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

# floo db

> Query, inspect, migrate, and reset managed Postgres surfaces for an app.

`floo db` exposes read and migration access to an app's managed Postgres. It also exposes preview database branch inspection and reset for pull request previews.

[pgvector](https://github.com/pgvector/pgvector) is enabled on every managed Postgres, and the `vector` type resolves unqualified. `floo db query`, `floo db migrate`, and your app's own connection all see it without a `CREATE EXTENSION` step or a schema prefix. See [Databases → Vector search with pgvector](/docs/guides/databases#vector-search-with-pgvector).

## query

Run a SQL query against the managed database for an app.

```bash theme={null}
floo db query --app my-app "SELECT id, email FROM users LIMIT 5"
floo db query --app my-app "SELECT COUNT(*) FROM orders" --env prod
floo db query --app my-app "SELECT * FROM logs" --limit 50
```

### Flags

| Flag          | Default              | Description                         |
| ------------- | -------------------- | ----------------------------------- |
| `--app`, `-a` | inferred from config | App name or ID                      |
| `--env`       | `dev`                | Target environment: `dev` or `prod` |
| `--limit`     | `1000`               | Maximum rows to return              |

## schema

Print the current database schema for an app.

```bash theme={null}
floo db schema --app my-app
```

## migrate

Run pending migrations against the managed database.

```bash theme={null}
floo db migrate --app my-app
```

The CLI ships the migration payload from your current checkout. Use this before or after a deploy when the app depends on a schema change.

## connections

Show current Postgres connection usage versus the role's limit.

```bash theme={null}
floo db connections --app my-app
floo db connections --app my-app --env prod
floo db connections --app my-app --json
```

### Flags

| Flag          | Default              | Description                         |
| ------------- | -------------------- | ----------------------------------- |
| `--app`, `-a` | inferred from config | App name or ID                      |
| `--env`       | `dev`                | Target environment: `dev` or `prod` |

### Output

```
my-app (dev): 18/25 Postgres connections in use (72%)
```

When the role is near capacity (≥75%), the output adds a heads-up about pooling and a one-line `Email team@getfloo.com — we can provision a dedicated instance.` Use this command when diagnosing `too many connections` errors or before turning up app autoscaling.

## branches list

List the managed Postgres branches backing one preview environment.

```bash theme={null}
floo db branches list feat-db-abcde --app my-app
floo db branches list https://my-app-preview-feat-db-abcde.on.getfloo.com --app my-app --json
```

The preview argument can be a preview slug, preview URL, source branch, or `#123` when it resolves to one preview.

### JSON output

```json theme={null}
{
  "success": true,
  "data": {
    "preview": {
      "slug": "feat-db-abcde",
      "environment_name": "preview"
    },
    "database_branches": [
      {
        "name": "default",
        "source_environment": "dev",
        "resource_status": "ready",
        "hydration_mode": "clone-dev",
        "schema_name": "app_123_preview_feat_db_abcde",
        "reset_eligible": true
      }
    ],
    "total": 1
  }
}
```

The response is agent-safe. It includes branch metadata and reset eligibility, but never plaintext credentials.

## branches show

Show one preview database branch.

```bash theme={null}
floo db branches show feat-db-abcde --app my-app
floo db branches show feat-db-abcde --app my-app --name analytics --json
```

### Flags

| Flag          | Default              | Description                  |
| ------------- | -------------------- | ---------------------------- |
| `--app`, `-a` | inferred from config | App name or ID               |
| `--name`      | `default`            | Managed Postgres branch name |

## branches reset

Drop and recreate one preview-owned managed Postgres branch. Dev and prod are untouched.

```bash theme={null}
floo db branches reset feat-db-abcde --app my-app --name default
floo db branches reset feat-db-abcde --app my-app --name default --yes --json
floo --dry-run db branches reset feat-db-abcde --app my-app --name default
```

Reset is tier 2 because it destroys preview-only data. Non-interactive callers must pass `--yes`.

### Flags

| Flag          | Default              | Description                  |
| ------------- | -------------------- | ---------------------------- |
| `--app`, `-a` | inferred from config | App name or ID               |
| `--name`      | `default`            | Managed Postgres branch name |
| `--yes`       | off                  | Skip the confirmation prompt |

### JSON reset fields

```json theme={null}
{
  "success": true,
  "data": {
    "destructive": true,
    "data_loss": true,
    "tier": 2,
    "scope": "preview",
    "dev_prod_untouched": true
  }
}
```

Reset is blocked for dev/prod databases, external databases, non-Postgres resources, Redis, Storage, and preview branch rows that are not ready.

## Related

* [Managed Services](/docs/guides/managed-services) — declare Postgres in `floo.app.toml`
* [`floo env`](/docs/cli/env) — read managed URLs like `DATABASE_URL` directly
* [Databases](/docs/guides/databases) — the end-to-end managed Postgres model
* [Preview Environments](/docs/guides/preview-environments) — supported preview data modes and branch reset behavior