Database Persistence (PostgreSQL)
Relevant source files
The following files were used as context for generating this wiki page:
PostgreSQL provides the primary state persistence for the n8n workflow orchestration engine within the Nyansa stack. It stores workflow definitions, execution history, and credentials. The service runs as a containerized instance named nyansa-postgres using the postgres:17.11-alpine image.
Sources: README.md:23-25, README.md:94
Architecture and Connectivity
The PostgreSQL service operates within the internal nyansa Docker network. It does not publish any ports to the host machine, ensuring it is only reachable by internal services like n8n.
The diagram shows the isolated communication between the n8n workflow engine and the PostgreSQL database within the private network.
Sources: README.md:65-80
Configuration and Secrets
PostgreSQL requires environment variables for authentication and initialization. These values are managed via a .env file that is excluded from version control for security.
| Variable | Purpose |
|---|---|
POSTGRES_USER | The database username used for connection. |
POSTGRES_DB | The specific database name for n8n state. |
POSTGRES_PASSWORD | The password for the PostgreSQL user. |
Sources: README.md:200, scripts/backup.sh:65
Backup and Recovery Operations
The system employs a dedicated script, scripts/backup.sh, to perform logical dumps of the database while the container is running. If the container is stopped, the script archives the underlying volume instead.
Logical Dump Process
When nyansa-postgres is active, the backup script executes pg_dump within the container to create a custom-format dump file.
The sequence shows how the backup script interacts with the running container to extract a consistent database state.
Sources: scripts/backup.sh:62-72
Volume Persistence
The database state is persisted in a named Docker volume called nyansa_postgres_storage. This ensures data survives container restarts or recreations.
Sources: scripts/backup.sh:37-43, scripts/backup.sh:71
Implementation Details
The PostgreSQL service is integrated into the Nyansa project structure to support "One-command stack" deployments. It is managed by Docker Compose and categorized as a core persistent component alongside Qdrant.
# Example of how backup.sh executes the dump
docker exec nyansa-postgres sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" --format=custom' \
>"$target/postgres.dump"
Sources: README.md:20, scripts/backup.sh:65-66
PostgreSQL serves as a critical infrastructure component for Nyansa, providing the reliable storage required for n8n's workflow automation and AI agent orchestration. Its configuration emphasizes network isolation and automated backup routines to maintain system integrity.