Open-Source Databases · macbre

sql-metadata

sql-metadata is a Python library that parses SQL queries and extracts structural metadata such as table names, column names, aliases, and query types. It supports multiple SQL dialects (MySQL, PostgreSQL, SQLite, MSSQL, Hive) and provides utilities for query normalization and alias resolution.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/macbre/sql-metadata

879

GitHub stars

128

Forks

Python

Primary language

MIT

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	macbre/sql-metadata
Owner	macbre
Primary language	Python
License	MIT — OSI-approved
Stars	879
Forks	128
Open issues	23
Latest release	v3.0.1 (2026-06-30)
Last updated	2026-07-08
Source	https://github.com/macbre/sql-metadata

What sql-metadata is

Built on sqlglot, sql-metadata tokenizes and parses SQL queries to extract and resolve metadata including columns, tables, aliases, subqueries, WITH clauses, and values. It returns structured data through a Parser API with properties like .columns, .tables, .columns_dict, and .query_type, supporting complex JOIN and subquery scenarios.

Quickstart

Get the sql-metadata source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/macbre/sql-metadata.git2cd sql-metadata3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

SQL Lineage and Data Governance

Extract table and column dependencies from queries for data lineage tracking, impact analysis, and compliance audits.

Query Analysis and Validation Tools

Build linters, formatters, or analysis tools that need to understand query structure without executing them.

Multi-Dialect SQL Processing Pipelines

Parse and extract metadata from heterogeneous SQL workloads (MySQL, PostgreSQL, Hive) in unified data platforms or ETL orchestration.

Implementation considerations

Dependency on sqlglot—ensure compatibility and update cadence align with your sqlglot version lock.
Parser raises InvalidQueryDefinition (ValueError subclass) for structurally invalid or empty queries; wrap calls in exception handlers.
Alias resolution is automatic but context-dependent; review output for complex nested queries and multi-schema joins.
Column alias names are extracted separately from resolved columns; ensure consuming code uses the correct property (.columns vs. .output_columns).
Test coverage and maintenance are active (latest release June 2026), but validate behavior on your specific SQL dialects before production deployment.

When to avoid it — and what to weigh

Real-Time Query Execution Required — This is a parser, not a query engine. If you need to execute queries or enforce security policies at runtime, use a database driver or query proxy.
Highly Dialect-Specific Edge Cases — While multiple dialects are supported, the README notes that backends 'can differ quite substantially'—vendor-specific syntax may not parse correctly.
Complex Procedural or Dynamic SQL — Parsing T-SQL stored procedures, dynamic SQL generation, or non-standard extensions is not designed to be supported.
Critical Security Enforcement Without Validation — Parser output should be validated; do not rely solely on this tool for blocking malicious queries without additional controls.

License & commercial use

MIT License—permissive open-source license allowing commercial use, modification, and distribution with attribution.

MIT is an OSI-approved permissive license. Commercial use is permitted. Verify compliance with your legal team and include license attribution in derivative works. No warranty or liability guarantees provided under MIT.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Adequate
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Good
Assessment confidence	High

Security considerations

This tool is a parser, not a security gateway. It processes input strings and returns structured data; it does not validate, sanitize, or block queries. Malformed or adversarial SQL may cause parser errors but should not cause code execution. Always validate or sanitize untrusted SQL input before parsing, and do not assume this tool can prevent SQL injection or enforce access controls.

Alternatives to consider

sqlparse

Lower-level SQL tokenizer; more generic, less metadata extraction; sql-metadata is built on sqlglot which offers richer semantic parsing.

sqlglot (direct use)

Lower-level dialect transpiler and parser; more powerful but requires deeper AST understanding; sql-metadata wraps it for simpler metadata extraction use cases.

Custom regex or hand-written parsers

Viable for simple or domain-specific SQL; does not scale to multiple dialects or complex queries; sql-metadata provides tested, multi-dialect coverage.

Software development agency

Build on sql-metadata with DEV.co software developers

Review the GitHub repository, test the interactive demo with your SQL workloads, and run your own dialect compatibility tests before integrating into production pipelines.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

sqllineage sql-parser db

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Databases API Development Custom Software Development Enterprise Software Talk to DEV.co

sql-metadata FAQ

Does sql-metadata execute queries?

No. It is a static parser that extracts metadata (columns, tables, aliases, etc.) from SQL text without connecting to or executing against a database.

Which SQL dialects are supported?

MySQL, PostgreSQL, SQLite, MSSQL, and Apache Hive. The README notes that backend differences can be substantial; test your specific dialect before production use.

How are aliases resolved?

Automatically. The parser resolves column aliases to their source columns, table aliases to table names, and subquery aliases to their underlying tables—all exposed via separate properties (e.g., .columns_aliases, .tables_aliases, .subqueries).

Can I use sql-metadata for security (e.g., blocking certain queries)?

Not as a standalone solution. Use it to extract metadata for analysis, but always validate and sanitize untrusted input separately and deploy additional security controls (e.g., database query proxy, row-level security).

Work with a software development agency

From first prototype to production, DEV.co delivers software development services around tools like sql-metadata. Our software development agency staffs experienced software developers and web developers for custom software development, web development, integrations, and ongoing support across open-source databases and beyond.

Evaluate sql-metadata for Your SQL Processing Needs

Review the GitHub repository, test the interactive demo with your SQL workloads, and run your own dialect compatibility tests before integrating into production pipelines.

Talk to DEV.co Schedule a Consultation