Docs: DocC prepared statements examples + PostgresCodable schema hints; fix tuple decoding in test #594

zamderax · 2025-10-15T11:11:46Z

Adds practical DocC examples for PostgresPreparedStatement and demonstrates usage with .query and .withTransaction.
Added more PostgresCodable docs with minimal SQL schemas for each code snippet so readers know exactly what tables/columns are expected.
Fixes an integration test to use tuple decoding for multi‑column rows:
Sources/PostgresNIO/Docs.docc/prepared-statement.md: New end‑to‑end examples
- Define InsertUser and LoadUser prepared statements
- Mix prepared statements with regular .query calls
- Use inside withTransaction for atomic sequences
Added a new Sources/PostgresNIO/Docs.docc/postgres-codable.md: Add inline SQL schema hints for the examples
- Shows examples of User codable, Company (JSONB), location (POINT), and enum/raw‑value examples
Tests/IntegrationTests/PostgresCodableTests.swift: Decode multi‑column rows via tuple and then construct the model (avoids unsupported direct struct decoding)

- Added a new section on manual query construction using `PostgresBindings` in the README.md. - Introduced a new `PostgresCodable` documentation file detailing how to encode and decode custom Swift types. - Enhanced the `PostgresQuery` documentation with examples of string interpolation and dynamic query building. - Updated `.gitignore` to include `.derivedData`. - Added integration tests for JSONB encoding and decoding functionality in `PostgresClientTests.swift`.

- Updated `decode` methods in `PostgresRandomAccessRow` to be public for better accessibility. - Modified documentation examples to utilize `makeRandomAccess()` for decoding rows, ensuring consistency and clarity. - Added new examples demonstrating the use of Codable structs with JSONB in the documentation. - Introduced integration tests for JSONB encoding/decoding functionality, validating the round-trip of nested Codable structs.

…ansaction; tests: decode multi-column rows via tuple in PostgresCodable test

…es for clarity

gwynne

Several initial nits. I haven't bothered including notes on every single line where double-backticks were missing or - Note:-style callouts were used instead of > Note:, it'd take me a lot longer to do that in the PR interface than it'd take anyone to just fix it in Xcode or such.

gwynne · 2025-10-15T11:14:08Z

Sources/PostgresNIO/Data/PostgresRow.swift

    /// - Throws: The error of the decoding implementation. See also `PSQLDecodable` protocol for this.
    /// - Returns: The decoded value of Type T.
