doc: documentation for dropping to READ COMMITTED isolation consensus

[petrosagg]

No description provided.

[kay-kim]

maybe?

Suggested change

	v26.33.0 lets self-managed deployments run Materialize's internal consensus
	queries under `READ COMMITTED` transaction isolation instead of `SERIALIZABLE`
	when using a PostgreSQL metadata database. The consensus queries are designed to
	be linearizable under `READ COMMITTED`, and running under it avoids the
	serialization-failure retries that `SERIALIZABLE` incurs under contention, which
	improves metadata write throughput.
	Starting in v26.33, Self-Managed deployments that use a **PostgreSQL metadata
	database** can configure Materialize to run its internal consensus queries under
	`READ COMMITTED` transaction isolation instead of `SERIALIZABLE`. The consensus
	queries are linearizable under `READ COMMITTED`. `READ COMMITTED` also improves
	metadata write throughput by avoiding the serialization-failure retries
	that `SERIALIZABLE` incurs under contention.

[kay-kim]

should we list the configmap option first?

[kay-kim]

Also, by this recommendation ... double-checking that we're recommending people set this flag. (I wasn't sure whether it was more that you set it after you're on v26.33)

[kay-kim]

I would make this part about cockroach a warning ... (also could people use other dbs as consensus db?). Am wondering if we should just make it generic?

something like:

{{< 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.

{{< /warning >}}

or

{{< warning >}}

- Only enable if using 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.

{{< /warning >}}

[kay-kim]

Maybe just make it 2 sentences:

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

[kay-kim]

Suggested change

	The parameter applies only to PostgreSQL metadata databases and must stay off on
	CockroachDB, so Materialize Cloud and other CockroachDB-backed deployments are
	unaffected. Enable it only after your entire environment has finished upgrading to
	v26.33 or later. For details, see the [Self-Managed upgrade
	notes](/self-managed-deployments/upgrading/version-notes/).
	{{< note >}}
	The parameter applies only to PostgreSQL metadata databases. Only enable it
	after you have upgraded your self-managed deployment to v26.33 or later.
	{{< /note >}}
	For details, see the [Self-Managed upgrade
	notes](/self-managed-deployments/upgrading/version-notes/).

[kay-kim]

Suggested change

	Self-managed deployments that use a PostgreSQL metadata database can now run
	Materialize's internal consensus queries under `READ COMMITTED` transaction
	isolation instead of `SERIALIZABLE`. The consensus queries are designed to be
	linearizable under `READ COMMITTED`, and running under it avoids the
	serialization-failure retries that `SERIALIZABLE` incurs under contention,
	improving metadata write throughput. This is controlled by the new
	`persist_pg_consensus_read_committed` system parameter, which is off by default.
	*Materialize Self-Managed only*
	Starting in v26.33, self-managed deployments that use a PostgreSQL metadata
	database can configure Materialize to run its internal consensus queries under
	`READ COMMITTED` transaction isolation instead of `SERIALIZABLE`. The consensus
	queries are linearizable under `READ COMMITTED`, while avoiding the
	serialization-failure retries that `SERIALIZABLE` incurs under contention,
	improving metadata write throughput. To use `READ COMMITTED`, Materialize
	introduces the `persist_pg_consensus_read_committed` system parameter.