refactor: switch to pg driver

* update docs

README.md

···
 # Twisted
 
-Twisted is a monorepo for a Tangled mobile client and the supporting Tap-backed indexing API.
+Twisted is a monorepo for a Tangled mobile client and a Tap-backed indexing API.
 
 ## Projects
 
-- `apps/twisted`: Ionic Vue client for browsing Tangled repos, profiles, issues, PRs, and indexed search results
-- `packages/api`: Go service that consumes Tangled records through Tap, fills gaps in the public Tangled API, and serves search
-- `docs`: top-level specs and plans, split by project under `docs/app` and `docs/api`
+- `apps/twisted`: Ionic Vue client for browsing Tangled repos, profiles, issues, PRs, and search
+- `packages/api`: Go service for ingest, search, read-through indexing, and activity cache
+- `docs`: project docs, ADRs, and operational references
 
 ## Architecture
 
-The app still uses Tangled's public knot and PDS APIs for canonical repo and profile data. The API project adds two complementary capabilities:
+The app still reads canonical repo and profile data from Tangled and AT Protocol APIs.
+The API adds:
 
-1. Global search over indexed Tangled content
-2. Index-backed summaries for data that is hard to derive from the public API alone, such as followers
+1. network-wide search over indexed Tangled content
+2. index-backed summaries that are hard to derive from public APIs alone
 
-That keeps direct browsing honest while giving the client one place to ask for cross-network discovery and graph augmentation.
+The backend now targets PostgreSQL for both local and remote deployments.
 
 ## Development
 
-Use the top-level [`justfile`](justfile) for common workflows (`just --list` to view)
-
-Use `apps/twisted/.env.local` for machine-local overrides such as a localhost API or OAuth callback.
-
-## Run Locally
-
-Install dependencies once from the repo root:
+Install JS dependencies once:
 
 ```bash
 pnpm install
 ```
 
-Start the Ionic/Vite app:
+Default local database URL:
 
 ```bash
-pnpm dev # or: just dev
+postgresql://localhost/${USER}_dev?sslmode=disable
 ```
 
-That serves the client from `apps/twisted` with Vite.
-
-To run the Go API locally for routine experimentation, no Turso credentials are required.
+That matches the Postgres.app-style local workflow and also matches the repo's
+`docker-compose.dev.yaml` if you want disposable local Postgres and Tap
+containers instead.
 
-Start the API in local file mode:
+Start the local database:
 
 ```bash
-pnpm api:run:api # or: just api-dev
+just db-up
 ```
 
-This serves the API and search site on `http://localhost:8080` using
-`packages/api/twister-dev.db`.
+Run the mobile app:
 
-To run the API against remote Turso instead:
+```bash
+pnpm dev
+```
+
+Run the API against local Postgres:
 
 ```bash
-just api-dev remote
+just api-dev
 ```
 
-Run the API smoke checks from the repo root:
+Run the indexer against local Postgres:
 
 ```bash
-uv run --project packages/scripts/api twister-api-smoke
+just api-run-indexer
 ```
 
-To verify admin endpoints as well, ensure `ADMIN_AUTH_TOKEN` is present in the
-environment before running the smoke script.
+Use `just api-dev sqlite` or `just api-run-indexer sqlite` only for the
+temporary SQLite rollback path.
 
-To run the indexer in local file mode as well:
+If you want the app to call the local API, put this in `apps/twisted/.env.local`:
 
 ```bash
-pnpm api:run:indexer # or: just api-run-indexer
+VITE_TWISTER_API_BASE_URL=http://localhost:8080
 ```
 
-To run the indexer against remote Turso, `packages/api/.env` needs:
-
-- `TAP_URL`
-- `TAP_AUTH_PASSWORD`
-- `INDEXED_COLLECTIONS`
+Run the API smoke checks from the repo root:
 
 ```bash
-just api-run-indexer remote
+uv run --project packages/scripts/api twister-api-smoke
 ```
 
-Typical local setup is three terminals:
+If `ADMIN_AUTH_TOKEN` is present, the smoke script also checks admin status.
 
-1. `pnpm dev`
-2. `pnpm api:run:api`
-3. `pnpm api:run:indexer`
+## Deployment
 
-If you want the app to call the local API, put this in `apps/twisted/.env.local`:
+Production deployment now uses Coolify plus a separate Coolify-managed
+PostgreSQL instance. The backend services are defined in
+`docker-compose.prod.yaml`.
 
-```bash
-VITE_TWISTER_API_BASE_URL=http://localhost:8080
-```
-
-Dev builds keep the current OAuth flow available. Production builds are read-only
-and hide auth entry points for now.
+See [`docs/reference/deployment-walkthrough.md`](docs/reference/deployment-walkthrough.md)
+for the full setup, bootstrap, backup, and cutover flow.
 
 ## Attributions
 
