thelastapi
Get started free

Get a Postgres DATABASE_URL in one command

Run vibiz dev to get a working Postgres DATABASE_URL written directly to .env.development.local with your schema ready for migrations.

On this page 10 sections

You can get a working Postgres DATABASE_URL in one command by running vibiz dev. The command provisions or connects to your project's development branch and writes the connection string straight into .env.development.local. Any Postgres client, ORM, or migration tool connects immediately over the internet without extra infrastructure setup.

Whether you are starting a local script or handing a workspace to an AI coding agent, this guide shows you how to initialize a database, fetch the connection string, and run queries.

How to initialize a database and get your URL

If you are starting a fresh project with a database, you only need two commands in your terminal:

Terminal
vibiz init my-backend --resources database
vibiz dev

The first command creates the project and provisions a Postgres database. The second command, vibiz dev, provisions the development copy and writes the environment variables to .env.development.local. When you inspect that file, DATABASE_URL is already set.

If you already have an existing project and want to add Postgres to it, run:

Terminal
vibiz add database
vibiz dev

You can read more about how isolated environments work across development and production in Serverless Postgres for side projects: one database per project and in the Database documentation.

What kind of database is behind the URL?

The DATABASE_URL connects to a real Postgres database over the internet. There are no proprietary query layers or custom drivers required. You can connect using psql, node-postgres, or whatever client library you prefer:

TypeScript
import postgres from 'postgres';

const sql = postgres(process.env.DATABASE_URL!);
const rows = await sql`select id, email from users limit 10`;

Migrations run directly against this database. If you use tools like Drizzle or Prisma, point them at DATABASE_URL and execute your standard migration commands:

Terminal
npx drizzle-kit migrate

For a deeper dive into wiring schemas and migration scripts, see our guide on how to use Postgres from Next.js with Drizzle or Prisma.

How does the development branch protect production?

Every database resource includes two environments: production and development. When you or an AI agent run vibiz dev, you receive the connection string for the development copy, not the production database.

The development copy is a dedicated branch created specifically for safe local execution and coding agents:

  • It copies the production schema and table definitions.
  • It keeps migration ledgers (such as Prisma's or Drizzle's), so migrations do not rerun unnecessarily.
  • It contains none of production's rows. Every table is emptied, checked, and only then handed out.

If you ever need to discard local testing data and restart from a clean slate matching production's schema, pass the --reset flag:

Terminal
vibiz dev --reset

The next time you run vibiz dev, the platform provisions a fresh branch with empty tables.

How do permissions and keys control database access?

Access to database credentials depends on the key you use. thelastapi provides two primary access tiers for API keys: Full-access keys and Limited keys.

CapabilityDevelopment copyProduction database
Retrieve DATABASE_URL via vibiz devYes (Full and Limited keys)No (Full-access keys only)
Connect via local client or ORMYesYes (with owner credentials)
Read via API (/database/query)Yes (up to 500 rows)No (403 owner_only)
Execute schema migrationsYesYes (Full-access keys only)

Limited keys (held by agents or untrusted environments) can freely read and write the development copy using their own client, but they can never view production rows or fetch production secrets. If an agent attempts to access production database data, the API returns a 403 forbidden error with details.reason: "owner_only". To learn more about controlling permissions, check the Keys and environments documentation.

If you want an agent or service to read production data without full access, the account owner can grant the single permission database.production:read:

Terminal
vibiz keys access key_123 allow database.production:read

How can you query the database over HTTP?

Sometimes you want to inspect tables or verify state without installing a Postgres driver or opening an interactive SQL shell. thelastapi provides HTTP endpoints for read-only inspection.

To inspect the schemas and tables with row estimates:

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

To run a single read-only SQL statement against the development environment:

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"}'

Read queries over HTTP have specific limits:

  • The statement must be a single SELECT, WITH, TABLE, VALUES, EXPLAIN, or SHOW statement.
  • The statement can be up to 20,000 characters.
  • Query execution times out after 5 seconds.
  • The API returns up to 500 rows; results beyond that are marked with truncated: true.

Attempting to run an INSERT, UPDATE, or DELETE statement through this HTTP endpoint returns a 400 invalid_request error. To write data, connect directly with a standard Postgres client using your DATABASE_URL.

How to use the database from external hosts

You do not need to host your web application on thelastapi to use the database. The database is a standalone resource that works from any cloud provider, container, or virtual private server.

To use the database in external production environments, you have two options:

Option 1: Load environment variables with the app key

Provide the application with its single production app key (VIBIZ_APP_KEY), install @vibiz/app, and call vibiz.loadEnv() at startup:

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

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

You can also evaluate the variables directly into a shell environment:

Terminal
eval "$(curl -fsS -H "Authorization: Bearer $VIBIZ_APP_KEY" \
  https://thelastapi.dev/v1/app/env?format=shell)" && exec node server.js

Option 2: Pull variables during build or CI

If your build pipeline generates static bundles or pre-populates configuration files, use vibiz env pull:

Terminal
npx @vibiz/cli env pull --format dotenv -o .env.production

For full details on using single standalone services outside our hosting platform, review the guide on how to use a managed Postgres database from an app hosted anywhere and the Use one service documentation.

How to export your database and avoid lock-in

Because the service uses standard Postgres, you can export your entire database at any time. thelastapi provides native export tools that generate clean snapshots that any standard Postgres 15+ instance can restore:

Terminal
vibiz export --db

This generates a compressed archive (<slug>-<env>-database.sql.gz) containing schemas, tables, rows, indexes, constraints, views, and functions without proprietary ownership grants. You can restore it to any Postgres database with:

Terminal
gunzip -c shop-production-database.sql.gz | psql "$NEW_DATABASE_URL"

For more on exports, backups, and data portability, consult the Export documentation.

Pricing and limits

Database resource limits and pricing are straightforward:

MetricSpecification
Databases per projectOne production database, one development branch
PricingEstimated $0.02/day cost (+20% default margin, billed_usd in usage)
HTTP read query limit5 seconds timeout, 500 row maximum
HTTP table page limitUp to 200 rows per page
Read statement sizeAt most 20,000 characters

Next steps

To get started right now, run vibiz init my-project --resources database followed by vibiz dev. If you also need authentication and deployment along with your database, follow our walkthrough on how to deploy a Next.js app with a database and sign-in in one command. You can create your account at thelastapi.dev/start.

Frequently asked questions

Where does vibiz dev store the development DATABASE_URL?

The `vibiz dev` command writes the development database connection string directly into `.env.development.local` in your current project folder.

Can an AI agent access production rows with the database URL?

No, Limited keys and AI agents only receive access to the development branch via `vibiz dev`, which contains all schema tables but none of production's rows. Production database access requires an account owner's full-access key or the specific `database.production:read` permission grant.

How do I run a command with the development DATABASE_URL without writing a file?

You can pass your command directly to the dev runner using `vibiz dev -- <command>`, such as `vibiz dev -- npm run dev`.

What happens if I try to execute an INSERT or UPDATE statement over the HTTP query endpoint?

The HTTP `/database/query` route is strictly read-only and will return a `400 invalid_request` error on write statements; to write rows, use your own Postgres client library pointed at `DATABASE_URL`.