Ephemeral databases

An ephemeral database is a real Postgres database you can create without signing up. It is the same thing every CapyDB project runs on - its own database cell, its own credentials, TLS on every connection, a pooled and a direct connection string - with one difference: 72 hours after it is created it is destroyed, data included, unless you claim it.

Use one to run a demo, test an app against real Postgres, give a coding agent somewhere to work, or try CapyDB before deciding anything. If what you built is worth keeping, claim the database and it becomes an ordinary project with nothing to migrate.

Ephemeral database or preview database?

They solve different problems:

Reach for a preview when you already have a project and want a branch of it. Reach for an ephemeral database when you have nothing yet.

Create one

In the browser

Open capydb.dev/ephemeral and press the button. The page shows the connection strings once the database is up, and remembers the database in that browser so a reload finds it again.

From the CLI

capydb ephemeral create

No login happens. The CLI creates the database, waits for it, and writes DATABASE_URL (plus the direct and pooled variants your framework uses) into your env file, exactly as capydb create does for a project. It also makes sure that env file is git-ignored.

capydb ephemeral create --name scratch --postgres-version 18
capydb ephemeral create --no-env -o json   # print the connection strings instead of writing a file
capydb ephemeral status                    # state and time left

From a coding agent

The MCP server exposes create_ephemeral_database and get_ephemeral_database. They are the server's only tools that need no authentication, so an assistant can give a project a working database without stopping to send you through sign-up. claim_ephemeral_database keeps it, and does require you.

From the API

curl -X POST https://capydb.dev/api/capydb/v1/ephemeral-databases

{
  "claim_token": "eph_…",
  "claim_url": "https://capydb.dev/dashboard/claim/prj_…?token=eph_…",
  "ephemeral_database": {
    "project_id": "prj_…",
    "name": "ephemeral-7f3a91c2",
    "state": "provisioning",
    "region": "…",
    "expires_at": "2026-09-25T09:30:00Z"
  }
}

The body is optional; name, region and postgres_version are the only fields. Provisioning is asynchronous and usually takes a few seconds. Poll the read with the claim token until state is ready - that response carries the connection strings:

curl https://capydb.dev/api/capydb/v1/ephemeral-databases/prj_… \
  -H "X-CapyDB-Claim-Token: eph_…"

state is provisioning, ready or failed. A failed database is not retried; create another one.

The claim token

The claim token is the only credential an unclaimed database has. It reads the connection strings back and it authorizes the claim.

• It is returned once, when the database is created. CapyDB stores only a hash of it, so it cannot be looked up or reissued.
• The CLI keeps it in .capydb/ephemeral.json (mode 0600, inside a git-ignored directory). The browser page keeps it in that browser's local storage.
• The claim link embeds it. Treat the link like a password.
• It stops working the moment the database is claimed or expires. From then on the read answers 404, and a claimed database is read through the normal project endpoints by the organization that owns it.

If you lose the token the database cannot be recovered or claimed. It keeps running until its 72 hours are up, and then it is gone.

Claim it

Claiming attaches the database to an organization. From that moment it is an ordinary project:

• it no longer expires,
• it gains the default nightly backup schedule,
• it runs on the organization's plan and counts against the plan's project limit,
• its data and its connection strings do not change, so the app you pointed at it keeps running. There is no export, no import and no cutover.

capydb ephemeral claim

The CLI logs you in if needed (which is also where sign-up and plan selection happen for a new account), claims the database, and links the directory to the new project. In the browser, open the claim link; from the API:

curl -X POST https://capydb.dev/api/capydb/v1/ephemeral-databases/prj_…/claim \
  -H "Authorization: Bearer $CAPYDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"claim_token": "eph_…"}'

Claiming needs the same things as creating a project: an organization with an active plan (every plan starts with a month free) and room under its project limit. It is safe to retry: a repeated claim by the same organization returns the project again. A claim answers 409 when another organization got there first, when the database has already expired, or while it is still being created.

The database arrives sized for the smallest plan. If your plan is larger, CapyDB resizes it to your plan's limits shortly after the claim.

Because the connection string was issued before the database had an owner, consider rotating its credentials after you claim it if the string has been anywhere you would not put a production secret - a chat transcript, a screen share, a CI log.

Limits

• 72 hours, fixed. The lifetime cannot be extended. Claim the database to keep it.
• Sized like the Vibe plan: 2 GB of storage, 15 connections, a 30 second statement timeout.
• Pauses when idle and resumes on the next connection, like any non-production CapyDB database.
• No backups and no point-in-time restore until it is claimed.
• Capped platform-wide. Only so many unclaimed ephemeral databases may exist at once. When every slot is in use the create answers 503; slots free up as databases expire or are claimed, so try again later rather than in a loop.
• Rate limited per address. A 429 means you have created several recently.

An unclaimed ephemeral database is not the place for anything you cannot afford to lose.