docs: add PostgreSQL KB how-to and troubleshooting guides (MIDDLEWARE-31526)#35
docs: add PostgreSQL KB how-to and troubleshooting guides (MIDDLEWARE-31526)#35SuJinpei wants to merge 2 commits into
Conversation
…-31526) Precipitate historical internal KB solutions into the product manual, modernized to the current acid.zalan.do/v1 postgresql CR and verified live on ACP 4.2/4.3: how_to: install pgvector, install zhparser, configure pg_hba whitelist, run as root, disable NodePort exposure. trouble_shooting: connection SSL off, pg_wal disk full, coredump from huge pages, repair streaming replica. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Warning Review limit reached
More reviews will be available in 42 minutes and 9 seconds. Learn how PR review limits work. Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file). ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits. 🚦 How do rate limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
WalkthroughNine new MDX documentation pages are added across two directories: five how-to guides covering ChangesHow-To Guides
Troubleshooting Guides
Estimated code review effort🎯 2 (Simple) | ⏱️ ~15 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (6)
docs/en/how_to/install_zhparser_extension.mdx (2)
67-90: ⚡ Quick winAdd
zhparser.extra_dictsto the configuration table if it applies.The text references
zhparser.extra_dictsas an option that must be set before the backend starts (line 88), but this option is missing from the configuration table on lines 72–80. If this option is relevant to users, add it to the table for completeness. If it's an advanced/rarely-used option outside the scope of this guide, clarify that the table covers only the most common options.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/en/how_to/install_zhparser_extension.mdx` around lines 67 - 90, The configuration table in the "Parser configuration" section lists options from `zhparser.punctuation_ignore` through `zhparser.multi_zall`, but the text below the table references `zhparser.extra_dicts` as an option that must be set before the backend starts. Either add `zhparser.extra_dicts` to the options table with its purpose (if it's a commonly-used option users should know about), or add a clarifying note in the text explaining that the table covers the most common options and `zhparser.extra_dicts` is an advanced configuration option covered separately.
98-102: 💤 Low valueConsider adding version expectations to the verification section.
The PR objectives note that zhparser v2.3 has been tested. You may want to clarify the expected version in the verification section so users can confirm they have a compatible version installed.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/en/how_to/install_zhparser_extension.mdx` around lines 98 - 102, The Verification section contains a SQL query to check the zhparser extension but lacks clarity on what version users should expect. Add explanatory text after the verification SQL query that specifies the expected version (v2.3 as mentioned in the PR objectives) and clarifies what the output should look like. This will help users confirm they have installed a compatible version by providing concrete expectations for the query result.docs/en/how_to/install_pgvector_extension.mdx (3)
24-36: ⚡ Quick winAdd fallback or troubleshooting guidance if pgvector is not available.
Line 32 notes that "version may differ depending on the operand release," implying that users should expect variation. However, there is no guidance on what to do if the extension is not found at all (empty result set). Consider adding a brief troubleshooting note: e.g., "If the query returns no rows, ensure the PostgreSQL Operator version is v4.3.0 or later."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/en/how_to/install_pgvector_extension.mdx` around lines 24 - 36, Add troubleshooting guidance after the expected output section of the pgvector extension verification step. Include a note that explains what to do if the query returns no rows (empty result set), such as advising the user to verify that the PostgreSQL Operator version is v4.3.0 or later. This will help users understand what to check when the vector extension is not found on their system, rather than leaving them without guidance for this failure case.
70-97: ⚖️ Poor tradeoffAdd guidance on parameter tuning and trade-offs for production use.
The indexing sections provide example configurations but lack context on when and how to tune them:
- IVFFlat (lines 72–82): The heuristic
rows / 1000is a reasonable starting point, but there is no guidance on post-deployment tuning. Should users run benchmarks to adjustlistsorivfflat.probes?- HNSW (lines 84–94): The claim "slower build time and higher memory usage than IVFFlat" is accurate, but concrete resource implications (e.g., CPU/memory during index creation) are not provided. What does "slower" mean—minutes, hours? How much additional memory is typical?
- Parameter defaults (m=16, ef_construction=64): While these are reasonable pgvector defaults, there is no guidance on adjusting them for workloads with different cardinality, dimensionality, or latency requirements.
Consider adding a brief tuning section or link to pgvector documentation on parameter selection for different workload profiles.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/en/how_to/install_pgvector_extension.mdx` around lines 70 - 97, The documentation sections for IVFFlat and HNSW index creation lack practical guidance on parameter tuning for production use. Add content that explains when and how to tune the `lists` and `ivfflat.probes` parameters for IVFFlat (including guidance on benchmarking and post-deployment adjustments), quantifies the performance and memory trade-offs mentioned for HNSW (e.g., typical build time ranges and memory overhead compared to IVFFlat), and provides clear guidance on adjusting the HNSW parameters (m and ef_construction) based on workload characteristics like cardinality, dimensionality, and latency requirements. Consider including a dedicated tuning section or linking to relevant pgvector documentation that explains parameter selection strategies for different production scenarios.
40-103: ⚡ Quick winClarify command execution context: kubectl exec vs direct psql.
The verification command (lines 27–30) uses
kubectl execto run psql within the pod, but the SQL examples (lines 40–103) for CREATE EXTENSION, smoke test, indexing, and verification do not show the execution context. Users may be unsure whether to:
- Run these SQL commands directly via the kubectl exec wrapper shown above, or
- Use a local psql client with appropriate connection flags.
For consistency, either:
- Show all SQL examples wrapped in
kubectl exec(or reference the pattern from step 1), or- Clarify that the SQL commands can be executed via any psql session (local, kubectl exec, or application client) connected to the database.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/en/how_to/install_pgvector_extension.mdx` around lines 40 - 103, The SQL examples in the "Smoke test", "IVFFlat", "HNSW", and "Upgrading the extension" sections lack clarity about their execution context, creating ambiguity about whether users should run them via kubectl exec (as shown in the earlier verification step) or via a local psql client. Either wrap all SQL code blocks with the kubectl exec pattern that was introduced earlier in the document, or add a clarifying statement above the SQL examples explaining that these commands can be executed via any psql session connected to the database (local, kubectl exec, or application client). This will provide consistent guidance throughout the documentation.docs/en/trouble_shooting/fix_streaming_replication.mdx (1)
27-34: ⚡ Quick winAdd explicit SQL execution context.
The SQL queries in the "Check replication state on the leader" section lack an explicit command for executing them (e.g., via
psqlin akubectl execwrapper). For operators unfamiliar with the Patroni/PostgreSQL troubleshooting workflow, this creates ambiguity about how to run the queries.Suggested enhancement to show SQL execution
### 2. Check replication state on the leader +```bash +kubectl exec -n $NAMESPACE $CLUSTER_NAME-0 -c postgres -- psql -U postgres -d postgres -c " ```sql -- On the leader: a healthy standby appears here in state 'streaming' SELECT application_name, state, sent_lsn, replay_lsn, sync_state @@ -32,6 +33,9 @@ SELECT application_name, state, sent_lsn, replay_lsn, sync_state -- An inactive slot / stale restart_lsn indicates a stuck standby SELECT slot_name, active, restart_lsn FROM pg_replication_slots;+```
Alternatively, restructure to explicitly instruct running the SQL via `psql` on the leader container. </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@docs/en/trouble_shooting/fix_streaming_replication.mdxaround lines 27 - 34,
The SQL queries in the replication state checking section (the SELECT queries
from pg_stat_replication and pg_replication_slots) lack explicit execution
instructions, creating ambiguity for users unfamiliar with the workflow. Wrap
these SQL queries with a clear execution command showing how to run them, either
by adding a kubectl exec wrapper around the psql invocation that demonstrates
connecting to the PostgreSQL container on the leader, or by adding explicit
step-by-step instructions immediately before the SQL block that explain how to
execute these queries via psql on the leader container. Ensure the execution
method is clearly visible and easy to follow.</details> <!-- cr-comment:v1:c7a23cbc4449b2d1a0914d2d --> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.Inline comments:
In@docs/en/how_to/configure_pg_hba_whitelist.mdx:
- Around line 48-49: The pg_hba configuration example at lines 48-49 with the
catch-all rules for host all all 0.0.0.0/0 md5 and host all all ::0/0 md5
presents highly permissive and insecure authentication settings without any
security warning, creating a disconnect with the security warning already
present in the SSL-off troubleshooting guide. Add an inline comment in the YAML
example explaining that these permissive rules allow unencrypted password
authentication from any network address and should only be used in development
or controlled environments, or consider moving these specific lines to a
separate clearly-marked example with a warning admonition, or omit them from the
default example and add a reference directing readers to the troubleshooting
guide when non-SSL access is required.In
@docs/en/trouble_shooting/pg_wal_disk_full.mdx:
- Around line 51-54: The documentation snippet shows a kubectl get command
followed by a comment about setting spec.numberOfInstances, which lacks clarity
on the actual editing procedure. Replace the get command and comment with
concrete editing instructions that demonstrate how to actually modify the
PostgreSQL resource. Include a choice of methods such as using kubectl edit to
open the resource in an editor and then modify the spec.numberOfInstances field,
or alternatively show how to use kubectl patch to apply the change directly with
the updated numberOfInstances value set to 1. Update the comment to clearly
indicate that the edit happens within the editor rather than being a separate
step.
Nitpick comments:
In@docs/en/how_to/install_pgvector_extension.mdx:
- Around line 24-36: Add troubleshooting guidance after the expected output
section of the pgvector extension verification step. Include a note that
explains what to do if the query returns no rows (empty result set), such as
advising the user to verify that the PostgreSQL Operator version is v4.3.0 or
later. This will help users understand what to check when the vector extension
is not found on their system, rather than leaving them without guidance for this
failure case.- Around line 70-97: The documentation sections for IVFFlat and HNSW index
creation lack practical guidance on parameter tuning for production use. Add
content that explains when and how to tune thelistsandivfflat.probes
parameters for IVFFlat (including guidance on benchmarking and post-deployment
adjustments), quantifies the performance and memory trade-offs mentioned for
HNSW (e.g., typical build time ranges and memory overhead compared to IVFFlat),
and provides clear guidance on adjusting the HNSW parameters (m and
ef_construction) based on workload characteristics like cardinality,
dimensionality, and latency requirements. Consider including a dedicated tuning
section or linking to relevant pgvector documentation that explains parameter
selection strategies for different production scenarios.- Around line 40-103: The SQL examples in the "Smoke test", "IVFFlat", "HNSW",
and "Upgrading the extension" sections lack clarity about their execution
context, creating ambiguity about whether users should run them via kubectl exec
(as shown in the earlier verification step) or via a local psql client. Either
wrap all SQL code blocks with the kubectl exec pattern that was introduced
earlier in the document, or add a clarifying statement above the SQL examples
explaining that these commands can be executed via any psql session connected to
the database (local, kubectl exec, or application client). This will provide
consistent guidance throughout the documentation.In
@docs/en/how_to/install_zhparser_extension.mdx:
- Around line 67-90: The configuration table in the "Parser configuration"
section lists options fromzhparser.punctuation_ignorethrough
zhparser.multi_zall, but the text below the table references
zhparser.extra_dictsas an option that must be set before the backend starts.
Either addzhparser.extra_dictsto the options table with its purpose (if it's
a commonly-used option users should know about), or add a clarifying note in the
text explaining that the table covers the most common options and
zhparser.extra_dictsis an advanced configuration option covered separately.- Around line 98-102: The Verification section contains a SQL query to check the
zhparser extension but lacks clarity on what version users should expect. Add
explanatory text after the verification SQL query that specifies the expected
version (v2.3 as mentioned in the PR objectives) and clarifies what the output
should look like. This will help users confirm they have installed a compatible
version by providing concrete expectations for the query result.In
@docs/en/trouble_shooting/fix_streaming_replication.mdx:
- Around line 27-34: The SQL queries in the replication state checking section
(the SELECT queries from pg_stat_replication and pg_replication_slots) lack
explicit execution instructions, creating ambiguity for users unfamiliar with
the workflow. Wrap these SQL queries with a clear execution command showing how
to run them, either by adding a kubectl exec wrapper around the psql invocation
that demonstrates connecting to the PostgreSQL container on the leader, or by
adding explicit step-by-step instructions immediately before the SQL block that
explain how to execute these queries via psql on the leader container. Ensure
the execution method is clearly visible and easy to follow.</details> <details> <summary>🪄 Autofix (Beta)</summary> Fix all unresolved CodeRabbit comments on this PR: - [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended) - [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes </details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Organization UI **Review profile**: CHILL **Plan**: Pro **Run ID**: `95764454-28c2-438a-a82e-42df0c44b031` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between d596803b1ab9902c7a6e85938ba110caf6a75e99 and db4dc3239ea33f222ce3706980ef60d0a652b373. </details> <details> <summary>📒 Files selected for processing (9)</summary> * `docs/en/how_to/configure_pg_hba_whitelist.mdx` * `docs/en/how_to/disable_nodeport_exposure.mdx` * `docs/en/how_to/install_pgvector_extension.mdx` * `docs/en/how_to/install_zhparser_extension.mdx` * `docs/en/how_to/run_postgresql_as_root.mdx` * `docs/en/trouble_shooting/connection_ssl_off.mdx` * `docs/en/trouble_shooting/coredump_huge_pages.mdx` * `docs/en/trouble_shooting/fix_streaming_replication.mdx` * `docs/en/trouble_shooting/pg_wal_disk_full.mdx` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Deploying alauda-postgresql with
|
| Latest commit: |
2580206
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://bef1c9e6.alauda-postgresql.pages.dev |
| Branch Preview URL: | https://docs-add-pg-kb-howtos-31526.alauda-postgresql.pages.dev |
- pg_hba whitelist: warn about permissive catch-all 0.0.0.0/0 / ::0/0 rules - pg_wal disk full: show concrete kubectl patch instead of a get + comment - zhparser: add zhparser.extra_dicts to the options table Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 participant
Summary
Precipitates historical internal Confluence KB PostgreSQL solutions into the product manual (
pg-docs), part of MIDDLEWARE-31526 (KB 沉淀 / 对标 OCP). Each guide was modernized to the currentacid.zalan.do/v1postgresqlCR and verified live on ACP 4.2 and 4.3 (PostgreSQL 16, operator v4.3.0).how_to (5)
trouble_shooting (4)
Verification
All procedures were re-run on live clusters on ACP 4.2/4.3 standing environments. Notes: distance operators / extension versions confirmed (pgvector 0.8.2, zhparser 2.3);
huge_pagesparameter replaces the obsolete per-version ConfigMap-mount hack; pg_hba applied viaspec.patroni.pg_hbaand reloaded without restart.🤖 Generated with Claude Code
Summary by CodeRabbit