Support variables in SELECT queries

[BorisTyshkevich]

Problem

altinity-sql-browser should support SQL queries with typed variables, for example:

WITH
    {database:String} AS p_database,
    {table:String} AS p_table
SELECT ...

Currently, there is no UI flow for detecting these variables while editing SQL and providing values before execution.

Proposed feature

While the user is typing a SQL query, the app should detect variables in the ClickHouse placeholder format:

{name:Type}

For every detected variable, show an input field below the SQL editor header where the user can enter a value.

Example detected variables:

{database:String}
{table:String}

Should render fields like:

database: [________]
table:    [________]

Execution behavior

When the query is executed, the app should substitute the variables with the entered values before sending the SQL to ClickHouse.

Example:

WITH
    {database:String} AS p_database,
    {table:String} AS p_table
SELECT ...

With values:

database = default
table = events

Should be sent to ClickHouse as:

WITH
    'default' AS p_database,
    'events' AS p_table
SELECT ...

Scope

This feature should apply only to SELECT queries.

It should not apply to VIEW definitions. Views have their own variables, and those variables should not be substituted by the app.

Requirements

• Detect variables in the format {name:Type} while editing SQL.
• Show a row below the SQL editor header with inputs for detected variables.
• Keep variable values editable before execution.
• Substitute variables only when executing SELECT queries.
• Do not substitute variables in VIEW definitions.
• Preserve existing behavior for queries without variables.

Acceptance criteria

• A SELECT query containing {database:String} and {table:String} displays two input fields: database and table.
• Running the query sends SQL with the entered values substituted.
• A VIEW definition containing variables is sent unchanged.
• Queries without variables continue to work as before.

[BorisTyshkevich]

Design resolved — ready to implement

{name:Type} is ClickHouse's native query-parameter syntax, so this feature is a UI + execution wrapper over CH's own parameter substitution — not client-side string rewriting. Decisions:

Substitution mechanism — native CH params. Values are sent as param_<name>=… query-string params; ClickHouse substitutes them server-side per the declared type. Injection-safe, type-correct for Identifier/DateTime/Array/Map/etc., and the reusable template (not a one-off substituted string) is what lands in history/share/saved queries. The params seam already exists (chUrl → runQuery/exportQuery).

When to substitute — read statements only. Pass params for SELECT / WITH…SELECT / EXPLAIN of those. Never pass params for CREATE [MATERIALIZED] VIEW, CREATE TABLE, INSERT, etc. This makes the "views unchanged" requirement fall out for free: a CREATE VIEW … {x:String} … is stored verbatim (exactly how CH parameterized views work). Classification is per statement, so in multi-statement script mode a script's reads get params and its DDL does not.

Detection. Parse {name:Type} while ignoring string literals and comments, and handle nested-paren types (Array(String), Map(String,UInt8), Tuple(...), Decimal(10,2)). Pure logic in src/core/, 100% covered.

UI. A single-line strip below the editor toolbar, one name: [____] text input per variable, that scrolls horizontally when there are many variables (no wrapping; scrolls, never clips — verified down to 360px mobile). The strip is shown only when a substitutable statement in the tab actually contains variables, so editing a CREATE VIEW with placeholders shows no fields. Label = variable name; type shown as placeholder/tooltip. Plain text inputs (no type-aware widgets in v1).

Values. Held per-tab, in memory — survive tab switches within a session, cleared on reload. Not persisted to localStorage, saved queries, or share links.

Empty values. Run is disabled until every detected variable has a value, so we never send a query with an unfilled placeholder.

Not to be confused with #39 (composable queries, {{name}} double-brace CTE-merge) — a separate feature with different syntax and semantics.

[BorisTyshkevich]

Update — variable-value scope (supersedes the earlier "per-tab, in-memory" decision).

Values are now shared by variable name and persisted (asb:varValues in localStorage), not per-tab/ephemeral: a value typed for {database:String} is reused and prefilled automatically by every query that references the same variable, and it survives tab switches, loading queries from history/library, and page reloads. Implemented on PR #138.