Skip to content

[P3][lens] Schema evolution for relational tables (v1 has no migration) #55

Description

@cevheri

Summary

Roadmap item (DESIGN.md sections 6.2/6.3 honest deferrals: "schema migration/evolution" is out of v1). Today table() on an existing name validates the passed schema EQUALS the persisted catalog entry and throws on any difference — correct and honest, but it means a deployed application can never add a column without manual data surgery.

Why

The no-migration rule is the right v1 answer (it prevents silent drift), but it is also the first wall a real application hits as it grows. An explicit, minimal evolution story keeps the honesty while removing the wall.

Scope sketch (exploratory)

  • Additive-only first: adding a new nullable/defaulted column is the one migration that needs no data rewrite (rows without the column read as the default). Renames, type changes, and drops stay refused.
  • The catalog entry gains a schema version or the schema comparison learns "compatible superset" — decide which preserves the faithful-cold-open contract for Studio.
  • An explicit API (table(db, name, schema, { evolve: true }) or a dedicated migrate() helper) — never implicit on open, so evolution is always a deliberate act.

Constraints

  • Interacts with the nullable-columns item in the relational capability arc; sequence them together.
  • On-disk record format unchanged (rows are JSON documents; only validation and the catalog entry evolve).
  • Changeset (minor); gate green.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions