fastdata
Guide

Getting started

This guide takes you from nothing to a first answer, then to your own database.

1. Requirements

  • Node.js 22.13 or newer (node --version).
  • Access to Claude, one of:
    • a logged-in Claude Code on the same machine (no extra setup: fastdata reuses its login),
    • an Anthropic API key in ANTHROPIC_API_KEY,
    • Amazon Bedrock (CLAUDE_CODE_USE_BEDROCK=1 plus your AWS credentials) or Google Vertex AI (CLAUDE_CODE_USE_VERTEX=1 plus your GCP credentials).

2. Install

curl -fsSL https://fastdata.run/install.sh | sh   # macOS / Linux, brings its own Node if needed
npm install -g fastdata         # or with npm; both install the aliases `fdata` and `fada`

The script installs into ~/.fastdata without sudo: it uses your Node when it is 22.13 or newer, otherwise it downloads Node 24 there, and adds ~/.fastdata/bin to your PATH. Rerun it to update; rm -rf ~/.fastdata uninstalls. On Windows, use npm.

Check it works: fastdata --version. To try it without installing, prefix the commands below with npx, e.g. npx fastdata init shop-demo --demo.

3. Try the demo

The demo is a small coffee shop: a SQLite database with customers, products, orders and order lines, plus a ready-made knowledge base.

fastdata init shop-demo --demo
cd shop-demo
fastdata doctor        # checks Claude access, the knowledge base and the connector
fastdata               # opens http://localhost:8000

Click one of the example questions, or ask your own:

  • Which 3 countries brought the most revenue last year?
  • What is the cancellation rate by sales channel?
  • Who are our top 10 customers, and what do they buy?

Each answer shows the steps the agent took, the query and its result table (with CSV download), then a Markdown answer with assumptions and the files it relied on.

Prefer the terminal?

fastdata ask "How many orders did we get last month?"
fastdata ask --continue "And the month before?"

4. Use your own database

In an empty folder (or a folder in your data team's repo):

fastdata init

This creates:

fastdata.yaml      # configuration
knowledge/         # the knowledge base the agent reads
.env.example       # where secrets go (copy to .env)
AGENTS.md          # guide for coding agents (Claude Code, Codex, ...) working on the knowledge base
CLAUDE.md          # points Claude Code at AGENTS.md

In a terminal, init then asks whether to learn your database now: answer Y, paste a database URL (postgres://…, mysql://…, sqlserver://… or a SQLite file), and fastdata sets up the connector and drafts knowledge/ from the schema. You can also run it later:

fastdata learn --url postgres://readonly_user:pass@host:5432/db

Review the drafts (see Knowledge base). Opening Claude Code in the folder helps with that: AGENTS.md tells it how to inspect the schema through your connector and what to write down.

To set things up by hand instead:

  1. Set the dialect in fastdata.yaml (postgres, mysql, snowflake, bigquery, …).
  2. Describe your data in knowledge/, starting with INDEX.md. Even a few lines per important table make a big difference. See Knowledge base.
  3. Choose how queries run:
    • Configure a connector and fastdata runs read-only queries for you, or
    • leave connector out: fastdata writes the SQL and you run it yourself (manual mode).
  4. Run fastdata doctor, fix anything it reports, then fastdata.

5. Next