Sqloxide

Warnings

• breaking Sqloxide 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.
• breaking With 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.
• gotcha Starting 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.
• gotcha In 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.

Install

• pip install sqloxide Install stable release

Imports

• 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.

Quickstart

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]}")