Tonic

Status: Alpha

tonic is a terminal-first database workspace for explicit SQL execution against saved targets.

It starts with a CLI, and now also exposes the first local service boundary over stdio so editor integrations can build on the same execution model.

Tonic stands for Tiny Octopus Navigating Infinite Catalogs. Why?... Why not?

Install

Homebrew

brew tap fairlabs/tap https://forgejo.fairlabs.dev/fairlabs/homebrew-tap.git
brew install tonic

Nix

nix profile install git+https://forgejo.fairlabs.dev/fairlabs/tonic.git

Run without installing:

nix run git+https://forgejo.fairlabs.dev/fairlabs/tonic.git

What It Is

The current shape of tonic is:

• saved local database targets
• explicit execution from inline SQL and query files
• file-scoped session metadata for multi-target workflows
• one shared runtime for CLI execution and the local serve boundary

tonic is not an ad hoc connection-string runner. Execution starts from a saved named target in effective config, then uses a consistent target-resolution and session model across commands.

Effective config means:

• global config from $XDG_CONFIG_HOME/tonic/config.yaml or ~/.config/tonic/config.yaml
• optional local override config from <repo-root>/.tonic/config.yaml when running inside a git repo, or ./.tonic/config.yaml outside a repo
• local connections replace same-named global connections as whole entries
• other config keys such as inspect_cache merge field-by-field

Current CLI Surface

config

• tonic config connections add postgres NAME [--local]
• tonic config connections add snowflake NAME [--local]
• tonic config connections add sqlite NAME [--local]
• tonic config connections add mysql NAME [--local]
• tonic config connections show [NAME]
• tonic config connections edit [--local]

query

• tonic query ping --target NAME
• tonic query exec --target NAME --sql '...'
• tonic query exec --file path.sql
• tonic query inspect catalogs --target NAME
• tonic query inspect namespaces --target NAME
• tonic query inspect tables --target NAME
• tonic query inspect views --target NAME
• tonic query inspect view-definition OBJECT --target NAME
• tonic query inspect columns OBJECT --target NAME
• tonic query inspect ddl OBJECT --target NAME --type ...

serve

• tonic serve --stdio

serve now exposes the first local JSON-RPC boundary over stdio. It reuses the same target resolution, inspection behavior, artifact parsing, and execution rules as the CLI.

Inspect requests served through serve now use tonic-owned persistent metadata caching with config-driven TTLs, and support explicit live refetch via the optional refresh=true request field on inspect methods.

What Works Today

• saved Postgres, Snowflake, and MySQL targets
• saved SQLite targets
• connectivity and context checks with query ping
• inline SQL execution with query exec --sql
• query-file execution with query exec --file
• catalog inspection with query inspect
• Snowflake inspect descriptions from object comments
• table, csv, and json output
• text and json output for definitions and DDL
• reusable primary and handle-bound file sessions
• file directives with tonic-file, tonic-bind, and tonic
• write statements, explicit transaction control, and --autocommit on|off
• explicit statement permissions with inherited global defaults and per-target allow/deny overrides
• explicit supported statement matching for select, DML, transaction control, and registered read-like/provider-specific statements such as show, describe, explain, values, call, merge, and replace
• opt-in Snowflake browserauth credential caching with one automatic retry when a stale cached login needs a fresh browser auth flow
• local stdio JSON-RPC service methods for targets, query execution, artifact planning, catalog inspection, and reusable sessions

query inspect currently supports:

• catalogs, namespaces, tables, views, view definitions, and table columns on Postgres and Snowflake
• catalogs, tables, views, view definitions, and table columns on MySQL
• namespaces, tables, views, view definitions, and table columns on SQLite
• descriptions for Snowflake catalogs, namespaces, tables, views, and columns
• DDL for catalogs, namespaces, tables, and views on Snowflake
• DDL for tables and views on MySQL and SQLite
• unquoted object references in name, namespace.name, and catalog.namespace.name forms

For file execution, tonic already supports reusable transaction-aware sessions with:

• file default sessions
• handle-bound sessions
• ephemeral one-off statement overrides
• explicit begin, commit, rollback, savepoint, release, and rollback to

Query Files

tonic query files let the SQL artifact describe how statements resolve targets and sessions.

Example:

-- tonic-file: target=warehouse context.schema=analytics autocommit=off
-- tonic-bind: handle=writer target=warehouse context.schema=public autocommit=off

select * from reports.daily_sales;

-- tonic: handle=writer
update reports.job_state set last_run_at = now() where name = 'daily_sales';

This is the core product direction: explicit query artifacts with local saved targets and predictable session behavior.

Inspect Cache

Inspect metadata is cached persistently in tonic using a local SQLite database. The cache is lazy-populated from inspect calls, shared across clients, and governed by effective tonic config.

Default behavior:

• inspect metadata is reused from cache when it is still fresh
• the default TTL is 168h (7 days)
• tonic query inspect ... --refresh forces a live refetch and overwrites the cached value
• tonic serve inspect requests accept refresh=true for the same bypass semantics

Example tonic config:

version: 2
inspect_cache:
  path: /home/you/.local/state/tonic/inspect-cache.db
  ttl: 168h

Near-Term Direction

The next layers on top of this core are:

• reusable inline sessions across separate CLI invocations
• expanding the serve runtime beyond the first stdio JSON-RPC surface
• editor, agent, and TUI clients built on that shared runtime

Docs

• docs/cli-shape.md
• docs/add-backends.md
• docs/execution-model.md
• docs/query-files.md
• docs/transactions.md
• docs/introspection.md
• docs/serve-contract.md
• docs/statements/README.md
• docs/statements/permissions.md

The docs are the source of truth for the execution model the repo is converging on.

Last Change

0.3.0: Added Snowflake inspect descriptions from object comments for catalogs, namespaces, tables, views, and columns.