From ee53287587201e716f8a8d830e5a97ad73c8fcc1 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Wed, 22 Apr 2026 15:28:08 -0400 Subject: [PATCH 1/3] Add known limitation: bulkmerge: distributed merge permanently fails when a participating SQL instance goes down Fixes DOC-16673 --- .../v26.2/known-limitations/import-into-limitations.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/current/_includes/v26.2/known-limitations/import-into-limitations.md b/src/current/_includes/v26.2/known-limitations/import-into-limitations.md index 6a7cce6f727..4cc416c015e 100644 --- a/src/current/_includes/v26.2/known-limitations/import-into-limitations.md +++ b/src/current/_includes/v26.2/known-limitations/import-into-limitations.md @@ -4,8 +4,9 @@ - After importing into an existing table, [constraints]({% link {{ page.version.version }}/constraints.md %}) will be un-validated and need to be [re-validated]({% link {{ page.version.version }}/alter-table.md %}#validate-constraint). - Imported rows must not conflict with existing rows in the table or any unique secondary indexes. - `IMPORT INTO` works for only a single existing table. +- When `IMPORT INTO` uses distributed merge, it stores intermediate SST files on participating SQL instances' local storage. If one of those SQL instances becomes unavailable during the merge phase, the job fails with a permanent error and must be restarted after that SQL instance becomes available again. - `IMPORT INTO` can sometimes fail with a "context canceled" error, or can restart itself many times without ever finishing. If this is happening, it is likely due to a high amount of disk contention. This can be mitigated by setting the `kv.bulk_io_write.max_rate` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) to a value below your max disk write speed. For example, to set it to 10MB/s, execute: {% include_cached copy-clipboard.html %} ~~~ sql SET CLUSTER SETTING kv.bulk_io_write.max_rate = '10MB'; - ~~~ \ No newline at end of file + ~~~ From f14253d4b547254c1dacb0982b6a9b8b32d16851 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Fri, 24 Apr 2026 14:11:40 -0400 Subject: [PATCH 2/3] update bulkmerge limitation text with github issue link --- .../v26.2/known-limitations/import-into-limitations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/_includes/v26.2/known-limitations/import-into-limitations.md b/src/current/_includes/v26.2/known-limitations/import-into-limitations.md index 4cc416c015e..bc0796281d5 100644 --- a/src/current/_includes/v26.2/known-limitations/import-into-limitations.md +++ b/src/current/_includes/v26.2/known-limitations/import-into-limitations.md @@ -4,7 +4,7 @@ - After importing into an existing table, [constraints]({% link {{ page.version.version }}/constraints.md %}) will be un-validated and need to be [re-validated]({% link {{ page.version.version }}/alter-table.md %}#validate-constraint). - Imported rows must not conflict with existing rows in the table or any unique secondary indexes. - `IMPORT INTO` works for only a single existing table. -- When `IMPORT INTO` uses distributed merge, it stores intermediate SST files on participating SQL instances' local storage. If one of those SQL instances becomes unavailable during the merge phase, the job fails with a permanent error and must be restarted after that SQL instance becomes available again. +- When `IMPORT INTO` uses distributed merge, it stores intermediate SST files on participating SQL instances' local storage. If one of those SQL instances becomes unavailable during the merge phase, the job fails with a permanent error and must be restarted after that SQL instance becomes available again. [#167491](https://github.com/cockroachdb/cockroach/issues/167491) - `IMPORT INTO` can sometimes fail with a "context canceled" error, or can restart itself many times without ever finishing. If this is happening, it is likely due to a high amount of disk contention. This can be mitigated by setting the `kv.bulk_io_write.max_rate` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) to a value below your max disk write speed. For example, to set it to 10MB/s, execute: {% include_cached copy-clipboard.html %} ~~~ sql From 3b8ee8be6f8852e3fd6be94d4ddcd1c42cbfa7be Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Fri, 24 Apr 2026 14:26:48 -0400 Subject: [PATCH 3/3] update with mw5h feedback (1) --- .../v26.2/known-limitations/import-into-limitations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/_includes/v26.2/known-limitations/import-into-limitations.md b/src/current/_includes/v26.2/known-limitations/import-into-limitations.md index bc0796281d5..6f2c04b65f1 100644 --- a/src/current/_includes/v26.2/known-limitations/import-into-limitations.md +++ b/src/current/_includes/v26.2/known-limitations/import-into-limitations.md @@ -4,7 +4,7 @@ - After importing into an existing table, [constraints]({% link {{ page.version.version }}/constraints.md %}) will be un-validated and need to be [re-validated]({% link {{ page.version.version }}/alter-table.md %}#validate-constraint). - Imported rows must not conflict with existing rows in the table or any unique secondary indexes. - `IMPORT INTO` works for only a single existing table. -- When `IMPORT INTO` uses distributed merge, it stores intermediate SST files on participating SQL instances' local storage. If one of those SQL instances becomes unavailable during the merge phase, the job fails with a permanent error and must be restarted after that SQL instance becomes available again. [#167491](https://github.com/cockroachdb/cockroach/issues/167491) +- When `IMPORT INTO` uses distributed merge, it stores intermediate SST files on participating SQL instances' local storage. If one of those SQL instances becomes unavailable during the merge phase, the job waits for that SQL instance to become available again. If the SQL instance does not become available again, the job fails with a permanent error. [#167491](https://github.com/cockroachdb/cockroach/issues/167491) - `IMPORT INTO` can sometimes fail with a "context canceled" error, or can restart itself many times without ever finishing. If this is happening, it is likely due to a high amount of disk contention. This can be mitigated by setting the `kv.bulk_io_write.max_rate` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) to a value below your max disk write speed. For example, to set it to 10MB/s, execute: {% include_cached copy-clipboard.html %} ~~~ sql