PostgreSQL DDL Parser from Scratch: The Architecture Behind Schema Weaver's SQL Parser v4
Every database tool that visualizes schemas, plans migrations, or powers AI agents needs to understand SQL structure. Most reach for libpg_query — a C extension that doesn't run in browsers. We built a pure TypeScript DDL parser from scratch that handles 60+ statement types across PostgreSQL 12–19, detects 11 relationship types, runs in the browser with zero dependencies, and passes 378 tests against 3,373 brutal SQL statements. This is the complete architecture — the 6-phase pipeline, the multi-strategy parser, and every design decision that makes it work.

Every database tool that visualizes schemas, plans migrations, or powers AI agents needs to understand SQL structure. Most reach for libpg_query — a C extension that compiles PostgreSQL's own parser into a WebAssembly module. It works, but it doesn't run natively in browsers, it brings a 2MB WASM payload, and it gives you a raw parse tree that still needs hundreds of lines of traversal to extract anything useful. We built a pure TypeScript DDL parser from scratch that handles 60+ statement types across PostgreSQL 12 through 19, detects 11 relationship types, runs in the browser with zero dependencies, and passes 378 tests against 3,373 brutal SQL statements. This is the complete architecture.
The Schema Weaver SQL Editor needs to understand your database schema before it can render ER diagrams, plan migrations, or let the AI agent reason about your tables. That understanding starts with parsing — transforming raw SQL DDL into a structured object model that the rest of the system can work with. This parser is the foundation that everything else is built on. If it fails, the ER diagram is wrong, the migration breaks, and the AI hallucinates. So we built it to never fail — or at least, to fail gracefully and tell you exactly what it couldn't understand.
1. Why We Built Our Own Parser
Before writing a single line of the parser, we evaluated every existing option. The PostgreSQL ecosystem has a few approaches to DDL parsing, and each one has a fundamental limitation that made it unsuitable for what Schema Weaver needs.
| Approach | Why It Falls Short |
|---|---|
| libpg_query (WASM) | 2MB WASM payload. Raw Postgres parse tree — not a schema model. Requires 500+ lines of traversal to extract table columns. No browser-native path without the WASM overhead. |
| node-sql-parser | Multi-database abstractions mean PostgreSQL-specific syntax is partially supported. No PG18 temporal tables. No PG19 property graphs. No relationship detection. |
| regex-only parsing | Fragile on nested structures. Breaks on dollar-quoted function bodies. No error recovery. No confidence scoring. No way to handle edge cases systematically. |
| pg_dump + information_schema | Requires a live database connection. Can't parse SQL files directly. No offline mode. No version-specific handling. Not an option for a browser-based tool. |
The fundamental problem: Schema Weaver is a browser-based tool. Users write SQL in the editor, and the parser needs to understand that SQL immediately — without a database connection, without a server round-trip, and without a 2MB WASM download. The parser needs to run in the same Vite application that renders the editor, produce a structured schema object that feeds ER diagrams and migration planning, and handle every PostgreSQL version from 12 to 19 including bleeding-edge features like temporal tables and property graphs.
No existing solution does all of that. So we built one.
2. The 6-Phase Pipeline
The parser processes raw SQL through six sequential phases. Each phase has a single responsibility, a well-defined input type, and a well-defined output type. This separation is not aesthetic — it is survival. In earlier versions, the parser was a monolith. Adding support for a new statement type meant editing the tokenizer, the splitter, and the parser in the same file. A bug in index parsing broke table parsing. The 6-phase split was the result of repeated failures in the monolith approach, and it has held up through four major versions.
tokenizer.ts"] end subgraph "Phase 2" S["Statement Splitter
statement-splitter.ts"] end subgraph "Phase 3" R{"Type Router"} AST["AST Strategy
strategy-ast.ts"] RX["Regex Strategy
strategy-regex.ts
+ 46 parser files"] end subgraph "Phase 4" C["ParseContext
Symbol Table + Dependency Graph"] end subgraph "Phase 5" REL["Relationship Detectors
11 detection modules"] end subgraph "Phase 6" B["Output Builder
schema-builder.ts"] end INPUT["Raw SQL DDL"] --> T T -->|"Token[]"| S S -->|"StatementInfo[]"| R R -->|"Tables, Views, Functions, Enums"| AST R -->|"Indexes, Triggers, Policies, Types"| RX R -->|"AST Failed"| RX AST -->|"AstParseResult"| C RX -->|"RegexParseResult"| C C --> REL REL --> B B --> OUTPUT["ParsedSchema"] style INPUT fill:#6c63ff,color:#fff,stroke:none style OUTPUT fill:#6c63ff,color:#fff,stroke:none style T fill:#00d4ff,color:#1a1d2e,stroke:none style S fill:#00e676,color:#1a1d2e,stroke:none style R fill:#ff9100,color:#fff,stroke:none style AST fill:#00d4ff,color:#1a1d2e,stroke:none style RX fill:#ffd740,color:#1a1d2e,stroke:none style C fill:#6c63ff,color:#fff,stroke:none style REL fill:#ff4081,color:#fff,stroke:none style B fill:#ffd740,color:#1a1d2e,stroke:none
Raw SQL enters at Phase 1 and flows through each phase in sequence. The critical design decision is in Phase 3: the multi-strategy parser. Rather than committing to a single parsing approach, the router dispatches each statement to the strategy most likely to succeed for its type — AST-first for some, regex-first for others, with automatic fallback when the primary strategy fails. This is the core innovation that gives us both depth and resilience.
3. Phase 1: The Tokenizer
The tokenizer converts raw SQL into a stream of typed tokens. It is a character-by-character state machine that tracks nesting depth, recognizes PostgreSQL-specific constructs, and handles every edge case that makes SQL lexing harder than it looks. The tokenizer is the only phase that sees the raw SQL string — everything downstream operates on the token stream, which means the tokenizer has to get the hard parts right so the rest of the pipeline never has to think about them again.
The hard parts are specific to PostgreSQL. Dollar-quoted strings like $$ body $$ or $tag$ body $tag$ are atomic — their contents are not tokenized. Nested block comments like /* outer /* inner */ still outer */ require a depth counter instead of the naive "find first */" approach. Multi-character operators like ::, ->>, and !~* need to be recognized as single tokens rather than sequences of individual characters. The tokenizer handles all of these with a state machine that processes one character at a time, maintaining context about whether it is inside a string, a comment, a dollar-quoted region, or an operator.
| Token Type | Example | Description |
|---|---|---|
| KEYWORD | CREATE, TABLE, PRIMARY |
Reserved SQL keywords |
| IDENTIFIER | users, my_table |
Unquoted identifiers |
| QUOTED_IDENTIFIER | "MyTable" |
Double-quoted identifiers |
| DOLLAR_STRING | $$ body $$ |
Dollar-quoted function bodies (atomic) |
| OPERATOR | ::, ->>, !~* |
Multi-character SQL operators |
| COMMENT | -- comment, /* block */ |
Comments (preserved or filtered) |
The tokenizer's error handling is worth noting. Unclosed quotes produce a specific error with line and column information — not a generic "parse failed" message. Dollar-quoted strings are treated as atomic units, so a function body containing SQL keywords or semicolons is never accidentally tokenized. Nested comments are tracked via a depth counter, preventing premature termination when an inner comment closes before the outer one. These details matter because real-world SQL dumps from pg_dump contain all of these edge cases simultaneously.
4. Phase 2: The Statement Splitter
Once the SQL is tokenized, the next challenge is splitting the token stream into individual statements. This sounds trivial — just split on semicolons — until you realize that semicolons appear inside function bodies, dollar-quoted strings, and BEGIN ATOMIC ... END blocks (the PG14+ inline function syntax). A naive split breaks every function definition into fragments.
The splitter solves this by tracking three types of nesting simultaneously: parenthesis depth (...), BEGIN ATOMIC ... END blocks, and dollar-quoted regions. A semicolon is only treated as a statement separator when all three depths are zero. This means a function body like CREATE FUNCTION foo() RETURNS void AS $$ BEGIN INSERT INTO bar VALUES (1); END; $$ LANGUAGE plpgsql; is correctly identified as a single statement, not split at the semicolons inside the dollar-quoted body.
Each resulting StatementInfo carries more than just the text. The splitter also identifies the statement type via keyword pattern matching on the first six keywords — distinguishing between CREATE TABLE, CREATE TABLE ... PARTITION OF, CREATE OR REPLACE FUNCTION, CREATE UNIQUE INDEX, and 60+ other variants. It also extracts the namespace (schema.objectName) and dependencies upfront — foreign key references, partition parents, inheritance targets, and function call dependencies — so the relationship detectors in Phase 5 don't have to re-parse the SQL.
// Pattern matching on first 6 keywords:
'CREATE TABLE' → 'CREATE_TABLE'
'CREATE TABLE ... PARTITION OF' → 'CREATE_TABLE_PARTITION'
'CREATE OR REPLACE FUNCTION' → 'CREATE_FUNCTION'
'CREATE UNIQUE INDEX' → 'CREATE_INDEX'
'ALTER TABLE' → 'ALTER_TABLE'
// ... 60+ statement types
5. The Multi-Strategy Parser
This is the core innovation. Rather than committing to a single parsing approach for all statement types, the parser uses two complementary strategies that compensate for each other's weaknesses. The router in Phase 3 dispatches each statement to the strategy most likely to succeed for its type, with automatic fallback when the primary strategy fails.
5.1 Strategy A: The Direct AST Parser
The AST parser is a comprehensive regex-based parser for standard DDL patterns. Despite the name, it doesn't build a traditional abstract syntax tree — instead, it uses structured pattern matching to extract fields from cleaned SQL. It handles CREATE TABLE, CREATE VIEW, CREATE FUNCTION, CREATE ENUM, CREATE SEQUENCE, and CREATE EXTENSION — the statement types where the structure is well-defined and the regex patterns can be precise.
The AST parser produces detailed results with high confidence scores: 0.90 for tables, 0.95 for indexes, 0.95 for enums, and 1.00 for extensions. Its weakness is malformed SQL — if the input doesn't match the expected pattern, it fails rather than producing partial output. This is where Strategy B comes in.
5.2 Strategy B: The Regex Fallback
The regex fallback is a collection of 46 specialized parser files that use targeted pattern matching for specific syntax. It is deliberately more tolerant than the AST parser — it can extract data from malformed SQL, it handles syntax variations that the AST parser doesn't anticipate, and it is easy to extend for new PostgreSQL features without modifying the core pipeline.
The regex strategy is preferred for certain statement types where PostgreSQL syntax is inherently complex: CREATE INDEX (partial indexes, covering indexes, operator classes), CREATE TRIGGER (complex REFERENCING clauses), CREATE POLICY (USING/WITH CHECK expressions), CREATE TYPE (ENUM, composite), CREATE DOMAIN (custom constraints), and CREATE AGGREGATE (specialized syntax). For these types, the regex patterns are more precise than the AST approach because they can handle the specific variations without the overhead of a general-purpose parser.
5.3 The Decision Flow
CREATE_TRIGGER,
CREATE_POLICY,
CREATE_TYPE,
CREATE_DOMAIN,
CREATE_AGGREGATE"| REGEX_FIRST["Try Regex FIRST"] CHECK -->|"CREATE_TABLE,
CREATE_VIEW,
CREATE_FUNCTION,
CREATE_ENUM,
CREATE_SEQUENCE,
CREATE_EXTENSION"| AST_FIRST["Try AST FIRST"] REGEX_FIRST --> RS{"Regex Success?"} RS -->|"Yes"| MERGE["Merge Result into Context"] RS -->|"No"| TRY_AST["Try AST Parser"] AST_FIRST --> AS{"AST Success?"} AS -->|"Yes"| MERGE AS -->|"No"| TRY_REGEX["Try Regex Parser"] TRY_AST --> TAS{"AST Success?"} TAS -->|"Yes"| MERGE TAS -->|"No"| WARN["Emit INCOMPLETE_PARSE Warning"] TRY_REGEX --> TRS{"Regex Success?"} TRS -->|"Yes"| MERGE TRS -->|"No"| WARN WARN --> SKIP["Skip Statement, Continue"] MERGE --> NEXT["Process Next Statement"] SKIP --> NEXT style START fill:#6c63ff,color:#fff,stroke:none style CHECK fill:#ff9100,color:#fff,stroke:none style MERGE fill:#00e676,color:#1a1d2e,stroke:none style WARN fill:#ff4081,color:#fff,stroke:none style SKIP fill:#ff5252,color:#fff,stroke:none
The decision logic is deterministic and fast. For each statement, the router checks the statement type, dispatches to the appropriate primary strategy, and falls back to the alternative if the primary fails. If both strategies fail, the parser emits an INCOMPLETE_PARSE warning and moves to the next statement. It never throws, it never crashes, and it never stops processing the rest of the file because one statement couldn't be understood.
const regexFirstTypes: StatementType[] = [
'CREATE_INDEX',
'CREATE_TRIGGER',
'CREATE_POLICY',
'CREATE_TYPE',
'CREATE_DOMAIN',
'CREATE_AGGREGATE',
];
if (regexFirstTypes.includes(stmt.type)) {
const regexResult = tryRegexParse(stmt, context);
if (regexResult.success) {
mergeRegexResult(regexResult, context);
return;
}
const astResult = tryAstParse(stmt, context);
if (astResult.success) {
mergeAstResult(astResult, context);
return;
}
} else {
const astResult = tryAstParse(stmt, context);
if (astResult.success) {
mergeAstResult(astResult, context);
return;
}
const regexResult = tryRegexParse(stmt, context);
if (regexResult.success) {
mergeRegexResult(regexResult, context);
return;
}
}
// Both failed - emit warning, continue
context.addWarning({
level: 'WARNING',
code: 'INCOMPLETE_PARSE',
message: `Could not parse statement: ${stmt.text.slice(0, 100)}...`,
});
CREATE INDEX may be detected but its WHERE clause lost. Always check result.confidence and result.errors on the output. Low confidence means the parser extracted the skeleton but may have dropped details.
6. The Parser Catalog
The parser ships with 46 individual parser files, each handling a specific statement type or variant. This is not over-engineering — each parser encapsulates domain knowledge about a specific PostgreSQL syntax that would be impossible to handle with a single general-purpose approach. The table parser alone handles partitioning, inheritance, temporal periods, row-level security, storage parameters, and 50+ ALTER TABLE sub-commands. Trying to squeeze all of that into one file produced unmaintainable code in earlier versions.
| Parser | Statement Types | Confidence |
|---|---|---|
| table-parser.ts | CREATE TABLE, CTAS, PARTITION OF | 0.90 |
| view-parser.ts | CREATE VIEW, MATERIALIZED VIEW (catch-all fallback) | 0.80 |
| index-parser.ts | CREATE INDEX, UNIQUE, CONCURRENTLY, partial, covering | 0.95 |
| function-parser.ts | CREATE FUNCTION, PROCEDURE, OR REPLACE | 0.75 |
| trigger-parser.ts | CREATE TRIGGER, CONSTRAINT TRIGGER | 0.85 |
| alter-table-parser.ts | 50+ ALTER TABLE sub-commands | 0.80 |
| property-graph-parser.ts | CREATE PROPERTY GRAPH (PG19 SQL/PGQ) | 0.85 |
| temporal-parser.ts | PERIOD, SYSTEM_VERSIONING (PG18) | 0.90 |
| drop-parser.ts | 35+ DROP statement variants | 0.95 |
Many parsers have -extended variants that add enhanced extraction on top of the base parser. The view-extended-parser.ts handles column lists and WITH options. The function-extended-parser.ts captures strict mode, transforms, and window/aggregate flags. The role-extended-parser.ts parses IN ROLE, ROLE, ADMIN memberships and SETTINGS. The extended variants run after the base parser, filling in fields that the base parser left empty. This layered approach means we can add new extraction capabilities without risking regressions in the core parsing logic.
7. Relationship Detection
Parsing individual SQL statements is only half the problem. The other half is understanding how those statements relate to each other — which tables reference which other tables, which views depend on which tables, which triggers call which functions. Without relationships, you have a list of objects. With relationships, you have a schema graph — the data structure that powers ER diagrams, dependency-aware migration ordering, and the AI agent's understanding of how your database is connected.
The relationship detection phase runs 11 specialized detectors, each identifying a specific type of relationship. The detectors operate on the ParseContext — a symbol table that contains all parsed objects and their cross-references. The symbol table is built incrementally during Phase 3, and the relationship detectors use it to resolve references across statements.
FOREIGN_KEY"] PART["partition-detector.ts
PARTITION_CHILD/PARENT"] INH["inheritance-detector.ts
INHERITANCE"] VD["view-dependencies.ts
VIEW_DEPENDENCY"] TB["trigger-bindings.ts
TRIGGER_TARGET/FUNCTION"] SEQ["sequence-ownership.ts
HAS_SEQUENCE"] PG["property-graph-relations.ts
VERTEX/EDGE"] TEMP["temporal-relations.ts
TEMPORAL_FK/PERIOD"] POL["Policy Detection
POLICY_TARGET"] CALL["Call Detection
CALLS"] DEP["Extension Dependencies
DEPENDS_ON"] end CTX["ParseContext
(Symbol Table)"] --> FK CTX --> PART CTX --> INH CTX --> VD CTX --> TB CTX --> SEQ CTX --> PG CTX --> TEMP FK --> OUT["Relationship[]"] PART --> OUT INH --> OUT VD --> OUT TB --> OUT SEQ --> OUT PG --> OUT TEMP --> OUT POL --> OUT CALL --> OUT DEP --> OUT style CTX fill:#6c63ff,color:#fff,stroke:none style OUT fill:#00e676,color:#1a1d2e,stroke:none
Each relationship carries a confidence score and a source type that indicates how the relationship was detected. EXPLICIT_FK means the relationship was found via an explicit REFERENCES clause — the highest confidence. INFERRED_VIEW means the relationship was inferred from analyzing a view's query — lower confidence because query analysis is heuristic. PARSER_MATCH means the regex or AST parser identified the relationship directly. These distinctions matter for downstream consumers: the ER diagram renderer might only show explicit foreign keys, while the AI agent might use all relationship types including inferred ones.
| Type | Source → Target | Detection Method |
|---|---|---|
| FOREIGN_KEY | Column → Column | Explicit REFERENCES |
| PARTITION_CHILD | Table → Table | PARTITION OF clause |
| INHERITANCE | Table → Table | INHERITS clause |
| VIEW_DEPENDENCY | View → Table | Query analysis |
| TRIGGER_FUNCTION | Trigger → Function | EXECUTE FUNCTION |
| PROPERTY_GRAPH_VERTEX | Graph → Table | Vertex table mapping |
| TEMPORAL_FK | Column → Column | PERIOD FK constraints |
8. PG12 to PG19: Eight Versions, One Parser
PostgreSQL adds features in every major release, and the parser needs to handle all of them. This is not just about recognizing new keywords — it is about understanding how new syntax constructs interact with existing ones. For example, PG15 added NULLS NOT DISTINCT for unique indexes, which changes how the index parser needs to handle the UNIQUE keyword. PG18 added temporal tables with PERIOD clauses and WITH SYSTEM VERSIONING, which changes how the table parser handles constraints. PG19 added property graphs via SQL/PGQ, which is an entirely new DDL category that didn't exist before.
The parser handles all of this through version-aware pattern matching. Each parser file includes logic for version-specific syntax, and the parser produces appropriate errors or warnings when it encounters syntax that doesn't match the expected version range. A CREATE PROPERTY GRAPH statement in a file tagged as PG16 will parse successfully (the parser doesn't enforce version constraints at parse time) but will produce a suggestion-level warning that this syntax requires PG19.
| Feature | PG12 | PG13 | PG14 | PG15 | PG16 | PG17 | PG18 | PG19 |
|---|---|---|---|---|---|---|---|---|
| Covering Indexes (INCLUDE) | Y | Y | Y | Y | Y | Y | Y | Y |
| SQL Standard Function Bodies | N | N | Y | Y | Y | Y | Y | Y |
| NULLS NOT DISTINCT | N | N | N | Y | Y | Y | Y | Y |
| MERGE/SPLIT Partitions | N | N | N | N | N | Y | Y | Y |
| Temporal Tables (PERIOD) | N | N | N | N | N | N | Y | Y |
| Property Graphs (SQL/PGQ) | N | N | N | N | N | N | N | Y |
9. Error Handling: Never Throw
The parser follows a graceful degradation model with four principles: never throw on recoverable errors, track all issues in the output, attach confidence scores to every object, and support multiple recovery modes. This is a deliberate design choice that reflects how the parser is used in production — it processes SQL files that may be incomplete, may contain syntax errors, and may use features the parser hasn't seen yet. The parser's job is to extract as much useful information as possible and report what it couldn't understand, not to act as a SQL validator.
Every error carries a level (ERROR, WARNING, SUGGESTION, INFO) and a structured error code (PARSE_ERROR, FK_UNRESOLVED, INCOMPLETE_PARSE, etc.). The confidence score on each parsed object ranges from 0.0 to 1.0 — a table parsed from a clean CREATE TABLE statement scores 0.90, while a table extracted via regex fallback from malformed SQL might score 0.50. Downstream consumers can use these scores to decide whether to trust the output or flag it for manual review.
const result = parsePostgresSQL(sql);
// 1. Check for critical errors
if (result.errors.filter(e => e.level === 'ERROR').length > 0) {
console.error('Parse failed:', result.errors);
}
// 2. Check confidence
if (result.confidence < 0.8) {
console.warn('Low confidence parse:', result.confidence);
}
// 3. Check warnings for partial parses
const partialParses = result.warnings.filter(
w => w.code === 'INCOMPLETE_PARSE'
);
// 4. Check individual object confidence
const lowConfidenceTables = result.tables.filter(
t => t.confidence < 0.8
);
The recovery modes are worth understanding because they determine how the parser behaves when things go wrong. SKIP_TOKEN advances past a single unexpected token and continues. SKIP_STATEMENT abandons the current statement entirely and moves to the next one. SKIP_CONSTRUCT abandons the current nested construct (like a constraint or column definition) but continues with the enclosing statement. CONTINUE means the parser recovered without losing any meaningful information. These modes are selected automatically based on the error type and position, and they are recorded in the error's recovery field so downstream code can understand what happened.
10. The Output: ParsedSchema
The final output of the parser is a ParsedSchema object — a single typed structure that contains everything the parser discovered about your SQL. This is the data structure that feeds the ER diagram renderer, the migration planner, the AI agent's context builder, and every other consumer in the Schema Weaver system. Its design reflects a principle we learned the hard way: the output format should be stable even when the parser internals change. Downstream code depends on the shape of ParsedSchema, not on how the parser produces it.
The PostgresStats object is worth highlighting. It is a computed summary that includes the count of each data type category across all columns, the number of primary keys, foreign keys, unique constraints, check constraints, not-null constraints, generated columns, default values, partitioned tables, child partitions, temporary tables, inherited tables, RLS policies, and temporal constraints. This summary powers the schema overview panel in the SQL Editor and gives the AI agent a quick statistical picture of the database without having to iterate through every object.
interface ParsedSchema {
tables: Table[];
relationships: Relationship[];
enumTypes: EnumType[];
views: View[];
triggers: Trigger[];
indexes: Index[];
sequences: Sequence[];
functions: PostgresFunction[];
policies: Policy[];
extensions: Extension[];
schemas: string[];
domains: Domain[];
compositeTypes: CompositeType[];
roles: Role[];
rules: Rule[];
aggregates?: Aggregate[];
propertyGraphs?: PropertyGraph[];
stats: PostgresStats;
errors: ParserError[];
warnings: ParserError[];
parseTime?: number;
confidence: number;
}
11. Performance and Testing
The parser processes 3,373 SQL statements across 15 brutal test fixtures with a 100% pass rate across 378 tests. The test suite is organized into five categories: unit tests for individual components, edge case tests for specific feature areas, end-to-end tests that parse complete schemas, stress tests for performance and memory, and brutal tests that throw hostile SQL at the parser to verify it doesn't crash. The brutal tests are the most important — they include version-specific SQL files for every PostgreSQL version from 12 to 19, combinatorial explosions of nested syntax, malformed SQL with unclosed quotes and missing semicolons, and realistic pg_dump output from multi-version databases.
| Metric | Value |
|---|---|
| Total Test Suites | 26 suites |
| Total Tests | 378 tests |
| Pass Rate | 100% |
| Brutal SQL Files | 15 files |
| Total Statements Tested | 3,373 |
| E-commerce fixture (~800 stmts) | <500ms, <50MB |
| SaaS platform fixture (~1000 stmts) | <750ms, <75MB |
| Temporal-graph fixture (~1200 stmts) | <1000ms, <100MB |
The performance characteristics are predictable because every phase has known time complexity. The tokenizer is O(n) — single pass over the SQL string. The statement splitter is O(n) — single pass over the token stream. The parser is O(n x m) — n statements times m pattern matches per type. The relationship builder is O(t-squared) — t tables for foreign key resolution. The output builder is O(t + i + v) — linear over all objects. For most real-world schemas, the total parse time is dominated by the parser phase, and the total is well under one second for schemas with hundreds of tables.
Memory usage is bounded at approximately 5-10x the input SQL size, with the token stream consuming about 10 bytes per token. The parser runs identically in the browser and in Node.js — there are no platform-specific optimizations, no filesystem access, and no native modules. The browser is the primary deployment target, and every design decision prioritizes keeping the parser lightweight enough to run in a Vite application without blocking the main thread.
12. Open Source: pg-ddl-parser
The parser is open source and available now. Install it from npm, browse the source on GitHub, or try it live in the Schema Weaver SQL Editor.
npm install pg-ddl-parser
The public API surface is intentionally minimal — one main function (parsePostgresSQL) that takes a SQL string and returns a ParsedSchema, plus individual exports for the tokenizer, splitter, and parse context for advanced use cases. The package supports tree-shaking, ships with ESM and CJS dual output, and includes full TypeScript type definitions.
// Main export - parse everything
import { parsePostgresSQL } from 'pg-ddl-parser';
const result = parsePostgresSQL(sql);
console.log(result.tables); // [{ name: 'users', columns: [...], ... }]
console.log(result.relationships); // [{ type: 'FOREIGN_KEY', source: ..., target: ... }]
console.log(result.confidence); // 0.95
// Advanced: use individual phases
import { tokenize } from 'pg-ddl-parser';
import { splitStatements } from 'pg-ddl-parser';
import { createParseContext } from 'pg-ddl-parser';
// Type-only imports (tree-shakeable)
import type { Table, Index, Relationship } from 'pg-ddl-parser';
Open-sourcing the parser is a trust decision. Schema Weaver is a database tool — users need to trust that their SQL is being handled correctly and that nothing unexpected is happening to their schema definitions. Open source means you can verify exactly what the parser does with your SQL. It also means the parser benefits from the community's collective experience with PostgreSQL edge cases that we haven't encountered yet. If you find a statement that doesn't parse correctly, open an issue on GitHub or fix it yourself instead of waiting for us.
result.errors and result.confidence — the parser will tell you exactly what it couldn't understand. Star us on GitHub if you find it useful.
13. Design Philosophy
Three principles guided every decision in this parser, and they are worth stating explicitly because they are the reasons the parser works where simpler approaches fail.
Principle 1: Zero runtime dependencies. The parser is pure TypeScript with no external dependencies. It runs in the browser and in Node.js without any build step, any WASM compilation, or any native module loading. This was non-negotiable for Schema Weaver — the parser runs in the same Vite application as the editor, and a 2MB WASM payload or a native module requirement would break the deployment model. The tradeoff is that the parser doesn't use PostgreSQL's own parser via libpg_query, which means it can't handle every possible SQL variation. The multi-strategy approach compensates for this.
Principle 2: Graceful degradation over correctness. A SQL validator that rejects invalid input is useless for a tool that processes real-world SQL dumps. Real SQL files contain syntax errors, version-incompatible statements, and creative uses of PostgreSQL features that no specification documents. The parser's job is to extract as much useful information as possible and report what it couldn't understand, not to act as a gatekeeper. Every parsed object carries a confidence score, and every error carries a structured code and recovery mode.
Principle 3: Partial output is always better than no output. If a file contains 100 statements and 3 of them fail to parse, the parser returns 97 parsed objects and 3 error entries. It never discards successful parses because of downstream failures. It never throws an exception that stops processing the rest of the file. It never returns an empty result because one statement was malformed. This principle is what makes the parser usable in production — real SQL is messy, and the parser handles that mess gracefully.



