Query databases and explore data. Use when the user mentions database, query, SQL, table, schema, data exploration, "check the data", "look at the database", "what's in the table", "show me records", "find in database", PostgreSQL, MySQL, SQLite, cross-database joins, data validation, or export query results. Also triggers on: exploring schemas, sampling data, running analytics queries, checking data quality, or any task involving database operations.
Query and analyze data across PostgreSQL, MySQL, and SQLite databases using a unified DuckDB engine. Triggers on mentions of database, SQL, query, table exploration, data checking, or cross-database joins.
/plugin marketplace add meomeocoj/cc-plugins/plugin install meomeocoj-data-analyze-plugins-data-analyze@meomeocoj/cc-pluginsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
credentials.example.jsonreferences/connection_examples.mdreferences/extensions.mdreferences/query_patterns.mdscripts/credential_manager.pyscripts/federated_query.pyscripts/schema_explorer.pyQuery and analyze data across PostgreSQL, MySQL, and SQLite databases using DuckDB as a unified query engine.
YOU MUST ALWAYS RUN THIS FIRST before attempting ANY database operation.
DO NOT skip this step. DO NOT assume database names. DO NOT run queries until you see the list of available databases.
# ALWAYS run this first - find and list configured databases
CREDS=".claude/data-analyze/credentials.json"
if [ -f "./$CREDS" ]; then
CREDS_FILE="./$CREDS"
echo "Using project credentials: $CREDS_FILE"
elif [ -f "$HOME/$CREDS" ]; then
CREDS_FILE="$HOME/$CREDS"
echo "Using user credentials: $CREDS_FILE"
else
echo "❌ No credentials file found!"
echo "Create credentials at: ./.claude/data-analyze/credentials.json (project) or ~/.claude/data-analyze/credentials.json (user)"
exit 1
fi
echo "Available databases:"
jq -r '.databases[] | " - \(.name) (\(.type))"' "$CREDS_FILE"
ONLY PROCEED with queries after seeing the list of available databases above.
# List all tables
python ${CLAUDE_PLUGIN_ROOT}/skills/unified-sql/scripts/schema_explorer.py --name prod_db --list-tables
# Describe a specific table
python ${CLAUDE_PLUGIN_ROOT}/skills/unified-sql/scripts/schema_explorer.py --name prod_db --describe users
# Sample data from a table
python ${CLAUDE_PLUGIN_ROOT}/skills/unified-sql/scripts/schema_explorer.py --name prod_db --sample orders --limit 10
python ${CLAUDE_PLUGIN_ROOT}/skills/unified-sql/scripts/federated_query.py \
--name prod_db \
--query "SELECT * FROM prod_db.users WHERE created_at >= '2024-01-01' LIMIT 10"
python ${CLAUDE_PLUGIN_ROOT}/skills/unified-sql/scripts/federated_query.py \
--names prod_db,sales_db \
--query "SELECT u.email, o.order_id FROM prod_db.users u JOIN sales_db.orders o ON u.id = o.user_id"
Examine table structures, columns, and data types without writing SQL.
Available operations:
--list-tables: Show all tables in database--describe TABLE: Show column names, types, nullability--sample TABLE: Preview rows from table--stats TABLE: Show row counts and column statisticsExample workflow:
# Step 1: List tables
python ${CLAUDE_PLUGIN_ROOT}/skills/unified-sql/scripts/schema_explorer.py --name prod_db --list-tables
# Step 2: Examine specific table
python ${CLAUDE_PLUGIN_ROOT}/skills/unified-sql/scripts/schema_explorer.py --name prod_db --describe users
# Step 3: Sample data
python ${CLAUDE_PLUGIN_ROOT}/skills/unified-sql/scripts/schema_explorer.py --name prod_db --sample users --limit 5
Join tables across different database systems in a single query.
Pattern:
-- Databases are referenced by their credential names
-- For example, if you have "users_db" and "orders_db" in credentials.json
SELECT
u.column,
o.column
FROM users_db.table1 u
JOIN orders_db.table2 o ON u.id = o.foreign_id
Example:
python ${CLAUDE_PLUGIN_ROOT}/skills/unified-sql/scripts/federated_query.py \
--names users_db,orders_db \
--query "
SELECT
u.email,
COUNT(o.order_id) as total_orders
FROM users_db.users u
LEFT JOIN orders_db.orders o ON u.id = o.user_id
GROUP BY u.email
ORDER BY total_orders DESC
"
Analyze query performance and execution plans.
Using EXPLAIN:
python ${CLAUDE_PLUGIN_ROOT}/skills/unified-sql/scripts/federated_query.py \
--name prod_db \
--query "EXPLAIN SELECT * FROM prod_db.large_table WHERE created_at >= '2024-01-01'"
Export query results in multiple formats.
Supported formats: table, json, csv, markdown
# Export to JSON
python ${CLAUDE_PLUGIN_ROOT}/skills/unified-sql/scripts/federated_query.py \
--name prod_db \
--query "SELECT * FROM prod_db.users" \
--format json > output.json
# Export to CSV
python ${CLAUDE_PLUGIN_ROOT}/skills/unified-sql/scripts/federated_query.py \
--name prod_db \
--query "SELECT * FROM prod_db.analytics" \
--format csv > output.csv
Credentials are stored in .claude/data-analyze/credentials.json and searched in order:
./.claude/data-analyze/credentials.json~/.claude/data-analyze/credentials.jsonSee ${CLAUDE_PLUGIN_ROOT}/skills/unified-sql/credentials.example.json for the template.
Key points:
name (this is what you reference in queries)postgres, mysql, sqlitehost, port, database, user, passwordpath to database fileShow available databases:
# Find and use credentials file (Project → User)
CREDS=".claude/data-analyze/credentials.json"
if [ -f "./$CREDS" ]; then
CREDS_FILE="./$CREDS"
elif [ -f "$HOME/$CREDS" ]; then
CREDS_FILE="$HOME/$CREDS"
else
echo "No credentials file found" >&2
exit 1
fi
jq -r '.databases[].name' "$CREDS_FILE"
jq -r '.databases[] | "\(.name): \(.type)"' "$CREDS_FILE"
.claude/ is typically gitignored./.claude/data-analyze/credentials.json~/.claude/data-analyze/credentials.jsonchmod 600 ~/.claude/data-analyze/credentials.json--nameSQL Injection Protection:
--allow-writes flag only when write operations are explicitly neededRead-Only Mode (Default):
The federated query tool runs in read-only mode by default. Dangerous SQL operations are blocked:
# This will be blocked by default
python ${CLAUDE_PLUGIN_ROOT}/skills/unified-sql/scripts/federated_query.py \
--name prod_db \
--query "DELETE FROM prod_db.users WHERE id = 1"
# Error: Dangerous SQL operation 'DELETE' detected. Use --allow-writes to enable.
# To allow write operations (use with caution)
python ${CLAUDE_PLUGIN_ROOT}/skills/unified-sql/scripts/federated_query.py \
--name prod_db \
--query "DELETE FROM prod_db.users WHERE id = 1" \
--allow-writes
Error Message Sanitization:
Single database:
# Scripts find credentials automatically (Project → User)
python ${CLAUDE_PLUGIN_ROOT}/skills/unified-sql/scripts/schema_explorer.py --name kolverse --list-tables
Multiple databases (federated query):
# Reference multiple databases by name (comma-separated)
python ${CLAUDE_PLUGIN_ROOT}/skills/unified-sql/scripts/federated_query.py \
--names kolverse,analytics_db \
--query "SELECT * FROM kolverse.users u JOIN analytics_db.metrics m ON u.id = m.user_id"
DuckDB supports many database extensions:
Pre-configured in scripts:
postgres - PostgreSQL databasesmysql - MySQL/MariaDB databasessqlite - SQLite file databasesOther useful extensions:
httpfs - Query remote files (S3, HTTP)parquet - Parquet file supportjson - JSON/NDJSON supporticu - Advanced string operationsSee references/extensions.md for detailed extension documentation and usage examples.
# Install missing extension
con.execute("INSTALL postgres")
con.execute("LOAD postgres")
con.execute(query).fetch_df_chunk()con.execute("SET memory_limit='4GB'")--name, --names)--name).claude/data-analyze/credentials.json - Your database credentials (Project or User scope)${CLAUDE_PLUGIN_ROOT}/skills/unified-sql/credentials.example.json - Template for credentials fileUse when working with Payload CMS projects (payload.config.ts, collections, fields, hooks, access control, Payload API). Use when debugging validation errors, security issues, relationship queries, transactions, or hook behavior.