diff --git a/src/Titano.Data/ConnectionString.cs b/src/Titano.Data/ConnectionString.cs
new file mode 100644
index 00000000..849656e4
--- /dev/null
+++ b/src/Titano.Data/ConnectionString.cs
@@ -0,0 +1,111 @@
+using System.Globalization;
+using System.Text;
+
+namespace Titano.Data;
+
+///
+/// key=value;… connection strings. Keys are case- and space-insensitive (SslMode = Ssl Mode);
+/// values may be single- or double-quoted, with the quote doubled inside.
+///
+internal sealed class ConnectionString
+{
+ private readonly Dictionary _values = new(StringComparer.Ordinal);
+ private readonly HashSet _used = new(StringComparer.Ordinal);
+
+ public ConnectionString(string text)
+ {
+ var i = 0;
+ while (i < text.Length)
+ {
+ var eq = text.IndexOf('=', i);
+ if (eq < 0)
+ {
+ if (text.AsSpan(i).Trim().Trim(';').IsEmpty) break;
+ throw new FormatException($"Connection string segment '{text[i..].Trim()}' has no '='.");
+ }
+ var key = Normalize(text.AsSpan(i, eq - i).Trim().TrimStart(';'));
+ i = eq + 1;
+ while (i < text.Length && char.IsWhiteSpace(text[i])) i++;
+ string value;
+ if (i < text.Length && text[i] is '"' or '\'')
+ {
+ var quote = text[i++];
+ var sb = new StringBuilder();
+ while (true)
+ {
+ if (i >= text.Length) throw new FormatException("Unterminated quoted value in connection string.");
+ if (text[i] == quote)
+ {
+ if (i + 1 < text.Length && text[i + 1] == quote)
+ {
+ sb.Append(quote);
+ i += 2;
+ continue;
+ }
+ i++;
+ break;
+ }
+ sb.Append(text[i++]);
+ }
+ value = sb.ToString();
+ while (i < text.Length && char.IsWhiteSpace(text[i])) i++;
+ if (i < text.Length && text[i] != ';') throw new FormatException("Unexpected text after a quoted connection string value.");
+ }
+ else
+ {
+ var end = text.IndexOf(';', i);
+ if (end < 0) end = text.Length;
+ value = text[i..end].Trim();
+ i = end;
+ }
+ if (key.Length == 0) throw new FormatException("Empty key in connection string.");
+ _values[key] = value;
+ if (i < text.Length && text[i] == ';') i++;
+ }
+ }
+
+ /// First present key among (synonyms), or null.
+ public string? Get(params string[] keys)
+ {
+ foreach (var key in keys)
+ {
+ var normalized = Normalize(key);
+ if (_values.TryGetValue(normalized, out var value))
+ {
+ _used.Add(normalized);
+ return value;
+ }
+ }
+ return null;
+ }
+
+ public int GetInt(int defaultValue, params string[] keys)
+ {
+ var text = Get(keys);
+ if (text is null) return defaultValue;
+ return int.TryParse(text, NumberStyles.Integer, CultureInfo.InvariantCulture, out var value)
+ ? value
+ : throw new FormatException($"Connection string value '{keys[0]}' must be an integer.");
+ }
+
+ public bool Contains(string key) => _values.ContainsKey(Normalize(key));
+
+ /// Rejects keys that no call consumed, so typos do not pass silently.
+ public void ThrowOnUnknownKeys()
+ {
+ foreach (var key in _values.Keys)
+ {
+ if (!_used.Contains(key)) throw new FormatException($"Unknown connection string key '{key}'.");
+ }
+ }
+
+ private static string Normalize(ReadOnlySpan key)
+ {
+ var sb = new StringBuilder(key.Length);
+ foreach (var c in key)
+ {
+ if (!char.IsWhiteSpace(c)) sb.Append(char.ToLowerInvariant(c));
+ }
+ return sb.ToString();
+ }
+}
diff --git a/src/Titano.Data/DatabaseException.cs b/src/Titano.Data/DatabaseException.cs
new file mode 100644
index 00000000..413c271b
--- /dev/null
+++ b/src/Titano.Data/DatabaseException.cs
@@ -0,0 +1,34 @@
+using System.Data.Common;
+
+namespace Titano.Data;
+
+/// Base of errors reported by a database engine; repositories test the kind without knowing the dialect.
+public abstract class DatabaseException : DbException
+{
+ protected DatabaseException(string message, Exception? innerException = null)
+ : base(message, innerException)
+ {
+ }
+
+ /// A UNIQUE or PRIMARY KEY constraint rejected the statement.
+ public virtual bool IsUniqueViolation => false;
+
+ /// A FOREIGN KEY constraint rejected the statement.
+ public virtual bool IsForeignKeyViolation => false;
+}
+
+/// The connection to the database server could not be established or was lost.
+public sealed class DatabaseConnectionException(string message, Exception? innerException = null)
+ : DatabaseException(message, innerException)
+{
+ public override bool IsTransient => true;
+}
+
+/// The database was migrated by a newer build; opening it would risk corrupting data this build does not know.
+public sealed class SchemaTooNewException(int databaseVersion, int supportedVersion)
+ : InvalidOperationException($"The database schema version {databaseVersion} is newer than the version {supportedVersion} this build supports.")
+{
+ public int DatabaseVersion { get; } = databaseVersion;
+
+ public int SupportedVersion { get; } = supportedVersion;
+}
diff --git a/src/Titano.Data/DbParam.cs b/src/Titano.Data/DbParam.cs
new file mode 100644
index 00000000..f6790b84
--- /dev/null
+++ b/src/Titano.Data/DbParam.cs
@@ -0,0 +1,125 @@
+namespace Titano.Data;
+
+/// Logical type of a : decides the SQLite binding and the PostgreSQL parameter type.
+public enum DbValueType
+{
+ /// Inferred from the CLR type of the value; a null stays untyped.
+ Auto,
+ Text,
+ Int32,
+ Int64,
+ Double,
+ Bool,
+ Uuid,
+
+ /// An instant, stored in UTC (timestamptz / ISO-8601 text ending in Z).
+ Timestamp,
+
+ /// A wall-clock date and time without offset (timestamp / ISO-8601 text without zone).
+ LocalDateTime,
+
+ Bytes,
+
+ /// JSON text (jsonb on PostgreSQL, TEXT on SQLite).
+ Json,
+}
+
+///
+/// A positional statement parameter: the n-th parameter binds to $n in the SQL text on both dialects.
+/// Implicit conversions keep the CLR type even for nulls, so (Guid?)null is still a typed uuid.
+///
+public readonly struct DbParam
+{
+ public DbParam(object? value, DbValueType type = DbValueType.Auto, string? name = null)
+ {
+ Name = name;
+ Type = type == DbValueType.Auto && value is not null ? Infer(value) : type;
+ Value = value is null ? null : Normalize(value, Type);
+ }
+
+ /// Optional label used in diagnostics only; binding is by position.
+ public string? Name { get; }
+
+ ///
+ /// The value in the canonical CLR form of : string (Text, Json), int, long, double, bool,
+ /// Guid, DateTimeOffset (Timestamp), DateTime (LocalDateTime) or byte[].
+ ///
+ public object? Value { get; }
+
+ /// Effective type; only for an untyped null.
+ public DbValueType Type { get; }
+
+ /// An untyped SQL NULL.
+ public static DbParam Null => default;
+
+ public static DbParam Text(string? value) => new(value, DbValueType.Text);
+ public static DbParam Json(string? value) => new(value, DbValueType.Json);
+ public static DbParam Bytes(byte[]? value) => new(value, DbValueType.Bytes);
+
+ /// Maps a CLR value to the type it binds as; throws for unsupported types.
+ public static DbValueType Infer(object value) => value switch
+ {
+ string => DbValueType.Text,
+ int or short or byte or sbyte or ushort => DbValueType.Int32,
+ long or uint or ulong => DbValueType.Int64,
+ double or float => DbValueType.Double,
+ bool => DbValueType.Bool,
+ Guid => DbValueType.Uuid,
+ DateTimeOffset => DbValueType.Timestamp,
+ DateTime d => d.Kind == DateTimeKind.Unspecified ? DbValueType.LocalDateTime : DbValueType.Timestamp,
+ byte[] => DbValueType.Bytes,
+ Enum => DbValueType.Int64,
+ _ => throw new NotSupportedException($"Parameter values of type {value.GetType().Name} are not supported."),
+ };
+
+ private static object Normalize(object value, DbValueType type)
+ {
+ var inv = System.Globalization.CultureInfo.InvariantCulture;
+ return type switch
+ {
+ DbValueType.Text or DbValueType.Json => value as string ?? Convert.ToString(value, inv) ?? string.Empty,
+ DbValueType.Int32 => value is int ? value : Convert.ToInt32(value, inv),
+ DbValueType.Int64 => value is long ? value : Convert.ToInt64(value, inv),
+ DbValueType.Double => value is double ? value : Convert.ToDouble(value, inv),
+ DbValueType.Bool => value is bool ? value : Convert.ToBoolean(value, inv),
+ DbValueType.Uuid => value is Guid ? value : Guid.Parse(Convert.ToString(value, inv)!),
+ DbValueType.Timestamp => value switch
+ {
+ DateTimeOffset o => o,
+ DateTime { Kind: DateTimeKind.Unspecified } d => new DateTimeOffset(d, TimeSpan.Zero),
+ DateTime d => new DateTimeOffset(d.ToUniversalTime()),
+ _ => throw new NotSupportedException($"Cannot bind {value.GetType().Name} as a timestamp."),
+ },
+ DbValueType.LocalDateTime => value switch
+ {
+ DateTime d => d,
+ DateTimeOffset o => o.DateTime,
+ _ => throw new NotSupportedException($"Cannot bind {value.GetType().Name} as a date-time."),
+ },
+ DbValueType.Bytes => value as byte[] ?? throw new NotSupportedException($"Cannot bind {value.GetType().Name} as bytes."),
+ _ => value,
+ };
+ }
+
+ public static implicit operator DbParam(string? value) => new(value, DbValueType.Text);
+ public static implicit operator DbParam(byte[]? value) => new(value, DbValueType.Bytes);
+ public static implicit operator DbParam(int value) => new(value, DbValueType.Int32);
+ public static implicit operator DbParam(int? value) => new(value, DbValueType.Int32);
+ public static implicit operator DbParam(long value) => new(value, DbValueType.Int64);
+ public static implicit operator DbParam(long? value) => new(value, DbValueType.Int64);
+ public static implicit operator DbParam(double value) => new(value, DbValueType.Double);
+ public static implicit operator DbParam(double? value) => new(value, DbValueType.Double);
+ public static implicit operator DbParam(bool value) => new(value, DbValueType.Bool);
+ public static implicit operator DbParam(bool? value) => new(value, DbValueType.Bool);
+ public static implicit operator DbParam(Guid value) => new(value, DbValueType.Uuid);
+ public static implicit operator DbParam(Guid? value) => new(value, DbValueType.Uuid);
+ public static implicit operator DbParam(DateTimeOffset value) => new(value, DbValueType.Timestamp);
+ public static implicit operator DbParam(DateTimeOffset? value) => new(value, DbValueType.Timestamp);
+
+ /// Unspecified-kind values are wall-clock times; UTC/local kinds are instants.
+ public static implicit operator DbParam(DateTime value) => new(value);
+
+ public static implicit operator DbParam(DateTime? value) => value is { } v ? new(v) : new(null, DbValueType.LocalDateTime);
+
+ public override string ToString() => $"{Name ?? "?"}:{Type}={Value ?? "NULL"}";
+}
diff --git a/src/Titano.Data/DbRow.cs b/src/Titano.Data/DbRow.cs
new file mode 100644
index 00000000..7af799c7
--- /dev/null
+++ b/src/Titano.Data/DbRow.cs
@@ -0,0 +1,200 @@
+using System.Globalization;
+
+namespace Titano.Data;
+
+/// Column names of a result set, shared by all of its rows.
+internal sealed class DbColumns(string[] names)
+{
+ private Dictionary? _ordinals;
+
+ public string[] Names { get; } = names;
+
+ public int GetOrdinal(string name)
+ {
+ if (_ordinals is null)
+ {
+ var map = new Dictionary(Names.Length, StringComparer.OrdinalIgnoreCase);
+ for (var i = 0; i < Names.Length; i++) map.TryAdd(Names[i], i);
+ _ordinals = map;
+ }
+ return _ordinals.TryGetValue(name, out var ordinal)
+ ? ordinal
+ : throw new IndexOutOfRangeException($"No column named '{name}' in the result.");
+ }
+}
+
+///
+/// One materialised result row. Values keep the provider's natural CLR type (SQLite: long, double, string,
+/// byte[]; PostgreSQL: decoded by type OID) and the typed getters convert between compatible forms, so the
+/// same mapping code reads both dialects (e.g. a SQLite TEXT uuid through ).
+/// Rows stay valid after the enumeration that produced them ends.
+///
+public sealed class DbRow
+{
+ private readonly DbColumns _columns;
+ private readonly object?[] _values;
+
+ internal DbRow(DbColumns columns, object?[] values)
+ {
+ _columns = columns;
+ _values = values;
+ }
+
+ public int FieldCount => _values.Length;
+
+ public string GetName(int ordinal) => _columns.Names[ordinal];
+
+ /// Case-insensitive column lookup; the first column with that name wins.
+ public int GetOrdinal(string name) => _columns.GetOrdinal(name);
+
+ public bool IsNull(int ordinal) => _values[ordinal] is null;
+
+ public object? GetValue(int ordinal) => _values[ordinal];
+
+ public string GetString(int ordinal) => GetStringOrNull(ordinal) ?? throw NullValue(ordinal);
+ public int GetInt32(int ordinal) => GetInt32OrNull(ordinal) ?? throw NullValue(ordinal);
+ public long GetInt64(int ordinal) => GetInt64OrNull(ordinal) ?? throw NullValue(ordinal);
+ public double GetDouble(int ordinal) => GetDoubleOrNull(ordinal) ?? throw NullValue(ordinal);
+ public bool GetBool(int ordinal) => GetBoolOrNull(ordinal) ?? throw NullValue(ordinal);
+ public Guid GetGuid(int ordinal) => GetGuidOrNull(ordinal) ?? throw NullValue(ordinal);
+ public DateTimeOffset GetDateTimeOffset(int ordinal) => GetDateTimeOffsetOrNull(ordinal) ?? throw NullValue(ordinal);
+ public DateTime GetDateTime(int ordinal) => GetDateTimeOrNull(ordinal) ?? throw NullValue(ordinal);
+ public byte[] GetBytes(int ordinal) => GetBytesOrNull(ordinal) ?? throw NullValue(ordinal);
+
+ public string? GetStringOrNull(int ordinal) => _values[ordinal] switch
+ {
+ null => null,
+ string s => s,
+ Guid g => TextValues.FormatGuid(g),
+ DateTimeOffset o => TextValues.FormatTimestamp(o),
+ DateTime d => TextValues.FormatLocal(d),
+ byte[] => throw Mismatch(ordinal, "string"),
+ var v => Convert.ToString(v, CultureInfo.InvariantCulture),
+ };
+
+ public int? GetInt32OrNull(int ordinal) => _values[ordinal] switch
+ {
+ null => null,
+ int i => i,
+ var v => checked((int)ToInt64(ordinal, v)),
+ };
+
+ public long? GetInt64OrNull(int ordinal) => _values[ordinal] is { } v ? ToInt64(ordinal, v) : null;
+
+ public double? GetDoubleOrNull(int ordinal) => _values[ordinal] switch
+ {
+ null => null,
+ double d => d,
+ long l => l,
+ int i => i,
+ float f => f,
+ string s => double.Parse(s, NumberStyles.Float, CultureInfo.InvariantCulture),
+ _ => throw Mismatch(ordinal, "double"),
+ };
+
+ public bool? GetBoolOrNull(int ordinal) => _values[ordinal] switch
+ {
+ null => null,
+ bool b => b,
+ long l => l != 0,
+ int i => i != 0,
+ _ => throw Mismatch(ordinal, "bool"),
+ };
+
+ public Guid? GetGuidOrNull(int ordinal) => _values[ordinal] switch
+ {
+ null => null,
+ Guid g => g,
+ string s => Guid.Parse(s),
+ _ => throw Mismatch(ordinal, "Guid"),
+ };
+
+ /// Instants: timestamptz values, ISO-8601 text, or timestamp values taken as UTC.
+ public DateTimeOffset? GetDateTimeOffsetOrNull(int ordinal) => _values[ordinal] switch
+ {
+ null => null,
+ DateTimeOffset o => o,
+ string s => TextValues.ParseTimestamp(s),
+ DateTime d => new DateTimeOffset(DateTime.SpecifyKind(d, DateTimeKind.Utc)),
+ _ => throw Mismatch(ordinal, "DateTimeOffset"),
+ };
+
+ /// Wall-clock date-times (unspecified kind); instants are returned as UTC.
+ public DateTime? GetDateTimeOrNull(int ordinal) => _values[ordinal] switch
+ {
+ null => null,
+ DateTime d => d,
+ string s => TextValues.ParseLocal(s),
+ DateTimeOffset o => o.UtcDateTime,
+ DateOnly d => d.ToDateTime(TimeOnly.MinValue),
+ _ => throw Mismatch(ordinal, "DateTime"),
+ };
+
+ public byte[]? GetBytesOrNull(int ordinal) => _values[ordinal] switch
+ {
+ null => null,
+ byte[] b => b,
+ _ => throw Mismatch(ordinal, "byte[]"),
+ };
+
+ public string GetString(string name) => GetString(GetOrdinal(name));
+ public string? GetStringOrNull(string name) => GetStringOrNull(GetOrdinal(name));
+ public int GetInt32(string name) => GetInt32(GetOrdinal(name));
+ public int? GetInt32OrNull(string name) => GetInt32OrNull(GetOrdinal(name));
+ public long GetInt64(string name) => GetInt64(GetOrdinal(name));
+ public long? GetInt64OrNull(string name) => GetInt64OrNull(GetOrdinal(name));
+ public double GetDouble(string name) => GetDouble(GetOrdinal(name));
+ public double? GetDoubleOrNull(string name) => GetDoubleOrNull(GetOrdinal(name));
+ public bool GetBool(string name) => GetBool(GetOrdinal(name));
+ public bool? GetBoolOrNull(string name) => GetBoolOrNull(GetOrdinal(name));
+ public Guid GetGuid(string name) => GetGuid(GetOrdinal(name));
+ public Guid? GetGuidOrNull(string name) => GetGuidOrNull(GetOrdinal(name));
+ public DateTimeOffset GetDateTimeOffset(string name) => GetDateTimeOffset(GetOrdinal(name));
+ public DateTimeOffset? GetDateTimeOffsetOrNull(string name) => GetDateTimeOffsetOrNull(GetOrdinal(name));
+ public DateTime GetDateTime(string name) => GetDateTime(GetOrdinal(name));
+ public DateTime? GetDateTimeOrNull(string name) => GetDateTimeOrNull(GetOrdinal(name));
+ public byte[] GetBytes(string name) => GetBytes(GetOrdinal(name));
+ public byte[]? GetBytesOrNull(string name) => GetBytesOrNull(GetOrdinal(name));
+
+ ///
+ /// Generic read used by scalar helpers: string, int, long, double, bool, Guid, DateTimeOffset, DateTime,
+ /// byte[], their nullable forms and enums (from integers). A null reads as default.
+ ///
+ public T? Get(int ordinal)
+ {
+ if (_values[ordinal] is null) return default;
+ var target = Nullable.GetUnderlyingType(typeof(T)) ?? typeof(T);
+ object value = target switch
+ {
+ _ when target == typeof(string) => GetString(ordinal),
+ _ when target == typeof(int) => GetInt32(ordinal),
+ _ when target == typeof(long) => GetInt64(ordinal),
+ _ when target == typeof(double) => GetDouble(ordinal),
+ _ when target == typeof(bool) => GetBool(ordinal),
+ _ when target == typeof(Guid) => GetGuid(ordinal),
+ _ when target == typeof(DateTimeOffset) => GetDateTimeOffset(ordinal),
+ _ when target == typeof(DateTime) => GetDateTime(ordinal),
+ _ when target == typeof(byte[]) => GetBytes(ordinal),
+ { IsEnum: true } => Enum.ToObject(target, GetInt64(ordinal)),
+ _ => _values[ordinal] is T ? _values[ordinal]! : throw Mismatch(ordinal, target.Name),
+ };
+ return (T)value;
+ }
+
+ private long ToInt64(int ordinal, object value) => value switch
+ {
+ long l => l,
+ int i => i,
+ short s => s,
+ bool b => b ? 1 : 0,
+ double d when d == Math.Floor(d) && d is >= long.MinValue and < long.MaxValue => (long)d,
+ string s => long.Parse(s, NumberStyles.AllowLeadingSign, CultureInfo.InvariantCulture),
+ _ => throw Mismatch(ordinal, "integer"),
+ };
+
+ private InvalidCastException NullValue(int ordinal) =>
+ new($"Column '{_columns.Names[ordinal]}' is NULL.");
+
+ private InvalidCastException Mismatch(int ordinal, string target) =>
+ new($"Column '{_columns.Names[ordinal]}' holds {_values[ordinal]!.GetType().Name}, which cannot be read as {target}.");
+}
diff --git a/src/Titano.Data/DbSessionExtensions.cs b/src/Titano.Data/DbSessionExtensions.cs
new file mode 100644
index 00000000..af6fb729
--- /dev/null
+++ b/src/Titano.Data/DbSessionExtensions.cs
@@ -0,0 +1,55 @@
+namespace Titano.Data;
+
+/// Single-row, list and scalar helpers over .
+public static class DbSessionExtensions
+{
+ /// The only row, or null when there is none; more than one row is an error.
+ public static async Task QuerySingleOrDefaultAsync(this IDbSession session, string sql, DbParam[] parameters, CancellationToken cancellationToken)
+ {
+ DbRow? found = null;
+ await foreach (var row in session.QueryAsync(sql, parameters, cancellationToken).ConfigureAwait(false))
+ {
+ if (found is not null) throw new InvalidOperationException("The query returned more than one row.");
+ found = row;
+ }
+ return found;
+ }
+
+ public static Task QuerySingleOrDefaultAsync(this IDbSession session, string sql, params DbParam[] parameters) =>
+ session.QuerySingleOrDefaultAsync(sql, parameters, CancellationToken.None);
+
+ /// The only row; none or more than one is an error.
+ public static async Task QuerySingleAsync(this IDbSession session, string sql, DbParam[] parameters, CancellationToken cancellationToken) =>
+ await session.QuerySingleOrDefaultAsync(sql, parameters, cancellationToken).ConfigureAwait(false)
+ ?? throw new InvalidOperationException("The query returned no rows.");
+
+ public static Task QuerySingleAsync(this IDbSession session, string sql, params DbParam[] parameters) =>
+ session.QuerySingleAsync(sql, parameters, CancellationToken.None);
+
+ /// Maps the only row, or returns default when there is none.
+ public static async Task QuerySingleOrDefaultAsync(this IDbSession session, string sql, DbParam[] parameters, Func map, CancellationToken cancellationToken)
+ {
+ var row = await session.QuerySingleOrDefaultAsync(sql, parameters, cancellationToken).ConfigureAwait(false);
+ return row is null ? default : map(row);
+ }
+
+ /// Maps every row into a list.
+ public static async Task> QueryListAsync(this IDbSession session, string sql, DbParam[] parameters, Func map, CancellationToken cancellationToken)
+ {
+ var list = new List();
+ await foreach (var row in session.QueryAsync(sql, parameters, cancellationToken).ConfigureAwait(false))
+ list.Add(map(row));
+ return list;
+ }
+
+ /// First column of the first row converted with ; default when there is no row or it is NULL.
+ public static async Task ScalarAsync(this IDbSession session, string sql, DbParam[] parameters, CancellationToken cancellationToken)
+ {
+ await foreach (var row in session.QueryAsync(sql, parameters, cancellationToken).ConfigureAwait(false))
+ return row.Get(0);
+ return default;
+ }
+
+ public static Task ScalarAsync(this IDbSession session, string sql, params DbParam[] parameters) =>
+ session.ScalarAsync(sql, parameters, CancellationToken.None);
+}
diff --git a/src/Titano.Data/IDatabase.cs b/src/Titano.Data/IDatabase.cs
new file mode 100644
index 00000000..9c58d185
--- /dev/null
+++ b/src/Titano.Data/IDatabase.cs
@@ -0,0 +1,60 @@
+namespace Titano.Data;
+
+/// A database (SQLite file or PostgreSQL server) that hands out pooled sessions (BRIEF §6.1).
+public interface IDatabase : IAsyncDisposable
+{
+ Dialect Dialect { get; }
+
+ /// Rents a connection from the pool; dispose the session to return it.
+ Task OpenAsync(CancellationToken cancellationToken);
+}
+
+///
+/// One pooled connection. SQL uses positional $1…$n placeholders on both dialects. A session is not
+/// thread-safe: run one command at a time and finish (or dispose) a query enumeration before the next command.
+///
+public interface IDbSession : IAsyncDisposable
+{
+ Dialect Dialect { get; }
+
+ /// True between and commit/rollback.
+ bool InTransaction { get; }
+
+ /// Runs one statement and returns the number of rows it inserted, updated or deleted.
+ Task ExecuteAsync(string sql, DbParam[] parameters, CancellationToken cancellationToken);
+
+ /// Streams the rows of one statement.
+ IAsyncEnumerable QueryAsync(string sql, DbParam[] parameters, CancellationToken cancellationToken);
+
+ /// Runs a parameterless multi-statement script (migrations, maintenance).
+ Task ExecuteScriptAsync(string script, CancellationToken cancellationToken);
+
+ ///
+ /// Starts a transaction (BEGIN IMMEDIATE on SQLite, so writers queue up front instead of failing later).
+ /// Nested transactions are not supported.
+ ///
+ Task BeginAsync(CancellationToken cancellationToken);
+
+ ///
+ /// Inserts many rows: COPY … FROM STDIN on PostgreSQL, multi-row INSERTs in one transaction on SQLite.
+ /// Each row array is consumed before the next one is requested, so producers may reuse it.
+ ///
+ Task BulkInsertAsync(string table, IReadOnlyList columns, IAsyncEnumerable