v26.48.0 release notes

doc/user/content/releases/_index.md

@@ -20,6 +20,60 @@ Starting with the v26.1.0 release, Materialize releases on a weekly schedule for
 both Cloud and Self-Managed. See [Release schedule](/releases/schedule) for details.
 {{</ note >}}
 
+## v26.48.0
+*Released to Materialize Cloud: 2026-10-29* <br>
+*Released to Materialize Self-Managed: 2026-10-30* <br>
+
+### Improved hydration times and memory efficiency for upsert sources {#v26.48-upsert-hydration}
+
+Upsert sources that spill to disk now hydrate up to 48% faster, with up to 66% lower peak memory and disk usage.
+
+![Hydration time and peak memory plus disk usage for an upsert source, old versus new: hydration time drops from 206.1 minutes to 107.9–113.3 minutes, and peak memory plus disk usage drops from 542 GiB to 183–208 GiB](/images/releases/v2648_upsert_hydration.png)
+
+Materialize now uses its own buffer pool to keep hot data in memory and serve sequential work from disk. Previously, this was left to the operating system's swap. In addition, we now apply LZ4 compression to in-progress data while building an upsert source. See our [blog post](https://materialize.com/blog/materialize-out-of-core/) for details on how it works.
+
+We ran our tests on Materialize Cloud. We created a new Kafka upsert source, from scratch, on an M.1-1.5xlarge cluster, which has a total heap capacity of 637 GiB. The source ingested from a Kafka topic, consisting of a single partition of about 1.5B messages (roughly 100 GB), holding 956M distinct keys, with records around 100 bytes. We measured hydration times as how long it took from `CREATE SOURCE` until every key is indexed, and the source is keeping up with the topic. We ran the test four times, and observed that hydration times dropped from 206 minutes to between 108 and 113 minutes. Peak memory and disk usage dropped from 542 GiB to between 183 and 208 GiB.
+
+This change has been rolled out to all Materialize Cloud environments and applies to all existing and new clusters. It will be enabled by default in Materialize Self-Managed in the coming weeks.
+
+### Kafka sink headers are generally available {#v26.48-kafka-sink-headers-ga}
+
+The `HEADERS` option for Kafka sinks and the `materialize-sink-id` header, both previously in private preview, are now generally available. `HEADERS` adds the entries of a `map[text => text]` or `map[text => bytea]` column as headers on every message the sink produces. Every Kafka sink now also attaches a `materialize-sink-id` header carrying the sink's ID, so downstream consumers can correlate a data topic with its progress topic without querying Materialize. For more information, see [`CREATE SINK`: Headers](/sql/create-sink/kafka/#headers).
+
+To see how a downstream loader can use the `materialize-sink-id` header to expose only fully committed timestamps, see [Transactional downstream updates using Kafka](/export-data/patterns/transactional-downstream-updates-kafka/).
+
+### Safely drop upstream `NOT NULL` constraints in your MySQL sources {#v26.48-exclude-not-null-constraints}
+Materialize now allows you to `EXCLUDE ALL NOT NULL CONSTRAINTS` when creating a table from a MySQL source, as it already did for PostgreSQL sources. Every column is ingested as nullable, so you can drop `NOT NULL` constraints upstream without causing your table to error. `PRIMARY KEY` and `UNIQUE` constraints are still recorded, and primary key columns remain `NOT NULL`.
+
+```mzsql
+CREATE TABLE orders
+  FROM SOURCE mysql_source (REFERENCE mydb.orders)
+  WITH (EXCLUDE ALL NOT NULL CONSTRAINTS);
+```
+
+For more details, see [`CREATE TABLE ... FROM SOURCE`](/sql/create-table/mysql/) for MySQL and the guide on [excluding nullability constraints](/ingest-data/mysql/source-versioning/#excluding-nullability-constraints).
+
+### Improvements {#v26.48-improvements}
+- **New cluster details page on Self-Managed**: The [redesigned cluster details page](#v26.47-cluster-details-page) is now available on Materialize Self-Managed. To try it, open a cluster and select **Show the new cluster details page** in the breadcrumb bar.
+- **No Kubernetes restart backoff during zero-downtime upgrade catch-up**: A read-only `environmentd` that reboots to pick up DDL changes while it catches up now restarts inside its container instead of exiting it, so Kubernetes no longer applies crash-restart backoff to the repeated reboots a zero-downtime upgrade can need.
+- **Bounded replication slot creation for PostgreSQL sources**: Creating a PostgreSQL source's replication slot is now bounded by a one-minute timeout, applied as the upstream session's `lock_timeout` and configurable, so an upstream transaction holding the slot creation open surfaces an error the source can resume from rather than blocking it indefinitely; the timeout has no effect when the upstream is a physical standby.
+- **Faster progress tracking for sources with many tables**: A source now updates the committed progress of each of its tables only when that table has advanced, rather than walking all of them on every invocation, which on an idle source with 1,000 tables cut total source dataflow time by 40% (129s to 77s of operator time over a two-minute sample on an eight-worker replica).
+- **Fewer Kafka clients on replicas running many sources**: A worker now creates a Kafka reader consumer only once it is responsible for a partition of the source's topic, instead of one per source per worker, which on a four-worker replica with 11 mostly single-partition sources cut the replica's Kafka clients from 55 to 24; each consumer runs a thread per broker, so the old count was what drove the CPU throttling and degraded freshness seen with a few hundred sources on one replica.
+- **Lower memory while hydrating large materialized views**: The consolidation that runs when a materialized view sink's first batch lands no longer collects the whole buffer onto the heap at once, and instead accumulates it in bounded runs that can spill to disk; a TPC-H scale-factor-100 hydration that previously exhausted its replica's 849 GiB memory limit and had to recover now peaks at about 628 GiB and finishes without a restart.
+- **`environmentd` queues more connections while it boots**: The SQL and HTTP listeners now request a kernel accept backlog of 1,024 instead of 128, so connections made during a long boot — including the Kubernetes readiness and liveness probes, which occupy a queue slot even though they close immediately — are queued rather than dropped, making `environmentd` less likely to be restarted by its liveness probe during a long startup.
+- **Time zone data updated to 2026e**: Materialize now ships IANA time zone data 2026e, in which `America/Winnipeg`, `Canada/Central`, `America/Rainy_River`, and `America/Inuvik` stop falling back on 2026-11-01 and keep their summer offsets year-round, and `EST5EDT`, `CST6CDT`, `MST7MDT`, and `PST8PDT` return to US federal rules.
+- **External autoscaling for the connection balancer**: The `Materialize` resource gains a `balancerdExternallyScaled` field, and `Balancer` an `externallyScaled` field, that stop the Kubernetes operator from reasserting the balancerd Deployment's replica count on every reconcile, so a HorizontalPodAutoscaler can own it; `balancerdReplicas` then only seeds the count when the Deployment is first created.
+
+### Guides {#v26.48-guides}
+- [Fine tune for sub-second freshness](/transform-data/freshness/subsecond-freshness/)
+- [Troubleshooting Iceberg sinks](/export-data/iceberg-troubleshooting/)
+
+### Bug Fixes {#v26.48-bug-fixes}
+- Fixed a PostgreSQL source's replica growing until it was killed for running out of memory when upstream schema validation kept failing while the replication stream was silent; the validator retried without pausing and filled an unbounded error queue that is drained only on a keepalive, and it now reports each failure once.
+- Fixed `ALTER CONNECTION` panicking when run on an Iceberg catalog connection, or on the parent S3 or GCP connection that an S3 Tables or BigLake catalog uses.
+- Fixed connection credentials supplied as literal strings rather than wrapped in a `SECRET` — OAuth credentials, AWS session tokens, usernames, access key IDs, and TLS certificates — being written verbatim to the logs whenever a connection was dumped, which happens on every `ALTER CONNECTION` compatibility failure and on every sink a cluster reconciles.
+- Fixed the `dbt-materialize` cluster and schema ownership checks that guard a blue/green deployment never raising anything, because they subtracted the set of objects under deployment the wrong way around; they now also treat membership in the owning role as ownership, which is how Materialize itself decides whether a role may run the swap that `deploy_promote` performs.
+
 ## v26.47.1
 *Released to Materialize Cloud: 2026-10-29* <br>
 *Released to Materialize Self-Managed: 2026-10-30* <br>

doc/user/data/self_managed/self_managed_operator_compatibility.yml

@@ -5,6 +5,11 @@ columns:
   - column: Release date
   - column: Notes
 rows:
+  - Materialize Operator: v26.48
+    orchestratord version: v26.48
+    environmentd version: v26.48
+    Release date: "2026-10-30"
+    Notes: "See [v26.48 release notes](/releases/#v26480)"
   - Materialize Operator: v26.47.1
     orchestratord version: v26.47.1
     environmentd version: v26.47.1