Home  /  Self-Managed Deployments  /  Upgrading

Upgrade notes

View as Markdown

Review the notes for your target version before upgrading. For the general upgrade procedure, see the upgrade guides.

Upgrading to v26.33 and later versions

Starting in v26.33, Self-Managed deployments that use a PostgreSQL metadata database can configure Materialize to run its internal consensus queries using READ COMMITTED instead of SERIALIZABLE transaction isolation.

NOTE: The transaction isolation levels discussed in this section refer to those of the PostgreSQL metadata database, not Materialize’s client transaction isolation levels.

The consensus queries are designed to be linearizable under READ COMMITTED. READ COMMITTED also improves metadata write throughput by avoiding the serialization-failure retries that SERIALIZABLE incurs under contention.

To use READ COMMITTED with a PostgreSQL metadata database, enable the persist_pg_consensus_read_committed parameter. The parameter is disabled by default.

WARNING!

  • Do not use with non-PostgreSQL metadata databases; Materialize will refuse to run consensus queries when the parameter is enabled for other metadata databases.

  • You must be on v26.33+ before enabling the parameter.

Recommendation: After your entire environment has finished upgrading to v26.33 or later, enable the parameter on PostgreSQL-backed deployments by adding it to your system parameters ConfigMap:

{
  "persist_pg_consensus_read_committed": true
}

or with ALTER SYSTEM SET (as a superuser):

ALTER SYSTEM SET persist_pg_consensus_read_committed = true;

Upgrading to v26.30 and later versions

v26.30.0 introduces support for a new version of the Materialize CRD, v1, which provides simplified rollouts. Previously, Materialize only supported v1alpha1; v1alpha1 remains the default.

Upgrading to v26.30+ does not require adopting the v1 CRD; adopting v1 is opt-in. You can upgrade as usual while continuing to use v1alpha1; your existing instances will behave exactly as before. However, once you are on v26.30+, we do recommend you schedule adoption of v1 before the next major release.

If using Materialize-provided TF modules, v3.1.1+ automatically handles the prerequisites for adopting v1. It does not switch your instances to v1. To switch to v1, see Switch to v1 CRD.

Upgrading to v26.1 and later versions

  • To upgrade to v26.1 or future versions, you must first upgrade to v26.0

Upgrading to v26.0

  • Upgrading to v26.0.0 is a major version upgrade. To upgrade to v26.0 from v25.2.X or v25.1, you must first upgrade to v25.2.16 and then upgrade to v26.0.0.

  • For upgrades, the inPlaceRollout setting has been deprecated and will be ignored. Instead, use the new setting rolloutStrategy to specify either:

    • WaitUntilReady (Default)
    • ImmediatelyPromoteCausingDowntime

    For more information, see rolloutStrategy.

  • New requirements were introduced for license keys. To upgrade, you will first need to add a license key to the backendSecret used in the spec for your Materialize resource.

    See License key for details on getting your license key.

  • Swap is now enabled by default. Swap reduces the memory required to operate Materialize and improves cost efficiency. Upgrading to v26.0 requires some preparation to ensure Kubernetes nodes are labeled and configured correctly. As such:

    • If you are using the Materialize-provided Terraforms, upgrade to version v0.6.1 of the Terraform.

    • If you are not using a Materialize-provided Terraform, refer to Prepare for swap and upgrade to v26.0.

Upgrading between minor versions less than v26

  • Prior to v26, you must upgrade at most one minor version at a time. For example, upgrading from v25.1.5 to v25.2.16 is permitted.
Back to top ↑