Query Files

Query files let the SQL artifact describe how its statements resolve targets and sessions.

Use query files when you need more than one statement, reusable sessions, transaction state, or visible per-statement target changes.

File Defaults

tonic-file declares default metadata before the first SQL statement.

-- tonic-file: target=warehouse context.schema=analytics autocommit=off

select * from reports.daily_sales;

Allowed fields are target, autocommit, and context.<key>.

Reusable Handles

tonic-bind declares a named reusable session before the first SQL statement.

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

Required fields are handle and target. Optional fields are autocommit and context.<key>.

Per-Statement Overrides

tonic applies to the next SQL statement only.

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

-- tonic: target=scratch context.schema=temp
select * from one_off_table;

Allowed fields are target, handle, and context.<key>.

handle and target cannot be combined in the same tonic directive. autocommit is not allowed on per-statement directives.

Placement

Only SQL line comments are recognized:

• -- tonic-file: ...
• -- tonic-bind: ...
• -- tonic: ...

tonic-file and tonic-bind must appear before the first SQL statement. A tonic directive may have blank lines before its statement, but unrelated comments break the association.

Execution Modes

Statements run in one of three modes:

• primary: the file default target/context and reusable primary session.
• handle: a reusable session bound by tonic-bind and selected with tonic: handle=....
• ephemeral: a one-off per-statement target or context override.

Ephemeral sessions are closed immediately after the statement and always use autocommit=on in the current implementation.