From 8358e63e2090f7e31f846b45fc5a2ed7750ff354 Mon Sep 17 00:00:00 2001 From: Arno Dirlam Date: Sat, 31 Oct 2026 18:51:22 +0100 Subject: [PATCH 1/2] Parser: Add opt-in psql script parsing --- README.md | 1 + src/ParserOptions.ts | 1 + src/cst/Expr.ts | 6 +++- src/cst/Node.ts | 1 + src/cst/Program.ts | 1 + src/cst/Psql.ts | 24 ++++++++++++++ src/cst/Statement.ts | 3 ++ src/parser.pegjs | 62 ++++++++++++++++++++++++++++++++++-- src/showNode/base.ts | 2 +- src/showNode/expr.ts | 2 ++ src/showNode/transformMap.ts | 3 ++ test/psql.test.ts | 34 ++++++++++++++++++++ 12 files changed, 135 insertions(+), 5 deletions(-) create mode 100644 src/cst/Psql.ts create mode 100644 test/psql.test.ts diff --git a/README.md b/README.md index 1f891c08..d50abb38 100644 --- a/README.md +++ b/README.md @@ -187,6 +187,7 @@ Note the following conventions: Parses SQL string and returns the CST tree. Takes the following options: - **dialect**: `'sqlite' | 'bigquery' | 'mysql' | 'mariadb' | 'postgresql' | 'plpgsql'` The SQL dialect to parse **(required)**. +- **psql**: `boolean` Enables parsing standalone psql backslash commands and variable references for PostgreSQL. Command text is preserved. - **includeRange**: `boolean` When enabled adds `range: [number, number]` field to all CST nodes, which contains the start and end locations of the node. - **includeComments**: `boolean` When enabled adds `leading: Whitespace[]` and/or `trailing: Whitespace[]` diff --git a/src/ParserOptions.ts b/src/ParserOptions.ts index deedf489..154fcbef 100644 --- a/src/ParserOptions.ts +++ b/src/ParserOptions.ts @@ -25,6 +25,7 @@ export type ParserOptions = { includeSpaces?: boolean; includeRange?: boolean; paramTypes?: ParamType[]; + psql?: boolean; /** SQL file name, used when reporting syntax errors */ filename?: string; }; diff --git a/src/cst/Expr.ts b/src/cst/Expr.ts index 4e4e7cf1..97a49633 100644 --- a/src/cst/Expr.ts +++ b/src/cst/Expr.ts @@ -10,6 +10,7 @@ import { WindowDefinition, } from "./Select"; import { Default } from "./Insert"; +import { PsqlIdentifier, PsqlVariable } from "./Psql"; import { PostgresqlOperator, PostgresqlOperatorExpr, @@ -36,6 +37,7 @@ export type AllExprNodes = | ArraySliceSpecifier; export type Expr = + | PsqlVariable | ListExpr | ParenExpr | BinaryExpr @@ -436,7 +438,9 @@ export interface ArraySliceSpecifier extends BaseNode { to?: Expr; } -export interface Identifier extends BaseNode { +export type Identifier = PlainIdentifier | PsqlIdentifier; + +export interface PlainIdentifier extends BaseNode { type: "identifier"; text: string; name: string; diff --git a/src/cst/Node.ts b/src/cst/Node.ts index 4449d635..8c57e025 100644 --- a/src/cst/Node.ts +++ b/src/cst/Node.ts @@ -32,6 +32,7 @@ export * from "./ProcClause"; export * from "./Procedure"; export * from "./ProceduralLanguage"; export * from "./Program"; +export * from "./Psql"; export * from "./Publication"; export * from "./RenameTable"; export * from "./Role"; diff --git a/src/cst/Program.ts b/src/cst/Program.ts index 6d893f4a..74a3cd8e 100644 --- a/src/cst/Program.ts +++ b/src/cst/Program.ts @@ -4,4 +4,5 @@ import { Statement } from "./Statement"; export interface Program extends BaseNode { type: "program"; statements: Statement[]; + psql?: boolean; } diff --git a/src/cst/Psql.ts b/src/cst/Psql.ts new file mode 100644 index 00000000..bd68a100 --- /dev/null +++ b/src/cst/Psql.ts @@ -0,0 +1,24 @@ +import { BaseNode } from "./Base"; +import { Statement } from "./Statement"; + +export interface PsqlCommand extends BaseNode { + type: "psql_command"; + text: string; +} + +export interface PsqlQuery extends BaseNode { + type: "psql_query"; + query: Statement; + terminator: string; +} + +export interface PsqlVariable extends BaseNode { + type: "psql_variable"; + text: string; +} + +export interface PsqlIdentifier extends BaseNode { + type: "psql_identifier"; + name: string; + text: string; +} diff --git a/src/cst/Statement.ts b/src/cst/Statement.ts index ec48b931..478fc77e 100644 --- a/src/cst/Statement.ts +++ b/src/cst/Statement.ts @@ -32,8 +32,11 @@ import { MergeStmt } from "./Merge"; import { TruncateStmt } from "./Truncate"; import { UpdateStmt } from "./Update"; import { DoStmt } from "./Do"; +import { PsqlCommand, PsqlQuery } from "./Psql"; export type Statement = + | PsqlCommand + | PsqlQuery | AllAlterTableStatements | AllBigqueryStatements | AllCommentStatements diff --git a/src/parser.pegjs b/src/parser.pegjs index 4ac04aee..aa54066a 100644 --- a/src/parser.pegjs +++ b/src/parser.pegjs @@ -50,10 +50,64 @@ } start - = c1:__ program:program c2:__ { + = &{ return options.psql && options.dialect === "postgresql"; } p:psql_program { return p; } + / c1:__ program:program c2:__ { return surrounding(c1, program, c2); } +psql_program + = items:(c1:__ x:(psql_command / psql_query) { return surrounding(c1, x, []); })* c2:__ { + return loc({ type: "program", statements: items, psql: true, trailing: c2 }); + } + +psql_query + = query:statement c:__ terminator:(";" / psql_query_command / !. { return ""; }) { + return loc({ type: "psql_query", query: trailing(query, c), terminator }); + } + +psql_query_command + = &psql_line_start text:$( "\\" ("gdesc" / "gexec" / "gset" / "gx" / "g") ![a-zA-Z_] psql_command_arguments) { + return text; + } + +psql_command + = &psql_line_start text:$("\\" psql_command_name psql_command_arguments) { + return loc({ type: "psql_command", text }); + } + +psql_command_name + = [^ \t\r\n\\]+ + +psql_line_start + = &{ return input.slice(input.lastIndexOf("\n", peg$currPos - 1) + 1, peg$currPos).trim() === ""; } + +psql_command_arguments + = (psql_single_quoted_argument / psql_double_quoted_argument / psql_backquoted_argument / !("\\" / end_of_line / "'" / "\"" / "`") .)* + +psql_single_quoted_argument + = "'" ("''" / "\\" . / !"'" .)* "'" + +psql_double_quoted_argument + = "\"" (!"\"" .)* "\"" + +psql_backquoted_argument + = "`" (!"`" .)* "`" + +psql_variable + = &{ return options.psql && options.dialect === "postgresql"; } + text:$(":" ("'" psql_variable_name "'" / psql_variable_name / "{?" psql_variable_name "}")) { + return loc({ type: "psql_variable", text }); + } + +psql_identifier + = &{ return options.psql && options.dialect === "postgresql"; } + ":" '"' name:$psql_variable_name '"' { + return loc({ type: "psql_identifier", name, text: text() }); + } + +psql_variable_name + = [a-zA-Z_0-9]+ + program = head:(statement / empty) tail:(__ ";" __ (statement / empty))* { return loc({ @@ -8116,7 +8170,8 @@ array_slice_specifier } primary - = literal + = psql_variable + / literal / primary_paren_expr / paren$compound_select_stmt / &bigquery x:(typed_array_expr / array_expr / typed_struct_expr) { return x; } @@ -8868,7 +8923,8 @@ explicit_alias_ident } ident "identifier" - = quoted_ident + = psql_identifier + / quoted_ident / name:ident_name !{ return isReservedKeyword(name); } { return loc(createIdentifier(name, name)); } diff --git a/src/showNode/base.ts b/src/showNode/base.ts index 449ec781..dda27907 100644 --- a/src/showNode/base.ts +++ b/src/showNode/base.ts @@ -10,5 +10,5 @@ export const baseMap: FullTransformMap< all_columns: () => "*", empty: () => "", alias: (node) => show([node.expr, node.asKw, node.alias, node.columnAliases]), - program: (node) => show(node.statements, ";"), + program: (node) => show(node.statements, node.psql ? "" : ";"), }; diff --git a/src/showNode/expr.ts b/src/showNode/expr.ts index 9f2eb1ae..87893cf0 100644 --- a/src/showNode/expr.ts +++ b/src/showNode/expr.ts @@ -3,6 +3,8 @@ import { AllExprNodes } from "../cst/Node"; import { FullTransformMap } from "../cstTransformer"; export const exprMap: FullTransformMap = { + psql_variable: (node) => node.text, + psql_identifier: (node) => node.text, list_expr: (node) => show(node.items, ","), paren_expr: (node) => "(" + show(node.expr) + ")", binary_expr: (node) => show([node.left, node.operator, node.right]), diff --git a/src/showNode/transformMap.ts b/src/showNode/transformMap.ts index 05357c39..fef53e29 100644 --- a/src/showNode/transformMap.ts +++ b/src/showNode/transformMap.ts @@ -1,4 +1,5 @@ import { alterActionMap } from "./alter_action"; +import { show } from "../show"; import { alterTableMap } from "./alter_table"; import { analyzeMap } from "./analyze"; import { baseMap } from "./base"; @@ -48,6 +49,8 @@ import { sqliteMap } from "./dialects/sqlite"; import { mysqlMap } from "./dialects/mysql"; export const transformMap: FullTransformMap = { + psql_command: (node) => node.text, + psql_query: (node) => show(node.query) + node.terminator, ...baseMap, // SELECT, INSERT, UPDATE, DELETE, TRUNCATE, MERGE diff --git a/test/psql.test.ts b/test/psql.test.ts new file mode 100644 index 00000000..9234bba2 --- /dev/null +++ b/test/psql.test.ts @@ -0,0 +1,34 @@ +import { parse, show } from "../src/main"; +import { includeAll } from "./test_utils"; + +describe("psql scripts", () => { + it.each([ + "\\set id 1\nSELECT :id, :'name' FROM :\"table\";\n\\quit\n", + "\\if :enabled\nSELECT 1\n\\gset result_\n\\else\nSELECT 2;\n\\endif\n", + "\\restrict abc123\nSELECT 1;\n\\unrestrict abc123\n", + "-- heading\nSELECT 1; -- trailing\n\\echo 'done'\n", + "SELECT 1\n\\gexec\nSELECT 2;", + "SELECT 1", + "\\echo 'two words with ''quotes'''\n", + '\\echo "two words"\n', + "\\echo `printf hi`\n", + "\\unknown value\n", + "SELECT :id, :'name', :\"table\", :{?enabled};", + ])("round-trips %s", (sql) => { + const tree = parse(sql, { dialect: "postgresql", psql: true, ...includeAll }); + expect(show(tree)).toBe(sql); + expect(tree.psql).toBe(true); + }); + + it.each(["SELECT\n\\echo partial\n1;", "SELECT 1 \\gset", "\\echo hi \\\\ SELECT 1;"])( + "rejects unsupported command placement or syntax: %s", + (sql) => { + expect(() => parse(sql, { dialect: "postgresql", psql: true })).toThrow(); + } + ); + + it("requires opt-in and the PostgreSQL dialect", () => { + expect(() => parse("\\quit", { dialect: "postgresql" })).toThrow(); + expect(() => parse("\\quit", { dialect: "sqlite", psql: true })).toThrow(); + }); +}); From 0a00400f981eafca6b8670dc7aaece1b5548b633 Mon Sep 17 00:00:00 2001 From: Arno Dirlam Date: Sat, 31 Oct 2026 19:25:23 +0100 Subject: [PATCH 2/2] Package: Build parser for Git installs --- package.json | 1 + 1 file changed, 1 insertion(+) diff --git a/package.json b/package.json index 03ef978a..1956c666 100644 --- a/package.json +++ b/package.json @@ -35,6 +35,7 @@ "test:plpgsql": "jest --config test/config/plpgsql.json", "test:all": "yarn test:sqlite && yarn test:bigquery && yarn test:mysql && yarn test:mariadb && yarn test:postgresql && yarn test:plpgsql", "test": "yarn generate && yarn test:all", + "prepare": "yarn build", "perf:big": "yarn ts-node perf/perf-test.ts big", "perf:func": "yarn ts-node perf/perf-test.ts func", "perf:paren": "yarn ts-node perf/perf-test.ts paren",