@opengroundplan/core 0.1.1

package/templates/layers/db-sqlite/files/src/__solutionName.dot__.Persistence.Sqlite/SqliteMigrator.cs

@@ -0,0 +1,99 @@
+using Microsoft.Data.Sqlite;
+
+namespace {{ solutionName | dot }}.Persistence.Sqlite;
+
+public sealed record MigrationResult(IReadOnlyList<string> Applied, int AlreadyApplied);
+
+/// <summary>
+/// Forward-only plain-SQL migrations: every unseen *.sql in filename order, one
+/// transaction per file, recorded in schema_migrations. See docs/db/sqlite.md.
+/// </summary>
+public static class SqliteMigrator
+{
+    private const string Ledger = "schema_migrations";
+
+    public static async Task<MigrationResult> MigrateAsync(
+        SqliteConnection connection,
+        string directory,
+        CancellationToken cancellationToken = default)
+    {
+        await ExecuteAsync(
+            connection,
+            $"CREATE TABLE IF NOT EXISTS {Ledger} (name TEXT PRIMARY KEY, applied_at TEXT NOT NULL DEFAULT (datetime('now')));",
+            cancellationToken);
+
+        var done = await AppliedNamesAsync(connection, cancellationToken);
+        var applied = new List<string>();
+
+        foreach (var name in Pending(directory, done))
+        {
+            var sql = await File.ReadAllTextAsync(Path.Combine(directory, name), cancellationToken);
+            await ApplyOneAsync(connection, name, sql, cancellationToken);
+            applied.Add(name);
+        }
+
+        return new MigrationResult(applied, done.Count);
+    }
+
+    private static async Task ApplyOneAsync(
+        SqliteConnection connection,
+        string name,
+        string sql,
+        CancellationToken cancellationToken)
+    {
+        await using var transaction = await connection.BeginTransactionAsync(cancellationToken);
+
+        await using (var script = connection.CreateCommand())
+        {
+            script.CommandText = sql;
+            await script.ExecuteNonQueryAsync(cancellationToken);
+        }
+
+        await using (var record = connection.CreateCommand())
+        {
+            record.CommandText = $"INSERT INTO {Ledger} (name) VALUES ($name);";
+            record.Parameters.AddWithValue("$name", name);
+            await record.ExecuteNonQueryAsync(cancellationToken);
+        }
+
+        await transaction.CommitAsync(cancellationToken);
+    }
+
+    private static IEnumerable<string> Pending(string directory, HashSet<string> done)
+    {
+        if (!Directory.Exists(directory))
+        {
+            return [];
+        }
+
+        return Directory.EnumerateFiles(directory, "*.sql")
+            .Select(Path.GetFileName)
+            .OfType<string>()
+            .Where(name => !done.Contains(name))
+            .OrderBy(name => name, StringComparer.Ordinal);
+    }
+
+    private static async Task<HashSet<string>> AppliedNamesAsync(
+        SqliteConnection connection,
+        CancellationToken cancellationToken)
+    {
+        var names = new HashSet<string>(StringComparer.Ordinal);
+
+        await using var command = connection.CreateCommand();
+        command.CommandText = $"SELECT name FROM {Ledger};";
+        await using var reader = await command.ExecuteReaderAsync(cancellationToken);
+        while (await reader.ReadAsync(cancellationToken))
+        {
+            names.Add(reader.GetString(0));
+        }
+
+        return names;
+    }
+
+    private static async Task ExecuteAsync(SqliteConnection connection, string sql, CancellationToken cancellationToken)
+    {
+        await using var command = connection.CreateCommand();
+        command.CommandText = sql;
+        await command.ExecuteNonQueryAsync(cancellationToken);
+    }
+}

package/templates/layers/db-sqlite/files/src/__solutionName.dot__.Persistence.Sqlite/SqliteOptions.cs

