Attach DB

What Is This?

Overview

Attach DB is a DuckDB skill that connects an existing DuckDB database file to your active development session, making it immediately available for interactive querying and exploration. When invoked with a path to a .duckdb file, the skill performs a full schema inspection, cataloging all tables, columns, and row counts, then writes a SQL state file that persists the session configuration. This allows subsequent queries to restore the same database context automatically using the duckdb -init flag.

The skill is designed to work in close coordination with the /duckdb-skills:query command. Rather than manually reconnecting to a database and re-establishing context each time you open a new terminal session, Attach DB handles that setup in a single step. It reads the database structure, surfaces the schema details for immediate reference, and ensures that your query environment is consistent and reproducible across sessions.

This approach reduces friction in data-heavy development workflows where analysts and engineers frequently switch between multiple database files or need to share a reproducible query environment with teammates. By automating the attachment and schema discovery process, Attach DB keeps the focus on writing and running queries rather than managing connection state.

Who Should Use This

• Data engineers who work with multiple DuckDB files across different projects and need fast, repeatable access to each database
• Backend developers integrating DuckDB into application pipelines who need to inspect schema structure before writing queries
• Data analysts running exploratory queries against local .duckdb files and wanting session continuity between terminal restarts
• DevOps engineers automating data validation workflows where consistent database initialization is required
• Researchers and data scientists managing local analytical databases who need quick schema overviews without writing boilerplate SQL
• Technical leads reviewing database structures during code reviews or onboarding sessions

Why Use It?

Problems It Solves

• Manually reconnecting to a DuckDB file and re-running schema inspection queries every session wastes time and introduces inconsistency
• Without a saved state file, query sessions are ephemeral, meaning context is lost when the terminal closes and must be rebuilt from scratch
• Discovering table names, column types, and row counts requires multiple separate SQL commands, slowing down initial exploration
• Sharing a consistent query environment across team members is difficult without a standardized initialization file
• Switching between multiple database files in a single workflow often leads to errors caused by stale or incorrect session context

Core Highlights

• Attaches any valid .duckdb file with a single command invocation
• Automatically explores and reports the full schema including tables, columns, and row counts
• Writes a persistent SQL state file for use with duckdb -init
• Integrates directly with /duckdb-skills:query for a seamless query workflow
• Provides immediate schema visibility without manual SQL introspection
• Supports reproducible session initialization across different machines and team members
• Uses only Bash tooling, keeping the dependency footprint minimal

How to Use It?

Basic Usage

Invoke the skill by providing the path to your DuckDB database file as the argument:

/duckdb-skills:attach-db ./data/analytics.duckdb

The skill will connect to the file, inspect the schema, and write an initialization state file. You can then start DuckDB with that state file loaded:

duckdb -init .duckdb_session.sql ./data/analytics.duckdb

Specific Scenarios

Scenario 1: Exploring a new database before writing queries

When you receive a .duckdb file from a colleague, run Attach DB first to get a full picture of the schema before writing any SQL. The skill outputs table names, column definitions, and row counts, giving you the context needed to write accurate queries immediately.

Scenario 2: Restoring a previous session after a terminal restart

After the state file is written, restarting your session is straightforward:

duckdb -init .duckdb_session.sql

This restores the attached database and any session-level settings without repeating the setup process.

Real-World Examples

Example 1: Validating a data pipeline output

/duckdb-skills:attach-db ./output/pipeline_results.duckdb

After attachment, query the results table directly to verify row counts and column values match expectations.

Example 2: Onboarding a new team member

Commit the generated .duckdb_session.sql file to the repository. New team members run duckdb -init .duckdb_session.sql to get an identical query environment without any manual configuration.

Important Notes

Requirements

• A valid .duckdb database file must exist at the specified path before invoking the skill
• DuckDB must be installed and accessible in the system PATH
• Bash must be available in the execution environment
• Write permissions are required in the working directory for the state file to be created