Versioning Rules
- Semantic suffix: Tables follow the pattern
<dataset_id>_<name>_v<major>. - Additive fields: Columns may be appended without bumping the major version; they’re documented in changelogs and fully backfilled before announcement.
- Breaking changes: Renames, type changes, or constraint updates trigger a new table version. The previous version remains queryable for at least one quarter.
| Scenario | Action | Communication |
|---|---|---|
| New nullable column | Add column, update docs | Changelog |
| Column type widening | Create _v<next> table and dual-write | RFC via customer email |
| Constraint tightening | Validate in shadow schema, then publish | Maintenance window notice |
Deprecation Cycle
- Announcement (T₀) — Publish a deprecation note in release notes and mark the dataset here.
- Dual writing (T₀ → T₀ + 30 d) — Both versions populate in parallel.
_created_at/_updated_atvalues align. - Cutover (T₀ + 30 d) — Consumers switch to the new table. Old exports freeze but remain queryable.
- Retirement (T₀ + 90 d) — Old table is archived in cold storage. Contact support if you need an exception.
Consumer Guidance
- Track schema drift by comparing SQL scripts in
BlockDb.Postgres.Tables.Publicagainst your internal materialized version. - Pin ETL jobs to dataset IDs (
0101,0201, etc.) rather than table names to automatically pick up new versions. - Monitor the account-linked email for schema change notifications.
Want early access to upcoming schema shifts?
Opt into the private pre-release program at [email protected].
Opt into the private pre-release program at [email protected].
Breaking change template
When a breaking change is planned, communications include:- Summary of change and impacted datasets
- Migration guide and mapping (old → new)
- Dual-write window dates (start/end)
- Cutover date and validation checklist
- Retirement date and archive location
Consumer checklist
- Pin ETL by dataset IDs (e.g.,
0101) not hard-coded table names - Watch Release Notes for additive/breaking changes
- Diff SQL in
BlockDb.Postgres.Tables.Publicagainst your materialized schema