sqloxide

library0.61.1pypypi✓ verified 21d ago

Sqloxide provides Python bindings for the high-performance `sqlparser-rs` Rust library. It enables fast, efficient, and accurate parsing of SQL queries into a structured Abstract Syntax Tree (AST) in Python, making it suitable for tasks like building data lineage graphs, especially across complex or auto-generated SQL codebases that include deeply nested queries, sub-selects, and table aliases. The library is currently at version 0.61.1 and its minor version now tracks the underlying `sqlparser-rs` library's minor version, indicating a responsive release cadence.

database data

pip install sqloxide

github ↗package ↗

INSTALL

IMPORT

SIG · SQLOXIDE

sqloxide

databasepythonv0.61.1

Install

2.4s avg

Import

—

Disk

33MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.61.1 · 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

py 3.10–3.95 runs

build_error

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.4s · import 0.000s · 36MB

33MB installed

● package 33MB

Code

Verified usage

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

parse_sql

✓ from sqloxide import parse_sql

mutate_expressions

✓ from sqloxide import mutate_expressions

Used for programmatic modification of the SQL AST.

mutate_relations

✓ from sqloxide import mutate_relations

Used for programmatic modification of the SQL AST, specifically relations.

This quickstart demonstrates how to parse a SQL query using `sqloxide.parse_sql`. The function returns a Python object which is a typed Abstract Syntax Tree (AST) that mirrors the `sqlparser-rs` AST schema. You can specify different SQL dialects (e.g., 'ansi', 'mysql', 'postgres', 'sqlite', 'snowflake', 'bigquery', 'hive', 'generic') for accurate parsing.

from sqloxide import parse_sql sql_query = """ SELECT employee.first_name, employee.last_name, call.start_time, call.end_time, call_outcome.outcome_text FROM employee INNER JOIN call ON call.employee_id = employee.id INNER JOIN call_outcome ON call.call_outcome_id = call_outcome.id ORDER BY call.start_time ASC; """ # Parse the SQL query, specifying a dialect (e.g., 'ansi') ast_output = parse_sql(sql=sql_query, dialect='ansi') # The output is a Python object representing the AST # print(ast_output) # Uncomment to see the full AST # Example of accessing parts of the AST (structure depends on SQL and sqlparser-rs version) if ast_output and isinstance(ast_output, list) and 'Query' in ast_output[0]: query_body = ast_output[0]['Query']['body'] if 'Select' in query_body: projection_items = query_body['Select']['projection'] print(f"Number of projected columns: {len(projection_items)}") print(f"First projected item: {projection_items[0]}")

Debug

Known issues

breakingSqloxide v0.61.0 dropped support for Python 3.7 and 3.8, requiring Python 3.9 or newer. This change was due to incompatibilities with `pyo3` 0.28, which was upgraded alongside `sqlparser-rs` to 0.61.0.

fix

Upgrade your Python environment to 3.9 or higher.

affects: >=0.61.0

breakingWith the upgrade to `sqlparser-rs` 0.61.0 in sqloxide v0.61.0, several `Statement` variants (e.g., `Update`, `CreateView`, `Truncate`, `Grant`, `Revoke`) changed their internal representation from inline struct variants to tuple-struct wrappers. This significantly alters the `serde`/JSON shape of the AST for these statement types compared to versions prior to 0.61.0.

fix

If your code relies on directly inspecting or manipulating the AST structure for these statement types, you will need to update your logic to match the new JSON/Python object shape. Refer to the `sqlparser-rs` 0.57-0.61 release notes for specific structural changes.

affects: >=0.61.0

gotchaStarting with v0.61.0, sqloxide adopted a new versioning scheme where its minor version (e.g., `0.61.x`) now tracks the minor version of the wrapped `sqlparser-rs` crate (e.g., `0.61`). This means that `sqloxide`'s version number will change more frequently and directly reflect the underlying Rust parser's evolution.

fix

Be aware that minor version bumps in sqloxide may now correspond to significant updates and potential breaking changes in the underlying `sqlparser-rs` library. Review `sqlparser-rs` changelogs in addition to sqloxide's for detailed impact analysis during upgrades.

affects: >=0.61.0

gotchaIn versions prior to v0.61.1, exceptions raised within Python callbacks provided to `mutate_relations` or `mutate_expressions` functions might not have been properly propagated. This could lead to silently returning partially mutated results instead of signalling an error.

fix

Upgrade to sqloxide v0.61.1 or later to ensure proper exception propagation from mutation callbacks. If on an older version, add robust error checking within and around your mutation callbacks.

affects: <0.61.1

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'sqloxide'

The `sqloxide` library is not installed in your current Python environment.

fix

pip install sqloxide

TypeError: parse_sql_to_ast() missing 1 required positional argument: 'sql'

The `parse_sql_to_ast` function was called without providing the necessary SQL query string argument.

fix

import sqloxide
ast = sqloxide.parse_sql_to_ast("SELECT 1 FROM my_table")

sqloxide.SqloxideError: ParserError("Expected an expression after SELECT, found: FROM")

The provided SQL query string is syntactically incorrect or contains elements not supported by the underlying `sqlparser-rs` library.

fix

Review and correct the SQL query string to ensure it is valid, for example: `sqloxide.parse_sql_to_ast("SELECT column_name FROM my_table")`

AttributeError: 'list' object has no attribute 'statements'

The `parse_sql_to_ast` function returns a list of dictionaries (representing SQL statements), but you are attempting to access an attribute directly on this list object as if it were a single custom object or dictionary.

fix

Iterate through the returned list or access elements by index, and then access dictionary keys using `['key']` notation. For example:

import sqloxide
ast = sqloxide.parse_sql_to_ast("SELECT 1; SELECT 2;")
for statement_dict in ast:
    print(statement_dict.keys())

# Or for a single statement:
single_statement_ast = sqloxide.parse_sql_to_ast("SELECT 1")
first_statement = single_statement_ast[0]
print(first_statement.get('Select'))

Upgrade

Version history

0.61.1latest on PyPI · released Apr 6, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/wseaton/sqloxide ↗

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