docs: suggest metadata store with instant ADD COLUMN semantics (#15334)

Co-authored-by: 317brian <[email protected]>
apache · Nov 9, 2023 · e7d0429 · e7d0429
1 parent 895e535
commit e7d0429
Show file tree

Hide file tree

Showing 3 changed files with 17 additions and 9 deletions.
diff --git a/docs/design/metadata-storage.md b/docs/design/metadata-storage.md
@@ -44,7 +44,19 @@ See [Metadata storage configuration](../configuration/index.md#metadata-storage)
 
 ## Available metadata stores
 
-Druid supports Derby, MySQL, and PostgreSQL for storing metadata. 
+Druid supports Derby, MySQL, and PostgreSQL for storing metadata.
+
+To avoid issues with upgrades that require schema changes to a large metadata table, consider a metadata store version that supports instant ADD COLUMN semantics.
+See the database-specific docs for guidance on versions.
+
+### MySQL
+
+See [mysql-metadata-storage extension documentation](../development/extensions-core/mysql.md).
+
+### PostgreSQL
+
+See [postgresql-metadata-storage](../development/extensions-core/postgresql.md).
+
 
 ### Derby
 
@@ -59,14 +71,6 @@ druid.metadata.storage.type=derby
 druid.metadata.storage.connector.connectURI=jdbc:derby://localhost:1527//opt/var/druid_state/derby;create=true
 ```
 
-### MySQL
-
-See [mysql-metadata-storage extension documentation](../development/extensions-core/mysql.md).
-
-### PostgreSQL
-
-See [postgresql-metadata-storage](../development/extensions-core/postgresql.md).
-
 ## Adding custom DBCP properties
 
 You can add custom properties to customize the database connection pool (DBCP) for connecting to the metadata store.

diff --git a/docs/development/extensions-core/mysql.md b/docs/development/extensions-core/mysql.md
@@ -61,6 +61,8 @@ Depending on the MariaDB client library version, the connector supports both `jd
 
 ## Setting up MySQL
 
+To avoid issues with upgrades that require schema changes to a large metadata table, consider a MySQL version that supports instant ADD COLUMN semantics. For example, MySQL 8.
+
 1. Install MySQL
 
   Use your favorite package manager to install mysql, e.g.:

diff --git a/docs/development/extensions-core/postgresql.md b/docs/development/extensions-core/postgresql.md
@@ -27,6 +27,8 @@ To use this Apache Druid extension, [include](../../configuration/extensions.md#
 
 ## Setting up PostgreSQL
 
+To avoid issues with upgrades that require schema changes to a large metadata table, consider a PostgreSQL version that supports instant ADD COLUMN semantics.
+
 1. Install PostgreSQL
 
   Use your favorite package manager to install PostgreSQL, e.g.: