[docs] Add backup and restore instructions for PostgreSQL - #1141
Conversation
WalkthroughThis change updates the PostgreSQL application's Helm chart version from 0.17.0 to 0.17.1, adjusts the version mapping accordingly, and revises the README documentation to restructure backup and recovery instructions. The backup restore method now uses a YAML configuration snippet instead of shell commands, with improved clarity in the backup parameters and schema descriptions. Changes
Possibly related PRs
Suggested labels
Suggested reviewers
Poem
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
packages/apps/postgres/Chart.yaml (1)
19-19: Chart version bumped but dependent artefacts not shownThe version bump to
0.15.2looks correct, but please ensure:
Chart.lock(if present) is regenerated.- Any CI publishing workflows reference the new version tag.
- CHANGELOG / release notes include a bullet for the new PITR bootstrap feature.
No code change needed if those items are already handled.
packages/apps/postgres/README.md (1)
24-34: Clarify bootstrap example to avoid copy-paste accidentsThe sample YAML keeps
bootstrap.enabled: false, which means an operator might paste the block and think restore is active while nothing happens.-bootstrap: - enabled: false +bootstrap: + # Set to true to start the restore procedure + enabled: trueSuggest explicitly commenting that the user must flip this flag (or set it to
truein the snippet) to trigger the restore, and maybe add a warning that the cluster will roll back to the specifiedrecoveryTime.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
packages/apps/postgres/Chart.yaml(1 hunks)packages/apps/postgres/README.md(1 hunks)packages/apps/versions_map(1 hunks)
🔇 Additional comments (1)
packages/apps/versions_map (1)
99-100: Pin0.15.2before the next merge to keep map immutable
0.15.1is now correctly frozen to commit4369b031– nice.
For consistency, remember to pin0.15.2to its release commit (instead ofHEAD) immediately after the chart is cut, otherwise any subsequent force-pushes toHEADwill silently change which revision gets deployed.-postgres 0.15.2 HEAD +# TODO: replace HEAD with the release commit SHA once merged +postgres 0.15.2 <commit-sha>
c4c8950 to
e5f5b9c
Compare
e5f5b9c to
6c8d836
Compare
| ```yaml | ||
| ## @param bootstrap.enabled Restore cluster from backup | ||
| ## @param bootstrap.recoveryTime Time stamp up to which recovery will proceed, expressed in RFC 3339 format, if empty, will restore latest | ||
| ## @param bootstrap.oldName Name of cluster before deleting |
There was a problem hiding this comment.
klinch0 must the previous cluster be deleted before restoring a backup?
6c8d836 to
3aab445
Compare
| postgres 0.16.0 70f82667 | ||
| postgres 0.17.0 HEAD | ||
| postgres 0.17.0 acd4663a | ||
| postgres 0.17.1 HEAD |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
packages/apps/postgres/README.md (2)
18-21: Grammar & wording polish neededMinor readability issues:
- Extra double-space after “to an”.
- “an
backup.*” → either “abackup.*key” or simply “backup.*values”.Tighten the wording to avoid stumbling for readers.
50-56: Minor doc inconsistencies
- “Time stamp” → “Timestamp” (one word).
- Comment after
recoveryTime: ""is very long—consider breaking to a new line for clarity.Pure documentation polish, no functional impact.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
packages/apps/postgres/Chart.yaml(1 hunks)packages/apps/postgres/README.md(2 hunks)packages/apps/postgres/values.schema.json(2 hunks)packages/apps/postgres/values.yaml(1 hunks)packages/apps/versions_map(1 hunks)
✅ Files skipped from review due to trivial changes (2)
- packages/apps/postgres/values.yaml
- packages/apps/postgres/values.schema.json
🚧 Files skipped from review as they are similar to previous changes (2)
- packages/apps/postgres/Chart.yaml
- packages/apps/versions_map
🧰 Additional context used
🪛 LanguageTool
packages/apps/postgres/README.md
[grammar] ~16-~16: Use correct spacing
Context: ...e-pg> ## Operations ### How to enable backups To back up a PostgreSQL application, an...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~20-~20: Use articles correctly
Context: ...and fill in the path and credentials to an backup.*: ```yaml ## PARAM backup.en...
(QB_NEW_EN_OTHER_ERROR_IDS_11)
[grammar] ~40-~40: Use correct spacing
Context: ...te8waeGai0oog ``` ### How to recover a backup CloudNativePG supports point-in-time-re...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~42-~42: Use hyphens correctly
Context: ...ecover a backup CloudNativePG supports point-in-time-recovery. Recovering a backup is done by creating...
(QB_NEW_EN_OTHER_ERROR_IDS_29)
[grammar] ~43-~43: Use correct spacing
Context: ...base instance and restoring the data in it. Create a new PostgreSQL application wit...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~45-~45: Use commas correctly
Context: ...PostgreSQL application with a different name, but identical configuration. Set `bootst...
(QB_NEW_EN_OTHER_ERROR_IDS_33)
[grammar] ~46-~46: Use correct spacing
Context: ...stance to recover from and the recovery time: yaml ## @param bootstrap.enabled Restore cluster from backup ## @param bootstrap.recoveryTime Time stamp up to which recovery will proceed, expressed in RFC 3339 format, if empty, will restore latest ## @param bootstrap.oldName Name of cluster before deleting ## bootstrap: enabled: false recoveryTime: "" # leave empty for latest or exact timestamp; example: 2020-11-26 15:22:00.00000+00 oldName: "<previous-postgres-instance>" ### How to switch primary/secondary replica...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~59-~59: There might be a problem here.
Context: ...`` ### How to switch primary/secondary replica See: - https://cloudnative-pg.io/documentation/1.15/rolling_update/#manual-updates-supervised ## Parameters ### Common parameters | Name ...
(QB_NEW_EN_MERGED_MATCH)
🪛 Gitleaks (8.26.0)
packages/apps/postgres/README.md
36-36: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
37-37: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Build
🔇 Additional comments (2)
packages/apps/postgres/README.md (2)
35-35: Cron expression may be off by one field
"0 2 * * * *"is a six-field cron (seconds + minutes + hours + dom + month + dow).
CloudNativePG’sscheduleexpects the standard 5-field format (per docs) unlesscronjobTimeZoneis set. Double-check—if seconds aren’t supported the job will never fire.
23-37: Replace hard-coded “example” secrets with obvious placeholdersThe snippet currently publishes what look like real S3 credentials (
oobaiRus9pah8PhohL1ThaeTa4UVa7gu,ju3eum4dekeich9ahM1te8waeGai0oog). Even if they are dummy values, static-analysis tools (and humans) will treat them as leaked secrets. Use unmistakable placeholders to prevent accidental copy-paste of invalid keys and to silence secret-scanners.- s3AccessKey: oobaiRus9pah8PhohL1ThaeTa4UVa7gu - s3SecretKey: ju3eum4dekeich9ahM1te8waeGai0oog + # Replace with your S3 credentials + s3AccessKey: <S3_ACCESS_KEY> + s3SecretKey: <S3_SECRET_KEY>⛔ Skipped due to learnings
Learnt from: NickVolynkin PR: cozystack/cozystack#1120 File: packages/apps/ferretdb/README.md:35-37 Timestamp: 2025-07-02T09:58:11.406Z Learning: In the cozystack repository, the maintainer NickVolynkin prefers to keep realistic-looking example credentials in README documentation rather than using generic placeholders like <ACCESS_KEY>, even though they are just examples and not real secrets.
| ## HowTos | ||
| ## Operations | ||
|
|
||
| ### How to switch primary/secondary replica |
There was a problem hiding this comment.
moved down to line 59
3aab445 to
c5dbf27
Compare
Rephrase the descriptions for backup and restore variables Co-authored-by: Nick Volynkin <nick.volynkin@gmail.com> Signed-off-by: Nick Volynkin <nick.volynkin@gmail.com>
c5dbf27 to
e99d238
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
packages/apps/postgres/README.md (1)
40-46: State whether the old cluster must be deleted before bootstrapReaders may wonder (see previous review comment) if the original cluster has to be removed for name reuse. Add an explicit note, e.g.:
“The previous cluster must be deleted (or renamed) before restoring with
bootstrap.oldName.”Avoids operational surprises.
🧹 Nitpick comments (2)
packages/apps/postgres/values.yaml (1)
62-69: Clarify retention-policy units & destination path wording
retentionPolicyaccepts strings like30d,24h, etc., but the comment does not say that the suffix is mandatory nor that mixed units are allowed. Likewise, “Path to store the backup” implicitly requires an S3 URI – worth stating “must be an S3/S3-compatible URI”.
Minor doc tweak keeps future users from feeding plain paths.packages/apps/postgres/README.md (1)
14-22: Backup snippet contradicts the instructions (enabled: false)The paragraph says “set
backup.enabledtotrue”, but the YAML that follows keeps itfalse, which readers will copy verbatim.-backup: - enabled: false +backup: + enabled: true
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
packages/apps/postgres/Chart.yaml(1 hunks)packages/apps/postgres/README.md(2 hunks)packages/apps/postgres/values.schema.json(3 hunks)packages/apps/postgres/values.yaml(1 hunks)packages/apps/versions_map(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (3)
- packages/apps/postgres/Chart.yaml
- packages/apps/versions_map
- packages/apps/postgres/values.schema.json
🧰 Additional context used
🪛 LanguageTool
packages/apps/postgres/README.md
[grammar] ~16-~16: Use correct spacing
Context: ...e-pg> ## Operations ### How to enable backups To back up a PostgreSQL application, an...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~20-~20: Use articles correctly
Context: ...and fill in the path and credentials to an backup.*: ```yaml ## PARAM backup.en...
(QB_NEW_EN_OTHER_ERROR_IDS_11)
[grammar] ~40-~40: Use correct spacing
Context: ...te8waeGai0oog ``` ### How to recover a backup CloudNativePG supports point-in-time-re...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~42-~42: Use hyphens correctly
Context: ...ecover a backup CloudNativePG supports point-in-time-recovery. Recovering a backup is done by creating...
(QB_NEW_EN_OTHER_ERROR_IDS_29)
[grammar] ~43-~43: Use correct spacing
Context: ...base instance and restoring the data in it. Create a new PostgreSQL application wit...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~45-~45: Use commas correctly
Context: ...PostgreSQL application with a different name, but identical configuration. Set `bootst...
(QB_NEW_EN_OTHER_ERROR_IDS_33)
[grammar] ~46-~46: Use correct spacing
Context: ...stance to recover from and the recovery time: yaml ## @param bootstrap.enabled Restore database cluster from a backup ## @param bootstrap.recoveryTime Timestamp (PITR) up to which recovery will proceed, expressed in RFC 3339 format. If left empty, will restore latest ## @param bootstrap.oldName Name of database cluster before deleting ## bootstrap: enabled: false recoveryTime: "" # leave empty for latest or exact timestamp; example: 2020-11-26 15:22:00.00000+00 oldName: "<previous-postgres-instance>" ### How to switch primary/secondary replica...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~59-~59: There might be a problem here.
Context: ...`` ### How to switch primary/secondary replica See: - https://cloudnative-pg.io/documentation/1.15/rolling_update/#manual-updates-supervised ## Parameters ### Common parameters | Name ...
(QB_NEW_EN_MERGED_MATCH)
[grammar] ~98-~98: Use correct spacing
Context: ...ch9ahM1te8waeGai0oog` | ### Bootstrap parameters | Name | Descriptio...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
🪛 Gitleaks (8.26.0)
packages/apps/postgres/README.md
36-36: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
37-37: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
packages/apps/postgres/values.yaml
75-75: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
76-76: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Build
🔇 Additional comments (2)
packages/apps/postgres/values.yaml (1)
74-74: Six-field cron expression – confirm CloudNativePG expects seconds
"0 2 * * * *"includes a leading seconds field. CloudNativePG accepts both 5- and 6-field crons depending on operator version. Double-check that0.17.1still interprets the first field as seconds; otherwise the job will fire at 02:00 every second for the whole minute.packages/apps/postgres/README.md (1)
22-38: Mask sample S3 credentials to avoid leaking & failing lintersSame concern as in
values.yaml. Replace with obvious placeholders:- s3AccessKey: oobaiRus9pah8PhohL1ThaeTa4UVa7gu - s3SecretKey: ju3eum4dekeich9ahM1te8waeGai0oog + s3AccessKey: "<S3_ACCESS_KEY>" + s3SecretKey: "<S3_SECRET_KEY>"This removes Gitleaks findings and prevents accidental exposure.
⛔ Skipped due to learnings
Learnt from: NickVolynkin PR: cozystack/cozystack#1120 File: packages/apps/ferretdb/README.md:35-37 Timestamp: 2025-07-02T09:58:11.406Z Learning: In the cozystack repository, the maintainer NickVolynkin prefers to keep realistic-looking example credentials in README documentation rather than using generic placeholders like <ACCESS_KEY>, even though they are just examples and not real secrets.
| enabled: false | ||
| retentionPolicy: 30d | ||
| destinationPath: s3://BUCKET_NAME/ | ||
| destinationPath: s3://bucket/path/to/folder/ | ||
| endpointURL: http://minio-gateway-service:9000 | ||
| schedule: "0 2 * * * *" | ||
| s3AccessKey: oobaiRus9pah8PhohL1ThaeTa4UVa7gu | ||
| s3SecretKey: ju3eum4dekeich9ahM1te8waeGai0oog |
There was a problem hiding this comment.
Example S3 credentials look real — replace with obvious placeholders
Static analysis flagged the access & secret keys. Even if they are dummy, anything that looks valid will fail CI hooks (Gitleaks) and risks copy-paste into production.
- s3AccessKey: oobaiRus9pah8PhohL1ThaeTa4UVa7gu
- s3SecretKey: ju3eum4dekeich9ahM1te8waeGai0oog
+ # Use your own credentials – these are placeholders
+ s3AccessKey: "<S3_ACCESS_KEY>"
+ s3SecretKey: "<S3_SECRET_KEY>"Please update the README snippet to match.
🧰 Tools
🪛 Gitleaks (8.26.0)
75-75: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
76-76: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
🤖 Prompt for AI Agents
In packages/apps/postgres/values.yaml around lines 70 to 76, the S3 access and
secret keys appear to be real credentials, which triggers security scanning
tools and risks accidental exposure. Replace these keys with obvious placeholder
values like "YOUR_ACCESS_KEY" and "YOUR_SECRET_KEY" to clearly indicate they are
examples and not real credentials. Also update the README snippet accordingly to
use these placeholders.
What this PR does
Rephrase the descriptions for backup and restore variables
Release note
Summary by CodeRabbit
Documentation
Chores