Directives

Query-file directives are SQL line comments with machine-readable fields.

tonic-file

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

Allowed fields:

• target
• context.<key>
• autocommit

Rules:

• Must appear before the first SQL statement.
• Only one tonic-file directive is allowed.
• May declare target, context, autocommit, or any combination.

tonic-bind

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

Allowed fields:

• handle
• target
• context.<key>
• autocommit

Rules:

• Must appear before the first SQL statement.
• handle and target are required.
• Each handle may only be declared once.

tonic

-- tonic: handle=writer
update jobs set last_run_at = current_timestamp where name = 'daily_sales';

Allowed fields:

• target
• handle
• context.<key>

Rules:

• Applies to the next SQL statement only.
• handle cannot be combined with target.
• autocommit is not allowed.
• Blank lines are allowed before the statement, but unrelated comments break the association.

Context Merge Order

Context resolves from broadest to most specific:

1. CLI --context key=value defaults.
2. tonic-file context.
3. tonic-bind context.
4. Per-statement tonic context.

If a handle fixed a specific context key, a statement cannot override that key to a different value.