@@ -0,0 +1,81 @@
+namespace {{ solutionName | dot }}.Persistence.Sqlite;
+
+/// <summary>The one place a SQLite default may appear.</summary>
+public sealed record SqliteOptions
+{
+    // Protocol literals from the SQLite pragma spec, not tunables.
+    private static readonly string[] JournalModes = ["DELETE", "TRUNCATE", "PERSIST", "MEMORY", "WAL", "OFF"];
+    private static readonly string[] SynchronousLevels = ["OFF", "NORMAL", "FULL", "EXTRA"];
+    private static readonly string[] TruthyValues = ["1", "true", "yes", "on"];
+
+    public string File { get; init; } = "{{ sqliteFile }}";
+    public int BusyTimeoutMs { get; init; } = 5000;
+    public string JournalMode { get; init; } = "WAL";
+    public string Synchronous { get; init; } = "NORMAL";
+    public bool ForeignKeys { get; init; } = true;
+    public string MigrationsDir { get; init; } = "migrations";
+
+    /// <summary>Each in-memory connection gets its own empty database, so journaling does not apply.</summary>
+    public bool IsInMemory =>
+        File == ":memory:"
+        || File.StartsWith("file::memory:", StringComparison.Ordinal)
+        || File.Contains("mode=memory", StringComparison.Ordinal);
+
+    public static SqliteOptions FromEnvironment(IDictionary<string, string?>? env = null)
+    {
+        string? Read(string key)
+        {
+            string? value = null;
+            if (env is null)
+            {
+                value = Environment.GetEnvironmentVariable(key);
+            }
+            else
+            {
+                env.TryGetValue(key, out value);
+            }
+            return string.IsNullOrWhiteSpace(value) ? null : value.Trim();
+        }
+
+        var fallback = new SqliteOptions();
+        return fallback with
+        {
+            File = Read("SQLITE_FILE") ?? fallback.File,
+            BusyTimeoutMs = Integer(Read("SQLITE_BUSY_TIMEOUT_MS"), "SQLITE_BUSY_TIMEOUT_MS", fallback.BusyTimeoutMs),
+            JournalMode = OneOf(Read("SQLITE_JOURNAL_MODE"), "SQLITE_JOURNAL_MODE", JournalModes, fallback.JournalMode),
+            Synchronous = OneOf(Read("SQLITE_SYNCHRONOUS"), "SQLITE_SYNCHRONOUS", SynchronousLevels, fallback.Synchronous),
+            ForeignKeys = Boolean(Read("SQLITE_FOREIGN_KEYS"), fallback.ForeignKeys),
+            MigrationsDir = Read("SQLITE_MIGRATIONS_DIR") ?? fallback.MigrationsDir,
+        };
+    }
+
+    private static int Integer(string? raw, string key, int fallback)
+    {
+        if (raw is null)
+        {
+            return fallback;
+        }
+        if (!int.TryParse(raw, out var value) || value < 0)
+        {
+            throw new InvalidOperationException($"{key} must be a non-negative integer, got '{raw}'.");
+        }
+        return value;
+    }
+
+    private static bool Boolean(string? raw, bool fallback) =>
+        raw is null ? fallback : TruthyValues.Contains(raw.ToLowerInvariant());
+
+    private static string OneOf(string? raw, string key, string[] allowed, string fallback)
+    {
+        if (raw is null)
+        {
+            return fallback;
+        }
+        var upper = raw.ToUpperInvariant();
+        if (!allowed.Contains(upper))
+        {
+            throw new InvalidOperationException($"{key} must be one of {string.Join(", ", allowed)}, got '{raw}'.");
+        }
+        return upper;
+    }
+}

package/templates/layers/db-sqlite/files/src/__solutionName.dot__.Persistence.Sqlite/__solutionName.dot__.Persistence.Sqlite.csproj

