feat: establish Go service and database foundation

internal/database/database.go

@@ -0,0 +1,30 @@
+package database
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+func Open(ctx context.Context, databaseURL string) (*pgxpool.Pool, error) {
+	poolConfig, err := pgxpool.ParseConfig(databaseURL)
+	if err != nil {
+		return nil, fmt.Errorf("parsing database configuration: %w", err)
+	}
+	poolConfig.MaxConns = 12
+	poolConfig.MinConns = 1
+	poolConfig.MaxConnLifetime = 30 * time.Minute
+	poolConfig.MaxConnIdleTime = 5 * time.Minute
+
+	pool, err := pgxpool.NewWithConfig(ctx, poolConfig)
+	if err != nil {
+		return nil, fmt.Errorf("opening database: %w", err)
+	}
+	if err := pool.Ping(ctx); err != nil {
+		pool.Close()
+		return nil, fmt.Errorf("pinging database: %w", err)
+	}
+	return pool, nil
+}

internal/database/migrate.go

@@ -0,0 +1,23 @@
+package database
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// Migrate applies the idempotent local MVP schema. Production migration tooling
+// can execute the same reviewed SQL from migrations/.
+func Migrate(ctx context.Context, pool *pgxpool.Pool, migration string) error {
+	for statement := range strings.SplitSeq(migration, "-- statement-break") {
+		if strings.TrimSpace(statement) == "" {
+			continue
+		}
+		if _, err := pool.Exec(ctx, statement); err != nil {
+			return fmt.Errorf("applying migration: %w", err)
+		}
+	}
+	return nil
+}