Postgres Implementation

.editorconfig

@@ -11,6 +11,9 @@ indent_size = 4
 csharp_new_line_before_members_in_object_initializers = false
 csharp_preferred_modifier_order = public, private, protected, internal, file, new, static, abstract, virtual, sealed, readonly, override, extern, unsafe, volatile, async, required:suggestion
 csharp_style_var_for_built_in_types = true:suggestion
+csharp_wrap_parameters_style = chop_if_long
+csharp_wrap_arguments_style = chop_if_long
+csharp_keep_user_linebreaks = true
 dotnet_style_parentheses_in_arithmetic_binary_operators = never_if_unnecessary:none
 dotnet_style_parentheses_in_other_binary_operators = always_for_clarity:none
 dotnet_style_parentheses_in_relational_binary_operators = never_if_unnecessary:none
@@ -21,11 +24,15 @@ dotnet_style_qualification_for_field = false:suggestion
 dotnet_style_qualification_for_method = false:suggestion
 dotnet_style_qualification_for_property = false:suggestion
 dotnet_style_require_accessibility_modifiers = for_non_interface_members:suggestion
+csharp_arguments_named = named
+dotnet_code_quality.ca1051.exclude_structs = true
 
 # ReSharper properties
 resharper_csharp_insert_final_newline = true
 resharper_for_simple_types = use_var_when_evident
 resharper_trailing_comma_in_multiline_lists = true
+resharper_csharp_wrap_arguments_style = chop_if_long
+resharper_csharp_keep_existing_linebreaks = true
 
 [{*.yaml,*.yml}]
 indent_size = 2

.github/workflows/build.yml

@@ -33,13 +33,12 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-dotnet@v4
         with:
-          dotnet-version: '8.0.408'
+          dotnet-version: '10.0'
       - run: dotnet build
       - name: Run Tests
         run: |
           dotnet test
         env:
-          POSTGRES_PORT: ${{ env.POSTGRES_PORT }}
-          POSTGRES_USERNAME: ${{ env.POSTGRES_USERNAME }}
-          POSTGRES_PASSWORD: ${{ env.POSTGRES_PASSWORD }}
-          POSTGRES_DATABASE: ${{ env.POSTGRES_DATABASE }}
+          PG_USERNAME: ${{ env.POSTGRES_USERNAME }}
+          PG_PASSWORD: ${{ env.POSTGRES_PASSWORD }}
+          PG_DATABASE: ${{ env.POSTGRES_DATABASE }}

.gitignore

@@ -2,4 +2,5 @@ bin/
 obj/
 /packages/
 riderModule.iml
-/_ReSharper.Caches/
+/_ReSharper.Caches/
+run_actions

README.MD

@@ -1,2 +1,186 @@
 # SQLx C#
