docs(postgres): fix incorrect commands and fields found by executing the guides

[tamalsaha]

Postgres docs refresher: fixes found by executing the guides

Every fix below was found by running the postgres guides on a live KubeDB cluster (v2026.6.19, PostgreSQL 18.3) and comparing real output to what the docs claim. Each was confirmed against the source of truth (apimachinery API types, kubectl api-resources, or observed cluster behavior) and re-verified after the fix.

Auth secret keys (wrong key names returned empty)

• quickstart/quickstart.md, initialization/script_source.md, clustering/streaming_replication.md: the auth secret was read with POSTGRES_USER / POSTGRES_PASSWORD keys, which return nothing. The real keys are username / password (secret type kubernetes.io/basic-auth, keys core.BasicAuthUsernameKey/BasicAuthPasswordKey). Fixed the read commands, the example secret YAML, and the kubectl dba describe output (Type: Opaque -> kubernetes.io/basic-auth).

StatefulSet -> PetSet

• update-version, scaling/vertical-scaling, scaling/horizontal-scaling, tls/configure, volume-expansion/standalone, volume-expansion/ha-cluster: kubectl get sts -n demo <db> returns statefulsets.apps "..." not found. KubeDB manages a PetSet; changed sts -> petset.

Clustering (streaming_replication.md)

• Standby role label is kubedb.com/role=standby, not replica.
• The standby Service is <db>-standby (all-pods service is <db>-pods); the doc's <db>-replicas service does not exist. Fixed the service listing and the hot-standby connection host.
• select pg_last_xlog_receive_location(); errors on PG18 (function removed); replaced with pg_last_wal_receive_lsn().
• Malformed version: "10.2"-v5 -> version: "18.3".

Broken paths / URLs (404)

• update-version: yamls/update_version.yaml -> yamls/upgrade_version.yaml.
• scaling/horizontal-scaling: deploy path was missing /yamls/.
• configuration/using-config-file: the curl URL used raw.githubusercontent.com/.../raw/... (404); removed the extra /raw/. The kubectl apply path pointed to a non-existent configuration/pg-configuration.yaml; pointed it to the real custom-config/pg-custom-config.yaml and aligned that file's secretName to pg-configuration.

rotate-authentication

• After user-defined rotation the doc read secret quick-postgres-user-auth-new, which does not exist. The rotated secret is quick-postgres-user-auth.

custom-rbac

• The Role granted petsets under apiGroup apps; PetSets are in apps.k8s.appscode.com. Fixed the group in the doc and both example role YAMLs (which were even staler, using statefulsets). Also fixed the miniute-postgres typo -> minute-postgres.

Stale output that no longer matches

• synchronous: default is now quorum-based (synchronous_standby_names = ANY 1 (...)); replicas report sync_state = quorum, not sync/potential.
• configuration/pgtune: generated config header shows # DB Version: 18 for a 18.3 database (doc said 17).
• update-version: before/after version-verify outputs showed 11.11/13.2, contradicting the guide's own 17.9 -> 18.3 flow.
• reconfigure/cluster: one explanatory bullet said spec.configuration.secretName while the ops YAML uses spec.configuration.configSecret.name.

Verification

All fixes were re-run on the cluster and produce the documented result (readiness reached, ops requests Successful, corrected commands return the expected values). No em-dashes were introduced. Some guides were blocked by missing cluster infrastructure (no expandable StorageClass for volume expansion, no prometheus-operator, no object storage for backup/pitr, no gitops operator, no second cluster for remote-replica) and were not modified.

Summary by CodeRabbit

• Documentation
  • Updated PostgreSQL guides and examples to match current command output, resource names, and connection steps.
  • Refreshed credential and secret examples to use username/password keys and basic-auth secret types.
  • Reworked clustering, scaling, upgrade, and volume-expansion examples to use petset where applicable.
  • Corrected RBAC and configuration examples, including updated API group and resource names.
  • Adjusted version references and replication outputs to reflect newer PostgreSQL behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 056f7925-1407-442b-af2b-4ba0c0983233

