## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The server holds long advisory-lock transactions on dedicated
database connections (`withDedicatedDbConnection`): workspace source and
lifecycle locks, the skill cache lock, agent-directory operations,
status cards and others
> - `withDedicatedDbConnection` kept at most 4 idle connections, but it
had no limit on connections in use. A run start can hold two at once,
because the source lock nests the lifecycle lock
> - After a restart or deploy, a burst of run starts can open hundreds
of connections. That can exceed the database's `max_connections` at the
moment recovery needs the database most. The documented per-process
total (`DATABASE_POOL_MAX` + 2) was also wrong
> - This pull request bounds the dedicated connections in use with a
fair queue, keeps nested and in-transaction callers deadlock-free, and
states the real connection budget
> - The benefit is that a restart burst of 200 or 1,000 run starts
completes within the limit (at most 48 in use with the default limit of
24), where before most of the starts failed with "too many clients"
## Linked Issues or Issue Description
**What existing behavior does this improve?**
`withDedicatedDbConnection`, which gives long advisory-lock transactions
a connection outside the main pool.
**Subsystem affected**
Database client (`packages/db/src/client.ts`) and the connection-sizing
documentation.
**Current behavior**
Nothing bounds the dedicated connections in use; only 4 idle ones are
kept. A run start can hold two at once (the source lock nests the
lifecycle lock). A burst of run starts after a restart can open hundreds
of connections and exceed `max_connections`. The documented per-process
total (`DATABASE_POOL_MAX` + 2) is wrong.
**Proposed behavior**
A per-process limit on dedicated connections in use
(`DATABASE_DEDICATED_CONNECTION_MAX`, default 24) with a first-in,
first-out queue. A caller that already holds a dedicated connection, or
runs inside an open transaction, never waits, because its wait could
deadlock with the holder that blocks it. After
`DATABASE_DEDICATED_CONNECTION_WAIT_MS` (default 30 s), a queued caller
gets a connection over the limit, so a lock cycle that PostgreSQL cannot
see ends in a delay, not a hang. The documentation states the real
per-process budget.
**Reason and benefit**
At 50 agents, staging showed about 9 new connections per second from
this function. At 1,000 agents, a restart burst can take the database
down when recovery needs it most. With the default limit of 24, a burst
of 200 or 1,000 starts completes with at most 48 dedicated connections
in use.
**Additional context**
Refs the 1,000-concurrent-agents plan
(`doc/plans/2026-11-13-thousand-concurrent-agents.md`). Reusing the
outer session for a nested lock was considered. The locks are
transaction-level advisory locks (`pg_advisory_xact_lock`), so a nested
lock in the outer transaction would be held until the outer transaction
ends, which changes lock lifetimes and order.
## What Changed
- `packages/db/src/client.ts`: `withDedicatedDbConnection` admits
callers against a per-owner limit (`DATABASE_DEDICATED_CONNECTION_MAX`,
option `dedicatedConnectionMax`, default 24) with a first-in, first-out
queue. The slot is released after the connection is returned or closed.
- Nested callers (an active dedicated hold of the same owner in the
async context) and callers inside an open transaction of a client from
this process are admitted without a wait. The transaction marker is an
`AsyncLocalStorage` scope that ends when the transaction callback ends.
- A queued caller is admitted over the limit after
`DATABASE_DEDICATED_CONNECTION_WAIT_MS` (option
`dedicatedConnectionWaitMs`, default 30000).
- `dedicatedDbConnectionStats(db)` reports the limit, in-use, peak,
waiting, queued, over-limit and nested-over-limit counts.
- `PRIVATE_POOL_MAX_CONNECTIONS` names the private pool sizes that were
literals, and `databaseConnectionBudget()` returns the per-process worst
case: main pool + 9 private + 2 listeners + 2 x limit + 4 idle dedicated
= 73 with the defaults.
- `server/src/services/skill-package-store.ts`: an isolated package read
takes its package I/O permit before its dedicated connection, and takes
a second dedicated connection only for the cache trim after a publish.
Before, each of up to 32 queued readers held a dedicated connection
while it waited for one of 2 permits. `skillPackageStorageIoDepth()`
reports the queue for the store's test.
- `withDedicatedDbConnection(db, action, { admitWithoutWaiting: true })`
admits a caller at once. The skill package store passes it for the
dedicated connections it takes while it holds a package permit, so a
permit holder never waits for a slot that a cache-lock owner holds while
that owner waits for the permit. The overshoot is bounded by the permits
(2 storage, 2 response).
- `doc/DATABASE.md` and `docs/deploy/database.md`: document the
admission rules, the two new variables and the real connection budget,
which replaces "`DATABASE_POOL_MAX` + 2".
## Verification
- New `packages/db/src/dedicated-connection-admission.test.ts` (embedded
PostgreSQL, `max_connections` 100). A restart burst with the default
limit: each start holds a source advisory lock on a dedicated connection
and nests a lifecycle lock on a second one, 40 ms in all.
- Before (same burst, scratch test on master): 200 starts gave 151
failures ("sorry, too many clients already") and 99 dedicated sessions
open. 1,000 starts gave 823 failures and 99 sessions.
- After: 200 starts gave 0 failures, 45 sessions, peak in use 48, queue
wait p50 541 ms / p99 815 ms. 1,000 starts gave 0 failures, 40 sessions,
peak in use 48, wait p50 1,767 ms / p99 3,422 ms. The wait is the queue
of this synthetic burst of 40 ms holds. Before, the same callers waited
about as long for connection setup, and most then failed.
- Steady state: 20 concurrent holders under the limit are never queued
(`queued: 0`).
- Nested acquisition: with a limit of 2, two holders each take a nested
connection while a third caller is queued. All finish (no deadlock); the
queued caller runs after them.
- In-transaction caller: with a limit of 1, a pooled transaction holds a
row lock and then asks for a dedicated connection, while the one
dedicated holder waits for that row lock. The caller is admitted at once
and both finish. A hard limit would deadlock here.
- Resource holder: with a limit of 1, the slot holder waits for a
resource that a second caller holds. The second caller, with
`admitWithoutWaiting`, is admitted at once and both finish.
- Wait bound: with a limit of 1 and a 100 ms bound, a queued caller is
admitted over the limit after the bound.
- Budget: the sum of the actual `max` of every private pool equals
`databaseConnectionBudget().privatePools`, and the default total is 73.
- `skill-package-store.test.ts` ("does not load queued legacy bodies for
files reads"): 32 readers queue for package I/O while only the 2 active
readers hold dedicated connections, and the 33rd reader still gets
"busy" at once. With the old order and a limit of 24, CI showed only 22
readers reaching that queue. `skill-package-store`,
`skill-version-cache`, `company-skills-empty-runtime`,
`runtime-skill-preservation`, `company-skills-runtime-concurrency` and
`company-skills-service` pass locally. Two `company-skills.test.ts`
workspace-discovery tests fail locally on master too (same result with
this change), so they are not caused by it.
- `packages/db`: client, lazy-transaction, prepared-query,
response-capture, work-signal and dedicated-pool suites, 134 passed.
- `server`: skill-version-cache, status-card-evaluation-work,
git-workspace-expiration, execution-workspace-runtime-control-conflict,
agent-instruction-working-copies, company-skills-empty-runtime and
decisions-service suites: 413 passed. In one combined run under machine
load, git-workspace-expiration failed at file level with all its tests
passing; alone it passed 96 of 96.
- `npx tsc --noEmit` in `packages/db`: passes.
## Risks
- A caller that holds an application-level lock (for example a
filesystem lock) and then waits in the queue can block a dedicated
holder that needs that lock. The 30 s wait bound ends such a cycle with
a delay. The over-limit counter shows it.
- Nested and in-transaction callers do not wait, so the in-use count can
reach twice the limit with one level of nesting. The documented budget
counts this.
- In a large restart burst, run starts now queue for a slot instead of
opening new connections. Steady state (about 10 to 20 dedicated
connections at 1,000 runs) stays under the default limit of 24, so a
run's first turn does not wait there.
- The checkpoint pool (3 connections) can limit throughput at 1,000 runs
on a hosted database. This pull request does not change it; it needs an
owner decision on the hosted connection budget.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`), Claude Code agent with tool use
and code execution.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
21 KiB
Database
How to run Paperclip against PostgreSQL, change the schema, and write migrations.
This file holds database setup and the rules that apply to every schema change.
It is not a record of individual tables or features. The schema in
packages/db/src/schema/ and its tests describe those. Put a note about one
feature's tables in that feature's doc, or leave it in the PR description.
1. Embedded PostgreSQL — zero config
If you don't set DATABASE_URL, the server automatically starts an embedded PostgreSQL instance and manages a local data directory.
pnpm dev
That's it. On first start the server:
- Creates a
~/.paperclip/instances/default/db/directory for storage - Ensures the
paperclipdatabase exists - Runs migrations automatically for empty databases
- Starts serving requests
Data persists across restarts in ~/.paperclip/instances/default/db/. To reset local dev data, delete that directory.
If you need to apply pending migrations manually, run:
pnpm db:migrate
When DATABASE_URL is unset, this command targets the current embedded PostgreSQL instance for your active Paperclip config/instance.
This mode is ideal for local development and one-command installs.
Docker note: the Docker quickstart image also uses embedded PostgreSQL by default. Persist /paperclip to keep DB state across container restarts (see doc/DOCKER.md).
2. Local PostgreSQL (Docker)
For a full PostgreSQL server locally, use the included Docker Compose setup:
docker compose up -d
This starts PostgreSQL 17 on localhost:5432. Then set the connection string:
cp .env.example .env
# .env already contains:
# DATABASE_URL=postgres://paperclip:paperclip@localhost:5432/paperclip
Run migrations:
DATABASE_URL=postgres://paperclip:paperclip@localhost:5432/paperclip \
pnpm db:migrate
Start the server:
pnpm dev
3. Hosted PostgreSQL (Supabase)
For production, use a hosted PostgreSQL provider. Supabase is a good option with a free tier.
Setup
- Create a project at database.new
- Go to Project Settings > Database > Connection string
- Copy the URI and replace the password placeholder with your database password
Connection string
Supabase offers two connection modes:
Direct connection (port 5432) — use for migrations and one-off scripts:
postgres://postgres.[PROJECT-REF]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:5432/postgres
Connection pooling via Supavisor (port 6543) — use for the application:
postgres://postgres.[PROJECT-REF]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:6543/postgres
Configure
For the application runtime, use a direct PostgreSQL connection unless the database client has explicit prepared-statement configuration for your pooling mode:
DATABASE_URL=postgres://postgres.[PROJECT-REF]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:5432/postgres
If you later run the app with a pooled runtime URL, set DATABASE_MIGRATION_URL to the direct connection URL. Paperclip uses it for startup schema checks/migrations and plugin namespace migrations, while the app continues to use DATABASE_URL for runtime queries:
DATABASE_URL=postgres://postgres.[PROJECT-REF]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:6543/postgres
DATABASE_MIGRATION_URL=postgres://postgres.[PROJECT-REF]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:5432/postgres
If your transaction-mode pooler does not support protocol-level named prepared statements, set DATABASE_PREPARED_STATEMENTS=false. If your pooler supports them, you can opt in with DATABASE_PREPARED_STATEMENTS=true. Check your provider's pooler configuration before you enable this setting. Keep DATABASE_MIGRATION_URL on a direct connection. Do not edit database client source files as part of deployment setup.
Push the schema
# Use the direct connection (port 5432) for schema changes
DATABASE_URL=postgres://postgres.[PROJECT-REF]:[PASSWORD]@...5432/postgres \
pnpm db:migrate
Free tier limits
- 500 MB database storage
- 200 concurrent connections
- Projects pause after 1 week of inactivity
See Supabase pricing for current details.
Client tuning (optional)
All of these are optional; when unset, the driver defaults apply and behavior is unchanged — typical self-hosted setups need none of them:
DATABASE_PREPARED_STATEMENTS=false # use false when the pooler does not support named prepared statements
DATABASE_POOL_MAX=25 # connection pool size; default: 10
DATABASE_IDLE_TIMEOUT_SECONDS=60 # close idle pooled connections; default: 60 (0 = keep open)
DATABASE_CONNECT_TIMEOUT_SECONDS=10 # default: 30
DATABASE_MAX_LIFETIME_SECONDS=1800 # recycle a pooled connection after this long; default: 30-60 min (random)
DATABASE_APPLICATION_NAME=paperclip # application_name in pg_stat_activity; default: paperclip
withDedicatedDbConnection gives an action exclusive use of one session outside
the main pool (application name paperclip-workspace-finalization-lock). Each
createDb owner keeps at most DEDICATED_CONNECTION_IDLE_MAX (4) of these
single-connection clients idle for reuse; they follow the same idle timeout and
max lifetime as the main pool. At most DATABASE_DEDICATED_CONNECTION_MAX
(default 24) dedicated clients are in use at once per owner. A caller that
finds the limit reached waits in a first-in, first-out queue. A caller that
already holds a dedicated client, or runs inside an open transaction of the
same process, is admitted at once, because its wait could deadlock with the
holder that it blocks. A caller that holds another bounded resource that a
holder can need passes { admitWithoutWaiting: true } for the same reason; the
skill package store does this while it holds one of its package I/O permits
(at most 2 storage and 2 response permits). Such callers can take the in-use
count above the limit.
A caller that waits longer than DATABASE_DEDICATED_CONNECTION_WAIT_MS
(default 30000) is admitted over the limit, so a lock cycle that the database
cannot see ends in a delay, not a hang. A connection whose action throws is
closed, never reused. Actions must keep
session state transaction-scoped (pg_advisory_xact_lock,
set_config(..., true)). Like the main pool, a retained session sees an
ALTER DATABASE or ALTER ROLE ... SET change only after it reconnects; a test
that changes such a setting calls closeDedicatedDbConnections first. Shutdown
and ending the owner client close the idle set.
Connections per server process, at most (databaseConnectionBudget in
packages/db/src/client.ts computes this, and a test keeps it equal to the
pool settings):
| Source | Connections |
|---|---|
| Main pool | DATABASE_POOL_MAX (driver default 10) |
| Private pools: controller lease 2, legacy controller lease 1, controller-instance lease 1, runner checkpoint 3, file storage 2 | 9 |
| Notification listeners: plugin lifecycle 1, deployment notifications 1 | 2 |
Dedicated clients: 2 x DATABASE_DEDICATED_CONNECTION_MAX in use (one nested client per holder) + 4 idle |
52 with the default limit |
| Total with defaults | 73 |
A separate DATABASE_MIGRATION_URL adds a second owner with its own pools.
Admission over the limit after the wait bound can exceed this total.
An explicit DATABASE_PREPARED_STATEMENTS=true enables named prepared statements
for parameterized ORM queries, transactions, reserved connections, and dedicated
clients. Postgres.js manages the statement cache. This does not cache query
results. Bound values and returned data stay fresh. Explicit per-query options
still apply, including prepare: false and simple-protocol execution. With the
setting unset, ORM queries keep their existing unprepared behavior and tagged
SQL uses the driver default. With false, preparation stays disabled.
Switching between modes
The database mode is controlled by DATABASE_URL:
DATABASE_URL |
Mode |
|---|---|
| Not set | Embedded PostgreSQL (~/.paperclip/instances/default/db/) |
postgres://...localhost... |
Local Docker PostgreSQL |
postgres://...supabase.com... |
Hosted Supabase |
Your Drizzle schema (packages/db/src/schema/) stays the same regardless of mode.
Schema change workflow
When you change the data model:
-
Edit
packages/db/src/schema/*.ts. -
Export each new table from
packages/db/src/schema/index.ts. -
Generate the migration from the repository root:
pnpm db:generate -
Validate that everything compiles:
pnpm -r typecheck
pnpm db:generate compiles packages/db first, because
packages/db/drizzle.config.ts reads the compiled schema from dist/schema/*.js.
Then update every layer that the change affects: packages/shared types and
validators, server routes and services, and ui API clients and pages.
Migration compatibility with the running release
Paperclip Cloud starts a new release while the previous one is still serving
against the same database. Every migration is therefore classified by
packages/db/src/migration-compatibility.ts as one of:
| Class | Meaning | Examples |
|---|---|---|
online_compatible |
The previous release keeps working and no lock is held for long. A deployer applies it without a pause. | CREATE TABLE and anything on a table created in the same migration, CREATE INDEX CONCURRENTLY, ADD COLUMN that is nullable or has a constant default, ADD CONSTRAINT ... NOT VALID, CREATE TYPE, ALTER TYPE ... ADD VALUE |
requires_staging |
The previous release breaks or its writes are rejected. Ship it in two releases: expand first, contract later. | DROP TABLE/DROP COLUMN, renames, ALTER COLUMN ... TYPE, SET NOT NULL, DROP DEFAULT, a NOT NULL column without a default, a validated CHECK, a UNIQUE constraint or unique index on an existing table, TRUNCATE, DELETE |
unknown |
The classifier cannot prove either. This includes every statement it does not recognize and every lock or duration hazard (reason codes starting with lock_hazard_). |
plain CREATE INDEX on an existing table, a validated foreign key on an existing table, VALIDATE CONSTRAINT, UPDATE backfills, procedural DO blocks, CREATE OR REPLACE FUNCTION, triggers on existing tables, DROP INDEX, DROP CONSTRAINT |
A migration takes the worst class of its statements. Lock and duration hazards
are unknown, not compatible with a warning.
A table counts as created in the migration when the statement is a plain
CREATE TABLE, or a CREATE TABLE IF NOT EXISTS for a table that no earlier
migration created. IF NOT EXISTS on a table from an earlier migration proves
nothing, so later statements on that table are judged as changes to an existing
table.
drizzle-kit emits validated foreign keys and plain indexes. For an existing
table, edit the generated SQL: append NOT VALID to the foreign key, and use
CREATE INDEX CONCURRENTLY IF NOT EXISTS.
PostgreSQL rejects CONCURRENTLY inside a transaction, and the migrator runs
each migration file in one transaction. A migration that uses CONCURRENTLY
must therefore be listed in MIGRATIONS_WITH_TOP_LEVEL_STATEMENTS in
packages/db/src/client.ts, and every statement in it must be idempotent,
because a failed run starts again from the first statement. The pull-request
guard fails a new CONCURRENTLY migration that is not in that list.
The rule for a new migration. A pull request fails when a migration it adds
is unknown. Rewrite the migration, split it into expand and contract
migrations, or, when you have verified the migration yourself, state the class
in the first lines of the migration file:
-- paperclip:migration-compat online_compatible: <why the previous release keeps working and no lock is held long>
Use requires_staging in place of online_compatible when the previous
release cannot run against the migration. The justification is mandatory. The
override is read only from the migration file, so it is reviewed with the SQL
and travels with it. A contract migration (for example the DROP COLUMN that
follows an expand release) always classifies as requires_staging; mark it
online_compatible this way once no running release uses the column.
requires_staging does not fail the pull request yet; it prints a notice.
Check a migration locally:
cd packages/db
pnpm exec tsx scripts/migration-compatibility.ts src/migrations/0468_busy_wendell_rand.sql
pnpm exec tsx scripts/migration-compatibility.ts # distribution over all migrations
pnpm exec tsx scripts/migration-compatibility.ts --check # the pull-request guard
The guard runs in check:migrations (so in the @paperclipai/db typecheck and
build) against the merge base with origin/master, and in the pull-request
policy job through .github/scripts/check-pr-migration-order.mjs. Migrations
that were already on master when the classifier shipped are not annotated.
Deployers read the result from the cloud migrator manifest
(cloud-migrators/v1/<sha>/manifest.json, built by
scripts/cloud-migrator-artifacts.mjs). Its migrationCompatibility.migrations
array lists every packed migration in journal order with idx, tag,
sqlSha256 (the hash the migrator records in the migration history),
compatibility, classified (the classifier's verdict before an override),
override, overrideJustification, and reasons.
Migration authoring checklist
Older embedded databases can use SQL_ASCII. Test encoding-sensitive SQL on
both SQL_ASCII and UTF-8 databases.
The 0126 issue comment attribution backfill showed the failure mode this checklist is meant to prevent: each batch looked for the next rows with an unindexed predicate, so PostgreSQL repeatedly scanned the same table and the migration became O(n²) as the table grew.
When authoring migrations or one-time backfills:
- Create the supporting index for the batch predicate before the backfill loop runs.
- Bound batches by an indexed key, such as an id range or keyset pagination cursor. Do not use
OFFSETpagination or a query shape that re-scans already-visited rows each batch. - Avoid unbounded full-table
UPDATEorDELETEstatements. Add a selective predicate and process rows in bounded batches when table size can be large. - Use
CREATE INDEX CONCURRENTLYfor large existing tables when the migration can run outside a transaction and must avoid long write locks. - Split schema changes, index creation, and data backfill into separate phases so each step has clear locking and rollback behavior.
- Treat the
check:migrationsCI gate as the enforcement backstop for these rules. If it flags a migration, rewrite the migration or add a suppression comment with the indexed predicate, batch bound, and reason the remaining scan is safe.
Migration snapshots
drizzle-kit generate diffs packages/db/src/schema/ against the newest snapshot in packages/db/src/migrations/meta/. That snapshot must describe the schema that every migration produces when they run in order. A snapshot that drifts from the schema makes the next migration wrong, because generate folds the drift into it. The drift can add a column that an earlier migration already created, which makes that migration fail on a fresh database. It can also drop a column that the schema still uses.
- Create every migration with
pnpm --filter @paperclipai/db generate. Do not hand-write a snapshot. - Do not hand-edit a snapshot to resolve a merge conflict. Renumber your migration and run
generateagain, aspackages/db/.gitattributesdescribes. - The repo keeps only the newest 5 snapshots.
generaterunsprune:snapshotsafterwards to delete older ones. Drizzle only reads the newest snapshot, and each snapshot is a full copy of the schema (over 1 MB each). Older snapshots are still in git history. packages/db/src/migration-snapshot-drift.test.tsis the enforcement backstop. It repeats the diff thatgenerateperforms and fails when the newest snapshot no longer matchespackages/db/src/schema/.
Connection loss and retries
The database client does not replay arbitrary statements after a disconnect.
PostgreSQL may have committed a statement before the connection loses its
response. The postgres.js message write CONNECTION_CLOSED does not prove
that the statement was never sent: the driver also uses it when an in-flight
query loses its connection. SQL text cannot establish replay safety either;
a SELECT can call a function with side effects.
The affected operation fails and a new operation can reconnect through the pool. Callers may retry only when the complete operation is idempotent or has a durable receipt that prevents duplicate effects. Some transient statement failures therefore reach the caller instead of being retried automatically.
When a database connection closes, its transaction fails. Paperclip does not replay that transaction. New requests can use a fresh connection from the pool. Queries from the failed transaction must keep failing, even after the pool reconnects.
Transaction-aware delivery work signals
Durable delivery queues, including plugin resource lifecycle events, use process-local work signals to avoid empty polling. Register work before writing a queue row, on that row's transaction:
await db.transaction(async tx => {
await signalDatabaseWork(tx, "queue-topic");
await tx.insert(existingQueueTable).values(row);
});
createDb instruments transaction callbacks and nested savepoints. Subscribers
receive intent immediately and settlement only after the outer transaction
finishes. Caller-owned transactions therefore need no extra post-commit wrapper.
Dedicated clients from withDedicatedDbConnection share the owner's signal
scope. No schema changes, triggers, dedicated listener connection, or periodic
queries are installed by this API.
The first registered write in a transaction fetches pg_current_xact_id().
Awaiting registration is required: a failure at that point must prevent the
queue write. Unrelated transactions add no queries. If the transaction rejects,
the coordinator probes pg_xact_status(xid) through the root pool before scanning
the queue. An in-progress transaction remains unresolved even when the queue
currently looks empty. Committed/aborted results permit reconciliation; NULL
means PostgreSQL has discarded an old, no-longer-active transaction's outcome.
The existing durable queue supplies the work in either case. Probe failures
retain the idle hold and schedule another attempt. Work signals never replay
queries or convert a failed database operation into success.
This uses PostgreSQL's transaction-information functions (this path requires PostgreSQL 14+; embedded PostgreSQL uses 18). See the PostgreSQL transaction information documentation. The process-local intent survives coordinator replacement, but not process exit. Startup scans recover committed queue rows. Independent DB clients, other processes, late transactions from an old process, and database failover need an explicit ownership/wake protocol; these signals are not cross-process messaging. Use the same root client for in-process writers. New queue insertion paths must register before writing, or they can remain unseen until the next startup or another notification. Tests should verify both the producer and its outer transaction boundary.
Plugin database namespaces
The plugin runtime tracks plugin-owned database namespaces and migrations in plugin_database_namespaces and plugin_migrations. Hosted deployments that separate runtime and migration connections should set DATABASE_MIGRATION_URL; plugin namespace migration work uses the migration connection when present.
Backups
Paperclip supports automatic and manual logical database backups. These dumps include
non-system database schemas such as public, the Drizzle migration journal, and
plugin-owned database schemas. See doc/database-backups.md for the current
paperclipai db:backup / pnpm db:backup commands and backup retention
configuration.
Database backups do not include non-database instance files such as local-disk uploads, workspace files, or the local encrypted secrets master key. Back those paths up separately when you need full instance disaster recovery.
More documentation
| Area | Doc |
|---|---|
| Automatic backups and restore | database-backups.md |
| Response-size diagnostics, the postgres.js patch, transaction memory | database-client-internals.md |
| Remote workspace snapshot storage | workspace-storage.md |
| Execution admission tables | server/src/modules/README.md |