-.NET Library for database access that leverages new features in C# to improve upon the ADO.NET API. 
+## Overview
+.NET Library for database access that leverages new features in C# to improve upon the ADO.NET API.
+The aim of the library is to include other databases with open/available client protocol
+documentation.
+
+## Core
+### Basic Query
+```c#
+struct Row : IFromRow<DbRow, Row>
+{
+    public required int Id { get; init; }
+
+    public required string Name { get; init; }
+
+    public required int? ChildId { get; init; }
+
+    public static Row FromRow(DbRow dataRow)
+    {
+        return new Row
+        {
+            Id = dataRow.GetIntNotNull("id"),
+            Name = dataRow.GetStringNotNull("name"),
+            ChildId = dataRow.GetInt("child_id"),
+        };
+    }
+}
+
+// Full usage
+await using var connection = pool.CreateConnection();
+using var query = connection.CreateQuery(sql);
+var rows = await query.FetchAllAsync<Row>();
+
+// With no query
+// Creates query, executes query to fetch all and disposes of the query
+await using var connection = pool.CreateConnection();
+var rows = await connection.FetchAllAsync<Row>(sql);
+
+// With no connection
+// Create connection, create query, executes query to fetch all and disposes of connection and query
+var rows = await pool.FetchAllAsync<Row>(sql);
+```
+
+### Parameterized Query
+```c#
+struct Param : IBindMany<DbBindable>
+{
+    public required int Id { get; init; }
+
+    public void BindMany(DbBindable bindable)
+    {
+        bindable.Bind(Id);
+    }
+}
+
+// Full usage with manual binding
+await using var connection = pool.CreateConnection();
+using var query = connection.CreateQuery(parameterizedQuery);
+// Binds to first parameter present in query
+query.Bind(1); 
+var rows = await query.FetchAllAsync<Row>();
+
+// With no query and param type
+await using var connection = pool.CreateConnection();
+var rows = await connection.FetchAllAsync<Param, Row>(sql, new Param { Id = 1 });
+
+// With no connection or query and param type
+var rows = await pool.FetchAllAsync<Param, Row>(sql, new Param { Id = 1 });
+```
+
+### Batch Queries
+```c#
+// With query batch, manually binding parameters
+await using var connection = pool.CreateConnection();
+using var queryBatch = connection.CreateQueryBatch();
+
+Param[] paramBatches;
+foreach (Param param in paramBatches)
+{
+    var query = queryBatch.CreateQuery(insertSql);
+    param.BindMany(query);
+}
+
+var rowsAffected = await queryBatch.ExecuteNonQueryAsync();
+
+// With extension method
+await using var connection = pool.CreateConnection();
+Param[] paramBatches;
+var rowsAffected = await connection.ExecuteNonQueryBatchAsync(insertSql, paramBatches);
+```
+
+### FromRow
+`IFromRow` allows for defining how data row deserialization is facilitated to create a new instance
+of the type that implements this interface. For examples of its usage, see the code blocks above.
+The interface can be implemented manually or source generated. The source generated option is
+implemented for each database and might provide different options. Example of a database
+implementation:
+```c#
+[Sqlx.Postgres.Generated.FromRow]
+partial struct Row
+{
+    public required int Id { get; init; }
+
+    public required string Name { get; init; }
+
+    public required int? ChildId { get; init; }
+}
+```
+
+## Philosophy
+### Implement General Use Cases as Extension Methods
+When interfacing with databases, a few use cases/patterns show up WAY more than others. Rather
+than ask others to handle that duplication themselves through extension members or god forbid
+copy and paste code, extension members are made available on the library level. For example, in a
+lot of cases we execute a parameterized query with 1 result set and map those rows to a type. Other
+libraries require the ceremony of:
+1. Creating a command
+2. Binding parameters
+3. Executing a reader
+4. Iterating over that reader
+5. Mapping each row as a new type
+
+This is fine and there are libraries on top of the drivers that make this much easier, but we would
+rather have that behaviour provided for you to make the interaction with the DB streamlined. As long
+as the row type has `IFromRow` implemented for itself against your database, you can simply call,
+`await connection.FetchAll<RowType(sql)`. There is also a case for handling parameterized queries
+where you implement `IBindAll` for your database on a parameter type so that you call
+`await connection.FetchAll<ParamType, RowType>(sql, param)`. This has the downside of obfuscating
+the actual row parsing and parameter binding to implementations but it at least makes it explicit.
+
+### Result Mapping
+Although sqlx-cs can be used to deal with dynamic result sets and row shapes, it thrives when row
+types are known and clearly defined as CLR types. Each database provides a source generator for
+creating implementations of `IFromRow` for that database and the type itself. Developers should lean
+on that functionality rather than trying to deal with rows as opaque tuples.
+
+### Embracing new C# features
+The original intention of the library was to make an ADO.NET with modern features of the language.
+Although some features such as:
+- Using `IAsyncEnumerable` for result sets
+- Using `PipeReader` on the connection stream
+
+were dropped due to performance concerns, the library tries to set itself up for future additions
+to the language such as:
+- Extension interfaces
+- Sealed enums
+- Union types
+
+### Opinionated Design
+You might notice that there are some core module interfaces for connections, queries or data rows.
+You might have also noticed that they have complex generics types associated with them.
+
+THIS IS BY DESIGN.
+
+This means that you will have a hard time interacting with the library as though every connection,
+query or data row is essentially the same thing even though they are linked to separate databases.
+It's this library's opinion that generic repositories are not the best solution and should only be
+chosen with care and concern for the downsides. You might notice similar takes on other options or
+functionality in this library where certain patterns are discouraged but not impossible. This is not
+to say that someone cannot make that decision, it's just that the author(s) of this library do not
+want to encourage to make certain decisions. If you would like fewer restrictions like this, ADO.NET
+would be an easier option.
+
+## Database Support
+### [Postgres](sqlx-cs-pg/Postgres.md)
+
+### Connection Encryption
+SSL connections are not implemented.... yet!
+
+### FAQs
+#### Is there support for non-async/blocking connections?
+No. Database interactions generally involve some sort of IO so it would be best to put that into an
+async operation. However, if there is enough desire to use this library for blocking connections
+than it could be a future addition.
+
+#### Why does everything involve extension methods?
+As mentioned [here](#implement-general-use-cases-as-extension-methods), extension methods are the
+best way to add behaviour and compose multiple concepts/types into a single general use case.
+
+There are also cases where extension methods may seem a little overkill such as row field
+deserialization. Honestly, I agree that it's a little convoluted, but it's the only way to add the
+ability to deserialize certain types without making a general `IDataRow.Get<T>`. These types of
+generic methods without bounds are rife for developers to add values that can never be deserialized,
+and you won't know until you run your application. With that in mind, we hope to remove those
+methods when this [feature](https://github.com/dotnet/csharplang/issues/9319) is finally implemented
+in C#.

benchmarks/Benchmarks.md

@@ -0,0 +1,89 @@
+# Benchmarks
+## Queries
+### Overview
+Benchmarks are run using BenchmarkDotNet and run the same SQL query and deserialization. Init SQL:
+```postgresql
+DROP TABLE IF EXISTS public.posts;
+CREATE TABLE public.posts (
+    id int primary key generated always as identity, 
+    text_field text not null, 
+    creation_date timestamp not null,
+    last_change_date timestamp not null,
+    counter int
+);
+
+INSERT INTO public.posts(text_field, creation_date, last_change_date)
+SELECT REPEAT('x', 2000), current_timestamp, current_timestamp
+FROM generate_series(1, 5000) s
+```
+Queries executed during benchmarks:
+```postgresql
+-- Single row
+SELECT id, text_field, creation_date, last_change_date, counter
+FROM public.posts
+WHERE id = $1;
+
+-- Multi row
+SELECT id, text_field, creation_date, last_change_date, counter
+FROM public.posts
+WHERE id BETWEEN $1 AND $2;
+
+-- All rows
+SELECT id, text_field, creation_date, last_change_date, counter
+FROM public.posts;
+```
+
+### Results
+Results seen below are from a single run so the stats can vary due to IO. However, the general trend
+is minimal difference between the 2 drivers.
+
+| Method     | Categories                                     | Mean        | Error       | StdDev      | Median      | Ratio | RatioSD | Gen0       | Gen1       | Gen2      | Allocated    | Alloc Ratio |
+|------------|------------------------------------------------|-------------|-------------|-------------|-------------|-------|---------|------------|------------|-----------|--------------|-------------|
+| Npgsql     | Batched Queries                                | 337.9 us    | 13.53 us    | 38.83 us    | 330.0 us    | 1.01  | 0.16    | -          | -          | -         | 53.48 KB     | 1.00        |
+| sqlx-cs-pg | Batched Queries                                | 254.8 us    | 9.54 us     | 27.05 us    | 251.8 us    | 0.76  | 0.12    | -          | -          | -         | 51.4 KB      | 0.96        |
+|            |                                                |             |             |             |             |       |         |            |            |           |              |             |
+| Npgsql     | Simple Query, All Rows                         | 13,671.0 us | 780.23 us   | 2,263.58 us | 13,259.5 us | 1.03  | 0.24    | 1000.0000  | -          | -         | 20309.25 KB  | 1.00        |
+| sqlx-cs-pg | Simple Query, All Rows                         | 12,771.2 us | 1,148.92 us | 3,183.64 us | 11,856.5 us | 0.96  | 0.29    | 1000.0000  | -          | -         | 20528.64 KB  | 1.01        |
+|            |                                                |             |             |             |             |       |         |            |            |           |              |             |
+| Npgsql     | Simple Query, Concurrent Connections, All Rows | 70,377.9 us | 1,406.02 us | 3,679.30 us | 70,570.3 us | 1.00  | 0.07    | 14000.0000 | 13000.0000 | 2000.0000 | 202920.96 KB | 1.00        |
+| sqlx-cs-pg | Simple Query, Concurrent Connections, All Rows | 69,889.5 us | 1,389.41 us | 3,660.27 us | 69,462.0 us | 1.00  | 0.07    | 13000.0000 | 12000.0000 | 1000.0000 | 205268.41 KB | 1.01        |
+|            |                                                |             |             |             |             |       |         |            |            |           |              |             |
+| Npgsql     | Simple Query, Multi Row                        | 327.4 us    | 10.10 us    | 29.30 us    | 326.2 us    | 1.01  | 0.13    | -          | -          | -         | 48.48 KB     | 1.00        |
+| sqlx-cs-pg | Simple Query, Multi Row                        | 229.2 us    | 7.59 us     | 21.65 us    | 231.0 us    | 0.71  | 0.09    | -          | -          | -         | 47.18 KB     | 0.97        |
+|            |                                                |             |             |             |             |       |         |            |            |           |              |             |
+| Npgsql     | Simple Query, Single Row                       | 239.2 us    | 6.59 us     | 18.37 us    | 235.6 us    | 1.01  | 0.11    | -          | -          | -         | 7.38 KB      | 1.00        |
+| sqlx-cs-pg | Simple Query, Single Row                       | 155.6 us    | 3.93 us     | 11.35 us    | 154.2 us    | 0.65  | 0.07    | -          | -          | -         | 6.43 KB      | 0.87        |
+## PostgreSQL COPY
+### Overview
+Benchmarks are run using BenchmarkDotNet and run the same SQL query and copy data. Init SQL:
+```postgresql
+DROP TABLE IF EXISTS public.copy_target;
+CREATE TABLE public.copy_target(
+    id int primary key,
+    text_field text not null,
+    creation_date timestamp not null,
+    last_change_date timestamp not null,
+    counter int
+);
+```
+Queries executed during benchmarks:
+```postgresql
+COPY public.copy_target FROM STDIN WITH (FORMAT CSV);
+
+COPY public.copy_target FROM STDIN WITH (FORMAT binary);
+```
+
+### Results
+| Method     | Categories      | Mean     | Error    | StdDev   | Median   | Ratio | RatioSD | Gen0      | Allocated   | Alloc Ratio |
+|------------|-----------------|----------|----------|----------|----------|-------|---------|-----------|-------------|-------------|
+| Npgsql     | CopyIn, Binary  | 66.76 ms | 1.500 ms | 4.350 ms | 65.93 ms | 1.00  | 0.09    | -         | 1566.61 KB  | 1.00        |
+| sqlx-cs-pg | CopyIn, Binary  | 69.67 ms | 1.381 ms | 3.564 ms | 68.08 ms | 1.05  | 0.08    | -         | 1572.19 KB  | 1.00        |
+|            |                 |          |          |          |          |       |         |           |             |             |
+| Npgsql     | CopyIn, CSV     | 86.91 ms | 1.734 ms | 4.350 ms | 87.04 ms | 1.00  | 0.07    | -         | 4.76 KB     | 1.00        |
+| sqlx-cs-pg | CopyIn, CSV     | 87.62 ms | 1.748 ms | 4.544 ms | 87.39 ms | 1.01  | 0.07    | -         | 3.81 KB     | 0.80        |
+|            |                 |          |          |          |          |       |         |           |             |             |
+| Npgsql     | CopyOut, Binary | 15.44 ms | 2.086 ms | 6.118 ms | 12.44 ms | 1.14  | 0.60    | 1000.0000 | 20300.69 KB | 1.00        |
+| sqlx-cs-pg | CopyOut, Binary | 14.61 ms | 1.432 ms | 4.154 ms | 13.24 ms | 1.08  | 0.47    | 1000.0000 | 20530.5 KB  | 1.01        |
+|            |                 |          |          |          |          |       |         |           |             |             |
+| Npgsql     | CopyOut, CSV    | 17.81 ms | 0.679 ms | 1.948 ms | 17.22 ms | 1.01  | 0.15    | -         | 526.79 KB   | 1.00        |
+| sqlx-cs-pg | CopyOut, CSV    | 18.65 ms | 0.827 ms | 2.425 ms | 17.77 ms | 1.06  | 0.17    | -         | 117.51 KB   | 0.22        |

benchmarks/IdPairParam.cs

@@ -0,0 +1,17 @@
+using Sqlx.Core.Query;
+using Sqlx.Postgres.Query;
+
+namespace benchmarks;
+
+public readonly struct IdPairParam : IBindMany<IPgBindable>
+{
+    public required int Id1 { get; init; }
+
+    public required int Id2 { get; init; }
+
+    public void BindMany(IPgBindable bindable)
+    {
+        bindable.Bind(Id1);
+        bindable.Bind(Id2);
+    }
+}

benchmarks/IdParam.cs

@@ -0,0 +1,14 @@
+using Sqlx.Core.Query;
+using Sqlx.Postgres.Query;
+
+namespace benchmarks;
+
+public readonly struct IdParam : IBindMany<IPgBindable>
+{
+    public required int Id { get; init; }
+
+    public void BindMany(IPgBindable bindable)
+    {
+        bindable.Bind(Id);
+    }
+}