sql

func AppendRowLimit ¶ added in v0.18.33

func AppendRowLimit(sql string, info *SelectInfo, n int) string

AppendRowLimit returns sql bounded to at most n rows, when a LIMIT can be appended to it without changing what it means.

It exists because two of the four subquery constructs do not want a SET. EXISTS asks whether there is A row and a scalar subquery is an ERROR past ONE, so reading the whole result to answer either is work nobody asked for — and on the DML door it was a WRONG REFUSAL: that door bounds what a subquery may return (54000, `WADJET_IN_SET_MAX`), so `DELETE FROM t WHERE EXISTS (SELECT 1 FROM big)` refused at the ten thousandth row of a question one row answers, and a scalar subquery past the bound reported 54000 where this engine's own rule is 21000. Bounding the READ puts each construct back inside the rule it is judged by: IN keeps the bound because IN really does need the set.

The append is declined — sql is returned unchanged — when the query already bounds itself with LIMIT or OFFSET, or is a UNION, because in those spellings a trailing LIMIT is not an append: it is either a syntax error or a second, differently-scoped bound. Those keep whatever behaviour they had.

info must be the parse of sql. Callers that hold one (the correlated evaluators parse once at compile time and rebuild per row) pass it; callers that hold only text use WithRowLimit.

func CheckSingleStatement ¶ added in v0.18.23

func CheckSingleStatement(sql string) error

CheckSingleStatement refuses a string that carries more than one statement, the way PostgreSQL refuses one at an entry point that answers with a single result.

THE ORDER IS PART OF THE ANSWER, and it is measured against 17.11 rather than remembered. PostgreSQL parses the whole string first, so

INSERT INTO t (id) VALUES (1); INSERT INTO t (id) VALUES (2)
    -> 42601  cannot insert multiple commands into a prepared statement
INSERT INTO t (id) VALUES (1); ZZZ NOT SQL
    -> 42601  syntax error at or near "ZZZ"

A syntax error anywhere in the string outranks the multi-command refusal, and reporting the multi-command message for the second one would tell a client its SQL was fine when it was not. Both carry 42601.

A single statement costs nothing here: the string is not parsed twice, because the caller is about to parse it anyway.

func CoerceBooleanLiterals ¶ added in v0.18.30

func CoerceBooleanLiterals(info *SelectInfo) error

