Environment Variable Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• src/meltano_state_backend_postgresql/backend.py
• pyproject.toml
• README.md
• tests/test_meltano.py
• fixtures/project/meltano.yml
• tests/test_conninfo.py

Environment variables in the meltano-state-backend-postgresql project provide a flexible mechanism for configuring connection parameters and security settings without hardcoding sensitive information. This system allows developers to override default settings and Meltano configuration files using standard environment variable naming conventions, which is particularly critical for production deployments and CI/CD pipelines.

The configuration logic maps specific environment variables to internal settings managed by the PostgreSQLStateStoreManager. These variables cover essential connection details such as host, port, credentials, and database-specific identifiers like schemas and table names.

Sources: src/meltano_state_backend_postgresql/backend.py:46-121, README.md:82-94

Mapping and Naming Convention

The project utilizes the MELTANO_STATE_BACKEND_POSTGRESQL_ prefix for all its environment variables. This prefix is programmatically derived from the setting names defined in the Meltano entry points.

Configuration Variable Mapping

Environment Variable	Setting Name	Description	Default (if applicable)
MELTANO_STATE_BACKEND_POSTGRESQL_HOST	state_backend.postgresql.host	PostgreSQL server hostname	localhost
MELTANO_STATE_BACKEND_POSTGRESQL_PORT	state_backend.postgresql.port	PostgreSQL server port	5432
MELTANO_STATE_BACKEND_POSTGRESQL_DATABASE	state_backend.postgresql.database	Database name	Required
MELTANO_STATE_BACKEND_POSTGRESQL_USER	state_backend.postgresql.user	Authentication username	Required
MELTANO_STATE_BACKEND_POSTGRESQL_PASSWORD	state_backend.postgresql.password	Authentication password	Required
MELTANO_STATE_BACKEND_POSTGRESQL_SCHEMA	state_backend.postgresql.schema	Database schema name	Default search_path
MELTANO_STATE_BACKEND_POSTGRESQL_SSLMODE	state_backend.postgresql.sslmode	SSL connection mode	prefer
MELTANO_STATE_BACKEND_POSTGRESQL_TABLE	state_backend.postgresql.table	Table for state storage	state

Sources: src/meltano_state_backend_postgresql/backend.py:46-121, pyproject.toml:29-36, tests/test_meltano.py:31-64

Data Flow and Initialization

The configuration follows a hierarchy where explicit environment variables or keyword arguments override parameters extracted from the state_backend.uri.

The flow shows how environment variables and URI parameters are merged and validated before establishing a database connection.
Sources: src/meltano_state_backend_postgresql/backend.py:124-159, tests/test_conninfo.py:133-146

Security Considerations

For production environments, the project specifically recommends using environment variables for sensitive values, particularly the MELTANO_STATE_BACKEND_POSTGRESQL_PASSWORD. The internal setting definition for the password is explicitly marked as sensitive=True.

POSTGRESQL_PASSWORD = SettingDefinition(
    name="state_backend.postgresql.password",
    label="PostgreSQL Password",
    description="PostgreSQL password",
    kind=SettingKind.STRING,
    sensitive=True,
    env_specific=True,
)

Sources: src/meltano_state_backend_postgresql/backend.py:86-93, README.md:82-88

Integration with Meltano

The project registers its settings through entry points in pyproject.toml. This allows Meltano to automatically discover the settings and map them to the corresponding environment variables using the MELTANO_ prefix followed by the setting name in uppercase with underscores.

Connection Resolution Sequence

When a connection is initialized, the system resolves the parameters in the following priority order:

1. Overrides: Explicit arguments passed to the PostgreSQLStateStoreManager.
2. Environment Variables: Values set in the shell or .env files.
3. Connection URI: Parameters parsed from the state_backend.uri.
4. Defaults: Hardcoded defaults like localhost for host and prefer for SSL mode.

The sequence diagram illustrates the prioritization and validation steps taken before the final connection string is passed to the PostgreSQL driver.
Sources: src/meltano_state_backend_postgresql/backend.py:124-175, pyproject.toml:29-36, tests/test_conninfo.py:31-48

Summary

Environment Variable Configuration is the primary method for managing secure and environment-specific settings for the PostgreSQL state backend. By mapping MELTANO_STATE_BACKEND_POSTGRESQL_* variables to internal SettingDefinition objects, the system ensures that sensitive credentials like passwords remain external to code and configuration files. This configuration layer integrates seamlessly with Meltano's settings registry and the psycopg connection logic to provide a robust database interface.