{"id":1817,"library":"dbt-postgres","title":"dbt-postgres Adapter","description":"dbt-postgres is an adapter that enables dbt-core to connect and transform data within PostgreSQL databases. It provides the necessary protocols and base functionality for dbt to interact with Postgres, allowing data analysts and engineers to build data transformation pipelines using SQL. The library is currently at version 1.10.0 and follows the release cadence of dbt-core, with minor versions typically introducing new features and patches addressing bugs, aiming for backward compatibility for end-users.","status":"active","version":"1.10.0","language":"en","source_language":"en","source_url":"https://github.com/dbt-labs/dbt-adapters.git#subdirectory=dbt-postgres","tags":["dbt","data transformation","etl","sql","postgres","database adapter","analytics engineering"],"install":[{"cmd":"pip install dbt-core dbt-postgres","lang":"bash","label":"Install dbt-core and dbt-postgres"}],"dependencies":[{"reason":"dbt-postgres is an adapter for dbt-core and requires it to function. Since dbt 1.8, dbt-core is no longer automatically installed with adapters.","package":"dbt-core","optional":false},{"reason":"Default Python driver for PostgreSQL. Can be overridden to 'psycopg2' for potentially better performance if compiled locally.","package":"psycopg2-binary","optional":true}],"imports":[],"quickstart":{"code":"# 1. Install dbt-core and dbt-postgres (if not already installed)\npip install dbt-core dbt-postgres\n\n# 2. Initialize a new dbt project\ndbt init my_postgres_project\n\n# 3. Navigate into your project directory\ncd my_postgres_project\n\n# 4. Configure your profiles.yml (usually located at ~/.dbt/profiles.yml)\n#    Replace placeholders with your PostgreSQL credentials. Example below:\n#\n#    my_postgres_project:\n#      target: dev\n#      outputs:\n#        dev:\n#          type: postgres\n#          host: localhost\n#          user: {{ env_var('DBT_PG_USER', 'postgres') }}\n#          password: {{ env_var('DBT_PG_PASSWORD', 'mysecretpassword') }}\n#          port: 5432\n#          dbname: my_database\n#          schema: public\n#          threads: 4\n#          keepalives_idle: 0\n#          connect_timeout: 10\n\n# 5. Verify your dbt connection\ndbt debug\n\n# 6. Create a sample model (e.g., models/my_first_model.sql)\n#    Content of models/my_first_model.sql:\n#    -- models/my_first_model.sql\n#    select\n#        1 as id,\n#        'hello dbt!' as message\n\n# 7. Run your dbt models\ndbt run\n\n# 8. Test your dbt models (if tests are defined)\ndbt test","lang":"bash","description":"This quickstart guides you through setting up a new dbt project with the `dbt-postgres` adapter. It covers installation, project initialization, `profiles.yml` configuration to connect to a PostgreSQL database, debugging the connection, and running a simple dbt model. Ensure you have a running PostgreSQL instance and replace the placeholder credentials in `profiles.yml` with your actual database details. Environment variables like `DBT_PG_USER` and `DBT_PG_PASSWORD` can be used for sensitive information."},"warnings":[{"fix":"Upgrade Python to version 3.9 or newer (e.g., Python 3.10, 3.11, 3.12, or 3.13).","message":"dbt-postgres 1.9.0 dropped support for Python 3.8. Users must upgrade their Python environment to 3.9 or higher. dbt 1.10 supports Python 3.13 for the Postgres adapter.","severity":"breaking","affected_versions":">=1.9.0"},{"fix":"When installing, use `pip install dbt-core dbt-postgres` (or your specific adapter) to ensure both are present.","message":"Starting with dbt version 1.8, installing a dbt adapter (like `dbt-postgres`) no longer automatically installs `dbt-core`. This change decouples adapter and core versions. Users must now explicitly install both `dbt-core` and the desired adapter.","severity":"breaking","affected_versions":">=1.8.0"},{"fix":"To use `psycopg2` instead of `psycopg2-binary`, first uninstall `psycopg2-binary`, then `export DBT_PSYCOPG2_NAME=psycopg2` before installing `dbt-postgres`.","message":"By default, `dbt-postgres` installs `psycopg2-binary`, which is a pre-built version. For optimized performance, especially in production environments, users may prefer to install `psycopg2` (which compiles against local PostgreSQL libraries). This can be done by setting the `DBT_PSYCOPG2_NAME` environment variable.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure you understand whether your dbt setup requires local `profiles.yml` management or leverages dbt Cloud's integrated connection settings.","message":"`profiles.yml` is used for configuring connections when running `dbt Core` or `dbt Fusion` locally. If you are using `dbt Cloud`, you typically do not need to create or manage a `profiles.yml` file, as connection details are handled within the dbt Cloud platform.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When defining or referencing dbt engine-specific environment variables, prefer the `DBT_ENGINE_` prefix where applicable, and be aware of this distinction to avoid naming collisions.","message":"In dbt 1.10, environment variables specifically for the dbt engine now use the `DBT_ENGINE_` prefix to avoid potential conflicts with user-defined `DBT_` prefixed variables. While older `DBT_` variables still function, new engine-specific variables will adhere to the `DBT_ENGINE_` prefix.","severity":"gotcha","affected_versions":">=1.10.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}