feat: PostgreSQL sink backend

.agents/skills/sink-parity/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: sink-parity
+description: Keep the fs, mongo and postgres sink backends at feature parity when changing any of them
+---
+
+Keep the sink backends at feature parity.
+
+Read `AGENTS.md` first. It is the canonical project guide for this repository.
+
+GitProxy persists its state through interchangeable sink backends: `src/db/file` (NeDB), `src/db/mongo`, and `src/db/postgres`. They all implement the `Sink` interface in `src/db/types.ts`, and deployments pick one via the `sink` config. A feature that exists in one backend but not the others is a bug waiting for whichever deployment uses the others.
+
+Use this skill whenever a change touches any of:
+
+- the `Sink` interface or the entity classes (`Repo`, `User`, push types) in `src/db/types.ts`
+- any backend adapter under `src/db/file`, `src/db/mongo`, or `src/db/postgres`
+- the migration framework (`src/db/migrations`) or the postgres schema
+
+## The contract
+
+- `src/db/types.ts` is the single source of truth: the `Sink` interface plus the doc comments on its members define the behaviour every backend must provide. No backend implementation, mongo included, outranks the contract. A new `Sink` member or entity field is not done until all three backends implement it in the same change; do not leave a backend behind for a follow-up.
+- `npm run check-types:server` enforces the interface structurally, but it cannot see semantic drift. The rest of this checklist exists for what the compiler cannot catch.
+
+## Adding or changing a Sink member
+
+1. Add the member to the `Sink` interface with a doc comment stating its semantics (ordering, case sensitivity, empty-result shape).
+2. Implement it in `src/db/file`, `src/db/mongo`, and `src/db/postgres`. The doc comment on the interface member is the reference for behaviour, not any one backend: whichever implementation lands first defines the semantics, so spell them out in the doc comment and make the other backends match it. Historically most members appeared in mongo first, but new functionality can just as well start in postgres; do not assume mongo is the template.
+3. Export it from each backend's `index.ts` and wire the dispatcher in `src/db/index.ts`.
+4. Add unit tests for every backend, not just the one you started from.
+
+## Adding a field to an entity
+
+1. Update the class in `src/db/types.ts`.
+2. fs and mongo store documents whole, so writes usually pass new fields through automatically; verify reads return them.
+3. postgres maps fields to columns explicitly, so every layer must be updated by hand:
+   - schema: add the column (see the migration rules below)
+   - create: insert the field, applying the same defaults as mongo (for example `dateCreated`/`lastModified` are stamped with the current ISO time on create)
+   - update: extend the column allowlist; a field missing from the allowlist is dropped silently, and an update reduced to zero columns throws, which has already nearly shipped a startup crash (`populateRepoDates`)
+   - read: add the column to every select and to the row-to-entity mapping
+4. If mongo or fs bump `lastModified` (or similar) on a mutation, every backend must bump it on that mutation.
+
+## Postgres schema changes
+
+- Schema changes are append-only migrations; never edit or reorder an entry that has shipped.
+- Cross-backend logical migrations belong in `src/db/migrations` (registered in `registry.ts`) and run through the `Sink` hooks (`getAppliedMigrations`, `recordMigration`, `unrecordMigration`), so they must work against all three backends.
+- `deriveCreatedAt` is best-effort by design: mongo derives a timestamp from the ObjectId, fs and postgres return `undefined` and callers fall back. Do not assume it returns a value.
+
+## Semantic parity rules
+
+- Same defaults on create in every backend.
+- Same case handling: usernames are lowercased on permission changes; name lookups are case-insensitive where mongo's are.
+- Same projections: list endpoints must return the same field set from every backend, or UI behaviour diverges by deployment.
+- Same error behaviour for invalid input (missing id, empty update).
+
+## Tests
+
+- Each backend has unit tests under `test/db/<backend>` that mock the driver (`pg` is mocked for postgres, NeDB runs in-memory for fs). Integration tests (`test/db/postgres/*.integration.test.ts`, `test/db/mongo/*.integration.test.ts`) run against a real service and are skipped when none is reachable; CI runs them in dedicated lanes.
+- When you touch a backend, add or extend BOTH kinds for it: unit coverage for the logic, integration coverage for the real query shapes. The fs backend has no external service, so unit coverage is enough there.
+- Keep the test scenarios aligned across backends: perform the same operations with the same inputs, and assert the same outputs, so parity is something the suite proves rather than something reviewers eyeball. If a scenario genuinely does not apply to a backend, say so in a comment instead of silently skipping it.
+
+## Verify before pushing
+
+```
+npm run check-types:server
+cross-env NODE_ENV=test npx vitest --run test/db
+npm run lint
+npm run format:check
+```
+
+Postgres integration tests (`npm run test:integration:postgres`) need a reachable PostgreSQL database; CI runs them in the dedicated lane.

