dimas-b commented on code in PR #4981:
URL: https://github.com/apache/polaris/pull/4981#discussion_r3606017528
##########
site/content/in-dev/unreleased/metastores/relational-jdbc.md:
##########
@@ -101,3 +101,28 @@ java \
```
For more details on the bootstrap command and other administrative operations,
see the [Admin Tool]({{% ref "../admin-tool" %}}) documentation.
+
+## Schema upgrades
+
+Polaris does not run automated schema migrations. Bootstrapping applies a full
`schema-vN.sql`
+script and records the schema version in the `polaris_schema.version` table;
upgrading an existing
+database to a newer schema version is a manual, operator-driven step.
+
+### Upgrading to schema v5
+
+Schema v5 makes the `events.catalog_id` column nullable: events that are not
scoped to a catalog
+(principal, policy, rate-limiting, etc.) store `NULL` instead of the legacy
placeholder string
+`__realm__` that pre-v5 schemas required (the placeholder only ever existed in
1.6.0 release
+candidates).
+
+Until you upgrade, the server keeps working: it detects a schema version below
5 from the
+`polaris_schema.version` table at startup and continues writing the legacy
placeholder for events
+that are not catalog-scoped. To upgrade an existing v3/v4 database, run the
following one-time SQL
+(adjust the `ALTER` syntax to your database if needed — the statements below
work on PostgreSQL,
+CockroachDB, and H2), then restart Polaris:
+
+```sql
+ALTER TABLE polaris_schema.events ALTER COLUMN catalog_id DROP NOT NULL;
Review Comment:
This PR has been in review for a long time :sweat_smile: Given the low
impact, let's merge "as is". Follow-up doc improvements are welcome, of course.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
