simple-ddl-parser

library1.13.0pypypi✓ verified 85d ago

Simple DDL Parser is a Python library designed to parse SQL DDL (Data Definition Language) files from various dialects, including HQL, TSQL (MSSQL), Oracle, AWS Redshift, Snowflake, MySQL, and PostgreSQL. It extracts comprehensive information about database entities like tables, columns (types, defaults, primary keys), sequences, alters, and custom types into a JSON or Python dictionary format. The library is actively maintained with frequent releases, currently at version 1.13.0, and typically sees rapid updates with more than 12 releases per year.

database data

pip install simple-ddl-parser

github ↗package ↗

INSTALL

IMPORT

SIG · SIMPLE-DDL-PARSER

simple-ddl-parser

databasepythonv1.13.0

Install

1.8s avg

Import

155ms

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.13.0 · 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.920 runs

installs and imports cleanly · install 0.0s · import 0.164s · 19.4MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.8s · import 0.146s · 20MB

18MB installed

● package 18MB

Code

Verified usage

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

DDLParser

✓ from simple_ddl_parser import DDLParser

parse_from_file

✓ from simple_ddl_parser import parse_from_file

This quickstart demonstrates how to parse a DDL statement using the `DDLParser` class. It shows a basic table creation and an example of parsing an HQL statement with the `output_mode='hql'` argument to extract dialect-specific details like `EXTERNAL` or `LOCATION`.

from simple_ddl_parser import DDLParser ddl_statement = """ CREATE TABLE users ( user_id INT PRIMARY KEY, username VARCHAR(50) NOT NULL UNIQUE, email VARCHAR(100), created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); """ parser = DDLParser(ddl_statement) parsed_data = parser.run() print(parsed_data) # Example with dialect-specific output (e.g., HQL) hql_ddl = """ CREATE EXTERNAL TABLE IF NOT EXISTS database.table_name ( day_long_nm string, calendar_dt date, source_batch_id string ) PARTITIONED BY (batch_id int) STORED AS PARQUET LOCATION 's3://datalake/table_name/v1'; """ hql_parser = DDLParser(hql_ddl) hql_parsed_data = hql_parser.run(output_mode='hql') print(hql_parsed_data)

Debug

Known issues

breakingPython 3.7 and 3.8 are no longer supported. The minimum required Python version is now 3.9.

fix

Upgrade your Python environment to 3.9 or newer.

affects: >=1.8.0

breakingThe output structure for arguments within brackets (e.g., `NULL_IF=('field')`) changed from a single string to a list of strings. Additionally, `=` and `IN` keywords are now parsed as separate tokens, which might affect custom processing of the output.

fix

Update your code to expect `[''field'']` instead of `''('field')'` for bracketed arguments. Review custom parsing logic that might rely on older tokenization of `=` and `IN`.

affects: >=1.6.0

breakingFor PostgreSQL, `TIME ZONE` is now an explicit boolean keyword `with_time_zone` instead of being part of the type definition. For BigQuery, `RANGE_BUCKETS` range is now in its own `range` keyword, and `*_TRUNC` functions' second argument moved to `trunc_by`.

fix

Adjust your code to handle the new output schema for PostgreSQL's `TIME ZONE` and BigQuery's `RANGE_BUCKETS` and `*_TRUNC` constructs.

affects: >=1.3.0

gotchaBy default, the parser does not raise an error if a statement cannot be parsed; instead, it silently skips the problematic statement and may produce incomplete or empty output. This can make debugging difficult.

fix

Initialize the parser with `DDLParser(ddl_string, silent=False)` to force it to raise a `DDLParserError` on unparsable statements. Alternatively, inspect the output carefully for missing entities.

affects: All versions

Errors

Common errors & fixes

DDLParserError: Unknown statement at LexToken(STRING,"'(value)'",line,column)

The parser failed to understand a `CHECK` constraint using the `IN` keyword, e.g., `CHECK(col IN ('val1', 'val2'))`.

fix

Ensure you are using a recent version of `simple-ddl-parser` (fix was included in `v0.26.0` and later). If the issue persists with other `IN` clauses, consider rewriting the `CHECK` statement using `OR` conditions or report an issue.

Table is completely missing from the parsed output, or columns are incorrect, despite valid DDL.

The parser might encounter issues with complex index definitions (e.g., multi-column indexes with many included columns) within a `CREATE TABLE` statement, causing it to skip the entire table or misparse parts of it.

fix

Simplify the problematic index definitions in your DDL for parsing, or update to the latest version as bug fixes are frequently released for such edge cases. Report specific DDL examples as GitHub issues if the problem persists.

TypeError: 'NoneType' object is not subscriptable

This generic error often occurs when the parser fails to correctly interpret a part of the DDL, leading to `None` being returned where a dictionary or list was expected, and subsequent code attempts to access it.

fix

Enable strict error reporting with `DDLParser(ddl_string, silent=False)` to get a more specific `DDLParserError`. Review the DDL for syntax that might not be fully supported by `simple-ddl-parser` or dialect-specific nuances.

Upgrade

Version history

1.13.0latest on PyPI · released Mar 28, 2026

Audit

Dependencies

plyrequiredUsed for lexing and parsing (lex & yacc in Python).

pythonrequiredRequires Python 3.9 or higher. Support for Python 3.7 and 3.8 was deprecated in v1.8.0.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/xnuinside/simple-ddl-parser ↗

packagehttps://pypi.org/project/simple-ddl-parser/ ↗