postgres-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Postgres CLI (V2)

Postgres CLI（V2版）

Use

postgres-cli

to query PostgreSQL through named connection targets.

使用

postgres-cli

通过已命名的连接目标查询PostgreSQL数据库。

Platform Support

平台支持

```
scripts/postgres-cli
```
is a launcher script.

Prebuilt binaries are expected in

scripts/bin/

for:

macOS arm64 (
```
postgres-cli-darwin-arm64
```
)
Linux x86_64 (
```
postgres-cli-linux-x86_64
```
)
Windows x86_64 (
```
postgres-cli-windows-x86_64.exe
```
)

If no compatible binary exists and source + Cargo are available, launcher falls back to
```
cargo run --release
```
.

```
scripts/postgres-cli
```
是一个启动脚本。
预编译二进制文件需放置在
```
scripts/bin/
```
目录下，支持以下平台：
- macOS arm64（
```
postgres-cli-darwin-arm64
```
  ）
- Linux x86_64（
```
postgres-cli-linux-x86_64
```
  ）
- Windows x86_64（
```
postgres-cli-windows-x86_64.exe
```
  ）
若不存在兼容的二进制文件，且源码和Cargo可用，启动脚本会回退到
```
cargo run --release
```
方式运行。

Available Scripts

可用脚本

```
scripts/postgres-cli
```
- Launcher that selects a platform binary.
```
scripts/build-release-binary.sh
```
- Builds and places a binary for current host into
```
scripts/bin/
```
.

scripts/refresh-binaries-from-release.sh <tag>

- Downloads release binaries into

scripts/bin/

```
scripts/postgres-cli
```
- 用于选择对应平台二进制文件的启动器。
```
scripts/build-release-binary.sh
```
- 为当前主机构建二进制文件并放置到
```
scripts/bin/
```
目录。

scripts/refresh-binaries-from-release.sh <tag>

- 从发布版本下载二进制文件到

scripts/bin/

目录。

When To Use

使用场景

The user asks to inspect Postgres data.
The user asks to run SQL against a configured target.
The user asks for schema introspection.
The user asks to validate DB CLI config or debug connectivity.
The user asks to refresh schema cache for agent context.

用户需要检查Postgres数据时。
用户需要针对已配置的目标运行SQL时。
用户需要进行模式自省操作时。
用户需要验证数据库CLI配置或调试连接问题时。
用户需要刷新Agent上下文的模式缓存时。

Setup

安装配置

Read Setup Guide.

请阅读安装指南。

V2 Command Contract

V2 命令约定

Global flags (before subcommand):

```
--project-root <path>
```
(optional; default cwd)
```
--target <name>
```
(optional if
```
default_target
```
set)
```
--format <json|text|csv|tsv>
```
(default
```
json
```
)
```
--output <path>
```
(optional output file)
```
--no-summary
```
(suppresses text summary)

Subcommands:

query

input: exactly one of
```
--sql
```
,
```
--sql-file
```
,
```
--stdin
```
flags:
```
--mode <read|write>
```
(default
```
read
```
),
```
--timeout-ms
```

explain

input: exactly one of
```
--sql
```
,
```
--sql-file
```
,
```
--stdin
```

flags:

--analyze

--verbose

--buffers

--settings

--wal

--timeout-ms

introspect

required:

--kind <schemas|tables|columns|indexes|constraints|views|materialized-views|functions|triggers|enums|rowcounts|rowcounts-exact>

optional filters:
```
--schema
```
(repeatable),
```
--table schema.table
```
(repeatable)

schema-cache update

flags:

--all-tables

--with-markdown

--table-file-naming <table|schema-table>

--timeout-ms

```
targets list
```
```
config validate
```
```
doctor
```

全局标志（子命令之前）：

```
--project-root <path>
```
（可选；默认当前工作目录）
```
--target <name>
```
（若已设置
```
default_target
```
则可选）
```
--format <json|text|csv|tsv>
```
（默认
```
json
```
）
```
--output <path>
```
（可选输出文件路径）
```
--no-summary
```
（禁用文本摘要）

子命令：

```
query
```
- 输入：必须指定
```
--sql
```
  、
```
--sql-file
```
  、
```
--stdin
```
  中的一个
- 标志：
```
--mode <read|write>
```
  （默认
```
read
```
  ）、
```
--timeout-ms
```

explain

输入：必须指定
```
--sql
```
、
```
--sql-file
```
、
```
--stdin
```
中的一个

标志：

--analyze

、

--verbose

、

--buffers

、

--settings

、

--wal

、

--timeout-ms

introspect

必填：

