Registry / data / sql-metadata

sql-metadata

library3.0.1pypypi✓ verified 25d ago

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.

data serialization

pip install sql-metadata

github ↗package ↗

INSTALL

IMPORT

SIG · SQL-METADATA

sql-metadata

datapythonv3.0.1

Install

2.1s avg

Import

375ms

Disk

22MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.0.1 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.396s · 23.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.1s · import 0.354s · 24MB

22MB installed

● package 22MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Parser

✓ from sql_metadata.parser import Parser

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

Debug

Known issues

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

affects: >=2.16.0

gotchaThe `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.

affects: 2.20.0

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

affects: <2.20.0

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

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'sql-metadata'

The Python package for import is `sql_metadata` (with an underscore), not `sql-metadata` (with a hyphen), or the library is not installed.

fix

First, ensure installation: `pip install sql-metadata`. Then, use the correct import statement: `from sql_metadata.parser import Parser`.

AttributeError: 'Parser' object has no attribute 'get_query_type'

The `Parser` class exposes metadata directly as attributes (e.g., `parser.query_type`, `parser.tables`) rather than as methods (e.g., `parser.get_query_type()`).

fix

Access the metadata directly as attributes: `from sql_metadata.parser import Parser
sql_query = 'SELECT col1 FROM my_table'
parser = Parser(sql_query)
query_type = parser.query_type
tables = parser.tables`

TypeError: expected string or bytes-like object

The `Parser` constructor received an argument of an incorrect type (e.g., `None`, integer, or a list) instead of the expected SQL query string.

fix

Ensure that the argument passed to the `Parser` constructor is a string representing the SQL query: `from sql_metadata.parser import Parser
sql_query = "SELECT col1 FROM my_table" # Must be a string
parser = Parser(sql_query)`

IndexError: list index out of range

This error typically occurs when the provided SQL query is malformed, uses highly complex or non-standard syntax, leading to `sql-metadata` or its `sqlparse` dependency failing to correctly parse or tokenize it.

fix

Ensure your SQL query is syntactically correct and adheres to standard SQL. If the query is complex but valid, try simplifying it. Also, ensure both `sql-metadata` and `sqlparse` are updated to their latest versions: `pip install --upgrade sql-metadata sqlparse`.

Upgrade

Version history

3.0.1latest on PyPI · released Jun 30, 2026

Audit

Dependencies

sqlparserequiredCore dependency for SQL tokenization and parsing. sql-metadata builds on its output.

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/macbre/sql-metadata ↗

packagehttps://pypi.org/project/sql-metadata/ ↗