Installation Guide
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The meltano-state-backend-postgresql package is a Meltano extension designed to provide a PostgreSQL-based state backend. This allows Meltano to store incremental replication state data within a PostgreSQL database rather than the default local filesystem or system database.
The installation process involves adding the package to the Meltano Python environment and configuring the connection parameters via the state_backend settings. This guide covers the prerequisite environment requirements, installation methods using common Python package managers, and initial configuration steps.
Sources: README.md:1-12, pyproject.toml:1-15
Prerequisites
Before installation, ensure your environment meets the following requirements:
- Python Version:
python >= 3.10 - Meltano Version:
meltano >= 3.7 - PostgreSQL Driver:
psycopg[binary] >= 3.1, < 4
Sources: pyproject.toml:23-28, fixtures/project/meltano.yml:1
Installation Methods
The package must be installed in the same Python environment where Meltano is running.
Using uv
For users utilizing the [uv] package manager, the tool can be installed directly from the GitHub repository:
uv tool install --with git+https://github.com/meltano/meltano-state-backend-postgresql.git meltano
Sources: README.md:18-20
Using pipx
If Meltano is installed via pipx, the extension should be injected into the existing Meltano virtual environment:
pipx install meltano
pipx inject meltano git+https://github.com/meltano/meltano-state-backend-postgresql.git
Sources: README.md:22-25
Configuration
Once installed, Meltano must be instructed to use the PostgreSQL backend by setting the state_backend.uri.
Connection URI Format
The primary configuration is the connection URI, which follows the standard PostgreSQL format:
postgresql://<user>:<password>@<host>:<port>/<database>?options=-csearch_path%3D<schema>
The ?options=-csearch_path%3D<schema> parameter defines the target schema. If omitted, the backend defaults to the server's search_path.
Sources: README.md:29-37, src/meltano_state_backend_postgresql/backend.py:175-182
Detailed Setting Definitions
The extension exposes several settings that can be configured individually in meltano.yml or via environment variables.
| Setting Name | Description | Type | Default |
|---|---|---|---|
state_backend.postgresql.host | PostgreSQL server hostname | String | localhost |
state_backend.postgresql.port | PostgreSQL server port | Integer | 5432 |
state_backend.postgresql.user | Authentication username | String | - |
state_backend.postgresql.password | Authentication password | String (Sensitive) | - |
state_backend.postgresql.database | Target database name | String | - |
state_backend.postgresql.schema | Target schema name | String | search_path |
state_backend.postgresql.table | State storage table name | String | state |
state_backend.postgresql.sslmode | SSL connection mode | String | prefer |
Sources: src/meltano_state_backend_postgresql/backend.py:46-105, README.md:52-61
System Architecture
The following diagram illustrates how the PostgreSQLStateStoreManager interacts with the PostgreSQL database during the initialization and state persistence process.
The manager automatically ensures the existence of the state table during initialization, containing columns for state_id, partial_state, completed_state, and updated_at.
Sources: src/meltano_state_backend_postgresql/backend.py:184-219, tests/test_conninfo.py:136-150
Environment Variable Configuration
For production environments, it is recommended to use environment variables for sensitive credentials.
export MELTANO_STATE_BACKEND_POSTGRESQL_PASSWORD='my_secure_password'
meltano config set meltano state_backend.uri 'postgresql://my_user@localhost/my_database'
Sources: README.md:73-77
Summary
Installing the meltano-state-backend-postgresql extension requires placing it within the Meltano execution environment and defining a PostgreSQL connection URI. The backend manages the lifecycle of the state table automatically and supports advanced PostgreSQL features such as SSL modes and advisory locks for state safety.