--kind <schemas|tables|columns|indexes|constraints|views|materialized-views|functions|triggers|enums|rowcounts|rowcounts-exact>

可选过滤器：
```
--schema
```
（可重复使用）、
```
--table schema.table
```
（可重复使用）

schema-cache update

标志：

--all-tables

、

--with-markdown

、

--table-file-naming <table|schema-table>

、

--timeout-ms

```
targets list
```
```
config validate
```
```
doctor
```

Safety Rules

安全规则

Prefer read targets for normal data inspection.
```
query --mode read
```
blocks mutating SQL.
Mutating SQL requires
```
query --mode write
```
and
```
allow_write=true
```
on target.
```
explain --analyze
```
on mutating SQL requires write-enabled target.

正常数据检查时优先使用只读目标。
```
query --mode read
```
会阻止修改数据的SQL。
修改数据的SQL需要使用
```
query --mode write
```
且目标需设置
```
allow_write=true
```
。
对修改数据的SQL执行
```
explain --analyze
```
需要目标启用写入权限。

Command Patterns

命令示例

Run read query:

bash

scripts/postgres-cli --project-root /path/to/repo --target webshop-read query --sql "SELECT now();"

Run write query intentionally:

bash

scripts/postgres-cli --project-root /path/to/repo --target webshop-write query --mode write --sql "UPDATE users SET active = true WHERE id = 1;"

Introspect tables:

bash

scripts/postgres-cli --project-root /path/to/repo --target webshop-read introspect --kind tables

Explain a query:

bash

scripts/postgres-cli --project-root /path/to/repo --target webshop-read explain --sql "SELECT * FROM users WHERE id = 1;"

Validate config:

bash

scripts/postgres-cli --project-root /path/to/repo config validate

Doctor connectivity:

bash

scripts/postgres-cli --project-root /path/to/repo --target webshop-read doctor

Update schema cache (JSON only):

bash

scripts/postgres-cli --project-root /path/to/repo --target webshop-read schema-cache update

Update schema cache with markdown:

bash

scripts/postgres-cli --project-root /path/to/repo --target webshop-read schema-cache update --with-markdown

运行只读查询：

bash

scripts/postgres-cli --project-root /path/to/repo --target webshop-read query --sql "SELECT now();"

有意运行写入查询：

bash

scripts/postgres-cli --project-root /path/to/repo --target webshop-write query --mode write --sql "UPDATE users SET active = true WHERE id = 1;"

自省表结构：

bash

scripts/postgres-cli --project-root /path/to/repo --target webshop-read introspect --kind tables

解释查询语句：

bash

scripts/postgres-cli --project-root /path/to/repo --target webshop-read explain --sql "SELECT * FROM users WHERE id = 1;"

验证配置：

bash

scripts/postgres-cli --project-root /path/to/repo config validate

诊断连接问题：

bash

scripts/postgres-cli --project-root /path/to/repo --target webshop-read doctor

更新模式缓存（仅JSON格式）：

bash

scripts/postgres-cli --project-root /path/to/repo --target webshop-read schema-cache update

更新带Markdown格式的模式缓存：

bash

scripts/postgres-cli --project-root /path/to/repo --target webshop-read schema-cache update --with-markdown

Progressive Schema Loading

渐进式模式加载

When schema context is needed, use this order:

Read
```
.agent/postgres-cli/schema/index.json
```
.

Load only required files from

.agent/postgres-cli/schema/tables/*.json

Read
```
.agent/postgres-cli/schema/relations.json
```
when join/relationship reasoning is needed.
If markdown was generated, consult
```
.md
```
files only for human-friendly display.
If cache is missing or stale, run
```
schema-cache update
```
.

当需要模式上下文时，请按照以下顺序操作：

读取
```
.agent/postgres-cli/schema/index.json
```
文件。

仅从

.agent/postgres-cli/schema/tables/*.json

加载所需的文件。

当需要关联/关系推理时，读取
```
.agent/postgres-cli/schema/relations.json
```
文件。
若已生成Markdown文件，仅在需要友好的人类可读展示时参考
```
.md
```
文件。
若缓存缺失或过期，运行
```
schema-cache update
```
命令。

Agent Guidelines

Agent使用指南

Always pass
```
--target
```
unless
```
default_target
```
is known and stable.
Default to
```
--format json
```
for machine parsing.
Prefer
```
query --mode read
```
unless the user explicitly requests data mutation.
Return relevant result rows and summarize key findings.

除非已知
```
default_target
```
是稳定的，否则始终传递
```
--target
```
参数。
默认使用
```
--format json
```
以方便机器解析。
除非用户明确要求修改数据，否则优先使用
```
query --mode read
```
。
返回相关的结果行并总结关键发现。