Drizzle adapter

@siteping/adapter-drizzle is a SitepingStore backed by Drizzle ORM. It has one entry per database family:

It requires Node 20+ and drizzle-orm 0.45 or later (below 1.0), a peer dependency. @siteping/server serves the store over HTTP (step 3):

npm i @siteping/adapter-drizzle @siteping/server drizzle-orm

Add your database driver (pg, postgres, @neondatabase/serverless, @electric-sql/pglite, @libsql/client…) and drizzle-kit for migrations.

1. Add the tables to your schema

The adapter never creates tables at runtime: it gives you Drizzle table definitions to export from your own schema, so drizzle-kit manages them like any other table.

// db/schema.ts — PostgreSQL
import { createSitepingPgTables } from "@siteping/adapter-drizzle/pg";

export const { sitepingFeedbacks, sitepingAnnotations } = createSitepingPgTables();

// db/schema.ts — Turso / libSQL
import { createSitepingSqliteTables } from "@siteping/adapter-drizzle/libsql";

export const { sitepingFeedbacks, sitepingAnnotations } = createSitepingSqliteTables();

Then generate and apply the migration as usual, with a drizzle.config.ts pointing at that schema (dialect: "postgresql" or dialect: "turso"):

npx drizzle-kit generate   # writes the SQL migration
npx drizzle-kit migrate    # applies it — or `npx drizzle-kit push` while prototyping

What gets created

Two tables, siteping_feedbacks and siteping_annotations by default. Annotations reference their feedback with ON DELETE CASCADE.

Column types follow the dialect: on PostgreSQL, JSON fields are jsonb and timestamps are timestamptz(3); on libSQL, JSON fields are stored as text and timestamps as epoch milliseconds.

Custom table names

Pass { feedbacks, annotations } to rename the tables (index names follow), and hand the same tables to the store through the tables option — otherwise it queries the default names:

// db/schema.ts
export const { sitepingFeedbacks, sitepingAnnotations } = createSitepingPgTables({
  feedbacks: "client_feedbacks",
  annotations: "client_feedback_annotations",
});

// server
const store = createPgSitepingStore(db, { tables: { sitepingFeedbacks, sitepingAnnotations } });

The defaults are exported as DEFAULT_SITEPING_TABLE_NAMES.

2. Create the store

// PostgreSQL — node-postgres
import { drizzle } from "drizzle-orm/node-postgres";
import { createPgSitepingStore } from "@siteping/adapter-drizzle/pg";

export const store = createPgSitepingStore(drizzle(process.env.DATABASE_URL!), {
  screenshotStorage,
  logger: console,
});

Every PostgreSQL driver works the same way — swap the drizzle import (drizzle-orm/neon-http, drizzle-orm/postgres-js, drizzle-orm/pglite…). The store never opens an interactive db.transaction: every write is a single statement, so drivers without interactive transactions, like Neon HTTP, are fully supported.

// Turso / libSQL
import { drizzle } from "drizzle-orm/libsql";
import { createLibSQLSitepingStore } from "@siteping/adapter-drizzle/libsql";

export const store = createLibSQLSitepingStore(
  drizzle({ connection: { url: process.env.TURSO_DATABASE_URL!, authToken: process.env.TURSO_AUTH_TOKEN } }),
  { screenshotStorage, logger: console },
);

3. Serve it

The store is storage only. Mount it behind createSitepingHandler({ store }) from @siteping/server to get validation, auth, CORS, redaction and webhooks:

// app/api/siteping/route.ts
import { createSitepingHandler } from "@siteping/server";
import { store } from "@/lib/siteping-store";

export const { GET, POST, PATCH, DELETE, OPTIONS } = createSitepingHandler({
  store,
  apiKey: process.env.SITEPING_API_KEY,
});

Options

Both factories take the same options:

Screenshots

Without screenshotStorage, the screenshot's base64 data URL is stored inline in screenshot_url (with a one-time warning to the logger) — fine for development, heavy for production.

With screenshotStorage, upload(dataUrl, { feedbackId, mimeType }) runs before the insert and only the returned URL is stored:

• feedbackId is the id the record will be stored under — generated server-side, fresh for every create attempt, never the client's clientId.
• mimeType is the media type the data URL declares — image/jpeg, image/png or image/webp, lowercased. Anything else (an SVG, which is script-capable when served inline, or no type at all) is reported as image/jpeg, the widget's capture format. Use it as the object's Content-Type.
• If upload throws, the feedback is still saved with screenshotUrl: null, and the failure goes to the logger.

The returned URL must be unique to the upload. Key objects by a fresh random value — never by a content hash, a fixed name or feedbackId alone. feedbackId happens to be unique per attempt with this store, but a ScreenshotStorage does not know which store calls it: passed to Prisma, where feedbackId is the client's clientId, an object keyed by it is rewritten by every retry. The store treats each URL as owned by the one feedback that stores it and may pass it to delete without coordinating with concurrent creates; a URL shared by several feedbacks can lose an object another feedback still points at.

Ready-made storage. @siteping/screenshot-storage provides a screenshotStorage for S3-compatible buckets, Cloudflare Images or your disk, with random keys and deletes scoped to its own objects. Its /drizzle-pg and /drizzle-libsql entries can also keep screenshots in a table of this same database, for small or self-contained deployments; in production, object storage is the better choice.