-    func decode<T: PostgresDecodable, JSONDecoder: PostgresJSONDecoder>(
+    public func decode<T: PostgresDecodable, JSONDecoder: PostgresJSONDecoder>(


gwynne · 2025-10-15T11:14:26Z

Sources/PostgresNIO/Data/PostgresRow.swift

    /// - Throws: The error of the decoding implementation. See also `PSQLDecodable` protocol for this.
    /// - Returns: The decoded value of Type T.
-    func decode<T: PostgresDecodable, JSONDecoder: PostgresJSONDecoder>(
+    public func decode<T: PostgresDecodable, JSONDecoder: PostgresJSONDecoder>(


gwynne · 2025-10-15T11:16:35Z

Sources/PostgresNIO/New/PostgresCodable.swift

+/// }
+/// ```
+///
+/// - Note: `PostgresNonThrowingEncodable` is a variant that doesn't throw, allowing usage without `try`.


Suggested change

/// - Note: `PostgresNonThrowingEncodable` is a variant that doesn't throw, allowing usage without `try`.

/// > Note: ``PostgresNonThrowingEncodable`` is a variant that doesn't throw, allowing usage without `try`.

gwynne · 2025-10-15T11:16:50Z

Sources/PostgresNIO/New/PostgresCodable.swift

 /// A type that can decode itself from a postgres wire binary representation.
 ///
-/// If you want to conform a type to PostgresDecodable you must implement the decode method.
+/// Conform your custom types to `PostgresDecodable` to enable them to be decoded from query results.


Suggested change

/// Conform your custom types to `PostgresDecodable` to enable them to be decoded from query results.

/// Conform your custom types to ``PostgresDecodable`` to enable them to be decoded from query results.

gwynne · 2025-10-15T11:16:57Z

Sources/PostgresNIO/New/PostgresCodable.swift

+///
+/// ## Conforming Built-in Types
+///
+/// Many standard Swift types already conform to `PostgresDecodable`:


Suggested change

/// Many standard Swift types already conform to `PostgresDecodable`:

/// Many standard Swift types already conform to ``PostgresDecodable``:

gwynne · 2025-10-15T11:17:14Z

Sources/PostgresNIO/New/PostgresCodable.swift

+/// // Returns nil if the database value is NULL
+/// ```
+///
+/// - Note: The `_DecodableType` associated type is an implementation detail for Optional handling.


Suggested change

/// - Note: The `_DecodableType` associated type is an implementation detail for Optional handling.

/// > Note: The `_DecodableType` associated type is an implementation detail for `Optional` handling.

gwynne · 2025-10-15T11:17:38Z

Sources/PostgresNIO/New/PostgresQuery.swift

+/// - Note: String interpolation is the recommended approach for simple queries as it automatically handles parameter counting and binding.
+/// - Warning: Always use parameter binding for user input. Never concatenate user input directly into SQL strings.


Suggested change

/// - Note: String interpolation is the recommended approach for simple queries as it automatically handles parameter counting and binding.

/// - Warning: Always use parameter binding for user input. Never concatenate user input directly into SQL strings.

/// > Note: String interpolation is the recommended approach for simple queries as it automatically handles parameter counting and binding.

///

/// > Warning: Always use parameter binding for user input. Never concatenate user input directly into SQL strings.

gwynne · 2025-10-15T11:17:52Z

Sources/PostgresNIO/New/PostgresQuery.swift

+/// - SeeAlso: `PostgresBindings` for more details on manual binding construction.
+/// - SeeAlso: `PostgresClient` for connection pool management and query execution.


Suggested change

/// - SeeAlso: `PostgresBindings` for more details on manual binding construction.

/// - SeeAlso: `PostgresClient` for connection pool management and query execution.

/// - SeeAlso: ``PostgresBindings`` for more details on manual binding construction.

/// - SeeAlso: ``PostgresClient`` for connection pool management and query execution.

gwynne · 2025-10-15T11:18:42Z

.gitignore

 Package.resolved
 .swiftpm
 Tests/LinuxMain.swift
+.derivedData


This was an accident as I was unable to use DocC to break a cache. I will remove it.

gwynne · 2025-10-15T11:20:26Z

Tests/IntegrationTests/Utilities.swift

+        var tlsConfiguration = TLSConfiguration.makeClientConfiguration()
+        tlsConfiguration.certificateVerification = .none
+        var clientConfig = PostgresClient.Configuration(
+            host: env("POSTGRES_HOSTNAME") ?? "localhost",
+            port: env("POSTGRES_PORT").flatMap({ Int($0) }) ?? 5432,
+            username: env("POSTGRES_USER") ?? "test_username",
+            password: env("POSTGRES_PASSWORD") ?? "test_password",
+            database: env("POSTGRES_DB") ?? "test_database",
+            tls: .prefer(tlsConfiguration)


Suggested change

var tlsConfiguration = TLSConfiguration.makeClientConfiguration()

tlsConfiguration.certificateVerification = .none

var clientConfig = PostgresClient.Configuration(

host: env("POSTGRES_HOSTNAME") ?? "localhost",

port: env("POSTGRES_PORT").flatMap({ Int($0) }) ?? 5432,

username: env("POSTGRES_USER") ?? "test_username",

password: env("POSTGRES_PASSWORD") ?? "test_password",

database: env("POSTGRES_DB") ?? "test_database",

tls: .prefer(tlsConfiguration)

var clientConfig = PostgresClient.Configuration(

host: env("POSTGRES_HOSTNAME") ?? "localhost",

port: env("POSTGRES_PORT").flatMap({ Int($0) }) ?? 5432,

username: env("POSTGRES_USER") ?? "test_username",

password: env("POSTGRES_PASSWORD") ?? "test_password",

database: env("POSTGRES_DB") ?? "test_database",

tls: .disable

Don't encourage people to disable certificate verification. Match the existing test configuration by disabling TLS.

zamderax · 2025-10-15T14:24:11Z

Great I made a bunch of commits to address these.

zamderax added 4 commits October 15, 2025 11:58

docs(prepared-statements): add DocC examples using .query and .withTr…

06f206f

…ansaction; tests: decode multi-column rows via tuple in PostgresCodable test

docs(PostgresCodable): add example schemas (SQL) alongside code sampl…

62f0ad4

…es for clarity

zamderax requested review from fabianfett and gwynne as code owners October 15, 2025 11:11

gwynne requested changes Oct 15, 2025

View reviewed changes

addressing backticks and accidental commits to gitignore

a10c711

	/// - Note: `PostgresNonThrowingEncodable` is a variant that doesn't throw, allowing usage without `try`.
	/// > Note: ``PostgresNonThrowingEncodable`` is a variant that doesn't throw, allowing usage without `try`.

	/// Conform your custom types to `PostgresDecodable` to enable them to be decoded from query results.
	/// Conform your custom types to ``PostgresDecodable`` to enable them to be decoded from query results.

	/// Many standard Swift types already conform to `PostgresDecodable`:
	/// Many standard Swift types already conform to ``PostgresDecodable``:

	/// - Note: The `_DecodableType` associated type is an implementation detail for Optional handling.
	/// > Note: The `_DecodableType` associated type is an implementation detail for `Optional` handling.

		/// - Note: String interpolation is the recommended approach for simple queries as it automatically handles parameter counting and binding.
		/// - Warning: Always use parameter binding for user input. Never concatenate user input directly into SQL strings.

		/// - SeeAlso: `PostgresBindings` for more details on manual binding construction.
		/// - SeeAlso: `PostgresClient` for connection pool management and query execution.

Uh oh!

Docs: DocC prepared statements examples + PostgresCodable schema hints; fix tuple decoding in test #594

Are you sure you want to change the base?

Docs: DocC prepared statements examples + PostgresCodable schema hints; fix tuple decoding in test #594

Uh oh!

Conversation

zamderax commented Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gwynne left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zamderax commented Oct 15, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

zamderax commented Oct 15, 2025 •

edited

Loading