Drizzle / Postgres

@chatpack/adapter-drizzle is the production storage adapter: Postgres via Drizzle ORM. It works with any Drizzle Postgres driver - node-postgres, postgres.js, PGlite, Neon, Vercel Postgres.

Install

npm install @chatpack/core @chatpack/adapter-drizzle drizzle-orm pg

drizzle-orm is a peer dependency - the adapter plugs into the Drizzle instance your app already has.

Use

import { drizzle } from "drizzle-orm/node-postgres";
import { chatpack } from "@chatpack/core";
import { drizzleAdapter } from "@chatpack/adapter-drizzle";

const db = drizzle(process.env.DATABASE_URL!);

export const chat = chatpack({
  storage: drizzleAdapter(db),
  auth: async (req) => getSessionUser(req),
});

Creating the tables

Chatpack needs twelve tables (chatpack_conversations, chatpack_conversation_participants, chatpack_messages, chatpack_message_search_tokens, chatpack_message_reactions, chatpack_message_mentions, chatpack_conversation_invites, chatpack_join_requests, chatpack_user_blocks, chatpack_conversation_mutes, chatpack_moderation_reports, chatpack_user_bans). Users are referenced by id only - there is no foreign key into your users table.

export * from "@chatpack/adapter-drizzle"; // conversations, participants, messages, reactions, invites, moderation

drizzle-kit generate && drizzle-kit migrate

Neon and serverless runtimes

Chatpack message writes use db.transaction(). Use Neon's WebSocket Pool, not the Neon HTTP driver:

import { Pool, neonConfig } from "@neondatabase/serverless";
import { attachDatabasePool } from "@vercel/functions";
import { drizzle } from "drizzle-orm/neon-serverless";
import ws from "ws";

neonConfig.webSocketConstructor = ws;
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
attachDatabasePool(pool);

export const db = drizzle({ client: pool });

The Neon HTTP driver cannot run the transactions required for message ordering and group mutations. Current Chatpack deployments must use a Node.js runtime or another transaction-capable Drizzle Postgres driver.

Correctness guarantees

The two things a chat backend must get right under concurrency, and how this adapter does them (ADR 0007):

• Monotonic message ordering - seq is assigned by an atomic UPDATE ... SET last_seq = last_seq + 1 ... RETURNING; Postgres row locking serializes concurrent sends. A unique index on (conversation_id, seq) enforces the invariant at the schema level too.
• One conversation per user pair - creation uses ON CONFLICT (pair_key) WHERE pair_key IS NOT NULL DO NOTHING + re-select against the partial unique pair_key index, so concurrent find-or-create calls converge. The repeated WHERE is required: Postgres only matches an ON CONFLICT target to a partial index when the predicate is restated.
• Groups are created, never found - a group has pairKey: null, so it takes a plain INSERT with no conflict target, and the conversation row plus every participant row are written in one db.transaction. A half-created group would be unreadable and therefore unrepairable.
• Idempotent membership - addParticipants uses ON CONFLICT (conversation_id, user_id) DO NOTHING, never DO UPDATE, so a retried request can't demote an admin back to member. Like reactions, membership writes issue no UPDATE on the conversation.
• Idempotent reactions - the same shape: ON CONFLICT (message_id, user_id, emoji) DO NOTHING against a unique index on the triple, so five concurrent identical reactions collapse to one row. Reacting deliberately issues no UPDATE on the conversation, so it can't advance last_seq / last_activity_at or reorder the conversation list.
• A use cap that actually caps - consumeInvite checks usability and increments in one statement (UPDATE ... SET uses = uses + 1 WHERE code = $1 AND (max_uses IS NULL OR uses < max_uses) AND (expires_at IS NULL OR expires_at > now()) RETURNING *), so five simultaneous redemptions of a maxUses: 1 link admit exactly one person. Zero rows back means "spent", which core turns into 410. Join requests are the one place that does use DO UPDATE - a re-ask has to replace a stale denial with a fresh pending row.
• Channel joins ride the same idempotency - a self-join into an "open" channel goes through addParticipants, so eight concurrent joins by one user leave one participant row. The directory query filters on type = 'group' AND visibility = 'public' (both, not just visibility) and reads visibility / join_policy through a narrowing coercion, so a legacy NULL or a hand-edited value comes back as "private" / "approval" instead of leaking out of the union.

Testing

The integration suite runs the full Chatpack engine against this adapter on PGlite - real Postgres compiled to WASM - so pnpm test needs no Docker or external database, locally or in CI. The same trick works for your own tests:

import { PGlite } from "@electric-sql/pglite";
import { drizzle } from "drizzle-orm/pglite";
import { drizzleAdapter, migrationSql, type DrizzlePgDatabase } from "@chatpack/adapter-drizzle";

const pglite = new PGlite();
await pglite.exec(migrationSql);
const db = drizzle(pglite) as unknown as DrizzlePgDatabase;
const chat = chatpack({ storage: drizzleAdapter(db) });

(The cast bridges a type mismatch between the drizzle-orm/pglite driver's return type and the adapter's driver-agnostic DrizzlePgDatabase - it's what the adapter's own test suite does.)

No connection string?

Supabase projects that expose PostgREST through the Supabase JS client should use the first-party Supabase adapter. Convex, Firestore, and other stores without a first-party adapter are supported through a custom adapter. If you can reach Postgres with a connection string (Neon, RDS, Railway, Fly, Replit, Vercel Postgres), use this adapter - don't write a custom one.