fastdata reads fastdata.yaml. Commands look for it in the current folder, then in each parent
folder; -c, --config <path> points at a specific file. Relative paths inside it are resolved from
the folder that contains it.
Full example
version: 1
knowledge: ./knowledge
model: claude-opus-5-5
effort: medium
max_turns: 30
dialect: postgres
connector:
type: mcp
command: fastdata
args: ["connector", "postgres"]
env:
DATABASE_URL: ${ANALYTICS_DB_URL}
limits:
preview_rows: 50
max_rows: 100
query_timeout_s: 60
Options
| Key | Default | Meaning |
|---|---|---|
version | 1 | Config format version. |
knowledge | ./knowledge | Folder the agent reads. See Knowledge base. |
model | claude-opus-5-5 | Claude model id. Any model your account can use, e.g. claude-sonnet-5-5 for lower cost. |
effort | medium | How much the model thinks: low, medium, high, xhigh, max. Higher is slower and costs more; try high for hard multi-table questions. |
max_turns | 30 | Maximum agent steps per question. Caps the cost of one answer. |
dialect | none | SQL dialect the agent should write: postgres, mysql, sqlite, mssql, snowflake, bigquery, … |
connector | none | How queries run. Omit for manual mode. See Connectors. |
limits.preview_rows | 50 | Rows of each result the model sees. All fetched rows (up to max_rows) still reach the UI. |
limits.max_rows | 100 | Rows fetched per query. The built-in Postgres and SQLite executors stop in the database (Postgres wraps the query in LIMIT); results from other connectors are trimmed to this. The UI table and CSV download get the same rows. Raise it if people need bigger exports. |
limits.query_timeout_s | 60 | Time fastdata waits for the connector per query. |
connector (MCP)
| Key | Default | Meaning |
|---|---|---|
type | mcp | |
command | Program that starts an MCP server over stdio. fastdata means this fastdata (built-in executors). | |
args | [] | Arguments for command. |
env | {} | Environment for the server process (only these plus basics like PATH/HOME are passed). |
url | MCP endpoint for the streamable HTTP transport. Set exactly one of command or url. | |
headers | {} | HTTP headers for url. |
tool | auto | Name of the SQL tool. |
sql_arg | auto | Argument of tool that takes the SQL. |
extra_args | {} | Constant arguments added to every call. |
connector (HTTP)
| Key | Default | Meaning |
|---|---|---|
type | http | |
url | Endpoint that receives POST with a JSON body. | |
headers | {} | HTTP headers. |
sql_field | sql | Body field that carries the SQL. |
extra_body | {} | Constant fields added to the body. |
Secrets and environment variables
Never write passwords or tokens into fastdata.yaml. Reference environment variables instead:
| Syntax | Meaning |
|---|---|
${NAME} | Value of NAME; fastdata stops with an error naming the variable if it is unset or empty. |
${NAME:-fallback} | Value of NAME, or fallback if it is unset or empty. |
Variables come from your shell or from a .env file next to fastdata.yaml (shell values win).
Keep .env out of git; commit a .env.example with the variable names instead.
Claude credentials
These are read from the environment, not from fastdata.yaml:
| Setup | What to set |
|---|---|
| Claude Code installed and logged in on this machine | nothing |
| Anthropic API key | ANTHROPIC_API_KEY |
| Amazon Bedrock | CLAUDE_CODE_USE_BEDROCK=1 and your AWS credentials/region |
| Google Vertex AI | CLAUDE_CODE_USE_VERTEX=1 and your GCP project/region credentials |
fastdata doctor tells you whether it found credentials in the environment.
Files fastdata writes
| Path | What |
|---|---|
.fastdata/last-session (next to fastdata.yaml) | Id of the last terminal conversation, for ask --continue |
Claude Code's config folder (~/.claude/projects/…) | Conversation transcripts, kept by the Claude Agent SDK so follow-ups work |
Add .fastdata/ to your .gitignore.