@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>{{ dotnetTargetFramework }}</TargetFramework>
+    <RootNamespace>{{ solutionName | dot }}.Persistence.Sqlite</RootNamespace>
+    <AssemblyName>{{ solutionName | dot }}.Persistence.Sqlite</AssemblyName>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Data.Sqlite" />
+    <!-- Overrides the transitive 2.1.11, which carries GHSA-2m69-gcr7-jv3q. -->
+    <PackageReference Include="SQLitePCLRaw.bundle_e_sqlite3" />
+  </ItemGroup>
+
+</Project>

package/templates/layers/db-sqlite/files/src/__solutionName.snake__/db/sqlite/connection.py

@@ -0,0 +1,49 @@
+"""Async SQLite connections with the pragmas SQLite does not enable on its own."""
+
+import sqlite3
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import AsyncIterator
+
+import aiosqlite
+
+from .settings import SqliteSettings, is_in_memory, load_sqlite_settings
+
+
+async def _configure(connection: aiosqlite.Connection, settings: SqliteSettings) -> None:
+    await connection.execute(f"PRAGMA busy_timeout = {settings.busy_timeout_ms}")
+    await connection.execute(f"PRAGMA foreign_keys = {'ON' if settings.foreign_keys else 'OFF'}")
+    if not is_in_memory(settings.file):
+        await connection.execute(f"PRAGMA journal_mode = {settings.journal_mode}")
+        await connection.execute(f"PRAGMA synchronous = {settings.synchronous}")
+
+
+async def open_database(settings: SqliteSettings | None = None) -> aiosqlite.Connection:
+    resolved = settings or load_sqlite_settings()
+    if not is_in_memory(resolved.file):
+        Path(resolved.file).resolve().parent.mkdir(parents=True, exist_ok=True)
+
+    connection = await aiosqlite.connect(resolved.file)
+    connection.row_factory = sqlite3.Row
+    await _configure(connection, resolved)
+    return connection
+
+
+@asynccontextmanager
+async def connection(settings: SqliteSettings | None = None) -> AsyncIterator[aiosqlite.Connection]:
+    """Commits on clean exit, rolls back on any exception."""
+    handle = await open_database(settings)
+    try:
+        yield handle
+        await handle.commit()
+    except BaseException:
+        await handle.rollback()
+        raise
+    finally:
+        await handle.close()
+
+
+async def backup_to(handle: aiosqlite.Connection, destination: str) -> None:
+    """Copies a live database safely; copying the file can capture a torn WAL state."""
+    Path(destination).resolve().parent.mkdir(parents=True, exist_ok=True)
+    await handle.execute("VACUUM INTO ?", (destination,))

package/templates/layers/db-sqlite/files/src/__solutionName.snake__/db/sqlite/health.py

@@ -0,0 +1,36 @@
+"""Liveness and integrity probes."""
+
+import time
+from dataclasses import dataclass
+
+import aiosqlite
+
+
+@dataclass(frozen=True, slots=True)
+class DatabaseHealth:
+    ok: bool
+    latency_ms: float
+    engine: str = "sqlite"
+    error: str | None = None
+
+
+async def check_health(handle: aiosqlite.Connection) -> DatabaseHealth:
+    """Cheap probe for readiness endpoints — proves the file is open and readable."""
+    started = time.perf_counter()
+    try:
+        async with handle.execute("SELECT 1") as cursor:
+            await cursor.fetchone()
+    except Exception as error:
+        return DatabaseHealth(ok=False, latency_ms=_elapsed(started), error=str(error))
+    return DatabaseHealth(ok=True, latency_ms=_elapsed(started))
+
+
+async def check_integrity(handle: aiosqlite.Connection) -> bool:
+    """Full file scan — run on demand or on a schedule, never in a readiness probe."""
+    async with handle.execute("PRAGMA integrity_check") as cursor:
+        row = await cursor.fetchone()
+    return bool(row) and row[0] == "ok"
+
+
+def _elapsed(started: float) -> float:
+    return (time.perf_counter() - started) * 1000

package/templates/layers/db-sqlite/files/src/__solutionName.snake__/db/sqlite/migrate.py

