# Postgres

Managed PostgreSQL database instances.

```hcl
postgres "main" {}
```

Reference postgres attributes in env blocks:

```hcl
service "api" {
  build = build.api
  command = "./api"

  endpoint {
    public = true
  }

  env = {
    DATABASE_URL = postgres.main.url
  }
}

postgres "main" {}
```

## Available postgres attributes

- `url` - Full connection string (e.g., `postgres://user:pass@host:5432/dbname`)
- `host` - Database host
- `port` - Database port
- `user` - Database user
- `password` - Database password
- `name` - Database name
- `direct_url` - Non-pooled connection string, bypassing the connection pooler. Use when you need a direct database connection (e.g., Prisma's `directUrl`).
- `direct_host` - Non-pooled database host, bypassing the connection pooler.

## Querying the database

Use `specific psql` to connect to a development database. This will start the database if it's not already running.

```sh
# Interactive session
specific psql main

# Run a single query (useful for coding agents)
specific psql main -- -c "SELECT * FROM users LIMIT 5"

# List tables
specific psql main -- -c "\dt"
```

<!-- beta:reshape -->
## Schema Migrations

For zero-downtime schema migrations, use Reshape:

```hcl
postgres "main" {
  reshape {
    enabled = true
  }
}
```

Run `specific docs /postgres/reshape` for full documentation on managing migrations.

<!-- /beta:reshape -->
---

Related topics:
<!-- beta:reshape -->
- Run `specific docs /postgres/reshape` for zero-downtime schema migrations
<!-- /beta:reshape -->
- Run `specific docs sync` for real-time data synchronization
- Run `specific docs exec` for running one-off commands
