Postgres Adapter

Use PostgreSQL as a remote storage backend with connection pooling, schema migrations, and full sync support.

Overview

The Postgres adapter stores data in a PostgreSQL database. It is suited for server-side applications, shared infrastructure, and workloads that benefit from SQL queries, full-text search, or transactional guarantees across multiple stores.

Connection

import { createStore } from "@cuitty/persist";

const store = await createStore("analytics", {
  adapter: "postgres",
  connectionString: "postgresql://user:pass@localhost:5432/persist",
});

You can also pass individual connection parameters:

const store = await createStore("analytics", {
  adapter: "postgres",
  postgres: {
    host: "localhost",
    port: 5432,
    database: "persist",
    user: "persist_app",
    password: process.env.DB_PASSWORD,
    ssl: { rejectUnauthorized: true },
  },
});

Schema migration

On first connection, Persist creates the required tables (persist_records, persist_events, persist_kv, persist_sync_queue) in a persist schema. Subsequent connections check the schema version and run incremental migrations as needed.

-- Tables created automatically
persist.persist_records   -- key, value (jsonb), version, updated_at
persist.persist_events    -- id, stream, payload (jsonb), timestamp
persist.persist_kv        -- key, value, updated_at
persist.persist_sync_queue -- id, operation, payload, status

You can customize the schema name:

const store = await createStore("analytics", {
  adapter: "postgres",
  connectionString: "postgresql://...",
  postgres: { schema: "my_app_persist" },
});

Connection pooling

Persist uses a connection pool internally. The default pool size is 10 connections. Configure it based on your workload:

const store = await createStore("analytics", {
  adapter: "postgres",
  connectionString: "postgresql://...",
  postgres: {
    poolSize: 20,
    idleTimeout: 30_000,
    connectionTimeout: 5_000,
  },
});

For serverless environments (AWS Lambda, Vercel), set poolSize: 1 and use a connection pooler like PgBouncer to avoid exhausting database connections.

Sync support

The Postgres adapter supports full bidirectional sync. It can act as both a sync source and target, making it a natural choice for a central sync server that multiple devices replicate against.

Supported store classes

Records, events, and kv are fully supported. Blob storage is not supported — use the S3 adapter for binary objects and combine it with Postgres for structured data.