sqloxide

As of v0.61.0, sqloxide supports free-threaded Python (3.13t, 3.14t). You can parse SQL from multiple threads in parallel without the Global Interpreter Lock (GIL) and without needing manual locks, making it highly efficient for parallel processing.

import concurrent.futures
from sqloxide import parse_sql

queries = [f"SELECT col_{i} FROM table_{i}" for i in range(100)]

# Works efficiently in parallel on free-threaded Python builds
with concurrent.futures.ThreadPoolExecutor(max_workers=8) as pool:
    results = list(pool.map(lambda q: parse_sql(sql=q, dialect="generic"), queries))

Install sqloxide using pip. Wheels are available for Linux (x86_64, i686, aarch64), macOS (x86_64, ARM), and Windows, supporting Python 3.9 through 3.14.

pip install sqloxide

Use parse_sql to convert a SQL string into a typed Abstract Syntax Tree (AST). The returned object follows the sqlparser-rs AST schema and behaves like a Python dictionary/JSON document. You must specify a dialect (e.g., 'ansi', 'generic').

from sqloxide import parse_sql

sql = """
SELECT employee.first_name, employee.last_name
FROM employee
ORDER BY employee.first_name ASC;
"""

output = parse_sql(sql=sql, dialect='ansi')
print(output)

If you have modified the AST in Python, you can reconstruct the original SQL query using restore_ast. This is useful for performing manual edits to the parsed structure and then generating the resulting SQL string.

from sqloxide import restore_ast

# Assuming 'output' is an AST from parse_sql()
query = restore_ast(ast=output)
print(query)

Use mutate_relations to perform structured edits specifically on table names or relations within a query. This is more targeted than general expression mutation.

from sqloxide import parse_sql, mutate_relations

sql = "SELECT something from somewhere where something = 1"
ast = parse_sql(sql=sql, dialect="ansi")

def func(x):
    return x.replace("somewhere", "anywhere")

result = mutate_relations(parsed_query=ast, func=func)
print(result)

Use the visitor pattern to perform structured edits on expressions within a query. Pass the parsed AST and a function func that accepts an AST node and returns a modified version of it.

from sqloxide import parse_sql, mutate_expressions

sql = "SELECT something from somewhere where something = 1 and something_else = 2"

def func(x):
    if "CompoundIdentifier" in x.keys():
        for y in x["CompoundIdentifier"]:
            y["value"] = y["value"].upper()
    return x

ast = parse_sql(sql=sql, dialect="ansi")
result = mutate_expressions(parsed_query=ast, func=func)
print(result)

The restore_ast function takes a list of Python objects (representing a modified AST) and converts them back into a list of SQL query strings.

Parameters:

• ast (list): A list of Python objects representing the SQL AST.

Returns: A list of strings, where each string is a reconstructed SQL query.

Errors:

• Raises ValueError if the Python objects cannot be deserialized back into SQL statements.

import sqloxide

# Assuming 'ast' was obtained from sqloxide.parse_sql()
sql_queries = sqloxide.restore_ast(ast)
for query in sql_queries:
    print(query)

Use mutate_expressions(parsed_query, func) to transform expressions within a parsed SQL query. This is a powerful tool for rewriting SQL logic.

• parsed_query: The parsed SQL statement object.
• func: A Python callable that accepts an expression object and returns a new expression object.

The function performs the following lifecycle for each expression:

1. Converts the expression object to a Python-compatible format.
2. Passes it to your func.
3. Takes the return value of func and converts it back into a SQL expression object to replace the original.

Returns a list of strings, where each string is the modified SQL statement.

def replace_with_constant(expr):
    # Logic to return a new expression object
    return new_expr

modified_queries = mutate_expressions(parsed_query, replace_with_constant)

Use extract_relations(parsed_query) to retrieve all relations (e.g., table names) from a previously parsed SQL query object. The parsed_query must be a Python object representing a list of SQL statements.

Returns a list of relation objects.

relations = extract_relations(parsed_parsed_query)
# relations is a list of relation objects found in the query

Use extract_expressions(parsed_query) to retrieve all expressions (e.g., column references, literals, arithmetic operations) from a parsed SQL query object.

Returns a list of expression objects.

expressions = extract_expressions(parsed_query)
# expressions is a list of expression objects found in the query

Use mutate_relations(parsed_query, func) to modify table identifiers within a parsed query.

• parsed_query: The parsed SQL statement object.
• func: A Python callable that accepts a single string (the identifier value) and returns a new string.

The function iterates through all relations and replaces the identifier values with the return value of func.

Returns a list of strings, where each string is the modified SQL statement.

def rename_table(name):
    return f"new_{name}"

# This will rename all tables in the query
modified_queries = mutate_relations(parsed_query, rename_table)

The sqloxide module provides several functions for inspecting and modifying the SQL AST after it has been parsed. These functions allow you to traverse the tree to find specific elements or apply transformations.

Available Functions:

• extract_relations(ast): Extracts relations (e.g., table names) from the AST.
• mutate_relations(ast, ...): Mutates relations within the AST.
• extract_expressions(ast): Extracts expressions from the AST.
• mutate_expressions(ast, ...): Mutates expressions within the AST.