@@ -0,0 +1,58 @@
+"""Forward-only plain-SQL migrations. See docs/db/sqlite.md for the rules."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import aiosqlite
+
+from .settings import load_sqlite_settings
+
+LEDGER = "schema_migrations"
+
+
+@dataclass(frozen=True, slots=True)
+class MigrationResult:
+    applied: tuple[str, ...]
+    already_applied: int
+
+
+async def _pending(handle: aiosqlite.Connection, directory: Path) -> list[str]:
+    if not directory.is_dir():
+        return []
+    async with handle.execute(f"SELECT name FROM {LEDGER}") as cursor:
+        done = {row[0] for row in await cursor.fetchall()}
+    return sorted(p.name for p in directory.glob("*.sql") if p.name not in done)
+
+
+async def migrate(handle: aiosqlite.Connection, directory: str | None = None) -> MigrationResult:
+    """Applies every unseen *.sql in filename order.
+
+    executescript commits before it runs, so a failing migration leaves the file's own
+    statements to SQLite's per-statement atomicity and the ledger row unwritten — rerun
+    after fixing, and keep each migration idempotent (CREATE TABLE IF NOT EXISTS).
+    """
+    path = Path(directory or load_sqlite_settings().migrations_dir)
+
+    await handle.execute(
+        f"CREATE TABLE IF NOT EXISTS {LEDGER} ("
+        " name TEXT PRIMARY KEY,"
+        " applied_at TEXT NOT NULL DEFAULT (datetime('now')))"
+    )
+    await handle.commit()
+
+    async with handle.execute(f"SELECT count(*) FROM {LEDGER}") as cursor:
+        before = (await cursor.fetchone())[0]
+
+    applied: list[str] = []
+    for name in await _pending(handle, path):
+        sql = (path / name).read_text(encoding="utf-8")
+        try:
+            await handle.executescript(sql)
+            await handle.execute(f"INSERT INTO {LEDGER} (name) VALUES (?)", (name,))
+            await handle.commit()
+        except Exception:
+            await handle.rollback()
+            raise
+        applied.append(name)
+
+    return MigrationResult(applied=tuple(applied), already_applied=before)

package/templates/layers/db-sqlite/files/src/__solutionName.snake__/db/sqlite/settings.py

@@ -0,0 +1,68 @@
+"""The one place a SQLite default may appear. Call sites read these settings."""
+
+import os
+from dataclasses import dataclass
+from typing import Mapping
+
+# Protocol literals from the SQLite pragma spec, not tunables.
+JOURNAL_MODES = frozenset({"DELETE", "TRUNCATE", "PERSIST", "MEMORY", "WAL", "OFF"})
+SYNCHRONOUS_LEVELS = frozenset({"OFF", "NORMAL", "FULL", "EXTRA"})
+
+_TRUE = frozenset({"1", "true", "yes", "on"})
+
+
+@dataclass(frozen=True, slots=True)
+class SqliteSettings:
+    file: str = "{{ sqliteFile }}"
+    busy_timeout_ms: int = 5000
+    journal_mode: str = "WAL"
+    synchronous: str = "NORMAL"
+    foreign_keys: bool = True
+    migrations_dir: str = "migrations"
+
+
+def _read(env: Mapping[str, str], key: str) -> str | None:
+    value = env.get(key, "").strip()
+    return value or None
+
+
+def _integer(env: Mapping[str, str], key: str, fallback: int) -> int:
+    raw = _read(env, key)
+    if raw is None:
+        return fallback
+    if not raw.isdigit():
+        raise ValueError(f"{key} must be a non-negative integer, got {raw!r}")
+    return int(raw)
+
+
+def _boolean(env: Mapping[str, str], key: str, fallback: bool) -> bool:
+    raw = _read(env, key)
+    return fallback if raw is None else raw.lower() in _TRUE
+
+
+def _one_of(env: Mapping[str, str], key: str, allowed: frozenset[str], fallback: str) -> str:
+    raw = _read(env, key)
+    if raw is None:
+        return fallback
+    upper = raw.upper()
+    if upper not in allowed:
+        raise ValueError(f"{key} must be one of {sorted(allowed)}, got {raw!r}")
+    return upper
+
+
+def load_sqlite_settings(env: Mapping[str, str] | None = None) -> SqliteSettings:
+    source = os.environ if env is None else env
+    defaults = SqliteSettings()
+    return SqliteSettings(
+        file=_read(source, "SQLITE_FILE") or defaults.file,
+        busy_timeout_ms=_integer(source, "SQLITE_BUSY_TIMEOUT_MS", defaults.busy_timeout_ms),
+        journal_mode=_one_of(source, "SQLITE_JOURNAL_MODE", JOURNAL_MODES, defaults.journal_mode),
+        synchronous=_one_of(source, "SQLITE_SYNCHRONOUS", SYNCHRONOUS_LEVELS, defaults.synchronous),
+        foreign_keys=_boolean(source, "SQLITE_FOREIGN_KEYS", defaults.foreign_keys),
+        migrations_dir=_read(source, "SQLITE_MIGRATIONS_DIR") or defaults.migrations_dir,
+    )
+
+
+def is_in_memory(file: str) -> bool:
+    """Each in-memory connection gets its own empty database, so journaling does not apply."""
+    return file == ":memory:" or file.startswith("file::memory:") or "mode=memory" in file

package/templates/layers/db-sqlite/files/src/db/sqlite/cli.ts

@@ -0,0 +1,38 @@
+/**
+ * Migration and health entry point. Wire it into package.json scripts, e.g.
+ *   "db:migrate": "tsx src/db/sqlite/cli.ts migrate"
+ */
+import { closeDatabase, getDatabase } from './client.js';
+import { checkHealth, checkIntegrity } from './health.js';
+import { migrate } from './migrate.js';
+
+const COMMANDS = ['migrate', 'health', 'integrity'] as const;
+type Command = (typeof COMMANDS)[number];
+
+function main(command: string | undefined): number {
+  if (!command || !COMMANDS.includes(command as Command)) {
+    console.error(`usage: cli <${COMMANDS.join('|')}>`);
+    return 2;
+  }
+
+  const db = getDatabase();
+  try {
+    if (command === 'migrate') {
+      const { applied, alreadyApplied } = migrate(db);
+      console.log(applied.length ? `Applied ${applied.join(', ')}` : `Up to date (${alreadyApplied} migrations)`);
+      return 0;
+    }
+    if (command === 'integrity') {
+      const ok = checkIntegrity(db);
+      console.log(ok ? 'integrity ok' : 'integrity FAILED');
+      return ok ? 0 : 1;
+    }
+    const health = checkHealth(db);
+    console.log(JSON.stringify(health));
+    return health.ok ? 0 : 1;
+  } finally {
+    closeDatabase();
+  }
+}
+
+process.exitCode = main(process.argv[2]);

package/templates/layers/db-sqlite/files/src/db/sqlite/client.ts

@@ -0,0 +1,45 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import Database from 'better-sqlite3';
+import { isInMemory, loadSqliteSettings, type SqliteSettings } from './settings.js';
+
+export type SqliteDatabase = Database.Database;
+
+/**
+ * Opens a connection and applies the pragmas SQLite does not enable on its own.
+ * better-sqlite3 is synchronous by design: SQLite reads are microseconds, so a
+ * thread hop costs more than the query.
+ */
+export function openDatabase(settings: SqliteSettings = loadSqliteSettings()): SqliteDatabase {
+  const memory = isInMemory(settings.file);
+  if (!memory) fs.mkdirSync(path.dirname(path.resolve(settings.file)), { recursive: true });
+
+  const db = new Database(settings.file);
+  db.pragma(`busy_timeout = ${settings.busyTimeoutMs}`);
+  db.pragma(`foreign_keys = ${settings.foreignKeys ? 'ON' : 'OFF'}`);
+
+  if (!memory) {
+    db.pragma(`journal_mode = ${settings.journalMode}`);
+    db.pragma(`synchronous = ${settings.synchronous}`);
+  }
+  return db;
+}
+
+let shared: SqliteDatabase | undefined;
+
+/** One connection per process — SQLite serializes writers anyway, so a pool buys nothing. */
+export function getDatabase(): SqliteDatabase {
+  shared ??= openDatabase();
+  return shared;
+}
+
+export function closeDatabase(): void {
+  shared?.close();
+  shared = undefined;
+}
+
+/** Copies a live database safely; `cp` on a WAL database can capture a torn state. */
+export function backupTo(db: SqliteDatabase, destination: string): void {
+  fs.mkdirSync(path.dirname(path.resolve(destination)), { recursive: true });
+  db.prepare('VACUUM INTO ?').run(destination);
+}

package/templates/layers/db-sqlite/files/src/db/sqlite/health.ts

@@ -0,0 +1,30 @@
+import type { SqliteDatabase } from './client.js';
+
+export interface DatabaseHealth {
+  ok: boolean;
+  engine: 'sqlite';
+  latencyMs: number;
+  error?: string;
+}
+
+/** Cheap liveness probe for readiness endpoints — proves the file is open and readable. */
+export function checkHealth(db: SqliteDatabase): DatabaseHealth {
+  const started = performance.now();
+  try {
+    db.prepare('SELECT 1').get();
+    return { ok: true, engine: 'sqlite', latencyMs: performance.now() - started };
+  } catch (error) {
+    return {
+      ok: false,
+      engine: 'sqlite',
+      latencyMs: performance.now() - started,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/** Full file scan — run on demand or on a schedule, never in a readiness probe. */
+export function checkIntegrity(db: SqliteDatabase): boolean {
+  const row = db.pragma('integrity_check', { simple: true });
+  return row === 'ok';
+}

package/templates/layers/db-sqlite/files/src/db/sqlite/index.ts

@@ -0,0 +1,8 @@
+export { loadSqliteSettings, isInMemory } from './settings.js';
+export type { SqliteSettings, JournalMode, SynchronousLevel } from './settings.js';
+export { openDatabase, getDatabase, closeDatabase, backupTo } from './client.js';
+export type { SqliteDatabase } from './client.js';
+export { migrate } from './migrate.js';
+export type { MigrationResult } from './migrate.js';
+export { checkHealth, checkIntegrity } from './health.js';
+export type { DatabaseHealth } from './health.js';

package/templates/layers/db-sqlite/files/src/db/sqlite/migrate.ts

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadSqliteSettings } from './settings.js';
+import type { SqliteDatabase } from './client.js';
+
+const LEDGER = 'schema_migrations';
+
+export interface MigrationResult {
+  applied: string[];
+  alreadyApplied: number;
+}
+
+function pending(db: SqliteDatabase, directory: string): string[] {
+  if (!fs.existsSync(directory)) return [];
+  const done = new Set(
+    (db.prepare(`SELECT name FROM ${LEDGER}`).all() as { name: string }[]).map((row) => row.name),
+  );
+  return fs
+    .readdirSync(directory)
+    .filter((name) => name.endsWith('.sql'))
+    .sort()
+    .filter((name) => !done.has(name));
+}
+
+/**
+ * Applies every unseen `*.sql` in filename order, one transaction per file, so a failure
+ * leaves the schema and the ledger in step. Forward-only — see docs/db/sqlite.md.
+ */
+export function migrate(db: SqliteDatabase, directory = loadSqliteSettings().migrationsDir): MigrationResult {
+  db.exec(
+    `CREATE TABLE IF NOT EXISTS ${LEDGER} (
+       name       TEXT PRIMARY KEY,
+       applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+     )`,
+  );
+
+  const before = (db.prepare(`SELECT count(*) AS n FROM ${LEDGER}`).get() as { n: number }).n;
+  const applied: string[] = [];
+
+  for (const name of pending(db, directory)) {
+    const sql = fs.readFileSync(path.join(directory, name), 'utf8');
+    const run = db.transaction(() => {
+      db.exec(sql);
+      db.prepare(`INSERT INTO ${LEDGER} (name) VALUES (?)`).run(name);
+    });
+    run();
+    applied.push(name);
+  }
+
+  return { applied, alreadyApplied: before };
+}

package/templates/layers/db-sqlite/files/src/db/sqlite/settings.ts

@@ -0,0 +1,75 @@
+/**
+ * The one place a SQLite default may appear. Everything else reads these settings —
+ * a connection string or pragma written at a call site is a bug.
+ */
+
+/** Protocol literals from the SQLite pragma spec, not tunables. */
+const JOURNAL_MODES = ['DELETE', 'TRUNCATE', 'PERSIST', 'MEMORY', 'WAL', 'OFF'] as const;
+const SYNCHRONOUS_LEVELS = ['OFF', 'NORMAL', 'FULL', 'EXTRA'] as const;
+
+export type JournalMode = (typeof JOURNAL_MODES)[number];
+export type SynchronousLevel = (typeof SYNCHRONOUS_LEVELS)[number];
+
+export interface SqliteSettings {
+  file: string;
+  busyTimeoutMs: number;
+  journalMode: JournalMode;
+  synchronous: SynchronousLevel;
+  foreignKeys: boolean;
+  migrationsDir: string;
+}
+
+const defaults: SqliteSettings = {
+  file: '{{ sqliteFile }}',
+  busyTimeoutMs: 5000,
+  journalMode: 'WAL',
+  synchronous: 'NORMAL',
+  foreignKeys: true,
+  migrationsDir: 'migrations',
+};
+
+type Env = Record<string, string | undefined>;
+
+function read(env: Env, key: string): string | undefined {
+  const value = env[key];
+  return value === undefined || value.trim() === '' ? undefined : value.trim();
+}
+
+function integer(env: Env, key: string, fallback: number): number {
+  const raw = read(env, key);
+  if (raw === undefined) return fallback;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`${key} must be a non-negative integer, got "${raw}"`);
+  }
+  return parsed;
+}
+
+function boolean(env: Env, key: string, fallback: boolean): boolean {
+  const raw = read(env, key)?.toLowerCase();
+  if (raw === undefined) return fallback;
+  return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'on';
+}
+
+function oneOf<T extends string>(env: Env, key: string, allowed: readonly T[], fallback: T): T {
+  const raw = read(env, key)?.toUpperCase() as T | undefined;
+  if (raw === undefined) return fallback;
+  if (!allowed.includes(raw)) throw new Error(`${key} must be one of ${allowed.join(', ')}, got "${raw}"`);
+  return raw;
+}
+
+export function loadSqliteSettings(env: Env = process.env): SqliteSettings {
+  return {
+    file: read(env, 'SQLITE_FILE') ?? defaults.file,
+    busyTimeoutMs: integer(env, 'SQLITE_BUSY_TIMEOUT_MS', defaults.busyTimeoutMs),
+    journalMode: oneOf(env, 'SQLITE_JOURNAL_MODE', JOURNAL_MODES, defaults.journalMode),
+    synchronous: oneOf(env, 'SQLITE_SYNCHRONOUS', SYNCHRONOUS_LEVELS, defaults.synchronous),
+    foreignKeys: boolean(env, 'SQLITE_FOREIGN_KEYS', defaults.foreignKeys),
+    migrationsDir: read(env, 'SQLITE_MIGRATIONS_DIR') ?? defaults.migrationsDir,
+  };
+}
+
+/** Each in-memory connection gets its own empty database, so pooling and journaling do not apply. */
+export function isInMemory(file: string): boolean {
+  return file === ':memory:' || file.startsWith('file::memory:') || file.includes('mode=memory');
+}