# Attach Db

Attach a DuckDB database file for use with /duckdb-skills:query.

- Repository: https://github.com/duckdb/duckdb-skills (613 stars)
- Category: Data and ML
- License: MIT
- Last updated: 2026-04-23
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add duckdb/duckdb-skills --skill attach-db -g -a claude-code -y`
Codex: `npx skills add duckdb/duckdb-skills --skill attach-db -g -a codex -y`
Cursor: `npx skills add duckdb/duckdb-skills --skill attach-db -g -a cursor -y`
Gemini CLI: `npx skills add duckdb/duckdb-skills --skill attach-db -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add duckdb/duckdb-skills`

## Description

Attach a DuckDB database file for use with /duckdb-skills:query. Explores the schema (tables, columns, row counts) and writes a SQL state file so subsequent queries can restore this session automatically via duckdb -init.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

You are helping the user attach a DuckDB database file for interactive querying.

Database path given: `$0`

Follow these steps in order, stopping and reporting clearly if any step fails.

**State file convention**: see the "Resolve state directory" section below. All skills share a single `state.sql` file per project. Once resolved, any skill can use it with `duckdb -init "$STATE_DIR/state.sql" -c "<QUERY>"`.

## Step 1, Resolve the database path

If `$0` is a relative path, resolve it against `$PWD` to get an absolute path (`RESOLVED_PATH`).

```bash
RESOLVED_PATH="$(cd "$(dirname "$0")" 2>/dev/null && pwd)/$(basename "$0")"
```

Check the file exists:

```bash
test -f "$RESOLVED_PATH"
```

- **File exists** -> continue to Step 2.
- **File not found** -> ask the user if they want to create a new empty database (DuckDB creates the file on first write). If yes, continue. If no, stop.

## Step 2, Check DuckDB is installed

```bash
command -v duckdb
```

If not found, delegate to `/duckdb-skills:install-duckdb` and then continue.

## Step 3, Validate the database

```bash
duckdb "$RESOLVED_PATH" -c "PRAGMA version;"
```

- **Success** -> continue.
- **Failure** -> report the error clearly (e.g. corrupt file, not a DuckDB database) and stop.

## Step 4, Explore the schema

First, list all tables:

```bash
duckdb "$RESOLVED_PATH" -csv -c "
SELECT table_name, estimated_size
FROM duckdb_tables()
ORDER BY table_name;
"
```

If the database has **no tables**, note that it is empty and skip to Step 5.

For each table discovered (up to 20), run:

```bash
duckdb "$RESOLVED_PATH" -csv -c "
DESCRIBE <table_name>;
SELECT count() AS row_count FROM <table_name>;
"
```

Collect the column definitions and row counts for the summary.

## Step 5, Resolve the state directory

Check if a state file already exists in either location:

```bash
# Option 1: in the project directory
test -f .duckdb-skills/state.sql && STATE_DIR=".duckdb-skills"

The rest: https://github.com/duckdb/duckdb-skills/blob/HEAD/skills/attach-db/SKILL.md