sqlingo.js

A JavaScript/TypeScript port of SQLGlot, which is a comprehensive SQL parser, transpiler, optimizer, and engine.

This package allows you to parse, transpile, optimize, and execute SQL across 33+ dialects in JavaScript, with no other setup.

Supports TypeScript & CJS/ESM. Works in Node.js and the browser.

There's also an alternative polyglot library - check it out!

Installation

npm install @hdnax/sqlingo.js
# or
pnpm add @hdnax/sqlingo.js
# or
yarn add @hdnax/sqlingo.js

Quick Start

import { parse, transpile } from "@hdnax/sqlingo.js";

// Parse SQL into an AST
const [ast] = parse("SELECT a, b FROM t WHERE a > 1");

// Transpile between dialects
const [result] = transpile("SELECT EPOCH_MS(1618088028295)", {
  read: "duckdb",
  write: "hive",
});
// => "SELECT FROM_UNIXTIME(1618088028295 / POW(10, 3))"

See the Usage Guide for full API documentation and examples.

Supported Dialects

Athena, BigQuery, ClickHouse, Databricks, Doris, Dremio, Drill, Druid, DuckDB, Dune, Exasol, Fabric, Hive, Materialize, MySQL, Oracle, Postgres, Presto, PRQL, Redshift, RisingWave, SingleStore, Snowflake, Solr, Spark, Spark2, SQLite, StarRocks, Tableau, Teradata, Trino, TSQL

Goals (& Non-goals)

The main goal is that sqlingo.js should be a close mirror to SQLGlot. This way, it can quickly catch up with SQLGlot bug fixes and new releases.

Another goal is to stay true to Typescript convention (check CONVENTION.md).

Currently, these are non-goals:

• Optimized performance.
• Optimized bundle size.
• Compatibility with SQLGlot (but it should be trivial to make the two compatible)

Backstory

I'm currenly maintaining @dbml/core, a library that supports converting between DBML and SQL. Under the hood it uses ANTLR for parsing, and honestly it's been a mess:

• @dbml/core is 33MB, which is quite insane to be honest. It actually broke our CI with OOM errors.
• We can't add more dialects without making the bundle even larger.
• The parser is feature-incomplete and spits out user-unfriendly error messages like No viable alternative at....
• After all that, we only support 5 dialects.

At a hackathon, I was poking around Dagster and stumbled upon SQLGlot. I thought it was amazing that there was a library like this. SQLGlot seems to be trusted by a lots of tools in the Python ecosystems.

Since then, I was looking for an alternative in Javascript, because I want to run it on the browser. Sadly, at the time, there was none that I knew of.

I tried running SQLGlot through Pyodide as a hack, but the runtime is way too heavy to ship anywhere that matters.

Therefore, I decided to port it. At 2 weeks into my porting process, polyglot was announced (LOL!). However, I didn't want to waste my effort & also wanted full control - so I just continued anyways.

Development Setup

Prerequisites

Make sure these are installed on your machine:

• node@^20 - Installation Guide
• pnpm@^10.26.1 - Installation Guide

Available Scripts

pnpm test          # Run tests
pnpm test:ui       # Run tests with UI
pnpm test:coverage # Run tests with coverage
pnpm build         # Build the project
pnpm dev           # Build in watch mode
pnpm typecheck     # Type check without emitting
pnpm lint          # Lint the code
pnpm lint:fix      # Lint and auto-fix issues
pnpm run docs      # Generate documentation

Mirror Guide

Check CONVENTION.md.

I have compiled our convention and lots of pitfalls there. You can use the knowledge there to allow easier debugging.

License

sqlingo.js is licensed under the MIT License. See LICENSE for details.

Attribution

This project is based on SQLGlot by Toby Mao, which is also licensed under the MIT License. The original SQLGlot source code is included as a submodule in this repository.

See COPYRIGHT_NOTICE for full copyright information.