CockroachDB 1.1 adds explicit import and node-removal workflows

Moving data into a distributed database and removing a machine from it both require work beyond issuing a logical request. Imported rows must become the database's own key-value representation and reach their destination nodes. Removing a node requires its replicas to find eligible homes elsewhere. CockroachDB 1.1 supplies explicit workflows for both jobs, with practical limits documented at launch.

The October 12 release notes introduce CSV IMPORT, node decommissioning, and new SQL commands for inspecting queries and jobs. They also change memory defaults and several SQL compatibility rules. This is a release about operating the database as much as extending the statements applications can send.

I find that direction useful because distribution should come with inspectable procedures for changing the deployment. Automatic replication does not eliminate an operator's need to distinguish a failed node from one that should permanently leave. Similarly, accepting a CSV file is only the beginning of an import procedure.

CSV import has a single-node conversion phase

The IMPORT guide at the launch commit labels the feature experimental. It requires enabling a cluster setting before use:

SET CLUSTER SETTING experimental.importcsv.enabled = true;

The receiving node becomes the processing node. It streams the input file and converts tabular values into CockroachDB-compatible key-value data. It writes that generated data to a temporary location. Once conversion completes, the relevant cluster nodes import the generated data from that location.

This separates conversion from distribution. The first phase runs on one node, consuming that node's CPU and memory alongside its normal traffic. Later ingestion work is distributed. Describing the whole operation as parallel across all nodes would conceal the conversion bottleneck and the resource requirements of the node receiving the statement.

The guide recommends connecting directly to an appropriate node when the deployment is asymmetric, rather than letting a load balancer choose randomly. That advice follows from the implementation. Choosing the processing node selects where the concentrated conversion work runs.

Temporary storage must be reachable by every destination

The converted data needs a temporary location accessible to all nodes through the same address. A private directory on the processing node is insufficient for that shared role. The guide describes cloud storage, network file storage, and a file server as possible arrangements.

Local storage can hold the original input file, but that does not remove the shared temporary-location requirement. There are two different storage roles, the source that the processing node reads and the generated data that other nodes ingest. Conflating them can produce a configuration in which conversion succeeds but the rest of the cluster cannot access its output.

The processing node also needs sufficient local store capacity for conversion. The guide requires at least the input file's size in available storage, with additional space when that same machine also stores the input. A configured --max-disk-temp-storage limit must accommodate the import as well.

Generated temporary data is not automatically cleaned up by completion of the import. The operator must remove it afterward. This gives the workflow a storage lifecycle extending beyond the statement's successful result, with capacity planning relevant before conversion and cleanup relevant afterward.

Import creates one new table

The target table must not already exist. Its definition appears in the import statement or in a referenced file containing CREATE TABLE. This release imports a single table at a time, so the statement does not represent an automatic reconstruction of every object in an existing database.

The guide recommends specifying secondary indexes during import because adding them afterward is slower. That lets conversion account for the intended table structure during the load. Objects on which the table depends must already exist, while objects depending on the imported table can only be created after it exists.

Imported tables are new objects and need their privileges granted. Only root may execute IMPORT in this implementation. Those authorization details belong to the migration plan because successful ingestion alone does not grant application roles access to the resulting table.

I regard these as useful limits for a first import interface. They define what the operation can complete and what surrounding schema work remains separate. A one-table loader can improve migration without implying that a complete foreign database can be imported in one statement.

Decommissioning differs from stopping a process

The node-removal guide at the same commit describes decommissioning as allowing in-flight requests to finish, rejecting new ones, and transferring range replicas and leases away. The intended end state is a node that holds no data requiring its continued participation.

Temporarily stopping a process expresses a different intent. A stopped node can return, and the system can treat it as an active placement target again. Decommissioning records that the node should leave permanently, so restarting it does not automatically make it a recipient of rebalanced data.

The guide defines a range as a contiguous part of the sorted keyspace and says each replica occupies a different node. One replica holds the range lease and coordinates reads and writes for that range. Permanent removal must therefore account for both the stored replicas and responsibility for serving their requests.

For a secure cluster with the appropriate certificates already available, the documented command to decommission and stop a particular live node has this form:

cockroach quit --decommission --certs-dir=certs --host=node.example.com

The hostname is an example of the node being removed. It is not an instruction to perform the operation against an arbitrary healthy node. The procedure's target and the available replacement capacity determine what the cluster can do next.

Replica placement determines whether removal can complete

A three-node cluster with three replicas of each range cannot finish removing one node while preserving that arrangement on only the other two. Those nodes already have replicas of each range, and CockroachDB will not place two replicas of the same range on one node. The guide requires adding a fourth node first in that example.

The same constraint can appear in a larger cluster through a table-specific replication zone. If one table requires five replicas across a five-node cluster, removing one node cannot complete for that table even if the rest of the database uses only three replicas. The most restrictive relevant placement requirement controls completion.

This explains a decommission operation that appears to stop making progress after moving much of the data. Free disk capacity alone does not establish eligible replica destinations. The cluster also needs enough distinct nodes satisfying the configured replication requirements.

Dead-node removal has a waiting distinction as well. The guide specifies --wait=live rather than waiting for every targeted node, since a dead node cannot report completion. That changes what the administrative command waits for while retaining the record that the node is decommissioned.

SQL inspection gives operations named objects

Version 1.1 adds SHOW QUERIES, SHOW SESSIONS, and CANCEL QUERY for active work and connections. SHOW JOBS exposes schema-change progress and enterprise backup and restore work. The new job-control statements can pause, resume, or cancel enterprise backup and restore jobs.

These operations have different scopes. A session is a client connection, a query is work executing through a session, and a job can represent longer-running administrative activity. Giving each an inspection interface helps an operator identify which kind of state needs attention without equating every slow operation with a stuck connection.

SHOW TRACE replaces the previous debug and trace variants of EXPLAIN. The shell and utilities also gain options to reveal SQL they send implicitly. That makes the administrative client less opaque when its visible command triggers additional database statements.

Resource defaults change during the upgrade

The defaults for --max-sql-memory and --cache become 128 MiB each, replacing defaults based on 25 percent of physical memory. The release notes call the new values appropriate for local development and direct production deployments to configure larger values. An unchanged startup command can therefore give the new version a different resource budget.

The new --max-disk-temp-storage setting bounds temporary disk capacity for memory-intensive SQL operations that spill intermediate results. Disk spilling provides another place for execution state, with its own finite capacity. It does not turn memory-heavy queries into resource-free work.

Other compatibility changes include case-sensitive quoted identifiers and requiring CASCADE to drop a nonempty database. The release also warns that upgrading from 1.0 to 1.1 follows a different procedure from an update within 1.0. The new import and removal interfaces sit within those explicit configuration and upgrade boundaries, with conversion resources and eligible replica destinations determining whether the requested operations can complete.