Home  /  Reference

ALTER CLUSTER

ALTER CLUSTER changes the configuration of a cluster, which might incur downtime. To rename a cluster, use ALTER ... RENAME.

Syntax

Set new configuration value

ALTER CLUSTER name SET ( cluster_option = value ) WITH with_options

Reset configuration to original value

ALTER CLUSTER name RESET ( cluster_option_name )

Cluster options

Field Value Description
SIZE text The size of the resource allocations for the cluster. See Size for details.
REPLICATION FACTOR text The number of replicas to provision for the cluster. See Replication factor for details.
Default: 1
INTROSPECTION INTERVAL interval The interval at which to collect introspection data. See Troubleshooting for details about introspection data. The special value 0 entirely disables the gathering of introspection data.
Default: 1s
INTROSPECTION DEBUGGING bool Indicates whether to introspect the gathering of the introspection data.
Default: FALSE
MANAGED bool Whether to automatically manage the cluster’s replicas based on the configured size and replication factor. If FALSE, enables the use of the deprecated CREATE CLUSTER REPLICA command.
Default: TRUE
SCHEDULE [MANUAL,ON REFRESH] The scheduling type for the cluster.
Default: MANUAL

with_options

WITH ( WAIT UNTIL READY ( wait_until_ready_option = value ) FOR = duration )
Field Value Description
WAIT UNTIL READY…TIMEOUT duration For a graceful cluster resizing, the maximum duration to wait for the new replicas to be ready.
WAIT UNTIL READY…ON TIMEOUT [COMMIT,ROLLBACK] For a graceful cluster resizing, the action to take on timeout.
  • COMMIT cuts over to the new replica regardless of its hydration status, which may lead to downtime.
  • ROLLBACK removes the pending replica and returns a timeout error.
Default: COMMIT.
WAIT FOR duration For a graceful cluster resizing, a fixed duration to wait for the new replicas to be ready. This option might lead to downtime, so we recommend using the WAIT UNTIL READY option instead.

Graceful cluster resizing

PREVIEW This feature is in private preview. It is under active development and may have stability or performance issues. It isn't subject to our backwards compatibility guarantees.

You must contact us to enable this feature in your Materialize region.

Changing the size of a cluster using the ALTER CLUSTER command requires the cluster to restart, which incurs downtime. For clusters that don’t contain sources or sinks, you can use the WAIT UNTIL READY option to perform a graceful resizing, which spins up an additional cluster replica under the covers with the desired new size, waits for the replica to be hydrated, and then replaces the original replica. This allows you to perform cluster resizing with no downtime.

ALTER CLUSTER c1
SET (SIZE '100CC') WITH (WAIT UNTIL READY (TIMEOUT = '10m', ON TIMEOUT = 'COMMIT'));

The ALTER statement is blocking and will return only when the new replica becomes ready. This could take as long as the specified timeout. During this operation, any other reconfiguration command issued against this cluster will fail. Additionally, any connection interruption or statement cancelation will cause a rollback — no size change will take effect in that case.

Examples

Replication factor

Alter cluster to two replicas:

ALTER CLUSTER c1 SET (REPLICATION FACTOR 2);

Resizing

For clusters with no sources or sinks, you can alter the cluster size with no downtime (i.e., graceful cluster resizing) using the WAIT UNTIL READY option:

ALTER CLUSTER c1
SET (SIZE '100CC') WITH (WAIT UNTIL READY (TIMEOUT = '10m', ON TIMEOUT = 'COMMIT'));

For clusters with sources or sinks, you can alter the cluster size using a bare ALTER CLUSTER statement, but this operation incurs downtime:

ALTER CLUSTER c1 SET (SIZE '100cc');

Schedule

PREVIEW This feature is in private preview. It is under active development and may have stability or performance issues. It isn't subject to our backwards compatibility guarantees.

You must contact us to enable this feature in your Materialize region. 
ALTER CLUSTER c1 SET (SCHEDULE = ON REFRESH (HYDRATION TIME ESTIMATE = '1 hour'));

See the reference documentation for CREATE CLUSTER or CREATE MATERIALIZED VIEW for more details on scheduled clusters.

Converting unmanaged to managed clusters

WARNING!

Unmanaged clusters are a deprecated feature of Materialize that required manual management of cluster replicas.

We recommend converting any unmanaged clusters to managed clusters by following the instructions below.

Alter the managed status of a cluster to managed:

ALTER CLUSTER c1 SET (MANAGED);

Materialize permits converting an unmanged cluster to a managed cluster if the following conditions are met:

  • The cluster replica names are r1, r2, …, rN.
  • All replicas have the same size.
  • If there are no replicas, SIZE needs to be specified.
  • If specified, the replication factor must match the number of replicas.

Note that the cluster will not have settings for the availability zones, and compute-specific settings. If needed, these can be set explicitly.

Privileges

The privileges required to execute this statement are:

  • Ownership of the cluster.

See also

Back to top ↑