.github/workflows/ci.yml

@@ -22,6 +22,24 @@ jobs:
         node-version: [22.x, 24.x]
         mongodb-version: ['6.0', '7.0', '8.0']
 
+    # PostgreSQL service container for the postgres integration tests. A
+    # single version (postgres:16) keeps the lane fast; a broader version
+    # matrix can follow later if needed.
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: git_proxy_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
     steps:
       - name: Harden Runner
         uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
@@ -71,6 +89,12 @@ jobs:
           GIT_PROXY_MONGO_CONNECTION_STRING: mongodb://localhost:27017/git-proxy-test
         run: npm run test:integration
 
+      - name: PostgreSQL Integration Tests
+        env:
+          RUN_POSTGRES_TESTS: 'true'
+          GIT_PROXY_POSTGRES_CONNECTION_STRING: postgresql://postgres:postgres@localhost:5432/git_proxy_test
+        run: npm run test:integration:postgres
+
       - name: Upload test coverage report
         uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:

.opencode/commands/sink-parity.md

@@ -0,0 +1,5 @@
+---
+description: Keep the fs, mongo and postgres sink backends at feature parity
+---
+
+Follow @.agents/skills/sink-parity/SKILL.md.

AGENTS.md

@@ -375,6 +375,10 @@ This file is the canonical project guide. Tool-specific entry points:
 - OpenCode: `.opencode/commands/`
 - Codex: `AGENTS.md`
 
+### Database changes
+
+The fs, mongo and postgres sink backends must stay at feature parity. Before changing anything under `src/db`, read `.agents/skills/sink-parity/SKILL.md`: apparently simple adaptor changes usually cost more on the postgres side (explicit columns, update allowlists, append-only schema migrations) than on the document stores, and the skill carries the checklist that keeps the backends aligned.
+
 ---
 
 ## Agent Workflow

CONTRIBUTING.md

