{"id":5504,"library":"sqloxide","title":"Sqloxide","description":"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.","status":"active","version":"0.61.1","language":"en","source_language":"en","source_url":"https://github.com/wseaton/sqloxide","tags":["SQL","parser","AST","Rust","data lineage"],"install":[{"cmd":"pip install sqloxide","lang":"bash","label":"Install stable release"}],"dependencies":[],"imports":[{"symbol":"parse_sql","correct":"from sqloxide import parse_sql"},{"note":"Used for programmatic modification of the SQL AST.","symbol":"mutate_expressions","correct":"from sqloxide import mutate_expressions"},{"note":"Used for programmatic modification of the SQL AST, specifically relations.","symbol":"mutate_relations","correct":"from sqloxide import mutate_relations"}],"quickstart":{"code":"from sqloxide import parse_sql\n\nsql_query = \"\"\"\nSELECT\n    employee.first_name,\n    employee.last_name,\n    call.start_time,\n    call.end_time,\n    call_outcome.outcome_text\nFROM\n    employee\nINNER JOIN call ON call.employee_id = employee.id\nINNER JOIN call_outcome ON call.call_outcome_id = call_outcome.id\nORDER BY\n    call.start_time ASC;\n\"\"\"\n\n# Parse the SQL query, specifying a dialect (e.g., 'ansi')\nast_output = parse_sql(sql=sql_query, dialect='ansi')\n\n# The output is a Python object representing the AST\n# print(ast_output) # Uncomment to see the full AST\n\n# Example of accessing parts of the AST (structure depends on SQL and sqlparser-rs version)\nif ast_output and isinstance(ast_output, list) and 'Query' in ast_output[0]:\n    query_body = ast_output[0]['Query']['body']\n    if 'Select' in query_body:\n        projection_items = query_body['Select']['projection']\n        print(f\"Number of projected columns: {len(projection_items)}\")\n        print(f\"First projected item: {projection_items[0]}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or higher.","message":"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.","severity":"breaking","affected_versions":">=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.","message":"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.","severity":"breaking","affected_versions":">=0.61.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.61.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<0.61.1"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}