thelastapi
Get started free

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.

On this page 8 sections

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.
  • 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.

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:

PropertyProductionDevelopment branch
Tables and schemasLive schemaIdentical copy of live schema
Application rowsReal customer dataEmptied upon branch creation
Migration ledgerLive ledgerPreserved from production
AccessFull-access keys onlyFull-access and Limited keys
AI agent accessRead/write blockedRead/write permitted via development URL
Reset optionsManual migrationsInstant 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 and Keys and environments.

Connecting your local environment

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

Terminal
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:

Terminal
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:

TypeScript
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:

Terminal
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:

Terminal
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.

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:

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

To run an ad-hoc read query:

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 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:

Terminal
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 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.