Skip to content
varcDocs
Varc
Docs

Developer Tools

SQL

Validate and execute Redis-aware SELECT, UPDATE, and EXPLAIN statements from the Varc CLI.

Varc CLI exposes the same Redis-aware SQL planner and execution engine as the desktop app. One sql run command accepts SELECT, UPDATE, EXPLAIN SELECT, or EXPLAIN UPDATE; the statement determines the operation.

Create a named query

Keep SQL in a normal project file and register it in varc.toml:

[queries.expire_sessions]
path = "queries/expire-sessions.sql"
connection = "local"
database = 0
UPDATE redis
SET ttl_ms = 60000
WHERE key LIKE 'session:%'
RETURNING key, ttl_ms
LIMIT 100

Named paths resolve relative to the containing varc.toml. A query definition may contain any supported SELECT, UPDATE, or EXPLAIN statement.

Validate without connecting

varc sql validate expire_sessions
varc sql validate --file queries/inspect.sql
printf 'SELECT key FROM redis LIMIT 10' | varc sql validate --stdin
varc sql validate --statement "EXPLAIN SELECT key FROM redis LIMIT 10"

Validation reads one bounded UTF-8 statement and calls the SQL planner. It returns the statement kind and source-ranged diagnostics without resolving a connection or contacting Redis. Invalid SQL exits with status 2.

The source limit is 1 MiB. A name, --file, --stdin, and --statement are mutually exclusive, and stdin is read only when --stdin is explicit.

Execute a statement

varc sql run expire_sessions
varc sql run --file queries/inspect.sql
varc sql run --statement "SELECT key, type, ttl_ms FROM redis LIMIT 100"

Use global --connection, --url, or --url-env to select a direct target. --database overrides the named query or connection database. The global connection selector takes precedence over a named query’s connection.

SELECT and UPDATE are prepared before Varc connects, then execute with the SQL engine’s default bounded segments. Varc automatically continues each paused segment until the query completes, fails, or is interrupted. SQL LIMIT remains the caller-controlled row or update limit.

EXPLAIN returns the semantic plan directly and never resolves or opens a connection:

varc sql run --statement \
  "EXPLAIN UPDATE redis SET ttl_ms = 60000 WHERE key LIKE 'session:%' LIMIT 100"

Read the result

Human output is an escaped tab-separated table followed by returned-row and updated-row counts. UPDATE without RETURNING prints its updated-row count; UPDATE RETURNING uses the same table as SELECT.

varc --format json sql run --file queries/inspect.sql

JSON mode writes one versioned envelope to stdout. It includes the source, statement kind, lifecycle, columns, every result row, terminal progress, and a terminal error when execution fails. Rows are fetched page by page and written incrementally, so the CLI does not collect the complete result in memory. Binary cells, decimal integers, special doubles, JSON scalars, collection summaries, cardinality, and truncation metadata retain their tagged forms. Process-local job IDs, result handles, snapshot versions, and page cursors are not exposed.

Ctrl-C or SIGTERM cancels the native job, waits for terminal progress, prints the terminal result, releases the result index, and closes the client. An interrupted execution exits with status 130; a terminal execution failure is non-zero after any retained rows and progress have been emitted.

Next steps