Esquema de cada comando soportado con railroad diagram (mermaid), gramática EBNF, ejemplos válidos y errores típicos. Equivalente al syntax diagrams de SQLite o al SQL command reference de PostgreSQL — pero acotado al subset que gabysql ya entrega.

Para el inventario exhaustivo de lo que NO está implementado todavía (comandos faltantes, prioridades, bloques de implementación sugeridos), ver MISSING_COMMANDS.md.

Para el detalle del formato en disco que respalda esta gramática, ver TECHNICAL_SPECS.md. Para el AST en código, src/sql.rs.

📊 ¿No ves los railroad diagrams? Este documento usa 17 bloques mermaid + 1 en ARCHITECTURE.md. Si los ves como código en lugar de gráfico, tu renderer no soporta mermaid. Soluciones:

• GitHub web: los renderiza nativamente desde 2022. Si no se ven, refrescá hard (Ctrl+F5).
• VS Code: instalá la extensión bierner.markdown-mermaid — sin ella el Markdown Preview no los pinta.
• Obsidian / Typora / Joplin: lo soportan nativamente.
• GitHub mobile: NO los renderiza — abrir en navegador desktop.
• PDF export: requiere mermaid-cli (npm i -g @mermaid-js/mermaid-cli) o usar Pandoc + filtro.

Los 17 bloques de este archivo + el de ARCHITECTURE.md fueron validados sintácticamente el 2026-05-29 — si alguno no renderiza es porque el renderer cortó por límite de nodos (raro), no porque el código mermaid esté roto.

🧭 Índice de comandos

🔤 Identificadores

Tablas, columnas e índices comparten una sola regla. Definida en catalog::validate_identifier.

• Forma léxica: [A-Za-z_][A-Za-z0-9_]*
• Longitud máxima: 64 caracteres (MAX_IDENT_LEN)
• Case-insensitive en comparación, case-preserving en almacenamiento
• No puede ser una palabra reservada del parser

Palabras reservadas (case-insensitive): add, alter, and, between, bool, column, create, database, databases, date, datetime, default, delete, drop, exists, false, float, from, if, index, insert, int, into, json, key, limit, not, null, offset, on, primary, select, set, show, table, text, true, unique, update, values, where.

Errores típicos:

🧱 Tipos de dato soportados

flowchart LR
    INT["INT<br/>i64 little-endian"]
    TEXT["TEXT<br/>UTF-8 bytes"]
    BOOL["BOOL<br/>0 ó 1"]
    FLOAT["FLOAT<br/>f64 little-endian"]
    DATE["DATE<br/>texto ISO-8601"]
    DATETIME["DATETIME<br/>texto ISO-8601"]
    TIME["TIME<br/>texto HH:MM:SS[.fff]"]
    UUID["UUID<br/>texto 8-4-4-4-12 hex"]
    JSON["JSON<br/>texto, no indexable"]
    NULL["NULL<br/>solo en columnas no PK"]

No soportado todavía: BLOB/BYTEA/BINARY (binario crudo), DECIMAL exacto, ARRAY[T], ENUM(...), INTERVAL, TIME WITH TIME ZONE, TIMESTAMP WITH TIME ZONE. Diferidos a Y2.

CREATE DATABASE

Solo en modo server multi-DB (-dir) o CLI con un directorio. Crea un archivo .db aplicando el formato VERSION = 33 (bump P4 por column stats persistidas, ver ADR-0068). En modo single-DB (-db) responde 405.

🛤️ Railroad

flowchart LR
    S([▶]) --> C[CREATE] --> D[DATABASE]
    D --> IFNE{IF NOT EXISTS?}
    IFNE -- "no" --> N[/db_name/]
    IFNE -- "sí" --> IF[IF] --> NOT[NOT] --> EX[EXISTS] --> N
    N --> SEMI[";"] --> E([■])

📜 EBNF

create_database ::= "CREATE" "DATABASE" ("IF" "NOT" "EXISTS")? identifier

✅ Ejemplos

CREATE DATABASE shop;
CREATE DATABASE IF NOT EXISTS analytics;

❌ Errores típicos

DROP DATABASE

Elimina el archivo .db y su .wal si quedó. Acción irreversible, sin respaldo.

🛤️ Railroad

flowchart LR
    S([▶]) --> D[DROP] --> DB[DATABASE]
    DB --> IFE{IF EXISTS?}
    IFE -- "no" --> N[/db_name/]
    IFE -- "sí" --> IF[IF] --> EX[EXISTS] --> N
    N --> SEMI[";"] --> E([■])

📜 EBNF

drop_database ::= "DROP" "DATABASE" ("IF" "EXISTS")? identifier

✅ Ejemplos

DROP DATABASE analytics;
DROP DATABASE IF EXISTS legacy;

❌ Errores típicos

SHOW DATABASES

🛤️ Railroad

flowchart LR
    S([▶]) --> SH[SHOW] --> DBS[DATABASES] --> SEMI[";"] --> E([■])

📜 EBNF

show_databases ::= "SHOW" "DATABASES"

✅ Resultado

Devuelve una ResultSet con una columna database, un row por DB ordenado alfabéticamente:

{ "columns": ["database"], "rows": [["analytics"], ["shop"]], "message": null }

CREATE TABLE

🛤️ Railroad diagram

flowchart LR
    Start([▶]) --> CREATE[CREATE]
    CREATE --> TABLE[TABLE]
    TABLE --> Name[/identifier/]
    Name --> POPEN["("]
    POPEN --> Col[ColumnDef]
    Col --> COMMA{","}
    COMMA -- "sí" --> Col
    COMMA -- "no" --> PCLOSE[")"]
    PCLOSE --> SEMI[";"]
    SEMI --> End([■])

flowchart LR
    S([ColumnDef]) --> N[/identifier/]
    N --> T[/type/]
    T --> CST{constraint?}
    CST -- "no" --> E([fin])
    CST -- "PRIMARY KEY" --> CST
    CST -- "NOT NULL" --> CST
    CST -- "UNIQUE" --> CST
    CST -- "DEFAULT lit" --> CST

📜 EBNF

create_table   ::= "CREATE" "TABLE" identifier "(" table_item ("," table_item)* ")"
table_item     ::= column_def | table_constraint
column_def     ::= identifier type column_constraint*
column_constraint ::= [ "CONSTRAINT" identifier ]
                    ( "PRIMARY" "KEY"
                    | "NOT" "NULL"
                    | "UNIQUE"
                    | "DEFAULT" default_value
                    | "CHECK" "(" expr ")"
                    | "REFERENCES" identifier "(" identifier ")" fk_action* )
table_constraint  ::= [ "CONSTRAINT" identifier ]
                    ( "PRIMARY" "KEY" "(" identifier { "," identifier } ")"
                    | "UNIQUE" "(" identifier { "," identifier } ")"
                    | "CHECK" "(" expr ")"
                    | "FOREIGN" "KEY" "(" identifier { "," identifier } ")"
                        "REFERENCES" identifier "(" identifier { "," identifier } ")" fk_action* )
fk_action      ::= ("ON" "DELETE" | "ON" "UPDATE")
                   ("RESTRICT" | "CASCADE" | "SET" "NULL" | "SET" "DEFAULT" | "NO" "ACTION")
type           ::= "INT" | "TEXT" | "BOOL" | "FLOAT" | "DATE" | "DATETIME" | "JSON"
literal        ::= integer | float | string | "TRUE" | "FALSE" | "NULL"
default_value  ::= literal | default_fn
default_fn     ::= ("gen_random_uuid" | "uuid_v4" | "uuid_generate_v4" | "random_uuid"
                  | "uuid_v7" | "uuid_generate_v7" | "gen_uuid_v7"
                  | "current_timestamp" | "now") "(" ")"
identifier     ::= [A-Za-z_][A-Za-z0-9_]*

Notas:

