Individual Setting Configuration

Relevant source files

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

• README.md
• src/meltano_state_backend_postgresql/backend.py
• pyproject.toml
• tests/test_meltano.py
• tests/test_conninfo.py
• tests/test_integration.py

Individual Setting Configuration refers to the mechanism within the meltano-state-backend-postgresql extension that allows users to define PostgreSQL connection parameters as discrete Meltano settings rather than a single unified connection URI. This approach provides granular control over database credentials and connection behavior, facilitating easier integration with environment variables and secret management systems.

This configuration method serves as an alternative or override to the state_backend.uri parameter. While a URI can provide a complete connection string, individual settings allow specific overrides for the host, port, user, password, database, and schema, which are then processed and validated by the backend to form a valid libpq connection string.

Sources: README.md:46-64, src/meltano_state_backend_postgresql/backend.py:101-131

Configuration Architecture

The system utilizes a hierarchical precedence logic when resolving connection parameters. It first parses the provided state_backend.uri and then applies any specific overrides provided through individual state_backend.postgresql.* settings.

Precedence and Resolution Logic

The conninfo_from_params function handles the merging of these configuration sources. It extracts initial parameters from the URI using conninfo_to_dict and then explicitly overwrites keys if individual arguments are passed to the PostgreSQLStateStoreManager constructor.

Core Settings Definitions

The backend defines several SettingDefinition objects that map Meltano settings to internal backend parameters. These are exposed via entry points in the project metadata.

Backend Setting Parameters

Setting Name	Label	Kind	Description
state_backend.postgresql.host	PostgreSQL Host	String	Server hostname (default: localhost)
state_backend.postgresql.port	PostgreSQL Port	Integer	Server port (default: 5432)
state_backend.postgresql.database	PostgreSQL Database	String	Target database name
state_backend.postgresql.user	PostgreSQL User	String	Authentication username
state_backend.postgresql.password	PostgreSQL Password	String	Authentication password (Sensitive)
state_backend.postgresql.schema	PostgreSQL Schema	String	Target schema (default: search_path)
state_backend.postgresql.sslmode	PostgreSQL SSL Mode	String	SSL connection mode (default: prefer)
state_backend.postgresql.table	PostgreSQL Table	String	Table for state storage (default: state)

Sources: src/meltano_state_backend_postgresql/backend.py:46-98, pyproject.toml:34-42, README.md:73-79

Implementation Details

Validation Requirements

The backend enforces strict validation for mandatory connection parameters. Even if a URI is provided, the resulting connection dictionary must contain the following keys, or a MissingStateBackendSettingsError is raised:

1. user
2. password
3. dbname (mapped from database)

Sources: src/meltano_state_backend_postgresql/backend.py:121-129, tests/test_conninfo.py:121-149

Environment Variable Mapping

Settings are designed to be env_specific, allowing them to be set via environment variables following the pattern MELTANO_STATE_BACKEND_POSTGRESQL_<SETTING_NAME>. For example, state_backend.postgresql.password can be set using MELTANO_STATE_BACKEND_POSTGRESQL_PASSWORD.

Sources: src/meltano_state_backend_postgresql/backend.py:74-81, tests/test_meltano.py:35-69

Schema and Table Identification

Unlike core connection parameters which are handled by psycopg, the schema and table settings are used to construct a psycopg.sql.Identifier.

• If schema is provided, the identifier is qualified as "schema"."table".
• If schema is omitted, the identifier is unqualified as "table", relying on the PostgreSQL search_path.

Usage Example

Users can configure these settings in meltano.yml to maintain a clean base URI while injecting sensitive credentials or specific environment overrides.

state_backend:
  uri: postgresql://localhost/my_database
  postgresql:
    user: my_user
    password: my_password
    schema: analytics_state
    sslmode: verify-full

Sources: README.md:55-64, fixtures/project/meltano.yml:7-11

Conclusion

Individual Setting Configuration provides the necessary flexibility for production Meltano environments where database connection strings must be dynamically constructed from multiple sources. By separating the host/database identity from authentication credentials and schema-level overrides, the backend ensures compatibility with complex infrastructure requirements while maintaining robust validation and security standards.