@@ -12,6 +12,8 @@ For project governance, roles, and voting procedures, see the [Governance sectio
 - [Development Workflow](#development-workflow)
 - [Testing](#testing)
   - [Unit Tests](#unit-tests)
+  - [MongoDB Integration Tests](#mongodb-integration-tests)
+  - [PostgreSQL Integration Tests](#postgresql-integration-tests)
   - [End-to-End Tests](#end-to-end-tests)
   - [UI Tests (Cypress)](#ui-tests-cypress)
   - [Fuzz Tests](#fuzz-tests)
@@ -87,7 +89,7 @@ git-proxy/
 ├── src/
 │   ├── proxy/              # Core proxy logic (action chain, processors)
 │   ├── service/            # Express app, API routes, authentication (Passport.js)
-│   ├── db/                 # Database abstraction (MongoDB + NeDB)
+│   ├── db/                 # Database abstraction (MongoDB, PostgreSQL, NeDB)
 │   ├── config/             # Configuration loading and generated types
 │   ├── ui/                 # React dashboard (Material-UI)
 │   ├── plugin.ts           # Plugin base classes (PushActionPlugin, PullActionPlugin)
@@ -113,7 +115,7 @@ git-proxy/
 
 - **Action chain**: Git push/fetch requests flow through a chain of processors in `src/proxy/chain.ts`
 - **Plugin system**: Extends the action chain with custom logic (see `src/plugin.ts`)
-- **Dual database**: MongoDB for production state; [NeDB](https://github.com/seald/nedb) for local file-based development (`.data/` directory)
+- **Pluggable database**: MongoDB or PostgreSQL for production state; [NeDB](https://github.com/seald/nedb) for local file-based development (`.data/` directory)
 - **Authentication**: Passport.js strategies (local, Active Directory, OpenID Connect)
 
 ## Development Workflow
@@ -202,6 +204,31 @@ Configuration: [vitest.config.integration.ts](vitest.config.integration.ts)
 
 In CI, `RUN_MONGO_TESTS` is set automatically in the workflow that runs integration tests.
 
+### PostgreSQL Integration Tests
+
+Some tests require a real PostgreSQL instance. These are guarded by the `RUN_POSTGRES_TESTS` environment variable and run separately from unit tests.
+
+```bash
+# Start PostgreSQL with Docker
+docker run -d --name postgres-test -p 5432:5432 \
+  -e POSTGRES_USER=postgres \
+  -e POSTGRES_PASSWORD=postgres \
+  -e POSTGRES_DB=git_proxy_test \
+  postgres:16
+
+# Run PostgreSQL integration tests
+npm run test:integration:postgres
+
+# Cleanup
+docker stop postgres-test && docker rm postgres-test
+```
+
+Configuration: [vitest.config.integration.postgres.ts](vitest.config.integration.postgres.ts)
+
+Unlike the MongoDB lane, `RUN_POSTGRES_TESTS` and the connection string are set by the Vitest config itself, so no extra environment variables are required on the command line — you only need a PostgreSQL instance reachable at `postgresql://postgres:postgres@localhost:5432/git_proxy_test`.
+
+In CI, the PostgreSQL integration tests run against a `postgres:16` service container in the same workflow as the MongoDB integration tests.
+
 ### End-to-End Tests
 
 E2E tests perform real git operations against a Dockerized environment. They use Vitest with a separate config.

config.schema.json

@@ -568,6 +568,81 @@
             "enabled": { "type": "boolean" }
           },
           "required": ["type", "enabled"]
+        },
+        {
+          "type": "object",
+          "name": "PostgreSQL Config",
+          "description": "Connection properties for PostgreSQL. The `connectionString` may also be supplied via the `GIT_PROXY_POSTGRES_CONNECTION_STRING` environment variable. If neither a `connectionString` nor the discrete `host`/`port`/`user`/`password`/`database` fields are set, the standard `PGHOST`/`PGPORT`/`PGUSER`/`PGPASSWORD`/`PGDATABASE` environment variables are used.",
+          "properties": {
+            "type": { "type": "string", "const": "postgres" },
+            "enabled": { "type": "boolean" },
+            "connectionString": {
+              "type": "string",
+              "description": "PostgreSQL client connection string, see [https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING). If omitted, `GIT_PROXY_POSTGRES_CONNECTION_STRING` is used as a fallback, then the discrete fields below, then the `PG*` environment variables. Takes precedence over the discrete fields when set."
+            },
+            "host": {
+              "type": "string",
+              "description": "Database server host. Used when `connectionString` is not set. Falls back to the `PGHOST` environment variable."
+            },
+            "port": {
+              "type": "number",
+              "description": "Database server port. Used when `connectionString` is not set. Falls back to the `PGPORT` environment variable."
+            },
+            "user": {
+              "type": "string",
+              "description": "Database user. Used when `connectionString` is not set. Falls back to the `PGUSER` environment variable."
+            },
+            "password": {
+              "type": "string",
+              "description": "Database password. Used when `connectionString` is not set. Falls back to the `PGPASSWORD` environment variable."
+            },
+            "database": {
+              "type": "string",
+              "description": "Database name. Used when `connectionString` is not set. Falls back to the `PGDATABASE` environment variable."
+            },
+            "autoMigrate": {
+              "type": "boolean",
+              "description": "Run pending schema migrations automatically at startup (default `true`). Set to `false` when the runtime database role must not hold DDL rights: apply migrations out-of-band with DDL-capable credentials (`npm run migrate:postgres:schema`), and startup will only verify the schema is current, refusing to start while any migration is pending."
+            },
+            "ssl": {
+              "description": "TLS configuration for the connection. `true` enables TLS with default certificate verification; an object is passed to the PostgreSQL client as TLS options (for example `rejectUnauthorized`, `ca`, `cert`, `key`).",
+              "oneOf": [{ "type": "boolean" }, { "type": "object", "additionalProperties": true }]
+            },
+            "pool": {
+              "type": "object",
+              "description": "Connection pool tuning passed to the PostgreSQL client.",
+              "properties": {
+                "max": {
+                  "type": "number",
+                  "description": "Maximum number of clients the pool may hold."
+                },
+                "idleTimeoutMillis": {
+                  "type": "number",
+                  "description": "Milliseconds a client may sit idle in the pool before being closed."
+                },
+                "connectionTimeoutMillis": {
+                  "type": "number",
+                  "description": "Milliseconds to wait for a connection before timing out."
+                }
+              }
+            },
+            "awsIamAuth": {
+              "type": "object",
+              "description": "Authenticate to Amazon RDS/Aurora with an IAM auth token instead of a static password. When enabled, a short-lived token is generated for each new connection from the AWS SDK default credential chain, so no password is stored. Requires the discrete `host`/`port`/`user` fields (or the `PGHOST`/`PGPORT`/`PGUSER` environment variables) rather than a `connectionString`, requires TLS (`ssl` defaults to `true` when omitted), and needs the optional `@aws-sdk/rds-signer` dependency to be installed.",
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "description": "Enable IAM token authentication for the PostgreSQL connection."
+                },
+                "region": {
+                  "type": "string",
+                  "description": "AWS region of the RDS/Aurora instance. Falls back to the `AWS_REGION` / `AWS_DEFAULT_REGION` environment variables, then the AWS SDK's default region resolution."
+                }
+              },
+              "required": ["enabled"]
+            }
+          },
+          "required": ["type", "enabled"]
         }
       ]
     },

eslint.config.mjs

@@ -57,6 +57,8 @@ export default defineConfig(
       // vendored code we're not changing
       'src/ui/assets/js/**',
       'src/ui/assets/css/**',
+      // local claude worktrees / scratch
+      '.claude/**',
     ],
   },