{ "slug": "persist/adapters", "title": "Storage Adapters", "description": "Configure SQLite, Postgres, S3, and P2P adapters for Persist stores.", "url": "https://cuitty.com/docs/persist/adapters", "markdown_url": "https://cuitty.com/docs/persist/adapters.md", "json_url": "https://cuitty.com/docs/persist/adapters.json", "frontmatter": { "title": "Storage Adapters", "description": "Configure SQLite, Postgres, S3, and P2P adapters for Persist stores.", "order": 2, "section": "Persist", "updatedAt": "2026-05-12" }, "headings": [ { "depth": 1, "slug": "storage-adapters", "text": "Storage Adapters" }, { "depth": 2, "slug": "sqlite", "text": "SQLite" }, { "depth": 2, "slug": "postgres", "text": "Postgres" }, { "depth": 3, "slug": "connection-pooling", "text": "Connection pooling" }, { "depth": 2, "slug": "s3", "text": "S3" }, { "depth": 2, "slug": "p2p", "text": "P2P" }, { "depth": 2, "slug": "custom-adapters", "text": "Custom adapters" } ], "body_markdown": "# Storage Adapters\n\nPersist uses pluggable adapters for storage backends. Every adapter exposes the same API (`store.records`, `store.kv`, `store.blobs`, `store.events`), so you can swap backends without changing application code.\n\n## SQLite\n\nThe default adapter. Ideal for local-first apps, development, and mobile.\n\n```ts\nimport { createStore } from \"@cuitty/persist\";\n\nconst store = await createStore({\n name: \"my-app\",\n adapter: \"sqlite\",\n path: \"./data/my-app.db\",\n});\n```\n\nSQLite stores are single-file, need no external process, and support WAL mode for concurrent reads out of the box.\n\n## Postgres\n\nProduction-grade durability with full SQL support. Best for server-side workloads.\n\n```ts\nconst store = await createStore({\n name: \"my-app\",\n adapter: \"postgres\",\n connection: {\n host: \"localhost\",\n port: 5432,\n database: \"persist\",\n user: \"persist\",\n password: process.env.PG_PASSWORD,\n },\n});\n```\n\n### Connection pooling\n\nPass `pool: { max: 20 }` to control the connection pool size. The default is 10.\n\n## S3\n\nBlob storage adapter for large files and binary data.\n\n```ts\nconst store = await createStore({\n name: \"my-app\",\n adapter: \"s3\",\n bucket: \"my-persist-bucket\",\n region: \"us-east-1\",\n credentials: {\n accessKeyId: process.env.AWS_ACCESS_KEY_ID!,\n secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,\n },\n});\n```\n\nThe S3 adapter maps `store.blobs` operations to S3 objects and `store.records` to JSON objects stored under a configurable prefix.\n\n## P2P\n\nPeer-to-peer replication with no central server. Peers discover each other and sync directly.\n\n```ts\nconst store = await createStore({\n name: \"my-app\",\n adapter: \"p2p\",\n discovery: {\n method: \"mdns\", // or \"dht\" for wide-area\n topic: \"my-app-sync\",\n },\n});\n```\n\nThe P2P adapter uses CRDTs internally to merge writes from multiple peers without conflicts.\n\n## Custom adapters\n\nImplement the `PersistAdapter` interface to build your own backend.\n\n```ts\nimport type { PersistAdapter } from \"@cuitty/persist\";\n\nconst myAdapter: PersistAdapter = {\n async get(key: string) { /* ... */ },\n async put(key: string, value: unknown) { /* ... */ },\n async delete(key: string) { /* ... */ },\n async list(prefix: string) { /* ... */ },\n};\n\nconst store = await createStore({\n name: \"my-app\",\n adapter: myAdapter,\n});\n```\n\nAll four methods must return promises. `list` returns an async iterable of `{ key, value }` pairs.", "body_html": "

Storage Adapters

\n

Persist uses pluggable adapters for storage backends. Every adapter exposes the same API (store.records, store.kv, store.blobs, store.events), so you can swap backends without changing application code.

\n

SQLite

\n

The default adapter. Ideal for local-first apps, development, and mobile.

\n
import { createStore } from \"@cuitty/persist\";\n\nconst store = await createStore({\n  name: \"my-app\",\n  adapter: \"sqlite\",\n  path: \"./data/my-app.db\",\n});
\n

SQLite stores are single-file, need no external process, and support WAL mode for concurrent reads out of the box.

\n

Postgres

\n

Production-grade durability with full SQL support. Best for server-side workloads.

\n
const store = await createStore({\n  name: \"my-app\",\n  adapter: \"postgres\",\n  connection: {\n    host: \"localhost\",\n    port: 5432,\n    database: \"persist\",\n    user: \"persist\",\n    password: process.env.PG_PASSWORD,\n  },\n});
\n

Connection pooling

\n

Pass pool: { max: 20 } to control the connection pool size. The default is 10.

\n

S3

\n

Blob storage adapter for large files and binary data.

\n
const store = await createStore({\n  name: \"my-app\",\n  adapter: \"s3\",\n  bucket: \"my-persist-bucket\",\n  region: \"us-east-1\",\n  credentials: {\n    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,\n    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,\n  },\n});
\n

The S3 adapter maps store.blobs operations to S3 objects and store.records to JSON objects stored under a configurable prefix.

\n

P2P

\n

Peer-to-peer replication with no central server. Peers discover each other and sync directly.

\n
const store = await createStore({\n  name: \"my-app\",\n  adapter: \"p2p\",\n  discovery: {\n    method: \"mdns\",         // or \"dht\" for wide-area\n    topic: \"my-app-sync\",\n  },\n});
\n

The P2P adapter uses CRDTs internally to merge writes from multiple peers without conflicts.

\n

Custom adapters

\n

Implement the PersistAdapter interface to build your own backend.

\n
import type { PersistAdapter } from \"@cuitty/persist\";\n\nconst myAdapter: PersistAdapter = {\n  async get(key: string) { /* ... */ },\n  async put(key: string, value: unknown) { /* ... */ },\n  async delete(key: string) { /* ... */ },\n  async list(prefix: string) { /* ... */ },\n};\n\nconst store = await createStore({\n  name: \"my-app\",\n  adapter: myAdapter,\n});
\n

All four methods must return promises. list returns an async iterable of { key, value } pairs.

", "links_out": [] }