attach-db

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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>"

你需要协助用户挂载DuckDB数据库文件以进行交互式查询。

给定的数据库路径：

$0

请按顺序执行以下步骤，任何步骤失败都请停止并清晰上报问题。

状态文件约定：请参阅下文「解析状态目录」章节。所有skill每个项目共用一个

state.sql

文件。解析完成后，任何skill都可以通过

duckdb -init "$STATE_DIR/state.sql" -c "<QUERY>"

使用该文件。

Step 1 — Resolve the database path

步骤1 — 解析数据库路径

$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.

如果

$0

是相对路径，基于

$PWD

解析得到绝对路径（

RESOLVED_PATH

）。

bash

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

检查文件是否存在：

bash

test -f "$RESOLVED_PATH"

文件存在 -> 继续执行步骤2
未找到文件 -> 询问用户是否要创建新的空数据库（DuckDB会在首次写入时创建文件）。如果用户同意则继续，否则终止操作。

Step 2 — Check DuckDB is installed

步骤2 — 检查DuckDB是否已安装

bash

command -v duckdb

If not found, delegate to

/duckdb-skills:install-duckdb

and then continue.

bash

command -v duckdb

如果未找到，则调用

/duckdb-skills:install-duckdb

完成安装后继续。

Step 3 — Validate the database

步骤3 — 校验数据库

bash

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

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

bash

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

执行成功 -> 继续
执行失败 -> 清晰上报错误（例如文件损坏、不是DuckDB数据库等）并终止操作。

Step 4 — Explore the schema

步骤4 — 探查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.

首先列出所有表：

bash

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

如果数据库没有任何表，说明库为空，直接跳转到步骤5。

对发现的每个表（最多20个）执行以下命令：

bash

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

收集列定义和行数用于后续汇总。

Step 5 — Resolve the state directory

步骤5 — 解析状态目录

Check if a state file already exists in either location:

bash

undefined

检查以下两个位置是否已存在状态文件：

bash

undefined

Option 1: in the project directory

选项1：项目目录下

test -f .duckdb-skills/state.sql && STATE_DIR=".duckdb-skills"

Option 2: in the home directory, scoped by project root path

选项2：用户主目录下，按项目根路径隔离

PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")" PROJECT_ID="$(echo "$PROJECT_ROOT" | tr '/' '-')" test -f "$HOME/.duckdb-skills/$PROJECT_ID/state.sql" && STATE_DIR="$HOME/.duckdb-skills/$PROJECT_ID"


If **neither exists**, ask the user:

> Where would you like to store the DuckDB session state for this project?
>
> 1. **In the project directory** (`.duckdb-skills/state.sql`) — colocated with the project, easy to find. You can choose to gitignore it.
> 2. **In your home directory** (`~/.duckdb-skills/<project-id>/state.sql`) — keeps the project directory clean.

Based on their choice:

**Option 1:**
```bash
STATE_DIR=".duckdb-skills"
mkdir -p "$STATE_DIR"

Then ask: "Would you like to gitignore
.duckdb-skills/
?" If yes:

bash

echo '.duckdb-skills/' >> .gitignore

Option 2:

bash

PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")"
PROJECT_ID="$(echo "$PROJECT_ROOT" | tr '/' '-')"
STATE_DIR="$HOME/.duckdb-skills/$PROJECT_ID"
mkdir -p "$STATE_DIR"


如果**两个位置都不存在**，询问用户：

> 你希望将本项目的DuckDB会话状态存储在哪个位置？
>
> 1. **项目目录下**（`.duckdb-skills/state.sql`）—— 与项目同目录，易于查找，你可以选择将其加入gitignore。
> 2. **用户主目录下**（`~/.duckdb-skills/<project-id>/state.sql`）—— 保持项目目录整洁。

根据用户选择执行：

**选项1：**
```bash
STATE_DIR=".duckdb-skills"
mkdir -p "$STATE_DIR"

然后询问："你是否希望将
.duckdb-skills/
加入gitignore？" 如果用户同意：

bash

echo '.duckdb-skills/' >> .gitignore

选项2：

bash

PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")"
PROJECT_ID="$(echo "$PROJECT_ROOT" | tr '/' '-')"
STATE_DIR="$HOME/.duckdb-skills/$PROJECT_ID"
mkdir -p "$STATE_DIR"

Step 6 — Append to the state file

步骤6 — 追加内容到状态文件

state.sql

is a shared, accumulative init file used by all duckdb-skills. It may already contain macros, LOAD statements, secrets, or other ATTACH statements written by other skills. Never overwrite it — always check for duplicates and append.

Derive the database alias from the filename without extension (e.g.

my_data.duckdb

→

my_data

). Check if this ATTACH already exists:

bash

grep -q "ATTACH.*RESOLVED_PATH" "$STATE_DIR/state.sql" 2>/dev/null

If not already present, append:

bash

cat >> "$STATE_DIR/state.sql" <<'STATESQL'
ATTACH IF NOT EXISTS 'RESOLVED_PATH' AS my_data;
USE my_data;
STATESQL

Replace

RESOLVED_PATH

and

my_data

with the actual values. If the alias would conflict with an existing one in the file, ask the user for a name.

state.sql

是所有duckdb-skills共用的累加型初始化文件，可能已经包含其他skill写入的宏、LOAD语句、密钥或其他ATTACH语句。绝对不要覆盖该文件—— 始终先检查是否重复，再追加内容。

从数据库文件名中提取不含后缀的别名（例如

my_data.duckdb

→

my_data

）。检查该ATTACH语句是否已存在：

bash

grep -q "ATTACH.*RESOLVED_PATH" "$STATE_DIR/state.sql" 2>/dev/null

如果不存在，则追加：

bash

cat >> "$STATE_DIR/state.sql" <<'STATESQL'
ATTACH IF NOT EXISTS 'RESOLVED_PATH' AS my_data;
USE my_data;
STATESQL

将

RESOLVED_PATH

和

my_data

替换为实际值。如果别名与文件中现有别名冲突，询问用户指定新名称。

Step 7 — Verify the state file works

步骤7 — 验证状态文件可用

bash

duckdb -init "$STATE_DIR/state.sql" -c "SHOW TABLES;"

If this fails, fix the state file and retry.

bash

duckdb -init "$STATE_DIR/state.sql" -c "SHOW TABLES;"

如果执行失败，修复状态文件后重试。

Step 8 — Report

步骤8 — 上报结果

Summarize for the user:

Database path: the resolved absolute path
Alias: the database alias used in the state file
State file: the resolved
```
STATE_DIR/state.sql
```
path
Tables: name, column count, row count for each table (or note the DB is empty)
Confirm the database is now active for
```
/duckdb-skills:query
```

If the database is empty, suggest creating tables or importing data.

为用户汇总以下信息：

数据库路径：解析后的绝对路径
别名：状态文件中使用的数据库别名
状态文件：解析后的
```
STATE_DIR/state.sql
```
路径
表信息：每个表的名称、列数、行数（如果库为空则说明数据库为空）
确认数据库现在已可用于
```
/duckdb-skills:query
```

如果数据库为空，建议用户创建表或导入数据。