From 0ba1f377c9b3aedf5aca53dc83951d2815bb8c52 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Wed, 22 Oct 2025 15:25:31 -0400 Subject: [PATCH 1/2] Add docs for `sql.schema.approx_max_object_count` Fixes DOC-14949 Information about this cluster setting will also be added to the list of backwards-incompatible changes in the v25.4.0 release notes via DOC-15112 --- src/current/v25.4/schema-design-overview.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/src/current/v25.4/schema-design-overview.md b/src/current/v25.4/schema-design-overview.md index c725d530b26..6a7e32446a0 100644 --- a/src/current/v25.4/schema-design-overview.md +++ b/src/current/v25.4/schema-design-overview.md @@ -124,10 +124,22 @@ CockroachDB has been shown to perform well with clusters containing 10,000 table As you scale to a large number of tables, note that: -- The amount of RAM per node is the limiting factor for the number of tables and other schema objects the cluster can support. This includes columns, indexes, GIN indexes, constraints, and partitions. Increasing RAM is likely to have the greatest impact on the number of these objects that a cluster can support, while increasing the number of nodes will not have a substantial effect. +- {% include_cached new-in.html version="v25.4" %} The cluster setting [`sql.schema.approx_max_object_count`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-schema-approx-max-object-count) defaults to 20,000 and blocks creation of new schema objects once the approximate count exceeds the limit. The check relies on cached [table statistics]({% link {{ page.version.version }}/cost-based-optimizer.md %}#table-statistics), so enforcement can lag until statistics refresh. +- Other than the value of the `sql.schema.approx_max_object_count` cluster setting, the amount of RAM per node is the limiting factor for the number of tables and other schema objects the cluster can support. This includes columns, indexes, GIN indexes, constraints, and partitions. Increasing RAM is likely to have the greatest impact on the number of these objects that a cluster can support, while increasing the number of nodes will not have a substantial effect. - The number of databases or schemas on the cluster has minimal impact on the total number of tables that it can support. - Performance at larger numbers of tables may be affected by your use of [backup and restore]({% link {{ page.version.version }}/backup-and-restore-overview.md %}) and [Change data capture (CDC)]({% link {{ page.version.version }}/change-data-capture-overview.md %}). +If you upgrade to this version with an existing object count above the limit set by [`sql.schema.approx_max_object_count`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-schema-approx-max-object-count), the upgrade will complete, but future attempts to create schema objects will return an error until you raise or disable the limit: + +{% include_cached copy-clipboard.html %} +~~~ sql +-- Raise the limit +SET CLUSTER SETTING sql.schema.approx_max_object_count = 50000; + +-- Or disable the limit +SET CLUSTER SETTING sql.schema.approx_max_object_count = 0; +~~~ + See the [Hardware]({% link {{ page.version.version }}/recommended-production-settings.md %}#hardware) section for additional recommendations based on your expected workloads. ### Quantity of rows From ccafb019aa342abeb7a4bf96ea840a9d6593d61c Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Mon, 27 Oct 2025 14:02:23 -0400 Subject: [PATCH 2/2] Update with taroface feedback (1) --- src/current/v25.4/schema-design-overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/current/v25.4/schema-design-overview.md b/src/current/v25.4/schema-design-overview.md index 6a7e32446a0..6e89d571b62 100644 --- a/src/current/v25.4/schema-design-overview.md +++ b/src/current/v25.4/schema-design-overview.md @@ -124,8 +124,8 @@ CockroachDB has been shown to perform well with clusters containing 10,000 table As you scale to a large number of tables, note that: -- {% include_cached new-in.html version="v25.4" %} The cluster setting [`sql.schema.approx_max_object_count`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-schema-approx-max-object-count) defaults to 20,000 and blocks creation of new schema objects once the approximate count exceeds the limit. The check relies on cached [table statistics]({% link {{ page.version.version }}/cost-based-optimizer.md %}#table-statistics), so enforcement can lag until statistics refresh. -- Other than the value of the `sql.schema.approx_max_object_count` cluster setting, the amount of RAM per node is the limiting factor for the number of tables and other schema objects the cluster can support. This includes columns, indexes, GIN indexes, constraints, and partitions. Increasing RAM is likely to have the greatest impact on the number of these objects that a cluster can support, while increasing the number of nodes will not have a substantial effect. +- {% include_cached new-in.html version="v25.4" %} The cluster setting [`sql.schema.approx_max_object_count`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-schema-approx-max-object-count) defaults to `20000` and blocks creation of new schema objects once the approximate count exceeds the limit. The check relies on cached [table statistics]({% link {{ page.version.version }}/cost-based-optimizer.md %}#table-statistics), so enforcement can lag until statistics refresh. +- Other than the value of the `sql.schema.approx_max_object_count` cluster setting, the amount of RAM per node is the limiting factor for the number of tables and other schema objects the cluster can support. This includes columns, [indexes]({% link {{ page.version.version }}/indexes.md %}), [GIN indexes]({% link {{ page.version.version }}/inverted-indexes.md %}), [constraints]({% link {{ page.version.version }}/constraints.md %}), and [partitions]({% link {{ page.version.version }}/partitioning.md %}). Increasing RAM is likely to have the greatest impact on the number of these objects that a cluster can support, while increasing the number of nodes will not have a substantial effect. - The number of databases or schemas on the cluster has minimal impact on the total number of tables that it can support. - Performance at larger numbers of tables may be affected by your use of [backup and restore]({% link {{ page.version.version }}/backup-and-restore-overview.md %}) and [Change data capture (CDC)]({% link {{ page.version.version }}/change-data-capture-overview.md %}).