Cleanup. Add an optional delete(url) and the store removes screenshots it no longer needs: on deleteFeedback, on deleteAllFeedbacks, when a submission loses a race against a duplicate of itself (it uploaded its own object, now an orphan — discarded even when reading the winning submission back then fails), and when an insert fails. Before any delete it checks that no stored feedback still references the URL — an insert reported as failed may have committed after all — and if that check itself fails, every object is kept. Deletes run at most 8 at a time, so a project delete freeing thousands of objects does not flood your storage. Cleanup is best-effort: a failing delete is logged and never fails the operation. Inline data: URLs are never passed to delete.

Large projects. With a delete hook, deleteAllFeedbacks needs the removed URLs back, so it deletes the project in chunks of 500 rows — each chunk atomically, its screenshots cleaned up before the next — and no driver response or in-memory list grows with the project. If a chunk fails, the call throws StorePersistenceError: the earlier chunks stay deleted and cleaned up, and retrying the call removes the rest. Without a delete hook the whole project goes in one atomic statement.

Concurrency guarantees

• Duplicate submissions are atomic. The store implements createFeedbackIfAbsent: the unique client_id index plus ON CONFLICT DO NOTHING arbitrate concurrent submissions of the same feedback, across store instances and processes. Exactly one caller gets created: true, so the handler notifies your webhooks once, whichever server instance each request reached.
• Annotations land with their feedback, or not at all. On PostgreSQL the feedback and its annotations are inserted by one statement (a data-modifying CTE). On libSQL, multi-statement writes go through db.batch, which runs as one transaction and never holds the write lock across an await — your application can keep writing to the same database concurrently.
• Ordering is stable. Lists come back newest first. createdAt is the clock value at insert time, and rows created in the same millisecond — by one store instance, several processes, or your own code inserting through the exported tables — are ordered by an insertion ordinal the database itself assigns on every insert: the internal creation_sequence identity on PostgreSQL, SQLite's implicit rowid on libSQL. A later insert always lists first, and offset pages never overlap or skip rows.
• updatedAt never precedes createdAt. Status updates clamp it in SQL against the row's own timestamps, which holds across processes whose clocks disagree.
• Project ownership. The store implements verifyProjectOwnership, so the handler answers 404 to a PATCH/DELETE addressing an id from another project.

Internal columns

The tables carry a few columns of the store's own, never part of the returned records:

Text search and non-ASCII case

getFeedbacks({ search }) — the search query parameter — matches the message case-insensitively with JavaScript's Unicode-aware toLowerCase(), the same folding as the memory and localStorage stores: échec finds Échec and äöü finds ÄÖÜ, whatever the database's own rules. That is what message_search is for: SQLite's LIKE folds only ASCII case, and PostgreSQL's ILIKE folds with the column collation / LC_CTYPE (ASCII-only under C). The store fills message_search on insert and matches the lowercased term against it with a plain LIKE. Wildcards typed in the search (%, _, \) are matched literally.

Rows without it — inserted by your own code outside the store — fall back to searching message with the database's folding (LIKE on libSQL, ILIKE on PostgreSQL). Backfill them once so every row folds Unicode case:

import { eq, isNull } from "drizzle-orm";

const rows = await db
  .select({ id: sitepingFeedbacks.id, message: sitepingFeedbacks.message })
  .from(sitepingFeedbacks)
  .where(isNull(sitepingFeedbacks.messageSearch));

for (const row of rows) {
  await db
    .update(sitepingFeedbacks)
    .set({ messageSearch: row.message.toLowerCase() })
    .where(eq(sitepingFeedbacks.id, row.id));
}

Run the backfill in JavaScript, not with SQL lower(): the database's lower() follows the same locale rules the column exists to avoid.

Errors

• A database failure on a write (read-only or full database, lost connection, rejected statement…) surfaces as StorePersistenceError, with the driver error as cause. Detect it with isStorePersistence.
• updateFeedback reads the (immutable) annotations before updating the row, so no database call runs after the update commits: a failed annotation read leaves the row untouched, and an applied update is never reported as failed because of a read that followed it.
• updateFeedback and deleteFeedback on an unknown id throw StoreNotFoundError.

Both entries re-export StorePersistenceError, isStorePersistence, StoreNotFoundError and StoreDuplicateError, so you can catch them without another import.

Limitations

• PostgreSQL and libSQL only. There is no MySQL entry yet.
• libSQL only through drizzle-orm/libsql. Other SQLite drivers (better-sqlite3, Cloudflare D1) are not supported.
• One local libSQL file shared by several processes. SQLite runs one writer at a time: set the client's busy timeout — drizzle({ connection: { url: "file:siteping.db", timeout: 5000 } }) — so concurrent writes queue instead of failing with SQLITE_BUSY.
• Foreign keys on libSQL. Cascades need PRAGMA foreign_keys = ON, which libSQL does not guarantee, so the store deletes annotations explicitly alongside their feedback. Feedbacks you delete yourself outside the store need the same care.
• Search on rows without message_search folds case the database's way (ASCII-only on libSQL, and on PostgreSQL under a C collation / LC_CTYPE) until you backfill them.