polygres-troubleshooting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Polygres Troubleshooting

Polygres故障排查

Use read-only checks first. Resolve context, preserve evidence, classify the failure boundary, and recommend the smallest safe correction. Do not mutate while diagnosing.

优先使用只读检查。解决上下文问题、保留证据、划分故障边界，并推荐最安全的最小纠正措施。诊断期间请勿进行变更操作。

Workflow

工作流程

Read the installed
```
polygres --help
```
and command-specific help before using a command. Installed behavior is the source of truth for CLI compatibility.
Resolve identity, configuration source, and one exact project using
```
references/context-and-connectivity.md
```
. Stop on an ambiguous project.
Capture the symptom, timestamp, sanitized command or SDK call, exit code or exception type,
```
request_id
```
, job ID, and whether pagination returned a cursor. For generated pipelines, also capture the manifest state, plan digest, approved action IDs, checkpoint, and last successfully completed stage.
Inspect project and database evidence with
```
references/projects-and-database.md
```
.
If
```
project_mode
```
is
```
synced
```
, use
```
references/synced-projects.md
```
and skip target database, row, import, and migration checks.
For import job or migration failures, use
```
references/jobs-and-migrations.md
```
. For graph, vector, text, hybrid, or general readiness failures, use
```
references/retrieval.md
```
. For pgContext capability, collection, point, operation, recall, or Joint failures, use
```
references/context.md
```
.
Classify the fault as CLI/local configuration, control-plane, Runtime API, Postgres/database or pooler, or asynchronous job state. Use
```
references/errors-and-escalation.md
```
for typed SDK errors and escalation.
Re-check status before retry. Recommend a corrective action, but obtain explicit approval and delegate supported mutations to
```
$polygres-cli
```
or application changes to
```
$polygres-sdk
```
.

For a single-row write that lost the response after submission, treat the commit outcome as ambiguous unless public evidence resolves it. Do not automatically retry a row-only insert, upsert, or ignore. For a Context-backed write, replay the exact request with its exact idempotency key within the 24-hour replay window; the composite ledger prevents another row mutation. After

ROW_CONTEXT_IDEMPOTENCY_EXPIRED

, inspect the row and Context point before choosing a new key.

在使用命令前，先阅读已安装的
```
polygres --help
```
及命令专属帮助文档。已安装版本的行为是CLI兼容性的唯一依据。
通过
```
references/context-and-connectivity.md
```
确定身份、配置源以及一个明确的项目。若项目存在歧义，需停止操作。
记录症状、时间戳、经过脱敏处理的命令或SDK调用、退出码或异常类型、
```
request_id
```
、任务ID，以及分页是否返回游标。对于生成的流水线，还需记录清单状态、计划摘要、已批准的操作ID、检查点以及最后成功完成的阶段。
通过
```
references/projects-and-database.md
```
检查项目和数据库证据。
若
```
project_mode
```
为
```
synced
```
，请使用
```
references/synced-projects.md
```
，并跳过目标数据库、行、导入和迁移检查。
针对导入任务或迁移失败，请使用
```
references/jobs-and-migrations.md
```
。针对图、向量、文本、混合或通用就绪性失败，请使用
```
references/retrieval.md
```
。针对pgContext功能、收集、点、操作、召回或联合失败，请使用
```
references/context.md
```
。
将故障归类为CLI/本地配置问题、控制平面问题、Runtime API问题、Postgres/数据库或连接池问题，或异步任务状态问题。针对类型化SDK错误和升级流程，请使用
```
references/errors-and-escalation.md
```
。
重试前重新检查状态。建议采取纠正措施，但需获得明确批准，并将支持的变更操作委托给
```
$polygres-cli
```
，或将应用程序变更委托给
```
$polygres-sdk
```
。

对于提交后丢失响应的单行写入操作，除非公开证据能明确结果，否则需将提交结果视为不明确。请勿自动重试仅涉及行的插入、更新插入或忽略操作。对于基于Context的写入操作，请在24小时重放窗口内使用其确切的幂等键重放请求；复合分类账可防止再次发生行变更。在

ROW_CONTEXT_IDEMPOTENCY_EXPIRED

后，请先检查行和Context点，再选择新的键。

Evidence rules

证据规则

Use only commands confirmed by installed help and public
```
$polygres-sdk
```
methods. Never guess a private endpoint or use internal observability.
Preserve request and job IDs exactly. Distinguish absent evidence from a successful check.
Never log a database password, API key, authorization header, connection string containing credentials, or full environment output.
Do not retry validation, authentication, permission, or compatibility errors as if they were transient. Bound any retry for a rate limit or timeout.
Do not request approval again for a corrective action already covered by an unchanged consolidated pipeline review. Ask again when its project, source scope, action set, egress, destructive effect, or plan digest changed.
Report pagination and partial failure explicitly; a successful first page or one healthy subsystem does not prove the whole operation succeeded.

仅使用已安装帮助文档确认的命令和公开的
```
$polygres-sdk
```
方法。切勿猜测私有端点或使用内部可观测性工具。
准确保留请求ID和任务ID。区分证据缺失与检查成功的情况。
切勿记录数据库密码、API密钥、授权标头、包含凭据的连接字符串或完整环境输出。
请勿将验证、认证、权限或兼容性错误视为临时错误进行重试。对速率限制或超时的重试需设置次数上限。
若纠正操作已涵盖在未变更的合并流水线审核中，则无需再次请求批准。当项目、源范围、操作集、出口、破坏性影响或计划摘要发生变化时，需重新请求批准。
明确报告分页和部分失败情况；第一页成功或一个子系统健康并不代表整个操作成功。

Diagnostic report

诊断报告

Resolved identity: account identity or the exact reason it is unknown.
Resolved project: exact project ID or the ambiguity that blocked selection.
Symptom: observable failure and affected operation.
Observed evidence: sanitized statuses, exception classes, and timestamps.
Likely cause: evidence-backed classification with confidence.
Safe checks performed: public read-only commands and SDK calls used.
Corrective action: smallest documented action, not yet performed.
Approval or escalation: approval needed or escalation destination.
IDs retained: request IDs, job IDs, and cursors without secrets.
Unknowns: missing, stale, incompatible, or contradictory evidence.

已确认身份： 账户身份，或身份未知的确切原因。
已确认项目： 确切的项目ID，或阻碍选择的歧义问题。
症状： 可观测到的故障及受影响的操作。
观测证据： 经过脱敏处理的状态、异常类别和时间戳。
可能原因： 基于证据的分类及置信度。
已执行的安全检查： 使用的公开只读命令和SDK调用。
纠正措施： 最小化的已文档化操作（尚未执行）。
批准或升级： 是否需要批准，或升级的目标对象。
保留的ID： 请求ID、任务ID和不含密钥的游标。
未知项： 缺失、过时、不兼容或矛盾的证据。

Boundaries

边界限制

Do not mutate while diagnosing, rotate credentials, retry jobs or Context operations, apply migrations, reconcile points, rebuild graph resources, or start a text, vector, or Context reindex.
Do not call an undocumented or private route and do not query a private observability system.
Do not claim root cause when evidence supports only a likely boundary.

诊断期间请勿进行变更操作，包括轮换凭据、重试任务或Context操作、应用迁移、协调点、重建图资源，或启动文本、向量或Context重新索引。
请勿调用未公开或私有路由，也请勿查询私有可观测性系统。
当证据仅支持可能的故障边界时，请勿声称已找到根本原因。