@concavejs/docstore-cf-hyperdrive

DocStore for external SQL databases (PostgreSQL, MySQL) reached through Cloudflare Hyperdrive, plus Postgres-native search, vector, and blob providers. The stores are written against a portable SqlAdapter interface, so they also run outside Workers with any Postgres client that implements it.

Preview: validate schema setup, database compatibility, backups, and restore drills against your own provider before using this adapter for important data.

Document storage

HyperdriveDocStore implements the full DocStore contract (MVCC document log, index entries, globals) over generic SQL. Pick the adapter for your dialect:

import { HyperdriveDocStore, PostgresHyperdriveAdapter } from "@concavejs/docstore-cf-hyperdrive";

const store = new HyperdriveDocStore(new PostgresHyperdriveAdapter(env.HYPERDRIVE));

On Cloudflare, prefer the hyperdrive() storage constructor from @concavejs/runtime-cf's defineConcave composition, which wires everything below automatically for the postgres dialect. The mysql dialect provides the docstore only (no Postgres-native search, vectors or blobs).

Postgres-native search: PostgresSearchStore

Full-text search through a shared concave_search_entries table with a generated tsvector column and GIN index. syncWrites() mirrors committed document revisions (same MVCC timestamps as the documents table), so queries are snapshot-aware: a query at readTimestamp sees exactly the revisions a transaction at that snapshot would.

• Convex-compatible matching: AND of query tokens, prefix match on the last term, ts_rank scoring with creation-time tie-breaking.
• Filter fields are pushed down via a filter_values @> … JSONB containment (GIN-indexed) and post-filtered exactly in JS.
• Tokenization uses the simple regconfig by default; pass regconfig to opt into stemming.

Postgres-native vectors: PostgresVecStore

pgvector-backed vector search with one physical table per Concave vector index (vector columns have fixed dimensions). Dimensions come from the schema when declared, otherwise the table is created lazily from the first synced embedding. Searches use cosine distance with an HNSW index and join back to the documents table.

Extension policy:

• mode: "native" — fail setupSchema() if pgvector is unavailable.
• mode: "auto" (default) — probe CREATE EXTENSION IF NOT EXISTS vector, fall back per fallback:
  • "scan" (default) — delegate to the provided scanStore (typically the documents-store scan implementation).
  • "error" — reject vector searches.

Postgres blobs: PostgresBlobStore

Blob bytes and metadata in one concave_blobs table (bytea body), giving transactional durability in the same database that holds documents. Object stores (R2/S3) remain the better fit for large objects.

Testing

src/postgres-stores.test.ts runs the stores against PGlite — real Postgres (with pgvector) in WASM — covering FTS prefix matching, filter pushdown, snapshot reads, tombstones, cosine ranking, extension fallbacks, and the blob contract. Run with bun test in this package.

Support and license

See the public support policy for the alpha support boundary. Concave is licensed under custom functional-source license terms.