Skip to content

Commit 4980e8b

Browse files
committed
docs: use native PostgreSQL enum type instead of CHECK constraint
PostgreSQL enum implementation: - Adapter creates named type: {schema}_{table}_{column}_enum - Column references the created type - Type lifecycle managed automatically (create/drop with table) Both MySQL and PostgreSQL now use native enum types.
1 parent a62055f commit 4980e8b

File tree

1 file changed

+17
-5
lines changed

1 file changed

+17
-5
lines changed

docs/design/multi-backend-plan.md

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -68,10 +68,22 @@ with the understanding that these are not portable to PostgreSQL.
6868

6969
`enum` remains a core type with backend-specific implementation:
7070
- **MySQL:** Native `ENUM('a','b','c')` inline in column definition
71-
- **PostgreSQL:** `VARCHAR(n)` with `CHECK (column IN ('a','b','c'))` constraint
71+
- **PostgreSQL:** Native enum type via `CREATE TYPE` + column reference
7272

73-
The adapter automatically translates enum definitions to the appropriate backend syntax.
74-
This provides portable enum semantics while using native capabilities where available.
73+
PostgreSQL enum implementation:
74+
```sql
75+
-- Adapter creates named type before table creation
76+
CREATE TYPE {schema}_{table}_{column}_enum AS ENUM ('a', 'b', 'c');
77+
78+
-- Column references the type
79+
CREATE TABLE {table} (
80+
{column} {schema}_{table}_{column}_enum NOT NULL
81+
);
82+
83+
-- Type is dropped when table is dropped (via CASCADE or explicit cleanup)
84+
```
85+
86+
The adapter handles type lifecycle automatically (creation, cleanup on table drop).
7587

7688
### 1.3 Final Core Types
7789

@@ -118,7 +130,7 @@ CORE_TYPES = {
118130
| Decision | Rationale |
119131
|----------|-----------|
120132
| **No unsigned integers** | PostgreSQL has no unsigned types; cannot be portably emulated |
121-
| **Enum via CHECK on PostgreSQL** | PostgreSQL native enum requires separate `CREATE TYPE`; CHECK constraint provides equivalent validation |
133+
| **Enum via CREATE TYPE on PostgreSQL** | Adapter manages enum type lifecycle (create before table, drop with table) |
122134
| **No text type** | `varchar(n)` sufficient for most uses; native `text` available per-backend |
123135
| **datetime (not timestamp)** | Matches Python naming; familiar to scientists; avoids MySQL/PG timestamp confusion |
124136
| **json → jsonb on PostgreSQL** | Better performance and indexing; key order not guaranteed by JSON spec anyway |
@@ -613,7 +625,7 @@ Test against both databases in GitHub Actions with Python 3.9-3.12.
613625
| `char(n)` | `char(n)` | `char(n)` | |
614626
| `varchar(n)` | `varchar(n)` | `varchar(n)` | |
615627
| `decimal(p,s)` | `decimal(p,s)` | `numeric(p,s)` | |
616-
| `enum(...)` | `enum(...)` | `varchar` + CHECK | CHECK constraint emulates enum |
628+
| `enum(...)` | `enum(...)` | `CREATE TYPE` + reference | Native enum on both backends |
617629

618630
## Appendix B: Native Types (Backend-Specific)
619631

0 commit comments

Comments
 (0)