Skip to main content

Postgres Configuration

Postgres handles identity management and symbol database storage. It stores user authentication data and debugging symbol metadata.

Configuration Modes​

Artifact Hub backend

Connect to existing Postgres​

This mode connects to your existing Postgres database, AWS Aurora PostgreSQL or GCP Cloud SQL.

Standard Postgres Configuration​

Standard Postgres Configuration
postgres:
  mode: "use_existing"
  use_existing:
    host: "" # host:port
    user: ""
    password: ""
    database: "zymtrace"  # Database name
    secure: false  # Enable TLS/secure connection
    autoCreateDBs: false  # When true, zymtrace migration will automatically create the required databases. 
    # NOTE: For autoCreateDBs to work, the database user must have CREATEDB permission. 
    # Grant with: ALTER USER "your-user" CREATEDB;

Setting up the Postgres use_existing mode

Postgres setups can vary based on security needs like data classification and role usage. The example below is a simplified guideline.

tip

Note that unlike typical applications, which require only INSERT and SELECT permissions, the zymtrace database migration job requires DDL access.

If you're setting up zymtrace for the first time, the most straightforward approach is to create one role with both DDL and DML permissions.

Database Setup Options​

You have two options for setting up the required databases:

  1. Manual Setup: Create databases and users manually using SQL commands
  2. Automatic Setup: Enable autoCreateDBs to let zymtrace create databases during migration
Option 1: Manual Database Setup​

For manual database setup, use the SQL commands below. This approach gives you full control over user permissions and database ownership.

The commands below assume you're connected to the database using a role with superuser privileges.

CREATE ROLE zystem LOGIN PASSWORD 'metsyz';

CREATE DATABASE zymtrace_identity OWNER zystem;
CREATE DATABASE zymtrace_symdb OWNER zystem;
CREATE DATABASE zymtrace_web OWNER zystem;

\c zymtrace_identity
ALTER SCHEMA public OWNER TO zystem;

\c zymtrace_symdb
ALTER SCHEMA public OWNER TO zystem;

\c zymtrace_web
ALTER SCHEMA public OWNER TO zystem;
Option 2: Automatic Database Setup​

Alternatively, you can enable autoCreateDBs: true in your configuration to let zymtrace automatically create the required databases during migration. This requires the database user to have CREATEDB permission.

When to use automatic setup:

  • Development environments where quick setup is preferred
  • When you have administrative access to grant broad CREATE permissions
  • Testing scenarios where database recreation is acceptable

When to use manual setup:

  • Production environments requiring strict permission control
  • When following security best practices with minimal required permissions
  • Enterprise environments with database administration policies

Security Considerations​

Database Permissions​

zymtrace requires both DDL (Data Definition Language) and DML (Data Manipulation Language) permissions:

  • DDL permissions: Required for database schema migrations
  • DML permissions: Required for normal application operations
User Role Management​

For production environments, consider creating separate roles for:

  • Migration role: Has DDL permissions for schema updates
  • Application role: Has minimal DML permissions for runtime operations

Configuration Examples​

Development Environment​

For development setups with simplified security:

postgres:
  mode: "use_existing"
  use_existing:
    host: "postgres.dev.company.com:5432"
    user: "zymtrace_dev"
    password: "dev-password"
    database: "zymtrace"
    secure: false
    autoCreateDBs: true