flyrain commented on code in PR #4981:
URL: https://github.com/apache/polaris/pull/4981#discussion_r3604981613
##########
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:
Small doc nit: this block is presented as working on PostgreSQL,
CockroachDB, and H2, but `ALTER COLUMN ... DROP NOT NULL` is the
Postgres/Cockroach spelling — H2 historically uses `ALTER COLUMN catalog_id SET
NULL`. The "adjust the ALTER syntax to your database if needed" hedge covers
it, and H2 is effectively test-only, so this is optional — but if you want it
copy-pasteable, worth naming H2's variant. (I couldn't verify the exact H2
version's syntax here, so flag if this is already fine.)
--
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]