-This project relies heavily on the work of the [Tangled team](https://tangled.org/tangled.org) (duh)
-and the infrastructure made available by [microcosm](https://microcosm.blue), specifically
-Lightrail and Constellation.
+This project relies heavily on the work of the
+[Tangled team](https://tangled.org/tangled.org) and the infrastructure made
+available by [microcosm](https://microcosm.blue), especially Lightrail and
+Constellation.

docker-compose.dev.yaml

···
+services:
+  postgres:
+    image: postgres:17-alpine
+    restart: unless-stopped
+    ports:
+      - "5432:5432"
+    environment:
+      POSTGRES_USER: ${USER:-postgres}
+      POSTGRES_DB: ${USER:-postgres}_dev
+      POSTGRES_HOST_AUTH_METHOD: trust
+    volumes:
+      - twisted-postgres:/var/lib/postgresql/data
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          "pg_isready -h localhost -p 5432 -U ${USER:-postgres} -d ${USER:-postgres}_dev",
+        ]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  tap:
+    image: ghcr.io/bluesky-social/indigo/tap:sha-4f47add43060c27e8a37d9d76482ecddf001fcd8
+    restart: unless-stopped
+    ports:
+      - "2480:2480"
+    environment:
+      TAP_BIND: :2480
+      TAP_DATABASE_URL: sqlite:///data/tap.db
+      TAP_ADMIN_PASSWORD: ${TAP_AUTH_PASSWORD:-twisted-dev}
+      TAP_LOG_LEVEL: ${TAP_LOG_LEVEL:-info}
+      TAP_COLLECTION_FILTERS: ${TAP_COLLECTION_FILTERS:-}
+    volumes:
+      - twisted-tap:/data
+
+volumes:
+  twisted-postgres:
+  twisted-tap:

docker-compose.prod.yaml

···
+services:
+  api:
+    build:
+      context: ./packages/api
+      dockerfile: Dockerfile
+    command: ["twister", "api"]
+    restart: unless-stopped
+    environment:
+      DATABASE_URL: ${DATABASE_URL:?DATABASE_URL is required}
+      HTTP_BIND_ADDR: ${HTTP_BIND_ADDR:-:8080}
+      LOG_LEVEL: ${LOG_LEVEL:-info}
+      LOG_FORMAT: ${LOG_FORMAT:-json}
+      SEARCH_DEFAULT_LIMIT: ${SEARCH_DEFAULT_LIMIT:-20}
+      SEARCH_MAX_LIMIT: ${SEARCH_MAX_LIMIT:-100}
+      SEARCH_DEFAULT_MODE: ${SEARCH_DEFAULT_MODE:-keyword}
+      READ_THROUGH_MODE: ${READ_THROUGH_MODE:-missing}
+      READ_THROUGH_COLLECTIONS: ${READ_THROUGH_COLLECTIONS:-}
+      READ_THROUGH_MAX_ATTEMPTS: ${READ_THROUGH_MAX_ATTEMPTS:-5}
+      INDEXED_COLLECTIONS: ${INDEXED_COLLECTIONS:-}
+      ENABLE_ADMIN_ENDPOINTS: ${ENABLE_ADMIN_ENDPOINTS:-false}
+      ADMIN_AUTH_TOKEN: ${ADMIN_AUTH_TOKEN:-}
+      OAUTH_CLIENT_ID: ${OAUTH_CLIENT_ID:-}
+      OAUTH_REDIRECT_URIS: ${OAUTH_REDIRECT_URIS:-}
+    expose:
+      - "8080"
+
+  indexer:
+    build:
+      context: ./packages/api
+      dockerfile: Dockerfile
+    command: ["twister", "indexer"]
+    restart: unless-stopped
+    environment:
+      DATABASE_URL: ${DATABASE_URL:?DATABASE_URL is required}
+      INDEXER_HEALTH_ADDR: ${INDEXER_HEALTH_ADDR:-:9090}
+      LOG_LEVEL: ${LOG_LEVEL:-info}
+      LOG_FORMAT: ${LOG_FORMAT:-json}
+      TAP_URL: ${TAP_URL:-ws://tap:2480/channel}
+      TAP_AUTH_PASSWORD: ${TAP_AUTH_PASSWORD:?TAP_AUTH_PASSWORD is required}
+      INDEXED_COLLECTIONS: ${INDEXED_COLLECTIONS:?INDEXED_COLLECTIONS is required}
+      ENABLE_INGEST_ENRICHMENT: ${ENABLE_INGEST_ENRICHMENT:-true}
+    expose:
+      - "9090"
+
+  tap:
+    image: ghcr.io/bluesky-social/indigo/tap:sha-4f47add43060c27e8a37d9d76482ecddf001fcd8
+    restart: unless-stopped
+    environment:
+      TAP_BIND: :2480
+      TAP_DATABASE_URL: ${TAP_DATABASE_URL:-sqlite:///data/tap.db}
+      TAP_ADMIN_PASSWORD: ${TAP_AUTH_PASSWORD:?TAP_AUTH_PASSWORD is required}
+      TAP_LOG_LEVEL: ${TAP_LOG_LEVEL:-info}
+      TAP_COLLECTION_FILTERS: ${TAP_COLLECTION_FILTERS:-}
+    volumes:
+      - tap-data:/data
+    expose:
+      - "2480"
+
+volumes:
+  tap-data:

docs/README.md

···
 
 ## Reference
 
-Completed work — architecture, APIs, and data models as built.
-
-- [`reference/api.md`](reference/api.md) — Go search API service
+- [`reference/api.md`](reference/api.md) — API runtime, config, and data model
+- [`reference/deployment-walkthrough.md`](reference/deployment-walkthrough.md) — Coolify + Postgres deploy guide
+- [`reference/metrics.md`](reference/metrics.md) — rollout checks for API, indexer, and Postgres
+- [`reference/resync.md`](reference/resync.md) — backfill and rebuild recovery playbook
 - [`reference/app.md`](reference/app.md) — Ionic Vue mobile app
-- [`reference/deployment-walkthrough.md`](reference/deployment-walkthrough.md) — Railway deployment guide
 - [`reference/lexicons.md`](reference/lexicons.md) — Tangled AT Protocol record types
-- [`reference/metrics.md`](reference/metrics.md) — Railway and Turso usage checks after deploy
-- [`reference/resync.md`](reference/resync.md) — Backfill and repo-resync recovery playbook
 
 ## Specs
 
-Forward-looking designs for remaining work.
-
-- [`specs/data-sources.md`](specs/data-sources.md) — Constellation, Tangled XRPC, Tap, AT Protocol, Bluesky OAuth
-- [`specs/search.md`](specs/search.md) — Search stabilization, indexing, activity cache, and later ranking work
-- [`specs/app-features.md`](specs/app-features.md) — Remaining mobile app features
+- [`specs/data-sources.md`](specs/data-sources.md) — upstream systems and API sources
+- [`specs/search.md`](specs/search.md) — current search/indexing direction
+- [`specs/app-features.md`](specs/app-features.md) — remaining mobile app features
 
-## ADR Research
+## ADRs
 
-Focused option analysis for pending architectural decisions.
-
-- [`adr/pg.md`](adr/pg.md) — PostgreSQL as a production backend option for Twister search
-- [`adr/turso.md`](adr/turso.md) — Turso/libSQL as a production backend option for Twister search
-- [`adr/storage.md`](adr/storage.md) — Accepted production storage decision for Twister search
+- [`adr/storage.md`](adr/storage.md) — accepted Postgres + Coolify storage decision
+- [`adr/pg.md`](adr/pg.md) — PostgreSQL research and tradeoffs
+- [`adr/turso.md`](adr/turso.md) — superseded Turso research kept for history
 
 ## Roadmap
 
-- [`roadmap.md`](roadmap.md) — All remaining milestones and tasks
+- [`roadmap.md`](roadmap.md) — current milestone list

docs/adr/storage.md

···
 ---
-title: ADR - Choose Turso For Production Search Storage
-updated: 2026-03-25
+title: ADR - Choose PostgreSQL And Coolify For Search Storage
+updated: 2026-03-26
 status: accepted
 ---
 
 ## Decision
 
-Twister will use Turso as the production database backend for search and indexing.
-
-This decision is based on current project constraints, not on a claim that Turso is universally superior to PostgreSQL. The goal is to ship a production-capable search service with the lowest migration cost from the current codebase while keeping room to revisit the decision later if the workload changes materially.
-
-## Context
-
-Twister's current search hardening work has two separate concerns:
-
-1. make local experimentation cheaper and less messy
-2. choose a production backend deliberately instead of letting the experimentation setup turn into production by accident
-
-The codebase already relies on SQLite/libSQL-style behavior:
-
-- SQLite FTS5 search
-- SQLite-oriented migrations
-- `database/sql` access via `github.com/tursodatabase/libsql-client-go`
-- local experimentation through `file:` databases
-
-The production candidates researched were:
-
-- PostgreSQL
-- Turso remote/libSQL
-- Turso embedded-replica style deployment
-
-The supporting research is recorded in:
-
-- [PostgreSQL research](pg.md)
-- [Turso research](turso.md)
-
-## Why Turso
-
-### 1. Lowest Migration Cost
-
-Turso preserves the current SQLite/libSQL query model and avoids a full rewrite of:
-
-- search queries
-- migration files
-- ranking behavior
-- snippet generation behavior
-- search regression expectations
-
-PostgreSQL remains a credible long-term option, but adopting it now would force a larger rewrite at exactly the point where search hardening should focus on ingestion correctness, smoke tests, read-through indexing, and the activity cache.
-
-### 2. Best Match For Current Priorities
-
-The immediate work is not to invent a new search architecture. It is to stabilize:
-
-- Tap ingestion
-- read-through indexing
-- JetStream activity caching
-- local experimentation workflows
-- end-to-end smoke testing
-
-Turso lets the project do that without changing database families midstream.
-
-### 3. Clear Path From Experimentation To Production
-
-The local `file:` workflow remains the right choice for development and experimentation. For production, the chosen backend family is still Turso, which gives the project a cleaner transition than moving from local SQLite semantics to PostgreSQL semantics all at once.
-
-### 4. Embedded Replicas Stay Optional
-
-This ADR does not require Turso embedded replicas immediately.
-
-The production choice is Turso as the backend family. The initial production shape can be plain remote libSQL if that is the least risky deployment path. Embedded replicas remain a future optimization if the Go driver and build constraints become acceptable.
-
-## Why Not PostgreSQL Right Now
-
-PostgreSQL was the strongest long-term alternative, but it loses on near-term fit.
-
-Reasons not to choose it now:
+Twisted will use PostgreSQL as the primary database backend for search,
+indexing, queue state, and activity cache. The production deploy target is a
+Coolify application for `api`, `indexer`, and `tap` plus a separate
+Coolify-managed PostgreSQL instance.
 
-- it requires rewriting the current FTS5-based search implementation
-- it changes search behavior during a hardening phase where behavior stability matters
-- it increases migration scope before the ingestion model itself is stabilized
-- it solves an architectural future that the project has not yet fully reached
+## Why
 
-If Twister later becomes a larger multi-process, write-heavy service with operational requirements that outgrow Turso, PostgreSQL can be reconsidered with better evidence.
+- PostgreSQL is the better fit for long-running multi-service deployment.
+- Coolify gives the project a straightforward Git-to-deploy path with built-in
+  Traefik and a managed database resource.
+- The current service shape already wants two long-lived processes writing to
+  one shared database.
+- A local PostgreSQL workflow keeps development closer to production than the
+  old Turso split.
 
 ## Consequences
 
 ### Positive
 
-- minimum code churn from the current search implementation
-- fastest path to production-capable search hardening
-- preserves current SQLite FTS behavior as the baseline
-- keeps experimentation and production closer together conceptually
+- one mainstream database for local and remote environments
+- simpler production backups and restore story
+- easier operational model for `api` and `indexer`
+- no dependency on Turso-specific SQLite extension behavior
 
 ### Negative
 
-- production remains in the SQLite/libSQL family, which may be less conventional than PostgreSQL for some operational teams
-- embedded replicas are not a drop-in next step in the current Go setup
-- a later move to PostgreSQL would still be a meaningful migration if Twister grows past Turso's sweet spot
-
-## Production Shape
-
-The production recommendation is:
-
-1. keep local `file:` databases for experimentation and development
-2. use Turso remote/libSQL as the default production target
-3. evaluate embedded replicas only after the main search-hardening work is stable
-
-This avoids coupling the production decision to a premature embedded-replica rollout.
-
-## Follow-Up Work
-
-- define the migration path from the experimental local DB to the production Turso database
-- document backup and restore procedures for both local experimentation and production
-- keep PostgreSQL as a revisit option if production requirements change
-- explicitly evaluate embedded replicas later against Go driver and build constraints
-
-## Experimental Local DB Procedures
-
-The experimental local DB is a workflow aid, not a production artifact.
-
-Operational rules:
-
-1. Keep the database file out of git and treat it as disposable.
-2. Use stop-and-copy backups for anything worth preserving.
-3. Prefer restore-or-rebuild over repair if the DB becomes suspect.
-4. Allow the file to grow during active experiments, then compact or delete it afterward.
-
-The concrete local backup, restore, and disk-growth procedures live in
-[docs/reference/api.md](/Users/owais/Projects/Twisted/docs/reference/api.md).
-
-## Migration Path To Production Turso
-
-The migration path is intentionally code-first, not file-first.
-
-Do not promote `twister-dev.db` directly into production. The experimental DB proves schema, queries, and workflow assumptions, but the production dataset should be rebuilt from authoritative upstream sources.
-
-### Phase 1: Stabilize Local Behavior
-
-- finalize schema changes in embedded migrations
-- validate search behavior locally
-- validate smoke tests against the local workflow
-
-Exit condition:
-
-- a fresh local database can be created from migrations and pass the smoke-test baseline
-
-### Phase 2: Prepare Turso Production Target
-
-- provision the production Turso database
-- enable the required SQLite/libSQL features used by Twister
-- configure production credentials and environment variables
-- verify migrations apply cleanly to an empty production-shaped database
-
-Exit condition:
-
-- Twister can start against an empty Turso database and complete migrations successfully
-
-### Phase 3: Rebuild The Dataset From Sources Of Truth
-
-- start the indexer against Turso
-- use Tap backfill and repo-resync paths to rebuild the searchable corpus
-- let read-through indexing fill misses during verification
-- build the JetStream activity cache from a recent timestamp cursor rather than from copied local state
-
-Exit condition:
+- the search layer must move off SQLite FTS5
+- ranking and snippet behavior will change
+- SQLite remains only as a temporary rollback path during migration
 
-- the production Turso dataset is populated from Tap, repo recovery paths, and API-triggered indexing rather than from a copied experimental DB file
+## Search Shape
 
-### Phase 4: Verify And Cut Over
+Keyword search will use PostgreSQL full-text search:
 
-- run the API smoke scripts against the Turso-backed environment
-- confirm health, search, document fetches, indexing, and activity cache behavior
-- switch app traffic only after the smoke-test baseline passes
+- weighted `tsvector`
+- `websearch_to_tsquery('simple', ...)`
+- `ts_rank_cd`
+- `ts_headline`
 
-Exit condition:
+The HTTP response shape stays stable, but exact scores and snippets are not
+expected to match the previous FTS5 implementation.
 
-- production traffic points at the Turso-backed deployment and the local experimental DB is no longer part of the serving path
+## Migration Plan
 
-## Explicit Non-Goal For Migration
+1. add PostgreSQL connection/config support and local defaults
+2. add a primary PostgreSQL migration set
+3. move search and store implementations to PostgreSQL
+4. deploy `api`, `indexer`, and `tap` from `docker-compose.prod.yaml`
+5. rebuild data through `backfill`, `enrich`, and `reindex`
+6. cut traffic over only after smoke checks pass
 
-The migration plan does not include a direct file copy from local SQLite to production Turso as the default rollout path. If a one-off import becomes necessary later, it should be treated as a separate migration task with its own validation steps.
+## Explicit Non-Goal
 
-## Revisit Conditions
+The default migration does not include a Turso-to-PostgreSQL data import. The
+serving dataset should be rebuilt from authoritative upstream sources.
 
-Re-open this ADR if any of the following become true:
+## Related Records
 
-- Twister needs multiple high-write production workers across separate hosts
-- operational requirements start favoring standard PostgreSQL tooling over libSQL continuity
-- embedded replicas prove impractical in the Go runtime the project wants to keep
-- semantic and hybrid search work introduces storage requirements that fit PostgreSQL materially better
+- `docs/adr/pg.md` remains the background research for this decision
+- `docs/adr/turso.md` is retained as superseded historical context

docs/adr/turso.md

···
 ---
 title: ADR Research - Turso For Production Search
-updated: 2026-03-25
-status: research
+updated: 2026-03-26
+status: superseded
 ---
 
-## Summary
+## Status
 
-Turso is the lowest-migration production candidate because Twister already uses libSQL/SQLite-style storage and query patterns. It preserves the current mental model and minimizes rewrite cost.
+This research record is kept for history. It no longer describes the active
+deployment direction.
 
-The open question is not whether Turso can work, but which Turso mode fits production:
-
-- remote libSQL primary
-- local experimentation via plain `file:` SQLite
-- Turso embedded-replica style local-read, remote-sync patterns
-
-## Why Consider It
-
-Twister already depends on:
-
-- `github.com/tursodatabase/libsql-client-go`
-- SQLite-style migrations
-- SQLite FTS5 behavior
-
-That makes Turso the shortest path from current code to a production-capable deployment.
-
-## Fit For Twister
-
-### Strengths
-
-#### Lowest Rewrite Cost
-
-Staying with Turso/libSQL keeps Twister in the same family of database semantics it already uses. Compared with PostgreSQL, this means less work in:
+## Historical Summary
 
-- search query rewrites
-- migration rewrites
-- ranking behavior drift
-- compatibility testing
+Turso was originally attractive because Twisted already used SQLite-style
+queries, migrations, and FTS5 search behavior. It offered the shortest path
+from local file-backed development to a remotely hosted production database.
 
-#### Good Match For Local Experimentation
+## Why It Was Superseded
 
-The current hardening plan already relies on local `file:` workflows to reduce the messiness and cost of experimentation. Turso and libSQL naturally support this style of development.
+The project has now chosen PostgreSQL plus Coolify instead.
 
-#### Embedded-Replica Model Is Relevant
+Main reasons:
 
-Turso's embedded replica story is directly relevant to Twister's workload because it allows:
+- Twisted now runs as multiple long-lived services against one shared database
+- the project wants standard production operations and restore tooling
+- local and production environments should converge on one database family
+- the cost of carrying Turso-specific behavior forward outweighed the migration
 
-- local reads from a file-backed database
-- sync to a remote primary
-- read-your-writes behavior for the initiating replica
-- periodic background sync
+## What Still Matters From This Research
 
-On paper, this is a strong match for a search service that wants cheap local reads while keeping a remote production database.
+- rebuilding the dataset from upstream sources remains the safer default than
+  promoting an experimental local database
+- embedded-replica ideas were interesting but were not a fit for the Go stack
+  the project kept
+- search behavior changes must be treated as product-visible, not just as a
+  storage swap
 
-## Costs And Risks
+## Current Source Of Truth
 
-### Remote Turso Alone Does Not Solve The Current Pain
-
-The current problem statement came from burning reads and writes during experimentation. A plain remote Turso deployment keeps the same basic cost surface, even if production operations are cleaner than ad hoc local experiments.
-
-### Embedded Replicas Have Important Caveats
-
-Turso's embedded replicas are promising, but the docs call out constraints that matter for Twister:
-
-- they require a real filesystem
-- they are not suitable for serverless environments without disk
-- local DB files should not be opened while syncing
-- sync behavior can amplify writes because replication is frame-based
-
-This means the operational model has to be chosen carefully. It is not a free "best of both worlds" switch.
-
-### Current Go Stack Makes The Best Turso Story Harder
-
-This is the biggest repo-specific caveat.
-
-The Turso Go quickstart notes that `github.com/tursodatabase/libsql-client-go/libsql` does not support embedded replicas. Twister currently uses that library for remote libSQL access, while local file mode is handled separately with `modernc.org/sqlite`.
-
-Twister also currently builds with `CGO_ENABLED=0` in `packages/api/justfile`.
-
-That means the cleanest embedded-replica path may require:
-
-- changing drivers
-- reconsidering the pure-Go build constraint
-- accepting CGO in production builds, or waiting for a better pure-Go story
-
-So while Turso embedded replicas are attractive in principle, they are not a drop-in upgrade for the current codebase.
-
-## Repo-Specific Implications
-
-- Remote Turso/libSQL is the easiest production continuation of the current code.
-- Local `file:` mode is already useful for stabilizing experimentation.
-- Embedded replicas are strategically interesting but would likely force deeper driver and build changes than the current roadmap implies.
-
-## When Turso Is The Better Choice
-
-Choose Turso if most of the following are true:
-
-- minimizing migration cost is the top priority
-- preserving current SQLite FTS behavior matters
-- production can tolerate a simpler deployment model, especially early on
-- We want to keep search and experimentation close to the current implementation
-
-## When Turso Needs Extra Caution
-
-Be careful with Turso if most of the following are true:
-
-- Twister needs multiple production writers across separate hosts
-- the system must avoid CGO and keep pure-Go builds
-- We expect embedded replicas to be a near-term production feature
-- operational simplicity matters more than minimizing query rewrites
-
-## Recommendation
-
-Turso is the best near-term production candidate if the goal is minimum code churn and continuity with the current search stack.
-
-Remote Turso is the easiest short path. Embedded replicas are the most interesting medium-term Turso option, but they should be treated as additional engineering work rather than an assumption, especially given the current Go driver and build setup.
-
-## Sources
-
-- [Turso Go quickstart](https://docs.turso.tech/sdk/go/quickstart#local-only)
-- [Turso embedded replicas docs](https://docs.turso.tech/features/embedded-replicas)
+See `docs/adr/storage.md` for the accepted storage decision.

docs/reference/api.md

···
 ---
 title: API Service Reference
-updated: 2026-03-24
+updated: 2026-03-26
 ---
 
-Twister is a Go service that indexes Tangled content and serves a search API. It connects to the AT Protocol ecosystem via Tap (firehose consumer), XRPC (direct record lookups), and Constellation (backlink queries), storing indexed data in Turso/libSQL with FTS5 full-text search.
+Twisted is a Go service that indexes Tangled content, serves search, and caches
+recent activity. It uses PostgreSQL for the primary runtime and retains a
+temporary local SQLite fallback behind `--local`.
 
-## Architecture
+## Runtime Modes
 
-The service is a single Go binary with multiple subcommands, each running a different runtime mode. All modes share the same database and configuration layer.
-
-**Runtime modes:**
-
-| Command       | Purpose                                                             |
-| ------------- | ------------------------------------------------------------------- |
-| `api` (serve) | HTTP search API server                                              |
-| `indexer`     | Consumes Tap firehose events, normalizes and indexes records        |
-| `backfill`    | Discovers users from seed files, registers them with Tap            |
-| `enrich`      | Backfills missing metadata (repo names, handles, web URLs) via XRPC |
-| `reindex`     | Re-syncs all documents into the FTS index                           |
-| `healthcheck` | One-shot liveness probe for container orchestration                 |
-
-The `embed-worker` and `reembed` commands exist as stubs for the upcoming semantic search pipeline (Nomic Embed Text v1.5 deployed via Railway template).
-
-All commands accept a `--local` flag that switches to a local SQLite file and text-format logging for development.
+| Command | Purpose |
+| --- | --- |
+| `api` | HTTP API server |
+| `indexer` | Tap consumer and index writer |
+| `backfill` | register repos with Tap |
+| `enrich` | fill missing repo names, handles, and web URLs |
+| `reindex` | re-upsert documents and finalize the search index |
+| `healthcheck` | one-shot config and process probe |
 
 ## HTTP API
 
-The API server binds to `:8080` by default (configurable via `HTTP_BIND_ADDR`). CORS is open (`*` origin, GET/OPTIONS).
+- `GET /healthz` — liveness probe
+- `GET /readyz` — readiness probe, checks database reachability
+- `GET /search` — keyword search
+- `GET /documents/{id}` — fetch one indexed document
+- `GET /admin/status` — cursor and queue state when admin routes are enabled
 
-### Search
+The API also serves the built-in search/docs site from `/` and `/docs*`.
 
-**`GET /search`** — Main search endpoint. Routes to keyword, semantic, or hybrid based on `mode` parameter.
+## Search
 
-**`GET /search/keyword`** — Full-text search via FTS5 with BM25 scoring.
+Keyword search is implemented with PostgreSQL full-text search.
 
-Parameters:
+- weighted fields: title, author handle, repo name, summary, body, tags
+- query parser: `websearch_to_tsquery('simple', ...)`
+- ranking: `ts_rank_cd`
+- snippets: `ts_headline`
 
-- `q` (required) — Query string
-- `limit` (1–100, default 20) — Results per page
-- `offset` (default 0) — Pagination offset
-- `collection` — Filter by AT Protocol collection NSID
-- `type` — Filter by record type (repo, issue, pull, profile, string)
-- `author` — Filter by handle or DID
-- `repo` — Filter by repo name or DID
-- `language` — Filter by primary language
-- `from`, `to` — Date range (ISO 8601)
-- `state` — Filter issues/PRs by state (open, closed, merged)
-- `mode` — Search mode (keyword, semantic, hybrid)
+Response shape stays the same as the previous FTS5 API. Ranking and snippet
+details are allowed to differ from the SQLite-era implementation.
 
-Response includes query metadata, total count, and an array of results each containing: ID, collection, record type, title, summary, body snippet (with `<mark>` highlights), score, repo name, author handle, DID, AT-URI, web URL, and timestamps.
+## Database
 
-**`GET /documents/{id}`** — Fetch a single document by stable ID.
+Primary backend: PostgreSQL.
 
-### Health
-
-- **`GET /healthz`** — Liveness probe, always 200
-- **`GET /readyz`** — Readiness probe, pings database
+Main tables:
 
-### Admin
+- `documents`
+- `sync_state`
+- `identity_handles`
+- `record_state`
+- `indexing_jobs`
+- `indexing_audit`
+- `jetstream_events`
 
-When `ENABLE_ADMIN_ENDPOINTS=true` with a configured `ADMIN_AUTH_TOKEN`:
+`documents` stores a generated weighted `tsvector` column plus a GIN index for
+keyword search.
 
-- **`GET /admin/status`** — Tap cursor, JetStream cursor, document count, and
-  read-through queue status
-- **`GET /admin/indexing/jobs`** — List queue rows, filtered by `status`,
-  `source`, or `document`
-- **`GET /admin/indexing/audit`** — List append-only audit rows, filtered by
-  `source`, `decision`, or `document`
-- **`POST /admin/indexing/enqueue`** — Queue a single record by explicit body
-- **`POST /admin/reindex`** — Trigger FTS re-sync
+## Configuration
 
-### Smoke Checks
+Primary env vars:
 
-Smoke checks for the API surface live in `packages/scripts/api/`.
+- `DATABASE_URL`
+- `HTTP_BIND_ADDR`
+- `INDEXER_HEALTH_ADDR`
+- `TAP_URL`
+- `TAP_AUTH_PASSWORD`
+- `INDEXED_COLLECTIONS`
+- `READ_THROUGH_MODE`
+- `READ_THROUGH_COLLECTIONS`
+- `READ_THROUGH_MAX_ATTEMPTS`
+- `ENABLE_ADMIN_ENDPOINTS`
+- `ADMIN_AUTH_TOKEN`
 
-From the repo root:
+Default local database URL:
 
 ```sh
-uv run --project packages/scripts/api twister-api-smoke
+postgresql://localhost/${USER}_dev?sslmode=disable
 ```
 
-If `ADMIN_AUTH_TOKEN` is present in the environment, the smoke script can also
-verify `GET /admin/status`.
-
-### Static Content
+`--local` is deprecated and switches to the legacy SQLite fallback at
+`packages/api/twister-dev.db`.
 
-The API also serves a search site with live search and API documentation at `/` and `/docs*`, built with Alpine.js (no build step, embedded in `internal/view/`).
+## Local Operation
 
-## Database
+Start local Postgres with the repo compose file:
 
-Turso (libSQL) with the following tables:
+```sh
+just db-up
+just api-dev
+just api-run-indexer
+```
 
-**documents** — Core search index. Each record gets a stable ID of `did|collection|rkey`. Stores title, body, summary, metadata (repo name, author handle, web URL, language, tags), and timestamps. Soft-deleted via `deleted_at`.
+That dev compose file also runs Tap locally at `ws://localhost:2480/channel`.
 
-**documents_fts** — FTS5 virtual table for full-text search over title, body, summary, repo name, author handle, and tags. Uses `unicode61` tokenizer with tuned BM25 weights (title weighted highest at 2.5, then author handle at 2.0, summary at 1.5).
-
-**sync_state** — Cursor tracking for the Tap consumer. Stores consumer name, current cursor, high water mark, and last update time. Enables crash-safe resume.
-
-**identity_handles** — DID-to-handle cache. Updated from Tap identity events and XRPC lookups.
-
-**record_state** — Issue and PR state cache (open/closed/merged). Keyed by subject AT-URI.
-
-**indexing_jobs** — Durable read-through/admin queue with status, lease owner,
-lease expiry, retry counters, and terminal states (`failed`, `dead_letter`).
-
-**indexing_audit** — Append-only record of enqueue decisions, retries, skips,
-completions, and dead letters.
-
-**document_embeddings** — Vector storage (768-dim F32_BLOB with DiskANN cosine index). Schema ready but not yet populated.
-
-**embedding_jobs** — Async embedding job queue. Schema ready but worker not yet active.
-
-## Indexing Pipeline
-
-The indexer connects to Tap via WebSocket, consuming AT Protocol record events in real-time. For each event:
-
-1. Filter against the configured collection allowlist (supports wildcards like `sh.tangled.*`)
-2. Route to the appropriate normalizer based on collection
-3. Normalize into a document (extract title, body, summary, metadata)
-4. Optionally enrich via XRPC (resolve author handle, repo name, web URL)
-5. Upsert into the database (auto-syncs FTS)
-6. Persist the Tap cursor and then acknowledge the event
-
-The indexer resumes from its last cursor on restart and replays idempotently.
-It logs status every 30 seconds and uses exponential backoff (1s–5s) for
-transient failures.
-
-Read-through indexing is `missing` by default. Only allowed collections can be
-queued, detail reads queue single focal records, and bulk list handlers no
-longer enqueue whole collections.
-
-## Record Normalizers
-
-Each AT Protocol collection has a dedicated normalizer that extracts searchable content:
-
-| Collection                      | Record Type   | Searchable               | Content                     |
-| ------------------------------- | ------------- | ------------------------ | --------------------------- |
-| `sh.tangled.repo`               | repo          | Yes (if named)           | Name, description, topics   |
-| `sh.tangled.repo.issue`         | issue         | Yes                      | Title, body, repo reference |
-| `sh.tangled.repo.pull`          | pull          | Yes                      | Title, body, target branch  |
-| `sh.tangled.repo.issue.comment` | issue_comment | Yes (if has body)        | Comment body                |
-| `sh.tangled.repo.pull.comment`  | pull_comment  | Yes (if has body)        | Comment body                |
-| `sh.tangled.string`             | string        | Yes (if has content)     | Filename, contents          |
-| `sh.tangled.actor.profile`      | profile       | Yes (if has description) | Profile description         |
-| `sh.tangled.graph.follow`       | follow        | No                       | Graph edge only             |
-
-State records (`sh.tangled.repo.issue.state`, `sh.tangled.repo.pull.status`) update the `record_state` table rather than creating documents.
-
-## XRPC Client
-
-The built-in XRPC client provides typed access to AT Protocol endpoints with caching (1-hour TTL for DID docs and repo names):
-
-- DID resolution via PLC Directory (`did:plc:`) or `.well-known/did.json` (`did:web:`)
-- Identity resolution (PDS endpoint + handle from DID document)
-- Record fetching (`com.atproto.repo.getRecord`, `com.atproto.repo.listRecords`)
-- Repo name resolution from `sh.tangled.repo` records
-- Web URL construction for Tangled entities
-
-## Backfill
-
-The backfill command now defaults to `--source lightrail`: it calls
-`com.atproto.sync.listReposByCollection`, dedupes returned DIDs, and batch
-submits them to Tap. `--source graph` keeps the older seed-file follow and
-collaborator crawl for targeted fallback runs.
-
-## Configuration
-
-All configuration is via environment variables (with `.env` file support):
-
-| Variable                   | Default                 | Purpose                                         |
-| -------------------------- | ----------------------- | ----------------------------------------------- |
-| `TURSO_DATABASE_URL`       | —                       | Database connection (required unless `--local`) |
-| `TURSO_AUTH_TOKEN`         | —                       | Auth token (required for remote)                |
-| `TAP_URL`                  | —                       | Tap WebSocket URL                               |
-| `TAP_AUTH_PASSWORD`        | —                       | Tap admin password                              |
-| `INDEXED_COLLECTIONS`      | all                     | Collection allowlist (CSV, supports wildcards)  |
-| `READ_THROUGH_MODE`        | missing                 | `off`, `missing`, or `broad`                    |
-| `READ_THROUGH_COLLECTIONS` | `INDEXED_COLLECTIONS`   | Read-through allowlist                          |
-| `READ_THROUGH_MAX_ATTEMPTS`| 5                       | Retries before `dead_letter`                    |
-| `HTTP_BIND_ADDR`           | `:8080`                 | API server bind address                         |
-| `INDEXER_HEALTH_ADDR`      | `:9090`                 | Indexer health probe address                    |
-| `LOG_LEVEL`                | info                    | debug/info/warn/error                           |
-| `LOG_FORMAT`               | json                    | json or text                                    |
-| `ENABLE_ADMIN_ENDPOINTS`   | false                   | Enable admin routes                             |
-| `ADMIN_AUTH_TOKEN`         | —                       | Bearer token for admin                          |
-| `ENABLE_INGEST_ENRICHMENT` | true                    | XRPC enrichment at ingest time                  |
-| `PLC_DIRECTORY_URL`        | `https://plc.directory` | PLC Directory                                   |
-| `XRPC_TIMEOUT`             | 15s                     | XRPC HTTP timeout                               |
-
-Recommended production practice is to use explicit search-relevant collection
-lists for `INDEXED_COLLECTIONS` and `READ_THROUGH_COLLECTIONS`, not
-`sh.tangled.*`, and to leave `sh.tangled.graph.follow` out of both.
+Use `just api-dev sqlite` only when you need the temporary SQLite rollback path.
 
 ## Deployment
 
-Deployed on Railway with three services:
-
-- **api** — HTTP server (port 8080, health at `/readyz`)
-- **indexer** — Tap consumer (health at `:9090/health`)
-- **tap** — Tap instance (external dependency)
-
-All services share the same Turso database. The API and indexer are separate deployments of the same binary with different subcommands.
-
-## Experimental Local DB
-
-The local development database lives at `packages/api/twister-dev.db` when the
-API runs with `--local`.
-
-Operational rules:
-
-1. Stop the API before backup or restore.
-2. Copy `twister-dev.db` and any matching `-wal` or `-shm` files together.
-3. Prefer restore-or-rebuild over repair if the file becomes suspect.
-4. Let the DB grow during active experiments, then compact or delete it later.
+Production uses:
 
-Useful local inspection:
+- Coolify Application with `docker-compose.prod.yaml`
+- separate Coolify-managed PostgreSQL resource
+- private Tap service from the pinned Indigo image
+- built-in Coolify Traefik for the public `api` domain
 
-```sh
-cd packages/api
-du -h twister-dev.db*
-ls -lh twister-dev.db*
-```
+See `docs/reference/deployment-walkthrough.md` for the full production flow.

docs/reference/deployment-walkthrough.md

···
 # Deployment Walkthrough
 
-This repo maps cleanly to Railway, but only for the backend pieces.
+Twisted deploys to Coolify as one Compose application with three services:
 
-- Deploy `packages/api` to Railway as two services: `api` and `indexer`.
-- Keep the Ionic + Capacitor app on your machine or in CI for native builds.
-- Point the mobile app at the Railway `api` service with
-  `VITE_TWISTER_API_BASE_URL`.
+- `api`: public HTTP service
+- `indexer`: private Tap consumer
+- `tap`: private Indigo Tap service
 
-## What Railway Should Host
+PostgreSQL is a separate Coolify-managed resource.
 
-Railway is a good home for the Go services in this repo:
+## Files
 
-- `api`: serves HTTP routes, docs, search, proxies, and readiness checks
-- `indexer`: consumes Tap, writes into Turso, and exposes its own health endpoint
-Railway is not the place that ships the native iOS or Android app. You still
-build, sign, and distribute the Capacitor shells separately.
+- production compose: `docker-compose.prod.yaml`
+- local dev compose: `docker-compose.dev.yaml`
+- app image build: `packages/api/Dockerfile`
+- Tap image: `ghcr.io/bluesky-social/indigo/tap:sha-4f47add43060c27e8a37d9d76482ecddf001fcd8`
 
 ## Prerequisites
 
-Before you start, have these ready:
+- Coolify access
+- one Coolify PostgreSQL resource
+- this repo connected to Coolify
+- explicit `INDEXED_COLLECTIONS` and `READ_THROUGH_COLLECTIONS`
+- one shared Tap admin password
 
-- a Railway account and the Railway CLI
-- a Turso database URL and auth token
-- a Tap URL and Tap auth password
-From this machine:
+## Provision PostgreSQL
 
-```sh
-cd /Users/owais/Projects/Twisted
-railway login
-```
+Create the PostgreSQL resource first.
 
-## Create The Railway Project
-
-In the Railway dashboard, create one empty project with two empty services:
-
-- `api`
-- `indexer`
-Then link this repo to that project:
+- keep the generated connection string in Coolify secrets as `DATABASE_URL`
+- use PostgreSQL backups from the database resource
+- point both `api` and `indexer` at the same database
 
-```sh
-cd /Users/owais/Projects/Twisted
-railway link
-```
+## Create The Coolify App
 
-## Configure Service Shape
+In Coolify:
 
-Both services should deploy from the same local path:
+1. create a new Application
+2. choose the Docker Compose build pack
+3. point it at this repo
+4. set base directory to `/`
+5. set compose file location to `/docker-compose.prod.yaml`
 
-- path: `packages/api`
-- build source: `packages/api/Dockerfile`
-Set the service start commands in Railway:
-- `api`: `twister api`
-- `indexer`: `twister indexer`
-The checked-in Dockerfile already builds the `twister` binary.
+Do not add your own Traefik container. Coolify already provides the proxy.
 
-## Set Variables
+## Set Environment Variables
 
-Use shared variables for values both services need:
+Shared:
 
-- `TURSO_DATABASE_URL`
-- `TURSO_AUTH_TOKEN`
+- `DATABASE_URL`
+- `INDEXED_COLLECTIONS`
 - `LOG_LEVEL=info`
 - `LOG_FORMAT=json`
-Set these on `api`:
-- `HTTP_BIND_ADDR=0.0.0.0:${{ PORT }}`
+- `TAP_AUTH_PASSWORD=<required>`
+
+`api`:
+
+- `HTTP_BIND_ADDR=:8080`
 - `SEARCH_DEFAULT_LIMIT=20`
 - `SEARCH_MAX_LIMIT=100`
 - `READ_THROUGH_MODE=missing`
-- `READ_THROUGH_COLLECTIONS=<explicit search collection CSV>`
+- `READ_THROUGH_COLLECTIONS=<explicit CSV>`
 - `READ_THROUGH_MAX_ATTEMPTS=5`
 - `ENABLE_ADMIN_ENDPOINTS=false`
-- `ADMIN_AUTH_TOKEN=<set this if admin routes are enabled>`
-Set these on `indexer`:
-- `INDEXER_HEALTH_ADDR=0.0.0.0:${{ PORT }}`
-- `TAP_URL=<your Tap URL>`
-- `TAP_AUTH_PASSWORD=<your Tap password>`
-- `INDEXED_COLLECTIONS=<matching explicit search collection CSV>`
-- `ENABLE_INGEST_ENRICHMENT=true`
-Do not use `sh.tangled.*` for those allowlists. Match the Lightrail-backed
-search collection set and leave `sh.tangled.graph.follow` out.
-Optional OAuth variables for a Railway-hosted web client metadata endpoint:
-- `OAUTH_CLIENT_ID`
-- `OAUTH_REDIRECT_URIS`
-The `${{ PORT }}` reference matters. Railway health checks run against the
-service port it injects, so the process must listen on that port.
+- `ADMIN_AUTH_TOKEN=<optional>`
+- `OAUTH_CLIENT_ID=<optional>`
+- `OAUTH_REDIRECT_URIS=<optional CSV>`
 
-## Deploy From This Machine
+`indexer`:
 
-From the repo root, deploy `packages/api` into each Railway service:
+- `INDEXER_HEALTH_ADDR=:9090`
+- `TAP_URL=ws://tap:2480/channel`
+- `ENABLE_INGEST_ENRICHMENT=true`
 
-```sh
-cd /Users/owais/Projects/Twisted
-railway up packages/api --path-as-root --service api
-railway up packages/api --path-as-root --service indexer
-```
+`tap`:
 
-`--path-as-root` is important in this monorepo. It makes `packages/api` the
-deployment root instead of archiving the whole repo.
+- `TAP_COLLECTION_FILTERS=<optional explicit CSV>`
+- optional persistent volume override if you do not want the default `/data`
 
-## Configure Health Checks
+Use explicit search collections. Do not use `sh.tangled.*` in production.
 
-Set the health check path in Railway for each service:
+## Domains And Health Checks
 
-- `api`: `/readyz`
-- `indexer`: `/health`
-`/readyz` is the better API check because it verifies database reachability.
+Expose only `api` publicly.
 
-## First Bootstrap
+- assign the domain in Coolify to the `api` service
+- if `api` stays on `:8080`, include that internal port in the Coolify mapping
+- configure readiness checks against `GET /readyz`
+- keep `indexer` and `tap` private
+- monitor `indexer` with `GET /health`
 
-A fresh environment is not search-ready just because the services booted.
+## First Bootstrap
 
-1. Deploy `api`.
-2. Deploy `indexer`.
-3. Confirm the `api` domain returns `200` from `/readyz`.
-4. Confirm the `indexer` returns `200` from `/health`.
-5. Run the initial backfill against the same Turso and Tap environment.
-Use Railway shell so the command runs inside the live `indexer` environment:
+1. deploy `tap`
+2. deploy `api`
+3. deploy `indexer`
+4. confirm `api` returns `200` from `/readyz`
+5. confirm `indexer` returns `200` from `/health`
+6. confirm `indexer` can reach `ws://tap:2480/channel`
+7. open a Coolify terminal in the `indexer` service and run:
 
 ```sh
-cd /Users/owais/Projects/Twisted
-railway link # Select indexer service if prompted
-railway shell
-twister backfill --source lightrail
+twister backfill
+twister enrich
+twister reindex
 ```
 
-Do not call the environment ready until that first backfill has completed.
+This rebuilds the serving dataset from authoritative sources. Do not import the
+old Turso data as the default migration path.
 
-## Point The App At Railway
+## Point The App At Coolify
 
-For local app builds, set the Railway API URL in `apps/twisted/.env`:
+For local app builds:
 
 ```sh
 VITE_TWISTER_API_BASE_URL=https://<your-api-domain>
 ```
 
-Then build or run the app as usual:
+Then run the app normally with `pnpm --dir apps/twisted dev` or `build`.
+
+## Rollback Notes
 
-```sh
-pnpm --dir apps/twisted dev
-pnpm --dir apps/twisted build
-pnpm --dir apps/twisted exec cap sync
-```
+- keep the SQLite `--local` path only as a temporary development fallback
+- rollback production by restoring PostgreSQL and redeploying the prior app
+- treat PostgreSQL restore as the database rollback primitive

docs/reference/metrics.md

···
 # Metrics To Watch
 
-Use this after deploying the Lightrail-backed backfill flow and detail-only
-read-through changes.
+Use this after rolling out the Coolify + PostgreSQL deployment.
 
-## Goal
+## Goals
 
 Confirm that:
 
-- the API stops creating broad read-through churn during browse traffic
-- the indexer still keeps search current through Tap
-- bootstrap backfills become cheaper and more predictable
+- `api` stays stable under browse-heavy traffic
+- `indexer` keeps search current through Tap
+- PostgreSQL handles ingest, queue churn, and activity writes without backlog
 
-## Railway
+## Coolify Application
 
-Watch both `api` and `indexer` for 24 to 48 hours after deploy.
+Watch both services for 24 to 48 hours after deploy.
 
-### API service
+### API
 
 Expected direction:
 
-- lower average CPU
-- fewer latency spikes on browse-heavy endpoints
-- lower memory churn from fewer queued background jobs
+- lower latency spikes
+- stable memory
+- flat restart count
 
 Useful checks:
 
-- CPU usage before and after deploy
-- memory usage before and after deploy
-- request latency for browse-heavy periods
+- request latency
+- CPU and memory
+- `/readyz` failures
 - restart count
 
-If this change is helping, the API should look flatter under normal browsing,
-especially when clients hit repo lists, issue lists, pull lists, or follows.
-
-### Indexer service
+### Indexer
 
 Expected direction:
 
-- similar steady-state load during normal Tap ingest
-- shorter, more deliberate spikes only when `twister backfill` is run
+- steady-state load during Tap ingest
+- bounded spikes during `backfill`, `enrich`, and `reindex`
+- `/health` stays green outside deploy windows
 
 Useful checks:
 
-- CPU during normal operation
-- CPU during `twister backfill --source lightrail`
-- memory during backfill
+- CPU and memory
 - restart count
+- Tap reconnect frequency
+- queue drain time after backfill
 
-The indexer may still spike during an initial bootstrap. That is expected. The
-important change is that the API should stop causing constant incidental work.
-
-## Turso
-
-This is where the clearest savings should show up.
+## PostgreSQL
 
 Expected direction:
 
-- fewer write operations
-- fewer row updates in indexing job tables
-- lower write amplification from browse traffic
+- predictable connection count
+- stable write latency during ingest
+- no long-lived lock buildup in `indexing_jobs`
+- bounded table growth in `jetstream_events` and `indexing_audit`
 
 Useful checks:
 
-- total row writes
-- total queries
-- write-heavy windows during normal app usage
-- latency on write statements if you have it
-
-The main reduction should come from no longer enqueueing whole list responses
-into `indexing_jobs` during browse requests.
+- connections
+- disk growth
+- slow queries
+- write latency
+- backup duration and restore confidence
 
-## Twister Admin Signals
+## Admin Signals
 
-If admin endpoints are enabled, compare these before and after deploy:
+If admin routes are enabled, compare:
 
 - `read_through.pending`
 - `read_through.processing`
 - `read_through.failed`
 - `read_through.dead_letter`
-- `read_through.last_processed_at`
+- `tap.cursor`
+- `jetstream.cursor`
 
-Healthy post-change behavior:
+Healthy behavior:
 
 - pending stays near zero most of the time
-- processing only bumps when detail pages fetch missing records
-- failed and dead-letter counts grow slowly, not continuously
-
-Relevant endpoint:
-
-```sh
-curl -H "Authorization: Bearer $ADMIN_AUTH_TOKEN" http://<api-host>/admin/status
-```
-
-## What To Compare
-
-Use the same day-of-week and similar traffic windows if possible.
-
-Good comparisons:
-
-- 24 hours before deploy vs 24 hours after deploy
-- one browse-heavy period before vs after
-- one bootstrap backfill run before vs after
+- processing drains after bursts
+- failed and dead-letter stay small and explainable
 
 ## Success Signals
 
-Treat the rollout as successful if most of these are true:
-
-- API CPU is lower or less spiky under normal browsing
-- Turso writes drop during browse-heavy traffic
-- read-through queue counts stay close to zero most of the time
-- backfill runs complete with fewer upstream calls and cleaner batching
-- search freshness still tracks Tap ingest without visible regressions
+- `/readyz` and `/health` remain consistently green
+- search freshness tracks Tap ingest
+- backfill and enrich jobs complete without manual cleanup
+- PostgreSQL latency stays stable during bootstrap and normal use
 
 ## Failure Signals
 
-Investigate if you see any of these:
-
-- search misses rise after deploy
-- detail pages repeatedly enqueue the same records
-- `read_through.pending` grows and does not drain
-- indexer CPU stays elevated long after a bootstrap run
-- Turso writes do not drop despite the handler changes
-
-If that happens, inspect Tap coverage first, then spot-check whether operators
-ran `twister backfill --source lightrail` for the environment.
+- queue counts rise and do not drain
+- `/readyz` flips during normal browse traffic
+- search misses rise after cutover
+- PostgreSQL write latency climbs during normal ingest
+- restores or backups are failing or taking too long

docs/reference/resync.md

···
 updated: 2026-03-26
 ---
 
-Twister's search index has three recovery paths. Choose based on what broke.
-
-| Situation                                             | Recovery path                                |
-| ----------------------------------------------------- | -------------------------------------------- |
-| FTS index corrupted or drifted from stored documents  | `twister reindex`                            |
-| Documents missing — never received via Tap            | `twister backfill` + let the indexer consume |
-| Documents missing — received but fields empty/wrong   | `twister enrich`                             |
-| Full index loss — DB dropped or migrated              | backfill then reindex then enrich            |
-| Tap cursor too far ahead — events skipped after a gap | cursor reset via `sync_state` table          |
-
----
+Twisted has three recovery tools. Choose based on what broke.
 
-## Paths Overview
-
-**Tap** is the authoritative ingest and backfill path. Documents reach the index
-when the `indexer` consumes events from Tap. Completeness depends on which DIDs
-Tap is tracking.
-
-**Read-through indexing** now runs in `missing` mode by default: when the API
-fetches a record that is absent or stale, and the collection is allowed, it
-enqueues a background job. Bulk list reads no longer enqueue entire collections.
-
-**JetStream** feeds only the activity cache (`/activity`). It does not contribute
-to the search index.
-
----
+| Situation | Recovery path |
+| --- | --- |
+| Search results wrong but documents exist | `twister reindex` |
+| Documents missing because Tap never delivered them | `twister backfill` |
+| Documents exist but derived metadata is empty or stale | `twister enrich` |
+| Full database loss or migration to a fresh PostgreSQL instance | backfill, enrich, reindex |
 
 ## Commands
 
 ### `twister indexer`
 
-Runs the Tap consumer. Must be running continuously for real-time indexing.
-Persists cursor to `sync_state` table under consumer name `indexer-tap-v1`.
+Runs the Tap consumer continuously. Persists its cursor in `sync_state`.
 
 ### `twister backfill`
 
-Defaults to `--source lightrail`: discovers DIDs from
-`com.atproto.sync.listReposByCollection` and submits them to Tap in batches.
-Use `--source graph` only for targeted fallback seeding from handles or DIDs.
+Default source is `lightrail`. Use graph mode only for targeted fallback.
 
 ```sh
-# full-network dry-run first
 twister backfill --dry-run
-
-# full-network bootstrap
 twister backfill
-
-# targeted fallback
-twister backfill --source graph --seeds seeds.txt --max-hops 2 \
-  --concurrency 5 --batch-size 10 --batch-delay 1s
+twister backfill --source graph --seeds seeds.txt --max-hops 2
 ```
 
-Safe to re-run. Discovery deduplicates and `repos/add` is treated as idempotent.
+Safe to rerun. Discovery is deduplicated and Tap registration is treated as
+idempotent.
 
 ### `twister reindex`
 
-Re-upserts stored documents into the FTS table and runs `optimize`. Does not
-re-fetch from upstream — only re-processes what is already in the DB.
+Re-upserts stored documents so PostgreSQL recomputes search state from the
+canonical `documents` rows.
 
 ```sh
-twister reindex                            # all documents
+twister reindex
 twister reindex --collection sh.tangled.repo
 twister reindex --did did:plc:abc123
-twister reindex --dry-run                  # preview without writing
+twister reindex --dry-run
 ```
 
-Run this when: FTS results are stale after a schema migration, after a bulk
-document import, or whenever search quality seems inconsistent with stored data.
-
 ### `twister enrich`
 
-Resolves missing `author_handle`, `repo_name`, and `web_url` via XRPC for
-documents already in the DB.
+Fills missing `author_handle`, `repo_name`, and `web_url`.
 
 ```sh
-twister enrich                             # all documents
+twister enrich
 twister enrich --collection sh.tangled.repo.issue
 twister enrich --did did:plc:abc123
 twister enrich --dry-run
 ```
-
-Run this when: search results show documents with empty author handles, or
-after deploying enrichment logic changes.
-
----
 
 ## Scenario Playbooks
 
-### FTS index out of sync
+### Search drift
 
-Documents exist in the DB but search returns wrong/stale results.
+If search results look stale but the document rows are present:
 
 ```sh
-twister reindex --dry-run   # confirm scope
-twister reindex             # re-upsert + FTS optimize
+twister reindex --dry-run
+twister reindex
 ```
 
-Verify with `GET /search?q=<known-term>`.
+### Missing documents
 
-### Documents missing from search
+If a record is fetchable through the API but not searchable:
 
-Fetch a known record directly. If it returns from `/actors/{handle}/repos/{repo}`
-but does not appear in `/search`, the document was never indexed.
-
-1. Check if the DID is tracked by Tap. If not, run `backfill`:
-
-   ```sh
-   twister backfill --source graph --seeds <handle-or-did> --max-hops 0
-   ```
-
-2. Once Tap is tracking the DID, the `indexer` will deliver historical events.
-   Monitor progress via `GET /admin/status` and inspect backlog or failures with
-   `GET /admin/indexing/jobs` and `GET /admin/indexing/audit`.
+1. make sure Tap is tracking the DID
+2. run targeted `backfill` if needed
+3. let `indexer` drain
+4. re-run `enrich` if metadata is still incomplete
 
-3. If you need the record indexed immediately, fetch the detail endpoint through
-   the API or enqueue it explicitly with `POST /admin/indexing/enqueue`.
+### Metadata gaps
 
-### Enrichment gaps
-
-Documents appear in search but `author_handle` or `repo_name` is empty.
+If `author_handle` or `repo_name` is empty:
 
 ```sh
-twister enrich --dry-run   # preview what would be resolved
-twister enrich             # apply
-twister reindex            # re-sync FTS after field updates
+twister enrich --dry-run
+twister enrich
+twister reindex
 ```
 
-### Full index recovery
+### Full PostgreSQL rebuild
 
-Use this sequence after a DB drop, migration to a new Turso database, or other
-full-loss event.
+Use this after restoring to a fresh database or moving to a new PostgreSQL
+instance.
 
-1. Confirm migrations ran: `twister api --local` performs `store.Migrate` on startup.
-2. Register repos with Tap:
+1. start `api` once so migrations run
+2. start `indexer`
+3. run `twister backfill`
+4. run `twister enrich`
+5. run `twister reindex`
+6. verify `/readyz`, `/health`, and smoke checks
 
-   ```sh
-   twister backfill --dry-run
-   twister backfill
-   ```
-
-3. Start the indexer and let it consume: `twister indexer`
-4. Once backfill is complete, enrich fields and re-sync FTS:
-
-   ```sh
-   twister enrich
-   twister reindex
-   ```
-
-5. Verify: `GET /admin/status` for cursor progress, `GET /readyz` for DB health.
+This is the default migration path from the old Turso-backed deployment too.
 
 ### Tap cursor reset
 
-If the indexer cursor is ahead of what Tap will deliver (e.g., after a Tap
-instance reset), events will be skipped until the cursor catches up.
-
-To reset the cursor and reprocess from the beginning of Tap's retention window:
+If the Tap cursor is ahead of the retained event window:
 
 ```sql
 DELETE FROM sync_state WHERE consumer_name = 'indexer-tap-v1';
 ```
 
-Then restart the `indexer`. It will start from the head of the stream and
-process all events Tap delivers.
-
-> **Note:** This does not cause duplicate documents — `UpsertDocument` is
-> idempotent. It may reprocess a large backlog depending on Tap retention.
+Then restart the `indexer`.
 
----
+## Status Checks
 
-## Checking Status
-
-With `ENABLE_ADMIN_ENDPOINTS=true`:
+With admin routes enabled:
 
 ```sh
 curl -H "Authorization: Bearer $ADMIN_AUTH_TOKEN" \
   http://localhost:8080/admin/status
 ```
 
-Response includes:
+Watch:
 
-- `tap.cursor` and `tap.updated_at`
-- `jetstream.cursor` and `jetstream.updated_at`
+- `tap.cursor`
+- `jetstream.cursor`
 - `documents`
-- `read_through.pending`, `processing`, `completed`, `failed`, `dead_letter`
-- `read_through.oldest_pending_age_s` and `oldest_running_age_s`
-- `read_through.last_completed_at` and `last_processed_at`
+- `read_through.pending`
+- `read_through.processing`
+- `read_through.failed`
+- `read_through.dead_letter`

docs/roadmap.md

···
 ---
 title: Roadmap
-updated: 2026-03-25
+updated: 2026-03-26
 ---
 
 ## API: Search Stabilization
 
 Highest priority. This work blocks further investment in search quality and broader discovery features.
 
-- [x] Stabilize local development and experimentation around a local `file:` database
+- [x] Stabilize local development around PostgreSQL, with SQLite kept only as a rollback path
 - [x] Document backup, restore, and disk-growth procedures for the experimental local DB
 - [x] Research production backend options: PostgreSQL, Turso remote/libSQL, and Turso embedded replicas
 - [x] Write a production storage decision record with workload and operational tradeoffs, using `docs/adr/pg.md` and `docs/adr/turso.md`
···
 
 Completed on [2026-03-25](../CHANGELOG.md#2026-03-25)
 
-## API: FTS5 Search Quality
+## API: Keyword Search Quality
 
 Improve keyword search quality without external dependencies.
 
 **Depends on:** API: Search Stabilization
 
 - [ ] Synonym expansion at query time (e.g. "repo" matches "repository")
-- [ ] Stemming tokenizer (porter or unicode61+porter)
+- [ ] Stemming and parser tuning for PostgreSQL full-text search
 - [ ] Prefix search support for autocomplete
 - [ ] Field weight tuning based on real query patterns
 - [ ] Recency boost for recently updated content

docs/specs/search.md

···
 ---
 title: Search
-updated: 2026-03-25
+updated: 2026-03-26
 ---
 
-> Warning: this document is pretty long. Look at the roadmap and ADR summaries for a
-> high-level overview, or jump to the relevant sections.
-
-Search now has two phases:
-
-1. Stabilize indexing and activity caching so search is cheap and reliable.
-2. Enhance keyword search quality with FTS5 features once the base pipeline is stable.
+Twisted search is now operationally centered on PostgreSQL, Tap ingest, and a
+small set of rebuild tools.
 
-## Immediate Priority
+## Current State
 
-The current highest-priority search work is operational, not ranking:
-
-- Stabilize experimentation around a local `file:` database workflow.
-- Add cURL smoke tests for search, document fetches, indexing, and activity reads.
-- Enqueue background indexing when the API fetches records that are not yet searchable.
-- Cache recent JetStream activity server-side with a persisted 24-hour cursor.
-
-Production storage is Turso cloud. The reasoning is recorded in `docs/adr/storage.md`, with the comparison inputs in `docs/adr/pg.md` and `docs/adr/turso.md`.
-
-These tasks block further work on search quality improvements.
-
-## Planning Decisions
-
-### Why This Comes First
-
-Search quality is currently constrained more by ingestion cost and freshness gaps than by ranking quality.
-The next iteration should make Twister cheaper to operate, resilient across restarts, and able to backfill misses on demand before any new semantic or hybrid work.
-
-### Resolved Questions
-
-#### Local-Only Storage
-
-Twister can already run against a local `file:` database. That is useful for stabilizing development and experimentation while the indexing model is still changing. It should not automatically be treated as the final production architecture.
-
-The production storage question remains open and should compare at least:
-
-- PostgreSQL with native full-text search and conventional operational tooling
-- Turso remote/libSQL
-- Turso with embedded replicas or similar local-read, remote-sync patterns
-
-That comparison has been completed, and the current production choice is Turso.
-
-#### Tangled First-Commit Timestamp
-
-The first Tangled commit timestamp is useful as a lower-bound hint for one-time experiments, but it should not become the default replay cursor.
-JetStream has to default to recent history (< 72 hours from now is what's possible) so bootstrap cost stays bounded.
-
-#### Tap Versus JetStream
-
-Tap remains the authoritative indexing and bulk backfill path. JetStream should power only a bounded recent-activity cache.
-Read-through API indexing closes gaps when a user fetches a record before Tap has delivered it.
+- primary storage: PostgreSQL
+- local default URL: `postgresql://localhost/${USER}_dev?sslmode=disable`
+- production deploy target: Coolify application plus managed PostgreSQL
+- legacy fallback: local SQLite behind `--local`
 
 ## Goals
 
-- Reduce search-related reads and writes enough that remote Turso cost is no longer the dominant constraint.
-- Keep indexed content fresh enough for browsing and search without requiring a full-network rebuild after routine restarts.
-- Serve recent activity cheaply from a local cache.
-- Add a smoke-test layer that verifies search and indexing behavior end to end.
-
-## Current Search Mode
-
-### Keyword Search (Implemented)
-
-Full-text search is powered by SQLite FTS5 with BM25 scoring. Queries match title, body, summary, repo name, author handle, and tags. Results are ranked with field-specific weights and snippets highlight matches with `<mark>` tags.
-
-## Stabilization Plan
-
-### Storage
-
-Twister should use a local `file:` database to stabilize experimentation and reduce the messiness of iteration while the indexing pipeline is being hardened. Production storage should remain explicitly undecided until the project compares PostgreSQL and Turso-based options against the final workload.
-
-Requirements:
-
-- keep local-file mode as the simplest path for development and experimentation
-- document what assumptions the local path makes about single-host or shared-disk execution
-- document backup, restore, and disk-growth procedures
-- produce a production storage decision record comparing PostgreSQL and Turso options, starting from `docs/adr/pg.md` and `docs/adr/turso.md`
-
-Evaluation criteria for the production decision:
-
-- write-heavy ingestion behavior
-- FTS quality and indexing ergonomics
-- operational complexity and backup story
-- latency for reads and writes
-- failure recovery and restore workflow
-- support for future semantic search requirements
-
-Acceptance:
-
-- local development no longer depends on remote Turso for routine experimentation
-- the production backend choice is documented with explicit tradeoffs
-- the chosen production backend has a migration path from the experimental local setup
-
-The concrete local DB operating procedure lives in `docs/reference/api.md`.
-The production migration path is documented in `docs/adr/storage.md`.
-
-### Read-Through Indexing
-
-When the API fetches a repo, issue, PR, profile, or similar detail record
-directly from upstream, it should enqueue background indexing work only when
-that record is missing or stale. Tap remains the primary ingest path;
-read-through indexing only closes gaps.
-
-Requirements:
-
-- add a durable job table for on-demand indexing
-- deduplicate jobs by stable document identity
-- reuse the existing normalization and upsert path
-- trigger jobs from detail handlers that already fetch upstream records
-- do not enqueue whole collections from list or browse handlers
-
-Acceptance:
-
-- a fetched-but-missing record becomes searchable shortly after the first successful API read
-- repeated page views do not create unbounded duplicate work
-- queue state and terminal failures are inspectable through admin endpoints
-- failures are visible through logs and smoke tests
-
-### Activity Cache
-
-JetStream should back a recent-activity cache, not the main search index. The server should persist a timestamp cursor, seed it to `now - ~24h` on first boot, rewind slightly on reconnect, and expire old events aggressively.
-
-Requirements:
-
-- add a dedicated activity cache table
-- persist a separate JetStream consumer cursor
-- seed missing cursors to recent history, not full history
-- keep retention bounded by age and row count
-
-Acceptance:
-
-- common activity reads can be served from the cache
-- restarts resume from the stored timestamp cursor
-- reconnects are idempotent and tolerate a short rewind window
+- keep search fresh through Tap ingest and targeted backfill
+- preserve the current `/search` API contract
+- make local development and production use the same database family
+- keep rebuild and recovery workflows simple enough to rehearse
 
-### Smoke Tests
+## Keyword Search
 
-Twister needs cURL-based smoke tests covering:
+Implemented with PostgreSQL full-text search:
 
-- `GET /healthz`
-- `GET /readyz`
-- `GET /search`
-- `GET /documents/{id}`
-- one fetch path that should enqueue indexing
-- one activity endpoint backed by the cache
+- weighted `tsvector` over title, author handle, repo name, summary, body, tags
+- `websearch_to_tsquery('simple', ...)`
+- `ts_rank_cd`
+- `ts_headline`
 
-Acceptance:
+Result scores and snippets may differ from the old SQLite FTS5 implementation.
 
-- one local command can verify the critical API surface
-- the same scripts can run against staging or production by changing the base URL
+## Ingest Model
 
-## Operational Model
+1. Tap is the authoritative indexing path.
+2. Read-through indexing fills misses from detail fetches.
+3. JetStream powers only the bounded activity cache.
+4. `backfill`, `enrich`, and `reindex` rebuild the serving dataset.
 
-1. Tap ingests the authoritative search corpus.
-2. Direct API reads enqueue background indexing for misses.
-3. JetStream fills only the recent-activity cache.
-4. Smoke tests guard the critical paths.
-5. FTS5 quality improvements (synonyms, stemming, prefix search) follow once the base pipeline is stable.
+## Operational Rules
 
-## Backfill Strategy
+- use explicit collection allowlists in production
+- do not import Turso data as the default migration path
+- treat PostgreSQL backups and restore drills as part of normal operations
+- keep the SQLite path only until the PostgreSQL rollout is fully bedded in
 
-- Search index backfill should continue to use Tap admin backfill, firehose-driven repo sync, or repo export based resync.
-- Activity cache bootstrap should use a recent JetStream timestamp cursor, defaulting to `now - 24h`.
-- A manual cursor override can exist for one-time replay experiments, but it should not be the default startup path.
+## Next Search Work
 
-## API Contract
-
-**`GET /search`** — Unified endpoint, routes by `mode` parameter.
-
-### Parameters
-
-| Param        | Required | Default | Description                           |
-| ------------ | -------- | ------- | ------------------------------------- |
-| `q`          | Yes      | —       | Query string                          |
-| `mode`       | No       | keyword | keyword                               |
-| `limit`      | No       | 20      | Results per page (1–100)              |
-| `offset`     | No       | 0       | Pagination offset                     |
-| `collection` | No       | —       | Filter by collection NSID             |
-| `type`       | No       | —       | Filter by record type                 |
-| `author`     | No       | —       | Filter by handle or DID               |
-| `repo`       | No       | —       | Filter by repo name or DID            |
-| `language`   | No       | —       | Filter by primary language            |
-| `from`       | No       | —       | Created after (ISO 8601)              |
-| `to`         | No       | —       | Created before (ISO 8601)             |
-| `state`      | No       | —       | Issue/PR state (open, closed, merged) |
-
-### Response
-
-```json
-{
-  "query": "tangled vue",
-  "mode": "keyword",
-  "total": 42,
-  "limit": 20,
-  "offset": 0,
-  "results": [
-    {
-      "id": "did:plc:abc|sh.tangled.repo|my-repo",
-      "collection": "sh.tangled.repo",
-      "record_type": "repo",
-      "title": "my-repo",
-      "summary": "A Vue component library",
-      "body_snippet": "...building <mark>Vue</mark> components for <mark>Tangled</mark>...",
-      "score": 4.82,
-      "matched_by": ["keyword"],
-      "repo_name": "my-repo",
-      "author_handle": "alice.bsky.social",
-      "did": "did:plc:abc",
-      "at_uri": "at://did:plc:abc/sh.tangled.repo/my-repo",
-      "web_url": "https://tangled.sh/alice.bsky.social/my-repo",
-      "created_at": "2026-01-15T10:00:00Z",
-      "updated_at": "2026-03-20T14:30:00Z"
-    }
-  ]
-}
-```
-
-## Search Strategy
-
-Indexing via Tap is useful but has proven unreliable for maintaining complete, up-to-date coverage. The approach:
-
-1. **Keyword search is the foundation.** It works now and covers the primary use case — finding repos, issues, and people by name or content.
-
-2. **Constellation supplements search results.** Star counts and follower counts from Constellation can be used as ranking signals without needing to index interaction records ourselves.
-
-3. **Read-through indexing closes freshness gaps.** If a user can fetch a record, the system should be able to make it searchable shortly after.
-
-4. **JetStream is for recent activity, not authoritative indexing.** Use it to power the cached feed, not to replace Tap or repo re-sync.
-
-5. **FTS5 enhancements are the next quality step.** Synonym expansion, stemming, and prefix search improve discovery without external dependencies.
-
-6. **Graceful degradation.** The mobile app treats the search API as optional. If Twister is unavailable, handle-based direct browsing still works. Search results link into the same browsing screens.
-
-## Quality Improvements (Planned)
-
-- Synonym expansion at query time (e.g. "repo" matches "repository")
-- Stemming tokenizer (porter or unicode61+porter)
-- Prefix search support for autocomplete
-- Field weight tuning based on real query patterns
-- Recency boost for recently updated content
-- Collection-aware ranking
-- Star count as a ranking signal
-- State filtering defaults
-- Better snippet generation
-- Relevance test fixtures
-
-## Mobile Integration
-
-The app calls the search API from the Explore tab. Results are displayed in segmented views (repos, users, issues/PRs).
-Each result links to the corresponding browsing screen (repo detail, profile, issue detail).
-
-When the search API is unavailable, the Explore tab shows an appropriate state rather than breaking.
-The Home tab's handle-based browsing is fully independent of search.
+- synonym expansion
+- stemming and better tokenizer choices
+- field weight tuning from real queries
+- recency boosts
+- relevance fixtures that assert behavior, not exact score strings

justfile

···
 api-build:
     just --justfile packages/api/justfile build
 
-# Run API. Usage: just api-dev [mode], mode: local|remote (default local)
+# Run API. Usage: just api-dev [mode], mode: local|remote|sqlite (default local)
 api-dev mode="local":
     just --justfile packages/api/justfile run-api {{mode}}
 
-# Run indexer. Usage: just api-run-indexer [mode], mode: local|remote (default local)
+# Run indexer. Usage: just api-run-indexer [mode], mode: local|remote|sqlite (default local)
 api-run-indexer mode="local":
     just --justfile packages/api/justfile run-indexer {{mode}}
+
+db-up:
+    docker compose -f docker-compose.dev.yaml up -d postgres tap
+
+db-down:
+    docker compose -f docker-compose.dev.yaml down
+
+db-psql:
+    psql "postgresql://localhost/${USER:-postgres}_dev?sslmode=disable"
 
 api-test:
     just --justfile packages/api/justfile test

packages/api/doc.go

···
 // Twister is the Tap-backed indexing and search API for Tangled.
 //
-// It proxies upstream AT Protocol services such as knots, PDS endpoints,
-// Bluesky, Constellation, and Jetstream so the app can use a single origin.
-//
 // Requirements
 //
 //   - Go 1.25+
-//   - A Turso database, or local SQLite for development
+//   - PostgreSQL for the normal local and production workflow
 //
 // Running locally
 //
-//	cd packages/api
-//	go run . api --local
-//
-// The local API listens on :8080 by default and uses packages/api/twister-dev.db.
-// Logs are printed as text when --local is set.
-//
-// # API smoke tests
-//
-// Smoke checks live in packages/scripts/api/. From the repo root:
-//
-//	uv run --project packages/scripts/api twister-api-smoke
-//
-// Optional base URL override:
-//
-//	TWISTER_API_BASE_URL=http://localhost:8080 \
-//	  uv run --project packages/scripts/api twister-api-smoke
+//	cd /Users/owais/Projects/Twisted
+//	just db-up
+//	just api-dev
+//	just api-run-indexer
 //
-// # Experimental local DB operations
+// The default local database URL is:
 //
-// The experimental local database lives at packages/api/twister-dev.db when
-// you run Twister with --local. Treat it as disposable unless you explicitly
-// back it up.
+//	postgresql://localhost/${USER}_dev?sslmode=disable
 //
-// Backup:
+// That matches a Postgres.app-style setup and the repo's dev compose file.
 //
-//  1. Stop the Twister process using the local DB.
-//  2. Copy the database file and any SQLite sidecar files if they exist.
-//
-// Example:
+// # Legacy fallback
 //
-//	cd packages/api
-//	mkdir -p backups
-//	timestamp="$(date +%Y%m%d-%H%M%S)"
-//	cp twister-dev.db "backups/twister-dev-${timestamp}.db"
-//	test -f twister-dev.db-wal && cp twister-dev.db-wal "backups/twister-dev-${timestamp}.db-wal"
-//	test -f twister-dev.db-shm && cp twister-dev.db-shm "backups/twister-dev-${timestamp}.db-shm"
+// `--local` is deprecated and switches the service to the temporary SQLite
+// fallback at packages/api/twister-dev.db.
 //
-// Restore:
+//	go run . api --local
 //
-//  1. Stop the Twister process.
-//  2. Move the current local DB aside if you want to keep it.
-//  3. Copy the backup file back to twister-dev.db.
-//  4. Restore matching -wal and -shm files only if they came from the same set.
+// Smoke checks
 //
-// Example:
+//	uv run --project packages/scripts/api twister-api-smoke
 //
-//	cd packages/api
-//	mv twister-dev.db "twister-dev.db.broken.$(date +%Y%m%d-%H%M%S)" 2>/dev/null || true
-//	cp backups/twister-dev-YYYYMMDD-HHMMSS.db twister-dev.db
+// Optional base URL override:
 //
-// Disk growth:
+//	TWISTER_API_BASE_URL=http://localhost:8080 \
+//	  uv run --project packages/scripts/api twister-api-smoke
 //
-// The local DB grows because of indexed documents, FTS tables, activity cache
-// rows, and repeated backfill or reindex runs.
+// Environment variables
 //
-// Recommended operating procedure:
-//
-//  1. Check file growth periodically.
-//  2. Delete and rebuild the DB freely when the dataset is no longer useful.
-//  3. Run VACUUM only when you intentionally want to compact a long-lived DB.
-//  4. Keep old backups out of the repo and rotate them manually.
-//
-// Inspection commands:
-//
-//	cd packages/api
-//	du -h twister-dev.db*
-//	ls -lh twister-dev.db*
-//
-// Failure recovery: prefer restore-or-rebuild over manual repair if the
-// experimental DB becomes
-// suspicious or inconsistent. It is a developer convenience database, not the
-// source of truth.
-//
-// # Environment variables
-//
-// Copy .env.example to .env in the repo root or packages/api/. The server loads
-// .env, ../.env, and ../../.env automatically.
-//
-//   - TURSO_DATABASE_URL: Turso/libSQL connection URL, required unless --local
-//   - TURSO_AUTH_TOKEN: auth token, required for non-file URLs
-//   - HTTP_BIND_ADDR: default :8080
-//   - LOG_LEVEL: debug, info, warn, or error; default info
-//   - LOG_FORMAT: json or text; default json
-//   - SEARCH_DEFAULT_LIMIT: default 20
-//   - SEARCH_MAX_LIMIT: default 100
+//   - DATABASE_URL: primary database connection URL
+//   - HTTP_BIND_ADDR: API bind address, default :8080
+//   - INDEXER_HEALTH_ADDR: indexer health bind address, default :9090
+//   - LOG_LEVEL: debug, info, warn, or error
+//   - LOG_FORMAT: json or text
+//   - TAP_URL: Tap WebSocket URL, default ws://localhost:2480/channel in local indexer runs
+//   - TAP_AUTH_PASSWORD: Tap admin password, default twisted-dev in local indexer runs
+//   - INDEXED_COLLECTIONS: comma-separated AT collections to index
+//   - READ_THROUGH_MODE: off or missing; default missing
+//   - READ_THROUGH_COLLECTIONS: read-through allowlist
+//   - READ_THROUGH_MAX_ATTEMPTS: retries before dead_letter
 //   - ENABLE_ADMIN_ENDPOINTS: default false
-//   - ADMIN_AUTH_TOKEN: bearer token for admin endpoints
-//   - CONSTELLATION_URL: default https://constellation.microcosm.blue
-//   - CONSTELLATION_USER_AGENT: user-agent sent to Constellation
-//   - TAP_URL: Tap firehose URL, indexer only
-//   - TAP_AUTH_PASSWORD: Tap auth password, indexer only
-//   - INDEXED_COLLECTIONS: comma-separated AT collections to index
-//   - READ_THROUGH_MODE: off, missing, or broad; default missing
-//   - READ_THROUGH_COLLECTIONS: read-through allowlist, default INDEXED_COLLECTIONS
-//   - READ_THROUGH_MAX_ATTEMPTS: max retries before dead_letter, default 5
+//   - ADMIN_AUTH_TOKEN: bearer token for admin routes
 //
 // CLI commands
 //
···
 //	twister backfill
 //	twister reindex
 //	twister enrich
-//
-// Enrich:
+//	twister healthcheck
 //
-// Resolves missing author_handle, repo_name, and web_url fields on documents
-// already in the database.
+// # Deployment
 //
-//	twister enrich --local
-//	twister enrich --local --collection sh.tangled.repo
-//	twister enrich --local --did did:plc:abc123
-//	twister enrich --local --dry-run
-//
-// Flags: --collection, --did, --document, --dry-run, --concurrency (default 5).
-//
-// Proxy endpoints
-//
-//   - GET /proxy/knot/{host}/{nsid} -> https://{host}/xrpc/{nsid}
-//   - GET /proxy/pds/{host}/{nsid} -> https://{host}/xrpc/{nsid}
-//   - GET /proxy/bsky/{nsid} -> https://public.api.bsky.app/xrpc/{nsid}
-//   - GET /identity/resolve -> https://bsky.social/xrpc/com.atproto.identity.resolveHandle
-//   - GET /identity/did/{did} -> https://plc.directory/{did} or /.well-known/did.json
-//   - GET /backlinks/count -> Constellation getBacklinksCount, cached
-//   - WS /activity/stream -> wss://jetstream2.us-east.bsky.network/subscribe
-//
-// # Admin endpoints
-//
-// Admin routes require ENABLE_ADMIN_ENDPOINTS=true. If ADMIN_AUTH_TOKEN is set,
-// requests must send Authorization: Bearer <ADMIN_AUTH_TOKEN>.
-//
-//   - GET /admin/status: cursor state, queue counts, oldest ages, last activity
-//   - GET /admin/indexing/jobs: inspect queue rows by status, source, or document
-//   - GET /admin/indexing/audit: inspect append-only indexing audit rows
-//   - POST /admin/indexing/enqueue: queue one explicit record for indexing
-//   - POST /admin/reindex: re-sync all or filtered documents into the FTS index
+// Production uses Coolify for the `api`, `indexer`, and `tap` services plus a
+// separate Coolify-managed PostgreSQL resource. See docs/reference/deployment-walkthrough.md.
 package main

packages/api/go.mod

···
 require (
 	github.com/charmbracelet/log v1.0.0
 	github.com/coder/websocket v1.8.12
+	github.com/jackc/pgx/v5 v5.9.1
 	github.com/joho/godotenv v1.5.1
 	github.com/spf13/cobra v1.10.2
-	github.com/tursodatabase/libsql-client-go v0.0.0-20251219100830-236aa1ff8acc
 	modernc.org/sqlite v1.47.0
 )
 
 require (
-	github.com/antlr4-go/antlr/v4 v4.13.0 // indirect
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
 	github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
 	github.com/charmbracelet/lipgloss v1.1.0 // indirect
···
 	github.com/go-logfmt/logfmt v0.6.1 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-runewidth v0.0.16 // indirect
···
 	github.com/spf13/pflag v1.0.9 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	golang.org/x/exp v0.0.0-20251023183803-a4bb9ffd2546 // indirect
+	golang.org/x/sync v0.19.0 // indirect
 	golang.org/x/sys v0.42.0 // indirect
+	golang.org/x/text v0.29.0 // indirect
 	modernc.org/libc v1.70.0 // indirect
 	modernc.org/mathutil v1.7.1 // indirect
 	modernc.org/memory v1.11.0 // indirect

packages/api/go.sum

···
-github.com/antlr4-go/antlr/v4 v4.13.0 h1:lxCg3LAv+EUK6t1i0y1V6/SLeUi0eKEKdhQAlS8TVTI=
-github.com/antlr4-go/antlr/v4 v4.13.0/go.mod h1:pfChB/xh/Unjila75QW7+VU4TSnWnnk9UTnmpPaOR2g=
 github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k=
 github.com/aymanbagabas/go-osc52/v2 v2.0.1/go.mod h1:uYgXzlJ7ZpABp8OJ+exZzJJhRNQ2ASbcXHWsFqH8hp8=
 github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc h1:4pZI35227imm7yK2bGPcfpFEmuY1gc2YSTShr4iJBfs=
···
 github.com/coder/websocket v1.8.12 h1:5bUXkEPPIbewrnkU8LTCLVaxi4N4J8ahufH2vlo4NAo=
 github.com/coder/websocket v1.8.12/go.mod h1:LNVeNrXQZfe5qhS9ALED3uA+l5pPqvwXg3CKoDBB2gs=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
···
 github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
+github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+github.com/jackc/pgx/v5 v5.9.1 h1:uwrxJXBnx76nyISkhr33kQLlUqjv7et7b9FjCen/tdc=
+github.com/jackc/pgx/v5 v5.9.1/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
+github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
+github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
 github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
 github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
 github.com/lucasb-eyer/go-colorful v1.2.0 h1:1nnpGOrhyZZuNyfu1QjKiUICQ74+3FNCN69Aj6K7nkY=
···
 github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
 github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
 github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
-github.com/tursodatabase/libsql-client-go v0.0.0-20251219100830-236aa1ff8acc h1:lzi/5fg2EfinRlh3v//YyIhnc4tY7BTqazQGwb1ar+0=
-github.com/tursodatabase/libsql-client-go v0.0.0-20251219100830-236aa1ff8acc/go.mod h1:08inkKyguB6CGGssc/JzhmQWwBgFQBgjlYFjxjRh7nU=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
···
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
 golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/text v0.29.0 h1:1neNs90w9YzJ9BocxfsQNHKuAT4pkghyXc4nhZ6sJvk=
+golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4=
 golang.org/x/tools v0.42.0 h1:uNgphsn75Tdz5Ji2q36v/nsFSfR/9BRFvqhGBaJGd5k=
 golang.org/x/tools v0.42.0/go.mod h1:Ma6lCIwGZvHK6XtgbswSoWroEkhugApmsXyrUmBhfr0=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 modernc.org/cc/v4 v4.27.1 h1:9W30zRlYrefrDV2JE2O8VDtJ1yPGownxciz5rrbQZis=

packages/api/internal/api/api.go

···
 
 // Server is the HTTP search API server.
 type Server struct {
-	search        *search.Repository
+	search        search.Repository
 	store         store.Store
 	cfg           *config.Config
 	log           *slog.Logger
···
 }
 
 // New creates a new API server.
-func New(searchRepo *search.Repository, st store.Store, cfg *config.Config, log *slog.Logger, constellation *constellation.Client, xrpcClient *xrpc.Client) *Server {
+func New(searchRepo search.Repository, st store.Store, cfg *config.Config, log *slog.Logger, constellation *constellation.Client, xrpcClient *xrpc.Client) *Server {
 	registry := normalize.NewRegistry()
 	policy := idx.NewPolicy(cfg.IndexedCollections, cfg.ReadThroughCollections, cfg.ReadThroughMode)
 	return &Server{

packages/api/internal/api/test_store_test.go

···
 func (s *apiTestStore) ListDocuments(_ context.Context, _ store.DocumentFilter) ([]*store.Document, error) {
 	return nil, nil
 }
-func (s *apiTestStore) OptimizeFTS(_ context.Context) error { return nil }
+func (s *apiTestStore) OptimizeSearchIndex(_ context.Context) error { return nil }
 func (s *apiTestStore) GetSyncState(_ context.Context, _ string) (*store.SyncState, error) {
 	return nil, nil
 }

packages/api/internal/backfill/doc.go

···
 // Package backfill provides Tap bootstrap tooling for Twister.
 //
-// # Backfill Runbook
+// # Backfill runbook
 //
-// This runbook covers initial bootstrap and repeat runs using:
+// The default command is:
 //
 //	twister backfill
 //
 // `--source lightrail` is the default and discovers DIDs from
-// com.atproto.sync.listReposByCollection. `--source graph` keeps the older
-// handle/DID seed crawl for targeted fallback runs.
-//
-// # Graph Seeds Input
-//
-// The `--seeds` flag applies only to `--source graph` and supports either of
-// these forms:
-//
-//  1. File path:
-//
-//     twister backfill --seeds /etc/twister/seeds.txt
-//
-//  2. Comma-separated inline list:
-//
-//     twister backfill --seeds anirudh.fi,atprotocol.dev,oppi.li
+// com.atproto.sync.listReposByCollection. `--source graph` remains available for
+// targeted fallback runs.
 //
-// Supported seed entries are DIDs and handles.
-//
-// Repository-managed example seed file:
-//
-//	docs/api/seeds.txt
+// # Graph seeds input
 //
-// Runtime seed file is typically mounted outside the repo, for example:
+// The `--seeds` flag applies only to `--source graph` and accepts either:
 //
-//	/etc/twister/seeds.txt
+//  1. a file path
+//  2. a comma-separated list of DIDs or handles
 //
-// # Prerequisites
+// Prerequisites
 //
-// Required environment variables:
-//
-//   - TURSO_DATABASE_URL
-//   - TURSO_AUTH_TOKEN (for non-file Turso URLs)
+//   - DATABASE_URL
 //   - TAP_URL
 //   - TAP_AUTH_PASSWORD
 //
-// # First Bootstrap
-//
-//  1. Run full-network dry-run:
-//
-//     twister backfill --dry-run
+// Typical bootstrap
 //
-//  2. Run real bootstrap:
+//  1. twister backfill --dry-run
+//  2. twister backfill
+//  3. twister enrich
+//  4. twister reindex
 //
-//     twister backfill
+// In local development, docker-compose.dev.yaml runs Tap on
+// ws://localhost:2480/channel.
 //
-//  3. Use graph mode only for targeted fallback:
-//
-//     twister backfill --source graph --seeds /tmp/twister-seeds.txt --max-hops 2
-//
-// Watch logs for discovery totals and Tap submission progress.
-//
-// # Repeat Run
-//
-// Re-run `twister backfill` whenever you need to reseed the authoritative Tap
-// corpus. Append graph seeds only when using `--source graph`.
-//
-// # Dry-Run Safety
-//
-// Before production mutation:
-//   - include --dry-run
-//   - confirm only discovery output appears
-//   - confirm no Tap mutation side effects
+// Re-run backfill whenever you need to reseed the authoritative Tap corpus.
 package backfill

packages/api/internal/config/config.go

···
 import (
 	"errors"
 	"os"
+	"os/user"
 	"path/filepath"
 	"strconv"
 	"strings"
···
 )
 
 type Config struct {
-	TursoURL                   string
-	TursoToken                 string
+	DatabaseURL                string
 	TapURL                     string
 	TapAuthPassword            string
 	IndexedCollections         string
···
 	loadDotEnv()
 
 	cfg := &Config{
-		TursoURL:                   os.Getenv("TURSO_DATABASE_URL"),
-		TursoToken:                 os.Getenv("TURSO_AUTH_TOKEN"),
+		DatabaseURL:                databaseURL(),
 		TapURL:                     os.Getenv("TAP_URL"),
 		TapAuthPassword:            os.Getenv("TAP_AUTH_PASSWORD"),
 		IndexedCollections:         os.Getenv("INDEXED_COLLECTIONS"),
···
 	}
 
 	if opts.Local {
-		dbURL, err := localDatabaseURL(opts.WorkDir)
+		dbURL, err := localSQLiteDatabaseURL(opts.WorkDir)
 		if err != nil {
 			return nil, err
 		}
-		cfg.TursoURL = dbURL
-		cfg.TursoToken = ""
+		cfg.DatabaseURL = dbURL
 		cfg.LogFormat = "text"
 	}
 
 	var errs []error
-	if cfg.TursoURL == "" {
-		errs = append(errs, errors.New("TURSO_DATABASE_URL is required"))
-	}
-	if cfg.TursoToken == "" && !strings.HasPrefix(cfg.TursoURL, "file:") {
-		errs = append(errs, errors.New("TURSO_AUTH_TOKEN is required for non-file URLs"))
+	if cfg.DatabaseURL == "" {
+		errs = append(errs, errors.New("DATABASE_URL is required"))
 	}
 	if len(errs) > 0 {
 		return nil, errors.Join(errs...)
···
 	return cfg, nil
 }
 
-func localDatabaseURL(workDir string) (string, error) {
+func localSQLiteDatabaseURL(workDir string) (string, error) {
 	if strings.TrimSpace(workDir) == "" {
 		var err error
 		workDir, err = os.Getwd()
···
 		}
 	}
 	return "file:" + filepath.Join(workDir, "twister-dev.db"), nil
+}
+
+func databaseURL() string {
+	if v := strings.TrimSpace(os.Getenv("DATABASE_URL")); v != "" {
+		return v
+	}
+	if v := strings.TrimSpace(os.Getenv("TURSO_DATABASE_URL")); v != "" {
+		return v
+	}
+	return defaultLocalDatabaseURL()
+}
+
+func defaultLocalDatabaseURL() string {
+	userName := strings.TrimSpace(os.Getenv("USER"))
+	if userName == "" {
+		if current, err := user.Current(); err == nil {
+			userName = strings.TrimSpace(current.Username)
+		}
+	}
+	if userName == "" {
+		userName = "postgres"
+	}
+	return "postgresql://localhost/" + userName + "_dev?sslmode=disable"
 }
 
 func loadDotEnv() {

packages/api/internal/config/config_test.go

···
 	"testing"
 )
 
-func TestLoadRequiresRemoteTursoConfigurationByDefault(t *testing.T) {
+func TestLoadUsesDefaultLocalPostgresURL(t *testing.T) {
+	t.Setenv("DATABASE_URL", "")
 	t.Setenv("TURSO_DATABASE_URL", "")
-	t.Setenv("TURSO_AUTH_TOKEN", "")
 
-	_, err := Load(LoadOptions{})
-	if err == nil {
-		t.Fatal("expected missing Turso config to fail")
+	cfg, err := Load(LoadOptions{})
+	if err != nil {
+		t.Fatalf("load config: %v", err)
+	}
+	if got, want := cfg.DatabaseURL, defaultLocalDatabaseURL(); got != want {
+		t.Fatalf("DatabaseURL: got %q, want %q", got, want)
 	}
 }
 
 func TestLoadLocalOverridesRemoteDatabaseAndLogging(t *testing.T) {
 	workDir := t.TempDir()
-	t.Setenv("TURSO_DATABASE_URL", "libsql://example.turso.io")
-	t.Setenv("TURSO_AUTH_TOKEN", "secret")
+	t.Setenv("DATABASE_URL", "postgresql://localhost/test_dev?sslmode=disable")
 	t.Setenv("LOG_FORMAT", "json")
 
 	cfg, err := Load(LoadOptions{Local: true, WorkDir: workDir})
···
 	}
 
 	wantURL := "file:" + filepath.Join(workDir, "twister-dev.db")
-	if cfg.TursoURL != wantURL {
-		t.Fatalf("TursoURL: got %q, want %q", cfg.TursoURL, wantURL)
-	}
-	if cfg.TursoToken != "" {
-		t.Fatalf("TursoToken: got %q, want empty", cfg.TursoToken)
+	if cfg.DatabaseURL != wantURL {
+		t.Fatalf("DatabaseURL: got %q, want %q", cfg.DatabaseURL, wantURL)
 	}
 	if cfg.LogFormat != "text" {
 		t.Fatalf("LogFormat: got %q, want %q", cfg.LogFormat, "text")
···
 	if err != nil {
 		t.Fatalf("getwd: %v", err)
 	}
+	t.Setenv("DATABASE_URL", "")
 	t.Setenv("TURSO_DATABASE_URL", "")
-	t.Setenv("TURSO_AUTH_TOKEN", "")
 
 	cfg, err := Load(LoadOptions{Local: true})
 	if err != nil {
···
 	}
 
 	wantURL := "file:" + filepath.Join(wd, "twister-dev.db")
-	if cfg.TursoURL != wantURL {
-		t.Fatalf("TursoURL: got %q, want %q", cfg.TursoURL, wantURL)
+	if cfg.DatabaseURL != wantURL {
+		t.Fatalf("DatabaseURL: got %q, want %q", cfg.DatabaseURL, wantURL)
 	}
 }
 
 func TestLoadReadThroughDefaults(t *testing.T) {
-	t.Setenv("TURSO_DATABASE_URL", "file:test.db")
-	t.Setenv("TURSO_AUTH_TOKEN", "")
+	t.Setenv("DATABASE_URL", "file:test.db")
 	t.Setenv("INDEXED_COLLECTIONS", "sh.tangled.repo,sh.tangled.repo.issue")
 	t.Setenv("READ_THROUGH_MODE", "")
 	t.Setenv("READ_THROUGH_COLLECTIONS", "")
···
 	}
 }
 
-func TestLoadUsesRailwayPortForBindAddresses(t *testing.T) {
-	t.Setenv("TURSO_DATABASE_URL", "file:test.db")
-	t.Setenv("TURSO_AUTH_TOKEN", "")
+func TestLoadUsesPortEnvForBindAddresses(t *testing.T) {
+	t.Setenv("DATABASE_URL", "file:test.db")
 	t.Setenv("HTTP_BIND_ADDR", "")
 	t.Setenv("INDEXER_HEALTH_ADDR", "")
 	t.Setenv("PORT", "4567")
···
 	}
 }
 
-func TestLoadPrefersExplicitBindAddressesOverRailwayPort(t *testing.T) {
-	t.Setenv("TURSO_DATABASE_URL", "file:test.db")
-	t.Setenv("TURSO_AUTH_TOKEN", "")
+func TestLoadPrefersExplicitBindAddressesOverPortEnv(t *testing.T) {
+	t.Setenv("DATABASE_URL", "file:test.db")
 	t.Setenv("HTTP_BIND_ADDR", "0.0.0.0:8081")
 	t.Setenv("INDEXER_HEALTH_ADDR", "0.0.0.0:9091")
 	t.Setenv("PORT", "4567")
···
 		t.Fatalf("IndexerHealthAddr: got %q", cfg.IndexerHealthAddr)
 	}
 }
+
+func TestLoadSupportsLegacyDatabaseEnvName(t *testing.T) {
+	t.Setenv("DATABASE_URL", "")
+	t.Setenv("TURSO_DATABASE_URL", "file:test.db")
+
+	cfg, err := Load(LoadOptions{})
+	if err != nil {
+		t.Fatalf("load config: %v", err)
+	}
+	if got, want := cfg.DatabaseURL, "file:test.db"; got != want {
+		t.Fatalf("DatabaseURL: got %q, want %q", got, want)
+	}
+}

packages/api/internal/enrich/enrich.go

···
 
 	if !opts.DryRun && result.Updated > 0 {
 		r.log.Info("enrich: optimizing fts index")
-		if err := r.store.OptimizeFTS(ctx); err != nil {
-			r.log.Error("enrich: fts optimize failed", slog.String("error", err.Error()))
+		if err := r.store.OptimizeSearchIndex(ctx); err != nil {
+			r.log.Error("enrich: search index finalize failed", slog.String("error", err.Error()))
 			result.Errors++
 		}
 	}

packages/api/internal/ingest/ingest_test.go

···
 	return docs, nil
 }
 
-func (f *fakeStore) OptimizeFTS(_ context.Context) error {
+func (f *fakeStore) OptimizeSearchIndex(_ context.Context) error {
 	return nil
 }
 

packages/api/internal/reindex/reindex.go

···
-// Package reindex re-syncs documents to the FTS index from stored fields.
+// Package reindex re-syncs documents to the search index from stored fields.
 // It is used by the `twister reindex` CLI command and the POST /admin/reindex endpoint.
 package reindex
 
···
 }
 
 // Run reindexes documents matching opts.
-// It re-upserts each document (which re-syncs the FTS virtual table) and then
-// runs an FTS optimize pass to merge Tantivy/FTS5 segments.
+// It re-upserts each document and then runs any backend-specific search index
+// optimization step.
 func (r *Runner) Run(ctx context.Context, opts Options) (*Result, error) {
 	filter := store.DocumentFilter{
 		Collection: opts.Collection,
···
 	}
 
 	if !opts.DryRun {
-		r.log.Info("reindex: optimizing fts index")
-		if err := r.store.OptimizeFTS(ctx); err != nil {
-			r.log.Error("reindex: fts optimize failed", slog.String("error", err.Error()))
+		r.log.Info("reindex: finalizing search index")
+		if err := r.store.OptimizeSearchIndex(ctx); err != nil {
+			r.log.Error("reindex: search index finalize failed", slog.String("error", err.Error()))
 			result.Errors++
 		}
 	}

packages/api/internal/search/postgres_repository.go

···
+package search
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"strings"
+)
+
+type PostgresRepository struct {
+	db *sql.DB
+}
+
+type pgSearchArgs struct {
+	args []any
+}
+
+func newPGSearchArgs(initial ...any) *pgSearchArgs {
+	return &pgSearchArgs{args: append([]any{}, initial...)}
+}
+
+func (p *pgSearchArgs) Add(value any) string {
+	p.args = append(p.args, value)
+	return fmt.Sprintf("$%d", len(p.args))
+}
+
+func (p *pgSearchArgs) Values() []any {
+	return p.args
+}
+
+func (r *PostgresRepository) Ping(ctx context.Context) error {
+	return r.db.PingContext(ctx)
+}
+
+func (r *PostgresRepository) Keyword(ctx context.Context, p Params) (*Response, error) {
+	args := newPGSearchArgs(p.Query)
+	where := []string{"d.search_vector @@ query.q", "d.deleted_at IS NULL"}
+	joins := []string{
+		"LEFT JOIN identity_handles repo_owner ON repo_owner.did = d.repo_did AND repo_owner.is_active = TRUE",
+	}
+
+	if p.Collection != "" {
+		where = append(where, "d.collection = "+args.Add(p.Collection))
+	}
+	if p.Type != "" {
+		where = append(where, "d.record_type = "+args.Add(p.Type))
+	}
+	if p.Author != "" {
+		placeholder := args.Add(p.Author)
+		where = append(where, fmt.Sprintf("(d.author_handle = %s OR d.did = %s)", placeholder, args.Add(p.Author)))
+	}
+	if p.Repo != "" {
+		placeholder := args.Add(p.Repo)
+		where = append(where, fmt.Sprintf("(d.repo_name = %s OR d.repo_did = %s)", placeholder, args.Add(p.Repo)))
+	}
+	if p.Language != "" {
+		where = append(where, "d.language = "+args.Add(p.Language))
+	}
+	if p.From != "" {
+		where = append(where, "d.created_at >= "+args.Add(p.From))
+	}
+	if p.To != "" {
+		where = append(where, "d.created_at <= "+args.Add(p.To))
+	}
+	if p.State != "" {
+		joins = append(joins, "JOIN record_state rs ON rs.subject_uri = d.at_uri")
+		where = append(where, "rs.state = "+args.Add(p.State))
+	}
+
+	baseQuery := `
+		WITH query AS (
+			SELECT websearch_to_tsquery('simple', $1) AS q
+		)`
+	fromClause := `
+		FROM documents d
+		CROSS JOIN query
+		` + strings.Join(joins, "\n")
+	whereClause := " WHERE " + strings.Join(where, " AND ")
+
+	countSQL := baseQuery + `
+		SELECT COUNT(*)
+	` + fromClause + whereClause
+
+	var total int
+	if err := r.db.QueryRowContext(ctx, countSQL, args.Values()...).Scan(&total); err != nil {
+		return nil, fmt.Errorf("count: %w", err)
+	}
+
+	limitPlaceholder := args.Add(p.Limit)
+	offsetPlaceholder := args.Add(p.Offset)
+
+	resultsSQL := baseQuery + `
+		SELECT d.id, d.title, d.summary, d.repo_name, repo_owner.handle, d.author_handle,
+		       d.did, d.at_uri, d.web_url, d.collection, d.record_type, d.created_at, d.updated_at,
+		       ts_rank_cd(d.search_vector, query.q) AS score,
+		       ts_headline(
+		       	'simple',
+		       	COALESCE(NULLIF(d.body, ''), COALESCE(d.summary, '')),
+		       	query.q,
+		       	'StartSel=<mark>, StopSel=</mark>, MaxWords=20, MinWords=10, MaxFragments=2, FragmentDelimiter= ... '
+		       ) AS body_snippet
+	` + fromClause + whereClause + `
+		ORDER BY score DESC, d.updated_at DESC
+		LIMIT ` + limitPlaceholder + ` OFFSET ` + offsetPlaceholder
+
+	rows, err := r.db.QueryContext(ctx, resultsSQL, args.Values()...)
+	if err != nil {
+		return nil, fmt.Errorf("search: %w", err)
+	}
+	defer rows.Close()
+
+	results := make([]Result, 0)
+	for rows.Next() {
+		res, err := scanResult(rows)
+		if err != nil {
+			return nil, err
+		}
+		results = append(results, *res)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("rows: %w", err)
+	}
+
+	return &Response{
+		Query:   p.Query,
+		Mode:    "keyword",
+		Total:   total,
+		Limit:   p.Limit,
+		Offset:  p.Offset,
+		Results: results,
+	}, nil
+}
+
+func scanResult(scanner interface {
+	Scan(dest ...any) error
+}) (*Result, error) {
+	var res Result
+	var title, summary, repoName, repoOwnerHandle, authorHandle sql.NullString
+	var webURL, createdAt, updatedAt sql.NullString
+	var bodySnippet sql.NullString
+
+	if err := scanner.Scan(
+		&res.ID, &title, &summary, &repoName, &repoOwnerHandle, &authorHandle,
+		&res.DID, &res.ATURI, &webURL, &res.Collection, &res.RecordType,
+		&createdAt, &updatedAt, &res.Score, &bodySnippet,
+	); err != nil {
+		return nil, fmt.Errorf("scan: %w", err)
+	}
+	res.Title = title.String
+	res.Summary = summary.String
+	res.RepoName = repoName.String
+	res.RepoOwnerHandle = repoOwnerHandle.String
+	res.AuthorHandle = authorHandle.String
+	res.WebURL = webURL.String
+	res.BodySnippet = bodySnippet.String
+	res.CreatedAt = createdAt.String
+	res.UpdatedAt = updatedAt.String
+	res.MatchedBy = []string{"keyword"}
+	return &res, nil
+}

packages/api/internal/search/search.go

···
 import (
 	"context"
 	"database/sql"
-	"fmt"
 	"strings"
 )
 
···
 }
 
 // Repository executes search queries against the database.
-type Repository struct {
-	db *sql.DB
-}
-
-// NewRepository creates a search repository backed by the given database.
-func NewRepository(db *sql.DB) *Repository {
-	return &Repository{db: db}
-}
-
-// Ping checks database connectivity.
-func (r *Repository) Ping(ctx context.Context) error {
-	return r.db.PingContext(ctx)
-}
-
-// Keyword runs a full-text keyword search.
-func (r *Repository) Keyword(ctx context.Context, p Params) (*Response, error) {
-	ftsQuery := toFTS5Query(p.Query)
-
-	var filters []string
-	var filterArgs []any
-
-	if p.Collection != "" {
-		filters = append(filters, "d.collection = ?")
-		filterArgs = append(filterArgs, p.Collection)
-	}
-	if p.Type != "" {
-		filters = append(filters, "d.record_type = ?")
-		filterArgs = append(filterArgs, p.Type)
-	}
-	if p.Author != "" {
-		filters = append(filters, "(d.author_handle = ? OR d.did = ?)")
-		filterArgs = append(filterArgs, p.Author, p.Author)
-	}
-	if p.Repo != "" {
-		filters = append(filters, "(d.repo_name = ? OR d.repo_did = ?)")
-		filterArgs = append(filterArgs, p.Repo, p.Repo)
-	}
-	if p.Language != "" {
-		filters = append(filters, "d.language = ?")
-		filterArgs = append(filterArgs, p.Language)
-	}
-	if p.From != "" {
-		filters = append(filters, "d.created_at >= ?")
-		filterArgs = append(filterArgs, p.From)
-	}
-	if p.To != "" {
-		filters = append(filters, "d.created_at <= ?")
-		filterArgs = append(filterArgs, p.To)
-	}
-
-	var join string
-	if p.State != "" {
-		join = "JOIN record_state rs ON rs.subject_uri = d.at_uri"
-		filters = append(filters, "rs.state = ?")
-		filterArgs = append(filterArgs, p.State)
-	}
-
-	where := "documents_fts MATCH ? AND d.deleted_at IS NULL"
-	if len(filters) > 0 {
-		where += " AND " + strings.Join(filters, " AND ")
-	}
-
-	countSQL := fmt.Sprintf("SELECT COUNT(*) FROM documents_fts JOIN documents d ON d.id = documents_fts.id %s WHERE %s", join, where)
-	countArgs := append([]any{ftsQuery}, filterArgs...)
-
-	var total int
-	if err := r.db.QueryRowContext(ctx, countSQL, countArgs...).Scan(&total); err != nil {
-		return nil, explainNativeFTSError("count", err)
-	}
-
-	resultsSQL := fmt.Sprintf(`
-		SELECT d.id, d.title, d.summary, d.repo_name, repo_owner.handle, d.author_handle,
-		       d.did, d.at_uri, d.web_url, d.collection, d.record_type, d.created_at, d.updated_at,
-		       -bm25(documents_fts, 0.0, 3.0, 1.0, 1.5, 2.5, 2.0, 1.2) AS score,
-		       snippet(documents_fts, 2, '<mark>', '</mark>', '...', 20) AS body_snippet
-		FROM documents_fts
-		JOIN documents d ON d.id = documents_fts.id
-		LEFT JOIN identity_handles repo_owner ON repo_owner.did = d.repo_did AND repo_owner.is_active = 1
-		%s
-		WHERE %s
-		ORDER BY score DESC
-		LIMIT ? OFFSET ?`, join, where)
-
-	resultsArgs := make([]any, 0, 1+len(filterArgs)+2)
-	resultsArgs = append(resultsArgs, ftsQuery)
-	resultsArgs = append(resultsArgs, filterArgs...)
-	resultsArgs = append(resultsArgs, p.Limit, p.Offset)
-
-	rows, err := r.db.QueryContext(ctx, resultsSQL, resultsArgs...)
-	if err != nil {
-		return nil, explainNativeFTSError("search", err)
-	}
-	defer rows.Close()
-
-	results := make([]Result, 0)
-	for rows.Next() {
-		var res Result
-		var title, summary, repoName, repoOwnerHandle, authorHandle sql.NullString
-		var webURL, createdAt, updatedAt sql.NullString
-		var bodySnippet sql.NullString
-
-		if err := rows.Scan(
-			&res.ID, &title, &summary, &repoName, &repoOwnerHandle, &authorHandle,
-			&res.DID, &res.ATURI, &webURL, &res.Collection, &res.RecordType,
-			&createdAt, &updatedAt, &res.Score, &bodySnippet,
-		); err != nil {
-			return nil, fmt.Errorf("scan: %w", err)
-		}
-		res.Title = title.String
-		res.Summary = summary.String
-		res.RepoName = repoName.String
-		res.RepoOwnerHandle = repoOwnerHandle.String
-		res.AuthorHandle = authorHandle.String
-		res.WebURL = webURL.String
-		res.BodySnippet = bodySnippet.String
-		res.CreatedAt = createdAt.String
-		res.UpdatedAt = updatedAt.String
-		res.MatchedBy = []string{"keyword"}
-		results = append(results, res)
-	}
-	if err := rows.Err(); err != nil {
-		return nil, fmt.Errorf("rows: %w", err)
-	}
-
-	return &Response{
-		Query:   p.Query,
-		Mode:    "keyword",
-		Total:   total,
-		Limit:   p.Limit,
-		Offset:  p.Offset,
-		Results: results,
-	}, nil
-}
-
-func explainNativeFTSError(op string, err error) error {
-	msg := err.Error()
-	if strings.Contains(msg, "no such table: documents_fts") ||
-		strings.Contains(msg, "no such module: fts5") {
-		return fmt.Errorf("%s: SQLite FTS5 is unavailable on this database; ensure the FTS5 migration succeeded and that Turso SQLite extensions are enabled for this database/group: %w", op, err)
-	}
-	return fmt.Errorf("%s: %w", op, err)
+type Repository interface {
+	Ping(ctx context.Context) error
+	Keyword(ctx context.Context, p Params) (*Response, error)
 }
 
-func toFTS5Query(raw string) string {
-	parts := strings.Fields(raw)
-	if len(parts) == 0 {
-		return `""`
-	}
-
-	quoted := make([]string, 0, len(parts))
-	for _, part := range parts {
-		part = strings.ReplaceAll(part, `"`, `""`)
-		quoted = append(quoted, `"`+part+`"`)
+func NewRepository(url string, db *sql.DB) Repository {
+	if strings.HasPrefix(url, "file:") {
+		return &SQLiteRepository{db: db}
 	}
-	return strings.Join(quoted, " OR ")
+	return &PostgresRepository{db: db}
 }

packages/api/internal/search/search_test.go

···
 	"tangled.org/desertthunder.dev/twister/internal/store"
 )
 
-func TestKeywordSearchUsesFTS5Index(t *testing.T) {
+func TestKeywordSearchUsesLegacySQLiteSearchIndex(t *testing.T) {
 	dir := t.TempDir()
 	dbPath := filepath.Join(dir, "search.db")
 	url := "file:" + dbPath
 
-	db, err := store.Open(url, "")
+	db, err := store.Open(url)
 	if err != nil {
 		t.Fatalf("open: %v", err)
 	}
···
 		t.Fatalf("migrate: %v", err)
 	}
 
-	st := store.New(db)
-	repo := search.NewRepository(db)
+	st := store.New(url, db)
+	repo := search.NewRepository(url, db)
 	ctx := context.Background()
 
 	doc := &store.Document{

packages/api/internal/search/sqlite_repository.go

···
+package search
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"strings"
+)
+
+type SQLiteRepository struct {
+	db *sql.DB
+}
+
+func (r *SQLiteRepository) Ping(ctx context.Context) error {
+	return r.db.PingContext(ctx)
+}
+
+func (r *SQLiteRepository) Keyword(ctx context.Context, p Params) (*Response, error) {
+	ftsQuery := toFTS5Query(p.Query)
+
+	var filters []string
+	var filterArgs []any
+
+	if p.Collection != "" {
+		filters = append(filters, "d.collection = ?")
+		filterArgs = append(filterArgs, p.Collection)
+	}
+	if p.Type != "" {
+		filters = append(filters, "d.record_type = ?")
+		filterArgs = append(filterArgs, p.Type)
+	}
+	if p.Author != "" {
+		filters = append(filters, "(d.author_handle = ? OR d.did = ?)")
+		filterArgs = append(filterArgs, p.Author, p.Author)
+	}
+	if p.Repo != "" {
+		filters = append(filters, "(d.repo_name = ? OR d.repo_did = ?)")
+		filterArgs = append(filterArgs, p.Repo, p.Repo)
+	}
+	if p.Language != "" {
+		filters = append(filters, "d.language = ?")
+		filterArgs = append(filterArgs, p.Language)
+	}
+	if p.From != "" {
+		filters = append(filters, "d.created_at >= ?")
+		filterArgs = append(filterArgs, p.From)
+	}
+	if p.To != "" {
+		filters = append(filters, "d.created_at <= ?")
+		filterArgs = append(filterArgs, p.To)
+	}
+
+	var join string
+	if p.State != "" {
+		join = "JOIN record_state rs ON rs.subject_uri = d.at_uri"
+		filters = append(filters, "rs.state = ?")
+		filterArgs = append(filterArgs, p.State)
+	}
+
+	where := "documents_fts MATCH ? AND d.deleted_at IS NULL"
+	if len(filters) > 0 {
+		where += " AND " + strings.Join(filters, " AND ")
+	}
+
+	countSQL := fmt.Sprintf(
+		"SELECT COUNT(*) FROM documents_fts JOIN documents d ON d.id = documents_fts.id %s WHERE %s",
+		join, where,
+	)
+	countArgs := append([]any{ftsQuery}, filterArgs...)
+
+	var total int
+	if err := r.db.QueryRowContext(ctx, countSQL, countArgs...).Scan(&total); err != nil {
+		return nil, explainSQLiteSearchError("count", err)
+	}
+
+	resultsSQL := fmt.Sprintf(`
+		SELECT d.id, d.title, d.summary, d.repo_name, repo_owner.handle, d.author_handle,
+		       d.did, d.at_uri, d.web_url, d.collection, d.record_type, d.created_at, d.updated_at,
+		       -bm25(documents_fts, 0.0, 3.0, 1.0, 1.5, 2.5, 2.0, 1.2) AS score,
+		       snippet(documents_fts, 2, '<mark>', '</mark>', '...', 20) AS body_snippet
+		FROM documents_fts
+		JOIN documents d ON d.id = documents_fts.id
+		LEFT JOIN identity_handles repo_owner ON repo_owner.did = d.repo_did AND repo_owner.is_active = 1
+		%s
+		WHERE %s
+		ORDER BY score DESC
+		LIMIT ? OFFSET ?`, join, where)
+
+	resultsArgs := make([]any, 0, 1+len(filterArgs)+2)
+	resultsArgs = append(resultsArgs, ftsQuery)
+	resultsArgs = append(resultsArgs, filterArgs...)
+	resultsArgs = append(resultsArgs, p.Limit, p.Offset)
+
+	rows, err := r.db.QueryContext(ctx, resultsSQL, resultsArgs...)
+	if err != nil {
+		return nil, explainSQLiteSearchError("search", err)
+	}
+	defer rows.Close()
+
+	results := make([]Result, 0)
+	for rows.Next() {
+		res, err := scanResult(rows)
+		if err != nil {
+			return nil, err
+		}
+		results = append(results, *res)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("rows: %w", err)
+	}
+
+	return &Response{
+		Query:   p.Query,
+		Mode:    "keyword",
+		Total:   total,
+		Limit:   p.Limit,
+		Offset:  p.Offset,
+		Results: results,
+	}, nil
+}
+
+func explainSQLiteSearchError(op string, err error) error {
+	msg := err.Error()
+	if strings.Contains(msg, "no such table: documents_fts") ||
+		strings.Contains(msg, "no such module: fts5") {
+		return fmt.Errorf("%s: SQLite FTS5 is unavailable on this database: %w", op, err)
+	}
+	return fmt.Errorf("%s: %w", op, err)
+}
+
+func toFTS5Query(raw string) string {
+	parts := strings.Fields(raw)
+	if len(parts) == 0 {
+		return `""`
+	}
+
+	quoted := make([]string, 0, len(parts))
+	for _, part := range parts {
+		part = strings.ReplaceAll(part, `"`, `""`)
+		quoted = append(quoted, `"`+part+`"`)
+	}
+	return strings.Join(quoted, " OR ")
+}

packages/api/internal/store/db.go

···
 	"strings"
 	"time"
 
-	_ "github.com/tursodatabase/libsql-client-go/libsql"
+	_ "github.com/jackc/pgx/v5/stdlib"
 	_ "modernc.org/sqlite"
 )
 
-//go:embed migrations/*.sql
+//go:embed migrations/*.sql migrations_postgres/*.sql
 var migrationsFS embed.FS
 
+type Backend string
+
+const (
+	BackendPostgres Backend = "postgres"
+	BackendSQLite   Backend = "sqlite"
+)
+
 type migrationMode struct {
-	allowTursoExtensionSkip bool
-	targetDescription       string
+	backend           Backend
+	targetDescription string
+}
+
+// DetectBackend returns the configured database backend for the given URL.
+func DetectBackend(url string) Backend {
+	if strings.HasPrefix(url, "file:") {
+		return BackendSQLite
+	}
+	return BackendPostgres
 }
 
 // Open establishes a connection to the database.
-// For remote Turso URLs (libsql:// or https://) it uses the libsql-client-go driver.
-// For local file: URLs it uses the pure-Go SQLite driver (no CGo required).
-func Open(url, token string) (*sql.DB, error) {
-	driver, dsn := driverAndDSN(url, token)
+func Open(url string) (*sql.DB, error) {
+	driver, dsn := driverAndDSN(url)
 	db, err := sql.Open(driver, dsn)
 	if err != nil {
 		return nil, fmt.Errorf("open db: %w", err)
 	}
-	if strings.HasPrefix(url, "file:") {
+	switch DetectBackend(url) {
+	case BackendSQLite:
 		if err := configureLocalSQLite(db); err != nil {
 			db.Close()
 			return nil, err
 		}
+	case BackendPostgres:
+		configurePostgresPool(db)
 	}
 	if err := db.Ping(); err != nil {
 		db.Close()
···
 }
 
 func configureLocalSQLite(db *sql.DB) error {
-	// Busy timeout gives the writer a window to wait instead of failing fast with "database is locked".
 	if _, err := db.Exec(`PRAGMA busy_timeout = 5000`); err != nil {
 		return fmt.Errorf("configure sqlite busy_timeout: %w", err)
 	}
-	// WAL mode allows concurrent readers with a writer and is the default for multi-process local dev.
 	if _, err := db.Exec(`PRAGMA journal_mode = WAL`); err != nil {
 		return fmt.Errorf("configure sqlite wal mode: %w", err)
 	}
···
 	return nil
 }
 
-// driverAndDSN returns the sql driver name and DSN for the given URL.
-// file: URLs use the pure-Go "sqlite" driver; all others use "libsql".
-func driverAndDSN(url, token string) (driver, dsn string) {
+func configurePostgresPool(db *sql.DB) {
+	db.SetMaxOpenConns(10)
+	db.SetMaxIdleConns(10)
+	db.SetConnMaxLifetime(30 * time.Minute)
+	db.SetConnMaxIdleTime(5 * time.Minute)
+}
+
+func driverAndDSN(url string) (driver, dsn string) {
 	if strings.HasPrefix(url, "file:") {
 		return "sqlite", strings.TrimPrefix(url, "file:")
 	}
-	if token == "" || strings.Contains(url, "?") {
-		return "libsql", url
-	}
-	return "libsql", url + "?authToken=" + token
+	return "pgx", url
 }
 
-// Migrate runs all embedded SQL migration files in order, skipping any that
-// have already been applied. Applied filenames are recorded in the
-// schema_migrations table so re-runs are idempotent.
+// Migrate runs embedded SQL migrations for the selected backend.
 func Migrate(db *sql.DB, url string) error {
+	switch DetectBackend(url) {
+	case BackendSQLite:
+		return migrateSQLite(db, url)
+	default:
+		return migratePostgres(db)
+	}
+}
+
+func migrateSQLite(db *sql.DB, url string) error {
 	if _, err := db.Exec(`CREATE TABLE IF NOT EXISTS schema_migrations (
 		filename   TEXT PRIMARY KEY,
 		applied_at TEXT NOT NULL
···
 		return fmt.Errorf("create schema_migrations table: %w", err)
 	}
 
-	if err := backfillMigrationHistory(db); err != nil {
+	if err := backfillSQLiteMigrationHistory(db); err != nil {
 		return fmt.Errorf("backfill migration history: %w", err)
 	}
 
 	mode := migrationMode{
-		allowTursoExtensionSkip: strings.HasPrefix(url, "file:"),
-		targetDescription:       migrationTargetDescription(url),
+		backend:           BackendSQLite,
+		targetDescription: migrationTargetDescription(url),
 	}
-	entries, err := migrationsFS.ReadDir("migrations")
+	return runMigrations(db, "migrations", "?", mode)
+}
+
+func migratePostgres(db *sql.DB) error {
+	if _, err := db.Exec(`CREATE TABLE IF NOT EXISTS schema_migrations (
+		filename   TEXT PRIMARY KEY,
+		applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+	)`); err != nil {
+		return fmt.Errorf("create schema_migrations table: %w", err)
+	}
+
+	mode := migrationMode{
+		backend:           BackendPostgres,
+		targetDescription: "postgresql",
+	}
+	return runMigrations(db, "migrations_postgres", "$", mode)
+}
+
+func runMigrations(db *sql.DB, dir, placeholderPrefix string, mode migrationMode) error {
+	entries, err := migrationsFS.ReadDir(dir)
 	if err != nil {
 		return fmt.Errorf("read migrations dir: %w", err)
 	}
···
 		if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".sql") {
 			continue
 		}
+
 		var already int
-		_ = db.QueryRow(`SELECT COUNT(*) FROM schema_migrations WHERE filename = ?`, entry.Name()).Scan(&already)
+		query := `SELECT COUNT(*) FROM schema_migrations WHERE filename = ?`
+		args := []any{entry.Name()}
+		if placeholderPrefix == "$" {
+			query = `SELECT COUNT(*) FROM schema_migrations WHERE filename = $1`
+		}
+		if err := db.QueryRow(query, args...).Scan(&already); err != nil {
+			return fmt.Errorf("check migration %s: %w", entry.Name(), err)
+		}
 		if already > 0 {
 			slog.Debug("migration already applied, skipping", "file", entry.Name())
 			continue
 		}
-		data, err := migrationsFS.ReadFile("migrations/" + entry.Name())
+
+		data, err := migrationsFS.ReadFile(dir + "/" + entry.Name())
 		if err != nil {
 			return fmt.Errorf("read migration %s: %w", entry.Name(), err)
 		}
 		if err := execMigration(db, entry.Name(), string(data), mode); err != nil {
 			return err
 		}
-		if _, err := db.Exec(
-			`INSERT INTO schema_migrations (filename, applied_at) VALUES (?, datetime('now'))`,
-			entry.Name(),
-		); err != nil {
+
+		insert := `INSERT INTO schema_migrations (filename, applied_at) VALUES (?, datetime('now'))`
+		if placeholderPrefix == "$" {
+			insert = `INSERT INTO schema_migrations (filename) VALUES ($1)`
+		}
+		if _, err := db.Exec(insert, entry.Name()); err != nil {
 			return fmt.Errorf("record migration %s: %w", entry.Name(), err)
 		}
 		slog.Info("migration applied", "file", entry.Name())
···
 	return nil
 }
 
-// backfillMigrationHistory records already-applied migrations for databases
-// that pre-date the schema_migrations tracking table. It is a no-op if the
-// table already has any entries (i.e. tracking was already in place).
-func backfillMigrationHistory(db *sql.DB) error {
+func backfillSQLiteMigrationHistory(db *sql.DB) error {
 	var count int
 	if err := db.QueryRow(`SELECT COUNT(*) FROM schema_migrations`).Scan(&count); err != nil || count > 0 {
 		return nil
···
 	if sqliteTableExists(db, "identity_handles") {
 		mark("002_identity_handles.sql")
 	}
-
 	if sqliteTableExists(db, "documents_fts") {
-		mark("003_documents_fts.sql")
+		mark("003_documents_fts5.sql")
 	}
-
 	if sqliteColumnExists(db, "documents", "web_url") {
 		mark("004_web_url.sql")
 	}
-
 	return nil
 }
 
···
 func execMigration(db *sql.DB, name, content string, mode migrationMode) error {
 	for _, stmt := range splitStatements(content) {
 		if _, err := db.Exec(stmt); err != nil {
-			upper := strings.ToUpper(stmt)
-			if strings.Contains(upper, "LIBSQL_VECTOR_IDX") {
-				slog.Debug("migration: skipping unsupported vector index DDL",
-					"migration", name,
-				)
-				continue
-			}
-			if strings.Contains(upper, "CREATE VIRTUAL TABLE") && strings.Contains(upper, "USING FTS5") {
-				return fmt.Errorf(
-					"migration %s: SQLite FTS5 statement failed on %s: %w\nstatement: %s\nhint: this app uses SQLite FTS5 on Turso Cloud. Enable SQLite extensions for the Turso group/database before rerunning the service",
-					name, mode.targetDescription, err, stmt,
-				)
+			if mode.backend == BackendSQLite {
+				upper := strings.ToUpper(stmt)
+				if strings.Contains(upper, "LIBSQL_VECTOR_IDX") {
+					slog.Debug("migration: skipping unsupported vector index DDL",
+						"migration", name,
+					)
+					continue
+				}
+				if strings.Contains(upper, "CREATE VIRTUAL TABLE") &&
+					strings.Contains(upper, "USING FTS5") {
+					return fmt.Errorf(
+						"migration %s: SQLite FTS5 statement failed on %s: %w\nstatement: %s",
+						name, mode.targetDescription, err, stmt,
+					)
+				}
 			}
 			return fmt.Errorf("migration %s: exec failed: %w\nstatement: %s", name, err, stmt)
 		}
···
 }
 
 func migrationTargetDescription(url string) string {
-	switch {
-	case strings.HasPrefix(url, "file:"):
+	switch DetectBackend(url) {
+	case BackendSQLite:
 		return "local SQLite"
-	case strings.HasPrefix(url, "libsql://"), strings.HasPrefix(url, "https://"):
-		return "remote Turso/libSQL"
 	default:
-		return "database"
+		return "postgresql"
 	}
 }
 

packages/api/internal/store/db_test.go

···
 	_ "modernc.org/sqlite"
 )
 
-func TestExecMigrationSkipsTursoExtensionDDLForLocalSQLite(t *testing.T) {
+func TestExecMigrationRunsLegacySQLiteFTSForLocalFallback(t *testing.T) {
 	db, err := sql.Open("sqlite", ":memory:")
 	if err != nil {
 		t.Fatalf("open sqlite: %v", err)
···
 	t.Cleanup(func() { _ = db.Close() })
 
 	err = execMigration(db, "003_documents_fts5.sql", "CREATE VIRTUAL TABLE documents_fts USING fts5(title);", migrationMode{
-		allowTursoExtensionSkip: true,
-		targetDescription:       "local SQLite",
+		backend:           BackendSQLite,
+		targetDescription: "local SQLite",
 	})
 	if err != nil {
 		t.Fatalf("expected local SQLite migration to create FTS5 table: %v", err)
···
 	t.Cleanup(func() { _ = db.Close() })
 
 	err = execMigration(db, "003_documents_fts5.sql", "CREATE VIRTUAL TABLE documents_fts USING fts5(", migrationMode{
-		allowTursoExtensionSkip: false,
-		targetDescription:       "remote Turso/libSQL",
+		backend:           BackendSQLite,
+		targetDescription: "local SQLite",
 	})
 	if err == nil {
-		t.Fatal("expected remote migration to fail when FTS5 is unavailable")
+		t.Fatal("expected SQLite migration to fail when FTS5 is unavailable")
 	}
-	if !strings.Contains(err.Error(), "uses SQLite FTS5 on Turso Cloud") {
+	if !strings.Contains(err.Error(), "SQLite FTS5 statement failed") {
 		t.Fatalf("unexpected error: %v", err)
 	}
 }
 
 func TestOpenLocalSQLiteAppliesPragmasAndPoolLimits(t *testing.T) {
 	path := filepath.Join(t.TempDir(), "local.db")
-	db, err := Open("file:"+path, "")
+	db, err := Open("file:" + path)
 	if err != nil {
 		t.Fatalf("open local sqlite: %v", err)
 	}

packages/api/internal/store/indexing_audit.go

···
 	"time"
 )
 
-func (s *SQLStore) AppendIndexingAudit(ctx context.Context, input IndexingAuditInput) error {
+func (s *SQLiteStore) AppendIndexingAudit(ctx context.Context, input IndexingAuditInput) error {
 	now := time.Now().UTC().Format(time.RFC3339)
 	_, err := s.db.ExecContext(ctx, `
 		INSERT INTO indexing_audit (
···
 	return nil
 }
 
-func (s *SQLStore) ListIndexingAudit(
+func (s *SQLiteStore) ListIndexingAudit(
 	ctx context.Context, filter IndexingAuditFilter,
 ) ([]*IndexingAuditEntry, error) {
 	query := `

packages/api/internal/store/indexing_jobs.go

···
 	"time"
 )
 
-func (s *SQLStore) GetIndexingJob(ctx context.Context, documentID string) (*IndexingJob, error) {
+func (s *SQLiteStore) GetIndexingJob(ctx context.Context, documentID string) (*IndexingJob, error) {
 	row := s.db.QueryRowContext(ctx, `
 		SELECT document_id, did, collection, rkey, cid, record_json, source,
 		       attempts, status, COALESCE(last_error, ''), scheduled_at, updated_at,
···
 	return job, nil
 }
 
-func (s *SQLStore) EnqueueIndexingJob(ctx context.Context, input IndexingJobInput) error {
+func (s *SQLiteStore) EnqueueIndexingJob(ctx context.Context, input IndexingJobInput) error {
 	now := time.Now().UTC().Format(time.RFC3339)
 	source := strings.TrimSpace(input.Source)
 	if source == "" {
···
 	return nil
 }
 
-func (s *SQLStore) ClaimIndexingJob(
+func (s *SQLiteStore) ClaimIndexingJob(
 	ctx context.Context, workerID string, leaseUntil string,
 ) (*IndexingJob, error) {
 	now := time.Now().UTC().Format(time.RFC3339)
···
 	return job, nil
 }
 
-func (s *SQLStore) CompleteIndexingJob(ctx context.Context, documentID string) error {
+func (s *SQLiteStore) CompleteIndexingJob(ctx context.Context, documentID string) error {
 	now := time.Now().UTC().Format(time.RFC3339)
 	_, err := s.db.ExecContext(ctx, `
 		UPDATE indexing_jobs
···
 	return nil
 }
 
-func (s *SQLStore) RetryIndexingJob(
+func (s *SQLiteStore) RetryIndexingJob(
 	ctx context.Context, documentID string, nextScheduledAt string, lastError string,
 ) error {
 	now := time.Now().UTC().Format(time.RFC3339)
···
 	return nil
 }
 
-func (s *SQLStore) FailIndexingJob(
+func (s *SQLiteStore) FailIndexingJob(
 	ctx context.Context, documentID string, status string, lastError string,
 ) error {
 	now := time.Now().UTC().Format(time.RFC3339)
···
 	return nil
 }
 
-func (s *SQLStore) ListIndexingJobs(
+func (s *SQLiteStore) ListIndexingJobs(
 	ctx context.Context, filter IndexingJobFilter,
 ) ([]*IndexingJob, error) {
 	query := `
···
 	return jobs, nil
 }
 
-func (s *SQLStore) GetIndexingJobStats(ctx context.Context) (*IndexingJobStats, error) {
+func (s *SQLiteStore) GetIndexingJobStats(ctx context.Context) (*IndexingJobStats, error) {
 	row := s.db.QueryRowContext(ctx, `
 		SELECT
 			COUNT(*) FILTER (WHERE status = ?),

packages/api/internal/store/migrations_postgres/001_initial.sql

···
+CREATE TABLE IF NOT EXISTS documents (
+    id            TEXT PRIMARY KEY,
+    did           TEXT NOT NULL,
+    collection    TEXT NOT NULL,
+    rkey          TEXT NOT NULL,
+    at_uri        TEXT NOT NULL,
+    cid           TEXT NOT NULL,
+    record_type   TEXT NOT NULL,
+    title         TEXT,
+    body          TEXT,
+    summary       TEXT,
+    repo_did      TEXT,
+    repo_name     TEXT,
+    author_handle TEXT,
+    tags_json     TEXT,
+    language      TEXT,
+    created_at    TEXT,
+    updated_at    TEXT,
+    indexed_at    TEXT NOT NULL,
+    web_url       TEXT DEFAULT '',
+    deleted_at    TEXT,
+    search_vector TSVECTOR GENERATED ALWAYS AS (
+        setweight(to_tsvector('simple', COALESCE(title, '')), 'A') ||
+        setweight(to_tsvector('simple', COALESCE(author_handle, '')), 'A') ||
+        setweight(to_tsvector('simple', COALESCE(repo_name, '')), 'B') ||
+        setweight(to_tsvector('simple', COALESCE(summary, '')), 'B') ||
+        setweight(to_tsvector('simple', COALESCE(body, '')), 'C') ||
+        setweight(to_tsvector('simple', COALESCE(tags_json, '')), 'D')
+    ) STORED
+);
+
+CREATE INDEX IF NOT EXISTS idx_documents_did ON documents(did);
+CREATE INDEX IF NOT EXISTS idx_documents_collection ON documents(collection);
+CREATE INDEX IF NOT EXISTS idx_documents_record_type ON documents(record_type);
+CREATE INDEX IF NOT EXISTS idx_documents_repo_did ON documents(repo_did);
+CREATE INDEX IF NOT EXISTS idx_documents_created_at ON documents(created_at);
+CREATE INDEX IF NOT EXISTS idx_documents_deleted_at ON documents(deleted_at);
+CREATE INDEX IF NOT EXISTS idx_documents_search_vector ON documents USING GIN(search_vector);
+
+CREATE TABLE IF NOT EXISTS sync_state (
+    consumer_name   TEXT PRIMARY KEY,
+    cursor          TEXT NOT NULL,
+    high_water_mark TEXT,
+    updated_at      TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS identity_handles (
+    did        TEXT PRIMARY KEY,
+    handle     TEXT NOT NULL,
+    is_active  BOOLEAN NOT NULL DEFAULT TRUE,
+    status     TEXT,
+    updated_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_identity_handles_handle ON identity_handles(handle);
+
+CREATE TABLE IF NOT EXISTS record_state (
+    subject_uri TEXT PRIMARY KEY,
+    state       TEXT NOT NULL,
+    updated_at  TEXT NOT NULL
+);

packages/api/internal/store/migrations_postgres/002_indexing_jobs.sql

···
+CREATE TABLE IF NOT EXISTS indexing_jobs (
+    document_id      TEXT PRIMARY KEY,
+    did              TEXT NOT NULL,
+    collection       TEXT NOT NULL,
+    rkey             TEXT NOT NULL,
+    cid              TEXT NOT NULL,
+    record_json      TEXT NOT NULL,
+    source           TEXT NOT NULL DEFAULT 'read_through',
+    status           TEXT NOT NULL,
+    attempts         INTEGER NOT NULL DEFAULT 0,
+    last_error       TEXT,
+    scheduled_at     TEXT NOT NULL,
+    updated_at       TEXT NOT NULL,
+    lease_owner      TEXT DEFAULT '',
+    lease_expires_at TEXT DEFAULT '',
+    completed_at     TEXT DEFAULT ''
+);
+
+CREATE INDEX IF NOT EXISTS idx_indexing_jobs_status_scheduled
+    ON indexing_jobs(status, scheduled_at, updated_at);
+
+CREATE INDEX IF NOT EXISTS idx_indexing_jobs_claim
+    ON indexing_jobs(status, scheduled_at, lease_expires_at, updated_at);

packages/api/internal/store/migrations_postgres/003_jetstream_events.sql

···
+CREATE TABLE IF NOT EXISTS jetstream_events (
+    id          BIGSERIAL PRIMARY KEY,
+    time_us     BIGINT NOT NULL,
+    did         TEXT NOT NULL,
+    kind        TEXT NOT NULL,
+    collection  TEXT,
+    rkey        TEXT,
+    operation   TEXT,
+    payload     TEXT NOT NULL,
+    received_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_jetstream_events_time_us
+    ON jetstream_events(time_us DESC);

packages/api/internal/store/migrations_postgres/004_indexing_audit.sql

···
+CREATE TABLE IF NOT EXISTS indexing_audit (
+    id          BIGSERIAL PRIMARY KEY,
+    source      TEXT NOT NULL,
+    document_id TEXT NOT NULL,
+    collection  TEXT NOT NULL,
+    cid         TEXT NOT NULL,
+    decision    TEXT NOT NULL,
+    attempt     INTEGER NOT NULL DEFAULT 0,
+    error       TEXT,
+    created_at  TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_indexing_audit_created
+    ON indexing_audit(created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_indexing_audit_document
+    ON indexing_audit(document_id, created_at DESC);

packages/api/internal/store/postgres_store.go

···
+package store
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+)
+
+type PostgresStore struct {
+	db *sql.DB
+}
+
+type pgArgs struct {
+	args []any
+}
+
+func newPGArgs(initial ...any) *pgArgs {
+	return &pgArgs{args: append([]any{}, initial...)}
+}
+
+func (p *pgArgs) Add(value any) string {
+	p.args = append(p.args, value)
+	return fmt.Sprintf("$%d", len(p.args))
+}
+
+func (p *pgArgs) Values() []any {
+	return p.args
+}
+
+func (s *PostgresStore) UpsertDocument(ctx context.Context, doc *Document) error {
+	doc.IndexedAt = time.Now().UTC().Format(time.RFC3339)
+
+	_, err := s.db.ExecContext(ctx, `
+		INSERT INTO documents (
+			id, did, collection, rkey, at_uri, cid, record_type,
+			title, body, summary, repo_did, repo_name, author_handle,
+			tags_json, language, created_at, updated_at, indexed_at, web_url, deleted_at
+		) VALUES (
+			$1, $2, $3, $4, $5, $6, $7,
+			$8, $9, $10, $11, $12, $13,
+			$14, $15, $16, $17, $18, $19, $20
+		)
+		ON CONFLICT(id) DO UPDATE SET
+			did = excluded.did,
+			collection = excluded.collection,
+			rkey = excluded.rkey,
+			at_uri = excluded.at_uri,
+			cid = excluded.cid,
+			record_type = excluded.record_type,
+			title = excluded.title,
+			body = excluded.body,
+			summary = excluded.summary,
+			repo_did = excluded.repo_did,
+			repo_name = excluded.repo_name,
+			author_handle = excluded.author_handle,
+			tags_json = excluded.tags_json,
+			language = excluded.language,
+			created_at = excluded.created_at,
+			updated_at = excluded.updated_at,
+			indexed_at = excluded.indexed_at,
+			web_url = excluded.web_url,
+			deleted_at = excluded.deleted_at`,
+		doc.ID, doc.DID, doc.Collection, doc.RKey, doc.ATURI, doc.CID, doc.RecordType,
+		doc.Title, doc.Body, doc.Summary, doc.RepoDID, doc.RepoName, doc.AuthorHandle,
+		doc.TagsJSON, doc.Language, doc.CreatedAt, doc.UpdatedAt, doc.IndexedAt,
+		doc.WebURL, nullableStr(doc.DeletedAt),
+	)
+	if err != nil {
+		return fmt.Errorf("upsert document: %w", err)
+	}
+	return nil
+}
+
+func (s *PostgresStore) ListDocuments(ctx context.Context, filter DocumentFilter) ([]*Document, error) {
+	query := `SELECT id, did, collection, rkey, at_uri, cid, record_type,
+		title, body, summary, repo_did, repo_name, author_handle,
+		tags_json, language, created_at, updated_at, indexed_at, web_url, deleted_at
+		FROM documents WHERE deleted_at IS NULL`
+	args := newPGArgs()
+
+	if filter.DocumentID != "" {
+		query += " AND id = " + args.Add(filter.DocumentID)
+	}
+	if filter.Collection != "" {
+		query += " AND collection = " + args.Add(filter.Collection)
+	}
+	if filter.DID != "" {
+		query += " AND did = " + args.Add(filter.DID)
+	}
+
+	rows, err := s.db.QueryContext(ctx, query, args.Values()...)
+	if err != nil {
+		return nil, fmt.Errorf("list documents: %w", err)
+	}
+	defer rows.Close()
+
+	var docs []*Document
+	for rows.Next() {
+		doc := &Document{}
+		var (
+			title, body, summary, repoDID, repoName, authorHandle       sql.NullString
+			tagsJSON, language, createdAt, updatedAt, webURL, deletedAt sql.NullString
+		)
+		if err := rows.Scan(
+			&doc.ID, &doc.DID, &doc.Collection, &doc.RKey, &doc.ATURI, &doc.CID, &doc.RecordType,
+			&title, &body, &summary, &repoDID, &repoName, &authorHandle,
+			&tagsJSON, &language, &createdAt, &updatedAt, &doc.IndexedAt, &webURL, &deletedAt,
+		); err != nil {
+			return nil, fmt.Errorf("scan document: %w", err)
+		}
+		doc.Title = title.String
+		doc.Body = body.String
+		doc.Summary = summary.String
+		doc.RepoDID = repoDID.String
+		doc.RepoName = repoName.String
+		doc.AuthorHandle = authorHandle.String
+		doc.TagsJSON = tagsJSON.String
+		doc.Language = language.String
+		doc.CreatedAt = createdAt.String
+		doc.UpdatedAt = updatedAt.String
+		doc.WebURL = webURL.String
+		doc.DeletedAt = deletedAt.String
+		docs = append(docs, doc)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("iterate documents: %w", err)
+	}
+	return docs, nil
+}
+
+func (s *PostgresStore) OptimizeSearchIndex(_ context.Context) error {
+	return nil
+}
+
+func (s *PostgresStore) GetDocument(ctx context.Context, id string) (*Document, error) {
+	row := s.db.QueryRowContext(ctx, `
+		SELECT id, did, collection, rkey, at_uri, cid, record_type,
+		       title, body, summary, repo_did, repo_name, author_handle,
+		       tags_json, language, created_at, updated_at, indexed_at, web_url, deleted_at
+		FROM documents WHERE id = $1`, id)
+
+	doc, err := scanDocument(row)
+	if errors.Is(err, sql.ErrNoRows) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("get document: %w", err)
+	}
+	return doc, nil
+}
+
+func (s *PostgresStore) MarkDeleted(ctx context.Context, id string) error {
+	now := time.Now().UTC().Format(time.RFC3339)
+	_, err := s.db.ExecContext(ctx, `UPDATE documents SET deleted_at = $1 WHERE id = $2`, now, id)
+	if err != nil {
+		return fmt.Errorf("mark deleted: %w", err)
+	}
+	return nil
+}
+
+func (s *PostgresStore) GetSyncState(ctx context.Context, consumer string) (*SyncState, error) {
+	row := s.db.QueryRowContext(ctx, `
+		SELECT consumer_name, cursor, COALESCE(high_water_mark, ''), updated_at
+		FROM sync_state WHERE consumer_name = $1`, consumer)
+
+	ss := &SyncState{}
+	err := row.Scan(&ss.ConsumerName, &ss.Cursor, &ss.HighWaterMark, &ss.UpdatedAt)
+	if errors.Is(err, sql.ErrNoRows) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("get sync state: %w", err)
+	}
+	return ss, nil
+}
+
+func (s *PostgresStore) SetSyncState(ctx context.Context, consumer string, cursor string) error {
+	now := time.Now().UTC().Format(time.RFC3339)
+	_, err := s.db.ExecContext(ctx, `
+		INSERT INTO sync_state (consumer_name, cursor, updated_at) VALUES ($1, $2, $3)
+		ON CONFLICT(consumer_name) DO UPDATE SET
+			cursor = excluded.cursor,
+			updated_at = excluded.updated_at`,
+		consumer, cursor, now,
+	)
+	if err != nil {
+		return fmt.Errorf("set sync state: %w", err)
+	}
+	return nil
+}
+
+func (s *PostgresStore) UpdateRecordState(ctx context.Context, subjectURI string, state string) error {
+	now := time.Now().UTC().Format(time.RFC3339)
+	_, err := s.db.ExecContext(ctx, `
+		INSERT INTO record_state (subject_uri, state, updated_at) VALUES ($1, $2, $3)
+		ON CONFLICT(subject_uri) DO UPDATE SET
+			state = excluded.state,
+			updated_at = excluded.updated_at`,
+		subjectURI, state, now,
+	)
+	if err != nil {
+		return fmt.Errorf("update record state: %w", err)
+	}
+	return nil
+}
+
+func (s *PostgresStore) UpsertIdentityHandle(
+	ctx context.Context, did, handle string, isActive bool, status string,
+) error {
+	now := time.Now().UTC().Format(time.RFC3339)
+	_, err := s.db.ExecContext(ctx, `
+		INSERT INTO identity_handles (did, handle, is_active, status, updated_at)
+		VALUES ($1, $2, $3, $4, $5)
+		ON CONFLICT(did) DO UPDATE SET
+			handle = excluded.handle,
+			is_active = excluded.is_active,
+			status = excluded.status,
+			updated_at = excluded.updated_at`,
+		did, handle, isActive, nullableStr(status), now,
+	)
+	if err != nil {
+		return fmt.Errorf("upsert identity handle: %w", err)
+	}
+	return nil
+}
+
+func (s *PostgresStore) GetIdentityHandle(ctx context.Context, did string) (string, error) {
+	var handle sql.NullString
+	err := s.db.QueryRowContext(ctx, `SELECT handle FROM identity_handles WHERE did = $1`, did).Scan(&handle)
+	if errors.Is(err, sql.ErrNoRows) {
+		return "", nil
+	}
+	if err != nil {
+		return "", fmt.Errorf("get identity handle: %w", err)
+	}
+	return handle.String, nil
+}
+
+func (s *PostgresStore) GetIndexingJob(ctx context.Context, documentID string) (*IndexingJob, error) {
+	row := s.db.QueryRowContext(ctx, `
+		SELECT document_id, did, collection, rkey, cid, record_json, source,
+		       attempts, status, COALESCE(last_error, ''), scheduled_at, updated_at,
+		       COALESCE(lease_owner, ''), COALESCE(lease_expires_at, ''),
+		       COALESCE(completed_at, '')
+		FROM indexing_jobs
+		WHERE document_id = $1`, documentID)
+
+	job, err := scanIndexingJob(row)
+	if errors.Is(err, sql.ErrNoRows) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("get indexing job: %w", err)
+	}
+	return job, nil
+}
+
+func (s *PostgresStore) EnqueueIndexingJob(ctx context.Context, input IndexingJobInput) error {
+	now := time.Now().UTC().Format(time.RFC3339)
+	source := strings.TrimSpace(input.Source)
+	if source == "" {
+		source = IndexSourceReadThrough
+	}
+
+	_, err := s.db.ExecContext(ctx, `
+		INSERT INTO indexing_jobs (
+			document_id, did, collection, rkey, cid, record_json, source,
+			status, attempts, last_error, scheduled_at, updated_at,
+			lease_owner, lease_expires_at, completed_at
+		) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, 0, NULL, $9, $10, '', '', '')
+		ON CONFLICT(document_id) DO UPDATE SET
+			did = excluded.did,
+			collection = excluded.collection,
+			rkey = excluded.rkey,
+			cid = excluded.cid,
+			record_json = excluded.record_json,
+			source = excluded.source,
+			status = excluded.status,
+			last_error = NULL,
+			scheduled_at = excluded.scheduled_at,
+			updated_at = excluded.updated_at,
+			lease_owner = '',
+			lease_expires_at = '',
+			completed_at = ''`,
+		input.DocumentID, input.DID, input.Collection, input.RKey, input.CID,
+		input.RecordJSON, source, IndexingJobPending, now, now,
+	)
+	if err != nil {
+		return fmt.Errorf("enqueue indexing job: %w", err)
+	}
+	return nil
+}
+
+func (s *PostgresStore) ClaimIndexingJob(
+	ctx context.Context, workerID string, leaseUntil string,
+) (*IndexingJob, error) {
+	now := time.Now().UTC().Format(time.RFC3339)
+	tx, err := s.db.BeginTx(ctx, nil)
+	if err != nil {
+		return nil, fmt.Errorf("begin claim tx: %w", err)
+	}
+	defer tx.Rollback()
+
+	row := tx.QueryRowContext(ctx, `
+		WITH candidate AS (
+			SELECT document_id
+			FROM indexing_jobs
+			WHERE (
+				status = $1
+				AND scheduled_at::timestamptz <= $2::timestamptz
+			) OR (
+				status = $3
+				AND lease_expires_at IS NOT NULL
+				AND lease_expires_at != ''
+				AND lease_expires_at::timestamptz <= $2::timestamptz
+			)
+			ORDER BY scheduled_at::timestamptz ASC, updated_at::timestamptz ASC
+			FOR UPDATE SKIP LOCKED
+			LIMIT 1
+		)
+		UPDATE indexing_jobs jobs
+		SET status = $4, updated_at = $5, lease_owner = $6, lease_expires_at = $7
+		FROM candidate
+		WHERE jobs.document_id = candidate.document_id
+		RETURNING jobs.document_id, jobs.did, jobs.collection, jobs.rkey, jobs.cid,
+		          jobs.record_json, jobs.source, jobs.attempts, jobs.status,
+		          COALESCE(jobs.last_error, ''), jobs.scheduled_at, jobs.updated_at,
+		          COALESCE(jobs.lease_owner, ''), COALESCE(jobs.lease_expires_at, ''),
+		          COALESCE(jobs.completed_at, '')`,
+		IndexingJobPending, now, IndexingJobProcessing, IndexingJobProcessing,
+		now, workerID, leaseUntil,
+	)
+
+	job, err := scanIndexingJob(row)
+	if errors.Is(err, sql.ErrNoRows) {
+		if err := tx.Commit(); err != nil {
+			return nil, fmt.Errorf("commit empty claim tx: %w", err)
+		}
+		return nil, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("claim indexing job: %w", err)
+	}
+	if err := tx.Commit(); err != nil {
+		return nil, fmt.Errorf("commit claim tx: %w", err)
+	}
+	return job, nil
+}
+
+func (s *PostgresStore) CompleteIndexingJob(ctx context.Context, documentID string) error {
+	now := time.Now().UTC().Format(time.RFC3339)
+	_, err := s.db.ExecContext(ctx, `
+		UPDATE indexing_jobs
+		SET status = $1, updated_at = $2, completed_at = $3,
+		    lease_owner = '', lease_expires_at = '', last_error = NULL
+		WHERE document_id = $4`,
+		IndexingJobCompleted, now, now, documentID,
+	)
+	if err != nil {
+		return fmt.Errorf("complete indexing job: %w", err)
+	}
+	return nil
+}
+
+func (s *PostgresStore) RetryIndexingJob(
+	ctx context.Context, documentID string, nextScheduledAt string, lastError string,
+) error {
+	now := time.Now().UTC().Format(time.RFC3339)
+	_, err := s.db.ExecContext(ctx, `
+		UPDATE indexing_jobs
+		SET status = $1, attempts = attempts + 1, last_error = $2, scheduled_at = $3,
+		    updated_at = $4, lease_owner = '', lease_expires_at = ''
+		WHERE document_id = $5`,
+		IndexingJobPending, lastError, nextScheduledAt, now, documentID,
+	)
+	if err != nil {
+		return fmt.Errorf("retry indexing job: %w", err)
+	}
+	return nil
+}
+
+func (s *PostgresStore) FailIndexingJob(
+	ctx context.Context, documentID string, status string, lastError string,
+) error {
+	now := time.Now().UTC().Format(time.RFC3339)
+	_, err := s.db.ExecContext(ctx, `
+		UPDATE indexing_jobs
+		SET status = $1, attempts = attempts + 1, last_error = $2, updated_at = $3,
+		    lease_owner = '', lease_expires_at = ''
+		WHERE document_id = $4`,
+		status, lastError, now, documentID,
+	)
+	if err != nil {
+		return fmt.Errorf("fail indexing job: %w", err)
+	}
+	return nil
+}
+
+func (s *PostgresStore) ListIndexingJobs(
+	ctx context.Context, filter IndexingJobFilter,
+) ([]*IndexingJob, error) {
+	query := `
+		SELECT document_id, did, collection, rkey, cid, record_json, source,
+		       attempts, status, COALESCE(last_error, ''), scheduled_at, updated_at,
+		       COALESCE(lease_owner, ''), COALESCE(lease_expires_at, ''),
+		       COALESCE(completed_at, '')
+		FROM indexing_jobs
+		WHERE 1 = 1`
+	args := newPGArgs()
+
+	if filter.DocumentID != "" {
+		query += " AND document_id = " + args.Add(filter.DocumentID)
+	}
+	if filter.Status != "" {
+		query += " AND status = " + args.Add(filter.Status)
+	}
+	if filter.Source != "" {
+		query += " AND source = " + args.Add(filter.Source)
+	}
+
+	query += " ORDER BY updated_at::timestamptz DESC"
+	limit := filter.Limit
+	if limit <= 0 {
+		limit = 50
+	}
+	query += " LIMIT " + args.Add(limit)
+	if filter.Offset > 0 {
+		query += " OFFSET " + args.Add(filter.Offset)
+	}
+
+	rows, err := s.db.QueryContext(ctx, query, args.Values()...)
+	if err != nil {
+		return nil, fmt.Errorf("list indexing jobs: %w", err)
+	}
+	defer rows.Close()
+
+	var jobs []*IndexingJob
+	for rows.Next() {
+		job, err := scanIndexingJob(rows)
+		if err != nil {
+			return nil, fmt.Errorf("scan indexing job: %w", err)
+		}
+		jobs = append(jobs, job)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("iterate indexing jobs: %w", err)
+	}
+	return jobs, nil
+}
+
+func (s *PostgresStore) GetIndexingJobStats(ctx context.Context) (*IndexingJobStats, error) {
+	row := s.db.QueryRowContext(ctx, `
+		SELECT
+			COUNT(*) FILTER (WHERE status = $1),
+			COUNT(*) FILTER (WHERE status = $2),
+			COUNT(*) FILTER (WHERE status = $3),
+			COUNT(*) FILTER (WHERE status = $4),
+			COUNT(*) FILTER (WHERE status = $5),
+			COALESCE(MIN(CASE WHEN status = $1 THEN scheduled_at END), ''),
+			COALESCE(MIN(CASE WHEN status = $2 THEN updated_at END), ''),
+			COALESCE(MAX(completed_at), ''),
+			COALESCE(MAX(updated_at), '')
+		FROM indexing_jobs`,
+		IndexingJobPending, IndexingJobProcessing, IndexingJobCompleted,
+		IndexingJobFailed, IndexingJobDeadLetter,
+	)
+
+	stats := &IndexingJobStats{}
+	err := row.Scan(
+		&stats.Pending, &stats.Processing, &stats.Completed, &stats.Failed,
+		&stats.DeadLetter, &stats.OldestPendingAt, &stats.OldestRunningAt,
+		&stats.LastCompletedAt, &stats.LastProcessedAt,
+	)
+	if err != nil {
+		return nil, fmt.Errorf("get indexing job stats: %w", err)
+	}
+	return stats, nil
+}
+
+func (s *PostgresStore) AppendIndexingAudit(ctx context.Context, input IndexingAuditInput) error {
+	now := time.Now().UTC().Format(time.RFC3339)
+	_, err := s.db.ExecContext(ctx, `
+		INSERT INTO indexing_audit (
+			source, document_id, collection, cid, decision, attempt, error, created_at
+		) VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
+		input.Source, input.DocumentID, input.Collection, input.CID,
+		input.Decision, input.Attempt, nullableStr(input.Error), now,
+	)
+	if err != nil {
+		return fmt.Errorf("append indexing audit: %w", err)
+	}
+	return nil
+}
+
+func (s *PostgresStore) ListIndexingAudit(
+	ctx context.Context, filter IndexingAuditFilter,
+) ([]*IndexingAuditEntry, error) {
+	query := `
+		SELECT id, source, document_id, collection, cid, decision,
+		       attempt, COALESCE(error, ''), created_at
+		FROM indexing_audit
+		WHERE 1 = 1`
+	args := newPGArgs()
+
+	if filter.DocumentID != "" {
+		query += " AND document_id = " + args.Add(filter.DocumentID)
+	}
+	if filter.Source != "" {
+		query += " AND source = " + args.Add(filter.Source)
+	}
+	if filter.Decision != "" {
+		query += " AND decision = " + args.Add(filter.Decision)
+	}
+
+	query += " ORDER BY created_at::timestamptz DESC"
+	limit := filter.Limit
+	if limit <= 0 {
+		limit = 50
+	}
+	query += " LIMIT " + args.Add(limit)
+	if filter.Offset > 0 {
+		query += " OFFSET " + args.Add(filter.Offset)
+	}
+
+	rows, err := s.db.QueryContext(ctx, query, args.Values()...)
+	if err != nil {
+		return nil, fmt.Errorf("list indexing audit: %w", err)
+	}
+	defer rows.Close()
+
+	var entries []*IndexingAuditEntry
+	for rows.Next() {
+		entry := &IndexingAuditEntry{}
+		if err := rows.Scan(
+			&entry.ID, &entry.Source, &entry.DocumentID, &entry.Collection,
+			&entry.CID, &entry.Decision, &entry.Attempt, &entry.Error,
+			&entry.CreatedAt,
+		); err != nil {
+			return nil, fmt.Errorf("scan indexing audit: %w", err)
+		}
+		entries = append(entries, entry)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("iterate indexing audit: %w", err)
+	}
+	return entries, nil
+}
+
+func (s *PostgresStore) GetFollowSubjects(ctx context.Context, did string) ([]string, error) {
+	rows, err := s.db.QueryContext(ctx, `
+		SELECT DISTINCT repo_did
+		FROM documents
+		WHERE did = $1
+		  AND collection = 'sh.tangled.graph.follow'
+		  AND deleted_at IS NULL
+		  AND repo_did IS NOT NULL
+		  AND repo_did != ''`,
+		did,
+	)
+	if err != nil {
+		return nil, fmt.Errorf("get follow subjects: %w", err)
+	}
+	defer rows.Close()
+
+	var subjects []string
+	for rows.Next() {
+		var subject string
+		if err := rows.Scan(&subject); err != nil {
+			return nil, fmt.Errorf("scan follow subject: %w", err)
+		}
+		subjects = append(subjects, subject)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("iterate follow subjects: %w", err)
+	}
+	return subjects, nil
+}
+
+func (s *PostgresStore) GetRepoCollaborators(ctx context.Context, repoOwnerDID string) ([]string, error) {
+	rows, err := s.db.QueryContext(ctx, `
+		SELECT DISTINCT did
+		FROM documents
+		WHERE repo_did = $1
+		  AND did != $1
+		  AND deleted_at IS NULL
+		  AND collection IN (
+			'sh.tangled.repo.issue',
+			'sh.tangled.repo.pull',
+			'sh.tangled.repo.issue.comment',
+			'sh.tangled.repo.pull.comment'
+		  )`,
+		repoOwnerDID,
+	)
+	if err != nil {
+		return nil, fmt.Errorf("get repo collaborators: %w", err)
+	}
+	defer rows.Close()
+
+	var collaborators []string
+	for rows.Next() {
+		var collaborator string
+		if err := rows.Scan(&collaborator); err != nil {
+			return nil, fmt.Errorf("scan collaborator: %w", err)
+		}
+		collaborators = append(collaborators, collaborator)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("iterate collaborators: %w", err)
+	}
+	return collaborators, nil
+}
+
+func (s *PostgresStore) CountDocuments(ctx context.Context) (int64, error) {
+	var n int64
+	err := s.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM documents WHERE deleted_at IS NULL`).Scan(&n)
+	if err != nil {
+		return 0, fmt.Errorf("count documents: %w", err)
+	}
+	return n, nil
+}
+
+func (s *PostgresStore) CountPendingIndexingJobs(ctx context.Context) (int64, error) {
+	var n int64
+	err := s.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM indexing_jobs WHERE status = 'pending'`).Scan(&n)
+	if err != nil {
+		return 0, fmt.Errorf("count pending indexing jobs: %w", err)
+	}
+	return n, nil
+}
+
+func (s *PostgresStore) InsertJetstreamEvent(ctx context.Context, event *JetstreamEvent, maxEvents int) error {
+	tx, err := s.db.BeginTx(ctx, nil)
+	if err != nil {
+		return fmt.Errorf("begin insert jetstream event tx: %w", err)
+	}
+	defer tx.Rollback()
+
+	_, err = tx.ExecContext(ctx, `
+		INSERT INTO jetstream_events (time_us, did, kind, collection, rkey, operation, payload, received_at)
+		VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
+		event.TimeUS, event.DID, event.Kind, nullableStr(event.Collection),
+		nullableStr(event.RKey), nullableStr(event.Operation), event.Payload, event.ReceivedAt,
+	)
+	if err != nil {
+		return fmt.Errorf("insert jetstream event: %w", err)
+	}
+
+	if maxEvents > 0 {
+		_, err = tx.ExecContext(ctx, `
+			DELETE FROM jetstream_events
+			WHERE id IN (
+				SELECT id FROM jetstream_events
+				ORDER BY time_us DESC
+				OFFSET $1
+			)`, maxEvents)
+		if err != nil {
+			return fmt.Errorf("trim jetstream events: %w", err)
+		}
+	}
+
+	if err := tx.Commit(); err != nil {
+		return fmt.Errorf("commit insert jetstream event tx: %w", err)
+	}
+	return nil
+}
+
+func (s *PostgresStore) ListJetstreamEvents(
+	ctx context.Context, filter JetstreamEventFilter,
+) ([]*JetstreamEvent, error) {
+	query := `
+		SELECT id, time_us, did, kind,
+		       COALESCE(collection, ''), COALESCE(rkey, ''), COALESCE(operation, ''),
+		       payload, received_at
+		FROM jetstream_events WHERE 1=1`
+	args := newPGArgs()
+
+	if filter.Collection != "" {
+		query += " AND collection = " + args.Add(filter.Collection)
+	}
+	if filter.DID != "" {
+		query += " AND did = " + args.Add(filter.DID)
+	}
+	if filter.Operation != "" {
+		query += " AND operation = " + args.Add(filter.Operation)
+	}
+
+	query += " ORDER BY time_us DESC"
+	limit := filter.Limit
+	if limit <= 0 {
+		limit = 50
+	}
+	query += " LIMIT " + args.Add(limit)
+	if filter.Offset > 0 {
+		query += " OFFSET " + args.Add(filter.Offset)
+	}
+
+	rows, err := s.db.QueryContext(ctx, query, args.Values()...)
+	if err != nil {
+		return nil, fmt.Errorf("list jetstream events: %w", err)
+	}
+	defer rows.Close()
+
+	var events []*JetstreamEvent
+	for rows.Next() {
+		e := &JetstreamEvent{}
+		if err := rows.Scan(
+			&e.ID, &e.TimeUS, &e.DID, &e.Kind,
+			&e.Collection, &e.RKey, &e.Operation,
+			&e.Payload, &e.ReceivedAt,
+		); err != nil {
+			return nil, fmt.Errorf("scan jetstream event: %w", err)
+		}
+		events = append(events, e)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("iterate jetstream events: %w", err)
+	}
+	return events, nil
+}
+
+func (s *PostgresStore) Ping(ctx context.Context) error {
+	return s.db.PingContext(ctx)
+}

packages/api/internal/store/sql_store.go

···
 	"time"
 )
 
-// SQLStore implements Store against a libSQL database.
-type SQLStore struct {
+// SQLiteStore implements Store against a SQLite database.
+type SQLiteStore struct {
 	db *sql.DB
 }
 
 // New wraps an open *sql.DB in a Store implementation.
-func New(db *sql.DB) Store {
-	return &SQLStore{db: db}
+func New(url string, db *sql.DB) Store {
+	if DetectBackend(url) == BackendPostgres {
+		return &PostgresStore{db: db}
+	}
+	return &SQLiteStore{db: db}
 }
 
-func (s *SQLStore) UpsertDocument(ctx context.Context, doc *Document) error {
+func (s *SQLiteStore) UpsertDocument(ctx context.Context, doc *Document) error {
 	doc.IndexedAt = time.Now().UTC().Format(time.RFC3339)
 	tx, err := s.db.BeginTx(ctx, nil)
 	if err != nil {
···
 	return nil
 }
 
-func (s *SQLStore) ListDocuments(ctx context.Context, filter DocumentFilter) ([]*Document, error) {
+func (s *SQLiteStore) ListDocuments(ctx context.Context, filter DocumentFilter) ([]*Document, error) {
 	query := `SELECT id, did, collection, rkey, at_uri, cid, record_type,
 		       title, body, summary, repo_did, repo_name, author_handle,
 		       tags_json, language, created_at, updated_at, indexed_at, web_url, deleted_at
···
 	return docs, nil
 }
 
-func (s *SQLStore) OptimizeFTS(ctx context.Context) error {
+func (s *SQLiteStore) OptimizeSearchIndex(ctx context.Context) error {
 	_, err := s.db.ExecContext(ctx, `INSERT INTO documents_fts(documents_fts) VALUES('optimize')`)
 	if err != nil {
-		return fmt.Errorf("optimize fts: %w", err)
+		return fmt.Errorf("optimize search index: %w", err)
 	}
 	return nil
 }
 
-func (s *SQLStore) GetDocument(ctx context.Context, id string) (*Document, error) {
+func (s *SQLiteStore) GetDocument(ctx context.Context, id string) (*Document, error) {
 	row := s.db.QueryRowContext(ctx, `
 		SELECT id, did, collection, rkey, at_uri, cid, record_type,
 		       title, body, summary, repo_did, repo_name, author_handle,
···
 	return doc, nil
 }
 
-func (s *SQLStore) MarkDeleted(ctx context.Context, id string) error {
+func (s *SQLiteStore) MarkDeleted(ctx context.Context, id string) error {
 	now := time.Now().UTC().Format(time.RFC3339)
 	tx, err := s.db.BeginTx(ctx, nil)
 	if err != nil {
···
 	return nil
 }
 
-func (s *SQLStore) GetSyncState(ctx context.Context, consumer string) (*SyncState, error) {
+func (s *SQLiteStore) GetSyncState(ctx context.Context, consumer string) (*SyncState, error) {
 	row := s.db.QueryRowContext(ctx, `
 		SELECT consumer_name, cursor, high_water_mark, updated_at
 		FROM sync_state WHERE consumer_name = ?`, consumer)
···
 	return ss, nil
 }
 
-func (s *SQLStore) SetSyncState(ctx context.Context, consumer string, cursor string) error {
+func (s *SQLiteStore) SetSyncState(ctx context.Context, consumer string, cursor string) error {
 	now := time.Now().UTC().Format(time.RFC3339)
 	_, err := s.db.ExecContext(ctx, `
 		INSERT INTO sync_state (consumer_name, cursor, updated_at) VALUES (?, ?, ?)
···
 	return nil
 }
 
-func (s *SQLStore) UpdateRecordState(ctx context.Context, subjectURI string, state string) error {
+func (s *SQLiteStore) UpdateRecordState(ctx context.Context, subjectURI string, state string) error {
 	now := time.Now().UTC().Format(time.RFC3339)
 	_, err := s.db.ExecContext(ctx, `
 		INSERT INTO record_state (subject_uri, state, updated_at) VALUES (?, ?, ?)
···
 	return nil
 }
 
-func (s *SQLStore) UpsertIdentityHandle(ctx context.Context, did, handle string, isActive bool, status string) error {
+func (s *SQLiteStore) UpsertIdentityHandle(ctx context.Context, did, handle string, isActive bool, status string) error {
 	now := time.Now().UTC().Format(time.RFC3339)
 	_, err := s.db.ExecContext(ctx, `
 		INSERT INTO identity_handles (did, handle, is_active, status, updated_at)
···
 	return nil
 }
 
-func (s *SQLStore) GetIdentityHandle(ctx context.Context, did string) (string, error) {
+func (s *SQLiteStore) GetIdentityHandle(ctx context.Context, did string) (string, error) {
 	var handle sql.NullString
 	err := s.db.QueryRowContext(ctx, `SELECT handle FROM identity_handles WHERE did = ?`, did).Scan(&handle)
 	if errors.Is(err, sql.ErrNoRows) {
···
 	return handle.String, nil
 }
 
-func (s *SQLStore) GetFollowSubjects(ctx context.Context, did string) ([]string, error) {
+func (s *SQLiteStore) GetFollowSubjects(ctx context.Context, did string) ([]string, error) {
 	rows, err := s.db.QueryContext(ctx, `
 		SELECT DISTINCT repo_did
 		FROM documents
···
 	return subjects, nil
 }
 
-func (s *SQLStore) GetRepoCollaborators(ctx context.Context, repoOwnerDID string) ([]string, error) {
+func (s *SQLiteStore) GetRepoCollaborators(ctx context.Context, repoOwnerDID string) ([]string, error) {
 	rows, err := s.db.QueryContext(ctx, `
 		SELECT DISTINCT did
 		FROM documents
···
 	return collaborators, nil
 }
 
-func (s *SQLStore) CountDocuments(ctx context.Context) (int64, error) {
+func (s *SQLiteStore) CountDocuments(ctx context.Context) (int64, error) {
 	var n int64
 	err := s.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM documents WHERE deleted_at IS NULL`).Scan(&n)
 	if err != nil {
···
 	return n, nil
 }
 
-func (s *SQLStore) CountPendingIndexingJobs(ctx context.Context) (int64, error) {
+func (s *SQLiteStore) CountPendingIndexingJobs(ctx context.Context) (int64, error) {
 	var n int64
 	err := s.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM indexing_jobs WHERE status = 'pending'`).Scan(&n)
 	if err != nil {
···
 	return n, nil
 }
 
-func (s *SQLStore) InsertJetstreamEvent(ctx context.Context, event *JetstreamEvent, maxEvents int) error {
+func (s *SQLiteStore) InsertJetstreamEvent(ctx context.Context, event *JetstreamEvent, maxEvents int) error {
 	tx, err := s.db.BeginTx(ctx, nil)
 	if err != nil {
 		return fmt.Errorf("begin insert jetstream event tx: %w", err)
···
 	return nil
 }
 
-func (s *SQLStore) ListJetstreamEvents(ctx context.Context, filter JetstreamEventFilter) ([]*JetstreamEvent, error) {
+func (s *SQLiteStore) ListJetstreamEvents(ctx context.Context, filter JetstreamEventFilter) ([]*JetstreamEvent, error) {
 	query := `
 		SELECT id, time_us, did, kind,
 		       COALESCE(collection, ''), COALESCE(rkey, ''), COALESCE(operation, ''),
···
 	return events, nil
 }
 
-func (s *SQLStore) Ping(ctx context.Context) error {
+func (s *SQLiteStore) Ping(ctx context.Context) error {
 	return s.db.PingContext(ctx)
 }
 

packages/api/internal/store/store.go

···
 	GetDocument(ctx context.Context, id string) (*Document, error)
 	MarkDeleted(ctx context.Context, id string) error
 	ListDocuments(ctx context.Context, filter DocumentFilter) ([]*Document, error)
-	OptimizeFTS(ctx context.Context) error
+	OptimizeSearchIndex(ctx context.Context) error
 	GetSyncState(ctx context.Context, consumer string) (*SyncState, error)
 	SetSyncState(ctx context.Context, consumer string, cursor string) error
 	UpdateRecordState(ctx context.Context, subjectURI string, state string) error

packages/api/internal/store/store_test.go

···
 	dbPath := filepath.Join(dir, "test.db")
 	url := "file:" + dbPath
 
-	db, err := store.Open(url, "")
+	db, err := store.Open(url)
 	if err != nil {
 		t.Fatalf("open: %v", err)
 	}
···
 		t.Fatalf("migrate: %v", err)
 	}
 
-	st := store.New(db)
+	st := store.New(url, db)
 	ctx := context.Background()
 
 	t.Run("upsert and get document", func(t *testing.T) {

packages/api/internal/view/api-docs.json

···
     "summary": "Unified search across all indexed Tangled documents.",
     "details": "Delegates to keyword search. The mode parameter is accepted but only \"keyword\" is supported.",
     "queryParams": [
-      { "name": "q", "type": "string", "required": true, "description": "Search query. Supports boolean operators, phrases, and prefix matching." },
-      { "name": "mode", "type": "string", "required": false, "description": "Search mode. Only \"keyword\" is supported." },
+      {
+        "name": "q",
+        "type": "string",
+        "required": true,
+        "description": "Search query. Supports boolean operators, phrases, and prefix matching."
+      },
+      {
+        "name": "mode",
+        "type": "string",
+        "required": false,
+        "description": "Search mode. Only \"keyword\" is supported."
+      },
       { "name": "limit", "type": "int", "required": false, "description": "Results per page (1–100). Default 20." },
       { "name": "offset", "type": "int", "required": false, "description": "Pagination offset. Default 0." },
-      { "name": "collection", "type": "string", "required": false, "description": "Filter by ATProto collection NSID." },
-      { "name": "type", "type": "string", "required": false, "description": "Filter by record type: repo, issue, pull, profile, string." },
+      {
+        "name": "collection",
+        "type": "string",
+        "required": false,
+        "description": "Filter by ATProto collection NSID."
+      },
+      {
+        "name": "type",
+        "type": "string",
+        "required": false,
+        "description": "Filter by record type: repo, issue, pull, profile, string."
+      },
       { "name": "author", "type": "string", "required": false, "description": "Filter by author handle or DID." },
       { "name": "repo", "type": "string", "required": false, "description": "Filter by repository name." },
       { "name": "language", "type": "string", "required": false, "description": "Filter by programming language." },
···
     "page": "search",
     "route": "/search/keyword",
     "method": "GET",
-    "summary": "FTS5 keyword search over indexed Tangled documents.",
+    "summary": "PostgreSQL full-text keyword search over indexed Tangled documents.",
     "details": "Same parameters and response shape as GET /search. Use this route to bypass mode negotiation.",
     "queryParams": [
-      { "name": "q", "type": "string", "required": true, "description": "Search query. Supports boolean operators, phrases, and prefix matching." },
+      {
+        "name": "q",
+        "type": "string",
+        "required": true,
+        "description": "Search query. Supports boolean operators, phrases, and prefix matching."
+      },
       { "name": "limit", "type": "int", "required": false, "description": "Results per page (1–100). Default 20." },
       { "name": "offset", "type": "int", "required": false, "description": "Pagination offset. Default 0." },
-      { "name": "collection", "type": "string", "required": false, "description": "Filter by ATProto collection NSID." },
-      { "name": "type", "type": "string", "required": false, "description": "Filter by record type: repo, issue, pull, profile, string." },
+      {
+        "name": "collection",
+        "type": "string",
+        "required": false,
+        "description": "Filter by ATProto collection NSID."
+      },
+      {
+        "name": "type",
+        "type": "string",
+        "required": false,
+        "description": "Filter by record type: repo, issue, pull, profile, string."
+      },
       { "name": "author", "type": "string", "required": false, "description": "Filter by author handle or DID." },
       { "name": "repo", "type": "string", "required": false, "description": "Filter by repository name." },
       { "name": "language", "type": "string", "required": false, "description": "Filter by programming language." },
···
     "method": "GET",
     "summary": "Fetch a single indexed document by its stable ID.",
     "details": "The document ID has the format did|collection|rkey. Deleted documents return 404.",
-    "pathParams": [
-      { "name": "id", "type": "string", "description": "Stable document ID (did|collection|rkey)." }
-    ]
+    "pathParams": [{ "name": "id", "type": "string", "description": "Stable document ID (did|collection|rkey)." }]
   },
   {
     "page": "actors",
···
     "method": "GET",
     "summary": "Tangled actor profile with optional Bluesky social data.",
     "details": "Resolves handle to DID, fetches sh.tangled.actor.profile from the actor's PDS. If the profile record has bluesky:true, Bluesky display name and avatar are also returned.",
-    "pathParams": [
-      { "name": "handle", "type": "string", "description": "Tangled handle or DID." }
-    ]
+    "pathParams": [{ "name": "handle", "type": "string", "description": "Tangled handle or DID." }]
   },
   {
     "page": "actors",
     "route": "/actors/{handle}/repos",
     "method": "GET",
     "summary": "List all sh.tangled.repo records for an actor.",
-    "pathParams": [
-      { "name": "handle", "type": "string", "description": "Tangled handle or DID." }
-    ]
+    "pathParams": [{ "name": "handle", "type": "string", "description": "Tangled handle or DID." }]
   },
   {
     "page": "actors",
···
       { "name": "repo", "type": "string", "description": "Repository name." }
     ],
     "queryParams": [
-      { "name": "ref", "type": "string", "required": false, "description": "Branch, tag, or commit SHA. Defaults to default branch." },
+      {
+        "name": "ref",
+        "type": "string",
+        "required": false,
+        "description": "Branch, tag, or commit SHA. Defaults to default branch."
+      },
       { "name": "path", "type": "string", "required": false, "description": "Subdirectory path within the tree." }
     ]
   },
···
     ],
     "queryParams": [
       { "name": "ref", "type": "string", "required": false, "description": "Branch, tag, or commit SHA." },
-      { "name": "path", "type": "string", "required": false, "description": "Limit log to commits touching this path." },
+      {
+        "name": "path",
+        "type": "string",
+        "required": false,
+        "description": "Limit log to commits touching this path."
+      },
       { "name": "limit", "type": "int", "required": false, "description": "Max commits to return." },
-      { "name": "cursor", "type": "string", "required": false, "description": "Pagination cursor from a previous response." }
+      {
+        "name": "cursor",
+        "type": "string",
+        "required": false,
+        "description": "Pagination cursor from a previous response."
+      }
     ]
   },
   {
···
     "route": "/actors/{handle}/issues",
     "method": "GET",
     "summary": "All issues authored by an actor, pre-joined with state.",
-    "pathParams": [
-      { "name": "handle", "type": "string", "description": "Tangled handle or DID." }
-    ]
+    "pathParams": [{ "name": "handle", "type": "string", "description": "Tangled handle or DID." }]
   },
   {
     "page": "actors",
     "route": "/actors/{handle}/pulls",
     "method": "GET",
     "summary": "All pull requests authored by an actor, pre-joined with status.",
-    "pathParams": [
-      { "name": "handle", "type": "string", "description": "Tangled handle or DID." }
-    ]
+    "pathParams": [{ "name": "handle", "type": "string", "description": "Tangled handle or DID." }]
   },
   {
     "page": "actors",
     "route": "/actors/{handle}/following",
     "method": "GET",
     "summary": "sh.tangled.graph.follow records for an actor.",
-    "pathParams": [
-      { "name": "handle", "type": "string", "description": "Tangled handle or DID." }
-    ]
+    "pathParams": [{ "name": "handle", "type": "string", "description": "Tangled handle or DID." }]
   },
   {
     "page": "actors",
     "route": "/actors/{handle}/strings",
     "method": "GET",
     "summary": "sh.tangled.string records posted by an actor.",
-    "pathParams": [
-      { "name": "handle", "type": "string", "description": "Tangled handle or DID." }
-    ]
+    "pathParams": [{ "name": "handle", "type": "string", "description": "Tangled handle or DID." }]
   },
   {
     "page": "issues",
···
     "method": "GET",
     "summary": "Fetch a DID document for did:plc or did:web identifiers.",
     "details": "did:plc resolves via plc.directory. did:web resolves via https://{host}/.well-known/did.json. Other DID methods return 400.",
-    "pathParams": [
-      { "name": "did", "type": "string", "description": "A did:plc:… or did:web:… identifier." }
-    ]
+    "pathParams": [{ "name": "did", "type": "string", "description": "A did:plc:… or did:web:… identifier." }]
   },
   {
     "page": "activity",
···
     "queryParams": [
       { "name": "limit", "type": "int", "required": false, "description": "Results per page (1–200). Default 50." },
       { "name": "offset", "type": "int", "required": false, "description": "Pagination offset. Default 0." },
-      { "name": "collection", "type": "string", "required": false, "description": "Filter by ATProto collection NSID." },
-      { "name": "operation", "type": "string", "required": false, "description": "Filter by operation: create, update, delete." },
+      {
+        "name": "collection",
+        "type": "string",
+        "required": false,
+        "description": "Filter by ATProto collection NSID."
+      },
+      {
+        "name": "operation",
+        "type": "string",
+        "required": false,
+        "description": "Filter by operation: create, update, delete."
+      },
       { "name": "did", "type": "string", "required": false, "description": "Filter by actor DID." }
     ]
   },
···
     "method": "GET",
     "summary": "Social summary for an actor: follower count via Constellation.",
     "details": "Best-effort — if Constellation is unavailable follower_count is 0 rather than an error.",
-    "pathParams": [
-      { "name": "did", "type": "string", "description": "ATProto DID, e.g. did:plc:abc." }
-    ]
+    "pathParams": [{ "name": "did", "type": "string", "description": "ATProto DID, e.g. did:plc:abc." }]
   },
   {
     "page": "profiles",
···
     "details": "Used by the mobile client for star counts (source: sh.tangled.graph.star) and follower counts (source: sh.tangled.graph.follow).",
     "queryParams": [
       { "name": "subject", "type": "string", "required": true, "description": "AT URI or DID being linked to." },
-      { "name": "source", "type": "string", "required": true, "description": "Collection NSID of the backlink records." }
+      {
+        "name": "source",
+        "type": "string",
+        "required": true,
+        "description": "Collection NSID of the backlink records."
+      }
     ]
   },
   {
···
     "method": "GET",
     "summary": "Proxy a GET request to the Bluesky public API.",
     "details": "Forwards to https://public.api.bsky.app/xrpc/{nsid}. No authentication is forwarded; only public endpoints are accessible.",
-    "pathParams": [
-      { "name": "nsid", "type": "string", "description": "XRPC NSID to call on the Bluesky public API." }
-    ]
+    "pathParams": [{ "name": "nsid", "type": "string", "description": "XRPC NSID to call on the Bluesky public API." }]
   },
   {
     "page": "health",
···
     "route": "/readyz",
     "method": "GET",
     "summary": "Readiness probe. Checks database reachability.",
-    "details": "Executes a test query against the Turso/SQLite database. Returns 503 if the database cannot be reached."
+    "details": "Checks database reachability."
   }
 ]

packages/api/internal/view/templates/docs/index.html

···
   <thead><tr><th>Resource</th><th>Description</th></tr></thead>
   <tbody>
     <tr><td><a href="/docs/search">Search</a></td>
-        <td>FTS5 keyword search over indexed documents</td></tr>
+        <td>PostgreSQL keyword search over indexed documents</td></tr>
     <tr><td><a href="/docs/documents">Documents</a></td>
         <td>Fetch a single indexed document by stable ID</td></tr>
     <tr><td><a href="/docs/actors">Actors &amp; Repos</a></td>

packages/api/internal/view/templates/docs/search.html

···
 {{define "title"}}Search — Twister API{{end}}
 {{define "content"}}
 <h1>Search</h1>
-<p>Search endpoints run FTS5 keyword queries over indexed Tangled documents.
-Results include highlighted body snippets and BM25 relevance scores. If
-Constellation is configured, repository results are enriched with star counts.</p>
+<p>Search endpoints run PostgreSQL full-text queries over indexed Tangled
+documents. Results include highlighted snippets and weighted relevance scores.
+If Constellation is configured, repository results are enriched with star counts.</p>
 {{range .}}{{template "doc-entry" .}}{{end}}
 <h2>Query syntax</h2>
-<p>The keyword search uses SQLite FTS5 query syntax:</p>
+<p>The keyword search uses PostgreSQL web-style query parsing:</p>
 <table>
   <thead><tr><th>Feature</th><th>Example</th></tr></thead>
   <tbody>
-    <tr><td>Boolean AND</td><td><code>go AND search</code></td></tr>
-    <tr><td>Boolean NOT</td><td><code>rust NOT unsafe</code></td></tr>
+    <tr><td>Simple terms</td><td><code>go search</code></td></tr>
+    <tr><td>Exclude term</td><td><code>rust -unsafe</code></td></tr>
     <tr><td>Phrase</td><td><code>"pull request"</code></td></tr>
-    <tr><td>Prefix</td><td><code>tang*</code></td></tr>
-    <tr><td>Field-scoped</td><td><code>title:parser</code></td></tr>
+    <tr><td>Natural-language</td><td><code>repo issue parser</code></td></tr>
   </tbody>
 </table>
 <h2>Errors</h2>

packages/api/justfile

···
 build:
     CGO_ENABLED=0 go build -ldflags "{{ldflags}}" -o twister ./main.go
 
-# Run the API server. Usage: just run-api [mode], mode: local|remote (default local)
+# Run the API server. Usage: just run-api [mode], mode: local|remote|sqlite (default local)
 run-api mode="local":
     if [ "{{mode}}" = "local" ]; then \
-        go run -ldflags "{{ldflags}}" ./main.go api --local; \
+        DATABASE_URL="postgresql://localhost/${USER:-postgres}_dev?sslmode=disable" \
+        go run -ldflags "{{ldflags}}" ./main.go api; \
     elif [ "{{mode}}" = "remote" ]; then \
         go run -ldflags "{{ldflags}}" ./main.go api; \
+    elif [ "{{mode}}" = "sqlite" ]; then \
+        go run -ldflags "{{ldflags}}" ./main.go api --local; \
     else \
-        echo "invalid mode '{{mode}}' (expected local or remote)" >&2; \
+        echo "invalid mode '{{mode}}' (expected local, remote, or sqlite)" >&2; \
         exit 1; \
     fi
 
-# Run the indexer. Usage: just run-indexer [mode], mode: local|remote (default local)
+# Run the indexer. Usage: just run-indexer [mode], mode: local|remote|sqlite (default local)
 run-indexer mode="local":
     if [ "{{mode}}" = "local" ]; then \
-        go run -ldflags "{{ldflags}}" ./main.go indexer --local; \
+        DATABASE_URL="postgresql://localhost/${USER:-postgres}_dev?sslmode=disable" \
+        TAP_URL="${TAP_URL:-ws://localhost:2480/channel}" \
+        TAP_AUTH_PASSWORD="${TAP_AUTH_PASSWORD:-twisted-dev}" \
+        go run -ldflags "{{ldflags}}" ./main.go indexer; \
     elif [ "{{mode}}" = "remote" ]; then \
         go run -ldflags "{{ldflags}}" ./main.go indexer; \
+    elif [ "{{mode}}" = "sqlite" ]; then \
+        go run -ldflags "{{ldflags}}" ./main.go indexer --local; \
     else \
-        echo "invalid mode '{{mode}}' (expected local or remote)" >&2; \
+        echo "invalid mode '{{mode}}' (expected local, remote, or sqlite)" >&2; \
         exit 1; \
     fi
 

packages/api/main.go

···
 		SilenceErrors: true,
 	}
 
-	root.PersistentFlags().BoolVar(&local, "local", false, "Use a local twister-dev.db database and text logs for development")
+	root.PersistentFlags().BoolVar(&local, "local", false, "Deprecated: use the legacy local SQLite fallback instead of the default Postgres database URL")
 
 	root.AddCommand(
 		newAPICmd(&local),
···
 			log := observability.NewLogger(cfg)
 			log.Info("starting api", slog.String("service", "api"), slog.String("version", version), slog.String("addr", cfg.HTTPBindAddr))
 
-			db, err := store.Open(cfg.TursoURL, cfg.TursoToken)
+			db, err := store.Open(cfg.DatabaseURL)
 			if err != nil {
 				return fmt.Errorf("open database: %w", err)
 			}
 			defer db.Close()
 
-			if err := store.Migrate(db, cfg.TursoURL); err != nil {
+			if err := store.Migrate(db, cfg.DatabaseURL); err != nil {
 				return fmt.Errorf("migrate database: %w", err)
 			}
 
-			st := store.New(db)
-			searchRepo := search.NewRepository(db)
+			st := store.New(cfg.DatabaseURL, db)
+			searchRepo := search.NewRepository(cfg.DatabaseURL, db)
 
 			constellationClient := constellation.NewClient(
 				constellation.WithBaseURL(cfg.ConstellationURL),
···
 				return fmt.Errorf("TAP_URL is required for indexer")
 			}
 
-			db, err := store.Open(cfg.TursoURL, cfg.TursoToken)
+			db, err := store.Open(cfg.DatabaseURL)
 			if err != nil {
 				return fmt.Errorf("open database: %w", err)
 			}
 			defer db.Close()
 
-			if err := store.Migrate(db, cfg.TursoURL); err != nil {
+			if err := store.Migrate(db, cfg.DatabaseURL); err != nil {
 				return fmt.Errorf("migrate database: %w", err)
 			}
 
-			st := store.New(db)
+			st := store.New(cfg.DatabaseURL, db)
 			registry := normalize.NewRegistry()
 			tap := tapclient.New(cfg.TapURL, cfg.TapAuthPassword, log)
 			runner := ingest.NewRunner(st, registry, tap, cfg.IndexedCollections, log)
···
 				return fmt.Errorf("TAP_URL is required for backfill")
 			}
 
-			db, err := store.Open(cfg.TursoURL, cfg.TursoToken)
+			db, err := store.Open(cfg.DatabaseURL)
 			if err != nil {
 				return fmt.Errorf("open database: %w", err)
 			}
 			defer db.Close()
 
-			if err := store.Migrate(db, cfg.TursoURL); err != nil {
+			if err := store.Migrate(db, cfg.DatabaseURL); err != nil {
 				return fmt.Errorf("migrate database: %w", err)
 			}
 
···
 			)
 
 			runner := backfill.NewRunner(
-				store.New(db),
+				store.New(cfg.DatabaseURL, db),
 				tapAdmin,
 				xrpcClient,
 				log,
···
 			log := observability.NewLogger(cfg)
 			log.Info("starting reindex", slog.String("service", "reindex"), slog.String("version", version))
 
-			db, err := store.Open(cfg.TursoURL, cfg.TursoToken)
+			db, err := store.Open(cfg.DatabaseURL)
 			if err != nil {
 				return fmt.Errorf("open database: %w", err)
 			}
 			defer db.Close()
 
-			if err := store.Migrate(db, cfg.TursoURL); err != nil {
+			if err := store.Migrate(db, cfg.DatabaseURL); err != nil {
 				return fmt.Errorf("migrate database: %w", err)
 			}
 
 			ctx, cancel := baseContext()
 			defer cancel()
 
-			runner := reindex.New(store.New(db), log)
+			runner := reindex.New(store.New(cfg.DatabaseURL, db), log)
 			result, err := runner.Run(ctx, opts)
 			if result != nil {
 				log.Info("reindex finished",
···
 			log := observability.NewLogger(cfg)
 			log.Info("starting enrich", slog.String("service", "enrich"), slog.String("version", version))
 
-			db, err := store.Open(cfg.TursoURL, cfg.TursoToken)
+			db, err := store.Open(cfg.DatabaseURL)
 			if err != nil {
 				return fmt.Errorf("open database: %w", err)
 			}
 			defer db.Close()
 
-			if err := store.Migrate(db, cfg.TursoURL); err != nil {
+			if err := store.Migrate(db, cfg.DatabaseURL); err != nil {
 				return fmt.Errorf("migrate database: %w", err)
 			}
 
···
 			ctx, cancel := baseContext()
 			defer cancel()
 
-			runner := enrich.New(store.New(db), xrpcClient, log)
+			runner := enrich.New(store.New(cfg.DatabaseURL, db), xrpcClient, log)
 			result, err := runner.Run(ctx, opts)
 			if result != nil {
 				log.Info("enrich finished",