thelastapi
Get started free

A development database branch agents cannot break

A development database branch gives your tools and agents an isolated Postgres copy with your production schema, migration ledgers, and zero live rows.

On this page 9 sections

A development database branch is an isolated Postgres copy that clones your production schema and migration ledgers while stripping out every row of user data. When coding tools and AI agents work on your application, they connect directly to this development copy rather than production. Your agents can run migrations, insert test data, run queries, or wipe tables clean without any risk of altering live customer records or dropping live tables.

Giving coding agents direct database access speeds up development, but giving them production credentials risks catastrophic data loss. Here is how a development database branch works in thelastapi, what agents can and cannot touch, and how to manage schema updates safely.

Why agents need an isolated database branch

When you ask an AI agent or a coding assistant to build a feature, it usually needs to inspect your schema, run a migration, seed records, and verify queries. If you connect that assistant to production, any hallucinated query or bad command can corrupt live records. This is why agents should never touch production rows.

Setting up manual local mock databases has its own problems:

  • Drifted schemas. Local copies fall out of sync with production. Migrations run cleanly on an engineer's laptop but fail during deployment because tables or constraints do not match.
  • Accidental credential leaks. Developers copy production connection strings into local .env files to debug an issue quickly, leaving live credentials in plain text where an agent can read them.
  • Migration reruns. Re-running migration scripts against an empty manual database often fails if your ORM ledger does not match what production already knows about.

A dedicated development database branch solves this by providing a separate Postgres database per project that mirrors production structure while keeping all customer records completely inaccessible.

How the development copy works

When you initialize a database resource with thelastapi, you get a Postgres database for your project accessible via DATABASE_URL. The development copy is an exact architectural branch of that database:

  1. Schema mirroring. It contains production's schemas, tables, indexes, views, functions, triggers, and sequence positions.
  2. Zero production rows. Every table is emptied before the branch is handed out. The application's data rows and sign-in users and sessions are completely removed and verified.
  3. Preserved migration ledgers. Drizzle and Prisma migration ledgers are retained in the development branch. Your ORM recognizes that past migrations have already been applied, so your tooling will not attempt to run duplicate migrations.

The database runs plain Postgres over the internet, so any ORM, client library, or migration tool works without custom adapters. For more background on provisioning, see serverless Postgres for side projects: one database per project and the Database documentation.

Setting up your development branch with the CLI

You can spin up your development copy and write its connection variables to a local environment file in one command:

Terminal
vibiz dev

This provisions the development environment and writes DATABASE_URL (pointing to the development branch) into .env.development.local. The CLI prints variable names but conceals the secret values.

If you prefer to run your local dev server directly without saving an environment file to disk, pass your start command after --:

Terminal
vibiz dev -- npm run dev

To run your schema migrations against the branch, use your regular migration tools against the loaded environment:

Terminal
npx drizzle-kit migrate

If an agent or a test suite makes unwanted changes to the branch, you can discard it and start fresh:

Terminal
vibiz dev --reset

The --reset flag throws away the existing development copy. The next time you run vibiz dev, thelastapi branches from your production schema again.

What agents can and cannot do

When configuring AI agents, you provide them with an API key. In thelastapi, keys default to full access, but you can create a Limited key designed specifically for agents:

Terminal
vibiz keys create coding-agent --limited

A Limited key defaults strictly to the development environment. It cannot read production variables, cannot inspect production rows, and cannot execute commands against live data. More details about permissions are in Keys and environments.

The following table breaks down what agents can and cannot do across environments:

ActionDevelopment branchProduction database
Get DATABASE_URLYes (vibiz dev or limited key)No (full-access keys only)
Inspect tables and run read-only SQLYesNo (403 owner_only)
Write or insert rowsYes (using client and dev DATABASE_URL)Never for agents
Export database contentsYes (SQL and CSV)No (403 owner_only)

If an agent attempts to access production rows or variables through the API, the system returns a 403 forbidden error with details.reason: "owner_only" and names the missing permission (such as database.production:read).