CoerceBooleanLiterals resolves an UNKNOWN-typed literal used as a truth value, which is the one shape a boolean context accepts that is not already a boolean (#599).

PostgreSQL types a bare quoted literal from the context it meets, so a boolean context runs it through the boolean input function: measured live on postgres:17-alpine, `SELECT 1 WHERE 'true'`, `'yes'`, `'t'` and `' 1 '` all SUCCEED, `WHERE NULL` succeeds and returns nothing, and `WHERE 'abc'` is 22P02 `invalid input syntax for type boolean: "abc"` — NOT the 42804 a typed non-boolean gets.

Wadjet answered 0 rows for all four, because nothing typed the literal at all: `expr.FilterPredicate`'s generic arm takes a failed `v.(bool)` assertion for FALSE. So this runs at parse time, where the literal can simply BECOME the boolean it names.

The grammar is PostgreSQL's `parse_bool_with_len`, the same one `CAST(<string> AS BOOLEAN)` already follows (ADR-0012): case-insensitive, C whitespace trimmed, any non-empty PREFIX of "true"/"false"/"yes"/"no", plus "on"/"off" and the single characters "1" and "0". `'tr'` and `'fals'` ARE values; `'o'` alone is not, because it cannot choose between "on" and "off".

func ExprIdentity ¶ added in v0.18.6

func ExprIdentity(n Node) string

ExprIdentity renders an expression in the canonical form that answers "are these the same expression?".

Three spelling differences are erased, and only these three:

• PARENTHESES. `(g + 1)`, `((g) + 1)` and `g + 1` are one identity. The parse tree already records the grouping, so a ParenNode carries no information the tree does not.
• IDENTIFIER CASE. `G + 1` and `g + 1` are one identity, the way PostgreSQL folds an unquoted identifier.
• WHITESPACE. `g+1` and `g + 1` are one identity, which the AST rendering already gave.

Nothing else is erased. Associativity in particular is NOT: `g - 1 - 2` is `(g - 1) - 2` and `g - (1 - 2)` is itself, and the two identities differ, because the two expressions differ. That is why the rendering is fully parenthesised at every infix node rather than relying on String()'s precedence-free output — dropping a ParenNode and printing `a * b + c` for `a * (b + c)` would make two DIFFERENT expressions one identity, which is the wrong answer in the more dangerous direction.

func ExprIdentityUnqualified ¶ added in v0.18.21

func ExprIdentityUnqualified(n Node) string

ExprIdentityUnqualified is ExprIdentity with TABLE QUALIFIERS erased as well, so `typemx.g + 1` and `g + 1` are one identity (#738).

It is a SEPARATE function and not a fourth rule in ExprIdentity, because erasing a qualifier needs a SCOPE that this file does not have: `a.x` and `b.x` over a join are two expressions and `t.x` and `x` in a single-relation block are one. Only a caller holding the block's FROM list can tell them apart, and exactly one does — physical.groupCheck, which uses this when the block has ONE source and ExprIdentity when it has more.

Erasing it unconditionally would make two different expressions one identity, which is the failure this file's header calls "the wrong answer in the more dangerous direction".

func FoldIdent ¶ added in v0.18.30

func FoldIdent(s string) string

FoldIdent is the case fold PostgreSQL applies to an UNQUOTED identifier: ASCII A-Z becomes a-z and NOTHING else changes.

The ASCII restriction is PostgreSQL's own, measured on postgres:17-alpine with a UTF8 server encoding: `CREATE TABLE t (Ä int)` stores the column as `Ä`, and `SELECT 1 AS Ä` publishes `Ä`. strings.ToLower would fold it to `ä` and invent a name no PostgreSQL client would expect, so the fold is written out byte by byte rather than borrowed from unicode.

func GroupKeyName ¶ added in v0.18.6

func GroupKeyName(n Node) string

GroupKeyName is the column name a GROUP BY term's value is published under by the aggregate, on both execution paths.

A bare column reference keeps its own name with any delimiters stripped, so `GROUP BY "g + 1"` names the column `g + 1` and not the four-token string `"g + 1"` the worker's hash aggregate cannot find in a batch (#725). Anything else — a computed key — is named by its own rendered text with redundant outer parentheses removed, so `GROUP BY (g + 1)` and `GROUP BY g + 1` publish ONE name and a SELECT item spelled either way resolves to it.

Case is PRESERVED: this is a name a batch column is matched against by bytes, so the name must be what the value is actually published under. ExprIdentity, which is only ever compared, is the one that folds case.

func HasTopLevelReturning ¶ added in v0.18.5

func HasTopLevelReturning(sql string) bool

HasTopLevelReturning reports whether a DML statement writes a RETURNING clause outside any parentheses.

RETURNING is not a lexer keyword, so every clause that collects raw text swallowed it and then answered differently: bare `DELETE FROM t RETURNING *` took it as the table's ALIAS, `DELETE ... WHERE id = 1 RETURNING *` fed it to the WHERE's complete-parse and called legal SQL a syntax error, and `INSERT ... RETURNING id` dropped it in silence and reported INSERT 1. One check over the whole statement gives all four doors the same answer: it is a legal statement whose feature this server has not implemented, so 0A000 (#686 R2-4).

An unquoted RETURNING is always the clause — PostgreSQL reserves the word, so a column of that name must be double-quoted, and a quoted identifier is not matched here.

func HasTopLevelWhereToken ¶ added in v0.18.5

func HasTopLevelWhereToken(sql string) bool

HasTopLevelWhereToken reports whether sql spells a WHERE keyword outside any parentheses.

It exists for one caller: the backstop in wadjet.BuildDMLPredicate, which has to tell "this DELETE is unconditional because it was written that way" from "this DELETE is unconditional because the parser dropped its WHERE". The two are indistinguishable in DMLTarget.WhereSQL, and the second one empties tables (#686).

The lexer decides, not strings.Contains: a WHERE inside a string literal ('WHERE') or a quoted identifier ("where") is not a clause, and a WHERE belonging to a SUBQUERY (`SET n = (SELECT ... WHERE ...)`) is not this statement's clause either — hence the depth counter.

func IsAggregate ¶

func IsAggregate(name string) bool

IsAggregate returns true if the function name is a known aggregate.

func LeadingKeyword ¶ added in v0.18.20

func LeadingKeyword(sql string) string

LeadingKeyword returns a statement's first keyword, uppercased, with leading whitespace and comments skipped — or "" when the statement has no keyword.

It exists because a TEXT PREFIX is not a classifier. pgwire decided "is this DML" with `strings.HasPrefix(upper, "INSERT ")` — a literal space — so `INSERT\nINTO t …`, `UPDATE\tt SET …` and `/* hint */ UPDATE …` all missed the branch. Multi-line SQL is what every ORM and JDBC prepared statement emits and a `/* … */` prefix is what sqlcommenter prepends, so the miss was the common case, not the corner: those statements fell through to the QUERY path, which meant Describe EXECUTED the write and Execute ran it AGAIN — a duplicated row reported as `SELECT 1` (review B3).

The lexer already knows what a comment and a quoted identifier are, so this asks it rather than re-deciding.

func NormalizeIdentRef ¶

func NormalizeIdentRef(s string) string

NormalizeIdentRef strips the delimiters from an identifier reference so that it reads as the plain column name the execution layer matches against batch schemas: `"id.orig_h"` → id.orig_h, `"my tbl"."c"` → my tbl.c. Strings that are not a bare identifier reference (expressions, function calls, literals) are returned unchanged.

func OuterColumnCandidates ¶

func OuterColumnCandidates(subquerySQL string) []string

OuterColumnCandidates returns the column names a subquery may read from the query that ENCLOSES it: every reference it cannot resolve against its own FROM clause. Subqueries nested inside it are walked too, so a correlation two levels down is reported at the top.

It exists for column pruning. A column a correlated subquery reads is a column the outer query NEEDS, even when it appears nowhere in the outer SELECT list or WHERE clause — and the pruning walk had no case for a subquery node at all, so it never saw one. The outer batch then carried no such column, readOuterValues substituted NULL for it, every comparison against that NULL was UNKNOWN, and the query answered 0 rows with no indication anything had gone wrong (issue #347).

It is deliberately over-inclusive where it cannot be sure. An unqualified name is reported even though the subquery's own FROM may well supply it, because deciding that needs a catalog this package does not have. Naming a column the outer relation does not have costs nothing — the caller filters candidates against the scan's own schema (sanitizeScanNeeds) — while missing one it does have is the wrong answer above. A reference qualified by one of the subquery's own tables or aliases is the one case it can rule out, and does.

A subquery that does not parse yields no candidates: the expression compiler parses the same text and declines to build a correlated evaluator for it, and the runtime guard in readOuterValues fails loudly if one is built anyway.

func OutputColumnName ¶ added in v0.18.43

func OutputColumnName(col SelectColumn) string

OutputColumnName is the name PostgreSQL publishes an unaliased SELECT item under — its `FigureColname`, decided from the parsed AST and never from the expression's TEXT.

The whole rule, measured on PostgreSQL 17 over 49 spellings (#732):

g, t.g, (g)                       → g            (the column)
(c_row).b                         → b            (the FIELD)
abs(g), count(*), sum(g) OVER ()  → abs, count, sum   (the function)
CASE …, COALESCE, NULLIF, GREATEST → case, coalesce, …
EXISTS (…)                        → exists
ARRAY[…]                          → array
EXTRACT(YEAR FROM d)              → extract
CAST(g AS int), g::int            → g            (the ARGUMENT)
CAST('2020-01-01' AS date)        → date         (the TYPE, only when the
                                                  argument has no name)
(SELECT g FROM … LIMIT 1)         → g            (the subquery's column)
g + 1, -g, 1, 'abc', g IS NULL,
g = 1, g BETWEEN 1 AND 2,
g IN (1,2), g || 'x', (SELECT 1)  → ?column?

A CAST is the one PostgreSQL gets asked about most and the one most often guessed wrong: it is named after its ARGUMENT, and reaches for the type only when the argument itself is unnamed. The brief for arc E3 said "a CAST → the TYPE" and the measurement said otherwise.

Several `?column?` in one SELECT list is legal and is what PostgreSQL does: `SELECT g + 1, g + 2` returns two columns of that name. Output slots have identity by POSITION (#556/#557), so a duplicate published name is not a collision.

It returns "" for a STAR, which has no single name.

func ParseBoolText ¶ added in v0.18.30

func ParseBoolText(s string) (bool, bool)

ParseBoolText is PostgreSQL's boolean input function, `parse_bool_with_len`. Exported because two doors need the SAME grammar and a second copy is how they drift: a boolean CONTEXT here, and CAST(<string> AS BOOLEAN) in the expression compiler.

func QuoteIdent ¶

func QuoteIdent(name string) string

QuoteIdent renders an identifier so that re-parsing it yields the same identifier. Names the lexer would otherwise re-read as something else — embedded dots (a flat JSON column such as id.orig_h), spaces, other punctuation, a leading digit, an ASCII UPPER-CASE letter (which the lexer folds, #731), or a keyword spelling — come back double-quoted with any interior quote doubled. Names that already lex as a single unquoted identifier are returned unchanged, so printed SQL for ordinary columns is byte-identical to what it was before delimited identifiers existed.

func RebuildSQL ¶

func RebuildSQL(info *SelectInfo, rewrittenWhere Node) string

RebuildSQL reconstructs a full SELECT SQL string from a SelectInfo, using the provided expression as the WHERE clause instead of the original. This is used by the correlated subquery evaluator to substitute outer values.

func RefuseReservedSlotName ¶ added in v0.18.6

func RefuseReservedSlotName(name, where string) error

RefuseReservedSlotName returns the 42939 (reserved_name) refusal for a name a user is CREATING that collides with a hidden slot, or nil when it does not. where names the site, so the message says which door saw it.

Call it where a name is MINTED BY THE USER: a SELECT alias, a derived table's or a CTE's output names, and the DDL and ingest doors (CREATE TABLE, the CreateTable API, an Ingester's schema, an INSERT column list that creates a column).

Do NOT call it on a table's STORED columns at read time. Reading is not minting: the column already exists, some binary wrote it, and refusing it makes the table unreadable by every query — including the `SELECT *` that would show the user what is in it — while CREATE TABLE, the Go API and INSERT all still succeeded, so the trap closed behind the user with DROP TABLE the only exit. A stored collision is handled by renumbering the PLANNER's slot instead (renameCollidingSlots), so the two coexist.

func RefuseReservedSlotNames ¶ added in v0.18.6

func RefuseReservedSlotNames(names []string, where string) error

RefuseReservedSlotNames refuses the first colliding name in names, in sorted order so the message does not depend on map iteration.

func RefuseUnsupportedStatement ¶ added in v0.18.42

func RefuseUnsupportedStatement(pq *ParsedQuery) error

RefuseUnsupportedStatement is the refusal a door owes a parsed statement no handler of that door accepts. It returns nil for a statement that IS a query, so a door calls it once, at the point it dispatches by statement type, immediately after its own handlers have had their turn.

#860: `ALTER TABLE` — and `CREATE VIEW`, `DROP VIEW`, and on the HTTP door the alert and snapshot statements — parse into a ParsedQuery whose type no branch handles, so every door fell through to ExtractSelect and reported `no SELECT info in parsed query`: an internal invariant's wording, with no SQLSTATE on the HTTP door and the blanket 42000 through pgwire. A client cannot branch on that, and the message names nothing it wrote.

The disposition is 0A000 (feature_not_supported), which is already this engine's class for a shape it parses and cannot execute (`RETURNING is not supported`, above), and the message names the STATEMENT. It is raised here rather than inside ExtractSelect because a better message from ExtractSelect would still be produced by planner code, one call site at a time, for a statement no planner should ever have been handed.

func ReservedSlotFamily ¶ added in v0.18.6

func ReservedSlotFamily(name string) string

ReservedSlotFamily returns the slot prefix name collides with, or "".

The comparison is case-insensitive because column resolution is: a user who writes `__WIN_0` reaches the same slot every consumer looks up.

func RevertGroupByAliasesShadowedByInput ¶ added in v0.18.16

func RevertGroupByAliasesShadowedByInput(info *SelectInfo, provides func(bare string) bool)

RevertGroupByAliasesShadowedByInput applies PostgreSQL's precedence for a bare GROUP BY name: an INPUT COLUMN wins over a SELECT alias.

The parser substitutes such a name with the alias's defining expression unconditionally, and its own doc comment claimed the opposite ("a table column with the same name keeps precedence over the alias") — protocol item 9's exact failure mode, a record describing intended behaviour as present behaviour. There is no precedence check in the parser and there cannot be one: it has no schema and no scope. So the substitution is provisional and this undoes it, called from the layer that knows what the FROM sources provide.

provides reports whether one of this block's own sources carries the bare name. It must answer only where it is CERTAIN: an unenumerable source (a table function, a SELECT *, a table absent from the catalog) has to answer false, which keeps the substitution and the pre-#739 answer.

The wrong-answer shape this closes: `SELECT h AS g, COUNT(*) FROM gcov GROUP BY g, h` grouped by (h, h) and answered 2 rows where PostgreSQL — which groups by (g, h) — answers 6. Both engines answered, and they answered different numbers.

func SetAlertIntervalFloorForTest ¶

func SetAlertIntervalFloorForTest(d time.Duration) func()

SetAlertIntervalFloorForTest lowers the CREATE ALERT interval floor for the duration of a test. Call the returned function (typically with defer) to restore the production floor.

func SlotName ¶ added in v0.18.6

func SlotName(family SlotFamily, n int) string

SlotName is the Nth slot of a family: `SlotName(SlotWindowOutput, 0)` is `__win_0`.

Minting a slot through this rather than through a local fmt.Sprintf is what keeps the reservation and the names in one place — a family whose names are built somewhere else is a family the refusal below does not really cover.

func SplitIdentRef ¶

func SplitIdentRef(s string) (qualifier, name string, ok bool)

SplitIdentRef interprets s as an identifier reference and returns its optional qualifier and its name. Quoting is honoured, so the qualifier split happens only at a dot the lexer actually produced:

l_orderkey     → ("", "l_orderkey")
o.o_custkey    → ("o", "o_custkey")
"id.orig_h"    → ("", "id.orig_h")   — one delimited name, not qualified
"my tbl"."c"   → ("my tbl", "c")

ok is false for anything that is not a bare identifier reference (a function call, an arithmetic expression, a literal, a multi-level path); callers then fall back to their own string handling.

func SplitStatements ¶ added in v0.18.23

func SplitStatements(sql string) []string

SplitStatements splits a SQL string into the statements a client wrote, separated by TOP-LEVEL semicolons.

It exists because PostgreSQL's simple query protocol carries a whole script in one message and runs it as a SEQUENCE, one CommandComplete per statement. Everything here that reached a semicolon before this did `strings.TrimRight(sql, ";")` and nothing else, so a two-statement string was ONE statement to every parser below it — and what happened to the tail then depended on which sub-parser consumed it. `INSERT …; INSERT …` ran the first and silently dropped the second, and `INSERT …; ZZZ NOT SQL` ran the INSERT and silently ignored the garbage, where PostgreSQL runs neither (#711).

THE LEXER DECIDES, not strings.Split. A semicolon is a separator only where it is a semicolon TOKEN at paren depth zero, so

UPDATE t SET name = 'a;b' WHERE id = 1     -- one statement
SELECT "a;b" FROM t                        -- one statement
SELECT 1 -- ; not a separator
SELECT $$a;b$$                             -- one statement
SELECT /* ; */ 1                           -- one statement

all stay whole: the lexer reads string literals, dollar-quoted strings, double-quoted identifiers and both comment forms, so none of them can emit a TokenSemicolon.

The DEPTH counter is the same guard HasTopLevelWhereToken uses. A semicolon inside parentheses cannot separate statements in any legal SQL, and treating one as a separator would cut a statement in half and report the halves' errors instead of the statement's. When the parens never balance — the input is malformed — depth never returns to zero, nothing is split, and the whole string goes to Parse, which is where a malformed statement's error belongs.

A lex ERROR (an unterminated string literal, say) stops the scan and the unconsumed remainder is returned as one final piece, for the same reason: the error is the statement's, and Parse is what reports it.

A piece with NO STATEMENT IN IT is dropped, and that means whitespace, semicolons AND COMMENTS. `SELECT 1; -- trailing comment` is one statement in PostgreSQL and was one statement here before this function existed; treating the comment as a second statement made that string — and `…; /* banner */`, and a stray `--` from an editor, and the `-- query tag` every ORM appends — a two-statement string that every one-statement door then refused with 42601. Trimming whitespace alone is not enough for the same reason `strings.Split` is not enough one paragraph up: only the lexer knows what a comment is. A piece whose first token is EOF holds nothing to run.

An input with no statement at all yields nil, which callers read as PostgreSQL's EmptyQuery — and PostgreSQL answers a comment-only query string with exactly that.

func WindowOutputName ¶ added in v0.18.6

func WindowOutputName(col SelectColumn) string

WindowOutputName is the name a SELECT-list window column is published under.

The alias where the query gave one, and otherwise the FUNCTION's name, which is what PostgreSQL 17 calls it:

SELECT SUM(a) OVER () FROM t              -- PostgreSQL: "sum"
SELECT ROW_NUMBER() OVER (ORDER BY id)…   -- PostgreSQL: "row_number"

FIVE places name this column and they have to agree: the logical builder's projection (which decides what the operator emits), the embedded API's deriveColumns (the single-process result schema), the binder's blockOutputs (a derived table's namespace), and the two positional-ORDER-BY resolvers. They did not: an unaliased window was `sum(a) OVER (...)` in four of them and the empty string in the fifth, so the projection published nothing, the result schema asked for the text, and `ORDER BY 1` rewrote to a name with parentheses in it that no sort key could resolve.

It lives here rather than in the logical package because the parser cannot import the planner, and the positional resolvers are in the parser.

func WithRowLimit ¶ added in v0.18.33

func WithRowLimit(sql string, n int) string

WithRowLimit is AppendRowLimit for a caller that holds only the subquery text. A statement that does not parse is returned unchanged: this function decides how much to READ, never what is legal, and the compiler and the runner both raise on their own for text they cannot use.