From a09aa168763517babe0196b9be05a189dfcd311a Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 09:40:33 +0000 Subject: [PATCH] feat(data): add database abstractions and SQLite binding IDatabase/IDbSession/IDbTransaction with positional $n parameters, typed DbParam and DbRow, SqlDialect helpers, and a P/Invoke binding to the system SQLite (winsqlite3 / libsqlite3) with WAL pragmas, statement cache, serialized writes, busy retry, interrupt-based cancellation, VACUUM INTO backups and restore. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC --- src/Titano.Data/ConnectionString.cs | 111 ++++++++ src/Titano.Data/DatabaseException.cs | 34 +++ src/Titano.Data/DbParam.cs | 125 ++++++++ src/Titano.Data/DbRow.cs | 200 +++++++++++++ src/Titano.Data/DbSessionExtensions.cs | 55 ++++ src/Titano.Data/IDatabase.cs | 60 ++++ src/Titano.Data/SqlDialect.cs | 78 +++++ src/Titano.Data/Sqlite/SqliteConnection.cs | 209 ++++++++++++++ src/Titano.Data/Sqlite/SqliteDatabase.cs | 265 +++++++++++++++++ src/Titano.Data/Sqlite/SqliteException.cs | 19 ++ src/Titano.Data/Sqlite/SqliteNative.cs | 104 +++++++ src/Titano.Data/Sqlite/SqliteSession.cs | 315 +++++++++++++++++++++ src/Titano.Data/Sqlite/SqliteStatement.cs | 170 +++++++++++ src/Titano.Data/TextValues.cs | 135 +++++++++ 14 files changed, 1880 insertions(+) create mode 100644 src/Titano.Data/ConnectionString.cs create mode 100644 src/Titano.Data/DatabaseException.cs create mode 100644 src/Titano.Data/DbParam.cs create mode 100644 src/Titano.Data/DbRow.cs create mode 100644 src/Titano.Data/DbSessionExtensions.cs create mode 100644 src/Titano.Data/IDatabase.cs create mode 100644 src/Titano.Data/SqlDialect.cs create mode 100644 src/Titano.Data/Sqlite/SqliteConnection.cs create mode 100644 src/Titano.Data/Sqlite/SqliteDatabase.cs create mode 100644 src/Titano.Data/Sqlite/SqliteException.cs create mode 100644 src/Titano.Data/Sqlite/SqliteNative.cs create mode 100644 src/Titano.Data/Sqlite/SqliteSession.cs create mode 100644 src/Titano.Data/Sqlite/SqliteStatement.cs create mode 100644 src/Titano.Data/TextValues.cs 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 rows, CancellationToken cancellationToken); + + Task ExecuteAsync(string sql, params DbParam[] parameters) => ExecuteAsync(sql, parameters, CancellationToken.None); + + IAsyncEnumerable QueryAsync(string sql, params DbParam[] parameters) => QueryAsync(sql, parameters, CancellationToken.None); + + Task BeginAsync() => BeginAsync(CancellationToken.None); + + Task BulkInsertAsync(string table, IReadOnlyList columns, IAsyncEnumerable rows) => + BulkInsertAsync(table, columns, rows, CancellationToken.None); +} + +/// An open transaction; disposing it without rolls it back. +public interface IDbTransaction : IAsyncDisposable +{ + Task CommitAsync(CancellationToken cancellationToken = default); + + Task RollbackAsync(CancellationToken cancellationToken = default); +} diff --git a/src/Titano.Data/SqlDialect.cs b/src/Titano.Data/SqlDialect.cs new file mode 100644 index 00000000..1581a9ad --- /dev/null +++ b/src/Titano.Data/SqlDialect.cs @@ -0,0 +1,78 @@ +using System.Text; + +namespace Titano.Data; + +/// +/// The few SQL fragments that differ between SQLite (≥ 3.31) and PostgreSQL. Everything else in the +/// repositories is plain SQL that both accept: $n placeholders, ON CONFLICT … DO UPDATE, +/// TRUE/FALSE, NULLS LAST, LIKE … ESCAPE. +/// +public sealed class SqlDialect +{ + /// Separator of lists (ASCII unit separator, never part of a tag). + public const char ListSeparator = '\u001f'; + + private SqlDialect(Dialect dialect) => Dialect = dialect; + + public static SqlDialect Sqlite { get; } = new(Dialect.Sqlite); + + public static SqlDialect Postgres { get; } = new(Dialect.Postgres); + + public Dialect Dialect { get; } + + public bool IsPostgres => Dialect == Dialect.Postgres; + + public static SqlDialect For(Dialect dialect) => dialect == Dialect.Postgres ? Postgres : Sqlite; + + /// Row lock for read-modify-write inside a transaction; empty on SQLite, whose BEGIN IMMEDIATE already holds the write lock. + public string ForUpdate => IsPostgres ? " FOR UPDATE" : string.Empty; + + /// Calendar year of a timestamp column (SQLite stores ISO-8601 text). + public string Year(string expression) => IsPostgres + ? $"CAST(EXTRACT(YEAR FROM {expression}) AS integer)" + : $"CAST(substr({expression}, 1, 4) AS INTEGER)"; + + /// Month (1–12) of a timestamp column. + public string Month(string expression) => IsPostgres + ? $"CAST(EXTRACT(MONTH FROM {expression}) AS integer)" + : $"CAST(substr({expression}, 6, 2) AS INTEGER)"; + + /// Aggregate that joins the group's values with (order unspecified). + public string StringAgg(string expression) => IsPostgres + ? $"string_agg({expression}, chr(31))" + : $"group_concat({expression}, char(31))"; + + /// + /// INSERT … VALUES ($1…$n) ON CONFLICT (keys) DO UPDATE SET …; the first + /// columns form the conflict target. The syntax is shared by SQLite ≥ 3.24 and PostgreSQL ≥ 9.5. + /// + public static string Upsert(string table, IReadOnlyList columns, int keyCount) + { + ArgumentOutOfRangeException.ThrowIfLessThan(keyCount, 1); + ArgumentOutOfRangeException.ThrowIfGreaterThan(keyCount, columns.Count); + var sb = new StringBuilder("INSERT INTO ").Append(table).Append(" (").AppendJoin(", ", columns).Append(") VALUES ("); + for (var i = 1; i <= columns.Count; i++) sb.Append(i > 1 ? ", $" : "$").Append(i); + sb.Append(") ON CONFLICT ("); + for (var i = 0; i < keyCount; i++) sb.Append(i > 0 ? ", " : string.Empty).Append(columns[i]); + if (keyCount == columns.Count) return sb.Append(") DO NOTHING").ToString(); + sb.Append(") DO UPDATE SET "); + for (var i = keyCount; i < columns.Count; i++) + sb.Append(i > keyCount ? ", " : string.Empty).Append(columns[i]).Append(" = excluded.").Append(columns[i]); + return sb.ToString(); + } + + /// Double-quotes an identifier (both dialects). + public static string QuoteIdentifier(string name) => "\"" + name.Replace("\"", "\"\"", StringComparison.Ordinal) + "\""; + + /// A LIKE … ESCAPE '\' pattern that matches anywhere. + public static string ContainsPattern(string text) + { + var sb = new StringBuilder(text.Length + 2).Append('%'); + foreach (var c in text) + { + if (c is '%' or '_' or '\\') sb.Append('\\'); + sb.Append(c); + } + return sb.Append('%').ToString(); + } +} diff --git a/src/Titano.Data/Sqlite/SqliteConnection.cs b/src/Titano.Data/Sqlite/SqliteConnection.cs new file mode 100644 index 00000000..b81c7f10 --- /dev/null +++ b/src/Titano.Data/Sqlite/SqliteConnection.cs @@ -0,0 +1,209 @@ +using System.Text; +using static Titano.Data.Sqlite.SqliteNative; + +namespace Titano.Data.Sqlite; + +/// One native SQLite connection with its pragmas and an LRU cache of prepared statements. +internal sealed unsafe class SqliteConnection : IDisposable +{ + private const int StatementCacheCapacity = 64; + private const string Pragmas = + "PRAGMA synchronous=NORMAL; PRAGMA foreign_keys=ON; PRAGMA temp_store=MEMORY; " + + "PRAGMA cache_size=-65536; PRAGMA mmap_size=268435456;"; + + private readonly Dictionary> _cache = new(StringComparer.Ordinal); + private readonly LinkedList _lru = new(); + + private SqliteConnection(nint handle) => Handle = handle; + + public nint Handle { get; private set; } + + public bool IsAutoCommit => sqlite3_get_autocommit(Handle) != 0; + + /// Rows changed by INSERT/UPDATE/DELETE since the connection opened (DDL does not count). + public int TotalChanges => sqlite3_total_changes(Handle); + + /// Rows changed by the most recent INSERT/UPDATE/DELETE. + public int Changes => sqlite3_changes(Handle); + + /// Opens a read-write connection and applies the BRIEF §6.2 pragmas (WAL only for files). + public static SqliteConnection Open(string filename, bool isMemory, int busyTimeoutMs) + { + var connection = OpenRaw(filename, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE | SQLITE_OPEN_URI | SQLITE_OPEN_NOMUTEX); + try + { + sqlite3_busy_timeout(connection.Handle, busyTimeoutMs); + connection.Exec(isMemory ? Pragmas : "PRAGMA journal_mode=WAL; " + Pragmas); + return connection; + } + catch + { + connection.Dispose(); + throw; + } + } + + public static SqliteConnection OpenReadOnly(string path) => + OpenRaw(path, SQLITE_OPEN_READONLY | SQLITE_OPEN_NOMUTEX); + + private static SqliteConnection OpenRaw(string filename, int flags) + { + nint db; + int rc; + fixed (byte* p = NullTerminated(filename)) rc = sqlite3_open_v2(p, out db, flags, null); + if (rc != SQLITE_OK) + { + var message = db != 0 ? Utf8(sqlite3_errmsg(db)) : null; + if (db != 0) sqlite3_close_v2(db); + throw new SqliteException($"Cannot open SQLite database '{filename}': {message ?? "error " + rc}", rc); + } + sqlite3_extended_result_codes(db, 1); + return new SqliteConnection(db); + } + + /// Runs one or more parameterless statements. + public void Exec(string sql) + { + byte* error; + int rc; + fixed (byte* p = NullTerminated(sql)) rc = sqlite3_exec(Handle, p, 0, 0, out error); + if (rc == SQLITE_OK) return; + var message = Utf8(error) ?? $"SQLite error {rc}"; + sqlite3_free(error); + throw new SqliteException(message, rc); + } + + /// Takes a statement from the cache (or prepares one); give it back with . + public SqliteStatement Rent(string sql) + { + if (_cache.TryGetValue(sql, out var node)) + { + if (!node.Value.InUse) + { + _lru.Remove(node); + _lru.AddFirst(node); + node.Value.InUse = true; + return node.Value; + } + // Same SQL already running on this connection (nested enumeration): use a private copy. + var copy = Prepare(sql); + copy.InUse = true; + return copy; + } + + var statement = Prepare(sql); + statement.InUse = true; + statement.Cached = true; + _cache[sql] = _lru.AddFirst(statement); + if (_lru.Count > StatementCacheCapacity && _lru.Last is { Value.InUse: false } last) + { + _lru.RemoveLast(); + _cache.Remove(last.Value.Sql); + last.Value.Dispose(); + } + return statement; + } + + public void Return(SqliteStatement statement) + { + statement.InUse = false; + if (statement.Cached) statement.Reset(); + else statement.Dispose(); + } + + public void Interrupt() => sqlite3_interrupt(Handle); + + public SqliteException Error(int rc) => new(Utf8(sqlite3_errmsg(Handle)) ?? $"SQLite error {rc}", rc); + + public void Dispose() + { + if (Handle == 0) return; + foreach (var statement in _lru) statement.Dispose(); + _lru.Clear(); + _cache.Clear(); + sqlite3_close_v2(Handle); + Handle = 0; + } + + private SqliteStatement Prepare(string sql) + { + var bytes = Encoding.UTF8.GetBytes(SqliteSqlText.TranslatePlaceholders(sql)); + fixed (byte* p = bytes) + { + var rc = sqlite3_prepare_v2(Handle, p, bytes.Length, out var statement, out var tail); + if (rc != SQLITE_OK) throw Error(rc); + if (statement == 0) throw new ArgumentException("The SQL text contains no statement.", nameof(sql)); + var rest = bytes.Length - (int)(tail - p); + if (rest > 0 && HasStatement(tail, rest)) + { + sqlite3_finalize(statement); + throw new ArgumentException("Only one statement per command is allowed; use ExecuteScriptAsync for scripts.", nameof(sql)); + } + return new SqliteStatement(this, statement, sql); + } + } + + /// True when the remaining text holds more than whitespace and comments. + private bool HasStatement(byte* text, int length) + { + var rc = sqlite3_prepare_v2(Handle, text, length, out var statement, out _); + if (statement != 0) sqlite3_finalize(statement); + return rc != SQLITE_OK || statement != 0; + } + + private static byte[] NullTerminated(string s) + { + var bytes = new byte[Encoding.UTF8.GetByteCount(s) + 1]; + Encoding.UTF8.GetBytes(s, bytes); + return bytes; + } +} + +/// Rewrites $n placeholders for SQLite, which numbers $name parameters by first appearance. +internal static class SqliteSqlText +{ + /// Turns $n into ?n outside string literals, quoted identifiers and comments. + public static string TranslatePlaceholders(string sql) + { + if (!sql.Contains('$', StringComparison.Ordinal)) return sql; + var sb = new StringBuilder(sql.Length); + var i = 0; + while (i < sql.Length) + { + var c = sql[i]; + var next = i + 1 < sql.Length ? sql[i + 1] : '\0'; + int end; + switch (c) + { + case '\'' or '"' or '`': + end = sql.IndexOf(c, i + 1); + break; + case '[': + end = sql.IndexOf(']', i + 1); + break; + case '-' when next == '-': + end = sql.IndexOf('\n', i + 2); + break; + case '/' when next == '*': + end = sql.IndexOf("*/", i + 2, StringComparison.Ordinal); + if (end >= 0) end++; + break; + case '$' when char.IsAsciiDigit(next) && (i == 0 || !IsIdentifierChar(sql[i - 1])): + sb.Append('?'); + i++; + continue; + default: + sb.Append(c); + i++; + continue; + } + // Copy the literal, identifier or comment verbatim (to the end of the text if unterminated). + end = end < 0 ? sql.Length : end + 1; + sb.Append(sql, i, end - i); + i = end; + } + return sb.ToString(); + } + + private static bool IsIdentifierChar(char c) => char.IsLetterOrDigit(c) || c is '_' or '$'; +} diff --git a/src/Titano.Data/Sqlite/SqliteDatabase.cs b/src/Titano.Data/Sqlite/SqliteDatabase.cs new file mode 100644 index 00000000..eb64e302 --- /dev/null +++ b/src/Titano.Data/Sqlite/SqliteDatabase.cs @@ -0,0 +1,265 @@ +using System.Globalization; +using System.Text.RegularExpressions; +using Titano.Core.Diagnostics; +using Titano.Core.IO; +using static Titano.Data.Sqlite.SqliteNative; + +namespace Titano.Data.Sqlite; + +/// Parsed SQLite connection string: Data Source=<path>|:memory:;Pool Size=4. +internal sealed record SqliteSettings(string DataSource, int PoolSize) +{ + public bool IsMemory => DataSource == ":memory:"; + + public static SqliteSettings Parse(string connectionString) + { + var cs = new ConnectionString(connectionString); + var source = cs.Get("Data Source", "DataSource", "Filename") + ?? throw new FormatException("A SQLite connection string needs 'Data Source'."); + var pool = cs.GetInt(4, "Pool Size", "Max Pool Size"); + cs.ThrowOnUnknownKeys(); + if (pool < 1) throw new FormatException("'Pool Size' must be at least 1."); + return new SqliteSettings(source, pool); + } +} + +/// +/// SQLite through the system library (BRIEF §6.2). Up to Pool Size connections serve concurrent +/// readers (WAL); writes are serialised in-process by one async write lock, so writers wait in a queue instead +/// of spinning on SQLITE_BUSY. In-memory databases use a single shared-cache connection. +/// +public sealed class SqliteDatabase : IDatabase +{ + /// 3.31.0, the oldest library accepted: it has UPSERT, NULLS LAST and VACUUM INTO. + public const int MinimumVersionNumber = 3_031_000; + + internal const int BusyTimeoutMs = 5000; + private const string LogCategory = "Data.Sqlite"; + + private readonly string _filename; + private readonly bool _memory; + private readonly int _maxConnections; + private readonly SemaphoreSlim _slots; + private readonly SemaphoreSlim _writeLock = new(1, 1); + private readonly Stack _idle = new(); + private readonly Lock _gate = new(); + private bool _disposed; + + private SqliteDatabase(SqliteSettings settings) + { + _memory = settings.IsMemory; + if (_memory) + { + _filename = $"file:titano-{Guid.NewGuid():N}?mode=memory&cache=shared"; + _maxConnections = 1; + } + else + { + Path = System.IO.Path.GetFullPath(settings.DataSource); + var directory = System.IO.Path.GetDirectoryName(Path); + if (!string.IsNullOrEmpty(directory)) Directory.CreateDirectory(directory); + _filename = Path; + _maxConnections = settings.PoolSize; + } + _slots = new SemaphoreSlim(_maxConnections, _maxConnections); + } + + public Dialect Dialect => Dialect.Sqlite; + + /// Full path of the database file; null for an in-memory database. + public string? Path { get; } + + /// Version string of the loaded SQLite library, e.g. "3.45.1". + public static string LibraryVersion + { + get + { + EnsureLibrary(); + unsafe + { + return Utf8(sqlite3_libversion()) ?? "?"; + } + } + } + + internal static SqliteDatabase Open(SqliteSettings settings) + { + EnsureLibrary(); + var database = new SqliteDatabase(settings); + // The first connection validates the path, switches the file to WAL and keeps a memory database alive. + database._idle.Push(database.CreateConnection()); + return database; + } + + public async Task OpenAsync(CancellationToken cancellationToken) + { + ObjectDisposedException.ThrowIf(_disposed, this); + await _slots.WaitAsync(cancellationToken).ConfigureAwait(false); + try + { + SqliteConnection? connection; + lock (_gate) _idle.TryPop(out connection); + return new SqliteSession(this, connection ?? CreateConnection()); + } + catch + { + _slots.Release(); + throw; + } + } + + /// + /// Writes a consistent copy with VACUUM INTO to as + /// <name>-yyyyMMdd-HHmmss-fff.db and deletes all but the newest copies. + /// Readers and writers continue meanwhile. Returns the new file. + /// + public async Task BackupAsync(string directory, int keep = 3, CancellationToken cancellationToken = default) + { + ArgumentOutOfRangeException.ThrowIfLessThan(keep, 1); + Directory.CreateDirectory(directory); + var stem = BackupStem; + string target; + while (true) + { + target = System.IO.Path.Combine(directory, string.Create(CultureInfo.InvariantCulture, $"{stem}-{DateTime.UtcNow:yyyyMMdd-HHmmss-fff}.db")); + if (!File.Exists(target)) break; + await Task.Delay(2, cancellationToken).ConfigureAwait(false); + } + var temp = target + ".tmp"; + await using (var session = (SqliteSession)await OpenAsync(cancellationToken).ConfigureAwait(false)) + await Task.Run(() => session.VacuumInto(temp, cancellationToken), cancellationToken).ConfigureAwait(false); + File.Move(temp, target); + + var pattern = new Regex("^" + Regex.Escape(stem) + @"-\d{8}-\d{6}-\d{3}\.db$", RegexOptions.CultureInvariant); + var backups = Directory.EnumerateFiles(directory) + .Where(f => pattern.IsMatch(System.IO.Path.GetFileName(f))) + .OrderByDescending(f => System.IO.Path.GetFileName(f), StringComparer.Ordinal) + .ToList(); + foreach (var old in backups.Skip(keep)) File.Delete(old); + Log.Info(LogCategory, $"Backup written to {target}"); + return target; + } + + /// + /// Replaces the database file with a backup after checking it with PRAGMA quick_check. Waits until + /// every session of this instance is returned; no other process may have the file open. + /// + public async Task RestoreAsync(string backupPath, CancellationToken cancellationToken = default) + { + if (Path is null) throw new NotSupportedException("An in-memory database cannot be restored."); + if (!File.Exists(backupPath)) throw new FileNotFoundException("Backup file not found.", backupPath); + Validate(backupPath); + + await _writeLock.WaitAsync(cancellationToken).ConfigureAwait(false); + var taken = 0; + try + { + for (; taken < _maxConnections; taken++) await _slots.WaitAsync(cancellationToken).ConfigureAwait(false); + lock (_gate) + { + while (_idle.TryPop(out var connection)) connection.Dispose(); + } + var temp = AtomicFile.TempPathFor(Path); + File.Copy(backupPath, temp); + // A WAL left behind belongs to the old file and would be replayed onto the restored one. + File.Delete(Path + "-wal"); + File.Delete(Path + "-shm"); + AtomicFile.Commit(temp, Path); + Log.Info(LogCategory, $"Database restored from {backupPath}"); + } + finally + { + if (taken > 0) _slots.Release(taken); + _writeLock.Release(); + } + } + + public ValueTask DisposeAsync() + { + lock (_gate) + { + if (_disposed) return ValueTask.CompletedTask; + _disposed = true; + while (_idle.TryPop(out var connection)) connection.Dispose(); + } + return ValueTask.CompletedTask; + } + + internal Task AcquireWriteAsync(CancellationToken cancellationToken) => _writeLock.WaitAsync(cancellationToken); + + internal void ReleaseWrite() => _writeLock.Release(); + + /// Takes back a session's connection; one left inside a transaction is rolled back or dropped. + internal void Return(SqliteConnection connection) + { + try + { + if (!connection.IsAutoCommit) + { + try + { + connection.Exec("ROLLBACK"); + } + catch (SqliteException ex) + { + Log.Warning(LogCategory, "Dropping a connection whose transaction could not be rolled back.", ex); + connection.Dispose(); + return; + } + } + lock (_gate) + { + if (_disposed) connection.Dispose(); + else _idle.Push(connection); + } + } + finally + { + _slots.Release(); + } + } + + private string BackupStem => Path is null ? "titano" : System.IO.Path.GetFileNameWithoutExtension(Path); + + private SqliteConnection CreateConnection() => SqliteConnection.Open(_filename, _memory, BusyTimeoutMs); + + private static void EnsureLibrary() + { + EnsureResolver(); + int version; + try + { + version = sqlite3_libversion_number(); + } + catch (DllNotFoundException ex) + { + throw new NotSupportedException("The system SQLite library was not found (winsqlite3.dll, libsqlite3.so.0 or libsqlite3.dylib).", ex); + } + if (version < MinimumVersionNumber) + throw new NotSupportedException($"SQLite {version / 1_000_000}.{version / 1000 % 1000}.{version % 1000} is too old; 3.31 or newer is required."); + } + + private static void Validate(string backupPath) + { + try + { + using var connection = SqliteConnection.OpenReadOnly(backupPath); + var statement = connection.Rent("PRAGMA quick_check"); + try + { + var rc = statement.Step(); + if (rc != SQLITE_ROW) throw connection.Error(rc); + var result = statement.ReadRow(statement.ReadColumns()).GetStringOrNull(0); + if (result != "ok") throw new InvalidDataException($"The backup failed its integrity check: {result}"); + } + finally + { + connection.Return(statement); + } + } + catch (SqliteException ex) + { + throw new InvalidDataException("The file is not a readable SQLite database.", ex); + } + } +} diff --git a/src/Titano.Data/Sqlite/SqliteException.cs b/src/Titano.Data/Sqlite/SqliteException.cs new file mode 100644 index 00000000..360c977f --- /dev/null +++ b/src/Titano.Data/Sqlite/SqliteException.cs @@ -0,0 +1,19 @@ +namespace Titano.Data.Sqlite; + +/// An error returned by SQLite, with its primary and extended result codes. +public sealed class SqliteException(string message, int extendedResultCode) : DatabaseException(message) +{ + /// Primary result code (low byte), e.g. 19 = SQLITE_CONSTRAINT. + public int ResultCode => ExtendedResultCode & 0xFF; + + /// Extended result code, e.g. 2067 = SQLITE_CONSTRAINT_UNIQUE. + public int ExtendedResultCode { get; } = extendedResultCode; + + public override int ErrorCode => ExtendedResultCode; + + public override bool IsTransient => ResultCode is SqliteNative.SQLITE_BUSY or SqliteNative.SQLITE_LOCKED; + + public override bool IsUniqueViolation => ExtendedResultCode is SqliteNative.SQLITE_CONSTRAINT_UNIQUE or SqliteNative.SQLITE_CONSTRAINT_PRIMARYKEY; + + public override bool IsForeignKeyViolation => ExtendedResultCode == SqliteNative.SQLITE_CONSTRAINT_FOREIGNKEY; +} diff --git a/src/Titano.Data/Sqlite/SqliteNative.cs b/src/Titano.Data/Sqlite/SqliteNative.cs new file mode 100644 index 00000000..95fe8590 --- /dev/null +++ b/src/Titano.Data/Sqlite/SqliteNative.cs @@ -0,0 +1,104 @@ +using System.Reflection; +using System.Runtime.InteropServices; + +namespace Titano.Data.Sqlite; + +/// +/// P/Invoke surface of the system SQLite library: winsqlite3.dll (Windows 10 1709+), libsqlite3.so.0 +/// (Linux) or libsqlite3.dylib (macOS). Strings cross the boundary as UTF-8 encoded by hand; the default +/// calling convention matches winsqlite3's __stdcall exports on x86 and is cdecl elsewhere. +/// +internal static unsafe class SqliteNative +{ + private const string Library = "titano-sqlite3"; + private static int _resolverInstalled; + + public const int SQLITE_OK = 0; + public const int SQLITE_ERROR = 1; + public const int SQLITE_INTERRUPT = 9; + public const int SQLITE_BUSY = 5; + public const int SQLITE_LOCKED = 6; + public const int SQLITE_CONSTRAINT = 19; + public const int SQLITE_ROW = 100; + public const int SQLITE_DONE = 101; + + public const int SQLITE_CONSTRAINT_FOREIGNKEY = SQLITE_CONSTRAINT | (3 << 8); + public const int SQLITE_CONSTRAINT_PRIMARYKEY = SQLITE_CONSTRAINT | (6 << 8); + public const int SQLITE_CONSTRAINT_UNIQUE = SQLITE_CONSTRAINT | (8 << 8); + + public const int SQLITE_OPEN_READONLY = 0x00000001; + public const int SQLITE_OPEN_READWRITE = 0x00000002; + public const int SQLITE_OPEN_CREATE = 0x00000004; + public const int SQLITE_OPEN_URI = 0x00000040; + public const int SQLITE_OPEN_NOMUTEX = 0x00008000; + + public const int SQLITE_INTEGER = 1; + public const int SQLITE_FLOAT = 2; + public const int SQLITE_TEXT = 3; + public const int SQLITE_BLOB = 4; + public const int SQLITE_NULL = 5; + + /// Destructor sentinel that makes SQLite copy bound text/blobs before the call returns. + public static readonly nint SQLITE_TRANSIENT = -1; + + /// Routes the logical library name to the platform's system SQLite (once per process). + public static void EnsureResolver() + { + if (Interlocked.Exchange(ref _resolverInstalled, 1) == 0) + NativeLibrary.SetDllImportResolver(typeof(SqliteNative).Assembly, Resolve); + } + + private static nint Resolve(string name, Assembly assembly, DllImportSearchPath? searchPath) + { + if (name != Library) return 0; + string[] candidates = OperatingSystem.IsWindows() ? ["winsqlite3.dll"] + : OperatingSystem.IsMacOS() ? ["libsqlite3.dylib", "/usr/lib/libsqlite3.dylib"] + : ["libsqlite3.so.0", "libsqlite3.so"]; + foreach (var candidate in candidates) + { + if (NativeLibrary.TryLoad(candidate, assembly, searchPath, out var handle)) return handle; + } + return 0; + } + + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_libversion_number(); + [DllImport(Library, ExactSpelling = true)] public static extern byte* sqlite3_libversion(); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_open_v2(byte* filename, out nint db, int flags, byte* vfs); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_close_v2(nint db); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_extended_result_codes(nint db, int onoff); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_busy_timeout(nint db, int ms); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_exec(nint db, byte* sql, nint callback, nint arg, out byte* errmsg); + [DllImport(Library, ExactSpelling = true)] public static extern void sqlite3_free(void* p); + [DllImport(Library, ExactSpelling = true)] public static extern byte* sqlite3_errmsg(nint db); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_extended_errcode(nint db); + [DllImport(Library, ExactSpelling = true)] public static extern void sqlite3_interrupt(nint db); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_changes(nint db); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_total_changes(nint db); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_get_autocommit(nint db); + + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_prepare_v2(nint db, byte* sql, int nBytes, out nint stmt, out byte* tail); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_step(nint stmt); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_reset(nint stmt); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_clear_bindings(nint stmt); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_finalize(nint stmt); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_stmt_readonly(nint stmt); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_bind_parameter_count(nint stmt); + + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_bind_null(nint stmt, int index); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_bind_int64(nint stmt, int index, long value); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_bind_double(nint stmt, int index, double value); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_bind_text(nint stmt, int index, byte* text, int nBytes, nint destructor); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_bind_blob(nint stmt, int index, void* data, int nBytes, nint destructor); + + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_column_count(nint stmt); + [DllImport(Library, ExactSpelling = true)] public static extern byte* sqlite3_column_name(nint stmt, int index); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_column_type(nint stmt, int index); + [DllImport(Library, ExactSpelling = true)] public static extern long sqlite3_column_int64(nint stmt, int index); + [DllImport(Library, ExactSpelling = true)] public static extern double sqlite3_column_double(nint stmt, int index); + [DllImport(Library, ExactSpelling = true)] public static extern byte* sqlite3_column_text(nint stmt, int index); + [DllImport(Library, ExactSpelling = true)] public static extern void* sqlite3_column_blob(nint stmt, int index); + [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_column_bytes(nint stmt, int index); + + /// Decodes a NUL-terminated UTF-8 string owned by SQLite. + public static string? Utf8(byte* p) => p is null ? null : Marshal.PtrToStringUTF8((nint)p); +} diff --git a/src/Titano.Data/Sqlite/SqliteSession.cs b/src/Titano.Data/Sqlite/SqliteSession.cs new file mode 100644 index 00000000..eeee6552 --- /dev/null +++ b/src/Titano.Data/Sqlite/SqliteSession.cs @@ -0,0 +1,315 @@ +using System.Runtime.CompilerServices; +using System.Text; +using static Titano.Data.Sqlite.SqliteNative; + +namespace Titano.Data.Sqlite; + +/// +/// A pooled SQLite connection. Statements that write take the database write lock for their duration when no +/// transaction holds it already; SQLITE_BUSY/LOCKED from other processes is retried a few times outside +/// transactions. Cancellation interrupts the running statement with sqlite3_interrupt. +/// +internal sealed class SqliteSession(SqliteDatabase database, SqliteConnection connection) : IDbSession +{ + private const int MaxBusyRetries = 3; + private SqliteTransaction? _transaction; + private bool _disposed; + + public Dialect Dialect => Dialect.Sqlite; + + public bool InTransaction => _transaction is not null; + + public async Task ExecuteAsync(string sql, DbParam[] parameters, CancellationToken cancellationToken) + { + ObjectDisposedException.ThrowIf(_disposed, this); + cancellationToken.ThrowIfCancellationRequested(); + var statement = connection.Rent(sql); + var locked = false; + try + { + statement.Bind(parameters); + if (!statement.IsReadOnly && _transaction is null) + { + await database.AcquireWriteAsync(cancellationToken).ConfigureAwait(false); + locked = true; + } + using var interrupt = RegisterInterrupt(cancellationToken); + var before = connection.TotalChanges; + while (await StepAsync(statement, _transaction is null, cancellationToken).ConfigureAwait(false) == SQLITE_ROW) + { + } + // sqlite3_changes keeps the last DML count across DDL; only trust it when this statement changed rows. + return connection.TotalChanges != before ? connection.Changes : 0; + } + finally + { + connection.Return(statement); + if (locked) database.ReleaseWrite(); + } + } + + public async IAsyncEnumerable QueryAsync(string sql, DbParam[] parameters, [EnumeratorCancellation] CancellationToken cancellationToken) + { + ObjectDisposedException.ThrowIf(_disposed, this); + cancellationToken.ThrowIfCancellationRequested(); + var statement = connection.Rent(sql); + var locked = false; + try + { + statement.Bind(parameters); + if (!statement.IsReadOnly && _transaction is null) + { + await database.AcquireWriteAsync(cancellationToken).ConfigureAwait(false); + locked = true; + } + using var interrupt = RegisterInterrupt(cancellationToken); + DbColumns? columns = null; + var retry = _transaction is null; + while (await StepAsync(statement, retry, cancellationToken).ConfigureAwait(false) == SQLITE_ROW) + { + retry = false; // restarting after rows were yielded would repeat them + columns ??= statement.ReadColumns(); + yield return statement.ReadRow(columns); + cancellationToken.ThrowIfCancellationRequested(); + } + } + finally + { + connection.Return(statement); + if (locked) database.ReleaseWrite(); + } + } + + public async Task ExecuteScriptAsync(string script, CancellationToken cancellationToken) + { + ObjectDisposedException.ThrowIf(_disposed, this); + cancellationToken.ThrowIfCancellationRequested(); + var locked = _transaction is null; + if (locked) await database.AcquireWriteAsync(cancellationToken).ConfigureAwait(false); + try + { + using var interrupt = RegisterInterrupt(cancellationToken); + connection.Exec(script); + } + catch (SqliteException ex) when (ex.ResultCode == SQLITE_INTERRUPT && cancellationToken.IsCancellationRequested) + { + throw new OperationCanceledException(ex.Message, ex, cancellationToken); + } + finally + { + if (locked) database.ReleaseWrite(); + } + } + + public async Task BeginAsync(CancellationToken cancellationToken) + { + ObjectDisposedException.ThrowIf(_disposed, this); + if (_transaction is not null) throw new InvalidOperationException("A transaction is already active on this session."); + await database.AcquireWriteAsync(cancellationToken).ConfigureAwait(false); + try + { + await RunAsync("BEGIN IMMEDIATE", retryBusy: true, cancellationToken).ConfigureAwait(false); + } + catch + { + database.ReleaseWrite(); + throw; + } + return _transaction = new SqliteTransaction(this); + } + + public async Task BulkInsertAsync(string table, IReadOnlyList columns, IAsyncEnumerable rows, CancellationToken cancellationToken) + { + ObjectDisposedException.ThrowIf(_disposed, this); + if (columns.Count == 0) throw new ArgumentException("At least one column is required.", nameof(columns)); + // 999 is the variable limit of SQLite builds before 3.32. + var rowsPerStatement = Math.Clamp(999 / columns.Count, 1, 100); + var buffer = new object?[rowsPerStatement * columns.Count]; + var ownTransaction = _transaction is null ? await BeginAsync(cancellationToken).ConfigureAwait(false) : null; + try + { + long total = 0; + var buffered = 0; + using (RegisterInterrupt(cancellationToken)) + { + await foreach (var row in rows.WithCancellation(cancellationToken).ConfigureAwait(false)) + { + if (row.Length != columns.Count) + throw new ArgumentException($"A row has {row.Length} values for {columns.Count} columns.", nameof(rows)); + Array.Copy(row, 0, buffer, buffered * columns.Count, row.Length); + if (++buffered == rowsPerStatement) + { + await InsertBufferedAsync(table, columns, buffer, buffered, cancellationToken).ConfigureAwait(false); + total += buffered; + buffered = 0; + } + } + if (buffered > 0) + { + await InsertBufferedAsync(table, columns, buffer, buffered, cancellationToken).ConfigureAwait(false); + total += buffered; + } + } + if (ownTransaction is not null) await ownTransaction.CommitAsync(cancellationToken).ConfigureAwait(false); + return total; + } + finally + { + if (ownTransaction is not null) await ownTransaction.DisposeAsync().ConfigureAwait(false); + } + } + + public async ValueTask DisposeAsync() + { + if (_disposed) return; + _disposed = true; + if (_transaction is { } transaction) + { + try + { + await EndTransactionAsync(transaction, commit: false, CancellationToken.None).ConfigureAwait(false); + } + catch (SqliteException) + { + // The pool rolls the connection back or drops it below. + } + if (_transaction is not null) + { + _transaction = null; + database.ReleaseWrite(); + } + } + database.Return(connection); + } + + /// Ends if it is still the active one; a failed COMMIT leaves it open for rollback. + internal async Task EndTransactionAsync(SqliteTransaction transaction, bool commit, CancellationToken cancellationToken) + { + if (_transaction != transaction) return; + try + { + await RunAsync(commit ? "COMMIT" : "ROLLBACK", retryBusy: commit, cancellationToken).ConfigureAwait(false); + } + finally + { + if (connection.IsAutoCommit) + { + _transaction = null; + database.ReleaseWrite(); + } + } + } + + /// Runs VACUUM INTO (backups); it only reads, so no write lock is taken. + internal void VacuumInto(string path, CancellationToken cancellationToken) + { + var statement = connection.Rent("VACUUM INTO $1"); + try + { + statement.Bind([path]); + using var interrupt = RegisterInterrupt(cancellationToken); + var rc = statement.Step(); + if (rc == SQLITE_DONE) return; + if ((rc & 0xFF) == SQLITE_INTERRUPT && cancellationToken.IsCancellationRequested) throw new OperationCanceledException(cancellationToken); + throw connection.Error(rc); + } + finally + { + connection.Return(statement); + } + } + + private async Task InsertBufferedAsync(string table, IReadOnlyList columns, object?[] buffer, int rowCount, CancellationToken cancellationToken) + { + var statement = connection.Rent(InsertSql(table, columns, rowCount)); + try + { + for (var i = 0; i < rowCount * columns.Count; i++) statement.BindValue(i + 1, buffer[i]); + await StepAsync(statement, retryBusy: false, cancellationToken).ConfigureAwait(false); + } + finally + { + connection.Return(statement); + } + } + + private static string InsertSql(string table, IReadOnlyList columns, int rowCount) + { + var sb = new StringBuilder("INSERT INTO ").Append(SqlDialect.QuoteIdentifier(table)).Append(" ("); + for (var c = 0; c < columns.Count; c++) sb.Append(c > 0 ? ", " : string.Empty).Append(SqlDialect.QuoteIdentifier(columns[c])); + sb.Append(") VALUES "); + var n = 1; + for (var r = 0; r < rowCount; r++) + { + sb.Append(r > 0 ? ", (" : "("); + for (var c = 0; c < columns.Count; c++) sb.Append(c > 0 ? ", ?" : "?").Append(n++); + sb.Append(')'); + } + return sb.ToString(); + } + + private async Task RunAsync(string sql, bool retryBusy, CancellationToken cancellationToken) + { + var statement = connection.Rent(sql); + try + { + await StepAsync(statement, retryBusy, cancellationToken).ConfigureAwait(false); + } + finally + { + connection.Return(statement); + } + } + + private async ValueTask StepAsync(SqliteStatement statement, bool retryBusy, CancellationToken cancellationToken) + { + for (var attempt = 0; ; attempt++) + { + var rc = statement.Step(); + if (rc is SQLITE_ROW or SQLITE_DONE) return rc; + var primary = rc & 0xFF; + if (primary == SQLITE_INTERRUPT && cancellationToken.IsCancellationRequested) + throw new OperationCanceledException(cancellationToken); + if (retryBusy && primary is SQLITE_BUSY or SQLITE_LOCKED && attempt < MaxBusyRetries) + { + // busy_timeout already waited; another process holds the lock for long. Back off and restart. + statement.Rewind(); + await Task.Delay(50 * (attempt + 1) + Random.Shared.Next(50), cancellationToken).ConfigureAwait(false); + continue; + } + throw connection.Error(rc); + } + } + + private CancellationTokenRegistration RegisterInterrupt(CancellationToken cancellationToken) => + cancellationToken.CanBeCanceled + ? cancellationToken.UnsafeRegister(static state => ((SqliteConnection)state!).Interrupt(), connection) + : default; +} + +/// A BEGIN IMMEDIATE transaction holding the database write lock until it ends. +internal sealed class SqliteTransaction(SqliteSession session) : IDbTransaction +{ + private bool _completed; + + public async Task CommitAsync(CancellationToken cancellationToken = default) + { + ObjectDisposedException.ThrowIf(_completed, this); + await session.EndTransactionAsync(this, commit: true, cancellationToken).ConfigureAwait(false); + _completed = true; + } + + public async Task RollbackAsync(CancellationToken cancellationToken = default) + { + ObjectDisposedException.ThrowIf(_completed, this); + _completed = true; + await session.EndTransactionAsync(this, commit: false, cancellationToken).ConfigureAwait(false); + } + + public async ValueTask DisposeAsync() + { + if (_completed) return; + _completed = true; + await session.EndTransactionAsync(this, commit: false, CancellationToken.None).ConfigureAwait(false); + } +} diff --git a/src/Titano.Data/Sqlite/SqliteStatement.cs b/src/Titano.Data/Sqlite/SqliteStatement.cs new file mode 100644 index 00000000..3b96b7d2 --- /dev/null +++ b/src/Titano.Data/Sqlite/SqliteStatement.cs @@ -0,0 +1,170 @@ +using System.Buffers; +using System.Globalization; +using System.Text; +using static Titano.Data.Sqlite.SqliteNative; + +namespace Titano.Data.Sqlite; + +/// A prepared statement owned by one ; reused through its statement cache. +internal sealed unsafe class SqliteStatement : IDisposable +{ + private const int StackTextBytes = 256; + private readonly SqliteConnection _connection; + + public SqliteStatement(SqliteConnection connection, nint handle, string sql) + { + _connection = connection; + Handle = handle; + Sql = sql; + IsReadOnly = sqlite3_stmt_readonly(handle) != 0; + ParameterCount = sqlite3_bind_parameter_count(handle); + } + + public nint Handle { get; private set; } + + /// The SQL text as the caller wrote it (cache key). + public string Sql { get; } + + /// The statement does not write the database (no write lock needed). + public bool IsReadOnly { get; } + + /// Highest parameter number used by the statement. + public int ParameterCount { get; } + + public bool InUse { get; set; } + + public bool Cached { get; set; } + + public void Bind(DbParam[] parameters) + { + if (parameters.Length != ParameterCount) + throw new ArgumentException($"The statement uses {ParameterCount} parameter(s) but {parameters.Length} were supplied.", nameof(parameters)); + for (var i = 0; i < parameters.Length; i++) Bind(i + 1, parameters[i].Value, parameters[i].Type); + } + + /// Binds a raw CLR value (bulk insert rows); the type is inferred like does. + public void BindValue(int index, object? value) => Bind(index, value, DbValueType.Auto); + + public int Step() => sqlite3_step(Handle); + + /// Rewinds for another execution with the same bindings. + public void Rewind() => sqlite3_reset(Handle); + + /// Rewinds after an execution; a step error was already reported, so the code is ignored. + public void Reset() + { + sqlite3_reset(Handle); + sqlite3_clear_bindings(Handle); + } + + public DbColumns ReadColumns() + { + var names = new string[sqlite3_column_count(Handle)]; + for (var i = 0; i < names.Length; i++) names[i] = Utf8(sqlite3_column_name(Handle, i)) ?? string.Empty; + return new DbColumns(names); + } + + public DbRow ReadRow(DbColumns columns) + { + var values = new object?[columns.Names.Length]; + for (var i = 0; i < values.Length; i++) + { + values[i] = sqlite3_column_type(Handle, i) switch + { + SQLITE_INTEGER => sqlite3_column_int64(Handle, i), + SQLITE_FLOAT => sqlite3_column_double(Handle, i), + SQLITE_TEXT => ReadText(i), + SQLITE_BLOB => ReadBlob(i), + _ => null, + }; + } + return new DbRow(columns, values); + } + + public void Dispose() + { + if (Handle != 0) + { + sqlite3_finalize(Handle); + Handle = 0; + } + } + + private void Bind(int index, object? value, DbValueType type) + { + var rc = value switch + { + null => sqlite3_bind_null(Handle, index), + string s => BindText(index, s), + long l => sqlite3_bind_int64(Handle, index, l), + int n => sqlite3_bind_int64(Handle, index, n), + double d => sqlite3_bind_double(Handle, index, d), + bool b => sqlite3_bind_int64(Handle, index, b ? 1 : 0), + Guid g => BindFormatted(index, g, "D"), + DateTimeOffset o => BindFormatted(index, o.UtcDateTime, "yyyy-MM-dd'T'HH:mm:ss.ffffff'Z'"), + DateTime d when type == DbValueType.LocalDateTime || (type == DbValueType.Auto && d.Kind == DateTimeKind.Unspecified) + => BindFormatted(index, d, "yyyy-MM-dd'T'HH:mm:ss.ffffff"), + DateTime d => BindFormatted(index, d.ToUniversalTime(), "yyyy-MM-dd'T'HH:mm:ss.ffffff'Z'"), + byte[] b => BindBlob(index, b), + _ => BindNormalized(index, new DbParam(value)), + }; + if (rc != SQLITE_OK) throw _connection.Error(rc); + } + + private int BindNormalized(int index, DbParam p) + { + Bind(index, p.Value, p.Type); + return SQLITE_OK; + } + + private int BindText(int index, string s) + { + if (s.Length <= StackTextBytes / 3) + { + var buffer = stackalloc byte[StackTextBytes]; + var n = Encoding.UTF8.GetBytes(s, new Span(buffer, StackTextBytes)); + return sqlite3_bind_text(Handle, index, buffer, n, SQLITE_TRANSIENT); + } + var rented = ArrayPool.Shared.Rent(Encoding.UTF8.GetByteCount(s)); + try + { + var n = Encoding.UTF8.GetBytes(s, rented); + fixed (byte* p = rented) return sqlite3_bind_text(Handle, index, p, n, SQLITE_TRANSIENT); + } + finally + { + ArrayPool.Shared.Return(rented); + } + } + + private int BindFormatted(int index, T value, string format) where T : IUtf8SpanFormattable + { + var buffer = stackalloc byte[64]; + var span = new Span(buffer, 64); + if (!value.TryFormat(span, out var n, format, CultureInfo.InvariantCulture)) + throw new FormatException($"Cannot format {value} for SQLite."); + return sqlite3_bind_text(Handle, index, buffer, n, SQLITE_TRANSIENT); + } + + private int BindBlob(int index, byte[] data) + { + byte empty = 0; + // A null pointer would bind NULL; an empty blob needs any valid address. + if (data.Length == 0) return sqlite3_bind_blob(Handle, index, &empty, 0, SQLITE_TRANSIENT); + fixed (byte* p = data) return sqlite3_bind_blob(Handle, index, p, data.Length, SQLITE_TRANSIENT); + } + + private string ReadText(int column) + { + var p = sqlite3_column_text(Handle, column); + var n = sqlite3_column_bytes(Handle, column); + return n == 0 ? string.Empty : Encoding.UTF8.GetString(p, n); + } + + private byte[] ReadBlob(int column) + { + var p = (byte*)sqlite3_column_blob(Handle, column); + var n = sqlite3_column_bytes(Handle, column); + return n == 0 ? [] : new ReadOnlySpan(p, n).ToArray(); + } +} diff --git a/src/Titano.Data/TextValues.cs b/src/Titano.Data/TextValues.cs new file mode 100644 index 00000000..cb1143fa --- /dev/null +++ b/src/Titano.Data/TextValues.cs @@ -0,0 +1,135 @@ +using System.Globalization; + +namespace Titano.Data; + +/// +/// Canonical text forms of values without a native SQLite type, also used for PostgreSQL text parameters. +/// Date-times are fixed-width ISO-8601 with microseconds, so text order equals chronological order. +/// +internal static class TextValues +{ + private const string TimestampFormat = "yyyy-MM-dd'T'HH:mm:ss.ffffff'Z'"; + private const string LocalFormat = "yyyy-MM-dd'T'HH:mm:ss.ffffff"; + + public static string FormatTimestamp(DateTimeOffset value) => value.UtcDateTime.ToString(TimestampFormat, CultureInfo.InvariantCulture); + + public static string FormatLocal(DateTime value) => value.ToString(LocalFormat, CultureInfo.InvariantCulture); + + public static string FormatGuid(Guid value) => value.ToString("D"); + + /// Parses an ISO-8601 or PostgreSQL timestamp; a missing offset means UTC. + public static DateTimeOffset ParseTimestamp(ReadOnlySpan text) + { + if (!TryParse(text, out var value, out var offset)) + throw new FormatException($"Invalid timestamp '{text}'."); + if (value == DateTime.MaxValue || value == DateTime.MinValue) + return new DateTimeOffset(value, TimeSpan.Zero); + return new DateTimeOffset(DateTime.SpecifyKind(value - (offset ?? TimeSpan.Zero), DateTimeKind.Utc)); + } + + /// Parses a wall-clock date-time (unspecified kind); a value carrying an offset is returned in UTC. + public static DateTime ParseLocal(ReadOnlySpan text) + { + if (!TryParse(text, out var value, out var offset)) + throw new FormatException($"Invalid date-time '{text}'."); + return offset is { } o ? DateTime.SpecifyKind(value - o, DateTimeKind.Utc) : value; + } + + /// Accepts yyyy-MM-dd[(T| )HH:mm[:ss[.f…]]][Z|±HH[[:]mm[[:]ss]]] and ±infinity. + private static bool TryParse(ReadOnlySpan s, out DateTime value, out TimeSpan? offset) + { + value = default; + offset = null; + s = s.Trim(); + if (s.SequenceEqual("infinity")) + { + value = DateTime.MaxValue; + return true; + } + if (s.SequenceEqual("-infinity")) + { + value = DateTime.MinValue; + return true; + } + if (s.Length < 10 || s[4] != '-' || s[7] != '-' + || !Digits(s[..4], out var year) || !Digits(s.Slice(5, 2), out var month) || !Digits(s.Slice(8, 2), out var day)) + return false; + + int hour = 0, minute = 0, second = 0; + long fraction = 0; + var i = 10; + if (i < s.Length && s[i] is 'T' or ' ') + { + if (s.Length < i + 6 || s[i + 3] != ':' || !Digits(s.Slice(i + 1, 2), out hour) || !Digits(s.Slice(i + 4, 2), out minute)) + return false; + i += 6; + if (i < s.Length && s[i] == ':') + { + if (s.Length < i + 3 || !Digits(s.Slice(i + 1, 2), out second)) + return false; + i += 3; + if (i < s.Length && s[i] == '.') + { + var start = ++i; + var digits = 0; + for (; i < s.Length && char.IsAsciiDigit(s[i]); i++) + { + if (digits++ < 7) fraction = fraction * 10 + (s[i] - '0'); + } + if (i == start) return false; + for (; digits < 7; digits++) fraction *= 10; + } + } + } + + if (i < s.Length) + { + if (s[i] == 'Z' && i == s.Length - 1) + { + offset = TimeSpan.Zero; + } + else if (s[i] is '+' or '-') + { + var negative = s[i++] == '-'; + if (!OffsetPart(s, ref i, out var oh, colon: false)) return false; + var om = 0; + var os = 0; + if (i < s.Length && !OffsetPart(s, ref i, out om, colon: true)) return false; + if (i < s.Length && !OffsetPart(s, ref i, out os, colon: true)) return false; + if (i != s.Length) return false; + var span = new TimeSpan(oh, om, os); + offset = negative ? -span : span; + } + else + { + return false; + } + } + + if (year < 1 || month is < 1 or > 12 || day < 1 || day > DateTime.DaysInMonth(year, month) + || hour > 23 || minute > 59 || second > 59) + return false; + value = new DateTime(year, month, day, hour, minute, second, DateTimeKind.Unspecified).AddTicks(fraction); + return true; + } + + private static bool OffsetPart(ReadOnlySpan s, ref int i, out int value, bool colon) + { + if (colon && s[i] == ':') i++; + value = 0; + if (s.Length < i + 2 || !Digits(s.Slice(i, 2), out value)) return false; + i += 2; + return true; + } + + private static bool Digits(ReadOnlySpan s, out int value) + { + value = 0; + foreach (var c in s) + { + if (!char.IsAsciiDigit(c)) return false; + value = value * 10 + (c - '0'); + } + return true; + } +}