Inspecting and querying the branch over HTTP

Agents and automated workflows do not always need to connect a complete Postgres client just to inspect schemas or verify data. thelastapi provides read-only API routes and agent actions to inspect the branch.

Inspecting schemas and tables

To inspect the schemas and tables with estimated row counts, query the /v1/projects/:id/database endpoint:

Terminal
curl "https://thelastapi.dev/v1/projects/prj_123/database?env=development" \
  -H "Authorization: Bearer $VIBIZ_API_KEY"

Agents using tool calls run vibiz_database { project_id } to get this same structural summary.

Running read-only queries

You can execute a single read-only SQL statement through the API:

Terminal
curl https://thelastapi.dev/v1/projects/prj_123/database/query \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"sql":"select table_name from information_schema.tables where table_schema = '\''public'\''","env":"development"}'

This read view has built-in guardrails:

  • It only accepts read-only statements: SELECT, WITH, TABLE, VALUES, EXPLAIN, or SHOW.
  • Query statements can be up to 20,000 characters long.
  • Execution timeout is capped at 5 seconds.
  • Results return up to 500 rows. If more rows exist, the response sets truncated: true.

If a query attempts to execute an INSERT, UPDATE, DELETE, or DROP statement in this read view, the endpoint responds with an invalid_request (HTTP 400). When agents need to write data during development or testing, they must connect using their own Postgres client to the development DATABASE_URL. This approach is ideal when you need to seed data in a development branch, not in production.

Connecting with an application client

Once your development branch is active, standard application code connects to it using plain Postgres drivers:

TypeScript
import postgres from 'postgres';

const sql = postgres(process.env.DATABASE_URL!);

// Querying the development copy
const rows = await sql`
  select id, email from users limit 10
`;
console.log('Development users:', rows);

When building an application hosted elsewhere, you can also load your environment directly using @vibiz/app. See the Use one service documentation for details on connecting external runtimes.

TypeScript
import { vibiz } from '@vibiz/app';

await vibiz.loadEnv();
// DATABASE_URL is now populated in process.env

Backups and exports

You can export your database at any time. The export engine produces a plain SQL file that can be restored into any standard Postgres 15+ instance:

Terminal
vibiz export --db --csv

This command generates a gzipped snapshot containing your schema, tables, indexes, views, sequences, and rows, along with CSV files for each table. For Limited keys used by agents, vibiz export automatically defaults to exporting the development environment. Attempting to export the production database or download secret .env values with a Limited key will result in a 403 owner_only refusal. Complete export details can be found on the Export documentation.

Database branch pricing and limits

Database branches in thelastapi follow simple usage accounting:

  • Limit: Exactly one database per project, and one development branch per project.
  • Cost: Usage records each ready database at an estimated $0.02 a day of cost, billed with the default margin (+20% today, shown as billed_usd in usage) while finalized pricing is not decided.
  • Handling delays: If a branch is still provisioning when queried, the API returns 409 dependency_not_ready. Running vibiz dev triggers provisioning.

To get started with an isolated database branch for your agents and local tests, run vibiz init <name> --resources database and run vibiz dev in your project folder.

Frequently asked questions

Does a development database branch contain any live user data?

No. Every development branch is created with production schemas and migration ledgers, but all application rows, sign-in users, and active sessions are stripped and checked before access is granted.

Can an AI agent run schema migrations against the development database?

Yes. Agents can run migration tools like Drizzle or Prisma using their own database client connected to the development `DATABASE_URL`. Migration ledgers are preserved so past migrations do not rerun.

What happens if an agent tries to modify data through the read-only database API?

Any statement in the read view that would write data (such as `INSERT` or `UPDATE`) is rejected with a `400 invalid_request` error. Write operations require using a direct Postgres connection with the development `DATABASE_URL`.

How can I reset a corrupted development branch?

Run `vibiz dev --reset`. This command deletes the existing development branch, and the next `vibiz dev` command branches fresh from your production schema.