Upgrading

Porulle ships schema as Drizzle table definitions — consumers own their migrations. When a release adds or changes tables, the repository’s docs/migration-*.md files are the consumer migration contracts: each one carries the exact SQL to bring an existing database forward, plus the behavioral notes that go with it. Apply them in your own migration tooling (drizzle-kit, raw SQL, whatever runs your deploys); fresh installs get the final shape from drizzle-kit push and need none of them.

Release-to-release upgrades

Start here. These cover a whole version step, including behaviour changes that have no schema component.

| Contract | What it covers | |----------|----------------| | migration-0.15-to-0.16.md | Latest. No schema changes. An auth check that fails is no longer reported as a rejected credential — a fault now logs and returns 500 instead of a silent 401 | | migration-0.13-to-0.14.md | The server refuses to start when it can resolve no organization; resolveActor becomes a public export. Everything else additive | | migration-0.11-to-0.13.md | Start here if you are on 0.11. There is no 0.12.0 on npm, so latest went 0.11.0 → 0.13.0 and this covers both. Authorization defaults tightened in several places | | migration-0.1-to-0.7.md | Upgrade path for 0.1.0 early adopters — schema diff first, then behavioral changes |

Schema contracts

Applied independently of a version step, when you adopt the feature each one backs.

| Contract | What it covers | |----------|----------------| | migration-sellable-custom-fields.md | Provenance columns on sellable_custom_fields (source, status, confidence, evidence, locale, approval stamps) and the approved-only partial unique index | | migration-entity-field-definitions.md | The runtime entity_field_definitions table that layers over code-config fields | | migration-sellable-entity-revisions.md | The full-snapshot sellable_entity_revisions history store with reason enum and retention pin | | migration-media-origin.md | origin/confidence/derived_from_asset_id on media_assets, created_at on entity_media, and the level-scoped unique indexes | | migration-catalog-tags-and-compare-at.md | The org-scoped tags / entity_tags tables and prices.compare_at_amount | | migration-catalog-field-ownership.md | The catalog_field_ownership table and owner enum — requires PostgreSQL 15+ (UNIQUE NULLS NOT DISTINCT) | | migration-channel-catalog-pushes.md | Catalog push bookkeeping for channel connectors | | migration-channel-outbound-echo.md | Outbound echo suppression, so a push does not re-import as an inbound change |

Related

• Database Schema — the current shape all contracts converge on
• Deploy — where migrations fit in the deploy pipeline