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

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

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

```bash
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](https://thelastapi.dev/blog/postgres-database-per-project) and in the [Database documentation](https://thelastapi.dev/docs/database).

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

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

```bash
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](https://thelastapi.dev/blog/postgres-nextjs-drizzle-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:

```bash
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.

| Capability | Development copy | Production database |
| --- | --- | --- |
| Retrieve `DATABASE_URL` via `vibiz dev` | Yes (Full and Limited keys) | No (Full-access keys only) |
| Connect via local client or ORM | Yes | Yes (with owner credentials) |
| Read via API (`/database/query`) | Yes (up to 500 rows) | No (`403 owner_only`) |
| Execute schema migrations | Yes | Yes (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](https://thelastapi.dev/docs/keys).

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

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

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

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

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

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

```bash
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](https://thelastapi.dev/blog/postgres-from-any-host) and the [Use one service documentation](https://thelastapi.dev/docs/use-one).

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

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

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

For more on exports, backups, and data portability, consult the [Export documentation](https://thelastapi.dev/docs/export).

## Pricing and limits

Database resource limits and pricing are straightforward:

| Metric | Specification |
| --- | --- |
| Databases per project | One production database, one development branch |
| Pricing | Estimated $0.02/day cost (+20% default margin, `billed_usd` in usage) |
| HTTP read query limit | 5 seconds timeout, 500 row maximum |
| HTTP table page limit | Up to 200 rows per page |
| Read statement size | At 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](https://thelastapi.dev/blog/deploy-nextjs-app-database-sign-in). You can create your account at [thelastapi.dev/start](https://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`.

---

Published 2026-11-15 · https://thelastapi.dev/blog/get-database-url-one-command
