attach-db

Overview of attach-db skill

What attach-db does

The attach-db skill helps you attach a DuckDB database file so it can be queried immediately with /duckdb-skills:query. It is built for Database Engineering workflows where the main goal is to turn a local .duckdb file into a usable session, not to explore the database manually from scratch.

Who should use it

Use the attach-db skill if you already have a DuckDB file and want the skill to validate it, inspect its schema, and prepare a reusable state file. It is a good fit when you need repeatable analysis across multiple queries, or when you want a fast path from “I have a database file” to “I can ask questions about it.”

Why it is different

The attach-db guide is not just a connection helper. It checks whether DuckDB is installed, verifies the file is a valid DuckDB database, and writes session state so later queries can restore automatically with duckdb -init. That makes the skill useful when reliability matters and you want less setup friction before querying.

How to Use attach-db skill

Install and invoke attach-db

Install the attach-db skill into the DuckDB skills set, then call it with a path to the database file: attach-db <path-to-database.duckdb>. For example, use a real file path rather than a vague prompt like “attach my database,” because the skill depends on a concrete path to resolve, validate, and open the file.

Give the skill the right input

The best input is the exact database path plus a short note about your intent, such as whether the file should be treated as read-only, whether you expect it to exist already, and what you want to query next. Stronger prompts look like: “Attach ./data/sales.duckdb so I can inspect tables related to orders and revenue.” That helps the skill focus schema exploration on what matters.

What the workflow actually does

The attach-db skill resolves relative paths, checks whether the file exists, verifies DuckDB is available, and validates the database before continuing. It then explores schema details such as tables, columns, and row counts, and writes a shared state.sql file so future DuckDB commands can reuse the session through duckdb -init. This is the part users usually care about most: fewer repeat setup steps.

Read these files first

Start with SKILL.md in skills/attach-db. If you are integrating the skill into a larger workflow, also inspect the neighboring DuckDB skills that consume the saved state file, especially the query-related skill the attach step is meant to support. In practice, the attach step is most useful when you understand both the validation path and the downstream query flow.

attach-db skill FAQ

Is attach-db only for existing DuckDB files?

No. The skill can also handle the case where the file does not exist yet and may be created later, but it pauses to confirm before proceeding. That matters if you are deciding whether attach-db fits your workflow: it is safe for existing files, but it is not a blind “create whatever I asked for” helper.

Do I need this if I can already run DuckDB commands?

Yes, if you want a repeatable attach-and-validate workflow with schema discovery and saved session state. A plain prompt can connect to a database, but the attach-db skill adds guardrails around path resolution, database validation, and state reuse. If you only need a one-off query, the skill may be more than you need.

Is attach-db beginner friendly?

Mostly yes, because the skill is procedural and stops clearly when something fails. The main beginner risk is giving an imprecise path or assuming any .db file is a DuckDB database. If you can provide an exact file path and a basic goal, the attach-db guide is straightforward to use.

When should I not use attach-db?

Skip it if you do not have a local DuckDB file, if you are not using DuckDB tooling, or if you only need high-level advice rather than a queryable session. It is also the wrong choice if your real need is database migration or ETL, since attach-db is about attaching and preparing a database for analysis, not transforming one.

How to Improve attach-db skill

Provide a more specific target

The single biggest quality boost comes from naming the exact file and the next question you want answered. Compare “attach this database” with “attach ./warehouse.duckdb and prepare it for investigating customer churn tables.” The second version helps the skill validate the right file and makes the schema scan more relevant.

Be explicit about the expected state

If the database might be missing, corrupted, or newly created, say so up front. The attach-db skill behaves differently in those cases, and your prompt should reflect that. Clear expectations reduce back-and-forth and help the skill decide whether to continue, stop, or ask for confirmation.

Use the first output to guide the next query

The attach step is only the setup layer. After it reports tables, columns, and row counts, use that output to shape the next query prompt instead of asking for everything at once. For better results, follow up with a focused request like “query only the sales tables” or “summarize the top five dimensions in this schema.”

Watch for the common failure modes

The main failure modes are wrong paths, non-DuckDB files, and assuming the install state is already correct. If the skill reports a problem, fix the input rather than retrying the same prompt unchanged. For attach-db in Database Engineering work, precision at the file-path stage usually matters more than prompt length.