Quick Start

This quick start uses SQLite because it does not need secrets or server setup.

1. Add A Project-Local Target

tonic connections add sqlite scratch --path ./scratch.db --local

--local writes to <repo-root>/.tonic/config.yaml when you are inside a git repository. Outside a git repository, it writes to ./.tonic/config.yaml.

2. Check Connectivity

tonic query ping --target scratch

Expected shape:

ok target="scratch" backend=sqlite

3. Run Inline SQL

tonic query exec --target scratch --sql 'select sqlite_version() as version'

Inline SQL is intentionally single-statement. Use query files for multi-statement workflows.

4. Try JSON Output

tonic query exec \
  --target scratch \
  --format json \
  --sql "values (1, 'alpha'), (2, 'bravo')"

table, csv, and json are supported for query execution.

5. Execute A Query File

Create scratch.sql:

-- tonic-file: target=scratch

select 1 as id, 'from-file' as source;

select 2 as id, 'same-primary-session' as source;

Run it:

tonic query exec --file scratch.sql

File execution prints each statement header and result as that statement finishes in table and CSV modes, so you can follow a longer file while it runs. JSON output is emitted once after the whole file finishes.

6. Inspect Objects

tonic inspect tables --target scratch --refresh

--refresh bypasses the persistent inspect cache and fetches live metadata.