ALTER CLUSTER

ALTER CLUSTER changes the configuration of a cluster, such as the SIZE or REPLICATON FACTOR.

Syntax

ALTER CLUSTER has the following syntax variations:

ALTER CLUSTER <cluster_name>
SET (
    SIZE = <text>,
    REPLICATION FACTOR = <int>,
    MANAGED = <bool>,
    SCHEDULE = { MANUAL | ON REFRESH (...) }
)
[WITH ({ WAIT UNTIL READY({TIMEOUT | ON TIMEOUT {COMMIT|ROLLBACK}}) | WAIT FOR <duration> })]
;

ALTER CLUSTER <cluster_name>
RESET (
    REPLICATION FACTOR,
    MANAGED,
    SCHEDULE
)
;

ALTER CLUSTER <cluster_name> RENAME TO <new_cluster_name>;

ALTER CLUSTER <cluster_name> OWNER TO <new_owner_role>;

ALTER CLUSTER <cluster1> SWAP WITH <cluster2>;

Cluster configuration

WITH options

Considerations

Resizing

Available sizes

See also:

• Materialize service consumption table.

• Blog:Scaling Beyond Memory: How Materialize Uses Swap for Larger Workloads.

Resource allocation

To determine the specific resource allocation for a given cluster size, query the mz_cluster_replica_sizes system catalog table.

Downtime

Resizing operation can incur downtime unless used with WAIT UNTIL READY option. See zero-downtime cluster resizing for details.

Zero-downtime cluster resizing

You can use the WAIT UNTIL READY option to perform a zero-downtime resizing, which incurs no downtime. Instead of restarting the cluster, this approach 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.

ALTER CLUSTER c1
SET (SIZE 'M.1-xsmall') 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.

Replication factor

The REPLICATION FACTOR option determines the number of replicas provisioned for the cluster. Each replica of the cluster provisions a new pool of compute resources to perform exactly the same computations on exactly the same data. Each replica incurs cost, calculated as cluster size * replication factor per second. See Usage & billing for more details.

Replication factor and fault tolerance

Provisioning more than one replica provides fault tolerance. Clusters with multiple replicas can tolerate failures of the underlying hardware that cause a replica to become unreachable. As long as one replica of the cluster remains available, the cluster can continue to maintain dataflows and serve queries.

Materialize automatically assigns names to replicas (e.g., r1, r2). You can view information about individual replicas in the Materialize console and the system catalog.

Availability guarantees

When provisioning replicas,

• For clusters sized under 3200cc, Materialize guarantees that all provisioned replicas in a cluster are spread across the underlying cloud provider’s availability zones.

• For clusters sized at 3200cc and above, even distribution of replicas across availability zones cannot be guaranteed.

Required privileges

To execute the ALTER CLUSTER command, you need:

• Ownership of the cluster.

• To rename a cluster, you must also have membership in the <new_owner_role>.

• To swap names with another cluster, you must also have ownership of the other cluster.

See also:

• Access control (Materialize Cloud)
• Access control (Materialize Self-Managed)

Examples

Replication factor

The following example uses ALTER CLUSTER to update the REPLICATION FACTOR of cluster c1 to 2:

ALTER CLUSTER c1 SET (REPLICATION FACTOR 2);

Increasing the REPLICATION FACTOR increases the cluster’s fault tolerance, not its work capacity.

Resizing

You can alter the cluster size with no downtime (i.e., zero-downtime cluster resizing) by running the ALTER CLUSTER command with the WAIT UNTIL READY option:

ALTER CLUSTER c1
SET (SIZE 'M.1-xsmall') WITH (WAIT UNTIL READY (TIMEOUT = '10m', ON TIMEOUT = 'COMMIT'));

Alternatively, you can alter the cluster size immediately, without waiting, by running the ALTER CLUSTER command:

ALTER CLUSTER c1 SET (SIZE 'M.1-xsmall');

This will incur downtime when the cluster contains objects that need re-hydration before they are ready. This includes indexes, materialized views, and some types of sources.

Schedule

For use cases that require using scheduled clusters, you can set or change the originally configured schedule and related options using the ALTER CLUSTER command.

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

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.

See also

• ALTER ... RENAME
• CREATE CLUSTER
• CREATE SINK
• SHOW SINKS