@opengroundplan/core 0.1.1

package/templates/layers/db-postgres/files/internal/db/postgres_config.go

@@ -0,0 +1,79 @@
+package db
+
+import (
+	"fmt"
+	"os"
+	"strconv"
+)
+
+// PostgreSQL-only settings. The shared surface (URL, pool bounds, timeouts) lives
+// in db-core's Config; this adds what only this engine understands, under the
+// same environment prefix.
+type PostgresConfig struct {
+	SSLMode         string
+	IdleTimeoutMS   int
+	MigrationsDir   string
+	MigrationsTable string
+	// Advisory-lock key. Every app sharing this database must use the same number.
+	MigrationsLockID int64
+}
+
+var validSSLModes = map[string]bool{
+	"disable":     true,
+	"prefer":      true,
+	"require":     true,
+	"verify-full": true,
+}
+
+// Typed defaults. The single place a literal PostgreSQL value may appear.
+func postgresDefaults() PostgresConfig {
+	return PostgresConfig{
+		SSLMode:          "prefer",
+		IdleTimeoutMS:    30_000,
+		MigrationsDir:    "./migrations",
+		MigrationsTable:  "schema_migrations",
+		MigrationsLockID: 3_141_592,
+	}
+}
+
+func LoadPostgresConfig() (PostgresConfig, error) {
+	cfg := postgresDefaults()
+
+	if value := os.Getenv(envPrefix + "_SSLMODE"); value != "" {
+		cfg.SSLMode = value
+	}
+	if !validSSLModes[cfg.SSLMode] {
+		return PostgresConfig{}, fmt.Errorf("%s_SSLMODE must be disable, prefer, require or verify-full, got %q", envPrefix, cfg.SSLMode)
+	}
+	if value := os.Getenv(envPrefix + "_MIGRATIONS_DIR"); value != "" {
+		cfg.MigrationsDir = value
+	}
+	if value := os.Getenv(envPrefix + "_MIGRATIONS_TABLE"); value != "" {
+		cfg.MigrationsTable = value
+	}
+
+	var err error
+	if cfg.IdleTimeoutMS, err = pgInt("_IDLE_TIMEOUT_MS", cfg.IdleTimeoutMS); err != nil {
+		return PostgresConfig{}, err
+	}
+	lockID, err := pgInt("_MIGRATIONS_LOCK_ID", int(cfg.MigrationsLockID))
+	if err != nil {
+		return PostgresConfig{}, err
+	}
+	cfg.MigrationsLockID = int64(lockID)
+
+	return cfg, nil
+}
+
+// Named pgInt rather than integer: db-core already owns that helper in this package.
+func pgInt(suffix string, fallback int) (int, error) {
+	value := os.Getenv(envPrefix + suffix)
+	if value == "" {
+		return fallback, nil
+	}
+	parsed, err := strconv.Atoi(value)
+	if err != nil {
+		return 0, fmt.Errorf("%s%s must be an integer, got %q", envPrefix, suffix, value)
+	}
+	return parsed, nil
+}

package/templates/layers/db-postgres/files/internal/db/postgres_errors.go

@@ -0,0 +1,59 @@
+package db
+
+import (
+	"errors"
+
+	"github.com/jackc/pgx/v5/pgconn"
+)
+
+// SQLSTATE translation. Drivers leak vendor codes; db-core's taxonomy is what
+// callers branch on, so the mapping lives here and nowhere else.
+//
+// Codes: https://www.postgresql.org/docs/current/errcodes-appendix.html
+var sqlStateKinds = map[string]Kind{
+	"23505": KindConflict,    // unique_violation
+	"23502": KindIntegrity,   // not_null_violation
+	"23503": KindIntegrity,   // foreign_key_violation
+	"23514": KindIntegrity,   // check_violation
+	"23P01": KindIntegrity,   // exclusion_violation
+	"40001": KindTransient,   // serialization_failure
+	"40P01": KindTransient,   // deadlock_detected
+	"55P03": KindTransient,   // lock_not_available
+	"57014": KindTimeout,     // query_canceled, which is what statement_timeout raises
+	"53300": KindUnavailable, // too_many_connections
+	"57P01": KindUnavailable, // admin_shutdown
+	"57P02": KindUnavailable, // crash_shutdown
+	"57P03": KindUnavailable, // cannot_connect_now
+}
+
+// Whole classes that map uniformly, checked after the exact codes above.
+var sqlClassKinds = map[string]Kind{
+	"08": KindUnavailable, // connection exception
+	"53": KindUnavailable, // insufficient resources
+	"23": KindIntegrity,   // integrity constraint violation
+}
+
+func Classify(err error) Kind {
+	var pgErr *pgconn.PgError
+	if !errors.As(err, &pgErr) {
+		return KindUnknown
+	}
+	if kind, ok := sqlStateKinds[pgErr.Code]; ok {
+		return kind
+	}
+	if len(pgErr.Code) >= 2 {
+		if kind, ok := sqlClassKinds[pgErr.Code[:2]]; ok {
+			return kind
+		}
+	}
+	return KindUnknown
+}
+
+// ToDBError wraps a driver error in db-core's taxonomy, preserving the cause.
+func ToDBError(err error) *Error {
+	var already *Error
+	if errors.As(err, &already) {
+		return already
+	}
+	return Wrap(Classify(err), err)
+}

