Install & Compatibility
Where this runs
tested against v0.3.11 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.012s · 21.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.008s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Language
✓ from tree_sitter import Language
Parser
✓ from tree_sitter import Parser
tree_sitter_sql
✓ import tree_sitter_sql
This quickstart demonstrates how to initialize the `tree-sitter-sql` grammar with the `tree-sitter` Python bindings, create a parser, and parse a sample SQL string. It then shows how to access the root node and perform a basic traversal to find a specific type of statement.
import tree_sitter_sql
from tree_sitter import Language, Parser
# Initialize the SQL language from the installed grammar package
SQL_LANGUAGE = Language(tree_sitter_sql.language())
# Create a parser and set its language
parser = Parser()
parser.set_language(SQL_LANGUAGE)
# SQL code to parse (must be bytes)
sql_code = b"""
SELECT id, name FROM users WHERE age > 30 ORDER BY name ASC;
"""
# Parse the SQL code
tree = parser.parse(sql_code)
# Get the root node of the syntax tree
root_node = tree.root_node
# Print a basic representation of the tree (for demonstration)
# In a real application, you would traverse the tree or use queries.
print(f"Root Node Type: {root_node.type}")
print(f"Root Node Text: {root_node.text.decode('utf8')}")
# Example of finding a specific node type (e.g., 'select_statement')
# This is a basic traversal; for complex patterns, Tree-sitter queries are used.
select_statement_node = None
for child in root_node.children:
if child.type == 'select_statement':
select_statement_node = child
break
if select_statement_node:
print(f"Found 'select_statement' node. Text: {select_statement_node.text.decode('utf8')}")
else:
print("No 'select_statement' node found.")
Debug
Known issues
breakingGrammar definitions (node names, structure) in `tree-sitter-sql` can evolve. Updates to the grammar may introduce breaking changes to existing Tree-sitter queries that rely on specific node types or structures, requiring query adjustments.fixRegularly check the `tree-sitter-sql` GitHub repository for grammar updates and adjust Tree-sitter queries to match the latest grammar structure. Utilize Tree-sitter's query debugger for validation.
affects: All versions, as grammars are under active development.
breakingThe underlying `tree-sitter` Python library (on which `tree-sitter-sql` depends) may introduce breaking changes. For example, the behavior of `iter_matches` was updated to fix incorrect behavior, requiring changes for code relying on the old behavior.fixStay informed about `tree-sitter` Python binding releases and their change logs. Update your `tree-sitter` dependency and adapt code as necessary.
affects: All versions, as `tree-sitter` core evolves.
gotchaThe `tree-sitter-sql` grammar aims for permissiveness and initially focuses on the PostgreSQL dialect. While general, it may not strictly conform to all nuances of other specific SQL dialects (e.g., SQLite, MySQL, BigQuery).fixIf strict parsing for a particular SQL dialect is required, evaluate the grammar's fidelity to that dialect. Consider contributing to the `tree-sitter-sql` project or exploring dedicated grammars for specific dialects if available (e.g., `tree-sitter-sqlite`, `tree-sitter-sql-bigquery`).
affects: All versions
Upgrade
Version history
0.3.11latest on PyPI · released Oct 1, 2025
Audit
Dependencies
tree-sitterrequiredProvides the core Tree-sitter Python bindings necessary to use the SQL grammar.