---
name: postgres
description: PostgreSQL database server for persistent relational storage
metadata:
  version: "1.0.0"
  vibestack:
    main: false
    metrics-port: 9187
---

# PostgreSQL Skill

Installs and configures [PostgreSQL](https://www.postgresql.org/) database server for persistent relational data storage.

## Features

- Persistent relational database
- Auto-creates database and user on first run
- WAL-based replication ready
- Connection string exposed as `DATABASE_URL`
- Optional metrics via postgres_exporter

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `POSTGRES_PORT` | `5432` | PostgreSQL port |
| `POSTGRES_USER` | `vibestack` | Default user |
| `POSTGRES_PASSWORD` | `vibestack` | Default password |
| `POSTGRES_DB` | `vibestack` | Default database |
| `POSTGRES_DATA_DIR` | `/data/postgres` | Data directory |
| `POSTGRES_INITDB_ARGS` | (none) | Extra initdb arguments |
| `POSTGRES_MAX_CONNECTIONS` | `100` | Maximum connections |

### Output Variables

After starting, the skill exports:

| Variable | Example |
|----------|---------|
| `DATABASE_URL` | `postgresql://vibestack:vibestack@localhost:5432/vibestack` |

## Usage

### As a dependency

```yaml
metadata:
  vibestack:
    requires:
      - postgres
```

### Connection

```bash
# Connect with psql
psql "$DATABASE_URL"

# From application
DATABASE_URL=postgresql://vibestack:vibestack@localhost:5432/vibestack
```

### Custom initialization

Place SQL files in `initdb.d/` directory - they'll be executed on first startup:

```
skills/postgres/
├── initdb.d/
│   ├── 01-create-tables.sql
│   └── 02-seed-data.sql
```

## Data Persistence

All data is stored in `POSTGRES_DATA_DIR` (default: `/data/postgres`). Mount this directory to persist data across container restarts.

## Backup Integration

The `backup` skill automatically backs up PostgreSQL data using pg_dump for consistent snapshots.

## Security

For production use:
1. Set a strong `POSTGRES_PASSWORD`
2. Restrict network access to trusted hosts
3. Use SSL for connections (configure in postgresql.conf)