dbtype/docs/architecture/open-questions.md

status, last_updated

status	last_updated
draft	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
• 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: 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
• 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
• 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
• 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	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