Skip to content

feat: add optional PostgreSQL + pgvector backend#375

Open
chrisdietr wants to merge 1 commit intotobi:mainfrom
chrisdietr:feat/postgres-backend-v2
Open

feat: add optional PostgreSQL + pgvector backend#375
chrisdietr wants to merge 1 commit intotobi:mainfrom
chrisdietr:feat/postgres-backend-v2

Conversation

@chrisdietr
Copy link

Summary

Adds PostgreSQL + pgvector as an optional backend for QMD.

SQLite remains the default. PostgreSQL is opt-in via:

  • QMD_BACKEND=postgres
  • QMD_POSTGRES_URL=postgresql://...

This version is rebuilt against the current v2 layout on main, so the diff matches the current code organization instead of the old pre-v2 structure.

Why

SQLite is still the best default for local single-user usage.

PostgreSQL is useful for shared or multi-process deployments where multiple agents or services need concurrent access to the same QMD index.

What changed

  • backend selection in src/db.ts
  • PostgreSQL adapter in src/pg.ts
  • PostgreSQL worker in src/pg-worker.ts
  • PostgreSQL schema/store support in src/store.ts
  • CLI status output updated in src/cli/qmd.ts
  • SDK wording updated in src/index.ts
  • docs and changelog updates
  • opt-in PostgreSQL integration tests

Out of scope

  • automatic migration from SQLite to PostgreSQL
  • changing the default backend
  • MCP-specific feature changes beyond store/backend compatibility
  • larger public SDK API redesign

Reviewer guide

Suggested review order:

  1. src/db.ts
  2. src/pg.ts
  3. src/pg-worker.ts
  4. src/store.ts
  5. src/cli/qmd.ts
  6. src/index.ts
  7. test/store.postgres.test.ts
  8. README.md
  9. CHANGELOG.md

Validation

  • bun run build
  • bun test --preload ./src/test-preload.ts test/sdk.test.ts
  • PostgreSQL integration tests are opt-in
  • sqlite-vec-dependent tests still depend on local extension-loading support
AI-assisted development notes

Prompts used

  • Port the PostgreSQL backend work onto the current v2 layout without reintroducing obsolete files.
  • Move CLI-related changes from the old src/qmd.ts location into src/cli/qmd.ts.
  • Keep SQLite as the default backend and make PostgreSQL opt-in.
  • Avoid unnecessary MCP-specific branching if the store/SDK layer already handles backend differences.

Decision summary

  • Rebuilt this as a v2-native change instead of preserving the old pre-v2 file layout.
  • Kept backend selection environment-driven in this PR to limit surface-area changes.
  • Left MCP mostly untouched because it already consumes the SDK/store layer.
  • Added PostgreSQL coverage as opt-in integration tests.
  • Updated SDK wording to be backend-neutral and exposed QMDStore.backend.

Alternatives considered

  • Updating the original pre-v2 PR directly
    Rejected because the resulting diff was harder to review after the v2 refactor.

  • Adding explicit PostgreSQL constructor options to the stable SDK in this PR
    Deferred to keep this change focused on backend support.

Validation performed

  • verified PostgreSQL schema initialization path
  • verified PostgreSQL FTS behavior in tests
  • verified pgvector-backed similarity search path in tests
  • verified CLI status output logic for SQLite vs PostgreSQL
  • verified TypeScript build and SDK tests

@chrisdietr chrisdietr force-pushed the feat/postgres-backend-v2 branch from 8d183e3 to 55328be Compare March 11, 2026 15:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant