hum3/gobank-db
Watch
1
0
Fork
You've already forked gobank-db
 0
Code Issues 3 Pull requests Projects Releases Packages Wiki Activity Actions

Document view versioning pattern for external consumers #3

New issue
Open
opened 2026-08-07 14:22:40 +00:00 by hum3 · 0 comments
hum3 commented 2026-08-07 14:22:40 +00:00
Owner
Copy link

Problem

gobank-db does not currently document the convention for database views that serve as contracts with external consumers.

Proposed Convention

Views are the stable interface that external consumers depend on. The versioning pattern follows Go module conventions:

  • v0 views (e.g. v0_product_catalogue) — unstable, may change without notice. External consumers should not depend on these in production.
  • v1+ views (e.g. v1_product_catalogue) — stable contract. Only non-breaking changes allowed: adding columns, adding rows. No column removals, type changes, or semantic changes.
  • Breaking changes to a stable view require a new major version (e.g. v2_product_catalogue). The previous version continues to exist.

Rules

  1. New views start at v0 during development
  2. Promoting to v1 is a deliberate decision — it signals stability
  3. Non-breaking additions to a v1+ view are fine (new nullable columns, new computed columns)
  4. Any change that would break existing queries against the view requires a new major version
  5. Deprecated view versions should be retained for a migration period with a -- DEPRECATED comment

Example

-- v0: unstable, may change without notice
CREATE VIEW v0_product_catalogue AS ...;

-- v1: stable contract — only additive changes
CREATE VIEW v1_product_catalogue AS ...;

-- v2: breaking change from v1 (e.g. column removed or renamed)
CREATE VIEW v2_product_catalogue AS ...;

Context

gobank-products is the first client implementing this pattern with v0_product_catalogue. This should be documented in gobank-db so all gobank family projects follow the same convention.

Deliverables

  • Document the view versioning convention in README.md or a dedicated doc
  • Add to ROADMAP.md under the schema management section

Migrated from Codeberg: originally #3, opened 2026-03-27.

## Problem gobank-db does not currently document the convention for database views that serve as contracts with external consumers. ## Proposed Convention Views are the stable interface that external consumers depend on. The versioning pattern follows Go module conventions: - **v0 views** (e.g. `v0_product_catalogue`) — unstable, may change without notice. External consumers should not depend on these in production. - **v1+ views** (e.g. `v1_product_catalogue`) — stable contract. Only non-breaking changes allowed: adding columns, adding rows. No column removals, type changes, or semantic changes. - **Breaking changes** to a stable view require a new major version (e.g. `v2_product_catalogue`). The previous version continues to exist. ### Rules 1. New views start at v0 during development 2. Promoting to v1 is a deliberate decision — it signals stability 3. Non-breaking additions to a v1+ view are fine (new nullable columns, new computed columns) 4. Any change that would break existing queries against the view requires a new major version 5. Deprecated view versions should be retained for a migration period with a `-- DEPRECATED` comment ### Example ```sql -- v0: unstable, may change without notice CREATE VIEW v0_product_catalogue AS ...; -- v1: stable contract — only additive changes CREATE VIEW v1_product_catalogue AS ...; -- v2: breaking change from v1 (e.g. column removed or renamed) CREATE VIEW v2_product_catalogue AS ...; ``` ## Context gobank-products is the first client implementing this pattern with `v0_product_catalogue`. This should be documented in gobank-db so all gobank family projects follow the same convention. ## Deliverables - [ ] Document the view versioning convention in README.md or a dedicated doc - [ ] Add to ROADMAP.md under the schema management section --- *Migrated from Codeberg: originally [#3](https://codeberg.org/hum3/gobank-db/issues/3), opened 2026-03-27.*
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
v0.1.3
v0.1.2
v0.1.1
v0.1.0
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
hum3/gobank-db#3
No description provided.