> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockdb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema Governance

> How BlockDB versions SQL assets and communicates breaking or additive changes.

## 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

1. **Announcement (T₀)** — Publish a deprecation note in release notes and mark the dataset here.
2. **Dual writing (T₀ → T₀ + 30 d)** — Both versions populate in parallel. `_created_at` / `_updated_at` values align.
3. **Cutover (T₀ + 30 d)** — Consumers switch to the new table. Old exports freeze but remain queryable.
4. **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.Public` against 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.

<Callout icon="lightbulb" color="#3B82F6" iconType="regular">
  Want early access to upcoming schema shifts?\
  Opt into the private pre-release program at [support@blockdb.io](mailto:support@blockdb.io).
</Callout>

## 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.Public` against your materialized schema