{"id":2462,"library":"dbt-duckdb","title":"dbt-duckdb Adapter","description":"dbt-duckdb is the adapter that connects dbt (data build tool) with DuckDB, an embedded analytical database. It allows users to manage and transform data using SQL or Python models, enabling a powerful local data stack or data lakehouse architecture. The library is actively maintained with frequent releases, currently at version 1.10.1.","status":"active","version":"1.10.1","language":"en","source_language":"en","source_url":"https://github.com/jwills/dbt-duckdb","tags":["dbt","duckdb","data build tool","adapter","OLAP","analytics","embedded database","data lakehouse"],"install":[{"cmd":"pip install dbt-core dbt-duckdb","lang":"bash","label":"Recommended installation"},{"cmd":"pip install dbt-duckdb[glue]","lang":"bash","label":"For AWS Glue Catalog integration (optional)"},{"cmd":"pip install dbt-duckdb[md]","lang":"bash","label":"For MotherDuck integration (optional)"}],"dependencies":[{"reason":"This is a dbt adapter; it requires dbt-core. Current versions target dbt-core >= 1.8.x. As of dbt-duckdb 1.8, dbt-core must be installed explicitly.","package":"dbt-core"},{"reason":"The underlying analytical database engine. Required for functionality. Current versions target duckdb >= 1.1.x.","package":"duckdb"},{"reason":"A dependency for efficient data handling, often bumped in releases. [cite: GitHub release notes]","package":"pyarrow"},{"reason":"Pinned below 1.9.x in 1.10.1 due to compatibility with pytest-logbook. [cite: GitHub release notes]","package":"logbook"}],"imports":[],"quickstart":{"code":"mkdir my_dbt_project\ncd my_dbt_project\ndbt init my_dbt_project_name\n# Edit ~/.dbt/profiles.yml (or profiles.yml in project root)\n# Add the following profile:\n#\n#   my_dbt_project_name:\n#     target: dev\n#     outputs:\n#       dev:\n#         type: duckdb\n#         path: /tmp/dbt.duckdb  # Or './dbt_warehouse.duckdb' for project-local persistence\n#         threads: 4\n#\ndbt debug --profile my_dbt_project_name\n# Expected output: Connection test successful.\n\n# Create a simple SQL model (e.g., models/my_model.sql)\n# -- my_model.sql --\n# SELECT 1 as id, 'hello' as message\n\n# Run your dbt models\ndbt run","lang":"bash","description":"This quickstart guides you through initializing a dbt project, configuring the `dbt-duckdb` adapter in your `profiles.yml` for local storage, and running a simple dbt model. The `path` field is crucial for data persistence."},"warnings":[{"fix":"Upgrade your Python environment to version 3.10 or later.","message":"Python 3.8 and 3.9 are no longer supported. Version 1.10.1 dropped support for both, and 1.9.2 dropped Python 3.8. Users must upgrade to Python 3.10 or newer.","severity":"breaking","affected_versions":">=1.10.1 (Python 3.8, 3.9); >=1.9.2 (Python 3.8)"},{"fix":"Modify your installation command to `pip install dbt-core dbt-duckdb` and ensure your `dbt-core` version meets the adapter's requirements.","message":"Explicit dbt-core Installation Required: As of dbt-duckdb 1.8, dbt-core is no longer automatically installed as a dependency. Users must explicitly install `dbt-core` alongside `dbt-duckdb` (e.g., `pip install dbt-core dbt-duckdb`). Ensure `dbt-core` version is compatible; current dbt-duckdb versions target `dbt-core >= 1.8.x`.","severity":"breaking","affected_versions":">=1.8.0"},{"fix":"Always set the `path` configuration in your `profiles.yml` to a file path on your filesystem to enable data persistence. Use `:memory:` explicitly if non-persistence is desired.","message":"Default In-Memory Database (No Persistence): By default, `dbt-duckdb` runs against an in-memory DuckDB database, meaning any data generated by `dbt run` will not be persisted after the process exits. To store your data to disk, you *must* specify a `path` in your `profiles.yml` configuration (e.g., `path: /path/to/my/database.duckdb`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"If encountering conflicts, consider isolating dbt-duckdb in a dedicated virtual environment or checking if other dependencies can tolerate `logbook < 1.9`. Report issues if this impacts critical functionality.","message":"logbook Dependency Pin: Version 1.10.1 introduced a dependency pin `logbook < 1.9`. This is due to `pytest-logbook`'s reliance on a compat module removed in `logbook` 1.9.x. This might cause dependency conflicts if other libraries in your environment require a newer version of `logbook`.","severity":"gotcha","affected_versions":">=1.10.1"},{"fix":"Update your dbt models and configurations to use the current, supported methods for interacting with DeltaLake if applicable. Refer to the dbt-duckdb documentation for updated patterns.","message":"DeltaLake Functions Removed: Legacy DeltaLake functions were removed in `dbt-duckdb` 1.8.4. Models or workflows relying on these older functions will break.","severity":"deprecated","affected_versions":">=1.8.4"},{"fix":"Be aware of these limitations when designing solutions for MotherDuck. Test thoroughly if using advanced SQL features or custom extensions.","message":"MotherDuck Limitations: When connecting to MotherDuck (cloud-hosted DuckDB), certain features are limited compared to a local DuckDB instance. This includes lack of support for custom extensions/user-defined functions and potential differences in behavior for some advanced SQL features like `dbt.listagg` macros and foreign-key constraints.","severity":"gotcha","affected_versions":"All versions when using MotherDuck"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}