Modern abstraction over SQL

VS Code Getting Started

BtrQL is easiest to try from Visual Studio Code: install the demo VSIX for your operating system and architecture, then use the bundled language support for syntax highlighting, diagnostics, formatting, and workspace commands.

Production does not need a BtrQL runtime. The editor helps you write and check source; the deliverable remains generated SQL that you review, test, and run with existing database drivers, migration tools, and runbooks.

Download The Demo VSIX

Direct demo downloads:

Requirements:

  • Visual Studio Code
  • the demo VSIX matching your platform
  • on Windows, the same.NET 11 runtime required by the Windows CLI toolchain

The macOS and Linux packages are self-contained. The Windows VSIX uses the framework-dependent Windows CLI/LSP toolchain built on macOS.

The Free Local license applies only to demo artifacts. The VSIX does not report project files, schemas, generated SQL, telemetry, or error reports over the internet.

Install The VSIX

Use the Visual Studio Code command palette and run Extensions: Install from VSIX..., then select the downloaded package such as btrql-demo-osx-arm64.vsix.

After installation, open a folder containing .btrql files and reload the window if VS Code prompts you.

The demo VSIX includes syntax highlighting, local language support, formatting, and workspace build commands. Debugger support is not included in the demo VSIX.

Run Commands In VS Code

Open the command palette and type BtrQL to see the installed commands.

  • BtrQL: Outline shows inferred relation types, columns, imports, and lineage.
  • BtrQL: Configuration controls optional Outline metadata.
  • BtrQL: Build Project reads project.json and writes generated SQL into the configured output-folder.
  • Full-capability packages also enable SQL conversion, schema comparison, and pipeline debugging commands.

While you edit .btrql files, diagnostics, completion, formatting, and navigation stay available directly in the editor. See the VS Code extension guide for the complete command reference, result-type completion, and troubleshooting.

Optional Examples Bundle

Download the examples ZIP for two ready-to-open, source-only projects: postgresql/ and clickhouse/. Each project contains separate .btrql files for features supported by that target; generated SQL and unsupported-dialect diagnostics are intentionally omitted.

Extract the ZIP, open the target project in VS Code, and configure its live database through BTrQL: Configure Live Database. The included project.json uses obvious credential placeholders and the vscode-secret profile, so real credentials can stay in VS Code SecretStorage.

Open A BtrQL Project

The smallest useful project has source files, schema metadata, and a generated SQL folder:

project/  project.json  schema metadata  src/    main.btrql  generated/​

project.json names the target dialect, schema metadata path, and generated SQL folder:

{  "output-folder": "generated",  "target-dialect": "postgresql",  "schema-cache-path": "schema metadata"}​

Open the folder in VS Code, edit .btrql files, and use the generated SQL as the review surface before deployment.

Existing SQL Files

BtrQL projects can contain both .btrql and .sql files. Keep existing SQL where it already works, then add BtrQL for new or repeated query logic.

When the compiler can parse a SQL file, objects defined there can expose typed symbols to the rest of the BtrQL project. If a SQL feature is not supported by the language yet, create the table, view, function, or stored procedure in a test database and import its catalog metadata into the BtrQL project.

Where To Go Next

  • Use the VS Code extension guide for editor features, commands, Outline, and troubleshooting.
  • Use Syntax overview for the grammar and core source surface in detail.
  • Use Walkthroughs for end-to-end source and generated SQL walkthroughs.
  • Use Actual novelty when moving from one source file to a project layout.
  • Use Application integration for ownership, bind variables, result mapping, deployment boundaries, and examples in Java, Python, and TypeScript.
  • Check Feature matrix before relying on a dialect or feature.
  • Read Support scope to understand current non-goals and unsupported surfaces.

Frequently Asked Questions

How does the BtrQL compiler validate table names and columns offline?

BtrQL uses a cached metadata JSON file or active database connections specified in project.json. The compiler uses this information to build a local schema cache, allowing it to validate query shapes entirely offline in your editor without querying a live database.

Can I use the VS Code extension without installing the local BtrQL CLI?

The VS Code extension includes an embedded version of the compiler, so you can perform basic editing, syntax highlighting, and queries out-of-the-box. However, the CLI tool is required for advanced build scripts and CI/CD pipelines.

What is the purpose of the project.json file in BtrQL workspaces?

The project.json file serves as the configuration root for a BtrQL workspace, defining compiler options, dialect targets, schema metadata sources, and source file locations.