---
status: draft
last_updated: 2026-05-22
---

# Open Questions Tracker

All unresolved architectural questions for dbtype, organized by theme.

## Schema & Module

### OQ-01: Should relation entries use a naming convention?

- **Origin**: [schema.md](schema.md)
- **Status**: Open
- **Priority**: Medium
- **Context**: Currently `UsersRelations` / `TasksRelations`. Is this naming convention sufficient, or should relations be structured differently? A `relations` field on the table entry would couple relations to table definitions.
- **Cross-references**: OQ-03

### OQ-02: Should derived schemas live in the module or be extracted separately?

- **Origin**: [schema.md](schema.md)
- **Status**: Open
- **Priority**: Low
- **Context**: Insert/update schemas can be added as module entries (`InsertUsers`, `UpdateUsers`) or extracted by walking the module. Adding them to the module increases size but makes everything accessible via `Import`. Extracting separately is more flexible but requires separate code paths.
- **Cross-references**: OQ-03

### OQ-03: Should the module support multiple database namespaces?

- **Origin**: [schema.md](schema.md)
- **Status**: Open
- **Priority**: Low
- **Context**: One module per database, or one module with all tables across all databases? Probably one per database namespace, but this needs confirmation from real use cases.

## Element & Host

### OQ-04: Should column elements support nested TypeBox schemas?

- **Origin**: [elements.md](elements.md)
- **Status**: Open
- **Priority**: High
- **Context**: The research docs proposed `DbType.String({ notNull: true, inner: Type.String({ format: 'email', maxLength: 255 }) })`. With UJSX elements, this would be `<column name="email" type="string" notNull format="email" maxLength={255} />`. The flat props model works for common cases, but custom validation constraints (patterns, ranges, custom checks) may need a nested `inner` prop. Should we support `<column name="email" type="string" notNull inner={Type.String({ format: 'email', maxLength: 255 })} />`?
- **Cross-references**: ADR-001

### OQ-05: How to handle PG enum pre-declaration?

- **Origin**: [hosts.md](hosts.md)
- **Status**: Open
- **Priority**: High
- **Context**: PG requires `pgEnum()` at module scope before tables that reference it. Options: (A) return both enums and tables from render, (B) start with text for all enums, (C) per-column opt-in with `postgres: { nativeEnum: true }`. Option A is cleanest but changes the render API. Option B is simplest but loses PG enum validation.

### OQ-06: Should hosts return rendered tables or store them in context?

- **Origin**: [hosts.md](hosts.md)
- **Status**: Open
- **Priority**: Medium
- **Context**: The probe scripts use `ctx.tables` to collect rendered tables. A more functional approach would have `render()` return the rendered table directly. Need to resolve this before implementation.

### OQ-07: Should we support JSX file extensions?

- **Origin**: [elements.md](elements.md)
- **Status**: Open
- **Priority**: Low
- **Context**: JSX syntax (`.tsx` with `jsxImportSource: '@alkdev/ujsx'`) would be more ergonomic than `h()` calls. This requires build configuration (TSConfig `jsx`, bundler support). The `h()` API works universally; JSX is a convenience layer.

## Repo Adapter

### OQ-08: Per-dialect handler differences?

- **Origin**: [repo-adapter.md](repo-adapter.md)
- **Status**: Open
- **Priority**: Medium
- **Context**: PG has `.returning()` on all mutations, MySQL often doesn't. Should the adapter handle this transparently (always try `.returning()`, fall back gracefully), or should it be explicit in the config?

### OQ-09: Relation rendering responsibility?

- **Origin**: [repo-adapter.md](repo-adapter.md)
- **Status**: Open
- **Priority**: Medium
- **Context**: Should the host render relations (new element type `<relation>`), or should the adapter generate them from the module's relation entries? The adapter knows the rendered table objects; the module knows the relation structure. Leaning toward the adapter generating them.

## Migration & Diffing

### OQ-10: How far should migration diffing go in phase 1?

- **Origin**: [module.md](module.md)
- **Status**: Open
- **Priority**: Low
- **Context**: `Value.Diff` on serialized schemas produces structural edit lists (insert/delete/update property). Translating these to `ALTER TABLE` statements is straightforward for additive changes (new column) but complex for destructive ones (drop column, change type). Phase 1 likely skips migration generation entirely (rely on `drizzle-kit`), but the module structure should not prevent it later.

## Summary Table

| ID | Question | Origin | Priority | Status |
|----|----------|--------|----------|--------|
| OQ-01 | Relation naming convention | schema.md | Medium | Open |
| OQ-02 | Derived schemas in module or separate | schema.md | Low | Open |
| OQ-03 | Multiple database namespaces | schema.md | Low | Open |
| OQ-04 | Nested TypeBox schemas in column props | elements.md | High | Open |
| OQ-05 | PG enum pre-declaration | hosts.md | High | Open |
| OQ-06 | Host render return value vs context | hosts.md | Medium | Open |
| OQ-07 | JSX file extensions | elements.md | Low | Open |
| OQ-08 | Per-dialect handler differences | repo-adapter.md | Medium | Open |
| OQ-09 | Relation rendering responsibility | repo-adapter.md | Medium | Open |
| OQ-10 | Migration diffing scope | module.md | Low | Open |