Docs: DocC prepared statements examples + PostgresCodable schema hints; fix tuple decoding in test by zamderax · Pull Request #594 · vapor/postgres-nio

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)

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

    /// - 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

    /// - 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

+/// }
+/// ```
+///
+/// - 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

 /// 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

+///
+/// ## 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

+/// // 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

+/// - 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.

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

Great I made a bunch of commits to address these.

fabianfett · 2025-12-04T14:31:08Z

@@ -0,0 +1,442 @@
+# PostgresCodable


This is a pretty, pretty great doc!
In an ideal case we would put the swift sections into Snippets to ensure they continue to build.

- 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

- Replace row.makeRandomAccess() pattern with direct tuple decoding - Remove misleading "better performance" claim from withConnection docs - Add PostgresCodable conformance to UserProfile example

zamderax · 2025-12-26T18:59:25Z

Thanks Fabian, I made some adjustments based on your comments

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

gwynne requested changes Oct 15, 2025

View reviewed changes

fabianfett reviewed Dec 4, 2025

View reviewed changes

Comment thread Sources/PostgresNIO/Docs.docc/index.md Outdated

fabianfett reviewed Dec 4, 2025

View reviewed changes

Comment thread Sources/PostgresNIO/Docs.docc/index.md Outdated

fabianfett reviewed Dec 4, 2025

View reviewed changes

Comment thread Sources/PostgresNIO/Docs.docc/index.md Outdated

fabianfett reviewed Dec 4, 2025

View reviewed changes

zamderax added 6 commits December 26, 2025 13:58

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

b5a25c9

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

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

508b940

…es for clarity

addressing backticks and accidental commits to gitignore

934587e

Address Fabian's review comments

abc514b

- Replace row.makeRandomAccess() pattern with direct tuple decoding - Remove misleading "better performance" claim from withConnection docs - Add PostgresCodable conformance to UserProfile example

zamderax force-pushed the add-docc-examples branch from c1db220 to abc514b Compare December 26, 2025 18:58

	/// - 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.

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!

Uh oh!

Uh oh!

Uh oh!

zamderax commented Oct 15, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zamderax commented Dec 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

zamderax commented Oct 15, 2025 •

edited

Loading