feat: add PostgreSQL query-store foundation (#148)

.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`).

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

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
     },

server/package.json

@@ -5,14 +5,15 @@
   "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": {
     "@fsf/shared": "*",
     "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"
   }
 }