Skip to content
CommonLayer
Documentation menu
On this page

ADR-0021: PostgreSQL clusters use the ICU locale provider by default

Status: Accepted (WP-22, recorded in docs/status/WP-22.md). Implemented in projects/postgresql/image/entrypoint.sh and the HA chart.

Context

The CommonLayer base is musl-based. musl's libc locale support does not provide the collations PostgreSQL users expect from glibc (en_US.UTF-8 and friends), so libc-based collation on musl would silently sort text differently or offer no useful locales.

Decision

  • Initialise clusters with POSTGRES_INITDB_LOCALE_PROVIDER=icu, ICU locale und (root collation) and LC_CTYPE=C.UTF-8, with data checksums on. The HA chart passes the same settings to CloudNativePG, whose defaults are libc C.
  • Ship the full ICU data (icu-data-full, about 30 MB more per image) instead of the English subset, because other locales would otherwise fall back to the root collation without any error.

Consequences

  • Moving a cluster from a glibc-based image (for example Bitnami's) by reusing its data volume is not safe: indexes on text would need a reindex. The Bitnami migration guide therefore recommends a logical migration (dump and restore) and documents volume reuse only as an expert option with a mandatory reindex.
  • initdb prints a harmless "no usable system locales" warning on musl (documented in the project README).
  • Image size is about 120 MB uncompressed per major, of which about 32 MB is ICU data.