Modern abstraction over SQL

VS Code extension

Install the VSIX, use local language services, inspect inferred relation types, and run workspace commands without leaving the editor.

What The VSIX Includes

The BtrQL VSIX bundles syntax highlighting, the PostgreSQL and ClickHouse language servers, compiler integration, formatting, navigation, and the BtrQL Outline. It runs locally and uses the project.json and schema metadata in the folder you open. Generated SQL remains the deployment artifact; the extension is an authoring and build-time tool.

The demo package includes compilation, formatting, diagnostics, completion, navigation, Outline, and project builds. Commands that require reverse conversion, schema comparison, or debugging remain visible but explain that a full-capability package is required.

Editor And Language Features

For .btrql files the extension provides:

  • semantic syntax highlighting and live diagnostics;
  • formatting through Format Document;
  • completion for query operations, tables, fields, imports, extension members, and earlier sequential aliases;
  • hover, signature help, go to definition, references, document highlights, workspace symbols, and inlay hints;
  • the standard VS Code Outline and the richer BtrQL Outline;
  • local project builds using the bundled compiler.

Completion is relation-aware and position-specific. At top level it offers only top-level statements such as extension; at a direct extension-member boundary it offers only method and column. A relation step after . offers applicable relation methods, a scalar expression offers fields, constants, scalar functions, and applicable extension columns, and a relation operand or table-kind argument offers compatible relations and table functions. Scalar- and relation-type positions receive their corresponding type categories. Qualified scalar suggestions are resolved against the relation alias, and earlier aliases in select or addColumn are available only to later expressions.

Freeze A Derived Extension Result

An extension method can normally omit its result annotation and let the compiler infer it. To protect a reusable method from unintended shape changes, insert => immediately before its existing =. In that empty annotation slot, the editor offers exactly one completion: the complete currently derived symbolic result.

extension [user_id: INTEGER] {  method joinOrders(other: [buyer_id: INTEGER]) => T0 ++ T1 =    self      .innerJoin(other on user_id == buyer_id)}

Receiver and table-argument shapes are minimum contracts. This method requires only the join key from T0 and the join key from T1; wider relations satisfy those contracts and retain their additional columns when T0 ++ T1 is instantiated.

The suggestion is generated from the same semantic renderer as Outline. Accepting it does not override inference: it adds a checked annotation, and a later implementation change that produces a different normalized relation type becomes an error. A body must already follow = so the editor has a result to derive.

BtrQL Outline

Run BtrQL: Outline or open BtrQL Outline in Explorer. It shows relations, imported modules, schema symbols, output columns, inferred scalar types, lineage, extension columns, and symbolic extension-method results. Select an entry to navigate to its declaration.

The standard VS Code Outline and BtrQL Outline use the same result-type renderer. Relation variables are displayed as T0, T1, and later variables; concrete scalar types retain names such as INTEGER, VARCHAR, Int32, and String. Use BtrQL: Configuration to choose optional column metadata shown in the BtrQL Outline.

Command Reference

Open the command palette and type BtrQL.

Command Availability Purpose
BtrQL: Outline Demo and full Focus the BtrQL Outline and refresh inferred relation types.
BtrQL: Configuration Demo and full Select optional Outline metadata columns.
BtrQL: Build Project Demo and full Compile the current workspace using project.json.
BtrQL: Convert SQL Selection To BtrQL Full Reverse the selected SQL into BtrQL.
BtrQL: Show Schema Comparison Full Compare declared/cached and live schema metadata.
BtrQL: Debug Pipeline At Cursor Full Start a relation-pipeline debugging session at the cursor.
BtrQL: Show Debug History Full Reopen recent debugger sessions and evaluations.
BtrQL: Smart Delete Left Demo and full Preserve BtrQL-aware deletion behavior; bound to Backspace in writable BtrQL editors.

VS Code's built-in Format Document, Go to Definition, Go to References, Show Hover, and Go to Symbol commands invoke the corresponding BtrQL language features when a .btrql document is active.

Settings

The extension exposes these workspace settings:

  • btrql.lsp.logLevel controls language-server logging.
  • btrql.lsp.wireTrace writes JSON-RPC traffic to the local runtime log directory for troubleshooting.
  • btrql.lsp.targetDialectVersion temporarily overrides the dialect version from project.json.
  • btrql.lsp.maxRestartCount limits automatic language-server restarts before crash-loop protection stops retrying.

Prefer project configuration for checked-in dialect and schema behavior. Use editor settings for local diagnostics and troubleshooting.

Installation And Troubleshooting

Install the package with Extensions: Install from VSIX..., open the folder containing project.json, and reload the window if prompted. The VSIX must match the operating system and architecture because it contains local native executables.

If language features do not start:

  1. confirm that VS Code opened the project folder rather than a single file;
  2. verify that project.json names postgresql or clickhouse and points to readable schema metadata;
  3. open Output → BtrQL to inspect startup diagnostics;
  4. enable btrql.lsp.wireTrace only while investigating protocol behavior;
  5. run BtrQL: Build Project to distinguish editor state from compiler diagnostics.