# Seed data in a development branch, not in production

> Seed development databases safely using an isolated branch with empty tables, keeping test fixtures away from production rows.

**To seed a database for development safely, run your seed scripts against an isolated development branch that contains your production schema but none of your production rows.** thelastapi provisions this automatically when you run `vibiz dev`, giving you a separate development `DATABASE_URL` with emptied tables and preserved migration ledgers. Your local tools and AI agents can insert mock users, catalog items, and test state without any chance of corrupting live data.

Writing mock records directly to a shared database or a production database is dangerous. When developers or autonomous coding tools populate tables with fake emails, mock billing identifiers, or synthetic orders, clean boundaries disappear. This guide covers how development database branching works in thelastapi, how to run seeding scripts against your development branch, and how to start over whenever your mock data gets messy.

## Why seed data must never touch production

Local feature work and test suites require realistic data: user accounts with verified states, active subscriptions, mock inventory, and related records across multiple tables. However, mixing seed scripts with production data introduces critical problems:

- **Customer disruption.** A naive `DELETE FROM users` or an automated truncation in a seed script will destroy live accounts. Even an additive seed script can pollute public search indexes, send unwanted mock emails to real addresses, or create fake analytics events.
- **Agent drift.** AI tools like Claude Code, Cursor, and Codex frequently run scripts to verify new features. If an agent holds credentials to a database containing live rows, an errant migration or poorly bounded seed script can drop production constraints or overwrite customer records. We explain this boundary further in [why agents should never touch production rows](https://thelastapi.dev/blog/agents-never-touch-production-rows).
- **Schema mismatch.** Developing against a stale local copy often leads to failed migrations when deploying. You need the exact schema of production, but none of the live data.

By separating environments completely, you can populate hundreds of mock records, test edge cases, and delete records at will, knowing your production database remains untouched.

## How the development database branch works

When you add a database to your project (`vibiz init my-app --resources database` or `vibiz add database`), thelastapi provisions serverless Postgres accessible over the public internet. You can read more about connection options in the [Database documentation](https://thelastapi.dev/docs/database).

Every database comes with two environments: production and development. The development copy is not a completely blank database that you have to configure by hand, nor is it a clone of your customers' records. Instead, it is an automated branch that features:

1. **Identical schema.** All schemas, tables, indexes, keys, triggers, and sequences match production.
2. **Empty tables.** Every table is completely emptied before the branch is handed out. This applies to your application tables as well as built-in tables like sign-in users and sessions.
3. **Preserved migration ledgers.** Migration tracking tables (such as those used by Drizzle or Prisma) retain their state. This ensures your migration runner recognizes that existing schema steps have already run, so it will not attempt to re-apply old migrations on an empty branch.

Usage records each ready database at an estimated cost of $0.02 per day, billed with the default margin (+20% today, displayed as `billed_usd` in usage).

Here is how the two environments compare:

| Property | Production | Development branch |
| --- | --- | --- |
| Tables and schemas | Live schema | Identical copy of live schema |
| Application rows | Real customer data | Emptied upon branch creation |
| Migration ledger | Live ledger | Preserved from production |
| Access | Full-access keys only | Full-access and Limited keys |
| AI agent access | Read/write blocked | Read/write permitted via development URL |
| Reset options | Manual migrations | Instant wipe with `vibiz dev --reset` |

Because Limited keys and AI agents only receive credentials for the development copy, you can let an agent run database tasks freely. For more details on environment isolation, see [a development database branch agents cannot break](https://thelastapi.dev/blog/development-database-branch-agents) and [Keys and environments](https://thelastapi.dev/docs/keys).

## Connecting your local environment

To start developing and seeding locally, request your development credentials using the CLI:

```bash
vibiz dev
```

This command provisions the development copy if it does not already exist, retrieves its connection string, and writes `DATABASE_URL` (along with development sign-in and AI credentials) to `.env.development.local`. The secret values are never printed directly in your terminal output.

If you prefer not to write a file to disk, you can pass the environment directly to your application or migration runner:

```bash
vibiz dev -- npm run dev
```

Because the database is standard Postgres over the internet, you can use any ORM, migration tool, or client library, including Drizzle, Prisma, or the standard `postgres` client.

## Writing and running a seed script

Once your development database is provisioned, you can write a seeding script that inserts the records your application needs to function locally.

Here is an example using TypeScript and the `postgres` driver to seed an organization, several mock users, and related profile records:

```ts
import postgres from 'postgres';

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

async function seed() {
  console.log('Seeding development database...');

  // Clean out any previous test data
  await sql`TRUNCATE TABLE profiles, users CASCADE`;

  // Insert mock users
  const users = await sql`
    INSERT INTO users (id, email, name, role)
    VALUES 
      ('usr_01', 'ana@example.com', 'Ana Silva', 'admin'),
      ('usr_02', 'ben@example.com', 'Ben Chen', 'member')
    RETURNING id, email;
  `;

  for (const user of users) {
    await sql`
      INSERT INTO profiles (user_id, bio, onboarded)
      VALUES (${user.id}, 'Development seed account', true);
    `;
  }

  console.log(`Seeded ${users.length} users successfully.`);
  await sql.end();
}

seed().catch((err) => {
  console.error('Seeding failed:', err);
  process.exit(1);
});
```

To run this seed script against your development branch, execute it with `vibiz dev`:

```bash
vibiz dev -- node --loader ts-node seed.ts
```

If you manage your schema using an ORM migration tool, you can run migrations and seeds in sequence:

```bash
vibiz dev -- npx drizzle-kit migrate
vibiz dev -- npm run seed
```

If you are running separate microservices or independent tools alongside your primary app, you can provision databases per project as outlined in [Serverless Postgres for side projects: one database per project](https://thelastapi.dev/blog/postgres-database-per-project).

## Querying development rows over HTTP

You do not need to install `psql` or open a database client to inspect whether your seed data landed properly. thelastapi provides read-only HTTP endpoints for checking schema and querying data directly.

To view tables and row estimates in your development branch:

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

To run an ad-hoc read query:

```bash
curl https://thelastapi.dev/v1/projects/prj_123/database/query \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "sql": "SELECT id, email, role FROM users LIMIT 10",
    "env": "development"
  }'
```

The database query endpoint is strictly read-only. It permits a single `SELECT`, `WITH`, `TABLE`, `VALUES`, `EXPLAIN`, or `SHOW` statement. It accepts up to 20,000 characters, runs for at most 5 seconds, and returns up to the first 500 rows (setting `truncated: true` if more exist). Attempting to run a write query like `INSERT` or `UPDATE` through this endpoint returns a `400 invalid_request` error. To write seed rows, always connect directly using `DATABASE_URL`.

## Resetting dirty seed data

During feature development, mock data quickly becomes inconsistent. You might create partially completed checkouts, half-deleted records, or test accounts in malformed states. Rather than writing complex cleanup scripts to unpick damaged relationships, you can wipe the branch entirely.

Run the reset flag:

```bash
vibiz dev --reset
```

This throws away the current development copy. The next time you run `vibiz dev`, the platform provisions a brand-new development branch cloned from your production schema, empties every table, ensures migration ledgers are intact, and supplies clean connection details. You can then run your seed script against a fresh slate.

## Next steps

To set up an isolated database branch for your project, install the CLI and run `vibiz dev` to write your local environment variables. If you need to manage access for your team or automated agents, review [Keys and environments](https://thelastapi.dev/docs/keys) to configure Limited keys that can safely seed and test without viewing production data.

## Frequently asked questions

### Does creating a development database branch copy sensitive production data?

No. When thelastapi creates a development branch, it copies your production table schemas and migration ledgers, but empties every table before providing the connection string. Production customer data is never copied to the development branch.

### Can an AI agent or Limited key accidentally run a seed script against production?

No. Limited keys and automated agents only receive credentials for the development branch via `vibiz dev`. Requests from limited keys to access production database credentials return a `403 forbidden` error with `details.reason: "owner_only"`.

### What happens if I make a mistake while seeding my development branch?

You can throw away the messy development branch at any time by running `vibiz dev --reset`. The next call to `vibiz dev` will branch a clean copy from your current production schema with empty tables.

---

Published 2026-11-15 · https://thelastapi.dev/blog/seed-data-development-branch
