ansible-playbooks/roles/postgres

PostgreSQL Role

Installs and configures PostgreSQL as a shared database service for multiple applications with isolated databases and users.

Features

• Shared PostgreSQL instance (system service)
• Per-service database isolation
• Per-service user privileges (minimal permissions)
• Container access support (via Podman gateway)
• Configurable logging backend (journald or files)
• Performance tuning presets

Architecture Pattern

Decentralized database management:

• PostgreSQL role: Installs and configures the server
• Service roles: Create their own databases/users (e.g., immich, nextcloud)
• Isolation: Each service user can only access their own database

See CLAUDE.md for detailed architecture documentation.

Container Access

For containers to reach PostgreSQL:

PostgreSQL binds to 127.0.0.1 by default (secure, localhost-only).

Containers can reach PostgreSQL via Pasta's --map-host-loopback feature, which routes container's 127.0.0.1 to the host's 127.0.0.1.

In docker-compose files, use:

extra_hosts:
    - "postgres.local:127.0.0.1"

No additional bind addresses or firewall rules needed!

Logging Backends

journald (default):

• Logs via stderr → systemd journal
• View: journalctl -u postgresql -f

file:

• Logs to data directory or /var/log/postgresql/
• Automatic logrotate configuration

Switch via postgres_log_backend variable.

Hands-on Commands

# Connect to PostgreSQL
sudo -u postgres psql

# List databases
sudo -u postgres psql -c '\l'

# List users and permissions
sudo -u postgres psql -c '\du'

# Test connection
psql -h localhost -U myservice_user -d myservice_db

# View logs (journald)
journalctl -u postgresql -f
journalctl -u postgresql -p err

# View logs (file - Arch)
tail -f /var/lib/postgres/data/log/postgresql-*.log

# View logs (file - Debian)
tail -f /var/log/postgresql/postgresql-*.log

# Check listen addresses
sudo -u postgres psql -c "SHOW listen_addresses;"

# Performance settings
sudo -u postgres psql -c "SHOW shared_buffers;"
sudo -u postgres psql -c "SHOW effective_cache_size;"

References

• PostgreSQL Documentation
• PostgreSQL Logging
• PostgreSQL Performance Tuning
• pg_hba.conf Documentation