Skip to content

Commit a62055f

Browse files
committed
docs: keep enum in core types with CHECK constraint emulation
Enum remains a portable core type: - MySQL: Native ENUM('a','b','c') inline - PostgreSQL: VARCHAR with CHECK constraint The adapter handles the translation automatically, providing portable enum semantics across backends.
1 parent 5ae5019 commit a62055f

File tree

1 file changed

+11
-10
lines changed

1 file changed

+11
-10
lines changed

docs/design/multi-backend-plan.md

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -64,16 +64,14 @@ The following unsigned types have been removed from `CORE_TYPES`:
6464
Users requiring unsigned integers should use MySQL native types (e.g., `int unsigned`)
6565
with the understanding that these are not portable to PostgreSQL.
6666

67-
### 1.2 Enum Removed from Core Types
67+
### 1.2 Enum Handling
6868

69-
`enum` has been removed from core types due to significant implementation differences:
70-
- **MySQL:** Inline `ENUM('a','b','c')` in column definition
71-
- **PostgreSQL:** Requires separate `CREATE TYPE` statement
69+
`enum` remains a core type with backend-specific implementation:
70+
- **MySQL:** Native `ENUM('a','b','c')` inline in column definition
71+
- **PostgreSQL:** `VARCHAR(n)` with `CHECK (column IN ('a','b','c'))` constraint
7272

73-
Users should:
74-
- Use `varchar(n)` with application-level validation for portable code
75-
- Use native `enum` type on MySQL (non-portable)
76-
- Use CHECK constraints on PostgreSQL (non-portable)
73+
The adapter automatically translates enum definitions to the appropriate backend syntax.
74+
This provides portable enum semantics while using native capabilities where available.
7775

7876
### 1.3 Final Core Types
7977

@@ -109,6 +107,9 @@ CORE_TYPES = {
109107

110108
# Fixed-point (portable)
111109
"decimal": ..., # MySQL: decimal(p,s), PostgreSQL: numeric(p,s)
110+
111+
# Enum (portable with backend-specific implementation)
112+
"enum": ..., # MySQL: enum(...), PostgreSQL: varchar + CHECK
112113
}
113114
```
114115

@@ -117,7 +118,7 @@ CORE_TYPES = {
117118
| Decision | Rationale |
118119
|----------|-----------|
119120
| **No unsigned integers** | PostgreSQL has no unsigned types; cannot be portably emulated |
120-
| **No enum** | PostgreSQL requires separate type creation; too different to abstract |
121+
| **Enum via CHECK on PostgreSQL** | PostgreSQL native enum requires separate `CREATE TYPE`; CHECK constraint provides equivalent validation |
121122
| **No text type** | `varchar(n)` sufficient for most uses; native `text` available per-backend |
122123
| **datetime (not timestamp)** | Matches Python naming; familiar to scientists; avoids MySQL/PG timestamp confusion |
123124
| **json → jsonb on PostgreSQL** | Better performance and indexing; key order not guaranteed by JSON spec anyway |
@@ -612,6 +613,7 @@ Test against both databases in GitHub Actions with Python 3.9-3.12.
612613
| `char(n)` | `char(n)` | `char(n)` | |
613614
| `varchar(n)` | `varchar(n)` | `varchar(n)` | |
614615
| `decimal(p,s)` | `decimal(p,s)` | `numeric(p,s)` | |
616+
| `enum(...)` | `enum(...)` | `varchar` + CHECK | CHECK constraint emulates enum |
615617

616618
## Appendix B: Native Types (Backend-Specific)
617619

@@ -650,4 +652,3 @@ array types (e.g., integer[])
650652
| `uint16` | No PostgreSQL equivalent | Use `int32` or MySQL native `smallint unsigned` |
651653
| `uint32` | No PostgreSQL equivalent | Use `int64` or MySQL native `int unsigned` |
652654
| `uint64` | No PostgreSQL equivalent | Use `int64` (if range fits) or MySQL native `bigint unsigned` |
653-
| `enum` | Different implementation per backend | Use `varchar(n)` or backend-specific native enum |

0 commit comments

Comments
 (0)