@axiomdb/sql-parser

SQL tokenizer and parser for AxiomDB.

Installation

npm install @axiomdb/sql-parser

Overview

Parses SQL strings into an AST representation. Used internally by @axiomdb/babel-plugin, @axiomdb/ts-plugin, and the VS Code extension.

Note: This is primarily an internal package. The API may change between minor versions.

Usage

Tokenizing

The tokenize function converts template literal parts into tokens. It accepts the quasis (string parts) and expressions (interpolated values) from a tagged template, plus an optional dialect.

import { tokenize, postgresql } from "@axiomdb/sql-parser";

const quasis = ["SELECT id, name FROM users WHERE id = ", ""];
const expressions = [userId];

const tokens = tokenize(quasis, expressions, postgresql);

Parsing

The parse function converts tokens into a single SQL statement AST node. Use parseMulti for SQL that may contain multiple semicolon-separated statements.

import { parse, parseMulti, tokenize, postgresql } from "@axiomdb/sql-parser";

const tokens = tokenize(["SELECT id, name FROM users WHERE active = ", ""], [true], postgresql);

// Single statement
const ast = parse(tokens, postgresql);

// Multiple statements (returns array if more than one, or a single SqlStatement)
const multi = parseMulti(tokens, postgresql);

Dialect-specific parsing

Each dialect adds keywords and operators specific to its database. Import dialects from the main export:

import { postgresql, mysql, mssql } from "@axiomdb/sql-parser";

Or from the /dialects subpath export:

import { postgresql, mysql, mssql } from "@axiomdb/sql-parser/dialects";

Pass a dialect to tokenize and parse to enable dialect-specific syntax:

const tokens = tokenize(quasis, expressions, mysql);
const ast = parse(tokens, mysql);

Without a dialect, PostgreSQL is used as the default.

AST node types

The parser produces typed AST nodes for each SQL statement kind:

| Node type | SQL | |-----------|-----| | SqlSelect | SELECT queries | | SqlInsert | INSERT statements | | SqlUpdate | UPDATE statements | | SqlDelete | DELETE statements | | SqlMerge | MERGE statements | | SqlCall | CALL / EXEC statements | | SqlCTEWrapper | WITH ... AS (...) wrapper | | SqlSetOperation | UNION / INTERSECT / EXCEPT | | SqlTransactionControl | BEGIN / COMMIT / ROLLBACK |

Expression and clause nodes include SqlColumnRef, SqlFunctionCall, SqlSubqueryExpr, SqlJoin, SqlWindowDef, SqlWhereComparison, and many more. See the exported types from the package for the full list.

Exported types

import type { Token, TokenType, SqlStatement, SqlSelect, SqlDialect } from "@axiomdb/sql-parser";

License

MIT