> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# vetta db

> Work with a fullstack app's managed database from the terminal: SQL, tables, migrations.

Every `fullstack` [app](/docs/cli/apps) comes with a managed Postgres database. These commands reach it
without a connection string. API detail: [Database](/docs/api/database).

Every command takes an optional `--app <id-or-name>`. **Omit it when the organization has one
`fullstack` app** — that app is resolved for you. With several, the command fails with
`ambiguous_app` and lists the candidates; name one. With none, `not_found`: make one with
`vetta app create <name> --type fullstack`.

`query` and `migrate` require the `agents:write` scope; `tables` and `migrations` require `agents:read`.

## Commands

| Command                       | Description                                             |
| ----------------------------- | ------------------------------------------------------- |
| `vetta db query "<sql>"`      | Run SQL and print the rows.                             |
| `vetta db tables`             | List the database's tables with row and size estimates. |
| `vetta db migrate <file.sql>` | Apply a SQL file as a named migration, once.            |
| `vetta db migrations`         | List the migrations that have been applied.             |

## query

```bash theme={"system"}
vetta db query "select count(*) from todos"
vetta db query "insert into todos (title) values ('ship it')" --app storefront
```

```json theme={"system"}
{ "object": "app_db_result", "rows": [{ "count": 3 }], "row_count": 1 }
```

## tables

```bash theme={"system"}
vetta db tables
```

```json theme={"system"}
{ "data": [{ "object": "db_table", "name": "todos", "schema": "public", "rows": 3, "size_bytes": 16384 }] }
```

## migrate

```bash theme={"system"}
vetta db migrate sql/0001_todos.sql
vetta db migrate sql/0001_todos.sql --name todos --app storefront
```

| Flag     | Description                                                                                  |
| -------- | -------------------------------------------------------------------------------------------- |
| `--name` | The migration's name. Defaults to the file's base name without its extension (`0001_todos`). |
| `--app`  | The app whose database to migrate.                                                           |

A migration is applied **once per name**: re-running the command with the same file is a no-op that
prints the existing ledger row, and re-running it with a *changed* file under the same name fails
with `version_conflict` — write a new file instead. Names are lowercase letters, digits, `_` and `-`.

For an app a project declares, put the files in the declaration instead — `apps[].migrations` in
[`naive.config`](/docs/cli/naive#config-surface) applies them on every `naive up`.

## migrations

```bash theme={"system"}
vetta db migrations
```

```json theme={"system"}
{
  "data": [
    {
      "id": "dbm_01H...",
      "object": "db_migration",
      "name": "0001_todos",
      "sha256": "9f86d081…",
      "applied_at": "2026-09-06T12:00:00.000Z",
      "statements": 1
    }
  ]
}
```