@codemirror/lang-sql

@codemirror/lang-sql is the official SQL language package for the CodeMirror 6 code editor. It provides a Lezer-based grammar for tokenizing SQL, driving syntax highlighting, code folding, and indentation inside any CodeMirror instance, plus a configurable autocompletion layer that can complete SQL keywords and, when given a schema, table and column names.

Rather than shipping a single fixed grammar, the package models SQL as a base tokenizer parameterized by a SQLDialect spec — keyword lists, type names, operator characters, identifier-quoting rules, and string-escaping behavior are all pluggable. This lets one small package cover StandardSQL plus ready-made dialects for PostgreSQL, MySQL, MariaDB, MSSQL, SQLite, Cassandra, and PL/SQL, and lets consumers define entirely custom dialects with SQLDialect.define().

The completion side goes beyond keyword lists: it resolves the syntax tree around the cursor to find table/column context (including detecting FROM ... AS alias aliases), and walks a nested SQLNamespace schema object supplied by the host application to offer contextually correct completions — for example, completing column names only after a recognized table or alias.

As part of the core codemirror organization (alongside @codemirror/lang-javascript, @lezer/*, etc.), it’s the standard way any CodeMirror-based editor, SQL playground, or admin/database UI adds SQL-aware editing without hand-writing a parser or autocomplete source.

What You Get

• A Lezer-based SQL grammar (sql.grammar) with tokenizers for keywords, identifiers, quoted identifiers, strings, numbers, bit/byte literals, comments, and operators, wired to CodeMirror’s highlighting, folding, and indentation systems
• Ready-made SQLDialect definitions for StandardSQL, PostgreSQL, MySQL, MariaDB, MSSQL, SQLite, Cassandra, and PL/SQL, each tuning keywords, types, quoting, and comment/escape rules for that vendor
• SQLDialect.define() and configureLanguage() for defining or extending a fully custom dialect (keyword lists, operator characters, identifier quote characters, bit-literal handling, etc.)
• keywordCompletionSource() for dialect-aware keyword/type completions, with optional upper-casing and custom Completion object construction
• schemaCompletionSource() / the schema option on sql() for turning a nested SQLNamespace object (schemas → tables → columns) into context-sensitive completions, including alias resolution from FROM ... AS x clauses
• A single sql(config) entry point that returns a CodeMirror LanguageSupport extension combining the chosen dialect’s language, keyword completion, and schema completion in one call

Common Use Cases

• SQL editor in a browser-based data tool - a query builder or database admin UI (e.g. an internal Postgres/MySQL console) embeds CodeMirror and drops in sql({dialect: PostgreSQL, schema}) to get highlighting plus table/column autocomplete straight from the app’s known schema.
• BI/analytics product query editors - a SaaS analytics or BI dashboard lets users hand-write SQL against their warehouse; lang-sql supplies the editing experience (highlighting, folding, keyword completion) without the product writing its own SQL tokenizer.
• Multi-dialect developer tooling - a tool that needs to support several database engines (e.g. MySQL and MSSQL) selects the matching built-in SQLDialect per connection rather than maintaining separate parsers.
• Custom/internal query language editors - teams with a SQL-like DSL use SQLDialect.define() to describe their own keyword and type set and reuse the grammar, tokenizer, and completion machinery instead of writing a bespoke one.
• Notebook and REPL-style SQL cells - embedded editors in data-notebook products use sql() for consistent, low-effort SQL syntax highlighting inside a broader CodeMirror-based notebook UI.

Under The Hood

Architecture The package layers a Lezer grammar (src/sql.grammar, compiled to sql.grammar.js/.d.ts) underneath two thin coordination modules: sql.ts, which configures the base parser with indentNodeProp/foldNodeProp/styleTags and exposes the SQLDialect class plus the eight built-in dialect constants (StandardSQL, PostgreSQL, MySQL, MariaSQL, MSSQL, SQLite, Cassandra, PLSQL), and complete.ts, which implements schema-aware completion by resolving the CodeMirror syntaxTree around the cursor into an identifier path (walking CompositeIdentifier/alias chains via parentsFor/getAliases) and matching that path against a CompletionLevel tree built from the user-supplied SQLNamespace. tokens.ts supplies the dialect-parameterized tokenizer (tokensFor(dialect)) that the grammar’s tokenizers array swaps in per dialect, so the single compiled grammar is reused across all eight variants rather than each dialect getting its own parser. The core abstraction a consumer depends on is the SQLDialect/SQLConfig contract — changing that would ripple into every dialect definition and the sql() entry point.

Tech Stack Written in TypeScript targeting ES modules ("type": "module"), built via the shared @codemirror/buildhelper tool (cm-buildhelper src/sql.ts in the prepare script) which handles bundling to dist/index.js/dist/index.cjs plus .d.ts generation, giving both ESM and CJS consumers a single entry point. Runtime dependencies are all first-party CodeMirror/Lezer packages — @codemirror/autocomplete, @codemirror/language, @codemirror/state, @lezer/common, @lezer/highlight, @lezer/lr — with no third-party runtime dependencies, keeping the package thin and consistent with the rest of the @codemirror/lang-* family. Tests run via cm-runtests, the shared CodeMirror test runner, rather than a general-purpose framework like Jest or Vitest.

Code Quality Tests live in test/test-tokens.ts and test/test-complete.ts using the ist assertion library and Mocha-style describe/it blocks, covering dialect-specific tokenization (bit literals, dollar-quoted strings, quoted identifiers) and completion behavior (schema traversal, alias resolution, quoting). Source files are compact and single-purpose (sql.ts, complete.ts, tokens.ts), use consistent camelCase naming, and lean on TypeScript’s type system for the public API (SQLDialectSpec, SQLConfig, SQLNamespace) with doc comments (///) that double as the source for the generated API reference in the README. Error handling is minimal by design — malformed input is left to the parser’s error-recovery grammar rather than throwing, which is standard for an incremental editor parser.

What Makes It Unique Rather than one grammar per SQL vendor, the package’s Dialect-parameterized tokenizer lets a single compiled Lezer grammar serve StandardSQL and seven vendor dialects by swapping keyword/type/operator/quoting tables at configuration time, and exposes that same mechanism publicly via SQLDialect.define() so consumers can add dialects the maintainers never anticipated. Its completion layer goes beyond flat keyword lists by resolving real syntactic context — including alias tracking through FROM ... AS clauses — against an arbitrarily nested schema object, which is a deeper level of schema-awareness than most lightweight editor-completion integrations attempt.