Quick start
sqlingo is built around one idea: SQL is a tree. A query string goes in, becomes a tree of objects you can inspect and transform, and comes back out as a string in any dialect. Parsing, transpiling, optimizing, and building queries are all variations of this same cycle. Once that model clicks, the rest of the API follows naturally.
This page gets the library installed and shows each major operation once so you have a working mental map before reading the full guide.
Install
sqlingo ships as a single npm package with one peer dependency. luxon is used internally for date and time literal handling: dialects differ substantially in how they represent dates (DATE_SUB in MySQL, interval arithmetic in Postgres, DATE_ADD in BigQuery), and luxon provides the cross-platform date parsing that lets sqlingo correctly transpile between them.
npm install sqlingo luxonParse SQL
Parsing is always the first step. parseOne takes a SQL string and returns a tree of Expression objects: an AST (abstract syntax tree) where each node represents one SQL concept such as a column reference, a function call, a WHERE clause, or a literal value. The tree is what you work with. Generating SQL, searching for columns, and running transformations all operate on that tree.
import { parseOne } from "sqlingo";
const ast = parseOne("SELECT a, b FROM users WHERE active = true");
console.log(ast.sql()); // "SELECT a, b FROM users WHERE active = TRUE"Notice that true became TRUE in the output. The base dialect normalizes SQL as it generates: booleans are uppercased, whitespace is collapsed, and some syntax is canonicalized to a standard form. This normalization is deliberate. It makes query comparison and transformation predictable. If you need output that matches a specific database's conventions, pass that dialect to .sql(), or use transpile with explicit read and write options.
Transpile between dialects
Transpiling converts SQL from one database syntax to another. The transpile function accepts a SQL string and returns an array of SQL strings, one per statement in the input, since a single input can contain multiple semicolon-separated statements. When you are transpiling a single statement, the typical pattern is to destructure with [sql].
import { transpile } from "sqlingo";
import { MySQL } from "sqlingo/mysql";
import { Postgres } from "sqlingo/postgres";
const [sql] = transpile(
"SELECT DATE_SUB(d, INTERVAL 1 DAY) FROM t",
{ read: MySQL, write: Postgres },
);
console.log(sql);
// "SELECT d - INTERVAL '1 DAY' FROM t"The read option tells sqlingo how to parse the input: which tokenizer rules to use, which keywords to recognize, and which syntax quirks to expect. The write option controls how the output is generated. Here, MySQL's DATE_SUB has no direct Postgres equivalent, so sqlingo converts it to interval arithmetic automatically. The same mechanism handles type casting, string concatenation operators, quoting conventions, and hundreds of other dialect differences.
Each dialect is imported from a separate entry point (sqlingo/mysql, sqlingo/postgres, etc.), which lets bundlers tree-shake the ones you don't use. Only the dialects you import end up in your bundle.
Optimize a query
The optimizer rewrites SQL to be more explicit and normalized. It needs schema information to know which tables and columns exist, so it can expand SELECT *, qualify ambiguous column references, and remove dead conditions.
import { optimize, parseOne, MappingSchema } from "sqlingo";
const schema = new MappingSchema({ t: { a: "int", b: "int" } });
const optimized = optimize(
parseOne("SELECT * FROM t WHERE 1 = 1 AND a > 2"),
{ schema },
);
console.log(optimized.sql());
// SELECT "t"."a" AS "a", "t"."b" AS "b" FROM "t" AS "t" WHERE "t"."a" > 2Three transformations happened here:
SELECT *expanded to"t"."a" AS "a", "t"."b" AS "b"because the schema declaredaandbas the columns oft.1 = 1was removed as a tautology that can never cause a row to be filtered.All identifiers were qualified with their table name and double-quoted, turning
ainto"t"."a".
Optimization is optional. Use it when you need explicit, unambiguous SQL for query analysis tools, migration pipelines, lineage tracking, or any situation where you need to know precisely which table every column comes from.
Next steps
The Guide explains what happens under the hood:
How the tree is structured and what each node type represents
How to search and transform nodes with
.find(),.findAll(), and.transform()How transpiling and optimizing build on the same parse-tree-generate cycle