{"id":1723,"library":"sql-metadata","title":"SQL Metadata","description":"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.","status":"active","version":"2.20.0","language":"python","source_language":"en","source_url":"https://github.com/macbre/sql-metadata","tags":["sql","parsing","metadata","database","analysis","query"],"install":[{"cmd":"pip install sql-metadata","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for SQL tokenization and parsing. sql-metadata builds on its output.","package":"sqlparse"}],"imports":[{"symbol":"Parser","correct":"from sql_metadata.parser import Parser"}],"quickstart":{"code":"from sql_metadata.parser import Parser\n\nsql_query = \"SELECT id, name, email FROM users WHERE status = 'active' ORDER BY name;\"\nparser = Parser(sql_query)\n\nprint(f\"Tables: {parser.tables}\")\nprint(f\"Columns: {parser.columns}\")\nprint(f\"Query Type: {parser.query_type}\")\nprint(f\"Limit: {parser.limit}\")\nprint(f\"Group by: {parser.group_by}\")","lang":"python","description":"Initialize a Parser object with a SQL string to extract various metadata attributes."},"warnings":[{"fix":"Upgrade Python to 3.9 or newer, or downgrade sql-metadata to <2.16.0.","message":"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.","severity":"breaking","affected_versions":">=2.16.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"2.20.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.20.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'2.20.0':46 'accuraci':61 'activ':51 'analysi':71 'cadenc':53 'column':21 'current':43 'databas':70 'delet':29 'depend':66 'e.g':25 'extract':15 'improv':59 'insert':27 'leverag':33 'librari':9,41 'maintain':49 'metadata':2,5,16,69 'minor':56 'name':20,22 'often':54 'output':37 'pars':11,60,68 'python':8 'queri':13,23,36,72 'releas':52,55 'select':26 'sql':1,4,12,67 'sql-metadata':3 'sqlpars':40,65 'tabl':19 'token':35 'type':24 'updat':28,63 'version':44,57","created_at":"2026-04-09T04:00:22.101632+00:00","updated_at":"2026-04-16T22:10:15.650734+00:00","problems":[{"fix":"First, ensure installation: `pip install sql-metadata`. Then, use the correct import statement: `from sql_metadata.parser import Parser`.","cause":"The Python package for import is `sql_metadata` (with an underscore), not `sql-metadata` (with a hyphen), or the library is not installed.","error":"ModuleNotFoundError: No module named 'sql-metadata'"},{"fix":"Access the metadata directly as attributes: `from sql_metadata.parser import Parser\nsql_query = 'SELECT col1 FROM my_table'\nparser = Parser(sql_query)\nquery_type = parser.query_type\ntables = parser.tables`","cause":"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()`).","error":"AttributeError: 'Parser' object has no attribute 'get_query_type'"},{"fix":"Ensure that the argument passed to the `Parser` constructor is a string representing the SQL query: `from sql_metadata.parser import Parser\nsql_query = \"SELECT col1 FROM my_table\" # Must be a string\nparser = Parser(sql_query)`","cause":"The `Parser` constructor received an argument of an incorrect type (e.g., `None`, integer, or a list) instead of the expected SQL query string.","error":"TypeError: expected string or bytes-like object"},{"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`.","cause":"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.","error":"IndexError: list index out of range"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.0.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/macbre/sql-metadata","docs":null,"changelog":null,"pypi":"https://pypi.org/project/sql-metadata/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":null}}