📥 Commits

Reviewing files that changed from the base of the PR and between ee18883 and 1dabb9b.

📒 Files selected for processing (18)

• docs/examples/postgres/custom-config/pg-custom-config.yaml
• docs/examples/postgres/custom-rbac/pg-custom-role-two.yaml
• docs/examples/postgres/custom-rbac/pg-custom-role.yaml
• docs/guides/postgres/clustering/streaming_replication.md
• docs/guides/postgres/configuration/pgtune.md
• docs/guides/postgres/configuration/using-config-file.md
• docs/guides/postgres/custom-rbac/using-custom-rbac.md
• docs/guides/postgres/initialization/script_source.md
• docs/guides/postgres/quickstart/quickstart.md
• docs/guides/postgres/reconfigure/cluster.md
• docs/guides/postgres/rotate-authentication/rotateauth.md
• docs/guides/postgres/scaling/horizontal-scaling/scale-horizontally/index.md
• docs/guides/postgres/scaling/vertical-scaling/scale-vertically/index.md
• docs/guides/postgres/synchronous/index.md
• docs/guides/postgres/tls/configure/index.md
• docs/guides/postgres/update-version/versionupgrading/index.md
• docs/guides/postgres/volume-expansion/ha-cluster/HA Cluster.md
• docs/guides/postgres/volume-expansion/standalone/standalone.md

---

📝 Walkthrough

Walkthrough

This PR updates KubeDB Postgres documentation and example manifests: renaming StatefulSet references to PetSet, changing auth Secret keys from POSTGRES_USER/POSTGRES_PASSWORD to username/password with kubernetes.io/basic-auth type, correcting RBAC API groups/resource names, refreshing example versions, and updating synchronous replication descriptions.

Changes

Postgres documentation updates

Layer / File(s)	Summary
RBAC example and guide corrections docs/examples/postgres/custom-rbac/pg-custom-role.yaml, pg-custom-role-two.yaml, docs/guides/postgres/custom-rbac/using-custom-rbac.md	RBAC rules updated to use apps.k8s.appscode.com/petsets instead of apps/statefulsets, and typo'd resource names corrected (miniute-postgres → minute-postgres).
Auth Secret key rename to username/password docs/guides/postgres/quickstart/quickstart.md, initialization/script_source.md, clustering/streaming_replication.md, rotate-authentication/rotateauth.md	Example Secret outputs and retrieval commands updated from POSTGRES_USER/POSTGRES_PASSWORD keys to username/password with kubernetes.io/basic-auth type.
StatefulSet to PetSet command updates docs/guides/postgres/scaling/..., tls/configure/index.md, volume-expansion/..., update-version/versionupgrading/index.md	Example kubectl get sts commands replaced with kubectl get petset across scaling, TLS, volume-expansion, and version-upgrade guides.
Version, config, and role label refresh docs/examples/postgres/custom-config/pg-custom-config.yaml, docs/guides/postgres/configuration/*, reconfigure/cluster.md, clustering/streaming_replication.md, synchronous/index.md, update-version/versionupgrading/index.md	Updates example Postgres versions (17/18), configuration secret field path, config file URLs, standby role labels/service names, and quorum-based sync replication description.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant kubectl
  participant Secret
  User->>kubectl: get secret -o jsonpath='.data.username'
  kubectl->>Secret: fetch data.username
  Secret-->>kubectl: base64 username
  User->>kubectl: get secret -o jsonpath='.data.password'
  kubectl->>Secret: fetch data.password
  Secret-->>kubectl: base64 password

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the PR’s main doc fixes to incorrect commands and field names found by running the guides.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs-refresh-postgres

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Visit the preview URL for this PR (updated for commit 1dabb9b):

https://kubedb-v2-hugo--pr951-docs-refresh-postgre-nvx60wpo.web.app

_{(expires Fri, 10 Jul 2026 15:23:53 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: 0f29ae8ae0bd54a99bf2b223b6833be47acd5943}