# Managed Postgres

A managed PostgreSQL database, provisioned in one command and wired into your services by reference.

## Provision

```bash
lizard add postgres
```

The first Postgres addon is named `postgres`, so `${{postgres.DATABASE_URL}}` works immediately.

## Environment variables

The addon exposes a standard set of connection variables:

| Variable | Description |
|----------|-------------|
| `DATABASE_URL` | Full connection string (`postgres://…`) |
| `PGHOST` | Host |
| `PGPORT` | Port |
| `PGUSER` | User |
| `PGPASSWORD` | Password |
| `PGDATABASE` | Database name |
| `POSTGRES_USER` | Alias for the user |
| `POSTGRES_DB` | Alias for the database |
| `POSTGRES_PASSWORD` | Alias for the password |

## Connect a service

Reference the connection string from the consumer service and redeploy:

```bash
lizard secrets set DATABASE_URL='${{postgres.DATABASE_URL}}' --service api
lizard redeploy --service api
```

The reference resolves at deploy time and rotates automatically if the addon's credentials change — every consumer picks up the new value on its next deploy.

Verify connectivity without printing the connection string:

```bash
lizard run --service api -- sh -c 'psql "$DATABASE_URL" -c "SELECT 1"'
```

## Run migrations on deploy

Use a pre-deploy command for migrations. Make migrations safe to retry and compatible with both the old and new application version:

```bash
lizard service set api --set preDeployCommand="npm run migrate"
lizard redeploy --service api
```

For a Django app the command is `python manage.py migrate`; [Python app hosting](https://lizard.build/blog/python-app-hosting#deploying-django) has the equivalent for Flask and FastAPI.

## Browse and query data

Open the **Postgres editor** in the dashboard (`lizard open`) to run SQL and browse tables directly. For ad-hoc local work, run a command with the service's injected environment:

```bash
lizard run --service api -- sh -c 'exec psql "$DATABASE_URL"'
```

## Grow storage

Data volumes are grow-only:

```bash
lizard scale --service postgres --storage 8192
```

## Multiple databases

Adding a second Postgres gives it a generated name (e.g. `postgres-autumn-bear`). Reference it explicitly:

```bash
lizard add postgres
lizard secrets set ANALYTICS_URL='${{postgres-autumn-bear.DATABASE_URL}}' --service api
```

## See also

- [Managed Addons](https://lizard.build/docs/addons) — naming, references, and the dashboard browsers.
- [Cross-Service References](https://lizard.build/docs/variables/references) — reference syntax and resolution.

See [storage and recovery](https://lizard.build/docs/platform/storage-and-recovery) for backup and restore planning. Local `lizard run` requires `psql` and a reachable database endpoint; it does not run inside the deployed service.