feat: add PostgreSQL parameter tuning with memory-aware defaults

[xgerman]

• Add postgresParameters map to CRD for user overrides
• Add memory and cpu resource fields to CRD (default unlimited)
• Implement memory-aware defaults (shared_buffers=25%, effective_cache_size=75%, etc.)
• Add static best-practice defaults (max_connections=300, autovacuum, WAL, IO)
• Add protected parameters (cron.database_name, replication slots, prepared txns)
• Wire CPU/memory into CNPG cluster with Guaranteed QoS (requests=limits)
• Add controller patching for parameter and resource changes
• Add 30 unit tests for pg_defaults.go (87% coverage)
• Add PostgreSQL tuning documentation guide

Closes #255

[Copilot]

Pull request overview

Adds PostgreSQL parameter tuning and resource configuration to the DocumentDB Kubernetes Operator by introducing a spec.postgresParameters override map, optional CPU/memory limits, and memory-aware parameter defaults that are propagated into the underlying CloudNativePG (CNPG) Cluster.

Changes:

• Add memory-aware + static default PostgreSQL parameter computation with protected parameters and user overrides.
• Wire spec.resource.memory/cpu into CNPG Cluster spec.resources using Guaranteed QoS (requests == limits).
• Add docs + mkdocs navigation for PostgreSQL tuning guidance, and unit tests for defaults logic.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
operator/src/internal/controller/documentdb_controller.go	Adds patching logic to update CNPG cluster for parameter/resource changes.
operator/src/internal/cnpg/cnpg_cluster.go	Uses merged parameter defaults and builds CNPG resource requirements from CRD CPU/memory fields.
operator/src/internal/cnpg/pg_defaults.go	Implements memory-aware defaults, static defaults, protected params, and merge logic.
operator/src/internal/cnpg/pg_defaults_test.go	Adds unit tests covering defaults and merge behavior.
operator/src/api/preview/documentdb_types.go	Extends the CRD Go types with postgresParameters, resource.memory, and resource.cpu.
operator/src/api/preview/zz_generated.deepcopy.go	Adds deep-copy support for the new PostgresParameters map.
operator/src/config/crd/bases/documentdb.io_dbs.yaml	Updates generated CRD schema to include new fields (and modifies an XValidation rule).
operator/documentdb-helm-chart/crds/documentdb.io_dbs.yaml	Mirrors CRD schema updates for Helm distribution.
mkdocs.yml	Adds nav entry for the new PostgreSQL tuning doc.
docs/operator-public-documentation/postgresql-tuning.md	Adds tuning documentation for defaults, overrides, and resource configuration.

[hossain-rayhan]

Should we call it MemoryLimit then?

[xgerman]

Good question! I kept it as memory (rather than memoryLimit) for two reasons:

1. It sets both requests.memory AND limits.memory (Guaranteed QoS) — so calling it "limit" would be misleading since it is equally the "request". It is really the memory allocation for the pod.

2. Follows the CNPG convention — CloudNative-PG uses spec.resources.limits.memory but the user-facing concept is "how much memory should this database pod have."

Happy to rename if you feel strongly about it — since this is a preview API, now is the time to get the name right. Let me know!