# PostgreSQL

Docker deployment for PostgreSQL and pgAdmin. Run all commands from the
repository root.

## Persistent Data

PostgreSQL data, database dumps, and pgAdmin state are stored in the
Docker-managed named volumes `postgres_data`, `postgres_backups`, and
`pgadmin_data`.

Existing bind-mount deployments must migrate their database and pgAdmin data
before recreating the stack. Do not start PostgreSQL against an empty named
volume and assume the previous database was imported.

## Installation

1. Create `.env` if it does not exist:

   ```bash
   cp -n .env.sample .env
   ```

2. Set the required values in `.env`:

   ```dotenv
   TZ=Africa/Johannesburg
   POSTGRES_USER=postgres
   POSTGRES_PASSWORD=<strong-password>
   POSTGRES_DB=maindb
   PGADMIN_EMAIL=admin@example.com
   PGADMIN_PASSWORD=<strong-password>
   DOCKERLOGGING_MAXFILE=3
   DOCKERLOGGING_MAXSIZE=10m
   ```

3. Render the template:

   ```bash
   ./substitute_env.sh docker-compose-files/postgres/template.yaml docker-compose.postgres.yml .env
   ```

4. Validate and start the stack:

   ```bash
   docker compose -f docker-compose.postgres.yml config --quiet
   docker compose -f docker-compose.postgres.yml up -d
   ```

5. Verify the containers and open pgAdmin at `http://<HOST_IP>:8484`:

   ```bash
   docker compose -f docker-compose.postgres.yml ps
   docker compose -f docker-compose.postgres.yml logs --tail=100
   ```

## Apply Configuration Changes

```bash
./substitute_env.sh docker-compose-files/postgres/template.yaml docker-compose.postgres.yml .env
docker compose -f docker-compose.postgres.yml up -d
```

## Initial Setup

Add PostgreSQL to pgAdmin using host `postgres`, port `5432`, and the database
credentials from `.env`.

## Network Requirements

- PostgreSQL is published on host port `5433`.
- pgAdmin is published on host port `8484`.
- Restrict both ports to trusted networks.

## Troubleshooting

If an older generated Compose file reports write-permission errors, re-render
it from the current template and recreate the stack. The current template uses
named volumes instead of host-created appdata directories.

## Useful Commands

```bash
docker compose -f docker-compose.postgres.yml exec postgres pg_isready
```

## Backup

Back up all three named volumes and create regular logical database dumps with
`pg_dump`.