From edc8d94762f73d68e2361bf39bf97d4be07e3316 Mon Sep 17 00:00:00 2001
From: Adam Eivy <atomantic@gmail.com>
Date: Tue, 25 Aug 2026 17:36:27 +0000
Subject: [PATCH] feat: add PostgreSQL query foundation (#148)

---
 .changelog/NEXT.md                          |   1 +
 docs/development.md                         |  29 +
 ecosystem.config.cjs                        |   5 +-
 package-lock.json                           | 160 ++++++
 server/package.json                         |   4 +-
 server/src/db/postgres-schema.sql           | 600 ++++++++++++++++++++
 server/src/db/postgres.service.ts           | 346 +++++++++++
 tests/integration/db/postgresSchema.spec.ts |  89 +++
 tests/unit/db/postgresService.spec.ts       | 186 ++++++
 9 files changed, 1418 insertions(+), 2 deletions(-)
 create mode 100644 server/src/db/postgres-schema.sql
 create mode 100644 server/src/db/postgres.service.ts
 create mode 100644 tests/integration/db/postgresSchema.spec.ts
 create mode 100644 tests/unit/db/postgresService.spec.ts

diff --git a/.changelog/NEXT.md b/.changelog/NEXT.md
index 77a969d7..64db6f7b 100644
--- a/.changelog/NEXT.md
+++ b/.changelog/NEXT.md
@@ -14,6 +14,7 @@
 
 ## Internal
 
+- **[issue-148] PostgreSQL query-store foundation** — Added a packaged PostgreSQL schema and lazy async connection layer with transactional initialization, health checks, and named parameters, while leaving the current SQLite/JSON runtime unchanged until the staged migration completes.
 - Provider comparison cards no longer emit an invalid nested-`<button>` HTML warning under React 19 (the card header is now a `role="button"` element, keeping click and keyboard toggling).
 - SQLite driver is now loaded lazily so the server can start and serve JSON-backed data even when the native binding is unavailable.
 - Dev server binds all interfaces and accepts Tailscale `*.ts.net` hostnames, so the UI is reachable across the tailnet (over plain HTTP, or HTTPS when fronted by `tailscale serve`).
diff --git a/docs/development.md b/docs/development.md
index 892ba180..ac63e9ee 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -21,6 +21,7 @@ SparseTree/
 
 - Node.js 18+
 - npm 9+
+- PostgreSQL 15+ (optional during the staged query-store migration)
 
 ### Installation
 
@@ -50,6 +51,34 @@ pm2 restart ecosystem.config.cjs
 
 **Note:** Don't use `pm2 kill` or `pm2 delete all` as this server may have multiple PM2 apps running.
 
+### PostgreSQL query store (staged)
+
+PostgreSQL is being introduced as a rebuildable query layer while JSON files in
+`data/person/` remain the source of truth. The existing SQLite/JSON runtime stays
+active until the later cutover work is complete, so `DATABASE_URL` is optional for
+now.
+
+To make a standard connection URL available to the staged service, export it before
+starting the process:
+
+```bash
+export DATABASE_URL='postgresql://sparsetree:password@localhost:5432/sparsetree'
+pm2 restart ecosystem.config.cjs --update-env
+```
+
+Credentials are not stored in `ecosystem.config.cjs`. When `DATABASE_URL` is absent
+or unreachable, the PostgreSQL service reports itself unavailable without changing
+the current SQLite/JSON startup behavior. This foundation is not selected by the
+application yet; later migration slices will move writers and readers onto it.
+
+The PostgreSQL integration test creates and removes a unique schema inside the
+database named by `SPARSETREE_TEST_DATABASE_URL`:
+
+```bash
+SPARSETREE_TEST_DATABASE_URL="$DATABASE_URL" \
+  npm test -- --run tests/integration/db/postgresSchema.spec.ts
+```
+
 ## Build
 
 ```bash
diff --git a/ecosystem.config.cjs b/ecosystem.config.cjs
index 4b7129f5..b9815ac9 100644
--- a/ecosystem.config.cjs
+++ b/ecosystem.config.cjs
@@ -24,7 +24,10 @@ module.exports = {
         NODE_ENV: 'development',
         PORT: PORTS.API,
         HOST: '0.0.0.0',
-        CDP_PORT: PORTS.CDP
+        CDP_PORT: PORTS.CDP,
+        // PostgreSQL is staged alongside SQLite until the query-layer cutover.
+        // Keep credentials outside this tracked config.
+        DATABASE_URL: process.env.DATABASE_URL
       },
       watch: false
     },
diff --git a/package-lock.json b/package-lock.json
index f2e46702..7adab40d 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -2081,6 +2081,18 @@
         "undici-types": ">=7.24.0 <7.24.7"
       }
     },
+    "node_modules/@types/pg": {
+      "version": "8.23.1",
+      "resolved": "https://registry.npmjs.org/@types/pg/-/pg-8.23.1.tgz",
+      "integrity": "sha512-fKVHpikPdg4GKks3JuLEhvwSyvwzF23hnabPy6DD8ljVbC7+6J5dQzdv4arV6jqq57djnMgs1HKBxX4P8aBI3A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*",
+        "pg-protocol": "*",
+        "pg-types": "^2.2.0"
+      }
+    },
     "node_modules/@types/qs": {
       "version": "6.15.1",
       "resolved": "https://registry.npmjs.org/@types/qs/-/qs-6.15.1.tgz",
@@ -5782,6 +5794,95 @@
       "integrity": "sha512-7EAHlyLHI56VEIdK57uwHdHKIaAGbnXPiw0yWbarQZOKaKpvUIgW0jWRVLiatnM+XXlSwsanIBH/hzGMJulMow==",
       "license": "MIT"
     },
+    "node_modules/pg": {
+      "version": "8.23.0",
+      "resolved": "https://registry.npmjs.org/pg/-/pg-8.23.0.tgz",
+      "integrity": "sha512-Ip2EQCngowJLGOfCwkFhPXU7/ljlhn6Rxlmy4XYfL2Y+vyRM59+8uR2xqRWKdYmbXmxCFOAmKxBuSUCdF34qLg==",
+      "license": "MIT",
+      "dependencies": {
+        "pg-connection-string": "^2.14.0",
+        "pg-pool": "^3.14.0",
+        "pg-protocol": "^1.16.0",
+        "pg-types": "2.2.0",
+        "pgpass": "1.0.5"
+      },
+      "engines": {
+        "node": ">= 16.0.0"
+      },
+      "optionalDependencies": {
+        "pg-cloudflare": "^1.4.0"
+      },
+      "peerDependencies": {
+        "pg-native": ">=3.0.1"
+      },
+      "peerDependenciesMeta": {
+        "pg-native": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/pg-cloudflare": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/pg-cloudflare/-/pg-cloudflare-1.4.0.tgz",
+      "integrity": "sha512-Vo7z/6rrQYxpNRylp4Tlob2elzbh+N/MOQbxFVWCxS7oEx6jF53GTJFxK2WWpKuBRkmiin4Mt+xofFDjx09R0A==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/pg-connection-string": {
+      "version": "2.14.0",
+      "resolved": "https://registry.npmjs.org/pg-connection-string/-/pg-connection-string-2.14.0.tgz",
+      "integrity": "sha512-XwWDGcLRGCXAR8F/AM5bG7Q+A3Wm2s6QeEjlOKZLlH3UYcguiqCWKyWXVag5TLTIjR7oOJUY8kcADaZgWPyLeg==",
+      "license": "MIT"
+    },
+    "node_modules/pg-int8": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/pg-int8/-/pg-int8-1.0.1.tgz",
+      "integrity": "sha512-WCtabS6t3c8SkpDBUlb1kjOs7l66xsGdKpIPZsg4wR+B3+u9UAum2odSsF9tnvxg80h4ZxLWMy4pRjOsFIqQpw==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=4.0.0"
+      }
+    },
+    "node_modules/pg-pool": {
+      "version": "3.14.0",
+      "resolved": "https://registry.npmjs.org/pg-pool/-/pg-pool-3.14.0.tgz",
+      "integrity": "sha512-gKtPkFdQPU3DksooVLi9LsjZxrsBUZIpa+7aVx+LV5pNh0KzP4Zleud2po+ConrxbuXGBJ6Hfer6hdgpIBpBaw==",
+      "license": "MIT",
+      "peerDependencies": {
+        "pg": ">=8.0"
+      }
+    },
+    "node_modules/pg-protocol": {
+      "version": "1.16.0",
+      "resolved": "https://registry.npmjs.org/pg-protocol/-/pg-protocol-1.16.0.tgz",
+      "integrity": "sha512-sILXutLVjCLjcDuOmvhX5e2Z4cS5qG/6Bu3VkpFwdf/633ElGLpEh9bgmuI5I4sqKqkifQiGyiCcx1HdtrK7tg==",
+      "license": "MIT"
+    },
+    "node_modules/pg-types": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/pg-types/-/pg-types-2.2.0.tgz",
+      "integrity": "sha512-qTAAlrEsl8s4OiEQY69wDvcMIdQN6wdz5ojQiOy6YRMuynxenON0O5oCpJI6lshc6scgAY8qvJ2On/p+CXY0GA==",
+      "license": "MIT",
+      "dependencies": {
+        "pg-int8": "1.0.1",
+        "postgres-array": "~2.0.0",
+        "postgres-bytea": "~1.0.0",
+        "postgres-date": "~1.0.4",
+        "postgres-interval": "^1.1.0"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/pgpass": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/pgpass/-/pgpass-1.0.5.tgz",
+      "integrity": "sha512-FdW9r/jQZhSeohs1Z3sI1yxFQNFvMcnmfuj4WBMUTxOrAyLMaTcE1aAMBiTlbMNaXvBCQuVi0R7hd8udDSP7ug==",
+      "license": "MIT",
+      "dependencies": {
+        "split2": "^4.1.0"
+      }
+    },
     "node_modules/picocolors": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -6042,6 +6143,45 @@
         "node": "^10 || ^12 || >=14"
       }
     },
+    "node_modules/postgres-array": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/postgres-array/-/postgres-array-2.0.0.tgz",
+      "integrity": "sha512-VpZrUqU5A69eQyW2c5CA1jtLecCsN2U/bD6VilrFDWq5+5UIEVO7nazS3TEcHf1zuPYO/sqGvUvW62g86RXZuA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/postgres-bytea": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/postgres-bytea/-/postgres-bytea-1.0.1.tgz",
+      "integrity": "sha512-5+5HqXnsZPE65IJZSMkZtURARZelel2oXUEO8rH83VS/hxH5vv1uHquPg5wZs8yMAfdv971IU+kcPUczi7NVBQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/postgres-date": {
+      "version": "1.0.7",
+      "resolved": "https://registry.npmjs.org/postgres-date/-/postgres-date-1.0.7.tgz",
+      "integrity": "sha512-suDmjLVQg78nMK2UZ454hAG+OAW+HQPZ6n++TNDUX+L0+uUlLywnoxJKDou51Zm+zTCjrCl0Nq6J9C5hP9vK/Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/postgres-interval": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/postgres-interval/-/postgres-interval-1.2.0.tgz",
+      "integrity": "sha512-9ZhXKM/rw350N1ovuWHbGxnGh/SNJ4cnxHiM0rxE4VN41wsg8P8zWn9hv/buK00RP4WvlOyr/RBDiptyxVbkZQ==",
+      "license": "MIT",
+      "dependencies": {
+        "xtend": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/prebuild-install": {
       "version": "7.1.3",
       "resolved": "https://registry.npmjs.org/prebuild-install/-/prebuild-install-7.1.3.tgz",
@@ -6932,6 +7072,15 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/split2": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/split2/-/split2-4.2.0.tgz",
+      "integrity": "sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg==",
+      "license": "ISC",
+      "engines": {
+        "node": ">= 10.x"
+      }
+    },
     "node_modules/sshpk": {
       "version": "1.18.0",
       "resolved": "https://registry.npmjs.org/sshpk/-/sshpk-1.18.0.tgz",
@@ -7886,6 +8035,15 @@
         "node": ">=0.4.0"
       }
     },
+    "node_modules/xtend": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/xtend/-/xtend-4.0.2.tgz",
+      "integrity": "sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.4"
+      }
+    },
     "node_modules/y18n": {
       "version": "5.0.8",
       "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz",
@@ -7967,6 +8125,7 @@
         "better-sqlite3": "^12.10.1",
         "cors": "^2.8.6",
         "express": "^5.2.1",
+        "pg": "^8.23.0",
         "playwright": "^1.59.1",
         "portos-ai-toolkit": "^0.8.4",
         "tsx": "^4.19.2",
@@ -7979,6 +8138,7 @@
         "@types/express": "^5.0.0",
         "@types/express-serve-static-core": "~5.0.7",
         "@types/node": "^25.6.0",
+        "@types/pg": "^8.23.1",
         "typescript": "^6.0.2"
       }
     },
diff --git a/server/package.json b/server/package.json
index 4a56d3c1..258c270a 100644
--- a/server/package.json
+++ b/server/package.json
@@ -5,7 +5,7 @@
   "main": "dist/index.js",
   "scripts": {
     "dev": "tsx watch src/index.ts",
-    "build": "tsc && cp src/db/schema.sql dist/db/",
+    "build": "tsc && cp src/db/*.sql dist/db/",
     "start": "tsx src/index.ts"
   },
   "dependencies": {
@@ -13,6 +13,7 @@
     "better-sqlite3": "^12.10.1",
     "cors": "^2.8.6",
     "express": "^5.2.1",
+    "pg": "^8.23.0",
     "playwright": "^1.59.1",
     "portos-ai-toolkit": "^0.8.4",
     "tsx": "^4.19.2",
@@ -25,6 +26,7 @@
     "@types/express": "^5.0.0",
     "@types/express-serve-static-core": "~5.0.7",
     "@types/node": "^25.6.0",
+    "@types/pg": "^8.23.1",
     "typescript": "^6.0.2"
   }
 }
diff --git a/server/src/db/postgres-schema.sql b/server/src/db/postgres-schema.sql
new file mode 100644
index 00000000..281a0694
--- /dev/null
+++ b/server/src/db/postgres-schema.sql
@@ -0,0 +1,600 @@
+-- SparseTree PostgreSQL derived query-store baseline
+-- JSON files in data/person remain the Layer 1 source of truth.
+
+-- ============================================================================
+-- CORE IDENTITY
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS person (
+    person_id TEXT PRIMARY KEY,
+    display_name TEXT NOT NULL,
+    birth_name TEXT,
+    gender TEXT CHECK (gender IN ('male', 'female', 'unknown')),
+    living BOOLEAN NOT NULL DEFAULT FALSE,
+    bio TEXT,
+    is_unusual_death BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_person_display_name ON person(display_name);
+CREATE INDEX IF NOT EXISTS idx_person_gender ON person(gender);
+CREATE INDEX IF NOT EXISTS idx_person_unusual_death ON person(is_unusual_death) WHERE is_unusual_death;
+
+CREATE TABLE IF NOT EXISTS external_identity (
+    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    person_id TEXT NOT NULL REFERENCES person(person_id) ON DELETE CASCADE,
+    source TEXT NOT NULL,
+    external_id TEXT NOT NULL,
+    url TEXT,
+    confidence DOUBLE PRECISION DEFAULT 1.0,
+    last_seen_at TIMESTAMPTZ,
+    UNIQUE (source, external_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_external_identity_person ON external_identity(person_id);
+CREATE INDEX IF NOT EXISTS idx_external_identity_source ON external_identity(source);
+CREATE INDEX IF NOT EXISTS idx_external_identity_lookup ON external_identity(source, external_id);
+CREATE INDEX IF NOT EXISTS idx_external_identity_person_source ON external_identity(person_id, source);
+
+-- ============================================================================
+-- RELATIONSHIPS
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS parent_edge (
+    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    child_id TEXT NOT NULL REFERENCES person(person_id) ON DELETE CASCADE,
+    parent_id TEXT NOT NULL REFERENCES person(person_id) ON DELETE CASCADE,
+    parent_role TEXT CHECK (parent_role IN ('father', 'mother', 'parent')),
+    confidence DOUBLE PRECISION DEFAULT 1.0,
+    source TEXT,
+    UNIQUE (child_id, parent_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_parent_edge_child ON parent_edge(child_id);
+CREATE INDEX IF NOT EXISTS idx_parent_edge_parent ON parent_edge(parent_id);
+
+CREATE TABLE IF NOT EXISTS spouse_edge (
+    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    person1_id TEXT NOT NULL REFERENCES person(person_id) ON DELETE CASCADE,
+    person2_id TEXT NOT NULL REFERENCES person(person_id) ON DELETE CASCADE,
+    marriage_date TEXT,
+    marriage_place TEXT,
+    divorce_date TEXT,
+    confidence DOUBLE PRECISION DEFAULT 1.0,
+    source TEXT,
+    UNIQUE (person1_id, person2_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_spouse_edge_person1 ON spouse_edge(person1_id);
+CREATE INDEX IF NOT EXISTS idx_spouse_edge_person2 ON spouse_edge(person2_id);
+
+-- ============================================================================
+-- EVENTS, CLAIMS, AND PROVENANCE
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS vital_event (
+    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    person_id TEXT NOT NULL REFERENCES person(person_id) ON DELETE CASCADE,
+    event_type TEXT NOT NULL CHECK (event_type IN ('birth', 'death', 'burial', 'christening', 'marriage', 'divorce')),
+    date_original TEXT,
+    date_formal TEXT,
+    date_year INTEGER,
+    place TEXT,
+    place_id TEXT,
+    source TEXT,
+    confidence DOUBLE PRECISION DEFAULT 1.0,
+    UNIQUE (person_id, event_type, source)
+);
+
+CREATE INDEX IF NOT EXISTS idx_vital_event_person ON vital_event(person_id);
+CREATE INDEX IF NOT EXISTS idx_vital_event_type ON vital_event(event_type);
+CREATE INDEX IF NOT EXISTS idx_vital_event_person_type ON vital_event(person_id, event_type);
+CREATE INDEX IF NOT EXISTS idx_vital_event_year ON vital_event(date_year);
+CREATE INDEX IF NOT EXISTS idx_vital_event_place ON vital_event(place);
+
+CREATE TABLE IF NOT EXISTS claim (
+    claim_id TEXT PRIMARY KEY,
+    person_id TEXT NOT NULL REFERENCES person(person_id) ON DELETE CASCADE,
+    predicate TEXT NOT NULL,
+    value_text TEXT,
+    value_date TEXT,
+    source TEXT,
+    confidence DOUBLE PRECISION DEFAULT 1.0,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_claim_person ON claim(person_id);
+CREATE INDEX IF NOT EXISTS idx_claim_predicate ON claim(predicate);
+CREATE INDEX IF NOT EXISTS idx_claim_person_predicate ON claim(person_id, predicate);
+
+CREATE TABLE IF NOT EXISTS life_event (
+    event_id TEXT PRIMARY KEY,
+    person_id TEXT NOT NULL REFERENCES person(person_id) ON DELETE CASCADE,
+    event_type TEXT NOT NULL,
+    event_role TEXT NOT NULL DEFAULT 'principal',
+    date_original TEXT,
+    date_formal TEXT,
+    date_year INTEGER,
+    date_month INTEGER,
+    date_day INTEGER,
+    date_end_year INTEGER,
+    place_original TEXT,
+    place_normalized TEXT,
+    place_id TEXT,
+    value TEXT,
+    description TEXT,
+    cause TEXT,
+    source TEXT NOT NULL,
+    source_id TEXT,
+    confidence DOUBLE PRECISION DEFAULT 1.0,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_life_event_person ON life_event(person_id);
+CREATE INDEX IF NOT EXISTS idx_life_event_type ON life_event(event_type);
+CREATE INDEX IF NOT EXISTS idx_life_event_year ON life_event(date_year);
+CREATE INDEX IF NOT EXISTS idx_life_event_place ON life_event(place_normalized);
+CREATE INDEX IF NOT EXISTS idx_life_event_source ON life_event(source);
+CREATE INDEX IF NOT EXISTS idx_life_event_source_id ON life_event(source, source_id);
+
+CREATE TABLE IF NOT EXISTS note (
+    note_id TEXT PRIMARY KEY,
+    person_id TEXT NOT NULL REFERENCES person(person_id) ON DELETE CASCADE,
+    note_type TEXT NOT NULL,
+    title TEXT,
+    content TEXT NOT NULL,
+    content_type TEXT NOT NULL DEFAULT 'text',
+    language TEXT NOT NULL DEFAULT 'en',
+    source TEXT NOT NULL,
+    source_id TEXT,
+    author TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_note_person ON note(person_id);
+CREATE INDEX IF NOT EXISTS idx_note_type ON note(note_type);
+CREATE INDEX IF NOT EXISTS idx_note_source ON note(source);
+
+CREATE TABLE IF NOT EXISTS source_citation (
+    citation_id TEXT PRIMARY KEY,
+    entity_type TEXT NOT NULL,
+    entity_id TEXT NOT NULL,
+    source_type TEXT,
+    title TEXT,
+    author TEXT,
+    publisher TEXT,
+    publication_date TEXT,
+    url TEXT,
+    repository TEXT,
+    call_number TEXT,
+    page TEXT,
+    provider TEXT,
+    provider_source_id TEXT,
+    notes TEXT,
+    confidence DOUBLE PRECISION NOT NULL DEFAULT 1.0 CHECK (confidence BETWEEN 0.0 AND 1.0),
+    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_source_citation_entity ON source_citation(entity_type, entity_id);
+CREATE INDEX IF NOT EXISTS idx_source_citation_provider ON source_citation(provider, provider_source_id);
+
+CREATE TABLE IF NOT EXISTS local_override (
+    override_id TEXT PRIMARY KEY,
+    entity_type TEXT NOT NULL,
+    entity_id TEXT NOT NULL,
+    field_name TEXT NOT NULL,
+    original_value TEXT,
+    override_value TEXT,
+    reason TEXT,
+    source TEXT NOT NULL DEFAULT 'local',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE (entity_type, entity_id, field_name)
+);
+
+CREATE INDEX IF NOT EXISTS idx_local_override_entity ON local_override(entity_type, entity_id);
+
+CREATE TABLE IF NOT EXISTS sync_log (
+    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    entity_type TEXT NOT NULL,
+    entity_id TEXT NOT NULL,
+    provider TEXT NOT NULL,
+    sync_type TEXT NOT NULL,
+    status TEXT NOT NULL,
+    records_added INTEGER NOT NULL DEFAULT 0,
+    records_updated INTEGER NOT NULL DEFAULT 0,
+    records_unchanged INTEGER NOT NULL DEFAULT 0,
+    error_message TEXT,
+    started_at TIMESTAMPTZ,
+    completed_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_sync_log_entity ON sync_log(entity_type, entity_id);
+CREATE INDEX IF NOT EXISTS idx_sync_log_provider ON sync_log(provider);
+
+-- ============================================================================
+-- DATABASE MEMBERSHIP AND USER STATE
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS database_info (
+    db_id TEXT PRIMARY KEY,
+    root_id TEXT REFERENCES person(person_id),
+    root_name TEXT,
+    source_provider TEXT,
+    max_generations INTEGER,
+    person_count INTEGER NOT NULL DEFAULT 0,
+    is_sample BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS database_membership (
+    db_id TEXT NOT NULL,
+    person_id TEXT NOT NULL REFERENCES person(person_id) ON DELETE CASCADE,
+    is_root BOOLEAN NOT NULL DEFAULT FALSE,
+    generation INTEGER,
+    PRIMARY KEY (db_id, person_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_database_membership_db ON database_membership(db_id);
+CREATE INDEX IF NOT EXISTS idx_database_membership_root ON database_membership(db_id, is_root);
+
+CREATE TABLE IF NOT EXISTS favorite (
+    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    db_id TEXT NOT NULL,
+    person_id TEXT NOT NULL REFERENCES person(person_id) ON DELETE CASCADE,
+    why_interesting TEXT,
+    tags JSONB CHECK (tags IS NULL OR jsonb_typeof(tags) = 'array'),
+    added_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE (db_id, person_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_favorite_db ON favorite(db_id);
+CREATE INDEX IF NOT EXISTS idx_favorite_person ON favorite(person_id);
+CREATE INDEX IF NOT EXISTS idx_favorite_added_at ON favorite(added_at DESC);
+
+CREATE TABLE IF NOT EXISTS discovery_dismissed (
+    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    db_id TEXT NOT NULL,
+    person_id TEXT NOT NULL REFERENCES person(person_id) ON DELETE CASCADE,
+    ai_reason TEXT,
+    ai_tags JSONB CHECK (ai_tags IS NULL OR jsonb_typeof(ai_tags) = 'array'),
+    dismissed_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE (db_id, person_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_discovery_dismissed_db ON discovery_dismissed(db_id);
+CREATE INDEX IF NOT EXISTS idx_discovery_dismissed_person ON discovery_dismissed(person_id);
+
+-- ============================================================================
+-- MEDIA, ENRICHMENT, AND PLACES
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS blob (
+    blob_hash TEXT PRIMARY KEY,
+    path TEXT NOT NULL,
+    mime_type TEXT,
+    size_bytes BIGINT,
+    width INTEGER,
+    height INTEGER,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS media (
+    media_id TEXT PRIMARY KEY,
+    person_id TEXT NOT NULL REFERENCES person(person_id) ON DELETE CASCADE,
+    blob_hash TEXT REFERENCES blob(blob_hash) ON DELETE SET NULL,
+    source TEXT NOT NULL,
+    source_url TEXT,
+    is_primary BOOLEAN NOT NULL DEFAULT FALSE,
+    caption TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_media_person ON media(person_id);
+CREATE INDEX IF NOT EXISTS idx_media_primary ON media(person_id, is_primary);
+
+CREATE TABLE IF NOT EXISTS description (
+    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    person_id TEXT NOT NULL REFERENCES person(person_id) ON DELETE CASCADE,
+    text TEXT NOT NULL,
+    source TEXT NOT NULL,
+    language TEXT NOT NULL DEFAULT 'en',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE (person_id, source)
+);
+
+CREATE INDEX IF NOT EXISTS idx_description_person ON description(person_id);
+
+CREATE TABLE IF NOT EXISTS provider_mapping (
+    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    person_id TEXT NOT NULL REFERENCES person(person_id) ON DELETE CASCADE,
+    provider TEXT NOT NULL,
+    account_id TEXT,
+    match_method TEXT,
+    match_confidence DOUBLE PRECISION DEFAULT 1.0,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE (person_id, provider)
+);
+
+CREATE INDEX IF NOT EXISTS idx_provider_mapping_person ON provider_mapping(person_id);
+
+CREATE TABLE IF NOT EXISTS place_geocode (
+    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    place_text TEXT NOT NULL UNIQUE,
+    lat DOUBLE PRECISION,
+    lng DOUBLE PRECISION,
+    display_name TEXT,
+    geocode_status TEXT NOT NULL DEFAULT 'pending'
+        CHECK (geocode_status IN ('pending', 'resolved', 'not_found', 'error')),
+    geocoded_at TIMESTAMPTZ,
+    source TEXT NOT NULL DEFAULT 'nominatim'
+);
+
+CREATE INDEX IF NOT EXISTS idx_place_geocode_text ON place_geocode(place_text);
+CREATE INDEX IF NOT EXISTS idx_place_geocode_status ON place_geocode(geocode_status);
+
+-- ============================================================================
+-- SEARCH
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS person_search (
+    person_id TEXT PRIMARY KEY REFERENCES person(person_id) ON DELETE CASCADE,
+    display_name TEXT NOT NULL,
+    birth_name TEXT NOT NULL DEFAULT '',
+    aliases TEXT NOT NULL DEFAULT '',
+    bio TEXT NOT NULL DEFAULT '',
+    occupations TEXT NOT NULL DEFAULT '',
+    search_document TSVECTOR GENERATED ALWAYS AS (
+        setweight(to_tsvector('simple'::REGCONFIG, COALESCE(display_name, '')), 'A') ||
+        setweight(to_tsvector('simple'::REGCONFIG, COALESCE(birth_name, '')), 'A') ||
+        setweight(to_tsvector('simple'::REGCONFIG, COALESCE(aliases, '')), 'B') ||
+        setweight(to_tsvector('english'::REGCONFIG, COALESCE(bio, '')), 'C') ||
+        setweight(to_tsvector('english'::REGCONFIG, COALESCE(occupations, '')), 'B')
+    ) STORED
+);
+
+CREATE INDEX IF NOT EXISTS idx_person_search_document ON person_search USING GIN(search_document);
+
+-- ============================================================================
+-- AUDITOR
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS audit_run (
+    run_id TEXT PRIMARY KEY,
+    db_id TEXT NOT NULL,
+    root_person_id TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'queued'
+        CHECK (status IN ('queued', 'running', 'paused', 'completed', 'cancelled', 'error')),
+    config JSONB NOT NULL,
+    cursor JSONB,
+    started_at TIMESTAMPTZ,
+    paused_at TIMESTAMPTZ,
+    completed_at TIMESTAMPTZ,
+    persons_checked INTEGER NOT NULL DEFAULT 0,
+    issues_found INTEGER NOT NULL DEFAULT 0,
+    fixes_applied INTEGER NOT NULL DEFAULT 0,
+    error_message TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_audit_run_db ON audit_run(db_id);
+CREATE INDEX IF NOT EXISTS idx_audit_run_status ON audit_run(status);
+
+CREATE TABLE IF NOT EXISTS audit_issue (
+    issue_id TEXT PRIMARY KEY,
+    run_id TEXT NOT NULL REFERENCES audit_run(run_id) ON DELETE CASCADE,
+    person_id TEXT NOT NULL,
+    issue_type TEXT NOT NULL,
+    severity TEXT NOT NULL CHECK (severity IN ('error', 'warning', 'info', 'hint')),
+    description TEXT NOT NULL,
+    current_value TEXT,
+    suggested_value TEXT,
+    suggested_source TEXT,
+    status TEXT NOT NULL DEFAULT 'open'
+        CHECK (status IN ('open', 'accepted', 'rejected', 'auto_applied')),
+    resolved_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_audit_issue_run ON audit_issue(run_id);
+CREATE INDEX IF NOT EXISTS idx_audit_issue_person ON audit_issue(person_id);
+CREATE INDEX IF NOT EXISTS idx_audit_issue_type ON audit_issue(issue_type);
+CREATE INDEX IF NOT EXISTS idx_audit_issue_status ON audit_issue(status);
+CREATE INDEX IF NOT EXISTS idx_audit_issue_severity ON audit_issue(severity);
+
+CREATE TABLE IF NOT EXISTS audit_change (
+    change_id TEXT PRIMARY KEY,
+    issue_id TEXT REFERENCES audit_issue(issue_id) ON DELETE SET NULL,
+    person_id TEXT NOT NULL,
+    table_name TEXT NOT NULL,
+    field TEXT NOT NULL,
+    old_value TEXT,
+    new_value TEXT,
+    applied_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_audit_change_issue ON audit_change(issue_id);
+CREATE INDEX IF NOT EXISTS idx_audit_change_person ON audit_change(person_id);
+
+-- ============================================================================
+-- CAUSE-OF-DEATH CLASSIFICATION AND MIGRATION TRACKING
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS unusual_death_keyword (
+    keyword TEXT PRIMARY KEY,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+INSERT INTO unusual_death_keyword (keyword) VALUES
+    ('slain'), ('slew'), ('killed in battle'), ('murdered'), ('assassinated'),
+    ('beheaded'), ('decapitated'), ('executed'), ('hanged'), ('guillotin'),
+    ('crucified'), ('stabbed'), ('shot'), ('gunshot'), ('poisoned'),
+    ('strangled'), ('drowned'), ('devoured'), ('eaten by'), ('mauled'),
+    ('trampled'), ('crushed'), ('fell from'), ('fell into'), ('thrown from'),
+    ('gored'), ('plague'), ('leprosy'), ('consumption'), ('cholera'),
+    ('struck by lightning'), ('lightning'), ('froze to death'), ('starved'),
+    ('burned to death'), ('burnt to death'), ('consumed by fire'), ('dragon'),
+    ('serpent'), ('wolves'), ('bear '), ('shipwreck'), ('duel'),
+    ('broken heart'), ('died of grief'), ('mining accident'), ('train accident'),
+    ('railway accident'), ('martyrdom'), ('martyred'), ('suicide')
+ON CONFLICT (keyword) DO NOTHING;
+
+CREATE TABLE IF NOT EXISTS migration (
+    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    name TEXT NOT NULL UNIQUE,
+    applied_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+INSERT INTO migration (name)
+VALUES ('postgres_001_baseline')
+ON CONFLICT (name) DO NOTHING;
+
+-- ============================================================================
+-- VIEWS AND TIMESTAMP TRIGGERS
+-- ============================================================================
+
+CREATE OR REPLACE VIEW person_computed AS
+SELECT
+    person.person_id,
+    person.display_name,
+    person.gender,
+    birth.date_year AS birth_year,
+    birth.place_original AS birth_place,
+    death.date_year AS death_year,
+    death.place_original AS death_place,
+    death.cause AS death_cause,
+    CASE
+        WHEN birth.date_year IS NOT NULL AND death.date_year IS NOT NULL
+        THEN death.date_year - birth.date_year
+    END AS age_at_death,
+    (SELECT COUNT(*) FROM parent_edge WHERE parent_id = person.person_id) AS child_count,
+    (SELECT MIN(date_year) FROM life_event
+     WHERE person_id = person.person_id AND event_type = 'http://gedcomx.org/Marriage') AS first_marriage_year,
+    CASE
+        WHEN birth.date_year IS NOT NULL THEN
+            (SELECT MIN(date_year) FROM life_event
+             WHERE person_id = person.person_id AND event_type = 'http://gedcomx.org/Marriage') - birth.date_year
+    END AS age_at_first_marriage,
+    (SELECT value FROM life_event
+     WHERE person_id = person.person_id AND event_type = 'data:,TitleOfNobility'
+     ORDER BY created_at, event_id LIMIT 1) AS title_of_nobility,
+    (SELECT value FROM life_event
+     WHERE person_id = person.person_id AND event_type = 'http://gedcomx.org/Occupation'
+     ORDER BY created_at, event_id LIMIT 1) AS primary_occupation,
+    (SELECT value FROM life_event
+     WHERE person_id = person.person_id AND event_type = 'http://gedcomx.org/MilitaryService'
+     ORDER BY created_at, event_id LIMIT 1) AS military_service,
+    EXISTS (
+        SELECT 1 FROM note
+        WHERE person_id = person.person_id AND note_type = 'life_sketch'
+    ) AS has_life_sketch
+FROM person
+LEFT JOIN LATERAL (
+    SELECT date_year, place_original
+    FROM life_event
+    WHERE person_id = person.person_id AND event_type = 'http://gedcomx.org/Birth'
+    ORDER BY created_at, event_id
+    LIMIT 1
+) AS birth ON TRUE
+LEFT JOIN LATERAL (
+    SELECT date_year, place_original, cause
+    FROM life_event
+    WHERE person_id = person.person_id AND event_type = 'http://gedcomx.org/Death'
+    ORDER BY created_at, event_id
+    LIMIT 1
+) AS death ON TRUE;
+
+CREATE OR REPLACE FUNCTION sparsetree_set_updated_at()
+RETURNS TRIGGER
+LANGUAGE plpgsql
+AS $$
+BEGIN
+    NEW.updated_at = CURRENT_TIMESTAMP;
+    RETURN NEW;
+END;
+$$;
+
+DO $trigger$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_trigger
+        WHERE tgname = 'trg_person_updated_at'
+          AND tgrelid = 'person'::REGCLASS
+    ) THEN
+        CREATE TRIGGER trg_person_updated_at
+        BEFORE UPDATE ON person
+        FOR EACH ROW EXECUTE FUNCTION sparsetree_set_updated_at();
+    END IF;
+END
+$trigger$;
+
+DO $trigger$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_trigger
+        WHERE tgname = 'trg_life_event_updated_at'
+          AND tgrelid = 'life_event'::REGCLASS
+    ) THEN
+        CREATE TRIGGER trg_life_event_updated_at
+        BEFORE UPDATE ON life_event
+        FOR EACH ROW EXECUTE FUNCTION sparsetree_set_updated_at();
+    END IF;
+END
+$trigger$;
+
+DO $trigger$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_trigger
+        WHERE tgname = 'trg_note_updated_at'
+          AND tgrelid = 'note'::REGCLASS
+    ) THEN
+        CREATE TRIGGER trg_note_updated_at
+        BEFORE UPDATE ON note
+        FOR EACH ROW EXECUTE FUNCTION sparsetree_set_updated_at();
+    END IF;
+END
+$trigger$;
+
+DO $trigger$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_trigger
+        WHERE tgname = 'trg_local_override_updated_at'
+          AND tgrelid = 'local_override'::REGCLASS
+    ) THEN
+        CREATE TRIGGER trg_local_override_updated_at
+        BEFORE UPDATE ON local_override
+        FOR EACH ROW EXECUTE FUNCTION sparsetree_set_updated_at();
+    END IF;
+END
+$trigger$;
+
+CREATE OR REPLACE FUNCTION sparsetree_touch_database_info()
+RETURNS TRIGGER
+LANGUAGE plpgsql
+AS $$
+BEGIN
+    UPDATE database_info
+    SET updated_at = CURRENT_TIMESTAMP
+    WHERE db_id = NEW.db_id;
+    RETURN NEW;
+END;
+$$;
+
+DO $trigger$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_trigger
+        WHERE tgname = 'trg_database_membership_insert'
+          AND tgrelid = 'database_membership'::REGCLASS
+    ) THEN
+        CREATE TRIGGER trg_database_membership_insert
+        AFTER INSERT ON database_membership
+        FOR EACH ROW EXECUTE FUNCTION sparsetree_touch_database_info();
+    END IF;
+END
+$trigger$;
diff --git a/server/src/db/postgres.service.ts b/server/src/db/postgres.service.ts
new file mode 100644
index 00000000..7ae1d925
--- /dev/null
+++ b/server/src/db/postgres.service.ts
@@ -0,0 +1,346 @@
+import { readFile } from 'fs/promises';
+import path from 'path';
+import {
+  Pool,
+  type PoolConfig,
+  type QueryResult,
+  type QueryResultRow,
+} from 'pg';
+
+export const POSTGRES_SCHEMA_PATH = path.join(import.meta.dirname, 'postgres-schema.sql');
+
+export type QueryParams = Record<string, unknown> | readonly unknown[];
+
+interface QueryExecutor {
+  query<T extends QueryResultRow = QueryResultRow>(
+    text: string,
+    values?: unknown[]
+  ): Promise<QueryResult<T>>;
+}
+
+interface PoolClientLike extends QueryExecutor {
+  release(): void;
+}
+
+interface PoolLike extends QueryExecutor {
+  connect(): Promise<PoolClientLike>;
+  end(): Promise<void>;
+}
+
+interface PostgresServiceOptions {
+  connectionString?: string;
+  pool?: PoolLike;
+  poolFactory?: (config: PoolConfig) => PoolLike;
+  schemaPath?: string;
+  schemaSql?: string;
+}
+
+export interface CompiledQuery {
+  text: string;
+  values: unknown[];
+}
+
+type SqlState = 'code' | 'single-quote' | 'double-quote' | 'line-comment' | 'block-comment' | 'dollar-quote';
+
+/**
+ * Resolve the staged PostgreSQL backend configuration without inventing a
+ * local/default credential. An empty value means PostgreSQL is not configured.
+ */
+export function resolveDatabaseUrl(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const value = env.DATABASE_URL?.trim();
+  return value || undefined;
+}
+
+/**
+ * Convert the named @parameter convention used by the current query layer into
+ * pg's positional parameters. Tokens inside strings/comments are left intact.
+ */
+export function compileNamedQuery(sql: string, params: Record<string, unknown>): CompiledQuery {
+  const positions = new Map<string, number>();
+  const values: unknown[] = [];
+  let text = '';
+  let state: SqlState = 'code';
+  let blockCommentDepth = 0;
+  let dollarQuoteDelimiter = '';
+
+  for (let index = 0; index < sql.length;) {
+    const char = sql[index];
+    const next = sql[index + 1];
+
+    if (state === 'single-quote') {
+      text += char;
+      if (char === "'" && next === "'") {
+        text += next;
+        index += 2;
+        continue;
+      }
+      if (char === "'") state = 'code';
+      index++;
+      continue;
+    }
+
+    if (state === 'double-quote') {
+      text += char;
+      if (char === '"' && next === '"') {
+        text += next;
+        index += 2;
+        continue;
+      }
+      if (char === '"') state = 'code';
+      index++;
+      continue;
+    }
+
+    if (state === 'line-comment') {
+      text += char;
+      if (char === '\n') state = 'code';
+      index++;
+      continue;
+    }
+
+    if (state === 'block-comment') {
+      if (char === '/' && next === '*') {
+        text += '/*';
+        blockCommentDepth++;
+        index += 2;
+        continue;
+      }
+      if (char === '*' && next === '/') {
+        text += '*/';
+        blockCommentDepth--;
+        if (blockCommentDepth === 0) state = 'code';
+        index += 2;
+        continue;
+      }
+      text += char;
+      index++;
+      continue;
+    }
+
+    if (state === 'dollar-quote') {
+      if (sql.startsWith(dollarQuoteDelimiter, index)) {
+        text += dollarQuoteDelimiter;
+        index += dollarQuoteDelimiter.length;
+        state = 'code';
+        continue;
+      }
+      text += char;
+      index++;
+      continue;
+    }
+
+    if (char === "'") {
+      state = 'single-quote';
+      text += char;
+      index++;
+      continue;
+    }
+    if (char === '"') {
+      state = 'double-quote';
+      text += char;
+      index++;
+      continue;
+    }
+    if (char === '-' && next === '-') {
+      state = 'line-comment';
+      text += '--';
+      index += 2;
+      continue;
+    }
+    if (char === '/' && next === '*') {
+      state = 'block-comment';
+      blockCommentDepth = 1;
+      text += '/*';
+      index += 2;
+      continue;
+    }
+    if (char === '$') {
+      const delimiter = sql.slice(index).match(/^\$(?:[A-Za-z_][A-Za-z0-9_]*)?\$/)?.[0];
+      if (delimiter) {
+        state = 'dollar-quote';
+        dollarQuoteDelimiter = delimiter;
+        text += delimiter;
+        index += delimiter.length;
+        continue;
+      }
+    }
+    if (char === '@' && next && /[A-Za-z_]/.test(next)) {
+      const match = sql.slice(index + 1).match(/^[A-Za-z_][A-Za-z0-9_]*/);
+      const name = match?.[0];
+      if (!name) {
+        text += char;
+        index++;
+        continue;
+      }
+      if (!Object.prototype.hasOwnProperty.call(params, name)) {
+        throw new Error(`Missing PostgreSQL query parameter: ${name}`);
+      }
+      let position = positions.get(name);
+      if (position === undefined) {
+        values.push(params[name]);
+        position = values.length;
+        positions.set(name, position);
+      }
+      text += `$${position}`;
+      index += name.length + 1;
+      continue;
+    }
+
+    text += char;
+    index++;
+  }
+
+  return { text, values };
+}
+
+function normalizeQuery(sql: string, params?: QueryParams): CompiledQuery {
+  if (!params) return { text: sql, values: [] };
+  if (Array.isArray(params)) return { text: sql, values: [...params] };
+  return compileNamedQuery(sql, params as Record<string, unknown>);
+}
+
+/**
+ * Create an isolated service instance. The exported singleton below uses the
+ * process environment; tests and future workers can inject a pool explicitly.
+ */
+export function createPostgresService(options: PostgresServiceOptions = {}) {
+  const connectionString = options.connectionString?.trim() || resolveDatabaseUrl();
+  const poolFactory = options.poolFactory ?? ((config: PoolConfig) => new Pool(config));
+  let pool: PoolLike | null = options.pool ?? null;
+  let initialization: Promise<void> | null = null;
+
+  const isConfigured = (): boolean => Boolean(pool || connectionString);
+
+  const getPool = (): PoolLike => {
+    if (pool) return pool;
+    if (!connectionString) {
+      throw new Error('PostgreSQL is not configured; set DATABASE_URL to enable the query store');
+    }
+    pool = poolFactory({ connectionString, application_name: 'sparsetree' });
+    return pool;
+  };
+
+  const execute = <T extends QueryResultRow>(
+    executor: QueryExecutor,
+    sql: string,
+    params?: QueryParams
+  ): Promise<QueryResult<T>> => {
+    const query = normalizeQuery(sql, params);
+    return executor.query<T>(query.text, query.values);
+  };
+
+  const queryAll = async <T extends QueryResultRow>(sql: string, params?: QueryParams): Promise<T[]> => {
+    const result = await execute<T>(getPool(), sql, params);
+    return result.rows;
+  };
+
+  const queryOne = async <T extends QueryResultRow>(sql: string, params?: QueryParams): Promise<T | undefined> => {
+    const result = await execute<T>(getPool(), sql, params);
+    return result.rows[0];
+  };
+
+  const run = <T extends QueryResultRow = QueryResultRow>(
+    sql: string,
+    params?: QueryParams
+  ): Promise<QueryResult<T>> => execute<T>(getPool(), sql, params);
+
+  const transaction = async <T>(work: (tx: {
+    queryAll<Row extends QueryResultRow>(sql: string, params?: QueryParams): Promise<Row[]>;
+    queryOne<Row extends QueryResultRow>(sql: string, params?: QueryParams): Promise<Row | undefined>;
+    run<Row extends QueryResultRow = QueryResultRow>(sql: string, params?: QueryParams): Promise<QueryResult<Row>>;
+  }) => Promise<T>): Promise<T> => {
+    const client = await getPool().connect();
+    let started = false;
+    try {
+      await client.query('BEGIN');
+      started = true;
+      const result = await work({
+        queryAll: async <Row extends QueryResultRow>(sql: string, params?: QueryParams) =>
+          (await execute<Row>(client, sql, params)).rows,
+        queryOne: async <Row extends QueryResultRow>(sql: string, params?: QueryParams) =>
+          (await execute<Row>(client, sql, params)).rows[0],
+        run: <Row extends QueryResultRow = QueryResultRow>(sql: string, params?: QueryParams) =>
+          execute<Row>(client, sql, params),
+      });
+      await client.query('COMMIT');
+      return result;
+    } catch (error) {
+      if (started) await client.query('ROLLBACK');
+      throw error;
+    } finally {
+      client.release();
+    }
+  };
+
+  const loadSchema = (): Promise<string> => options.schemaSql !== undefined
+    ? Promise.resolve(options.schemaSql)
+    : readFile(options.schemaPath ?? POSTGRES_SCHEMA_PATH, 'utf8');
+
+  const initDb = (): Promise<void> => {
+    if (!initialization) {
+      initialization = loadSchema()
+        .then((schema) => transaction((tx) => tx.run(schema)))
+        .then(() => undefined)
+        .catch((error) => {
+          initialization = null;
+          throw error;
+        });
+    }
+    return initialization;
+  };
+
+  const isAvailable = (): Promise<boolean> => {
+    if (!isConfigured()) return Promise.resolve(false);
+    return Promise.resolve()
+      .then(() => getPool().query('SELECT 1'))
+      .then(() => true, () => false);
+  };
+
+  const closeDb = async (): Promise<void> => {
+    if (!pool) return;
+    const activePool = pool;
+    pool = null;
+    initialization = null;
+    await activePool.end();
+  };
+
+  const tableExists = async (tableName: string, schema = 'public'): Promise<boolean> => {
+    const row = await queryOne<{ exists: boolean }>(
+      'SELECT to_regclass(@qualifiedName) IS NOT NULL AS exists',
+      { qualifiedName: `${schema}.${tableName}` }
+    );
+    return row?.exists ?? false;
+  };
+
+  const migrationApplied = async (name: string): Promise<boolean> => {
+    const row = await queryOne<{ exists: boolean }>(
+      'SELECT EXISTS (SELECT 1 FROM migration WHERE name = @name) AS exists',
+      { name }
+    );
+    return row?.exists ?? false;
+  };
+
+  const recordMigration = (name: string): Promise<QueryResult> => run(
+    `INSERT INTO migration (name)
+     VALUES (@name)
+     ON CONFLICT (name) DO NOTHING`,
+    { name }
+  );
+
+  return {
+    isConfigured,
+    isAvailable,
+    initDb,
+    getPool,
+    closeDb,
+    queryAll,
+    queryOne,
+    run,
+    transaction,
+    tableExists,
+    migrationApplied,
+    recordMigration,
+  };
+}
+
+export const postgresService = createPostgresService();
diff --git a/tests/integration/db/postgresSchema.spec.ts b/tests/integration/db/postgresSchema.spec.ts
new file mode 100644
index 00000000..d51e5d93
--- /dev/null
+++ b/tests/integration/db/postgresSchema.spec.ts
@@ -0,0 +1,89 @@
+import { readFile } from 'fs/promises';
+import { Pool } from 'pg';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import {
+  POSTGRES_SCHEMA_PATH,
+  createPostgresService,
+} from '../../../server/src/db/postgres.service.js';
+
+const connectionString = process.env.SPARSETREE_TEST_DATABASE_URL;
+const describePostgres = connectionString ? describe : describe.skip;
+
+describePostgres('PostgreSQL schema baseline', () => {
+  const schemaName = `sparsetree_test_${process.pid}_${Date.now()}`;
+  const quotedSchema = `"${schemaName}"`;
+  let pool: Pool;
+  let schemaSql: string;
+
+  beforeAll(async () => {
+    pool = new Pool({ connectionString, application_name: 'sparsetree-schema-test' });
+    await pool.query(`CREATE SCHEMA ${quotedSchema}`);
+    const baseline = await readFile(POSTGRES_SCHEMA_PATH, 'utf8');
+    schemaSql = `SET search_path TO ${quotedSchema};\n${baseline}`;
+  });
+
+  afterAll(async () => {
+    if (!pool) return;
+    await pool.query(`DROP SCHEMA IF EXISTS ${quotedSchema} CASCADE`);
+    await pool.end();
+  });
+
+  it('can be applied twice and creates the current derived-store tables', async () => {
+    await createPostgresService({ pool, schemaSql }).initDb();
+    await createPostgresService({ pool, schemaSql }).initDb();
+
+    const result = await pool.query<{ table_name: string }>(
+      `SELECT table_name
+       FROM information_schema.tables
+       WHERE table_schema = $1 AND table_type = 'BASE TABLE'
+       ORDER BY table_name`,
+      [schemaName]
+    );
+
+    expect(result.rows.map((row) => row.table_name)).toEqual(expect.arrayContaining([
+      'person',
+      'external_identity',
+      'parent_edge',
+      'database_info',
+      'database_membership',
+      'favorite',
+      'local_override',
+      'person_search',
+      'audit_run',
+      'audit_issue',
+      'audit_change',
+      'migration',
+    ]));
+  });
+
+  it('uses PostgreSQL-native booleans, timestamps, JSON, and indexed tsvectors', async () => {
+    const columns = await pool.query<{ table_name: string; column_name: string; data_type: string }>(
+      `SELECT table_name, column_name, data_type
+       FROM information_schema.columns
+       WHERE table_schema = $1
+         AND (table_name, column_name) IN (
+           ('person', 'living'),
+           ('person', 'created_at'),
+           ('favorite', 'tags'),
+           ('audit_run', 'config'),
+           ('person_search', 'search_document')
+         )`,
+      [schemaName]
+    );
+
+    expect(columns.rows).toEqual(expect.arrayContaining([
+      expect.objectContaining({ table_name: 'person', column_name: 'living', data_type: 'boolean' }),
+      expect.objectContaining({ table_name: 'person', column_name: 'created_at', data_type: 'timestamp with time zone' }),
+      expect.objectContaining({ table_name: 'favorite', column_name: 'tags', data_type: 'jsonb' }),
+      expect.objectContaining({ table_name: 'audit_run', column_name: 'config', data_type: 'jsonb' }),
+      expect.objectContaining({ table_name: 'person_search', column_name: 'search_document', data_type: 'tsvector' }),
+    ]));
+
+    const searchIndex = await pool.query<{ indexdef: string }>(
+      `SELECT indexdef FROM pg_indexes
+       WHERE schemaname = $1 AND indexname = 'idx_person_search_document'`,
+      [schemaName]
+    );
+    expect(searchIndex.rows[0]?.indexdef).toContain('USING gin');
+  });
+});
diff --git a/tests/unit/db/postgresService.spec.ts b/tests/unit/db/postgresService.spec.ts
new file mode 100644
index 00000000..f372aa2b
--- /dev/null
+++ b/tests/unit/db/postgresService.spec.ts
@@ -0,0 +1,186 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  compileNamedQuery,
+  createPostgresService,
+  resolveDatabaseUrl,
+} from '../../../server/src/db/postgres.service.js';
+
+const queryResult = <T extends Record<string, unknown>>(rows: T[] = []) => ({
+  command: 'SELECT',
+  rowCount: rows.length,
+  oid: 0,
+  fields: [],
+  rows,
+});
+
+function createPoolMock() {
+  const client = {
+    query: vi.fn(async () => queryResult()),
+    release: vi.fn(),
+  };
+  return {
+    client,
+    pool: {
+      query: vi.fn(async () => queryResult()),
+      connect: vi.fn(async () => client),
+      end: vi.fn(async () => undefined),
+    },
+  };
+}
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.restoreAllMocks();
+});
+
+describe('PostgreSQL configuration', () => {
+  it('uses only a non-empty DATABASE_URL', () => {
+    expect(resolveDatabaseUrl({ DATABASE_URL: ' postgresql://localhost/sparsetree ' }))
+      .toBe('postgresql://localhost/sparsetree');
+    expect(resolveDatabaseUrl({ DATABASE_URL: '   ' })).toBeUndefined();
+    expect(resolveDatabaseUrl({})).toBeUndefined();
+  });
+
+  it('does not create a pool until a query needs one', async () => {
+    const { pool } = createPoolMock();
+    const poolFactory = vi.fn(() => pool);
+    const service = createPostgresService({
+      connectionString: 'postgresql://localhost/sparsetree',
+      poolFactory,
+    });
+
+    expect(service.isConfigured()).toBe(true);
+    expect(poolFactory).not.toHaveBeenCalled();
+
+    await service.queryAll('SELECT 1');
+
+    expect(poolFactory).toHaveBeenCalledWith({
+      connectionString: 'postgresql://localhost/sparsetree',
+      application_name: 'sparsetree',
+    });
+  });
+
+  it('reports an absent or unreachable database as unavailable', async () => {
+    vi.stubEnv('DATABASE_URL', '');
+    const unconfigured = createPostgresService();
+    const { pool } = createPoolMock();
+    pool.query.mockRejectedValueOnce(new Error('connection refused'));
+    const unreachable = createPostgresService({ pool });
+
+    await expect(unconfigured.isAvailable()).resolves.toBe(false);
+    expect(() => unconfigured.getPool()).toThrow('set DATABASE_URL');
+    await expect(unreachable.isAvailable()).resolves.toBe(false);
+  });
+});
+
+describe('compileNamedQuery', () => {
+  it('reuses positions and ignores tokens inside PostgreSQL literals and comments', () => {
+    const compiled = compileNamedQuery(
+      `SELECT '@literal', "@identifier", $$@dollar$$
+       FROM person
+       WHERE person_id = @personId OR person_id = @personId
+         AND display_name = @name -- @lineComment
+         /* outer @comment /* nested @comment */ still ignored */`,
+      { personId: '01PERSON', name: 'Ada' }
+    );
+
+    expect(compiled.text).toContain('person_id = $1 OR person_id = $1');
+    expect(compiled.text).toContain('display_name = $2');
+    expect(compiled.text).toContain("'@literal'");
+    expect(compiled.text).toContain('$$@dollar$$');
+    expect(compiled.text).toContain('-- @lineComment');
+    expect(compiled.values).toEqual(['01PERSON', 'Ada']);
+  });
+
+  it('fails before querying when a named value is missing', () => {
+    expect(() => compileNamedQuery('SELECT * FROM person WHERE person_id = @personId', {}))
+      .toThrow('Missing PostgreSQL query parameter: personId');
+  });
+});
+
+describe('PostgreSQL query service', () => {
+  it('returns rows and forwards named parameters as positional values', async () => {
+    const { pool } = createPoolMock();
+    pool.query.mockResolvedValueOnce(queryResult([{ person_id: '01PERSON' }]));
+    const service = createPostgresService({ pool });
+
+    await expect(service.queryOne<{ person_id: string }>(
+      'SELECT person_id FROM person WHERE person_id = @personId',
+      { personId: '01PERSON' }
+    )).resolves.toEqual({ person_id: '01PERSON' });
+
+    expect(pool.query).toHaveBeenCalledWith(
+      'SELECT person_id FROM person WHERE person_id = $1',
+      ['01PERSON']
+    );
+  });
+
+  it('commits successful transactions and releases the client', async () => {
+    const { client, pool } = createPoolMock();
+    client.query
+      .mockResolvedValueOnce(queryResult())
+      .mockResolvedValueOnce(queryResult([{ person_id: '01PERSON' }]))
+      .mockResolvedValueOnce(queryResult());
+    const service = createPostgresService({ pool });
+
+    const result = await service.transaction(async (tx) => tx.queryOne<{ person_id: string }>(
+      'SELECT person_id FROM person WHERE person_id = @personId',
+      { personId: '01PERSON' }
+    ));
+
+    expect(result).toEqual({ person_id: '01PERSON' });
+    expect(client.query.mock.calls).toEqual([
+      ['BEGIN'],
+      ['SELECT person_id FROM person WHERE person_id = $1', ['01PERSON']],
+      ['COMMIT'],
+    ]);
+    expect(client.release).toHaveBeenCalledOnce();
+  });
+
+  it('rolls back failed transactions and releases the client', async () => {
+    const { client, pool } = createPoolMock();
+    const service = createPostgresService({ pool });
+
+    await expect(service.transaction(async () => {
+      throw new Error('write failed');
+    })).rejects.toThrow('write failed');
+
+    expect(client.query.mock.calls).toEqual([['BEGIN'], ['ROLLBACK']]);
+    expect(client.release).toHaveBeenCalledOnce();
+  });
+
+  it('initializes one time per service and retries after a failed initialization', async () => {
+    const { client, pool } = createPoolMock();
+    client.query
+      .mockResolvedValueOnce(queryResult())
+      .mockRejectedValueOnce(new Error('schema unavailable'))
+      .mockResolvedValueOnce(queryResult())
+      .mockResolvedValueOnce(queryResult())
+      .mockResolvedValueOnce(queryResult())
+      .mockResolvedValueOnce(queryResult());
+    const service = createPostgresService({ pool, schemaSql: 'CREATE TABLE example (id TEXT)' });
+
+    await expect(service.initDb()).rejects.toThrow('schema unavailable');
+    await expect(service.initDb()).resolves.toBeUndefined();
+    await expect(service.initDb()).resolves.toBeUndefined();
+
+    expect(client.query.mock.calls).toEqual([
+      ['BEGIN'],
+      ['CREATE TABLE example (id TEXT)', []],
+      ['ROLLBACK'],
+      ['BEGIN'],
+      ['CREATE TABLE example (id TEXT)', []],
+      ['COMMIT'],
+    ]);
+  });
+
+  it('closes the pool and clears configured state', async () => {
+    const { pool } = createPoolMock();
+    const service = createPostgresService({ pool });
+
+    await service.closeDb();
+
+    expect(pool.end).toHaveBeenCalledOnce();
+    expect(service.isConfigured()).toBe(false);
+  });
+});