• PRIMARY KEY implica NOT NULL. Sigue habiendo una sola PK por tabla (puede ser compuesta PRIMARY KEY (a, b, ...) con K2/VERSION 8, todas INT NOT NULL).
• UNIQUE inline auto-genera un índice unique con nombre uq_<tabla>_<col> (ver CREATE UNIQUE INDEX). UNIQUE (a, b, ...) table-level reusa el encoder K2.
• DEFAULT NULL es válido pero incompatible con NOT NULL en la misma columna.
• DEFAULT no se admite sobre la PK.
• El literal de DEFAULT debe coincidir con el tipo de la columna; name TEXT DEFAULT 1 se rechaza en CREATE TABLE.
• DEFAULT <fn>() (N5, 2026-05-30): además de literales, DEFAULT acepta una llamada sin argumentos a una función pura del whitelist: gen_random_uuid (alias: uuid_v4, uuid_generate_v4, random_uuid), uuid_v7 (alias: uuid_generate_v7, gen_uuid_v7), current_timestamp (alias: now). La función se re-evalúa por fila en cada INSERT. Funciones fuera del whitelist se rechazan en CREATE TABLE. Ver ADR-0066 Gap 6.
• CHECK (expr) (L2/VERSION 10) admite cualquier expresión Expr (booleana 3VL ANSI). Se evalúa en INSERT/UPDATE/UPSERT/cascade. Subqueries dentro de CHECK se rechazan con [GBY-4069]. Persistencia como texto canónico vía format_expr + reparse en cada open. [GBY-3008] CHECK_VIOLATED cuando falla.
• REFERENCES <tabla>(<col>): el target column debe ser la PK del parent (no se admiten FKs contra UNIQUE no-PK). El tipo de la FK debe coincidir con el de la PK referenciada. Self-references válidas. Acciones referenciales completas en ON DELETE y ON UPDATE (L1/V9 + residual #4): RESTRICT (default), CASCADE, SET NULL, SET DEFAULT, NO ACTION. FK multi-col (residual #3/V12) via constraint table-level FOREIGN KEY (a, b) REFERENCES p (x, y) — target debe ser la PK compuesta del parent, lookup O(log n) por fingerprint K2.
• CONSTRAINT <name> (residual #2/V11): nombre opcional para PK/UNIQUE/FK/CHECK; útil con ALTER TABLE DROP CONSTRAINT <name> después.

✅ Ejemplos válidos

CREATE TABLE users (
  id INT PRIMARY KEY,
  email TEXT NOT NULL UNIQUE,
  name TEXT,
  active BOOL DEFAULT TRUE,
  score FLOAT,
  status TEXT NOT NULL DEFAULT 'pending',
  born DATE,
  meta JSON
);

CREATE TABLE orders (
  id INT PRIMARY KEY,
  user_id INT REFERENCES users(id) ON DELETE CASCADE,
  total FLOAT,
  tries INT DEFAULT 0
);

-- Self-reference: cada empleado puede tener un manager (que también es empleado).
CREATE TABLE employee (
  id INT PRIMARY KEY,
  name TEXT NOT NULL,
  manager_id INT REFERENCES employee(id)
);

❌ Errores típicos

CREATE INDEX

🛤️ Railroad

flowchart LR
    S([▶]) --> C[CREATE] --> I[INDEX] --> N[/index_name/]
    N --> ON[ON] --> T[/table_name/]
    T --> POPEN["("] --> COL[/column_name/] --> PCLOSE[")"] --> SEMI[";"] --> E([■])

📜 EBNF

create_index ::= "CREATE" "UNIQUE"? "INDEX" identifier "ON" identifier "(" identifier ")"

✅ Ejemplos

-- Crear índice (backfill automático sobre las filas ya existentes)
CREATE INDEX idx_users_name ON users (name);
CREATE INDEX idx_orders_status ON orders (status);

-- Índice único: el backfill aborta si existen duplicados; en caliente
-- INSERT/UPDATE conflictivos se rechazan antes de tocar disco.
CREATE UNIQUE INDEX uq_users_email ON users (email);

❌ Errores típicos

Reglas: una sola columna por índice, solo equality (=). UNIQUE permite múltiples NULL. Ver ADR-0005.

DROP INDEX

🛤️ Railroad

flowchart LR
    S([▶]) --> D[DROP] --> I[INDEX] --> N[/index_name/] --> SEMI[";"] --> E([■])

📜 EBNF

drop_index ::= "DROP" "INDEX" identifier

✅ Ejemplos

DROP INDEX idx_users_name;

❌ Errores típicos

DROP INDEX no libera las páginas del B+Tree del índice. La reclamación queda para una futura herramienta vacuum (ver STATUS.md).

DROP TABLE

Borra la entrada de la tabla en el catálogo. Las páginas backing (data + índices secundarios de esa tabla) no se liberan; el espacio se reclama con un futuro vacuum.

🛤️ Railroad

flowchart LR
    S([▶]) --> D[DROP] --> T[TABLE]
    T --> IFE{IF EXISTS?}
    IFE -- "no" --> N[/table_name/]
    IFE -- "sí" --> IF[IF] --> EX[EXISTS] --> N
    N --> SEMI[";"] --> E([■])

📜 EBNF

drop_table ::= "DROP" "TABLE" ("IF" "EXISTS")? identifier

✅ Ejemplos

DROP TABLE users;
DROP TABLE IF EXISTS scratch;

❌ Errores típicos

ALTER TABLE ADD COLUMN

Agrega una columna al final del esquema. Las filas previas se decodifican con su DEFAULT (o NULL) sin reescritura — el rewrite ocurre naturalmente cuando un UPDATE toca esa fila.

🛤️ Railroad

flowchart LR
    S([▶]) --> A[ALTER] --> T[TABLE] --> N[/table_name/]
    N --> ADD[ADD] --> COL{COLUMN?} --> CD[ColumnDef]
    CD --> SEMI[";"] --> E([■])

📜 EBNF

alter_table_add ::= "ALTER" "TABLE" identifier "ADD" "COLUMN"? column_def
column_def       ::= identifier type column_constraint*

✅ Ejemplos

ALTER TABLE users ADD COLUMN nick TEXT;
ALTER TABLE users ADD COLUMN status TEXT NOT NULL DEFAULT 'pending';
ALTER TABLE users ADD COLUMN email TEXT UNIQUE;
ALTER TABLE users ADD score FLOAT DEFAULT 0;     -- COLUMN es opcional

❌ Errores típicos

Restricciones: para DROP COLUMN, RENAME COLUMN y RENAME TABLE ver la sección DDL extendido (K1). PK compuesta + índices compuestos cerrados en K2 (VERSION 8, ver ADR-0019). ALTER ... TYPE y ALTER PK siguen pendientes.

DDL extendido (K1)

Bloque K1 (2026-05-26). Cuatro sentencias DDL adicionales que no cambian el formato en disco (VERSION sigue en 7).

CREATE TABLE [IF NOT EXISTS] [(col_aliases)] AS SELECT

Materializa el resultado de una SelectQuery (SELECT, set ops o VALUES) como una tabla nueva. La primera columna del result-set debe ser INT no-NULL y se promueve a PRIMARY KEY.

ctas ::= "CREATE" "TABLE" ("IF" "NOT" "EXISTS")? identifier
         ("(" identifier ("," identifier)* ")")?
         "AS" select_query ";"

CREATE TABLE activos AS SELECT id, nombre FROM usuarios WHERE id > 0;
CREATE TABLE IF NOT EXISTS dst (pk, label) AS SELECT id, nombre FROM src;
CREATE TABLE lit (id, label) AS VALUES (1, 'a'), (2, 'b');
CREATE TABLE merged AS SELECT id, nombre FROM a UNION SELECT id, nombre FROM b;

Errores típicos: [GBY-4058] primera columna no INT no-NULL · [GBY-4063] arity de aliases ≠ arity del SELECT · [GBY-2004] el destino ya existe (sin IF NOT EXISTS).

RENAME TABLE / ALTER TABLE ... RENAME TO

rename_table ::= "RENAME" "TABLE" identifier "TO" identifier ";"
              |  "ALTER" "TABLE" identifier "RENAME" "TO" identifier ";"

RENAME TABLE old TO new;
ALTER TABLE old RENAME TO new;

Las FKs entrantes (otras tablas que referencien old) se reescriben automáticamente al nuevo nombre. Errores: [GBY-4062] destino tomado · [GBY-2001] origen no existe.

ALTER TABLE ... DROP COLUMN [IF EXISTS]

alter_drop ::= "ALTER" "TABLE" identifier "DROP" "COLUMN"
               ("IF" "EXISTS")? identifier ";"

ALTER TABLE users DROP COLUMN nick;
ALTER TABLE users DROP COLUMN IF EXISTS deprecated_flag;

Bloqueado sobre la PK ([GBY-4059]), columnas indexadas ([GBY-4060], sugiere DROP INDEX <name> primero) y columnas con FK saliente o entrante ([GBY-4061]). Implementación: rewrite in place de cada fila (decode + remove + encode + upsert).

ALTER TABLE ... RENAME COLUMN

alter_rename_col ::= "ALTER" "TABLE" identifier "RENAME" "COLUMN"
                     identifier "TO" identifier ";"

ALTER TABLE users RENAME COLUMN nick TO handle;
ALTER TABLE pedidos RENAME COLUMN id TO pedido_id;  -- arrastra PK + FKs entrantes

No reescribe filas (el on-disk row es posicional). Si la columna es la PK, TableMeta.primary_key se actualiza; si está indexada, IndexMeta.column se actualiza; las FKs entrantes que referencien la columna se reescriben. Errores: [GBY-4062] destino tomado · [GBY-2002] origen no existe.

ALTER TABLE ADD CHECK (L3) / DROP CONSTRAINT (residual #2)

L3 (2026-05-27): agrega un CHECK después del CREATE TABLE. Hace full-scan de la tabla y revalida todas las filas existentes contra la expresión — si alguna viola, la sentencia se aborta sin persistir el constraint. Costo O(n) en filas, una sola vez.

Residual #2 (2026-05-27): elimina por nombre cualquier constraint nombrado (CHECK / UNIQUE / FK). PK siempre rechazada ([GBY-4072]).

📜 EBNF

alter_add_check    ::= "ALTER" "TABLE" identifier "ADD"
                       [ "CONSTRAINT" identifier ] "CHECK" "(" expr ")" ";"
alter_drop_constraint ::= "ALTER" "TABLE" identifier "DROP" "CONSTRAINT"
                          [ "IF" "EXISTS" ] identifier ";"

✅ Ejemplos

-- Agregar CHECK con re-validación O(n)
ALTER TABLE products ADD CHECK (price >= 0);
ALTER TABLE products ADD CONSTRAINT chk_stock_positivo CHECK (stock >= 0);

-- Quitar constraints nombradas
ALTER TABLE products DROP CONSTRAINT chk_stock_positivo;
ALTER TABLE orders DROP CONSTRAINT IF EXISTS fk_orders_user;
ALTER TABLE users DROP CONSTRAINT uq_users_email;

❌ Errores típicos

CREATE VIEW / DROP VIEW (bloque V)

Bloque V (2026-05-27, VERSION 13). Vistas lógicas read-only sobre el SELECT que las definió. La vista guarda únicamente el source_sql + alias de columnas; en cada query se expande dentro del FROM como una derived table. Tablas y vistas comparten namespace.

📜 EBNF

create_view ::= "CREATE" "VIEW" [ "IF" "NOT" "EXISTS" ] identifier
                [ "(" identifier ("," identifier)* ")" ]
                "AS" select_stmt ";"
drop_view   ::= "DROP" "VIEW" [ "IF" "EXISTS" ] identifier ";"

✅ Ejemplos

CREATE VIEW activos AS
  SELECT id, nombre, email FROM users WHERE active = TRUE;

SELECT * FROM activos ORDER BY nombre;

CREATE VIEW IF NOT EXISTS resumen (cliente, total)
  AS SELECT customer_id, SUM(total) FROM orders GROUP BY customer_id;

-- DML sobre vistas no se permite
-- INSERT INTO activos VALUES (...);  -- [GBY-4075] VIEWS_ARE_READONLY

-- Vistas anidadas (la fuente puede referenciar otra vista; cycle guard depth=32)
CREATE VIEW vips AS SELECT * FROM activos WHERE id IN (SELECT user_id FROM gold_members);

DROP VIEW IF EXISTS resumen;

⚠️ Reglas

• Read-only: INSERT/UPDATE/DELETE/TRUNCATE sobre una vista devuelven [GBY-4075].
• SELECT simple: la fuente debe ser un SELECT plano. Set ops (UNION/INTERSECT/EXCEPT) o VALUES como fuente devuelven [GBY-4078].
• Cycle guard: expansión limitada a MAX_VIEW_DEPTH = 32. Ciclos o cadenas muy profundas devuelven [GBY-4076] VIEW_DEPTH_EXCEEDED.
• Namespace compartido: una vista con el nombre de una tabla existente (o viceversa) devuelve [GBY-4077] NAME_ALREADY_EXISTS.
• Los column_aliases (si se declaran) deben tener la misma arity que el SELECT.

❌ Errores típicos

INSERT

🛤️ Railroad

flowchart LR
    S([▶]) --> I["INSERT (o REPLACE)"] --> INTO[INTO] --> T[/table/]
    T --> COLS["( col_list )"]
    COLS --> SRC{insert_source}
    SRC -- "VALUES" --> ROWS["(vals), (vals), ..."]
    SRC -- "SELECT" --> SEL[SELECT body]
    ROWS --> OC{ON CONFLICT?}
    SEL --> OC
    OC -- "DO NOTHING" --> RET
    OC -- "DO UPDATE SET ..." --> RET
    OC -- "(REPLACE)" --> RET
    OC --> RET{RETURNING?}
    RET -- "*  /  cols" --> SEMI[";"]
    RET --> SEMI
    SEMI --> E([■])

📜 EBNF

insert        ::= ("INSERT" | "REPLACE") "INTO" identifier "(" col_list ")"
                  insert_source
                  on_conflict_clause?
                  returning_clause?
insert_source ::= "VALUES" "(" value_list ")" ("," "(" value_list ")")*
                | "SELECT" select_body
on_conflict_clause
              ::= "ON" "CONFLICT" ( "(" identifier ")" )? "DO" conflict_action
conflict_action
              ::= "NOTHING"
                | "UPDATE" "SET" assignment ("," assignment)*
assignment    ::= identifier "=" value
returning_clause
              ::= "RETURNING" ( "*" | identifier ("," identifier)* )
col_list      ::= identifier ("," identifier)*
value_list    ::= value ("," value)*
value         ::= integer | float | string | "TRUE" | "FALSE" | "NULL"
string        ::= "'" ([^'] | "''")* "'"

REPLACE INTO ... VALUES (...) se desugara internamente a INSERT ... ON CONFLICT DO REPLACE — la cláusula ON CONFLICT explícita no se acepta si la sentencia empezó con REPLACE. El target opcional (col) solo se admite si col es PK o tiene índice UNIQUE ([GBY-4032]). En DO UPDATE SET, los valores de la derecha son literales — EXCLUDED.col no se soporta en este release.

Desde el bloque J (2026-05-25) el INSERT admite tres formas:

• Single-row: INSERT INTO t (cols) VALUES (a, b, c);
• Multi-row: INSERT INTO t (cols) VALUES (a, b), (c, d), (e, f);
• Por subquery: INSERT INTO t (cols) SELECT ... FROM ...; — el SELECT puede usar cualquier feature del SELECT (WHERE/JOIN/GROUP BY/ORDER BY). Se materializa primero, después se insertan filas en orden.

El message del response trae la cuenta: "OK (3 filas insertadas)".

✅ Ejemplos

-- Single-row (compat pre-J)
INSERT INTO users (id, name, active, score) VALUES (1, 'Ana', TRUE, 9.5);
INSERT INTO products (id, name, price) VALUES (10, 'Café o''rgánico', 4500.50);

-- Multi-row (bloque J)
INSERT INTO users (id, name, active) VALUES
  (2, 'Beto',  FALSE),
  (3, 'Carla', TRUE),
  (4, 'Dario', TRUE);

-- INSERT...SELECT (bloque J)
INSERT INTO users_backup (id, name, active)
SELECT id, name, active FROM users WHERE active = TRUE;

-- Con agregados del bloque F
INSERT INTO sales_summary (region, total)
SELECT region, SUM(monto) FROM ventas GROUP BY region;

-- UPSERT (bloque J2): ON CONFLICT DO NOTHING
INSERT INTO users (id, email) VALUES (1, 'a@x')
  ON CONFLICT DO NOTHING;

-- UPSERT: ON CONFLICT DO UPDATE (sin EXCLUDED.col por ahora — RHS literal)
INSERT INTO users (id, name) VALUES (1, 'Ana M')
  ON CONFLICT (id) DO UPDATE SET name = 'Ana M';

-- REPLACE INTO (SQLite-style): borra la fila conflictiva + inserta
REPLACE INTO users (id, name) VALUES (1, 'Anna');

-- RETURNING (bloque J2): la respuesta trae las filas afectadas
INSERT INTO orders (id, total) VALUES (10, 199.50) RETURNING id;
UPDATE products SET on_sale = TRUE WHERE stock > 0 AND price < 50 RETURNING id, price;
DELETE FROM sessions WHERE last_seen < '2024-01-01' RETURNING user_id;

❌ Errores típicos

Mantenimiento: tras el insert, todos los índices secundarios de la tabla se actualizan automáticamente.

SELECT

🛤️ Railroad

flowchart LR
    S([▶]) --> SEL[SELECT]
    SEL --> DIST{DISTINCT?}
    DIST --> COLS{select_list}
    COLS -- "*" --> FROM
    COLS -- "items" --> ITEMS[col, agg AS alias, ...] --> FROM[FROM]
    FROM --> T[/table/]
    T --> JOIN{JOINs?}
    JOIN --> WH{WHERE?}
    WH --> GB{GROUP BY?}
    GB --> HAV{HAVING?}
    HAV --> OB{ORDER BY?}
    OB --> LIM{LIMIT?}
    LIM --> OFF{OFFSET?}
    OFF --> SEMI[";"] --> E([■])

flowchart LR
    A([where_clause]) --> OR{OR}
    OR --> AND{AND}
    AND --> NOT{NOT?}
    NOT -- "NOT" --> NOT
    NOT --> PRIM{primary}
    PRIM -- "(...)" --> A
    PRIM -- "EXISTS (SELECT)" --> EX([EXISTS])
    PRIM --> ATOM[atom]
    ATOM --> COL[/column/]
    COL --> OP{operador}
    OP -- "=" --> VEQ["value, (SELECT), o ref outer"]
    OP -- "< > <= >= <> !=" --> VCMP["value"]
    OP -- "BETWEEN" --> VBT["int AND int"]
    OP -- "IS [NOT] NULL" --> VNULL([NULL])
    OP -- "[NOT] LIKE" --> VLIKE["'patron' (con % _ y \\)"]
    OP -- "[NOT] IN" --> VIN["lista o (SELECT)"]

📜 EBNF

select       ::= "SELECT" ["DISTINCT"] select_list "FROM" identifier
                  ("WHERE" where_clause)?
                  ("GROUP" "BY" identifier ("," identifier)*)?
                  ("HAVING" where_clause)?
                  ("ORDER" "BY" identifier ("ASC" | "DESC")?)?
                  ("LIMIT" integer)?
                  ("OFFSET" integer)?
select_list  ::= "*" | select_item ("," select_item)*
select_item  ::= identifier
              | agg_func "(" agg_arg ")" ["AS" identifier | identifier]
agg_func     ::= "COUNT" | "SUM" | "AVG" | "MIN" | "MAX"
agg_arg      ::= "*" | "DISTINCT" identifier | identifier
where_clause  ::= where_or
where_or      ::= where_and ( "OR" where_and )*
where_and     ::= where_not ( "AND" where_not )*
where_not     ::= "NOT" where_not
                | where_primary
where_primary ::= "(" where_or ")"
                | "EXISTS" "(" select ")"
                | "NOT" "EXISTS" "(" select ")"
                | where_atom
where_atom    ::= identifier "=" ( value | "(" select ")" | qualified_ident )
                | identifier compare_op value
                | identifier "BETWEEN" integer "AND" integer
                | identifier "IS" ["NOT"] "NULL"
                | identifier ["NOT"] "LIKE" string
                | identifier ["NOT"] "IN" "(" value_list ")"
                | identifier "IN" "(" select ")"
compare_op    ::= "<" | "<=" | ">" | ">=" | "<>" | "!="
value_list    ::= value ("," value)*
qualified_ident ::= identifier ( "." identifier )?

Precedencia (de más baja a más alta): OR < AND < NOT < paréntesis / átomo. Es la convención estándar SQL: a OR b AND c se interpreta como a OR (b AND c). Los paréntesis fuerzan agrupaciones distintas.

Lógica trivaluada (3VL) — el WHERE evalúa con la tabla de verdad de SQL estándar para NULL:

• NULL AND false → false; NULL AND true → NULL; NULL AND NULL → NULL
• NULL OR true → true; NULL OR false → NULL; NULL OR NULL → NULL
• NOT NULL → NULL
• Una fila sobrevive el filtro solo si la expresión evalúa a true; false y NULL (unknown) la descartan.

Limitación E1: EXISTS correlacionado y col = otra.col (column-ref del outer) solo se permiten como único átomo del WHERE. Combinarlos con AND/OR/NOT devuelve [GBY-4024] — soporte completo queda para un bloque posterior. Subqueries no-correlacionadas (IN (SELECT), = (SELECT), EXISTS no-correlacionado) sí se pueden combinar libremente.

🔗 FROM con JOINs (bloque A del roadmap)

from_clause ::= table_ref join_clause*
table_ref   ::= identifier [ ["AS"] identifier ]
join_clause ::= ( "," | "CROSS" "JOIN" ) table_ref
              | ( "INNER" "JOIN" | "JOIN" ) table_ref "ON" qualified_ident "=" qualified_ident
              | ( "LEFT"  ["OUTER"] "JOIN" ) table_ref "ON" qualified_ident "=" qualified_ident
              | ( "RIGHT" ["OUTER"] "JOIN" ) table_ref "ON" qualified_ident "=" qualified_ident
              | ( "FULL"  ["OUTER"] "JOIN" ) table_ref "ON" qualified_ident "=" qualified_ident
              | ( "INNER" | "LEFT" ["OUTER"] | "RIGHT" ["OUTER"] | "FULL" ["OUTER"] | ε ) "JOIN" table_ref "USING" "(" identifier ")"
              | "NATURAL" ( "INNER" | "LEFT" ["OUTER"] | "RIGHT" ["OUTER"] | "FULL" ["OUTER"] | ε ) "JOIN" table_ref

Reglas:

• INNER JOIN (o JOIN solo, equivalente ANSI) requiere ON l = r con un único equi-predicado. AND/OR y operadores no-equi (<, >, BETWEEN, etc.) en el ON siguen pendientes — workaround: filtrarlos en el WHERE post-JOIN.
• CROSS JOIN (y la comma-syntax FROM a, b) NO admite ON. Producto cartesiano completo.
• LEFT [OUTER] JOIN: preserva todas las filas del lado izquierdo. Cuando no hay match, las columnas del lado derecho aparecen como NULL.
• RIGHT [OUTER] JOIN: simétrico — preserva todas las del derecho, NULL-fill en el izquierdo.
• FULL [OUTER] JOIN: combina ambos comportamientos (toda fila de cualquier lado aparece, con NULL en el otro lado si no hay match).
• El OUTER es opcional (estándar SQL): LEFT JOIN y LEFT OUTER JOIN son sinónimos.
• JOIN ... USING (col) es sugar para JOIN ... ON l.col = r.col. La columna col aparece una sola vez en SELECT * (ANSI). En este release soporta exactamente UNA columna en la lista (multi-col en backlog).
• NATURAL JOIN deriva automáticamente un USING con la columna que ambas tablas comparten por nombre. Si las tablas comparten 0 o >1 columnas comunes en este release → [GBY-4023].
• Las tablas se pueden aliasar con [AS] alias. El alias oculta el nombre real (estándar SQL): si declarás FROM alumnos a, después tenés que usar a.nombre, no alumnos.nombre.
• En SELECT/WHERE/ORDER BY, una columna que existe en >1 tabla debe ir cualificada (tabla.col); si no, [GBY-4018].
• SELECT * en JOIN expande a TODAS las columnas de TODAS las tablas, cada una prefijada con su qualifier para evitar colisiones.

Complejidad:

• Nested-loop puro (fallback): O(N1 × N2 × … × Nk). Se usa cuando el ON no apunta contra PK ni índice del right, o cuando el JOIN es CROSS/RIGHT/FULL.
• Index-loop (optimización transparente): O(N1 × log N2) por JOIN. Se activa automáticamente cuando se cumplen las 3 condiciones: (a) el ON (o el USING/NATURAL derivado) referencia la PK o una columna indexada del right; (b) el tipo de JOIN es INNER o LEFT; (c) hay un predicate (no aplica a CROSS). El engine elige el path por sí mismo — no hace falta cambiar el SQL.

Sobre qualified_ident en el RHS del =: solo es válido dentro de una subquery correlacionada dentro de EXISTS (...). Permite expresar WHERE inner_col = outer_table.outer_col, donde outer_table es la tabla del SELECT padre. Usarlo fuera de ese contexto devuelve [GBY-4016].

Sobre EXISTS: la subquery se ejecuta una sola vez si no referencia columnas del outer; cuando sí lo hace, se re-ejecuta una vez por cada fila del outer (post-filter). Esta variante correlacionada es O(N × costo_subquery), sin optimizer; tiene sentido cuando la subquery se reduce vía PK/índice con la outer-ref.

= funciona sobre la PK o sobre cualquier columna que tenga índice secundario. BETWEEN funciona sobre la PK y sobre cualquier columna INT con índice secundario (índice OrderedInt, default automático al crear índice sobre INT; ver ADR-0017); para TEXT/FLOAT/BOOL/DATE/DATETIME indexados, BETWEEN queda en el Camino A. IN (SELECT …) acepta subqueries no-correlacionadas (la subquery no referencia columnas del outer); la subquery debe devolver exactamente una columna, se ejecuta una sola vez y el resultado se materializa como set para filtrar el outer — la columna del outer debe ser la PK o tener índice secundario, igual que =. ORDER BY funciona sobre cualquier columna del schema (no requiere índice); el sort es en memoria post-scan, así que para tablas grandes con LIMIT chico conviene tener un WHERE que reduzca el conjunto antes del sort.

✅ Ejemplos

SELECT * FROM users;
SELECT id, name FROM users LIMIT 10;
SELECT id, name FROM users LIMIT 10 OFFSET 20;

-- Por PK
SELECT * FROM users WHERE id = 1;
SELECT id, name FROM users WHERE id BETWEEN 1 AND 100;

-- Por columna indexada (requiere CREATE INDEX previo)
SELECT * FROM users WHERE name = 'Ana';
SELECT id FROM orders WHERE status = 'pending' LIMIT 50;

-- BETWEEN sobre columna INT indexada (índice OrderedInt, ADR-0017)
-- CREATE INDEX idx_users_score ON users (score);  -- score INT
SELECT id, name FROM users WHERE score BETWEEN 80 AND 100 LIMIT 25;

-- Operadores E2: <, >, <=, >=, <>, !=, LIKE, IS NULL, IN literal
SELECT id FROM users WHERE score < 50;
SELECT id FROM users WHERE score >= 80 AND score <= 100;
SELECT id FROM users WHERE name <> 'Ana';
SELECT id FROM users WHERE name LIKE 'A%';            -- empieza con 'A'
SELECT id FROM users WHERE name LIKE '_eto';          -- 4 chars, termina en 'eto'
SELECT id FROM users WHERE description NOT LIKE '%spam%';
SELECT id FROM users WHERE deleted_at IS NULL;
SELECT id FROM users WHERE id IN (1, 2, 3);
SELECT id FROM users WHERE country NOT IN ('AR', 'BR');
SELECT id FROM products WHERE code LIKE '50\%%';      -- LIKE literal '%' con escape

-- Agregaciones (bloque F): COUNT/SUM/AVG/MIN/MAX, GROUP BY, HAVING, DISTINCT
SELECT COUNT(*) FROM users;
SELECT COUNT(*) AS total FROM users WHERE active = TRUE;
SELECT COUNT(monto), SUM(monto), AVG(monto) FROM ventas;
SELECT region, SUM(monto) AS total
   FROM ventas
  GROUP BY region
  ORDER BY total DESC;
SELECT region, producto, COUNT(*) AS n
   FROM ventas
  GROUP BY region, producto
 HAVING COUNT(*) > 1;
SELECT DISTINCT category FROM products;
SELECT COUNT(DISTINCT user_id) FROM sessions;

-- Reglas ANSI estrictas:
-- - Toda columna no-agregada en el SELECT debe figurar en GROUP BY ([GBY-4027]).
-- - Las funciones agregadas solo se permiten en SELECT y HAVING, no en WHERE ([GBY-4025]).
-- - Sin GROUP BY pero con agregados → UNA fila global (incluso sobre input vacío: COUNT=0, resto=NULL).
-- - Agregados sobre SELECT con JOIN funcionan desde F2 (2026-05-30, ADR-0066 Gap 1+7).
-- - COUNT(DISTINCT col) sobre JOIN funciona desde R9 (2026-06-15, ADR-0079).

-- AND / OR / NOT + paréntesis (bloque E1)
SELECT id FROM users WHERE active = TRUE AND score BETWEEN 80 AND 100;
SELECT id FROM users WHERE city = 'BA' OR city = 'MDQ';
SELECT id FROM users WHERE NOT status = 'banned';
SELECT id FROM users WHERE (city = 'BA' OR city = 'MDQ') AND active = TRUE;
-- Precedencia estándar: AND ata más fuerte que OR.
SELECT id FROM users WHERE city = 'BA' OR city = 'MDQ' AND active = TRUE;
-- Equivale a: city = 'BA' OR (city = 'MDQ' AND active = TRUE)

-- ORDER BY (cualquier columna; ASC default; NULLs primero)
SELECT id, name FROM users ORDER BY name ASC;
SELECT id, name FROM users ORDER BY score DESC LIMIT 10;
SELECT id FROM orders WHERE status = 'pending' ORDER BY total DESC LIMIT 5 OFFSET 10;

-- IN (SELECT …) — subquery no-correlacionada
-- Requiere: outer.curso_id indexado (o ser PK) e inner.nivel indexado (o ser PK).
SELECT nombre FROM alumnos
 WHERE curso_id IN (SELECT id FROM cursos WHERE nivel = '3 Medio');

-- IN sobre PK directa (no requiere índice en el outer):
SELECT id, label FROM t WHERE id IN (SELECT ref_id FROM picks);

-- = (SELECT …) — subquery escalar (1 columna × ≤1 fila).
-- Si la subquery devuelve 0 filas o NULL, el match es vacío (semántica ANSI).
-- Si devuelve >1 fila, error [GBY-4014] — usar IN (...) en su lugar.
SELECT nombre FROM alumnos
 WHERE curso_id = (SELECT id FROM cursos WHERE nombre = 'matematica');

-- EXISTS no-correlacionada: la subquery se ejecuta UNA vez.
SELECT id FROM padre WHERE EXISTS (SELECT id FROM auditoria WHERE id = 1);

-- EXISTS correlacionada: re-ejecuta por cada fila del outer.
-- Padres que tienen al menos un hijo:
SELECT id, nombre FROM padre
 WHERE EXISTS (SELECT id FROM hijo WHERE parent_id = padre.id);

-- NOT EXISTS correlacionado: padres sin hijos.
SELECT id, nombre FROM padre
 WHERE NOT EXISTS (SELECT id FROM hijo WHERE parent_id = padre.id);

-- INNER JOIN clásico con aliases y columnas cualificadas
SELECT a.nombre, c.nombre FROM alumnos a
 INNER JOIN cursos c ON a.curso_id = c.id
 ORDER BY a.nombre ASC;

-- JOIN de 3 tablas en cadena (left-deep)
SELECT persona.nombre, ciudad.nombre, pais.nombre
  FROM persona
  JOIN ciudad ON persona.ciudad_id = ciudad.id
  JOIN pais   ON ciudad.pais_id = pais.id;

-- CROSS JOIN explícito (cartesian product)
SELECT a.v, b.w FROM a CROSS JOIN b;

-- Comma-syntax = CROSS JOIN
SELECT a.v, b.w FROM a, b;

-- Self-join vía aliases distintos
SELECT e.nombre, j.nombre FROM empleado e
  INNER JOIN empleado j ON e.jefe_id = j.id;

-- WHERE sobre columna cualificada de cualquier tabla
SELECT alumnos.nombre FROM alumnos
  JOIN cursos ON alumnos.curso_id = cursos.id
 WHERE cursos.nivel = '3M';

-- LEFT JOIN: padres sin hijos aparecen con etiqueta NULL
SELECT padre.nombre, hijo.etiqueta FROM padre
  LEFT JOIN hijo ON padre.id = hijo.parent_id
 ORDER BY padre.id ASC;

-- RIGHT JOIN: filas del derecho sin match aparecen con columnas del izq en NULL
SELECT a.v, b.w FROM a
  RIGHT JOIN b ON a.id = b.a_id;

-- FULL OUTER JOIN: combina LEFT + RIGHT en un solo paso
SELECT a.v, b.w FROM a
  FULL OUTER JOIN b ON a.id = b.a_id;

-- USING (col) — sugar para ON l.col = r.col; SELECT * dedup la columna
SELECT ciudad.nombre, pais.nombre_pais
  FROM ciudad JOIN pais USING (pais_id);

-- NATURAL JOIN — auto-detecta la columna común por nombre
SELECT ciudad.nombre, pais.nombre_pais
  FROM ciudad NATURAL JOIN pais;

❌ Errores típicos

UPDATE

🛤️ Railroad

flowchart LR
    S([▶]) --> U[UPDATE] --> T[/table/]
    T --> SET[SET] --> A[col = value]
    A --> COMMA{","}
    COMMA -- "sí" --> A
    COMMA -- "no" --> WH[WHERE]
    WH --> WC[where_clause] --> RET{RETURNING?}
    RET -- "*  /  cols" --> SEMI[";"]
    RET --> SEMI
    SEMI --> E([■])

📜 EBNF

update       ::= "UPDATE" identifier "SET" assignment ("," assignment)*
                  "WHERE" where_clause
                  returning_clause?
assignment   ::= identifier "=" value

where_clause y returning_clause son los mismos definidos en SELECT y INSERT respectivamente — ver esas secciones.

Desde el bloque E3 el WHERE de UPDATE acepta exactamente la misma gramática que SELECT: combinadores AND/OR/NOT, paréntesis, todos los operadores E1+E2 (=, <, >, <=, >=, <>/!=, LIKE, IS NULL, IN literal, BETWEEN) y subqueries (IN (SELECT), = (SELECT), EXISTS). El UPDATE se aplica a todas las filas que el WHERE matchee; el message del response trae la cuenta.

✅ Ejemplos

-- Por PK directa
UPDATE users SET name = 'Ana M' WHERE id = 1;

-- Multi-asignación
UPDATE orders
   SET status = 'paid', total = 199.50
 WHERE id = 42;

-- Por columna indexada (afecta a todas las filas matcheadas)
UPDATE users SET active = FALSE WHERE city = 'BA';

-- Por predicado compuesto (E1+E2)
UPDATE products SET on_sale = TRUE
 WHERE price < 100 AND stock > 0 AND name LIKE '%demo%';

-- Por subquery
UPDATE users SET status = 'banned'
 WHERE id IN (SELECT uid FROM blacklist);

❌ Errores típicos

Solo los índices cuya columna está en el SET se tocan; los demás no pagan costo. La resolución del WHERE en E3 hace FullScan + filtro 3VL salvo cuando el WHERE es exactamente pk = N (fast-path por PK). La optimización para = col_indexada y IN (SELECT) queda en backlog (correctitud primero). Ver src/sql.rs:exec_update.

DELETE

🛤️ Railroad

flowchart LR
    S([▶]) --> D[DELETE] --> F[FROM] --> T[/table/]
    T --> WH[WHERE] --> WC[where_clause]
    WC --> RET{RETURNING?}
    RET -- "*  /  cols" --> SEMI[";"]
    RET --> SEMI
    SEMI --> E([■])

📜 EBNF

delete  ::= "DELETE" "FROM" identifier "WHERE" where_clause
            returning_clause?

where_clause y returning_clause son los mismos definidos en SELECT e INSERT respectivamente.

Mismo where_clause que SELECT y UPDATE (bloque E3). Borra todas las filas matcheadas en orden de PK ascendente; las FK con ON DELETE CASCADE se aplican fila por fila. El message del response trae la cuenta.

✅ Ejemplos

-- Por PK
DELETE FROM users WHERE id = 5;

-- Por columna indexada (multi-fila)
DELETE FROM logs WHERE level = 'debug';

-- Por subquery
DELETE FROM sessions WHERE user_id IN (SELECT id FROM users WHERE banned = TRUE);

-- Por predicado compuesto
DELETE FROM tickets WHERE status = 'closed' AND updated_at < '2024-01-01';

❌ Errores típicos

Antes de borrar la fila, el engine la lee para evictar la entrada correspondiente de cada índice secundario. Si la tabla tiene FKs entrantes, el motor resuelve cascade/restrict iterativamente con un worklist y cycle protection (visited set sobre (tabla, pk)). Para tablas grandes con FKs entrantes, se recomienda crear un índice secundario sobre la columna FK del hijo — el engine lo usa automáticamente para que el lookup de hijos sea O(log n) en vez de full scan.

TRUNCATE

Bloque J (2026-05-25). Borra todas las filas de la tabla manteniendo el schema (columnas, índices, FKs). Implementación naive: scan de todas las PKs + delete_with_cascade por fila. Respeta las declaraciones ON DELETE CASCADE / RESTRICT de FKs entrantes — no es un O(1) hack como en Postgres/MySQL.

📜 EBNF

truncate ::= "TRUNCATE" ["TABLE"] identifier

✅ Ejemplos

TRUNCATE TABLE logs;          -- borra todo `logs`
TRUNCATE staging;             -- la palabra TABLE es opcional

❌ Errores típicos

Transacciones explícitas (BEGIN / COMMIT / ROLLBACK)

Bloque T (2026-05-25). Por defecto cada batch enviado a /exec (HTTP) o cada invocación de gabysql exec (CLI) es una transacción atómica implícita: o se commitean todas las sentencias del batch o ninguna. BEGIN/COMMIT/ROLLBACK permiten ademas abortar el batch a mitad de camino y obtener feedback explícito por sentencia.

📜 EBNF

tcl ::= "BEGIN" ["TRANSACTION" | "WORK"]
      | "START" "TRANSACTION"
      | "COMMIT" ["TRANSACTION" | "WORK"]
      | "END" ["TRANSACTION" | "WORK"]
      | "ROLLBACK" ["TRANSACTION" | "WORK"]
      | "ROLLBACK" "TO" ["SAVEPOINT"] ident                  -- M12
      | "SAVEPOINT" ident                                    -- M12
      | "RELEASE" ["SAVEPOINT"] ident                        -- M12

Sinónimos ANSI aceptados: BEGIN = START TRANSACTION. COMMIT = END. Las palabras TRANSACTION y WORK después de BEGIN/COMMIT/END/ROLLBACK son opcionales. Las palabras SAVEPOINT después de ROLLBACK TO o RELEASE son opcionales (compat con PostgreSQL).

✅ Ejemplos

BEGIN;
  INSERT INTO ledger (id, amount) VALUES (1, 100);
  INSERT INTO ledger (id, amount) VALUES (2, -100);
COMMIT;

-- Aborto a mitad de batch:
BEGIN;
  UPDATE inventory SET stock = stock - 1 WHERE sku = 'ABC';
  -- ... validación adicional falla ...
ROLLBACK;

-- M12: recuperación parcial con SAVEPOINT (ANSI SQL:2003).
BEGIN;
  INSERT INTO usuarios (id, nombre) VALUES (1, 'Ana');
  SAVEPOINT antes_de_imports;
    INSERT INTO usuarios SELECT * FROM csv_dump;  -- falla con PK dup
  ROLLBACK TO SAVEPOINT antes_de_imports;          -- vuelve al checkpoint
  -- Ana sigue intacta. Sigo con otro intento.
  INSERT INTO usuarios (id, nombre) VALUES (2, 'Beto');
  RELEASE SAVEPOINT antes_de_imports;              -- libera el slot (no revierte)
COMMIT;

🧠 Semántica SAVEPOINT (M12)

• SAVEPOINT name marca un punto-de-retorno dentro de la tx. Cero efecto sobre la tx en sí; solo bookkeeping (snapshot del cache del Pager).
• ROLLBACK TO [SAVEPOINT] name descarta cambios desde el savepoint. El savepoint sigue en la stack — hay que RELEASE para liberarlo. Cualquier savepoint declarado DESPUÉS de name queda invalidado.
• RELEASE [SAVEPOINT] name libera el slot del savepoint (y los posteriores). NO revierte cambios — los inserts entre savepoint y release permanecen.
• COMMIT y ROLLBACK full limpian toda la stack automáticamente.
• Re-SAVEPOINT con el mismo nombre marca un nuevo punto sin borrar el anterior (semántica ANSI).
• [GBY-4140] si SAVEPOINT/ROLLBACK TO/RELEASE se emite sin BEGIN activo.
• [GBY-4141] si el nombre no existe en la tx actual.

Ver ADR-0089.

⚠️ Limitaciones

• ROLLBACK descarta TODO el cache del Pager: en un batch que mezcla sentencias antes y después de BEGIN, las anteriores también se pierden. BEGIN/ROLLBACK funciona limpio cuando BEGIN es la primera sentencia del batch. Para revertir parcialmente dentro de la tx, usar SAVEPOINT (M12).
• No hay transacciones cross-request en el server HTTP ✅ entregado por M13 (2026-06-15, ADR-0090). El cliente abre sesión con POST /tx/begin, envía el session_id en cada /exec (header X-Gabysql-Session o ?session=<id>), y cierra con POST /tx/commit o POST /tx/rollback. Ver API.md.
• SAVEPOINT / ROLLBACK TO SAVEPOINT no implementados (P1). ✅ implementados desde M12 (2026-06-15, ADR-0089). Sintaxis: SAVEPOINT name, ROLLBACK TO [SAVEPOINT] name, RELEASE [SAVEPOINT] name. ANSI SQL:2003 completo.
• SET TRANSACTION ISOLATION LEVEL ... y BEGIN READ ONLY no implementados (P2). gabysql es single-writer estricto — el isolation siempre es serializable de facto; no hay nivel para configurar.

❌ Errores típicos

Funciones escalares (bloques G1 + G2 + G3)

Desde el bloque G1 (2026-05-26), el SELECT list acepta expresiones escalares además de columnas crudas y agregadas: funciones built-in (LENGTH, UPPER, CONCAT, …), CAST(x AS TYPE), CASE … END, literales, y los conditionals COALESCE/NULLIF/IFNULL/IF. Cada expresión puede recibir AS alias para nombrar la columna del ResultSet.

El bloque G2 (2026-05-26) extiende esas mismas expresiones a las superficies de filtrado y mutación:

• WHERE (incluye el WHERE de SELECT, UPDATE, DELETE): cualquier Expr que evalúe a BOOL/NULL puede ser un átomo del WHERE. Forma típica: WHERE LENGTH(nombre) > 3, WHERE UPPER(nombre) = 'ANA', WHERE COALESCE(activo, false) = true, WHERE 5 < LENGTH(nombre) (LHS literal, RHS función).
• HAVING: igual que WHERE, con la libertad ya existente de referir agregados. Ej: HAVING UPPER(grupo) = 'X'.
• UPDATE SET col = <expr> y ON CONFLICT DO UPDATE SET col = <expr>: la RHS puede ser cualquier Expr. Se evalúa contra la fila pre-update, así que SET a = b, b = a deja ambos con los valores intercambiados (las dos RHS ven el snapshot original).

El bloque G3 (2026-05-26) cierra la familia:

• Operadores aritméticos binarios +, -, *, /, % sobre INT/FLOAT con promoción implícita (INT+FLOAT → FLOAT). Overflow → [GBY-4042]; división/módulo por cero → [GBY-4043]; tipos inválidos → [GBY-4044].
• Operador || (concat) con misma precedencia que +/- (regla PostgreSQL). Cualquier tipo se reduce a TEXT; NULL propaga (ANSI estricta).
• Postfix predicates sobre Expr: LENGTH(x) IS NULL, UPPER(x) LIKE 'A%', LENGTH(x) IN (3,4,5), LENGTH(x) BETWEEN 3 AND 10 (más sus formas NOT ...).
• Funciones escalares P2/P3: TRIM/LTRIM/RTRIM, REPLACE, SPLIT_PART, CEIL/FLOOR, MOD, POWER/SQRT, DATE_ADD/DATE_SUB, DATEDIFF, EXTRACT, STRFTIME.

Pendientes residuales menores: EXCLUDED.col dentro de ON CONFLICT DO UPDATE SET y unary - prefix sobre expresión (se puede escribir 0 - LENGTH(x)).

NULL propagation: por defecto cualquier argumento NULL hace que la función devuelva NULL. Las excepciones son COALESCE/NULLIF/IFNULL/IF/Now/CurrentDate/CurrentTimestamp (la primera tiene su propio short-circuit, las últimas no tienen args).

📜 EBNF mínima

select_item    = expression [ "AS" ident | ident ] ;
expression     = arith [ cmp_op arith | postfix ] ;
postfix        = "IS" [ "NOT" ] "NULL"
               | [ "NOT" ] "LIKE" string_literal
               | [ "NOT" ] "IN" "(" value { "," value } ")"
               | [ "NOT" ] "BETWEEN" arith "AND" arith ;
arith          = arith_term { ( "+" | "-" | "||" ) arith_term } ;
arith_term     = arith_factor { ( "*" | "/" | "%" ) arith_factor } ;
arith_factor   = primary ;
primary        = literal
               | qualified_ident
               | func_call
               | "CAST" "(" expression "AS" type_name ")"
               | "CASE" [ expression ] ( "WHEN" expression "THEN" expression )+
                 [ "ELSE" expression ] "END"
               | "(" expression ")" ;
func_call      = ident "(" [ expression { "," expression } ] ")"
               | "EXTRACT" "(" extract_field "FROM" expression ")"
               | "CURRENT_DATE" | "CURRENT_TIMESTAMP" ;
extract_field  = "YEAR" | "MONTH" | "DAY" | "HOUR" | "MINUTE" | "SECOND" ;
cmp_op         = "=" | "<>" | "!=" | "<" | "<=" | ">" | ">=" ;
type_name      = "INT" | "FLOAT" | "TEXT" | "BOOL" | "DATE" | "DATETIME" | "JSON" ;

🧮 Operadores aritméticos (bloque G3)

• NULL en cualquier lado → NULL (3VL).
• Tipos incompatibles ('abc' + 1, true * 2, …) → [GBY-4044].
• Para forzar precedencia distinta, usar paréntesis.

🧰 Funciones soportadas (G1 + G3)

✅ Ejemplos

SELECT id, UPPER(name) AS n FROM users WHERE id = 1;

SELECT
  CASE WHEN score >= 90 THEN 'A'
       WHEN score >= 75 THEN 'B'
       ELSE 'C' END AS grade
FROM exams;

SELECT COALESCE(nickname, name, 'anónimo') FROM users;

SELECT CAST(price AS TEXT) || '?' FROM products; -- G3: `||` soportado
SELECT CONCAT(CAST(price AS TEXT), '?') FROM products; -- forma equivalente

-- G2: expresiones en WHERE, HAVING, UPDATE SET
SELECT id FROM users WHERE LENGTH(name) > 3;
SELECT id FROM users WHERE UPPER(name) = 'ANA';
SELECT id FROM users WHERE COALESCE(active, false) = true;
SELECT id FROM users WHERE CASE WHEN age > 18 THEN true ELSE false END = true;

SELECT g, COUNT(*) FROM t GROUP BY g HAVING UPPER(g) = 'X';

UPDATE users SET name = UPPER(name) WHERE id = 1;
UPDATE users SET descr = COALESCE(descr, 'sin descr') WHERE id = 2;
UPDATE users SET tier = CASE WHEN age >= 18 THEN 'adult' ELSE 'minor' END;
DELETE FROM users WHERE LENGTH(name) = 0;

-- G3: aritméticos, concat, postfix Expr y funciones P2/P3
SELECT precio * cantidad AS total FROM ventas;
SELECT id FROM ventas WHERE precio * 1.21 > 1000;
UPDATE ventas SET contador = contador + 1 WHERE id = 1;
SELECT nombre || ' ' || apellido AS fullname FROM users;
SELECT id FROM users WHERE LENGTH(name) IS NULL;
SELECT id FROM users WHERE UPPER(name) LIKE 'A%';
SELECT id FROM users WHERE LENGTH(name) IN (3, 4, 5);
SELECT id FROM users WHERE LENGTH(name) BETWEEN 3 AND 10;
SELECT TRIM('  hola  '), REPLACE('a-b-c', '-', '_'), SPLIT_PART('a-b-c', '-', 2);
SELECT CEIL(1.2), FLOOR(1.8), MOD(10, 3), POWER(2, 10), SQRT(16);
SELECT DATE_ADD('2026-01-01', 31), DATEDIFF('2026-12-31', '2026-01-01');
SELECT EXTRACT(YEAR FROM '2026-05-26'), STRFTIME('%Y-%m', '2026-05-26');

❌ Errores típicos

Subqueries y derived tables (bloque H)

Bloque H (2026-05-26) cierra los P0+P1 de subqueries: derived tables, NOT IN (SELECT), subquery escalar en SELECT list, y multi-predicate correlated EXISTS dentro de AND/OR/NOT.

📜 EBNF

from_source   := tabla_ident [ alias ]
               | "(" subquery ")" alias       (* derived table — alias OBLIGATORIO *)

subquery      := "SELECT" select_stmt

scalar_subq   := "(" subquery ")"             (* dentro de Expr *)

where_atom    := … (formas pre-H) …
               | columna [ "NOT" ] "IN" "(" subquery ")"   (* H *)
               | "EXISTS" "(" subquery ")"                  (* puede ir dentro de AND/OR/NOT — H *)
               | "NOT" "EXISTS" "(" subquery ")"            (* idem *)

expr_primary  := … (formas pre-H) …
               | scalar_subq                  (* H *)

✅ Ejemplos

-- Derived table: lista de cursos con cantidad de alumnos.
SELECT sub.curso_id, sub.total
FROM (SELECT curso_id, COUNT(*) AS total FROM alumnos GROUP BY curso_id) AS sub
ORDER BY sub.total DESC;

-- Derived table joineada con una tabla persistente.
SELECT cursos.nivel, sub.total
FROM cursos
INNER JOIN (SELECT curso_id, COUNT(*) AS total FROM alumnos GROUP BY curso_id) AS sub
  ON cursos.id = sub.curso_id;

-- NOT IN con 3VL ANSI estricta.
SELECT id FROM cursos
WHERE id NOT IN (SELECT curso_id FROM alumnos WHERE edad = 19);

-- Subquery escalar en SELECT list (correlated).
SELECT cursos.id,
       (SELECT COUNT(*) FROM alumnos WHERE alumnos.curso_id = cursos.id) AS cnt
FROM cursos;

-- EXISTS correlacionado combinado con otro predicado.
SELECT id FROM cursos
WHERE EXISTS (SELECT 1 FROM alumnos WHERE alumnos.curso_id = cursos.id)
  AND id = 1;

⚠️ Reglas y limitaciones

• Alias obligatorio en derived tables (ANSI estricto, [GBY-4048]). Sin él el parser rechaza.
• Sin nombres duplicados en el output de una derived table ([GBY-4049]). Usar alias internos para des-ambiguar.
• Inferencia de tipo por columna del derived: si todos los valores no-NULL son de la misma variante (INT/FLOAT/BOOL/TEXT), el schema virtual usa ese tipo; mezcla → fallback a TEXT.
• Sin índices sobre derived (always full-scan en el outer). Sin UPDATE/DELETE/INSERT sobre una derived table.
• NOT IN + NULL: si la subquery proyecta algún NULL, col NOT IN (...) devuelve NULL para todos los outer rows que no matcheen exactamente. Es la regla ANSI estricta — distinta de NOT (col IN ...) cuando hay match.
• Subquery escalar: exactamente 1 columna y a lo sumo 1 fila. 0 filas → NULL. más de 1 → [GBY-4014]. más de 1 columna → [GBY-4011].
• Correlated multi-predicado: EXISTS y col = outer.col correlacionados ahora funcionan dentro de AND/OR/NOT (el código histórico [GBY-4024] queda deprecado).

❌ Errores típicos

Set operations y VALUES (bloque I)

Operaciones de conjunto entre queries (UNION / INTERSECT / EXCEPT) con su variante ALL, alias MINUS de Oracle, y VALUES usable como query standalone o como tabla virtual dentro del FROM.

📜 EBNF

select_query    ::= select_term { ( "UNION" | "EXCEPT" | "MINUS" ) [ "ALL" ] intersect_term }*
                    [ "ORDER" "BY" ident [ "ASC" | "DESC" ] ]
                    [ "LIMIT" int ] [ "OFFSET" int ]
intersect_term  ::= select_term { "INTERSECT" [ "ALL" ] select_term }*
select_term     ::= select_stmt
                  | values_stmt
                  | "(" select_query ")"
values_stmt     ::= "VALUES" row { "," row }*
row             ::= "(" expr { "," expr }* ")"

🪜 Precedencia (ANSI)

1. INTERSECT (más alta — ata más fuerte).
2. UNION y EXCEPT / MINUS (misma precedencia, asociativos a izquierda).

A UNION B INTERSECT C se parsea como A UNION (B INTERSECT C). Para forzar otro orden, usar paréntesis.

🧮 Semántica de multisets

• UNION ALL: append (preserva duplicados). count_out = count_l + count_r.
• UNION (sin ALL): append + dedup. count_out = 1 para cada fila distinta.
• INTERSECT ALL: count_out = min(count_l, count_r) por fila distinta.
• INTERSECT: count_out = 1 para cada fila presente en ambos.
• EXCEPT ALL: count_out = max(0, count_l - count_r) por fila distinta.
• EXCEPT: count_out = 1 para cada fila presente en LHS y no en RHS.
• Dos NULL son iguales acá (comportamiento ANSI de set ops).

🪧 Compatibilidad columna a columna

• Ambos lados deben tener la misma arity ([GBY-4054] si no).
• Los tipos deben ser compatibles: INT/FLOAT promueven entre sí, cualquier otra mezcla rompe con [GBY-4055]. NULL no chequea tipo.
• Los headers del output vienen del LHS (regla ANSI: el primer SELECT impone los nombres).

✅ Ejemplos

-- Unión simple con dedup
SELECT id FROM a UNION SELECT id FROM b ORDER BY id ASC;

-- Unión preservando duplicados
SELECT nombre FROM clientes_2024 UNION ALL SELECT nombre FROM clientes_2025;

-- Intersección + ORDER BY al nivel del resultado
(SELECT id FROM activos) INTERSECT (SELECT id FROM premium) ORDER BY id DESC LIMIT 10;

-- Diferencia con alias MINUS
SELECT id FROM a MINUS SELECT id FROM b;

-- VALUES standalone (devuelve ResultSet con headers column1, column2, ...)
VALUES (1, 'a'), (2, 'b'), (3, 'c');

-- VALUES como tabla virtual en FROM
SELECT id, name FROM (VALUES (1, 'a'), (2, 'b')) AS t(id, name) ORDER BY id ASC;

-- JOIN entre persistente y VALUES virtual
SELECT a.id, t.tag
FROM a INNER JOIN (VALUES (1, 'uno'), (3, 'tres')) AS t(id, tag) ON a.id = t.id;

-- Precedencia: INTERSECT ata más fuerte que UNION
-- ( == A UNION (B INTERSECT C) )
VALUES (1), (2) UNION VALUES (3), (4) INTERSECT VALUES (4), (5);
-- → 1, 2, 4

❌ Errores típicos

⚠️ No soportado todavía

• ORDER BY 1 posicional sobre el output de un set op (usar nombre).
• Set ops dentro de UPDATE / DELETE (no es ANSI estándar).
• ALL / ANY / SOME sobre subqueries (backlog H-P2).

CTEs no-recursivas (WITH, bloque W1)

Common Table Expressions: dar nombre a una subquery para reusarla en FROM / JOIN / subqueries (IN, EXISTS, scalar) y en cualquiera de las ramas de un set op. Múltiples CTEs encadenables — b puede referenciar a declarada antes.

📜 EBNF

with_query    ::= "WITH" cte_def { "," cte_def }* select_query
cte_def       ::= ident "AS" "(" select_stmt ")"

🧠 Semántica

• Shadowing ANSI: el nombre de la CTE prevalece sobre cualquier tabla real homónima del catálogo.
• Orden de declaración estricto: WITH a AS (...), b AS (SELECT FROM a) está OK; al revés (b antes que a) rompe con “tabla no existe” al parsear b.
• Visible desde set ops: WITH x AS (...) SELECT FROM x UNION SELECT FROM x resuelve x en ambas ramas.
• Re-ejecución: si la CTE se referencia N veces, el body se materializa N veces (deuda explícita — futura optimización por memoización, ver ADR-0026 §1).

✅ Ejemplos

-- CTE simple
WITH seniors AS (SELECT id, nombre FROM empleados WHERE salario >= 100)
SELECT nombre FROM seniors ORDER BY nombre;

-- Encadenamiento
WITH ventas_2025 AS (SELECT * FROM ventas WHERE anio = 2025),
     top_clientes AS (SELECT cliente_id, SUM(monto) AS total
                      FROM ventas_2025 GROUP BY cliente_id)
SELECT cliente_id FROM top_clientes WHERE total >= 10000;

-- CTE en JOIN
WITH big AS (SELECT uid FROM orders WHERE total >= 100)
SELECT u.name FROM users u INNER JOIN big ON u.id = big.uid;

-- CTE en subquery
WITH high AS (SELECT id FROM t WHERE v >= 20)
SELECT id FROM t WHERE id IN (SELECT id FROM high);

-- CTE visible desde ambas ramas de un UNION
WITH x AS (SELECT id FROM t WHERE id = 1)
SELECT id FROM x UNION SELECT id FROM t WHERE id = 2 ORDER BY id;

❌ Errores típicos

⚠️ No soportado todavía

• Column aliases en la cabecera (WITH cte(c1, c2) AS (...)) — workaround inline disponible.
• Window functions (ROW_NUMBER, RANK, SUM() OVER (...)) — bloque W3.
• CTEs sobre UPDATE / DELETE — sólo SELECT por ahora.

CTEs recursivas (WITH RECURSIVE, bloque W2)

Common Table Expressions recursivas: el body se materializa por fixpoint base+step. Soporta exactamente UNA CTE recursive por statement, con body canónico anchor UNION [ALL] step. Casos típicos: generadores de números, traversal de jerarquías (descendientes / ancestros), expansión transitiva.

📜 EBNF

recursive_query  ::= "WITH" "RECURSIVE" ident "AS" "(" recursive_body ")" select_query
recursive_body   ::= select_stmt "UNION" [ "ALL" ] select_stmt

El primer SELECT es el anchor (caso base — no puede referenciar la CTE). El segundo es el step (caso recursivo — debe referenciar la CTE por nombre en algún FROM).

🧠 Semántica (delta semantics, ANSI)

• Iteración 0: accum = anchor.exec(); delta = accum.
• Iteración N≥1: el step se ejecuta con la CTE bindeada SOLO a delta (no al accum cumulativo); el resultado se filtra por dedup contra accum cuando es UNION (no ALL); accum se extiende con las filas nuevas; delta = filas nuevas.
• Terminación: cuando delta = ∅.
• Guards de runaway: MAX_RECURSIVE_ITERATIONS = 1000 y MAX_RECURSIVE_ROWS = 100_000. Recursión bien terminada no se acerca a estos límites.

✅ Ejemplos

-- Generador 1..100
WITH RECURSIVE nums AS (
    SELECT 1 AS n
    UNION ALL
    SELECT n + 1 FROM nums WHERE n < 100
)
SELECT n FROM nums;

-- Descendientes de un nodo en un árbol (id, parent)
WITH RECURSIVE descendants AS (
    SELECT id FROM tree WHERE id = :root_id
    UNION ALL
    SELECT t.id FROM tree t INNER JOIN descendants d ON t.parent = d.id
)
SELECT id FROM descendants ORDER BY id;

-- UNION (no ALL) — termina natural por dedup
WITH RECURSIVE r AS (
    SELECT 1 AS n
    UNION
    SELECT 1 FROM r  -- step produce SIEMPRE 1; dedup ⇒ delta vacío ⇒ stop
)
SELECT n FROM r;

-- JOIN entre la CTE recursive y una tabla persistente
WITH RECURSIVE nums AS (
    SELECT 1 AS n UNION ALL SELECT n + 1 FROM nums WHERE n < 5
)
SELECT l.lab FROM nums INNER JOIN labels l ON l.n = nums.n ORDER BY l.lab;

❌ Errores típicos

⚠️ No soportado todavía

• Múltiples CTEs recursive en el mismo WITH — usar un solo WITH RECURSIVE o anidar.
• Cumulative semantics (step lee el accum, no solo el delta) — diferido; mayoría de casos prácticos funcionan con delta.
• Window functions sobre el resultado del fixpoint — bloque W3.

Window functions (bloque W3)

Funciones que computan un valor por fila usando OTRAS filas de la misma partition — clásicas: enumerar dentro de un grupo (ROW_NUMBER), rankear (RANK/DENSE_RANK), totales corridos (SUM(x) OVER (ORDER BY d)), mirar fila anterior/siguiente (LAG/LEAD), partir en buckets (NTILE), valores extremos de la partition (FIRST_VALUE/LAST_VALUE).

📜 EBNF

window_call    ::= window_func "(" [ expr {"," expr}* ] ")"
                   "OVER" "(" [ "PARTITION" "BY" expr {"," expr}* ]
                              [ "ORDER" "BY" expr [ "ASC" | "DESC" ]
                                              {"," expr [ "ASC" | "DESC" ]}* ] ")"
window_func    ::= "ROW_NUMBER" | "RANK" | "DENSE_RANK" | "NTILE"
                 | "COUNT" | "SUM" | "AVG" | "MIN" | "MAX"
                 | "LAG" | "LEAD" | "FIRST_VALUE" | "LAST_VALUE"

🧠 Defaults de frame (sin spec explícita — ROWS BETWEEN ... no soportado)

✅ Ejemplos

-- Numerar dentro de cada región por salario descendente
SELECT id, region, ROW_NUMBER() OVER (PARTITION BY region ORDER BY salary DESC) AS rk
FROM employees;

-- Rankear con ties (RANK salta, DENSE_RANK no)
SELECT id, score,
       RANK() OVER (ORDER BY score DESC) AS r,
       DENSE_RANK() OVER (ORDER BY score DESC) AS dr
FROM students;

-- Total corrido por fecha
SELECT date, amount, SUM(amount) OVER (ORDER BY date) AS running_total
FROM tx;

-- Total por región (full partition, sin ORDER BY)
SELECT id, region, SUM(amount) OVER (PARTITION BY region) AS region_total
FROM sales;

-- Mirar fila anterior con default
SELECT date, price, LAG(price, 1, 0) OVER (ORDER BY date) AS prev_or_zero
FROM ticks;

-- Partir en quartiles
SELECT id, score, NTILE(4) OVER (ORDER BY score DESC) AS quartile
FROM students;

❌ Errores típicos

⚠️ No soportado todavía

• Frame specs explícitas: ROWS BETWEEN N PRECEDING AND M FOLLOWING, RANGE BETWEEN ..., GROUPS BETWEEN .... Los defaults aplican; no se pueden customizar.
• WINDOW w AS (...) named windows: reusar una spec entre múltiples columnas.
• PERCENT_RANK, CUME_DIST: funciones de distribución.
• Mezcla con GROUP BY: usar derived table como workaround.
• LAST_VALUE con semántica ANSI (CURRENT ROW default con ORDER BY): llegará cuando se implementen frames explícitas.

Triggers (bloques X1 + X2)

CREATE TRIGGER ... {BEFORE|AFTER} ... FOR EACH ROW <body>: ejecuta un body DML antes o después de cada fila afectada por un INSERT/UPDATE/DELETE. Body puede ser una sola sentencia (X1) o un bloque BEGIN ... END con múltiples sentencias (X2). Persistido en el catálogo (bump VERSION 13 → 14 en X1; X2 sin bump).

📜 EBNF

create_trigger ::= "CREATE" "TRIGGER" ident ("BEFORE"|"AFTER") ("INSERT"|"UPDATE"|"DELETE")
                   "ON" ident "FOR" "EACH" "ROW" trigger_body
trigger_body   ::= dml_stmt
                 | "BEGIN" dml_stmt {";" dml_stmt}* [";"] "END"
drop_trigger   ::= "DROP" "TRIGGER" ["IF" "EXISTS"] ident
dml_stmt       ::= insert_stmt | update_stmt | delete_stmt | replace_stmt

🧠 Referencias NEW.col / OLD.col

Las referencias se substituyen a nivel de TOKEN antes de re-parsear el body — funciona en cualquier contexto (INSERT VALUES, UPDATE SET, WHERE, etc.).

✅ Ejemplos

-- Auditoría simple
CREATE TABLE audit (id INT PRIMARY KEY, action TEXT, who INT);
CREATE TRIGGER audit_user_insert AFTER INSERT ON users
    FOR EACH ROW INSERT INTO audit (id, action, who)
                 VALUES (NEW.id, 'inserted', NEW.id);

-- Log de cambios con NEW y OLD
CREATE TRIGGER log_price_change AFTER UPDATE ON products
    FOR EACH ROW INSERT INTO price_log (id, old_price, new_price)
                 VALUES (NEW.id, OLD.price, NEW.price);

-- Tombstone table
CREATE TRIGGER tomb AFTER DELETE ON items
    FOR EACH ROW INSERT INTO removed (id, name) VALUES (OLD.id, OLD.name);

-- Borrado
DROP TRIGGER IF EXISTS audit_user_insert;

❌ Errores típicos

🧠 BEFORE vs AFTER

🧠 Body BEGIN ... END (X2)

Las sentencias dentro del block se separan con ; y se ejecutan en orden. Si alguna falla, las restantes NO se ejecutan y el error se propaga al DML principal — toda la transacción rollback. BEGIN ... END puede anidarse aunque no agrega expresividad en X2 (no hay scope ni control de flujo).

⚠️ No soportado (estado al 2026-06-15)

Entregado posteriormente (notar que esta sección estaba escrita para X1/X2):

• Control de flujo en el body (IF/LOOP/WHILE, variables DECLARE) ✅ entregado por X4 → X4f (PL/pgSQL completo, 2026-05-29). IF/CASE/WHILE/FOR/LOOP/DECLARE/SET/RAISE/EXCEPTION/RETURN. Ver secciones X4b–X4f y X5–X6 abajo.
• RAISE EXCEPTION / RAISE NOTICE ✅ entregado por X4c (2026-05-28). Sintaxis RAISE [EXCEPTION|NOTICE] 'msg'.
• Lenguaje procedural (variables, IF/THEN, LOOP, EXCEPTION) ✅ entregado por X4 → X6.

Sigue pendiente:

• NEW mutable en BEFORE (NEW.updated_at := NOW() desde dentro del body del trigger). Lo que pasó el caller persiste tal cual.
• FOR EACH STATEMENT (vs FOR EACH ROW) — fuera de scope.
• INSTEAD OF triggers (sobre vistas) — fuera de scope.
• OLD en UPSERT que terminó en UPDATE — el path INSERT ... ON CONFLICT DO UPDATE que dispara AFTER UPDATE fire con OLD=None.

Stored procedures (bloque X3)

CREATE PROCEDURE name(p1 TYPE, ...) AS <body> + CALL name(args) + DROP PROCEDURE: encapsular side effects parametrizados. Body es DML simple o BEGIN ... END multi-stmt. CALL es un statement standalone — no se puede usar como expresión (funciones invocables en SELECT llegan en X3b). Persistido en catálogo (bump VERSION 14 → 15).

📜 EBNF

create_proc  ::= "CREATE" "PROCEDURE" ident "(" [param {"," param}*] ")"
                 "AS" proc_body
param        ::= ident type_name
proc_body    ::= dml_stmt
               | "BEGIN" dml_stmt {";" dml_stmt}* [";"] "END"
drop_proc    ::= "DROP" "PROCEDURE" ["IF" "EXISTS"] ident
call_stmt    ::= "CALL" ident "(" [expr {"," expr}*] ")"

✅ Ejemplos

-- Procedure simple
CREATE PROCEDURE log_msg(p_id INT, p_msg TEXT) AS
    INSERT INTO log (id, msg) VALUES (p_id, p_msg);

CALL log_msg(42, 'hello');

-- Body multi-statement
CREATE PROCEDURE log_both(p_id INT) AS BEGIN
    INSERT INTO log_a (id) VALUES (p_id);
    INSERT INTO log_b (id) VALUES (p_id);
END;

CALL log_both(99);

-- Args como expresiones
CALL log_msg(10 + 5, UPPER('abc'));

-- Cleanup
DROP PROCEDURE IF EXISTS log_msg;

⚠️ Limitación conocida — choque param/columna

Si una columna tiene el mismo nombre que un parámetro, el ident de la columna también se substituye (token-level) y la query rompe. Workaround: prefijar param names (p_id, arg_name) — convención estándar PG.

-- ❌ choque: `id` aparece como param Y como columna
CREATE PROCEDURE add_log(id INT) AS INSERT INTO log (id) VALUES (id);

-- ✅
CREATE PROCEDURE add_log(p_id INT) AS INSERT INTO log (id) VALUES (p_id);

❌ Errores típicos

⚠️ No soportado todavía

• CREATE FUNCTION ... RETURNS scalar invocable desde SELECT/WHERE — X3b.
• Type checking estricto en CALL (hoy el motor confía en que el DML downstream rebote).
• Args OUT/INOUT, DECLARE variables locales, IF/LOOP/WHILE — área de PL/pgSQL, X4+.
• Recursion guard para procedures.
• CREATE PROCEDURE ... RETURNS TABLE (tabla de salida).

User-defined functions (bloque X3b)

CREATE FUNCTION name(p1 TYPE, ...) RETURNS TYPE AS <expr> + DROP FUNCTION: funciones escalares invocables desde cualquier expresión (SELECT, WHERE, HAVING, ORDER BY, body de otra function…). Body es UNA expresión (no SELECT — desviación práctica de ANSI). Persistido en catálogo (bump VERSION 15 → 16).

📜 EBNF

create_function ::= "CREATE" "FUNCTION" ident "(" [param {"," param}*] ")"
                    "RETURNS" type_name "AS" expr
drop_function   ::= "DROP" "FUNCTION" ["IF" "EXISTS"] ident

✅ Ejemplos

-- Doble
CREATE FUNCTION dbl(p_x INT) RETURNS INT AS p_x * 2;
SELECT id, dbl(v) AS doubled FROM t;

-- Saludar con CONCAT
CREATE FUNCTION greet(p_name TEXT) RETURNS TEXT AS CONCAT('Hi ', p_name);
SELECT greet(name) FROM users;

-- Predicado en WHERE
CREATE FUNCTION big(p_x INT) RETURNS BOOL AS p_x >= 100;
SELECT * FROM t WHERE big(v);

-- Composición
CREATE FUNCTION quad(p_x INT) RETURNS INT AS dbl(dbl(p_x));
SELECT quad(v) FROM t;  -- = dbl(dbl(v)) = v * 4

-- Cleanup
DROP FUNCTION IF EXISTS dbl;

⚠️ Restricciones

• Body es UNA Expr, no un SELECT. Sin acceso a tablas dentro del body (workaround: pre-procesar con un trigger o usar CTE/view externos).
• NEW/OLD no aplican (esos son scope de triggers).
• CHECK constraints rechazan user functions para preservar pureza.
• Mismo workaround de procedures para choque param/columna: prefijar (p_x).

❌ Errores típicos

⚠️ No soportado todavía

• Body como SELECT (RETURNS ... AS $$ SELECT ... $$ LANGUAGE SQL) — requiere SELECT sin FROM.
• RETURNS TABLE (table-valued functions).
• Type checking estricto en args/return.
• IMMUTABLE/STABLE/VOLATILE hints.
• PL/pgSQL body (variables, IF, LOOP).

Control de flujo IF (bloque X4)

IF expr THEN <stmts> [ELSIF expr THEN <stmts>]* [ELSE <stmts>] END IF: control de flujo como statement top-level. Funciona en cualquier contexto donde quepa un statement — batches SQL planos, bodies de trigger / procedure, branches de otro IF (anidado).

📜 EBNF

if_stmt    ::= "IF" expr "THEN" stmt_list
               { "ELSIF" expr "THEN" stmt_list }*
               [ "ELSE" stmt_list ]
               "END" "IF"
stmt_list  ::= stmt {";" stmt}* [";"]

🧠 Semántica

• La condición debe evaluar a BOOL o NULL (NULL se trata como FALSE — 3VL).
• Otros tipos → [GBY-4105].
• Evalúa cada condición en orden; primer TRUE ejecuta su branch y sale (no evalúa las restantes).
• Si ninguna fue TRUE y hay ELSE, ejecuta ELSE. Sino, no-op.

✅ Ejemplos

-- Top-level
IF (SELECT COUNT(*) FROM orders) > 1000 THEN
    INSERT INTO alerts (msg) VALUES ('alta carga');
END IF;

-- Chain ELSIF
IF total >= 1000 THEN INSERT INTO platinum VALUES (id);
ELSIF total >= 100 THEN INSERT INTO gold VALUES (id);
ELSIF total >= 10  THEN INSERT INTO silver VALUES (id);
ELSE INSERT INTO bronze VALUES (id);
END IF;

-- Dentro de trigger
CREATE TRIGGER classify AFTER INSERT ON t FOR EACH ROW BEGIN
    IF NEW.v >= 100 THEN INSERT INTO big VALUES (NEW.id);
    ELSE INSERT INTO small VALUES (NEW.id);
    END IF;
END;

-- Dentro de procedure
CREATE PROCEDURE classify(p_id INT, p_v INT) AS BEGIN
    IF p_v >= 100 THEN INSERT INTO log (id, label) VALUES (p_id, 'big');
    ELSE INSERT INTO log (id, label) VALUES (p_id, 'small');
    END IF;
END;

-- Anidado
IF cond1 THEN
    IF cond2 THEN INSERT INTO log VALUES (1); END IF;
END IF;

❌ Errores típicos

⚠️ No soportado todavía

• Variables locales (DECLARE x INT [DEFAULT expr]) — X4b.
• Asignación (SET x = expr / x := expr) — X4b.
• WHILE / LOOP / FOR / EXIT [WHEN] / CONTINUE — X4b.
• RAISE EXCEPTION / RAISE NOTICE — X4c.
• EXCEPTION WHEN ... THEN handlers — X4c.
• CASE statement (vs CASE expression que ya existe en SELECT list) — futuro.

Variables + WHILE LOOP (bloque X4b)

DECLARE + SET + WHILE LOOP + EXIT [WHEN]: variables locales y loops. Top-level y dentro de bodies de trigger/procedure. Scope plano (limitación X4b — no nested scope por BEGIN..END).

📜 EBNF

declare_stmt  ::= "DECLARE" ident type_name [ "DEFAULT" expr ]
set_stmt      ::= "SET" ident "=" expr
while_stmt    ::= "WHILE" expr "LOOP" stmt_list "END" "LOOP"
exit_stmt     ::= "EXIT" [ "WHEN" expr ]

🧠 Semántica

• DECLARE agrega variable al scope (init con DEFAULT expr o NULL). Redeclarar → [GBY-4108].
• SET actualiza variable existente (RHS = Expr eval’d contra scope actual). Variable no declarada → [GBY-4107].
• WHILE itera mientras cond TRUE. Guard MAX_LOOP_ITERATIONS = 100_000 → [GBY-4109].
• EXIT sin WHEN: sale incondicional del loop innermost.
• EXIT WHEN cond: sale solo si cond TRUE.

⚠️ Limitación importante: variables NO en INSERT VALUES

DECLARE n INT DEFAULT 5;
-- ❌ falla — el parser de VALUES exige Value literal, no Expr
INSERT INTO t VALUES (n);

Workarounds:

-- ✅ INSERT SELECT acepta Expr
INSERT INTO t SELECT n FROM (VALUES (1)) AS dummy;

-- ✅ UPDATE SET acepta Expr (vars OK en RHS)
UPDATE t SET col = n WHERE id = 1;

-- ✅ En procedure: usar params (se substituyen a literal en CALL)
CREATE PROCEDURE foo(p_n INT) AS INSERT INTO t VALUES (p_n);

✅ Ejemplos

-- Counter loop
DECLARE i INT DEFAULT 0;
WHILE i < 10 LOOP
    SET i = i + 1;
END LOOP;

-- Loop con EXIT WHEN
DECLARE counter INT DEFAULT 0;
WHILE TRUE LOOP
    SET counter = counter + 1;
    EXIT WHEN counter >= 42;
END LOOP;

-- Loop con IF + EXIT incondicional
DECLARE found INT DEFAULT 0;
WHILE found = 0 LOOP
    SET found = (SELECT COUNT(*) FROM t WHERE flag = 1);
    IF found > 0 THEN EXIT; END IF;
    -- ... resto del trabajo
END LOOP;

-- En procedure body
CREATE PROCEDURE process(p_max INT) AS BEGIN
    DECLARE i INT DEFAULT 0;
    WHILE i < p_max LOOP
        UPDATE counters SET v = v + 1 WHERE id = 1;
        SET i = i + 1;
    END LOOP;
END;

❌ Errores típicos

⚠️ No soportado al cierre de X4b (estado de la sub-sección X4b — desde 2026-06-15 muchos están entregados, ver bloques X4c/X4d/X4e/X4f/X5/X6 abajo)

Entregado posteriormente:

• FOR i IN a..b LOOP ✅ X4c (2026-05-28).
• FOR row IN SELECT ... LOOP ✅ X6 (2026-05-29, ADR-0042).
• RAISE EXCEPTION ✅ X4c (2026-05-28).
• EXCEPTION WHEN handlers ✅ X4d (2026-05-28).
• LOOP ... END LOOP standalone ✅ X4d (2026-05-28).

Sigue pendiente:

• Nested scope real por BEGIN..END block — diferido.
• Type checking estricto en DECLARE/SET — diferido (parser acepta sin validar el tipo declarado).
• Variables en INSERT VALUES — requiere lift de la restricción de VALUES.

RAISE + FOR LOOP (bloque X4c)

RAISE [EXCEPTION|NOTICE] 'msg': aborto explícito con mensaje (EXCEPTION) o info logging (NOTICE). FOR ident IN start TO end LOOP <body> END LOOP: range loop con auto-declaración de la variable de iteración.

📜 EBNF

raise_stmt ::= "RAISE" [ "EXCEPTION" | "NOTICE" ] string_literal
for_stmt   ::= "FOR" ident "IN" expr "TO" expr "LOOP" stmt_list "END" "LOOP"

🧠 Semántica

RAISE:

• Si no se especifica level, default es EXCEPTION.
• EXCEPTION → [GBY-4111] con el mensaje del user. Propaga normalmente; el wrap caller hace rollback de la transacción.
• NOTICE → ResultSet vacío con message = "NOTICE: <msg>". No interrumpe el flujo.
• En X4c no había EXCEPTION WHEN ... handlers — entregados en X4d (2026-05-28, ADR-0036).

FOR:

• i se auto-declara en var_scope al inicio (shadowing si ya existe; se restaura al terminar).
• Iteración inclusiva: i = start, start+1, ..., end.
• Si start > end, no itera (sin error).
• STEP fijo en 1, ascendente.
• start/end deben ser INT (→ [GBY-4113] si no).
• EXIT [WHEN] funciona dentro de FOR (mismo sentinel que WHILE).
• Guard MAX_LOOP_ITERATIONS = 100_000 compartido.

Sintaxis non-PG: PG usa FOR i IN 1..10 LOOP. gabysql usa start TO end para evitar ambigüedad con qualifier ident (tabla.col).

✅ Ejemplos

-- RAISE en validación
CREATE TRIGGER validate AFTER INSERT ON orders FOR EACH ROW BEGIN
    IF NEW.amount < 0 THEN
        RAISE EXCEPTION 'negative amount not allowed';
    END IF;
END;

-- NOTICE para logging
RAISE NOTICE 'job started';

-- FOR loop básico
FOR i IN 1 TO 10 LOOP
    INSERT INTO log SELECT i FROM (VALUES (1)) AS x;
END LOOP;

-- FOR + EXIT WHEN
FOR i IN 1 TO 100 LOOP
    EXIT WHEN i = 5;
END LOOP;

-- FOR en procedure
CREATE PROCEDURE process_n(p_max INT) AS BEGIN
    DECLARE total INT DEFAULT 0;
    FOR i IN 1 TO p_max LOOP
        SET total = total + i;
    END LOOP;
END;

❌ Errores típicos

⚠️ No soportado todavía

• EXCEPTION WHEN ... THEN handlers (BEGIN ... EXCEPTION ... END) — X4d.
• FOR row IN SELECT ... LOOP (resultset iteration) — X4d.
• LOOP ... END LOOP standalone (sin WHILE/FOR) — X4d.
• RETURN expr dentro de functions — X4d.
• STEP n y REVERSE (descendente) en FOR — futuro.
• Formato % en RAISE (RAISE EXCEPTION 'value % invalid', x) — futuro.
• RAISE WARNING / INFO — futuro.

EXCEPTION handlers + LOOP standalone (bloque X4d)

BEGIN <body> [EXCEPTION WHEN OTHERS THEN <handler>] END: try/catch con catch-all (X4d sólo soporta WHEN OTHERS). LOOP <body> END LOOP standalone: infinite hasta EXIT o MAX_LOOP_ITERATIONS.

📜 EBNF

block_stmt ::= "BEGIN" stmt_list [ "EXCEPTION" "WHEN" "OTHERS" "THEN" stmt_list ] "END"
loop_stmt  ::= "LOOP" stmt_list "END" "LOOP"

🧠 Semántica

BEGIN..END:

• Lookahead distingue BEGIN [TRANSACTION]; (transaction) de BEGIN <stmt>... (block).
• Body ejecuta en orden. Si alguno rebota:
  • EXIT sentinel → re-propagar (debe alcanzar el LOOP outer).
  • Sin handler → propagar error.
  • Con handler → ejecutar handler en su lugar, retornar OK con "EXCEPTION caught: <orig>".
• WHEN OTHERS es catch-all — atrapa cualquier error (RAISE, runtime, PK dup, etc.).
• Re-raise condicional posible dentro del handler: RAISE EXCEPTION 'new msg'.

LOOP standalone:

• Infinite hasta EXIT (sentinel) o hit MAX_LOOP_ITERATIONS = 100_000.
• Sin EXIT → [GBY-4109].

✅ Ejemplos

-- Try/catch básico
BEGIN
    INSERT INTO t (id) VALUES (1);
EXCEPTION WHEN OTHERS THEN
    INSERT INTO log VALUES (now(), 'failed');
END;

-- LOOP standalone
DECLARE i INT DEFAULT 0;
LOOP
    SET i = i + 1;
    EXIT WHEN i = 100;
END LOOP;

-- EXCEPTION en trigger body (no aborta el INSERT principal)
CREATE TRIGGER safe AFTER INSERT ON orders FOR EACH ROW BEGIN
    BEGIN
        UPDATE counters SET n = n + 1 WHERE id = NEW.id;
    EXCEPTION WHEN OTHERS THEN
        INSERT INTO err_log VALUES (NEW.id);
    END;
END;

-- EXCEPTION dentro de WHILE (handler corre cada iteración)
DECLARE i INT DEFAULT 0;
DECLARE caught INT DEFAULT 0;
WHILE i < 5 LOOP
    SET i = i + 1;
    BEGIN
        RAISE EXCEPTION 'iter %', i;
    EXCEPTION WHEN OTHERS THEN
        SET caught = caught + 1;
    END;
END LOOP;
-- caught == 5

-- LOOP con condición compleja vía EXIT WHEN
DECLARE done INT DEFAULT 0;
LOOP
    UPDATE jobs SET status = 'processing' WHERE id IN
        (SELECT id FROM jobs WHERE status = 'pending' LIMIT 10);
    SET done = (SELECT COUNT(*) FROM jobs WHERE status = 'pending');
    EXIT WHEN done = 0;
END LOOP;

❌ Errores típicos

⚠️ No soportado todavía

• EXCEPTION WHEN <code> filtros específicos (WHEN no_data_found, etc.) — X4e.
• FOR row IN SELECT ... LOOP — X4e.
• RETURN expr en functions — X4e.
• CASE statement — diferido.
• Múltiples WHEN branches en EXCEPTION.

CASE statement + EXCEPTION filtrada (bloque X4e)

CASE WHEN cond THEN <stmts> [WHEN cond THEN <stmts>]* [ELSE <stmts>] END CASE — statement-level (vs CASE expression que vive en SELECT list). EXCEPTION WHEN <code> THEN <handler> — filtros por código numérico en BEGIN..END handlers, múltiples WHEN encadenados con OTHERS fallback opcional.

📜 EBNF

case_stmt   ::= "CASE" "WHEN" expr "THEN" stmt_list
                { "WHEN" expr "THEN" stmt_list }*
                [ "ELSE" stmt_list ]
                "END" "CASE"
exc_handler ::= "WHEN" ( integer | "OTHERS" ) "THEN" stmt_list

🧠 Semántica

CASE statement:

• Searched form solo (no operando inicial — usar CASE WHEN x = v THEN ...).
• Semánticamente idéntico a IF/ELSIF/ELSE/END IF.
• Primer WHEN cuya cond evalúe TRUE corre; resto se ignora.
• ELSE corre si ninguna WHEN matchea. Sin ELSE + sin match → no-op.

EXCEPTION WHEN <code>:

• Filtro = literal entero (4111, 3001, etc.) — el código [GBY-NNNN] sin prefijo.
• Múltiples WHEN encadenados → primer filter que matchee el código del error gana.
• OTHERS matchea cualquier error no atrapado por filtros previos. Va al final.
• Sin handler match → re-propaga el error.

✅ Ejemplos

-- CASE statement con clasificación
DECLARE amt INT DEFAULT 500;
CASE
    WHEN amt >= 1000 THEN INSERT INTO platinum VALUES (id);
    WHEN amt >= 100  THEN INSERT INTO gold VALUES (id);
    WHEN amt >= 10   THEN INSERT INTO silver VALUES (id);
    ELSE INSERT INTO bronze VALUES (id);
END CASE;

-- EXCEPTION filtrada por código
BEGIN
    INSERT INTO orders (id, amount) VALUES (1, -5);
EXCEPTION
    WHEN 3008 THEN                                   -- CHECK violation
        INSERT INTO bad_orders (id) VALUES (1);
    WHEN 3001 THEN                                   -- duplicate PK
        UPDATE orders SET amount = -5 WHERE id = 1;
    WHEN OTHERS THEN
        INSERT INTO err_log (msg) VALUES ('unknown');
END;

-- CASE dentro de procedure
CREATE PROCEDURE tier(p_id INT, p_amt INT) AS BEGIN
    CASE
        WHEN p_amt >= 100 THEN INSERT INTO tier_log VALUES (p_id, 'gold');
        WHEN p_amt >= 50  THEN INSERT INTO tier_log VALUES (p_id, 'silver');
        ELSE INSERT INTO tier_log VALUES (p_id, 'bronze');
    END CASE;
END;

❌ Errores típicos

⚠️ No soportado todavía

• EXCEPTION WHEN <name> filtros simbólicos (WHEN no_data_found, WHEN unique_violation) — X4f.
• CASE expr WHEN val THEN ... simple form como statement — diferido.
• Múltiples códigos en un mismo WHEN (WHEN 3001 OR 3002 THEN) — diferido.

RETURN en function bodies (bloque X4f)

CREATE FUNCTION ... AS BEGIN ... RETURN expr; END — function bodies multi-statement con RETURN expr como mecanismo de salida. La forma single-expression body de X3b (AS x + 1) sigue funcionando.

📜 EBNF

create_function ::= "CREATE" "FUNCTION" ident "(" [ param { "," param }* ] ")"
                    "RETURNS" type "AS" function_body
function_body   ::= expr
                  | "BEGIN" stmt_list "END"
return_stmt     ::= "RETURN" expr

🧠 Semántica

• El parser detecta BEGIN justo después de AS y conmuta a body multi-statement (depth tracking idéntico a procedure/trigger).
• RETURN expr evalúa la expresión y termina la function devolviendo ese valor al caller.
• RETURN burbujea a través de IF/WHILE/FOR/CASE/BEGIN sin código extra (mismo patrón de sentinel que EXIT).
• Si la function llega al final sin RETURN, devuelve NULL.
• RETURN fuera de un function body multi-statement → [GBY-4118].
• Funciones que llaman funciones funcionan correctamente — cada invocación snapshot-tea/restaura su pending RETURN.

✅ Ejemplos

-- IF con early return
CREATE FUNCTION sign(x INT) RETURNS TEXT AS BEGIN
    IF x < 0 THEN
        RETURN 'negative';
    ELSIF x = 0 THEN
        RETURN 'zero';
    ELSE
        RETURN 'positive';
    END IF;
END;

SELECT sign(-3), sign(0), sign(7);  -- 'negative', 'zero', 'positive'

-- Variables locales + loop + RETURN
CREATE FUNCTION sum_to(n INT) RETURNS INT AS BEGIN
    DECLARE i INT DEFAULT 1;
    DECLARE total INT DEFAULT 0;
    WHILE i <= n LOOP
        SET total = total + i;
        SET i = i + 1;
    END LOOP;
    RETURN total;
END;

SELECT sum_to(10);  -- 55

-- Composición de functions
CREATE FUNCTION dbl(x INT) RETURNS INT AS x * 2;
CREATE FUNCTION quad(x INT) RETURNS INT AS BEGIN
    RETURN dbl(dbl(x));
END;

SELECT quad(3);  -- 12

❌ Errores típicos

⚠️ No soportado todavía

• RETURNS TABLE (table-valued functions) — diferido.
• RETURN QUERY <select> estilo PL/pgSQL — diferido.
• OUT / INOUT parameters como mecanismo de retorno alternativo — diferido.

INTEGRITY CHECK

Recorre la DB abierta y reporta toda inconsistencia detectable: páginas con CRC inválido, filas no decodificables, entradas de índice secundario huérfanas (apuntan a PKs que ya no existen) y FKs huérfanas (valor no NULL sin parent). De solo lectura — no modifica nada.

🛤️ Railroad

flowchart LR
    S([▶]) --> I[INTEGRITY] --> C[CHECK] --> SEMI[";"] --> E([■])

📜 EBNF

integrity_check ::= "INTEGRITY" "CHECK"

✅ Forma del resultado

INTEGRITY CHECK devuelve un ResultSet con columnas kind, object, detail — una fila por hallazgo. El campo message resume:

• DB sana: OK · N tablas · M filas · K índices · F FKs · P páginas
• DB con hallazgos: FAIL · H hallazgos · ...

Ejemplo de respuesta sin hallazgos:

{
  "columns": ["kind", "object", "detail"],
  "rows": [],
  "message": "OK · 2 tablas · 4 filas · 1 índices · 2 FKs · 4 páginas"
}

🏷️ Categorías de hallazgo

Recomendado correrlo después de un crash, después de restaurar un backup, o como sanity check periódico. La complejidad es O(filas + entradas_de_índice + filas_con_FK), totalmente secuencial.

🧠 Combinaciones útiles dentro de una transacción

gabysql permite múltiples sentencias separadas por ; en un solo /exec HTTP o en un solo gabysql exec ... "...". Todas viajan dentro de la misma transacción: si una falla, todas se revierten.

-- Receta común: schema + datos seed + índice + verify, todo atómico
CREATE TABLE products (id INT PRIMARY KEY, sku TEXT, price FLOAT);
INSERT INTO products (id, sku, price) VALUES (1, 'A-001', 99.0);
INSERT INTO products (id, sku, price) VALUES (2, 'A-002', 149.5);
CREATE INDEX idx_products_sku ON products (sku);
SELECT * FROM products WHERE sku = 'A-001';

Si la 4ª sentencia (CREATE INDEX) falla por el motivo que sea, las 3 anteriores también se revierten: la DB queda en el estado previo.

🔭 Lo que no está implementado todavía

flowchart LR
    A([Camino A]) --> NOT_NULL[NOT NULL] --> UNIQUE[UNIQUE] --> DEFAULT[DEFAULT]
    DEFAULT --> ORDER_BY[ORDER BY indexado] --> COMPOSITE[Índice compuesto]
    A --> EXPLAIN[EXPLAIN]
    B([Camino B]) --> ALTER[ALTER TABLE] --> PREP[Prepared statements]
    C([Camino C]) --> JOIN[JOIN] --> GROUP[GROUP BY] --> SUB[Subqueries] --> CTE[CTE / window]

Cada bucket vive en su camino correspondiente del COMMERCIAL_ROADMAP. Si necesitas alguno con prioridad para un caso de uso real, abre un Issue describiendo el escenario.