diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a82940e6..eb463b4a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -77,20 +77,26 @@ jobs:
tests/CSharpDB.Admin.Reports.Tests/CSharpDB.Admin.Reports.Tests.csproj
tests/CSharpDB.Admin.Forms.Tests/CSharpDB.Admin.Forms.Tests.csproj
tests/CSharpDB.Api.Tests/CSharpDB.Api.Tests.csproj
+ tests/CSharpDB.Benchmarks.Tests/CSharpDB.Benchmarks.Tests.csproj
tests/CSharpDB.Cli.Tests/CSharpDB.Cli.Tests.csproj
tests/CSharpDB.CodeModules.Tests/CSharpDB.CodeModules.Tests.csproj
tests/CSharpDB.Daemon.Tests/CSharpDB.Daemon.Tests.csproj
tests/CSharpDB.Data.Tests/CSharpDB.Data.Tests.csproj
tests/CSharpDB.DataGeneration.Tests/CSharpDB.DataGeneration.Tests.csproj
+ tests/CSharpDB.DataPrivacy.Tests/CSharpDB.DataPrivacy.Tests.csproj
tests/CSharpDB.DevOps.Tests/CSharpDB.DevOps.Tests.csproj
tests/CSharpDB.EntityFrameworkCore.Tests/CSharpDB.EntityFrameworkCore.Tests.csproj
tests/CSharpDB.EntityFrameworkCore.Tools.Tests/CSharpDB.EntityFrameworkCore.Tools.Tests.csproj
+ tests/CSharpDB.Mcp.Tests/CSharpDB.Mcp.Tests.csproj
tests/CSharpDB.Migration.Access.Tests/CSharpDB.Migration.Access.Tests.csproj
tests/CSharpDB.Migration.Compatibility.Tests/CSharpDB.Migration.Compatibility.Tests.csproj
tests/CSharpDB.Migration.DualRun.Tests/CSharpDB.Migration.DualRun.Tests.csproj
tests/CSharpDB.Migration.Files.Tests/CSharpDB.Migration.Files.Tests.csproj
+ tests/CSharpDB.Migration.LiteDb.Tests/CSharpDB.Migration.LiteDb.Tests.csproj
tests/CSharpDB.Migration.MySql.Tests/CSharpDB.Migration.MySql.Tests.csproj
+ tests/CSharpDB.Migration.Retained.Tests/CSharpDB.Migration.Retained.Tests.csproj
tests/CSharpDB.Migration.SqlServer.Tests/CSharpDB.Migration.SqlServer.Tests.csproj
+ tests/CSharpDB.Migration.Sqlite.Tests/CSharpDB.Migration.Sqlite.Tests.csproj
tests/CSharpDB.Migration.Tests/CSharpDB.Migration.Tests.csproj
tests/CSharpDB.Observability.Tests/CSharpDB.Observability.Tests.csproj
tests/CSharpDB.Pipelines.Tests/CSharpDB.Pipelines.Tests.csproj
@@ -251,7 +257,29 @@ jobs:
run: sudo apt-get update && sudo apt-get install -y clang zlib1g-dev
- name: Publish NativeAOT library
- run: dotnet publish src/CSharpDB.Native/CSharpDB.Native.csproj -c Release -r ${{ matrix.rid }}
+ run: dotnet publish src/CSharpDB.Native/CSharpDB.Native.csproj -c Release -r ${{ matrix.rid }} -p:ILLinkTreatWarningsAsErrors=true -p:IlcTreatWarningsAsErrors=true
+
+ - name: Use private link-free temporary directory for native archive smoke (macOS)
+ if: runner.os == 'macOS'
+ shell: bash
+ run: |
+ temp_directory="$(mktemp -d /private/tmp/csharpdb-native-archive.XXXXXX)"
+ chmod 700 "${temp_directory}"
+ echo "TMPDIR=${temp_directory}" >> "${GITHUB_ENV}"
+
+ - name: Publish native archive SQL smoke
+ run: dotnet publish tests/CSharpDB.Native.ArchiveSmoke/CSharpDB.Native.ArchiveSmoke.csproj -c Release -r ${{ matrix.rid }} --self-contained true -p:PublishAot=true -o artifacts/native-archive-smoke/${{ matrix.rid }}
+
+ - name: Run published native archive SQL smoke
+ shell: pwsh
+ run: |
+ $executableName = if ($IsWindows) { 'CSharpDB.Native.ArchiveSmoke.exe' } else { 'CSharpDB.Native.ArchiveSmoke' }
+ $executable = Join-Path 'artifacts/native-archive-smoke/${{ matrix.rid }}' $executableName
+ $library = [IO.Path]::GetFullPath('src/CSharpDB.Native/bin/Release/net10.0/${{ matrix.rid }}/publish/${{ matrix.lib }}')
+ if (-not (Test-Path -LiteralPath $executable -PathType Leaf)) { throw "Archive smoke executable missing: $executable" }
+ if (-not (Test-Path -LiteralPath $library -PathType Leaf)) { throw "Native library missing: $library" }
+ & $executable $library
+ if ($LASTEXITCODE -ne 0) { throw "Native archive SQL smoke failed with exit code $LASTEXITCODE." }
- name: Publish observability trim and NativeAOT smoke
run: dotnet publish tests/CSharpDB.Observability.TrimSmoke/CSharpDB.Observability.TrimSmoke.csproj -c Release -r ${{ matrix.rid }} --self-contained true -p:PublishAot=true -o artifacts/observability-aot/${{ matrix.rid }}
diff --git a/CSharpDB.slnx b/CSharpDB.slnx
index 3c9cac40..93edaf2c 100644
--- a/CSharpDB.slnx
+++ b/CSharpDB.slnx
@@ -86,6 +86,7 @@
+
@@ -115,6 +116,7 @@
+
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index fc196c18..ebfe1942 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -1,47 +1,45 @@
# What's New
-## CSharpDB 4.6.6
-
-CSharpDB 4.6.6 improves durable write throughput, prepared queries, and bounded
-primary-key reads while strengthening reader snapshot, buffered-row, and concurrent
-WAL-read correctness.
-These notes cover changes since v4.6.5.
-
-### Query and write improvements
-
-- Reuse prepared SELECT plans across parameter values and support bounded integer
- primary-key ranges through pooled readers and ordinary queries.
-- Preserve reader catalog snapshots across commits and checkpoints, including
- schema metadata used by existing readers.
-- Preserve committed row-count metadata during writes and restore it after
- publication, avoiding unnecessary full-table scans for reader `COUNT(*)` queries.
-- Reduce table-scan, LIMIT, snapshot-pager, and leaf-prefetch allocations. Forward
- intact row batches while preserving ownership and mixed row/batch traversal.
-- Streamline primary-key mutations and INSERT execution by reusing column ordinals,
- avoiding per-row observer allocations, and skipping redundant canonical value
- conversions.
-- Reduce durable-write checkpoint stalls and improve WAL/checkpoint lifecycle
- handling and storage-page ownership.
-
-### Storage correctness
-
-- Prevent checkpoint reset or retained-tail compaction from invalidating WAL
- offsets used during write-conflict resolution. This fixes a concurrency race
- that could cause short WAL reads or return incorrect page contents.
-- Defer checkpoint finalization while durable commits still have unpublished WAL
- offsets, preserving correct reads after those commits complete.
-- Add deterministic regression coverage for reset and compaction, including stale
- offsets that remain within file bounds, cancellation, lock release, and forward
- progress. The database and WAL formats are unchanged.
-
-### Dependencies and maintenance
-
-- Update gRPC/Protobuf, SQL Server migration dependencies, WebView2, OpenTelemetry,
- Scalar, and test tooling.
-- Retain Microsoft.OpenApi 2.12.0 for compatibility with
- Microsoft.AspNetCore.OpenApi 10.0.12 on .NET 10.
-
-### Performance guardrails
-
-- Validate performance evidence integrity and reject incomplete or inconsistent
- comparison evidence.
+## CSharpDB 4.7.0
+
+CSharpDB 4.7.0 establishes shared SDK and ADO.NET gRPC connection/session handling
+and fixes archive-backed SQL in the compiled native library.
+These notes cover changes since v4.6.6.
+
+### Remote client foundation
+
+- Share physical gRPC clients between SDK rentals and pooled ADO.NET connections
+ with matching options. Bound pool capacity, honor cancellation while waiting,
+ and isolate endpoints, credentials, routes, and caller-owned HTTP clients.
+- Add explicit native HTTP/2 gRPC selection and experimental persistent command
+ sessions for SQL and transactions. Existing Auto/unary defaults remain in
+ place; streaming requires an explicit opt-in.
+- Preserve transaction ownership, private temporary-table state, result schemas,
+ and logical column types across rentals and sessions. Drain active operations
+ before returning a client, reject stale rentals, and clean up unfinished
+ transactions without automatically replaying commands after disconnect.
+- Prevent a queued transaction begin from blocking a schema owner's commit or
+ rollback. Cancel and drain pending begins during client disposal, and clean up
+ transactions that cannot be registered after cancellation or shutdown.
+- Preserve the selected gRPC call mode when Admin clones routed client options.
+
+### Archive and dependency fixes
+
+- Fix external archive table registration in the NativeAOT library by generating
+ schema and manifest JSON metadata. Keep existing archive JSON bytes, enum
+ validation, legacy omitted-field defaults, and explicit-null rejection.
+- Add a published NativeAOT archive SQL smoke covering scans, primary-key lookup,
+ declared types, and close/reopen persistence through the C API. Fail native
+ publication on trimming or AOT warnings.
+- Support private migration reject artifacts on Linux tmpfs, including RAM-backed
+ temporary directories, while retaining owner, permission, link and ACL checks.
+- Update the optional SQL Server migration adapter's PKCS dependency to 9.0.22
+ and keep its exact bundle inventories and third-party notice aligned.
+- Include all 27 solution test modules in the ordinary pull-request CI matrix.
+
+### Scope and support
+
+Persistent streaming remains experimental and opt-in. This release does not
+include the custom TCP prototype or remote prepared-statement handles, and no
+verified network performance improvement is claimed. The native archive smoke
+checks the C API; it does not establish remote gRPC support under NativeAOT.
diff --git a/docs/releases/changelog-publication.json b/docs/releases/changelog-publication.json
index cd16a70a..413501c2 100644
--- a/docs/releases/changelog-publication.json
+++ b/docs/releases/changelog-publication.json
@@ -3,8 +3,8 @@
"verifiedOn": "2026-10-12",
"source": "https://api.github.com/repos/MaxAkbar/CSharpDB/releases",
"notesReview": {
- "version": "4.6.6",
- "sha256": "0c44953b85d05e17495662f40795fd2704124b9c5fbeba0d0e9fb960218c3628"
+ "version": "4.7.0",
+ "sha256": "d7e25f8ffa9e33627e37c50bcd3b4df48ff040ed41b68519b8d57343da196ea1"
},
"releases": [
{
diff --git a/scripts/Publish-CSharpDbSqlServerMigrationBundle.ps1 b/scripts/Publish-CSharpDbSqlServerMigrationBundle.ps1
index 7fb41457..4187d6b6 100644
--- a/scripts/Publish-CSharpDbSqlServerMigrationBundle.ps1
+++ b/scripts/Publish-CSharpDbSqlServerMigrationBundle.ps1
@@ -161,7 +161,7 @@ function Assert-ReviewedWorkerPackageClosure {
'System.Configuration.ConfigurationManager/9.0.18'
'System.Diagnostics.EventLog/9.0.18'
'System.IdentityModel.Tokens.Jwt/8.16.0'
- 'System.Security.Cryptography.Pkcs/9.0.18'
+ 'System.Security.Cryptography.Pkcs/9.0.22'
'System.Security.Cryptography.ProtectedData/9.0.18'
'System.Threading.RateLimiting/9.0.18'
) | Sort-Object
diff --git a/scripts/Test-SqlServerMigrationIsolation.ps1 b/scripts/Test-SqlServerMigrationIsolation.ps1
index 188a53e1..d9421f9e 100644
--- a/scripts/Test-SqlServerMigrationIsolation.ps1
+++ b/scripts/Test-SqlServerMigrationIsolation.ps1
@@ -370,7 +370,7 @@ function Assert-ReviewedWorkerPackageClosure {
'System.Configuration.ConfigurationManager/9.0.18'
'System.Diagnostics.EventLog/9.0.18'
'System.IdentityModel.Tokens.Jwt/8.16.0'
- 'System.Security.Cryptography.Pkcs/9.0.18'
+ 'System.Security.Cryptography.Pkcs/9.0.22'
'System.Security.Cryptography.ProtectedData/9.0.18'
'System.Threading.RateLimiting/9.0.18'
) | Sort-Object
diff --git a/src/CSharpDB.Admin/Services/DatabaseClientHolder.cs b/src/CSharpDB.Admin/Services/DatabaseClientHolder.cs
index ca621028..779e6322 100644
--- a/src/CSharpDB.Admin/Services/DatabaseClientHolder.cs
+++ b/src/CSharpDB.Admin/Services/DatabaseClientHolder.cs
@@ -663,6 +663,8 @@ private static CSharpDbClientOptions CloneOptions(
ConnectionString = options.ConnectionString,
DataSource = options.DataSource,
HttpClient = options.HttpClient,
+ GrpcMode = options.GrpcMode,
+ GrpcCallMode = options.GrpcCallMode,
ApiKey = options.ApiKey,
ApiKeyHeaderName = options.ApiKeyHeaderName,
RouteContext = routeContext,
diff --git a/src/CSharpDB.Client/CSharpDB.Client.csproj b/src/CSharpDB.Client/CSharpDB.Client.csproj
index 711808e0..d3653299 100644
--- a/src/CSharpDB.Client/CSharpDB.Client.csproj
+++ b/src/CSharpDB.Client/CSharpDB.Client.csproj
@@ -5,7 +5,7 @@
enable
enable
CSharpDB.Client
- Unified CSharpDB client SDK with pluggable transports (Direct, HTTP, gRPC, TCP, Named Pipes).
+ Unified CSharpDB client SDK with Direct, HTTP and gRPC transports.
@@ -20,6 +20,9 @@
+
+
+
diff --git a/src/CSharpDB.Client/CSharpDbClient.cs b/src/CSharpDB.Client/CSharpDbClient.cs
index 70e79d19..803f4358 100644
--- a/src/CSharpDB.Client/CSharpDbClient.cs
+++ b/src/CSharpDB.Client/CSharpDbClient.cs
@@ -16,7 +16,8 @@ public sealed class CSharpDbClient :
ICSharpDbTableArchiveProgressExporter,
ICSharpDbTransactionalSnapshotReader,
ICSharpDbExclusiveSessionProvider,
- ICSharpDbTransactionalSchemaIdentityWriter
+ ICSharpDbTransactionalSchemaIdentityWriter,
+ IScalarProjectionClient
{
private readonly ICSharpDbClient _inner;
@@ -31,6 +32,24 @@ public static ICSharpDbClient Create(CSharpDbClientOptions options)
return new CSharpDbClient(ClientTransportResolver.Create(options));
}
+ /// Rents a validated gRPC connection. Dispose the client to return it to the shared pool.
+ public static async ValueTask RentAsync(
+ CSharpDbClientOptions options, int maxPoolSize = 32, CancellationToken ct = default)
+ {
+ ArgumentNullException.ThrowIfNull(options);
+ return new CSharpDbClient(await GrpcClientPoolRegistry.RentAsync(options, maxPoolSize, ct).ConfigureAwait(false));
+ }
+
+ /// Retires all gRPC pools for an endpoint. Active rentals are disposed on return.
+ public static ValueTask ClearPoolAsync(string endpoint)
+ {
+ ArgumentException.ThrowIfNullOrWhiteSpace(endpoint);
+ return GrpcClientPoolRegistry.ClearAsync(endpoint.Trim());
+ }
+
+ /// Retires all shared gRPC pools.
+ public static ValueTask ClearAllPoolsAsync() => GrpcClientPoolRegistry.ClearAsync();
+
public static ICSharpDbShardAdminClient CreateShardAdmin(CSharpDbClientOptions options)
{
ArgumentNullException.ThrowIfNull(options);
@@ -58,6 +77,13 @@ public static ICSharpDbShardDirectoryClient CreateShardDirectoryClient(CSharpDbC
}
public string DataSource => _inner.DataSource;
+ bool IScalarProjectionClient.SupportsScalarProjection
+ => _inner is IScalarProjectionClient { SupportsScalarProjection: true };
+ ValueTask IScalarProjectionClient.ExecuteScalarProjectionAsync(
+ string sql, string? transactionId, CancellationToken cancellationToken)
+ => _inner is IScalarProjectionClient { SupportsScalarProjection: true } scalar
+ ? scalar.ExecuteScalarProjectionAsync(sql, transactionId, cancellationToken)
+ : throw new NotSupportedException("This connection does not support scalar projection.");
public Task ReadDefinitionCatalogAsync(string? continuationToken = null, int pageSize = 64, CancellationToken ct = default)
=> _inner is ICSharpDbDefinitionCatalogReader reader
? reader.ReadDefinitionCatalogAsync(continuationToken, pageSize, ct)
diff --git a/src/CSharpDB.Client/CSharpDbClientOptions.cs b/src/CSharpDB.Client/CSharpDbClientOptions.cs
index ec2f26bb..a1c7760f 100644
--- a/src/CSharpDB.Client/CSharpDbClientOptions.cs
+++ b/src/CSharpDB.Client/CSharpDbClientOptions.cs
@@ -9,6 +9,8 @@ public sealed class CSharpDbClientOptions
public string? ConnectionString { get; init; }
public string? DataSource { get; init; }
public HttpClient? HttpClient { get; init; }
+ public CSharpDbGrpcMode GrpcMode { get; init; } = CSharpDbGrpcMode.Auto;
+ public CSharpDbGrpcCallMode GrpcCallMode { get; init; } = CSharpDbGrpcCallMode.Unary;
public string? ApiKey { get; init; }
public string ApiKeyHeaderName { get; init; } = "X-CSharpDB-Api-Key";
public CSharpDbRouteContext? RouteContext { get; init; }
diff --git a/src/CSharpDB.Client/CSharpDbGrpcCallMode.cs b/src/CSharpDB.Client/CSharpDbGrpcCallMode.cs
new file mode 100644
index 00000000..5df64e07
--- /dev/null
+++ b/src/CSharpDB.Client/CSharpDbGrpcCallMode.cs
@@ -0,0 +1,10 @@
+namespace CSharpDB.Client;
+
+/// Selects how SQL and transaction commands travel over native gRPC.
+public enum CSharpDbGrpcCallMode
+{
+ Unary = 0,
+
+ /// Experimental persistent command stream; requires GrpcMode.Native.
+ Streaming = 1,
+}
diff --git a/src/CSharpDB.Client/CSharpDbGrpcMode.cs b/src/CSharpDB.Client/CSharpDbGrpcMode.cs
new file mode 100644
index 00000000..64658161
--- /dev/null
+++ b/src/CSharpDB.Client/CSharpDbGrpcMode.cs
@@ -0,0 +1,17 @@
+namespace CSharpDB.Client;
+
+/// Controls the HTTP protocol used by the gRPC transport.
+public enum CSharpDbGrpcMode
+{
+ ///
+ /// Preserves compatibility: plain HTTP uses gRPC-Web over HTTP/1.1 unless
+ /// a custom HttpClient is supplied; HTTPS uses native gRPC.
+ ///
+ Auto = 0,
+
+ ///
+ /// Uses native gRPC and requires HTTP/2, including on a plain HTTP endpoint.
+ /// An unencrypted server endpoint must be configured for HTTP/2 only.
+ ///
+ Native = 1,
+}
diff --git a/src/CSharpDB.Client/Grpc/GrpcModelMapper.cs b/src/CSharpDB.Client/Grpc/GrpcModelMapper.cs
index 8ac9ebad..c22cec03 100644
--- a/src/CSharpDB.Client/Grpc/GrpcModelMapper.cs
+++ b/src/CSharpDB.Client/Grpc/GrpcModelMapper.cs
@@ -571,26 +571,76 @@ public static ViewBrowseResult ToModel(ViewBrowseResultMessage value)
};
public static SqlExecutionResultMessage ToMessage(SqlExecutionResult value)
+ => ToMessage(value, includeMetadata: true, allowCompactScalarInt64: false);
+
+ public static SqlExecutionResultMessage ToMessage(SqlExecutionResult value, bool includeMetadata)
+ => ToMessage(value, includeMetadata, allowCompactScalarInt64: false);
+
+ public static SqlExecutionResultMessage ToMessage(SqlExecutionResult value, bool includeMetadata, bool allowCompactScalarInt64)
{
+ long scalar = 0;
+ bool compact = allowCompactScalarInt64 && TryGetSingleInt64Result(value, out scalar);
var message = new SqlExecutionResultMessage
{
IsQuery = value.IsQuery,
- ColumnNames = value.ColumnNames is null ? null : ToStringList(value.ColumnNames),
- ColumnTypes = value.ColumnTypes is null ? null : ToStringList(value.ColumnTypes),
- ColumnNullability = value.ColumnNullability is null
+ ColumnNames = !includeMetadata || value.ColumnNames is null ? null : ToStringList(value.ColumnNames),
+ ColumnTypes = !includeMetadata || value.ColumnTypes is null ? null : ToStringList(value.ColumnTypes),
+ ColumnNullability = !includeMetadata || value.ColumnNullability is null
? null
: ToBoolList(value.ColumnNullability),
- Rows = value.Rows is null ? null : ToVariantArrayList(value.Rows),
+ Rows = compact || value.Rows is null ? null : ToVariantArrayList(value.Rows),
RowsAffected = value.RowsAffected,
Error = value.Error,
Elapsed = Duration.FromTimeSpan(value.Elapsed),
};
- if (value.Columns is not null)
+ if (includeMetadata && value.Columns is not null)
message.Columns.Add(value.Columns.Select(ToMessage));
+ if (compact) message.ScalarInt64 = scalar;
return message;
}
public static SqlExecutionResult ToModel(SqlExecutionResultMessage value)
+ {
+ if (value.HasScalarInt64)
+ throw new CSharpDbClientException("A compact SQL scalar requires a negotiated command session.");
+ return ToSqlExecutionResultModel(value);
+ }
+
+ internal static SqlExecutionResult ToSessionModel(SqlExecutionResultMessage value)
+ => ToSessionModel(value, metadata: null);
+
+ internal static SqlExecutionResult ToSessionModel(SqlExecutionResultMessage value, GrpcSessionResultMetadata? metadata)
+ {
+ if (value.HasScalarInt64 && (!value.IsQuery || value.Error is not null || value.Rows is not null
+ || !(metadata?.HasSingleColumnMetadata ?? HasSingleColumnMetadata(value))))
+ throw new CSharpDbClientException("The command session returned an invalid compact SQL scalar.");
+ return metadata is null ? ToSqlExecutionResultModel(value) : ToSqlExecutionResultModel(value, metadata);
+ }
+
+ internal static bool HasSingleColumnMetadata(SqlExecutionResultMessage value)
+ => (value.ColumnNames?.Values.Count == 1 || value.Columns.Count == 1)
+ && (value.ColumnNames is null || value.ColumnNames.Values.Count == 1)
+ && (value.ColumnTypes is null || value.ColumnTypes.Values.Count == 1)
+ && (value.ColumnNullability is null || value.ColumnNullability.Values.Count == 1)
+ && value.Columns.Count <= 1;
+
+ private static bool TryGetSingleInt64Result(SqlExecutionResult value, out long scalar)
+ {
+ scalar = 0;
+ if (!value.IsQuery || value.Error is not null || value.Rows is not { Count: 1 }
+ || value.Rows[0] is not { Length: 1 } row || row[0] is not long number)
+ return false;
+ if (!(value.ColumnNames is { Length: 1 } || value.Columns is { Length: 1 })
+ || (value.ColumnNames is not null && value.ColumnNames.Length != 1)
+ || (value.ColumnTypes is not null && value.ColumnTypes.Length != 1)
+ || (value.ColumnNullability is not null && value.ColumnNullability.Length != 1)
+ || (value.Columns is not null && value.Columns.Length != 1))
+ return false;
+ scalar = number;
+ return true;
+ }
+
+ private static SqlExecutionResult ToSqlExecutionResultModel(SqlExecutionResultMessage value)
=> new()
{
IsQuery = value.IsQuery,
@@ -600,7 +650,25 @@ public static SqlExecutionResult ToModel(SqlExecutionResultMessage value)
Columns = value.Columns.Count == 0
? null
: value.Columns.Select(ToModel).ToArray(),
- Rows = value.Rows is null ? null : ToRows(value.Rows),
+ Rows = value.HasScalarInt64
+ ? new List(1) { new object?[] { value.ScalarInt64 } }
+ : value.Rows is null ? null : ToRows(value.Rows),
+ RowsAffected = value.RowsAffected,
+ Error = value.Error,
+ Elapsed = value.Elapsed.ToTimeSpan(),
+ };
+
+ private static SqlExecutionResult ToSqlExecutionResultModel(SqlExecutionResultMessage value, GrpcSessionResultMetadata metadata)
+ => new()
+ {
+ IsQuery = value.IsQuery,
+ ColumnNames = metadata.CreateColumnNames(),
+ ColumnTypes = metadata.CreateColumnTypes(),
+ ColumnNullability = metadata.CreateColumnNullability(),
+ Columns = metadata.CreateColumns(),
+ Rows = value.HasScalarInt64
+ ? new List(1) { new object?[] { value.ScalarInt64 } }
+ : value.Rows is null ? null : ToRows(value.Rows),
RowsAffected = value.RowsAffected,
Error = value.Error,
Elapsed = value.Elapsed.ToTimeSpan(),
diff --git a/src/CSharpDB.Client/Grpc/GrpcSessionResultMetadata.cs b/src/CSharpDB.Client/Grpc/GrpcSessionResultMetadata.cs
new file mode 100644
index 00000000..7a2f72f1
--- /dev/null
+++ b/src/CSharpDB.Client/Grpc/GrpcSessionResultMetadata.cs
@@ -0,0 +1,85 @@
+using CSharpDB.Client.Models;
+using CSharpDB.Client.Internal;
+
+namespace CSharpDB.Client.Grpc;
+
+/// Private canonical mapped metadata for one validated session schema.
+internal sealed class GrpcSessionResultMetadata
+{
+ private readonly string[]? _names;
+ private readonly string[]? _types;
+ private readonly bool[]? _nullability;
+ private readonly ColumnDefinition[]? _columns;
+ private readonly bool _hasScalarProjectionMetadata;
+ private readonly ScalarTypeSnapshot? _scalarType;
+
+ internal bool HasSingleColumnMetadata { get; }
+
+ internal GrpcSessionResultMetadata(SqlExecutionResultMessage definition)
+ {
+ HasSingleColumnMetadata = GrpcModelMapper.HasSingleColumnMetadata(definition);
+ _names = definition.ColumnNames?.Values.ToArray();
+ _types = definition.ColumnTypes?.Values.ToArray();
+ _nullability = definition.ColumnNullability?.Values.ToArray();
+ if (definition.Columns.Count != 0)
+ {
+ _columns = new ColumnDefinition[definition.Columns.Count];
+ for (int i = 0; i < _columns.Length; i++)
+ _columns[i] = GrpcModelMapper.ToModel(definition.Columns[i]);
+ }
+
+ _hasScalarProjectionMetadata = HasSingleColumnMetadata
+ && _names is { Length: 1 } && _columns is { Length: 1 };
+ if (_hasScalarProjectionMetadata && _columns![0].DeclaredType is { } type)
+ {
+ _scalarType = new ScalarTypeSnapshot(
+ type.Kind, type.Length, type.Precision, type.Scale, type.FractionalSecondsPrecision);
+ }
+ }
+
+ internal bool TryGetScalarType(out ScalarTypeSnapshot? declaredType)
+ {
+ declaredType = _scalarType;
+ return _hasScalarProjectionMetadata;
+ }
+
+ internal string[]? CreateColumnNames()
+ => _names is null ? null : (string[])_names.Clone();
+
+ internal string[]? CreateColumnTypes()
+ => _types is null ? null : (string[])_types.Clone();
+
+ internal bool[]? CreateColumnNullability()
+ => _nullability is null ? null : (bool[])_nullability.Clone();
+
+ internal ColumnDefinition[]? CreateColumns()
+ {
+ if (_columns is null) return null;
+ var columns = new ColumnDefinition[_columns.Length];
+ for (int i = 0; i < columns.Length; i++)
+ {
+ ColumnDefinition canonical = _columns[i];
+ columns[i] = new ColumnDefinition
+ {
+ SchemaId = canonical.SchemaId,
+ Name = canonical.Name,
+ Type = canonical.Type,
+ DeclaredType = canonical.DeclaredType is { } type ? new SqlTypeDescriptor
+ {
+ Kind = type.Kind,
+ Length = type.Length,
+ Precision = type.Precision,
+ Scale = type.Scale,
+ FractionalSecondsPrecision = type.FractionalSecondsPrecision,
+ } : null,
+ Nullable = canonical.Nullable,
+ IsPrimaryKey = canonical.IsPrimaryKey,
+ IsIdentity = canonical.IsIdentity,
+ IsRowVersion = canonical.IsRowVersion,
+ Collation = canonical.Collation,
+ DefaultSql = canonical.DefaultSql,
+ };
+ }
+ return columns;
+ }
+}
diff --git a/src/CSharpDB.Client/Internal/ClientTransportResolver.cs b/src/CSharpDB.Client/Internal/ClientTransportResolver.cs
index 0e04a034..93f1a488 100644
--- a/src/CSharpDB.Client/Internal/ClientTransportResolver.cs
+++ b/src/CSharpDB.Client/Internal/ClientTransportResolver.cs
@@ -27,7 +27,9 @@ public static ICSharpDbClient Create(CSharpDbClientOptions options)
options.HttpClient,
options.ApiKey,
options.ApiKeyHeaderName,
- options.RouteContext),
+ options.RouteContext,
+ options.GrpcMode,
+ options.GrpcCallMode),
CSharpDbTransport.NamedPipes => throw CreateNotImplementedTransportException(CSharpDbTransport.NamedPipes),
_ => throw new CSharpDbClientConfigurationException($"Unsupported transport '{resolution.Transport}'."),
};
@@ -41,6 +43,15 @@ private static Resolution Resolve(CSharpDbClientOptions options)
endpointUri = parsedEndpointUri;
var transport = options.Transport ?? InferTransport(endpoint, endpointUri);
+ if (!Enum.IsDefined(options.GrpcMode))
+ throw new CSharpDbClientConfigurationException($"Unsupported gRPC mode '{options.GrpcMode}'.");
+ if (!Enum.IsDefined(options.GrpcCallMode))
+ throw new CSharpDbClientConfigurationException($"Unsupported gRPC call mode '{options.GrpcCallMode}'.");
+ if (options.GrpcCallMode == CSharpDbGrpcCallMode.Streaming &&
+ (transport != CSharpDbTransport.Grpc || options.GrpcMode != CSharpDbGrpcMode.Native))
+ throw new CSharpDbClientConfigurationException("Streaming gRPC requires the Grpc transport and GrpcMode.Native.");
+ if (options.GrpcMode != CSharpDbGrpcMode.Auto && transport != CSharpDbTransport.Grpc)
+ throw new CSharpDbClientConfigurationException("GrpcMode is only supported for the Grpc transport.");
return transport switch
{
CSharpDbTransport.Direct => ResolveDirect(options, ResolveDirectEndpointPath(endpoint, endpointUri)),
@@ -51,6 +62,14 @@ private static Resolution Resolve(CSharpDbClientOptions options)
};
}
+ internal static Uri ResolvePooledGrpcEndpoint(CSharpDbClientOptions options)
+ {
+ var resolution = Resolve(options);
+ if (resolution.Transport != CSharpDbTransport.Grpc)
+ throw new CSharpDbClientConfigurationException("Client pooling requires the Grpc transport.");
+ return resolution.EndpointUri!;
+ }
+
private static Resolution ResolveDirect(CSharpDbClientOptions options, string? endpointPath)
{
DirectTarget? endpointTarget = endpointPath is null
diff --git a/src/CSharpDB.Client/Internal/EngineTransportClient.DiagnosticsCapability.cs b/src/CSharpDB.Client/Internal/EngineTransportClient.DiagnosticsCapability.cs
index a910f557..4ec42f55 100644
--- a/src/CSharpDB.Client/Internal/EngineTransportClient.DiagnosticsCapability.cs
+++ b/src/CSharpDB.Client/Internal/EngineTransportClient.DiagnosticsCapability.cs
@@ -1883,7 +1883,7 @@ private int TryGetCachedDatabaseActiveReaderCount()
try
{
- return databaseTask.GetAwaiter().GetResult().ActiveReaderCount;
+ return databaseTask.GetAwaiter().GetResult().ActiveQueryReaderCount;
}
catch
{
diff --git a/src/CSharpDB.Client/Internal/EngineTransportClient.ExclusiveSession.cs b/src/CSharpDB.Client/Internal/EngineTransportClient.ExclusiveSession.cs
index 7dd2b7da..3e92aa9c 100644
--- a/src/CSharpDB.Client/Internal/EngineTransportClient.ExclusiveSession.cs
+++ b/src/CSharpDB.Client/Internal/EngineTransportClient.ExclusiveSession.cs
@@ -18,7 +18,8 @@ public async ValueTask OpenExclusiveSessionAsync(Cance
EngineTransportClient? session = null;
try
{
- if (_activeFinalizations != 0) throw new InvalidOperationException("Wait for transaction completion before starting an exclusive operation.");
+ if (_activeFinalizations != 0 || _pendingTransactionBegins != 0)
+ throw new InvalidOperationException("Wait for transaction admission/completion before starting an exclusive operation.");
var source = _directDatabaseOptions;
var storage = source.StorageEngineOptions;
var options = new DatabaseOptions
diff --git a/src/CSharpDB.Client/Internal/EngineTransportClient.cs b/src/CSharpDB.Client/Internal/EngineTransportClient.cs
index 2146b6a0..212b56ad 100644
--- a/src/CSharpDB.Client/Internal/EngineTransportClient.cs
+++ b/src/CSharpDB.Client/Internal/EngineTransportClient.cs
@@ -70,6 +70,9 @@ private HashSet?
private readonly object _databaseGate = new();
private readonly object _disposeGate = new();
private readonly ConcurrentDictionary _transactions = new(StringComparer.Ordinal);
+ private readonly CancellationTokenSource _transactionAdmissionsShutdown = new();
+ private int _pendingTransactionBegins;
+ private TaskCompletionSource? _transactionBeginsDrained;
private int _activeFinalizations;
private TaskCompletionSource? _finalizationsDrained;
private Task? _databaseTask;
@@ -78,7 +81,6 @@ private HashSet?
private Task? _disposeTask;
private bool _disposeStarted;
private int _exclusiveMaintenanceActive;
- private long _databaseOwnershipEpoch;
private bool _catalogsInitialized;
private List? _clientLockBoundaryStates;
@@ -664,85 +666,87 @@ public async Task BeginTransactionAsync(CancellationToke
{
using ClientLockLease clientLock = await AcquireClientLockAsync(ct);
ThrowIfDisposing();
- long reuseEpoch = CaptureDatabaseOwnershipEpoch();
- Database? database = null;
- if (_hybridDatabaseOptions is null)
+ // Initialize client metadata before taking a writer snapshot. Otherwise
+ // the first ordinary command could wait for schema access held by the
+ // session whose caller is waiting for that command to finish.
+ await EnsureCatalogsInitializedAsync(ct);
+ Database database = await GetDatabaseAsync(ct);
+ if (SnapshotSessionRequiresExclusiveAccess && database.ActiveReaderCount > 0)
+ throw new CSharpDbClientException(
+ "Snapshot hybrid transactions require exclusive access. Close active snapshot readers first.");
+
+ using var admission = CancellationTokenSource.CreateLinkedTokenSource(
+ ct, _transactionAdmissionsShutdown.Token);
+ RegisterPendingTransactionBegin();
+ // Schema admission can depend on another session committing. Pin the
+ // cached owner, but let completion/disposal acquire the client lock.
+ clientLock.ReleaseLock();
+ WriteTransaction? transaction = null;
+ ClientTransactionSession? session = null;
+ bool registered = false;
+ try
{
- database = await DetachCachedDatabaseCoreAsync(
- ct,
- "Cannot start a client-managed transaction while direct snapshot readers are active.");
- if (database is not null)
+ transaction = await database.BeginWriteTransactionAsync(admission.Token);
+ session = new ClientTransactionSession(
+ database,
+ transaction,
+ _observabilityEnabled
+ ? database.RuntimeDiagnosticsState?.TimeProvider ??
+ _observabilityTimeProvider
+ : null,
+ database.RuntimeDiagnosticsState?.SessionAbandonmentThreshold ??
+ _directDatabaseOptions.ObservabilityOptions?.SessionAbandonmentThreshold ??
+ TimeSpan.FromMinutes(30));
+
+ using ClientLockLease registrationLock = await AcquireClientLockAsync(admission.Token);
+ ThrowIfDisposing();
+ ct.ThrowIfCancellationRequested();
+ string transactionId = Guid.NewGuid().ToString("N", CultureInfo.InvariantCulture);
+ if (!_transactions.TryAdd(transactionId, session))
+ throw new CSharpDbClientException("Failed to register the transaction session.");
+ try
{
- try
- {
- await database.ResetReusableSessionStateAsync();
- }
- catch
- {
- await database.DisposeAsync();
- throw;
- }
+ RetainRuntimeDiagnosticsState(session);
}
- }
- else
- {
- // Hybrid persistence may be configured to run only on Dispose.
- // Preserve that physical-close boundary rather than retaining
- // the handle across logical transaction sessions.
- await ReleaseCachedDatabaseCoreAsync(
- ct,
- "Cannot start a client-managed transaction while direct snapshot readers are active.");
- }
+ catch
+ {
+ _transactions.TryRemove(transactionId, out _);
+ throw;
+ }
+ registered = true;
- database ??= await OpenOwnedDatabaseAsync(_databasePath, ct);
- try
+ return new TransactionSessionInfo
+ {
+ TransactionId = transactionId,
+ ExpiresAtUtc = DateTime.MaxValue,
+ };
+ }
+ catch (OperationCanceledException exception) when (ct.IsCancellationRequested)
{
- await database.BeginTransactionAsync(ct);
+ throw new OperationCanceledException(exception.Message, exception, ct);
}
- catch
+ catch (OperationCanceledException) when (_transactionAdmissionsShutdown.IsCancellationRequested)
{
- await database.DisposeAsync();
- throw;
+ throw new ObjectDisposedException(nameof(EngineTransportClient));
}
-
- string transactionId = Guid.NewGuid().ToString("N", CultureInfo.InvariantCulture);
- var session = new ClientTransactionSession(
- database,
- reuseEpoch,
- _observabilityEnabled
- ? database.RuntimeDiagnosticsState?.TimeProvider ??
- _observabilityTimeProvider
- : null,
- database.RuntimeDiagnosticsState?.SessionAbandonmentThreshold ??
- _directDatabaseOptions.ObservabilityOptions?.SessionAbandonmentThreshold ??
- TimeSpan.FromMinutes(30));
- if (!_transactions.TryAdd(transactionId, session))
+ finally
{
try
{
- await database.RollbackAsync(CancellationToken.None);
+ if (!registered)
+ {
+ if (session is not null)
+ await DisposeTransactionSessionAsync(session);
+ else if (transaction is not null)
+ await transaction.DisposeAsync();
+ }
}
finally
{
- await database.DisposeAsync();
+ using ClientLockLease admissionLock = await AcquireClientLockAsync(CancellationToken.None);
+ UnregisterPendingTransactionBegin();
}
-
- throw new CSharpDbClientException("Failed to register the transaction session.");
- }
-
- RetainRuntimeDiagnosticsState(session);
-
- if (_transactions.Count > 1)
- {
- foreach (ClientTransactionSession activeSession in _transactions.Values)
- activeSession.DisableReuse();
}
-
- return new TransactionSessionInfo
- {
- TransactionId = transactionId,
- ExpiresAtUtc = DateTime.MaxValue,
- };
}
public async Task ExecuteInTransactionAsync(string transactionId, string sql, CancellationToken ct = default)
@@ -786,7 +790,8 @@ public async Task ExecuteInTransactionAsync(string transacti
using IDisposable? queueDurationScope = operation?.EnterQueueDurationScope();
queryDispatched = true;
- return await ExecuteQueryAsync(session.Database, sql, ct);
+ await using var result = await session.Transaction.ExecuteAsync(sql, ct);
+ return await MaterializeQueryResultAsync(result, ct);
}
catch (Exception exception)
{
@@ -828,11 +833,11 @@ public async Task ExecuteInTransactionAsync(string transacti
try
{
- CoreTableSchema? schema = session.Database.GetTableSchema(normalizedTableName);
+ CoreTableSchema? schema = session.Transaction.GetTableSchema(normalizedTableName);
if (schema is null)
return null;
- IndexSchema[] indexes = session.Database.GetIndexes()
+ IndexSchema[] indexes = session.Transaction.GetIndexes()
.Where(index =>
index.Kind is not (
CSharpDB.Primitives.IndexKind.ForeignKeyInternal or
@@ -845,10 +850,10 @@ CSharpDB.Primitives.IndexKind.ForeignKeyInternal or
return new TransactionTableSnapshot
{
HasUpdateHostCallbacks = _directDatabaseOptions.StorageEngineOptions.PagerOptions.Interceptors.Count != 0
- || session.Database.HasUpdateHostCallbacks(normalizedTableName),
+ || session.Transaction.HasUpdateHostCallbacks(normalizedTableName),
Schema = MapTableSchema(schema),
Indexes = indexes,
- Triggers = session.Database.GetTriggers()
+ Triggers = session.Transaction.GetTriggers()
.Where(trigger => string.Equals(trigger.TableName, normalizedTableName, StringComparison.OrdinalIgnoreCase))
.Select(MapTriggerSchema).ToArray(),
};
@@ -880,7 +885,7 @@ public async ValueTask ApplyTableSchemaIdentitiesAsync(
try
{
- await session.Database.ApplyTableSchemaIdentitiesAsync(
+ await session.Transaction.ApplyTableSchemaIdentitiesAsync(
normalizedTableName,
MapCoreTableSchema(identitySource),
ct);
@@ -999,7 +1004,7 @@ await session.Database.ApplyTableSchemaIdentitiesAsync(
using IDisposable? queueDurationScope = operation?.EnterQueueDurationScope();
queryDispatched = true;
- result = await session.Database.ExecuteAsync(sql, ct);
+ result = await session.Transaction.ExecuteAsync(sql, ct);
if (!result.IsQuery)
return null;
@@ -1235,6 +1240,7 @@ private async Task DisposeCoreAsync()
ClientLockLease lifecycleBoundaryLock =
await AcquireClientLockAsync(CancellationToken.None);
List sessionsToDispose;
+ Task? transactionBeginsDrained;
Task? finalizationsDrained;
Task? maintenanceLifetimesDrained;
try
@@ -1253,6 +1259,7 @@ private async Task DisposeCoreAsync()
sessionsToDispose.Add(session);
}
+ transactionBeginsDrained = _transactionBeginsDrained?.Task;
finalizationsDrained = GetFinalizationsDrainedTask();
maintenanceLifetimesDrained =
GetMaintenanceLifetimesDrainedTask();
@@ -1267,29 +1274,44 @@ private async Task DisposeCoreAsync()
{
try
{
- await Task.WhenAll(sessionsToDispose.Select(DisposeClaimedSessionAsync));
+ try
+ {
+ // Cancellation callbacks may reenter the client, so never
+ // invoke them while holding the lifecycle lock.
+ _transactionAdmissionsShutdown.Cancel();
+ }
+ finally
+ {
+ await Task.WhenAll(sessionsToDispose.Select(DisposeClaimedSessionAsync));
+ }
}
finally
{
+ if (transactionBeginsDrained is not null)
+ await transactionBeginsDrained;
if (finalizationsDrained is not null)
await finalizationsDrained;
- if (maintenanceLifetimesDrained is not null)
- await maintenanceLifetimesDrained;
- }
-
- using (ClientLockLease finalLock =
- await AcquireClientLockAsync(CancellationToken.None))
- {
- if (_databaseTask is not null)
+ try
{
- try
- {
- var db = await _databaseTask;
- await db.DisposeAsync();
- }
- catch
+ if (maintenanceLifetimesDrained is not null)
+ await maintenanceLifetimesDrained;
+ }
+ finally
+ {
+ using ClientLockLease finalLock =
+ await AcquireClientLockAsync(CancellationToken.None);
+ if (_databaseTask is not null)
{
- // ignore lazy-init failures during dispose
+ try
+ {
+ Database database = await _databaseTask;
+ await database.DisposeAsync();
+ }
+ catch
+ {
+ // Preserve best-effort cached-owner disposal. Errors
+ // finishing logical transaction sessions propagate above.
+ }
}
}
}
@@ -1318,6 +1340,7 @@ await AcquireClientLockAsync(CancellationToken.None))
s_disposeFlushToken.Value = previousToken;
DisposeClientMaintenanceDiagnostics();
DisposeRuntimeDiagnosticsStates();
+ _transactionAdmissionsShutdown.Dispose();
_lock.Dispose();
}
}
@@ -1606,8 +1629,22 @@ internal void CompleteOpen()
}
}
+ private bool SnapshotSessionRequiresExclusiveAccess =>
+ _hybridDatabaseOptions?.PersistenceMode == HybridPersistenceMode.Snapshot &&
+ (_hybridDatabaseOptions.PersistenceTriggers &
+ (HybridPersistenceTriggers.Commit | HybridPersistenceTriggers.Dispose)) != 0;
+
private async Task GetDatabaseAsync(CancellationToken ct)
{
+ // Full-image hybrid persistence requires exclusive access at session
+ // completion. Incremental-durable hybrid and file owners allow overlap.
+ if (SnapshotSessionRequiresExclusiveAccess &&
+ (!_transactions.IsEmpty || Volatile.Read(ref _activeFinalizations) != 0 ||
+ Volatile.Read(ref _pendingTransactionBegins) != 0))
+ {
+ throw new CSharpDB.Primitives.CSharpDbException(CSharpDB.Primitives.ErrorCode.Busy,
+ "Finish the active snapshot hybrid transaction before using the ordinary session or starting another transaction.");
+ }
using IDisposable? operationalBoundary =
EnterDirectOperationalTransportScope();
@@ -1637,7 +1674,6 @@ private async Task GetDatabaseAsync(CancellationToken ct)
var openCompletion = new TaskCompletionSource(
TaskCreationOptions.RunContinuationsAsynchronously);
createdOpenTask = openCompletion.Task;
- _databaseOwnershipEpoch++;
_databaseTask = createdOpenTask;
if (openBoundary is not null)
{
@@ -1785,10 +1821,10 @@ private async Task AcquireExclusiveDatabaseAccessA
try
{
ThrowIfDisposing();
- if (activeTransactionMessage is not null && !_transactions.IsEmpty)
+ if (!_transactions.IsEmpty || _activeFinalizations != 0 || _pendingTransactionBegins != 0)
{
throw new ExclusiveDatabaseAccessRejectedException(
- activeTransactionMessage);
+ activeTransactionMessage ?? "Finish active transactions before starting an exclusive operation.");
}
maintenanceOperation?.SetPhase(
@@ -1923,7 +1959,6 @@ private async ValueTask ReopenAndCacheExclusiveDatabaseAsync(
"Exclusive database access ended before the restored database could be cached.");
}
- _databaseOwnershipEpoch++;
_catalogsInitialized = false;
_databaseTask = Task.FromResult(database);
database = null;
@@ -2128,18 +2163,18 @@ private sealed class ClientTransactionSession
private long _lastActiveTimestamp;
private int _activeGateOperations;
private int _activeDiagnosticsReaders;
- private int _reuseDisabled;
private int _runtimeDiagnosticsStateOwnershipReleased;
private int _state;
public ClientTransactionSession(
Database database,
- long reuseEpoch,
+ WriteTransaction transaction,
TimeProvider? diagnosticsTimeProvider,
TimeSpan diagnosticsAbandonmentThreshold)
{
Database = database;
- ReuseEpoch = reuseEpoch;
+ Transaction = transaction;
+ transaction.SetTemporaryTableSession(this);
_diagnosticsTimeProvider = diagnosticsTimeProvider;
_diagnosticsAbandonmentThreshold = diagnosticsAbandonmentThreshold;
if (diagnosticsTimeProvider is not null)
@@ -2156,14 +2191,11 @@ public ClientTransactionSession(
}
public Database Database { get; }
- public long ReuseEpoch { get; }
- public bool ReuseAllowed => Volatile.Read(ref _reuseDisabled) == 0;
+ public WriteTransaction Transaction { get; }
public bool CanPublishDiagnostics => _diagnosticsTimeProvider is not null;
public bool HasActiveDiagnosticsReader =>
Volatile.Read(ref _activeDiagnosticsReaders) > 0;
- public void DisableReuse() => Volatile.Write(ref _reuseDisabled, 1);
-
public async ValueTask TryEnterOperationAsync(CancellationToken ct)
{
if (Volatile.Read(ref _state) != 0)
@@ -2383,8 +2415,17 @@ public TimeSpan GetDiagnosticsAge()
public bool TryClaimFinalization()
=> Interlocked.CompareExchange(ref _state, 1, 0) == 0;
- public ValueTask WaitForOperationsAsync(CancellationToken ct)
- => new(_operationGate.WaitAsync(ct));
+ public async ValueTask WaitForOperationsAsync(CancellationToken ct)
+ {
+ await _operationGate.WaitAsync(ct);
+ // Cancellation can race a successful semaphore handoff. Return
+ // the gate before reporting cancellation to finalization recovery.
+ if (ct.IsCancellationRequested)
+ {
+ _operationGate.Release();
+ ct.ThrowIfCancellationRequested();
+ }
+ }
public void CancelFinalizationClaim()
=> Volatile.Write(ref _state, 0);
@@ -2859,6 +2900,11 @@ private async Task ExecuteQueryAsync(
{
using IDisposable? transportScope = EnterDirectTransportScope();
await using var result = await db.ExecuteAsync(sql, observabilitySql ?? sql, ct);
+ return await MaterializeQueryResultAsync(result, ct);
+ }
+
+ private static async Task MaterializeQueryResultAsync(CSharpDB.Execution.QueryResult result, CancellationToken ct)
+ {
var rows = await result.ToListAsync(ct);
return new SqlExecutionResult
{
@@ -3417,6 +3463,21 @@ private void ThrowIfDisposing()
throw new ObjectDisposedException(nameof(EngineTransportClient));
}
+ private void RegisterPendingTransactionBegin()
+ {
+ if (_pendingTransactionBegins++ == 0)
+ _transactionBeginsDrained = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
+ }
+
+ private void UnregisterPendingTransactionBegin()
+ {
+ if (--_pendingTransactionBegins == 0)
+ {
+ _transactionBeginsDrained!.TrySetResult();
+ _transactionBeginsDrained = null;
+ }
+ }
+
private void RegisterFinalization()
{
if (_activeFinalizations++ == 0)
@@ -3440,7 +3501,7 @@ private async Task DisposeClaimedSessionAsync(ClientTransactionSession session)
try
{
await session.WaitForOperationsAsync(CancellationToken.None);
- await session.Database.DisposeAsync();
+ await DisposeTransactionSessionAsync(session);
}
finally
{
@@ -3452,6 +3513,20 @@ private async Task DisposeClaimedSessionAsync(ClientTransactionSession session)
}
}
+ private static async ValueTask DisposeTransactionSessionAsync(ClientTransactionSession session)
+ {
+ try
+ {
+ await session.Transaction.DisposeAsync();
+ }
+ finally
+ {
+ using (session.Database.EnterTemporaryTableSessionScope(session))
+ await session.Database.ClearTemporaryTablesAsync();
+ await session.Database.PersistClientSessionBoundaryAsync();
+ }
+ }
+
private async Task CompleteTransactionAsync(
string transactionId,
bool commit,
@@ -3459,9 +3534,7 @@ private async Task CompleteTransactionAsync(
{
ClientLockLease lifecycleBoundaryLock = await AcquireClientLockAsync(ct);
ClientTransactionSession? session = null;
- bool adopted = false;
bool operationGateAcquired = false;
- bool sessionResetSucceeded = false;
try
{
ThrowIfDisposing();
@@ -3490,17 +3563,20 @@ private async Task CompleteTransactionAsync(
using (ClientLockLease recoveryLock =
await AcquireClientLockAsync(CancellationToken.None))
{
- session.CancelFinalizationClaim();
disposeClaimedSession = _disposeStarted;
if (!disposeClaimedSession)
+ {
+ session.CancelFinalizationClaim();
_transactions.TryAdd(transactionId, session);
+ }
}
if (disposeClaimedSession)
{
try
{
- await session.Database.DisposeAsync();
+ await session.WaitForOperationsAsync(CancellationToken.None);
+ await DisposeTransactionSessionAsync(session);
}
finally
{
@@ -3522,34 +3598,18 @@ await AcquireClientLockAsync(CancellationToken.None))
throw;
}
- Database database = session.Database;
-
if (commit)
- await database.CommitAsync(ct);
+ await session.Transaction.CommitAsync(ct);
else
- await database.RollbackAsync(ct);
-
- if (_hybridDatabaseOptions is null)
- {
- await database.ResetReusableSessionStateAsync();
- sessionResetSucceeded = true;
- }
+ await session.Transaction.RollbackAsync(ct);
}
finally
{
if (session is not null && operationGateAcquired)
{
- using (ClientLockLease adoptionLock =
- await AcquireClientLockAsync(CancellationToken.None))
- {
- if (!_disposeStarted && _hybridDatabaseOptions is null && sessionResetSucceeded)
- adopted = TryAdoptCachedDatabase(session);
- }
-
try
{
- if (!adopted)
- await session.Database.DisposeAsync();
+ await DisposeTransactionSessionAsync(session);
}
finally
{
@@ -3565,103 +3625,12 @@ await AcquireClientLockAsync(CancellationToken.None))
}
}
- private long CaptureDatabaseOwnershipEpoch()
- {
- lock (_databaseGate)
- return _databaseOwnershipEpoch;
- }
-
- private bool TryAdoptCachedDatabase(ClientTransactionSession session)
- {
- lock (_databaseGate)
- {
- if (!session.ReuseAllowed ||
- session.ReuseEpoch != _databaseOwnershipEpoch ||
- !ReferenceEquals(
- session.Database.RuntimeDiagnosticsState,
- CurrentRuntimeDiagnosticsState) ||
- !_transactions.IsEmpty ||
- _databaseTask is not null ||
- _databaseReleaseCompletion is { Task.IsCompleted: false })
- {
- return false;
- }
-
- _catalogsInitialized = false;
- _databaseReleaseCompletion = null;
- _databaseOwnershipEpoch++;
- _databaseTask = Task.FromResult(session.Database);
- return true;
- }
- }
-
- private async Task DetachCachedDatabaseCoreAsync(
- CancellationToken ct,
- string activeReaderMessage)
- {
- Task? openTask;
- TaskCompletionSource releaseCompletion;
- lock (_databaseGate)
- {
- openTask = _databaseTask;
- _catalogsInitialized = false;
- if (openTask is null)
- return null;
-
- _databaseTask = null;
- releaseCompletion = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
- _databaseReleaseCompletion = releaseCompletion;
- }
-
- try
- {
- Database database;
- try
- {
- database = await openTask.WaitAsync(ct);
- }
- catch (OperationCanceledException) when (ct.IsCancellationRequested)
- {
- lock (_databaseGate)
- {
- if (_databaseTask is null)
- _databaseTask = openTask;
- }
-
- throw;
- }
- catch
- {
- return null;
- }
-
- if (database.ActiveReaderCount > 0)
- {
- lock (_databaseGate)
- {
- if (_databaseTask is null)
- _databaseTask = openTask;
- }
-
- throw new CSharpDbClientException(activeReaderMessage);
- }
-
- return database;
- }
- finally
- {
- lock (_databaseGate)
- {
- if (ReferenceEquals(_databaseReleaseCompletion, releaseCompletion))
- _databaseReleaseCompletion = null;
- }
-
- releaseCompletion.TrySetResult();
- }
- }
-
private async Task ReleaseCachedDatabaseCoreAsync(CancellationToken ct, string activeReaderMessage)
{
+ if (!_transactions.IsEmpty || _activeFinalizations != 0 || _pendingTransactionBegins != 0)
+ throw new CSharpDbClientException(
+ "Cannot release the direct database handle while client-managed transactions are active or completing.");
+
Task? openTask;
TaskCompletionSource releaseCompletion;
lock (_databaseGate)
diff --git a/src/CSharpDB.Client/Internal/GrpcApiKeyClientInterceptor.cs b/src/CSharpDB.Client/Internal/GrpcApiKeyClientInterceptor.cs
index 5bb9de2c..08859c13 100644
--- a/src/CSharpDB.Client/Internal/GrpcApiKeyClientInterceptor.cs
+++ b/src/CSharpDB.Client/Internal/GrpcApiKeyClientInterceptor.cs
@@ -20,6 +20,17 @@ public override AsyncUnaryCall AsyncUnaryCall(
TRequest request,
ClientInterceptorContext context,
AsyncUnaryCallContinuation continuation)
+ {
+ return continuation(request, WithHeaders(context));
+ }
+
+ public override AsyncDuplexStreamingCall AsyncDuplexStreamingCall(
+ ClientInterceptorContext context,
+ AsyncDuplexStreamingCallContinuation continuation)
+ => continuation(WithHeaders(context));
+
+ private ClientInterceptorContext WithHeaders(
+ ClientInterceptorContext context) where TRequest : class where TResponse : class
{
var metadata = new Metadata();
if (context.Options.Headers is not null)
@@ -35,10 +46,10 @@ public override AsyncUnaryCall AsyncUnaryCall(
metadata.Add(_apiKeyHeaderName, _apiKey);
var options = context.Options.WithHeaders(metadata);
- return continuation(request, new ClientInterceptorContext(
+ return new ClientInterceptorContext(
context.Method,
context.Host,
- options));
+ options);
}
private static string NormalizeHeaderName(string? headerName)
diff --git a/src/CSharpDB.Client/Internal/GrpcClientLease.cs b/src/CSharpDB.Client/Internal/GrpcClientLease.cs
new file mode 100644
index 00000000..a58b2ee2
--- /dev/null
+++ b/src/CSharpDB.Client/Internal/GrpcClientLease.cs
@@ -0,0 +1,208 @@
+using CSharpDB.Client.Grpc;
+using Grpc.Core;
+using Grpc.Core.Interceptors;
+
+namespace CSharpDB.Client.Internal;
+
+/// Guards every RPC on one rental and resets its transaction state before returning the connection.
+internal sealed class GrpcClientLease(GrpcTransportClient owner, Func release) : Interceptor
+{
+ private readonly object _gate = new();
+ private HashSet? _transactions;
+ private HashSet? _rollbackAttempts;
+ private int _activeCalls;
+ private bool _healthy = true;
+ private TaskCompletionSource? _drained;
+ private Task? _disposeTask;
+
+ public override AsyncUnaryCall AsyncUnaryCall(
+ TRequest request, ClientInterceptorContext context,
+ AsyncUnaryCallContinuation continuation)
+ {
+ string? transactionId = request switch
+ {
+ TransactionSqlRequest sql => sql.TransactionId,
+ TransactionIdRequest transaction => transaction.TransactionId,
+ _ => null,
+ };
+ string method = context.Method.Name;
+ Begin(method, transactionId);
+ AsyncUnaryCall call;
+ try { call = continuation(request, context); }
+ catch { Complete(method, transactionId, null, failed: true); throw; }
+ return new AsyncUnaryCall(
+ ObserveAsync(call.ResponseAsync, method, transactionId),
+ static state => ((AsyncUnaryCall)state).ResponseHeadersAsync,
+ static state => ((AsyncUnaryCall)state).GetStatus(),
+ static state => ((AsyncUnaryCall)state).GetTrailers(),
+ static state => ((AsyncUnaryCall)state).Dispose(), call);
+ }
+
+ internal Task ExecuteAsync(
+ GrpcCommandSession session, CommandSessionRequest command, CancellationToken ct)
+ where TResponse : class
+ {
+ string method = command.CommandCase switch
+ {
+ CommandSessionRequest.CommandOneofCase.GetInfo => "GetInfo",
+ CommandSessionRequest.CommandOneofCase.ExecuteSql => "ExecuteSql",
+ CommandSessionRequest.CommandOneofCase.BeginTransaction => "BeginTransaction",
+ CommandSessionRequest.CommandOneofCase.ExecuteInTransaction => "ExecuteInTransaction",
+ CommandSessionRequest.CommandOneofCase.CommitTransaction => "CommitTransaction",
+ CommandSessionRequest.CommandOneofCase.RollbackTransaction => "RollbackTransaction",
+ _ => throw new ArgumentException("The command is not supported by a client rental.", nameof(command)),
+ };
+ string? transactionId = command.CommandCase switch
+ {
+ CommandSessionRequest.CommandOneofCase.ExecuteInTransaction => command.ExecuteInTransaction.TransactionId,
+ CommandSessionRequest.CommandOneofCase.CommitTransaction => command.CommitTransaction.TransactionId,
+ CommandSessionRequest.CommandOneofCase.RollbackTransaction => command.RollbackTransaction.TransactionId,
+ _ => null,
+ };
+ Begin(method, transactionId);
+ Task response;
+ try { response = session.ExecuteAsync(command, ct); }
+ catch { Complete(method, transactionId, null, failed: true); throw; }
+ return ObserveAsync(response, method, transactionId);
+ }
+
+ internal Task ExecuteSqlAsync(
+ GrpcCommandSession session, CommandSessionRequest command, CancellationToken ct)
+ {
+ string method = command.CommandCase switch
+ {
+ CommandSessionRequest.CommandOneofCase.ExecuteSql => "ExecuteSql",
+ CommandSessionRequest.CommandOneofCase.ExecuteInTransaction => "ExecuteInTransaction",
+ _ => throw new ArgumentException("The command must execute SQL.", nameof(command)),
+ };
+ string? transactionId = command.ExecuteInTransaction?.TransactionId;
+ Begin(method, transactionId);
+ Task response;
+ try { response = session.ExecuteSqlAsync(command, ct); }
+ catch { Complete(method, transactionId, null, failed: true); throw; }
+ return ObserveSqlAsync(response, method, transactionId);
+ }
+
+ private async Task ObserveSqlAsync(
+ Task response, string method, string? transactionId)
+ {
+ try
+ {
+ GrpcCommandSession.SqlReply result = await response.ConfigureAwait(false);
+ // SQL cannot change transaction ownership. Do not box the reply struct
+ // merely to run the common completion/drain accounting.
+ Complete(method, transactionId, null, failed: false);
+ return result;
+ }
+ catch { Complete(method, transactionId, null, failed: true); throw; }
+ }
+
+ private void Begin(string method, string? transactionId)
+ {
+ lock (_gate)
+ {
+ ObjectDisposedException.ThrowIf(_disposeTask is not null, this);
+ if (transactionId is not null && _transactions?.Contains(transactionId) != true)
+ throw new InvalidOperationException("The transaction does not belong to this client rental.");
+ if (method == "RollbackTransaction" &&
+ !(_rollbackAttempts ??= new(StringComparer.Ordinal)).Add(transactionId!))
+ throw new InvalidOperationException("Rollback was already attempted. Dispose this client rental.");
+ _activeCalls++;
+ }
+ }
+
+ private async Task ObserveAsync(Task response, string method, string? transactionId)
+ {
+ try
+ {
+ T result = await response.ConfigureAwait(false);
+ Complete(method, transactionId, result, failed: false);
+ return result;
+ }
+ catch { Complete(method, transactionId, null, failed: true); throw; }
+ }
+
+ private void Complete(string method, string? transactionId, object? response, bool failed)
+ {
+ lock (_gate)
+ {
+ if (failed) _healthy = false;
+ else if (response is TransactionSessionInfoMessage transaction)
+ (_transactions ??= new(StringComparer.Ordinal)).Add(transaction.TransactionId);
+ else if (method is "CommitTransaction" or "RollbackTransaction")
+ {
+ _transactions?.Remove(transactionId!);
+ _rollbackAttempts?.Remove(transactionId!);
+ }
+ _activeCalls--;
+ if (_activeCalls == 0) _drained?.TrySetResult();
+ }
+ }
+
+ public ValueTask DisposeAsync()
+ {
+ Task drain;
+ TaskCompletionSource completion;
+ lock (_gate)
+ {
+ if (_disposeTask is not null) return new ValueTask(_disposeTask);
+ if (_activeCalls == 0 && (_transactions is null || _transactions.Count == 0))
+ {
+ // Completed reads need no cleanup task. Publish disposal before
+ // returning the owner so a stale rental cannot issue another RPC.
+ _disposeTask = Task.CompletedTask;
+ try
+ {
+ ValueTask returned = release(owner, _healthy);
+ if (returned.IsCompletedSuccessfully) returned.GetAwaiter().GetResult();
+ else _disposeTask = returned.AsTask();
+ }
+ catch (Exception error) { _disposeTask = Task.FromException(error); }
+ return new ValueTask(_disposeTask);
+ }
+ completion = new(TaskCreationOptions.RunContinuationsAsynchronously);
+ _disposeTask = completion.Task;
+ drain = _activeCalls == 0 ? Task.CompletedTask
+ : (_drained = new(TaskCreationOptions.RunContinuationsAsynchronously)).Task;
+ }
+ _ = ResetAndReturnAsync(drain, completion);
+ return new ValueTask(completion.Task);
+ }
+
+ private async Task ResetAndReturnAsync(Task drain, TaskCompletionSource completion)
+ {
+ try
+ {
+ bool needsCleanup;
+ lock (_gate) needsCleanup = _activeCalls != 0 || _transactions?.Count > 0;
+ if (needsCleanup)
+ {
+ // Ordinary completed reads need no timer or cleanup RPC.
+ // One deadline covers outstanding calls and all rollback cleanup.
+ using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(5));
+ try { await drain.WaitAsync(timeout.Token).ConfigureAwait(false); }
+ catch { lock (_gate) _healthy = false; }
+ if (drain.IsCompletedSuccessfully)
+ {
+ string[] pending;
+ lock (_gate) pending = _transactions is null ? []
+ : _transactions.Except(_rollbackAttempts ?? []).ToArray();
+ foreach (string transactionId in pending)
+ {
+ try { await owner.RollbackTransactionAsync(transactionId, timeout.Token).WaitAsync(timeout.Token).ConfigureAwait(false); }
+ catch { lock (_gate) _healthy = false; }
+ }
+ }
+ }
+ bool healthy;
+ lock (_gate)
+ {
+ healthy = _healthy;
+ _transactions?.Clear();
+ }
+ await release(owner, healthy).ConfigureAwait(false);
+ completion.SetResult();
+ }
+ catch (Exception error) { completion.SetException(error); }
+ }
+}
diff --git a/src/CSharpDB.Client/Internal/GrpcClientPool.cs b/src/CSharpDB.Client/Internal/GrpcClientPool.cs
new file mode 100644
index 00000000..617f8bfd
--- /dev/null
+++ b/src/CSharpDB.Client/Internal/GrpcClientPool.cs
@@ -0,0 +1,189 @@
+using System.Collections.Concurrent;
+using System.Diagnostics;
+using System.Runtime.CompilerServices;
+
+namespace CSharpDB.Client.Internal;
+
+/// Pools validated gRPC clients; every checkout gets fresh logical session state.
+internal static class GrpcClientPoolRegistry
+{
+ private static readonly ConcurrentDictionary Pools = new();
+ // Client options and route contexts are immutable after initialization. Weak
+ // keys avoid retaining one-off configurations after their callers release them.
+ private static readonly ConditionalWeakTable ValidatedEndpoints = new();
+ // Retire unused families as well as their sockets, including high-cardinality routes.
+ private static readonly Timer IdleTimer = new(static state => { _ = PruneAsync(); }, null,
+ TimeSpan.FromSeconds(30), TimeSpan.FromSeconds(30));
+
+ public static async ValueTask RentAsync(
+ CSharpDbClientOptions options, int maxPoolSize, CancellationToken ct)
+ {
+ ArgumentOutOfRangeException.ThrowIfLessThan(maxPoolSize, 1);
+ var endpoint = ValidatedEndpoints.GetValue(options, ClientTransportResolver.ResolvePooledGrpcEndpoint);
+ var key = new GrpcPoolKey(options, endpoint, maxPoolSize);
+ while (true)
+ {
+ ct.ThrowIfCancellationRequested();
+ var pool = Pools.GetOrAdd(key, static (poolKey, clientOptions) =>
+ new GrpcClientPool(clientOptions, poolKey.MaxPoolSize), options);
+ var session = await pool.TryRentAsync(ct).ConfigureAwait(false);
+ if (session is not null) return session;
+ Pools.TryRemove(new KeyValuePair(key, pool));
+ }
+ }
+
+ public static async ValueTask ClearAsync(string? endpoint = null)
+ {
+ string? normalized = endpoint is null ? null : new Uri(endpoint, UriKind.Absolute).AbsoluteUri;
+ foreach (var pair in Pools)
+ if ((normalized is null || pair.Key.Endpoint == normalized) &&
+ Pools.TryRemove(new KeyValuePair(pair.Key, pair.Value)))
+ await pair.Value.RetireAsync().ConfigureAwait(false);
+ }
+
+ private static async Task PruneAsync()
+ {
+ foreach (var pair in Pools)
+ {
+ if (!pair.Value.TryRetireIdle(TimeSpan.FromMinutes(2))) continue;
+ Pools.TryRemove(new KeyValuePair(pair.Key, pair.Value));
+ try { await pair.Value.RetireAsync().ConfigureAwait(false); }
+ catch { /* A background prune must not terminate the process. */ }
+ }
+ }
+
+ private readonly struct GrpcPoolKey : IEquatable
+ {
+ public string Endpoint { get; }
+ public int MaxPoolSize { get; }
+ private readonly CSharpDbGrpcMode _mode;
+ private readonly CSharpDbGrpcCallMode _callMode;
+ private readonly HttpClient? _httpClient;
+ private readonly string? _keyspace, _routeKey, _apiKey;
+ private readonly string _apiKeyHeader;
+
+ public GrpcPoolKey(CSharpDbClientOptions options, Uri endpoint, int maxPoolSize)
+ {
+ Endpoint = endpoint.AbsoluteUri;
+ MaxPoolSize = maxPoolSize;
+ _mode = options.GrpcMode;
+ _callMode = options.GrpcCallMode;
+ _httpClient = options.HttpClient;
+ _keyspace = options.RouteContext?.Keyspace;
+ _routeKey = options.RouteContext?.Key;
+ _apiKey = options.ApiKey;
+ _apiKeyHeader = options.ApiKeyHeaderName;
+ }
+
+ public bool Equals(GrpcPoolKey other)
+ => Endpoint == other.Endpoint && MaxPoolSize == other.MaxPoolSize &&
+ _mode == other._mode && _callMode == other._callMode && ReferenceEquals(_httpClient, other._httpClient) &&
+ _keyspace == other._keyspace && _routeKey == other._routeKey &&
+ _apiKey == other._apiKey && _apiKeyHeader == other._apiKeyHeader;
+ public override bool Equals(object? obj) => obj is GrpcPoolKey other && Equals(other);
+ public override int GetHashCode()
+ {
+ var hash = new HashCode();
+ hash.Add(Endpoint); hash.Add(MaxPoolSize); hash.Add(_mode);
+ hash.Add(_callMode);
+ hash.Add(_httpClient is null ? 0 : System.Runtime.CompilerServices.RuntimeHelpers.GetHashCode(_httpClient));
+ hash.Add(_keyspace); hash.Add(_routeKey); hash.Add(_apiKey); hash.Add(_apiKeyHeader);
+ return hash.ToHashCode();
+ }
+ }
+}
+
+internal sealed class GrpcClientPool
+{
+ private readonly object _gate = new();
+ private readonly Stack _idle = new();
+ private readonly SemaphoreSlim _slots;
+ private readonly CancellationTokenSource _retirement = new();
+ private readonly CSharpDbClientOptions _options;
+ private readonly Func _return;
+ private bool _retired;
+ private int _active;
+ private long _lastUse = Stopwatch.GetTimestamp();
+
+ public GrpcClientPool(CSharpDbClientOptions options, int maxPoolSize)
+ {
+ _options = options;
+ _slots = new SemaphoreSlim(maxPoolSize, maxPoolSize);
+ _return = ReturnAsync;
+ }
+
+ public async ValueTask TryRentAsync(CancellationToken ct)
+ {
+ ct.ThrowIfCancellationRequested();
+ if (!_slots.Wait(0))
+ {
+ using var linked = CancellationTokenSource.CreateLinkedTokenSource(ct, _retirement.Token);
+ try { await _slots.WaitAsync(linked.Token).ConfigureAwait(false); }
+ catch (OperationCanceledException) when (!ct.IsCancellationRequested && _retirement.IsCancellationRequested)
+ { return null; }
+ }
+
+ GrpcTransportClient? client;
+ lock (_gate)
+ {
+ if (_retired) { _slots.Release(); return null; }
+ _active++;
+ _lastUse = Stopwatch.GetTimestamp();
+ client = _idle.TryPop(out var idle) ? idle : null;
+ }
+ try
+ {
+ if (client is null)
+ {
+ client = (GrpcTransportClient)ClientTransportResolver.Create(_options);
+ await client.GetInfoAsync(ct).ConfigureAwait(false);
+ }
+ ct.ThrowIfCancellationRequested();
+ return client.CreateLease(_return);
+ }
+ catch
+ {
+ try { if (client is not null) await client.DisposeAsync().ConfigureAwait(false); }
+ finally { lock (_gate) _active--; _slots.Release(); }
+ throw;
+ }
+ }
+
+ private async ValueTask ReturnAsync(GrpcTransportClient client, bool reusable)
+ {
+ bool dispose;
+ lock (_gate)
+ {
+ _active--;
+ _lastUse = Stopwatch.GetTimestamp();
+ dispose = _retired || !reusable;
+ if (!dispose) _idle.Push(client);
+ }
+ try { if (dispose) await client.DisposeAsync().ConfigureAwait(false); }
+ finally { _slots.Release(); }
+ }
+
+ public bool TryRetireIdle(TimeSpan idleAge)
+ {
+ lock (_gate)
+ {
+ if (_retired || _active != 0 || Stopwatch.GetElapsedTime(_lastUse) < idleAge) return false;
+ _retired = true;
+ return true;
+ }
+ }
+
+ public async ValueTask RetireAsync()
+ {
+ GrpcTransportClient[] idle;
+ lock (_gate)
+ {
+ _retired = true;
+ idle = _idle.ToArray();
+ _idle.Clear();
+ }
+ _retirement.Cancel();
+ foreach (var client in idle) await client.DisposeAsync().ConfigureAwait(false);
+ // Active clients are disposed on return. Waiters reopen through the registry.
+ }
+}
diff --git a/src/CSharpDB.Client/Internal/GrpcCommandSession.cs b/src/CSharpDB.Client/Internal/GrpcCommandSession.cs
new file mode 100644
index 00000000..fdc31989
--- /dev/null
+++ b/src/CSharpDB.Client/Internal/GrpcCommandSession.cs
@@ -0,0 +1,353 @@
+using CSharpDB.Client.Grpc;
+using Google.Protobuf.WellKnownTypes;
+using Grpc.Core;
+using Grpc.Core.Interceptors;
+
+namespace CSharpDB.Client.Internal;
+
+/// Adapts command calls to one ordered, versioned native gRPC stream.
+internal sealed class GrpcCommandSession(CallInvoker invoker) : Interceptor, IAsyncDisposable
+{
+ private const string ResultSchemaCapability = "result-schema-ref-v1";
+ private const string SingleInt64Capability = "single-int64-result-v1";
+ private readonly object _gate = new();
+ private readonly SemaphoreSlim _commands = new(1, 1);
+ private readonly CancellationTokenSource _lifetime = new();
+ private readonly CSharpDbRpc.CSharpDbRpcClient _client = new(invoker);
+ private AsyncDuplexStreamingCall? _call;
+ private Exception? _fault;
+ private Task? _disposeTask;
+ private bool _negotiated;
+ private bool _resultSchemaReferences;
+ private bool _singleInt64Results;
+ private ulong _requestId;
+ private ulong _lastResultSchemaId;
+ private ResultSchema? _resultSchema;
+
+ public override AsyncUnaryCall AsyncUnaryCall(
+ TRequest request, ClientInterceptorContext context,
+ AsyncUnaryCallContinuation continuation)
+ {
+ CommandSessionRequest? command = context.Method.Name switch
+ {
+ "GetInfo" => new() { GetInfo = (Empty)(object)request },
+ "ExecuteSql" => new() { ExecuteSql = (SqlRequest)(object)request },
+ "BeginTransaction" => new() { BeginTransaction = (Empty)(object)request },
+ "ExecuteInTransaction" => new() { ExecuteInTransaction = (TransactionSqlRequest)(object)request },
+ "CommitTransaction" => new() { CommitTransaction = (TransactionIdRequest)(object)request },
+ "RollbackTransaction" => new() { RollbackTransaction = (TransactionIdRequest)(object)request },
+ _ => null,
+ };
+ if (command is null) return continuation(request, context);
+ var state = new UnaryCall(this, command, context.Options);
+ return new AsyncUnaryCall(state.Response,
+ static value => ((UnaryCall)value).HeadersAsync(),
+ static value => ((UnaryCall)value).Status(),
+ static value => ((UnaryCall)value).Trailers(),
+ static value => ((UnaryCall)value).Cancel(), state);
+ }
+
+ internal async Task ExecuteAsync(CommandSessionRequest command, CancellationToken ct)
+ where TResponse : class
+ => ReadResponse((await ExchangeAsync(command, ct).ConfigureAwait(false)).Response);
+
+ internal readonly record struct SqlReply(SqlExecutionResultMessage Response, GrpcSessionResultMetadata? Metadata);
+ private readonly record struct ExchangeReply(CommandSessionResponse Response, GrpcSessionResultMetadata? Metadata);
+
+ internal async Task ExecuteSqlAsync(CommandSessionRequest command, CancellationToken ct)
+ {
+ if (command.CommandCase is not (CommandSessionRequest.CommandOneofCase.ExecuteSql or
+ CommandSessionRequest.CommandOneofCase.ExecuteInTransaction))
+ throw new ArgumentException("The command must execute SQL.", nameof(command));
+ ExchangeReply reply = await ExchangeAsync(command, ct, captureSqlMetadata: true).ConfigureAwait(false);
+ return new(ReadResponse(reply.Response), reply.Metadata);
+ }
+
+ private static TResponse ReadResponse(CommandSessionResponse response) where TResponse : class
+ {
+ if (response.Error is not null) throw ReadError(response.Error);
+ return (TResponse)(object)(response.Info ?? (object?)response.Result ?? response.Transaction ?? (object?)response.Completed)!;
+ }
+
+ private async Task ExchangeAsync(CommandSessionRequest command, CancellationToken ct,
+ bool captureSqlMetadata = false)
+ {
+ // A canceled waiter has sent nothing and must not cancel the active command.
+ await _commands.WaitAsync(ct).ConfigureAwait(false);
+ try
+ {
+ AsyncDuplexStreamingCall call;
+ lock (_gate)
+ {
+ ObjectDisposedException.ThrowIf(_disposeTask is not null, this);
+ if (_fault is not null)
+ throw new RpcException(new Status(StatusCode.Unavailable, "The command session is closed. Commands are never replayed."));
+ call = _call ??= _client.CommandSession(cancellationToken: _lifetime.Token);
+ }
+ try
+ {
+ ct.ThrowIfCancellationRequested();
+ if (!_negotiated)
+ {
+ await call.RequestStream.WriteAsync(new CommandSessionRequest
+ {
+ Hello = new CommandSessionHello
+ {
+ ProtocolVersion = 1,
+ Capabilities = { ResultSchemaCapability, SingleInt64Capability },
+ },
+ }, ct).ConfigureAwait(false);
+ if (!await call.ResponseStream.MoveNext(ct).ConfigureAwait(false))
+ throw ProtocolError("The server closed the command session before negotiation.");
+ var hello = call.ResponseStream.Current;
+ if (hello.RequestId != 0 || hello.ResultSchemaId != 0 || hello.ResultSchemaReference ||
+ hello.Ready is not { ProtocolVersion: 1, MaxInFlight: 1 } ||
+ !hello.Ready.Capabilities.Contains("sql") || !hello.Ready.Capabilities.Contains("transactions"))
+ throw ProtocolError("The server did not negotiate the required command session capabilities.");
+ _resultSchemaReferences = hello.Ready.Capabilities.Contains(ResultSchemaCapability);
+ _singleInt64Results = hello.Ready.Capabilities.Contains(SingleInt64Capability);
+ _negotiated = true;
+ }
+ command.RequestId = checked(++_requestId);
+ await call.RequestStream.WriteAsync(command, ct).ConfigureAwait(false);
+ if (!await call.ResponseStream.MoveNext(ct).ConfigureAwait(false))
+ throw ProtocolError("The server closed the command session before returning a command result.");
+ var response = call.ResponseStream.Current;
+ if (response.RequestId != command.RequestId || !Matches(command, response))
+ throw ProtocolError("The command session returned an unexpected request ID or result type.");
+ if (response.Error is { } error) _ = ReadError(error); // Validate errors inside the fault boundary, too.
+ ResultSchema? schema = ResolveResultSchema(response);
+ ValidateSingleInt64Result(response, schema);
+ GrpcSessionResultMetadata? metadata = null;
+ if (captureSqlMetadata)
+ metadata = schema?.EnsureMetadata();
+ else if (response.ResultSchemaReference)
+ schema!.Restore(response.Result!);
+ return new(response, metadata);
+ }
+ catch (Exception error)
+ {
+ _resultSchema = null;
+ lock (_gate) _fault ??= error;
+ _lifetime.Cancel();
+ call.Dispose();
+ throw;
+ }
+ }
+ finally { _commands.Release(); }
+ }
+
+ private void ValidateSingleInt64Result(CommandSessionResponse response, ResultSchema? schema)
+ {
+ if (response.Result is not { HasScalarInt64: true } result) return;
+ if (!_singleInt64Results)
+ throw ProtocolError("The command session returned a compact integer result without negotiation.");
+ // Validate against the captured wire schema without rehydrating reference
+ // frames. A present Rows wrapper, even empty, conflicts with this encoding.
+ if (!result.IsQuery || result.Error is not null || result.Rows is not null ||
+ !(schema?.HasSingleColumnMetadata ?? GrpcModelMapper.HasSingleColumnMetadata(result)))
+ throw ProtocolError("A compact integer result requires a successful one-column query and no rows payload.");
+ }
+
+ private ResultSchema? ResolveResultSchema(CommandSessionResponse response)
+ {
+ if (!_resultSchemaReferences)
+ {
+ if (response.ResultSchemaId != 0 || response.ResultSchemaReference)
+ throw ProtocolError("The command session returned result schema fields without negotiation.");
+ return null;
+ }
+
+ if (response.Result is not { IsQuery: true, Error: null } result)
+ {
+ if (response.ResultSchemaId != 0 || response.ResultSchemaReference)
+ throw ProtocolError("Only successful query results can define or reference a result schema.");
+ _resultSchema = null;
+ return null;
+ }
+
+ if (response.ResultSchemaReference)
+ {
+ if (_resultSchema is null || response.ResultSchemaId == 0 || response.ResultSchemaId != _resultSchema.Id)
+ throw ProtocolError("The command session referenced an unknown or stale result schema.");
+ if (result.ColumnNames is not null || result.ColumnTypes is not null ||
+ result.ColumnNullability is not null || result.Columns.Count != 0)
+ throw ProtocolError("A result schema reference must omit all column metadata.");
+ return _resultSchema;
+ }
+
+ if (_lastResultSchemaId == ulong.MaxValue || response.ResultSchemaId != _lastResultSchemaId + 1)
+ throw ProtocolError("Result schema definitions must have consecutive nonzero IDs.");
+ _resultSchema = new ResultSchema(response.ResultSchemaId, result);
+ _lastResultSchemaId = response.ResultSchemaId;
+ return _resultSchema;
+ }
+
+ /// Owns immutable private metadata, independent of every received result.
+ private sealed class ResultSchema
+ {
+ private readonly SqlExecutionResultMessage _definition;
+ private GrpcSessionResultMetadata? _metadata;
+ public ulong Id { get; }
+ public bool HasSingleColumnMetadata { get; }
+
+ public ResultSchema(ulong id, SqlExecutionResultMessage result)
+ {
+ Id = id;
+ _definition = new SqlExecutionResultMessage
+ {
+ ColumnNames = result.ColumnNames?.Clone(),
+ ColumnTypes = result.ColumnTypes?.Clone(),
+ ColumnNullability = result.ColumnNullability?.Clone(),
+ };
+ _definition.Columns.Add(result.Columns.Select(column => column.Clone()));
+ HasSingleColumnMetadata = GrpcModelMapper.HasSingleColumnMetadata(_definition);
+ }
+
+ public GrpcSessionResultMetadata EnsureMetadata()
+ => _metadata ??= new GrpcSessionResultMetadata(_definition);
+
+ public void Restore(SqlExecutionResultMessage result)
+ {
+ // Only the generic wire API restores protobuf metadata. Never expose
+ // private cache objects through its mutable returned message, including
+ // before the mapped metadata snapshot has first been initialized.
+ result.ColumnNames = _definition.ColumnNames?.Clone();
+ result.ColumnTypes = _definition.ColumnTypes?.Clone();
+ result.ColumnNullability = _definition.ColumnNullability?.Clone();
+ result.Columns.Add(_definition.Columns.Select(column => column.Clone()));
+ }
+ }
+
+ private static bool Matches(CommandSessionRequest command, CommandSessionResponse response)
+ => response.Error is not null || command.CommandCase switch
+ {
+ CommandSessionRequest.CommandOneofCase.GetInfo => response.Info is not null,
+ CommandSessionRequest.CommandOneofCase.ExecuteSql or CommandSessionRequest.CommandOneofCase.ExecuteInTransaction => response.Result is not null,
+ CommandSessionRequest.CommandOneofCase.BeginTransaction => response.Transaction is not null,
+ CommandSessionRequest.CommandOneofCase.CommitTransaction or CommandSessionRequest.CommandOneofCase.RollbackTransaction => response.Completed is not null,
+ _ => false,
+ };
+
+ private static RpcException ProtocolError(string message)
+ => new(new Status(StatusCode.DataLoss, message));
+
+ private static RpcException ReadError(CommandSessionError error)
+ {
+ var code = (StatusCode)error.StatusCode;
+ if (!System.Enum.IsDefined(code) || code == StatusCode.OK) throw ProtocolError("The command session returned an invalid error status.");
+ var trailers = new Metadata();
+ try
+ {
+ foreach (var item in error.Trailers)
+ {
+ if (item.ValueCase == CommandSessionMetadata.ValueOneofCase.Binary) trailers.Add(item.Key, item.Binary.ToByteArray());
+ else if (item.ValueCase == CommandSessionMetadata.ValueOneofCase.Text) trailers.Add(item.Key, item.Text);
+ else throw ProtocolError("The command session returned an invalid error trailer.");
+ }
+ }
+ catch (ArgumentException) { throw ProtocolError("The command session returned an invalid error trailer."); }
+ return new RpcException(new Status(code, error.Detail), trailers);
+ }
+
+ public ValueTask DisposeAsync()
+ {
+ TaskCompletionSource completion;
+ lock (_gate)
+ {
+ if (_disposeTask is not null) return new ValueTask(_disposeTask);
+ completion = new(TaskCreationOptions.RunContinuationsAsynchronously);
+ _disposeTask = completion.Task;
+ }
+ _ = CloseAsync(completion);
+ return new ValueTask(completion.Task);
+ }
+
+ private async Task CloseAsync(TaskCompletionSource completion)
+ {
+ bool idle = _commands.Wait(0);
+ try
+ {
+ var call = _call;
+ if (idle && call is not null && _fault is null)
+ {
+ using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(2));
+ try
+ {
+ await call.RequestStream.CompleteAsync().WaitAsync(timeout.Token).ConfigureAwait(false);
+ // EOF acknowledges server-side cleanup before the owner closes.
+ if (await call.ResponseStream.MoveNext(timeout.Token).ConfigureAwait(false))
+ throw ProtocolError("An idle command session returned an unsolicited result.");
+ }
+ catch { /* Retirement still aborts a broken or unresponsive stream. */ }
+ }
+ }
+ finally
+ {
+ _lifetime.Cancel();
+ _call?.Dispose();
+ if (idle) _commands.Release();
+ // A concurrent command may still be unwinding its cancellation.
+ // The semaphore and token source remain valid until it releases them.
+ completion.TrySetResult();
+ }
+ }
+
+ private sealed class UnaryCall where T : class
+ {
+ private readonly GrpcCommandSession _session;
+ private readonly CancellationTokenSource _cancellation;
+ public Task Response { get; }
+
+ public UnaryCall(GrpcCommandSession session, CommandSessionRequest command, CallOptions options)
+ {
+ _session = session;
+ _cancellation = CancellationTokenSource.CreateLinkedTokenSource(options.CancellationToken);
+ if (options.Deadline is { } deadline)
+ {
+ TimeSpan remaining = deadline - DateTime.UtcNow;
+ if (remaining <= TimeSpan.Zero) _cancellation.Cancel();
+ else _cancellation.CancelAfter(remaining);
+ }
+ Response = RunAsync(command);
+ }
+
+ private async Task RunAsync(CommandSessionRequest command)
+ {
+ try
+ {
+ var response = await _session.ExchangeAsync(command, _cancellation.Token).ConfigureAwait(false);
+ return ReadResponse(response.Response);
+ }
+ finally { _cancellation.Dispose(); }
+ }
+
+ public void Cancel()
+ {
+ try { _cancellation.Cancel(); }
+ catch (ObjectDisposedException) { }
+ }
+
+ public async Task HeadersAsync()
+ {
+ try { await Response.ConfigureAwait(false); }
+ catch { }
+ return _session._call is { } call
+ ? await call.ResponseHeadersAsync.ConfigureAwait(false) : new Metadata();
+ }
+
+ public Status Status()
+ {
+ if (!Response.IsCompleted) throw new InvalidOperationException("The command has not completed.");
+ if (Response.IsCompletedSuccessfully) return global::Grpc.Core.Status.DefaultSuccess;
+ return Response.Exception?.GetBaseException() is RpcException rpc
+ ? rpc.Status : new Status(StatusCode.Cancelled, "The command was canceled.");
+ }
+
+ public Metadata Trailers()
+ {
+ if (!Response.IsCompleted) throw new InvalidOperationException("The command has not completed.");
+ return Response.Exception?.GetBaseException() is RpcException rpc ? rpc.Trailers : new Metadata();
+ }
+ }
+}
diff --git a/src/CSharpDB.Client/Internal/GrpcRouteContextClientInterceptor.cs b/src/CSharpDB.Client/Internal/GrpcRouteContextClientInterceptor.cs
index 2e736156..99a98062 100644
--- a/src/CSharpDB.Client/Internal/GrpcRouteContextClientInterceptor.cs
+++ b/src/CSharpDB.Client/Internal/GrpcRouteContextClientInterceptor.cs
@@ -9,6 +9,17 @@ public override AsyncUnaryCall AsyncUnaryCall(
TRequest request,
ClientInterceptorContext context,
AsyncUnaryCallContinuation continuation)
+ {
+ return continuation(request, WithHeaders(context));
+ }
+
+ public override AsyncDuplexStreamingCall AsyncDuplexStreamingCall(
+ ClientInterceptorContext context,
+ AsyncDuplexStreamingCallContinuation continuation)
+ => continuation(WithHeaders(context));
+
+ private ClientInterceptorContext WithHeaders(
+ ClientInterceptorContext context) where TRequest : class where TResponse : class
{
var metadata = new Metadata();
if (context.Options.Headers is not null)
@@ -26,9 +37,9 @@ public override AsyncUnaryCall AsyncUnaryCall(
metadata.Add(CSharpDbRouteHeaderNames.GrpcShardKey, routeContext.Key);
var options = context.Options.WithHeaders(metadata);
- return continuation(request, new ClientInterceptorContext(
+ return new ClientInterceptorContext(
context.Method,
context.Host,
- options));
+ options);
}
}
diff --git a/src/CSharpDB.Client/Internal/GrpcTransportClient.ScalarProjection.cs b/src/CSharpDB.Client/Internal/GrpcTransportClient.ScalarProjection.cs
new file mode 100644
index 00000000..119ed14a
--- /dev/null
+++ b/src/CSharpDB.Client/Internal/GrpcTransportClient.ScalarProjection.cs
@@ -0,0 +1,63 @@
+using System.Runtime.CompilerServices;
+using CSharpDB.Client.Grpc;
+using Grpc.Core;
+
+namespace CSharpDB.Client.Internal;
+
+internal sealed partial class GrpcTransportClient : IScalarProjectionClient
+{
+ bool IScalarProjectionClient.SupportsScalarProjection => _commandSession is not null;
+
+ ValueTask IScalarProjectionClient.ExecuteScalarProjectionAsync(
+ string sql, string? transactionId, CancellationToken cancellationToken)
+ {
+ if (_commandSession is null)
+ throw new NotSupportedException("Scalar projection requires a command session.");
+
+ CommandSessionRequest command = transactionId is null
+ ? new() { ExecuteSql = new SqlRequest { Sql = sql } }
+ : new()
+ {
+ ExecuteInTransaction = new TransactionSqlRequest { TransactionId = transactionId, Sql = sql },
+ };
+
+ // Dispatch through the same lease accounting, transaction checks and session fault boundary.
+ return MapScalarProjectionAsync(_lease is not null
+ ? _lease.ExecuteSqlAsync(_commandSession, command, cancellationToken)
+ : _commandSession.ExecuteSqlAsync(command, cancellationToken),
+ cancellationToken);
+ }
+
+ [AsyncMethodBuilder(typeof(PoolingAsyncValueTaskMethodBuilder<>))]
+ private static async ValueTask MapScalarProjectionAsync(
+ Task response, CancellationToken cancellationToken)
+ {
+ try
+ {
+ return MapScalarProjectionReply(await response.ConfigureAwait(false));
+ }
+ catch (RpcException ex) when (ex.StatusCode == StatusCode.Cancelled && cancellationToken.IsCancellationRequested)
+ {
+ throw new OperationCanceledException(cancellationToken);
+ }
+ catch (RpcException ex)
+ {
+ throw TranslateRpcException(ex);
+ }
+ }
+
+ internal static ScalarProjectionResult MapScalarProjectionReply(GrpcCommandSession.SqlReply reply)
+ {
+ SqlExecutionResultMessage response = reply.Response;
+ if (response.HasScalarInt64 && response.IsQuery && response.Error is null && response.Rows is null
+ && reply.Metadata is { } metadata && metadata.TryGetScalarType(out var declaredType))
+ {
+ // Full SDK mapping validates duration before Data performs type conversion or cancellation.
+ _ = response.Elapsed.ToTimeSpan();
+ return ScalarProjectionResult.FromCompactInt64(response.ScalarInt64, declaredType);
+ }
+
+ // Map the response already received. Unsupported shapes must never execute SQL again.
+ return ScalarProjectionResult.FromFallback(GrpcModelMapper.ToSessionModel(response, reply.Metadata));
+ }
+}
diff --git a/src/CSharpDB.Client/Internal/GrpcTransportClient.cs b/src/CSharpDB.Client/Internal/GrpcTransportClient.cs
index acccc124..0ea56c10 100644
--- a/src/CSharpDB.Client/Internal/GrpcTransportClient.cs
+++ b/src/CSharpDB.Client/Internal/GrpcTransportClient.cs
@@ -19,13 +19,18 @@ internal sealed partial class GrpcTransportClient : ICSharpDbClient, ICSharpDbSh
private readonly GrpcChannel _channel;
private readonly CSharpDbRpc.CSharpDbRpcClient _client;
private readonly string _endpoint;
+ private readonly CallInvoker _invoker;
+ private readonly GrpcClientLease? _lease;
+ private readonly GrpcCommandSession? _commandSession;
public GrpcTransportClient(
Uri endpoint,
HttpClient? httpClient = null,
string? apiKey = null,
string? apiKeyHeaderName = null,
- CSharpDbRouteContext? routeContext = null)
+ CSharpDbRouteContext? routeContext = null,
+ CSharpDbGrpcMode grpcMode = CSharpDbGrpcMode.Auto,
+ CSharpDbGrpcCallMode grpcCallMode = CSharpDbGrpcCallMode.Unary)
{
ArgumentNullException.ThrowIfNull(endpoint);
@@ -37,15 +42,24 @@ public GrpcTransportClient(
channelOptions.HttpClient = httpClient;
channelOptions.DisposeHttpClient = false;
}
- else if (endpoint.Scheme.Equals(Uri.UriSchemeHttp, StringComparison.OrdinalIgnoreCase))
+ else if (grpcMode == CSharpDbGrpcMode.Auto &&
+ endpoint.Scheme.Equals(Uri.UriSchemeHttp, StringComparison.OrdinalIgnoreCase))
{
channelOptions.HttpHandler = new GrpcWebHandler(
GrpcWebMode.GrpcWeb,
new HttpClientHandler());
+ // This handler belongs to the transport, including when a pool retires it.
+ channelOptions.DisposeHttpClient = true;
channelOptions.HttpVersion = System.Net.HttpVersion.Version11;
channelOptions.HttpVersionPolicy = HttpVersionPolicy.RequestVersionExact;
}
+ if (grpcMode == CSharpDbGrpcMode.Native)
+ {
+ channelOptions.HttpVersion = System.Net.HttpVersion.Version20;
+ channelOptions.HttpVersionPolicy = HttpVersionPolicy.RequestVersionExact;
+ }
+
_channel = GrpcChannel.ForAddress(endpoint, channelOptions);
CallInvoker invoker = _channel.CreateCallInvoker();
if (!string.IsNullOrWhiteSpace(apiKey))
@@ -53,9 +67,29 @@ public GrpcTransportClient(
if (routeContext is not null)
invoker = invoker.Intercept(new GrpcRouteContextClientInterceptor(routeContext));
+ if (grpcCallMode == CSharpDbGrpcCallMode.Streaming)
+ {
+ _commandSession = new GrpcCommandSession(invoker);
+ invoker = invoker.Intercept(_commandSession);
+ }
+
+ _invoker = invoker;
_client = new CSharpDbRpc.CSharpDbRpcClient(invoker);
}
+ private GrpcTransportClient(GrpcTransportClient owner, GrpcClientLease lease)
+ {
+ _channel = owner._channel;
+ _endpoint = owner._endpoint;
+ _lease = lease;
+ _commandSession = owner._commandSession;
+ _invoker = owner._invoker.Intercept(lease);
+ _client = new CSharpDbRpc.CSharpDbRpcClient(_invoker);
+ }
+
+ internal GrpcTransportClient CreateLease(Func release)
+ => new(this, new GrpcClientLease(this, release));
+
public string DataSource => _endpoint;
public Task GetShardMapAsync(CancellationToken ct = default)
@@ -219,7 +253,9 @@ public Task MarkDirectoryEntryStaleAsync(
ct);
public Task GetInfoAsync(CancellationToken ct = default)
- => CallAsync(_client.GetInfoAsync(EmptyRequest, cancellationToken: ct), GrpcModelMapper.ToModel, ct);
+ => _commandSession is not null
+ ? CallSessionAsync(new() { GetInfo = EmptyRequest }, GrpcModelMapper.ToModel, ct)
+ : CallAsync(_client.GetInfoAsync(EmptyRequest, cancellationToken: ct), GrpcModelMapper.ToModel, ct);
public Task> GetTableNamesAsync(CancellationToken ct = default)
=> CallAsync(_client.GetTableNamesAsync(EmptyRequest, cancellationToken: ct), GrpcModelMapper.ToStringList, ct);
@@ -462,23 +498,36 @@ public Task ExecuteProcedureAsync(string name, IReadOn
}, cancellationToken: ct), GrpcModelMapper.ToModel, ct);
public Task ExecuteSqlAsync(string sql, CancellationToken ct = default)
- => CallAsync(_client.ExecuteSqlAsync(new SqlRequest { Sql = sql }, cancellationToken: ct), GrpcModelMapper.ToModel, ct);
+ => _commandSession is not null
+ ? CallSessionSqlAsync(new() { ExecuteSql = new SqlRequest { Sql = sql } }, ct)
+ : CallAsync(_client.ExecuteSqlAsync(new SqlRequest { Sql = sql }, cancellationToken: ct), GrpcModelMapper.ToModel, ct);
public Task BeginTransactionAsync(CancellationToken ct = default)
- => CallAsync(_client.BeginTransactionAsync(EmptyRequest, cancellationToken: ct), GrpcModelMapper.ToModel, ct);
+ => _commandSession is not null
+ ? CallSessionAsync(new() { BeginTransaction = EmptyRequest }, GrpcModelMapper.ToModel, ct)
+ : CallAsync(_client.BeginTransactionAsync(EmptyRequest, cancellationToken: ct), GrpcModelMapper.ToModel, ct);
public Task ExecuteInTransactionAsync(string transactionId, string sql, CancellationToken ct = default)
- => CallAsync(_client.ExecuteInTransactionAsync(new TransactionSqlRequest
- {
- TransactionId = transactionId,
- Sql = sql,
- }, cancellationToken: ct), GrpcModelMapper.ToModel, ct);
+ => _commandSession is not null
+ ? CallSessionSqlAsync(new()
+ {
+ ExecuteInTransaction = new TransactionSqlRequest { TransactionId = transactionId, Sql = sql },
+ }, ct)
+ : CallAsync(_client.ExecuteInTransactionAsync(new TransactionSqlRequest
+ {
+ TransactionId = transactionId,
+ Sql = sql,
+ }, cancellationToken: ct), GrpcModelMapper.ToModel, ct);
public Task CommitTransactionAsync(string transactionId, CancellationToken ct = default)
- => CallEmptyAsync(_client.CommitTransactionAsync(new TransactionIdRequest { TransactionId = transactionId }, cancellationToken: ct), ct);
+ => _commandSession is not null
+ ? CallSessionEmptyAsync(new() { CommitTransaction = new TransactionIdRequest { TransactionId = transactionId } }, ct)
+ : CallEmptyAsync(_client.CommitTransactionAsync(new TransactionIdRequest { TransactionId = transactionId }, cancellationToken: ct), ct);
public Task RollbackTransactionAsync(string transactionId, CancellationToken ct = default)
- => CallEmptyAsync(_client.RollbackTransactionAsync(new TransactionIdRequest { TransactionId = transactionId }, cancellationToken: ct), ct);
+ => _commandSession is not null
+ ? CallSessionEmptyAsync(new() { RollbackTransaction = new TransactionIdRequest { TransactionId = transactionId } }, ct)
+ : CallEmptyAsync(_client.RollbackTransactionAsync(new TransactionIdRequest { TransactionId = transactionId }, cancellationToken: ct), ct);
public Task> GetCollectionNamesAsync(CancellationToken ct = default)
=> CallAsync(_client.GetCollectionNamesAsync(EmptyRequest, cancellationToken: ct), GrpcModelMapper.ToStringList, ct);
@@ -575,10 +624,57 @@ public Task CheckIndexesAsync(string? databasePath = null, s
public ValueTask DisposeAsync()
{
+ if (_lease is not null) return _lease.DisposeAsync();
+ if (_commandSession is not null) return DisposeCommandSessionAsync();
_channel.Dispose();
return ValueTask.CompletedTask;
}
+ private async ValueTask DisposeCommandSessionAsync()
+ {
+ try { await _commandSession!.DisposeAsync().ConfigureAwait(false); }
+ finally { _channel.Dispose(); }
+ }
+
+ // Rental guards run synchronously, before asynchronous response mapping,
+ // just as they do on the generated unary call path.
+ private Task DispatchSessionAsync(CommandSessionRequest command, CancellationToken ct)
+ where TResponse : class
+ => _lease is not null
+ ? _lease.ExecuteAsync(_commandSession!, command, ct)
+ : _commandSession!.ExecuteAsync(command, ct);
+
+ private Task CallSessionAsync(
+ CommandSessionRequest command, Func map, CancellationToken ct)
+ where TResponse : class
+ => MapSessionAsync(DispatchSessionAsync(command, ct), map, ct);
+
+ private Task CallSessionEmptyAsync(CommandSessionRequest command, CancellationToken ct)
+ => MapSessionAsync(DispatchSessionAsync(command, ct), static response => response, ct);
+
+ private Task CallSessionSqlAsync(CommandSessionRequest command, CancellationToken ct)
+ => MapSessionAsync(_lease is not null
+ ? _lease.ExecuteSqlAsync(_commandSession!, command, ct)
+ : _commandSession!.ExecuteSqlAsync(command, ct),
+ static reply => GrpcModelMapper.ToSessionModel(reply.Response, reply.Metadata), ct);
+
+ private static async Task MapSessionAsync(
+ Task response, Func map, CancellationToken ct)
+ {
+ try
+ {
+ return map(await response.ConfigureAwait(false));
+ }
+ catch (RpcException ex) when (ex.StatusCode == StatusCode.Cancelled && ct.IsCancellationRequested)
+ {
+ throw new OperationCanceledException(ct);
+ }
+ catch (RpcException ex)
+ {
+ throw TranslateRpcException(ex);
+ }
+ }
+
private async Task CallEmptyAsync(AsyncUnaryCall call, CancellationToken ct)
{
try
diff --git a/src/CSharpDB.Client/Internal/IScalarProjectionClient.cs b/src/CSharpDB.Client/Internal/IScalarProjectionClient.cs
new file mode 100644
index 00000000..1602dbc4
--- /dev/null
+++ b/src/CSharpDB.Client/Internal/IScalarProjectionClient.cs
@@ -0,0 +1,55 @@
+using CSharpDB.Client.Models;
+
+namespace CSharpDB.Client.Internal;
+
+/// A private result projection over the existing client session and rental.
+internal interface IScalarProjectionClient
+{
+ bool SupportsScalarProjection { get; }
+ /// Each returned ValueTask must be consumed exactly once.
+ ValueTask ExecuteScalarProjectionAsync(
+ string sql, string? transactionId, CancellationToken cancellationToken);
+}
+
+// Only immutable primitives cross this boundary; canonical SDK metadata remains private.
+internal sealed record class ScalarTypeSnapshot
+{
+ public ScalarTypeSnapshot(
+ SqlTypeKind Kind, int? Length, int? Precision, int? Scale, int? FractionalSecondsPrecision)
+ {
+ this.Kind = Kind;
+ this.Length = Length;
+ this.Precision = Precision;
+ this.Scale = Scale;
+ this.FractionalSecondsPrecision = FractionalSecondsPrecision;
+ }
+
+ public SqlTypeKind Kind { get; }
+ public int? Length { get; }
+ public int? Precision { get; }
+ public int? Scale { get; }
+ public int? FractionalSecondsPrecision { get; }
+}
+
+internal readonly struct ScalarProjectionResult
+{
+ private ScalarProjectionResult(
+ bool hasCompactInt64, long value, ScalarTypeSnapshot? declaredType, SqlExecutionResult? fallback)
+ {
+ HasCompactInt64 = hasCompactInt64;
+ Int64 = value;
+ DeclaredType = declaredType;
+ Fallback = fallback;
+ }
+
+ internal bool HasCompactInt64 { get; }
+ internal long Int64 { get; }
+ internal ScalarTypeSnapshot? DeclaredType { get; }
+ internal SqlExecutionResult? Fallback { get; }
+
+ internal static ScalarProjectionResult FromCompactInt64(long value, ScalarTypeSnapshot? declaredType)
+ => new(true, value, declaredType, null);
+
+ internal static ScalarProjectionResult FromFallback(SqlExecutionResult result)
+ => new(false, default, null, result ?? throw new ArgumentNullException(nameof(result)));
+}
diff --git a/src/CSharpDB.Client/Protos/csharpdb_rpc.proto b/src/CSharpDB.Client/Protos/csharpdb_rpc.proto
index b3059a93..c3545c8a 100644
--- a/src/CSharpDB.Client/Protos/csharpdb_rpc.proto
+++ b/src/CSharpDB.Client/Protos/csharpdb_rpc.proto
@@ -82,6 +82,7 @@ service CSharpDbRpc {
rpc ExecuteProcedure (ExecuteProcedureRequest) returns (ProcedureExecutionResultMessage);
rpc ExecuteSql (SqlRequest) returns (SqlExecutionResultMessage);
+ rpc CommandSession (stream CommandSessionRequest) returns (stream CommandSessionResponse);
rpc BeginTransaction (google.protobuf.Empty) returns (TransactionSessionInfoMessage);
rpc ExecuteInTransaction (TransactionSqlRequest) returns (SqlExecutionResultMessage);
@@ -780,6 +781,60 @@ message ExecuteProcedureRequest {
VariantObject args = 2;
}
+// Version 1 deliberately permits only one command in flight per stream.
+message CommandSessionHello {
+ uint32 protocol_version = 1;
+ repeated string capabilities = 2;
+}
+
+message CommandSessionReady {
+ uint32 protocol_version = 1;
+ uint32 max_in_flight = 2;
+ repeated string capabilities = 3;
+}
+
+message CommandSessionRequest {
+ uint64 request_id = 1;
+ oneof command {
+ CommandSessionHello hello = 2;
+ google.protobuf.Empty get_info = 3;
+ SqlRequest execute_sql = 4;
+ google.protobuf.Empty begin_transaction = 5;
+ TransactionSqlRequest execute_in_transaction = 6;
+ TransactionIdRequest commit_transaction = 7;
+ TransactionIdRequest rollback_transaction = 8;
+ }
+}
+
+message CommandSessionMetadata {
+ string key = 1;
+ oneof value {
+ string text = 2;
+ bytes binary = 3;
+ }
+}
+
+message CommandSessionError {
+ int32 status_code = 1;
+ string detail = 2;
+ repeated CommandSessionMetadata trailers = 3;
+}
+
+message CommandSessionResponse {
+ uint64 request_id = 1;
+ oneof outcome {
+ CommandSessionReady ready = 2;
+ DatabaseInfoMessage info = 3;
+ SqlExecutionResultMessage result = 4;
+ TransactionSessionInfoMessage transaction = 5;
+ google.protobuf.Empty completed = 6;
+ CommandSessionError error = 7;
+ }
+ // Used only after both peers negotiate result-schema-ref-v1.
+ uint64 result_schema_id = 8;
+ bool result_schema_reference = 9;
+}
+
message SqlRequest {
string sql = 1;
}
@@ -1024,6 +1079,8 @@ message SqlExecutionResultMessage {
StringList column_types = 7;
BoolList column_nullability = 8;
repeated ColumnDefinitionMessage columns = 9;
+ // Negotiated single-int64-result-v1 command sessions only. Presence includes zero.
+ optional sint64 scalar_int64 = 10;
}
message DatabaseInfoMessage {
diff --git a/src/CSharpDB.Client/README.md b/src/CSharpDB.Client/README.md
index 51e84a30..e4f7ed28 100644
--- a/src/CSharpDB.Client/README.md
+++ b/src/CSharpDB.Client/README.md
@@ -4,11 +4,55 @@
It owns the public client contract used to talk to a database, while transport and lower-level implementation details stay behind that boundary.
+## Shared gRPC pooling
+
+Rent a client when your application creates and disposes a client for each
+operation. The SDK owns the pool; ADO.NET's `Pooling=true` uses this same pool.
+
+```csharp
+var options = new CSharpDbClientOptions
+{
+ Transport = CSharpDbTransport.Grpc,
+ Endpoint = "http://localhost:5000",
+};
+await using var client = await CSharpDbClient.RentAsync(options, maxPoolSize: 32, ct: ct);
+var result = await client.ExecuteSqlAsync("SELECT 42", ct);
+// Dispose returns the connection to the shared pool.
+```
+
+`Create(options)` remains an unpooled factory. Keeping one created client open
+already reuses its channel. `RentAsync` adds reuse across separate client
+lifetimes and supports both Auto gRPC-Web and Native HTTP/2. Pools isolate
+endpoint, mode, credentials, routing, caller-owned HTTP client, and capacity.
+The same configuration and capacity allow SDK and ADO.NET to share a pool.
+
+A new physical connection performs `GetInfo`; warm rentals make no validation
+RPC. At capacity, rentals wait and honor cancellation. Each rental has fresh
+lifetime and transaction ownership: disposed rentals cannot send RPCs, and a
+transaction identifier must belong to the rental that created it. Dispose
+drains outstanding RPCs and rolls back unfinished transactions under one
+five-second cleanup deadline. Failed or canceled RPCs discard the connection;
+SQL error responses do not automatically discard it. Commands are never
+replayed. An unacknowledged rollback does not prove that the server released
+its transaction.
+
+`ClearPoolAsync(endpoint)` retires every configuration for an endpoint;
+`ClearAllPoolsAsync()` retires all shared gRPC pools. Idle connections close
+immediately, active connections close on return, and waiting rentals can join
+a new pool. Families without active rentals expire after two idle minutes,
+checked every 30 seconds. Caller-owned `HttpClient` objects remain caller-owned.
+API-key authentication still occurs per RPC. Warm rentals do not prove current
+server reachability, and remote prepared statement handles are not added.
+
## Current Direction
- `CSharpDB.Client` is now the real implementation layer for database access.
- `Direct`, `Http`, and `Grpc` are implemented transports today.
-- `NamedPipes` remains the only future transport target.
+- `NamedPipes` is reserved but remains unimplemented.
+- The shared pooling/session foundation is retained after the gRPC
+ micro-optimization experiment. A custom TCP transport is a separate proposed
+ experiment and is not implemented in this checkpoint. See the
+ [network experiment closeout](../../tests/CSharpDB.NetworkBenchmarks/CLOSEOUT.md).
## Logical Types, Carriers, and Row Values
@@ -57,6 +101,17 @@ var client = CSharpDbClient.Create(new CSharpDbClientOptions
The transport can be selected explicitly with `Transport`. If it is omitted, the client infers it from `Endpoint` and otherwise defaults to direct.
+Transactions opened by one direct client, including the daemon's database client,
+share its cached database and writer coordinator. Each session owns an isolated
+transaction and temporary-table scope. Commit, rollback, and rental cleanup finish
+the session without closing another session's database or WAL. Conflicting writes
+return `TransactionConflict`; commands are not replayed automatically. Releasing
+the cached database or starting exclusive maintenance requires all transactions
+and their finalization to finish. File and incremental hybrid owners support
+overlapping transactions. Snapshot hybrid mode with automatic commit or disposal
+persistence requires exclusive session access and returns `Busy` for overlapping
+transactions or ordinary commands until the active transaction finishes.
+
Direct resolution currently accepts:
- `Endpoint` as a file path
@@ -181,6 +236,86 @@ var client = CSharpDbClient.Create(new CSharpDbClientOptions
This resolves to the dedicated `CSharpDB.Daemon` gRPC host.
+`GrpcMode = CSharpDbGrpcMode.Auto` preserves existing behavior: plain HTTP
+uses gRPC-Web over HTTP/1.1 when no `HttpClient` is supplied; HTTPS uses native
+gRPC. A supplied `HttpClient` retains its existing handler configuration.
+
+To require native HTTP/2 gRPC explicitly, including on an unencrypted local
+HTTP/2-only listener, use:
+
+```csharp
+await using var client = CSharpDbClient.Create(new CSharpDbClientOptions
+{
+ Transport = CSharpDbTransport.Grpc,
+ Endpoint = "http://127.0.0.1:5821",
+ GrpcMode = CSharpDbGrpcMode.Native
+});
+```
+
+Native mode requires HTTP/2 and does not fall back to gRPC-Web or HTTP/1.1.
+Configure the corresponding daemon listener as shown in its
+[transport guide](../CSharpDB.Daemon/README.md#native-http2-grpc).
+Reuse this client across operations to reuse the underlying connection.
+Custom `HttpClient` instances remain caller-owned and must support HTTP/2
+without a gRPC-Web wrapper when used with native mode.
+
+### Experimental persistent command sessions
+
+Set both `GrpcMode = CSharpDbGrpcMode.Native` and
+`GrpcCallMode = CSharpDbGrpcCallMode.Streaming` to send SQL, transaction
+commands, and `GetInfo` over one persistent bidirectional gRPC call:
+
+```csharp
+var options = new CSharpDbClientOptions
+{
+ Transport = CSharpDbTransport.Grpc,
+ Endpoint = "http://127.0.0.1:5821",
+ GrpcMode = CSharpDbGrpcMode.Native,
+ GrpcCallMode = CSharpDbGrpcCallMode.Streaming
+};
+await using var client = await CSharpDbClient.RentAsync(options, maxPoolSize: 32);
+await client.ExecuteSqlAsync("SELECT 42");
+```
+
+The first command negotiates protocol version 1 and SQL/transaction
+capabilities. Authentication and routing metadata bind to the stream when
+it opens. Each physical stream executes one command at a time; concurrent
+calls queue. SDK and ADO.NET share the existing pool for matching options,
+including call mode. `Unary` remains the default and uses a separate pool
+family. Other APIs continue using their existing unary RPCs.
+
+Peers can also negotiate `result-schema-ref-v1`. Each stream retains one
+private result schema and sends a schema reference when the next query's
+actual metadata matches it. A changed schema sends full metadata again;
+non-query results, errors, and other commands clear the cached schema.
+Older peers continue sending full metadata. Public result metadata remains
+independent across calls and rentals. An invalid schema reference closes
+the stream without replaying the command.
+
+The client maps each negotiated schema definition once and privately caches
+that mapping. Referenced results use the captured mapping directly, with
+fresh arrays, column objects, and declared-type objects for every result.
+
+The independent `single-int64-result-v1` capability encodes a successful
+one-row, one-column `Int64` result without nested protobuf row objects.
+Selection uses the actual result shape and carrier; declared SQL types and
+public result collections are preserved. Nulls, other carriers, and other
+result shapes use the existing encoding. Peers negotiate this capability
+before use, and unary RPCs continue using the existing encoding.
+
+Returning a rental rolls back its unfinished transactions before reuse.
+Disconnecting a stream also triggers server rollback of its remaining
+transactions, with a five-second cleanup deadline. Cancellation during an
+active exchange closes the stream; a canceled queue waiter sends nothing.
+Failed rentals are discarded. Commands are never automatically replayed,
+and a lost commit response has an unknown outcome until the application
+checks the data. An older server without `CommandSession` fails explicitly.
+
+This prototype has no pipelining, batching, remote prepared handles, or
+session-wide temporary tables outside transaction sessions. Benchmark it
+against unary mode for your workload before enabling it; see the
+[fixed socket experiment](../../tests/CSharpDB.NetworkBenchmarks/README.md#persistent-command-session-experiment).
+
When the remote host is configured with API-key mode, set `ApiKey` once on the
client options. The HTTP transport sends it as a request header, and the gRPC
transport sends it as call metadata.
diff --git a/src/CSharpDB.Daemon/Grpc/CSharpDbRpcService.Session.cs b/src/CSharpDB.Daemon/Grpc/CSharpDbRpcService.Session.cs
new file mode 100644
index 00000000..eeaed2ee
--- /dev/null
+++ b/src/CSharpDB.Daemon/Grpc/CSharpDbRpcService.Session.cs
@@ -0,0 +1,132 @@
+using CSharpDB.Client.Grpc;
+using Google.Protobuf;
+using Google.Protobuf.WellKnownTypes;
+using Grpc.Core;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
+
+namespace CSharpDB.Daemon.Grpc;
+
+public sealed partial class CSharpDbRpcService
+{
+ public override async Task CommandSession(
+ IAsyncStreamReader requestStream,
+ IServerStreamWriter responseStream,
+ ServerCallContext context)
+ {
+ if (context.GetHttpContext().Request.Protocol != "HTTP/2")
+ throw new RpcException(new Status(StatusCode.Unimplemented, "Command sessions require native HTTP/2."));
+
+ var transactions = new HashSet(StringComparer.Ordinal);
+ try
+ {
+ using (var handshake = CancellationTokenSource.CreateLinkedTokenSource(context.CancellationToken))
+ {
+ handshake.CancelAfter(TimeSpan.FromSeconds(10));
+ if (!await requestStream.MoveNext(handshake.Token).ConfigureAwait(false)) return;
+ }
+ CommandSessionRequest hello = requestStream.Current;
+ if (hello.RequestId != 0 || hello.CommandCase != CommandSessionRequest.CommandOneofCase.Hello ||
+ hello.Hello.ProtocolVersion != 1)
+ throw new RpcException(new Status(StatusCode.Unimplemented, "Command session protocol version 1 is required."));
+
+ var ready = new CommandSessionReady { ProtocolVersion = 1, MaxInFlight = 1 };
+ ready.Capabilities.Add(["sql", "transactions"]);
+ bool reuseResultSchema = hello.Hello.Capabilities.Contains(CommandResultSchemaCache.Capability);
+ CommandResultSchemaCache? resultSchemas = null;
+ if (reuseResultSchema)
+ {
+ ready.Capabilities.Add(CommandResultSchemaCache.Capability);
+ resultSchemas = new CommandResultSchemaCache();
+ }
+ bool compactScalarInt64 = hello.Hello.Capabilities.Contains(SingleInt64ResultCapability);
+ if (compactScalarInt64) ready.Capabilities.Add(SingleInt64ResultCapability);
+ await responseStream.WriteAsync(new CommandSessionResponse { Ready = ready }).ConfigureAwait(false);
+ ulong lastRequest = 0;
+ while (await requestStream.MoveNext(context.CancellationToken).ConfigureAwait(false))
+ {
+ CommandSessionRequest request = requestStream.Current;
+ if (request.RequestId != checked(lastRequest + 1) ||
+ request.CommandCase is CommandSessionRequest.CommandOneofCase.None or CommandSessionRequest.CommandOneofCase.Hello)
+ throw new RpcException(new Status(StatusCode.InvalidArgument, "Command IDs must be consecutive and commands must be supported."));
+ lastRequest = request.RequestId;
+ var response = new CommandSessionResponse { RequestId = request.RequestId };
+ try
+ {
+ switch (request.CommandCase)
+ {
+ case CommandSessionRequest.CommandOneofCase.GetInfo:
+ response.Info = await GetInfo(EmptyResponse, context).ConfigureAwait(false);
+ break;
+ case CommandSessionRequest.CommandOneofCase.ExecuteSql:
+ var sqlResult = await ExecuteSqlResultAsync(request.ExecuteSql, context, static result => result).ConfigureAwait(false);
+ SetCommandSessionResult(response, sqlResult, resultSchemas, compactScalarInt64);
+ break;
+ case CommandSessionRequest.CommandOneofCase.BeginTransaction:
+ if (transactions.Count >= 64)
+ throw new RpcException(new Status(StatusCode.ResourceExhausted, "A command session supports at most 64 active transactions."));
+ response.Transaction = await BeginTransaction(EmptyResponse, context).ConfigureAwait(false);
+ transactions.Add(response.Transaction.TransactionId);
+ break;
+ case CommandSessionRequest.CommandOneofCase.ExecuteInTransaction:
+ RequireSessionTransaction(transactions, request.ExecuteInTransaction.TransactionId);
+ var transactionResult = await ExecuteAsync(context,
+ ct => client.ExecuteInTransactionAsync(request.ExecuteInTransaction.TransactionId,
+ request.ExecuteInTransaction.Sql, ct), static result => result).ConfigureAwait(false);
+ SetCommandSessionResult(response, transactionResult, resultSchemas, compactScalarInt64);
+ break;
+ case CommandSessionRequest.CommandOneofCase.CommitTransaction:
+ RequireSessionTransaction(transactions, request.CommitTransaction.TransactionId);
+ response.Completed = await CommitTransaction(request.CommitTransaction, context).ConfigureAwait(false);
+ transactions.Remove(request.CommitTransaction.TransactionId);
+ break;
+ case CommandSessionRequest.CommandOneofCase.RollbackTransaction:
+ RequireSessionTransaction(transactions, request.RollbackTransaction.TransactionId);
+ response.Completed = await RollbackTransaction(request.RollbackTransaction, context).ConfigureAwait(false);
+ transactions.Remove(request.RollbackTransaction.TransactionId);
+ break;
+ default:
+ throw new RpcException(new Status(StatusCode.Unimplemented, "Unsupported session command."));
+ }
+ }
+ catch (OperationCanceledException) when (context.CancellationToken.IsCancellationRequested) { throw; }
+ catch (Exception error)
+ {
+ RpcException rpc = error as RpcException ?? TranslateException(error);
+ response.Error = new CommandSessionError { StatusCode = (int)rpc.StatusCode, Detail = rpc.Status.Detail };
+ foreach (var trailer in rpc.Trailers)
+ {
+ var value = new CommandSessionMetadata { Key = trailer.Key };
+ if (trailer.IsBinary) value.Binary = ByteString.CopyFrom(trailer.ValueBytes);
+ else value.Text = trailer.Value;
+ response.Error.Trailers.Add(value);
+ }
+ }
+ if (response.Result is not { IsQuery: true, Error: null }) resultSchemas?.Clear();
+ await responseStream.WriteAsync(response).ConfigureAwait(false);
+ }
+ }
+ finally
+ {
+ // Even a Begin response lost to disconnect leaves its transaction
+ // owned here. Never close the shared database or replay a command.
+ using var cleanup = new CancellationTokenSource(TimeSpan.FromSeconds(5));
+ foreach (string transaction in transactions)
+ {
+ try { await client.RollbackTransactionAsync(transaction, cleanup.Token).ConfigureAwait(false); }
+ catch (Exception error)
+ {
+ // Cleanup is best effort; surface failures without masking the original call error.
+ services?.GetService>()?
+ .LogWarning(error, "Command session transaction cleanup failed.");
+ }
+ }
+ }
+ }
+
+ private static void RequireSessionTransaction(HashSet transactions, string transaction)
+ {
+ if (!transactions.Contains(transaction))
+ throw new RpcException(new Status(StatusCode.PermissionDenied, "The transaction does not belong to this command session."));
+ }
+}
diff --git a/src/CSharpDB.Daemon/Grpc/CSharpDbRpcService.SessionSchema.cs b/src/CSharpDB.Daemon/Grpc/CSharpDbRpcService.SessionSchema.cs
new file mode 100644
index 00000000..9f8cb024
--- /dev/null
+++ b/src/CSharpDB.Daemon/Grpc/CSharpDbRpcService.SessionSchema.cs
@@ -0,0 +1,128 @@
+using CSharpDB.Client.Grpc;
+using CSharpDB.Client.Models;
+
+namespace CSharpDB.Daemon.Grpc;
+
+public sealed partial class CSharpDbRpcService
+{
+ private const string SingleInt64ResultCapability = "single-int64-result-v1";
+
+ private static void SetCommandSessionResult(CommandSessionResponse response, SqlExecutionResult result,
+ CommandResultSchemaCache? schemas, bool allowCompactScalarInt64)
+ {
+ if (schemas is null) response.Result = GrpcModelMapper.ToMessage(result, includeMetadata: true, allowCompactScalarInt64: allowCompactScalarInt64);
+ else schemas.SetResult(response, result, allowCompactScalarInt64);
+ }
+
+ /// One privately owned schema snapshot for one negotiated command stream.
+ private sealed class CommandResultSchemaCache
+ {
+ internal const string Capability = "result-schema-ref-v1";
+ private ResultSchemaSnapshot? _schema;
+ private ulong _schemaId;
+
+ internal void Clear() => _schema = null;
+
+ internal void SetResult(CommandSessionResponse response, SqlExecutionResult result, bool allowCompactScalarInt64)
+ {
+ if (!result.IsQuery || result.Error is not null)
+ {
+ Clear();
+ response.Result = GrpcModelMapper.ToMessage(result, includeMetadata: true, allowCompactScalarInt64: allowCompactScalarInt64);
+ return;
+ }
+ if (_schema?.Matches(result) == true)
+ {
+ // Compare fresh backend metadata first; a hit never builds or
+ // serializes metadata messages merely to discard them afterward.
+ response.Result = GrpcModelMapper.ToMessage(result, includeMetadata: false, allowCompactScalarInt64: allowCompactScalarInt64);
+ response.ResultSchemaId = _schemaId;
+ response.ResultSchemaReference = true;
+ return;
+ }
+
+ SqlExecutionResultMessage message = GrpcModelMapper.ToMessage(result, includeMetadata: true, allowCompactScalarInt64: allowCompactScalarInt64);
+ var schema = new ResultSchemaSnapshot(result);
+ ulong id = checked(_schemaId + 1);
+ response.Result = message;
+ response.ResultSchemaId = id;
+ _schema = schema;
+ _schemaId = id;
+ }
+ }
+
+ private sealed class ResultSchemaSnapshot
+ {
+ private readonly string[]? _names;
+ private readonly string[]? _types;
+ private readonly bool[]? _nullability;
+ private readonly ColumnDefinition[]? _columns;
+
+ internal ResultSchemaSnapshot(SqlExecutionResult result)
+ {
+ _names = result.ColumnNames is null ? null : (string[])result.ColumnNames.Clone();
+ _types = result.ColumnTypes is null ? null : (string[])result.ColumnTypes.Clone();
+ _nullability = result.ColumnNullability is null ? null : (bool[])result.ColumnNullability.Clone();
+ if (result.Columns is { } columns)
+ {
+ _columns = new ColumnDefinition[columns.Length];
+ for (int i = 0; i < columns.Length; i++) _columns[i] = CopyColumn(columns[i]);
+ }
+ }
+
+ internal bool Matches(SqlExecutionResult result)
+ {
+ if (!EqualValues(_names, result.ColumnNames) || !EqualValues(_types, result.ColumnTypes)
+ || !EqualValues(_nullability, result.ColumnNullability)) return false;
+ var columns = result.Columns;
+ if (_columns is null || columns is null) return _columns is null && columns is null;
+ if (_columns.Length != columns.Length) return false;
+ for (int i = 0; i < columns.Length; i++)
+ if (!EqualColumn(_columns[i], columns[i])) return false;
+ return true;
+ }
+
+ private static bool EqualValues(T[]? expected, T[]? actual)
+ {
+ if (expected is null || actual is null) return expected is null && actual is null;
+ if (expected.Length != actual.Length) return false;
+ for (int i = 0; i < expected.Length; i++)
+ if (!EqualityComparer.Default.Equals(expected[i], actual[i])) return false;
+ return true;
+ }
+
+ private static bool EqualColumn(ColumnDefinition expected, ColumnDefinition? actual)
+ => actual is not null && expected.SchemaId == actual.SchemaId && expected.Name == actual.Name
+ && expected.Type == actual.Type && expected.Nullable == actual.Nullable
+ && expected.IsPrimaryKey == actual.IsPrimaryKey && expected.IsIdentity == actual.IsIdentity
+ && expected.IsRowVersion == actual.IsRowVersion && expected.Collation == actual.Collation
+ && expected.DefaultSql == actual.DefaultSql && EqualDeclaredType(expected.DeclaredType, actual.DeclaredType);
+
+ private static bool EqualDeclaredType(SqlTypeDescriptor? expected, SqlTypeDescriptor? actual)
+ {
+ if (expected is null || actual is null) return expected is null && actual is null;
+ return expected.Kind == actual.Kind && expected.Length == actual.Length
+ && expected.Precision == actual.Precision && expected.Scale == actual.Scale
+ && expected.FractionalSecondsPrecision == actual.FractionalSecondsPrecision;
+ }
+
+ private static ColumnDefinition CopyColumn(ColumnDefinition column)
+ => new()
+ {
+ SchemaId = column.SchemaId,
+ Name = column.Name,
+ Type = column.Type,
+ DeclaredType = column.DeclaredType is { } type ? new SqlTypeDescriptor
+ {
+ Kind = type.Kind, Length = type.Length, Precision = type.Precision,
+ Scale = type.Scale, FractionalSecondsPrecision = type.FractionalSecondsPrecision,
+ } : null,
+ Nullable = column.Nullable,
+ IsPrimaryKey = column.IsPrimaryKey,
+ IsIdentity = column.IsIdentity,
+ IsRowVersion = column.IsRowVersion,
+ Collation = column.Collation,
+ DefaultSql = column.DefaultSql,
+ };
+ }
+}
diff --git a/src/CSharpDB.Daemon/Grpc/CSharpDbRpcService.cs b/src/CSharpDB.Daemon/Grpc/CSharpDbRpcService.cs
index 66edccff..3daf49de 100644
--- a/src/CSharpDB.Daemon/Grpc/CSharpDbRpcService.cs
+++ b/src/CSharpDB.Daemon/Grpc/CSharpDbRpcService.cs
@@ -18,7 +18,7 @@
namespace CSharpDB.Daemon.Grpc;
-public sealed class CSharpDbRpcService : CSharpDbRpc.CSharpDbRpcBase
+public sealed partial class CSharpDbRpcService : CSharpDbRpc.CSharpDbRpcBase
{
public override Task ReadDefinitionCatalog(DefinitionCatalogRequest request, ServerCallContext context)
=> ExecuteAsync(context,
@@ -382,9 +382,13 @@ public override Task ExecuteProcedure(ExecutePr
=> ExecuteAsync(context, ct => client.ExecuteProcedureAsync(request.Name, ReadRequiredObject(request.Args), ct), GrpcModelMapper.ToMessage);
public override Task ExecuteSql(SqlRequest request, ServerCallContext context)
+ => ExecuteSqlResultAsync(request, context, GrpcModelMapper.ToMessage);
+
+ private Task ExecuteSqlResultAsync(SqlRequest request, ServerCallContext context,
+ Func map)
{
if (TryCreateStatelessTemporaryTableSqlRejection(request.Sql, out var rejection))
- return Task.FromResult(GrpcModelMapper.ToMessage(rejection));
+ return Task.FromResult(map(rejection));
return ExecuteAsync(
context,
@@ -400,7 +404,7 @@ public override Task ExecuteSql(SqlRequest request, S
return result;
},
- GrpcModelMapper.ToMessage);
+ map);
}
public override Task BeginTransaction(Empty request, ServerCallContext context)
diff --git a/src/CSharpDB.Daemon/README.md b/src/CSharpDB.Daemon/README.md
index 9996c1b8..ab663013 100644
--- a/src/CSharpDB.Daemon/README.md
+++ b/src/CSharpDB.Daemon/README.md
@@ -97,6 +97,54 @@ When `Transport = Grpc` connects to a plain `http://` daemon endpoint,
default HTTP service URL. HTTPS endpoints and custom gRPC test clients can still
use native gRPC.
+### Native HTTP/2 gRPC
+
+The SDK supports `GrpcMode = CSharpDbGrpcMode.Native`, and ADO.NET accepts
+`Grpc Mode=Native`. Both require HTTP/2 instead of selecting the default
+plain-HTTP gRPC-Web compatibility path. Existing clients remain on `Auto`.
+
+For a local experiment, configure two loopback listeners in the daemon's
+`appsettings.json` using Kestrel's standard endpoint configuration:
+
+```json
+{
+ "Kestrel": {
+ "Endpoints": {
+ "Compatibility": {
+ "Url": "http://127.0.0.1:5820",
+ "Protocols": "Http1"
+ },
+ "NativeGrpc": {
+ "Url": "http://127.0.0.1:5821",
+ "Protocols": "Http2"
+ }
+ }
+ }
+}
+```
+
+Merge this section with the existing configuration. REST and gRPC-Web clients
+use port `5820`; native gRPC clients use port `5821`. An unencrypted native
+gRPC listener must be HTTP/2-only. Remote deployments should use a trusted
+HTTPS listener supporting HTTP/2; native mode also works with HTTPS and
+retains certificate validation.
+
+The socket experiment is in
+[`tests/CSharpDB.NetworkBenchmarks`](../../tests/CSharpDB.NetworkBenchmarks/README.md).
+It uses the actual daemon with dynamically assigned loopback ports and the
+same SQL messages and database execution path in both arms.
+
+The daemon also exposes experimental `CommandSession` protocol version 1
+over native HTTP/2: a capability handshake followed by ordered SQL and
+transaction commands on one bidirectional stream. Clients opt in with
+`GrpcCallMode = CSharpDbGrpcCallMode.Streaming` or ADO.NET
+`Grpc Call Mode=Streaming`, together with explicit native mode. Existing
+unary RPCs remain available. Each session permits one command in flight,
+binds API-key/routing metadata at opening, and owns its transaction IDs.
+When it ends, unfinished transactions receive best-effort rollback with a
+five-second deadline. Cleanup failures are logged. No command is replayed
+after disconnect. See the [SDK session guide](../CSharpDB.Client/README.md#experimental-persistent-command-sessions).
+
For remote access to a daemon on another machine, use `Grpc` or `Http` with a
normal base address such as:
diff --git a/src/CSharpDB.Data/CSharpDbCommand.cs b/src/CSharpDB.Data/CSharpDbCommand.cs
index 6630660c..b6789883 100644
--- a/src/CSharpDB.Data/CSharpDbCommand.cs
+++ b/src/CSharpDB.Data/CSharpDbCommand.cs
@@ -67,6 +67,26 @@ public override async Task ExecuteNonQueryAsync(CancellationToken cancellat
public override async Task ExecuteScalarAsync(CancellationToken cancellationToken)
{
+ var connection = (CSharpDbConnection)(DbConnection
+ ?? throw new InvalidOperationException("Connection is not set."));
+ if (connection.GetSession() is RemoteDatabaseSession remote
+ && !IsTransactionControl(CommandText, out _))
+ {
+ using AdoCommandObservation? observation = connection.StartCommandObservation(CommandText);
+ try
+ {
+ string sql = SqlParameterBinder.Bind(CommandText, _parameters);
+ return await remote.ExecuteScalarAsync(sql, cancellationToken);
+ }
+ catch (Exception ex)
+ {
+ observation?.FailBeforeDispatch(ex);
+ if (ex is CSharpDbException databaseException)
+ throw new CSharpDbDataException(databaseException);
+ throw;
+ }
+ }
+
await using var result = await ExecuteQueryAsync(cancellationToken);
if (result.IsQuery &&
result.Schema.Length > 0 &&
@@ -108,12 +128,7 @@ private async ValueTask ExecuteQueryAsync(CancellationToken cancell
var connection = (CSharpDbConnection)(DbConnection
?? throw new InvalidOperationException("Connection is not set."));
var session = connection.GetSession();
- string normalizedCommand = CommandText.Trim().TrimEnd(';').Trim();
- bool isTransactionControl =
- normalizedCommand.Equals("START TRANSACTION", StringComparison.OrdinalIgnoreCase)
- || normalizedCommand.Equals("BEGIN TRANSACTION", StringComparison.OrdinalIgnoreCase)
- || normalizedCommand.Equals("COMMIT", StringComparison.OrdinalIgnoreCase)
- || normalizedCommand.Equals("ROLLBACK", StringComparison.OrdinalIgnoreCase);
+ bool isTransactionControl = IsTransactionControl(CommandText, out string normalizedCommand);
using AdoCommandObservation? observation = isTransactionControl
? null
: connection.StartCommandObservation(CommandText);
@@ -171,6 +186,15 @@ private async ValueTask ExecuteQueryAsync(CancellationToken cancell
}
}
+ private static bool IsTransactionControl(string commandText, out string normalizedCommand)
+ {
+ normalizedCommand = commandText.Trim().TrimEnd(';').Trim();
+ return normalizedCommand.Equals("START TRANSACTION", StringComparison.OrdinalIgnoreCase)
+ || normalizedCommand.Equals("BEGIN TRANSACTION", StringComparison.OrdinalIgnoreCase)
+ || normalizedCommand.Equals("COMMIT", StringComparison.OrdinalIgnoreCase)
+ || normalizedCommand.Equals("ROLLBACK", StringComparison.OrdinalIgnoreCase);
+ }
+
public override void Cancel() { /* no-op */ }
public override void Prepare()
{
diff --git a/src/CSharpDB.Data/CSharpDbConnection.cs b/src/CSharpDB.Data/CSharpDbConnection.cs
index a8372d72..4331b8a6 100644
--- a/src/CSharpDB.Data/CSharpDbConnection.cs
+++ b/src/CSharpDB.Data/CSharpDbConnection.cs
@@ -25,6 +25,8 @@ private static readonly ConditionalWeakTable
s_sharedPooledOpenPlans = new();
+ private static readonly ConditionalWeakTable
+ s_sharedRemoteOpenPlans = new();
private string _connectionString = "";
private CSharpDbConnectionStringBuilder? _connectionStringBuilder;
@@ -144,22 +146,31 @@ public override async Task OpenAsync(CancellationToken cancellationToken)
IDisposable? lifecycleBoundary = null;
try
{
- SharedPooledOpenPlan? sharedPooledPlan = GetSharedPooledOpenPlan();
- if (sharedPooledPlan is not null)
+ if (CanShareRemoteOpenPlan() &&
+ s_sharedRemoteOpenPlans.TryGetValue(_connectionString, out var remotePlan))
{
- lifecycleBoundary = EnterDatabaseOpenBoundary(
- sharedPooledPlan.Configuration.RuntimeDirectDatabaseOptions);
- _session = await OpenPreparedPooledSessionAsync(
- sharedPooledPlan,
- cancellationToken);
+ _session = new RemoteDatabaseSession(await CSharpDbClient.RentAsync(
+ remotePlan.Options, remotePlan.MaxPoolSize, cancellationToken));
}
else
{
- ConnectionOpenPlan plan = GetConnectionOpenPlan();
- TryCacheSharedPooledOpenPlan(plan);
- lifecycleBoundary = EnterDatabaseOpenBoundary(
- plan.Embedded?.Configuration.RuntimeDirectDatabaseOptions);
- _session = await OpenConfiguredSessionAsync(plan, cancellationToken);
+ SharedPooledOpenPlan? sharedPooledPlan = GetSharedPooledOpenPlan();
+ if (sharedPooledPlan is not null)
+ {
+ lifecycleBoundary = EnterDatabaseOpenBoundary(
+ sharedPooledPlan.Configuration.RuntimeDirectDatabaseOptions);
+ _session = await OpenPreparedPooledSessionAsync(
+ sharedPooledPlan,
+ cancellationToken);
+ }
+ else
+ {
+ ConnectionOpenPlan plan = GetConnectionOpenPlan();
+ TryCacheSharedPooledOpenPlan(plan);
+ lifecycleBoundary = EnterDatabaseOpenBoundary(
+ plan.Embedded?.Configuration.RuntimeDirectDatabaseOptions);
+ _session = await OpenConfiguredSessionAsync(plan, cancellationToken);
+ }
}
CacheCommandObservabilityOptionsSnapshot(
@@ -263,6 +274,11 @@ public static void ClearPool(string connectionString)
public static async ValueTask ClearPoolAsync(string connectionString)
{
var builder = new CSharpDbConnectionStringBuilder(connectionString);
+ if (!string.IsNullOrWhiteSpace(builder.Endpoint))
+ {
+ await CSharpDbClient.ClearPoolAsync(builder.Endpoint.Trim());
+ return;
+ }
if (string.IsNullOrWhiteSpace(builder.DataSource))
return;
@@ -298,6 +314,7 @@ public static async ValueTask ClearAllPoolsAsync()
{
await CSharpDbConnectionPoolRegistry.ClearAllAsync();
await SharedMemoryDatabaseRegistry.ClearAllAsync();
+ await CSharpDbClient.ClearAllPoolsAsync();
}
public async ValueTask SaveToFileAsync(string filePath, CancellationToken cancellationToken = default)
@@ -707,17 +724,29 @@ private async ValueTask OpenRemoteSessionAsync(
if (!string.IsNullOrWhiteSpace(builder.LoadFrom))
throw new InvalidOperationException("Load From is only supported for embedded in-memory data sources.");
- if (builder.Pooling)
- throw new InvalidOperationException("Pooling is not supported for daemon-backed connections.");
+ if (builder.Pooling && transport != CSharpDbTransport.Grpc)
+ throw new InvalidOperationException("Remote pooling is currently supported only for the Grpc transport.");
string endpoint = builder.Endpoint.Trim();
- ICSharpDbClient client = await OpenClientAsync(new CSharpDbClientOptions
+ var options = new CSharpDbClientOptions
{
Transport = transport,
Endpoint = endpoint,
HttpClient = TransportHttpClient,
+ GrpcMode = builder.GrpcMode ?? CSharpDbGrpcMode.Auto,
+ GrpcCallMode = builder.GrpcCallMode ?? CSharpDbGrpcCallMode.Unary,
RouteContext = BuildRouteContext(builder),
- }, cancellationToken);
+ };
+
+ if (builder.Pooling)
+ {
+ int maxPoolSize = builder.MaxPoolSize;
+ ICSharpDbClient rented = await CSharpDbClient.RentAsync(options, maxPoolSize, cancellationToken);
+ if (CanShareRemoteOpenPlan())
+ s_sharedRemoteOpenPlans.GetValue(_connectionString, _ => new SharedRemoteOpenPlan(options, maxPoolSize));
+ return new RemoteDatabaseSession(rented);
+ }
+ ICSharpDbClient client = await OpenClientAsync(options, cancellationToken);
return new RemoteDatabaseSession(client);
}
@@ -740,6 +769,12 @@ private static PoolKey CreatePoolKey(
private CSharpDbConnectionStringBuilder GetConnectionStringBuilder()
=> _connectionStringBuilder ??= new CSharpDbConnectionStringBuilder(_connectionString);
+ private bool CanShareRemoteOpenPlan()
+ => !string.IsNullOrEmpty(_connectionString) && TransportHttpClient is null &&
+ DirectDatabaseOptions is null && HybridDatabaseOptions is null;
+
+ private sealed record SharedRemoteOpenPlan(CSharpDbClientOptions Options, int MaxPoolSize);
+
private SharedPooledOpenPlan? GetSharedPooledOpenPlan()
{
if (_sharedPooledOpenPlan is not null)
@@ -827,6 +862,12 @@ private ConnectionOpenPlan GetConnectionOpenPlan()
CSharpDbConnectionStringBuilder builder = GetConnectionStringBuilder();
string? currentDirectoryKey = GetCurrentDirectoryCacheKey(builder);
CSharpDbTransport? configuredTransport = ParseTransportOrNull(builder.Transport);
+ if (builder.GrpcCallMode == CSharpDbGrpcCallMode.Streaming &&
+ (configuredTransport != CSharpDbTransport.Grpc || builder.GrpcMode != CSharpDbGrpcMode.Native))
+ throw new InvalidOperationException("Streaming gRPC requires Transport=Grpc and Grpc Mode=Native.");
+ if (builder.GrpcMode is { } grpcMode &&
+ grpcMode != CSharpDbGrpcMode.Auto && configuredTransport != CSharpDbTransport.Grpc)
+ throw new InvalidOperationException("Grpc Mode is only supported for the Grpc transport.");
bool hasEmbeddedTuning = CSharpDbEmbeddedConfigurationResolver.HasRequestedTuning(
builder,
DirectDatabaseOptions,
diff --git a/src/CSharpDB.Data/CSharpDbConnectionStringBuilder.cs b/src/CSharpDB.Data/CSharpDbConnectionStringBuilder.cs
index 2c9c7214..05e38580 100644
--- a/src/CSharpDB.Data/CSharpDbConnectionStringBuilder.cs
+++ b/src/CSharpDB.Data/CSharpDbConnectionStringBuilder.cs
@@ -1,5 +1,6 @@
using System.Data.Common;
using System.Globalization;
+using CSharpDB.Client;
namespace CSharpDB.Data;
@@ -10,6 +11,8 @@ public sealed class CSharpDbConnectionStringBuilder : DbConnectionStringBuilder
private const string LoadFromKey = "Load From";
private const string PoolingKey = "Pooling";
private const string TransportKey = "Transport";
+ private const string GrpcModeKey = "Grpc Mode";
+ private const string GrpcCallModeKey = "Grpc Call Mode";
private const string MaxPoolSizeKey = "Max Pool Size";
private const string StoragePresetKey = "Storage Preset";
private const string EmbeddedOpenModeKey = "Embedded Open Mode";
@@ -61,6 +64,40 @@ public int MaxPoolSize
}
}
+ public CSharpDbGrpcMode? GrpcMode
+ {
+ get
+ {
+ var mode = GetNullableEnum(GrpcModeKey);
+ if (mode.HasValue && !Enum.IsDefined(mode.Value))
+ throw new FormatException("Grpc Mode must be Auto or Native.");
+ return mode;
+ }
+ set
+ {
+ if (value.HasValue && !Enum.IsDefined(value.Value))
+ throw new ArgumentOutOfRangeException(nameof(value), "Grpc Mode must be Auto or Native.");
+ SetNullableEnum(GrpcModeKey, value);
+ }
+ }
+
+ public CSharpDbGrpcCallMode? GrpcCallMode
+ {
+ get
+ {
+ var mode = GetNullableEnum(GrpcCallModeKey);
+ if (mode.HasValue && !Enum.IsDefined(mode.Value))
+ throw new FormatException("Grpc Call Mode must be Unary or Streaming.");
+ return mode;
+ }
+ set
+ {
+ if (value.HasValue && !Enum.IsDefined(value.Value))
+ throw new ArgumentOutOfRangeException(nameof(value), "Grpc Call Mode must be Unary or Streaming.");
+ SetNullableEnum(GrpcCallModeKey, value);
+ }
+ }
+
public CSharpDbStoragePreset? StoragePreset
{
get => GetNullableEnum(StoragePresetKey);
diff --git a/src/CSharpDB.Data/CSharpDbTransaction.cs b/src/CSharpDB.Data/CSharpDbTransaction.cs
index 1336199e..7e7d9117 100644
--- a/src/CSharpDB.Data/CSharpDbTransaction.cs
+++ b/src/CSharpDB.Data/CSharpDbTransaction.cs
@@ -61,7 +61,17 @@ protected override void Dispose(bool disposing)
{
if (disposing && !_completed)
{
- try { Rollback(); } catch { /* best-effort rollback on dispose */ }
+ try
+ {
+ if (_connection.GetSession() is RemoteDatabaseSession)
+ {
+ using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(5));
+ RollbackAsync(timeout.Token).GetAwaiter().GetResult();
+ }
+ else Rollback();
+ }
+ catch { /* best-effort rollback on dispose */ }
+ finally { _completed = true; _connection.ClearTransaction(); }
}
base.Dispose(disposing);
}
@@ -70,7 +80,14 @@ public override async ValueTask DisposeAsync()
{
if (!_completed)
{
- try { await RollbackAsync(CancellationToken.None); } catch { }
+ try
+ {
+ using var timeout = _connection.GetSession() is RemoteDatabaseSession
+ ? new CancellationTokenSource(TimeSpan.FromSeconds(5)) : null;
+ await RollbackAsync(timeout?.Token ?? CancellationToken.None);
+ }
+ catch { }
+ finally { _completed = true; _connection.ClearTransaction(); }
}
}
}
diff --git a/src/CSharpDB.Data/README.md b/src/CSharpDB.Data/README.md
index 2028fd98..319de07b 100644
--- a/src/CSharpDB.Data/README.md
+++ b/src/CSharpDB.Data/README.md
@@ -164,8 +164,77 @@ Connection-string rules:
- Embedded/direct mode: use `Data Source=...`
- Daemon-backed mode: use `Transport=Grpc;Endpoint=http://...`
-- `Data Source`, `Load From`, and connection pooling are embedded-only options
+- `Data Source` and `Load From` are embedded-only options
+- Remote `Pooling=true` is supported with `Transport=Grpc`; pooling defaults to `false`
- `Endpoint` requires an explicit `Transport`
+- `Grpc Mode=Native` explicitly requires HTTP/2 with `Transport=Grpc`;
+ omitted or `Grpc Mode=Auto` preserves the existing compatibility behavior
+
+For a local HTTP/2-only daemon listener, use:
+
+```text
+Transport=Grpc;Grpc Mode=Native;Endpoint=http://127.0.0.1:5821
+```
+
+Configure the listener using the daemon's
+[native gRPC guide](../CSharpDB.Daemon/README.md#native-http2-grpc).
+This selects the wire protocol. Pooling is a separate option; remote
+server-side prepared handles are not implemented.
+
+### Remote gRPC pooling
+
+For applications that open and close an ADO.NET connection for each command,
+opt into reuse of validated gRPC clients and their channels:
+
+```text
+Transport=Grpc;Endpoint=http://localhost:5000;Pooling=true;Max Pool Size=32
+```
+
+The pool lives in `CSharpDB.Client`. ADO.NET rents through
+`CSharpDbClient.RentAsync`; direct SDK callers and ADO.NET share retained
+connections when endpoint, mode, routing, credentials, HTTP client, and pool
+capacity match. See the [SDK pooling API](../CSharpDB.Client/README.md#shared-grpc-pooling).
+
+Each new physical client performs the existing `GetInfo` check. A warm logical
+open rents that client without a validation RPC. `Max Pool Size` (default 32)
+limits simultaneous leases per configuration; further opens wait and honor
+the `OpenAsync` cancellation token. Pools isolate endpoints, gRPC modes,
+routes, credentials, caller-supplied HTTP clients, and pool sizes.
+
+Closing a logical connection rolls back its unfinished transaction before
+returning the client. Failed or canceled RPCs discard the client; commands
+are never automatically replayed. Rollback on disposal has a five-second
+cleanup deadline. An unacknowledged rollback does not guarantee that the
+server released its transaction, and a warm open does not prove the server
+is reachable: the next RPC can still fail.
+
+Families with no active leases expire after two minutes of inactivity,
+checked every 30 seconds. `ClearPool`/`ClearPoolAsync` with a remote connection
+string retire all configurations for its endpoint; `ClearAllPools` also
+clears remote pools. Idle clients are disposed immediately, active leases
+are disposed on return, and blocked opens can join a new pool. Caller-owned
+`HttpClient` objects remain caller-owned.
+
+With the default unary call mode, API-key authentication occurs per RPC.
+Remote server-side prepared statement handles are not implemented.
+
+### Experimental persistent command sessions
+
+```text
+Transport=Grpc;Grpc Mode=Native;Grpc Call Mode=Streaming;Endpoint=http://127.0.0.1:5821;Pooling=true;Max Pool Size=32
+```
+
+This uses the SDK's experimental persistent native gRPC session for SQL,
+transactions, and `GetInfo`, with one command in flight per physical session.
+Authentication and protocol negotiation happen when the stream opens.
+SDK rentals and ADO.NET connections with matching options share that stream;
+unary and streaming call modes use separate pool families. Closing a
+connection resets its transactions before reuse. Active cancellation or a
+disconnect closes the stream and triggers server transaction cleanup;
+commands, including commits, are never replayed automatically. See the
+[SDK session guide](../CSharpDB.Client/README.md#experimental-persistent-command-sessions)
+for the protocol and failure behavior. Omit `Grpc Call Mode` to retain unary
+calls. Explicit `Grpc Mode=Native` is required for streaming.
For a daemon host, `Grpc` is the primary transport today:
@@ -180,7 +249,7 @@ Transport guidance:
- `Direct` with `Data Source=...` is still faster than any network hop when the caller can open the database locally
- `Grpc` is the fastest supported network transport in the current CSharpDB stack
- `NamedPipes` is not implemented end to end today, so do not target it yet for daemon-backed ADO.NET
-- for daemon-backed workloads, reuse open connections instead of reconnecting for each command
+- for daemon-backed workloads, reuse open connections or enable gRPC pooling for frequent open/close cycles
## In-Memory Connection Strings
diff --git a/src/CSharpDB.Data/RemoteDatabaseSession.cs b/src/CSharpDB.Data/RemoteDatabaseSession.cs
index cd32a5bb..ac3798d9 100644
--- a/src/CSharpDB.Data/RemoteDatabaseSession.cs
+++ b/src/CSharpDB.Data/RemoteDatabaseSession.cs
@@ -1,6 +1,8 @@
using System.Globalization;
+using System.Runtime.CompilerServices;
using System.Text.Json;
using CSharpDB.Client;
+using CSharpDB.Client.Internal;
using CSharpDB.Client.Models;
using CSharpDB.Execution;
using CSharpDB.Observability;
@@ -23,8 +25,8 @@ namespace CSharpDB.Data;
internal sealed class RemoteDatabaseSession : ICSharpDbSession
{
private ICSharpDbClient? _client;
- private readonly Func? _releaseAsync;
private string? _transactionId;
+ private bool _rollbackAttempted;
public bool SupportsStructuredExecution => false;
public CSharpDbObservabilityOptions? ObservabilityOptionsSnapshot => null;
@@ -34,12 +36,9 @@ internal sealed class RemoteDatabaseSession : ICSharpDbSession
public ICSharpDbObservabilityClient? RemoteObservabilityClient =>
Volatile.Read(ref _client) as ICSharpDbObservabilityClient;
- internal RemoteDatabaseSession(
- ICSharpDbClient client,
- Func? releaseAsync = null)
+ internal RemoteDatabaseSession(ICSharpDbClient client)
{
_client = client ?? throw new ArgumentNullException(nameof(client));
- _releaseAsync = releaseAsync;
}
public ValueTask ExecuteAsync(string sql, CancellationToken cancellationToken = default)
@@ -97,6 +96,7 @@ public async ValueTask BeginTransactionAsync(CancellationToken cancellationToken
TransactionSessionInfo info = await GetClient().BeginTransactionAsync(cancellationToken);
_transactionId = info.TransactionId;
+ _rollbackAttempted = false;
}
public async ValueTask CommitAsync(CancellationToken cancellationToken = default)
@@ -109,6 +109,7 @@ public async ValueTask CommitAsync(CancellationToken cancellationToken = default
public async ValueTask RollbackAsync(CancellationToken cancellationToken = default)
{
string transactionId = _transactionId ?? throw new InvalidOperationException("No transaction is active.");
+ _rollbackAttempted = true;
await GetClient().RollbackTransactionAsync(transactionId, cancellationToken);
_transactionId = null;
}
@@ -141,28 +142,100 @@ public IReadOnlyCollection GetTriggers()
public async ValueTask DisposeAsync()
{
- var client = _client;
- _client = null;
+ var client = Interlocked.Exchange(ref _client, null);
+ string? transactionId = _transactionId;
_transactionId = null;
if (client is not null)
{
- if (_releaseAsync is null)
- await client.DisposeAsync();
- else
- await _releaseAsync(client);
+ if (transactionId is not null && !_rollbackAttempted)
+ {
+ using var cleanup = new CancellationTokenSource(TimeSpan.FromSeconds(5));
+ try { await client.RollbackTransactionAsync(transactionId, cleanup.Token); }
+ catch { /* The SDK rental discards a connection after a failed RPC. */ }
+ }
+ await client.DisposeAsync();
}
}
private async ValueTask ExecuteSqlCoreAsync(string sql, CancellationToken cancellationToken)
{
- SqlExecutionResult result = _transactionId is null
- ? await GetClient().ExecuteSqlAsync(sql, cancellationToken)
- : await GetClient().ExecuteInTransactionAsync(_transactionId, sql, cancellationToken);
+ SqlExecutionResult result = await DispatchSqlAsync(sql, cancellationToken);
+ ThrowIfFailed(result);
+ return MaterializeResult(result);
+ }
+ /// Each returned ValueTask must be consumed exactly once.
+ [AsyncMethodBuilder(typeof(PoolingAsyncValueTaskMethodBuilder<>))]
+ internal async ValueTask ExecuteScalarAsync(string sql, CancellationToken cancellationToken)
+ {
+ SqlExecutionResult result;
+ if (GetClient() is IScalarProjectionClient { SupportsScalarProjection: true } scalarClient)
+ {
+ ScalarProjectionResult projected = await scalarClient.ExecuteScalarProjectionAsync(
+ sql, _transactionId, cancellationToken);
+ if (projected.HasCompactInt64)
+ {
+ DbValue value = DbValue.FromInteger(projected.Int64);
+ CoreSqlTypeKind? kind = projected.DeclaredType is { } declaredType
+ ? MapScalarSqlTypeKind(declaredType.Kind, declaredType.Length, declaredType.Precision,
+ declaredType.Scale, declaredType.FractionalSecondsPrecision)
+ : null;
+ cancellationToken.ThrowIfCancellationRequested();
+ return kind is CoreSqlTypeKind declaredKind
+ ? TypeMapper.GetClrValue(value, declaredKind)
+ : TypeMapper.GetClrValue(value);
+ }
+ // The transport already dispatched SQL. Consume its full response
+ // without issuing another command, including for older/wider results.
+ result = projected.Fallback
+ ?? throw new InvalidOperationException("The scalar projection did not return a result.");
+ }
+ else
+ {
+ result = await DispatchSqlAsync(sql, cancellationToken);
+ }
+ ThrowIfFailed(result);
+ // Preserve conversion/validation of unused cells for wider or older-server results.
+ // The narrow path uses this response's metadata and never resends the SQL.
+ if (result.IsQuery && result.ColumnNames is { Length: 1 } && result.Columns is { Length: 1 }
+ && result.Rows is { Count: 1 } && result.Rows[0] is { Length: 1 } row)
+ {
+ DbValue value = ToDbValue(row[0]);
+ CSharpDB.Client.Models.SqlTypeDescriptor? declaredType = result.Columns[0].DeclaredType;
+ CoreSqlTypeKind? kind = declaredType is null ? null : MapScalarSqlTypeKind(declaredType);
+ cancellationToken.ThrowIfCancellationRequested();
+ return kind is CoreSqlTypeKind declaredKind
+ ? TypeMapper.GetClrValue(value, declaredKind)
+ : TypeMapper.GetClrValue(value);
+ }
+
+ await using QueryResult materialized = MaterializeResult(result);
+ if (materialized.IsQuery && materialized.Schema.Length > 0
+ && await materialized.MoveNextAsync(cancellationToken))
+ {
+ CoreColumnDefinition column = materialized.Schema[0];
+ return column.DeclaredType is null
+ ? TypeMapper.GetClrValue(materialized.Current[0])
+ : TypeMapper.GetClrValue(materialized.Current[0], column.EffectiveType);
+ }
+
+ return null;
+ }
+
+ private Task DispatchSqlAsync(string sql, CancellationToken cancellationToken)
+ => _transactionId is null
+ ? GetClient().ExecuteSqlAsync(sql, cancellationToken)
+ : GetClient().ExecuteInTransactionAsync(_transactionId, sql, cancellationToken);
+
+ private static void ThrowIfFailed(SqlExecutionResult result)
+ {
if (!string.IsNullOrWhiteSpace(result.Error))
throw new CSharpDbException(ErrorCode.Unknown, result.Error);
+ }
+ private static QueryResult MaterializeResult(SqlExecutionResult result)
+ {
if (!result.IsQuery)
return new QueryResult(result.RowsAffected);
@@ -237,40 +310,63 @@ private static CoreColumnDefinition MapColumnDefinition(CSharpDB.Client.Models.C
private static CSharpDB.Primitives.SqlTypeDescriptor MapSqlTypeDescriptor(
CSharpDB.Client.Models.SqlTypeDescriptor type)
=> CSharpDB.Primitives.SqlTypeDescriptor.Create(
- type.Kind switch
- {
- CSharpDB.Client.Models.SqlTypeKind.Boolean => CSharpDB.Primitives.SqlTypeKind.Boolean,
- CSharpDB.Client.Models.SqlTypeKind.TinyInt => CSharpDB.Primitives.SqlTypeKind.TinyInt,
- CSharpDB.Client.Models.SqlTypeKind.SmallInt => CSharpDB.Primitives.SqlTypeKind.SmallInt,
- CSharpDB.Client.Models.SqlTypeKind.Integer => CSharpDB.Primitives.SqlTypeKind.Integer,
- CSharpDB.Client.Models.SqlTypeKind.BigInt => CSharpDB.Primitives.SqlTypeKind.BigInt,
- CSharpDB.Client.Models.SqlTypeKind.Real => CSharpDB.Primitives.SqlTypeKind.Real,
- CSharpDB.Client.Models.SqlTypeKind.Double => CSharpDB.Primitives.SqlTypeKind.Double,
- CSharpDB.Client.Models.SqlTypeKind.Decimal => CSharpDB.Primitives.SqlTypeKind.Decimal,
- CSharpDB.Client.Models.SqlTypeKind.Char => CSharpDB.Primitives.SqlTypeKind.Char,
- CSharpDB.Client.Models.SqlTypeKind.VarChar => CSharpDB.Primitives.SqlTypeKind.VarChar,
- CSharpDB.Client.Models.SqlTypeKind.Text => CSharpDB.Primitives.SqlTypeKind.Text,
- CSharpDB.Client.Models.SqlTypeKind.Binary => CSharpDB.Primitives.SqlTypeKind.Binary,
- CSharpDB.Client.Models.SqlTypeKind.VarBinary => CSharpDB.Primitives.SqlTypeKind.VarBinary,
- CSharpDB.Client.Models.SqlTypeKind.Blob => CSharpDB.Primitives.SqlTypeKind.Blob,
- CSharpDB.Client.Models.SqlTypeKind.Uuid => CSharpDB.Primitives.SqlTypeKind.Uuid,
- CSharpDB.Client.Models.SqlTypeKind.Date => CSharpDB.Primitives.SqlTypeKind.Date,
- CSharpDB.Client.Models.SqlTypeKind.Time => CSharpDB.Primitives.SqlTypeKind.Time,
- CSharpDB.Client.Models.SqlTypeKind.Timestamp => CSharpDB.Primitives.SqlTypeKind.Timestamp,
- CSharpDB.Client.Models.SqlTypeKind.TimestampWithTimeZone => CSharpDB.Primitives.SqlTypeKind.TimestampWithTimeZone,
- CSharpDB.Client.Models.SqlTypeKind.IntervalYearToMonth => CSharpDB.Primitives.SqlTypeKind.IntervalYearToMonth,
- CSharpDB.Client.Models.SqlTypeKind.IntervalDayToSecond => CSharpDB.Primitives.SqlTypeKind.IntervalDayToSecond,
- CSharpDB.Client.Models.SqlTypeKind.Json => CSharpDB.Primitives.SqlTypeKind.Json,
- CSharpDB.Client.Models.SqlTypeKind.Xml => CSharpDB.Primitives.SqlTypeKind.Xml,
- CSharpDB.Client.Models.SqlTypeKind.Bit => CSharpDB.Primitives.SqlTypeKind.Bit,
- CSharpDB.Client.Models.SqlTypeKind.VarBit => CSharpDB.Primitives.SqlTypeKind.VarBit,
- _ => throw new InvalidOperationException($"Unsupported logical SQL type '{type.Kind}'."),
- },
+ MapSqlTypeKind(type.Kind),
type.Length,
type.Precision,
type.Scale,
type.FractionalSecondsPrecision);
+ private static CoreSqlTypeKind MapScalarSqlTypeKind(CSharpDB.Client.Models.SqlTypeDescriptor type)
+ => MapScalarSqlTypeKind(type.Kind, type.Length, type.Precision,
+ type.Scale, type.FractionalSecondsPrecision);
+
+ private static CoreSqlTypeKind MapScalarSqlTypeKind(
+ CSharpDB.Client.Models.SqlTypeKind declaredKind, int? length, int? precision,
+ int? scale, int? fractionalSecondsPrecision)
+ {
+ CoreSqlTypeKind kind = MapSqlTypeKind(declaredKind);
+ // Every supported kind accepts absent facets. Keep the existing validator
+ // for any supplied facet, including zero, and run it before cancellation.
+ if (length.HasValue || precision.HasValue || scale.HasValue
+ || fractionalSecondsPrecision.HasValue)
+ {
+ _ = CoreSqlTypeDescriptor.Create(
+ kind, length, precision, scale, fractionalSecondsPrecision);
+ }
+ return kind;
+ }
+
+ private static CoreSqlTypeKind MapSqlTypeKind(CSharpDB.Client.Models.SqlTypeKind kind)
+ => kind switch
+ {
+ CSharpDB.Client.Models.SqlTypeKind.Boolean => CSharpDB.Primitives.SqlTypeKind.Boolean,
+ CSharpDB.Client.Models.SqlTypeKind.TinyInt => CSharpDB.Primitives.SqlTypeKind.TinyInt,
+ CSharpDB.Client.Models.SqlTypeKind.SmallInt => CSharpDB.Primitives.SqlTypeKind.SmallInt,
+ CSharpDB.Client.Models.SqlTypeKind.Integer => CSharpDB.Primitives.SqlTypeKind.Integer,
+ CSharpDB.Client.Models.SqlTypeKind.BigInt => CSharpDB.Primitives.SqlTypeKind.BigInt,
+ CSharpDB.Client.Models.SqlTypeKind.Real => CSharpDB.Primitives.SqlTypeKind.Real,
+ CSharpDB.Client.Models.SqlTypeKind.Double => CSharpDB.Primitives.SqlTypeKind.Double,
+ CSharpDB.Client.Models.SqlTypeKind.Decimal => CSharpDB.Primitives.SqlTypeKind.Decimal,
+ CSharpDB.Client.Models.SqlTypeKind.Char => CSharpDB.Primitives.SqlTypeKind.Char,
+ CSharpDB.Client.Models.SqlTypeKind.VarChar => CSharpDB.Primitives.SqlTypeKind.VarChar,
+ CSharpDB.Client.Models.SqlTypeKind.Text => CSharpDB.Primitives.SqlTypeKind.Text,
+ CSharpDB.Client.Models.SqlTypeKind.Binary => CSharpDB.Primitives.SqlTypeKind.Binary,
+ CSharpDB.Client.Models.SqlTypeKind.VarBinary => CSharpDB.Primitives.SqlTypeKind.VarBinary,
+ CSharpDB.Client.Models.SqlTypeKind.Blob => CSharpDB.Primitives.SqlTypeKind.Blob,
+ CSharpDB.Client.Models.SqlTypeKind.Uuid => CSharpDB.Primitives.SqlTypeKind.Uuid,
+ CSharpDB.Client.Models.SqlTypeKind.Date => CSharpDB.Primitives.SqlTypeKind.Date,
+ CSharpDB.Client.Models.SqlTypeKind.Time => CSharpDB.Primitives.SqlTypeKind.Time,
+ CSharpDB.Client.Models.SqlTypeKind.Timestamp => CSharpDB.Primitives.SqlTypeKind.Timestamp,
+ CSharpDB.Client.Models.SqlTypeKind.TimestampWithTimeZone => CSharpDB.Primitives.SqlTypeKind.TimestampWithTimeZone,
+ CSharpDB.Client.Models.SqlTypeKind.IntervalYearToMonth => CSharpDB.Primitives.SqlTypeKind.IntervalYearToMonth,
+ CSharpDB.Client.Models.SqlTypeKind.IntervalDayToSecond => CSharpDB.Primitives.SqlTypeKind.IntervalDayToSecond,
+ CSharpDB.Client.Models.SqlTypeKind.Json => CSharpDB.Primitives.SqlTypeKind.Json,
+ CSharpDB.Client.Models.SqlTypeKind.Xml => CSharpDB.Primitives.SqlTypeKind.Xml,
+ CSharpDB.Client.Models.SqlTypeKind.Bit => CSharpDB.Primitives.SqlTypeKind.Bit,
+ CSharpDB.Client.Models.SqlTypeKind.VarBit => CSharpDB.Primitives.SqlTypeKind.VarBit,
+ _ => throw new InvalidOperationException($"Unsupported logical SQL type '{kind}'."),
+ };
+
private static CoreForeignKeyDefinition MapForeignKeyDefinition(CSharpDB.Client.Models.ForeignKeyDefinition foreignKey)
=> new()
{
diff --git a/src/CSharpDB.Data/TypeMapper.cs b/src/CSharpDB.Data/TypeMapper.cs
index eca58308..a257f2bb 100644
--- a/src/CSharpDB.Data/TypeMapper.cs
+++ b/src/CSharpDB.Data/TypeMapper.cs
@@ -117,7 +117,15 @@ public static object GetClrValue(DbValue value, SqlTypeDescriptor type)
if (value.IsNull)
return DBNull.Value;
- return type.Kind switch
+ return GetClrValue(value, type.Kind);
+ }
+
+ internal static object GetClrValue(DbValue value, SqlTypeKind kind)
+ {
+ if (value.IsNull)
+ return DBNull.Value;
+
+ return kind switch
{
SqlTypeKind.Boolean => value.AsInteger != 0,
SqlTypeKind.TinyInt => checked((byte)value.AsInteger),
diff --git a/src/CSharpDB.Engine/Database.cs b/src/CSharpDB.Engine/Database.cs
index 322ff10f..7f3fad00 100644
--- a/src/CSharpDB.Engine/Database.cs
+++ b/src/CSharpDB.Engine/Database.cs
@@ -119,6 +119,7 @@ public ImplicitInsertExecutionMode ImplicitInsertExecutionMode
}
public int ActiveReaderCount => _pager.ActiveReaderCount;
+ internal int ActiveQueryReaderCount => _pager.ActiveQueryReaderCount;
internal bool IsObservabilityEnabled => _observabilityOptions is not null;
@@ -2544,26 +2545,17 @@ private Dictionary CaptureSnapshotRowCounts()
internal IDisposable EnterTemporaryTableSessionScope(object sessionKey) =>
_temporaryTables.EnterSessionScope(sessionKey);
+ // Preserve hybrid Dispose-trigger persistence at a logical client boundary
+ // without closing the shared database while other transactions own it.
+ internal ValueTask PersistClientSessionBoundaryAsync() =>
+ PersistHybridStateAsync(HybridPersistenceTriggers.Dispose, CancellationToken.None);
+
internal bool HasTemporaryTablesForCurrentSession =>
_temporaryTables.GetTableNames().Count != 0;
internal bool HasTemporaryTableContextForCurrentSession =>
_temporaryTables.HasCurrentSessionContext;
- internal async ValueTask ResetReusableSessionStateAsync()
- {
- if (_inTransaction || _explicitTransactionFailed)
- throw new InvalidOperationException("Cannot reuse a database handle with an active or failed transaction.");
- if (ActiveReaderCount != 0)
- throw new InvalidOperationException("Cannot reuse a database handle while snapshot readers are active.");
-
- // A physical close flushes deferred catalog state and destroys every
- // temporary-table context. Warm handle handoff must preserve that
- // boundary before the handle changes logical owners.
- await FlushPendingAdvisoryStatisticsAsync(CancellationToken.None);
- await _temporaryTables.ClearAsync();
- }
-
internal uint GetTableRootPage(string tableName) => _catalog.GetTableRootPage(tableName);
///
@@ -2840,8 +2832,10 @@ public async ValueTask> SearchAsync(
/// Whether table CHECK expressions can invoke registered host callbacks during an update.
public bool HasUpdateHostCallbacks(string tableName)
+ => HasUpdateHostCallbacks(GetTableSchema(tableName));
+
+ internal bool HasUpdateHostCallbacks(TableSchema? schema)
{
- var schema = GetTableSchema(tableName);
if (schema is null) return true;
foreach (var check in schema.CheckConstraints)
{
diff --git a/src/CSharpDB.Engine/WriteTransaction.cs b/src/CSharpDB.Engine/WriteTransaction.cs
index 2932f57b..50186c04 100644
--- a/src/CSharpDB.Engine/WriteTransaction.cs
+++ b/src/CSharpDB.Engine/WriteTransaction.cs
@@ -20,6 +20,7 @@ public sealed class WriteTransaction : IAsyncDisposable
private readonly LifecycleOperation? _lifecycleOperation;
private bool _completed;
private bool _writeFailed;
+ private object? _temporaryTableSessionKey;
internal WriteTransaction(
Database database,
@@ -39,6 +40,89 @@ internal WriteTransaction(
_lifecycleOperation = lifecycleOperation;
}
+ // Client sessions share the database owner but have private temporary tables.
+ // Deferred query iteration must enter this scope along with the pager binding.
+ internal void SetTemporaryTableSession(object sessionKey)
+ => _temporaryTableSessionKey = sessionKey;
+
+ private IDisposable BindExecution()
+ => BindExecution(_storageTransaction.Bind());
+
+ private IDisposable BindSnapshotExecution()
+ => BindExecution(_storageTransaction.BindSnapshotRead());
+
+ private IDisposable BindExecution(IDisposable binding)
+ {
+ if (_temporaryTableSessionKey is null)
+ return binding;
+ try
+ {
+ return new SessionBinding(binding,
+ _database.EnterTemporaryTableSessionScope(_temporaryTableSessionKey));
+ }
+ catch
+ {
+ binding.Dispose();
+ throw;
+ }
+ }
+
+ private sealed class SessionBinding(IDisposable binding, IDisposable sessionScope) : IDisposable
+ {
+ public void Dispose()
+ {
+ try { sessionScope.Dispose(); }
+ finally { binding.Dispose(); }
+ }
+ }
+
+ internal TableSchema? GetTableSchema(string tableName)
+ {
+ EnsureActive();
+ using var scope = BindExecution();
+ TableSchema? schema = _catalog.GetTable(tableName);
+ if (schema is null)
+ return null;
+ long nextRowId = schema.NextRowId;
+ foreach (var hint in _planner.GetCommittedNextRowIdHints())
+ if (string.Equals(hint.Key, tableName, StringComparison.OrdinalIgnoreCase))
+ nextRowId = Math.Max(nextRowId, hint.Value);
+ return new TableSchema
+ {
+ SchemaId = schema.SchemaId,
+ TableName = schema.TableName,
+ Columns = schema.Columns,
+ ForeignKeys = schema.ForeignKeys,
+ CheckConstraints = schema.CheckConstraints,
+ KeyConstraints = schema.KeyConstraints,
+ QualifiedMappings = schema.QualifiedMappings,
+ NextRowId = nextRowId,
+ };
+ }
+
+ internal IReadOnlyCollection GetIndexes() => _catalog.GetIndexes();
+ internal IReadOnlyCollection GetTriggers() => _catalog.GetTriggers();
+ internal bool HasUpdateHostCallbacks(string tableName)
+ => _database.HasUpdateHostCallbacks(GetTableSchema(tableName));
+
+ internal async ValueTask ApplyTableSchemaIdentitiesAsync(
+ string tableName, TableSchema identitySource, CancellationToken ct)
+ {
+ EnsureActive();
+ EnsureWriteAllowed();
+ try
+ {
+ using var scope = BindExecution();
+ await _storageTransaction.AcquireSchemaWriteLockAsync(ct);
+ await _catalog.ApplyTableSchemaIdentitiesAsync(tableName, identitySource, ct);
+ }
+ catch
+ {
+ _writeFailed = true;
+ throw;
+ }
+ }
+
///
/// Execute SQL within this transaction.
///
@@ -64,7 +148,7 @@ private async ValueTask ExecuteSqlCoreAsync(string sql, Cancellatio
Statement statement = Parser.TryParseSimpleSelect(sql, out var simpleSelect)
? simpleSelect
: Parser.Parse(sql);
- return await ExecuteAsyncCore(statement, _storageTransaction.Bind, ct);
+ return await ExecuteAsyncCore(statement, BindExecution, ct);
}
///
@@ -91,7 +175,7 @@ private async ValueTask ExecuteStatementRootCoreAsync(
ArgumentNullException.ThrowIfNull(statement);
EnsureActive();
- return await ExecuteAsyncCore(statement, _storageTransaction.Bind, ct);
+ return await ExecuteAsyncCore(statement, BindExecution, ct);
}
internal async ValueTask ExecuteImplicitAutoCommitAsync(Statement statement, CancellationToken ct = default)
@@ -138,7 +222,7 @@ private async ValueTask ExecuteSnapshotReadSqlCoreAsync(
if (!classification.IsReadOnly)
throw new InvalidOperationException("Snapshot-read execution only supports read-only statements.");
- return await ExecuteAsyncCore(classification.Statement, _storageTransaction.BindSnapshotRead, ct);
+ return await ExecuteAsyncCore(classification.Statement, BindSnapshotExecution, ct);
}
///
@@ -169,7 +253,7 @@ private async ValueTask ExecuteSnapshotReadStatementCoreAsync(
if (!SqlStatementClassifier.IsReadOnly(statement))
throw new InvalidOperationException("Snapshot-read execution only supports read-only statements.");
- return await ExecuteAsyncCore(statement, _storageTransaction.BindSnapshotRead, ct);
+ return await ExecuteAsyncCore(statement, BindSnapshotExecution, ct);
}
///
@@ -315,10 +399,17 @@ private async ValueTask RollbackCoreAsync(CancellationToken ct)
public async ValueTask DisposeAsync()
{
- if (_completed)
- return;
-
- await RollbackAsync();
+ try
+ {
+ if (!_completed)
+ await RollbackAsync();
+ }
+ finally
+ {
+ // Catalog preparation can fail before commit begins. Always release
+ // the storage transaction even when the logical transaction ended.
+ await _storageTransaction.DisposeAsync();
+ }
}
private void EnsureActive()
diff --git a/src/CSharpDB.Execution/QueryPlanner.cs b/src/CSharpDB.Execution/QueryPlanner.cs
index 6b41dcba..55ac67b3 100644
--- a/src/CSharpDB.Execution/QueryPlanner.cs
+++ b/src/CSharpDB.Execution/QueryPlanner.cs
@@ -1138,12 +1138,16 @@ private async ValueTask ExecuteCoreAsync(Statement stmt, Cancellati
return stmt switch
{
ConditionalStatement conditional => await ExecuteConditionalAsync(conditional, ct),
+ CreateTableStatement { IsTemporary: true } createTemporary =>
+ await ExecuteCreateTableAsync(createTemporary, ct),
CreateTableStatement create => await ExecuteSchemaMutationAsync(
token => ExecuteCreateTableAsync(create, token),
ct),
CreateExternalTableStatement createExternal => await ExecuteSchemaMutationAsync(
token => ExecuteCreateExternalTableAsync(createExternal, token),
ct),
+ DropTableStatement dropTemporary when dropTemporary.IsTemporary || HasTemporaryTable(dropTemporary.TableName) =>
+ await ExecuteDropTableAsync(dropTemporary, ct),
DropTableStatement drop => await ExecuteSchemaMutationAsync(
token => ExecuteDropTableAsync(drop, token),
ct),
diff --git a/src/CSharpDB.ImportExport/Serialization/TableArchiveJson.cs b/src/CSharpDB.ImportExport/Serialization/TableArchiveJson.cs
index df753f55..8123c515 100644
--- a/src/CSharpDB.ImportExport/Serialization/TableArchiveJson.cs
+++ b/src/CSharpDB.ImportExport/Serialization/TableArchiveJson.cs
@@ -1,19 +1,23 @@
using System.Text.Json;
using System.Text.Json.Serialization;
+using CSharpDB.Primitives;
namespace CSharpDB.ImportExport.Serialization;
internal static class TableArchiveJson
{
- public static readonly JsonSerializerOptions Options = new()
+ private static readonly JsonSerializerOptions Options = new()
{
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
WriteIndented = true,
Converters =
{
- new JsonStringEnumConverter(
- JsonNamingPolicy.CamelCase,
- allowIntegerValues: false),
+ new JsonStringEnumConverter(JsonNamingPolicy.CamelCase, allowIntegerValues: false),
+ new JsonStringEnumConverter(JsonNamingPolicy.CamelCase, allowIntegerValues: false),
+ new JsonStringEnumConverter(JsonNamingPolicy.CamelCase, allowIntegerValues: false),
+ new JsonStringEnumConverter(JsonNamingPolicy.CamelCase, allowIntegerValues: false),
},
};
+
+ public static TableArchiveJsonContext Context { get; } = new(Options);
}
diff --git a/src/CSharpDB.ImportExport/Serialization/TableArchiveJsonContext.cs b/src/CSharpDB.ImportExport/Serialization/TableArchiveJsonContext.cs
new file mode 100644
index 00000000..40cf17ee
--- /dev/null
+++ b/src/CSharpDB.ImportExport/Serialization/TableArchiveJsonContext.cs
@@ -0,0 +1,13 @@
+using System.Text.Json.Serialization;
+using CSharpDB.ImportExport.Models;
+
+namespace CSharpDB.ImportExport.Serialization;
+
+[JsonSourceGenerationOptions(GenerationMode = JsonSourceGenerationMode.Metadata)]
+[JsonSerializable(typeof(TableArchiveSchema))]
+[JsonSerializable(typeof(TableArchiveManifest))]
+[JsonSerializable(typeof(TableArchiveSchemaDocument))]
+[JsonSerializable(typeof(TableArchiveManifestDocument))]
+internal partial class TableArchiveJsonContext : JsonSerializerContext
+{
+}
diff --git a/src/CSharpDB.ImportExport/Serialization/TableArchiveReadDocuments.cs b/src/CSharpDB.ImportExport/Serialization/TableArchiveReadDocuments.cs
new file mode 100644
index 00000000..b948c746
--- /dev/null
+++ b/src/CSharpDB.ImportExport/Serialization/TableArchiveReadDocuments.cs
@@ -0,0 +1,129 @@
+using System.Text.Json.Serialization;
+using CSharpDB.ImportExport.Models;
+using CSharpDB.Primitives;
+
+namespace CSharpDB.ImportExport.Serialization;
+
+// Generated constructors for required/init-only models can overwrite property
+// initializers when JSON omits additive fields. Mutable read documents preserve
+// those legacy defaults, while explicit null still reaches normal validation.
+internal sealed class TableArchiveSchemaDocument
+{
+ public Guid SchemaId { get; set; }
+ [JsonRequired] public string TableName { get; set; } = null!;
+ [JsonRequired] public IReadOnlyList Columns { get; set; } = null!;
+ public IReadOnlyList ForeignKeys { get; set; } = [];
+ public IReadOnlyList CheckConstraints { get; set; } = [];
+ public IReadOnlyList KeyConstraints { get; set; } = [];
+ public IReadOnlyList? SecondaryIndexes { get; set; }
+ public long NextRowId { get; set; }
+
+ public TableArchiveSchema ToModel() => new()
+ {
+ SchemaId = SchemaId, TableName = TableName, Columns = Columns,
+ ForeignKeys = TableArchiveReadDocuments.Map(ForeignKeys, static item => item.ToModel()),
+ CheckConstraints = CheckConstraints, KeyConstraints = KeyConstraints,
+ SecondaryIndexes = TableArchiveReadDocuments.Map(SecondaryIndexes, static item => item.ToModel()),
+ NextRowId = NextRowId,
+ };
+}
+
+internal sealed class TableArchiveForeignKeyDocument
+{
+ public Guid SchemaId { get; set; }
+ public IReadOnlyList ColumnSchemaIds { get; set; } = [];
+ public Guid ReferencedTableSchemaId { get; set; }
+ public IReadOnlyList ReferencedColumnSchemaIds { get; set; } = [];
+ public Guid ReferencedKeySchemaId { get; set; }
+ [JsonRequired] public string ConstraintName { get; set; } = null!;
+ [JsonRequired] public string ColumnName { get; set; } = null!;
+ [JsonRequired] public string ReferencedTableName { get; set; } = null!;
+ [JsonRequired] public string ReferencedColumnName { get; set; } = null!;
+ public IReadOnlyList ColumnNames { get; set; } = [];
+ public IReadOnlyList ReferencedColumnNames { get; set; } = [];
+ public ForeignKeyOnDeleteAction OnDelete { get; set; }
+ public ForeignKeyOnDeleteAction OnUpdate { get; set; }
+ [JsonRequired] public string SupportingIndexName { get; set; } = null!;
+
+ public TableArchiveForeignKey ToModel() => new()
+ {
+ SchemaId = SchemaId, ColumnSchemaIds = ColumnSchemaIds,
+ ReferencedTableSchemaId = ReferencedTableSchemaId, ReferencedColumnSchemaIds = ReferencedColumnSchemaIds,
+ ReferencedKeySchemaId = ReferencedKeySchemaId, ConstraintName = ConstraintName,
+ ColumnName = ColumnName, ReferencedTableName = ReferencedTableName,
+ ReferencedColumnName = ReferencedColumnName, ColumnNames = ColumnNames,
+ ReferencedColumnNames = ReferencedColumnNames, OnDelete = OnDelete, OnUpdate = OnUpdate,
+ SupportingIndexName = SupportingIndexName,
+ };
+}
+
+internal sealed class TableArchiveSecondaryIndexDocument
+{
+ [JsonRequired] public string Name { get; set; } = null!;
+ [JsonRequired] public IReadOnlyList Columns { get; set; } = null!;
+ public IReadOnlyList ColumnCollations { get; set; } = [];
+ public bool IsUnique { get; set; }
+
+ public TableArchiveSecondaryIndex ToModel() => new()
+ {
+ Name = Name, Columns = Columns, ColumnCollations = ColumnCollations, IsUnique = IsUnique,
+ };
+}
+
+internal sealed class TableArchiveManifestDocument
+{
+ public int FormatVersion { get; set; } = TableArchiveManifest.LatestFormatVersion;
+ [JsonRequired] public string SourceTableName { get; set; } = null!;
+ public DateTimeOffset CreatedUtc { get; set; } = DateTimeOffset.UtcNow;
+ public long RowCount { get; set; }
+ public string SchemaEntry { get; set; } = "native:schema";
+ public string RowsEntry { get; set; } = "native:rows";
+ public IReadOnlyList Indexes { get; set; } = [];
+ public TableArchiveDigestsDocument? Digests { get; set; }
+
+ public TableArchiveManifest ToModel() => new()
+ {
+ FormatVersion = FormatVersion, SourceTableName = SourceTableName, CreatedUtc = CreatedUtc,
+ RowCount = RowCount, SchemaEntry = SchemaEntry, RowsEntry = RowsEntry,
+ Indexes = TableArchiveReadDocuments.Map(Indexes, static item => item.ToModel()),
+ Digests = Digests?.ToModel(),
+ };
+}
+
+internal sealed class TableArchiveIndexDocument
+{
+ [JsonRequired] public string Name { get; set; } = null!;
+ [JsonRequired] public string Kind { get; set; } = null!;
+ [JsonRequired] public string ColumnName { get; set; } = null!;
+ public int ColumnIndex { get; set; }
+ public long EntryCount { get; set; }
+ public string SectionEntry { get; set; } = "native:index:primary-key";
+
+ public TableArchiveIndexManifest ToModel() => new()
+ {
+ Name = Name, Kind = Kind, ColumnName = ColumnName, ColumnIndex = ColumnIndex,
+ EntryCount = EntryCount, SectionEntry = SectionEntry,
+ };
+}
+
+internal sealed class TableArchiveDigestsDocument
+{
+ public string Algorithm { get; set; } = TableArchiveSectionDigests.Sha256Algorithm;
+ public string Encoding { get; set; } = TableArchiveSectionDigests.LowercaseHexEncoding;
+ [JsonRequired] public string Schema { get; set; } = null!;
+ [JsonRequired] public string Rows { get; set; } = null!;
+ [JsonRequired] public string PhysicalIndex { get; set; } = null!;
+
+ public TableArchiveSectionDigests ToModel() => new()
+ {
+ Algorithm = Algorithm, Encoding = Encoding, Schema = Schema, Rows = Rows, PhysicalIndex = PhysicalIndex,
+ };
+}
+
+internal static class TableArchiveReadDocuments
+{
+ internal static IReadOnlyList Map(
+ IReadOnlyList? items, Func convert)
+ where TDocument : class where TModel : class
+ => items?.Select(item => item is null ? null! : convert(item)).ToArray()!;
+}
diff --git a/src/CSharpDB.ImportExport/TableArchives/TableArchiveReader.cs b/src/CSharpDB.ImportExport/TableArchives/TableArchiveReader.cs
index 5431c191..a1f6e2d7 100644
--- a/src/CSharpDB.ImportExport/TableArchives/TableArchiveReader.cs
+++ b/src/CSharpDB.ImportExport/TableArchives/TableArchiveReader.cs
@@ -272,7 +272,7 @@ private static async ValueTask ReadNativeSchemaAsync(
{
byte[] bytes = await ReadSectionAsync(stream, header.SchemaOffset, header.SchemaLength, ct);
TableArchiveSchema schema =
- JsonSerializer.Deserialize(bytes, TableArchiveJson.Options)
+ JsonSerializer.Deserialize(bytes, TableArchiveJson.Context.TableArchiveSchemaDocument)?.ToModel()
?? throw new InvalidDataException("The table archive schema is empty.");
if (schema.Columns is null)
throw new InvalidDataException("The table archive schema columns collection is null.");
@@ -319,7 +319,7 @@ private static async ValueTask ReadNativeManifestAsync(
CancellationToken ct)
{
byte[] bytes = await ReadSectionAsync(stream, header.ManifestOffset, header.ManifestLength, ct);
- var manifest = JsonSerializer.Deserialize(bytes, TableArchiveJson.Options)
+ var manifest = JsonSerializer.Deserialize(bytes, TableArchiveJson.Context.TableArchiveManifestDocument)?.ToModel()
?? throw new InvalidDataException("The table archive manifest is empty.");
if (manifest.FormatVersion is not (
TableArchiveManifest.CurrentFormatVersion or
diff --git a/src/CSharpDB.ImportExport/TableArchives/TableArchiveWriter.cs b/src/CSharpDB.ImportExport/TableArchives/TableArchiveWriter.cs
index 2869abc8..d73a8df6 100644
--- a/src/CSharpDB.ImportExport/TableArchives/TableArchiveWriter.cs
+++ b/src/CSharpDB.ImportExport/TableArchives/TableArchiveWriter.cs
@@ -129,7 +129,7 @@ private static async ValueTask WriteNativeAsync(
TableArchiveSchema archiveSchema = TableArchiveSchema.FromTableSchema(schema, secondaryIndexes);
byte[] schemaBytes = JsonSerializer.SerializeToUtf8Bytes(
archiveSchema,
- TableArchiveJson.Options);
+ TableArchiveJson.Context.TableArchiveSchema);
await destination.WriteAsync(schemaBytes, ct);
string schemaDigest = EncodeDigest(SHA256.HashData(schemaBytes));
@@ -220,7 +220,7 @@ private static async ValueTask WriteNativeAsync(
},
};
long manifestOffset = destination.Position;
- byte[] manifestBytes = JsonSerializer.SerializeToUtf8Bytes(manifest, TableArchiveJson.Options);
+ byte[] manifestBytes = JsonSerializer.SerializeToUtf8Bytes(manifest, TableArchiveJson.Context.TableArchiveManifest);
await destination.WriteAsync(manifestBytes, ct);
destination.Position = 0;
diff --git a/src/CSharpDB.Migration.SqlServer/CSharpDB.Migration.SqlServer.csproj b/src/CSharpDB.Migration.SqlServer/CSharpDB.Migration.SqlServer.csproj
index 5987843d..fc28859d 100644
--- a/src/CSharpDB.Migration.SqlServer/CSharpDB.Migration.SqlServer.csproj
+++ b/src/CSharpDB.Migration.SqlServer/CSharpDB.Migration.SqlServer.csproj
@@ -16,6 +16,8 @@
+
+
diff --git a/src/CSharpDB.Migration.SqlServer/THIRD-PARTY-NOTICES.md b/src/CSharpDB.Migration.SqlServer/THIRD-PARTY-NOTICES.md
index 3d1ddff0..1e863f37 100644
--- a/src/CSharpDB.Migration.SqlServer/THIRD-PARTY-NOTICES.md
+++ b/src/CSharpDB.Migration.SqlServer/THIRD-PARTY-NOTICES.md
@@ -30,7 +30,7 @@ Microsoft Software License Terms included at
| System.Configuration.ConfigurationManager | 9.0.18 | MIT |
| System.Diagnostics.EventLog | 9.0.18 | MIT |
| System.IdentityModel.Tokens.Jwt | 8.16.0 | MIT |
-| System.Security.Cryptography.Pkcs | 9.0.18 | MIT |
+| System.Security.Cryptography.Pkcs | 9.0.22 | MIT |
| System.Security.Cryptography.ProtectedData | 9.0.18 | MIT |
| System.Threading.RateLimiting | 9.0.18 | MIT |
diff --git a/src/CSharpDB.Migration/MigrationRejectArtifactPublication.cs b/src/CSharpDB.Migration/MigrationRejectArtifactPublication.cs
index 8e43642c..f4dfe06e 100644
--- a/src/CSharpDB.Migration/MigrationRejectArtifactPublication.cs
+++ b/src/CSharpDB.Migration/MigrationRejectArtifactPublication.cs
@@ -1267,10 +1267,11 @@ private static bool IsAbsentLinuxAclAttribute(
return false;
}
- // ext2/3/4 enforce uid and mode bits. EOPNOTSUPP therefore means the
+ // ext2/3/4 and tmpfs enforce uid and mode bits. EOPNOTSUPP means the
// queried optional NFSv4/richacl family is not implemented, not that
// an unverified access policy was accepted.
- return unchecked((ulong)(long)status.Type) == LinuxExtFileSystem;
+ ulong fileSystem = unchecked((ulong)(long)status.Type);
+ return fileSystem is LinuxExtFileSystem or LinuxTmpFileSystem;
}
private static void RequireUnixTemporaryIdentity(
@@ -1571,6 +1572,7 @@ private sealed record DestinationBinding(
private const int UnixAtEmptyPath = 0x1000;
private const uint LinuxStatxHardLinkCount = 0x0004;
private const ulong LinuxExtFileSystem = 0x0000EF53;
+ private const ulong LinuxTmpFileSystem = 0x01021994;
private const int LinuxNoExtendedAttribute = 61;
private const int LinuxOperationNotSupported = 95;
private const int DarwinNoEntry = 2;
diff --git a/src/CSharpDB.Storage/Paging/Pager.cs b/src/CSharpDB.Storage/Paging/Pager.cs
index ed1a0461..0b0c2ab7 100644
--- a/src/CSharpDB.Storage/Paging/Pager.cs
+++ b/src/CSharpDB.Storage/Paging/Pager.cs
@@ -233,6 +233,10 @@ private set
}
public int ActiveReaderCount => _checkpoints?.ActiveReaderCount ?? 0;
+ // Writer snapshots pin WAL history but are not client query readers.
+ internal int ActiveQueryReaderCount => Math.Max(0,
+ ActiveReaderCount - (_transactions?.ActiveExplicitTransactionCount ?? 0));
+
internal bool TryGetRuntimeDiagnosticsSnapshot(out PagerRuntimeRawSnapshot snapshot)
{
snapshot = default;
diff --git a/src/CSharpDB.Storage/Transactions/PagerWriteTransaction.cs b/src/CSharpDB.Storage/Transactions/PagerWriteTransaction.cs
index 431e26d6..e8a2b25c 100644
--- a/src/CSharpDB.Storage/Transactions/PagerWriteTransaction.cs
+++ b/src/CSharpDB.Storage/Transactions/PagerWriteTransaction.cs
@@ -16,6 +16,9 @@ internal PagerWriteTransaction(Pager pager, PagerTransactionState state)
internal IDisposable Bind() => _pager.BindTransaction(_state);
+ internal ValueTask AcquireSchemaWriteLockAsync(CancellationToken ct)
+ => _pager.AcquireSchemaWriteLockAsync(ct);
+
internal IDisposable BindSnapshotRead()
=> new CombinedBinding(Bind(), _pager.SuppressLogicalReadTracking());
diff --git a/src/CSharpDB.Storage/Transactions/TransactionCoordinator.cs b/src/CSharpDB.Storage/Transactions/TransactionCoordinator.cs
index 11aa7b64..e25dfc7e 100644
--- a/src/CSharpDB.Storage/Transactions/TransactionCoordinator.cs
+++ b/src/CSharpDB.Storage/Transactions/TransactionCoordinator.cs
@@ -41,6 +41,11 @@ internal sealed class TransactionCoordinator : IDisposable
internal int ActiveWriterCount => GetRuntimeStateSnapshot().ActiveWriterCount;
+ internal int ActiveExplicitTransactionCount
+ {
+ get { lock (_stateGate) return _activeExplicitTransactions.Count; }
+ }
+
internal (
int ActiveWriterCount,
bool HasActiveExplicitWriters,
diff --git a/src/Directory.Build.props b/src/Directory.Build.props
index 3d71cabc..99492199 100644
--- a/src/Directory.Build.props
+++ b/src/Directory.Build.props
@@ -11,7 +11,7 @@
README.md
icon.png
en
- 4.6.6
+ 4.7.0
diff --git a/tests/CSharpDB.Daemon.Tests/CSharpDB.Daemon.Tests.csproj b/tests/CSharpDB.Daemon.Tests/CSharpDB.Daemon.Tests.csproj
index 7cd88553..01ad6de9 100644
--- a/tests/CSharpDB.Daemon.Tests/CSharpDB.Daemon.Tests.csproj
+++ b/tests/CSharpDB.Daemon.Tests/CSharpDB.Daemon.Tests.csproj
@@ -27,6 +27,7 @@
+
diff --git a/tests/CSharpDB.Daemon.Tests/DirectStreamingDispatchTests.cs b/tests/CSharpDB.Daemon.Tests/DirectStreamingDispatchTests.cs
new file mode 100644
index 00000000..084b0b8e
--- /dev/null
+++ b/tests/CSharpDB.Daemon.Tests/DirectStreamingDispatchTests.cs
@@ -0,0 +1,234 @@
+using System.Collections.Concurrent;
+using System.Reflection;
+using System.Runtime.ExceptionServices;
+using CSharpDB.Client;
+using CSharpDB.Client.Models;
+using CSharpDB.Testing;
+using Grpc.Core;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+using CoreException = CSharpDB.Primitives.CSharpDbException;
+using CoreError = CSharpDB.Primitives.ErrorCode;
+
+namespace CSharpDB.Daemon.Tests;
+
+public sealed class DirectStreamingDispatchTests
+{
+ [Fact(Timeout = 30000)]
+ public async Task Disposal_DrainsStreamAndUnaryCalls_BeforeRollbackAndReuse()
+ {
+ var ct = TestContext.Current.CancellationToken;
+ var control = new Control { HoldSql = "INSERT INTO dispatch_drain VALUES (1)", HoldMetadata = true };
+ await using var host = Host(control);
+ var options = Options(host);
+ ICSharpDbClient? first = null;
+ try
+ {
+ first = await CSharpDbClient.RentAsync(options, 1, ct);
+ Assert.Null((await first.ExecuteSqlAsync("CREATE TABLE dispatch_drain (id INTEGER PRIMARY KEY)", ct)).Error);
+ string id = (await first.BeginTransactionAsync(ct)).TransactionId;
+ var direct = first.ExecuteInTransactionAsync(id, control.HoldSql!, ct);
+ await control.SqlEntered.Task.WaitAsync(TimeSpan.FromSeconds(5), ct);
+ var unary = first.GetTableNamesAsync(ct);
+ await control.MetadataEntered.Task.WaitAsync(TimeSpan.FromSeconds(5), ct);
+ Task disposed = first.DisposeAsync().AsTask();
+ Assert.Same(disposed, first.DisposeAsync().AsTask());
+ Task waiting = CSharpDbClient.RentAsync(options, 1, ct).AsTask();
+ Assert.False(disposed.IsCompleted);
+ Assert.False(waiting.IsCompleted);
+ control.SqlRelease.TrySetResult();
+ Assert.Null((await direct.WaitAsync(TimeSpan.FromSeconds(5), ct)).Error);
+ Assert.False(disposed.IsCompleted);
+ Assert.False(waiting.IsCompleted);
+ Assert.Equal(0, control.Count(nameof(ICSharpDbClient.RollbackTransactionAsync)));
+ control.MetadataRelease.TrySetResult();
+ Assert.Contains("dispatch_drain", await unary.WaitAsync(TimeSpan.FromSeconds(5), ct));
+ await disposed.WaitAsync(TimeSpan.FromSeconds(5), ct);
+ await using var next = await waiting.WaitAsync(TimeSpan.FromSeconds(5), ct);
+ Assert.Equal(1, control.Count(nameof(ICSharpDbClient.RollbackTransactionAsync)));
+ Assert.Equal(0L, (await next.ExecuteSqlAsync("SELECT COUNT(*) FROM dispatch_drain", ct)).Rows![0][0]);
+ Assert.Equal(1, HttpCount(host, "CommandSession"));
+
+ // Both the direct stream methods and unary admin methods must still
+ // pass the same disposed-rental guard after its owner is reused.
+ var before = host.Snapshot().ToDictionary();
+ await Assert.ThrowsAsync(() => first.ExecuteSqlAsync("SELECT 42", ct));
+ await Assert.ThrowsAsync(() => first.GetInfoAsync(ct));
+ await Assert.ThrowsAsync(() => first.CommitTransactionAsync(id, ct));
+ await Assert.ThrowsAsync(() => first.GetMaintenanceReportAsync(ct));
+ Assert.Equal(before.OrderBy(x => x.Key.Method), host.Snapshot().OrderBy(x => x.Key.Method));
+ Assert.Equal(42L, (await next.ExecuteSqlAsync("SELECT 42", ct)).Rows![0][0]);
+ }
+ finally
+ {
+ control.ReleaseAll();
+ if (first is not null) await first.DisposeAsync();
+ await CSharpDbClient.ClearPoolAsync(host.NativeEndpoint.AbsoluteUri);
+ }
+ }
+
+ [Fact(Timeout = 30000)]
+ public async Task ForeignTransactionChecks_RemainLocal_WhileUnaryCallIsActive()
+ {
+ var ct = TestContext.Current.CancellationToken;
+ var control = new Control { HoldMetadata = true };
+ await using var host = Host(control);
+ try
+ {
+ await using var owner = await CSharpDbClient.RentAsync(Options(host), 2, ct);
+ await using var other = await CSharpDbClient.RentAsync(Options(host), 2, ct);
+ string id = (await owner.BeginTransactionAsync(ct)).TransactionId;
+ var unary = owner.GetTableNamesAsync(ct);
+ await control.MetadataEntered.Task.WaitAsync(TimeSpan.FromSeconds(5), ct);
+ try
+ {
+ await Assert.ThrowsAsync(() => other.ExecuteInTransactionAsync(id, "SELECT 42", ct));
+ await Assert.ThrowsAsync(() => other.CommitTransactionAsync(id, ct));
+ await Assert.ThrowsAsync(() => other.RollbackTransactionAsync(id, ct));
+ Assert.Equal(0, control.Count(nameof(ICSharpDbClient.ExecuteInTransactionAsync)));
+ Assert.Equal(0, control.Count(nameof(ICSharpDbClient.CommitTransactionAsync)));
+ Assert.Equal(0, control.Count(nameof(ICSharpDbClient.RollbackTransactionAsync)));
+ Assert.False(unary.IsCompleted);
+ Assert.Equal(42L, (await owner.ExecuteInTransactionAsync(id, "SELECT 42", ct)).Rows![0][0]);
+ await owner.CommitTransactionAsync(id, ct);
+ Assert.Equal(1, control.Count(nameof(ICSharpDbClient.ExecuteInTransactionAsync)));
+ Assert.Equal(1, control.Count(nameof(ICSharpDbClient.CommitTransactionAsync)));
+ }
+ finally { control.MetadataRelease.TrySetResult(); }
+ await unary.WaitAsync(TimeSpan.FromSeconds(5), ct);
+ Assert.Equal(42L, (await other.ExecuteSqlAsync("SELECT 42", ct)).Rows![0][0]);
+ }
+ finally { control.ReleaseAll(); await CSharpDbClient.ClearPoolAsync(host.NativeEndpoint.AbsoluteUri); }
+ }
+
+ [Theory(Timeout = 30000)]
+ [InlineData(false)]
+ [InlineData(true)]
+ public async Task StreamOrUnaryRpcFailure_UsesSharedPoisonAndRollback_WithoutReplay(bool unaryFailure)
+ {
+ var ct = TestContext.Current.CancellationToken;
+ var control = new Control();
+ await using var host = Host(control);
+ var options = Options(host);
+ try
+ {
+ await using (var first = await CSharpDbClient.RentAsync(options, 1, ct))
+ {
+ Assert.Null((await first.ExecuteSqlAsync("CREATE TABLE dispatch_failure (id INTEGER PRIMARY KEY)", ct)).Error);
+ string id = (await first.BeginTransactionAsync(ct)).TransactionId;
+ Assert.Null((await first.ExecuteInTransactionAsync(id, "INSERT INTO dispatch_failure VALUES (1)", ct)).Error);
+ control.FailMetadata = unaryFailure;
+ control.FailSql = unaryFailure ? null : "SELECT direct_failure";
+ var error = await Assert.ThrowsAsync(() => unaryFailure
+ ? first.GetTableNamesAsync(ct) : (Task)first.ExecuteSqlAsync("SELECT direct_failure", ct));
+ Assert.Equal(CoreError.Busy, error.Code);
+ var rpc = Assert.IsType(error.InnerException);
+ Assert.Equal(StatusCode.Aborted, rpc.StatusCode);
+ Assert.Equal("Busy", rpc.Trailers.GetValue("csharpdb-error-code"));
+ control.FailMetadata = false; control.FailSql = null;
+ }
+ Assert.Equal(1, control.FailureAttempts);
+ Assert.Equal(1, control.Count(nameof(ICSharpDbClient.RollbackTransactionAsync)));
+ await using var next = await CSharpDbClient.RentAsync(options, 1, ct);
+ Assert.Equal(0L, (await next.ExecuteSqlAsync("SELECT COUNT(*) FROM dispatch_failure", ct)).Rows![0][0]);
+ Assert.Equal(2, HttpCount(host, "CommandSession"));
+ Assert.Equal(1, control.FailureAttempts);
+ }
+ finally { await CSharpDbClient.ClearPoolAsync(host.NativeEndpoint.AbsoluteUri); }
+ }
+
+ [Fact(Timeout = 30000)]
+ public async Task SqlErrorResult_IsReturnedOnce_AndDoesNotPoisonTheRental()
+ {
+ var ct = TestContext.Current.CancellationToken;
+ var control = new Control();
+ await using var host = Host(control);
+ var options = Options(host);
+ try
+ {
+ await using (var first = await CSharpDbClient.RentAsync(options, 1, ct))
+ {
+ int before = control.Count(nameof(ICSharpDbClient.ExecuteSqlAsync));
+ var result = await first.ExecuteSqlAsync("SELECT sql_result_error", ct);
+ Assert.Equal("controlled SQL error result", result.Error);
+ Assert.Equal(before + 1, control.Count(nameof(ICSharpDbClient.ExecuteSqlAsync)));
+ Assert.NotNull(await first.GetInfoAsync(ct));
+ Assert.Empty(await first.GetTableNamesAsync(ct));
+ }
+ await using var next = await CSharpDbClient.RentAsync(options, 1, ct);
+ Assert.Equal(42L, (await next.ExecuteSqlAsync("SELECT 42", ct)).Rows![0][0]);
+ Assert.Equal(1, HttpCount(host, "CommandSession"));
+ }
+ finally { await CSharpDbClient.ClearPoolAsync(host.NativeEndpoint.AbsoluteUri); }
+ }
+
+ private static CSharpDbClientOptions Options(GrpcSocketDaemonFixture host) => new()
+ {
+ Transport = CSharpDbTransport.Grpc, GrpcMode = CSharpDbGrpcMode.Native,
+ GrpcCallMode = CSharpDbGrpcCallMode.Streaming, Endpoint = host.NativeEndpoint.AbsoluteUri,
+ };
+ private static long HttpCount(GrpcSocketDaemonFixture host, string method)
+ => host.Snapshot().Where(x => x.Key.Method.EndsWith("/" + method, StringComparison.Ordinal)).Sum(x => x.Value);
+ private static GrpcSocketDaemonFixture Host(Control control) => new(configureServices: services =>
+ {
+ var original = services.Last(x => x.ServiceType == typeof(ICSharpDbClient));
+ services.Replace(ServiceDescriptor.Singleton(provider =>
+ {
+ var real = (ICSharpDbClient)original.ImplementationFactory!(provider);
+ var proxy = DispatchProxy.Create();
+ ((Backend)(object)proxy).Inner = real;
+ ((Backend)(object)proxy).Control = control;
+ return proxy;
+ }));
+ });
+ public sealed class Control
+ {
+ public string? HoldSql, FailSql;
+ public bool HoldMetadata, FailMetadata;
+ public int FailureAttempts;
+ public ConcurrentDictionary Calls { get; } = new();
+ public TaskCompletionSource SqlEntered { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously);
+ public TaskCompletionSource SqlRelease { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously);
+ public TaskCompletionSource MetadataEntered { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously);
+ public TaskCompletionSource MetadataRelease { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously);
+ public int Count(string method) => Calls.GetValueOrDefault(method);
+ public void ReleaseAll() { SqlRelease.TrySetResult(); MetadataRelease.TrySetResult(); }
+ }
+ public class Backend : DispatchProxy
+ {
+ public ICSharpDbClient Inner = null!;
+ public Control Control = null!;
+ protected override object? Invoke(MethodInfo? targetMethod, object?[]? args)
+ {
+ MethodInfo method = targetMethod!;
+ Control.Calls.AddOrUpdate(method.Name, 1, static (_, count) => count + 1);
+ if ((Control.FailMetadata && method.Name == nameof(ICSharpDbClient.GetTableNamesAsync))
+ || (Control.FailSql is { } failure && method.Name == nameof(ICSharpDbClient.ExecuteSqlAsync) && Equals(args![0], failure)))
+ { Interlocked.Increment(ref Control.FailureAttempts); throw new CoreException(CoreError.Busy, "controlled RPC failure"); }
+ if (method.Name == nameof(ICSharpDbClient.ExecuteSqlAsync) && Equals(args![0], "SELECT sql_result_error"))
+ return Task.FromResult(new SqlExecutionResult { Error = "controlled SQL error result" });
+ if (Control.HoldMetadata && method.Name == nameof(ICSharpDbClient.GetTableNamesAsync))
+ return HoldMetadataAsync((CancellationToken)args![0]!);
+ object? result;
+ try { result = method.Invoke(Inner, args); }
+ catch (TargetInvocationException error) when (error.InnerException is not null)
+ { ExceptionDispatchInfo.Capture(error.InnerException).Throw(); throw; }
+ if (Control.HoldSql is { } held && method.Name == nameof(ICSharpDbClient.ExecuteInTransactionAsync) && Equals(args![1], held))
+ return HoldSqlAsync((Task)result!, (CancellationToken)args[2]!);
+ return result;
+ }
+ private async Task HoldSqlAsync(Task execution, CancellationToken ct)
+ {
+ var result = await execution;
+ Control.SqlEntered.TrySetResult();
+ await Control.SqlRelease.Task.WaitAsync(ct);
+ return result;
+ }
+ private async Task> HoldMetadataAsync(CancellationToken ct)
+ {
+ Control.MetadataEntered.TrySetResult();
+ await Control.MetadataRelease.Task.WaitAsync(ct);
+ return await Inner.GetTableNamesAsync(ct);
+ }
+ }
+}
diff --git a/tests/CSharpDB.Daemon.Tests/ExchangeTaskLifetimeTests.cs b/tests/CSharpDB.Daemon.Tests/ExchangeTaskLifetimeTests.cs
new file mode 100644
index 00000000..45173200
--- /dev/null
+++ b/tests/CSharpDB.Daemon.Tests/ExchangeTaskLifetimeTests.cs
@@ -0,0 +1,366 @@
+using CSharpDB.Client;
+using CSharpDB.Client.Grpc;
+using CSharpDB.Client.Internal;
+using CSharpDB.Client.Models;
+using CSharpDB.Testing;
+using Google.Protobuf.WellKnownTypes;
+using Grpc.Core;
+using Grpc.Core.Interceptors;
+
+namespace CSharpDB.Daemon.Tests;
+
+public sealed class ExchangeTaskLifetimeTests
+{
+ [Fact(Timeout = 30000)]
+ public async Task PublicSqlInfoAndTransactionTasks_KeepTheirResultsAcrossExchangesAndRentalReturn()
+ {
+ var ct = TestContext.Current.CancellationToken;
+ await using var host = new GrpcSocketDaemonFixture();
+ var options = Options(host);
+ try
+ {
+ Task sql;
+ Task info;
+ Task transaction;
+ SqlExecutionResult sqlResult;
+ DatabaseInfo infoResult;
+ TransactionSessionInfo transactionResult;
+ await using (var first = await CSharpDbClient.RentAsync(options, 1, ct))
+ {
+ sql = first.ExecuteSqlAsync("SELECT 111", ct);
+ sqlResult = await sql;
+ info = first.GetInfoAsync(ct);
+ infoResult = await info;
+ transaction = first.BeginTransactionAsync(ct);
+ transactionResult = await transaction;
+ await first.RollbackTransactionAsync(transactionResult.TransactionId, ct);
+ for (int index = 0; index < 32; index++)
+ Assert.Equal((long)index, (await first.ExecuteSqlAsync($"SELECT {index}", ct)).Rows![0][0]);
+ }
+ await using (var next = await CSharpDbClient.RentAsync(options, 1, ct))
+ {
+ for (int index = 32; index < 64; index++)
+ Assert.Equal((long)index, (await next.ExecuteSqlAsync($"SELECT {index}", ct)).Rows![0][0]);
+ }
+ Assert.Same(sqlResult, await sql);
+ Assert.Equal(111L, sqlResult.Rows![0][0]);
+ Assert.Same(infoResult, await info);
+ Assert.Same(transactionResult, await transaction);
+ Assert.False(string.IsNullOrEmpty(transactionResult.TransactionId));
+ }
+ finally { await CSharpDbClient.ClearPoolAsync(options.Endpoint!); }
+ }
+
+ [Theory(Timeout = 30000)]
+ [InlineData(false)]
+ [InlineData(true)]
+ public async Task PublicSqlFailureTask_KeepsItsErrorOrCancellationAfterLaterRental(bool cancel)
+ {
+ var ct = TestContext.Current.CancellationToken;
+ await using var host = new GrpcSocketDaemonFixture();
+ var options = Options(host);
+ using var cancellation = CancellationTokenSource.CreateLinkedTokenSource(ct);
+ try
+ {
+ Task retained;
+ SqlExecutionResult? failedResult = null;
+ string? sqlError = null;
+ await using (var first = await CSharpDbClient.RentAsync(options, 1, ct))
+ {
+ if (cancel)
+ {
+ cancellation.Cancel();
+ retained = first.ExecuteSqlAsync("SELECT 111", cancellation.Token);
+ var error = await Assert.ThrowsAnyAsync(() => retained);
+ Assert.Equal(cancellation.Token, error.CancellationToken);
+ }
+ else
+ {
+ retained = first.ExecuteSqlAsync("SELECT * FROM exchange_lifetime_missing_table", ct);
+ failedResult = await retained;
+ sqlError = failedResult.Error;
+ Assert.False(string.IsNullOrEmpty(sqlError));
+ Assert.Equal(17L, (await first.ExecuteSqlAsync("SELECT 17", ct)).Rows![0][0]);
+ }
+ }
+ await using (var next = await CSharpDbClient.RentAsync(options, 1, ct))
+ {
+ for (int index = 0; index < 32; index++)
+ Assert.Equal((long)index, (await next.ExecuteSqlAsync($"SELECT {index}", ct)).Rows![0][0]);
+ }
+ if (cancel)
+ {
+ var error = await Assert.ThrowsAnyAsync(() => retained);
+ Assert.Equal(cancellation.Token, error.CancellationToken);
+ Assert.True(retained.IsCanceled);
+ }
+ else
+ {
+ Assert.Same(failedResult, await retained);
+ Assert.Equal(sqlError, (await retained).Error);
+ }
+ }
+ finally { await CSharpDbClient.ClearPoolAsync(options.Endpoint!); }
+ }
+
+ [Theory(Timeout = 30000)]
+ [InlineData(0)]
+ [InlineData(1)]
+ [InlineData(2)]
+ public async Task TaskConsumers_KeepMixedCompletionsAcrossSequentialSessionReuse(int consumer)
+ {
+ var retained = new List();
+ for (int index = 0; index < 48; index++)
+ {
+ TestContext.Current.CancellationToken.ThrowIfCancellationRequested();
+ bool hold = index / 4 % 2 == 1;
+ await using var work = new Work(consumer, index, (Outcome)(index % 4), hold);
+ Assert.Equal(!hold, work.Operation.IsCompleted);
+ if (hold) work.Peer.Complete();
+ retained.Add(await ObserveAsync(work));
+ if (index % 8 == 7) await CheckRetainedAsync(retained);
+ }
+ await CheckRetainedAsync(retained);
+ }
+
+ [Theory(Timeout = 30000)]
+ [InlineData(0)]
+ [InlineData(1)]
+ [InlineData(2)]
+ public async Task TaskConsumers_KeepIndependentMixedCompletionsAcrossConcurrentSessions(int consumer)
+ {
+ var retained = new List();
+ for (int batch = 0; batch < 6; batch++)
+ {
+ Work[] work = Enumerable.Range(0, 12)
+ .Select(lane => new Work(consumer, 1000 + batch * 12 + lane, (Outcome)(lane % 4), hold: true)).ToArray();
+ try
+ {
+ Assert.All(work, item => Assert.False(item.Operation.IsCompleted));
+ Task[] observations = work.Select(ObserveAsync).ToArray();
+ foreach (int lane in batch % 2 == 0 ? Enumerable.Range(0, 12).Reverse() : Enumerable.Range(0, 12))
+ work[lane].Peer.Complete();
+ retained.AddRange(await Task.WhenAll(observations)
+ .WaitAsync(TimeSpan.FromSeconds(15), TestContext.Current.CancellationToken));
+ }
+ finally
+ {
+ foreach (Work item in work) await item.DisposeAsync();
+ }
+ await CheckRetainedAsync(retained);
+ }
+ }
+
+ private static CSharpDbClientOptions Options(GrpcSocketDaemonFixture host) => new()
+ {
+ Transport = CSharpDbTransport.Grpc, GrpcMode = CSharpDbGrpcMode.Native,
+ GrpcCallMode = CSharpDbGrpcCallMode.Streaming, Endpoint = host.NativeEndpoint.AbsoluteUri,
+ };
+
+ private static async Task ObserveAsync(Work work)
+ {
+ object? result = null;
+ RpcException? failure = null;
+ CancellationToken? canceledToken = null;
+ switch (work.Outcome)
+ {
+ case Outcome.Success:
+ result = await ReadResultAsync(work);
+ if (result is SqlExecutionResultMessage sql) Assert.Equal(work.Index, sql.RowsAffected);
+ else Assert.Equal(work.Peer.Owner, Assert.IsType(result).DataSource);
+ break;
+ case Outcome.WireError:
+ case Outcome.TransportError:
+ failure = await Assert.ThrowsAsync(() => work.Operation);
+ Assert.Equal(work.Outcome == Outcome.WireError ? StatusCode.InvalidArgument : StatusCode.Internal, failure.StatusCode);
+ Assert.Equal(work.Peer.Owner, failure.Status.Detail);
+ Assert.Equal(work.Peer.Owner, failure.Trailers.GetValue("x-owner"));
+ break;
+ case Outcome.Canceled:
+ var canceled = await Assert.ThrowsAnyAsync(() => work.Operation);
+ canceledToken = canceled.CancellationToken;
+ Assert.True(canceledToken.Value.IsCancellationRequested);
+ if (work.Consumer != 2) Assert.Equal(work.Token, canceledToken.Value);
+ break;
+ }
+ Assert.Equal(1, work.Peer.CommandWrites);
+ Metadata? headers = work.Headers is null ? null : await work.Headers;
+ if (headers is not null) Assert.Equal(work.Peer.Owner, headers.GetValue("x-owner"));
+ var observed = new Observation(work, result, failure, canceledToken, headers);
+ CheckUnaryCompletion(observed);
+ return observed;
+ }
+
+ private static async Task CheckRetainedAsync(IEnumerable retained)
+ {
+ foreach (Observation item in retained)
+ {
+ if (item.Failure is not null)
+ Assert.Same(item.Failure, await Assert.ThrowsAsync(() => item.Work.Operation));
+ else if (item.CanceledToken is not null)
+ {
+ var error = await Assert.ThrowsAnyAsync(() => item.Work.Operation);
+ Assert.Equal(item.CanceledToken.Value, error.CancellationToken);
+ Assert.True(item.Work.Operation.IsCanceled);
+ }
+ else Assert.Same(item.Result, await ReadResultAsync(item.Work));
+ if (item.Work.Headers is not null) Assert.Same(item.Headers, await item.Work.Headers);
+ CheckUnaryCompletion(item);
+ }
+ }
+
+ private static void CheckUnaryCompletion(Observation item)
+ {
+ if (item.Work.Unary is not { } call) return;
+ Assert.Same(item.Work.Operation, call.ResponseAsync);
+ StatusCode expected = item.Work.Outcome switch
+ {
+ Outcome.Success => StatusCode.OK,
+ Outcome.WireError => StatusCode.InvalidArgument,
+ Outcome.TransportError => StatusCode.Internal,
+ _ => StatusCode.Cancelled,
+ };
+ Assert.Equal(expected, call.GetStatus().StatusCode);
+ if (item.Failure is not null) Assert.Equal(item.Work.Peer.Owner, call.GetTrailers().GetValue("x-owner"));
+ else Assert.Empty(call.GetTrailers());
+ }
+
+ private static async Task