0
# Simple DDL Parser
1

2
A comprehensive Python library for parsing DDL (Data Definition Language) SQL statements from various database dialects into structured JSON/Python dictionaries. Built with PLY (Python Lex-Yacc), it converts DDL files into detailed metadata containing information about database schemas, tables, columns (with types, constraints, defaults), primary keys, foreign keys, sequences, custom types, and other database entities.
3

4
## Package Information
5

6
- **Package Name**: simple-ddl-parser
7
- **Language**: Python
8
- **Installation**: `pip install simple-ddl-parser`
9

10
## Core Imports
11

12
```python
13
from simple_ddl_parser import DDLParser, parse_from_file
14
from typing import Optional, Union, List, Dict
15
import logging
16
```
17

18
Import exceptions:
19

20
```python
21
from simple_ddl_parser import SimpleDDLParserException, DDLParserError
22
```
23

24
Import supported dialects information:
25

26
```python
27
from simple_ddl_parser import supported_dialects
28
```
29

30
## Basic Usage
31

32
```python
33
from simple_ddl_parser import DDLParser
34

35
# Parse DDL from string
36
ddl_content = """
37
CREATE TABLE users (
38
    id INTEGER PRIMARY KEY,
39
    name VARCHAR(50) NOT NULL,
40
    email VARCHAR(100) UNIQUE
41
);
42
"""
43

44
parser = DDLParser(ddl_content)
45
parsed_tables = parser.run()
46
print(parsed_tables)
47

48
# Parse DDL from file
49
from simple_ddl_parser import parse_from_file
50

51
parsed_tables = parse_from_file('schema.sql')
52
print(parsed_tables)
53
```
54

55
## Architecture
56

57
The parser is built with a modular dialect-based architecture:
58

59
- **DDLParser**: Main parser class that orchestrates parsing and output formatting
60
- **Dialects**: Input dialect classes handle SQL syntax variations across database systems
61
- **Output Dialects**: Format parsed results according to specific database output requirements
62
- **Lexer/Parser**: PLY-based tokenization and parsing engine for DDL syntax analysis
63
- **Utilities**: Helper functions for name normalization, parentheses handling, and data processing
64

65
## Capabilities
66

67
### Core Parsing
68

69
Primary DDL parsing functionality that converts SQL DDL statements into structured dictionaries. Handles tables, columns, constraints, indexes, and other database objects with full metadata extraction.
70

71
```python { .api }
72
class DDLParser:
73
    def __init__(
74
        self,
75
        content: str,
76
        silent: bool = True,
77
        debug: bool = False,
78
        normalize_names: bool = False,
79
        log_file: Optional[str] = None,
80
        log_level: Union[str, int] = logging.INFO
81
    ): ...
82
    
83
    def run(
84
        self,
85
        *,
86
        dump: bool = False,
87
        dump_path: str = "schemas",
88
        file_path: Optional[str] = None,
89
        output_mode: str = "sql",
90
        group_by_type: bool = False,
91
        json_dump: bool = False
92
    ) -> List[Dict]: ...
93

94
def parse_from_file(
95
    file_path: str,
96
    encoding: Optional[str] = "utf-8",
97
    parser_settings: Optional[dict] = None,
98
    **kwargs
99
) -> List[Dict]: ...
100
```
101

102
[Core Parsing](./core-parsing.md)
103

104
### Input Dialect Support  
105

106
Specialized parsing logic for different SQL database dialects, handling syntax variations and database-specific features like data types, functions, and DDL extensions.
107

108
```python { .api }
109
# Available input dialects (classes from simple_ddl_parser.dialects)
110
class BaseSQL: ...
111
class MySQL: ...
112
class PSQL: ...  # PostgreSQL
113
class MSSQL: ...  # Microsoft SQL Server
114
class Oracle: ...
115
class HQL: ...  # Hive Query Language
116
class BigQuery: ...
117
class Redshift: ...
118
class Snowflake: ...
119
class SparkSQL: ...
120
class IBMDb2: ...
121
class Athena: ...
122
```
123

124
[Input Dialects](./input-dialects.md)
125

126
### Output Formatting
127

128
Convert parsed DDL metadata back into formatted SQL DDL statements optimized for specific database platforms, with dialect-specific syntax and conventions.
129

130
```python { .api }
131
# Available output modes
132
supported_dialects: Dict[str, Any]  # Maps dialect names to output classes
133

134
def dialects_clean_up(output_mode: str, table_data) -> Dict: ...
135
```
136

137
[Output Formatting](./output-formatting.md)
138

139
### Command Line Interface
140

141
CLI tool accessible via the `sdp` command for processing DDL files from the command line with various output options and batch processing capabilities.
142

143
```python { .api }
144
def main(): ...  # Main CLI entry point (exposed as 'sdp' command)
145
def cli(): ...  # Create argument parser
146
def run_for_file(args): ...
147
def correct_extension(file_name: str) -> bool: ...
148
```
149

150
[Command Line Interface](./cli.md)
151

152
### Exception Handling
153

154
Comprehensive error handling and exception classes for robust DDL parsing with detailed error reporting and debugging capabilities.
155

156
```python { .api }
157
class SimpleDDLParserException(Exception): ...
158
DDLParserError = SimpleDDLParserException  # Alias for backward compatibility
159
```
160

161
[Exception Handling](./exceptions.md)
162

163
## Types
164

165
```python { .api }
166
# Core type aliases and return types
167
List[Dict]  # Main return type for parsed DDL structures
168
Dict  # Individual table/entity metadata structure
169
Optional[str]  # Optional string parameters
170
Union[str, int]  # Flexible parameter types for logging levels
171
```