sqlglot

library30.1.0pypypi✓ verified 35d ago

SQLGlot is a powerful Python library for parsing, transpiling, optimizing, and even executing SQL. It supports translating SQL across over 30 different database dialects, enabling cross-dialect compatibility, query parsing into Abstract Syntax Trees (ASTs), programmatic query rewriting, and optimization. It's known for being a fast, pure-Python solution with no external dependencies and is regularly among the top Python package downloads. The library is currently at version 30.1.0 and follows a versioning strategy where MINOR version increments can introduce backwards-incompatible changes.

data database serialization

github ↗package ↗homepage ↗docs ↗

Install & Compatibility

Where this runs

tested against v30.8.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

5/15 runs

✓ 2.81s

py 3.11

5/15 runs

✓ 2.8s

py 3.12

5/15 runs

✓ 2.64s

py 3.13

5/15 runs

✓ 2.63s

py 3.9

13/15 runs

✓ 2.68s

71MB installed

● package 71MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Commonly imported directly for convenience; the root module also provides it.

from sqlglot import parse_one

Commonly imported directly for convenience; the root module also provides it.

from sqlglot import transpile

The `exp` submodule contains all expression types for AST manipulation and is typically imported directly from the root `sqlglot` module now.

from sqlglot import exp

This quickstart demonstrates basic SQL parsing and cross-dialect transpilation. The `parse_one` function converts a SQL string into an Abstract Syntax Tree (AST), while `transpile` converts SQL between specified dialects. It also shows a common pattern for transforming MySQL-specific functions to BigQuery equivalents.

from sqlglot import parse_one, transpile # Parse a SQL query (defaults to SQLGlot dialect if 'read' is not specified) sql_query = "SELECT id, name FROM users WHERE age > 18" expression = parse_one(sql_query) print(f"Parsed Expression: {expression}") # Transpile from MySQL to BigQuery mysql_query = "SELECT IFNULL(employee_name, 'Unknown') AS employee_status FROM employees;" bigquery_query = transpile(mysql_query, read="mysql", write="bigquery")[0] print(f"Transpiled to BigQuery: {bigquery_query}") # Further manipulation of the AST is possible with `expression` object # E.g., print(expression.find_all(exp.Column))

sqlglot --version

Debug

Known footguns

gotchaFailing to specify the `read` (source) or `write` (target) dialect during `parse_one` or `transpile` calls can lead to `ParseError` or incorrect output. SQLGlot defaults to its 'SQLGlot dialect', which is a superset, if not specified.

gotchaSQLGlot strictly parses valid SQL. It will raise a `ParseError` if the SQL string contains non-SQL constructs like templating variables (e.g., `{{parameter}}`) or invalid syntax (e.g., unquoted timestamps in some contexts).

breakingSQLGlot's versioning strategy indicates that MINOR version increments (e.g., 29.x to 30.x) can introduce backwards-incompatible fixes or feature additions. Be mindful of minor version bumps during upgrades.

gotchaWhile SQLGlot is comprehensive, transpilation across all possible dialect pairs and inputs is an 'incremental' problem. Some specific dialect conversions may have limitations or ongoing improvements.

gotchaParsing SQL queries with column names or identifiers using non-standard quoting (e.g., backticks as often used by LLMs) can lead to `ParseError`.

gotchaSQLGlot parsing or transpilation can, in rare cases, encounter performance bottlenecks or infinite loops when processing extremely complex or malformed SQL, leading to a 'TIMEOUT' rather than an explicit `ParseError`. This is more likely with very large queries, deeply nested expressions, or highly unusual syntax patterns.

Upgrade

Version history

Breaking-change detection hasn't run for this library yet.

Audit

Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity

14 hits · last 30 days

gptbot

amazonbot

ahrefsbot

claudebot

Resources

githubhttps://github.com/tobymao/sqlglot ↗

packagehttps://pypi.org/project/sqlglot/ ↗

homepagehttps://sqlglot.com/ ↗

docshttps://sqlglot.com/sqlglot.html ↗