SQL Metadata

2.20.0 · active · verified Thu Apr 09

sql-metadata is a Python library that parses SQL queries to extract metadata such as table names, column names, query type (e.g., SELECT, INSERT, UPDATE, DELETE), and more. It leverages the tokenized query output from the `sqlparse` library. The current version is 2.20.0, and it maintains an active release cadence, often releasing minor versions to improve parsing accuracy and update its `sqlparse` dependency.

Warnings

breaking Support for Python 3.8 was dropped in version 2.16.0. Users on Python 3.8 will need to upgrade their Python environment or pin sql-metadata to a version prior to 2.16.0.
Fix: Upgrade Python to 3.9 or newer, or downgrade sql-metadata to <2.16.0.
gotcha The `Parser.columns` method in version 2.20.0 contains a fix that causes a column named `source` to be dropped if it is the last column in a `SELECT` statement. This change in behavior might affect applications relying on specific column outputs for such edge cases.
Fix: If 'source' is expected as the last column, verify results on v2.20.0. Consider restructuring the query or inspecting `parser.tokens` directly for more granular control if this specific edge case causes issues.
gotcha Parsing accuracy for specific SQL dialects and complex constructs (e.g., `ALTER TABLE ... ADD KEY`, MSSQL unqualified schema tables, `TRUNCATE TABLE`, Hive `CREATE FUNCTION`) has been incrementally improved across minor versions (e.g., v2.13.0, v2.14.0, v2.17.0, v2.12.0). Users on older versions might experience incorrect or incomplete metadata extraction for such queries.
Fix: Ensure you are using the latest version of `sql-metadata` to benefit from the most recent parsing improvements and bug fixes, especially for complex or less common SQL constructs.
gotcha The library's parsing capabilities are highly dependent on the underlying `sqlparse` library. While `sql-metadata` manages its `sqlparse` dependency, breaking changes or parsing quirks in `sqlparse` can indirectly affect `sql-metadata`'s behavior and accuracy. Always check `sqlparse` release notes if `sql-metadata` updates its `sqlparse` dependency.
Fix: When `sql-metadata` updates its `sqlparse` dependency (often noted in release logs), review `sqlparse`'s changelog for any potential regressions or behavior changes that might affect your SQL parsing.

Install

pip install sql-metadata Install stable version

Imports

Parser
```
from sql_metadata.parser import Parser
```

Quickstart

Initialize a Parser object with a SQL string to extract various metadata attributes.

from sql_metadata.parser import Parser

sql_query = "SELECT id, name, email FROM users WHERE status = 'active' ORDER BY name;"
parser = Parser(sql_query)

print(f"Tables: {parser.tables}")
print(f"Columns: {parser.columns}")
print(f"Query Type: {parser.query_type}")
print(f"Limit: {parser.limit}")
print(f"Group by: {parser.group_by}")

view raw JSON →