package/templates/layers/db-postgres/files/internal/db/postgres_migrate.go

@@ -0,0 +1,155 @@
+package db
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"slices"
+	"strings"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// Table names cannot be bound as parameters, so the value is validated instead.
+var safeIdentifier = regexp.MustCompile(`^[a-z_][a-z0-9_]*$`)
+
+// Migrate applies every pending migration in filename order, each in its own
+// transaction, and records a checksum. An already-applied file that changed is a
+// hard error: the database and the repository disagree about history, and
+// guessing which one is right is how data gets lost.
+func Migrate(ctx context.Context, pool *pgxpool.Pool, pg PostgresConfig) ([]string, error) {
+	if !safeIdentifier.MatchString(pg.MigrationsTable) {
+		return nil, NewError(KindUnknown, "migrations table must match %s, got %q", safeIdentifier, pg.MigrationsTable)
+	}
+	table := `"` + pg.MigrationsTable + `"`
+
+	files, err := listMigrations(pg.MigrationsDir)
+	if err != nil {
+		return nil, err
+	}
+
+	// A dedicated session: the advisory lock is held by the connection, not the pool.
+	conn, err := pool.Acquire(ctx)
+	if err != nil {
+		return nil, ToDBError(fmt.Errorf("acquire migration connection: %w", err))
+	}
+	defer conn.Release()
+
+	// Request traffic runs under a statement_timeout; a migration may
+	// legitimately take far longer than that.
+	if _, err := conn.Exec(ctx, "SET statement_timeout = 0"); err != nil {
+		return nil, ToDBError(fmt.Errorf("clear statement timeout: %w", err))
+	}
+
+	// Serialises concurrent deploys instead of letting them race.
+	if _, err := conn.Exec(ctx, "SELECT pg_advisory_lock($1)", pg.MigrationsLockID); err != nil {
+		return nil, ToDBError(fmt.Errorf("take migration lock: %w", err))
+	}
+	defer func() {
+		// Best effort: releasing the connection ends the session and the lock anyway.
+		_, _ = conn.Exec(context.WithoutCancel(ctx), "SELECT pg_advisory_unlock($1)", pg.MigrationsLockID)
+	}()
+
+	createTable := fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s (
+		version    text PRIMARY KEY,
+		checksum   text NOT NULL,
+		applied_at timestamptz NOT NULL DEFAULT now()
+	)`, table)
+	if _, err := conn.Exec(ctx, createTable); err != nil {
+		return nil, ToDBError(fmt.Errorf("create migrations table: %w", err))
+	}
+
+	known, err := readApplied(ctx, conn.Conn(), table)
+	if err != nil {
+		return nil, err
+	}
+
+	applied := make([]string, 0, len(files))
+	for _, path := range files {
+		body, err := os.ReadFile(path)
+		if err != nil {
+			return nil, ToDBError(fmt.Errorf("read %s: %w", path, err))
+		}
+
+		name := filepath.Base(path)
+		sum := sha256.Sum256(body)
+		digest := hex.EncodeToString(sum[:])
+
+		if previous, seen := known[name]; seen {
+			if previous != digest {
+				return nil, NewError(KindConflict,
+					"migration %s was edited after it was applied; add a new migration instead", name)
+			}
+			continue
+		}
+
+		if err := applyMigration(ctx, conn.Conn(), table, name, string(body), digest); err != nil {
+			return nil, err
+		}
+		applied = append(applied, name)
+	}
+
+	return applied, nil
+}
+
+func applyMigration(ctx context.Context, conn *pgx.Conn, table, name, body, digest string) error {
+	tx, err := conn.Begin(ctx)
+	if err != nil {
+		return ToDBError(fmt.Errorf("begin %s: %w", name, err))
+	}
+	// No-op once the transaction has been committed.
+	defer func() { _ = tx.Rollback(context.WithoutCancel(ctx)) }()
+
+	if _, err := tx.Exec(ctx, body); err != nil {
+		return ToDBError(fmt.Errorf("migration %s failed: %w", name, err))
+	}
+
+	insert := fmt.Sprintf("INSERT INTO %s (version, checksum) VALUES ($1, $2)", table)
+	if _, err := tx.Exec(ctx, insert, name, digest); err != nil {
+		return ToDBError(fmt.Errorf("record %s: %w", name, err))
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		return ToDBError(fmt.Errorf("commit %s: %w", name, err))
+	}
+	return nil
+}
+
+func readApplied(ctx context.Context, conn *pgx.Conn, table string) (map[string]string, error) {
+	rows, err := conn.Query(ctx, fmt.Sprintf("SELECT version, checksum FROM %s", table))
+	if err != nil {
+		return nil, ToDBError(fmt.Errorf("read applied migrations: %w", err))
+	}
+	defer rows.Close()
+
+	known := make(map[string]string)
+	for rows.Next() {
+		var version, checksum string
+		if err := rows.Scan(&version, &checksum); err != nil {
+			return nil, ToDBError(fmt.Errorf("scan applied migration: %w", err))
+		}
+		known[version] = checksum
+	}
+	return known, rows.Err()
+}
+
+func listMigrations(directory string) ([]string, error) {
+	entries, err := os.ReadDir(directory)
+	if err != nil {
+		return nil, NewError(KindUnknown, "migrations directory not readable: %v", err)
+	}
+
+	var files []string
+	for _, entry := range entries {
+		if !entry.IsDir() && strings.HasSuffix(entry.Name(), ".sql") {
+			files = append(files, filepath.Join(directory, entry.Name()))
+		}
+	}
+	slices.Sort(files)
+	return files, nil
+}

package/templates/layers/db-postgres/files/migrations/0001_init.sql

@@ -0,0 +1,9 @@
+-- Baseline schema.
+--
+-- Migrations are immutable once applied: the runner records a checksum per file
+-- and refuses to start if one changes. To alter anything, add a new file.
+-- Filenames sort lexicographically, so keep the zero-padded numeric prefix.
+
+-- Case-insensitive text. Emails and usernames compare correctly without
+-- lower() on every predicate, which would defeat their indexes.
+CREATE EXTENSION IF NOT EXISTS citext;

package/templates/layers/db-postgres/files/package.json

@@ -0,0 +1,11 @@
+{
+  "dependencies": {
+    "pg": "^8.22.0"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.20.0"
+  },
+  "scripts": {
+    "db:migrate": "node --experimental-strip-types src/db/postgres/migrate.ts"
+  }
+}

package/templates/layers/db-postgres/files/pyproject.toml

@@ -0,0 +1,2 @@
+[project]
+dependencies = ["psycopg[binary]>=3.3,<4", "psycopg-pool>=3.3,<4"]

package/templates/layers/db-postgres/files/src/__solutionName.dot__.Data.Postgres/PostgresErrors.cs

@@ -0,0 +1,57 @@
+using Npgsql;
+using {{ solutionName | dot }}.Data;
+
+namespace {{ solutionName | dot }}.Data.Postgres;
+
+// SQLSTATE translation. Drivers leak vendor codes; the seam's taxonomy is what
+// callers branch on, so the mapping lives here and nowhere else.
+//
+// Codes: https://www.postgresql.org/docs/current/errcodes-appendix.html
+public static class PostgresErrors
+{
+    private static readonly Dictionary<string, DatabaseErrorKind> ByCode = new(StringComparer.Ordinal)
+    {
+        ["23505"] = DatabaseErrorKind.Conflict,      // unique_violation
+        ["23502"] = DatabaseErrorKind.Integrity,     // not_null_violation
+        ["23503"] = DatabaseErrorKind.Integrity,     // foreign_key_violation
+        ["23514"] = DatabaseErrorKind.Integrity,     // check_violation
+        ["23P01"] = DatabaseErrorKind.Integrity,     // exclusion_violation
+        ["40001"] = DatabaseErrorKind.Transient,     // serialization_failure
+        ["40P01"] = DatabaseErrorKind.Transient,     // deadlock_detected
+        ["55P03"] = DatabaseErrorKind.Transient,     // lock_not_available
+        ["57014"] = DatabaseErrorKind.Timeout,       // query_canceled, raised by statement_timeout
+        ["53300"] = DatabaseErrorKind.Unavailable,   // too_many_connections
+        ["57P01"] = DatabaseErrorKind.Unavailable,   // admin_shutdown
+        ["57P02"] = DatabaseErrorKind.Unavailable,   // crash_shutdown
+        ["57P03"] = DatabaseErrorKind.Unavailable,   // cannot_connect_now
+    };
+
+    // Whole classes that map uniformly, checked after the exact codes above.
+    private static readonly Dictionary<string, DatabaseErrorKind> ByClass = new(StringComparer.Ordinal)
+    {
+        ["08"] = DatabaseErrorKind.Unavailable,      // connection exception
+        ["53"] = DatabaseErrorKind.Unavailable,      // insufficient resources
+        ["23"] = DatabaseErrorKind.Integrity,        // integrity constraint violation
+    };
+
+    public static DatabaseErrorKind Classify(Exception error)
+    {
+        if (error is not PostgresException postgres)
+        {
+            return error is NpgsqlException ? DatabaseErrorKind.Unavailable : DatabaseErrorKind.Unknown;
+        }
+
+        if (ByCode.TryGetValue(postgres.SqlState, out var kind))
+        {
+            return kind;
+        }
+
+        return postgres.SqlState.Length >= 2 && ByClass.TryGetValue(postgres.SqlState[..2], out var byClass)
+            ? byClass
+            : DatabaseErrorKind.Unknown;
+    }
+
+    // Wraps a driver error in the seam's taxonomy, preserving the original as inner.
+    public static DatabaseException Translate(Exception error) =>
+        error as DatabaseException ?? DatabaseException.Wrap(Classify(error), error);
+}

package/templates/layers/db-postgres/files/src/__solutionName.dot__.Data.Postgres/PostgresMigrator.cs

@@ -0,0 +1,171 @@
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.RegularExpressions;
+using Npgsql;
+using {{ solutionName | dot }}.Data;
+
+namespace {{ solutionName | dot }}.Data.Postgres;
+
+// Forward-only SQL migration runner. Files run in filename order, each in its own
+// transaction, recorded with a checksum. An already-applied file that changed is a
+// hard error: the database and the repository disagree about history, and guessing
+// which one is right is how data gets lost.
+public static class PostgresMigrator
+{
+    // Table names cannot be bound as parameters, so the value is validated instead.
+    private static readonly Regex SafeIdentifier = new("^[a-z_][a-z0-9_]*$", RegexOptions.Compiled);
+
+    public static async Task<IReadOnlyList<string>> RunAsync(
+        DatabaseOptions database,
+        PostgresOptions postgres,
+        CancellationToken cancellationToken = default)
+    {
+        var table = SafeTable(postgres.MigrationsTable);
+        var files = ListMigrations(postgres.MigrationsDir);
+        var applied = new List<string>();
+
+        // A dedicated connection, not a pooled one: the advisory lock lives on the session.
+        await using var connection = new NpgsqlConnection(postgres.ToConnectionString(database));
+        await connection.OpenAsync(cancellationToken);
+
+        // Request traffic runs under a statement_timeout; a migration may
+        // legitimately take far longer than that.
+        await ExecuteAsync(connection, "SET statement_timeout = 0", cancellationToken);
+
+        // Serialises concurrent deploys instead of letting them race.
+        await using (var take = new NpgsqlCommand("SELECT pg_advisory_lock(@lockId)", connection))
+        {
+            take.Parameters.AddWithValue("lockId", postgres.MigrationsLockId);
+            await take.ExecuteNonQueryAsync(cancellationToken);
+        }
+
+        try
+        {
+            await ExecuteAsync(
+                connection,
+                $"""
+                 CREATE TABLE IF NOT EXISTS "{table}" (
+                     version    text PRIMARY KEY,
+                     checksum   text NOT NULL,
+                     applied_at timestamptz NOT NULL DEFAULT now()
+                 )
+                 """,
+                cancellationToken);
+
+            var known = await ReadAppliedAsync(connection, table, cancellationToken);
+
+            foreach (var file in files)
+            {
+                var name = Path.GetFileName(file);
+                var body = await File.ReadAllTextAsync(file, cancellationToken);
+                var digest = Checksum(body);
+
+                if (known.TryGetValue(name, out var previous))
+                {
+                    if (previous != digest)
+                    {
+                        throw new DatabaseException(
+                            DatabaseErrorKind.Conflict,
+                            $"Migration {name} was edited after it was applied. Add a new migration instead.");
+                    }
+
+                    continue;
+                }
+
+                await ApplyAsync(connection, table, name, body, digest, cancellationToken);
+                applied.Add(name);
+            }
+        }
+        finally
+        {
+            await using var release = new NpgsqlCommand("SELECT pg_advisory_unlock(@lockId)", connection);
+            release.Parameters.AddWithValue("lockId", postgres.MigrationsLockId);
+            await release.ExecuteNonQueryAsync(CancellationToken.None);
+        }
+
+        return applied;
+    }
+
+    private static async Task ApplyAsync(
+        NpgsqlConnection connection,
+        string table,
+        string name,
+        string body,
+        string digest,
+        CancellationToken cancellationToken)
+    {
+        await using var transaction = await connection.BeginTransactionAsync(cancellationToken);
+        try
+        {
+            await using (var migration = new NpgsqlCommand(body, connection, transaction))
+            {
+                await migration.ExecuteNonQueryAsync(cancellationToken);
+            }
+
+            await using (var record = new NpgsqlCommand(
+                $"""INSERT INTO "{table}" (version, checksum) VALUES (@version, @checksum)""",
+                connection,
+                transaction))
+            {
+                record.Parameters.AddWithValue("version", name);
+                record.Parameters.AddWithValue("checksum", digest);
+                await record.ExecuteNonQueryAsync(cancellationToken);
+            }
+
+            await transaction.CommitAsync(cancellationToken);
+        }
+        catch (Exception error)
+        {
+            await transaction.RollbackAsync(CancellationToken.None);
+            throw new DatabaseException(
+                PostgresErrors.Classify(error), $"Migration {name} failed: {error.Message}", error);
+        }
+    }
+
+    private static async Task<Dictionary<string, string>> ReadAppliedAsync(
+        NpgsqlConnection connection,
+        string table,
+        CancellationToken cancellationToken)
+    {
+        var known = new Dictionary<string, string>(StringComparer.Ordinal);
+
+        await using var command = new NpgsqlCommand($"""SELECT version, checksum FROM "{table}" """, connection);
+        await using var reader = await command.ExecuteReaderAsync(cancellationToken);
+        while (await reader.ReadAsync(cancellationToken))
+        {
+            known[reader.GetString(0)] = reader.GetString(1);
+        }
+
+        return known;
+    }
+
+    private static async Task ExecuteAsync(
+        NpgsqlConnection connection,
+        string sql,
+        CancellationToken cancellationToken)
+    {
+        await using var command = new NpgsqlCommand(sql, connection);
+        await command.ExecuteNonQueryAsync(cancellationToken);
+    }
+
+    private static string SafeTable(string table) => SafeIdentifier.IsMatch(table)
+        ? table
+        : throw new InvalidOperationException(
+            $"Migrations table must match {SafeIdentifier}, got \"{table}\".");
+
+    private static string[] ListMigrations(string directory)
+    {
+        if (!Directory.Exists(directory))
+        {
+            throw new DirectoryNotFoundException($"Migrations directory not found: {directory}");
+        }
+
+        var files = Directory.GetFiles(directory, "*.sql");
+        Array.Sort(files, StringComparer.Ordinal);
+        return files;
+    }
+
+    // ToHexString rather than ToHexStringLower, which needs .NET 9+.
+    private static string Checksum(string body) =>
+        Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(body))).ToLowerInvariant();
+}

package/templates/layers/db-postgres/files/src/__solutionName.dot__.Data.Postgres/PostgresOptions.cs

@@ -0,0 +1,92 @@
+using {{ solutionName | dot }}.Data;
+
+namespace {{ solutionName | dot }}.Data.Postgres;
+
+// PostgreSQL-only settings. The shared surface (Url, pool bounds, timeouts) lives
+// in DatabaseOptions; this adds what only this engine understands, under the same prefix.
+public sealed record PostgresOptions
+{
+    private const string Prefix = "{{ dbEnvPrefix }}";
+
+    public string SslMode { get; init; } = "prefer";
+
+    public int IdleTimeoutMs { get; init; } = 30_000;
+
+    public string MigrationsDir { get; init; } = "./migrations";
+
+    public string MigrationsTable { get; init; } = "schema_migrations";
+
+    // Advisory-lock key. Every app sharing this database must use the same number.
+    public long MigrationsLockId { get; init; } = 3_141_592;
+
+    public static PostgresOptions FromEnvironment() => new()
+    {
+        SslMode = ValidatedSslMode(Text("SSLMODE") ?? "prefer"),
+        IdleTimeoutMs = Number("IDLE_TIMEOUT_MS", 30_000),
+        MigrationsDir = Text("MIGRATIONS_DIR") ?? "./migrations",
+        MigrationsTable = Text("MIGRATIONS_TABLE") ?? "schema_migrations",
+        MigrationsLockId = Number("MIGRATIONS_LOCK_ID", 3_141_592),
+    };
+
+    // Builds the Npgsql connection string from the seam's Url plus these extras.
+    public string ToConnectionString(DatabaseOptions database)
+    {
+        if (!database.HasEngine)
+        {
+            throw new InvalidOperationException($"{Prefix}_URL is required when the PostgreSQL layer is installed.");
+        }
+
+        var builder = new Npgsql.NpgsqlConnectionStringBuilder(database.Url)
+        {
+            MinPoolSize = database.PoolMin,
+            MaxPoolSize = database.PoolMax,
+            // Npgsql counts both of these in whole seconds.
+            Timeout = Math.Max(1, database.ConnectTimeoutMs / 1000),
+            ConnectionIdleLifetime = Math.Max(1, IdleTimeoutMs / 1000),
+            // Server-side cap, so one runaway query cannot hold a connection forever.
+            Options = $"-c statement_timeout={database.StatementTimeoutMs}",
+        };
+
+        // sslmode from the URL wins; this only fills in when the URL omits it.
+        if (!database.Url.Contains("sslmode", StringComparison.OrdinalIgnoreCase))
+        {
+            builder.SslMode = ParseSslMode(SslMode);
+        }
+
+        return builder.ConnectionString;
+    }
+
+    private static string ValidatedSslMode(string value) => value switch
+    {
+        "disable" or "prefer" or "require" or "verify-full" => value,
+        _ => throw new InvalidOperationException(
+            $"{Prefix}_SSLMODE must be disable, prefer, require or verify-full, got \"{value}\"."),
+    };
+
+    private static Npgsql.SslMode ParseSslMode(string value) => value switch
+    {
+        "disable" => Npgsql.SslMode.Disable,
+        "require" => Npgsql.SslMode.Require,
+        "verify-full" => Npgsql.SslMode.VerifyFull,
+        _ => Npgsql.SslMode.Prefer,
+    };
+
+    private static string? Text(string key)
+    {
+        var value = Environment.GetEnvironmentVariable($"{Prefix}_{key}");
+        return string.IsNullOrWhiteSpace(value) ? null : value;
+    }
+
+    private static int Number(string key, int fallback)
+    {
+        var raw = Text(key);
+        if (raw is null)
+        {
+            return fallback;
+        }
+
+        return int.TryParse(raw, out var parsed)
+            ? parsed
+            : throw new InvalidOperationException($"{Prefix}_{key} must be an integer, got \"{raw}\".");
+    }
+}

package/templates/layers/db-postgres/files/src/__solutionName.dot__.Data.Postgres/__solutionName.dot__.Data.Postgres.csproj

@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <!-- The driver lives here, never in the seam: only this project references Npgsql. -->
+  <PropertyGroup>
+    <TargetFramework>{{ dotnetTargetFramework }}</TargetFramework>
+    <RootNamespace>{{ solutionName | dot }}.Data.Postgres</RootNamespace>
+    <AssemblyName>{{ solutionName | dot }}.Data.Postgres</AssemblyName>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <LangVersion>latest</LangVersion>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <NoWarn>$(NoWarn);CS1591</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Npgsql" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <!-- Forward slashes: a backslash directly before a token reads as an escaped
+         brace and the token is left unrendered. MSBuild accepts / on every platform. -->
+    <ProjectReference Include="../{{ solutionName | dot }}.Data/{{ solutionName | dot }}.Data.csproj" />
+  </ItemGroup>
+
+</Project>