Getting Started with dbology

DBOLOGY is a command-line copilot for data analysts and data engineers. It works against your real, messy database — duplicate tables, legacy logic, missing descriptions and all — not a clean semantic layer.

What you need

• A Mac, Linux, or Windows machine
• A license key from HowAboutData
• An API key for an LLM provider — Anthropic, OpenAI, or other models
• Credentials for your database (SQL Server, Databricks, or Snowflake)

Step 1 — Install

Open a terminal and run:

curl -fsSL https://get.databaseology.com/install.sh | sh

This downloads the right binary for your machine and puts it in your PATH. It takes about 30 seconds. No Python or other software required.

When it's done, verify the install:

dbology version

Step 2 — First launch

Run:

dbology

The first time you run it, a setup wizard walks you through three things:

1. Your license key

Paste the key you received by email (formatted DBOL-XXXX-XXXX-XXXX). Your license is stored locally and checked in the background — no action needed after this.

2. Your LLM provider

Pick one and paste your API key when prompted:

• Anthropic
• OpenAI
• Other models

The wizard sends one tiny test request to verify your credentials before saving. Your key stays on your machine and is never sent anywhere except your chosen provider. You can switch providers later via /model or /config.

Tip: dbology works with any supported model. For the deepest reasoning we recommend claude-opus-4-8; the default claude-sonnet-4-6 is faster and handles most questions well — switch anytime with /model.

3. Your database connection

Pick the analytics mode for this connection:

• Healthcare analytics — loads the healthcare domain expert (HEDIS measures, ICD-10/HCPCS/CPT codes, CMS programs, risk adjustment) backed by live national benchmark data
• General database analytics — schema discovery + SQL only, no healthcare context

Then choose your database type and enter the connection details:

• SQL Server — server address, username, password
• Databricks — server hostname, HTTP path, access token
• Snowflake — account identifier, username, password, warehouse

Your credentials stay on your machine and are never uploaded.

After setup, dbology connects to your database and opens a prompt where you can start asking questions.

Step 3 — Ask your first question

Once the prompt is open, just type in plain English:

> How many members do we have by line of business?

> What tables have claims data?

> Show me ER visit trends by month for the last year

> What is the HEDIS AMR rate for our Medicare members?

dbology figures out which tables to look at, writes the SQL, runs it, and explains the results. For healthcare questions (like HEDIS measures or ICD-10 codes), it also looks up definitions and national benchmarks automatically.

Beyond Q&A: understand and trust your data

Plain-English questions are just the start. Four commands tackle the parts of data work that usually eat your day:

/trace-upper <object> — Where does this come from? Trace a table or view back to its sources, rendered as a lineage tree — so you stop guessing which pipeline populated a column.

> /trace-upper dbo.fact_claims

/trace-down <object> — What breaks if I change this? See everything downstream — tables, views, reports, and jobs — that depends on an object before you touch it.

> /trace-down dbo.dim_member

/dedup <table.column> — Is this duplicated somewhere? Find columns elsewhere in the warehouse that duplicate or overlap the one you care about, ranked by confidence — so you pick the right source and avoid double-counting.

> /dedup dw.fact_claims.member_id

/risk <table|view> — Can I trust these numbers? Scan an object for data-quality issues across six dimensions — timeliness, completeness, uniqueness, validity, consistency, and accuracy — before you build on it.

> /risk dw.fact_claims

Selecting databases

After you pick a server profile, dbology asks which databases or catalogs to work with. Use the arrow keys to move and space to select, then press Enter.

You can change your database selection at any time during a session:

/db

Useful commands

Type these at the > prompt at any time:

Press Ctrl+C at any time to stop a running query without closing the tool.

Memory — dbology learns your world

dbology keeps a private memory for each database connection — abbreviations, table conventions, and business rules specific to your organization.

It comes pre-loaded with common healthcare terms (PMPM, HCC, ADK, IBNR, etc.). As you work, dbology will suggest remembering new facts — for example, if you tell it "we always use the dw.fact_claims table for claims data", it will offer to save that so it remembers next time. Just answer "yes" and it sticks for future sessions.

You don't need to manage it manually — what it remembers is surfaced automatically when relevant. Tell dbology what you'd like it to remember and it handles the rest.

Switching computers

Your license allows activation on a set number of machines. To move to a new machine:

1. On your old machine, run: dbology deactivate
2. On your new machine, install and run dbology — the wizard will prompt for your license key again

Troubleshooting

"License not found" — double-check the key you entered. Keys are case-sensitive and formatted DBOL-XXXX-XXXX-XXXX.

"Seat limit reached" — your license is already active on the maximum number of machines. Run dbology deactivate on one of the other machines first.

Connection errors on startup — check that your database credentials are correct with /config, then select "Edit" on your profile.

Slow responses — switch to a faster model with /model and select claude-sonnet-4-6.

Unexpected query results — give dbology more context to remember. If it picked the wrong table, tell it: "use dw.fact_claims for claims data" and confirm when it offers to save.

Getting help

Email support@howaboutdata.com with questions or issues.