@dbml/core 5.3.0 → 5.4.0

package/lib/parse/ANTLR/ASTGeneration/mysql/README.md

@@ -1,157 +1,262 @@
-# MySQL model structure generator
-
-This folder houses the implementation of the MySQL model structure generator based on the ANTLR4 parser.
-
-This file documents the current features and bugs of this model structure generator.
-
-In the below table, the following notation is used:
-  - ✅: Supported.
-  - 🤷🏼‍♂️: Invalid SQL in MySQL.
-  - ❓: Valid SQL in MySQL, the generator can still generate output but it ignores this syntax.
-  - ❌: Valid SQL in MySQL, but the generator fails to generate any output.
-
-| SQL syntax                    | MySQL         |
-|-------------------------------|---------------|
-| 1. INSERT statement           |           |
-| 1.a. Basic INSERT ... VALUES  | ✅            |
-| 1.b. INSERT ... SELECT        | ❌            |
-| 1.c. Multi-row INSERT         | ✅            |
-| 1.d. Common table expression (WITH clause) | ❌            |
-| 1.e. Target table alias       | 🤷🏼‍♂️         |
-| 1.f. INSERT ... RETURNING/INSERT … OUTPUT | 🤷🏼‍♂️         |
-| 1.g. INSERT ... ON CONFLICT (UPSERT)/INSERT ... ON DUPLICATE KEY/INSERT … IGNORE | ❓ (ignore the ON DUPLICATE KEY and IGNORE clauses) |
-| 1.h. INSERT OVERWRITE         | 🤷🏼‍♂️         |
-| 1.i. Multi-table INSERT       | ❌            |
-| 1.j. Conditional multi-table INSERT (WHEN/FIRST/ALL) | ❌            |
-| 6. CREATE TABLE               |           |
-| 6.a. Basic syntax             | ✅            |
-| 6.a.i. Enumerated data type   | 🤷🏼‍♂️         |
-| 6.a.ii. Data type of the form name(...) | ✅            |
-| 6.a.iii. Data type of the form name\[...\] | 🤷🏼‍♂️         |
-| 6.b. PRIMARY KEY              |               |
-| 6.b.i. Inline PRIMARY KEY     | ✅            |
-| 6.b.ii. Out-of-line PRIMARY KEY | ✅            |
-| 6.b.iii. Composite PRIMARY KEY | ✅            |
-| 6.b.iv. Named PRIMARY KEY     | ✅            |
-| 6.b.v. Other options (deferrable, etc.) | ❓ (ignore the options) |
-| 6.c. FOREIGN KEY              |               |
-| 6.c.i. Inline FOREIGN KEY     | ✅            |
-| 6.c.ii. Out-of-line FOREIGN KEY | ✅            |
-| 6.c.iii. Composite FOREIGN KEY | ✅            |
-| 6.c.iv. Named FOREIGN KEY     | ✅            |
-| 6.c.v. ON UPDATE              | ✅            |
-| 6.c.vi. ON DELETE             | ✅            |
-| 6.c.vii. Other options (deferrable, etc.) | ❓ (ignore the options) |
-| 6.d. UNIQUE                   |               |
-| 6.d.i. Inline UNIQUE          | ✅            |
-| 6.d.ii. Out-of-line UNIQUE    | ✅            |
-| 6.d.iii. Composite UNIQUE     | ✅            |
-| 6.d.iv. Named UNIQUE          | ✅            |
-| 6.d.v. Other options (deferrable, etc) | ❓ (ignore the option) |
-| 6.d.vi. NULLS NOT DISTINCT    | ❌ (parse fail) |
-| 6.d.vii. UNIQUE KEY/UNIQUE INDEX | ✅            |
-| 6.e. CHECK                    |               |
-| 6.e.i. Inline CHECK           | ✅            |
-| 6.e.ii. Out-of-line CHECK     | ✅            |
-| 6.e.iii. Named CHECK          | ✅ (ignored for inline checks) |
-| 6.e.iv. Other options (enforcement control, etc.) | ❓ (ignore the options) |
-| 6.f. DEFAULT values           |               |
-| 6.f.i. Inline DEFAULT         | ✅            |
-| 6.f.ii. Out-of-line DEFAULT   | 🤷🏼‍♂️         |
-| 6.f.iii. Functional DEFAULT   | ✅            |
-| 6.f.iv. Named DEFAULT         | 🤷🏼‍♂️         |
-| 6.g. NULL                     | ✅            |
-| 6.h. NOT NULL                 |               |
-| 6.h.i. Inline NOT NULL        | ✅            |
-| 6.h.ii. Out-of-line NOT NULL  | 🤷🏼‍♂️         |
-| 6.h.iii. Named NOT NULL       | 🤷🏼‍♂️         |
-| 6.h.iv. Other options (deferrable, etc.) | ❓ (ignore) |
-| 6.i. Indexes                  |               |
-| 6.i.i. Inline indexes         | ❌ (parse fail) |
-| 6.i.ii. Out-of-line indexes   | ✅            |
-| 6.i.iii. Named indexes        | ✅            |
-| 6.i.iv. Multi-column indexes  | ✅            |
-| 6.i.v. CLUSTERED/NONCLUSTERED | 🤷🏼‍♂️         |
-| 6.i.vi. FULLTEXT              | ❓ (ignore) |
-| 6.i.vii. SPATIAL              | ❓ (ignore) |
-| 6.i.viii. Other options       | ❓ (ignore) |
-| 6.i.ix. USING HASH/BTREE      | ✅            |
-| 6.j. Auto-increment           |               |
-| 6.j.i. AUTO_INCREMENT         | ✅            |
-| 6.j.ii. SERIAL/BIG SERIAL     | 🤷🏼‍♂️         |
-| 6.j.iii. IDENTITY             | 🤷🏼‍♂️         |
-| 6.j.iv. Increment range       | ❓ (ignore) |
-| 6.j.v. GENERATED ... AS IDENTITY | 🤷🏼‍♂️         |
-| 6.k. Computed column          | ❓            |
-| 6.l. TEMPORARY tables         | ❌ (Totally ignored) |
-| 6.m. CREATE TABLE AS SELECT (CTAS) | ❌            |
-| 6.n. Comments                 |               |
-| 6.n.i. Table comments         | ✅            |
-| 6.n.ii. Column comments       | ✅            |
-| 6.o. Other options (inheritance, UNLOGGED, partition, collate, etc.) | ❓            |
-| 7. ALTER TABLE                |           |
-| 7.a. ADD COLUMN               |               |
-| 7.a.i. Type                   | ❌            |
-| 7.a.ii. DEFAULT               | ❌            |
-| 7.a.iii. NOT NULL             | ❌            |
-| 7.a.iv. NULL                  | ❌            |
-| 7.a.v. CHECK                  | ❌            |
-| 7.a.vi. UNIQUE                | ❌ (parse fail when giving a name) |
-| 7.a.vii. FOREIGN KEY          | ❌ (parse fail for FOREIGN KEY name REFERENCES ...) |
-| 7.a.viii. PRIMARY KEY         | ❌            |
-| 7.a.ix. AUTOINCREMENT/SERIAL/BIGSERIAL/IDENTITY/GENERATED AS IDENTITY | ❌            |
-| 7.a.x. Computed column        | ❌            |
-| 7.b. DROP COLUMN              | ❌            |
-| 7.c. ALTER COLUMN / MODIFY COLUMN |               |
-| 7.c.i. COMMENT                | ❌            |
-| 7.c.ii. Others                | ❌            |
-| 7.d. RENAME COLUMN            | ❌            |
-| 7.e. ADD CONSTRAINT           |               |
-| 7.e.i. DEFAULT                | ❌ (parse fail) |
-| 7.e.ii. NOT NULL              | ❌            |
-| 7.e.iii. NULL                 | ❌            |
-| 7.e.iv. named CHECK           | ✅            |
-| 7.e.v. unnamed CHECK          | ✅            |
-| 7.e.vi. named UNIQUE          | ❌            |
-| 7.e.vii. unnamed UNIQUE       | ❌            |
-| 7.e.viii. named PRIMARY KEY   | ❓ (ignore name) |
-| 7.e.ix. unnamed PRIMARY KEY   | ✅            |
-| 7.e.x. named FOREIGN KEY      | ✅            |
-| 7.e.xi. unnamed FOREIGN KEY   | ✅            |
-| 7.g. DROP CONSTRAINT          | ❌            |
-| 7.h. ALTER CONSTRAINT         | ❌            |
-| 7.i. RENAME TABLE             | ❌            |
-| 7.j. SET SCHEMA               | ❌            |
-| 7.k. ALTER INDEX              | ❌            |
-| 7.l. DROP INDEX               | ❌            |
-| 7.m. SET COMMENT/COMMENT =    | ❌            |
-| 7.n. ADD INDEX                | ❌            |
-| 8. DROP TABLE                 |           |
-| 8.a. Basic syntax             | ❌            |
-| 9. CREATE INDEX               |           |
-| 9.a. Basic syntax             | ✅            |
-| 9.b. Composite index          | ✅            |
-| 9.c. Named index              | ✅            |
-| 9.d. UNIQUE index             | ✅            |
-| 9.e. Partial/Filtered index   | ❌ (parse fail) |
-| 9.f. BTREE/HASH/GIST/BRIN/… index | ✅            |
-| 9.g. INCLUDE columns          | 🤷🏼‍♂️         |
-| 9.h. CLUSTERED/NONCLUSTERED   | ❓ (ignore) |
-| 9.i. Functional index         | ✅            |
-| 9.j. FULLTEXT/SPATIAL index   | ❓ (ignore) |
-| 9.k. COLLATE                  | ❌ (parse fail) |
-| 9.l. COMMENT                  | ❓ (ignore) |
-| 9.m. NULLS LAST/FIRST         | 🤷🏼‍♂️         |
-| 9.n. ASC/DESC                 | ❓ (ignore) |
-| 10. DROP INDEX                |           |
-| 10.a. Basic syntax            | ❌            |
-| 11. ALTER INDEX               | 🤷🏼‍♂️         |
-| 11.a. RENAME                  | 🤷🏼‍♂️         |
-| 11.b. ALTER COLUMN            | 🤷🏼‍♂️         |
-| 12. CREATE VIEW               |           |
-| 12.a. Basic syntax            | ❌            |
-| 13. Comment                   |               |
-| 13.a. Table comments          | 🤷🏼‍♂️         |
-| 13.b. Column comments         | 🤷🏼‍♂️         |
-| 13.c. COMMENT … IS NULL       | 🤷🏼‍♂️         |
-| 13.d. Index comments          | ❌ (parse fail) |
+# MySQL SQL Parser Support
+
+> Comprehensive documentation for the MySQL model structure generator based on the ANTLR4 parser.
+
+## Overview
+
+This module provides SQL parsing capabilities for MySQL databases, enabling conversion of MySQL DDL statements to DBML format. The parser supports MySQL-specific syntax including `AUTO_INCREMENT` columns, `UNIQUE KEY`/`UNIQUE INDEX` syntax, inline table and column comments, and various index types.
+
+## Support Legend
+
+| Symbol | Meaning |
+|--------|---------|
+| ✓ | Fully supported and correctly parsed |
+| ◐ | Valid SQL that is parsed, but some options/clauses are ignored |
+| ✗ | Valid MySQL syntax, but the parser fails to generate output |
+| — | Syntax not valid in MySQL |
+
+## Key Capabilities
+
+- **Data Definition**
+  - `CREATE TABLE` with full syntax support
+  - Data types: parameterized types (e.g., `VARCHAR(255)`, `DECIMAL(10,2)`)
+- **Constraints**
+  - `PRIMARY KEY` (column-level, table-level, multi-column, with explicit name)
+  - `FOREIGN KEY` with `ON UPDATE` / `ON DELETE` actions
+  - `UNIQUE`, `UNIQUE KEY`, `UNIQUE INDEX`
+  - `CHECK`, `DEFAULT`, `NOT NULL`
+- **Auto-increment**
+  - `AUTO_INCREMENT` column attribute
+- **Indexes**
+  - `CREATE INDEX` with BTREE, HASH
+  - Table-level indexes in `CREATE TABLE`
+  - Function-based indexes
+- **Comments**
+  - Inline `COMMENT` attribute for tables and columns
+- **Data Manipulation**
+  - Basic `INSERT` and multi-row `INSERT`
+
+---
+
+## Feature Support Matrix
+
+### `CREATE TABLE`
+
+| Feature | Status | Notes |
+|---------|---------|-------|
+| Basic `CREATE TABLE` syntax | ✓ | |
+| Enumerated data types (ENUM) | ✓ | MySQL uses inline ENUM type |
+| Parameterized types `name(...)` | ✓ | e.g., `VARCHAR(255)`, `DECIMAL(10,2)` |
+| Array types `name[...]` | — | Not supported in MySQL |
+| TEMPORARY tables | ✗ | Tables are completely ignored |
+| `CREATE TABLE` AS SELECT | ✗ | |
+| Table options (ENGINE, CHARSET, etc.) | ◐ | Options are ignored |
+
+### Constraints
+
+#### `PRIMARY KEY`
+
+| Feature | Status | Notes |
+|---------|---------|-------|
+| Column-level `PRIMARY KEY` | ✓ | `id INT PRIMARY KEY` |
+| Table-level `PRIMARY KEY` | ✓ | `PRIMARY KEY (id)` |
+| Multi-column `PRIMARY KEY` | ✓ | `PRIMARY KEY (a, b)` |
+| Explicitly named (CONSTRAINT name) | ✓ | `CONSTRAINT pk_name PRIMARY KEY (id)` |
+| Index options (USING BTREE, etc.) | ◐ | Options are ignored |
+
+#### `FOREIGN KEY`
+
+| Feature | Status | Notes |
+|---------|---------|-------|
+| Column-level `FOREIGN KEY` | ✓ | `col INT REFERENCES other(id)` |
+| Table-level `FOREIGN KEY` | ✓ | `FOREIGN KEY (col) REFERENCES other(id)` |
+| Multi-column `FOREIGN KEY` | ✓ | `FOREIGN KEY (a, b) REFERENCES other(x, y)` |
+| Explicitly named (CONSTRAINT name) | ✓ | `CONSTRAINT fk_name FOREIGN KEY ...` |
+| `ON UPDATE` action | ✓ | CASCADE, SET NULL, RESTRICT, NO ACTION |
+| `ON DELETE` action | ✓ | CASCADE, SET NULL, RESTRICT, NO ACTION |
+| Index options | ◐ | Options are ignored |
+
+#### `UNIQUE`
+
+| Feature | Status | Notes |
+|---------|---------|-------|
+| Column-level `UNIQUE` | ✓ | `col INT UNIQUE` |
+| Table-level `UNIQUE` | ✓ | `UNIQUE (col)` |
+| Multi-column `UNIQUE` | ✓ | `UNIQUE (a, b)` |
+| Explicitly named (CONSTRAINT name) | ✓ | `CONSTRAINT uq_name UNIQUE (col)` |
+| Index options | ◐ | Options are ignored |
+| NULLS NOT DISTINCT | ✗ | Treats NULLs as equal - parse failure in MySQL |
+| `UNIQUE KEY` / `UNIQUE INDEX` | ✓ | MySQL-specific alternative syntax |
+
+#### `CHECK`
+
+| Feature | Status | Notes |
+|---------|---------|-------|
+| Column-level `CHECK` | ✓ | `col INT CHECK (col > 0)` |
+| Table-level `CHECK` | ✓ | `CHECK (col > 0)` |
+| Explicitly named (CONSTRAINT name) | ✓ | Name ignored for column-level checks |
+| NOT ENFORCED option | ◐ | Enforcement control is ignored |
+
+#### `DEFAULT`
+
+| Feature | Status | Notes |
+|---------|---------|-------|
+| Column-level `DEFAULT` | ✓ | `col INT DEFAULT 0` |
+| Table-level `DEFAULT` | — | MySQL only supports column-level `DEFAULT` |
+| Function as `DEFAULT` | ✓ | `DEFAULT CURRENT_TIMESTAMP`, `DEFAULT UUID()` |
+| Explicitly named `DEFAULT` | — | MySQL doesn't support named `DEFAULT` constraints |
+
+#### `NOT NULL` / NULL
+
+| Feature | Status | Notes |
+|---------|---------|-------|
+| Column-level `NOT NULL` | ✓ | `col INT NOT NULL` |
+| NULL (explicitly nullable) | ✓ | `col INT NULL` |
+| Table-level `NOT NULL` | — | MySQL only supports column-level `NOT NULL` |
+| Constraint options | ◐ | Options are ignored |
+
+### Auto-Increment Columns
+
+| Feature | Status | Notes |
+|---------|---------|-------|
+| `AUTO_INCREMENT` (column attribute) | ✓ | `id INT AUTO_INCREMENT PRIMARY KEY` |
+| `AUTO_INCREMENT` starting value | ◐ | `AUTO_INCREMENT=1000` table option is ignored |
+| `SERIAL` (pseudo-type) | — | PostgreSQL syntax - not valid in MySQL |
+| `BIGSERIAL` (pseudo-type) | — | PostgreSQL syntax - not valid in MySQL |
+| `IDENTITY(seed, increment)` (column property) | — | SQL Server/Snowflake syntax - not valid in MySQL |
+| `GENERATED AS IDENTITY` (column property) | — | SQL standard syntax - not valid in MySQL |
+
+### Inline Indexes (in `CREATE TABLE`)
+
+| Feature | Status | Notes |
+|---------|---------|-------|
+| Column-level indexes | ✗ | Parse failure |
+| Table-level indexes (INDEX/KEY) | ✓ | |
+| Named indexes | ✓ | |
+| Multi-column indexes | ✓ | |
+| USING BTREE | ✓ | |
+| USING HASH | ✓ | |
+| CLUSTERED/NONCLUSTERED | — | SQL Server syntax |
+| FULLTEXT index | ◐ | Ignored |
+| SPATIAL index | ◐ | Ignored |
+| Other index options | ◐ | Ignored |
+
+### Table/Column Comments (in `CREATE TABLE`)
+
+| Feature | Status | Notes |
+|---------|---------|-------|
+| Table `COMMENT` attribute | ✓ | e.g., `CREATE TABLE t (...) COMMENT 'desc'` |
+| Column `COMMENT` attribute | ✓ | e.g., `col INT COMMENT 'desc'` |
+
+---
+
+### `CREATE INDEX`
+
+| Feature | Status | Notes |
+|---------|---------|-------|
+| Basic `CREATE INDEX` | ✓ | |
+| Multi-column index | ✓ | |
+| Explicitly named index | ✓ | |
+| `UNIQUE` index | ✓ | |
+| BTREE index | ✓ | |
+| HASH index | ✓ | |
+| Function-based index | ✓ | e.g., `CREATE INDEX ON t ((col + 1))` |
+| Partial/Filtered index | ✗ | Parse failure |
+| INCLUDE columns | — | Not supported in MySQL |
+| CLUSTERED/NONCLUSTERED | ◐ | Ignored |
+| FULLTEXT index | ◐ | Ignored |
+| SPATIAL index | ◐ | Ignored |
+| COLLATE | ✗ | Parse failure |
+| Index `COMMENT` | ◐ | Ignored |
+| NULLS FIRST/LAST | — | Not supported in MySQL |
+| ASC/DESC | ◐ | Ignored |
+
+---
+
+### `INSERT` Statements
+
+| Feature | Status | Notes |
+|---------|---------|-------|
+| Basic `INSERT` ... VALUES | ✓ | |
+| Multi-row `INSERT` | ✓ | |
+| `INSERT` ... SELECT | ✗ | |
+| WITH clause (CTE) | ✗ | |
+| Target table alias | — | Not supported in MySQL |
+| `INSERT` ... RETURNING | — | Not supported in MySQL |
+| `INSERT` ... ON DUPLICATE KEY UPDATE | ◐ | Clause is ignored |
+| `INSERT` IGNORE | ◐ | IGNORE is ignored |
+| `INSERT` OVERWRITE | — | Snowflake/Hive syntax |
+| Multi-table `INSERT` | ✗ | |
+| Conditional `INSERT` (WHEN/FIRST/ALL) | ✗ | |
+
+---
+
+### `ALTER TABLE`
+
+| Feature | Status | Notes |
+|---------|---------|-------|
+| **ADD COLUMN** | | |
+| - All column properties | ✗ | |
+| **DROP COLUMN** | ✗ | |
+| **ALTER COLUMN / MODIFY COLUMN** | | |
+| - `COMMENT` | ✗ | |
+| - Other modifications | ✗ | |
+| **RENAME COLUMN** | ✗ | |
+| **ADD CONSTRAINT** | | |
+| - Named `CHECK` | ✓ | |
+| - Unnamed `CHECK` | ✓ | |
+| - Named `UNIQUE` | ✗ | |
+| - Unnamed `UNIQUE` | ✗ | |
+| - Named `PRIMARY KEY` | ◐ | Name is ignored |
+| - Unnamed `PRIMARY KEY` | ✓ | |
+| - Named `FOREIGN KEY` | ✓ | |
+| - Unnamed `FOREIGN KEY` | ✓ | |
+| - `DEFAULT` | ✗ | Parse failure |
+| - `NOT NULL` / NULL | ✗ | |
+| **DROP CONSTRAINT** | ✗ | |
+| **ALTER CONSTRAINT** | ✗ | |
+| **RENAME TABLE** | ✗ | |
+| **SET SCHEMA** | ✗ | |
+| **ADD INDEX** | ✗ | |
+
+---
+
+### Other DDL Statements
+
+| Feature | Status | Notes |
+|---------|---------|-------|
+| `DROP TABLE` | ✗ | |
+| `DROP INDEX` | ✗ | |
+| `ALTER INDEX` | — | Not supported in MySQL |
+| `CREATE VIEW` | ✗ | |
+
+---
+
+### Comments (Standalone Statements)
+
+| Feature | Status | Notes |
+|---------|---------|-------|
+| Standalone table comments | — | Use inline `COMMENT` in `CREATE TABLE` |
+| Standalone column comments | — | Use inline `COMMENT` |
+| Index comments | ✗ | Parse failure |
+
+---
+
+## Known Limitations
+
+- **TEMPORARY tables**: Completely ignored during parsing
+- **Column-level indexes in `CREATE TABLE`**: Parse failure for INDEX/KEY definitions inline with columns
+- **`ALTER TABLE` operations**: Limited support; primarily ADD CONSTRAINT (`CHECK`, `FOREIGN KEY`) is functional
+- **DDL modification statements**: `DROP TABLE`, `DROP INDEX` not supported
+- **`INSERT` ... SELECT**: Subqueries in `INSERT` statements not supported
+- **`CREATE VIEW`**: View definitions are not parsed
+- **FULLTEXT/SPATIAL indexes**: Parsed but ignored in output
+
+## MySQL-Specific Notes
+
+1. **`AUTO_INCREMENT`**: The MySQL-specific `AUTO_INCREMENT` attribute is correctly recognized and converted to auto-increment columns in DBML
+2. **`UNIQUE KEY`/`UNIQUE INDEX`**: Both MySQL syntaxes are supported for defining unique constraints
+3. **Inline Comments**: MySQL's `COMMENT` attribute for tables and columns is fully supported (unlike PostgreSQL which uses `COMMENT ON` statements)
+4. **Index Types**: `BTREE` and `HASH` index types are supported; `FULLTEXT` and `SPATIAL` are parsed but ignored
+5. **Table Engine**: `ENGINE`, `CHARSET`, `COLLATE` and other table options are parsed but ignored in DBML output
+6. **ENUM Type**: MySQL's inline `ENUM` type definition is handled differently from PostgreSQL's `CREATE TYPE`