Current user-facing configuration is supplied through CLI flags and environment variables.

Runtime

spiral sql --threads 8

--threads controls the SQL client engine worker count.

If --threads is omitted, Spiral uses the default worker count derived from available parallelism.

Output

spiral sql --max-rows 50 --max-columns 12 --max-cell-width 48

--max-rows controls the REPL preview size. The REPL wraps relation-producing queries with a logical limit of max_rows + 1, displays at most max_rows, and uses the extra row to report that more rows are available.

--max-columns controls how many columns are printed. When omitted, the REPL fits as many columns as it can into the detected terminal width. Set --max-columns 0 to print all columns.

--max-cell-width sets the per-header and per-cell cap used only when the result table would exceed the detected display width. Set --max-cell-width 0 to print unbounded text.

History

When SPIRAL_HISTORY is unset, the REPL tries ~/.spiral_history.

If no history file can be opened, the REPL falls back to in-memory history for the current process.

SQL configuration

The SQL command supports a trace flag for execution diagnostics:

spiral sql --trace=/tmp/spiral-trace.json -c "SELECT 1;"
spiral sql --trace-ui --trace=/tmp/spiral-trace.json -c "SELECT 1;"

--trace-ui serves the trace from 127.0.0.1:9001, opens it in https://ui.perfetto.dev, and keeps the local server running until the process is interrupted.

The SQL path also supports trace settings:

SET trace = 'perfetto';
SET trace.output = '/tmp/spiral-trace.json';
SET trace.level = 'debug';
SET trace.next = '/tmp/next-query-trace.json';

Other user-facing configuration is supplied through CLI flags and environment variables.