dbtype/docs/architecture/open-questions.md

status, last_updated

status	last_updated
draft	2026-05-23

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
• 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
• 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
• 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
• Status: Resolved
• Priority: High Resolved
• 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.
• Resolution: Yes — flat props for common cases, inner as escape hatch for custom validation. When inner is provided, extractTable() uses it directly instead of calling colToTypeBox(). The host ignores inner — it's purely for the TypeBox schema. See ADR-007.

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

• Origin: hosts.md
• Status: Resolved
• Priority: High Resolved
• 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 }.
• Resolution: Option A — the PG host accumulates enums in ctx.enums during the render walk. The consumer includes both ctx.enums and ctx.tables in their Drizzle schema. Enum names follow the table_column convention. See ADR-008.

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

• Origin: hosts.md
• Status: Resolved
• 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.
• Resolution: render() accumulates results in root.ctx (tables, enums). The context shape varies by dialect — SQLite has ctx.tables, PG has ctx.tables and ctx.enums. See hosts.md Rendering Pipeline.

OQ-07: Should we support JSX file extensions?

• Origin: 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
• 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
• 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
• 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 Resolved	Resolved — ADR-007
OQ-05	PG enum pre-declaration	hosts.md	High Resolved	Resolved — ADR-008
OQ-06	Host render return value vs context	hosts.md	Medium	Resolved
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