diff --git a/docs/calibration-20260914-status.md b/docs/calibration-20260914-status.md new file mode 100644 index 00000000..65368df0 --- /dev/null +++ b/docs/calibration-20260914-status.md @@ -0,0 +1,199 @@ +PG10—PG20 校准阶段报告(2026-09-14T14:42:30.720497+08:00) + +原清单 F-001—F-026 均已有逐版修复、原已正确或不适用的源码记录及分批核验。后续审校继续发现并修复了配置、函数、psql、pgbench、数据类型及其四个包含文件中的问题。**全书逐句语义校准、最终独立对账和 33 项最终构建仍未完成。** 本报告不将机器扫描、历史通过记录或台账数量当作全文验收。 + +最新完成范围是 libpq、大对象和前后端协议三章的十一版完整校准。libpq 已核验提交 `73975603fb7706520b66c3b416b594a28ffd0f9e`;本阶段交付包含大对象与协议的 24 个正文文件和 4 份报告。协议新增修复包括 PG18—20 密钥字段类型、PG18 启动协议编码、PG14—17 次版本、PG14 缺失认证消息及未来 MERGE/两阶段说明、PG18+ 过时的生成列限制。逐项十一版矩阵见 [协议全章报告](/Users/vonng/pgsty/pgdoc/docs/calibration-protocol-whole-20260914.md);大对象 API 类型与操作系统用户权限见 [大对象报告](/Users/vonng/pgsty/pgdoc/docs/calibration-lobj-20260914.md)。两章当前正文均已通过本批原生核验。 + +英文固定为 10.23、11.22、12.22、13.23、14.24、15.19、16.15、17.11、18.6、19beta3 和 PG20 提交 86f7c82cf1023e3599f40f939727791a7090cd44。PG18 优先阅读;其他版本逐一核对完整段落、表格行和版本差异,同义英文共用译文,保留自身功能、签名、默认值、限制、代码和链接。遵守 exclude、glossary 及语境规则、style 的优先顺序。 + +阶段提交已核验:`d961bc1f3652f667f2a48b5638111ed099177ce4`(143 个文件),以及 `cfdd4bea4eca0eae6503d3ea36c5070e458cfc14`(355 个 PG10—20 正文文件和 3 份报告)。后一个提交的 358 个路径、提交 blob 与审定记录逐一相同。已核验阶段提交 `46de150b9b3a4d3ed1b677c0189ef9cfb9ecef03`(16 个文件)另含 libpq 连接、状态、执行、异步、管道、分块读取与取消接口的修复及四份对应报告;这些范围均已完成本批新快照核验。其他任务的 PG9.6 工作保留,没有推送或发布。 + +下表“修”表示本项或其横向核查中同范围的关联问题已修复;“核”表示针对该问题原本正确;“—”表示同版不适用;“例”表示明确保留的项目例外。“分项”表示一个原始问题包含多种版本状态,详见其子表。**这些是修复台账状态,最终当前源码对账进度另列,不能合并理解为最终通过。** + +| 问题 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| F-001 链接、术语链接和相关缺句 | 修 | 修 | 修 | 修/例 | 修/例 | 修/例 | 修/例 | 修/例 | 修/例 | 修/例 | 修/例 | +| F-002 锁表容量公式 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| F-003 pgbench greatest / least 返回类型 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| F-004 pg_split_walfile_name 换算说明 | — | — | — | — | — | — | 修 | 修 | 修 | 修 | 修 | +| F-005 SQL/JSON 引言 | — | — | — | — | — | — | 修 | 修 | 修 | 修 | 修 | +| F-006 复制配置引言 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| F-007 通用文件访问函数 EXECUTE 权限 | — | — | — | — | — | — | 修 | 修 | 修 | 修 | 修 | +| F-008 EXTRACT(WEEK) | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| F-009 系统信息与对象标识 | 核 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | +| F-010 未来版本表行、列及相关语义 | 分项 | 分项 | 分项 | 分项 | 分项 | 分项 | 分项 | 分项 | 分项 | 分项 | 分项 | +| F-011 PG14 备份控制函数表 | 核 | 核 | 核 | 修 | 修 | — | — | — | — | — | — | +| F-012 element_types.domain_default | 修 | 修 | 修 | 修 | 修 | 修 | 修 | — | — | — | — | +| F-013 协议变更总结 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| F-014 pgoutput 参数 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| F-015 配置章缺段、示例和版本差异 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| F-016 postgres_fdw ON CONFLICT 及相关说明 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | +| F-017 并行受限清单 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| F-018 SHOW 的区域设置变量 | 核 | 核 | 核 | 核 | 修 | 修 | 核 | 核 | 核 | 核 | 核 | +| F-019 操作符族/类 RECHECK 说明 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 核 | 核 | 核 | +| F-020 to_hex(-1234) 示例 | — | — | — | — | — | — | — | 核 | 核 | 核 | 核 | +| F-021 文档指南“纯文本文件” | 核 | 核 | 核 | 核 | 修 | 修 | 修 | — | — | — | — | +| F-022 NLS、pg_dump、CancelRequest 与锚点 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| F-023 polygon(circle) 示例损坏 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| F-024 libpq 参数状态和协议状态 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| F-025 句级与示例杂项 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| F-026 PG15 pg_walinspect | — | — | — | — | — | 修 | 核 | 核 | 核 | 核 | 核 | + +**F-001:链接、术语链接和相关缺句。** 恢复同版 xref/link/glossterm 与缺文,保留 PG13–20 已核实的 role/instance 链接例外;链接计数本身不作为语义证明。 + +**F-002:锁表容量公式。** max_locks_per_transaction / max_pred_locks_per_transaction 使用各自版本的公式;PG16 起的新公式与旧版分开,补齐谓词锁节。 + +**F-003:pgbench greatest / least 返回类型。** 按“任一参数为 double 时返回 double,否则返回 integer”定译;PG10–12 对应旧版结构核验。 + +**F-004:pg_split_walfile_name 换算说明。** 补齐备份节末的换算段、wal_segment_size、\gset 示例;PG16 起适用,PG19 原有示例保留并校准上下文。 + +**F-005:SQL/JSON 引言。** 补齐数据模型及相关能力说明;保留 PG16 与 PG17+ 各自项目数量和链接,不把新版引言灌入旧版。 + +**F-006:复制配置引言。** 补齐逻辑复制段,核准流复制、物理复制、逻辑复制的同版原文关系;未机械套用原报告对首段关系的判断。 + +**F-007:通用文件访问函数 EXECUTE 权限。** 原文说可选参数由独立的物理函数实现,因此需要分别授予权限;已按该含义修复 PG16–20,避免误解为 SQL 默认参数。 + +**F-008:EXTRACT(WEEK)。** 补齐 PG18–20 interval 按整周计算的单句;其余版本核对原有周编号说明。 + +**F-009:系统信息与对象标识。** 系统信息引言在 PG16+ 补齐。对象标识引导句在十一版原本都有;pg_get_acl 示例缺口实际涉及 PG18/20,PG19 原有。 + +**F-010:未来版本表行、列及相关语义。** 按 20 个表主题、关联段落和表头拆分核验:AT LOCAL、^@、MERGE 策略、系统目录/视图列、substream、pg_stat_statements 列名等。各版本具体处理见分项矩阵。 + +**F-011:PG14 备份控制函数表。** PG14 实际缺三行,包含 pg_stop_backup() 重载,并有旧版 start/stop 签名问题;同时修正 PG13 pg_is_in_backup 说明。PG15+ 按已移除功能处理。 + +**F-012:element_types.domain_default。** PG14–16 补行;PG10–13 虽有该行,却误写为数据库名,已改为同版英文的“尚未实现”。PG17+ 不适用。 + +**F-013:协议变更总结。** 恢复 PG14 完整清单,校准各版 BinaryRow 说明;从 PG15–17 移除误入的 PG18 COPY/CSV 说明。 + +**F-014:pgoutput 参数。** PG14 恢复 binary/messages;PG15 移除未来的协议版本 4、parallel/origin 内容;PG19/20 按拆分后的完整参数节核对。 + +**F-015:配置章缺段、示例和版本差异。** ANY/FIRST、fsync()/initdb --sync-only、O_DIRECT 等已核对。原“约 25 组”残余信号收敛为 15 个实际检查范围;之后已完成十一版 config.sgml 的完整共用单元审校。 + +**F-016:postgres_fdw ON CONFLICT 及相关说明。** 恢复 PG17 缺段,随后通读十一版 postgres_fdw 及 dblink;按版本保留连接、权限、事务和参数差异。 + +**F-017:并行受限清单。** PG14–16 补齐 InitPlan 等旧版项目及相关限制;其他版本严格按本版清单,保留 PG17+ 的变更。 + +**F-018:SHOW 的区域设置变量。** PG14/15 补齐 LC_COLLATE、LC_CTYPE;其余九版核验原有条目。 + +**F-019:操作符族/类 RECHECK 说明。** 补齐并统一 PG10–17 的旧版说明;PG18+ 原文已移除,核验后保持自己的结构。 + +**F-020:to_hex(-1234) 示例。** PG17–20 缺失的负数示例在阶段提交 d961bc1 中已修复;本轮复核时记为已正确。PG10–16 无此同版示例。 + +**F-021:文档指南“纯文本文件”。** 重新纠正旧台账:该节在 PG10–16 都存在。PG10–13 原已有;PG14/15 的并行修复已保留复核;PG16 已补齐。Pandoc >=1.13 仅 PG12–16 要求。PG17+ 已移除该节。 + +**F-022:NLS、pg_dump、CancelRequest 与锚点。** 恢复 PG14 AVAIL_LANGUAGES、--no-synchronized-snapshots 和 Int32(16);恢复 PG14/16 strict-and-lax-modes 上游锚点。后续 JSON 全节审校已覆盖正文。 + +**F-023:polygon(circle) 示例损坏。** 修复 PG14–20 七版的损坏数字输出,逐版保留同版完整结果;PG10–13 核验原样正确。 + +**F-024:libpq 参数状态和协议状态。** scram_iterations 缺口实际涉及 PG16–18,另补 PG18 search_path;清除 PG14–17 的未来协议字段,并统一同版指针有效期说明。 + +**F-025:句级与示例杂项。** 核对 --geqo 形式、pgpass HOME 句、BinaryRow、回归测试 screen;横向修复所有适用位置。 + +**F-026:PG15 pg_walinspect。** 恢复两个 till_end 函数,移除未来的 pg_get_wal_block_info;完整核对 PG15 五个函数及 end_lsn 行为。其他适用版本按自身函数集合保留。 + +完整原始修复依据见 [26 项状态与证据索引](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/status.json);[F-021 十一版完整中英段落](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/f021-current-complete-parents-20260914.json) 和 [F-021 当前快照核验](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/f021-current-native-proof-20260914.json) 已更新。原始独立审查材料保留不改;本轮更正只写入执行台账。 + +F-010 的 20 个表主题分别核对如下,关联说明和表头另有逐版记录。 + +| F-010 表主题 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| acl | — | — | 核 | 核 | 修 | 修 | 修 | 核 | 核 | 核 | 核 | +| crypt-algorithms | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 核 | 核 | 核 | 核 | +| crypt-iterations | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 核 | 核 | 核 | 核 | +| pg_backend_memory_contexts | — | — | — | — | 修 | 修 | 修 | 核 | 核 | 核 | 核 | +| pg_constraint | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 核 | 核 | 核 | +| pg_hba_file_rules | 核 | 核 | 核 | 核 | 修 | 修 | 核 | 核 | 核 | 核 | 核 | +| pg_ident_file_mappings | — | — | — | — | — | 修 | 核 | 核 | 核 | 核 | 核 | +| pg_index | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| pg_prepared_statements | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| pg_stat_statements | 核 | 核 | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | 核 | +| pg_stats | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| pg_stats_ext | — | — | 核 | 核 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| pg_stats_ext_exprs | — | — | — | — | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| pg_subscription | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| policy | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 核 | 核 | 核 | 核 | +| privilege-summary | — | — | 核 | 核 | 修 | 修 | 修 | 核 | 核 | 核 | 核 | +| string-other | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| timezone | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| typcategory | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| views | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 核 | 核 | 修 | 核 | + +数据类型四个包含文件中,下面 35 个问题或一致性检查组均有十一格记录。44 个文件以及 11 个 pg_lsn 表行补充已经应用;55 个范围与当前源码、固定英文及新解析快照精确一致,六个原有额外 ID 逐一复核后保留。1882 个完整父单元和 1114 处代码有精确证据;这些不是独立缺陷数量。 + +| 后续数据类型问题/检查组 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| JSON 词元术语 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| JSON 原生类型映射 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| JSON 原子业务数据 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| JSON 两个子对象的包含关系 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| jsonb_path_ops 的具体性 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| JSON 排序解释 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| JSON 下标 | — | — | — | — | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| PL/Perl hash | — | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| jsonpath 与 SQL 下划线区别 | — | — | — | — | — | — | 修 | 修 | 修 | 修 | 修 | +| GIN 同版等号示意记法 | — | — | 修 | 修 | 修 | 修 | 修 | 核 | 核 | 核 | 核 | +| jsonpath 命名变量说明 | — | — | 修 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 修 | +| jsonpath 最深嵌套层 | — | — | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| jsonpath 数组下标转换 | — | — | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| JSON null 与 SQL NULL | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 数组字面量显式类型 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 数组维数与同版错误输出 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 矩形数组切片与按日项目 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 数组元素 NULL 行为 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 数组切片 NULL 与空数组 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 数组扩展后的 NULL 填充 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 数组下界与下标 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 复合值显式目标类型 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 复合类型与记法术语 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| LATERAL 单次函数调用 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| RETURNING 的同版语句范围 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 计算字段可见索引 | 修 | 修 | 修 | 修 | 修 | 核 | 修 | 修 | 修 | 修 | 修 | +| 多范围列表数量 | — | — | — | — | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 无界范围与显式无穷值 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 范围的 hash 术语 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 范围操作符列表标点 | 修 | 修 | 修 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| 旧版 JSON 键操作符标点 | 修 | 修 | 修 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| JSON 可见注释及索引 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 数组可见注释及索引 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 复合类型可见标题 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 范围可见索引及内置函数 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | + +各格的原文路径、修改前后哈希、共用单元、适用范围和验证理由见 [数据类型逐格证据](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/datatype-included-issue-version-matrix.json)。较早关闭的 datatype.sgml 主文件另有 197 个范围核验,清除了旧版混入的 POSIX、XML 和 UUID 新版说明,并修正 numeric 舍入、interval 无穷值等语义。 + +psql 已完整核对命令、变量、正文、框架和示例,修复 AUTOCOMMIT 否定条件、命令输入和引用、正则模式、管道模式语义以及旧版混入的新选项;[173 个命令/变量/段落检查组 × 11 版](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/psql-full-issue-version-matrix.json) 对应 209 个精确范围。pgbench 已修复参数、返回类型、日志格式、可见注释和版本限制;[30 个问题组 × 11 版](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/pgbench-full-issue-version-matrix.json) 与 244 个含关联修复的范围核验对应。 + +全量记录按 [问题/共用单元逐项索引](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/status-report-20260914/ALL-ISSUES.md) 查看,逐格原始证据在 [当前对账数据](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/status-report-20260914/all-version-cells-reconciled.json)。当前共有 3537 个任务或共用单元、38907 个版本格;不能说成发现了 3537 个缺陷。 + +本次重新对账当前源码,25495 格直接精确匹配,188 格仅有受保护代码之外的行尾空白差异,531 格可由已记录的后续修复组合得到当前范围,1430 格由已核验的当前完整范围覆盖;290 格生成表记录已通过当前本地化输入重放并与新快照核对。另有 8113 格不适用记录、394 格误入/过时内容删除记录,保留各自的英文缺席证据。**仍有 2466 格需要重新绑定当前范围;这是证据对账待办,不能直接算成同数量的新缺陷,也不能当作通过。** + +下述历史对账快照之后,全文检索主章及关联校准已完成;当前继续从 libpq 推进完整中英阅读,并随每个问题横向覆盖十一版;其余未读范围包括部分系统目录、information_schema、libpq、ECPG、协议、命令参考和发行说明等。同时继续处理历史范围与当前源文的对账。最终还需完成十一版全书检查、HTML/A4/US 共 33 个构建及页面视检。现有分批解析退出码为 PG10–12 的 3、PG13–20 的 1,含合法差异及尚未关闭的全书信号,不能报告成全书检查通过。 + +后续进展(2026-09-14T15:08:46+08:00):全文检索章节现已完成十一版正文修复及新快照核验,新增 [37 个检查组的逐版说明](/Users/vonng/pgsty/pgdoc/docs/calibration-textsearch-20260914.md),包含具体缺陷、同版不适用项和英文疑点。函数表、系统目录、配置、SQL 命令参考及扩展文档的相关位置继续校准;这部分不包含在前述历史 38907 格的统计快照中。 + +后续进展(2026-09-14T15:45:49+08:00):已完成 [initdb、unaccent 与全文检索关联章节的 23 组 × 11 版核验](/Users/vonng/pgsty/pgdoc/docs/calibration-textsearch-followup-20260914.md)。257 个文件、1466 个完整父单元与当前/审定/新快照及固定英文一致,334 个提示逐项核定,0 漂移。移除 PG14—17 的 16 个未来 initdb 参数条目及 PG14—16 的未来 unaccent 引号规则,修正校验和、有效用户、词典权限、解析器说明与共同术语。本批 253 格另行记录,未计入前述历史 38907 格;全书余项、旧范围对账和 33 构建仍继续。 + +后续进展:已完成 [libpq 连接控制节 47 组 × 11 版核验](/Users/vonng/pgsty/pgdoc/docs/calibration-libpq-connection-20260914.md)。517 格包含 399 个修复、50 个原本正确和 68 个不适用记录;11 个新快照精确一致,100 个提示逐项绑定完整已读父块。该统计仅为连接节,未计入历史 38907 格。继续完整阅读连接状态和其余接口,并横向同步所有适用版本。 + +后续进展:已完成 [libpq 连接状态节 27 组 × 11 版核验](/Users/vonng/pgsty/pgdoc/docs/calibration-libpq-status-20260914.md)。297 格为 180 个修复、84 个原本正确和 33 个不适用;259 个完整 API 条目、270 个原样代码块及十一版新快照已核准,29 个既有属性锚点逐项绑定。继续执行查询节及其余全文;最终构建仍未完成。 + +后续进展:[libpq 执行与结果处理 69 组 × 11 版](/Users/vonng/pgsty/pgdoc/docs/calibration-libpq-execution-20260914.md)已完成正文及范围内新快照核验,759 格(600 修复、126 原本正确、33 不适用)。包括错误条件反译、未来 MERGE/分块状态、Oid 大小写与标识符转义否定句等。继续异步及其余接口;全书和最终 33 构建仍未完成。 + +后续进展:[libpq 异步、管道、分块读取和取消接口](/Users/vonng/pgsty/pgdoc/docs/calibration-libpq-flow-20260914.md)新增 55 组 × 11 版记录,605 格(297 修复、131 原本正确、170 不适用、7 固定英文疑义)。四个范围的正文及新快照核验已完成;继续快速路径、通知、COPY 和余下章节。 + +后续进展:[libpq 快速路径、通知与 COPY](/Users/vonng/pgsty/pgdoc/docs/calibration-libpq-transfer-20260914.md)新增 32 组 × 11 版记录,352 格(263 修复、62 原本正确、27 不适用)。32 个完整父节和新快照精确一致,零漂移、零范围提示;继续控制函数、杂项函数及余下全文。 + +后续进展:[libpq 控制、杂项、通知与事件](/Users/vonng/pgsty/pgdoc/docs/calibration-libpq-control-events-20260914.md)新增 54 组 × 11 版,594 格(357 修复、190 原本正确、42 不适用、5 源码例外)。44 个完整父节新快照核验零漂移,唯一提示已用本版源码分类;继续环境与构建说明等余下全文,最终 33 项构建尚未启动。 + +后续进展:[libpq 环境与构建说明](/Users/vonng/pgsty/pgdoc/docs/calibration-libpq-environment-20260914.md)新增 36 组 × 11 版,396 格(220 修复、118 原本正确、58 不适用);66 个完整范围通过新快照核验,零漂移、零范围提示。SSL 与 OAuth 等余下全文继续。 + +后续进展:[libpq SSL](/Users/vonng/pgsty/pgdoc/docs/calibration-libpq-ssl-20260914.md)新增 37 组 × 11 版,407 格(247 修复、133 原本正确、27 不适用)。十一版完整 SSL 节新快照零漂移,37 条提示均以原有锚点或逐行全文配对分类,零未决。OAuth 与跨文件问题继续。 + +后续进展:[OAuth 跨文件校准](/Users/vonng/pgsty/pgdoc/docs/calibration-libpq-oauth-20260914.md)新增 26 组、286 格(58 修复、19 原本正确、209 不适用)。PG18—20 四类文件的 15 个完整父块已应用并通过新快照核验,三组原生提示逐条完成全文配对;PG10—17 明确无此功能。示例章节发现的本版代码差异继续处理。 + +本阶段完成:[libpq 全章校准](/Users/vonng/pgsty/pgdoc/docs/calibration-libpq-whole-20260914.md),537 个节范围、2079 个本版英文代码块与审定父块对应;222 条新快照提示全部按当前行号匹配审定全文或源码勘误证据,零未决、零漂移。[示例与章首](/Users/vonng/pgsty/pgdoc/docs/calibration-libpq-examples-20260914.md)补齐最后范围。当前全章累计 398 个检查组、4378 个逐版格,包含正确项和例外,不是缺陷总数。全书校准、历史独立对账与最终33项构建继续。 + +[大对象全章校准](/Users/vonng/pgsty/pgdoc/docs/calibration-lobj-20260914.md)已完成十一版阅读、修订及新快照核验:25 组275格(95修复、158原本正确、11不适用、11源文疑点),176节和231代码块完整绑定,零范围提示、零漂移。API类型与文件权限依据各版头文件和后端实现核实;本章尚未纳入最终构建。 + +[协议概述与消息流校准](/Users/vonng/pgsty/pgdoc/docs/calibration-protocol-front-20260914.md)已完成十一版完整阅读和新快照核验,61组671格(516修复、89原本正确、66不适用),189节及11外框精确绑定;169提示逐项关闭。该范围之外的协议章节与全书仍在继续。 + +协议全章已完成十一版完整对照及本批原生验收:324 个协议范围、2 个迁移 pgoutput 参数节、51 个代码块,13 个目标文件与新快照精确一致;2725 条范围提示已逐项绑定,0 未决、0 漂移。139 个问题/回归组的十一格矩阵和新增字段错误详见 [协议全章报告](/Users/vonng/pgsty/pgdoc/docs/calibration-protocol-whole-20260914.md)。本次完成范围包括 SASL、复制命令、逻辑复制和全部消息格式;全书、历史最终对账与33最终构建仍未完成。 diff --git a/docs/calibration-libpq-connection-20260914.md b/docs/calibration-libpq-connection-20260914.md new file mode 100644 index 00000000..78a0665a --- /dev/null +++ b/docs/calibration-libpq-connection-20260914.md @@ -0,0 +1,65 @@ +**PG10—PG20:libpq 连接控制章节校准** + +本批按 PG18 优先完整阅读连接控制节,再逐一核对其余十版的完整条目与版本差异。47 个检查组、517 个版本格包含语义缺陷、缺句、版本适用性和术语校准,不是 47 个独立新增缺陷。已完成十一版正文修复及本批新快照核验。原 26 项及前序批次见[阶段总报告](/Users/vonng/pgsty/pgdoc/docs/calibration-20260914-status.md)。 + +主要语义修复包括:PG13—20 的 `PQconninfo` 应返回实际连接值;SSL 私钥回调不得通过异常或 `longjmp` 跳出,原译文表达了相反限制;PG14—20 的重置轮询对照函数应为 `PQconnectPoll`;PG18—20 补齐 `PQsocketPoll` 引导句;PG17—20 移除本版英文已删的两秒超时下限,并补足 SNI 代理与 `direct` 协商条件。较旧版本保留各自英文仍有的规则。 + +修=本轮修复;核=对照本版英文后原本正确;无=本版没有相应定义。每项均保存了英文、修复前后完整父块及哈希。 + +| 检查组 | 级别 | PG10 | PG11 | PG12 | PG13 | PG14 | PG15 | PG16 | PG17 | PG18 | PG19 | PG20 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| C19-LQ-001 参数数组长度、NULL 与空值的说明 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-002 首个 dbname 的连接字符串展开规则 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-003 参数数组与连接字符串的覆盖优先级 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-004 PQconnectdb 的空白分隔说明 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-005 PQsetdbLogin 其余参数按规则应用 | P2 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-006 非阻塞连接的追踪输出目的流 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-007 非阻塞连接遗漏 PQsocketPoll 引导句 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 修 | 修 | 修 | +| C19-LQ-008 中间连接状态的出现顺序和值均无保证 | P2 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-009 非阻塞连接的空指针、非阻塞及释放表述 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-010 PQconndefaults 后备值与结构字段说明 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-011 PQconninfo 返回实际使用值而非默认值 | P2 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-012 PQconninfoParse 内存不足时的两个 NULL | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-013 PQresetStart 对照的建连函数是 PQconnectPoll | P2 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-014 SSL 密钥回调禁止通过异常或 longjmp 跳出 | P2 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-015 SSL 密钥回调替代默认处理的强调标记 | P3 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-016 host 与 hostaddr 的默认平台范围 | P3 | 核 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-017 host 的套接字目录与绝对路径说明 | P3 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-018 hostaddr 与 host 同时指定时的认证条件 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-019 DNS 查询可能长时间阻塞 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-020 require_auth 必须恰好采用一种允许方法 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-021 connect_timeout 保留旧版下限、移除新版旧说明 | P2 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | +| C19-LQ-022 keepalive 重传间隔的秒数含义 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-023 TCP keepalive 术语与已审配置章一致 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-024 tcp_user_timeout 未确认数据的时限 | P3 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-025 gssencmode 禁用的是 GSSAPI 加密 | P2 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-026 GSSAPI 优先级不受 sslmode 参数值影响 | P2 | 无 | 无 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-027 requiressl 弃用状态与编译条件 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-028 SSL 压缩改善响应时间的方向 | P3 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-029 sslpassword 提示抑制句与 libpq 标记 | P3 | 无 | 无 | 无 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-030 sslcrl 的存在条件修饰文件 | P3 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-031 sslcrldir 的存在条件修饰目录 | P3 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-032 SNI 代理需要 direct 协商的新版条件 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | +| C19-LQ-033 SNI 标题词与索引的中文名称 | P3 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-034 SSL 最大协议版本的后端上限条件 | P3 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-035 Kerberos 服务名通过 configure 选项设置 | P3 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-036 GSS 委派的 credentials 统一译为凭据 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-037 SCRAM 透传密钥不应由用户直接指定 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQ-038 OAuth 授权范围及客户端类型的可读说明 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQ-039 fork 与可执行程序的说明 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-040 关键词示例 literal 与可翻译占位符区分 | P3 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-041 JDBC 兼容例外的条件与转换方向 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-042 主机名解析术语 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-043 URI 语法中三处说明性短语翻译 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-044 连接引言的同时保持多个连接与内存不足 | P3 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-045 非阻塞连接索引翻译 | P3 | 修 | 修 | 修 | 修 | 修 | 核 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-046 外部 SSL 引擎的指定形式 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQ-047 fallback_application_name 的后备值说明 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | + +完整阅读覆盖 110 个条目变体、38 个外层段落、11 个节框架和 604 个实际条目;68 个最终条目变体、12 个外层修改、4 个框架及 11 个措辞精炼已复读。256 个代码/语法块逐版校验,仅本地化 `PQconninfoOption` 的可读注释和 URI 语法内说明性 `phrase`;函数签名、URI 标识符和其余代码保持对应版本。 + +十一版当前源码、审定稿、新解析快照、固定英文及原生解包英文精确一致,零漂移。100 个范围内提示分别是 94 个既有本地锚点、6 组旧版未命名小节;全部逐项绑定到 106 个完整已读父块,核对模式名、相邻项目顺序和自身中英正文后保留。`git diff --check` 通过。 + +本批仅关闭 `libpq-connect` 范围。OAuth 授权范围在认证钩子中的三处关联说明仍随后续整节阅读处理。libpq 其余章节、全书其他待读范围、历史证据对账和最终 33 项 HTML/A4/US 构建均未完成。全书原始结构检查退出码仍为 PG10—12 的 3、PG13—20 的 1,不代表全书通过。 + +详细证据:[逐问题十一版矩阵](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-connect-full-issue-version-matrix.json)、[完整审定父块](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-connect-full-finalized-parent-plans.json)、[604 条目绑定](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-connect-full-finalized-entry-proof.json)、[新快照核验](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-connect-native-current-snapshot-proof.json)、[100 条逐项处置](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-connect-native-dispositions.json)、[106 完整父块](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-connect-native-parent-proof.json)。 diff --git a/docs/calibration-libpq-control-events-20260914.md b/docs/calibration-libpq-control-events-20260914.md new file mode 100644 index 00000000..93f97b51 --- /dev/null +++ b/docs/calibration-libpq-control-events-20260914.md @@ -0,0 +1,72 @@ +**PG10—PG20:libpq 控制函数、杂项函数、通知与事件系统校准** + +从 PG18 开始完整中英对照,并逐项核对其余十版。54 个检查组、594 个版本格:357 格修复、190 格原本正确、42 格不适用、5 格经源码核实的例外。检查组包含技术错误、措辞和版本边界,不等于 54 个新增缺陷。 + +主要修复包括:十一版将事件函数的“conn 参数可以为 NULL”误作返回 NULL;通知处理器的 void 指针误作空指针;事件注册数量“只受内存限制”被误译。PG16—20 补齐 PQconninfoFree 的 NULL 参数无操作说明。PG14 移除混入的未来事件规则,恢复本版连接重置失败状态、结果复制失败和清理责任。PG14—20 将结果实例数据错误地说成在连接中注册的问题已修正。同步核准错误详细程度、CONTEXT 条件、跟踪字段、阻塞查询、结果字段与内存归属。 + +固定英文 PG10—14 将 PQresultSetInstanceData 错写为不存在的 PQsetResultInstanceData;已逐版核对头文件、实现及导出表。PG10—13 修正正文与示例,PG14 保留既有正确译文和链接,英文快照未改。五格记为有证据的源码例外,未当成五个翻译缺陷。 + +修=已修复;核=该项原本正确;无=不适用;例=对应源码核实的例外。 + +| 检查组 | 级别 | PG10 | PG11 | PG12 | PG13 | PG14 | PG15 | PG16 | PG17 | PG18 | PG19 | PG20 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| C19-LQCM-001 编码名称重复字词和 ID 说明 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQCM-002 设置客户端编码、返回值与当前值接口 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQCM-003 SQLSTATE 可用条件误作任一项可用 | P2 | 无 | 无 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQCM-004 错误详细程度重复旧句、字段和已有结果 | P3 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQCM-005 CONTEXT ALWAYS 条件与显示模式 | P2 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQCM-006 PG10/11 无 SQLSTATE 的模式集合 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQCM-007 跟踪行的方向、分隔和消息类型 | P3 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQCM-008 Windows 跟踪编译标志与文件指针 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQCM-009 回归跟踪隐去字段的含义 | P3 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQCM-010 停止跟踪和引言措辞 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQCM-011 内存释放和 Windows DLL 条件 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQCM-012 PQconninfoFree 缺 NULL 参数无操作句 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | +| C19-LQCM-013 附属字符串误作子字符串 | P3 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQCM-014 查询可能阻塞、调用者自行查询算法 | P2 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQCM-015 密码算法版本、兼容别名、内存与错误 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQCM-016 PG17 起修改密码 API 及错误返回 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | 核 | 核 | +| C19-LQCM-017 空结果对象与 conn 不为 null 的区别 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQCM-018 事件 conn 可为 NULL 误作返回 NULL | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQCM-019 先填充结果再触发事件及防重复调用 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQCM-020 PG14 混入未来 PGEVT_RESULTCOPY 说明 | P2 | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQCM-021 结果副本释放、标志、事件过程措辞 | P3 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQCM-022 设置属性的忽略条件及返回值 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQCM-023 元组字段、下标位置和 SQL null 值 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQCM-024 附属存储生命周期与类型对齐 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQCM-025 结果内存统计以分配字节求和 | P3 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQCM-026 运行时版本、两位数字、连接选项和标记 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQCM-027 PG17 起微秒时间与套接字超时接口 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | 核 | 核 | +| C19-LQNE-001 通知传递必然性与处理函数返回后的继续执行 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQNE-002 接收器 void 指针误作空指针 | P2 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQNE-003 处理器 void 指针误作空指针 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQNE-004 消息传给接收器的主被动关系 | P2 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQNE-005 错误字段与预格式化消息 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQNE-006 通知回调仍可能被调用的生命周期 | P3 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQNE-007 设置处理函数、NULL 指针及两层处理 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQNE-008 通知可见索引及 PG10 短结束标签 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQNE-009 事件系统销毁与用途术语 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQNE-010 两类数据及透传指针注册说明 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQNE-011 PG14 注册事件混入未来表述 | P3 | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQNE-012 PG18 起 CONNECTION_OK 上游标记 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQNE-013 PG14 连接重置失败与状态缺失 | P2 | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQNE-014 创建结果时失败传播和 PG15 起行为 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQNE-015 PG14 复制失败及清理责任被新版替换 | P2 | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQNE-016 销毁事件清理责任、无法报告失败 | P3 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQNE-017 回调 typedef 是函数指针类型 | P3 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQNE-018 Windows 回调地址必须始终一致 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQNE-019 事件注册数量仅受内存限制 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQNE-020 结果实例数据误说在 conn 中注册 | P2 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQNE-021 实例数据是否计入内存统计 | P3 | 无 | 无 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQNE-022 逐连接注册、名称生命周期和实例查找 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQNE-023 透传指针与实例数据的生命周期和释放 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQNE-024 事件示例标题、框架引言及可见 C 注释 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQNE-025 固定英文函数名笔误的源码核实例外 | EXCEPTION | 例 | 例 | 例 | 例 | 例 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQNE-026 代码保留自身错误输出、TRUE 和事件行为 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQNE-027 相同英文 API 的共用译文和事件过程术语 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | + +完整阅读 77 个初始 API 变体及全部中文候选、20 个外段变体和 14 个框架,覆盖 343 个实际条目、154 个实际外段;复读 87 个最终 API 变体及全部修改外段、框架,另复读 32 个共用译文调整。387 个代码块保留各版本代码与签名;只本地化原有事件示例注释,并执行上述有源码证据的 API 名称例外。 + +44 个完整逐版父节与审定稿、固定英文、原生解包英文、新快照逐字一致,零漂移。唯一 PG14 链接提示对应已核实的源码笔误,已单独分类。全书原始审计仍为 PG10—12 退出 3、PG13—20 退出 1;这不是整书验收。余下全书校准与最终 33 项 HTML/PDF 构建仍待完成。 + +证据:[控制与杂项十一版矩阵](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-control-misc-full-issue-version-matrix.json)、[通知与事件十一版矩阵](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-notice-events-full-issue-version-matrix.json)、[新快照核验](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-control-events-native-validation.json)、[原生提示分类](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-control-events-native-classification.json)、[英文笔误的逐版源码证据](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-events-fixed-source-erratum-proof.json)。 diff --git a/docs/calibration-libpq-environment-20260914.md b/docs/calibration-libpq-environment-20260914.md new file mode 100644 index 00000000..17c8ced9 --- /dev/null +++ b/docs/calibration-libpq-environment-20260914.md @@ -0,0 +1,54 @@ +**PG10—PG20:libpq 环境、连接文件、LDAP、线程与构建说明校准** + +从 PG18 开始完整中英对照,并逐项核验其余十版。36 个检查组、396 个版本格:220 格修复、118 格原本正确、58 格不适用。检查组包含技术缺陷、措辞和版本边界,不等于 36 个新增缺陷。正文及本范围原生核验已完成。 + +主要修复:PG16—18 的 PGLOADBALANCEHOSTS,以及 PG18 的 PGMINPROTOCOLVERSION、PGMAXPROTOCOLVERSION,共五个条目误放在会话默认行为列表,已按本版英文移回连接参数列表。PG18—20 的连接服务文件引言补齐 service 关键字;十一版修正 Either service file、文件与环境变量优先级、密码文件的组及其他用户权限说明。PG14—20 恢复 LDAP 连接失败时的后备说明,并将“与 LDIF 一起创建”改为“使用 LDIF 创建”。 + +十一版同时校准构建与编译、链接的区别,修正未指定头文件或选项的条件,补译 pg_config/pkg-config 可见索引。保留各版 HOME 查找、servicefile、OAuth 环境变量、PG17 起线程安全及 PG18 起 Curl 条件等边界;恢复三版 Curl 条件强调标签。 + +修=已修复;核=该项原本正确;无=不适用。 + +| 检查组 | 级别 | PG10 | PG11 | PG12 | PG13 | PG14 | PG15 | PG16 | PG17 | PG18 | PG19 | PG20 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| C19-LQEN-001 PGLOADBALANCEHOSTS 混入会话默认行为列表 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 核 | 核 | +| C19-LQEN-002 PG18 最低与最高协议版本变量列表归属 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 核 | 核 | +| C19-LQEN-003 连接默认值条件和引言句序 | P3 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEN-004 逐变量参数映射及 TLS、认证、GSS 版本边界 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQEN-005 同时设置 PGREQUIRESSL 与 PGSSLMODE 的效果 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEN-006 旧版 PGSERVICEFILE 文件名说明标点 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 无 | 无 | +| C19-LQEN-007 PG19 起 PGSERVICEFILE 使用连接参数 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | +| C19-LQEN-008 PG19 起 PGOAUTHCAFILE 变量 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | +| C19-LQEN-009 会话默认项、系统配置及本地化目录 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQEN-010 PG18 起 HOME 和有效用户目录查找 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | 核 | +| C19-LQEN-011 密码文件权限中的所属组及其他用户 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEN-012 密码文件提示注释、通配与主机匹配说明 | P3 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEN-013 密码文件默认位置、转义与复制专用项 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQEN-014 PG18 起缺 service 关键字 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQEN-015 服务名称关联和无需重新编译的说明 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEN-016 Either service file 误作或者服务文件 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEN-017 服务文件、环境变量和连接字符串的优先级 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEN-018 逐用户和系统文件路径及 PG19 多余标签 | P3 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 修 | 核 | +| C19-LQEN-019 服务配置示例可见注释 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEN-020 LDAP 配置段与 RFC 格式引导句 | P3 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEN-021 LDAP 无法连接时继续处理和后备项 | P2 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEN-022 使用 LDIF 创建误作与 LDIF 一起创建 | P2 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEN-023 LDAP 混合配置注释保留参数标识符 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEN-024 PG17 起始终线程安全与早期编译选项 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQEN-025 PGconn 和 PGresult 并发访问限制 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQEN-026 弃用接口替代说明及 PQcancel 的本版差异 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEN-027 PG18 起 Curl 初始化条件的强调标签 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQEN-028 Kerberos 协作锁及 PG19 起回调接口 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQEN-029 多线程程序节标题 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEN-030 构建包含编译和链接的定义 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEN-031 未包含头文件及未指定选项的条件 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEN-032 链接 libpq 库误作编译进去 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEN-033 头文件目录、编译选项和可移植性说明 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEN-034 pg_config 与 pkg-config 可见索引漏译 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEN-035 遗漏 -lpq 说明的正文标点 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEN-036 构建命令、错误输出与选项顺序 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | + +完整阅读 81 个初始段落变体、3 个 API 变体和 15 个框架;按变量名重新配对全部 44 个环境变量变体,核对每版完整列表及顺序。复读 24 个最终修改变体、4 个外层段落变体、4 个线程和构建框架及 3 类标签空白修订。对应 687 个实际叶段、33 个环境外段、11 个 API 条目;209 个代码块保持本版代码和错误输出,仅调整两类原有注释。 + +66 个完整逐版范围与审定稿、固定英文、原生解包英文和新快照精确一致,零漂移、零范围内提示。`git diff --check` 通过。全书原始审计退出码仍为 PG10—12 的 3 和 PG13—20 的 1;全书语义校准、历史证据对账和最终 33 项构建仍未完成。 + +证据:[逐问题十一版矩阵](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-environment-full-issue-version-matrix.json)、[完整审定父块](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-environment-full-finalized-parent-plans.json)、[变量列表归属](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-environment-full-list-membership-proof.json)、[新快照核验](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-environment-native-validation.json)。 diff --git a/docs/calibration-libpq-examples-20260914.md b/docs/calibration-libpq-examples-20260914.md new file mode 100644 index 00000000..2d22ed78 --- /dev/null +++ b/docs/calibration-libpq-examples-20260914.md @@ -0,0 +1,27 @@ +**PG10—PG20:libpq 示例与章首校准** + +从 PG18 起完整阅读三个示例,再核对五个英文框架变体、全部十一版中文程序和版本差异。修复 PG16—20 仍保留的 HAVE_SYS_SELECT_H 条件编译;PG19 查询与注释中的 SQL 大小写及多余 standard_conforming_strings 设置按本版英文恢复。保留旧版头文件规则、连接错误输出、字节串转义及各版输出。 + +41 个原有 C 注释变体均已翻译并复读,内嵌 SQL、输出、文件名和可执行代码单独校验。同步校准示例所在发行包的引言,并恢复 PG13 起章标题的 — 实体。另复读六个章框架和命令执行外层框架,统一五个共用引言段落。 + +| 检查组 | 级别 | PG10 | PG11 | PG12 | PG13 | PG14 | PG15 | PG16 | PG17 | PG18 | PG19 | PG20 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| C19-LQEX-001 PG16 起无条件包含 sys/select.h | P2 | 核 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEX-002 PG19 查询示例 SQL 及注释大小写 | P3 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 修 | 核 | +| C19-LQEX-003 PG19 多余 standard_conforming_strings 设置 | P3 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 修 | 核 | +| C19-LQEX-004 程序原有可译注释 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEX-005 示例所在源代码发行包的引言 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEX-006 PG13 起章标题的上游 mdash 实体 | P3 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQEX-007 旧版连接失败输出与新版本差异 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQEX-008 各版示例字节串、转义与预期输出 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQEX-009 通知次数、事务和资源清理行为 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQEX-010 三个程序的接口、数组、消息与 SQL 顺序 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQOUT-001 章首 C 应用程序编程接口定义 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQOUT-002 底层应用接口与用户可见行为 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQOUT-003 章末示例及源代码发行包引言 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQOUT-004 头文件包含和库链接两项要求 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 核 | 修 | 修 | 修 | +| C19-LQOUT-005 连接建立后的命令执行引言 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | + +这 15 个检查组包含措辞、已正确条件和本版差异,不能视为 15 个新增缺陷。示例与章首修订已纳入十一版全章新快照核验,代码有完整审定父块及专门的 33 个程序比对记录。`git diff --check` 通过;尚未执行最终 HTML/PDF 构建或示例运行测试。 + +证据:[全部程序比对](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-examples-full-finalized-raw-proof.json)、[最终注释](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-examples-full-finalized-comment-final-read.json)、[全章源码覆盖](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-whole-source-coverage.json)。 diff --git a/docs/calibration-libpq-execution-20260914.md b/docs/calibration-libpq-execution-20260914.md new file mode 100644 index 00000000..1df973a6 --- /dev/null +++ b/docs/calibration-libpq-execution-20260914.md @@ -0,0 +1,92 @@ +**PG10—PG20:libpq 查询执行、结果读取和转义校准** + +本批从 PG18 开始,完整阅读四个执行子节,再逐项核对其余十版。69 个检查组、759 个版本格涵盖技术错误、漏译、版本适用性、术语及措辞;600 格修复、126 格本版原本正确、33 格不适用。这些检查组不等于 69 个新增缺陷。正文与本批新快照核验已完成。 + +主要修复如下: + +- PG13—20 的 `PQresultErrorMessage` 把“没有错误”条件译反;PG14—20 的详细错误消息说明误解了指定详细程度后的假设条件。 +- PG14—16 的主执行节混入未来 `PGRES_TUPLES_CHUNK`,PG17—20 的结果读取引言反而漏列本版已有的分块状态;PG14 的命令行数说明还混入两处未来 `MERGE`。 +- PG14—20 把 C 类型 `Oid` 写成 `oid`;PG13—20 漏译标识符转义条件中的否定,并弱化了释放结果内存的要求。 +- 校准类型修饰符、格式代码、实际数据长度、零字节结尾、null 值与空指针、预备语句、错误字段、bytea 引号和内存有效期。保留本版类型头文件、旧协议限制和命令集合。 + +修=本轮修复;核=就该问题核对本版英文后原本正确;无=本版不适用。技术上已正确的格子可能同时接受措辞润色。 + +| 检查组 | 级别 | PG10 | PG11 | PG12 | PG13 | PG14 | PG15 | PG16 | PG17 | PG18 | PG19 | PG20 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| C19-LQM-001 PQexec 严重错误的举例与空指针含义 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-002 resultFormat 无法逐列选择结果格式 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-003 参数 null、空指针及二进制表示的说明 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-004 nParams 仅统计预先指定类型的参数 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-005 PQprepare 返回空指针不等于空结果集 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-006 执行预备语句的名称、解析与规划 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-007 PQdescribePrepared 预备语句术语 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-008 PQdescribePortal 遵守 portal 不翻译规则 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-009 关闭预备语句及 portal 时无操作的说明 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | +| C19-LQM-010 旧版结果状态说明混入 PGRES_TUPLES_CHUNK | P2 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 核 | 核 | 核 | 核 | +| C19-LQM-011 单行模式统一译名 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-012 状态枚举值与状态码说明 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-013 PQresultErrorMessage 无错误条件反译 | P2 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-014 错误字符串由 PQclear 释放的生命周期 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-015 详细错误消息应按指定详细程度重新生成 | P2 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-016 非错误结果的诊断字符串保持本版原样 | P3 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-017 错误报告字段与 SQL 域的术语区分 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-018 非本地化严重性及 PostgreSQL 9.6 起的范围 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-019 诊断对象应为现存对象而非同类对象 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-020 错误上下文、事实与数据类型说明 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-021 错误信息折行与段落分隔 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-022 PQclear 的 NULL 无操作条款仅 PG16 起存在 | P2 | 无 | 无 | 无 | 无 | 修 | 修 | 核 | 核 | 核 | 核 | 核 | +| C19-LQM-023 参数引用与转义的优势 | P3 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-024 类型转换提示中服务器选择类型的主语 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-025 数值形式的类型 OID 与类型不匹配说明 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-026 PGresult 访问函数误译为存储器函数 | P2 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQM-027 协议 2.0 限制仅保留在本版原文仍有处 | CHECK | 核 | 核 | 核 | 核 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | +| C19-LQM-028 描述函数的 NULL 名称在十一版均有效 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQM-029 预备语句删除段落与新关闭函数的版本边界 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQR-001 PG14 命令行数说明混入未来 MERGE | P2 | 无 | 无 | 无 | 无 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQR-002 PG17 起结果读取引言漏列分块状态 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | +| C19-LQR-003 C 类型 Oid 大小写被误改 | P2 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-004 类型修饰符误译为修饰符类型 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-005 多数数据类型不使用修饰符的说明 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-006 格式代码遵守现行术语表 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-007 查询列与表列的列号区别 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-008 各种数据类型并非多个数据类型 | P3 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-009 零字节结尾与二进制数据内嵌零字节 | P2 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-010 字段值与 SQL 域术语区分 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-011 null 字段、空字符串与空指针区别 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-012 结果数据所属存储及生命周期 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-013 实际数据长度误作真值长度 | P2 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-014 二进制长度为必不可少的信息 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-015 PG16 起其他结果类型不再称查询类型 | P3 | 核 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-016 PQfsize 返回内部表示大小 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-017 列名转小写及 SQL 查询结果示例引导 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-018 PQprint 分页器、字段和空指针数组注释 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-019 PQprint 可选列名输出与旧用途 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-020 PQbinaryTuples 弃用范围与推荐函数 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-021 命令行数说明中的预备查询术语 | P3 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-022 PQoidStatus 弃用并非删除函数 | P3 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-023 索引中残留的英文位置说明 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-024 null 值的可见索引 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-025 OID 的可见索引 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-026 标识符转义条件漏译否定 | P2 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-027 标识符转义结果必须释放 | P2 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-028 转义输入长度不包含末尾零字节 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-029 反斜杠和相关例程表述 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-030 字符串字面量与调用者提供的引号 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-031 转义缓冲区至少为两倍长度加一字节 | P3 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-032 无效多字节编码、错误消息与输出串 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-033 旧转义函数不接受连接参数 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-034 behind the scenes 与安全隐患措辞 | P3 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-035 旧转义函数的弃用关系 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-036 二进制数据转义为 bytea 字面量的含义 | P2 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-037 bytea 转义结果不含外围单引号 | P2 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-038 bytea 输入输出长度与末尾零字节 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQR-039 PQunescapeBytea 的完整反向转换说明 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQR-040 类型 OID 头文件位置及协议 3.0 前限制 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | + +完整阅读覆盖 103 个英文 API 条目变体及全部中文候选、448 个实际 API 条目、19 个外层段落变体和 5 个节框架。全部最终条目、完整外框及所有权/假设条件精炼均已复读。481 个代码块中仅校准 11 个 `PQprint` 块内原有的可见注释;C/SQL 语法、签名与标识符保持自身版本。 + +四个子节共 44 个逐版范围与当前源码、审定稿、固定英文和新解析快照一致,零漂移。主执行节的 40 个提示逐项绑定到既有查询参数 ID;另外三个子节没有范围内结构提示。`git diff --check` 通过。 + +本批仅关闭 `libpq-exec` 下的四个子节。libpq 剩余章节、整书通读、历史证据对账与最终 33 项 HTML/A4/US 构建仍未完成。原始整书结构审计退出码仍为 PG10—12 的 3、PG13—20 的 1,不能报告为整书验收通过。 + +证据:[主执行逐问题矩阵](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-main-full-issue-version-matrix.json)、[结果与转义逐问题矩阵](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-result-full-issue-version-matrix.json)、[主执行原生核验](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-main-native-validation.json)、[结果与转义原生核验](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-result-native-validation.json)、[完整结果与转义审定稿](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-result-full-approved-parent-plans.json)。 diff --git a/docs/calibration-libpq-flow-20260914.md b/docs/calibration-libpq-flow-20260914.md new file mode 100644 index 00000000..3d9bde90 --- /dev/null +++ b/docs/calibration-libpq-flow-20260914.md @@ -0,0 +1,75 @@ +**PG10—PG20:libpq 异步、管道、分块读取与取消接口校准** + +本批从 PG18 开始,完整核对十一版的异步处理、管道模式、单行/分块读取和取消查询。55 个检查组、605 个版本格包含 297 格修复、131 格原本正确、170 格不适用和 7 格固定英文自身疑义;不是 55 个新增缺陷。正文修复及本批原生解析核验均已完成。 + +主要修复:PG14 的异步与管道使用说明混入后续版本限制;PG17—20 漏译有限行数读取、同步关闭接口和 PQsendPipelineSync 错误恢复说明;PG14—20 将显式事务例外译成“除非”,并将双向阻塞译成“阻止”。同时补齐零行结果立即返回、重复函数和类型标记,校准缓冲区发送、同类函数、取消接口弃用术语及可见索引。 + +修=已修复;核=就该问题本版原本正确;无=本版不适用;疑=固定英文自身存在待上游澄清的表述,保留忠实译文。管道首次出现在 PG14,分块读取和新取消接口从 PG17 起存在;PG10—13 的协议 2.0 限制、PG10/11 的非阻塞重试文本、PG17 的状态标记均按各自英文保留。 + +| 检查组 | 级别 | PG10 | PG11 | PG12 | PG13 | PG14 | PG15 | PG16 | PG17 | PG18 | PG19 | PG20 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| C19-LQA-001 PG14 PQsendQuery 混入 PG15 起的管道限制 | P2 | 无 | 无 | 无 | 无 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQA-002 PG17 起引言遗漏有限行数读取 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | +| C19-LQA-003 异步提交成功与等待结果的区别 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQA-004 查询参数独立指定与单命令限制 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQA-005 预备语句的创建与按名称执行 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQA-006 portal 遵守不翻译词表 | P3 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQA-007 非空结果指针与读取完成条件 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQA-008 读取输入与返回值不表示读到数据 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQA-009 缓冲输入清除 select 可读就绪指示 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQA-010 非阻塞输出缓冲区等待发送的说明 | P3 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQA-011 PQflush 发送队列、返回值与非阻塞条件 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQA-012 大型结果可能不适合完整缓冲 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQA-013 同步异步接口成对对应关系 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQA-014 多个命令结果分别读取与重叠处理 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQA-015 主循环就绪检测与读取调用次序 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQA-016 发送阻塞、长命令与 COPY IN 的关系 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQA-017 同时等待读写并读取服务器输出避免互相阻塞 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQA-018 协议 2.0 的版本限制 | CHECK | 核 | 核 | 核 | 核 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | +| C19-LQA-019 PG17 起异步关闭接口及结果调用列表 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | 核 | 核 | +| C19-LQA-020 管道同步结果与错误后的读取规则 | CHECK | 无 | 无 | 无 | 无 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQA-021 取消后仍须正常读取结果及取消 API 版本 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQA-022 PQisBusy 和 PQisnonblocking 返回语义 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQA-023 PG10/11 旧非阻塞重试段的本版适用性 | CHECK | 核 | 核 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | +| C19-LQF-001 PG14 混入后续版本的管道使用限制 | P2 | 无 | 无 | 无 | 无 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQF-002 PG17 起漏列同步关闭预备语句和 portal 接口 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | +| C19-LQF-003 PG17 起错误恢复漏列 PQsendPipelineSync | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | +| C19-LQF-004 显式事务例外说明误译为除非 | P2 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQF-005 双向阻塞误译为阻止操作 | P2 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQF-006 查询队列、网络往返与两种阻塞模式 | P3 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQF-007 连接状态、进入和退出管道的条件 | P3 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQF-008 同步消息链接文字与同步点作用 | P3 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQF-009 PQsendPipelineSync 不自动发送缓冲数据 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | +| C19-LQF-010 服务端与客户端缓冲区的发送区别 | P3 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQF-011 管道结果读取与队列匹配 | P3 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQF-012 非阻塞事件循环与交错处理标题 | P3 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQF-013 管道使用场景、延迟与性能代价 | P3 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQF-014 客户端依赖结果与服务器端交换信息 | P2 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQF-015 读改写示例的两条可见注释 | P3 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQF-016 管道化和批处理模式可见索引 | P3 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQF-017 各版发送 API、同步结果与单行模式位置 | CHECK | 无 | 无 | 无 | 无 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQF-018 固定英文首个错误状态的内部表述疑义 | SOURCE_DOUBT | 无 | 无 | 无 | 无 | 疑 | 疑 | 疑 | 疑 | 疑 | 疑 | 疑 | +| C19-LQF-019 零行结果立即返回的限定遗漏 | P2 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | +| C19-LQF-020 普通 PGresult 类型标记与查询归属 | P3 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | +| C19-LQF-021 同类函数译法与单行分块调用时机 | P3 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQF-022 分块上限、零行终止与失败后撤销操作 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQF-023 PGcancelConn 完整类型引用 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | +| C19-LQF-024 取消轮询遗漏重复函数标记与连接描述 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | +| C19-LQF-025 旧取消函数弃用术语 | P3 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQF-026 取消查询与取消错误消息索引 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | +| C19-LQF-027 取消连接加密和认证参数适用性 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | 核 | 核 | +| C19-LQF-028 取消请求已发送不保证实际生效 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQF-029 取消超时、状态和套接字有效期 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | 核 | 核 | +| C19-LQF-030 取消对象重置、释放与错误字符串生命周期 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | 核 | 核 | +| C19-LQF-031 旧取消接口的信号处理和线程安全边界 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQF-032 PG17 状态标记与 PG18 起结构差异 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | 核 | 核 | + +阅读覆盖 68 个完整英文 API 变体及全部中文候选、270 个实际条目、76 个外层段落变体和 20 个框架。修改后的完整单元均已复读,并检查自身版本差异。288 个代码块保持自身 C/SQL 语法,只有 PG14—20 的读改写示例各翻译两条可见 SQL 注释。 + +40 个完整逐版范围与当前源码、审定稿、固定英文、原生解包英文和新快照精确一致,零漂移。异步节没有范围内结构提示;另三节的 15 个提示均逐项绑定至既有 PQpipelineStatus 状态 ID,已核对完整中英父块、状态名、路径和次序后保留。`git diff --check` 通过。 + +保留的英文疑义:PG14—20 的结果处理段称首个错误也报告 PGRES_PIPELINE_ABORTED,而错误处理段写首个错误先报告 PGRES_FATAL_ERROR,剩余排队操作才报告 PGRES_PIPELINE_ABORTED。两处本版英文与忠实译文均保留,单独记录,未计为翻译缺陷。 + +本批不等于全书验收。快速路径、通知和 COPY 修订稿正在复读;libpq 其余章节、全书通读、历史证据对账与最终 33 项 HTML/A4/US 构建仍未完成。整书原始结构审计退出码仍为 PG10—12 的 3、PG13—20 的 1。 + +证据:[异步矩阵](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-async-full-issue-version-matrix.json)、[管道与取消矩阵](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-flow-full-issue-version-matrix.json)、[29 完整审定父块](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-flow-full-finalized-parent-plans.json)、[新快照核验](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-flow-native-validation.json)、[15 个原生提示逐项处置](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-flow-native-dispositions.json)、[固定英文疑义](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-flow-full-fixed-source-doubts.json)。 diff --git a/docs/calibration-libpq-oauth-20260914.md b/docs/calibration-libpq-oauth-20260914.md new file mode 100644 index 00000000..eb5e04bf --- /dev/null +++ b/docs/calibration-libpq-oauth-20260914.md @@ -0,0 +1,40 @@ +**PG10—PG20:OAuth 跨文件校准** + +从 PG18 起核对 libpq 全部 OAuth 接口、外段、调试项与代码脚注,并扩展到 client-auth、oauth-validators 和 protocol。PG18—20 共 15 个完整父块、12 个文件;PG10—17 根据本版英文确认尚无这些功能。 + +已修复授权范围、签发者、设备授权的译名不一致,non-NULL 条件、异步回调文件描述符说明和令牌适用组合;恢复协议首次交互第五步的三个原文段落、重新连接说明归属、当前用户有效令牌和两类元数据等限定。保留各版 API、调试行为、八个协议步骤及消息顺序。 + +26 个检查组 × 11 版,共 286 格:58 格修复、19 格原本正确、209 格不适用。检查组包含缺陷、措辞及已正确的技术边界,不等于 26 个新增缺陷。修=修复;核=原本正确;无=不适用。 + +| 检查组 | 级别 | PG10 | PG11 | PG12 | PG13 | PG14 | PG15 | PG16 | PG17 | PG18 | PG19 | PG20 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| C19-LQOA-001 设备授权流程译名及安装说明 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQOA-002 Windows 内置流程限制与自定义流程能力 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | 核 | +| C19-LQOA-003 认证钩子要求应用程序执行操作及后备行为 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQOA-004 获取钩子、默认行为与进程内生效范围 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | 核 | +| C19-LQOA-005 完整验证 URI 的 non-NULL 条件 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQOA-006 二维码验证仍显示 URI 和用户代码 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | 核 | +| C19-LQOA-007 Bearer 令牌适用的用户、签发者与授权范围组合 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQOA-008 异步回调设置 altsock 及轮询顺序 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQOA-009 令牌和清理回调生存期及记录状态措辞 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQOA-010 PG19 起版本 2 结构体强制转换及签发者检查 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | +| C19-LQOA-011 调试模式安全与不安全标签、默认值和错误行为 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | 核 | +| C19-LQOA-012 PG19 起 http 模式与提供者交互的措辞 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 修 | 修 | +| C19-LQOA-013 OAuth 签名原有 C 注释本地化 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQOA-014 验证器客户端授权的 scope 统一为授权范围 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQOA-015 设备授权客户端与受信任部署脚注 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQOA-016 用户名映射委派中的令牌授权范围 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQOA-017 HBA scope 参数中的授权范围 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQOA-018 无缓存令牌时的两次连接及 libpq 行为 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQOA-019 发现连接的当前用户与有效令牌限定 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQOA-020 GS2 三个可选部分及服务器忽略行为 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQOA-021 不支持通道绑定且不使用 AuthenticationSASLFinal | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | 核 | +| C19-LQOA-022 首次交互第五步恢复三个完整段落 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQOA-023 客户端已配置及服务器提供的两类元数据 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQOA-024 重新连接说明归位及第六步服务器消息 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQOA-025 OAUTHBEARER 不强制令牌获取方式及结束 SASL | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQOA-026 逐版保留八步骤及协议字段和消息顺序 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | 核 | + +全部修改文本及 15 个最终措辞细化绑定复读完成。24 个代码块保留本版代码和输出,仅翻译原有 C 注释;验证器原生提示中的另六个完整条目也已中英对照,语义正确。新快照核验零漂移,三组提示均以三个完整职责条目的精确行号配对关闭;无未决范围提示。全书校准和最终 33 项构建尚未完成。 + +证据:[逐项十一版矩阵](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-oauth-full-issue-version-matrix.json)、[完整审定父块](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-oauth-full-finalized-parent-plans.json)、[新快照核验](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-oauth-native-validation.json)、[原生提示全文分类](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-oauth-native-classification.json)。 diff --git a/docs/calibration-libpq-ssl-20260914.md b/docs/calibration-libpq-ssl-20260914.md new file mode 100644 index 00000000..536c9862 --- /dev/null +++ b/docs/calibration-libpq-ssl-20260914.md @@ -0,0 +1,55 @@ +**PG10—PG20:libpq SSL 校准** + +从 PG18 起完整阅读 SSL 全节,再逐项核对十个其他版本。37 个检查组、407 个版本格:247 格修复、133 格原本正确、27 格不适用。检查组包括技术缺陷、措辞和版本边界,不等于 37 个新增缺陷。 + +关键修复:十一版将“不建议依赖 sslmode=require 的兼容验证行为”误译为“鼓励依赖”,现已恢复否定及 verify-ca/verify-full 要求。十一版私钥权限的 world/group 被直译为“世界或组”,已与密码文件统一,并保留 root 所有、0640 和 Windows 例外。PG14 移除混入的 PG15 TLS 引言、SAN/IP 匹配规则及 RFC 6125 注释,恢复其本版说明。 + +同步修复防护表引导句缺谓语、prefer 将“加密”泛化为“安全性”、冒充攻击译名、CA/MITM 标记,以及信任链、客户端证书、开销和初始化说明。保留 PG18 起旧初始化接口无操作等版本变化。22 个 API 签名块完全不变。 + +修=已修复;核=该项原本正确;无=不适用。 + +| 检查组 | 级别 | PG10 | PG11 | PG12 | PG13 | PG14 | PG15 | PG16 | PG17 | PG18 | PG19 | PG20 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| C19-LQSSL-001 不建议依赖 require 兼容行为被译成鼓励 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-002 PG14 混入未来 TLS 引言与索引 | P2 | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQSSL-003 PG14 混入 PG15 SAN 规则和 RFC6125 注释 | P2 | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQSSL-004 逐版主机名、通配符和 IP 地址验证边界 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQSSL-005 PG15 起 SAN 缺失条件和匹配对象句序 | P3 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-006 PG15 起 RFC6125 兼容说明和 SAN 复数 | P3 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-007 身份伪造、根自签名证书和信任链 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-008 两端证书链、叶证书与签发共用译文 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-009 沿完整证书链验证与 verify-full 条件 | P3 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-010 客户端证书链、私钥和路径主语 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-011 私钥权限 world/group 被译为世界或组 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-012 root 所有者、0640 例外和 Windows 边界 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQSSL-013 PG10 首证书说明恢复上游破折号实体 | P3 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQSSL-014 PEM 与 DER 支持误作可能格式 | P3 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-015 密钥加密、TTY 和密码回调说明 | P3 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-016 证书创建说明误作指令 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-017 根证书、CRL、环境路径和证书顺序 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQSSL-018 CA 缩写错误使用 literal 标记 | P3 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-019 表头缺 MITM 缩写标记 | P3 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-020 Impersonation 误作模仿及授权含义 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-021 中间人攻击主体与无法察觉的关系 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-022 三种威胁的译名按序配对及合法本地锚点 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQSSL-023 不同 sslmode 防护级别的引导句 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-024 连接前两端配置 SSL 的前提 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-025 认证后发送敏感数据及此前的顺序 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-026 防护表引导句缺 illustrates 谓语 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-027 prefer 行将 encryption 泛化为安全性 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-028 加密和密钥交换开销的共用译文 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-029 prefer 默认值的兼容目的与建议 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-030 trusted CA 使用规范术语 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQSSL-031 文件用途、证书所有权与信任的区别 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQSSL-032 初始化 API 引言共用译文 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 核 | 核 | 核 | +| C19-LQSSL-033 PG18 起初始化接口弃用与无操作语义 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQSSL-034 OpenSSL 1.1.0 例外的 PG10/11 边界 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQSSL-035 PG18 起库名称 literal 被代词省略 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQSSL-036 早期初始化说明统一第二人称 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 无 | 无 | 无 | +| C19-LQSSL-037 两种表格本版结构与 PG13 起列宽 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | + +阅读 38 个段落变体、12 个 API/威胁条目变体、12 个表行变体、3 个表格框架和 10 个节框架及所有中文候选;复读全部修改文本。覆盖 55 个实际条目、278 个外段、132 个表行及 22 个代码块。 + +十一版完整 SSL 节与当前审定稿、固定英文、原生解包英文和新快照精确一致,零漂移。37 条原生提示已逐条以行号绑定完整条目或表行:15 个原有本地锚点、11 组三个已翻译威胁标题、11 组按文件名配对的四行文件用途表;无未决范围提示。`git diff --check` 通过。全书审计、剩余校准及最终 33 项构建仍未完成。 + +证据:[逐问题十一版矩阵](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-ssl-full-issue-version-matrix.json)、[完整审定父块](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-ssl-full-approved-parent-plans.json)、[新快照核验](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-ssl-native-validation.json)、[逐条原生提示分类及全文证据](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-ssl-native-classification.json)。 diff --git a/docs/calibration-libpq-status-20260914.md b/docs/calibration-libpq-status-20260914.md new file mode 100644 index 00000000..9ee059a4 --- /dev/null +++ b/docs/calibration-libpq-status-20260914.md @@ -0,0 +1,45 @@ +**PG10—PG20:libpq 连接状态章节校准** + +本批从 PG18 开始完整阅读连接状态节,再核对其余十版的全部 API 条目、外层段落和版本差异。27 个检查组、297 个版本格包含技术问题、措辞、术语和适用性检查,不代表 27 个独立新增缺陷。180 格修复,84 格原本正确,33 格不适用。正文修复和本批新快照核验均已完成。 + +主要修复:PG10—14 的 `PQsslAttribute`、`PQsslStruct` 混入了后续版本的返回条件;PG14 多出 PG15 起才有的 SSL 库检测整段;PG13—20 把错误消息“可能包含多行”译成必然包含多行。此外补齐错误消息索引层级,明确 `PQtty` 的 NULL 唯一例外,并校准访问函数、字段、版本号及 NOTIFY 通知等说明。 + +修=本轮修复;核=就该问题对照本版英文后原本正确;无=本版不适用。F-024 的参数状态列表已重新完整阅读十一版,包括 `scram_iterations`、`search_path`、指针有效期与各自版本范围。 + +| 检查组 | 级别 | PG10 | PG11 | PG12 | PG13 | PG14 | PG15 | PG16 | PG17 | PG18 | PG19 | PG20 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| C19-LQS-001 主机名与端口信息生成失败的说明 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQS-002 PQhostaddr 的 NULL 与空字符串说明 | P3 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQS-003 PQtty 的唯一例外与始终为空返回值 | P3 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQS-004 PQoptions 是连接请求中传递的选项 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQS-005 PQstatus 保留本版状态常量标记 | P3 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | +| C19-LQS-006 事务状态的有效事务块措辞 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQS-007 协议版本说明与旧版协议 2.0 范围 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 核 | 核 | 核 | +| C19-LQS-008 服务器版本号两位数字与次版本措辞 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQS-009 PQerrorMessage 漏译 functions | P3 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQS-010 错误消息可能含多行而非必然多行 | P2 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQS-011 错误消息索引补齐 PGconn 层级 | P3 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | +| C19-LQS-012 PQsocket 的文件描述符编号 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQS-013 后端 PID 与 NOTIFY 通知的关系 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQS-014 后端 PID 可见索引未译 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQS-015 PQsslInUse 布尔返回值语序 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQS-016 旧版 PQsslAttribute 混入新版返回条件 | P2 | 修 | 修 | 修 | 修 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQS-017 PG14 混入 PG15 SSL 库探测整段 | P2 | 无 | 无 | 无 | 无 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQS-018 旧版 PQsslStruct 混入新版 NULL 条件 | P2 | 修 | 修 | 修 | 修 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQS-019 PQsslStruct 所请求对象与 SSL 实现的关系 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQS-020 PG14 OpenSSL 名称应保留同版引号结构 | P3 | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQS-021 访问函数获取内容与内部字段术语 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQS-022 连接与 PGconn 对象的生命周期表述 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQS-023 F024 参数状态列表与指针有效期重新全读 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQS-024 完整协议版本函数仅 PG18 起存在 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | 核 | +| C19-LQS-025 GSSAPI 认证状态函数仅 PG16 起存在 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | 核 | 核 | 核 | +| C19-LQS-026 SSL 属性 ALPN 仅 PG17 起存在 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | 核 | 核 | +| C19-LQS-027 SSL 属性名称扩展说明仅 PG16 起存在 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | 核 | 核 | 核 | + +完整阅读覆盖 58 个英文条目变体及全部中文候选、9 个外层段落、1 个框架、259 个实际条目;32 个最终条目变体、5 个完整外层框架和 7 个返回条件精炼均已复读。270 个签名/代码块保留原样,除原有可读 C 注释翻译外,与本版英文精确相同。 + +十一版当前源码、审定稿、固定英文、原生解包英文及新解析快照一致,零漂移。29 个范围内结构提示均为既有 SSL 属性锚点,逐项核对属性名、相邻次序、父路径及完整 API 中英正文后保留。PG14 删除未来段落后遗留的一行空白已单独清理并记录;`git diff --check` 通过。 + +本批仅关闭 `libpq-status`。执行查询和 libpq 其余节继续校准;全书其他待读范围、历史证据对账和最终 33 项 HTML/A4/US 构建仍未完成。全书原始结构检查退出码仍为 PG10—12 的 3、PG13—20 的 1,不能报告为全书通过。 + +详细证据:[逐问题十一版矩阵](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-status-full-issue-version-matrix.json)、[完整审定父块](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-status-full-accepted-parent-plans.json)、[259 条目绑定](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-status-full-accepted-entry-proof.json)、[新快照核验](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-status-native-current-snapshot-proof.json)、[29 条逐项处置](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-status-native-dispositions.json)、[完整父块](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-status-native-parent-proof.json)。 diff --git a/docs/calibration-libpq-transfer-20260914.md b/docs/calibration-libpq-transfer-20260914.md new file mode 100644 index 00000000..a287b1d1 --- /dev/null +++ b/docs/calibration-libpq-transfer-20260914.md @@ -0,0 +1,50 @@ +**PG10—PG20:libpq 快速路径、通知与 COPY 校准** + +从 PG18 开始完整阅读三个范围,并逐项核对其余十版。32 个检查组、352 个版本格包含 263 格修复、62 格原本正确和 27 格不适用。这些组包括技术缺陷、措辞和版本边界检查,不等于 32 个新增缺陷。正文及范围内新快照核验已完成。 + +主要修复:PG14—19 的快速路径参数误允许 1 字节整数,各适用版原文只允许 2 或 4 字节;补齐结果长度的字节单位。PG14—20 的通知通道名称“不必与关系名有关联”被译成绝对无关。十一版的 COPY 终止行“必须仅由反斜杠和点组成”被弱化为包含这两个字符,严重错误被窄化为系统错误。PG13—20 的发送完成主语及显式调用顺序有误,PG18—20 的旧 COPY 接口还漏译 CSV 注意事项。 + +同步校准数据方向、缓冲指针和内存归属、零字节结尾、读写就绪、已入队与实际发送的区别、可见索引及三条 PGnotify C 注释。保留各自旧协议限制;PG20 英文已移除快速路径整节,故不添加。 + +修=已修复;核=针对该项原本正确;无=本版不适用。 + +| 检查组 | 级别 | PG10 | PG11 | PG12 | PG13 | PG14 | PG15 | PG16 | PG17 | PG18 | PG19 | PG20 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| C19-LQT-001 快速路径误加 1 字节整数参数 | P2 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 无 | +| C19-LQT-002 快速路径结果长度遗漏字节单位 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 无 | +| C19-LQT-003 快速路径缓冲指针、字节序与结果整数大小 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 无 | +| C19-LQT-004 快速路径安全警告和替代调用方式 | P3 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 无 | +| C19-LQT-005 集合值结果与函数种类限制 | P3 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 无 | +| C19-LQT-006 NULL 参数和结果的旧协议行为 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 无 | +| C19-LQT-007 快速路径返回状态和结果释放 | P3 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 无 | +| C19-LQT-008 快速路径可见索引 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 无 | +| C19-LQT-009 通知通道与关系名称不必相关的条件 | P2 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQT-010 PGnotify 字段内存归属与名称 | P3 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQT-011 PGnotify 三条可见 C 注释 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQT-012 通知函数句中误留英文句点及可见索引 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQT-013 读取已收通知和轮询方法弃用措辞 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQT-014 无实际命令时检查通知的条件 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQT-015 监听、载荷、结果处理与通知读取次序 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LQT-016 COPY 的网络连接和数据传输引言 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQT-017 COPY 状态和元数据引导 | P3 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQT-018 COPY 字段函数索引与旧函数弃用说明 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQT-019 发送缓冲区分块边界没有语义作用 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQT-020 写就绪、入队和实际发送的区别 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQT-021 严重错误误作仅限系统错误 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQT-022 返回缓冲指针与 NULL、完整行接收 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQT-023 COPY 接收和发送的零字节结尾 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQT-024 终止行必须仅由反斜杠和点组成 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQT-025 PQgetline 换行符、长度和返回值 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQT-026 异步读取整行与部分行、缓冲大小 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQT-027 PG18 起 PQputline 漏译 CSV 限制 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-LQT-028 应用通知服务器发送完成的主语 | P2 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQT-029 PQendcopy 的显式调用和多命令结果循环 | P3 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQT-030 COPY 完成后恢复正常操作的次序 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LQT-031 协议 2.0 元数据及强制失败限制 | CHECK | 核 | 核 | 核 | 核 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | +| C19-LQT-032 COPY 格式代码、方向与二进制列 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | + +阅读覆盖 25 个完整英文 API 变体及全部中文候选、34 个外层段落变体和 8 个框架;对应 121 个实际条目、238 个外层段落。26 个最终条目变体、24 个修改段落和 6 个修改框架已复读。109 个代码块保持自身 C 签名与语法,仅 11 个 PGnotify 块内各三条原有可见注释本地化。 + +32 个完整逐版范围与当前源码、审定稿、固定英文、原生解包英文和新快照精确一致,零漂移、零范围内结构提示。`git diff --check` 通过。全书原始审计仍为 PG10—12 退出 3、PG13—20 退出 1;libpq 余下内容、整书语义阅读、历史证据对账与最终 33 项构建尚未完成。 + +证据:[逐问题十一版矩阵](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-transfer-full-issue-version-matrix.json)、[完整审定中英父块](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-transfer-full-parent-plans.json)、[新快照核验](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-transfer-native-validation.json)、[代码保护核验](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-transfer-full-raw-proof.json)。 diff --git a/docs/calibration-libpq-whole-20260914.md b/docs/calibration-libpq-whole-20260914.md new file mode 100644 index 00000000..dcad7c7e --- /dev/null +++ b/docs/calibration-libpq-whole-20260914.md @@ -0,0 +1,15 @@ +**PG10—PG20:libpq 全章校准结果** + +十一版 libpq 全章已按完整中英语义单元完成本阶段校准,并以修订后的新快照核验。原始阅读清单覆盖 468 个条目变体、336 个段落变体、12 个表行变体、3 个表格框架、94 个节框架、6 个章框架及 225 个代码变体;相同英文的所有不同中文候选均按本版核对。 + +最终源码覆盖 537 个节范围及 2,079 个本版英文代码块。526 个节直接匹配完整审定父块;11 个命令执行父节由已读外层框架和四个完整子节组成。十一版当前源码、审定稿、新快照、固定英文与原生解包英文对应一致。 + +累计 398 个检查组、4378 个逐版格:ALREADY_CORRECT=987、FIXED=2712、NOT_APPLICABLE=667、RETAINED_SOURCE_DOUBT=7、REVIEWED_EXCEPTION=5。这些格包含缺陷修复、措辞、原本正确的条件、不适用与源文疑点,不能当作新增缺陷数量。 + +主要修复包括旧版混入未来功能、参数归属、容量与字节单位、返回值和 NULL 条件、内存与对象生存期、读写与发送顺序、并发与回调条件、SSL 反义及版本规则、OAuth 跨文件遗漏、代码示例不同步和原有可译注释。完整逐项状态见[十一版矩阵](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-whole-issue-version-matrix.json)。 + +最初 87 条配对信号中,86 条来自合法的已翻译标签,另 1 条为 PG14 混入未来证书说明,已修复。最终原生检查保留 222 条提示:193 个既有本地 ID、17 组匿名单元配对、11 组文件用途表行、1 条 PG14 英文错误 API 名所致引用差异。每条均重新按当前行号绑定完整审定文本或对应版本源码勘误证据,零未决提示、零源码漂移。 + +这次关闭的是 libpq 全章的语义及源码结构核验。**其余全书语义校准、历史修复对账和最终 33 项 HTML/A4 PDF/US PDF 构建仍未完成。** 原生工具的全书原始退出码仍保留,不把合法定制忽略掉或降低检查强度;本报告也不把它们冒充全书构建通过。 + +证据:[全章逐节覆盖](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-whole-source-coverage.json)、[代码覆盖](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-whole-source-raw-coverage.json)、[原始信号处理](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-whole-source-initial-signal-closure.json)、[新快照核验](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-whole-native-validation.json)、[222 条全文分类](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/libpq-whole-native-classification.json)。 diff --git a/docs/calibration-lobj-20260914.md b/docs/calibration-lobj-20260914.md new file mode 100644 index 00000000..17d15bf6 --- /dev/null +++ b/docs/calibration-lobj-20260914.md @@ -0,0 +1,41 @@ +**PG10—PG20:大对象全章校准结果** + +从 PG18 开始,完整核对十一版 `lobj.sgml` 的本版英文与全部中文变体:57 个段落变体、8 个表行变体、3 个表框架、29 个节框架、1 个章框架和 33 个代码变体。修订稿的八个段落变体、三个旧版接口签名变体及全部注释已复读。最终覆盖 176 个节、522 个段落、44 个表行和 231 个代码块。 + +主要修复:PG15/16 的 `lo_lseek64`、`lo_tell64`、`lo_truncate64` 误用未来的 `int64_t`,已依据各版头文件恢复 `pg_int64`;PG18 起保留 `int64_t`。十一版服务器端文件导入、导出权限的表述明确为“运行数据库服务器的操作系统用户”,依据各版后端实现核实。另修正 PG16 示例版权年份,校准缓冲区长度、截断对象、零字节、分块建议和原有可译索引、注释。 + +以下 25 个检查组含缺陷、措辞、原本正确项、版本差异与英文疑点,不是 25 个新增缺陷。修=已修;核=本版原本正确;无=本版没有该说明;源疑=固定英文自身疑点,按源文保留。 + +| 检查组 | 级别 | PG10 | PG11 | PG12 | PG13 | PG14 | PG15 | PG16 | PG17 | PG18 | PG19 | PG20 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| C19-LO-001 lo_lseek64 的本版 64 位类型 | P2 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 核 | 核 | 核 | 核 | +| C19-LO-002 lo_tell64 的本版 64 位类型 | P2 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 核 | 核 | 核 | 核 | +| C19-LO-003 lo_truncate64 的本版 64 位类型 | P2 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 核 | 核 | 核 | 核 | +| C19-LO-004 服务器文件访问使用操作系统账号权限 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LO-005 PG16 示例误用未来版权年份 | P3 | 核 | 核 | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | 核 | +| C19-LO-006 大对象和 TOAST 对照的可见索引 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LO-007 lo_write 缓冲区长度的指代 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LO-008 截断对象与描述符的关系 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LO-009 扩展大对象时的零字节 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LO-010 读写分块长度的建议措辞 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LO-011 示例所在源代码发行包 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LO-012 原有 C 与 SQL 注释本地化 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-LO-013 读写、截断及所有者权限 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LO-014 PG11 起 lo_open 的权限检查时机 | CHECK | 无 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LO-015 PG16 起只读事务限制说明 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 核 | 核 | 核 | 核 | +| C19-LO-016 PG14 起管道模式限制说明 | CHECK | 无 | 无 | 无 | 无 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LO-017 PG15 创建接口顺序与 mode 历史兼容 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LO-018 SQL 表格行、签名及 PG13 布局差异 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LO-019 2 GB 偏移、长度与错误返回 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LO-020 4 TB 与 1 GB 容量及稀疏分配 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LO-021 客户端文件与 PG11 起 GRANT 说明 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LO-022 实际读写字节数与 INT_MAX 限制 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LO-023 截断后位置不变及扩展行为 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LO-024 关闭、移除及事务结束自动关闭 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-LO-025 固定英文示例对负数读返回的处理顺序 | SOURCE | 源疑 | 源疑 | 源疑 | 源疑 | 源疑 | 源疑 | 源疑 | 源疑 | 源疑 | 源疑 | 源疑 | + +十一版新快照已完成原生准备和审计。当前中文、审定稿、新快照、固定英文与解包英文精确一致,全部 176 个节精确对应已读父块,范围内零未决提示、零漂移。完整代码与本版英文逐一核验,除已审定的原有注释本地化和上述版本订正外,代码、标识符及输出保持一致。 + +固定英文示例 `pickout` 在检查 `lo_read` 的负数返回值之前使用 `buf[nbytes]`,十一版均保留本版代码并单列源文疑点;未声称执行测试。大对象范围 `git diff --check` 通过。工作区同期其他任务的 `ddl.sgml` 修改曾产生全局空白提示,未据本批范围检查声称全局通过。全书校准、历史对账及最终 33 项 HTML/A4 PDF/US PDF 构建仍未完成。 + +证据:[十一版逐项矩阵](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/lobj-full-issue-version-matrix.json)、[API 与权限实现](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/lobj-source-api-permission-proof.json)、[完整代码对照](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/lobj-full-raw-proof.json)、[新快照核验](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/lobj-native-validation.json)、[176 节绑定](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/lobj-native-scope-coverage.json)。 diff --git a/docs/calibration-protocol-front-20260914.md b/docs/calibration-protocol-front-20260914.md new file mode 100644 index 00000000..7bab006d --- /dev/null +++ b/docs/calibration-protocol-front-20260914.md @@ -0,0 +1,79 @@ +**PG10—PG20:协议概述与消息流校准结果** + +已从 PG18 起完整阅读十一版的协议章首、概述与消息流,包括启动、简单和扩展查询、管道、函数调用、COPY、异步消息、取消、终止、SSL 和 GSSAPI。覆盖 158 个外层段落变体、28 个一般消息条目变体、22 个补充启动条目变体、10 个启动段落变体、14 个表行变体、5 个表框架、33 个节框架及 2 个章框架;20 个 SSL/GSSAPI 完整父节按七组完整差异复读。 + +主要修复:PG15—17 的启动条目混入 PG18 说明,PG11—17 管道 DDL 条件误用 PG18 规则,PG14—16 混入新版 SSL 握手段落;十一版 RowDescription/DataRow 先后顺序、Sync 消息名、COPY 的或关系与可能性限定、数据字段指代、取消机制效率和 core dump 误译;PG14—20 的 GSSAPI 长度前缀,以及 PG18—20 的协议 3.2 消息变更说明。 + +修订稿的 61 个变体、8 个精炼变体和 3 个外框变体均已复读。40 个程序块与本版英文精确相同;PG11 仅移除本版英文没有的隐藏注释,保留示例故意写错的 SELCT。删除未来段落后产生的九处空行尾空白已定点清理,协议范围 `git diff --check` 通过。 + +下面是 61 个检查组、671 个逐版格:修=已修;核=本版原本正确;无=本版没有该处说明。检查组也包含措辞和已正确条件,不能当作新增缺陷数量。 + +| 检查组 | 级别 | PG10 | PG11 | PG12 | PG13 | PG14 | PG15 | PG16 | PG17 | PG18 | PG19 | PG20 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| C19-PF-001 启动时额外认证的方法与可选条件 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-002 NegotiateProtocolVersion 的本版消息流程 | P2 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 核 | 核 | 核 | +| C19-PF-003 BackendKeyData 的本版第三方实现说明 | P2 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 核 | 核 | 核 | +| C19-PF-004 RowDescription 在 DataRow 之前发送 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-005 函数调用仅返回标量,结果集合并非集合类型 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-006 启动与正常操作阶段 | P3 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-007 正常操作的前后端驱动关系 | P3 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-008 连接终止时在进程退出前回滚 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-009 数据值文本表示与空字符 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-010 解析、绑定和执行引言排版 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-011 行集与 COPY 查询响应 | P3 | 修 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-012 状态机接收合理消息而非假设固定顺序 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-013 多语句作为单个事务执行 | P3 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-014 隐式事务块的定义与自动关闭 | P3 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-015 显式事务块的延续和合并 | P3 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-016 无 BEGIN 的提交或回滚可能是误操作 | P2 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-017 首个错误终止多语句消息 | P3 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-018 执行任何语句前先解析整串查询 | P2 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-019 Execute 消息名及响应约束 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-020 Execute 阶段恰好一条终止响应 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-021 必需操作与可选操作 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-022 管道化术语与在途查询 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-023 整组查询作为单个事务 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-024 Sync 消息名与独立提交边界 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-025 各版管道 DDL 执行条件 | P2 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 核 | 核 | 核 | +| C19-PF-026 按 Sync 消息数量判断完成 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-027 pg_proc 系统目录与执行权限 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-028 旧函数调用协议的替代方式 | P3 | 核 | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | 核 | 核 | +| C19-PF-029 函数调用周期和响应顺序 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-030 CopyDone 允许成功结束 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-031 COPY 输入中 Flush 或 Sync 的例外 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-032 COPY 输出启动和中止传输 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-033 COPY 输出异步消息与可选终止判断 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-034 双向 COPY 的强调标记 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-035 COPY 列数和格式代码字段 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-036 同一通道的 NOTIFY 触发条件 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-037 取消请求使用新连接且无直接响应 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-038 取消请求的密钥数据及中止行为 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-039 取消机制考虑安全性和效率 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-040 core dump 不应译成内核转储 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-041 断连前事务可能提交的限定 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-042 SSL 说明遵守各版适用范围 | P2 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 核 | 核 | 核 | 核 | +| C19-PF-043 GSSAPI 初始化长度前缀及本版 RFC 链接 | P2 | 无 | 无 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-044 SSL 错误不得展示给用户的条件 | P2 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-045 GSSAPI 错误不得展示给用户的条件 | P2 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-046 SSL 单字节握手及额外数据处理 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-047 GSSAPI 单字节握手及额外数据处理 | P3 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-048 新版 SSL 提前协商的断连条件与遗漏标记 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | +| C19-PF-049 新版直接 SSL 协商及通用工具适用性 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | +| C19-PF-050 SSL 取消请求引言 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-051 GSSAPI 取消请求引言 | P3 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-052 SSL 在认证检查中拒绝未加密会话 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-053 GSSAPI 在认证检查中拒绝未加密会话 | P3 | 无 | 无 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-054 SSL 可切换 GSSAPI 段落括号 | P3 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| C19-PF-055 协议 3.2 密钥长度与两种消息变更 | P2 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-PF-056 协议 3.1 保留原因的完整表述 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | +| C19-PF-057 协议防僵化测试排版 | P3 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 修 | 核 | +| C19-PF-058 章首协议 3.0 与 3.2 的版本说明 | P3 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | +| C19-PF-059 ParameterStatus 全部参数及历史版本界线 | CHECK | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| C19-PF-060 PG19 beta 默认 3.9999 及显式绕过方式 | CHECK | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 无 | 核 | 无 | +| C19-PF-061 本版多语句示例中的隐藏注释 | P3 | 无 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | + +十一版新快照原生核验完成,22 个完整父节、189 个节范围和 11 个章外框与当前源码及审定稿精确一致。169 条范围提示已逐项绑定完整中英文本:165 个既有本地 ID、4 条来自同一个已翻译跨列表行的配对提示。另保留四版原有 ALPN 标识的 literal 加亮,字面值与英文一致;没有遗漏的受保护行内标记。 + +本报告只关闭上述范围。SASL/SCRAM 修订稿已读、尚未应用;复制协议、消息格式等仍在继续。全书语义校准、历史修复对账和最终 33 项 HTML/A4 PDF/US PDF 构建仍未完成。 + +证据:[十一版矩阵](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/protocol-front-full-accepted-issue-version-matrix.json)、[新快照验证](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/protocol-front-native-validation.json)、[169 条全文分类](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/protocol-front-native-classification.json)、[逐节覆盖](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/protocol-front-full-scope-coverage.json)、[40 个本版代码块](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/protocol-front-full-raw-proof.json)。 diff --git a/docs/calibration-protocol-whole-20260914.md b/docs/calibration-protocol-whole-20260914.md new file mode 100644 index 00000000..d1ccb141 --- /dev/null +++ b/docs/calibration-protocol-whole-20260914.md @@ -0,0 +1,163 @@ +PG10—PG20 协议全章校准记录(2026-09-14) + +十一版 `protocol.sgml` 全章已完成中英对照、正文修复、共用译文校准与本批原生解析验收;另核对了 PG19/20 移到 `logicaldecoding.sgml` 的完整 pgoutput 参数节。**全书校准、历史台账最终对账与 33 项最终 HTML/A4/US PDF 构建尚未完成。** + +最重要的新增修复是 PG18—20 BackendKeyData 的字段类型仍沿用旧协议:长度字段 Int32(12) 改为本版 Int32,密钥字段 Int32 改为 Byte n;PG17 则移除错误混入的可变长密钥说明,保留本版 4 字节定义。PG18 StartupMessage 编码恢复为 196610;PG14—17 的次版本说明恢复为 0。PG19/20 保留其本版泛化的 Int32 定义。 + +此外,补齐 PG14 AuthenticationSCMCredential,移除 PG14 CommandComplete 中未来的 MERGE 标签、逻辑复制流程中的 Begin Prepare/Prepare 句及 Relation 中未来的发布列列表限定。PG18—20 Relation/TupleData 移除过时的生成列排除条件;PG10—17 按各自英文保留对应限制。恢复 PG10—17 引言中的 CopyData 例外,明确 NULL 与零长度值、SASL 偏好顺序、初始响应长度、消息名、错误字段关系与现存对象等。 + +SASL/SCRAM 已校准服务端响应方向、must 限定、通道绑定、UTF-8/SASLprep 回退和 pass-through 随机值;复制命令已修正 PG15 timeline 的 int4 类型、PG15/16 未来 ALTER_REPLICATION_SLOT、PG17 未来 TWO_PHASE 选项、PG17+ 布尔参数省值说明、时间线所属关系、WAL 刷盘及 catalog_xmin 等。本表与证据分别保留各版本的适用性。 + +完整初读覆盖 284 个条目变体、258 个外段变体、14 个表行变体、5 个表框架、59 个节框架、2 个章框架和 6 个原样代码变体。条目包含其完整内部段落与字段。相同英文复用已读译文,版本差异逐一核对;全部新写译文复读。后六节的 350 个英文文本族、4318 处实际文本均有精确绑定,另有 26 个迁移参数段。 + +新 checkpoint-protocol-whole-final 以十一份独立中文快照执行准备和原生审计。13 个目标文件的当前正文、审定稿、快照、固定英文与上游解包英文精确一致;324 个协议范围和 2 个迁移参数节、51 个代码块逐一绑定,零漂移。prepare 全部为 0;整书 raw audit 的 3(PG10—12)/1(PG13—20)是既有全书提示,范围通过以逐条分类结果为依据。 + +2725 条范围提示分别为:2367 个既有自定义 ID、290 个匿名字段组、59 个 PG14 既有段落/列表包装差异、3 组保留的准确附加链接、2 条针对同一个 PG15 兼容锚点的提示,以及 4 条译文跨列表行提示。每条均绑定完整已读中英父块及准确位置,未决项为零。21 条初始路由信号全部处置,其中 11 条是英文自身在两个启动阶段重复列出 ErrorResponse,不计缺陷。 + +下列 139 个问题或回归组各有十一格,共 1529 格:1000 格修复/校准、388 格原本正确、141 格本版不适用。格数不是独立缺陷数量;CHECK 行为回归核对。修=本组完成修复或措辞校准,核=原本正确,—=同版无此定义。 + +| 问题 / 检查组 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 启动时额外认证的方法与可选条件 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| NegotiateProtocolVersion 的本版消息流程 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 核 | 核 | 核 | +| BackendKeyData 的本版第三方实现说明 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 核 | 核 | 核 | +| RowDescription 在 DataRow 之前发送 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 函数调用仅返回标量,结果集合并非集合类型 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 启动与正常操作阶段 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | +| 正常操作的前后端驱动关系 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | +| 连接终止时在进程退出前回滚 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 数据值文本表示与空字符 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 解析、绑定和执行引言排版 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 行集与 COPY 查询响应 | 修 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 状态机接收合理消息而非假设固定顺序 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 多语句作为单个事务执行 | — | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 隐式事务块的定义与自动关闭 | — | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 显式事务块的延续和合并 | — | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 无 BEGIN 的提交或回滚可能是误操作 | — | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 首个错误终止多语句消息 | — | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 执行任何语句前先解析整串查询 | — | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| Execute 消息名及响应约束 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| Execute 阶段恰好一条终止响应 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 必需操作与可选操作 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 管道化术语与在途查询 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 整组查询作为单个事务 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| Sync 消息名与独立提交边界 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 各版管道 DDL 执行条件 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 核 | 核 | 核 | +| 按 Sync 消息数量判断完成 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| pg_proc 系统目录与执行权限 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 旧函数调用协议的替代方式 | 核 | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | 核 | 核 | +| 函数调用周期和响应顺序 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| CopyDone 允许成功结束 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| COPY 输入中 Flush 或 Sync 的例外 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| COPY 输出启动和中止传输 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| COPY 输出异步消息与可选终止判断 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 双向 COPY 的强调标记 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| COPY 列数和格式代码字段 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 同一通道的 NOTIFY 触发条件 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 取消请求使用新连接且无直接响应 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 取消请求的密钥数据及中止行为 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 取消机制考虑安全性和效率 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| core dump 不应译成内核转储 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 断连前事务可能提交的限定 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| SSL 说明遵守各版适用范围 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 核 | 核 | 核 | 核 | +| GSSAPI 初始化长度前缀及本版 RFC 链接 | — | — | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| SSL 错误不得展示给用户的条件 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| GSSAPI 错误不得展示给用户的条件 | — | — | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| SSL 单字节握手及额外数据处理 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| GSSAPI 单字节握手及额外数据处理 | — | — | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 新版 SSL 提前协商的断连条件与遗漏标记 | — | — | — | — | — | — | — | 修 | 修 | 修 | 修 | +| 新版直接 SSL 协商及通用工具适用性 | — | — | — | — | — | — | — | 修 | 修 | 修 | 修 | +| SSL 取消请求引言 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| GSSAPI 取消请求引言 | — | — | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| SSL 在认证检查中拒绝未加密会话 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| GSSAPI 在认证检查中拒绝未加密会话 | — | — | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| SSL 可切换 GSSAPI 段落括号 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 协议 3.2 密钥长度与两种消息变更 | — | — | — | — | — | — | — | — | 修 | 修 | 修 | +| 协议 3.1 保留原因的完整表述 | — | — | — | — | — | — | — | — | 修 | 修 | 修 | +| 协议防僵化测试排版 | — | — | — | — | — | — | — | — | — | 修 | 核 | +| 章首协议 3.0 与 3.2 的版本说明 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | +| [回归] ParameterStatus 全部参数及历史版本界线 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| [回归] PG19 beta 默认 3.9999 及显式绕过方式 | — | — | — | — | — | — | — | — | — | 核 | — | +| 本版多语句示例中的隐藏注释 | — | 修 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| SASL 机制数量与本版引导句 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 核 | 核 | 核 | +| 初始客户端响应的可选条件 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 挑战与响应的先后流程 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 认证结束消息的数据发送方向与可选条件 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| SASLprep 对 UTF-8 与原始密码的处理 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 通道绑定首现译名与 PG10 未实现说明 | 核 | 修 | 修 | 修 | 修 | 核 | 修 | 修 | 修 | 修 | 修 | +| 无通道绑定时的随机值转发与重放 | — | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 通道绑定、证书及密码 hash 术语 | — | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| SCRAM 引言与 RFC 链接的本版差异 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 核 | 核 | 核 | +| [回归] 使用启动消息中的用户名 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| [回归] 服务端机制列表的 SSL 条件 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| [回归] 客户端机制选择与通道绑定类型 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| [回归] SCRAM 后续三步消息顺序 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| IDENTIFY_SYSTEM.timeline 的本版 int4/int8 类型 | 核 | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | 核 | 核 | +| ALTER_REPLICATION_SLOT 的版本范围 | — | — | — | — | — | 修 | 修 | 核 | 核 | 核 | 核 | +| ALTER_REPLICATION_SLOT 的 TWO_PHASE 适用范围 | — | — | — | — | — | — | — | 修 | 核 | 核 | 核 | +| 布尔参数省略 value 等同 TRUE 的节末说明 | — | — | — | — | — | — | — | 修 | 修 | 修 | 修 | +| TIMELINE_HISTORY 文件所属时间线及字节返回语义 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 允许复制槽同步到备库与故障切换后的恢复 | — | — | — | — | — | — | — | 修 | 修 | 修 | 修 | +| START_REPLICATION 错误例举及起始位置 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 热备反馈 catalog_xmin 最小值、禁用过程与纪元标记 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| BASE_BACKUP 压缩级别整数及算法范围 | — | — | — | — | — | 修 | 修 | 修 | 修 | 修 | 修 | +| libpq 工具归属及测试工具用途 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| WAL 刷盘位置与已写入、已应用位置区分 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| WAL 续接记录、页边界与 XLogData/WALData 版本名 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 命令名索引保留真实标识符 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 时间线与旧时间线末尾的版本行为 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| CopyData 有效载荷和保活、反馈消息的方向及单位 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 旧版 BASE_BACKUP.size 保留 null | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| READ_REPLICATION_SLOT 物理槽限制及返回值 | — | — | — | — | — | 修 | 修 | 修 | 修 | 修 | 修 | +| PG19+ 主库状态消息事务 ID 与纪元位宽 | — | — | — | — | — | — | — | — | — | 修 | 修 | +| 已读相同英文的标识、标签、日志与命令措辞复用 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| [回归] CREATE 选项、快照、保留 WAL 与返回字段的版本回归 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| [回归] 逻辑复制 confirmed_flush_lsn 起点及输出插件 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| [回归] 基础备份参数、权限、格式、清单与排除文件的版本回归 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| [回归] DROP 的 WAIT 与跨数据库旧版限制、UPLOAD_MANIFEST 适用性 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| BackendKeyData 可变长密钥字段的 Int32 / Byte n | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | +| PG17 BackendKeyData 误入未来可变长密钥说明 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | +| StartupMessage 协议版本与编码一致 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 核 | 核 | +| AuthenticationSCMCredential 本版定义完整 | 核 | 核 | 核 | 核 | 修 | 核 | — | — | — | — | — | +| CommandComplete MERGE 标签的版本范围 | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| PG14 流程移除未来 Begin Prepare / Prepare | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| PG18+ Relation / TupleData 不再排除生成列 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | +| PG14 Relation 移除未来发布列列表限定 | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| 逻辑消息字段保留本版 ID/OID 及类型注解 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| PG10—17 消息格式引言恢复 CopyData 例外 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 核 | 核 | 核 | +| 消息长度包含长度字段本身 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| SASL 机制按服务器偏好排序 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 认证请求、挑战及 SASL 结果说明 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| SASL 客户端初始响应的长度与 -1 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| Bind/Close/Describe/Execute/Parse/Sync 等消息名 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| Bind NULL 与零长度参数区分 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| FunctionCall/Response NULL 与零长度区分 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| DataRow NULL 与零长度列值区分 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| EmptyQueryResponse 代替 CommandComplete | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| Error/Notice 带标识字段及字段值 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 通知发送者 PID、通道及有效载荷 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 版本号与请求码高低位说明 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 核 | +| 错误字段标题、标签、S/V 本地化及对象归属 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 错误字段关系与当前存在的数据库对象 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 长行处理与段落分隔 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 逻辑复制消息保留真实名称 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 复制源、源服务器及 Origin 消息 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| Xid 字段仅在流式事务中出现 | — | — | — | — | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 事务标志含义及旧版 must be 0 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| Relation 标识、列属性与版本元数据 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 事务提交、预备及回滚时间戳 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| TupleData TOAST、文本及二进制值 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 协议版本 4 的并行应用与迁移参数节 | — | — | — | — | — | — | 修 | 修 | 修 | 核 | 核 | +| 读取完整字符串及丢弃缓冲区容纳不下的尾部 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 逻辑流复制名称、Origin 可选性与下游职责 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| COPY 输入、输出、双向消息方向 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 格式代码术语、参数/结果数量及传输格式 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 启动参数名称、值、对象 ID 与连接选项 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| [回归] INSERT OID、COPY/CSV 和协议 2.0 变更回归 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| PG19/20 迁移参数节的中文断词空格 | — | — | — | — | — | — | — | — | — | 修 | 修 | +| [回归] 认证标识字节、长度、整数常量及旧协议回归 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | 核 | +| [回归] 流事务/两阶段/二进制消息的版本字段回归 | — | — | — | — | 核 | 核 | 核 | 核 | 核 | 核 | 核 | + +完整逐格证据:[139 组版本矩阵](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/protocol-whole-issue-version-matrix.json);[324+2 个范围来源绑定](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/protocol-whole-source-coverage.json);[完整当前快照核验](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/protocol-whole-native-current-snapshot-proof.json);[2725 条逐项分类](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/protocol-whole-native-accepted-classification.json);[后六节全部共用文本](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/protocol-remainder-full-accepted-atom-version-matrix.json)。 + +固定英文中的 CopyBothResponse / 旧版 CopyResponse 表述按本版保留,另有逐版源文疑点记录。本批原生验收不代表运行时协议测试、全书语义验收或最终 HTML/PDF 构建成功。阶段提交另行核验,未推送。 diff --git a/docs/calibration-textsearch-20260914.md b/docs/calibration-textsearch-20260914.md new file mode 100644 index 00000000..9f58fac7 --- /dev/null +++ b/docs/calibration-textsearch-20260914.md @@ -0,0 +1,55 @@ +全文检索章节十一版校准记录(2026-09-14T15:08:46+08:00) + +本批已修复并验证 PG10—PG20 的 `textsearch.sgml`,从 PG18 开始完整阅读所有正文、表格、外层段落和示例,再核对其余十版的差异。下表为 37 个检查组(含一个英文疑点),不是 37 个独立新增缺陷。关联章节中的术语和新发现问题仍在继续处理;全书逐句审校、最终独立对账及 33 项构建尚未完成。 + +主要修复:PG14—16 词典列表误入 `estonian_stem`;PG10—14 高亮段落误入 PG16 起的说明;PG13—20 的 `siglen` 漏掉字节单位。十一版共用段落还修复了排名重要性、先后匹配方向、同义词与分类词典混淆、过滤词典限制、最长匹配并列选择、NULL、词元类型和复合词构成等问题。 + +“修”表示该检查组有修复;“核”表示针对该问题原本正确;“—”表示完整同版英文中没有该功能或说明;“例”表示有具体理由的保留译法。 + +| 检查组 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 词典列表混入未来版本输出 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 核 | 核 | 核 | 核 | +| 旧版高亮说明混入新版句子 | 修 | 修 | 修 | 修 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| siglen 签名长度漏译字节单位 | — | — | — | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 排名漏译文档部分的重要程度 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 短语匹配漏译前后方向 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 天文学同义词词典误译为分类词典 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 不起作用误译为禁止放在末尾 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 最长匹配长度相同时采用最后定义 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 跳过对该索引词应用子词典 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 任意停用词通配位置 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 恢复全部变格和变位形式 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 复合词构成误译为复合格式 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 每个词元及每种词元类型的区分 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| NULL 与空值的区分 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 两个字段合并后包含查询词 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| AND 与 OR 返回组合后的查询 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 不同词的数量误译为唯一词 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 构建时间不敏感误译为无关 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| i.e. 误译为例如 | — | — | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 签名 hash 说明及更小的扫描比例 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 排名数值归一化术语 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 停用词首术语未翻译 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 加引号及未加引号的查询文本 | — | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 省略可选配置误译为忽略参数 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 词干约简说明语序与可选参数 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 解析器对字母的界定 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 配置构成及 C 开发和安装权限说明 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 配置文件基名及安装步骤 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 词典可识别的输入范围 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 词缀类首部与字段 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 查询词、解析及测试说明 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 示例注释与描述性格式占位符 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| ASCII 字母与空白词元类型表 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 保留既有词位 bright 译法并记录英文 noun 疑点 | 例 | 例 | 例 | 例 | 例 | 例 | 例 | 例 | 例 | 例 | 例 | +| 全文检索、文本检索、词典及标题索引术语 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| URL 规范化术语 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| ts_stat 按权重统计词出现次数 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | + +正文证据包括 285 种英文段落、24 种表格行、2 种表格外层结构、6 种章节外层结构和 157 种示例,以及各自全部中文候选。实际绑定 3023 个段落/表格行和 1230 个示例块。修改后的完整译文与各版差异已复核,SQL、示例输出、版本参数、链接和手动锚点按本版保留。 + +新快照的十一版解析准备均成功。全书审计仍保留原始非零退出码(PG10—12 为 3,PG13—20 为 1);本章范围内只有 126 个既有中文列表 ID 提示,逐一核对完整父项、函数签名、段落、层级及顺序后保留。十一版中文当前源码、审定稿和新快照一致,固定英文与本次解包英文一致,未发现本章源码漂移。 + +英文将 `bright` 称为 noun 的疑点保留记录;中文沿用既有“词位”译法。保留原始示例、早期版本的限制及合法排版标签,没有修改固定英文。 + +完整依据:[问题矩阵](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/textsearch-book-issue-version-matrix.json)、[审定稿](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/textsearch-book-file-plans.json)、[逐段绑定](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/textsearch-book-read-unit-proof.json)、[新快照证明](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/textsearch-book-native-current-snapshot-proof.json)、[126 个锚点的完整中英父项](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/textsearch-book-native-parent-proof.json)。 diff --git a/docs/calibration-textsearch-followup-20260914.md b/docs/calibration-textsearch-followup-20260914.md new file mode 100644 index 00000000..0d4b9681 --- /dev/null +++ b/docs/calibration-textsearch-followup-20260914.md @@ -0,0 +1,49 @@ +**PG10—PG20:全文检索关联章节与 initdb 补充校准** + +更新时间:2026-09-14T15:45:48+08:00。本报告追加 23 个检查组、253 个版本格;检查组包含同一问题的多个表现及术语校准,不等于 23 个新增独立缺陷。 + +已按 PG18 优先阅读,并对照十一版各自固定英文完成本批正文修复。原 26 项清单和先前批次见[阶段总报告](/Users/vonng/pgsty/pgdoc/docs/calibration-20260914-status.md),全文检索主章见[主章校准报告](/Users/vonng/pgsty/pgdoc/docs/calibration-textsearch-20260914.md)。 + +**逐问题版本核验**。修=本轮修复;核=对照本版英文后确认原有内容正确;无=本版英文不具备该参数或内容。已经清除的未来内容记为“修”。 + +| 检查组 | 级别 | PG10 | PG11 | PG12 | PG13 | PG14 | PG15 | PG16 | PG17 | PG18 | PG19 | PG20 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| initdb 混入 PG18 默认启用与性能损失说明 | P2 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 修 | 核 | 核 | 核 | +| initdb 混入 --no-data-checksums | P2 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 核 | 核 | 核 | +| initdb 混入 --no-sync-data-files | P2 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 修 | 核 | 核 | 核 | +| initdb 混入 -c / --set | P2 | 无 | 无 | 无 | 无 | 修 | 修 | 核 | 核 | 核 | 核 | 核 | +| initdb 混入 -s / --show | P2 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 核 | 核 | 核 | 核 | +| initdb 混入 --sync-method | P2 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 核 | 核 | 核 | 核 | +| PG14 认证说明沿用新版段落与链接 | P2 | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| PG14 --sync-only 混入新版补充句 | P2 | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| 超级用户有效身份;PG15 缺 postgres 名称说明 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 核 | 核 | 核 | 核 | 核 | +| 密码选项保留各版超级用户称谓 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 核 | 核 | 核 | 核 | 核 | +| initdb 交叉引用标签遗漏与未译 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 无 | 无 | 无 | +| initdb 默认文本检索配置术语 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| initdb 选项分组与顺序混入新版 | P2 | 核 | 核 | 核 | 核 | 修 | 修 | 修 | 核 | 核 | 核 | 核 | +| PG14/15 集簇定义及模板库引言未跟随本版 | P2 | 核 | 核 | 核 | 核 | 修 | 修 | 核 | 核 | 核 | 核 | 核 | +| PG14 参见列表混入新版链接 | P3 | 核 | 核 | 核 | 核 | 修 | 核 | 核 | 核 | 核 | 核 | 核 | +| unaccent 混入 PG17 起的带引号转换规则 | P2 | 无 | 无 | 无 | 无 | 修 | 修 | 修 | 核 | 核 | 核 | 核 | +| 全文/文本检索、词典、词元、解析器及索引标题 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| dict_int 把不同词误译为唯一词 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| pg_ts_config_map 缺解析器限定;恢复查询顺序 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 词典模板实现函数及普通用户说明 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| headline / lextype 回调名称误译 | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| get_current_ts_config 说明标点与 OID | P3 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | +| 创建词典模板中普通用户设置参数的含义 | P2 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | 修 | + +**本批阅读与检查证据**:`initdb` 完整对照了 56 个参数/环境变量变体、10 个文件框架、336 个条目,复核 15 组最终改动。共移除 16 个未来参数条目,保留各版 ICU/builtin、校验和、认证、编码和环境变量差异。`unaccent` 十一版全文完成对照,188 个段落绑定,PG14—16 的带引号规则及示例整项删除,PG17—20 保留。 + +关联术语完成了 182 个初始配对变体、34 个补充变体,以及三个 SQL 参考页的十一版完整对照。235 个文件内有 1444 个完整父单元绑定;48 组补充最终中英对照已复核,1225 处为经过逐组阅读后确定的术语替换。该范围内的 SGML 标签、属性、链接及 3847 个代码块保持原样。范围之外的章节仍按全书待办继续核查。 + +全项目十一版重新检索“全文搜索、文本搜索、文本检索字典、过滤字典、分类字典”已无残留;该检索结果只作为术语残留检查。新参数在其他章节的三处命中均位于 PG18 发行说明,三个完整中英段落已读,内容与本版一致。差异检查清理了 14 处代码块之外的行尾空白,`git diff --check` 通过。 + +**本批解析核验完成**:257 个文件、1466 个完整父单元与当前源码、审定稿、固定英文和新快照一致,零漂移。334 个范围内提示已逐项核定,证据见下方文件。全书原始结构检查退出码仍为 PG10—12 的 3、PG13—20 的 1;此处仅声明本批范围内完成核验。 + +**固定英文疑义已保留并记录**:`pg_ts_parser` 将解析器输出称为 lexeme;`ALTER TEXT SEARCH PARSER/TEMPLATE` 说明仅改名而语法含 `SET SCHEMA`;`dict_int` 的独立示例配置顺序存在歧义;PG11 发行说明将 `json(b)_to_tsvector` 的结果称为 query。没有自行改写固定英文的这些陈述。 + +**全任务仍在进行**:全书逐章语义核查、历史范围对账及最终 HTML/A4/US 构建继续进行。33 个最终构建目标均尚未完成验收,本报告不将此前构建或本批解析替代最终构建。 + +详细证据:[逐组十一版矩阵](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/textsearch-followup-issue-version-matrix.json)、[initdb 全文审定稿](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/initdb-full-file-plans.json)、[unaccent 全文审定稿](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/unaccent-full-finalized-file-plans.json)、[关联父单元绑定](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/textsearch-terms-followup-finalized-parent-plans.json)、[差异空白修正](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/textsearch-followup-whitespace-finalization.json)。 + +解析证据:[当前源码与快照绑定](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/textsearch-followup-native-current-snapshot-proof.json)、[逐项处置](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/textsearch-followup-native-dispositions.json)、[完整父块复核](/Users/vonng/pgsty/pgdoc/outputs/pg10-20-calibration-20260911-134417/zcode-followup/textsearch-followup-native-parent-proof.json)。 diff --git a/zh/10/array.sgml b/zh/10/array.sgml index fd449b60..706c8191 100644 --- a/zh/10/array.sgml +++ b/zh/10/array.sgml @@ -4,7 +4,7 @@ 数组 - array + 数组 PostgreSQL 允许将表列定义为变长多维数组。可以创建任何内置或用户定义的基础类型、枚举类型或复合类型的数组。尚不支持域的数组。 @@ -13,8 +13,8 @@ 数组类型的声明 - array - declaration + 数组 + 声明 @@ -62,8 +62,8 @@ CREATE TABLE tictactoe ( 数组值输入 - array - constant + 数组 + 常量 @@ -84,7 +84,7 @@ CREATE TABLE tictactoe ( (这类数组常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。必要时可能需要显式指定类型。) + linkend="sql-syntax-constants-generic">中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。可能需要显式指定类型。) @@ -116,7 +116,10 @@ SELECT * FROM sal_emp; - 多维数组在每个维度上的长度必须匹配。不匹配会导致错误,例如: + + 多维数组的各个子数组在每个维度上的长度必须匹配。不匹配会导致错误,例如: + + INSERT INTO sal_emp VALUES ('Bill', '{10000, 10000, 10000, 10000}', @@ -146,8 +149,8 @@ INSERT INTO sal_emp 访问数组 - array - accessing + 数组 + 访问 @@ -180,9 +183,9 @@ SELECT pay_by_quarter[3] FROM sal_emp; - 我们还可以访问数组或子数组的任意矩形切片。数组切片通过在一个或多个数组维度上写成 + 我们还可以访问数组的任意矩形切片,即子数组。数组切片通过在一个或多个数组维度上写成 lower-bound:upper-bound - 的形式来表示。例如,下面这个查询取回 Bill 在一周前两天日程安排中的第一个项目: + 的形式来表示。例如,下面这个查询取回 Bill 在一周中前两天里每天的首项日程: SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill'; @@ -229,11 +232,11 @@ SELECT schedule[:][1:1] FROM sal_emp WHERE name = 'Bill'; - 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回空值。此外,如果下标超出数组边界,也会返回空值(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是空值而不是错误。 + 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回 NULL。此外,如果下标超出数组边界,也会返回 NULL(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是 NULL 而不是错误。 - 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回空值。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是空值。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回空值。 + 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回 NULL。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是 NULL。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回 NULL。 @@ -287,8 +290,8 @@ SELECT cardinality(schedule) FROM sal_emp WHERE name = 'Carol'; 修改数组 - array - modifying + 数组 + 修改 @@ -325,7 +328,7 @@ UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}' - 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用空值填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含空值。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 + 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用 NULL 填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含 NULL。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 @@ -437,21 +440,21 @@ SELECT array_cat(ARRAY[5,6], ARRAY[[1,2],[3,4]]); 在简单情况下,优先使用上面讨论的连接操作符,而不是直接调用这些函数。不过,由于连接操作符被重载以同时服务于这三种情形,所以在某些场景下使用这些函数之一有助于避免歧义。例如,考虑: -SELECT ARRAY[1, 2] || '{3, 4}'; -- the untyped literal is taken as an array +SELECT ARRAY[1, 2] || '{3, 4}'; -- 未指定类型的字面量被当作数组 ?column? ----------- {1,2,3,4} -SELECT ARRAY[1, 2] || '7'; -- so is this one +SELECT ARRAY[1, 2] || '7'; -- 这个字面量也一样 ERROR: malformed array literal: "7" -SELECT ARRAY[1, 2] || NULL; -- so is an undecorated NULL +SELECT ARRAY[1, 2] || NULL; -- 未加类型修饰的 NULL 也一样 ?column? ---------- {1,2} (1 row) -SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant +SELECT array_append(ARRAY[1, 2], NULL); -- 这可能才是原本想表达的意思 array_append -------------- {1,2,NULL} @@ -465,8 +468,8 @@ SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant 在数组中搜索 - array - searching + 数组 + 搜索 @@ -507,9 +510,14 @@ SELECT * FROM 关于该函数的说明见 - 还可以使用&&操作符搜索数组,它检查左操作数是否与右操作数重叠。例如: + + 也可以使用 && 操作符来搜索数组,它会检查左操作数是否与右操作数有重叠。例如: + + SELECT * FROM sal_emp WHERE pay_by_quarter && ARRAY[10000]; -关于此操作符和其他数组操作符的更多说明,参见。可以通过适当的索引来加速这种搜索,参见。 + + + 关于该操作符和其他数组操作符的更多说明见。如所述,也可以通过适当的索引加速。 还可以使用array_positionarray_positions函数在数组中搜索特定值。前者返回某个值在数组中首次出现位置的下标;后者返回一个数组,其中包含该值在数组中所有出现位置的下标。例如: @@ -536,7 +544,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); 数组输入和输出语法 - array + 数组 I/O @@ -549,7 +557,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); - 默认情况下,数组各维度的下界索引值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: + 默认情况下,数组各维度的下界下标值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2 FROM (SELECT '[1:1][-2:-1][3:5]={{{1,2,3},{4,5,6}}}'::int[] AS f1) AS ss; diff --git a/zh/10/catalogs.sgml b/zh/10/catalogs.sgml index fdb05782..8645f815 100644 --- a/zh/10/catalogs.sgml +++ b/zh/10/catalogs.sgml @@ -310,27 +310,27 @@ pg_ts_config - 文本搜索配置 + 文本检索配置 pg_ts_config_map - 文本搜索配置的词元映射 + 文本检索配置的词元映射 pg_ts_dict - 文本搜索字典 + 文本检索词典 pg_ts_parser - 文本搜索分析器 + 文本检索解析器 pg_ts_template - 文本搜索模板 + 文本检索模板 @@ -6830,12 +6830,12 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config目录包含表示文本搜索配置的条目。一个配置指定某个特定的文本搜索分析器,以及针对该分析器每种输出词元类型所定义的字典列表。分析器由pg_ts_config项表示,而词元到字典的映射则由pg_ts_config系统目录包含表示文本检索配置的条目。一个配置指定某个特定的文本检索解析器,以及针对该解析器每种输出词元类型所定义的词典列表。解析器记录在pg_ts_config条目中,而词元到词典的映射则由pg_ts_config_map中的辅助项定义。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。 @@ -6866,7 +6866,7 @@ SCRAM-SHA-256$<iteration count>:&l name - 文本搜索配置名 + 文本检索配置名 @@ -6893,7 +6893,7 @@ SCRAM-SHA-256$<iteration count>:&l oid pg_ts_parser.oid - 该配置的文本搜索分析器的OID + 该配置的文本检索解析器的 OID @@ -6910,11 +6910,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config_map目录包含的项展示了对于每一个文本搜索配置的每一种输出词元类型,有哪些文本搜索字典可供查询以及以何种顺序。 + pg_ts_config_map 系统目录中的条目说明了,对于每个文本检索配置所用解析器的每种输出词元类型,应当查询哪些文本检索词典以及查询的顺序。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -6947,7 +6947,7 @@ SCRAM-SHA-256$<iteration count>:&l integer - 一种由配置的分析器送出的词元类型 + 一种由配置的解析器送出的词元类型 @@ -6965,7 +6965,7 @@ SCRAM-SHA-256$<iteration count>:&l oid pg_ts_dict.oid - 要查询的文本搜索字典的OID + 要查询的文本检索词典的 OID @@ -6982,11 +6982,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_dict目录包含定义文本搜索字典的项。一个字典依赖于一个文本搜索模板,它指定了所有需要的函数实现,字典本身则为模板支持的用户可设置参数提供值。这种分工允许无权限的用户创建字典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 + pg_ts_dict系统目录包含定义文本检索词典的项。一个词典依赖于一个文本检索模板,它指定了所有需要的实现函数,词典本身则为模板支持的用户可设置参数提供值。这种分工允许普通用户创建词典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7017,7 +7017,7 @@ SCRAM-SHA-256$<iteration count>:&l name - 文本搜索字典名 + 文本检索词典名 @@ -7026,7 +7026,7 @@ SCRAM-SHA-256$<iteration count>:&l oid pg_namespace.oid - 包含该字典的名字空间OID + 包含该词典的名字空间的 OID @@ -7035,7 +7035,7 @@ SCRAM-SHA-256$<iteration count>:&l oid pg_authid.oid - 字典的拥有者 + 词典的拥有者 @@ -7044,7 +7044,7 @@ SCRAM-SHA-256$<iteration count>:&l oid pg_ts_template.oid - 该字典的文本搜索模板的OID + 该词典的文本检索模板的 OID @@ -7070,11 +7070,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_parser目录包含定义文本搜索分析器的项。一个分析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个分析器必须用C语言级别的函数实现,创建新分析器的工作只限于数据库的超级用户。 + pg_ts_parser系统目录包含定义文本检索解析器的项。一个解析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个解析器必须用 C 语言级别的函数实现,创建新解析器的工作只限于数据库的超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7105,7 +7105,7 @@ SCRAM-SHA-256$<iteration count>:&l name - 文本搜索分析器的名字 + 文本检索解析器的名字 @@ -7114,7 +7114,7 @@ SCRAM-SHA-256$<iteration count>:&l oid pg_namespace.oid - 包含此分析器的名字空间的OID + 包含此解析器的名字空间的 OID @@ -7123,7 +7123,7 @@ SCRAM-SHA-256$<iteration count>:&l regproc pg_proc.oid - 分析器启动函数的OID + 解析器启动函数的 OID @@ -7132,7 +7132,7 @@ SCRAM-SHA-256$<iteration count>:&l regproc pg_proc.oid - 分析器的下一词元函数的OID + 解析器的下一词元函数的 OID @@ -7141,7 +7141,7 @@ SCRAM-SHA-256$<iteration count>:&l regproc pg_proc.oid - 分析器的关闭函数的OID + 解析器的关闭函数的 OID @@ -7150,7 +7150,7 @@ SCRAM-SHA-256$<iteration count>:&l regproc pg_proc.oid - 分析器标题函数的 OID + 解析器的 headline 函数的 OID @@ -7159,7 +7159,7 @@ SCRAM-SHA-256$<iteration count>:&l regproc pg_proc.oid - 分析器的词汇类型函数的OID + 解析器的 lextype 函数的 OID @@ -7176,11 +7176,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_template目录包含定义文本搜索模板的项。一个模板是一类文本搜索字典的实现骨架。由于一个模板必须用C语言级别的函数实现,新模板的创建只限于数据库超级用户。 + pg_ts_template系统目录包含定义文本检索模板的项。一个模板是一类文本检索词典的实现骨架。由于一个模板必须用 C 语言级别的函数实现,新模板的创建只限于数据库超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7211,7 +7211,7 @@ SCRAM-SHA-256$<iteration count>:&l name - 文本搜索模板的名字 + 文本检索模板的名字 diff --git a/zh/10/config.sgml b/zh/10/config.sgml index 2bf2aabd..7fc0148b 100644 --- a/zh/10/config.sgml +++ b/zh/10/config.sgml @@ -2788,13 +2788,13 @@ ANY num_sync ( num_sync ( )。 + 设置规划器对一系列顺序磁盘页面读取中单次读取的代价估计。默认值是 1.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -2824,7 +2823,7 @@ ANY num_sync ( )。 + 设置规划器对一次非顺序磁盘页面读取的代价估计。默认值是 4.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -2846,8 +2845,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( - 遗传查询优化 + 遗传查询优化器 - GEQO是一个使用探索式搜索来执行查询规划的算法。它可以降低负载查询的规划时间。 同时,GEQO的检索是随机的,因此它的规划可能会不可确定。 更多信息参阅Chapter 50。 - 遗传查询规划器(GEQO)是一种使用启发式搜索来进行查询规划的算法。它可以降低对于复杂查询(连接很多表的查询)的规划时间,但是代价是它产生的计划有时候要差于使用穷举搜索算法找到的计划。详见。 + 遗传查询优化器(GEQO)是一种使用启发式搜索进行查询规划的算法。它可以缩短复杂查询(连接很多关系的查询)的规划时间,代价是生成的计划有时不如常规穷举搜索算法找到的计划。更多信息见 @@ -3007,7 +3004,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( - 在哪里做日志 + 日志记录到哪里 日志写到哪里 @@ -3282,7 +3277,7 @@ SELECT * FROM parent WHERE key = 2400; current_logfiles - 和日志_目的地配置参数 + 和 log_destination 配置参数 @@ -3309,7 +3304,7 @@ csvlog log/postgresql.csv - 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设备LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: + 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设施LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: local0.* /var/log/postgresql @@ -3317,7 +3312,7 @@ local0.* /var/log/postgresql - 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源极其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见。 + 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源及其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见 @@ -3333,20 +3328,20 @@ local0.* /var/log/postgresql - 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 + 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息可能不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 - 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供方法来轮转日志文件。还有,在某些不使用日志收集器的平台上可能会导致丢失或者混淆日志输出,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 + 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供便捷的方法来轮转日志文件。还有,在某些平台上,不使用日志收集器可能会导致日志输出丢失或混杂,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 - 日志收集器被设计成从来不会丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 + 日志收集器被设计成从来不会丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它可能会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 @@ -3378,7 +3373,7 @@ local0.* /var/log/postgresql logging_collector被启用时,这个参数设置被创建的日志文件的文件名。 - 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何时区独立的%转义,计算将在由指定的时区中完成)。 + 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何依赖时区的%转义,计算将在由指定的时区中完成)。 被支持的%转义和开放组织的strftime说明中列举的类似。 注意系统的strftime不会被直接使用,因此平台相关(非标准)的扩展无法工作。 默认是postgresql-%Y-%m-%d_%H%M%S.log。 @@ -3405,7 +3400,7 @@ local0.* /var/log/postgresql - 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的十进制格式,该数字必须以一个0(零)开始)。 + 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的八进制格式,该数字必须以一个0(零)开始)。 @@ -3466,7 +3461,7 @@ local0.* /var/log/postgresql - 示例:要保留 24 小时的日志,每个小时一个日志文件,但是在日志文件尺寸超过 1GB 时轮转。可以这样做:将log_filename设置为server_log.%H%M、 + 示例:要保留 24 小时的日志,每个小时一个日志文件,如果日志文件尺寸超过 1GB,也会提前轮转。可以这样做:将log_filename设置为server_log.%H%M、 将log_truncate_on_rotation设置为on、 将log_rotation_age设置为60并且 将log_rotation_size设置为1000000。 @@ -3485,7 +3480,7 @@ local0.* /var/log/postgresql - 当启用了向syslog记录时,这个参数决定要使用的syslog设备。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4、 + 当启用了向syslog记录时,这个参数决定要使用的syslog设施。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4LOCAL5LOCAL6LOCAL7中选择,默认值是LOCAL0。还请参阅系统的syslog守护进程的文档。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -3540,7 +3535,7 @@ local0.* /var/log/postgresql - 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,有必要让消息保持逻辑上的整体性(也更加有用)。 + 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,让消息保持逻辑上的完整性可能是必要的,也可能更有用。 @@ -3602,9 +3597,7 @@ local0.* /var/log/postgresql - 控制在服务器日志中记录哪些导致错误条件的SQL语句。当前的SQL语句将包含在任何指定 - severity - 或更高消息的日志条目中。 + 控制在服务器日志中记录哪些导致错误条件的SQL语句。对于达到指定严重级别或更高级别的消息,其日志条目中会包含当前 SQL 语句。 有效值为DEBUG5DEBUG4DEBUG3DEBUG2DEBUG1、 @@ -3636,7 +3629,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -3670,7 +3663,7 @@ local0.* /var/log/postgresql DEBUG1..DEBUG5 - 为开发者提供连续的更详细的信息。 + 为开发者提供逐级更加详细的信息。 DEBUG INFORMATION @@ -3729,7 +3722,7 @@ local0.* /var/log/postgresql - 记录什么到日志 + 记录哪些内容 @@ -3750,7 +3743,7 @@ local0.* /var/log/postgresql - application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。它也会被通过包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为问号(?)。 + application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。也可以通过将其包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为问号(?)。 @@ -3774,7 +3767,6 @@ local0.* /var/log/postgresql - 这个参数启用发出各种调试输出。当设置时,会打印生成的解析树, 查询重写输出,或执行的每个查询的执行计划。这些信息是在LOG 信息级别发出,因此默认的,它们会出现在服务器日志中,但不会发送给客户端。 可以通过 client_min_messages和/或log_min_messages 来设置。这些参数缺省是off。 这些参数将会让多种调试输出被发出。当被设置时,它们为每一个被执行的查询打印结果分析树、查询重写器输出或执行计划。这些消息在LOG消息级别上被发出,因此默认情况下它们将出现在服务器日志中但不会被发送到客户端。你可以通过调整和/或来改变这种情况。这些参数默认是关闭的。 @@ -3808,7 +3800,7 @@ local0.* /var/log/postgresql 导致检查点和重启点在服务器日志中记录。日志消息中包括一些统计信息, 包括写入的缓冲区数量和写入它们所花费的时间。此参数只能在 - postgresql.conf文件或服务器命令行中设置。默认值为开启。 + postgresql.conf文件或服务器命令行中设置。默认值为关闭。 @@ -3865,7 +3857,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -3887,7 +3879,7 @@ local0.* /var/log/postgresql 控制在服务器日志中记录的每条消息的详细程度。有效值为TERSE, - DEFAULTVERBOSE,每个值都会添加更多字段到显示的消息中。 + DEFAULTVERBOSE,它们依次在显示的消息中增加更多字段。 TERSE不包括DETAILHINTQUERYCONTEXT错误信息的记录。 VERBOSE输出包括SQLSTATE错误代码 @@ -3907,7 +3899,7 @@ local0.* /var/log/postgresql - 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致很微小的性能损失。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致不可忽视的性能开销。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -3980,8 +3972,8 @@ local0.* /var/log/postgresql %n - 带毫秒的时间戳(作为 Unix 时代) - no + 带毫秒精度的 Unix 时间戳 + %i @@ -4096,7 +4088,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' UPDATEDELETETRUNCATE, 和COPY FROM。 如果PREPAREEXECUTE和 - EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个执行消息时会产生日志并且会包括绑定参数的值(任何内嵌的单引号会被双写)。 + EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个 Execute 消息时会产生日志并且会包括 Bind 参数的值(任何内嵌的单引号会被双写)。 @@ -4107,7 +4099,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在执行阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 + 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在 Execute 阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 @@ -4144,7 +4136,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 控制临时文件名和大小的日志记录。 - 临时文件可以用于排序、哈希和临时查询结果。 + 临时文件可以用于排序、hash 和临时查询结果。 每当删除临时文件时都会发出日志记录。 值为零时记录所有临时文件信息,而正值仅记录大小大于或等于指定千字节数的文件。 默认设置为-1,禁用此类日志记录。 @@ -4222,7 +4214,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 设置log_filenamelog_rotation_age为你的日志文件提供一种一致的、可预测的命名空间。这让你预测文件名会是怎样以及知道什么时候一个个体日志文件完成并且因此准备好被导入。 + 设置log_filenamelog_rotation_age,为日志文件提供一致且可预测的命名方案。这样就能预测文件名,并知道单个日志文件何时已完成写入、可以导入。 @@ -4251,8 +4243,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 进程标题 - 这些设置控制服务器进程的进程标题如何修改。通常可以通过ps等程序查看进程标题, - 在 Windows 上则可以使用Process Explorer。详情参见。 + 这些设置控制服务器进程的进程标题如何修改。通常可以通过ps等程序查看进程标题,在 Windows 上则可以使用Process Explorer。详情参见 @@ -4279,7 +4270,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 每次服务器接收到新的SQL命令时,都可以更新进程标题。 + 启用后,每次服务器接收到新的 SQL 命令时都会更新进程标题。 在大多数平台上,默认情况下此设置为on,但在Windows上默认为off, 因为该平台更新进程标题的开销较大。 只有超级用户能更改这个设置。 @@ -4314,7 +4305,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对每个会话当前执行命令的信息收集,包括命令开始执行的时间。 - 此参数默认为开启状态。请注意,即使启用了此信息,只有超级用户、具有 + 此参数默认为开启状态。请注意,即使启用了此参数,只有超级用户、具有 pg_read_all_stats角色权限的角色和拥有被报告会话的用户 (包括属于他们具有权限的角色的会话)才能看到此信息,因此不应构成安全风险。 只有超级用户能更改这个设置。 @@ -4330,7 +4321,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 为每个活动会话指定存储当前执行命令的文本所保留的字节数,它们被用于pg_stat_activity.query域。 + 为每个活动会话指定存储当前执行命令的文本所预留的字节数,它们被用于pg_stat_activity.query字段。 默认值是 1024字节。这个参数只能在服务器启动时被设置。 @@ -4347,7 +4338,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对数据库活动的统计信息收集。 - 此参数默认为开启,因为自动清理守护进程需要收集的信息。 + 此参数默认为开启,因为自动清理守护进程需要这些收集到的信息。 只有超级用户能更改这个设置。 @@ -4361,7 +4352,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用数据库I/O调用的计时。 默认情况下,此参数处于关闭状态,因为它将重复查询操作系统的当前时间,这可能会在某些平台上造成显著的开销。 您可以使用工具来测量系统上计时的开销。 + 启用数据库I/O调用的计时。 默认情况下,此参数处于关闭状态,因为它将重复查询操作系统的当前时间,这可能会在某些平台上造成显著的开销。 你可以使用工具来测量系统上计时的开销。 I/O计时信息显示在中,也显示在使用BUFFERS选项的输出中, 并由提供。只有超级用户能更改这个设置。 @@ -4378,7 +4369,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用函数调用次数和时间的跟踪。指定pl以仅跟踪过程语言函数, + 启用函数调用次数和耗时的跟踪。指定pl以仅跟踪过程语言函数, all以同时跟踪SQL和C语言函数。默认值为none, 即禁用函数统计跟踪。只有超级用户能更改这个设置。 @@ -4438,7 +4429,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 对于每个查询,将各自模块的性能统计输出到服务器日志中。这是一个简单的性能分析工具,类似于Unix getrusage()操作系统功能。 - log_statement_stats报告总语句统计,而其他选项报告每个模块的统计信息。 + log_statement_stats报告整个语句的统计信息,而其他选项报告每个模块的统计信息。 log_statement_stats不能与任何单独模块选项一起启用。所有这些选项默认情况下都是禁用的。 只有超级用户才能更改这些设置。 @@ -4454,7 +4445,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 自动清理 - autovacuum + 自动清理 配置参数 @@ -4494,10 +4485,10 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 每次由自动清理执行的操作都会被记录,如果运行时间至少达到指定毫秒数。将此设置为零会记录所有自动清理操作。 + 当自动清理执行的操作运行时间至少达到指定毫秒数时,就会记录该操作。将此设置为零会记录所有自动清理操作。 负一(默认值)会禁用记录自动清理操作。 例如,如果将其设置为250ms,则所有运行时间为250ms或更长的自动清理和分析都将被记录。 - 此外,当此参数设置为任何值而不是-1时,如果由于冲突的锁定而跳过自动清理操作,则会记录消息。 + 此外,当此参数设置为任何非-1值时,如果由于冲突锁而跳过自动清理操作,则会记录消息。 启用此参数可帮助跟踪自动清理活动。 此参数只能在postgresql.conf文件或服务器命令行中设置;但可以通过更改表存储参数来覆盖对单个表的设置。 @@ -4677,7 +4668,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; DEBUG1LOGNOTICEWARNINGERROR。 每个级别都包括其后的所有级别。级别越靠后,被发送的消息越少。默认值是NOTICE。 - 注意LOG在这里有与中不同的排名。 + 注意LOG在这里的排序与中的不同。 @@ -4695,11 +4686,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,用于进行搜索该对象的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 + 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,搜索该对象时的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 - search_path的值必需是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被安静地忽略。 + search_path的值必须是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被静默忽略。 @@ -4727,11 +4718,12 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个参数的缺省值是"$user", public。这种设置支持一个数据库(其中没有用户拥有私有模式,并且所有人共享使用public)、每个用户私有模式及其组合的共享使用。其它效果可以通过全局或者针对每个用户修改默认搜索路径设置获得。 + 这个参数的默认值是"$user", public。这种设置支持共享使用数据库(用户没有私有模式,所有人共享使用public)、每个用户拥有私有模式,以及二者的组合。 + 还可以通过全局或针对每个用户修改默认搜索路径设置来获得其他效果。 - 更多有关方案处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 + 更多有关模式处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 @@ -4749,7 +4741,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,只要有至少一条策略被应用则查询就会失败。默认为on。受限的行可见性会导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS)属性的角色没有效果。 + 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,原本会应用至少一条策略的查询就会失败。默认为on。受限的行可见性可能导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS属性的角色)没有效果。 @@ -4771,7 +4763,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建企图将失败。 + 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建尝试将失败。 @@ -4779,7 +4771,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当创建数据库时也会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 + 创建数据库时也不会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 @@ -4803,11 +4795,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被放置在里表中的连续表空间中。如果列表被选中元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 + 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被依次放置在列表中的连续表空间中。如果列表中被选中的元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 - 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,类似于为用户指定一个不具有CREATE权限的表空间。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特殊地,使用一个在postgresql.conf中设置的值时,这条规则起效。 + 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,指定一个用户不具有CREATE权限的表空间也同样是错误。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特别是,使用一个在postgresql.conf中设置的值时,这条规则起效。 @@ -4830,7 +4822,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 这个参数通常为打开。 当设置为off时,它禁用期间对函数体字符串的验证。 - 禁用验证避免了验证处理的副作用,特别避免了如向前引用导致的伪肯定。 + 禁用验证避免了验证处理的副作用,也避免前向引用等问题导致的误报。 在代表其他用户载入函数之前设置这个参数为offpg_dump会自动这样做。 @@ -4873,7 +4865,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态 。默认是off(读/写)。 + 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态。默认是off(读/写)。 @@ -4894,11 +4886,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当运行在serializable隔离级别时,一个可延迟只读 SQL 事务可以在它被允许继续之前延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的负荷;因此串行化代码将没有任何理由因为并发更新而强制它中断,使得这个选项适合于长时间运行的只读事务。 + 当运行在serializable隔离级别时,一个可延迟只读 SQL 事务可能在获准继续之前被延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的开销;因此串行化代码将没有任何理由因为并发更新而强制它中止,使得这个选项适合于长时间运行的只读事务。 - 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些操作在低于serializable隔离级别上的事务无效。默认值是off。 + 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些运行在低于serializable隔离级别上的事务无效。默认值是off @@ -4942,7 +4934,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的只读状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -4962,7 +4954,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的可延迟性状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -5016,7 +5008,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为事务超时将总是第一个被触发。 + 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为语句超时将总是第一个被触发。 如果log_min_error_statement 被设置为ERROR 或更低,超时的语句将被记录。 @@ -5050,8 +5042,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; + - 当表的pg_class.relfrozenxid字段达到该设置指定的年龄时,VACUUM会执行激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值是 1.5 亿个事务。尽管用户可以将该值设置为 0 到 20 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的 95%,从而在触发防回卷 autovacuum 之前仍有机会执行一次常规手工VACUUM。更多信息请参见。 + 如果表的pg_class.relfrozenxid字段达到此设置指定的年龄,VACUUM就会执行一次激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值为 1.5 亿个事务。尽管用户可以将该值设置在 0 到 20 亿之间,VACUUM仍会悄悄将其有效值限制为不超过的 95%,以便在针对该表启动防回卷自动清理之前,周期性手工VACUUM仍有机会运行。详见 @@ -5064,7 +5057,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 指定VACUUM在扫描表时用来决定是否冻结行版本的切断年龄(以事务计)。默认值是 5000 万个事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见。 + 指定VACUUM在扫描表时用来决定是否冻结行版本的截止年龄(以事务计)。默认值是 5000 万个事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见 @@ -5076,8 +5069,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; + - 当表的pg_class.relminmxid字段达到该设置指定的年龄时,VACUUM会执行激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不是只扫描那些可能包含死元组的页面。默认值是 1.5 亿个多事务。尽管用户可以将该值设置为 0 到 20 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的 95%,从而在触发防回卷 autovacuum 之前仍有机会执行一次常规手工VACUUM。更多信息请参见。 + 如果表的pg_class.relminmxid字段达到此设置指定的年龄,VACUUM就会执行一次激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值为 1.5 亿个多事务。尽管用户可以将该值设置在 0 到 20 亿之间,VACUUM仍会悄悄将其有效值限制为不超过的 95%,以便在针对该表启动防回卷清理之前,周期性手工VACUUM仍有机会运行。详见 @@ -5090,7 +5084,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 指定VACUUM在扫描表时用来决定是否将多事务 ID 替换为较新的事务 ID 或多事务 ID 的切断年龄(以多事务计)。默认值是 500 万个多事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见。 + 指定VACUUM在扫描表时用来决定是否将多事务 ID 替换为较新的事务 ID 或多事务 ID 的截止年龄(以多事务计)。默认值是 500 万个多事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见 @@ -5124,7 +5118,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这里的实际选择都是根据爱好做出的,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码将比 base64 编码更大。 + 这里的实际选择主要取决于偏好,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码会比 base64 编码略大。 @@ -5145,7 +5139,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当在XML和字符串值之间进行转换时,无论设置DOCUMENT或 CONTENT都是隐式的。可参阅Section 8.13。 有效值是DOCUMENT和CONTENT。 缺省值是CONTENT。当在 XML 和字符串值之间进行转换时,设置DOCUMENTCONTENT都是隐式的。详见。有效值是DOCUMENTCONTENT。默认值是CONTENT。 + 设置在 XML 与字符串值之间进行转换时,隐含采用DOCUMENT还是CONTENT。 + 有关说明参见。有效值是DOCUMENTCONTENT。默认值是CONTENT @@ -5177,7 +5172,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 区域和格式化 + 区域设置和格式化 @@ -5191,7 +5186,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域行为的设置初始化配置文件。 + 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域设置行为的设置初始化配置文件。 @@ -5204,10 +5199,13 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置间隔值的显示格式。值sql_standard将产生匹配SQL标准间隔文本的输出。当参数被设置为ISO时,值postgres(默认)将产生匹配PostgreSQL发行 8.4 之前的输出。当DateStyle参数被设置为非ISO输出时,值postgres_verbose会产生匹配PostgreSQL发行 8.4 之前的输出。值iso_8601会产生匹配在 ISO 8601 的 4.4.3.2 节中定义的带标志符格式的时间间隔的输出。 + 设置时间间隔值的显示格式。值sql_standard会生成符合SQL标准时间间隔字面量的输出。 + 值postgres(默认值)的输出与PostgreSQL 8.4 之前版本中设为ISO时的输出一致。 + 值postgres_verbose的输出与PostgreSQL 8.4 之前版本中DateStyle设为非ISO输出时的输出一致。 + 值iso_8601会生成符合 ISO 8601 第 4.4.3.2 节定义的时间间隔带标志符格式的输出。 - IntervalStyle参数也可以影响对有歧义的间隔输入的解释。详见。 + IntervalStyle参数也会影响对有歧义的时间间隔输入的解释。详见 @@ -5297,11 +5295,11 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 在一些系统上,这个区域分类并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 + 在一些系统上,这个区域设置类别并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 - 只有超级用户能更改这个设置。 + 只有超级用户能更改这个设置,因为它会同时影响发送到服务器日志和客户端的消息,设置不当可能降低服务器日志的可读性。 @@ -5316,7 +5314,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化货币量的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化货币量的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -5331,7 +5329,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化数字的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化数字的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -5346,7 +5344,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化日期和时间的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化日期和时间的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -5361,7 +5359,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 选择被那些没有显式参数指定配置的文本搜索函数变体使用的文本搜索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配区域的配置,initdb将用对应于选中的lc_ctype区域的设置初始化配置文件。 + 选择被那些没有显式参数指定配置的文本检索函数变体使用的文本检索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配该区域设置的配置,initdb将用对应于选中的lc_ctype区域设置的值初始化配置文件。 @@ -5375,7 +5373,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 为了载入附加的功能或者达到提高性能的目的,可用多个设置来预先载入共享库到服务器中。 - 例如'$libdir/mylib'设置可能会导致mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 + 例如'$libdir/mylib'设置会使mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 @@ -5384,12 +5382,12 @@ SET XML OPTION { DOCUMENT | CONTENT }; 只有特别为与PostgreSQL一起使用设计的共享库才能以这种方式载入。每一个PostgreSQL支持 - 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非PostgreSQL无法 + 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非 PostgreSQL 库无法 以这种方式被载入。你可能可以使用操作系统的工具(如LD_PRELOAD)载入它。 - 总之,请参考特定模块的文档来用推荐的方法载入它。 + 一般来说,请参考特定模块的文档来用推荐的方法载入它。 @@ -5421,9 +5419,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 这个特性的目的是允许非特权用户在特定的会话中载入正在调试的或者性能度量库, - 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客 - 户端的PGOPTIONS环境变量或者 + 这个特性的目的是允许非特权用户在特定的会话中载入用于调试或性能测量的库, + 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客户端的PGOPTIONS环境变量或者 ALTER ROLE SET来设置这个参数。 @@ -5460,7 +5457,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 不同,相对于在库被第一次使用 - 时载入它,在会话开始时载入库并没有什么性能优势。不过,当使用连接池时这样做还是有一些 + 时载入它,在会话开始时载入库并没有明显的性能优势。不过,当使用连接池时这样做还是有一些 优势。 @@ -5498,9 +5495,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 在 Windows 主机上,在服务器启动时预载入一个库并不会减少启动每个新服务器进程所需的 - 时间;每一个服务器进程将会重新载入预载入的库。不过,对于那些要在postmaster启动时 + 时间;每一个服务器进程将会重新载入所有预载入的库。不过,对于那些要在postmaster启动时 执行操作的库来说,Windows 主机上的 - shared_preload_libraries任然有用。 + shared_preload_libraries仍然有用。 @@ -5554,7 +5551,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - GIN 索引返回的集合尺寸的软上限。详见。 + GIN 索引扫描返回的集合尺寸的软上限。详见 @@ -5584,17 +5581,17 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这是在锁上等待的毫秒数,然后再检查是否存在死锁条件。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 + 指定在检查是否发生死锁之前等待锁的毫秒数。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 我们乐观地假设在生产应用程序中死锁并不常见,所以在检查死锁之前只是等待一段时间。 增加此值会减少在不必要的死锁检查中浪费的时间,但会减慢实际死锁错误的报告速度。 - 默认值为一秒(1s),这可能是您在实践中想要的最小值。 - 在负载较重的服务器上,您可能希望提高它。 - 理想情况下,设置应超过您的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 + 默认值为一秒(1s),这可能是你在实践中想要的最小值。 + 在负载较重的服务器上,你可能希望提高它。 + 理想情况下,设置应超过你的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 只有超级用户能更改这个设置。 - 当被设置时,这个参数还可以决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 + 当被设置时,这个参数也决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 @@ -5645,7 +5642,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制在谓词锁被提升为覆盖整个关系之前,该谓词锁能够在单个关系上锁住多少页面或元组。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个关系之前,可以对单个关系中的多少页面或元组加谓词锁。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -5660,7 +5657,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制在谓词锁被提升为覆盖整个页面之前,该谓词锁能在单一页面上锁住多少行。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个页面之前,可以对单个页面中的多少行加谓词锁。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -5686,7 +5683,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个空数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。对于那些要求旧行为的应用的向后兼容性,这个变量可以被设置为off。 + 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个值为空值的数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。为了向后兼容那些要求旧行为的应用,这个变量可以被设置为off @@ -5704,11 +5701,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制字符串文本中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\。如果客户端代码没有做到正确转义,那么将会导致 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 + 这个参数控制字符串字面量中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\。如果客户端代码没有做到正确转义,那么就可能遭到 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 - 注意在符合标准的字符串文本中,\就表示\。这个参数只影响不符合标准的文本的处理,包括转义字符串语法(E'...')。 + 注意在符合标准的字符串字面量中,\就表示\。这个参数只影响不符合标准的字面量的处理,包括转义字符串语法(E'...')。 @@ -5746,11 +5743,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 打开时,如果在普通字符串文本中('...'语法)出现了 一个反斜线(\)并且standard_conforming_strings为关闭,那么就会发出一个警告。默认值是on。 + 打开时,如果在普通字符串字面量中('...'语法)出现了 一个反斜线(\)并且standard_conforming_strings为关闭,那么就会发出一个警告。默认值是on - 希望使用反斜线作为转义符的应用应该被修改来使用转义字符串语法(E'...'),因为在 SQL 标准中普通字符串的默认行为是将反斜线视作一个普通字符。这个变量可以被启用来帮助定位需要被更改的代码。 + 希望使用反斜线作为转义符的应用应该被修改来使用转义字符串语法(E'...'),因为按照 SQL 标准,普通字符串现在默认将反斜线视作一个普通字符。这个变量可以被启用来帮助定位需要被更改的代码。 @@ -5811,7 +5808,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' standard_conforming_strings (boolean) - 字符串标准符合 + 字符串符合标准 standard_conforming_strings配置参数 @@ -5819,7 +5816,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 控制普通字符串文本('...')是否按照 SQL 标准把反斜线当普通文本。从PostgreSQL 9.1 开始,默认值为on(之前的发行中默认值为off)。应用可以检查这个参数来判断字符串文本如何被处理。这个参数的存在也可以被当做转义字符串语法(E'...')被支持的标志。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 + 控制普通字符串字面量('...')是否按照 SQL 标准把反斜线当普通文本。从PostgreSQL 9.1 开始,默认值为on(之前的发行中默认值为off)。应用可以检查这个参数来判断字符串字面量如何被处理。这个参数的存在也可以被当做转义字符串语法(E'...')被支持的标志。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 @@ -5834,7 +5831,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询来,这样的扫描会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on。 + 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询,这样的扫描可能会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on @@ -5857,15 +5854,15 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr得出空值值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空(未知)。因此这个参数默认为off。 + 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr计算结果为空值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空值(未知)。因此这个参数默认为off - 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释)。它们不是非常有用并且在普通应用中也不常见,在应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及 空值的表达式的语义上感到困惑,因此这个选项默认为关闭。 + 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释),它们不是非常有用并且在普通应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及空值的表达式语义感到困惑,因此这个选项默认为关闭。 - 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不是劣质程序的一般修复。 + 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不能普遍修复错误的程序写法。 @@ -5922,15 +5919,15 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果设置为false(默认值),PostgreSQL在将修改的数据文件刷新到文件系统失败时,将引发PANIC级错误。 + 如果设置为false(默认值),PostgreSQL在将修改后的数据文件刷盘到文件系统失败时,将引发PANIC级错误。 这样会导致数据库服务器崩溃。这个参数只能在服务器启动时被设置。 在某些操作系统上,回写失败后,内核页面缓存中的数据状态未知。 在某些情况下,它可能已被完全遗忘,因此重试不安全;第二次尝试可能报告为成功,而事实上数据已丢失。在此类情形下,避免数据丢失的唯一方法是在报告任何故障后从WAL中恢复,最好是在调查了故障的根本原因并更换了任何有故障的硬件之后。 - 如果设置为true,PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷新操作。 - 仅在调查操作系统假如回写失败时对缓冲数据的处理方式的情况下,才将其设置为true。 + 如果设置为true,PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷盘操作。 + 只有在调查清楚操作系统在回写失败时如何处理缓冲数据之后,才应将其设置为true。 @@ -5943,11 +5940,10 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 预置选项 - 下列参数是只读的。 - 同样,它们被排除在postgresql.conf文件示例之外。 - 这些选项报告特定应用可能感兴趣的多种PostgreSQL行为,特别是管理前端相关的行为。 - 所有这些都是在PostgreSQL被编译或者它被安装时决定的。 - + 下列参数是只读的,在编译或安装 PostgreSQL 时确定。 + 因此,它们未列入示例 postgresql.conf 文件。 + 这些选项报告 PostgreSQL 行为的各个方面,某些应用(特别是管理前端)可能对此感兴趣。 + @@ -5976,7 +5972,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告对这个集簇是否启用了数据校验码。详见。 + 报告对这个集簇是否启用了数据校验和。详见 @@ -6010,7 +6006,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告PostgreSQL是否在编译时打开了 64 位整数日期和时间。从PostgreSQL 10起,这个值总是on。 + 报告PostgreSQL是否在编译时启用了对 64 位整数日期和时间的支持。从PostgreSQL 10起,这个值总是on @@ -6057,7 +6053,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定的。默认值是 100 个参数。 + 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定。默认值是 100 个参数。 @@ -6072,7 +6068,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64 ;因此max_identifier_length的默认值是 63,但是在使用多字节编码时可以少于 63 个字符。 + 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64;因此max_identifier_length的默认值是 63 字节,在使用多字节编码时,这可能不足 63 个字符。 @@ -6133,7 +6129,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告服务器版本数值。它是由编译服务器时的PG_VERSION值决定的。 + 报告服务器的版本号。它是由编译服务器时的PG_VERSION值决定的。 @@ -6148,7 +6144,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告服务器版本数值的整数值。它是由编译服务器时的PG_VERSION_NUM值决定的。 + 以整数形式报告服务器的版本号。它是由编译服务器时的PG_VERSION_NUM值决定的。 @@ -6190,11 +6186,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 自定义选项 - 这个特性被设计用来由附加模块向PostgreSQL添加通常不为系统知道的参数(例如过程语言)。这允许使用标准方法配置扩展模块。 + 这个特性允许附加模块(例如过程语言)向PostgreSQL添加系统通常不认识的参数。这样便能以标准方式配置扩展模块。 - 自定义选项有两部分名称:一个扩展名,然后是一个句点,再然后是正确的参数名,就像 SQL 中的合格名称。一个示例是plpgsql.variable_conflict。 + 自定义选项的名称由两部分组成:扩展名称和参数名本身,中间用句点分隔,类似于 SQL 中的限定名。例如plpgsql.variable_conflict @@ -6202,7 +6198,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' PostgreSQL将接受任何两部分参数名称的设置。 这些变量被视为占位符,在定义它们的模块加载之前没有任何功能。 当加载扩展模块时,它将添加其变量定义并根据这些定义转换任何占位符值。 - 如果存在以其扩展名开头的任何未识别的占位符,将发出警告并删除这些占位符。 + 如果存在以其扩展名称开头的任何未识别的占位符,将发出警告。 @@ -6226,7 +6222,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 允许将表空间创建为pg_tblspc内的目录,当CREATE TABLESPACE命令提供空位置字符串时。 + 当向CREATE TABLESPACE命令提供空的位置字符串时,允许将表空间创建为pg_tblspc内的目录。 这旨在允许测试主库和备库在同一台机器上运行的复制场景。这样的目录可能会混淆备份工具,因为这些工具期望在该位置只找到符号链接。 只有超级用户能更改这个设置。 @@ -6257,7 +6253,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据的时有用。这个参数在会话开始之后不能被更改。 + 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据时有用。这个参数在会话开始之后不能被更改。 @@ -6302,7 +6298,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 + 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 @@ -6337,7 +6333,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果打开,发出在排序操作中的资源使用的相关信息。只有在编译PostgreSQL时定义了TRACE_SORT宏, 这个参数才可用(不过,当前在默认情况下就定义了TRACE_SORT)。 + 如果开启,输出排序操作中的资源使用信息。只有在编译PostgreSQL时定义了TRACE_SORT宏, 这个参数才可用(不过,当前在默认情况下就定义了TRACE_SORT)。 @@ -6351,7 +6347,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。对每一种锁类型,已授权锁和等待锁的计数也会被一起转储。一个日志文件输出的示例如下: + 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。还会转储每种锁类型已授予的锁数、等待的锁数,以及它们的总数。一个日志文件输出的示例如下: LOG: LockAcquire: new: lock(0xb7acd844) id(24688,24696,0,0,0,1) grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0 @@ -6420,7 +6416,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果设置,不会跟踪小于这个 OID 的锁(用于避免在系统表上的输出)。 + 如果设置,不会跟踪 OID 小于此值的表上的锁(用于避免在系统表上的输出)。 @@ -6491,7 +6487,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,被修改的任何缓冲区的整页镜像及其WAL记录都被加入到记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 + 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,与该 WAL 记录相关的所有已修改缓冲区的整页镜像都会被添加到该记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 @@ -6534,11 +6530,11 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 在读取过程中检测到校验和失败通常会导致PostgreSQL报告错误,中止当前事务。 - 将ignore_checksum_failure设置为on会导致系统忽略失败(但仍然报告警告),并继续处理。 - 这种行为可能导致崩溃,传播或隐藏损坏,或其他严重问题。然而,它可能允许您跳过错误, - 并检索可能仍然存在于表中的未损坏的元组,如果块头仍然正常。如果头部损坏,即使启用此选项也会报告错误。 - 默认设置为off。 - 只有超级用户能更改这个设置。 + 将ignore_checksum_failure设置为 on 会使系统忽略失败(但仍报告警告),并继续处理。 + 这种行为可能导致崩溃、传播或隐藏损坏,或引发其他严重问题。 + 但是,如果块首部仍然正常,它可能允许你跳过错误,检索表中可能仍然存在的未损坏元组。 + 如果首部损坏,即使启用此选项也会报告错误。默认设置为off。 + 只有超级用户才能更改此设置。 @@ -6555,7 +6551,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 检测到损坏的页面头通常会导致PostgreSQL报告错误,中止当前事务。 将zero_damaged_pages设置为on会导致系统报告警告,将内存中的损坏页面清零,并继续处理。 - 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许您跳过错误,并从表中可能存在的未损坏页面中检索行。 + 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许你跳过错误,并从表中可能存在的未损坏页面中检索行。 如果由于硬件或软件错误而发生损坏,这对于恢复数据很有用。通常在放弃从表的损坏页面恢复数据的希望之前,不应将其设置为on。 清零的页面不会强制写入磁盘,因此建议在再次关闭此参数之前重新创建表或索引。默认设置为off。 只有超级用户能更改这个设置。 @@ -6568,11 +6564,11 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 短选项 - 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,并且它们作为一个单字母选项存在并不表示它们会被大量使用。 + 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,它们以单字母选项的形式存在,并不一定表示鼓励频繁使用这些选项。
- 短选项键 + 短选项对照 diff --git a/zh/10/datatype.sgml b/zh/10/datatype.sgml index b92b994c..ed81b236 100644 --- a/zh/10/datatype.sgml +++ b/zh/10/datatype.sgml @@ -148,7 +148,7 @@ line - 平面上的无限长的线 + 平面上的无限直线 @@ -160,19 +160,19 @@ macaddr - MAC(Media Access Control)地址 + MAC(媒体访问控制)地址 macaddr8 - MAC(Media Access Control)地址(EUI-64格式) + MAC(媒体访问控制)地址(EUI-64格式) money - 货币数量 + 货币额 @@ -180,7 +180,7 @@ s) ] decimal [ (p, s) ] - 可选择精度的精确数字 + 可选择精度的精确数值 @@ -192,7 +192,7 @@ pg_lsn - PostgreSQL日志序列号类型 + PostgreSQL 日志序列号 @@ -264,13 +264,13 @@ tsquery - 文本搜索查询 + 文本检索查询 tsvector - 文本搜索文档 + 文本检索文档 @@ -407,14 +407,14 @@
- 数字类型常量的语法在里描述。数字类型有一整套对应的数学操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 + 数字类型常量的语法在里描述。数字类型有一整套对应的算术操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 整数类型 - 整数 + integer @@ -427,7 +427,7 @@ int4 - 整数 + integer @@ -447,11 +447,11 @@
- 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。而只有在integer的范围不够的时候才使用bigint。 + 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。bigint则设计用于integer的范围不够的情况。 - SQL只声明了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在许多其它SQL数据库系统中使用。 + SQL只规定了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在某些其他SQL数据库系统中使用。 @@ -460,11 +460,11 @@ 任意精度数值 - 数字(数据类型) + numeric(数据类型) - 任意精度数字 + 任意精度数值 @@ -476,7 +476,14 @@ 类型numeric可以存储非常多位的数字。我们特别建议将它用于货币金额和其它要求计算准确的数量。numeric值的计算在可能的情况下会得到准确的结果,例如加法、减法、乘法。不过,numeric类型上的算术运算比整数类型或者下一节描述的浮点数类型要慢很多。
- 下面使用如下术语:numeric精度是整个数中有效数字的总数,即小数点两侧的数字位数之和。numeric小数位数是小数部分中十进制数字的数量,即小数点右侧的位数。因此,数值 23.5141 的精度为 6,小数位数为 4。整数可以视为小数位数为零。 + + 我们在下文中使用以下术语: + 精度(precision)是一个numeric + 值中有效数字的总位数,也就是小数点两侧数字的总数。 + 小数位数(scale)是小数部分中位于小数点 + 右侧的十进制位数。因此,数值 23.5141 的精度为 6,小数位数为 4。 + 整数可以认为其小数位数为 0。 + 可以配置numeric列的最大精度和最大小数位数。要声明numeric类型的列,使用以下语法: NUMERIC(precision, scale) @@ -506,12 +513,12 @@ NUMERIC NaN - 非数字 + 非数 - 非数字 - 数字(数据类型) + 非数 + numeric(数据类型) 除了普通数值外,numeric类型还允许特殊值NaN,表示非数。对NaN的任何运算都会产生另一个NaN。在 SQL 命令中将该值写为常量时,必须加上引号,例如UPDATE table SET x = 'NaN'。输入时,字符串NaN的识别不区分大小写。 @@ -565,7 +572,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 双精度 + double precision @@ -575,7 +582,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; float8 - 双精度 + double precision @@ -618,7 +625,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 非数字 + 非数 double precision @@ -626,7 +633,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; Infinity -Infinity NaN -它们分别表示 IEEE 754 的特殊值无穷大负无穷大非数字。(在浮点运算不遵循 IEEE 754 的机器上,这些值可能无法按预期工作。)在 SQL 命令中将这些值写为常量时,必须加上引号,例如UPDATE table SET x = '-Infinity'。输入时,这些字符串的识别不区分大小写。 +它们分别表示 IEEE 754 的特殊值无穷大负无穷大非数。(在浮点运算不遵循 IEEE 754 的机器上,这些值可能无法按预期工作。)在 SQL 命令中将这些值写为常量时,必须加上引号,例如UPDATE table SET x = '-Infinity'。输入时,这些字符串的识别不区分大小写。
@@ -686,13 +693,13 @@ FROM generate_series(-3.5, 3.5, 1) as x; - auto-increment + 自动递增 serial - sequence - and serial type + 序列 + 与 serial 类型 @@ -817,7 +824,7 @@ ALTER SEQUENCE tablename_ SELECT '12.34'::float8::numeric::money;
- 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有圆整错误。 + 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有舍入误差。
@@ -829,7 +836,7 @@ SELECT '52093.89'::money::numeric::float8; 一个 money 值除以一个整数值时,会朝零方向截去小数 - 部分。要得到圆整结果,可以除以一个浮点值,或者在除法前先把 + 部分。要得到舍入后的结果,可以除以一个浮点值,或者在除法前先把 money 转换为 numeric,再在除法后转换回 money(如果要避免精度丢失风险,后一种做法更好)。 当一个 money 值被另一个 money 值除时, @@ -848,12 +855,12 @@ SELECT '52093.89'::money::numeric::float8; - string + 字符串 - 字符 + character @@ -888,7 +895,7 @@ SELECT '52093.89'::money::numeric::float8; character(n), char(n) - 定长,空白填充 + 定长,空格填充 text @@ -960,7 +967,7 @@ SELECT '52093.89'::money::numeric::float8; - 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储代码为零的字符(有时称为NUL)。有关更多信息,请参阅。 + 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储编码值为零的字符(有时称为NUL)。有关更多信息,请参阅 @@ -979,7 +986,7 @@ SELECT '52093.89'::money::numeric::float8; - 这三种类型之间没有性能差别,除了使用空白填充类型时会占用更多存储 + 这三种类型之间没有性能差别,除了使用空格填充类型时会占用更多存储 空间,以及在写入带长度约束的列时需要少量额外 CPU 周期来检查长度。 虽然在某些其他数据库系统中,character(n) 可能有一定性能优势,但在 PostgreSQL @@ -1014,7 +1021,7 @@ INSERT INTO test2 VALUES ('ok'); INSERT INTO test2 VALUES ('good '); INSERT INTO test2 VALUES ('too long'); ERROR: value too long for type character varying(5) -INSERT INTO test2 VALUES ('too long'::varchar(5)); -- explicit truncation +INSERT INTO test2 VALUES ('too long'::varchar(5)); -- 显式截断 SELECT b, char_length(b) FROM test2; b | char_length @@ -1133,7 +1140,7 @@ SELECT b, char_length(b) FROM test2; 开头(以便与转义格式区分)。在某些上下文中,这个开头的反斜线 可能需要通过双写进行转义(见 )。作为输入时,十六进制数字 - 可以使用大写或小写,并且在两个数字组成的一组之间允许出现空白 + 可以使用大写或小写,并且每两个数字组成一组,组与组之间允许出现空白 (但组内以及起始的 \x 序列中不能有空白)。 十六进制格式与大量外部应用和协议兼容,并且通常比转义格式转换得 更快,因此更推荐使用。 @@ -1185,7 +1192,7 @@ SELECT '\xDEADBEEF'; 0 - 0字节 + 零值字节 '\000' SELECT '\000'::bytea; \x00 @@ -1242,15 +1249,24 @@ SELECT '\xDEADBEEF'; - Bytea字节默认以hex格式输出。如果把改为escape, - 不可打印字节会被转换为等价的三位八进制值,并在前面加一个反斜线。大多数可打印字节以客户端字符集中相应的标准表示输出,例如: + 默认情况下,bytea 字节会以 hex + 格式输出。如果把 改为 + escape不可打印字节会被转换成 + 等价的三位八进制值,并在前面加一个反斜线。大多数 + 可打印字节则会按其在客户端字符集中的标准表示输出, + 例如: + + SET bytea_output = 'escape'; SELECT 'abc \153\154\155 \052\251\124'::bytea; bytea ---------------- abc klm *\251T -十进制值为 92 的字节(反斜线)在输出中会被双写。详情见。 + + + 十进制值 92(反斜线)的字节在输出中会被双写。详情见 + @@ -1316,10 +1332,10 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; time - 不带时区的时间 + time without time zone - 带时区的时间 + time with time zone timestamp @@ -1328,13 +1344,13 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; timestamptz - 带时区的时间戳 + timestamp with time zone - 不带时区的时间戳 + timestamp without time zone - 间隔 + interval 时间跨度 @@ -1418,7 +1434,7 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; - SQL 要求仅写 timestamp 时,应等效于 + SQL 标准要求仅写 timestamp 时,应等效于 timestamp without time zone,而 PostgreSQL 也遵循这种行为。 timestamptz 被接受为 @@ -1501,7 +1517,7 @@ MINUTE TO SECOND 其中 p 是可选的精度说明,给出秒字段中 保留的小数位数。精度可用于 timetimestampinterval 类型, - 范围是 0 到 6。这与前文描述的取值一致。如果在常量声明中没有指定 + 范围是 0 到 6。如果在常量声明中没有指定 精度,则默认采用该字面值本身的精度(但不超过 6 位)。 @@ -1528,7 +1544,7 @@ MINUTE TO SECOND 1999-01-08 - ISO 8601; 任何模式下的1月8日 + ISO 8601; 任何模式下的1月8日 (推荐格式) @@ -1564,27 +1580,27 @@ MINUTE TO SECOND 99-Jan-08 - YMD模式中的1月8日,否则错误 + YMD模式中的1月8日,否则报错 08-Jan-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 Jan-08-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 19990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 1999.008 - 年和一年中的日子 + 年和一年中的第几天 J2451187 @@ -1606,10 +1622,10 @@ MINUTE TO SECOND time - 无时区的时间 + time without time zone - 带时区的时间 + time with time zone @@ -1684,11 +1700,11 @@ MINUTE TO SECOND 040506+0730 - ISO 8601,以分数小时形式给出 UTC 偏移 + ISO 8601,时区的 UTC 偏移不是整小时 040506+07:30:00 - UTC偏移量指定为秒(ISO 8601中不允许) + UTC 偏移精确到秒(ISO 8601中不允许) 04:05:06 PST @@ -1765,20 +1781,34 @@ MINUTE TO SECOND - 带时区的时间戳 + timestamp with time zone - 无时区的时间戳 + timestamp without time zone - 时间戳类型的有效输入由日期与时间拼接而成,其后可以跟时区,再后可以跟ADBC。(或者,AD/BC可以出现在时区之前,但这不是首选顺序。)因此: + + 时间戳类型的有效输入由一个日期和时间的串接组成,后面跟着一个可选 + 时区,以及一个可选的 ADBC + (另外,AD/BC 也可以出现在 + 时区前面,但这种顺序并不推荐)。因此: + + 1999-01-08 04:05:06 -以及: + + 和: + 1999-01-08 04:05:06 -8:00 -都是有效值,遵循ISO8601 标准。此外,也支持下面这种常用格式: + + + 都是遵循 ISO 8601 标准的有效值。另外,广泛使用 + 的下列格式: + January 8 04:05:06 1999 PST - + + 也被支持。 + 按照SQL标准,timestamp without time zonetimestamp with time zone字面量的区别在于,时间后是否有+-符号及其后的时区偏移。因此,按照该标准,TIMESTAMP '2004-10-19 10:23:54'timestamp without time zone,而TIMESTAMP '2004-10-19 10:23:54+02'timestamp with time zonePostgreSQL在确定字符串字面量的类型之前,从不检查其内容,因此会把上述两者都视为timestamp without time zone。为确保字面量被视为timestamp with time zone,应为它显式指定正确类型:TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'若字面量已经被确定为timestamp without time zonePostgreSQL会静默忽略任何时区标记。也就是说,所得值来自输入值中的日期/时间字段,不会根据时区调整。 @@ -1808,12 +1838,12 @@ January 8 04:05:06 1999 PST time - constants + 常量 date - constants + 常量 @@ -1914,13 +1944,13 @@ January 8 04:05:06 1999 PST date 输出格式 - formatting + 格式化 time 输出格式 - formatting + 格式化 @@ -1950,7 +1980,7 @@ January 8 04:05:06 1999 PST ISO - ISO 8601, SQL标准 + ISO 8601,SQL 标准 1997-12-17 07:37:16-08 @@ -1981,7 +2011,7 @@ January 8 04:05:06 1999 PST - SQL和POSTGRES风格中,如果DMY域顺序被指定,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。 + SQL和POSTGRES风格中,如果指定了 DMY 字段顺序,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。
@@ -2044,7 +2074,7 @@ January 8 04:05:06 1999 PST 时区 - time zone + 时区 @@ -2099,7 +2129,8 @@ January 8 04:05:06 1999 PST - PostgreSQL允许使用三种不同形式指定时区: + PostgreSQL 允许使用三种不同形式来指定时区: + 完整时区名称,例如 America/New_York。 @@ -2128,11 +2159,20 @@ January 8 04:05:06 1999 PST 除了时区名称和缩写之外, PostgreSQL 还接受 POSIX 风格的 时区说明,见 。 - 这个选项通常不如使用具名时区更合适,但如果没有可用的 IANA - 时区条目,它可能就是必需的。 + 这个选项通常不如使用具名时区更合适,但如果没有合适的 IANA 时区条目可用,它可能就是必需的。 - 简而言之,缩写和完整名称的区别是:缩写表示特定的 UTC 偏移,而许多完整名称隐含本地夏令时规则,因此有两个可能的 UTC 偏移。例如,2014-06-04 12:00 America/New_York表示纽约当地时间的中午,在该日期使用的是东部夏令时间(UTC-4)。因此,2014-06-04 12:00 EDT指定相同的时刻。但是,2014-06-04 12:00 EST指定东部标准时间(UTC-5)的中午,而不管该日期是否名义上实行夏令时。 + + + 简而言之,这就是缩写和全名的区别:缩写表示某个特定的 UTC 偏移, + 而很多完整名称隐含了当地的夏令时规则,因此可能对应两个不同的 + UTC 偏移。例如, + 2014-06-04 12:00 America/New_York 表示纽约 + 当地时间中午;在这个具体日期,它属于东部夏令时(UTC-4),所以 + 2014-06-04 12:00 EDT 指定的是同一个时刻。 + 但 2014-06-04 12:00 EST 指定的是东部标准时 + 中午(UTC-5),无论当天名义上是否正在实行夏令时。 + 更复杂的是,一些司法辖区在不同时间使用同一时区缩写来表示不同的 @@ -2143,12 +2183,17 @@ January 8 04:05:06 1999 PST 当地民用时间。 - 在所有情况下,时区名称和缩写的识别都不区分大小写。(这与 8.2 之前的PostgreSQL版本不同;那些版本在某些上下文中区分大小写,在另一些上下文中则不区分。) + + 无论哪种形式,时区名称及其缩写都不区分大小写。(这是对 + PostgreSQL 8.2 之前版本的一项改动; + 在那些版本中,时区名在某些环境下区分大小写,而在另一些环境下则 + 不区分。) + 时区名称和缩写并不是硬编码在服务器中的;它们来自安装目录下 .../share/timezone/ 和 - .../share/timezonesets/ 子目录中的数据 + .../share/timezonesets/ 子目录中的配置文件 (见 )。 @@ -2186,13 +2231,13 @@ January 8 04:05:06 1999 PST - interval值可以使用下列语法书写: + interval值可以使用下列详细语法书写: @ quantity unit quantity unit... direction - 其中quantity是一个数字(很可能是有符号的); + 其中quantity是一个数字(可以带有符号); unitmicrosecondmillisecondsecondminutehourday、 @@ -2226,7 +2271,7 @@ January 8 04:05:06 1999 PST P quantity unit quantity unit ... T quantity unit ... 字符串必须以 P 开头,并且可以包含一个 - T 来引出一天中时间单位。可用的单位缩写见 + T 来引出一天中的时间单位。可用的单位缩写见 。单位可以省略, 也可以按任意顺序出现,但小于一天的单位必须出现在 T 之后。特别是,M 的含义 @@ -2265,7 +2310,7 @@ P quantity unit M - 分钟 (在时间部分中) + 分钟(在时间部分中) S @@ -2340,7 +2385,7 @@ P years-months- P1Y2M3DT4H5M6S - 带标志符的ISO 8601 格式:含义同上 + ISO 8601 带标志符的格式:含义同上 P0001-02-03T04:05:06 @@ -2370,7 +2415,7 @@ SELECT EXTRACT(days from '80 hours'::interval); interval 输出格式 - formatting + 格式化 @@ -2407,7 +2452,7 @@ SELECT EXTRACT(days from '80 hours'::interval); iso_8601 风格的输出符合 ISO 8601 标准 - 4.4.3.2 节描述的带标志符格式。 + 4.4.3.2 节描述的带标志符的格式
@@ -2458,7 +2503,7 @@ SELECT EXTRACT(days from '80 hours'::interval); 布尔类型 - Boolean + 布尔 数据类型 @@ -2569,15 +2614,15 @@ SELECT * FROM test1 WHERE a; 数据类型 - enumerated (enum) + 枚举(enum) - enumerated types + 枚举类型 - 枚举(enum)类型是由一个静态、值的有序集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的日期,或者一个数据的状态值集合。 + 枚举(enum)类型是由一个静态的有序值集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的各天,或者一个数据的状态值集合。 @@ -2686,7 +2731,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 实现细节 - 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空格也是有意义的。 + 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空白也是有意义的。 @@ -2698,7 +2743,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 从内部枚举值到文本标签的翻译被保存在系统目录pg_enum中。可以直接查询该目录。 + 从内部枚举值到文本标签的转换关系被保存在系统目录pg_enum中。直接查询该目录可能会有所帮助。 @@ -2769,7 +2814,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays circle24字节 - <(x,y),r>(中心点和半径) + <(x,y),r>(圆心和半径) @@ -2777,7 +2822,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 我们提供了丰富的函数和操作符来进行各种几何操作,例如缩放、平移、 - 旋转以及计算相交等,详见 。 + 旋转以及求交等,详见 @@ -2788,7 +2833,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 点是几何类型的基本二维构造块。用下面的语法描述point类型的值: + 点是几何类型的基本二维构造块。用下面任一种语法描述point类型的值: ( x , y ) @@ -2804,14 +2849,14 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线 + 直线 line - 线由线性方程Ax + By + C = 0 + 直线由线性方程Ax + By + C = 0 表示,其中AB不能同时为零。类型line 的值采用以下形式输入和输出: @@ -2831,7 +2876,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays (x1,y1)(x2,y2) - 是线上不同的两点。 + 是直线上不同的两点。 @@ -2847,7 +2892,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线段用一对线段的端点来表示。lseg类型的值用下面的语法声明: + 线段用一对线段的端点来表示。lseg类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ( x2 , y2 ) ] @@ -2871,15 +2916,15 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 方框 - box (data type) + box(数据类型) - rectangle + 矩形 - 方框用其对角的点对表示。box类型的值使用下面的语法指定: + 方框用其对角的点对表示。box类型的值使用下面任一种语法指定: ( ( x1 , y1 ) , ( x2 , y2 ) ) @@ -2898,7 +2943,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 在输入时可以提供任意两个对角,但是值将根据需要被按顺序记录为右上角和左下角。 + 在输入时可以提供任意两个对角,但是值将根据需要被重新排列,并依次存储为右上角和左下角。 @@ -2906,7 +2951,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 路径 - path (data type) + path(数据类型) @@ -2914,7 +2959,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - path类型的值用下面的语法声明: + path类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ... , ( xn , yn ) ] @@ -2924,11 +2969,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays x1 , y1 , ... , xn , yn - 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被忽略时,路径将被假定为封闭。 + 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被省略时,路径将被假定为封闭。 - 路径的输出使用第一种或第二种语法。 + 路径的输出视情况使用第一种或第二种语法。 @@ -2939,10 +2984,10 @@ SELECT person.name, holidays.num_weeks FROM person, holidays polygon - 多边形由点的列表(多边形的顶点)表示。多边形与闭合路径非常相似,但存储方式不同,并且有自己的支持例程。 + 多边形由点的列表(多边形的顶点)表示。多边形与封闭路径非常相似,但存储方式不同,并且有自己的支持例程。 - polygon类型的值用下列语法声明: + polygon类型的值用下列任一种语法指定: ( ( x1 , y1 ) , ... , ( xn , yn ) ) @@ -2967,7 +3012,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 圆由一个圆心和一个半径代表。circle类型的值用下面的语法指定: + 圆由一个圆心和一个半径代表。circle类型的值用下面任一种语法指定: < ( x , y ) , r > @@ -2990,7 +3035,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 网络地址类型 - network + 网络 数据类型 @@ -3044,8 +3089,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 在对 inetcidr 数据类型排序时,IPv4 - 地址总是排在 IPv6 地址之前,包括那些封装在 IPv6 地址中或映射到 - IPv6 地址中的 IPv4 地址,例如 ::10.2.3.4 或 + 地址总是排在 IPv6 地址之前,即使后者是封装或映射 IPv4 地址所得的 IPv6 地址,例如 ::10.2.3.4 或 ::ffff:10.4.3.2。 @@ -3091,7 +3135,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays cidr 类型保存 IPv4 或 IPv6 网络说明。输入和输出格式 遵循无类别域间路由(CIDR)约定。指定网络的格式为 address/y,其中 - address 是网络最低地址的 + address 是网络的 IPv4 或 IPv6 表示,而 y 是网络掩码中的位数。 如果省略 y,则会按照旧式 @@ -3201,7 +3245,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - <type>inet</type> vs. <type>cidr</type> + <type>inet</type> 与 <type>cidr</type> inetcidr 两种数据类型的本质区别在于: @@ -3227,12 +3271,12 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - MAC地址 + MAC 地址 macaddr - macaddr类型存储 MAC 地址,也就是以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: + macaddr类型存储 MAC 地址,例如以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: '08:00:2b:01:02:03' @@ -3266,15 +3310,15 @@ SELECT person.name, holidays.num_weeks FROM person, holidays <type>macaddr8</type> - macaddr8 (data type) + macaddr8(数据类型) - MAC地址(EUI-64格式) + MAC 地址(EUI-64 格式) macaddr - macaddr8类型以 EUI-64 格式存储 MAC 地址,例如常见的以太网卡硬件地址(尽管 MAC 地址也有其他用途)。该类型既接受 6 字节也接受 8 字节的 MAC 地址,并以 8 字节格式存储。给定的 6 字节格式 MAC 地址会以 8 字节格式存储,其中第 4 和第 5 字节分别设为 FF 和 FE。注意,IPv6 使用修改后的 EUI-64 格式,从 EUI-48 转换后应将第 7 位设为 1。提供的函数macaddr8_set7bit可完成这一更改。一般来说,接受由成对十六进制数字(在字节边界上)构成的输入,各对之间可以统一使用':''-''.'中的一种分隔。十六进制数字的数量必须为 16 个(8 字节)或 12 个(6 字节)。开头和结尾的空白会被忽略。以下是可以接受的输入格式示例: + macaddr8类型以 EUI-64 格式存储 MAC 地址,例如常见的以太网卡硬件地址(尽管 MAC 地址也有其他用途)。该类型既接受 6 字节也接受 8 字节的 MAC 地址,并以 8 字节格式存储。给定的 6 字节格式 MAC 地址会以 8 字节格式存储,其中第 4 和第 5 字节分别设为 FF 和 FE。注意,IPv6 使用修改后的 EUI-64 格式,从 EUI-48 转换后应将第 7 位设为 1。提供的函数macaddr8_set7bit可完成这一更改。一般来说,接受由成对十六进制数字(在字节边界上)构成的输入,各对之间可以统一使用':''-''.'中的一种分隔。十六进制数字的数量必须为 16 个(8 字节)或 12 个(6 字节)。开头和结尾的空白会被忽略。以下是可以接受的输入格式示例: '08:00:2b:01:02:03:04:05' '08-00-2b-01-02-03-04-05' '08002b:0102030405' @@ -3307,7 +3351,13 @@ SELECT macaddr8_set7bit('08:00:2b:01:02:03'); 数据类型 - 位串是由 1 和 0 组成的字符串,可用于存储或可视化位掩码。SQL 有两种位类型:bit(n)bit varying(n),其中n是正整数。 + + 位串是由 1 和 0 组成的字符串。它们可用于存储或展示位掩码。 + SQL 中有两种位类型: + bit(n) 和 + bit varying(n),其中 + n 是正整数。 + bit 类型的数据长度必须与 @@ -3357,31 +3407,31 @@ SELECT * FROM test; - 一个 bit 串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 + 一个位串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 开销,具体取决于串的长度。(不过,长值可能会被压缩或移到行外存储, 与 中对字符串的说明相同。) - 文本搜索类型 + 文本检索类型 - 全文搜索 + 全文检索 数据类型 - 文本搜索 + 文本检索 数据类型 - PostgreSQL 提供了两种专为支持全文搜索而 - 设计的数据类型。所谓全文搜索,是指在一组自然语言 + PostgreSQL 提供了两种专为支持全文检索而 + 设计的数据类型。所谓全文检索,是指在一组自然语言 文档中查找最匹配某个 查询的文档。tsvector 类型以 - 适合文本搜索的优化形式表示文档,tsquery 类型则表示 + 适合文本检索的优化形式表示文档,tsquery 类型则表示 文本查询。关于这一功能的详细解释见 ; 相关函数和操作符的概览见 @@ -3393,40 +3443,74 @@ SELECT * FROM test; tsvector(数据类型) - 一个tsvector值是由互不相同的词位组成的有序列表。词位是经过规范化以合并同一个词的不同变体的词(详情见)。排序和去重会在输入时自动完成,如本例所示: + + tsvector 值是一个排好序且互不重复的 + 词位(lexeme)列表,这些词已经过 + 正规化,以便把同一单词的不同变体合并起来 + (详见 )。排序和去重会在输入时自动 + 完成,如下例所示: + + SELECT 'a fat cat sat on a mat and ate a fat rat'::tsvector; tsvector ---------------------------------------------------- 'a' 'and' 'ate' 'cat' 'fat' 'mat' 'on' 'rat' 'sat' -要表示包含空白或标点符号的词位,请用引号括住它们: + + + 若要表示包含空白或标点的词位,请用引号将它们括起来: + + SELECT $$the lexeme ' ' contains spaces$$::tsvector; tsvector ------------------------------------------- ' ' 'contains' 'lexeme' 'spaces' 'the' -(本例和下一个示例使用美元符号引用的字符串字面量,以免在字面量中双写引号造成混淆。)内嵌的引号和反斜线必须双写: + + + (本例及下例使用美元引用的字符串常量,以避免在字符串内部必须 + 双写引号所造成的混淆。)嵌入的引号和反斜线必须双写: + + SELECT $$the lexeme 'Joe''s' contains a quote$$::tsvector; tsvector ------------------------------------------------ 'Joe''s' 'a' 'contains' 'lexeme' 'quote' 'the' -还可以给词位附加整数形式的位置,如下所示: + + + 还可以为词位附加整数形式的 位置: + + SELECT 'a:1 fat:2 cat:3 sat:4 on:5 a:6 mat:7 and:8 ate:9 a:10 fat:11 rat:12'::tsvector; tsvector ------------------------------------------------------------------------------- 'a':1,6,10 'and':8 'ate':9 'cat':3 'fat':2,11 'mat':7 'on':5 'rat':12 'sat':4 -位置通常表示原词在文档中的位置。位置信息可用于邻近度排序。位置值的范围为 1 到 16383;更大的数值会被静默设为 16383。同一词位的重复位置会被丢弃。 + - 具有位置的词位还可以标记一个权重,它可以是A, - BCD。 - D是默认值,因此不会在输出中显示: + 一个位置通常表示源词在文档中的位置。位置信息可用于 + 邻近度排序。位置值可以位于 1 到 16383 + 之间;更大的数字会被静默设为 16383。同一词位的重复位置会被丢弃。 + + + + 带有位置的词位还可以进一步附加一个 + 权重标签,其值可以是 + ABC + 或 DD 是默认值,因此在 + 输出中不会显示: + + SELECT 'a:1A fat:2B,4C cat:5D'::tsvector; tsvector ---------------------------- 'a':1A 'cat':5 'fat':2B,4C -权重通常用来反映文档结构,例如为标题中的词和正文中的词采用不同标记。文本搜索排名函数可以为不同的权重标记分配不同优先级。 + + + 权重通常用于反映文档结构,例如把标题中的词和正文中的词区分开来。 + 文本检索排序函数可以为不同的权重标记分配不同优先级。 + 必须认识到,tsvector 类型本身并不会执行任何词语 - 规范化;它假定输入的词已经按照应用需求完成规范化。例如: + 正规化;它假定输入的词已经按照应用需求完成正规化。例如: SELECT 'The Fat Rats'::tsvector; @@ -3435,9 +3519,9 @@ SELECT 'The Fat Rats'::tsvector; 'Fat' 'Rats' 'The' - 对于大多数英文全文搜索应用来说,上述词会被视为尚未规范化,但 + 对于大多数英文全文检索应用来说,上述词会被视为尚未正规化,但 tsvector 并不在意。原始文档文本通常应先经过 - to_tsvector,以按搜索需要对词语进行规范化: + to_tsvector,以按检索需要对词语进行正规化: SELECT to_tsvector('english', 'The Fat Rats'); @@ -3526,9 +3610,9 @@ SELECT 'super:*'::tsquery; 引号的使用规则与前面介绍 tsvector 时相同;同样, - 与 tsvector 一样,任何需要的词语规范化都必须在 + 与 tsvector 一样,任何需要的词语正规化都必须在 转换为 tsquery 类型之前完成。to_tsquery - 函数很适合用来实现这种规范化: + 函数很适合用来实现这种正规化: SELECT to_tsquery('Fat:ab & Cats'); @@ -3554,8 +3638,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); ---------------+------------ 'postgradu':1 | 'postgr':* - 因而它能够匹配其带前缀的后继形式 - postgraduate。 + 因而它能够匹配postgraduate 词干化后的形式。 @@ -3573,7 +3656,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); uuid 数据类型用于存储由 RFC 4122、 ISO/IEC 9834-8:2005 及相关标准定义的通用唯一标识符(UUID)。 - (有些系统把这种数据类型称为全局唯一标识符,或 GUID, + (有些系统把这种数据类型称为全局唯一标识符,或 GUID GUID。)这种标识符是一个 128 位的量,由某种算法生成,该算法被设计为使同一算法在已知宇宙中 被其他人生成出相同标识符的概率极低。因此,对于分布式系统而言, @@ -3590,7 +3673,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11 PostgreSQL 也接受其他输入形式:可以使用 - 大写字母、用花括号包围标准格式、忽略部分或全部连字符,或者在任意 + 大写字母、用花括号包围标准格式、省略部分或全部连字符,或者在任意 4 位分组后额外加上连字符。例如: A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11 @@ -3638,16 +3721,25 @@ a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11 创建XML值 - 要生成xml类型的值,可以对字符数据使用函数xmlparsexmlparse + + 要从字符数据生成 xml 类型的值,可以使用函数 + xmlparsexmlparse XMLPARSE ( { DOCUMENT | CONTENT } value) -例如: + 示例: +Manual...') XMLPARSE (CONTENT 'abcbarfoo') -]]>按照 SQL 标准,这是将字符串转换为 XML 值的唯一方式,不过也可以使用以下 PostgreSQL 特有语法: + 按照 SQL 标准,这是把字符串转换为 XML 值的 + 唯一方法;但 PostgreSQL 特有的下列语法: +bar' 'bar'::xml -]]> +]]> + 也可以使用。 + 即使输入值指定了文档类型声明(DTD),xml 类型也不会 @@ -3656,18 +3748,25 @@ xml 'bar' 来执行验证。 - 相反的操作是把xml值转换为字符串,这使用函数xmlserializexmlserialize + + 反向操作,也就是从 xml 生成字符串值,则使用函数 + xmlserializexmlserialize XMLSERIALIZE ( { DOCUMENT | CONTENT } value AS type ) - type可以是charactercharacter varyingtext(或这些类型之一的别名)。同样,按照 SQL 标准,这是在xml类型和字符类型之间转换的唯一方式,不过 PostgreSQL 也允许直接对值进行类型转换。 + type 可以是 + charactercharacter varying 或 + text(或它们的别名)。同样,根据 SQL 标准,这是在 + xml 与字符类型之间进行转换的唯一方式,但 + PostgreSQL 也允许你直接进行类型转换。 + 当字符串值在不经过 XMLPARSEXMLSERIALIZE 的情况下与 xml 类型互相转换时, 选择 DOCUMENT 还是 CONTENT - 由会话配置参数 XML option - XML option 决定,可以使用 + 由会话配置参数 XML 选项 + XML 选项 决定,可以使用 标准命令设置: SET XML OPTION { DOCUMENT | CONTENT }; @@ -3731,7 +3830,7 @@ SET xmloption TO { DOCUMENT | CONTENT }; xml 数据类型有些特殊,因为它不提供任何比较操作符。 这是因为对 XML 数据并不存在良定义且通用的比较算法。其结果是, - 你无法通过把某个 xml 值与搜索值比较来检索行。 + 你无法通过把某个 xml 列与搜索值比较来检索行。 因此,XML 值通常应伴随一个独立的键字段,例如 ID。另一种比较 XML 值的办法,是先把它们转换成字符串;但请注意,字符串比较对 XML 的比较需求通常帮助不大。 @@ -3739,14 +3838,14 @@ SET xmloption TO { DOCUMENT | CONTENT }; 由于 xml 数据类型没有可用的比较操作符,因此无法直接 - 在这种类型上创建索引。如果需要在 XML 中快速搜索,可行方案包括: + 在这种类型的列上创建索引。如果需要在 XML 中快速搜索,可行方案包括: 将表达式转换为字符串类型后为其建立索引,或者为某个 XPath 表达式 建立索引。当然,实际查询也必须相应调整为使用该被索引的表达式。 - PostgreSQL 的文本搜索功能也可用于加速 - XML 数据的全文搜索。不过,目前 PostgreSQL 发行版中仍缺少所需的 + PostgreSQL 的文本检索功能也可用于加速 + XML 数据的全文检索。不过,目前 PostgreSQL 发行版中仍缺少所需的 预处理支持。 @@ -3883,7 +3982,7 @@ SELECT * FROM pg_attribute regprocedure pg_proc - 函数与参数类型 + 带参数类型的函数 sum(int4) @@ -3932,21 +4031,21 @@ SELECT * FROM pg_attribute regconfig pg_ts_config - 文本搜索配置 + 文本检索配置 english regdictionary pg_ts_dict - 文本搜索字典 + 文本检索词典 simple
- 对于按名字空间分组的对象,所有 OID 别名类型都接受模式限定名称;如果不加限定就无法在当前搜索路径中找到对象,输出时也会显示模式限定名称。regprocregoper别名类型只接受唯一的(未重载的)输入名称,因此用途有限;对于大多数用途,regprocedureregoperator更合适。对于regoperator,通过将未使用的操作数写为NONE来标识一元操作符。 + 对于按命名空间分组的对象,所有 OID 别名类型都接受模式限定名称;如果不加限定就无法在当前搜索路径中找到对象,输出时也会显示模式限定名称。regprocregoper别名类型只接受唯一的(未重载的)输入名称,因此用途有限;对于大多数用途,regprocedureregoperator更合适。对于regoperator,通过将未使用的操作数写为NONE来标识一元操作符。 大多数 OID 别名类型还有一个附加特性,就是会创建依赖关系。如果 @@ -3954,9 +4053,8 @@ SELECT * FROM pg_attribute 它就会对被引用对象建立依赖。例如,如果某列的默认表达式是 nextval('my_seq'::regclass)PostgreSQL 就会知道该默认表达式依赖于 - 序列 my_seq,因此系统在删除该序列之前,必须先 - 移除该默认表达式。 - (regrole 是这一特性的例外:该类型的常量不允许出现在 + 序列 my_seq,因此系统不允许在尚未移除该默认表达式时删除序列。 + (regrole 是这一特性的唯一例外:该类型的常量不允许出现在 存储表达式中。) @@ -4118,7 +4216,7 @@ SELECT * FROM pg_attribute anyarray - 表示一个函数可以接受任意数组数据类型(参见 + 表示一个函数可以接受任意数组数据类型(参见)。 @@ -4173,12 +4271,12 @@ SELECT * FROM pg_attribute trigger - 触发器函数被声明为返回trigger. + 表示触发器函数被声明为返回 trigger event_trigger - 事件触发器函数被声明为返回event_trigger. + 表示事件触发器函数被声明为返回 event_trigger @@ -4193,11 +4291,11 @@ SELECT * FROM pg_attribute unknown - 标识一种尚未解析出的类型,例如未修饰的字符串字面值。 + 标识一种尚未解析出的类型,例如未修饰的字符串字面值的类型。 - opaque + opaque 一个已废弃的类型名称,以前用于上述多种用途。 diff --git a/zh/10/dict-int.sgml b/zh/10/dict-int.sgml index df327be2..b323402d 100644 --- a/zh/10/dict-int.sgml +++ b/zh/10/dict-int.sgml @@ -1,16 +1,16 @@ - dict_int — 用于整数的示例全文搜索词典 + dict_int — 用于整数的示例全文检索词典 dict_int - dict_int是一个全文搜索附加词典模板的示例。 + dict_int是一个全文检索附加词典模板的示例。 引入这个示例词典是为了控制整数(有符号和无符号)的索引, - 使这类数字能够被索引,同时又避免唯一词的数量过度增长, + 使这类数字能够被索引,同时又避免不同词的数量过度增长, 因为那会严重影响搜索性能。 @@ -42,7 +42,7 @@ 用法 - 安装dict_int扩展后,会创建一个文本搜索模板 + 安装dict_int扩展后,会创建一个文本检索模板 intdict_template以及一个基于该模板、使用默认参数的词典 intdict。你可以修改这些参数,例如: @@ -65,7 +65,7 @@ mydb# select ts_lexize('intdict', '12345678');
但在实际使用中,通常需要像所述那样, - 将它包含到某个文本搜索配置中。可能类似如下: + 将它包含到某个文本检索配置中。可能类似如下: ALTER TEXT SEARCH CONFIGURATION english diff --git a/zh/10/func.sgml b/zh/10/func.sgml index 3d614011..df33bdd4 100644 --- a/zh/10/func.sgml +++ b/zh/10/func.sgml @@ -6851,7 +6851,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 文本搜索函数和操作符 + 文本检索函数和操作符 全文检索 @@ -6859,7 +6859,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 文本搜索 + 文本检索 函数和操作符 @@ -6867,11 +6867,11 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple 以及 - 总结了为全文检索提供的函数和操作符。PostgreSQL的文本搜索功能的详细解释可参考。 + 总结了为全文检索提供的函数和操作符。PostgreSQL的文本检索功能的详细解释可参考
- 文本搜索操作符 + 文本检索操作符 @@ -6954,10 +6954,10 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple tsquery 包含操作符只考虑两个查询中列出的词位,忽略组合操作符。 - 除了表中列出的操作符,tsvectortsquery 类型还定义了普通的 B-树比较操作符(=< 等)。这些操作符对文本搜索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。 + 除了表中列出的操作符,tsvectortsquery 类型还定义了普通的 B-树比较操作符(=< 等)。这些操作符对文本检索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。
- 文本搜索函数 + 文本检索函数 @@ -6979,7 +6979,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple get_current_ts_config get_current_ts_config() regconfig - 获取默认的文本搜索配置 + 获取默认的文本检索配置 get_current_ts_config() english @@ -7174,17 +7174,17 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 所有接受一个可选的regconfig参数的文本搜索函数在省略该参数时,会使用由指定的配置。 + 所有接受一个可选的regconfig参数的文本检索函数在省略该参数时,会使用由指定的配置。 - 中的函数被单独列出,因为它们通常不被用于日常的文本搜索操作。 - 它们有助于开发和调试新的文本搜索配置。 + 中的函数被单独列出,因为它们通常不被用于日常的文本检索操作。 + 它们有助于开发和调试新的文本检索配置。
- 文本搜索调试函数 + 文本检索调试函数 diff --git a/zh/10/gist.sgml b/zh/10/gist.sgml index 23317615..4965f1ea 100644 --- a/zh/10/gist.sgml +++ b/zh/10/gist.sgml @@ -670,7 +670,7 @@ my_fetch(PG_FUNCTION_ARGS) 示例 - PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本搜索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: + PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本检索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: diff --git a/zh/10/json.sgml b/zh/10/json.sgml index f2a4b761..18dc68a9 100644 --- a/zh/10/json.sgml +++ b/zh/10/json.sgml @@ -23,7 +23,7 @@ 有两种 JSON 数据类型:jsonjsonb。它们接受的输入值集合几乎相同。实际使用中的主要区别是效率。json 数据类型保存输入文本的精确副本,处理函数每次执行时都必须重新解析;而 jsonb 数据以分解后的二进制格式存储,额外的转换开销使输入稍慢,但无需重新解析,因此处理速度明显更快。jsonb 还支持索引,这可能带来显著优势。 - 由于 json 类型存储的是输入文本的精确副本,因此它会保留标记 + 由于 json 类型存储的是输入文本的精确副本,因此它会保留词元 之间在语义上无关紧要的空白,以及 JSON 对象内部键的顺序。此外,如果值中 的某个 JSON 对象包含同一个键多次,所有键/值对都会被保留下来(处理函数会 将最后一个值视为生效值)。相比之下,jsonb 不保留空白,不保留 @@ -46,7 +46,7 @@ 当把文本形式的 JSON 输入转换为 jsonb 时, - RFC 7159 描述的基本类型会有效映射到原生的 + RFC 7159 描述的基本类型实际上会映射到原生的 PostgreSQL 类型上,如 所示。因此,什么样的数据构成 有效的 jsonb 会有一些额外但较小的限制,这些限制不适用于 @@ -94,7 +94,7 @@ null - (无) + (无) SQL NULL 是不同的概念 @@ -109,18 +109,18 @@ 以下都是有效的 json(或 jsonb)表达式: --- Simple scalar/primitive value --- Primitive values can be numbers, quoted strings, true, false, or null +-- 简单的标量/基本值 +-- 基本值可以是数字、加引号的字符串、true、false 或 null SELECT '5'::json; --- Array of zero or more elements (elements need not be of same type) +-- 包含零个或多个元素的数组(元素不必是同一类型) SELECT '[1, 2, "foo", null]'::json; --- Object containing pairs of keys and values --- Note that object keys must always be quoted strings +-- 包含键值对的对象 +-- 注意,对象的键必须始终是加引号的字符串 SELECT '{"bar": "baz", "balance": 7.77, "active": false}'::json; --- Arrays and objects can be nested arbitrarily +-- 数组和对象可以任意嵌套 SELECT '{"foo": [true, "bar"], "tags": {"a": 1, "b": null}}'::json; @@ -171,8 +171,7 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 当 JSON 数据存储在表中时,它与任何其他数据类型一样,都要面对相同的并发控 制考量。虽然存储大型文档是可行的,但要记住,任何更新都会在整行上获取一个 行级锁。应考虑将 JSON 文档限制在可管理的大小,以减少更新事务之间的锁争用。 - 理想情况下,每个 JSON 文档都应表示一个原子数据项,按照业务规则,它不应被 - 合理地进一步拆分为更小且可独立修改的数据项。 + 理想情况下,每个 JSON 文档都应表示一个原子数据项,根据业务规则,无法再合理地将它细分为更小且可独立修改的数据项。 @@ -180,11 +179,11 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; <type>jsonb</type> 包含与存在 jsonb - containment + 包含 jsonb - existence + 存在 测试 包含jsonb 的一项重要能力。 @@ -193,33 +192,32 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 示例都返回真: --- Simple scalar/primitive values contain only the identical value: +-- 简单的标量/基本值只包含相同的值: SELECT '"foo"'::jsonb @> '"foo"'::jsonb; --- The array on the right side is contained within the one on the left: +-- 左侧数组包含右侧数组: SELECT '[1, 2, 3]'::jsonb @> '[1, 3]'::jsonb; --- Order of array elements is not significant, so this is also true: +-- 数组元素的顺序无关紧要,因此下面的结果也为真: SELECT '[1, 2, 3]'::jsonb @> '[3, 1]'::jsonb; --- Duplicate array elements don't matter either: +-- 重复的数组元素也无关紧要: SELECT '[1, 2, 3]'::jsonb @> '[1, 2, 2]'::jsonb; --- The object with a single pair on the right side is contained --- within the object on the left side: +-- 左侧对象包含右侧只有一个键值对的对象: SELECT '{"product": "PostgreSQL", "version": 9.4, "jsonb": true}'::jsonb @> '{"version": 9.4}'::jsonb; --- The array on the right side is not considered contained within the +-- The array on the right side is not considered contained within the -- array on the left, even though a similar array is nested within it: -SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- yields false +SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- 结果为假 --- But with a layer of nesting, it is contained: +-- 但增加一层嵌套后,就构成了包含关系: SELECT '[1, 2, [1, 3]]'::jsonb @> '[[1, 3]]'::jsonb; --- Similarly, containment is not reported here: -SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- yields false +-- 同样,下面也不构成包含关系: +SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- 结果为假 --- A top-level key and an empty object is contained: +-- 包含由顶层键和空对象构成的对象: SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; @@ -234,11 +232,11 @@ SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; 对于结构必须匹配这一一般原则,有一个特殊例外:数组可以包含一个基本值: --- This array contains the primitive string value: +-- 这个数组包含该基本字符串值: SELECT '["foo", "bar"]'::jsonb @> '"bar"'::jsonb; --- This exception is not reciprocal -- non-containment is reported here: -SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false +-- 这个例外并不对称——下面的结果表示不包含: +SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- 结果为假 @@ -248,19 +246,19 @@ SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false 外,下面这些示例都返回真: --- String exists as array element: +-- 字符串作为数组元素存在: SELECT '["foo", "bar", "baz"]'::jsonb ? 'bar'; --- String exists as object key: +-- 字符串作为对象键存在: SELECT '{"foo": "bar"}'::jsonb ? 'foo'; --- Object values are not considered: -SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- yields false +-- 不考虑对象的值: +SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- 结果为假 --- As with containment, existence must match at the top level: -SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- yields false +-- 与包含关系一样,存在性必须在顶层匹配: +SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- 结果为假 --- A string is considered to exist if it matches a primitive JSON string: +-- 如果字符串与一个基本 JSON 字符串匹配,则认为它存在: SELECT '"foo"'::jsonb ? 'foo'; @@ -274,8 +272,7 @@ SELECT '"foo"'::jsonb ? 'foo'; 由于 JSON 包含是嵌套的,因此适当的查询可以跳过对子对象的显式选择。例如, 假设我们有一个 doc 列,其顶层是对象,而且大 多数对象都带有 tags 字段,该字段中包含子对象数组。下面 - 这个查询会找出那些包含同时带有 "term":"paris" 和 - "term":"food" 的子对象的项,同时忽略 + 这个查询会找出同时出现包含 "term":"paris" 的子对象和包含 "term":"food" 的子对象的项,同时忽略 tags 数组之外的任何此类键: SELECT doc->'site_name' FROM websites @@ -305,7 +302,7 @@ SELECT doc->'site_name' FROM websites <type>jsonb</type> 索引 jsonb - indexes on + 索引 @@ -313,7 +310,7 @@ SELECT doc->'site_name' FROM websites 或键/值对。提供了两种 GIN 操作符类,它们在性能和灵活性 之间提供不同的权衡。 - 对于jsonb,默认 GIN 操作符类支持使用顶层键存在操作符??&?|以及路径/值存在操作符@>的查询。(这些操作符所实现语义的详情,参见。)使用此操作符类创建索引的示例如下: + 对于jsonb,默认 GIN 操作符类支持使用顶层键存在操作符??&?|以及路径/值存在操作符@>的查询。(这些操作符所实现语义的详情,参见。)使用此操作符类创建索引的示例如下: CREATE INDEX idxgin ON api USING GIN (jdoc); 非默认的 GIN 操作符类jsonb_path_ops仅支持为@>操作符建立索引。使用此操作符类创建索引的示例如下: CREATE INDEX idxginp ON api USING GIN (jdoc jsonb_path_ops); @@ -344,14 +341,14 @@ CREATE INDEX idxginp ON api USING GIN (jdoc jsonb_path_ops); 名为 jdocjsonb 列里。 如果在该列上创建了 GIN 索引,那么下面这样的查询就可以利用这个索引: --- Find documents in which the key "company" has value "Magnafone" +-- 查找键 "company" 的值为 "Magnafone" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"company": "Magnafone"}'; 但是,类似下面这样的查询就无法使用该索引,因为虽然操作符 ? 可索引,但它并未直接应用到被索引的列 jdoc 上: --- Find documents in which the key "tags" contains key or array element "qui" +-- 查找键 "tags" 包含键或数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc -> 'tags' ? 'qui'; 不过,只要适当地使用表达式索引,上述查询也可以利用索引。如果经常查询 @@ -368,7 +365,7 @@ CREATE INDEX idxgintags ON api USING GIN ((jdoc -> 'tags')); 另一种查询方法是利用包含,例如: --- Find documents in which the key "tags" contains array element "qui" +-- 查找键 "tags" 包含数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qui"]}'; jdoc 列上的简单 GIN 索引可以支持这个查询。 @@ -391,9 +388,9 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu 基本上,每个 jsonb_path_ops 索引项都是该值连同 - 通向该值的键一起计算出的哈希。例如,要索引 + 通向该值的键一起计算出的 hash。例如,要索引 {"foo": {"bar": "baz"}},会创建一个单独的索引项, - 其哈希值中同时纳入 foobar 和 + 其 hash 值中同时纳入 foobarbaz 这三者。因此,查找这一结构的包含查询会得到一次 非常精确的索引搜索;但完全没有办法据此找出 foo 是否 作为键出现。另一方面,jsonb_ops 索引会分别创建三个 @@ -413,11 +410,11 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu jsonb也支持btreehash索引。通常只有在需要检查完整 JSON 文档是否相等时,这些索引才有用。对于btree排序,jsonb数据的顺序很少值得关注,但为求完整,列出如下: -Object > Array > Boolean > Number > String > Null +对象 > 数组 > 布尔值 > 数字 > 字符串 > Null -Object with n pairs > object with n - 1 pairs +包含 n 个键值对的对象 > 包含 n - 1 个键值对的对象 -Array with n elements > array with n - 1 elements +包含 n 个元素的数组 > 包含 n - 1 个元素的数组 键值对数量相等的对象按以下顺序比较: 键-1, 值-1, 键-2 ... 注意,对象键按其存储顺序比较;尤其是,较短的键存储在较长的键之前,因此可能产生不直观的结果,例如: diff --git a/zh/10/libpq.sgml b/zh/10/libpq.sgml index d9201174..007172ab 100644 --- a/zh/10/libpq.sgml +++ b/zh/10/libpq.sgml @@ -12,19 +12,19 @@ - libpq是应用程序员使用PostgreSQLC接口。libpq是一个库函数的集合,它们允许客户端程序传递查询给PostgreSQL后端服务器并且接收这些查询的结果。 + libpqPostgreSQLC应用程序编程接口。libpq是一组库函数,客户端程序可用它们向PostgreSQL后端服务器发送查询并接收查询结果。 - libpq也是很多其他PostgreSQL应用接口的底层引擎,包括为 C++、Perl、Python、Tcl 和 ECPG编写的接口。如果你使用那些包,某些方面的libpq行为将会对你很重要。特别是,描述了任何使用libpq的应用的用户可见的行为。 + libpq也是其他几个PostgreSQL应用程序接口的底层引擎,包括为 C++、Perl、Python、Tcl 和ECPG编写的接口。因此,对于这些包的用户,libpq行为的某些方面也很重要。特别是,描述了任何使用libpq的应用程序的用户都能观察到的行为。 - 在本章的末尾()包括了一些短程序来展示如何编写使用libpq的应用。在源代码发布的src/test/examples目录中还有一些完整的libpq应用的示例。 + 本章末尾()包含一些简短程序,展示如何编写使用libpq的程序。源代码发行包的src/test/examples目录中还提供了几个完整的libpq应用程序示例。 - 使用libpq的客户端程序必须包括头文件libpq-fe.hlibpq-fe.h并必须与libpq库链接在一起。 + 使用libpq的客户端程序必须包含头文件libpq-fe.hlibpq-fe.h,并且必须与libpq库链接。 @@ -39,7 +39,7 @@ - 在 Unix 上,复制一个拥有打开 libpq 连接的进程可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行代码是安全的。 + 在 Unix 上,对持有已打开 libpq 连接的进程执行 fork 操作可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行程序是安全的。 @@ -66,32 +66,32 @@ PGconn *PQconnectdbParams(const char * const *keywords, - 被传递的数组可以为空,这样就会使用所有默认参数。 - 也可以只包含一个或几个参数设置。他们在长度上必须匹配。 - 对于参数数组的处理将会停止于keywords数组中第一个NULL元素。 - 而且,如果与非-NULL keywords条目相关联的values条目为NULL或者空字符串,则忽略该项并继续处理下一对数组项。 + 传入的数组可以为空,以使用所有默认参数,也可以包含一个或多个参数设置。 + 两个数组的长度必须相同。处理会在 keywords 数组的第一个 NULL 元素处停止。 + 如果某个非 NULLkeywords 元素所对应的 + values 元素为 NULL 或空字符串,则忽略这一项,继续处理下一对数组元素。 - 当expand_dbname为非零时,会检查第一个dbname关键词的值以查看它是否为一个连接字符串。 - 如果是,它被扩展到从字符串中提取的单独的连接参数。 - 该值被认为是一个连接字符串,而不仅是一个数据库名称,如果它包含一个等号(=)或者它以URI模式标志符开头, - (有关连接字符串格式的更多详情可见。) - 只有dbname的第一次出现会按这种方式处理,任何后续dbname值会被当做一个普通数据库名处理。 + 当 expand_dbname 非零时,会检查第一个 dbname 关键词的值是否为 + 连接字符串。如果是,就将其展开为从该字符串中提取的各个连接参数。 + 如果该值包含等号(=),或以 URI 方案标识符开头,就会将其视为连接字符串,而非单纯的数据库名。 + (连接字符串格式的详细说明见。) + 只有第一次出现的 dbname 会按这种方式处理;后续的 dbname 参数都作为普通数据库名处理。 - 通常,参数数组从开头到结尾进行处理。 - 当关键词有重复时,使用最后一个值(不是 NULL 或空)。 - 此规则特别适用于连接字符串中的关键字与一个出现在keywords数组中的关键字冲突的情况。 - 因此,程序员可以决定数组条目是否能被覆盖或用连接字符串获取的值覆盖。 - 出现在扩展的dbname条目之前的数组条目可以被连接字符串的字段所覆盖,反之,这些字段被dbname之后出现的数组条目所覆盖。(但是,再有,只有在那些条目支持非空值时。) + 通常会从头到尾处理参数数组。如果某个关键词重复出现,则采用最后一个非 NULL 且非空的值。 + 此规则也适用于连接字符串中的关键词与 keywords 数组中的关键词冲突的情况。 + 因此,程序员可以决定数组元素是覆盖连接字符串中的值,还是被这些值覆盖。 + 出现在要展开的 dbname 元素之前的数组元素,可以被连接字符串中的字段覆盖; + 而这些字段又会被出现在 dbname 之后的数组元素覆盖(同样,只有这些元素提供非空值时才会覆盖)。 - 在处理完所有数组条目和任何扩展的连接字符串后,所有未设置的连接参数都将使用默认值填充。 - 如果一个未设置参数的相关环境变量(参见 )被设置了,它的值会被使用。 - 如果环境变量未被设置,则使用参数的内置默认值。 + 处理完所有数组元素及展开的连接字符串后,仍未设置的连接参数将填入默认值。 + 如果某个未设置参数对应的环境变量(见)已经设置,就使用该环境变量的值; + 否则使用该参数的内置默认值。 @@ -113,7 +113,7 @@ PGconn *PQconnectdb(const char *conninfo); - 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空格分隔的一个或多个参数设置,还可以包含一个URI。详见。 + 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空白分隔的一个或多个参数设置,还可以包含一个URI。详见 @@ -135,9 +135,13 @@ PGconn *PQsetdbLogin(const char *pghost, - 这是 PQconnectdb 的前身,使用固定的一组参数。除缺失参数始终采用默认值之外,功能相同。对于要使用默认值的任意固定参数,请传入 NULL 或空字符串。 + + 这是 PQconnectdb 的前身,使用固定的一组参数。除缺失参数始终采用默认值之外,功能相同。对于要使用默认值的任意固定参数,请传入 NULL 或空字符串。 + - 如果 dbName 包含 = 符号,或具有有效的连接 URI 前缀,就会将其当作 conninfo 字符串处理,方式与将其传给 PQconnectdb 完全相同,然后按照 PQconnectdbParams 的规则应用其余参数。 + + 如果 dbName 包含 = 符号,或具有有效的连接 URI 前缀,就会将其当作 conninfo 字符串处理,方式与将其传给 PQconnectdb 完全相同,然后按照 PQconnectdbParams 的规则应用其余参数。 + @@ -167,7 +171,7 @@ PGconn *PQsetdb(char *pghost, PQconnectPollPQconnectPoll - nonblocking connection + 非阻塞连接 以非阻塞的方式建立一个到数据库服务器的连接。 @@ -200,7 +204,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 如果你调用PQtrace,确保你追踪的该流对象不会阻塞。 + 如果你调用PQtrace,确保接收追踪输出的流对象不会阻塞。 @@ -213,7 +217,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 要开始无阻塞的连接请求,可调用PQconnectStart或者PQconnectStartParams。如果结果为空,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 + 要开始非阻塞连接请求,可调用PQconnectStart或者PQconnectStartParams。如果结果为空指针,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 @@ -312,11 +316,11 @@ switch(PQstatus(conn)) - 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。否则,PQconnectStart后面跟着PQconnectPoll循环等效于PQconnectdb。 + 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。除此之外,PQconnectStart后面跟着PQconnectPoll循环等效于PQconnectdb - 注意当PQconnectStartPQconnectStartParams返回一个非空的指针时,你必须在用完它之后调用PQfinish来处理那些结构体和任何相关的内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 + 注意当PQconnectStartPQconnectStartParams返回一个非空的指针时,你必须在用完它之后调用PQfinish来释放该结构体及其关联的所有内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 @@ -332,21 +336,21 @@ PQconninfoOption *PQconndefaults(void); typedef struct { char *keyword; /* 该选项的关键词 */ - char *envvar; /* 依赖的环境变量名 */ - char *compiled; /* 依赖的内置默认值 */ + char *envvar; /* 后备环境变量名 */ + char *compiled; /* 编译时设置的后备默认值 */ char *val; /* 选项的当前值,或者 NULL */ - char *label; /* 连接对话框中域的标签 */ - char *dispchar; /* 指示如何在一个连接对话框中显示这个域。值是: + char *label; /* 连接对话框中字段的标签 */ + char *dispchar; /* 指示如何在连接对话框中显示此字段。可取值: "" 显示输入的值 - "*" 密码域 - 隐藏值 + "*" 密码字段 - 隐藏值 "D" 调试选项 - 默认不显示 */ - int dispsize; /* 用于对话框的以字符计的域尺寸 */ + int dispsize; /* 对话框中的字段宽度,以字符计 */ } PQconninfoOption; - 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的PQconnectdb选项和它们的当前缺省值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回该空指针。注意当前缺省值(val域)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 + 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的PQconnectdb选项和它们的当前默认值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回空指针。注意当前默认值(val字段)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 @@ -366,7 +370,9 @@ PQconninfoOption *PQconninfo(PGconn *conn); - 返回一个连接选项数组。可以用它确定所有可能的 PQconnectdb 选项,以及实际用于连接服务器的值。返回值指向一个 PQconninfoOption 结构体数组,该数组以 keyword 指针为空的条目结束。上文针对 PQconndefaults 的所有注意事项,也适用于 PQconninfo 的结果。 + + 返回一个连接选项数组。可以用它确定所有可能的 PQconnectdb 选项,以及实际用于连接服务器的值。返回值指向一个 PQconninfoOption 结构体数组,该数组以 keyword 指针为空的条目结束。上文针对 PQconndefaults 的所有注意事项,也适用于 PQconninfo 的结果。 + @@ -392,7 +398,9 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); - 如果errmsg不是NULL,那么成功时*errmsg会被设置为NULL, 否则设置为被malloc过的错误字符串以说明该问题(也可以将*errmsg设置为NULL并且函数返回NULL,这表示一种内存耗尽的情况)。 + 如果 errmsg 不是 NULL,则成功时将 *errmsg 设为 NULL; + 失败时将其设为由 malloc 分配的、用于说明问题的错误字符串。 + (也可能出现 *errmsg 被设为 NULL,同时函数返回 NULL 的情况;这表示内存不足。) @@ -422,7 +430,7 @@ void PQfinish(PGconn *conn); PQresetPQreset - 重置与服务器的通讯通道。 + 重置与服务器的通信通道。 void PQreset(PGconn *conn); @@ -440,7 +448,7 @@ void PQreset(PGconn *conn); PQresetPollPQresetPoll - 以非阻塞方式重置与服务器的通讯通道。 + 以非阻塞方式重置与服务器的通信通道。 int PQresetStart(PGconn *conn); @@ -451,7 +459,9 @@ PostgresPollingStatusType PQresetPoll(PGconn *conn); 这些函数会关闭与服务器的连接,并尝试使用与之前完全相同的参数建立新连接。如果原本可用的连接丢失,这可以用于错误恢复。它们与上文的 PQreset 不同之处在于采用非阻塞方式。它们受到与 PQconnectStartParamsPQconnectStartPQconnectPoll 相同的限制。 - 要开始重置连接,请调用 PQresetStart。如果它返回 0,则重置失败。如果返回 1,则使用 PQresetPoll 轮询重置过程,其方式与使用 PQconnectPoll 创建连接完全相同。 + + 要开始重置连接,请调用 PQresetStart。如果返回 0,表示重置失败。如果返回 1,则使用 PQresetPoll 轮询重置过程,方式与使用 PQconnectPoll 建立连接完全相同。 + @@ -536,19 +546,19 @@ PGPing PQping(const char *conninfo); 几个libpq函数解析用户指定的字符串以获取连接参数。 - 这些字符串有两种被接受的格式:普通的关键字/值字符串和URI。URI通常遵循 + 这些字符串有两种被接受的格式:普通的关键词/值字符串和URI。URI通常遵循 RFC - 3986,除了允许多主机连接字符串,如下面进一步描述的那样。 + 3986,但也允许使用多主机连接字符串,详见下文。 关键词/值连接字符串 - 在关键词/值格式中,每一个参数设置的形式都是keyword = value,在设置之间有空白。 - 设置的等号周围的空白是可选的。 - 要写一个空值或一个包含空白的值,将它用单引号包围,例如keyword = 'a value'。 - 值里面的单引号和反斜线必须用一个反斜线转义,即\'\\。 + 在关键词/值格式中,每一个参数设置的形式都是关键词 = ,设置之间以空格分隔。 + 设置的等号周围的空格是可选的。 + 要写一个空值或一个包含空格的值,将它用单引号包围,例如keyword = 'a value'。 + 值里面的单引号和反斜杠必须用一个反斜杠转义,即\'\\ @@ -571,22 +581,22 @@ host=localhost port=5432 dbname=mydb connect_timeout=10 postgresql://userspec@hostspec/dbname?paramspec -where userspec is: +其中 userspec 为: user:password -and hostspec is: +hostspec 为: host:port,... -and paramspec is: +paramspec 为: name=value&... - URI模式标志符可以是postgresql://postgres://。 + URI方案标识符可以是postgresql://postgres://。 每一个剩下的URI部分都是可选的。 下列示例展示了合法的URI语法: @@ -603,7 +613,7 @@ postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application postgresql:///mydb?host=localhost&port=5433 - 全部的命名参数必须匹配中列出的关键词,除了与JDBC连接URI兼容之外,ssl=true的实例转换到sslmode=require。 + 所有命名参数都必须与中列出的关键词匹配;唯一的例外是,为兼容 JDBC 连接 URI,会将 ssl=true 转换为 sslmode=require 可以在 URI 的任意部分使用百分号编码来包含具有特殊含义的符号,例如将 = 替换为 %3D @@ -619,7 +629,7 @@ postgresql://[2001:db8::1234]/database 主机组件会被按照参数对应的描述来解释。 特别地,如果主机部分是空或看起来像一个绝对路径名称,将使用一个 Unix 域套接字连接,否则将启动一个 TCP/IP 连接。 不过要注意,斜线是 URI 层次部分中的一个保留字符。 - 因此,要指定一个非标准的 Unix 域套接字目录,要么忽略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: + 因此,要指定一个非标准的 Unix 域套接字目录,要么省略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: postgresql:///dbname?host=/var/lib/postgresql postgresql://%2Fvar%2Flib%2Fpostgresql/dbname @@ -629,7 +639,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以在一个URI中指定多个主机,每一个都有一个可选的端口。 一个形式为postgresql://host1:port1,host2:port2,host3:port3/的URI等效于host=host1,host2,host3 port=port1,port2,port3形式的连接字符串。 - 如下所述,每一个主机都将被尝试,直到成功地建立一个连接。 + 如下所述,每一个主机都将被依次尝试,直到成功地建立一个连接。 @@ -638,7 +648,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以指定多个要连接的主机,这样它们会按给定的顺序被尝试。 - 在键/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 + 在关键词/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 在指定的每一个选项中都必须给出相同数量的元素,这样第一个hostaddr对应于第一个主机名,第二个hostaddr对应于第二个主机名,以此类推。 不过,如果仅指定一个port,它将被应用于所有的主机。 @@ -648,7 +658,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 不管是哪一种格式,单一的主机名可以被翻译成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 + 不管是哪一种格式,单一的主机名可以被解析成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 @@ -686,7 +696,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 如果指定了host而没有指定hostaddr,则会发生主机名查找。 (当使用PQconnectPoll时,查找发生在PQconnectPoll首次考虑此主机名时, - 并且可能导致PQconnectPoll阻塞一段时间。) + 并且可能导致PQconnectPoll阻塞相当长的时间。) @@ -698,11 +708,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果同时指定了hosthostaddr, - 则hostaddr的值给出服务器的网络地址。 - 除非认证方法需要,否则host的值将被忽略, - 在这种情况下,它将用作主机名。 - + 如果同时指定了 hosthostaddr,则 hostaddr 的值给出服务器的网络地址。只有认证方法需要主机名时,才会将 host 的值用作主机名;否则忽略该值。 + 注意,以下情况很可能导致认证失败:host不是位于网络地址hostaddr的服务器名称。另外,同时指定hosthostaddr时,将使用host来标识密码文件中的连接(参见)。 @@ -746,8 +753,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - PostgreSQL用户连接的用户名。 - 默认为运行应用程序的操作系统用户名相同。 + 建立连接所用的 PostgreSQL 用户名。默认与运行应用程序的操作系统用户名相同。 @@ -757,7 +763,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果服务器要求密码认证,则使用密码。 + 服务器要求密码认证时所使用的密码。 @@ -827,9 +833,9 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 指定配置参数的回退值。 + 指定配置参数的后备值。 如果没有通过连接参数或PGAPPNAME环境变量为application_name指定值, - 则将使用此值。在通用实用程序中指定回退名称很有用,该程序希望设置默认应用程序名称, + 则将使用此值。在通用实用程序中指定后备名称很有用,该程序希望设置默认应用程序名称, 但允许用户覆盖它。 @@ -840,9 +846,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制是否使用客户端TCP保持活动。默认值为1,表示开启,但如果不想要保持活动,可以将其更改为0,表示关闭。 - 对于通过Unix域套接字进行的连接,此参数将被忽略。 - + 控制是否使用客户端 TCP keepalive。默认值为 1,表示开启;如果不需要 keepalive,可以将其设为 0,表示关闭。对于通过 Unix 域套接字建立的连接,此参数会被忽略。 + @@ -851,11 +856,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在多少秒的不活动后,TCP应向服务器发送保持活动消息。值为零使用系统默认值。 - 对通过Unix域套接字进行的连接或禁用保持活动的连接,此参数将被忽略。 - 仅在支持TCP_KEEPIDLE或等效套接字选项的系统以及Windows上支持; - 在其他系统上,它没有任何效果。 - + 控制在多久没有活动后,TCP 应向服务器发送 keepalive 消息,以秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPIDLE 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -864,11 +866,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在服务器未确认的情况下重新传输TCP保持活动消息的秒数。值为零时使用系统默认值。 - 此参数在通过Unix域套接字进行连接或禁用保持活动时将被忽略。 - 仅在支持TCP_KEEPINTVL或等效套接字选项的系统和Windows上支持; - 在其他系统上,此参数无效。 - + 控制未被服务器确认收到的 TCP keepalive 消息在多少秒后应被重传。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPINTVL 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -877,11 +876,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在客户端与服务器之间连接被视为断开之前可以丢失的TCP keepalive数量。 - 值为零时使用系统默认值。对通过Unix域套接字建立的连接或禁用keepalives的连接,此参数将被忽略。 - 仅在支持TCP_KEEPCNT或等效套接字选项的系统上受支持; - 在其他系统上,此参数无效。 - + 控制在客户端与服务器之间的连接被视为中断之前,可以丢失多少个 TCP keepalive 消息。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPCNT 或等效套接字选项的系统上受支持;在其他系统上无效。 + @@ -918,7 +914,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - prefer (默认) + prefer (默认) 首先尝试SSL连接;如果失败,则尝试非SSL连接 @@ -958,13 +954,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - sslmode被忽略用于Unix域套接字通信。 - 如果PostgreSQL没有SSL支持编译, + 在 Unix 域套接字通信中,sslmode 会被忽略。 + 如果PostgreSQL编译时未启用 SSL 支持, 使用选项requireverify-caverify-full会导致错误,而选项allowprefer 将被接受,但libpq实际上不会尝试建立SSL 连接。SSL使用libpq的SSL + sortas="libpq">在 libpq 中 @@ -974,15 +970,15 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 此选项已被sslmode设置所取代。 - + 此选项已弃用,请改用 sslmode 设置。 + 如果设置为1,则需要与服务器建立SSL连接(这相当于sslmode require)。libpq将拒绝连接,如果服务器不接受 SSL连接。如果设置为0(默认值), libpq将与服务器协商连接类型(相当于sslmode - prefer)。此选项仅在PostgreSQL编译时启用SSL支持。 + prefer)。此选项仅在 PostgreSQL 编译时启用了 SSL 支持的情况下可用。 @@ -1014,7 +1010,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 这个参数指定了用于客户端证书的密钥的位置。它可以指定一个文件名,该文件名将被用来替代默认的 ~/.postgresql/postgresql.key,或者它可以指定一个从外部引擎 - (引擎是OpenSSL可加载模块)获取的密钥。外部引擎规范应该包括一个由冒号分隔的引擎名称和 + (引擎是OpenSSL可加载模块)获取的密钥。外部引擎的指定形式应包含一个由冒号分隔的引擎名称和 一个引擎特定的密钥标识符。如果没有进行SSL连接,则此参数将被忽略。 @@ -1059,7 +1055,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname krbsrvname - 用于使用GSSAPI进行认证时要使用的Kerberos服务名称。 + 使用 GSSAPI 认证时所用的 Kerberos 服务名。 这必须与服务器配置中指定的Kerberos认证服务名称匹配,才能成功进行认证。 (另请参见。) @@ -1104,20 +1100,21 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 连接状态函数 - 这些函数可以被用来询问一个已有数据库连接对象的状态。 + 这些函数可用于查询现有数据库连接对象的状态。 - libpq-fe.h - libpq-int.h - libpq应用程序员应该小心地维护PGconn抽象。使用下面描述的访问函数来理解PGconn的内容。我们不推荐使用libpq-int.h引用内部的PGconn域,因为它们可能在未来改变。 - + libpq-fe.h + libpq-int.h + 编写 libpq 应用程序时,应注意维护 PGconn 的抽象。请使用下述访问函数获取 PGconn 的内容。不建议通过 libpq-int.h 引用 PGconn 的内部字段,因为这些字段将来可能改变。 + - 以下函数返回建立连接时确定的参数值。这些值在连接存续期间保持不变。如果使用多主机连接字符串,以下函数的值:PQhost, - PQportPQpass可能会在使用同一个PGconn对象建立新连接时改变。其他值在以下对象的整个生命周期内保持不变:PGconn对象。 + + 以下函数返回建立连接时确定的参数值。这些值在连接存续期间保持不变。如果使用多主机连接字符串,并使用同一个 PGconn 对象建立新连接,则 PQhostPQportPQpass 的返回值可能改变。其他值在 PGconn 对象的整个生命周期内保持不变。 + PQdb PQdb @@ -1164,7 +1161,7 @@ char *PQpass(const PGconn *conn); - 返回活跃连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 + 返回活动连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 char *PQhost(const PGconn *conn); @@ -1176,7 +1173,7 @@ char *PQhost(const PGconn *conn); - 如果conn参数是NULL,则PQhost返回NULL。否则,如果在生成主机信息时发生错误(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 PQhost 返回 NULL。否则,如果在生成主机信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1190,7 +1187,7 @@ char *PQhost(const PGconn *conn); - 返回活跃连接的端口。 + 返回活动连接的端口。 char *PQport(const PGconn *conn); @@ -1202,7 +1199,7 @@ char *PQport(const PGconn *conn); - 如果conn参数是NULL,则PQport返回NULL。否则,如果在生成端口信息时发生错误(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 PQport 返回 NULL。否则,如果在生成端口信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1215,7 +1212,9 @@ char *PQport(const PGconn *conn); PQtty PQtty - 返回连接的调试TTY。(此设置已过时,因为服务器不再理会TTY设置,但为保持向后兼容,仍保留了此函数。) + + 返回该连接用于调试的TTY。(此功能已过时,因为服务器不再使用TTY设置,但为保持向后兼容仍保留此函数。) + char *PQtty(const PGconn *conn); @@ -1227,7 +1226,7 @@ char *PQtty(const PGconn *conn); - 返回被传递给连接请求的命令行选项。 + 返回连接请求中传递的命令行选项。 char *PQoptions(const PGconn *conn); @@ -1235,9 +1234,11 @@ char *PQoptions(const PGconn *conn); - + - 以下函数返回的状态数据可能在执行操作时发生变化,这些操作针对PGconn对象。 + + 以下函数返回的状态数据,可能随着对 PGconn 对象执行操作而改变。 + PQstatus PQstatus @@ -1273,7 +1274,7 @@ ConnStatusType PQstatus(const PGconn *conn); PGTransactionStatusType PQtransactionStatus(const PGconn *conn); - 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个合法的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接损坏,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE。 + 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个有效的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接异常,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE @@ -1315,9 +1316,12 @@ const char *PQparameterStatus(const PGconn *conn, const char *paramName); PQprotocolVersion PQprotocolVersion - 查询正在使用的前端/后端协议。 + + 查询正在使用的前端/后端协议。 + int PQprotocolVersion(const PGconn *conn); -应用程序可以使用此函数判断是否支持某些特性。目前可能的值为 2(协议 2.0)、3(协议 3.0)或零(连接无效)。连接启动完成后,协议版本不会改变,但理论上可能在重置连接时改变。与PostgreSQL7.4 或更新版本的服务器通信时,通常使用协议 3.0;7.4 之前的服务器仅支持协议 2.0。(协议 1.0 已过时,且不被以下库支持:libpq。) + +应用程序可以使用此函数判断是否支持某些特性。目前,可能的值为 2(协议 2.0)、3(协议 3.0)或零(连接异常)。连接启动完成后,协议版本不会改变,但理论上可能在连接重置期间改变。通常,与 PostgreSQL 7.4 或更高版本的服务器通信时使用协议 3.0;7.4 之前的服务器仅支持协议 2.0。(协议 1.0 已过时,libpq 不支持它。) @@ -1338,11 +1342,11 @@ int PQserverVersion(const PGconn *conn); - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,PQserverVersion为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 + 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,PQserverVersion为每个部分使用两位数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - 因此,出于判断特性兼容性的目的,应用应该将PQserverVersion的结果除以100而不是10000来判断逻辑的主版本号。在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 + 因此,出于判断特性兼容性的目的,应用应该将PQserverVersion的结果除以100而不是10000来判断逻辑的主版本号。在所有主版本系列中,各次版本(缺陷修复版本)之间只有最后两位数字不同。 @@ -1361,9 +1365,7 @@ char *PQerrorMessage(const PGconn *conn); - 几乎所有的libpq函数在失败时都会为PQerrorMessage设置一个消息。 - 注意按照libpq习惯,一个非空PQerrorMessage结果可能由多行构成,并且将包括一个尾部新行。 - 调用者不应该直接释放结果。当相关的PGconn句柄被传递给PQfinish时,它将被释放。在PGconn结构体上的多个操作之间,不能指望结果字符串会保持不变。 + 几乎所有 libpq 函数在失败时都会设置一条供 PQerrorMessage 返回的消息。注意,按照 libpq 的约定,非空的 PQerrorMessage 结果可能包含多行,并以换行符结尾。调用者不应直接释放该结果;当关联的 PGconn 句柄被传给 PQfinish 时,结果会被释放。不能假定在对 PGconn 结构体执行其他操作后,结果字符串仍保持不变。 @@ -1372,7 +1374,7 @@ char *PQerrorMessage(const PGconn *conn); PQsocketPQsocket - 获得到服务器连接套接字的文件描述符号。一个合法的描述符将会大于等于零。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 + 获取与服务器相连的套接字的文件描述符编号。有效描述符大于或等于 0。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 int PQsocket(const PGconn *conn); @@ -1389,7 +1391,7 @@ int PQsocket(const PGconn *conn); 返回处理这个连接的后端进程的进程ID(PID)。 PID 确定服务器进程的 PID - in libpq + 在 libpq 中 @@ -1398,7 +1400,7 @@ int PQbackendPID(const PGconn *conn); - 后端PID有助于调试目的并且可用于与NOTIFY消息(它包括发出提示的后端进程的PID)进行比较。注意PID属于一个在数据库服务器主机上执行的进程,而不是本地主机进程! + 后端 PID 可用于调试,也可与 NOTIFY 消息进行比较(消息包含发出通知的后端进程的 PID)。注意,该 PID 属于在数据库服务器主机上运行的进程,而非本地主机上的进程! @@ -1437,15 +1439,17 @@ int PQconnectionUsedPassword(const PGconn *conn); - + - 以下函数返回与 SSL 相关的信息。这些信息通常在连接建立后不会改变。 + + 以下函数返回与 SSL 相关的信息。这些信息通常在连接建立后不会改变。 + PQsslInUsePQsslInUse - 返回true(1)如果连接使用SSL,返回false(0)如果不使用。 + 如果连接使用 SSL,则返回真(1);否则返回假(0)。 int PQsslInUse(const PGconn *conn); @@ -1464,10 +1468,10 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); - 可用属性列表因使用的SSL库和连接类型而异。如果连接不使用SSL或指定的属性名称对于所使用的库未定义,则返回NULL。 + 可用属性列表因所使用的 SSL 库和连接类型而异。如果某个属性不可用,则返回 NULL。 - 通常可以取得以下属性: + 通常可以获取以下属性: library @@ -1532,12 +1536,14 @@ const char * const * PQsslAttributeNames(const PGconn *conn); PQsslStructPQsslStruct - 返回一个指向描述连接的SSL实现特定对象的指针。如果连接未加密或SSL实现不提供连接的请求对象类型,则返回NULL。 + 返回指向描述此连接的对象的指针,该对象的类型由 SSL 实现决定。 void *PQsslStruct(const PGconn *conn, const char *struct_name); - 可用的结构体取决于所使用的 SSL 实现。对于 OpenSSL,有一个名为 "OpenSSL" 的结构体,取得它时会返回指向 OpenSSLSSL结构体的指针。可以使用类似以下的代码来调用此函数: + 可用的结构体取决于所使用的 SSL 实现。对于 OpenSSL,可以通过名称 "OpenSSL" 获取一个结构体,函数返回指向 OpenSSL 的 SSL 结构体的指针。可以使用如下代码调用此函数: + #include @@ -1579,7 +1585,7 @@ void *PQgetssl(const PGconn *conn); - + @@ -1587,7 +1593,7 @@ void *PQgetssl(const PGconn *conn); 命令执行函数 - 一旦到一个数据库服务器的连接被成功建立,这里描述的函数可以被用来执行 SQL 查询和命令。 + 与数据库服务器的连接成功建立后,此处描述的函数用于执行 SQL 查询和命令。 @@ -1608,11 +1614,8 @@ PGresult *PQexec(PGconn *conn, const char *command); - 返回一个PGresult指针或者可能是一个空指针。 - 除了内存不足的情况或者由于严重错误无法将命令发送给服务器之外,一般都会返回一个非空指针。 - PQresultStatus函数应当被调用来检查返回值是否代表错误(包括空指针的值,它会返回PGRES_FATAL_ERROR)。 - 用PQerrorMessage可得到关于那些错误的详细信息。 - + 返回一个 PGresult 指针,也可能返回空指针。除内存不足或无法向服务器发送命令等严重错误外,通常都会返回非空指针。应调用 PQresultStatus 函数检查返回值是否表示错误(也应检查空指针,此时该函数返回 PGRES_FATAL_ERROR)。使用 PQerrorMessage 获取此类错误的更多信息。 + 命令字符串可以包含多个 SQL 命令(以分号分隔)。在一次PQexec调用中发送的多个查询会在同一个事务中处理,除非查询字符串中显式包含BEGIN/COMMIT命令将其划分为多个事务。不过要注意,返回的PGresult结构体只描述该字符串中最后执行的命令的结果。如果其中一条命令失败,就会在此处停止处理该字符串,返回的PGresult则描述该错误。 @@ -1685,8 +1688,8 @@ PGresult *PQexecParams(PGconn *conn, paramValues[] - 指定参数的实际值。这个数组中的一个空指针表示对应的参数为空,否则该指针指向一个以零终止的文本字符串(用于文本格式)或者以服务器所期待格式的二进制数据(用于二进制格式)。 - + 指定参数的实际值。数组中的空指针表示对应参数为 null;否则,指针指向以零结尾的文本字符串(文本格式),或采用服务器所要求格式的二进制数据(二进制格式)。 + @@ -1694,8 +1697,8 @@ PGresult *PQexecParams(PGconn *conn, paramLengths[] - 指定二进制格式参数的实际数据长度。它对空参数和文本格式参数被忽略。当没有二进制参数时,该数组指针可以为空。 - + 指定二进制格式参数的实际数据长度。对于 null 参数和文本格式参数,该值会被忽略。如果没有二进制参数,数组指针可以为空指针。 + @@ -1703,11 +1706,11 @@ PGresult *PQexecParams(PGconn *conn, paramFormats[] - 指定参数是否为文本(在参数相应的数组项中放一个零)或二进制(在参数相应的数组项中放一个一)。如果该数组指针为空,那么所有参数都会被假定为文本串。 - + 指定参数采用文本格式(在对应数组元素中填入零)还是二进制格式(填入一)。如果数组指针为空指针,则将所有参数视为文本字符串。 + - 以二进制格式传递的值要求后端所期待的内部表示形式的知识。例如,整数必须以网络字节序被传递。传递numeric值要求关于服务器存储格式的知识,正如src/backend/utils/adt/numeric.c::numeric_send()以及src/backend/utils/adt/numeric.c::numeric_recv()中所实现的。 - + 以二进制格式传递值时,需要了解后端所要求的内部表示形式。例如,整数必须以网络字节序传递。传递 numeric 值时,需要了解服务器的存储格式,其实现见 src/backend/utils/adt/numeric.c::numeric_send()src/backend/utils/adt/numeric.c::numeric_recv()。 + @@ -1715,8 +1718,8 @@ PGresult *PQexecParams(PGconn *conn, resultFormat - 指定零来得到文本格式的结果,或者指定一来得到二进制格式的结果(目前没有规定要求以不同格式得到不同的结果列,尽管在底层协议中这是可以实现的)。 - + 指定零以获取文本格式的结果,指定一以获取二进制格式的结果。(目前无法让不同结果列使用不同格式,尽管底层协议支持这样做。) + @@ -1726,7 +1729,9 @@ PGresult *PQexecParams(PGconn *conn, - PQexecParams 相对于 PQexec 的主要优点是可以将参数值与命令字符串分开,从而避免繁琐且容易出错的加引号和转义工作。 + + PQexecParams 相对于 PQexec 的主要优点是可以将参数值与命令字符串分开,从而避免繁琐且容易出错的加引号和转义工作。 + PQexec不同,PQexecParams至多允许在给定串中出现一个 SQL 命令(其中可以有分号,但是不能有超过一个非空命令)。这是底层协议的一个限制,但是有助于抵抗 SQL 注入攻击。 @@ -1735,12 +1740,12 @@ PGresult *PQexecParams(PGconn *conn, - 通过 OID 指定参数类型很罗嗦,特别是如果你不愿意将特定的 OID 值硬编码到你的程序中时。不过,即使服务器本身也无法确定参数的类型,你可以避免这样做,或者选择一种与你想要的不同的类型。在 SQL 命令文本中,附加一个显式类型转换给参数符号来表示你将发送什么样的数据类型。例如: + 通过 OID 指定参数类型较为繁琐,尤其是在不希望将具体 OID 值写死在程序中时。不过,即使服务器无法自行确定参数类型,或者推断出的类型与你所需的不同,也可以避免直接指定 OID。在 SQL 命令文本中,为参数符号添加显式类型转换,即可指定要发送的数据类型。例如: SELECT * FROM mytable WHERE x = $1::bigint; - 这强制参数$1被当作bigint,而默认情况下它将被赋予与x相同的类型。当以二进制格式发送参数值时,我们强烈推荐以这种方式或通过指定一个数字类型的 OID 来强制参数类型决定。因为二进制格式比文本格式具有更少的冗余,并且因此服务器将不会有更多机会为你检测一个类型匹配错误。 - +这会强制将参数 $1 当作 bigint,而默认情况下会为它分配与 x 相同的类型。以二进制格式发送参数值时,强烈建议采用这种方式,或直接指定类型的数值 OID,来明确决定参数类型。因为二进制格式的冗余比文本格式更少,服务器发现类型不匹配错误的机会也更少。 + @@ -1760,13 +1765,15 @@ PGresult *PQprepare(PGconn *conn, - PQprepare 创建一个预备语句,供随后使用 PQexecPrepared 执行。此功能允许重复执行命令,而不必每次都进行解析和规划;详见 PQprepare 仅在使用协议 3.0 及更高版本的连接中受支持,使用协议 2.0 时会失败。 + + PQprepare 创建一个预备语句,供随后使用 PQexecPrepared 执行。此功能允许重复执行命令,而不必每次都进行解析和规划;详见 PQprepare 仅在使用协议 3.0 及更高版本的连接中受支持,使用协议 2.0 时会失败。 + 该函数从query串创建一个名为stmtName的预备语句,该串必须包含一个单一 SQL 命令。 stmtName可以是""来创建一个未命名语句,在这种情况下任何已存在未命名语句将被自动替换。 否则,如果语句名称已经在当前会话中被定义,则是一种错误。如果使用了任何参数,它们在查询中以$1$2等引用。 - nParams是参数的个数,其类型在数组paramTypes[]中被预先指定(当nParams为零时,该数组指针可以是NULL)。 + nParams 是在数组 paramTypes[] 中预先指定了类型的参数数量(当nParams为零时,该数组指针可以是NULL)。 paramTypes[]通过 OID 指定要赋予给参数符号的数据类型。 如果paramTypesNULL或者该数组中任何特定元素为零,服务器会用对待未指定类型的字符串字面量的方式为参数符号推测一种数据类型。 还有,查询能够使用编号高于nParams的参数符号,它们的数据类型也会被自动推测(找出推测出的数据类型的方法见PQdescribePrepared)。 @@ -1774,7 +1781,7 @@ PGresult *PQprepare(PGconn *conn, 正如PQexec一样,结果通常是一个PGresult对象,其内容代表服务器端成功或失败。 - 一个空结果表示内存不足或者根本无法发送命令。关于错误的更多信息请见PQerrorMessage。 + 返回空指针表示内存不足,或者根本无法发送命令。关于错误的更多信息请见PQerrorMessage @@ -1799,7 +1806,7 @@ PGresult *PQexecPrepared(PGconn *conn, - PQexecPrepared类似于PQexecParams, 但要执行的命令是通过指定先前准备好的语句来指定,而不是提供查询字符串。 此功能允许重复使用的命令只被解析和计划一次,而不是每次执行时都要进行。 该语句必须在当前会话中先前准备好。 PQexecPrepared 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + PQexecPrepared类似于PQexecParams, 但它通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。 此功能使重复使用的命令只需解析和规划一次,而不必在每次执行时都进行这些工作。 该语句必须事先在当前会话中创建为预备语句。 PQexecPrepared 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 参数与PQexecParams相同,只是给出了预备语句的名称而不是查询字符串, @@ -1813,21 +1820,21 @@ PGresult *PQexecPrepared(PGconn *conn, - 提交请求以获取有关指定准备好的语句的信息,并等待完成。 + 提交请求以获取有关指定预备语句的信息,并等待完成。 PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - PQdescribePrepared允许应用程序获取关于先前准备的语句的信息。 PQdescribePrepared 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + PQdescribePrepared允许应用程序获取关于先前创建的预备语句的信息。 PQdescribePrepared 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 stmtName可以是""NULL来引用 - 未命名的语句,否则必须是现有准备好的语句的名称。成功时,返回一个 + 未命名的语句,否则必须是现有预备语句的名称。成功时,返回一个 状态为PGRES_COMMAND_OKPGresult。 函数PQnparamsPQparamtype可以应用于此 - PGresult以获取有关准备语句参数的信息, + PGresult以获取有关预备语句参数的信息, 函数PQnfieldsPQfnamePQftype等提供有关语句的结果列(如果有)的信息。 @@ -1839,13 +1846,15 @@ PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - 提交请求以获取有关指定门户的信息,并等待完成。 + 提交请求以获取有关指定 portal 的信息,并等待完成。 PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - PQdescribePortal允许应用程序获取有关先前创建的 portal 的信息。 (libpq不直接提供对 portal 的访问,但你可以使用此函数检查通过DECLARE CURSOR SQL 命令创建的游标的属性。) PQdescribePortal 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + + PQdescribePortal 允许应用程序获取先前创建的 portal 的信息。(libpq 不提供对 portal 的直接访问,但可以用此函数检查通过 DECLARE CURSOR SQL 命令创建的游标的属性。) PQdescribePortal 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + portalName可以是""NULL来引用未命名的 portal, @@ -1858,7 +1867,9 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - PGresultPGresult结构体封装服务器返回的结果。libpq应用程序的开发者应注意保持PGresult的抽象性。请使用下面的访问函数获取PGresult的内容。避免直接引用PGresult结构体的字段,因为这些字段以后可能改变。 + + PGresultPGresult 结构体封装服务器返回的结果。编写 libpq 应用程序时,应注意维护 PGresult 的抽象。请使用下述访问函数获取 PGresult 的内容。避免直接引用 PGresult 结构体的字段,因为这些字段将来可能改变。 + PQresultStatus PQresultStatus @@ -1957,7 +1968,7 @@ ExecStatusType PQresultStatus(const PGresult *res); PGRES_SINGLE_TUPLE - PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单一行模式时发生(见)。 + PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单行模式时发生(见)。 @@ -1974,10 +1985,12 @@ ExecStatusType PQresultStatus(const PGresult *res); PQresStatus PQresStatus - PQresultStatus返回的枚举值转换为描述该状态码的字符串常量。调用者不应释放此结果。 + + 将 PQresultStatus 返回的枚举值转换为描述该状态码的字符串常量。调用者不应释放此结果。 + char *PQresStatus(ExecStatusType status); - + @@ -1985,10 +1998,13 @@ char *PQresStatus(ExecStatusType status); PQresultErrorMessage PQresultErrorMessage - 返回与命令关联的错误消息;如果没有错误,则返回空字符串。 + + 返回与命令关联的错误消息;如果没有错误,则返回空字符串。 + char *PQresultErrorMessage(const PGresult *res); -如果发生了错误,返回的字符串会包含末尾换行符。调用者不应直接释放结果。在将关联的PGresult句柄传给以下函数时,会释放该结果:PQclear。 - + +如果发生了错误,返回的字符串会以换行符结尾。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 PQclear 时,结果会被释放。 + 紧跟着一个PQexecPQgetResult调用,PQerrorMessage(在连接上)将返回与PQresultErrorMessage相同的字符串(在结果上)。 @@ -2003,11 +2019,15 @@ char *PQresultErrorMessage(const PGresult *res); PQresultVerboseErrorMessage PQresultVerboseErrorMessage - 返回与PGresult对象关联的错误消息的重新格式化版本。 + + 返回与 PGresult 对象关联的错误消息的重新格式化版本。 + char *PQresultVerboseErrorMessage(const PGresult *res, PGVerbosity verbosity, PGContextVisibility show_context); -某些情况下,客户端可能希望取得之前报告的错误的更详细版本。PQresultVerboseErrorMessage可以满足这一需求:它计算以下函数本应生成的消息:PQresultErrorMessage,假设在生成给定的PGresult时,连接已经采用指定的详细程度设置。如果PGresult不是错误结果,则改为报告PGresult is not an error result。返回的字符串包含末尾换行符。 + +有时客户端希望获取先前报告过的错误的更详细版本。PQresultVerboseErrorMessage 可满足这一需求:它按指定的详细程度设置重新生成消息。假如在生成给定 PGresult 时,连接已经采用这些设置,那么 PQresultErrorMessage 返回的就会是这条消息。如果 PGresult 不是错误结果,则改为报告 PGresult is not an error result。返回的字符串以换行符结尾。 + 和大部分从PGresult中提取数据的其他函数不同,这个函数的结果是一个全新分配的字符串。调用者在不需要这个字符串以后,必须使用PQfreemem()释放它。 @@ -2022,18 +2042,20 @@ char *PQresultVerboseErrorMessage(const PGresult *res, PQresultErrorFieldPQresultErrorField - 返回错误报告中的单个字段。 + + 返回错误报告中的单个字段。 + char *PQresultErrorField(const PGresult *res, int fieldcode); - fieldcode是错误字段标识符,参见下文列出的符号。NULL会在以下情况下返回:PGresult不是错误或警告结果,或者不包含指定字段。字段值通常不含末尾换行符。调用者不应直接释放结果。在将关联的PGresult句柄传给以下函数时,会释放该结果:PQclear。 - +fieldcode 是错误字段标识符,参见下文列出的符号。如果 PGresult 不是错误或警告结果,或者不包含指定字段,则返回 NULL。字段值通常不含末尾换行符。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 PQclear 时,结果会被释放。 + 可以使用以下字段代码: PG_DIAG_SEVERITY - 严重性。域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 @@ -2042,16 +2064,16 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_SEVERITY_NONLOCALIZED - 域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY域相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 版本以后产生的报告中。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY字段相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 及更高版本产生的报告中。 - PG_DIAG_SQLSTATEerror codeslibpq + PG_DIAG_SQLSTATE错误码libpq - 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个域无法被本地化,并且总是存在。 + 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个字段无法被本地化,并且总是存在。 @@ -2078,7 +2100,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_MESSAGE_HINT - 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是铁的事实。可能有多行。 + 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是确切事实。可能有多行。 @@ -2096,7 +2118,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_INTERNAL_POSITION - 这被定义为与PG_DIAG_STATEMENT_POSITION域相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个域出现时,PG_DIAG_INTERNAL_QUERY域将总是出现。 + 这被定义为与PG_DIAG_STATEMENT_POSITION字段相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个字段出现时,PG_DIAG_INTERNAL_QUERY字段将总是出现。 @@ -2114,7 +2136,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONTEXT - 指示错误发生的环境。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 + 指示错误发生的上下文。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 @@ -2132,7 +2154,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_TABLE_NAME - 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名域)。 + 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名字段)。 @@ -2141,7 +2163,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_COLUMN_NAME - 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名域来标识该表)。 + 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名字段来标识该表)。 @@ -2150,7 +2172,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_DATATYPE_NAME - 如果错误与一个特定数据类型相关,这里是该数据了行的名字(该数据类型的模式名参考模式名域)。 + 如果错误与一个特定数据类型相关,这里是该数据类型的名字(该数据类型的模式名参考模式名字段)。 @@ -2159,7 +2181,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONSTRAINT_NAME - 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的域(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 + 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的字段(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 @@ -2195,12 +2217,12 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); - 用于模式名、表名、列名、数据类型名和约束名的域只提供给有限的错误类型,见。不要假定任何这些域的存在保证另一个域的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些域。同样地,不要假定这些域代表当前数据库中同类的对象。 + 用于模式名、表名、列名、数据类型名和约束名的字段只提供给有限的错误类型,见。不要假定任何这些字段的存在保证另一个字段的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些字段。同样地,不要假定这些字段代表当前数据库中现存的对象。 - 客户端负责格式化显示信息来迎合它的需要,特别是根据需要打断长的行。出现在错误消息域中的新行字符应该被当作分段而不是换行。 + 客户端负责按自身需要格式化所显示的信息,尤其应在需要时将长行折行。错误消息字段中的换行符应当视为段落分隔,而非行分隔。 libpq 内部产生的错误包含严重性和主要消息,但通常没有其他字段。使用 3.0 之前协议的服务器返回的错误包含严重性和主要消息,有时还包含详细消息,但没有其他字段。 @@ -2214,10 +2236,12 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PQclearPQclear - 释放与PGresult关联的存储空间。每个命令结果都应通过PQclear在不再需要结果时将其释放。 + + 释放与 PGresult 关联的存储空间。每个命令结果在不再需要时都应通过 PQclear 释放。 + void PQclear(PGresult *res); - + 你可以在需要时一直保留PGresult对象;它不会在你发出新命令时消失,甚至在关闭连接后也不会消失。要销毁它,你必须调用PQclear。否则应用程序会发生内存泄漏。 @@ -2225,15 +2249,15 @@ void PQclear(PGresult *res); - + 检索查询结果信息 - 这些函数被用来从一个代表成功查询结果(也就是状态为PGRES_TUPLES_OK或者PGRES_SINGLE_TUPLE)的PGresult对象中抽取信息。它们也可以被用来从一个成功的 Describe 操作中抽取信息:一个 Describe 的结果具有和该查询被实际执行所提供的完全相同的列信息,但是它没有行。对于其他状态值的对象,这些函数会认为结果具有零行和零列。 - + 这些函数用于从表示成功查询结果的 PGresult 对象中提取信息,即状态为 PGRES_TUPLES_OKPGRES_SINGLE_TUPLE 的对象。它们也可用于提取成功 Describe 操作的结果信息:Describe 结果包含的列信息与实际执行查询时相同,但行数为零。对于其他状态值的对象,这些函数会将结果视为零行、零列。 + @@ -2258,7 +2282,7 @@ int PQntuples(const PGresult *res); - 返回查询结果中每一行的列(域)数。 + 返回查询结果中每一行的列(字段)数。 int PQnfields(const PGresult *res); @@ -2271,7 +2295,8 @@ int PQnfields(const PGresult *res); PQfname PQfname - 返回给定列号对应的列名。列号从 0 开始。调用者不应直接释放结果。在将关联的PGresult句柄传给以下函数时,会释放该结果:PQclear。 + + 返回给定列号对应的列名。列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 PQclear 时,结果会被释放。 char *PQfname(const PGresult *res, int column_number); @@ -2302,11 +2327,11 @@ int PQfnumber(const PGresult *res, - 给定的名称被视作一个 SQL 命令中的一个标识符,也就是说,除非被双引号引用,它是小写形式的。例如,给定一个 SQL 命令: + 给定名称按 SQL 命令中的标识符处理,即除非用双引号引用,否则会转换为小写。例如,对于以下 SQL 命令生成的查询结果: SELECT 1 AS FOO, 2 AS "BAR"; - 我们将得到结果: +会得到以下结果: PQfname(res, 0) foo PQfname(res, 1) BAR @@ -2324,7 +2349,7 @@ PQfnumber(res, "\"BAR\"") 1 - 返回给定列从中取出的表的 OID。列号从 0 开始。 + 返回给定列所取自的表的 OID。列号从 0 开始。 Oid PQftable(const PGresult *res, int column_number); @@ -2333,7 +2358,9 @@ Oid PQftable(const PGresult *res, 如果列号超出范围、指定的列不是对表列的简单引用,或者使用 3.0 之前的协议,则返回 InvalidOid。可以查询系统表 pg_class,确定所引用的具体表。 - 包含 libpq 头文件后,将定义类型 Oid 和常量 InvalidOid。它们都属于某种整数类型。 + + 包含 libpq 头文件后,将定义类型 Oid 和常量 InvalidOid。它们都属于某种整数类型。 + @@ -2342,7 +2369,7 @@ Oid PQftable(const PGresult *res, - 返回构成指定查询结果列的列(在其表中)的列号。查询结果列号从 0 开始,但是表列具有非零编号。 + 返回指定查询结果列所对应的表列在表中的列号。查询结果的列号从 0 开始,而表列的编号非零。 int PQftablecol(const PGresult *res, int column_number); @@ -2359,7 +2386,7 @@ int PQftablecol(const PGresult *res, - 返回指示给定列格式的格式编码。列号从 0 开始。 + 返回表示给定列格式的格式代码。列号从 0 开始。 int PQfformat(const PGresult *res, int column_number); @@ -2367,7 +2394,7 @@ int PQfformat(const PGresult *res, - 格式代码零指示文本数据表示,而格式代码一表示二进制表示(其他代码被保留用于未来的定义)。 + 格式代码零表示文本数据,格式代码一表示二进制数据。(其他代码保留供将来定义。) @@ -2394,7 +2421,7 @@ Oid PQftype(const PGresult *res, - 返回与给定列号相关联的列的修饰符类型。列号从 0 开始。 + 返回与给定列号相关联的列的类型修饰符。列号从 0 开始。 int PQfmod(const PGresult *res, int column_number); @@ -2402,7 +2429,7 @@ int PQfmod(const PGresult *res, - 修饰符值的解释是与类型相关的,它们通常指示精度或尺寸限制。值 -1 被用来指示没有信息可用。大部分的数据类型不适用修饰符,在那种情况中值总是 -1。 + 修饰符值的含义由数据类型决定,通常表示精度或大小限制。值 -1 表示没有可用信息。大多数数据类型不使用修饰符,此时该值始终为 -1。 @@ -2412,7 +2439,7 @@ int PQfmod(const PGresult *res, - 返回与给定列号相关的列的尺寸(以字节计)。列号从 0 开始。 + 返回给定列号对应列的大小,以字节计。列号从 0 开始。 int PQfsize(const PGresult *res, int column_number); @@ -2420,7 +2447,7 @@ int PQfsize(const PGresult *res, - PQfsize返回在一个数据库行中为这个列分配的空间,换句话说是服务器对该数据类型的内部表示的尺寸(因此,它对客户端并不是真地非常有用)。一个负值指示该数据类型是变长的。 + PQfsize 返回数据库行中为该列分配的空间,即服务器内部表示该数据类型所需的大小。(因此,它对客户端用处不大。)负值表示该数据类型是变长类型。 @@ -2437,8 +2464,7 @@ int PQbinaryTuples(const PGresult *res); - 这个函数已经被废弃(除了与COPY一起使用),因为一个单一PGresult可以在某些列中包含文本数据而且在另一些列中包含二进制数据。 - PQfformat要更好。只有结果的所有列是二进制(格式 1)时PQbinaryTuples才返回 1。 + 此函数已弃用(与 COPY 配合使用的情况除外),因为单个 PGresult 可能在部分列中包含文本数据,而在其他列中包含二进制数据。推荐使用 PQfformat。只有结果中的所有列都采用二进制格式(格式 1)时,PQbinaryTuples 才返回 1。 @@ -2447,7 +2473,8 @@ int PQbinaryTuples(const PGresult *res); PQgetvalue PQgetvalue - 返回以下结果中某一行的一个字段值:PGresult。行号和列号都从 0 开始。调用者不应直接释放结果。在将关联的PGresult句柄传给以下函数时,会释放该结果:PQclear。 + + 返回 PGresult 中某一行的单个字段值。行号和列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 PQclear 时,结果会被释放。 char *PQgetvalue(const PGresult *res, int row_number, @@ -2455,24 +2482,26 @@ char *PQgetvalue(const PGresult *res, - 对于文本格式的数据,PQgetvalue 返回字段值的字符串表示,以零字节结尾。对于二进制格式的数据,返回值采用该数据类型的 typsendtypreceive 函数所决定的二进制表示。(这种情况下,值后面实际上也有一个零字节,但通常没有用处,因为值本身很可能包含零字节。) + + 对于文本格式的数据,PQgetvalue 返回字段值的字符串表示,以零字节结尾。对于二进制格式的数据,返回值采用该数据类型的 typsendtypreceive 函数所决定的二进制表示。(这种情况下,值后面实际上也有一个零字节,但通常没有用处,因为值本身很可能包含零字节。) + - 如果该域值为空,则返回一个空串。关于区分空值和空字符串值请见PQgetisnull。 + 如果字段值为 null,则返回空字符串。关于如何区分 null 值与空字符串值,参见 PQgetisnull - PQgetvalue返回的指针指向作为PGresult结构体一部分的存储。我们不应该修改它指向的数据,并且如果要在超过PGresult结构体本身的生命期之外使用它,我们必须显式地把该数据拷贝到其他存储中。 + PQgetvalue 返回的指针指向属于 PGresult 结构体的存储空间。不应修改它所指向的数据;如果需要在 PGresult 结构体的生命周期结束后继续使用这些数据,就必须显式地将数据复制到其他存储空间。 - PQgetisnullPQgetisnullnull valuein libpq + PQgetisnullPQgetisnullnull 值libpq 中的 - 测试一个域是否为空值。行号和列号从 0 开始。 + 检查字段是否为 null 值。行号和列号从 0 开始。 int PQgetisnull(const PGresult *res, int row_number, @@ -2481,7 +2510,7 @@ int PQgetisnull(const PGresult *res, - 如果该域是空,这个函数返回 1。如果它包含一个非空值,则返回 0(注意PQgetvalue将为一个空域返回一个空串,不是一个空指针)。 + 如果字段为 null,此函数返回 1;如果包含非 null 值,则返回 0。(注意,对于 null 字段,PQgetvalue 返回空字符串,而非空指针。) @@ -2491,7 +2520,7 @@ int PQgetisnull(const PGresult *res, - 返回一个域值的真实长度,以字节计。行号和列号从 0 开始。 + 返回字段值的实际长度,以字节计。行号和列号从 0 开始。 int PQgetlength(const PGresult *res, int row_number, @@ -2500,9 +2529,7 @@ int PQgetlength(const PGresult *res, - 这是特定数据值的真实数据长度,也就是PQgetvalue指向的对象的尺寸。 - 对于文本数据格式,这和strlen()相同。对于二进制格式这是基本信息。 - 注意我们应该依赖于PQfsize来得到实际的数据长度。 + 这是该数据值的实际数据长度,即 PQgetvalue 所指对象的大小。对于文本格式的数据,它与 strlen() 的结果相同。对于二进制格式,这是必不可少的信息。注意,不应依赖 PQfsize 来获取实际数据长度。 @@ -2547,29 +2574,29 @@ Oid PQparamtype(const PGresult *res, int param_number); - 将所有的行打印到指定的输出流,以及有选择地将列名打印到指定的输出流。 + 将所有行输出到指定的输出流,并可选择输出列名。 void PQprint(FILE *fout, /* 输出流 */ const PGresult *res, const PQprintOpt *po); typedef struct { - pqbool header; /* 打印输出域标题和行计数 */ - pqbool align; /* 填充对齐域 */ - pqbool standard; /* 旧的格式 */ + pqbool header; /* 打印输出字段标题和行数 */ + pqbool align; /* 填充并对齐字段 */ + pqbool standard; /* 旧的简陋格式 */ pqbool html3; /* 输出 HTML 表格 */ - pqbool expanded; /* 扩展表格 */ - pqbool pager; /* 如果必要为输出使用页 */ - char *fieldSep; /* 域分隔符 */ + pqbool expanded; /* 展开表格 */ + pqbool pager; /* 需要时使用分页器输出 */ + char *fieldSep; /* 字段分隔符 */ char *tableOpt; /* 用于 HTML 表格元素的属性 */ char *caption; /* HTML 表格标题 */ - char **fieldName; /* 替换域名称的空终止数组 */ + char **fieldName; /* 以空指针结尾的替换字段名数组 */ } PQprintOpt; - 这个函数以前被psql用来打印查询结果,但是现在不是这样了。注意它假定所有的数据都是文本格式。 + psql 以前用此函数打印查询结果,现在已不再使用。注意,此函数假定所有数据都是文本格式。 @@ -2612,7 +2639,9 @@ char *PQcmdTuples(PGresult *res); - 此函数返回一个字符串,其中包含产生该 PGresultSQL 语句所影响的行数。此函数只能在执行 SELECTCREATE TABLE ASINSERTUPDATEDELETEMOVEFETCHCOPY 语句之后使用,也可以在对包含 INSERTUPDATEDELETE 语句的预备查询执行 EXECUTE 之后使用。如果产生 PGresult 的是其他命令,PQcmdTuples 将返回空字符串。调用者不应直接释放返回值;将关联的 PGresult 句柄传给 PQclear 时,它会被释放。 + + 此函数返回一个字符串,其中包含产生该 PGresultSQL 语句所影响的行数。此函数只能在执行 SELECTCREATE TABLE ASINSERTUPDATEDELETEMOVEFETCHCOPY 语句之后使用,也可以在对包含 INSERTUPDATEDELETE 语句的预备查询执行 EXECUTE 之后使用。如果产生 PGresult 的是其他命令,PQcmdTuples 将返回空字符串。调用者不应直接释放返回值;当关联的 PGresult 句柄被传给 PQclear 时,返回值会被释放。 + @@ -2622,7 +2651,7 @@ char *PQcmdTuples(PGresult *res); - 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDin libpq。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid。 + 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDlibpq 中的。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid Oid PQoidValue(const PGresult *res); @@ -2634,7 +2663,9 @@ Oid PQoidValue(const PGresult *res); PQoidStatus PQoidStatus - 此函数已弃用,推荐使用PQoidValue,且此函数不是线程安全的。它返回包含插入行 OID 的字符串,而PQoidValue返回 OID 值。 + + 此函数不是线程安全的,现已弃用,推荐改用 PQoidValue。它返回包含插入行 OID 的字符串,而 PQoidValue 返回 OID 值。 + char *PQoidStatus(const PGresult *res); @@ -2650,7 +2681,7 @@ char *PQoidStatus(const PGresult *res); 转义字符串 - in libpq + libpq 中的 @@ -2666,17 +2697,13 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); 为了让一个字符串可用于 SQL 命令,PQescapeLiteral会对它进行转义。 - 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜线)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 + 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜杠)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 PQescapeLiteral执行这种操作。 - PQescapeLiteral返回一个str参数的已被转义版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,PQescapeLiteral会停止在零,该行为更像strncpy)。 - 返回字符串中的所有特殊字符都会被替换,这样它们就能被PostgreSQL字符串字面量解析器正确处理。 - 结果中也会附加一个终止零字节,并包含包围PostgreSQL字符串字面量所需的单引号。 - + PQescapeLiteral 返回 str 参数的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节,PQescapeLiteral 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便 PostgreSQL 字符串字面量解析器正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号包含在结果字符串中。 + 发生错误时,PQescapeLiteral返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -2690,7 +2717,7 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); - 注意,当一个数据值被作为PQexecParams或其兄弟例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 + 注意,当一个数据值被作为PQexecParams或相关例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 @@ -2705,14 +2732,13 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - PQescapeIdentifier 对字符串进行转义,使其可用作 SQL 标识符,例如表名、列名或函数名。当用户提供的标识符可能包含未经转义就不会被 SQL 解析器视为标识符一部分的特殊字符,或包含需要保留大小写的大写字符时,此函数很有用。 + + PQescapeIdentifier 对字符串进行转义,使其可用作 SQL 标识符,例如表名、列名或函数名。当用户提供的标识符可能包含未经转义就不会被 SQL 解析器视为标识符一部分的特殊字符,或包含需要保留大小写的大写字符时,此函数很有用。 + - PQescapeIdentifier返回一个str参数的已被转义为 SQL 标识符的版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存必须用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,PQescapeIdentifier会停止在零,该行为更像strncpy)。 - 返回串中的所有特殊字符都被替换掉,这样它们能被作为一个 SQL 标识符正确地处理。还会加上一个终止零字节。返回串也将被双引号包围。 - + PQescapeIdentifier 返回 str 参数作为 SQL 标识符的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,必须使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节,PQescapeIdentifier 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便正确地作为 SQL 标识符处理。还会添加一个末尾零字节,并用双引号包围返回的字符串。 + 发生错误时,PQescapeIdentifier返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -2721,7 +2747,7 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - 与字符串一样,要阻止 SQL 注入攻击,当从一个不可信的来源接收到 SQL 标识符时,它们必须被转义。 + 与字符串字面量一样,为防止 SQL 注入攻击,从不可信来源接收到的 SQL 标识符必须经过转义。 @@ -2740,18 +2766,12 @@ size_t PQescapeStringConn(PGconn *conn, - PQescapeStringConn转义字符串,它很像PQescapeLiteral。 - 与PQescapeLiteral不一样的是,调用者负责提供一个合适尺寸的缓冲区。 - 此外,PQescapeStringConn不产生必须包围PostgreSQL字符串的单引号。 - 它们应该在结果要插入的 SQL 命令中提供。参数from指向要被转义的串的第一个字符,并且length参数给出了这个串中的字节数。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,PQescapeStringConn会停止在零,该行为更像strncpy)。 - to应当指向一个缓冲区,它至少能容纳length值的两倍再加一个字节,否则该行为是未被定义的。 - 如果tofrom串重叠,行为也是未被定义的。 - + PQescapeStringConn 对字符串字面量进行转义,与 PQescapeLiteral 类似。与 PQescapeLiteral 不同,调用者需要提供大小合适的缓冲区。此外,PQescapeStringConn 不会生成包围 PostgreSQL 字符串字面量所需的单引号;应在包含转义结果的 SQL 命令中提供这些引号。from 参数指向待转义字符串的首字符,length 参数给出该字符串的字节数。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节,PQescapeStringConn 会在该字节处停止;这一行为类似于 strncpy。)to 必须指向一个缓冲区,其容量至少为 length 的两倍加一个字节,否则行为未定义。如果 tofrom 字符串重叠,行为同样未定义。 + - 如果error参数不是NULL,那么成功时*error被设置为零,错误时设置为非零。当前唯一可能的错误情况涉及源串中非法的多字节编码。错误时仍然会产生输出串,但是可以预期服务器将认为它是畸形的并且拒绝它。在发生错误时,一个合适的消息被存储在conn对象中,不管error是不是NULL。 - + 如果 error 参数不是 NULL,则成功时将 *error 设为零,出错时设为非零。目前唯一可能的错误是源字符串中存在无效的多字节编码。出错时仍会生成输出字符串,但预计服务器会因其格式错误而拒绝它。发生错误时,无论 error 是否为 NULL,都会在 conn 对象中保存相应消息。 + PQescapeStringConn返回写到to的字节数,不包括终止的零字节。 @@ -2764,15 +2784,19 @@ size_t PQescapeStringConn(PGconn *conn, - PQescapeString是以下函数的旧版本,现已弃用:PQescapeStringConn。 + PQescapeStringPQescapeStringConn 的旧版本,现已弃用。 size_t PQescapeString (char *to, const char *from, size_t length); - + - PQescapeStringConn 唯一的区别是,PQescapeString 不接受 PGconnerror 参数。因此,它无法根据连接属性(例如字符编码)调整行为,可能给出错误的结果。此外,它也无法报告错误情况。 + + 与 PQescapeStringConn 唯一的区别是,PQescapeString 不接受 PGconnerror 参数。因此,它无法根据连接属性(例如字符编码)调整行为,可能给出错误的结果。此外,它也无法报告错误情况。 + - PQescapeString 可以在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。在其他情形下,它存在安全隐患,应改用 PQescapeStringConn + + PQescapeString 可以在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。在其他情形下,它存在安全隐患,应改用 PQescapeStringConn。 + @@ -2780,7 +2804,9 @@ size_t PQescapeString (char *to, const char *from, size_t length); PQescapeByteaConn PQescapeByteaConn - 对二进制数据进行转义,使其能够在 SQL 命令中用作以下类型的值:bytea。与PQescapeStringConn一样,这仅用于将数据直接插入 SQL 命令字符串的情况。 + + 对二进制数据进行转义,使其能够在 SQL 命令中用作 bytea 类型的值。与 PQescapeStringConn 一样,这仅用于将数据直接插入 SQL 命令字符串的情况。 + unsigned char *PQescapeByteaConn(PGconn *conn, const unsigned char *from, size_t from_length, @@ -2794,10 +2820,12 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - from参数指向要被转义的串的第一个字节,并且from_length参数给出这个二进制串中的字节数(一个终止的零字节是不需要的也是不被计算的)。to_length参数指向一个将保持生成的已转义串长度的变量。这个结果串长度包括结果的终止零字节。 + from 参数指向待转义字符串的首字节,from_length 参数给出该二进制字符串的字节数。(末尾零字节既不需要,也不计入长度。)to_length 参数指向用于保存转义后字符串长度的变量。该结果字符串长度包含结果末尾的零字节。 - PQescapeByteaConn 返回 from 参数所指二进制字符串的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。返回字符串中的所有特殊字符都已替换,以便 PostgreSQL 字符串字面量解析器和 bytea 输入函数正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号不包含在结果字符串中。 + + PQescapeByteaConn 返回 from 参数所指二进制字符串的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。返回字符串中的所有特殊字符都已替换,以便 PostgreSQL 字符串字面量解析器和 bytea 输入函数正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号不包含在结果字符串中。 + 在发生错误时,将返回一个空指针,并且一个合适的错误消息被存储在conn对象中。当前,唯一可能的错误是没有足够的内存用于结果串。 @@ -2810,7 +2838,7 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - PQescapeBytea是以下函数的旧版本,现已弃用:PQescapeByteaConn。 + PQescapeByteaPQescapeByteaConn 的旧版本,现已弃用。 unsigned char *PQescapeBytea(const unsigned char *from, size_t from_length, @@ -2819,9 +2847,7 @@ unsigned char *PQescapeBytea(const unsigned char *from, - 与PQescapeByteaConn的唯一区别是PQescapeBytea不用一个PGconn参数。 - 正因为这样,PQescapeBytea只能在一次只使用一个PostgreSQL连接的客户端程序中安全地使用(在这种情况下它可以在内部找出它需要知道的东西)。 - 如果在有多个数据库连接的程序中使用,它可能给出错误的结果(在那种情况下使用PQescapeByteaConn)。 + 与 PQescapeByteaConn 唯一的区别是,PQescapeBytea 不接受 PGconn 参数。因此,PQescapeBytea 只能在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。如果在使用多个数据库连接的程序中使用,它可能给出错误的结果(此时应使用 PQescapeByteaConn)。 @@ -2887,26 +2913,26 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - PQexec总是收集命令的整个结果,把它缓存在一个单一的PGresult中。虽然这简化了应用的错误处理逻辑,它对于包含很多行的结果并不现实。 - + PQexec 总是收集命令的完整结果,并将其缓存在单个 PGresult 中。这简化了应用程序的错误处理逻辑,但对于包含大量行的结果,可能不切实际。 + - 如果应用程序不希望受到这些限制,可以改用构成PQexec的底层函数:PQsendQueryPQgetResult。此外,还有PQsendQueryParams, - PQsendPrepare, - PQsendQueryPrepared, - PQsendDescribePrepared,以及PQsendDescribePortal,它们可以与PQgetResult配合使用,分别实现以下函数的功能:PQexecParams, - PQprepare, - PQexecPrepared, - PQdescribePrepared,以及PQdescribePortal + + 如果应用程序不希望受到这些限制,可以改用构成 PQexec 的底层函数:PQsendQueryPQgetResult。此外,PQsendQueryParamsPQsendPreparePQsendQueryPreparedPQsendDescribePreparedPQsendDescribePortal 可以与 PQgetResult 配合使用,分别实现 PQexecParamsPQpreparePQexecPreparedPQdescribePreparedPQdescribePortal 的功能。 + PQsendQuery PQsendQuery - 向服务器提交命令,不等待结果。命令发送成功时返回 1,否则返回 0(此时可以使用PQerrorMessage取得更多失败信息)。 + + 向服务器提交命令,不等待结果。命令发送成功时返回 1,否则返回 0(此时可使用 PQerrorMessage 获取更多失败信息)。 + int PQsendQuery(PGconn *conn, const char *command); -成功调用PQsendQuery之后,应调用PQgetResult一次或多次来取得结果。PQsendQuery在同一连接上不能再次调用,直到PQgetResult返回空指针,表明命令已经完成。 + +成功调用 PQsendQuery 后,应调用 PQgetResult 一次或多次来获取结果。在 PQgetResult 返回空指针、表明命令已完成之前,不得在同一连接上再次调用 PQsendQuery。 + @@ -2914,7 +2940,9 @@ int PQsendQuery(PGconn *conn, const char *command); PQsendQueryParams PQsendQueryParams - 向服务器提交命令及独立指定的参数,不等待结果。 + + 向服务器提交命令及独立指定的参数,不等待结果。 + int PQsendQueryParams(PGconn *conn, const char *command, int nParams, @@ -2923,7 +2951,9 @@ int PQsendQueryParams(PGconn *conn, const int *paramLengths, const int *paramFormats, int resultFormat); -该函数等价于PQsendQuery,但查询参数可以与查询字符串分开指定。函数参数的处理方式与PQexecParams相同。与PQexecParams一样,它不能用于协议 2.0 的连接,并且查询字符串中只允许包含一条命令。 + +该函数等价于 PQsendQuery,但查询参数可以与查询字符串分开指定。函数参数的处理方式与 PQexecParams 相同。与 PQexecParams 一样,它不能用于协议 2.0 的连接,并且查询字符串中只允许包含一条命令。 + @@ -2931,13 +2961,17 @@ int PQsendQueryParams(PGconn *conn, PQsendPrepare PQsendPrepare - 发送按给定参数创建预备语句的请求,不等待完成。 + + 发送按给定参数创建预备语句的请求,不等待完成。 + int PQsendPrepare(PGconn *conn, const char *stmtName, const char *query, int nParams, const Oid *paramTypes); -这是PQprepare的异步版本:请求发送成功时返回 1,否则返回 0。调用成功后,再调用PQgetResult,确定服务器是否成功创建了预备语句。函数参数的处理方式与PQprepare相同。与PQprepare一样,它不能用于协议 2.0 的连接。 + +这是 PQprepare 的异步版本:请求发送成功时返回 1,否则返回 0。调用成功后,再调用 PQgetResult,确定服务器是否成功创建了预备语句。函数参数的处理方式与 PQprepare 相同。与 PQprepare 一样,它不能用于协议 2.0 的连接。 + @@ -2945,7 +2979,9 @@ int PQsendPrepare(PGconn *conn, PQsendQueryPrepared PQsendQueryPrepared - 发送使用给定参数执行预备语句的请求,不等待结果。 + + 发送使用给定参数执行预备语句的请求,不等待结果。 + int PQsendQueryPrepared(PGconn *conn, const char *stmtName, int nParams, @@ -2953,7 +2989,9 @@ int PQsendQueryPrepared(PGconn *conn, const int *paramLengths, const int *paramFormats, int resultFormat); -该函数类似于PQsendQueryParams,但通过指定先前已准备好的语句的名称来确定要执行的命令,而不是提供查询字符串。函数参数的处理方式与PQexecPrepared相同。与PQexecPrepared一样,它不能用于协议 2.0 的连接。 + +该函数类似于 PQsendQueryParams,但通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。函数参数的处理方式与 PQexecPrepared 相同。与 PQexecPrepared 一样,它不能用于协议 2.0 的连接。 + @@ -2990,7 +3028,9 @@ PGresult *PQgetResult(PGconn *conn); - 必须反复调用 PQgetResult,直到它返回空指针,表明命令已经完成。(如果当前没有正在执行的命令,调用 PQgetResult 会立即返回空指针。)对于 PQgetResult 返回的每个非空结果,都应使用前文介绍的 PGresult 访问函数处理。使用完毕后,不要忘记调用 PQclear 释放每个结果对象。注意,只有存在正在执行的命令,且所需响应数据尚未被 PQconsumeInput 读取时,PQgetResult 才会阻塞。 + + 必须反复调用 PQgetResult,直到它返回空指针,表明命令已经完成。(如果当前没有正在执行的命令,调用 PQgetResult 会立即返回空指针。)对于 PQgetResult 返回的非空指针,应使用前文介绍的 PGresult 访问函数处理相应结果。使用完毕后,不要忘记调用 PQclear 释放每个结果对象。注意,只有存在正在执行的命令,且所需响应数据尚未被 PQconsumeInput 读取时,PQgetResult 才会阻塞。 + @@ -3001,37 +3041,36 @@ PGresult *PQgetResult(PGconn *conn); - + - 使用PQsendQueryPQgetResult解决了PQexec的一个问题:如果一个命令字符串包含多个SQL命令,这些命令的结果可以被个别地获得(顺便说一句:这样就允许一种简单的重叠处理形式, 客户端可以处理一个命令的结果,而同时服务器可以继续处理同一命令字符串中后面的查询)。 - + 使用 PQsendQueryPQgetResult 可以解决 PQexec 的一个问题:如果命令字符串包含多个 SQL 命令,就能分别获取这些命令的结果。(这也支持一种简单的重叠处理方式:客户端可以处理某条命令的结果,同时服务器继续处理同一命令字符串中后面的查询。) + - 可以被PQsendQueryPQgetResult获得的另一种常常想要的特性是一次从大型结果中检索一行。这会在中讨论。 - + 使用 PQsendQueryPQgetResult 还可以实现另一项常见需求:从大型查询结果中一次读取一行。详见 。 + - 仅仅调用PQgetResult仍会使客户端阻塞,直到服务器完成下一条SQL命令。可以通过正确使用另外两个函数来避免这种情况: + + 仅仅调用 PQgetResult 仍会使客户端阻塞,直到服务器完成下一条 SQL 命令。可以通过正确使用另外两个函数来避免这种情况: + PQconsumeInput PQconsumeInput - 如果有来自服务器的输入可用,则使用之。 + 如果服务器有可读取的输入,则读取这些输入。 int PQconsumeInput(PGconn *conn); - PQconsumeInput通常返回 1 表明没有错误,而返回 0 表明有某种麻烦发生(此时可以用PQerrorMessage)。 - 注意该结果并不表明是否真正收集了任何输入数据。在调用PQconsumeInput之后,应用可以检查PQisBusy和/或PQnotifies来看看它们的状态是否改变。 + PQconsumeInput 通常返回 1,表示没有错误;发生问题时则返回 0(此时可查看 PQerrorMessage)。注意,返回值并不说明是否实际读取了输入数据。调用 PQconsumeInput 后,应用程序可以检查 PQisBusy 和/或 PQnotifies,以确定其状态是否发生变化。 - 即使应用还不准备处理一个结果或通知,PQconsumeInput也可以被调用。 - 这个函数将读取可用的数据并且把它保存在一个缓冲区中,从而导致一个select()的读准备好指示消失。 - 因此应用可以使用PQconsumeInput立即清除select()条件,并且在空闲时再检查结果。 + 即使应用程序尚未准备好处理结果或通知,也可以调用 PQconsumeInput。此函数会读取可用数据并将其保存在缓冲区中,从而清除 select() 的可读就绪指示。因此,应用程序可以用 PQconsumeInput 立即清除 select() 的就绪条件,随后在合适的时候检查结果。 @@ -3051,22 +3090,20 @@ int PQisBusy(PGconn *conn); - + - 一个使用这些函数的典型应用将有一个主循环,在主循环中会使用select()poll()等待所有它必须响应的情况。 - 其中之一将是来自服务器的输入可用,对select()来说意味着PQsocket标识的文件描述符上有可读的数据。 - 当主循环检测到输入准备好时,它将调用PQconsumeInput读取输入。 - 然后它可以调用PQisBusy,如果PQisBusy返回假(0)则接着调用PQgetResult。 - 它还可以调用PQnotifies检测NOTIFY消息(见)。 - + 使用这些函数的典型应用程序会在主循环中通过 select()poll() 等待需要响应的各种条件。其中一个条件是服务器有可读取的输入;对于 select(),这意味着 PQsocket 标识的文件描述符上有可读数据。主循环检测到输入就绪时,应调用 PQconsumeInput 读取输入,然后调用 PQisBusy。如果 PQisBusy 返回假(0),就可以接着调用 PQgetResult。还可以调用 PQnotifies 检测 NOTIFY 消息(见 )。 + 一个使用PQsendQuery/PQgetResult的客户端也可以尝试取消一个正在被服务器处理的命令,见。 但是,不管PQcancel的返回值是什么,应用都必须继续使用PQgetResult进行正常的结果读取序列。一次成功的取消只会导致命令比不取消时更快终止。 - 使用上述函数可以避免在等待数据库服务器输入时阻塞。不过,应用程序仍可能在等待向服务器发送输出时阻塞。这种情况较少见,但发送很长的 SQL 命令或数据值时可能发生。(如果应用程序通过COPY IN发送数据,发生的可能性则大得多。)为了防止这种情况,实现完全非阻塞的数据库操作,可以使用以下附加函数。 + + 使用上述函数可以避免在等待数据库服务器输入时阻塞。不过,应用程序仍可能在等待向服务器发送输出时阻塞。这种情况较少见,但发送很长的 SQL 命令或数据值时可能发生。(如果应用程序通过 COPY IN 发送数据,发生的可能性则大得多。)为了防止这种情况,实现完全非阻塞的数据库操作,可以使用以下附加函数。 + PQsetnonblocking PQsetnonblocking @@ -3113,9 +3150,7 @@ int PQisnonblocking(const PGconn *conn); - 尝试将任何排队的输出数据刷新到服务器。如果成功(或发送队列为空),则返回0; - 如果由于某种原因失败,则返回-1;如果尚未能够发送发送队列中的所有数据(只有在连接为非阻塞时才会发生此情况), - 则返回1。 + 尝试将发送队列中的输出数据发送到服务器。成功(或发送队列为空)时返回 0;因某种原因失败时返回 -1;如果尚未能发送队列中的全部数据,则返回 1(这种情况只可能发生在非阻塞连接上)。 int PQflush(PGconn *conn); @@ -3123,15 +3158,11 @@ int PQflush(PGconn *conn); - + - 在一个非阻塞连接上发送任何命令或者数据之后,要调用PQflush。 - 如果它返回 1,就要等待套接字变成读准备好或写准备好。如果它变为写准备好,应再次调用PQflush。 - 如果它变为读准备好,则应先调用PQconsumeInput,然后再调用PQflush。 - 一直重复直到PQflush返回 0(有必要检查读准备好并且用PQconsumeInput耗尽输入,因为服务器可能阻塞给我们发送数据的尝试,例如 NOTICE 消息,并且在我们读它的数据之前它都不会读我们的数据)。 - 一旦PQflush返回 0,应等待套接字变成读准备好并且接着按照上文所述读取响应。 - + 在非阻塞连接上发送命令或数据后,应调用 PQflush。如果返回 1,就等待套接字变为可读或可写。套接字可写时,再次调用 PQflush;可读时,先调用 PQconsumeInput,再调用 PQflush。重复上述步骤,直到 PQflush 返回 0。(必须检查套接字是否可读,并用 PQconsumeInput 读完输入,因为服务器可能在尝试向客户端发送数据时阻塞,例如发送 NOTICE 消息;在客户端读取这些数据之前,服务器不会读取客户端发送的数据。)当 PQflush 返回 0 后,等待套接字变为可读,再按前述方法读取响应。 + @@ -3259,7 +3290,7 @@ int PQrequestCancel(PGconn *conn); 快速路径接口 - fast path + 快速路径 @@ -3295,21 +3326,22 @@ typedef struct - fnid参数是要被执行的函数的 OID。argsnargs定义了要传递给函数的参数;它们必须匹配已声明的函数参数列表。当一个参数结构体的isint域为真时,u.integer值被以指定长度(必须是 2 或 4 字节)整数的形式发送给服务器;这时候会发生恰当的字节交换。当isint为假时,*u.ptr中指定数量的字节将不做任何处理被发送出去;这些数据必须是服务器 预期的用于该函数参数数据类型的二进制传输的格式(由于历史原因u.ptr被声明为类型int *,其实把它考虑成void *会更好)。result_buf是放置该函数返回值的缓冲区。调用者必须已经分配了足够的空间来存储返回值(这里没有检查!)。实际的结果长度将被放在result_len指向的整数中返回。如果预期结果是 2 或 4 字节整数,把result_is_int设为 1;否则设为 0。把result_is_int设为 1 导致libpq在必要时对值进行交换字节,这样它就作为对客户端机器正确的int值被传输,注意对任一种允许的结果大小都会传递一个 4 字节整数到*result_buf。当result_is_int是 0 时,服务器发送的二进制格式字节将不做修改直接返回(在这种情况下,把result_buf考虑为类型void *更好)。 - + fnid 参数是要执行函数的 OID。argsnargs 指定传给函数的参数,必须与函数声明中的参数列表匹配。参数结构体的 isint 字段为真时,u.integer 值会以指定长度的整数发送到服务器,该长度必须是 2 或 4 字节,并会进行适当的字节序转换。isint 为假时,位于 *u.ptr 的指定数量字节会原样发送;数据必须符合服务器对该函数参数数据类型的二进制传输格式要求。(将 u.ptr 声明为 int * 是历史原因;将其视为 void * 更合适。)result_buf 指向用于存放函数返回值的缓冲区。调用者必须事先分配足够空间来保存返回值,这里不会检查!实际结果长度以字节为单位,返回到 result_len 指向的整数中。如果预期结果是 2 或 4 字节整数,将 result_is_int 设为 1,否则设为 0。将 result_is_int 设为 1 后,libpq 会按需转换字节序,使结果成为适合客户端机器的 int 值;注意,无论是哪种允许的结果大小,传入 *result_buf 的都是 4 字节整数。result_is_int 为 0 时,服务器发送的二进制格式字节串会原样返回。(此时,将 result_buf 视为 void * 更合适。) + - PQfn总是返回一个有效的PGresult指针,成功时状态为PGRES_COMMAND_OK,遇到问题时为PGRES_FATAL_ERROR。 - 在使用结果之前应该检查结果状态。 - 当结果不再使用后,调用者有义务使用PQclear释放PGresult。 - + PQfn 总是返回有效的 PGresult 指针:成功时状态为 PGRES_COMMAND_OK,遇到问题时为 PGRES_FATAL_ERROR。使用结果前应检查其状态。不再需要结果时,调用者负责使用 PQclear 释放 PGresult。 + - 要传递NULL参数到函数,将参数结构体的len字段设置为-1isintu 字段就不相关了。(但这仅适用于使用协议 3.0 及更高版本的连接。) + 要向函数传入 NULL 参数,将该参数结构体的 len 字段设为 -1;此时,isintu 字段便不再相关。(但这仅适用于使用协议 3.0 及更高版本的连接。) + 如果函数返回 NULL,则将 *result_len 设为 -1,而不修改 *result_buf。(这仅适用于使用协议 3.0 及更高版本的连接;在协议 2.0 中,既不修改 *result_len,也不修改 *result_buf。) - 注意,使用此接口时无法处理集合值结果。此外,函数必须是普通函数,不能是聚合函数或窗口函数。 + + 注意,使用此接口时无法处理集合值结果。此外,函数必须是普通函数,不能是聚合函数或窗口函数。 + @@ -3318,7 +3350,7 @@ typedef struct NOTIFY - in libpq + 在 libpq 中 @@ -3327,32 +3359,36 @@ typedef struct libpq应用把LISTENUNLISTENNOTIFY命令作为普通 SQL 命令提交。 - 随后通过调用PQnotifies.PQnotifies来检测NOTIFY消息的到达。 + 随后通过调用PQnotifiesPQnotifies来检测NOTIFY消息的到达。 - 函数PQnotifies从已收到但尚未处理的服务器通知消息列表中返回下一条通知。如果没有待处理的通知,则返回空指针。一旦通知由PQnotifies返回,就被视为已处理,并从通知列表中移除。 + + 函数 PQnotifies 从已收到但尚未处理的服务器通知消息列表中返回下一条通知。没有待处理通知时返回空指针。一旦 PQnotifies 返回一条通知,该通知就被视为已处理,并从通知列表中移除。 + PGnotify *PQnotifies(PGconn *conn); typedef struct pgNotify { - char *relname; /* notification channel name */ - int be_pid; /* process ID of notifying server process */ - char *extra; /* notification payload string */ + char *relname; /* 通知通道名称 */ + int be_pid; /* 发送通知的服务器进程 ID */ + char *extra; /* 通知载荷字符串 */ } PGnotify; -处理完一个PGnotify对象(由PQnotifies返回)后,一定要用PQfreemem释放它。只需释放PGnotify指针;relnameextra字段并非独立分配。(这些字段名称是历史遗留的;尤其是,通道名称与关系名称不必有任何关联。) + +处理完 PQnotifies 返回的 PGnotify 对象后,务必使用 PQfreemem 释放它。只需释放 PGnotify 指针;relnameextra 字段并非独立分配。(这些字段名称是历史遗留的;尤其是,通道名称与关系名称不必有任何关联。) + 给出了一个示例程序展示异步通知的使用。 - PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数吸收的消息。 + PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数读取的消息。 在较早版本的libpq中,及时收到NOTIFY消息的唯一方法是不断提交命令,哪怕是空命令,然后在每次PQexec后检查PQnotifies。 - 虽然这种方法仍然有效,但由于效率过低,现已废弃。 + 虽然这种方法仍然有效,但由于浪费处理能力,现已弃用。 - 当你没有可用的命令提交时,一种更好的检查NOTIFY消息的方法是调用PQconsumeInput,然后检查PQnotifies。 + 当没有需要执行的实际命令时,一种更好的检查NOTIFY消息的方法是调用PQconsumeInput,然后检查PQnotifies。 你可以使用select()等待服务器数据到达,这样在无事可做时就不会浪费CPU资源(参见PQsocket以获得可传给select()的文件描述符)。 注意不管是用PQsendQuery/PQgetResult提交命令还是简单地使用PQexec,这种方法都能正常工作。 不过,你应该记住在每次PQgetResultPQexec之后检查PQnotifies,看看在命令的处理过程中是否有通知到达。 @@ -3365,20 +3401,16 @@ typedef struct pgNotify COPY - with libpq + 使用 libpq - PostgreSQL中的COPY命令有用于libpq的对网络连接读出或者写入的选项。这一节描述的函数允许应用通过提供或者消耗已拷贝的数据来充分利用这个功能。 - + PostgreSQLCOPY 命令提供了选项,可以通过 libpq 使用的网络连接读取或写入数据。本节介绍的函数允许应用程序通过提供或接收复制数据来使用这一能力。 + - 整个处理是应用首先通过PQexec或者一个等效的函数发出 SQL COPY命令。 - 对这个命令的响应(如果命令无误)将是一个状态代码是PGRES_COPY_OUT或 者PGRES_COPY_IN(取决于指定的拷贝方向)的PGresult对象。 - 应用然后就应该使用这一节的函数接收或者传送数据行。在数据传输结束之后,另外一个PGresult对象会被返回以表明传输的成功或者失败。 - 它的状态将是:PGRES_COMMAND_OK表示成功,PGRES_FATAL_ERROR表示发生了一些问题。 - 此时我们可以通过PQexec发出进一步的 SQL 命令(在COPY操作的处理过程中,不能用同一个连接执行其它 SQL 命令)。 - + 整体流程如下:应用程序先通过 PQexec 或等效函数发出 SQL COPY 命令。如果命令没有错误,响应就是一个 PGresult 对象,其状态码为 PGRES_COPY_OUTPGRES_COPY_IN,取决于指定的复制方向。应用程序随后应使用本节函数接收或发送数据行。数据传输完成后,会返回另一个 PGresult 对象,表示传输成功或失败:成功时状态为 PGRES_COMMAND_OK,出现问题时为 PGRES_FATAL_ERROR。此时可以通过 PQexec 继续发出 SQL 命令。(COPY 操作进行期间,不能在同一连接上执行其他 SQL 命令。) + 如果一个COPY命令是通过PQexec在一个可能包含额外命令的字符串中发出的,那么应用在完成COPY序列之后必须继续用PQgetResult取得结果。 @@ -3386,12 +3418,14 @@ typedef struct pgNotify - 这一节的函数应该只在从PQexecPQgetResult获得了PGRES_COPY_OUTPGRES_COPY_IN结果状态后执行。 - + 只有从 PQexecPQgetResult 获得 PGRES_COPY_OUTPGRES_COPY_IN 结果状态后,才应调用本节函数。 + - 一个PGresult对象若带有上述某个状态值,还会携带关于即将开始的COPY操作的附加数据。这些数据可以通过下列函数取得,这些函数也用于查询结果: + + 带有上述某个状态值的 PGresult 对象,还会携带关于即将开始的 COPY 操作的附加数据。这些数据可以通过下列函数获取,这些函数也用于查询结果: + - PQnfieldsPQnfieldswith COPY + PQnfieldsPQnfields用于 COPY @@ -3401,7 +3435,7 @@ typedef struct pgNotify - PQbinaryTuplesPQbinaryTupleswith COPY + PQbinaryTuplesPQbinaryTuples用于 COPY @@ -3412,7 +3446,7 @@ typedef struct pgNotify - PQfformatPQfformatwith COPY + PQfformatPQfformat用于 COPY @@ -3424,7 +3458,7 @@ typedef struct pgNotify - + 这些附加数据值仅在使用协议 3.0 时可用。使用协议 2.0 时,这些函数都返回 0。 @@ -3434,8 +3468,8 @@ typedef struct pgNotify 用于发送<command>COPY</command>数据的函数 - 这些函数用于在COPY FROM STDIN期间发送数据。如果在连接不是COPY_IN状态,调用它们会失败。 - + 这些函数用于在 COPY FROM STDIN 期间发送数据。如果连接不处于 COPY_IN 状态,调用它们会失败。 + @@ -3452,12 +3486,11 @@ int PQputCopyData(PGconn *conn, - 传输指定buffer中长度为nbytesCOPY数据到服务器。 - 如果数据被放在队列中,结果是 1;如果因为缓冲区满而无法被放在队列中(只可能发生在连接是非阻塞模式时),那么结果是零;如果发生错误,结果为 -1(如果返回值为 -1,那么使用PQerrorMessage检索细节。如果值是零,那么等待写准备好然后重试)。 + 将指定 buffer 中长度为 nbytesCOPY 数据传输到服务器。数据成功加入队列时返回 1;因缓冲区已满而无法加入队列时返回零(仅可能发生在非阻塞模式下);发生错误时返回 -1。(返回 -1 时,可用 PQerrorMessage 获取详细信息。返回零时,应等待可写就绪后重试。) - 应用可以把COPY数据流划分成任意方便的大小放到缓冲区中。在发送时,缓冲区载荷的边界没有什么语意。数据流的内容必须匹配COPY命令预期的数据格式;详见。 + 应用程序可以将 COPY 数据流分成任意方便大小的数据块,逐块装入缓冲区。发送时,这些数据块的边界没有语义含义。数据流内容必须符合 COPY 命令预期的数据格式;详见 @@ -3474,13 +3507,16 @@ int PQputCopyEnd(PGconn *conn, - 如果 errormsgNULL,则成功结束 COPY_IN 操作。如果 errormsg 不为 NULL,则强制 COPY 失败,并将 errormsg 指向的字符串用作错误消息。(但不应假定服务器一定会返回这条完全相同的错误消息,因为服务器可能已经因自身原因使 COPY 失败。还要注意,在使用 3.0 之前协议的连接上,强制失败选项不起作用。) + + 如果 errormsgNULL,则成功结束 COPY_IN 操作。如果 errormsg 不为 NULL,则强制 COPY 失败,并将 errormsg 指向的字符串用作错误消息。(但不应假定服务器一定会返回这条完全相同的错误消息,因为服务器可能已经因自身原因使 COPY 失败。还要注意,在使用 3.0 之前协议的连接上,强制失败选项不起作用。) + - 如果终止消息被发送,则结果为 1;在非阻塞模式中,结果为 1 也可能只表示终止消息被成功地放在了发送队列中 (在非阻塞模式中,要确认数据确实被发送出去,你应该接着等待写准备好并且调用PQflush,重复这些直到返回零)。 零表示该函数由于缓冲区满而无法将该终止消息放在队列中,这只会发生在非阻塞模式中(在这种情况下,等待写准备好并且再次尝试PQputCopyEnd调用)。 如果发生系统错误,则返回 -1,可以使用PQerrorMessage检索详情。 + + 终止消息已发送时返回 1;在非阻塞模式下,返回 1 也可能仅表示该消息已成功加入发送队列。(在非阻塞模式下,要确认数据已经发送,应接着等待可写就绪并调用 PQflush,反复执行直到返回零。)返回零表示缓冲区已满,无法将终止消息加入队列;这种情况仅可能发生在非阻塞模式下。(此时,应等待可写就绪,再次调用 PQputCopyEnd。)发生严重错误时返回 -1,可用 PQerrorMessage 获取详细信息。 + - 在成功调用PQputCopyEnd之后,调用PQgetResult获取COPY命令的最终结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 成功调用 PQputCopyEnd 后,调用 PQgetResult 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -3510,24 +3546,19 @@ int PQgetCopyData(PGconn *conn, - 在一个COPY期间尝试从服务器获取另外一行数据。数据总是以每次一个数据行的方式被返回;如果只有一个部分行可用,那么它不会被返回。 - 成功返回一个数据行涉及到分配一块内存来保存该数据。buffer参数必须为非NULL。 - *buffer被设置为指向分配到的内存的指针,或者是在没有返回缓冲区的情况下指向NULL。 - 一个非NULL的结果缓冲区在不需要时必须用PQfreemem释放。 + 在 COPY 期间尝试从服务器获取下一行数据。每次总是返回一个完整数据行;如果只有部分行可用,则不返回。成功返回数据行时,会分配一块内存保存数据。buffer 参数必须为非 NULL*buffer 会被设置为指向所分配的内存;如果没有返回缓冲区,则设为 NULL。非 NULL 的结果缓冲区在不再需要时应使用 PQfreemem 释放。 - 在成功返回一行之后,返回的值就是该数据行里数据的字节数(将是大于零)。 - 被返回的字符串总是以零字节结尾,虽然这可能只是对文本COPY有用。 - 一个零结果表示该COPY仍然在处理中,但是还没有可用的行(只在async为真时才可能)。 - 一个 -1 结果表示COPY已经完成。-2 结果表示发生了错误(参考PQerrorMessage获取原因)。 + 成功返回一行时,返回值是该行的数据字节数,始终大于零。返回的字符串总是以零字节结尾,不过这可能仅对文本 COPY 有用。返回零表示 COPY 仍在进行,但尚无可用行(仅在 async 为真时可能发生)。返回 -1 表示 COPY 已完成;返回 -2 表示发生了错误(可用 PQerrorMessage 查看原因)。 - async 为真(非零)时,PQgetCopyData 不会阻塞等待输入;如果 COPY 仍在进行,但没有完整的行可用,则返回零。(这种情况下,应等待读就绪,随后先调用 PQconsumeInput,再调用 PQgetCopyData。)当 async 为假(零)时,PQgetCopyData 会阻塞,直到有数据可用或操作完成。 + + 当 async 为真(非零)时,PQgetCopyData 不会阻塞等待输入;如果 COPY 仍在进行,但没有完整行可用,则返回零。(此时,应等待读就绪,先调用 PQconsumeInput,再调用 PQgetCopyData。)当 async 为假(零)时,PQgetCopyData 会阻塞,直到数据可用或操作完成。 + - 在PQgetCopyData返回 -1 之后,调用PQgetResult获取COPY命令的最后结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 在 PQgetCopyData 返回 -1 后,调用 PQgetResult 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -3536,11 +3567,11 @@ int PQgetCopyData(PGconn *conn, - 用于<command>COPY</command>的废弃函数 + 用于<command>COPY</command>的过时函数 - 这些函数代表了以前的处理COPY的方法。尽管它们还能用,但是现在已经被废弃,因为它们的错误处理很糟糕、检测结束数据的方法也不方便,并且缺少对二进制或非阻塞传输的支持。 - + 这些函数使用较旧的方式处理 COPY。虽然仍然可用,但由于错误处理欠佳、检测数据结束的方式不便,而且缺少对二进制或非阻塞传输的支持,已被弃用。 + @@ -3548,7 +3579,7 @@ int PQgetCopyData(PGconn *conn, - 读取一个以新行终止的字符行到(由服务器传输) 到一个长度为length的字符串缓冲区。 + 将服务器传来的、以换行符结尾的一行字符读入大小为 length 的字符串缓冲区。 int PQgetline(PGconn *conn, char *buffer, @@ -3557,11 +3588,10 @@ int PQgetline(PGconn *conn, - 这个函数拷贝最多length-1 个字符到该缓冲区中,并且把终止的新行转换成一个零字节。 - PQgetline在输入结束时返回EOF,如果整行都被读取则返回 0,如果缓冲区填满了而还没有遇到结束的新行则返回 1。 - + 此函数最多将 length-1 个字符复制到缓冲区,并将末尾的换行符转换为零字节。PQgetline 在输入结束时返回 EOF,读完一整行时返回 0,缓冲区已满但尚未读到末尾换行符时返回 1。 + - 注意,应用必须检查是否一个新行包含两个字符\.,这表明服务器 已经完成了COPY命令的结果发送。如果应用可能收到超过length-1 字符长的行, 我们就应该确保正确识别\.行(例如,不要把一个长数据行的结束当作一个终止行)。 + 注意,应用程序必须检查新读入的一行是否仅由 \. 两个字符组成,这表示服务器已发送完 COPY 命令的结果。如果可能收到长度超过 length-1 个字符的行,必须确保正确识别 \. 行,例如不能把长数据行的末尾误当作终止行。 @@ -3571,7 +3601,7 @@ int PQgetline(PGconn *conn, - 不阻塞地读取一行COPY数据(由服务器传输)到一个缓冲区中。 + 以非阻塞方式将服务器传来的一行 COPY 数据读入缓冲区。 int PQgetlineAsync(PGconn *conn, char *buffer, @@ -3580,22 +3610,18 @@ int PQgetlineAsync(PGconn *conn, - 这个函数类似于PQgetline,但是可以被用于那些必须异步读取COPY数据的应用, 也就是不阻塞的应用。 - 在发出了COPY命令并得到了PGRES_COPY_OUT响应之后, - 应用应该调用PQconsumeInputPQgetlineAsync直到检测到结束数据的信号。 - + 此函数类似于 PQgetline,但可用于必须异步读取 COPY 数据的应用程序,即读取时不阻塞。发出 COPY 命令并收到 PGRES_COPY_OUT 响应后,应用程序应调用 PQconsumeInputPQgetlineAsync,直到检测到数据结束信号。 + - 不像PQgetline,这个函数负责检测结束数据。 + 与 PQgetline 不同,此函数会负责检测数据结束。 - 在每次调用时,如果libpq的输入缓冲区中有一个完整的数据行可用,PQgetlineAsync都将返回数据。 - 否则,在剩余行到达之前不会返回数据。如果识别到拷贝数据结束的标志,此函数返回 -1;如果没有可用数据则返回 0; - 或者返回一个正数,表示返回的数据字节数。如果返回 -1,调用者下一步必须调用PQendcopy,然后回到正常处理。 + 每次调用时,如果 libpq 的输入缓冲区中有完整数据行,PQgetlineAsync 就会返回数据;否则,要等该行剩余部分到达后才返回数据。识别到复制数据结束标记时返回 -1,没有可用数据时返回 0,否则返回正数,表示返回的数据字节数。返回 -1 后,调用者必须接着调用 PQendcopy,然后恢复正常处理。 - 返回的数据将不超过一个数据行的范围。如果可能,每次将返回一个完整行。但如果调用者提供的缓冲区太小不足以容下服务器发送的行,那么将返回部分行。对于文本数据,这可以通过测试返回的最后一个字节是否\n来检测(在二进制COPY中, 需要对COPY数据格式进行实际的分析,以便做相同的判断)。被返回的字符串不是空结尾的(如果你想增加一个终止空,确保传递一个比实际可用空间少一字节的bufsize)。 + 返回的数据不会跨越数据行边界。只要可能,每次就返回一整行;但如果调用者提供的缓冲区太小,容不下服务器发送的一行,则只返回部分行。对于文本数据,可检查最后返回的字节是否为 \n,以判断是否返回了完整行。(对于二进制 COPY,则必须实际解析 COPY 数据格式才能作出相同判断。)返回的字符串不以零字节结尾。(如果要自行添加末尾的零字节,务必将传入的 bufsize 设置为比实际可用空间少一字节。) @@ -3605,7 +3631,7 @@ int PQgetlineAsync(PGconn *conn, - 向服务器发送一个空终止的字符串。如果 OK 则返回 0;如果不能发送字符串则返回EOF。 + 向服务器发送以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputline(PGconn *conn, const char *string); @@ -3613,16 +3639,13 @@ int PQputline(PGconn *conn, - 一系列PQputline调用发送的COPY数据流和PQgetlineAsync返回的数据具有相同的格式, - 只是应用不需要每次PQputline调用中发送刚好一个数据行;在每次调用中发送多行或者部分行都是可以的。 + 连续调用 PQputline 发送的 COPY 数据流,与 PQgetlineAsync 返回的数据格式相同。不过,应用程序不必在每次 PQputline 调用中恰好发送一个数据行;每次发送部分行或多行也可以。 - 在PostgreSQL协议 3.0 之前,应用必须显式地发送两个字符\.作为最后一行来告知服务器应用程序已完成发送COPY数据。 - 虽然这么做仍然有效,但是它已经被废弃并且\.的特殊含义可能在将来的版本中删除。 - 在发送完实际数据之后, 调用PQendcopy就足够了。 - + 在 PostgreSQL 协议 3.0 之前,应用程序必须显式发送由 \. 两个字符组成的最后一行,告知服务器应用程序已发送完 COPY 数据。虽然这种方式仍然有效,但已被弃用,\. 的特殊含义预计会在未来版本中移除。发送完实际数据后,调用 PQendcopy 即可。 + @@ -3632,7 +3655,7 @@ int PQputline(PGconn *conn, - 向服务器发送一个非空终止的字符串。如果 OK 则返回 0,如果不能发送字符串则返回EOF。 + 向服务器发送不以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputnbytes(PGconn *conn, const char *buffer, @@ -3641,7 +3664,7 @@ int PQputnbytes(PGconn *conn, - 这个函数类似PQputline,除了数据缓冲区不需要以零字节结尾,因为要发送的字节数是直接指定的。在发送二进制数据时使用这个函数。 + 此函数与 PQputline 完全相同,只是直接指定了要发送的字节数,因此数据缓冲区不必以零字节结尾。发送二进制数据时可使用此函数。 @@ -3650,15 +3673,16 @@ int PQputnbytes(PGconn *conn, PQendcopy PQendcopy - 与服务器同步。 + + 与服务器同步。 + int PQendcopy(PGconn *conn); -此函数会等待服务器完成复制。调用时机应为:使用PQputline向服务器发送最后一个字符串后,或者使用PQgetline从服务器收到最后一个字符串后。必须调用此函数,否则服务器与客户端将会不同步。此函数返回后,服务器便准备好接收下一条 SQL 命令。成功完成时返回 0,否则返回非零值。(若返回非零值,可使用PQerrorMessage取得详细信息。) + +此函数会等待服务器完成复制。应在使用 PQputline 向服务器发送最后一个字符串后,或使用 PQgetline 从服务器接收最后一个字符串后调用它。必须调用此函数,否则服务器与客户端会失去同步。函数返回后,服务器便准备好接收下一条 SQL 命令。成功完成时返回 0,否则返回非零值。(返回非零值时,可用 PQerrorMessage 获取详细信息。) + - 在使用PQgetResult时,应用应该通过反复调用PQgetline并且在看到终止行后调用PQendcopy来响应PGRES_COPY_OUT结果。 - 然后它应该返回到PQgetResult循环直到PQgetResult返回一个空指针。 - 类似地,PGRES_COPY_IN结果会用一系列PQputline加上之后的PQendcopy来处理,然后返回到PQgetResult循环。 - 这样的安排将保证嵌入到一系列SQL命令中的COPY命令将被正确执行。 + 使用 PQgetResult 时,收到 PGRES_COPY_OUT 结果后,应用程序应反复调用 PQgetline,并在看到终止行后调用 PQendcopy。随后应回到 PQgetResult 循环,直到 PQgetResult 返回空指针。类似地,收到 PGRES_COPY_IN 结果后,应连续调用 PQputline,再调用 PQendcopy,然后回到 PQgetResult 循环。这样可以保证嵌在一系列 SQL 命令中的 COPY 命令正确执行。 @@ -3677,8 +3701,8 @@ int PQendcopy(PGconn *conn); 控制函数 - 这些函数控制libpq行为各种各样的细节。 - + 这些函数控制 libpq 行为的各种细节。 + @@ -3687,17 +3711,15 @@ int PQendcopy(PGconn *conn); - 返回客户端编码。 + 返回客户端编码。 int PQclientEncoding(const PGconn *conn); - - 请注意,它返回的是编码 ID,而不是一个符号串字符串,如EUC_JP。如果不成功,它会返回 -1。要把一个编码 ID 转换为为一个编码名称,可以用: - +注意,返回的是编码 ID,而不是 EUC_JP 这样的符号字符串。失败时返回 -1。要将编码 ID 转换为编码名称,可以使用: char *pg_encoding_to_char(int encoding_id); - + @@ -3759,16 +3781,16 @@ PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibilit - 启用对客户端/服务器通讯的跟踪,把跟踪信息输出到一个调试文件流中。 + 启用客户端/服务器通信跟踪,将跟踪信息写入调试文件流。 void PQtrace(PGconn *conn, FILE *stream); - + - 在 Windows上,如果libpq库和应用使用了不同的标志编译,那么这个函数调用会导致应用崩溃,因为FILE指针的内部表达是不一样的。特别是多线程/单线程、发布/调试 以及静态/动态标志应该是库和所有使用库的应用都一致。 + 在 Windows 上,如果 libpq 库与应用程序使用不同的标志编译,调用此函数会导致应用程序崩溃,因为 FILE 指针的内部表示不同。具体而言,库与所有使用它的应用程序都应使用相同的多线程/单线程、发布/调试和静态/动态标志。 @@ -3779,11 +3801,12 @@ void PQtrace(PGconn *conn, FILE *stream); PQuntrace PQuntrace - 禁用以下函数启动的跟踪:PQtrace。 + + 禁用由 PQtrace 启动的跟踪。 void PQuntrace(PGconn *conn); - + @@ -3810,11 +3833,8 @@ void PQfreemem(void *ptr); - 释放libpq分配的内存,尤其是PQescapeByteaConn,PQescapeBytea,PQunescapeBytea,和PQnotifies分配的内存。 - 特别重要的是,在微软 Windows 上使用这个函数,而不是free()。 - 这是因为只有 当 DLL 和应用的多线程/单线程、发布/调试以及静态/动态标志相同时,才能在一个 DLL 中分配内存并且在应用中释放它。 - 在非微软 Windows 平台上,这个函数与标准库函数free()相同。 - + 释放 libpq 分配的内存,特别是 PQescapeByteaConnPQescapeByteaPQunescapeByteaPQnotifies 分配的内存。在 Microsoft Windows 上,务必使用此函数,而不是 free()。这是因为只有 DLL 与应用程序使用相同的多线程/单线程、发布/调试和静态/动态标志,才能在 DLL 中分配内存并在应用程序中释放它。在 Microsoft Windows 以外的平台上,此函数与标准库函数 free() 相同。 + @@ -3822,7 +3842,8 @@ void PQfreemem(void *ptr); PQconninfoFree PQconninfoFree - 释放以下函数分配的数据结构:PQconndefaultsPQconninfoParse。 + + 释放PQconndefaultsPQconninfoParse分配的数据结构。 void PQconninfoFree(PQconninfoOption *connOptions); @@ -3866,10 +3887,13 @@ char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, PQencryptPassword PQencryptPassword - 准备经过 md5 加密的PostgreSQL密码。 + + 准备一个PostgreSQL密码的md5加密形式。 + char *PQencryptPassword(const char *passwd, const char *user); - PQencryptPassword是以下函数的旧版本,现已弃用:PQencryptPasswordConn。区别在于PQencryptPassword不需要连接对象,并且md5始终用作加密算法。 + PQencryptPasswordPQencryptPasswordConn的旧版本,现已弃用。其差别是PQencryptPassword不需要连接对象,并且总是用md5作为加密算法。 + @@ -3888,8 +3912,8 @@ PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); 这是libpq内部用于分配并初始化一个空PGresult对象的函数。 如果无法分配内存,此函数返回NULL。 将它导出供外部调用,是因为一些应用需要自行生成结果对象,特别是带有错误状态的对象。 - 如果conn非空,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 - 此外,如果conn非空,连接中注册的所有事件过程也会被复制到PGresult中。 + 如果conn 不为 null,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 + 此外,如果conn 不为 null,连接中注册的所有事件过程也会被复制到PGresult中。 (这些过程不会收到PGEVT_RESULTCREATE调用,但可参见PQfireResultCreateEvents。) 注意,最终应对该对象调用PQclear,就像处理libpq自身返回的PGresult一样。 @@ -3908,16 +3932,16 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); - conn参数被传送给事件过程,但不会被直接使用。如果事件过程不使用它,则会返回NULL。 - + conn 参数会传递给事件过程,但此函数不会直接使用它。如果事件过程不使用此参数,则可以传入 NULL。 + 已经接收到这个对象的PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件过程不会被再次触发。 - 这个函数与PQmakeEmptyPGresult分开的主要原因是在调用事件过程之前创建一个PGresult并且填充它常常是合适的。 - + 此函数与 PQmakeEmptyPGresult 分开的主要原因是,通常适合先创建 PGresult 并填充数据,然后再调用事件过程。 + @@ -3925,10 +3949,12 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); PQcopyResult PQcopyResult - 创建一个PGresult对象的副本。副本与源结果没有任何关联,并且PQclear必须在不再需要该副本时调用。如果函数失败,会返回NULL + + 创建 PGresult 对象的副本。副本与源结果没有任何关联,不再需要副本时必须调用 PQclear。函数失败时返回 NULL。 + PGresult *PQcopyResult(const PGresult *src, int flags); - + 这不是为了制作一个精确的副本。返回的结果总是放在PGRES_TUPLES_OK状态中,并且不复制源中的任何错误消息。 (但是会复制命令状态字符串。)flags参数确定要复制的其他内容。它是几个标志的按位或。 PG_COPYRES_ATTRS指定复制源结果的属性(列定义)。 PG_COPYRES_TUPLES指定复制源结果的元组。(这也意味着复制属性。) PG_COPYRES_NOTICEHOOKS指定复制源结果的通知钩子。 PG_COPYRES_EVENTS指定复制源结果的事件。(但不复制与源相关的任何实例数据。) @@ -3957,18 +3983,15 @@ int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs); - 设置一个PGresult对象的一个元组域值。 + 设置 PGresult 对象中某个元组的字段值。 int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len); - + - 这个函数将自动按需增加结果的内部元组数组。但是,tup_num参数必须小于等于PQntuples,意味着这个函数对元组数组一次只能增加一个元组。 - 但已存在的任意元组中的任意域可以以任意顺序进行调整。如果field_num的一个值已经存在,它会被覆盖。 - 如果len是 -1,或valueNULL, 该域值会被设置为一个 SQL 空值。 - value会被复制到结果的私有存储中,因此函数返回后就不再需要了。如果函数失败,返回值是 0。如果函数成功,返回值会是非 0。 - + 此函数会根据需要自动扩展结果内部的元组数组。不过,tup_num 参数必须小于或等于 PQntuples,也就是说,每次只能向元组数组增加一个元组。已有元组的任何字段都可以按任意顺序修改。如果 field_num 指定的位置已有值,该值会被覆盖。如果 len 为 -1 或 valueNULL,则将该字段设置为 SQL null 值。value 会被复制到结果的私有存储中,因此函数返回后就不再需要它。函数失败时返回零,成功时返回非零值。 + @@ -3985,8 +4008,8 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); - 当res被清除时,这个函数分配的内存也会被释放掉。如果函数失败,返回值是NULL。结果被保证为按照数据的任意类型充分地对齐,正如malloc所作的。 - + 使用此函数分配的所有内存都会在清除 res 时释放。函数失败时返回 NULL。与 malloc 一样,返回的内存保证满足任意数据类型的对齐要求。 + @@ -4002,28 +4025,25 @@ int PQlibVersion(void); - 在运行时,这个函数的结果可以被用来决定在当前已载入的 libpq 版本中特定的功能是否可用。 - 例如,这个函数可以被用来决定哪些选项可以被用于PQconnectdb。 - + 可在运行时根据此函数的结果,判断当前已加载的 libpq 版本是否具有特定功能。例如,可用它判断 PQconnectdb 支持哪些连接选项。 + - 结果通过将库的主版本号乘以10000再加上次版本号形成。例如,版本10.1将被返回为100001,而版本11.0将被返回为110000。 - + 返回值等于库的主版本号乘以 10000 再加上次版本号。例如,版本 10.1 返回 100001,版本 11.0 返回 110000。 + - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。 - 对于那些版本,PQlibVersion为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - + 在主版本 10 之前,PostgreSQL 使用由三个部分组成的版本号,前两个部分共同表示主版本。对于这些版本,PQlibVersion 用两位数字表示每个部分;例如,版本 9.1.5 返回 90105,版本 9.2.0 返回 90200。 + - 因此,出于判断特性兼容性的目的,应用应该将PQlibVersion的结果除以100而不是10000来判断逻辑的主版本号。 - 在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 - + 因此,为了判断功能兼容性,应用程序应将 PQlibVersion 的结果除以 100 而非 10000,得到逻辑上的主版本号。在所有版本系列中,次版本(错误修复版本)之间只有最后两位数字不同。 + - 这个函数出现于PostgreSQL版本 9.1,因此它不能被用来在早期的版本中检测所需的功能,因为调用它将会创建一个对版本9.1及其后版本的链接依赖。 + 此函数从 PostgreSQL 9.1 起提供,因而不能用它检测更早版本是否具有所需功能:调用它会建立对 9.1 或更高版本的链接依赖。 @@ -4037,13 +4057,13 @@ int PQlibVersion(void); 通知处理 - notice processing - in libpq + 通知处理 + 在 libpq 中 - 服务器产生的通知和警告消息不会被查询执行函数返回,因为它们不代表查询失败。它们可以被传递给一个通知处理函数,并且在处理者返回后执行会继续正常进行。默认的处理函数会把消息打印在stderr上,但是应用可以通过提供它自己的处理函数来重载这种行为。 - + 服务器生成的通知和警告消息不由查询执行函数返回,因为它们并不表示查询失败。这些消息会传递给通知处理函数,处理函数返回后,执行正常继续。默认通知处理函数将消息打印到 stderr,应用程序也可以提供自己的处理函数来替换这一行为。 + 由于历史原因,通知处理有两个级别,称为通知接收器和通知处理器。通知接收器的默认行为是格式化通知并且将一个字符串传递给通知处理器来打印。不过,如果一个应用选择提供自己的通知接收器,它通常会忽略通知处理器层并且在通知接收器中完成所有工作。 @@ -4051,10 +4071,10 @@ int PQlibVersion(void); 函数PQsetNoticeReceiver - notice receiver + 通知接收器 PQsetNoticeReceiver为一个连接对象设置或者检查当前的通知接收器。 相似地,PQsetNoticeProcessor - notice processor + 通知处理器 PQsetNoticeProcessor设置或检查当前的通知处理器。 @@ -4077,19 +4097,16 @@ PQsetNoticeProcessor(PGconn *conn, - 当接收到一个服务器产生的或者libpq内部产生的通知或警告消息,通知接收器函数会被调用。 - 该函数会以一种PGRES_NONFATAL_ERROR PGresult的形式接收该消息 - (这允许接收器使用PQresultErrorField抽取个别的域,或者使用PQresultErrorMessage或者PQresultVerboseErrorMessage得到一个完整的预格式化的消息)。 - 被传递给PQsetNoticeReceiver的同一个 void 指针也被传递(必要时,这个指针可以被用来访问应用相关的状态)。 - + 从服务器收到通知或警告消息,或者 libpq 内部生成这类消息时,便会调用通知接收器函数。消息以状态为 PGRES_NONFATAL_ERRORPGresult 对象传给该函数。(接收器可使用 PQresultErrorField 提取单个字段,也可使用 PQresultErrorMessagePQresultVerboseErrorMessage 获取完整的预格式化消息。)传给 PQsetNoticeReceiver 的同一个 void 指针也会传入。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知接收器会简单地抽取消息(使用PQresultErrorMessage)并且将它传递给通知处理器。 - 通知处理器负责处理一个以文本形式给出的通知或警告消息。该消息的字符串文本(包括一个收尾的新行)被传递给通知处理器,外加一个同时被传递给PQsetNoticeProcessor的空指针(必要时,这个指针可以被用来访问应用相关的状态)。 - + 通知处理器负责处理以文本形式提供的通知或警告消息。传给它的参数包括消息字符串(含末尾的换行符),以及先前传给 PQsetNoticeProcessor 的同一个 void 指针。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知处理器很简单: @@ -4103,9 +4120,8 @@ defaultNoticeProcessor(void *arg, const char *message) - 一旦你设定了一个通知接收器或处理器,你应该期待只要PGconn对象或者从它构造出的PGresult对象存在,该函数就可能被调用。 - 在一个PGresult创建时,PGconn的当前通知处理指针被复制到PGresult中,以备类似PQgetvalue的函数使用。 - + 设置通知接收器或处理器后,应当预期:只要 PGconn 对象或由它生成的 PGresult 对象仍存在,就可能调用该函数。创建 PGresult 时,会将 PGconn 当前的通知处理指针复制到 PGresult 中,供 PQgetvalue 等函数在需要时使用。 + @@ -4113,10 +4129,10 @@ defaultNoticeProcessor(void *arg, const char *message) 事件系统 - libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和毁灭。一种主要的使用情况是这允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 + libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和销毁。一个主要用途是允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 - 每个注册的事件处理程序都与两个数据相关联,libpq仅将其视为不透明的void *指针。 有一个透传指针,当事件处理程序与PGconn注册时,应用程序提供。 透传指针在PGconn及其生成的所有PGresult的生命周期内永远不会更改; 因此,如果使用,它必须指向长期存在的数据。 此外,还有一个实例数据指针,在每个PGconnPGresult中一开始都是NULL。 可以使用PQinstanceDataPQsetInstanceDataPQresultInstanceDataPQsetResultInstanceData函数来操作此指针。 请注意,与透传指针不同,PGconn的实例数据不会自动继承到从中创建的PGresultlibpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 —— 这是事件处理程序的责任。 + 每个注册的事件处理程序都与两项数据相关联,libpq仅将其视为不透明的void *指针。 有一个透传指针,由应用程序在向 PGconn 注册事件处理程序时提供。 透传指针在PGconn及其生成的所有PGresult的生命周期内永远不会更改; 因此,如果使用,它必须指向长期存在的数据。 此外,还有一个实例数据指针,在每个PGconnPGresult中一开始都是NULL。 可以使用PQinstanceDataPQsetInstanceDataPQresultInstanceDataPQresultSetInstanceData函数来操作此指针。 请注意,与透传指针不同,PGconn的实例数据不会自动继承到从中创建的PGresultlibpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 — 这是事件处理程序的责任。 事件类型 @@ -4129,7 +4145,7 @@ defaultNoticeProcessor(void *arg, const char *message) PGEVT_REGISTER - 注册事件在PQregisterEventProc被调用时触发。此时最适合初始化事件处理函数可能需要的instanceData。每个连接中的每个事件处理函数只会触发一次注册事件。如果事件处理函数失败,则中止注册。 + 注册事件在PQregisterEventProc被调用时触发。此时最适合初始化事件过程可能需要的instanceData。每个连接中的每个事件过程只会触发一次注册事件。如果事件过程失败,则中止注册。 typedef struct { PGconn *conn; @@ -4141,26 +4157,26 @@ typedef struct PGEVT_CONNRESET - 连接重置事件会在完成以下调用时触发:PQresetPQresetPoll。在这两种情况下,只有重置成功才会触发该事件。如果事件处理函数失败,整个连接重置就会失败;PGconn会被置于CONNECTION_BAD状态,并且PQresetPoll将返回PGRES_POLLING_FAILED。 + 连接重置事件会在完成以下调用时触发:PQresetPQresetPoll。在这两种情况下,只有重置成功才会触发该事件。如果事件过程失败,整个连接重置就会失败;PGconn会被置于CONNECTION_BAD状态,并且PQresetPoll将返回PGRES_POLLING_FAILED typedef struct { PGconn *conn; } PGEventConnReset; -收到PGEVT_CONNRESET事件时,应将evtInfo指针强制转换为PGEventConnReset *。虽然其中的PGconn刚刚被重置,但所有事件数据都保持不变。应利用此事件重置、重新加载或重新查询相关联的instanceData。注意,即使事件处理函数未能处理PGEVT_CONNRESET,它仍会在连接关闭时收到PGEVT_CONNDESTROY事件。 +收到PGEVT_CONNRESET事件时,应将evtInfo指针强制转换为PGEventConnReset *。虽然其中的PGconn刚刚被重置,但所有事件数据都保持不变。应利用此事件重置、重新加载或重新查询相关联的instanceData。注意,即使事件过程未能处理PGEVT_CONNRESET,它仍会在连接关闭时收到PGEVT_CONNDESTROY事件。 PGEVT_CONNDESTROY - 连接销毁事件由以下调用触发:PQfinish。事件处理函数负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 + 连接销毁事件由以下调用触发:PQfinish。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGconn *conn; } PGEventConnDestroy; -收到PGEVT_CONNDESTROY事件时,应将evtInfo指针强制转换为PGEventConnDestroy *。该事件触发于以下函数执行任何其他清理工作之前:PQfinish。事件处理函数的返回值会被忽略,因为无法通过以下函数报告失败:PQfinish。此外,事件处理函数失败不应中止清理不再使用的内存的过程。 +收到PGEVT_CONNDESTROY事件时,应将evtInfo指针强制转换为PGEventConnDestroy *。该事件触发于以下函数执行任何其他清理工作之前:PQfinish。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:PQfinish。此外,事件过程失败不应中止清理不再使用的内存的过程。 @@ -4192,32 +4208,32 @@ typedef struct PGEVT_RESULTCOPY - 结果复制事件会在调用PQcopyResult时触发。只有复制完成后才会触发该事件。只有为源结果成功处理过PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件处理函数,才会收到PGEVT_RESULTCOPY事件。 + 结果复制事件会在调用PQcopyResult时触发。只有复制完成后才会触发该事件。只有为源结果成功处理过PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件过程,才会收到PGEVT_RESULTCOPY事件。 typedef struct { const PGresult *src; PGresult *dest; } PGEventResultCopy; -收到PGEVT_RESULTCOPY事件时,应将evtInfo指针强制转换为PGEventResultCopy *。其中,src结果是复制源,而dest结果是复制目标。可以利用此事件对instanceData进行深复制,因为PQcopyResult无法完成这项工作。如果事件处理函数失败,整个复制操作就会失败,并且dest结果将被清除。返回失败代码时,必须完成所有清理工作,因为不会为目标结果发送PGEVT_RESULTDESTROY事件。 +收到PGEVT_RESULTCOPY事件时,应将evtInfo指针强制转换为PGEventResultCopy *。其中,src结果是复制源,而dest结果是复制目标。可以利用此事件对instanceData进行深复制,因为PQcopyResult无法完成这项工作。如果事件过程失败,整个复制操作就会失败,并且dest结果将被清除。返回失败代码时,必须完成所有清理工作,因为不会为目标结果发送PGEVT_RESULTDESTROY事件。 PGEVT_RESULTDESTROY - 结果销毁事件由以下调用触发:PQclear。事件处理函数负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 + 结果销毁事件由以下调用触发:PQclear。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGresult *result; } PGEventResultDestroy; -收到PGEVT_RESULTDESTROY事件时,应将evtInfo指针强制转换为PGEventResultDestroy *。该事件触发于以下函数执行任何其他清理工作之前:PQclear。事件处理函数的返回值会被忽略,因为无法通过以下函数报告失败:PQclear。此外,事件处理函数失败不应中止清理不再使用的内存的过程。 +收到PGEVT_RESULTDESTROY事件时,应将evtInfo指针强制转换为PGEventResultDestroy *。该事件触发于以下函数执行任何其他清理工作之前:PQclear。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:PQclear。此外,事件过程失败不应中止清理不再使用的内存的过程。 - 事件回调函数 + 事件回调过程 @@ -4225,9 +4241,12 @@ typedef struct - PGEventProc是通过 typedef 定义的事件处理函数指针类型,也就是接收 libpq 事件的用户回调函数的指针类型。事件处理函数的签名必须为 + PGEventProc 是通过 typedef 定义的事件过程指针类型,也就是接收 libpq 事件的用户回调函数的指针类型。事件过程的签名必须为: + int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) -其中,evtId参数指示发生了哪一种PGEVT事件。必须将evtInfo指针强制转换为适当的结构体类型,以获取关于该事件的更多信息。passThrough参数是在注册事件处理函数时传给以下函数的指针:PQregisterEventProc。函数应在成功时返回非零值,在失败时返回零。 + +evtId 参数指示发生了哪一种 PGEVT 事件。必须将 evtInfo 指针强制转换为适当的结构体类型,以获取关于该事件的更多信息。passThrough 参数是在注册事件过程时传给 PQregisterEventProc 的指针。函数应在成功时返回非零值,在失败时返回零。 + 在任何一个PGconn中,一个特定事件过程只能被注册一次。这是因为该过程的地址被用作查找键来标识相关的实例数据。 @@ -4236,8 +4255,8 @@ int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) - 在 Windows 上,函数能够有两个不同的地址:一个对 DLL 之外可见而另一个对 DLL 之内可见。我们应当小心只有其中之一会被用于libpq的事件过程函数,否则将会产生混淆。编写代码的最简单规则是将所有的事件过程声明为static。如果过程的地址必须对它自己的源代码文件之外可见,提供一个单独的函数来返回该地址。 - + 在 Windows 上,函数可能有两个不同的地址:一个在 DLL 外部可见,另一个在 DLL 内部可见。使用 libpq 的事件过程函数时,务必始终使用其中同一个地址,否则会产生混淆。确保代码正常工作的最简单做法,是将事件过程声明为 static。如果需要在过程所在的源文件之外取得其地址,应提供一个单独的函数来返回该地址。 + @@ -4263,7 +4282,7 @@ int PQregisterEventProc(PGconn *conn, PGEventProc proc, - 在每一个你想要接收事件的PGconn上必须注册一个事件过程。和内存不同,没有限制说一个连接上能注册多少个事件过程。如果该函数成功,它会返回一个非零值。如果它失败,则会返回零。 + 对于希望接收其事件的每个 PGconn,都必须注册一次事件过程。一个连接可注册的事件过程数量只受内存限制。函数成功时返回非零值,失败时返回零。 @@ -4303,7 +4322,9 @@ void *PQinstanceData(const PGconn *conn, PGEventProc proc); PQresultSetInstanceData PQresultSetInstanceData - 将结果的instanceData(针对proc)设置为data。成功时返回非零,失败时返回零。(只有当proc未在结果中正确注册时,才可能失败。) + + 将结果中针对 procinstanceData 设置为 data。成功时返回非零值,失败时返回零。(只有当 proc 未在结果中正确注册时,才可能失败。) + int PQresultSetInstanceData(PGresult *res, PGEventProc proc, void *data); @@ -4327,18 +4348,18 @@ void *PQresultInstanceData(const PGresult *res, PGEventProc proc); - 事件实例 + 事件示例 - 这里是一个管理与 libpq 连接和结果相关的私有数据的示例的框架。 - + 下面给出一个示例框架,用于管理与 libpq 连接和结果关联的私有数据。 + -/* The instanceData */ +/* instanceData 数据 */ typedef struct { int n; @@ -4364,8 +4385,8 @@ main(void) return 1; } - /* called once on any connection that should receive events. - * Sends a PGEVT_REGISTER to myEventProc. + /* 在每个需要接收事件的连接上调用一次。 + * 向 myEventProc 发送 PGEVT_REGISTER 事件。 */ if (!PQregisterEventProc(conn, myEventProc, "mydata_proc", NULL)) { @@ -4374,28 +4395,28 @@ main(void) return 1; } - /* conn instanceData is available */ + /* 可以取得 conn 的 instanceData */ data = PQinstanceData(conn, myEventProc); - /* Sends a PGEVT_RESULTCREATE to myEventProc */ + /* 向 myEventProc 发送 PGEVT_RESULTCREATE 事件 */ res = PQexec(conn, "SELECT 1 + 1"); - /* result instanceData is available */ + /* 可以取得结果的 instanceData */ data = PQresultInstanceData(res, myEventProc); - /* If PG_COPYRES_EVENTS is used, sends a PGEVT_RESULTCOPY to myEventProc */ + /* 使用 PG_COPYRES_EVENTS 时,向 myEventProc 发送 PGEVT_RESULTCOPY 事件 */ res_copy = PQcopyResult(res, PG_COPYRES_TUPLES | PG_COPYRES_EVENTS); - /* result instanceData is available if PG_COPYRES_EVENTS was - * used during the PQcopyResult call. + /* 如果调用 PQcopyResult 时使用了 PG_COPYRES_EVENTS, + * 就可以取得结果的 instanceData。 */ data = PQresultInstanceData(res_copy, myEventProc); - /* Both clears send a PGEVT_RESULTDESTROY to myEventProc */ + /* 两次清除操作都会向 myEventProc 发送 PGEVT_RESULTDESTROY 事件 */ PQclear(res); PQclear(res_copy); - /* Sends a PGEVT_CONNDESTROY to myEventProc */ + /* 向 myEventProc 发送 PGEVT_CONNDESTROY 事件 */ PQfinish(conn); return 0; @@ -4411,7 +4432,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventRegister *e = (PGEventRegister *)evtInfo; mydata *data = get_mydata(e->conn); - /* associate app specific data with connection */ + /* 将应用程序特有的数据与连接关联 */ PQsetInstanceData(e->conn, myEventProc, data); break; } @@ -4431,7 +4452,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventConnDestroy *e = (PGEventConnDestroy *)evtInfo; mydata *data = PQinstanceData(e->conn, myEventProc); - /* free instance data because the conn is being destroyed */ + /* 连接正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; @@ -4443,8 +4464,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *conn_data = PQinstanceData(e->conn, myEventProc); mydata *res_data = dup_mydata(conn_data); - /* associate app specific data with result (copy it from conn) */ - PQsetResultInstanceData(e->result, myEventProc, res_data); + /* 将应用程序特有的数据与结果关联(从 conn 复制) */ + PQresultSetInstanceData(e->result, myEventProc, res_data); break; } @@ -4454,8 +4475,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *src_data = PQresultInstanceData(e->src, myEventProc); mydata *dest_data = dup_mydata(src_data); - /* associate app specific data with result (copy it from a result) */ - PQsetResultInstanceData(e->dest, myEventProc, dest_data); + /* 将应用程序特有的数据与结果关联(从另一个结果复制) */ + PQresultSetInstanceData(e->dest, myEventProc, dest_data); break; } @@ -4464,18 +4485,18 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventResultDestroy *e = (PGEventResultDestroy *)evtInfo; mydata *data = PQresultInstanceData(e->result, myEventProc); - /* free instance data because the result is being destroyed */ + /* 结果正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; } - /* unknown event ID, just return TRUE. */ + /* 未知的事件 ID,直接返回 TRUE。 */ default: break; } - return TRUE; /* event processing succeeded */ + return TRUE; /* 事件处理成功 */ } ]]> @@ -4489,7 +4510,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) 环境变量 - 以下环境变量可用于选择连接参数的默认值,供以下函数使用:PQconnectdbPQsetdbLoginPQsetdb,前提是调用代码没有直接指定这些参数的值。例如,这样可以避免在简单的客户端应用程序中硬编码数据库连接信息。 + + 以下环境变量可用于选择连接参数的默认值,供 PQconnectdbPQsetdbLoginPQsetdb 在调用代码未直接指定参数值时使用。例如,这样可以避免在简单的客户端应用程序中硬编码数据库连接信息。 + @@ -4586,9 +4609,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSERVICEFILE - PGSERVICEFILE指定每个用户的连接服务文件的名称 - (参见)。 - 默认为~/.pg_service.conf,或者在Microsoft Windows上为%APPDATA%\postgresql\.pg_service.conf。 + PGSERVICEFILE指定每个用户的连接服务文件的名称(参见)。 + 默认为~/.pg_service.conf,或者在 Microsoft Windows 上为%APPDATA%\postgresql\.pg_service.conf @@ -4633,7 +4655,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGREQUIRESSL的行为与连接参数相同。 - 这个环境变量已被弃用,推荐使用PGSSLMODE变量;设置这两个变量会抑制这个变量的效果。 + 这个环境变量已被弃用,推荐使用PGSSLMODE变量;同时设置这两个变量时,前者不再生效。 @@ -4760,7 +4782,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 以下环境变量可用于指定每个PostgreSQL会话的默认行为。(也可参见命令,了解按用户或按数据库设置默认行为的方法。) + + 以下环境变量可用于指定每个 PostgreSQL 会话的默认行为。(也可参见 命令,了解按用户或按数据库设置默认行为的方法。) + @@ -4787,7 +4811,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGGEQO为遗传查询优化器设置默认模式(等同于SET geqo TO ...)。 - 有关这些环境变量的正确取值,请参见SQL命令 + +有关这些环境变量的正确取值,请参见 SQL 命令 。 + 下面的环境变量决定libpq的内部行为,它们会覆盖编译在程序中的默认值。 @@ -4835,7 +4861,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) (可以复制上面这一行,并在行首加上#,在文件中加入提示注释。)前四个字段中的每一个都可以是字面值,或者是*,后者可以匹配任何内容。将使用与当前连接参数匹配的第一行中的密码字段。(因此,使用通配符时,应将更具体的条目放在前面。)如果条目需要包含:\,请使用\转义该字符。主机名字段首先匹配已指定的host连接参数;否则匹配已指定的hostaddr参数。如果两者都未指定,则查找主机名localhost。在以下情况下也会查找主机名localhost:连接使用 Unix 域套接字,且host参数与libpq的默认套接字目录路径匹配。在备库中,数据库字段为replication时,匹配连接到主库的流复制连接。除此之外,数据库字段的用途有限,因为同一用户在同一数据库集簇的所有数据库中使用相同的密码。 - 在 Unix 系统上,密码文件上的权限必须不允许所有人或组内访问,可以用chmod 0600 ~/.pgpass这样的命令实现。如果权限没有这么严格,该文件将被忽略。在微软 Windows 上,该文件被假定存储在一个安全的目录中,因此不会进行特别的权限检查。 + 在 Unix 系统上,密码文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.pgpass 这样的命令实现。如果权限没有这么严格,该文件将被忽略。在 Microsoft Windows 上,假定该文件存储在安全的目录中,因此不进行特殊的权限检查。 @@ -4857,10 +4883,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 连接服务文件允许 libpq 连接参数与一个单一服务名称关联。 - 那个服务名称可以在一个 libpq 连接字符串里面指定,与其相关的设置将被使用。 - 这允许在不重新编译使用 libpq 的应用的前提下修改连接参数。 - 服务名称也可以被使用PGSERVICE环境变量来指定。 + 连接服务文件允许将 libpq 连接参数与单个服务名称关联。随后可以在 libpq 连接字符串中指定该服务名称,从而使用关联的设置。这样便可以修改连接参数,而无需重新编译使用 libpq 的应用程序。也可以使用 PGSERVICE 环境变量指定服务名称。 @@ -4876,23 +4899,19 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 或者服务文件使用一种INI 文件格式,其中小节名是服务名并且参数是连接参数。 - 列表见。例如: + 两种服务文件均使用 INI 文件 格式,其中配置段名称是服务名称,参数是连接参数;参数列表见 。例如: -# comment +# 注释 [mydb] host=somehost port=5433 user=admin - 在PostgreSQL安装的share/pg_service.conf.sample中提供了一个示例文件。 +PostgreSQL 安装目录中的 share/pg_service.conf.sample 提供了一个示例文件。 - 从服务文件中获取的连接参数与从其他来源获取的参数相结合。 - 服务文件设置覆盖相应的环境变量,然后反过来可以由连接字符串中直接给出的值覆盖。 - 例如,使用上面的服务文件,连接字符串service=mydb port=5434将使用主机somehost,端口5434, - 用户admin,以及由环境变量或内置默认所设置的其他参数。 + 从服务文件中获取的连接参数会与其他来源的参数合并。服务文件中的设置会覆盖相应的环境变量,而连接字符串中直接给出的值又会覆盖服务文件中的设置。例如,使用上述服务文件时,连接字符串 service=mydb port=5434 将使用主机 somehost、端口 5434、用户 admin,以及由环境变量或内置默认值设置的其他参数。 @@ -4935,7 +4954,7 @@ ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase) 你也可以将常规的服务文件条目和 LDAP 查找混合。pg_service.conf中一节的完整示例: -# 只有主机和端口存储在LDAP中,显式指定dbname和user。 +# 仅 host 和 port 存储在 LDAP 中;显式指定 dbname 和 user [customerdb] dbname=customer user=appuser @@ -4960,13 +4979,13 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 服务器证书的客户端验证 + 客户端对服务器证书的验证 - 默认情况下,PostgreSQL将不会执行服务器证书的任何验证。这意味着可以在不被客户端知晓的情况下伪造服务器身份(例如通过修改一个 DNS 记录或者接管服务器的 IP 地址)。为了阻止哄骗,客户端必须能够通过一条信任链验证服务器的身份。信任链可以这样建立:在一台计算机上放置一个根(自签名的)证书机构(CA)的证书并且在另一台计算机上放置一个由根证书签发的叶子证书。还可以使用一种中间证书,它由根证书签发并且可以签发叶子证书。 + 默认情况下,PostgreSQL 不会对服务器证书执行任何验证。这意味着可以在客户端不知情的情况下伪造服务器身份,例如修改 DNS 记录或接管服务器的 IP 地址。要防止身份伪造,客户端必须能够通过信任链验证服务器身份。建立信任链的方法是:在一台计算机上放置根证书机构(CA)的自签名证书,在另一台计算机上放置由根证书签发的叶证书。也可以使用由根证书签发、又用于签发叶证书的中间证书。 - 要让客户端验证服务器的身份,请在客户端放置根证书,并在服务器上放置由该根证书签名的叶证书。要让服务器验证客户端的身份,请在服务器上放置根证书,并在客户端放置由该根证书签名的叶证书。也可以使用一个或多个中间证书(通常与叶证书存储在一起),将叶证书链接到根证书。 + 要让客户端验证服务器的身份,请在客户端放置根证书,并在服务器上放置由该根证书签发的叶证书。要让服务器验证客户端的身份,请在服务器上放置根证书,并在客户端放置由该根证书签发的叶证书。也可以使用一个或多个中间证书(通常与叶证书存储在一起),将叶证书链接到根证书。 建立信任链后,客户端可以通过两种方式验证服务器发送的叶证书。如果参数 sslmode 设为 verify-ca,libpq 会沿证书链检查到存储在客户端上的根证书,以验证服务器是否可信。如果 sslmode 设为 verify-full,libpq 还会验证服务器主机名是否与服务器证书中存储的名称匹配。如果无法验证服务器证书,SSL 连接将失败。在大多数对安全敏感的环境中,建议使用 verify-full @@ -4985,8 +5004,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 为了与 PostgreSQL 的早期版本达到向后兼容,如果存在一个根 CA 文件,sslmode=require的行为将与verify-ca相同,即服务器证书根据 CA 验证。我们鼓励依赖这种行为,并且需要证书验证的应用应该总是使用verify-ca或者verify-full。 - + 为与 PostgreSQL 的早期版本向后兼容,如果存在根 CA 文件,sslmode=require 的行为将与 verify-ca 相同,即根据 CA 验证服务器证书。不建议依赖这种行为;需要证书验证的应用程序应始终使用 verify-caverify-full。 + @@ -4994,38 +5013,26 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 客户端证书 - 如果服务器尝试通过请求客户端的叶证书来验证客户端的身份, - libpq将发送存储在文件 - ~/.postgresql/postgresql.crt中的证书,该文件位于用户的主目录中。 - 证书必须链到服务器信任的根证书。匹配的 - 私钥文件~/.postgresql/postgresql.key也必须存在。 - 在Microsoft Windows上,这些文件的名称分别为 - %APPDATA%\postgresql\postgresql.crt和 - %APPDATA%\postgresql\postgresql.key。 - 证书和密钥文件的位置可以通过连接参数 - sslcertsslkey, - 或通过环境变量PGSSLCERTPGSSLKEY来覆盖。 - + 如果服务器请求客户端的叶证书以验证客户端身份,libpq 将发送用户主目录下 ~/.postgresql/postgresql.crt 文件中存储的证书。这些证书必须通过证书链连接到服务器信任的根证书。还必须存在匹配的私钥文件 ~/.postgresql/postgresql.key。在 Microsoft Windows 上,这两个文件分别名为 %APPDATA%\postgresql\postgresql.crt%APPDATA%\postgresql\postgresql.key。可以通过连接参数 sslcertsslkey,或环境变量 PGSSLCERTPGSSLKEY,覆盖证书和密钥文件的位置。 + - 在Unix系统上,私钥文件的权限必须禁止任何对世界或组的访问;可以通过类似以下命令来实现: - chmod 0600 ~/.postgresql/postgresql.key。 - 或者,该文件可以由root拥有并具有组读取权限(即0640权限)。 - 该设置适用于由操作系统管理证书和密钥文件的安装。然后,libpq的用户应该成为具有对这些证书和密钥文件访问权限的组的成员。 - (在Microsoft Windows上,没有文件权限检查,因为假定%APPDATA%\postgresql目录是安全的。) - + 在 Unix 系统上,私钥文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.postgresql/postgresql.key 这样的命令实现。另一种做法是使文件归 root 所有,并允许组用户读取(即 0640 权限)。这种设置适用于由操作系统管理证书和密钥文件的安装环境。此时,应将 libpq 用户加入有权访问这些证书和密钥文件的组。(在 Microsoft Windows 上,不检查文件权限,因为假定 %APPDATA%\postgresql 目录是安全的。) + - postgresql.crt 中的第一个证书必须是客户端证书,因为它必须与客户端私钥匹配。可以选择在文件后面追加中间证书,这样就无需在服务器的 root.crt 文件中存储中间证书。 + postgresql.crt 中的第一个证书必须是客户端证书,因为它必须与客户端私钥匹配。可以选择在文件后面追加中间证书 — 这样就无需在服务器的 root.crt 文件中存储中间证书。 - 创建证书的指令请参考。 + 有关创建证书的说明,请参见 不同模式中提供的保护 - sslmode参数选择不同的值可以提供不同程度的保护。SSL 可以防范三类攻击: + + sslmode 参数的不同值提供不同级别的保护。SSL 可以防范三类攻击: + 窃听 @@ -5037,31 +5044,33 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 中间人(MITM - 如果一个第三方能对客户端和服务器之间传送的数据进行修改,它就能假装是服务器并且因此能看见并且修改数据,即使这些数据已被加密。然后第三方可以将连接信息和数据转送给原来的服务器,使得它不可能检测到攻击。这样做的通常途径包括 DNS 污染和地址劫持,借此客户端被重定向到一个不同的服务器。还有几种其他的攻击方式能够完成这种攻击。SSL使用证书验证让客户端认证服务器,就可以阻止这种攻击。 - + + 如果第三方能修改客户端与服务器之间传输的数据,就可以冒充服务器,进而查看和修改数据,即使数据已经加密。随后,第三方可以将连接信息和数据转发给原来的服务器,使攻击无法被察觉。常见的手段包括 DNS 污染和地址劫持,从而将客户端引向预期之外的服务器。还有其他几种攻击手段可以达到同样的目的。SSL 使用证书验证,让客户端认证服务器身份,以防范这种攻击。 + - 模仿 + 冒充 - 如果一个第三方能假装是一个授权的客户端,它能够简单地访问它本不能访问的数据。通常这可以由不安全的密码管理所致。SSL使用客户端证书来确保只有持有合法证书的客户端才能访问服务器,这样就能阻止这种攻击。 - + + 如果第三方能冒充获授权的客户端,就能直接访问其无权访问的数据。这通常可能由不安全的密码管理导致。SSL 使用客户端证书,确保只有持有有效证书的客户端才能访问服务器,以防范这种攻击。 + - 对于一个已知受 SSL 保护的连接,在连接建立之前,必须在客户端和服务器两端都配置 SSL。如果只在服务器端配置,客户端在得知服务器要求高安全性之前,可能就已经开始发送敏感信息(例如密码)。在 libpq 中,要确保连接安全,可以把sslmode参数设置为verify-fullverify-ca,并为系统提供一个用于验证的根证书。这类似于使用https URL浏览加密网页。 + 要确保连接安全,必须在建立连接之前,在客户端和服务器两端配置 SSL。如果仅在服务器上配置,客户端可能在得知服务器要求高安全性之前就已发送敏感信息(例如密码)。在 libpq 中,可以将 sslmode 参数设为 verify-fullverify-ca,并向系统提供用于验证的根证书,以确保连接安全。这类似于使用 https URL 进行加密的网页浏览。 - 一旦服务器已经被认证,客户端可以传递敏感数据。这意味着直到这一点,客户端都不需要知道是否证书将被用于认证,这样只需要在服务器配置中指定就比较安全。 + 服务器通过身份认证后,客户端便可以传送敏感数据。这意味着,在此之前,客户端无需知道是否会使用证书进行认证,因此可以安全地仅在服务器配置中指定这一点。 - 所有SSL选项都带来了加密和密钥交换的负荷,因此必须在性能和安全性之间做出平衡。不同sslmode值所保护的风险,以及它们是怎样看待安全性和负荷的。 + 所有 SSL 选项都会产生加密和密钥交换的开销,因此必须在性能与安全性之间作出权衡。 说明了不同 sslmode 值所能防范的风险,以及它们所表达的对安全性和开销的取舍。
@@ -5082,7 +5091,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) disable - 我不关心安全性,并且我不想为加密增加负荷。 + 我不关心安全性,并且我不想为加密增加开销。 @@ -5090,7 +5099,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) allow 可能 - 我不关心安全性,但如果服务器坚持,我将承担加密带来的负荷。 + 我不关心安全性,但如果服务器坚持,我将承担加密带来的开销。 @@ -5098,7 +5107,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) prefer 可能 - 我不关心安全性,但如果服务器支持,我希望承担加密带来的负荷。 + 我不关心加密,但如果服务器支持,我希望承担加密带来的开销。 @@ -5106,7 +5115,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) require - 我想要对数据加密,并且我接受因此带来的负荷。我信任该网络会保证我总是连接到想要连接的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我信任该网络会保证我总是连接到想要连接的服务器。 @@ -5114,7 +5123,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-ca 取决于 CA 策略 - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器。 @@ -5122,7 +5131,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-full - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 @@ -5135,7 +5144,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - sslmode的默认值是prefer。如表中所示,这在安全性的角度来说没有意义,并且它只承诺可能的性能负荷。提供它作为默认值只是为了向后兼容,并且我们不推荐在安全部署中使用它。 + sslmode 的默认值是 prefer。如表所示,从安全角度看,这一设置没有意义;它只会在可能时带来性能开销。将其作为默认值仅出于向后兼容的考虑,不建议在有安全要求的部署中使用。 @@ -5177,8 +5186,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) ~/.postgresql/root.crt - 可信的证书机构 - 检查服务器证书是由一个可信的证书机构签发 + 受信任的证书机构 + 检查服务器证书是由一个受信任的证书机构签发 @@ -5196,9 +5205,9 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) SSL 库初始化 - 如果您的应用程序初始化libssl和/或libcrypto库,并且libpq - 构建时带有SSL支持,您应该调用PQinitOpenSSL告诉libpq - libssl和/或libcrypto库已被您的应用程序初始化,以便 + 如果你的应用程序初始化libssl和/或libcrypto库,并且libpq + 构建时带有SSL支持,你应该调用PQinitOpenSSL告诉libpq + libssl和/或libcrypto库已被你的应用程序初始化,以便 libpq不会再初始化这些库。 @@ -5209,7 +5218,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 允许应用选择要初始化哪个安全性库。 + 允许应用程序选择要初始化的安全库。 void PQinitOpenSSL(int do_ssl, int do_crypto); @@ -5234,7 +5243,7 @@ void PQinitOpenSSL(int do_ssl, int do_crypto); - 允许应用选择要初始化哪个安全性库。 + 允许应用程序选择要初始化的安全库。 void PQinitSSL(int do_ssl); @@ -5259,7 +5268,7 @@ void PQinitSSL(int do_ssl); - 在线程化程序中的行为 + 多线程程序中的行为 线程 @@ -5293,7 +5302,9 @@ int PQisthreadsafe(); PGresult对象在创建后通常是只读的,因此可以在线程之间自由传递。不过,如果你使用中描述的任何会修改PGresult的函数,则需要自行避免对同一个PGresult执行并发操作。 - 已弃用的 PQrequestCancelPQoidStatus 函数不是线程安全的,不应在多线程程序中使用。可以用 PQcancel 替代 PQrequestCancel,用 PQoidValue 替代 PQoidStatus + + 已弃用的函数 PQrequestCancelPQoidStatus 不是线程安全的,不应在多线程程序中使用。PQrequestCancel 可以用 PQcancel 替代;PQoidStatus 可以用 PQoidValue 替代。 + 如果你在应用程序中使用 Kerberos(除了libpq内部之外),则需要在 Kerberos 调用周围加锁,因为 Kerberos 函数不是线程安全的。可参考libpq源代码中的PQregisterThreadLock函数,它提供了一种在libpq与应用程序之间协作加锁的方法。 @@ -5303,7 +5314,7 @@ int PQisthreadsafe(); - 编译 <application>libpq</application> 程序 + 构建 <application>libpq</application> 程序 编译 @@ -5311,16 +5322,16 @@ int PQisthreadsafe(); - 要编译(即编译并且链接)一个使用libpq的程序,你需要做下列所有的事情: + 要构建(即编译和链接)一个使用 libpq 的程序,需要完成以下所有步骤: - 包括libpq-fe.h头文件: + 包含 libpq-fe.h 头文件: #include <libpq-fe.h> - 如果你无法这样做,那么你通常会从你的编译器得到像这样的错误消息: +如果没有这样做,编译器通常会给出类似以下内容的错误消息: foo.c: In function `main': foo.c:34: `PGconn' undeclared (first use in this function) @@ -5329,24 +5340,24 @@ foo.c:54: `CONNECTION_BAD' undeclared (first use in this function) foo.c:68: `PGRES_COMMAND_OK' undeclared (first use in this function) foo.c:95: `PGRES_TUPLES_OK' undeclared (first use in this function) - + - 通过为你的编译器提供-Idirectory选项,向你的编译器指出PostgreSQL头文件安装在哪里(在某些情况下编译器默认将查看该目录,因此你可以忽略这个选项)。例如你的编译命令行可能看起来像: + 向编译器提供 -Idirectory 选项,指定 PostgreSQL 头文件的安装目录。(某些情况下,编译器默认会搜索该目录,此时可以省略这个选项。)例如,编译命令行可以是: cc -c -I/usr/local/pgsql/include testprog.c - 如果你在使用 makefile,那么把该选项加到CPPFLAGS变量中: +如果使用 makefile,请将该选项添加到 CPPFLAGS 变量中: CPPFLAGS += -I/usr/local/pgsql/include - + 如果你的程序可能由其他用户编译,那么你不应该像那样硬编码目录位置。你可以运行工具pg_configpg_configwith libpq在本地系统上找出头文件在哪里: + sortas="libpq">用于 libpq在本地系统上找出头文件在哪里: $ pg_config --includedir /usr/local/include @@ -5354,8 +5365,7 @@ CPPFLAGS += -I/usr/local/pgsql/include - 如果你安装了pkg-configpkg-configwith - libpq,你可以运行: + 如果你安装了pkg-configpkg-config用于 libpq,你可以运行: $ pkg-config --cflags libpq -I/usr/local/include @@ -5364,20 +5374,20 @@ CPPFLAGS += -I/usr/local/pgsql/include - 无法为编译器指定正确的选项将导致一个错误消息,例如: + 未向编译器指定正确的选项将导致类似以下内容的错误消息: testlibpq.c:8:22: libpq-fe.h: No such file or directory - + - 当链接最终的程序时,指定选项-lpq,这样libpq库会被编译进去,也可以用选项-Ldirectory向编译器指出libpq库所在的位置(再次,编译器将默认搜索某些目录)。为了最大的可移植性,将选项放在选项前面。例如: + 链接最终程序时,指定 -lpq 选项以链接 libpq 库,同时指定 -Ldirectory 选项,告知编译器 libpq 库所在的目录。(同样,编译器默认会搜索某些目录。)为获得最大的可移植性,请将 选项放在 选项之前。例如: cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq - + 你也可以使用pg_config找出库目录: @@ -5404,7 +5414,7 @@ testlibpq.o(.text+0x60): undefined reference to `PQsetdbLogin' testlibpq.o(.text+0x71): undefined reference to `PQstatus' testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' - 这意味着你忘了 . + 这意味着你忘记了 /usr/bin/ld: cannot find -lpq @@ -5421,7 +5431,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' 示例程序 - 这些示例和其他示例可以在源代码发布的src/test/examples目录中找到。 + 这些示例和其他示例可在源代码发行包的src/test/examples目录中找到。 @@ -5435,7 +5445,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' * * testlibpq.c * - * Test the C version of libpq, the PostgreSQL frontend library. + * 测试 PostgreSQL 前端库 libpq 的 C 语言版本。 */ #include #include @@ -5459,19 +5469,18 @@ main(int argc, char **argv) j; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "Connection to database failed: %s", @@ -5479,7 +5488,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -5490,19 +5499,17 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Our test case here involves using a cursor, for which we must be inside - * a transaction block. We could do the whole thing with a single - * PQexec() of "select * from pg_database", but that's too trivial to make - * a good example. + * 这里的测试用例使用游标,因此必须处于事务块内。 + * 只需调用一次 PQexec() 执行 "select * from pg_database" 就能完成全部操作, + * 但这太简单了,不足以作为一个好的示例。 */ - /* Start a transaction block */ + /* 开始一个事务块 */ res = PQexec(conn, "BEGIN"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -5513,7 +5520,7 @@ main(int argc, char **argv) PQclear(res); /* - * Fetch rows from pg_database, the system catalog of databases + * 从数据库系统目录 pg_database 中获取行 */ res = PQexec(conn, "DECLARE myportal CURSOR FOR select * from pg_database"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -5532,13 +5539,13 @@ main(int argc, char **argv) exit_nicely(conn); } - /* first, print out the attribute names */ + /* 首先,打印属性名 */ nFields = PQnfields(res); for (i = 0; i < nFields; i++) printf("%-15s", PQfname(res, i)); printf("\n\n"); - /* next, print out the rows */ + /* 接着,打印各行 */ for (i = 0; i < PQntuples(res); i++) { for (j = 0; j < nFields; j++) @@ -5548,15 +5555,15 @@ main(int argc, char **argv) PQclear(res); - /* close the portal ... we don't bother to check for errors ... */ + /* 关闭 portal……这里不再检查错误…… */ res = PQexec(conn, "CLOSE myportal"); PQclear(res); - /* end the transaction */ + /* 结束事务 */ res = PQexec(conn, "END"); PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -5575,15 +5582,15 @@ main(int argc, char **argv) * * * testlibpq2.c - * Test of the asynchronous notification interface + * 测试异步通知接口 * - * Start this program, then from psql in another window do + * 启动此程序,然后在另一个窗口中通过 psql 执行 * NOTIFY TBL2; - * Repeat four times to get this program to exit. + * 重复四次后,此程序便会退出。 * - * Or, if you want to get fancy, try this: - * populate a database with the following commands - * (provided in src/test/examples/testlibpq2.sql): + * 或者,可以尝试更复杂的示例: + * 使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq2.sql 中): * * CREATE SCHEMA TESTLIBPQ2; * SET search_path = TESTLIBPQ2; @@ -5592,7 +5599,7 @@ main(int argc, char **argv) * CREATE RULE r1 AS ON INSERT TO TBL1 DO * (INSERT INTO TBL2 VALUES (new.i); NOTIFY TBL2); * - * Start this program, then from psql do this four times: + * 启动此程序,然后通过 psql 将以下命令执行四次: * * INSERT INTO TESTLIBPQ2.TBL1 VALUES (10); */ @@ -5629,19 +5636,18 @@ main(int argc, char **argv) int nnotifies; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "Connection to database failed: %s", @@ -5649,7 +5655,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -5660,13 +5666,12 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Issue LISTEN command to enable notifications from the rule's NOTIFY. + * 发出 LISTEN 命令,以接收规则中的 NOTIFY 发出的通知。 */ res = PQexec(conn, "LISTEN TBL2"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -5677,14 +5682,13 @@ main(int argc, char **argv) } PQclear(res); - /* Quit after four notifies are received. */ + /* 收到四次通知后退出。 */ nnotifies = 0; while (nnotifies < 4) { /* - * Sleep until something happens on the connection. We use select(2) - * to wait for input, but you could also use poll() or similar - * facilities. + * 休眠,直到连接上有事件发生。这里使用 select(2) 等待输入, + * 也可以使用 poll() 或类似机制。 */ int sock; fd_set input_mask; @@ -5692,7 +5696,7 @@ main(int argc, char **argv) sock = PQsocket(conn); if (sock < 0) - break; /* shouldn't happen */ + break; /* 不应发生 */ FD_ZERO(&input_mask); FD_SET(sock, &input_mask); @@ -5703,7 +5707,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Now check for input */ + /* 现在检查是否有输入 */ PQconsumeInput(conn); while ((notify = PQnotifies(conn)) != NULL) { @@ -5718,7 +5722,7 @@ main(int argc, char **argv) fprintf(stderr, "Done.\n"); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -5737,10 +5741,10 @@ main(int argc, char **argv) * * * testlibpq3.c - * Test out-of-line parameters and binary I/O. + * 测试在 SQL 命令文本之外独立传递的参数和二进制 I/O。 * - * Before running this, populate a database with the following commands - * (provided in src/test/examples/testlibpq3.sql): + * 运行前,使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq3.sql 中): * * CREATE SCHEMA testlibpq3; * SET search_path = testlibpq3; @@ -5748,7 +5752,7 @@ main(int argc, char **argv) * INSERT INTO test1 values (1, 'joe''s place', '\\000\\001\\002\\003\\004'); * INSERT INTO test1 values (2, 'ho there', '\\004\\003\\002\\001\\000'); * - * The expected output is: + * 预期输出为: * * tuple 0: got * i = (4 bytes) 1 @@ -5772,7 +5776,7 @@ main(int argc, char **argv) #include #include "libpq-fe.h" -/* for ntohl/htonl */ +/* 用于 ntohl/htonl */ #include #include @@ -5785,9 +5789,8 @@ exit_nicely(PGconn *conn) } /* - * This function prints a query result that is a binary-format fetch from - * a table defined as in the comment above. We split it out because the - * main() function uses it twice. + * 此函数打印从上面注释所定义的表中以二进制格式获取的查询结果。 + * 由于 main() 会使用它两次,因此将它单独提取成一个函数。 */ static void show_binary_results(PGresult *res) @@ -5798,7 +5801,7 @@ show_binary_results(PGresult *res) t_fnum, b_fnum; - /* Use PQfnumber to avoid assumptions about field order in result */ + /* 使用 PQfnumber,以避免对结果中的字段顺序作出假设 */ i_fnum = PQfnumber(res, "i"); t_fnum = PQfnumber(res, "t"); b_fnum = PQfnumber(res, "b"); @@ -5811,24 +5814,22 @@ show_binary_results(PGresult *res) int blen; int ival; - /* Get the field values (we ignore possibility they are null!) */ + /* 获取字段值(这里忽略它们可能为 null 的情况!) */ iptr = PQgetvalue(res, i, i_fnum); tptr = PQgetvalue(res, i, t_fnum); bptr = PQgetvalue(res, i, b_fnum); /* - * The binary representation of INT4 is in network byte order, which - * we'd better coerce to the local byte order. + * INT4 的二进制表示采用网络字节序,最好将其转换为本机字节序。 */ ival = ntohl(*((uint32_t *) iptr)); /* - * The binary representation of TEXT is, well, text, and since libpq - * was nice enough to append a zero byte to it, it'll work just fine - * as a C string. + * TEXT 的二进制表示就是文本,而 libpq 会在其后追加一个零字节, + * 因此可以直接将其用作 C 字符串。 * - * The binary representation of BYTEA is a bunch of bytes, which could - * include embedded nulls so we have to pay attention to field length. + * BYTEA 的二进制表示是一组字节,其中可能嵌有零字节, + * 因此必须注意字段长度。 */ blen = PQgetlength(res, i, b_fnum); @@ -5856,19 +5857,18 @@ main(int argc, char **argv) uint32_t binaryIntVal; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "Connection to database failed: %s", @@ -5876,7 +5876,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SET search_path = testlibpq3"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -5887,27 +5887,25 @@ main(int argc, char **argv) PQclear(res); /* - * The point of this program is to illustrate use of PQexecParams() with - * out-of-line parameters, as well as binary transmission of data. + * 此程序旨在演示如何使用 PQexecParams() 在 SQL 命令文本之外独立传递参数, + * 以及如何以二进制方式传输数据。 * - * This first example transmits the parameters as text, but receives the - * results in binary format. By using out-of-line parameters we can avoid - * a lot of tedious mucking about with quoting and escaping, even though - * the data is text. Notice how we don't have to do anything special with - * the quote mark in the parameter value. + * 第一个示例以文本形式传输参数,但以二进制格式接收结果。 + * 通过在 SQL 命令文本之外独立传递参数,即使数据是文本,也可以避免 + * 许多繁琐的引号和转义处理。注意,参数值中的引号无需任何特殊处理。 */ - /* Here is our out-of-line parameter value */ + /* 这是在 SQL 命令文本之外独立传递的参数值 */ paramValues[0] = "joe's place"; res = PQexecParams(conn, "SELECT * FROM test1 WHERE t = $1", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, - NULL, /* don't need param lengths since text */ - NULL, /* default to all text params */ - 1); /* ask for binary results */ + NULL, /* 文本参数无需指定长度 */ + NULL, /* 默认所有参数均为文本 */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -5921,31 +5919,29 @@ main(int argc, char **argv) PQclear(res); /* - * In this second example we transmit an integer parameter in binary form, - * and again retrieve the results in binary form. + * 第二个示例以二进制形式传输一个整数参数,并同样以二进制形式获取结果。 * - * Although we tell PQexecParams we are letting the backend deduce - * parameter type, we really force the decision by casting the parameter - * symbol in the query text. This is a good safety measure when sending - * binary parameters. + * 虽然我们告诉 PQexecParams 让后端推断参数类型,但实际上, + * 查询文本中的参数符号经过强制类型转换,因此其类型已经确定。 + * 发送二进制参数时,这是一项良好的安全措施。 */ - /* Convert integer value "2" to network byte order */ + /* 将整数值 "2" 转换为网络字节序 */ binaryIntVal = htonl((uint32_t) 2); - /* Set up parameter arrays for PQexecParams */ + /* 为 PQexecParams 设置参数数组 */ paramValues[0] = (char *) &binaryIntVal; paramLengths[0] = sizeof(binaryIntVal); - paramFormats[0] = 1; /* binary */ + paramFormats[0] = 1; /* 二进制 */ res = PQexecParams(conn, "SELECT * FROM test1 WHERE i = $1::int4", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, paramLengths, paramFormats, - 1); /* ask for binary results */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -5958,7 +5954,7 @@ main(int argc, char **argv) PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; diff --git a/zh/10/lobj.sgml b/zh/10/lobj.sgml index f02b5e8e..3d7fed0a 100644 --- a/zh/10/lobj.sgml +++ b/zh/10/lobj.sgml @@ -3,8 +3,8 @@ 大对象 - large object - BLOBlarge object + 大对象 + BLOB大对象 PostgreSQL提供一种大对象机制,允许以流式方式访问存储在专用大对象结构中的用户数据。在处理大到无法方便地整体操作的数据值时,这种流式访问非常有用。 @@ -19,7 +19,7 @@ TOAST - versus large objects + 与大对象对比 @@ -182,11 +182,11 @@ inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE); int lo_write(PGconn *conn, int fd, const char *buf, size_t len); - 将buf中的len字节(其大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 + 将buf中的len字节(缓冲区大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -203,7 +203,7 @@ int lo_read(PGconn *conn, int fd, char *buf, size_t len); - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -269,7 +269,7 @@ pg_int64 lo_tell64(PGconn *conn, int fd); int lo_truncate(PGconn *conn, int fd, size_t len); - 该函数把大对象描述符fd截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用空字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 + 该函数把大对象描述符fd对应的大对象截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用零字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 @@ -390,16 +390,16 @@ CREATE TABLE image ( raster oid ); -SELECT lo_creat(-1); -- returns OID of new, empty large object +SELECT lo_creat(-1); -- 返回新建的空大对象的 OID -SELECT lo_create(43213); -- attempts to create large object with OID 43213 +SELECT lo_create(43213); -- 尝试创建 OID 为 43213 的大对象 -SELECT lo_unlink(173454); -- deletes large object with OID 173454 +SELECT lo_unlink(173454); -- 删除 OID 为 173454 的大对象 INSERT INTO image (name, raster) VALUES ('beautiful image', lo_import('/etc/motd')); -INSERT INTO image (name, raster) -- same as above, but specify OID to use +INSERT INTO image (name, raster) -- 与上例相同,但指定要使用的 OID VALUES ('beautiful image', lo_import('/etc/motd', 68583)); SELECT lo_export(image.raster, '/tmp/motd') FROM image @@ -407,7 +407,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image - 服务器端 lo_importlo_export 函数的行为与客户端对应函数有很大不同。这两个函数使用数据库拥有者用户的权限,读写服务器文件系统中的文件,因此仅限超级用户使用。相比之下,客户端导入和导出函数使用客户端程序的权限,读写客户端文件系统中的文件。客户端函数不要求超级用户权限。 + 服务器端 lo_importlo_export 函数的行为与客户端对应函数有很大不同。这两个函数使用运行数据库服务器的操作系统用户的权限,读写服务器文件系统中的文件,因此仅限超级用户使用。相比之下,客户端导入和导出函数使用客户端程序的权限,读写客户端文件系统中的文件。客户端函数不要求超级用户权限。 lo_readlo_write的功能也可以通过服务器端调用获得,但服务器端函数名与客户端接口不同,因为它们不包含下划线。必须将这些函数调用为loreadlowrite。 @@ -419,7 +419,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image 示例程序 - 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行版的src/test/examples/testlo.c中找到。 + 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行包的src/test/examples/testlo.c中找到。 @@ -428,13 +428,13 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /*------------------------------------------------------------------------- * * testlo.c - * test using large objects with libpq + * 测试使用 libpq 操作大对象 * * Portions Copyright (c) 1996-2017, PostgreSQL Global Development Group * Portions Copyright (c) 1994, Regents of the University of California * * - * IDENTIFICATION + * 标识 * src/test/examples/testlo.c * *------------------------------------------------------------------------- @@ -454,7 +454,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /* * importFile - - * import file "in_filename" into database as large object "lobjOid" + * 将文件 "in_filename" 作为大对象 "lobjOid" 导入数据库 * */ static Oid @@ -468,16 +468,16 @@ importFile(PGconn *conn, char *filename) int fd; /* - * open the file to be read in + * 打开要读取的文件 */ fd = open(filename, O_RDONLY, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"\n", filename); } /* - * create the large object + * 创建大对象 */ lobjId = lo_creat(conn, INV_READ | INV_WRITE); if (lobjId == 0) @@ -486,7 +486,7 @@ importFile(PGconn *conn, char *filename) lobj_fd = lo_open(conn, lobjId, INV_WRITE); /* - * read in from the Unix file and write to the inversion file + * 从 Unix 文件读取数据并写入大对象 */ while ((nbytes = read(fd, buf, BUFSIZE)) > 0) { @@ -524,7 +524,7 @@ pickout(PGconn *conn, Oid lobjId, int start, int len) fprintf(stderr, ">>> %s", buf); nread += nbytes; if (nbytes <= 0) - break; /* no more data? */ + break; /* 没有更多数据? */ } free(buf); fprintf(stderr, "\n"); @@ -570,7 +570,7 @@ overwrite(PGconn *conn, Oid lobjId, int start, int len) /* * exportFile - - * export large object "lobjOid" to file "out_filename" + * 将大对象 "lobjOid" 导出到文件 "out_filename" * */ static void @@ -583,24 +583,24 @@ exportFile(PGconn *conn, Oid lobjId, char *filename) int fd; /* - * open the large object + * 打开大对象 */ lobj_fd = lo_open(conn, lobjId, INV_READ); if (lobj_fd < 0) fprintf(stderr, "cannot open large object %u", lobjId); /* - * open the file to be written to + * 打开要写入的文件 */ fd = open(filename, O_CREAT | O_WRONLY | O_TRUNC, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"", filename); } /* - * read in from the inversion file and write to the Unix file + * 从大对象读取数据并写入 Unix 文件 */ while ((nbytes = lo_read(conn, lobj_fd, buf, BUFSIZE)) > 0) { @@ -647,11 +647,11 @@ main(int argc, char **argv) out_filename = argv[3]; /* - * set up the connection + * 建立连接 */ conn = PQsetdb(NULL, NULL, NULL, NULL, database); - /* check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "Connection to database failed: %s", @@ -659,7 +659,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) diff --git a/zh/10/pgtrgm.sgml b/zh/10/pgtrgm.sgml index 05f25e43..57366252 100644 --- a/zh/10/pgtrgm.sgml +++ b/zh/10/pgtrgm.sgml @@ -267,11 +267,11 @@ SELECT * FROM test_trgm WHERE t ~ '(foo|bar)'; - 文本搜索集成 + 文本检索集成 与全文索引结合使用时,三字符组匹配是非常有用的工具。 - 尤其是,它有助于识别那些因拼写错误而无法被全文搜索机制直接匹配的输入词。 + 尤其是,它有助于识别那些因拼写错误而无法被全文检索机制直接匹配的输入词。 diff --git a/zh/10/protocol.sgml b/zh/10/protocol.sgml index 0ff3349c..bfc9855f 100644 --- a/zh/10/protocol.sgml +++ b/zh/10/protocol.sgml @@ -33,7 +33,7 @@ - 会话通常由前端选择终止,但在某些情况下也可能由后端强制终止。无论哪种情况,后端在关闭连接前都会回滚所有打开的(未完成的)事务。 + 会话通常由前端选择终止,但在某些情况下也可能由后端强制终止。无论哪种情况,后端关闭连接时,都会在退出前回滚所有打开的(未完成的)事务。 @@ -72,9 +72,7 @@ 整个执行周期包括一个解析步骤,它从文本查询字符串创建预备语句; 一个绑定步骤,它根据预备语句和所需参数值创建 portal; - 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询 - (SELECTSHOW等),可以要求执行步骤只取回 - 有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 + 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询(SELECTSHOW等),可以要求执行步骤只取回有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 @@ -91,8 +89,8 @@ - 文本形式的数值是特定数据类型的输入/输出转换函数生成或接受的任何字符串。在传输形式上,字符串没有末尾空字符;如果前端要想把收到的值当作C字符串处理,那么必须自己加上一个(顺便说一下,文本格式不允许嵌入空字符)。 - + 值的文本表示是相应数据类型的输入/输出转换函数生成和接受的字符串。在传输形式中,值的末尾没有空字符;前端若要将收到的值作为 C 字符串处理,必须自行添加一个。(文本格式也不允许内嵌空字符。) + 整数的二进制表示采用网络字节序(最高有效字节在前)。至于其他数据类型,请查阅文档或源代码了解其二进制表示形式。要注意,复杂数据类型的二进制表示可能会在不同服务器版本之间发生变化;文本格式通常是可移植性更好的选择。 @@ -112,7 +110,7 @@ 启动 - 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,判断该连接在初步上是否可接受,以及是否需要额外的认证。 + 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,初步判断是否接受该连接,以及需要何种额外认证(如果需要)。 @@ -355,7 +353,7 @@ 表示即将返回行作为对SELECTFETCH等查询的响应。 - 此消息的内容描述了行的列布局。这将跟随每个返回给前端的行的DataRow消息。 + 此消息的内容描述了行的列布局。该消息之后,每个返回给前端的行都对应一条 DataRow 消息。 @@ -411,7 +409,7 @@ - SELECT 查询(或其他返回行集的查询,如 EXPLAINSHOW)的响应通常包含 RowDescription、零条或多条 DataRow 消息,以及最后的 CommandComplete。在前端与服务器之间执行 COPY 输入或输出时,会使用 所述的特殊协议。所有其他类型的查询通常只产生一条 CommandComplete 消息。 + SELECT 查询(或其他返回行集的查询,如 EXPLAINSHOW)的响应通常包含 RowDescription、零条或多条 DataRow 消息,以及最后的 CommandComplete。在前端与服务器之间执行 COPY 输入或输出时,会使用 所述的特殊协议。所有其他类型的查询通常只产生一条 CommandComplete 消息。 由于查询字符串可能包含若干条查询(以分号分隔),因此在后端完成整个查询字符串的处理之前,可能会出现多个这样的响应序列。只有在整个字符串处理完毕且后端已准备好接受新的查询字符串时,才会发出 ReadyForQuery 消息。 @@ -434,8 +432,8 @@ - 我们建议的方法是把前端代码写成状态机的风格,它可以在任何时刻接受任何有意义的消息类型,而不是假设消息的序列总是准确。 - + 建议以状态机的方式编写前端,使其能够在任何合理的时机接收相应类型的消息,而不把消息确切顺序的假设写死在代码中。 + @@ -488,11 +486,11 @@ - 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是执行不会导致后端发送 ReadyForQuery 或 RowDescription。 + 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是 Execute 不会导致后端发送 ReadyForQuery 或 RowDescription。 - 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息之一结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 + 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息中的恰好一条结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 @@ -507,7 +505,7 @@ - 除了这些基本的、必须的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 + 除了这些基本的、必需的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 @@ -542,44 +540,38 @@ - 流水线处理 + 管道化 - 流水线处理 + 管道化 协议规范 - 使用扩展查询协议允许流水线处理,这意味着发送一系列查询而无需等待先前的查询完成。 - 这减少了完成一系列操作所需的网络往返次数。然而,用户必须仔细考虑所需的行为,如果其中一步失败, - 因为后续查询已经在传输到服务器的过程中。 - + 扩展查询协议允许管道化,即连续发送一系列查询,而不等待先前查询完成。这减少了完成一组操作所需的网络往返次数。不过,用户必须仔细考虑其中某个步骤失败时所需的行为,因为后续查询已经在发往服务器的途中。 + - 处理这个问题的一种方法是将整个查询系列作为一个事务处理,即将其包装在BEGIN... - COMMIT中。然而,如果希望其中一些命令独立于其他命令提交,这并没有帮助。 - + 处理这个问题的一种方式是让整组查询成为单个事务,即用BEGIN ... COMMIT包围它们。不过,如果希望其中某些命令独立于其他命令提交,这种方式就无法满足要求。 + - 扩展查询协议提供了另一种管理这个问题的方式,即在依赖的步骤之间省略发送同步消息。 - 由于在错误后,后端会跳过命令消息直到找到同步消息,这允许在管道中的后续命令在前面的命令失败时自动跳过,而无需客户端明确地使用BEGINCOMMIT来管理。 - 管道中可以通过同步消息分隔独立可提交的段。 - + 扩展查询协议提供了另一种处理方式,即省略相互依赖的步骤之间的 Sync 消息。发生错误后,后端会跳过命令消息,直到遇到 Sync,因此当前面的命令失败时,管道中的后续命令便会自动跳过,而不必由客户端用BEGINCOMMIT显式管理。管道中可独立提交的各段可以用 Sync 消息分隔。 + 如果客户端没有发出显式的 BEGIN,那么每个 Sync 通常会在前序步骤成功时引发隐式的 COMMIT,失败时引发隐式的 ROLLBACK。不过,少数 DDL 命令(例如 CREATE DATABASE)不能在事务块中执行。如果这类命令在管道中执行,成功时会强制立即提交,以保持数据库一致性。紧随这类命令之后的 Sync 除了返回 ReadyForQuery 外,不产生其他效果。 - 当使用这种方法时,必须通过计算ReadyForQuery消息的数量并等待达到发送的Syncs数量来确定管道的完成。 - 计算命令完成响应是不可靠的,因为其中一些命令可能会被跳过,因此不会产生完成消息。 - + 使用这种方式时,必须统计 ReadyForQuery 消息的数量,并等待该数量达到已发送的 Sync 消息数量,才能确定管道已完成。统计命令完成响应并不可靠,因为某些命令可能未被执行,因而不会产生完成消息。 + 函数调用 - 函数调用子协议允许客户端请求一个对存在于数据库pg_proc系统表中的任意函数的直接调用。客户端必须在该函数上有执行的权限。 - + 函数调用子协议允许客户端请求直接调用数据库pg_proc系统目录中的任意函数。客户端必须具有该函数的执行权限。 + @@ -589,8 +581,8 @@ - 一个函数调用周期是由前端向后端发送一条FunctionCall消息初始化的。然后后端根据函数调用的结果发送一条或者更多响应消息,并且最后是一条ReadyForQuery响应消息。ReadyForQuery通知前端它可以安全地发送一个新的查询或者函数调用了。 - + 函数调用周期由前端向后端发送一条 FunctionCall 消息来启动。后端随后根据函数调用的结果发送一条或多条响应消息,最后发送一条 ReadyForQuery 响应消息。ReadyForQuery 告知前端,可以安全地发送新的查询或函数调用。 + 来自后端的可能的响应消息是: @@ -609,7 +601,7 @@ FunctionCallResponse - 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者集合类型的结果)。 + 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者结果集合)。 @@ -643,7 +635,7 @@ - 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(表示成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 + 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(允许成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 @@ -651,11 +643,11 @@ - 在拷贝入模式下,后端将忽略所收到的Flush和Sync消息。收到任何其他非拷贝消息类型都会造成一个错误,它将导致上面所描述的拷贝入状态中断(Flush和Sync的例外是为了方便客户端库,它们总是在一个Execute消息之后发送Flush和Sync,而不检查被执行的命令是否为一个COPY FROM STDIN)。 - + 后端会忽略在拷贝入模式期间收到的 Flush 和 Sync 消息。收到任何其他非拷贝类型的消息都会构成错误,并按上述方式中止拷贝入状态。(Flush 和 Sync 的例外是为了方便那些总是在 Execute 消息之后发送 Flush 或 Sync、而不检查待执行命令是否为COPY FROM STDIN的客户端库。) + - 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句的时候初始化的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能退出传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 + 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句时启动的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能中止传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 @@ -663,16 +655,16 @@ - 在CopyData消息中间可能会散布有NoticeResponse和ParameterStatus消息。前端必须处理这些情况,并且应该也为异步消息类型(参见)准备好。除此之外,可以将任何除 CopyData 或 CopyDone 以外的消息类型视为拷贝出模式的终止标志。 - + NoticeResponse 和 ParameterStatus 消息可能穿插在 CopyData 消息之间;前端必须处理这些情况,并应准备好处理其他异步消息类型(参见)。除此之外,可以将任何除 CopyData 或 CopyDone 以外的消息类型视为拷贝出模式的终止标志。 + - 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许数据以高速批量方式在客户端与服务器之间双向传输。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见。 + 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许高速批量地向服务器发送数据以及从服务器接收数据。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见 - CopyInResponse、CopyOutResponse和CopyBothResponse消息包括域和格式代码,域告诉前端每行的列数,而格式代码则用于具体每个列(就目前的实现而言,一个给定COPY操作中的所有列都将使用同样的格式,但是消息设计并不做这个假设)。 - + CopyInResponse、CopyOutResponse 和 CopyBothResponse 消息包含一些字段,用于告知前端每行的列数以及每列所使用的格式代码。(在当前实现中,同一次COPY操作的所有列都使用相同格式,但消息设计并不作此假设。) + @@ -699,8 +691,8 @@ - 如果前端发出一个LISTEN命令, 那么无论何时在为同一个通道名NOTIFY时,后端将发送一个NotificationResponse消息(不要和NoticeResponse搞混!)。 - + 如果前端发出LISTEN命令,那么每当针对同一通道名执行NOTIFY命令时,后端都会发送一条 NotificationResponse 消息(不要与 NoticeResponse 混淆)。 + @@ -718,11 +710,11 @@ - 要发出一条取消请求,前端打开一个与服务器的新连接并且发送一条CancelRequest消息, 而不是通常在新连接中经常发送的StartupMessage消息。服务器将处理这个请求然后关闭连接。 出于安全原因,对取消请求消息不做直接的响应。 - + 要发出取消请求,前端会新建到服务器的连接,并发送 CancelRequest 消息,而不是新连接通常发送的 StartupMessage 消息。服务器处理该请求后便会关闭连接。出于安全原因,服务器不会直接回复取消请求消息。 + - 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的关键数据(PID和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则退出当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 + 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的密钥数据(PID 和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则中止当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 @@ -730,7 +722,7 @@ - 这么做是对安全性和有效性通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 + 这么做是对安全性和效率通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 @@ -750,11 +742,11 @@ - 其他终止场景来自各种故障,例如任一端发生内核转储、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 + 其他终止场景来自各种故障,例如任一端发生 core dump、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 - 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果很可能在得知断开之前被提交。 + 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果可能在发现连接断开之前被提交。 @@ -770,12 +762,16 @@ 前端还应准备好处理服务器对 SSLRequest 返回的 ErrorMessage 响应。只有当服务器版本早于 PostgreSQL 引入 SSL 支持时,才会发生这种情况。(这样的服务器已经非常古老,现实中可能已不存在。)此时必须关闭连接,但前端可以选择建立一个新连接,并在不请求 SSL 的情况下继续通信。 - 当可以执行 SSL 加密时,服务器预计仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给他们的 SSL 库,要么在发现他们已经读取到额外的字节时将其视为协议违规。 + 当可以执行 SSL 加密时,服务器应仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给所用的 SSL 库,要么在发现已经读取到额外的字节时将其视为协议违规。 - 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 SSLRequest。 + + 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 SSLRequest。 + - 虽然协议本身没有提供让服务器强制使用 SSL 加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + + 虽然协议本身没有提供让服务器强制使用SSL加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + @@ -797,24 +793,21 @@ - 客户端从列表中选择一个支持的机制,并向服务器发送一个SASLInitialResponse消息。 - 该消息包括所选机制的名称,以及如果所选机制使用的话,还包括一个可选的初始客户端响应。 - + 客户端从列表中选择一种受支持的机制,并向服务器发送 SASLInitialResponse 消息。消息包含所选机制的名称;如果该机制使用初始客户端响应,消息还可以包含这一可选响应。 + - 一个或多个服务器挑战和客户端响应消息将随后而来。每个服务器挑战都是在一个 - AuthenticationSASLContinue 消息中发送的,随后是客户端在一个 SASLResponse - 消息中的响应。这些消息的具体内容是特定于机制的。 - + 随后会进行一轮或多轮服务器挑战和客户端响应。每次服务器挑战都通过 AuthenticationSASLContinue 消息发送,随后客户端通过 SASLResponse 消息响应。消息的具体内容取决于所用机制。 + - 最后,当认证交换成功完成时,服务器会发送可选的 AuthenticationSASLFinal 消息,随后立即发送 AuthenticationOk。AuthenticationSASLFinal 包含机制特定的附加数据;若该机制不需要完成时附加数据,则不会发送 AuthenticationSASLFinal。 - + 最后,认证交换成功完成时,服务器会发送 AuthenticationSASLFinal 消息,紧接着发送 AuthenticationOk 消息。AuthenticationSASLFinal 包含从服务器发给客户端的附加数据,其具体内容取决于所选认证机制。如果该认证机制不使用在完成时发送的附加数据,则不会发送 AuthenticationSASLFinal 消息。 + @@ -834,13 +827,8 @@ - SCRAM规范规定密码也必须是UTF-8编码,并且使用SASLprep算法处理。 - 然而,PostgreSQL不要求密码必须使用UTF-8编码。 - 当用户设置密码时,无论实际使用的编码是什么,都会像使用UTF-8一样使用SASLprep进行处理。 - 但是,如果密码不是合法的UTF-8字节序列,或者包含SASLprep算法禁止的UTF-8字节序列, - 则会使用原始密码而不进行SASLprep处理,而不是抛出错误。这样可以在密码为UTF-8时对其进行规范化, - 但仍允许使用非UTF-8密码,并且不需要系统知道密码使用的编码方式。 - + SCRAM 规范规定密码也必须采用 UTF-8 编码,并通过SASLprep算法处理。不过,PostgreSQL并不要求密码使用 UTF-8。设置用户密码时,无论实际采用何种编码,都会将其视作 UTF-8 并用 SASLprep 处理。但是,如果密码不是合法的 UTF-8 字节序列,或者包含 SASLprep 算法禁止的 UTF-8 字节序列,就会直接使用未经 SASLprep 处理的原始密码,而不抛出错误。这样既能对 UTF-8 密码进行规范化,又允许使用非 UTF-8 密码,而且不要求系统知道密码采用何种编码。 + 尚未实现通道绑定 @@ -880,17 +868,23 @@ 流复制协议 要发起流式复制,前端在启动消息中发送 replication 参数。布尔值 true 告知后端进入 walsender 模式,在该模式下可以发出一小组复制命令,而不是 SQL 语句。walsender 模式只能使用简单查询协议。启用 后,复制命令会记录到服务器日志中。传入值 database 会指示 walsender 连接到 dbname 参数指定的数据库,从而允许此连接用于从该数据库进行逻辑复制。 -为了测试复制命令,可以通过psql或其他使用libpq的工具建立复制连接,连接字符串中应包含replication选项,例如: + + 为了测试复制命令,可以通过 psql 或其他使用 libpq 的工具建立复制连接,连接字符串中应包含 replication 选项,例如: + psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" -不过,通常更有用的做法是使用(用于物理复制)或(用于逻辑复制)。 + +不过,通常更有用的做法是使用 (用于物理复制)或 (用于逻辑复制)。 + walsender 模式接受以下命令: IDENTIFY_SYSTEM - 识别系统 + IDENTIFY_SYSTEM - 请求服务器标识自身。服务器返回一个只有一行的结果集,包含四个字段: + + 请求服务器标识自身。服务器会返回一个包含四个字段的单行结果集: + @@ -899,7 +893,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" systemid (text) - 标识数据库集簇的唯一系统标识符。可用于检查初始化备库的基础备份是否来自同一个数据库集簇。 + + 用于标识该集簇的唯一系统标识符。它可用于检查初始化备库所用的基础备份是否来自同一个集簇。 + @@ -924,7 +920,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" dbname (text) - 所连接的数据库,或 null。 + + 当前连接到的数据库,或为 null。 + @@ -983,7 +981,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" content (bytea) - 时间线历史文件的内容。 + + 时间线历史文件的内容。 + @@ -1013,7 +1013,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" output_plugin - 用于逻辑解码的输出插件名称(参见 )。 + + 用于逻辑解码的输出插件的名称(参见)。 + @@ -1088,22 +1090,16 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" START_REPLICATION [ SLOT slot_name ] [ PHYSICAL ] XXX/XXX [ TIMELINE tli ] - 开始复制 + START_REPLICATION - 指示服务器开始流式传输WAL,从WAL位置XXX/XXX开始。 - 如果指定了TIMELINE选项,则流式传输将从时间线tli开始; - 否则,将选择服务器当前的时间线。如果请求的WAL部分已经被回收,服务器可能会回复错误。 - 成功时,服务器将用CopyBothResponse消息回复,然后开始向前端流式传输WAL。 - + 指示服务器从 WAL 位置 XXX/XXX 开始流式传输 WAL。如果指定了 TIMELINE 选项,则从时间线 tli 开始传输;否则选择服务器当前的时间线。服务器可以返回错误,例如请求的 WAL 部分已被回收时。成功时,服务器返回 CopyBothResponse 消息,然后开始向前端流式传输 WAL。 + - 如果通过slot_name提供了复制槽名称, - 那么在复制进行期间会更新该复制槽,以便服务器知道哪些 WAL 段, - 以及在启用了 hot_standby_feedback 时,哪些事务 - 仍然被备库所需要。 - + 如果通过 slot_name 提供了复制槽名称,该复制槽会随着复制的进行而更新,使服务器知道备库仍需要哪些 WAL 段,以及在启用 hot_standby_feedback 时仍需要哪些事务。 + 如果客户端请求的时间线不是最新时间线,但属于服务器的历史,服务器会从请求的起点开始,流式传输该时间线上的所有 WAL,直到服务器切换到另一条时间线的位置。如果客户端请求的流式传输起点恰好位于旧时间线的末尾,服务器会立即返回 CommandComplete,而不进入 COPY 模式。 @@ -1354,7 +1350,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" DROP_REPLICATION_SLOT slot_name WAIT - 删除复制槽 + DROP_REPLICATION_SLOT 删除复制槽,释放任何保留的服务器端资源。如果该槽是逻辑槽,且创建它的数据库与 walsender 当前连接的数据库不同,则此命令失败。 @@ -1396,9 +1392,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 设置备份的标签。如果未指定,则将使用base backup作为备份标签。 - 标签的引号使用规则与打开的标准SQL字符串相同。 - + 设置备份标签。如果未指定,则使用 base backup 作为备份标签。标签的引号规则与启用 时的标准 SQL 字符串相同。 + @@ -1491,7 +1486,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" size (int8) - 如果请求了进度报告,则为表空间的大致大小;否则为空值。 + + 如果请求了进度报告,则为表空间的大致大小;否则为 null。 + @@ -1545,7 +1542,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 逻辑复制协议 + 逻辑流复制协议 本节介绍逻辑复制协议,它是一种以复制命令START_REPLICATION @@ -1554,7 +1551,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 逻辑复制协议构建在物理流复制协议的底层机制之上。 + 逻辑流复制协议构建在物理流复制协议的基本机制之上。 @@ -1609,7 +1606,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 逻辑复制协议逐个发送事务。这意味着,一对 Begin 和 Commit 消息之间的所有消息都属于同一个事务。 - 每个被发送的事务都包含零条或多条 DML 消息(插入、更新、删除)。在级联场景下,它还会包含 Origin 消息。Origin 消息表示该事务产生于另一个复制节点。由于逻辑复制协议中的复制节点可以是任意实现,因此唯一标识符就是该源头的名称。下游是否以及如何处理这一信息,由其自行决定。Origin 消息总是在事务中的任何 DML 消息之前发送。 + 每个发送的事务都包含零条或多条 DML 消息(Insert、Update、Delete)。在级联配置中,还可能包含 Origin 消息。Origin 消息表示该事务源自另一个复制节点。由于逻辑复制协议中的复制节点几乎可以是任何实现,因此唯一的标识符就是复制源的名称。下游负责按需处理这一信息(如果需要处理)。Origin 消息总是在事务中的任何 DML 消息之前发送。 @@ -1674,9 +1671,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 对后端返回的字符串长度,没有预定义的限制。 - 前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。 - 如果做不到这一点,就应读取完整字符串,并丢弃不适合固定大小缓冲区的尾随字符。 + 后端返回的字符串长度没有预定义的限制。前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。如果做不到这一点,就应读取完整字符串,并丢弃固定大小的缓冲区容纳不下的尾随字符。 @@ -1701,8 +1696,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 消息格式 - 本节描述每条消息的详细格式。每条消息都标记了可由前端(F)、后端(B)或双方(F&B)发送。 - 请注意,虽然每条消息开头都带有字节计数,但大多数消息格式都定义为无需参考该计数也能确定消息边界。这一设计最初是出于历史原因(早期已废弃的协议 v2 没有显式长度字段),同时也有助于有效性校验。 + 本节描述每条消息的详细格式。每条消息都标明它可以由前端(F)、后端(B)或双方(F & B)发送。注意,虽然每条消息开头都有字节计数,但消息格式的定义使得无需参考该计数也能确定消息的结束位置。这有助于检查消息的有效性。(CopyData 消息是例外,因为它构成数据流的一部分,任何单条 CopyData 消息的内容都无法独立解释。) @@ -1723,7 +1717,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -1754,7 +1748,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -1784,7 +1778,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -1814,7 +1808,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(12) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -1851,7 +1845,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -1882,7 +1876,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -1913,7 +1907,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -1944,7 +1938,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -1981,7 +1975,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2019,7 +2013,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2056,7 +2050,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2093,7 +2087,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(12) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2130,7 +2124,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2148,13 +2142,13 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int16 -后续参数格式码的数量(下文以 C 表示)。可以为零,表示没有参数,或者所有参数都使用默认格式(文本);也可以为一,此时指定的格式码应用于所有参数;还可以等于实际参数数量。 +后续参数格式代码的数量(下文以 C 表示)。可以为零,表示没有参数,或者所有参数都使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有参数;还可以等于实际参数数量。 Int16[C] -参数格式码。目前每个格式码必须为零(文本)或一(二进制)。 +参数格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -2173,20 +2167,20 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byten -参数值,格式由对应的格式码指明。n 为上述长度。 +参数值,格式由对应的格式代码指明。n 为上述长度。 最后一个参数之后是以下字段: Int16 -后续结果列格式码的数量(下文以 R 表示)。可以为零,表示没有结果列,或者所有结果列都应使用默认格式(文本);也可以为一,此时指定的格式码应用于所有结果列(如果有);还可以等于查询实际的结果列数量。 +后续结果列格式代码的数量(下文以 R 表示)。可以为零,表示没有结果列,或者所有结果列都应使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有结果列(如果有);还可以等于查询实际的结果列数量。 Int16[R] -结果列格式码。目前每个格式码必须为零(文本)或一(二进制)。 +结果列格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -2210,7 +2204,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2234,7 +2228,7 @@ CancelRequest (F) - 消息内容的长度,以字节为单位,包括此长度字段本身。 + 消息内容的长度(以字节为单位),包括其自身。 @@ -2290,7 +2284,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2326,7 +2320,7 @@ CancelRequest (F) Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2351,7 +2345,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2415,7 +2409,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2452,7 +2446,7 @@ CancelRequest (F) Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2481,7 +2475,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2510,13 +2504,13 @@ CancelRequest (F) Byte1('G') -标识消息为开始复制输入的响应。前端此时必须发送复制输入数据(如果尚未准备好,应发送 CopyFail 消息)。 +将该消息标识为开始 COPY 输入的响应。前端此时必须发送 COPY 输入数据(如果尚未准备好,应发送 CopyFail 消息)。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2565,13 +2559,13 @@ CancelRequest (F) Byte1('H') -标识消息为开始复制输出的响应。该消息之后会发送复制输出数据。 +将该消息标识为开始 COPY 输出的响应。此消息之后会发送 COPY 输出数据。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2620,13 +2614,13 @@ CancelRequest (F) Byte1('W') -标识消息为开始双向复制的响应。此消息仅用于流复制。 +将该消息标识为开始双向 COPY 的响应。此消息仅用于流复制。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2682,7 +2676,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2697,7 +2691,7 @@ CancelRequest (F) Int32 -列值的长度,以字节为单位(不包括本长度字段自身)。可以为零。特殊值 -1 表示列值为 NULL,此时后面没有值字节。 +列值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 列值。为 NULL 时,后面不再有值的字节。 @@ -2728,14 +2722,14 @@ CancelRequest (F) - 标识消息为描述命令。 + 将该消息标识为 Describe 命令。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2778,7 +2772,7 @@ CancelRequest (F) Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2807,7 +2801,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -2846,14 +2840,14 @@ CancelRequest (F) - 标识消息为一个执行命令。 + 将该消息标识为 Execute 命令。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2888,14 +2882,14 @@ CancelRequest (F) - 将消息标识为Flush命令。 + 将该消息标识为 Flush 命令。 Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2924,7 +2918,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2957,7 +2951,7 @@ CancelRequest (F) Int32 -参数值的长度,以字节为单位(不包括本长度字段自身)。可以为零。特殊值 -1 表示参数值为 NULL,此时后面没有值字节。 +参数值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 参数值。为 NULL 时,后面不再有值的字节。 @@ -3002,13 +2996,13 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 Int32 -函数结果值的长度,以字节为单位(不包括本长度字段自身)。可以为零。特殊值 -1 表示函数结果为 NULL,此时后面没有值字节。 +函数结果值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 函数结果。为 NULL 时,后面不再有值的字节。 @@ -3047,7 +3041,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3082,7 +3076,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3130,7 +3124,7 @@ CancelRequest (F) Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3159,7 +3153,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -3205,7 +3199,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3223,7 +3217,7 @@ CancelRequest (F) String -通知进程传来的载荷字符串。 +通知进程传来的有效载荷字符串。 @@ -3252,7 +3246,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3295,7 +3289,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3328,14 +3322,14 @@ CancelRequest (F) - 将消息标识为解析命令。 + 将该消息标识为 Parse 命令。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3384,14 +3378,14 @@ CancelRequest (F) - 将消息标识为解析完成指示器。 + 将该消息标识为 Parse 完成指示。 Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3421,7 +3415,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3450,15 +3444,14 @@ CancelRequest (F) - 标识消息为 portal 挂起指示器。 - 请注意,仅当执行消息的行数限制达到时才会出现此消息。 + 将该消息标识为 portal 挂起指示。注意,仅当达到 Execute 消息指定的行数限制时,才会出现此消息。 Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3487,7 +3480,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3524,7 +3517,7 @@ CancelRequest (F) Int32(5) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3563,7 +3556,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3622,7 +3615,7 @@ CancelRequest (F) Int16 -字段所使用的格式代码。目前为零(文本)或一(二进制)。对于 Describe 的语句变体所返回的 RowDescription,格式代码尚未确定,始终为零。 +字段所使用的格式代码。目前为零(文本)或一(二进制)。对于 Describe 针对预备语句的变体所返回的 RowDescription,格式代码尚未确定,始终为零。 @@ -3652,7 +3645,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3703,7 +3696,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3729,7 +3722,7 @@ CancelRequest (F) Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3760,7 +3753,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3844,14 +3837,14 @@ CancelRequest (F) - 将消息标识为同步命令。 + 将该消息标识为 Sync 命令。 Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3880,7 +3873,7 @@ CancelRequest (F) Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3896,7 +3889,7 @@ CancelRequest (F) -错误和通知消息域 +错误和通知消息字段 本节描述了ErrorResponse和NoticeResponse消息中可能出现的字段。每个字段类型都有一个单字节的标识符。 @@ -3910,11 +3903,7 @@ CancelRequest (F) - 严重性: 字段内容为ERROR, FATAL, 或 - PANIC (在错误消息中), 或 - WARNING, NOTICE, DEBUG, - INFO, 或 LOG (在通知消息中), - 或者这些内容的本地化翻译。始终存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中),或这些内容的本地化翻译。始终存在。 @@ -3924,11 +3913,7 @@ CancelRequest (F) - 严重性:字段内容为 ERRORFATAL 或 - PANIC(在错误消息中),或 WARNINGNOTICEDEBUG、 - INFOLOG(在通知消息中)。 - 这与S字段相同,只是内容不会被本地化。仅在由PostgreSQL版本9.6 - 及更高版本生成的消息中存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中)。它与 S 字段相同,只是内容从不本地化。仅在 PostgreSQL 9.6 及更高版本生成的消息中存在。 @@ -3938,7 +3923,7 @@ CancelRequest (F) - Code: 错误的SQLSTATE代码(参见)。不可本地化。始终存在。 + 代码:错误的 SQLSTATE 代码(见 )。不可本地化。始终存在。 @@ -3948,9 +3933,7 @@ CancelRequest (F) - 消息: 主要的人类可读错误消息。 - 这应该准确但简洁(通常一行)。 - 总是存在。 + 消息:主要的可读错误消息。应准确而简洁(通常为一行)。始终存在。 @@ -3960,7 +3943,7 @@ CancelRequest (F) - 详细信息:一个可选的次要错误消息,提供有关问题的更多详细信息。可能会跨多行。 + 详细信息:可选的次要错误消息,提供有关该问题的更多细节。可能占多行。 @@ -3970,9 +3953,7 @@ CancelRequest (F) - 提示: 关于问题应该怎么做的一个可选建议。 - 这意在与细节不同,它提供建议(可能不合适)而不是硬性事实。 - 可能会跨越多行。 + 提示:可选的建议,说明如何处理该问题。它与详细信息的区别在于,它提供建议(可能并不合适),而非确凿事实。可能占多行。 @@ -4014,9 +3995,7 @@ CancelRequest (F) - Where: 错误发生的上下文指示。 - 目前包括活动的过程语言函数和内部生成查询的调用堆栈回溯。 - 跟踪每行一个条目,最近的在前。 + 上下文:说明错误发生时的上下文。目前包括活跃的过程语言函数和内部生成的查询的调用栈回溯。回溯每行一个条目,最近的调用在前。 @@ -4026,7 +4005,7 @@ CancelRequest (F) - Schema name: 如果错误与特定数据库对象相关联,则为包含该对象的模式的名称(如果有)。 + 模式名:如果错误与某个特定数据库对象有关,则为包含该对象的模式名称(如果有)。 @@ -4036,7 +4015,7 @@ CancelRequest (F) - 表名: 如果错误与特定表相关联,则为表的名称。(有关表模式名称的名称,请参考模式名称字段。) + 表名:如果错误与某个特定表有关,则为该表的名称。(表所在模式的名称见模式名字段。) @@ -4046,7 +4025,7 @@ CancelRequest (F) - 列名: 如果错误与特定表列相关联,则为列的名称。(请参考模式和表名字段以识别表。) + 列名:如果错误与某个特定表列有关,则为该列的名称。(通过模式名和表名字段确定该表。) @@ -4056,8 +4035,7 @@ CancelRequest (F) - 数据类型名称: 如果错误与特定数据类型相关联,则为数据类型的名称。 - (有关数据类型模式的名称,请参阅模式名称字段。) + 数据类型名:如果错误与某个特定数据类型有关,则为该数据类型的名称。(数据类型所在模式的名称见模式名字段。) @@ -4067,8 +4045,7 @@ CancelRequest (F) - 约束名称: 如果错误与特定约束相关联,则为约束的名称。请参考上面列出的字段,了解相关表或域。 - (为此,即使索引不是使用约束语法创建的,也将其视为约束。) + 约束名:如果错误与某个特定约束有关,则为该约束的名称。相关的表或域见上述字段。(这里将索引也视为约束,即使它不是用约束语法创建的。) @@ -4078,7 +4055,7 @@ CancelRequest (F) - 文件: 报告错误的源代码位置的文件名。 + 文件:报告错误的源代码位置所在的文件名。 @@ -4088,7 +4065,7 @@ CancelRequest (F) - Line: 源代码位置的行号,报告错误的位置。 + 行号:报告错误的源代码位置所在的行号。 @@ -4098,7 +4075,7 @@ CancelRequest (F) - Routine: 报告错误的源代码例程的名称。 + 例程:报告错误的源代码例程的名称。 @@ -4108,15 +4085,12 @@ CancelRequest (F) - 模式名称、表名称、列名称、数据类型名称和约束名称的字段仅针对有限数量的错误类型提供; - 请参阅。前端不应假设任何这些字段的存在就保证了另一个字段的存在。 - 核心错误源观察到上述相互关系,但用户定义的函数可能以其他方式使用这些字段。 - 同样地,客户端不应假设这些字段表示当前数据库中的当代对象。 + 模式名、表名、列名、数据类型名和约束名字段仅针对有限的几类错误提供,见 。前端不应假设其中任何字段的存在就保证了另一个字段的存在。核心错误源遵循上述相互关系,但用户定义的函数可能以其他方式使用这些字段。同样,客户端不应假设这些字段表示当前数据库中现存的对象。 - 客户端负责格式化显示的信息以满足其需求;特别是应根据需要换行。错误消息字段中出现的换行符应被视为段落分隔符,而不是换行符。 + 客户端负责按自身需要格式化显示的信息;尤其应根据需要将长行断开。错误消息字段中的换行符应视为段落分隔符,而非行分隔符。 @@ -4144,7 +4118,7 @@ CancelRequest (F) - 将消息标识为开始消息。 + 将该消息标识为 Begin 消息。 @@ -4188,7 +4162,7 @@ CancelRequest (F) - 标识消息为提交消息。 + 将该消息标识为 Commit 消息。 @@ -4237,7 +4211,7 @@ CancelRequest (F) Byte1('O') -标识消息为复制源消息。 +将该消息标识为 Origin 消息。 @@ -4259,7 +4233,7 @@ CancelRequest (F) - 请注意,在单个事务中可能存在多个Origin消息。 + 注意,单个事务中可能有多条 Origin 消息。 @@ -4274,7 +4248,7 @@ CancelRequest (F) Byte1('R') -将该消息标识为关系消息。 +将该消息标识为 Relation 消息。 @@ -4301,7 +4275,7 @@ CancelRequest (F) - 关系的复制标识设置(与relreplidentpg_class中相同)。 + 关系的复制标识设置(与 pg_class 中的 relreplident 相同)。 @@ -4336,7 +4310,7 @@ CancelRequest (F) - 列的类型修饰符 (atttypmod)。 + 列的类型修饰符(atttypmod)。 @@ -4355,7 +4329,7 @@ CancelRequest (F) Byte1('Y') -将该消息标识为类型消息。 +将该消息标识为 Type 消息。 @@ -4391,13 +4365,13 @@ CancelRequest (F) Byte1('I') -将该消息标识为插入消息。 +将该消息标识为 Insert 消息。 Int32 -关系的 ID,与关系消息中的 ID 对应。 +关系的 ID,与 Relation 消息中的 ID 对应。 @@ -4428,13 +4402,13 @@ CancelRequest (F) Byte1('U') -将该消息标识为更新消息。 +将该消息标识为 Update 消息。 Int32 -关系的 ID,与关系消息中的 ID 对应。 +关系的 ID,与 Relation 消息中的 ID 对应。 @@ -4490,13 +4464,13 @@ CancelRequest (F) Byte1('D') -将该消息标识为删除消息。 +将该消息标识为 Delete 消息。 Int32 -关系的 ID,与关系消息中的 ID 对应。 +关系的 ID,与 Relation 消息中的 ID 对应。 diff --git a/zh/10/rangetypes.sgml b/zh/10/rangetypes.sgml index 92eca5d6..d8d10cf5 100644 --- a/zh/10/rangetypes.sgml +++ b/zh/10/rangetypes.sgml @@ -4,7 +4,7 @@ 范围类型 - range type + 范围类型 @@ -18,7 +18,9 @@ 内置范围类型 - PostgreSQL 提供以下内置范围类型: + + PostgreSQL 自带下列内置范围类型: + int4rangeinteger 的范围 @@ -37,7 +39,9 @@ daterangedate 的范围 - 此外,还可以定义自己的范围类型;参见了解更多信息。 + + 此外,你还可以定义自己的范围类型;详见。 + @@ -92,15 +96,15 @@ SELECT isempty(numrange(1, 5)); 无限(无界)范围 - 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作 +/-infinity,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的 +/-infinity 值。 + 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作正负无穷大,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的正负无穷大值。 - 具有infinity概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 + 具有无穷大概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 - 函数lower_infupper_inf分别测试范围的下界和上界是否为无限。 + 函数lower_infupper_inf分别测试范围是否没有下界和上界。 @@ -259,23 +263,23 @@ SELECT '[11:10, 23:00]'::timerange; 索引 - range type - indexes on + 范围类型 + 索引 可以为范围类型的表列创建 GiST 和 SP-GiST 索引。例如,创建 GiST 索引: CREATE INDEX reservation_idx ON reservation USING GIST (during); -GiST 或 SP-GiST 索引可以加速涉及以下范围操作符的查询:=, - &&, - <@, - @>, - <<, - >>, - -|-, +GiST 或 SP-GiST 索引可以加速涉及以下范围操作符的查询:=、 + &&、 + <@、 + @>、 + <<、 + >>、 + -|-&<&>(参见了解更多信息)。 - 此外,也可以为范围类型的表列创建 B-树和哈希索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和哈希支持主要是为了允许在查询内部进行排序和哈希,而不是用于创建实际的索引。 + 此外,也可以为范围类型的表列创建 B-树和 hash 索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和 hash 支持主要是为了允许在查询内部进行排序和 hash 运算,而不是用于创建实际的索引。 @@ -283,8 +287,8 @@ CREATE INDEX reservation_idx ON reservation USING GIST (during); 范围上的约束 - range type - exclude + 范围类型 + 排他约束 diff --git a/zh/10/recovery-config.sgml b/zh/10/recovery-config.sgml index 20c3d614..368c6c6c 100644 --- a/zh/10/recovery-config.sgml +++ b/zh/10/recovery-config.sgml @@ -4,9 +4,9 @@ 恢复配置 - configuration - of recovery - 一个备库 + 配置 + 恢复 + 备库 本章介绍 recovery.confrecovery.conf 文件中可用的设置。它们只在恢复期间生效。如果之后还要进行恢复,必须重新设置这些参数。恢复开始后,就不能再更改它们。 diff --git a/zh/10/ref/alter_extension.sgml b/zh/10/ref/alter_extension.sgml index 892e9d06..082101cf 100644 --- a/zh/10/ref/alter_extension.sgml +++ b/zh/10/ref/alter_extension.sgml @@ -164,7 +164,7 @@ ALTER EXTENSION name DROP function_name operator_name - 要添加到扩展或从扩展中移除的对象名称。表、聚合、域、外部表、函数、操作符、操作符类、操作符族、序列、文本搜索对象、类型和视图的名称可以带模式限定。 + 要添加到扩展或从扩展中移除的对象名称。表、聚合、域、外部表、函数、操作符、操作符类、操作符族、序列、文本检索对象、类型和视图的名称可以带模式限定。 diff --git a/zh/10/ref/alter_tsconfig.sgml b/zh/10/ref/alter_tsconfig.sgml index c19cfa68..722151a7 100644 --- a/zh/10/ref/alter_tsconfig.sgml +++ b/zh/10/ref/alter_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义 + 更改一个文本检索配置的定义 @@ -45,7 +45,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义。你可以修改其从记号类型到字典的映射, + 更改一个文本检索配置的定义。你可以修改其从词元类型到词典的映射, 或者更改该配置的名称或拥有者。 @@ -67,7 +67,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 一个现有文本搜索配置的名称(可以是模式限定的)。 + 一个现有文本检索配置的名称(可以是模式限定的)。 @@ -78,7 +78,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 由该配置的解析器发出的记号类型的名称。 + 由该配置的解析器发出的词元类型的名称。 @@ -89,7 +89,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 用于指定记号类型的文本搜索字典名称。如果列出了多个字典, + 用于指定词元类型的文本检索词典名称。如果列出了多个词典, 将按指定顺序依次查阅它们。 @@ -101,7 +101,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 在映射中要替换的文本搜索字典的名称。 + 在映射中要替换的文本检索词典的名称。 @@ -113,7 +113,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA 被用来替代old_dictionary - 的文本搜索字典的名称。 + 的文本检索词典的名称。 @@ -124,7 +124,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新名称。 + 该文本检索配置的新名称。 @@ -135,7 +135,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新拥有者。 + 该文本检索配置的新拥有者。 @@ -146,21 +146,21 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新模式。 + 该文本检索配置的新模式。 - ADD MAPPING FOR形式为指定的词元类型安装要查询的字典列表;如果任何词元类型已经存在映射,则会报错。ALTER MAPPING FOR形式执行相同操作,但会先移除这些词元类型的现有映射。ALTER MAPPING REPLACE形式在任何出现旧字典的地方用new_dictionary替换old_dictionary。当出现FOR时,只对指定的词元类型执行此操作;不出现时,则对该配置的所有映射执行。DROP MAPPING形式移除指定词元类型的所有字典,使这些类型的词元被文本搜索配置忽略。如果词元类型没有映射,则会报错,除非出现IF EXISTS + ADD MAPPING FOR形式为指定的词元类型安装要查询的词典列表;如果任何词元类型已经存在映射,则会报错。ALTER MAPPING FOR形式执行相同操作,但会先移除这些词元类型的现有映射。ALTER MAPPING REPLACE形式在任何出现旧词典的地方用new_dictionary替换old_dictionary。当出现FOR时,只对指定的词元类型执行此操作;不出现时,则对该配置的所有映射执行。DROP MAPPING形式移除指定词元类型的所有词典,使这些类型的词元被文本检索配置忽略。如果词元类型没有映射,则会报错,除非出现IF EXISTS 示例 - 以下示例在my_config中使用english的任何地方,都将english字典替换为swedish字典。 + 以下示例在my_config中使用english的任何地方,都将english词典替换为swedish词典。 ALTER TEXT SEARCH CONFIGURATION my_config diff --git a/zh/10/ref/alter_tsdictionary.sgml b/zh/10/ref/alter_tsdictionary.sgml index 1356e2fd..e12fca46 100644 --- a/zh/10/ref/alter_tsdictionary.sgml +++ b/zh/10/ref/alter_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH DICTIONARY - 更改一个文本搜索字典的定义 + 更改一个文本检索词典的定义 @@ -37,14 +37,14 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - ALTER TEXT SEARCH DICTIONARY更改文本搜索字典的 - 定义。你可以更改该字典的模板相关选项,也可以更改该字典的名称或拥有者。 + ALTER TEXT SEARCH DICTIONARY更改文本检索词典的 + 定义。你可以更改该词典的模板相关选项,也可以更改该词典的名称或拥有者。 - 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该字典 + 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该词典 的拥有者。 @@ -59,7 +59,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 一个现有文本搜索字典的名称(可以是模式限定的)。 + 一个现有文本检索词典的名称(可以是模式限定的)。 @@ -70,7 +70,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -81,7 +81,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 模板相关选项要使用的新值。如果省略等号和值,则会从该字典中移除 + 模板相关选项要使用的新值。如果省略等号和值,则会从该词典中移除 该选项之前的设置,从而允许使用默认值。 @@ -93,7 +93,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新名称。 + 该文本检索词典的新名称。 @@ -104,7 +104,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新拥有者。 + 该文本检索词典的新拥有者。 @@ -115,7 +115,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新模式。 + 该文本检索词典的新模式。 @@ -134,7 +134,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 下面的示例命令更改了一个基于 Snowball 的字典的停用词列表。其他参数 + 下面的示例命令更改了一个基于 Snowball 的词典的停用词列表。其他参数 保持不变。 @@ -160,7 +160,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( language = dutch, StopWords ); - 下面的示例命令更新了该字典的定义,但实际上并没有做 + 下面的示例命令更新了该词典的定义,但实际上并没有做 任何更改。 @@ -168,7 +168,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( dummy ); (之所以可行,是因为选项移除代码在不存在该选项时也不会报错。) - 这种技巧在修改该字典的配置文件时很有用:ALTER + 这种技巧在修改该词典的配置文件时很有用:ALTER 会强制现有数据库会话重新读取配置文件,而如果它们先前已经读取过这 些文件,本来是不会再次读取的。 diff --git a/zh/10/ref/alter_tsparser.sgml b/zh/10/ref/alter_tsparser.sgml index e1026b50..9700926e 100644 --- a/zh/10/ref/alter_tsparser.sgml +++ b/zh/10/ref/alter_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH PARSER - 更改一个全文检索解析器的定义 + 更改一个文本检索解析器的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA 描述 - ALTER TEXT SEARCH PARSER更改全文检索解析器的定义。 + ALTER TEXT SEARCH PARSER更改文本检索解析器的定义。 当前唯一支持的功能是更改该解析器的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA name - 一个现有全文检索解析器的名称(可以是模式限定的)。 + 一个现有文本检索解析器的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_name - 该全文检索解析器的新名称。 + 该文本检索解析器的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_schema - 该全文检索解析器的新模式。 + 该文本检索解析器的新模式。 diff --git a/zh/10/ref/alter_tstemplate.sgml b/zh/10/ref/alter_tstemplate.sgml index e2604fd1..802475da 100644 --- a/zh/10/ref/alter_tstemplate.sgml +++ b/zh/10/ref/alter_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH TEMPLATE - 更改一个文本搜索模板的定义 + 更改一个文本检索模板的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA 描述 - ALTER TEXT SEARCH TEMPLATE更改文本搜索模板的定义。 + ALTER TEXT SEARCH TEMPLATE更改文本检索模板的定义。 当前唯一支持的功能是更改该模板的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA name - 一个现有文本搜索模板的名称(可以是模式限定的)。 + 一个现有文本检索模板的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_name - 该文本搜索模板的新名称。 + 该文本检索模板的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_schema - 该文本搜索模板的新模式。 + 该文本检索模板的新模式。 diff --git a/zh/10/ref/comment.sgml b/zh/10/ref/comment.sgml index 73726ce1..bec60184 100644 --- a/zh/10/ref/comment.sgml +++ b/zh/10/ref/comment.sgml @@ -112,7 +112,7 @@ COMMENT ON rule_name trigger_name - 要添加注释的对象名称。表、聚合、排序规则、转换、域、外部表、函数、索引、操作符、操作符类、操作符族、序列、统计信息、文本搜索对象、类型和视图的名称可以带模式限定。为列添加注释时,relation_name必须引用表、视图、复合类型或外部表。 + 要添加注释的对象名称。表、聚合、排序规则、转换、域、外部表、函数、索引、操作符、操作符类、操作符族、序列、统计信息、文本检索对象、类型和视图的名称可以带模式限定。为列添加注释时,relation_name必须引用表、视图、复合类型或外部表。 diff --git a/zh/10/ref/create_tsconfig.sgml b/zh/10/ref/create_tsconfig.sgml index caf8d05b..480afd8c 100644 --- a/zh/10/ref/create_tsconfig.sgml +++ b/zh/10/ref/create_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH CONFIGURATION - 定义一个新的文本搜索配置 + 定义一个新的文本检索配置 @@ -33,24 +33,24 @@ CREATE TEXT SEARCH CONFIGURATION name CREATE TEXT SEARCH CONFIGURATION - 创建一个新的文本搜索配置。文本搜索配置指定一个能把字符串拆分为记号 - 的文本搜索解析器,以及一些可用于判断哪些记号对搜索有意义的词典。 + 创建一个新的文本检索配置。文本检索配置指定一个能把字符串拆分为词元 + 的文本检索解析器,以及一些可用于判断哪些词元对搜索有意义的词典。 - 如果只指定了解析器,那么新文本搜索配置最初没有从记号类型到词典的映射, + 如果只指定了解析器,那么新文本检索配置最初没有从词元类型到词典的映射, 因而会忽略所有词。要让该配置真正可用,必须使用后续的ALTER TEXT SEARCH CONFIGURATION命令创建映射。 - 另一种方式是复制一个现有的文本搜索配置。 + 另一种方式是复制一个现有的文本检索配置。 - 如果给出了一个模式名称,则文本搜索配置会被创建在指定的模式中。否则它将会 + 如果给出了一个模式名称,则文本检索配置会被创建在指定的模式中。否则它将会 被创建在当前模式中。 - 定义该文本搜索配置的用户会成为其拥有者。 + 定义该文本检索配置的用户会成为其拥有者。 @@ -66,7 +66,7 @@ CREATE TEXT SEARCH CONFIGURATION namename - 要创建的文本搜索配置的名称。该名称可以是模式限定的。 + 要创建的文本检索配置的名称。该名称可以是模式限定的。 @@ -75,7 +75,7 @@ CREATE TEXT SEARCH CONFIGURATION nameparser_name - 此配置要使用的文本搜索解析器的名称。 + 此配置要使用的文本检索解析器的名称。 @@ -84,7 +84,7 @@ CREATE TEXT SEARCH CONFIGURATION namesource_config - 要复制的现有文本搜索配置的名称。 + 要复制的现有文本检索配置的名称。 diff --git a/zh/10/ref/create_tsdictionary.sgml b/zh/10/ref/create_tsdictionary.sgml index ad77cd39..851347ed 100644 --- a/zh/10/ref/create_tsdictionary.sgml +++ b/zh/10/ref/create_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH DICTIONARY - 定义一个新的文本搜索字典 + 定义一个新的文本检索词典 @@ -33,19 +33,19 @@ CREATE TEXT SEARCH DICTIONARY name CREATE TEXT SEARCH DICTIONARY创建一个 - 新的文本搜索字典。文本搜索字典指定一种在搜索时识别哪些词值得关注、 - 哪些词不值得关注的方式。字典依赖于文本搜索模板,后者规定了实际执行 - 这项工作的函数。通常,字典会提供一些选项,用来控制模板函数的具体 + 新的文本检索词典。文本检索词典指定一种在搜索时识别哪些词值得关注、 + 哪些词不值得关注的方式。词典依赖于文本检索模板,后者规定了实际执行 + 这项工作的函数。通常,词典会提供一些选项,用来控制模板函数的具体 行为。 - 如果给出了一个模式名称,那么该文本搜索字典会被创建在指定的模式中。 + 如果给出了一个模式名称,那么该文本检索词典会被创建在指定的模式中。 否则它会被创建在当前模式中。 - 定义文本搜索字典的用户将成为其拥有者。 + 定义文本检索词典的用户将成为其拥有者。 @@ -61,7 +61,7 @@ CREATE TEXT SEARCH DICTIONARY name name - 要创建的文本搜索字典的名称。该名称可以被模式限定。 + 要创建的文本检索词典的名称。该名称可以被模式限定。 @@ -70,7 +70,7 @@ CREATE TEXT SEARCH DICTIONARY name template - 用于定义该字典基本行为的文本搜索模板名称。 + 用于定义该词典基本行为的文本检索模板名称。 @@ -79,7 +79,7 @@ CREATE TEXT SEARCH DICTIONARY name option - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -105,7 +105,7 @@ CREATE TEXT SEARCH DICTIONARY name 下面的示例命令创建了一个基于 Snowball 且使用非标准停用词列表的 - 字典。 + 词典。 diff --git a/zh/10/ref/create_tsparser.sgml b/zh/10/ref/create_tsparser.sgml index d8ebb16a..ef2e1438 100644 --- a/zh/10/ref/create_tsparser.sgml +++ b/zh/10/ref/create_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH PARSER - 定义一个新的全文检索解析器 + 定义一个新的文本检索解析器 @@ -36,19 +36,19 @@ CREATE TEXT SEARCH PARSER name ( CREATE TEXT SEARCH PARSER创建一个 - 新的全文检索解析器。全文检索解析器定义了一种方法,用于将文本字符串 - 拆分成记号并为这些记号指定类型(类别)。解析器本身并没有太大用处, - 必须与一些全文检索字典一起绑定到一个全文检索配置中,才能用于搜索。 + 新的文本检索解析器。文本检索解析器定义了一种方法,用于将文本字符串 + 拆分成词元并为这些词元指定类型(类别)。解析器本身并没有太大用处, + 必须与一些文本检索词典一起绑定到一个文本检索配置中,才能用于搜索。 - 如果给出了一个模式名称,那么全文检索解析器将被创建在指定的模式中。 + 如果给出了一个模式名称,那么文本检索解析器将被创建在指定的模式中。 否则它会被创建在当前模式中。 要使用CREATE TEXT SEARCH PARSER,你必须是超级用户。 - 之所以有此限制,是因为错误的全文检索解析器定义可能会让服务器陷入 + 之所以有此限制,是因为错误的文本检索解析器定义可能会让服务器陷入 混乱,甚至崩溃。 @@ -65,7 +65,7 @@ CREATE TEXT SEARCH PARSER name ( name - 要创建的全文检索解析器的名称。该名称可以是模式限定的。 + 要创建的文本检索解析器的名称。该名称可以是模式限定的。 @@ -83,7 +83,7 @@ CREATE TEXT SEARCH PARSER name ( gettoken_function - 该解析器的获取下一个记号的函数名称。 + 该解析器的获取下一个词元的函数名称。 @@ -101,7 +101,7 @@ CREATE TEXT SEARCH PARSER name ( lextypes_function - 该解析器的 lextypes 函数的名称(该函数返回它所产生的记号类型集合的 + 该解析器的 lextypes 函数的名称(该函数返回它所产生的词元类型集合的 信息)。 @@ -111,7 +111,7 @@ CREATE TEXT SEARCH PARSER name ( headline_function - 该解析器的 headline 函数的名称(该函数对一组记号生成摘要)。 + 该解析器的 headline 函数的名称(该函数对一组词元生成摘要)。 diff --git a/zh/10/ref/create_tstemplate.sgml b/zh/10/ref/create_tstemplate.sgml index f6d2128f..baf2d57b 100644 --- a/zh/10/ref/create_tstemplate.sgml +++ b/zh/10/ref/create_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH TEMPLATE - 定义一个新的全文检索模板 + 定义一个新的文本检索模板 @@ -33,22 +33,22 @@ CREATE TEXT SEARCH TEMPLATE name ( CREATE TEXT SEARCH TEMPLATE创建一个 - 新的全文检索模板。全文检索模板定义实现全文检索字典的函数。模板本身 - 并无直接用途,必须先实例化为字典后才能使用。字典通常会指定要传递给 + 新的文本检索模板。文本检索模板定义实现文本检索词典的函数。模板本身 + 并无直接用途,必须先实例化为词典后才能使用。词典通常会指定要传递给 模板函数的参数。 - 如果给出了模式名称,则全文检索模板会被创建在指定模式中。否则它会被 + 如果给出了模式名称,则文本检索模板会被创建在指定模式中。否则它会被 创建在当前模式中。 要使用CREATE TEXT SEARCH TEMPLATE,你 - 必须是超级用户。之所以有此限制,是因为错误的全文检索模板定义可能使 - 服务器陷入混乱,甚至崩溃。将模板与字典分离的原因在于,模板封装了定 - 义字典时那些不安全的方面。而在定义字典时可设置的参数, - 对非特权用户来说是安全的,因此创建字典不必是特权操作。 + 必须是超级用户。之所以有此限制,是因为错误的文本检索模板定义可能使 + 服务器陷入混乱,甚至崩溃。将模板与词典分离的原因在于,模板封装了定 + 义词典时那些不安全的方面。而在定义词典时可设置的参数, + 由普通用户设置也是安全的,因此创建词典不必是特权操作。 @@ -64,7 +64,7 @@ CREATE TEXT SEARCH TEMPLATE name ( name - 要创建的全文检索模板名称。该名称可以是模式限定的。 + 要创建的文本检索模板名称。该名称可以是模式限定的。 diff --git a/zh/10/ref/drop_opclass.sgml b/zh/10/ref/drop_opclass.sgml index 53d1b5a7..0542a274 100644 --- a/zh/10/ref/drop_opclass.sgml +++ b/zh/10/ref/drop_opclass.sgml @@ -110,7 +110,7 @@ DROP OPERATOR CLASS [ IF EXISTS ] name示例 - 移除 B-tree 操作符类widget_ops: + 移除 B-树操作符类widget_ops DROP OPERATOR CLASS widget_ops USING btree; diff --git a/zh/10/ref/drop_tsconfig.sgml b/zh/10/ref/drop_tsconfig.sgml index 0881769f..1a985a29 100644 --- a/zh/10/ref/drop_tsconfig.sgml +++ b/zh/10/ref/drop_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH CONFIGURATION - 移除一个文本搜索配置 + 移除一个文本检索配置 @@ -29,7 +29,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 描述 - DROP TEXT SEARCH CONFIGURATION删除一个现有文本搜索配置。 + DROP TEXT SEARCH CONFIGURATION删除一个现有文本检索配置。 要执行此命令,你必须是该配置的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name IF EXISTS - 如果该文本搜索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name name - 现有文本搜索配置的名称(可以被模式限定)。 + 现有文本检索配置的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name CASCADE - 自动删除依赖于该文本搜索配置的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索配置的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name RESTRICT - 如果有任何对象依赖于该文本搜索配置,则拒绝删除该配置。这是默认值。 + 如果有任何对象依赖于该文本检索配置,则拒绝删除该配置。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 示例 - 移除文本搜索配置my_english: + 移除文本检索配置my_english DROP TEXT SEARCH CONFIGURATION my_english; 如果已有索引在to_tsvector调用中引用了该配置, - 此命令将不会成功。加上CASCADE可以在删除该文本搜索配置的同时删除这类索引。 + 此命令将不会成功。加上CASCADE可以在删除该文本检索配置的同时删除这类索引。 diff --git a/zh/10/ref/drop_tsdictionary.sgml b/zh/10/ref/drop_tsdictionary.sgml index ba5c3de3..25463d98 100644 --- a/zh/10/ref/drop_tsdictionary.sgml +++ b/zh/10/ref/drop_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH DICTIONARY - 移除一个文本搜索字典 + 移除一个文本检索词典 @@ -29,8 +29,8 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name描述 - DROP TEXT SEARCH DICTIONARY删除一个现有文本搜索字典。 - 要执行此命令,你必须是该字典的拥有者。 + DROP TEXT SEARCH DICTIONARY删除一个现有文本检索词典。 + 要执行此命令,你必须是该词典的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索字典不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索词典不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] namename - 一个现有文本搜索字典的名称(可以被模式限定)。 + 一个现有文本检索词典的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索字典的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索词典的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索字典,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索词典,则拒绝删除它。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name示例 - 移除文本搜索字典english: + 移除文本检索词典english DROP TEXT SEARCH DICTIONARY english; - 如果已有文本搜索配置使用该字典,此命令将不会成功。 - 加上CASCADE可以在删除字典的同时删除这类配置。 + 如果已有文本检索配置使用该词典,此命令将不会成功。 + 加上CASCADE可以在删除词典的同时删除这类配置。 diff --git a/zh/10/ref/drop_tsparser.sgml b/zh/10/ref/drop_tsparser.sgml index a3ea49d7..d6c56efb 100644 --- a/zh/10/ref/drop_tsparser.sgml +++ b/zh/10/ref/drop_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH PARSER - 移除一个文本搜索解析器 + 移除一个文本检索解析器 @@ -29,7 +29,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name描述 - DROP TEXT SEARCH PARSER删除一个现有文本搜索解析器。 + DROP TEXT SEARCH PARSER删除一个现有文本检索解析器。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] namename - 一个现有文本搜索解析器的名称(可以被模式限定)。 + 一个现有文本检索解析器的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索解析器的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索解析器的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索解析器,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索解析器,则拒绝删除它。这是默认值。 @@ -82,13 +82,13 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name示例 - 移除文本搜索解析器my_parser: + 移除文本检索解析器my_parser DROP TEXT SEARCH PARSER my_parser; - 如果已有文本搜索配置使用该解析器,此命令将不会成功。 + 如果已有文本检索配置使用该解析器,此命令将不会成功。 加上CASCADE可以在删除解析器的同时删除这类配置。 diff --git a/zh/10/ref/drop_tstemplate.sgml b/zh/10/ref/drop_tstemplate.sgml index 2a0fda88..ea4a9dff 100644 --- a/zh/10/ref/drop_tstemplate.sgml +++ b/zh/10/ref/drop_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH TEMPLATE - 移除一个文本搜索模板 + 移除一个文本检索模板 @@ -29,7 +29,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name描述 - DROP TEXT SEARCH TEMPLATE删除一个现有文本搜索模板。 + DROP TEXT SEARCH TEMPLATE删除一个现有文本检索模板。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] namename - 现有文本搜索模板的名称(可以被模式限定)。 + 现有文本检索模板的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索模板的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索模板的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索模板,则拒绝删除该模板。这是默认值。 + 如果有任何对象依赖于该文本检索模板,则拒绝删除该模板。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name示例 - 移除文本搜索模板thesaurus: + 移除文本检索模板thesaurus DROP TEXT SEARCH TEMPLATE thesaurus; - 如果已有文本搜索字典使用该模板,此命令将不会成功。加上CASCADE - 可以在删除该模板的同时删除这类字典。 + 如果已有文本检索词典使用该模板,此命令将不会成功。加上CASCADE + 可以在删除该模板的同时删除这类词典。 diff --git a/zh/10/ref/initdb.sgml b/zh/10/ref/initdb.sgml index 923ac1c1..deff9d63 100644 --- a/zh/10/ref/initdb.sgml +++ b/zh/10/ref/initdb.sgml @@ -136,7 +136,7 @@ PostgreSQL documentation - + @@ -195,7 +195,7 @@ PostgreSQL documentation - 使initdb从文件中读取引导超级用户的密码。文件的第一行会被当作密码。 + 使initdb从文件中读取数据库超级用户的密码。文件的第一行会被当作密码。 @@ -215,7 +215,7 @@ PostgreSQL documentation - 设置默认文本搜索配置。更多信息见 + 设置默认文本检索配置。更多信息见 @@ -226,10 +226,9 @@ PostgreSQL documentation - 选择数据库超级用户的用户名。默认值是运行 - initdb的实际用户名称。超级用户的名称本身 - 并不重要,不过即使操作系统用户名称不同,人们也可能选择沿用惯常 - 的名称postgres。 + 选择数据库超级用户的用户名。默认值是运行initdb的有效用户的名称。 + 超级用户的名称本身并不重要,不过即使操作系统用户名称不同,也可以选择沿用惯常的名称 + postgres @@ -239,7 +238,7 @@ PostgreSQL documentation - 使initdb提示输入要赋给引导超级用户的密码。如果不打算使用密码认证, + 使initdb提示输入要赋给数据库超级用户的密码。如果不打算使用密码认证, 这一点并不重要。否则,在设置密码之前将无法使用密码认证。 diff --git a/zh/10/ref/pgbench.sgml b/zh/10/ref/pgbench.sgml index 441fd105..f2b79e9c 100644 --- a/zh/10/ref/pgbench.sgml +++ b/zh/10/ref/pgbench.sgml @@ -36,7 +36,7 @@ PostgreSQL documentation 描述 - pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,必要时可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 + pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,也可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 @@ -57,13 +57,15 @@ tps = 85.296346 (excluding connections establishing) 前六行报告了一些最重要的参数设置。下一行报告已完成的事务数和预期的事务数(后者就是客户端数与每个客户端的事务数的乘积);除非运行在完成前失败,否则这两个数应该相等。(在 模式下,只打印实际的事务数。)最后两行报告每秒事务数,分别计入和不计入启动数据库会话的时间。 - 默认的类 TPC-B 事务测试要求预先建立特定的表。pgbench应使用(初始化)选项调用,以创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: + + 默认的类 TPC-B 事务测试要求预先建立特定的表。应使用(初始化)选项调用pgbench来创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: + + pgbench -i other-options dbname - 其中, - dbname是已创建好的、用于执行测试的数据库名称。(可能还需要使用, - 和/或选项来指定如何连接到数据库服务器。) + 其中dbname是已创建好的、用于执行测试的数据库名称。(可能还需要使用和/或选项来指定如何连接到数据库服务器。) + @@ -76,14 +78,14 @@ pgbench -i other-options 在默认的比例因子 1 下,这些表最初包含如下行数: -table # of rows +表 行数 --------------------------------- pgbench_branches 1 pgbench_tellers 10 pgbench_accounts 100000 pgbench_history 0 - 可以使用(比例因子)选项来增加行数,而且在大多数场景下也确实应该这样做。此时还可以配合使用(fillfactor)选项。 + 可以使用(比例因子)选项来增加行数,而且在大多数场景下通常也应该这样做。此时还可以配合使用(fillfactor)选项。 @@ -109,7 +111,7 @@ pgbench options d 初始化选项 - pgbench 接受以下用于初始化的命令行参数: + pgbench 接受以下命令行初始化参数: @@ -222,7 +224,7 @@ pgbench options d 基准测试选项 - pgbench 接受以下用于基准测试的命令行参数: + pgbench 接受以下命令行基准测试参数: @@ -359,13 +361,13 @@ pgbench options d 用于向服务器提交查询的协议: - simple: 使用简单查询协议。 + simple:使用简单查询协议。 - extended: 使用扩展查询协议。 + extended:使用扩展查询协议。 - prepared: 使用带有预备语句的扩展查询协议。 + prepared:使用带有预备语句的扩展查询协议。 默认为简单查询协议。(详见 。) @@ -449,7 +451,7 @@ pgbench options d 较高的计划滞后时间表明,在所选客户端数和线程数下,系统无法以指定速率处理事务。 当平均事务执行时间长于事务之间的计划间隔时,后续事务会不断进一步落后, - 而计划滞后时间也会随着测试持续时间增加。在这种情况下,只能降低指定的事务速率。 + 而计划滞后时间也会随着测试持续时间增加。在这种情况下,需要降低指定的事务速率。 @@ -461,7 +463,7 @@ pgbench options d pgbench输出中报告指定的比例因子。 - 对于内置测试,这通常没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 + 对于内置测试,这没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 但在只测试自定义基准(选项)时, 除非使用此选项,否则比例因子会被报告为 1。 @@ -635,7 +637,7 @@ pgbench options d 注解 - 实际执行的<quote>事务</quote>在<application>pgbench</application>中是什么? + 在<application>pgbench</application>中实际执行的<quote>事务</quote>是什么? pgbench会从指定列表中随机选取测试脚本来执行。 @@ -682,7 +684,7 @@ pgbench options d - 在PostgreSQL 9.6 之前,脚本文件中的 SQL 命令以换行符结束,因此不能跨行续写。现在,连续的 SQL 命令之间必须用分号分隔(不过,如果 SQL 命令后面跟着元命令,则不需要分号)。如果需要创建适用于新旧版本pgbench的脚本文件,请务必将每条 SQL 命令写在单独一行,并以分号结尾。 + 在PostgreSQL 9.6 之前,脚本文件中的 SQL 命令以换行结束,因此不能跨行。现在连续 SQL 命令之间必须用分号分隔(如果 SQL 命令后面跟着一个元命令,则不需要分号)。如果需要创建一个既能在旧版也能在新版pgbench下工作的脚本文件,务必将每个 SQL 命令写在单独一行,并以分号结束。 @@ -716,7 +718,7 @@ pgbench options d
- 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令及其参数之间以空白分隔。支持的元命令如下: + 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令的参数以空白分隔。支持的元命令如下: @@ -727,7 +729,7 @@ pgbench options d - 将变量varname设置为根据expression计算出的值。表达式可以包含整数常量(例如5432)、double 常量(例如3.14159)、变量引用:variablename、具有通常优先级和结合性的一元操作符(+、-)和二元操作符(+、-、*、/、%)、函数调用以及括号。 + 将变量varname设置为根据expression计算出的值。表达式可以包含整数常量(例如5432)、双精度常量(例如3.14159)、变量引用:variablename、具有通常优先级和结合性的一元操作符(+、-)和二元操作符(+、-、*、/、%)、函数调用以及括号。 @@ -771,7 +773,7 @@ pgbench options d - command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在其开头再写一个冒号。 + command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在argument开头再写一个冒号。 @@ -911,29 +913,28 @@ pgbench options d - 对于指数分布,parameter通过在以下位置截断一个快速衰减的指数分布来控制分布:parameter,然后将其投影到边界之间的整数上。准确地说,令 + + 对于指数分布,parameter通过在parameter处截断一个快速衰减的指数分布,再将其投影到边界之间的整数上,从而控制分布。准确地说,令 + f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) -则值i 位于 min 和 - max 之间(包括端点),被抽到的概率为: - f(i) - f(i + 1)。 + + 则minmax之间(含边界)的值i会以f(i) - f(i + 1)的概率被抽中。 - 直观地说,parameter越大,接近min的值被访问得越频繁,而接近max的值被访问得越少。parameter越接近 0,访问分布就越平坦(越均匀)。对该分布的一个粗略近似是:范围内最常出现的 1% 的值,即接近min的那些值,会在parameter% 的时间里被抽中。parameter的值必须严格为正。 + + 直观地说,parameter越大,越靠近min的值越容易被抽到,而越靠近max的值越不容易被抽到。parameter越接近 0,分布就越平坦(也就越均匀)。对这种分布的一个粗略近似是:范围内出现频率最高的 1% 的值,即最靠近min的那些值,大约会占到parameter% 的抽样次数。parameter必须严格大于 0。 + - 对于高斯分布,该区间映射到标准正态分布(经典的钟形高斯曲线),左侧截断于 -parameter,右侧截断于 +parameter。区间中部的值更容易被抽到。准确地说,如果 PHI(x) 为标准正态分布的累积分布函数,均值 mu 定义为 (max + min) / 2.0,并且 - + 对于高斯分布,该区间会映射到一个标准正态分布(经典钟形高斯曲线),并在左侧-parameter和右侧+parameter处截断。区间中部的值更容易被抽到。准确地说,如果PHI(x)是标准正态分布的累积分布函数,均值mu定义为(max + min) / 2.0,则有 + f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / (2.0 * PHI(parameter) - 1) - 那么,值 i 位于 min 和 - max 之间(包括端点),被抽到的概率为: - f(i + 0.5) - f(i - 0.5)。直观地说,parameter 越大,越靠近区间中部的值被抽到的频率就越高,而越靠近 min 和 - max 边界的值被抽到的频率就越低。约 67% 的值抽自区间中间的 1.0 / parameter,即均值周围相对 0.5 / parameter 的范围;95% 的值抽自区间中间的 2.0 / parameter,即均值周围相对 1.0 / parameter 的范围。例如,如果 parameter 为 4.0,则 67% 的值抽自区间中间四分之一(1.0 / 4.0)的范围(即从 - 3.0 / 8.05.0 / 8.0),95% 的值抽自区间中间一半(2.0 / 4.0)的范围(第二和第三四分位)。考虑到 Box-Muller 变换的性能,parameter 的最小值为 2.0。 - + 则minmax(包含边界)之间的值i被抽中的概率为:f(i + 0.5) - f(i - 0.5)。直观地说,parameter越大,越靠近区间中间的值被抽到的频率越高,而越靠近minmax边界的值被抽到的频率越低。大约 67% 的值会落在区间中部1.0 / parameter这一段内,也就是均值两侧各占区间长度0.5 / parameter的范围内;约 95% 的值会落在区间中部2.0 / parameter这一段内,也就是均值两侧各占区间长度1.0 / parameter的范围内。例如,如果parameter为 4.0,则 67% 的值会落在区间中间四分之一(1.0 / 4.0)内,也就是从3.0 / 8.05.0 / 8.0;95% 的值会落在区间中间一半(2.0 / 4.0)内,也就是第二和第三四分位。考虑到 Box-Muller 变换的性能,parameter的最小值为 2.0。 + @@ -983,8 +984,7 @@ END;
- 下面是单个客户端运行时生成的日志文件片段: - + 这里是在单个客户端运行中生成的一个日志文件的片段: 0 199 2241 0 1175850568 995598 0 200 2465 0 1175850568 998079 @@ -992,9 +992,8 @@ END; 0 202 2038 0 1175850569 2663 - 下面是另一个使用 --rate=100 和 --latency-limit=5 的示例(请注意额外的 - schedule_lag 列): - + 另一个示例使用的是--rate=100以及--latency-limit=5(注意额外的 + schedule_lag列): 0 81 4621 0 1412881037 912698 3005 0 82 6173 0 1412881037 914578 4304 @@ -1004,7 +1003,8 @@ END; 0 84 4142 0 1412881037 918023 2333 0 85 2465 0 1412881037 919759 740 - 在这个示例中,事务 82 超时了,因为其延迟(6.173 ms)超过了 5 ms 的限制。接下来的两个事务被跳过,因为它们在开始前就已经超时。 + 在这个示例中,事务 82 迟到了,因为它的延迟(6.173 ms)超过了 + 5 ms 限制。接下来的两个事务被跳过,因为它们在开始之前就已经迟到了。 @@ -1023,13 +1023,13 @@ END; 其中, - interval_start 是时间区间的开始时间(以 Unix 纪元时间戳表示), - num_transactions 是区间内的事务数, + interval_start 是时间区间的开始时间(以 Unix 纪元时间戳表示), + num_transactions 是区间内的事务数, sum_latency 是区间内事务延迟的总和, sum_latency_2 是区间内事务延迟的平方和, - min_latency 是区间内的最小延迟,而 - max_latency 是区间内的最大延迟。接下来的字段 - sum_lag, sum_lag_2, min_lag 和 max_lag 仅在使用 @@ -1049,7 +1049,7 @@ END; - 逐语句报告 + 逐语句延迟 使用选项时,pgbench会收集每个客户端执行的每条语句所经过的事务时间。基准测试完成后,它会报告这些值的平均值,称为每条语句的延迟。 @@ -1087,11 +1087,11 @@ script statistics: - 所有数值都是针对每个客户端执行的每条语句计算的,并在基准测试完成后报告。 + 如果指定了多个脚本文件,则会分别为每个脚本文件报告平均值。 - 请注意,收集计算每条语句延迟所需的额外计时信息会增加一些开销。这会降低平均执行速度,使计算出的 TPS 下降。减速程度因平台和硬件而异,差别可能很大。比较启用和未启用延迟报告时的平均 TPS 值,是衡量计时开销是否显著的好方法。 + 注意,为逐语句延迟计算收集额外的计时信息会带来一定开销。这会拖慢平均执行速度,并降低计算出的 TPS。减速幅度在很大程度上取决于平台和硬件。比较启用和未启用延迟报告时的平均 TPS 值,是判断这一计时开销是否显著的好方法。 @@ -1112,7 +1112,7 @@ script statistics: - 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和空闲空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 + 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和无效空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 diff --git a/zh/10/ref/psql-ref.sgml b/zh/10/ref/psql-ref.sgml index 4bc80215..355c4a41 100644 --- a/zh/10/ref/psql-ref.sgml +++ b/zh/10/ref/psql-ref.sgml @@ -47,7 +47,7 @@ PostgreSQL documentation - 把所有非空输入行按照它们被读入的形式打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 + 在读入时将所有非空输入行打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 all @@ -78,10 +78,10 @@ PostgreSQL documentation - 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,直到它处理完序列中所有的选项之后终止。 + 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,而是在按顺序处理完所有选项后终止。 - command必须是一个服务器完全可解析的命令字符串(即不包含psql相关的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: + command必须是一个服务器完全可解析的命令字符串(即不包含psql专有的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: psql -c '\x' -c 'SELECT * FROM foo;' @@ -94,8 +94,8 @@ echo '\x \\ SELECT * FROM foo;' | psql 每个SQL命令字符串传递给都作为一个单独的查询发送到服务器。 因此,即使字符串包含多个SQL命令,服务器也会将其作为单个事务执行, - 除非字符串中包含明确的BEGIN/COMMIT命令将其分成多个事务。 - + 除非字符串中包含显式的BEGIN/COMMIT命令将其分成多个事务。 + 此外,psql只打印字符串中最后一条SQL命令的结果。这与从文件读取同一字符串或将其送入psql标准输入时的行为不同,因为在这些情况下,psql会分别发送每条SQL命令。 @@ -149,7 +149,7 @@ EOF - 如果filename-(连字符),则会读取标准输入,直到遇到 EOF 指示或\q元命令。这可用于将交互式输入与文件输入交错使用。不过请注意,这种情况下不会使用 Readline(很像指定了时的情况)。 + 如果filename-(连字符),则会读取标准输入,直到遇到 EOF 指示或\q元命令。这可用于将交互式输入与文件输入交错使用。不过请注意,这种情况下不会使用 Readline(很像指定了时的情况)。 @@ -163,7 +163,7 @@ EOF - 使用separator作为非对齐输出的域分隔符。这等效于\pset fieldsep或者\f。 + 使用separator作为非对齐输出的字段分隔符。这等效于\pset fieldsep或者\f @@ -183,7 +183,7 @@ EOF - 切换到HTML输出模式。这等效于\pset format html或者\H命令。 + 切换到HTML表格输出模式。这等效于\pset format html或者\H命令。 @@ -217,7 +217,7 @@ EOF - 不要使用Readline进行行编辑,也不要使用命令历史记录。这有助于在剪切和粘贴时关闭制表符展开。 + 不要使用Readline进行行编辑,也不要使用命令历史记录。这有助于在剪切和粘贴时关闭TAB 补全。 @@ -237,7 +237,7 @@ EOF - 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。 + 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展名。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。 @@ -257,7 +257,7 @@ EOF - 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息以及多种输出。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon。 + 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息和各种提示信息。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon @@ -277,7 +277,7 @@ EOF - 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户一个可以取消执行的选项。使用这个选项可以调试脚本。 + 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户,并允许取消执行。使用这个选项可以调试脚本。 @@ -287,7 +287,7 @@ EOF - 运行在单行模式中,其中新行会终止一个 SQL 命令,就像分号的作用一样。 + 运行在单行模式中,其中换行符会终止一个 SQL 命令,就像分号的作用一样。 @@ -313,7 +313,7 @@ EOF - 指定要替换HTML table标签的选项。详见\pset tableattr。 + 指定要放在HTML table标签内的选项。详见\pset tableattr @@ -334,7 +334,7 @@ EOF - 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要重置一个变量,去掉等号就行。要把一个变量置为空值,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 + 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要取消变量的设置,去掉等号就行。要把一个变量设为空字符串,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 @@ -396,7 +396,7 @@ EOF - 不读取启动文件(要么是系统范围的psqlrc文件,要么是用户的~/.psqlrc文件)。 + 不读取启动文件(既不读取系统范围的psqlrc文件,也不读取用户的~/.psqlrc文件)。 @@ -406,7 +406,7 @@ EOF - 设置非对齐输出的域分隔符为零字节。这等效于\pset fieldsep_zero。 + 设置非对齐输出的字段分隔符为零字节。这等效于\pset fieldsep_zero @@ -416,7 +416,7 @@ EOF - 设置非对齐输出的记录分隔符为零字节。例如,这对与xargs -0配合有关。这等效于\pset recordsep_zero。 + 设置非对齐输出的记录分隔符为零字节。例如,这有助于与xargs -0配合使用。这等效于\pset recordsep_zero @@ -476,10 +476,9 @@ EOF 分别指定这些参数。如果遇到一个不属于任何选项的参数, 它将被解释为数据库名(如果数据库名已经给出,则解释为数据库用户名)。 并非所有这些选项都是必需的;它们都有有用的默认值。如果省略主机名, - psql 在 Unix 上将通过 Unix 域套接字连接到本地主机上的服务器, - 在 Windows 上则通过 TCP/IP 连接到 localhost。默认端口号在编译时确定。 + psql 将通过 Unix 域套接字连接到本地主机上的服务器,而在没有 Unix 域套接字的机器上则通过 TCP/IP 连接到 localhost。默认端口号在编译时确定。 由于数据库服务器使用相同的默认值,因此在大多数情况下不必指定端口。 - 默认数据库用户名是你的操作系统用户名。数据库用户名确定后,它也会被用作默认数据库名。 + 默认用户名是你的操作系统用户名,默认数据库名也是如此。 请注意,你不能随意以任意数据库用户名连接到任意数据库。数据库管理员应当已经告知你拥有的访问权限。 @@ -538,7 +537,7 @@ testdb=> 元命令 - 你输入到psql中的任何以未加引用的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 + 你输入到psql中的任何以未加引号的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 @@ -554,7 +553,7 @@ testdb=> 如下面所述。其中介绍的:'variable_name':"variable_name"形式也同样适用。 - 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉尾随换行)会替换反引号中的文本。在反引号包围的文本内部,不会发生特殊引用或其他处理,只有一种例外:如果出现:variable_name,且variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会被适当地引用成单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于回车和换行字符在所有平台上都无法安全引用,当变量值中出现这类字符时,:'variable_name'这种形式会打印错误消息,并且不会替换变量值。 + 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉末尾的换行符)会替换反引号中的文本。在反引号包围的文本内部,不会进行特殊的引号处理或其他处理,但出现:variable_name时,如果variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会适当地加上引号,使其成为单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于无法保证在所有平台上都能对回车和换行字符安全地加引号,当变量值中出现这类字符时,:'variable_name'形式会打印错误消息,并且不会替换变量值。 @@ -577,7 +576,7 @@ testdb=> \a - 如果当前表格输出格式是不对齐,则切换为对齐;否则切换为不对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset。 + 如果当前表格输出格式是非对齐,则切换为对齐;否则切换为非对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset @@ -598,7 +597,7 @@ testdb=> 默认情况下,参数在位置语法中被重用,但在给定conninfo字符串时不会被重用。 传递-reuse-previous=on-reuse-previous=off作为第一个参数将覆盖该默认设置。 如果参数被重用,则任何未明确指定为位置参数或在conninfo字符串中的参数将从现有连接的参数中获取。 - 一个例外是,如果使用位置语法将host设置更改为其先前值,则现有连接参数中存在的任何hostaddr设置将被删除。 + 一个例外是,如果使用位置语法更改host设置,使其不同于先前的值,则现有连接参数中存在的任何hostaddr设置将被删除。 此外,仅当用户、主机和端口设置未更改时,才会重用现有连接使用的任何密码。 当命令既不指定也不重用特定参数时,将使用libpq的默认值。 @@ -614,7 +613,7 @@ testdb=> => \c mydb myuser host.dom 6432 => \c service=foo => \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable" -=> \c -reuse-previous=on sslmode=require -- changes only sslmode +=> \c -reuse-previous=on sslmode=require -- 仅更改 sslmode => \c postgresql://tom@localhost/mydb?application_name=myapp @@ -760,7 +759,7 @@ testdb=> \dA[+] [ pattern ] - 列出访问方法。如果指定了pattern,则只显示名称匹配该模式的访问方法。如果在命令名后附加+,还会列出每个访问方法关联的处理函数和描述。 + 列出访问方法。如果指定了pattern,则只显示名称匹配该模式的访问方法。如果在命令名后附加+,还会列出每个访问方法关联的处理器函数和描述。 @@ -885,28 +884,28 @@ testdb=> \dF[+] [ pattern ] - 列出文本搜索配置。如果指定了pattern,则只显示名称匹配该模式的配置。如果使用\dF+形式,则显示每个配置的完整说明,包括底层文本搜索解析器和每种解析器词元类型的词典列表。 + 列出全文检索配置。如果指定了pattern,则只显示名称匹配该模式的配置。如果使用\dF+形式,则显示每个配置的完整说明,包括底层全文检索解析器和每种解析器词元类型的词典列表。 \dFd[+] [ pattern ] - 列出文本搜索词典。如果指定了pattern,则只显示名称匹配该模式的词典。如果使用\dFd+形式,还会显示每个选中词典的附加信息,包括底层文本搜索模板和选项值。 + 列出全文检索词典。如果指定了pattern,则只显示名称匹配该模式的词典。如果使用\dFd+形式,还会显示每个选中词典的附加信息,包括底层全文检索模板和选项值。 \dFp[+] [ pattern ] - 列出文本搜索解析器。如果指定了pattern,则只显示名称匹配该模式的解析器。如果使用\dFp+形式,则显示每个解析器的完整说明,包括底层函数和可识别的词元类型列表。 + 列出全文检索解析器。如果指定了pattern,则只显示名称匹配该模式的解析器。如果使用\dFp+形式,则显示每个解析器的完整说明,包括底层函数和可识别的词元类型列表。 \dFt[+] [ pattern ] - 列出文本搜索模板。如果指定了pattern,则只显示名称匹配该模式的模板。如果使用\dFt+形式,还会显示每个模板的附加信息,包括底层函数名。 + 列出全文检索模板。如果指定了pattern,则只显示名称匹配该模式的模板。如果使用\dFt+形式,还会显示每个模板的附加信息,包括底层函数名。 @@ -929,7 +928,7 @@ testdb=> \dL[S+] [ pattern ] - 列出过程语言。如果指定了pattern,则只列出名称匹配该模式的语言。默认只显示用户创建的语言;提供S修饰符可包含系统对象。如果在命令名后附加+,还会列出每种语言的调用处理程序、验证器、访问权限,以及它是否为系统对象。 + 列出过程语言。如果指定了pattern,则只列出名称匹配该模式的语言。默认只显示用户创建的语言;提供S修饰符可包含系统对象。如果在命令名后附加+,还会列出每种语言的调用处理器、验证器、访问权限,以及它是否为系统对象。 @@ -971,7 +970,7 @@ testdb=> \drds [ role-pattern [ database-pattern ] ] - 列出已定义的配置设置。这些设置可以专属于角色、专属于数据库,或同时专属于两者。role-patterndatabase-pattern分别用于选择要列出的特定角色和数据库。如果省略,或指定了*,则列出所有设置,分别包括非角色专属或非数据库专属的设置。 + 列出已定义的配置设置。这些设置可以特定于角色、特定于数据库,或同时特定于两者。role-patterndatabase-pattern分别用于选择要列出的角色和数据库。省略某个模式参数或将其指定为*时,不会按该参数筛选,还会分别包含不特定于角色或不特定于数据库的设置。 命令用于定义角色专属和数据库专属的配置设置。 @@ -1087,7 +1086,9 @@ Tue Oct 26 21:40:57 CEST 1999 \encoding [ encoding ] - 设置客户端字符集编码。如果没有参数,则显示当前编码。 + + 设置客户端字符集编码。没有参数时,此命令显示当前编码。 + @@ -1133,7 +1134,7 @@ Tue Oct 26 21:40:57 CEST 1999 - 设置未对齐查询输出的字段分隔符。默认值是竖线(|)。 + 设置非对齐查询输出的字段分隔符。默认值是竖线(|)。 它等同于\pset fieldsep @@ -1149,7 +1150,7 @@ Tue Oct 26 21:40:57 CEST 1999 如果当前查询缓冲区为空,则最近发送的查询将被重新执行。除此之外,没有任何参数的\g基本上等同于一个分号。 带有参数的\g提供了一个一次性替代\o命令的选择。 - 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号展开。该行剩余的内容只会原样传递给 shell。 + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 @@ -1192,7 +1193,7 @@ CREATE INDEX hello 10
- 如果指定了前缀,则会将该字符串加到查询的列名前面,以构成要使用的变量名: + 如果指定了prefix,则会将该字符串加到查询的列名前面,以构成要使用的变量名: => SELECT 'hello' AS var1, 10 AS var2 -> \gset result_ => \echo :result_var1 :result_var2 @@ -1221,7 +1222,7 @@ hello 10 给出指定SQL命令的语法帮助。如果未指定command, 则psql将列出所有可用语法帮助的命令。如果command是星号 - (*),则显示所有SQL命令的语法帮助。 + (*),则显示所有SQL命令的语法帮助。 @@ -1242,9 +1243,7 @@ hello 10 \H\html - 打开HTML查询输出格式。如果HTML格式已经打开, - 则切换回默认的对齐文本格式。此命令用于兼容性和便利性,但请参阅\pset - 有关设置其他输出选项。 + 打开HTML查询输出格式。如果HTML格式已经打开,则切换回默认的对齐文本格式。此命令是为兼容性和便利性而保留的;设置其他输出选项的方法见\pset @@ -1254,13 +1253,10 @@ hello 10 \i\include filename - 从文件filename中读取输入,并将其执行为 - 好像它是在键盘上键入的一样。 + 从文件filename中读取输入,并像在键盘上输入一样执行它。 - 如果filename- - (连字符),那么标准输入将被读取,直到EOF指示或\q元命令。 - 这可用于将交互式输入与文件输入交错使用。请注意,仅当在最外层级别处于活动状态时,Readline行为才会被使用。 + 如果filename-(连字符),则从标准输入读取,直到遇到 EOF 指示或\q元命令。这可用于将交互式输入与文件输入交错使用。请注意,只有在最外层启用了 Readline,此处才会使用 Readline 功能。 @@ -1279,36 +1275,20 @@ hello 10 这组命令实现了可嵌套的条件块。条件块必须以\if开始,以\endif结束。中间可以包含任意数量的\elif子句,后面还可以选择跟随一个\else子句。普通查询和其他类型的反斜线命令可以(通常也会)出现在构成条件块的命令之间。 - \if\elif命令读取它们的参数,并将其作为布尔表达式进行评估。 - 如果表达式为true,则处理将继续进行;否则,直到达到匹配的\elif、 - \else\endif为止,将跳过行。一旦\if或 - \elif测试成功,同一块中后续\elif命令的参数不会被评估,而是被视为false。 - 在\else之后的行只有在没有早期匹配的\if\elif成功时才会被处理。 + \if\elif命令读取其参数,并将其作为布尔表达式求值。如果表达式的值为true,则正常继续处理;否则,跳过后续行,直到遇到匹配的\elif\else\endif。一旦\if\elif测试成功,同一块中后续\elif命令的参数就不再求值,而是被视为假。只有前面所有匹配的\if\elif测试都未成功时,才会处理\else后面的行。 - expression参数 - 是\if\elif命令的参数, - 受变量插值和反引号扩展的影响,就像任何其他反斜杠命令参数一样。 - 之后,它被评估为一个开/关选项变量的值。因此,有效值是以下任何一个不 - 含糊的不区分大小写匹配之一: - true, false, 1, - 0, on, off, - yes, no。例如, - t, TtR - 都将被视为true。 + 与其他反斜线命令的参数一样,\if\elif命令的expression参数会经过变量插值和反引号扩展。随后,按开/关选项变量值的规则对结果求值。因此,有效值是以下值的不区分大小写且无歧义的匹配:truefalse10onoffyesno。例如,tTtR都会被视为true 不能正确求值为真或假的表达式会产生警告,并被视为假。 - 被跳过的行仍会正常解析,以识别查询和反斜线命令,但查询不会发送给服务器,条件命令(\if\elif\else\endif)以外的反斜线命令会被忽略。对于条件命令,只检查嵌套是否合法。被跳过的行中的变量引用不会展开,也不会执行反引号展开。 + 被跳过的行仍会正常解析,以识别查询和反斜线命令,但查询不会发送给服务器,条件命令(\if\elif\else\endif)以外的反斜线命令会被忽略。对于条件命令,只检查嵌套是否合法。被跳过的行中的变量引用不会展开,也不会执行反引号扩展。 - 所有给定条件块的反斜杠命令必须出现在同一个源文件中。如果在主输入文件或一个 - \include的文件上达到文件结束之前,所有本地 - \if块都没有关闭, - 那么psql将会引发错误。 + 同一个条件块的所有反斜线命令必须出现在同一个源文件中。如果主输入文件或通过\include引入的文件到达 EOF 时,仍有本地\if块未关闭,psql就会报错。 下面是一个示例: --- check for the existence of two separate records in the database and store --- the results in separate psql variables +-- 检查数据库中是否存在两条不同的记录,并将 +-- 结果分别存入不同的 psql 变量 SELECT EXISTS(SELECT 1 FROM customer WHERE customer_id = 123) as is_customer, EXISTS(SELECT 1 FROM employee WHERE employee_id = 456) as is_employee @@ -1354,7 +1334,7 @@ SELECT 从数据库中读取具有OIDloid的大对象,并将其写入filename。请注意,这与服务器函数 - lo_export略有不同,后者使用数据库服务器运行的用户权限, + lo_export略有不同,后者使用运行数据库服务器的用户的权限, 并在服务器的文件系统上操作。 @@ -1393,7 +1373,7 @@ lo_import 152801 - 从数据库中删除具有OIDloid的大对象。 + 从数据库中删除OIDloid的大对象。 @@ -1411,10 +1391,10 @@ lo_import 152801 将后续查询结果保存到文件filename,或通过管道传给 shell 命令command。如果没有指定参数,查询输出将恢复为标准输出。 - 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号展开。该行剩余的内容只会原样传递给 shell。 + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 - 查询结果包括从数据库服务器获取的所有表、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 + 查询结果包括从数据库服务器获取的所有表格、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 @@ -1429,7 +1409,10 @@ lo_import 152801 \p\print - 将当前查询缓冲区打印到标准输出。如果当前查询缓冲区为空,则改为打印最近执行的查询。 + + 将当前查询缓冲区打印到标准输出。 + 如果当前查询缓冲区为空,则打印最近执行的查询。 + @@ -1485,7 +1468,7 @@ lo_import 152801 零(默认值)会导致目标宽度由环境变量COLUMNS控制,或者如果未设置 COLUMNS则由检测到的屏幕宽度控制。 另外,如果columns为零,则wrapped格式仅影响屏幕输出。 - 如果columns为非零,则文件和管道输出也会被包装到该宽度。 + 如果columns为非零,则文件和管道输出也会按该宽度折行。 @@ -1530,11 +1513,11 @@ lo_import 152801 wrapped格式与aligned相似,但会将较宽的数据值折成多行,使输出适应目标列宽。目标宽度的确定方式见columns选项的说明。请注意,psql不会尝试对列标题折行;因此,如果列标题所需的总宽度超过目标宽度,wrapped格式的行为就与aligned相同。 - asciidochtml, - latexlatex-longtable,和 + asciidochtml、 + latexlatex-longtabletroff-ms格式生成的表格旨在包含在使用相应标记语言的文档中。 它们不是完整的文档!这在HTML中可能不是必需的,但在 - LaTeX中,则必须有一个完整的文档包装器。 + LaTeX中,则必须有一个完整文档的外层结构。 latex-longtable格式需要LaTeXlongtablebooktabs包。 @@ -1552,25 +1535,19 @@ lo_import 152801 - ascii样式使用普通的ASCII字符。数据中的换行使用右边边缘的+符号显示。 - 当wrapped格式将数据从一行换到下一行而没有换行符时,在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 + ascii样式使用普通的ASCII字符。数据中的换行符以右边缘的+符号表示。当wrapped格式在没有换行符的位置把数据折到下一行时,会在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 - old-ascii样式使用普通的ASCII字符,使用在PostgreSQL 8.4及更早版本中使用的格式样式。 - 数据中的换行符使用:符号代替左侧列分隔符显示。 - 当数据从一行换行到下一行而没有换行符时,使用;符号代替左侧列分隔符。 + old-ascii样式使用普通的ASCII字符,采用PostgreSQL 8.4 及更早版本的格式样式。数据中的换行符以替代左侧列分隔符的:符号表示。当数据在没有换行符的位置折到下一行时,则用;符号替代左侧列分隔符。 - unicode样式使用Unicode绘图字符。数据中的换行使用右边距中的回车符号显示。 - 当数据从一行换行到下一行而没有换行符时,第一行的右边距显示省略号符号, - 接着在下一行的左边距再次显示省略号符号。 + unicode样式使用 Unicode 框线绘制字符。数据中的换行符以右边缘的回车符号表示。当数据在没有换行符的位置折到下一行时,会在第一行的右边缘显示省略号符号,并在下一行的左边缘再次显示。 - 当border设置大于零时,linestyle选项还确定了用哪些字符绘制边框线。 - 普通的ASCII字符在任何地方都有效,但在识别Unicode字符的显示器上看起来更好。 + 当border设置大于零时,linestyle选项还决定用哪些字符绘制边框线。普通的ASCII字符在任何环境中都可用,但在支持 Unicode 的显示设备上,Unicode 字符更美观。 @@ -1690,7 +1667,7 @@ lo_import 152801 \qecho text [ ... ] - 这个命令与\echo命令相同,只是输出将被写入查询输出通道,由\o设置。 + 这个命令与\echo相同,只是输出会写入由\o设置的查询输出通道。 @@ -1720,8 +1697,7 @@ lo_import 152801 \set [ name [ value [ ... ] ] ] - psql变量name设置为,如果给出多个值,则设置为所有值的串接。如果只给出一个参数,则将变量设置为空字符串值。要取消变量设置,请使用\unset命令。 + psql变量name设置为value,如果给出多个值,则设置为所有值的串接。如果只给出一个参数,则将变量设置为空字符串值。要取消变量设置,请使用\unset命令。 \set没有任何参数时,显示当前设置的所有psql变量的名称和值。 @@ -1742,8 +1718,10 @@ lo_import 152801 \setenv name [ value ] - 将环境变量name设置为;如果没有提供,则取消设置该环境变量。例如: + + 设置环境变量namevalue, + 或者如果未提供value,则取消设置环境变量。示例: + testdb=> \setenv PAGER less testdb=> \setenv LESS -imx4F @@ -1776,8 +1754,7 @@ testdb=> \setenv LESS -imx4F - 这个命令获取并显示指定视图的定义,以CREATE OR REPLACE VIEW命令的形式。 - 定义将打印到当前查询输出通道,由\o设置。 + 这个命令获取指定视图的定义,并以CREATE OR REPLACE VIEW命令的形式显示。定义会打印到由\o设置的当前查询输出通道。 @@ -1833,7 +1810,7 @@ testdb=> \setenv LESS -imx4F 将当前查询缓冲区写入文件filename,或通过管道传递给 shell 命令command。如果当前查询缓冲区为空,则改为写入最近执行的查询。 - 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号展开。该行剩余的内容只会原样传递给 shell。 + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 @@ -1841,8 +1818,13 @@ testdb=> \setenv LESS -imx4F \watch [ seconds ] - 重复执行当前查询缓冲区(如同\g),直到被中断或查询失败。每次执行之间等待指定的秒数(默认为 2)。每个查询结果都会显示一个标题,其中包含\pset title字符串(如果有)、查询开始时间和延迟间隔。 - 如果当前查询缓冲区为空,则改为重新执行最近发送的查询。 + + 重复执行当前查询缓冲区(如同 \g 一样),直到被中断或查询失败。两次执行之间等待指定的秒数(默认 2 秒)。每次查询结果都会带有一个头部,其中包含 \pset title + 字符串(如果有)、查询开始时的时间以及延迟间隔。 + + + 如果当前查询缓冲区为空,则重新执行最近发送的查询。 + @@ -1871,13 +1853,11 @@ testdb=> \setenv LESS -imx4F \! [ command ] - 不带参数时,转义到一个子shell;psql在子shell退出时恢复。 - 带参数时,执行shell命令command。 + 不带参数时,进入一个子 shell;子 shell 退出后,psql恢复运行。带参数时,执行 shell 命令command - 与大多数其他元命令不同,整个行的剩余部分始终被视为\!的参数, - 在参数中不执行变量插值或反引号扩展。行的其余部分被直接传递给shell。 + 与大多数其他元命令不同,该行剩余的全部内容始终被视为\!的参数,其中不会进行变量插值或反引号扩展。该行剩余内容会原样传给 shell。 @@ -1889,7 +1869,7 @@ testdb=> \setenv LESS -imx4F 显示帮助信息。可选的topic参数 (默认为commands)选择要解释的psql的哪个部分: - commands描述psql的反斜杠命令; + commands描述psql的反斜线命令; options描述可以传递给psql的命令行选项; 而variables显示关于psql配置变量的帮助。 @@ -1903,12 +1883,12 @@ testdb=> \setenv LESS -imx4F 模式 - patterns + 模式 在 psql 和 pg_dump 中 - 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要把它写成两个相邻的双引号,这同样是符合 SQL 引用标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你不能只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 + 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要在双引号包围的文本内把它写成两个相邻的双引号,这同样是符合 SQL 加引号标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你可以只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 @@ -1952,7 +1932,7 @@ bar - 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要重置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 + 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要取消设置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 @@ -1966,7 +1946,7 @@ bar - 控制psql行为的变量通常不能被重置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse。 + 控制psql行为的变量通常不能被取消设置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse @@ -1984,7 +1964,7 @@ bar - 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被重置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交打开模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身即不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 + 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被取消设置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交关闭模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身既不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 @@ -2014,7 +1994,7 @@ bar DBNAME - 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -2023,7 +2003,7 @@ bar ECHO - 如果被设置为all,所有非空输入行会被按照读入它们的样子打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被重置或者设置为none(默认值)则不会显示任何查询。 + 如果被设置为all,所有非空输入行会在读入时打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被设置为none(默认值)则不会显示任何查询。 @@ -2041,7 +2021,7 @@ bar ENCODING - 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者重置。 + 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者取消设置。 @@ -2050,12 +2030,12 @@ bar FETCH_COUNT - 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每一组就会包括这么多个行。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 + 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每组包含的行数等于该整数值。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 - 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT个行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 + 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 @@ -2065,7 +2045,7 @@ bar HISTCONTROL - 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则匹配之前的历史行的行不会被放入。值ignoreboth组合了上述两种值。如果被重置或者被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 + 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则与上一条历史记录相同的行不会被放入。值ignoreboth组合了上述两种值。如果被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 @@ -2107,7 +2087,7 @@ bar HOST - 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -2116,7 +2096,7 @@ bar IGNOREEOF - 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须键入多个连续的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 + 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须连续键入与该数值相等数量的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 @@ -2144,7 +2124,7 @@ bar - 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被重置或者设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 + 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 @@ -2162,7 +2142,7 @@ bar PORT - 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -2194,7 +2174,7 @@ bar SERVER_VERSION_NUM - 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者重设。 + 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者取消设置。 @@ -2203,7 +2183,7 @@ bar SHOW_CONTEXT - 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT域。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 + 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT字段。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 当VERBOSITY被设置为terse时,这个设置无效(另见\errverbose,它可以用来得到刚遇到的错误的详细信息)。 @@ -2222,7 +2202,7 @@ bar SINGLESTEP - 设置这个变量为on等效于命令选项。 + 设置这个变量为on等效于命令行选项 @@ -2231,7 +2211,7 @@ bar USER - 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -2240,7 +2220,7 @@ bar VERBOSITY - 这个变量可以被设置为值defaultverbose或者terse来控制错误报告的详细程度(另见\errverbose,在想得到之前的错误的详细版本时使用)。 + 这个变量可以被设置为值defaultverbose或者terse来控制错误报告的详细程度(另见\errverbose,在想得到刚遇到的错误的详细信息时使用)。 @@ -2251,7 +2231,7 @@ bar VERSION_NUM - 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或重设。 + 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或取消设置。 @@ -2261,10 +2241,10 @@ bar - <acronym>SQL</acronym> 中插入变量 + <acronym>SQL</acronym> 插值 - psql变量的一个关键特性是可以把它们替换(插入)到常规SQL语句中,也可以把它们作为元命令的参数。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。插入一个值而不加引号的语法是在变量名前面加上一个冒号(:)。例如, + psql变量的一个关键特性是可以把它们替换(插值)到常规SQL语句中,也可以把它们替换到元命令的参数中。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。不加引号地插值一个值的语法是在变量名前面加上一个冒号(:)。例如, testdb=> \set foo 'my_table' testdb=> SELECT * FROM :foo; @@ -2273,7 +2253,7 @@ testdb=> SELECT * FROM :foo; - 当一个值被用作 SQL 文本或者标识符时,最安全的是把它加上引用。要引用一个变量的值作为 SQL 文本,可以把变量名称放在单引号中并且在引号前面写一个冒号。要引用作为 SQL 标识符,则可以把变量名称放在双引号中并且在引号前面写一个冒号。这种结构可以正确地处理变量值中嵌入的引号和其他特殊字符。之前的示例用这种方法写会更安全: + 当一个值要用作 SQL 字面量或标识符时,最安全的做法是为它加上引号。要将变量值作为 SQL 字面量加引号,应写一个冒号,后面跟用单引号括起来的变量名。要将变量值作为 SQL 标识符加引号,则在冒号后面用双引号括起变量名。这些写法能正确处理变量值中嵌入的引号和其他特殊字符。前面的示例可用以下更安全的写法: testdb=> \set foo 'my_table' testdb=> SELECT * FROM :"foo"; @@ -2281,11 +2261,11 @@ testdb=> SELECT * FROM :"foo"; - 在被引用的SQL文本和标识符中将不会执行变量插入。因此,一个诸如':foo'的结构不会从一个变量的值产生一个被引用的文本(即便能够也会不安全,因为无法正确地处理嵌入在值中的引号)。 + 在加引号的SQL字面量和标识符内部,不会执行变量插值。因此,':foo'这样的写法不能根据变量值生成加引号的字面量(即使能够生效,也不安全,因为它无法正确处理变量值中嵌入的引号)。 - 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个被引用的字符串插入: + 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个加引号的字符串进行插值: testdb=> \set content `cat my_file.txt` testdb=> INSERT INTO my_table VALUES (:'content'); @@ -2294,11 +2274,11 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 因为冒号可以合法地出现在 SQL 命令中,一次明显的插入尝试(即:name:'name'或者:"name")不会被替换,除非所提及的变量就是当前被设置的。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 + 因为冒号可以合法地出现在 SQL 命令中,一次明显的插值尝试(即:name:'name'或者:"name")不会被替换,除非所指的变量当前已设置。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 - 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 文本或者标识符的冒号引用语法是一种psql扩展。 + 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 字面量或者标识符的冒号加引号语法是一种psql扩展。 @@ -2333,7 +2313,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %n - 数据库会话用户名。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的展开结果。) + 数据库会话用户名。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) @@ -2344,20 +2324,21 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %~ - %/相同,但如果该数据库是你的默认数据库,则输出~(波浪号)。 + 类似 %/,但如果该数据库是你的默认数据库,则输出 ~ + (波浪号)。 %# - 如果会话用户是数据库超级用户,则为#,否则为>。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的展开结果。) + 如果会话用户是数据库超级用户,则为#,否则为>。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) %p - 当前连接的后端的进程 ID。 + 当前所连接后端的进程 ID。 @@ -2365,7 +2346,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %R - 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 dollar-quoted 字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 + 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 美元引用字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 @@ -2392,7 +2373,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %digits - 带有所示八进制码的字符被替换。 + 替换为指定八进制代码对应的字符。 @@ -2449,7 +2430,7 @@ testdb=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# ' psql支持 Readline 库,便于编辑和检索输入行。命令历史记录会在 psql 退出时自动保存,并在 psql 启动时重新载入。也支持 Tab 补全,不过其补全逻辑并不声称自己是 SQL 解析器。Tab 补全生成的查询还可能干扰其他 SQL 命令,例如 SET - TRANSACTION ISOLATION LEVEL。如果出于某种原因你不喜欢 Tab 补全,可以将以下内容放入主目录下名为 .inputrc 的文件中,将其关闭: + TRANSACTION ISOLATION LEVEL。如果出于某种原因你不喜欢 Tab 补全,可以将以下内容放入主目录下名为 .inputrc 的文件中,将其关闭: $if psql set disable-completion on $endif @@ -2591,11 +2572,11 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' 用户的个人启动文件名为.psqlrc,并且在调用用户的主目录中寻找。 - 在Windows上,个人启动文件的名称改为%APPDATA%\postgresql\psqlrc.conf。 + Windows 没有主目录这一概念,在 Windows 上,个人启动文件的名称为%APPDATA%\postgresql\psqlrc.conf。 在任何情况下,可以通过设置PSQLRC环境变量来覆盖此默认文件路径。 - 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加连字符和PostgreSQL的主版本或次版本号来使其与psql版本相关, + 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加连字符和PostgreSQL的大版本或小版本号来使其与psql版本相关, 例如~/.psqlrc-9.2~/.psqlrc-9.2.5。 最具体版本匹配的文件将优先读取,而不是非特定版本的文件。 @@ -2622,14 +2603,14 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - psql最适合与相同或较旧主要版本的服务器配合使用。 - 如果服务器的版本比psql本身更新,反斜杠命令特别容易失败。 - 然而,\d系列的反斜杠命令应该可以在版本回溯到9.2的服务器上运行, + psql最适合与相同或较旧大版本的服务器配合使用。 + 如果服务器的版本比psql本身更新,反斜线命令特别容易失败。 + 然而,\d系列的反斜线命令应该可以在最低至 7.4 版本的服务器上运行, 但不一定适用于比psql本身更新的服务器。运行SQL命令和显示查询结果的一般功能 - 也应该可以在更新主要版本的服务器上运行,但不能保证在所有情况下都能实现。 + 也应该可以在更新大版本的服务器上运行,但不能保证在所有情况下都能实现。 - 如果你想用psql连接到多个具有不同主版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个主版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 + 如果你想用psql连接到多个具有不同大版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个大版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 @@ -2643,7 +2624,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空格。现在则要求一些空格。 + 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空白。现在则要求用空白分隔。 @@ -2701,6 +2682,7 @@ peter@localhost testdb=> SELECT * FROM my_table; 3 | three 4 | four (4 rows) + 要以不同方式显示表格,可以使用\pset命令: peter@localhost testdb=> \pset border 2 Border style is 2. @@ -2779,10 +2761,10 @@ testdb=> \crosstabview first second (4 rows) 第二个示例显示一个乘法表,行按数值降序排列,列则独立地按数值升序排列。 testdb=> SELECT t1.first as "A", t2.first+100 AS "B", t1.first*(t2.first+100) as "AxB", -testdb(> row_number() over(order by t2.first) AS ord -testdb(> FROM my_table t1 CROSS JOIN my_table t2 ORDER BY 1 DESC -testdb(> \crosstabview "A" "B" "AxB" ord - A | 101 | 102 | 103 | 104 +testdb-> row_number() over(order by t2.first) AS ord +testdb-> FROM my_table t1 CROSS JOIN my_table t2 ORDER BY 1 DESC +testdb-> \crosstabview "A" "B" "AxB" ord + A | 101 | 102 | 103 | 104 ---+-----+-----+-----+----- 4 | 404 | 408 | 412 | 416 3 | 303 | 306 | 309 | 312 diff --git a/zh/10/release-10.sgml b/zh/10/release-10.sgml index daa65b92..f336ebaf 100644 --- a/zh/10/release-10.sgml +++ b/zh/10/release-10.sgml @@ -7519,7 +7519,7 @@ Branch: REL_11_STABLE [98a4d6950] 2020-04-27 12:21:04 -0400 Branch: REL_10_STABLE [072a86327] 2020-04-27 12:21:04 -0400 Branch: REL9_6_STABLE [22dcb6c20] 2020-04-27 12:21:04 -0400 --> - 修复全文搜索,使其正确处理短语搜索之上的 NOT(Tom Lane) + 修复全文检索,使其正确处理短语搜索之上的 NOT(Tom Lane) !(foo<->bar) 等查询在通过 GiST 或 GIN 索引搜索执行时,无法找到匹配行。 @@ -7533,7 +7533,7 @@ Branch: REL_11_STABLE [5db48808c] 2020-05-07 15:59:52 -0400 Branch: REL_10_STABLE [26cf16a93] 2020-05-07 15:59:52 -0400 Branch: REL9_6_STABLE [7c9d9aa5c] 2020-05-07 15:59:52 -0400 --> - 修复短语搜索包含同时具有前缀匹配和权重限制的项时的全文搜索(Tom Lane) + 修复短语搜索包含同时具有前缀匹配和权重限制的项时的全文检索(Tom Lane) @@ -9347,7 +9347,7 @@ Branch: REL_11_STABLE [88d03d73c] 2019-11-03 16:10:45 -0500 Branch: REL_10_STABLE [4077e9ae1] 2019-11-03 16:10:56 -0500 Branch: REL9_6_STABLE [d43bd9dce] 2019-11-03 16:11:05 -0500 --> - 避免 ispell 文本搜索词典包含错误的词缀数据时发生崩溃(Arthur Zakirov) + 避免 ispell 文本检索词典包含错误的词缀数据时发生崩溃(Arthur Zakirov) @@ -11869,7 +11869,7 @@ Branch: REL9_3_STABLE [591d0ac88] 2018-09-15 13:42:34 -0400 修复字符类检查,使其在 Windows 上不会因高于 U+FFFF 的 Unicode 字符而失败(Tom Lane,Kenji Uno) - 此缺陷影响全文搜索操作,以及 contrib/ltreecontrib/pg_trgm + 此缺陷影响全文检索操作,以及 contrib/ltreecontrib/pg_trgm @@ -12467,7 +12467,7 @@ Branch: REL9_5_STABLE [c79b39fb1] 2018-09-06 10:49:45 -0400 Branch: REL9_4_STABLE [d4ab39626] 2018-09-06 10:49:45 -0400 Branch: REL9_3_STABLE [25ff97ba7] 2018-09-06 10:49:45 -0400 --> - 修复 contrib/unaccentunaccent() 函数,使其使用与函数位于同一模式中的 unaccent 文本搜索词典(Tom Lane) + 修复 contrib/unaccentunaccent() 函数,使其使用与函数位于同一模式中的 unaccent 文本检索词典(Tom Lane) 以前,它尝试通过搜索路径查找词典;如果搜索路径设置受限,就可能失败。 @@ -13028,7 +13028,7 @@ Branch: REL9_3_STABLE [cbb37b2e1] 2018-05-24 12:07:42 -0400 --> 修复 getObjectDescriptiongetObjectIdentity 输出中某些对象名未加模式限定的问题(Kyotaro Horiguchi,Tom Lane) - 排序规则、转换、文本搜索对象、发布关系和扩展统计对象的名称,未在应当使用模式限定时加上限定。 + 排序规则、转换、文本检索对象、发布关系和扩展统计对象的名称,未在应当使用模式限定时加上限定。 @@ -15945,7 +15945,7 @@ Branch: REL_10_STABLE [5159626af] 2017-11-03 14:14:16 -0400 --> 移除 contrib/tsearch2 模块(Robert Haas) - 此模块用于兼容 PostgreSQL 8.3 之前的发行版所附带的全文搜索版本。 + 此模块用于兼容 PostgreSQL 8.3 之前的发行版所附带的全文检索版本。 @@ -16770,7 +16770,7 @@ This was disabled in the PG 9.6 branch so there is no commit here. - JSONJSONB 增加全文搜索支持(Dmitry Dolgov) + JSONJSONB 增加全文检索支持(Dmitry Dolgov) 现在可以将函数 ts_headline()to_tsvector() 用于这些数据类型。 diff --git a/zh/10/rowtypes.sgml b/zh/10/rowtypes.sgml index 00293d60..7f508227 100644 --- a/zh/10/rowtypes.sgml +++ b/zh/10/rowtypes.sgml @@ -68,7 +68,7 @@ CREATE TABLE inventory_item ( - 构造组合值 + 构造复合值 复合类型 @@ -76,7 +76,7 @@ CREATE TABLE inventory_item ( - 要把组合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,组合常量的一般格式如下: + 要把复合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,复合常量的一般格式如下: '( val1 , val2 , ... )' @@ -96,16 +96,21 @@ CREATE TABLE inventory_item ( - (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。必要时可能需要显式指定类型。) + (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。可能需要显式指定类型,以指明应将该常量转换为哪种类型。) - 这种ROW表达式语法也可以用于构造复合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: + + ROW表达式语法也可以用于构造复合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: + ROW('fuzzy dice', 42, 1.99) ROW('', 42, NULL) -只要表达式中有多个字段,ROW 关键字实际上是可选的,因此这些可以简写为: + + 只要表达式中有多个字段,ROW 关键字实际上是可选的,因此这些可以简写为: + ('fuzzy dice', 42, 1.99) ('', 42, NULL) -这种ROW表达式语法的更多细节见。 + + 关于ROW表达式语法的更多细节,见 @@ -114,7 +119,7 @@ ROW('', 42, NULL) 访问复合类型 - 要访问组合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: + 要访问复合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: SELECT item.name FROM on_hand WHERE item.price > 9.99; @@ -136,7 +141,7 @@ SELECT (on_hand.item).name FROM on_hand WHERE (on_hand.item).price > 9.99; - 无论何时从组合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回组合值的函数结果中只选取一个字段,你需要这样写: + 无论何时从复合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回复合值的函数结果中只选取一个字段,你需要这样写: SELECT (my_func(...)).field FROM ... @@ -151,10 +156,10 @@ SELECT (my_func(...)).field FROM ... - 修改组合值 + 修改复合类型 - 下面是一些插入和更新组合列时正确语法的示例。先看插入或更新整个列值的情况: + 下面是一些插入和更新复合列时正确语法的示例。先看插入或更新整个列值的情况: INSERT INTO mytab (complex_col) VALUES((1.1,2.2)); @@ -166,7 +171,7 @@ UPDATE mytab SET complex_col = ROW(1.1,2.2) WHERE ...; - 我们也可以更新组合列中的单个子字段: + 我们也可以更新复合列中的单个子字段: UPDATE mytab SET complex_col.r = (complex_col).r + 1 WHERE ...; @@ -194,11 +199,11 @@ INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2); - 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的组合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: + 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的复合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: SELECT c FROM inventory_item c; - 这个查询会产生一个单独的组合值列,因此我们可能得到如下输出: + 这个查询会产生一个单独的复合值列,因此我们可能得到如下输出: c ------------------------ @@ -209,7 +214,7 @@ SELECT c FROM inventory_item c; - 普通的限定列名语法table_name.column_name可以理解为对该表当前行的组合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) + 普通的限定列名语法table_name.column_name可以理解为对该表当前行的复合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) @@ -243,10 +248,15 @@ SELECT (m).* FROM (SELECT myfunc(x) AS m FROM some_table OFFSET 0) ss; - 这里的composite_value.*语法在以下结构的顶层出现时会产生这类列展开:(SELECT输出列表)、RETURNING列表(位于INSERT/UPDATE/DELETE)、VALUES子句,或行构造器。在所有其他上下文中(包括嵌套在上述结构之内时),将.*附加到复合值上不会改变该值,因为它表示所有列,因此结果仍然是同一个复合值。例如,如果somefunc()接受一个复合值参数,这些查询就是等价的: + + 当composite_value.*出现在SELECT输出列表、INSERT/UPDATE/DELETE中的RETURNING列表、VALUES子句或行构造器的顶层时,就会产生这种列展开行为。在所有其他上下文中(包括嵌套在上述结构之内时),给复合值附加.*不会改变其值,因为它表示所有列,因此结果仍然是同一个复合值。例如,如果somefunc()接受一个复合值参数,这些查询就是等价的: + + SELECT somefunc(c.*) FROM inventory_item c; SELECT somefunc(c) FROM inventory_item c; -在这两种情况下,inventory_item的当前行都会作为单个复合值参数传递给该函数。即使.*在这种情况下不起作用,使用它仍是良好的风格,因为它明确表示这里需要的是复合值。特别是,解析器会将c(位于c.*)解释为表名或别名,而不是列名,因此不存在歧义;但如果没有.*,就不能明确判断c表示表名还是列名,而且会优先采用列名解释,只要存在一列名为c。 + + + 在这两种情况下,inventory_item的当前行都会作为单个复合值参数传递给该函数。尽管.*在这种场合并不起作用,使用它仍是一种良好风格,因为它能明确表明这里想要的是复合值。特别是,解析器会把c.*中的c视为表名或别名,而不是列名,因此不会产生歧义;而没有.*时,就不清楚c究竟表示表名还是列名,而且如果存在名为c的列,实际上会优先按列名解释。 @@ -256,7 +266,7 @@ SELECT * FROM inventory_item c ORDER BY c; SELECT * FROM inventory_item c ORDER BY c.*; SELECT * FROM inventory_item c ORDER BY ROW(c.*); - 所有这些ORDER BY子句都指定了该行的组合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: + 所有这些ORDER BY子句都指定了该行的复合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: SELECT * FROM inventory_item c ORDER BY ROW(c.name, c.supplier_id, c.price); SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); @@ -265,7 +275,7 @@ SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); - 另一种与组合值有关的特殊语法行为是,我们可以使用函数记法来提取组合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: + 另一种与复合值有关的特殊语法行为是,我们可以使用函数记法来提取复合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: SELECT c.name FROM inventory_item c WHERE c.price > 1000; @@ -284,11 +294,11 @@ SELECT c.somefunc FROM inventory_item c; 函数记法与字段记法之间的这种等价性,使得我们可以通过在复合类型上使用函数来实现计算字段 - computed field + 计算字段 - field - computed + 字段 + 计算 使用上面最后一种查询形式的应用程序,无需直接知道somefunc并不是该表中的真实列。 @@ -303,7 +313,7 @@ SELECT c.somefunc FROM inventory_item c; 复合类型的输入和输出语法 - 组合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明组合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 + 复合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明复合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 '( 42)' @@ -311,7 +321,7 @@ SELECT c.somefunc FROM inventory_item c; - 如前所示,在写组合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让组合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的组合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作组合语法的数据字符。 + 如前所示,在写复合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让复合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的复合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作复合语法的数据字符。 @@ -325,18 +335,18 @@ SELECT c.somefunc FROM inventory_item c; - 记住,你在 SQL 命令中写的内容会先被解释为字符串字面量,然后才会被解释为组合值。这会使所需的反斜杠数量翻倍(假定使用的是转义字符串语法)。例如,要在组合值中插入一个包含双引号和反斜杠的text字段,需要写成: + 记住,你在 SQL 命令中写的内容会先被解释为字符串字面量,然后才会被解释为复合值。这会使所需的反斜杠数量翻倍(假定使用的是转义字符串语法)。例如,要在复合值中插入一个包含双引号和反斜杠的text字段,需要写成: INSERT ... VALUES ('("\"\\")'); - 字符串字面量处理器会去掉一层反斜杠,因此传到组合值解析器时看起来是("\"\\")。随后,送入text数据类型输入例程的字符串就变成了"\。(如果我们使用的数据类型的输入例程也会把反斜杠当作特殊字符处理,例如bytea,那么为了在存储的组合字段中得到一个反斜杠,命令里可能需要多达八个反斜杠。)美元引用(见)可用于避免反斜杠加倍的需要。 + 字符串字面量处理器会去掉一层反斜杠,因此传到复合值解析器时看起来是("\"\\")。随后,送入text数据类型输入例程的字符串就变成了"\。(如果我们使用的数据类型的输入例程也会把反斜杠当作特殊字符处理,例如bytea,那么为了在存储的复合字段中得到一个反斜杠,命令里可能需要多达八个反斜杠。)美元引用(见)可用于避免反斜杠加倍的需要。 - 在 SQL 命令中编写组合值时,ROW构造器语法通常比组合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是组合成员时完全相同。 + 在 SQL 命令中编写复合值时,ROW构造器语法通常比复合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是复合成员时完全相同。 diff --git a/zh/10/textsearch.sgml b/zh/10/textsearch.sgml index c96e4756..c5afa867 100644 --- a/zh/10/textsearch.sgml +++ b/zh/10/textsearch.sgml @@ -1,21 +1,21 @@ - 全文搜索 + 全文检索 - 全文搜索 + 全文检索 - 文本搜索 + 文本检索 介绍 - 全文检索(或简称文本搜索)提供了识别满足 + 全文检索(或简称文本检索)提供了识别满足 查询条件的自然语言文档的能力, 并且可按它们与查询的相关度进行排序。最常见的搜索类型,是找出所有包含给定 查询词的文档,并按它们与查询的相似性 @@ -25,7 +25,7 @@ - 文本搜索操作符在数据库中已经存在很多年了。 + 文本检索操作符在数据库中已经存在很多年了。 PostgreSQL为文本数据类型提供了 ~~*LIKEILIKE 操作符,但它们缺少现代信息系统所要求的许多关键特性: @@ -138,7 +138,7 @@ ()。围绕这两种数据类型还有许多函数和 操作符(),其中最重要的是匹配操作符 @@,我们将在中介绍。 - 全文搜索还可以借助索引加速()。 + 全文检索还可以借助索引加速()。 @@ -147,11 +147,11 @@ 文档 - 全文搜索 + 文本检索 - 文档是全文搜索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本搜索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 + 文档是全文检索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本检索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 @@ -179,7 +179,7 @@ WHERE m.mid = d.did AND m.mid = 12; - 为了进行文本搜索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 + 为了进行文本检索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 @@ -187,7 +187,7 @@ WHERE m.mid = d.did AND m.mid = 12; 基本文本匹配 - 在PostgreSQL中,全文搜索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: + 在PostgreSQL中,全文检索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: SELECT 'a fat cat sat on a mat and ate a fat rat'::tsvector @@ 'cat & rat'::tsquery; @@ -203,7 +203,7 @@ SELECT 'fat & cow'::tsquery @@ 'a fat cat sat on a mat and ate a fat rat'::t - 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索术语,这些术语必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个术语组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本搜索匹配更像是这样: + 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索词,这些搜索词必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个搜索词组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本检索匹配更像是这样: SELECT to_tsvector('fat cats ate fat rats') @@ to_tsquery('fat & rat'); @@ -221,7 +221,7 @@ SELECT 'fat cats ate fat rats'::tsvector @@ to_tsquery('fat & rat'); f - 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,默认假定已经正规化,因此 rats 不会匹配 rat。 + 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,被假定为已经正规化,因此 rats 不会匹配 rat @@ -290,49 +290,49 @@ SELECT phraseto_tsquery('the cats ate the rats'); 配置 - 前述的都是简单的文本搜索示例。正如前面所提到的,全文搜索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如基于空白之外的解析。这个功能由文本搜索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 + 前述的都是简单的文本检索示例。正如前面所提到的,全文检索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如不局限于按空白划分的解析。这个功能由文本检索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 - 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本搜索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config。 + 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本检索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config - 依赖一个配置的每一个文本搜索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当这个参数被忽略时,default_text_search_config才被使用。 + 依赖一个配置的每一个文本检索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当省略这个参数时,default_text_search_config才被使用。 - 为了让建立自定义文本搜索配置更容易,一个配置可以从更简单的数据库对象来建立。PostgreSQL的文本搜索功能提供了四类配置相关的数据库对象: + 为了便于构建自定义文本检索配置,配置由更简单的数据库对象组合而成。PostgreSQL 的文本检索功能提供了四类与配置相关的数据库对象: - 文本搜索解析器将文档拆分成词元并分类每个词元(例如,作为词或者数字)。 + 文本检索解析器将文档拆分成词元并对每个词元分类(例如,作为词或者数字)。 - 文本搜索词典将词元转变成正规化的形式并拒绝停用词。 + 文本检索词典将词元转变成正规化的形式并拒绝停用词。 - 文本搜索模板提供位于词典底层的函数(一个词典简单地指定一个模板和一组用于模板的参数)。 + 文本检索模板提供位于词典底层的函数(词典只需指定一个模板及其一组参数)。 - 文本搜索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 + 文本检索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 - 文本搜索解析器和模板是从低层 C 函数构建而来,因此它要求 C 编程能力来开发新的解析器和模板,并且还需要超级用户权限来把它们安装到一个数据库中(在PostgreSQL发布的contrib/区域中有一些附加的解析器和模板的示例)。由于词典和配置只是对底层解析器和模板的参数化和连接,不需要特殊的权限来创建一个新词典或配置。创建定制词典和配置的示例将在本章稍后的部分给出。 + 文本检索解析器和模板由底层 C 函数构成,因此开发新的解析器和模板需要 C 编程能力,将它们安装到数据库中则需要超级用户权限。(PostgreSQL 发行版的 contrib/ 目录中有附加解析器和模板的示例。)词典和配置只是为底层解析器和模板设置参数并将它们连接起来,因此创建新词典或配置不需要特殊权限。本章后面会给出创建自定义词典和配置的示例。 @@ -343,14 +343,14 @@ SELECT phraseto_tsquery('the cats ate the rats'); 表和索引 - 在前一节中的示例演示了使用简单常数字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 + 在前一节中的示例演示了使用简单常量字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 搜索表 - 即使没有索引,也可以执行全文搜索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend: + 即使没有索引,也可以执行全文检索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend SELECT title @@ -374,7 +374,7 @@ WHERE to_tsvector(body) @@ to_tsquery('friend'); - 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 中同时包含 createtable: + 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 合在一起包含 createtable SELECT title @@ -388,7 +388,7 @@ LIMIT 10; - 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本搜索在实际使用中通常都需要建立索引。 + 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本检索在实际使用中通常都需要建立索引。 @@ -396,9 +396,15 @@ LIMIT 10; 创建索引 - 我们可以创建一个GIN索引()来加速文本搜索: + + 我们可以创建一个GIN索引()来加速文本检索: + + CREATE INDEX pgweb_idx ON pgweb USING GIN (to_tsvector('english', body)); -注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本搜索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含tsvector,它们使用不同的文本搜索配置创建,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 + + + 注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本检索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含使用不同文本检索配置创建的tsvector,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 + 由于上面的索引使用了 to_tsvector 的双参数版本,因此只有同样使用相同配置名的双参数版 to_tsvector 查询,才能使用该索引。也就是说,WHERE to_tsvector('english', body) @@ 'a & b' 可以使用该索引,而 WHERE to_tsvector(body) @@ 'a & b' 则不能。这样可以保证索引只会和创建索引项时所用的同一配置配合使用。 @@ -434,7 +440,7 @@ LIMIT 10; 当使用一个单独的列来存储 tsvector 表示时,需要创建一个触发器来使 tsvector 列保持最新,以应对 titlebody 的任何更改。 说明了如何做到这一点。 - 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本搜索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 + 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本检索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 @@ -442,10 +448,10 @@ LIMIT 10; - 控制文本搜索 + 控制文本检索 - 要实现全文搜索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 + 要实现全文检索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 @@ -464,7 +470,7 @@ to_tsvector( config - to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本搜索配置进行处理。下面是一个简单示例: + to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本检索配置进行处理。下面是一个简单示例: SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); @@ -479,7 +485,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每类词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本搜索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english。 + to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每个词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本检索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english @@ -487,7 +493,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为空,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: + 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为 NULL,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: UPDATE tt SET ti = @@ -518,22 +524,35 @@ to_tsquery( config - to_tsquery创建一个tsquery值,其来源为querytext,其中必须是由以下 tsquery 操作符分隔的单个词元:&(AND)、|(OR)、!(NOT)以及 <->(FOLLOWED BY),也可以使用括号分组。换句话说,to_tsquery 的输入必须已经遵循 tsquery 输入的一般规则,如 所述。区别在于,基本的 tsquery 输入会直接使用词元,而 to_tsquery 会使用指定或默认的配置将每个词元正规化为词位,并丢弃根据该配置判定为停用词的词元。例如: + to_tsquery 根据 querytext 创建一个 tsquery 值。输入必须由单个词元组成,这些词元之间使用 tsquery 操作符 &(AND)、|(OR)、!(NOT)和 <->(FOLLOWED BY)分隔,并可使用圆括号分组。换句话说,传给 to_tsquery 的输入,必须已经遵循 中描述的 tsquery 一般输入规则。不同之处在于,基础 tsquery 输入是按字面接受词元,而 to_tsquery 会使用指定或默认配置,把每个词元正规化为词位,并丢弃那些按该配置被判定为停用词的词元。例如: + + SELECT to_tsquery('english', 'The & Fat & Rats'); to_tsquery --------------- 'fat' & 'rat' -与基本的 tsquery 输入一样,可以给每个词位附加权重,以限制它只匹配 tsvector 中具有这些权重的词位。例如: + + + 与基础tsquery输入一样,可以为每个词位附加权重,以限制它只匹配具有这些权重的tsvector词位。例如: + + SELECT to_tsquery('english', 'Fat | Rats:AB'); to_tsquery ------------------ 'fat' | 'rat':AB -此外,可以把 * 附加到词位上来指定前缀匹配: + + + 此外,还可以在词位后附加*来指定前缀匹配: + + SELECT to_tsquery('supern:*A & star:A*B'); to_tsquery -------------------------- 'supern':*A & 'star':*AB -这样的词位将匹配 tsvector 中以给定字符串开头的任何单词。 + + + 这样的词位将匹配tsvector中任何以给定字符串开头的单词。 + to_tsquery也可以接受单引号括起来的短语。当配置中包含可能在这类短语上触发的分类词典时,这一点尤其有用。在下面的例子中,一个分类词典包含规则 supernovae @@ -585,12 +604,19 @@ phraseto_tsquery( config phraseto_tsquery的行为很像plainto_tsquery,不过它会在保留下来的词之间插入<->(FOLLOWED BY)操作符,而不是&(AND)操作符。此外,停用词也不是简单地丢弃,而是通过插入<N>操作符(而不是<->操作符)来体现。在搜索精确词位序列时,这个函数很有用,因为 FOLLOWED BY 操作符不仅检查所有词位是否存在,还检查词位的顺序。 - 示例: + + 示例: + + SELECT phraseto_tsquery('english', 'The Fat Rats'); phraseto_tsquery ------------------ 'fat' <-> 'rat' -plainto_tsquery一样,phraseto_tsquery函数也不会识别其输入中的tsquery操作符、权重标签或前缀匹配标签: + + + 与plainto_tsquery一样,phraseto_tsquery函数也不会识别输入中的tsquery操作符、权重标签或前缀匹配标签: + + SELECT phraseto_tsquery('english', 'The Fat & Rats:C'); phraseto_tsquery ----------------------------- @@ -604,7 +630,7 @@ SELECT phraseto_tsquery('english', 'The Fat & Rats:C'); 搜索结果排名 - 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及它们出现于文档中哪个部分。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 + 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及这些词所处文档部分的重要程度。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 目前可用的两种排名函数是: @@ -651,11 +677,21 @@ SELECT phraseto_tsquery('english', 'The Fat & Rats:C'); - 对这两个函数来说,可选的weights参数允许根据词实例的标注情况赋予它们不同权重。权重数组按如下顺序指定各类词的权重: -{D-weight, C-weight, B-weight, A-weight} -如果没有提供weights,则使用如下默认值: + + 对这两个函数来说,可选的 weights 参数允许根据词实例的标注情况赋予它们不同权重。权重数组按如下顺序指定各类词的权重: + + +{D-权重, C-权重, B-权重, A-权重} + + + 如果没有提供 weights,则使用如下默认值: + + {0.1, 0.2, 0.4, 1.0} -通常,权重用于标注文档中特殊部分的词,例如标题或开头的摘要,从而使它们相对于正文中的词具有更高或更低的重要性。 + + + 通常,权重用于标记来自文档特定区域的词,例如标题或开头摘要中的词,从而使它们相较于正文中的词被赋予更高或更低的重要性。 + 由于较长的文档更有机会包含查询词,因此把文档大小纳入考量是合理的。例如,一个一百词的文档里某个搜索词出现五次,通常会比一个一千词的文档里同一搜索词也只出现五次更相关。两种排名函数都接受一个整数 normalization 选项,用于指定文档长度是否影响排名,以及具体如何影响。该整数选项控制多种行为,因此它是一个位掩码:你可以使用 | 指定一种或多种行为(例如 2|4)。 @@ -683,12 +719,12 @@ SELECT phraseto_tsquery('english', 'The Fat & Rats:C'); - 8 用文档中唯一词的数量除排名 + 8 用文档中不同词的数量除排名 - 16 用 1 + 文档中唯一词数量的对数除排名 + 16 用 1 + 文档中不同词数量的对数除排名 @@ -702,7 +738,7 @@ SELECT phraseto_tsquery('english', 'The Fat & Rats:C'); - 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。正规化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 + 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。归一化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 @@ -774,9 +810,7 @@ ts_headline( config ts_headline 接收文档和查询,并返回文档中一段 - 高亮查询词条的摘录。具体而言,该函数会先用查询选择相关文本片段,然后 - 高亮查询中出现的所有词,即使这些词的位置并不满足查询本身的位置限制。 - 用于解析文档的配置可通过 config 指定; + 高亮查询词的摘录。用于解析文档的配置可通过 config 指定; 若省略 config,则使用 default_text_search_config 配置。 @@ -863,7 +897,7 @@ occurrences to display in the result.', 附加特性 - 本节介绍一些在文本搜索中很有用的附加函数和操作符。 + 本节介绍一些在文本检索中很有用的附加函数和操作符。 @@ -976,7 +1010,7 @@ occurrences to display in the result.', - 返回用 AND 结合的两个给定查询。 + 返回两个给定查询的 AND 组合。 @@ -990,7 +1024,7 @@ occurrences to display in the result.', - 返回用 OR 结合的两个给定查询。 + 返回两个给定查询的 OR 组合。 @@ -1043,7 +1077,7 @@ SELECT to_tsquery('fat') <-> to_tsquery('cat | rat'); - 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: + 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在其后距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: SELECT tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10); @@ -1129,8 +1163,10 @@ SELECT querytree(to_tsquery('!defined')); - 这种形式的ts_rewrite 只应用一条重写规则:target 会被替换成 substitute,替换范围是整个 query。例如: + + 这种形式的 ts_rewrite 只应用一条重写规则:无论 targetquery 中的何处出现,都用 substitute 替换它。例如: + + SELECT ts_rewrite('a & b'::tsquery, 'a'::tsquery, 'c'::tsquery); ts_rewrite ------------ @@ -1147,7 +1183,10 @@ SELECT ts_rewrite('a & b'::tsquery, 'a'::tsquery, 'c'::tsquery); - 这种形式的ts_rewrite接受一个起始query和一个 SQLselect命令,该命令以文本字符串给出。该select必须产生两列tsquery类型的值。对于select结果中的每一行,第一列值(目标)的各次出现都会被第二列值(替换)取代,替换范围为当前query值。例如: + + 这种形式的 ts_rewrite 接受一个起始 query 和一个以文本字符串给出的 SQL select 命令。该 select 必须产生两列 tsquery 类型的值。对于 select 结果中的每一行,第一列值(目标)在当前 query 值中的所有出现都会被第二列值(替换)取代。例如: + + CREATE TABLE aliases (t tsquery PRIMARY KEY, s tsquery); INSERT INTO aliases VALUES('a', 'c'); @@ -1226,7 +1265,10 @@ tsvector_update_trigger(tsvector_column_nametsvector_column_name, config_column_name, text_column_name , ... ) - 这些触发器函数会自动计算一个tsvector列,其值来自一个或多个文本列,并受以下命令中所指定参数的控制:CREATE TRIGGER。下面是一个用法示例: + + 这些触发器函数会在 CREATE TRIGGER 命令中给定参数的控制下,从一个或多个文本列自动计算出一个 tsvector 列。下面是它们的一个使用示例: + + CREATE TABLE messages ( title text, body text, @@ -1248,13 +1290,19 @@ SELECT title, body FROM messages WHERE tsv @@ to_tsquery('title & body'); title | body ------------+----------------------- title here | the body text is here -创建这个触发器后,titlebody中的任何更改都会自动反映到tsv中,应用无需为此操心。 + + + 创建该触发器之后,对titlebody的任何修改都会自动反映到tsv中,而应用程序无需关心这一点。 + - 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本搜索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 + 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本检索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 - 这些内置触发器有一个限制,即它们会一视同仁地处理所有输入列。要对不同列采用不同处理方式 — 例如,给标题赋予与正文不同的权重 — 就需要编写自定义触发器。下面是一个使用PL/pgSQL作为触发器语言的示例: + + 这些内置触发器的一个限制是,它们会以相同方式处理所有输入列。若要对列做不同处理 — 例如让标题和正文具有不同权重 — 就需要编写自定义触发器。下面是一个使用 PL/pgSQL 作为触发器语言的示例: + + CREATE FUNCTION messages_trigger() RETURNS trigger AS $$ begin new.tsv := @@ -1315,7 +1363,7 @@ ts_stat(sqlquery text, - 如果提供了 weights,则只统计具有这些权重之一的出现。 + 如果提供了 weights,则只统计具有这些权重之一的词的出现次数。 @@ -1344,7 +1392,7 @@ LIMIT 10; 解析器 - 文本搜索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 + 文本检索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 @@ -1364,12 +1412,12 @@ LIMIT 10; asciiword - 单词,所有 ASCII 字母 + 单词,全部由 ASCII 字母组成 elephant word - 单词,所有字母 + 单词,全部由字母组成 mañana @@ -1379,12 +1427,12 @@ LIMIT 10; asciihword - 带连字符的单词,所有 ASCII + 带连字符的单词,全部为 ASCII 字符 up-to-date hword - 带连字符的单词,所有字母 + 带连字符的单词,由字母组成 lógico-matemática @@ -1394,12 +1442,12 @@ LIMIT 10; hword_asciipart - 带连字符的单词部分,所有 ASCII + 带连字符的单词部分,全部为 ASCII 字符 postgresql-beta1 上下文中的 postgresql hword_part - 带连字符的单词部分,所有字母 + 带连字符的单词部分,全部由字母组成 lógico-matemática 上下文中的 lógicomatemática @@ -1474,8 +1522,8 @@ LIMIT 10; blank - 空格符号 - (其他不识别的任意空白或标点符号) + 空白符号 + (未被识别为其他类型的空白或标点符号) @@ -1483,7 +1531,7 @@ LIMIT 10; - 解析器的一个字母的概念由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时可以用来区别它们。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 + 解析器对字母的界定由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时区分它们会很有用。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 email 不支持 RFC 5322 定义的所有有效电子邮件字符。具体来说,电子邮件用户名中支持的非字母数字字符只有句点、短横线和下划线。 @@ -1523,7 +1571,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h 词典 - 词典用于消除不应参与搜索的词(stop words),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 + 词典用于消除不应参与搜索的词(停用词),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 一些正规化的示例: @@ -1535,7 +1583,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - URL地址可以被正规化,以便让等价的 URL 匹配: + URL 地址可以规范化,以便让等价的 URL 匹配: @@ -1580,32 +1628,32 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤字典) + 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤词典 - 如果字典知道该词元但它是一个停用词,则返回一个空数组 + 如果词典知道该词元但它是一个停用词,则返回一个空数组 - 如果字典不识别该输入词元,则返回NULL + 如果词典不识别该输入词元,则返回NULL - PostgreSQL为许多语言提供了预定义的字典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发布的contrib/区域。 + PostgreSQL为许多语言提供了预定义的词典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发行版的contrib/目录。 - 文本搜索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 + 文本检索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 - 配置词典列表的一般规则是,把最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语分类词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: + 配置词典列表的一般规则是,把适用范围最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语同义词词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: ALTER TEXT SEARCH CONFIGURATION astro_en @@ -1614,14 +1662,14 @@ ALTER TEXT SEARCH CONFIGURATION astro_en - 过滤词典可以放在列表中的任何位置,只是不能放在最后,因为放在最后就没有意义了。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 + 过滤词典可以放在列表中的任何位置,但放在末尾没有用处。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 停用词 - 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文搜索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: + 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文检索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: SELECT to_tsvector('english', 'in the list of stop words'); @@ -1753,7 +1801,7 @@ SELECT * FROM ts_debug('english', 'Paris'); - synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基本名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 + synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 @@ -1815,28 +1863,28 @@ mydb=# SELECT 'indexes are very useful'::tsvector @@ to_tsquery('tst', 'indices' - 基本上一个分类词典会用一个首选词替换所有非首选词,并且也可选择地保留原始术语用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典要求一个下列格式的配置文件: + 分类词典基本上会用一个首选词替换所有非首选词,并且也可以选择保留原始词用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典需要一个采用以下格式的配置文件: -# this is a comment -sample word(s) : indexed word(s) -more sample word(s) : more indexed word(s) +# 这是一条注释 +示例词(一个或多个) : 索引词(一个或多个) +更多示例词(一个或多个) : 更多索引词(一个或多个) ... - 其中冒号(:)符号扮演了一个短语及其替换之间的定界符。 + 其中冒号(:)符号用作短语及其替换词之间的分隔符。 - 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过对子词典的应用,但所有样例词都必须能被子词典识别。 + 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过将子词典应用于该词,但所有样例词都必须能被子词典识别。 - 如果有多个短语匹配输入,则分类词典选择最长的那一个,并且使用最后的定义打破连结。 + 如果有多个短语匹配输入,分类词典会选择最长的匹配;长度相同时使用最后的定义。 - 由子词典识别的特定停用词不能够被指定;改用?标记任何可以出现停用词的地方。例如,假定根据子词典athe是停用词: + 由子词典识别的特定停用词不能够被指定;改用?标记可出现任意停用词的位置。例如,假定根据子词典athe是停用词: ? one ? two : swsw @@ -1878,7 +1926,7 @@ CREATE TEXT SEARCH DICTIONARY thesaurus_simple ( - mythesaurus是分类词典配置文件的基础名称(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 + mythesaurus是分类词典配置文件的基名(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 @@ -1903,7 +1951,7 @@ ALTER TEXT SEARCH CONFIGURATION russian 分类词典示例 - 考虑简单的天文词库 thesaurus_astro,其中包含一些天文单词组合: + 考虑一个简单的天文分类词典 thesaurus_astro,其中包含一些天文单词组合: supernovae stars : sn @@ -1971,7 +2019,7 @@ SELECT plainto_tsquery('supernova star'); <application>Ispell</application> 词典 - Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以把搜索词 bank 的词尾变化和词形变化对应起来,例如 bankingbankedbanksbanks'bank's。 + Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以匹配搜索词 bank 的所有变格和变位形式,例如 bankingbankedbanksbanks'bank's @@ -1986,12 +2034,12 @@ SELECT plainto_tsquery('supernova star'); - 要创建一个Ispell词典,执行这三步: + 要创建一个Ispell词典,请执行以下步骤: - 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。有必要抽取.aff.dic文件,把扩展改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): + 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。需要提取.aff.dic文件,将扩展名改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): iconv -f ISO_8859-1 -t UTF-8 -o nn_no.affix nn_NO.aff iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic @@ -2000,7 +2048,7 @@ iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic - 拷贝文件到$SHAREDIR/tsearch_data目录 + 复制文件到$SHAREDIR/tsearch_data目录 @@ -2018,11 +2066,11 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( - 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基础名称。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 + 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基名。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 - Ispell 词典通常识别一个有限集合的词,这样它们后面应该跟着另一个更广义的词典;例如,一个 Snowball 词典,它可以识别所有东西。 + Ispell 词典通常只能识别有限的词,因此其后应跟着另一个覆盖范围更广的词典;例如,一个 Snowball 词典,它可以识别所有输入。 @@ -2030,13 +2078,13 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( prefixes flag *A: - . > RE # As in enter > reenter + . > RE # 例如 enter > reenter suffixes flag T: - E > ST # As in late > latest - [^AEIOU]Y > -Y,IEST # As in dirty > dirtiest - [AEIOU]Y > EST # As in gray > grayest - [^EY] > EST # As in small > smallest + E > ST # 例如 late > latest + [^AEIOU]Y > -Y,IEST # 例如 dirty > dirtiest + [AEIOU]Y > EST # 例如 gray > grayest + [^EY] > EST # 例如 small > smallest @@ -2052,14 +2100,14 @@ lark/MRS .dict文件的格式是: -basic_form/affix_class_name +基本词形/词缀类名 .affix文件中,每一个词缀标志以下面的格式描述: -condition > [-stripping_letters,] adding_affix +条件 > [-删除的字母,] 添加的词缀 @@ -2068,7 +2116,7 @@ condition > [-stripping_letters,] adding_affix - Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,它标记可以参与到复合格式中的词典词: + Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,用于标记词典中可以参与构成复合词的词: compoundwords controlled z @@ -2098,7 +2146,7 @@ SFX T 0 est [^ey] - 一个词缀类的第一行是头部。头部后面列出了词缀规则的域: + 一个词缀类的第一行是首部。首部后面列出了词缀规则的字段: @@ -2150,7 +2198,7 @@ largehearted <application>Snowball</application> 词典 - Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每一个算法懂得按照其语言中的拼写,如何缩减词的常见变体形式为一个基础或词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择地指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。例如,有一个内置的定义等效于 + Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每种算法都知道如何把其语言中词的常见变体约简为基本拼写形式,也就是词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。例如,有一个内置的定义等效于 CREATE TEXT SEARCH DICTIONARY english_stem ( @@ -2164,7 +2212,7 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( - 一个Snowball词典识别所有的东西,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 + 一个Snowball词典识别所有输入,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 @@ -2175,11 +2223,11 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( 配置示例 - 一个文本搜索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本搜索配置来执行其处理。配置参数指定了默认配置的名称,如果忽略了显式的配置参数,文本搜索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 + 一个文本检索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本检索配置来执行其处理。配置参数指定了默认配置的名称,如果省略了显式的配置参数,文本检索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 - 有一些预定义的文本搜索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本搜索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本搜索对象()的信息。 + 有一些预定义的文本检索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本检索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本检索对象()的信息。 @@ -2271,17 +2319,17 @@ SHOW default_text_search_config; - 测试和调试文本搜索 + 测试和调试文本检索 - 一个自定义文本搜索配置的行为很容易变得混乱。本节中描述的函数对于测试文本搜索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 + 一个自定义文本检索配置的行为很容易让人困惑。本节中描述的函数对于测试文本检索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 配置测试 - 函数ts_debug允许简单地测试一个文本搜索配置。 + 函数ts_debug可方便地测试一个文本检索配置。 @@ -2301,7 +2349,7 @@ ts_debug( config re ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果该参数被忽略则使用default_text_search_config指定的配置。 + class="PARAMETER">config指定的配置,如果省略该参数则使用default_text_search_config指定的配置。 @@ -2376,7 +2424,7 @@ SELECT * FROM ts_debug('english', 'a fat cat sat on a mat - it ate a fat rats') - 为了一个更广泛的示范,我们先为英语语言创建一个public.english配置和 Ispell 词典: + 为了做更完整的演示,我们先为英语创建一个public.english配置和 Ispell 词典: @@ -2405,7 +2453,7 @@ SELECT * FROM ts_debug('public.english', 'The Brightest supernovaes'); - 在这个示例中,词Brightest被解析器识别为一个ASCII word(别名asciiword)。对于这种词元类型,词典列表是english_ispellenglish_stem。该词被english_ispell识别,并被这个词典归约为名词bright。词supernovaesenglish_ispell词典来说是未知的,因此它会被传递给下一个词典;幸运的是,它随后被识别了。(实际上,english_stem是一个 Snowball 词典,它能够识别所有输入;这也是为什么它被放在词典列表末尾。) + 在这个示例中,词Brightest被解析器识别为一个ASCII 词(别名asciiword)。对于这种词元类型,词典列表是english_ispellenglish_stem。该词被english_ispell识别,并被这个词典归约为词位bright。词supernovaesenglish_ispell词典来说是未知的,因此它会被传递给下一个词典;幸运的是,它随后被识别了。(实际上,english_stem是一个 Snowball 词典,它能够识别所有输入;这也是为什么它被放在词典列表末尾。) @@ -2434,7 +2482,7 @@ FROM ts_debug('public.english', 'The Brightest supernovaes'); 解析器测试 - 下列函数允许直接测试一个文本搜索解析器。 + 下列函数允许直接测试一个文本检索解析器。 @@ -2476,7 +2524,7 @@ ts_token_type(parser_oid oid, OUT - ts_token_type返回一个表,描述指定解析器能够识别的每一种词元。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: + ts_token_type返回一个表,描述指定解析器能够识别的每一种词元类型。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: SELECT * FROM ts_token_type('default'); @@ -2514,7 +2562,7 @@ SELECT * FROM ts_token_type('default'); 词典测试 - ts_lexize函数帮助词典测试。 + ts_lexize函数便于测试词典。 @@ -2572,17 +2620,17 @@ SELECT plainto_tsquery('supernovae stars'); - 文本搜索的首选索引类型 + 文本检索的首选索引类型 - 文本搜索 + 文本检索 索引 - 有两种索引可以用来加速全文搜索:GIN和 + 有两种索引可以用来加速全文检索:GINGiST。 - 请注意,索引对于全文搜索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 + 请注意,索引对于全文检索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 要创建这样的索引,可以采用下面的任一种方式: @@ -2593,7 +2641,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GIN - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIN (column); @@ -2613,7 +2661,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GiST - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIST (column); @@ -2631,7 +2679,7 @@ SELECT plainto_tsquery('supernovae stars'); - GIN 索引是文本搜索的首选索引类型。作为倒排索引,每个词(词位)在 + GIN 索引是文本检索的首选索引类型。作为倒排索引,每个词(词位)在 其中都有一个索引项,其中有压缩过的匹配位置的列表。多词搜索可以找到 第一个匹配,然后使用该索引移除缺少额外词的行。GIN 索引只存储 tsvector值的词(词位),并且不存储它们的权重标签。因此, @@ -2639,15 +2687,15 @@ SELECT plainto_tsquery('supernovae stars'); - 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。该签名通过哈希每一个词到一个 n 位串中的一个单一位来产生,通过将所有这些位 OR 在一起产生一个 n 位的文档签名。当两个词哈希到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。 + 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。该签名通过将每个词 hash 到一个 n 位串中的一位,再将所有这些位进行 OR 运算来生成,结果是一个 n 位的文档签名。当两个词 hash 到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。 - 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的可用性。假匹配的可能性取决于几个因素,特别是唯一词的数量,因此推荐使用词典来缩减这个数量。 + 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的实用性。假匹配的可能性取决于几个因素,特别是不同词的数量,因此推荐使用词典来缩减这个数量。 - 注意GIN索引的构件时间常常可以通过增加来改进,而GiST索引的构建时间则与该参数无关。 + 注意GIN索引的构建时间常常可以通过增加来改进,而GiST索引的构建时间则对该参数不敏感。 对大集合分区并正确使用 GIN 和 GiST 索引允许实现带在线更新的快速搜索。分区可以在数据库层面上使用表继承来完成,或者通过将文档分布在服务器上,并使用 模块收集搜索结果来完成。后者是可能的,因为排名函数只使用本地信息。 @@ -2658,7 +2706,7 @@ SELECT plainto_tsquery('supernovae stars'); <application>psql</application> 支持 - 关于文本搜索配置对象的信息可以在psql中使用一组命令获得: + 关于文本检索配置对象的信息可以在psql中使用一组命令获得: \dF{d,p,t}+ PATTERN @@ -2666,7 +2714,7 @@ SELECT plainto_tsquery('supernovae stars'); - 可选参数 PATTERN 可以是文本搜索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: + 可选参数 PATTERN 可以是文本检索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: => \dF *fulltext* @@ -2692,7 +2740,9 @@ SELECT plainto_tsquery('supernovae stars'); \dF+ PATTERN - 列出文本搜索配置(添加 +可获得更详细的信息)。 + + 列出文本检索配置(加上 + 可显示更多细节)。 + => \dF russian List of text search configurations Schema | Name | Description @@ -2731,7 +2781,9 @@ Parser: "pg_catalog.default" \dFd+ PATTERN - 列出文本搜索词典(加上+可获得更详细的信息)。 + + 列出文本检索词典(加上 + 可显示更多细节)。 + => \dFd List of text search dictionaries Schema | Name | Description @@ -2760,7 +2812,9 @@ Parser: "pg_catalog.default" \dFp+ PATTERN - 列出文本搜索解析器(添加 +可获得更详细的信息)。 + + 列出文本检索解析器(加上 + 可显示更多细节)。 + => \dFp List of text search parsers Schema | Name | Description @@ -2811,7 +2865,9 @@ Parser: "pg_catalog.default" \dFt+ PATTERN - 列出文本搜索模板(添加 +可获得更详细的信息)。 + + 列出文本检索模板(加上 + 可显示更多细节)。 + => \dFt List of text search templates Schema | Name | Description @@ -2832,7 +2888,7 @@ Parser: "pg_catalog.default" 限制 - 目前,PostgreSQL的文本搜索功能存在以下限制: + 目前,PostgreSQL的文本检索功能存在以下限制: 每个词位的长度必须小于 2K 字节 @@ -2859,12 +2915,12 @@ Parser: "pg_catalog.default" - 为了对比,PostgreSQL 8.1 的文档包含 10,441 个唯一词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 + 为了对比,PostgreSQL 8.1 的文档包含 10,441 个不同词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 - 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个唯一词。 + 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个不同词。 diff --git a/zh/10/unaccent.sgml b/zh/10/unaccent.sgml index 0bc0bfe7..ea1617ac 100644 --- a/zh/10/unaccent.sgml +++ b/zh/10/unaccent.sgml @@ -8,11 +8,11 @@ - unaccent是一个文本搜索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤字典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文搜索能够以不区分重音的方式处理文本。 + unaccent是一个文本检索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤词典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文检索能够以不区分重音的方式处理文本。 - unaccent当前的实现还不能作为thesaurus词典的正规化字典使用。 + unaccent当前的实现还不能作为thesaurus词典的正规化词典使用。 @@ -61,7 +61,7 @@ - 与其他PostgreSQL文本搜索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含无法转换的字符的行都会被静默忽略,因此规则文件可以包含不适用于当前编码的规则。 + 与其他PostgreSQL文本检索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含无法转换的字符的行都会被静默忽略,因此规则文件可以包含不适用于当前编码的规则。 @@ -74,7 +74,7 @@ 用法 - 安装unaccent扩展会创建一个文本搜索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 + 安装unaccent扩展会创建一个文本检索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 mydb=# ALTER TEXT SEARCH DICTIONARY unaccent (RULES='my_rules'); @@ -95,7 +95,7 @@ mydb=# select ts_lexize('unaccent','Hôtel'); - 下面的示例展示了如何将unaccent词典插入到文本搜索配置中: + 下面的示例展示了如何将unaccent词典插入到文本检索配置中: mydb=# CREATE TEXT SEARCH CONFIGURATION fr ( COPY = french ); mydb=# ALTER TEXT SEARCH CONFIGURATION fr @@ -126,7 +126,7 @@ mydb=# select ts_headline('fr','Hôtel de la Mer',to_tsquery('fr','Hotels') 函数 - unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本搜索环境之外使用。 + unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本检索环境之外使用。 @@ -138,7 +138,7 @@ unaccent(dictionary - 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本搜索词典。 + 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本检索词典。 diff --git a/zh/11/array.sgml b/zh/11/array.sgml index 49e8b7b6..5491ebf5 100644 --- a/zh/11/array.sgml +++ b/zh/11/array.sgml @@ -4,7 +4,7 @@ 数组 - array + 数组 @@ -15,8 +15,8 @@ 数组类型的声明 - array - declaration + 数组 + 声明 @@ -64,8 +64,8 @@ CREATE TABLE tictactoe ( 数组值输入 - array - constant + 数组 + 常量 @@ -86,7 +86,7 @@ CREATE TABLE tictactoe ( (这类数组常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。必要时可能需要显式指定类型。) + linkend="sql-syntax-constants-generic"/>中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。可能需要显式指定类型。) @@ -118,7 +118,10 @@ SELECT * FROM sal_emp; - 多维数组在每个维度上的长度必须匹配。不匹配会导致错误,例如: + + 多维数组的各个子数组在每个维度上的长度必须匹配。不匹配会导致错误,例如: + + INSERT INTO sal_emp VALUES ('Bill', '{10000, 10000, 10000, 10000}', @@ -148,8 +151,8 @@ INSERT INTO sal_emp 访问数组 - array - accessing + 数组 + 访问 @@ -182,9 +185,9 @@ SELECT pay_by_quarter[3] FROM sal_emp; - 我们还可以访问数组或子数组的任意矩形切片。数组切片通过在一个或多个数组维度上写成 + 我们还可以访问数组的任意矩形切片,即子数组。数组切片通过在一个或多个数组维度上写成 lower-bound:upper-bound - 的形式来表示。例如,下面这个查询取回 Bill 在一周前两天日程安排中的第一个项目: + 的形式来表示。例如,下面这个查询取回 Bill 在一周中前两天里每天的首项日程: SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill'; @@ -231,11 +234,11 @@ SELECT schedule[:][1:1] FROM sal_emp WHERE name = 'Bill'; - 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回空值。此外,如果下标超出数组边界,也会返回空值(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是空值而不是错误。 + 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回 NULL。此外,如果下标超出数组边界,也会返回 NULL(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是 NULL 而不是错误。 - 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回空值。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是空值。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回空值。 + 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回 NULL。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是 NULL。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回 NULL。 @@ -289,8 +292,8 @@ SELECT cardinality(schedule) FROM sal_emp WHERE name = 'Carol'; 修改数组 - array - modifying + 数组 + 修改 @@ -327,7 +330,7 @@ UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}' - 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用空值填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含空值。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 + 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用 NULL 填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含 NULL。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 @@ -439,21 +442,21 @@ SELECT array_cat(ARRAY[5,6], ARRAY[[1,2],[3,4]]); 在简单情况下,优先使用上面讨论的连接操作符,而不是直接调用这些函数。不过,由于连接操作符被重载以同时服务于这三种情形,所以在某些场景下使用这些函数之一有助于避免歧义。例如,考虑: -SELECT ARRAY[1, 2] || '{3, 4}'; -- the untyped literal is taken as an array +SELECT ARRAY[1, 2] || '{3, 4}'; -- 未指定类型的字面量被当作数组 ?column? ----------- {1,2,3,4} -SELECT ARRAY[1, 2] || '7'; -- so is this one +SELECT ARRAY[1, 2] || '7'; -- 这个字面量也一样 ERROR: malformed array literal: "7" -SELECT ARRAY[1, 2] || NULL; -- so is an undecorated NULL +SELECT ARRAY[1, 2] || NULL; -- 未加类型修饰的 NULL 也一样 ?column? ---------- {1,2} (1 row) -SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant +SELECT array_append(ARRAY[1, 2], NULL); -- 这可能才是原本想表达的意思 array_append -------------- {1,2,NULL} @@ -467,8 +470,8 @@ SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant 在数组中搜索 - array - searching + 数组 + 搜索 @@ -509,9 +512,14 @@ SELECT * FROM 关于该函数的说明见 - 还可以使用&&操作符搜索数组,它检查左操作数是否与右操作数重叠。例如: + + 也可以使用 && 操作符来搜索数组,它会检查左操作数是否与右操作数有重叠。例如: + + SELECT * FROM sal_emp WHERE pay_by_quarter && ARRAY[10000]; -关于此操作符和其他数组操作符的更多说明,参见。可以通过适当的索引来加速这种搜索,参见。 + + + 关于该操作符和其他数组操作符的更多说明见。如所述,也可以通过适当的索引加速。 还可以使用array_positionarray_positions函数在数组中搜索特定值。前者返回某个值在数组中首次出现位置的下标;后者返回一个数组,其中包含该值在数组中所有出现位置的下标。例如: @@ -538,7 +546,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); 数组输入和输出语法 - array + 数组 I/O @@ -551,7 +559,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); - 默认情况下,数组各维度的下界索引值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: + 默认情况下,数组各维度的下界下标值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2 FROM (SELECT '[1:1][-2:-1][3:5]={{{1,2,3},{4,5,6}}}'::int[] AS f1) AS ss; diff --git a/zh/11/catalogs.sgml b/zh/11/catalogs.sgml index e81e5cd4..bec99122 100644 --- a/zh/11/catalogs.sgml +++ b/zh/11/catalogs.sgml @@ -310,27 +310,27 @@ pg_ts_config - 文本搜索配置 + 文本检索配置 pg_ts_config_map - 文本搜索配置的词元映射 + 文本检索配置的词元映射 pg_ts_dict - 文本搜索字典 + 文本检索词典 pg_ts_parser - 文本搜索分析器 + 文本检索解析器 pg_ts_template - 文本搜索模板 + 文本检索模板 @@ -6925,12 +6925,12 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config目录包含表示文本搜索配置的条目。一个配置指定某个特定的文本搜索分析器,以及针对该分析器每种输出词元类型所定义的字典列表。分析器由pg_ts_config项表示,而词元到字典的映射则由pg_ts_config系统目录包含表示文本检索配置的条目。一个配置指定某个特定的文本检索解析器,以及针对该解析器每种输出词元类型所定义的词典列表。解析器记录在pg_ts_config条目中,而词元到词典的映射则由pg_ts_config_map中的辅助项定义。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。 @@ -6961,7 +6961,7 @@ SCRAM-SHA-256$<iteration count>:&l name - 文本搜索配置名 + 文本检索配置名 @@ -6988,7 +6988,7 @@ SCRAM-SHA-256$<iteration count>:&l oid pg_ts_parser.oid - 该配置的文本搜索分析器的OID + 该配置的文本检索解析器的 OID @@ -7005,11 +7005,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config_map目录包含的项展示了对于每一个文本搜索配置的每一种输出词元类型,有哪些文本搜索字典可供查询以及以何种顺序。 + pg_ts_config_map 系统目录中的条目说明了,对于每个文本检索配置所用解析器的每种输出词元类型,应当查询哪些文本检索词典以及查询的顺序。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7042,7 +7042,7 @@ SCRAM-SHA-256$<iteration count>:&l integer - 一种由配置的分析器送出的词元类型 + 一种由配置的解析器送出的词元类型 @@ -7060,7 +7060,7 @@ SCRAM-SHA-256$<iteration count>:&l oid pg_ts_dict.oid - 要查询的文本搜索字典的OID + 要查询的文本检索词典的 OID @@ -7077,11 +7077,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_dict目录包含定义文本搜索字典的项。一个字典依赖于一个文本搜索模板,它指定了所有需要的函数实现,字典本身则为模板支持的用户可设置参数提供值。这种分工允许无权限的用户创建字典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 + pg_ts_dict系统目录包含定义文本检索词典的项。一个词典依赖于一个文本检索模板,它指定了所有需要的实现函数,词典本身则为模板支持的用户可设置参数提供值。这种分工允许普通用户创建词典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7112,7 +7112,7 @@ SCRAM-SHA-256$<iteration count>:&l name - 文本搜索字典名 + 文本检索词典名 @@ -7121,7 +7121,7 @@ SCRAM-SHA-256$<iteration count>:&l oid pg_namespace.oid - 包含该字典的名字空间OID + 包含该词典的名字空间的 OID @@ -7130,7 +7130,7 @@ SCRAM-SHA-256$<iteration count>:&l oid pg_authid.oid - 字典的拥有者 + 词典的拥有者 @@ -7139,7 +7139,7 @@ SCRAM-SHA-256$<iteration count>:&l oid pg_ts_template.oid - 该字典的文本搜索模板的OID + 该词典的文本检索模板的 OID @@ -7165,11 +7165,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_parser目录包含定义文本搜索分析器的项。一个分析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个分析器必须用C语言级别的函数实现,创建新分析器的工作只限于数据库的超级用户。 + pg_ts_parser系统目录包含定义文本检索解析器的项。一个解析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个解析器必须用 C 语言级别的函数实现,创建新解析器的工作只限于数据库的超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7200,7 +7200,7 @@ SCRAM-SHA-256$<iteration count>:&l name - 文本搜索分析器的名字 + 文本检索解析器的名字 @@ -7209,7 +7209,7 @@ SCRAM-SHA-256$<iteration count>:&l oid pg_namespace.oid - 包含此分析器的名字空间的OID + 包含此解析器的名字空间的 OID @@ -7218,7 +7218,7 @@ SCRAM-SHA-256$<iteration count>:&l regproc pg_proc.oid - 分析器启动函数的OID + 解析器启动函数的 OID @@ -7227,7 +7227,7 @@ SCRAM-SHA-256$<iteration count>:&l regproc pg_proc.oid - 分析器的下一词元函数的OID + 解析器的下一词元函数的 OID @@ -7236,7 +7236,7 @@ SCRAM-SHA-256$<iteration count>:&l regproc pg_proc.oid - 分析器的关闭函数的OID + 解析器的关闭函数的 OID @@ -7245,7 +7245,7 @@ SCRAM-SHA-256$<iteration count>:&l regproc pg_proc.oid - 分析器标题函数的 OID + 解析器的 headline 函数的 OID @@ -7254,7 +7254,7 @@ SCRAM-SHA-256$<iteration count>:&l regproc pg_proc.oid - 分析器的词汇类型函数的OID + 解析器的 lextype 函数的 OID @@ -7271,11 +7271,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_template目录包含定义文本搜索模板的项。一个模板是一类文本搜索字典的实现骨架。由于一个模板必须用C语言级别的函数实现,新模板的创建只限于数据库超级用户。 + pg_ts_template系统目录包含定义文本检索模板的项。一个模板是一类文本检索词典的实现骨架。由于一个模板必须用 C 语言级别的函数实现,新模板的创建只限于数据库超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7306,7 +7306,7 @@ SCRAM-SHA-256$<iteration count>:&l name - 文本搜索模板的名字 + 文本检索模板的名字 diff --git a/zh/11/config.sgml b/zh/11/config.sgml index 8537d74b..ece5a2e4 100644 --- a/zh/11/config.sgml +++ b/zh/11/config.sgml @@ -2802,7 +2802,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( )。 + 设置规划器对一系列顺序磁盘页面读取中单次读取的代价估计。默认值是 1.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -2957,7 +2956,7 @@ ANY num_sync ( )。 + 设置规划器对一次非顺序磁盘页面读取的代价估计。默认值是 4.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -2979,8 +2978,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( - 遗传查询优化 + 遗传查询优化器 - GEQO是一个使用探索式搜索来执行查询规划的算法。它可以降低负载查询的规划时间。 同时,GEQO的检索是随机的,因此它的规划可能会不可确定。 更多信息参阅Chapter 50。 - 遗传查询规划器(GEQO)是一种使用启发式搜索来进行查询规划的算法。它可以降低对于复杂查询(连接很多表的查询)的规划时间,但是代价是它产生的计划有时候要差于使用穷举搜索算法找到的计划。详见。 + 遗传查询优化器(GEQO)是一种使用启发式搜索进行查询规划的算法。它可以缩短复杂查询(连接很多关系的查询)的规划时间,代价是生成的计划有时不如常规穷举搜索算法找到的计划。更多信息见 @@ -3185,7 +3182,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( .) + 目前,约束排除仅在通常用于通过继承树实现表分区的情况下默认启用。为所有表启用它会增加额外的规划开销,这在简单查询上相当明显,而且通常不会为简单查询带来好处。如果没有通过传统继承方式进行分区的表,你可能希望完全关闭它。(注意,分区表的等效功能由另一个参数控制。) @@ -3430,8 +3424,7 @@ SELECT * FROM parent WHERE key = 2400; parallel_leader_participation (boolean) - parallel_leader_participation configuration - parameter + parallel_leader_participation 配置参数 @@ -3485,7 +3478,7 @@ SELECT * FROM parent WHERE key = 2400; - 在哪里做日志 + 日志记录到哪里 日志写到哪里 @@ -3493,7 +3486,7 @@ SELECT * FROM parent WHERE key = 2400; current_logfiles - 和日志_目的地配置参数 + 和 log_destination 配置参数 @@ -3520,7 +3513,7 @@ csvlog log/postgresql.csv - 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设备LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: + 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设施LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: local0.* /var/log/postgresql @@ -3528,7 +3521,7 @@ local0.* /var/log/postgresql - 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源极其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见。 + 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源及其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见 @@ -3544,20 +3537,20 @@ local0.* /var/log/postgresql - 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 + 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息可能不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 - 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供方法来轮转日志文件。还有,在某些不使用日志收集器的平台上可能会导致丢失或者混淆日志输出,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 + 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供便捷的方法来轮转日志文件。还有,在某些平台上,不使用日志收集器可能会导致日志输出丢失或混杂,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 - 日志收集器被设计成从来不会丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 + 日志收集器被设计成从来不会丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它可能会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 @@ -3589,7 +3582,7 @@ local0.* /var/log/postgresql logging_collector被启用时,这个参数设置被创建的日志文件的文件名。 - 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何时区独立的%转义,计算将在由指定的时区中完成)。 + 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何依赖时区的%转义,计算将在由指定的时区中完成)。 被支持的%转义和开放组织的strftime说明中列举的类似。 注意系统的strftime不会被直接使用,因此平台相关(非标准)的扩展无法工作。 默认是postgresql-%Y-%m-%d_%H%M%S.log。 @@ -3616,7 +3609,7 @@ local0.* /var/log/postgresql - 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的十进制格式,该数字必须以一个0(零)开始)。 + 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的八进制格式,该数字必须以一个0(零)开始)。 @@ -3677,7 +3670,7 @@ local0.* /var/log/postgresql - 示例:要保留 24 小时的日志,每个小时一个日志文件,但是在日志文件尺寸超过 1GB 时轮转。可以这样做:将log_filename设置为server_log.%H%M、 + 示例:要保留 24 小时的日志,每个小时一个日志文件,如果日志文件尺寸超过 1GB,也会提前轮转。可以这样做:将log_filename设置为server_log.%H%M、 将log_truncate_on_rotation设置为on、 将log_rotation_age设置为60并且 将log_rotation_size设置为1000000。 @@ -3696,7 +3689,7 @@ local0.* /var/log/postgresql - 当启用了向syslog记录时,这个参数决定要使用的syslog设备。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4、 + 当启用了向syslog记录时,这个参数决定要使用的syslog设施。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4LOCAL5LOCAL6LOCAL7中选择,默认值是LOCAL0。还请参阅系统的syslog守护进程的文档。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -3751,7 +3744,7 @@ local0.* /var/log/postgresql - 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,有必要让消息保持逻辑上的整体性(也更加有用)。 + 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,让消息保持逻辑上的完整性可能是必要的,也可能更有用。 @@ -3813,9 +3806,7 @@ local0.* /var/log/postgresql - 控制在服务器日志中记录哪些导致错误条件的SQL语句。当前的SQL语句将包含在任何指定 - severity - 或更高消息的日志条目中。 + 控制在服务器日志中记录哪些导致错误条件的SQL语句。对于达到指定严重级别或更高级别的消息,其日志条目中会包含当前 SQL 语句。 有效值为DEBUG5DEBUG4DEBUG3DEBUG2DEBUG1、 @@ -3847,7 +3838,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -3881,7 +3872,7 @@ local0.* /var/log/postgresql DEBUG1..DEBUG5 - 为开发者提供连续的更详细的信息。 + 为开发者提供逐级更加详细的信息。 DEBUG INFORMATION @@ -3940,7 +3931,7 @@ local0.* /var/log/postgresql - 记录什么到日志 + 记录哪些内容 @@ -3961,7 +3952,7 @@ local0.* /var/log/postgresql - application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。它也会被通过包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为问号(?)。 + application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。也可以通过将其包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为问号(?)。 @@ -3985,7 +3976,6 @@ local0.* /var/log/postgresql - 这个参数启用发出各种调试输出。当设置时,会打印生成的解析树, 查询重写输出,或执行的每个查询的执行计划。这些信息是在LOG 信息级别发出,因此默认的,它们会出现在服务器日志中,但不会发送给客户端。 可以通过 client_min_messages和/或log_min_messages 来设置。这些参数缺省是off。 这些参数将会让多种调试输出被发出。当被设置时,它们为每一个被执行的查询打印结果分析树、查询重写器输出或执行计划。这些消息在LOG消息级别上被发出,因此默认情况下它们将出现在服务器日志中但不会被发送到客户端。你可以通过调整和/或来改变这种情况。这些参数默认是关闭的。 @@ -4019,7 +4009,7 @@ local0.* /var/log/postgresql 导致检查点和重启点在服务器日志中记录。日志消息中包括一些统计信息, 包括写入的缓冲区数量和写入它们所花费的时间。此参数只能在 - postgresql.conf文件或服务器命令行中设置。默认值为开启。 + postgresql.conf文件或服务器命令行中设置。默认值为关闭。 @@ -4076,7 +4066,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -4098,7 +4088,7 @@ local0.* /var/log/postgresql 控制在服务器日志中记录的每条消息的详细程度。有效值为TERSE, - DEFAULTVERBOSE,每个值都会添加更多字段到显示的消息中。 + DEFAULTVERBOSE,它们依次在显示的消息中增加更多字段。 TERSE不包括DETAILHINTQUERYCONTEXT错误信息的记录。 VERBOSE输出包括SQLSTATE错误代码 @@ -4118,7 +4108,7 @@ local0.* /var/log/postgresql - 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致很微小的性能损失。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致不可忽视的性能开销。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -4191,8 +4181,8 @@ local0.* /var/log/postgresql %n - 带毫秒的时间戳(作为 Unix 时代) - no + 带毫秒精度的 Unix 时间戳 + %i @@ -4307,7 +4297,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' UPDATEDELETETRUNCATE, 和COPY FROM。 如果PREPAREEXECUTE和 - EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个执行消息时会产生日志并且会包括绑定参数的值(任何内嵌的单引号会被双写)。 + EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个 Execute 消息时会产生日志并且会包括 Bind 参数的值(任何内嵌的单引号会被双写)。 @@ -4318,7 +4308,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在执行阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 + 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在 Execute 阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 @@ -4355,7 +4345,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 控制临时文件名和大小的日志记录。 - 临时文件可以用于排序、哈希和临时查询结果。 + 临时文件可以用于排序、hash 和临时查询结果。 每当删除临时文件时都会发出日志记录。 值为零时记录所有临时文件信息,而正值仅记录大小大于或等于指定千字节数的文件。 默认设置为-1,禁用此类日志记录。 @@ -4433,7 +4423,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 设置log_filenamelog_rotation_age为你的日志文件提供一种一致的、可预测的命名空间。这让你预测文件名会是怎样以及知道什么时候一个个体日志文件完成并且因此准备好被导入。 + 设置log_filenamelog_rotation_age,为日志文件提供一致且可预测的命名方案。这样就能预测文件名,并知道单个日志文件何时已完成写入、可以导入。 @@ -4462,8 +4452,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 进程标题 - 这些设置控制服务器进程的进程标题如何修改。通常可以通过ps等程序查看进程标题, - 在 Windows 上则可以使用Process Explorer。详情参见。 + 这些设置控制服务器进程的进程标题如何修改。通常可以通过ps等程序查看进程标题,在 Windows 上则可以使用Process Explorer。详情参见 @@ -4490,7 +4479,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 每次服务器接收到新的SQL命令时,都可以更新进程标题。 + 启用后,每次服务器接收到新的 SQL 命令时都会更新进程标题。 在大多数平台上,默认情况下此设置为on,但在Windows上默认为off, 因为该平台更新进程标题的开销较大。 只有超级用户能更改这个设置。 @@ -4525,7 +4514,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对每个会话当前执行命令的信息收集,包括命令开始执行的时间。 - 此参数默认为开启状态。请注意,即使启用了此信息,只有超级用户、具有 + 此参数默认为开启状态。请注意,即使启用了此参数,只有超级用户、具有 pg_read_all_stats角色权限的角色和拥有被报告会话的用户 (包括属于他们具有权限的角色的会话)才能看到此信息,因此不应构成安全风险。 只有超级用户能更改这个设置。 @@ -4541,7 +4530,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 为每个活动会话指定存储当前执行命令的文本所保留的字节数,它们被用于pg_stat_activity.query域。 + 为每个活动会话指定存储当前执行命令的文本所预留的字节数,它们被用于pg_stat_activity.query字段。 默认值是 1024字节。这个参数只能在服务器启动时被设置。 @@ -4558,7 +4547,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对数据库活动的统计信息收集。 - 此参数默认为开启,因为自动清理守护进程需要收集的信息。 + 此参数默认为开启,因为自动清理守护进程需要这些收集到的信息。 只有超级用户能更改这个设置。 @@ -4572,7 +4561,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用数据库I/O调用的计时。 默认情况下,此参数处于关闭状态,因为它将重复查询操作系统的当前时间,这可能会在某些平台上造成显著的开销。 您可以使用工具来测量系统上计时的开销。 + 启用数据库I/O调用的计时。 默认情况下,此参数处于关闭状态,因为它将重复查询操作系统的当前时间,这可能会在某些平台上造成显著的开销。 你可以使用工具来测量系统上计时的开销。 I/O计时信息显示在中,也显示在使用BUFFERS选项的输出中, 并由提供。只有超级用户能更改这个设置。 @@ -4589,7 +4578,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用函数调用次数和时间的跟踪。指定pl以仅跟踪过程语言函数, + 启用函数调用次数和耗时的跟踪。指定pl以仅跟踪过程语言函数, all以同时跟踪SQL和C语言函数。默认值为none, 即禁用函数统计跟踪。只有超级用户能更改这个设置。 @@ -4649,7 +4638,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 对于每个查询,将各自模块的性能统计输出到服务器日志中。这是一个简单的性能分析工具,类似于Unix getrusage()操作系统功能。 - log_statement_stats报告总语句统计,而其他选项报告每个模块的统计信息。 + log_statement_stats报告整个语句的统计信息,而其他选项报告每个模块的统计信息。 log_statement_stats不能与任何单独模块选项一起启用。所有这些选项默认情况下都是禁用的。 只有超级用户才能更改这些设置。 @@ -4665,7 +4654,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 自动清理 - autovacuum + 自动清理 配置参数 @@ -4705,10 +4694,10 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 每次由自动清理执行的操作都会被记录,如果运行时间至少达到指定毫秒数。将此设置为零会记录所有自动清理操作。 + 当自动清理执行的操作运行时间至少达到指定毫秒数时,就会记录该操作。将此设置为零会记录所有自动清理操作。 负一(默认值)会禁用记录自动清理操作。 例如,如果将其设置为250ms,则所有运行时间为250ms或更长的自动清理和分析都将被记录。 - 此外,当此参数设置为任何值而不是-1时,如果由于冲突的锁定或同时删除的关系而跳过自动清理操作,则会记录消息。 + 此外,当此参数设置为任何非-1值时,如果由于冲突锁或关系被并发删除而跳过自动清理操作,则会记录消息。 启用此参数可帮助跟踪自动清理活动。 此参数只能在postgresql.conf文件或服务器命令行中设置;但可以通过更改表存储参数来覆盖对单个表的设置。 @@ -4888,7 +4877,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; DEBUG1LOGNOTICEWARNINGERROR。 每个级别都包括其后的所有级别。级别越靠后,被发送的消息越少。默认值是NOTICE。 - 注意LOG在这里有与中不同的排名。 + 注意LOG在这里的排序与中的不同。 @@ -4906,11 +4895,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,用于进行搜索该对象的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 + 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,搜索该对象时的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 - search_path的值必需是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被安静地忽略。 + search_path的值必须是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被静默忽略。 @@ -4938,11 +4927,12 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个参数的缺省值是"$user", public。这种设置支持一个数据库(其中没有用户拥有私有模式,并且所有人共享使用public)、每个用户私有模式及其组合的共享使用。其它效果可以通过全局或者针对每个用户修改默认搜索路径设置获得。 + 这个参数的默认值是"$user", public。这种设置支持共享使用数据库(用户没有私有模式,所有人共享使用public)、每个用户拥有私有模式,以及二者的组合。 + 还可以通过全局或针对每个用户修改默认搜索路径设置来获得其他效果。 - 更多有关方案处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 + 更多有关模式处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 @@ -4962,7 +4952,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,只要有至少一条策略被应用则查询就会失败。默认为on。受限的行可见性会导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS)属性的角色没有效果。 + 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,原本会应用至少一条策略的查询就会失败。默认为on。受限的行可见性可能导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS属性的角色)没有效果。 @@ -4984,7 +4974,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建企图将失败。 + 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建尝试将失败。 @@ -4992,7 +4982,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当创建数据库时也会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 + 创建数据库时也不会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 @@ -5016,11 +5006,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被放置在里表中的连续表空间中。如果列表被选中元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 + 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被依次放置在列表中的连续表空间中。如果列表中被选中的元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 - 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,类似于为用户指定一个不具有CREATE权限的表空间。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特殊地,使用一个在postgresql.conf中设置的值时,这条规则起效。 + 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,指定一个用户不具有CREATE权限的表空间也同样是错误。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特别是,使用一个在postgresql.conf中设置的值时,这条规则起效。 @@ -5043,7 +5033,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 这个参数通常为打开。 当设置为off时,它禁用期间对函数体字符串的验证。 - 禁用验证避免了验证处理的副作用,特别避免了如向前引用导致的伪肯定。 + 禁用验证避免了验证处理的副作用,也避免前向引用等问题导致的误报。 在代表其他用户载入函数之前设置这个参数为offpg_dump会自动这样做。 @@ -5086,7 +5076,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态 。默认是off(读/写)。 + 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态。默认是off(读/写)。 @@ -5107,11 +5097,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当运行在serializable隔离级别时,一个可延迟只读 SQL 事务可以在它被允许继续之前延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的负荷;因此串行化代码将没有任何理由因为并发更新而强制它中断,使得这个选项适合于长时间运行的只读事务。 + 当运行在serializable隔离级别时,一个可延迟只读 SQL 事务可能在获准继续之前被延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的开销;因此串行化代码将没有任何理由因为并发更新而强制它中止,使得这个选项适合于长时间运行的只读事务。 - 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些操作在低于serializable隔离级别上的事务无效。默认值是off。 + 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些运行在低于serializable隔离级别上的事务无效。默认值是off @@ -5155,7 +5145,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的只读状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -5175,7 +5165,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的可延迟性状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -5189,16 +5179,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 控制当前会话中复制相关触发器和规则的触发。 - 可能的值是origin(默认值), - replicalocal。 - 设置此参数会导致丢弃先前缓存的任何查询计划。 - 只有超级用户能更改这个设置。 + 控制当前会话中复制相关触发器和规则的触发。设置此变量需要超级用户权限,并会丢弃任何先前缓存的查询计划。 + 可用值为origin(默认值)、replicalocal 这个设置的预期用途是由逻辑复制系统在应用所复制的更改时将它设置为replica。 - 其效果将是触发器和规则(没有对其默认配置做修改)在复制机上将不会被触发。 + 其效果将是触发器和规则(没有对其默认配置做修改)在副本上将不会被触发。 更多信息请参考的子句ENABLE TRIGGER以及ENABLE RULE @@ -5245,7 +5232,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为事务超时将总是第一个被触发。 + 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为语句超时将总是第一个被触发。 如果log_min_error_statement 被设置为ERROR 或更低,超时的语句将被记录。 @@ -5279,8 +5266,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; + - 当表的pg_class.relfrozenxid字段达到该设置指定的年龄时,VACUUM会执行激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值是 1.5 亿个事务。尽管用户可以将该值设置为 0 到 20 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的 95%,从而在触发防回卷 autovacuum 之前仍有机会执行一次常规手工VACUUM。更多信息请参见。 + 如果表的pg_class.relfrozenxid字段达到此设置指定的年龄,VACUUM就会执行一次激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值为 1.5 亿个事务。尽管用户可以将该值设置在 0 到 20 亿之间,VACUUM仍会悄悄将其有效值限制为不超过的 95%,以便在针对该表启动防回卷自动清理之前,周期性手工VACUUM仍有机会运行。详见 @@ -5293,7 +5281,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 指定VACUUM在扫描表时用来决定是否冻结行版本的切断年龄(以事务计)。默认值是 5000 万个事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见。 + 指定VACUUM在扫描表时用来决定是否冻结行版本的截止年龄(以事务计)。默认值是 5000 万个事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见 @@ -5305,8 +5293,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; + - 当表的pg_class.relminmxid字段达到该设置指定的年龄时,VACUUM会执行激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不是只扫描那些可能包含死元组的页面。默认值是 1.5 亿个多事务。尽管用户可以将该值设置为 0 到 20 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的 95%,从而在触发防回卷 autovacuum 之前仍有机会执行一次常规手工VACUUM。更多信息请参见。 + 如果表的pg_class.relminmxid字段达到此设置指定的年龄,VACUUM就会执行一次激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值为 1.5 亿个多事务。尽管用户可以将该值设置在 0 到 20 亿之间,VACUUM仍会悄悄将其有效值限制为不超过的 95%,以便在针对该表启动防回卷清理之前,周期性手工VACUUM仍有机会运行。详见 @@ -5319,7 +5308,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 指定VACUUM在扫描表时用来决定是否将多事务 ID 替换为较新的事务 ID 或多事务 ID 的切断年龄(以多事务计)。默认值是 500 万个多事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见。 + 指定VACUUM在扫描表时用来决定是否将多事务 ID 替换为较新的事务 ID 或多事务 ID 的截止年龄(以多事务计)。默认值是 500 万个多事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见 @@ -5382,7 +5371,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这里的实际选择都是根据爱好做出的,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码将比 base64 编码更大。 + 这里的实际选择主要取决于偏好,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码会比 base64 编码略大。 @@ -5403,7 +5392,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当在XML和字符串值之间进行转换时,无论设置DOCUMENT或 CONTENT都是隐式的。可参阅Section 8.13。 有效值是DOCUMENT和CONTENT。 缺省值是CONTENT。当在 XML 和字符串值之间进行转换时,设置DOCUMENTCONTENT都是隐式的。详见。有效值是DOCUMENTCONTENT。默认值是CONTENT。 + 设置在 XML 与字符串值之间进行转换时,隐含采用DOCUMENT还是CONTENT。 + 有关说明参见。有效值是DOCUMENTCONTENT。默认值是CONTENT @@ -5435,7 +5425,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 区域和格式化 + 区域设置和格式化 @@ -5449,7 +5439,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域行为的设置初始化配置文件。 + 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域设置行为的设置初始化配置文件。 @@ -5462,10 +5452,13 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置间隔值的显示格式。值sql_standard将产生匹配SQL标准间隔文本的输出。当参数被设置为ISO时,值postgres(默认)将产生匹配PostgreSQL发行 8.4 之前的输出。当DateStyle参数被设置为非ISO输出时,值postgres_verbose会产生匹配PostgreSQL发行 8.4 之前的输出。值iso_8601会产生匹配在 ISO 8601 的 4.4.3.2 节中定义的带标志符格式的时间间隔的输出。 + 设置时间间隔值的显示格式。值sql_standard会生成符合SQL标准时间间隔字面量的输出。 + 值postgres(默认值)的输出与PostgreSQL 8.4 之前版本中设为ISO时的输出一致。 + 值postgres_verbose的输出与PostgreSQL 8.4 之前版本中DateStyle设为非ISO输出时的输出一致。 + 值iso_8601会生成符合 ISO 8601 第 4.4.3.2 节定义的时间间隔带标志符格式的输出。 - IntervalStyle参数也可以影响对有歧义的间隔输入的解释。详见。 + IntervalStyle参数也会影响对有歧义的时间间隔输入的解释。详见 @@ -5555,11 +5548,11 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 在一些系统上,这个区域分类并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 + 在一些系统上,这个区域设置类别并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 - 只有超级用户能更改这个设置。 + 只有超级用户能更改这个设置,因为它会同时影响发送到服务器日志和客户端的消息,设置不当可能降低服务器日志的可读性。 @@ -5574,7 +5567,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化货币量的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化货币量的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -5589,7 +5582,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化数字的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化数字的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -5604,7 +5597,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化日期和时间的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化日期和时间的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -5619,7 +5612,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 选择被那些没有显式参数指定配置的文本搜索函数变体使用的文本搜索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配区域的配置,initdb将用对应于选中的lc_ctype区域的设置初始化配置文件。 + 选择被那些没有显式参数指定配置的文本检索函数变体使用的文本检索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配该区域设置的配置,initdb将用对应于选中的lc_ctype区域设置的值初始化配置文件。 @@ -5633,7 +5626,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 为了载入附加的功能或者达到提高性能的目的,可用多个设置来预先载入共享库到服务器中。 - 例如'$libdir/mylib'设置可能会导致mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 + 例如'$libdir/mylib'设置会使mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 @@ -5642,12 +5635,12 @@ SET XML OPTION { DOCUMENT | CONTENT }; 只有特别为与PostgreSQL一起使用设计的共享库才能以这种方式载入。每一个PostgreSQL支持 - 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非PostgreSQL无法 + 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非 PostgreSQL 库无法 以这种方式被载入。你可能可以使用操作系统的工具(如LD_PRELOAD)载入它。 - 总之,请参考特定模块的文档来用推荐的方法载入它。 + 一般来说,请参考特定模块的文档来用推荐的方法载入它。 @@ -5679,9 +5672,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 这个特性的目的是允许非特权用户在特定的会话中载入正在调试的或者性能度量库, - 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客 - 户端的PGOPTIONS环境变量或者 + 这个特性的目的是允许非特权用户在特定的会话中载入用于调试或性能测量的库, + 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客户端的PGOPTIONS环境变量或者 ALTER ROLE SET来设置这个参数。 @@ -5718,7 +5710,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 不同,相对于在库被第一次使用 - 时载入它,在会话开始时载入库并没有什么性能优势。不过,当使用连接池时这样做还是有一些 + 时载入它,在会话开始时载入库并没有明显的性能优势。不过,当使用连接池时这样做还是有一些 优势。 @@ -5756,9 +5748,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 在 Windows 主机上,在服务器启动时预载入一个库并不会减少启动每个新服务器进程所需的 - 时间;每一个服务器进程将会重新载入预载入的库。不过,对于那些要在postmaster启动时 + 时间;每一个服务器进程将会重新载入所有预载入的库。不过,对于那些要在postmaster启动时 执行操作的库来说,Windows 主机上的 - shared_preload_libraries任然有用。 + shared_preload_libraries仍然有用。 @@ -5832,7 +5824,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - GIN 索引返回的集合尺寸的软上限。详见。 + GIN 索引扫描返回的集合尺寸的软上限。详见 @@ -5862,17 +5854,17 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这是在锁上等待的毫秒数,然后再检查是否存在死锁条件。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 + 指定在检查是否发生死锁之前等待锁的毫秒数。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 我们乐观地假设在生产应用程序中死锁并不常见,所以在检查死锁之前只是等待一段时间。 增加此值会减少在不必要的死锁检查中浪费的时间,但会减慢实际死锁错误的报告速度。 - 默认值为一秒(1s),这可能是您在实践中想要的最小值。 - 在负载较重的服务器上,您可能希望提高它。 - 理想情况下,设置应超过您的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 + 默认值为一秒(1s),这可能是你在实践中想要的最小值。 + 在负载较重的服务器上,你可能希望提高它。 + 理想情况下,设置应超过你的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 只有超级用户能更改这个设置。 - 当被设置时,这个参数还可以决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 + 当被设置时,这个参数也决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 @@ -5923,7 +5915,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制在谓词锁被提升为覆盖整个关系之前,该谓词锁能够在单个关系上锁住多少页面或元组。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个关系之前,可以对单个关系中的多少页面或元组加谓词锁。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -5938,7 +5930,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制在谓词锁被提升为覆盖整个页面之前,该谓词锁能在单一页面上锁住多少行。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个页面之前,可以对单个页面中的多少行加谓词锁。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -5964,7 +5956,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个空数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。对于那些要求旧行为的应用的向后兼容性,这个变量可以被设置为off。 + 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个值为空值的数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。为了向后兼容那些要求旧行为的应用,这个变量可以被设置为off @@ -5982,11 +5974,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制字符串文本中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\。如果客户端代码没有做到正确转义,那么将会导致 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 + 这个参数控制字符串字面量中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\。如果客户端代码没有做到正确转义,那么就可能遭到 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 - 注意在符合标准的字符串文本中,\就表示\。这个参数只影响不符合标准的文本的处理,包括转义字符串语法(E'...')。 + 注意在符合标准的字符串字面量中,\就表示\。这个参数只影响不符合标准的字面量的处理,包括转义字符串语法(E'...')。 @@ -6024,11 +6016,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 打开时,如果在普通字符串文本中('...'语法)出现了 一个反斜线(\)并且standard_conforming_strings为关闭,那么就会发出一个警告。默认值是on。 + 打开时,如果在普通字符串字面量中('...'语法)出现了 一个反斜线(\)并且standard_conforming_strings为关闭,那么就会发出一个警告。默认值是on - 希望使用反斜线作为转义符的应用应该被修改来使用转义字符串语法(E'...'),因为在 SQL 标准中普通字符串的默认行为是将反斜线视作一个普通字符。这个变量可以被启用来帮助定位需要被更改的代码。 + 希望使用反斜线作为转义符的应用应该被修改来使用转义字符串语法(E'...'),因为按照 SQL 标准,普通字符串现在默认将反斜线视作一个普通字符。这个变量可以被启用来帮助定位需要被更改的代码。 @@ -6049,7 +6041,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 设置这个参数不会禁用所有与大对象相关的安全检查 — 除了那些在PostgreSQL 9.0中已经修改了的默认行为。 + 设置此变量不会禁用所有与大对象相关的安全检查 — 只禁用那些在PostgreSQL 9.0 中默认行为发生变化的检查。 @@ -6091,7 +6083,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' standard_conforming_strings (boolean) - 字符串标准符合 + 字符串符合标准 standard_conforming_strings配置参数 @@ -6099,7 +6091,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 控制普通字符串文本('...')是否按照 SQL 标准把反斜线当普通文本。从PostgreSQL 9.1 开始,默认值为on(之前的发行中默认值为off)。应用可以检查这个参数来判断字符串文本如何被处理。这个参数的存在也可以被当做转义字符串语法(E'...')被支持的标志。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 + 控制普通字符串字面量('...')是否按照 SQL 标准把反斜线当普通文本。从PostgreSQL 9.1 开始,默认值为on(之前的发行中默认值为off)。应用可以检查这个参数来判断字符串字面量如何被处理。这个参数的存在也可以被当做转义字符串语法(E'...')被支持的标志。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 @@ -6114,7 +6106,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询来,这样的扫描会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on。 + 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询,这样的扫描可能会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on @@ -6137,15 +6129,15 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr得出空值值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空(未知)。因此这个参数默认为off。 + 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr计算结果为空值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空值(未知)。因此这个参数默认为off - 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释)。它们不是非常有用并且在普通应用中也不常见,在应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及 空值的表达式的语义上感到困惑,因此这个选项默认为关闭。 + 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释),它们不是非常有用并且在普通应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及空值的表达式语义感到困惑,因此这个选项默认为关闭。 - 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不是劣质程序的一般修复。 + 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不能普遍修复错误的程序写法。 @@ -6202,15 +6194,15 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果设置为false(默认值),PostgreSQL在将修改的数据文件刷新到文件系统失败时,将引发PANIC级错误。 + 如果设置为false(默认值),PostgreSQL在将修改后的数据文件刷盘到文件系统失败时,将引发PANIC级错误。 这样会导致数据库服务器崩溃。这个参数只能在服务器启动时被设置。 在某些操作系统上,回写失败后,内核页面缓存中的数据状态未知。 在某些情况下,它可能已被完全遗忘,因此重试不安全;第二次尝试可能报告为成功,而事实上数据已丢失。在此类情形下,避免数据丢失的唯一方法是在报告任何故障后从WAL中恢复,最好是在调查了故障的根本原因并更换了任何有故障的硬件之后。 - 如果设置为true,PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷新操作。 - 仅在调查操作系统假如回写失败时对缓冲数据的处理方式的情况下,才将其设置为true。 + 如果设置为true,PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷盘操作。 + 只有在调查清楚操作系统在回写失败时如何处理缓冲数据之后,才应将其设置为true。 @@ -6223,11 +6215,10 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 预置选项 - 下列参数是只读的。 - 同样,它们被排除在postgresql.conf文件示例之外。 - 这些选项报告特定应用可能感兴趣的多种PostgreSQL行为,特别是管理前端相关的行为。 - 所有这些都是在PostgreSQL被编译或者它被安装时决定的。 - + 下列参数是只读的,在编译或安装 PostgreSQL 时确定。 + 因此,它们未列入示例 postgresql.conf 文件。 + 这些选项报告 PostgreSQL 行为的各个方面,某些应用(特别是管理前端)可能对此感兴趣。 + @@ -6256,7 +6247,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告对这个集簇是否启用了数据校验码。详见。 + 报告对这个集簇是否启用了数据校验和。详见 @@ -6269,7 +6260,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 在Unix系统上,这个参数报告启动时的数据目录(由定义)的权限。 + 在 Unix 系统上,这个参数报告服务器启动时数据目录(由定义)的权限。 (在Microsoft Windows上这个参数将总是显示0700。) 更多信息请参考 @@ -6305,7 +6296,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告PostgreSQL是否在编译时打开了 64 位整数日期和时间。从PostgreSQL 10起,这个值总是on。 + 报告PostgreSQL是否在编译时启用了对 64 位整数日期和时间的支持。从PostgreSQL 10起,这个值总是on @@ -6352,7 +6343,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定的。默认值是 100 个参数。 + 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定。默认值是 100 个参数。 @@ -6367,7 +6358,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64 ;因此max_identifier_length的默认值是 63,但是在使用多字节编码时可以少于 63 个字符。 + 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64;因此max_identifier_length的默认值是 63 字节,在使用多字节编码时,这可能不足 63 个字符。 @@ -6428,7 +6419,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告服务器版本数值。它是由编译服务器时的PG_VERSION值决定的。 + 报告服务器的版本号。它是由编译服务器时的PG_VERSION值决定的。 @@ -6443,7 +6434,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告服务器版本数值的整数值。它是由编译服务器时的PG_VERSION_NUM值决定的。 + 以整数形式报告服务器的版本号。它是由编译服务器时的PG_VERSION_NUM值决定的。 @@ -6486,11 +6477,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 自定义选项 - 这个特性被设计用来由附加模块向PostgreSQL添加通常不为系统知道的参数(例如过程语言)。这允许使用标准方法配置扩展模块。 + 这个特性允许附加模块(例如过程语言)向PostgreSQL添加系统通常不认识的参数。这样便能以标准方式配置扩展模块。 - 自定义选项有两部分名称:一个扩展名,然后是一个句点,再然后是正确的参数名,就像 SQL 中的合格名称。一个示例是plpgsql.variable_conflict。 + 自定义选项的名称由两部分组成:扩展名称和参数名本身,中间用句点分隔,类似于 SQL 中的限定名。例如plpgsql.variable_conflict @@ -6498,7 +6489,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' PostgreSQL将接受任何两部分参数名称的设置。 这些变量被视为占位符,在定义它们的模块加载之前没有任何功能。 当加载扩展模块时,它将添加其变量定义并根据这些定义转换任何占位符值。 - 如果存在以其扩展名开头的任何未识别的占位符,将发出警告并删除这些占位符。 + 如果存在以其扩展名称开头的任何未识别的占位符,将发出警告。 @@ -6522,7 +6513,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 允许将表空间创建为pg_tblspc内的目录,当CREATE TABLESPACE命令提供空位置字符串时。 + 当向CREATE TABLESPACE命令提供空的位置字符串时,允许将表空间创建为pg_tblspc内的目录。 这旨在允许测试主库和备库在同一台机器上运行的复制场景。这样的目录可能会混淆备份工具,因为这些工具期望在该位置只找到符号链接。 只有超级用户能更改这个设置。 @@ -6553,7 +6544,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据的时有用。这个参数在会话开始之后不能被更改。 + 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据时有用。这个参数在会话开始之后不能被更改。 @@ -6598,7 +6589,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 + 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 @@ -6633,7 +6624,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果打开,发出在排序操作中的资源使用的相关信息。只有在编译PostgreSQL时定义了TRACE_SORT宏, 这个参数才可用(不过,当前在默认情况下就定义了TRACE_SORT)。 + 如果开启,输出排序操作中的资源使用信息。只有在编译PostgreSQL时定义了TRACE_SORT宏, 这个参数才可用(不过,当前在默认情况下就定义了TRACE_SORT)。 @@ -6648,7 +6639,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。对每一种锁类型,已授权锁和等待锁的计数也会被一起转储。一个日志文件输出的示例如下: + 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。还会转储每种锁类型已授予的锁数、等待的锁数,以及它们的总数。一个日志文件输出的示例如下: LOG: LockAcquire: new: lock(0xb7acd844) id(24688,24696,0,0,0,1) grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0 @@ -6720,7 +6711,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果设置,不会跟踪小于这个 OID 的锁(用于避免在系统表上的输出)。 + 如果设置,不会跟踪 OID 小于此值的表上的锁(用于避免在系统表上的输出)。 @@ -6794,7 +6785,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,被修改的任何缓冲区的整页镜像及其WAL记录都被加入到记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 + 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,与该 WAL 记录相关的所有已修改缓冲区的整页镜像都会被添加到该记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 @@ -6837,11 +6828,11 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 在读取过程中检测到校验和失败通常会导致PostgreSQL报告错误,中止当前事务。 - 将ignore_checksum_failure设置为on会导致系统忽略失败(但仍然报告警告),并继续处理。 - 这种行为可能导致崩溃,传播或隐藏损坏,或其他严重问题。然而,它可能允许您跳过错误, - 并检索可能仍然存在于表中的未损坏的元组,如果块头仍然正常。如果头部损坏,即使启用此选项也会报告错误。 - 默认设置为off。 - 只有超级用户能更改这个设置。 + 将ignore_checksum_failure设置为 on 会使系统忽略失败(但仍报告警告),并继续处理。 + 这种行为可能导致崩溃、传播或隐藏损坏,或引发其他严重问题。 + 但是,如果块首部仍然正常,它可能允许你跳过错误,检索表中可能仍然存在的未损坏元组。 + 如果首部损坏,即使启用此选项也会报告错误。默认设置为off。 + 只有超级用户才能更改此设置。 @@ -6858,7 +6849,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 检测到损坏的页面头通常会导致PostgreSQL报告错误,中止当前事务。 将zero_damaged_pages设置为on会导致系统报告警告,将内存中的损坏页面清零,并继续处理。 - 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许您跳过错误,并从表中可能存在的未损坏页面中检索行。 + 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许你跳过错误,并从表中可能存在的未损坏页面中检索行。 如果由于硬件或软件错误而发生损坏,这对于恢复数据很有用。通常在放弃从表的损坏页面恢复数据的希望之前,不应将其设置为on。 清零的页面不会强制写入磁盘,因此建议在再次关闭此参数之前重新创建表或索引。默认设置为off。 只有超级用户能更改这个设置。 @@ -6874,7 +6865,8 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果LLVM有所需要的功能,用GDB注册所生成的函数。这会让调试更加容易。默认设置是off。这个参数只能在服务器启动时设置。 + 如果 LLVM 具有所需的功能,则向GDB注册生成的函数。 + 这会让调试更加容易。默认设置为off。这个参数只能在服务器启动时设置。 @@ -6890,7 +6882,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 将生成的LLVM IR写入文件系统,位于内。 - 这仅对于在JIT实现内部工作时有用。默认设置为off。 + 这仅对开发 JIT 的内部实现有用。默认设置为off。 只有超级用户能更改这个设置。 @@ -6919,10 +6911,9 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果LLVM有所需的功能,发出需要的数据以允许perf对JIT生成的函数画像。 - 这会写出文件到$HOME/.debug/jit/中,如果需要,由用户负责对其执行清除。 - 默认设置是off。 - 这个参数只能在服务器启动时设置。 + 如果 LLVM 具有所需的功能,则输出让perf对 JIT 生成的函数进行性能分析所需的数据。 + 这会将文件写入$HOME/.debug/jit/;用户应在需要时自行清理。 + 默认设置为off。这个参数只能在服务器启动时设置。 @@ -6948,11 +6939,11 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 短选项 - 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,并且它们作为一个单字母选项存在并不表示它们会被大量使用。 + 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,它们以单字母选项的形式存在,并不一定表示鼓励频繁使用这些选项。
- 短选项键 + 短选项对照 diff --git a/zh/11/datatype.sgml b/zh/11/datatype.sgml index f567c21f..d64aff9b 100644 --- a/zh/11/datatype.sgml +++ b/zh/11/datatype.sgml @@ -148,7 +148,7 @@ line - 平面上的无限长的线 + 平面上的无限直线 @@ -160,19 +160,19 @@ macaddr - MAC(Media Access Control)地址 + MAC(媒体访问控制)地址 macaddr8 - MAC(Media Access Control)地址(EUI-64格式) + MAC(媒体访问控制)地址(EUI-64格式) money - 货币数量 + 货币额 @@ -180,7 +180,7 @@ s) ] decimal [ (p, s) ] - 可选择精度的精确数字 + 可选择精度的精确数值 @@ -192,7 +192,7 @@ pg_lsn - PostgreSQL日志序列号类型 + PostgreSQL 日志序列号 @@ -264,13 +264,13 @@ tsquery - 文本搜索查询 + 文本检索查询 tsvector - 文本搜索文档 + 文本检索文档 @@ -407,14 +407,14 @@
- 数字类型常量的语法在里描述。数字类型有一整套对应的数学操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 + 数字类型常量的语法在里描述。数字类型有一整套对应的算术操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 整数类型 - 整数 + integer @@ -427,7 +427,7 @@ int4 - 整数 + integer @@ -447,11 +447,11 @@
- 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。而只有在integer的范围不够的时候才使用bigint。 + 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。bigint则设计用于integer的范围不够的情况。 - SQL只声明了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在许多其它SQL数据库系统中使用。 + SQL只规定了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在某些其他SQL数据库系统中使用。 @@ -460,11 +460,11 @@ 任意精度数值 - 数字(数据类型) + numeric(数据类型) - 任意精度数字 + 任意精度数值 @@ -476,7 +476,14 @@ 类型numeric可以存储非常多位的数字。我们特别建议将它用于货币金额和其它要求计算准确的数量。numeric值的计算在可能的情况下会得到准确的结果,例如加法、减法、乘法。不过,numeric类型上的算术运算比整数类型或者下一节描述的浮点数类型要慢很多。
- 下面使用如下术语:numeric精度是整个数中有效数字的总数,即小数点两侧的数字位数之和。numeric小数位数是小数部分中十进制数字的数量,即小数点右侧的位数。因此,数值 23.5141 的精度为 6,小数位数为 4。整数可以视为小数位数为零。 + + 我们在下文中使用以下术语: + 精度(precision)是一个numeric + 值中有效数字的总位数,也就是小数点两侧数字的总数。 + 小数位数(scale)是小数部分中位于小数点 + 右侧的十进制位数。因此,数值 23.5141 的精度为 6,小数位数为 4。 + 整数可以认为其小数位数为 0。 + 可以配置numeric列的最大精度和最大小数位数。要声明numeric类型的列,使用以下语法: NUMERIC(precision, scale) @@ -506,12 +513,12 @@ NUMERIC NaN - 非数字 + 非数 - 非数字 - 数字(数据类型) + 非数 + numeric(数据类型) 除了普通数值外,numeric类型还允许特殊值NaN,表示非数。对NaN的任何运算都会产生另一个NaN。在 SQL 命令中将该值写为常量时,必须加上引号,例如UPDATE table SET x = 'NaN'。输入时,字符串NaN的识别不区分大小写。 @@ -565,7 +572,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 双精度 + double precision @@ -575,7 +582,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; float8 - 双精度 + double precision @@ -618,7 +625,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 非数字 + 非数 double precision @@ -626,7 +633,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; Infinity -Infinity NaN -它们分别表示 IEEE 754 的特殊值无穷大负无穷大非数字。(在浮点运算不遵循 IEEE 754 的机器上,这些值可能无法按预期工作。)在 SQL 命令中将这些值写为常量时,必须加上引号,例如UPDATE table SET x = '-Infinity'。输入时,这些字符串的识别不区分大小写。 +它们分别表示 IEEE 754 的特殊值无穷大负无穷大非数。(在浮点运算不遵循 IEEE 754 的机器上,这些值可能无法按预期工作。)在 SQL 命令中将这些值写为常量时,必须加上引号,例如UPDATE table SET x = '-Infinity'。输入时,这些字符串的识别不区分大小写。
@@ -686,13 +693,13 @@ FROM generate_series(-3.5, 3.5, 1) as x; - auto-increment + 自动递增 serial - sequence - and serial type + 序列 + 与 serial 类型 @@ -817,7 +824,7 @@ ALTER SEQUENCE tablename_ SELECT '12.34'::float8::numeric::money;
- 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有圆整错误。 + 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有舍入误差。
@@ -829,7 +836,7 @@ SELECT '52093.89'::money::numeric::float8; 一个 money 值除以一个整数值时,会朝零方向截去小数 - 部分。要得到圆整结果,可以除以一个浮点值,或者在除法前先把 + 部分。要得到舍入后的结果,可以除以一个浮点值,或者在除法前先把 money 转换为 numeric,再在除法后转换回 money(如果要避免精度丢失风险,后一种做法更好)。 当一个 money 值被另一个 money 值除时, @@ -848,12 +855,12 @@ SELECT '52093.89'::money::numeric::float8; - string + 字符串 - 字符 + character @@ -888,7 +895,7 @@ SELECT '52093.89'::money::numeric::float8; character(n), char(n) - 定长,空白填充 + 定长,空格填充 text @@ -960,7 +967,7 @@ SELECT '52093.89'::money::numeric::float8; - 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储代码为零的字符(有时称为NUL)。有关更多信息,请参阅。 + 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储编码值为零的字符(有时称为NUL)。有关更多信息,请参阅 @@ -979,7 +986,7 @@ SELECT '52093.89'::money::numeric::float8; - 这三种类型之间没有性能差别,除了使用空白填充类型时会占用更多存储 + 这三种类型之间没有性能差别,除了使用空格填充类型时会占用更多存储 空间,以及在写入带长度约束的列时需要少量额外 CPU 周期来检查长度。 虽然在某些其他数据库系统中,character(n) 可能有一定性能优势,但在 PostgreSQL @@ -1014,7 +1021,7 @@ INSERT INTO test2 VALUES ('ok'); INSERT INTO test2 VALUES ('good '); INSERT INTO test2 VALUES ('too long'); ERROR: value too long for type character varying(5) -INSERT INTO test2 VALUES ('too long'::varchar(5)); -- explicit truncation +INSERT INTO test2 VALUES ('too long'::varchar(5)); -- 显式截断 SELECT b, char_length(b) FROM test2; b | char_length @@ -1133,13 +1140,15 @@ SELECT b, char_length(b) FROM test2; 开头(以便与转义格式区分)。在某些上下文中,这个开头的反斜线 可能需要通过双写进行转义(见 )。作为输入时,十六进制数字 - 可以使用大写或小写,并且在两个数字组成的一组之间允许出现空白 + 可以使用大写或小写,并且每两个数字组成一组,组与组之间允许出现空白 (但组内以及起始的 \x 序列中不能有空白)。 十六进制格式与大量外部应用和协议兼容,并且通常比转义格式转换得 更快,因此更推荐使用。 - 例如: + + 示例: + SET bytea_output = 'hex'; SELECT '\xDEADBEEF'::bytea; @@ -1190,7 +1199,7 @@ SELECT '\xDEADBEEF'::bytea; 0 - 0字节 + 零值字节 '\000' SELECT '\000'::bytea; \x00 @@ -1247,15 +1256,24 @@ SELECT '\xDEADBEEF'::bytea; - Bytea字节默认以hex格式输出。如果把改为escape, - 不可打印字节会被转换为等价的三位八进制值,并在前面加一个反斜线。大多数可打印字节以客户端字符集中相应的标准表示输出,例如: + 默认情况下,bytea 字节会以 hex + 格式输出。如果把 改为 + escape不可打印字节会被转换成 + 等价的三位八进制值,并在前面加一个反斜线。大多数 + 可打印字节则会按其在客户端字符集中的标准表示输出, + 例如: + + SET bytea_output = 'escape'; SELECT 'abc \153\154\155 \052\251\124'::bytea; bytea ---------------- abc klm *\251T -十进制值为 92 的字节(反斜线)在输出中会被双写。详情见。 + + + 十进制值 92(反斜线)的字节在输出中会被双写。详情见 + @@ -1321,10 +1339,10 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; time - 不带时区的时间 + time without time zone - 带时区的时间 + time with time zone timestamp @@ -1333,13 +1351,13 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; timestamptz - 带时区的时间戳 + timestamp with time zone - 不带时区的时间戳 + timestamp without time zone - 间隔 + interval 时间跨度 @@ -1423,7 +1441,7 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; - SQL 要求仅写 timestamp 时,应等效于 + SQL 标准要求仅写 timestamp 时,应等效于 timestamp without time zone,而 PostgreSQL 也遵循这种行为。 timestamptz 被接受为 @@ -1506,7 +1524,7 @@ MINUTE TO SECOND 其中 p 是可选的精度说明,给出秒字段中 保留的小数位数。精度可用于 timetimestampinterval 类型, - 范围是 0 到 6。这与前文描述的取值一致。如果在常量声明中没有指定 + 范围是 0 到 6。如果在常量声明中没有指定 精度,则默认采用该字面值本身的精度(但不超过 6 位)。 @@ -1533,7 +1551,7 @@ MINUTE TO SECOND 1999-01-08 - ISO 8601; 任何模式下的1月8日 + ISO 8601; 任何模式下的1月8日 (推荐格式) @@ -1569,27 +1587,27 @@ MINUTE TO SECOND 99-Jan-08 - YMD模式中的1月8日,否则错误 + YMD模式中的1月8日,否则报错 08-Jan-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 Jan-08-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 19990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 1999.008 - 年和一年中的日子 + 年和一年中的第几天 J2451187 @@ -1611,10 +1629,10 @@ MINUTE TO SECOND time - 无时区的时间 + time without time zone - 带时区的时间 + time with time zone @@ -1691,11 +1709,11 @@ MINUTE TO SECOND 040506+0730 - ISO 8601,以分数小时形式给出 UTC 偏移 + ISO 8601,时区的 UTC 偏移不是整小时 040506+07:30:00 - UTC偏移量指定为秒(ISO 8601中不允许) + UTC 偏移精确到秒(ISO 8601中不允许) 04:05:06 PST @@ -1772,20 +1790,34 @@ MINUTE TO SECOND - 带时区的时间戳 + timestamp with time zone - 无时区的时间戳 + timestamp without time zone - 时间戳类型的有效输入由日期与时间拼接而成,其后可以跟时区,再后可以跟ADBC。(或者,AD/BC可以出现在时区之前,但这不是首选顺序。)因此: + + 时间戳类型的有效输入由一个日期和时间的串接组成,后面跟着一个可选 + 时区,以及一个可选的 ADBC + (另外,AD/BC 也可以出现在 + 时区前面,但这种顺序并不推荐)。因此: + + 1999-01-08 04:05:06 -以及: + + 和: + 1999-01-08 04:05:06 -8:00 -都是有效值,遵循ISO8601 标准。此外,也支持下面这种常用格式: + + + 都是遵循 ISO 8601 标准的有效值。另外,广泛使用 + 的下列格式: + January 8 04:05:06 1999 PST - + + 也被支持。 + 按照SQL标准,timestamp without time zonetimestamp with time zone字面量的区别在于,时间后是否有+-符号及其后的时区偏移。因此,按照该标准,TIMESTAMP '2004-10-19 10:23:54'timestamp without time zone,而TIMESTAMP '2004-10-19 10:23:54+02'timestamp with time zonePostgreSQL在确定字符串字面量的类型之前,从不检查其内容,因此会把上述两者都视为timestamp without time zone。为确保字面量被视为timestamp with time zone,应为它显式指定正确类型:TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'若字面量已经被确定为timestamp without time zonePostgreSQL会静默忽略任何时区标记。也就是说,所得值来自输入值中的日期/时间字段,不会根据时区调整。 @@ -1815,12 +1847,12 @@ January 8 04:05:06 1999 PST time - constants + 常量 date - constants + 常量 @@ -1921,13 +1953,13 @@ January 8 04:05:06 1999 PST date 输出格式 - formatting + 格式化 time 输出格式 - formatting + 格式化 @@ -1957,7 +1989,7 @@ January 8 04:05:06 1999 PST ISO - ISO 8601, SQL标准 + ISO 8601,SQL 标准 1997-12-17 07:37:16-08 @@ -1988,7 +2020,7 @@ January 8 04:05:06 1999 PST - SQL和POSTGRES风格中,如果DMY域顺序被指定,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。 + SQL和POSTGRES风格中,如果指定了 DMY 字段顺序,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。
@@ -2051,7 +2083,7 @@ January 8 04:05:06 1999 PST 时区 - time zone + 时区 @@ -2106,7 +2138,8 @@ January 8 04:05:06 1999 PST - PostgreSQL允许使用三种不同形式指定时区: + PostgreSQL 允许使用三种不同形式来指定时区: + 完整时区名称,例如 America/New_York。 @@ -2135,11 +2168,20 @@ January 8 04:05:06 1999 PST 除了时区名称和缩写之外, PostgreSQL 还接受 POSIX 风格的 时区说明,见 。 - 这个选项通常不如使用具名时区更合适,但如果没有可用的 IANA - 时区条目,它可能就是必需的。 + 这个选项通常不如使用具名时区更合适,但如果没有合适的 IANA 时区条目可用,它可能就是必需的。 - 简而言之,缩写和完整名称的区别是:缩写表示特定的 UTC 偏移,而许多完整名称隐含本地夏令时规则,因此有两个可能的 UTC 偏移。例如,2014-06-04 12:00 America/New_York表示纽约当地时间的中午,在该日期使用的是东部夏令时间(UTC-4)。因此,2014-06-04 12:00 EDT指定相同的时刻。但是,2014-06-04 12:00 EST指定东部标准时间(UTC-5)的中午,而不管该日期是否名义上实行夏令时。 + + + 简而言之,这就是缩写和全名的区别:缩写表示某个特定的 UTC 偏移, + 而很多完整名称隐含了当地的夏令时规则,因此可能对应两个不同的 + UTC 偏移。例如, + 2014-06-04 12:00 America/New_York 表示纽约 + 当地时间中午;在这个具体日期,它属于东部夏令时(UTC-4),所以 + 2014-06-04 12:00 EDT 指定的是同一个时刻。 + 但 2014-06-04 12:00 EST 指定的是东部标准时 + 中午(UTC-5),无论当天名义上是否正在实行夏令时。 + 更复杂的是,一些司法辖区在不同时间使用同一时区缩写来表示不同的 @@ -2150,12 +2192,17 @@ January 8 04:05:06 1999 PST 当地民用时间。 - 在所有情况下,时区名称和缩写的识别都不区分大小写。(这与 8.2 之前的PostgreSQL版本不同;那些版本在某些上下文中区分大小写,在另一些上下文中则不区分。) + + 无论哪种形式,时区名称及其缩写都不区分大小写。(这是对 + PostgreSQL 8.2 之前版本的一项改动; + 在那些版本中,时区名在某些环境下区分大小写,而在另一些环境下则 + 不区分。) + 时区名称和缩写并不是硬编码在服务器中的;它们来自安装目录下 .../share/timezone/ 和 - .../share/timezonesets/ 子目录中的数据 + .../share/timezonesets/ 子目录中的配置文件 (见 )。 @@ -2193,13 +2240,13 @@ January 8 04:05:06 1999 PST - interval值可以使用下列语法书写: + interval值可以使用下列详细语法书写: @ quantity unit quantity unit... direction - 其中quantity是一个数字(很可能是有符号的); + 其中quantity是一个数字(可以带有符号); unitmicrosecondmillisecondsecondminutehourday、 @@ -2233,7 +2280,7 @@ January 8 04:05:06 1999 PST P quantity unit quantity unit ... T quantity unit ... 字符串必须以 P 开头,并且可以包含一个 - T 来引出一天中时间单位。可用的单位缩写见 + T 来引出一天中的时间单位。可用的单位缩写见 。单位可以省略, 也可以按任意顺序出现,但小于一天的单位必须出现在 T 之后。特别是,M 的含义 @@ -2272,7 +2319,7 @@ P quantity unit M - 分钟 (在时间部分中) + 分钟(在时间部分中) S @@ -2347,7 +2394,7 @@ P years-months- P1Y2M3DT4H5M6S - 带标志符的ISO 8601 格式:含义同上 + ISO 8601 带标志符的格式:含义同上 P0001-02-03T04:05:06 @@ -2377,7 +2424,7 @@ SELECT EXTRACT(days from '80 hours'::interval); interval 输出格式 - formatting + 格式化 @@ -2414,7 +2461,7 @@ SELECT EXTRACT(days from '80 hours'::interval); iso_8601 风格的输出符合 ISO 8601 标准 - 4.4.3.2 节描述的带标志符格式。 + 4.4.3.2 节描述的带标志符的格式
@@ -2465,7 +2512,7 @@ SELECT EXTRACT(days from '80 hours'::interval); 布尔类型 - Boolean + 布尔 数据类型 @@ -2576,15 +2623,15 @@ SELECT * FROM test1 WHERE a; 数据类型 - enumerated (enum) + 枚举(enum) - enumerated types + 枚举类型 - 枚举(enum)类型是由一个静态、值的有序集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的日期,或者一个数据的状态值集合。 + 枚举(enum)类型是由一个静态的有序值集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的各天,或者一个数据的状态值集合。 @@ -2693,7 +2740,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 实现细节 - 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空格也是有意义的。 + 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空白也是有意义的。 @@ -2705,7 +2752,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 从内部枚举值到文本标签的翻译被保存在系统目录pg_enum中。可以直接查询该目录。 + 从内部枚举值到文本标签的转换关系被保存在系统目录pg_enum中。直接查询该目录可能会有所帮助。 @@ -2776,7 +2823,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays circle24字节 - <(x,y),r>(中心点和半径) + <(x,y),r>(圆心和半径) @@ -2784,7 +2831,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 我们提供了丰富的函数和操作符来进行各种几何操作,例如缩放、平移、 - 旋转以及计算相交等,详见 。 + 旋转以及求交等,详见 @@ -2795,7 +2842,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 点是几何类型的基本二维构造块。用下面的语法描述point类型的值: + 点是几何类型的基本二维构造块。用下面任一种语法描述point类型的值: ( x , y ) @@ -2811,14 +2858,14 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线 + 直线 line - 线由线性方程Ax + By + C = 0 + 直线由线性方程Ax + By + C = 0 表示,其中AB不能同时为零。类型line 的值采用以下形式输入和输出: @@ -2838,7 +2885,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays (x1,y1)(x2,y2) - 是线上不同的两点。 + 是直线上不同的两点。 @@ -2854,7 +2901,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线段用一对线段的端点来表示。lseg类型的值用下面的语法声明: + 线段用一对线段的端点来表示。lseg类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ( x2 , y2 ) ] @@ -2878,15 +2925,15 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 方框 - box (data type) + box(数据类型) - rectangle + 矩形 - 方框用其对角的点对表示。box类型的值使用下面的语法指定: + 方框用其对角的点对表示。box类型的值使用下面任一种语法指定: ( ( x1 , y1 ) , ( x2 , y2 ) ) @@ -2905,7 +2952,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 在输入时可以提供任意两个对角,但是值将根据需要被按顺序记录为右上角和左下角。 + 在输入时可以提供任意两个对角,但是值将根据需要被重新排列,并依次存储为右上角和左下角。 @@ -2913,7 +2960,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 路径 - path (data type) + path(数据类型) @@ -2921,7 +2968,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - path类型的值用下面的语法声明: + path类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ... , ( xn , yn ) ] @@ -2931,11 +2978,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays x1 , y1 , ... , xn , yn - 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被忽略时,路径将被假定为封闭。 + 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被省略时,路径将被假定为封闭。 - 路径的输出使用第一种或第二种语法。 + 路径的输出视情况使用第一种或第二种语法。 @@ -2946,10 +2993,10 @@ SELECT person.name, holidays.num_weeks FROM person, holidays polygon - 多边形由点的列表(多边形的顶点)表示。多边形与闭合路径非常相似,但存储方式不同,并且有自己的支持例程。 + 多边形由点的列表(多边形的顶点)表示。多边形与封闭路径非常相似,但存储方式不同,并且有自己的支持例程。 - polygon类型的值用下列语法声明: + polygon类型的值用下列任一种语法指定: ( ( x1 , y1 ) , ... , ( xn , yn ) ) @@ -2974,7 +3021,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 圆由一个圆心和一个半径代表。circle类型的值用下面的语法指定: + 圆由一个圆心和一个半径代表。circle类型的值用下面任一种语法指定: < ( x , y ) , r > @@ -2997,7 +3044,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 网络地址类型 - network + 网络 数据类型 @@ -3051,8 +3098,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 在对 inetcidr 数据类型排序时,IPv4 - 地址总是排在 IPv6 地址之前,包括那些封装在 IPv6 地址中或映射到 - IPv6 地址中的 IPv4 地址,例如 ::10.2.3.4 或 + 地址总是排在 IPv6 地址之前,即使后者是封装或映射 IPv4 地址所得的 IPv6 地址,例如 ::10.2.3.4 或 ::ffff:10.4.3.2。 @@ -3098,7 +3144,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays cidr 类型保存 IPv4 或 IPv6 网络说明。输入和输出格式 遵循无类别域间路由(CIDR)约定。指定网络的格式为 address/y,其中 - address 是网络最低地址的 + address 是网络的 IPv4 或 IPv6 表示,而 y 是网络掩码中的位数。 如果省略 y,则会按照旧式 @@ -3208,7 +3254,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - <type>inet</type> vs. <type>cidr</type> + <type>inet</type> 与 <type>cidr</type> inetcidr 两种数据类型的本质区别在于: @@ -3234,12 +3280,12 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - MAC地址 + MAC 地址 macaddr - macaddr类型存储 MAC 地址,也就是以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: + macaddr类型存储 MAC 地址,例如以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: '08:00:2b:01:02:03' @@ -3273,15 +3319,15 @@ SELECT person.name, holidays.num_weeks FROM person, holidays <type>macaddr8</type> - macaddr8 (data type) + macaddr8(数据类型) - MAC地址(EUI-64格式) + MAC 地址(EUI-64 格式) macaddr - macaddr8类型以 EUI-64 格式存储 MAC 地址,例如常见的以太网卡硬件地址(尽管 MAC 地址也有其他用途)。该类型既接受 6 字节也接受 8 字节的 MAC 地址,并以 8 字节格式存储。给定的 6 字节格式 MAC 地址会以 8 字节格式存储,其中第 4 和第 5 字节分别设为 FF 和 FE。注意,IPv6 使用修改后的 EUI-64 格式,从 EUI-48 转换后应将第 7 位设为 1。提供的函数macaddr8_set7bit可完成这一更改。一般来说,接受由成对十六进制数字(在字节边界上)构成的输入,各对之间可以统一使用':''-''.'中的一种分隔。十六进制数字的数量必须为 16 个(8 字节)或 12 个(6 字节)。开头和结尾的空白会被忽略。以下是可以接受的输入格式示例: + macaddr8类型以 EUI-64 格式存储 MAC 地址,例如常见的以太网卡硬件地址(尽管 MAC 地址也有其他用途)。该类型既接受 6 字节也接受 8 字节的 MAC 地址,并以 8 字节格式存储。给定的 6 字节格式 MAC 地址会以 8 字节格式存储,其中第 4 和第 5 字节分别设为 FF 和 FE。注意,IPv6 使用修改后的 EUI-64 格式,从 EUI-48 转换后应将第 7 位设为 1。提供的函数macaddr8_set7bit可完成这一更改。一般来说,接受由成对十六进制数字(在字节边界上)构成的输入,各对之间可以统一使用':''-''.'中的一种分隔。十六进制数字的数量必须为 16 个(8 字节)或 12 个(6 字节)。开头和结尾的空白会被忽略。以下是可以接受的输入格式示例: '08:00:2b:01:02:03:04:05' '08-00-2b-01-02-03-04-05' '08002b:0102030405' @@ -3314,7 +3360,13 @@ SELECT macaddr8_set7bit('08:00:2b:01:02:03'); 数据类型 - 位串是由 1 和 0 组成的字符串,可用于存储或可视化位掩码。SQL 有两种位类型:bit(n)bit varying(n),其中n是正整数。 + + 位串是由 1 和 0 组成的字符串。它们可用于存储或展示位掩码。 + SQL 中有两种位类型: + bit(n) 和 + bit varying(n),其中 + n 是正整数。 + bit 类型的数据长度必须与 @@ -3364,31 +3416,31 @@ SELECT * FROM test; - 一个 bit 串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 + 一个位串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 开销,具体取决于串的长度。(不过,长值可能会被压缩或移到行外存储, 与 中对字符串的说明相同。) - 文本搜索类型 + 文本检索类型 - 全文搜索 + 全文检索 数据类型 - 文本搜索 + 文本检索 数据类型 - PostgreSQL 提供了两种专为支持全文搜索而 - 设计的数据类型。所谓全文搜索,是指在一组自然语言 + PostgreSQL 提供了两种专为支持全文检索而 + 设计的数据类型。所谓全文检索,是指在一组自然语言 文档中查找最匹配某个 查询的文档。tsvector 类型以 - 适合文本搜索的优化形式表示文档,tsquery 类型则表示 + 适合文本检索的优化形式表示文档,tsquery 类型则表示 文本查询。关于这一功能的详细解释见 ; 相关函数和操作符的概览见 @@ -3400,40 +3452,74 @@ SELECT * FROM test; tsvector(数据类型) - 一个tsvector值是由互不相同的词位组成的有序列表。词位是经过规范化以合并同一个词的不同变体的词(详情见)。排序和去重会在输入时自动完成,如本例所示: + + tsvector 值是一个排好序且互不重复的 + 词位(lexeme)列表,这些词已经过 + 正规化,以便把同一单词的不同变体合并起来 + (详见 )。排序和去重会在输入时自动 + 完成,如下例所示: + + SELECT 'a fat cat sat on a mat and ate a fat rat'::tsvector; tsvector ---------------------------------------------------- 'a' 'and' 'ate' 'cat' 'fat' 'mat' 'on' 'rat' 'sat' -要表示包含空白或标点符号的词位,请用引号括住它们: + + + 若要表示包含空白或标点的词位,请用引号将它们括起来: + + SELECT $$the lexeme ' ' contains spaces$$::tsvector; tsvector ------------------------------------------- ' ' 'contains' 'lexeme' 'spaces' 'the' -(本例和下一个示例使用美元符号引用的字符串字面量,以免在字面量中双写引号造成混淆。)内嵌的引号和反斜线必须双写: + + + (本例及下例使用美元引用的字符串常量,以避免在字符串内部必须 + 双写引号所造成的混淆。)嵌入的引号和反斜线必须双写: + + SELECT $$the lexeme 'Joe''s' contains a quote$$::tsvector; tsvector ------------------------------------------------ 'Joe''s' 'a' 'contains' 'lexeme' 'quote' 'the' -还可以给词位附加整数形式的位置,如下所示: + + + 还可以为词位附加整数形式的 位置: + + SELECT 'a:1 fat:2 cat:3 sat:4 on:5 a:6 mat:7 and:8 ate:9 a:10 fat:11 rat:12'::tsvector; tsvector ------------------------------------------------------------------------------- 'a':1,6,10 'and':8 'ate':9 'cat':3 'fat':2,11 'mat':7 'on':5 'rat':12 'sat':4 -位置通常表示原词在文档中的位置。位置信息可用于邻近度排序。位置值的范围为 1 到 16383;更大的数值会被静默设为 16383。同一词位的重复位置会被丢弃。 + - 具有位置的词位还可以标记一个权重,它可以是A, - BCD。 - D是默认值,因此不会在输出中显示: + 一个位置通常表示源词在文档中的位置。位置信息可用于 + 邻近度排序。位置值可以位于 1 到 16383 + 之间;更大的数字会被静默设为 16383。同一词位的重复位置会被丢弃。 + + + + 带有位置的词位还可以进一步附加一个 + 权重标签,其值可以是 + ABC + 或 DD 是默认值,因此在 + 输出中不会显示: + + SELECT 'a:1A fat:2B,4C cat:5D'::tsvector; tsvector ---------------------------- 'a':1A 'cat':5 'fat':2B,4C -权重通常用来反映文档结构,例如为标题中的词和正文中的词采用不同标记。文本搜索排名函数可以为不同的权重标记分配不同优先级。 + + + 权重通常用于反映文档结构,例如把标题中的词和正文中的词区分开来。 + 文本检索排序函数可以为不同的权重标记分配不同优先级。 + 必须认识到,tsvector 类型本身并不会执行任何词语 - 规范化;它假定输入的词已经按照应用需求完成规范化。例如: + 正规化;它假定输入的词已经按照应用需求完成正规化。例如: SELECT 'The Fat Rats'::tsvector; @@ -3442,9 +3528,9 @@ SELECT 'The Fat Rats'::tsvector; 'Fat' 'Rats' 'The' - 对于大多数英文全文搜索应用来说,上述词会被视为尚未规范化,但 + 对于大多数英文全文检索应用来说,上述词会被视为尚未正规化,但 tsvector 并不在意。原始文档文本通常应先经过 - to_tsvector,以按搜索需要对词语进行规范化: + to_tsvector,以按检索需要对词语进行正规化: SELECT to_tsvector('english', 'The Fat Rats'); @@ -3533,9 +3619,9 @@ SELECT 'super:*'::tsquery; 引号的使用规则与前面介绍 tsvector 时相同;同样, - 与 tsvector 一样,任何需要的词语规范化都必须在 + 与 tsvector 一样,任何需要的词语正规化都必须在 转换为 tsquery 类型之前完成。to_tsquery - 函数很适合用来实现这种规范化: + 函数很适合用来实现这种正规化: SELECT to_tsquery('Fat:ab & Cats'); @@ -3561,8 +3647,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); ---------------+------------ 'postgradu':1 | 'postgr':* - 因而它能够匹配其带前缀的后继形式 - postgraduate。 + 因而它能够匹配postgraduate 词干化后的形式。 @@ -3580,7 +3665,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); uuid 数据类型用于存储由 RFC 4122、 ISO/IEC 9834-8:2005 及相关标准定义的通用唯一标识符(UUID)。 - (有些系统把这种数据类型称为全局唯一标识符,或 GUID, + (有些系统把这种数据类型称为全局唯一标识符,或 GUID GUID。)这种标识符是一个 128 位的量,由某种算法生成,该算法被设计为使同一算法在已知宇宙中 被其他人生成出相同标识符的概率极低。因此,对于分布式系统而言, @@ -3597,7 +3682,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11 PostgreSQL 也接受其他输入形式:可以使用 - 大写字母、用花括号包围标准格式、忽略部分或全部连字符,或者在任意 + 大写字母、用花括号包围标准格式、省略部分或全部连字符,或者在任意 4 位分组后额外加上连字符。例如: A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11 @@ -3645,16 +3730,25 @@ a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11 创建XML值 - 要生成xml类型的值,可以对字符数据使用函数xmlparsexmlparse + + 要从字符数据生成 xml 类型的值,可以使用函数 + xmlparsexmlparse XMLPARSE ( { DOCUMENT | CONTENT } value) -例如: + 示例: +Manual...') XMLPARSE (CONTENT 'abcbarfoo') -]]>按照 SQL 标准,这是将字符串转换为 XML 值的唯一方式,不过也可以使用以下 PostgreSQL 特有语法: + 按照 SQL 标准,这是把字符串转换为 XML 值的 + 唯一方法;但 PostgreSQL 特有的下列语法: +bar' 'bar'::xml -]]> +]]> + 也可以使用。 + 即使输入值指定了文档类型声明(DTD),xml 类型也不会 @@ -3663,18 +3757,25 @@ xml 'bar' 来执行验证。 - 相反的操作是把xml值转换为字符串,这使用函数xmlserializexmlserialize + + 反向操作,也就是从 xml 生成字符串值,则使用函数 + xmlserializexmlserialize XMLSERIALIZE ( { DOCUMENT | CONTENT } value AS type ) - type可以是charactercharacter varyingtext(或这些类型之一的别名)。同样,按照 SQL 标准,这是在xml类型和字符类型之间转换的唯一方式,不过 PostgreSQL 也允许直接对值进行类型转换。 + type 可以是 + charactercharacter varying 或 + text(或它们的别名)。同样,根据 SQL 标准,这是在 + xml 与字符类型之间进行转换的唯一方式,但 + PostgreSQL 也允许你直接进行类型转换。 + 当字符串值在不经过 XMLPARSEXMLSERIALIZE 的情况下与 xml 类型互相转换时, 选择 DOCUMENT 还是 CONTENT - 由会话配置参数 XML option - XML option 决定,可以使用 + 由会话配置参数 XML 选项 + XML 选项 决定,可以使用 标准命令设置: SET XML OPTION { DOCUMENT | CONTENT }; @@ -3738,7 +3839,7 @@ SET xmloption TO { DOCUMENT | CONTENT }; xml 数据类型有些特殊,因为它不提供任何比较操作符。 这是因为对 XML 数据并不存在良定义且通用的比较算法。其结果是, - 你无法通过把某个 xml 值与搜索值比较来检索行。 + 你无法通过把某个 xml 列与搜索值比较来检索行。 因此,XML 值通常应伴随一个独立的键字段,例如 ID。另一种比较 XML 值的办法,是先把它们转换成字符串;但请注意,字符串比较对 XML 的比较需求通常帮助不大。 @@ -3746,14 +3847,14 @@ SET xmloption TO { DOCUMENT | CONTENT }; 由于 xml 数据类型没有可用的比较操作符,因此无法直接 - 在这种类型上创建索引。如果需要在 XML 中快速搜索,可行方案包括: + 在这种类型的列上创建索引。如果需要在 XML 中快速搜索,可行方案包括: 将表达式转换为字符串类型后为其建立索引,或者为某个 XPath 表达式 建立索引。当然,实际查询也必须相应调整为使用该被索引的表达式。 - PostgreSQL 的文本搜索功能也可用于加速 - XML 数据的全文搜索。不过,目前 PostgreSQL 发行版中仍缺少所需的 + PostgreSQL 的文本检索功能也可用于加速 + XML 数据的全文检索。不过,目前 PostgreSQL 发行版中仍缺少所需的 预处理支持。 @@ -3771,12 +3872,12 @@ SET xmloption TO { DOCUMENT | CONTENT }; 域类型 - domain + - data type - domain + 数据类型 + @@ -3788,13 +3889,13 @@ SET xmloption TO { DOCUMENT | CONTENT }; CREATE DOMAIN posint AS integer CHECK (VALUE > 0); CREATE TABLE mytable (id posint); -INSERT INTO mytable VALUES(1); -- works -INSERT INTO mytable VALUES(-1); -- fails +INSERT INTO mytable VALUES(1); -- 成功 +INSERT INTO mytable VALUES(-1); -- 失败 - 当底层类型的一个操作符或函数适用于一个域值时,域会被自动向下转换为底层类型。因此,mytable.id - 1的结果会被认为是类型integer而不是posint。我们可以写成(mytable.id - 1)::posint来把结果转换回posint,这会导致域的约束被重新检查。在这种情况下,如果该表达式被应用于一个值为1的id就会错误。把底层类型的值赋给域类型的一个字段或者变量不需要写显式的类型转换,但是域的约束将会被检查。 + 当底层类型的一个操作符或函数被应用于一个域值时,域会被自动向下转换为底层类型。因此,mytable.id - 1的结果会被认为是类型integer而不是posint。我们可以写成(mytable.id - 1)::posint来把结果转换回posint,这会导致域的约束被重新检查。在这种情况下,如果该表达式被应用于一个值为1的id就会报错。把底层类型的值赋给域类型的一个字段或者变量不需要写显式的类型转换,但是域的约束将会被检查。 @@ -3925,7 +4026,7 @@ SELECT * FROM pg_attribute regprocedure pg_proc - 函数与参数类型 + 带参数类型的函数 sum(int4) @@ -3974,21 +4075,21 @@ SELECT * FROM pg_attribute regconfig pg_ts_config - 文本搜索配置 + 文本检索配置 english regdictionary pg_ts_dict - 文本搜索字典 + 文本检索词典 simple
- 对于按名字空间分组的对象,所有 OID 别名类型都接受模式限定名称;如果不加限定就无法在当前搜索路径中找到对象,输出时也会显示模式限定名称。regprocregoper别名类型只接受唯一的(未重载的)输入名称,因此用途有限;对于大多数用途,regprocedureregoperator更合适。对于regoperator,通过将未使用的操作数写为NONE来标识一元操作符。 + 对于按命名空间分组的对象,所有 OID 别名类型都接受模式限定名称;如果不加限定就无法在当前搜索路径中找到对象,输出时也会显示模式限定名称。regprocregoper别名类型只接受唯一的(未重载的)输入名称,因此用途有限;对于大多数用途,regprocedureregoperator更合适。对于regoperator,通过将未使用的操作数写为NONE来标识一元操作符。 大多数 OID 别名类型还有一个附加特性,就是会创建依赖关系。如果 @@ -3996,9 +4097,8 @@ SELECT * FROM pg_attribute 它就会对被引用对象建立依赖。例如,如果某列的默认表达式是 nextval('my_seq'::regclass)PostgreSQL 就会知道该默认表达式依赖于 - 序列 my_seq,因此系统在删除该序列之前,必须先 - 移除该默认表达式。 - (regrole 是这一特性的例外:该类型的常量不允许出现在 + 序列 my_seq,因此系统不允许在尚未移除该默认表达式时删除序列。 + (regrole 是这一特性的唯一例外:该类型的常量不允许出现在 存储表达式中。) @@ -4160,7 +4260,7 @@ SELECT * FROM pg_attribute anyarray - 表示一个函数可以接受任意数组数据类型(参见 + 表示一个函数可以接受任意数组数据类型(参见)。 @@ -4215,12 +4315,12 @@ SELECT * FROM pg_attribute trigger - 触发器函数被声明为返回trigger. + 表示触发器函数被声明为返回 trigger event_trigger - 事件触发器函数被声明为返回event_trigger. + 表示事件触发器函数被声明为返回 event_trigger @@ -4235,7 +4335,7 @@ SELECT * FROM pg_attribute unknown - 标识一种尚未解析出的类型,例如未修饰的字符串字面值。 + 标识一种尚未解析出的类型,例如未修饰的字符串字面值的类型。 diff --git a/zh/11/dict-int.sgml b/zh/11/dict-int.sgml index 2988defd..c20e9906 100644 --- a/zh/11/dict-int.sgml +++ b/zh/11/dict-int.sgml @@ -1,16 +1,16 @@ - dict_int — 用于整数的示例全文搜索词典 + dict_int — 用于整数的示例全文检索词典 dict_int - dict_int是一个全文搜索附加词典模板的示例。 + dict_int是一个全文检索附加词典模板的示例。 引入这个示例词典是为了控制整数(有符号和无符号)的索引, - 使这类数字能够被索引,同时又避免唯一词的数量过度增长, + 使这类数字能够被索引,同时又避免不同词的数量过度增长, 因为那会严重影响搜索性能。 @@ -42,7 +42,7 @@ 用法 - 安装dict_int扩展后,会创建一个文本搜索模板 + 安装dict_int扩展后,会创建一个文本检索模板 intdict_template以及一个基于该模板、使用默认参数的词典 intdict。你可以修改这些参数,例如: @@ -65,7 +65,7 @@ mydb# select ts_lexize('intdict', '12345678');
但在实际使用中,通常需要像所述那样, - 将它包含到某个文本搜索配置中。可能类似如下: + 将它包含到某个文本检索配置中。可能类似如下: ALTER TEXT SEARCH CONFIGURATION english diff --git a/zh/11/func.sgml b/zh/11/func.sgml index 327a7fa5..586aa67d 100644 --- a/zh/11/func.sgml +++ b/zh/11/func.sgml @@ -6921,7 +6921,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 文本搜索函数和操作符 + 文本检索函数和操作符 全文检索 @@ -6929,7 +6929,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 文本搜索 + 文本检索 函数和操作符 @@ -6937,11 +6937,11 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple 以及 - 总结了为全文检索提供的函数和操作符。PostgreSQL的文本搜索功能的详细解释可参考。 + 总结了为全文检索提供的函数和操作符。PostgreSQL的文本检索功能的详细解释可参考
- 文本搜索操作符 + 文本检索操作符 @@ -7024,10 +7024,10 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple tsquery 包含操作符只考虑两个查询中列出的词位,忽略组合操作符。 - 除了表中列出的操作符,tsvectortsquery 类型还定义了普通的 B-树比较操作符(=< 等)。这些操作符对文本搜索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。 + 除了表中列出的操作符,tsvectortsquery 类型还定义了普通的 B-树比较操作符(=< 等)。这些操作符对文本检索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。
- 文本搜索函数 + 文本检索函数 @@ -7049,7 +7049,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple get_current_ts_config get_current_ts_config() regconfig - 获取默认的文本搜索配置 + 获取默认的文本检索配置 get_current_ts_config() english @@ -7258,17 +7258,17 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 所有接受一个可选的regconfig参数的文本搜索函数在省略该参数时,会使用由指定的配置。 + 所有接受一个可选的regconfig参数的文本检索函数在省略该参数时,会使用由指定的配置。 - 中的函数被单独列出,因为它们通常不被用于日常的文本搜索操作。 - 它们有助于开发和调试新的文本搜索配置。 + 中的函数被单独列出,因为它们通常不被用于日常的文本检索操作。 + 它们有助于开发和调试新的文本检索配置。
- 文本搜索调试函数 + 文本检索调试函数 diff --git a/zh/11/gist.sgml b/zh/11/gist.sgml index eb2c2180..d65755e3 100644 --- a/zh/11/gist.sgml +++ b/zh/11/gist.sgml @@ -690,7 +690,7 @@ my_fetch(PG_FUNCTION_ARGS) 示例 - PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本搜索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: + PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本检索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: diff --git a/zh/11/json.sgml b/zh/11/json.sgml index aa67ebc1..94fda2cb 100644 --- a/zh/11/json.sgml +++ b/zh/11/json.sgml @@ -23,7 +23,7 @@ 有两种 JSON 数据类型:jsonjsonb。它们接受的输入值集合几乎相同。实际使用中的主要区别是效率。json 数据类型保存输入文本的精确副本,处理函数每次执行时都必须重新解析;而 jsonb 数据以分解后的二进制格式存储,额外的转换开销使输入稍慢,但无需重新解析,因此处理速度明显更快。jsonb 还支持索引,这可能带来显著优势。 - 由于 json 类型存储的是输入文本的精确副本,因此它会保留标记 + 由于 json 类型存储的是输入文本的精确副本,因此它会保留词元 之间在语义上无关紧要的空白,以及 JSON 对象内部键的顺序。此外,如果值中 的某个 JSON 对象包含同一个键多次,所有键/值对都会被保留下来(处理函数会 将最后一个值视为生效值)。相比之下,jsonb 不保留空白,不保留 @@ -46,7 +46,7 @@ 当把文本形式的 JSON 输入转换为 jsonb 时, - RFC 7159 描述的基本类型会有效映射到原生的 + RFC 7159 描述的基本类型实际上会映射到原生的 PostgreSQL 类型上,如 所示。因此,什么样的数据构成 有效的 jsonb 会有一些额外但较小的限制,这些限制不适用于 @@ -94,7 +94,7 @@ null - (无) + (无) SQL NULL 是不同的概念 @@ -109,18 +109,18 @@ 以下都是有效的 json(或 jsonb)表达式: --- Simple scalar/primitive value --- Primitive values can be numbers, quoted strings, true, false, or null +-- 简单的标量/基本值 +-- 基本值可以是数字、加引号的字符串、true、false 或 null SELECT '5'::json; --- Array of zero or more elements (elements need not be of same type) +-- 包含零个或多个元素的数组(元素不必是同一类型) SELECT '[1, 2, "foo", null]'::json; --- Object containing pairs of keys and values --- Note that object keys must always be quoted strings +-- 包含键值对的对象 +-- 注意,对象的键必须始终是加引号的字符串 SELECT '{"bar": "baz", "balance": 7.77, "active": false}'::json; --- Arrays and objects can be nested arbitrarily +-- 数组和对象可以任意嵌套 SELECT '{"foo": [true, "bar"], "tags": {"a": 1, "b": null}}'::json; @@ -171,8 +171,7 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 当 JSON 数据存储在表中时,它与任何其他数据类型一样,都要面对相同的并发控 制考量。虽然存储大型文档是可行的,但要记住,任何更新都会在整行上获取一个 行级锁。应考虑将 JSON 文档限制在可管理的大小,以减少更新事务之间的锁争用。 - 理想情况下,每个 JSON 文档都应表示一个原子数据项,按照业务规则,它不应被 - 合理地进一步拆分为更小且可独立修改的数据项。 + 理想情况下,每个 JSON 文档都应表示一个原子数据项,根据业务规则,无法再合理地将它细分为更小且可独立修改的数据项。 @@ -180,11 +179,11 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; <type>jsonb</type> 包含与存在 jsonb - containment + 包含 jsonb - existence + 存在 测试 包含jsonb 的一项重要能力。 @@ -193,33 +192,32 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 示例都返回真: --- Simple scalar/primitive values contain only the identical value: +-- 简单的标量/基本值只包含相同的值: SELECT '"foo"'::jsonb @> '"foo"'::jsonb; --- The array on the right side is contained within the one on the left: +-- 左侧数组包含右侧数组: SELECT '[1, 2, 3]'::jsonb @> '[1, 3]'::jsonb; --- Order of array elements is not significant, so this is also true: +-- 数组元素的顺序无关紧要,因此下面的结果也为真: SELECT '[1, 2, 3]'::jsonb @> '[3, 1]'::jsonb; --- Duplicate array elements don't matter either: +-- 重复的数组元素也无关紧要: SELECT '[1, 2, 3]'::jsonb @> '[1, 2, 2]'::jsonb; --- The object with a single pair on the right side is contained --- within the object on the left side: +-- 左侧对象包含右侧只有一个键值对的对象: SELECT '{"product": "PostgreSQL", "version": 9.4, "jsonb": true}'::jsonb @> '{"version": 9.4}'::jsonb; --- The array on the right side is not considered contained within the --- array on the left, even though a similar array is nested within it: -SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- yields false +-- 左侧数组被认为包含右侧数组, +-- 尽管其中嵌套了一个类似的数组: +SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- 结果为假 --- But with a layer of nesting, it is contained: +-- 但增加一层嵌套后,就构成了包含关系: SELECT '[1, 2, [1, 3]]'::jsonb @> '[[1, 3]]'::jsonb; --- Similarly, containment is not reported here: -SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- yields false +-- 同样,下面也不构成包含关系: +SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- 结果为假 --- A top-level key and an empty object is contained: +-- 包含由顶层键和空对象构成的对象: SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; @@ -234,11 +232,11 @@ SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; 对于结构必须匹配这一一般原则,有一个特殊例外:数组可以包含一个基本值: --- This array contains the primitive string value: +-- 这个数组包含该基本字符串值: SELECT '["foo", "bar"]'::jsonb @> '"bar"'::jsonb; --- This exception is not reciprocal -- non-containment is reported here: -SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false +-- 这个例外并不对称——下面的结果表示不包含: +SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- 结果为假 @@ -248,19 +246,19 @@ SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false 外,下面这些示例都返回真: --- String exists as array element: +-- 字符串作为数组元素存在: SELECT '["foo", "bar", "baz"]'::jsonb ? 'bar'; --- String exists as object key: +-- 字符串作为对象键存在: SELECT '{"foo": "bar"}'::jsonb ? 'foo'; --- Object values are not considered: -SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- yields false +-- 不考虑对象的值: +SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- 结果为假 --- As with containment, existence must match at the top level: -SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- yields false +-- 与包含关系一样,存在性必须在顶层匹配: +SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- 结果为假 --- A string is considered to exist if it matches a primitive JSON string: +-- 如果字符串与一个基本 JSON 字符串匹配,则认为它存在: SELECT '"foo"'::jsonb ? 'foo'; @@ -274,8 +272,7 @@ SELECT '"foo"'::jsonb ? 'foo'; 由于 JSON 包含是嵌套的,因此适当的查询可以跳过对子对象的显式选择。例如, 假设我们有一个 doc 列,其顶层是对象,而且大 多数对象都带有 tags 字段,该字段中包含子对象数组。下面 - 这个查询会找出那些包含同时带有 "term":"paris" 和 - "term":"food" 的子对象的项,同时忽略 + 这个查询会找出同时出现包含 "term":"paris" 的子对象和包含 "term":"food" 的子对象的项,同时忽略 tags 数组之外的任何此类键: SELECT doc->'site_name' FROM websites @@ -305,7 +302,7 @@ SELECT doc->'site_name' FROM websites <type>jsonb</type> 索引 jsonb - indexes on + 索引 @@ -313,7 +310,7 @@ SELECT doc->'site_name' FROM websites 或键/值对。提供了两种 GIN 操作符类,它们在性能和灵活性 之间提供不同的权衡。 - 对于jsonb,默认 GIN 操作符类支持使用顶层键存在操作符??&?|以及路径/值存在操作符@>的查询。(这些操作符所实现语义的详情,参见。)使用此操作符类创建索引的示例如下: + 对于jsonb,默认 GIN 操作符类支持使用顶层键存在操作符??&?|以及路径/值存在操作符@>的查询。(这些操作符所实现语义的详情,参见。)使用此操作符类创建索引的示例如下: CREATE INDEX idxgin ON api USING GIN (jdoc); 非默认的 GIN 操作符类jsonb_path_ops仅支持为@>操作符建立索引。使用此操作符类创建索引的示例如下: CREATE INDEX idxginp ON api USING GIN (jdoc jsonb_path_ops); @@ -344,14 +341,14 @@ CREATE INDEX idxginp ON api USING GIN (jdoc jsonb_path_ops); 名为 jdocjsonb 列里。 如果在该列上创建了 GIN 索引,那么下面这样的查询就可以利用这个索引: --- Find documents in which the key "company" has value "Magnafone" +-- 查找键 "company" 的值为 "Magnafone" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"company": "Magnafone"}'; 但是,类似下面这样的查询就无法使用该索引,因为虽然操作符 ? 可索引,但它并未直接应用到被索引的列 jdoc 上: --- Find documents in which the key "tags" contains key or array element "qui" +-- 查找键 "tags" 包含键或数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc -> 'tags' ? 'qui'; 不过,只要适当地使用表达式索引,上述查询也可以利用索引。如果经常查询 @@ -368,7 +365,7 @@ CREATE INDEX idxgintags ON api USING GIN ((jdoc -> 'tags')); 另一种查询方法是利用包含,例如: --- Find documents in which the key "tags" contains array element "qui" +-- 查找键 "tags" 包含数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qui"]}'; jdoc 列上的简单 GIN 索引可以支持这个查询。 @@ -391,9 +388,9 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu 基本上,每个 jsonb_path_ops 索引项都是该值连同 - 通向该值的键一起计算出的哈希。例如,要索引 + 通向该值的键一起计算出的 hash。例如,要索引 {"foo": {"bar": "baz"}},会创建一个单独的索引项, - 其哈希值中同时纳入 foobar 和 + 其 hash 值中同时纳入 foobarbaz 这三者。因此,查找这一结构的包含查询会得到一次 非常精确的索引搜索;但完全没有办法据此找出 foo 是否 作为键出现。另一方面,jsonb_ops 索引会分别创建三个 @@ -413,11 +410,11 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu jsonb也支持btreehash索引。通常只有在需要检查完整 JSON 文档是否相等时,这些索引才有用。对于btree排序,jsonb数据的顺序很少值得关注,但为求完整,列出如下: -Object > Array > Boolean > Number > String > Null +对象 > 数组 > 布尔值 > 数字 > 字符串 > Null -Object with n pairs > object with n - 1 pairs +包含 n 个键值对的对象 > 包含 n - 1 个键值对的对象 -Array with n elements > array with n - 1 elements +包含 n 个元素的数组 > 包含 n - 1 个元素的数组 键值对数量相等的对象按以下顺序比较: 键-1, 值-1, 键-2 ... 注意,对象键按其存储顺序比较;尤其是,较短的键存储在较长的键之前,因此可能产生不直观的结果,例如: @@ -437,7 +434,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu PL/Perl 的扩展名为 jsonb_plperljsonb_plperlu。如果使用它们, - jsonb 值会按适当方式映射为 Perl 数组、哈希和标量。 + jsonb 值会按适当方式映射为 Perl 数组、hash 和标量。 diff --git a/zh/11/libpq.sgml b/zh/11/libpq.sgml index 3fbd4433..fd29f6b9 100644 --- a/zh/11/libpq.sgml +++ b/zh/11/libpq.sgml @@ -12,19 +12,19 @@ - libpq是应用程序员使用PostgreSQLC接口。libpq是一个库函数的集合,它们允许客户端程序传递查询给PostgreSQL后端服务器并且接收这些查询的结果。 + libpqPostgreSQLC应用程序编程接口。libpq是一组库函数,客户端程序可用它们向PostgreSQL后端服务器发送查询并接收查询结果。 - libpq也是很多其他PostgreSQL应用接口的底层引擎,包括为 C++、Perl、Python、Tcl 和 ECPG编写的接口。如果你使用那些包,某些方面的libpq行为将会对你很重要。特别是,描述了任何使用libpq的应用的用户可见的行为。 + libpq也是其他几个PostgreSQL应用程序接口的底层引擎,包括为 C++、Perl、Python、Tcl 和ECPG编写的接口。因此,对于这些包的用户,libpq行为的某些方面也很重要。特别是,描述了任何使用libpq的应用程序的用户都能观察到的行为。 - 在本章的末尾()包括了一些短程序来展示如何编写使用libpq的应用。在源代码发布的src/test/examples目录中还有一些完整的libpq应用的示例。 + 本章末尾()包含一些简短程序,展示如何编写使用libpq的程序。源代码发行包的src/test/examples目录中还提供了几个完整的libpq应用程序示例。 - 使用libpq的客户端程序必须包括头文件libpq-fe.hlibpq-fe.h并必须与libpq库链接在一起。 + 使用libpq的客户端程序必须包含头文件libpq-fe.hlibpq-fe.h,并且必须与libpq库链接。 @@ -39,7 +39,7 @@ - 在 Unix 上,复制一个拥有打开 libpq 连接的进程可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行代码是安全的。 + 在 Unix 上,对持有已打开 libpq 连接的进程执行 fork 操作可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行程序是安全的。 @@ -66,32 +66,32 @@ PGconn *PQconnectdbParams(const char * const *keywords, - 被传递的数组可以为空,这样就会使用所有默认参数。 - 也可以只包含一个或几个参数设置。他们在长度上必须匹配。 - 对于参数数组的处理将会停止于keywords数组中第一个NULL元素。 - 而且,如果与非-NULL keywords条目相关联的values条目为NULL或者空字符串,则忽略该项并继续处理下一对数组项。 + 传入的数组可以为空,以使用所有默认参数,也可以包含一个或多个参数设置。 + 两个数组的长度必须相同。处理会在 keywords 数组的第一个 NULL 元素处停止。 + 如果某个非 NULLkeywords 元素所对应的 + values 元素为 NULL 或空字符串,则忽略这一项,继续处理下一对数组元素。 - 当expand_dbname为非零时,会检查第一个dbname关键词的值以查看它是否为一个连接字符串。 - 如果是,它被扩展到从字符串中提取的单独的连接参数。 - 该值被认为是一个连接字符串,而不仅是一个数据库名称,如果它包含一个等号(=)或者它以URI模式标志符开头, - (有关连接字符串格式的更多详情可见。) - 只有dbname的第一次出现会按这种方式处理,任何后续dbname值会被当做一个普通数据库名处理。 + 当 expand_dbname 非零时,会检查第一个 dbname 关键词的值是否为 + 连接字符串。如果是,就将其展开为从该字符串中提取的各个连接参数。 + 如果该值包含等号(=),或以 URI 方案标识符开头,就会将其视为连接字符串,而非单纯的数据库名。 + (连接字符串格式的详细说明见。) + 只有第一次出现的 dbname 会按这种方式处理;后续的 dbname 参数都作为普通数据库名处理。 - 通常,参数数组从开头到结尾进行处理。 - 当关键词有重复时,使用最后一个值(不是 NULL 或空)。 - 此规则特别适用于连接字符串中的关键字与一个出现在keywords数组中的关键字冲突的情况。 - 因此,程序员可以决定数组条目是否能被覆盖或用连接字符串获取的值覆盖。 - 出现在扩展的dbname条目之前的数组条目可以被连接字符串的字段所覆盖,反之,这些字段被dbname之后出现的数组条目所覆盖。(但是,再有,只有在那些条目支持非空值时。) + 通常会从头到尾处理参数数组。如果某个关键词重复出现,则采用最后一个非 NULL 且非空的值。 + 此规则也适用于连接字符串中的关键词与 keywords 数组中的关键词冲突的情况。 + 因此,程序员可以决定数组元素是覆盖连接字符串中的值,还是被这些值覆盖。 + 出现在要展开的 dbname 元素之前的数组元素,可以被连接字符串中的字段覆盖; + 而这些字段又会被出现在 dbname 之后的数组元素覆盖(同样,只有这些元素提供非空值时才会覆盖)。 - 在处理完所有数组条目和任何扩展的连接字符串后,所有未设置的连接参数都将使用默认值填充。 - 如果一个未设置参数的相关环境变量(参见 )被设置了,它的值会被使用。 - 如果环境变量未被设置,则使用参数的内置默认值。 + 处理完所有数组元素及展开的连接字符串后,仍未设置的连接参数将填入默认值。 + 如果某个未设置参数对应的环境变量(见)已经设置,就使用该环境变量的值; + 否则使用该参数的内置默认值。 @@ -113,7 +113,7 @@ PGconn *PQconnectdb(const char *conninfo); - 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空格分隔的一个或多个参数设置,还可以包含一个URI。详见。 + 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空白分隔的一个或多个参数设置,还可以包含一个URI。详见 @@ -135,9 +135,13 @@ PGconn *PQsetdbLogin(const char *pghost, - 这是 PQconnectdb 的前身,使用固定的一组参数。除缺失参数始终采用默认值之外,功能相同。对于要使用默认值的任意固定参数,请传入 NULL 或空字符串。 + + 这是 PQconnectdb 的前身,使用固定的一组参数。除缺失参数始终采用默认值之外,功能相同。对于要使用默认值的任意固定参数,请传入 NULL 或空字符串。 + - 如果 dbName 包含 = 符号,或具有有效的连接 URI 前缀,就会将其当作 conninfo 字符串处理,方式与将其传给 PQconnectdb 完全相同,然后按照 PQconnectdbParams 的规则应用其余参数。 + + 如果 dbName 包含 = 符号,或具有有效的连接 URI 前缀,就会将其当作 conninfo 字符串处理,方式与将其传给 PQconnectdb 完全相同,然后按照 PQconnectdbParams 的规则应用其余参数。 + @@ -167,7 +171,7 @@ PGconn *PQsetdb(char *pghost, PQconnectPollPQconnectPoll - nonblocking connection + 非阻塞连接 以非阻塞的方式建立一个到数据库服务器的连接。 @@ -200,7 +204,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 如果你调用PQtrace,确保你追踪的该流对象不会阻塞。 + 如果你调用PQtrace,确保接收追踪输出的流对象不会阻塞。 @@ -213,7 +217,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 要开始无阻塞的连接请求,可调用PQconnectStart或者PQconnectStartParams。如果结果为空,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 + 要开始非阻塞连接请求,可调用PQconnectStart或者PQconnectStartParams。如果结果为空指针,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 @@ -312,11 +316,11 @@ switch(PQstatus(conn)) - 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。否则,PQconnectStart后面跟着PQconnectPoll循环等效于PQconnectdb。 + 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。除此之外,PQconnectStart后面跟着PQconnectPoll循环等效于PQconnectdb - 注意当PQconnectStartPQconnectStartParams返回一个非空的指针时,你必须在用完它之后调用PQfinish来处理那些结构体和任何相关的内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 + 注意当PQconnectStartPQconnectStartParams返回一个非空的指针时,你必须在用完它之后调用PQfinish来释放该结构体及其关联的所有内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 @@ -332,21 +336,21 @@ PQconninfoOption *PQconndefaults(void); typedef struct { char *keyword; /* 该选项的关键词 */ - char *envvar; /* 依赖的环境变量名 */ - char *compiled; /* 依赖的内置默认值 */ + char *envvar; /* 后备环境变量名 */ + char *compiled; /* 编译时设置的后备默认值 */ char *val; /* 选项的当前值,或者 NULL */ - char *label; /* 连接对话框中域的标签 */ - char *dispchar; /* 指示如何在一个连接对话框中显示这个域。值是: + char *label; /* 连接对话框中字段的标签 */ + char *dispchar; /* 指示如何在连接对话框中显示此字段。可取值: "" 显示输入的值 - "*" 密码域 - 隐藏值 + "*" 密码字段 - 隐藏值 "D" 调试选项 - 默认不显示 */ - int dispsize; /* 用于对话框的以字符计的域尺寸 */ + int dispsize; /* 对话框中的字段宽度,以字符计 */ } PQconninfoOption; - 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的PQconnectdb选项和它们的当前缺省值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回该空指针。注意当前缺省值(val域)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 + 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的PQconnectdb选项和它们的当前默认值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回空指针。注意当前默认值(val字段)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 @@ -366,7 +370,9 @@ PQconninfoOption *PQconninfo(PGconn *conn); - 返回一个连接选项数组。可以用它确定所有可能的 PQconnectdb 选项,以及实际用于连接服务器的值。返回值指向一个 PQconninfoOption 结构体数组,该数组以 keyword 指针为空的条目结束。上文针对 PQconndefaults 的所有注意事项,也适用于 PQconninfo 的结果。 + + 返回一个连接选项数组。可以用它确定所有可能的 PQconnectdb 选项,以及实际用于连接服务器的值。返回值指向一个 PQconninfoOption 结构体数组,该数组以 keyword 指针为空的条目结束。上文针对 PQconndefaults 的所有注意事项,也适用于 PQconninfo 的结果。 + @@ -392,7 +398,9 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); - 如果errmsg不是NULL,那么成功时*errmsg会被设置为NULL, 否则设置为被malloc过的错误字符串以说明该问题(也可以将*errmsg设置为NULL并且函数返回NULL,这表示一种内存耗尽的情况)。 + 如果 errmsg 不是 NULL,则成功时将 *errmsg 设为 NULL; + 失败时将其设为由 malloc 分配的、用于说明问题的错误字符串。 + (也可能出现 *errmsg 被设为 NULL,同时函数返回 NULL 的情况;这表示内存不足。) @@ -422,7 +430,7 @@ void PQfinish(PGconn *conn); PQresetPQreset - 重置与服务器的通讯通道。 + 重置与服务器的通信通道。 void PQreset(PGconn *conn); @@ -440,7 +448,7 @@ void PQreset(PGconn *conn); PQresetPollPQresetPoll - 以非阻塞方式重置与服务器的通讯通道。 + 以非阻塞方式重置与服务器的通信通道。 int PQresetStart(PGconn *conn); @@ -451,7 +459,9 @@ PostgresPollingStatusType PQresetPoll(PGconn *conn); 这些函数会关闭与服务器的连接,并尝试使用与之前完全相同的参数建立新连接。如果原本可用的连接丢失,这可以用于错误恢复。它们与上文的 PQreset 不同之处在于采用非阻塞方式。它们受到与 PQconnectStartParamsPQconnectStartPQconnectPoll 相同的限制。 - 要开始重置连接,请调用 PQresetStart。如果它返回 0,则重置失败。如果返回 1,则使用 PQresetPoll 轮询重置过程,其方式与使用 PQconnectPoll 创建连接完全相同。 + + 要开始重置连接,请调用 PQresetStart。如果返回 0,表示重置失败。如果返回 1,则使用 PQresetPoll 轮询重置过程,方式与使用 PQconnectPoll 建立连接完全相同。 + @@ -536,19 +546,19 @@ PGPing PQping(const char *conninfo); 几个libpq函数解析用户指定的字符串以获取连接参数。 - 这些字符串有两种被接受的格式:普通的关键字/值字符串和URI。URI通常遵循 + 这些字符串有两种被接受的格式:普通的关键词/值字符串和URI。URI通常遵循 RFC - 3986,除了允许多主机连接字符串,如下面进一步描述的那样。 + 3986,但也允许使用多主机连接字符串,详见下文。 关键词/值连接字符串 - 在关键词/值格式中,每一个参数设置的形式都是keyword = value,在设置之间有空白。 - 设置的等号周围的空白是可选的。 - 要写一个空值或一个包含空白的值,将它用单引号包围,例如keyword = 'a value'。 - 值里面的单引号和反斜线必须用一个反斜线转义,即\'\\。 + 在关键词/值格式中,每一个参数设置的形式都是关键词 = ,设置之间以空格分隔。 + 设置的等号周围的空格是可选的。 + 要写一个空值或一个包含空格的值,将它用单引号包围,例如keyword = 'a value'。 + 值里面的单引号和反斜杠必须用一个反斜杠转义,即\'\\ @@ -571,22 +581,22 @@ host=localhost port=5432 dbname=mydb connect_timeout=10 postgresql://userspec@hostspec/dbname?paramspec -where userspec is: +其中 userspec 为: user:password -and hostspec is: +hostspec 为: host:port,... -and paramspec is: +paramspec 为: name=value&... - URI模式标志符可以是postgresql://postgres://。 + URI方案标识符可以是postgresql://postgres://。 每一个剩下的URI部分都是可选的。 下列示例展示了合法的URI语法: @@ -603,7 +613,7 @@ postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application postgresql:///mydb?host=localhost&port=5433 - 全部的命名参数必须匹配中列出的关键词,除了与JDBC连接URI兼容之外,ssl=true的实例转换到sslmode=require。 + 所有命名参数都必须与中列出的关键词匹配;唯一的例外是,为兼容 JDBC 连接 URI,会将 ssl=true 转换为 sslmode=require 可以在 URI 的任意部分使用百分号编码来包含具有特殊含义的符号,例如将 = 替换为 %3D @@ -619,7 +629,7 @@ postgresql://[2001:db8::1234]/database 主机组件会被按照参数对应的描述来解释。 特别地,如果主机部分是空或看起来像一个绝对路径名称,将使用一个 Unix 域套接字连接,否则将启动一个 TCP/IP 连接。 不过要注意,斜线是 URI 层次部分中的一个保留字符。 - 因此,要指定一个非标准的 Unix 域套接字目录,要么忽略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: + 因此,要指定一个非标准的 Unix 域套接字目录,要么省略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: postgresql:///dbname?host=/var/lib/postgresql postgresql://%2Fvar%2Flib%2Fpostgresql/dbname @@ -629,7 +639,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以在一个URI中指定多个主机,每一个都有一个可选的端口。 一个形式为postgresql://host1:port1,host2:port2,host3:port3/的URI等效于host=host1,host2,host3 port=port1,port2,port3形式的连接字符串。 - 如下所述,每一个主机都将被尝试,直到成功地建立一个连接。 + 如下所述,每一个主机都将被依次尝试,直到成功地建立一个连接。 @@ -639,7 +649,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以指定多个要连接的主机,这样它们会按给定的顺序被尝试。 - 在键/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 + 在关键词/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 在指定的每一个选项中都必须给出相同数量的元素,这样第一个hostaddr对应于第一个主机名,第二个hostaddr对应于第二个主机名,以此类推。 不过,如果仅指定一个port,它将被应用于所有的主机。 @@ -649,11 +659,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 不管是哪一种格式,单一的主机名可以被翻译成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 + 不管是哪一种格式,单一的主机名可以被解析成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 - 当多个主机被指定时或者单个主机名被翻译成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。 + 当多个主机被指定时或者单个主机名被解析成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。 @@ -687,7 +697,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 如果指定了host而没有指定hostaddr,则会发生主机名查找。 (当使用PQconnectPoll时,查找发生在PQconnectPoll首次考虑此主机名时, - 并且可能导致PQconnectPoll阻塞一段时间。) + 并且可能导致PQconnectPoll阻塞相当长的时间。) @@ -699,11 +709,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果同时指定了hosthostaddr, - 则hostaddr的值给出服务器的网络地址。 - 除非认证方法需要,否则host的值将被忽略, - 在这种情况下,它将用作主机名。 - + 如果同时指定了 hosthostaddr,则 hostaddr 的值给出服务器的网络地址。只有认证方法需要主机名时,才会将 host 的值用作主机名;否则忽略该值。 + 注意,以下情况很可能导致认证失败:host不是位于网络地址hostaddr的服务器名称。另外,同时指定hosthostaddr时,将使用host来标识密码文件中的连接(参见)。 @@ -747,8 +754,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - PostgreSQL用户连接的用户名。 - 默认为运行应用程序的操作系统用户名相同。 + 建立连接所用的 PostgreSQL 用户名。默认与运行应用程序的操作系统用户名相同。 @@ -758,7 +764,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果服务器要求密码认证,则使用密码。 + 服务器要求密码认证时所使用的密码。 @@ -828,9 +834,9 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 指定配置参数的回退值。 + 指定配置参数的后备值。 如果没有通过连接参数或PGAPPNAME环境变量为application_name指定值, - 则将使用此值。在通用实用程序中指定回退名称很有用,该程序希望设置默认应用程序名称, + 则将使用此值。在通用实用程序中指定后备名称很有用,该程序希望设置默认应用程序名称, 但允许用户覆盖它。 @@ -841,9 +847,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制是否使用客户端TCP保持活动。默认值为1,表示开启,但如果不想要保持活动,可以将其更改为0,表示关闭。 - 对于通过Unix域套接字进行的连接,此参数将被忽略。 - + 控制是否使用客户端 TCP keepalive。默认值为 1,表示开启;如果不需要 keepalive,可以将其设为 0,表示关闭。对于通过 Unix 域套接字建立的连接,此参数会被忽略。 + @@ -852,11 +857,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在多少秒的不活动后,TCP应向服务器发送保持活动消息。值为零使用系统默认值。 - 对通过Unix域套接字进行的连接或禁用保持活动的连接,此参数将被忽略。 - 仅在支持TCP_KEEPIDLE或等效套接字选项的系统以及Windows上支持; - 在其他系统上,它没有任何效果。 - + 控制在多久没有活动后,TCP 应向服务器发送 keepalive 消息,以秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPIDLE 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -865,11 +867,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在服务器未确认的情况下重新传输TCP保持活动消息的秒数。值为零时使用系统默认值。 - 此参数在通过Unix域套接字进行连接或禁用保持活动时将被忽略。 - 仅在支持TCP_KEEPINTVL或等效套接字选项的系统和Windows上支持; - 在其他系统上,此参数无效。 - + 控制未被服务器确认收到的 TCP keepalive 消息在多少秒后应被重传。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPINTVL 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -878,11 +877,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在客户端与服务器之间连接被视为断开之前可以丢失的TCP keepalive数量。 - 值为零时使用系统默认值。对通过Unix域套接字建立的连接或禁用keepalives的连接,此参数将被忽略。 - 仅在支持TCP_KEEPCNT或等效套接字选项的系统上受支持; - 在其他系统上,此参数无效。 - + 控制在客户端与服务器之间的连接被视为中断之前,可以丢失多少个 TCP keepalive 消息。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPCNT 或等效套接字选项的系统上受支持;在其他系统上无效。 + @@ -973,7 +969,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - prefer (默认) + prefer (默认) 首先尝试SSL连接;如果失败,则尝试非SSL连接 @@ -1013,13 +1009,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - sslmode被忽略用于Unix域套接字通信。 - 如果PostgreSQL没有SSL支持编译, + 在 Unix 域套接字通信中,sslmode 会被忽略。 + 如果PostgreSQL编译时未启用 SSL 支持, 使用选项requireverify-caverify-full会导致错误,而选项allowprefer 将被接受,但libpq实际上不会尝试建立SSL 连接。SSL使用libpq的SSL + sortas="libpq">在 libpq 中 @@ -1029,15 +1025,15 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 此选项已被sslmode设置所取代。 - + 此选项已弃用,请改用 sslmode 设置。 + 如果设置为1,则需要与服务器建立SSL连接(这相当于sslmode require)。libpq将拒绝连接,如果服务器不接受 SSL连接。如果设置为0(默认值), libpq将与服务器协商连接类型(相当于sslmode - prefer)。此选项仅在PostgreSQL编译时启用SSL支持。 + prefer)。此选项仅在 PostgreSQL 编译时启用了 SSL 支持的情况下可用。 @@ -1053,7 +1049,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname SSL 压缩现在被认为不安全,已不再建议使用。OpenSSL 1.1.0 默认禁用压缩,许多操作系统发行版也在更早的版本中禁用了压缩,因此,如果服务器不接受压缩,将此参数设为 on 不会产生效果。另一方面,OpenSSL 1.0.0 之前的版本不支持禁用压缩,因此这些版本会忽略此参数,是否使用压缩取决于服务器。 - 如果安全性不是主要考虑因素,压缩可以提高吞吐量,如果网络是瓶颈的话。如果CPU性能是限制因素,禁用压缩可以提高响应时间和吞吐量。 + 如果安全性不是主要考虑因素,压缩可以提高吞吐量,如果网络是瓶颈的话。如果CPU性能是限制因素,禁用压缩可以缩短响应时间并提高吞吐量。 @@ -1077,7 +1073,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 这个参数指定了用于客户端证书的密钥的位置。它可以指定一个文件名,该文件名将被用来替代默认的 ~/.postgresql/postgresql.key,或者它可以指定一个从外部引擎 - (引擎是OpenSSL可加载模块)获取的密钥。外部引擎规范应该包括一个由冒号分隔的引擎名称和 + (引擎是OpenSSL可加载模块)获取的密钥。外部引擎的指定形式应包含一个由冒号分隔的引擎名称和 一个引擎特定的密钥标识符。如果没有进行SSL连接,则此参数将被忽略。 @@ -1122,7 +1118,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname krbsrvname - 用于使用GSSAPI进行认证时要使用的Kerberos服务名称。 + 使用 GSSAPI 认证时所用的 Kerberos 服务名。 这必须与服务器配置中指定的Kerberos认证服务名称匹配,才能成功进行认证。 (另请参见。) @@ -1167,20 +1163,21 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 连接状态函数 - 这些函数可以被用来询问一个已有数据库连接对象的状态。 + 这些函数可用于查询现有数据库连接对象的状态。 - libpq-fe.h - libpq-int.h - libpq应用程序员应该小心地维护PGconn抽象。使用下面描述的访问函数来理解PGconn的内容。我们不推荐使用libpq-int.h引用内部的PGconn域,因为它们可能在未来改变。 - + libpq-fe.h + libpq-int.h + 编写 libpq 应用程序时,应注意维护 PGconn 的抽象。请使用下述访问函数获取 PGconn 的内容。不建议通过 libpq-int.h 引用 PGconn 的内部字段,因为这些字段将来可能改变。 + - 以下函数返回建立连接时确定的参数值。这些值在连接存续期间保持不变。如果使用多主机连接字符串,以下函数的值:PQhost, - PQportPQpass可能会在使用同一个PGconn对象建立新连接时改变。其他值在以下对象的整个生命周期内保持不变:PGconn对象。 + + 以下函数返回建立连接时确定的参数值。这些值在连接存续期间保持不变。如果使用多主机连接字符串,并使用同一个 PGconn 对象建立新连接,则 PQhostPQportPQpass 的返回值可能改变。其他值在 PGconn 对象的整个生命周期内保持不变。 + PQdb PQdb @@ -1227,7 +1224,7 @@ char *PQpass(const PGconn *conn); - 返回活跃连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 + 返回活动连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 char *PQhost(const PGconn *conn); @@ -1239,7 +1236,7 @@ char *PQhost(const PGconn *conn); - 如果conn参数是NULL,则PQhost返回NULL。否则,如果在生成主机信息时发生错误(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 PQhost 返回 NULL。否则,如果在生成主机信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1253,7 +1250,7 @@ char *PQhost(const PGconn *conn); - 返回活跃连接的端口。 + 返回活动连接的端口。 char *PQport(const PGconn *conn); @@ -1265,7 +1262,7 @@ char *PQport(const PGconn *conn); - 如果conn参数是NULL,则PQport返回NULL。否则,如果在生成端口信息时发生错误(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 PQport 返回 NULL。否则,如果在生成端口信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1278,7 +1275,9 @@ char *PQport(const PGconn *conn); PQtty PQtty - 返回连接的调试TTY。(此设置已过时,因为服务器不再理会TTY设置,但为保持向后兼容,仍保留了此函数。) + + 返回该连接用于调试的TTY。(此功能已过时,因为服务器不再使用TTY设置,但为保持向后兼容仍保留此函数。) + char *PQtty(const PGconn *conn); @@ -1290,7 +1289,7 @@ char *PQtty(const PGconn *conn); - 返回被传递给连接请求的命令行选项。 + 返回连接请求中传递的命令行选项。 char *PQoptions(const PGconn *conn); @@ -1298,9 +1297,11 @@ char *PQoptions(const PGconn *conn); - + - 以下函数返回的状态数据可能在执行操作时发生变化,这些操作针对PGconn对象。 + + 以下函数返回的状态数据,可能随着对 PGconn 对象执行操作而改变。 + PQstatus PQstatus @@ -1336,7 +1337,7 @@ ConnStatusType PQstatus(const PGconn *conn); PGTransactionStatusType PQtransactionStatus(const PGconn *conn); - 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个合法的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接损坏,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE。 + 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个有效的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接异常,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE @@ -1378,9 +1379,12 @@ const char *PQparameterStatus(const PGconn *conn, const char *paramName); PQprotocolVersion PQprotocolVersion - 查询正在使用的前端/后端协议。 + + 查询正在使用的前端/后端协议。 + int PQprotocolVersion(const PGconn *conn); -应用程序可以使用此函数判断是否支持某些特性。目前可能的值为 2(协议 2.0)、3(协议 3.0)或零(连接无效)。连接启动完成后,协议版本不会改变,但理论上可能在重置连接时改变。与PostgreSQL7.4 或更新版本的服务器通信时,通常使用协议 3.0;7.4 之前的服务器仅支持协议 2.0。(协议 1.0 已过时,且不被以下库支持:libpq。) + +应用程序可以使用此函数判断是否支持某些特性。目前,可能的值为 2(协议 2.0)、3(协议 3.0)或零(连接异常)。连接启动完成后,协议版本不会改变,但理论上可能在连接重置期间改变。通常,与 PostgreSQL 7.4 或更高版本的服务器通信时使用协议 3.0;7.4 之前的服务器仅支持协议 2.0。(协议 1.0 已过时,libpq 不支持它。) @@ -1401,11 +1405,11 @@ int PQserverVersion(const PGconn *conn); - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,PQserverVersion为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 + 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,PQserverVersion为每个部分使用两位数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - 因此,出于判断特性兼容性的目的,应用应该将PQserverVersion的结果除以100而不是10000来判断逻辑的主版本号。在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 + 因此,出于判断特性兼容性的目的,应用应该将PQserverVersion的结果除以100而不是10000来判断逻辑的主版本号。在所有主版本系列中,各次版本(缺陷修复版本)之间只有最后两位数字不同。 @@ -1424,9 +1428,7 @@ char *PQerrorMessage(const PGconn *conn); - 几乎所有的libpq函数在失败时都会为PQerrorMessage设置一个消息。 - 注意按照libpq习惯,一个非空PQerrorMessage结果可能由多行构成,并且将包括一个尾部新行。 - 调用者不应该直接释放结果。当相关的PGconn句柄被传递给PQfinish时,它将被释放。在PGconn结构体上的多个操作之间,不能指望结果字符串会保持不变。 + 几乎所有 libpq 函数在失败时都会设置一条供 PQerrorMessage 返回的消息。注意,按照 libpq 的约定,非空的 PQerrorMessage 结果可能包含多行,并以换行符结尾。调用者不应直接释放该结果;当关联的 PGconn 句柄被传给 PQfinish 时,结果会被释放。不能假定在对 PGconn 结构体执行其他操作后,结果字符串仍保持不变。 @@ -1435,7 +1437,7 @@ char *PQerrorMessage(const PGconn *conn); PQsocketPQsocket - 获得到服务器连接套接字的文件描述符号。一个合法的描述符将会大于等于零。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 + 获取与服务器相连的套接字的文件描述符编号。有效描述符大于或等于 0。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 int PQsocket(const PGconn *conn); @@ -1452,7 +1454,7 @@ int PQsocket(const PGconn *conn); 返回处理这个连接的后端进程的进程ID(PID)。 PID 确定服务器进程的 PID - in libpq + 在 libpq 中 @@ -1461,7 +1463,7 @@ int PQbackendPID(const PGconn *conn); - 后端PID有助于调试目的并且可用于与NOTIFY消息(它包括发出提示的后端进程的PID)进行比较。注意PID属于一个在数据库服务器主机上执行的进程,而不是本地主机进程! + 后端 PID 可用于调试,也可与 NOTIFY 消息进行比较(消息包含发出通知的后端进程的 PID)。注意,该 PID 属于在数据库服务器主机上运行的进程,而非本地主机上的进程! @@ -1500,15 +1502,17 @@ int PQconnectionUsedPassword(const PGconn *conn); - + - 以下函数返回与 SSL 相关的信息。这些信息通常在连接建立后不会改变。 + + 以下函数返回与 SSL 相关的信息。这些信息通常在连接建立后不会改变。 + PQsslInUsePQsslInUse - 返回true(1)如果连接使用SSL,返回false(0)如果不使用。 + 如果连接使用 SSL,则返回真(1);否则返回假(0)。 int PQsslInUse(const PGconn *conn); @@ -1527,10 +1531,10 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); - 可用属性列表因使用的SSL库和连接类型而异。如果连接不使用SSL或指定的属性名称对于所使用的库未定义,则返回NULL。 + 可用属性列表因所使用的 SSL 库和连接类型而异。如果某个属性不可用,则返回 NULL。 - 通常可以取得以下属性: + 通常可以获取以下属性: library @@ -1595,12 +1599,14 @@ const char * const * PQsslAttributeNames(const PGconn *conn); PQsslStructPQsslStruct - 返回一个指向描述连接的SSL实现特定对象的指针。如果连接未加密或SSL实现不提供连接的请求对象类型,则返回NULL。 + 返回指向描述此连接的对象的指针,该对象的类型由 SSL 实现决定。 void *PQsslStruct(const PGconn *conn, const char *struct_name); - 可用的结构体取决于所使用的 SSL 实现。对于 OpenSSL,有一个名为 "OpenSSL" 的结构体,取得它时会返回指向 OpenSSLSSL结构体的指针。可以使用类似以下的代码来调用此函数: + 可用的结构体取决于所使用的 SSL 实现。对于 OpenSSL,可以通过名称 "OpenSSL" 获取一个结构体,函数返回指向 OpenSSL 的 SSL 结构体的指针。可以使用如下代码调用此函数: + #include @@ -1642,7 +1648,7 @@ void *PQgetssl(const PGconn *conn); - + @@ -1650,7 +1656,7 @@ void *PQgetssl(const PGconn *conn); 命令执行函数 - 一旦到一个数据库服务器的连接被成功建立,这里描述的函数可以被用来执行 SQL 查询和命令。 + 与数据库服务器的连接成功建立后,此处描述的函数用于执行 SQL 查询和命令。 @@ -1671,11 +1677,8 @@ PGresult *PQexec(PGconn *conn, const char *command); - 返回一个PGresult指针或者可能是一个空指针。 - 除了内存不足的情况或者由于严重错误无法将命令发送给服务器之外,一般都会返回一个非空指针。 - PQresultStatus函数应当被调用来检查返回值是否代表错误(包括空指针的值,它会返回PGRES_FATAL_ERROR)。 - 用PQerrorMessage可得到关于那些错误的详细信息。 - + 返回一个 PGresult 指针,也可能返回空指针。除内存不足或无法向服务器发送命令等严重错误外,通常都会返回非空指针。应调用 PQresultStatus 函数检查返回值是否表示错误(也应检查空指针,此时该函数返回 PGRES_FATAL_ERROR)。使用 PQerrorMessage 获取此类错误的更多信息。 + 命令字符串可以包含多个 SQL 命令(以分号分隔)。在一次PQexec调用中发送的多个查询会在同一个事务中处理,除非查询字符串中显式包含BEGIN/COMMIT命令,将其划分为多个事务。(有关服务器如何处理多查询字符串的详细信息,请参见。)但要注意,返回的PGresult结构体只描述该字符串中最后执行的命令的结果。如果其中一条命令失败,就会在此处停止处理该字符串,返回的PGresult则描述该错误。 @@ -1748,8 +1751,8 @@ PGresult *PQexecParams(PGconn *conn, paramValues[] - 指定参数的实际值。这个数组中的一个空指针表示对应的参数为空,否则该指针指向一个以零终止的文本字符串(用于文本格式)或者以服务器所期待格式的二进制数据(用于二进制格式)。 - + 指定参数的实际值。数组中的空指针表示对应参数为 null;否则,指针指向以零结尾的文本字符串(文本格式),或采用服务器所要求格式的二进制数据(二进制格式)。 + @@ -1757,8 +1760,8 @@ PGresult *PQexecParams(PGconn *conn, paramLengths[] - 指定二进制格式参数的实际数据长度。它对空参数和文本格式参数被忽略。当没有二进制参数时,该数组指针可以为空。 - + 指定二进制格式参数的实际数据长度。对于 null 参数和文本格式参数,该值会被忽略。如果没有二进制参数,数组指针可以为空指针。 + @@ -1766,11 +1769,11 @@ PGresult *PQexecParams(PGconn *conn, paramFormats[] - 指定参数是否为文本(在参数相应的数组项中放一个零)或二进制(在参数相应的数组项中放一个一)。如果该数组指针为空,那么所有参数都会被假定为文本串。 - + 指定参数采用文本格式(在对应数组元素中填入零)还是二进制格式(填入一)。如果数组指针为空指针,则将所有参数视为文本字符串。 + - 以二进制格式传递的值要求后端所期待的内部表示形式的知识。例如,整数必须以网络字节序被传递。传递numeric值要求关于服务器存储格式的知识,正如src/backend/utils/adt/numeric.c::numeric_send()以及src/backend/utils/adt/numeric.c::numeric_recv()中所实现的。 - + 以二进制格式传递值时,需要了解后端所要求的内部表示形式。例如,整数必须以网络字节序传递。传递 numeric 值时,需要了解服务器的存储格式,其实现见 src/backend/utils/adt/numeric.c::numeric_send()src/backend/utils/adt/numeric.c::numeric_recv()。 + @@ -1778,8 +1781,8 @@ PGresult *PQexecParams(PGconn *conn, resultFormat - 指定零来得到文本格式的结果,或者指定一来得到二进制格式的结果(目前没有规定要求以不同格式得到不同的结果列,尽管在底层协议中这是可以实现的)。 - + 指定零以获取文本格式的结果,指定一以获取二进制格式的结果。(目前无法让不同结果列使用不同格式,尽管底层协议支持这样做。) + @@ -1789,7 +1792,9 @@ PGresult *PQexecParams(PGconn *conn, - PQexecParams 相对于 PQexec 的主要优点是可以将参数值与命令字符串分开,从而避免繁琐且容易出错的加引号和转义工作。 + + PQexecParams 相对于 PQexec 的主要优点是可以将参数值与命令字符串分开,从而避免繁琐且容易出错的加引号和转义工作。 + PQexec不同,PQexecParams至多允许在给定串中出现一个 SQL 命令(其中可以有分号,但是不能有超过一个非空命令)。这是底层协议的一个限制,但是有助于抵抗 SQL 注入攻击。 @@ -1798,12 +1803,12 @@ PGresult *PQexecParams(PGconn *conn, - 通过 OID 指定参数类型很罗嗦,特别是如果你不愿意将特定的 OID 值硬编码到你的程序中时。不过,即使服务器本身也无法确定参数的类型,你可以避免这样做,或者选择一种与你想要的不同的类型。在 SQL 命令文本中,附加一个显式类型转换给参数符号来表示你将发送什么样的数据类型。例如: + 通过 OID 指定参数类型较为繁琐,尤其是在不希望将具体 OID 值写死在程序中时。不过,即使服务器无法自行确定参数类型,或者推断出的类型与你所需的不同,也可以避免直接指定 OID。在 SQL 命令文本中,为参数符号添加显式类型转换,即可指定要发送的数据类型。例如: SELECT * FROM mytable WHERE x = $1::bigint; - 这强制参数$1被当作bigint,而默认情况下它将被赋予与x相同的类型。当以二进制格式发送参数值时,我们强烈推荐以这种方式或通过指定一个数字类型的 OID 来强制参数类型决定。因为二进制格式比文本格式具有更少的冗余,并且因此服务器将不会有更多机会为你检测一个类型匹配错误。 - +这会强制将参数 $1 当作 bigint,而默认情况下会为它分配与 x 相同的类型。以二进制格式发送参数值时,强烈建议采用这种方式,或直接指定类型的数值 OID,来明确决定参数类型。因为二进制格式的冗余比文本格式更少,服务器发现类型不匹配错误的机会也更少。 + @@ -1823,13 +1828,15 @@ PGresult *PQprepare(PGconn *conn, - PQprepare创建一个后面会由PQexecPrepared执行的预备语句。 这个特性允许命令被反复执行而无需每次都进行解析和规划,详见PQprepare 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + + PQprepare 创建一个预备语句,供随后使用 PQexecPrepared 执行。 这个特性允许命令被反复执行而无需每次都进行解析和规划,详见PQprepare 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + 该函数从query串创建一个名为stmtName的预备语句,该串必须包含一个单一 SQL 命令。 stmtName可以是""来创建一个未命名语句,在这种情况下任何已存在未命名语句将被自动替换。 否则,如果语句名称已经在当前会话中被定义,则是一种错误。如果使用了任何参数,它们在查询中以$1$2等引用。 - nParams是参数的个数,其类型在数组paramTypes[]中被预先指定(当nParams为零时,该数组指针可以是NULL)。 + nParams 是在数组 paramTypes[] 中预先指定了类型的参数数量(当nParams为零时,该数组指针可以是NULL)。 paramTypes[]通过 OID 指定要赋予给参数符号的数据类型。 如果paramTypesNULL或者该数组中任何特定元素为零,服务器会用对待未指定类型的字符串字面量的方式为参数符号推测一种数据类型。 还有,查询能够使用编号高于nParams的参数符号,它们的数据类型也会被自动推测(找出推测出的数据类型的方法见PQdescribePrepared)。 @@ -1837,7 +1844,7 @@ PGresult *PQprepare(PGconn *conn, 正如PQexec一样,结果通常是一个PGresult对象,其内容代表服务器端成功或失败。 - 一个空结果表示内存不足或者根本无法发送命令。关于错误的更多信息请见PQerrorMessage。 + 返回空指针表示内存不足,或者根本无法发送命令。关于错误的更多信息请见PQerrorMessage @@ -1862,7 +1869,7 @@ PGresult *PQexecPrepared(PGconn *conn, - PQexecPrepared类似于PQexecParams, 但要执行的命令是通过指定先前准备好的语句来指定,而不是提供查询字符串。 此功能允许重复使用的命令只被解析和计划一次,而不是每次执行时都要进行。 该语句必须在当前会话中先前准备好。 PQexecPrepared 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + PQexecPrepared类似于PQexecParams, 但它通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。 此功能使重复使用的命令只需解析和规划一次,而不必在每次执行时都进行这些工作。 该语句必须事先在当前会话中创建为预备语句。 PQexecPrepared 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 参数与PQexecParams相同,只是给出了预备语句的名称而不是查询字符串, @@ -1876,21 +1883,21 @@ PGresult *PQexecPrepared(PGconn *conn, - 提交请求以获取有关指定准备好的语句的信息,并等待完成。 + 提交请求以获取有关指定预备语句的信息,并等待完成。 PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - PQdescribePrepared允许应用程序获取关于先前准备的语句的信息。 PQdescribePrepared 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + PQdescribePrepared允许应用程序获取关于先前创建的预备语句的信息。 PQdescribePrepared 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 stmtName可以是""NULL来引用 - 未命名的语句,否则必须是现有准备好的语句的名称。成功时,返回一个 + 未命名的语句,否则必须是现有预备语句的名称。成功时,返回一个 状态为PGRES_COMMAND_OKPGresult。 函数PQnparamsPQparamtype可以应用于此 - PGresult以获取有关准备语句参数的信息, + PGresult以获取有关预备语句参数的信息, 函数PQnfieldsPQfnamePQftype等提供有关语句的结果列(如果有)的信息。 @@ -1902,13 +1909,15 @@ PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - 提交请求以获取有关指定门户的信息,并等待完成。 + 提交请求以获取有关指定 portal 的信息,并等待完成。 PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - PQdescribePortal允许应用程序获取有关先前创建的 portal 的信息。 (libpq不直接提供对 portal 的访问,但你可以使用此函数检查通过DECLARE CURSOR SQL 命令创建的游标的属性。) PQdescribePortal 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + + PQdescribePortal 允许应用程序获取先前创建的 portal 的信息。(libpq 不提供对 portal 的直接访问,但可以用此函数检查通过 DECLARE CURSOR SQL 命令创建的游标的属性。) PQdescribePortal 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + portalName可以是""NULL来引用未命名的 portal, @@ -1921,7 +1930,9 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - PGresultPGresult结构体封装服务器返回的结果。libpq应用程序的开发者应注意保持PGresult的抽象性。请使用下面的访问函数获取PGresult的内容。避免直接引用PGresult结构体的字段,因为这些字段以后可能改变。 + + PGresultPGresult 结构体封装服务器返回的结果。编写 libpq 应用程序时,应注意维护 PGresult 的抽象。请使用下述访问函数获取 PGresult 的内容。避免直接引用 PGresult 结构体的字段,因为这些字段将来可能改变。 + PQresultStatus PQresultStatus @@ -2020,7 +2031,7 @@ ExecStatusType PQresultStatus(const PGresult *res); PGRES_SINGLE_TUPLE - PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单一行模式时发生(见)。 + PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单行模式时发生(见)。 @@ -2037,10 +2048,12 @@ ExecStatusType PQresultStatus(const PGresult *res); PQresStatus PQresStatus - PQresultStatus返回的枚举值转换为描述该状态码的字符串常量。调用者不应释放此结果。 + + 将 PQresultStatus 返回的枚举值转换为描述该状态码的字符串常量。调用者不应释放此结果。 + char *PQresStatus(ExecStatusType status); - + @@ -2048,10 +2061,13 @@ char *PQresStatus(ExecStatusType status); PQresultErrorMessage PQresultErrorMessage - 返回与命令关联的错误消息;如果没有错误,则返回空字符串。 + + 返回与命令关联的错误消息;如果没有错误,则返回空字符串。 + char *PQresultErrorMessage(const PGresult *res); -如果发生了错误,返回的字符串会包含末尾换行符。调用者不应直接释放结果。在将关联的PGresult句柄传给以下函数时,会释放该结果:PQclear。 - + +如果发生了错误,返回的字符串会以换行符结尾。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 PQclear 时,结果会被释放。 + 紧跟着一个PQexecPQgetResult调用,PQerrorMessage(在连接上)将返回与PQresultErrorMessage相同的字符串(在结果上)。 @@ -2066,11 +2082,15 @@ char *PQresultErrorMessage(const PGresult *res); PQresultVerboseErrorMessage PQresultVerboseErrorMessage - 返回与PGresult对象关联的错误消息的重新格式化版本。 + + 返回与 PGresult 对象关联的错误消息的重新格式化版本。 + char *PQresultVerboseErrorMessage(const PGresult *res, PGVerbosity verbosity, PGContextVisibility show_context); -某些情况下,客户端可能希望取得之前报告的错误的更详细版本。PQresultVerboseErrorMessage可以满足这一需求:它计算以下函数本应生成的消息:PQresultErrorMessage,假设在生成给定的PGresult时,连接已经采用指定的详细程度设置。如果PGresult不是错误结果,则改为报告PGresult is not an error result。返回的字符串包含末尾换行符。 + +有时客户端希望获取先前报告过的错误的更详细版本。PQresultVerboseErrorMessage 可满足这一需求:它按指定的详细程度设置重新生成消息。假如在生成给定 PGresult 时,连接已经采用这些设置,那么 PQresultErrorMessage 返回的就会是这条消息。如果 PGresult 不是错误结果,则改为报告 PGresult is not an error result。返回的字符串以换行符结尾。 + 和大部分从PGresult中提取数据的其他函数不同,这个函数的结果是一个全新分配的字符串。调用者在不需要这个字符串以后,必须使用PQfreemem()释放它。 @@ -2085,18 +2105,20 @@ char *PQresultVerboseErrorMessage(const PGresult *res, PQresultErrorFieldPQresultErrorField - 返回错误报告中的单个字段。 + + 返回错误报告中的单个字段。 + char *PQresultErrorField(const PGresult *res, int fieldcode); - fieldcode是错误字段标识符,参见下文列出的符号。NULL会在以下情况下返回:PGresult不是错误或警告结果,或者不包含指定字段。字段值通常不含末尾换行符。调用者不应直接释放结果。在将关联的PGresult句柄传给以下函数时,会释放该结果:PQclear。 - +fieldcode 是错误字段标识符,参见下文列出的符号。如果 PGresult 不是错误或警告结果,或者不包含指定字段,则返回 NULL。字段值通常不含末尾换行符。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 PQclear 时,结果会被释放。 + 可以使用以下字段代码: PG_DIAG_SEVERITY - 严重性。域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 @@ -2105,16 +2127,16 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_SEVERITY_NONLOCALIZED - 域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY域相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 版本以后产生的报告中。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY字段相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 及更高版本产生的报告中。 - PG_DIAG_SQLSTATEerror codeslibpq + PG_DIAG_SQLSTATE错误码libpq - 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个域无法被本地化,并且总是存在。 + 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个字段无法被本地化,并且总是存在。 @@ -2141,7 +2163,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_MESSAGE_HINT - 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是铁的事实。可能有多行。 + 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是确切事实。可能有多行。 @@ -2159,7 +2181,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_INTERNAL_POSITION - 这被定义为与PG_DIAG_STATEMENT_POSITION域相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个域出现时,PG_DIAG_INTERNAL_QUERY域将总是出现。 + 这被定义为与PG_DIAG_STATEMENT_POSITION字段相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个字段出现时,PG_DIAG_INTERNAL_QUERY字段将总是出现。 @@ -2177,7 +2199,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONTEXT - 指示错误发生的环境。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 + 指示错误发生的上下文。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 @@ -2195,7 +2217,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_TABLE_NAME - 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名域)。 + 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名字段)。 @@ -2204,7 +2226,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_COLUMN_NAME - 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名域来标识该表)。 + 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名字段来标识该表)。 @@ -2213,7 +2235,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_DATATYPE_NAME - 如果错误与一个特定数据类型相关,这里是该数据了行的名字(该数据类型的模式名参考模式名域)。 + 如果错误与一个特定数据类型相关,这里是该数据类型的名字(该数据类型的模式名参考模式名字段)。 @@ -2222,7 +2244,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONSTRAINT_NAME - 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的域(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 + 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的字段(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 @@ -2258,12 +2280,12 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); - 用于模式名、表名、列名、数据类型名和约束名的域只提供给有限的错误类型,见。不要假定任何这些域的存在保证另一个域的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些域。同样地,不要假定这些域代表当前数据库中同类的对象。 + 用于模式名、表名、列名、数据类型名和约束名的字段只提供给有限的错误类型,见。不要假定任何这些字段的存在保证另一个字段的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些字段。同样地,不要假定这些字段代表当前数据库中现存的对象。 - 客户端负责格式化显示信息来迎合它的需要,特别是根据需要打断长的行。出现在错误消息域中的新行字符应该被当作分段而不是换行。 + 客户端负责按自身需要格式化所显示的信息,尤其应在需要时将长行折行。错误消息字段中的换行符应当视为段落分隔,而非行分隔。 libpq 内部产生的错误包含严重性和主要消息,但通常没有其他字段。使用 3.0 之前协议的服务器返回的错误包含严重性和主要消息,有时还包含详细消息,但没有其他字段。 @@ -2277,10 +2299,12 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PQclearPQclear - 释放与PGresult关联的存储空间。每个命令结果都应通过PQclear在不再需要结果时将其释放。 + + 释放与 PGresult 关联的存储空间。每个命令结果在不再需要时都应通过 PQclear 释放。 + void PQclear(PGresult *res); - + 你可以在需要时一直保留PGresult对象;它不会在你发出新命令时消失,甚至在关闭连接后也不会消失。要销毁它,你必须调用PQclear。否则应用程序会发生内存泄漏。 @@ -2288,15 +2312,15 @@ void PQclear(PGresult *res); - + 检索查询结果信息 - 这些函数被用来从一个代表成功查询结果(也就是状态为PGRES_TUPLES_OK或者PGRES_SINGLE_TUPLE)的PGresult对象中抽取信息。它们也可以被用来从一个成功的 Describe 操作中抽取信息:一个 Describe 的结果具有和该查询被实际执行所提供的完全相同的列信息,但是它没有行。对于其他状态值的对象,这些函数会认为结果具有零行和零列。 - + 这些函数用于从表示成功查询结果的 PGresult 对象中提取信息,即状态为 PGRES_TUPLES_OKPGRES_SINGLE_TUPLE 的对象。它们也可用于提取成功 Describe 操作的结果信息:Describe 结果包含的列信息与实际执行查询时相同,但行数为零。对于其他状态值的对象,这些函数会将结果视为零行、零列。 + @@ -2321,7 +2345,7 @@ int PQntuples(const PGresult *res); - 返回查询结果中每一行的列(域)数。 + 返回查询结果中每一行的列(字段)数。 int PQnfields(const PGresult *res); @@ -2334,7 +2358,8 @@ int PQnfields(const PGresult *res); PQfname PQfname - 返回给定列号对应的列名。列号从 0 开始。调用者不应直接释放结果。在将关联的PGresult句柄传给以下函数时,会释放该结果:PQclear。 + + 返回给定列号对应的列名。列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 PQclear 时,结果会被释放。 char *PQfname(const PGresult *res, int column_number); @@ -2365,11 +2390,11 @@ int PQfnumber(const PGresult *res, - 给定的名称被视作一个 SQL 命令中的一个标识符,也就是说,除非被双引号引用,它是小写形式的。例如,给定一个 SQL 命令: + 给定名称按 SQL 命令中的标识符处理,即除非用双引号引用,否则会转换为小写。例如,对于以下 SQL 命令生成的查询结果: SELECT 1 AS FOO, 2 AS "BAR"; - 我们将得到结果: +会得到以下结果: PQfname(res, 0) foo PQfname(res, 1) BAR @@ -2387,7 +2412,7 @@ PQfnumber(res, "\"BAR\"") 1 - 返回给定列从中取出的表的 OID。列号从 0 开始。 + 返回给定列所取自的表的 OID。列号从 0 开始。 Oid PQftable(const PGresult *res, int column_number); @@ -2396,7 +2421,9 @@ Oid PQftable(const PGresult *res, 如果列号超出范围、指定的列不是对表列的简单引用,或者使用 3.0 之前的协议,则返回 InvalidOid。可以查询系统表 pg_class,确定所引用的具体表。 - 包含 libpq 头文件后,将定义类型 Oid 和常量 InvalidOid。它们都属于某种整数类型。 + + 包含 libpq 头文件后,将定义类型 Oid 和常量 InvalidOid。它们都属于某种整数类型。 + @@ -2405,7 +2432,7 @@ Oid PQftable(const PGresult *res, - 返回构成指定查询结果列的列(在其表中)的列号。查询结果列号从 0 开始,但是表列具有非零编号。 + 返回指定查询结果列所对应的表列在表中的列号。查询结果的列号从 0 开始,而表列的编号非零。 int PQftablecol(const PGresult *res, int column_number); @@ -2422,7 +2449,7 @@ int PQftablecol(const PGresult *res, - 返回指示给定列格式的格式编码。列号从 0 开始。 + 返回表示给定列格式的格式代码。列号从 0 开始。 int PQfformat(const PGresult *res, int column_number); @@ -2430,7 +2457,7 @@ int PQfformat(const PGresult *res, - 格式代码零指示文本数据表示,而格式代码一表示二进制表示(其他代码被保留用于未来的定义)。 + 格式代码零表示文本数据,格式代码一表示二进制数据。(其他代码保留供将来定义。) @@ -2457,7 +2484,7 @@ Oid PQftype(const PGresult *res, - 返回与给定列号相关联的列的修饰符类型。列号从 0 开始。 + 返回与给定列号相关联的列的类型修饰符。列号从 0 开始。 int PQfmod(const PGresult *res, int column_number); @@ -2465,7 +2492,7 @@ int PQfmod(const PGresult *res, - 修饰符值的解释是与类型相关的,它们通常指示精度或尺寸限制。值 -1 被用来指示没有信息可用。大部分的数据类型不适用修饰符,在那种情况中值总是 -1。 + 修饰符值的含义由数据类型决定,通常表示精度或大小限制。值 -1 表示没有可用信息。大多数数据类型不使用修饰符,此时该值始终为 -1。 @@ -2475,7 +2502,7 @@ int PQfmod(const PGresult *res, - 返回与给定列号相关的列的尺寸(以字节计)。列号从 0 开始。 + 返回给定列号对应列的大小,以字节计。列号从 0 开始。 int PQfsize(const PGresult *res, int column_number); @@ -2483,7 +2510,7 @@ int PQfsize(const PGresult *res, - PQfsize返回在一个数据库行中为这个列分配的空间,换句话说是服务器对该数据类型的内部表示的尺寸(因此,它对客户端并不是真地非常有用)。一个负值指示该数据类型是变长的。 + PQfsize 返回数据库行中为该列分配的空间,即服务器内部表示该数据类型所需的大小。(因此,它对客户端用处不大。)负值表示该数据类型是变长类型。 @@ -2500,8 +2527,7 @@ int PQbinaryTuples(const PGresult *res); - 这个函数已经被废弃(除了与COPY一起使用),因为一个单一PGresult可以在某些列中包含文本数据而且在另一些列中包含二进制数据。 - PQfformat要更好。只有结果的所有列是二进制(格式 1)时PQbinaryTuples才返回 1。 + 此函数已弃用(与 COPY 配合使用的情况除外),因为单个 PGresult 可能在部分列中包含文本数据,而在其他列中包含二进制数据。推荐使用 PQfformat。只有结果中的所有列都采用二进制格式(格式 1)时,PQbinaryTuples 才返回 1。 @@ -2510,7 +2536,8 @@ int PQbinaryTuples(const PGresult *res); PQgetvalue PQgetvalue - 返回以下结果中某一行的一个字段值:PGresult。行号和列号都从 0 开始。调用者不应直接释放结果。在将关联的PGresult句柄传给以下函数时,会释放该结果:PQclear。 + + 返回 PGresult 中某一行的单个字段值。行号和列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 PQclear 时,结果会被释放。 char *PQgetvalue(const PGresult *res, int row_number, @@ -2518,24 +2545,26 @@ char *PQgetvalue(const PGresult *res, - 对于文本格式的数据,PQgetvalue 返回字段值的字符串表示,以零字节结尾。对于二进制格式的数据,返回值采用该数据类型的 typsendtypreceive 函数所决定的二进制表示。(这种情况下,值后面实际上也有一个零字节,但通常没有用处,因为值本身很可能包含零字节。) + + 对于文本格式的数据,PQgetvalue 返回字段值的字符串表示,以零字节结尾。对于二进制格式的数据,返回值采用该数据类型的 typsendtypreceive 函数所决定的二进制表示。(这种情况下,值后面实际上也有一个零字节,但通常没有用处,因为值本身很可能包含零字节。) + - 如果该域值为空,则返回一个空串。关于区分空值和空字符串值请见PQgetisnull。 + 如果字段值为 null,则返回空字符串。关于如何区分 null 值与空字符串值,参见 PQgetisnull - PQgetvalue返回的指针指向作为PGresult结构体一部分的存储。我们不应该修改它指向的数据,并且如果要在超过PGresult结构体本身的生命期之外使用它,我们必须显式地把该数据拷贝到其他存储中。 + PQgetvalue 返回的指针指向属于 PGresult 结构体的存储空间。不应修改它所指向的数据;如果需要在 PGresult 结构体的生命周期结束后继续使用这些数据,就必须显式地将数据复制到其他存储空间。 - PQgetisnullPQgetisnullnull valuein libpq + PQgetisnullPQgetisnullnull 值libpq 中的 - 测试一个域是否为空值。行号和列号从 0 开始。 + 检查字段是否为 null 值。行号和列号从 0 开始。 int PQgetisnull(const PGresult *res, int row_number, @@ -2544,7 +2573,7 @@ int PQgetisnull(const PGresult *res, - 如果该域是空,这个函数返回 1。如果它包含一个非空值,则返回 0(注意PQgetvalue将为一个空域返回一个空串,不是一个空指针)。 + 如果字段为 null,此函数返回 1;如果包含非 null 值,则返回 0。(注意,对于 null 字段,PQgetvalue 返回空字符串,而非空指针。) @@ -2554,7 +2583,7 @@ int PQgetisnull(const PGresult *res, - 返回一个域值的真实长度,以字节计。行号和列号从 0 开始。 + 返回字段值的实际长度,以字节计。行号和列号从 0 开始。 int PQgetlength(const PGresult *res, int row_number, @@ -2563,9 +2592,7 @@ int PQgetlength(const PGresult *res, - 这是特定数据值的真实数据长度,也就是PQgetvalue指向的对象的尺寸。 - 对于文本数据格式,这和strlen()相同。对于二进制格式这是基本信息。 - 注意我们应该依赖于PQfsize来得到实际的数据长度。 + 这是该数据值的实际数据长度,即 PQgetvalue 所指对象的大小。对于文本格式的数据,它与 strlen() 的结果相同。对于二进制格式,这是必不可少的信息。注意,不应依赖 PQfsize 来获取实际数据长度。 @@ -2610,29 +2637,29 @@ Oid PQparamtype(const PGresult *res, int param_number); - 将所有的行打印到指定的输出流,以及有选择地将列名打印到指定的输出流。 + 将所有行输出到指定的输出流,并可选择输出列名。 void PQprint(FILE *fout, /* 输出流 */ const PGresult *res, const PQprintOpt *po); typedef struct { - pqbool header; /* 打印输出域标题和行计数 */ - pqbool align; /* 填充对齐域 */ - pqbool standard; /* 旧的格式 */ + pqbool header; /* 打印输出字段标题和行数 */ + pqbool align; /* 填充并对齐字段 */ + pqbool standard; /* 旧的简陋格式 */ pqbool html3; /* 输出 HTML 表格 */ - pqbool expanded; /* 扩展表格 */ - pqbool pager; /* 如果必要为输出使用页 */ - char *fieldSep; /* 域分隔符 */ + pqbool expanded; /* 展开表格 */ + pqbool pager; /* 需要时使用分页器输出 */ + char *fieldSep; /* 字段分隔符 */ char *tableOpt; /* 用于 HTML 表格元素的属性 */ char *caption; /* HTML 表格标题 */ - char **fieldName; /* 替换域名称的空终止数组 */ + char **fieldName; /* 以空指针结尾的替换字段名数组 */ } PQprintOpt; - 这个函数以前被psql用来打印查询结果,但是现在不是这样了。注意它假定所有的数据都是文本格式。 + psql 以前用此函数打印查询结果,现在已不再使用。注意,此函数假定所有数据都是文本格式。 @@ -2675,7 +2702,9 @@ char *PQcmdTuples(PGresult *res); - 此函数返回一个字符串,其中包含产生该 PGresultSQL 语句所影响的行数。此函数只能在执行 SELECTCREATE TABLE ASINSERTUPDATEDELETEMOVEFETCHCOPY 语句之后使用,也可以在对包含 INSERTUPDATEDELETE 语句的预备查询执行 EXECUTE 之后使用。如果产生 PGresult 的是其他命令,PQcmdTuples 将返回空字符串。调用者不应直接释放返回值;将关联的 PGresult 句柄传给 PQclear 时,它会被释放。 + + 此函数返回一个字符串,其中包含产生该 PGresultSQL 语句所影响的行数。此函数只能在执行 SELECTCREATE TABLE ASINSERTUPDATEDELETEMOVEFETCHCOPY 语句之后使用,也可以在对包含 INSERTUPDATEDELETE 语句的预备查询执行 EXECUTE 之后使用。如果产生 PGresult 的是其他命令,PQcmdTuples 将返回空字符串。调用者不应直接释放返回值;当关联的 PGresult 句柄被传给 PQclear 时,返回值会被释放。 + @@ -2685,7 +2714,7 @@ char *PQcmdTuples(PGresult *res); - 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDin libpq。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid。 + 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDlibpq 中的。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid Oid PQoidValue(const PGresult *res); @@ -2697,7 +2726,9 @@ Oid PQoidValue(const PGresult *res); PQoidStatus PQoidStatus - 此函数已弃用,推荐使用PQoidValue,且此函数不是线程安全的。它返回包含插入行 OID 的字符串,而PQoidValue返回 OID 值。 + + 此函数不是线程安全的,现已弃用,推荐改用 PQoidValue。它返回包含插入行 OID 的字符串,而 PQoidValue 返回 OID 值。 + char *PQoidStatus(const PGresult *res); @@ -2713,7 +2744,7 @@ char *PQoidStatus(const PGresult *res); 转义字符串 - in libpq + libpq 中的 @@ -2729,17 +2760,13 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); 为了让一个字符串可用于 SQL 命令,PQescapeLiteral会对它进行转义。 - 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜线)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 + 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜杠)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 PQescapeLiteral执行这种操作。 - PQescapeLiteral返回一个str参数的已被转义版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,PQescapeLiteral会停止在零,该行为更像strncpy)。 - 返回字符串中的所有特殊字符都会被替换,这样它们就能被PostgreSQL字符串字面量解析器正确处理。 - 结果中也会附加一个终止零字节,并包含包围PostgreSQL字符串字面量所需的单引号。 - + PQescapeLiteral 返回 str 参数的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节,PQescapeLiteral 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便 PostgreSQL 字符串字面量解析器正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号包含在结果字符串中。 + 发生错误时,PQescapeLiteral返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -2753,7 +2780,7 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); - 注意,当一个数据值被作为PQexecParams或其兄弟例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 + 注意,当一个数据值被作为PQexecParams或相关例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 @@ -2768,14 +2795,13 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - PQescapeIdentifier 对字符串进行转义,使其可用作 SQL 标识符,例如表名、列名或函数名。当用户提供的标识符可能包含未经转义就不会被 SQL 解析器视为标识符一部分的特殊字符,或包含需要保留大小写的大写字符时,此函数很有用。 + + PQescapeIdentifier 对字符串进行转义,使其可用作 SQL 标识符,例如表名、列名或函数名。当用户提供的标识符可能包含未经转义就不会被 SQL 解析器视为标识符一部分的特殊字符,或包含需要保留大小写的大写字符时,此函数很有用。 + - PQescapeIdentifier返回一个str参数的已被转义为 SQL 标识符的版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存必须用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,PQescapeIdentifier会停止在零,该行为更像strncpy)。 - 返回串中的所有特殊字符都被替换掉,这样它们能被作为一个 SQL 标识符正确地处理。还会加上一个终止零字节。返回串也将被双引号包围。 - + PQescapeIdentifier 返回 str 参数作为 SQL 标识符的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,必须使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节,PQescapeIdentifier 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便正确地作为 SQL 标识符处理。还会添加一个末尾零字节,并用双引号包围返回的字符串。 + 发生错误时,PQescapeIdentifier返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -2784,7 +2810,7 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - 与字符串一样,要阻止 SQL 注入攻击,当从一个不可信的来源接收到 SQL 标识符时,它们必须被转义。 + 与字符串字面量一样,为防止 SQL 注入攻击,从不可信来源接收到的 SQL 标识符必须经过转义。 @@ -2803,18 +2829,12 @@ size_t PQescapeStringConn(PGconn *conn, - PQescapeStringConn转义字符串,它很像PQescapeLiteral。 - 与PQescapeLiteral不一样的是,调用者负责提供一个合适尺寸的缓冲区。 - 此外,PQescapeStringConn不产生必须包围PostgreSQL字符串的单引号。 - 它们应该在结果要插入的 SQL 命令中提供。参数from指向要被转义的串的第一个字符,并且length参数给出了这个串中的字节数。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,PQescapeStringConn会停止在零,该行为更像strncpy)。 - to应当指向一个缓冲区,它至少能容纳length值的两倍再加一个字节,否则该行为是未被定义的。 - 如果tofrom串重叠,行为也是未被定义的。 - + PQescapeStringConn 对字符串字面量进行转义,与 PQescapeLiteral 类似。与 PQescapeLiteral 不同,调用者需要提供大小合适的缓冲区。此外,PQescapeStringConn 不会生成包围 PostgreSQL 字符串字面量所需的单引号;应在包含转义结果的 SQL 命令中提供这些引号。from 参数指向待转义字符串的首字符,length 参数给出该字符串的字节数。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节,PQescapeStringConn 会在该字节处停止;这一行为类似于 strncpy。)to 必须指向一个缓冲区,其容量至少为 length 的两倍加一个字节,否则行为未定义。如果 tofrom 字符串重叠,行为同样未定义。 + - 如果error参数不是NULL,那么成功时*error被设置为零,错误时设置为非零。当前唯一可能的错误情况涉及源串中非法的多字节编码。错误时仍然会产生输出串,但是可以预期服务器将认为它是畸形的并且拒绝它。在发生错误时,一个合适的消息被存储在conn对象中,不管error是不是NULL。 - + 如果 error 参数不是 NULL,则成功时将 *error 设为零,出错时设为非零。目前唯一可能的错误是源字符串中存在无效的多字节编码。出错时仍会生成输出字符串,但预计服务器会因其格式错误而拒绝它。发生错误时,无论 error 是否为 NULL,都会在 conn 对象中保存相应消息。 + PQescapeStringConn返回写到to的字节数,不包括终止的零字节。 @@ -2827,15 +2847,19 @@ size_t PQescapeStringConn(PGconn *conn, - PQescapeString是以下函数的旧版本,现已弃用:PQescapeStringConn。 + PQescapeStringPQescapeStringConn 的旧版本,现已弃用。 size_t PQescapeString (char *to, const char *from, size_t length); - + - PQescapeStringConn 唯一的区别是,PQescapeString 不接受 PGconnerror 参数。因此,它无法根据连接属性(例如字符编码)调整行为,可能给出错误的结果。此外,它也无法报告错误情况。 + + 与 PQescapeStringConn 唯一的区别是,PQescapeString 不接受 PGconnerror 参数。因此,它无法根据连接属性(例如字符编码)调整行为,可能给出错误的结果。此外,它也无法报告错误情况。 + - PQescapeString 可以在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。在其他情形下,它存在安全隐患,应改用 PQescapeStringConn + + PQescapeString 可以在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。在其他情形下,它存在安全隐患,应改用 PQescapeStringConn。 + @@ -2843,7 +2867,9 @@ size_t PQescapeString (char *to, const char *from, size_t length); PQescapeByteaConn PQescapeByteaConn - 对二进制数据进行转义,使其能够在 SQL 命令中用作以下类型的值:bytea。与PQescapeStringConn一样,这仅用于将数据直接插入 SQL 命令字符串的情况。 + + 对二进制数据进行转义,使其能够在 SQL 命令中用作 bytea 类型的值。与 PQescapeStringConn 一样,这仅用于将数据直接插入 SQL 命令字符串的情况。 + unsigned char *PQescapeByteaConn(PGconn *conn, const unsigned char *from, size_t from_length, @@ -2857,10 +2883,12 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - from参数指向要被转义的串的第一个字节,并且from_length参数给出这个二进制串中的字节数(一个终止的零字节是不需要的也是不被计算的)。to_length参数指向一个将保持生成的已转义串长度的变量。这个结果串长度包括结果的终止零字节。 + from 参数指向待转义字符串的首字节,from_length 参数给出该二进制字符串的字节数。(末尾零字节既不需要,也不计入长度。)to_length 参数指向用于保存转义后字符串长度的变量。该结果字符串长度包含结果末尾的零字节。 - PQescapeByteaConn 返回 from 参数所指二进制字符串的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。返回字符串中的所有特殊字符都已替换,以便 PostgreSQL 字符串字面量解析器和 bytea 输入函数正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号不包含在结果字符串中。 + + PQescapeByteaConn 返回 from 参数所指二进制字符串的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。返回字符串中的所有特殊字符都已替换,以便 PostgreSQL 字符串字面量解析器和 bytea 输入函数正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号不包含在结果字符串中。 + 在发生错误时,将返回一个空指针,并且一个合适的错误消息被存储在conn对象中。当前,唯一可能的错误是没有足够的内存用于结果串。 @@ -2873,7 +2901,7 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - PQescapeBytea是以下函数的旧版本,现已弃用:PQescapeByteaConn。 + PQescapeByteaPQescapeByteaConn 的旧版本,现已弃用。 unsigned char *PQescapeBytea(const unsigned char *from, size_t from_length, @@ -2882,9 +2910,7 @@ unsigned char *PQescapeBytea(const unsigned char *from, - 与PQescapeByteaConn的唯一区别是PQescapeBytea不用一个PGconn参数。 - 正因为这样,PQescapeBytea只能在一次只使用一个PostgreSQL连接的客户端程序中安全地使用(在这种情况下它可以在内部找出它需要知道的东西)。 - 如果在有多个数据库连接的程序中使用,它可能给出错误的结果(在那种情况下使用PQescapeByteaConn)。 + 与 PQescapeByteaConn 唯一的区别是,PQescapeBytea 不接受 PGconn 参数。因此,PQescapeBytea 只能在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。如果在使用多个数据库连接的程序中使用,它可能给出错误的结果(此时应使用 PQescapeByteaConn)。 @@ -2950,26 +2976,26 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - PQexec总是收集命令的整个结果,把它缓存在一个单一的PGresult中。虽然这简化了应用的错误处理逻辑,它对于包含很多行的结果并不现实。 - + PQexec 总是收集命令的完整结果,并将其缓存在单个 PGresult 中。这简化了应用程序的错误处理逻辑,但对于包含大量行的结果,可能不切实际。 + - 如果应用程序不希望受到这些限制,可以改用构成PQexec的底层函数:PQsendQueryPQgetResult。此外,还有PQsendQueryParams, - PQsendPrepare, - PQsendQueryPrepared, - PQsendDescribePrepared,以及PQsendDescribePortal,它们可以与PQgetResult配合使用,分别实现以下函数的功能:PQexecParams, - PQprepare, - PQexecPrepared, - PQdescribePrepared,以及PQdescribePortal + + 如果应用程序不希望受到这些限制,可以改用构成 PQexec 的底层函数:PQsendQueryPQgetResult。此外,PQsendQueryParamsPQsendPreparePQsendQueryPreparedPQsendDescribePreparedPQsendDescribePortal 可以与 PQgetResult 配合使用,分别实现 PQexecParamsPQpreparePQexecPreparedPQdescribePreparedPQdescribePortal 的功能。 + PQsendQuery PQsendQuery - 向服务器提交命令,不等待结果。命令发送成功时返回 1,否则返回 0(此时可以使用PQerrorMessage取得更多失败信息)。 + + 向服务器提交命令,不等待结果。命令发送成功时返回 1,否则返回 0(此时可使用 PQerrorMessage 获取更多失败信息)。 + int PQsendQuery(PGconn *conn, const char *command); -成功调用PQsendQuery之后,应调用PQgetResult一次或多次来取得结果。PQsendQuery在同一连接上不能再次调用,直到PQgetResult返回空指针,表明命令已经完成。 + +成功调用 PQsendQuery 后,应调用 PQgetResult 一次或多次来获取结果。在 PQgetResult 返回空指针、表明命令已完成之前,不得在同一连接上再次调用 PQsendQuery。 + @@ -2977,7 +3003,9 @@ int PQsendQuery(PGconn *conn, const char *command); PQsendQueryParams PQsendQueryParams - 向服务器提交命令及独立指定的参数,不等待结果。 + + 向服务器提交命令及独立指定的参数,不等待结果。 + int PQsendQueryParams(PGconn *conn, const char *command, int nParams, @@ -2986,7 +3014,9 @@ int PQsendQueryParams(PGconn *conn, const int *paramLengths, const int *paramFormats, int resultFormat); -该函数等价于PQsendQuery,但查询参数可以与查询字符串分开指定。函数参数的处理方式与PQexecParams相同。与PQexecParams一样,它不能用于协议 2.0 的连接,并且查询字符串中只允许包含一条命令。 + +该函数等价于 PQsendQuery,但查询参数可以与查询字符串分开指定。函数参数的处理方式与 PQexecParams 相同。与 PQexecParams 一样,它不能用于协议 2.0 的连接,并且查询字符串中只允许包含一条命令。 + @@ -2994,13 +3024,17 @@ int PQsendQueryParams(PGconn *conn, PQsendPrepare PQsendPrepare - 发送按给定参数创建预备语句的请求,不等待完成。 + + 发送按给定参数创建预备语句的请求,不等待完成。 + int PQsendPrepare(PGconn *conn, const char *stmtName, const char *query, int nParams, const Oid *paramTypes); -这是PQprepare的异步版本:请求发送成功时返回 1,否则返回 0。调用成功后,再调用PQgetResult,确定服务器是否成功创建了预备语句。函数参数的处理方式与PQprepare相同。与PQprepare一样,它不能用于协议 2.0 的连接。 + +这是 PQprepare 的异步版本:请求发送成功时返回 1,否则返回 0。调用成功后,再调用 PQgetResult,确定服务器是否成功创建了预备语句。函数参数的处理方式与 PQprepare 相同。与 PQprepare 一样,它不能用于协议 2.0 的连接。 + @@ -3008,7 +3042,9 @@ int PQsendPrepare(PGconn *conn, PQsendQueryPrepared PQsendQueryPrepared - 发送使用给定参数执行预备语句的请求,不等待结果。 + + 发送使用给定参数执行预备语句的请求,不等待结果。 + int PQsendQueryPrepared(PGconn *conn, const char *stmtName, int nParams, @@ -3016,7 +3052,9 @@ int PQsendQueryPrepared(PGconn *conn, const int *paramLengths, const int *paramFormats, int resultFormat); -该函数类似于PQsendQueryParams,但通过指定先前已准备好的语句的名称来确定要执行的命令,而不是提供查询字符串。函数参数的处理方式与PQexecPrepared相同。与PQexecPrepared一样,它不能用于协议 2.0 的连接。 + +该函数类似于 PQsendQueryParams,但通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。函数参数的处理方式与 PQexecPrepared 相同。与 PQexecPrepared 一样,它不能用于协议 2.0 的连接。 + @@ -3053,7 +3091,9 @@ PGresult *PQgetResult(PGconn *conn); - 必须反复调用 PQgetResult,直到它返回空指针,表明命令已经完成。(如果当前没有正在执行的命令,调用 PQgetResult 会立即返回空指针。)对于 PQgetResult 返回的每个非空结果,都应使用前文介绍的 PGresult 访问函数处理。使用完毕后,不要忘记调用 PQclear 释放每个结果对象。注意,只有存在正在执行的命令,且所需响应数据尚未被 PQconsumeInput 读取时,PQgetResult 才会阻塞。 + + 必须反复调用 PQgetResult,直到它返回空指针,表明命令已经完成。(如果当前没有正在执行的命令,调用 PQgetResult 会立即返回空指针。)对于 PQgetResult 返回的非空指针,应使用前文介绍的 PGresult 访问函数处理相应结果。使用完毕后,不要忘记调用 PQclear 释放每个结果对象。注意,只有存在正在执行的命令,且所需响应数据尚未被 PQconsumeInput 读取时,PQgetResult 才会阻塞。 + @@ -3064,37 +3104,36 @@ PGresult *PQgetResult(PGconn *conn); - + - 使用PQsendQueryPQgetResult解决了PQexec的一个问题:如果一个命令字符串包含多个SQL命令,这些命令的结果可以被个别地获得(顺便说一句:这样就允许一种简单的重叠处理形式, 客户端可以处理一个命令的结果,而同时服务器可以继续处理同一命令字符串中后面的查询)。 - + 使用 PQsendQueryPQgetResult 可以解决 PQexec 的一个问题:如果命令字符串包含多个 SQL 命令,就能分别获取这些命令的结果。(这也支持一种简单的重叠处理方式:客户端可以处理某条命令的结果,同时服务器继续处理同一命令字符串中后面的查询。) + - 可以被PQsendQueryPQgetResult获得的另一种常常想要的特性是一次从大型结果中检索一行。这会在中讨论。 - + 使用 PQsendQueryPQgetResult 还可以实现另一项常见需求:从大型查询结果中一次读取一行。详见 。 + - 仅仅调用PQgetResult仍会使客户端阻塞,直到服务器完成下一条SQL命令。可以通过正确使用另外两个函数来避免这种情况: + + 仅仅调用 PQgetResult 仍会使客户端阻塞,直到服务器完成下一条 SQL 命令。可以通过正确使用另外两个函数来避免这种情况: + PQconsumeInput PQconsumeInput - 如果有来自服务器的输入可用,则使用之。 + 如果服务器有可读取的输入,则读取这些输入。 int PQconsumeInput(PGconn *conn); - PQconsumeInput通常返回 1 表明没有错误,而返回 0 表明有某种麻烦发生(此时可以用PQerrorMessage)。 - 注意该结果并不表明是否真正收集了任何输入数据。在调用PQconsumeInput之后,应用可以检查PQisBusy和/或PQnotifies来看看它们的状态是否改变。 + PQconsumeInput 通常返回 1,表示没有错误;发生问题时则返回 0(此时可查看 PQerrorMessage)。注意,返回值并不说明是否实际读取了输入数据。调用 PQconsumeInput 后,应用程序可以检查 PQisBusy 和/或 PQnotifies,以确定其状态是否发生变化。 - 即使应用还不准备处理一个结果或通知,PQconsumeInput也可以被调用。 - 这个函数将读取可用的数据并且把它保存在一个缓冲区中,从而导致一个select()的读准备好指示消失。 - 因此应用可以使用PQconsumeInput立即清除select()条件,并且在空闲时再检查结果。 + 即使应用程序尚未准备好处理结果或通知,也可以调用 PQconsumeInput。此函数会读取可用数据并将其保存在缓冲区中,从而清除 select() 的可读就绪指示。因此,应用程序可以用 PQconsumeInput 立即清除 select() 的就绪条件,随后在合适的时候检查结果。 @@ -3114,22 +3153,20 @@ int PQisBusy(PGconn *conn); - + - 一个使用这些函数的典型应用将有一个主循环,在主循环中会使用select()poll()等待所有它必须响应的情况。 - 其中之一将是来自服务器的输入可用,对select()来说意味着PQsocket标识的文件描述符上有可读的数据。 - 当主循环检测到输入准备好时,它将调用PQconsumeInput读取输入。 - 然后它可以调用PQisBusy,如果PQisBusy返回假(0)则接着调用PQgetResult。 - 它还可以调用PQnotifies检测NOTIFY消息(见)。 - + 使用这些函数的典型应用程序会在主循环中通过 select()poll() 等待需要响应的各种条件。其中一个条件是服务器有可读取的输入;对于 select(),这意味着 PQsocket 标识的文件描述符上有可读数据。主循环检测到输入就绪时,应调用 PQconsumeInput 读取输入,然后调用 PQisBusy。如果 PQisBusy 返回假(0),就可以接着调用 PQgetResult。还可以调用 PQnotifies 检测 NOTIFY 消息(见 )。 + 一个使用PQsendQuery/PQgetResult的客户端也可以尝试取消一个正在被服务器处理的命令,见。 但是,不管PQcancel的返回值是什么,应用都必须继续使用PQgetResult进行正常的结果读取序列。一次成功的取消只会导致命令比不取消时更快终止。 - 使用上述函数可以避免在等待数据库服务器输入时阻塞。不过,应用程序仍可能在等待向服务器发送输出时阻塞。这种情况较少见,但发送很长的 SQL 命令或数据值时可能发生。(如果应用程序通过COPY IN发送数据,发生的可能性则大得多。)为了防止这种情况,实现完全非阻塞的数据库操作,可以使用以下附加函数。 + + 使用上述函数可以避免在等待数据库服务器输入时阻塞。不过,应用程序仍可能在等待向服务器发送输出时阻塞。这种情况较少见,但发送很长的 SQL 命令或数据值时可能发生。(如果应用程序通过 COPY IN 发送数据,发生的可能性则大得多。)为了防止这种情况,实现完全非阻塞的数据库操作,可以使用以下附加函数。 + PQsetnonblocking PQsetnonblocking @@ -3176,9 +3213,7 @@ int PQisnonblocking(const PGconn *conn); - 尝试将任何排队的输出数据刷新到服务器。如果成功(或发送队列为空),则返回0; - 如果由于某种原因失败,则返回-1;如果尚未能够发送发送队列中的所有数据(只有在连接为非阻塞时才会发生此情况), - 则返回1。 + 尝试将发送队列中的输出数据发送到服务器。成功(或发送队列为空)时返回 0;因某种原因失败时返回 -1;如果尚未能发送队列中的全部数据,则返回 1(这种情况只可能发生在非阻塞连接上)。 int PQflush(PGconn *conn); @@ -3186,15 +3221,11 @@ int PQflush(PGconn *conn); - + - 在一个非阻塞连接上发送任何命令或者数据之后,要调用PQflush。 - 如果它返回 1,就要等待套接字变成读准备好或写准备好。如果它变为写准备好,应再次调用PQflush。 - 如果它变为读准备好,则应先调用PQconsumeInput,然后再调用PQflush。 - 一直重复直到PQflush返回 0(有必要检查读准备好并且用PQconsumeInput耗尽输入,因为服务器可能阻塞给我们发送数据的尝试,例如 NOTICE 消息,并且在我们读它的数据之前它都不会读我们的数据)。 - 一旦PQflush返回 0,应等待套接字变成读准备好并且接着按照上文所述读取响应。 - + 在非阻塞连接上发送命令或数据后,应调用 PQflush。如果返回 1,就等待套接字变为可读或可写。套接字可写时,再次调用 PQflush;可读时,先调用 PQconsumeInput,再调用 PQflush。重复上述步骤,直到 PQflush 返回 0。(必须检查套接字是否可读,并用 PQconsumeInput 读完输入,因为服务器可能在尝试向客户端发送数据时阻塞,例如发送 NOTICE 消息;在客户端读取这些数据之前,服务器不会读取客户端发送的数据。)当 PQflush 返回 0 后,等待套接字变为可读,再按前述方法读取响应。 + @@ -3322,7 +3353,7 @@ int PQrequestCancel(PGconn *conn); 快速路径接口 - fast path + 快速路径 @@ -3358,24 +3389,22 @@ typedef struct - fnid参数是要被执行的函数的 OID。argsnargs定义了要传递给函数的参数;它们必须匹配已声明的函数参数列表。当一个参数结构体的isint域为真时,u.integer值被以指定长度(必须是 2 或 4 字节)整数的形式发送给服务器;这时候会发生恰当的字节交换。当isint为假时,*u.ptr中指定数量的字节将不做任何处理被发送出去;这些数据必须是服务器 预期的用于该函数参数数据类型的二进制传输的格式(由于历史原因u.ptr被声明为类型int *,其实把它考虑成void *会更好)。result_buf是放置该函数返回值的缓冲区。调用者必须已经分配了足够的空间来存储返回值(这里没有检查!)。实际的结果长度将被放在result_len指向的整数中返回。如果预期结果是 2 或 4 字节整数,把result_is_int设为 1;否则设为 0。把result_is_int设为 1 导致libpq在必要时对值进行交换字节,这样它就作为对客户端机器正确的int值被传输,注意对任一种允许的结果大小都会传递一个 4 字节整数到*result_buf。当result_is_int是 0 时,服务器发送的二进制格式字节将不做修改直接返回(在这种情况下,把result_buf考虑为类型void *更好)。 - + fnid 参数是要执行函数的 OID。argsnargs 指定传给函数的参数,必须与函数声明中的参数列表匹配。参数结构体的 isint 字段为真时,u.integer 值会以指定长度的整数发送到服务器,该长度必须是 2 或 4 字节,并会进行适当的字节序转换。isint 为假时,位于 *u.ptr 的指定数量字节会原样发送;数据必须符合服务器对该函数参数数据类型的二进制传输格式要求。(将 u.ptr 声明为 int * 是历史原因;将其视为 void * 更合适。)result_buf 指向用于存放函数返回值的缓冲区。调用者必须事先分配足够空间来保存返回值,这里不会检查!实际结果长度以字节为单位,返回到 result_len 指向的整数中。如果预期结果是 2 或 4 字节整数,将 result_is_int 设为 1,否则设为 0。将 result_is_int 设为 1 后,libpq 会按需转换字节序,使结果成为适合客户端机器的 int 值;注意,无论是哪种允许的结果大小,传入 *result_buf 的都是 4 字节整数。result_is_int 为 0 时,服务器发送的二进制格式字节串会原样返回。(此时,将 result_buf 视为 void * 更合适。) + - PQfn总是返回一个有效的PGresult指针,成功时状态为PGRES_COMMAND_OK,遇到问题时为PGRES_FATAL_ERROR。 - 在使用结果之前应该检查结果状态。 - 当结果不再使用后,调用者有义务使用PQclear释放PGresult。 - + PQfn 总是返回有效的 PGresult 指针:成功时状态为 PGRES_COMMAND_OK,遇到问题时为 PGRES_FATAL_ERROR。使用结果前应检查其状态。不再需要结果时,调用者负责使用 PQclear 释放 PGresult。 + - 要传递NULL参数到函数,将参数结构体的len字段设置为-1isintu 字段就不相关了。(但这仅适用于使用协议 3.0 及更高版本的连接。) + 要向函数传入 NULL 参数,将该参数结构体的 len 字段设为 -1;此时,isintu 字段便不再相关。(但这仅适用于使用协议 3.0 及更高版本的连接。) + 如果函数返回 NULL,则将 *result_len 设为 -1,而不修改 *result_buf。(这仅适用于使用协议 3.0 及更高版本的连接;在协议 2.0 中,既不修改 *result_len,也不修改 *result_buf。) - 注意在使用此接口时,不能够处理集-值结果。 - 此外,函数必须是一个普通函数,而不是聚合、窗口函数或过程。 - + 注意,使用此接口时无法处理集合值结果。此外,函数必须是普通函数,不能是聚合函数、窗口函数或过程。 + @@ -3384,7 +3413,7 @@ typedef struct NOTIFY - in libpq + 在 libpq 中 @@ -3393,32 +3422,36 @@ typedef struct libpq应用把LISTENUNLISTENNOTIFY命令作为普通 SQL 命令提交。 - 随后通过调用PQnotifies.PQnotifies来检测NOTIFY消息的到达。 + 随后通过调用PQnotifiesPQnotifies来检测NOTIFY消息的到达。 - 函数PQnotifies从已收到但尚未处理的服务器通知消息列表中返回下一条通知。如果没有待处理的通知,则返回空指针。一旦通知由PQnotifies返回,就被视为已处理,并从通知列表中移除。 + + 函数 PQnotifies 从已收到但尚未处理的服务器通知消息列表中返回下一条通知。没有待处理通知时返回空指针。一旦 PQnotifies 返回一条通知,该通知就被视为已处理,并从通知列表中移除。 + PGnotify *PQnotifies(PGconn *conn); typedef struct pgNotify { - char *relname; /* notification channel name */ - int be_pid; /* process ID of notifying server process */ - char *extra; /* notification payload string */ + char *relname; /* 通知通道名称 */ + int be_pid; /* 发送通知的服务器进程 ID */ + char *extra; /* 通知载荷字符串 */ } PGnotify; -处理完一个PGnotify对象(由PQnotifies返回)后,一定要用PQfreemem释放它。只需释放PGnotify指针;relnameextra字段并非独立分配。(这些字段名称是历史遗留的;尤其是,通道名称与关系名称不必有任何关联。) + +处理完 PQnotifies 返回的 PGnotify 对象后,务必使用 PQfreemem 释放它。只需释放 PGnotify 指针;relnameextra 字段并非独立分配。(这些字段名称是历史遗留的;尤其是,通道名称与关系名称不必有任何关联。) + 给出了一个示例程序展示异步通知的使用。 - PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数吸收的消息。 + PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数读取的消息。 在较早版本的libpq中,及时收到NOTIFY消息的唯一方法是不断提交命令,哪怕是空命令,然后在每次PQexec后检查PQnotifies。 - 虽然这种方法仍然有效,但由于效率过低,现已废弃。 + 虽然这种方法仍然有效,但由于浪费处理能力,现已弃用。 - 当你没有可用的命令提交时,一种更好的检查NOTIFY消息的方法是调用PQconsumeInput,然后检查PQnotifies。 + 当没有需要执行的实际命令时,一种更好的检查NOTIFY消息的方法是调用PQconsumeInput,然后检查PQnotifies。 你可以使用select()等待服务器数据到达,这样在无事可做时就不会浪费CPU资源(参见PQsocket以获得可传给select()的文件描述符)。 注意不管是用PQsendQuery/PQgetResult提交命令还是简单地使用PQexec,这种方法都能正常工作。 不过,你应该记住在每次PQgetResultPQexec之后检查PQnotifies,看看在命令的处理过程中是否有通知到达。 @@ -3431,20 +3464,16 @@ typedef struct pgNotify COPY - with libpq + 使用 libpq - PostgreSQL中的COPY命令有用于libpq的对网络连接读出或者写入的选项。这一节描述的函数允许应用通过提供或者消耗已拷贝的数据来充分利用这个功能。 - + PostgreSQLCOPY 命令提供了选项,可以通过 libpq 使用的网络连接读取或写入数据。本节介绍的函数允许应用程序通过提供或接收复制数据来使用这一能力。 + - 整个处理是应用首先通过PQexec或者一个等效的函数发出 SQL COPY命令。 - 对这个命令的响应(如果命令无误)将是一个状态代码是PGRES_COPY_OUT或 者PGRES_COPY_IN(取决于指定的拷贝方向)的PGresult对象。 - 应用然后就应该使用这一节的函数接收或者传送数据行。在数据传输结束之后,另外一个PGresult对象会被返回以表明传输的成功或者失败。 - 它的状态将是:PGRES_COMMAND_OK表示成功,PGRES_FATAL_ERROR表示发生了一些问题。 - 此时我们可以通过PQexec发出进一步的 SQL 命令(在COPY操作的处理过程中,不能用同一个连接执行其它 SQL 命令)。 - + 整体流程如下:应用程序先通过 PQexec 或等效函数发出 SQL COPY 命令。如果命令没有错误,响应就是一个 PGresult 对象,其状态码为 PGRES_COPY_OUTPGRES_COPY_IN,取决于指定的复制方向。应用程序随后应使用本节函数接收或发送数据行。数据传输完成后,会返回另一个 PGresult 对象,表示传输成功或失败:成功时状态为 PGRES_COMMAND_OK,出现问题时为 PGRES_FATAL_ERROR。此时可以通过 PQexec 继续发出 SQL 命令。(COPY 操作进行期间,不能在同一连接上执行其他 SQL 命令。) + 如果一个COPY命令是通过PQexec在一个可能包含额外命令的字符串中发出的,那么应用在完成COPY序列之后必须继续用PQgetResult取得结果。 @@ -3452,12 +3481,14 @@ typedef struct pgNotify - 这一节的函数应该只在从PQexecPQgetResult获得了PGRES_COPY_OUTPGRES_COPY_IN结果状态后执行。 - + 只有从 PQexecPQgetResult 获得 PGRES_COPY_OUTPGRES_COPY_IN 结果状态后,才应调用本节函数。 + - 一个PGresult对象若带有上述某个状态值,还会携带关于即将开始的COPY操作的附加数据。这些数据可以通过下列函数取得,这些函数也用于查询结果: + + 带有上述某个状态值的 PGresult 对象,还会携带关于即将开始的 COPY 操作的附加数据。这些数据可以通过下列函数获取,这些函数也用于查询结果: + - PQnfieldsPQnfieldswith COPY + PQnfieldsPQnfields用于 COPY @@ -3467,7 +3498,7 @@ typedef struct pgNotify - PQbinaryTuplesPQbinaryTupleswith COPY + PQbinaryTuplesPQbinaryTuples用于 COPY @@ -3478,7 +3509,7 @@ typedef struct pgNotify - PQfformatPQfformatwith COPY + PQfformatPQfformat用于 COPY @@ -3490,7 +3521,7 @@ typedef struct pgNotify - + 这些附加数据值仅在使用协议 3.0 时可用。使用协议 2.0 时,这些函数都返回 0。 @@ -3500,8 +3531,8 @@ typedef struct pgNotify 用于发送<command>COPY</command>数据的函数 - 这些函数用于在COPY FROM STDIN期间发送数据。如果在连接不是COPY_IN状态,调用它们会失败。 - + 这些函数用于在 COPY FROM STDIN 期间发送数据。如果连接不处于 COPY_IN 状态,调用它们会失败。 + @@ -3518,12 +3549,11 @@ int PQputCopyData(PGconn *conn, - 传输指定buffer中长度为nbytesCOPY数据到服务器。 - 如果数据被放在队列中,结果是 1;如果因为缓冲区满而无法被放在队列中(只可能发生在连接是非阻塞模式时),那么结果是零;如果发生错误,结果为 -1(如果返回值为 -1,那么使用PQerrorMessage检索细节。如果值是零,那么等待写准备好然后重试)。 + 将指定 buffer 中长度为 nbytesCOPY 数据传输到服务器。数据成功加入队列时返回 1;因缓冲区已满而无法加入队列时返回零(仅可能发生在非阻塞模式下);发生错误时返回 -1。(返回 -1 时,可用 PQerrorMessage 获取详细信息。返回零时,应等待可写就绪后重试。) - 应用可以把COPY数据流划分成任意方便的大小放到缓冲区中。在发送时,缓冲区载荷的边界没有什么语意。数据流的内容必须匹配COPY命令预期的数据格式;详见。 + 应用程序可以将 COPY 数据流分成任意方便大小的数据块,逐块装入缓冲区。发送时,这些数据块的边界没有语义含义。数据流内容必须符合 COPY 命令预期的数据格式;详见 @@ -3540,13 +3570,16 @@ int PQputCopyEnd(PGconn *conn, - 如果 errormsgNULL,则成功结束 COPY_IN 操作。如果 errormsg 不为 NULL,则强制 COPY 失败,并将 errormsg 指向的字符串用作错误消息。(但不应假定服务器一定会返回这条完全相同的错误消息,因为服务器可能已经因自身原因使 COPY 失败。还要注意,在使用 3.0 之前协议的连接上,强制失败选项不起作用。) + + 如果 errormsgNULL,则成功结束 COPY_IN 操作。如果 errormsg 不为 NULL,则强制 COPY 失败,并将 errormsg 指向的字符串用作错误消息。(但不应假定服务器一定会返回这条完全相同的错误消息,因为服务器可能已经因自身原因使 COPY 失败。还要注意,在使用 3.0 之前协议的连接上,强制失败选项不起作用。) + - 如果终止消息被发送,则结果为 1;在非阻塞模式中,结果为 1 也可能只表示终止消息被成功地放在了发送队列中 (在非阻塞模式中,要确认数据确实被发送出去,你应该接着等待写准备好并且调用PQflush,重复这些直到返回零)。 零表示该函数由于缓冲区满而无法将该终止消息放在队列中,这只会发生在非阻塞模式中(在这种情况下,等待写准备好并且再次尝试PQputCopyEnd调用)。 如果发生系统错误,则返回 -1,可以使用PQerrorMessage检索详情。 + + 终止消息已发送时返回 1;在非阻塞模式下,返回 1 也可能仅表示该消息已成功加入发送队列。(在非阻塞模式下,要确认数据已经发送,应接着等待可写就绪并调用 PQflush,反复执行直到返回零。)返回零表示缓冲区已满,无法将终止消息加入队列;这种情况仅可能发生在非阻塞模式下。(此时,应等待可写就绪,再次调用 PQputCopyEnd。)发生严重错误时返回 -1,可用 PQerrorMessage 获取详细信息。 + - 在成功调用PQputCopyEnd之后,调用PQgetResult获取COPY命令的最终结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 成功调用 PQputCopyEnd 后,调用 PQgetResult 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -3576,24 +3609,19 @@ int PQgetCopyData(PGconn *conn, - 在一个COPY期间尝试从服务器获取另外一行数据。数据总是以每次一个数据行的方式被返回;如果只有一个部分行可用,那么它不会被返回。 - 成功返回一个数据行涉及到分配一块内存来保存该数据。buffer参数必须为非NULL。 - *buffer被设置为指向分配到的内存的指针,或者是在没有返回缓冲区的情况下指向NULL。 - 一个非NULL的结果缓冲区在不需要时必须用PQfreemem释放。 + 在 COPY 期间尝试从服务器获取下一行数据。每次总是返回一个完整数据行;如果只有部分行可用,则不返回。成功返回数据行时,会分配一块内存保存数据。buffer 参数必须为非 NULL*buffer 会被设置为指向所分配的内存;如果没有返回缓冲区,则设为 NULL。非 NULL 的结果缓冲区在不再需要时应使用 PQfreemem 释放。 - 在成功返回一行之后,返回的值就是该数据行里数据的字节数(将是大于零)。 - 被返回的字符串总是以零字节结尾,虽然这可能只是对文本COPY有用。 - 一个零结果表示该COPY仍然在处理中,但是还没有可用的行(只在async为真时才可能)。 - 一个 -1 结果表示COPY已经完成。-2 结果表示发生了错误(参考PQerrorMessage获取原因)。 + 成功返回一行时,返回值是该行的数据字节数,始终大于零。返回的字符串总是以零字节结尾,不过这可能仅对文本 COPY 有用。返回零表示 COPY 仍在进行,但尚无可用行(仅在 async 为真时可能发生)。返回 -1 表示 COPY 已完成;返回 -2 表示发生了错误(可用 PQerrorMessage 查看原因)。 - async 为真(非零)时,PQgetCopyData 不会阻塞等待输入;如果 COPY 仍在进行,但没有完整的行可用,则返回零。(这种情况下,应等待读就绪,随后先调用 PQconsumeInput,再调用 PQgetCopyData。)当 async 为假(零)时,PQgetCopyData 会阻塞,直到有数据可用或操作完成。 + + 当 async 为真(非零)时,PQgetCopyData 不会阻塞等待输入;如果 COPY 仍在进行,但没有完整行可用,则返回零。(此时,应等待读就绪,先调用 PQconsumeInput,再调用 PQgetCopyData。)当 async 为假(零)时,PQgetCopyData 会阻塞,直到数据可用或操作完成。 + - 在PQgetCopyData返回 -1 之后,调用PQgetResult获取COPY命令的最后结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 在 PQgetCopyData 返回 -1 后,调用 PQgetResult 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -3602,11 +3630,11 @@ int PQgetCopyData(PGconn *conn, - 用于<command>COPY</command>的废弃函数 + 用于<command>COPY</command>的过时函数 - 这些函数代表了以前的处理COPY的方法。尽管它们还能用,但是现在已经被废弃,因为它们的错误处理很糟糕、检测结束数据的方法也不方便,并且缺少对二进制或非阻塞传输的支持。 - + 这些函数使用较旧的方式处理 COPY。虽然仍然可用,但由于错误处理欠佳、检测数据结束的方式不便,而且缺少对二进制或非阻塞传输的支持,已被弃用。 + @@ -3614,7 +3642,7 @@ int PQgetCopyData(PGconn *conn, - 读取一个以新行终止的字符行到(由服务器传输) 到一个长度为length的字符串缓冲区。 + 将服务器传来的、以换行符结尾的一行字符读入大小为 length 的字符串缓冲区。 int PQgetline(PGconn *conn, char *buffer, @@ -3623,11 +3651,10 @@ int PQgetline(PGconn *conn, - 这个函数拷贝最多length-1 个字符到该缓冲区中,并且把终止的新行转换成一个零字节。 - PQgetline在输入结束时返回EOF,如果整行都被读取则返回 0,如果缓冲区填满了而还没有遇到结束的新行则返回 1。 - + 此函数最多将 length-1 个字符复制到缓冲区,并将末尾的换行符转换为零字节。PQgetline 在输入结束时返回 EOF,读完一整行时返回 0,缓冲区已满但尚未读到末尾换行符时返回 1。 + - 注意,应用必须检查是否一个新行包含两个字符\.,这表明服务器 已经完成了COPY命令的结果发送。如果应用可能收到超过length-1 字符长的行, 我们就应该确保正确识别\.行(例如,不要把一个长数据行的结束当作一个终止行)。 + 注意,应用程序必须检查新读入的一行是否仅由 \. 两个字符组成,这表示服务器已发送完 COPY 命令的结果。如果可能收到长度超过 length-1 个字符的行,必须确保正确识别 \. 行,例如不能把长数据行的末尾误当作终止行。 @@ -3637,7 +3664,7 @@ int PQgetline(PGconn *conn, - 不阻塞地读取一行COPY数据(由服务器传输)到一个缓冲区中。 + 以非阻塞方式将服务器传来的一行 COPY 数据读入缓冲区。 int PQgetlineAsync(PGconn *conn, char *buffer, @@ -3646,22 +3673,18 @@ int PQgetlineAsync(PGconn *conn, - 这个函数类似于PQgetline,但是可以被用于那些必须异步读取COPY数据的应用, 也就是不阻塞的应用。 - 在发出了COPY命令并得到了PGRES_COPY_OUT响应之后, - 应用应该调用PQconsumeInputPQgetlineAsync直到检测到结束数据的信号。 - + 此函数类似于 PQgetline,但可用于必须异步读取 COPY 数据的应用程序,即读取时不阻塞。发出 COPY 命令并收到 PGRES_COPY_OUT 响应后,应用程序应调用 PQconsumeInputPQgetlineAsync,直到检测到数据结束信号。 + - 不像PQgetline,这个函数负责检测结束数据。 + 与 PQgetline 不同,此函数会负责检测数据结束。 - 在每次调用时,如果libpq的输入缓冲区中有一个完整的数据行可用,PQgetlineAsync都将返回数据。 - 否则,在剩余行到达之前不会返回数据。如果识别到拷贝数据结束的标志,此函数返回 -1;如果没有可用数据则返回 0; - 或者返回一个正数,表示返回的数据字节数。如果返回 -1,调用者下一步必须调用PQendcopy,然后回到正常处理。 + 每次调用时,如果 libpq 的输入缓冲区中有完整数据行,PQgetlineAsync 就会返回数据;否则,要等该行剩余部分到达后才返回数据。识别到复制数据结束标记时返回 -1,没有可用数据时返回 0,否则返回正数,表示返回的数据字节数。返回 -1 后,调用者必须接着调用 PQendcopy,然后恢复正常处理。 - 返回的数据将不超过一个数据行的范围。如果可能,每次将返回一个完整行。但如果调用者提供的缓冲区太小不足以容下服务器发送的行,那么将返回部分行。对于文本数据,这可以通过测试返回的最后一个字节是否\n来检测(在二进制COPY中, 需要对COPY数据格式进行实际的分析,以便做相同的判断)。被返回的字符串不是空结尾的(如果你想增加一个终止空,确保传递一个比实际可用空间少一字节的bufsize)。 + 返回的数据不会跨越数据行边界。只要可能,每次就返回一整行;但如果调用者提供的缓冲区太小,容不下服务器发送的一行,则只返回部分行。对于文本数据,可检查最后返回的字节是否为 \n,以判断是否返回了完整行。(对于二进制 COPY,则必须实际解析 COPY 数据格式才能作出相同判断。)返回的字符串不以零字节结尾。(如果要自行添加末尾的零字节,务必将传入的 bufsize 设置为比实际可用空间少一字节。) @@ -3671,7 +3694,7 @@ int PQgetlineAsync(PGconn *conn, - 向服务器发送一个空终止的字符串。如果 OK 则返回 0;如果不能发送字符串则返回EOF。 + 向服务器发送以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputline(PGconn *conn, const char *string); @@ -3679,16 +3702,13 @@ int PQputline(PGconn *conn, - 一系列PQputline调用发送的COPY数据流和PQgetlineAsync返回的数据具有相同的格式, - 只是应用不需要每次PQputline调用中发送刚好一个数据行;在每次调用中发送多行或者部分行都是可以的。 + 连续调用 PQputline 发送的 COPY 数据流,与 PQgetlineAsync 返回的数据格式相同。不过,应用程序不必在每次 PQputline 调用中恰好发送一个数据行;每次发送部分行或多行也可以。 - 在PostgreSQL协议 3.0 之前,应用必须显式地发送两个字符\.作为最后一行来告知服务器应用程序已完成发送COPY数据。 - 虽然这么做仍然有效,但是它已经被废弃并且\.的特殊含义可能在将来的版本中删除。 - 在发送完实际数据之后, 调用PQendcopy就足够了。 - + 在 PostgreSQL 协议 3.0 之前,应用程序必须显式发送由 \. 两个字符组成的最后一行,告知服务器应用程序已发送完 COPY 数据。虽然这种方式仍然有效,但已被弃用,\. 的特殊含义预计会在未来版本中移除。发送完实际数据后,调用 PQendcopy 即可。 + @@ -3698,7 +3718,7 @@ int PQputline(PGconn *conn, - 向服务器发送一个非空终止的字符串。如果 OK 则返回 0,如果不能发送字符串则返回EOF。 + 向服务器发送不以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputnbytes(PGconn *conn, const char *buffer, @@ -3707,7 +3727,7 @@ int PQputnbytes(PGconn *conn, - 这个函数类似PQputline,除了数据缓冲区不需要以零字节结尾,因为要发送的字节数是直接指定的。在发送二进制数据时使用这个函数。 + 此函数与 PQputline 完全相同,只是直接指定了要发送的字节数,因此数据缓冲区不必以零字节结尾。发送二进制数据时可使用此函数。 @@ -3716,15 +3736,16 @@ int PQputnbytes(PGconn *conn, PQendcopy PQendcopy - 与服务器同步。 + + 与服务器同步。 + int PQendcopy(PGconn *conn); -此函数会等待服务器完成复制。调用时机应为:使用PQputline向服务器发送最后一个字符串后,或者使用PQgetline从服务器收到最后一个字符串后。必须调用此函数,否则服务器与客户端将会不同步。此函数返回后,服务器便准备好接收下一条 SQL 命令。成功完成时返回 0,否则返回非零值。(若返回非零值,可使用PQerrorMessage取得详细信息。) + +此函数会等待服务器完成复制。应在使用 PQputline 向服务器发送最后一个字符串后,或使用 PQgetline 从服务器接收最后一个字符串后调用它。必须调用此函数,否则服务器与客户端会失去同步。函数返回后,服务器便准备好接收下一条 SQL 命令。成功完成时返回 0,否则返回非零值。(返回非零值时,可用 PQerrorMessage 获取详细信息。) + - 在使用PQgetResult时,应用应该通过反复调用PQgetline并且在看到终止行后调用PQendcopy来响应PGRES_COPY_OUT结果。 - 然后它应该返回到PQgetResult循环直到PQgetResult返回一个空指针。 - 类似地,PGRES_COPY_IN结果会用一系列PQputline加上之后的PQendcopy来处理,然后返回到PQgetResult循环。 - 这样的安排将保证嵌入到一系列SQL命令中的COPY命令将被正确执行。 + 使用 PQgetResult 时,收到 PGRES_COPY_OUT 结果后,应用程序应反复调用 PQgetline,并在看到终止行后调用 PQendcopy。随后应回到 PQgetResult 循环,直到 PQgetResult 返回空指针。类似地,收到 PGRES_COPY_IN 结果后,应连续调用 PQputline,再调用 PQendcopy,然后回到 PQgetResult 循环。这样可以保证嵌在一系列 SQL 命令中的 COPY 命令正确执行。 @@ -3743,8 +3764,8 @@ int PQendcopy(PGconn *conn); 控制函数 - 这些函数控制libpq行为各种各样的细节。 - + 这些函数控制 libpq 行为的各种细节。 + @@ -3753,17 +3774,15 @@ int PQendcopy(PGconn *conn); - 返回客户端编码。 + 返回客户端编码。 int PQclientEncoding(const PGconn *conn); - - 请注意,它返回的是编码 ID,而不是一个符号串字符串,如EUC_JP。如果不成功,它会返回 -1。要把一个编码 ID 转换为为一个编码名称,可以用: - +注意,返回的是编码 ID,而不是 EUC_JP 这样的符号字符串。失败时返回 -1。要将编码 ID 转换为编码名称,可以使用: char *pg_encoding_to_char(int encoding_id); - + @@ -3825,16 +3844,16 @@ PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibilit - 启用对客户端/服务器通讯的跟踪,把跟踪信息输出到一个调试文件流中。 + 启用客户端/服务器通信跟踪,将跟踪信息写入调试文件流。 void PQtrace(PGconn *conn, FILE *stream); - + - 在 Windows上,如果libpq库和应用使用了不同的标志编译,那么这个函数调用会导致应用崩溃,因为FILE指针的内部表达是不一样的。特别是多线程/单线程、发布/调试 以及静态/动态标志应该是库和所有使用库的应用都一致。 + 在 Windows 上,如果 libpq 库与应用程序使用不同的标志编译,调用此函数会导致应用程序崩溃,因为 FILE 指针的内部表示不同。具体而言,库与所有使用它的应用程序都应使用相同的多线程/单线程、发布/调试和静态/动态标志。 @@ -3845,11 +3864,12 @@ void PQtrace(PGconn *conn, FILE *stream); PQuntrace PQuntrace - 禁用以下函数启动的跟踪:PQtrace。 + + 禁用由 PQtrace 启动的跟踪。 void PQuntrace(PGconn *conn); - + @@ -3876,11 +3896,8 @@ void PQfreemem(void *ptr); - 释放libpq分配的内存,尤其是PQescapeByteaConn,PQescapeBytea,PQunescapeBytea,和PQnotifies分配的内存。 - 特别重要的是,在微软 Windows 上使用这个函数,而不是free()。 - 这是因为只有 当 DLL 和应用的多线程/单线程、发布/调试以及静态/动态标志相同时,才能在一个 DLL 中分配内存并且在应用中释放它。 - 在非微软 Windows 平台上,这个函数与标准库函数free()相同。 - + 释放 libpq 分配的内存,特别是 PQescapeByteaConnPQescapeByteaPQunescapeByteaPQnotifies 分配的内存。在 Microsoft Windows 上,务必使用此函数,而不是 free()。这是因为只有 DLL 与应用程序使用相同的多线程/单线程、发布/调试和静态/动态标志,才能在 DLL 中分配内存并在应用程序中释放它。在 Microsoft Windows 以外的平台上,此函数与标准库函数 free() 相同。 + @@ -3888,7 +3905,8 @@ void PQfreemem(void *ptr); PQconninfoFree PQconninfoFree - 释放以下函数分配的数据结构:PQconndefaultsPQconninfoParse。 + + 释放PQconndefaultsPQconninfoParse分配的数据结构。 void PQconninfoFree(PQconninfoOption *connOptions); @@ -3932,10 +3950,13 @@ char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, PQencryptPassword PQencryptPassword - 准备经过 md5 加密的PostgreSQL密码。 + + 准备一个PostgreSQL密码的md5加密形式。 + char *PQencryptPassword(const char *passwd, const char *user); - PQencryptPassword是以下函数的旧版本,现已弃用:PQencryptPasswordConn。区别在于PQencryptPassword不需要连接对象,并且md5始终用作加密算法。 + PQencryptPasswordPQencryptPasswordConn的旧版本,现已弃用。其差别是PQencryptPassword不需要连接对象,并且总是用md5作为加密算法。 + @@ -3954,8 +3975,8 @@ PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); 这是libpq内部用于分配并初始化一个空PGresult对象的函数。 如果无法分配内存,此函数返回NULL。 将它导出供外部调用,是因为一些应用需要自行生成结果对象,特别是带有错误状态的对象。 - 如果conn非空,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 - 此外,如果conn非空,连接中注册的所有事件过程也会被复制到PGresult中。 + 如果conn 不为 null,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 + 此外,如果conn 不为 null,连接中注册的所有事件过程也会被复制到PGresult中。 (这些过程不会收到PGEVT_RESULTCREATE调用,但可参见PQfireResultCreateEvents。) 注意,最终应对该对象调用PQclear,就像处理libpq自身返回的PGresult一样。 @@ -3974,16 +3995,16 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); - conn参数被传送给事件过程,但不会被直接使用。如果事件过程不使用它,则会返回NULL。 - + conn 参数会传递给事件过程,但此函数不会直接使用它。如果事件过程不使用此参数,则可以传入 NULL。 + 已经接收到这个对象的PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件过程不会被再次触发。 - 这个函数与PQmakeEmptyPGresult分开的主要原因是在调用事件过程之前创建一个PGresult并且填充它常常是合适的。 - + 此函数与 PQmakeEmptyPGresult 分开的主要原因是,通常适合先创建 PGresult 并填充数据,然后再调用事件过程。 + @@ -3991,10 +4012,12 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); PQcopyResult PQcopyResult - 创建一个PGresult对象的副本。副本与源结果没有任何关联,并且PQclear必须在不再需要该副本时调用。如果函数失败,会返回NULL + + 创建 PGresult 对象的副本。副本与源结果没有任何关联,不再需要副本时必须调用 PQclear。函数失败时返回 NULL。 + PGresult *PQcopyResult(const PGresult *src, int flags); - + 这不是为了制作一个精确的副本。返回的结果总是放在PGRES_TUPLES_OK状态中,并且不复制源中的任何错误消息。 (但是会复制命令状态字符串。)flags参数确定要复制的其他内容。它是几个标志的按位或。 PG_COPYRES_ATTRS指定复制源结果的属性(列定义)。 PG_COPYRES_TUPLES指定复制源结果的元组。(这也意味着复制属性。) PG_COPYRES_NOTICEHOOKS指定复制源结果的通知钩子。 PG_COPYRES_EVENTS指定复制源结果的事件。(但不复制与源相关的任何实例数据。) @@ -4023,18 +4046,15 @@ int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs); - 设置一个PGresult对象的一个元组域值。 + 设置 PGresult 对象中某个元组的字段值。 int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len); - + - 这个函数将自动按需增加结果的内部元组数组。但是,tup_num参数必须小于等于PQntuples,意味着这个函数对元组数组一次只能增加一个元组。 - 但已存在的任意元组中的任意域可以以任意顺序进行调整。如果field_num的一个值已经存在,它会被覆盖。 - 如果len是 -1,或valueNULL, 该域值会被设置为一个 SQL 空值。 - value会被复制到结果的私有存储中,因此函数返回后就不再需要了。如果函数失败,返回值是 0。如果函数成功,返回值会是非 0。 - + 此函数会根据需要自动扩展结果内部的元组数组。不过,tup_num 参数必须小于或等于 PQntuples,也就是说,每次只能向元组数组增加一个元组。已有元组的任何字段都可以按任意顺序修改。如果 field_num 指定的位置已有值,该值会被覆盖。如果 len 为 -1 或 valueNULL,则将该字段设置为 SQL null 值。value 会被复制到结果的私有存储中,因此函数返回后就不再需要它。函数失败时返回零,成功时返回非零值。 + @@ -4051,8 +4071,8 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); - 当res被清除时,这个函数分配的内存也会被释放掉。如果函数失败,返回值是NULL。结果被保证为按照数据的任意类型充分地对齐,正如malloc所作的。 - + 使用此函数分配的所有内存都会在清除 res 时释放。函数失败时返回 NULL。与 malloc 一样,返回的内存保证满足任意数据类型的对齐要求。 + @@ -4068,28 +4088,25 @@ int PQlibVersion(void); - 在运行时,这个函数的结果可以被用来决定在当前已载入的 libpq 版本中特定的功能是否可用。 - 例如,这个函数可以被用来决定哪些选项可以被用于PQconnectdb。 - + 可在运行时根据此函数的结果,判断当前已加载的 libpq 版本是否具有特定功能。例如,可用它判断 PQconnectdb 支持哪些连接选项。 + - 结果通过将库的主版本号乘以10000再加上次版本号形成。例如,版本10.1将被返回为100001,而版本11.0将被返回为110000。 - + 返回值等于库的主版本号乘以 10000 再加上次版本号。例如,版本 10.1 返回 100001,版本 11.0 返回 110000。 + - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。 - 对于那些版本,PQlibVersion为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - + 在主版本 10 之前,PostgreSQL 使用由三个部分组成的版本号,前两个部分共同表示主版本。对于这些版本,PQlibVersion 用两位数字表示每个部分;例如,版本 9.1.5 返回 90105,版本 9.2.0 返回 90200。 + - 因此,出于判断特性兼容性的目的,应用应该将PQlibVersion的结果除以100而不是10000来判断逻辑的主版本号。 - 在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 - + 因此,为了判断功能兼容性,应用程序应将 PQlibVersion 的结果除以 100 而非 10000,得到逻辑上的主版本号。在所有版本系列中,次版本(错误修复版本)之间只有最后两位数字不同。 + - 这个函数出现于PostgreSQL版本 9.1,因此它不能被用来在早期的版本中检测所需的功能,因为调用它将会创建一个对版本9.1及其后版本的链接依赖。 + 此函数从 PostgreSQL 9.1 起提供,因而不能用它检测更早版本是否具有所需功能:调用它会建立对 9.1 或更高版本的链接依赖。 @@ -4103,13 +4120,13 @@ int PQlibVersion(void); 通知处理 - notice processing - in libpq + 通知处理 + 在 libpq 中 - 服务器产生的通知和警告消息不会被查询执行函数返回,因为它们不代表查询失败。它们可以被传递给一个通知处理函数,并且在处理者返回后执行会继续正常进行。默认的处理函数会把消息打印在stderr上,但是应用可以通过提供它自己的处理函数来重载这种行为。 - + 服务器生成的通知和警告消息不由查询执行函数返回,因为它们并不表示查询失败。这些消息会传递给通知处理函数,处理函数返回后,执行正常继续。默认通知处理函数将消息打印到 stderr,应用程序也可以提供自己的处理函数来替换这一行为。 + 由于历史原因,通知处理有两个级别,称为通知接收器和通知处理器。通知接收器的默认行为是格式化通知并且将一个字符串传递给通知处理器来打印。不过,如果一个应用选择提供自己的通知接收器,它通常会忽略通知处理器层并且在通知接收器中完成所有工作。 @@ -4117,10 +4134,10 @@ int PQlibVersion(void); 函数PQsetNoticeReceiver - notice receiver + 通知接收器 PQsetNoticeReceiver为一个连接对象设置或者检查当前的通知接收器。 相似地,PQsetNoticeProcessor - notice processor + 通知处理器 PQsetNoticeProcessor设置或检查当前的通知处理器。 @@ -4143,19 +4160,16 @@ PQsetNoticeProcessor(PGconn *conn, - 当接收到一个服务器产生的或者libpq内部产生的通知或警告消息,通知接收器函数会被调用。 - 该函数会以一种PGRES_NONFATAL_ERROR PGresult的形式接收该消息 - (这允许接收器使用PQresultErrorField抽取个别的域,或者使用PQresultErrorMessage或者PQresultVerboseErrorMessage得到一个完整的预格式化的消息)。 - 被传递给PQsetNoticeReceiver的同一个 void 指针也被传递(必要时,这个指针可以被用来访问应用相关的状态)。 - + 从服务器收到通知或警告消息,或者 libpq 内部生成这类消息时,便会调用通知接收器函数。消息以状态为 PGRES_NONFATAL_ERRORPGresult 对象传给该函数。(接收器可使用 PQresultErrorField 提取单个字段,也可使用 PQresultErrorMessagePQresultVerboseErrorMessage 获取完整的预格式化消息。)传给 PQsetNoticeReceiver 的同一个 void 指针也会传入。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知接收器会简单地抽取消息(使用PQresultErrorMessage)并且将它传递给通知处理器。 - 通知处理器负责处理一个以文本形式给出的通知或警告消息。该消息的字符串文本(包括一个收尾的新行)被传递给通知处理器,外加一个同时被传递给PQsetNoticeProcessor的空指针(必要时,这个指针可以被用来访问应用相关的状态)。 - + 通知处理器负责处理以文本形式提供的通知或警告消息。传给它的参数包括消息字符串(含末尾的换行符),以及先前传给 PQsetNoticeProcessor 的同一个 void 指针。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知处理器很简单: @@ -4169,9 +4183,8 @@ defaultNoticeProcessor(void *arg, const char *message) - 一旦你设定了一个通知接收器或处理器,你应该期待只要PGconn对象或者从它构造出的PGresult对象存在,该函数就可能被调用。 - 在一个PGresult创建时,PGconn的当前通知处理指针被复制到PGresult中,以备类似PQgetvalue的函数使用。 - + 设置通知接收器或处理器后,应当预期:只要 PGconn 对象或由它生成的 PGresult 对象仍存在,就可能调用该函数。创建 PGresult 时,会将 PGconn 当前的通知处理指针复制到 PGresult 中,供 PQgetvalue 等函数在需要时使用。 + @@ -4179,10 +4192,10 @@ defaultNoticeProcessor(void *arg, const char *message) 事件系统 - libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和毁灭。一种主要的使用情况是这允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 + libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和销毁。一个主要用途是允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 - 每个注册的事件处理程序都与两个数据相关联,libpq仅将其视为不透明的void *指针。 有一个透传指针,当事件处理程序与PGconn注册时,应用程序提供。 透传指针在PGconn及其生成的所有PGresult的生命周期内永远不会更改; 因此,如果使用,它必须指向长期存在的数据。 此外,还有一个实例数据指针,在每个PGconnPGresult中一开始都是NULL。 可以使用PQinstanceDataPQsetInstanceDataPQresultInstanceDataPQsetResultInstanceData函数来操作此指针。 请注意,与透传指针不同,PGconn的实例数据不会自动继承到从中创建的PGresultlibpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 —— 这是事件处理程序的责任。 + 每个注册的事件处理程序都与两项数据相关联,libpq仅将其视为不透明的void *指针。 有一个透传指针,由应用程序在向 PGconn 注册事件处理程序时提供。 透传指针在PGconn及其生成的所有PGresult的生命周期内永远不会更改; 因此,如果使用,它必须指向长期存在的数据。 此外,还有一个实例数据指针,在每个PGconnPGresult中一开始都是NULL。 可以使用PQinstanceDataPQsetInstanceDataPQresultInstanceDataPQresultSetInstanceData函数来操作此指针。 请注意,与透传指针不同,PGconn的实例数据不会自动继承到从中创建的PGresultlibpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 — 这是事件处理程序的责任。 事件类型 @@ -4195,7 +4208,7 @@ defaultNoticeProcessor(void *arg, const char *message) PGEVT_REGISTER - 注册事件在PQregisterEventProc被调用时触发。此时最适合初始化事件处理函数可能需要的instanceData。每个连接中的每个事件处理函数只会触发一次注册事件。如果事件处理函数失败,则中止注册。 + 注册事件在PQregisterEventProc被调用时触发。此时最适合初始化事件过程可能需要的instanceData。每个连接中的每个事件过程只会触发一次注册事件。如果事件过程失败,则中止注册。 typedef struct { PGconn *conn; @@ -4207,26 +4220,26 @@ typedef struct PGEVT_CONNRESET - 连接重置事件会在完成以下调用时触发:PQresetPQresetPoll。在这两种情况下,只有重置成功才会触发该事件。如果事件处理函数失败,整个连接重置就会失败;PGconn会被置于CONNECTION_BAD状态,并且PQresetPoll将返回PGRES_POLLING_FAILED。 + 连接重置事件会在完成以下调用时触发:PQresetPQresetPoll。在这两种情况下,只有重置成功才会触发该事件。如果事件过程失败,整个连接重置就会失败;PGconn会被置于CONNECTION_BAD状态,并且PQresetPoll将返回PGRES_POLLING_FAILED typedef struct { PGconn *conn; } PGEventConnReset; -收到PGEVT_CONNRESET事件时,应将evtInfo指针强制转换为PGEventConnReset *。虽然其中的PGconn刚刚被重置,但所有事件数据都保持不变。应利用此事件重置、重新加载或重新查询相关联的instanceData。注意,即使事件处理函数未能处理PGEVT_CONNRESET,它仍会在连接关闭时收到PGEVT_CONNDESTROY事件。 +收到PGEVT_CONNRESET事件时,应将evtInfo指针强制转换为PGEventConnReset *。虽然其中的PGconn刚刚被重置,但所有事件数据都保持不变。应利用此事件重置、重新加载或重新查询相关联的instanceData。注意,即使事件过程未能处理PGEVT_CONNRESET,它仍会在连接关闭时收到PGEVT_CONNDESTROY事件。 PGEVT_CONNDESTROY - 连接销毁事件由以下调用触发:PQfinish。事件处理函数负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 + 连接销毁事件由以下调用触发:PQfinish。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGconn *conn; } PGEventConnDestroy; -收到PGEVT_CONNDESTROY事件时,应将evtInfo指针强制转换为PGEventConnDestroy *。该事件触发于以下函数执行任何其他清理工作之前:PQfinish。事件处理函数的返回值会被忽略,因为无法通过以下函数报告失败:PQfinish。此外,事件处理函数失败不应中止清理不再使用的内存的过程。 +收到PGEVT_CONNDESTROY事件时,应将evtInfo指针强制转换为PGEventConnDestroy *。该事件触发于以下函数执行任何其他清理工作之前:PQfinish。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:PQfinish。此外,事件过程失败不应中止清理不再使用的内存的过程。 @@ -4258,32 +4271,32 @@ typedef struct PGEVT_RESULTCOPY - 结果复制事件会在调用PQcopyResult时触发。只有复制完成后才会触发该事件。只有为源结果成功处理过PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件处理函数,才会收到PGEVT_RESULTCOPY事件。 + 结果复制事件会在调用PQcopyResult时触发。只有复制完成后才会触发该事件。只有为源结果成功处理过PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件过程,才会收到PGEVT_RESULTCOPY事件。 typedef struct { const PGresult *src; PGresult *dest; } PGEventResultCopy; -收到PGEVT_RESULTCOPY事件时,应将evtInfo指针强制转换为PGEventResultCopy *。其中,src结果是复制源,而dest结果是复制目标。可以利用此事件对instanceData进行深复制,因为PQcopyResult无法完成这项工作。如果事件处理函数失败,整个复制操作就会失败,并且dest结果将被清除。返回失败代码时,必须完成所有清理工作,因为不会为目标结果发送PGEVT_RESULTDESTROY事件。 +收到PGEVT_RESULTCOPY事件时,应将evtInfo指针强制转换为PGEventResultCopy *。其中,src结果是复制源,而dest结果是复制目标。可以利用此事件对instanceData进行深复制,因为PQcopyResult无法完成这项工作。如果事件过程失败,整个复制操作就会失败,并且dest结果将被清除。返回失败代码时,必须完成所有清理工作,因为不会为目标结果发送PGEVT_RESULTDESTROY事件。 PGEVT_RESULTDESTROY - 结果销毁事件由以下调用触发:PQclear。事件处理函数负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 + 结果销毁事件由以下调用触发:PQclear。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGresult *result; } PGEventResultDestroy; -收到PGEVT_RESULTDESTROY事件时,应将evtInfo指针强制转换为PGEventResultDestroy *。该事件触发于以下函数执行任何其他清理工作之前:PQclear。事件处理函数的返回值会被忽略,因为无法通过以下函数报告失败:PQclear。此外,事件处理函数失败不应中止清理不再使用的内存的过程。 +收到PGEVT_RESULTDESTROY事件时,应将evtInfo指针强制转换为PGEventResultDestroy *。该事件触发于以下函数执行任何其他清理工作之前:PQclear。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:PQclear。此外,事件过程失败不应中止清理不再使用的内存的过程。 - 事件回调函数 + 事件回调过程 @@ -4291,9 +4304,12 @@ typedef struct - PGEventProc是通过 typedef 定义的事件处理函数指针类型,也就是接收 libpq 事件的用户回调函数的指针类型。事件处理函数的签名必须为 + PGEventProc 是通过 typedef 定义的事件过程指针类型,也就是接收 libpq 事件的用户回调函数的指针类型。事件过程的签名必须为: + int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) -其中,evtId参数指示发生了哪一种PGEVT事件。必须将evtInfo指针强制转换为适当的结构体类型,以获取关于该事件的更多信息。passThrough参数是在注册事件处理函数时传给以下函数的指针:PQregisterEventProc。函数应在成功时返回非零值,在失败时返回零。 + +evtId 参数指示发生了哪一种 PGEVT 事件。必须将 evtInfo 指针强制转换为适当的结构体类型,以获取关于该事件的更多信息。passThrough 参数是在注册事件过程时传给 PQregisterEventProc 的指针。函数应在成功时返回非零值,在失败时返回零。 + 在任何一个PGconn中,一个特定事件过程只能被注册一次。这是因为该过程的地址被用作查找键来标识相关的实例数据。 @@ -4302,8 +4318,8 @@ int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) - 在 Windows 上,函数能够有两个不同的地址:一个对 DLL 之外可见而另一个对 DLL 之内可见。我们应当小心只有其中之一会被用于libpq的事件过程函数,否则将会产生混淆。编写代码的最简单规则是将所有的事件过程声明为static。如果过程的地址必须对它自己的源代码文件之外可见,提供一个单独的函数来返回该地址。 - + 在 Windows 上,函数可能有两个不同的地址:一个在 DLL 外部可见,另一个在 DLL 内部可见。使用 libpq 的事件过程函数时,务必始终使用其中同一个地址,否则会产生混淆。确保代码正常工作的最简单做法,是将事件过程声明为 static。如果需要在过程所在的源文件之外取得其地址,应提供一个单独的函数来返回该地址。 + @@ -4329,7 +4345,7 @@ int PQregisterEventProc(PGconn *conn, PGEventProc proc, - 在每一个你想要接收事件的PGconn上必须注册一个事件过程。和内存不同,没有限制说一个连接上能注册多少个事件过程。如果该函数成功,它会返回一个非零值。如果它失败,则会返回零。 + 对于希望接收其事件的每个 PGconn,都必须注册一次事件过程。一个连接可注册的事件过程数量只受内存限制。函数成功时返回非零值,失败时返回零。 @@ -4369,7 +4385,9 @@ void *PQinstanceData(const PGconn *conn, PGEventProc proc); PQresultSetInstanceData PQresultSetInstanceData - 将结果的instanceData(针对proc)设置为data。成功时返回非零,失败时返回零。(只有当proc未在结果中正确注册时,才可能失败。) + + 将结果中针对 procinstanceData 设置为 data。成功时返回非零值,失败时返回零。(只有当 proc 未在结果中正确注册时,才可能失败。) + int PQresultSetInstanceData(PGresult *res, PGEventProc proc, void *data); @@ -4393,18 +4411,18 @@ void *PQresultInstanceData(const PGresult *res, PGEventProc proc); - 事件实例 + 事件示例 - 这里是一个管理与 libpq 连接和结果相关的私有数据的示例的框架。 - + 下面给出一个示例框架,用于管理与 libpq 连接和结果关联的私有数据。 + -/* The instanceData */ +/* instanceData 数据 */ typedef struct { int n; @@ -4430,8 +4448,8 @@ main(void) return 1; } - /* called once on any connection that should receive events. - * Sends a PGEVT_REGISTER to myEventProc. + /* 在每个需要接收事件的连接上调用一次。 + * 向 myEventProc 发送 PGEVT_REGISTER 事件。 */ if (!PQregisterEventProc(conn, myEventProc, "mydata_proc", NULL)) { @@ -4440,28 +4458,28 @@ main(void) return 1; } - /* conn instanceData is available */ + /* 可以取得 conn 的 instanceData */ data = PQinstanceData(conn, myEventProc); - /* Sends a PGEVT_RESULTCREATE to myEventProc */ + /* 向 myEventProc 发送 PGEVT_RESULTCREATE 事件 */ res = PQexec(conn, "SELECT 1 + 1"); - /* result instanceData is available */ + /* 可以取得结果的 instanceData */ data = PQresultInstanceData(res, myEventProc); - /* If PG_COPYRES_EVENTS is used, sends a PGEVT_RESULTCOPY to myEventProc */ + /* 使用 PG_COPYRES_EVENTS 时,向 myEventProc 发送 PGEVT_RESULTCOPY 事件 */ res_copy = PQcopyResult(res, PG_COPYRES_TUPLES | PG_COPYRES_EVENTS); - /* result instanceData is available if PG_COPYRES_EVENTS was - * used during the PQcopyResult call. + /* 如果调用 PQcopyResult 时使用了 PG_COPYRES_EVENTS, + * 就可以取得结果的 instanceData。 */ data = PQresultInstanceData(res_copy, myEventProc); - /* Both clears send a PGEVT_RESULTDESTROY to myEventProc */ + /* 两次清除操作都会向 myEventProc 发送 PGEVT_RESULTDESTROY 事件 */ PQclear(res); PQclear(res_copy); - /* Sends a PGEVT_CONNDESTROY to myEventProc */ + /* 向 myEventProc 发送 PGEVT_CONNDESTROY 事件 */ PQfinish(conn); return 0; @@ -4477,7 +4495,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventRegister *e = (PGEventRegister *)evtInfo; mydata *data = get_mydata(e->conn); - /* associate app specific data with connection */ + /* 将应用程序特有的数据与连接关联 */ PQsetInstanceData(e->conn, myEventProc, data); break; } @@ -4497,7 +4515,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventConnDestroy *e = (PGEventConnDestroy *)evtInfo; mydata *data = PQinstanceData(e->conn, myEventProc); - /* free instance data because the conn is being destroyed */ + /* 连接正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; @@ -4509,8 +4527,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *conn_data = PQinstanceData(e->conn, myEventProc); mydata *res_data = dup_mydata(conn_data); - /* associate app specific data with result (copy it from conn) */ - PQsetResultInstanceData(e->result, myEventProc, res_data); + /* 将应用程序特有的数据与结果关联(从 conn 复制) */ + PQresultSetInstanceData(e->result, myEventProc, res_data); break; } @@ -4520,8 +4538,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *src_data = PQresultInstanceData(e->src, myEventProc); mydata *dest_data = dup_mydata(src_data); - /* associate app specific data with result (copy it from a result) */ - PQsetResultInstanceData(e->dest, myEventProc, dest_data); + /* 将应用程序特有的数据与结果关联(从另一个结果复制) */ + PQresultSetInstanceData(e->dest, myEventProc, dest_data); break; } @@ -4530,18 +4548,18 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventResultDestroy *e = (PGEventResultDestroy *)evtInfo; mydata *data = PQresultInstanceData(e->result, myEventProc); - /* free instance data because the result is being destroyed */ + /* 结果正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; } - /* unknown event ID, just return true. */ + /* 未知的事件 ID,直接返回 true。 */ default: break; } - return true; /* event processing succeeded */ + return true; /* 事件处理成功 */ } ]]> @@ -4555,7 +4573,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) 环境变量 - 以下环境变量可用于选择连接参数的默认值,供以下函数使用:PQconnectdbPQsetdbLoginPQsetdb,前提是调用代码没有直接指定这些参数的值。例如,这样可以避免在简单的客户端应用程序中硬编码数据库连接信息。 + + 以下环境变量可用于选择连接参数的默认值,供 PQconnectdbPQsetdbLoginPQsetdb 在调用代码未直接指定参数值时使用。例如,这样可以避免在简单的客户端应用程序中硬编码数据库连接信息。 + @@ -4652,9 +4672,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSERVICEFILE - PGSERVICEFILE指定每个用户的连接服务文件的名称 - (参见)。 - 默认为~/.pg_service.conf,或者在Microsoft Windows上为%APPDATA%\postgresql\.pg_service.conf。 + PGSERVICEFILE指定每个用户的连接服务文件的名称(参见)。 + 默认为~/.pg_service.conf,或者在 Microsoft Windows 上为%APPDATA%\postgresql\.pg_service.conf @@ -4699,7 +4718,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGREQUIRESSL的行为与连接参数相同。 - 这个环境变量已被弃用,推荐使用PGSSLMODE变量;设置这两个变量会抑制这个变量的效果。 + 这个环境变量已被弃用,推荐使用PGSSLMODE变量;同时设置这两个变量时,前者不再生效。 @@ -4826,7 +4845,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 以下环境变量可用于指定每个PostgreSQL会话的默认行为。(也可参见命令,了解按用户或按数据库设置默认行为的方法。) + + 以下环境变量可用于指定每个 PostgreSQL 会话的默认行为。(也可参见 命令,了解按用户或按数据库设置默认行为的方法。) + @@ -4853,7 +4874,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGGEQO为遗传查询优化器设置默认模式(等同于SET geqo TO ...)。 - 有关这些环境变量的正确取值,请参见SQL命令 + +有关这些环境变量的正确取值,请参见 SQL 命令 。 + 下面的环境变量决定libpq的内部行为,它们会覆盖编译在程序中的默认值。 @@ -4901,7 +4924,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) (可以复制上面这一行,并在行首加上#,在文件中加入提示注释。)前四个字段中的每一个都可以是字面值,或者是*,后者可以匹配任何内容。将使用与当前连接参数匹配的第一行中的密码字段。(因此,使用通配符时,应将更具体的条目放在前面。)如果条目需要包含:\,请使用\转义该字符。主机名字段首先匹配已指定的host连接参数;否则匹配已指定的hostaddr参数。如果两者都未指定,则查找主机名localhost。在以下情况下也会查找主机名localhost:连接使用 Unix 域套接字,且host参数与libpq的默认套接字目录路径匹配。在备库中,数据库字段为replication时,匹配连接到主库的流复制连接。除此之外,数据库字段的用途有限,因为同一用户在同一数据库集簇的所有数据库中使用相同的密码。 - 在 Unix 系统上,密码文件上的权限必须不允许所有人或组内访问,可以用chmod 0600 ~/.pgpass这样的命令实现。如果权限没有这么严格,该文件将被忽略。在微软 Windows 上,该文件被假定存储在一个安全的目录中,因此不会进行特别的权限检查。 + 在 Unix 系统上,密码文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.pgpass 这样的命令实现。如果权限没有这么严格,该文件将被忽略。在 Microsoft Windows 上,假定该文件存储在安全的目录中,因此不进行特殊的权限检查。 @@ -4923,10 +4946,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 连接服务文件允许 libpq 连接参数与一个单一服务名称关联。 - 那个服务名称可以在一个 libpq 连接字符串里面指定,与其相关的设置将被使用。 - 这允许在不重新编译使用 libpq 的应用的前提下修改连接参数。 - 服务名称也可以被使用PGSERVICE环境变量来指定。 + 连接服务文件允许将 libpq 连接参数与单个服务名称关联。随后可以在 libpq 连接字符串中指定该服务名称,从而使用关联的设置。这样便可以修改连接参数,而无需重新编译使用 libpq 的应用程序。也可以使用 PGSERVICE 环境变量指定服务名称。 @@ -4942,23 +4962,19 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 或者服务文件使用一种INI 文件格式,其中小节名是服务名并且参数是连接参数。 - 列表见。例如: + 两种服务文件均使用 INI 文件 格式,其中配置段名称是服务名称,参数是连接参数;参数列表见 。例如: -# comment +# 注释 [mydb] host=somehost port=5433 user=admin - 在PostgreSQL安装的share/pg_service.conf.sample中提供了一个示例文件。 +PostgreSQL 安装目录中的 share/pg_service.conf.sample 提供了一个示例文件。 - 从服务文件中获取的连接参数与从其他来源获取的参数相结合。 - 服务文件设置覆盖相应的环境变量,然后反过来可以由连接字符串中直接给出的值覆盖。 - 例如,使用上面的服务文件,连接字符串service=mydb port=5434将使用主机somehost,端口5434, - 用户admin,以及由环境变量或内置默认所设置的其他参数。 + 从服务文件中获取的连接参数会与其他来源的参数合并。服务文件中的设置会覆盖相应的环境变量,而连接字符串中直接给出的值又会覆盖服务文件中的设置。例如,使用上述服务文件时,连接字符串 service=mydb port=5434 将使用主机 somehost、端口 5434、用户 admin,以及由环境变量或内置默认值设置的其他参数。 @@ -5001,7 +5017,7 @@ ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase) 你也可以将常规的服务文件条目和 LDAP 查找混合。pg_service.conf中一节的完整示例: -# 只有主机和端口存储在LDAP中,显式指定dbname和user。 +# 仅 host 和 port 存储在 LDAP 中;显式指定 dbname 和 user [customerdb] dbname=customer user=appuser @@ -5026,13 +5042,13 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 服务器证书的客户端验证 + 客户端对服务器证书的验证 - 默认情况下,PostgreSQL将不会执行服务器证书的任何验证。这意味着可以在不被客户端知晓的情况下伪造服务器身份(例如通过修改一个 DNS 记录或者接管服务器的 IP 地址)。为了阻止哄骗,客户端必须能够通过一条信任链验证服务器的身份。信任链可以这样建立:在一台计算机上放置一个根(自签名的)证书机构(CA)的证书并且在另一台计算机上放置一个由根证书签发的叶子证书。还可以使用一种中间证书,它由根证书签发并且可以签发叶子证书。 + 默认情况下,PostgreSQL 不会对服务器证书执行任何验证。这意味着可以在客户端不知情的情况下伪造服务器身份,例如修改 DNS 记录或接管服务器的 IP 地址。要防止身份伪造,客户端必须能够通过信任链验证服务器身份。建立信任链的方法是:在一台计算机上放置根证书机构(CA)的自签名证书,在另一台计算机上放置由根证书签发的叶证书。也可以使用由根证书签发、又用于签发叶证书的中间证书。 - 要让客户端验证服务器的身份,请在客户端放置根证书,并在服务器上放置由该根证书签名的叶证书。要让服务器验证客户端的身份,请在服务器上放置根证书,并在客户端放置由该根证书签名的叶证书。也可以使用一个或多个中间证书(通常与叶证书存储在一起),将叶证书链接到根证书。 + 要让客户端验证服务器的身份,请在客户端放置根证书,并在服务器上放置由该根证书签发的叶证书。要让服务器验证客户端的身份,请在服务器上放置根证书,并在客户端放置由该根证书签发的叶证书。也可以使用一个或多个中间证书(通常与叶证书存储在一起),将叶证书链接到根证书。 建立信任链后,客户端可以通过两种方式验证服务器发送的叶证书。如果参数 sslmode 设为 verify-ca,libpq 会沿证书链检查到存储在客户端上的根证书,以验证服务器是否可信。如果 sslmode 设为 verify-full,libpq 还会验证服务器主机名是否与服务器证书中存储的名称匹配。如果无法验证服务器证书,SSL 连接将失败。在大多数对安全敏感的环境中,建议使用 verify-full @@ -5051,8 +5067,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 为了与 PostgreSQL 的早期版本达到向后兼容,如果存在一个根 CA 文件,sslmode=require的行为将与verify-ca相同,即服务器证书根据 CA 验证。我们鼓励依赖这种行为,并且需要证书验证的应用应该总是使用verify-ca或者verify-full。 - + 为与 PostgreSQL 的早期版本向后兼容,如果存在根 CA 文件,sslmode=require 的行为将与 verify-ca 相同,即根据 CA 验证服务器证书。不建议依赖这种行为;需要证书验证的应用程序应始终使用 verify-caverify-full。 + @@ -5060,40 +5076,28 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 客户端证书 - 如果服务器尝试通过请求客户端的叶证书来验证客户端的身份, - libpq将发送存储在文件 - ~/.postgresql/postgresql.crt中的证书,该文件位于用户的主目录中。 - 证书必须链到服务器信任的根证书。匹配的 - 私钥文件~/.postgresql/postgresql.key也必须存在。 - 在Microsoft Windows上,这些文件的名称分别为 - %APPDATA%\postgresql\postgresql.crt和 - %APPDATA%\postgresql\postgresql.key。 - 证书和密钥文件的位置可以通过连接参数 - sslcertsslkey, - 或通过环境变量PGSSLCERTPGSSLKEY来覆盖。 - + 如果服务器请求客户端的叶证书以验证客户端身份,libpq 将发送用户主目录下 ~/.postgresql/postgresql.crt 文件中存储的证书。这些证书必须通过证书链连接到服务器信任的根证书。还必须存在匹配的私钥文件 ~/.postgresql/postgresql.key。在 Microsoft Windows 上,这两个文件分别名为 %APPDATA%\postgresql\postgresql.crt%APPDATA%\postgresql\postgresql.key。可以通过连接参数 sslcertsslkey,或环境变量 PGSSLCERTPGSSLKEY,覆盖证书和密钥文件的位置。 + - 在Unix系统上,私钥文件的权限必须禁止任何对世界或组的访问;可以通过类似以下命令来实现: - chmod 0600 ~/.postgresql/postgresql.key。 - 或者,该文件可以由root拥有并具有组读取权限(即0640权限)。 - 该设置适用于由操作系统管理证书和密钥文件的安装。然后,libpq的用户应该成为具有对这些证书和密钥文件访问权限的组的成员。 - (在Microsoft Windows上,没有文件权限检查,因为假定%APPDATA%\postgresql目录是安全的。) - + 在 Unix 系统上,私钥文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.postgresql/postgresql.key 这样的命令实现。另一种做法是使文件归 root 所有,并允许组用户读取(即 0640 权限)。这种设置适用于由操作系统管理证书和密钥文件的安装环境。此时,应将 libpq 用户加入有权访问这些证书和密钥文件的组。(在 Microsoft Windows 上,不检查文件权限,因为假定 %APPDATA%\postgresql 目录是安全的。) + postgresql.crt中的第一个证书必须是客户端的证书,因为它必须匹配客户端的私钥。可以选择将中间证书追加到该文件 — 这样做避免了在服务器上存放中间证书的要求()。 - 创建证书的指令请参考。 + 有关创建证书的说明,请参见 不同模式中提供的保护 - sslmode参数选择不同的值可以提供不同程度的保护。SSL 可以防范三类攻击: + + sslmode 参数的不同值提供不同级别的保护。SSL 可以防范三类攻击: + 窃听 @@ -5105,31 +5109,33 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 中间人(MITM - 如果一个第三方能对客户端和服务器之间传送的数据进行修改,它就能假装是服务器并且因此能看见并且修改数据,即使这些数据已被加密。然后第三方可以将连接信息和数据转送给原来的服务器,使得它不可能检测到攻击。这样做的通常途径包括 DNS 污染和地址劫持,借此客户端被重定向到一个不同的服务器。还有几种其他的攻击方式能够完成这种攻击。SSL使用证书验证让客户端认证服务器,就可以阻止这种攻击。 - + + 如果第三方能修改客户端与服务器之间传输的数据,就可以冒充服务器,进而查看和修改数据,即使数据已经加密。随后,第三方可以将连接信息和数据转发给原来的服务器,使攻击无法被察觉。常见的手段包括 DNS 污染和地址劫持,从而将客户端引向预期之外的服务器。还有其他几种攻击手段可以达到同样的目的。SSL 使用证书验证,让客户端认证服务器身份,以防范这种攻击。 + - 模仿 + 冒充 - 如果一个第三方能假装是一个授权的客户端,它能够简单地访问它本不能访问的数据。通常这可以由不安全的密码管理所致。SSL使用客户端证书来确保只有持有合法证书的客户端才能访问服务器,这样就能阻止这种攻击。 - + + 如果第三方能冒充获授权的客户端,就能直接访问其无权访问的数据。这通常可能由不安全的密码管理导致。SSL 使用客户端证书,确保只有持有有效证书的客户端才能访问服务器,以防范这种攻击。 + - 对于一个已知受 SSL 保护的连接,在连接建立之前,必须在客户端和服务器两端都配置 SSL。如果只在服务器端配置,客户端在得知服务器要求高安全性之前,可能就已经开始发送敏感信息(例如密码)。在 libpq 中,要确保连接安全,可以把sslmode参数设置为verify-fullverify-ca,并为系统提供一个用于验证的根证书。这类似于使用https URL浏览加密网页。 + 要确保连接安全,必须在建立连接之前,在客户端和服务器两端配置 SSL。如果仅在服务器上配置,客户端可能在得知服务器要求高安全性之前就已发送敏感信息(例如密码)。在 libpq 中,可以将 sslmode 参数设为 verify-fullverify-ca,并向系统提供用于验证的根证书,以确保连接安全。这类似于使用 https URL 进行加密的网页浏览。 - 一旦服务器已经被认证,客户端可以传递敏感数据。这意味着直到这一点,客户端都不需要知道是否证书将被用于认证,这样只需要在服务器配置中指定就比较安全。 + 服务器通过身份认证后,客户端便可以传送敏感数据。这意味着,在此之前,客户端无需知道是否会使用证书进行认证,因此可以安全地仅在服务器配置中指定这一点。 - 所有SSL选项都带来了加密和密钥交换的负荷,因此必须在性能和安全性之间做出平衡。不同sslmode值所保护的风险,以及它们是怎样看待安全性和负荷的。 + 所有 SSL 选项都会产生加密和密钥交换的开销,因此必须在性能与安全性之间作出权衡。 说明了不同 sslmode 值所能防范的风险,以及它们所表达的对安全性和开销的取舍。
@@ -5150,7 +5156,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) disable - 我不关心安全性,并且我不想为加密增加负荷。 + 我不关心安全性,并且我不想为加密增加开销。 @@ -5158,7 +5164,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) allow 可能 - 我不关心安全性,但如果服务器坚持,我将承担加密带来的负荷。 + 我不关心安全性,但如果服务器坚持,我将承担加密带来的开销。 @@ -5166,7 +5172,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) prefer 可能 - 我不关心安全性,但如果服务器支持,我希望承担加密带来的负荷。 + 我不关心加密,但如果服务器支持,我希望承担加密带来的开销。 @@ -5174,7 +5180,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) require - 我想要对数据加密,并且我接受因此带来的负荷。我信任该网络会保证我总是连接到想要连接的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我信任该网络会保证我总是连接到想要连接的服务器。 @@ -5182,7 +5188,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-ca 取决于 CA 策略 - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器。 @@ -5190,7 +5196,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-full - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 @@ -5203,7 +5209,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - sslmode的默认值是prefer。如表中所示,这在安全性的角度来说没有意义,并且它只承诺可能的性能负荷。提供它作为默认值只是为了向后兼容,并且我们不推荐在安全部署中使用它。 + sslmode 的默认值是 prefer。如表所示,从安全角度看,这一设置没有意义;它只会在可能时带来性能开销。将其作为默认值仅出于向后兼容的考虑,不建议在有安全要求的部署中使用。 @@ -5245,8 +5251,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) ~/.postgresql/root.crt - 可信的证书机构 - 检查服务器证书是由一个可信的证书机构签发 + 受信任的证书机构 + 检查服务器证书是由一个受信任的证书机构签发 @@ -5264,9 +5270,9 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) SSL 库初始化 - 如果您的应用程序初始化libssl和/或libcrypto库,并且libpq - 构建时带有SSL支持,您应该调用PQinitOpenSSL告诉libpq - libssl和/或libcrypto库已被您的应用程序初始化,以便 + 如果你的应用程序初始化libssl和/或libcrypto库,并且libpq + 构建时带有SSL支持,你应该调用PQinitOpenSSL告诉libpq + libssl和/或libcrypto库已被你的应用程序初始化,以便 libpq不会再初始化这些库。 但是,当使用OpenSSL版本1.1.0或更高版本时,无需这样做,因为重复初始化不再成问题。 @@ -5278,7 +5284,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 允许应用选择要初始化哪个安全性库。 + 允许应用程序选择要初始化的安全库。 void PQinitOpenSSL(int do_ssl, int do_crypto); @@ -5303,7 +5309,7 @@ void PQinitOpenSSL(int do_ssl, int do_crypto); - 允许应用选择要初始化哪个安全性库。 + 允许应用程序选择要初始化的安全库。 void PQinitSSL(int do_ssl); @@ -5328,7 +5334,7 @@ void PQinitSSL(int do_ssl); - 在线程化程序中的行为 + 多线程程序中的行为 线程 @@ -5362,7 +5368,9 @@ int PQisthreadsafe(); PGresult对象在创建后通常是只读的,因此可以在线程之间自由传递。不过,如果你使用中描述的任何会修改PGresult的函数,则需要自行避免对同一个PGresult执行并发操作。 - 已弃用的 PQrequestCancelPQoidStatus 函数不是线程安全的,不应在多线程程序中使用。可以用 PQcancel 替代 PQrequestCancel,用 PQoidValue 替代 PQoidStatus + + 已弃用的函数 PQrequestCancelPQoidStatus 不是线程安全的,不应在多线程程序中使用。PQrequestCancel 可以用 PQcancel 替代;PQoidStatus 可以用 PQoidValue 替代。 + 如果你在应用程序中使用 Kerberos(除了libpq内部之外),则需要在 Kerberos 调用周围加锁,因为 Kerberos 函数不是线程安全的。可参考libpq源代码中的PQregisterThreadLock函数,它提供了一种在libpq与应用程序之间协作加锁的方法。 @@ -5372,7 +5380,7 @@ int PQisthreadsafe(); - 编译 <application>libpq</application> 程序 + 构建 <application>libpq</application> 程序 编译 @@ -5380,16 +5388,16 @@ int PQisthreadsafe(); - 要编译(即编译并且链接)一个使用libpq的程序,你需要做下列所有的事情: + 要构建(即编译和链接)一个使用 libpq 的程序,需要完成以下所有步骤: - 包括libpq-fe.h头文件: + 包含 libpq-fe.h 头文件: #include <libpq-fe.h> - 如果你无法这样做,那么你通常会从你的编译器得到像这样的错误消息: +如果没有这样做,编译器通常会给出类似以下内容的错误消息: foo.c: In function `main': foo.c:34: `PGconn' undeclared (first use in this function) @@ -5398,24 +5406,24 @@ foo.c:54: `CONNECTION_BAD' undeclared (first use in this function) foo.c:68: `PGRES_COMMAND_OK' undeclared (first use in this function) foo.c:95: `PGRES_TUPLES_OK' undeclared (first use in this function) - + - 通过为你的编译器提供-Idirectory选项,向你的编译器指出PostgreSQL头文件安装在哪里(在某些情况下编译器默认将查看该目录,因此你可以忽略这个选项)。例如你的编译命令行可能看起来像: + 向编译器提供 -Idirectory 选项,指定 PostgreSQL 头文件的安装目录。(某些情况下,编译器默认会搜索该目录,此时可以省略这个选项。)例如,编译命令行可以是: cc -c -I/usr/local/pgsql/include testprog.c - 如果你在使用 makefile,那么把该选项加到CPPFLAGS变量中: +如果使用 makefile,请将该选项添加到 CPPFLAGS 变量中: CPPFLAGS += -I/usr/local/pgsql/include - + 如果你的程序可能由其他用户编译,那么你不应该像那样硬编码目录位置。你可以运行工具pg_configpg_configwith libpq在本地系统上找出头文件在哪里: + sortas="libpq">用于 libpq在本地系统上找出头文件在哪里: $ pg_config --includedir /usr/local/include @@ -5423,8 +5431,7 @@ CPPFLAGS += -I/usr/local/pgsql/include - 如果你安装了pkg-configpkg-configwith - libpq,你可以运行: + 如果你安装了pkg-configpkg-config用于 libpq,你可以运行: $ pkg-config --cflags libpq -I/usr/local/include @@ -5433,20 +5440,20 @@ CPPFLAGS += -I/usr/local/pgsql/include - 无法为编译器指定正确的选项将导致一个错误消息,例如: + 未向编译器指定正确的选项将导致类似以下内容的错误消息: testlibpq.c:8:22: libpq-fe.h: No such file or directory - + - 当链接最终的程序时,指定选项-lpq,这样libpq库会被编译进去,也可以用选项-Ldirectory向编译器指出libpq库所在的位置(再次,编译器将默认搜索某些目录)。为了最大的可移植性,将选项放在选项前面。例如: + 链接最终程序时,指定 -lpq 选项以链接 libpq 库,同时指定 -Ldirectory 选项,告知编译器 libpq 库所在的目录。(同样,编译器默认会搜索某些目录。)为获得最大的可移植性,请将 选项放在 选项之前。例如: cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq - + 你也可以使用pg_config找出库目录: @@ -5473,7 +5480,7 @@ testlibpq.o(.text+0x60): undefined reference to `PQsetdbLogin' testlibpq.o(.text+0x71): undefined reference to `PQstatus' testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' - 这意味着你忘了 . + 这意味着你忘记了 /usr/bin/ld: cannot find -lpq @@ -5490,7 +5497,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' 示例程序 - 这些示例和其他示例可以在源代码发布的src/test/examples目录中找到。 + 这些示例和其他示例可在源代码发行包的src/test/examples目录中找到。 @@ -5504,7 +5511,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' * * testlibpq.c * - * Test the C version of libpq, the PostgreSQL frontend library. + * 测试 PostgreSQL 前端库 libpq 的 C 语言版本。 */ #include #include @@ -5528,19 +5535,18 @@ main(int argc, char **argv) j; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "Connection to database failed: %s", @@ -5548,7 +5554,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -5559,19 +5565,17 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Our test case here involves using a cursor, for which we must be inside - * a transaction block. We could do the whole thing with a single - * PQexec() of "select * from pg_database", but that's too trivial to make - * a good example. + * 这里的测试用例使用游标,因此必须处于事务块内。 + * 只需调用一次 PQexec() 执行 "select * from pg_database" 就能完成全部操作, + * 但这太简单了,不足以作为一个好的示例。 */ - /* Start a transaction block */ + /* 开始一个事务块 */ res = PQexec(conn, "BEGIN"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -5582,7 +5586,7 @@ main(int argc, char **argv) PQclear(res); /* - * Fetch rows from pg_database, the system catalog of databases + * 从数据库系统目录 pg_database 中获取行 */ res = PQexec(conn, "DECLARE myportal CURSOR FOR select * from pg_database"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -5601,13 +5605,13 @@ main(int argc, char **argv) exit_nicely(conn); } - /* first, print out the attribute names */ + /* 首先,打印属性名 */ nFields = PQnfields(res); for (i = 0; i < nFields; i++) printf("%-15s", PQfname(res, i)); printf("\n\n"); - /* next, print out the rows */ + /* 接着,打印各行 */ for (i = 0; i < PQntuples(res); i++) { for (j = 0; j < nFields; j++) @@ -5617,15 +5621,15 @@ main(int argc, char **argv) PQclear(res); - /* close the portal ... we don't bother to check for errors ... */ + /* 关闭 portal……这里不再检查错误…… */ res = PQexec(conn, "CLOSE myportal"); PQclear(res); - /* end the transaction */ + /* 结束事务 */ res = PQexec(conn, "END"); PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -5644,15 +5648,15 @@ main(int argc, char **argv) * * * testlibpq2.c - * Test of the asynchronous notification interface + * 测试异步通知接口 * - * Start this program, then from psql in another window do + * 启动此程序,然后在另一个窗口中通过 psql 执行 * NOTIFY TBL2; - * Repeat four times to get this program to exit. + * 重复四次后,此程序便会退出。 * - * Or, if you want to get fancy, try this: - * populate a database with the following commands - * (provided in src/test/examples/testlibpq2.sql): + * 或者,可以尝试更复杂的示例: + * 使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq2.sql 中): * * CREATE SCHEMA TESTLIBPQ2; * SET search_path = TESTLIBPQ2; @@ -5661,7 +5665,7 @@ main(int argc, char **argv) * CREATE RULE r1 AS ON INSERT TO TBL1 DO * (INSERT INTO TBL2 VALUES (new.i); NOTIFY TBL2); * - * Start this program, then from psql do this four times: + * 启动此程序,然后通过 psql 将以下命令执行四次: * * INSERT INTO TESTLIBPQ2.TBL1 VALUES (10); */ @@ -5698,19 +5702,18 @@ main(int argc, char **argv) int nnotifies; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "Connection to database failed: %s", @@ -5718,7 +5721,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -5729,13 +5732,12 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Issue LISTEN command to enable notifications from the rule's NOTIFY. + * 发出 LISTEN 命令,以接收规则中的 NOTIFY 发出的通知。 */ res = PQexec(conn, "LISTEN TBL2"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -5746,14 +5748,13 @@ main(int argc, char **argv) } PQclear(res); - /* Quit after four notifies are received. */ + /* 收到四次通知后退出。 */ nnotifies = 0; while (nnotifies < 4) { /* - * Sleep until something happens on the connection. We use select(2) - * to wait for input, but you could also use poll() or similar - * facilities. + * 休眠,直到连接上有事件发生。这里使用 select(2) 等待输入, + * 也可以使用 poll() 或类似机制。 */ int sock; fd_set input_mask; @@ -5761,7 +5762,7 @@ main(int argc, char **argv) sock = PQsocket(conn); if (sock < 0) - break; /* shouldn't happen */ + break; /* 不应发生 */ FD_ZERO(&input_mask); FD_SET(sock, &input_mask); @@ -5772,7 +5773,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Now check for input */ + /* 现在检查是否有输入 */ PQconsumeInput(conn); while ((notify = PQnotifies(conn)) != NULL) { @@ -5787,7 +5788,7 @@ main(int argc, char **argv) fprintf(stderr, "Done.\n"); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -5806,10 +5807,10 @@ main(int argc, char **argv) * * * testlibpq3.c - * Test out-of-line parameters and binary I/O. + * 测试在 SQL 命令文本之外独立传递的参数和二进制 I/O。 * - * Before running this, populate a database with the following commands - * (provided in src/test/examples/testlibpq3.sql): + * 运行前,使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq3.sql 中): * * CREATE SCHEMA testlibpq3; * SET search_path = testlibpq3; @@ -5817,7 +5818,7 @@ main(int argc, char **argv) * INSERT INTO test1 values (1, 'joe''s place', '\\000\\001\\002\\003\\004'); * INSERT INTO test1 values (2, 'ho there', '\\004\\003\\002\\001\\000'); * - * The expected output is: + * 预期输出为: * * tuple 0: got * i = (4 bytes) 1 @@ -5841,7 +5842,7 @@ main(int argc, char **argv) #include #include "libpq-fe.h" -/* for ntohl/htonl */ +/* 用于 ntohl/htonl */ #include #include @@ -5854,9 +5855,8 @@ exit_nicely(PGconn *conn) } /* - * This function prints a query result that is a binary-format fetch from - * a table defined as in the comment above. We split it out because the - * main() function uses it twice. + * 此函数打印从上面注释所定义的表中以二进制格式获取的查询结果。 + * 由于 main() 会使用它两次,因此将它单独提取成一个函数。 */ static void show_binary_results(PGresult *res) @@ -5867,7 +5867,7 @@ show_binary_results(PGresult *res) t_fnum, b_fnum; - /* Use PQfnumber to avoid assumptions about field order in result */ + /* 使用 PQfnumber,以避免对结果中的字段顺序作出假设 */ i_fnum = PQfnumber(res, "i"); t_fnum = PQfnumber(res, "t"); b_fnum = PQfnumber(res, "b"); @@ -5880,24 +5880,22 @@ show_binary_results(PGresult *res) int blen; int ival; - /* Get the field values (we ignore possibility they are null!) */ + /* 获取字段值(这里忽略它们可能为 null 的情况!) */ iptr = PQgetvalue(res, i, i_fnum); tptr = PQgetvalue(res, i, t_fnum); bptr = PQgetvalue(res, i, b_fnum); /* - * The binary representation of INT4 is in network byte order, which - * we'd better coerce to the local byte order. + * INT4 的二进制表示采用网络字节序,最好将其转换为本机字节序。 */ ival = ntohl(*((uint32_t *) iptr)); /* - * The binary representation of TEXT is, well, text, and since libpq - * was nice enough to append a zero byte to it, it'll work just fine - * as a C string. + * TEXT 的二进制表示就是文本,而 libpq 会在其后追加一个零字节, + * 因此可以直接将其用作 C 字符串。 * - * The binary representation of BYTEA is a bunch of bytes, which could - * include embedded nulls so we have to pay attention to field length. + * BYTEA 的二进制表示是一组字节,其中可能嵌有零字节, + * 因此必须注意字段长度。 */ blen = PQgetlength(res, i, b_fnum); @@ -5925,19 +5923,18 @@ main(int argc, char **argv) uint32_t binaryIntVal; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "Connection to database failed: %s", @@ -5945,7 +5942,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SET search_path = testlibpq3"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -5956,27 +5953,25 @@ main(int argc, char **argv) PQclear(res); /* - * The point of this program is to illustrate use of PQexecParams() with - * out-of-line parameters, as well as binary transmission of data. + * 此程序旨在演示如何使用 PQexecParams() 在 SQL 命令文本之外独立传递参数, + * 以及如何以二进制方式传输数据。 * - * This first example transmits the parameters as text, but receives the - * results in binary format. By using out-of-line parameters we can avoid - * a lot of tedious mucking about with quoting and escaping, even though - * the data is text. Notice how we don't have to do anything special with - * the quote mark in the parameter value. + * 第一个示例以文本形式传输参数,但以二进制格式接收结果。 + * 通过在 SQL 命令文本之外独立传递参数,即使数据是文本,也可以避免 + * 许多繁琐的引号和转义处理。注意,参数值中的引号无需任何特殊处理。 */ - /* Here is our out-of-line parameter value */ + /* 这是在 SQL 命令文本之外独立传递的参数值 */ paramValues[0] = "joe's place"; res = PQexecParams(conn, "SELECT * FROM test1 WHERE t = $1", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, - NULL, /* don't need param lengths since text */ - NULL, /* default to all text params */ - 1); /* ask for binary results */ + NULL, /* 文本参数无需指定长度 */ + NULL, /* 默认所有参数均为文本 */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -5990,31 +5985,29 @@ main(int argc, char **argv) PQclear(res); /* - * In this second example we transmit an integer parameter in binary form, - * and again retrieve the results in binary form. + * 第二个示例以二进制形式传输一个整数参数,并同样以二进制形式获取结果。 * - * Although we tell PQexecParams we are letting the backend deduce - * parameter type, we really force the decision by casting the parameter - * symbol in the query text. This is a good safety measure when sending - * binary parameters. + * 虽然我们告诉 PQexecParams 让后端推断参数类型,但实际上, + * 查询文本中的参数符号经过强制类型转换,因此其类型已经确定。 + * 发送二进制参数时,这是一项良好的安全措施。 */ - /* Convert integer value "2" to network byte order */ + /* 将整数值 "2" 转换为网络字节序 */ binaryIntVal = htonl((uint32_t) 2); - /* Set up parameter arrays for PQexecParams */ + /* 为 PQexecParams 设置参数数组 */ paramValues[0] = (char *) &binaryIntVal; paramLengths[0] = sizeof(binaryIntVal); - paramFormats[0] = 1; /* binary */ + paramFormats[0] = 1; /* 二进制 */ res = PQexecParams(conn, "SELECT * FROM test1 WHERE i = $1::int4", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, paramLengths, paramFormats, - 1); /* ask for binary results */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -6027,7 +6020,7 @@ main(int argc, char **argv) PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; diff --git a/zh/11/lobj.sgml b/zh/11/lobj.sgml index a2edfc51..12f2f107 100644 --- a/zh/11/lobj.sgml +++ b/zh/11/lobj.sgml @@ -3,8 +3,8 @@ 大对象 - large object - BLOBlarge object + 大对象 + BLOB大对象 PostgreSQL提供一种大对象机制,允许以流式方式访问存储在专用大对象结构中的用户数据。在处理大到无法方便地整体操作的数据值时,这种流式访问非常有用。 @@ -19,7 +19,7 @@ TOAST - versus large objects + 与大对象对比 @@ -186,11 +186,11 @@ inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE); int lo_write(PGconn *conn, int fd, const char *buf, size_t len); - 将buf中的len字节(其大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 + 将buf中的len字节(缓冲区大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -207,7 +207,7 @@ int lo_read(PGconn *conn, int fd, char *buf, size_t len); - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -273,7 +273,7 @@ pg_int64 lo_tell64(PGconn *conn, int fd); int lo_truncate(PGconn *conn, int fd, size_t len); - 该函数把大对象描述符fd截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用空字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 + 该函数把大对象描述符fd对应的大对象截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用零字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 @@ -394,16 +394,16 @@ CREATE TABLE image ( raster oid ); -SELECT lo_creat(-1); -- returns OID of new, empty large object +SELECT lo_creat(-1); -- 返回新建的空大对象的 OID -SELECT lo_create(43213); -- attempts to create large object with OID 43213 +SELECT lo_create(43213); -- 尝试创建 OID 为 43213 的大对象 -SELECT lo_unlink(173454); -- deletes large object with OID 173454 +SELECT lo_unlink(173454); -- 删除 OID 为 173454 的大对象 INSERT INTO image (name, raster) VALUES ('beautiful image', lo_import('/etc/motd')); -INSERT INTO image (name, raster) -- same as above, but specify OID to use +INSERT INTO image (name, raster) -- 与上例相同,但指定要使用的 OID VALUES ('beautiful image', lo_import('/etc/motd', 68583)); SELECT lo_export(image.raster, '/tmp/motd') FROM image @@ -412,7 +412,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image - 服务器端的lo_importlo_export函数与其客户端对应函数的行为差异很大。这两个函数在服务器的文件系统中读写文件,使用数据库所有者的权限。因此,默认情况下它们的使用仅限于超级用户。相比之下,客户端导入和导出函数在客户端的文件系统中读写文件,使用客户端程序的权限。客户端函数不需要任何数据库权限,除了读取或写入相关大对象所需的权限。 + 服务器端的lo_importlo_export函数与其客户端对应函数的行为差异很大。这两个函数在服务器的文件系统中读写文件,使用运行数据库服务器的操作系统用户的权限。因此,默认情况下它们的使用仅限于超级用户。相比之下,客户端导入和导出函数在客户端的文件系统中读写文件,使用客户端程序的权限。客户端函数不需要任何数据库权限,除了读取或写入相关大对象所需的权限。 @@ -431,7 +431,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image 示例程序 - 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行版的src/test/examples/testlo.c中找到。 + 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行包的src/test/examples/testlo.c中找到。 @@ -440,13 +440,13 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /*------------------------------------------------------------------------- * * testlo.c - * test using large objects with libpq + * 测试使用 libpq 操作大对象 * * Portions Copyright (c) 1996-2018, PostgreSQL Global Development Group * Portions Copyright (c) 1994, Regents of the University of California * * - * IDENTIFICATION + * 标识 * src/test/examples/testlo.c * *------------------------------------------------------------------------- @@ -466,7 +466,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /* * importFile - - * import file "in_filename" into database as large object "lobjOid" + * 将文件 "in_filename" 作为大对象 "lobjOid" 导入数据库 * */ static Oid @@ -480,16 +480,16 @@ importFile(PGconn *conn, char *filename) int fd; /* - * open the file to be read in + * 打开要读取的文件 */ fd = open(filename, O_RDONLY, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"\n", filename); } /* - * create the large object + * 创建大对象 */ lobjId = lo_creat(conn, INV_READ | INV_WRITE); if (lobjId == 0) @@ -498,7 +498,7 @@ importFile(PGconn *conn, char *filename) lobj_fd = lo_open(conn, lobjId, INV_WRITE); /* - * read in from the Unix file and write to the inversion file + * 从 Unix 文件读取数据并写入大对象 */ while ((nbytes = read(fd, buf, BUFSIZE)) > 0) { @@ -536,7 +536,7 @@ pickout(PGconn *conn, Oid lobjId, int start, int len) fprintf(stderr, ">>> %s", buf); nread += nbytes; if (nbytes <= 0) - break; /* no more data? */ + break; /* 没有更多数据? */ } free(buf); fprintf(stderr, "\n"); @@ -582,7 +582,7 @@ overwrite(PGconn *conn, Oid lobjId, int start, int len) /* * exportFile - - * export large object "lobjOid" to file "out_filename" + * 将大对象 "lobjOid" 导出到文件 "out_filename" * */ static void @@ -595,24 +595,24 @@ exportFile(PGconn *conn, Oid lobjId, char *filename) int fd; /* - * open the large object + * 打开大对象 */ lobj_fd = lo_open(conn, lobjId, INV_READ); if (lobj_fd < 0) fprintf(stderr, "cannot open large object %u", lobjId); /* - * open the file to be written to + * 打开要写入的文件 */ fd = open(filename, O_CREAT | O_WRONLY | O_TRUNC, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"", filename); } /* - * read in from the inversion file and write to the Unix file + * 从大对象读取数据并写入 Unix 文件 */ while ((nbytes = lo_read(conn, lobj_fd, buf, BUFSIZE)) > 0) { @@ -659,11 +659,11 @@ main(int argc, char **argv) out_filename = argv[3]; /* - * set up the connection + * 建立连接 */ conn = PQsetdb(NULL, NULL, NULL, NULL, database); - /* check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "Connection to database failed: %s", @@ -671,7 +671,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) diff --git a/zh/11/pgtrgm.sgml b/zh/11/pgtrgm.sgml index edf12a49..e7d83b21 100644 --- a/zh/11/pgtrgm.sgml +++ b/zh/11/pgtrgm.sgml @@ -339,11 +339,11 @@ SELECT * FROM test_trgm WHERE t ~ '(foo|bar)'; - 文本搜索集成 + 文本检索集成 与全文索引结合使用时,三字符组匹配是非常有用的工具。 - 尤其是,它有助于识别那些因拼写错误而无法被全文搜索机制直接匹配的输入词。 + 尤其是,它有助于识别那些因拼写错误而无法被全文检索机制直接匹配的输入词。 diff --git a/zh/11/protocol.sgml b/zh/11/protocol.sgml index 097ac8e6..36b07c84 100644 --- a/zh/11/protocol.sgml +++ b/zh/11/protocol.sgml @@ -33,7 +33,7 @@ - 会话通常由前端选择终止,但在某些情况下也可能由后端强制终止。无论哪种情况,后端在关闭连接前都会回滚所有打开的(未完成的)事务。 + 会话通常由前端选择终止,但在某些情况下也可能由后端强制终止。无论哪种情况,后端关闭连接时,都会在退出前回滚所有打开的(未完成的)事务。 @@ -72,9 +72,7 @@ 整个执行周期包括一个解析步骤,它从文本查询字符串创建预备语句; 一个绑定步骤,它根据预备语句和所需参数值创建 portal; - 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询 - (SELECTSHOW等),可以要求执行步骤只取回 - 有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 + 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询(SELECTSHOW等),可以要求执行步骤只取回有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 @@ -91,8 +89,8 @@ - 文本形式的数值是特定数据类型的输入/输出转换函数生成或接受的任何字符串。在传输形式上,字符串没有末尾空字符;如果前端要想把收到的值当作C字符串处理,那么必须自己加上一个(顺便说一下,文本格式不允许嵌入空字符)。 - + 值的文本表示是相应数据类型的输入/输出转换函数生成和接受的字符串。在传输形式中,值的末尾没有空字符;前端若要将收到的值作为 C 字符串处理,必须自行添加一个。(文本格式也不允许内嵌空字符。) + 整数的二进制表示采用网络字节序(最高有效字节在前)。至于其他数据类型,请查阅文档或源代码了解其二进制表示形式。要注意,复杂数据类型的二进制表示可能会在不同服务器版本之间发生变化;文本格式通常是可移植性更好的选择。 @@ -112,7 +110,7 @@ 启动 - 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,判断该连接在初步上是否可接受,以及是否需要额外的认证。 + 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,初步判断是否接受该连接,以及需要何种额外认证(如果需要)。 @@ -355,7 +353,7 @@ 表示即将返回行作为对SELECTFETCH等查询的响应。 - 此消息的内容描述了行的列布局。这将跟随每个返回给前端的行的DataRow消息。 + 此消息的内容描述了行的列布局。该消息之后,每个返回给前端的行都对应一条 DataRow 消息。 @@ -434,14 +432,14 @@ - 我们建议的方法是把前端代码写成状态机的风格,它可以在任何时刻接受任何有意义的消息类型,而不是假设消息的序列总是准确。 - + 建议以状态机的方式编写前端,使其能够在任何合理的时机接收相应类型的消息,而不把消息确切顺序的假设写死在代码中。 + 一个简单查询中的多条语句 - 当一个简单查询消息中包含多于一条SQL语句(被分号分隔)时,那些语句会被当做一个事务中执行,除非其中包括显式事务控制命令来强制不同的行为。例如,如果消息包括 + 当一个简单查询消息中包含多于一条SQL语句(被分号分隔)时,这些语句会作为单个事务执行,除非其中包括显式事务控制命令来强制不同的行为。例如,如果消息包括 INSERT INTO mytable VALUES(1); SELECT 1/0; @@ -463,15 +461,15 @@ SELECT 1/0; - 这种行为通过在一个隐式事务块中的一个多语句Query消息中运行那些语句来实现,除非它们运行在某个显式事务块中。隐式事务块与常规事务块之间的区别在于隐式块会在Query消息结束时自动被关闭,或者是在没有错误的情况下由一个隐式提交关闭,或者是在有错误时由一个隐式的回滚关闭。这类似于一个语句自己执行(当不在事务块中时)时发生的隐式提交或回滚。 - + 这种行为的实现方式是:除非已有显式事务块可供这些语句执行,否则就在一个隐式事务块中执行多语句 Query 消息中的语句。隐式事务块与常规事务块的主要区别在于,隐式块会在 Query 消息结束时自动关闭:没有错误时隐式提交,发生错误时隐式回滚。这类似于单独执行一条语句(不在事务块中)时发生的隐式提交或回滚。 + - 如果会话已经在一个事务块中,作为前面某个消息中BEGIN的结果,那么Query消息会简单地继续那个事务块,不管该消息包含一个语句还是多个语句。不过,如果该Query消息包含一个关闭现有事务块的COMMIT或者ROLLBACK,那么任何接下来的语句都会在一个隐式事务块中被执行。反过来,如果在多语句Query消息中出现一个BEGIN,那么它会开始一个常规事务块,这个常规事务块将只能被一个显式的COMMIT或者ROLLBACK终止,不管这两种命令是出现在这个Query消息还是后面的一个Query消息中。如果BEGIN跟在一些作为隐式事务块执行的语句后面,那些语句不会被立刻提交。实际上,它们会被包括到新的常规事务块中。 + 如果会话因前面某条消息中的BEGIN而已经处于事务块中,那么 Query 消息会继续该事务块,不管该消息包含一个语句还是多个语句。不过,如果该Query消息包含一个关闭现有事务块的COMMIT或者ROLLBACK,那么任何接下来的语句都会在一个隐式事务块中被执行。反过来,如果在多语句Query消息中出现一个BEGIN,那么它会开始一个常规事务块,这个常规事务块将只能被一个显式的COMMIT或者ROLLBACK终止,不管这两种命令是出现在这个Query消息还是后面的一个Query消息中。如果BEGIN跟在一些作为隐式事务块执行的语句后面,那些语句不会被立刻提交。实际上,它们会被包括到新的常规事务块中。 - 出现在一个隐式事务块中的COMMIT或者ROLLBACK会被正常执行并且关闭该隐式块。不过,由于没有先前的BEGIN配对的COMMIT或者ROLLBACK表示一种错误,所以将会发出一个警告。如果后面还有更多语句,将会为它们开始一个新的隐式事务块。 + 出现在一个隐式事务块中的COMMIT或者ROLLBACK会被正常执行并且关闭该隐式块。不过,由于没有先前的BEGIN配对的COMMIT或者ROLLBACK可能表示误操作,所以会发出警告。如果后面还有更多语句,将会为它们开始一个新的隐式事务块。 @@ -479,23 +477,23 @@ SELECT 1/0; - 记住,不管任何事务控制命令存不存在,Query消息的执行会在第一个错误时停止。因此,对于下面的在一个Query消息中的示例 + 请记住,无论消息中是否包含事务控制命令,Query 消息的执行都会在第一个错误处停止。例如,单条 Query 消息包含以下内容时: BEGIN; SELECT 1/0; ROLLBACK; - 会话中将留下一个失败的常规事务块,因为在出现除零错误后不会到达ROLLBACK。将需要另一个ROLLBACK把会话恢复到一种可用的状态。 - +会话会停留在失败的常规事务块内,因为发生除零错误后不会再执行ROLLBACK。需要另发一条ROLLBACK,才能将会话恢复到可用状态。 + - 另一种要注意的行为是,最初的词法和语法分析是在整个查询字符串被执行之前进行的。因此后面的语句中的简单错误(例如拼写错误的关键词)可能会阻止任何语句的执行。这通常对用户是不可见的,因为在当作一个隐式事务块执行时,这些语句不管怎样都会全部被回滚。不过,在尝试于一个多语句Query中执行多个事务时,这种现象可能是可见的。例如,如果一个拼写错误把我们之前的示例变成 + 另一种要注意的行为是,在执行任何语句之前,会先对整个查询字符串进行词法和语法分析。因此后面的语句中的简单错误(例如拼写错误的关键词)可能会阻止任何语句的执行。这通常对用户是不可见的,因为在当作一个隐式事务块执行时,这些语句不管怎样都会全部被回滚。不过,在尝试于一个多语句Query中执行多个事务时,这种现象可能是可见的。例如,如果一个拼写错误把我们之前的示例变成 BEGIN; INSERT INTO mytable VALUES(1); COMMIT; INSERT INTO mytable VALUES(2); -SELCT 1/0; +SELCT 1/0; 那么这些语句都不会被运行,导致可见的差别,即第一个INSERT没有被提交。在语义分析及其后阶段检测到的错误(例如拼错的表名或者列名)不会有这种效果。 @@ -552,11 +550,11 @@ SELCT 1/0; - 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是执行不会导致后端发送 ReadyForQuery 或 RowDescription。 + 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是 Execute 不会导致后端发送 ReadyForQuery 或 RowDescription。 - 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息之一结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 + 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息中的恰好一条结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 @@ -571,7 +569,7 @@ SELCT 1/0; - 除了这些基本的、必须的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 + 除了这些基本的、必需的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 @@ -607,46 +605,40 @@ SELCT 1/0; - 流水线处理 + 管道化 - 流水线处理 + 管道化 协议规范 - 使用扩展查询协议允许流水线处理,这意味着发送一系列查询而无需等待先前的查询完成。 - 这减少了完成一系列操作所需的网络往返次数。然而,用户必须仔细考虑所需的行为,如果其中一步失败, - 因为后续查询已经在传输到服务器的过程中。 - + 扩展查询协议允许管道化,即连续发送一系列查询,而不等待先前查询完成。这减少了完成一组操作所需的网络往返次数。不过,用户必须仔细考虑其中某个步骤失败时所需的行为,因为后续查询已经在发往服务器的途中。 + - 处理这个问题的一种方法是将整个查询系列作为一个事务处理,即将其包装在BEGIN... - COMMIT中。然而,如果希望其中一些命令独立于其他命令提交,这并没有帮助。 - + 处理这个问题的一种方式是让整组查询成为单个事务,即用BEGIN ... COMMIT包围它们。不过,如果希望其中某些命令独立于其他命令提交,这种方式就无法满足要求。 + - 扩展查询协议提供了另一种管理这个问题的方式,即在依赖的步骤之间省略发送同步消息。 - 由于在错误后,后端会跳过命令消息直到找到同步消息,这允许在管道中的后续命令在前面的命令失败时自动跳过,而无需客户端明确地使用BEGINCOMMIT来管理。 - 管道中可以通过同步消息分隔独立可提交的段。 - + 扩展查询协议提供了另一种处理方式,即省略相互依赖的步骤之间的 Sync 消息。发生错误后,后端会跳过命令消息,直到遇到 Sync,因此当前面的命令失败时,管道中的后续命令便会自动跳过,而不必由客户端用BEGINCOMMIT显式管理。管道中可独立提交的各段可以用 Sync 消息分隔。 + - 如果客户端没有发出显式 BEGIN,则会启动一个隐式事务块。每个 Sync 通常会在前序步骤成功时导致隐式 COMMIT,失败时导致隐式 ROLLBACK。服务器只有在第一个命令结束且尚未收到 Sync 时,才能识别这种隐式事务块。有一些 DDL 命令(例如 CREATE DATABASE)不能在事务块内执行;若这类命令在管道中执行,除非它是某个 Sync 之后的第一条命令,否则会失败。此外,它成功后会强制立即提交以保持数据库一致性。因此,紧随这些命令之后的 Sync 除了返回 ReadyForQuery 外不会产生额外效果。 - + 如果客户端没有发出显式的BEGIN,那么每个 Sync 通常会在前序步骤成功时引发隐式的COMMIT,失败时引发隐式的ROLLBACK。不过,少数 DDL 命令(例如CREATE DATABASE)不能在事务块中执行。如果这类命令在管道中执行,除非它是管道中的第一条命令,否则会失败。此外,它成功后会强制立即提交,以保持数据库一致性。因此,紧随这类命令之后的 Sync 除了返回 ReadyForQuery 外,不产生其他效果。 + - 当使用这种方法时,必须通过计算ReadyForQuery消息的数量并等待达到发送的Syncs数量来确定管道的完成。 - 计算命令完成响应是不可靠的,因为其中一些命令可能会被跳过,因此不会产生完成消息。 - + 使用这种方式时,必须统计 ReadyForQuery 消息的数量,并等待该数量达到已发送的 Sync 消息数量,才能确定管道已完成。统计命令完成响应并不可靠,因为某些命令可能被跳过,因而不会产生完成消息。 + 函数调用 - 函数调用子协议允许客户端请求一个对存在于数据库pg_proc系统表中的任意函数的直接调用。客户端必须在该函数上有执行的权限。 - + 函数调用子协议允许客户端请求直接调用数据库pg_proc系统目录中的任意函数。客户端必须具有该函数的执行权限。 + @@ -656,8 +648,8 @@ SELCT 1/0; - 一个函数调用周期是由前端向后端发送一条FunctionCall消息初始化的。然后后端根据函数调用的结果发送一条或者更多响应消息,并且最后是一条ReadyForQuery响应消息。ReadyForQuery通知前端它可以安全地发送一个新的查询或者函数调用了。 - + 函数调用周期由前端向后端发送一条 FunctionCall 消息来启动。后端随后根据函数调用的结果发送一条或多条响应消息,最后发送一条 ReadyForQuery 响应消息。ReadyForQuery 告知前端,可以安全地发送新的查询或函数调用。 + 来自后端的可能的响应消息是: @@ -676,7 +668,7 @@ SELCT 1/0; FunctionCallResponse - 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者集合类型的结果)。 + 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者结果集合)。 @@ -710,7 +702,7 @@ SELCT 1/0; - 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(表示成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 + 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(允许成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 @@ -718,11 +710,11 @@ SELCT 1/0; - 在拷贝入模式下,后端将忽略所收到的Flush和Sync消息。收到任何其他非拷贝消息类型都会造成一个错误,它将导致上面所描述的拷贝入状态中断(Flush和Sync的例外是为了方便客户端库,它们总是在一个Execute消息之后发送Flush和Sync,而不检查被执行的命令是否为一个COPY FROM STDIN)。 - + 后端会忽略在拷贝入模式期间收到的 Flush 和 Sync 消息。收到任何其他非拷贝类型的消息都会构成错误,并按上述方式中止拷贝入状态。(Flush 和 Sync 的例外是为了方便那些总是在 Execute 消息之后发送 Flush 或 Sync、而不检查待执行命令是否为COPY FROM STDIN的客户端库。) + - 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句的时候初始化的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能退出传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 + 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句时启动的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能中止传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 @@ -730,16 +722,16 @@ SELCT 1/0; - 在CopyData消息中间可能会散布有NoticeResponse和ParameterStatus消息。前端必须处理这些情况,并且应该也为异步消息类型(参见)准备好。除此之外,可以将任何除 CopyData 或 CopyDone 以外的消息类型视为拷贝出模式的终止标志。 - + NoticeResponse 和 ParameterStatus 消息可能穿插在 CopyData 消息之间;前端必须处理这些情况,并应准备好处理其他异步消息类型(参见)。除此之外,可以将任何除 CopyData 或 CopyDone 以外的消息类型视为拷贝出模式的终止标志。 + - 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许数据以高速批量方式在客户端与服务器之间双向传输。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见。 + 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许高速批量地向服务器发送数据以及从服务器接收数据。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见 - CopyInResponse、CopyOutResponse和CopyBothResponse消息包括域和格式代码,域告诉前端每行的列数,而格式代码则用于具体每个列(就目前的实现而言,一个给定COPY操作中的所有列都将使用同样的格式,但是消息设计并不做这个假设)。 - + CopyInResponse、CopyOutResponse 和 CopyBothResponse 消息包含一些字段,用于告知前端每行的列数以及每列所使用的格式代码。(在当前实现中,同一次COPY操作的所有列都使用相同格式,但消息设计并不作此假设。) + @@ -766,8 +758,8 @@ SELCT 1/0; - 如果前端发出一个LISTEN命令, 那么无论何时在为同一个通道名NOTIFY时,后端将发送一个NotificationResponse消息(不要和NoticeResponse搞混!)。 - + 如果前端发出LISTEN命令,那么每当针对同一通道名执行NOTIFY命令时,后端都会发送一条 NotificationResponse 消息(不要与 NoticeResponse 混淆)。 + @@ -785,11 +777,11 @@ SELCT 1/0; - 要发出一条取消请求,前端打开一个与服务器的新连接并且发送一条CancelRequest消息, 而不是通常在新连接中经常发送的StartupMessage消息。服务器将处理这个请求然后关闭连接。 出于安全原因,对取消请求消息不做直接的响应。 - + 要发出取消请求,前端会新建到服务器的连接,并发送 CancelRequest 消息,而不是新连接通常发送的 StartupMessage 消息。服务器处理该请求后便会关闭连接。出于安全原因,服务器不会直接回复取消请求消息。 + - 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的关键数据(PID和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则退出当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 + 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的密钥数据(PID 和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则中止当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 @@ -797,7 +789,7 @@ SELCT 1/0; - 这么做是对安全性和有效性通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 + 这么做是对安全性和效率通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 @@ -817,11 +809,11 @@ SELCT 1/0; - 其他终止场景来自各种故障,例如任一端发生内核转储、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 + 其他终止场景来自各种故障,例如任一端发生 core dump、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 - 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果很可能在得知断开之前被提交。 + 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果可能在发现连接断开之前被提交。 @@ -837,12 +829,16 @@ SELCT 1/0; 前端还应准备好处理服务器对 SSLRequest 返回的 ErrorMessage 响应。只有当服务器版本早于 PostgreSQL 引入 SSL 支持时,才会发生这种情况。(这样的服务器已经非常古老,现实中可能已不存在。)此时必须关闭连接,但前端可以选择建立一个新连接,并在不请求 SSL 的情况下继续通信。 - 当可以执行 SSL 加密时,服务器预计仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给他们的 SSL 库,要么在发现他们已经读取到额外的字节时将其视为协议违规。 + 当可以执行 SSL 加密时,服务器应仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给所用的 SSL 库,要么在发现已经读取到额外的字节时将其视为协议违规。 - 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 SSLRequest。 + + 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 SSLRequest。 + - 虽然协议本身没有提供让服务器强制使用 SSL 加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + + 虽然协议本身没有提供让服务器强制使用SSL加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + @@ -864,24 +860,21 @@ SELCT 1/0; - 客户端从列表中选择一个支持的机制,并向服务器发送一个SASLInitialResponse消息。 - 该消息包括所选机制的名称,以及如果所选机制使用的话,还包括一个可选的初始客户端响应。 - + 客户端从列表中选择一种受支持的机制,并向服务器发送 SASLInitialResponse 消息。消息包含所选机制的名称;如果该机制使用初始客户端响应,消息还可以包含这一可选响应。 + - 一个或多个服务器挑战和客户端响应消息将随后而来。每个服务器挑战都是在一个 - AuthenticationSASLContinue 消息中发送的,随后是客户端在一个 SASLResponse - 消息中的响应。这些消息的具体内容是特定于机制的。 - + 随后会进行一轮或多轮服务器挑战和客户端响应。每次服务器挑战都通过 AuthenticationSASLContinue 消息发送,随后客户端通过 SASLResponse 消息响应。消息的具体内容取决于所用机制。 + - 最后,当认证交换成功完成时,服务器会发送可选的 AuthenticationSASLFinal 消息,随后立即发送 AuthenticationOk。AuthenticationSASLFinal 包含机制特定的附加数据;若该机制不需要完成时附加数据,则不会发送 AuthenticationSASLFinal。 - + 最后,认证交换成功完成时,服务器会发送 AuthenticationSASLFinal 消息,紧接着发送 AuthenticationOk 消息。AuthenticationSASLFinal 包含从服务器发给客户端的附加数据,其具体内容取决于所选认证机制。如果该认证机制不使用在完成时发送的附加数据,则不会发送 AuthenticationSASLFinal 消息。 + @@ -901,31 +894,22 @@ SELCT 1/0; - SCRAM规范规定密码也必须是UTF-8编码,并且使用SASLprep算法处理。 - 然而,PostgreSQL不要求密码必须使用UTF-8编码。 - 当用户设置密码时,无论实际使用的编码是什么,都会像使用UTF-8一样使用SASLprep进行处理。 - 但是,如果密码不是合法的UTF-8字节序列,或者包含SASLprep算法禁止的UTF-8字节序列, - 则会使用原始密码而不进行SASLprep处理,而不是抛出错误。这样可以在密码为UTF-8时对其进行规范化, - 但仍允许使用非UTF-8密码,并且不需要系统知道密码使用的编码方式。 - + SCRAM 规范规定密码也必须采用 UTF-8 编码,并通过SASLprep算法处理。不过,PostgreSQL并不要求密码使用 UTF-8。设置用户密码时,无论实际采用何种编码,都会将其视作 UTF-8 并用 SASLprep 处理。但是,如果密码不是合法的 UTF-8 字节序列,或者包含 SASLprep 算法禁止的 UTF-8 字节序列,就会直接使用未经 SASLprep 处理的原始密码,而不抛出错误。这样既能对 UTF-8 密码进行规范化,又允许使用非 UTF-8 密码,而且不要求系统知道密码采用何种编码。 + - Channel binding在支持SSL的PostgreSQL构建中受支持。带有通道绑定的SCRAM的SASL机制名称是 + 通道绑定在支持SSL的PostgreSQL构建中受支持。带有通道绑定的SCRAM的SASL机制名称是 SCRAM-SHA-256-PLUS。PostgreSQL使用的通道绑定类型是 tls-server-end-point - 在没有通道绑定的SCRAM中,服务器选择一个随机数, - 传输给客户端,与用户提供的密码在传输的密码哈希中混合。虽然这可以 - 防止密码哈希在后续会话中被成功重新传输,但无法阻止真实服务器和客 - 户端之间的虚假服务器通过服务器的随机值并成功进行认证。 - + 在不带通道绑定的SCRAM中,服务器会选择一个随机数并发送给客户端,将它与用户提供的密码混合,形成所传输的密码 hash。虽然这样可以防止在后续会话中成功重放该密码 hash,但无法阻止位于真实服务器与客户端之间的伪造服务器转发服务器的随机值并成功通过认证。 + - SCRAM与通道绑定一起防止这种中间人攻击,通过将服务器证书的签名混合到传输的密码哈希中。 - 虽然伪造服务器可以重新传输真实服务器的证书,但它无法访问与该证书匹配的私钥,因此无法证明自己是所有者,导致SSL连接失败。 - + 带通道绑定的SCRAM会将服务器证书的签名混入所传输的密码 hash,从而防止此类中间人攻击。虽然伪造服务器可以转发真实服务器的证书,但它无法取得与证书匹配的私钥,因此无法证明自己是证书所有者,最终导致 SSL 连接失败。 + @@ -994,21 +978,27 @@ SELCT 1/0; 无论是物理复制还是逻辑复制的 walsender 模式,都只能使用简单查询协议。 -为了测试复制命令,可以通过psql或其他使用libpq的工具建立复制连接,连接字符串中应包含replication选项,例如: + + 为了测试复制命令,可以通过 psql 或其他使用 libpq 的工具建立复制连接,连接字符串中应包含 replication 选项,例如: + psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" -不过,通常更有用的做法是使用(用于物理复制)或(用于逻辑复制)。 + +不过,通常更有用的做法是使用 (用于物理复制)或 (用于逻辑复制)。 + - 复制命令在服务器日志中记录,当启用时。 + 启用 后,复制命令会记录到服务器日志中。 复制模式接受以下命令: IDENTIFY_SYSTEM - 识别系统 + IDENTIFY_SYSTEM - 请求服务器标识自身。服务器返回一个只有一行的结果集,包含四个字段: + + 请求服务器标识自身。服务器会返回一个包含四个字段的单行结果集: + @@ -1017,7 +1007,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" systemid (text) - 标识数据库集簇的唯一系统标识符。可用于检查初始化备库的基础备份是否来自同一个数据库集簇。 + + 用于标识该集簇的唯一系统标识符。它可用于检查初始化备库所用的基础备份是否来自同一个集簇。 + @@ -1042,7 +1034,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" dbname (text) - 所连接的数据库,或 null。 + + 当前连接到的数据库,或为 null。 + @@ -1101,7 +1095,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" content (bytea) - 时间线历史文件的内容。 + + 时间线历史文件的内容。 + @@ -1208,22 +1204,16 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" START_REPLICATION [ SLOT slot_name ] [ PHYSICAL ] XXX/XXX [ TIMELINE tli ] - 开始复制 + START_REPLICATION - 指示服务器开始流式传输WAL,从WAL位置XXX/XXX开始。 - 如果指定了TIMELINE选项,则流式传输将从时间线tli开始; - 否则,将选择服务器当前的时间线。如果请求的WAL部分已经被回收,服务器可能会回复错误。 - 成功时,服务器将用CopyBothResponse消息回复,然后开始向前端流式传输WAL。 - + 指示服务器从 WAL 位置 XXX/XXX 开始流式传输 WAL。如果指定了 TIMELINE 选项,则从时间线 tli 开始传输;否则选择服务器当前的时间线。服务器可以返回错误,例如请求的 WAL 部分已被回收时。成功时,服务器返回 CopyBothResponse 消息,然后开始向前端流式传输 WAL。 + - 如果通过slot_name提供了复制槽名称, - 那么在复制进行期间会更新该复制槽,以便服务器知道哪些 WAL 段, - 以及在启用了 hot_standby_feedback 时,哪些事务 - 仍然被备库所需要。 - + 如果通过 slot_name 提供了复制槽名称,该复制槽会随着复制的进行而更新,使服务器知道备库仍需要哪些 WAL 段,以及在启用 hot_standby_feedback 时仍需要哪些事务。 + 如果客户端请求的时间线不是最新时间线,但属于服务器的历史,服务器会从请求的起点开始,流式传输该时间线上的所有 WAL,直到服务器切换到另一条时间线的位置。如果客户端请求的流式传输起点恰好位于旧时间线的末尾,服务器会立即返回 CommandComplete,而不进入 COPY 模式。 @@ -1474,7 +1464,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" DROP_REPLICATION_SLOT slot_name WAIT - 删除复制槽 + DROP_REPLICATION_SLOT 删除复制槽,释放任何保留的服务器端资源。如果该槽是逻辑槽,且创建它的数据库与 walsender 当前连接的数据库不同,则此命令失败。 @@ -1516,9 +1506,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 设置备份的标签。如果未指定,则将使用base backup作为备份标签。 - 标签的引号使用规则与打开的标准SQL字符串相同。 - + 设置备份标签。如果未指定,则使用 base backup 作为备份标签。标签的引号规则与启用 时的标准 SQL 字符串相同。 + @@ -1618,7 +1607,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" size (int8) - 如果请求了进度报告,则为表空间的大致大小;否则为空值。 + + 如果请求了进度报告,则为表空间的大致大小;否则为 null。 + @@ -1682,7 +1673,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 逻辑复制协议 + 逻辑流复制协议 本节介绍逻辑复制协议,它是一种以复制命令START_REPLICATION @@ -1691,7 +1682,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 逻辑复制协议构建在物理流复制协议的底层机制之上。 + 逻辑流复制协议构建在物理流复制协议的基本机制之上。 @@ -1746,7 +1737,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 逻辑复制协议逐个发送事务。这意味着,一对 Begin 和 Commit 消息之间的所有消息都属于同一个事务。 - 每个被发送的事务都包含零条或多条 DML 消息(插入、更新、删除)。在级联场景下,它还会包含 Origin 消息。Origin 消息表示该事务产生于另一个复制节点。由于逻辑复制协议中的复制节点可以是任意实现,因此唯一标识符就是该源头的名称。下游是否以及如何处理这一信息,由其自行决定。Origin 消息总是在事务中的任何 DML 消息之前发送。 + 每个发送的事务都包含零条或多条 DML 消息(Insert、Update、Delete)。在级联配置中,还可能包含 Origin 消息。Origin 消息表示该事务源自另一个复制节点。由于逻辑复制协议中的复制节点几乎可以是任何实现,因此唯一的标识符就是复制源的名称。下游负责按需处理这一信息(如果需要处理)。Origin 消息总是在事务中的任何 DML 消息之前发送。 @@ -1811,9 +1802,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 对后端返回的字符串长度,没有预定义的限制。 - 前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。 - 如果做不到这一点,就应读取完整字符串,并丢弃不适合固定大小缓冲区的尾随字符。 + 后端返回的字符串长度没有预定义的限制。前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。如果做不到这一点,就应读取完整字符串,并丢弃固定大小的缓冲区容纳不下的尾随字符。 @@ -1838,8 +1827,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 消息格式 - 本节描述每条消息的详细格式。每条消息都标记了可由前端(F)、后端(B)或双方(F&B)发送。 - 请注意,虽然每条消息开头都带有字节计数,但大多数消息格式都定义为无需参考该计数也能确定消息边界。这一设计最初是出于历史原因(早期已废弃的协议 v2 没有显式长度字段),同时也有助于有效性校验。 + 本节描述每条消息的详细格式。每条消息都标明它可以由前端(F)、后端(B)或双方(F & B)发送。注意,虽然每条消息开头都有字节计数,但消息格式的定义使得无需参考该计数也能确定消息的结束位置。这有助于检查消息的有效性。(CopyData 消息是例外,因为它构成数据流的一部分,任何单条 CopyData 消息的内容都无法独立解释。) @@ -1860,7 +1848,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -1891,7 +1879,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -1921,7 +1909,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -1951,7 +1939,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(12) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -1988,7 +1976,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2019,7 +2007,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2050,7 +2038,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2081,7 +2069,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2118,7 +2106,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2156,7 +2144,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2193,7 +2181,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2230,7 +2218,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(12) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2267,7 +2255,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2285,13 +2273,13 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int16 -后续参数格式码的数量(下文以 C 表示)。可以为零,表示没有参数,或者所有参数都使用默认格式(文本);也可以为一,此时指定的格式码应用于所有参数;还可以等于实际参数数量。 +后续参数格式代码的数量(下文以 C 表示)。可以为零,表示没有参数,或者所有参数都使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有参数;还可以等于实际参数数量。 Int16[C] -参数格式码。目前每个格式码必须为零(文本)或一(二进制)。 +参数格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -2310,20 +2298,20 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byten -参数值,格式由对应的格式码指明。n 为上述长度。 +参数值,格式由对应的格式代码指明。n 为上述长度。 最后一个参数之后是以下字段: Int16 -后续结果列格式码的数量(下文以 R 表示)。可以为零,表示没有结果列,或者所有结果列都应使用默认格式(文本);也可以为一,此时指定的格式码应用于所有结果列(如果有);还可以等于查询实际的结果列数量。 +后续结果列格式代码的数量(下文以 R 表示)。可以为零,表示没有结果列,或者所有结果列都应使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有结果列(如果有);还可以等于查询实际的结果列数量。 Int16[R] -结果列格式码。目前每个格式码必须为零(文本)或一(二进制)。 +结果列格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -2347,7 +2335,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2371,7 +2359,7 @@ CancelRequest (F) - 消息内容的长度,以字节为单位,包括此长度字段本身。 + 消息内容的长度(以字节为单位),包括其自身。 @@ -2427,7 +2415,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2463,7 +2451,7 @@ CancelRequest (F) Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2488,7 +2476,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2552,7 +2540,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2589,7 +2577,7 @@ CancelRequest (F) Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2618,7 +2606,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2647,13 +2635,13 @@ CancelRequest (F) Byte1('G') -标识消息为开始复制输入的响应。前端此时必须发送复制输入数据(如果尚未准备好,应发送 CopyFail 消息)。 +将该消息标识为开始 COPY 输入的响应。前端此时必须发送 COPY 输入数据(如果尚未准备好,应发送 CopyFail 消息)。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2702,13 +2690,13 @@ CancelRequest (F) Byte1('H') -标识消息为开始复制输出的响应。该消息之后会发送复制输出数据。 +将该消息标识为开始 COPY 输出的响应。此消息之后会发送 COPY 输出数据。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2757,13 +2745,13 @@ CancelRequest (F) Byte1('W') -标识消息为开始双向复制的响应。此消息仅用于流复制。 +将该消息标识为开始双向 COPY 的响应。此消息仅用于流复制。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2819,7 +2807,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2834,7 +2822,7 @@ CancelRequest (F) Int32 -列值的长度,以字节为单位(不包括本长度字段自身)。可以为零。特殊值 -1 表示列值为 NULL,此时后面没有值字节。 +列值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 列值。为 NULL 时,后面不再有值的字节。 @@ -2865,14 +2853,14 @@ CancelRequest (F) - 标识消息为描述命令。 + 将该消息标识为 Describe 命令。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2915,7 +2903,7 @@ CancelRequest (F) Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2944,7 +2932,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -2983,14 +2971,14 @@ CancelRequest (F) - 标识消息为一个执行命令。 + 将该消息标识为 Execute 命令。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3025,14 +3013,14 @@ CancelRequest (F) - 将消息标识为Flush命令。 + 将该消息标识为 Flush 命令。 Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3061,7 +3049,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3094,7 +3082,7 @@ CancelRequest (F) Int32 -参数值的长度,以字节为单位(不包括本长度字段自身)。可以为零。特殊值 -1 表示参数值为 NULL,此时后面没有值字节。 +参数值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 参数值。为 NULL 时,后面不再有值的字节。 @@ -3139,13 +3127,13 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 Int32 -函数结果值的长度,以字节为单位(不包括本长度字段自身)。可以为零。特殊值 -1 表示函数结果为 NULL,此时后面没有值字节。 +函数结果值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 函数结果。为 NULL 时,后面不再有值的字节。 @@ -3184,7 +3172,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3219,7 +3207,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3267,7 +3255,7 @@ CancelRequest (F) Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3296,7 +3284,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -3342,7 +3330,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3360,7 +3348,7 @@ CancelRequest (F) String -通知进程传来的载荷字符串。 +通知进程传来的有效载荷字符串。 @@ -3389,7 +3377,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3432,7 +3420,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3465,14 +3453,14 @@ CancelRequest (F) - 将消息标识为解析命令。 + 将该消息标识为 Parse 命令。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3521,14 +3509,14 @@ CancelRequest (F) - 将消息标识为解析完成指示器。 + 将该消息标识为 Parse 完成指示。 Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3558,7 +3546,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3587,15 +3575,14 @@ CancelRequest (F) - 标识消息为 portal 挂起指示器。 - 请注意,仅当执行消息的行数限制达到时才会出现此消息。 + 将该消息标识为 portal 挂起指示。注意,仅当达到 Execute 消息指定的行数限制时,才会出现此消息。 Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3624,7 +3611,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3661,7 +3648,7 @@ CancelRequest (F) Int32(5) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3700,7 +3687,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3759,7 +3746,7 @@ CancelRequest (F) Int16 -字段所使用的格式代码。目前为零(文本)或一(二进制)。对于 Describe 的语句变体所返回的 RowDescription,格式代码尚未确定,始终为零。 +字段所使用的格式代码。目前为零(文本)或一(二进制)。对于 Describe 针对预备语句的变体所返回的 RowDescription,格式代码尚未确定,始终为零。 @@ -3789,7 +3776,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3840,7 +3827,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3866,7 +3853,7 @@ CancelRequest (F) Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3897,7 +3884,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3981,14 +3968,14 @@ CancelRequest (F) - 将消息标识为同步命令。 + 将该消息标识为 Sync 命令。 Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -4017,7 +4004,7 @@ CancelRequest (F) Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -4033,7 +4020,7 @@ CancelRequest (F) -错误和通知消息域 +错误和通知消息字段 本节描述了ErrorResponse和NoticeResponse消息中可能出现的字段。每个字段类型都有一个单字节的标识符。 @@ -4047,11 +4034,7 @@ CancelRequest (F) - 严重性: 字段内容为ERROR, FATAL, 或 - PANIC (在错误消息中), 或 - WARNING, NOTICE, DEBUG, - INFO, 或 LOG (在通知消息中), - 或者这些内容的本地化翻译。始终存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中),或这些内容的本地化翻译。始终存在。 @@ -4061,11 +4044,7 @@ CancelRequest (F) - 严重性:字段内容为 ERRORFATAL 或 - PANIC(在错误消息中),或 WARNINGNOTICEDEBUG、 - INFOLOG(在通知消息中)。 - 这与S字段相同,只是内容不会被本地化。仅在由PostgreSQL版本9.6 - 及更高版本生成的消息中存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中)。它与 S 字段相同,只是内容从不本地化。仅在 PostgreSQL 9.6 及更高版本生成的消息中存在。 @@ -4075,7 +4054,7 @@ CancelRequest (F) - Code: 错误的SQLSTATE代码(参见)。不可本地化。始终存在。 + 代码:错误的 SQLSTATE 代码(见 )。不可本地化。始终存在。 @@ -4085,9 +4064,7 @@ CancelRequest (F) - 消息: 主要的人类可读错误消息。 - 这应该准确但简洁(通常一行)。 - 总是存在。 + 消息:主要的可读错误消息。应准确而简洁(通常为一行)。始终存在。 @@ -4097,7 +4074,7 @@ CancelRequest (F) - 详细信息:一个可选的次要错误消息,提供有关问题的更多详细信息。可能会跨多行。 + 详细信息:可选的次要错误消息,提供有关该问题的更多细节。可能占多行。 @@ -4107,9 +4084,7 @@ CancelRequest (F) - 提示: 关于问题应该怎么做的一个可选建议。 - 这意在与细节不同,它提供建议(可能不合适)而不是硬性事实。 - 可能会跨越多行。 + 提示:可选的建议,说明如何处理该问题。它与详细信息的区别在于,它提供建议(可能并不合适),而非确凿事实。可能占多行。 @@ -4151,9 +4126,7 @@ CancelRequest (F) - Where: 错误发生的上下文指示。 - 目前包括活动的过程语言函数和内部生成查询的调用堆栈回溯。 - 跟踪每行一个条目,最近的在前。 + 上下文:说明错误发生时的上下文。目前包括活跃的过程语言函数和内部生成的查询的调用栈回溯。回溯每行一个条目,最近的调用在前。 @@ -4163,7 +4136,7 @@ CancelRequest (F) - Schema name: 如果错误与特定数据库对象相关联,则为包含该对象的模式的名称(如果有)。 + 模式名:如果错误与某个特定数据库对象有关,则为包含该对象的模式名称(如果有)。 @@ -4173,7 +4146,7 @@ CancelRequest (F) - 表名: 如果错误与特定表相关联,则为表的名称。(有关表模式名称的名称,请参考模式名称字段。) + 表名:如果错误与某个特定表有关,则为该表的名称。(表所在模式的名称见模式名字段。) @@ -4183,7 +4156,7 @@ CancelRequest (F) - 列名: 如果错误与特定表列相关联,则为列的名称。(请参考模式和表名字段以识别表。) + 列名:如果错误与某个特定表列有关,则为该列的名称。(通过模式名和表名字段确定该表。) @@ -4193,8 +4166,7 @@ CancelRequest (F) - 数据类型名称: 如果错误与特定数据类型相关联,则为数据类型的名称。 - (有关数据类型模式的名称,请参阅模式名称字段。) + 数据类型名:如果错误与某个特定数据类型有关,则为该数据类型的名称。(数据类型所在模式的名称见模式名字段。) @@ -4204,8 +4176,7 @@ CancelRequest (F) - 约束名称: 如果错误与特定约束相关联,则为约束的名称。请参考上面列出的字段,了解相关表或域。 - (为此,即使索引不是使用约束语法创建的,也将其视为约束。) + 约束名:如果错误与某个特定约束有关,则为该约束的名称。相关的表或域见上述字段。(这里将索引也视为约束,即使它不是用约束语法创建的。) @@ -4215,7 +4186,7 @@ CancelRequest (F) - 文件: 报告错误的源代码位置的文件名。 + 文件:报告错误的源代码位置所在的文件名。 @@ -4225,7 +4196,7 @@ CancelRequest (F) - Line: 源代码位置的行号,报告错误的位置。 + 行号:报告错误的源代码位置所在的行号。 @@ -4235,7 +4206,7 @@ CancelRequest (F) - Routine: 报告错误的源代码例程的名称。 + 例程:报告错误的源代码例程的名称。 @@ -4245,15 +4216,12 @@ CancelRequest (F) - 模式名称、表名称、列名称、数据类型名称和约束名称的字段仅针对有限数量的错误类型提供; - 请参阅。前端不应假设任何这些字段的存在就保证了另一个字段的存在。 - 核心错误源观察到上述相互关系,但用户定义的函数可能以其他方式使用这些字段。 - 同样地,客户端不应假设这些字段表示当前数据库中的当代对象。 + 模式名、表名、列名、数据类型名和约束名字段仅针对有限的几类错误提供,见 。前端不应假设其中任何字段的存在就保证了另一个字段的存在。核心错误源遵循上述相互关系,但用户定义的函数可能以其他方式使用这些字段。同样,客户端不应假设这些字段表示当前数据库中现存的对象。 - 客户端负责格式化显示的信息以满足其需求;特别是应根据需要换行。错误消息字段中出现的换行符应被视为段落分隔符,而不是换行符。 + 客户端负责按自身需要格式化显示的信息;尤其应根据需要将长行断开。错误消息字段中的换行符应视为段落分隔符,而非行分隔符。 @@ -4281,7 +4249,7 @@ CancelRequest (F) - 将消息标识为开始消息。 + 将该消息标识为 Begin 消息。 @@ -4325,7 +4293,7 @@ CancelRequest (F) - 标识消息为提交消息。 + 将该消息标识为 Commit 消息。 @@ -4374,7 +4342,7 @@ CancelRequest (F) Byte1('O') -标识消息为复制源消息。 +将该消息标识为 Origin 消息。 @@ -4396,7 +4364,7 @@ CancelRequest (F) - 请注意,在单个事务中可能存在多个Origin消息。 + 注意,单个事务中可能有多条 Origin 消息。 @@ -4411,7 +4379,7 @@ CancelRequest (F) Byte1('R') -将该消息标识为关系消息。 +将该消息标识为 Relation 消息。 @@ -4438,7 +4406,7 @@ CancelRequest (F) - 关系的复制标识设置(与relreplidentpg_class中相同)。 + 关系的复制标识设置(与 pg_class 中的 relreplident 相同)。 @@ -4473,7 +4441,7 @@ CancelRequest (F) - 列的类型修饰符 (atttypmod)。 + 列的类型修饰符(atttypmod)。 @@ -4492,7 +4460,7 @@ CancelRequest (F) Byte1('Y') -将该消息标识为类型消息。 +将该消息标识为 Type 消息。 @@ -4528,13 +4496,13 @@ CancelRequest (F) Byte1('I') -将该消息标识为插入消息。 +将该消息标识为 Insert 消息。 Int32 -关系的 ID,与关系消息中的 ID 对应。 +关系的 ID,与 Relation 消息中的 ID 对应。 @@ -4565,13 +4533,13 @@ CancelRequest (F) Byte1('U') -将该消息标识为更新消息。 +将该消息标识为 Update 消息。 Int32 -关系的 ID,与关系消息中的 ID 对应。 +关系的 ID,与 Relation 消息中的 ID 对应。 @@ -4627,13 +4595,13 @@ CancelRequest (F) Byte1('D') -将该消息标识为删除消息。 +将该消息标识为 Delete 消息。 Int32 -关系的 ID,与关系消息中的 ID 对应。 +关系的 ID,与 Relation 消息中的 ID 对应。 @@ -4674,7 +4642,7 @@ CancelRequest (F) Byte1('T') -将该消息标识为截断消息。 +将该消息标识为 Truncate 消息。 @@ -4695,7 +4663,7 @@ CancelRequest (F) Int32 -关系的 ID,与关系消息中的 ID 对应。每个关系都重复出现此字段。 +关系的 ID,与 Relation 消息中的 ID 对应。每个关系都重复出现此字段。 diff --git a/zh/11/rangetypes.sgml b/zh/11/rangetypes.sgml index e29cda85..e9983d1d 100644 --- a/zh/11/rangetypes.sgml +++ b/zh/11/rangetypes.sgml @@ -4,7 +4,7 @@ 范围类型 - range type + 范围类型 @@ -18,7 +18,9 @@ 内置范围类型 - PostgreSQL 提供以下内置范围类型: + + PostgreSQL 自带下列内置范围类型: + int4rangeinteger 的范围 @@ -37,7 +39,9 @@ daterangedate 的范围 - 此外,还可以定义自己的范围类型;参见了解更多信息。 + + 此外,你还可以定义自己的范围类型;详见。 + @@ -92,15 +96,15 @@ SELECT isempty(numrange(1, 5)); 无限(无界)范围 - 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作 +/-infinity,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的 +/-infinity 值。 + 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作正负无穷大,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的正负无穷大值。 - 具有infinity概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 + 具有无穷大概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 - 函数lower_infupper_inf分别测试范围的下界和上界是否为无限。 + 函数lower_infupper_inf分别测试范围是否没有下界和上界。 @@ -259,23 +263,23 @@ SELECT '[11:10, 23:00]'::timerange; 索引 - range type - indexes on + 范围类型 + 索引 可以为范围类型的表列创建 GiST 和 SP-GiST 索引。例如,创建 GiST 索引: CREATE INDEX reservation_idx ON reservation USING GIST (during); -GiST 或 SP-GiST 索引可以加速涉及以下范围操作符的查询:=, - &&, - <@, - @>, - <<, - >>, - -|-, +GiST 或 SP-GiST 索引可以加速涉及以下范围操作符的查询:=、 + &&、 + <@、 + @>、 + <<、 + >>、 + -|-&<&>(参见了解更多信息)。 - 此外,也可以为范围类型的表列创建 B-树和哈希索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和哈希支持主要是为了允许在查询内部进行排序和哈希,而不是用于创建实际的索引。 + 此外,也可以为范围类型的表列创建 B-树和 hash 索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和 hash 支持主要是为了允许在查询内部进行排序和 hash 运算,而不是用于创建实际的索引。 @@ -284,8 +288,8 @@ CREATE INDEX reservation_idx ON reservation USING GIST (during); 范围上的约束 - range type - exclude + 范围类型 + 排他约束 diff --git a/zh/11/recovery-config.sgml b/zh/11/recovery-config.sgml index 178d9c57..9fd213d7 100644 --- a/zh/11/recovery-config.sgml +++ b/zh/11/recovery-config.sgml @@ -4,9 +4,9 @@ 恢复配置 - configuration - of recovery - 一个备库 + 配置 + 恢复 + 备库 本章介绍 recovery.confrecovery.conf 文件中可用的设置。它们只在恢复期间生效。如果之后还要进行恢复,必须重新设置这些参数。恢复开始后,就不能再更改它们。 diff --git a/zh/11/ref/alter_extension.sgml b/zh/11/ref/alter_extension.sgml index 86286dec..ed782ba4 100644 --- a/zh/11/ref/alter_extension.sgml +++ b/zh/11/ref/alter_extension.sgml @@ -170,7 +170,7 @@ ALTER EXTENSION name DROP 要添加到扩展中或从扩展中移除的对象名称。表、聚合、域、外部表、函数、 - 操作符、操作符类、操作符族、过程、例程、序列、文本搜索对象、类型和视图的名称 + 操作符、操作符类、操作符族、过程、例程、序列、文本检索对象、类型和视图的名称 可以带模式限定。 diff --git a/zh/11/ref/alter_tsconfig.sgml b/zh/11/ref/alter_tsconfig.sgml index 453d7ee7..02e172c8 100644 --- a/zh/11/ref/alter_tsconfig.sgml +++ b/zh/11/ref/alter_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义 + 更改一个文本检索配置的定义 @@ -45,7 +45,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义。你可以修改其从记号类型到字典的映射, + 更改一个文本检索配置的定义。你可以修改其从词元类型到词典的映射, 或者更改该配置的名称或拥有者。 @@ -67,7 +67,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 一个现有文本搜索配置的名称(可以是模式限定的)。 + 一个现有文本检索配置的名称(可以是模式限定的)。 @@ -78,7 +78,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 由该配置的解析器发出的记号类型的名称。 + 由该配置的解析器发出的词元类型的名称。 @@ -89,7 +89,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 用于指定记号类型的文本搜索字典名称。如果列出了多个字典, + 用于指定词元类型的文本检索词典名称。如果列出了多个词典, 将按指定顺序依次查阅它们。 @@ -101,7 +101,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 在映射中要替换的文本搜索字典的名称。 + 在映射中要替换的文本检索词典的名称。 @@ -113,7 +113,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA 被用来替代old_dictionary - 的文本搜索字典的名称。 + 的文本检索词典的名称。 @@ -124,7 +124,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新名称。 + 该文本检索配置的新名称。 @@ -135,7 +135,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新拥有者。 + 该文本检索配置的新拥有者。 @@ -146,21 +146,21 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新模式。 + 该文本检索配置的新模式。 - ADD MAPPING FOR形式为指定的词元类型安装要查询的字典列表;如果任何词元类型已经存在映射,则会报错。ALTER MAPPING FOR形式执行相同操作,但会先移除这些词元类型的现有映射。ALTER MAPPING REPLACE形式在任何出现旧字典的地方用new_dictionary替换old_dictionary。当出现FOR时,只对指定的词元类型执行此操作;不出现时,则对该配置的所有映射执行。DROP MAPPING形式移除指定词元类型的所有字典,使这些类型的词元被文本搜索配置忽略。如果词元类型没有映射,则会报错,除非出现IF EXISTS + ADD MAPPING FOR形式为指定的词元类型安装要查询的词典列表;如果任何词元类型已经存在映射,则会报错。ALTER MAPPING FOR形式执行相同操作,但会先移除这些词元类型的现有映射。ALTER MAPPING REPLACE形式在任何出现旧词典的地方用new_dictionary替换old_dictionary。当出现FOR时,只对指定的词元类型执行此操作;不出现时,则对该配置的所有映射执行。DROP MAPPING形式移除指定词元类型的所有词典,使这些类型的词元被文本检索配置忽略。如果词元类型没有映射,则会报错,除非出现IF EXISTS 示例 - 以下示例在my_config中使用english的任何地方,都将english字典替换为swedish字典。 + 以下示例在my_config中使用english的任何地方,都将english词典替换为swedish词典。 ALTER TEXT SEARCH CONFIGURATION my_config diff --git a/zh/11/ref/alter_tsdictionary.sgml b/zh/11/ref/alter_tsdictionary.sgml index 9fedf32d..76c28ac6 100644 --- a/zh/11/ref/alter_tsdictionary.sgml +++ b/zh/11/ref/alter_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH DICTIONARY - 更改一个文本搜索字典的定义 + 更改一个文本检索词典的定义 @@ -37,14 +37,14 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - ALTER TEXT SEARCH DICTIONARY更改文本搜索字典的 - 定义。你可以更改该字典的模板相关选项,也可以更改该字典的名称或拥有者。 + ALTER TEXT SEARCH DICTIONARY更改文本检索词典的 + 定义。你可以更改该词典的模板相关选项,也可以更改该词典的名称或拥有者。 - 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该字典 + 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该词典 的拥有者。 @@ -59,7 +59,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 一个现有文本搜索字典的名称(可以是模式限定的)。 + 一个现有文本检索词典的名称(可以是模式限定的)。 @@ -70,7 +70,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -81,7 +81,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 模板相关选项要使用的新值。如果省略等号和值,则会从该字典中移除 + 模板相关选项要使用的新值。如果省略等号和值,则会从该词典中移除 该选项之前的设置,从而允许使用默认值。 @@ -93,7 +93,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新名称。 + 该文本检索词典的新名称。 @@ -104,7 +104,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新拥有者。 + 该文本检索词典的新拥有者。 @@ -115,7 +115,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新模式。 + 该文本检索词典的新模式。 @@ -134,7 +134,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 下面的示例命令更改了一个基于 Snowball 的字典的停用词列表。其他参数 + 下面的示例命令更改了一个基于 Snowball 的词典的停用词列表。其他参数 保持不变。 @@ -160,7 +160,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( language = dutch, StopWords ); - 下面的示例命令更新了该字典的定义,但实际上并没有做 + 下面的示例命令更新了该词典的定义,但实际上并没有做 任何更改。 @@ -168,7 +168,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( dummy ); (之所以可行,是因为选项移除代码在不存在该选项时也不会报错。) - 这种技巧在修改该字典的配置文件时很有用:ALTER + 这种技巧在修改该词典的配置文件时很有用:ALTER 会强制现有数据库会话重新读取配置文件,而如果它们先前已经读取过这 些文件,本来是不会再次读取的。 diff --git a/zh/11/ref/alter_tsparser.sgml b/zh/11/ref/alter_tsparser.sgml index 0844cb0a..ccc73f05 100644 --- a/zh/11/ref/alter_tsparser.sgml +++ b/zh/11/ref/alter_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH PARSER - 更改一个全文检索解析器的定义 + 更改一个文本检索解析器的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA 描述 - ALTER TEXT SEARCH PARSER更改全文检索解析器的定义。 + ALTER TEXT SEARCH PARSER更改文本检索解析器的定义。 当前唯一支持的功能是更改该解析器的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA name - 一个现有全文检索解析器的名称(可以是模式限定的)。 + 一个现有文本检索解析器的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_name - 该全文检索解析器的新名称。 + 该文本检索解析器的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_schema - 该全文检索解析器的新模式。 + 该文本检索解析器的新模式。 diff --git a/zh/11/ref/alter_tstemplate.sgml b/zh/11/ref/alter_tstemplate.sgml index a3eec599..9c9dfc2c 100644 --- a/zh/11/ref/alter_tstemplate.sgml +++ b/zh/11/ref/alter_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH TEMPLATE - 更改一个文本搜索模板的定义 + 更改一个文本检索模板的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA 描述 - ALTER TEXT SEARCH TEMPLATE更改文本搜索模板的定义。 + ALTER TEXT SEARCH TEMPLATE更改文本检索模板的定义。 当前唯一支持的功能是更改该模板的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA name - 一个现有文本搜索模板的名称(可以是模式限定的)。 + 一个现有文本检索模板的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_name - 该文本搜索模板的新名称。 + 该文本检索模板的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_schema - 该文本搜索模板的新模式。 + 该文本检索模板的新模式。 diff --git a/zh/11/ref/comment.sgml b/zh/11/ref/comment.sgml index 89b06fe3..68533da6 100644 --- a/zh/11/ref/comment.sgml +++ b/zh/11/ref/comment.sgml @@ -116,7 +116,7 @@ COMMENT ON rule_name trigger_name - 要添加注释的对象名称。表、聚合、排序规则、转换、域、外部表、函数、索引、操作符、操作符类、操作符族、过程、例程、序列、统计信息、文本搜索对象、类型和视图的名称可以带模式限定。为列添加注释时,relation_name必须引用表、视图、复合类型或外部表。 + 要添加注释的对象名称。表、聚合、排序规则、转换、域、外部表、函数、索引、操作符、操作符类、操作符族、过程、例程、序列、统计信息、文本检索对象、类型和视图的名称可以带模式限定。为列添加注释时,relation_name必须引用表、视图、复合类型或外部表。 diff --git a/zh/11/ref/create_tsconfig.sgml b/zh/11/ref/create_tsconfig.sgml index 974ef42a..1d4ceca2 100644 --- a/zh/11/ref/create_tsconfig.sgml +++ b/zh/11/ref/create_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH CONFIGURATION - 定义一个新的文本搜索配置 + 定义一个新的文本检索配置 @@ -33,24 +33,24 @@ CREATE TEXT SEARCH CONFIGURATION name CREATE TEXT SEARCH CONFIGURATION - 创建一个新的文本搜索配置。文本搜索配置指定一个能把字符串拆分为记号 - 的文本搜索解析器,以及一些可用于判断哪些记号对搜索有意义的词典。 + 创建一个新的文本检索配置。文本检索配置指定一个能把字符串拆分为词元 + 的文本检索解析器,以及一些可用于判断哪些词元对搜索有意义的词典。 - 如果只指定了解析器,那么新文本搜索配置最初没有从记号类型到词典的映射, + 如果只指定了解析器,那么新文本检索配置最初没有从词元类型到词典的映射, 因而会忽略所有词。要让该配置真正可用,必须使用后续的ALTER TEXT SEARCH CONFIGURATION命令创建映射。 - 另一种方式是复制一个现有的文本搜索配置。 + 另一种方式是复制一个现有的文本检索配置。 - 如果给出了一个模式名称,则文本搜索配置会被创建在指定的模式中。否则它将会 + 如果给出了一个模式名称,则文本检索配置会被创建在指定的模式中。否则它将会 被创建在当前模式中。 - 定义该文本搜索配置的用户会成为其拥有者。 + 定义该文本检索配置的用户会成为其拥有者。 @@ -66,7 +66,7 @@ CREATE TEXT SEARCH CONFIGURATION namename - 要创建的文本搜索配置的名称。该名称可以是模式限定的。 + 要创建的文本检索配置的名称。该名称可以是模式限定的。 @@ -75,7 +75,7 @@ CREATE TEXT SEARCH CONFIGURATION nameparser_name - 此配置要使用的文本搜索解析器的名称。 + 此配置要使用的文本检索解析器的名称。 @@ -84,7 +84,7 @@ CREATE TEXT SEARCH CONFIGURATION namesource_config - 要复制的现有文本搜索配置的名称。 + 要复制的现有文本检索配置的名称。 diff --git a/zh/11/ref/create_tsdictionary.sgml b/zh/11/ref/create_tsdictionary.sgml index 2dbca552..75218295 100644 --- a/zh/11/ref/create_tsdictionary.sgml +++ b/zh/11/ref/create_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH DICTIONARY - 定义一个新的文本搜索字典 + 定义一个新的文本检索词典 @@ -33,19 +33,19 @@ CREATE TEXT SEARCH DICTIONARY name CREATE TEXT SEARCH DICTIONARY创建一个 - 新的文本搜索字典。文本搜索字典指定一种在搜索时识别哪些词值得关注、 - 哪些词不值得关注的方式。字典依赖于文本搜索模板,后者规定了实际执行 - 这项工作的函数。通常,字典会提供一些选项,用来控制模板函数的具体 + 新的文本检索词典。文本检索词典指定一种在搜索时识别哪些词值得关注、 + 哪些词不值得关注的方式。词典依赖于文本检索模板,后者规定了实际执行 + 这项工作的函数。通常,词典会提供一些选项,用来控制模板函数的具体 行为。 - 如果给出了一个模式名称,那么该文本搜索字典会被创建在指定的模式中。 + 如果给出了一个模式名称,那么该文本检索词典会被创建在指定的模式中。 否则它会被创建在当前模式中。 - 定义文本搜索字典的用户将成为其拥有者。 + 定义文本检索词典的用户将成为其拥有者。 @@ -61,7 +61,7 @@ CREATE TEXT SEARCH DICTIONARY name name - 要创建的文本搜索字典的名称。该名称可以被模式限定。 + 要创建的文本检索词典的名称。该名称可以被模式限定。 @@ -70,7 +70,7 @@ CREATE TEXT SEARCH DICTIONARY name template - 用于定义该字典基本行为的文本搜索模板名称。 + 用于定义该词典基本行为的文本检索模板名称。 @@ -79,7 +79,7 @@ CREATE TEXT SEARCH DICTIONARY name option - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -105,7 +105,7 @@ CREATE TEXT SEARCH DICTIONARY name 下面的示例命令创建了一个基于 Snowball 且使用非标准停用词列表的 - 字典。 + 词典。 diff --git a/zh/11/ref/create_tsparser.sgml b/zh/11/ref/create_tsparser.sgml index 6af67ab8..5f2e5184 100644 --- a/zh/11/ref/create_tsparser.sgml +++ b/zh/11/ref/create_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH PARSER - 定义一个新的全文检索解析器 + 定义一个新的文本检索解析器 @@ -36,19 +36,19 @@ CREATE TEXT SEARCH PARSER name ( CREATE TEXT SEARCH PARSER创建一个 - 新的全文检索解析器。全文检索解析器定义了一种方法,用于将文本字符串 - 拆分成记号并为这些记号指定类型(类别)。解析器本身并没有太大用处, - 必须与一些全文检索字典一起绑定到一个全文检索配置中,才能用于搜索。 + 新的文本检索解析器。文本检索解析器定义了一种方法,用于将文本字符串 + 拆分成词元并为这些词元指定类型(类别)。解析器本身并没有太大用处, + 必须与一些文本检索词典一起绑定到一个文本检索配置中,才能用于搜索。 - 如果给出了一个模式名称,那么全文检索解析器将被创建在指定的模式中。 + 如果给出了一个模式名称,那么文本检索解析器将被创建在指定的模式中。 否则它会被创建在当前模式中。 要使用CREATE TEXT SEARCH PARSER,你必须是超级用户。 - 之所以有此限制,是因为错误的全文检索解析器定义可能会让服务器陷入 + 之所以有此限制,是因为错误的文本检索解析器定义可能会让服务器陷入 混乱,甚至崩溃。 @@ -65,7 +65,7 @@ CREATE TEXT SEARCH PARSER name ( name - 要创建的全文检索解析器的名称。该名称可以是模式限定的。 + 要创建的文本检索解析器的名称。该名称可以是模式限定的。 @@ -83,7 +83,7 @@ CREATE TEXT SEARCH PARSER name ( gettoken_function - 该解析器的获取下一个记号的函数名称。 + 该解析器的获取下一个词元的函数名称。 @@ -101,7 +101,7 @@ CREATE TEXT SEARCH PARSER name ( lextypes_function - 该解析器的 lextypes 函数的名称(该函数返回它所产生的记号类型集合的 + 该解析器的 lextypes 函数的名称(该函数返回它所产生的词元类型集合的 信息)。 @@ -111,7 +111,7 @@ CREATE TEXT SEARCH PARSER name ( headline_function - 该解析器的 headline 函数的名称(该函数对一组记号生成摘要)。 + 该解析器的 headline 函数的名称(该函数对一组词元生成摘要)。 diff --git a/zh/11/ref/create_tstemplate.sgml b/zh/11/ref/create_tstemplate.sgml index 5dd2e1c0..24ee925e 100644 --- a/zh/11/ref/create_tstemplate.sgml +++ b/zh/11/ref/create_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH TEMPLATE - 定义一个新的全文检索模板 + 定义一个新的文本检索模板 @@ -33,22 +33,22 @@ CREATE TEXT SEARCH TEMPLATE name ( CREATE TEXT SEARCH TEMPLATE创建一个 - 新的全文检索模板。全文检索模板定义实现全文检索字典的函数。模板本身 - 并无直接用途,必须先实例化为字典后才能使用。字典通常会指定要传递给 + 新的文本检索模板。文本检索模板定义实现文本检索词典的函数。模板本身 + 并无直接用途,必须先实例化为词典后才能使用。词典通常会指定要传递给 模板函数的参数。 - 如果给出了模式名称,则全文检索模板会被创建在指定模式中。否则它会被 + 如果给出了模式名称,则文本检索模板会被创建在指定模式中。否则它会被 创建在当前模式中。 要使用CREATE TEXT SEARCH TEMPLATE,你 - 必须是超级用户。之所以有此限制,是因为错误的全文检索模板定义可能使 - 服务器陷入混乱,甚至崩溃。将模板与字典分离的原因在于,模板封装了定 - 义字典时那些不安全的方面。而在定义字典时可设置的参数, - 对非特权用户来说是安全的,因此创建字典不必是特权操作。 + 必须是超级用户。之所以有此限制,是因为错误的文本检索模板定义可能使 + 服务器陷入混乱,甚至崩溃。将模板与词典分离的原因在于,模板封装了定 + 义词典时那些不安全的方面。而在定义词典时可设置的参数, + 由普通用户设置也是安全的,因此创建词典不必是特权操作。 @@ -64,7 +64,7 @@ CREATE TEXT SEARCH TEMPLATE name ( name - 要创建的全文检索模板名称。该名称可以是模式限定的。 + 要创建的文本检索模板名称。该名称可以是模式限定的。 diff --git a/zh/11/ref/drop_opclass.sgml b/zh/11/ref/drop_opclass.sgml index 9d67dc64..545a2517 100644 --- a/zh/11/ref/drop_opclass.sgml +++ b/zh/11/ref/drop_opclass.sgml @@ -110,7 +110,7 @@ DROP OPERATOR CLASS [ IF EXISTS ] name示例 - 移除 B-tree 操作符类widget_ops: + 移除 B-树操作符类widget_ops DROP OPERATOR CLASS widget_ops USING btree; diff --git a/zh/11/ref/drop_tsconfig.sgml b/zh/11/ref/drop_tsconfig.sgml index ea139802..b3ebb9d1 100644 --- a/zh/11/ref/drop_tsconfig.sgml +++ b/zh/11/ref/drop_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH CONFIGURATION - 移除一个文本搜索配置 + 移除一个文本检索配置 @@ -29,7 +29,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 描述 - DROP TEXT SEARCH CONFIGURATION删除一个现有文本搜索配置。 + DROP TEXT SEARCH CONFIGURATION删除一个现有文本检索配置。 要执行此命令,你必须是该配置的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name IF EXISTS - 如果该文本搜索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name name - 现有文本搜索配置的名称(可以被模式限定)。 + 现有文本检索配置的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name CASCADE - 自动删除依赖于该文本搜索配置的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索配置的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name RESTRICT - 如果有任何对象依赖于该文本搜索配置,则拒绝删除该配置。这是默认值。 + 如果有任何对象依赖于该文本检索配置,则拒绝删除该配置。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 示例 - 移除文本搜索配置my_english: + 移除文本检索配置my_english DROP TEXT SEARCH CONFIGURATION my_english; 如果已有索引在to_tsvector调用中引用了该配置, - 此命令将不会成功。加上CASCADE可以在删除该文本搜索配置的同时删除这类索引。 + 此命令将不会成功。加上CASCADE可以在删除该文本检索配置的同时删除这类索引。 diff --git a/zh/11/ref/drop_tsdictionary.sgml b/zh/11/ref/drop_tsdictionary.sgml index 316c5d00..0f7751a1 100644 --- a/zh/11/ref/drop_tsdictionary.sgml +++ b/zh/11/ref/drop_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH DICTIONARY - 移除一个文本搜索字典 + 移除一个文本检索词典 @@ -29,8 +29,8 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name描述 - DROP TEXT SEARCH DICTIONARY删除一个现有文本搜索字典。 - 要执行此命令,你必须是该字典的拥有者。 + DROP TEXT SEARCH DICTIONARY删除一个现有文本检索词典。 + 要执行此命令,你必须是该词典的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索字典不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索词典不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] namename - 一个现有文本搜索字典的名称(可以被模式限定)。 + 一个现有文本检索词典的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索字典的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索词典的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索字典,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索词典,则拒绝删除它。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name示例 - 移除文本搜索字典english: + 移除文本检索词典english DROP TEXT SEARCH DICTIONARY english; - 如果已有文本搜索配置使用该字典,此命令将不会成功。 - 加上CASCADE可以在删除字典的同时删除这类配置。 + 如果已有文本检索配置使用该词典,此命令将不会成功。 + 加上CASCADE可以在删除词典的同时删除这类配置。 diff --git a/zh/11/ref/drop_tsparser.sgml b/zh/11/ref/drop_tsparser.sgml index a65f47be..ea74f0f8 100644 --- a/zh/11/ref/drop_tsparser.sgml +++ b/zh/11/ref/drop_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH PARSER - 移除一个文本搜索解析器 + 移除一个文本检索解析器 @@ -29,7 +29,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name描述 - DROP TEXT SEARCH PARSER删除一个现有文本搜索解析器。 + DROP TEXT SEARCH PARSER删除一个现有文本检索解析器。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] namename - 一个现有文本搜索解析器的名称(可以被模式限定)。 + 一个现有文本检索解析器的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索解析器的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索解析器的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索解析器,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索解析器,则拒绝删除它。这是默认值。 @@ -82,13 +82,13 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name示例 - 移除文本搜索解析器my_parser: + 移除文本检索解析器my_parser DROP TEXT SEARCH PARSER my_parser; - 如果已有文本搜索配置使用该解析器,此命令将不会成功。 + 如果已有文本检索配置使用该解析器,此命令将不会成功。 加上CASCADE可以在删除解析器的同时删除这类配置。 diff --git a/zh/11/ref/drop_tstemplate.sgml b/zh/11/ref/drop_tstemplate.sgml index fa1faab0..3a44c927 100644 --- a/zh/11/ref/drop_tstemplate.sgml +++ b/zh/11/ref/drop_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH TEMPLATE - 移除一个文本搜索模板 + 移除一个文本检索模板 @@ -29,7 +29,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name描述 - DROP TEXT SEARCH TEMPLATE删除一个现有文本搜索模板。 + DROP TEXT SEARCH TEMPLATE删除一个现有文本检索模板。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] namename - 现有文本搜索模板的名称(可以被模式限定)。 + 现有文本检索模板的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索模板的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索模板的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索模板,则拒绝删除该模板。这是默认值。 + 如果有任何对象依赖于该文本检索模板,则拒绝删除该模板。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name示例 - 移除文本搜索模板thesaurus: + 移除文本检索模板thesaurus DROP TEXT SEARCH TEMPLATE thesaurus; - 如果已有文本搜索字典使用该模板,此命令将不会成功。加上CASCADE - 可以在删除该模板的同时删除这类字典。 + 如果已有文本检索词典使用该模板,此命令将不会成功。加上CASCADE + 可以在删除该模板的同时删除这类词典。 diff --git a/zh/11/ref/initdb.sgml b/zh/11/ref/initdb.sgml index 67014373..2bcff87b 100644 --- a/zh/11/ref/initdb.sgml +++ b/zh/11/ref/initdb.sgml @@ -142,7 +142,7 @@ PostgreSQL documentation - + @@ -154,7 +154,7 @@ PostgreSQL documentation - + @@ -213,7 +213,7 @@ PostgreSQL documentation - 使initdb从文件中读取引导超级用户的密码。文件的第一行会被当作密码。 + 使initdb从文件中读取数据库超级用户的密码。文件的第一行会被当作密码。 @@ -233,7 +233,7 @@ PostgreSQL documentation - 设置默认文本搜索配置。更多信息见 + 设置默认文本检索配置。更多信息见 @@ -244,10 +244,9 @@ PostgreSQL documentation - 选择数据库超级用户的用户名。默认值是运行 - initdb的实际用户名称。超级用户的名称本身 - 并不重要,不过即使操作系统用户名称不同,人们也可能选择沿用惯常 - 的名称postgres。 + 选择数据库超级用户的用户名。默认值是运行initdb的有效用户的名称。 + 超级用户的名称本身并不重要,不过即使操作系统用户名称不同,也可以选择沿用惯常的名称 + postgres @@ -257,7 +256,7 @@ PostgreSQL documentation - 使initdb提示输入要赋给引导超级用户的密码。如果不打算使用密码认证, + 使initdb提示输入要赋给数据库超级用户的密码。如果不打算使用密码认证, 这一点并不重要。否则,在设置密码之前将无法使用密码认证。 diff --git a/zh/11/ref/pgbench.sgml b/zh/11/ref/pgbench.sgml index 1a237fb1..7d1363b8 100644 --- a/zh/11/ref/pgbench.sgml +++ b/zh/11/ref/pgbench.sgml @@ -36,7 +36,7 @@ PostgreSQL documentation 描述 - pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,必要时可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 + pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,也可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 @@ -57,13 +57,15 @@ tps = 85.296346 (excluding connections establishing) 前六行报告了一些最重要的参数设置。下一行报告已完成的事务数和预期的事务数(后者就是客户端数与每个客户端的事务数的乘积);除非运行在完成前失败,否则这两个数应该相等。(在 模式下,只打印实际的事务数。)最后两行报告每秒事务数,分别计入和不计入启动数据库会话的时间。 - 默认的类 TPC-B 事务测试要求预先建立特定的表。pgbench应使用(初始化)选项调用,以创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: + + 默认的类 TPC-B 事务测试要求预先建立特定的表。应使用(初始化)选项调用pgbench来创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: + + pgbench -i other-options dbname - 其中, - dbname是已创建好的、用于执行测试的数据库名称。(可能还需要使用, - 和/或选项来指定如何连接到数据库服务器。) + 其中dbname是已创建好的、用于执行测试的数据库名称。(可能还需要使用和/或选项来指定如何连接到数据库服务器。) + @@ -76,14 +78,14 @@ pgbench -i other-options 在默认的比例因子 1 下,这些表最初包含如下行数: -table # of rows +表 行数 --------------------------------- pgbench_branches 1 pgbench_tellers 10 pgbench_accounts 100000 pgbench_history 0 - 可以使用(比例因子)选项来增加行数,而且在大多数场景下也确实应该这样做。此时还可以配合使用(fillfactor)选项。 + 可以使用(比例因子)选项来增加行数,而且在大多数场景下通常也应该这样做。此时还可以配合使用(fillfactor)选项。 @@ -102,14 +104,14 @@ pgbench options d 选项 - 下面分成三个部分。数据库初始化期间使用的选项和运行基准时会使用不同的选项,但也有一些选项在两种情况下都使用。 + 以下内容分为三个小节。数据库初始化和运行基准测试时使用不同的选项,但有些选项在这两种情况下都适用。 初始化选项 - pgbench 接受以下用于初始化的命令行参数: + pgbench 接受以下命令行初始化参数: @@ -293,7 +295,7 @@ pgbench options d 基准测试选项 - pgbench 接受以下用于基准测试的命令行参数: + pgbench 接受以下命令行基准测试参数: @@ -430,13 +432,13 @@ pgbench options d 用于向服务器提交查询的协议: - simple: 使用简单查询协议。 + simple:使用简单查询协议。 - extended: 使用扩展查询协议。 + extended:使用扩展查询协议。 - prepared: 使用带有预备语句的扩展查询协议。 + prepared:使用带有预备语句的扩展查询协议。 默认为简单查询协议。(详见 。) @@ -520,7 +522,7 @@ pgbench options d 较高的计划滞后时间表明,在所选客户端数和线程数下,系统无法以指定速率处理事务。 当平均事务执行时间长于事务之间的计划间隔时,后续事务会不断进一步落后, - 而计划滞后时间也会随着测试持续时间增加。在这种情况下,只能降低指定的事务速率。 + 而计划滞后时间也会随着测试持续时间增加。在这种情况下,需要降低指定的事务速率。 @@ -532,7 +534,7 @@ pgbench options d pgbench输出中报告指定的比例因子。 - 对于内置测试,这通常没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 + 对于内置测试,这没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 但在只测试自定义基准(选项)时, 除非使用此选项,否则比例因子会被报告为 1。 @@ -735,7 +737,7 @@ pgbench options d 注解 - 实际执行的<quote>事务</quote>在<application>pgbench</application>中是什么? + 在<application>pgbench</application>中实际执行的<quote>事务</quote>是什么? pgbench会从指定列表中随机选取测试脚本来执行。 @@ -782,7 +784,7 @@ pgbench options d - 在PostgreSQL 9.6 之前,脚本文件中的 SQL 命令以换行符结束,因此不能跨行续写。现在,连续的 SQL 命令之间必须用分号分隔(不过,如果 SQL 命令后面跟着元命令,则不需要分号)。如果需要创建适用于新旧版本pgbench的脚本文件,请务必将每条 SQL 命令写在单独一行,并以分号结尾。 + 在PostgreSQL 9.6 之前,脚本文件中的 SQL 命令以换行结束,因此不能跨行。现在连续 SQL 命令之间必须用分号分隔(如果 SQL 命令后面跟着一个元命令,则不需要分号)。如果需要创建一个既能在旧版也能在新版pgbench下工作的脚本文件,务必将每个 SQL 命令写在单独一行,并以分号结束。 @@ -809,7 +811,7 @@ pgbench options d default_seed - 默认在哈希函数中使用的种子 + 默认在 hash 函数中使用的种子 @@ -826,7 +828,7 @@ pgbench options d
- 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令及其参数之间以空白分隔。支持的元命令如下: + 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令的参数以空白分隔。支持的元命令如下: @@ -909,7 +911,7 @@ pgbench options d
- command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在其开头再写一个冒号。 + command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在argument开头再写一个冒号。 @@ -1175,14 +1177,14 @@ pgbench options d hash_fnv1a(a [, seed ] ) integer - FNV-1a 哈希 + FNV-1a hash hash_fnv1a(10, 5432) -7793829335365542153 hash_murmur2(a [, seed ] ) integer - MurmurHash2 哈希 + MurmurHash2 hash hash_murmur2(10, 5432) -5817877081768721676 @@ -1224,7 +1226,7 @@ pgbench options d pow(x, y), power(x, y) double - 指数 + 求幂 pow(2.0, 10), power(2.0, 10) 1024.0 @@ -1273,29 +1275,28 @@ pgbench options d - 对于指数分布,parameter通过在以下位置截断一个快速衰减的指数分布来控制分布:parameter,然后将其投影到边界之间的整数上。准确地说,令 + + 对于指数分布,parameter通过在parameter处截断一个快速衰减的指数分布,再将其投影到边界之间的整数上,从而控制分布。准确地说,令 + f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) -则值i 位于 min 和 - max 之间(包括端点),被抽到的概率为: - f(i) - f(i + 1)。 + + 则minmax之间(含边界)的值i会以f(i) - f(i + 1)的概率被抽中。 - 直观地说,parameter越大,接近min的值被访问得越频繁,而接近max的值被访问得越少。parameter越接近 0,访问分布就越平坦(越均匀)。对该分布的一个粗略近似是:范围内最常出现的 1% 的值,即接近min的那些值,会在parameter% 的时间里被抽中。parameter的值必须严格为正。 + + 直观地说,parameter越大,越靠近min的值越容易被抽到,而越靠近max的值越不容易被抽到。parameter越接近 0,分布就越平坦(也就越均匀)。对这种分布的一个粗略近似是:范围内出现频率最高的 1% 的值,即最靠近min的那些值,大约会占到parameter% 的抽样次数。parameter必须严格大于 0。 + - 对于高斯分布,该区间映射到标准正态分布(经典的钟形高斯曲线),左侧截断于 -parameter,右侧截断于 +parameter。区间中部的值更容易被抽到。准确地说,如果 PHI(x) 为标准正态分布的累积分布函数,均值 mu 定义为 (max + min) / 2.0,并且 - + 对于高斯分布,该区间会映射到一个标准正态分布(经典钟形高斯曲线),并在左侧-parameter和右侧+parameter处截断。区间中部的值更容易被抽到。准确地说,如果PHI(x)是标准正态分布的累积分布函数,均值mu定义为(max + min) / 2.0,则有 + f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / (2.0 * PHI(parameter) - 1) - 那么,值 i 位于 min 和 - max 之间(包括端点),被抽到的概率为: - f(i + 0.5) - f(i - 0.5)。直观地说,parameter 越大,越靠近区间中部的值被抽到的频率就越高,而越靠近 min 和 - max 边界的值被抽到的频率就越低。约 67% 的值抽自区间中间的 1.0 / parameter,即均值周围相对 0.5 / parameter 的范围;95% 的值抽自区间中间的 2.0 / parameter,即均值周围相对 1.0 / parameter 的范围。例如,如果 parameter 为 4.0,则 67% 的值抽自区间中间四分之一(1.0 / 4.0)的范围(即从 - 3.0 / 8.05.0 / 8.0),95% 的值抽自区间中间一半(2.0 / 4.0)的范围(第二和第三四分位)。考虑到 Box-Muller 变换的性能,parameter 的最小值为 2.0。 - + 则minmax(包含边界)之间的值i被抽中的概率为:f(i + 0.5) - f(i - 0.5)。直观地说,parameter越大,越靠近区间中间的值被抽到的频率越高,而越靠近minmax边界的值被抽到的频率越低。大约 67% 的值会落在区间中部1.0 / parameter这一段内,也就是均值两侧各占区间长度0.5 / parameter的范围内;约 95% 的值会落在区间中部2.0 / parameter这一段内,也就是均值两侧各占区间长度1.0 / parameter的范围内。例如,如果parameter为 4.0,则 67% 的值会落在区间中间四分之一(1.0 / 4.0)内,也就是从3.0 / 8.05.0 / 8.0;95% 的值会落在区间中间一半(2.0 / 4.0)内,也就是第二和第三四分位。考虑到 Box-Muller 变换的性能,parameter的最小值为 2.0。 +
@@ -1309,8 +1310,8 @@ f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / - 哈希函数 hashhash_murmur2 和 - hash_fnv1a 接受一个输入值和一个可选的种子参数。如果未提供种子,则使用 :default_seed 的值,该值随机初始化,除非通过命令行 -D 选项设置。哈希函数可以用来打散随机函数的分布,例如 random_zipfian 或 + Hash 函数 hashhash_murmur2 和 + hash_fnv1a 接受一个输入值和一个可选的种子参数。如果未提供种子,则使用 :default_seed 的值,该值随机初始化,除非通过命令行 -D 选项设置。Hash 函数可以用来打散随机函数的分布,例如 random_zipfianrandom_exponential。例如,以下 pgbench 脚本模拟了社交媒体和博客平台中可能出现的典型真实工作负载,其中少数账户产生了过多的负载: @@ -1372,8 +1373,7 @@ END; - 下面是单个客户端运行时生成的日志文件片段: - + 这里是在单个客户端运行中生成的一个日志文件的片段: 0 199 2241 0 1175850568 995598 0 200 2465 0 1175850568 998079 @@ -1381,9 +1381,8 @@ END; 0 202 2038 0 1175850569 2663 - 下面是另一个使用 --rate=100--latency-limit=5 的示例(请注意额外的 - schedule_lag 列): - + 另一个示例使用的是--rate=100以及--latency-limit=5(注意额外的 + schedule_lag列): 0 81 4621 0 1412881037 912698 3005 0 82 6173 0 1412881037 914578 4304 @@ -1393,7 +1392,8 @@ END; 0 84 4142 0 1412881037 918023 2333 0 85 2465 0 1412881037 919759 740 - 在这个示例中,事务 82 超时了,因为其延迟(6.173 ms)超过了 5 ms 的限制。接下来的两个事务被跳过,因为它们在开始前就已经超时。 + 在这个示例中,事务 82 迟到了,因为它的延迟(6.173 ms)超过了 + 5 ms 限制。接下来的两个事务被跳过,因为它们在开始之前就已经迟到了。 @@ -1418,7 +1418,7 @@ END; sum_latency_2 是区间内事务延迟的平方和, min_latency 是区间内的最小延迟,而 max_latency 是区间内的最大延迟。接下来的字段 - sum_lagsum_lag_2min_lagmax_lag 仅在使用 选项时出现。它们提供各事务等待前一事务完成的时间统计,即各事务计划开始时间与实际开始时间之间的差值。最后一个字段 skipped 仅在还使用 选项时出现。它记录因开始时间过晚而被跳过的事务数。每个事务都计入其提交时所在的时间区间。 + sum_lagsum_lag_2min_lagmax_lag 仅在使用 选项时出现。它们提供各事务等待前一事务完成的时间统计,即各事务计划开始时间与实际开始时间之间的差值。最后一个字段 skipped 仅在还使用 选项时出现。它记录因开始时间过晚而被跳过的事务数。每个事务都计入其提交时所在的时间区间。 @@ -1438,7 +1438,7 @@ END; - 逐语句报告 + 逐语句延迟 使用选项时,pgbench会收集每个客户端执行的每条语句所经过的事务时间。基准测试完成后,它会报告这些值的平均值,称为每条语句的延迟。 @@ -1475,11 +1475,11 @@ statement latencies in milliseconds: - 所有数值都是针对每个客户端执行的每条语句计算的,并在基准测试完成后报告。 + 如果指定了多个脚本文件,则会分别为每个脚本文件报告平均值。 - 请注意,收集计算每条语句延迟所需的额外计时信息会增加一些开销。这会降低平均执行速度,使计算出的 TPS 下降。减速程度因平台和硬件而异,差别可能很大。比较启用和未启用延迟报告时的平均 TPS 值,是衡量计时开销是否显著的好方法。 + 注意,为逐语句延迟计算收集额外的计时信息会带来一定开销。这会拖慢平均执行速度,并降低计算出的 TPS。减速幅度在很大程度上取决于平台和硬件。比较启用和未启用延迟报告时的平均 TPS 值,是判断这一计时开销是否显著的好方法。 @@ -1500,7 +1500,7 @@ statement latencies in milliseconds: - 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和空闲空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 + 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和无效空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 diff --git a/zh/11/ref/psql-ref.sgml b/zh/11/ref/psql-ref.sgml index f8b60cf8..d9c9de16 100644 --- a/zh/11/ref/psql-ref.sgml +++ b/zh/11/ref/psql-ref.sgml @@ -47,7 +47,7 @@ PostgreSQL documentation - 把所有非空输入行按照它们被读入的形式打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 + 在读入时将所有非空输入行打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 all @@ -78,10 +78,10 @@ PostgreSQL documentation - 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,直到它处理完序列中所有的选项之后终止。 + 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,而是在按顺序处理完所有选项后终止。 - command必须是一个服务器完全可解析的命令字符串(即不包含psql相关的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: + command必须是一个服务器完全可解析的命令字符串(即不包含psql专有的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: psql -c '\x' -c 'SELECT * FROM foo;' @@ -94,7 +94,7 @@ echo '\x \\ SELECT * FROM foo;' | psql 每个SQL命令字符串传递给都作为一个单独的请求发送到服务器。 因此,即使字符串包含多个SQL命令,服务器也会将其作为单个事务执行, - 除非字符串中包含明确的BEGIN/COMMIT命令将其分成多个事务。 + 除非字符串中包含显式的BEGIN/COMMIT命令将其分成多个事务。 (有关服务器如何处理多查询字符串的更多详细信息,请参见。) 此外,psql只打印字符串中最后一条SQL命令的结果。这与从文件读取同一字符串或将其送入psql标准输入时的行为不同,因为在这些情况下,psql会分别发送每条SQL命令。 @@ -149,7 +149,7 @@ EOF - 如果filename-(连字符),则会读取标准输入,直到遇到 EOF 指示或\q元命令。这可用于将交互式输入与文件输入交错使用。不过请注意,这种情况下不会使用 Readline(很像指定了时的情况)。 + 如果filename-(连字符),则会读取标准输入,直到遇到 EOF 指示或\q元命令。这可用于将交互式输入与文件输入交错使用。不过请注意,这种情况下不会使用 Readline(很像指定了时的情况)。 @@ -163,7 +163,7 @@ EOF - 使用separator作为非对齐输出的域分隔符。这等效于\pset fieldsep或者\f。 + 使用separator作为非对齐输出的字段分隔符。这等效于\pset fieldsep或者\f
@@ -183,7 +183,7 @@ EOF - 切换到HTML输出模式。这等效于\pset format html或者\H命令。 + 切换到HTML表格输出模式。这等效于\pset format html或者\H命令。
@@ -217,7 +217,7 @@ EOF - 不要使用Readline进行行编辑,也不要使用命令历史记录。这有助于在剪切和粘贴时关闭制表符展开。 + 不要使用Readline进行行编辑,也不要使用命令历史记录。这有助于在剪切和粘贴时关闭TAB 补全。
@@ -237,7 +237,7 @@ EOF - 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。 + 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展名。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。 @@ -257,7 +257,7 @@ EOF - 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息以及多种输出。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon。 + 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息和各种提示信息。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon @@ -277,7 +277,7 @@ EOF - 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户一个可以取消执行的选项。使用这个选项可以调试脚本。 + 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户,并允许取消执行。使用这个选项可以调试脚本。 @@ -287,7 +287,7 @@ EOF - 运行在单行模式中,其中新行会终止一个 SQL 命令,就像分号的作用一样。 + 运行在单行模式中,其中换行符会终止一个 SQL 命令,就像分号的作用一样。 @@ -313,7 +313,7 @@ EOF - 指定要替换HTML table标签的选项。详见\pset tableattr。 + 指定要放在HTML table标签内的选项。详见\pset tableattr @@ -334,7 +334,7 @@ EOF - 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要重置一个变量,去掉等号就行。要把一个变量置为空值,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 + 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要取消变量的设置,去掉等号就行。要把一个变量设为空字符串,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 @@ -396,7 +396,7 @@ EOF - 不读取启动文件(要么是系统范围的psqlrc文件,要么是用户的~/.psqlrc文件)。 + 不读取启动文件(既不读取系统范围的psqlrc文件,也不读取用户的~/.psqlrc文件)。 @@ -406,7 +406,7 @@ EOF - 设置非对齐输出的域分隔符为零字节。这等效于\pset fieldsep_zero。 + 设置非对齐输出的字段分隔符为零字节。这等效于\pset fieldsep_zero @@ -416,7 +416,7 @@ EOF - 设置非对齐输出的记录分隔符为零字节。例如,这对与xargs -0配合有关。这等效于\pset recordsep_zero。 + 设置非对齐输出的记录分隔符为零字节。例如,这有助于与xargs -0配合使用。这等效于\pset recordsep_zero @@ -476,10 +476,9 @@ EOF 分别指定这些参数。如果遇到一个不属于任何选项的参数, 它将被解释为数据库名(如果数据库名已经给出,则解释为数据库用户名)。 并非所有这些选项都是必需的;它们都有有用的默认值。如果省略主机名, - psql 在 Unix 上将通过 Unix 域套接字连接到本地主机上的服务器, - 在 Windows 上则通过 TCP/IP 连接到 localhost。默认端口号在编译时确定。 + psql 将通过 Unix 域套接字连接到本地主机上的服务器,而在没有 Unix 域套接字的机器上则通过 TCP/IP 连接到 localhost。默认端口号在编译时确定。 由于数据库服务器使用相同的默认值,因此在大多数情况下不必指定端口。 - 默认数据库用户名是你的操作系统用户名。数据库用户名确定后,它也会被用作默认数据库名。 + 默认用户名是你的操作系统用户名,默认数据库名也是如此。 请注意,你不能随意以任意数据库用户名连接到任意数据库。数据库管理员应当已经告知你拥有的访问权限。
@@ -540,7 +539,7 @@ testdb=> 元命令 - 你输入到psql中的任何以未加引用的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 + 你输入到psql中的任何以未加引号的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 @@ -557,7 +556,7 @@ testdb=> - 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉尾随换行)会替换反引号中的文本。在反引号包围的文本内部,不会发生特殊引用或其他处理,只有一种例外:如果出现:variable_name,且variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会被适当地引用成单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于回车和换行字符在所有平台上都无法安全引用,当变量值中出现这类字符时,:'variable_name'这种形式会打印错误消息,并且不会替换变量值。 + 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉末尾的换行符)会替换反引号中的文本。在反引号包围的文本内部,不会进行特殊的引号处理或其他处理,但出现:variable_name时,如果variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会适当地加上引号,使其成为单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于无法保证在所有平台上都能对回车和换行字符安全地加引号,当变量值中出现这类字符时,:'variable_name'形式会打印错误消息,并且不会替换变量值。 @@ -580,7 +579,7 @@ testdb=> \a - 如果当前表格输出格式是不对齐,则切换为对齐;否则切换为不对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset。 + 如果当前表格输出格式是非对齐,则切换为对齐;否则切换为非对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset @@ -601,7 +600,7 @@ testdb=> 默认情况下,参数在位置语法中被重用,但在给定conninfo字符串时不会被重用。 传递-reuse-previous=on-reuse-previous=off作为第一个参数将覆盖该默认设置。 如果参数被重用,则任何未明确指定为位置参数或在conninfo字符串中的参数将从现有连接的参数中获取。 - 一个例外是,如果使用位置语法将host设置更改为其先前值,则现有连接参数中存在的任何hostaddr设置将被删除。 + 一个例外是,如果使用位置语法更改host设置,使其不同于先前的值,则现有连接参数中存在的任何hostaddr设置将被删除。 此外,仅当用户、主机和端口设置未更改时,才会重用现有连接使用的任何密码。 当命令既不指定也不重用特定参数时,将使用libpq的默认值。 @@ -617,7 +616,7 @@ testdb=> => \c mydb myuser host.dom 6432 => \c service=foo => \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable" -=> \c -reuse-previous=on sslmode=require -- changes only sslmode +=> \c -reuse-previous=on sslmode=require -- 仅更改 sslmode => \c postgresql://tom@localhost/mydb?application_name=myapp
@@ -757,7 +756,9 @@ testdb=> \da[S] [ pattern ] - 列出聚合函数及其返回类型和操作的数据类型。如果指定了pattern,则只显示名称匹配该模式的聚合函数。默认只显示用户创建的对象;提供模式或S修饰符可包含系统对象。 + + 列出聚合函数,以及它们的返回类型和所作用的数据类型。如果指定了 pattern,则只显示名称与模式匹配的聚合。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 @@ -765,7 +766,10 @@ testdb=> \dA[+] [ pattern ] - 列出访问方法。如果指定了pattern,则只显示名称匹配该模式的访问方法。如果在命令名后附加+,还会列出每个访问方法关联的处理函数和描述。 + + 列出访问方法。如果指定了 pattern,则只显示名称与模式匹配的访问方法。如果在命令名后追加 +,则每个访问方法都会连同其关联的处理器函数和描述一起列出。 + @@ -773,7 +777,10 @@ testdb=> \db[+] [ pattern ] - 列出表空间。如果指定了pattern,则只显示名称匹配该模式的表空间。如果在命令名后附加+,还会列出每个表空间关联的选项、磁盘大小、权限和描述。 + + 列出表空间。如果指定了 pattern,则只显示名称与模式匹配的表空间。如果在命令名后追加 +,则每个表空间都会连同其关联选项、磁盘大小、权限和描述一起列出。 + @@ -781,7 +788,9 @@ testdb=> \dc[S+] [ pattern ] - 列出字符集编码之间的转换。如果指定了pattern,则只列出名称匹配该模式的转换。默认只显示用户创建的对象;提供模式或S修饰符可包含系统对象。如果在命令名后附加+,还会列出每个对象关联的描述。 + + 列出字符集编码之间的转换。如果指定了 pattern,则只列出名称与模式匹配的转换。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 +,则每个对象都会连同其相关描述一起列出。 + @@ -811,7 +820,10 @@ testdb=> \dD[S+] [ pattern ] - 列出域。如果指定了pattern,则只显示名称匹配该模式的域。默认只显示用户创建的对象;提供模式或S修饰符可包含系统对象。如果在命令名后附加+,还会列出每个对象关联的权限和描述。 + + 列出域。如果指定了 pattern,则只显示名称与模式匹配的域。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 +,则每个对象都会连同其相关权限和描述一起列出。 + @@ -892,28 +904,28 @@ testdb=> \dF[+] [ pattern ] - 列出文本搜索配置。如果指定了pattern,则只显示名称匹配该模式的配置。如果使用\dF+形式,则显示每个配置的完整说明,包括底层文本搜索解析器和每种解析器词元类型的词典列表。 + 列出全文检索配置。如果指定了pattern,则只显示名称匹配该模式的配置。如果使用\dF+形式,则显示每个配置的完整说明,包括底层全文检索解析器和每种解析器词元类型的词典列表。 \dFd[+] [ pattern ] - 列出文本搜索词典。如果指定了pattern,则只显示名称匹配该模式的词典。如果使用\dFd+形式,还会显示每个选中词典的附加信息,包括底层文本搜索模板和选项值。 + 列出全文检索词典。如果指定了pattern,则只显示名称匹配该模式的词典。如果使用\dFd+形式,还会显示每个选中词典的附加信息,包括底层全文检索模板和选项值。 \dFp[+] [ pattern ] - 列出文本搜索解析器。如果指定了pattern,则只显示名称匹配该模式的解析器。如果使用\dFp+形式,则显示每个解析器的完整说明,包括底层函数和可识别的词元类型列表。 + 列出全文检索解析器。如果指定了pattern,则只显示名称匹配该模式的解析器。如果使用\dFp+形式,则显示每个解析器的完整说明,包括底层函数和可识别的词元类型列表。 \dFt[+] [ pattern ] - 列出文本搜索模板。如果指定了pattern,则只显示名称匹配该模式的模板。如果使用\dFt+形式,还会显示每个模板的附加信息,包括底层函数名。 + 列出全文检索模板。如果指定了pattern,则只显示名称匹配该模式的模板。如果使用\dFt+形式,还会显示每个模板的附加信息,包括底层函数名。 @@ -936,7 +948,10 @@ testdb=> \dL[S+] [ pattern ] - 列出过程语言。如果指定了pattern,则只列出名称匹配该模式的语言。默认只显示用户创建的语言;提供S修饰符可包含系统对象。如果在命令名后附加+,还会列出每种语言的调用处理程序、验证器、访问权限,以及它是否为系统对象。 + + 列出过程语言。如果指定了 pattern,则只列出名称与模式匹配的语言。默认情况下,只显示用户创建的语言;提供 S 修饰符可包括系统对象。如果在命令名后追加 +,则每种语言都会连同其调用处理器、验证器、访问权限以及它是否为系统对象一起列出。 + @@ -945,7 +960,10 @@ testdb=> \dn[S+] [ pattern ] - 列出模式(命名空间)。如果指定了pattern,则只列出名称匹配该模式的模式。默认只显示用户创建的对象;提供模式或S修饰符可包含系统对象。如果在命令名后附加+,还会列出每个对象关联的权限和描述(如果有)。 + + 列出模式(命名空间)。如果指定了 pattern,则只列出名称与模式匹配的模式。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 +,则每个对象都会连同其相关权限和描述(如果有)一起列出。 + @@ -961,7 +979,9 @@ testdb=> \dO[S+] [ pattern ] - 列出排序规则。如果指定了pattern,则只列出名称匹配该模式的排序规则。默认只显示用户创建的对象;提供模式或S修饰符可包含系统对象。如果在命令名后附加+,还会列出每个排序规则关联的描述(如果有)。请注意,只会显示可用于当前数据库编码的排序规则,因此同一安装中的不同数据库可能会得到不同结果。 + + 列出排序规则。如果指定了 pattern,则只列出名称与模式匹配的排序规则。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 +,则每个排序规则都会连同其相关描述(如果有)一起列出。请注意,只会显示与当前数据库编码兼容的排序规则,因此在同一安装中的不同数据库里结果可能不同。 + @@ -978,7 +998,7 @@ testdb=> \drds [ role-pattern [ database-pattern ] ] - 列出已定义的配置设置。这些设置可以专属于角色、专属于数据库,或同时专属于两者。role-patterndatabase-pattern分别用于选择要列出的特定角色和数据库。如果省略,或指定了*,则列出所有设置,分别包括非角色专属或非数据库专属的设置。 + 列出已定义的配置设置。这些设置可以特定于角色、特定于数据库,或同时特定于两者。role-patterndatabase-pattern分别用于选择要列出的角色和数据库。省略某个模式参数或将其指定为*时,不会按该参数筛选,还会分别包含不特定于角色或不特定于数据库的设置。 命令用于定义角色专属和数据库专属的配置设置。 @@ -994,7 +1014,9 @@ testdb=> \dRs[+] [ pattern ] - 列出复制订阅。如果指定了pattern,则只列出名称匹配该模式的订阅。如果在命令名后附加+,还会显示订阅的附加属性。 + + 列出逻辑复制订阅。如果指定了 pattern,则只列出名称与模式匹配的订阅。如果在命令名后追加 +,则会显示订阅的其他属性。 + @@ -1024,7 +1046,9 @@ testdb=> \dy[+] [ pattern ] - 列出事件触发器。如果指定了pattern,则只列出名称匹配该模式的事件触发器。如果在命令名后附加+,还会列出每个对象关联的描述。 + + 列出事件触发器。如果指定了 pattern,则只列出名称与模式匹配的事件触发器。如果在命令名后追加 +,则每个对象都会连同其相关描述一起列出。 + @@ -1095,7 +1119,9 @@ Tue Oct 26 21:40:57 CEST 1999 \encoding [ encoding ] - 设置客户端字符集编码。如果没有参数,则显示当前编码。 + + 设置客户端字符集编码。没有参数时,此命令显示当前编码。 + @@ -1141,7 +1167,7 @@ Tue Oct 26 21:40:57 CEST 1999 - 设置未对齐查询输出的字段分隔符。默认值是竖线(|)。 + 设置非对齐查询输出的字段分隔符。默认值是竖线(|)。 它等同于\pset fieldsep @@ -1157,7 +1183,7 @@ Tue Oct 26 21:40:57 CEST 1999 如果当前查询缓冲区为空,则最近发送的查询将被重新执行。除此之外,没有任何参数的\g基本上等同于一个分号。 带有参数的\g提供了一个一次性替代\o命令的选择。
- 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号展开。该行剩余的内容只会原样传递给 shell。 + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 @@ -1211,7 +1237,7 @@ CREATE INDEX hello 10
- 如果指定了前缀,则会将该字符串加到查询的列名前面,以构成要使用的变量名: + 如果指定了prefix,则会将该字符串加到查询的列名前面,以构成要使用的变量名: => SELECT 'hello' AS var1, 10 AS var2 -> \gset result_ => \echo :result_var1 :result_var2 @@ -1240,7 +1266,7 @@ hello 10 给出指定SQL命令的语法帮助。如果未指定command, 则psql将列出所有可用语法帮助的命令。如果command是星号 - (*),则显示所有SQL命令的语法帮助。 + (*),则显示所有SQL命令的语法帮助。 @@ -1261,9 +1287,7 @@ hello 10 \H\html - 打开HTML查询输出格式。如果HTML格式已经打开, - 则切换回默认的对齐文本格式。此命令用于兼容性和便利性,但请参阅\pset - 有关设置其他输出选项。 + 打开HTML查询输出格式。如果HTML格式已经打开,则切换回默认的对齐文本格式。此命令是为兼容性和便利性而保留的;设置其他输出选项的方法见\pset @@ -1273,13 +1297,10 @@ hello 10 \i\include filename - 从文件filename中读取输入,并将其执行为 - 好像它是在键盘上键入的一样。 + 从文件filename中读取输入,并像在键盘上输入一样执行它。 - 如果filename- - (连字符),那么标准输入将被读取,直到EOF指示或\q元命令。 - 这可用于将交互式输入与文件输入交错使用。请注意,仅当在最外层级别处于活动状态时,Readline行为才会被使用。 + 如果filename-(连字符),则从标准输入读取,直到遇到 EOF 指示或\q元命令。这可用于将交互式输入与文件输入交错使用。请注意,只有在最外层启用了 Readline,此处才会使用 Readline 功能。 @@ -1298,36 +1319,20 @@ hello 10 这组命令实现了可嵌套的条件块。条件块必须以\if开始,以\endif结束。中间可以包含任意数量的\elif子句,后面还可以选择跟随一个\else子句。普通查询和其他类型的反斜线命令可以(通常也会)出现在构成条件块的命令之间。 - \if\elif命令读取它们的参数,并将其作为布尔表达式进行评估。 - 如果表达式为true,则处理将继续进行;否则,直到达到匹配的\elif、 - \else\endif为止,将跳过行。一旦\if或 - \elif测试成功,同一块中后续\elif命令的参数不会被评估,而是被视为false。 - 在\else之后的行只有在没有早期匹配的\if\elif成功时才会被处理。 + \if\elif命令读取其参数,并将其作为布尔表达式求值。如果表达式的值为true,则正常继续处理;否则,跳过后续行,直到遇到匹配的\elif\else\endif。一旦\if\elif测试成功,同一块中后续\elif命令的参数就不再求值,而是被视为假。只有前面所有匹配的\if\elif测试都未成功时,才会处理\else后面的行。 - expression参数 - 是\if\elif命令的参数, - 受变量插值和反引号扩展的影响,就像任何其他反斜杠命令参数一样。 - 之后,它被评估为一个开/关选项变量的值。因此,有效值是以下任何一个不 - 含糊的不区分大小写匹配之一: - true, false, 1, - 0, on, off, - yes, no。例如, - t, TtR - 都将被视为true。 + 与其他反斜线命令的参数一样,\if\elif命令的expression参数会经过变量插值和反引号扩展。随后,按开/关选项变量值的规则对结果求值。因此,有效值是以下值的不区分大小写且无歧义的匹配:truefalse10onoffyesno。例如,tTtR都会被视为true 不能正确求值为真或假的表达式会产生警告,并被视为假。 - 被跳过的行仍会正常解析,以识别查询和反斜线命令,但查询不会发送给服务器,条件命令(\if\elif\else\endif)以外的反斜线命令会被忽略。对于条件命令,只检查嵌套是否合法。被跳过的行中的变量引用不会展开,也不会执行反引号展开。 + 被跳过的行仍会正常解析,以识别查询和反斜线命令,但查询不会发送给服务器,条件命令(\if\elif\else\endif)以外的反斜线命令会被忽略。对于条件命令,只检查嵌套是否合法。被跳过的行中的变量引用不会展开,也不会执行反引号扩展。 - 所有给定条件块的反斜杠命令必须出现在同一个源文件中。如果在主输入文件或一个 - \include的文件上达到文件结束之前,所有本地 - \if块都没有关闭, - 那么psql将会引发错误。 + 同一个条件块的所有反斜线命令必须出现在同一个源文件中。如果主输入文件或通过\include引入的文件到达 EOF 时,仍有本地\if块未关闭,psql就会报错。 下面是一个示例: --- check for the existence of two separate records in the database and store --- the results in separate psql variables +-- 检查数据库中是否存在两条不同的记录,并将 +-- 结果分别存入不同的 psql 变量 SELECT EXISTS(SELECT 1 FROM customer WHERE customer_id = 123) as is_customer, EXISTS(SELECT 1 FROM employee WHERE employee_id = 456) as is_employee @@ -1373,7 +1378,7 @@ SELECT 从数据库中读取具有OIDloid的大对象,并将其写入filename。请注意,这与服务器函数 - lo_export略有不同,后者使用数据库服务器运行的用户权限, + lo_export略有不同,后者使用运行数据库服务器的用户的权限, 并在服务器的文件系统上操作。 @@ -1412,7 +1417,7 @@ lo_import 152801 - 从数据库中删除具有OIDloid的大对象。 + 从数据库中删除OIDloid的大对象。 @@ -1430,10 +1435,10 @@ lo_import 152801 将后续查询结果保存到文件filename,或通过管道传给 shell 命令command。如果没有指定参数,查询输出将恢复为标准输出。 - 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号展开。该行剩余的内容只会原样传递给 shell。 + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 - 查询结果包括从数据库服务器获取的所有表、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 + 查询结果包括从数据库服务器获取的所有表格、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 @@ -1448,7 +1453,10 @@ lo_import 152801 \p\print - 将当前查询缓冲区打印到标准输出。如果当前查询缓冲区为空,则改为打印最近执行的查询。 + + 将当前查询缓冲区打印到标准输出。 + 如果当前查询缓冲区为空,则打印最近执行的查询。 + @@ -1466,8 +1474,11 @@ lo_import 152801 \prompt [ text ] name - 提示用户提供文本,将其赋值给变量名称。还可以指定可选的提示字符串text。(对于多个单词的提示,用单引号括起文本。) + + 提示用户提供文本,将其赋值给变量name。 + 可以指定一个可选的提示字符串text。 + (对于多个单词的提示,用单引号括起文本。) + 默认情况下,\prompt 使用终端进行输入和输出。然而,如果使用了 @@ -1501,7 +1512,7 @@ lo_import 152801 零(默认值)会导致目标宽度由环境变量COLUMNS控制,或者如果未设置 COLUMNS则由检测到的屏幕宽度控制。 另外,如果columns为零,则wrapped格式仅影响屏幕输出。 - 如果columns为非零,则文件和管道输出也会被包装到该宽度。 + 如果columns为非零,则文件和管道输出也会按该宽度折行。 @@ -1546,11 +1557,11 @@ lo_import 152801 wrapped格式与aligned相似,但会将较宽的数据值折成多行,使输出适应目标列宽。目标宽度的确定方式见columns选项的说明。请注意,psql不会尝试对列标题折行;因此,如果列标题所需的总宽度超过目标宽度,wrapped格式的行为就与aligned相同。 - asciidochtml, - latexlatex-longtable,和 + asciidochtml、 + latexlatex-longtabletroff-ms格式生成的表格旨在包含在使用相应标记语言的文档中。 它们不是完整的文档!这在HTML中可能不是必需的,但在 - LaTeX中,则必须有一个完整的文档包装器。 + LaTeX中,则必须有一个完整文档的外层结构。 latex-longtable格式需要LaTeXlongtablebooktabs包。 @@ -1568,25 +1579,19 @@ lo_import 152801 - ascii样式使用普通的ASCII字符。数据中的换行使用右边边缘的+符号显示。 - 当wrapped格式将数据从一行换到下一行而没有换行符时,在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 + ascii样式使用普通的ASCII字符。数据中的换行符以右边缘的+符号表示。当wrapped格式在没有换行符的位置把数据折到下一行时,会在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 - old-ascii样式使用普通的ASCII字符,使用在PostgreSQL 8.4及更早版本中使用的格式样式。 - 数据中的换行符使用:符号代替左侧列分隔符显示。 - 当数据从一行换行到下一行而没有换行符时,使用;符号代替左侧列分隔符。 + old-ascii样式使用普通的ASCII字符,采用PostgreSQL 8.4 及更早版本的格式样式。数据中的换行符以替代左侧列分隔符的:符号表示。当数据在没有换行符的位置折到下一行时,则用;符号替代左侧列分隔符。 - unicode样式使用Unicode绘图字符。数据中的换行使用右边距中的回车符号显示。 - 当数据从一行换行到下一行而没有换行符时,第一行的右边距显示省略号符号, - 接着在下一行的左边距再次显示省略号符号。 + unicode样式使用 Unicode 框线绘制字符。数据中的换行符以右边缘的回车符号表示。当数据在没有换行符的位置折到下一行时,会在第一行的右边缘显示省略号符号,并在下一行的左边缘再次显示。 - 当border设置大于零时,linestyle选项还确定了用哪些字符绘制边框线。 - 普通的ASCII字符在任何地方都有效,但在识别Unicode字符的显示器上看起来更好。 + 当border设置大于零时,linestyle选项还决定用哪些字符绘制边框线。普通的ASCII字符在任何环境中都可用,但在支持 Unicode 的显示设备上,Unicode 字符更美观。 @@ -1706,7 +1711,7 @@ lo_import 152801 \qecho text [ ... ] - 这个命令与\echo命令相同,只是输出将被写入查询输出通道,由\o设置。 + 这个命令与\echo相同,只是输出会写入由\o设置的查询输出通道。 @@ -1736,9 +1741,7 @@ lo_import 152801 \set [ name [ value [ ... ] ] ] - psql变量名称设置为,如果给出多个值,则设置为所有值的串接。如果只给出一个参数,则将变量设置为空字符串值。要取消变量设置,请使用\unset命令。 + psql变量name设置为value,如果给出多个值,则设置为所有值的串接。如果只给出一个参数,则将变量设置为空字符串值。要取消变量设置,请使用\unset命令。 \set没有任何参数时,显示当前设置的所有psql变量的名称和值。 @@ -1759,9 +1762,10 @@ lo_import 152801 \setenv name [ value ] - 将环境变量名称设置为;如果没有提供,则取消设置该环境变量。例如: + + 设置环境变量namevalue, + 或者如果未提供value,则取消设置环境变量。示例: + testdb=> \setenv PAGER less testdb=> \setenv LESS -imx4F @@ -1795,8 +1799,7 @@ testdb=> \setenv LESS -imx4F - 这个命令获取并显示指定视图的定义,以CREATE OR REPLACE VIEW命令的形式。 - 定义将打印到当前查询输出通道,由\o设置。 + 这个命令获取指定视图的定义,并以CREATE OR REPLACE VIEW命令的形式显示。定义会打印到由\o设置的当前查询输出通道。 @@ -1852,7 +1855,7 @@ testdb=> \setenv LESS -imx4F 将当前查询缓冲区写入文件filename,或通过管道传递给 shell 命令command。如果当前查询缓冲区为空,则改为写入最近执行的查询。 - 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号展开。该行剩余的内容只会原样传递给 shell。 + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 @@ -1860,8 +1863,13 @@ testdb=> \setenv LESS -imx4F \watch [ seconds ] - 重复执行当前查询缓冲区(如同\g),直到被中断或查询失败。每次执行之间等待指定的秒数(默认为 2)。每个查询结果都会显示一个标题,其中包含\pset title字符串(如果有)、查询开始时间和延迟间隔。 - 如果当前查询缓冲区为空,则改为重新执行最近发送的查询。 + + 重复执行当前查询缓冲区(如同 \g 一样),直到被中断或查询失败。两次执行之间等待指定的秒数(默认 2 秒)。每次查询结果都会带有一个头部,其中包含 \pset title + 字符串(如果有)、查询开始时的时间以及延迟间隔。 + + + 如果当前查询缓冲区为空,则重新执行最近发送的查询。 + @@ -1890,13 +1898,11 @@ testdb=> \setenv LESS -imx4F \! [ command ] - 不带参数时,转义到一个子shell;psql在子shell退出时恢复。 - 带参数时,执行shell命令command。 + 不带参数时,进入一个子 shell;子 shell 退出后,psql恢复运行。带参数时,执行 shell 命令command - 与大多数其他元命令不同,整个行的剩余部分始终被视为\!的参数, - 在参数中不执行变量插值或反引号扩展。行的其余部分被直接传递给shell。 + 与大多数其他元命令不同,该行剩余的全部内容始终被视为\!的参数,其中不会进行变量插值或反引号扩展。该行剩余内容会原样传给 shell。 @@ -1908,7 +1914,7 @@ testdb=> \setenv LESS -imx4F 显示帮助信息。可选的topic参数 (默认为commands)选择要解释的psql的哪个部分: - commands描述psql的反斜杠命令; + commands描述psql的反斜线命令; options描述可以传递给psql的命令行选项; 而variables显示关于psql配置变量的帮助。 @@ -1937,12 +1943,12 @@ select 1\; select 2\; select 3; 模式 - patterns + 模式 在 psql 和 pg_dump 中 - 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要把它写成两个相邻的双引号,这同样是符合 SQL 引用标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你不能只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 + 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要在双引号包围的文本内把它写成两个相邻的双引号,这同样是符合 SQL 加引号标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你可以只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 @@ -1986,7 +1992,7 @@ bar - 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要重置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 + 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要取消设置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 @@ -2000,7 +2006,7 @@ bar - 控制psql行为的变量通常不能被重置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse。 + 控制psql行为的变量通常不能被取消设置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse @@ -2018,7 +2024,7 @@ bar - 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被重置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交打开模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身即不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 + 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被取消设置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交关闭模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身既不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 @@ -2048,7 +2054,7 @@ bar DBNAME - 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -2057,7 +2063,7 @@ bar ECHO - 如果被设置为all,所有非空输入行会被按照读入它们的样子打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被重置或者设置为none(默认值)则不会显示任何查询。 + 如果被设置为all,所有非空输入行会在读入时打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被设置为none(默认值)则不会显示任何查询。 @@ -2075,7 +2081,7 @@ bar ENCODING - 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者重置。 + 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者取消设置。 @@ -2093,12 +2099,12 @@ bar FETCH_COUNT - 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每一组就会包括这么多个行。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 + 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每组包含的行数等于该整数值。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 - 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT个行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 + 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 @@ -2108,7 +2114,7 @@ bar HISTCONTROL - 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则匹配之前的历史行的行不会被放入。值ignoreboth组合了上述两种值。如果被重置或者被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 + 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则与上一条历史记录相同的行不会被放入。值ignoreboth组合了上述两种值。如果被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 @@ -2150,7 +2156,7 @@ bar HOST - 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -2159,7 +2165,7 @@ bar IGNOREEOF - 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须键入多个连续的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 + 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须连续键入与该数值相等数量的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 @@ -2197,7 +2203,7 @@ bar - 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被重置或者设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 + 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 @@ -2215,7 +2221,7 @@ bar PORT - 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -2256,7 +2262,7 @@ bar SERVER_VERSION_NUM - 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者重设。 + 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者取消设置。 @@ -2265,7 +2271,7 @@ bar SHOW_CONTEXT - 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT域。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 + 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT字段。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 当VERBOSITY被设置为terse时,这个设置无效(另见\errverbose,它可以用来得到刚遇到的错误的详细信息)。 @@ -2284,7 +2290,7 @@ bar SINGLESTEP - 设置这个变量为on等效于命令选项。 + 设置这个变量为on等效于命令行选项 @@ -2302,7 +2308,7 @@ bar USER - 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -2311,7 +2317,7 @@ bar VERBOSITY - 这个变量可以被设置为值defaultverbose或者terse来控制错误报告的详细程度(另见\errverbose,在想得到之前的错误的详细版本时使用)。 + 这个变量可以被设置为值defaultverbose或者terse来控制错误报告的详细程度(另见\errverbose,在想得到刚遇到的错误的详细信息时使用)。 @@ -2322,7 +2328,7 @@ bar VERSION_NUM - 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或重设。 + 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或取消设置。 @@ -2332,10 +2338,10 @@ bar - <acronym>SQL</acronym> 中插入变量 + <acronym>SQL</acronym> 插值 - psql变量的一个关键特性是可以把它们替换(插入)到常规SQL语句中,也可以把它们作为元命令的参数。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。插入一个值而不加引号的语法是在变量名前面加上一个冒号(:)。例如, + psql变量的一个关键特性是可以把它们替换(插值)到常规SQL语句中,也可以把它们替换到元命令的参数中。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。不加引号地插值一个值的语法是在变量名前面加上一个冒号(:)。例如, testdb=> \set foo 'my_table' testdb=> SELECT * FROM :foo; @@ -2344,7 +2350,7 @@ testdb=> SELECT * FROM :foo; - 当一个值被用作 SQL 文本或者标识符时,最安全的是把它加上引用。要引用一个变量的值作为 SQL 文本,可以把变量名称放在单引号中并且在引号前面写一个冒号。要引用作为 SQL 标识符,则可以把变量名称放在双引号中并且在引号前面写一个冒号。这种结构可以正确地处理变量值中嵌入的引号和其他特殊字符。之前的示例用这种方法写会更安全: + 当一个值要用作 SQL 字面量或标识符时,最安全的做法是为它加上引号。要将变量值作为 SQL 字面量加引号,应写一个冒号,后面跟用单引号括起来的变量名。要将变量值作为 SQL 标识符加引号,则在冒号后面用双引号括起变量名。这些写法能正确处理变量值中嵌入的引号和其他特殊字符。前面的示例可用以下更安全的写法: testdb=> \set foo 'my_table' testdb=> SELECT * FROM :"foo"; @@ -2352,11 +2358,11 @@ testdb=> SELECT * FROM :"foo"; - 在被引用的SQL文本和标识符中将不会执行变量插入。因此,一个诸如':foo'的结构不会从一个变量的值产生一个被引用的文本(即便能够也会不安全,因为无法正确地处理嵌入在值中的引号)。 + 在加引号的SQL字面量和标识符内部,不会执行变量插值。因此,':foo'这样的写法不能根据变量值生成加引号的字面量(即使能够生效,也不安全,因为它无法正确处理变量值中嵌入的引号)。 - 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个被引用的字符串插入: + 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个加引号的字符串进行插值: testdb=> \set content `cat my_file.txt` testdb=> INSERT INTO my_table VALUES (:'content'); @@ -2365,7 +2371,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 因为冒号可以合法地出现在 SQL 命令中,一次明显的插入尝试(即:name:'name'或者:"name")不会被替换,除非所提及的变量就是当前被设置的。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 + 因为冒号可以合法地出现在 SQL 命令中,一次明显的插值尝试(即:name:'name'或者:"name")不会被替换,除非所指的变量当前已设置。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 @@ -2373,7 +2379,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 文本或者标识符的冒号引用语法是一种psql扩展。 + 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 字面量或者标识符的冒号加引号语法是一种psql扩展。 @@ -2408,7 +2414,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %n - 数据库会话用户名。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的展开结果。) + 数据库会话用户名。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) @@ -2419,20 +2425,21 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %~ - %/相同,但如果该数据库是你的默认数据库,则输出~(波浪号)。 + 类似 %/,但如果该数据库是你的默认数据库,则输出 ~ + (波浪号)。 %# - 如果会话用户是数据库超级用户,则为#,否则为>。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的展开结果。) + 如果会话用户是数据库超级用户,则为#,否则为>。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) %p - 当前连接的后端的进程 ID。 + 当前所连接后端的进程 ID。 @@ -2440,7 +2447,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %R - 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 dollar-quoted 字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 + 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 美元引用字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 @@ -2467,7 +2474,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %digits - 带有所示八进制码的字符被替换。 + 替换为指定八进制代码对应的字符。 @@ -2610,9 +2617,9 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 如果查询结果无法在屏幕上显示完整,它们将通过此命令进行传输。典型的值是moreless。 + 如果查询结果无法在屏幕上显示完整,它们会通过管道传给此命令。典型的值是moreless。 可以通过将PSQL_PAGERPAGER设置为空字符串,或通过调整\pset命令的与分页相关的选项来禁用分页器。 - 这些变量按照列出的顺序进行检查;首先设置的变量将被使用。 + 这些变量按照列出的顺序进行检查;使用按该顺序找到的第一个已设置的变量。 如果它们都没有设置,默认情况下在大多数平台上使用more,但在Cygwin上使用less @@ -2673,11 +2680,11 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' 用户的个人启动文件名为.psqlrc,并且在调用用户的主目录中寻找。 - 在Windows上,个人启动文件的名称改为%APPDATA%\postgresql\psqlrc.conf。 + Windows 没有主目录这一概念,在 Windows 上,个人启动文件的名称为%APPDATA%\postgresql\psqlrc.conf。 在任何情况下,可以通过设置PSQLRC环境变量来覆盖此默认文件路径。 - 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加连字符和PostgreSQL的主版本或次版本号来使其与psql版本相关, + 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加连字符和PostgreSQL的大版本或小版本号来使其与psql版本相关, 例如~/.psqlrc-9.2~/.psqlrc-9.2.5。 最具体版本匹配的文件将优先读取,而不是非特定版本的文件。 @@ -2704,14 +2711,14 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - psql最适合与相同或较旧主要版本的服务器配合使用。 - 如果服务器的版本比psql本身更新,反斜杠命令特别容易失败。 - 然而,\d系列的反斜杠命令应该可以在版本回溯到9.2的服务器上运行, + psql最适合与相同或较旧大版本的服务器配合使用。 + 如果服务器的版本比psql本身更新,反斜线命令特别容易失败。 + 然而,\d系列的反斜线命令应该可以在最低至 7.4 版本的服务器上运行, 但不一定适用于比psql本身更新的服务器。运行SQL命令和显示查询结果的一般功能 - 也应该可以在更新主要版本的服务器上运行,但不能保证在所有情况下都能实现。 + 也应该可以在更新大版本的服务器上运行,但不能保证在所有情况下都能实现。 - 如果你想用psql连接到多个具有不同主版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个主版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 + 如果你想用psql连接到多个具有不同大版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个大版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 @@ -2725,7 +2732,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空格。现在则要求一些空格。 + 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空白。现在则要求用空白分隔。 @@ -2783,6 +2790,7 @@ peter@localhost testdb=> SELECT * FROM my_table; 3 | three 4 | four (4 rows) + 要以不同方式显示表格,可以使用\pset命令: peter@localhost testdb=> \pset border 2 Border style is 2. @@ -2861,10 +2869,10 @@ testdb=> \crosstabview first second (4 rows) 第二个示例显示一个乘法表,行按数值降序排列,列则独立地按数值升序排列。 testdb=> SELECT t1.first as "A", t2.first+100 AS "B", t1.first*(t2.first+100) as "AxB", -testdb(> row_number() over(order by t2.first) AS ord -testdb(> FROM my_table t1 CROSS JOIN my_table t2 ORDER BY 1 DESC -testdb(> \crosstabview "A" "B" "AxB" ord - A | 101 | 102 | 103 | 104 +testdb-> row_number() over(order by t2.first) AS ord +testdb-> FROM my_table t1 CROSS JOIN my_table t2 ORDER BY 1 DESC +testdb-> \crosstabview "A" "B" "AxB" ord + A | 101 | 102 | 103 | 104 ---+-----+-----+-----+----- 4 | 404 | 408 | 412 | 416 3 | 303 | 306 | 309 | 312 diff --git a/zh/11/release-11.sgml b/zh/11/release-11.sgml index 3b9af4d4..72d99971 100644 --- a/zh/11/release-11.sgml +++ b/zh/11/release-11.sgml @@ -1093,7 +1093,7 @@ Branch: REL_12_STABLE [3b4580f5c] 2023-06-24 17:18:08 -0400 Branch: REL_11_STABLE [c7f33a197] 2023-06-24 17:18:08 -0400 --> - 防止非常复杂的文本搜索模式导致栈溢出崩溃 + 防止非常复杂的文本检索模式导致栈溢出崩溃 (Tom Lane) @@ -2745,7 +2745,7 @@ Branch: REL_12_STABLE [1aed4c4fd] 2022-11-21 17:07:07 -0500 Branch: REL_11_STABLE [c0eed8891] 2022-11-21 17:07:07 -0500 --> - 确保在执行短语匹配时可以取消全文搜索查询的执行(Tom Lane) + 确保在执行短语匹配时可以取消全文检索查询的执行(Tom Lane) @@ -11639,7 +11639,7 @@ Branch: REL_11_STABLE [98a4d6950] 2020-04-27 12:21:04 -0400 Branch: REL_10_STABLE [072a86327] 2020-04-27 12:21:04 -0400 Branch: REL9_6_STABLE [22dcb6c20] 2020-04-27 12:21:04 -0400 --> - 修复全文搜索,使其正确处理短语搜索之上的 NOT(Tom Lane) + 修复全文检索,使其正确处理短语搜索之上的 NOT(Tom Lane) !(foo<->bar) 等查询在通过 GiST 或 GIN 索引搜索执行时,无法找到匹配行。 @@ -11653,7 +11653,7 @@ Branch: REL_11_STABLE [5db48808c] 2020-05-07 15:59:52 -0400 Branch: REL_10_STABLE [26cf16a93] 2020-05-07 15:59:52 -0400 Branch: REL9_6_STABLE [7c9d9aa5c] 2020-05-07 15:59:52 -0400 --> - 修复短语搜索包含同时具有前缀匹配和权重限制的项时的全文搜索(Tom Lane) + 修复短语搜索包含同时具有前缀匹配和权重限制的项时的全文检索(Tom Lane) @@ -13735,7 +13735,7 @@ Branch: REL_11_STABLE [88d03d73c] 2019-11-03 16:10:45 -0500 Branch: REL_10_STABLE [4077e9ae1] 2019-11-03 16:10:56 -0500 Branch: REL9_6_STABLE [d43bd9dce] 2019-11-03 16:11:05 -0500 --> - 避免 ispell 文本搜索词典包含错误的词缀数据时发生崩溃(Arthur Zakirov) + 避免 ispell 文本检索词典包含错误的词缀数据时发生崩溃(Arthur Zakirov) @@ -17280,7 +17280,7 @@ Branch: REL9_3_STABLE [33c697e9d] 2018-11-03 13:56:10 -0400 --> 修复字符类检查,使其在 Windows 上不会因高于 U+FFFF 的 Unicode 字符而失败(Tom Lane,Kenji Uno) - 此缺陷影响全文搜索操作,以及 contrib/ltreecontrib/pg_trgm + 此缺陷影响全文检索操作,以及 contrib/ltreecontrib/pg_trgm @@ -18734,7 +18734,7 @@ same commits as above 2018-04-05 [1664ae197] Add websearch_to_tsquery --> - 添加文本搜索函数 websearch_to_tsquery(),支持类似网页搜索引擎所用的查询语法(Victor Drobny,Dmitry Ivanov) + 添加文本检索函数 websearch_to_tsquery(),支持类似网页搜索引擎所用的查询语法(Victor Drobny,Dmitry Ivanov) @@ -18742,7 +18742,7 @@ same commits as above 2018-04-07 [1c1791e00] Add json(b)_to_tsvector function --> - 添加函数 json(b)_to_tsvector(),以创建用于匹配 JSON/JSONB 值的文本搜索查询(Dmitry Dolgov) + 添加函数 json(b)_to_tsvector(),以创建用于匹配 JSON/JSONB 值的文本检索查询(Dmitry Dolgov) diff --git a/zh/11/rowtypes.sgml b/zh/11/rowtypes.sgml index 69a9df49..da3df234 100644 --- a/zh/11/rowtypes.sgml +++ b/zh/11/rowtypes.sgml @@ -58,17 +58,21 @@ SELECT price_extension(item, 10) FROM on_hand; - 每当创建一张表时,也会自动创建一个与该表同名的复合类型,用来表示表的行类型。例如,假如我们执行了: + + 每当你创建一个表时,系统也会自动创建一个与该表同名的复合类型,用来表示该表的行类型。例如,如果我们这样写: + CREATE TABLE inventory_item ( name text, supplier_id integer REFERENCES suppliers, price numeric CHECK (price > 0) ); -那么,与上文相同的inventory_item复合类型就会随之产生,而且可以像上文那样使用。不过,请注意当前实现的一个重要限制:由于复合类型本身不关联任何约束,表定义中的约束并不适用于表外的复合类型值。(要解决这一问题,可以在复合类型上创建一个域,并将所需约束定义为该域的 CHECK 约束。) + + 那么上面展示的同一个inventory_item复合类型也会顺带生成,并且同样可以像前面那样使用。不过,当前实现有一个重要限制:由于复合类型本身不关联任何约束,表定义中给出的那些约束在表之外的复合类型值上并不适用。(解决办法是:在该复合类型之上创建一个域,并把所需的约束作为该域的CHECK约束。) + - 构造组合值 + 构造复合值 复合类型 @@ -76,7 +80,7 @@ CREATE TABLE inventory_item ( - 要把组合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,组合常量的一般格式如下: + 要把复合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,复合常量的一般格式如下: '( val1 , val2 , ... )' @@ -96,16 +100,21 @@ CREATE TABLE inventory_item ( - (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。必要时可能需要显式指定类型。) + (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。可能需要显式指定类型,以指明应将该常量转换为哪种类型。) - 这种ROW表达式语法也可以用于构造复合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: + + ROW表达式语法也可以用于构造复合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: + ROW('fuzzy dice', 42, 1.99) ROW('', 42, NULL) -只要表达式中有多个字段,ROW 关键字实际上是可选的,因此这些可以简写为: + + 只要表达式中有多个字段,ROW 关键字实际上是可选的,因此这些可以简写为: + ('fuzzy dice', 42, 1.99) ('', 42, NULL) -这种ROW表达式语法的更多细节见。 + + 关于ROW表达式语法的更多细节,见 @@ -114,7 +123,7 @@ ROW('', 42, NULL) 访问复合类型 - 要访问组合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: + 要访问复合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: SELECT item.name FROM on_hand WHERE item.price > 9.99; @@ -136,7 +145,7 @@ SELECT (on_hand.item).name FROM on_hand WHERE (on_hand.item).price > 9.99; - 无论何时从组合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回组合值的函数结果中只选取一个字段,你需要这样写: + 无论何时从复合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回复合值的函数结果中只选取一个字段,你需要这样写: SELECT (my_func(...)).field FROM ... @@ -151,10 +160,10 @@ SELECT (my_func(...)).field FROM ... - 修改组合值 + 修改复合类型 - 下面是一些插入和更新组合列时正确语法的示例。先看插入或更新整个列值的情况: + 下面是一些插入和更新复合列时正确语法的示例。先看插入或更新整个列值的情况: INSERT INTO mytab (complex_col) VALUES((1.1,2.2)); @@ -166,7 +175,7 @@ UPDATE mytab SET complex_col = ROW(1.1,2.2) WHERE ...; - 我们也可以更新组合列中的单个子字段: + 我们也可以更新复合列中的单个子字段: UPDATE mytab SET complex_col.r = (complex_col).r + 1 WHERE ...; @@ -194,11 +203,11 @@ INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2); - 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的组合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: + 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的复合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: SELECT c FROM inventory_item c; - 这个查询会产生一个单独的组合值列,因此我们可能得到如下输出: + 这个查询会产生一个单独的复合值列,因此我们可能得到如下输出: c ------------------------ @@ -209,7 +218,7 @@ SELECT c FROM inventory_item c; - 普通的限定列名语法table_name.column_name可以理解为对该表当前行的组合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) + 普通的限定列名语法table_name.column_name可以理解为对该表当前行的复合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) @@ -237,16 +246,23 @@ SELECT (myfunc(x)).a, (myfunc(x)).b, (myfunc(x)).c FROM some_table; - PostgreSQL处理列展开时,实际上会把第一种形式转换成第二种形式。因此,在这个示例中,myfunc()每行都会被调用三次,无论采用哪种语法。如果它是一个开销较大的函数,你可能希望避免这种情况,可以使用如下查询: + PostgreSQL处理列展开时,实际上会把第一种形式转换成第二种形式。因此,在这个示例中,无论使用哪种语法,myfunc()每行都会被调用三次。如果它是一个开销较大的函数,你可能希望避免这种情况,可以使用如下查询: + SELECT m.* FROM some_table, LATERAL myfunc(x) AS m; -将函数放在一个 LATERAL FROM 项中,可以避免它在每行上被调用多次。m.* 仍会展开成 m.a, m.b, m.c,但现在这些变量只是引用 FROM 项的输出。(LATERAL 关键字在这里是可选的,但我们把它写出来,以明确该函数所取得的 x 来自 some_table。) + + 把该函数放在LATERAL FROM项中,可以避免它在每行上被调用多次。m.*仍会展开为m.a, m.b, m.c,但现在这些变量只是对该FROM项输出的引用。(这里的LATERAL关键字其实是可选的,不过我们把它写出来,是为了明确该函数会从some_table中取得x。) - 这里的composite_value.*语法在以下结构的顶层出现时会产生这类列展开:(SELECT输出列表)、RETURNING列表(位于INSERT/UPDATE/DELETE)、VALUES子句,或行构造器。在所有其他上下文中(包括嵌套在上述结构之内时),将.*附加到复合值上不会改变该值,因为它表示所有列,因此结果仍然是同一个复合值。例如,如果somefunc()接受一个复合值参数,这些查询就是等价的: + + 当composite_value.*出现在SELECT输出列表、INSERT/UPDATE/DELETE中的RETURNING列表、VALUES子句或行构造器的顶层时,就会产生这种列展开行为。在所有其他上下文中(包括嵌套在上述结构之内时),给复合值附加.*不会改变其值,因为它表示所有列,因此结果仍然是同一个复合值。例如,如果somefunc()接受一个复合值参数,这些查询就是等价的: + + SELECT somefunc(c.*) FROM inventory_item c; SELECT somefunc(c) FROM inventory_item c; -在这两种情况下,inventory_item的当前行都会作为单个复合值参数传递给该函数。即使.*在这种情况下不起作用,使用它仍是良好的风格,因为它明确表示这里需要的是复合值。特别是,解析器会将c(位于c.*)解释为表名或别名,而不是列名,因此不存在歧义;但如果没有.*,就不能明确判断c表示表名还是列名,而且会优先采用列名解释,只要存在一列名为c。 + + + 在这两种情况下,inventory_item的当前行都会作为单个复合值参数传递给该函数。尽管.*在这种场合并不起作用,使用它仍是一种良好风格,因为它能明确表明这里想要的是复合值。特别是,解析器会把c.*中的c视为表名或别名,而不是列名,因此不会产生歧义;而没有.*时,就不清楚c究竟表示表名还是列名,而且如果存在名为c的列,实际上会优先按列名解释。 @@ -256,7 +272,7 @@ SELECT * FROM inventory_item c ORDER BY c; SELECT * FROM inventory_item c ORDER BY c.*; SELECT * FROM inventory_item c ORDER BY ROW(c.*); - 所有这些ORDER BY子句都指定了该行的组合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: + 所有这些ORDER BY子句都指定了该行的复合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: SELECT * FROM inventory_item c ORDER BY ROW(c.name, c.supplier_id, c.price); SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); @@ -265,7 +281,7 @@ SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); - 另一种与组合值有关的特殊语法行为是,我们可以使用函数记法来提取组合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: + 另一种与复合值有关的特殊语法行为是,我们可以使用函数记法来提取复合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: SELECT c.name FROM inventory_item c WHERE c.price > 1000; @@ -284,11 +300,11 @@ SELECT c.somefunc FROM inventory_item c; 函数记法与字段记法之间的这种等价性,使得我们可以通过在复合类型上使用函数来实现计算字段 - computed field + 计算字段 - field - computed + 字段 + 计算 使用上面最后一种查询形式的应用程序,无需直接知道somefunc并不是该表中的真实列。 @@ -306,7 +322,7 @@ SELECT c.somefunc FROM inventory_item c; 复合类型的输入和输出语法 - 组合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明组合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 + 复合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明复合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 '( 42)' @@ -314,7 +330,7 @@ SELECT c.somefunc FROM inventory_item c; - 如前所示,在写组合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让组合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的组合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作组合语法的数据字符。 + 如前所示,在写复合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让复合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的复合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作复合语法的数据字符。 @@ -328,18 +344,18 @@ SELECT c.somefunc FROM inventory_item c; - 记住,你在 SQL 命令中写的内容会先被解释为字符串字面量,然后才会被解释为组合值。这会使所需的反斜杠数量翻倍(假定使用的是转义字符串语法)。例如,要在组合值中插入一个包含双引号和反斜杠的text字段,需要写成: + 记住,你在 SQL 命令中写的内容会先被解释为字符串字面量,然后才会被解释为复合值。这会使所需的反斜杠数量翻倍(假定使用的是转义字符串语法)。例如,要在复合值中插入一个包含双引号和反斜杠的text字段,需要写成: INSERT ... VALUES ('("\"\\")'); - 字符串字面量处理器会去掉一层反斜杠,因此传到组合值解析器时看起来是("\"\\")。随后,送入text数据类型输入例程的字符串就变成了"\。(如果我们使用的数据类型的输入例程也会把反斜杠当作特殊字符处理,例如bytea,那么为了在存储的组合字段中得到一个反斜杠,命令里可能需要多达八个反斜杠。)美元引用(见)可用于避免反斜杠加倍的需要。 + 字符串字面量处理器会去掉一层反斜杠,因此传到复合值解析器时看起来是("\"\\")。随后,送入text数据类型输入例程的字符串就变成了"\。(如果我们使用的数据类型的输入例程也会把反斜杠当作特殊字符处理,例如bytea,那么为了在存储的复合字段中得到一个反斜杠,命令里可能需要多达八个反斜杠。)美元引用(见)可用于避免反斜杠加倍的需要。 - 在 SQL 命令中编写组合值时,ROW构造器语法通常比组合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是组合成员时完全相同。 + 在 SQL 命令中编写复合值时,ROW构造器语法通常比复合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是复合成员时完全相同。 diff --git a/zh/11/textsearch.sgml b/zh/11/textsearch.sgml index af545bdb..24be23a5 100644 --- a/zh/11/textsearch.sgml +++ b/zh/11/textsearch.sgml @@ -1,21 +1,21 @@ - 全文搜索 + 全文检索 - 全文搜索 + 全文检索 - 文本搜索 + 文本检索 介绍 - 全文检索(或简称文本搜索)提供了识别满足 + 全文检索(或简称文本检索)提供了识别满足 查询条件的自然语言文档的能力, 并且可按它们与查询的相关度进行排序。最常见的搜索类型,是找出所有包含给定 查询词的文档,并按它们与查询的相似性 @@ -25,7 +25,7 @@ - 文本搜索操作符在数据库中已经存在很多年了。 + 文本检索操作符在数据库中已经存在很多年了。 PostgreSQL为文本数据类型提供了 ~~*LIKEILIKE 操作符,但它们缺少现代信息系统所要求的许多关键特性: @@ -138,7 +138,7 @@ ()。围绕这两种数据类型还有许多函数和 操作符(),其中最重要的是匹配操作符 @@,我们将在中介绍。 - 全文搜索还可以借助索引加速()。 + 全文检索还可以借助索引加速()。 @@ -147,11 +147,11 @@ 文档 - 全文搜索 + 文本检索 - 文档是全文搜索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本搜索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 + 文档是全文检索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本检索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 @@ -179,7 +179,7 @@ WHERE m.mid = d.did AND m.mid = 12; - 为了进行文本搜索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 + 为了进行文本检索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 @@ -187,7 +187,7 @@ WHERE m.mid = d.did AND m.mid = 12; 基本文本匹配 - 在PostgreSQL中,全文搜索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: + 在PostgreSQL中,全文检索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: SELECT 'a fat cat sat on a mat and ate a fat rat'::tsvector @@ 'cat & rat'::tsquery; @@ -203,7 +203,7 @@ SELECT 'fat & cow'::tsquery @@ 'a fat cat sat on a mat and ate a fat rat'::t - 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索术语,这些术语必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个术语组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本搜索匹配更像是这样: + 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索词,这些搜索词必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个搜索词组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本检索匹配更像是这样: SELECT to_tsvector('fat cats ate fat rats') @@ to_tsquery('fat & rat'); @@ -221,7 +221,7 @@ SELECT 'fat cats ate fat rats'::tsvector @@ to_tsquery('fat & rat'); f - 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,默认假定已经正规化,因此 rats 不会匹配 rat。 + 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,被假定为已经正规化,因此 rats 不会匹配 rat @@ -290,49 +290,49 @@ SELECT phraseto_tsquery('the cats ate the rats'); 配置 - 前述的都是简单的文本搜索示例。正如前面所提到的,全文搜索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如基于空白之外的解析。这个功能由文本搜索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 + 前述的都是简单的文本检索示例。正如前面所提到的,全文检索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如不局限于按空白划分的解析。这个功能由文本检索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 - 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本搜索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config。 + 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本检索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config - 依赖一个配置的每一个文本搜索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当这个参数被忽略时,default_text_search_config才被使用。 + 依赖一个配置的每一个文本检索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当省略这个参数时,default_text_search_config才被使用。 - 为了让建立自定义文本搜索配置更容易,一个配置可以从更简单的数据库对象来建立。PostgreSQL的文本搜索功能提供了四类配置相关的数据库对象: + 为了便于构建自定义文本检索配置,配置由更简单的数据库对象组合而成。PostgreSQL 的文本检索功能提供了四类与配置相关的数据库对象: - 文本搜索解析器将文档拆分成词元并分类每个词元(例如,作为词或者数字)。 + 文本检索解析器将文档拆分成词元并对每个词元分类(例如,作为词或者数字)。 - 文本搜索词典将词元转变成正规化的形式并拒绝停用词。 + 文本检索词典将词元转变成正规化的形式并拒绝停用词。 - 文本搜索模板提供位于词典底层的函数(一个词典简单地指定一个模板和一组用于模板的参数)。 + 文本检索模板提供位于词典底层的函数(词典只需指定一个模板及其一组参数)。 - 文本搜索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 + 文本检索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 - 文本搜索解析器和模板是从低层 C 函数构建而来,因此它要求 C 编程能力来开发新的解析器和模板,并且还需要超级用户权限来把它们安装到一个数据库中(在PostgreSQL发布的contrib/区域中有一些附加的解析器和模板的示例)。由于词典和配置只是对底层解析器和模板的参数化和连接,不需要特殊的权限来创建一个新词典或配置。创建定制词典和配置的示例将在本章稍后的部分给出。 + 文本检索解析器和模板由底层 C 函数构成,因此开发新的解析器和模板需要 C 编程能力,将它们安装到数据库中则需要超级用户权限。(PostgreSQL 发行版的 contrib/ 目录中有附加解析器和模板的示例。)词典和配置只是为底层解析器和模板设置参数并将它们连接起来,因此创建新词典或配置不需要特殊权限。本章后面会给出创建自定义词典和配置的示例。 @@ -343,14 +343,14 @@ SELECT phraseto_tsquery('the cats ate the rats'); 表和索引 - 在前一节中的示例演示了使用简单常数字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 + 在前一节中的示例演示了使用简单常量字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 搜索表 - 即使没有索引,也可以执行全文搜索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend: + 即使没有索引,也可以执行全文检索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend SELECT title @@ -374,7 +374,7 @@ WHERE to_tsvector(body) @@ to_tsquery('friend'); - 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 中同时包含 createtable: + 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 合在一起包含 createtable SELECT title @@ -388,7 +388,7 @@ LIMIT 10; - 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本搜索在实际使用中通常都需要建立索引。 + 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本检索在实际使用中通常都需要建立索引。 @@ -396,9 +396,15 @@ LIMIT 10; 创建索引 - 我们可以创建一个GIN索引()来加速文本搜索: + + 我们可以创建一个GIN索引()来加速文本检索: + + CREATE INDEX pgweb_idx ON pgweb USING GIN (to_tsvector('english', body)); -注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本搜索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含tsvector,它们使用不同的文本搜索配置创建,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 + + + 注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本检索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含使用不同文本检索配置创建的tsvector,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 + 由于上面的索引使用了 to_tsvector 的双参数版本,因此只有同样使用相同配置名的双参数版 to_tsvector 查询,才能使用该索引。也就是说,WHERE to_tsvector('english', body) @@ 'a & b' 可以使用该索引,而 WHERE to_tsvector(body) @@ 'a & b' 则不能。这样可以保证索引只会和创建索引项时所用的同一配置配合使用。 @@ -434,7 +440,7 @@ LIMIT 10; 当使用一个单独的列来存储 tsvector 表示时,需要创建一个触发器来使 tsvector 列保持最新,以应对 titlebody 的任何更改。 说明了如何做到这一点。 - 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本搜索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 + 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本检索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 @@ -442,10 +448,10 @@ LIMIT 10; - 控制文本搜索 + 控制文本检索 - 要实现全文搜索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 + 要实现全文检索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 @@ -464,7 +470,7 @@ to_tsvector( config - to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本搜索配置进行处理。下面是一个简单示例: + to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本检索配置进行处理。下面是一个简单示例: SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); @@ -479,7 +485,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每类词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本搜索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english。 + to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每个词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本检索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english @@ -487,7 +493,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为空,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: + 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为 NULL,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: UPDATE tt SET ti = @@ -518,22 +524,35 @@ to_tsquery( config - to_tsquery创建一个tsquery值,其来源为querytext,其中必须是由以下 tsquery 操作符分隔的单个词元:&(AND)、|(OR)、!(NOT)以及 <->(FOLLOWED BY),也可以使用括号分组。换句话说,to_tsquery 的输入必须已经遵循 tsquery 输入的一般规则,如 所述。区别在于,基本的 tsquery 输入会直接使用词元,而 to_tsquery 会使用指定或默认的配置将每个词元正规化为词位,并丢弃根据该配置判定为停用词的词元。例如: + to_tsquery 根据 querytext 创建一个 tsquery 值。输入必须由单个词元组成,这些词元之间使用 tsquery 操作符 &(AND)、|(OR)、!(NOT)和 <->(FOLLOWED BY)分隔,并可使用圆括号分组。换句话说,传给 to_tsquery 的输入,必须已经遵循 中描述的 tsquery 一般输入规则。不同之处在于,基础 tsquery 输入是按字面接受词元,而 to_tsquery 会使用指定或默认配置,把每个词元正规化为词位,并丢弃那些按该配置被判定为停用词的词元。例如: + + SELECT to_tsquery('english', 'The & Fat & Rats'); to_tsquery --------------- 'fat' & 'rat' -与基本的 tsquery 输入一样,可以给每个词位附加权重,以限制它只匹配 tsvector 中具有这些权重的词位。例如: + + + 与基础tsquery输入一样,可以为每个词位附加权重,以限制它只匹配具有这些权重的tsvector词位。例如: + + SELECT to_tsquery('english', 'Fat | Rats:AB'); to_tsquery ------------------ 'fat' | 'rat':AB -此外,可以把 * 附加到词位上来指定前缀匹配: + + + 此外,还可以在词位后附加*来指定前缀匹配: + + SELECT to_tsquery('supern:*A & star:A*B'); to_tsquery -------------------------- 'supern':*A & 'star':*AB -这样的词位将匹配 tsvector 中以给定字符串开头的任何单词。 + + + 这样的词位将匹配tsvector中任何以给定字符串开头的单词。 + to_tsquery也可以接受单引号括起来的短语。当配置中包含可能在这类短语上触发的分类词典时,这一点尤其有用。在下面的例子中,一个分类词典包含规则 supernovae @@ -585,12 +604,19 @@ phraseto_tsquery( config phraseto_tsquery的行为很像plainto_tsquery,不过它会在保留下来的词之间插入<->(FOLLOWED BY)操作符,而不是&(AND)操作符。此外,停用词也不是简单地丢弃,而是通过插入<N>操作符(而不是<->操作符)来体现。在搜索精确词位序列时,这个函数很有用,因为 FOLLOWED BY 操作符不仅检查所有词位是否存在,还检查词位的顺序。 - 示例: + + 示例: + + SELECT phraseto_tsquery('english', 'The Fat Rats'); phraseto_tsquery ------------------ 'fat' <-> 'rat' -plainto_tsquery一样,phraseto_tsquery函数也不会识别其输入中的tsquery操作符、权重标签或前缀匹配标签: + + + 与plainto_tsquery一样,phraseto_tsquery函数也不会识别输入中的tsquery操作符、权重标签或前缀匹配标签: + + SELECT phraseto_tsquery('english', 'The Fat & Rats:C'); phraseto_tsquery ----------------------------- @@ -606,12 +632,12 @@ websearch_to_tsquery( configwebsearch_to_tsquery创建一个tsquery值,其来源为querytext,采用一种替代语法,其中简单的无格式文本就是一个有效查询。不同于plainto_tsqueryphraseto_tsquery,它还识别某些操作符。此外,这个函数不应引发语法错误,因此可以直接使用用户提供的原始输入进行搜索。支持以下语法: - 无引号文本:不在引号中的文本会被转换为由&操作符分隔的词,就像经过plainto_tsquery处理一样。 + 未加引号的文本:不在引号中的文本会被转换为由&操作符分隔的词,就像经过plainto_tsquery处理一样。 - "引号文本":引号中的文本会被转换为由<->操作符分隔的词,就像经过phraseto_tsquery处理一样。 + "加引号的文本":引号中的文本会被转换为由<->操作符分隔的词,就像经过phraseto_tsquery处理一样。 @@ -662,7 +688,7 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); 搜索结果排名 - 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及它们出现于文档中哪个部分。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 + 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及这些词所处文档部分的重要程度。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 目前可用的两种排名函数是: @@ -709,11 +735,21 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 对这两个函数来说,可选的weights参数允许根据词实例的标注情况赋予它们不同权重。权重数组按如下顺序指定各类词的权重: -{D-weight, C-weight, B-weight, A-weight} -如果没有提供weights,则使用如下默认值: + + 对这两个函数来说,可选的 weights 参数允许根据词实例的标注情况赋予它们不同权重。权重数组按如下顺序指定各类词的权重: + + +{D-权重, C-权重, B-权重, A-权重} + + + 如果没有提供 weights,则使用如下默认值: + + {0.1, 0.2, 0.4, 1.0} -通常,权重用于标注文档中特殊部分的词,例如标题或开头的摘要,从而使它们相对于正文中的词具有更高或更低的重要性。 + + + 通常,权重用于标记来自文档特定区域的词,例如标题或开头摘要中的词,从而使它们相较于正文中的词被赋予更高或更低的重要性。 + 由于较长的文档更有机会包含查询词,因此把文档大小纳入考量是合理的。例如,一个一百词的文档里某个搜索词出现五次,通常会比一个一千词的文档里同一搜索词也只出现五次更相关。两种排名函数都接受一个整数 normalization 选项,用于指定文档长度是否影响排名,以及具体如何影响。该整数选项控制多种行为,因此它是一个位掩码:你可以使用 | 指定一种或多种行为(例如 2|4)。 @@ -741,12 +777,12 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 8 用文档中唯一词的数量除排名 + 8 用文档中不同词的数量除排名 - 16 用 1 + 文档中唯一词数量的对数除排名 + 16 用 1 + 文档中不同词数量的对数除排名 @@ -760,7 +796,7 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。正规化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 + 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。归一化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 @@ -832,9 +868,7 @@ ts_headline( config ts_headline 接收文档和查询,并返回文档中一段 - 高亮查询词条的摘录。具体而言,该函数会先用查询选择相关文本片段,然后 - 高亮查询中出现的所有词,即使这些词的位置并不满足查询本身的位置限制。 - 用于解析文档的配置可通过 config 指定; + 高亮查询词的摘录。用于解析文档的配置可通过 config 指定; 若省略 config,则使用 default_text_search_config 配置。 @@ -921,7 +955,7 @@ occurrences to display in the result.', 附加特性 - 本节介绍一些在文本搜索中很有用的附加函数和操作符。 + 本节介绍一些在文本检索中很有用的附加函数和操作符。 @@ -1034,7 +1068,7 @@ occurrences to display in the result.', - 返回用 AND 结合的两个给定查询。 + 返回两个给定查询的 AND 组合。 @@ -1048,7 +1082,7 @@ occurrences to display in the result.', - 返回用 OR 结合的两个给定查询。 + 返回两个给定查询的 OR 组合。 @@ -1101,7 +1135,7 @@ SELECT to_tsquery('fat') <-> to_tsquery('cat | rat'); - 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: + 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在其后距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: SELECT tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10); @@ -1187,8 +1221,10 @@ SELECT querytree(to_tsquery('!defined')); - 这种形式的ts_rewrite 只应用一条重写规则:target 会被替换成 substitute,替换范围是整个 query。例如: + + 这种形式的 ts_rewrite 只应用一条重写规则:无论 targetquery 中的何处出现,都用 substitute 替换它。例如: + + SELECT ts_rewrite('a & b'::tsquery, 'a'::tsquery, 'c'::tsquery); ts_rewrite ------------ @@ -1205,7 +1241,10 @@ SELECT ts_rewrite('a & b'::tsquery, 'a'::tsquery, 'c'::tsquery); - 这种形式的ts_rewrite接受一个起始query和一个 SQLselect命令,该命令以文本字符串给出。该select必须产生两列tsquery类型的值。对于select结果中的每一行,第一列值(目标)的各次出现都会被第二列值(替换)取代,替换范围为当前query值。例如: + + 这种形式的 ts_rewrite 接受一个起始 query 和一个以文本字符串给出的 SQL select 命令。该 select 必须产生两列 tsquery 类型的值。对于 select 结果中的每一行,第一列值(目标)在当前 query 值中的所有出现都会被第二列值(替换)取代。例如: + + CREATE TABLE aliases (t tsquery PRIMARY KEY, s tsquery); INSERT INTO aliases VALUES('a', 'c'); @@ -1284,7 +1323,10 @@ tsvector_update_trigger(tsvector_column_nametsvector_column_name, config_column_name, text_column_name , ... ) - 这些触发器函数会自动计算一个tsvector列,其值来自一个或多个文本列,并受以下命令中所指定参数的控制:CREATE TRIGGER。下面是一个用法示例: + + 这些触发器函数会在 CREATE TRIGGER 命令中给定参数的控制下,从一个或多个文本列自动计算出一个 tsvector 列。下面是它们的一个使用示例: + + CREATE TABLE messages ( title text, body text, @@ -1306,13 +1348,19 @@ SELECT title, body FROM messages WHERE tsv @@ to_tsquery('title & body'); title | body ------------+----------------------- title here | the body text is here -创建这个触发器后,titlebody中的任何更改都会自动反映到tsv中,应用无需为此操心。 + + + 创建该触发器之后,对titlebody的任何修改都会自动反映到tsv中,而应用程序无需关心这一点。 + - 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本搜索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 + 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本检索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 - 这些内置触发器有一个限制,即它们会一视同仁地处理所有输入列。要对不同列采用不同处理方式 — 例如,给标题赋予与正文不同的权重 — 就需要编写自定义触发器。下面是一个使用PL/pgSQL作为触发器语言的示例: + + 这些内置触发器的一个限制是,它们会以相同方式处理所有输入列。若要对列做不同处理 — 例如让标题和正文具有不同权重 — 就需要编写自定义触发器。下面是一个使用 PL/pgSQL 作为触发器语言的示例: + + CREATE FUNCTION messages_trigger() RETURNS trigger AS $$ begin new.tsv := @@ -1373,7 +1421,7 @@ ts_stat(sqlquery text, - 如果提供了 weights,则只统计具有这些权重之一的出现。 + 如果提供了 weights,则只统计具有这些权重之一的词的出现次数。 @@ -1402,7 +1450,7 @@ LIMIT 10; 解析器 - 文本搜索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 + 文本检索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 @@ -1422,12 +1470,12 @@ LIMIT 10; asciiword - 单词,所有 ASCII 字母 + 单词,全部由 ASCII 字母组成 elephant word - 单词,所有字母 + 单词,全部由字母组成 mañana @@ -1437,12 +1485,12 @@ LIMIT 10; asciihword - 带连字符的单词,所有 ASCII + 带连字符的单词,全部为 ASCII 字符 up-to-date hword - 带连字符的单词,所有字母 + 带连字符的单词,由字母组成 lógico-matemática @@ -1452,12 +1500,12 @@ LIMIT 10; hword_asciipart - 带连字符的单词部分,所有 ASCII + 带连字符的单词部分,全部为 ASCII 字符 postgresql-beta1 上下文中的 postgresql hword_part - 带连字符的单词部分,所有字母 + 带连字符的单词部分,全部由字母组成 lógico-matemática 上下文中的 lógicomatemática @@ -1532,8 +1580,8 @@ LIMIT 10; blank - 空格符号 - (其他不识别的任意空白或标点符号) + 空白符号 + (未被识别为其他类型的空白或标点符号) @@ -1541,7 +1589,7 @@ LIMIT 10; - 解析器的一个字母的概念由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时可以用来区别它们。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 + 解析器对字母的界定由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时区分它们会很有用。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 email 不支持 RFC 5322 定义的所有有效电子邮件字符。具体来说,电子邮件用户名中支持的非字母数字字符只有句点、短横线和下划线。 @@ -1581,7 +1629,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h 词典 - 词典用于消除不应参与搜索的词(stop words),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 + 词典用于消除不应参与搜索的词(停用词),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 一些正规化的示例: @@ -1593,7 +1641,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - URL地址可以被正规化,以便让等价的 URL 匹配: + URL 地址可以规范化,以便让等价的 URL 匹配: @@ -1638,32 +1686,32 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤字典) + 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤词典 - 如果字典知道该词元但它是一个停用词,则返回一个空数组 + 如果词典知道该词元但它是一个停用词,则返回一个空数组 - 如果字典不识别该输入词元,则返回NULL + 如果词典不识别该输入词元,则返回NULL - PostgreSQL为许多语言提供了预定义的字典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发布的contrib/区域。 + PostgreSQL为许多语言提供了预定义的词典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发行版的contrib/目录。 - 文本搜索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 + 文本检索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 - 配置词典列表的一般规则是,把最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语分类词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: + 配置词典列表的一般规则是,把适用范围最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语同义词词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: ALTER TEXT SEARCH CONFIGURATION astro_en @@ -1672,14 +1720,14 @@ ALTER TEXT SEARCH CONFIGURATION astro_en - 过滤词典可以放在列表中的任何位置,只是不能放在最后,因为放在最后就没有意义了。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 + 过滤词典可以放在列表中的任何位置,但放在末尾没有用处。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 停用词 - 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文搜索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: + 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文检索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: SELECT to_tsvector('english', 'in the list of stop words'); @@ -1811,7 +1859,7 @@ SELECT * FROM ts_debug('english', 'Paris'); - synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基本名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 + synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 @@ -1873,28 +1921,28 @@ mydb=# SELECT 'indexes are very useful'::tsvector @@ to_tsquery('tst', 'indices' - 基本上一个分类词典会用一个首选词替换所有非首选词,并且也可选择地保留原始术语用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典要求一个下列格式的配置文件: + 分类词典基本上会用一个首选词替换所有非首选词,并且也可以选择保留原始词用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典需要一个采用以下格式的配置文件: -# this is a comment -sample word(s) : indexed word(s) -more sample word(s) : more indexed word(s) +# 这是一条注释 +示例词(一个或多个) : 索引词(一个或多个) +更多示例词(一个或多个) : 更多索引词(一个或多个) ... - 其中冒号(:)符号扮演了一个短语及其替换之间的定界符。 + 其中冒号(:)符号用作短语及其替换词之间的分隔符。 - 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过对子词典的应用,但所有样例词都必须能被子词典识别。 + 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过将子词典应用于该词,但所有样例词都必须能被子词典识别。 - 如果有多个短语匹配输入,则分类词典选择最长的那一个,并且使用最后的定义打破连结。 + 如果有多个短语匹配输入,分类词典会选择最长的匹配;长度相同时使用最后的定义。 - 由子词典识别的特定停用词不能够被指定;改用?标记任何可以出现停用词的地方。例如,假定根据子词典athe是停用词: + 由子词典识别的特定停用词不能够被指定;改用?标记可出现任意停用词的位置。例如,假定根据子词典athe是停用词: ? one ? two : swsw @@ -1936,7 +1984,7 @@ CREATE TEXT SEARCH DICTIONARY thesaurus_simple ( - mythesaurus是分类词典配置文件的基础名称(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 + mythesaurus是分类词典配置文件的基名(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 @@ -1961,7 +2009,7 @@ ALTER TEXT SEARCH CONFIGURATION russian 分类词典示例 - 考虑简单的天文词库 thesaurus_astro,其中包含一些天文单词组合: + 考虑一个简单的天文分类词典 thesaurus_astro,其中包含一些天文单词组合: supernovae stars : sn @@ -2029,7 +2077,7 @@ SELECT plainto_tsquery('supernova star'); <application>Ispell</application> 词典 - Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以把搜索词 bank 的词尾变化和词形变化对应起来,例如 bankingbankedbanksbanks'bank's。 + Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以匹配搜索词 bank 的所有变格和变位形式,例如 bankingbankedbanksbanks'bank's @@ -2041,12 +2089,12 @@ SELECT plainto_tsquery('supernova star'); - 要创建一个Ispell词典,执行这三步: + 要创建一个Ispell词典,请执行以下步骤: - 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。有必要抽取.aff.dic文件,把扩展改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): + 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。需要提取.aff.dic文件,将扩展名改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): iconv -f ISO_8859-1 -t UTF-8 -o nn_no.affix nn_NO.aff iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic @@ -2055,7 +2103,7 @@ iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic - 拷贝文件到$SHAREDIR/tsearch_data目录 + 复制文件到$SHAREDIR/tsearch_data目录 @@ -2073,11 +2121,11 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( - 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基础名称。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 + 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基名。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 - Ispell 词典通常识别一个有限集合的词,这样它们后面应该跟着另一个更广义的词典;例如,一个 Snowball 词典,它可以识别所有东西。 + Ispell 词典通常只能识别有限的词,因此其后应跟着另一个覆盖范围更广的词典;例如,一个 Snowball 词典,它可以识别所有输入。 @@ -2085,13 +2133,13 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( prefixes flag *A: - . > RE # As in enter > reenter + . > RE # 例如 enter > reenter suffixes flag T: - E > ST # As in late > latest - [^AEIOU]Y > -Y,IEST # As in dirty > dirtiest - [AEIOU]Y > EST # As in gray > grayest - [^EY] > EST # As in small > smallest + E > ST # 例如 late > latest + [^AEIOU]Y > -Y,IEST # 例如 dirty > dirtiest + [AEIOU]Y > EST # 例如 gray > grayest + [^EY] > EST # 例如 small > smallest @@ -2107,14 +2155,14 @@ lark/MRS .dict文件的格式是: -basic_form/affix_class_name +基本词形/词缀类名 .affix文件中,每一个词缀标志以下面的格式描述: -condition > [-stripping_letters,] adding_affix +条件 > [-删除的字母,] 添加的词缀 @@ -2123,7 +2171,7 @@ condition > [-stripping_letters,] adding_affix - Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,它标记可以参与到复合格式中的词典词: + Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,用于标记词典中可以参与构成复合词的词: compoundwords controlled z @@ -2153,7 +2201,7 @@ SFX T 0 est [^ey] - 一个词缀类的第一行是头部。头部后面列出了词缀规则的域: + 一个词缀类的第一行是首部。首部后面列出了词缀规则的字段: @@ -2205,7 +2253,7 @@ largehearted <application>Snowball</application> 词典 - Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每一个算法懂得按照其语言中的拼写,如何缩减词的常见变体形式为一个基础或词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择地指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。例如,有一个内置的定义等效于 + Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每种算法都知道如何把其语言中词的常见变体约简为基本拼写形式,也就是词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。例如,有一个内置的定义等效于 CREATE TEXT SEARCH DICTIONARY english_stem ( @@ -2219,7 +2267,7 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( - 一个Snowball词典识别所有的东西,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 + 一个Snowball词典识别所有输入,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 @@ -2230,11 +2278,11 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( 配置示例 - 一个文本搜索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本搜索配置来执行其处理。配置参数指定了默认配置的名称,如果忽略了显式的配置参数,文本搜索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 + 一个文本检索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本检索配置来执行其处理。配置参数指定了默认配置的名称,如果省略了显式的配置参数,文本检索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 - 有一些预定义的文本搜索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本搜索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本搜索对象()的信息。 + 有一些预定义的文本检索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本检索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本检索对象()的信息。 @@ -2326,17 +2374,17 @@ SHOW default_text_search_config; - 测试和调试文本搜索 + 测试和调试文本检索 - 一个自定义文本搜索配置的行为很容易变得混乱。本节中描述的函数对于测试文本搜索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 + 一个自定义文本检索配置的行为很容易让人困惑。本节中描述的函数对于测试文本检索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 配置测试 - 函数ts_debug允许简单地测试一个文本搜索配置。 + 函数ts_debug可方便地测试一个文本检索配置。 @@ -2355,7 +2403,7 @@ ts_debug( config re - ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果该参数被忽略则使用default_text_search_config指定的配置。 + ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果省略该参数则使用default_text_search_config指定的配置。 @@ -2430,7 +2478,7 @@ SELECT * FROM ts_debug('english', 'a fat cat sat on a mat - it ate a fat rats') - 为了一个更广泛的示范,我们先为英语语言创建一个public.english配置和 Ispell 词典: + 为了做更完整的演示,我们先为英语创建一个public.english配置和 Ispell 词典: @@ -2459,7 +2507,7 @@ SELECT * FROM ts_debug('public.english', 'The Brightest supernovaes'); - 在这个示例中,词Brightest被解析器识别为一个ASCII word(别名asciiword)。对于这种词元类型,词典列表是english_ispellenglish_stem。该词被english_ispell识别,并被这个词典归约为名词bright。词supernovaesenglish_ispell词典来说是未知的,因此它会被传递给下一个词典;幸运的是,它随后被识别了。(实际上,english_stem是一个 Snowball 词典,它能够识别所有输入;这也是为什么它被放在词典列表末尾。) + 在这个示例中,词Brightest被解析器识别为一个ASCII 词(别名asciiword)。对于这种词元类型,词典列表是english_ispellenglish_stem。该词被english_ispell识别,并被这个词典归约为词位bright。词supernovaesenglish_ispell词典来说是未知的,因此它会被传递给下一个词典;幸运的是,它随后被识别了。(实际上,english_stem是一个 Snowball 词典,它能够识别所有输入;这也是为什么它被放在词典列表末尾。) @@ -2488,7 +2536,7 @@ FROM ts_debug('public.english', 'The Brightest supernovaes'); 解析器测试 - 下列函数允许直接测试一个文本搜索解析器。 + 下列函数允许直接测试一个文本检索解析器。 @@ -2530,7 +2578,7 @@ ts_token_type(parser_oid oid< - ts_token_type返回一个表,描述指定解析器能够识别的每一种词元。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: + ts_token_type返回一个表,描述指定解析器能够识别的每一种词元类型。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: SELECT * FROM ts_token_type('default'); @@ -2568,7 +2616,7 @@ SELECT * FROM ts_token_type('default'); 词典测试 - ts_lexize函数帮助词典测试。 + ts_lexize函数便于测试词典。 @@ -2626,17 +2674,17 @@ SELECT plainto_tsquery('supernovae stars'); - 文本搜索的首选索引类型 + 文本检索的首选索引类型 - 文本搜索 + 文本检索 索引 - 有两种索引可以用来加速全文搜索:GIN和 + 有两种索引可以用来加速全文检索:GINGiST。 - 请注意,索引对于全文搜索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 + 请注意,索引对于全文检索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 要创建这样的索引,可以采用下面的任一种方式: @@ -2647,7 +2695,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GIN - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIN (column); @@ -2667,7 +2715,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GiST - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIST (column); @@ -2685,7 +2733,7 @@ SELECT plainto_tsquery('supernovae stars'); - GIN 索引是文本搜索的首选索引类型。作为倒排索引,每个词(词位)在 + GIN 索引是文本检索的首选索引类型。作为倒排索引,每个词(词位)在 其中都有一个索引项,其中有压缩过的匹配位置的列表。多词搜索可以找到 第一个匹配,然后使用该索引移除缺少额外词的行。GIN 索引只存储 tsvector值的词(词位),并且不存储它们的权重标签。因此, @@ -2693,15 +2741,15 @@ SELECT plainto_tsquery('supernovae stars'); - 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。该签名通过哈希每一个词到一个 n 位串中的一个单一位来产生,通过将所有这些位 OR 在一起产生一个 n 位的文档签名。当两个词哈希到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。 + 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。该签名通过将每个词 hash 到一个 n 位串中的一位,再将所有这些位进行 OR 运算来生成,结果是一个 n 位的文档签名。当两个词 hash 到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。 - 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的可用性。假匹配的可能性取决于几个因素,特别是唯一词的数量,因此推荐使用词典来缩减这个数量。 + 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的实用性。假匹配的可能性取决于几个因素,特别是不同词的数量,因此推荐使用词典来缩减这个数量。 - 注意GIN索引的构件时间常常可以通过增加来改进,而GiST索引的构建时间则与该参数无关。 + 注意GIN索引的构建时间常常可以通过增加来改进,而GiST索引的构建时间则对该参数不敏感。 @@ -2715,7 +2763,7 @@ SELECT plainto_tsquery('supernovae stars'); <application>psql</application> 支持 - 关于文本搜索配置对象的信息可以在psql中使用一组命令获得: + 关于文本检索配置对象的信息可以在psql中使用一组命令获得: \dF{d,p,t}+ PATTERN @@ -2723,7 +2771,7 @@ SELECT plainto_tsquery('supernovae stars'); - 可选参数 PATTERN 可以是文本搜索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: + 可选参数 PATTERN 可以是文本检索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: => \dF *fulltext* @@ -2749,7 +2797,9 @@ SELECT plainto_tsquery('supernovae stars'); \dF+ PATTERN - 列出文本搜索配置(添加 +可获得更详细的信息)。 + + 列出文本检索配置(加上 + 可显示更多细节)。 + => \dF russian List of text search configurations Schema | Name | Description @@ -2788,7 +2838,9 @@ Parser: "pg_catalog.default" \dFd+ PATTERN - 列出文本搜索词典(加上+可获得更详细的信息)。 + + 列出文本检索词典(加上 + 可显示更多细节)。 + => \dFd List of text search dictionaries Schema | Name | Description @@ -2817,7 +2869,9 @@ Parser: "pg_catalog.default" \dFp+ PATTERN - 列出文本搜索解析器(添加 +可获得更详细的信息)。 + + 列出文本检索解析器(加上 + 可显示更多细节)。 + => \dFp List of text search parsers Schema | Name | Description @@ -2868,7 +2922,9 @@ Parser: "pg_catalog.default" \dFt+ PATTERN - 列出文本搜索模板(添加 +可获得更详细的信息)。 + + 列出文本检索模板(加上 + 可显示更多细节)。 + => \dFt List of text search templates Schema | Name | Description @@ -2889,7 +2945,7 @@ Parser: "pg_catalog.default" 限制 - 目前,PostgreSQL的文本搜索功能存在以下限制: + 目前,PostgreSQL的文本检索功能存在以下限制: 每个词位的长度必须小于 2K 字节 @@ -2916,12 +2972,12 @@ Parser: "pg_catalog.default" - 为了对比,PostgreSQL 8.1 的文档包含 10,441 个唯一词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 + 为了对比,PostgreSQL 8.1 的文档包含 10,441 个不同词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 - 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个唯一词。 + 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个不同词。 diff --git a/zh/11/unaccent.sgml b/zh/11/unaccent.sgml index 0bc0bfe7..ea1617ac 100644 --- a/zh/11/unaccent.sgml +++ b/zh/11/unaccent.sgml @@ -8,11 +8,11 @@ - unaccent是一个文本搜索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤字典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文搜索能够以不区分重音的方式处理文本。 + unaccent是一个文本检索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤词典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文检索能够以不区分重音的方式处理文本。 - unaccent当前的实现还不能作为thesaurus词典的正规化字典使用。 + unaccent当前的实现还不能作为thesaurus词典的正规化词典使用。 @@ -61,7 +61,7 @@ - 与其他PostgreSQL文本搜索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含无法转换的字符的行都会被静默忽略,因此规则文件可以包含不适用于当前编码的规则。 + 与其他PostgreSQL文本检索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含无法转换的字符的行都会被静默忽略,因此规则文件可以包含不适用于当前编码的规则。 @@ -74,7 +74,7 @@ 用法 - 安装unaccent扩展会创建一个文本搜索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 + 安装unaccent扩展会创建一个文本检索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 mydb=# ALTER TEXT SEARCH DICTIONARY unaccent (RULES='my_rules'); @@ -95,7 +95,7 @@ mydb=# select ts_lexize('unaccent','Hôtel'); - 下面的示例展示了如何将unaccent词典插入到文本搜索配置中: + 下面的示例展示了如何将unaccent词典插入到文本检索配置中: mydb=# CREATE TEXT SEARCH CONFIGURATION fr ( COPY = french ); mydb=# ALTER TEXT SEARCH CONFIGURATION fr @@ -126,7 +126,7 @@ mydb=# select ts_headline('fr','Hôtel de la Mer',to_tsquery('fr','Hotels') 函数 - unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本搜索环境之外使用。 + unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本检索环境之外使用。 @@ -138,7 +138,7 @@ unaccent(dictionary - 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本搜索词典。 + 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本检索词典。 diff --git a/zh/12/array.sgml b/zh/12/array.sgml index 49e8b7b6..5491ebf5 100644 --- a/zh/12/array.sgml +++ b/zh/12/array.sgml @@ -4,7 +4,7 @@ 数组 - array + 数组 @@ -15,8 +15,8 @@ 数组类型的声明 - array - declaration + 数组 + 声明 @@ -64,8 +64,8 @@ CREATE TABLE tictactoe ( 数组值输入 - array - constant + 数组 + 常量 @@ -86,7 +86,7 @@ CREATE TABLE tictactoe ( (这类数组常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。必要时可能需要显式指定类型。) + linkend="sql-syntax-constants-generic"/>中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。可能需要显式指定类型。) @@ -118,7 +118,10 @@ SELECT * FROM sal_emp; - 多维数组在每个维度上的长度必须匹配。不匹配会导致错误,例如: + + 多维数组的各个子数组在每个维度上的长度必须匹配。不匹配会导致错误,例如: + + INSERT INTO sal_emp VALUES ('Bill', '{10000, 10000, 10000, 10000}', @@ -148,8 +151,8 @@ INSERT INTO sal_emp 访问数组 - array - accessing + 数组 + 访问 @@ -182,9 +185,9 @@ SELECT pay_by_quarter[3] FROM sal_emp; - 我们还可以访问数组或子数组的任意矩形切片。数组切片通过在一个或多个数组维度上写成 + 我们还可以访问数组的任意矩形切片,即子数组。数组切片通过在一个或多个数组维度上写成 lower-bound:upper-bound - 的形式来表示。例如,下面这个查询取回 Bill 在一周前两天日程安排中的第一个项目: + 的形式来表示。例如,下面这个查询取回 Bill 在一周中前两天里每天的首项日程: SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill'; @@ -231,11 +234,11 @@ SELECT schedule[:][1:1] FROM sal_emp WHERE name = 'Bill'; - 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回空值。此外,如果下标超出数组边界,也会返回空值(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是空值而不是错误。 + 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回 NULL。此外,如果下标超出数组边界,也会返回 NULL(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是 NULL 而不是错误。 - 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回空值。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是空值。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回空值。 + 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回 NULL。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是 NULL。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回 NULL。 @@ -289,8 +292,8 @@ SELECT cardinality(schedule) FROM sal_emp WHERE name = 'Carol'; 修改数组 - array - modifying + 数组 + 修改 @@ -327,7 +330,7 @@ UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}' - 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用空值填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含空值。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 + 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用 NULL 填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含 NULL。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 @@ -439,21 +442,21 @@ SELECT array_cat(ARRAY[5,6], ARRAY[[1,2],[3,4]]); 在简单情况下,优先使用上面讨论的连接操作符,而不是直接调用这些函数。不过,由于连接操作符被重载以同时服务于这三种情形,所以在某些场景下使用这些函数之一有助于避免歧义。例如,考虑: -SELECT ARRAY[1, 2] || '{3, 4}'; -- the untyped literal is taken as an array +SELECT ARRAY[1, 2] || '{3, 4}'; -- 未指定类型的字面量被当作数组 ?column? ----------- {1,2,3,4} -SELECT ARRAY[1, 2] || '7'; -- so is this one +SELECT ARRAY[1, 2] || '7'; -- 这个字面量也一样 ERROR: malformed array literal: "7" -SELECT ARRAY[1, 2] || NULL; -- so is an undecorated NULL +SELECT ARRAY[1, 2] || NULL; -- 未加类型修饰的 NULL 也一样 ?column? ---------- {1,2} (1 row) -SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant +SELECT array_append(ARRAY[1, 2], NULL); -- 这可能才是原本想表达的意思 array_append -------------- {1,2,NULL} @@ -467,8 +470,8 @@ SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant 在数组中搜索 - array - searching + 数组 + 搜索 @@ -509,9 +512,14 @@ SELECT * FROM 关于该函数的说明见 - 还可以使用&&操作符搜索数组,它检查左操作数是否与右操作数重叠。例如: + + 也可以使用 && 操作符来搜索数组,它会检查左操作数是否与右操作数有重叠。例如: + + SELECT * FROM sal_emp WHERE pay_by_quarter && ARRAY[10000]; -关于此操作符和其他数组操作符的更多说明,参见。可以通过适当的索引来加速这种搜索,参见。 + + + 关于该操作符和其他数组操作符的更多说明见。如所述,也可以通过适当的索引加速。 还可以使用array_positionarray_positions函数在数组中搜索特定值。前者返回某个值在数组中首次出现位置的下标;后者返回一个数组,其中包含该值在数组中所有出现位置的下标。例如: @@ -538,7 +546,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); 数组输入和输出语法 - array + 数组 I/O @@ -551,7 +559,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); - 默认情况下,数组各维度的下界索引值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: + 默认情况下,数组各维度的下界下标值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2 FROM (SELECT '[1:1][-2:-1][3:5]={{{1,2,3},{4,5,6}}}'::int[] AS f1) AS ss; diff --git a/zh/12/catalogs.sgml b/zh/12/catalogs.sgml index 1260e389..ec6b426c 100644 --- a/zh/12/catalogs.sgml +++ b/zh/12/catalogs.sgml @@ -315,27 +315,27 @@ pg_ts_config - 文本搜索配置 + 文本检索配置 pg_ts_config_map - 文本搜索配置的词元映射 + 文本检索配置的词元映射 pg_ts_dict - 文本搜索字典 + 文本检索词典 pg_ts_parser - 文本搜索分析器 + 文本检索解析器 pg_ts_template - 文本搜索模板 + 文本检索模板 @@ -7094,12 +7094,12 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config目录包含表示文本搜索配置的条目。一个配置指定某个特定的文本搜索分析器,以及针对该分析器每种输出词元类型所定义的字典列表。分析器由pg_ts_config项表示,而词元到字典的映射则由pg_ts_config系统目录包含表示文本检索配置的条目。一个配置指定某个特定的文本检索解析器,以及针对该解析器每种输出词元类型所定义的词典列表。解析器记录在pg_ts_config条目中,而词元到词典的映射则由pg_ts_config_map中的辅助项定义。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。 @@ -7132,7 +7132,7 @@ SCRAM-SHA-256$<iteration count>:&l name - 文本搜索配置名 + 文本检索配置名 @@ -7159,7 +7159,7 @@ SCRAM-SHA-256$<iteration count>:&l oid pg_ts_parser.oid - 该配置的文本搜索分析器的OID + 该配置的文本检索解析器的 OID @@ -7176,11 +7176,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config_map目录包含的项展示了对于每一个文本搜索配置的每一种输出词元类型,有哪些文本搜索字典可供查询以及以何种顺序。 + pg_ts_config_map 系统目录中的条目说明了,对于每个文本检索配置所用解析器的每种输出词元类型,应当查询哪些文本检索词典以及查询的顺序。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7213,7 +7213,7 @@ SCRAM-SHA-256$<iteration count>:&l integer - 一种由配置的分析器送出的词元类型 + 一种由配置的解析器送出的词元类型 @@ -7231,7 +7231,7 @@ SCRAM-SHA-256$<iteration count>:&l oid pg_ts_dict.oid - 要查询的文本搜索字典的OID + 要查询的文本检索词典的 OID @@ -7248,11 +7248,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_dict目录包含定义文本搜索字典的项。一个字典依赖于一个文本搜索模板,它指定了所有需要的函数实现,字典本身则为模板支持的用户可设置参数提供值。这种分工允许无权限的用户创建字典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 + pg_ts_dict系统目录包含定义文本检索词典的项。一个词典依赖于一个文本检索模板,它指定了所有需要的实现函数,词典本身则为模板支持的用户可设置参数提供值。这种分工允许普通用户创建词典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7285,7 +7285,7 @@ SCRAM-SHA-256$<iteration count>:&l name - 文本搜索字典名 + 文本检索词典名 @@ -7294,7 +7294,7 @@ SCRAM-SHA-256$<iteration count>:&l oid pg_namespace.oid - 包含该字典的名字空间OID + 包含该词典的名字空间的 OID @@ -7303,7 +7303,7 @@ SCRAM-SHA-256$<iteration count>:&l oid pg_authid.oid - 字典的拥有者 + 词典的拥有者 @@ -7312,7 +7312,7 @@ SCRAM-SHA-256$<iteration count>:&l oid pg_ts_template.oid - 该字典的文本搜索模板的OID + 该词典的文本检索模板的 OID @@ -7338,11 +7338,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_parser目录包含定义文本搜索分析器的项。一个分析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个分析器必须用C语言级别的函数实现,创建新分析器的工作只限于数据库的超级用户。 + pg_ts_parser系统目录包含定义文本检索解析器的项。一个解析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个解析器必须用 C 语言级别的函数实现,创建新解析器的工作只限于数据库的超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7375,7 +7375,7 @@ SCRAM-SHA-256$<iteration count>:&l name - 文本搜索分析器的名字 + 文本检索解析器的名字 @@ -7384,7 +7384,7 @@ SCRAM-SHA-256$<iteration count>:&l oid pg_namespace.oid - 包含此分析器的名字空间的OID + 包含此解析器的名字空间的 OID @@ -7393,7 +7393,7 @@ SCRAM-SHA-256$<iteration count>:&l regproc pg_proc.oid - 分析器启动函数的OID + 解析器启动函数的 OID @@ -7402,7 +7402,7 @@ SCRAM-SHA-256$<iteration count>:&l regproc pg_proc.oid - 分析器的下一词元函数的OID + 解析器的下一词元函数的 OID @@ -7411,7 +7411,7 @@ SCRAM-SHA-256$<iteration count>:&l regproc pg_proc.oid - 分析器的关闭函数的OID + 解析器的关闭函数的 OID @@ -7420,7 +7420,7 @@ SCRAM-SHA-256$<iteration count>:&l regproc pg_proc.oid - 分析器标题函数的 OID + 解析器的 headline 函数的 OID @@ -7429,7 +7429,7 @@ SCRAM-SHA-256$<iteration count>:&l regproc pg_proc.oid - 分析器的词汇类型函数的OID + 解析器的 lextype 函数的 OID @@ -7446,11 +7446,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_template目录包含定义文本搜索模板的项。一个模板是一类文本搜索字典的实现骨架。由于一个模板必须用C语言级别的函数实现,新模板的创建只限于数据库超级用户。 + pg_ts_template系统目录包含定义文本检索模板的项。一个模板是一类文本检索词典的实现骨架。由于一个模板必须用 C 语言级别的函数实现,新模板的创建只限于数据库超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7483,7 +7483,7 @@ SCRAM-SHA-256$<iteration count>:&l name - 文本搜索模板的名字 + 文本检索模板的名字 diff --git a/zh/12/config.sgml b/zh/12/config.sgml index ec854239..fa29e4f7 100644 --- a/zh/12/config.sgml +++ b/zh/12/config.sgml @@ -2383,7 +2383,7 @@ include_dir 'conf.d' 配置 恢复 - 一个备库 + 备库 @@ -3407,7 +3407,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( )。 + 设置规划器对一系列顺序磁盘页面读取中单次读取的代价估计。默认值是 1.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -3562,7 +3561,7 @@ ANY num_sync ( )。 + 设置规划器对一次非顺序磁盘页面读取的代价估计。默认值是 4.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -3584,8 +3583,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( - 遗传查询优化 + 遗传查询优化器 - GEQO是一个使用探索式搜索来执行查询规划的算法。它可以降低负载查询的规划时间。 同时,GEQO的检索是随机的,因此它的规划可能会不可确定。 更多信息参阅Chapter 50。 - 遗传查询规划器(GEQO)是一种使用启发式搜索来进行查询规划的算法。它可以降低对于复杂查询(连接很多表的查询)的规划时间,但是代价是它产生的计划有时候要差于使用穷举搜索算法找到的计划。详见。 + 遗传查询优化器(GEQO)是一种使用启发式搜索进行查询规划的算法。它可以缩短复杂查询(连接很多关系的查询)的规划时间,代价是生成的计划有时不如常规穷举搜索算法找到的计划。更多信息见 @@ -3795,7 +3792,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( .) + 目前,约束排除仅在通常用于通过继承树实现表分区的情况下默认启用。为所有表启用它会增加额外的规划开销,这在简单查询上相当明显,而且通常不会为简单查询带来好处。如果没有通过传统继承方式进行分区的表,你可能希望完全关闭它。(注意,分区表的等效功能由另一个参数控制。) @@ -4042,8 +4036,7 @@ SELECT * FROM parent WHERE key = 2400; parallel_leader_participation (boolean) - parallel_leader_participation configuration - parameter + parallel_leader_participation 配置参数 @@ -4095,13 +4088,7 @@ SELECT * FROM parent WHERE key = 2400; - 准备语句(显式准备或隐式生成的,例如 PL/pgSQL)可以使用自定义或通用计划执行。 - 使用其特定的参数值集为每个执行重新生成自定义计划,而通用计划不依赖于参数值,并且可以在执行中重复使用。 - 因此,使用通用计划可以节省计划时间,但如果理想计划严重依赖参数值,则通用计划可能效率低下。 - 这些选项之间的选择通常是自动进行的,但可以通过plan_cache_mode覆盖它。 - 允许的值为 auto (默认的),force_custom_planforce_generic_plan。 - 这个设置是在执行缓存计划时考虑,而不是在准备计划时考虑。 - 更多信息请参阅 . + 预备语句(无论是显式预备的,还是由 PL/pgSQL 等隐式生成的)可以使用自定义计划或通用计划执行。自定义计划会根据每次执行的具体参数值重新生成,而通用计划不依赖参数值,可以在多次执行之间复用。因此,使用通用计划能够节省规划时间,但如果理想计划高度依赖参数值,通用计划可能效率较低。系统通常会自动选择这两种计划,但可以通过plan_cache_mode覆盖这一选择。允许的值为auto(默认值)、force_custom_planforce_generic_plan。系统在执行缓存计划时考虑此设置,而不是在预备计划时。更多信息见 @@ -4118,7 +4105,7 @@ SELECT * FROM parent WHERE key = 2400; - 在哪里做日志 + 日志记录到哪里 日志写到哪里 @@ -4126,7 +4113,7 @@ SELECT * FROM parent WHERE key = 2400; current_logfiles - 和日志_目的地配置参数 + 和 log_destination 配置参数 @@ -4153,7 +4140,7 @@ csvlog log/postgresql.csv - 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设备LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: + 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设施LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: local0.* /var/log/postgresql @@ -4161,7 +4148,7 @@ local0.* /var/log/postgresql - 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源极其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见。 + 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源及其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见 @@ -4177,20 +4164,20 @@ local0.* /var/log/postgresql - 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 + 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息可能不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 - 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供方法来轮转日志文件。还有,在某些不使用日志收集器的平台上可能会导致丢失或者混淆日志输出,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 + 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供便捷的方法来轮转日志文件。还有,在某些平台上,不使用日志收集器可能会导致日志输出丢失或混杂,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 - 日志收集器被设计成从来不会丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 + 日志收集器被设计成从来不会丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它可能会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 @@ -4222,7 +4209,7 @@ local0.* /var/log/postgresql logging_collector被启用时,这个参数设置被创建的日志文件的文件名。 - 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何时区独立的%转义,计算将在由指定的时区中完成)。 + 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何依赖时区的%转义,计算将在由指定的时区中完成)。 被支持的%转义和开放组织的strftime说明中列举的类似。 注意系统的strftime不会被直接使用,因此平台相关(非标准)的扩展无法工作。 默认是postgresql-%Y-%m-%d_%H%M%S.log。 @@ -4249,7 +4236,7 @@ local0.* /var/log/postgresql - 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的十进制格式,该数字必须以一个0(零)开始)。 + 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的八进制格式,该数字必须以一个0(零)开始)。 @@ -4315,7 +4302,7 @@ local0.* /var/log/postgresql - 示例:要保留 24 小时的日志,每个小时一个日志文件,但是在日志文件尺寸超过 1GB 时轮转。可以这样做:将log_filename设置为server_log.%H%M、 + 示例:要保留 24 小时的日志,每个小时一个日志文件,如果日志文件尺寸超过 1GB,也会提前轮转。可以这样做:将log_filename设置为server_log.%H%M、 将log_truncate_on_rotation设置为on、 将log_rotation_age设置为60并且 将log_rotation_size设置为1000000。 @@ -4334,7 +4321,7 @@ local0.* /var/log/postgresql - 当启用了向syslog记录时,这个参数决定要使用的syslog设备。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4、 + 当启用了向syslog记录时,这个参数决定要使用的syslog设施。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4LOCAL5LOCAL6LOCAL7中选择,默认值是LOCAL0。还请参阅系统的syslog守护进程的文档。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -4389,7 +4376,7 @@ local0.* /var/log/postgresql - 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,有必要让消息保持逻辑上的整体性(也更加有用)。 + 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,让消息保持逻辑上的完整性可能是必要的,也可能更有用。 @@ -4451,9 +4438,7 @@ local0.* /var/log/postgresql - 控制在服务器日志中记录哪些导致错误条件的SQL语句。当前的SQL语句将包含在任何指定 - severity - 或更高消息的日志条目中。 + 控制在服务器日志中记录哪些导致错误条件的SQL语句。对于达到指定严重级别或更高级别的消息,其日志条目中会包含当前 SQL 语句。 有效值为DEBUG5DEBUG4DEBUG3DEBUG2DEBUG1、 @@ -4485,7 +4470,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -4505,7 +4490,7 @@ local0.* /var/log/postgresql - 设置所有语句都被记录的事务的比例,除了其他原因记录的语句。它适用于每个新事务,无论其语句的持续时间如何。 + 设置需要记录全部语句的事务比例,这些记录是在因其他原因记录的语句之外额外进行的。它适用于每个新事务,无论其语句的持续时间如何。 log_transaction_sample_rate可以帮助构建事务样本。 默认值为0,表示不记录任何额外事务的语句。将其设置为1会记录所有事务的所有语句。 只有超级用户能更改这个设置。 @@ -4541,7 +4526,7 @@ local0.* /var/log/postgresql DEBUG1..DEBUG5 - 为开发者提供连续的更详细的信息。 + 为开发者提供逐级更加详细的信息。 DEBUG INFORMATION @@ -4600,7 +4585,7 @@ local0.* /var/log/postgresql - 记录什么到日志 + 记录哪些内容 @@ -4621,7 +4606,7 @@ local0.* /var/log/postgresql - application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。它也会被通过包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为问号(?)。 + application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。也可以通过将其包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为问号(?)。 @@ -4645,7 +4630,6 @@ local0.* /var/log/postgresql - 这个参数启用发出各种调试输出。当设置时,会打印生成的解析树, 查询重写输出,或执行的每个查询的执行计划。这些信息是在LOG 信息级别发出,因此默认的,它们会出现在服务器日志中,但不会发送给客户端。 可以通过 client_min_messages和/或log_min_messages 来设置。这些参数缺省是off。 这些参数将会让多种调试输出被发出。当被设置时,它们为每一个被执行的查询打印结果分析树、查询重写器输出或执行计划。这些消息在LOG消息级别上被发出,因此默认情况下它们将出现在服务器日志中但不会被发送到客户端。你可以通过调整和/或来改变这种情况。这些参数默认是关闭的。 @@ -4679,7 +4663,7 @@ local0.* /var/log/postgresql 导致检查点和重启点在服务器日志中记录。日志消息中包括一些统计信息, 包括写入的缓冲区数量和写入它们所花费的时间。此参数只能在 - postgresql.conf文件或服务器命令行中设置。默认值为开启。 + postgresql.conf文件或服务器命令行中设置。默认值为关闭。 @@ -4738,7 +4722,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -4761,7 +4745,7 @@ local0.* /var/log/postgresql 控制在服务器日志中记录的每条消息的详细程度。有效值为TERSE, - DEFAULTVERBOSE,每个值都会添加更多字段到显示的消息中。 + DEFAULTVERBOSE,它们依次在显示的消息中增加更多字段。 TERSE不包括DETAILHINTQUERYCONTEXT错误信息的记录。 VERBOSE输出包括SQLSTATE错误代码 @@ -4781,7 +4765,7 @@ local0.* /var/log/postgresql - 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致很微小的性能损失。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致不可忽视的性能开销。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -4854,8 +4838,8 @@ local0.* /var/log/postgresql %n - 带毫秒的时间戳(作为 Unix 时代) - no + 带毫秒精度的 Unix 时间戳 + %i @@ -4970,7 +4954,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' UPDATEDELETETRUNCATE, 和COPY FROM。 如果PREPAREEXECUTE和 - EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个执行消息时会产生日志并且会包括绑定参数的值(任何内嵌的单引号会被双写)。 + EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个 Execute 消息时会产生日志并且会包括 Bind 参数的值(任何内嵌的单引号会被双写)。 @@ -4981,7 +4965,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在执行阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 + 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在 Execute 阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 @@ -5020,7 +5004,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 控制临时文件名和大小的日志记录。 - 临时文件可以用于排序、哈希和临时查询结果。 + 临时文件可以用于排序、hash 和临时查询结果。 如果通过此设置启用,每当删除临时文件时都会发出日志记录。 值为零时记录所有临时文件信息,而正值仅记录大小大于或等于指定数据量的文件。 如果未指定单位,则将其视为千字节。 @@ -5099,7 +5083,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 设置log_filenamelog_rotation_age为你的日志文件提供一种一致的、可预测的命名空间。这让你预测文件名会是怎样以及知道什么时候一个个体日志文件完成并且因此准备好被导入。 + 设置log_filenamelog_rotation_age,为日志文件提供一致且可预测的命名方案。这样就能预测文件名,并知道单个日志文件何时已完成写入、可以导入。 @@ -5128,8 +5112,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 进程标题 - 这些设置控制服务器进程的进程标题如何修改。通常可以通过ps等程序查看进程标题, - 在 Windows 上则可以使用Process Explorer。详情参见。 + 这些设置控制服务器进程的进程标题如何修改。通常可以通过ps等程序查看进程标题,在 Windows 上则可以使用Process Explorer。详情参见 @@ -5161,7 +5144,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 每次服务器接收到新的SQL命令时,都可以更新进程标题。 + 启用后,每次服务器接收到新的 SQL 命令时都会更新进程标题。 在大多数平台上,默认情况下此设置为on,但在Windows上默认为off, 因为该平台更新进程标题的开销较大。 只有超级用户能更改这个设置。 @@ -5196,7 +5179,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对每个会话当前执行命令的信息收集,包括命令开始执行的时间。 - 此参数默认为开启状态。请注意,即使启用了此信息,只有超级用户、具有 + 此参数默认为开启状态。请注意,即使启用了此参数,只有超级用户、具有 pg_read_all_stats角色权限的角色和拥有被报告会话的用户 (包括属于他们具有权限的角色的会话)才能看到此信息,因此不应构成安全风险。 只有超级用户能更改这个设置。 @@ -5214,7 +5197,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 为每个活动会话指定存储当前执行命令的文本所保留的内存量,它们被用于pg_stat_activity.query域。 + 为每个活动会话指定存储当前执行命令的文本所预留的内存量,它们被用于pg_stat_activity.query字段。 如果指定值时没有单位,则以字节为单位。默认值是 1024字节。这个参数只能在服务器启动时被设置。 @@ -5231,7 +5214,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对数据库活动的统计信息收集。 - 此参数默认为开启,因为自动清理守护进程需要收集的信息。 + 此参数默认为开启,因为自动清理守护进程需要这些收集到的信息。 只有超级用户能更改这个设置。 @@ -5245,7 +5228,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用数据库I/O调用的计时。 默认情况下,此参数处于关闭状态,因为它将重复查询操作系统的当前时间,这可能会在某些平台上造成显著的开销。 您可以使用工具来测量系统上计时的开销。 + 启用数据库I/O调用的计时。 默认情况下,此参数处于关闭状态,因为它将重复查询操作系统的当前时间,这可能会在某些平台上造成显著的开销。 你可以使用工具来测量系统上计时的开销。 I/O计时信息显示在中,也显示在使用BUFFERS选项的输出中, 并由提供。只有超级用户能更改这个设置。 @@ -5262,7 +5245,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用函数调用次数和时间的跟踪。指定pl以仅跟踪过程语言函数, + 启用函数调用次数和耗时的跟踪。指定pl以仅跟踪过程语言函数, all以同时跟踪SQL和C语言函数。默认值为none, 即禁用函数统计跟踪。只有超级用户能更改这个设置。 @@ -5322,7 +5305,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 对于每个查询,将各自模块的性能统计输出到服务器日志中。这是一个简单的性能分析工具,类似于Unix getrusage()操作系统功能。 - log_statement_stats报告总语句统计,而其他选项报告每个模块的统计信息。 + log_statement_stats报告整个语句的统计信息,而其他选项报告每个模块的统计信息。 log_statement_stats不能与任何单独模块选项一起启用。所有这些选项默认情况下都是禁用的。 只有超级用户才能更改这些设置。 @@ -5338,7 +5321,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 自动清理 - autovacuum + 自动清理 配置参数 @@ -5379,10 +5362,10 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 每次由自动清理执行的操作都会被记录,如果运行时间至少达到指定时间。将此设置为零会记录所有自动清理操作。 + 当自动清理执行的操作运行时间至少达到指定时间时,就会记录该操作。将此设置为零会记录所有自动清理操作。 -1(默认值)会禁用记录自动清理操作。如果未指定单位,则将其视为毫秒。 例如,如果将其设置为250ms,则所有运行时间为250ms或更长的自动清理和分析都将被记录。 - 此外,当此参数设置为任何值而不是-1时,如果由于冲突的锁定或同时删除的关系而跳过自动清理操作,则会记录消息。 + 此外,当此参数设置为任何非-1值时,如果由于冲突锁或关系被并发删除而跳过自动清理操作,则会记录消息。 启用此参数可帮助跟踪自动清理活动。 此参数只能在postgresql.conf文件或服务器命令行中设置;但可以通过更改表存储参数来覆盖对单个表的设置。 @@ -5581,7 +5564,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; DEBUG1LOGNOTICEWARNINGERROR。 每个级别都包括其后的所有级别。级别越靠后,被发送的消息越少。默认值是NOTICE。 - 注意LOG在这里有与中不同的排名。 + 注意LOG在这里的排序与中的不同。 @@ -5599,11 +5582,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,用于进行搜索该对象的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 + 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,搜索该对象时的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 - search_path的值必需是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被安静地忽略。 + search_path的值必须是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被静默忽略。 @@ -5631,11 +5614,12 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个参数的缺省值是"$user", public。这种设置支持一个数据库(其中没有用户拥有私有模式,并且所有人共享使用public)、每个用户私有模式及其组合的共享使用。其它效果可以通过全局或者针对每个用户修改默认搜索路径设置获得。 + 这个参数的默认值是"$user", public。这种设置支持共享使用数据库(用户没有私有模式,所有人共享使用public)、每个用户拥有私有模式,以及二者的组合。 + 还可以通过全局或针对每个用户修改默认搜索路径设置来获得其他效果。 - 更多有关方案处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 + 更多有关模式处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 @@ -5655,7 +5639,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,只要有至少一条策略被应用则查询就会失败。默认为on。受限的行可见性会导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS)属性的角色没有效果。 + 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,原本会应用至少一条策略的查询就会失败。默认为on。受限的行可见性可能导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS属性的角色)没有效果。 @@ -5674,8 +5658,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个参数指定了在创建表或物化视图时使用的默认表访问方法,如果CREATE命令没有明确指定访问方法, - 或者当使用SELECT ... INTO时,不允许指定表访问方法。默认值是heap。 + 创建表或物化视图时,如果CREATE命令没有显式指定访问方法,或者使用了不允许指定表访问方法的SELECT ... INTO,则使用此参数指定的默认表访问方法。默认值为heap @@ -5695,7 +5678,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建企图将失败。 + 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建尝试将失败。 @@ -5703,7 +5686,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当创建数据库时也会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 + 创建数据库时也不会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 @@ -5732,11 +5715,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被放置在里表中的连续表空间中。如果列表被选中元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 + 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被依次放置在列表中的连续表空间中。如果列表中被选中的元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 - 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,类似于为用户指定一个不具有CREATE权限的表空间。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特殊地,使用一个在postgresql.conf中设置的值时,这条规则起效。 + 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,指定一个用户不具有CREATE权限的表空间也同样是错误。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特别是,使用一个在postgresql.conf中设置的值时,这条规则起效。 @@ -5759,7 +5742,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 这个参数通常为打开。 当设置为off时,它禁用期间对函数体字符串的验证。 - 禁用验证避免了验证处理的副作用,特别避免了如向前引用导致的伪肯定。 + 禁用验证避免了验证处理的副作用,也避免前向引用等问题导致的误报。 在代表其他用户载入函数之前设置这个参数为offpg_dump会自动这样做。 @@ -5802,7 +5785,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态 。默认是off(读/写)。 + 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态。默认是off(读/写)。 @@ -5823,11 +5806,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当运行在serializable隔离级别时,一个可延迟只读 SQL 事务可以在它被允许继续之前延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的负荷;因此串行化代码将没有任何理由因为并发更新而强制它中断,使得这个选项适合于长时间运行的只读事务。 + 当运行在serializable隔离级别时,一个可延迟只读 SQL 事务可能在获准继续之前被延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的开销;因此串行化代码将没有任何理由因为并发更新而强制它中止,使得这个选项适合于长时间运行的只读事务。 - 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些操作在低于serializable隔离级别上的事务无效。默认值是off。 + 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些运行在低于serializable隔离级别上的事务无效。默认值是off @@ -5871,7 +5854,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的只读状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -5891,7 +5874,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的可延迟性状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -5905,16 +5888,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 控制当前会话中复制相关触发器和规则的触发。 - 可能的值是origin(默认值), - replicalocal。 - 设置此参数会导致丢弃先前缓存的任何查询计划。 - 只有超级用户能更改这个设置。 + 控制当前会话中复制相关触发器和规则的触发。设置此变量需要超级用户权限,并会丢弃任何先前缓存的查询计划。 + 可用值为origin(默认值)、replicalocal 这个设置的预期用途是由逻辑复制系统在应用所复制的更改时将它设置为replica。 - 其效果将是触发器和规则(没有对其默认配置做修改)在复制机上将不会被触发。 + 其效果将是触发器和规则(没有对其默认配置做修改)在副本上将不会被触发。 更多信息请参考的子句ENABLE TRIGGER以及ENABLE RULE @@ -5942,9 +5922,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 超时从命令到达服务器的时间开始计算,一直到它被服务器完成为止。 - 在扩展查询协议中,当任何与查询相关的消息(Parse、Bind、Execute、Describe)到达时,超时就开始计时, - 并在 Execute 或 Sync 消息完成时取消。 + 超时从命令到达服务器时开始计算,直到服务器完成该命令为止。 + 在扩展查询协议中,当任何与查询相关的消息(Parse、Bind、Execute、Describe)到达时开始计时, + 并在处理完 Execute 或 Sync 消息时取消计时。 @@ -5963,13 +5943,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 如果任何语句在试图获取表、索引、行或其他数据库对象上的锁时等到超过指定的时间量,该语句将被中止。 + 如果任何语句在试图获取表、索引、行或其他数据库对象上的锁时等待超过指定的时间量,该语句将被中止。 该时间限制独立地应用于每一次锁获取尝试。该限制会应用到显式锁定请求(如LOCK TABLE或不带NOWAITSELECT FOR UPDATE)和隐式获得的锁。 如果指定值时没有单位,则以毫秒为单位。一个零值(默认)将禁用超时。 - 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为事务超时将总是第一个被触发。 + 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为语句超时将总是第一个被触发。 如果log_min_error_statement 被设置为ERROR 或更低,超时的语句将被记录。 @@ -6003,8 +5983,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; + - 当表的pg_class.relfrozenxid字段达到该设置指定的年龄时,VACUUM会执行激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值是 1.5 亿个事务。尽管用户可以将该值设置为 0 到 20 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的 95%,从而在触发防回卷 autovacuum 之前仍有机会执行一次常规手工VACUUM。更多信息请参见。 + 如果表的pg_class.relfrozenxid字段达到此设置指定的年龄,VACUUM就会执行一次激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值为 1.5 亿个事务。尽管用户可以将该值设置在 0 到 20 亿之间,VACUUM仍会悄悄将其有效值限制为不超过的 95%,以便在针对该表启动防回卷自动清理之前,周期性手工VACUUM仍有机会运行。详见 @@ -6017,7 +5998,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 指定VACUUM在扫描表时用来决定是否冻结行版本的切断年龄(以事务计)。默认值是 5000 万个事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见。 + 指定VACUUM在扫描表时用来决定是否冻结行版本的截止年龄(以事务计)。默认值是 5000 万个事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见 @@ -6029,8 +6010,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; + - 当表的pg_class.relminmxid字段达到该设置指定的年龄时,VACUUM会执行激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不是只扫描那些可能包含死元组的页面。默认值是 1.5 亿个多事务。尽管用户可以将该值设置为 0 到 20 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的 95%,从而在触发防回卷 autovacuum 之前仍有机会执行一次常规手工VACUUM。更多信息请参见。 + 如果表的pg_class.relminmxid字段达到此设置指定的年龄,VACUUM就会执行一次激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值为 1.5 亿个多事务。尽管用户可以将该值设置在 0 到 20 亿之间,VACUUM仍会悄悄将其有效值限制为不超过的 95%,以便在针对该表启动防回卷清理之前,周期性手工VACUUM仍有机会运行。详见 @@ -6043,7 +6025,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 指定VACUUM在扫描表时用来决定是否将多事务 ID 替换为较新的事务 ID 或多事务 ID 的切断年龄(以多事务计)。默认值是 500 万个多事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见。 + 指定VACUUM在扫描表时用来决定是否将多事务 ID 替换为较新的事务 ID 或多事务 ID 的截止年龄(以多事务计)。默认值是 500 万个多事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见 @@ -6107,7 +6089,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这里的实际选择都是根据爱好做出的,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码将比 base64 编码更大。 + 这里的实际选择主要取决于偏好,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码会比 base64 编码略大。 @@ -6128,7 +6110,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当在XML和字符串值之间进行转换时,无论设置DOCUMENT或 CONTENT都是隐式的。可参阅Section 8.13。 有效值是DOCUMENT和CONTENT。 缺省值是CONTENT。当在 XML 和字符串值之间进行转换时,设置DOCUMENTCONTENT都是隐式的。详见。有效值是DOCUMENTCONTENT。默认值是CONTENT。 + 设置在 XML 与字符串值之间进行转换时,隐含采用DOCUMENT还是CONTENT。 + 有关说明参见。有效值是DOCUMENTCONTENT。默认值是CONTENT @@ -6179,7 +6162,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 区域和格式化 + 区域设置和格式化 @@ -6193,7 +6176,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域行为的设置初始化配置文件。 + 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域设置行为的设置初始化配置文件。 @@ -6206,10 +6189,13 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置间隔值的显示格式。值sql_standard将产生匹配SQL标准间隔文本的输出。当参数被设置为ISO时,值postgres(默认)将产生匹配PostgreSQL发行 8.4 之前的输出。当DateStyle参数被设置为非ISO输出时,值postgres_verbose会产生匹配PostgreSQL发行 8.4 之前的输出。值iso_8601会产生匹配在 ISO 8601 的 4.4.3.2 节中定义的带标志符格式的时间间隔的输出。 + 设置时间间隔值的显示格式。值sql_standard会生成符合SQL标准时间间隔字面量的输出。 + 值postgres(默认值)的输出与PostgreSQL 8.4 之前版本中设为ISO时的输出一致。 + 值postgres_verbose的输出与PostgreSQL 8.4 之前版本中DateStyle设为非ISO输出时的输出一致。 + 值iso_8601会生成符合 ISO 8601 第 4.4.3.2 节定义的时间间隔带标志符格式的输出。 - IntervalStyle参数也可以影响对有歧义的间隔输入的解释。详见。 + IntervalStyle参数也会影响对有歧义的时间间隔输入的解释。详见 @@ -6267,23 +6253,23 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 如果值为1(默认值)或更高,浮点值被输出为最短-精度格式;参见。 + 如果值为 1(默认值)或更高,浮点值被输出为最短精确格式;参见。 实际生成的位数只取决于输出的值,而不取决于此参数的值。 - float8 值最多需要 17 位数字,float4值最多需要9位数字。 + float8 值最多需要 17 位数字,float4值最多需要9位数字。 这种格式既快速又精确,在正确读取时精确地保留了原始的二进制浮点值。为了历史兼容性,允许的值最大为3。 如果值为零或负,则输出四舍五入为给定的十进制精度。 - 使用的精度是根据此参数的值减小的类型((FLT_DIGDBL_DIG,视情况而定)的标准位数。 + 所用精度以该类型的标准位数(根据类型使用FLT_DIGDBL_DIG)为基础,再按此参数的值减少。 (例如,指定 -1 将导致float4 值输出四舍五入为 5 位有效数字,而float8值四舍五入为 14 位。) - 此格式较慢,不会保留二进制浮点值的所有位,但可能令人更易于阅读。 + 此格式较慢,不会保留二进制浮点值的所有位,但可能更便于阅读。 此参数的含义,以及其默认值,在 PostgreSQL 12 中发生了变化; - 参见 以便进一步讨论。 + 参见 了解进一步讨论。 @@ -6319,11 +6305,11 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 在一些系统上,这个区域分类并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 + 在一些系统上,这个区域设置类别并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 - 只有超级用户能更改这个设置。 + 只有超级用户能更改这个设置,因为它会同时影响发送到服务器日志和客户端的消息,设置不当可能降低服务器日志的可读性。 @@ -6338,7 +6324,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化货币量的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化货币量的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -6353,7 +6339,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化数字的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化数字的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -6368,7 +6354,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化日期和时间的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化日期和时间的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -6383,7 +6369,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 选择被那些没有显式参数指定配置的文本搜索函数变体使用的文本搜索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配区域的配置,initdb将用对应于选中的lc_ctype区域的设置初始化配置文件。 + 选择被那些没有显式参数指定配置的文本检索函数变体使用的文本检索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配该区域设置的配置,initdb将用对应于选中的lc_ctype区域设置的值初始化配置文件。 @@ -6397,7 +6383,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 为了载入附加的功能或者达到提高性能的目的,可用多个设置来预先载入共享库到服务器中。 - 例如'$libdir/mylib'设置可能会导致mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 + 例如'$libdir/mylib'设置会使mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 @@ -6406,12 +6392,12 @@ SET XML OPTION { DOCUMENT | CONTENT }; 只有特别为与PostgreSQL一起使用设计的共享库才能以这种方式载入。每一个PostgreSQL支持 - 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非PostgreSQL无法 + 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非 PostgreSQL 库无法 以这种方式被载入。你可能可以使用操作系统的工具(如LD_PRELOAD)载入它。 - 总之,请参考特定模块的文档来用推荐的方法载入它。 + 一般来说,请参考特定模块的文档来用推荐的方法载入它。 @@ -6443,9 +6429,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 这个特性的目的是允许非特权用户在特定的会话中载入正在调试的或者性能度量库, - 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客 - 户端的PGOPTIONS环境变量或者 + 这个特性的目的是允许非特权用户在特定的会话中载入用于调试或性能测量的库, + 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客户端的PGOPTIONS环境变量或者 ALTER ROLE SET来设置这个参数。 @@ -6482,7 +6467,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 不同,相对于在库被第一次使用 - 时载入它,在会话开始时载入库并没有什么性能优势。不过,当使用连接池时这样做还是有一些 + 时载入它,在会话开始时载入库并没有明显的性能优势。不过,当使用连接池时这样做还是有一些 优势。 @@ -6520,9 +6505,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 在 Windows 主机上,在服务器启动时预载入一个库并不会减少启动每个新服务器进程所需的 - 时间;每一个服务器进程将会重新载入预载入的库。不过,对于那些要在postmaster启动时 + 时间;每一个服务器进程将会重新载入所有预载入的库。不过,对于那些要在postmaster启动时 执行操作的库来说,Windows 主机上的 - shared_preload_libraries任然有用。 + shared_preload_libraries仍然有用。 @@ -6596,7 +6581,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - GIN 索引返回的集合尺寸的软上限。详见。 + GIN 索引扫描返回的集合尺寸的软上限。详见 @@ -6628,18 +6613,18 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这是在锁上等待的时间,然后再检查是否存在死锁条件。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 + 指定在检查是否发生死锁之前等待锁的时间。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 我们乐观地假设在生产应用程序中死锁并不常见,所以在检查死锁之前只是等待一段时间。 增加此值会减少在不必要的死锁检查中浪费的时间,但会减慢实际死锁错误的报告速度。 如果未指定单位,则将其视为毫秒。 - 默认值为一秒(1s),这可能是您在实践中想要的最小值。 - 在负载较重的服务器上,您可能希望提高它。 - 理想情况下,设置应超过您的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 + 默认值为一秒(1s),这可能是你在实践中想要的最小值。 + 在负载较重的服务器上,你可能希望提高它。 + 理想情况下,设置应超过你的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 只有超级用户能更改这个设置。 - 当被设置时,这个参数还可以决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 + 当被设置时,这个参数也决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 @@ -6690,7 +6675,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制在谓词锁被提升为覆盖整个关系之前,该谓词锁能够在单个关系上锁住多少页面或元组。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个关系之前,可以对单个关系中的多少页面或元组加谓词锁。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -6705,7 +6690,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制在谓词锁被提升为覆盖整个页面之前,该谓词锁能在单一页面上锁住多少行。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个页面之前,可以对单个页面中的多少行加谓词锁。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -6731,7 +6716,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个空数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。对于那些要求旧行为的应用的向后兼容性,这个变量可以被设置为off。 + 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个值为空值的数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。为了向后兼容那些要求旧行为的应用,这个变量可以被设置为off @@ -6749,11 +6734,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制字符串文本中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\。如果客户端代码没有做到正确转义,那么将会导致 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 + 这个参数控制字符串字面量中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\。如果客户端代码没有做到正确转义,那么就可能遭到 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 - 注意在符合标准的字符串文本中,\就表示\。这个参数只影响不符合标准的文本的处理,包括转义字符串语法(E'...')。 + 注意在符合标准的字符串字面量中,\就表示\。这个参数只影响不符合标准的字面量的处理,包括转义字符串语法(E'...')。 @@ -6769,11 +6754,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 打开时,如果在普通字符串文本中('...'语法)出现了 一个反斜线(\)并且standard_conforming_strings为关闭,那么就会发出一个警告。默认值是on。 + 打开时,如果在普通字符串字面量中('...'语法)出现了 一个反斜线(\)并且standard_conforming_strings为关闭,那么就会发出一个警告。默认值是on - 希望使用反斜线作为转义符的应用应该被修改来使用转义字符串语法(E'...'),因为在 SQL 标准中普通字符串的默认行为是将反斜线视作一个普通字符。这个变量可以被启用来帮助定位需要被更改的代码。 + 希望使用反斜线作为转义符的应用应该被修改来使用转义字符串语法(E'...'),因为按照 SQL 标准,普通字符串现在默认将反斜线视作一个普通字符。这个变量可以被启用来帮助定位需要被更改的代码。 @@ -6794,7 +6779,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 设置这个参数不会禁用所有与大对象相关的安全检查 — 除了那些在PostgreSQL 9.0中已经修改了的默认行为。 + 设置此变量不会禁用所有与大对象相关的安全检查 — 只禁用那些在PostgreSQL 9.0 中默认行为发生变化的检查。 @@ -6836,7 +6821,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' standard_conforming_strings (boolean) - 字符串标准符合 + 字符串符合标准 standard_conforming_strings配置参数 @@ -6844,7 +6829,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 控制普通字符串文本('...')是否按照 SQL 标准把反斜线当普通文本。从PostgreSQL 9.1 开始,默认值为on(之前的发行中默认值为off)。应用可以检查这个参数来判断字符串文本如何被处理。这个参数的存在也可以被当做转义字符串语法(E'...')被支持的标志。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 + 控制普通字符串字面量('...')是否按照 SQL 标准把反斜线当普通文本。从PostgreSQL 9.1 开始,默认值为on(之前的发行中默认值为off)。应用可以检查这个参数来判断字符串字面量如何被处理。这个参数的存在也可以被当做转义字符串语法(E'...')被支持的标志。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 @@ -6859,7 +6844,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询来,这样的扫描会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on。 + 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询,这样的扫描可能会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on @@ -6882,15 +6867,15 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr得出空值值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空(未知)。因此这个参数默认为off。 + 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr计算结果为空值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空值(未知)。因此这个参数默认为off - 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释)。它们不是非常有用并且在普通应用中也不常见,在应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及 空值的表达式的语义上感到困惑,因此这个选项默认为关闭。 + 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释),它们不是非常有用并且在普通应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及空值的表达式语义感到困惑,因此这个选项默认为关闭。 - 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不是劣质程序的一般修复。 + 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不能普遍修复错误的程序写法。 @@ -6933,7 +6918,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 当被设置为开(on),PostgreSQL将在一次后端崩溃后自动重新初始化。 + 当设置为 on(默认值)时,PostgreSQL将在一次后端崩溃后自动重新初始化。 让这个值设置为开(on)通常是将数据库可用性最大化的最佳方法。但是在某些环境中,例如PostgreSQL被集群软件调用时,禁用重启可能很有用,这样集群软件可以得到控制并且采取它认为适当的行动。 @@ -6953,7 +6938,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果设置为关(off),PostgreSQL在将修改的数据文件刷新到文件系统失败时,将引发PANIC级错误。 + 当设置为 off(默认值)时,PostgreSQL在将修改后的数据文件刷盘到文件系统失败时,将引发PANIC级错误。 这样会导致数据库服务器崩溃。这个参数只能在服务器启动时被设置。 @@ -6962,8 +6947,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果设置为开(on),PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷新操作。 - 仅在调查操作系统假如回写失败时对缓冲数据的处理方式的情况下,才将其设置为开(on)。 + 如果设置为开(on),PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷盘操作。 + 只有在调查清楚操作系统在回写失败时如何处理缓冲数据之后,才应将其设置为开(on)。 @@ -6976,11 +6961,10 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 预置选项 - 下列参数是只读的。 - 同样,它们被排除在postgresql.conf文件示例之外。 - 这些选项报告特定应用可能感兴趣的多种PostgreSQL行为,特别是管理前端相关的行为。 - 所有这些都是在PostgreSQL被编译或者它被安装时决定的。 - + 下列参数是只读的,在编译或安装 PostgreSQL 时确定。 + 因此,它们未列入示例 postgresql.conf 文件。 + 这些选项报告 PostgreSQL 行为的各个方面,某些应用(特别是管理前端)可能对此感兴趣。 + @@ -7009,7 +6993,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告对这个集簇是否启用了数据校验码。详见。 + 报告对这个集簇是否启用了数据校验和。详见 @@ -7022,7 +7006,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 在Unix系统上,这个参数报告启动时的数据目录(由定义)的权限。 + 在 Unix 系统上,这个参数报告服务器启动时数据目录(由定义)的权限。 (在Microsoft Windows上这个参数将总是显示0700。) 更多信息请参考 @@ -7058,7 +7042,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告PostgreSQL是否在编译时打开了 64 位整数日期和时间。从PostgreSQL 10起,这个值总是on。 + 报告PostgreSQL是否在编译时启用了对 64 位整数日期和时间的支持。从PostgreSQL 10起,这个值总是on @@ -7105,7 +7089,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定的。默认值是 100 个参数。 + 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定。默认值是 100 个参数。 @@ -7120,7 +7104,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64 ;因此max_identifier_length的默认值是 63,但是在使用多字节编码时可以少于 63 个字符。 + 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64;因此max_identifier_length的默认值是 63 字节,在使用多字节编码时,这可能不足 63 个字符。 @@ -7181,7 +7165,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告服务器版本数值。它是由编译服务器时的PG_VERSION值决定的。 + 报告服务器的版本号。它是由编译服务器时的PG_VERSION值决定的。 @@ -7196,7 +7180,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告服务器版本数值的整数值。它是由编译服务器时的PG_VERSION_NUM值决定的。 + 以整数形式报告服务器的版本号。它是由编译服务器时的PG_VERSION_NUM值决定的。 @@ -7211,8 +7195,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告此PostgreSQL服务器已构建的 SSL 库的名称(即使此实例当前未配置或使用 SSL), - 例如OpenSSL,或一个空字符串(如果没有)。 + 报告此PostgreSQL服务器在构建时使用的 SSL 库的名称(即使此实例当前未配置或使用 SSL), + 例如OpenSSL,如果没有使用 SSL 库,则报告空字符串。 @@ -7255,11 +7239,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 自定义选项 - 这个特性被设计用来由附加模块向PostgreSQL添加通常不为系统知道的参数(例如过程语言)。这允许使用标准方法配置扩展模块。 + 这个特性允许附加模块(例如过程语言)向PostgreSQL添加系统通常不认识的参数。这样便能以标准方式配置扩展模块。 - 自定义选项有两部分名称:一个扩展名,然后是一个句点,再然后是正确的参数名,就像 SQL 中的合格名称。一个示例是plpgsql.variable_conflict。 + 自定义选项的名称由两部分组成:扩展名称和参数名本身,中间用句点分隔,类似于 SQL 中的限定名。例如plpgsql.variable_conflict @@ -7267,7 +7251,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' PostgreSQL将接受任何两部分参数名称的设置。 这些变量被视为占位符,在定义它们的模块加载之前没有任何功能。 当加载扩展模块时,它将添加其变量定义并根据这些定义转换任何占位符值。 - 如果存在以其扩展名开头的任何未识别的占位符,将发出警告并删除这些占位符。 + 如果存在以其扩展名称开头的任何未识别的占位符,将发出警告。 @@ -7291,7 +7275,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 允许将表空间创建为pg_tblspc内的目录,当CREATE TABLESPACE命令提供空位置字符串时。 + 当向CREATE TABLESPACE命令提供空的位置字符串时,允许将表空间创建为pg_tblspc内的目录。 这旨在允许测试主库和备库在同一台机器上运行的复制场景。这样的目录可能会混淆备份工具,因为这些工具期望在该位置只找到符号链接。 只有超级用户能更改这个设置。 @@ -7322,7 +7306,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据的时有用。这个参数在会话开始之后不能被更改。 + 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据时有用。这个参数在会话开始之后不能被更改。 @@ -7337,8 +7321,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 执行认证过程后启动新服务器进程时延迟的时间量。这是为了给开发者们一个机会在一个服务器进程上附加一个调试器。 - 如果指定值时没有单位,则以秒为单位。0值(默认值)禁用延迟。这个参数在会话开始之后不能被更改。 + 新服务器进程启动并完成认证过程之后的延迟时间。这旨在给开发者一个机会,用调试器附加到服务器进程上。 + 如果指定值时没有单位,则以秒为单位。零值(默认值)禁用延迟。这个参数在会话开始之后不能被更改。 @@ -7353,8 +7337,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 在新服务器进程分叉后,在进行认证过程之前,延迟的时间量。这是为了给开发者们一个机会在一个服务器进程上附加一个调试器来跟踪认证过程中的不当行为。 - 如果指定值时没有单位,则以秒为单位。0值(默认值)禁用延迟。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 新服务器进程刚刚派生之后、执行认证过程之前的延迟时间。这旨在给开发者一个机会,用调试器附加到服务器进程上,跟踪认证过程中的异常行为。 + 如果指定值时没有单位,则以秒为单位。零值(默认值)禁用延迟。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -7369,7 +7353,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 + 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 @@ -7404,7 +7388,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果打开,发出在排序操作中的资源使用的相关信息。只有在编译PostgreSQL时定义了TRACE_SORT宏, 这个参数才可用(不过,当前在默认情况下就定义了TRACE_SORT)。 + 如果开启,输出排序操作中的资源使用信息。只有在编译PostgreSQL时定义了TRACE_SORT宏, 这个参数才可用(不过,当前在默认情况下就定义了TRACE_SORT)。 @@ -7419,7 +7403,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。对每一种锁类型,已授权锁和等待锁的计数也会被一起转储。一个日志文件输出的示例如下: + 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。还会转储每种锁类型已授予的锁数、等待的锁数,以及它们的总数。一个日志文件输出的示例如下: LOG: LockAcquire: new: lock(0xb7acd844) id(24688,24696,0,0,0,1) grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0 @@ -7491,7 +7475,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果设置,不会跟踪小于这个 OID 的锁(用于避免在系统表上的输出)。 + 如果设置,不会跟踪 OID 小于此值的表上的锁(用于避免在系统表上的输出)。 @@ -7565,7 +7549,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,被修改的任何缓冲区的整页镜像及其WAL记录都被加入到记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 + 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,与该 WAL 记录相关的所有已修改缓冲区的整页镜像都会被添加到该记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 @@ -7608,11 +7592,11 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 在读取过程中检测到校验和失败通常会导致PostgreSQL报告错误,中止当前事务。 - 将ignore_checksum_failure设置为on会导致系统忽略失败(但仍然报告警告),并继续处理。 - 这种行为可能导致崩溃,传播或隐藏损坏,或其他严重问题。然而,它可能允许您跳过错误, - 并检索可能仍然存在于表中的未损坏的元组,如果块头仍然正常。如果头部损坏,即使启用此选项也会报告错误。 - 默认设置为off。 - 只有超级用户能更改这个设置。 + 将ignore_checksum_failure设置为 on 会使系统忽略失败(但仍报告警告),并继续处理。 + 这种行为可能导致崩溃、传播或隐藏损坏,或引发其他严重问题。 + 但是,如果块首部仍然正常,它可能允许你跳过错误,检索表中可能仍然存在的未损坏元组。 + 如果首部损坏,即使启用此选项也会报告错误。默认设置为off。 + 只有超级用户才能更改此设置。 @@ -7629,7 +7613,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 检测到损坏的页面头通常会导致PostgreSQL报告错误,中止当前事务。 将zero_damaged_pages设置为on会导致系统报告警告,将内存中的损坏页面清零,并继续处理。 - 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许您跳过错误,并从表中可能存在的未损坏页面中检索行。 + 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许你跳过错误,并从表中可能存在的未损坏页面中检索行。 如果由于硬件或软件错误而发生损坏,这对于恢复数据很有用。通常在放弃从表的损坏页面恢复数据的希望之前,不应将其设置为on。 清零的页面不会强制写入磁盘,因此建议在再次关闭此参数之前重新创建表或索引。默认设置为off。 只有超级用户能更改这个设置。 @@ -7645,7 +7629,8 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果LLVM有所需要的功能,用GDB注册所生成的函数。这会让调试更加容易。默认设置是off。这个参数只能在服务器启动时设置。 + 如果 LLVM 具有所需的功能,则向GDB注册生成的函数。 + 这会让调试更加容易。默认设置为off。这个参数只能在服务器启动时设置。 @@ -7661,7 +7646,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 将生成的LLVM IR写入文件系统,位于内。 - 这仅对于在JIT实现内部工作时有用。默认设置为off。 + 这仅对开发 JIT 的内部实现有用。默认设置为off。 只有超级用户能更改这个设置。 @@ -7690,10 +7675,9 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果LLVM有所需的功能,发出需要的数据以允许perf对JIT生成的函数画像。 - 这会写出文件到$HOME/.debug/jit/中,如果需要,由用户负责对其执行清除。 - 默认设置是off。 - 这个参数只能在服务器启动时设置。 + 如果 LLVM 具有所需的功能,则输出让perf对 JIT 生成的函数进行性能分析所需的数据。 + 这会将文件写入$HOME/.debug/jit/;用户应在需要时自行清理。 + 默认设置为off。这个参数只能在服务器启动时设置。 @@ -7719,11 +7703,11 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 短选项 - 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,并且它们作为一个单字母选项存在并不表示它们会被大量使用。 + 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,它们以单字母选项的形式存在,并不一定表示鼓励频繁使用这些选项。
- 短选项键 + 短选项对照 diff --git a/zh/12/datatype.sgml b/zh/12/datatype.sgml index 8240cb0e..db404776 100644 --- a/zh/12/datatype.sgml +++ b/zh/12/datatype.sgml @@ -148,7 +148,7 @@ line - 平面上的无限长的线 + 平面上的无限直线 @@ -160,19 +160,19 @@ macaddr - MAC(Media Access Control)地址 + MAC(媒体访问控制)地址 macaddr8 - MAC(Media Access Control)地址(EUI-64格式) + MAC(媒体访问控制)地址(EUI-64格式) money - 货币数量 + 货币额 @@ -180,7 +180,7 @@ s) ] decimal [ (p, s) ] - 可选择精度的精确数字 + 可选择精度的精确数值 @@ -192,7 +192,7 @@ pg_lsn - PostgreSQL日志序列号类型 + PostgreSQL 日志序列号 @@ -264,13 +264,13 @@ tsquery - 文本搜索查询 + 文本检索查询 tsvector - 文本搜索文档 + 文本检索文档 @@ -407,14 +407,14 @@
- 数字类型常量的语法在里描述。数字类型有一整套对应的数学操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 + 数字类型常量的语法在里描述。数字类型有一整套对应的算术操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 整数类型 - 整数 + integer @@ -427,7 +427,7 @@ int4 - 整数 + integer @@ -447,11 +447,11 @@
- 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。而只有在integer的范围不够的时候才使用bigint。 + 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。bigint则设计用于integer的范围不够的情况。 - SQL只声明了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在许多其它SQL数据库系统中使用。 + SQL只规定了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在某些其他SQL数据库系统中使用。 @@ -460,11 +460,11 @@ 任意精度数值 - 数字(数据类型) + numeric(数据类型) - 任意精度数字 + 任意精度数值 @@ -476,7 +476,14 @@ 类型numeric可以存储非常多位的数字。我们特别建议将它用于货币金额和其它要求计算准确的数量。numeric值的计算在可能的情况下会得到准确的结果,例如加法、减法、乘法。不过,numeric类型上的算术运算比整数类型或者下一节描述的浮点数类型要慢很多。
- 下面使用如下术语:numeric精度是整个数中有效数字的总数,即小数点两侧的数字位数之和。numeric小数位数是小数部分中十进制数字的数量,即小数点右侧的位数。因此,数值 23.5141 的精度为 6,小数位数为 4。整数可以视为小数位数为零。 + + 我们在下文中使用以下术语: + 精度(precision)是一个numeric + 值中有效数字的总位数,也就是小数点两侧数字的总数。 + 小数位数(scale)是小数部分中位于小数点 + 右侧的十进制位数。因此,数值 23.5141 的精度为 6,小数位数为 4。 + 整数可以认为其小数位数为 0。 + 可以配置numeric列的最大精度和最大小数位数。要声明numeric类型的列,使用以下语法: NUMERIC(precision, scale) @@ -506,12 +513,12 @@ NUMERIC NaN - 非数字 + 非数 - 非数字 - 数字(数据类型) + 非数 + numeric(数据类型) 除了普通数值外,numeric类型还允许特殊值NaN,表示非数。对NaN的任何运算都会产生另一个NaN。在 SQL 命令中将该值写为常量时,必须加上引号,例如UPDATE table SET x = 'NaN'。输入时,字符串NaN的识别不区分大小写。 @@ -565,7 +572,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 双精度 + double precision @@ -575,7 +582,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; float8 - 双精度 + double precision @@ -628,8 +635,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; 默认情况下,浮点值会以最短且精确的十进制表示形式输出; - 生成的十进制值比同一二进制精度下任何其他可表示值都更接近真实 - 存储的二进制值。(不过,为了避免输入例程普遍存在的一个错误, + 所生成的十进制值与实际存储的二进制值之间的距离,小于它与任何其他可用相同二进制精度表示的值之间的距离。(不过,为了避免输入例程普遍存在的一个错误, 即未能正确遵守舍入到最近偶数规则,当前输出值绝不会 恰好位于两个可表示值的正中间。) 对于float8值,最多使用 17 位有效十进制数字; @@ -638,14 +644,14 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 生成这种最短且精确的输出格式,比历史上的圆整格式要快得多。 + 生成这种最短且精确的输出格式,比历史上的舍入格式要快得多。 为了兼容旧版本PostgreSQL生成的输出, 并允许降低输出精度,可以使用 - 参数改为选择圆整后的 + 参数改为选择舍入后的 十进制输出。将该参数设置为 0 会恢复之前的默认行为,也就是把值 舍入为 6 位(对于float4)或 15 位 (对于float8)有效十进制数字。设置为负值会 @@ -659,14 +665,14 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 过去那些需要精确值的应用,往往必须把 + 过去那些需要精确值的应用,必须把 设置为 3 才能获得它们。 为了在版本之间获得最大兼容性,这类应用应继续这样做。 - 非数字 + 非数 double precision @@ -674,7 +680,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; Infinity -Infinity NaN -它们分别表示 IEEE 754 的特殊值无穷大负无穷大非数字。在 SQL 命令中将这些值写为常量时,必须加上引号,例如UPDATE table SET x = '-Infinity'。输入时,这些字符串的识别不区分大小写。 +它们分别表示 IEEE 754 的特殊值无穷大负无穷大非数。在 SQL 命令中将这些值写为常量时,必须加上引号,例如UPDATE table SET x = '-Infinity'。输入时,这些字符串的识别不区分大小写。 @@ -730,13 +736,13 @@ FROM generate_series(-3.5, 3.5, 1) as x; - auto-increment + 自动递增 serial - sequence - and serial type + 序列 + 与 serial 类型 @@ -861,7 +867,7 @@ ALTER SEQUENCE tablename_ SELECT '12.34'::float8::numeric::money; - 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有圆整错误。 + 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有舍入误差。 @@ -873,7 +879,7 @@ SELECT '52093.89'::money::numeric::float8; 一个 money 值除以一个整数值时,会朝零方向截去小数 - 部分。要得到圆整结果,可以除以一个浮点值,或者在除法前先把 + 部分。要得到舍入后的结果,可以除以一个浮点值,或者在除法前先把 money 转换为 numeric,再在除法后转换回 money(如果要避免精度丢失风险,后一种做法更好)。 当一个 money 值被另一个 money 值除时, @@ -892,12 +898,12 @@ SELECT '52093.89'::money::numeric::float8; - string + 字符串 - 字符 + character @@ -932,7 +938,7 @@ SELECT '52093.89'::money::numeric::float8; character(n), char(n) - 定长,空白填充 + 定长,空格填充 text @@ -1004,7 +1010,7 @@ SELECT '52093.89'::money::numeric::float8; - 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储代码为零的字符(有时称为NUL)。有关更多信息,请参阅。 + 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储编码值为零的字符(有时称为NUL)。有关更多信息,请参阅 @@ -1023,7 +1029,7 @@ SELECT '52093.89'::money::numeric::float8; - 这三种类型之间没有性能差别,除了使用空白填充类型时会占用更多存储 + 这三种类型之间没有性能差别,除了使用空格填充类型时会占用更多存储 空间,以及在写入带长度约束的列时需要少量额外 CPU 周期来检查长度。 虽然在某些其他数据库系统中,character(n) 可能有一定性能优势,但在 PostgreSQL @@ -1058,7 +1064,7 @@ INSERT INTO test2 VALUES ('ok'); INSERT INTO test2 VALUES ('good '); INSERT INTO test2 VALUES ('too long'); ERROR: value too long for type character varying(5) -INSERT INTO test2 VALUES ('too long'::varchar(5)); -- explicit truncation +INSERT INTO test2 VALUES ('too long'::varchar(5)); -- 显式截断 SELECT b, char_length(b) FROM test2; b | char_length @@ -1177,13 +1183,15 @@ SELECT b, char_length(b) FROM test2; 开头(以便与转义格式区分)。在某些上下文中,这个开头的反斜线 可能需要通过双写进行转义(见 )。作为输入时,十六进制数字 - 可以使用大写或小写,并且在两个数字组成的一组之间允许出现空白 + 可以使用大写或小写,并且每两个数字组成一组,组与组之间允许出现空白 (但组内以及起始的 \x 序列中不能有空白)。 十六进制格式与大量外部应用和协议兼容,并且通常比转义格式转换得 更快,因此更推荐使用。 - 例如: + + 示例: + SET bytea_output = 'hex'; SELECT '\xDEADBEEF'::bytea; @@ -1234,7 +1242,7 @@ SELECT '\xDEADBEEF'::bytea; 0 - 0字节 + 零值字节 '\000' SELECT '\000'::bytea; \x00 @@ -1291,15 +1299,24 @@ SELECT '\xDEADBEEF'::bytea; - Bytea字节默认以hex格式输出。如果把改为escape, - 不可打印字节会被转换为等价的三位八进制值,并在前面加一个反斜线。大多数可打印字节以客户端字符集中相应的标准表示输出,例如: + 默认情况下,bytea 字节会以 hex + 格式输出。如果把 改为 + escape不可打印字节会被转换成 + 等价的三位八进制值,并在前面加一个反斜线。大多数 + 可打印字节则会按其在客户端字符集中的标准表示输出, + 例如: + + SET bytea_output = 'escape'; SELECT 'abc \153\154\155 \052\251\124'::bytea; bytea ---------------- abc klm *\251T -十进制值为 92 的字节(反斜线)在输出中会被双写。详情见。 + + + 十进制值 92(反斜线)的字节在输出中会被双写。详情见 + @@ -1365,10 +1382,10 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; time - 不带时区的时间 + time without time zone - 带时区的时间 + time with time zone timestamp @@ -1377,13 +1394,13 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; timestamptz - 带时区的时间戳 + timestamp with time zone - 不带时区的时间戳 + timestamp without time zone - 间隔 + interval 时间跨度 @@ -1467,7 +1484,7 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; - SQL 要求仅写 timestamp 时,应等效于 + SQL 标准要求仅写 timestamp 时,应等效于 timestamp without time zone,而 PostgreSQL 也遵循这种行为。 timestamptz 被接受为 @@ -1548,7 +1565,7 @@ MINUTE TO SECOND 其中 p 是可选的精度说明,给出秒字段中 保留的小数位数。精度可用于 timetimestampinterval 类型, - 范围是 0 到 6。这与前文描述的取值一致。如果在常量声明中没有指定 + 范围是 0 到 6。如果在常量声明中没有指定 精度,则默认采用该字面值本身的精度(但不超过 6 位)。 @@ -1575,7 +1592,7 @@ MINUTE TO SECOND 1999-01-08 - ISO 8601; 任何模式下的1月8日 + ISO 8601; 任何模式下的1月8日 (推荐格式) @@ -1611,27 +1628,27 @@ MINUTE TO SECOND 99-Jan-08 - YMD模式中的1月8日,否则错误 + YMD模式中的1月8日,否则报错 08-Jan-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 Jan-08-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 19990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 1999.008 - 年和一年中的日子 + 年和一年中的第几天 J2451187 @@ -1653,10 +1670,10 @@ MINUTE TO SECOND time - 无时区的时间 + time without time zone - 带时区的时间 + time with time zone @@ -1733,11 +1750,11 @@ MINUTE TO SECOND 040506+0730 - ISO 8601,以分数小时形式给出 UTC 偏移 + ISO 8601,时区的 UTC 偏移不是整小时 040506+07:30:00 - UTC偏移量指定为秒(ISO 8601中不允许) + UTC 偏移精确到秒(ISO 8601中不允许) 04:05:06 PST @@ -1814,20 +1831,34 @@ MINUTE TO SECOND - 带时区的时间戳 + timestamp with time zone - 无时区的时间戳 + timestamp without time zone - 时间戳类型的有效输入由日期与时间拼接而成,其后可以跟时区,再后可以跟ADBC。(或者,AD/BC可以出现在时区之前,但这不是首选顺序。)因此: + + 时间戳类型的有效输入由一个日期和时间的串接组成,后面跟着一个可选 + 时区,以及一个可选的 ADBC + (另外,AD/BC 也可以出现在 + 时区前面,但这种顺序并不推荐)。因此: + + 1999-01-08 04:05:06 -以及: + + 和: + 1999-01-08 04:05:06 -8:00 -都是有效值,遵循ISO8601 标准。此外,也支持下面这种常用格式: + + + 都是遵循 ISO 8601 标准的有效值。另外,广泛使用 + 的下列格式: + January 8 04:05:06 1999 PST - + + 也被支持。 + 按照SQL标准,timestamp without time zonetimestamp with time zone字面量的区别在于,时间后是否有+-符号及其后的时区偏移。因此,按照该标准,TIMESTAMP '2004-10-19 10:23:54'timestamp without time zone,而TIMESTAMP '2004-10-19 10:23:54+02'timestamp with time zonePostgreSQL在确定字符串字面量的类型之前,从不检查其内容,因此会把上述两者都视为timestamp without time zone。为确保字面量被视为timestamp with time zone,应为它显式指定正确类型:TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'若字面量已经被确定为timestamp without time zonePostgreSQL会静默忽略任何时区标记。也就是说,所得值来自输入值中的日期/时间字段,不会根据时区调整。 @@ -1857,12 +1888,12 @@ January 8 04:05:06 1999 PST time - constants + 常量 date - constants + 常量 @@ -1963,13 +1994,13 @@ January 8 04:05:06 1999 PST date 输出格式 - formatting + 格式化 time 输出格式 - formatting + 格式化 @@ -1999,7 +2030,7 @@ January 8 04:05:06 1999 PST ISO - ISO 8601, SQL标准 + ISO 8601,SQL 标准 1997-12-17 07:37:16-08 @@ -2030,7 +2061,7 @@ January 8 04:05:06 1999 PST - SQL和POSTGRES风格中,如果DMY域顺序被指定,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。 + SQL和POSTGRES风格中,如果指定了 DMY 字段顺序,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。
@@ -2093,7 +2124,7 @@ January 8 04:05:06 1999 PST 时区 - time zone + 时区 @@ -2148,7 +2179,8 @@ January 8 04:05:06 1999 PST - PostgreSQL允许使用三种不同形式指定时区: + PostgreSQL 允许使用三种不同形式来指定时区: + 完整时区名称,例如 America/New_York。 @@ -2177,11 +2209,20 @@ January 8 04:05:06 1999 PST 除了时区名称和缩写之外, PostgreSQL 还接受 POSIX 风格的 时区说明,见 。 - 这个选项通常不如使用具名时区更合适,但如果没有可用的 IANA - 时区条目,它可能就是必需的。 + 这个选项通常不如使用具名时区更合适,但如果没有合适的 IANA 时区条目可用,它可能就是必需的。 - 简而言之,缩写和完整名称的区别是:缩写表示特定的 UTC 偏移,而许多完整名称隐含本地夏令时规则,因此有两个可能的 UTC 偏移。例如,2014-06-04 12:00 America/New_York表示纽约当地时间的中午,在该日期使用的是东部夏令时间(UTC-4)。因此,2014-06-04 12:00 EDT指定相同的时刻。但是,2014-06-04 12:00 EST指定东部标准时间(UTC-5)的中午,而不管该日期是否名义上实行夏令时。 + + + 简而言之,这就是缩写和全名的区别:缩写表示某个特定的 UTC 偏移, + 而很多完整名称隐含了当地的夏令时规则,因此可能对应两个不同的 + UTC 偏移。例如, + 2014-06-04 12:00 America/New_York 表示纽约 + 当地时间中午;在这个具体日期,它属于东部夏令时(UTC-4),所以 + 2014-06-04 12:00 EDT 指定的是同一个时刻。 + 但 2014-06-04 12:00 EST 指定的是东部标准时 + 中午(UTC-5),无论当天名义上是否正在实行夏令时。 + 更复杂的是,一些司法辖区在不同时间使用同一时区缩写来表示不同的 @@ -2192,12 +2233,17 @@ January 8 04:05:06 1999 PST 当地民用时间。 - 在所有情况下,时区名称和缩写的识别都不区分大小写。(这与 8.2 之前的PostgreSQL版本不同;那些版本在某些上下文中区分大小写,在另一些上下文中则不区分。) + + 无论哪种形式,时区名称及其缩写都不区分大小写。(这是对 + PostgreSQL 8.2 之前版本的一项改动; + 在那些版本中,时区名在某些环境下区分大小写,而在另一些环境下则 + 不区分。) + 时区名称和缩写并不是硬编码在服务器中的;它们来自安装目录下 .../share/timezone/ 和 - .../share/timezonesets/ 子目录中的数据 + .../share/timezonesets/ 子目录中的配置文件 (见 )。 @@ -2235,13 +2281,13 @@ January 8 04:05:06 1999 PST - interval值可以使用下列语法书写: + interval值可以使用下列详细语法书写: @ quantity unit quantity unit... direction - 其中quantity是一个数字(很可能是有符号的); + 其中quantity是一个数字(可以带有符号); unitmicrosecondmillisecondsecondminutehourday、 @@ -2275,7 +2321,7 @@ January 8 04:05:06 1999 PST P quantity unit quantity unit ... T quantity unit ... 字符串必须以 P 开头,并且可以包含一个 - T 来引出一天中时间单位。可用的单位缩写见 + T 来引出一天中的时间单位。可用的单位缩写见 。单位可以省略, 也可以按任意顺序出现,但小于一天的单位必须出现在 T 之后。特别是,M 的含义 @@ -2314,7 +2360,7 @@ P quantity unit M - 分钟 (在时间部分中) + 分钟(在时间部分中) S @@ -2389,7 +2435,7 @@ P years-months- P1Y2M3DT4H5M6S - 带标志符的ISO 8601 格式:含义同上 + ISO 8601 带标志符的格式:含义同上 P0001-02-03T04:05:06 @@ -2419,7 +2465,7 @@ SELECT EXTRACT(days from '80 hours'::interval); interval 输出格式 - formatting + 格式化 @@ -2456,7 +2502,7 @@ SELECT EXTRACT(days from '80 hours'::interval); iso_8601 风格的输出符合 ISO 8601 标准 - 4.4.3.2 节描述的带标志符格式。 + 4.4.3.2 节描述的带标志符的格式
@@ -2507,7 +2553,7 @@ SELECT EXTRACT(days from '80 hours'::interval); 布尔类型 - Boolean + 布尔 数据类型 @@ -2618,15 +2664,15 @@ SELECT * FROM test1 WHERE a; 数据类型 - enumerated (enum) + 枚举(enum) - enumerated types + 枚举类型 - 枚举(enum)类型是由一个静态、值的有序集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的日期,或者一个数据的状态值集合。 + 枚举(enum)类型是由一个静态的有序值集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的各天,或者一个数据的状态值集合。 @@ -2735,7 +2781,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 实现细节 - 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空格也是有意义的。 + 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空白也是有意义的。 @@ -2747,7 +2793,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 从内部枚举值到文本标签的翻译被保存在系统目录pg_enum中。可以直接查询该目录。 + 从内部枚举值到文本标签的转换关系被保存在系统目录pg_enum中。直接查询该目录可能会有所帮助。 @@ -2818,7 +2864,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays circle24字节 - <(x,y),r>(中心点和半径) + <(x,y),r>(圆心和半径) @@ -2831,7 +2877,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 我们提供了丰富的函数和操作符来进行各种几何操作,例如缩放、平移、 - 旋转以及计算相交等,详见 。 + 旋转以及求交等,详见 @@ -2842,7 +2888,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 点是几何类型的基本二维构造块。用下面的语法描述point类型的值: + 点是几何类型的基本二维构造块。用下面任一种语法描述point类型的值: ( x , y ) @@ -2858,14 +2904,14 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线 + 直线 line - 线由线性方程Ax + By + C = 0 + 直线由线性方程Ax + By + C = 0 表示,其中AB不能同时为零。类型line 的值采用以下形式输入和输出: @@ -2885,7 +2931,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays (x1,y1)(x2,y2) - 是线上不同的两点。 + 是直线上不同的两点。 @@ -2901,7 +2947,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线段用一对线段的端点来表示。lseg类型的值用下面的语法声明: + 线段用一对线段的端点来表示。lseg类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ( x2 , y2 ) ] @@ -2925,15 +2971,15 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 方框 - box (data type) + box(数据类型) - rectangle + 矩形 - 方框用其对角的点对表示。box类型的值使用下面的语法指定: + 方框用其对角的点对表示。box类型的值使用下面任一种语法指定: ( ( x1 , y1 ) , ( x2 , y2 ) ) @@ -2952,7 +2998,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 在输入时可以提供任意两个对角,但是值将根据需要被按顺序记录为右上角和左下角。 + 在输入时可以提供任意两个对角,但是值将根据需要被重新排列,并依次存储为右上角和左下角。 @@ -2960,7 +3006,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 路径 - path (data type) + path(数据类型) @@ -2968,7 +3014,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - path类型的值用下面的语法声明: + path类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ... , ( xn , yn ) ] @@ -2978,11 +3024,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays x1 , y1 , ... , xn , yn - 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被忽略时,路径将被假定为封闭。 + 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被省略时,路径将被假定为封闭。 - 路径的输出使用第一种或第二种语法。 + 路径的输出视情况使用第一种或第二种语法。 @@ -3006,7 +3052,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - polygon类型的值用下列语法声明: + polygon类型的值用下列任一种语法指定: ( ( x1 , y1 ) , ... , ( xn , yn ) ) @@ -3031,7 +3077,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 圆由一个圆心和一个半径代表。circle类型的值用下面的语法指定: + 圆由一个圆心和一个半径代表。circle类型的值用下面任一种语法指定: < ( x , y ) , r > @@ -3054,7 +3100,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 网络地址类型 - network + 网络 数据类型 @@ -3108,8 +3154,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 在对 inetcidr 数据类型排序时,IPv4 - 地址总是排在 IPv6 地址之前,包括那些封装在 IPv6 地址中或映射到 - IPv6 地址中的 IPv4 地址,例如 ::10.2.3.4 或 + 地址总是排在 IPv6 地址之前,即使后者是封装或映射 IPv4 地址所得的 IPv6 地址,例如 ::10.2.3.4 或 ::ffff:10.4.3.2。 @@ -3155,7 +3200,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays cidr 类型保存 IPv4 或 IPv6 网络说明。输入和输出格式 遵循无类别域间路由(CIDR)约定。指定网络的格式为 address/y,其中 - address 是网络最低地址的 + address 是网络的 IPv4 或 IPv6 表示,而 y 是网络掩码中的位数。 如果省略 y,则会按照旧式 @@ -3265,7 +3310,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - <type>inet</type> vs. <type>cidr</type> + <type>inet</type> 与 <type>cidr</type> inetcidr 两种数据类型的本质区别在于: @@ -3291,12 +3336,12 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - MAC地址 + MAC 地址 macaddr - macaddr类型存储 MAC 地址,也就是以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: + macaddr类型存储 MAC 地址,例如以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: '08:00:2b:01:02:03' @@ -3330,15 +3375,15 @@ SELECT person.name, holidays.num_weeks FROM person, holidays <type>macaddr8</type> - macaddr8 (data type) + macaddr8(数据类型) - MAC地址(EUI-64格式) + MAC 地址(EUI-64 格式) macaddr - macaddr8类型以 EUI-64 格式存储 MAC 地址,例如常见的以太网卡硬件地址(尽管 MAC 地址也有其他用途)。该类型既接受 6 字节也接受 8 字节的 MAC 地址,并以 8 字节格式存储。给定的 6 字节格式 MAC 地址会以 8 字节格式存储,其中第 4 和第 5 字节分别设为 FF 和 FE。注意,IPv6 使用修改后的 EUI-64 格式,从 EUI-48 转换后应将第 7 位设为 1。提供的函数macaddr8_set7bit可完成这一更改。一般来说,接受由成对十六进制数字(在字节边界上)构成的输入,各对之间可以统一使用':''-''.'中的一种分隔。十六进制数字的数量必须为 16 个(8 字节)或 12 个(6 字节)。开头和结尾的空白会被忽略。以下是可以接受的输入格式示例: + macaddr8类型以 EUI-64 格式存储 MAC 地址,例如常见的以太网卡硬件地址(尽管 MAC 地址也有其他用途)。该类型既接受 6 字节也接受 8 字节的 MAC 地址,并以 8 字节格式存储。给定的 6 字节格式 MAC 地址会以 8 字节格式存储,其中第 4 和第 5 字节分别设为 FF 和 FE。注意,IPv6 使用修改后的 EUI-64 格式,从 EUI-48 转换后应将第 7 位设为 1。提供的函数macaddr8_set7bit可完成这一更改。一般来说,接受由成对十六进制数字(在字节边界上)构成的输入,各对之间可以统一使用':''-''.'中的一种分隔。十六进制数字的数量必须为 16 个(8 字节)或 12 个(6 字节)。开头和结尾的空白会被忽略。以下是可以接受的输入格式示例: '08:00:2b:01:02:03:04:05' '08-00-2b-01-02-03-04-05' '08002b:0102030405' @@ -3371,7 +3416,13 @@ SELECT macaddr8_set7bit('08:00:2b:01:02:03'); 数据类型 - 位串是由 1 和 0 组成的字符串,可用于存储或可视化位掩码。SQL 有两种位类型:bit(n)bit varying(n),其中n是正整数。 + + 位串是由 1 和 0 组成的字符串。它们可用于存储或展示位掩码。 + SQL 中有两种位类型: + bit(n) 和 + bit varying(n),其中 + n 是正整数。 + bit 类型的数据长度必须与 @@ -3421,31 +3472,31 @@ SELECT * FROM test; - 一个 bit 串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 + 一个位串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 开销,具体取决于串的长度。(不过,长值可能会被压缩或移到行外存储, 与 中对字符串的说明相同。) - 文本搜索类型 + 文本检索类型 - 全文搜索 + 全文检索 数据类型 - 文本搜索 + 文本检索 数据类型 - PostgreSQL 提供了两种专为支持全文搜索而 - 设计的数据类型。所谓全文搜索,是指在一组自然语言 + PostgreSQL 提供了两种专为支持全文检索而 + 设计的数据类型。所谓全文检索,是指在一组自然语言 文档中查找最匹配某个 查询的文档。tsvector 类型以 - 适合文本搜索的优化形式表示文档,tsquery 类型则表示 + 适合文本检索的优化形式表示文档,tsquery 类型则表示 文本查询。关于这一功能的详细解释见 ; 相关函数和操作符的概览见 @@ -3457,40 +3508,74 @@ SELECT * FROM test; tsvector(数据类型) - 一个tsvector值是由互不相同的词位组成的有序列表。词位是经过规范化以合并同一个词的不同变体的词(详情见)。排序和去重会在输入时自动完成,如本例所示: + + tsvector 值是一个排好序且互不重复的 + 词位(lexeme)列表,这些词已经过 + 正规化,以便把同一单词的不同变体合并起来 + (详见 )。排序和去重会在输入时自动 + 完成,如下例所示: + + SELECT 'a fat cat sat on a mat and ate a fat rat'::tsvector; tsvector ---------------------------------------------------- 'a' 'and' 'ate' 'cat' 'fat' 'mat' 'on' 'rat' 'sat' -要表示包含空白或标点符号的词位,请用引号括住它们: + + + 若要表示包含空白或标点的词位,请用引号将它们括起来: + + SELECT $$the lexeme ' ' contains spaces$$::tsvector; tsvector ------------------------------------------- ' ' 'contains' 'lexeme' 'spaces' 'the' -(本例和下一个示例使用美元符号引用的字符串字面量,以免在字面量中双写引号造成混淆。)内嵌的引号和反斜线必须双写: + + + (本例及下例使用美元引用的字符串常量,以避免在字符串内部必须 + 双写引号所造成的混淆。)嵌入的引号和反斜线必须双写: + + SELECT $$the lexeme 'Joe''s' contains a quote$$::tsvector; tsvector ------------------------------------------------ 'Joe''s' 'a' 'contains' 'lexeme' 'quote' 'the' -还可以给词位附加整数形式的位置,如下所示: + + + 还可以为词位附加整数形式的 位置: + + SELECT 'a:1 fat:2 cat:3 sat:4 on:5 a:6 mat:7 and:8 ate:9 a:10 fat:11 rat:12'::tsvector; tsvector ------------------------------------------------------------------------------- 'a':1,6,10 'and':8 'ate':9 'cat':3 'fat':2,11 'mat':7 'on':5 'rat':12 'sat':4 -位置通常表示原词在文档中的位置。位置信息可用于邻近度排序。位置值的范围为 1 到 16383;更大的数值会被静默设为 16383。同一词位的重复位置会被丢弃。 + - 具有位置的词位还可以标记一个权重,它可以是A, - BCD。 - D是默认值,因此不会在输出中显示: + 一个位置通常表示源词在文档中的位置。位置信息可用于 + 邻近度排序。位置值可以位于 1 到 16383 + 之间;更大的数字会被静默设为 16383。同一词位的重复位置会被丢弃。 + + + + 带有位置的词位还可以进一步附加一个 + 权重标签,其值可以是 + ABC + 或 DD 是默认值,因此在 + 输出中不会显示: + + SELECT 'a:1A fat:2B,4C cat:5D'::tsvector; tsvector ---------------------------- 'a':1A 'cat':5 'fat':2B,4C -权重通常用来反映文档结构,例如为标题中的词和正文中的词采用不同标记。文本搜索排名函数可以为不同的权重标记分配不同优先级。 + + + 权重通常用于反映文档结构,例如把标题中的词和正文中的词区分开来。 + 文本检索排序函数可以为不同的权重标记分配不同优先级。 + 必须认识到,tsvector 类型本身并不会执行任何词语 - 规范化;它假定输入的词已经按照应用需求完成规范化。例如: + 正规化;它假定输入的词已经按照应用需求完成正规化。例如: SELECT 'The Fat Rats'::tsvector; @@ -3499,9 +3584,9 @@ SELECT 'The Fat Rats'::tsvector; 'Fat' 'Rats' 'The' - 对于大多数英文全文搜索应用来说,上述词会被视为尚未规范化,但 + 对于大多数英文全文检索应用来说,上述词会被视为尚未正规化,但 tsvector 并不在意。原始文档文本通常应先经过 - to_tsvector,以按搜索需要对词语进行规范化: + to_tsvector,以按检索需要对词语进行正规化: SELECT to_tsvector('english', 'The Fat Rats'); @@ -3590,9 +3675,9 @@ SELECT 'super:*'::tsquery; 引号的使用规则与前面介绍 tsvector 时相同;同样, - 与 tsvector 一样,任何需要的词语规范化都必须在 + 与 tsvector 一样,任何需要的词语正规化都必须在 转换为 tsquery 类型之前完成。to_tsquery - 函数很适合用来实现这种规范化: + 函数很适合用来实现这种正规化: SELECT to_tsquery('Fat:ab & Cats'); @@ -3618,8 +3703,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); ---------------+------------ 'postgradu':1 | 'postgr':* - 因而它能够匹配其带前缀的后继形式 - postgraduate。 + 因而它能够匹配postgraduate 词干化后的形式。 @@ -3637,7 +3721,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); uuid 数据类型用于存储由 RFC 4122、 ISO/IEC 9834-8:2005 及相关标准定义的通用唯一标识符(UUID)。 - (有些系统把这种数据类型称为全局唯一标识符,或 GUID, + (有些系统把这种数据类型称为全局唯一标识符,或 GUID GUID。)这种标识符是一个 128 位的量,由某种算法生成,该算法被设计为使同一算法在已知宇宙中 被其他人生成出相同标识符的概率极低。因此,对于分布式系统而言, @@ -3654,7 +3738,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11 PostgreSQL 也接受其他输入形式:可以使用 - 大写字母、用花括号包围标准格式、忽略部分或全部连字符,或者在任意 + 大写字母、用花括号包围标准格式、省略部分或全部连字符,或者在任意 4 位分组后额外加上连字符。例如: A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11 @@ -3702,16 +3786,25 @@ a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11 创建XML值 - 要生成xml类型的值,可以对字符数据使用函数xmlparsexmlparse + + 要从字符数据生成 xml 类型的值,可以使用函数 + xmlparsexmlparse XMLPARSE ( { DOCUMENT | CONTENT } value) -例如: + 示例: +Manual...') XMLPARSE (CONTENT 'abcbarfoo') -]]>按照 SQL 标准,这是将字符串转换为 XML 值的唯一方式,不过也可以使用以下 PostgreSQL 特有语法: + 按照 SQL 标准,这是把字符串转换为 XML 值的 + 唯一方法;但 PostgreSQL 特有的下列语法: +bar' 'bar'::xml -]]> +]]> + 也可以使用。 + 即使输入值指定了文档类型声明(DTD),xml 类型也不会 @@ -3720,18 +3813,25 @@ xml 'bar' 来执行验证。 - 相反的操作是把xml值转换为字符串,这使用函数xmlserializexmlserialize + + 反向操作,也就是从 xml 生成字符串值,则使用函数 + xmlserializexmlserialize XMLSERIALIZE ( { DOCUMENT | CONTENT } value AS type ) - type可以是charactercharacter varyingtext(或这些类型之一的别名)。同样,按照 SQL 标准,这是在xml类型和字符类型之间转换的唯一方式,不过 PostgreSQL 也允许直接对值进行类型转换。 + type 可以是 + charactercharacter varying 或 + text(或它们的别名)。同样,根据 SQL 标准,这是在 + xml 与字符类型之间进行转换的唯一方式,但 + PostgreSQL 也允许你直接进行类型转换。 + 当字符串值在不经过 XMLPARSEXMLSERIALIZE 的情况下与 xml 类型互相转换时, 选择 DOCUMENT 还是 CONTENT - 由会话配置参数 XML option - XML option 决定,可以使用 + 由会话配置参数 XML 选项 + XML 选项 决定,可以使用 标准命令设置: SET XML OPTION { DOCUMENT | CONTENT }; @@ -3795,7 +3895,7 @@ SET xmloption TO { DOCUMENT | CONTENT }; xml 数据类型有些特殊,因为它不提供任何比较操作符。 这是因为对 XML 数据并不存在良定义且通用的比较算法。其结果是, - 你无法通过把某个 xml 值与搜索值比较来检索行。 + 你无法通过把某个 xml 列与搜索值比较来检索行。 因此,XML 值通常应伴随一个独立的键字段,例如 ID。另一种比较 XML 值的办法,是先把它们转换成字符串;但请注意,字符串比较对 XML 的比较需求通常帮助不大。 @@ -3803,14 +3903,14 @@ SET xmloption TO { DOCUMENT | CONTENT }; 由于 xml 数据类型没有可用的比较操作符,因此无法直接 - 在这种类型上创建索引。如果需要在 XML 中快速搜索,可行方案包括: + 在这种类型的列上创建索引。如果需要在 XML 中快速搜索,可行方案包括: 将表达式转换为字符串类型后为其建立索引,或者为某个 XPath 表达式 建立索引。当然,实际查询也必须相应调整为使用该被索引的表达式。 - PostgreSQL 的文本搜索功能也可用于加速 - XML 数据的全文搜索。不过,目前 PostgreSQL 发行版中仍缺少所需的 + PostgreSQL 的文本检索功能也可用于加速 + XML 数据的全文检索。不过,目前 PostgreSQL 发行版中仍缺少所需的 预处理支持。 @@ -3828,12 +3928,12 @@ SET xmloption TO { DOCUMENT | CONTENT }; 域类型 - domain + - data type - domain + 数据类型 + @@ -3845,13 +3945,13 @@ SET xmloption TO { DOCUMENT | CONTENT }; CREATE DOMAIN posint AS integer CHECK (VALUE > 0); CREATE TABLE mytable (id posint); -INSERT INTO mytable VALUES(1); -- works -INSERT INTO mytable VALUES(-1); -- fails +INSERT INTO mytable VALUES(1); -- 成功 +INSERT INTO mytable VALUES(-1); -- 失败 - 当底层类型的一个操作符或函数适用于一个域值时,域会被自动向下转换为底层类型。因此,mytable.id - 1的结果会被认为是类型integer而不是posint。我们可以写成(mytable.id - 1)::posint来把结果转换回posint,这会导致域的约束被重新检查。在这种情况下,如果该表达式被应用于一个值为1的id就会错误。把底层类型的值赋给域类型的一个字段或者变量不需要写显式的类型转换,但是域的约束将会被检查。 + 当底层类型的一个操作符或函数被应用于一个域值时,域会被自动向下转换为底层类型。因此,mytable.id - 1的结果会被认为是类型integer而不是posint。我们可以写成(mytable.id - 1)::posint来把结果转换回posint,这会导致域的约束被重新检查。在这种情况下,如果该表达式被应用于一个值为1的id就会报错。把底层类型的值赋给域类型的一个字段或者变量不需要写显式的类型转换,但是域的约束将会被检查。 @@ -3982,7 +4082,7 @@ SELECT * FROM pg_attribute regprocedure pg_proc - 函数与参数类型 + 带参数类型的函数 sum(int4) @@ -4031,21 +4131,21 @@ SELECT * FROM pg_attribute regconfig pg_ts_config - 文本搜索配置 + 文本检索配置 english regdictionary pg_ts_dict - 文本搜索字典 + 文本检索词典 simple
- 对于按名字空间分组的对象,所有 OID 别名类型都接受模式限定名称;如果不加限定就无法在当前搜索路径中找到对象,输出时也会显示模式限定名称。regprocregoper别名类型只接受唯一的(未重载的)输入名称,因此用途有限;对于大多数用途,regprocedureregoperator更合适。对于regoperator,通过将未使用的操作数写为NONE来标识一元操作符。 + 对于按命名空间分组的对象,所有 OID 别名类型都接受模式限定名称;如果不加限定就无法在当前搜索路径中找到对象,输出时也会显示模式限定名称。regprocregoper别名类型只接受唯一的(未重载的)输入名称,因此用途有限;对于大多数用途,regprocedureregoperator更合适。对于regoperator,通过将未使用的操作数写为NONE来标识一元操作符。 大多数 OID 别名类型还有一个附加特性,就是会创建依赖关系。如果 @@ -4053,9 +4153,8 @@ SELECT * FROM pg_attribute 它就会对被引用对象建立依赖。例如,如果某列的默认表达式是 nextval('my_seq'::regclass)PostgreSQL 就会知道该默认表达式依赖于 - 序列 my_seq,因此系统在删除该序列之前,必须先 - 移除该默认表达式。 - (regrole 是这一特性的例外:该类型的常量不允许出现在 + 序列 my_seq,因此系统不允许在尚未移除该默认表达式时删除序列。 + (regrole 是这一特性的唯一例外:该类型的常量不允许出现在 存储表达式中。) @@ -4217,7 +4316,7 @@ SELECT * FROM pg_attribute anyarray - 表示一个函数可以接受任意数组数据类型(参见 + 表示一个函数可以接受任意数组数据类型(参见)。 @@ -4272,12 +4371,12 @@ SELECT * FROM pg_attribute trigger - 触发器函数被声明为返回trigger. + 表示触发器函数被声明为返回 trigger event_trigger - 事件触发器函数被声明为返回event_trigger. + 表示事件触发器函数被声明为返回 event_trigger @@ -4292,7 +4391,7 @@ SELECT * FROM pg_attribute unknown - 标识一种尚未解析出的类型,例如未修饰的字符串字面值。 + 标识一种尚未解析出的类型,例如未修饰的字符串字面值的类型。 diff --git a/zh/12/dict-int.sgml b/zh/12/dict-int.sgml index 2988defd..c20e9906 100644 --- a/zh/12/dict-int.sgml +++ b/zh/12/dict-int.sgml @@ -1,16 +1,16 @@ - dict_int — 用于整数的示例全文搜索词典 + dict_int — 用于整数的示例全文检索词典 dict_int - dict_int是一个全文搜索附加词典模板的示例。 + dict_int是一个全文检索附加词典模板的示例。 引入这个示例词典是为了控制整数(有符号和无符号)的索引, - 使这类数字能够被索引,同时又避免唯一词的数量过度增长, + 使这类数字能够被索引,同时又避免不同词的数量过度增长, 因为那会严重影响搜索性能。 @@ -42,7 +42,7 @@ 用法 - 安装dict_int扩展后,会创建一个文本搜索模板 + 安装dict_int扩展后,会创建一个文本检索模板 intdict_template以及一个基于该模板、使用默认参数的词典 intdict。你可以修改这些参数,例如: @@ -65,7 +65,7 @@ mydb# select ts_lexize('intdict', '12345678');
但在实际使用中,通常需要像所述那样, - 将它包含到某个文本搜索配置中。可能类似如下: + 将它包含到某个文本检索配置中。可能类似如下: ALTER TEXT SEARCH CONFIGURATION english diff --git a/zh/12/func.sgml b/zh/12/func.sgml index 6683e9be..957a1a9d 100644 --- a/zh/12/func.sgml +++ b/zh/12/func.sgml @@ -7187,7 +7187,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 文本搜索函数和操作符 + 文本检索函数和操作符 全文检索 @@ -7195,7 +7195,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 文本搜索 + 文本检索 函数和操作符 @@ -7203,11 +7203,11 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple 以及 - 总结了为全文检索提供的函数和操作符。PostgreSQL的文本搜索功能的详细解释可参考。 + 总结了为全文检索提供的函数和操作符。PostgreSQL的文本检索功能的详细解释可参考
- 文本搜索操作符 + 文本检索操作符 @@ -7290,10 +7290,10 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple tsquery 包含操作符只考虑两个查询中列出的词位,忽略组合操作符。 - 除了表中列出的操作符,tsvectortsquery 类型还定义了普通的 B-树比较操作符(=< 等)。这些操作符对文本搜索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。 + 除了表中列出的操作符,tsvectortsquery 类型还定义了普通的 B-树比较操作符(=< 等)。这些操作符对文本检索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。
- 文本搜索函数 + 文本检索函数 @@ -7315,7 +7315,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple get_current_ts_config get_current_ts_config() regconfig - 获取默认的文本搜索配置 + 获取默认的文本检索配置 get_current_ts_config() english @@ -7524,17 +7524,17 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 所有接受一个可选的regconfig参数的文本搜索函数在省略该参数时,会使用由指定的配置。 + 所有接受一个可选的regconfig参数的文本检索函数在省略该参数时,会使用由指定的配置。 - 中的函数被单独列出,因为它们通常不被用于日常的文本搜索操作。 - 它们有助于开发和调试新的文本搜索配置。 + 中的函数被单独列出,因为它们通常不被用于日常的文本检索操作。 + 它们有助于开发和调试新的文本检索配置。
- 文本搜索调试函数 + 文本检索调试函数 diff --git a/zh/12/gist.sgml b/zh/12/gist.sgml index eb2c2180..d65755e3 100644 --- a/zh/12/gist.sgml +++ b/zh/12/gist.sgml @@ -690,7 +690,7 @@ my_fetch(PG_FUNCTION_ARGS) 示例 - PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本搜索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: + PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本检索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: diff --git a/zh/12/json.sgml b/zh/12/json.sgml index f970f7b4..7d0e86f7 100644 --- a/zh/12/json.sgml +++ b/zh/12/json.sgml @@ -38,7 +38,7 @@ - 由于 json 类型存储的是输入文本的精确副本,因此它会保留标记 + 由于 json 类型存储的是输入文本的精确副本,因此它会保留词元 之间在语义上无关紧要的空白,以及 JSON 对象内部键的顺序。此外,如果值中 的某个 JSON 对象包含同一个键多次,所有键/值对都会被保留下来(处理函数会 将最后一个值视为生效值)。相比之下,jsonb 不保留空白,不保留 @@ -61,7 +61,7 @@ 当把文本形式的 JSON 输入转换为 jsonb 时, - RFC 7159 描述的基本类型会有效映射到原生的 + RFC 7159 描述的基本类型实际上会映射到原生的 PostgreSQL 类型上,如 所示。因此,什么样的数据构成 有效的 jsonb 会有一些额外但较小的限制,这些限制不适用于 @@ -109,7 +109,7 @@ null - (无) + (无) SQL NULL 是不同的概念 @@ -124,18 +124,18 @@ 以下都是有效的 json(或 jsonb)表达式: --- Simple scalar/primitive value --- Primitive values can be numbers, quoted strings, true, false, or null +-- 简单的标量/基本值 +-- 基本值可以是数字、加引号的字符串、true、false 或 null SELECT '5'::json; --- Array of zero or more elements (elements need not be of same type) +-- 包含零个或多个元素的数组(元素不必是同一类型) SELECT '[1, 2, "foo", null]'::json; --- Object containing pairs of keys and values --- Note that object keys must always be quoted strings +-- 包含键值对的对象 +-- 注意,对象的键必须始终是加引号的字符串 SELECT '{"bar": "baz", "balance": 7.77, "active": false}'::json; --- Arrays and objects can be nested arbitrarily +-- 数组和对象可以任意嵌套 SELECT '{"foo": [true, "bar"], "tags": {"a": 1, "b": null}}'::json; @@ -191,8 +191,7 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 当 JSON 数据存储在表中时,它与任何其他数据类型一样,都要面对相同的并发控 制考量。虽然存储大型文档是可行的,但要记住,任何更新都会在整行上获取一个 行级锁。应考虑将 JSON 文档限制在可管理的大小,以减少更新事务之间的锁争用。 - 理想情况下,每个 JSON 文档都应表示一个原子数据项,按照业务规则,它不应被 - 合理地进一步拆分为更小且可独立修改的数据项。 + 理想情况下,每个 JSON 文档都应表示一个原子数据项,根据业务规则,无法再合理地将它细分为更小且可独立修改的数据项。 @@ -200,11 +199,11 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; <type>jsonb</type> 包含与存在 jsonb - containment + 包含 jsonb - existence + 存在 测试 包含jsonb 的一项重要能力。 @@ -213,33 +212,32 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 示例都返回真: --- Simple scalar/primitive values contain only the identical value: +-- 简单的标量/基本值只包含相同的值: SELECT '"foo"'::jsonb @> '"foo"'::jsonb; --- The array on the right side is contained within the one on the left: +-- 左侧数组包含右侧数组: SELECT '[1, 2, 3]'::jsonb @> '[1, 3]'::jsonb; --- Order of array elements is not significant, so this is also true: +-- 数组元素的顺序无关紧要,因此下面的结果也为真: SELECT '[1, 2, 3]'::jsonb @> '[3, 1]'::jsonb; --- Duplicate array elements don't matter either: +-- 重复的数组元素也无关紧要: SELECT '[1, 2, 3]'::jsonb @> '[1, 2, 2]'::jsonb; --- The object with a single pair on the right side is contained --- within the object on the left side: +-- 左侧对象包含右侧只有一个键值对的对象: SELECT '{"product": "PostgreSQL", "version": 9.4, "jsonb": true}'::jsonb @> '{"version": 9.4}'::jsonb; --- The array on the right side is not considered contained within the --- array on the left, even though a similar array is nested within it: -SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- yields false +-- 左侧数组被认为包含右侧数组, +-- 尽管其中嵌套了一个类似的数组: +SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- 结果为假 --- But with a layer of nesting, it is contained: +-- 但增加一层嵌套后,就构成了包含关系: SELECT '[1, 2, [1, 3]]'::jsonb @> '[[1, 3]]'::jsonb; --- Similarly, containment is not reported here: -SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- yields false +-- 同样,下面也不构成包含关系: +SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- 结果为假 --- A top-level key and an empty object is contained: +-- 包含由顶层键和空对象构成的对象: SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; @@ -254,11 +252,11 @@ SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; 对于结构必须匹配这一一般原则,有一个特殊例外:数组可以包含一个基本值: --- This array contains the primitive string value: +-- 这个数组包含该基本字符串值: SELECT '["foo", "bar"]'::jsonb @> '"bar"'::jsonb; --- This exception is not reciprocal -- non-containment is reported here: -SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false +-- 这个例外并不对称——下面的结果表示不包含: +SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- 结果为假 @@ -268,19 +266,19 @@ SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false 外,下面这些示例都返回真: --- String exists as array element: +-- 字符串作为数组元素存在: SELECT '["foo", "bar", "baz"]'::jsonb ? 'bar'; --- String exists as object key: +-- 字符串作为对象键存在: SELECT '{"foo": "bar"}'::jsonb ? 'foo'; --- Object values are not considered: -SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- yields false +-- 不考虑对象的值: +SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- 结果为假 --- As with containment, existence must match at the top level: -SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- yields false +-- 与包含关系一样,存在性必须在顶层匹配: +SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- 结果为假 --- A string is considered to exist if it matches a primitive JSON string: +-- 如果字符串与一个基本 JSON 字符串匹配,则认为它存在: SELECT '"foo"'::jsonb ? 'foo'; @@ -294,8 +292,7 @@ SELECT '"foo"'::jsonb ? 'foo'; 由于 JSON 包含是嵌套的,因此适当的查询可以跳过对子对象的显式选择。例如, 假设我们有一个 doc 列,其顶层是对象,而且大 多数对象都带有 tags 字段,该字段中包含子对象数组。下面 - 这个查询会找出那些包含同时带有 "term":"paris" 和 - "term":"food" 的子对象的项,同时忽略 + 这个查询会找出同时出现包含 "term":"paris" 的子对象和包含 "term":"food" 的子对象的项,同时忽略 tags 数组之外的任何此类键: SELECT doc->'site_name' FROM websites @@ -325,7 +322,7 @@ SELECT doc->'site_name' FROM websites <type>jsonb</type> 索引 jsonb - indexes on + 索引 @@ -333,9 +330,20 @@ SELECT doc->'site_name' FROM websites 或键/值对。提供了两种 GIN 操作符类,它们在性能和灵活性 之间提供不同的权衡。 - 对于jsonb,默认 GIN 操作符类支持使用键存在操作符??|?&、包含操作符@>以及jsonpath匹配操作符@?@@的查询。(这些操作符所实现语义的详情,参见。)使用此操作符类创建索引的示例如下: + + jsonb 的默认 GIN 操作符类支持使用键存在操作符 + ??|?&, + 包含操作符 @>,以及 jsonpath 匹配操作符 + @?@@ 的查询。(关于这些操作符 + 所实现语义的细节,见 。) + 使用此操作符类创建索引的例子如下: + CREATE INDEX idxgin ON api USING GIN (jdoc); -非默认的 GIN 操作符类jsonb_path_ops不支持键存在操作符,但支持@>@?@@。使用此操作符类创建索引的示例如下: + + 非默认的 GIN 操作符类 jsonb_path_ops 不支持键存在 + 操作符,但支持 @>@? 和 + @@。使用此操作符类创建索引的例子如下: + CREATE INDEX idxginp ON api USING GIN (jdoc jsonb_path_ops); @@ -364,14 +372,14 @@ CREATE INDEX idxginp ON api USING GIN (jdoc jsonb_path_ops); 名为 jdocjsonb 列里。 如果在该列上创建了 GIN 索引,那么下面这样的查询就可以利用这个索引: --- Find documents in which the key "company" has value "Magnafone" +-- 查找键 "company" 的值为 "Magnafone" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"company": "Magnafone"}'; 但是,类似下面这样的查询就无法使用该索引,因为虽然操作符 ? 可索引,但它并未直接应用到被索引的列 jdoc 上: --- Find documents in which the key "tags" contains key or array element "qui" +-- 查找键 "tags" 包含键或数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc -> 'tags' ? 'qui'; 不过,只要适当地使用表达式索引,上述查询也可以利用索引。如果经常查询 @@ -389,7 +397,7 @@ CREATE INDEX idxgintags ON api USING GIN ((jdoc -> 'tags')); 另一种查询方法是利用包含,例如: --- Find documents in which the key "tags" contains array element "qui" +-- 查找键 "tags" 包含数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qui"]}'; jdoc 列上的简单 GIN 索引可以支持这个查询。 @@ -399,14 +407,26 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu 对性的表达式索引通常会比简单索引更小,搜索起来也更快。 - GIN 索引还支持@?@@操作符,用于执行jsonpath匹配。示例如下: + + GIN 索引还支持 @?@@ 操作符, + 它们执行 jsonpath 匹配。示例如下: + SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @? '$.tags[*] ? (@ == "qui")'; SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; -对于这些操作符,GIN 索引会提取形如访问器链 - = 常量的子句,其来源是jsonpath模式,然后根据这些子句中的键和值执行索引搜索。访问器链可以包含., - [*][下标]访问器。jsonb_ops操作符类还支持.*.**访问器,但jsonb_path_ops操作符类不支持。 + + 对于这些操作符,GIN 索引会从 + jsonpath 模式中提取出形如 + accessors_chain = constant 的子句,并根据其中提到 + 的键和值进行索引搜索。访问器链可以包含 + .key、 + [*] 和 + [index] 访问器。 + jsonb_ops 操作符类还支持 .* 和 + .** 访问器,但 jsonb_path_ops + 操作符类不支持。 + 虽然 jsonb_path_ops 操作符类只支持带有 @@ -414,7 +434,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; @@ 操作符的查询,但相较于默认操作符类 jsonb_ops,它具有显著的性能优势。 jsonb_path_ops 索引通常比相同数据上的 - jsonb_ops 索引小得多,而且搜索条件也更具特异性,尤其是在 + jsonb_ops 索引小得多,而且搜索也更有针对性,尤其是在 查询中包含数据里频繁出现的键时。因此,搜索操作通常比使用默认操作符类时 性能更佳。 @@ -430,9 +450,9 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; 基本上,每个 jsonb_path_ops 索引项都是该值连同 - 通向该值的键一起计算出的哈希。例如,要索引 + 通向该值的键一起计算出的 hash。例如,要索引 {"foo": {"bar": "baz"}},会创建一个单独的索引项, - 其哈希值中同时纳入 foobar 和 + 其 hash 值中同时纳入 foobarbaz 这三者。因此,查找这一结构的包含查询会得到一次 非常精确的索引搜索;但完全没有办法据此找出 foo 是否 作为键出现。另一方面,jsonb_ops 索引会分别创建三个 @@ -452,11 +472,11 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; jsonb也支持btreehash索引。通常只有在需要检查完整 JSON 文档是否相等时,这些索引才有用。对于btree排序,jsonb数据的顺序很少值得关注,但为求完整,列出如下: -Object > Array > Boolean > Number > String > Null +对象 > 数组 > 布尔值 > 数字 > 字符串 > Null -Object with n pairs > object with n - 1 pairs +包含 n 个键值对的对象 > 包含 n - 1 个键值对的对象 -Array with n elements > array with n - 1 elements +包含 n 个元素的数组 > 包含 n - 1 个元素的数组 键值对数量相等的对象按以下顺序比较: 键-1, 值-1, 键-2 ... 注意,对象键按其存储顺序比较;尤其是,较短的键存储在较长的键之前,因此可能产生不直观的结果,例如: @@ -476,7 +496,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; PL/Perl 的扩展名为 jsonb_plperljsonb_plperlu。如果使用它们, - jsonb 值会按适当方式映射为 Perl 数组、哈希和标量。 + jsonb 值会按适当方式映射为 Perl 数组、hash 和标量。 @@ -593,7 +613,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; $varname - 命名变量。其值可以通过若干 JSON 处理函数的 vars 参数设置。详情参见 及其注释。 + 命名变量。其值可以通过若干 JSON 处理函数的 vars 参数设置。详情参见 及其附注。 @ @@ -679,7 +699,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; 可以用两种形式给出: indexstart_index to end_index。 - 第一种形式按索引返回单个数组元素。第二种形式按索引范围返回数组切片, + 第一种形式按下标返回单个数组元素。第二种形式按下标范围返回数组切片, 其中包括与给定 start_indexend_index 对应的元素。 diff --git a/zh/12/libpq.sgml b/zh/12/libpq.sgml index d21e6915..a0bf11c9 100644 --- a/zh/12/libpq.sgml +++ b/zh/12/libpq.sgml @@ -12,19 +12,19 @@ - libpq是应用程序员使用PostgreSQLC接口。libpq是一个库函数的集合,它们允许客户端程序传递查询给PostgreSQL后端服务器并且接收这些查询的结果。 + libpqPostgreSQLC应用程序编程接口。libpq是一组库函数,客户端程序可用它们向PostgreSQL后端服务器发送查询并接收查询结果。 - libpq也是很多其他PostgreSQL应用接口的底层引擎,包括为 C++、Perl、Python、Tcl 和 ECPG编写的接口。如果你使用那些包,某些方面的libpq行为将会对你很重要。特别是,描述了任何使用libpq的应用的用户可见的行为。 + libpq也是其他几个PostgreSQL应用程序接口的底层引擎,包括为 C++、Perl、Python、Tcl 和ECPG编写的接口。因此,对于这些包的用户,libpq行为的某些方面也很重要。特别是,描述了任何使用libpq的应用程序的用户都能观察到的行为。 - 在本章的末尾()包括了一些短程序来展示如何编写使用libpq的应用。在源代码发布的src/test/examples目录中还有一些完整的libpq应用的示例。 + 本章末尾()包含一些简短程序,展示如何编写使用libpq的程序。源代码发行包的src/test/examples目录中还提供了几个完整的libpq应用程序示例。 - 使用libpq的客户端程序必须包括头文件libpq-fe.hlibpq-fe.h并必须与libpq库链接在一起。 + 使用libpq的客户端程序必须包含头文件libpq-fe.hlibpq-fe.h,并且必须与libpq库链接。 @@ -39,7 +39,7 @@ - 在 Unix 上,复制一个拥有打开 libpq 连接的进程可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行代码是安全的。 + 在 Unix 上,对持有已打开 libpq 连接的进程执行 fork 操作可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行程序是安全的。 @@ -66,32 +66,32 @@ PGconn *PQconnectdbParams(const char * const *keywords, - 被传递的数组可以为空,这样就会使用所有默认参数。 - 也可以只包含一个或几个参数设置。他们在长度上必须匹配。 - 对于参数数组的处理将会停止于keywords数组中第一个NULL元素。 - 而且,如果与非-NULL keywords条目相关联的values条目为NULL或者空字符串,则忽略该项并继续处理下一对数组项。 + 传入的数组可以为空,以使用所有默认参数,也可以包含一个或多个参数设置。 + 两个数组的长度必须相同。处理会在 keywords 数组的第一个 NULL 元素处停止。 + 如果某个非 NULLkeywords 元素所对应的 + values 元素为 NULL 或空字符串,则忽略这一项,继续处理下一对数组元素。 - 当expand_dbname为非零时,会检查第一个dbname关键词的值以查看它是否为一个连接字符串。 - 如果是,它被扩展到从字符串中提取的单独的连接参数。 - 该值被认为是一个连接字符串,而不仅是一个数据库名称,如果它包含一个等号(=)或者它以URI模式标志符开头, - (有关连接字符串格式的更多详情可见。) - 只有dbname的第一次出现会按这种方式处理,任何后续dbname值会被当做一个普通数据库名处理。 + 当 expand_dbname 非零时,会检查第一个 dbname 关键词的值是否为 + 连接字符串。如果是,就将其展开为从该字符串中提取的各个连接参数。 + 如果该值包含等号(=),或以 URI 方案标识符开头,就会将其视为连接字符串,而非单纯的数据库名。 + (连接字符串格式的详细说明见。) + 只有第一次出现的 dbname 会按这种方式处理;后续的 dbname 参数都作为普通数据库名处理。 - 通常,参数数组从开头到结尾进行处理。 - 当关键词有重复时,使用最后一个值(不是 NULL 或空)。 - 此规则特别适用于连接字符串中的关键字与一个出现在keywords数组中的关键字冲突的情况。 - 因此,程序员可以决定数组条目是否能被覆盖或用连接字符串获取的值覆盖。 - 出现在扩展的dbname条目之前的数组条目可以被连接字符串的字段所覆盖,反之,这些字段被dbname之后出现的数组条目所覆盖。(但是,再有,只有在那些条目支持非空值时。) + 通常会从头到尾处理参数数组。如果某个关键词重复出现,则采用最后一个非 NULL 且非空的值。 + 此规则也适用于连接字符串中的关键词与 keywords 数组中的关键词冲突的情况。 + 因此,程序员可以决定数组元素是覆盖连接字符串中的值,还是被这些值覆盖。 + 出现在要展开的 dbname 元素之前的数组元素,可以被连接字符串中的字段覆盖; + 而这些字段又会被出现在 dbname 之后的数组元素覆盖(同样,只有这些元素提供非空值时才会覆盖)。 - 在处理完所有数组条目和任何扩展的连接字符串后,所有未设置的连接参数都将使用默认值填充。 - 如果一个未设置参数的相关环境变量(参见 )被设置了,它的值会被使用。 - 如果环境变量未被设置,则使用参数的内置默认值。 + 处理完所有数组元素及展开的连接字符串后,仍未设置的连接参数将填入默认值。 + 如果某个未设置参数对应的环境变量(见)已经设置,就使用该环境变量的值; + 否则使用该参数的内置默认值。 @@ -113,7 +113,7 @@ PGconn *PQconnectdb(const char *conninfo); - 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空格分隔的一个或多个参数设置,还可以包含一个URI。详见。 + 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空白分隔的一个或多个参数设置,还可以包含一个URI。详见 @@ -135,9 +135,13 @@ PGconn *PQsetdbLogin(const char *pghost, - 这是 PQconnectdb 的前身,使用固定的一组参数。除缺失参数始终采用默认值之外,功能相同。对于要使用默认值的任意固定参数,请传入 NULL 或空字符串。 + + 这是 PQconnectdb 的前身,使用固定的一组参数。除缺失参数始终采用默认值之外,功能相同。对于要使用默认值的任意固定参数,请传入 NULL 或空字符串。 + - 如果 dbName 包含 = 符号,或具有有效的连接 URI 前缀,就会将其当作 conninfo 字符串处理,方式与将其传给 PQconnectdb 完全相同,然后按照 PQconnectdbParams 的规则应用其余参数。 + + 如果 dbName 包含 = 符号,或具有有效的连接 URI 前缀,就会将其当作 conninfo 字符串处理,方式与将其传给 PQconnectdb 完全相同,然后按照 PQconnectdbParams 的规则应用其余参数。 + @@ -167,7 +171,7 @@ PGconn *PQsetdb(char *pghost, PQconnectPollPQconnectPoll - nonblocking connection + 非阻塞连接 以非阻塞的方式建立一个到数据库服务器的连接。 @@ -200,7 +204,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 如果你调用PQtrace,确保你追踪的该流对象不会阻塞。 + 如果你调用PQtrace,确保接收追踪输出的流对象不会阻塞。 @@ -213,7 +217,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 要开始无阻塞的连接请求,可调用PQconnectStart或者PQconnectStartParams。如果结果为空,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 + 要开始非阻塞连接请求,可调用PQconnectStart或者PQconnectStartParams。如果结果为空指针,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 @@ -312,11 +316,11 @@ switch(PQstatus(conn)) - 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。否则,PQconnectStart后面跟着PQconnectPoll循环等效于PQconnectdb。 + 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。除此之外,PQconnectStart后面跟着PQconnectPoll循环等效于PQconnectdb - 注意当PQconnectStartPQconnectStartParams返回一个非空的指针时,你必须在用完它之后调用PQfinish来处理那些结构体和任何相关的内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 + 注意当PQconnectStartPQconnectStartParams返回一个非空的指针时,你必须在用完它之后调用PQfinish来释放该结构体及其关联的所有内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 @@ -332,21 +336,21 @@ PQconninfoOption *PQconndefaults(void); typedef struct { char *keyword; /* 该选项的关键词 */ - char *envvar; /* 依赖的环境变量名 */ - char *compiled; /* 依赖的内置默认值 */ + char *envvar; /* 后备环境变量名 */ + char *compiled; /* 编译时设置的后备默认值 */ char *val; /* 选项的当前值,或者 NULL */ - char *label; /* 连接对话框中域的标签 */ - char *dispchar; /* 指示如何在一个连接对话框中显示这个域。值是: + char *label; /* 连接对话框中字段的标签 */ + char *dispchar; /* 指示如何在连接对话框中显示此字段。可取值: "" 显示输入的值 - "*" 密码域 - 隐藏值 + "*" 密码字段 - 隐藏值 "D" 调试选项 - 默认不显示 */ - int dispsize; /* 用于对话框的以字符计的域尺寸 */ + int dispsize; /* 对话框中的字段宽度,以字符计 */ } PQconninfoOption; - 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的PQconnectdb选项和它们的当前缺省值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回该空指针。注意当前缺省值(val域)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 + 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的PQconnectdb选项和它们的当前默认值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回空指针。注意当前默认值(val字段)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 @@ -366,7 +370,9 @@ PQconninfoOption *PQconninfo(PGconn *conn); - 返回一个连接选项数组。可以用它确定所有可能的 PQconnectdb 选项,以及实际用于连接服务器的值。返回值指向一个 PQconninfoOption 结构体数组,该数组以 keyword 指针为空的条目结束。上文针对 PQconndefaults 的所有注意事项,也适用于 PQconninfo 的结果。 + + 返回一个连接选项数组。可以用它确定所有可能的 PQconnectdb 选项,以及实际用于连接服务器的值。返回值指向一个 PQconninfoOption 结构体数组,该数组以 keyword 指针为空的条目结束。上文针对 PQconndefaults 的所有注意事项,也适用于 PQconninfo 的结果。 + @@ -392,7 +398,9 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); - 如果errmsg不是NULL,那么成功时*errmsg会被设置为NULL, 否则设置为被malloc过的错误字符串以说明该问题(也可以将*errmsg设置为NULL并且函数返回NULL,这表示一种内存耗尽的情况)。 + 如果 errmsg 不是 NULL,则成功时将 *errmsg 设为 NULL; + 失败时将其设为由 malloc 分配的、用于说明问题的错误字符串。 + (也可能出现 *errmsg 被设为 NULL,同时函数返回 NULL 的情况;这表示内存不足。) @@ -422,7 +430,7 @@ void PQfinish(PGconn *conn); PQresetPQreset - 重置与服务器的通讯通道。 + 重置与服务器的通信通道。 void PQreset(PGconn *conn); @@ -440,7 +448,7 @@ void PQreset(PGconn *conn); PQresetPollPQresetPoll - 以非阻塞方式重置与服务器的通讯通道。 + 以非阻塞方式重置与服务器的通信通道。 int PQresetStart(PGconn *conn); @@ -451,7 +459,9 @@ PostgresPollingStatusType PQresetPoll(PGconn *conn); 这些函数会关闭与服务器的连接,并尝试使用与之前完全相同的参数建立新连接。如果原本可用的连接丢失,这可以用于错误恢复。它们与上文的 PQreset 不同之处在于采用非阻塞方式。它们受到与 PQconnectStartParamsPQconnectStartPQconnectPoll 相同的限制。 - 要开始重置连接,请调用 PQresetStart。如果它返回 0,则重置失败。如果返回 1,则使用 PQresetPoll 轮询重置过程,其方式与使用 PQconnectPoll 创建连接完全相同。 + + 要开始重置连接,请调用 PQresetStart。如果返回 0,表示重置失败。如果返回 1,则使用 PQresetPoll 轮询重置过程,方式与使用 PQconnectPoll 建立连接完全相同。 + @@ -536,19 +546,19 @@ PGPing PQping(const char *conninfo); 几个libpq函数解析用户指定的字符串以获取连接参数。 - 这些字符串有两种被接受的格式:普通的关键字/值字符串和URI。URI通常遵循 + 这些字符串有两种被接受的格式:普通的关键词/值字符串和URI。URI通常遵循 RFC - 3986,除了允许多主机连接字符串,如下面进一步描述的那样。 + 3986,但也允许使用多主机连接字符串,详见下文。 关键词/值连接字符串 - 在关键词/值格式中,每一个参数设置的形式都是keyword = value,在设置之间有空白。 - 设置的等号周围的空白是可选的。 - 要写一个空值或一个包含空白的值,将它用单引号包围,例如keyword = 'a value'。 - 值里面的单引号和反斜线必须用一个反斜线转义,即\'\\。 + 在关键词/值格式中,每一个参数设置的形式都是关键词 = ,设置之间以空格分隔。 + 设置的等号周围的空格是可选的。 + 要写一个空值或一个包含空格的值,将它用单引号包围,例如keyword = 'a value'。 + 值里面的单引号和反斜杠必须用一个反斜杠转义,即\'\\ @@ -571,22 +581,22 @@ host=localhost port=5432 dbname=mydb connect_timeout=10 postgresql://userspec@hostspec/dbname?paramspec -where userspec is: +其中 userspec 为: user:password -and hostspec is: +hostspec 为: host:port,... -and paramspec is: +paramspec 为: name=value&... - URI模式标志符可以是postgresql://postgres://。 + URI方案标识符可以是postgresql://postgres://。 每一个剩下的URI部分都是可选的。 下列示例展示了合法的URI语法: @@ -603,7 +613,7 @@ postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application postgresql:///mydb?host=localhost&port=5433 - 全部的命名参数必须匹配中列出的关键词,除了与JDBC连接URI兼容之外,ssl=true的实例转换到sslmode=require。 + 所有命名参数都必须与中列出的关键词匹配;唯一的例外是,为兼容 JDBC 连接 URI,会将 ssl=true 转换为 sslmode=require 可以在 URI 的任意部分使用百分号编码来包含具有特殊含义的符号,例如将 = 替换为 %3D @@ -619,7 +629,7 @@ postgresql://[2001:db8::1234]/database 主机组件会被按照参数对应的描述来解释。 特别地,如果主机部分是空或看起来像一个绝对路径名称,将使用一个 Unix 域套接字连接,否则将启动一个 TCP/IP 连接。 不过要注意,斜线是 URI 层次部分中的一个保留字符。 - 因此,要指定一个非标准的 Unix 域套接字目录,要么忽略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: + 因此,要指定一个非标准的 Unix 域套接字目录,要么省略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: postgresql:///dbname?host=/var/lib/postgresql postgresql://%2Fvar%2Flib%2Fpostgresql/dbname @@ -629,7 +639,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以在一个URI中指定多个主机,每一个都有一个可选的端口。 一个形式为postgresql://host1:port1,host2:port2,host3:port3/的URI等效于host=host1,host2,host3 port=port1,port2,port3形式的连接字符串。 - 如下所述,每一个主机都将被尝试,直到成功地建立一个连接。 + 如下所述,每一个主机都将被依次尝试,直到成功地建立一个连接。 @@ -639,7 +649,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以指定多个要连接的主机,这样它们会按给定的顺序被尝试。 - 在键/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 + 在关键词/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 在指定的每一个选项中都必须给出相同数量的元素,这样第一个hostaddr对应于第一个主机名,第二个hostaddr对应于第二个主机名,以此类推。 不过,如果仅指定一个port,它将被应用于所有的主机。 @@ -649,11 +659,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 不管是哪一种格式,单一的主机名可以被翻译成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 + 不管是哪一种格式,单一的主机名可以被解析成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 - 当多个主机被指定时或者单个主机名被翻译成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。 + 当多个主机被指定时或者单个主机名被解析成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。 @@ -687,7 +697,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 如果指定了host而没有指定hostaddr,则会发生主机名查找。 (当使用PQconnectPoll时,查找发生在PQconnectPoll首次考虑此主机名时, - 并且可能导致PQconnectPoll阻塞一段时间。) + 并且可能导致PQconnectPoll阻塞相当长的时间。) @@ -699,11 +709,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果同时指定了hosthostaddr, - 则hostaddr的值给出服务器的网络地址。 - 除非认证方法需要,否则host的值将被忽略, - 在这种情况下,它将用作主机名。 - + 如果同时指定了 hosthostaddr,则 hostaddr 的值给出服务器的网络地址。只有认证方法需要主机名时,才会将 host 的值用作主机名;否则忽略该值。 + 注意,以下情况很可能导致认证失败:host不是位于网络地址hostaddr的服务器名称。另外,同时指定hosthostaddr时,将使用host来标识密码文件中的连接(参见)。 @@ -747,8 +754,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - PostgreSQL用户连接的用户名。 - 默认为运行应用程序的操作系统用户名相同。 + 建立连接所用的 PostgreSQL 用户名。默认与运行应用程序的操作系统用户名相同。 @@ -758,7 +764,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果服务器要求密码认证,则使用密码。 + 服务器要求密码认证时所使用的密码。 @@ -828,9 +834,9 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 指定配置参数的回退值。 + 指定配置参数的后备值。 如果没有通过连接参数或PGAPPNAME环境变量为application_name指定值, - 则将使用此值。在通用实用程序中指定回退名称很有用,该程序希望设置默认应用程序名称, + 则将使用此值。在通用实用程序中指定后备名称很有用,该程序希望设置默认应用程序名称, 但允许用户覆盖它。 @@ -841,9 +847,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制是否使用客户端TCP保持活动。默认值为1,表示开启,但如果不想要保持活动,可以将其更改为0,表示关闭。 - 对于通过Unix域套接字进行的连接,此参数将被忽略。 - + 控制是否使用客户端 TCP keepalive。默认值为 1,表示开启;如果不需要 keepalive,可以将其设为 0,表示关闭。对于通过 Unix 域套接字建立的连接,此参数会被忽略。 + @@ -852,11 +857,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在多少秒的不活动后,TCP应向服务器发送保持活动消息。值为零使用系统默认值。 - 对通过Unix域套接字进行的连接或禁用保持活动的连接,此参数将被忽略。 - 仅在支持TCP_KEEPIDLE或等效套接字选项的系统以及Windows上支持; - 在其他系统上,它没有任何效果。 - + 控制在多久没有活动后,TCP 应向服务器发送 keepalive 消息,以秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPIDLE 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -865,11 +867,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在服务器未确认的情况下重新传输TCP保持活动消息的秒数。值为零时使用系统默认值。 - 此参数在通过Unix域套接字进行连接或禁用保持活动时将被忽略。 - 仅在支持TCP_KEEPINTVL或等效套接字选项的系统和Windows上支持; - 在其他系统上,此参数无效。 - + 控制未被服务器确认收到的 TCP keepalive 消息在多少秒后应被重传。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPINTVL 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -878,11 +877,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在客户端与服务器之间连接被视为断开之前可以丢失的TCP keepalive数量。 - 值为零时使用系统默认值。对通过Unix域套接字建立的连接或禁用keepalives的连接,此参数将被忽略。 - 仅在支持TCP_KEEPCNT或等效套接字选项的系统上受支持; - 在其他系统上,此参数无效。 - + 控制在客户端与服务器之间的连接被视为中断之前,可以丢失多少个 TCP keepalive 消息。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPCNT 或等效套接字选项的系统上受支持;在其他系统上无效。 + @@ -891,10 +887,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在连接在强制关闭之前,传输数据可以保持未被确认的毫秒数。 - 值为零时使用系统默认值。此参数对通过Unix域套接字进行的连接无效。 - 仅在支持TCP_USER_TIMEOUT的系统上受支持;在其他系统上,它没有效果。 - + 控制已发送的数据在连接被强制关闭之前最多可以保持未确认状态多长时间,以毫秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,此参数会被忽略。此参数仅在支持 TCP_USER_TIMEOUT 的系统上受支持;在其他系统上无效。 + @@ -964,25 +958,25 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个选项确定是否以及如何优先与服务器协商安全的GSS TCP/IP连接。有三种模式: + 这个选项确定是否以及以何种优先级与服务器协商安全的GSS TCP/IP连接。有三种模式: disable - 仅尝试非GSSAPI加密连接 + 仅尝试未经GSSAPI加密的连接 - prefer (默认) + prefer (默认) 如果存在GSSAPI凭据(即在凭据缓存中),首先尝试 GSSAPI加密连接;如果失败或没有凭据,则尝试 - 非GSSAPI加密连接。这是在编译PostgreSQL时使用GSSAPI支持时的默认设置。 + 未经GSSAPI加密的连接。这是在编译PostgreSQL时使用GSSAPI支持时的默认设置。 @@ -1001,7 +995,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname gssencmode在Unix域套接字通信中被忽略。如果PostgreSQL没有编译GSSAPI支持, 使用require选项将导致错误,而prefer将被接受,但libpq实际上不会尝试 - 进行GSSAPI加密连接。GSSAPI与libpq + 进行GSSAPI加密连接。GSSAPI在 libpq 中 @@ -1032,7 +1026,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - prefer (默认) + prefer (默认) 首先尝试SSL连接;如果失败,则尝试非SSL连接 @@ -1072,16 +1066,18 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - sslmode被忽略用于Unix域套接字通信。 - 如果PostgreSQL没有SSL支持编译, + 在 Unix 域套接字通信中,sslmode 会被忽略。 + 如果PostgreSQL编译时未启用 SSL 支持, 使用选项requireverify-caverify-full会导致错误,而选项allowprefer 将被接受,但libpq实际上不会尝试建立SSL 连接。SSL使用libpq的SSL + sortas="libpq">在 libpq 中 - 注意,如果可以使用 GSSAPI 加密,就会优先使用它而不是 SSL 加密,无论 sslmode 的值是什么。在具有可用 GSSAPI 基础设施(例如 Kerberos 服务器)的环境中,要强制使用 SSL 加密,还应将 gssencmode 设为 disable + + 注意,如果可以使用 GSSAPI 加密,就会优先使用它而不是 SSL 加密,无论 sslmode 的值是什么。在具有可用 GSSAPI 基础设施(例如 Kerberos 服务器)的环境中,要强制使用 SSL 加密,还应将 gssencmode 设为 disable。 + @@ -1090,15 +1086,15 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 此选项已被sslmode设置所取代。 - + 此选项已弃用,请改用 sslmode 设置。 + 如果设置为1,则需要与服务器建立SSL连接(这相当于sslmode require)。libpq将拒绝连接,如果服务器不接受 SSL连接。如果设置为0(默认值), libpq将与服务器协商连接类型(相当于sslmode - prefer)。此选项仅在PostgreSQL编译时启用SSL支持。 + prefer)。此选项仅在 PostgreSQL 编译时启用了 SSL 支持的情况下可用。 @@ -1114,7 +1110,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname SSL 压缩现在被认为不安全,已不再建议使用。OpenSSL 1.1.0 默认禁用压缩,许多操作系统发行版也在更早的版本中禁用了压缩,因此,如果服务器不接受压缩,将此参数设为 on 不会产生效果。另一方面,OpenSSL 1.0.0 之前的版本不支持禁用压缩,因此这些版本会忽略此参数,是否使用压缩取决于服务器。 - 如果安全性不是主要考虑因素,压缩可以提高吞吐量,如果网络是瓶颈的话。如果CPU性能是限制因素,禁用压缩可以提高响应时间和吞吐量。 + 如果安全性不是主要考虑因素,压缩可以提高吞吐量,如果网络是瓶颈的话。如果CPU性能是限制因素,禁用压缩可以缩短响应时间并提高吞吐量。 @@ -1138,7 +1134,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 这个参数指定了用于客户端证书的密钥的位置。它可以指定一个文件名,该文件名将被用来替代默认的 ~/.postgresql/postgresql.key,或者它可以指定一个从外部引擎 - (引擎是OpenSSL可加载模块)获取的密钥。外部引擎规范应该包括一个由冒号分隔的引擎名称和 + (引擎是OpenSSL可加载模块)获取的密钥。外部引擎的指定形式应包含一个由冒号分隔的引擎名称和 一个引擎特定的密钥标识符。如果没有进行SSL连接,则此参数将被忽略。 @@ -1184,13 +1180,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 用于使用GSSAPI进行认证时要使用的Kerberos服务名称。 + 使用 GSSAPI 认证时所用的 Kerberos 服务名。 这必须与服务器配置中指定的Kerberos认证服务名称匹配,才能成功进行认证。 (另请参见。) 默认值通常为postgres, - 但在构建PostgreSQL时可以通过 - 选项进行更改 - configure。 + 但在构建 PostgreSQL 时,可以通过 configure 选项更改。 在大多数环境中,通常不需要更改此参数。 一些Kerberos实现可能需要不同的服务名称, 例如Microsoft Active Directory需要服务名称为大写(POSTGRES)。 @@ -1236,20 +1230,21 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 连接状态函数 - 这些函数可以被用来询问一个已有数据库连接对象的状态。 + 这些函数可用于查询现有数据库连接对象的状态。 - libpq-fe.h - libpq-int.h - libpq应用程序员应该小心地维护PGconn抽象。使用下面描述的访问函数来理解PGconn的内容。我们不推荐使用libpq-int.h引用内部的PGconn域,因为它们可能在未来改变。 - + libpq-fe.h + libpq-int.h + 编写 libpq 应用程序时,应注意维护 PGconn 的抽象。请使用下述访问函数获取 PGconn 的内容。不建议通过 libpq-int.h 引用 PGconn 的内部字段,因为这些字段将来可能改变。 + - 以下函数返回建立连接时确定的参数值。这些值在连接存续期间保持不变。如果使用多主机连接字符串,以下函数的值:PQhost, - PQportPQpass可能会在使用同一个PGconn对象建立新连接时改变。其他值在以下对象的整个生命周期内保持不变:PGconn对象。 + + 以下函数返回建立连接时确定的参数值。这些值在连接存续期间保持不变。如果使用多主机连接字符串,并使用同一个 PGconn 对象建立新连接,则 PQhostPQportPQpass 的返回值可能改变。其他值在 PGconn 对象的整个生命周期内保持不变。 + PQdb PQdb @@ -1296,7 +1291,7 @@ char *PQpass(const PGconn *conn); - 返回活跃连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 + 返回活动连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 char *PQhost(const PGconn *conn); @@ -1308,7 +1303,7 @@ char *PQhost(const PGconn *conn); - 如果conn参数是NULL,则PQhost返回NULL。否则,如果在生成主机信息时发生错误(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 PQhost 返回 NULL。否则,如果在生成主机信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1330,8 +1325,7 @@ char *PQhostaddr(const PGconn *conn); - 如果conn 参数为 NULLPQhostaddr 返回 NULL 。 - 否则,如果生成主机信息时出现错误(如果连接尚未完全建立或出现错误),则返回一个空字符串。 + 如果 conn 参数为 NULL,则 PQhostaddr 返回 NULL。否则,如果在生成主机信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1341,7 +1335,7 @@ char *PQhostaddr(const PGconn *conn); - 返回活跃连接的端口。 + 返回活动连接的端口。 char *PQport(const PGconn *conn); @@ -1353,7 +1347,7 @@ char *PQport(const PGconn *conn); - 如果conn参数是NULL,则PQport返回NULL。否则,如果在生成端口信息时发生错误(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 PQport 返回 NULL。否则,如果在生成端口信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1366,7 +1360,9 @@ char *PQport(const PGconn *conn); PQtty PQtty - 返回连接的调试TTY。(此设置已过时,因为服务器不再理会TTY设置,但为保持向后兼容,仍保留了此函数。) + + 返回该连接用于调试的TTY。(此功能已过时,因为服务器不再使用TTY设置,但为保持向后兼容仍保留此函数。) + char *PQtty(const PGconn *conn); @@ -1378,7 +1374,7 @@ char *PQtty(const PGconn *conn); - 返回被传递给连接请求的命令行选项。 + 返回连接请求中传递的命令行选项。 char *PQoptions(const PGconn *conn); @@ -1386,9 +1382,11 @@ char *PQoptions(const PGconn *conn); - + - 以下函数返回的状态数据可能在执行操作时发生变化,这些操作针对PGconn对象。 + + 以下函数返回的状态数据,可能随着对 PGconn 对象执行操作而改变。 + PQstatus PQstatus @@ -1424,7 +1422,7 @@ ConnStatusType PQstatus(const PGconn *conn); PGTransactionStatusType PQtransactionStatus(const PGconn *conn); - 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个合法的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接损坏,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE。 + 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个有效的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接异常,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE @@ -1466,9 +1464,12 @@ const char *PQparameterStatus(const PGconn *conn, const char *paramName); PQprotocolVersion PQprotocolVersion - 查询正在使用的前端/后端协议。 + + 查询正在使用的前端/后端协议。 + int PQprotocolVersion(const PGconn *conn); -应用程序可以使用此函数判断是否支持某些特性。目前可能的值为 2(协议 2.0)、3(协议 3.0)或零(连接无效)。连接启动完成后,协议版本不会改变,但理论上可能在重置连接时改变。与PostgreSQL7.4 或更新版本的服务器通信时,通常使用协议 3.0;7.4 之前的服务器仅支持协议 2.0。(协议 1.0 已过时,且不被以下库支持:libpq。) + +应用程序可以使用此函数判断是否支持某些特性。目前,可能的值为 2(协议 2.0)、3(协议 3.0)或零(连接异常)。连接启动完成后,协议版本不会改变,但理论上可能在连接重置期间改变。通常,与 PostgreSQL 7.4 或更高版本的服务器通信时使用协议 3.0;7.4 之前的服务器仅支持协议 2.0。(协议 1.0 已过时,libpq 不支持它。) @@ -1489,11 +1490,11 @@ int PQserverVersion(const PGconn *conn); - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,PQserverVersion为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 + 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,PQserverVersion为每个部分使用两位数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - 因此,出于判断特性兼容性的目的,应用应该将PQserverVersion的结果除以100而不是10000来判断逻辑的主版本号。在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 + 因此,出于判断特性兼容性的目的,应用应该将PQserverVersion的结果除以100而不是10000来判断逻辑的主版本号。在所有主版本系列中,各次版本(缺陷修复版本)之间只有最后两位数字不同。 @@ -1512,9 +1513,7 @@ char *PQerrorMessage(const PGconn *conn); - 几乎所有的libpq函数在失败时都会为PQerrorMessage设置一个消息。 - 注意按照libpq习惯,一个非空PQerrorMessage结果可能由多行构成,并且将包括一个尾部新行。 - 调用者不应该直接释放结果。当相关的PGconn句柄被传递给PQfinish时,它将被释放。在PGconn结构体上的多个操作之间,不能指望结果字符串会保持不变。 + 几乎所有 libpq 函数在失败时都会设置一条供 PQerrorMessage 返回的消息。注意,按照 libpq 的约定,非空的 PQerrorMessage 结果可能包含多行,并以换行符结尾。调用者不应直接释放该结果;当关联的 PGconn 句柄被传给 PQfinish 时,结果会被释放。不能假定在对 PGconn 结构体执行其他操作后,结果字符串仍保持不变。 @@ -1523,7 +1522,7 @@ char *PQerrorMessage(const PGconn *conn); PQsocketPQsocket - 获得到服务器连接套接字的文件描述符号。一个合法的描述符将会大于等于零。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 + 获取与服务器相连的套接字的文件描述符编号。有效描述符大于或等于 0。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 int PQsocket(const PGconn *conn); @@ -1540,7 +1539,7 @@ int PQsocket(const PGconn *conn); 返回处理这个连接的后端进程的进程ID(PID)。 PID 确定服务器进程的 PID - in libpq + 在 libpq 中 @@ -1549,7 +1548,7 @@ int PQbackendPID(const PGconn *conn); - 后端PID有助于调试目的并且可用于与NOTIFY消息(它包括发出提示的后端进程的PID)进行比较。注意PID属于一个在数据库服务器主机上执行的进程,而不是本地主机进程! + 后端 PID 可用于调试,也可与 NOTIFY 消息进行比较(消息包含发出通知的后端进程的 PID)。注意,该 PID 属于在数据库服务器主机上运行的进程,而非本地主机上的进程! @@ -1588,15 +1587,17 @@ int PQconnectionUsedPassword(const PGconn *conn); - + - 以下函数返回与 SSL 相关的信息。这些信息通常在连接建立后不会改变。 + + 以下函数返回与 SSL 相关的信息。这些信息通常在连接建立后不会改变。 + PQsslInUsePQsslInUse - 返回true(1)如果连接使用SSL,返回false(0)如果不使用。 + 如果连接使用 SSL,则返回真(1);否则返回假(0)。 int PQsslInUse(const PGconn *conn); @@ -1615,10 +1616,10 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); - 可用属性列表因使用的SSL库和连接类型而异。如果连接不使用SSL或指定的属性名称对于所使用的库未定义,则返回NULL。 + 可用属性列表因所使用的 SSL 库和连接类型而异。如果某个属性不可用,则返回 NULL。 - 通常可以取得以下属性: + 通常可以获取以下属性: library @@ -1683,12 +1684,14 @@ const char * const * PQsslAttributeNames(const PGconn *conn); PQsslStructPQsslStruct - 返回一个指向描述连接的SSL实现特定对象的指针。如果连接未加密或SSL实现不提供连接的请求对象类型,则返回NULL。 + 返回指向描述此连接的对象的指针,该对象的类型由 SSL 实现决定。 void *PQsslStruct(const PGconn *conn, const char *struct_name); - 可用的结构体取决于所使用的 SSL 实现。对于 OpenSSL,有一个名为 "OpenSSL" 的结构体,取得它时会返回指向 OpenSSLSSL结构体的指针。可以使用类似以下的代码来调用此函数: + 可用的结构体取决于所使用的 SSL 实现。对于 OpenSSL,可以通过名称 "OpenSSL" 获取一个结构体,函数返回指向 OpenSSL 的 SSL 结构体的指针。可以使用如下代码调用此函数: + #include @@ -1730,7 +1733,7 @@ void *PQgetssl(const PGconn *conn); - + @@ -1738,7 +1741,7 @@ void *PQgetssl(const PGconn *conn); 命令执行函数 - 一旦到一个数据库服务器的连接被成功建立,这里描述的函数可以被用来执行 SQL 查询和命令。 + 与数据库服务器的连接成功建立后,此处描述的函数用于执行 SQL 查询和命令。 @@ -1759,11 +1762,8 @@ PGresult *PQexec(PGconn *conn, const char *command); - 返回一个PGresult指针或者可能是一个空指针。 - 除了内存不足的情况或者由于严重错误无法将命令发送给服务器之外,一般都会返回一个非空指针。 - PQresultStatus函数应当被调用来检查返回值是否代表错误(包括空指针的值,它会返回PGRES_FATAL_ERROR)。 - 用PQerrorMessage可得到关于那些错误的详细信息。 - + 返回一个 PGresult 指针,也可能返回空指针。除内存不足或无法向服务器发送命令等严重错误外,通常都会返回非空指针。应调用 PQresultStatus 函数检查返回值是否表示错误(也应检查空指针,此时该函数返回 PGRES_FATAL_ERROR)。使用 PQerrorMessage 获取此类错误的更多信息。 + 命令字符串可以包含多个 SQL 命令(以分号分隔)。在一次PQexec调用中发送的多个查询会在同一个事务中处理,除非查询字符串中显式包含BEGIN/COMMIT命令,将其划分为多个事务。(有关服务器如何处理多查询字符串的详细信息,请参见。)但要注意,返回的PGresult结构体只描述该字符串中最后执行的命令的结果。如果其中一条命令失败,就会在此处停止处理该字符串,返回的PGresult则描述该错误。 @@ -1836,8 +1836,8 @@ PGresult *PQexecParams(PGconn *conn, paramValues[] - 指定参数的实际值。这个数组中的一个空指针表示对应的参数为空,否则该指针指向一个以零终止的文本字符串(用于文本格式)或者以服务器所期待格式的二进制数据(用于二进制格式)。 - + 指定参数的实际值。数组中的空指针表示对应参数为 null;否则,指针指向以零结尾的文本字符串(文本格式),或采用服务器所要求格式的二进制数据(二进制格式)。 + @@ -1845,8 +1845,8 @@ PGresult *PQexecParams(PGconn *conn, paramLengths[] - 指定二进制格式参数的实际数据长度。它对空参数和文本格式参数被忽略。当没有二进制参数时,该数组指针可以为空。 - + 指定二进制格式参数的实际数据长度。对于 null 参数和文本格式参数,该值会被忽略。如果没有二进制参数,数组指针可以为空指针。 + @@ -1854,11 +1854,11 @@ PGresult *PQexecParams(PGconn *conn, paramFormats[] - 指定参数是否为文本(在参数相应的数组项中放一个零)或二进制(在参数相应的数组项中放一个一)。如果该数组指针为空,那么所有参数都会被假定为文本串。 - + 指定参数采用文本格式(在对应数组元素中填入零)还是二进制格式(填入一)。如果数组指针为空指针,则将所有参数视为文本字符串。 + - 以二进制格式传递的值要求后端所期待的内部表示形式的知识。例如,整数必须以网络字节序被传递。传递numeric值要求关于服务器存储格式的知识,正如src/backend/utils/adt/numeric.c::numeric_send()以及src/backend/utils/adt/numeric.c::numeric_recv()中所实现的。 - + 以二进制格式传递值时,需要了解后端所要求的内部表示形式。例如,整数必须以网络字节序传递。传递 numeric 值时,需要了解服务器的存储格式,其实现见 src/backend/utils/adt/numeric.c::numeric_send()src/backend/utils/adt/numeric.c::numeric_recv()。 + @@ -1866,8 +1866,8 @@ PGresult *PQexecParams(PGconn *conn, resultFormat - 指定零来得到文本格式的结果,或者指定一来得到二进制格式的结果(目前没有规定要求以不同格式得到不同的结果列,尽管在底层协议中这是可以实现的)。 - + 指定零以获取文本格式的结果,指定一以获取二进制格式的结果。(目前无法让不同结果列使用不同格式,尽管底层协议支持这样做。) + @@ -1877,7 +1877,9 @@ PGresult *PQexecParams(PGconn *conn, - PQexecParams 相对于 PQexec 的主要优点是可以将参数值与命令字符串分开,从而避免繁琐且容易出错的加引号和转义工作。 + + PQexecParams 相对于 PQexec 的主要优点是可以将参数值与命令字符串分开,从而避免繁琐且容易出错的加引号和转义工作。 + PQexec不同,PQexecParams至多允许在给定串中出现一个 SQL 命令(其中可以有分号,但是不能有超过一个非空命令)。这是底层协议的一个限制,但是有助于抵抗 SQL 注入攻击。 @@ -1886,12 +1888,12 @@ PGresult *PQexecParams(PGconn *conn, - 通过 OID 指定参数类型很罗嗦,特别是如果你不愿意将特定的 OID 值硬编码到你的程序中时。不过,即使服务器本身也无法确定参数的类型,你可以避免这样做,或者选择一种与你想要的不同的类型。在 SQL 命令文本中,附加一个显式类型转换给参数符号来表示你将发送什么样的数据类型。例如: + 通过 OID 指定参数类型较为繁琐,尤其是在不希望将具体 OID 值写死在程序中时。不过,即使服务器无法自行确定参数类型,或者推断出的类型与你所需的不同,也可以避免直接指定 OID。在 SQL 命令文本中,为参数符号添加显式类型转换,即可指定要发送的数据类型。例如: SELECT * FROM mytable WHERE x = $1::bigint; - 这强制参数$1被当作bigint,而默认情况下它将被赋予与x相同的类型。当以二进制格式发送参数值时,我们强烈推荐以这种方式或通过指定一个数字类型的 OID 来强制参数类型决定。因为二进制格式比文本格式具有更少的冗余,并且因此服务器将不会有更多机会为你检测一个类型匹配错误。 - +这会强制将参数 $1 当作 bigint,而默认情况下会为它分配与 x 相同的类型。以二进制格式发送参数值时,强烈建议采用这种方式,或直接指定类型的数值 OID,来明确决定参数类型。因为二进制格式的冗余比文本格式更少,服务器发现类型不匹配错误的机会也更少。 + @@ -1911,13 +1913,15 @@ PGresult *PQprepare(PGconn *conn, - PQprepare创建一个后面会由PQexecPrepared执行的预备语句。 这个特性允许命令被反复执行而无需每次都进行解析和规划,详见PQprepare 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + + PQprepare 创建一个预备语句,供随后使用 PQexecPrepared 执行。 这个特性允许命令被反复执行而无需每次都进行解析和规划,详见PQprepare 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + 该函数从query串创建一个名为stmtName的预备语句,该串必须包含一个单一 SQL 命令。 stmtName可以是""来创建一个未命名语句,在这种情况下任何已存在未命名语句将被自动替换。 否则,如果语句名称已经在当前会话中被定义,则是一种错误。如果使用了任何参数,它们在查询中以$1$2等引用。 - nParams是参数的个数,其类型在数组paramTypes[]中被预先指定(当nParams为零时,该数组指针可以是NULL)。 + nParams 是在数组 paramTypes[] 中预先指定了类型的参数数量(当nParams为零时,该数组指针可以是NULL)。 paramTypes[]通过 OID 指定要赋予给参数符号的数据类型。 如果paramTypesNULL或者该数组中任何特定元素为零,服务器会用对待未指定类型的字符串字面量的方式为参数符号推测一种数据类型。 还有,查询能够使用编号高于nParams的参数符号,它们的数据类型也会被自动推测(找出推测出的数据类型的方法见PQdescribePrepared)。 @@ -1925,7 +1929,7 @@ PGresult *PQprepare(PGconn *conn, 正如PQexec一样,结果通常是一个PGresult对象,其内容代表服务器端成功或失败。 - 一个空结果表示内存不足或者根本无法发送命令。关于错误的更多信息请见PQerrorMessage。 + 返回空指针表示内存不足,或者根本无法发送命令。关于错误的更多信息请见PQerrorMessage @@ -1950,7 +1954,7 @@ PGresult *PQexecPrepared(PGconn *conn, - PQexecPrepared类似于PQexecParams, 但要执行的命令是通过指定先前准备好的语句来指定,而不是提供查询字符串。 此功能允许重复使用的命令只被解析和计划一次,而不是每次执行时都要进行。 该语句必须在当前会话中先前准备好。 PQexecPrepared 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + PQexecPrepared类似于PQexecParams, 但它通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。 此功能使重复使用的命令只需解析和规划一次,而不必在每次执行时都进行这些工作。 该语句必须事先在当前会话中创建为预备语句。 PQexecPrepared 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 参数与PQexecParams相同,只是给出了预备语句的名称而不是查询字符串, @@ -1964,21 +1968,21 @@ PGresult *PQexecPrepared(PGconn *conn, - 提交请求以获取有关指定准备好的语句的信息,并等待完成。 + 提交请求以获取有关指定预备语句的信息,并等待完成。 PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - PQdescribePrepared允许应用程序获取关于先前准备的语句的信息。 PQdescribePrepared 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + PQdescribePrepared允许应用程序获取关于先前创建的预备语句的信息。 PQdescribePrepared 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 stmtName可以是""NULL来引用 - 未命名的语句,否则必须是现有准备好的语句的名称。成功时,返回一个 + 未命名的语句,否则必须是现有预备语句的名称。成功时,返回一个 状态为PGRES_COMMAND_OKPGresult。 函数PQnparamsPQparamtype可以应用于此 - PGresult以获取有关准备语句参数的信息, + PGresult以获取有关预备语句参数的信息, 函数PQnfieldsPQfnamePQftype等提供有关语句的结果列(如果有)的信息。 @@ -1990,13 +1994,15 @@ PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - 提交请求以获取有关指定门户的信息,并等待完成。 + 提交请求以获取有关指定 portal 的信息,并等待完成。 PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - PQdescribePortal允许应用程序获取有关先前创建的 portal 的信息。 (libpq不直接提供对 portal 的访问,但你可以使用此函数检查通过DECLARE CURSOR SQL 命令创建的游标的属性。) PQdescribePortal 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + + PQdescribePortal 允许应用程序获取先前创建的 portal 的信息。(libpq 不提供对 portal 的直接访问,但可以用此函数检查通过 DECLARE CURSOR SQL 命令创建的游标的属性。) PQdescribePortal 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + portalName可以是""NULL来引用未命名的 portal, @@ -2009,7 +2015,9 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - PGresultPGresult结构体封装服务器返回的结果。libpq应用程序的开发者应注意保持PGresult的抽象性。请使用下面的访问函数获取PGresult的内容。避免直接引用PGresult结构体的字段,因为这些字段以后可能改变。 + + PGresultPGresult 结构体封装服务器返回的结果。编写 libpq 应用程序时,应注意维护 PGresult 的抽象。请使用下述访问函数获取 PGresult 的内容。避免直接引用 PGresult 结构体的字段,因为这些字段将来可能改变。 + PQresultStatus PQresultStatus @@ -2108,7 +2116,7 @@ ExecStatusType PQresultStatus(const PGresult *res); PGRES_SINGLE_TUPLE - PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单一行模式时发生(见)。 + PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单行模式时发生(见)。 @@ -2125,10 +2133,12 @@ ExecStatusType PQresultStatus(const PGresult *res); PQresStatus PQresStatus - PQresultStatus返回的枚举值转换为描述该状态码的字符串常量。调用者不应释放此结果。 + + 将 PQresultStatus 返回的枚举值转换为描述该状态码的字符串常量。调用者不应释放此结果。 + char *PQresStatus(ExecStatusType status); - + @@ -2136,10 +2146,13 @@ char *PQresStatus(ExecStatusType status); PQresultErrorMessage PQresultErrorMessage - 返回与命令关联的错误消息;如果没有错误,则返回空字符串。 + + 返回与命令关联的错误消息;如果没有错误,则返回空字符串。 + char *PQresultErrorMessage(const PGresult *res); -如果发生了错误,返回的字符串会包含末尾换行符。调用者不应直接释放结果。在将关联的PGresult句柄传给以下函数时,会释放该结果:PQclear。 - + +如果发生了错误,返回的字符串会以换行符结尾。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 PQclear 时,结果会被释放。 + 紧跟着一个PQexecPQgetResult调用,PQerrorMessage(在连接上)将返回与PQresultErrorMessage相同的字符串(在结果上)。 @@ -2154,11 +2167,15 @@ char *PQresultErrorMessage(const PGresult *res); PQresultVerboseErrorMessage PQresultVerboseErrorMessage - 返回与PGresult对象关联的错误消息的重新格式化版本。 + + 返回与 PGresult 对象关联的错误消息的重新格式化版本。 + char *PQresultVerboseErrorMessage(const PGresult *res, PGVerbosity verbosity, PGContextVisibility show_context); -某些情况下,客户端可能希望取得之前报告的错误的更详细版本。PQresultVerboseErrorMessage可以满足这一需求:它计算以下函数本应生成的消息:PQresultErrorMessage,假设在生成给定的PGresult时,连接已经采用指定的详细程度设置。如果PGresult不是错误结果,则改为报告PGresult is not an error result。返回的字符串包含末尾换行符。 + +有时客户端希望获取先前报告过的错误的更详细版本。PQresultVerboseErrorMessage 可满足这一需求:它按指定的详细程度设置重新生成消息。假如在生成给定 PGresult 时,连接已经采用这些设置,那么 PQresultErrorMessage 返回的就会是这条消息。如果 PGresult 不是错误结果,则改为报告 PGresult is not an error result。返回的字符串以换行符结尾。 + 和大部分从PGresult中提取数据的其他函数不同,这个函数的结果是一个全新分配的字符串。调用者在不需要这个字符串以后,必须使用PQfreemem()释放它。 @@ -2173,18 +2190,20 @@ char *PQresultVerboseErrorMessage(const PGresult *res, PQresultErrorFieldPQresultErrorField - 返回错误报告中的单个字段。 + + 返回错误报告中的单个字段。 + char *PQresultErrorField(const PGresult *res, int fieldcode); - fieldcode是错误字段标识符,参见下文列出的符号。NULL会在以下情况下返回:PGresult不是错误或警告结果,或者不包含指定字段。字段值通常不含末尾换行符。调用者不应直接释放结果。在将关联的PGresult句柄传给以下函数时,会释放该结果:PQclear。 - +fieldcode 是错误字段标识符,参见下文列出的符号。如果 PGresult 不是错误或警告结果,或者不包含指定字段,则返回 NULL。字段值通常不含末尾换行符。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 PQclear 时,结果会被释放。 + 可以使用以下字段代码: PG_DIAG_SEVERITY - 严重性。域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 @@ -2193,16 +2212,16 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_SEVERITY_NONLOCALIZED - 域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY域相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 版本以后产生的报告中。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY字段相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 及更高版本产生的报告中。 - PG_DIAG_SQLSTATEerror codeslibpq + PG_DIAG_SQLSTATE错误码libpq - 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个域无法被本地化,并且总是存在。 + 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个字段无法被本地化,并且总是存在。 @@ -2229,7 +2248,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_MESSAGE_HINT - 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是铁的事实。可能有多行。 + 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是确切事实。可能有多行。 @@ -2247,7 +2266,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_INTERNAL_POSITION - 这被定义为与PG_DIAG_STATEMENT_POSITION域相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个域出现时,PG_DIAG_INTERNAL_QUERY域将总是出现。 + 这被定义为与PG_DIAG_STATEMENT_POSITION字段相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个字段出现时,PG_DIAG_INTERNAL_QUERY字段将总是出现。 @@ -2265,7 +2284,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONTEXT - 指示错误发生的环境。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 + 指示错误发生的上下文。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 @@ -2283,7 +2302,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_TABLE_NAME - 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名域)。 + 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名字段)。 @@ -2292,7 +2311,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_COLUMN_NAME - 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名域来标识该表)。 + 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名字段来标识该表)。 @@ -2301,7 +2320,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_DATATYPE_NAME - 如果错误与一个特定数据类型相关,这里是该数据了行的名字(该数据类型的模式名参考模式名域)。 + 如果错误与一个特定数据类型相关,这里是该数据类型的名字(该数据类型的模式名参考模式名字段)。 @@ -2310,7 +2329,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONSTRAINT_NAME - 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的域(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 + 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的字段(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 @@ -2346,12 +2365,12 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); - 用于模式名、表名、列名、数据类型名和约束名的域只提供给有限的错误类型,见。不要假定任何这些域的存在保证另一个域的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些域。同样地,不要假定这些域代表当前数据库中同类的对象。 + 用于模式名、表名、列名、数据类型名和约束名的字段只提供给有限的错误类型,见。不要假定任何这些字段的存在保证另一个字段的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些字段。同样地,不要假定这些字段代表当前数据库中现存的对象。 - 客户端负责格式化显示信息来迎合它的需要,特别是根据需要打断长的行。出现在错误消息域中的新行字符应该被当作分段而不是换行。 + 客户端负责按自身需要格式化所显示的信息,尤其应在需要时将长行折行。错误消息字段中的换行符应当视为段落分隔,而非行分隔。 libpq 内部产生的错误包含严重性和主要消息,但通常没有其他字段。使用 3.0 之前协议的服务器返回的错误包含严重性和主要消息,有时还包含详细消息,但没有其他字段。 @@ -2365,10 +2384,12 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PQclearPQclear - 释放与PGresult关联的存储空间。每个命令结果都应通过PQclear在不再需要结果时将其释放。 + + 释放与 PGresult 关联的存储空间。每个命令结果在不再需要时都应通过 PQclear 释放。 + void PQclear(PGresult *res); - + 你可以在需要时一直保留PGresult对象;它不会在你发出新命令时消失,甚至在关闭连接后也不会消失。要销毁它,你必须调用PQclear。否则应用程序会发生内存泄漏。 @@ -2376,15 +2397,15 @@ void PQclear(PGresult *res); - + 检索查询结果信息 - 这些函数被用来从一个代表成功查询结果(也就是状态为PGRES_TUPLES_OK或者PGRES_SINGLE_TUPLE)的PGresult对象中抽取信息。它们也可以被用来从一个成功的 Describe 操作中抽取信息:一个 Describe 的结果具有和该查询被实际执行所提供的完全相同的列信息,但是它没有行。对于其他状态值的对象,这些函数会认为结果具有零行和零列。 - + 这些函数用于从表示成功查询结果的 PGresult 对象中提取信息,即状态为 PGRES_TUPLES_OKPGRES_SINGLE_TUPLE 的对象。它们也可用于提取成功 Describe 操作的结果信息:Describe 结果包含的列信息与实际执行查询时相同,但行数为零。对于其他状态值的对象,这些函数会将结果视为零行、零列。 + @@ -2409,7 +2430,7 @@ int PQntuples(const PGresult *res); - 返回查询结果中每一行的列(域)数。 + 返回查询结果中每一行的列(字段)数。 int PQnfields(const PGresult *res); @@ -2422,7 +2443,8 @@ int PQnfields(const PGresult *res); PQfname PQfname - 返回给定列号对应的列名。列号从 0 开始。调用者不应直接释放结果。在将关联的PGresult句柄传给以下函数时,会释放该结果:PQclear。 + + 返回给定列号对应的列名。列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 PQclear 时,结果会被释放。 char *PQfname(const PGresult *res, int column_number); @@ -2453,11 +2475,11 @@ int PQfnumber(const PGresult *res, - 给定的名称被视作一个 SQL 命令中的一个标识符,也就是说,除非被双引号引用,它是小写形式的。例如,给定一个 SQL 命令: + 给定名称按 SQL 命令中的标识符处理,即除非用双引号引用,否则会转换为小写。例如,对于以下 SQL 命令生成的查询结果: SELECT 1 AS FOO, 2 AS "BAR"; - 我们将得到结果: +会得到以下结果: PQfname(res, 0) foo PQfname(res, 1) BAR @@ -2475,7 +2497,7 @@ PQfnumber(res, "\"BAR\"") 1 - 返回给定列从中取出的表的 OID。列号从 0 开始。 + 返回给定列所取自的表的 OID。列号从 0 开始。 Oid PQftable(const PGresult *res, int column_number); @@ -2484,7 +2506,9 @@ Oid PQftable(const PGresult *res, 如果列号超出范围、指定的列不是对表列的简单引用,或者使用 3.0 之前的协议,则返回 InvalidOid。可以查询系统表 pg_class,确定所引用的具体表。 - 包含 libpq 头文件后,将定义类型 Oid 和常量 InvalidOid。它们都属于某种整数类型。 + + 包含 libpq 头文件后,将定义类型 Oid 和常量 InvalidOid。它们都属于某种整数类型。 + @@ -2493,7 +2517,7 @@ Oid PQftable(const PGresult *res, - 返回构成指定查询结果列的列(在其表中)的列号。查询结果列号从 0 开始,但是表列具有非零编号。 + 返回指定查询结果列所对应的表列在表中的列号。查询结果的列号从 0 开始,而表列的编号非零。 int PQftablecol(const PGresult *res, int column_number); @@ -2510,7 +2534,7 @@ int PQftablecol(const PGresult *res, - 返回指示给定列格式的格式编码。列号从 0 开始。 + 返回表示给定列格式的格式代码。列号从 0 开始。 int PQfformat(const PGresult *res, int column_number); @@ -2518,7 +2542,7 @@ int PQfformat(const PGresult *res, - 格式代码零指示文本数据表示,而格式代码一表示二进制表示(其他代码被保留用于未来的定义)。 + 格式代码零表示文本数据,格式代码一表示二进制数据。(其他代码保留供将来定义。) @@ -2545,7 +2569,7 @@ Oid PQftype(const PGresult *res, - 返回与给定列号相关联的列的修饰符类型。列号从 0 开始。 + 返回与给定列号相关联的列的类型修饰符。列号从 0 开始。 int PQfmod(const PGresult *res, int column_number); @@ -2553,7 +2577,7 @@ int PQfmod(const PGresult *res, - 修饰符值的解释是与类型相关的,它们通常指示精度或尺寸限制。值 -1 被用来指示没有信息可用。大部分的数据类型不适用修饰符,在那种情况中值总是 -1。 + 修饰符值的含义由数据类型决定,通常表示精度或大小限制。值 -1 表示没有可用信息。大多数数据类型不使用修饰符,此时该值始终为 -1。 @@ -2563,7 +2587,7 @@ int PQfmod(const PGresult *res, - 返回与给定列号相关的列的尺寸(以字节计)。列号从 0 开始。 + 返回给定列号对应列的大小,以字节计。列号从 0 开始。 int PQfsize(const PGresult *res, int column_number); @@ -2571,7 +2595,7 @@ int PQfsize(const PGresult *res, - PQfsize返回在一个数据库行中为这个列分配的空间,换句话说是服务器对该数据类型的内部表示的尺寸(因此,它对客户端并不是真地非常有用)。一个负值指示该数据类型是变长的。 + PQfsize 返回数据库行中为该列分配的空间,即服务器内部表示该数据类型所需的大小。(因此,它对客户端用处不大。)负值表示该数据类型是变长类型。 @@ -2588,8 +2612,7 @@ int PQbinaryTuples(const PGresult *res); - 这个函数已经被废弃(除了与COPY一起使用),因为一个单一PGresult可以在某些列中包含文本数据而且在另一些列中包含二进制数据。 - PQfformat要更好。只有结果的所有列是二进制(格式 1)时PQbinaryTuples才返回 1。 + 此函数已弃用(与 COPY 配合使用的情况除外),因为单个 PGresult 可能在部分列中包含文本数据,而在其他列中包含二进制数据。推荐使用 PQfformat。只有结果中的所有列都采用二进制格式(格式 1)时,PQbinaryTuples 才返回 1。 @@ -2598,7 +2621,8 @@ int PQbinaryTuples(const PGresult *res); PQgetvalue PQgetvalue - 返回以下结果中某一行的一个字段值:PGresult。行号和列号都从 0 开始。调用者不应直接释放结果。在将关联的PGresult句柄传给以下函数时,会释放该结果:PQclear。 + + 返回 PGresult 中某一行的单个字段值。行号和列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 PQclear 时,结果会被释放。 char *PQgetvalue(const PGresult *res, int row_number, @@ -2606,24 +2630,26 @@ char *PQgetvalue(const PGresult *res, - 对于文本格式的数据,PQgetvalue 返回字段值的字符串表示,以零字节结尾。对于二进制格式的数据,返回值采用该数据类型的 typsendtypreceive 函数所决定的二进制表示。(这种情况下,值后面实际上也有一个零字节,但通常没有用处,因为值本身很可能包含零字节。) + + 对于文本格式的数据,PQgetvalue 返回字段值的字符串表示,以零字节结尾。对于二进制格式的数据,返回值采用该数据类型的 typsendtypreceive 函数所决定的二进制表示。(这种情况下,值后面实际上也有一个零字节,但通常没有用处,因为值本身很可能包含零字节。) + - 如果该域值为空,则返回一个空串。关于区分空值和空字符串值请见PQgetisnull。 + 如果字段值为 null,则返回空字符串。关于如何区分 null 值与空字符串值,参见 PQgetisnull - PQgetvalue返回的指针指向作为PGresult结构体一部分的存储。我们不应该修改它指向的数据,并且如果要在超过PGresult结构体本身的生命期之外使用它,我们必须显式地把该数据拷贝到其他存储中。 + PQgetvalue 返回的指针指向属于 PGresult 结构体的存储空间。不应修改它所指向的数据;如果需要在 PGresult 结构体的生命周期结束后继续使用这些数据,就必须显式地将数据复制到其他存储空间。 - PQgetisnullPQgetisnullnull valuein libpq + PQgetisnullPQgetisnullnull 值libpq 中的 - 测试一个域是否为空值。行号和列号从 0 开始。 + 检查字段是否为 null 值。行号和列号从 0 开始。 int PQgetisnull(const PGresult *res, int row_number, @@ -2632,7 +2658,7 @@ int PQgetisnull(const PGresult *res, - 如果该域是空,这个函数返回 1。如果它包含一个非空值,则返回 0(注意PQgetvalue将为一个空域返回一个空串,不是一个空指针)。 + 如果字段为 null,此函数返回 1;如果包含非 null 值,则返回 0。(注意,对于 null 字段,PQgetvalue 返回空字符串,而非空指针。) @@ -2642,7 +2668,7 @@ int PQgetisnull(const PGresult *res, - 返回一个域值的真实长度,以字节计。行号和列号从 0 开始。 + 返回字段值的实际长度,以字节计。行号和列号从 0 开始。 int PQgetlength(const PGresult *res, int row_number, @@ -2651,9 +2677,7 @@ int PQgetlength(const PGresult *res, - 这是特定数据值的真实数据长度,也就是PQgetvalue指向的对象的尺寸。 - 对于文本数据格式,这和strlen()相同。对于二进制格式这是基本信息。 - 注意我们应该依赖于PQfsize来得到实际的数据长度。 + 这是该数据值的实际数据长度,即 PQgetvalue 所指对象的大小。对于文本格式的数据,它与 strlen() 的结果相同。对于二进制格式,这是必不可少的信息。注意,不应依赖 PQfsize 来获取实际数据长度。 @@ -2698,29 +2722,29 @@ Oid PQparamtype(const PGresult *res, int param_number); - 将所有的行打印到指定的输出流,以及有选择地将列名打印到指定的输出流。 + 将所有行输出到指定的输出流,并可选择输出列名。 void PQprint(FILE *fout, /* 输出流 */ const PGresult *res, const PQprintOpt *po); typedef struct { - pqbool header; /* 打印输出域标题和行计数 */ - pqbool align; /* 填充对齐域 */ - pqbool standard; /* 旧的格式 */ + pqbool header; /* 打印输出字段标题和行数 */ + pqbool align; /* 填充并对齐字段 */ + pqbool standard; /* 旧的简陋格式 */ pqbool html3; /* 输出 HTML 表格 */ - pqbool expanded; /* 扩展表格 */ - pqbool pager; /* 如果必要为输出使用页 */ - char *fieldSep; /* 域分隔符 */ + pqbool expanded; /* 展开表格 */ + pqbool pager; /* 需要时使用分页器输出 */ + char *fieldSep; /* 字段分隔符 */ char *tableOpt; /* 用于 HTML 表格元素的属性 */ char *caption; /* HTML 表格标题 */ - char **fieldName; /* 替换域名称的空终止数组 */ + char **fieldName; /* 以空指针结尾的替换字段名数组 */ } PQprintOpt; - 这个函数以前被psql用来打印查询结果,但是现在不是这样了。注意它假定所有的数据都是文本格式。 + psql 以前用此函数打印查询结果,现在已不再使用。注意,此函数假定所有数据都是文本格式。 @@ -2763,7 +2787,9 @@ char *PQcmdTuples(PGresult *res); - 此函数返回一个字符串,其中包含产生该 PGresultSQL 语句所影响的行数。此函数只能在执行 SELECTCREATE TABLE ASINSERTUPDATEDELETEMOVEFETCHCOPY 语句之后使用,也可以在对包含 INSERTUPDATEDELETE 语句的预备查询执行 EXECUTE 之后使用。如果产生 PGresult 的是其他命令,PQcmdTuples 将返回空字符串。调用者不应直接释放返回值;将关联的 PGresult 句柄传给 PQclear 时,它会被释放。 + + 此函数返回一个字符串,其中包含产生该 PGresultSQL 语句所影响的行数。此函数只能在执行 SELECTCREATE TABLE ASINSERTUPDATEDELETEMOVEFETCHCOPY 语句之后使用,也可以在对包含 INSERTUPDATEDELETE 语句的预备查询执行 EXECUTE 之后使用。如果产生 PGresult 的是其他命令,PQcmdTuples 将返回空字符串。调用者不应直接释放返回值;当关联的 PGresult 句柄被传给 PQclear 时,返回值会被释放。 + @@ -2773,7 +2799,7 @@ char *PQcmdTuples(PGresult *res); - 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDin libpq。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid。 + 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDlibpq 中的。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid Oid PQoidValue(const PGresult *res); @@ -2785,7 +2811,9 @@ Oid PQoidValue(const PGresult *res); PQoidStatus PQoidStatus - 此函数已弃用,推荐使用PQoidValue,且此函数不是线程安全的。它返回包含插入行 OID 的字符串,而PQoidValue返回 OID 值。 + + 此函数不是线程安全的,现已弃用,推荐改用 PQoidValue。它返回包含插入行 OID 的字符串,而 PQoidValue 返回 OID 值。 + char *PQoidStatus(const PGresult *res); @@ -2801,7 +2829,7 @@ char *PQoidStatus(const PGresult *res); 转义字符串 - in libpq + libpq 中的 @@ -2817,17 +2845,13 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); 为了让一个字符串可用于 SQL 命令,PQescapeLiteral会对它进行转义。 - 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜线)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 + 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜杠)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 PQescapeLiteral执行这种操作。 - PQescapeLiteral返回一个str参数的已被转义版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,PQescapeLiteral会停止在零,该行为更像strncpy)。 - 返回字符串中的所有特殊字符都会被替换,这样它们就能被PostgreSQL字符串字面量解析器正确处理。 - 结果中也会附加一个终止零字节,并包含包围PostgreSQL字符串字面量所需的单引号。 - + PQescapeLiteral 返回 str 参数的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节,PQescapeLiteral 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便 PostgreSQL 字符串字面量解析器正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号包含在结果字符串中。 + 发生错误时,PQescapeLiteral返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -2841,7 +2865,7 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); - 注意,当一个数据值被作为PQexecParams或其兄弟例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 + 注意,当一个数据值被作为PQexecParams或相关例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 @@ -2856,14 +2880,13 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - PQescapeIdentifier 对字符串进行转义,使其可用作 SQL 标识符,例如表名、列名或函数名。当用户提供的标识符可能包含未经转义就不会被 SQL 解析器视为标识符一部分的特殊字符,或包含需要保留大小写的大写字符时,此函数很有用。 + + PQescapeIdentifier 对字符串进行转义,使其可用作 SQL 标识符,例如表名、列名或函数名。当用户提供的标识符可能包含未经转义就不会被 SQL 解析器视为标识符一部分的特殊字符,或包含需要保留大小写的大写字符时,此函数很有用。 + - PQescapeIdentifier返回一个str参数的已被转义为 SQL 标识符的版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存必须用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,PQescapeIdentifier会停止在零,该行为更像strncpy)。 - 返回串中的所有特殊字符都被替换掉,这样它们能被作为一个 SQL 标识符正确地处理。还会加上一个终止零字节。返回串也将被双引号包围。 - + PQescapeIdentifier 返回 str 参数作为 SQL 标识符的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,必须使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节,PQescapeIdentifier 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便正确地作为 SQL 标识符处理。还会添加一个末尾零字节,并用双引号包围返回的字符串。 + 发生错误时,PQescapeIdentifier返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -2872,7 +2895,7 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - 与字符串一样,要阻止 SQL 注入攻击,当从一个不可信的来源接收到 SQL 标识符时,它们必须被转义。 + 与字符串字面量一样,为防止 SQL 注入攻击,从不可信来源接收到的 SQL 标识符必须经过转义。 @@ -2891,18 +2914,12 @@ size_t PQescapeStringConn(PGconn *conn, - PQescapeStringConn转义字符串,它很像PQescapeLiteral。 - 与PQescapeLiteral不一样的是,调用者负责提供一个合适尺寸的缓冲区。 - 此外,PQescapeStringConn不产生必须包围PostgreSQL字符串的单引号。 - 它们应该在结果要插入的 SQL 命令中提供。参数from指向要被转义的串的第一个字符,并且length参数给出了这个串中的字节数。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,PQescapeStringConn会停止在零,该行为更像strncpy)。 - to应当指向一个缓冲区,它至少能容纳length值的两倍再加一个字节,否则该行为是未被定义的。 - 如果tofrom串重叠,行为也是未被定义的。 - + PQescapeStringConn 对字符串字面量进行转义,与 PQescapeLiteral 类似。与 PQescapeLiteral 不同,调用者需要提供大小合适的缓冲区。此外,PQescapeStringConn 不会生成包围 PostgreSQL 字符串字面量所需的单引号;应在包含转义结果的 SQL 命令中提供这些引号。from 参数指向待转义字符串的首字符,length 参数给出该字符串的字节数。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节,PQescapeStringConn 会在该字节处停止;这一行为类似于 strncpy。)to 必须指向一个缓冲区,其容量至少为 length 的两倍加一个字节,否则行为未定义。如果 tofrom 字符串重叠,行为同样未定义。 + - 如果error参数不是NULL,那么成功时*error被设置为零,错误时设置为非零。当前唯一可能的错误情况涉及源串中非法的多字节编码。错误时仍然会产生输出串,但是可以预期服务器将认为它是畸形的并且拒绝它。在发生错误时,一个合适的消息被存储在conn对象中,不管error是不是NULL。 - + 如果 error 参数不是 NULL,则成功时将 *error 设为零,出错时设为非零。目前唯一可能的错误是源字符串中存在无效的多字节编码。出错时仍会生成输出字符串,但预计服务器会因其格式错误而拒绝它。发生错误时,无论 error 是否为 NULL,都会在 conn 对象中保存相应消息。 + PQescapeStringConn返回写到to的字节数,不包括终止的零字节。 @@ -2915,15 +2932,19 @@ size_t PQescapeStringConn(PGconn *conn, - PQescapeString是以下函数的旧版本,现已弃用:PQescapeStringConn。 + PQescapeStringPQescapeStringConn 的旧版本,现已弃用。 size_t PQescapeString (char *to, const char *from, size_t length); - + - PQescapeStringConn 唯一的区别是,PQescapeString 不接受 PGconnerror 参数。因此,它无法根据连接属性(例如字符编码)调整行为,可能给出错误的结果。此外,它也无法报告错误情况。 + + 与 PQescapeStringConn 唯一的区别是,PQescapeString 不接受 PGconnerror 参数。因此,它无法根据连接属性(例如字符编码)调整行为,可能给出错误的结果。此外,它也无法报告错误情况。 + - PQescapeString 可以在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。在其他情形下,它存在安全隐患,应改用 PQescapeStringConn + + PQescapeString 可以在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。在其他情形下,它存在安全隐患,应改用 PQescapeStringConn。 + @@ -2931,7 +2952,9 @@ size_t PQescapeString (char *to, const char *from, size_t length); PQescapeByteaConn PQescapeByteaConn - 对二进制数据进行转义,使其能够在 SQL 命令中用作以下类型的值:bytea。与PQescapeStringConn一样,这仅用于将数据直接插入 SQL 命令字符串的情况。 + + 对二进制数据进行转义,使其能够在 SQL 命令中用作 bytea 类型的值。与 PQescapeStringConn 一样,这仅用于将数据直接插入 SQL 命令字符串的情况。 + unsigned char *PQescapeByteaConn(PGconn *conn, const unsigned char *from, size_t from_length, @@ -2945,10 +2968,12 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - from参数指向要被转义的串的第一个字节,并且from_length参数给出这个二进制串中的字节数(一个终止的零字节是不需要的也是不被计算的)。to_length参数指向一个将保持生成的已转义串长度的变量。这个结果串长度包括结果的终止零字节。 + from 参数指向待转义字符串的首字节,from_length 参数给出该二进制字符串的字节数。(末尾零字节既不需要,也不计入长度。)to_length 参数指向用于保存转义后字符串长度的变量。该结果字符串长度包含结果末尾的零字节。 - PQescapeByteaConn 返回 from 参数所指二进制字符串的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。返回字符串中的所有特殊字符都已替换,以便 PostgreSQL 字符串字面量解析器和 bytea 输入函数正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号不包含在结果字符串中。 + + PQescapeByteaConn 返回 from 参数所指二进制字符串的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。返回字符串中的所有特殊字符都已替换,以便 PostgreSQL 字符串字面量解析器和 bytea 输入函数正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号不包含在结果字符串中。 + 在发生错误时,将返回一个空指针,并且一个合适的错误消息被存储在conn对象中。当前,唯一可能的错误是没有足够的内存用于结果串。 @@ -2961,7 +2986,7 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - PQescapeBytea是以下函数的旧版本,现已弃用:PQescapeByteaConn。 + PQescapeByteaPQescapeByteaConn 的旧版本,现已弃用。 unsigned char *PQescapeBytea(const unsigned char *from, size_t from_length, @@ -2970,9 +2995,7 @@ unsigned char *PQescapeBytea(const unsigned char *from, - 与PQescapeByteaConn的唯一区别是PQescapeBytea不用一个PGconn参数。 - 正因为这样,PQescapeBytea只能在一次只使用一个PostgreSQL连接的客户端程序中安全地使用(在这种情况下它可以在内部找出它需要知道的东西)。 - 如果在有多个数据库连接的程序中使用,它可能给出错误的结果(在那种情况下使用PQescapeByteaConn)。 + 与 PQescapeByteaConn 唯一的区别是,PQescapeBytea 不接受 PGconn 参数。因此,PQescapeBytea 只能在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。如果在使用多个数据库连接的程序中使用,它可能给出错误的结果(此时应使用 PQescapeByteaConn)。 @@ -3038,26 +3061,26 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - PQexec总是收集命令的整个结果,把它缓存在一个单一的PGresult中。虽然这简化了应用的错误处理逻辑,它对于包含很多行的结果并不现实。 - + PQexec 总是收集命令的完整结果,并将其缓存在单个 PGresult 中。这简化了应用程序的错误处理逻辑,但对于包含大量行的结果,可能不切实际。 + - 如果应用程序不希望受到这些限制,可以改用构成PQexec的底层函数:PQsendQueryPQgetResult。此外,还有PQsendQueryParams, - PQsendPrepare, - PQsendQueryPrepared, - PQsendDescribePrepared,以及PQsendDescribePortal,它们可以与PQgetResult配合使用,分别实现以下函数的功能:PQexecParams, - PQprepare, - PQexecPrepared, - PQdescribePrepared,以及PQdescribePortal + + 如果应用程序不希望受到这些限制,可以改用构成 PQexec 的底层函数:PQsendQueryPQgetResult。此外,PQsendQueryParamsPQsendPreparePQsendQueryPreparedPQsendDescribePreparedPQsendDescribePortal 可以与 PQgetResult 配合使用,分别实现 PQexecParamsPQpreparePQexecPreparedPQdescribePreparedPQdescribePortal 的功能。 + PQsendQuery PQsendQuery - 向服务器提交命令,不等待结果。命令发送成功时返回 1,否则返回 0(此时可以使用PQerrorMessage取得更多失败信息)。 + + 向服务器提交命令,不等待结果。命令发送成功时返回 1,否则返回 0(此时可使用 PQerrorMessage 获取更多失败信息)。 + int PQsendQuery(PGconn *conn, const char *command); -成功调用PQsendQuery之后,应调用PQgetResult一次或多次来取得结果。PQsendQuery在同一连接上不能再次调用,直到PQgetResult返回空指针,表明命令已经完成。 + +成功调用 PQsendQuery 后,应调用 PQgetResult 一次或多次来获取结果。在 PQgetResult 返回空指针、表明命令已完成之前,不得在同一连接上再次调用 PQsendQuery。 + @@ -3065,7 +3088,9 @@ int PQsendQuery(PGconn *conn, const char *command); PQsendQueryParams PQsendQueryParams - 向服务器提交命令及独立指定的参数,不等待结果。 + + 向服务器提交命令及独立指定的参数,不等待结果。 + int PQsendQueryParams(PGconn *conn, const char *command, int nParams, @@ -3074,7 +3099,9 @@ int PQsendQueryParams(PGconn *conn, const int *paramLengths, const int *paramFormats, int resultFormat); -该函数等价于PQsendQuery,但查询参数可以与查询字符串分开指定。函数参数的处理方式与PQexecParams相同。与PQexecParams一样,它不能用于协议 2.0 的连接,并且查询字符串中只允许包含一条命令。 + +该函数等价于 PQsendQuery,但查询参数可以与查询字符串分开指定。函数参数的处理方式与 PQexecParams 相同。与 PQexecParams 一样,它不能用于协议 2.0 的连接,并且查询字符串中只允许包含一条命令。 + @@ -3082,13 +3109,17 @@ int PQsendQueryParams(PGconn *conn, PQsendPrepare PQsendPrepare - 发送按给定参数创建预备语句的请求,不等待完成。 + + 发送按给定参数创建预备语句的请求,不等待完成。 + int PQsendPrepare(PGconn *conn, const char *stmtName, const char *query, int nParams, const Oid *paramTypes); -这是PQprepare的异步版本:请求发送成功时返回 1,否则返回 0。调用成功后,再调用PQgetResult,确定服务器是否成功创建了预备语句。函数参数的处理方式与PQprepare相同。与PQprepare一样,它不能用于协议 2.0 的连接。 + +这是 PQprepare 的异步版本:请求发送成功时返回 1,否则返回 0。调用成功后,再调用 PQgetResult,确定服务器是否成功创建了预备语句。函数参数的处理方式与 PQprepare 相同。与 PQprepare 一样,它不能用于协议 2.0 的连接。 + @@ -3096,7 +3127,9 @@ int PQsendPrepare(PGconn *conn, PQsendQueryPrepared PQsendQueryPrepared - 发送使用给定参数执行预备语句的请求,不等待结果。 + + 发送使用给定参数执行预备语句的请求,不等待结果。 + int PQsendQueryPrepared(PGconn *conn, const char *stmtName, int nParams, @@ -3104,7 +3137,9 @@ int PQsendQueryPrepared(PGconn *conn, const int *paramLengths, const int *paramFormats, int resultFormat); -该函数类似于PQsendQueryParams,但通过指定先前已准备好的语句的名称来确定要执行的命令,而不是提供查询字符串。函数参数的处理方式与PQexecPrepared相同。与PQexecPrepared一样,它不能用于协议 2.0 的连接。 + +该函数类似于 PQsendQueryParams,但通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。函数参数的处理方式与 PQexecPrepared 相同。与 PQexecPrepared 一样,它不能用于协议 2.0 的连接。 + @@ -3141,7 +3176,9 @@ PGresult *PQgetResult(PGconn *conn); - 必须反复调用 PQgetResult,直到它返回空指针,表明命令已经完成。(如果当前没有正在执行的命令,调用 PQgetResult 会立即返回空指针。)对于 PQgetResult 返回的每个非空结果,都应使用前文介绍的 PGresult 访问函数处理。使用完毕后,不要忘记调用 PQclear 释放每个结果对象。注意,只有存在正在执行的命令,且所需响应数据尚未被 PQconsumeInput 读取时,PQgetResult 才会阻塞。 + + 必须反复调用 PQgetResult,直到它返回空指针,表明命令已经完成。(如果当前没有正在执行的命令,调用 PQgetResult 会立即返回空指针。)对于 PQgetResult 返回的非空指针,应使用前文介绍的 PGresult 访问函数处理相应结果。使用完毕后,不要忘记调用 PQclear 释放每个结果对象。注意,只有存在正在执行的命令,且所需响应数据尚未被 PQconsumeInput 读取时,PQgetResult 才会阻塞。 + @@ -3152,37 +3189,36 @@ PGresult *PQgetResult(PGconn *conn); - + - 使用PQsendQueryPQgetResult解决了PQexec的一个问题:如果一个命令字符串包含多个SQL命令,这些命令的结果可以被个别地获得(顺便说一句:这样就允许一种简单的重叠处理形式, 客户端可以处理一个命令的结果,而同时服务器可以继续处理同一命令字符串中后面的查询)。 - + 使用 PQsendQueryPQgetResult 可以解决 PQexec 的一个问题:如果命令字符串包含多个 SQL 命令,就能分别获取这些命令的结果。(这也支持一种简单的重叠处理方式:客户端可以处理某条命令的结果,同时服务器继续处理同一命令字符串中后面的查询。) + - 可以被PQsendQueryPQgetResult获得的另一种常常想要的特性是一次从大型结果中检索一行。这会在中讨论。 - + 使用 PQsendQueryPQgetResult 还可以实现另一项常见需求:从大型查询结果中一次读取一行。详见 。 + - 仅仅调用PQgetResult仍会使客户端阻塞,直到服务器完成下一条SQL命令。可以通过正确使用另外两个函数来避免这种情况: + + 仅仅调用 PQgetResult 仍会使客户端阻塞,直到服务器完成下一条 SQL 命令。可以通过正确使用另外两个函数来避免这种情况: + PQconsumeInput PQconsumeInput - 如果有来自服务器的输入可用,则使用之。 + 如果服务器有可读取的输入,则读取这些输入。 int PQconsumeInput(PGconn *conn); - PQconsumeInput通常返回 1 表明没有错误,而返回 0 表明有某种麻烦发生(此时可以用PQerrorMessage)。 - 注意该结果并不表明是否真正收集了任何输入数据。在调用PQconsumeInput之后,应用可以检查PQisBusy和/或PQnotifies来看看它们的状态是否改变。 + PQconsumeInput 通常返回 1,表示没有错误;发生问题时则返回 0(此时可查看 PQerrorMessage)。注意,返回值并不说明是否实际读取了输入数据。调用 PQconsumeInput 后,应用程序可以检查 PQisBusy 和/或 PQnotifies,以确定其状态是否发生变化。 - 即使应用还不准备处理一个结果或通知,PQconsumeInput也可以被调用。 - 这个函数将读取可用的数据并且把它保存在一个缓冲区中,从而导致一个select()的读准备好指示消失。 - 因此应用可以使用PQconsumeInput立即清除select()条件,并且在空闲时再检查结果。 + 即使应用程序尚未准备好处理结果或通知,也可以调用 PQconsumeInput。此函数会读取可用数据并将其保存在缓冲区中,从而清除 select() 的可读就绪指示。因此,应用程序可以用 PQconsumeInput 立即清除 select() 的就绪条件,随后在合适的时候检查结果。 @@ -3202,22 +3238,20 @@ int PQisBusy(PGconn *conn); - + - 一个使用这些函数的典型应用将有一个主循环,在主循环中会使用select()poll()等待所有它必须响应的情况。 - 其中之一将是来自服务器的输入可用,对select()来说意味着PQsocket标识的文件描述符上有可读的数据。 - 当主循环检测到输入准备好时,它将调用PQconsumeInput读取输入。 - 然后它可以调用PQisBusy,如果PQisBusy返回假(0)则接着调用PQgetResult。 - 它还可以调用PQnotifies检测NOTIFY消息(见)。 - + 使用这些函数的典型应用程序会在主循环中通过 select()poll() 等待需要响应的各种条件。其中一个条件是服务器有可读取的输入;对于 select(),这意味着 PQsocket 标识的文件描述符上有可读数据。主循环检测到输入就绪时,应调用 PQconsumeInput 读取输入,然后调用 PQisBusy。如果 PQisBusy 返回假(0),就可以接着调用 PQgetResult。还可以调用 PQnotifies 检测 NOTIFY 消息(见 )。 + 一个使用PQsendQuery/PQgetResult的客户端也可以尝试取消一个正在被服务器处理的命令,见。 但是,不管PQcancel的返回值是什么,应用都必须继续使用PQgetResult进行正常的结果读取序列。一次成功的取消只会导致命令比不取消时更快终止。 - 使用上述函数可以避免在等待数据库服务器输入时阻塞。不过,应用程序仍可能在等待向服务器发送输出时阻塞。这种情况较少见,但发送很长的 SQL 命令或数据值时可能发生。(如果应用程序通过COPY IN发送数据,发生的可能性则大得多。)为了防止这种情况,实现完全非阻塞的数据库操作,可以使用以下附加函数。 + + 使用上述函数可以避免在等待数据库服务器输入时阻塞。不过,应用程序仍可能在等待向服务器发送输出时阻塞。这种情况较少见,但发送很长的 SQL 命令或数据值时可能发生。(如果应用程序通过 COPY IN 发送数据,发生的可能性则大得多。)为了防止这种情况,实现完全非阻塞的数据库操作,可以使用以下附加函数。 + PQsetnonblocking PQsetnonblocking @@ -3235,11 +3269,7 @@ int PQsetnonblocking(PGconn *conn, int arg); - 在非阻塞状态下,成功调用PQsendQuery、 - PQputlinePQputnbytes、 - PQputCopyDataPQendcopy不会阻塞; - 它们的更改将存储在本地输出缓冲区中,直到刷新为止。 - 不成功的调用将返回错误,必须重试。 + 在非阻塞状态下,成功调用 PQsendQueryPQputlinePQputnbytesPQputCopyDataPQendcopy 不会阻塞;产生的数据保存在本地输出缓冲区中,等待发送。失败的调用会返回错误,必须重试。 @@ -3270,9 +3300,7 @@ int PQisnonblocking(const PGconn *conn); - 尝试将任何排队的输出数据刷新到服务器。如果成功(或发送队列为空),则返回0; - 如果由于某种原因失败,则返回-1;如果尚未能够发送发送队列中的所有数据(只有在连接为非阻塞时才会发生此情况), - 则返回1。 + 尝试将发送队列中的输出数据发送到服务器。成功(或发送队列为空)时返回 0;因某种原因失败时返回 -1;如果尚未能发送队列中的全部数据,则返回 1(这种情况只可能发生在非阻塞连接上)。 int PQflush(PGconn *conn); @@ -3280,15 +3308,11 @@ int PQflush(PGconn *conn); - + - 在一个非阻塞连接上发送任何命令或者数据之后,要调用PQflush。 - 如果它返回 1,就要等待套接字变成读准备好或写准备好。如果它变为写准备好,应再次调用PQflush。 - 如果它变为读准备好,则应先调用PQconsumeInput,然后再调用PQflush。 - 一直重复直到PQflush返回 0(有必要检查读准备好并且用PQconsumeInput耗尽输入,因为服务器可能阻塞给我们发送数据的尝试,例如 NOTICE 消息,并且在我们读它的数据之前它都不会读我们的数据)。 - 一旦PQflush返回 0,应等待套接字变成读准备好并且接着按照上文所述读取响应。 - + 在非阻塞连接上发送命令或数据后,应调用 PQflush。如果返回 1,就等待套接字变为可读或可写。套接字可写时,再次调用 PQflush;可读时,先调用 PQconsumeInput,再调用 PQflush。重复上述步骤,直到 PQflush 返回 0。(必须检查套接字是否可读,并用 PQconsumeInput 读完输入,因为服务器可能在尝试向客户端发送数据时阻塞,例如发送 NOTICE 消息;在客户端读取这些数据之前,服务器不会读取客户端发送的数据。)当 PQflush 返回 0 后,等待套接字变为可读,再按前述方法读取响应。 + @@ -3416,7 +3440,7 @@ int PQrequestCancel(PGconn *conn); 快速路径接口 - fast path + 快速路径 @@ -3452,24 +3476,22 @@ typedef struct - fnid参数是要被执行的函数的 OID。argsnargs定义了要传递给函数的参数;它们必须匹配已声明的函数参数列表。当一个参数结构体的isint域为真时,u.integer值被以指定长度(必须是 2 或 4 字节)整数的形式发送给服务器;这时候会发生恰当的字节交换。当isint为假时,*u.ptr中指定数量的字节将不做任何处理被发送出去;这些数据必须是服务器 预期的用于该函数参数数据类型的二进制传输的格式(由于历史原因u.ptr被声明为类型int *,其实把它考虑成void *会更好)。result_buf是放置该函数返回值的缓冲区。调用者必须已经分配了足够的空间来存储返回值(这里没有检查!)。实际的结果长度将被放在result_len指向的整数中返回。如果预期结果是 2 或 4 字节整数,把result_is_int设为 1;否则设为 0。把result_is_int设为 1 导致libpq在必要时对值进行交换字节,这样它就作为对客户端机器正确的int值被传输,注意对任一种允许的结果大小都会传递一个 4 字节整数到*result_buf。当result_is_int是 0 时,服务器发送的二进制格式字节将不做修改直接返回(在这种情况下,把result_buf考虑为类型void *更好)。 - + fnid 参数是要执行函数的 OID。argsnargs 指定传给函数的参数,必须与函数声明中的参数列表匹配。参数结构体的 isint 字段为真时,u.integer 值会以指定长度的整数发送到服务器,该长度必须是 2 或 4 字节,并会进行适当的字节序转换。isint 为假时,位于 *u.ptr 的指定数量字节会原样发送;数据必须符合服务器对该函数参数数据类型的二进制传输格式要求。(将 u.ptr 声明为 int * 是历史原因;将其视为 void * 更合适。)result_buf 指向用于存放函数返回值的缓冲区。调用者必须事先分配足够空间来保存返回值,这里不会检查!实际结果长度以字节为单位,返回到 result_len 指向的整数中。如果预期结果是 2 或 4 字节整数,将 result_is_int 设为 1,否则设为 0。将 result_is_int 设为 1 后,libpq 会按需转换字节序,使结果成为适合客户端机器的 int 值;注意,无论是哪种允许的结果大小,传入 *result_buf 的都是 4 字节整数。result_is_int 为 0 时,服务器发送的二进制格式字节串会原样返回。(此时,将 result_buf 视为 void * 更合适。) + - PQfn总是返回一个有效的PGresult指针,成功时状态为PGRES_COMMAND_OK,遇到问题时为PGRES_FATAL_ERROR。 - 在使用结果之前应该检查结果状态。 - 当结果不再使用后,调用者有义务使用PQclear释放PGresult。 - + PQfn 总是返回有效的 PGresult 指针:成功时状态为 PGRES_COMMAND_OK,遇到问题时为 PGRES_FATAL_ERROR。使用结果前应检查其状态。不再需要结果时,调用者负责使用 PQclear 释放 PGresult。 + - 要传递NULL参数到函数,将参数结构体的len字段设置为-1isintu 字段就不相关了。(但这仅适用于使用协议 3.0 及更高版本的连接。) + 要向函数传入 NULL 参数,将该参数结构体的 len 字段设为 -1;此时,isintu 字段便不再相关。(但这仅适用于使用协议 3.0 及更高版本的连接。) + 如果函数返回 NULL,则将 *result_len 设为 -1,而不修改 *result_buf。(这仅适用于使用协议 3.0 及更高版本的连接;在协议 2.0 中,既不修改 *result_len,也不修改 *result_buf。) - 注意在使用此接口时,不能够处理集-值结果。 - 此外,函数必须是一个普通函数,而不是聚合、窗口函数或过程。 - + 注意,使用此接口时无法处理集合值结果。此外,函数必须是普通函数,不能是聚合函数、窗口函数或过程。 + @@ -3478,7 +3500,7 @@ typedef struct NOTIFY - in libpq + 在 libpq 中 @@ -3487,32 +3509,36 @@ typedef struct libpq应用把LISTENUNLISTENNOTIFY命令作为普通 SQL 命令提交。 - 随后通过调用PQnotifies.PQnotifies来检测NOTIFY消息的到达。 + 随后通过调用PQnotifiesPQnotifies来检测NOTIFY消息的到达。 - 函数PQnotifies从已收到但尚未处理的服务器通知消息列表中返回下一条通知。如果没有待处理的通知,则返回空指针。一旦通知由PQnotifies返回,就被视为已处理,并从通知列表中移除。 + + 函数 PQnotifies 从已收到但尚未处理的服务器通知消息列表中返回下一条通知。没有待处理通知时返回空指针。一旦 PQnotifies 返回一条通知,该通知就被视为已处理,并从通知列表中移除。 + PGnotify *PQnotifies(PGconn *conn); typedef struct pgNotify { - char *relname; /* notification channel name */ - int be_pid; /* process ID of notifying server process */ - char *extra; /* notification payload string */ + char *relname; /* 通知通道名称 */ + int be_pid; /* 发送通知的服务器进程 ID */ + char *extra; /* 通知载荷字符串 */ } PGnotify; -处理完一个PGnotify对象(由PQnotifies返回)后,一定要用PQfreemem释放它。只需释放PGnotify指针;relnameextra字段并非独立分配。(这些字段名称是历史遗留的;尤其是,通道名称与关系名称不必有任何关联。) + +处理完 PQnotifies 返回的 PGnotify 对象后,务必使用 PQfreemem 释放它。只需释放 PGnotify 指针;relnameextra 字段并非独立分配。(这些字段名称是历史遗留的;尤其是,通道名称与关系名称不必有任何关联。) + 给出了一个示例程序展示异步通知的使用。 - PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数吸收的消息。 + PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数读取的消息。 在较早版本的libpq中,及时收到NOTIFY消息的唯一方法是不断提交命令,哪怕是空命令,然后在每次PQexec后检查PQnotifies。 - 虽然这种方法仍然有效,但由于效率过低,现已废弃。 + 虽然这种方法仍然有效,但由于浪费处理能力,现已弃用。 - 当你没有可用的命令提交时,一种更好的检查NOTIFY消息的方法是调用PQconsumeInput,然后检查PQnotifies。 + 当没有需要执行的实际命令时,一种更好的检查NOTIFY消息的方法是调用PQconsumeInput,然后检查PQnotifies。 你可以使用select()等待服务器数据到达,这样在无事可做时就不会浪费CPU资源(参见PQsocket以获得可传给select()的文件描述符)。 注意不管是用PQsendQuery/PQgetResult提交命令还是简单地使用PQexec,这种方法都能正常工作。 不过,你应该记住在每次PQgetResultPQexec之后检查PQnotifies,看看在命令的处理过程中是否有通知到达。 @@ -3525,20 +3551,16 @@ typedef struct pgNotify COPY - with libpq + 使用 libpq - PostgreSQL中的COPY命令有用于libpq的对网络连接读出或者写入的选项。这一节描述的函数允许应用通过提供或者消耗已拷贝的数据来充分利用这个功能。 - + PostgreSQLCOPY 命令提供了选项,可以通过 libpq 使用的网络连接读取或写入数据。本节介绍的函数允许应用程序通过提供或接收复制数据来使用这一能力。 + - 整个处理是应用首先通过PQexec或者一个等效的函数发出 SQL COPY命令。 - 对这个命令的响应(如果命令无误)将是一个状态代码是PGRES_COPY_OUT或 者PGRES_COPY_IN(取决于指定的拷贝方向)的PGresult对象。 - 应用然后就应该使用这一节的函数接收或者传送数据行。在数据传输结束之后,另外一个PGresult对象会被返回以表明传输的成功或者失败。 - 它的状态将是:PGRES_COMMAND_OK表示成功,PGRES_FATAL_ERROR表示发生了一些问题。 - 此时我们可以通过PQexec发出进一步的 SQL 命令(在COPY操作的处理过程中,不能用同一个连接执行其它 SQL 命令)。 - + 整体流程如下:应用程序先通过 PQexec 或等效函数发出 SQL COPY 命令。如果命令没有错误,响应就是一个 PGresult 对象,其状态码为 PGRES_COPY_OUTPGRES_COPY_IN,取决于指定的复制方向。应用程序随后应使用本节函数接收或发送数据行。数据传输完成后,会返回另一个 PGresult 对象,表示传输成功或失败:成功时状态为 PGRES_COMMAND_OK,出现问题时为 PGRES_FATAL_ERROR。此时可以通过 PQexec 继续发出 SQL 命令。(COPY 操作进行期间,不能在同一连接上执行其他 SQL 命令。) + 如果一个COPY命令是通过PQexec在一个可能包含额外命令的字符串中发出的,那么应用在完成COPY序列之后必须继续用PQgetResult取得结果。 @@ -3546,12 +3568,14 @@ typedef struct pgNotify - 这一节的函数应该只在从PQexecPQgetResult获得了PGRES_COPY_OUTPGRES_COPY_IN结果状态后执行。 - + 只有从 PQexecPQgetResult 获得 PGRES_COPY_OUTPGRES_COPY_IN 结果状态后,才应调用本节函数。 + - 一个PGresult对象若带有上述某个状态值,还会携带关于即将开始的COPY操作的附加数据。这些数据可以通过下列函数取得,这些函数也用于查询结果: + + 带有上述某个状态值的 PGresult 对象,还会携带关于即将开始的 COPY 操作的附加数据。这些数据可以通过下列函数获取,这些函数也用于查询结果: + - PQnfieldsPQnfieldswith COPY + PQnfieldsPQnfields用于 COPY @@ -3561,7 +3585,7 @@ typedef struct pgNotify - PQbinaryTuplesPQbinaryTupleswith COPY + PQbinaryTuplesPQbinaryTuples用于 COPY @@ -3572,7 +3596,7 @@ typedef struct pgNotify - PQfformatPQfformatwith COPY + PQfformatPQfformat用于 COPY @@ -3584,7 +3608,7 @@ typedef struct pgNotify - + 这些附加数据值仅在使用协议 3.0 时可用。使用协议 2.0 时,这些函数都返回 0。 @@ -3594,8 +3618,8 @@ typedef struct pgNotify 用于发送<command>COPY</command>数据的函数 - 这些函数用于在COPY FROM STDIN期间发送数据。如果在连接不是COPY_IN状态,调用它们会失败。 - + 这些函数用于在 COPY FROM STDIN 期间发送数据。如果连接不处于 COPY_IN 状态,调用它们会失败。 + @@ -3612,12 +3636,11 @@ int PQputCopyData(PGconn *conn, - 传输指定buffer中长度为nbytesCOPY数据到服务器。 - 如果数据被放在队列中,结果是 1;如果因为缓冲区满而无法被放在队列中(只可能发生在连接是非阻塞模式时),那么结果是零;如果发生错误,结果为 -1(如果返回值为 -1,那么使用PQerrorMessage检索细节。如果值是零,那么等待写准备好然后重试)。 + 将指定 buffer 中长度为 nbytesCOPY 数据传输到服务器。数据成功加入队列时返回 1;因缓冲区已满而无法加入队列时返回零(仅可能发生在非阻塞模式下);发生错误时返回 -1。(返回 -1 时,可用 PQerrorMessage 获取详细信息。返回零时,应等待可写就绪后重试。) - 应用可以把COPY数据流划分成任意方便的大小放到缓冲区中。在发送时,缓冲区载荷的边界没有什么语意。数据流的内容必须匹配COPY命令预期的数据格式;详见。 + 应用程序可以将 COPY 数据流分成任意方便大小的数据块,逐块装入缓冲区。发送时,这些数据块的边界没有语义含义。数据流内容必须符合 COPY 命令预期的数据格式;详见 @@ -3634,13 +3657,16 @@ int PQputCopyEnd(PGconn *conn, - 如果 errormsgNULL,则成功结束 COPY_IN 操作。如果 errormsg 不为 NULL,则强制 COPY 失败,并将 errormsg 指向的字符串用作错误消息。(但不应假定服务器一定会返回这条完全相同的错误消息,因为服务器可能已经因自身原因使 COPY 失败。还要注意,在使用 3.0 之前协议的连接上,强制失败选项不起作用。) + + 如果 errormsgNULL,则成功结束 COPY_IN 操作。如果 errormsg 不为 NULL,则强制 COPY 失败,并将 errormsg 指向的字符串用作错误消息。(但不应假定服务器一定会返回这条完全相同的错误消息,因为服务器可能已经因自身原因使 COPY 失败。还要注意,在使用 3.0 之前协议的连接上,强制失败选项不起作用。) + - 如果终止消息被发送,则结果为 1;在非阻塞模式中,结果为 1 也可能只表示终止消息被成功地放在了发送队列中 (在非阻塞模式中,要确认数据确实被发送出去,你应该接着等待写准备好并且调用PQflush,重复这些直到返回零)。 零表示该函数由于缓冲区满而无法将该终止消息放在队列中,这只会发生在非阻塞模式中(在这种情况下,等待写准备好并且再次尝试PQputCopyEnd调用)。 如果发生系统错误,则返回 -1,可以使用PQerrorMessage检索详情。 + + 终止消息已发送时返回 1;在非阻塞模式下,返回 1 也可能仅表示该消息已成功加入发送队列。(在非阻塞模式下,要确认数据已经发送,应接着等待可写就绪并调用 PQflush,反复执行直到返回零。)返回零表示缓冲区已满,无法将终止消息加入队列;这种情况仅可能发生在非阻塞模式下。(此时,应等待可写就绪,再次调用 PQputCopyEnd。)发生严重错误时返回 -1,可用 PQerrorMessage 获取详细信息。 + - 在成功调用PQputCopyEnd之后,调用PQgetResult获取COPY命令的最终结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 成功调用 PQputCopyEnd 后,调用 PQgetResult 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -3670,24 +3696,19 @@ int PQgetCopyData(PGconn *conn, - 在一个COPY期间尝试从服务器获取另外一行数据。数据总是以每次一个数据行的方式被返回;如果只有一个部分行可用,那么它不会被返回。 - 成功返回一个数据行涉及到分配一块内存来保存该数据。buffer参数必须为非NULL。 - *buffer被设置为指向分配到的内存的指针,或者是在没有返回缓冲区的情况下指向NULL。 - 一个非NULL的结果缓冲区在不需要时必须用PQfreemem释放。 + 在 COPY 期间尝试从服务器获取下一行数据。每次总是返回一个完整数据行;如果只有部分行可用,则不返回。成功返回数据行时,会分配一块内存保存数据。buffer 参数必须为非 NULL*buffer 会被设置为指向所分配的内存;如果没有返回缓冲区,则设为 NULL。非 NULL 的结果缓冲区在不再需要时应使用 PQfreemem 释放。 - 在成功返回一行之后,返回的值就是该数据行里数据的字节数(将是大于零)。 - 被返回的字符串总是以零字节结尾,虽然这可能只是对文本COPY有用。 - 一个零结果表示该COPY仍然在处理中,但是还没有可用的行(只在async为真时才可能)。 - 一个 -1 结果表示COPY已经完成。-2 结果表示发生了错误(参考PQerrorMessage获取原因)。 + 成功返回一行时,返回值是该行的数据字节数,始终大于零。返回的字符串总是以零字节结尾,不过这可能仅对文本 COPY 有用。返回零表示 COPY 仍在进行,但尚无可用行(仅在 async 为真时可能发生)。返回 -1 表示 COPY 已完成;返回 -2 表示发生了错误(可用 PQerrorMessage 查看原因)。 - async 为真(非零)时,PQgetCopyData 不会阻塞等待输入;如果 COPY 仍在进行,但没有完整的行可用,则返回零。(这种情况下,应等待读就绪,随后先调用 PQconsumeInput,再调用 PQgetCopyData。)当 async 为假(零)时,PQgetCopyData 会阻塞,直到有数据可用或操作完成。 + + 当 async 为真(非零)时,PQgetCopyData 不会阻塞等待输入;如果 COPY 仍在进行,但没有完整行可用,则返回零。(此时,应等待读就绪,先调用 PQconsumeInput,再调用 PQgetCopyData。)当 async 为假(零)时,PQgetCopyData 会阻塞,直到数据可用或操作完成。 + - 在PQgetCopyData返回 -1 之后,调用PQgetResult获取COPY命令的最后结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 在 PQgetCopyData 返回 -1 后,调用 PQgetResult 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -3696,11 +3717,11 @@ int PQgetCopyData(PGconn *conn, - 用于<command>COPY</command>的废弃函数 + 用于<command>COPY</command>的过时函数 - 这些函数代表了以前的处理COPY的方法。尽管它们还能用,但是现在已经被废弃,因为它们的错误处理很糟糕、检测结束数据的方法也不方便,并且缺少对二进制或非阻塞传输的支持。 - + 这些函数使用较旧的方式处理 COPY。虽然仍然可用,但由于错误处理欠佳、检测数据结束的方式不便,而且缺少对二进制或非阻塞传输的支持,已被弃用。 + @@ -3708,7 +3729,7 @@ int PQgetCopyData(PGconn *conn, - 读取一个以新行终止的字符行到(由服务器传输) 到一个长度为length的字符串缓冲区。 + 将服务器传来的、以换行符结尾的一行字符读入大小为 length 的字符串缓冲区。 int PQgetline(PGconn *conn, char *buffer, @@ -3717,11 +3738,10 @@ int PQgetline(PGconn *conn, - 这个函数拷贝最多length-1 个字符到该缓冲区中,并且把终止的新行转换成一个零字节。 - PQgetline在输入结束时返回EOF,如果整行都被读取则返回 0,如果缓冲区填满了而还没有遇到结束的新行则返回 1。 - + 此函数最多将 length-1 个字符复制到缓冲区,并将末尾的换行符转换为零字节。PQgetline 在输入结束时返回 EOF,读完一整行时返回 0,缓冲区已满但尚未读到末尾换行符时返回 1。 + - 注意,应用必须检查是否一个新行包含两个字符\.,这表明服务器 已经完成了COPY命令的结果发送。如果应用可能收到超过length-1 字符长的行, 我们就应该确保正确识别\.行(例如,不要把一个长数据行的结束当作一个终止行)。 + 注意,应用程序必须检查新读入的一行是否仅由 \. 两个字符组成,这表示服务器已发送完 COPY 命令的结果。如果可能收到长度超过 length-1 个字符的行,必须确保正确识别 \. 行,例如不能把长数据行的末尾误当作终止行。 @@ -3731,7 +3751,7 @@ int PQgetline(PGconn *conn, - 不阻塞地读取一行COPY数据(由服务器传输)到一个缓冲区中。 + 以非阻塞方式将服务器传来的一行 COPY 数据读入缓冲区。 int PQgetlineAsync(PGconn *conn, char *buffer, @@ -3740,22 +3760,18 @@ int PQgetlineAsync(PGconn *conn, - 这个函数类似于PQgetline,但是可以被用于那些必须异步读取COPY数据的应用, 也就是不阻塞的应用。 - 在发出了COPY命令并得到了PGRES_COPY_OUT响应之后, - 应用应该调用PQconsumeInputPQgetlineAsync直到检测到结束数据的信号。 - + 此函数类似于 PQgetline,但可用于必须异步读取 COPY 数据的应用程序,即读取时不阻塞。发出 COPY 命令并收到 PGRES_COPY_OUT 响应后,应用程序应调用 PQconsumeInputPQgetlineAsync,直到检测到数据结束信号。 + - 不像PQgetline,这个函数负责检测结束数据。 + 与 PQgetline 不同,此函数会负责检测数据结束。 - 在每次调用时,如果libpq的输入缓冲区中有一个完整的数据行可用,PQgetlineAsync都将返回数据。 - 否则,在剩余行到达之前不会返回数据。如果识别到拷贝数据结束的标志,此函数返回 -1;如果没有可用数据则返回 0; - 或者返回一个正数,表示返回的数据字节数。如果返回 -1,调用者下一步必须调用PQendcopy,然后回到正常处理。 + 每次调用时,如果 libpq 的输入缓冲区中有完整数据行,PQgetlineAsync 就会返回数据;否则,要等该行剩余部分到达后才返回数据。识别到复制数据结束标记时返回 -1,没有可用数据时返回 0,否则返回正数,表示返回的数据字节数。返回 -1 后,调用者必须接着调用 PQendcopy,然后恢复正常处理。 - 返回的数据将不超过一个数据行的范围。如果可能,每次将返回一个完整行。但如果调用者提供的缓冲区太小不足以容下服务器发送的行,那么将返回部分行。对于文本数据,这可以通过测试返回的最后一个字节是否\n来检测(在二进制COPY中, 需要对COPY数据格式进行实际的分析,以便做相同的判断)。被返回的字符串不是空结尾的(如果你想增加一个终止空,确保传递一个比实际可用空间少一字节的bufsize)。 + 返回的数据不会跨越数据行边界。只要可能,每次就返回一整行;但如果调用者提供的缓冲区太小,容不下服务器发送的一行,则只返回部分行。对于文本数据,可检查最后返回的字节是否为 \n,以判断是否返回了完整行。(对于二进制 COPY,则必须实际解析 COPY 数据格式才能作出相同判断。)返回的字符串不以零字节结尾。(如果要自行添加末尾的零字节,务必将传入的 bufsize 设置为比实际可用空间少一字节。) @@ -3765,7 +3781,7 @@ int PQgetlineAsync(PGconn *conn, - 向服务器发送一个空终止的字符串。如果 OK 则返回 0;如果不能发送字符串则返回EOF。 + 向服务器发送以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputline(PGconn *conn, const char *string); @@ -3773,16 +3789,13 @@ int PQputline(PGconn *conn, - 一系列PQputline调用发送的COPY数据流和PQgetlineAsync返回的数据具有相同的格式, - 只是应用不需要每次PQputline调用中发送刚好一个数据行;在每次调用中发送多行或者部分行都是可以的。 + 连续调用 PQputline 发送的 COPY 数据流,与 PQgetlineAsync 返回的数据格式相同。不过,应用程序不必在每次 PQputline 调用中恰好发送一个数据行;每次发送部分行或多行也可以。 - 在PostgreSQL协议 3.0 之前,应用必须显式地发送两个字符\.作为最后一行来告知服务器应用程序已完成发送COPY数据。 - 虽然这么做仍然有效,但是它已经被废弃并且\.的特殊含义可能在将来的版本中删除。 - 在发送完实际数据之后, 调用PQendcopy就足够了。 - + 在 PostgreSQL 协议 3.0 之前,应用程序必须显式发送由 \. 两个字符组成的最后一行,告知服务器应用程序已发送完 COPY 数据。虽然这种方式仍然有效,但已被弃用,\. 的特殊含义预计会在未来版本中移除。发送完实际数据后,调用 PQendcopy 即可。 + @@ -3792,7 +3805,7 @@ int PQputline(PGconn *conn, - 向服务器发送一个非空终止的字符串。如果 OK 则返回 0,如果不能发送字符串则返回EOF。 + 向服务器发送不以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputnbytes(PGconn *conn, const char *buffer, @@ -3801,7 +3814,7 @@ int PQputnbytes(PGconn *conn, - 这个函数类似PQputline,除了数据缓冲区不需要以零字节结尾,因为要发送的字节数是直接指定的。在发送二进制数据时使用这个函数。 + 此函数与 PQputline 完全相同,只是直接指定了要发送的字节数,因此数据缓冲区不必以零字节结尾。发送二进制数据时可使用此函数。 @@ -3810,15 +3823,16 @@ int PQputnbytes(PGconn *conn, PQendcopy PQendcopy - 与服务器同步。 + + 与服务器同步。 + int PQendcopy(PGconn *conn); -此函数会等待服务器完成复制。调用时机应为:使用PQputline向服务器发送最后一个字符串后,或者使用PQgetline从服务器收到最后一个字符串后。必须调用此函数,否则服务器与客户端将会不同步。此函数返回后,服务器便准备好接收下一条 SQL 命令。成功完成时返回 0,否则返回非零值。(若返回非零值,可使用PQerrorMessage取得详细信息。) + +此函数会等待服务器完成复制。应在使用 PQputline 向服务器发送最后一个字符串后,或使用 PQgetline 从服务器接收最后一个字符串后调用它。必须调用此函数,否则服务器与客户端会失去同步。函数返回后,服务器便准备好接收下一条 SQL 命令。成功完成时返回 0,否则返回非零值。(返回非零值时,可用 PQerrorMessage 获取详细信息。) + - 在使用PQgetResult时,应用应该通过反复调用PQgetline并且在看到终止行后调用PQendcopy来响应PGRES_COPY_OUT结果。 - 然后它应该返回到PQgetResult循环直到PQgetResult返回一个空指针。 - 类似地,PGRES_COPY_IN结果会用一系列PQputline加上之后的PQendcopy来处理,然后返回到PQgetResult循环。 - 这样的安排将保证嵌入到一系列SQL命令中的COPY命令将被正确执行。 + 使用 PQgetResult 时,收到 PGRES_COPY_OUT 结果后,应用程序应反复调用 PQgetline,并在看到终止行后调用 PQendcopy。随后应回到 PQgetResult 循环,直到 PQgetResult 返回空指针。类似地,收到 PGRES_COPY_IN 结果后,应连续调用 PQputline,再调用 PQendcopy,然后回到 PQgetResult 循环。这样可以保证嵌在一系列 SQL 命令中的 COPY 命令正确执行。 @@ -3837,8 +3851,8 @@ int PQendcopy(PGconn *conn); 控制函数 - 这些函数控制libpq行为各种各样的细节。 - + 这些函数控制 libpq 行为的各种细节。 + @@ -3847,17 +3861,15 @@ int PQendcopy(PGconn *conn); - 返回客户端编码。 + 返回客户端编码。 int PQclientEncoding(const PGconn *conn); - - 请注意,它返回的是编码 ID,而不是一个符号串字符串,如EUC_JP。如果不成功,它会返回 -1。要把一个编码 ID 转换为为一个编码名称,可以用: - +注意,返回的是编码 ID,而不是 EUC_JP 这样的符号字符串。失败时返回 -1。要将编码 ID 转换为编码名称,可以使用: char *pg_encoding_to_char(int encoding_id); - + @@ -3878,7 +3890,8 @@ int PQsetClientEncoding(PGconn *conn, const char *PQsetErrorVerbosity PQsetErrorVerbosity - 设置以下函数所返回消息的详细程度:PQerrorMessagePQresultErrorMessage。 + + 设置 PQerrorMessagePQresultErrorMessage 所返回消息的详细程度。 typedef enum { @@ -3890,13 +3903,12 @@ typedef enum PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); - - PQsetErrorVerbosity设置详细程度模式,并返回该连接先前的设置。在TERSE模式下,返回的消息只包含严重级别、主要文本和位置;通常一行就能容纳。DEFAULT模式生成的消息除上述内容外,还包含所有的详细信息、提示或上下文字段(这些内容可能跨越多行)。VERBOSE模式包含所有可用字段。SQLSTATE模式仅包含错误严重级别,以及可用时的SQLSTATE错误代码(如果没有错误代码,则输出与TERSE模式相同)。 +PQsetErrorVerbosity 设置详细程度模式,并返回该连接先前的设置。在 TERSE 模式下,返回的消息只包含严重级别、主要文本和位置;通常一行就能容纳。DEFAULT 模式生成的消息除上述内容外,还包含所有详细信息、提示或上下文字段(这些内容可能跨越多行)。VERBOSE 模式包含所有可用字段。SQLSTATE 模式仅包含错误严重级别,以及可用时的 SQLSTATE 错误代码(如果没有错误代码,则输出与 TERSE 模式相同)。 + - 更改详细程度设置不会影响已存在的PGresult对象的可用的消息,只会影响随后创建的对象。 - (如果想要用不同的详细程度打印之前的错误,请见PQresultVerboseErrorMessage ) - + 更改详细程度设置不会影响从既有 PGresult 对象中取得的消息,只影响随后创建的对象。(如果希望以不同的详细程度打印之前的错误,请参见 PQresultVerboseErrorMessage。) + @@ -3904,7 +3916,8 @@ PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); PQsetErrorContextVisibility PQsetErrorContextVisibility - 确定对CONTEXT字段的处理方式,这些字段位于以下函数返回的消息中:PQerrorMessagePQresultErrorMessage。 + + 确定 PQerrorMessagePQresultErrorMessage 所返回消息中 CONTEXT 字段的处理方式。 typedef enum { @@ -3915,8 +3928,8 @@ typedef enum PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibility show_context); - - PQsetErrorContextVisibility设置上下文显示模式,并返回连接的先前设置。此模式控制消息中是否包含CONTEXT字段。NEVER模式从不包含CONTEXT,而ALWAYS在该字段可用时总是包含它。在ERRORS模式(默认)下,CONTEXT字段只包含在错误消息中,不包含在通知和警告中。(不过,如果详细程度设置为TERSESQLSTATECONTEXT字段都会被省略,无论上下文显示模式如何。) +PQsetErrorContextVisibility 设置上下文显示模式,并返回连接先前的设置。此模式控制消息中是否包含 CONTEXT 字段。NEVER 模式从不包含 CONTEXT,而 ALWAYS 模式在该字段可用时总是包含它。在 ERRORS 模式(默认)下,CONTEXT 字段只包含在错误消息中,不包含在通知和警告中。(不过,如果详细程度设置为 TERSESQLSTATE,则无论上下文显示模式如何,都会省略 CONTEXT 字段。) + 更改此模式不会影响从既有 PGresult 对象中取得的消息,只影响随后创建的对象。(如果希望使用不同的显示模式打印之前的错误,请参见 PQresultVerboseErrorMessage。) @@ -3927,16 +3940,16 @@ PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibilit - 启用对客户端/服务器通讯的跟踪,把跟踪信息输出到一个调试文件流中。 + 启用客户端/服务器通信跟踪,将跟踪信息写入调试文件流。 void PQtrace(PGconn *conn, FILE *stream); - + - 在 Windows上,如果libpq库和应用使用了不同的标志编译,那么这个函数调用会导致应用崩溃,因为FILE指针的内部表达是不一样的。特别是多线程/单线程、发布/调试 以及静态/动态标志应该是库和所有使用库的应用都一致。 + 在 Windows 上,如果 libpq 库与应用程序使用不同的标志编译,调用此函数会导致应用程序崩溃,因为 FILE 指针的内部表示不同。具体而言,库与所有使用它的应用程序都应使用相同的多线程/单线程、发布/调试和静态/动态标志。 @@ -3947,11 +3960,12 @@ void PQtrace(PGconn *conn, FILE *stream); PQuntrace PQuntrace - 禁用以下函数启动的跟踪:PQtrace。 + + 禁用由 PQtrace 启动的跟踪。 void PQuntrace(PGconn *conn); - + @@ -3978,11 +3992,8 @@ void PQfreemem(void *ptr); - 释放libpq分配的内存,尤其是PQescapeByteaConn,PQescapeBytea,PQunescapeBytea,和PQnotifies分配的内存。 - 特别重要的是,在微软 Windows 上使用这个函数,而不是free()。 - 这是因为只有 当 DLL 和应用的多线程/单线程、发布/调试以及静态/动态标志相同时,才能在一个 DLL 中分配内存并且在应用中释放它。 - 在非微软 Windows 平台上,这个函数与标准库函数free()相同。 - + 释放 libpq 分配的内存,特别是 PQescapeByteaConnPQescapeByteaPQunescapeByteaPQnotifies 分配的内存。在 Microsoft Windows 上,务必使用此函数,而不是 free()。这是因为只有 DLL 与应用程序使用相同的多线程/单线程、发布/调试和静态/动态标志,才能在 DLL 中分配内存并在应用程序中释放它。在 Microsoft Windows 以外的平台上,此函数与标准库函数 free() 相同。 + @@ -3990,7 +4001,8 @@ void PQfreemem(void *ptr); PQconninfoFree PQconninfoFree - 释放以下函数分配的数据结构:PQconndefaultsPQconninfoParse。 + + 释放PQconndefaultsPQconninfoParse分配的数据结构。 void PQconninfoFree(PQconninfoOption *connOptions); @@ -4034,10 +4046,13 @@ char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, PQencryptPassword PQencryptPassword - 准备经过 md5 加密的PostgreSQL密码。 + + 准备一个PostgreSQL密码的md5加密形式。 + char *PQencryptPassword(const char *passwd, const char *user); - PQencryptPassword是以下函数的旧版本,现已弃用:PQencryptPasswordConn。区别在于PQencryptPassword不需要连接对象,并且md5始终用作加密算法。 + PQencryptPasswordPQencryptPasswordConn的旧版本,现已弃用。其差别是PQencryptPassword不需要连接对象,并且总是用md5作为加密算法。 + @@ -4056,8 +4071,8 @@ PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); 这是libpq内部用于分配并初始化一个空PGresult对象的函数。 如果无法分配内存,此函数返回NULL。 将它导出供外部调用,是因为一些应用需要自行生成结果对象,特别是带有错误状态的对象。 - 如果conn非空,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 - 此外,如果conn非空,连接中注册的所有事件过程也会被复制到PGresult中。 + 如果conn 不为 null,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 + 此外,如果conn 不为 null,连接中注册的所有事件过程也会被复制到PGresult中。 (这些过程不会收到PGEVT_RESULTCREATE调用,但可参见PQfireResultCreateEvents。) 注意,最终应对该对象调用PQclear,就像处理libpq自身返回的PGresult一样。 @@ -4076,16 +4091,16 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); - conn参数被传送给事件过程,但不会被直接使用。如果事件过程不使用它,则会返回NULL。 - + conn 参数会传递给事件过程,但此函数不会直接使用它。如果事件过程不使用此参数,则可以传入 NULL。 + 已经接收到这个对象的PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件过程不会被再次触发。 - 这个函数与PQmakeEmptyPGresult分开的主要原因是在调用事件过程之前创建一个PGresult并且填充它常常是合适的。 - + 此函数与 PQmakeEmptyPGresult 分开的主要原因是,通常适合先创建 PGresult 并填充数据,然后再调用事件过程。 + @@ -4093,10 +4108,12 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); PQcopyResult PQcopyResult - 创建一个PGresult对象的副本。副本与源结果没有任何关联,并且PQclear必须在不再需要该副本时调用。如果函数失败,会返回NULL + + 创建 PGresult 对象的副本。副本与源结果没有任何关联,不再需要副本时必须调用 PQclear。函数失败时返回 NULL。 + PGresult *PQcopyResult(const PGresult *src, int flags); - + 这不是为了制作一个精确的副本。返回的结果总是放在PGRES_TUPLES_OK状态中,并且不复制源中的任何错误消息。 (但是会复制命令状态字符串。)flags参数确定要复制的其他内容。它是几个标志的按位或。 PG_COPYRES_ATTRS指定复制源结果的属性(列定义)。 PG_COPYRES_TUPLES指定复制源结果的元组。(这也意味着复制属性。) PG_COPYRES_NOTICEHOOKS指定复制源结果的通知钩子。 PG_COPYRES_EVENTS指定复制源结果的事件。(但不复制与源相关的任何实例数据。) @@ -4125,18 +4142,15 @@ int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs); - 设置一个PGresult对象的一个元组域值。 + 设置 PGresult 对象中某个元组的字段值。 int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len); - + - 这个函数将自动按需增加结果的内部元组数组。但是,tup_num参数必须小于等于PQntuples,意味着这个函数对元组数组一次只能增加一个元组。 - 但已存在的任意元组中的任意域可以以任意顺序进行调整。如果field_num的一个值已经存在,它会被覆盖。 - 如果len是 -1,或valueNULL, 该域值会被设置为一个 SQL 空值。 - value会被复制到结果的私有存储中,因此函数返回后就不再需要了。如果函数失败,返回值是 0。如果函数成功,返回值会是非 0。 - + 此函数会根据需要自动扩展结果内部的元组数组。不过,tup_num 参数必须小于或等于 PQntuples,也就是说,每次只能向元组数组增加一个元组。已有元组的任何字段都可以按任意顺序修改。如果 field_num 指定的位置已有值,该值会被覆盖。如果 len 为 -1 或 valueNULL,则将该字段设置为 SQL null 值。value 会被复制到结果的私有存储中,因此函数返回后就不再需要它。函数失败时返回零,成功时返回非零值。 + @@ -4153,8 +4167,8 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); - 当res被清除时,这个函数分配的内存也会被释放掉。如果函数失败,返回值是NULL。结果被保证为按照数据的任意类型充分地对齐,正如malloc所作的。 - + 使用此函数分配的所有内存都会在清除 res 时释放。函数失败时返回 NULL。与 malloc 一样,返回的内存保证满足任意数据类型的对齐要求。 + @@ -4163,15 +4177,15 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); - 检索为PGresult对象分配的字节数。 + 获取为 PGresult 对象分配的字节数。 size_t PQresultMemorySize(const PGresult *res); - + - 此值是与PGresult对象关联的所有malloc请求的总和,就是说,PQclear将释放的所有空间。此信息可用于管理内存消耗。 - + 此值是与 PGresult 对象相关的所有 malloc 请求所分配字节数的总和,即 PQclear 将释放的全部内存。这一信息有助于管理内存消耗。 + @@ -4187,28 +4201,25 @@ int PQlibVersion(void); - 在运行时,这个函数的结果可以被用来决定在当前已载入的 libpq 版本中特定的功能是否可用。 - 例如,这个函数可以被用来决定哪些选项可以被用于PQconnectdb。 - + 可在运行时根据此函数的结果,判断当前已加载的 libpq 版本是否具有特定功能。例如,可用它判断 PQconnectdb 支持哪些连接选项。 + - 结果通过将库的主版本号乘以10000再加上次版本号形成。例如,版本10.1将被返回为100001,而版本11.0将被返回为110000。 - + 返回值等于库的主版本号乘以 10000 再加上次版本号。例如,版本 10.1 返回 100001,版本 11.0 返回 110000。 + - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。 - 对于那些版本,PQlibVersion为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - + 在主版本 10 之前,PostgreSQL 使用由三个部分组成的版本号,前两个部分共同表示主版本。对于这些版本,PQlibVersion 用两位数字表示每个部分;例如,版本 9.1.5 返回 90105,版本 9.2.0 返回 90200。 + - 因此,出于判断特性兼容性的目的,应用应该将PQlibVersion的结果除以100而不是10000来判断逻辑的主版本号。 - 在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 - + 因此,为了判断功能兼容性,应用程序应将 PQlibVersion 的结果除以 100 而非 10000,得到逻辑上的主版本号。在所有版本系列中,次版本(错误修复版本)之间只有最后两位数字不同。 + - 这个函数出现于PostgreSQL版本 9.1,因此它不能被用来在早期的版本中检测所需的功能,因为调用它将会创建一个对版本9.1及其后版本的链接依赖。 + 此函数从 PostgreSQL 9.1 起提供,因而不能用它检测更早版本是否具有所需功能:调用它会建立对 9.1 或更高版本的链接依赖。 @@ -4222,13 +4233,13 @@ int PQlibVersion(void); 通知处理 - notice processing - in libpq + 通知处理 + 在 libpq 中 - 服务器产生的通知和警告消息不会被查询执行函数返回,因为它们不代表查询失败。它们可以被传递给一个通知处理函数,并且在处理者返回后执行会继续正常进行。默认的处理函数会把消息打印在stderr上,但是应用可以通过提供它自己的处理函数来重载这种行为。 - + 服务器生成的通知和警告消息不由查询执行函数返回,因为它们并不表示查询失败。这些消息会传递给通知处理函数,处理函数返回后,执行正常继续。默认通知处理函数将消息打印到 stderr,应用程序也可以提供自己的处理函数来替换这一行为。 + 由于历史原因,通知处理有两个级别,称为通知接收器和通知处理器。通知接收器的默认行为是格式化通知并且将一个字符串传递给通知处理器来打印。不过,如果一个应用选择提供自己的通知接收器,它通常会忽略通知处理器层并且在通知接收器中完成所有工作。 @@ -4236,10 +4247,10 @@ int PQlibVersion(void); 函数PQsetNoticeReceiver - notice receiver + 通知接收器 PQsetNoticeReceiver为一个连接对象设置或者检查当前的通知接收器。 相似地,PQsetNoticeProcessor - notice processor + 通知处理器 PQsetNoticeProcessor设置或检查当前的通知处理器。 @@ -4262,19 +4273,16 @@ PQsetNoticeProcessor(PGconn *conn, - 当接收到一个服务器产生的或者libpq内部产生的通知或警告消息,通知接收器函数会被调用。 - 该函数会以一种PGRES_NONFATAL_ERROR PGresult的形式接收该消息 - (这允许接收器使用PQresultErrorField抽取个别的域,或者使用PQresultErrorMessage或者PQresultVerboseErrorMessage得到一个完整的预格式化的消息)。 - 被传递给PQsetNoticeReceiver的同一个 void 指针也被传递(必要时,这个指针可以被用来访问应用相关的状态)。 - + 从服务器收到通知或警告消息,或者 libpq 内部生成这类消息时,便会调用通知接收器函数。消息以状态为 PGRES_NONFATAL_ERRORPGresult 对象传给该函数。(接收器可使用 PQresultErrorField 提取单个字段,也可使用 PQresultErrorMessagePQresultVerboseErrorMessage 获取完整的预格式化消息。)传给 PQsetNoticeReceiver 的同一个 void 指针也会传入。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知接收器会简单地抽取消息(使用PQresultErrorMessage)并且将它传递给通知处理器。 - 通知处理器负责处理一个以文本形式给出的通知或警告消息。该消息的字符串文本(包括一个收尾的新行)被传递给通知处理器,外加一个同时被传递给PQsetNoticeProcessor的空指针(必要时,这个指针可以被用来访问应用相关的状态)。 - + 通知处理器负责处理以文本形式提供的通知或警告消息。传给它的参数包括消息字符串(含末尾的换行符),以及先前传给 PQsetNoticeProcessor 的同一个 void 指针。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知处理器很简单: @@ -4288,9 +4296,8 @@ defaultNoticeProcessor(void *arg, const char *message) - 一旦你设定了一个通知接收器或处理器,你应该期待只要PGconn对象或者从它构造出的PGresult对象存在,该函数就可能被调用。 - 在一个PGresult创建时,PGconn的当前通知处理指针被复制到PGresult中,以备类似PQgetvalue的函数使用。 - + 设置通知接收器或处理器后,应当预期:只要 PGconn 对象或由它生成的 PGresult 对象仍存在,就可能调用该函数。创建 PGresult 时,会将 PGconn 当前的通知处理指针复制到 PGresult 中,供 PQgetvalue 等函数在需要时使用。 + @@ -4298,10 +4305,10 @@ defaultNoticeProcessor(void *arg, const char *message) 事件系统 - libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和毁灭。一种主要的使用情况是这允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 + libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和销毁。一个主要用途是允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 - 每个注册的事件处理程序都与两个数据相关联,libpq仅将其视为不透明的void *指针。 有一个透传指针,当事件处理程序与PGconn注册时,应用程序提供。 透传指针在PGconn及其生成的所有PGresult的生命周期内永远不会更改; 因此,如果使用,它必须指向长期存在的数据。 此外,还有一个实例数据指针,在每个PGconnPGresult中一开始都是NULL。 可以使用PQinstanceDataPQsetInstanceDataPQresultInstanceDataPQsetResultInstanceData函数来操作此指针。 请注意,与透传指针不同,PGconn的实例数据不会自动继承到从中创建的PGresultlibpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 —— 这是事件处理程序的责任。 + 每个注册的事件处理程序都与两项数据相关联,libpq仅将其视为不透明的void *指针。 有一个透传指针,由应用程序在向 PGconn 注册事件处理程序时提供。 透传指针在PGconn及其生成的所有PGresult的生命周期内永远不会更改; 因此,如果使用,它必须指向长期存在的数据。 此外,还有一个实例数据指针,在每个PGconnPGresult中一开始都是NULL。 可以使用PQinstanceDataPQsetInstanceDataPQresultInstanceDataPQresultSetInstanceData函数来操作此指针。 请注意,与透传指针不同,PGconn的实例数据不会自动继承到从中创建的PGresultlibpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 — 这是事件处理程序的责任。 事件类型 @@ -4314,7 +4321,7 @@ defaultNoticeProcessor(void *arg, const char *message) PGEVT_REGISTER - 注册事件在PQregisterEventProc被调用时触发。此时最适合初始化事件处理函数可能需要的instanceData。每个连接中的每个事件处理函数只会触发一次注册事件。如果事件处理函数失败,则中止注册。 + 注册事件在PQregisterEventProc被调用时触发。此时最适合初始化事件过程可能需要的instanceData。每个连接中的每个事件过程只会触发一次注册事件。如果事件过程失败,则中止注册。 typedef struct { PGconn *conn; @@ -4326,26 +4333,26 @@ typedef struct PGEVT_CONNRESET - 连接重置事件会在完成以下调用时触发:PQresetPQresetPoll。在这两种情况下,只有重置成功才会触发该事件。如果事件处理函数失败,整个连接重置就会失败;PGconn会被置于CONNECTION_BAD状态,并且PQresetPoll将返回PGRES_POLLING_FAILED。 + 连接重置事件会在完成以下调用时触发:PQresetPQresetPoll。在这两种情况下,只有重置成功才会触发该事件。如果事件过程失败,整个连接重置就会失败;PGconn会被置于CONNECTION_BAD状态,并且PQresetPoll将返回PGRES_POLLING_FAILED typedef struct { PGconn *conn; } PGEventConnReset; -收到PGEVT_CONNRESET事件时,应将evtInfo指针强制转换为PGEventConnReset *。虽然其中的PGconn刚刚被重置,但所有事件数据都保持不变。应利用此事件重置、重新加载或重新查询相关联的instanceData。注意,即使事件处理函数未能处理PGEVT_CONNRESET,它仍会在连接关闭时收到PGEVT_CONNDESTROY事件。 +收到PGEVT_CONNRESET事件时,应将evtInfo指针强制转换为PGEventConnReset *。虽然其中的PGconn刚刚被重置,但所有事件数据都保持不变。应利用此事件重置、重新加载或重新查询相关联的instanceData。注意,即使事件过程未能处理PGEVT_CONNRESET,它仍会在连接关闭时收到PGEVT_CONNDESTROY事件。 PGEVT_CONNDESTROY - 连接销毁事件由以下调用触发:PQfinish。事件处理函数负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 + 连接销毁事件由以下调用触发:PQfinish。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGconn *conn; } PGEventConnDestroy; -收到PGEVT_CONNDESTROY事件时,应将evtInfo指针强制转换为PGEventConnDestroy *。该事件触发于以下函数执行任何其他清理工作之前:PQfinish。事件处理函数的返回值会被忽略,因为无法通过以下函数报告失败:PQfinish。此外,事件处理函数失败不应中止清理不再使用的内存的过程。 +收到PGEVT_CONNDESTROY事件时,应将evtInfo指针强制转换为PGEventConnDestroy *。该事件触发于以下函数执行任何其他清理工作之前:PQfinish。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:PQfinish。此外,事件过程失败不应中止清理不再使用的内存的过程。 @@ -4377,32 +4384,32 @@ typedef struct PGEVT_RESULTCOPY - 结果复制事件会在调用PQcopyResult时触发。只有复制完成后才会触发该事件。只有为源结果成功处理过PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件处理函数,才会收到PGEVT_RESULTCOPY事件。 + 结果复制事件会在调用PQcopyResult时触发。只有复制完成后才会触发该事件。只有为源结果成功处理过PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件过程,才会收到PGEVT_RESULTCOPY事件。 typedef struct { const PGresult *src; PGresult *dest; } PGEventResultCopy; -收到PGEVT_RESULTCOPY事件时,应将evtInfo指针强制转换为PGEventResultCopy *。其中,src结果是复制源,而dest结果是复制目标。可以利用此事件对instanceData进行深复制,因为PQcopyResult无法完成这项工作。如果事件处理函数失败,整个复制操作就会失败,并且dest结果将被清除。返回失败代码时,必须完成所有清理工作,因为不会为目标结果发送PGEVT_RESULTDESTROY事件。 +收到PGEVT_RESULTCOPY事件时,应将evtInfo指针强制转换为PGEventResultCopy *。其中,src结果是复制源,而dest结果是复制目标。可以利用此事件对instanceData进行深复制,因为PQcopyResult无法完成这项工作。如果事件过程失败,整个复制操作就会失败,并且dest结果将被清除。返回失败代码时,必须完成所有清理工作,因为不会为目标结果发送PGEVT_RESULTDESTROY事件。 PGEVT_RESULTDESTROY - 结果销毁事件由以下调用触发:PQclear。事件处理函数负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 + 结果销毁事件由以下调用触发:PQclear。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGresult *result; } PGEventResultDestroy; -收到PGEVT_RESULTDESTROY事件时,应将evtInfo指针强制转换为PGEventResultDestroy *。该事件触发于以下函数执行任何其他清理工作之前:PQclear。事件处理函数的返回值会被忽略,因为无法通过以下函数报告失败:PQclear。此外,事件处理函数失败不应中止清理不再使用的内存的过程。 +收到PGEVT_RESULTDESTROY事件时,应将evtInfo指针强制转换为PGEventResultDestroy *。该事件触发于以下函数执行任何其他清理工作之前:PQclear。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:PQclear。此外,事件过程失败不应中止清理不再使用的内存的过程。 - 事件回调函数 + 事件回调过程 @@ -4410,9 +4417,12 @@ typedef struct - PGEventProc是通过 typedef 定义的事件处理函数指针类型,也就是接收 libpq 事件的用户回调函数的指针类型。事件处理函数的签名必须为 + PGEventProc 是通过 typedef 定义的事件过程指针类型,也就是接收 libpq 事件的用户回调函数的指针类型。事件过程的签名必须为: + int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) -其中,evtId参数指示发生了哪一种PGEVT事件。必须将evtInfo指针强制转换为适当的结构体类型,以获取关于该事件的更多信息。passThrough参数是在注册事件处理函数时传给以下函数的指针:PQregisterEventProc。函数应在成功时返回非零值,在失败时返回零。 + +evtId 参数指示发生了哪一种 PGEVT 事件。必须将 evtInfo 指针强制转换为适当的结构体类型,以获取关于该事件的更多信息。passThrough 参数是在注册事件过程时传给 PQregisterEventProc 的指针。函数应在成功时返回非零值,在失败时返回零。 + 在任何一个PGconn中,一个特定事件过程只能被注册一次。这是因为该过程的地址被用作查找键来标识相关的实例数据。 @@ -4421,8 +4431,8 @@ int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) - 在 Windows 上,函数能够有两个不同的地址:一个对 DLL 之外可见而另一个对 DLL 之内可见。我们应当小心只有其中之一会被用于libpq的事件过程函数,否则将会产生混淆。编写代码的最简单规则是将所有的事件过程声明为static。如果过程的地址必须对它自己的源代码文件之外可见,提供一个单独的函数来返回该地址。 - + 在 Windows 上,函数可能有两个不同的地址:一个在 DLL 外部可见,另一个在 DLL 内部可见。使用 libpq 的事件过程函数时,务必始终使用其中同一个地址,否则会产生混淆。确保代码正常工作的最简单做法,是将事件过程声明为 static。如果需要在过程所在的源文件之外取得其地址,应提供一个单独的函数来返回该地址。 + @@ -4448,7 +4458,7 @@ int PQregisterEventProc(PGconn *conn, PGEventProc proc, - 在每一个你想要接收事件的PGconn上必须注册一个事件过程。和内存不同,没有限制说一个连接上能注册多少个事件过程。如果该函数成功,它会返回一个非零值。如果它失败,则会返回零。 + 对于希望接收其事件的每个 PGconn,都必须注册一次事件过程。一个连接可注册的事件过程数量只受内存限制。函数成功时返回非零值,失败时返回零。 @@ -4488,14 +4498,15 @@ void *PQinstanceData(const PGconn *conn, PGEventProc proc); PQresultSetInstanceData PQresultSetInstanceData - 将结果的instanceData(针对proc)设置为data。成功时返回非零,失败时返回零。(只有当proc未在结果中正确注册时,才可能失败。) + + 将结果中针对 procinstanceData 设置为 data。成功时返回非零值,失败时返回零。(只有当 proc 未在结果中正确注册时,才可能失败。) + int PQresultSetInstanceData(PGresult *res, PGEventProc proc, void *data); - 请注意,data表示的任何存储都不会计入PQresultMemorySize,除非使用PQresultAlloc分配。 - (这样做是值得推荐的,因为它消除了在销毁结果时显式释放此类存储的需要。) + 注意,data 所指的存储不会计入 PQresultMemorySize,除非使用 PQresultAlloc 分配它。(推荐这样做,因为结果销毁时便不必显式释放这部分存储。) @@ -4517,18 +4528,18 @@ void *PQresultInstanceData(const PGresult *res, PGEventProc proc); - 事件实例 + 事件示例 - 这里是一个管理与 libpq 连接和结果相关的私有数据的示例的框架。 - + 下面给出一个示例框架,用于管理与 libpq 连接和结果关联的私有数据。 + -/* The instanceData */ +/* instanceData 数据 */ typedef struct { int n; @@ -4554,8 +4565,8 @@ main(void) return 1; } - /* called once on any connection that should receive events. - * Sends a PGEVT_REGISTER to myEventProc. + /* 在每个需要接收事件的连接上调用一次。 + * 向 myEventProc 发送 PGEVT_REGISTER 事件。 */ if (!PQregisterEventProc(conn, myEventProc, "mydata_proc", NULL)) { @@ -4564,28 +4575,28 @@ main(void) return 1; } - /* conn instanceData is available */ + /* 可以取得 conn 的 instanceData */ data = PQinstanceData(conn, myEventProc); - /* Sends a PGEVT_RESULTCREATE to myEventProc */ + /* 向 myEventProc 发送 PGEVT_RESULTCREATE 事件 */ res = PQexec(conn, "SELECT 1 + 1"); - /* result instanceData is available */ + /* 可以取得结果的 instanceData */ data = PQresultInstanceData(res, myEventProc); - /* If PG_COPYRES_EVENTS is used, sends a PGEVT_RESULTCOPY to myEventProc */ + /* 使用 PG_COPYRES_EVENTS 时,向 myEventProc 发送 PGEVT_RESULTCOPY 事件 */ res_copy = PQcopyResult(res, PG_COPYRES_TUPLES | PG_COPYRES_EVENTS); - /* result instanceData is available if PG_COPYRES_EVENTS was - * used during the PQcopyResult call. + /* 如果调用 PQcopyResult 时使用了 PG_COPYRES_EVENTS, + * 就可以取得结果的 instanceData。 */ data = PQresultInstanceData(res_copy, myEventProc); - /* Both clears send a PGEVT_RESULTDESTROY to myEventProc */ + /* 两次清除操作都会向 myEventProc 发送 PGEVT_RESULTDESTROY 事件 */ PQclear(res); PQclear(res_copy); - /* Sends a PGEVT_CONNDESTROY to myEventProc */ + /* 向 myEventProc 发送 PGEVT_CONNDESTROY 事件 */ PQfinish(conn); return 0; @@ -4601,7 +4612,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventRegister *e = (PGEventRegister *)evtInfo; mydata *data = get_mydata(e->conn); - /* associate app specific data with connection */ + /* 将应用程序特有的数据与连接关联 */ PQsetInstanceData(e->conn, myEventProc, data); break; } @@ -4621,7 +4632,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventConnDestroy *e = (PGEventConnDestroy *)evtInfo; mydata *data = PQinstanceData(e->conn, myEventProc); - /* free instance data because the conn is being destroyed */ + /* 连接正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; @@ -4633,8 +4644,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *conn_data = PQinstanceData(e->conn, myEventProc); mydata *res_data = dup_mydata(conn_data); - /* associate app specific data with result (copy it from conn) */ - PQsetResultInstanceData(e->result, myEventProc, res_data); + /* 将应用程序特有的数据与结果关联(从 conn 复制) */ + PQresultSetInstanceData(e->result, myEventProc, res_data); break; } @@ -4644,8 +4655,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *src_data = PQresultInstanceData(e->src, myEventProc); mydata *dest_data = dup_mydata(src_data); - /* associate app specific data with result (copy it from a result) */ - PQsetResultInstanceData(e->dest, myEventProc, dest_data); + /* 将应用程序特有的数据与结果关联(从另一个结果复制) */ + PQresultSetInstanceData(e->dest, myEventProc, dest_data); break; } @@ -4654,18 +4665,18 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventResultDestroy *e = (PGEventResultDestroy *)evtInfo; mydata *data = PQresultInstanceData(e->result, myEventProc); - /* free instance data because the result is being destroyed */ + /* 结果正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; } - /* unknown event ID, just return true. */ + /* 未知的事件 ID,直接返回 true。 */ default: break; } - return true; /* event processing succeeded */ + return true; /* 事件处理成功 */ } ]]> @@ -4679,7 +4690,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) 环境变量 - 以下环境变量可用于选择连接参数的默认值,供以下函数使用:PQconnectdbPQsetdbLoginPQsetdb,前提是调用代码没有直接指定这些参数的值。例如,这样可以避免在简单的客户端应用程序中硬编码数据库连接信息。 + + 以下环境变量可用于选择连接参数的默认值,供 PQconnectdbPQsetdbLoginPQsetdb 在调用代码未直接指定参数值时使用。例如,这样可以避免在简单的客户端应用程序中硬编码数据库连接信息。 + @@ -4776,9 +4789,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSERVICEFILE - PGSERVICEFILE指定每个用户的连接服务文件的名称 - (参见)。 - 默认为~/.pg_service.conf,或者在Microsoft Windows上为%APPDATA%\postgresql\.pg_service.conf。 + PGSERVICEFILE指定每个用户的连接服务文件的名称(参见)。 + 默认为~/.pg_service.conf,或者在 Microsoft Windows 上为%APPDATA%\postgresql\.pg_service.conf @@ -4823,7 +4835,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGREQUIRESSL的行为与连接参数相同。 - 这个环境变量已被弃用,推荐使用PGSSLMODE变量;设置这两个变量会抑制这个变量的效果。 + 这个环境变量已被弃用,推荐使用PGSSLMODE变量;同时设置这两个变量时,前者不再生效。 @@ -4961,7 +4973,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 以下环境变量可用于指定每个PostgreSQL会话的默认行为。(也可参见命令,了解按用户或按数据库设置默认行为的方法。) + + 以下环境变量可用于指定每个 PostgreSQL 会话的默认行为。(也可参见 命令,了解按用户或按数据库设置默认行为的方法。) + @@ -4988,7 +5002,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGGEQO为遗传查询优化器设置默认模式(等同于SET geqo TO ...)。 - 有关这些环境变量的正确取值,请参见SQL命令 + +有关这些环境变量的正确取值,请参见 SQL 命令 。 + 下面的环境变量决定libpq的内部行为,它们会覆盖编译在程序中的默认值。 @@ -5036,7 +5052,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) (可以复制上面这一行,并在行首加上#,在文件中加入提示注释。)前四个字段中的每一个都可以是字面值,或者是*,后者可以匹配任何内容。将使用与当前连接参数匹配的第一行中的密码字段。(因此,使用通配符时,应将更具体的条目放在前面。)如果条目需要包含:\,请使用\转义该字符。主机名字段首先匹配已指定的host连接参数;否则匹配已指定的hostaddr参数。如果两者都未指定,则查找主机名localhost。在以下情况下也会查找主机名localhost:连接使用 Unix 域套接字,且host参数与libpq的默认套接字目录路径匹配。在备库中,数据库字段为replication时,匹配连接到主库的流复制连接。除此之外,数据库字段的用途有限,因为同一用户在同一数据库集簇的所有数据库中使用相同的密码。 - 在 Unix 系统上,密码文件上的权限必须不允许所有人或组内访问,可以用chmod 0600 ~/.pgpass这样的命令实现。如果权限没有这么严格,该文件将被忽略。在微软 Windows 上,该文件被假定存储在一个安全的目录中,因此不会进行特别的权限检查。 + 在 Unix 系统上,密码文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.pgpass 这样的命令实现。如果权限没有这么严格,该文件将被忽略。在 Microsoft Windows 上,假定该文件存储在安全的目录中,因此不进行特殊的权限检查。 @@ -5058,10 +5074,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 连接服务文件允许 libpq 连接参数与一个单一服务名称关联。 - 那个服务名称可以在一个 libpq 连接字符串里面指定,与其相关的设置将被使用。 - 这允许在不重新编译使用 libpq 的应用的前提下修改连接参数。 - 服务名称也可以被使用PGSERVICE环境变量来指定。 + 连接服务文件允许将 libpq 连接参数与单个服务名称关联。随后可以在 libpq 连接字符串中指定该服务名称,从而使用关联的设置。这样便可以修改连接参数,而无需重新编译使用 libpq 的应用程序。也可以使用 PGSERVICE 环境变量指定服务名称。 @@ -5077,23 +5090,19 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 或者服务文件使用一种INI 文件格式,其中小节名是服务名并且参数是连接参数。 - 列表见。例如: + 两种服务文件均使用 INI 文件 格式,其中配置段名称是服务名称,参数是连接参数;参数列表见 。例如: -# comment +# 注释 [mydb] host=somehost port=5433 user=admin - 在PostgreSQL安装的share/pg_service.conf.sample中提供了一个示例文件。 +PostgreSQL 安装目录中的 share/pg_service.conf.sample 提供了一个示例文件。 - 从服务文件中获取的连接参数与从其他来源获取的参数相结合。 - 服务文件设置覆盖相应的环境变量,然后反过来可以由连接字符串中直接给出的值覆盖。 - 例如,使用上面的服务文件,连接字符串service=mydb port=5434将使用主机somehost,端口5434, - 用户admin,以及由环境变量或内置默认所设置的其他参数。 + 从服务文件中获取的连接参数会与其他来源的参数合并。服务文件中的设置会覆盖相应的环境变量,而连接字符串中直接给出的值又会覆盖服务文件中的设置。例如,使用上述服务文件时,连接字符串 service=mydb port=5434 将使用主机 somehost、端口 5434、用户 admin,以及由环境变量或内置默认值设置的其他参数。 @@ -5136,7 +5145,7 @@ ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase) 你也可以将常规的服务文件条目和 LDAP 查找混合。pg_service.conf中一节的完整示例: -# 只有主机和端口存储在LDAP中,显式指定dbname和user。 +# 仅 host 和 port 存储在 LDAP 中;显式指定 dbname 和 user [customerdb] dbname=customer user=appuser @@ -5161,13 +5170,13 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 服务器证书的客户端验证 + 客户端对服务器证书的验证 - 默认情况下,PostgreSQL将不会执行服务器证书的任何验证。这意味着可以在不被客户端知晓的情况下伪造服务器身份(例如通过修改一个 DNS 记录或者接管服务器的 IP 地址)。为了阻止哄骗,客户端必须能够通过一条信任链验证服务器的身份。信任链可以这样建立:在一台计算机上放置一个根(自签名的)证书机构(CA)的证书并且在另一台计算机上放置一个由根证书签发的叶子证书。还可以使用一种中间证书,它由根证书签发并且可以签发叶子证书。 + 默认情况下,PostgreSQL 不会对服务器证书执行任何验证。这意味着可以在客户端不知情的情况下伪造服务器身份,例如修改 DNS 记录或接管服务器的 IP 地址。要防止身份伪造,客户端必须能够通过信任链验证服务器身份。建立信任链的方法是:在一台计算机上放置根证书机构(CA)的自签名证书,在另一台计算机上放置由根证书签发的叶证书。也可以使用由根证书签发、又用于签发叶证书的中间证书。 - 要让客户端验证服务器的身份,请在客户端放置根证书,并在服务器上放置由该根证书签名的叶证书。要让服务器验证客户端的身份,请在服务器上放置根证书,并在客户端放置由该根证书签名的叶证书。也可以使用一个或多个中间证书(通常与叶证书存储在一起),将叶证书链接到根证书。 + 要让客户端验证服务器的身份,请在客户端放置根证书,并在服务器上放置由该根证书签发的叶证书。要让服务器验证客户端的身份,请在服务器上放置根证书,并在客户端放置由该根证书签发的叶证书。也可以使用一个或多个中间证书(通常与叶证书存储在一起),将叶证书链接到根证书。 建立信任链后,客户端可以通过两种方式验证服务器发送的叶证书。如果参数 sslmode 设为 verify-ca,libpq 会沿证书链检查到存储在客户端上的根证书,以验证服务器是否可信。如果 sslmode 设为 verify-full,libpq 还会验证服务器主机名是否与服务器证书中存储的名称匹配。如果无法验证服务器证书,SSL 连接将失败。在大多数对安全敏感的环境中,建议使用 verify-full @@ -5186,8 +5195,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 为了与 PostgreSQL 的早期版本达到向后兼容,如果存在一个根 CA 文件,sslmode=require的行为将与verify-ca相同,即服务器证书根据 CA 验证。我们鼓励依赖这种行为,并且需要证书验证的应用应该总是使用verify-ca或者verify-full。 - + 为与 PostgreSQL 的早期版本向后兼容,如果存在根 CA 文件,sslmode=require 的行为将与 verify-ca 相同,即根据 CA 验证服务器证书。不建议依赖这种行为;需要证书验证的应用程序应始终使用 verify-caverify-full。 + @@ -5195,40 +5204,28 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 客户端证书 - 如果服务器尝试通过请求客户端的叶证书来验证客户端的身份, - libpq将发送存储在文件 - ~/.postgresql/postgresql.crt中的证书,该文件位于用户的主目录中。 - 证书必须链到服务器信任的根证书。匹配的 - 私钥文件~/.postgresql/postgresql.key也必须存在。 - 在Microsoft Windows上,这些文件的名称分别为 - %APPDATA%\postgresql\postgresql.crt和 - %APPDATA%\postgresql\postgresql.key。 - 证书和密钥文件的位置可以通过连接参数 - sslcertsslkey, - 或通过环境变量PGSSLCERTPGSSLKEY来覆盖。 - + 如果服务器请求客户端的叶证书以验证客户端身份,libpq 将发送用户主目录下 ~/.postgresql/postgresql.crt 文件中存储的证书。这些证书必须通过证书链连接到服务器信任的根证书。还必须存在匹配的私钥文件 ~/.postgresql/postgresql.key。在 Microsoft Windows 上,这两个文件分别名为 %APPDATA%\postgresql\postgresql.crt%APPDATA%\postgresql\postgresql.key。可以通过连接参数 sslcertsslkey,或环境变量 PGSSLCERTPGSSLKEY,覆盖证书和密钥文件的位置。 + - 在Unix系统上,私钥文件的权限必须禁止任何对世界或组的访问;可以通过类似以下命令来实现: - chmod 0600 ~/.postgresql/postgresql.key。 - 或者,该文件可以由root拥有并具有组读取权限(即0640权限)。 - 该设置适用于由操作系统管理证书和密钥文件的安装。然后,libpq的用户应该成为具有对这些证书和密钥文件访问权限的组的成员。 - (在Microsoft Windows上,没有文件权限检查,因为假定%APPDATA%\postgresql目录是安全的。) - + 在 Unix 系统上,私钥文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.postgresql/postgresql.key 这样的命令实现。另一种做法是使文件归 root 所有,并允许组用户读取(即 0640 权限)。这种设置适用于由操作系统管理证书和密钥文件的安装环境。此时,应将 libpq 用户加入有权访问这些证书和密钥文件的组。(在 Microsoft Windows 上,不检查文件权限,因为假定 %APPDATA%\postgresql 目录是安全的。) + postgresql.crt中的第一个证书必须是客户端的证书,因为它必须匹配客户端的私钥。可以选择将中间证书追加到该文件 — 这样做避免了在服务器上存放中间证书的要求()。 - 创建证书的指令请参考。 + 有关创建证书的说明,请参见 不同模式中提供的保护 - sslmode参数选择不同的值可以提供不同程度的保护。SSL 可以防范三类攻击: + + sslmode 参数的不同值提供不同级别的保护。SSL 可以防范三类攻击: + 窃听 @@ -5240,31 +5237,33 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 中间人(MITM - 如果一个第三方能对客户端和服务器之间传送的数据进行修改,它就能假装是服务器并且因此能看见并且修改数据,即使这些数据已被加密。然后第三方可以将连接信息和数据转送给原来的服务器,使得它不可能检测到攻击。这样做的通常途径包括 DNS 污染和地址劫持,借此客户端被重定向到一个不同的服务器。还有几种其他的攻击方式能够完成这种攻击。SSL使用证书验证让客户端认证服务器,就可以阻止这种攻击。 - + + 如果第三方能修改客户端与服务器之间传输的数据,就可以冒充服务器,进而查看和修改数据,即使数据已经加密。随后,第三方可以将连接信息和数据转发给原来的服务器,使攻击无法被察觉。常见的手段包括 DNS 污染和地址劫持,从而将客户端引向预期之外的服务器。还有其他几种攻击手段可以达到同样的目的。SSL 使用证书验证,让客户端认证服务器身份,以防范这种攻击。 + - 模仿 + 冒充 - 如果一个第三方能假装是一个授权的客户端,它能够简单地访问它本不能访问的数据。通常这可以由不安全的密码管理所致。SSL使用客户端证书来确保只有持有合法证书的客户端才能访问服务器,这样就能阻止这种攻击。 - + + 如果第三方能冒充获授权的客户端,就能直接访问其无权访问的数据。这通常可能由不安全的密码管理导致。SSL 使用客户端证书,确保只有持有有效证书的客户端才能访问服务器,以防范这种攻击。 + - 对于一个已知受 SSL 保护的连接,在连接建立之前,必须在客户端和服务器两端都配置 SSL。如果只在服务器端配置,客户端在得知服务器要求高安全性之前,可能就已经开始发送敏感信息(例如密码)。在 libpq 中,要确保连接安全,可以把sslmode参数设置为verify-fullverify-ca,并为系统提供一个用于验证的根证书。这类似于使用https URL浏览加密网页。 + 要确保连接受到 SSL 保护,必须在建立连接之前,在客户端和服务器两端配置 SSL。如果仅在服务器上配置,客户端可能在得知服务器要求高安全性之前就已发送敏感信息(例如密码)。在 libpq 中,可以将 sslmode 参数设为 verify-fullverify-ca,并向系统提供用于验证的根证书,以确保连接安全。这类似于使用 https URL 进行加密的网页浏览。 - 一旦服务器已经被认证,客户端可以传递敏感数据。这意味着直到这一点,客户端都不需要知道是否证书将被用于认证,这样只需要在服务器配置中指定就比较安全。 + 服务器通过身份认证后,客户端便可以传送敏感数据。这意味着,在此之前,客户端无需知道是否会使用证书进行认证,因此可以安全地仅在服务器配置中指定这一点。 - 所有SSL选项都带来了加密和密钥交换的负荷,因此必须在性能和安全性之间做出平衡。不同sslmode值所保护的风险,以及它们是怎样看待安全性和负荷的。 + 所有 SSL 选项都会产生加密和密钥交换的开销,因此必须在性能与安全性之间作出权衡。 说明了不同 sslmode 值所能防范的风险,以及它们所表达的对安全性和开销的取舍。
@@ -5285,7 +5284,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) disable - 我不关心安全性,并且我不想为加密增加负荷。 + 我不关心安全性,并且我不想为加密增加开销。 @@ -5293,7 +5292,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) allow 可能 - 我不关心安全性,但如果服务器坚持,我将承担加密带来的负荷。 + 我不关心安全性,但如果服务器坚持,我将承担加密带来的开销。 @@ -5301,7 +5300,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) prefer 可能 - 我不关心安全性,但如果服务器支持,我希望承担加密带来的负荷。 + 我不关心加密,但如果服务器支持,我希望承担加密带来的开销。 @@ -5309,7 +5308,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) require - 我想要对数据加密,并且我接受因此带来的负荷。我信任该网络会保证我总是连接到想要连接的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我信任该网络会保证我总是连接到想要连接的服务器。 @@ -5317,7 +5316,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-ca 取决于 CA 策略 - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器。 @@ -5325,7 +5324,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-full - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 @@ -5338,7 +5337,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - sslmode的默认值是prefer。如表中所示,这在安全性的角度来说没有意义,并且它只承诺可能的性能负荷。提供它作为默认值只是为了向后兼容,并且我们不推荐在安全部署中使用它。 + sslmode 的默认值是 prefer。如表所示,从安全角度看,这一设置没有意义;它只会在可能时带来性能开销。将其作为默认值仅出于向后兼容的考虑,不建议在有安全要求的部署中使用。 @@ -5380,8 +5379,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) ~/.postgresql/root.crt - 可信的证书机构 - 检查服务器证书是由一个可信的证书机构签发 + 受信任的证书机构 + 检查服务器证书是由一个受信任的证书机构签发 @@ -5399,9 +5398,9 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) SSL 库初始化 - 如果您的应用程序初始化libssl和/或libcrypto库,并且libpq - 构建时带有SSL支持,您应该调用PQinitOpenSSL告诉libpq - libssl和/或libcrypto库已被您的应用程序初始化,以便 + 如果你的应用程序初始化libssl和/或libcrypto库,并且libpq + 构建时带有SSL支持,你应该调用PQinitOpenSSL告诉libpq + libssl和/或libcrypto库已被你的应用程序初始化,以便 libpq不会再初始化这些库。 但是,当使用OpenSSL版本1.1.0或更高版本时,无需这样做,因为重复初始化不再成问题。 @@ -5413,7 +5412,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 允许应用选择要初始化哪个安全性库。 + 允许应用程序选择要初始化的安全库。 void PQinitOpenSSL(int do_ssl, int do_crypto); @@ -5438,7 +5437,7 @@ void PQinitOpenSSL(int do_ssl, int do_crypto); - 允许应用选择要初始化哪个安全性库。 + 允许应用程序选择要初始化的安全库。 void PQinitSSL(int do_ssl); @@ -5463,7 +5462,7 @@ void PQinitSSL(int do_ssl); - 在线程化程序中的行为 + 多线程程序中的行为 线程 @@ -5497,7 +5496,9 @@ int PQisthreadsafe(); PGresult对象在创建后通常是只读的,因此可以在线程之间自由传递。不过,如果你使用中描述的任何会修改PGresult的函数,则需要自行避免对同一个PGresult执行并发操作。 - 已弃用的 PQrequestCancelPQoidStatus 函数不是线程安全的,不应在多线程程序中使用。可以用 PQcancel 替代 PQrequestCancel,用 PQoidValue 替代 PQoidStatus + + 已弃用的函数 PQrequestCancelPQoidStatus 不是线程安全的,不应在多线程程序中使用。PQrequestCancel 可以用 PQcancel 替代;PQoidStatus 可以用 PQoidValue 替代。 + 如果你在应用程序中使用 Kerberos(除了libpq内部之外),则需要在 Kerberos 调用周围加锁,因为 Kerberos 函数不是线程安全的。可参考libpq源代码中的PQregisterThreadLock函数,它提供了一种在libpq与应用程序之间协作加锁的方法。 @@ -5507,7 +5508,7 @@ int PQisthreadsafe(); - 编译 <application>libpq</application> 程序 + 构建 <application>libpq</application> 程序 编译 @@ -5515,16 +5516,16 @@ int PQisthreadsafe(); - 要编译(即编译并且链接)一个使用libpq的程序,你需要做下列所有的事情: + 要构建(即编译和链接)一个使用 libpq 的程序,需要完成以下所有步骤: - 包括libpq-fe.h头文件: + 包含 libpq-fe.h 头文件: #include <libpq-fe.h> - 如果你无法这样做,那么你通常会从你的编译器得到像这样的错误消息: +如果没有这样做,编译器通常会给出类似以下内容的错误消息: foo.c: In function `main': foo.c:34: `PGconn' undeclared (first use in this function) @@ -5533,24 +5534,24 @@ foo.c:54: `CONNECTION_BAD' undeclared (first use in this function) foo.c:68: `PGRES_COMMAND_OK' undeclared (first use in this function) foo.c:95: `PGRES_TUPLES_OK' undeclared (first use in this function) - + - 通过为你的编译器提供-Idirectory选项,向你的编译器指出PostgreSQL头文件安装在哪里(在某些情况下编译器默认将查看该目录,因此你可以忽略这个选项)。例如你的编译命令行可能看起来像: + 向编译器提供 -Idirectory 选项,指定 PostgreSQL 头文件的安装目录。(某些情况下,编译器默认会搜索该目录,此时可以省略这个选项。)例如,编译命令行可以是: cc -c -I/usr/local/pgsql/include testprog.c - 如果你在使用 makefile,那么把该选项加到CPPFLAGS变量中: +如果使用 makefile,请将该选项添加到 CPPFLAGS 变量中: CPPFLAGS += -I/usr/local/pgsql/include - + 如果你的程序可能由其他用户编译,那么你不应该像那样硬编码目录位置。你可以运行工具pg_configpg_configwith libpq在本地系统上找出头文件在哪里: + sortas="libpq">用于 libpq在本地系统上找出头文件在哪里: $ pg_config --includedir /usr/local/include @@ -5558,8 +5559,7 @@ CPPFLAGS += -I/usr/local/pgsql/include - 如果你安装了pkg-configpkg-configwith - libpq,你可以运行: + 如果你安装了pkg-configpkg-config用于 libpq,你可以运行: $ pkg-config --cflags libpq -I/usr/local/include @@ -5568,20 +5568,20 @@ CPPFLAGS += -I/usr/local/pgsql/include - 无法为编译器指定正确的选项将导致一个错误消息,例如: + 未向编译器指定正确的选项将导致类似以下内容的错误消息: testlibpq.c:8:22: libpq-fe.h: No such file or directory - + - 当链接最终的程序时,指定选项-lpq,这样libpq库会被编译进去,也可以用选项-Ldirectory向编译器指出libpq库所在的位置(再次,编译器将默认搜索某些目录)。为了最大的可移植性,将选项放在选项前面。例如: + 链接最终程序时,指定 -lpq 选项以链接 libpq 库,同时指定 -Ldirectory 选项,告知编译器 libpq 库所在的目录。(同样,编译器默认会搜索某些目录。)为获得最大的可移植性,请将 选项放在 选项之前。例如: cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq - + 你也可以使用pg_config找出库目录: @@ -5608,7 +5608,7 @@ testlibpq.o(.text+0x60): undefined reference to `PQsetdbLogin' testlibpq.o(.text+0x71): undefined reference to `PQstatus' testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' - 这意味着你忘了 . + 这意味着你忘记了 /usr/bin/ld: cannot find -lpq @@ -5625,7 +5625,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' 示例程序 - 这些示例和其他示例可以在源代码发布的src/test/examples目录中找到。 + 这些示例和其他示例可在源代码发行包的src/test/examples目录中找到。 @@ -5639,7 +5639,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' * * testlibpq.c * - * Test the C version of libpq, the PostgreSQL frontend library. + * 测试 PostgreSQL 前端库 libpq 的 C 语言版本。 */ #include #include @@ -5663,19 +5663,18 @@ main(int argc, char **argv) j; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "Connection to database failed: %s", @@ -5683,7 +5682,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -5694,19 +5693,17 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Our test case here involves using a cursor, for which we must be inside - * a transaction block. We could do the whole thing with a single - * PQexec() of "select * from pg_database", but that's too trivial to make - * a good example. + * 这里的测试用例使用游标,因此必须处于事务块内。 + * 只需调用一次 PQexec() 执行 "select * from pg_database" 就能完成全部操作, + * 但这太简单了,不足以作为一个好的示例。 */ - /* Start a transaction block */ + /* 开始一个事务块 */ res = PQexec(conn, "BEGIN"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -5717,7 +5714,7 @@ main(int argc, char **argv) PQclear(res); /* - * Fetch rows from pg_database, the system catalog of databases + * 从数据库系统目录 pg_database 中获取行 */ res = PQexec(conn, "DECLARE myportal CURSOR FOR select * from pg_database"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -5736,13 +5733,13 @@ main(int argc, char **argv) exit_nicely(conn); } - /* first, print out the attribute names */ + /* 首先,打印属性名 */ nFields = PQnfields(res); for (i = 0; i < nFields; i++) printf("%-15s", PQfname(res, i)); printf("\n\n"); - /* next, print out the rows */ + /* 接着,打印各行 */ for (i = 0; i < PQntuples(res); i++) { for (j = 0; j < nFields; j++) @@ -5752,15 +5749,15 @@ main(int argc, char **argv) PQclear(res); - /* close the portal ... we don't bother to check for errors ... */ + /* 关闭 portal……这里不再检查错误…… */ res = PQexec(conn, "CLOSE myportal"); PQclear(res); - /* end the transaction */ + /* 结束事务 */ res = PQexec(conn, "END"); PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -5779,15 +5776,15 @@ main(int argc, char **argv) * * * testlibpq2.c - * Test of the asynchronous notification interface + * 测试异步通知接口 * - * Start this program, then from psql in another window do + * 启动此程序,然后在另一个窗口中通过 psql 执行 * NOTIFY TBL2; - * Repeat four times to get this program to exit. + * 重复四次后,此程序便会退出。 * - * Or, if you want to get fancy, try this: - * populate a database with the following commands - * (provided in src/test/examples/testlibpq2.sql): + * 或者,可以尝试更复杂的示例: + * 使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq2.sql 中): * * CREATE SCHEMA TESTLIBPQ2; * SET search_path = TESTLIBPQ2; @@ -5796,7 +5793,7 @@ main(int argc, char **argv) * CREATE RULE r1 AS ON INSERT TO TBL1 DO * (INSERT INTO TBL2 VALUES (new.i); NOTIFY TBL2); * - * Start this program, then from psql do this four times: + * 启动此程序,然后通过 psql 将以下命令执行四次: * * INSERT INTO TESTLIBPQ2.TBL1 VALUES (10); */ @@ -5833,19 +5830,18 @@ main(int argc, char **argv) int nnotifies; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "Connection to database failed: %s", @@ -5853,7 +5849,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -5864,13 +5860,12 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Issue LISTEN command to enable notifications from the rule's NOTIFY. + * 发出 LISTEN 命令,以接收规则中的 NOTIFY 发出的通知。 */ res = PQexec(conn, "LISTEN TBL2"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -5881,14 +5876,13 @@ main(int argc, char **argv) } PQclear(res); - /* Quit after four notifies are received. */ + /* 收到四次通知后退出。 */ nnotifies = 0; while (nnotifies < 4) { /* - * Sleep until something happens on the connection. We use select(2) - * to wait for input, but you could also use poll() or similar - * facilities. + * 休眠,直到连接上有事件发生。这里使用 select(2) 等待输入, + * 也可以使用 poll() 或类似机制。 */ int sock; fd_set input_mask; @@ -5896,7 +5890,7 @@ main(int argc, char **argv) sock = PQsocket(conn); if (sock < 0) - break; /* shouldn't happen */ + break; /* 不应发生 */ FD_ZERO(&input_mask); FD_SET(sock, &input_mask); @@ -5907,7 +5901,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Now check for input */ + /* 现在检查是否有输入 */ PQconsumeInput(conn); while ((notify = PQnotifies(conn)) != NULL) { @@ -5922,7 +5916,7 @@ main(int argc, char **argv) fprintf(stderr, "Done.\n"); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -5941,10 +5935,10 @@ main(int argc, char **argv) * * * testlibpq3.c - * Test out-of-line parameters and binary I/O. + * 测试在 SQL 命令文本之外独立传递的参数和二进制 I/O。 * - * Before running this, populate a database with the following commands - * (provided in src/test/examples/testlibpq3.sql): + * 运行前,使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq3.sql 中): * * CREATE SCHEMA testlibpq3; * SET search_path = testlibpq3; @@ -5952,7 +5946,7 @@ main(int argc, char **argv) * INSERT INTO test1 values (1, 'joe''s place', '\\000\\001\\002\\003\\004'); * INSERT INTO test1 values (2, 'ho there', '\\004\\003\\002\\001\\000'); * - * The expected output is: + * 预期输出为: * * tuple 0: got * i = (4 bytes) 1 @@ -5976,7 +5970,7 @@ main(int argc, char **argv) #include #include "libpq-fe.h" -/* for ntohl/htonl */ +/* 用于 ntohl/htonl */ #include #include @@ -5989,9 +5983,8 @@ exit_nicely(PGconn *conn) } /* - * This function prints a query result that is a binary-format fetch from - * a table defined as in the comment above. We split it out because the - * main() function uses it twice. + * 此函数打印从上面注释所定义的表中以二进制格式获取的查询结果。 + * 由于 main() 会使用它两次,因此将它单独提取成一个函数。 */ static void show_binary_results(PGresult *res) @@ -6002,7 +5995,7 @@ show_binary_results(PGresult *res) t_fnum, b_fnum; - /* Use PQfnumber to avoid assumptions about field order in result */ + /* 使用 PQfnumber,以避免对结果中的字段顺序作出假设 */ i_fnum = PQfnumber(res, "i"); t_fnum = PQfnumber(res, "t"); b_fnum = PQfnumber(res, "b"); @@ -6015,24 +6008,22 @@ show_binary_results(PGresult *res) int blen; int ival; - /* Get the field values (we ignore possibility they are null!) */ + /* 获取字段值(这里忽略它们可能为 null 的情况!) */ iptr = PQgetvalue(res, i, i_fnum); tptr = PQgetvalue(res, i, t_fnum); bptr = PQgetvalue(res, i, b_fnum); /* - * The binary representation of INT4 is in network byte order, which - * we'd better coerce to the local byte order. + * INT4 的二进制表示采用网络字节序,最好将其转换为本机字节序。 */ ival = ntohl(*((uint32_t *) iptr)); /* - * The binary representation of TEXT is, well, text, and since libpq - * was nice enough to append a zero byte to it, it'll work just fine - * as a C string. + * TEXT 的二进制表示就是文本,而 libpq 会在其后追加一个零字节, + * 因此可以直接将其用作 C 字符串。 * - * The binary representation of BYTEA is a bunch of bytes, which could - * include embedded nulls so we have to pay attention to field length. + * BYTEA 的二进制表示是一组字节,其中可能嵌有零字节, + * 因此必须注意字段长度。 */ blen = PQgetlength(res, i, b_fnum); @@ -6060,19 +6051,18 @@ main(int argc, char **argv) uint32_t binaryIntVal; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "Connection to database failed: %s", @@ -6080,7 +6070,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SET search_path = testlibpq3"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -6091,27 +6081,25 @@ main(int argc, char **argv) PQclear(res); /* - * The point of this program is to illustrate use of PQexecParams() with - * out-of-line parameters, as well as binary transmission of data. + * 此程序旨在演示如何使用 PQexecParams() 在 SQL 命令文本之外独立传递参数, + * 以及如何以二进制方式传输数据。 * - * This first example transmits the parameters as text, but receives the - * results in binary format. By using out-of-line parameters we can avoid - * a lot of tedious mucking about with quoting and escaping, even though - * the data is text. Notice how we don't have to do anything special with - * the quote mark in the parameter value. + * 第一个示例以文本形式传输参数,但以二进制格式接收结果。 + * 通过在 SQL 命令文本之外独立传递参数,即使数据是文本,也可以避免 + * 许多繁琐的引号和转义处理。注意,参数值中的引号无需任何特殊处理。 */ - /* Here is our out-of-line parameter value */ + /* 这是在 SQL 命令文本之外独立传递的参数值 */ paramValues[0] = "joe's place"; res = PQexecParams(conn, "SELECT * FROM test1 WHERE t = $1", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, - NULL, /* don't need param lengths since text */ - NULL, /* default to all text params */ - 1); /* ask for binary results */ + NULL, /* 文本参数无需指定长度 */ + NULL, /* 默认所有参数均为文本 */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -6125,31 +6113,29 @@ main(int argc, char **argv) PQclear(res); /* - * In this second example we transmit an integer parameter in binary form, - * and again retrieve the results in binary form. + * 第二个示例以二进制形式传输一个整数参数,并同样以二进制形式获取结果。 * - * Although we tell PQexecParams we are letting the backend deduce - * parameter type, we really force the decision by casting the parameter - * symbol in the query text. This is a good safety measure when sending - * binary parameters. + * 虽然我们告诉 PQexecParams 让后端推断参数类型,但实际上, + * 查询文本中的参数符号经过强制类型转换,因此其类型已经确定。 + * 发送二进制参数时,这是一项良好的安全措施。 */ - /* Convert integer value "2" to network byte order */ + /* 将整数值 "2" 转换为网络字节序 */ binaryIntVal = htonl((uint32_t) 2); - /* Set up parameter arrays for PQexecParams */ + /* 为 PQexecParams 设置参数数组 */ paramValues[0] = (char *) &binaryIntVal; paramLengths[0] = sizeof(binaryIntVal); - paramFormats[0] = 1; /* binary */ + paramFormats[0] = 1; /* 二进制 */ res = PQexecParams(conn, "SELECT * FROM test1 WHERE i = $1::int4", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, paramLengths, paramFormats, - 1); /* ask for binary results */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -6162,7 +6148,7 @@ main(int argc, char **argv) PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; diff --git a/zh/12/lobj.sgml b/zh/12/lobj.sgml index e184d342..0e71a962 100644 --- a/zh/12/lobj.sgml +++ b/zh/12/lobj.sgml @@ -3,8 +3,8 @@ 大对象 - large object - BLOBlarge object + 大对象 + BLOB大对象 PostgreSQL提供一种大对象机制,允许以流式方式访问存储在专用大对象结构中的用户数据。在处理大到无法方便地整体操作的数据值时,这种流式访问非常有用。 @@ -19,7 +19,7 @@ TOAST - versus large objects + 与大对象对比 @@ -186,11 +186,11 @@ inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE); int lo_write(PGconn *conn, int fd, const char *buf, size_t len); - 将buf中的len字节(其大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 + 将buf中的len字节(缓冲区大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -207,7 +207,7 @@ int lo_read(PGconn *conn, int fd, char *buf, size_t len); - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -273,7 +273,7 @@ pg_int64 lo_tell64(PGconn *conn, int fd); int lo_truncate(PGconn *conn, int fd, size_t len); - 该函数把大对象描述符fd截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用空字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 + 该函数把大对象描述符fd对应的大对象截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用零字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 @@ -394,16 +394,16 @@ CREATE TABLE image ( raster oid ); -SELECT lo_creat(-1); -- returns OID of new, empty large object +SELECT lo_creat(-1); -- 返回新建的空大对象的 OID -SELECT lo_create(43213); -- attempts to create large object with OID 43213 +SELECT lo_create(43213); -- 尝试创建 OID 为 43213 的大对象 -SELECT lo_unlink(173454); -- deletes large object with OID 173454 +SELECT lo_unlink(173454); -- 删除 OID 为 173454 的大对象 INSERT INTO image (name, raster) VALUES ('beautiful image', lo_import('/etc/motd')); -INSERT INTO image (name, raster) -- same as above, but specify OID to use +INSERT INTO image (name, raster) -- 与上例相同,但指定要使用的 OID VALUES ('beautiful image', lo_import('/etc/motd', 68583)); SELECT lo_export(image.raster, '/tmp/motd') FROM image @@ -412,7 +412,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image - 服务器端的lo_importlo_export函数与其客户端对应函数的行为差异很大。这两个函数在服务器的文件系统中读写文件,使用数据库所有者的权限。因此,默认情况下它们的使用仅限于超级用户。相比之下,客户端导入和导出函数在客户端的文件系统中读写文件,使用客户端程序的权限。客户端函数不需要任何数据库权限,除了读取或写入相关大对象所需的权限。 + 服务器端的lo_importlo_export函数与其客户端对应函数的行为差异很大。这两个函数在服务器的文件系统中读写文件,使用运行数据库服务器的操作系统用户的权限。因此,默认情况下它们的使用仅限于超级用户。相比之下,客户端导入和导出函数在客户端的文件系统中读写文件,使用客户端程序的权限。客户端函数不需要任何数据库权限,除了读取或写入相关大对象所需的权限。 @@ -431,7 +431,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image 示例程序 - 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行版的src/test/examples/testlo.c中找到。 + 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行包的src/test/examples/testlo.c中找到。 @@ -440,13 +440,13 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /*------------------------------------------------------------------------- * * testlo.c - * test using large objects with libpq + * 测试使用 libpq 操作大对象 * * Portions Copyright (c) 1996-2019, PostgreSQL Global Development Group * Portions Copyright (c) 1994, Regents of the University of California * * - * IDENTIFICATION + * 标识 * src/test/examples/testlo.c * *------------------------------------------------------------------------- @@ -466,7 +466,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /* * importFile - - * import file "in_filename" into database as large object "lobjOid" + * 将文件 "in_filename" 作为大对象 "lobjOid" 导入数据库 * */ static Oid @@ -480,16 +480,16 @@ importFile(PGconn *conn, char *filename) int fd; /* - * open the file to be read in + * 打开要读取的文件 */ fd = open(filename, O_RDONLY, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"\n", filename); } /* - * create the large object + * 创建大对象 */ lobjId = lo_creat(conn, INV_READ | INV_WRITE); if (lobjId == 0) @@ -498,7 +498,7 @@ importFile(PGconn *conn, char *filename) lobj_fd = lo_open(conn, lobjId, INV_WRITE); /* - * read in from the Unix file and write to the inversion file + * 从 Unix 文件读取数据并写入大对象 */ while ((nbytes = read(fd, buf, BUFSIZE)) > 0) { @@ -536,7 +536,7 @@ pickout(PGconn *conn, Oid lobjId, int start, int len) fprintf(stderr, ">>> %s", buf); nread += nbytes; if (nbytes <= 0) - break; /* no more data? */ + break; /* 没有更多数据? */ } free(buf); fprintf(stderr, "\n"); @@ -582,7 +582,7 @@ overwrite(PGconn *conn, Oid lobjId, int start, int len) /* * exportFile - - * export large object "lobjOid" to file "out_filename" + * 将大对象 "lobjOid" 导出到文件 "out_filename" * */ static void @@ -595,24 +595,24 @@ exportFile(PGconn *conn, Oid lobjId, char *filename) int fd; /* - * open the large object + * 打开大对象 */ lobj_fd = lo_open(conn, lobjId, INV_READ); if (lobj_fd < 0) fprintf(stderr, "cannot open large object %u", lobjId); /* - * open the file to be written to + * 打开要写入的文件 */ fd = open(filename, O_CREAT | O_WRONLY | O_TRUNC, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"", filename); } /* - * read in from the inversion file and write to the Unix file + * 从大对象读取数据并写入 Unix 文件 */ while ((nbytes = lo_read(conn, lobj_fd, buf, BUFSIZE)) > 0) { @@ -659,11 +659,11 @@ main(int argc, char **argv) out_filename = argv[3]; /* - * set up the connection + * 建立连接 */ conn = PQsetdb(NULL, NULL, NULL, NULL, database); - /* check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "Connection to database failed: %s", @@ -671,7 +671,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) diff --git a/zh/12/monitoring.sgml b/zh/12/monitoring.sgml index 089046fb..71d083e0 100644 --- a/zh/12/monitoring.sgml +++ b/zh/12/monitoring.sgml @@ -2333,17 +2333,13 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i checksum_failures bigint - - 在此数据库(或共享对象)中检测到的数据页校验码失败数,如果没有启用数据校验码则为NULL。 - + 在此数据库(或共享对象)中检测到的数据页校验和失败次数,如果未启用数据校验和则为 NULL。 checksum_last_failure timestamp with time zone - - 在此数据库(或共享对象)中检测到最后一个数据页校验码失败的时间,如果没有启用数据校验码则为NULL。 - + 在此数据库(或共享对象)中最后一次检测到数据页校验和失败的时间,如果未启用数据校验和则为 NULL。 diff --git a/zh/12/pgtrgm.sgml b/zh/12/pgtrgm.sgml index edf12a49..e7d83b21 100644 --- a/zh/12/pgtrgm.sgml +++ b/zh/12/pgtrgm.sgml @@ -339,11 +339,11 @@ SELECT * FROM test_trgm WHERE t ~ '(foo|bar)'; - 文本搜索集成 + 文本检索集成 与全文索引结合使用时,三字符组匹配是非常有用的工具。 - 尤其是,它有助于识别那些因拼写错误而无法被全文搜索机制直接匹配的输入词。 + 尤其是,它有助于识别那些因拼写错误而无法被全文检索机制直接匹配的输入词。 diff --git a/zh/12/protocol.sgml b/zh/12/protocol.sgml index 70606ef1..5fc81739 100644 --- a/zh/12/protocol.sgml +++ b/zh/12/protocol.sgml @@ -33,7 +33,7 @@ - 会话通常由前端选择终止,但在某些情况下也可能由后端强制终止。无论哪种情况,后端在关闭连接前都会回滚所有打开的(未完成的)事务。 + 会话通常由前端选择终止,但在某些情况下也可能由后端强制终止。无论哪种情况,后端关闭连接时,都会在退出前回滚所有打开的(未完成的)事务。 @@ -72,9 +72,7 @@ 整个执行周期包括一个解析步骤,它从文本查询字符串创建预备语句; 一个绑定步骤,它根据预备语句和所需参数值创建 portal; - 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询 - (SELECTSHOW等),可以要求执行步骤只取回 - 有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 + 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询(SELECTSHOW等),可以要求执行步骤只取回有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 @@ -91,8 +89,8 @@ - 文本形式的数值是特定数据类型的输入/输出转换函数生成或接受的任何字符串。在传输形式上,字符串没有末尾空字符;如果前端要想把收到的值当作C字符串处理,那么必须自己加上一个(顺便说一下,文本格式不允许嵌入空字符)。 - + 值的文本表示是相应数据类型的输入/输出转换函数生成和接受的字符串。在传输形式中,值的末尾没有空字符;前端若要将收到的值作为 C 字符串处理,必须自行添加一个。(文本格式也不允许内嵌空字符。) + 整数的二进制表示采用网络字节序(最高有效字节在前)。至于其他数据类型,请查阅文档或源代码了解其二进制表示形式。要注意,复杂数据类型的二进制表示可能会在不同服务器版本之间发生变化;文本格式通常是可移植性更好的选择。 @@ -112,7 +110,7 @@ 启动 - 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,判断该连接在初步上是否可接受,以及是否需要额外的认证。 + 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,初步判断是否接受该连接,以及需要何种额外认证(如果需要)。 @@ -355,7 +353,7 @@ 表示即将返回行作为对SELECTFETCH等查询的响应。 - 此消息的内容描述了行的列布局。这将跟随每个返回给前端的行的DataRow消息。 + 此消息的内容描述了行的列布局。该消息之后,每个返回给前端的行都对应一条 DataRow 消息。 @@ -434,14 +432,14 @@ - 我们建议的方法是把前端代码写成状态机的风格,它可以在任何时刻接受任何有意义的消息类型,而不是假设消息的序列总是准确。 - + 建议以状态机的方式编写前端,使其能够在任何合理的时机接收相应类型的消息,而不把消息确切顺序的假设写死在代码中。 + 一个简单查询中的多条语句 - 当一个简单查询消息中包含多于一条SQL语句(被分号分隔)时,那些语句会被当做一个事务中执行,除非其中包括显式事务控制命令来强制不同的行为。例如,如果消息包括 + 当一个简单查询消息中包含多于一条SQL语句(被分号分隔)时,这些语句会作为单个事务执行,除非其中包括显式事务控制命令来强制不同的行为。例如,如果消息包括 INSERT INTO mytable VALUES(1); SELECT 1/0; @@ -463,15 +461,15 @@ SELECT 1/0; - 这种行为通过在一个隐式事务块中的一个多语句Query消息中运行那些语句来实现,除非它们运行在某个显式事务块中。隐式事务块与常规事务块之间的区别在于隐式块会在Query消息结束时自动被关闭,或者是在没有错误的情况下由一个隐式提交关闭,或者是在有错误时由一个隐式的回滚关闭。这类似于一个语句自己执行(当不在事务块中时)时发生的隐式提交或回滚。 - + 这种行为的实现方式是:除非已有显式事务块可供这些语句执行,否则就在一个隐式事务块中执行多语句 Query 消息中的语句。隐式事务块与常规事务块的主要区别在于,隐式块会在 Query 消息结束时自动关闭:没有错误时隐式提交,发生错误时隐式回滚。这类似于单独执行一条语句(不在事务块中)时发生的隐式提交或回滚。 + - 如果会话已经在一个事务块中,作为前面某个消息中BEGIN的结果,那么Query消息会简单地继续那个事务块,不管该消息包含一个语句还是多个语句。不过,如果该Query消息包含一个关闭现有事务块的COMMIT或者ROLLBACK,那么任何接下来的语句都会在一个隐式事务块中被执行。反过来,如果在多语句Query消息中出现一个BEGIN,那么它会开始一个常规事务块,这个常规事务块将只能被一个显式的COMMIT或者ROLLBACK终止,不管这两种命令是出现在这个Query消息还是后面的一个Query消息中。如果BEGIN跟在一些作为隐式事务块执行的语句后面,那些语句不会被立刻提交。实际上,它们会被包括到新的常规事务块中。 + 如果会话因前面某条消息中的BEGIN而已经处于事务块中,那么 Query 消息会继续该事务块,不管该消息包含一个语句还是多个语句。不过,如果该Query消息包含一个关闭现有事务块的COMMIT或者ROLLBACK,那么任何接下来的语句都会在一个隐式事务块中被执行。反过来,如果在多语句Query消息中出现一个BEGIN,那么它会开始一个常规事务块,这个常规事务块将只能被一个显式的COMMIT或者ROLLBACK终止,不管这两种命令是出现在这个Query消息还是后面的一个Query消息中。如果BEGIN跟在一些作为隐式事务块执行的语句后面,那些语句不会被立刻提交。实际上,它们会被包括到新的常规事务块中。 - 出现在一个隐式事务块中的COMMIT或者ROLLBACK会被正常执行并且关闭该隐式块。不过,由于没有先前的BEGIN配对的COMMIT或者ROLLBACK表示一种错误,所以将会发出一个警告。如果后面还有更多语句,将会为它们开始一个新的隐式事务块。 + 出现在一个隐式事务块中的COMMIT或者ROLLBACK会被正常执行并且关闭该隐式块。不过,由于没有先前的BEGIN配对的COMMIT或者ROLLBACK可能表示误操作,所以会发出警告。如果后面还有更多语句,将会为它们开始一个新的隐式事务块。 @@ -479,17 +477,17 @@ SELECT 1/0; - 记住,不管任何事务控制命令存不存在,Query消息的执行会在第一个错误时停止。因此,对于下面的在一个Query消息中的示例 + 请记住,无论消息中是否包含事务控制命令,Query 消息的执行都会在第一个错误处停止。例如,单条 Query 消息包含以下内容时: BEGIN; SELECT 1/0; ROLLBACK; - 会话中将留下一个失败的常规事务块,因为在出现除零错误后不会到达ROLLBACK。将需要另一个ROLLBACK把会话恢复到一种可用的状态。 - +会话会停留在失败的常规事务块内,因为发生除零错误后不会再执行ROLLBACK。需要另发一条ROLLBACK,才能将会话恢复到可用状态。 + - 另一种要注意的行为是,最初的词法和语法分析是在整个查询字符串被执行之前进行的。因此后面的语句中的简单错误(例如拼写错误的关键词)可能会阻止任何语句的执行。这通常对用户是不可见的,因为在当作一个隐式事务块执行时,这些语句不管怎样都会全部被回滚。不过,在尝试于一个多语句Query中执行多个事务时,这种现象可能是可见的。例如,如果一个拼写错误把我们之前的示例变成 + 另一种要注意的行为是,在执行任何语句之前,会先对整个查询字符串进行词法和语法分析。因此后面的语句中的简单错误(例如拼写错误的关键词)可能会阻止任何语句的执行。这通常对用户是不可见的,因为在当作一个隐式事务块执行时,这些语句不管怎样都会全部被回滚。不过,在尝试于一个多语句Query中执行多个事务时,这种现象可能是可见的。例如,如果一个拼写错误把我们之前的示例变成 BEGIN; INSERT INTO mytable VALUES(1); @@ -552,11 +550,11 @@ SELCT 1/0; - 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是执行不会导致后端发送 ReadyForQuery 或 RowDescription。 + 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是 Execute 不会导致后端发送 ReadyForQuery 或 RowDescription。 - 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息之一结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 + 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息中的恰好一条结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 @@ -571,7 +569,7 @@ SELCT 1/0; - 除了这些基本的、必须的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 + 除了这些基本的、必需的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 @@ -607,46 +605,40 @@ SELCT 1/0; - 流水线处理 + 管道化 - 流水线处理 + 管道化 协议规范 - 使用扩展查询协议允许流水线处理,这意味着发送一系列查询而无需等待先前的查询完成。 - 这减少了完成一系列操作所需的网络往返次数。然而,用户必须仔细考虑所需的行为,如果其中一步失败, - 因为后续查询已经在传输到服务器的过程中。 - + 扩展查询协议允许管道化,即连续发送一系列查询,而不等待先前查询完成。这减少了完成一组操作所需的网络往返次数。不过,用户必须仔细考虑其中某个步骤失败时所需的行为,因为后续查询已经在发往服务器的途中。 + - 处理这个问题的一种方法是将整个查询系列作为一个事务处理,即将其包装在BEGIN... - COMMIT中。然而,如果希望其中一些命令独立于其他命令提交,这并没有帮助。 - + 处理这个问题的一种方式是让整组查询成为单个事务,即用BEGIN ... COMMIT包围它们。不过,如果希望其中某些命令独立于其他命令提交,这种方式就无法满足要求。 + - 扩展查询协议提供了另一种管理这个问题的方式,即在依赖的步骤之间省略发送同步消息。 - 由于在错误后,后端会跳过命令消息直到找到同步消息,这允许在管道中的后续命令在前面的命令失败时自动跳过,而无需客户端明确地使用BEGINCOMMIT来管理。 - 管道中可以通过同步消息分隔独立可提交的段。 - + 扩展查询协议提供了另一种处理方式,即省略相互依赖的步骤之间的 Sync 消息。发生错误后,后端会跳过命令消息,直到遇到 Sync,因此当前面的命令失败时,管道中的后续命令便会自动跳过,而不必由客户端用BEGINCOMMIT显式管理。管道中可独立提交的各段可以用 Sync 消息分隔。 + - 如果客户端没有发出显式 BEGIN,则会启动一个隐式事务块。每个 Sync 通常会在前序步骤成功时导致隐式 COMMIT,失败时导致隐式 ROLLBACK。服务器只有在第一个命令结束且尚未收到 Sync 时,才能识别这种隐式事务块。有一些 DDL 命令(例如 CREATE DATABASE)不能在事务块内执行;若这类命令在管道中执行,除非它是某个 Sync 之后的第一条命令,否则会失败。此外,它成功后会强制立即提交以保持数据库一致性。因此,紧随这些命令之后的 Sync 除了返回 ReadyForQuery 外不会产生额外效果。 - + 如果客户端没有发出显式的BEGIN,那么每个 Sync 通常会在前序步骤成功时引发隐式的COMMIT,失败时引发隐式的ROLLBACK。不过,少数 DDL 命令(例如CREATE DATABASE)不能在事务块中执行。如果这类命令在管道中执行,除非它是管道中的第一条命令,否则会失败。此外,它成功后会强制立即提交,以保持数据库一致性。因此,紧随这类命令之后的 Sync 除了返回 ReadyForQuery 外,不产生其他效果。 + - 当使用这种方法时,必须通过计算ReadyForQuery消息的数量并等待达到发送的Syncs数量来确定管道的完成。 - 计算命令完成响应是不可靠的,因为其中一些命令可能会被跳过,因此不会产生完成消息。 - + 使用这种方式时,必须统计 ReadyForQuery 消息的数量,并等待该数量达到已发送的 Sync 消息数量,才能确定管道已完成。统计命令完成响应并不可靠,因为某些命令可能被跳过,因而不会产生完成消息。 + 函数调用 - 函数调用子协议允许客户端请求一个对存在于数据库pg_proc系统表中的任意函数的直接调用。客户端必须在该函数上有执行的权限。 - + 函数调用子协议允许客户端请求直接调用数据库pg_proc系统目录中的任意函数。客户端必须具有该函数的执行权限。 + @@ -656,8 +648,8 @@ SELCT 1/0; - 一个函数调用周期是由前端向后端发送一条FunctionCall消息初始化的。然后后端根据函数调用的结果发送一条或者更多响应消息,并且最后是一条ReadyForQuery响应消息。ReadyForQuery通知前端它可以安全地发送一个新的查询或者函数调用了。 - + 函数调用周期由前端向后端发送一条 FunctionCall 消息来启动。后端随后根据函数调用的结果发送一条或多条响应消息,最后发送一条 ReadyForQuery 响应消息。ReadyForQuery 告知前端,可以安全地发送新的查询或函数调用。 + 来自后端的可能的响应消息是: @@ -676,7 +668,7 @@ SELCT 1/0; FunctionCallResponse - 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者集合类型的结果)。 + 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者结果集合)。 @@ -710,7 +702,7 @@ SELCT 1/0; - 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(表示成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 + 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(允许成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 @@ -718,11 +710,11 @@ SELCT 1/0; - 在拷贝入模式下,后端将忽略所收到的Flush和Sync消息。收到任何其他非拷贝消息类型都会造成一个错误,它将导致上面所描述的拷贝入状态中断(Flush和Sync的例外是为了方便客户端库,它们总是在一个Execute消息之后发送Flush和Sync,而不检查被执行的命令是否为一个COPY FROM STDIN)。 - + 后端会忽略在拷贝入模式期间收到的 Flush 和 Sync 消息。收到任何其他非拷贝类型的消息都会构成错误,并按上述方式中止拷贝入状态。(Flush 和 Sync 的例外是为了方便那些总是在 Execute 消息之后发送 Flush 或 Sync、而不检查待执行命令是否为COPY FROM STDIN的客户端库。) + - 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句的时候初始化的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能退出传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 + 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句时启动的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能中止传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 @@ -730,16 +722,16 @@ SELCT 1/0; - 在CopyData消息中间可能会散布有NoticeResponse和ParameterStatus消息。前端必须处理这些情况,并且应该也为异步消息类型(参见)准备好。除此之外,可以将任何除 CopyData 或 CopyDone 以外的消息类型视为拷贝出模式的终止标志。 - + NoticeResponse 和 ParameterStatus 消息可能穿插在 CopyData 消息之间;前端必须处理这些情况,并应准备好处理其他异步消息类型(参见)。除此之外,可以将任何除 CopyData 或 CopyDone 以外的消息类型视为拷贝出模式的终止标志。 + - 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许数据以高速批量方式在客户端与服务器之间双向传输。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见。 + 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许高速批量地向服务器发送数据以及从服务器接收数据。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见 - CopyInResponse、CopyOutResponse和CopyBothResponse消息包括域和格式代码,域告诉前端每行的列数,而格式代码则用于具体每个列(就目前的实现而言,一个给定COPY操作中的所有列都将使用同样的格式,但是消息设计并不做这个假设)。 - + CopyInResponse、CopyOutResponse 和 CopyBothResponse 消息包含一些字段,用于告知前端每行的列数以及每列所使用的格式代码。(在当前实现中,同一次COPY操作的所有列都使用相同格式,但消息设计并不作此假设。) + @@ -766,8 +758,8 @@ SELCT 1/0; - 如果前端发出一个LISTEN命令, 那么无论何时在为同一个通道名NOTIFY时,后端将发送一个NotificationResponse消息(不要和NoticeResponse搞混!)。 - + 如果前端发出LISTEN命令,那么每当针对同一通道名执行NOTIFY命令时,后端都会发送一条 NotificationResponse 消息(不要与 NoticeResponse 混淆)。 + @@ -785,11 +777,11 @@ SELCT 1/0; - 要发出一条取消请求,前端打开一个与服务器的新连接并且发送一条CancelRequest消息, 而不是通常在新连接中经常发送的StartupMessage消息。服务器将处理这个请求然后关闭连接。 出于安全原因,对取消请求消息不做直接的响应。 - + 要发出取消请求,前端会新建到服务器的连接,并发送 CancelRequest 消息,而不是新连接通常发送的 StartupMessage 消息。服务器处理该请求后便会关闭连接。出于安全原因,服务器不会直接回复取消请求消息。 + - 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的关键数据(PID和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则退出当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 + 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的密钥数据(PID 和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则中止当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 @@ -797,7 +789,7 @@ SELCT 1/0; - 这么做是对安全性和有效性通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 + 这么做是对安全性和效率通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 @@ -817,11 +809,11 @@ SELCT 1/0; - 其他终止场景来自各种故障,例如任一端发生内核转储、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 + 其他终止场景来自各种故障,例如任一端发生 core dump、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 - 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果很可能在得知断开之前被提交。 + 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果可能在发现连接断开之前被提交。 @@ -834,20 +826,24 @@ SELCT 1/0; 要发起一条使用SSL加密的连接,前端首先发送 SSLRequest 消息,而不是 StartupMessage。随后服务器会响应一个包含SN的单字节,分别表示它愿意或不愿意执行SSL加密。如果前端对该响应不满意,此时可以关闭连接。若要在收到S后继续,就先与服务器完成SSL启动握手(这里不做描述,它属于SSL规范的一部分)。如果成功,再继续发送通常的 StartupMessage。在这种情况下,StartupMessage 以及后续所有数据都会被SSL加密。若要在收到N后继续,则发送通常的 StartupMessage,并在不使用加密的情况下继续。 - (另外,可以在 N 响应之后发出 GSSENCRequest 消息,尝试使用 GSSAPI 加密代替 SSL。) + (另外,可以在 N 响应之后发出 GSSENCRequest 消息,尝试使用 GSSAPI 加密代替 SSL。) - 前端也应准备处理服务器对 SSLRequest 返回的 ErrorMessage。前端不应将该错误直接展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 SSL 的情况下继续。 + 前端也应准备处理服务器对 SSLRequest 返回的 ErrorMessage。前端不应将该错误展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 SSL 的情况下继续。 - 当可以执行 SSL 加密时,服务器预计仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给他们的 SSL 库,要么在发现他们已经读取到额外的字节时将其视为协议违规。 + 当可以执行 SSL 加密时,服务器应仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给所用的 SSL 库,要么在发现已经读取到额外的字节时将其视为协议违规。 - 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 SSLRequest。 + + 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 SSLRequest。 + - 虽然协议本身没有提供让服务器强制使用 SSL 加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + + 虽然协议本身没有提供让服务器强制使用SSL加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + @@ -860,24 +856,24 @@ SELCT 1/0; 要建立 GSSAPI 加密连接,前端首先发送 GSSENCRequest 消息,而不是 StartupMessage。服务器随后以单个字节响应,内容为 GN,分别表示愿意或不愿意使用 GSSAPI 加密。如果前端对响应不满意,可以在此时关闭连接。收到 G 后要继续,应使用 RFC2744 中介绍的 GSSAPI C 绑定或等效接口,在循环中调用 gss_init_sec_context() 来执行 GSSAPI 初始化,并将结果发送给服务器:先使用空输入,再依次使用服务器返回的每个结果,直到该调用不再产生输出。将 gss_init_sec_context() 的结果发送给服务器时,应在前面加上消息长度,以网络字节序的四字节整数表示。收到 N 后要继续,则发送通常的 StartupMessage,以不加密的方式继续。(也允许在收到 N 响应后发送 SSLRequest 消息,尝试使用 SSL 加密代替 GSSAPI。) - 前端也应准备处理服务器对 GSSENCRequest 返回的 ErrorMessage。前端不应将该错误直接展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 GSSAPI 加密的情况下继续。 + 前端也应准备处理服务器对 GSSENCRequest 返回的 ErrorMessage。前端不应将该错误展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 GSSAPI 加密的情况下继续。 - 当GSSAPI加密可用时,服务器预计只发送单个G字节,然后等待前端启动GSSAPI握手。此时如果还有其他可读字节,很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应编写代码,要么从套接字中恰好读取一个字节后再把套接字交给其 GSSAPI 库,要么在发现自己已经读到额外字节时将其视为协议违规。 + 当GSSAPI加密可用时,服务器应只发送单个G字节,然后等待前端启动GSSAPI握手。此时如果还有其他可读字节,很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应编写代码,要么从套接字中恰好读取一个字节后再把套接字交给其 GSSAPI 库,要么在发现自己已经读到额外字节时将其视为协议违规。 - 初始 GSSENCRequest 也可用于那些正在建立、目的是发送 CancelRequest 消息的连接。 - + 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 GSSENCRequest。 + 一旦成功建立GSSAPI加密连接,就应使用gss_wrap()加密通常的 StartupMessage 以及后续所有数据,并在实际加密负载前附上gss_wrap()结果长度,该长度以网络字节序的四字节整数表示。请注意,服务器只接受来自客户端、长度小于 16kB 的加密数据包。客户端应使用gss_wrap_size_limit()确定符合该限制的未加密消息大小,较大的消息则应拆分为多次gss_wrap()调用。典型分段是 8kB 的未加密数据,对应得到略大于 8kB 但明显小于 16kB 的加密数据包。通常可以认为,服务器不会向客户端发送大于 16kB 的加密数据包。 - 虽然协议本身并不为服务器提供强制启用GSSAPI加密的方法,但管理员可以把服务器配置为拒绝未加密会话,把它作为认证检查的一个副作用。 - + 虽然协议本身没有提供让服务器强制使用GSSAPI加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + @@ -899,24 +895,21 @@ SELCT 1/0; - 客户端从列表中选择一个支持的机制,并向服务器发送一个SASLInitialResponse消息。 - 该消息包括所选机制的名称,以及如果所选机制使用的话,还包括一个可选的初始客户端响应。 - + 客户端从列表中选择一种受支持的机制,并向服务器发送 SASLInitialResponse 消息。消息包含所选机制的名称;如果该机制使用初始客户端响应,消息还可以包含这一可选响应。 + - 一个或多个服务器挑战和客户端响应消息将随后而来。每个服务器挑战都是在一个 - AuthenticationSASLContinue 消息中发送的,随后是客户端在一个 SASLResponse - 消息中的响应。这些消息的具体内容是特定于机制的。 - + 随后会进行一轮或多轮服务器挑战和客户端响应。每次服务器挑战都通过 AuthenticationSASLContinue 消息发送,随后客户端通过 SASLResponse 消息响应。消息的具体内容取决于所用机制。 + - 最后,当认证交换成功完成时,服务器会发送可选的 AuthenticationSASLFinal 消息,随后立即发送 AuthenticationOk。AuthenticationSASLFinal 包含机制特定的附加数据;若该机制不需要完成时附加数据,则不会发送 AuthenticationSASLFinal。 - + 最后,认证交换成功完成时,服务器会发送 AuthenticationSASLFinal 消息,紧接着发送 AuthenticationOk 消息。AuthenticationSASLFinal 包含从服务器发给客户端的附加数据,其具体内容取决于所选认证机制。如果该认证机制不使用在完成时发送的附加数据,则不会发送 AuthenticationSASLFinal 消息。 + @@ -936,31 +929,22 @@ SELCT 1/0; - SCRAM规范规定密码也必须是UTF-8编码,并且使用SASLprep算法处理。 - 然而,PostgreSQL不要求密码必须使用UTF-8编码。 - 当用户设置密码时,无论实际使用的编码是什么,都会像使用UTF-8一样使用SASLprep进行处理。 - 但是,如果密码不是合法的UTF-8字节序列,或者包含SASLprep算法禁止的UTF-8字节序列, - 则会使用原始密码而不进行SASLprep处理,而不是抛出错误。这样可以在密码为UTF-8时对其进行规范化, - 但仍允许使用非UTF-8密码,并且不需要系统知道密码使用的编码方式。 - + SCRAM 规范规定密码也必须采用 UTF-8 编码,并通过SASLprep算法处理。不过,PostgreSQL并不要求密码使用 UTF-8。设置用户密码时,无论实际采用何种编码,都会将其视作 UTF-8 并用 SASLprep 处理。但是,如果密码不是合法的 UTF-8 字节序列,或者包含 SASLprep 算法禁止的 UTF-8 字节序列,就会直接使用未经 SASLprep 处理的原始密码,而不抛出错误。这样既能对 UTF-8 密码进行规范化,又允许使用非 UTF-8 密码,而且不要求系统知道密码采用何种编码。 + - Channel binding在支持SSL的PostgreSQL构建中受支持。带有通道绑定的SCRAM的SASL机制名称是 + 通道绑定在支持SSL的PostgreSQL构建中受支持。带有通道绑定的SCRAM的SASL机制名称是 SCRAM-SHA-256-PLUS。PostgreSQL使用的通道绑定类型是 tls-server-end-point - 在没有通道绑定的SCRAM中,服务器选择一个随机数, - 传输给客户端,与用户提供的密码在传输的密码哈希中混合。虽然这可以 - 防止密码哈希在后续会话中被成功重新传输,但无法阻止真实服务器和客 - 户端之间的虚假服务器通过服务器的随机值并成功进行认证。 - + 在不带通道绑定的SCRAM中,服务器会选择一个随机数并发送给客户端,将它与用户提供的密码混合,形成所传输的密码 hash。虽然这样可以防止在后续会话中成功重放该密码 hash,但无法阻止位于真实服务器与客户端之间的伪造服务器转发服务器的随机值并成功通过认证。 + - SCRAM与通道绑定一起防止这种中间人攻击,通过将服务器证书的签名混合到传输的密码哈希中。 - 虽然伪造服务器可以重新传输真实服务器的证书,但它无法访问与该证书匹配的私钥,因此无法证明自己是所有者,导致SSL连接失败。 - + 带通道绑定的SCRAM会将服务器证书的签名混入所传输的密码 hash,从而防止此类中间人攻击。虽然伪造服务器可以转发真实服务器的证书,但它无法取得与证书匹配的私钥,因此无法证明自己是证书所有者,最终导致 SSL 连接失败。 + @@ -1029,21 +1013,27 @@ SELCT 1/0; 无论是物理复制还是逻辑复制的 walsender 模式,都只能使用简单查询协议。 -为了测试复制命令,可以通过psql或其他使用libpq的工具建立复制连接,连接字符串中应包含replication选项,例如: + + 为了测试复制命令,可以通过 psql 或其他使用 libpq 的工具建立复制连接,连接字符串中应包含 replication 选项,例如: + psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" -不过,通常更有用的做法是使用(用于物理复制)或(用于逻辑复制)。 + +不过,通常更有用的做法是使用 (用于物理复制)或 (用于逻辑复制)。 + - 复制命令在服务器日志中记录,当启用时。 + 启用 后,复制命令会记录到服务器日志中。 复制模式接受以下命令: IDENTIFY_SYSTEM - 识别系统 + IDENTIFY_SYSTEM - 请求服务器标识自身。服务器返回一个只有一行的结果集,包含四个字段: + + 请求服务器标识自身。服务器会返回一个包含四个字段的单行结果集: + @@ -1052,7 +1042,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" systemid (text) - 标识数据库集簇的唯一系统标识符。可用于检查初始化备库的基础备份是否来自同一个数据库集簇。 + + 用于标识该集簇的唯一系统标识符。它可用于检查初始化备库所用的基础备份是否来自同一个集簇。 + @@ -1077,7 +1069,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" dbname (text) - 所连接的数据库,或 null。 + + 当前连接到的数据库,或为 null。 + @@ -1136,7 +1130,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" content (bytea) - 时间线历史文件的内容。 + + 时间线历史文件的内容。 + @@ -1243,22 +1239,16 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" START_REPLICATION [ SLOT slot_name ] [ PHYSICAL ] XXX/XXX [ TIMELINE tli ] - 开始复制 + START_REPLICATION - 指示服务器开始流式传输WAL,从WAL位置XXX/XXX开始。 - 如果指定了TIMELINE选项,则流式传输将从时间线tli开始; - 否则,将选择服务器当前的时间线。如果请求的WAL部分已经被回收,服务器可能会回复错误。 - 成功时,服务器将用CopyBothResponse消息回复,然后开始向前端流式传输WAL。 - + 指示服务器从 WAL 位置 XXX/XXX 开始流式传输 WAL。如果指定了 TIMELINE 选项,则从时间线 tli 开始传输;否则选择服务器当前的时间线。服务器可以返回错误,例如请求的 WAL 部分已被回收时。成功时,服务器返回 CopyBothResponse 消息,然后开始向前端流式传输 WAL。 + - 如果通过slot_name提供了复制槽名称, - 那么在复制进行期间会更新该复制槽,以便服务器知道哪些 WAL 段, - 以及在启用了 hot_standby_feedback 时,哪些事务 - 仍然被备库所需要。 - + 如果通过 slot_name 提供了复制槽名称,该复制槽会随着复制的进行而更新,使服务器知道备库仍需要哪些 WAL 段,以及在启用 hot_standby_feedback 时仍需要哪些事务。 + 如果客户端请求的时间线不是最新时间线,但属于服务器的历史,服务器会从请求的起点开始,流式传输该时间线上的所有 WAL,直到服务器切换到另一条时间线的位置。如果客户端请求的流式传输起点恰好位于旧时间线的末尾,服务器会立即返回 CommandComplete,而不进入 COPY 模式。 @@ -1516,7 +1506,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" DROP_REPLICATION_SLOT slot_name WAIT - 删除复制槽 + DROP_REPLICATION_SLOT 删除复制槽,释放任何保留的服务器端资源。如果该槽是逻辑槽,且创建它的数据库与 walsender 当前连接的数据库不同,则此命令失败。 @@ -1558,9 +1548,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 设置备份的标签。如果未指定,则将使用base backup作为备份标签。 - 标签的引号使用规则与打开的标准SQL字符串相同。 - + 设置备份标签。如果未指定,则使用 base backup 作为备份标签。标签的引号规则与启用 时的标准 SQL 字符串相同。 + @@ -1660,7 +1649,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" size (int8) - 如果请求了进度报告,则为表空间的大致大小;否则为空值。 + + 如果请求了进度报告,则为表空间的大致大小;否则为 null。 + @@ -1724,7 +1715,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 逻辑复制协议 + 逻辑流复制协议 本节介绍逻辑复制协议,它是一种以复制命令START_REPLICATION @@ -1733,7 +1724,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 逻辑复制协议构建在物理流复制协议的底层机制之上。 + 逻辑流复制协议构建在物理流复制协议的基本机制之上。 @@ -1793,7 +1784,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 逻辑复制协议逐个发送事务。这意味着,一对 Begin 和 Commit 消息之间的所有消息都属于同一个事务。 - 每个被发送的事务都包含零条或多条 DML 消息(插入、更新、删除)。在级联场景下,它还会包含 Origin 消息。Origin 消息表示该事务产生于另一个复制节点。由于逻辑复制协议中的复制节点可以是任意实现,因此唯一标识符就是该源头的名称。下游是否以及如何处理这一信息,由其自行决定。Origin 消息总是在事务中的任何 DML 消息之前发送。 + 每个发送的事务都包含零条或多条 DML 消息(Insert、Update、Delete)。在级联配置中,还可能包含 Origin 消息。Origin 消息表示该事务源自另一个复制节点。由于逻辑复制协议中的复制节点几乎可以是任何实现,因此唯一的标识符就是复制源的名称。下游负责按需处理这一信息(如果需要处理)。Origin 消息总是在事务中的任何 DML 消息之前发送。 @@ -1858,9 +1849,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 对后端返回的字符串长度,没有预定义的限制。 - 前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。 - 如果做不到这一点,就应读取完整字符串,并丢弃不适合固定大小缓冲区的尾随字符。 + 后端返回的字符串长度没有预定义的限制。前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。如果做不到这一点,就应读取完整字符串,并丢弃固定大小的缓冲区容纳不下的尾随字符。 @@ -1885,8 +1874,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 消息格式 - 本节描述每条消息的详细格式。每条消息都标记了可由前端(F)、后端(B)或双方(F&B)发送。 - 请注意,虽然每条消息开头都带有字节计数,但大多数消息格式都定义为无需参考该计数也能确定消息边界。这一设计最初是出于历史原因(早期已废弃的协议 v2 没有显式长度字段),同时也有助于有效性校验。 + 本节描述每条消息的详细格式。每条消息都标明它可以由前端(F)、后端(B)或双方(F & B)发送。注意,虽然每条消息开头都有字节计数,但消息格式的定义使得无需参考该计数也能确定消息的结束位置。这有助于检查消息的有效性。(CopyData 消息是例外,因为它构成数据流的一部分,任何单条 CopyData 消息的内容都无法独立解释。) @@ -1907,7 +1895,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -1938,7 +1926,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -1968,7 +1956,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -1998,7 +1986,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(12) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2035,7 +2023,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2066,7 +2054,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2097,7 +2085,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2128,7 +2116,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2165,7 +2153,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2203,7 +2191,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2240,7 +2228,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2277,7 +2265,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(12) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2314,7 +2302,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2332,13 +2320,13 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int16 -后续参数格式码的数量(下文以 C 表示)。可以为零,表示没有参数,或者所有参数都使用默认格式(文本);也可以为一,此时指定的格式码应用于所有参数;还可以等于实际参数数量。 +后续参数格式代码的数量(下文以 C 表示)。可以为零,表示没有参数,或者所有参数都使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有参数;还可以等于实际参数数量。 Int16[C] -参数格式码。目前每个格式码必须为零(文本)或一(二进制)。 +参数格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -2357,20 +2345,20 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byten -参数值,格式由对应的格式码指明。n 为上述长度。 +参数值,格式由对应的格式代码指明。n 为上述长度。 最后一个参数之后是以下字段: Int16 -后续结果列格式码的数量(下文以 R 表示)。可以为零,表示没有结果列,或者所有结果列都应使用默认格式(文本);也可以为一,此时指定的格式码应用于所有结果列(如果有);还可以等于查询实际的结果列数量。 +后续结果列格式代码的数量(下文以 R 表示)。可以为零,表示没有结果列,或者所有结果列都应使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有结果列(如果有);还可以等于查询实际的结果列数量。 Int16[R] -结果列格式码。目前每个格式码必须为零(文本)或一(二进制)。 +结果列格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -2394,7 +2382,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2418,7 +2406,7 @@ CancelRequest (F) - 消息内容的长度,以字节为单位,包括此长度字段本身。 + 消息内容的长度(以字节为单位),包括其自身。 @@ -2474,7 +2462,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2510,7 +2498,7 @@ CancelRequest (F) Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2535,7 +2523,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2608,7 +2596,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2645,7 +2633,7 @@ CancelRequest (F) Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2674,7 +2662,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2703,13 +2691,13 @@ CancelRequest (F) Byte1('G') -标识消息为开始复制输入的响应。前端此时必须发送复制输入数据(如果尚未准备好,应发送 CopyFail 消息)。 +将该消息标识为开始 COPY 输入的响应。前端此时必须发送 COPY 输入数据(如果尚未准备好,应发送 CopyFail 消息)。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2758,13 +2746,13 @@ CancelRequest (F) Byte1('H') -标识消息为开始复制输出的响应。该消息之后会发送复制输出数据。 +将该消息标识为开始 COPY 输出的响应。此消息之后会发送 COPY 输出数据。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2813,13 +2801,13 @@ CancelRequest (F) Byte1('W') -标识消息为开始双向复制的响应。此消息仅用于流复制。 +将该消息标识为开始双向 COPY 的响应。此消息仅用于流复制。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2875,7 +2863,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2890,7 +2878,7 @@ CancelRequest (F) Int32 -列值的长度,以字节为单位(不包括本长度字段自身)。可以为零。特殊值 -1 表示列值为 NULL,此时后面没有值字节。 +列值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 列值。为 NULL 时,后面不再有值的字节。 @@ -2921,14 +2909,14 @@ CancelRequest (F) - 标识消息为描述命令。 + 将该消息标识为 Describe 命令。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2971,7 +2959,7 @@ CancelRequest (F) Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3000,7 +2988,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -3039,14 +3027,14 @@ CancelRequest (F) - 标识消息为一个执行命令。 + 将该消息标识为 Execute 命令。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3081,14 +3069,14 @@ CancelRequest (F) - 将消息标识为Flush命令。 + 将该消息标识为 Flush 命令。 Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3117,7 +3105,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3150,7 +3138,7 @@ CancelRequest (F) Int32 -参数值的长度,以字节为单位(不包括本长度字段自身)。可以为零。特殊值 -1 表示参数值为 NULL,此时后面没有值字节。 +参数值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 参数值。为 NULL 时,后面不再有值的字节。 @@ -3195,13 +3183,13 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 Int32 -函数结果值的长度,以字节为单位(不包括本长度字段自身)。可以为零。特殊值 -1 表示函数结果为 NULL,此时后面没有值字节。 +函数结果值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 函数结果。为 NULL 时,后面不再有值的字节。 @@ -3240,7 +3228,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3275,7 +3263,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3323,7 +3311,7 @@ CancelRequest (F) Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3352,7 +3340,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -3398,7 +3386,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3416,7 +3404,7 @@ CancelRequest (F) String -通知进程传来的载荷字符串。 +通知进程传来的有效载荷字符串。 @@ -3445,7 +3433,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3488,7 +3476,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3521,14 +3509,14 @@ CancelRequest (F) - 将消息标识为解析命令。 + 将该消息标识为 Parse 命令。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3577,14 +3565,14 @@ CancelRequest (F) - 将消息标识为解析完成指示器。 + 将该消息标识为 Parse 完成指示。 Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3614,7 +3602,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3643,15 +3631,14 @@ CancelRequest (F) - 标识消息为 portal 挂起指示器。 - 请注意,仅当执行消息的行数限制达到时才会出现此消息。 + 将该消息标识为 portal 挂起指示。注意,仅当达到 Execute 消息指定的行数限制时,才会出现此消息。 Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3680,7 +3667,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3717,7 +3704,7 @@ CancelRequest (F) Int32(5) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3756,7 +3743,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3815,7 +3802,7 @@ CancelRequest (F) Int16 -字段所使用的格式代码。目前为零(文本)或一(二进制)。对于 Describe 的语句变体所返回的 RowDescription,格式代码尚未确定,始终为零。 +字段所使用的格式代码。目前为零(文本)或一(二进制)。对于 Describe 针对预备语句的变体所返回的 RowDescription,格式代码尚未确定,始终为零。 @@ -3845,7 +3832,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3896,7 +3883,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3922,7 +3909,7 @@ CancelRequest (F) Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3952,7 +3939,7 @@ CancelRequest (F) Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3982,7 +3969,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -4066,14 +4053,14 @@ CancelRequest (F) - 将消息标识为同步命令。 + 将该消息标识为 Sync 命令。 Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -4102,7 +4089,7 @@ CancelRequest (F) Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -4118,7 +4105,7 @@ CancelRequest (F) -错误和通知消息域 +错误和通知消息字段 本节描述了ErrorResponse和NoticeResponse消息中可能出现的字段。每个字段类型都有一个单字节的标识符。 @@ -4132,11 +4119,7 @@ CancelRequest (F) - 严重性: 字段内容为ERROR, FATAL, 或 - PANIC (在错误消息中), 或 - WARNING, NOTICE, DEBUG, - INFO, 或 LOG (在通知消息中), - 或者这些内容的本地化翻译。始终存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中),或这些内容的本地化翻译。始终存在。 @@ -4146,11 +4129,7 @@ CancelRequest (F) - 严重性:字段内容为 ERRORFATAL 或 - PANIC(在错误消息中),或 WARNINGNOTICEDEBUG、 - INFOLOG(在通知消息中)。 - 这与S字段相同,只是内容不会被本地化。仅在由PostgreSQL版本9.6 - 及更高版本生成的消息中存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中)。它与 S 字段相同,只是内容从不本地化。仅在 PostgreSQL 9.6 及更高版本生成的消息中存在。 @@ -4160,7 +4139,7 @@ CancelRequest (F) - Code: 错误的SQLSTATE代码(参见)。不可本地化。始终存在。 + 代码:错误的 SQLSTATE 代码(见 )。不可本地化。始终存在。 @@ -4170,9 +4149,7 @@ CancelRequest (F) - 消息: 主要的人类可读错误消息。 - 这应该准确但简洁(通常一行)。 - 总是存在。 + 消息:主要的可读错误消息。应准确而简洁(通常为一行)。始终存在。 @@ -4182,7 +4159,7 @@ CancelRequest (F) - 详细信息:一个可选的次要错误消息,提供有关问题的更多详细信息。可能会跨多行。 + 详细信息:可选的次要错误消息,提供有关该问题的更多细节。可能占多行。 @@ -4192,9 +4169,7 @@ CancelRequest (F) - 提示: 关于问题应该怎么做的一个可选建议。 - 这意在与细节不同,它提供建议(可能不合适)而不是硬性事实。 - 可能会跨越多行。 + 提示:可选的建议,说明如何处理该问题。它与详细信息的区别在于,它提供建议(可能并不合适),而非确凿事实。可能占多行。 @@ -4236,9 +4211,7 @@ CancelRequest (F) - Where: 错误发生的上下文指示。 - 目前包括活动的过程语言函数和内部生成查询的调用堆栈回溯。 - 跟踪每行一个条目,最近的在前。 + 上下文:说明错误发生时的上下文。目前包括活跃的过程语言函数和内部生成的查询的调用栈回溯。回溯每行一个条目,最近的调用在前。 @@ -4248,7 +4221,7 @@ CancelRequest (F) - Schema name: 如果错误与特定数据库对象相关联,则为包含该对象的模式的名称(如果有)。 + 模式名:如果错误与某个特定数据库对象有关,则为包含该对象的模式名称(如果有)。 @@ -4258,7 +4231,7 @@ CancelRequest (F) - 表名: 如果错误与特定表相关联,则为表的名称。(有关表模式名称的名称,请参考模式名称字段。) + 表名:如果错误与某个特定表有关,则为该表的名称。(表所在模式的名称见模式名字段。) @@ -4268,7 +4241,7 @@ CancelRequest (F) - 列名: 如果错误与特定表列相关联,则为列的名称。(请参考模式和表名字段以识别表。) + 列名:如果错误与某个特定表列有关,则为该列的名称。(通过模式名和表名字段确定该表。) @@ -4278,8 +4251,7 @@ CancelRequest (F) - 数据类型名称: 如果错误与特定数据类型相关联,则为数据类型的名称。 - (有关数据类型模式的名称,请参阅模式名称字段。) + 数据类型名:如果错误与某个特定数据类型有关,则为该数据类型的名称。(数据类型所在模式的名称见模式名字段。) @@ -4289,8 +4261,7 @@ CancelRequest (F) - 约束名称: 如果错误与特定约束相关联,则为约束的名称。请参考上面列出的字段,了解相关表或域。 - (为此,即使索引不是使用约束语法创建的,也将其视为约束。) + 约束名:如果错误与某个特定约束有关,则为该约束的名称。相关的表或域见上述字段。(这里将索引也视为约束,即使它不是用约束语法创建的。) @@ -4300,7 +4271,7 @@ CancelRequest (F) - 文件: 报告错误的源代码位置的文件名。 + 文件:报告错误的源代码位置所在的文件名。 @@ -4310,7 +4281,7 @@ CancelRequest (F) - Line: 源代码位置的行号,报告错误的位置。 + 行号:报告错误的源代码位置所在的行号。 @@ -4320,7 +4291,7 @@ CancelRequest (F) - Routine: 报告错误的源代码例程的名称。 + 例程:报告错误的源代码例程的名称。 @@ -4330,15 +4301,12 @@ CancelRequest (F) - 模式名称、表名称、列名称、数据类型名称和约束名称的字段仅针对有限数量的错误类型提供; - 请参阅。前端不应假设任何这些字段的存在就保证了另一个字段的存在。 - 核心错误源观察到上述相互关系,但用户定义的函数可能以其他方式使用这些字段。 - 同样地,客户端不应假设这些字段表示当前数据库中的当代对象。 + 模式名、表名、列名、数据类型名和约束名字段仅针对有限的几类错误提供,见 。前端不应假设其中任何字段的存在就保证了另一个字段的存在。核心错误源遵循上述相互关系,但用户定义的函数可能以其他方式使用这些字段。同样,客户端不应假设这些字段表示当前数据库中现存的对象。 - 客户端负责格式化显示的信息以满足其需求;特别是应根据需要换行。错误消息字段中出现的换行符应被视为段落分隔符,而不是换行符。 + 客户端负责按自身需要格式化显示的信息;尤其应根据需要将长行断开。错误消息字段中的换行符应视为段落分隔符,而非行分隔符。 @@ -4366,7 +4334,7 @@ CancelRequest (F) - 将消息标识为开始消息。 + 将该消息标识为 Begin 消息。 @@ -4410,7 +4378,7 @@ CancelRequest (F) - 标识消息为提交消息。 + 将该消息标识为 Commit 消息。 @@ -4459,7 +4427,7 @@ CancelRequest (F) Byte1('O') -标识消息为复制源消息。 +将该消息标识为 Origin 消息。 @@ -4481,7 +4449,7 @@ CancelRequest (F) - 请注意,在单个事务中可能存在多个Origin消息。 + 注意,单个事务中可能有多条 Origin 消息。 @@ -4496,7 +4464,7 @@ CancelRequest (F) Byte1('R') -将该消息标识为关系消息。 +将该消息标识为 Relation 消息。 @@ -4523,7 +4491,7 @@ CancelRequest (F) - 关系的复制标识设置(与relreplidentpg_class中相同)。 + 关系的复制标识设置(与 pg_class 中的 relreplident 相同)。 @@ -4558,7 +4526,7 @@ CancelRequest (F) - 列的类型修饰符 (atttypmod)。 + 列的类型修饰符(atttypmod)。 @@ -4577,7 +4545,7 @@ CancelRequest (F) Byte1('Y') -将该消息标识为类型消息。 +将该消息标识为 Type 消息。 @@ -4613,13 +4581,13 @@ CancelRequest (F) Byte1('I') -将该消息标识为插入消息。 +将该消息标识为 Insert 消息。 Int32 -关系的 ID,与关系消息中的 ID 对应。 +关系的 ID,与 Relation 消息中的 ID 对应。 @@ -4650,13 +4618,13 @@ CancelRequest (F) Byte1('U') -将该消息标识为更新消息。 +将该消息标识为 Update 消息。 Int32 -关系的 ID,与关系消息中的 ID 对应。 +关系的 ID,与 Relation 消息中的 ID 对应。 @@ -4712,13 +4680,13 @@ CancelRequest (F) Byte1('D') -将该消息标识为删除消息。 +将该消息标识为 Delete 消息。 Int32 -关系的 ID,与关系消息中的 ID 对应。 +关系的 ID,与 Relation 消息中的 ID 对应。 @@ -4759,7 +4727,7 @@ CancelRequest (F) Byte1('T') -将该消息标识为截断消息。 +将该消息标识为 Truncate 消息。 @@ -4780,7 +4748,7 @@ CancelRequest (F) Int32 -关系的 ID,与关系消息中的 ID 对应。每个关系都重复出现此字段。 +关系的 ID,与 Relation 消息中的 ID 对应。每个关系都重复出现此字段。 diff --git a/zh/12/rangetypes.sgml b/zh/12/rangetypes.sgml index e29cda85..e9983d1d 100644 --- a/zh/12/rangetypes.sgml +++ b/zh/12/rangetypes.sgml @@ -4,7 +4,7 @@ 范围类型 - range type + 范围类型 @@ -18,7 +18,9 @@ 内置范围类型 - PostgreSQL 提供以下内置范围类型: + + PostgreSQL 自带下列内置范围类型: + int4rangeinteger 的范围 @@ -37,7 +39,9 @@ daterangedate 的范围 - 此外,还可以定义自己的范围类型;参见了解更多信息。 + + 此外,你还可以定义自己的范围类型;详见。 + @@ -92,15 +96,15 @@ SELECT isempty(numrange(1, 5)); 无限(无界)范围 - 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作 +/-infinity,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的 +/-infinity 值。 + 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作正负无穷大,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的正负无穷大值。 - 具有infinity概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 + 具有无穷大概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 - 函数lower_infupper_inf分别测试范围的下界和上界是否为无限。 + 函数lower_infupper_inf分别测试范围是否没有下界和上界。 @@ -259,23 +263,23 @@ SELECT '[11:10, 23:00]'::timerange; 索引 - range type - indexes on + 范围类型 + 索引 可以为范围类型的表列创建 GiST 和 SP-GiST 索引。例如,创建 GiST 索引: CREATE INDEX reservation_idx ON reservation USING GIST (during); -GiST 或 SP-GiST 索引可以加速涉及以下范围操作符的查询:=, - &&, - <@, - @>, - <<, - >>, - -|-, +GiST 或 SP-GiST 索引可以加速涉及以下范围操作符的查询:=、 + &&、 + <@、 + @>、 + <<、 + >>、 + -|-&<&>(参见了解更多信息)。 - 此外,也可以为范围类型的表列创建 B-树和哈希索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和哈希支持主要是为了允许在查询内部进行排序和哈希,而不是用于创建实际的索引。 + 此外,也可以为范围类型的表列创建 B-树和 hash 索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和 hash 支持主要是为了允许在查询内部进行排序和 hash 运算,而不是用于创建实际的索引。 @@ -284,8 +288,8 @@ CREATE INDEX reservation_idx ON reservation USING GIST (during); 范围上的约束 - range type - exclude + 范围类型 + 排他约束 diff --git a/zh/12/ref/alter_extension.sgml b/zh/12/ref/alter_extension.sgml index 86286dec..ed782ba4 100644 --- a/zh/12/ref/alter_extension.sgml +++ b/zh/12/ref/alter_extension.sgml @@ -170,7 +170,7 @@ ALTER EXTENSION name DROP 要添加到扩展中或从扩展中移除的对象名称。表、聚合、域、外部表、函数、 - 操作符、操作符类、操作符族、过程、例程、序列、文本搜索对象、类型和视图的名称 + 操作符、操作符类、操作符族、过程、例程、序列、文本检索对象、类型和视图的名称 可以带模式限定。 diff --git a/zh/12/ref/alter_tsconfig.sgml b/zh/12/ref/alter_tsconfig.sgml index 453d7ee7..02e172c8 100644 --- a/zh/12/ref/alter_tsconfig.sgml +++ b/zh/12/ref/alter_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义 + 更改一个文本检索配置的定义 @@ -45,7 +45,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义。你可以修改其从记号类型到字典的映射, + 更改一个文本检索配置的定义。你可以修改其从词元类型到词典的映射, 或者更改该配置的名称或拥有者。 @@ -67,7 +67,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 一个现有文本搜索配置的名称(可以是模式限定的)。 + 一个现有文本检索配置的名称(可以是模式限定的)。 @@ -78,7 +78,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 由该配置的解析器发出的记号类型的名称。 + 由该配置的解析器发出的词元类型的名称。 @@ -89,7 +89,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 用于指定记号类型的文本搜索字典名称。如果列出了多个字典, + 用于指定词元类型的文本检索词典名称。如果列出了多个词典, 将按指定顺序依次查阅它们。 @@ -101,7 +101,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 在映射中要替换的文本搜索字典的名称。 + 在映射中要替换的文本检索词典的名称。 @@ -113,7 +113,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA 被用来替代old_dictionary - 的文本搜索字典的名称。 + 的文本检索词典的名称。 @@ -124,7 +124,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新名称。 + 该文本检索配置的新名称。 @@ -135,7 +135,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新拥有者。 + 该文本检索配置的新拥有者。 @@ -146,21 +146,21 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新模式。 + 该文本检索配置的新模式。 - ADD MAPPING FOR形式为指定的词元类型安装要查询的字典列表;如果任何词元类型已经存在映射,则会报错。ALTER MAPPING FOR形式执行相同操作,但会先移除这些词元类型的现有映射。ALTER MAPPING REPLACE形式在任何出现旧字典的地方用new_dictionary替换old_dictionary。当出现FOR时,只对指定的词元类型执行此操作;不出现时,则对该配置的所有映射执行。DROP MAPPING形式移除指定词元类型的所有字典,使这些类型的词元被文本搜索配置忽略。如果词元类型没有映射,则会报错,除非出现IF EXISTS + ADD MAPPING FOR形式为指定的词元类型安装要查询的词典列表;如果任何词元类型已经存在映射,则会报错。ALTER MAPPING FOR形式执行相同操作,但会先移除这些词元类型的现有映射。ALTER MAPPING REPLACE形式在任何出现旧词典的地方用new_dictionary替换old_dictionary。当出现FOR时,只对指定的词元类型执行此操作;不出现时,则对该配置的所有映射执行。DROP MAPPING形式移除指定词元类型的所有词典,使这些类型的词元被文本检索配置忽略。如果词元类型没有映射,则会报错,除非出现IF EXISTS 示例 - 以下示例在my_config中使用english的任何地方,都将english字典替换为swedish字典。 + 以下示例在my_config中使用english的任何地方,都将english词典替换为swedish词典。 ALTER TEXT SEARCH CONFIGURATION my_config diff --git a/zh/12/ref/alter_tsdictionary.sgml b/zh/12/ref/alter_tsdictionary.sgml index 9fedf32d..76c28ac6 100644 --- a/zh/12/ref/alter_tsdictionary.sgml +++ b/zh/12/ref/alter_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH DICTIONARY - 更改一个文本搜索字典的定义 + 更改一个文本检索词典的定义 @@ -37,14 +37,14 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - ALTER TEXT SEARCH DICTIONARY更改文本搜索字典的 - 定义。你可以更改该字典的模板相关选项,也可以更改该字典的名称或拥有者。 + ALTER TEXT SEARCH DICTIONARY更改文本检索词典的 + 定义。你可以更改该词典的模板相关选项,也可以更改该词典的名称或拥有者。 - 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该字典 + 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该词典 的拥有者。 @@ -59,7 +59,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 一个现有文本搜索字典的名称(可以是模式限定的)。 + 一个现有文本检索词典的名称(可以是模式限定的)。 @@ -70,7 +70,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -81,7 +81,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 模板相关选项要使用的新值。如果省略等号和值,则会从该字典中移除 + 模板相关选项要使用的新值。如果省略等号和值,则会从该词典中移除 该选项之前的设置,从而允许使用默认值。 @@ -93,7 +93,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新名称。 + 该文本检索词典的新名称。 @@ -104,7 +104,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新拥有者。 + 该文本检索词典的新拥有者。 @@ -115,7 +115,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新模式。 + 该文本检索词典的新模式。 @@ -134,7 +134,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 下面的示例命令更改了一个基于 Snowball 的字典的停用词列表。其他参数 + 下面的示例命令更改了一个基于 Snowball 的词典的停用词列表。其他参数 保持不变。 @@ -160,7 +160,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( language = dutch, StopWords ); - 下面的示例命令更新了该字典的定义,但实际上并没有做 + 下面的示例命令更新了该词典的定义,但实际上并没有做 任何更改。 @@ -168,7 +168,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( dummy ); (之所以可行,是因为选项移除代码在不存在该选项时也不会报错。) - 这种技巧在修改该字典的配置文件时很有用:ALTER + 这种技巧在修改该词典的配置文件时很有用:ALTER 会强制现有数据库会话重新读取配置文件,而如果它们先前已经读取过这 些文件,本来是不会再次读取的。 diff --git a/zh/12/ref/alter_tsparser.sgml b/zh/12/ref/alter_tsparser.sgml index 0844cb0a..ccc73f05 100644 --- a/zh/12/ref/alter_tsparser.sgml +++ b/zh/12/ref/alter_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH PARSER - 更改一个全文检索解析器的定义 + 更改一个文本检索解析器的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA 描述 - ALTER TEXT SEARCH PARSER更改全文检索解析器的定义。 + ALTER TEXT SEARCH PARSER更改文本检索解析器的定义。 当前唯一支持的功能是更改该解析器的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA name - 一个现有全文检索解析器的名称(可以是模式限定的)。 + 一个现有文本检索解析器的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_name - 该全文检索解析器的新名称。 + 该文本检索解析器的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_schema - 该全文检索解析器的新模式。 + 该文本检索解析器的新模式。 diff --git a/zh/12/ref/alter_tstemplate.sgml b/zh/12/ref/alter_tstemplate.sgml index a3eec599..9c9dfc2c 100644 --- a/zh/12/ref/alter_tstemplate.sgml +++ b/zh/12/ref/alter_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH TEMPLATE - 更改一个文本搜索模板的定义 + 更改一个文本检索模板的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA 描述 - ALTER TEXT SEARCH TEMPLATE更改文本搜索模板的定义。 + ALTER TEXT SEARCH TEMPLATE更改文本检索模板的定义。 当前唯一支持的功能是更改该模板的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA name - 一个现有文本搜索模板的名称(可以是模式限定的)。 + 一个现有文本检索模板的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_name - 该文本搜索模板的新名称。 + 该文本检索模板的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_schema - 该文本搜索模板的新模式。 + 该文本检索模板的新模式。 diff --git a/zh/12/ref/comment.sgml b/zh/12/ref/comment.sgml index 89b06fe3..68533da6 100644 --- a/zh/12/ref/comment.sgml +++ b/zh/12/ref/comment.sgml @@ -116,7 +116,7 @@ COMMENT ON rule_name trigger_name - 要添加注释的对象名称。表、聚合、排序规则、转换、域、外部表、函数、索引、操作符、操作符类、操作符族、过程、例程、序列、统计信息、文本搜索对象、类型和视图的名称可以带模式限定。为列添加注释时,relation_name必须引用表、视图、复合类型或外部表。 + 要添加注释的对象名称。表、聚合、排序规则、转换、域、外部表、函数、索引、操作符、操作符类、操作符族、过程、例程、序列、统计信息、文本检索对象、类型和视图的名称可以带模式限定。为列添加注释时,relation_name必须引用表、视图、复合类型或外部表。 diff --git a/zh/12/ref/create_tsconfig.sgml b/zh/12/ref/create_tsconfig.sgml index 974ef42a..1d4ceca2 100644 --- a/zh/12/ref/create_tsconfig.sgml +++ b/zh/12/ref/create_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH CONFIGURATION - 定义一个新的文本搜索配置 + 定义一个新的文本检索配置 @@ -33,24 +33,24 @@ CREATE TEXT SEARCH CONFIGURATION name CREATE TEXT SEARCH CONFIGURATION - 创建一个新的文本搜索配置。文本搜索配置指定一个能把字符串拆分为记号 - 的文本搜索解析器,以及一些可用于判断哪些记号对搜索有意义的词典。 + 创建一个新的文本检索配置。文本检索配置指定一个能把字符串拆分为词元 + 的文本检索解析器,以及一些可用于判断哪些词元对搜索有意义的词典。 - 如果只指定了解析器,那么新文本搜索配置最初没有从记号类型到词典的映射, + 如果只指定了解析器,那么新文本检索配置最初没有从词元类型到词典的映射, 因而会忽略所有词。要让该配置真正可用,必须使用后续的ALTER TEXT SEARCH CONFIGURATION命令创建映射。 - 另一种方式是复制一个现有的文本搜索配置。 + 另一种方式是复制一个现有的文本检索配置。 - 如果给出了一个模式名称,则文本搜索配置会被创建在指定的模式中。否则它将会 + 如果给出了一个模式名称,则文本检索配置会被创建在指定的模式中。否则它将会 被创建在当前模式中。 - 定义该文本搜索配置的用户会成为其拥有者。 + 定义该文本检索配置的用户会成为其拥有者。 @@ -66,7 +66,7 @@ CREATE TEXT SEARCH CONFIGURATION namename - 要创建的文本搜索配置的名称。该名称可以是模式限定的。 + 要创建的文本检索配置的名称。该名称可以是模式限定的。 @@ -75,7 +75,7 @@ CREATE TEXT SEARCH CONFIGURATION nameparser_name - 此配置要使用的文本搜索解析器的名称。 + 此配置要使用的文本检索解析器的名称。 @@ -84,7 +84,7 @@ CREATE TEXT SEARCH CONFIGURATION namesource_config - 要复制的现有文本搜索配置的名称。 + 要复制的现有文本检索配置的名称。 diff --git a/zh/12/ref/create_tsdictionary.sgml b/zh/12/ref/create_tsdictionary.sgml index 2dbca552..75218295 100644 --- a/zh/12/ref/create_tsdictionary.sgml +++ b/zh/12/ref/create_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH DICTIONARY - 定义一个新的文本搜索字典 + 定义一个新的文本检索词典 @@ -33,19 +33,19 @@ CREATE TEXT SEARCH DICTIONARY name CREATE TEXT SEARCH DICTIONARY创建一个 - 新的文本搜索字典。文本搜索字典指定一种在搜索时识别哪些词值得关注、 - 哪些词不值得关注的方式。字典依赖于文本搜索模板,后者规定了实际执行 - 这项工作的函数。通常,字典会提供一些选项,用来控制模板函数的具体 + 新的文本检索词典。文本检索词典指定一种在搜索时识别哪些词值得关注、 + 哪些词不值得关注的方式。词典依赖于文本检索模板,后者规定了实际执行 + 这项工作的函数。通常,词典会提供一些选项,用来控制模板函数的具体 行为。 - 如果给出了一个模式名称,那么该文本搜索字典会被创建在指定的模式中。 + 如果给出了一个模式名称,那么该文本检索词典会被创建在指定的模式中。 否则它会被创建在当前模式中。 - 定义文本搜索字典的用户将成为其拥有者。 + 定义文本检索词典的用户将成为其拥有者。 @@ -61,7 +61,7 @@ CREATE TEXT SEARCH DICTIONARY name name - 要创建的文本搜索字典的名称。该名称可以被模式限定。 + 要创建的文本检索词典的名称。该名称可以被模式限定。 @@ -70,7 +70,7 @@ CREATE TEXT SEARCH DICTIONARY name template - 用于定义该字典基本行为的文本搜索模板名称。 + 用于定义该词典基本行为的文本检索模板名称。 @@ -79,7 +79,7 @@ CREATE TEXT SEARCH DICTIONARY name option - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -105,7 +105,7 @@ CREATE TEXT SEARCH DICTIONARY name 下面的示例命令创建了一个基于 Snowball 且使用非标准停用词列表的 - 字典。 + 词典。 diff --git a/zh/12/ref/create_tsparser.sgml b/zh/12/ref/create_tsparser.sgml index 6af67ab8..5f2e5184 100644 --- a/zh/12/ref/create_tsparser.sgml +++ b/zh/12/ref/create_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH PARSER - 定义一个新的全文检索解析器 + 定义一个新的文本检索解析器 @@ -36,19 +36,19 @@ CREATE TEXT SEARCH PARSER name ( CREATE TEXT SEARCH PARSER创建一个 - 新的全文检索解析器。全文检索解析器定义了一种方法,用于将文本字符串 - 拆分成记号并为这些记号指定类型(类别)。解析器本身并没有太大用处, - 必须与一些全文检索字典一起绑定到一个全文检索配置中,才能用于搜索。 + 新的文本检索解析器。文本检索解析器定义了一种方法,用于将文本字符串 + 拆分成词元并为这些词元指定类型(类别)。解析器本身并没有太大用处, + 必须与一些文本检索词典一起绑定到一个文本检索配置中,才能用于搜索。 - 如果给出了一个模式名称,那么全文检索解析器将被创建在指定的模式中。 + 如果给出了一个模式名称,那么文本检索解析器将被创建在指定的模式中。 否则它会被创建在当前模式中。 要使用CREATE TEXT SEARCH PARSER,你必须是超级用户。 - 之所以有此限制,是因为错误的全文检索解析器定义可能会让服务器陷入 + 之所以有此限制,是因为错误的文本检索解析器定义可能会让服务器陷入 混乱,甚至崩溃。 @@ -65,7 +65,7 @@ CREATE TEXT SEARCH PARSER name ( name - 要创建的全文检索解析器的名称。该名称可以是模式限定的。 + 要创建的文本检索解析器的名称。该名称可以是模式限定的。 @@ -83,7 +83,7 @@ CREATE TEXT SEARCH PARSER name ( gettoken_function - 该解析器的获取下一个记号的函数名称。 + 该解析器的获取下一个词元的函数名称。 @@ -101,7 +101,7 @@ CREATE TEXT SEARCH PARSER name ( lextypes_function - 该解析器的 lextypes 函数的名称(该函数返回它所产生的记号类型集合的 + 该解析器的 lextypes 函数的名称(该函数返回它所产生的词元类型集合的 信息)。 @@ -111,7 +111,7 @@ CREATE TEXT SEARCH PARSER name ( headline_function - 该解析器的 headline 函数的名称(该函数对一组记号生成摘要)。 + 该解析器的 headline 函数的名称(该函数对一组词元生成摘要)。 diff --git a/zh/12/ref/create_tstemplate.sgml b/zh/12/ref/create_tstemplate.sgml index 5dd2e1c0..24ee925e 100644 --- a/zh/12/ref/create_tstemplate.sgml +++ b/zh/12/ref/create_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH TEMPLATE - 定义一个新的全文检索模板 + 定义一个新的文本检索模板 @@ -33,22 +33,22 @@ CREATE TEXT SEARCH TEMPLATE name ( CREATE TEXT SEARCH TEMPLATE创建一个 - 新的全文检索模板。全文检索模板定义实现全文检索字典的函数。模板本身 - 并无直接用途,必须先实例化为字典后才能使用。字典通常会指定要传递给 + 新的文本检索模板。文本检索模板定义实现文本检索词典的函数。模板本身 + 并无直接用途,必须先实例化为词典后才能使用。词典通常会指定要传递给 模板函数的参数。 - 如果给出了模式名称,则全文检索模板会被创建在指定模式中。否则它会被 + 如果给出了模式名称,则文本检索模板会被创建在指定模式中。否则它会被 创建在当前模式中。 要使用CREATE TEXT SEARCH TEMPLATE,你 - 必须是超级用户。之所以有此限制,是因为错误的全文检索模板定义可能使 - 服务器陷入混乱,甚至崩溃。将模板与字典分离的原因在于,模板封装了定 - 义字典时那些不安全的方面。而在定义字典时可设置的参数, - 对非特权用户来说是安全的,因此创建字典不必是特权操作。 + 必须是超级用户。之所以有此限制,是因为错误的文本检索模板定义可能使 + 服务器陷入混乱,甚至崩溃。将模板与词典分离的原因在于,模板封装了定 + 义词典时那些不安全的方面。而在定义词典时可设置的参数, + 由普通用户设置也是安全的,因此创建词典不必是特权操作。 @@ -64,7 +64,7 @@ CREATE TEXT SEARCH TEMPLATE name ( name - 要创建的全文检索模板名称。该名称可以是模式限定的。 + 要创建的文本检索模板名称。该名称可以是模式限定的。 diff --git a/zh/12/ref/drop_opclass.sgml b/zh/12/ref/drop_opclass.sgml index 9d67dc64..545a2517 100644 --- a/zh/12/ref/drop_opclass.sgml +++ b/zh/12/ref/drop_opclass.sgml @@ -110,7 +110,7 @@ DROP OPERATOR CLASS [ IF EXISTS ] name示例 - 移除 B-tree 操作符类widget_ops: + 移除 B-树操作符类widget_ops DROP OPERATOR CLASS widget_ops USING btree; diff --git a/zh/12/ref/drop_tsconfig.sgml b/zh/12/ref/drop_tsconfig.sgml index ea139802..b3ebb9d1 100644 --- a/zh/12/ref/drop_tsconfig.sgml +++ b/zh/12/ref/drop_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH CONFIGURATION - 移除一个文本搜索配置 + 移除一个文本检索配置 @@ -29,7 +29,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 描述 - DROP TEXT SEARCH CONFIGURATION删除一个现有文本搜索配置。 + DROP TEXT SEARCH CONFIGURATION删除一个现有文本检索配置。 要执行此命令,你必须是该配置的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name IF EXISTS - 如果该文本搜索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name name - 现有文本搜索配置的名称(可以被模式限定)。 + 现有文本检索配置的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name CASCADE - 自动删除依赖于该文本搜索配置的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索配置的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name RESTRICT - 如果有任何对象依赖于该文本搜索配置,则拒绝删除该配置。这是默认值。 + 如果有任何对象依赖于该文本检索配置,则拒绝删除该配置。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 示例 - 移除文本搜索配置my_english: + 移除文本检索配置my_english DROP TEXT SEARCH CONFIGURATION my_english; 如果已有索引在to_tsvector调用中引用了该配置, - 此命令将不会成功。加上CASCADE可以在删除该文本搜索配置的同时删除这类索引。 + 此命令将不会成功。加上CASCADE可以在删除该文本检索配置的同时删除这类索引。 diff --git a/zh/12/ref/drop_tsdictionary.sgml b/zh/12/ref/drop_tsdictionary.sgml index 316c5d00..0f7751a1 100644 --- a/zh/12/ref/drop_tsdictionary.sgml +++ b/zh/12/ref/drop_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH DICTIONARY - 移除一个文本搜索字典 + 移除一个文本检索词典 @@ -29,8 +29,8 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name描述 - DROP TEXT SEARCH DICTIONARY删除一个现有文本搜索字典。 - 要执行此命令,你必须是该字典的拥有者。 + DROP TEXT SEARCH DICTIONARY删除一个现有文本检索词典。 + 要执行此命令,你必须是该词典的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索字典不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索词典不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] namename - 一个现有文本搜索字典的名称(可以被模式限定)。 + 一个现有文本检索词典的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索字典的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索词典的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索字典,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索词典,则拒绝删除它。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name示例 - 移除文本搜索字典english: + 移除文本检索词典english DROP TEXT SEARCH DICTIONARY english; - 如果已有文本搜索配置使用该字典,此命令将不会成功。 - 加上CASCADE可以在删除字典的同时删除这类配置。 + 如果已有文本检索配置使用该词典,此命令将不会成功。 + 加上CASCADE可以在删除词典的同时删除这类配置。 diff --git a/zh/12/ref/drop_tsparser.sgml b/zh/12/ref/drop_tsparser.sgml index a65f47be..ea74f0f8 100644 --- a/zh/12/ref/drop_tsparser.sgml +++ b/zh/12/ref/drop_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH PARSER - 移除一个文本搜索解析器 + 移除一个文本检索解析器 @@ -29,7 +29,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name描述 - DROP TEXT SEARCH PARSER删除一个现有文本搜索解析器。 + DROP TEXT SEARCH PARSER删除一个现有文本检索解析器。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] namename - 一个现有文本搜索解析器的名称(可以被模式限定)。 + 一个现有文本检索解析器的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索解析器的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索解析器的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索解析器,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索解析器,则拒绝删除它。这是默认值。 @@ -82,13 +82,13 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name示例 - 移除文本搜索解析器my_parser: + 移除文本检索解析器my_parser DROP TEXT SEARCH PARSER my_parser; - 如果已有文本搜索配置使用该解析器,此命令将不会成功。 + 如果已有文本检索配置使用该解析器,此命令将不会成功。 加上CASCADE可以在删除解析器的同时删除这类配置。 diff --git a/zh/12/ref/drop_tstemplate.sgml b/zh/12/ref/drop_tstemplate.sgml index fa1faab0..3a44c927 100644 --- a/zh/12/ref/drop_tstemplate.sgml +++ b/zh/12/ref/drop_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH TEMPLATE - 移除一个文本搜索模板 + 移除一个文本检索模板 @@ -29,7 +29,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name描述 - DROP TEXT SEARCH TEMPLATE删除一个现有文本搜索模板。 + DROP TEXT SEARCH TEMPLATE删除一个现有文本检索模板。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] namename - 现有文本搜索模板的名称(可以被模式限定)。 + 现有文本检索模板的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索模板的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索模板的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索模板,则拒绝删除该模板。这是默认值。 + 如果有任何对象依赖于该文本检索模板,则拒绝删除该模板。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name示例 - 移除文本搜索模板thesaurus: + 移除文本检索模板thesaurus DROP TEXT SEARCH TEMPLATE thesaurus; - 如果已有文本搜索字典使用该模板,此命令将不会成功。加上CASCADE - 可以在删除该模板的同时删除这类字典。 + 如果已有文本检索词典使用该模板,此命令将不会成功。加上CASCADE + 可以在删除该模板的同时删除这类词典。 diff --git a/zh/12/ref/initdb.sgml b/zh/12/ref/initdb.sgml index 9a7d0995..62c3d204 100644 --- a/zh/12/ref/initdb.sgml +++ b/zh/12/ref/initdb.sgml @@ -142,7 +142,7 @@ PostgreSQL documentation - + @@ -154,7 +154,7 @@ PostgreSQL documentation - + @@ -213,7 +213,7 @@ PostgreSQL documentation - 使initdb从文件中读取引导超级用户的密码。文件的第一行会被当作密码。 + 使initdb从文件中读取数据库超级用户的密码。文件的第一行会被当作密码。 @@ -233,7 +233,7 @@ PostgreSQL documentation - 设置默认文本搜索配置。更多信息见 + 设置默认文本检索配置。更多信息见 @@ -244,10 +244,9 @@ PostgreSQL documentation - 选择数据库超级用户的用户名。默认值是运行 - initdb的实际用户名称。超级用户的名称本身 - 并不重要,不过即使操作系统用户名称不同,人们也可能选择沿用惯常 - 的名称postgres。 + 选择数据库超级用户的用户名。默认值是运行initdb的有效用户的名称。 + 超级用户的名称本身并不重要,不过即使操作系统用户名称不同,也可以选择沿用惯常的名称 + postgres @@ -257,7 +256,7 @@ PostgreSQL documentation - 使initdb提示输入要赋给引导超级用户的密码。如果不打算使用密码认证, + 使initdb提示输入要赋给数据库超级用户的密码。如果不打算使用密码认证, 这一点并不重要。否则,在设置密码之前将无法使用密码认证。 diff --git a/zh/12/ref/pgbench.sgml b/zh/12/ref/pgbench.sgml index cc418214..b51dd306 100644 --- a/zh/12/ref/pgbench.sgml +++ b/zh/12/ref/pgbench.sgml @@ -36,7 +36,7 @@ PostgreSQL documentation 描述 - pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,必要时可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 + pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,也可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 @@ -57,13 +57,15 @@ tps = 85.296346 (excluding connections establishing) 前六行报告了一些最重要的参数设置。下一行报告已完成的事务数和预期的事务数(后者就是客户端数与每个客户端的事务数的乘积);除非运行在完成前失败,否则这两个数应该相等。(在 模式下,只打印实际的事务数。)最后两行报告每秒事务数,分别计入和不计入启动数据库会话的时间。 - 默认的类 TPC-B 事务测试要求预先建立特定的表。pgbench应使用(初始化)选项调用,以创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: + + 默认的类 TPC-B 事务测试要求预先建立特定的表。应使用(初始化)选项调用pgbench来创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: + + pgbench -i other-options dbname - 其中, - dbname是已创建好的、用于执行测试的数据库名称。(可能还需要使用, - 和/或选项来指定如何连接到数据库服务器。) + 其中dbname是已创建好的、用于执行测试的数据库名称。(可能还需要使用和/或选项来指定如何连接到数据库服务器。) + @@ -76,14 +78,14 @@ pgbench -i other-options 在默认的比例因子 1 下,这些表最初包含如下行数: -table # of rows +表 行数 --------------------------------- pgbench_branches 1 pgbench_tellers 10 pgbench_accounts 100000 pgbench_history 0 - 可以使用(比例因子)选项来增加行数,而且在大多数场景下也确实应该这样做。此时还可以配合使用(fillfactor)选项。 + 可以使用(比例因子)选项来增加行数,而且在大多数场景下通常也应该这样做。此时还可以配合使用(fillfactor)选项。 @@ -102,14 +104,14 @@ pgbench options d 选项 - 下面分成三个部分。数据库初始化期间使用的选项和运行基准时会使用不同的选项,但也有一些选项在两种情况下都使用。 + 以下内容分为三个小节。数据库初始化和运行基准测试时使用不同的选项,但有些选项在这两种情况下都适用。 初始化选项 - pgbench 接受以下用于初始化的命令行参数: + pgbench 接受以下命令行初始化参数: @@ -304,7 +306,7 @@ pgbench options d 基准测试选项 - pgbench 接受以下用于基准测试的命令行参数: + pgbench 接受以下命令行基准测试参数: @@ -441,13 +443,13 @@ pgbench options d 用于向服务器提交查询的协议: - simple: 使用简单查询协议。 + simple:使用简单查询协议。 - extended: 使用扩展查询协议。 + extended:使用扩展查询协议。 - prepared: 使用带有预备语句的扩展查询协议。 + prepared:使用带有预备语句的扩展查询协议。 prepared模式下,pgbench从第二次查询迭代开始复用解析分析结果,因此pgbench比其他模式运行得更快。 @@ -532,7 +534,7 @@ pgbench options d 较高的计划滞后时间表明,在所选客户端数和线程数下,系统无法以指定速率处理事务。 当平均事务执行时间长于事务之间的计划间隔时,后续事务会不断进一步落后, - 而计划滞后时间也会随着测试持续时间增加。在这种情况下,只能降低指定的事务速率。 + 而计划滞后时间也会随着测试持续时间增加。在这种情况下,需要降低指定的事务速率。 @@ -544,7 +546,7 @@ pgbench options d pgbench输出中报告指定的比例因子。 - 对于内置测试,这通常没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 + 对于内置测试,这没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 但在只测试自定义基准(选项)时, 除非使用此选项,否则比例因子会被报告为 1。 @@ -826,7 +828,7 @@ pgbench options d - 在PostgreSQL 9.6 之前,脚本文件中的 SQL 命令以换行符结束,因此不能跨行续写。现在,连续的 SQL 命令之间必须用分号分隔(不过,如果 SQL 命令后面跟着元命令,则不需要分号)。如果需要创建适用于新旧版本pgbench的脚本文件,请务必将每条 SQL 命令写在单独一行,并以分号结尾。 + 在PostgreSQL 9.6 之前,脚本文件中的 SQL 命令以换行结束,因此不能跨行。现在连续 SQL 命令之间必须用分号分隔(如果 SQL 命令后面跟着一个元命令,则不需要分号)。如果需要创建一个既能在旧版也能在新版pgbench下工作的脚本文件,务必将每个 SQL 命令写在单独一行,并以分号结束。 @@ -859,7 +861,7 @@ pgbench options d default_seed - 默认在哈希函数中使用的种子 + 默认在 hash 函数中使用的种子 @@ -876,7 +878,7 @@ pgbench options d
- 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令及其参数之间以空白分隔。支持的元命令如下: + 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令的参数以空白分隔。支持的元命令如下: @@ -900,7 +902,7 @@ UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid RETURNING abalance \gset --- compound of two queries +-- 两个查询的组合 SELECT 1 \; SELECT 2 AS two, 3 AS three \gset p_
@@ -991,7 +993,7 @@ SELECT 2 AS two, 3 AS three \gset p_
- command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在其开头再写一个冒号。 + command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在argument开头再写一个冒号。 @@ -1257,14 +1259,14 @@ SELECT 2 AS two, 3 AS three \gset p_ hash_fnv1a(a [, seed ] ) integer - FNV-1a 哈希 + FNV-1a hash hash_fnv1a(10, 5432) -7793829335365542153 hash_murmur2(a [, seed ] ) integer - MurmurHash2 哈希 + MurmurHash2 hash hash_murmur2(10, 5432) -5817877081768721676 @@ -1306,7 +1308,7 @@ SELECT 2 AS two, 3 AS three \gset p_ pow(x, y), power(x, y) double - 指数 + 求幂 pow(2.0, 10), power(2.0, 10) 1024.0 @@ -1355,33 +1357,36 @@ SELECT 2 AS two, 3 AS three \gset p_ - 对于指数分布,parameter通过在以下位置截断一个快速衰减的指数分布来控制分布:parameter,然后将其投影到边界之间的整数上。准确地说,令 + + 对于指数分布,parameter通过在parameter处截断一个快速衰减的指数分布,再将其投影到边界之间的整数上,从而控制分布。准确地说,令 + f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) -则值i 位于 min 和 - max 之间(包括端点),被抽到的概率为: - f(i) - f(i + 1)。 + + 则minmax之间(含边界)的值i会以f(i) - f(i + 1)的概率被抽中。 - 直观地说,parameter越大,接近min的值被访问得越频繁,而接近max的值被访问得越少。parameter越接近 0,访问分布就越平坦(越均匀)。对该分布的一个粗略近似是:范围内最常出现的 1% 的值,即接近min的那些值,会在parameter% 的时间里被抽中。parameter的值必须严格为正。 + + 直观地说,parameter越大,越靠近min的值越容易被抽到,而越靠近max的值越不容易被抽到。parameter越接近 0,分布就越平坦(也就越均匀)。对这种分布的一个粗略近似是:范围内出现频率最高的 1% 的值,即最靠近min的那些值,大约会占到parameter% 的抽样次数。parameter必须严格大于 0。 + - 对于高斯分布,该区间映射到标准正态分布(经典的钟形高斯曲线),左侧截断于 -parameter,右侧截断于 +parameter。区间中部的值更容易被抽到。准确地说,如果 PHI(x) 为标准正态分布的累积分布函数,均值 mu 定义为 (max + min) / 2.0,并且 - + 对于高斯分布,该区间会映射到一个标准正态分布(经典钟形高斯曲线),并在左侧-parameter和右侧+parameter处截断。区间中部的值更容易被抽到。准确地说,如果PHI(x)是标准正态分布的累积分布函数,均值mu定义为(max + min) / 2.0,则有 + f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / (2.0 * PHI(parameter) - 1) - 那么,值 i 位于 min 和 - max 之间(包括端点),被抽到的概率为: - f(i + 0.5) - f(i - 0.5)。直观地说,parameter 越大,越靠近区间中部的值被抽到的频率就越高,而越靠近 min 和 - max 边界的值被抽到的频率就越低。约 67% 的值抽自区间中间的 1.0 / parameter,即均值周围相对 0.5 / parameter 的范围;95% 的值抽自区间中间的 2.0 / parameter,即均值周围相对 1.0 / parameter 的范围。例如,如果 parameter 为 4.0,则 67% 的值抽自区间中间四分之一(1.0 / 4.0)的范围(即从 - 3.0 / 8.05.0 / 8.0),95% 的值抽自区间中间一半(2.0 / 4.0)内,也就是第二和第三四分位。允许的最小parameter值为 2.0。 + 则minmax(包含边界)之间的值i被抽中的概率为:f(i + 0.5) - f(i - 0.5)。直观地说,parameter越大,越靠近区间中间的值被抽到的频率越高,而越靠近minmax边界的值被抽到的频率越低。大约 67% 的值会落在区间中部1.0 / parameter这一段内,也就是均值两侧各占区间长度0.5 / parameter的范围内;约 95% 的值会落在区间中部2.0 / parameter这一段内,也就是均值两侧各占区间长度1.0 / parameter的范围内。例如,如果parameter为 4.0,则 67% 的值会落在区间中间四分之一(1.0 / 4.0)内,也就是从3.0 / 8.05.0 / 8.0;95% 的值会落在区间中间一半(2.0 / 4.0)内,也就是第二和第三四分位。允许的最小parameter值为 2.0。 +
- random_zipfian会生成一个有界的 Zipfian 分布。parameter定义该分布的倾斜程度。parameter越大,越靠近区间起始处的值被抽到的频率就越高。这种分布满足:假设范围从 1 开始,抽到k与抽到k+1的概率之比为((k+1)/k)**parameter。例如,random_zipfian(1, ..., 2.5)生成值1的频率大约是生成2(2/1)**2.5 = - 5.66倍,而后者的生成频率又大约是生成3(3/2)**2.5 = 2.76倍,依此类推。 + random_zipfian会生成一个有界的 Zipfian 分布。 + parameter定义该分布的倾斜程度。parameter越大,越靠近区间起始处的值被抽到的频率就越高。 + 这种分布满足:假设范围从 1 开始,抽到k与抽到k+1的概率之比为 + ((k+1)/k)**parameter。 + 例如,random_zipfian(1, ..., 2.5)生成值1的频率大约是生成2(2/1)**2.5 = 5.66倍,而生成2的频率又大约是生成3(3/2)**2.5 = 2.76倍,依此类推。 pgbench的实现基于《Non-Uniform Random Variate Generation》,Luc Devroye,Springer 1986,第 550-551 页。 @@ -1391,8 +1396,8 @@ f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / - 哈希函数 hashhash_murmur2 和 - hash_fnv1a 接受一个输入值和一个可选的种子参数。如果未提供种子,则使用 :default_seed 的值,该值随机初始化,除非通过命令行 -D 选项设置。哈希函数可以用来打散随机函数的分布,例如 random_zipfian 或 + Hash 函数 hashhash_murmur2 和 + hash_fnv1a 接受一个输入值和一个可选的种子参数。如果未提供种子,则使用 :default_seed 的值,该值随机初始化,除非通过命令行 -D 选项设置。Hash 函数可以用来打散随机函数的分布,例如 random_zipfianrandom_exponential。例如,以下 pgbench 脚本模拟了社交媒体和博客平台中可能出现的典型真实工作负载,其中少数账户产生了过多的负载: @@ -1454,8 +1459,7 @@ END; - 下面是单个客户端运行时生成的日志文件片段: - + 这里是在单个客户端运行中生成的一个日志文件的片段: 0 199 2241 0 1175850568 995598 0 200 2465 0 1175850568 998079 @@ -1463,9 +1467,8 @@ END; 0 202 2038 0 1175850569 2663 - 下面是另一个使用 --rate=100--latency-limit=5 的示例(请注意额外的 - schedule_lag 列): - + 另一个示例使用的是--rate=100以及--latency-limit=5(注意额外的 + schedule_lag列): 0 81 4621 0 1412881037 912698 3005 0 82 6173 0 1412881037 914578 4304 @@ -1475,7 +1478,8 @@ END; 0 84 4142 0 1412881037 918023 2333 0 85 2465 0 1412881037 919759 740 - 在这个示例中,事务 82 超时了,因为其延迟(6.173 ms)超过了 5 ms 的限制。接下来的两个事务被跳过,因为它们在开始前就已经超时。 + 在这个示例中,事务 82 迟到了,因为它的延迟(6.173 ms)超过了 + 5 ms 限制。接下来的两个事务被跳过,因为它们在开始之前就已经迟到了。 @@ -1500,7 +1504,7 @@ END; sum_latency_2 是区间内事务延迟的平方和, min_latency 是区间内的最小延迟,而 max_latency 是区间内的最大延迟。接下来的字段 - sum_lagsum_lag_2min_lagmax_lag 仅在使用 选项时出现。它们提供各事务等待前一事务完成的时间统计,即各事务计划开始时间与实际开始时间之间的差值。最后一个字段 skipped 仅在还使用 选项时出现。它记录因开始时间过晚而被跳过的事务数。每个事务都计入其提交时所在的时间区间。 + sum_lagsum_lag_2min_lagmax_lag 仅在使用 选项时出现。它们提供各事务等待前一事务完成的时间统计,即各事务计划开始时间与实际开始时间之间的差值。最后一个字段 skipped 仅在还使用 选项时出现。它记录因开始时间过晚而被跳过的事务数。每个事务都计入其提交时所在的时间区间。 @@ -1520,7 +1524,7 @@ END; - 逐语句报告 + 逐语句延迟 使用选项时,pgbench会收集每个客户端执行的每条语句所经过的事务时间。基准测试完成后,它会报告这些值的平均值,称为每条语句的延迟。 @@ -1557,11 +1561,11 @@ statement latencies in milliseconds: - 所有数值都是针对每个客户端执行的每条语句计算的,并在基准测试完成后报告。 + 如果指定了多个脚本文件,则会分别为每个脚本文件报告平均值。 - 请注意,收集计算每条语句延迟所需的额外计时信息会增加一些开销。这会降低平均执行速度,使计算出的 TPS 下降。减速程度因平台和硬件而异,差别可能很大。比较启用和未启用延迟报告时的平均 TPS 值,是衡量计时开销是否显著的好方法。 + 注意,为逐语句延迟计算收集额外的计时信息会带来一定开销。这会拖慢平均执行速度,并降低计算出的 TPS。减速幅度在很大程度上取决于平台和硬件。比较启用和未启用延迟报告时的平均 TPS 值,是判断这一计时开销是否显著的好方法。 @@ -1582,7 +1586,7 @@ statement latencies in milliseconds: - 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和空闲空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 + 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和无效空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 diff --git a/zh/12/ref/psql-ref.sgml b/zh/12/ref/psql-ref.sgml index e77d7f6a..4cbfebf2 100644 --- a/zh/12/ref/psql-ref.sgml +++ b/zh/12/ref/psql-ref.sgml @@ -47,7 +47,7 @@ PostgreSQL documentation - 把所有非空输入行按照它们被读入的形式打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 + 在读入时将所有非空输入行打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 all @@ -78,10 +78,10 @@ PostgreSQL documentation - 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,直到它处理完序列中所有的选项之后终止。 + 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,而是在按顺序处理完所有选项后终止。 - command必须是一个服务器完全可解析的命令字符串(即不包含psql相关的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: + command必须是一个服务器完全可解析的命令字符串(即不包含psql专有的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: psql -c '\x' -c 'SELECT * FROM foo;' @@ -94,7 +94,7 @@ echo '\x \\ SELECT * FROM foo;' | psql 每个SQL命令字符串传递给都作为一个单独的请求发送到服务器。 因此,即使字符串包含多个SQL命令,服务器也会将其作为单个事务执行, - 除非字符串中包含明确的BEGIN/COMMIT命令将其分成多个事务。 + 除非字符串中包含显式的BEGIN/COMMIT命令将其分成多个事务。 (有关服务器如何处理多查询字符串的更多详细信息,请参见。) 此外,psql只打印字符串中最后一条SQL命令的结果。这与从文件读取同一字符串或将其送入psql标准输入时的行为不同,因为在这些情况下,psql会分别发送每条SQL命令。 @@ -158,7 +158,7 @@ EOF - 如果filename-(连字符),则会读取标准输入,直到遇到 EOF 指示或\q元命令。这可用于将交互式输入与文件输入交错使用。不过请注意,这种情况下不会使用 Readline(很像指定了时的情况)。 + 如果filename-(连字符),则会读取标准输入,直到遇到 EOF 指示或\q元命令。这可用于将交互式输入与文件输入交错使用。不过请注意,这种情况下不会使用 Readline(很像指定了时的情况)。 @@ -172,7 +172,7 @@ EOF - 使用separator作为非对齐输出的域分隔符。这等效于\pset fieldsep或者\f。 + 使用separator作为非对齐输出的字段分隔符。这等效于\pset fieldsep或者\f
@@ -226,7 +226,7 @@ EOF - 不要使用Readline进行行编辑,也不要使用命令历史记录。这有助于在剪切和粘贴时关闭制表符展开。 + 不要使用Readline进行行编辑,也不要使用命令历史记录。这有助于在剪切和粘贴时关闭TAB 补全。
@@ -246,7 +246,7 @@ EOF - 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。 + 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展名。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。
@@ -266,7 +266,7 @@ EOF - 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息以及多种输出。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon。 + 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息和各种提示信息。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon @@ -286,7 +286,7 @@ EOF - 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户一个可以取消执行的选项。使用这个选项可以调试脚本。 + 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户,并允许取消执行。使用这个选项可以调试脚本。 @@ -296,7 +296,7 @@ EOF - 运行在单行模式中,其中新行会终止一个 SQL 命令,就像分号的作用一样。 + 运行在单行模式中,其中换行符会终止一个 SQL 命令,就像分号的作用一样。 @@ -322,7 +322,7 @@ EOF - 指定要替换HTML table标签的选项。详见\pset tableattr。 + 指定要放在HTML table标签内的选项。详见\pset tableattr @@ -343,7 +343,7 @@ EOF - 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要重置一个变量,去掉等号就行。要把一个变量置为空值,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 + 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要取消变量的设置,去掉等号就行。要把一个变量设为空字符串,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 @@ -405,7 +405,7 @@ EOF - 不读取启动文件(要么是系统范围的psqlrc文件,要么是用户的~/.psqlrc文件)。 + 不读取启动文件(既不读取系统范围的psqlrc文件,也不读取用户的~/.psqlrc文件)。 @@ -415,7 +415,7 @@ EOF - 设置非对齐输出的域分隔符为零字节。这等效于\pset fieldsep_zero。 + 设置非对齐输出的字段分隔符为零字节。这等效于\pset fieldsep_zero @@ -425,7 +425,7 @@ EOF - 设置非对齐输出的记录分隔符为零字节。例如,这对与xargs -0配合有关。这等效于\pset recordsep_zero。 + 设置非对齐输出的记录分隔符为零字节。例如,这有助于与xargs -0配合使用。这等效于\pset recordsep_zero @@ -485,10 +485,9 @@ EOF 分别指定这些参数。如果遇到一个不属于任何选项的参数, 它将被解释为数据库名(如果数据库名已经给出,则解释为数据库用户名)。 并非所有这些选项都是必需的;它们都有有用的默认值。如果省略主机名, - psql 在 Unix 上将通过 Unix 域套接字连接到本地主机上的服务器, - 在 Windows 上则通过 TCP/IP 连接到 localhost。默认端口号在编译时确定。 + psql 将通过 Unix 域套接字连接到本地主机上的服务器,而在没有 Unix 域套接字的机器上则通过 TCP/IP 连接到 localhost。默认端口号在编译时确定。 由于数据库服务器使用相同的默认值,因此在大多数情况下不必指定端口。 - 默认数据库用户名是你的操作系统用户名。数据库用户名确定后,它也会被用作默认数据库名。 + 默认用户名是你的操作系统用户名,默认数据库名也是如此。 请注意,你不能随意以任意数据库用户名连接到任意数据库。数据库管理员应当已经告知你拥有的访问权限。
@@ -549,7 +548,7 @@ testdb=> 元命令 - 你输入到psql中的任何以未加引用的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 + 你输入到psql中的任何以未加引号的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 @@ -566,7 +565,7 @@ testdb=> - 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉尾随换行)会替换反引号中的文本。在反引号包围的文本内部,不会发生特殊引用或其他处理,只有一种例外:如果出现:variable_name,且variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会被适当地引用成单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于回车和换行字符在所有平台上都无法安全引用,当变量值中出现这类字符时,:'variable_name'这种形式会打印错误消息,并且不会替换变量值。 + 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉末尾的换行符)会替换反引号中的文本。在反引号包围的文本内部,不会进行特殊的引号处理或其他处理,但出现:variable_name时,如果variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会适当地加上引号,使其成为单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于无法保证在所有平台上都能对回车和换行字符安全地加引号,当变量值中出现这类字符时,:'variable_name'形式会打印错误消息,并且不会替换变量值。 @@ -589,7 +588,7 @@ testdb=> \a - 如果当前表格输出格式是不对齐,则切换为对齐;否则切换为不对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset。 + 如果当前表格输出格式是非对齐,则切换为对齐;否则切换为非对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset @@ -610,7 +609,7 @@ testdb=> 默认情况下,参数在位置语法中被重用,但在给定conninfo字符串时不会被重用。 传递-reuse-previous=on-reuse-previous=off作为第一个参数将覆盖该默认设置。 如果参数被重用,则任何未明确指定为位置参数或在conninfo字符串中的参数将从现有连接的参数中获取。 - 一个例外是,如果使用位置语法将host设置更改为其先前值,则现有连接参数中存在的任何hostaddr设置将被删除。 + 一个例外是,如果使用位置语法更改host设置,使其不同于先前的值,则现有连接参数中存在的任何hostaddr设置将被删除。 此外,仅当用户、主机和端口设置未更改时,才会重用现有连接使用的任何密码。 当命令既不指定也不重用特定参数时,将使用libpq的默认值。 @@ -626,7 +625,7 @@ testdb=> => \c mydb myuser host.dom 6432 => \c service=foo => \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable" -=> \c -reuse-previous=on sslmode=require -- changes only sslmode +=> \c -reuse-previous=on sslmode=require -- 仅更改 sslmode => \c postgresql://tom@localhost/mydb?application_name=myapp
@@ -768,7 +767,9 @@ testdb=> \da[S] [ pattern ] - 列出聚合函数及其返回类型和操作的数据类型。如果指定了pattern,则只显示名称匹配该模式的聚合函数。默认只显示用户创建的对象;提供模式或S修饰符可包含系统对象。 + + 列出聚合函数,以及它们的返回类型和所作用的数据类型。如果指定了 pattern,则只显示名称与模式匹配的聚合。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 @@ -776,7 +777,10 @@ testdb=> \dA[+] [ pattern ] - 列出访问方法。如果指定了pattern,则只显示名称匹配该模式的访问方法。如果在命令名后附加+,还会列出每个访问方法关联的处理函数和描述。 + + 列出访问方法。如果指定了 pattern,则只显示名称与模式匹配的访问方法。如果在命令名后追加 +,则每个访问方法都会连同其关联的处理器函数和描述一起列出。 + @@ -784,7 +788,10 @@ testdb=> \db[+] [ pattern ] - 列出表空间。如果指定了pattern,则只显示名称匹配该模式的表空间。如果在命令名后附加+,还会列出每个表空间关联的选项、磁盘大小、权限和描述。 + + 列出表空间。如果指定了 pattern,则只显示名称与模式匹配的表空间。如果在命令名后追加 +,则每个表空间都会连同其关联选项、磁盘大小、权限和描述一起列出。 + @@ -792,7 +799,9 @@ testdb=> \dc[S+] [ pattern ] - 列出字符集编码之间的转换。如果指定了pattern,则只列出名称匹配该模式的转换。默认只显示用户创建的对象;提供模式或S修饰符可包含系统对象。如果在命令名后附加+,还会列出每个对象关联的描述。 + + 列出字符集编码之间的转换。如果指定了 pattern,则只列出名称与模式匹配的转换。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 +,则每个对象都会连同其相关描述一起列出。 + @@ -822,7 +831,10 @@ testdb=> \dD[S+] [ pattern ] - 列出域。如果指定了pattern,则只显示名称匹配该模式的域。默认只显示用户创建的对象;提供模式或S修饰符可包含系统对象。如果在命令名后附加+,还会列出每个对象关联的权限和描述。 + + 列出域。如果指定了 pattern,则只显示名称与模式匹配的域。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 +,则每个对象都会连同其相关权限和描述一起列出。 + @@ -905,28 +917,28 @@ testdb=> \dF[+] [ pattern ] - 列出文本搜索配置。如果指定了pattern,则只显示名称匹配该模式的配置。如果使用\dF+形式,则显示每个配置的完整说明,包括底层文本搜索解析器和每种解析器词元类型的词典列表。 + 列出全文检索配置。如果指定了pattern,则只显示名称匹配该模式的配置。如果使用\dF+形式,则显示每个配置的完整说明,包括底层全文检索解析器和每种解析器词元类型的词典列表。 \dFd[+] [ pattern ] - 列出文本搜索词典。如果指定了pattern,则只显示名称匹配该模式的词典。如果使用\dFd+形式,还会显示每个选中词典的附加信息,包括底层文本搜索模板和选项值。 + 列出全文检索词典。如果指定了pattern,则只显示名称匹配该模式的词典。如果使用\dFd+形式,还会显示每个选中词典的附加信息,包括底层全文检索模板和选项值。 \dFp[+] [ pattern ] - 列出文本搜索解析器。如果指定了pattern,则只显示名称匹配该模式的解析器。如果使用\dFp+形式,则显示每个解析器的完整说明,包括底层函数和可识别的词元类型列表。 + 列出全文检索解析器。如果指定了pattern,则只显示名称匹配该模式的解析器。如果使用\dFp+形式,则显示每个解析器的完整说明,包括底层函数和可识别的词元类型列表。 \dFt[+] [ pattern ] - 列出文本搜索模板。如果指定了pattern,则只显示名称匹配该模式的模板。如果使用\dFt+形式,还会显示每个模板的附加信息,包括底层函数名。 + 列出全文检索模板。如果指定了pattern,则只显示名称匹配该模式的模板。如果使用\dFt+形式,还会显示每个模板的附加信息,包括底层函数名。 @@ -949,7 +961,10 @@ testdb=> \dL[S+] [ pattern ] - 列出过程语言。如果指定了pattern,则只列出名称匹配该模式的语言。默认只显示用户创建的语言;提供S修饰符可包含系统对象。如果在命令名后附加+,还会列出每种语言的调用处理程序、验证器、访问权限,以及它是否为系统对象。 + + 列出过程语言。如果指定了 pattern,则只列出名称与模式匹配的语言。默认情况下,只显示用户创建的语言;提供 S 修饰符可包括系统对象。如果在命令名后追加 +,则每种语言都会连同其调用处理器、验证器、访问权限以及它是否为系统对象一起列出。 + @@ -958,7 +973,10 @@ testdb=> \dn[S+] [ pattern ] - 列出模式(命名空间)。如果指定了pattern,则只列出名称匹配该模式的模式。默认只显示用户创建的对象;提供模式或S修饰符可包含系统对象。如果在命令名后附加+,还会列出每个对象关联的权限和描述(如果有)。 + + 列出模式(命名空间)。如果指定了 pattern,则只列出名称与模式匹配的模式。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 +,则每个对象都会连同其相关权限和描述(如果有)一起列出。 + @@ -974,7 +992,9 @@ testdb=> \dO[S+] [ pattern ] - 列出排序规则。如果指定了pattern,则只列出名称匹配该模式的排序规则。默认只显示用户创建的对象;提供模式或S修饰符可包含系统对象。如果在命令名后附加+,还会列出每个排序规则关联的描述(如果有)。请注意,只会显示可用于当前数据库编码的排序规则,因此同一安装中的不同数据库可能会得到不同结果。 + + 列出排序规则。如果指定了 pattern,则只列出名称与模式匹配的排序规则。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 +,则每个排序规则都会连同其相关描述(如果有)一起列出。请注意,只会显示与当前数据库编码兼容的排序规则,因此在同一安装中的不同数据库里结果可能不同。 + @@ -1008,7 +1028,7 @@ testdb=> \drds [ role-pattern [ database-pattern ] ] - 列出已定义的配置设置。这些设置可以专属于角色、专属于数据库,或同时专属于两者。role-patterndatabase-pattern分别用于选择要列出的特定角色和数据库。如果省略,或指定了*,则列出所有设置,分别包括非角色专属或非数据库专属的设置。 + 列出已定义的配置设置。这些设置可以特定于角色、特定于数据库,或同时特定于两者。role-patterndatabase-pattern分别用于选择要列出的角色和数据库。省略某个模式参数或将其指定为*时,不会按该参数筛选,还会分别包含不特定于角色或不特定于数据库的设置。 命令用于定义角色专属和数据库专属的配置设置。 @@ -1024,7 +1044,9 @@ testdb=> \dRs[+] [ pattern ] - 列出复制订阅。如果指定了pattern,则只列出名称匹配该模式的订阅。如果在命令名后附加+,还会显示订阅的附加属性。 + + 列出逻辑复制订阅。如果指定了 pattern,则只列出名称与模式匹配的订阅。如果在命令名后追加 +,则会显示订阅的其他属性。 + @@ -1054,7 +1076,9 @@ testdb=> \dy[+] [ pattern ] - 列出事件触发器。如果指定了pattern,则只列出名称匹配该模式的事件触发器。如果在命令名后附加+,还会列出每个对象关联的描述。 + + 列出事件触发器。如果指定了 pattern,则只列出名称与模式匹配的事件触发器。如果在命令名后追加 +,则每个对象都会连同其相关描述一起列出。 + @@ -1125,7 +1149,9 @@ Tue Oct 26 21:40:57 CEST 1999 \encoding [ encoding ] - 设置客户端字符集编码。如果没有参数,则显示当前编码。 + + 设置客户端字符集编码。没有参数时,此命令显示当前编码。 + @@ -1171,7 +1197,7 @@ Tue Oct 26 21:40:57 CEST 1999 - 设置未对齐查询输出的字段分隔符。默认值是竖线(|)。 + 设置非对齐查询输出的字段分隔符。默认值是竖线(|)。 它等同于\pset fieldsep @@ -1187,7 +1213,7 @@ Tue Oct 26 21:40:57 CEST 1999 如果当前查询缓冲区为空,则最近发送的查询将被重新执行。除此之外,没有任何参数的\g基本上等同于一个分号。 带有参数的\g提供了一个一次性替代\o命令的选择。
- 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号展开。该行剩余的内容只会原样传递给 shell。 + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 @@ -1241,7 +1267,7 @@ CREATE INDEX hello 10
- 如果指定了前缀,则会将该字符串加到查询的列名前面,以构成要使用的变量名: + 如果指定了prefix,则会将该字符串加到查询的列名前面,以构成要使用的变量名: => SELECT 'hello' AS var1, 10 AS var2 -> \gset result_ => \echo :result_var1 :result_var2 @@ -1270,7 +1296,7 @@ hello 10 给出指定SQL命令的语法帮助。如果未指定command, 则psql将列出所有可用语法帮助的命令。如果command是星号 - (*),则显示所有SQL命令的语法帮助。 + (*),则显示所有SQL命令的语法帮助。 @@ -1291,9 +1317,7 @@ hello 10 \H\html - 打开HTML查询输出格式。如果HTML格式已经打开, - 则切换回默认的对齐文本格式。此命令用于兼容性和便利性,但请参阅\pset - 有关设置其他输出选项。 + 打开HTML查询输出格式。如果HTML格式已经打开,则切换回默认的对齐文本格式。此命令是为兼容性和便利性而保留的;设置其他输出选项的方法见\pset @@ -1303,13 +1327,10 @@ hello 10 \i\include filename - 从文件filename中读取输入,并将其执行为 - 好像它是在键盘上键入的一样。 + 从文件filename中读取输入,并像在键盘上输入一样执行它。 - 如果filename- - (连字符),那么标准输入将被读取,直到EOF指示或\q元命令。 - 这可用于将交互式输入与文件输入交错使用。请注意,仅当在最外层级别处于活动状态时,Readline行为才会被使用。 + 如果filename-(连字符),则从标准输入读取,直到遇到 EOF 指示或\q元命令。这可用于将交互式输入与文件输入交错使用。请注意,只有在最外层启用了 Readline,此处才会使用 Readline 功能。 @@ -1328,36 +1349,20 @@ hello 10 这组命令实现了可嵌套的条件块。条件块必须以\if开始,以\endif结束。中间可以包含任意数量的\elif子句,后面还可以选择跟随一个\else子句。普通查询和其他类型的反斜线命令可以(通常也会)出现在构成条件块的命令之间。 - \if\elif命令读取它们的参数,并将其作为布尔表达式进行评估。 - 如果表达式为true,则处理将继续进行;否则,直到达到匹配的\elif、 - \else\endif为止,将跳过行。一旦\if或 - \elif测试成功,同一块中后续\elif命令的参数不会被评估,而是被视为false。 - 在\else之后的行只有在没有早期匹配的\if\elif成功时才会被处理。 + \if\elif命令读取其参数,并将其作为布尔表达式求值。如果表达式的值为true,则正常继续处理;否则,跳过后续行,直到遇到匹配的\elif\else\endif。一旦\if\elif测试成功,同一块中后续\elif命令的参数就不再求值,而是被视为假。只有前面所有匹配的\if\elif测试都未成功时,才会处理\else后面的行。 - expression参数 - 是\if\elif命令的参数, - 受变量插值和反引号扩展的影响,就像任何其他反斜杠命令参数一样。 - 之后,它被评估为一个开/关选项变量的值。因此,有效值是以下任何一个不 - 含糊的不区分大小写匹配之一: - true, false, 1, - 0, on, off, - yes, no。例如, - t, TtR - 都将被视为true。 + 与其他反斜线命令的参数一样,\if\elif命令的expression参数会经过变量插值和反引号扩展。随后,按开/关选项变量值的规则对结果求值。因此,有效值是以下值的不区分大小写且无歧义的匹配:truefalse10onoffyesno。例如,tTtR都会被视为true 不能正确求值为真或假的表达式会产生警告,并被视为假。 - 被跳过的行仍会正常解析,以识别查询和反斜线命令,但查询不会发送给服务器,条件命令(\if\elif\else\endif)以外的反斜线命令会被忽略。对于条件命令,只检查嵌套是否合法。被跳过的行中的变量引用不会展开,也不会执行反引号展开。 + 被跳过的行仍会正常解析,以识别查询和反斜线命令,但查询不会发送给服务器,条件命令(\if\elif\else\endif)以外的反斜线命令会被忽略。对于条件命令,只检查嵌套是否合法。被跳过的行中的变量引用不会展开,也不会执行反引号扩展。 - 所有给定条件块的反斜杠命令必须出现在同一个源文件中。如果在主输入文件或一个 - \include的文件上达到文件结束之前,所有本地 - \if块都没有关闭, - 那么psql将会引发错误。 + 同一个条件块的所有反斜线命令必须出现在同一个源文件中。如果主输入文件或通过\include引入的文件到达 EOF 时,仍有本地\if块未关闭,psql就会报错。 下面是一个示例: --- check for the existence of two separate records in the database and store --- the results in separate psql variables +-- 检查数据库中是否存在两条不同的记录,并将 +-- 结果分别存入不同的 psql 变量 SELECT EXISTS(SELECT 1 FROM customer WHERE customer_id = 123) as is_customer, EXISTS(SELECT 1 FROM employee WHERE employee_id = 456) as is_employee @@ -1403,7 +1408,7 @@ SELECT 从数据库中读取具有OIDloid的大对象,并将其写入filename。请注意,这与服务器函数 - lo_export略有不同,后者使用数据库服务器运行的用户权限, + lo_export略有不同,后者使用运行数据库服务器的用户的权限, 并在服务器的文件系统上操作。 @@ -1442,7 +1447,7 @@ lo_import 152801 - 从数据库中删除具有OIDloid的大对象。 + 从数据库中删除OIDloid的大对象。 @@ -1460,10 +1465,10 @@ lo_import 152801 将后续查询结果保存到文件filename,或通过管道传给 shell 命令command。如果没有指定参数,查询输出将恢复为标准输出。 - 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号展开。该行剩余的内容只会原样传递给 shell。 + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 - 查询结果包括从数据库服务器获取的所有表、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 + 查询结果包括从数据库服务器获取的所有表格、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 @@ -1478,7 +1483,10 @@ lo_import 152801 \p\print - 将当前查询缓冲区打印到标准输出。如果当前查询缓冲区为空,则改为打印最近执行的查询。 + + 将当前查询缓冲区打印到标准输出。 + 如果当前查询缓冲区为空,则打印最近执行的查询。 + @@ -1496,8 +1504,11 @@ lo_import 152801 \prompt [ text ] name - 提示用户提供文本,将其赋值给变量名称。还可以指定可选的提示字符串text。(对于多个单词的提示,用单引号括起文本。) + + 提示用户提供文本,将其赋值给变量name。 + 可以指定一个可选的提示字符串text。 + (对于多个单词的提示,用单引号括起文本。) + 默认情况下,\prompt 使用终端进行输入和输出。然而,如果使用了 @@ -1531,7 +1542,7 @@ lo_import 152801 零(默认值)会导致目标宽度由环境变量COLUMNS控制,或者如果未设置 COLUMNS则由检测到的屏幕宽度控制。 另外,如果columns为零,则wrapped格式仅影响屏幕输出。 - 如果columns为非零,则文件和管道输出也会被包装到该宽度。 + 如果columns为非零,则文件和管道输出也会按该宽度折行。 @@ -1591,12 +1602,12 @@ lo_import 152801 按逗号分隔的列值输出,并应用 RFC 4180 - 中描述的引用规则。 + 中描述的加引号规则。 此输出与服务器的CSV格式的 COPY命令兼容。 - 生成包含列名的标题行,除非 + 生成包含列名的表头行,除非 tuples_only参数设置为 - on。不打印标题和页脚。 + on。不打印表格标题和页脚。 每行以系统相关的行结束字符结束, 对于类Unix系统通常是单个换行符(\n), 对于Microsoft Windows则是回车和换行序列 @@ -1607,11 +1618,11 @@ lo_import 152801 wrapped格式与aligned相似,但会将较宽的数据值折成多行,使输出适应目标列宽。目标宽度的确定方式见columns选项的说明。请注意,psql不会尝试对列标题折行;因此,如果列标题所需的总宽度超过目标宽度,wrapped格式的行为就与aligned相同。 - asciidochtml, - latexlatex-longtable,和 + asciidochtml、 + latexlatex-longtabletroff-ms格式生成的表格旨在包含在使用相应标记语言的文档中。 它们不是完整的文档!这在HTML中可能不是必需的,但在 - LaTeX中,则必须有一个完整的文档包装器。 + LaTeX中,则必须有一个完整文档的外层结构。 latex格式使用LaTeXtabular 环境。 latex-longtable格式需要LaTeX @@ -1631,25 +1642,19 @@ lo_import 152801 - ascii样式使用普通的ASCII字符。数据中的换行使用右边边缘的+符号显示。 - 当wrapped格式将数据从一行换到下一行而没有换行符时,在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 + ascii样式使用普通的ASCII字符。数据中的换行符以右边缘的+符号表示。当wrapped格式在没有换行符的位置把数据折到下一行时,会在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 - old-ascii样式使用普通的ASCII字符,使用在PostgreSQL 8.4及更早版本中使用的格式样式。 - 数据中的换行符使用:符号代替左侧列分隔符显示。 - 当数据从一行换行到下一行而没有换行符时,使用;符号代替左侧列分隔符。 + old-ascii样式使用普通的ASCII字符,采用PostgreSQL 8.4 及更早版本的格式样式。数据中的换行符以替代左侧列分隔符的:符号表示。当数据在没有换行符的位置折到下一行时,则用;符号替代左侧列分隔符。 - unicode样式使用Unicode绘图字符。数据中的换行使用右边距中的回车符号显示。 - 当数据从一行换行到下一行而没有换行符时,第一行的右边距显示省略号符号, - 接着在下一行的左边距再次显示省略号符号。 + unicode样式使用 Unicode 框线绘制字符。数据中的换行符以右边缘的回车符号表示。当数据在没有换行符的位置折到下一行时,会在第一行的右边缘显示省略号符号,并在下一行的左边缘再次显示。 - 当border设置大于零时,linestyle选项还确定了用哪些字符绘制边框线。 - 普通的ASCII字符在任何地方都有效,但在识别Unicode字符的显示器上看起来更好。 + 当border设置大于零时,linestyle选项还决定用哪些字符绘制边框线。普通的ASCII字符在任何环境中都可用,但在支持 Unicode 的显示设备上,Unicode 字符更美观。 @@ -1769,7 +1774,7 @@ lo_import 152801 \qecho text [ ... ] - 这个命令与\echo命令相同,只是输出将被写入查询输出通道,由\o设置。 + 这个命令与\echo相同,只是输出会写入由\o设置的查询输出通道。 @@ -1799,9 +1804,7 @@ lo_import 152801 \set [ name [ value [ ... ] ] ] - psql变量名称设置为,如果给出多个值,则设置为所有值的串接。如果只给出一个参数,则将变量设置为空字符串值。要取消变量设置,请使用\unset命令。 + psql变量name设置为value,如果给出多个值,则设置为所有值的串接。如果只给出一个参数,则将变量设置为空字符串值。要取消变量设置,请使用\unset命令。 \set没有任何参数时,显示当前设置的所有psql变量的名称和值。 @@ -1822,9 +1825,10 @@ lo_import 152801 \setenv name [ value ] - 将环境变量名称设置为;如果没有提供,则取消设置该环境变量。例如: + + 设置环境变量namevalue, + 或者如果未提供value,则取消设置环境变量。示例: + testdb=> \setenv PAGER less testdb=> \setenv LESS -imx4F @@ -1858,8 +1862,7 @@ testdb=> \setenv LESS -imx4F - 这个命令获取并显示指定视图的定义,以CREATE OR REPLACE VIEW命令的形式。 - 定义将打印到当前查询输出通道,由\o设置。 + 这个命令获取指定视图的定义,并以CREATE OR REPLACE VIEW命令的形式显示。定义会打印到由\o设置的当前查询输出通道。 @@ -1915,7 +1918,7 @@ testdb=> \setenv LESS -imx4F 将当前查询缓冲区写入文件filename,或通过管道传递给 shell 命令command。如果当前查询缓冲区为空,则改为写入最近执行的查询。 - 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号展开。该行剩余的内容只会原样传递给 shell。 + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 @@ -1923,8 +1926,13 @@ testdb=> \setenv LESS -imx4F \watch [ seconds ] - 重复执行当前查询缓冲区(如同\g),直到被中断或查询失败。每次执行之间等待指定的秒数(默认为 2)。每个查询结果都会显示一个标题,其中包含\pset title字符串(如果有)、查询开始时间和延迟间隔。 - 如果当前查询缓冲区为空,则改为重新执行最近发送的查询。 + + 重复执行当前查询缓冲区(如同 \g 一样),直到被中断或查询失败。两次执行之间等待指定的秒数(默认 2 秒)。每次查询结果都会带有一个头部,其中包含 \pset title + 字符串(如果有)、查询开始时的时间以及延迟间隔。 + + + 如果当前查询缓冲区为空,则重新执行最近发送的查询。 + @@ -1953,13 +1961,11 @@ testdb=> \setenv LESS -imx4F \! [ command ] - 不带参数时,转义到一个子shell;psql在子shell退出时恢复。 - 带参数时,执行shell命令command。 + 不带参数时,进入一个子 shell;子 shell 退出后,psql恢复运行。带参数时,执行 shell 命令command - 与大多数其他元命令不同,整个行的剩余部分始终被视为\!的参数, - 在参数中不执行变量插值或反引号扩展。行的其余部分被直接传递给shell。 + 与大多数其他元命令不同,该行剩余的全部内容始终被视为\!的参数,其中不会进行变量插值或反引号扩展。该行剩余内容会原样传给 shell。 @@ -1971,7 +1977,7 @@ testdb=> \setenv LESS -imx4F 显示帮助信息。可选的topic参数 (默认为commands)选择要解释的psql的哪个部分: - commands描述psql的反斜杠命令; + commands描述psql的反斜线命令; options描述可以传递给psql的命令行选项; 而variables显示关于psql配置变量的帮助。 @@ -2000,12 +2006,12 @@ select 1\; select 2\; select 3; 模式 - patterns + 模式 在 psql 和 pg_dump 中 - 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要把它写成两个相邻的双引号,这同样是符合 SQL 引用标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你不能只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 + 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要在双引号包围的文本内把它写成两个相邻的双引号,这同样是符合 SQL 加引号标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你可以只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 @@ -2049,7 +2055,7 @@ bar - 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要重置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 + 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要取消设置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 @@ -2063,7 +2069,7 @@ bar - 控制psql行为的变量通常不能被重置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse。 + 控制psql行为的变量通常不能被取消设置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse @@ -2081,7 +2087,7 @@ bar - 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被重置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交打开模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身即不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 + 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被取消设置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交关闭模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身既不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 @@ -2111,7 +2117,7 @@ bar DBNAME - 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -2120,7 +2126,7 @@ bar ECHO - 如果被设置为all,所有非空输入行会被按照读入它们的样子打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被重置或者设置为none(默认值)则不会显示任何查询。 + 如果被设置为all,所有非空输入行会在读入时打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被设置为none(默认值)则不会显示任何查询。 @@ -2138,7 +2144,7 @@ bar ENCODING - 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者重置。 + 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者取消设置。 @@ -2156,12 +2162,12 @@ bar FETCH_COUNT - 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每一组就会包括这么多个行。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 + 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每组包含的行数等于该整数值。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 - 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT个行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 + 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 @@ -2180,7 +2186,7 @@ bar HISTCONTROL - 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则匹配之前的历史行的行不会被放入。值ignoreboth组合了上述两种值。如果被重置或者被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 + 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则与上一条历史记录相同的行不会被放入。值ignoreboth组合了上述两种值。如果被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 @@ -2222,7 +2228,7 @@ bar HOST - 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -2231,7 +2237,7 @@ bar IGNOREEOF - 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须键入多个连续的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 + 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须连续键入与该数值相等数量的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 @@ -2245,8 +2251,8 @@ bar LASTOID - 最后被影响的 OID 的值,这可能会由INSERT或者\lo_import命令返回。这个变量只保证在下一个SQL命令被显示完之前有效。 - PostgreSQL 服务器从12版开始不再支持 OID 系统列,因此,在面向此类服务器时,跟随在INSERT后面的 LASTOID 将始终为0。 + 最后被影响的 OID 的值,这可能会由INSERT或者\lo_import命令返回。这个变量仅保证在下一个SQL命令的结果显示完之前有效。 + PostgreSQL 服务器从12版开始不再支持 OID 系统列,因此,在面向此类服务器时,执行INSERT后的 LASTOID 将始终为0。 @@ -2271,7 +2277,7 @@ bar - 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被重置或者设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 + 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 @@ -2289,7 +2295,7 @@ bar PORT - 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -2330,7 +2336,7 @@ bar SERVER_VERSION_NUM - 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者重设。 + 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者取消设置。 @@ -2339,7 +2345,7 @@ bar SHOW_CONTEXT - 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT域。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 + 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT字段。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 当VERBOSITY被设置为tersesqlstate时,这个设置无效(另见\errverbose,它可以用来得到刚遇到的错误的详细信息)。 @@ -2358,7 +2364,7 @@ bar SINGLESTEP - 设置这个变量为on等效于命令选项。 + 设置这个变量为on等效于命令行选项 @@ -2376,7 +2382,7 @@ bar USER - 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -2385,7 +2391,7 @@ bar VERBOSITY - 这个变量可以被设置为值defaultverboseterse或者sqlstate来控制错误报告的详细程度(另见\errverbose,在想得到之前的错误的详细版本时使用)。 + 这个变量可以被设置为值defaultverboseterse或者sqlstate来控制错误报告的详细程度(另见\errverbose,在想得到刚遇到的错误的详细信息时使用)。 @@ -2396,7 +2402,7 @@ bar VERSION_NUM - 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或重设。 + 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或取消设置。 @@ -2406,10 +2412,10 @@ bar - <acronym>SQL</acronym> 中插入变量 + <acronym>SQL</acronym> 插值 - psql变量的一个关键特性是可以把它们替换(插入)到常规SQL语句中,也可以把它们作为元命令的参数。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。插入一个值而不加引号的语法是在变量名前面加上一个冒号(:)。例如, + psql变量的一个关键特性是可以把它们替换(插值)到常规SQL语句中,也可以把它们替换到元命令的参数中。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。不加引号地插值一个值的语法是在变量名前面加上一个冒号(:)。例如, testdb=> \set foo 'my_table' testdb=> SELECT * FROM :foo; @@ -2418,7 +2424,7 @@ testdb=> SELECT * FROM :foo; - 当一个值被用作 SQL 文本或者标识符时,最安全的是把它加上引用。要引用一个变量的值作为 SQL 文本,可以把变量名称放在单引号中并且在引号前面写一个冒号。要引用作为 SQL 标识符,则可以把变量名称放在双引号中并且在引号前面写一个冒号。这种结构可以正确地处理变量值中嵌入的引号和其他特殊字符。之前的示例用这种方法写会更安全: + 当一个值要用作 SQL 字面量或标识符时,最安全的做法是为它加上引号。要将变量值作为 SQL 字面量加引号,应写一个冒号,后面跟用单引号括起来的变量名。要将变量值作为 SQL 标识符加引号,则在冒号后面用双引号括起变量名。这些写法能正确处理变量值中嵌入的引号和其他特殊字符。前面的示例可用以下更安全的写法: testdb=> \set foo 'my_table' testdb=> SELECT * FROM :"foo"; @@ -2426,11 +2432,11 @@ testdb=> SELECT * FROM :"foo"; - 在被引用的SQL文本和标识符中将不会执行变量插入。因此,一个诸如':foo'的结构不会从一个变量的值产生一个被引用的文本(即便能够也会不安全,因为无法正确地处理嵌入在值中的引号)。 + 在加引号的SQL字面量和标识符内部,不会执行变量插值。因此,':foo'这样的写法不能根据变量值生成加引号的字面量(即使能够生效,也不安全,因为它无法正确处理变量值中嵌入的引号)。 - 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个被引用的字符串插入: + 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个加引号的字符串进行插值: testdb=> \set content `cat my_file.txt` testdb=> INSERT INTO my_table VALUES (:'content'); @@ -2439,7 +2445,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 因为冒号可以合法地出现在 SQL 命令中,一次明显的插入尝试(即:name:'name'或者:"name")不会被替换,除非所提及的变量就是当前被设置的。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 + 因为冒号可以合法地出现在 SQL 命令中,一次明显的插值尝试(即:name:'name'或者:"name")不会被替换,除非所指的变量当前已设置。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 @@ -2447,7 +2453,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 文本或者标识符的冒号引用语法是一种psql扩展。 + 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 字面量或者标识符的冒号加引号语法是一种psql扩展。 @@ -2482,7 +2488,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %n - 数据库会话用户名。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的展开结果。) + 数据库会话用户名。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) @@ -2493,20 +2499,21 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %~ - %/相同,但如果该数据库是你的默认数据库,则输出~(波浪号)。 + 类似 %/,但如果该数据库是你的默认数据库,则输出 ~ + (波浪号)。 %# - 如果会话用户是数据库超级用户,则为#,否则为>。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的展开结果。) + 如果会话用户是数据库超级用户,则为#,否则为>。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) %p - 当前连接的后端的进程 ID。 + 当前所连接后端的进程 ID。 @@ -2514,7 +2521,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %R - 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 dollar-quoted 字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 + 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 美元引用字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 @@ -2541,7 +2548,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %digits - 带有所示八进制码的字符被替换。 + 替换为指定八进制代码对应的字符。 @@ -2693,9 +2700,9 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 如果查询结果无法在屏幕上显示完整,它们将通过此命令进行传输。典型的值是moreless。 + 如果查询结果无法在屏幕上显示完整,它们会通过管道传给此命令。典型的值是moreless。 可以通过将PSQL_PAGERPAGER设置为空字符串,或通过调整\pset命令的与分页相关的选项来禁用分页器。 - 这些变量按照列出的顺序进行检查;首先设置的变量将被使用。 + 这些变量按照列出的顺序进行检查;使用按该顺序找到的第一个已设置的变量。 如果它们都没有设置,默认情况下在大多数平台上使用more,但在Cygwin上使用less @@ -2756,11 +2763,11 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' 用户的个人启动文件名为.psqlrc,并且在调用用户的主目录中寻找。 - 在Windows上,个人启动文件的名称改为%APPDATA%\postgresql\psqlrc.conf。 + Windows 没有主目录这一概念,在 Windows 上,个人启动文件的名称为%APPDATA%\postgresql\psqlrc.conf。 在任何情况下,可以通过设置PSQLRC环境变量来覆盖此默认文件路径。 - 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加连字符和PostgreSQL的主版本或次版本号来使其与psql版本相关, + 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加连字符和PostgreSQL的大版本或小版本号来使其与psql版本相关, 例如~/.psqlrc-9.2~/.psqlrc-9.2.5。 最具体版本匹配的文件将优先读取,而不是非特定版本的文件。 @@ -2787,14 +2794,14 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - psql最适合与相同或较旧主要版本的服务器配合使用。 - 如果服务器的版本比psql本身更新,反斜杠命令特别容易失败。 - 然而,\d系列的反斜杠命令应该可以在版本回溯到9.2的服务器上运行, + psql最适合与相同或较旧大版本的服务器配合使用。 + 如果服务器的版本比psql本身更新,反斜线命令特别容易失败。 + 然而,\d系列的反斜线命令应该可以在最低至 7.4 版本的服务器上运行, 但不一定适用于比psql本身更新的服务器。运行SQL命令和显示查询结果的一般功能 - 也应该可以在更新主要版本的服务器上运行,但不能保证在所有情况下都能实现。 + 也应该可以在更新大版本的服务器上运行,但不能保证在所有情况下都能实现。 - 如果你想用psql连接到多个具有不同主版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个主版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 + 如果你想用psql连接到多个具有不同大版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个大版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 @@ -2808,7 +2815,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空格。现在则要求一些空格。 + 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空白。现在则要求用空白分隔。 @@ -2866,6 +2873,7 @@ peter@localhost testdb=> SELECT * FROM my_table; 3 | three 4 | four (4 rows) + 要以不同方式显示表格,可以使用\pset命令: peter@localhost testdb=> \pset border 2 Border style is 2. @@ -2951,10 +2959,10 @@ testdb=> \crosstabview first second (4 rows) 第二个示例显示一个乘法表,行按数值降序排列,列则独立地按数值升序排列。 testdb=> SELECT t1.first as "A", t2.first+100 AS "B", t1.first*(t2.first+100) as "AxB", -testdb(> row_number() over(order by t2.first) AS ord -testdb(> FROM my_table t1 CROSS JOIN my_table t2 ORDER BY 1 DESC -testdb(> \crosstabview "A" "B" "AxB" ord - A | 101 | 102 | 103 | 104 +testdb-> row_number() over(order by t2.first) AS ord +testdb-> FROM my_table t1 CROSS JOIN my_table t2 ORDER BY 1 DESC +testdb-> \crosstabview "A" "B" "AxB" ord + A | 101 | 102 | 103 | 104 ---+-----+-----+-----+----- 4 | 404 | 408 | 412 | 416 3 | 303 | 306 | 309 | 312 diff --git a/zh/12/release-12.sgml b/zh/12/release-12.sgml index dc587b82..cb365b6b 100644 --- a/zh/12/release-12.sgml +++ b/zh/12/release-12.sgml @@ -5165,7 +5165,7 @@ Branch: REL_12_STABLE [3b4580f5c] 2023-06-24 17:18:08 -0400 Branch: REL_11_STABLE [c7f33a197] 2023-06-24 17:18:08 -0400 --> - 防止非常复杂的文本搜索模式导致栈溢出崩溃 + 防止非常复杂的文本检索模式导致栈溢出崩溃 (Tom Lane) § @@ -7117,7 +7117,7 @@ Branch: REL_12_STABLE [1aed4c4fd] 2022-11-21 17:07:07 -0500 Branch: REL_11_STABLE [c0eed8891] 2022-11-21 17:07:07 -0500 --> - 确保在执行短语匹配时可以取消全文搜索查询的执行(Tom Lane) + 确保在执行短语匹配时可以取消全文检索查询的执行(Tom Lane) § @@ -17421,7 +17421,7 @@ Branch: REL_11_STABLE [98a4d6950] 2020-04-27 12:21:04 -0400 Branch: REL_10_STABLE [072a86327] 2020-04-27 12:21:04 -0400 Branch: REL9_6_STABLE [22dcb6c20] 2020-04-27 12:21:04 -0400 --> - 修复全文搜索,使其正确处理短语搜索之上的 NOT(Tom Lane) § + 修复全文检索,使其正确处理短语搜索之上的 NOT(Tom Lane) § !(foo<->bar) 等查询在通过 GiST 或 GIN 索引搜索执行时,无法找到匹配行。 @@ -17435,7 +17435,7 @@ Branch: REL_11_STABLE [5db48808c] 2020-05-07 15:59:52 -0400 Branch: REL_10_STABLE [26cf16a93] 2020-05-07 15:59:52 -0400 Branch: REL9_6_STABLE [7c9d9aa5c] 2020-05-07 15:59:52 -0400 --> - 修复短语搜索包含同时具有前缀匹配和权重限制的项时的全文搜索(Tom Lane) § + 修复短语搜索包含同时具有前缀匹配和权重限制的项时的全文检索(Tom Lane) § @@ -19783,7 +19783,7 @@ Branch: REL_11_STABLE [88d03d73c] 2019-11-03 16:10:45 -0500 Branch: REL_10_STABLE [4077e9ae1] 2019-11-03 16:10:56 -0500 Branch: REL9_6_STABLE [d43bd9dce] 2019-11-03 16:11:05 -0500 --> - 避免 ispell 文本搜索词典包含错误的词缀数据时发生崩溃(Arthur Zakirov) § + 避免 ispell 文本检索词典包含错误的词缀数据时发生崩溃(Arthur Zakirov) § § @@ -21584,7 +21584,7 @@ Author: Tom Lane 更新 Snowball 词干提取词典,支持新的语言(Arthur Zakirov) § - 这为全文搜索添加了阿拉伯语、印度尼西亚语、爱尔兰语、立陶宛语、尼泊尔语和泰米尔语的词干提取支持。 + 这为全文检索添加了阿拉伯语、印度尼西亚语、爱尔兰语、立陶宛语、尼泊尔语和泰米尔语的词干提取支持。 diff --git a/zh/12/rowtypes.sgml b/zh/12/rowtypes.sgml index 69a9df49..da3df234 100644 --- a/zh/12/rowtypes.sgml +++ b/zh/12/rowtypes.sgml @@ -58,17 +58,21 @@ SELECT price_extension(item, 10) FROM on_hand; - 每当创建一张表时,也会自动创建一个与该表同名的复合类型,用来表示表的行类型。例如,假如我们执行了: + + 每当你创建一个表时,系统也会自动创建一个与该表同名的复合类型,用来表示该表的行类型。例如,如果我们这样写: + CREATE TABLE inventory_item ( name text, supplier_id integer REFERENCES suppliers, price numeric CHECK (price > 0) ); -那么,与上文相同的inventory_item复合类型就会随之产生,而且可以像上文那样使用。不过,请注意当前实现的一个重要限制:由于复合类型本身不关联任何约束,表定义中的约束并不适用于表外的复合类型值。(要解决这一问题,可以在复合类型上创建一个域,并将所需约束定义为该域的 CHECK 约束。) + + 那么上面展示的同一个inventory_item复合类型也会顺带生成,并且同样可以像前面那样使用。不过,当前实现有一个重要限制:由于复合类型本身不关联任何约束,表定义中给出的那些约束在表之外的复合类型值上并不适用。(解决办法是:在该复合类型之上创建一个域,并把所需的约束作为该域的CHECK约束。) + - 构造组合值 + 构造复合值 复合类型 @@ -76,7 +80,7 @@ CREATE TABLE inventory_item ( - 要把组合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,组合常量的一般格式如下: + 要把复合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,复合常量的一般格式如下: '( val1 , val2 , ... )' @@ -96,16 +100,21 @@ CREATE TABLE inventory_item ( - (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。必要时可能需要显式指定类型。) + (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。可能需要显式指定类型,以指明应将该常量转换为哪种类型。) - 这种ROW表达式语法也可以用于构造复合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: + + ROW表达式语法也可以用于构造复合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: + ROW('fuzzy dice', 42, 1.99) ROW('', 42, NULL) -只要表达式中有多个字段,ROW 关键字实际上是可选的,因此这些可以简写为: + + 只要表达式中有多个字段,ROW 关键字实际上是可选的,因此这些可以简写为: + ('fuzzy dice', 42, 1.99) ('', 42, NULL) -这种ROW表达式语法的更多细节见。 + + 关于ROW表达式语法的更多细节,见 @@ -114,7 +123,7 @@ ROW('', 42, NULL) 访问复合类型 - 要访问组合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: + 要访问复合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: SELECT item.name FROM on_hand WHERE item.price > 9.99; @@ -136,7 +145,7 @@ SELECT (on_hand.item).name FROM on_hand WHERE (on_hand.item).price > 9.99; - 无论何时从组合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回组合值的函数结果中只选取一个字段,你需要这样写: + 无论何时从复合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回复合值的函数结果中只选取一个字段,你需要这样写: SELECT (my_func(...)).field FROM ... @@ -151,10 +160,10 @@ SELECT (my_func(...)).field FROM ... - 修改组合值 + 修改复合类型 - 下面是一些插入和更新组合列时正确语法的示例。先看插入或更新整个列值的情况: + 下面是一些插入和更新复合列时正确语法的示例。先看插入或更新整个列值的情况: INSERT INTO mytab (complex_col) VALUES((1.1,2.2)); @@ -166,7 +175,7 @@ UPDATE mytab SET complex_col = ROW(1.1,2.2) WHERE ...; - 我们也可以更新组合列中的单个子字段: + 我们也可以更新复合列中的单个子字段: UPDATE mytab SET complex_col.r = (complex_col).r + 1 WHERE ...; @@ -194,11 +203,11 @@ INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2); - 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的组合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: + 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的复合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: SELECT c FROM inventory_item c; - 这个查询会产生一个单独的组合值列,因此我们可能得到如下输出: + 这个查询会产生一个单独的复合值列,因此我们可能得到如下输出: c ------------------------ @@ -209,7 +218,7 @@ SELECT c FROM inventory_item c; - 普通的限定列名语法table_name.column_name可以理解为对该表当前行的组合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) + 普通的限定列名语法table_name.column_name可以理解为对该表当前行的复合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) @@ -237,16 +246,23 @@ SELECT (myfunc(x)).a, (myfunc(x)).b, (myfunc(x)).c FROM some_table; - PostgreSQL处理列展开时,实际上会把第一种形式转换成第二种形式。因此,在这个示例中,myfunc()每行都会被调用三次,无论采用哪种语法。如果它是一个开销较大的函数,你可能希望避免这种情况,可以使用如下查询: + PostgreSQL处理列展开时,实际上会把第一种形式转换成第二种形式。因此,在这个示例中,无论使用哪种语法,myfunc()每行都会被调用三次。如果它是一个开销较大的函数,你可能希望避免这种情况,可以使用如下查询: + SELECT m.* FROM some_table, LATERAL myfunc(x) AS m; -将函数放在一个 LATERAL FROM 项中,可以避免它在每行上被调用多次。m.* 仍会展开成 m.a, m.b, m.c,但现在这些变量只是引用 FROM 项的输出。(LATERAL 关键字在这里是可选的,但我们把它写出来,以明确该函数所取得的 x 来自 some_table。) + + 把该函数放在LATERAL FROM项中,可以避免它在每行上被调用多次。m.*仍会展开为m.a, m.b, m.c,但现在这些变量只是对该FROM项输出的引用。(这里的LATERAL关键字其实是可选的,不过我们把它写出来,是为了明确该函数会从some_table中取得x。) - 这里的composite_value.*语法在以下结构的顶层出现时会产生这类列展开:(SELECT输出列表)、RETURNING列表(位于INSERT/UPDATE/DELETE)、VALUES子句,或行构造器。在所有其他上下文中(包括嵌套在上述结构之内时),将.*附加到复合值上不会改变该值,因为它表示所有列,因此结果仍然是同一个复合值。例如,如果somefunc()接受一个复合值参数,这些查询就是等价的: + + 当composite_value.*出现在SELECT输出列表、INSERT/UPDATE/DELETE中的RETURNING列表、VALUES子句或行构造器的顶层时,就会产生这种列展开行为。在所有其他上下文中(包括嵌套在上述结构之内时),给复合值附加.*不会改变其值,因为它表示所有列,因此结果仍然是同一个复合值。例如,如果somefunc()接受一个复合值参数,这些查询就是等价的: + + SELECT somefunc(c.*) FROM inventory_item c; SELECT somefunc(c) FROM inventory_item c; -在这两种情况下,inventory_item的当前行都会作为单个复合值参数传递给该函数。即使.*在这种情况下不起作用,使用它仍是良好的风格,因为它明确表示这里需要的是复合值。特别是,解析器会将c(位于c.*)解释为表名或别名,而不是列名,因此不存在歧义;但如果没有.*,就不能明确判断c表示表名还是列名,而且会优先采用列名解释,只要存在一列名为c。 + + + 在这两种情况下,inventory_item的当前行都会作为单个复合值参数传递给该函数。尽管.*在这种场合并不起作用,使用它仍是一种良好风格,因为它能明确表明这里想要的是复合值。特别是,解析器会把c.*中的c视为表名或别名,而不是列名,因此不会产生歧义;而没有.*时,就不清楚c究竟表示表名还是列名,而且如果存在名为c的列,实际上会优先按列名解释。 @@ -256,7 +272,7 @@ SELECT * FROM inventory_item c ORDER BY c; SELECT * FROM inventory_item c ORDER BY c.*; SELECT * FROM inventory_item c ORDER BY ROW(c.*); - 所有这些ORDER BY子句都指定了该行的组合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: + 所有这些ORDER BY子句都指定了该行的复合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: SELECT * FROM inventory_item c ORDER BY ROW(c.name, c.supplier_id, c.price); SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); @@ -265,7 +281,7 @@ SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); - 另一种与组合值有关的特殊语法行为是,我们可以使用函数记法来提取组合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: + 另一种与复合值有关的特殊语法行为是,我们可以使用函数记法来提取复合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: SELECT c.name FROM inventory_item c WHERE c.price > 1000; @@ -284,11 +300,11 @@ SELECT c.somefunc FROM inventory_item c; 函数记法与字段记法之间的这种等价性,使得我们可以通过在复合类型上使用函数来实现计算字段 - computed field + 计算字段 - field - computed + 字段 + 计算 使用上面最后一种查询形式的应用程序,无需直接知道somefunc并不是该表中的真实列。 @@ -306,7 +322,7 @@ SELECT c.somefunc FROM inventory_item c; 复合类型的输入和输出语法 - 组合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明组合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 + 复合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明复合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 '( 42)' @@ -314,7 +330,7 @@ SELECT c.somefunc FROM inventory_item c; - 如前所示,在写组合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让组合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的组合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作组合语法的数据字符。 + 如前所示,在写复合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让复合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的复合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作复合语法的数据字符。 @@ -328,18 +344,18 @@ SELECT c.somefunc FROM inventory_item c; - 记住,你在 SQL 命令中写的内容会先被解释为字符串字面量,然后才会被解释为组合值。这会使所需的反斜杠数量翻倍(假定使用的是转义字符串语法)。例如,要在组合值中插入一个包含双引号和反斜杠的text字段,需要写成: + 记住,你在 SQL 命令中写的内容会先被解释为字符串字面量,然后才会被解释为复合值。这会使所需的反斜杠数量翻倍(假定使用的是转义字符串语法)。例如,要在复合值中插入一个包含双引号和反斜杠的text字段,需要写成: INSERT ... VALUES ('("\"\\")'); - 字符串字面量处理器会去掉一层反斜杠,因此传到组合值解析器时看起来是("\"\\")。随后,送入text数据类型输入例程的字符串就变成了"\。(如果我们使用的数据类型的输入例程也会把反斜杠当作特殊字符处理,例如bytea,那么为了在存储的组合字段中得到一个反斜杠,命令里可能需要多达八个反斜杠。)美元引用(见)可用于避免反斜杠加倍的需要。 + 字符串字面量处理器会去掉一层反斜杠,因此传到复合值解析器时看起来是("\"\\")。随后,送入text数据类型输入例程的字符串就变成了"\。(如果我们使用的数据类型的输入例程也会把反斜杠当作特殊字符处理,例如bytea,那么为了在存储的复合字段中得到一个反斜杠,命令里可能需要多达八个反斜杠。)美元引用(见)可用于避免反斜杠加倍的需要。 - 在 SQL 命令中编写组合值时,ROW构造器语法通常比组合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是组合成员时完全相同。 + 在 SQL 命令中编写复合值时,ROW构造器语法通常比复合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是复合成员时完全相同。 diff --git a/zh/12/textsearch.sgml b/zh/12/textsearch.sgml index 9de29fc4..0f92130d 100644 --- a/zh/12/textsearch.sgml +++ b/zh/12/textsearch.sgml @@ -1,21 +1,21 @@ - 全文搜索 + 全文检索 - 全文搜索 + 全文检索 - 文本搜索 + 文本检索 介绍 - 全文检索(或简称文本搜索)提供了识别满足 + 全文检索(或简称文本检索)提供了识别满足 查询条件的自然语言文档的能力, 并且可按它们与查询的相关度进行排序。最常见的搜索类型,是找出所有包含给定 查询词的文档,并按它们与查询的相似性 @@ -25,7 +25,7 @@ - 文本搜索操作符在数据库中已经存在很多年了。 + 文本检索操作符在数据库中已经存在很多年了。 PostgreSQL为文本数据类型提供了 ~~*LIKEILIKE 操作符,但它们缺少现代信息系统所要求的许多关键特性: @@ -138,7 +138,7 @@ ()。围绕这两种数据类型还有许多函数和 操作符(),其中最重要的是匹配操作符 @@,我们将在中介绍。 - 全文搜索还可以借助索引加速()。 + 全文检索还可以借助索引加速()。 @@ -147,11 +147,11 @@ 文档 - 全文搜索 + 文本检索 - 文档是全文搜索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本搜索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 + 文档是全文检索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本检索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 @@ -179,7 +179,7 @@ WHERE m.mid = d.did AND m.mid = 12; - 为了进行文本搜索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 + 为了进行文本检索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 @@ -187,7 +187,7 @@ WHERE m.mid = d.did AND m.mid = 12; 基本文本匹配 - 在PostgreSQL中,全文搜索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: + 在PostgreSQL中,全文检索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: SELECT 'a fat cat sat on a mat and ate a fat rat'::tsvector @@ 'cat & rat'::tsquery; @@ -203,7 +203,7 @@ SELECT 'fat & cow'::tsquery @@ 'a fat cat sat on a mat and ate a fat rat'::t - 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索术语,这些术语必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个术语组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本搜索匹配更像是这样: + 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索词,这些搜索词必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个搜索词组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本检索匹配更像是这样: SELECT to_tsvector('fat cats ate fat rats') @@ to_tsquery('fat & rat'); @@ -221,7 +221,7 @@ SELECT 'fat cats ate fat rats'::tsvector @@ to_tsquery('fat & rat'); f - 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,默认假定已经正规化,因此 rats 不会匹配 rat。 + 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,被假定为已经正规化,因此 rats 不会匹配 rat @@ -290,49 +290,49 @@ SELECT phraseto_tsquery('the cats ate the rats'); 配置 - 前述的都是简单的文本搜索示例。正如前面所提到的,全文搜索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如基于空白之外的解析。这个功能由文本搜索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 + 前述的都是简单的文本检索示例。正如前面所提到的,全文检索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如不局限于按空白划分的解析。这个功能由文本检索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 - 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本搜索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config。 + 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本检索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config - 依赖一个配置的每一个文本搜索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当这个参数被忽略时,default_text_search_config才被使用。 + 依赖一个配置的每一个文本检索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当省略这个参数时,default_text_search_config才被使用。 - 为了让建立自定义文本搜索配置更容易,一个配置可以从更简单的数据库对象来建立。PostgreSQL的文本搜索功能提供了四类配置相关的数据库对象: + 为了便于构建自定义文本检索配置,配置由更简单的数据库对象组合而成。PostgreSQL 的文本检索功能提供了四类与配置相关的数据库对象: - 文本搜索解析器将文档拆分成词元并分类每个词元(例如,作为词或者数字)。 + 文本检索解析器将文档拆分成词元并对每个词元分类(例如,作为词或者数字)。 - 文本搜索词典将词元转变成正规化的形式并拒绝停用词。 + 文本检索词典将词元转变成正规化的形式并拒绝停用词。 - 文本搜索模板提供位于词典底层的函数(一个词典简单地指定一个模板和一组用于模板的参数)。 + 文本检索模板提供位于词典底层的函数(词典只需指定一个模板及其一组参数)。 - 文本搜索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 + 文本检索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 - 文本搜索解析器和模板是从低层 C 函数构建而来,因此它要求 C 编程能力来开发新的解析器和模板,并且还需要超级用户权限来把它们安装到一个数据库中(在PostgreSQL发布的contrib/区域中有一些附加的解析器和模板的示例)。由于词典和配置只是对底层解析器和模板的参数化和连接,不需要特殊的权限来创建一个新词典或配置。创建定制词典和配置的示例将在本章稍后的部分给出。 + 文本检索解析器和模板由底层 C 函数构成,因此开发新的解析器和模板需要 C 编程能力,将它们安装到数据库中则需要超级用户权限。(PostgreSQL 发行版的 contrib/ 目录中有附加解析器和模板的示例。)词典和配置只是为底层解析器和模板设置参数并将它们连接起来,因此创建新词典或配置不需要特殊权限。本章后面会给出创建自定义词典和配置的示例。 @@ -343,14 +343,14 @@ SELECT phraseto_tsquery('the cats ate the rats'); 表和索引 - 在前一节中的示例演示了使用简单常数字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 + 在前一节中的示例演示了使用简单常量字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 搜索表 - 即使没有索引,也可以执行全文搜索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend: + 即使没有索引,也可以执行全文检索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend SELECT title @@ -374,7 +374,7 @@ WHERE to_tsvector(body) @@ to_tsquery('friend'); - 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 中同时包含 createtable: + 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 合在一起包含 createtable SELECT title @@ -388,7 +388,7 @@ LIMIT 10; - 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本搜索在实际使用中通常都需要建立索引。 + 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本检索在实际使用中通常都需要建立索引。 @@ -396,9 +396,15 @@ LIMIT 10; 创建索引 - 我们可以创建一个GIN索引()来加速文本搜索: + + 我们可以创建一个GIN索引()来加速文本检索: + + CREATE INDEX pgweb_idx ON pgweb USING GIN (to_tsvector('english', body)); -注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本搜索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含tsvector,它们使用不同的文本搜索配置创建,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 + + + 注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本检索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含使用不同文本检索配置创建的tsvector,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 + 由于上面的索引使用了 to_tsvector 的双参数版本,因此只有同样使用相同配置名的双参数版 to_tsvector 查询,才能使用该索引。也就是说,WHERE to_tsvector('english', body) @@ 'a & b' 可以使用该索引,而 WHERE to_tsvector(body) @@ 'a & b' 则不能。这样可以保证索引只会和创建索引项时所用的同一配置配合使用。 @@ -414,15 +420,24 @@ CREATE INDEX pgweb_idx ON pgweb USING GIN (to_tsvector('english', title || ' ' | - 另一种方法是创建一个单独的tsvector列来保存to_tsvector的输出。若要让该列与其源数据自动保持同步,可以使用存储生成列。下面的示例把titlebody串接起来,并用coalesce保证一个字段仍然可以被建立索引,即使另一个字段为NULL: + + 另一种方法是创建一个单独的tsvector列来保存to_tsvector的输出。若要让该列与其源数据自动保持同步,可以使用存储生成列。下面的示例把titlebody串接起来,并用coalesce保证其中一个字段为NULL时,另一个字段仍然可以被建立索引: ALTER TABLE pgweb ADD COLUMN textsearchable_index_col tsvector GENERATED ALWAYS AS (to_tsvector('english', coalesce(title, '') || ' ' || coalesce(body, ''))) STORED; -然后我们创建一个GIN索引来加速搜索: + + + 然后我们创建一个GIN索引来加速搜索: + + CREATE INDEX textsearch_idx ON pgweb USING GIN (textsearchable_index_col); -现在可以执行快速全文检索了: + + + 现在我们准备好执行一个快速的全文检索了: + + SELECT title FROM pgweb WHERE textsearchable_index_col @@ to_tsquery('create & table') @@ -432,7 +447,7 @@ LIMIT 10; - 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本搜索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 + 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本检索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 @@ -440,10 +455,10 @@ LIMIT 10; - 控制文本搜索 + 控制文本检索 - 要实现全文搜索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 + 要实现全文检索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 @@ -462,7 +477,7 @@ to_tsvector( config - to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本搜索配置进行处理。下面是一个简单示例: + to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本检索配置进行处理。下面是一个简单示例: SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); @@ -477,7 +492,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每类词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本搜索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english。 + to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每个词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本检索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english @@ -485,7 +500,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为空,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: + 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为 NULL,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: UPDATE tt SET ti = @@ -516,22 +531,35 @@ to_tsquery( config - to_tsquery创建一个tsquery值,其来源为querytext,其中必须是由以下 tsquery 操作符分隔的单个词元:&(AND)、|(OR)、!(NOT)以及 <->(FOLLOWED BY),也可以使用括号分组。换句话说,to_tsquery 的输入必须已经遵循 tsquery 输入的一般规则,如 所述。区别在于,基本的 tsquery 输入会直接使用词元,而 to_tsquery 会使用指定或默认的配置将每个词元正规化为词位,并丢弃根据该配置判定为停用词的词元。例如: + to_tsquery 根据 querytext 创建一个 tsquery 值。输入必须由单个词元组成,这些词元之间使用 tsquery 操作符 &(AND)、|(OR)、!(NOT)和 <->(FOLLOWED BY)分隔,并可使用圆括号分组。换句话说,传给 to_tsquery 的输入,必须已经遵循 中描述的 tsquery 一般输入规则。不同之处在于,基础 tsquery 输入是按字面接受词元,而 to_tsquery 会使用指定或默认配置,把每个词元正规化为词位,并丢弃那些按该配置被判定为停用词的词元。例如: + + SELECT to_tsquery('english', 'The & Fat & Rats'); to_tsquery --------------- 'fat' & 'rat' -与基本的 tsquery 输入一样,可以给每个词位附加权重,以限制它只匹配 tsvector 中具有这些权重的词位。例如: + + + 与基础tsquery输入一样,可以为每个词位附加权重,以限制它只匹配具有这些权重的tsvector词位。例如: + + SELECT to_tsquery('english', 'Fat | Rats:AB'); to_tsquery ------------------ 'fat' | 'rat':AB -此外,可以把 * 附加到词位上来指定前缀匹配: + + + 此外,还可以在词位后附加*来指定前缀匹配: + + SELECT to_tsquery('supern:*A & star:A*B'); to_tsquery -------------------------- 'supern':*A & 'star':*AB -这样的词位将匹配 tsvector 中以给定字符串开头的任何单词。 + + + 这样的词位将匹配tsvector中任何以给定字符串开头的单词。 + to_tsquery也可以接受单引号括起来的短语。当配置中包含可能在这类短语上触发的分类词典时,这一点尤其有用。在下面的例子中,一个分类词典包含规则 supernovae @@ -583,12 +611,19 @@ phraseto_tsquery( config phraseto_tsquery的行为很像plainto_tsquery,不过它会在保留下来的词之间插入<->(FOLLOWED BY)操作符,而不是&(AND)操作符。此外,停用词也不是简单地丢弃,而是通过插入<N>操作符(而不是<->操作符)来体现。在搜索精确词位序列时,这个函数很有用,因为 FOLLOWED BY 操作符不仅检查所有词位是否存在,还检查词位的顺序。 - 示例: + + 示例: + + SELECT phraseto_tsquery('english', 'The Fat Rats'); phraseto_tsquery ------------------ 'fat' <-> 'rat' -plainto_tsquery一样,phraseto_tsquery函数也不会识别其输入中的tsquery操作符、权重标签或前缀匹配标签: + + + 与plainto_tsquery一样,phraseto_tsquery函数也不会识别输入中的tsquery操作符、权重标签或前缀匹配标签: + + SELECT phraseto_tsquery('english', 'The Fat & Rats:C'); phraseto_tsquery ----------------------------- @@ -604,12 +639,12 @@ websearch_to_tsquery( configwebsearch_to_tsquery创建一个tsquery值,其来源为querytext,采用一种替代语法,其中简单的无格式文本就是一个有效查询。不同于plainto_tsqueryphraseto_tsquery,它还识别某些操作符。此外,这个函数不应引发语法错误,因此可以直接使用用户提供的原始输入进行搜索。支持以下语法: - 无引号文本:不在引号中的文本会被转换为由&操作符分隔的词,就像经过plainto_tsquery处理一样。 + 未加引号的文本:不在引号中的文本会被转换为由&操作符分隔的词,就像经过plainto_tsquery处理一样。 - "引号文本":引号中的文本会被转换为由<->操作符分隔的词,就像经过phraseto_tsquery处理一样。 + "加引号的文本":引号中的文本会被转换为由<->操作符分隔的词,就像经过phraseto_tsquery处理一样。 @@ -660,7 +695,7 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); 搜索结果排名 - 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及它们出现于文档中哪个部分。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 + 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及这些词所处文档部分的重要程度。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 目前可用的两种排名函数是: @@ -707,11 +742,21 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 对这两个函数来说,可选的weights参数允许根据词实例的标注情况赋予它们不同权重。权重数组按如下顺序指定各类词的权重: -{D-weight, C-weight, B-weight, A-weight} -如果没有提供weights,则使用如下默认值: + + 对这两个函数来说,可选的 weights 参数允许根据词实例的标注情况赋予它们不同权重。权重数组按如下顺序指定各类词的权重: + + +{D-权重, C-权重, B-权重, A-权重} + + + 如果没有提供 weights,则使用如下默认值: + + {0.1, 0.2, 0.4, 1.0} -通常,权重用于标注文档中特殊部分的词,例如标题或开头的摘要,从而使它们相对于正文中的词具有更高或更低的重要性。 + + + 通常,权重用于标记来自文档特定区域的词,例如标题或开头摘要中的词,从而使它们相较于正文中的词被赋予更高或更低的重要性。 + 由于较长的文档更有机会包含查询词,因此把文档大小纳入考量是合理的。例如,一个一百词的文档里某个搜索词出现五次,通常会比一个一千词的文档里同一搜索词也只出现五次更相关。两种排名函数都接受一个整数 normalization 选项,用于指定文档长度是否影响排名,以及具体如何影响。该整数选项控制多种行为,因此它是一个位掩码:你可以使用 | 指定一种或多种行为(例如 2|4)。 @@ -739,12 +784,12 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 8 用文档中唯一词的数量除排名 + 8 用文档中不同词的数量除排名 - 16 用 1 + 文档中唯一词数量的对数除排名 + 16 用 1 + 文档中不同词数量的对数除排名 @@ -758,7 +803,7 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。正规化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 + 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。归一化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 @@ -830,9 +875,7 @@ ts_headline( config ts_headline 接收文档和查询,并返回文档中一段 - 高亮查询词条的摘录。具体而言,该函数会先用查询选择相关文本片段,然后 - 高亮查询中出现的所有词,即使这些词的位置并不满足查询本身的位置限制。 - 用于解析文档的配置可通过 config 指定; + 高亮查询词的摘录。用于解析文档的配置可通过 config 指定; 若省略 config,则使用 default_text_search_config 配置。 @@ -919,7 +962,7 @@ occurrences to display in the result.', 附加特性 - 本节介绍一些在文本搜索中很有用的附加函数和操作符。 + 本节介绍一些在文本检索中很有用的附加函数和操作符。 @@ -1032,7 +1075,7 @@ occurrences to display in the result.', - 返回用 AND 结合的两个给定查询。 + 返回两个给定查询的 AND 组合。 @@ -1046,7 +1089,7 @@ occurrences to display in the result.', - 返回用 OR 结合的两个给定查询。 + 返回两个给定查询的 OR 组合。 @@ -1099,7 +1142,7 @@ SELECT to_tsquery('fat') <-> to_tsquery('cat | rat'); - 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: + 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在其后距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: SELECT tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10); @@ -1185,8 +1228,10 @@ SELECT querytree(to_tsquery('!defined')); - 这种形式的ts_rewrite 只应用一条重写规则:target 会被替换成 substitute,替换范围是整个 query。例如: + + 这种形式的 ts_rewrite 只应用一条重写规则:无论 targetquery 中的何处出现,都用 substitute 替换它。例如: + + SELECT ts_rewrite('a & b'::tsquery, 'a'::tsquery, 'c'::tsquery); ts_rewrite ------------ @@ -1203,7 +1248,10 @@ SELECT ts_rewrite('a & b'::tsquery, 'a'::tsquery, 'c'::tsquery); - 这种形式的ts_rewrite接受一个起始query和一个 SQLselect命令,该命令以文本字符串给出。该select必须产生两列tsquery类型的值。对于select结果中的每一行,第一列值(目标)的各次出现都会被第二列值(替换)取代,替换范围为当前query值。例如: + + 这种形式的 ts_rewrite 接受一个起始 query 和一个以文本字符串给出的 SQL select 命令。该 select 必须产生两列 tsquery 类型的值。对于 select 结果中的每一行,第一列值(目标)在当前 query 值中的所有出现都会被第二列值(替换)取代。例如: + + CREATE TABLE aliases (t tsquery PRIMARY KEY, s tsquery); INSERT INTO aliases VALUES('a', 'c'); @@ -1288,7 +1336,10 @@ tsvector_update_trigger(tsvector_column_nametsvector_column_name, config_column_name, text_column_name , ... ) - 这些触发器函数会自动计算一个tsvector列,其值来自一个或多个文本列,并受以下命令中所指定参数的控制:CREATE TRIGGER。下面是一个用法示例: + + 这些触发器函数会在 CREATE TRIGGER 命令中给定参数的控制下,从一个或多个文本列自动计算出一个 tsvector 列。下面是它们的一个使用示例: + + CREATE TABLE messages ( title text, body text, @@ -1310,13 +1361,19 @@ SELECT title, body FROM messages WHERE tsv @@ to_tsquery('title & body'); title | body ------------+----------------------- title here | the body text is here -创建这个触发器后,titlebody中的任何更改都会自动反映到tsv中,应用无需为此操心。 + + + 创建该触发器之后,对titlebody的任何修改都会自动反映到tsv中,而应用程序无需关心这一点。 + - 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本搜索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 + 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本检索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 - 这些内置触发器有一个限制,即它们会一视同仁地处理所有输入列。要对不同列采用不同处理方式 — 例如,给标题赋予与正文不同的权重 — 就需要编写自定义触发器。下面是一个使用PL/pgSQL作为触发器语言的示例: + + 这些内置触发器的一个限制是,它们会以相同方式处理所有输入列。若要对列做不同处理 — 例如让标题和正文具有不同权重 — 就需要编写自定义触发器。下面是一个使用 PL/pgSQL 作为触发器语言的示例: + + CREATE FUNCTION messages_trigger() RETURNS trigger AS $$ begin new.tsv := @@ -1377,7 +1434,7 @@ ts_stat(sqlquery text, - 如果提供了 weights,则只统计具有这些权重之一的出现。 + 如果提供了 weights,则只统计具有这些权重之一的词的出现次数。 @@ -1406,7 +1463,7 @@ LIMIT 10; 解析器 - 文本搜索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 + 文本检索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 @@ -1426,12 +1483,12 @@ LIMIT 10; asciiword - 单词,所有 ASCII 字母 + 单词,全部由 ASCII 字母组成 elephant word - 单词,所有字母 + 单词,全部由字母组成 mañana @@ -1441,12 +1498,12 @@ LIMIT 10; asciihword - 带连字符的单词,所有 ASCII + 带连字符的单词,全部为 ASCII 字符 up-to-date hword - 带连字符的单词,所有字母 + 带连字符的单词,由字母组成 lógico-matemática @@ -1456,12 +1513,12 @@ LIMIT 10; hword_asciipart - 带连字符的单词部分,所有 ASCII + 带连字符的单词部分,全部为 ASCII 字符 postgresql-beta1 上下文中的 postgresql hword_part - 带连字符的单词部分,所有字母 + 带连字符的单词部分,全部由字母组成 lógico-matemática 上下文中的 lógicomatemática @@ -1536,8 +1593,8 @@ LIMIT 10; blank - 空格符号 - (其他不识别的任意空白或标点符号) + 空白符号 + (未被识别为其他类型的空白或标点符号) @@ -1545,7 +1602,7 @@ LIMIT 10; - 解析器的一个字母的概念由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时可以用来区别它们。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 + 解析器对字母的界定由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时区分它们会很有用。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 email 不支持 RFC 5322 定义的所有有效电子邮件字符。具体来说,电子邮件用户名中支持的非字母数字字符只有句点、短横线和下划线。 @@ -1585,7 +1642,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h 词典 - 词典用于消除不应参与搜索的词(stop words),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 + 词典用于消除不应参与搜索的词(停用词),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 一些正规化的示例: @@ -1597,7 +1654,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - URL地址可以被正规化,以便让等价的 URL 匹配: + URL 地址可以规范化,以便让等价的 URL 匹配: @@ -1642,32 +1699,32 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤字典) + 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤词典 - 如果字典知道该词元但它是一个停用词,则返回一个空数组 + 如果词典知道该词元但它是一个停用词,则返回一个空数组 - 如果字典不识别该输入词元,则返回NULL + 如果词典不识别该输入词元,则返回NULL - PostgreSQL为许多语言提供了预定义的字典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发布的contrib/区域。 + PostgreSQL为许多语言提供了预定义的词典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发行版的contrib/目录。 - 文本搜索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 + 文本检索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 - 配置词典列表的一般规则是,把最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语分类词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: + 配置词典列表的一般规则是,把适用范围最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语同义词词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: ALTER TEXT SEARCH CONFIGURATION astro_en @@ -1676,14 +1733,14 @@ ALTER TEXT SEARCH CONFIGURATION astro_en - 过滤词典可以放在列表中的任何位置,只是不能放在最后,因为放在最后就没有意义了。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 + 过滤词典可以放在列表中的任何位置,但放在末尾没有用处。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 停用词 - 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文搜索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: + 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文检索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: SELECT to_tsvector('english', 'in the list of stop words'); @@ -1815,7 +1872,7 @@ SELECT * FROM ts_debug('english', 'Paris'); - synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基本名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 + synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 @@ -1877,28 +1934,28 @@ mydb=# SELECT 'indexes are very useful'::tsvector @@ to_tsquery('tst', 'indices' - 基本上一个分类词典会用一个首选词替换所有非首选词,并且也可选择地保留原始术语用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典要求一个下列格式的配置文件: + 分类词典基本上会用一个首选词替换所有非首选词,并且也可以选择保留原始词用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典需要一个采用以下格式的配置文件: -# this is a comment -sample word(s) : indexed word(s) -more sample word(s) : more indexed word(s) +# 这是一条注释 +示例词(一个或多个) : 索引词(一个或多个) +更多示例词(一个或多个) : 更多索引词(一个或多个) ... - 其中冒号(:)符号扮演了一个短语及其替换之间的定界符。 + 其中冒号(:)符号用作短语及其替换词之间的分隔符。 - 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过对子词典的应用,但所有样例词都必须能被子词典识别。 + 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过将子词典应用于该词,但所有样例词都必须能被子词典识别。 - 如果有多个短语匹配输入,则分类词典选择最长的那一个,并且使用最后的定义打破连结。 + 如果有多个短语匹配输入,分类词典会选择最长的匹配;长度相同时使用最后的定义。 - 由子词典识别的特定停用词不能够被指定;改用?标记任何可以出现停用词的地方。例如,假定根据子词典athe是停用词: + 由子词典识别的特定停用词不能够被指定;改用?标记可出现任意停用词的位置。例如,假定根据子词典athe是停用词: ? one ? two : swsw @@ -1940,7 +1997,7 @@ CREATE TEXT SEARCH DICTIONARY thesaurus_simple ( - mythesaurus是分类词典配置文件的基础名称(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 + mythesaurus是分类词典配置文件的基名(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 @@ -1965,7 +2022,7 @@ ALTER TEXT SEARCH CONFIGURATION russian 分类词典示例 - 考虑简单的天文词库 thesaurus_astro,其中包含一些天文单词组合: + 考虑一个简单的天文分类词典 thesaurus_astro,其中包含一些天文单词组合: supernovae stars : sn @@ -2033,7 +2090,7 @@ SELECT plainto_tsquery('supernova star'); <application>Ispell</application> 词典 - Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以把搜索词 bank 的词尾变化和词形变化对应起来,例如 bankingbankedbanksbanks'bank's。 + Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以匹配搜索词 bank 的所有变格和变位形式,例如 bankingbankedbanksbanks'bank's @@ -2045,12 +2102,12 @@ SELECT plainto_tsquery('supernova star'); - 要创建一个Ispell词典,执行这三步: + 要创建一个Ispell词典,请执行以下步骤: - 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。有必要抽取.aff.dic文件,把扩展改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): + 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。需要提取.aff.dic文件,将扩展名改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): iconv -f ISO_8859-1 -t UTF-8 -o nn_no.affix nn_NO.aff iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic @@ -2059,7 +2116,7 @@ iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic - 拷贝文件到$SHAREDIR/tsearch_data目录 + 复制文件到$SHAREDIR/tsearch_data目录 @@ -2077,11 +2134,11 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( - 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基础名称。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 + 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基名。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 - Ispell 词典通常识别一个有限集合的词,这样它们后面应该跟着另一个更广义的词典;例如,一个 Snowball 词典,它可以识别所有东西。 + Ispell 词典通常只能识别有限的词,因此其后应跟着另一个覆盖范围更广的词典;例如,一个 Snowball 词典,它可以识别所有输入。 @@ -2089,13 +2146,13 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( prefixes flag *A: - . > RE # As in enter > reenter + . > RE # 例如 enter > reenter suffixes flag T: - E > ST # As in late > latest - [^AEIOU]Y > -Y,IEST # As in dirty > dirtiest - [AEIOU]Y > EST # As in gray > grayest - [^EY] > EST # As in small > smallest + E > ST # 例如 late > latest + [^AEIOU]Y > -Y,IEST # 例如 dirty > dirtiest + [AEIOU]Y > EST # 例如 gray > grayest + [^EY] > EST # 例如 small > smallest @@ -2111,14 +2168,14 @@ lark/MRS .dict文件的格式是: -basic_form/affix_class_name +基本词形/词缀类名 .affix文件中,每一个词缀标志以下面的格式描述: -condition > [-stripping_letters,] adding_affix +条件 > [-删除的字母,] 添加的词缀 @@ -2127,7 +2184,7 @@ condition > [-stripping_letters,] adding_affix - Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,它标记可以参与到复合格式中的词典词: + Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,用于标记词典中可以参与构成复合词的词: compoundwords controlled z @@ -2157,7 +2214,7 @@ SFX T 0 est [^ey] - 一个词缀类的第一行是头部。头部后面列出了词缀规则的域: + 一个词缀类的第一行是首部。首部后面列出了词缀规则的字段: @@ -2209,7 +2266,7 @@ largehearted <application>Snowball</application> 词典 - Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每一个算法懂得按照其语言中的拼写,如何缩减词的常见变体形式为一个基础或词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择地指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。例如,有一个内置的定义等效于 + Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每种算法都知道如何把其语言中词的常见变体约简为基本拼写形式,也就是词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。例如,有一个内置的定义等效于 CREATE TEXT SEARCH DICTIONARY english_stem ( @@ -2223,7 +2280,7 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( - 一个Snowball词典识别所有的东西,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 + 一个Snowball词典识别所有输入,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 @@ -2234,11 +2291,11 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( 配置示例 - 一个文本搜索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本搜索配置来执行其处理。配置参数指定了默认配置的名称,如果忽略了显式的配置参数,文本搜索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 + 一个文本检索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本检索配置来执行其处理。配置参数指定了默认配置的名称,如果省略了显式的配置参数,文本检索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 - 有一些预定义的文本搜索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本搜索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本搜索对象()的信息。 + 有一些预定义的文本检索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本检索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本检索对象()的信息。 @@ -2330,17 +2387,17 @@ SHOW default_text_search_config; - 测试和调试文本搜索 + 测试和调试文本检索 - 一个自定义文本搜索配置的行为很容易变得混乱。本节中描述的函数对于测试文本搜索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 + 一个自定义文本检索配置的行为很容易让人困惑。本节中描述的函数对于测试文本检索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 配置测试 - 函数ts_debug允许简单地测试一个文本搜索配置。 + 函数ts_debug可方便地测试一个文本检索配置。 @@ -2359,7 +2416,7 @@ ts_debug( config re - ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果该参数被忽略则使用default_text_search_config指定的配置。 + ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果省略该参数则使用default_text_search_config指定的配置。 @@ -2434,7 +2491,7 @@ SELECT * FROM ts_debug('english', 'a fat cat sat on a mat - it ate a fat rats') - 为了一个更广泛的示范,我们先为英语语言创建一个public.english配置和 Ispell 词典: + 为了做更完整的演示,我们先为英语创建一个public.english配置和 Ispell 词典: @@ -2463,7 +2520,7 @@ SELECT * FROM ts_debug('public.english', 'The Brightest supernovaes'); - 在这个示例中,词Brightest被解析器识别为一个ASCII word(别名asciiword)。对于这种词元类型,词典列表是english_ispellenglish_stem。该词被english_ispell识别,并被这个词典归约为名词bright。词supernovaesenglish_ispell词典来说是未知的,因此它会被传递给下一个词典;幸运的是,它随后被识别了。(实际上,english_stem是一个 Snowball 词典,它能够识别所有输入;这也是为什么它被放在词典列表末尾。) + 在这个示例中,词Brightest被解析器识别为一个ASCII 词(别名asciiword)。对于这种词元类型,词典列表是english_ispellenglish_stem。该词被english_ispell识别,并被这个词典归约为词位bright。词supernovaesenglish_ispell词典来说是未知的,因此它会被传递给下一个词典;幸运的是,它随后被识别了。(实际上,english_stem是一个 Snowball 词典,它能够识别所有输入;这也是为什么它被放在词典列表末尾。) @@ -2492,7 +2549,7 @@ FROM ts_debug('public.english', 'The Brightest supernovaes'); 解析器测试 - 下列函数允许直接测试一个文本搜索解析器。 + 下列函数允许直接测试一个文本检索解析器。 @@ -2534,7 +2591,7 @@ ts_token_type(parser_oid oid< - ts_token_type返回一个表,描述指定解析器能够识别的每一种词元。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: + ts_token_type返回一个表,描述指定解析器能够识别的每一种词元类型。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: SELECT * FROM ts_token_type('default'); @@ -2572,7 +2629,7 @@ SELECT * FROM ts_token_type('default'); 词典测试 - ts_lexize函数帮助词典测试。 + ts_lexize函数便于测试词典。 @@ -2630,17 +2687,17 @@ SELECT plainto_tsquery('supernovae stars'); - 文本搜索的首选索引类型 + 文本检索的首选索引类型 - 文本搜索 + 文本检索 索引 - 有两种索引可以用来加速全文搜索:GIN和 + 有两种索引可以用来加速全文检索:GINGiST。 - 请注意,索引对于全文搜索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 + 请注意,索引对于全文检索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 要创建这样的索引,可以采用下面的任一种方式: @@ -2651,7 +2708,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GIN - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIN (column); @@ -2671,7 +2728,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GiST - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIST (column); @@ -2689,7 +2746,7 @@ SELECT plainto_tsquery('supernovae stars'); - GIN 索引是文本搜索的首选索引类型。作为倒排索引,每个词(词位)在 + GIN 索引是文本检索的首选索引类型。作为倒排索引,每个词(词位)在 其中都有一个索引项,其中有压缩过的匹配位置的列表。多词搜索可以找到 第一个匹配,然后使用该索引移除缺少额外词的行。GIN 索引只存储 tsvector值的词(词位),并且不存储它们的权重标签。因此, @@ -2697,19 +2754,19 @@ SELECT plainto_tsquery('supernovae stars'); - 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。该签名通过哈希每一个词到一个 n 位串中的一个单一位来产生,通过将所有这些位 OR 在一起产生一个 n 位的文档签名。当两个词哈希到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。 + 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。该签名通过将每个词 hash 到一个 n 位串中的一位,再将所有这些位进行 OR 运算来生成,结果是一个 n 位的文档签名。当两个词 hash 到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。 - GiST 可以构建为覆盖索引,例如使用 INCLUDE 子句。被包含的列可以具有没有任何 GiST 操作符类的数据类型。被包含的属性会以未压缩形式存储。 + GiST 可以构建为覆盖索引,即使用 INCLUDE 子句。被包含的列可以具有没有任何 GiST 操作符类的数据类型。被包含的属性会以未压缩形式存储。 - 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的可用性。假匹配的可能性取决于几个因素,特别是唯一词的数量,因此推荐使用词典来缩减这个数量。 + 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的实用性。假匹配的可能性取决于几个因素,特别是不同词的数量,因此推荐使用词典来缩减这个数量。 - 注意GIN索引的构件时间常常可以通过增加来改进,而GiST索引的构建时间则与该参数无关。 + 注意GIN索引的构建时间常常可以通过增加来改进,而GiST索引的构建时间则对该参数不敏感。 @@ -2723,7 +2780,7 @@ SELECT plainto_tsquery('supernovae stars'); <application>psql</application> 支持 - 关于文本搜索配置对象的信息可以在psql中使用一组命令获得: + 关于文本检索配置对象的信息可以在psql中使用一组命令获得: \dF{d,p,t}+ PATTERN @@ -2731,7 +2788,7 @@ SELECT plainto_tsquery('supernovae stars'); - 可选参数 PATTERN 可以是文本搜索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: + 可选参数 PATTERN 可以是文本检索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: => \dF *fulltext* @@ -2757,7 +2814,9 @@ SELECT plainto_tsquery('supernovae stars'); \dF+ PATTERN - 列出文本搜索配置(添加 +可获得更详细的信息)。 + + 列出文本检索配置(加上 + 可显示更多细节)。 + => \dF russian List of text search configurations Schema | Name | Description @@ -2796,7 +2855,9 @@ Parser: "pg_catalog.default" \dFd+ PATTERN - 列出文本搜索词典(加上+可获得更详细的信息)。 + + 列出文本检索词典(加上 + 可显示更多细节)。 + => \dFd List of text search dictionaries Schema | Name | Description @@ -2831,7 +2892,9 @@ Parser: "pg_catalog.default" \dFp+ PATTERN - 列出文本搜索解析器(添加 +可获得更详细的信息)。 + + 列出文本检索解析器(加上 + 可显示更多细节)。 + => \dFp List of text search parsers Schema | Name | Description @@ -2882,7 +2945,9 @@ Parser: "pg_catalog.default" \dFt+ PATTERN - 列出文本搜索模板(添加 +可获得更详细的信息)。 + + 列出文本检索模板(加上 + 可显示更多细节)。 + => \dFt List of text search templates Schema | Name | Description @@ -2903,7 +2968,7 @@ Parser: "pg_catalog.default" 限制 - 目前,PostgreSQL的文本搜索功能存在以下限制: + 目前,PostgreSQL的文本检索功能存在以下限制: 每个词位的长度必须小于 2K 字节 @@ -2930,12 +2995,12 @@ Parser: "pg_catalog.default" - 为了对比,PostgreSQL 8.1 的文档包含 10,441 个唯一词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 + 为了对比,PostgreSQL 8.1 的文档包含 10,441 个不同词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 - 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个唯一词。 + 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个不同词。 diff --git a/zh/12/unaccent.sgml b/zh/12/unaccent.sgml index 0bc0bfe7..ea1617ac 100644 --- a/zh/12/unaccent.sgml +++ b/zh/12/unaccent.sgml @@ -8,11 +8,11 @@ - unaccent是一个文本搜索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤字典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文搜索能够以不区分重音的方式处理文本。 + unaccent是一个文本检索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤词典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文检索能够以不区分重音的方式处理文本。 - unaccent当前的实现还不能作为thesaurus词典的正规化字典使用。 + unaccent当前的实现还不能作为thesaurus词典的正规化词典使用。 @@ -61,7 +61,7 @@ - 与其他PostgreSQL文本搜索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含无法转换的字符的行都会被静默忽略,因此规则文件可以包含不适用于当前编码的规则。 + 与其他PostgreSQL文本检索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含无法转换的字符的行都会被静默忽略,因此规则文件可以包含不适用于当前编码的规则。 @@ -74,7 +74,7 @@ 用法 - 安装unaccent扩展会创建一个文本搜索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 + 安装unaccent扩展会创建一个文本检索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 mydb=# ALTER TEXT SEARCH DICTIONARY unaccent (RULES='my_rules'); @@ -95,7 +95,7 @@ mydb=# select ts_lexize('unaccent','Hôtel'); - 下面的示例展示了如何将unaccent词典插入到文本搜索配置中: + 下面的示例展示了如何将unaccent词典插入到文本检索配置中: mydb=# CREATE TEXT SEARCH CONFIGURATION fr ( COPY = french ); mydb=# ALTER TEXT SEARCH CONFIGURATION fr @@ -126,7 +126,7 @@ mydb=# select ts_headline('fr','Hôtel de la Mer',to_tsquery('fr','Hotels') 函数 - unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本搜索环境之外使用。 + unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本检索环境之外使用。 @@ -138,7 +138,7 @@ unaccent(dictionary - 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本搜索词典。 + 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本检索词典。 diff --git a/zh/13/array.sgml b/zh/13/array.sgml index 1b06e1d0..1d2a2443 100644 --- a/zh/13/array.sgml +++ b/zh/13/array.sgml @@ -4,7 +4,7 @@ 数组 - array + 数组 @@ -15,8 +15,8 @@ 数组类型的声明 - array - declaration + 数组 + 声明 @@ -64,8 +64,8 @@ CREATE TABLE tictactoe ( 数组值输入 - array - constant + 数组 + 常量 @@ -86,7 +86,7 @@ CREATE TABLE tictactoe ( (这类数组常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。必要时可能需要显式指定类型。) + linkend="sql-syntax-constants-generic"/>中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。可能需要显式指定类型。) @@ -118,7 +118,10 @@ SELECT * FROM sal_emp; - 多维数组在每个维度上的长度必须匹配。不匹配会导致错误,例如: + + 多维数组的各个子数组在每个维度上的长度必须匹配。不匹配会导致错误,例如: + + INSERT INTO sal_emp VALUES ('Bill', '{10000, 10000, 10000, 10000}', @@ -148,8 +151,8 @@ INSERT INTO sal_emp 访问数组 - array - accessing + 数组 + 访问 @@ -182,9 +185,9 @@ SELECT pay_by_quarter[3] FROM sal_emp; - 我们还可以访问数组或子数组的任意矩形切片。数组切片通过在一个或多个数组维度上写成 + 我们还可以访问数组的任意矩形切片,即子数组。数组切片通过在一个或多个数组维度上写成 lower-bound:upper-bound - 的形式来表示。例如,下面这个查询取回 Bill 在一周前两天日程安排中的第一个项目: + 的形式来表示。例如,下面这个查询取回 Bill 在一周中前两天里每天的首项日程: SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill'; @@ -231,11 +234,11 @@ SELECT schedule[:][1:1] FROM sal_emp WHERE name = 'Bill'; - 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回空值。此外,如果下标超出数组边界,也会返回空值(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是空值而不是错误。 + 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回 NULL。此外,如果下标超出数组边界,也会返回 NULL(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是 NULL 而不是错误。 - 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回空值。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是空值。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回空值。 + 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回 NULL。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是 NULL。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回 NULL。 @@ -289,8 +292,8 @@ SELECT cardinality(schedule) FROM sal_emp WHERE name = 'Carol'; 修改数组 - array - modifying + 数组 + 修改 @@ -327,7 +330,7 @@ UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}' - 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用空值填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含空值。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 + 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用 NULL 填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含 NULL。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 @@ -439,21 +442,21 @@ SELECT array_cat(ARRAY[5,6], ARRAY[[1,2],[3,4]]); 在简单情况下,优先使用上面讨论的连接操作符,而不是直接调用这些函数。不过,由于连接操作符被重载以同时服务于这三种情形,所以在某些场景下使用这些函数之一有助于避免歧义。例如,考虑: -SELECT ARRAY[1, 2] || '{3, 4}'; -- the untyped literal is taken as an array +SELECT ARRAY[1, 2] || '{3, 4}'; -- 未指定类型的字面量被当作数组 ?column? ----------- {1,2,3,4} -SELECT ARRAY[1, 2] || '7'; -- so is this one +SELECT ARRAY[1, 2] || '7'; -- 这个字面量也一样 ERROR: malformed array literal: "7" -SELECT ARRAY[1, 2] || NULL; -- so is an undecorated NULL +SELECT ARRAY[1, 2] || NULL; -- 未加类型修饰的 NULL 也一样 ?column? ---------- {1,2} (1 row) -SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant +SELECT array_append(ARRAY[1, 2], NULL); -- 这可能才是原本想表达的意思 array_append -------------- {1,2,NULL} @@ -467,8 +470,8 @@ SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant 在数组中搜索 - array - searching + 数组 + 搜索 @@ -509,12 +512,20 @@ SELECT * FROM 关于该函数的说明见 - 还可以使用&&操作符搜索数组,它检查左操作数是否与右操作数重叠。例如: + + 也可以使用 && 操作符来搜索数组,它会检查左操作数是否与右操作数有重叠。例如: + + SELECT * FROM sal_emp WHERE pay_by_quarter && ARRAY[10000]; -关于此操作符和其他数组操作符的更多说明,参见。可以通过适当的索引来加速这种搜索,参见。 + + + 关于该操作符和其他数组操作符的更多说明见。如所述,也可以通过适当的索引加速。 - 还可以使用array_positionarray_positions函数在数组中搜索特定值。前者返回某个值在数组中首次出现位置的下标;后者返回一个数组,其中包含该值在数组中所有出现位置的下标。例如: + + 也可以使用 array_positionarray_positions 函数在数组中搜索特定值。前者返回某个值在数组中首次出现位置的下标;后者返回一个数组,其中包含该值在数组中所有出现位置的下标。例如: + + SELECT array_position(ARRAY['sun','mon','tue','wed','thu','fri','sat'], 'mon'); array_position ---------------- @@ -540,7 +551,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); 数组输入和输出语法 - array + 数组 I/O @@ -553,7 +564,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); - 默认情况下,数组各维度的下界索引值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: + 默认情况下,数组各维度的下界下标值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2 FROM (SELECT '[1:1][-2:-1][3:5]={{{1,2,3},{4,5,6}}}'::int[] AS f1) AS ss; diff --git a/zh/13/catalogs.sgml b/zh/13/catalogs.sgml index a347c7cf..a2b8ca2d 100644 --- a/zh/13/catalogs.sgml +++ b/zh/13/catalogs.sgml @@ -310,27 +310,27 @@ pg_ts_config - 文本搜索配置 + 文本检索配置 pg_ts_config_map - 文本搜索配置的词元映射 + 文本检索配置的词元映射 pg_ts_dict - 文本搜索字典 + 文本检索词典 pg_ts_parser - 文本搜索分析器 + 文本检索解析器 pg_ts_template - 文本搜索模板 + 文本检索模板 @@ -7224,12 +7224,12 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config目录包含表示文本搜索配置的条目。一个配置指定某个特定的文本搜索分析器,以及针对该分析器每种输出词元类型所定义的字典列表。分析器由pg_ts_config项表示,而词元到字典的映射则由pg_ts_config系统目录包含表示文本检索配置的条目。一个配置指定某个特定的文本检索解析器,以及针对该解析器每种输出词元类型所定义的词典列表。解析器记录在pg_ts_config条目中,而词元到词典的映射则由pg_ts_config_map中的辅助项定义。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。 @@ -7261,7 +7261,7 @@ SCRAM-SHA-256$<iteration count>:&l cfgname name - 文本搜索配置名 + 文本检索配置名 @@ -7291,7 +7291,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_ts_parser.oid - 该配置的文本搜索分析器的OID + 该配置的文本检索解析器的 OID @@ -7308,11 +7308,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config_map目录包含的项展示了对于每一个文本搜索配置的每一种输出词元类型,有哪些文本搜索字典可供查询以及以何种顺序。 + pg_ts_config_map 系统目录中的条目说明了,对于每个文本检索配置所用解析器的每种输出词元类型,应当查询哪些文本检索词典以及查询的顺序。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7345,7 +7345,7 @@ SCRAM-SHA-256$<iteration count>:&l maptokentype int4 - 一种由配置的分析器送出的词元类型 + 一种由配置的解析器送出的词元类型 @@ -7364,7 +7364,7 @@ SCRAM-SHA-256$<iteration count>:&l (参考 pg_ts_dict.oid - 要查询的文本搜索字典的OID + 要查询的文本检索词典的 OID @@ -7381,11 +7381,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_dict目录包含定义文本搜索字典的项。一个字典依赖于一个文本搜索模板,它指定了所有需要的函数实现,字典本身则为模板支持的用户可设置参数提供值。这种分工允许无权限的用户创建字典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 + pg_ts_dict系统目录包含定义文本检索词典的项。一个词典依赖于一个文本检索模板,它指定了所有需要的实现函数,词典本身则为模板支持的用户可设置参数提供值。这种分工允许普通用户创建词典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7417,7 +7417,7 @@ SCRAM-SHA-256$<iteration count>:&l dictname name - 文本搜索字典名 + 文本检索词典名 @@ -7427,7 +7427,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_namespace.oid - 包含该字典的名字空间OID + 包含该词典的名字空间的 OID @@ -7437,7 +7437,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_authid.oid - 字典的拥有者 + 词典的拥有者 @@ -7447,7 +7447,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_ts_template.oid - 该字典的文本搜索模板的OID + 该词典的文本检索模板的 OID @@ -7473,11 +7473,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_parser目录包含定义文本搜索分析器的项。一个分析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个分析器必须用C语言级别的函数实现,创建新分析器的工作只限于数据库的超级用户。 + pg_ts_parser系统目录包含定义文本检索解析器的项。一个解析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个解析器必须用 C 语言级别的函数实现,创建新解析器的工作只限于数据库的超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7509,7 +7509,7 @@ SCRAM-SHA-256$<iteration count>:&l prsname name - 文本搜索分析器的名字 + 文本检索解析器的名字 @@ -7519,7 +7519,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_namespace.oid - 包含此分析器的名字空间的OID + 包含此解析器的名字空间的 OID @@ -7529,7 +7529,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器启动函数的OID + 解析器启动函数的 OID @@ -7539,7 +7539,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的下一词元函数的OID + 解析器的下一词元函数的 OID @@ -7549,7 +7549,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的关闭函数的OID + 解析器的关闭函数的 OID @@ -7559,7 +7559,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器标题函数的 OID + 解析器的 headline 函数的 OID @@ -7569,7 +7569,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的词汇类型函数的OID + 解析器的 lextype 函数的 OID @@ -7586,11 +7586,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_template目录包含定义文本搜索模板的项。一个模板是一类文本搜索字典的实现骨架。由于一个模板必须用C语言级别的函数实现,新模板的创建只限于数据库超级用户。 + pg_ts_template系统目录包含定义文本检索模板的项。一个模板是一类文本检索词典的实现骨架。由于一个模板必须用 C 语言级别的函数实现,新模板的创建只限于数据库超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7622,7 +7622,7 @@ SCRAM-SHA-256$<iteration count>:&l tmplname name - 文本搜索模板的名字 + 文本检索模板的名字 diff --git a/zh/13/config.sgml b/zh/13/config.sgml index 11487410..6b174733 100644 --- a/zh/13/config.sgml +++ b/zh/13/config.sgml @@ -2456,7 +2456,7 @@ include_dir 'conf.d' 配置 恢复 - 一个备库 + 备库 @@ -3551,7 +3551,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( )。 + 设置规划器对一系列顺序磁盘页面读取中单次读取的代价估计。默认值是 1.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -3709,7 +3708,7 @@ ANY num_sync ( )。 + 设置规划器对一次非顺序磁盘页面读取的代价估计。默认值是 4.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -3722,14 +3721,13 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( 。 如果指定值时没有单位,则以块为单位,即BLCKSZ字节,通常为8kB。默认值是512千字节(512kB)。 @@ -3855,13 +3853,13 @@ ANY num_sync ( num_sync ( - 遗传查询优化 + 遗传查询优化器 - GEQO是一个使用探索式搜索来执行查询规划的算法。它可以降低负载查询的规划时间。 同时,GEQO的检索是随机的,因此它的规划可能会不可确定。 更多信息参阅Chapter 50。 - 遗传查询规划器(GEQO)是一种使用启发式搜索来进行查询规划的算法。它可以降低对于复杂查询(连接很多表的查询)的规划时间,但是代价是它产生的计划有时候要差于使用穷举搜索算法找到的计划。详见。 + 遗传查询优化器(GEQO)是一种使用启发式搜索进行查询规划的算法。它可以缩短复杂查询(连接很多关系的查询)的规划时间,代价是生成的计划有时不如常规穷举搜索算法找到的计划。更多信息见 @@ -3942,7 +3939,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( .) + 目前,约束排除仅在通常用于通过继承树实现表分区的情况下默认启用。为所有表启用它会增加额外的规划开销,这在简单查询上相当明显,而且通常不会为简单查询带来好处。如果没有通过传统继承方式进行分区的表,你可能希望完全关闭它。(注意,分区表的等效功能由另一个参数控制。) @@ -4189,8 +4183,7 @@ SELECT * FROM parent WHERE key = 2400; parallel_leader_participation (boolean) - parallel_leader_participation configuration - parameter + parallel_leader_participation 配置参数 @@ -4242,13 +4235,7 @@ SELECT * FROM parent WHERE key = 2400; - 准备语句(显式准备或隐式生成的,例如 PL/pgSQL)可以使用自定义或通用计划执行。 - 使用其特定的参数值集为每个执行重新生成自定义计划,而通用计划不依赖于参数值,并且可以在执行中重复使用。 - 因此,使用通用计划可以节省计划时间,但如果理想计划严重依赖参数值,则通用计划可能效率低下。 - 这些选项之间的选择通常是自动进行的,但可以通过plan_cache_mode覆盖它。 - 允许的值为 auto (默认的),force_custom_planforce_generic_plan。 - 这个设置是在执行缓存计划时考虑,而不是在准备计划时考虑。 - 更多信息请参阅 . + 预备语句(无论是显式预备的,还是由 PL/pgSQL 等隐式生成的)可以使用自定义计划或通用计划执行。自定义计划会根据每次执行的具体参数值重新生成,而通用计划不依赖参数值,可以在多次执行之间复用。因此,使用通用计划能够节省规划时间,但如果理想计划高度依赖参数值,通用计划可能效率较低。系统通常会自动选择这两种计划,但可以通过plan_cache_mode覆盖这一选择。允许的值为auto(默认值)、force_custom_planforce_generic_plan。系统在执行缓存计划时考虑此设置,而不是在预备计划时。更多信息见 @@ -4265,7 +4252,7 @@ SELECT * FROM parent WHERE key = 2400; - 在哪里做日志 + 日志记录到哪里 日志写到哪里 @@ -4273,7 +4260,7 @@ SELECT * FROM parent WHERE key = 2400; current_logfiles - 和日志_目的地配置参数 + 和 log_destination 配置参数 @@ -4300,7 +4287,7 @@ csvlog log/postgresql.csv - 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设备LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: + 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设施LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: local0.* /var/log/postgresql @@ -4308,7 +4295,7 @@ local0.* /var/log/postgresql - 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源极其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见。 + 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源及其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见 @@ -4324,20 +4311,20 @@ local0.* /var/log/postgresql - 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 + 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息可能不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 - 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供方法来轮转日志文件。还有,在某些不使用日志收集器的平台上可能会导致丢失或者混淆日志输出,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 + 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供便捷的方法来轮转日志文件。还有,在某些平台上,不使用日志收集器可能会导致日志输出丢失或混杂,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 - 日志收集器被设计成从来不会丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 + 日志收集器被设计成从来不会丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它可能会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 @@ -4369,7 +4356,7 @@ local0.* /var/log/postgresql logging_collector被启用时,这个参数设置被创建的日志文件的文件名。 - 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何时区独立的%转义,计算将在由指定的时区中完成)。 + 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何依赖时区的%转义,计算将在由指定的时区中完成)。 被支持的%转义和开放组织的strftime说明中列举的类似。 注意系统的strftime不会被直接使用,因此平台相关(非标准)的扩展无法工作。 默认是postgresql-%Y-%m-%d_%H%M%S.log。 @@ -4396,7 +4383,7 @@ local0.* /var/log/postgresql - 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的十进制格式,该数字必须以一个0(零)开始)。 + 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的八进制格式,该数字必须以一个0(零)开始)。 @@ -4462,7 +4449,7 @@ local0.* /var/log/postgresql - 示例:要保留 24 小时的日志,每个小时一个日志文件,但是在日志文件尺寸超过 1GB 时轮转。可以这样做:将log_filename设置为server_log.%H%M、 + 示例:要保留 24 小时的日志,每个小时一个日志文件,如果日志文件尺寸超过 1GB,也会提前轮转。可以这样做:将log_filename设置为server_log.%H%M、 将log_truncate_on_rotation设置为on、 将log_rotation_age设置为60并且 将log_rotation_size设置为1000000。 @@ -4481,7 +4468,7 @@ local0.* /var/log/postgresql - 当启用了向syslog记录时,这个参数决定要使用的syslog设备。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4、 + 当启用了向syslog记录时,这个参数决定要使用的syslog设施。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4LOCAL5LOCAL6LOCAL7中选择,默认值是LOCAL0。还请参阅系统的syslog守护进程的文档。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -4536,7 +4523,7 @@ local0.* /var/log/postgresql - 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,有必要让消息保持逻辑上的整体性(也更加有用)。 + 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,让消息保持逻辑上的完整性可能是必要的,也可能更有用。 @@ -4598,9 +4585,7 @@ local0.* /var/log/postgresql - 控制在服务器日志中记录哪些导致错误条件的SQL语句。当前的SQL语句将包含在任何指定 - severity - 或更高消息的日志条目中。 + 控制在服务器日志中记录哪些导致错误条件的SQL语句。对于达到指定严重级别或更高级别的消息,其日志条目中会包含当前 SQL 语句。 有效值为DEBUG5DEBUG4DEBUG3DEBUG2DEBUG1、 @@ -4640,7 +4625,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -4678,7 +4663,7 @@ local0.* /var/log/postgresql - log_min_duration_statement的其他注释也适用于此设置。 + log_min_duration_statement的其他说明也适用于此设置。 @@ -4693,8 +4678,8 @@ local0.* /var/log/postgresql - 确定持续时间超过的语句的比例将被记录。 - 采样是随机的,例如0.5表示统计上有一半的机会任何给定的语句将被记录。 + 确定持续时间超过的语句中,将被记录的语句比例。 + 采样是随机的,例如0.5表示任意给定语句被记录的统计概率为二分之一。 默认值为1.0,表示记录所有采样的语句。 将此设置为零将禁用采样语句持续时间记录,与将log_min_duration_sample设置为-1相同。 只有超级用户能更改这个设置。 @@ -4712,7 +4697,7 @@ local0.* /var/log/postgresql - 设置所有语句都被记录的事务的比例,除了其他原因记录的语句。它适用于每个新事务,无论其语句的持续时间如何。 + 设置需要记录全部语句的事务比例,这些记录是在因其他原因记录的语句之外额外进行的。它适用于每个新事务,无论其语句的持续时间如何。 采样是随机的,例如0.1表示任何给定事务被记录的统计概率是十分之一。 log_transaction_sample_rate可以帮助构建事务样本。 默认值为0,表示不记录任何额外事务的语句。将其设置为1会记录所有事务的所有语句。 @@ -4755,7 +4740,7 @@ local0.* /var/log/postgresql DEBUG1 .. DEBUG5 - 为开发者提供连续的更详细的信息。 + 为开发者提供逐级更加详细的信息。 DEBUG INFORMATION @@ -4814,7 +4799,7 @@ local0.* /var/log/postgresql - 记录什么到日志 + 记录哪些内容 @@ -4835,7 +4820,7 @@ local0.* /var/log/postgresql - application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。它也会被通过包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为问号(?)。 + application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。也可以通过将其包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为问号(?)。 @@ -4859,7 +4844,6 @@ local0.* /var/log/postgresql - 这个参数启用发出各种调试输出。当设置时,会打印生成的解析树, 查询重写输出,或执行的每个查询的执行计划。这些信息是在LOG 信息级别发出,因此默认的,它们会出现在服务器日志中,但不会发送给客户端。 可以通过 client_min_messages和/或log_min_messages 来设置。这些参数缺省是off。 这些参数将会让多种调试输出被发出。当被设置时,它们为每一个被执行的查询打印结果分析树、查询重写器输出或执行计划。这些消息在LOG消息级别上被发出,因此默认情况下它们将出现在服务器日志中但不会被发送到客户端。你可以通过调整和/或来改变这种情况。这些参数默认是关闭的。 @@ -4893,7 +4877,7 @@ local0.* /var/log/postgresql 导致检查点和重启点在服务器日志中记录。日志消息中包括一些统计信息, 包括写入的缓冲区数量和写入它们所花费的时间。此参数只能在 - postgresql.conf文件或服务器命令行中设置。默认值为开启。 + postgresql.conf文件或服务器命令行中设置。默认值为关闭。 @@ -4952,7 +4936,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -4975,7 +4959,7 @@ local0.* /var/log/postgresql 控制在服务器日志中记录的每条消息的详细程度。有效值为TERSE, - DEFAULTVERBOSE,每个值都会添加更多字段到显示的消息中。 + DEFAULTVERBOSE,它们依次在显示的消息中增加更多字段。 TERSE不包括DETAILHINTQUERYCONTEXT错误信息的记录。 VERBOSE输出包括SQLSTATE错误代码 @@ -4995,7 +4979,7 @@ local0.* /var/log/postgresql - 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致很微小的性能损失。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致不可忽视的性能开销。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -5012,7 +4996,7 @@ local0.* /var/log/postgresql %字符开始转义序列,它将被按照下文描述的替换成状态信息。 未识别的转义被忽略。其他字符被直接复制到日志行。某些转义只被会话进程识别并且被主服务器进程等后台进程当作空。 通过指定一个在%之后和该选项之前的数字可以让状态信息左对齐或右对齐。 - 负值将导致在右边用空格填充状态信息已达到最小宽度,而正值则在左边填充。填充对于日志文件的人类可读性大有帮助。 + 负值将导致在右边用空格填充状态信息以达到最小宽度,而正值则在左边填充。填充对于日志文件的人类可读性大有帮助。 @@ -5077,8 +5061,8 @@ local0.* /var/log/postgresql %n - 带毫秒的时间戳(作为 Unix 时代) - no + 带毫秒精度的 Unix 时间戳 + %i @@ -5201,8 +5185,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 此设置仅影响作为结果打印的日志消息,, 和相关的设置。 - 该设置的非零值会增加一些开销,特别是当参数以二进制形式发送时,因为需要转换为文本。 + 此设置仅影响由及相关设置产生的日志消息。此设置为非零值时会增加一些开销,特别是以二进制形式发送参数时,因为需要将参数转换为文本。 @@ -5246,7 +5229,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' UPDATEDELETETRUNCATE, 和COPY FROM。 如果PREPAREEXECUTE和 - EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个执行消息时会产生日志并且会包括绑定参数的值(任何内嵌的单引号会被双写)。 + EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个 Execute 消息时会产生日志并且会包括 Bind 参数的值(任何内嵌的单引号会被双写)。 @@ -5257,7 +5240,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在执行阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 + 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在 Execute 阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 @@ -5296,7 +5279,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 控制临时文件名和大小的日志记录。 - 临时文件可以用于排序、哈希和临时查询结果。 + 临时文件可以用于排序、hash 和临时查询结果。 如果通过此设置启用,每当删除临时文件时都会发出日志记录。 值为零时记录所有临时文件信息,而正值仅记录大小大于或等于指定数据量的文件。 如果未指定单位,则将其视为千字节。 @@ -5376,7 +5359,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 设置log_filenamelog_rotation_age为你的日志文件提供一种一致的、可预测的命名空间。这让你预测文件名会是怎样以及知道什么时候一个个体日志文件完成并且因此准备好被导入。 + 设置log_filenamelog_rotation_age,为日志文件提供一致且可预测的命名方案。这样就能预测文件名,并知道单个日志文件何时已完成写入、可以导入。 @@ -5405,8 +5388,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 进程标题 - 这些设置控制服务器进程的进程标题如何修改。通常可以通过ps等程序查看进程标题, - 在 Windows 上则可以使用Process Explorer。详情参见。 + 这些设置控制服务器进程的进程标题如何修改。通常可以通过ps等程序查看进程标题,在 Windows 上则可以使用Process Explorer。详情参见 @@ -5440,7 +5422,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 每次服务器接收到新的SQL命令时,都可以更新进程标题。 + 启用后,每次服务器接收到新的 SQL 命令时都会更新进程标题。 在大多数平台上,默认情况下此设置为on,但在Windows上默认为off, 因为该平台更新进程标题的开销较大。 只有超级用户能更改这个设置。 @@ -5475,7 +5457,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对每个会话当前执行命令的信息收集,包括命令开始执行的时间。 - 此参数默认为开启状态。请注意,即使启用了此信息,只有超级用户、具有 + 此参数默认为开启状态。请注意,即使启用了此参数,只有超级用户、具有 pg_read_all_stats角色权限的角色和拥有被报告会话的用户 (包括属于他们具有权限的角色的会话)才能看到此信息,因此不应构成安全风险。 只有超级用户能更改这个设置。 @@ -5493,7 +5475,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 为每个活动会话指定存储当前执行命令的文本所保留的内存量,它们被用于pg_stat_activity.query域。 + 为每个活动会话指定存储当前执行命令的文本所预留的内存量,它们被用于pg_stat_activity.query字段。 如果指定值时没有单位,则以字节为单位。默认值是 1024字节。这个参数只能在服务器启动时被设置。 @@ -5510,7 +5492,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对数据库活动的统计信息收集。 - 此参数默认为开启,因为自动清理守护进程需要收集的信息。 + 此参数默认为开启,因为自动清理守护进程需要这些收集到的信息。 只有超级用户能更改这个设置。 @@ -5524,7 +5506,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用数据库I/O调用的计时。 默认情况下,此参数处于关闭状态,因为它将重复查询操作系统的当前时间,这可能会在某些平台上造成显著的开销。 您可以使用工具来测量系统上计时的开销。 + 启用数据库I/O调用的计时。 默认情况下,此参数处于关闭状态,因为它将重复查询操作系统的当前时间,这可能会在某些平台上造成显著的开销。 你可以使用工具来测量系统上计时的开销。 I/O计时信息显示在 pg_stat_database中,也显示在使用BUFFERS选项的输出中, 并由提供。只有超级用户能更改这个设置。 @@ -5542,7 +5524,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用函数调用次数和时间的跟踪。指定pl以仅跟踪过程语言函数, + 启用函数调用次数和耗时的跟踪。指定pl以仅跟踪过程语言函数, all以同时跟踪SQL和C语言函数。默认值为none, 即禁用函数统计跟踪。只有超级用户能更改这个设置。 @@ -5602,7 +5584,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 对于每个查询,将各自模块的性能统计输出到服务器日志中。这是一个简单的性能分析工具,类似于Unix getrusage()操作系统功能。 - log_statement_stats报告总语句统计,而其他选项报告每个模块的统计信息。 + log_statement_stats报告整个语句的统计信息,而其他选项报告每个模块的统计信息。 log_statement_stats不能与任何单独模块选项一起启用。所有这些选项默认情况下都是禁用的。 只有超级用户才能更改这些设置。 @@ -5618,7 +5600,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 自动清理 - autovacuum + 自动清理 配置参数 @@ -5658,10 +5640,10 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 每次由自动清理执行的操作都会被记录,如果运行时间至少达到指定时间。将此设置为零会记录所有自动清理操作。 + 当自动清理执行的操作运行时间至少达到指定时间时,就会记录该操作。将此设置为零会记录所有自动清理操作。 -1(默认值)会禁用记录自动清理操作。如果未指定单位,则将其视为毫秒。 例如,如果将其设置为250ms,则所有运行时间为250ms或更长的自动清理和分析都将被记录。 - 此外,当此参数设置为任何值而不是-1时,如果由于冲突的锁定或同时删除的关系而跳过自动清理操作,则会记录消息。 + 此外,当此参数设置为任何非-1值时,如果由于冲突锁或关系被并发删除而跳过自动清理操作,则会记录消息。 启用此参数可帮助跟踪自动清理活动。 此参数只能在postgresql.conf文件或服务器命令行中设置;但可以通过更改表存储参数来覆盖对单个表的设置。 @@ -5895,7 +5877,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; DEBUG1LOGNOTICEWARNINGERROR。 每个级别都包括其后的所有级别。级别越靠后,被发送的消息越少。默认值是NOTICE。 - 注意LOG在这里有与中不同的排名。 + 注意LOG在这里的排序与中的不同。 @@ -5913,11 +5895,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,用于进行搜索该对象的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 + 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,搜索该对象时的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 - search_path的值必需是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被安静地忽略。 + search_path的值必须是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被静默忽略。 @@ -5945,11 +5927,12 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个参数的缺省值是"$user", public。这种设置支持一个数据库(其中没有用户拥有私有模式,并且所有人共享使用public)、每个用户私有模式及其组合的共享使用。其它效果可以通过全局或者针对每个用户修改默认搜索路径设置获得。 + 这个参数的默认值是"$user", public。这种设置支持共享使用数据库(用户没有私有模式,所有人共享使用public)、每个用户拥有私有模式,以及二者的组合。 + 还可以通过全局或针对每个用户修改默认搜索路径设置来获得其他效果。 - 更多有关方案处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 + 更多有关模式处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 @@ -5969,7 +5952,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,只要有至少一条策略被应用则查询就会失败。默认为on。受限的行可见性会导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS)属性的角色没有效果。 + 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,原本会应用至少一条策略的查询就会失败。默认为on。受限的行可见性可能导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS属性的角色)没有效果。 @@ -5988,8 +5971,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个参数指定了在创建表或物化视图时使用的默认表访问方法,如果CREATE命令没有明确指定访问方法, - 或者当使用SELECT ... INTO时,不允许指定表访问方法。默认值是heap。 + 创建表或物化视图时,如果CREATE命令没有显式指定访问方法,或者使用了不允许指定表访问方法的SELECT ... INTO,则使用此参数指定的默认表访问方法。默认值为heap @@ -6009,7 +5991,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建企图将失败。 + 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建尝试将失败。 @@ -6017,7 +5999,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当创建数据库时也会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 + 创建数据库时也不会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 @@ -6046,11 +6028,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被放置在里表中的连续表空间中。如果列表被选中元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 + 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被依次放置在列表中的连续表空间中。如果列表中被选中的元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 - 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,类似于为用户指定一个不具有CREATE权限的表空间。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特殊地,使用一个在postgresql.conf中设置的值时,这条规则起效。 + 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,指定一个用户不具有CREATE权限的表空间也同样是错误。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特别是,使用一个在postgresql.conf中设置的值时,这条规则起效。 @@ -6073,7 +6055,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 这个参数通常为打开。 当设置为off时,它禁用期间对函数体字符串的验证。 - 禁用验证避免了验证处理的副作用,特别避免了如向前引用导致的伪肯定。 + 禁用验证避免了验证处理的副作用,也避免前向引用等问题导致的误报。 在代表其他用户载入函数之前设置这个参数为offpg_dump会自动这样做。 @@ -6116,7 +6098,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态 。默认是off(读/写)。 + 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态。默认是off(读/写)。 @@ -6137,11 +6119,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当运行在serializable隔离级别时,一个可延迟只读 SQL 事务可以在它被允许继续之前延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的负荷;因此串行化代码将没有任何理由因为并发更新而强制它中断,使得这个选项适合于长时间运行的只读事务。 + 当运行在serializable隔离级别时,一个可延迟只读 SQL 事务可能在获准继续之前被延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的开销;因此串行化代码将没有任何理由因为并发更新而强制它中止,使得这个选项适合于长时间运行的只读事务。 - 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些操作在低于serializable隔离级别上的事务无效。默认值是off。 + 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些运行在低于serializable隔离级别上的事务无效。默认值是off @@ -6185,7 +6167,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的只读状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -6205,7 +6187,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的可延迟性状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -6219,16 +6201,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 控制当前会话中复制相关触发器和规则的触发。 - 可能的值是origin(默认值), - replicalocal。 - 设置此参数会导致丢弃先前缓存的任何查询计划。 - 只有超级用户能更改这个设置。 + 控制当前会话中复制相关触发器和规则的触发。设置此变量需要超级用户权限,并会丢弃任何先前缓存的查询计划。 + 可用值为origin(默认值)、replicalocal 这个设置的预期用途是由逻辑复制系统在应用所复制的更改时将它设置为replica。 - 其效果将是触发器和规则(没有对其默认配置做修改)在复制机上将不会被触发。 + 其效果将是触发器和规则(没有对其默认配置做修改)在副本上将不会被触发。 更多信息请参考的子句ENABLE TRIGGER以及ENABLE RULE @@ -6258,9 +6237,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 超时从命令到达服务器的时间开始计算,一直到它被服务器完成为止。 - 如果单个简单查询消息中出现多个 SQL 语句,超时将分别应用于每个语句。(PostgreSQL 13 之前的版本通常将超时应用于整个查询字符串。 - 在扩展查询协议中,当任何与查询相关的消息(解析、绑定、执行、描述)到达时,超时就开始运行,并且可以通过执行完成或同步消息来取消超时。 + 超时从命令到达服务器时开始计算,直到服务器完成该命令为止。 + 如果单个简单查询消息中出现多个 SQL 语句,超时将分别应用于每个语句。 + (PostgreSQL 13 之前的版本通常将超时应用于整个查询字符串。) + 在扩展查询协议中,当任何与查询相关的消息(Parse、Bind、Execute、Describe)到达时开始计时, + 并在处理完 Execute 或 Sync 消息时取消计时。 @@ -6279,13 +6260,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 如果任何语句在试图获取表、索引、行或其他数据库对象上的锁时等到超过指定的时间量,该语句将被中止。 + 如果任何语句在试图获取表、索引、行或其他数据库对象上的锁时等待超过指定的时间量,该语句将被中止。 该时间限制独立地应用于每一次锁获取尝试。该限制会应用到显式锁定请求(如LOCK TABLE或不带NOWAITSELECT FOR UPDATE)和隐式获得的锁。 如果指定值时没有单位,则以毫秒为单位。一个零值(默认)将禁用超时。 - 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为事务超时将总是第一个被触发。 + 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为语句超时将总是第一个被触发。 如果log_min_error_statement 被设置为ERROR 或更低,超时的语句将被记录。 @@ -6319,8 +6300,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; + - 当表的pg_class.relfrozenxid字段达到该设置指定的年龄时,VACUUM会执行激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值是 1.5 亿个事务。尽管用户可以将该值设置为 0 到 20 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的 95%,从而在触发防回卷 autovacuum 之前仍有机会执行一次常规手工VACUUM。更多信息请参见。 + 如果表的pg_class.relfrozenxid字段达到此设置指定的年龄,VACUUM就会执行一次激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值为 1.5 亿个事务。尽管用户可以将该值设置在 0 到 20 亿之间,VACUUM仍会悄悄将其有效值限制为不超过的 95%,以便在针对该表启动防回卷自动清理之前,周期性手工VACUUM仍有机会运行。详见 @@ -6333,7 +6315,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 指定VACUUM在扫描表时用来决定是否冻结行版本的切断年龄(以事务计)。默认值是 5000 万个事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见。 + 指定VACUUM在扫描表时用来决定是否冻结行版本的截止年龄(以事务计)。默认值是 5000 万个事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见 @@ -6345,8 +6327,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; + - 当表的pg_class.relminmxid字段达到该设置指定的年龄时,VACUUM会执行激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不是只扫描那些可能包含死元组的页面。默认值是 1.5 亿个多事务。尽管用户可以将该值设置为 0 到 20 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的 95%,从而在触发防回卷 autovacuum 之前仍有机会执行一次常规手工VACUUM。更多信息请参见。 + 如果表的pg_class.relminmxid字段达到此设置指定的年龄,VACUUM就会执行一次激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值为 1.5 亿个多事务。尽管用户可以将该值设置在 0 到 20 亿之间,VACUUM仍会悄悄将其有效值限制为不超过的 95%,以便在针对该表启动防回卷清理之前,周期性手工VACUUM仍有机会运行。详见 @@ -6359,7 +6342,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 指定VACUUM在扫描表时用来决定是否将多事务 ID 替换为较新的事务 ID 或多事务 ID 的切断年龄(以多事务计)。默认值是 500 万个多事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见。 + 指定VACUUM在扫描表时用来决定是否将多事务 ID 替换为较新的事务 ID 或多事务 ID 的截止年龄(以多事务计)。默认值是 500 万个多事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见 @@ -6393,7 +6376,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这里的实际选择都是根据爱好做出的,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码将比 base64 编码更大。 + 这里的实际选择主要取决于偏好,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码会比 base64 编码略大。 @@ -6414,7 +6397,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当在XML和字符串值之间进行转换时,无论设置DOCUMENT或 CONTENT都是隐式的。可参阅Section 8.13。 有效值是DOCUMENT和CONTENT。 缺省值是CONTENT。当在 XML 和字符串值之间进行转换时,设置DOCUMENTCONTENT都是隐式的。详见。有效值是DOCUMENTCONTENT。默认值是CONTENT。 + 设置在 XML 与字符串值之间进行转换时,隐含采用DOCUMENT还是CONTENT。 + 有关说明参见。有效值是DOCUMENTCONTENT。默认值是CONTENT @@ -6465,7 +6449,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 区域和格式化 + 区域设置和格式化 @@ -6479,7 +6463,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域行为的设置初始化配置文件。 + 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域设置行为的设置初始化配置文件。 @@ -6492,10 +6476,13 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置间隔值的显示格式。值sql_standard将产生匹配SQL标准间隔文本的输出。当参数被设置为ISO时,值postgres(默认)将产生匹配PostgreSQL发行 8.4 之前的输出。当DateStyle参数被设置为非ISO输出时,值postgres_verbose会产生匹配PostgreSQL发行 8.4 之前的输出。值iso_8601会产生匹配在 ISO 8601 的 4.4.3.2 节中定义的带标志符格式的时间间隔的输出。 + 设置时间间隔值的显示格式。值sql_standard会生成符合SQL标准时间间隔字面量的输出。 + 值postgres(默认值)的输出与PostgreSQL 8.4 之前版本中设为ISO时的输出一致。 + 值postgres_verbose的输出与PostgreSQL 8.4 之前版本中DateStyle设为非ISO输出时的输出一致。 + 值iso_8601会生成符合 ISO 8601 第 4.4.3.2 节定义的时间间隔带标志符格式的输出。 - IntervalStyle参数也可以影响对有歧义的间隔输入的解释。详见。 + IntervalStyle参数也会影响对有歧义的时间间隔输入的解释。详见 @@ -6553,23 +6540,23 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 如果值为1(默认值)或更高,浮点值被输出为最短-精度格式;参见。 + 如果值为 1(默认值)或更高,浮点值被输出为最短精确格式;参见。 实际生成的位数只取决于输出的值,而不取决于此参数的值。 - float8 值最多需要 17 位数字,float4值最多需要9位数字。 + float8 值最多需要 17 位数字,float4值最多需要9位数字。 这种格式既快速又精确,在正确读取时精确地保留了原始的二进制浮点值。为了历史兼容性,允许的值最大为3。 如果值为零或负,则输出四舍五入为给定的十进制精度。 - 使用的精度是根据此参数的值减小的类型((FLT_DIGDBL_DIG,视情况而定)的标准位数。 + 所用精度以该类型的标准位数(根据类型使用FLT_DIGDBL_DIG)为基础,再按此参数的值减少。 (例如,指定 -1 将导致float4 值输出四舍五入为 5 位有效数字,而float8值四舍五入为 14 位。) - 此格式较慢,不会保留二进制浮点值的所有位,但可能令人更易于阅读。 + 此格式较慢,不会保留二进制浮点值的所有位,但可能更便于阅读。 此参数的含义,以及其默认值,在 PostgreSQL 12 中发生了变化; - 参见 以便进一步讨论。 + 参见 了解进一步讨论。 @@ -6605,11 +6592,11 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 在一些系统上,这个区域分类并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 + 在一些系统上,这个区域设置类别并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 - 只有超级用户能更改这个设置。 + 只有超级用户能更改这个设置,因为它会同时影响发送到服务器日志和客户端的消息,设置不当可能降低服务器日志的可读性。 @@ -6624,7 +6611,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化货币量的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化货币量的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -6639,7 +6626,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化数字的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化数字的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -6654,7 +6641,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化日期和时间的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化日期和时间的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -6669,7 +6656,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 选择被那些没有显式参数指定配置的文本搜索函数变体使用的文本搜索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配区域的配置,initdb将用对应于选中的lc_ctype区域的设置初始化配置文件。 + 选择被那些没有显式参数指定配置的文本检索函数变体使用的文本检索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配该区域设置的配置,initdb将用对应于选中的lc_ctype区域设置的值初始化配置文件。 @@ -6683,7 +6670,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 为了载入附加的功能或者达到提高性能的目的,可用多个设置来预先载入共享库到服务器中。 - 例如'$libdir/mylib'设置可能会导致mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 + 例如'$libdir/mylib'设置会使mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 @@ -6692,12 +6679,12 @@ SET XML OPTION { DOCUMENT | CONTENT }; 只有特别为与PostgreSQL一起使用设计的共享库才能以这种方式载入。每一个PostgreSQL支持 - 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非PostgreSQL无法 + 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非 PostgreSQL 库无法 以这种方式被载入。你可能可以使用操作系统的工具(如LD_PRELOAD)载入它。 - 总之,请参考特定模块的文档来用推荐的方法载入它。 + 一般来说,请参考特定模块的文档来用推荐的方法载入它。 @@ -6729,9 +6716,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 这个特性的目的是允许非特权用户在特定的会话中载入正在调试的或者性能度量库, - 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客 - 户端的PGOPTIONS环境变量或者 + 这个特性的目的是允许非特权用户在特定的会话中载入用于调试或性能测量的库, + 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客户端的PGOPTIONS环境变量或者 ALTER ROLE SET来设置这个参数。 @@ -6768,7 +6754,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 不同,相对于在库被第一次使用 - 时载入它,在会话开始时载入库并没有什么性能优势。不过,当使用连接池时这样做还是有一些 + 时载入它,在会话开始时载入库并没有明显的性能优势。不过,当使用连接池时这样做还是有一些 优势。 @@ -6806,9 +6792,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 在 Windows 主机上,在服务器启动时预载入一个库并不会减少启动每个新服务器进程所需的 - 时间;每一个服务器进程将会重新载入预载入的库。不过,对于那些要在postmaster启动时 + 时间;每一个服务器进程将会重新载入所有预载入的库。不过,对于那些要在postmaster启动时 执行操作的库来说,Windows 主机上的 - shared_preload_libraries任然有用。 + shared_preload_libraries仍然有用。 @@ -6882,7 +6868,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - GIN 索引返回的集合尺寸的软上限。详见。 + GIN 索引扫描返回的集合尺寸的软上限。详见 @@ -6914,18 +6900,18 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这是在锁上等待的时间,然后再检查是否存在死锁条件。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 + 指定在检查是否发生死锁之前等待锁的时间。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 我们乐观地假设在生产应用程序中死锁并不常见,所以在检查死锁之前只是等待一段时间。 增加此值会减少在不必要的死锁检查中浪费的时间,但会减慢实际死锁错误的报告速度。 如果未指定单位,则将其视为毫秒。 - 默认值为一秒(1s),这可能是您在实践中想要的最小值。 - 在负载较重的服务器上,您可能希望提高它。 - 理想情况下,设置应超过您的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 + 默认值为一秒(1s),这可能是你在实践中想要的最小值。 + 在负载较重的服务器上,你可能希望提高它。 + 理想情况下,设置应超过你的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 只有超级用户能更改这个设置。 - 当被设置时,这个参数还可以决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 + 当被设置时,这个参数也决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 @@ -6976,7 +6962,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制在谓词锁被提升为覆盖整个关系之前,该谓词锁能够在单个关系上锁住多少页面或元组。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个关系之前,可以对单个关系中的多少页面或元组加谓词锁。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -6991,7 +6977,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制在谓词锁被提升为覆盖整个页面之前,该谓词锁能在单一页面上锁住多少行。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个页面之前,可以对单个页面中的多少行加谓词锁。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -7017,7 +7003,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个空数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。对于那些要求旧行为的应用的向后兼容性,这个变量可以被设置为off。 + 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个值为空值的数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。为了向后兼容那些要求旧行为的应用,这个变量可以被设置为off @@ -7035,11 +7021,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制字符串文本中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\。如果客户端代码没有做到正确转义,那么将会导致 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 + 这个参数控制字符串字面量中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\。如果客户端代码没有做到正确转义,那么就可能遭到 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 - 注意在符合标准的字符串文本中,\就表示\。这个参数只影响不符合标准的文本的处理,包括转义字符串语法(E'...')。 + 注意在符合标准的字符串字面量中,\就表示\。这个参数只影响不符合标准的字面量的处理,包括转义字符串语法(E'...')。 @@ -7055,11 +7041,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 打开时,如果在普通字符串文本中('...'语法)出现了 一个反斜线(\)并且standard_conforming_strings为关闭,那么就会发出一个警告。默认值是on。 + 打开时,如果在普通字符串字面量中('...'语法)出现了 一个反斜线(\)并且standard_conforming_strings为关闭,那么就会发出一个警告。默认值是on - 希望使用反斜线作为转义符的应用应该被修改来使用转义字符串语法(E'...'),因为在 SQL 标准中普通字符串的默认行为是将反斜线视作一个普通字符。这个变量可以被启用来帮助定位需要被更改的代码。 + 希望使用反斜线作为转义符的应用应该被修改来使用转义字符串语法(E'...'),因为按照 SQL 标准,普通字符串现在默认将反斜线视作一个普通字符。这个变量可以被启用来帮助定位需要被更改的代码。 @@ -7080,7 +7066,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 设置这个参数不会禁用所有与大对象相关的安全检查 — 除了那些在PostgreSQL 9.0中已经修改了的默认行为。 + 设置此变量不会禁用所有与大对象相关的安全检查 — 只禁用那些在PostgreSQL 9.0 中默认行为发生变化的检查。 @@ -7122,7 +7108,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' standard_conforming_strings (boolean) - 字符串标准符合 + 字符串符合标准 standard_conforming_strings配置参数 @@ -7130,7 +7116,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 控制普通字符串文本('...')是否按照 SQL 标准把反斜线当普通文本。从PostgreSQL 9.1 开始,默认值为on(之前的发行中默认值为off)。应用可以检查这个参数来判断字符串文本如何被处理。这个参数的存在也可以被当做转义字符串语法(E'...')被支持的标志。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 + 控制普通字符串字面量('...')是否按照 SQL 标准把反斜线当普通文本。从PostgreSQL 9.1 开始,默认值为on(之前的发行中默认值为off)。应用可以检查这个参数来判断字符串字面量如何被处理。这个参数的存在也可以被当做转义字符串语法(E'...')被支持的标志。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 @@ -7145,7 +7131,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询来,这样的扫描会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on。 + 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询,这样的扫描可能会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on @@ -7168,15 +7154,15 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr得出空值值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空(未知)。因此这个参数默认为off。 + 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr计算结果为空值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空值(未知)。因此这个参数默认为off - 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释)。它们不是非常有用并且在普通应用中也不常见,在应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及 空值的表达式的语义上感到困惑,因此这个选项默认为关闭。 + 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释),它们不是非常有用并且在普通应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及空值的表达式语义感到困惑,因此这个选项默认为关闭。 - 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不是劣质程序的一般修复。 + 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不能普遍修复错误的程序写法。 @@ -7219,7 +7205,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 当被设置为开(on),PostgreSQL将在一次后端崩溃后自动重新初始化。 + 当设置为 on(默认值)时,PostgreSQL将在一次后端崩溃后自动重新初始化。 让这个值设置为开(on)通常是将数据库可用性最大化的最佳方法。但是在某些环境中,例如PostgreSQL被集群软件调用时,禁用重启可能很有用,这样集群软件可以得到控制并且采取它认为适当的行动。 @@ -7239,7 +7225,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果设置为关(off),PostgreSQL在将修改的数据文件刷新到文件系统失败时,将引发PANIC级错误。 + 当设置为 off(默认值)时,PostgreSQL在将修改后的数据文件刷盘到文件系统失败时,将引发PANIC级错误。 这样会导致数据库服务器崩溃。这个参数只能在服务器启动时被设置。 @@ -7248,8 +7234,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果设置为开(on),PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷新操作。 - 仅在调查操作系统假如回写失败时对缓冲数据的处理方式的情况下,才将其设置为开(on)。 + 如果设置为开(on),PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷盘操作。 + 只有在调查清楚操作系统在回写失败时如何处理缓冲数据之后,才应将其设置为开(on)。 @@ -7262,11 +7248,10 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 预置选项 - 下列参数是只读的。 - 同样,它们被排除在postgresql.conf文件示例之外。 - 这些选项报告特定应用可能感兴趣的多种PostgreSQL行为,特别是管理前端相关的行为。 - 所有这些都是在PostgreSQL被编译或者它被安装时决定的。 - + 下列参数是只读的,在编译或安装 PostgreSQL 时确定。 + 因此,它们未列入示例 postgresql.conf 文件。 + 这些选项报告 PostgreSQL 行为的各个方面,某些应用(特别是管理前端)可能对此感兴趣。 + @@ -7295,7 +7280,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告对这个集簇是否启用了数据校验码。详见。 + 报告对这个集簇是否启用了数据校验和。详见 @@ -7308,7 +7293,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 在Unix系统上,这个参数报告启动时的数据目录(由定义)的权限。 + 在 Unix 系统上,这个参数报告服务器启动时数据目录(由定义)的权限。 (在Microsoft Windows上这个参数将总是显示0700。) 更多信息请参考 @@ -7344,7 +7329,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告PostgreSQL是否在编译时打开了 64 位整数日期和时间。从PostgreSQL 10起,这个值总是on。 + 报告PostgreSQL是否在编译时启用了对 64 位整数日期和时间的支持。从PostgreSQL 10起,这个值总是on @@ -7391,7 +7376,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定的。默认值是 100 个参数。 + 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定。默认值是 100 个参数。 @@ -7406,7 +7391,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64 ;因此max_identifier_length的默认值是 63,但是在使用多字节编码时可以少于 63 个字符。 + 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64;因此max_identifier_length的默认值是 63 字节,在使用多字节编码时,这可能不足 63 个字符。 @@ -7467,7 +7452,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告服务器版本数值。它是由编译服务器时的PG_VERSION值决定的。 + 报告服务器的版本号。它是由编译服务器时的PG_VERSION值决定的。 @@ -7482,7 +7467,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告服务器版本数值的整数值。它是由编译服务器时的PG_VERSION_NUM值决定的。 + 以整数形式报告服务器的版本号。它是由编译服务器时的PG_VERSION_NUM值决定的。 @@ -7497,8 +7482,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告此PostgreSQL服务器已构建的 SSL 库的名称(即使此实例当前未配置或使用 SSL), - 例如OpenSSL,或一个空字符串(如果没有)。 + 报告此PostgreSQL服务器在构建时使用的 SSL 库的名称(即使此实例当前未配置或使用 SSL), + 例如OpenSSL,如果没有使用 SSL 库,则报告空字符串。 @@ -7541,11 +7526,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 自定义选项 - 这个特性被设计用来由附加模块向PostgreSQL添加通常不为系统知道的参数(例如过程语言)。这允许使用标准方法配置扩展模块。 + 这个特性允许附加模块(例如过程语言)向PostgreSQL添加系统通常不认识的参数。这样便能以标准方式配置扩展模块。 - 自定义选项有两部分名称:一个扩展名,然后是一个句点,再然后是正确的参数名,就像 SQL 中的合格名称。一个示例是plpgsql.variable_conflict。 + 自定义选项的名称由两部分组成:扩展名称和参数名本身,中间用句点分隔,类似于 SQL 中的限定名。例如plpgsql.variable_conflict @@ -7553,7 +7538,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' PostgreSQL将接受任何两部分参数名称的设置。 这些变量被视为占位符,在定义它们的模块加载之前没有任何功能。 当加载扩展模块时,它将添加其变量定义并根据这些定义转换任何占位符值。 - 如果存在以其扩展名开头的任何未识别的占位符,将发出警告并删除这些占位符。 + 如果存在以其扩展名称开头的任何未识别的占位符,将发出警告。 @@ -7577,7 +7562,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 允许将表空间创建为pg_tblspc内的目录,当CREATE TABLESPACE命令提供空位置字符串时。 + 当向CREATE TABLESPACE命令提供空的位置字符串时,允许将表空间创建为pg_tblspc内的目录。 这旨在允许测试主库和备库在同一台机器上运行的复制场景。这样的目录可能会混淆备份工具,因为这些工具期望在该位置只找到符号链接。 只有超级用户能更改这个设置。 @@ -7594,8 +7579,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 允许修改系统表的结构以及对系统表进行某些其他风险操作。即使对于超级用户,这也通常是不允许的。 - 不明智地使用此设置可能导致无法检索的数据丢失或严重损坏数据库系统。 + 允许修改系统表的结构以及对系统表进行某些其他风险操作。否则,即使超级用户也不允许执行这些操作。 + 不明智地使用此设置可能导致无法挽回的数据丢失或严重损坏数据库系统。 只有超级用户能更改这个设置。 @@ -7636,7 +7621,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据的时有用。这个参数在会话开始之后不能被更改。 + 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据时有用。这个参数在会话开始之后不能被更改。 @@ -7651,8 +7636,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 执行认证过程后启动新服务器进程时延迟的时间量。这是为了给开发者们一个机会在一个服务器进程上附加一个调试器。 - 如果指定值时没有单位,则以秒为单位。0值(默认值)禁用延迟。这个参数在会话开始之后不能被更改。 + 新服务器进程启动并完成认证过程之后的延迟时间。这旨在给开发者一个机会,用调试器附加到服务器进程上。 + 如果指定值时没有单位,则以秒为单位。零值(默认值)禁用延迟。这个参数在会话开始之后不能被更改。 @@ -7667,8 +7652,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 在新服务器进程分叉后,在进行认证过程之前,延迟的时间量。这是为了给开发者们一个机会在一个服务器进程上附加一个调试器来跟踪认证过程中的不当行为。 - 如果指定值时没有单位,则以秒为单位。0值(默认值)禁用延迟。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 新服务器进程刚刚派生之后、执行认证过程之前的延迟时间。这旨在给开发者一个机会,用调试器附加到服务器进程上,跟踪认证过程中的异常行为。 + 如果指定值时没有单位,则以秒为单位。零值(默认值)禁用延迟。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -7683,7 +7668,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 + 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 @@ -7718,7 +7703,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果打开,发出在排序操作中的资源使用的相关信息。只有在编译PostgreSQL时定义了TRACE_SORT宏, 这个参数才可用(不过,当前在默认情况下就定义了TRACE_SORT)。 + 如果开启,输出排序操作中的资源使用信息。只有在编译PostgreSQL时定义了TRACE_SORT宏, 这个参数才可用(不过,当前在默认情况下就定义了TRACE_SORT)。 @@ -7733,7 +7718,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。对每一种锁类型,已授权锁和等待锁的计数也会被一起转储。一个日志文件输出的示例如下: + 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。还会转储每种锁类型已授予的锁数、等待的锁数,以及它们的总数。一个日志文件输出的示例如下: LOG: LockAcquire: new: lock(0xb7acd844) id(24688,24696,0,0,0,1) grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0 @@ -7805,7 +7790,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果设置,不会跟踪小于这个 OID 的锁(用于避免在系统表上的输出)。 + 如果设置,不会跟踪 OID 小于此值的表上的锁(用于避免在系统表上的输出)。 @@ -7879,7 +7864,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,被修改的任何缓冲区的整页镜像及其WAL记录都被加入到记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 + 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,与该 WAL 记录相关的所有已修改缓冲区的整页镜像都会被添加到该记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 @@ -7922,11 +7907,11 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 在读取过程中检测到校验和失败通常会导致PostgreSQL报告错误,中止当前事务。 - 将ignore_checksum_failure设置为on会导致系统忽略失败(但仍然报告警告),并继续处理。 - 这种行为可能导致崩溃,传播或隐藏损坏,或其他严重问题。然而,它可能允许您跳过错误, - 并检索可能仍然存在于表中的未损坏的元组,如果块头仍然正常。如果头部损坏,即使启用此选项也会报告错误。 - 默认设置为off。 - 只有超级用户能更改这个设置。 + 将ignore_checksum_failure设置为 on 会使系统忽略失败(但仍报告警告),并继续处理。 + 这种行为可能导致崩溃、传播或隐藏损坏,或引发其他严重问题。 + 但是,如果块首部仍然正常,它可能允许你跳过错误,检索表中可能仍然存在的未损坏元组。 + 如果首部损坏,即使启用此选项也会报告错误。默认设置为off。 + 只有超级用户才能更改此设置。 @@ -7943,7 +7928,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 检测到损坏的页面头通常会导致PostgreSQL报告错误,中止当前事务。 将zero_damaged_pages设置为on会导致系统报告警告,将内存中的损坏页面清零,并继续处理。 - 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许您跳过错误,并从表中可能存在的未损坏页面中检索行。 + 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许你跳过错误,并从表中可能存在的未损坏页面中检索行。 如果由于硬件或软件错误而发生损坏,这对于恢复数据很有用。通常在放弃从表的损坏页面恢复数据的希望之前,不应将其设置为on。 清零的页面不会强制写入磁盘,因此建议在再次关闭此参数之前重新创建表或索引。默认设置为off。 只有超级用户能更改这个设置。 @@ -7963,9 +7948,9 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 如果设置为 off(默认值),则在恢复期间检测到引用无效页面的 WAL 记录会导致 PostgreSQL 引发 PANIC 级别错误,中止恢复。 将ignore_invalid_pages设置为on会导致系统忽略 WAL 记录中的无效页面引用(但仍报告警告),并继续恢复。 - 此行为可能会导致崩溃、数据丢失、传播或隐藏腐败,或其他严重问题。 - 但是,它可能允许你通过 PANIC 级错误,完成恢复,并启动服务器。 - 参数只能在服务器启动时设置。它仅在恢复期间或待机模式下生效。 + 此行为可能会导致崩溃、数据丢失、传播或隐藏损坏,或其他严重问题。 + 但是,它可能允许你跳过 PANIC 级错误,完成恢复,并启动服务器。 + 参数只能在服务器启动时设置。它仅在恢复期间或备库模式下生效。 @@ -7978,7 +7963,8 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果LLVM有所需要的功能,用GDB注册所生成的函数。这会让调试更加容易。默认设置是off。这个参数只能在服务器启动时设置。 + 如果 LLVM 具有所需的功能,则向GDB注册生成的函数。 + 这会让调试更加容易。默认设置为off。这个参数只能在服务器启动时设置。 @@ -7994,7 +7980,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 将生成的LLVM IR写入文件系统,位于内。 - 这仅对于在JIT实现内部工作时有用。默认设置为off。 + 这仅对开发 JIT 的内部实现有用。默认设置为off。 只有超级用户能更改这个设置。 @@ -8023,10 +8009,9 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果LLVM有所需的功能,发出需要的数据以允许perf对JIT生成的函数画像。 - 这会写出文件到$HOME/.debug/jit/中,如果需要,由用户负责对其执行清除。 - 默认设置是off。 - 这个参数只能在服务器启动时设置。 + 如果 LLVM 具有所需的功能,则输出让perf对 JIT 生成的函数进行性能分析所需的数据。 + 这会将文件写入$HOME/.debug/jit/;用户应在需要时自行清理。 + 默认设置为off。这个参数只能在服务器启动时设置。 @@ -8053,12 +8038,12 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 短选项 - 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,并且它们作为一个单字母选项存在并不表示它们会被大量使用。 + 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,它们以单字母选项的形式存在,并不一定表示鼓励频繁使用这些选项。
- 短选项键 + 短选项对照 diff --git a/zh/13/datatype.sgml b/zh/13/datatype.sgml index 8a6f3f7f..aa02122a 100644 --- a/zh/13/datatype.sgml +++ b/zh/13/datatype.sgml @@ -151,7 +151,7 @@ line - 平面上的无限长的线 + 平面上的无限直线 @@ -163,19 +163,19 @@ macaddr - MAC(Media Access Control)地址 + MAC(媒体访问控制)地址 macaddr8 - MAC(Media Access Control)地址(EUI-64格式) + MAC(媒体访问控制)地址(EUI-64格式) money - 货币数量 + 货币额 @@ -183,7 +183,7 @@ s) ] decimal [ (p, s) ] - 可选择精度的精确数字 + 可选择精度的精确数值 @@ -195,7 +195,7 @@ pg_lsn - PostgreSQL日志序列号类型 + PostgreSQL 日志序列号 @@ -273,13 +273,13 @@ tsquery - 文本搜索查询 + 文本检索查询 tsvector - 文本搜索文档 + 文本检索文档 @@ -420,14 +420,14 @@
- 数字类型常量的语法在里描述。数字类型有一整套对应的数学操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 + 数字类型常量的语法在里描述。数字类型有一整套对应的算术操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 整数类型 - 整数 + integer @@ -440,7 +440,7 @@ int4 - 整数 + integer @@ -460,11 +460,11 @@
- 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。而只有在integer的范围不够的时候才使用bigint。 + 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。bigint则设计用于integer的范围不够的情况。 - SQL只声明了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在许多其它SQL数据库系统中使用。 + SQL只规定了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在某些其他SQL数据库系统中使用。 @@ -473,11 +473,11 @@ 任意精度数值 - 数字(数据类型) + numeric(数据类型) - 任意精度数字 + 任意精度数值 @@ -489,7 +489,14 @@ 类型numeric可以存储非常多位的数字。我们特别建议将它用于货币金额和其它要求计算准确的数量。numeric值的计算在可能的情况下会得到准确的结果,例如加法、减法、乘法。不过,numeric类型上的算术运算比整数类型或者下一节描述的浮点数类型要慢很多。
- 下面使用如下术语:numeric精度是整个数中有效数字的总数,即小数点两侧的数字位数之和。numeric小数位数是小数部分中十进制数字的数量,即小数点右侧的位数。因此,数值 23.5141 的精度为 6,小数位数为 4。整数可以视为小数位数为零。 + + 我们在下文中使用以下术语: + 精度(precision)是一个numeric + 值中有效数字的总位数,也就是小数点两侧数字的总数。 + 小数位数(scale)是小数部分中位于小数点 + 右侧的十进制位数。因此,数值 23.5141 的精度为 6,小数位数为 4。 + 整数可以认为其小数位数为 0。 + 可以配置numeric列的最大精度和最大小数位数。要声明numeric类型的列,使用以下语法: NUMERIC(precision, scale) @@ -519,12 +526,12 @@ NUMERIC NaN - 非数字 + 非数 - 非数字 - 数字(数据类型) + 非数 + numeric(数据类型) 除了普通数值外,numeric类型还允许特殊值NaN,表示非数。对NaN的任何运算都会产生另一个NaN。在 SQL 命令中将该值写为常量时,必须加上引号,例如UPDATE table SET x = 'NaN'。输入时,字符串NaN的识别不区分大小写。 @@ -578,7 +585,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 双精度 + double precision @@ -588,7 +595,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; float8 - 双精度 + double precision @@ -641,8 +648,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; 默认情况下,浮点值会以最短且精确的十进制表示形式输出; - 生成的十进制值比同一二进制精度下任何其他可表示值都更接近真实 - 存储的二进制值。(不过,为了避免输入例程普遍存在的一个错误, + 所生成的十进制值与实际存储的二进制值之间的距离,小于它与任何其他可用相同二进制精度表示的值之间的距离。(不过,为了避免输入例程普遍存在的一个错误, 即未能正确遵守舍入到最近偶数规则,当前输出值绝不会 恰好位于两个可表示值的正中间。) 对于float8值,最多使用 17 位有效十进制数字; @@ -651,14 +657,14 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 生成这种最短且精确的输出格式,比历史上的圆整格式要快得多。 + 生成这种最短且精确的输出格式,比历史上的舍入格式要快得多。 为了兼容旧版本PostgreSQL生成的输出, 并允许降低输出精度,可以使用 - 参数改为选择圆整后的 + 参数改为选择舍入后的 十进制输出。将该参数设置为 0 会恢复之前的默认行为,也就是把值 舍入为 6 位(对于float4)或 15 位 (对于float8)有效十进制数字。设置为负值会 @@ -672,14 +678,14 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 过去那些需要精确值的应用,往往必须把 + 过去那些需要精确值的应用,必须把 设置为 3 才能获得它们。 为了在版本之间获得最大兼容性,这类应用应继续这样做。 - 非数字 + 非数 double precision @@ -687,7 +693,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; Infinity -Infinity NaN -它们分别表示 IEEE 754 的特殊值无穷大负无穷大非数字。在 SQL 命令中将这些值写为常量时,必须加上引号,例如UPDATE table SET x = '-Infinity'。输入时,这些字符串的识别不区分大小写。 +它们分别表示 IEEE 754 的特殊值无穷大负无穷大非数。在 SQL 命令中将这些值写为常量时,必须加上引号,例如UPDATE table SET x = '-Infinity'。输入时,这些字符串的识别不区分大小写。 @@ -743,13 +749,13 @@ FROM generate_series(-3.5, 3.5, 1) as x; - auto-increment + 自动递增 serial - sequence - and serial type + 序列 + 与 serial 类型 @@ -878,7 +884,7 @@ ALTER SEQUENCE tablename_ SELECT '12.34'::float8::numeric::money; - 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有圆整错误。 + 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有舍入误差。 @@ -890,7 +896,7 @@ SELECT '52093.89'::money::numeric::float8; 一个 money 值除以一个整数值时,会朝零方向截去小数 - 部分。要得到圆整结果,可以除以一个浮点值,或者在除法前先把 + 部分。要得到舍入后的结果,可以除以一个浮点值,或者在除法前先把 money 转换为 numeric,再在除法后转换回 money(如果要避免精度丢失风险,后一种做法更好)。 当一个 money 值被另一个 money 值除时, @@ -909,12 +915,12 @@ SELECT '52093.89'::money::numeric::float8; - string + 字符串 - 字符 + character @@ -949,7 +955,7 @@ SELECT '52093.89'::money::numeric::float8; character(n), char(n) - 定长,空白填充 + 定长,空格填充 text @@ -1021,7 +1027,7 @@ SELECT '52093.89'::money::numeric::float8; - 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储代码为零的字符(有时称为NUL)。有关更多信息,请参阅。 + 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储编码值为零的字符(有时称为NUL)。有关更多信息,请参阅 @@ -1040,7 +1046,7 @@ SELECT '52093.89'::money::numeric::float8; - 这三种类型之间没有性能差别,除了使用空白填充类型时会占用更多存储 + 这三种类型之间没有性能差别,除了使用空格填充类型时会占用更多存储 空间,以及在写入带长度约束的列时需要少量额外 CPU 周期来检查长度。 虽然在某些其他数据库系统中,character(n) 可能有一定性能优势,但在 PostgreSQL @@ -1075,7 +1081,7 @@ INSERT INTO test2 VALUES ('ok'); INSERT INTO test2 VALUES ('good '); INSERT INTO test2 VALUES ('too long'); ERROR: value too long for type character varying(5) -INSERT INTO test2 VALUES ('too long'::varchar(5)); -- explicit truncation +INSERT INTO test2 VALUES ('too long'::varchar(5)); -- 显式截断 SELECT b, char_length(b) FROM test2; b | char_length @@ -1197,13 +1203,15 @@ SELECT b, char_length(b) FROM test2; 开头(以便与转义格式区分)。在某些上下文中,这个开头的反斜线 可能需要通过双写进行转义(见 )。作为输入时,十六进制数字 - 可以使用大写或小写,并且在两个数字组成的一组之间允许出现空白 + 可以使用大写或小写,并且每两个数字组成一组,组与组之间允许出现空白 (但组内以及起始的 \x 序列中不能有空白)。 十六进制格式与大量外部应用和协议兼容,并且通常比转义格式转换得 更快,因此更推荐使用。 - 例如: + + 示例: + SET bytea_output = 'hex'; SELECT '\xDEADBEEF'::bytea; @@ -1259,7 +1267,7 @@ SELECT '\xDEADBEEF'::bytea; 0 - 0字节 + 零值字节 '\000' '\000'::bytea \x00 @@ -1316,15 +1324,24 @@ SELECT '\xDEADBEEF'::bytea; - Bytea字节默认以hex格式输出。如果把改为escape, - 不可打印字节会被转换为等价的三位八进制值,并在前面加一个反斜线。大多数可打印字节以客户端字符集中相应的标准表示输出,例如: + 默认情况下,bytea 字节会以 hex + 格式输出。如果把 改为 + escape不可打印字节会被转换成 + 等价的三位八进制值,并在前面加一个反斜线。大多数 + 可打印字节则会按其在客户端字符集中的标准表示输出, + 例如: + + SET bytea_output = 'escape'; SELECT 'abc \153\154\155 \052\251\124'::bytea; bytea ---------------- abc klm *\251T -十进制值为 92 的字节(反斜线)在输出中会被双写。详情见。 + + + 十进制值 92(反斜线)的字节在输出中会被双写。详情见 + @@ -1395,10 +1412,10 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; time - 不带时区的时间 + time without time zone - 带时区的时间 + time with time zone timestamp @@ -1407,13 +1424,13 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; timestamptz - 带时区的时间戳 + timestamp with time zone - 不带时区的时间戳 + timestamp without time zone - 间隔 + interval 时间跨度 @@ -1497,7 +1514,7 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; - SQL 要求仅写 timestamp 时,应等效于 + SQL 标准要求仅写 timestamp 时,应等效于 timestamp without time zone,而 PostgreSQL 也遵循这种行为。 timestamptz 被接受为 @@ -1578,11 +1595,11 @@ MINUTE TO SECOND 其中 p 是可选的精度说明,给出秒字段中 保留的小数位数。精度可用于 timetimestampinterval 类型, - 范围是 0 到 6。这与前文描述的取值一致。如果在常量声明中没有指定 + 范围是 0 到 6。如果在常量声明中没有指定 精度,则默认采用该字面值本身的精度(但不超过 6 位)。 - + 日期 @@ -1607,7 +1624,7 @@ MINUTE TO SECOND 1999-01-08 - ISO 8601; 任何模式下的1月8日 + ISO 8601; 任何模式下的1月8日 (推荐格式) @@ -1643,27 +1660,27 @@ MINUTE TO SECOND 99-Jan-08 - YMD模式中的1月8日,否则错误 + YMD模式中的1月8日,否则报错 08-Jan-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 Jan-08-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 19990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 1999.008 - 年和一年中的日子 + 年和一年中的第几天 J2451187 @@ -1678,17 +1695,17 @@ MINUTE TO SECOND
- + 时间 time - 无时区的时间 + time without time zone - 带时区的时间 + time with time zone @@ -1767,11 +1784,11 @@ MINUTE TO SECOND 040506+0730 - ISO 8601,以分数小时形式给出 UTC 偏移 + ISO 8601,时区的 UTC 偏移不是整小时 040506+07:30:00 - UTC偏移量指定为秒(ISO 8601中不允许) + UTC 偏移精确到秒(ISO 8601中不允许) 04:05:06 PST @@ -1840,7 +1857,7 @@ MINUTE TO SECOND - + 时间戳 @@ -1848,20 +1865,34 @@ MINUTE TO SECOND - 带时区的时间戳 + timestamp with time zone - 无时区的时间戳 + timestamp without time zone - 时间戳类型的有效输入由日期与时间拼接而成,其后可以跟时区,再后可以跟ADBC。(或者,AD/BC可以出现在时区之前,但这不是首选顺序。)因此: + + 时间戳类型的有效输入由一个日期和时间的串接组成,后面跟着一个可选 + 时区,以及一个可选的 ADBC + (另外,AD/BC 也可以出现在 + 时区前面,但这种顺序并不推荐)。因此: + + 1999-01-08 04:05:06 -以及: + + 和: + 1999-01-08 04:05:06 -8:00 -都是有效值,遵循ISO8601 标准。此外,也支持下面这种常用格式: + + + 都是遵循 ISO 8601 标准的有效值。另外,广泛使用 + 的下列格式: + January 8 04:05:06 1999 PST - + + 也被支持。 + 按照SQL标准,timestamp without time zonetimestamp with time zone字面量的区别在于,时间后是否有+-符号及其后的时区偏移。因此,按照该标准, TIMESTAMP '2004-10-19 10:23:54' @@ -1913,12 +1944,12 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' time - constants + 常量 date - constants + 常量 @@ -2019,13 +2050,13 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' date 输出格式 - formatting + 格式化 time 输出格式 - formatting + 格式化 @@ -2058,7 +2089,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' ISO - ISO 8601, SQL标准 + ISO 8601,SQL 标准 1997-12-17 07:37:16-08 @@ -2089,7 +2120,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' - SQL和POSTGRES风格中,如果DMY域顺序被指定,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。 + SQL和POSTGRES风格中,如果指定了 DMY 字段顺序,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。 @@ -2155,7 +2186,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 时区 - time zone + 时区 @@ -2210,7 +2241,8 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' - PostgreSQL允许使用三种不同形式指定时区: + PostgreSQL 允许使用三种不同形式来指定时区: + 完整时区名称,例如 America/New_York。 @@ -2239,11 +2271,20 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 除了时区名称和缩写之外, PostgreSQL 还接受 POSIX 风格的 时区说明,见 。 - 这个选项通常不如使用具名时区更合适,但如果没有可用的 IANA - 时区条目,它可能就是必需的。 + 这个选项通常不如使用具名时区更合适,但如果没有合适的 IANA 时区条目可用,它可能就是必需的。 - 简而言之,缩写和完整名称的区别是:缩写表示特定的 UTC 偏移,而许多完整名称隐含本地夏令时规则,因此有两个可能的 UTC 偏移。例如,2014-06-04 12:00 America/New_York表示纽约当地时间的中午,在该日期使用的是东部夏令时间(UTC-4)。因此,2014-06-04 12:00 EDT指定相同的时刻。但是,2014-06-04 12:00 EST指定东部标准时间(UTC-5)的中午,而不管该日期是否名义上实行夏令时。 + + + 简而言之,这就是缩写和全名的区别:缩写表示某个特定的 UTC 偏移, + 而很多完整名称隐含了当地的夏令时规则,因此可能对应两个不同的 + UTC 偏移。例如, + 2014-06-04 12:00 America/New_York 表示纽约 + 当地时间中午;在这个具体日期,它属于东部夏令时(UTC-4),所以 + 2014-06-04 12:00 EDT 指定的是同一个时刻。 + 但 2014-06-04 12:00 EST 指定的是东部标准时 + 中午(UTC-5),无论当天名义上是否正在实行夏令时。 + 更复杂的是,一些司法辖区在不同时间使用同一时区缩写来表示不同的 @@ -2254,12 +2295,17 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 当地民用时间。 - 在所有情况下,时区名称和缩写的识别都不区分大小写。(这与 8.2 之前的PostgreSQL版本不同;那些版本在某些上下文中区分大小写,在另一些上下文中则不区分。) + + 无论哪种形式,时区名称及其缩写都不区分大小写。(这是对 + PostgreSQL 8.2 之前版本的一项改动; + 在那些版本中,时区名在某些环境下区分大小写,而在另一些环境下则 + 不区分。) + 时区名称和缩写并不是硬编码在服务器中的;它们来自安装目录下 .../share/timezone/ 和 - .../share/timezonesets/ 子目录中的数据 + .../share/timezonesets/ 子目录中的配置文件 (见 )。 @@ -2297,13 +2343,13 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' - interval值可以使用下列语法书写: + interval值可以使用下列详细语法书写: @ quantity unit quantity unit... direction - 其中quantity是一个数字(很可能是有符号的); + 其中quantity是一个数字(可以带有符号); unitmicrosecondmillisecondsecondminutehourday、 @@ -2337,7 +2383,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' P quantity unit quantity unit ... T quantity unit ... 字符串必须以 P 开头,并且可以包含一个 - T 来引出一天中时间单位。可用的单位缩写见 + T 来引出一天中的时间单位。可用的单位缩写见 。单位可以省略, 也可以按任意顺序出现,但小于一天的单位必须出现在 T 之后。特别是,M 的含义 @@ -2376,7 +2422,7 @@ P quantity unit M - 分钟 (在时间部分中) + 分钟(在时间部分中) S @@ -2444,7 +2490,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; '1.5 weeks''01:02:03.45'。然而,由于 interval 在内部只存储整数字段,小数值必须转换成更小 - 的单位。大于月的单位的小数部分会被舍入为整数个月,例如 + 的单位。大于月的单位的小数部分会被截断为整数个月,例如 '1.5 years' 会变成 '1 year 6 mons'。周和天的小数部分会在假定 每月 30 天、每天 24 小时的前提下,计算成整数天和微秒,例如 @@ -2481,7 +2527,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; P1Y2M3DT4H5M6S - 带标志符的ISO 8601 格式:含义同上 + ISO 8601 带标志符的格式:含义同上 P0001-02-03T04:05:06 @@ -2499,7 +2545,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; interval 输出格式 - formatting + 格式化 @@ -2548,7 +2594,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; iso_8601 风格的输出符合 ISO 8601 标准 - 4.4.3.2 节描述的带标志符格式。 + 4.4.3.2 节描述的带标志符的格式
@@ -2599,7 +2645,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; 布尔类型 - Boolean + 布尔 数据类型 @@ -2710,15 +2756,15 @@ SELECT * FROM test1 WHERE a; 数据类型 - enumerated (enum) + 枚举(enum) - enumerated types + 枚举类型 - 枚举(enum)类型是由一个静态、值的有序集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的日期,或者一个数据的状态值集合。 + 枚举(enum)类型是由一个静态的有序值集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的各天,或者一个数据的状态值集合。 @@ -2827,7 +2873,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 实现细节 - 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空格也是有意义的。 + 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空白也是有意义的。 @@ -2839,7 +2885,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 从内部枚举值到文本标签的翻译被保存在系统目录pg_enum中。可以直接查询该目录。 + 从内部枚举值到文本标签的转换关系被保存在系统目录pg_enum中。直接查询该目录可能会有所帮助。 @@ -2914,7 +2960,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays circle24字节 - <(x,y),r>(中心点和半径) + <(x,y),r>(圆心和半径) @@ -2927,7 +2973,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 我们提供了丰富的函数和操作符来进行各种几何操作,例如缩放、平移、 - 旋转以及计算相交等,详见 。 + 旋转以及求交等,详见 @@ -2938,7 +2984,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 点是几何类型的基本二维构造块。用下面的语法描述point类型的值: + 点是几何类型的基本二维构造块。用下面任一种语法描述point类型的值: ( x , y ) @@ -2954,14 +3000,14 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线 + 直线 line - 线由线性方程Ax + By + C = 0 + 直线由线性方程Ax + By + C = 0 表示,其中AB不能同时为零。类型line 的值采用以下形式输入和输出: @@ -2981,7 +3027,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays (x1,y1)(x2,y2) - 是线上不同的两点。 + 是直线上不同的两点。 @@ -2997,7 +3043,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线段用一对线段的端点来表示。lseg类型的值用下面的语法声明: + 线段用一对线段的端点来表示。lseg类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ( x2 , y2 ) ] @@ -3021,15 +3067,15 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 方框 - box (data type) + box(数据类型) - rectangle + 矩形 - 方框用其对角的点对表示。box类型的值使用下面的语法指定: + 方框用其对角的点对表示。box类型的值使用下面任一种语法指定: ( ( x1 , y1 ) , ( x2 , y2 ) ) @@ -3048,7 +3094,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 在输入时可以提供任意两个对角,但是值将根据需要被按顺序记录为右上角和左下角。 + 在输入时可以提供任意两个对角,但是值将根据需要被重新排列,并依次存储为右上角和左下角。 @@ -3056,7 +3102,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 路径 - path (data type) + path(数据类型) @@ -3064,7 +3110,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - path类型的值用下面的语法声明: + path类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ... , ( xn , yn ) ] @@ -3074,11 +3120,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays x1 , y1 , ... , xn , yn - 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被忽略时,路径将被假定为封闭。 + 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被省略时,路径将被假定为封闭。 - 路径的输出使用第一种或第二种语法。 + 路径的输出视情况使用第一种或第二种语法。 @@ -3102,7 +3148,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - polygon类型的值用下列语法声明: + polygon类型的值用下列任一种语法指定: ( ( x1 , y1 ) , ... , ( xn , yn ) ) @@ -3127,7 +3173,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 圆由一个圆心和一个半径代表。circle类型的值用下面的语法指定: + 圆由一个圆心和一个半径代表。circle类型的值用下面任一种语法指定: < ( x , y ) , r > @@ -3150,7 +3196,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 网络地址类型 - network + 网络 数据类型 @@ -3207,8 +3253,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 在对 inetcidr 数据类型排序时,IPv4 - 地址总是排在 IPv6 地址之前,包括那些封装在 IPv6 地址中或映射到 - IPv6 地址中的 IPv4 地址,例如 ::10.2.3.4 或 + 地址总是排在 IPv6 地址之前,即使后者是封装或映射 IPv4 地址所得的 IPv6 地址,例如 ::10.2.3.4 或 ::ffff:10.4.3.2。 @@ -3364,7 +3409,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - <type>inet</type> vs. <type>cidr</type> + <type>inet</type> 与 <type>cidr</type> inetcidr 两种数据类型的本质区别在于: @@ -3390,12 +3435,12 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - MAC地址 + MAC 地址 macaddr - macaddr类型存储 MAC 地址,也就是以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: + macaddr类型存储 MAC 地址,例如以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: '08:00:2b:01:02:03' @@ -3429,11 +3474,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays <type>macaddr8</type> - macaddr8 (data type) + macaddr8(数据类型) - MAC地址(EUI-64格式) + MAC 地址(EUI-64 格式) macaddr @@ -3475,7 +3520,12 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 上述的后六种输入格式不属于任何标准。 - 要将传统 EUI-48 格式的 48 位 MAC 地址转换为修改后的 EUI-64 格式,以用作 IPv6 地址的主机部分,可以使用macaddr8_set7bit,如下所示: + + 要将 EUI-48 格式的传统 48 位 MAC 地址转换为修改后的 EUI-64 格式, + 以便作为 IPv6 地址的主机部分,可使用 + macaddr8_set7bit,如下所示: + + SELECT macaddr8_set7bit('08:00:2b:01:02:03'); macaddr8_set7bit @@ -3499,7 +3549,13 @@ SELECT macaddr8_set7bit('08:00:2b:01:02:03'); 数据类型 - 位串是由 1 和 0 组成的字符串,可用于存储或可视化位掩码。SQL 有两种位类型:bit(n)bit varying(n),其中n是正整数。 + + 位串是由 1 和 0 组成的字符串。它们可用于存储或展示位掩码。 + SQL 中有两种位类型: + bit(n) 和 + bit varying(n),其中 + n 是正整数。 + bit 类型的数据长度必须与 @@ -3549,31 +3605,31 @@ SELECT * FROM test; - 一个 bit 串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 + 一个位串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 开销,具体取决于串的长度。(不过,长值可能会被压缩或移到行外存储, 与 中对字符串的说明相同。) - 文本搜索类型 + 文本检索类型 - 全文搜索 + 全文检索 数据类型 - 文本搜索 + 文本检索 数据类型 - PostgreSQL 提供了两种专为支持全文搜索而 - 设计的数据类型。所谓全文搜索,是指在一组自然语言 + PostgreSQL 提供了两种专为支持全文检索而 + 设计的数据类型。所谓全文检索,是指在一组自然语言 文档中查找最匹配某个 查询的文档。tsvector 类型以 - 适合文本搜索的优化形式表示文档,tsquery 类型则表示 + 适合文本检索的优化形式表示文档,tsquery 类型则表示 文本查询。关于这一功能的详细解释见 ; 相关函数和操作符的概览见 @@ -3585,40 +3641,74 @@ SELECT * FROM test; tsvector(数据类型) - 一个tsvector值是由互不相同的词位组成的有序列表。词位是经过规范化以合并同一个词的不同变体的词(详情见)。排序和去重会在输入时自动完成,如本例所示: + + tsvector 值是一个排好序且互不重复的 + 词位(lexeme)列表,这些词已经过 + 正规化,以便把同一单词的不同变体合并起来 + (详见 )。排序和去重会在输入时自动 + 完成,如下例所示: + + SELECT 'a fat cat sat on a mat and ate a fat rat'::tsvector; tsvector ---------------------------------------------------- 'a' 'and' 'ate' 'cat' 'fat' 'mat' 'on' 'rat' 'sat' -要表示包含空白或标点符号的词位,请用引号括住它们: + + + 若要表示包含空白或标点的词位,请用引号将它们括起来: + + SELECT $$the lexeme ' ' contains spaces$$::tsvector; tsvector ------------------------------------------- ' ' 'contains' 'lexeme' 'spaces' 'the' -(本例和下一个示例使用美元符号引用的字符串字面量,以免在字面量中双写引号造成混淆。)内嵌的引号和反斜线必须双写: + + + (本例及下例使用美元引用的字符串常量,以避免在字符串内部必须 + 双写引号所造成的混淆。)嵌入的引号和反斜线必须双写: + + SELECT $$the lexeme 'Joe''s' contains a quote$$::tsvector; tsvector ------------------------------------------------ 'Joe''s' 'a' 'contains' 'lexeme' 'quote' 'the' -还可以给词位附加整数形式的位置,如下所示: + + + 还可以为词位附加整数形式的 位置: + + SELECT 'a:1 fat:2 cat:3 sat:4 on:5 a:6 mat:7 and:8 ate:9 a:10 fat:11 rat:12'::tsvector; tsvector -------------------------------------------------------------------&zwsp;------------ 'a':1,6,10 'and':8 'ate':9 'cat':3 'fat':2,11 'mat':7 'on':5 'rat':12 'sat':4 -位置通常表示原词在文档中的位置。位置信息可用于邻近度排序。位置值的范围为 1 到 16383;更大的数值会被静默设为 16383。同一词位的重复位置会被丢弃。 + + + 一个位置通常表示源词在文档中的位置。位置信息可用于 + 邻近度排序。位置值可以位于 1 到 16383 + 之间;更大的数字会被静默设为 16383。同一词位的重复位置会被丢弃。 + + + + 带有位置的词位还可以进一步附加一个 + 权重标签,其值可以是 + ABC + 或 DD 是默认值,因此在 + 输出中不会显示: - 具有位置的词位还可以标记一个权重,它可以是A, - BCD。 - D是默认值,因此不会在输出中显示: + SELECT 'a:1A fat:2B,4C cat:5D'::tsvector; tsvector ---------------------------- 'a':1A 'cat':5 'fat':2B,4C -权重通常用来反映文档结构,例如为标题中的词和正文中的词采用不同标记。文本搜索排名函数可以为不同的权重标记分配不同优先级。 + + + 权重通常用于反映文档结构,例如把标题中的词和正文中的词区分开来。 + 文本检索排序函数可以为不同的权重标记分配不同优先级。 + 必须认识到,tsvector 类型本身并不会执行任何词语 - 规范化;它假定输入的词已经按照应用需求完成规范化。例如: + 正规化;它假定输入的词已经按照应用需求完成正规化。例如: SELECT 'The Fat Rats'::tsvector; @@ -3627,9 +3717,9 @@ SELECT 'The Fat Rats'::tsvector; 'Fat' 'Rats' 'The' - 对于大多数英文全文搜索应用来说,上述词会被视为尚未规范化,但 + 对于大多数英文全文检索应用来说,上述词会被视为尚未正规化,但 tsvector 并不在意。原始文档文本通常应先经过 - to_tsvector,以按搜索需要对词语进行规范化: + to_tsvector,以按检索需要对词语进行正规化: SELECT to_tsvector('english', 'The Fat Rats'); @@ -3718,9 +3808,9 @@ SELECT 'super:*'::tsquery; 引号的使用规则与前面介绍 tsvector 时相同;同样, - 与 tsvector 一样,任何需要的词语规范化都必须在 + 与 tsvector 一样,任何需要的词语正规化都必须在 转换为 tsquery 类型之前完成。to_tsquery - 函数很适合用来实现这种规范化: + 函数很适合用来实现这种正规化: SELECT to_tsquery('Fat:ab & Cats'); @@ -3746,8 +3836,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); ---------------+------------ 'postgradu':1 | 'postgr':* - 因而它能够匹配其带前缀的后继形式 - postgraduate。 + 因而它能够匹配postgraduate 词干化后的形式。 @@ -3765,7 +3854,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); uuid 数据类型用于存储由 RFC 4122、 ISO/IEC 9834-8:2005 及相关标准定义的通用唯一标识符(UUID)。 - (有些系统把这种数据类型称为全局唯一标识符,或 GUID, + (有些系统把这种数据类型称为全局唯一标识符,或 GUID GUID。)这种标识符是一个 128 位的量,由某种算法生成,该算法被设计为使同一算法在已知宇宙中 被其他人生成出相同标识符的概率极低。因此,对于分布式系统而言, @@ -3782,7 +3871,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11 PostgreSQL 也接受其他输入形式:可以使用 - 大写字母、用花括号包围标准格式、忽略部分或全部连字符,或者在任意 + 大写字母、用花括号包围标准格式、省略部分或全部连字符,或者在任意 4 位分组后额外加上连字符。例如: A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11 @@ -3833,16 +3922,25 @@ a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11 创建XML值 - 要生成xml类型的值,可以对字符数据使用函数xmlparsexmlparse + + 要从字符数据生成 xml 类型的值,可以使用函数 + xmlparsexmlparse XMLPARSE ( { DOCUMENT | CONTENT } value) -例如: + 示例: +Manual...') XMLPARSE (CONTENT 'abcbarfoo') -]]>按照 SQL 标准,这是将字符串转换为 XML 值的唯一方式,不过也可以使用以下 PostgreSQL 特有语法: + 按照 SQL 标准,这是把字符串转换为 XML 值的 + 唯一方法;但 PostgreSQL 特有的下列语法: +bar' 'bar'::xml -]]> +]]> + 也可以使用。 + 即使输入值指定了文档类型声明(DTD),xml 类型也不会 @@ -3851,18 +3949,25 @@ xml 'bar' 来执行验证。 - 相反的操作是把xml值转换为字符串,这使用函数xmlserializexmlserialize + + 反向操作,也就是从 xml 生成字符串值,则使用函数 + xmlserializexmlserialize XMLSERIALIZE ( { DOCUMENT | CONTENT } value AS type ) - type可以是charactercharacter varyingtext(或这些类型之一的别名)。同样,按照 SQL 标准,这是在xml类型和字符类型之间转换的唯一方式,不过 PostgreSQL 也允许直接对值进行类型转换。 + type 可以是 + charactercharacter varying 或 + text(或它们的别名)。同样,根据 SQL 标准,这是在 + xml 与字符类型之间进行转换的唯一方式,但 + PostgreSQL 也允许你直接进行类型转换。 + 当字符串值在不经过 XMLPARSEXMLSERIALIZE 的情况下与 xml 类型互相转换时, 选择 DOCUMENT 还是 CONTENT - 由会话配置参数 XML option - XML option 决定,可以使用 + 由会话配置参数 XML 选项 + XML 选项 决定,可以使用 标准命令设置: SET XML OPTION { DOCUMENT | CONTENT }; @@ -3926,7 +4031,7 @@ SET xmloption TO { DOCUMENT | CONTENT }; xml 数据类型有些特殊,因为它不提供任何比较操作符。 这是因为对 XML 数据并不存在良定义且通用的比较算法。其结果是, - 你无法通过把某个 xml 值与搜索值比较来检索行。 + 你无法通过把某个 xml 列与搜索值比较来检索行。 因此,XML 值通常应伴随一个独立的键字段,例如 ID。另一种比较 XML 值的办法,是先把它们转换成字符串;但请注意,字符串比较对 XML 的比较需求通常帮助不大。 @@ -3934,14 +4039,14 @@ SET xmloption TO { DOCUMENT | CONTENT }; 由于 xml 数据类型没有可用的比较操作符,因此无法直接 - 在这种类型上创建索引。如果需要在 XML 中快速搜索,可行方案包括: + 在这种类型的列上创建索引。如果需要在 XML 中快速搜索,可行方案包括: 将表达式转换为字符串类型后为其建立索引,或者为某个 XPath 表达式 建立索引。当然,实际查询也必须相应调整为使用该被索引的表达式。 - PostgreSQL 的文本搜索功能也可用于加速 - XML 数据的全文搜索。不过,目前 PostgreSQL 发行版中仍缺少所需的 + PostgreSQL 的文本检索功能也可用于加速 + XML 数据的全文检索。不过,目前 PostgreSQL 发行版中仍缺少所需的 预处理支持。 @@ -3959,12 +4064,12 @@ SET xmloption TO { DOCUMENT | CONTENT }; 域类型 - domain + - data type - domain + 数据类型 + @@ -3976,13 +4081,13 @@ SET xmloption TO { DOCUMENT | CONTENT }; CREATE DOMAIN posint AS integer CHECK (VALUE > 0); CREATE TABLE mytable (id posint); -INSERT INTO mytable VALUES(1); -- works -INSERT INTO mytable VALUES(-1); -- fails +INSERT INTO mytable VALUES(1); -- 成功 +INSERT INTO mytable VALUES(-1); -- 失败 - 当底层类型的一个操作符或函数适用于一个域值时,域会被自动向下转换为底层类型。因此,mytable.id - 1的结果会被认为是类型integer而不是posint。我们可以写成(mytable.id - 1)::posint来把结果转换回posint,这会导致域的约束被重新检查。在这种情况下,如果该表达式被应用于一个值为1的id就会错误。把底层类型的值赋给域类型的一个字段或者变量不需要写显式的类型转换,但是域的约束将会被检查。 + 当底层类型的一个操作符或函数被应用于一个域值时,域会被自动向下转换为底层类型。因此,mytable.id - 1的结果会被认为是类型integer而不是posint。我们可以写成(mytable.id - 1)::posint来把结果转换回posint,这会导致域的约束被重新检查。在这种情况下,如果该表达式被应用于一个值为1的id就会报错。把底层类型的值赋给域类型的一个字段或者变量不需要写显式的类型转换,但是域的约束将会被检查。 @@ -4065,7 +4170,7 @@ INSERT INTO mytable VALUES(-1); -- fails 对象标识符(OID)在 PostgreSQL 内部被用作 若干系统表的主键。类型 oid 表示一个对象标识符。 - 此外还有若干 oid 的别名类型,统称为 + 此外还有若干 oid 的别名类型,其名称均形如 regsomething 给出了概要说明。 @@ -4142,14 +4247,14 @@ SELECT * FROM pg_attribute regconfig pg_ts_config - 文本搜索配置 + 文本检索配置 english regdictionary pg_ts_dict - 文本搜索字典 + 文本检索词典 simple @@ -4185,7 +4290,7 @@ SELECT * FROM pg_attribute regprocedure pg_proc - 函数与参数类型 + 带参数类型的函数 sum(int4) @@ -4206,7 +4311,7 @@ SELECT * FROM pg_attribute
- 对于按名字空间分组的对象,所有 OID 别名类型都接受模式限定名称;如果不加限定就无法在当前搜索路径中找到对象,输出时也会显示模式限定名称。regprocregoper别名类型只接受唯一的(未重载的)输入名称,因此用途有限;对于大多数用途,regprocedureregoperator更合适。对于regoperator,通过将未使用的操作数写为NONE来标识一元操作符。 + 对于按命名空间分组的对象,所有 OID 别名类型都接受模式限定名称;如果不加限定就无法在当前搜索路径中找到对象,输出时也会显示模式限定名称。regprocregoper别名类型只接受唯一的(未重载的)输入名称,因此用途有限;对于大多数用途,regprocedureregoperator更合适。对于regoperator,通过将未使用的操作数写为NONE来标识一元操作符。 大多数 OID 别名类型还有一个附加特性,就是会创建依赖关系。如果 @@ -4214,9 +4319,8 @@ SELECT * FROM pg_attribute 它就会对被引用对象建立依赖。例如,如果某列的默认表达式是 nextval('my_seq'::regclass)PostgreSQL 就会知道该默认表达式依赖于 - 序列 my_seq,因此系统在删除该序列之前,必须先 - 移除该默认表达式。 - (regrole 是这一特性的例外:该类型的常量不允许出现在 + 序列 my_seq,因此系统不允许在尚未移除该默认表达式时删除序列。 + (regrole 是这一特性的唯一例外:该类型的常量不允许出现在 存储表达式中。) @@ -4404,7 +4508,7 @@ SELECT * FROM pg_attribute anyarray - 表示一个函数可以接受任意数组数据类型(参见 + 表示一个函数可以接受任意数组数据类型(参见)。 @@ -4489,12 +4593,12 @@ SELECT * FROM pg_attribute trigger - 触发器函数被声明为返回trigger. + 表示触发器函数被声明为返回 trigger event_trigger - 事件触发器函数被声明为返回event_trigger. + 表示事件触发器函数被声明为返回 event_trigger @@ -4509,7 +4613,7 @@ SELECT * FROM pg_attribute unknown - 标识一种尚未解析出的类型,例如未修饰的字符串字面值。 + 标识一种尚未解析出的类型,例如未修饰的字符串字面值的类型。 @@ -4527,7 +4631,7 @@ SELECT * FROM pg_attribute voidrecord 用作结果类型 (如果函数被用作触发器或事件触发器,则也允许 triggerevent_trigger 作为结果类型)。 - 有些语言还支持借助多态伪类型来实现多态函数;详见 + 有些语言还支持借助上面列出的多态伪类型来实现多态函数;详见
diff --git a/zh/13/dict-int.sgml b/zh/13/dict-int.sgml index 7fa5c3c3..d2e76764 100644 --- a/zh/13/dict-int.sgml +++ b/zh/13/dict-int.sgml @@ -1,16 +1,16 @@ - dict_int — 用于整数的示例全文搜索词典 + dict_int — 用于整数的示例全文检索词典 dict_int - dict_int是一个全文搜索附加词典模板的示例。 + dict_int是一个全文检索附加词典模板的示例。 引入这个示例词典是为了控制整数(有符号和无符号)的索引, - 使这类数字能够被索引,同时又避免唯一词的数量过度增长, + 使这类数字能够被索引,同时又避免不同词的数量过度增长, 因为那会严重影响搜索性能。 @@ -54,7 +54,7 @@ 用法 - 安装dict_int扩展后,会创建一个文本搜索模板 + 安装dict_int扩展后,会创建一个文本检索模板 intdict_template以及一个基于该模板、使用默认参数的词典 intdict。你可以修改这些参数,例如: @@ -77,7 +77,7 @@ mydb# select ts_lexize('intdict', '12345678');
但在实际使用中,通常需要像所述那样, - 将它包含到某个文本搜索配置中。可能类似如下: + 将它包含到某个文本检索配置中。可能类似如下: ALTER TEXT SEARCH CONFIGURATION english diff --git a/zh/13/func.sgml b/zh/13/func.sgml index b21aa80f..c4ad2c86 100644 --- a/zh/13/func.sgml +++ b/zh/13/func.sgml @@ -10589,7 +10589,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 文本搜索函数和操作符 + 文本检索函数和操作符 全文检索 @@ -10597,7 +10597,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 文本搜索 + 文本检索 函数和操作符 @@ -10605,11 +10605,11 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple 以及 - 总结了为全文检索提供的函数和操作符。PostgreSQL的文本搜索功能的详细解释可参考。 + 总结了为全文检索提供的函数和操作符。PostgreSQL的文本检索功能的详细解释可参考
- 文本搜索操作符 + 文本检索操作符 @@ -10784,11 +10784,11 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple 除了这些专用操作符之外, 中所示的常用比较操作符也适用于tsvectortsquery类型。 - 这些操作符对文本搜索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。 + 这些操作符对文本检索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。
- 文本搜索函数 + 文本检索函数 @@ -10830,7 +10830,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple regconfig - 返回当前默认文本搜索配置的OID(由 所设定的). + 返回当前默认文本检索配置的 OID(由 设置)。 get_current_ts_config() @@ -11361,17 +11361,17 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 所有接受一个可选的regconfig参数的文本搜索函数在省略该参数时,会使用由指定的配置。 + 所有接受一个可选的regconfig参数的文本检索函数在省略该参数时,会使用由指定的配置。 - 中的函数被单独列出,因为它们通常不被用于日常的文本搜索操作。 - 它们主要有助于开发和调试新的文本搜索配置。 + 中的函数被单独列出,因为它们通常不被用于日常的文本检索操作。 + 它们主要有助于开发和调试新的文本检索配置。
- 文本搜索调试函数 + 文本检索调试函数 @@ -11406,7 +11406,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple lexemestext[] ) - 根据指定的或默认的文本搜索配置从document中提取和正规化词元,并返回关于每个词元是如何处理的信息。 + 根据指定的或默认的文本检索配置从document中提取和正规化词元,并返回关于每个词元是如何处理的信息。 详情参见 diff --git a/zh/13/gist.sgml b/zh/13/gist.sgml index 24649554..f599b93c 100644 --- a/zh/13/gist.sgml +++ b/zh/13/gist.sgml @@ -834,7 +834,7 @@ my_compress(PG_FUNCTION_ARGS) 示例 - PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本搜索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: + PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本检索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: diff --git a/zh/13/json.sgml b/zh/13/json.sgml index fec14f98..8e76a9ef 100644 --- a/zh/13/json.sgml +++ b/zh/13/json.sgml @@ -38,7 +38,7 @@ - 由于 json 类型存储的是输入文本的精确副本,因此它会保留标记 + 由于 json 类型存储的是输入文本的精确副本,因此它会保留词元 之间在语义上无关紧要的空白,以及 JSON 对象内部键的顺序。此外,如果值中 的某个 JSON 对象包含同一个键多次,所有键/值对都会被保留下来(处理函数会 将最后一个值视为生效值)。相比之下,jsonb 不保留空白,不保留 @@ -86,7 +86,7 @@ 当把文本形式的 JSON 输入转换为 jsonb 时, - RFC 7159 描述的基本类型会有效映射到原生的 + RFC 7159 描述的基本类型实际上会映射到原生的 PostgreSQL 类型上,如 所示。因此,什么样的数据构成 有效的 jsonb 会有一些额外但较小的限制,这些限制不适用于 @@ -137,7 +137,7 @@ null - (无) + (无) SQL NULL 是不同的概念 @@ -152,18 +152,18 @@ 以下都是有效的 json(或 jsonb)表达式: --- Simple scalar/primitive value --- Primitive values can be numbers, quoted strings, true, false, or null +-- 简单的标量/基本值 +-- 基本值可以是数字、加引号的字符串、true、false 或 null SELECT '5'::json; --- Array of zero or more elements (elements need not be of same type) +-- 包含零个或多个元素的数组(元素不必是同一类型) SELECT '[1, 2, "foo", null]'::json; --- Object containing pairs of keys and values --- Note that object keys must always be quoted strings +-- 包含键值对的对象 +-- 注意,对象的键必须始终是加引号的字符串 SELECT '{"bar": "baz", "balance": 7.77, "active": false}'::json; --- Arrays and objects can be nested arbitrarily +-- 数组和对象可以任意嵌套 SELECT '{"foo": [true, "bar"], "tags": {"a": 1, "b": null}}'::json; @@ -219,8 +219,7 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 当 JSON 数据存储在表中时,它与任何其他数据类型一样,都要面对相同的并发控 制考量。虽然存储大型文档是可行的,但要记住,任何更新都会在整行上获取一个 行级锁。应考虑将 JSON 文档限制在可管理的大小,以减少更新事务之间的锁争用。 - 理想情况下,每个 JSON 文档都应表示一个原子数据项,按照业务规则,它不应被 - 合理地进一步拆分为更小且可独立修改的数据项。 + 理想情况下,每个 JSON 文档都应表示一个原子数据项,根据业务规则,无法再合理地将它细分为更小且可独立修改的数据项。 @@ -228,11 +227,11 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; <type>jsonb</type> 包含与存在 jsonb - containment + 包含 jsonb - existence + 存在 测试 包含jsonb 的一项重要能力。 @@ -241,33 +240,32 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 示例都返回真: --- Simple scalar/primitive values contain only the identical value: +-- 简单的标量/基本值只包含相同的值: SELECT '"foo"'::jsonb @> '"foo"'::jsonb; --- The array on the right side is contained within the one on the left: +-- 左侧数组包含右侧数组: SELECT '[1, 2, 3]'::jsonb @> '[1, 3]'::jsonb; --- Order of array elements is not significant, so this is also true: +-- 数组元素的顺序无关紧要,因此下面的结果也为真: SELECT '[1, 2, 3]'::jsonb @> '[3, 1]'::jsonb; --- Duplicate array elements don't matter either: +-- 重复的数组元素也无关紧要: SELECT '[1, 2, 3]'::jsonb @> '[1, 2, 2]'::jsonb; --- The object with a single pair on the right side is contained --- within the object on the left side: +-- 左侧对象包含右侧只有一个键值对的对象: SELECT '{"product": "PostgreSQL", "version": 9.4, "jsonb": true}'::jsonb @> '{"version": 9.4}'::jsonb; --- The array on the right side is not considered contained within the --- array on the left, even though a similar array is nested within it: -SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- yields false +-- 左侧数组被认为包含右侧数组, +-- 尽管其中嵌套了一个类似的数组: +SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- 结果为假 --- But with a layer of nesting, it is contained: +-- 但增加一层嵌套后,就构成了包含关系: SELECT '[1, 2, [1, 3]]'::jsonb @> '[[1, 3]]'::jsonb; --- Similarly, containment is not reported here: -SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- yields false +-- 同样,下面也不构成包含关系: +SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- 结果为假 --- A top-level key and an empty object is contained: +-- 包含由顶层键和空对象构成的对象: SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; @@ -282,11 +280,11 @@ SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; 对于结构必须匹配这一一般原则,有一个特殊例外:数组可以包含一个基本值: --- This array contains the primitive string value: +-- 这个数组包含该基本字符串值: SELECT '["foo", "bar"]'::jsonb @> '"bar"'::jsonb; --- This exception is not reciprocal -- non-containment is reported here: -SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false +-- 这个例外并不对称——下面的结果表示不包含: +SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- 结果为假 @@ -296,19 +294,19 @@ SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false 外,下面这些示例都返回真: --- String exists as array element: +-- 字符串作为数组元素存在: SELECT '["foo", "bar", "baz"]'::jsonb ? 'bar'; --- String exists as object key: +-- 字符串作为对象键存在: SELECT '{"foo": "bar"}'::jsonb ? 'foo'; --- Object values are not considered: -SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- yields false +-- 不考虑对象的值: +SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- 结果为假 --- As with containment, existence must match at the top level: -SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- yields false +-- 与包含关系一样,存在性必须在顶层匹配: +SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- 结果为假 --- A string is considered to exist if it matches a primitive JSON string: +-- 如果字符串与一个基本 JSON 字符串匹配,则认为它存在: SELECT '"foo"'::jsonb ? 'foo'; @@ -322,8 +320,7 @@ SELECT '"foo"'::jsonb ? 'foo'; 由于 JSON 包含是嵌套的,因此适当的查询可以跳过对子对象的显式选择。例如, 假设我们有一个 doc 列,其顶层是对象,而且大 多数对象都带有 tags 字段,该字段中包含子对象数组。下面 - 这个查询会找出那些包含同时带有 "term":"paris" 和 - "term":"food" 的子对象的项,同时忽略 + 这个查询会找出同时出现包含 "term":"paris" 的子对象和包含 "term":"food" 的子对象的项,同时忽略 tags 数组之外的任何此类键: SELECT doc->'site_name' FROM websites @@ -353,7 +350,7 @@ SELECT doc->'site_name' FROM websites <type>jsonb</type> 索引 jsonb - indexes on + 索引 @@ -361,9 +358,20 @@ SELECT doc->'site_name' FROM websites 或键/值对。提供了两种 GIN 操作符类,它们在性能和灵活性 之间提供不同的权衡。 - 对于jsonb,默认 GIN 操作符类支持使用键存在操作符??|?&、包含操作符@>以及jsonpath匹配操作符@?@@的查询。(这些操作符所实现语义的详情,参见。)使用此操作符类创建索引的示例如下: + + jsonb 的默认 GIN 操作符类支持使用键存在操作符 + ??|?&, + 包含操作符 @>,以及 jsonpath 匹配操作符 + @?@@ 的查询。(关于这些操作符 + 所实现语义的细节,见 。) + 使用此操作符类创建索引的例子如下: + CREATE INDEX idxgin ON api USING GIN (jdoc); -非默认的 GIN 操作符类jsonb_path_ops不支持键存在操作符,但支持@>@?@@。使用此操作符类创建索引的示例如下: + + 非默认的 GIN 操作符类 jsonb_path_ops 不支持键存在 + 操作符,但支持 @>@? 和 + @@。使用此操作符类创建索引的例子如下: + CREATE INDEX idxginp ON api USING GIN (jdoc jsonb_path_ops); @@ -392,14 +400,14 @@ CREATE INDEX idxginp ON api USING GIN (jdoc jsonb_path_ops); 名为 jdocjsonb 列里。 如果在该列上创建了 GIN 索引,那么下面这样的查询就可以利用这个索引: --- Find documents in which the key "company" has value "Magnafone" +-- 查找键 "company" 的值为 "Magnafone" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"company": "Magnafone"}'; 但是,类似下面这样的查询就无法使用该索引,因为虽然操作符 ? 可索引,但它并未直接应用到被索引的列 jdoc 上: --- Find documents in which the key "tags" contains key or array element "qui" +-- 查找键 "tags" 包含键或数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc -> 'tags' ? 'qui'; 不过,只要适当地使用表达式索引,上述查询也可以利用索引。如果经常查询 @@ -417,7 +425,7 @@ CREATE INDEX idxgintags ON api USING GIN ((jdoc -> 'tags')); 另一种查询方法是利用包含,例如: --- Find documents in which the key "tags" contains array element "qui" +-- 查找键 "tags" 包含数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qui"]}'; jdoc 列上的简单 GIN 索引可以支持这个查询。 @@ -427,14 +435,26 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu 对性的表达式索引通常会比简单索引更小,搜索起来也更快。 - GIN 索引还支持@?@@操作符,用于执行jsonpath匹配。示例如下: + + GIN 索引还支持 @?@@ 操作符, + 它们执行 jsonpath 匹配。示例如下: + SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @? '$.tags[*] ? (@ == "qui")'; SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; -对于这些操作符,GIN 索引会提取形如访问器链 - = 常量的子句,其来源是jsonpath模式,然后根据这些子句中的键和值执行索引搜索。访问器链可以包含., - [*][下标]访问器。jsonb_ops操作符类还支持.*.**访问器,但jsonb_path_ops操作符类不支持。 + + 对于这些操作符,GIN 索引会从 + jsonpath 模式中提取出形如 + accessors_chain = constant 的子句,并根据其中提到 + 的键和值进行索引搜索。访问器链可以包含 + .key、 + [*] 和 + [index] 访问器。 + jsonb_ops 操作符类还支持 .* 和 + .** 访问器,但 jsonb_path_ops + 操作符类不支持。 + 虽然 jsonb_path_ops 操作符类只支持带有 @@ -442,7 +462,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; @@ 操作符的查询,但相较于默认操作符类 jsonb_ops,它具有显著的性能优势。 jsonb_path_ops 索引通常比相同数据上的 - jsonb_ops 索引小得多,而且搜索条件也更具特异性,尤其是在 + jsonb_ops 索引小得多,而且搜索也更有针对性,尤其是在 查询中包含数据里频繁出现的键时。因此,搜索操作通常比使用默认操作符类时 性能更佳。 @@ -458,9 +478,9 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; 基本上,每个 jsonb_path_ops 索引项都是该值连同 - 通向该值的键一起计算出的哈希。例如,要索引 + 通向该值的键一起计算出的 hash。例如,要索引 {"foo": {"bar": "baz"}},会创建一个单独的索引项, - 其哈希值中同时纳入 foobar 和 + 其 hash 值中同时纳入 foobarbaz 这三者。因此,查找这一结构的包含查询会得到一次 非常精确的索引搜索;但完全没有办法据此找出 foo 是否 作为键出现。另一方面,jsonb_ops 索引会分别创建三个 @@ -479,19 +499,34 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; - jsonb也支持btreehash索引。通常只有在需要检查完整 JSON 文档是否相等时,这些索引才有用。对于btree排序,jsonb数据的顺序很少值得关注,但为求完整,列出如下: + jsonb 还支持 btree 和 + hash 索引。通常只有在需要检查完整 JSON 文档是否相等时, + 它们才有用。btreejsonb 数据项的 + 排序顺序通常很少受到关注,但为了完整起见,其规则如下: + 对象 > 数组 > 布尔值 > 数字 > 字符串 > null 包含 n 个键值对的对象 > 包含 n - 1 个键值对的对象 包含 n 个元素的数组 > 包含 n - 1 个元素的数组 -例外是,出于历史原因,空的顶层数组排在null之前。键值对数量相等的对象按以下顺序比较: + + 其中有一个例外:出于历史原因,顶层空数组的排序小于 + null。如果对象所含键值对数量相同,则按如下顺序比较: + 键-1, 值-1, 键-2 ... -注意,对象键按其存储顺序比较;尤其是,较短的键存储在较长的键之前,因此可能产生不直观的结果,例如: + + 注意,对象键按照其存储顺序进行比较;尤其是由于较短的键会先于较长的键 + 存储,因此这可能导致一些不太直观的结果,例如: + { "aa": 1, "c": 1} > {"b": 1, "d": 1} -类似地,元素数量相等的数组按以下顺序比较: + + 同样,如果数组所含元素数量相同,则按如下顺序比较: + 元素-1, 元素-2 ... -JSON 基本值使用与其底层PostgreSQL数据类型相同的规则进行比较。字符串使用数据库的默认排序规则进行比较。 + + JSON 基本值使用与底层 PostgreSQL 数据类 + 型相同的比较规则。字符串使用默认数据库排序规则进行比较。 + @@ -504,7 +539,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; PL/Perl 的扩展名为 jsonb_plperljsonb_plperlu。如果使用它们, - jsonb 值会按适当方式映射为 Perl 数组、哈希和标量。 + jsonb 值会按适当方式映射为 Perl 数组、hash 和标量。 @@ -581,7 +616,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; - 路径表达式由一系列路径元素构成,可以是下列任意一种: + 路径表达式由一系列路径元素构成,这些元素可以是下列任意一种: @@ -720,7 +755,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; 类似 .**,但只选择 JSON 层次结构中指定的层级。 - 嵌套层级以整数指定。层级零对应当前对象。若要访问最低的嵌套层级, + 嵌套层级以整数指定。层级零对应当前对象。若要访问最深的嵌套层级, 可以使用 last 关键字。这是 PostgreSQL 对 SQL/JSON 标准的扩展。 @@ -738,13 +773,13 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; 可以用两种形式给出: indexstart_index to end_index。 - 第一种形式按索引返回单个数组元素。第二种形式按索引范围返回数组切片, + 第一种形式按下标返回单个数组元素。第二种形式按下标范围返回数组切片, 其中包括与给定 start_indexend_index 对应的元素。 指定的 index 可以是整数,也可以是返回单个 - 数值的表达式,该表达式会自动转换为整数。索引零对应第一个数组元素。 + 数值的表达式,该数值会自动转换为整数。下标零对应第一个数组元素。 你也可以使用 last 关键字来表示最后一个数组元素, 这对于处理长度未知的数组很有用。 diff --git a/zh/13/libpq.sgml b/zh/13/libpq.sgml index 6af68ed2..76ff652f 100644 --- a/zh/13/libpq.sgml +++ b/zh/13/libpq.sgml @@ -1,7 +1,7 @@ - <application>libpq</application> - C 库 + <application>libpq</application> — C 库 libpq @@ -12,19 +12,19 @@ - libpq是应用程序员使用PostgreSQLC接口。libpq是一个库函数的集合,它们允许客户端程序传递查询给PostgreSQL后端服务器并且接收这些查询的结果。 + libpqPostgreSQLC应用程序编程接口。libpq是一组库函数,客户端程序可用它们向PostgreSQL后端服务器发送查询并接收查询结果。 - libpq也是很多其他PostgreSQL应用接口的底层引擎,包括为 C++、Perl、Python、Tcl 和 ECPG编写的接口。如果你使用那些包,某些方面的libpq行为将会对你很重要。特别是,描述了任何使用libpq的应用的用户可见的行为。 + libpq也是其他几个PostgreSQL应用程序接口的底层引擎,包括为 C++、Perl、Python、Tcl 和ECPG编写的接口。因此,对于这些包的用户,libpq行为的某些方面也很重要。特别是,描述了任何使用libpq的应用程序的用户都能观察到的行为。 - 在本章的末尾()包括了一些短程序来展示如何编写使用libpq的应用。在源代码发布的src/test/examples目录中还有一些完整的libpq应用的示例。 + 本章末尾()包含一些简短程序,展示如何编写使用libpq的程序。源代码发行包的src/test/examples目录中还提供了几个完整的libpq应用程序示例。 - 使用libpq的客户端程序必须包括头文件libpq-fe.hlibpq-fe.h并必须与libpq库链接在一起。 + 使用libpq的客户端程序必须包含头文件libpq-fe.hlibpq-fe.h,并且必须与libpq库链接。 @@ -39,7 +39,7 @@ - 在 Unix 上,复制一个拥有打开 libpq 连接的进程可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行代码是安全的。 + 在 Unix 上,对持有已打开 libpq 连接的进程执行 fork 操作可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行程序是安全的。 @@ -66,32 +66,32 @@ PGconn *PQconnectdbParams(const char * const *keywords, - 被传递的数组可以为空,这样就会使用所有默认参数。 - 也可以只包含一个或几个参数设置。他们在长度上必须匹配。 - 对于参数数组的处理将会停止于keywords数组中第一个NULL元素。 - 而且,如果与非-NULL keywords条目相关联的values条目为NULL或者空字符串,则忽略该项并继续处理下一对数组项。 + 传入的数组可以为空,以使用所有默认参数,也可以包含一个或多个参数设置。 + 两个数组的长度必须相同。处理会在 keywords 数组的第一个 NULL 元素处停止。 + 如果某个非 NULLkeywords 元素所对应的 + values 元素为 NULL 或空字符串,则忽略这一项,继续处理下一对数组元素。 - 当expand_dbname为非零时,会检查第一个dbname关键词的值以查看它是否为一个连接字符串。 - 如果是,它被扩展到从字符串中提取的单独的连接参数。 - 该值被认为是一个连接字符串,而不仅是一个数据库名称,如果它包含一个等号(=)或者它以URI模式标志符开头, - (有关连接字符串格式的更多详情可见。) - 只有dbname的第一次出现会按这种方式处理,任何后续dbname值会被当做一个普通数据库名处理。 + 当 expand_dbname 非零时,会检查第一个 dbname 关键词的值是否为 + 连接字符串。如果是,就将其展开为从该字符串中提取的各个连接参数。 + 如果该值包含等号(=),或以 URI 方案标识符开头,就会将其视为连接字符串,而非单纯的数据库名。 + (连接字符串格式的详细说明见。) + 只有第一次出现的 dbname 会按这种方式处理;后续的 dbname 参数都作为普通数据库名处理。 - 通常,参数数组从开头到结尾进行处理。 - 当关键词有重复时,使用最后一个值(不是 NULL 或空)。 - 此规则特别适用于连接字符串中的关键字与一个出现在keywords数组中的关键字冲突的情况。 - 因此,程序员可以决定数组条目是否能被覆盖或用连接字符串获取的值覆盖。 - 出现在扩展的dbname条目之前的数组条目可以被连接字符串的字段所覆盖,反之,这些字段被dbname之后出现的数组条目所覆盖。(但是,再有,只有在那些条目支持非空值时。) + 通常会从头到尾处理参数数组。如果某个关键词重复出现,则采用最后一个非 NULL 且非空的值。 + 此规则也适用于连接字符串中的关键词与 keywords 数组中的关键词冲突的情况。 + 因此,程序员可以决定数组元素是覆盖连接字符串中的值,还是被这些值覆盖。 + 出现在要展开的 dbname 元素之前的数组元素,可以被连接字符串中的字段覆盖; + 而这些字段又会被出现在 dbname 之后的数组元素覆盖(同样,只有这些元素提供非空值时才会覆盖)。 - 在处理完所有数组条目和任何扩展的连接字符串后,所有未设置的连接参数都将使用默认值填充。 - 如果一个未设置参数的相关环境变量(参见 )被设置了,它的值会被使用。 - 如果环境变量未被设置,则使用参数的内置默认值。 + 处理完所有数组元素及展开的连接字符串后,仍未设置的连接参数将填入默认值。 + 如果某个未设置参数对应的环境变量(见)已经设置,就使用该环境变量的值; + 否则使用该参数的内置默认值。 @@ -113,7 +113,7 @@ PGconn *PQconnectdb(const char *conninfo); - 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空格分隔的一个或多个参数设置,还可以包含一个URI。详见。 + 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空白分隔的一个或多个参数设置,还可以包含一个URI。详见 @@ -136,11 +136,11 @@ PGconn *PQsetdbLogin(const char *pghost, - 这是的带有固定参数集合的前辈。它具有相同的功能,不过其中缺失的参数将总是采用默认值。对任意一个固定参数写NULL或一个空字符串将会使它采用默认值。 + 这是 的前身,使用固定的一组参数。除缺失参数始终采用默认值之外,功能相同。对于要使用默认值的任意固定参数,请传入 NULL 或空字符串。 - 如果dbName包含一个=符号或者具有一个合法的连接URI前缀,它会被当作一个conninfo字符串,就好像它已经被传递给了,并且剩余的参数则被应用为指定给。 + 如果 dbName 包含 = 符号,或具有有效的连接 URI 前缀,就会将其当作 conninfo 字符串处理,方式与将其传给 完全相同,然后按照 的规则应用其余参数。 @@ -171,7 +171,7 @@ PGconn *PQsetdb(char *pghost, PQconnectPollPQconnectPoll - nonblocking connection + 非阻塞连接 以非阻塞的方式建立一个到数据库服务器的连接。 @@ -204,7 +204,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 如果你调用,确保你追踪的该流对象不会阻塞。 + 如果你调用,确保接收追踪输出的流对象不会阻塞。 @@ -217,7 +217,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 要开始无阻塞的连接请求,可调用PQconnectStart或者。如果结果为空,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 + 要开始非阻塞连接请求,可调用PQconnectStart或者。如果结果为空指针,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 @@ -316,11 +316,11 @@ switch(PQstatus(conn)) - 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。否则,PQconnectStart后面跟着PQconnectPoll循环等效于。 + 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。除此之外,PQconnectStart后面跟着PQconnectPoll循环等效于 - 注意当PQconnectStart返回一个非空的指针时,你必须在用完它之后调用来处理那些结构体和任何相关的内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 + 注意当PQconnectStart返回一个非空的指针时,你必须在用完它之后调用来释放该结构体及其关联的所有内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 @@ -336,21 +336,21 @@ PQconninfoOption *PQconndefaults(void); typedef struct { char *keyword; /* 该选项的关键词 */ - char *envvar; /* 依赖的环境变量名 */ - char *compiled; /* 依赖的内置默认值 */ + char *envvar; /* 后备环境变量名 */ + char *compiled; /* 编译时设置的后备默认值 */ char *val; /* 选项的当前值,或者 NULL */ - char *label; /* 连接对话框中域的标签 */ - char *dispchar; /* 指示如何在一个连接对话框中显示这个域。值是: + char *label; /* 连接对话框中字段的标签 */ + char *dispchar; /* 指示如何在连接对话框中显示此字段。可取值: "" 显示输入的值 - "*" 密码域 - 隐藏值 + "*" 密码字段 - 隐藏值 "D" 调试选项 - 默认不显示 */ - int dispsize; /* 用于对话框的以字符计的域尺寸 */ + int dispsize; /* 对话框中的字段宽度,以字符计 */ } PQconninfoOption; - 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前缺省值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回该空指针。注意当前缺省值(val域)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 + 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前默认值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回空指针。注意当前默认值(val字段)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 @@ -371,9 +371,7 @@ PQconninfoOption *PQconninfo(PGconn *conn); - 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前缺省值。 - 返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。 - 上述所有对于的注解也适用于的结果。 + 返回一个连接选项数组。可以用它确定所有可能的 选项,以及实际用于连接服务器的值。返回值指向一个 PQconninfoOption 结构体数组,该数组以 keyword 指针为空的条目结束。上文针对 的所有注意事项,也适用于 的结果。 @@ -400,7 +398,9 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); - 如果errmsg不是NULL,那么成功时*errmsg会被设置为NULL, 否则设置为被malloc过的错误字符串以说明该问题(也可以将*errmsg设置为NULL并且函数返回NULL,这表示一种内存耗尽的情况)。 + 如果 errmsg 不是 NULL,则成功时将 *errmsg 设为 NULL; + 失败时将其设为由 malloc 分配的、用于说明问题的错误字符串。 + (也可能出现 *errmsg 被设为 NULL,同时函数返回 NULL 的情况;这表示内存不足。) @@ -430,7 +430,7 @@ void PQfinish(PGconn *conn); PQresetPQreset - 重置与服务器的通讯通道。 + 重置与服务器的通信通道。 void PQreset(PGconn *conn); @@ -448,7 +448,7 @@ void PQreset(PGconn *conn); PQresetPollPQresetPoll - 以非阻塞方式重置与服务器的通讯通道。 + 以非阻塞方式重置与服务器的通信通道。 int PQresetStart(PGconn *conn); @@ -464,7 +464,9 @@ PostgresPollingStatusType PQresetPoll(PGconn *conn); 这些函数受到PQconnectStartPQconnectPoll相同的限制。 - 要开始重置连接,请调用 。如果返回 0,表示重置失败。如果返回 1,则使用 PQresetPoll 轮询重置过程,方式与使用 PQconnectPoll 建立连接完全相同。 + + 要开始重置连接,请调用 。如果返回 0,表示重置失败。如果返回 1,则使用 PQresetPoll 轮询重置过程,方式与使用 PQconnectPoll 建立连接完全相同。 + @@ -558,7 +560,7 @@ void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook); int callback_fn(char *buf, int size, PGconn *conn); - 随后,libpq会调用该回调,而不是调用其默认的PQdefaultSSLKeyPassHook_OpenSSL处理程序。 + 随后,libpq会调用该回调,而不是调用其默认的PQdefaultSSLKeyPassHook_OpenSSL处理程序。 回调函数应确定密钥密码,并将其复制到大小为size的结果缓冲区buf中。 buf中的字符串必须以空字符结尾。 回调函数必须返回存储在buf中的密码长度,不包括结尾的空字符。 @@ -577,7 +579,7 @@ int callback_fn(char *buf, int size, PGconn *conn); - 除了异常、longjmp(...)等情况外,回调务必不可跳出正常控制流。它必须正常返回。 + 回调不得通过异常、longjmp(...)等方式跳出正常控制流。它必须正常返回。 @@ -613,19 +615,19 @@ PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void); 几个libpq函数解析用户指定的字符串以获取连接参数。 - 这些字符串有两种被接受的格式:普通的关键字/值字符串和URI。URI通常遵循 + 这些字符串有两种被接受的格式:普通的关键词/值字符串和URI。URI通常遵循 RFC - 3986,除了允许多主机连接字符串,如下面进一步描述的那样。 + 3986,但也允许使用多主机连接字符串,详见下文。 关键词/值连接字符串 - 在关键词/值格式中,每一个参数设置的形式都是keyword = value,在设置之间有空白。 - 设置的等号周围的空白是可选的。 - 要写一个空值或一个包含空白的值,将它用单引号包围,例如keyword = 'a value'。 - 值里面的单引号和反斜线必须用一个反斜线转义,即\'\\。 + 在关键词/值格式中,每一个参数设置的形式都是关键词 = ,设置之间以空格分隔。 + 设置的等号周围的空格是可选的。 + 要写一个空值或一个包含空格的值,将它用单引号包围,例如keyword = 'a value'。 + 值里面的单引号和反斜杠必须用一个反斜杠转义,即\'\\ @@ -648,22 +650,22 @@ host=localhost port=5432 dbname=mydb connect_timeout=10 postgresql://userspec@hostspec/dbname?paramspec -where userspec is: +其中 userspec 为: user:password -and hostspec is: +hostspec 为: host:port,... -and paramspec is: +paramspec 为: name=value&... - URI模式标志符可以是postgresql://postgres://。 + URI方案标识符可以是postgresql://postgres://。 每一个剩下的URI部分都是可选的。 下列示例展示了合法的URI语法: @@ -680,19 +682,15 @@ postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application postgresql:///mydb?host=localhost&port=5433 - 全部的命名参数必须匹配中列出的关键词,除了与JDBC连接URI兼容之外,ssl=true的实例转换到sslmode=require。 + 所有命名参数都必须与中列出的关键词匹配;唯一的例外是,为兼容 JDBC 连接 URI,会将 ssl=true 转换为 sslmode=require - 连接URI需要使用百分号编码 - 对其进行编码,如果其中包含具有特殊含义的符号。这里是一个示例,其中等号(=)被替换为 - %3D,空格字符被替换为 - %20: + 如果连接 URI 的任意部分包含具有特殊含义的符号,就需要使用百分号编码。下面的示例将等号(=)替换为 %3D,将空格字符替换为 %20 postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff - + 主机部分可能是主机名或一个 IP 地址。要指定一个 IPv6 地址,将它封闭在方括号中: @@ -705,7 +703,7 @@ postgresql://[2001:db8::1234]/database 主机组件会被按照参数对应的描述来解释。 特别地,如果主机部分是空或看起来像一个绝对路径名称,将使用一个 Unix 域套接字连接,否则将启动一个 TCP/IP 连接。 不过要注意,斜线是 URI 层次部分中的一个保留字符。 - 因此,要指定一个非标准的 Unix 域套接字目录,要么忽略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: + 因此,要指定一个非标准的 Unix 域套接字目录,要么省略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: postgresql:///dbname?host=/var/lib/postgresql postgresql://%2Fvar%2Flib%2Fpostgresql/dbname @@ -715,7 +713,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以在一个URI中指定多个主机,每一个都有一个可选的端口。 一个形式为postgresql://host1:port1,host2:port2,host3:port3/的URI等效于host=host1,host2,host3 port=port1,port2,port3形式的连接字符串。 - 如下所述,每一个主机都将被尝试,直到成功地建立一个连接。 + 如下所述,每一个主机都将被依次尝试,直到成功地建立一个连接。 @@ -725,7 +723,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以指定多个要连接的主机,这样它们会按给定的顺序被尝试。 - 在键/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 + 在关键词/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 在指定的每一个选项中都必须给出相同数量的元素,这样第一个hostaddr对应于第一个主机名,第二个hostaddr对应于第二个主机名,以此类推。 不过,如果仅指定一个port,它将被应用于所有的主机。 @@ -735,11 +733,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 不管是哪一种格式,单一的主机名可以被翻译成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 + 不管是哪一种格式,单一的主机名可以被解析成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 - 当多个主机被指定时或者单个主机名被翻译成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。 + 当多个主机被指定时或者单个主机名被解析成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。 @@ -756,13 +754,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname host - 要连接的主机名。主机名如果主机名看起来像绝对路径名, - 则指定的是Unix域通信而不是TCP/IP通信;该值是存储套接字文件的目录的名称。 - (在Unix上,绝对路径名以斜杠开头。在Windows上,以驱动器号开头的路径也被识别。) - 当未指定host或为空时,默认行为是连接到Unix域套接字Unix域套接字在 - /tmp(或在构建PostgreSQL时指定的套接字目录)中。在Windows和 - 没有Unix域套接字的机器上,默认是连接到localhost。 - + 要连接的主机名。主机名如果主机名看起来像绝对路径名, + 则指定的是 Unix 域通信,而非 TCP/IP 通信;此值是存放套接字文件的目录名。 + (在 Unix 上,绝对路径名以斜杠开头。在 Windows 上,也会识别以驱动器号开头的路径。) + 当未指定 host 或其值为空时,默认连接到 /tmp + (或构建 PostgreSQL 时指定的套接字目录)中的 Unix 域套接字。 + Unix 域套接字在 Windows 和没有 Unix 域套接字的机器上,默认连接到 localhost。 + 也可以接受一个逗号分隔的主机名列表,此时列表中的每个主机名将按顺序尝试; 列表中的空项将选择上述默认行为。详细信息请参见。 @@ -784,7 +782,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 如果指定了host而没有指定hostaddr,则会发生主机名查找。 (当使用PQconnectPoll时,查找发生在PQconnectPoll首次考虑此主机名时, - 并且可能导致PQconnectPoll阻塞一段时间。) + 并且可能导致PQconnectPoll阻塞相当长的时间。) @@ -796,11 +794,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果同时指定了hosthostaddr, - 则hostaddr的值给出服务器的网络地址。 - 除非认证方法需要,否则host的值将被忽略, - 在这种情况下,它将用作主机名。 - + 如果同时指定了 hosthostaddr,则 hostaddr 的值给出服务器的网络地址。只有认证方法需要主机名时,才会将 host 的值用作主机名;否则忽略该值。 + 注意,以下情况很可能导致认证失败:host不是位于网络地址hostaddr的服务器名称。另外,同时指定hosthostaddr时,将使用host来标识密码文件中的连接(参见)。 @@ -848,8 +843,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - PostgreSQL用户连接的用户名。 - 默认为运行应用程序的操作系统用户名相同。 + 建立连接所用的 PostgreSQL 用户名。默认与运行应用程序的操作系统用户名相同。 @@ -859,7 +853,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果服务器要求密码认证,则使用密码。 + 服务器要求密码认证时所使用的密码。 @@ -884,7 +878,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 这个选项控制客户端对通道绑定的使用。设置为require表示连接必须使用通道绑定, prefer表示客户端将在可用时选择通道绑定, 而disable则阻止使用通道绑定。默认情况下, - 如果PostgreSQL是使用SSL支持编译的,则默认为prefer; + 如果PostgreSQL是使用SSL支持编译的,则默认为prefer; 否则默认为disable。 @@ -948,9 +942,9 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 指定配置参数的回退值。 + 指定配置参数的后备值。 如果没有通过连接参数或PGAPPNAME环境变量为application_name指定值, - 则将使用此值。在通用实用程序中指定回退名称很有用,该程序希望设置默认应用程序名称, + 则将使用此值。在通用实用程序中指定后备名称很有用,该程序希望设置默认应用程序名称, 但允许用户覆盖它。 @@ -961,9 +955,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制是否使用客户端TCP保持活动。默认值为1,表示开启,但如果不想要保持活动,可以将其更改为0,表示关闭。 - 对于通过Unix域套接字进行的连接,此参数将被忽略。 - + 控制是否使用客户端 TCP keepalive。默认值为 1,表示开启;如果不需要 keepalive,可以将其设为 0,表示关闭。对于通过 Unix 域套接字建立的连接,此参数会被忽略。 + @@ -972,11 +965,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在多少秒的不活动后,TCP应向服务器发送保持活动消息。值为零使用系统默认值。 - 对通过Unix域套接字进行的连接或禁用保持活动的连接,此参数将被忽略。 - 仅在支持TCP_KEEPIDLE或等效套接字选项的系统以及Windows上支持; - 在其他系统上,它没有任何效果。 - + 控制在多久没有活动后,TCP 应向服务器发送 keepalive 消息,以秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPIDLE 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -985,11 +975,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在服务器未确认的情况下重新传输TCP保持活动消息的秒数。值为零时使用系统默认值。 - 此参数在通过Unix域套接字进行连接或禁用保持活动时将被忽略。 - 仅在支持TCP_KEEPINTVL或等效套接字选项的系统和Windows上支持; - 在其他系统上,此参数无效。 - + 控制未被服务器确认收到的 TCP keepalive 消息在多少秒后应被重传。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPINTVL 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -998,11 +985,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在客户端与服务器之间连接被视为断开之前可以丢失的TCP keepalive数量。 - 值为零时使用系统默认值。对通过Unix域套接字建立的连接或禁用keepalives的连接,此参数将被忽略。 - 仅在支持TCP_KEEPCNT或等效套接字选项的系统上受支持; - 在其他系统上,此参数无效。 - + 控制在客户端与服务器之间的连接被视为中断之前,可以丢失多少个 TCP keepalive 消息。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPCNT 或等效套接字选项的系统上受支持;在其他系统上无效。 + @@ -1011,10 +995,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在连接在强制关闭之前,传输数据可以保持未被确认的毫秒数。 - 值为零时使用系统默认值。此参数对通过Unix域套接字进行的连接无效。 - 仅在支持TCP_USER_TIMEOUT的系统上受支持;在其他系统上,它没有效果。 - + 控制已发送的数据在连接被强制关闭之前最多可以保持未确认状态多长时间,以毫秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,此参数会被忽略。此参数仅在支持 TCP_USER_TIMEOUT 的系统上受支持;在其他系统上无效。 + @@ -1084,25 +1066,25 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个选项确定是否以及如何优先与服务器协商安全的GSS TCP/IP连接。有三种模式: + 这个选项确定是否以及以何种优先级与服务器协商安全的GSS TCP/IP连接。有三种模式: disable - 仅尝试非GSSAPI加密连接 + 仅尝试未经GSSAPI加密的连接 - prefer (默认) + prefer (默认) 如果存在GSSAPI凭据(即在凭据缓存中),首先尝试 GSSAPI加密连接;如果失败或没有凭据,则尝试 - 非GSSAPI加密连接。这是在编译PostgreSQL时使用GSSAPI支持时的默认设置。 + 未经GSSAPI加密的连接。这是在编译PostgreSQL时使用GSSAPI支持时的默认设置。 @@ -1121,7 +1103,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname gssencmode在Unix域套接字通信中被忽略。如果PostgreSQL没有编译GSSAPI支持, 使用require选项将导致错误,而prefer将被接受,但libpq实际上不会尝试 - 进行GSSAPI加密连接。GSSAPI与libpq + 进行GSSAPI加密连接。GSSAPI在 libpq 中 @@ -1152,7 +1134,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - prefer (默认) + prefer (默认) 首先尝试SSL连接;如果失败,则尝试非SSL连接 @@ -1192,16 +1174,18 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - sslmode被忽略用于Unix域套接字通信。 - 如果PostgreSQL没有SSL支持编译, + 在 Unix 域套接字通信中,sslmode 会被忽略。 + 如果PostgreSQL编译时未启用 SSL 支持, 使用选项requireverify-caverify-full会导致错误,而选项allowprefer 将被接受,但libpq实际上不会尝试建立SSL 连接。SSL使用libpq的SSL + sortas="libpq">在 libpq 中 - 注意,如果可以使用 GSSAPI 加密,就会优先使用它而不是 SSL 加密,无论 sslmode 的值是什么。在具有可用 GSSAPI 基础设施(例如 Kerberos 服务器)的环境中,要强制使用 SSL 加密,还应将 gssencmode 设为 disable + + 注意,如果可以使用 GSSAPI 加密,就会优先使用它而不是 SSL 加密,无论 sslmode 的值是什么。在具有可用 GSSAPI 基础设施(例如 Kerberos 服务器)的环境中,要强制使用 SSL 加密,还应将 gssencmode 设为 disable。 + @@ -1210,15 +1194,15 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 此选项已被sslmode设置所取代。 - + 此选项已弃用,请改用 sslmode 设置。 + 如果设置为1,则需要与服务器建立SSL连接(这相当于sslmode require)。libpq将拒绝连接,如果服务器不接受 SSL连接。如果设置为0(默认值), libpq将与服务器协商连接类型(相当于sslmode - prefer)。此选项仅在PostgreSQL编译时启用SSL支持。 + prefer)。此选项仅在 PostgreSQL 编译时启用了 SSL 支持的情况下可用。 @@ -1237,7 +1221,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果安全性不是主要考虑因素,压缩可以提高吞吐量,如果网络是瓶颈的话。如果CPU性能是限制因素,禁用压缩可以提高响应时间和吞吐量。 + 如果安全性不是主要考虑因素,压缩可以提高吞吐量,如果网络是瓶颈的话。如果CPU性能是限制因素,禁用压缩可以缩短响应时间并提高吞吐量。 @@ -1261,7 +1245,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 这个参数指定了用于客户端证书的密钥的位置。它可以指定一个文件名,该文件名将被用来替代默认的 ~/.postgresql/postgresql.key,或者它可以指定一个从外部引擎 - (引擎是OpenSSL可加载模块)获取的密钥。外部引擎规范应该包括一个由冒号分隔的引擎名称和 + (引擎是OpenSSL可加载模块)获取的密钥。外部引擎的指定形式应包含一个由冒号分隔的引擎名称和 一个引擎特定的密钥标识符。如果没有进行SSL连接,则此参数将被忽略。 @@ -1273,7 +1257,9 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 这个参数指定了在sslkey中指定的密钥的密码,允许客户端证书私钥在磁盘上以加密形式存储,即使交互式密码输入不可行。 - 当向 libpq 提供加密的客户端证书密钥时,将此参数指定为任意非空值,都将抑制 OpenSSL 默认发出的 Enter PEM pass phrase: 提示。 + + 当向 libpq 提供加密的客户端证书密钥时,将此参数指定为任意非空值,都将抑制 OpenSSL 默认发出的 Enter PEM pass phrase: 提示。 + 如果密钥未加密,则忽略此参数。该参数对由OpenSSL引擎指定的密钥没有影响,除非引擎使用OpenSSL密码回调机制进行提示。 @@ -1324,8 +1310,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定连接允许的最低SSL/TLS协议版本。有效值为TLSv1, - TLSv1.1TLSv1.2和 + 这个参数指定连接允许的最低SSL/TLS协议版本。有效值为TLSv1、 + TLSv1.1TLSv1.2TLSv1.3。支持的协议取决于所使用的 OpenSSL版本,旧版本不支持最现代的协议版本。 如果未指定,默认值为TLSv1.2,符合本文撰写时的行业最佳实践。 @@ -1338,11 +1324,10 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定连接允许的最大SSL/TLS协议版本。有效值为TLSv1, - TLSv1.1TLSv1.2和 + 这个参数指定连接允许的最大SSL/TLS协议版本。有效值为TLSv1、 + TLSv1.1TLSv1.2TLSv1.3。支持的协议取决于使用的OpenSSL - 版本,旧版本不支持最新的协议版本。如果未设置,将忽略此参数,并且连接将使用后端定义的最大限制, - 如果设置。设置最大协议版本主要用于测试或者某些组件无法使用较新协议时。 + 版本,旧版本不支持最新的协议版本。如果未设置,则忽略此参数;如果后端定义了最大限制,连接将使用该限制。设置最大协议版本主要用于测试或者某些组件无法使用较新协议时。 @@ -1352,13 +1337,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 用于使用GSSAPI进行认证时要使用的Kerberos服务名称。 + 使用 GSSAPI 认证时所用的 Kerberos 服务名。 这必须与服务器配置中指定的Kerberos认证服务名称匹配,才能成功进行认证。 (另请参见。) 默认值通常为postgres, - 但在构建PostgreSQL时可以通过 - 选项进行更改 - configure。 + 但在构建 PostgreSQL 时,可以通过 configure 选项更改。 在大多数环境中,通常不需要更改此参数。 一些Kerberos实现可能需要不同的服务名称, 例如Microsoft Active Directory需要服务名称为大写(POSTGRES)。 @@ -1404,20 +1387,21 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 连接状态函数 - 这些函数可以被用来询问一个已有数据库连接对象的状态。 + 这些函数可用于查询现有数据库连接对象的状态。 - libpq-fe.h - libpq-int.h - libpq应用程序员应该小心地维护PGconn抽象。使用下面描述的访问函数来理解PGconn的内容。我们不推荐使用libpq-int.h引用内部的PGconn域,因为它们可能在未来改变。 - + libpq-fe.h + libpq-int.h + 编写 libpq 应用程序时,应注意维护 PGconn 的抽象。请使用下述访问函数获取 PGconn 的内容。不建议通过 libpq-int.h 引用 PGconn 的内部字段,因为这些字段将来可能改变。 + - 以下函数返回建立连接时确定的参数值。这些值在连接存续期间保持不变。如果使用多主机连接字符串,以下函数的值:, - 可能会在使用同一个PGconn对象建立新连接时改变。其他值在以下对象的整个生命周期内保持不变:PGconn对象。 + + 以下函数返回建立连接时确定的参数值。这些值在连接存续期间保持不变。如果使用多主机连接字符串,并使用同一个 PGconn 对象建立新连接,则 的返回值可能改变。其他值在 PGconn 对象的整个生命周期内保持不变。 + PQdbPQdb @@ -1464,7 +1448,7 @@ char *PQpass(const PGconn *conn); - 返回活跃连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 + 返回活动连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 char *PQhost(const PGconn *conn); @@ -1476,7 +1460,7 @@ char *PQhost(const PGconn *conn); - 如果conn参数是NULL,则返回NULL。否则,如果有一个错误产生主机信息(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成主机信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1498,8 +1482,7 @@ char *PQhostaddr(const PGconn *conn); - 如果conn 参数为 NULL 返回 NULL 。 - 否则,如果生成主机信息时出现错误(如果连接尚未完全建立或出现错误),则返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成主机信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1509,7 +1492,7 @@ char *PQhostaddr(const PGconn *conn); - 返回活跃连接的端口。 + 返回活动连接的端口。 char *PQport(const PGconn *conn); @@ -1521,7 +1504,7 @@ char *PQport(const PGconn *conn); - 如果conn参数是NULL,则返回NULL。否则,如果有一个错误产生端口信息(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成端口信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1534,7 +1517,9 @@ char *PQport(const PGconn *conn); PQttyPQtty - 返回该连接用于调试的TTY。(此功能已过时,因为服务器不再使用TTY设置,但为保持向后兼容仍保留此函数。) + + 返回该连接用于调试的TTY。(此功能已过时,因为服务器不再使用TTY设置,但为保持向后兼容仍保留此函数。) + char *PQtty(const PGconn *conn); @@ -1546,7 +1531,7 @@ char *PQtty(const PGconn *conn); - 返回被传递给连接请求的命令行选项。 + 返回连接请求中传递的命令行选项。 char *PQoptions(const PGconn *conn); @@ -1554,9 +1539,11 @@ char *PQoptions(const PGconn *conn); - + - 以下函数返回的状态数据可能在执行操作时发生变化,这些操作针对PGconn对象。 + + 以下函数返回的状态数据,可能随着对 PGconn 对象执行操作而改变。 + PQstatusPQstatus @@ -1592,7 +1579,7 @@ ConnStatusType PQstatus(const PGconn *conn); PGTransactionStatusType PQtransactionStatus(const PGconn *conn); - 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个合法的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接损坏,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE。 + 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个有效的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接异常,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE @@ -1634,9 +1621,12 @@ const char *PQparameterStatus(const PGconn *conn, const char *paramName); PQprotocolVersionPQprotocolVersion - 查询正在使用的前端/后端协议。 + + 查询正在使用的前端/后端协议。 + int PQprotocolVersion(const PGconn *conn); -应用程序可以使用此函数判断是否支持某些特性。目前,可能的值为 2(协议 2.0)、3(协议 3.0)或零(连接异常)。连接启动完成后,协议版本不会改变,但理论上可能在连接重置期间改变。通常,与PostgreSQL7.4 或更高版本的服务器通信时使用协议 3.0;7.4 之前的服务器仅支持协议 2.0。(协议 1.0 已过时,以下库不再支持它:libpq。) + +应用程序可以使用此函数判断是否支持某些特性。目前,可能的值为 2(协议 2.0)、3(协议 3.0)或零(连接异常)。连接启动完成后,协议版本不会改变,但理论上可能在连接重置期间改变。通常,与 PostgreSQL 7.4 或更高版本的服务器通信时使用协议 3.0;7.4 之前的服务器仅支持协议 2.0。(协议 1.0 已过时,libpq 不支持它。) @@ -1657,11 +1647,11 @@ int PQserverVersion(const PGconn *conn); - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 + 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,为每个部分使用两位数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 + 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。在所有主版本系列中,各次版本(缺陷修复版本)之间只有最后两位数字不同。 @@ -1680,9 +1670,7 @@ char *PQerrorMessage(const PGconn *conn); - 几乎所有的libpq在失败时都会为设置一个消息。 - 注意按照libpq习惯,一个非空结果由多行构成,并且将包括一个尾部新行。 - 调用者不应该直接释放结果。当相关的PGconn句柄被传递给时,它将被释放。在PGconn结构体上的多个操作之间,不能指望结果字符串会保持不变。 + 几乎所有 libpq 函数在失败时都会设置一条供 返回的消息。注意,按照 libpq 的约定,非空的 结果可能包含多行,并以换行符结尾。调用者不应直接释放该结果;当关联的 PGconn 句柄被传给 时,结果会被释放。不能假定在对 PGconn 结构体执行其他操作后,结果字符串仍保持不变。 @@ -1691,7 +1679,7 @@ char *PQerrorMessage(const PGconn *conn); PQsocketPQsocket - 获得到服务器连接套接字的文件描述符号。一个合法的描述符将会大于等于零。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 + 获取与服务器相连的套接字的文件描述符编号。有效描述符大于或等于 0。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 int PQsocket(const PGconn *conn); @@ -1708,7 +1696,7 @@ int PQsocket(const PGconn *conn); 返回处理这个连接的后端进程的进程ID(PID)。 PID 确定服务器进程的 PID - in libpq + 在 libpq 中 @@ -1717,7 +1705,7 @@ int PQbackendPID(const PGconn *conn); - 后端PID有助于调试目的并且可用于与NOTIFY消息(它包括发出提示的后端进程的PID)进行比较。注意PID属于一个在数据库服务器主机上执行的进程,而不是本地主机进程! + 后端 PID 可用于调试,也可与 NOTIFY 消息进行比较(消息包含发出通知的后端进程的 PID)。注意,该 PID 属于在数据库服务器主机上运行的进程,而非本地主机上的进程! @@ -1756,16 +1744,18 @@ int PQconnectionUsedPassword(const PGconn *conn); - + - 以下函数返回与 SSL 相关的信息。这些信息通常在连接建立后不会改变。 + + 以下函数返回与 SSL 相关的信息。这些信息通常在连接建立后不会改变。 + PQsslInUsePQsslInUse - 返回true(1)如果连接使用SSL,返回false(0)如果不使用。 + 如果连接使用 SSL,则返回真(1);否则返回假(0)。 int PQsslInUse(const PGconn *conn); @@ -1784,7 +1774,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); - 可用属性列表因使用的SSL库和连接类型而异。如果连接不使用SSL或指定的属性名称对于所使用的库未定义,则返回NULL。 + 可用属性列表因所使用的 SSL 库和连接类型而异。如果某个属性不可用,则返回 NULL。 通常可以获取以下属性: @@ -1853,12 +1843,14 @@ const char * const * PQsslAttributeNames(const PGconn *conn); PQsslStructPQsslStruct - 返回一个指向描述连接的SSL实现特定对象的指针。如果连接未加密或SSL实现不提供连接的请求对象类型,则返回NULL。 + 返回指向描述此连接的对象的指针,该对象的类型由 SSL 实现决定。 void *PQsslStruct(const PGconn *conn, const char *struct_name); - 可用的结构体取决于所使用的 SSL 实现。对于 OpenSSL,有一个名为 "OpenSSL" 的结构体,函数返回指向 OpenSSLSSL结构体的指针。可以使用如下代码调用此函数: + 可用的结构体取决于所使用的 SSL 实现。对于 OpenSSL,可以通过名称 "OpenSSL" 获取一个结构体,函数返回指向 OpenSSL 的 SSL 结构体的指针。可以使用如下代码调用此函数: + #include @@ -1905,7 +1897,7 @@ void *PQgetssl(const PGconn *conn); - + @@ -1913,7 +1905,7 @@ void *PQgetssl(const PGconn *conn); 命令执行函数 - 一旦到一个数据库服务器的连接被成功建立,这里描述的函数可以被用来执行 SQL 查询和命令。 + 与数据库服务器的连接成功建立后,此处描述的函数用于执行 SQL 查询和命令。 @@ -1934,11 +1926,8 @@ PGresult *PQexec(PGconn *conn, const char *command); - 返回一个PGresult指针或者可能是一个空指针。 - 除了内存不足的情况或者由于严重错误无法将命令发送给服务器之外,一般都会返回一个非空指针。 - 函数应当被调用来检查返回值是否代表错误(包括空指针的值,它会返回PGRES_FATAL_ERROR)。 - 用可得到关于那些错误的详细信息。 - + 返回一个 PGresult 指针,也可能返回空指针。除内存不足或无法向服务器发送命令等严重错误外,通常都会返回非空指针。应调用 函数检查返回值是否表示错误(也应检查空指针,此时该函数返回 PGRES_FATAL_ERROR)。使用 获取此类错误的更多信息。 + 命令字符串可以包含多个 SQL 命令(以分号分隔)。在一次调用中发送的多个查询会在同一个事务中处理,除非查询字符串中显式包含BEGIN/COMMIT命令,将其划分为多个事务。(有关服务器如何处理多查询字符串的详细信息,请参见。)但要注意,返回的PGresult结构体只描述该字符串中最后执行的命令的结果。如果其中一条命令失败,就会在此处停止处理该字符串,返回的PGresult则描述该错误。 @@ -2012,8 +2001,8 @@ PGresult *PQexecParams(PGconn *conn, paramValues[] - 指定参数的实际值。这个数组中的一个空指针表示对应的参数为空,否则该指针指向一个以零终止的文本字符串(用于文本格式)或者以服务器所期待格式的二进制数据(用于二进制格式)。 - + 指定参数的实际值。数组中的空指针表示对应参数为 null;否则,指针指向以零结尾的文本字符串(文本格式),或采用服务器所要求格式的二进制数据(二进制格式)。 + @@ -2021,8 +2010,8 @@ PGresult *PQexecParams(PGconn *conn, paramLengths[] - 指定二进制格式参数的实际数据长度。它对空参数和文本格式参数被忽略。当没有二进制参数时,该数组指针可以为空。 - + 指定二进制格式参数的实际数据长度。对于 null 参数和文本格式参数,该值会被忽略。如果没有二进制参数,数组指针可以为空指针。 + @@ -2030,11 +2019,11 @@ PGresult *PQexecParams(PGconn *conn, paramFormats[] - 指定参数是否为文本(在参数相应的数组项中放一个零)或二进制(在参数相应的数组项中放一个一)。如果该数组指针为空,那么所有参数都会被假定为文本串。 - + 指定参数采用文本格式(在对应数组元素中填入零)还是二进制格式(填入一)。如果数组指针为空指针,则将所有参数视为文本字符串。 + - 以二进制格式传递的值要求后端所期待的内部表示形式的知识。例如,整数必须以网络字节序被传递。传递numeric值要求关于服务器存储格式的知识,正如src/backend/utils/adt/numeric.c::numeric_send()以及src/backend/utils/adt/numeric.c::numeric_recv()中所实现的。 - + 以二进制格式传递值时,需要了解后端所要求的内部表示形式。例如,整数必须以网络字节序传递。传递 numeric 值时,需要了解服务器的存储格式,其实现见 src/backend/utils/adt/numeric.c::numeric_send()src/backend/utils/adt/numeric.c::numeric_recv()。 + @@ -2042,8 +2031,8 @@ PGresult *PQexecParams(PGconn *conn, resultFormat - 指定零来得到文本格式的结果,或者指定一来得到二进制格式的结果(目前没有规定要求以不同格式得到不同的结果列,尽管在底层协议中这是可以实现的)。 - + 指定零以获取文本格式的结果,指定一以获取二进制格式的结果。(目前无法让不同结果列使用不同格式,尽管底层协议支持这样做。) + @@ -2054,8 +2043,8 @@ PGresult *PQexecParams(PGconn *conn, - 相对于的主要优点是参数值可以从命令串中分离,因此避免了冗长的书写、容易发生错误的引用以及转义。 - + 相对于 的主要优点是可以将参数值与命令字符串分开,从而避免繁琐且容易出错的加引号和转义工作。 + 不同,至多允许在给定串中出现一个 SQL 命令(其中可以有分号,但是不能有超过一个非空命令)。这是底层协议的一个限制,但是有助于抵抗 SQL 注入攻击。 @@ -2064,12 +2053,12 @@ PGresult *PQexecParams(PGconn *conn, - 通过 OID 指定参数类型很罗嗦,特别是如果你不愿意将特定的 OID 值硬编码到你的程序中时。不过,即使服务器本身也无法确定参数的类型,你可以避免这样做,或者选择一种与你想要的不同的类型。在 SQL 命令文本中,附加一个显式类型转换给参数符号来表示你将发送什么样的数据类型。例如: + 通过 OID 指定参数类型较为繁琐,尤其是在不希望将具体 OID 值写死在程序中时。不过,即使服务器无法自行确定参数类型,或者推断出的类型与你所需的不同,也可以避免直接指定 OID。在 SQL 命令文本中,为参数符号添加显式类型转换,即可指定要发送的数据类型。例如: SELECT * FROM mytable WHERE x = $1::bigint; - 这强制参数$1被当作bigint,而默认情况下它将被赋予与x相同的类型。当以二进制格式发送参数值时,我们强烈推荐以这种方式或通过指定一个数字类型的 OID 来强制参数类型决定。因为二进制格式比文本格式具有更少的冗余,并且因此服务器将不会有更多机会为你检测一个类型匹配错误。 - +这会强制将参数 $1 当作 bigint,而默认情况下会为它分配与 x 相同的类型。以二进制格式发送参数值时,强烈建议采用这种方式,或直接指定类型的数值 OID,来明确决定参数类型。因为二进制格式的冗余比文本格式更少,服务器发现类型不匹配错误的机会也更少。 + @@ -2090,14 +2079,15 @@ PGresult *PQprepare(PGconn *conn, - 创建一个后面会由执行的预备语句。 - 这个特性允许命令被反复执行而无需每次都进行解析和规划,详见 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + 创建一个预备语句,供随后使用 执行。 + 这个特性允许命令被反复执行而无需每次都进行解析和规划,详见 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + 该函数从query串创建一个名为stmtName的预备语句,该串必须包含一个单一 SQL 命令。 stmtName可以是""来创建一个未命名语句,在这种情况下任何已存在未命名语句将被自动替换。 否则,如果语句名称已经在当前会话中被定义,则是一种错误。如果使用了任何参数,它们在查询中以$1$2等引用。 - nParams是参数的个数,其类型在数组paramTypes[]中被预先指定(当nParams为零时,该数组指针可以是NULL)。 + nParams 是在数组 paramTypes[] 中预先指定了类型的参数数量(当nParams为零时,该数组指针可以是NULL)。 paramTypes[]通过 OID 指定要赋予给参数符号的数据类型。 如果paramTypesNULL或者该数组中任何特定元素为零,服务器会用对待未指定类型的字符串字面量的方式为参数符号推测一种数据类型。 还有,查询能够使用编号高于nParams的参数符号,它们的数据类型也会被自动推测(找出推测出的数据类型的方法见)。 @@ -2105,7 +2095,7 @@ PGresult *PQprepare(PGconn *conn, 正如一样,结果通常是一个PGresult对象,其内容代表服务器端成功或失败。 - 一个空结果表示内存不足或者根本无法发送命令。关于错误的更多信息请见。 + 返回空指针表示内存不足,或者根本无法发送命令。关于错误的更多信息请见 @@ -2132,9 +2122,9 @@ PGresult *PQexecPrepared(PGconn *conn, 类似于, - 但要执行的命令是通过指定先前准备好的语句来指定,而不是提供查询字符串。 - 此功能允许重复使用的命令只被解析和计划一次,而不是每次执行时都要进行。 - 该语句必须在当前会话中先前准备好。 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + 但它通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。 + 此功能使重复使用的命令只需解析和规划一次,而不必在每次执行时都进行这些工作。 + 该语句必须事先在当前会话中创建为预备语句。 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 参数与相同,只是给出了预备语句的名称而不是查询字符串, @@ -2148,22 +2138,22 @@ PGresult *PQexecPrepared(PGconn *conn, - 提交请求以获取有关指定准备好的语句的信息,并等待完成。 + 提交请求以获取有关指定预备语句的信息,并等待完成。 PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - 允许应用程序获取关于先前准备的语句的信息。 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + 允许应用程序获取关于先前创建的预备语句的信息。 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 stmtName可以是""NULL来引用 - 未命名的语句,否则必须是现有准备好的语句的名称。成功时,返回一个 + 未命名的语句,否则必须是现有预备语句的名称。成功时,返回一个 状态为PGRES_COMMAND_OKPGresult。 函数可以应用于此 - PGresult以获取有关准备语句参数的信息, + PGresult以获取有关预备语句参数的信息, 函数等提供有关语句的结果列(如果有)的信息。 @@ -2175,15 +2165,15 @@ PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - 提交请求以获取有关指定门户的信息,并等待完成。 + 提交请求以获取有关指定 portal 的信息,并等待完成。 PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - 允许应用程序获取有关先前创建的 portal 的信息。 - (libpq不直接提供对 portal 的访问,但你可以使用此函数检查通过DECLARE CURSOR SQL 命令创建的游标的属性。) 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + 允许应用程序获取先前创建的 portal 的信息。(libpq 不提供对 portal 的直接访问,但可以用此函数检查通过 DECLARE CURSOR SQL 命令创建的游标的属性。) 仅支持使用协议 3.0 及更高版本的连接;使用协议 2.0 时会失败。 + portalName可以是""NULL来引用未命名的 portal, @@ -2196,7 +2186,9 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - PGresultPGresult结构体封装服务器返回的结果。libpq应用程序的开发者应注意保持PGresult的抽象性。请使用下面的访问函数获取PGresult的内容。避免直接引用PGresult结构体的字段,因为这些字段以后可能改变。 + + PGresultPGresult 结构体封装服务器返回的结果。编写 libpq 应用程序时,应注意维护 PGresult 的抽象。请使用下述访问函数获取 PGresult 的内容。避免直接引用 PGresult 结构体的字段,因为这些字段将来可能改变。 + PQresultStatusPQresultStatus @@ -2295,7 +2287,7 @@ ExecStatusType PQresultStatus(const PGresult *res); PGRES_SINGLE_TUPLE - PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单一行模式时发生(见)。 + PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单行模式时发生(见)。 @@ -2313,12 +2305,11 @@ ExecStatusType PQresultStatus(const PGresult *res); - 将返回的枚举转换成描述状态编码的字符串常量。调用者不应该释放结果。 - + 将 返回的枚举值转换为描述该状态码的字符串常量。调用者不应释放此结果。 char *PQresStatus(ExecStatusType status); - + @@ -2327,12 +2318,12 @@ char *PQresStatus(ExecStatusType status); - 返回与该命令相关的错误消息,如果有错误则会返回一个空字符串。 + 返回与命令关联的错误消息;如果没有错误,则返回空字符串。 char *PQresultErrorMessage(const PGresult *res); - 如果有一个错误,被返回的字符串将包含一个收尾的新行。调用者不应该直接释放结果。它将在相关的PGresult句柄被传递给之后被释放。 - +如果发生了错误,返回的字符串会以换行符结尾。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 + 紧跟着一个调用,(在连接上)将返回与相同的字符串(在结果上)。 @@ -2347,11 +2338,15 @@ char *PQresultErrorMessage(const PGresult *res); PQresultVerboseErrorMessagePQresultVerboseErrorMessage - 返回与PGresult对象关联的错误消息的重新格式化版本。 + + 返回与 PGresult 对象关联的错误消息的重新格式化版本。 + char *PQresultVerboseErrorMessage(const PGresult *res, PGVerbosity verbosity, PGContextVisibility show_context); -某些情况下,客户端可能希望取得之前报告的错误的更详细版本。可以满足这一需求:它计算以下函数本应生成的消息:,假设在生成给定的PGresult时,连接已经采用指定的详细程度设置。如果PGresult不是错误结果,则改为报告PGresult is not an error result。返回的字符串包含末尾换行符。 + +有时客户端希望获取先前报告过的错误的更详细版本。 可满足这一需求:它按指定的详细程度设置重新生成消息。假如在生成给定 PGresult 时,连接已经采用这些设置,那么 返回的就会是这条消息。如果 PGresult 不是错误结果,则改为报告 PGresult is not an error result。返回的字符串以换行符结尾。 + 和大部分从PGresult中提取数据的其他函数不同,这个函数的结果是一个全新分配的字符串。调用者在不需要这个字符串以后,必须使用PQfreemem()释放它。 @@ -2367,22 +2362,19 @@ char *PQresultVerboseErrorMessage(const PGresult *res, PQresultErrorFieldPQresultErrorField - 返回一个错误报告的一个域。 + 返回错误报告中的单个字段。 char *PQresultErrorField(const PGresult *res, int fieldcode); - fieldcode是一个错误域标识符,见下列符号。 - 如果PGresult不是一个错误或者警告结果或者不包括指定域,会返回NULL。 - 域通常不包括一个收尾的新行。调用者不应该直接释放结果。 - 它将在相关的PGresult句柄被传递给之后被释放。 - +fieldcode 是错误字段标识符,参见下文列出的符号。如果 PGresult 不是错误或警告结果,或者不包含指定字段,则返回 NULL。字段值通常不含末尾换行符。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 + 可以使用以下字段代码: PG_DIAG_SEVERITY - 严重性。域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 @@ -2391,17 +2383,17 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_SEVERITY_NONLOCALIZED - 域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY域相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 版本以后产生的报告中。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY字段相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 及更高版本产生的报告中。 PG_DIAG_SQLSTATEerror codeslibpq + >错误码libpq - 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个域无法被本地化,并且总是存在。 + 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个字段无法被本地化,并且总是存在。 @@ -2428,7 +2420,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_MESSAGE_HINT - 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是铁的事实。可能有多行。 + 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是确切事实。可能有多行。 @@ -2446,7 +2438,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_INTERNAL_POSITION - 这被定义为与PG_DIAG_STATEMENT_POSITION域相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个域出现时,PG_DIAG_INTERNAL_QUERY域将总是出现。 + 这被定义为与PG_DIAG_STATEMENT_POSITION字段相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个字段出现时,PG_DIAG_INTERNAL_QUERY字段将总是出现。 @@ -2464,7 +2456,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONTEXT - 指示错误发生的环境。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 + 指示错误发生的上下文。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 @@ -2482,7 +2474,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_TABLE_NAME - 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名域)。 + 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名字段)。 @@ -2491,7 +2483,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_COLUMN_NAME - 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名域来标识该表)。 + 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名字段来标识该表)。 @@ -2500,7 +2492,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_DATATYPE_NAME - 如果错误与一个特定数据类型相关,这里是该数据了行的名字(该数据类型的模式名参考模式名域)。 + 如果错误与一个特定数据类型相关,这里是该数据类型的名字(该数据类型的模式名参考模式名字段)。 @@ -2509,7 +2501,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONSTRAINT_NAME - 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的域(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 + 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的字段(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 @@ -2545,12 +2537,12 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); - 用于模式名、表名、列名、数据类型名和约束名的域只提供给有限的错误类型,见。不要假定任何这些域的存在保证另一个域的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些域。同样地,不要假定这些域代表当前数据库中同类的对象。 + 用于模式名、表名、列名、数据类型名和约束名的字段只提供给有限的错误类型,见。不要假定任何这些字段的存在保证另一个字段的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些字段。同样地,不要假定这些字段代表当前数据库中现存的对象。 - 客户端负责格式化显示信息来迎合它的需要,特别是根据需要打断长的行。出现在错误消息域中的新行字符应该被当作分段而不是换行。 + 客户端负责按自身需要格式化所显示的信息,尤其应在需要时将长行折行。错误消息字段中的换行符应当视为段落分隔,而非行分隔。 libpq 内部产生的错误包含严重性和主要消息,但通常没有其他字段。使用 3.0 之前协议的服务器返回的错误包含严重性和主要消息,有时还包含详细消息,但没有其他字段。 @@ -2564,10 +2556,12 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PQclearPQclear - 释放与PGresult关联的存储空间。每个命令结果都应通过在不再需要结果时将其释放。 + + 释放与 PGresult 关联的存储空间。每个命令结果在不再需要时都应通过 释放。 + void PQclear(PGresult *res); - + 你可以在需要时一直保留PGresult对象;它不会在你发出新命令时消失,甚至在关闭连接后也不会消失。要销毁它,你必须调用。否则应用程序会发生内存泄漏。 @@ -2575,15 +2569,15 @@ void PQclear(PGresult *res); - + 检索查询结果信息 - 这些函数被用来从一个代表成功查询结果(也就是状态为PGRES_TUPLES_OK或者PGRES_SINGLE_TUPLE)的PGresult对象中抽取信息。它们也可以被用来从一个成功的 Describe 操作中抽取信息:一个 Describe 的结果具有和该查询被实际执行所提供的完全相同的列信息,但是它没有行。对于其他状态值的对象,这些函数会认为结果具有零行和零列。 - + 这些函数用于从表示成功查询结果的 PGresult 对象中提取信息,即状态为 PGRES_TUPLES_OKPGRES_SINGLE_TUPLE 的对象。它们也可用于提取成功 Describe 操作的结果信息:Describe 结果包含的列信息与实际执行查询时相同,但行数为零。对于其他状态值的对象,这些函数会将结果视为零行、零列。 + @@ -2610,7 +2604,7 @@ int PQntuples(const PGresult *res); - 返回查询结果中每一行的列(域)数。 + 返回查询结果中每一行的列(字段)数。 int PQnfields(const PGresult *res); @@ -2626,7 +2620,7 @@ int PQnfields(const PGresult *res); - 返回与给定列号相关联的列名。列号从 0 开始。调用者不应该直接释放该结果。它将在相关的PGresult句柄被传递给之后被释放。 + 返回给定列号对应的列名。列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 char *PQfname(const PGresult *res, int column_number); @@ -2658,11 +2652,11 @@ int PQfnumber(const PGresult *res, - 给定的名称被视作一个 SQL 命令中的一个标识符,也就是说,除非被双引号引用,它是小写形式的。例如,给定一个 SQL 命令: + 给定名称按 SQL 命令中的标识符处理,即除非用双引号引用,否则会转换为小写。例如,对于以下 SQL 命令生成的查询结果: SELECT 1 AS FOO, 2 AS "BAR"; - 我们将得到结果: +会得到以下结果: PQfname(res, 0) foo PQfname(res, 1) BAR @@ -2680,7 +2674,7 @@ PQfnumber(res, "\"BAR\"") 1 - 返回给定列从中取出的表的 OID。列号从 0 开始。 + 返回给定列所取自的表的 OID。列号从 0 开始。 Oid PQftable(const PGresult *res, int column_number); @@ -2689,7 +2683,9 @@ Oid PQftable(const PGresult *res, 如果列号超出范围、指定的列不是对表列的简单引用,或者使用 3.0 之前的协议,则返回 InvalidOid。可以查询系统表 pg_class,确定所引用的具体表。 - 包含 libpq 头文件后,将定义类型 Oid 和常量 InvalidOid。它们都属于某种整数类型。 + + 包含 libpq 头文件后,将定义类型 Oid 和常量 InvalidOid。它们都属于某种整数类型。 + @@ -2698,7 +2694,7 @@ Oid PQftable(const PGresult *res, - 返回构成指定查询结果列的列(在其表中)的列号。查询结果列号从 0 开始,但是表列具有非零编号。 + 返回指定查询结果列所对应的表列在表中的列号。查询结果的列号从 0 开始,而表列的编号非零。 int PQftablecol(const PGresult *res, int column_number); @@ -2716,7 +2712,7 @@ int PQftablecol(const PGresult *res, - 返回指示给定列格式的格式编码。列号从 0 开始。 + 返回表示给定列格式的格式代码。列号从 0 开始。 int PQfformat(const PGresult *res, int column_number); @@ -2724,7 +2720,7 @@ int PQfformat(const PGresult *res, - 格式代码零指示文本数据表示,而格式代码一表示二进制表示(其他代码被保留用于未来的定义)。 + 格式代码零表示文本数据,格式代码一表示二进制数据。(其他代码保留供将来定义。) @@ -2752,7 +2748,7 @@ Oid PQftype(const PGresult *res, - 返回与给定列号相关联的列的修饰符类型。列号从 0 开始。 + 返回与给定列号相关联的列的类型修饰符。列号从 0 开始。 int PQfmod(const PGresult *res, int column_number); @@ -2760,7 +2756,7 @@ int PQfmod(const PGresult *res, - 修饰符值的解释是与类型相关的,它们通常指示精度或尺寸限制。值 -1 被用来指示没有信息可用。大部分的数据类型不适用修饰符,在那种情况中值总是 -1。 + 修饰符值的含义由数据类型决定,通常表示精度或大小限制。值 -1 表示没有可用信息。大多数数据类型不使用修饰符,此时该值始终为 -1。 @@ -2772,7 +2768,7 @@ int PQfmod(const PGresult *res, - 返回与给定列号相关的列的尺寸(以字节计)。列号从 0 开始。 + 返回给定列号对应列的大小,以字节计。列号从 0 开始。 int PQfsize(const PGresult *res, int column_number); @@ -2780,7 +2776,7 @@ int PQfsize(const PGresult *res, - 返回在一个数据库行中为这个列分配的空间,换句话说是服务器对该数据类型的内部表示的尺寸(因此,它对客户端并不是真地非常有用)。一个负值指示该数据类型是变长的。 + 返回数据库行中为该列分配的空间,即服务器内部表示该数据类型所需的大小。(因此,它对客户端用处不大。)负值表示该数据类型是变长类型。 @@ -2799,8 +2795,7 @@ int PQbinaryTuples(const PGresult *res); - 这个函数已经被废弃(除了与COPY一起使用),因为一个单一PGresult可以在某些列中包含文本数据而且在另一些列中包含二进制数据。 - 要更好。只有结果的所有列是二进制(格式 1)时才返回 1。 + 此函数已弃用(与 COPY 配合使用的情况除外),因为单个 PGresult 可能在部分列中包含文本数据,而在其他列中包含二进制数据。推荐使用 。只有结果中的所有列都采用二进制格式(格式 1)时, 才返回 1。 @@ -2812,8 +2807,7 @@ int PQbinaryTuples(const PGresult *res); - 返回一个PGresult的一行的单一域值。行和列号从 0 开始。调用者不应该直接释放该结果。 - 它将在相关的PGresult句柄被传递给之后被释放。 + 返回 PGresult 中某一行的单个字段值。行号和列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 char *PQgetvalue(const PGresult *res, int row_number, @@ -2822,15 +2816,15 @@ char *PQgetvalue(const PGresult *res, - 对于文本格式的数据,返回的值是该域值的一种空值结束的字符串表示。对于二进制格式的数据,该值是由该数据类型的typsendtypreceive函数决定的二进制表示(在这种情况下该值实际上也跟随着一个零字节,但是这通常没有用处,因为该值很可能包含嵌入的空)。 + 对于文本格式的数据, 返回字段值的字符串表示,以零字节结尾。对于二进制格式的数据,返回值采用该数据类型的 typsendtypreceive 函数所决定的二进制表示。(这种情况下,值后面实际上也有一个零字节,但通常没有用处,因为值本身很可能包含零字节。) - 如果该域值为空,则返回一个空串。关于区分空值和空字符串值请见。 + 如果字段值为 null,则返回空字符串。关于如何区分 null 值与空字符串值,参见 - 返回的指针指向作为PGresult结构体一部分的存储。我们不应该修改它指向的数据,并且如果要在超过PGresult结构体本身的生命期之外使用它,我们必须显式地把该数据拷贝到其他存储中。 + 返回的指针指向属于 PGresult 结构体的存储空间。不应修改它所指向的数据;如果需要在 PGresult 结构体的生命周期结束后继续使用这些数据,就必须显式地将数据复制到其他存储空间。 @@ -2839,12 +2833,12 @@ char *PQgetvalue(const PGresult *res, PQgetisnullPQgetisnullnull valuein libpq + >null 值libpq 中的 - 测试一个域是否为空值。行号和列号从 0 开始。 + 检查字段是否为 null 值。行号和列号从 0 开始。 int PQgetisnull(const PGresult *res, int row_number, @@ -2853,7 +2847,7 @@ int PQgetisnull(const PGresult *res, - 如果该域是空,这个函数返回 1。如果它包含一个非空值,则返回 0(注意将为一个空域返回一个空串,不是一个空指针)。 + 如果字段为 null,此函数返回 1;如果包含非 null 值,则返回 0。(注意,对于 null 字段, 返回空字符串,而非空指针。) @@ -2865,7 +2859,7 @@ int PQgetisnull(const PGresult *res, - 返回一个域值的真实长度,以字节计。行号和列号从 0 开始。 + 返回字段值的实际长度,以字节计。行号和列号从 0 开始。 int PQgetlength(const PGresult *res, int row_number, @@ -2874,9 +2868,7 @@ int PQgetlength(const PGresult *res, - 这是特定数据值的真实数据长度,也就是指向的对象的尺寸。 - 对于文本数据格式,这和strlen()相同。对于二进制格式这是基本信息。 - 注意我们应该依赖于来得到真值的数据长度。 + 这是该数据值的实际数据长度,即 所指对象的大小。对于文本格式的数据,它与 strlen() 的结果相同。对于二进制格式,这是必不可少的信息。注意,不应依赖 来获取实际数据长度。 @@ -2926,29 +2918,29 @@ Oid PQparamtype(const PGresult *res, int param_number); - 将所有的行打印到指定的输出流,以及有选择地将列名打印到指定的输出流。 + 将所有行输出到指定的输出流,并可选择输出列名。 void PQprint(FILE *fout, /* 输出流 */ const PGresult *res, const PQprintOpt *po); typedef struct { - pqbool header; /* 打印输出域标题和行计数 */ - pqbool align; /* 填充对齐域 */ - pqbool standard; /* 旧的格式 */ + pqbool header; /* 打印输出字段标题和行数 */ + pqbool align; /* 填充并对齐字段 */ + pqbool standard; /* 旧的简陋格式 */ pqbool html3; /* 输出 HTML 表格 */ - pqbool expanded; /* 扩展表格 */ - pqbool pager; /* 如果必要为输出使用页 */ - char *fieldSep; /* 域分隔符 */ + pqbool expanded; /* 展开表格 */ + pqbool pager; /* 需要时使用分页器输出 */ + char *fieldSep; /* 字段分隔符 */ char *tableOpt; /* 用于 HTML 表格元素的属性 */ char *caption; /* HTML 表格标题 */ - char **fieldName; /* 替换域名称的空终止数组 */ + char **fieldName; /* 以空指针结尾的替换字段名数组 */ } PQprintOpt; - 这个函数以前被psql用来打印查询结果,但是现在不是这样了。注意它假定所有的数据都是文本格式。 + psql 以前用此函数打印查询结果,现在已不再使用。注意,此函数假定所有数据都是文本格式。 @@ -2993,7 +2985,9 @@ char *PQcmdTuples(PGresult *res); - 此函数返回一个字符串,其中包含产生该 PGresultSQL 语句所影响的行数。此函数只能在执行 SELECTCREATE TABLE ASINSERTUPDATEDELETEMOVEFETCHCOPY 语句之后使用,也可以在对包含 INSERTUPDATEDELETE 语句的预备查询执行 EXECUTE 之后使用。如果产生 PGresult 的是其他命令, 将返回空字符串。调用者不应直接释放返回值;将关联的 PGresult 句柄传给 时,它会被释放。 + + 此函数返回一个字符串,其中包含产生该 PGresultSQL 语句所影响的行数。此函数只能在执行 SELECTCREATE TABLE ASINSERTUPDATEDELETEMOVEFETCHCOPY 语句之后使用,也可以在对包含 INSERTUPDATEDELETE 语句的预备查询执行 EXECUTE 之后使用。如果产生 PGresult 的是其他命令, 将返回空字符串。调用者不应直接释放返回值;当关联的 PGresult 句柄被传给 时,返回值会被释放。 + @@ -3004,7 +2998,7 @@ char *PQcmdTuples(PGresult *res); - 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDin libpq。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid。 + 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDlibpq 中的。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid Oid PQoidValue(const PGresult *res); @@ -3019,7 +3013,7 @@ Oid PQoidValue(const PGresult *res); - 这个函数已经被取代,并且不是线程安全的。它返回包含被插入行的 OID 的一个字符串,而返回 OID 值。 + 此函数不是线程安全的,现已弃用,推荐改用 。它返回包含插入行 OID 的字符串,而 返回 OID 值。 char *PQoidStatus(const PGresult *res); @@ -3036,7 +3030,7 @@ char *PQoidStatus(const PGresult *res); 转义字符串 - in libpq + libpq 中的 @@ -3054,17 +3048,13 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); 为了让一个字符串可用于 SQL 命令,会对它进行转义。 - 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜线)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 + 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜杠)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 执行这种操作。 - 返回一个str参数的已被转义版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - 返回字符串中的所有特殊字符都会被替换,这样它们就能被PostgreSQL字符串字面量解析器正确处理。 - 结果中也会附加一个终止零字节,并包含包围PostgreSQL字符串字面量所需的单引号。 - + 返回 str 参数的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便 PostgreSQL 字符串字面量解析器正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号包含在结果字符串中。 + 发生错误时,返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -3078,7 +3068,7 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); - 注意,当一个数据值被作为或其兄弟例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 + 注意,当一个数据值被作为或相关例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 @@ -3096,15 +3086,12 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - 转义一个要用作 SQL 标识符的字符串,例如表名、列名或函数名。当一个用户提供的标识符可能包含被 SQL 解析器解释为标识符一部分的特殊字符时,或者当该标识符可能包含大小写形式应该被保留的大写字符时,这个函数很有用。 - + 对字符串进行转义,使其可用作 SQL 标识符,例如表名、列名或函数名。当用户提供的标识符可能包含未经转义就不会被 SQL 解析器视为标识符一部分的特殊字符,或包含需要保留大小写的大写字符时,此函数很有用。 + - 返回一个str参数的已被转义为 SQL 标识符的版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - 返回串中的所有特殊字符都被替换掉,这样它们能被作为一个 SQL 标识符正确地处理。还会加上一个终止零字节。返回串也将被双引号包围。 - + 返回 str 参数作为 SQL 标识符的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,必须使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便正确地作为 SQL 标识符处理。还会添加一个末尾零字节,并用双引号包围返回的字符串。 + 发生错误时,返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -3113,7 +3100,7 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - 与字符串一样,要阻止 SQL 注入攻击,当从一个不可信的来源接收到 SQL 标识符时,它们必须被转义。 + 与字符串字面量一样,为防止 SQL 注入攻击,从不可信来源接收到的 SQL 标识符必须经过转义。 @@ -3134,18 +3121,12 @@ size_t PQescapeStringConn(PGconn *conn, - 转义字符串,它很像。 - 与不一样的是,调用者负责提供一个合适尺寸的缓冲区。 - 此外,不产生必须包围PostgreSQL字符串的单引号。 - 它们应该在结果要插入的 SQL 命令中提供。参数from指向要被转义的串的第一个字符,并且length参数给出了这个串中的字节数。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - to应当指向一个缓冲区,它能够保持至少比length值的两倍还要多至少一个字节,否则该行为是未被定义的。 - 如果tofrom串重叠,行为也是未被定义的。 - + 对字符串字面量进行转义,与 类似。与 不同,调用者需要提供大小合适的缓冲区。此外, 不会生成包围 PostgreSQL 字符串字面量所需的单引号;应在包含转义结果的 SQL 命令中提供这些引号。from 参数指向待转义字符串的首字符,length 参数给出该字符串的字节数。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)to 必须指向一个缓冲区,其容量至少为 length 的两倍加一个字节,否则行为未定义。如果 tofrom 字符串重叠,行为同样未定义。 + - 如果error参数不是NULL,那么成功时*error被设置为零,错误时设置为非零。当前唯一可能的错误情况涉及源串中非法的多字节编码。错误时仍然会产生输出串,但是可以预期服务器将认为它是畸形的并且拒绝它。在发生错误时,一个合适的消息被存储在conn对象中,不管error是不是NULL。 - + 如果 error 参数不是 NULL,则成功时将 *error 设为零,出错时设为非零。目前唯一可能的错误是源字符串中存在无效的多字节编码。出错时仍会生成输出字符串,但预计服务器会因其格式错误而拒绝它。发生错误时,无论 error 是否为 NULL,都会在 conn 对象中保存相应消息。 + 返回写到to的字节数,不包括终止的零字节。 @@ -3160,21 +3141,19 @@ size_t PQescapeStringConn(PGconn *conn, - 是一个更老的被废弃的版本。 + 的旧版本,现已弃用。 size_t PQescapeString (char *to, const char *from, size_t length); - + - 之间的唯一区别是不需要PGconnerror参数。 - 正因为如此,它不能基于连接属性(例如字符编码)调整它的行为并且因此它可能给出错误的结果。还有,它没有方法报告错误情况。 - + 与 唯一的区别是, 不接受 PGconnerror 参数。因此,它无法根据连接属性(例如字符编码)调整行为,可能给出错误的结果。此外,它也无法报告错误情况。 + - 可以在一次只使用一个PostgreSQL连接的客户端程序中安全地使用(在这种情况下它可以在现象后面找出它需要知道的东西)。 - 在其他环境中它是一个安全性灾难并且应该用来避免。 - + 可以在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。在其他情形下,它存在安全隐患,应改用 。 + @@ -3185,7 +3164,7 @@ size_t PQescapeString (char *to, const char *from, size_t length); - 把要用于一个 SQL 命令的二进制数据用类型bytea转义。和一样,只有在将数据直接插入到一个 SQL 命令串时才使用它。 + 对二进制数据进行转义,使其能够在 SQL 命令中用作 bytea 类型的值。与 一样,这仅用于将数据直接插入 SQL 命令字符串的情况。 unsigned char *PQescapeByteaConn(PGconn *conn, const unsigned char *from, @@ -3200,14 +3179,11 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - from参数指向要被转义的串的第一个字节,并且from_length参数给出这个二进制串中的字节数(一个终止的零字节是不需要的也是不被计算的)。to_length参数指向一个将保持生成的已转义串长度的变量。这个结果串长度包括结果的终止零字节。 + from 参数指向待转义字符串的首字节,from_length 参数给出该二进制字符串的字节数。(末尾零字节既不需要,也不计入长度。)to_length 参数指向用于保存转义后字符串长度的变量。该结果字符串长度包含结果末尾的零字节。 - 返回一个from参数的已被转义为二进制串的版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 返回串中的所有特殊字符都被替换掉,这样它们能被PostgreSQL的字符串解析器以及bytea输入函数正确地处理。 - 还会加上一个终止零字节。不是结果串一部分的PostgreSQL字符串必须被单引号包围。 + 返回 from 参数所指二进制字符串的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。返回字符串中的所有特殊字符都已替换,以便 PostgreSQL 字符串字面量解析器和 bytea 输入函数正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号不包含在结果字符串中。 @@ -3223,7 +3199,7 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - 是一个更老的被废弃的版本。 + 的旧版本,现已弃用。 unsigned char *PQescapeBytea(const unsigned char *from, size_t from_length, @@ -3232,9 +3208,7 @@ unsigned char *PQescapeBytea(const unsigned char *from, - 与的唯一区别是不用一个PGconn参数。 - 正因为这样,只能在一次只使用一个PostgreSQL连接的客户端程序中安全地使用(在这种情况下它可以在现象后面找出它需要知道的东西)。 - 如果在有多个数据库连接的程序中使用,它可能给出错误的结果(在那种情况下使用)。 + 与 唯一的区别是, 不接受 PGconn 参数。因此, 只能在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。如果在使用多个数据库连接的程序中使用,它可能给出错误的结果(此时应使用 )。 @@ -3300,32 +3274,25 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - 总是收集命令的整个结果,把它缓存在一个单一的PGresult中。虽然这简化了应用的错误处理逻辑,它对于包含很多行的结果并不现实。 - + 总是收集命令的完整结果,并将其缓存在单个 PGresult 中。这简化了应用程序的错误处理逻辑,但对于包含大量行的结果,可能不切实际。 + - 如果应用程序不希望受到这些限制,可以改用构成的底层函数:。此外,还有, - , - , - ,以及,它们可以与配合使用,分别实现以下函数的功能:, - , - , - ,以及 + + 如果应用程序不希望受到这些限制,可以改用构成 的底层函数:。此外, 可以与 配合使用,分别实现 的功能。 + PQsendQueryPQsendQuery - 提交一个命令到服务器,而不等待结果。 - 如果成功发送命令,则返回1,如果失败则返回0(在这种情况下,使用获取更多关于失败的信息)。 + 向服务器提交命令,不等待结果。命令发送成功时返回 1,否则返回 0(此时可使用 获取更多失败信息)。 int PQsendQuery(PGconn *conn, const char *command); - - 成功调用后,调用一次或多次来获取结果。 - 在返回空指针,表示命令执行完成之前,无法再次调用(在同一连接上)。 +成功调用 后,应调用 一次或多次来获取结果。在 返回空指针、表明命令已完成之前,不得在同一连接上再次调用 @@ -3334,7 +3301,9 @@ int PQsendQuery(PGconn *conn, const char *command); PQsendQueryParamsPQsendQueryParams - 向服务器提交命令及独立指定的参数,不等待结果。 + + 向服务器提交命令及独立指定的参数,不等待结果。 + int PQsendQueryParams(PGconn *conn, const char *command, int nParams, @@ -3343,7 +3312,9 @@ int PQsendQueryParams(PGconn *conn, const int *paramLengths, const int *paramFormats, int resultFormat); -该函数等价于,但查询参数可以与查询字符串分开指定。函数参数的处理方式与相同。与一样,它不能用于协议 2.0 的连接,并且查询字符串中只允许包含一条命令。 + +该函数等价于 ,但查询参数可以与查询字符串分开指定。函数参数的处理方式与 相同。与 一样,它不能用于协议 2.0 的连接,并且查询字符串中只允许包含一条命令。 + @@ -3351,13 +3322,17 @@ int PQsendQueryParams(PGconn *conn, PQsendPreparePQsendPrepare - 发送按给定参数创建预备语句的请求,不等待完成。 + + 发送按给定参数创建预备语句的请求,不等待完成。 + int PQsendPrepare(PGconn *conn, const char *stmtName, const char *query, int nParams, const Oid *paramTypes); -这是的异步版本:请求发送成功时返回 1,否则返回 0。调用成功后,再调用,确定服务器是否成功创建了预备语句。函数参数的处理方式与相同。与一样,它不能用于协议 2.0 的连接。 + +这是 的异步版本:请求发送成功时返回 1,否则返回 0。调用成功后,再调用 ,确定服务器是否成功创建了预备语句。函数参数的处理方式与 相同。与 一样,它不能用于协议 2.0 的连接。 + @@ -3365,7 +3340,9 @@ int PQsendPrepare(PGconn *conn, PQsendQueryPreparedPQsendQueryPrepared - 发送使用给定参数执行预备语句的请求,不等待结果。 + + 发送使用给定参数执行预备语句的请求,不等待结果。 + int PQsendQueryPrepared(PGconn *conn, const char *stmtName, int nParams, @@ -3373,7 +3350,9 @@ int PQsendQueryPrepared(PGconn *conn, const int *paramLengths, const int *paramFormats, int resultFormat); -该函数类似于,但通过指定先前已准备好的语句的名称来确定要执行的命令,而不是提供查询字符串。函数参数的处理方式与相同。与一样,它不能用于协议 2.0 的连接。 + +该函数类似于 ,但通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。函数参数的处理方式与 相同。与 一样,它不能用于协议 2.0 的连接。 + @@ -3411,13 +3390,7 @@ PGresult *PQgetResult(PGconn *conn); - 必须重复调用直到返回空指针,表示命令已完成。 - (如果在没有活动命令时调用, - 将立即返回空指针。)每个非空结果从 - 应该使用先前描述的相同PGresult访问器函数进行处理。 - 完成后不要忘记使用释放每个结果对象。请注意, - 仅在有命令处于活动状态且必要的响应数据尚未被 - 读取时才会阻塞。 + 必须反复调用 ,直到它返回空指针,表明命令已经完成。(如果当前没有正在执行的命令,调用 会立即返回空指针。)对于 返回的非空指针,应使用前文介绍的 PGresult 访问函数处理相应结果。使用完毕后,不要忘记调用 释放每个结果对象。注意,只有存在正在执行的命令,且所需响应数据尚未被 读取时, 才会阻塞。 @@ -3430,38 +3403,37 @@ PGresult *PQgetResult(PGconn *conn); - + - 使用解决了的一个问题:如果一个命令字符串包含多个SQL命令,这些命令的结果可以被个别地获得(顺便说一句:这样就允许一种简单的重叠处理形式, 客户端可以处理一个命令的结果,而同时服务器可以继续处理同一命令字符串中后面的查询)。 - + 使用 可以解决 的一个问题:如果命令字符串包含多个 SQL 命令,就能分别获取这些命令的结果。(这也支持一种简单的重叠处理方式:客户端可以处理某条命令的结果,同时服务器继续处理同一命令字符串中后面的查询。) + - 可以被获得的另一种常常想要的特性是一次从大型结果中检索一行。这会在中讨论。 - + 使用 还可以实现另一项常见需求:从大型查询结果中一次读取一行。详见 。 + - 仅仅调用仍会使客户端阻塞,直到服务器完成下一条SQL命令。可以通过正确使用另外两个函数来避免这种情况: + + 仅仅调用 仍会使客户端阻塞,直到服务器完成下一条 SQL 命令。可以通过正确使用另外两个函数来避免这种情况: + PQconsumeInputPQconsumeInput - 如果有来自服务器的输入可用,则使用之。 + 如果服务器有可读取的输入,则读取这些输入。 int PQconsumeInput(PGconn *conn); - 通常返回 1 表明没有错误,而返回 0 表明有某种麻烦发生(此时可以用)。 - 注意该结果并不表明是否真正收集了任何输入数据。在调用之后,应用可以检查和/或PQnotifies来看看它们的状态是否改变。 + 通常返回 1,表示没有错误;发生问题时则返回 0(此时可查看 )。注意,返回值并不说明是否实际读取了输入数据。调用 后,应用程序可以检查 和/或 PQnotifies,以确定其状态是否发生变化。 - 即使应用还不准备处理一个结果或通知,也可以被调用。 - 这个函数将读取可用的数 据并且把它保存在一个缓冲区中,从而导致一个select()的读准备好指示消失。 - 因此应用可以使用立即清除select()条件,并且在空闲时再检查结果。 + 即使应用程序尚未准备好处理结果或通知,也可以调用 。此函数会读取可用数据并将其保存在缓冲区中,从而清除 select() 的可读就绪指示。因此,应用程序可以用 立即清除 select() 的就绪条件,随后在合适的时候检查结果。 @@ -3483,22 +3455,20 @@ int PQisBusy(PGconn *conn); - + - 一个使用这些函数的典型应用将有一个主循环,在主循环中会使用select()poll()等待所有它必须响应的情况。 - 其中之一将是来自服务器的输入可用,对select()来说意味着标识的文件描述符上有可读的数据。 - 当主循环检测到输入准备好时,它将调用读取输入。 - 然后它可以调用,如果返回假(0)则接着调用。 - 它还可以调用PQnotifies检测NOTIFY消息(见)。 - + 使用这些函数的典型应用程序会在主循环中通过 select()poll() 等待需要响应的各种条件。其中一个条件是服务器有可读取的输入;对于 select(),这意味着 标识的文件描述符上有可读数据。主循环检测到输入就绪时,应调用 读取输入,然后调用 。如果 返回假(0),就可以接着调用 。还可以调用 PQnotifies 检测 NOTIFY 消息(见 )。 + 一个使用/的客户端也可以尝试取消一个正在被服务器处理的命令,见。 但是,不管的返回值是什么,应用都必须继续使用进行正常的结果读取序列。一次成功的取消只会导致命令比不取消时更快终止。 - 使用上述函数可以避免在等待数据库服务器输入时阻塞。不过,应用程序仍可能在等待向服务器发送输出时阻塞。这种情况较少见,但发送很长的 SQL 命令或数据值时可能发生。(如果应用程序通过COPY IN发送数据,发生的可能性则大得多。)为了防止这种情况,实现完全非阻塞的数据库操作,可以使用以下附加函数。 + + 使用上述函数可以避免在等待数据库服务器输入时阻塞。不过,应用程序仍可能在等待向服务器发送输出时阻塞。这种情况较少见,但发送很长的 SQL 命令或数据值时可能发生。(如果应用程序通过 COPY IN 发送数据,发生的可能性则大得多。)为了防止这种情况,实现完全非阻塞的数据库操作,可以使用以下附加函数。 + PQsetnonblockingPQsetnonblocking @@ -3516,11 +3486,7 @@ int PQsetnonblocking(PGconn *conn, int arg); - 在非阻塞状态下,成功调用、 - 、 - 不会阻塞; - 它们的更改将存储在本地输出缓冲区中,直到刷新为止。 - 不成功的调用将返回错误,必须重试。 + 在非阻塞状态下,成功调用 不会阻塞;产生的数据保存在本地输出缓冲区中,等待发送。失败的调用会返回错误,必须重试。 @@ -3551,9 +3517,7 @@ int PQisnonblocking(const PGconn *conn); - 尝试将任何排队的输出数据刷新到服务器。如果成功(或发送队列为空),则返回0; - 如果由于某种原因失败,则返回-1;如果尚未能够发送发送队列中的所有数据(只有在连接为非阻塞时才会发生此情况), - 则返回1。 + 尝试将发送队列中的输出数据发送到服务器。成功(或发送队列为空)时返回 0;因某种原因失败时返回 -1;如果尚未能发送队列中的全部数据,则返回 1(这种情况只可能发生在非阻塞连接上)。 int PQflush(PGconn *conn); @@ -3561,15 +3525,11 @@ int PQflush(PGconn *conn); - + - 在一个非阻塞连接上发送任何命令或者数据之后,要调用。 - 如果它返回 1,就要等待套接字变成读准备好或写准备好。如果它变为写准备好,应再次调用。 - 如果它变为读准备好,则应先调用,然后再调用。 - 一直重复直到返回 0(有必要检查读准备好并且用耗尽输入,因为服务器可能阻塞给我们发送数据的尝试,例如 NOTICE 消息,并且在我们读它的数据之前它都不会读我们的数据)。 - 一旦返回 0,应等待套接字变成读准备好并且接着按照上文所述读取响应。 - + 在非阻塞连接上发送命令或数据后,应调用 。如果返回 1,就等待套接字变为可读或可写。套接字可写时,再次调用 ;可读时,先调用 ,再调用 。重复上述步骤,直到 返回 0。(必须检查套接字是否可读,并用 读完输入,因为服务器可能在尝试向客户端发送数据时阻塞,例如发送 NOTICE 消息;在客户端读取这些数据之前,服务器不会读取客户端发送的数据。)当 返回 0 后,等待套接字变为可读,再按前述方法读取响应。 + @@ -3600,7 +3560,7 @@ int PQsetSingleRowMode(PGconn *conn); - 此函数只能在调用或其某个兄弟函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活单行模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 + 此函数只能在调用或其某个同类函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活单行模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 @@ -3686,7 +3646,7 @@ int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize); - 的一个已废弃变体。 + 的一个已弃用变体。 int PQrequestCancel(PGconn *conn); @@ -3706,7 +3666,7 @@ int PQrequestCancel(PGconn *conn); 快速路径接口 - fast path + 快速路径 @@ -3742,24 +3702,22 @@ typedef struct - fnid参数是要被执行的函数的 OID。argsnargs定义了要传递给函数的参数;它们必须匹配已声明的函数参数列表。当一个参数结构体的isint域为真时,u.integer值被以指定长度(必须是 2 或 4 字节)整数的形式发送给服务器;这时候会发生恰当的字节交换。当isint为假时,*u.ptr中指定数量的字节将不做任何处理被发送出去;这些数据必须是服务器 预期的用于该函数参数数据类型的二进制传输的格式(由于历史原因u.ptr被声明为类型int *,其实把它考虑成void *会更好)。result_buf是放置该函数返回值的缓冲区。调用者必须已经分配了足够的空间来存储返回值(这里没有检查!)。实际的结果长度将被放在result_len指向的整数中返回。如果预期结果是 2 或 4 字节整数,把result_is_int设为 1;否则设为 0。把result_is_int设为 1 导致libpq在必要时对值进行交换字节,这样它就作为对客户端机器正确的int值被传输,注意对任一种允许的结果大小都会传递一个 4 字节整数到*result_buf。当result_is_int是 0 时,服务器发送的二进制格式字节将不做修改直接返回(在这种情况下,把result_buf考虑为类型void *更好)。 - + fnid 参数是要执行函数的 OID。argsnargs 指定传给函数的参数,必须与函数声明中的参数列表匹配。参数结构体的 isint 字段为真时,u.integer 值会以指定长度的整数发送到服务器,该长度必须是 2 或 4 字节,并会进行适当的字节序转换。isint 为假时,位于 *u.ptr 的指定数量字节会原样发送;数据必须符合服务器对该函数参数数据类型的二进制传输格式要求。(将 u.ptr 声明为 int * 是历史原因;将其视为 void * 更合适。)result_buf 指向用于存放函数返回值的缓冲区。调用者必须事先分配足够空间来保存返回值,这里不会检查!实际结果长度以字节为单位,返回到 result_len 指向的整数中。如果预期结果是 2 或 4 字节整数,将 result_is_int 设为 1,否则设为 0。将 result_is_int 设为 1 后,libpq 会按需转换字节序,使结果成为适合客户端机器的 int 值;注意,无论是哪种允许的结果大小,传入 *result_buf 的都是 4 字节整数。result_is_int 为 0 时,服务器发送的二进制格式字节串会原样返回。(此时,将 result_buf 视为 void * 更合适。) + - PQfn总是返回一个有效的PGresult指针,包括状态PGRES_COMMAND_OK 表示成功或者PGRES_FATAL_ERROR在出现什么问题时。 - 在使用结果之前应该检查结果状态。 - 当结果不再使用后,调用者有义务使用释放PGresult。 - + PQfn 总是返回有效的 PGresult 指针:成功时状态为 PGRES_COMMAND_OK,遇到问题时为 PGRES_FATAL_ERROR。使用结果前应检查其状态。不再需要结果时,调用者负责使用 释放 PGresult。 + - 要传递NULL参数到函数,将参数结构体的len字段设置为-1isintu 字段就不相关了。(但这仅适用于使用协议 3.0 及更高版本的连接。) + 要向函数传入 NULL 参数,将该参数结构体的 len 字段设为 -1;此时,isintu 字段便不再相关。(但这仅适用于使用协议 3.0 及更高版本的连接。) + 如果函数返回 NULL,则将 *result_len 设为 -1,而不修改 *result_buf。(这仅适用于使用协议 3.0 及更高版本的连接;在协议 2.0 中,既不修改 *result_len,也不修改 *result_buf。) - 注意在使用此接口时,不能够处理集-值结果。 - 此外,函数必须是一个普通函数,而不是聚合、窗口函数或过程。 - + 注意,使用此接口时无法处理集合值结果。此外,函数必须是普通函数,不能是聚合函数、窗口函数或过程。 + @@ -3768,7 +3726,7 @@ typedef struct NOTIFY - in libpq + 在 libpq 中 @@ -3777,32 +3735,36 @@ typedef struct libpq应用把LISTENUNLISTENNOTIFY命令作为普通 SQL 命令提交。 - 随后通过调用PQnotifies.PQnotifies来检测NOTIFY消息的到达。 + 随后通过调用PQnotifiesPQnotifies来检测NOTIFY消息的到达。 - 函数PQnotifies从已收到但尚未处理的服务器通知消息列表中返回下一条通知。如果没有待处理的通知,则返回空指针。一旦通知由PQnotifies返回,就被视为已处理,并从通知列表中移除。 + + 函数 PQnotifies 从已收到但尚未处理的服务器通知消息列表中返回下一条通知。没有待处理通知时返回空指针。一旦 PQnotifies 返回一条通知,该通知就被视为已处理,并从通知列表中移除。 + PGnotify *PQnotifies(PGconn *conn); typedef struct pgNotify { - char *relname; /* notification channel name */ - int be_pid; /* process ID of notifying server process */ - char *extra; /* notification payload string */ + char *relname; /* 通知通道名称 */ + int be_pid; /* 发送通知的服务器进程 ID */ + char *extra; /* 通知载荷字符串 */ } PGnotify; -处理完一个PGnotify对象(由PQnotifies返回)后,一定要用释放它。只需释放PGnotify指针;relnameextra字段并非独立分配。(这些字段名称是历史遗留的;尤其是,通道名称与关系名称不必有任何关联。) + +处理完 PQnotifies 返回的 PGnotify 对象后,务必使用 释放它。只需释放 PGnotify 指针;relnameextra 字段并非独立分配。(这些字段名称是历史遗留的;尤其是,通道名称与关系名称不必有任何关联。) + 给出了一个示例程序展示异步通知的使用。 - PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数吸收的消息。 + PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数读取的消息。 在较早版本的libpq中,及时收到NOTIFY消息的唯一方法是不断提交命令,哪怕是空命令,然后在每次后检查PQnotifies。 - 虽然这种方法仍然有效,但由于效率过低,现已废弃。 + 虽然这种方法仍然有效,但由于浪费处理能力,现已弃用。 - 当你没有可用的命令提交时,一种更好的检查NOTIFY消息的方法是调用,然后检查PQnotifies。 + 当没有需要执行的实际命令时,一种更好的检查NOTIFY消息的方法是调用,然后检查PQnotifies。 你可以使用select()等待服务器数据到达,这样在无事可做时就不会浪费CPU资源(参见以获得可传给select()的文件描述符)。 注意不管是用/提交命令还是简单地使用,这种方法都能正常工作。 不过,你应该记住在每次之后检查PQnotifies,看看在命令的处理过程中是否有通知到达。 @@ -3815,20 +3777,16 @@ typedef struct pgNotify COPY - with libpq + 使用 libpq - PostgreSQL中的COPY命令有用于libpq的对网络连接读出或者写入的选项。这一节描述的函数允许应用通过提供或者消耗已拷贝的数据来充分利用这个功能。 - + PostgreSQLCOPY 命令提供了选项,可以通过 libpq 使用的网络连接读取或写入数据。本节介绍的函数允许应用程序通过提供或接收复制数据来使用这一能力。 + - 整个处理是应用首先通过或者一个等效的函数发出 SQL COPY命令。 - 对这个命令的响应(如果命令无误)将是一个状态代码是PGRES_COPY_OUT或 者PGRES_COPY_IN(取决于指定的拷贝方向)的PGresult对象。 - 应用然后就应该使用这一节的函数接收或者传送数据行。在数据传输结束之后,另外一个PGresult对象会被返回以表明传输的成功或者失败。 - 它的状态将是:PGRES_COMMAND_OK表示成功,PGRES_FATAL_ERROR表示发生了一些问题。 - 此时我们可以通过发出进一步的 SQL 命令(在COPY操作的处理过程中,不能用同一个连接执行其它 SQL 命令)。 - + 整体流程如下:应用程序先通过 或等效函数发出 SQL COPY 命令。如果命令没有错误,响应就是一个 PGresult 对象,其状态码为 PGRES_COPY_OUTPGRES_COPY_IN,取决于指定的复制方向。应用程序随后应使用本节函数接收或发送数据行。数据传输完成后,会返回另一个 PGresult 对象,表示传输成功或失败:成功时状态为 PGRES_COMMAND_OK,出现问题时为 PGRES_FATAL_ERROR。此时可以通过 继续发出 SQL 命令。(COPY 操作进行期间,不能在同一连接上执行其他 SQL 命令。) + 如果一个COPY命令是通过在一个可能包含额外命令的字符串中发出的,那么应用在完成COPY序列之后必须继续用取得结果。 @@ -3836,13 +3794,15 @@ typedef struct pgNotify - 这一节的函数应该只在从获得了PGRES_COPY_OUTPGRES_COPY_IN结果状态的后执行。 - + 只有从 获得 PGRES_COPY_OUTPGRES_COPY_IN 结果状态后,才应调用本节函数。 + - 一个PGresult对象若带有上述某个状态值,还会携带关于即将开始的COPY操作的附加数据。这些数据可以通过下列函数取得,这些函数也用于查询结果: + + 带有上述某个状态值的 PGresult 对象,还会携带关于即将开始的 COPY 操作的附加数据。这些数据可以通过下列函数获取,这些函数也用于查询结果: + PQnfieldsPQnfieldswith COPY + >PQnfields用于 COPY @@ -3853,7 +3813,7 @@ typedef struct pgNotify PQbinaryTuplesPQbinaryTupleswith COPY + >PQbinaryTuples用于 COPY @@ -3865,7 +3825,7 @@ typedef struct pgNotify PQfformatPQfformatwith COPY + >PQfformat用于 COPY @@ -3877,7 +3837,7 @@ typedef struct pgNotify - + 这些附加数据值仅在使用协议 3.0 时可用。使用协议 2.0 时,这些函数都返回 0。 @@ -3887,8 +3847,8 @@ typedef struct pgNotify 用于发送<command>COPY</command>数据的函数 - 这些函数用于在COPY FROM STDIN期间发送数据。如果在连接不是COPY_IN状态,调用它们会失败。 - + 这些函数用于在 COPY FROM STDIN 期间发送数据。如果连接不处于 COPY_IN 状态,调用它们会失败。 + @@ -3907,12 +3867,11 @@ int PQputCopyData(PGconn *conn, - 传输指定buffer中长度为nbytesCOPY数据到服务器。 - 如果数据被放在队列中,结果是 1;如果因为缓冲区满而无法被放在队列中(只可能发生在连接是非阻塞模式时),那么结果是零;如果发生错误,结果为 -1(如果返回值为 -1,那么使用检索细节。如果值是零,那么等待写准备好然后重试)。 + 将指定 buffer 中长度为 nbytesCOPY 数据传输到服务器。数据成功加入队列时返回 1;因缓冲区已满而无法加入队列时返回零(仅可能发生在非阻塞模式下);发生错误时返回 -1。(返回 -1 时,可用 获取详细信息。返回零时,应等待可写就绪后重试。) - 应用可以把COPY数据流划分成任意方便的大小放到缓冲区中。在发送时,缓冲区载荷的边界没有什么语意。数据流的内容必须匹配COPY命令预期的数据格式;详见。 + 应用程序可以将 COPY 数据流分成任意方便大小的数据块,逐块装入缓冲区。发送时,这些数据块的边界没有语义含义。数据流内容必须符合 COPY 命令预期的数据格式;详见 @@ -3929,18 +3888,16 @@ int PQputCopyEnd(PGconn *conn, - 如果 errormsgNULL,则成功结束 COPY_IN 操作。如果 errormsg 不为 NULL,则强制 COPY 失败,并将 errormsg 指向的字符串用作错误消息。(但不应假定服务器一定会返回这条完全相同的错误消息,因为服务器可能已经因自身原因使 COPY 失败。还要注意,在使用 3.0 之前协议的连接上,强制失败选项不起作用。) + + 如果 errormsgNULL,则成功结束 COPY_IN 操作。如果 errormsg 不为 NULL,则强制 COPY 失败,并将 errormsg 指向的字符串用作错误消息。(但不应假定服务器一定会返回这条完全相同的错误消息,因为服务器可能已经因自身原因使 COPY 失败。还要注意,在使用 3.0 之前协议的连接上,强制失败选项不起作用。) + - 如果终止消息被发送,则结果为 1;在非阻塞模式中,结果为 1 也可能只表示终止消息被成功地放在了发送队列中 - (在非阻塞模式中,要确认数据确实被发送出去,你应该接着等待写准备好并且调用,重复这些直到返回零)。 - 零表示该函数由于缓冲区满而无法将该终止消息放在队列中,这只会发生在非阻塞模式中(在这种情况下,等待写准备好并且再次尝试调用)。 - 如果发生系统错误,则返回 -1,可以使用检索详情。 + 终止消息已发送时返回 1;在非阻塞模式下,返回 1 也可能仅表示该消息已成功加入发送队列。(在非阻塞模式下,要确认数据已经发送,应接着等待可写就绪并调用 ,反复执行直到返回零。)返回零表示缓冲区已满,无法将终止消息加入队列;这种情况仅可能发生在非阻塞模式下。(此时,应等待可写就绪,再次调用 。)发生严重错误时返回 -1,可用 获取详细信息。 - 在成功调用之后,调用获取COPY命令的最终结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 成功调用 后,调用 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -3970,24 +3927,19 @@ int PQgetCopyData(PGconn *conn, - 在一个COPY期间尝试从服务器获取另外一行数据。数据总是以每次一个数据行的方式被返回;如果只有一个部分行可用,那么它不会被返回。 - 成功返回一个数据行涉及到分配一块内存来保存该数据。buffer参数必须为非NULL。 - *buffer被设置为指向分配到的内存的指针,或者是在没有返回缓冲区的情况下指向NULL。 - 一个非NULL的结果缓冲区在不需要时必须用释放。 + 在 COPY 期间尝试从服务器获取下一行数据。每次总是返回一个完整数据行;如果只有部分行可用,则不返回。成功返回数据行时,会分配一块内存保存数据。buffer 参数必须为非 NULL*buffer 会被设置为指向所分配的内存;如果没有返回缓冲区,则设为 NULL。非 NULL 的结果缓冲区在不再需要时应使用 释放。 - 在成功返回一行之后,返回的值就是该数据行里数据的字节数(将是大于零)。 - 被返回的字符串总是空终止的,虽然这可能只是对文本COPY有用。 - 一个零结果表示该COPY仍然在处理中,但是还没有可用的行(只在async为真时才可能)。 - 一个 -1 结果表示COPY已经完成。-2 结果表示发生了错误(参考获取原因)。 + 成功返回一行时,返回值是该行的数据字节数,始终大于零。返回的字符串总是以零字节结尾,不过这可能仅对文本 COPY 有用。返回零表示 COPY 仍在进行,但尚无可用行(仅在 async 为真时可能发生)。返回 -1 表示 COPY 已完成;返回 -2 表示发生了错误(可用 查看原因)。 - async 为真(非零)时, 不会阻塞等待输入;如果 COPY 仍在进行,但没有完整的行可用,则返回零。(这种情况下,应等待读就绪,随后先调用 ,再调用 。)当 async 为假(零)时, 会阻塞,直到有数据可用或操作完成。 + + 当 async 为真(非零)时, 不会阻塞等待输入;如果 COPY 仍在进行,但没有完整行可用,则返回零。(此时,应等待读就绪,先调用 ,再调用 。)当 async 为假(零)时, 会阻塞,直到数据可用或操作完成。 + - 在返回 -1 之后,调用获取COPY命令的最后结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 在 返回 -1 后,调用 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -3997,11 +3949,11 @@ int PQgetCopyData(PGconn *conn, - 用于<command>COPY</command>的废弃函数 + 用于<command>COPY</command>的过时函数 - 这些函数代表了以前的处理COPY的方法。尽管它们还能用,但是现在已经被废弃,因为它们的错误处理很糟糕、检测结束数据的方法也不方便,并且缺少对二进制或非阻塞传输的支持。 - + 这些函数使用较旧的方式处理 COPY。虽然仍然可用,但由于错误处理欠佳、检测数据结束的方式不便,而且缺少对二进制或非阻塞传输的支持,已被弃用。 + @@ -4011,7 +3963,7 @@ int PQgetCopyData(PGconn *conn, - 读取一个以新行终止的字符行到(由服务器传输) 到一个长度为length的字符串缓冲区。 + 将服务器传来的、以换行符结尾的一行字符读入大小为 length 的字符串缓冲区。 int PQgetline(PGconn *conn, char *buffer, @@ -4020,12 +3972,11 @@ int PQgetline(PGconn *conn, - 这个函数拷贝最多length-1 个字符到该缓冲区中,并且把终止的新行转换成一个零字节。 - 在输入结束时返回EOF,如果整行都被读取则返回 0,如果缓冲区填满了而还没有遇到结束的新行则返回 1。 - + 此函数最多将 length-1 个字符复制到缓冲区,并将末尾的换行符转换为零字节。 在输入结束时返回 EOF,读完一整行时返回 0,缓冲区已满但尚未读到末尾换行符时返回 1。 + - 注意,应用必须检查是否一个新行包含两个字符\.,这表明服务器 已经完成了COPY命令的结果发送。如果应用可能收到超过length-1 字符长的行, 我们就应该确保正确识别\.行(例如,不要把一个长数据行的结束当作一个终止行)。 + 注意,应用程序必须检查新读入的一行是否仅由 \. 两个字符组成,这表示服务器已发送完 COPY 命令的结果。如果可能收到长度超过 length-1 个字符的行,必须确保正确识别 \. 行,例如不能把长数据行的末尾误当作终止行。 @@ -4037,7 +3988,7 @@ int PQgetline(PGconn *conn, - 不阻塞地读取一行COPY数据(由服务器传输)到一个缓冲区中。 + 以非阻塞方式将服务器传来的一行 COPY 数据读入缓冲区。 int PQgetlineAsync(PGconn *conn, char *buffer, @@ -4046,23 +3997,19 @@ int PQgetlineAsync(PGconn *conn, - 这个函数类似于,但是可以被用于那些必须异步读取COPY数据的应用, 也就是不阻塞的应用。 - 在发出了COPY命令并得到了PGRES_COPY_OUT响应之后, - 应用应该调用直到检测到结束数据的信号。 - + 此函数类似于 ,但可用于必须异步读取 COPY 数据的应用程序,即读取时不阻塞。发出 COPY 命令并收到 PGRES_COPY_OUT 响应后,应用程序应调用 ,直到检测到数据结束信号。 + - 不像,这个函数负责检测结束数据。 + 与 不同,此函数会负责检测数据结束。 - 在每次调用时,如果libpq的输入缓冲区中有一个完整的数据行可用,都将返回数据。 - 否则,在剩余行到达之前不会返回数据。如果识别到拷贝数据结束的标志,此函数返回 -1;如果没有可用数据则返回 0; - 或者是给出一个正数给出被返回的字节数。如果返回 -1,调用者下一步必须调用,然后回到正常处理。 + 每次调用时,如果 libpq 的输入缓冲区中有完整数据行, 就会返回数据;否则,要等该行剩余部分到达后才返回数据。识别到复制数据结束标记时返回 -1,没有可用数据时返回 0,否则返回正数,表示返回的数据字节数。返回 -1 后,调用者必须接着调用 ,然后恢复正常处理。 - 返回的数据将不超过一个数据行的范围。如果可能,每次将返回一个完整行。但如果调用者提供的缓冲区太小不足以容下服务器发送的行,那么将返回部分行。对于文本数据,这可以通过测试返回的最后一个字节是否\n来检测(在二进制COPY中, 需要对COPY数据格式进行实际的分析,以便做相同的判断)。被返回的字符串不是空结尾的(如果你想增加一个终止空,确保传递一个比实际可用空间少一字节的bufsize)。 + 返回的数据不会跨越数据行边界。只要可能,每次就返回一整行;但如果调用者提供的缓冲区太小,容不下服务器发送的一行,则只返回部分行。对于文本数据,可检查最后返回的字节是否为 \n,以判断是否返回了完整行。(对于二进制 COPY,则必须实际解析 COPY 数据格式才能作出相同判断。)返回的字符串不以零字节结尾。(如果要自行添加末尾的零字节,务必将传入的 bufsize 设置为比实际可用空间少一字节。) @@ -4074,7 +4021,7 @@ int PQgetlineAsync(PGconn *conn, - 向服务器发送一个空终止的字符串。如果 OK 则返回 0;如果不能发送字符串则返回EOF。 + 向服务器发送以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputline(PGconn *conn, const char *string); @@ -4082,17 +4029,14 @@ int PQputline(PGconn *conn, - 一系列调用发送的COPY数据流和返回的数据具有相同的格式, - 只是应用不需要每次调用中发送刚好一个数据行;在每次调用中发送多行或者部分行都是可以的。 + 连续调用 发送的 COPY 数据流,与 返回的数据格式相同。不过,应用程序不必在每次 调用中恰好发送一个数据行;每次发送部分行或多行也可以。 - 在PostgreSQL协议 3.0 之前,应用必须显式地发送两个字符\.作为最后一行来指示服务器已经完成发送COPY数据。 - 虽然这么做仍然有效,但是它已经被废弃并且\.的特殊含义可能在将来的版本中删除。 - 在发送完实际数据之后, 调用就足够了。 - + 在 PostgreSQL 协议 3.0 之前,应用程序必须显式发送由 \. 两个字符组成的最后一行,告知服务器应用程序已发送完 COPY 数据。虽然这种方式仍然有效,但已被弃用,\. 的特殊含义预计会在未来版本中移除。发送完实际数据后,调用 即可。 + @@ -4104,7 +4048,7 @@ int PQputline(PGconn *conn, - 向服务器发送一个非空终止的字符串。如果 OK 则返回 0,如果不能发送字符串则返回EOF。 + 向服务器发送不以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputnbytes(PGconn *conn, const char *buffer, @@ -4113,7 +4057,7 @@ int PQputnbytes(PGconn *conn, - 这个函数类似,除了数据缓冲区不需要是空终止,因为要发送的字节数是直接指定的。在发送二进制数据时使用这个过程。 + 此函数与 完全相同,只是直接指定了要发送的字节数,因此数据缓冲区不必以零字节结尾。发送二进制数据时可使用此函数。 @@ -4129,15 +4073,11 @@ int PQputnbytes(PGconn *conn, int PQendcopy(PGconn *conn); - 这个函数等待服务器完成拷贝。当最后一个字符串已经用发送给服务器时或者当最后一个字符串已经用PQgetline从服务器接收到时,就会发出这个函数。 - 这个函数必须被发出,否则服务器将会和客户端不同步。从这个函数返回后,服务器就已经准备好接收下一个 SQL 命令了。函数成功完成时返回值为 0,否则返回非零值(如果返回值为非零值,用检索详情)。 +此函数会等待服务器完成复制。应在使用 向服务器发送最后一个字符串后,或使用 PQgetline 从服务器接收最后一个字符串后调用它。必须调用此函数,否则服务器与客户端会失去同步。函数返回后,服务器便准备好接收下一条 SQL 命令。成功完成时返回 0,否则返回非零值。(返回非零值时,可用 获取详细信息。) - 在使用时,应用应该通过反复调用并且在看到终止行后调用来响应PGRES_COPY_OUT结果。 - 然后它应该返回到循环直到返回一个空指针。 - 类似地,PGRES_COPY_IN结果会用一系列加上之后的来处理,然后返 回到循环。 - 这样的安排将保证嵌入到一系列SQL命令中的COPY命令将被正确执行。 + 使用 时,收到 PGRES_COPY_OUT 结果后,应用程序应反复调用 ,并在看到终止行后调用 。随后应回到 循环,直到 返回空指针。类似地,收到 PGRES_COPY_IN 结果后,应连续调用 ,再调用 ,然后回到 循环。这样可以保证嵌在一系列 SQL 命令中的 COPY 命令正确执行。 @@ -4156,8 +4096,8 @@ int PQendcopy(PGconn *conn); 控制函数 - 这些函数控制libpq行为各种各样的细节。 - + 这些函数控制 libpq 行为的各种细节。 + @@ -4167,17 +4107,15 @@ int PQendcopy(PGconn *conn); - 返回客户端编码。 + 返回客户端编码。 int PQclientEncoding(const PGconn *conn); - - 请注意,它返回的是编码 ID,而不是一个符号串字符串,如EUC_JP。如果不成功,它会返回 -1。要把一个编码 ID 转换为为一个编码名称,可以用: - +注意,返回的是编码 ID,而不是 EUC_JP 这样的符号字符串。失败时返回 -1。要将编码 ID 转换为编码名称,可以使用: char *pg_encoding_to_char(int encoding_id); - + @@ -4187,14 +4125,11 @@ char *pg_encoding_to_char(int encoding_id); - - 设置客户端编码。 - + 设置客户端编码。 int PQsetClientEncoding(PGconn *conn, const char *encoding); - conn是一个到服务器的连接,而encoding是你想使用的编码。 - 如果函数成功地设置编码,则返回 0,否则返回 -1。这个连接的当前编码可以使用确定。 + conn是到服务器的连接,而encoding是要使用的编码。如果成功设置编码,函数返回 0,否则返回 -1。此连接的当前编码可以通过以下函数确定: @@ -4203,7 +4138,8 @@ int PQsetClientEncoding(PGconn *conn, const char *PQsetErrorVerbosityPQsetErrorVerbosity - 设置以下函数所返回消息的详细程度:。 + + 设置 所返回消息的详细程度。 typedef enum { @@ -4215,13 +4151,12 @@ typedef enum PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); - - 设置详细程度模式,并返回该连接先前的设置。在TERSE模式下,返回的消息只包含严重级别、主要文本和位置;通常一行就能容纳。DEFAULT模式生成的消息除上述内容外,还包含所有的详细信息、提示或上下文字段(这些内容可能跨越多行)。VERBOSE模式包含所有可用字段。SQLSTATE模式仅包含错误严重级别,以及可用时的SQLSTATE错误代码(如果没有错误代码,则输出与TERSE模式相同)。 + 设置详细程度模式,并返回该连接先前的设置。在 TERSE 模式下,返回的消息只包含严重级别、主要文本和位置;通常一行就能容纳。DEFAULT 模式生成的消息除上述内容外,还包含所有详细信息、提示或上下文字段(这些内容可能跨越多行)。VERBOSE 模式包含所有可用字段。SQLSTATE 模式仅包含错误严重级别,以及可用时的 SQLSTATE 错误代码(如果没有错误代码,则输出与 TERSE 模式相同)。 + - 更改详细程度设置不会影响已存在的PGresult对象的可用的消息,只会影响随后创建的对象。 - (如果想要用不同的详细程度打印之前的错误,请见 ) - + 更改详细程度设置不会影响从既有 PGresult 对象中取得的消息,只影响随后创建的对象。(如果希望以不同的详细程度打印之前的错误,请参见 。) + @@ -4230,7 +4165,7 @@ PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); - 决定如何处理返回的消息中的CONTEXT域。 + 确定 所返回消息中 CONTEXT 字段的处理方式。 typedef enum { @@ -4241,15 +4176,12 @@ typedef enum PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibility show_context); + 设置上下文显示模式,并返回连接先前的设置。此模式控制消息中是否包含 CONTEXT 字段。NEVER 模式从不包含 CONTEXT,而 ALWAYS 模式在该字段可用时总是包含它。在 ERRORS 模式(默认)下,CONTEXT 字段只包含在错误消息中,不包含在通知和警告中。(不过,如果详细程度设置为 TERSESQLSTATE,则无论上下文显示模式如何,都会省略 CONTEXT 字段。) + - 设置上下文显示模式,返回该连接上之前的设置。 - 这个模式控制消息中是否包括CONTEXT域。 - NEVER模式不会包括CONTEXT,而ALWAYS则尽可能地包括这个域。 - 在ERRORS模式(默认)中,只在错误消息中包括CONTEXT域,而在通知和警告消息中不会包括。 - (但是,如果详细程度设置为 TERSESQLSTATE,则无论上下文显示模式如何,都会省略CONTEXT字段。) - - - 更改此模式不会影响从既有 PGresult 对象中取得的消息,只影响随后创建的对象。(如果希望使用不同的显示模式打印之前的错误,请参见 。) + + 更改此模式不会影响从既有 PGresult 对象中取得的消息,只影响随后创建的对象。(如果希望使用不同的显示模式打印之前的错误,请参见 。) + @@ -4258,16 +4190,16 @@ PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibilit - 启用对客户端/服务器通讯的跟踪,把跟踪信息输出到一个调试文件流中。 + 启用客户端/服务器通信跟踪,将跟踪信息写入调试文件流。 void PQtrace(PGconn *conn, FILE *stream); - + - 在 Windows上,如果libpq库和应用使用了不同的标志编译,那么这个函数调用会导致应用崩溃,因为FILE指针的内部表达是不一样的。特别是多线程/单线程、发布/调试 以及静态/动态标志应该是库和所有使用库的应用都一致。 + 在 Windows 上,如果 libpq 库与应用程序使用不同的标志编译,调用此函数会导致应用程序崩溃,因为 FILE 指针的内部表示不同。具体而言,库与所有使用它的应用程序都应使用相同的多线程/单线程、发布/调试和静态/动态标志。 @@ -4281,11 +4213,11 @@ void PQtrace(PGconn *conn, FILE *stream); - 禁用打开的跟踪。 + 禁用由 启动的跟踪。 void PQuntrace(PGconn *conn); - + @@ -4314,11 +4246,8 @@ void PQfreemem(void *ptr); - 释放libpq分配的内存,尤其是,,,和PQnotifies分配的内存。 - 特别重要的是,在微软 Windows 上使用这个函数,而不是free()。 - 这是因为只有 DLL 和应用的当多线程/单线程、发布/调试以及静态/动态标志相同时,才能在一个 DLL 中分配内存并且在应用中释放它。 - 在非微软 Windows 平台上,这个函数与标准库函数free()相同。 - + 释放 libpq 分配的内存,特别是 PQnotifies 分配的内存。在 Microsoft Windows 上,务必使用此函数,而不是 free()。这是因为只有 DLL 与应用程序使用相同的多线程/单线程、发布/调试和静态/动态标志,才能在 DLL 中分配内存并在应用程序中释放它。在 Microsoft Windows 以外的平台上,此函数与标准库函数 free() 相同。 + @@ -4336,8 +4265,8 @@ void PQconninfoFree(PQconninfoOption *connOptions); - 一个简单的不会做这些,因为数组包含对子字符串的引用。 - + 仅调用 不足以完成此项释放,因为数组还包含指向附属字符串的引用。 + @@ -4361,8 +4290,8 @@ char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, 当前支持的算法是md5scram-sha-256onoff也被接受作为md5的别名,用于与较老的服务器版本兼容)。 注意,对scram-sha-256支持是在PostgreSQL版本10中引入的,并且在老的服务器版本上无法工作。 如果algorithmNULL,这个函数将向服务器查询设置的当前值。 - 这种行为可能会阻塞当前事务,并且当前事务被中止或者连接正忙于执行另一个查询时会失败。 - 如果希望为服务器使用默认的算法但避免阻塞,应在调用之前查询你自己的password_encryption,并且将该值作为algorithm传入。 + 这一查询可能阻塞,并且当前事务被中止或者连接正忙于执行另一个查询时会失败。 + 如果希望为服务器使用默认的算法但避免阻塞,应在调用之前自行查询password_encryption,并且将该值作为algorithm传入。 @@ -4406,8 +4335,8 @@ PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); 这是libpq内部用于分配并初始化一个空PGresult对象的函数。 如果无法分配内存,此函数返回NULL。 将它导出供外部调用,是因为一些应用需要自行生成结果对象,特别是带有错误状态的对象。 - 如果conn非空,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 - 此外,如果conn非空,连接中注册的所有事件过程也会被复制到PGresult中。 + 如果conn 不为 null,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 + 此外,如果conn 不为 null,连接中注册的所有事件过程也会被复制到PGresult中。 (这些过程不会收到PGEVT_RESULTCREATE调用,但可参见。) 注意,最终应对该对象调用,就像处理libpq自身返回的PGresult一样。 @@ -4428,16 +4357,16 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); - conn参数被传送给事件过程,但不会被直接使用。如果事件过程不使用它,则会返回NULL。 - + conn 参数会传递给事件过程,但此函数不会直接使用它。如果事件过程不使用此参数,则可以传入 NULL。 + 已经接收到这个对象的PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件过程不会被再次触发。 - 这个函数与分开的主要原因是在调用事件过程之前创建一个PGresult并且填充它常常是合适的。 - + 此函数与 分开的主要原因是,通常适合先创建 PGresult 并填充数据,然后再调用事件过程。 + @@ -4446,13 +4375,11 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); - 为一个PGresult对象创建一个拷贝。 - 这个拷贝不会以任何方式链接到源结果,并且当该拷贝不再需要时,必须调用进行清理。如果函数失败,返回NULL。 - + 创建 PGresult 对象的副本。副本与源结果没有任何关联,不再需要副本时必须调用 。函数失败时返回 NULL PGresult *PQcopyResult(const PGresult *src, int flags); - + 这不是为了制作一个精确的副本。返回的结果总是放在PGRES_TUPLES_OK状态中,并且不复制源中的任何错误消息。 @@ -4492,18 +4419,15 @@ int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs); - 设置一个PGresult对象的一个元组域值。 + 设置 PGresult 对象中某个元组的字段值。 int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len); - + - 这个函数将自动按需增加结果的内部元组数组。但是,tup_num参数必须小于等于,意味着这个函数对元组数组一次只能增加一个元组。 - 但已存在的任意元组中的任意域可以以任意顺序进行调整。如果field_num的一个值已经存在,它会被覆盖。 - 如果len是 -1,或valueNULL, 该域值会被设置为一个 SQL 空值。 - value会被复制到结果的私有存储中,因此函数返回后就不再需要了。如果函数失败,返回值是 0。如果函数成功,返回值会是非 0。 - + 此函数会根据需要自动扩展结果内部的元组数组。不过,tup_num 参数必须小于或等于 ,也就是说,每次只能向元组数组增加一个元组。已有元组的任何字段都可以按任意顺序修改。如果 field_num 指定的位置已有值,该值会被覆盖。如果 len 为 -1 或 valueNULL,则将该字段设置为 SQL null 值。value 会被复制到结果的私有存储中,因此函数返回后就不再需要它。函数失败时返回零,成功时返回非零值。 + @@ -4521,8 +4445,8 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); - 当res被清除时,这个函数分配的内存也会被释放掉。如果函数失败,返回值是NULL。结果被保证为按照数据的任意类型充分地对齐,正如malloc所作的。 - + 使用此函数分配的所有内存都会在清除 res 时释放。函数失败时返回 NULL。与 malloc 一样,返回的内存保证满足任意数据类型的对齐要求。 + @@ -4533,15 +4457,15 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); - 检索为PGresult对象分配的字节数。 + 获取为 PGresult 对象分配的字节数。 size_t PQresultMemorySize(const PGresult *res); - + - 此值是与PGresult对象关联的所有malloc请求的总和,就是说,将释放的所有空间。此信息可用于管理内存消耗。 - + 此值是与 PGresult 对象相关的所有 malloc 请求所分配字节数的总和,即 将释放的全部内存。这一信息有助于管理内存消耗。 + @@ -4560,28 +4484,25 @@ int PQlibVersion(void); - 在运行时,这个函数的结果可以被用来决定在当前已载入的 libpq 版本中特定的功能是否可用。 - 例如,这个函数可以被用来决定哪些选项可以被用于。 - + 可在运行时根据此函数的结果,判断当前已加载的 libpq 版本是否具有特定功能。例如,可用它判断 支持哪些连接选项。 + - 结果通过将库的主版本号乘以10000再加上次版本号形成。例如,版本10.1将被返回为100001,而版本11.0将被返回为110000。 - + 返回值等于库的主版本号乘以 10000 再加上次版本号。例如,版本 10.1 返回 100001,版本 11.0 返回 110000。 + - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。 - 对于那些版本,为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - + 在主版本 10 之前,PostgreSQL 使用由三个部分组成的版本号,前两个部分共同表示主版本。对于这些版本, 用两位数字表示每个部分;例如,版本 9.1.5 返回 90105,版本 9.2.0 返回 90200。 + - 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。 - 在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 - + 因此,为了判断功能兼容性,应用程序应将 的结果除以 100 而非 10000,得到逻辑上的主版本号。在所有版本系列中,次版本(错误修复版本)之间只有最后两位数字不同。 + - 这个函数出现于PostgreSQL版本 9.1,因此它不能被用来在早期的版本中检测所需的功能,因为调用它将会创建一个对版本9.1及其后版本的链接依赖。 + 此函数从 PostgreSQL 9.1 起提供,因而不能用它检测更早版本是否具有所需功能:调用它会建立对 9.1 或更高版本的链接依赖。 @@ -4596,13 +4517,13 @@ int PQlibVersion(void); 通知处理 - notice processing - in libpq + 通知处理 + 在 libpq 中 - 服务器产生的通知和警告消息不会被查询执行函数返回,因为它们不代表查询失败。它们可以被传递给一个通知处理函数,并且在处理者返回后执行会继续正常进行。默认的处理函数会把消息打印在stderr上,但是应用可以通过提供它自己的处理函数来重载这种行为。 - + 服务器生成的通知和警告消息不由查询执行函数返回,因为它们并不表示查询失败。这些消息会传递给通知处理函数,处理函数返回后,执行正常继续。默认通知处理函数将消息打印到 stderr,应用程序也可以提供自己的处理函数来替换这一行为。 + 由于历史原因,通知处理有两个级别,称为通知接收器和通知处理器。通知接收器的默认行为是格式化通知并且将一个字符串传递给通知处理器来打印。不过,如果一个应用选择提供自己的通知接收器,它通常会忽略通知处理器层并且在通知接收器中完成所有工作。 @@ -4610,10 +4531,10 @@ int PQlibVersion(void); 函数PQsetNoticeReceiver - notice receiver + 通知接收器 PQsetNoticeReceiver为一个连接对象设置或者检查当前的通知接收器。 相似地,PQsetNoticeProcessor - notice processor + 通知处理器 PQsetNoticeProcessor设置或检查当前的通知处理器。 @@ -4636,19 +4557,16 @@ PQsetNoticeProcessor(PGconn *conn, - 当接收到一个服务器产生的或者libpq内部产生的通知或警告消息,通知接收器函数会被调用。 - 它会以一种PGRES_NONFATAL_ERROR PGresult的形式传递该消息 - (这允许接收器使用抽取个别的域,或者使用或者得到一个完整的预格式化的消息)。 - 被传递给PQsetNoticeReceiver的同一个空指针也被传递(必要时,这个指针可以被用来访问应用相关的状态)。 - + 从服务器收到通知或警告消息,或者 libpq 内部生成这类消息时,便会调用通知接收器函数。消息以状态为 PGRES_NONFATAL_ERRORPGresult 对象传给该函数。(接收器可使用 提取单个字段,也可使用 获取完整的预格式化消息。)传给 PQsetNoticeReceiver 的同一个 void 指针也会传入。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知接收器会简单地抽取消息(使用)并且将它传递给通知处理器。 - 通知处理器负责处理一个以文本形式给出的通知或警告消息。该消息的字符串文本(包括一个收尾的新行)被传递给通知处理器,外加一个同时被传递给PQsetNoticeProcessor的空指针(必要时,这个指针可以被用来访问应用相关的状态)。 - + 通知处理器负责处理以文本形式提供的通知或警告消息。传给它的参数包括消息字符串(含末尾的换行符),以及先前传给 PQsetNoticeProcessor 的同一个 void 指针。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知处理器很简单: @@ -4662,9 +4580,8 @@ defaultNoticeProcessor(void *arg, const char *message) - 一旦你设定了一个通知接收器或处理器,你应该期待只要PGconn对象或者从它构造出的PGresult对象存在,该函数就应该能被调用。 - 在一个PGresult创建时,PGconn的当前通知处理指针被复制到PGresult中,以备类似的函数使用。 - + 设置通知接收器或处理器后,应当预期:只要 PGconn 对象或由它生成的 PGresult 对象仍存在,就可能调用该函数。创建 PGresult 时,会将 PGconn 当前的通知处理指针复制到 PGresult 中,供 等函数在需要时使用。 + @@ -4672,19 +4589,19 @@ defaultNoticeProcessor(void *arg, const char *message) 事件系统 - libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和毁灭。一种主要的使用情况是这允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 + libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和销毁。一个主要用途是允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 - 每个注册的事件处理程序都与两个数据相关联,libpq仅将其视为不透明的void *指针。 - 有一个透传指针,当事件处理程序与PGconn注册时,应用程序提供。 + 每个注册的事件处理程序都与两项数据相关联,libpq仅将其视为不透明的void *指针。 + 有一个透传指针,由应用程序在向 PGconn 注册事件处理程序时提供。 透传指针在PGconn及其生成的所有PGresult的生命周期内永远不会更改; 因此,如果使用,它必须指向长期存在的数据。 此外,还有一个实例数据指针,在每个PGconnPGresult中一开始都是NULL。 可以使用、 - PQsetResultInstanceData函数来操作此指针。 + PQresultSetInstanceData函数来操作此指针。 请注意,与透传指针不同,PGconn的实例数据不会自动继承到从中创建的PGresult。 - libpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 —— 这是事件处理程序的责任。 + libpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 — 这是事件处理程序的责任。 @@ -4698,7 +4615,7 @@ defaultNoticeProcessor(void *arg, const char *message) PGEVT_REGISTER - 注册事件在被调用时触发。此时最适合初始化事件处理函数可能需要的instanceData。每个连接中的每个事件处理函数只会触发一次注册事件。如果事件处理函数失败,则中止注册。 + 注册事件在被调用时触发。此时最适合初始化事件过程可能需要的instanceData。每个连接中的每个事件过程只会触发一次注册事件。如果事件过程失败,则中止注册。 typedef struct { PGconn *conn; @@ -4710,26 +4627,26 @@ typedef struct PGEVT_CONNRESET - 连接重置事件会在完成以下调用时触发:PQresetPoll。在这两种情况下,只有重置成功才会触发该事件。如果事件处理函数失败,整个连接重置就会失败;PGconn会被置于CONNECTION_BAD状态,并且PQresetPoll将返回PGRES_POLLING_FAILED。 + 连接重置事件会在完成以下调用时触发:PQresetPoll。在这两种情况下,只有重置成功才会触发该事件。如果事件过程失败,整个连接重置就会失败;PGconn会被置于CONNECTION_BAD状态,并且PQresetPoll将返回PGRES_POLLING_FAILED typedef struct { PGconn *conn; } PGEventConnReset; -收到PGEVT_CONNRESET事件时,应将evtInfo指针强制转换为PGEventConnReset *。虽然其中的PGconn刚刚被重置,但所有事件数据都保持不变。应利用此事件重置、重新加载或重新查询相关联的instanceData。注意,即使事件处理函数未能处理PGEVT_CONNRESET,它仍会在连接关闭时收到PGEVT_CONNDESTROY事件。 +收到PGEVT_CONNRESET事件时,应将evtInfo指针强制转换为PGEventConnReset *。虽然其中的PGconn刚刚被重置,但所有事件数据都保持不变。应利用此事件重置、重新加载或重新查询相关联的instanceData。注意,即使事件过程未能处理PGEVT_CONNRESET,它仍会在连接关闭时收到PGEVT_CONNDESTROY事件。 PGEVT_CONNDESTROY - 连接销毁事件由以下调用触发:。事件处理函数负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 + 连接销毁事件由以下调用触发:。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGconn *conn; } PGEventConnDestroy; -收到PGEVT_CONNDESTROY事件时,应将evtInfo指针强制转换为PGEventConnDestroy *。该事件触发于以下函数执行任何其他清理工作之前:。事件处理函数的返回值会被忽略,因为无法通过以下函数报告失败:。此外,事件处理函数失败不应中止清理不再使用的内存的过程。 +收到PGEVT_CONNDESTROY事件时,应将evtInfo指针强制转换为PGEventConnDestroy *。该事件触发于以下函数执行任何其他清理工作之前:。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:。此外,事件过程失败不应中止清理不再使用的内存的过程。 @@ -4761,25 +4678,25 @@ typedef struct PGEVT_RESULTCOPY - 结果复制事件会在调用时触发。只有复制完成后才会触发该事件。只有为源结果成功处理过PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件处理函数,才会收到PGEVT_RESULTCOPY事件。 + 结果复制事件会在调用时触发。只有复制完成后才会触发该事件。只有为源结果成功处理过PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件过程,才会收到PGEVT_RESULTCOPY事件。 typedef struct { const PGresult *src; PGresult *dest; } PGEventResultCopy; -收到PGEVT_RESULTCOPY事件时,应将evtInfo指针强制转换为PGEventResultCopy *。其中,src结果是复制源,而dest结果是复制目标。可以利用此事件对instanceData进行深复制,因为PQcopyResult无法完成这项工作。如果事件处理函数失败,整个复制操作就会失败,并且dest结果将被清除。返回失败代码时,必须完成所有清理工作,因为不会为目标结果发送PGEVT_RESULTDESTROY事件。 +收到PGEVT_RESULTCOPY事件时,应将evtInfo指针强制转换为PGEventResultCopy *。其中,src结果是复制源,而dest结果是复制目标。可以利用此事件对instanceData进行深复制,因为PQcopyResult无法完成这项工作。如果事件过程失败,整个复制操作就会失败,并且dest结果将被清除。返回失败代码时,必须完成所有清理工作,因为不会为目标结果发送PGEVT_RESULTDESTROY事件。 PGEVT_RESULTDESTROY - 结果销毁事件由以下调用触发:。事件处理函数负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 + 结果销毁事件由以下调用触发:。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGresult *result; } PGEventResultDestroy; -收到PGEVT_RESULTDESTROY事件时,应将evtInfo指针强制转换为PGEventResultDestroy *。该事件触发于以下函数执行任何其他清理工作之前:。事件处理函数的返回值会被忽略,因为无法通过以下函数报告失败:。此外,事件处理函数失败不应中止清理不再使用的内存的过程。 +收到PGEVT_RESULTDESTROY事件时,应将evtInfo指针强制转换为PGEventResultDestroy *。该事件触发于以下函数执行任何其他清理工作之前:。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:。此外,事件过程失败不应中止清理不再使用的内存的过程。 @@ -4787,7 +4704,7 @@ typedef struct - 事件回调函数 + 事件回调过程 @@ -4797,16 +4714,11 @@ typedef struct - PGEventProc是到一个事件过程的指针的 typedef,也就是从 libpq 接收事件的用户回调函数。一个事件过程的原型必须是 - + PGEventProc 是通过 typedef 定义的事件过程指针类型,也就是接收 libpq 事件的用户回调函数的指针类型。事件过程的签名必须为: int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) - - evtId指示发生了哪一个PGEVT事件。 - evtInfo指针必须被类型转换为合适的结构体类型才能获得关于事件的进一步信息。 - 当事件过程已被注册时,passThrough参数是提供给的指针。 - 如果成功,该函数应该返回非零值,失败则返回零。 +evtId 参数指示发生了哪一种 PGEVT 事件。必须将 evtInfo 指针强制转换为适当的结构体类型,以获取关于该事件的更多信息。passThrough 参数是在注册事件过程时传给 的指针。函数应在成功时返回非零值,在失败时返回零。 @@ -4816,8 +4728,8 @@ int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) - 在 Windows 上,函数能够有两个不同的地址:一个对 DLL 之外可见而另一个对 DLL 之内可见。我们应当小心只有其中之一会被用于libpq的事件过程函数,否则将会产生混淆。编写代码的最简单规则是将所有的事件过程声明为static。如果过程的地址必须对它自己的源代码文件之外可见,提供一个单独的函数来返回该地址。 - + 在 Windows 上,函数可能有两个不同的地址:一个在 DLL 外部可见,另一个在 DLL 内部可见。使用 libpq 的事件过程函数时,务必始终使用其中同一个地址,否则会产生混淆。确保代码正常工作的最简单做法,是将事件过程声明为 static。如果需要在过程所在的源文件之外取得其地址,应提供一个单独的函数来返回该地址。 + @@ -4844,7 +4756,7 @@ int PQregisterEventProc(PGconn *conn, PGEventProc proc, - 在每一个你想要接收事件的PGconn上必须注册一个事件过程。和内存不同,没有限制说一个连接上能注册多少个事件过程。如果该函数成功,它会返回一个非零值。如果它失败,则会返回零。 + 对于希望接收其事件的每个 PGconn,都必须注册一次事件过程。一个连接可注册的事件过程数量只受内存限制。函数成功时返回非零值,失败时返回零。 @@ -4886,14 +4798,15 @@ void *PQinstanceData(const PGconn *conn, PGEventProc proc); PQresultSetInstanceDataPQresultSetInstanceData - 将结果的instanceData(针对proc)设置为data。成功时返回非零,失败时返回零。(只有当proc未在结果中正确注册时,才可能失败。) + + 将结果中针对 procinstanceData 设置为 data。成功时返回非零值,失败时返回零。(只有当 proc 未在结果中正确注册时,才可能失败。) + int PQresultSetInstanceData(PGresult *res, PGEventProc proc, void *data); - 请注意,data表示的任何存储都不会由考虑,除非使用分配。 - (这样做是值得推荐的,因为它消除了在销毁结果时显式释放此类存储的需要。) + 注意,data 所指的存储不会计入 ,除非使用 分配它。(推荐这样做,因为结果销毁时便不必显式释放这部分存储。) @@ -4916,18 +4829,18 @@ void *PQresultInstanceData(const PGresult *res, PGEventProc proc); - 事件实例 + 事件示例 - 这里是一个管理与 libpq 连接和结果相关的私有数据的示例的框架。 - + 下面给出一个示例框架,用于管理与 libpq 连接和结果关联的私有数据。 + -/* The instanceData */ +/* instanceData 数据 */ typedef struct { int n; @@ -4953,8 +4866,8 @@ main(void) return 1; } - /* called once on any connection that should receive events. - * Sends a PGEVT_REGISTER to myEventProc. + /* 在每个需要接收事件的连接上调用一次。 + * 向 myEventProc 发送 PGEVT_REGISTER 事件。 */ if (!PQregisterEventProc(conn, myEventProc, "mydata_proc", NULL)) { @@ -4963,28 +4876,28 @@ main(void) return 1; } - /* conn instanceData is available */ + /* 可以取得 conn 的 instanceData */ data = PQinstanceData(conn, myEventProc); - /* Sends a PGEVT_RESULTCREATE to myEventProc */ + /* 向 myEventProc 发送 PGEVT_RESULTCREATE 事件 */ res = PQexec(conn, "SELECT 1 + 1"); - /* result instanceData is available */ + /* 可以取得结果的 instanceData */ data = PQresultInstanceData(res, myEventProc); - /* If PG_COPYRES_EVENTS is used, sends a PGEVT_RESULTCOPY to myEventProc */ + /* 使用 PG_COPYRES_EVENTS 时,向 myEventProc 发送 PGEVT_RESULTCOPY 事件 */ res_copy = PQcopyResult(res, PG_COPYRES_TUPLES | PG_COPYRES_EVENTS); - /* result instanceData is available if PG_COPYRES_EVENTS was - * used during the PQcopyResult call. + /* 如果调用 PQcopyResult 时使用了 PG_COPYRES_EVENTS, + * 就可以取得结果的 instanceData。 */ data = PQresultInstanceData(res_copy, myEventProc); - /* Both clears send a PGEVT_RESULTDESTROY to myEventProc */ + /* 两次清除操作都会向 myEventProc 发送 PGEVT_RESULTDESTROY 事件 */ PQclear(res); PQclear(res_copy); - /* Sends a PGEVT_CONNDESTROY to myEventProc */ + /* 向 myEventProc 发送 PGEVT_CONNDESTROY 事件 */ PQfinish(conn); return 0; @@ -5000,7 +4913,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventRegister *e = (PGEventRegister *)evtInfo; mydata *data = get_mydata(e->conn); - /* associate app specific data with connection */ + /* 将应用程序特有的数据与连接关联 */ PQsetInstanceData(e->conn, myEventProc, data); break; } @@ -5020,7 +4933,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventConnDestroy *e = (PGEventConnDestroy *)evtInfo; mydata *data = PQinstanceData(e->conn, myEventProc); - /* free instance data because the conn is being destroyed */ + /* 连接正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; @@ -5032,8 +4945,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *conn_data = PQinstanceData(e->conn, myEventProc); mydata *res_data = dup_mydata(conn_data); - /* associate app specific data with result (copy it from conn) */ - PQsetResultInstanceData(e->result, myEventProc, res_data); + /* 将应用程序特有的数据与结果关联(从 conn 复制) */ + PQresultSetInstanceData(e->result, myEventProc, res_data); break; } @@ -5043,8 +4956,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *src_data = PQresultInstanceData(e->src, myEventProc); mydata *dest_data = dup_mydata(src_data); - /* associate app specific data with result (copy it from a result) */ - PQsetResultInstanceData(e->dest, myEventProc, dest_data); + /* 将应用程序特有的数据与结果关联(从另一个结果复制) */ + PQresultSetInstanceData(e->dest, myEventProc, dest_data); break; } @@ -5053,18 +4966,18 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventResultDestroy *e = (PGEventResultDestroy *)evtInfo; mydata *data = PQresultInstanceData(e->result, myEventProc); - /* free instance data because the result is being destroyed */ + /* 结果正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; } - /* unknown event ID, just return true. */ + /* 未知的事件 ID,直接返回 true。 */ default: break; } - return true; /* event processing succeeded */ + return true; /* 事件处理成功 */ } ]]> @@ -5078,7 +4991,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) 环境变量 - 以下环境变量可用于选择连接参数的默认值,供以下函数使用:,前提是调用代码没有直接指定这些参数的值。例如,这样可以避免在简单的客户端应用程序中硬编码数据库连接信息。 + + 以下环境变量可用于选择连接参数的默认值,供 在调用代码未直接指定参数值时使用。例如,这样可以避免在简单的客户端应用程序中硬编码数据库连接信息。 + @@ -5186,9 +5101,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSERVICEFILE - PGSERVICEFILE指定每个用户的连接服务文件的名称 - (参见)。 - 默认为~/.pg_service.conf,或者在Microsoft Windows上为%APPDATA%\postgresql\.pg_service.conf。 + PGSERVICEFILE指定每个用户的连接服务文件的名称(参见)。 + 默认为~/.pg_service.conf,或者在 Microsoft Windows 上为%APPDATA%\postgresql\.pg_service.conf @@ -5233,7 +5147,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGREQUIRESSL的行为与连接参数相同。 - 这个环境变量已被弃用,推荐使用PGSSLMODE变量;设置这两个变量会抑制这个变量的效果。 + 这个环境变量已被弃用,推荐使用PGSSLMODE变量;同时设置这两个变量时,前者不再生效。 @@ -5393,7 +5307,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 以下环境变量可用于指定每个PostgreSQL会话的默认行为。(也可参见命令,了解按用户或按数据库设置默认行为的方法。) + + 以下环境变量可用于指定每个 PostgreSQL 会话的默认行为。(也可参见 命令,了解按用户或按数据库设置默认行为的方法。) + @@ -5420,7 +5336,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGGEQO为遗传查询优化器设置默认模式(等同于SET geqo TO ...)。 - 有关这些环境变量的正确取值,请参见SQL命令 + +有关这些环境变量的正确取值,请参见 SQL 命令 。 + 下面的环境变量决定libpq的内部行为,它们会覆盖编译在程序中的默认值。 @@ -5468,7 +5386,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) (可以复制上面这一行,并在行首加上#,在文件中加入提示注释。)前四个字段中的每一个都可以是字面值,或者是*,后者可以匹配任何内容。将使用与当前连接参数匹配的第一行中的密码字段。(因此,使用通配符时,应将更具体的条目放在前面。)如果条目需要包含:\,请使用\转义该字符。主机名字段首先匹配已指定的host连接参数;否则匹配已指定的hostaddr参数。如果两者都未指定,则查找主机名localhost。在以下情况下也会查找主机名localhost:连接使用 Unix 域套接字,且host参数与libpq的默认套接字目录路径匹配。在备库中,数据库字段为replication时,匹配连接到主库的流复制连接。除此之外,数据库字段的用途有限,因为同一用户在同一数据库集簇的所有数据库中使用相同的密码。 - 在 Unix 系统上,密码文件上的权限必须不允许所有人或组内访问,可以用chmod 0600 ~/.pgpass这样的命令实现。如果权限没有这么严格,该文件将被忽略。在微软 Windows 上,该文件被假定存储在一个安全的目录中,因此不会进行特别的权限检查。 + 在 Unix 系统上,密码文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.pgpass 这样的命令实现。如果权限没有这么严格,该文件将被忽略。在 Microsoft Windows 上,假定该文件存储在安全的目录中,因此不进行特殊的权限检查。 @@ -5490,10 +5408,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 连接服务文件允许 libpq 连接参数与一个单一服务名称关联。 - 那个服务名称可以在一个 libpq 连接字符串里面指定,与其相关的设置将被使用。 - 这允许在不重新编译使用 libpq 的应用的前提下修改连接参数。 - 服务名称也可以被使用PGSERVICE环境变量来指定。 + 连接服务文件允许将 libpq 连接参数与单个服务名称关联。随后可以在 libpq 连接字符串中指定该服务名称,从而使用关联的设置。这样便可以修改连接参数,而无需重新编译使用 libpq 的应用程序。也可以使用 PGSERVICE 环境变量指定服务名称。 @@ -5509,23 +5424,19 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 或者服务文件使用一种INI 文件格式,其中小节名是服务名并且参数是连接参数。 - 列表见。例如: + 两种服务文件均使用 INI 文件 格式,其中配置段名称是服务名称,参数是连接参数;参数列表见 。例如: -# comment +# 注释 [mydb] host=somehost port=5433 user=admin - 在PostgreSQL安装的share/pg_service.conf.sample中提供了一个示例文件。 +PostgreSQL 安装目录中的 share/pg_service.conf.sample 提供了一个示例文件。 - 从服务文件中获取的连接参数与从其他来源获取的参数相结合。 - 服务文件设置覆盖相应的环境变量,然后反过来可以由连接字符串中直接给出的值覆盖。 - 例如,使用上面的服务文件,连接字符串service=mydb port=5434将使用主机somehost,端口5434, - 用户admin,以及由环境变量或内置默认所设置的其他参数。 + 从服务文件中获取的连接参数会与其他来源的参数合并。服务文件中的设置会覆盖相应的环境变量,而连接字符串中直接给出的值又会覆盖服务文件中的设置。例如,使用上述服务文件时,连接字符串 service=mydb port=5434 将使用主机 somehost、端口 5434、用户 admin,以及由环境变量或内置默认值设置的其他参数。 @@ -5568,7 +5479,7 @@ ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase) 你也可以将常规的服务文件条目和 LDAP 查找混合。pg_service.conf中一节的完整示例: -# 只有主机和端口存储在LDAP中,显式指定dbname和user。 +# 仅 host 和 port 存储在 LDAP 中;显式指定 dbname 和 user [customerdb] dbname=customer user=appuser @@ -5593,13 +5504,13 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 服务器证书的客户端验证 + 客户端对服务器证书的验证 - 默认情况下,PostgreSQL将不会执行服务器证书的任何验证。这意味着可以在不被客户端知晓的情况下伪造服务器身份(例如通过修改一个 DNS 记录或者接管服务器的 IP 地址)。为了阻止哄骗,客户端必须能够通过一条信任链验证服务器的身份。信任链可以这样建立:在一台计算机上放置一个根(自签名的)证书机构(CA)的证书并且在另一台计算机上放置一个由根证书签发的叶子证书。还可以使用一种中间证书,它由根证书签发并且可以签发叶子证书。 + 默认情况下,PostgreSQL 不会对服务器证书执行任何验证。这意味着可以在客户端不知情的情况下伪造服务器身份,例如修改 DNS 记录或接管服务器的 IP 地址。要防止身份伪造,客户端必须能够通过信任链验证服务器身份。建立信任链的方法是:在一台计算机上放置根证书机构(CA)的自签名证书,在另一台计算机上放置由根证书签发的叶证书。也可以使用由根证书签发、又用于签发叶证书的中间证书。 - 要让客户端验证服务器的身份,请在客户端放置根证书,并在服务器上放置由该根证书签名的叶证书。要让服务器验证客户端的身份,请在服务器上放置根证书,并在客户端放置由该根证书签名的叶证书。也可以使用一个或多个中间证书(通常与叶证书存储在一起),将叶证书链接到根证书。 + 要让客户端验证服务器的身份,请在客户端放置根证书,并在服务器上放置由该根证书签发的叶证书。要让服务器验证客户端的身份,请在服务器上放置根证书,并在客户端放置由该根证书签发的叶证书。也可以使用一个或多个中间证书(通常与叶证书存储在一起),将叶证书链接到根证书。 建立信任链后,客户端可以通过两种方式验证服务器发送的叶证书。如果参数 sslmode 设为 verify-ca,libpq 会沿证书链检查到存储在客户端上的根证书,以验证服务器是否可信。如果 sslmode 设为 verify-full,libpq 还会验证服务器主机名是否与服务器证书中存储的名称匹配。如果无法验证服务器证书,SSL 连接将失败。在大多数对安全敏感的环境中,建议使用 verify-full @@ -5618,8 +5529,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 为了与 PostgreSQL 的早期版本达到向后兼容,如果存在一个根 CA 文件,sslmode=require的行为将与verify-ca相同,即服务器证书根据 CA 验证。我们鼓励依赖这种行为,并且需要证书验证的应用应该总是使用verify-ca或者verify-full。 - + 为与 PostgreSQL 的早期版本向后兼容,如果存在根 CA 文件,sslmode=require 的行为将与 verify-ca 相同,即根据 CA 验证服务器证书。不建议依赖这种行为;需要证书验证的应用程序应始终使用 verify-caverify-full。 + @@ -5627,51 +5538,36 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 客户端证书 - 如果服务器尝试通过请求客户端的叶证书来验证客户端的身份, - libpq将发送存储在文件 - ~/.postgresql/postgresql.crt中的证书,该文件位于用户的主目录中。 - 证书必须链到服务器信任的根证书。匹配的 - 私钥文件~/.postgresql/postgresql.key也必须存在。 - 在Microsoft Windows上,这些文件的名称分别为 - %APPDATA%\postgresql\postgresql.crt和 - %APPDATA%\postgresql\postgresql.key。 - 证书和密钥文件的位置可以通过连接参数 - sslcertsslkey, - 或通过环境变量PGSSLCERTPGSSLKEY来覆盖。 - + 如果服务器请求客户端的叶证书以验证客户端身份,libpq 将发送用户主目录下 ~/.postgresql/postgresql.crt 文件中存储的证书。这些证书必须通过证书链连接到服务器信任的根证书。还必须存在匹配的私钥文件 ~/.postgresql/postgresql.key。在 Microsoft Windows 上,这两个文件分别名为 %APPDATA%\postgresql\postgresql.crt%APPDATA%\postgresql\postgresql.key。可以通过连接参数 sslcertsslkey,或环境变量 PGSSLCERTPGSSLKEY,覆盖证书和密钥文件的位置。 + - 在Unix系统上,私钥文件的权限必须禁止任何对世界或组的访问;可以通过类似以下命令来实现: - chmod 0600 ~/.postgresql/postgresql.key。 - 或者,该文件可以由root拥有并具有组读取权限(即0640权限)。 - 该设置适用于由操作系统管理证书和密钥文件的安装。然后,libpq的用户应该成为具有对这些证书和密钥文件访问权限的组的成员。 - (在Microsoft Windows上,没有文件权限检查,因为假定%APPDATA%\postgresql目录是安全的。) - + 在 Unix 系统上,私钥文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.postgresql/postgresql.key 这样的命令实现。另一种做法是使文件归 root 所有,并允许组用户读取(即 0640 权限)。这种设置适用于由操作系统管理证书和密钥文件的安装环境。此时,应将 libpq 用户加入有权访问这些证书和密钥文件的组。(在 Microsoft Windows 上,不检查文件权限,因为假定 %APPDATA%\postgresql 目录是安全的。) + postgresql.crt中的第一个证书必须是客户端的证书,因为它必须匹配客户端的私钥。可以选择将中间证书追加到该文件 — 这样做避免了在服务器上存放中间证书的要求()。 - 证书和密钥可能是 PEM 或 ASN.1 DER 格式。 + 证书和密钥可以采用 PEM 或 ASN.1 DER 格式。 - 密钥可以以明文存储,也可以使用OpenSSL支持的任何算法(例如AES-128)使用密码进行加密。 - 如果密钥是加密存储的,那么可以在连接选项中提供密码。 - 如果提供了加密密钥,而且sslpassword选项不存在或为空,那么只要 TTY 可用,OpenSSL就会以Enter PEM pass phrase:提示交互式输入密码。 - 应用程序可以通过提供自己的密钥密码回调,覆盖客户端证书提示以及sslpassword参数的处理;参见。 + 密钥可以以明文存储,也可以使用密码,按 OpenSSL 支持的任意算法(例如 AES-128)进行加密。如果密钥以加密形式存储,可以在 连接选项中提供密码。如果提供了加密密钥,而 sslpassword 选项缺失或为空,则在有 TTY 可用时,OpenSSL 会显示 Enter PEM pass phrase: 提示,交互式地请求输入密码。应用程序可以提供自己的密钥密码回调,以覆盖客户端证书提示及 sslpassword 参数的处理;参见 - 创建证书的指令请参考。 + 有关创建证书的说明,请参见 不同模式中提供的保护 - sslmode参数选择不同的值可以提供不同程度的保护。SSL 可以防范三类攻击: + + sslmode 参数的不同值提供不同级别的保护。SSL 可以防范三类攻击: + 窃听 @@ -5683,31 +5579,33 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 中间人(MITM - 如果一个第三方能对客户端和服务器之间传送的数据进行修改,它就能假装是服务器并且因此能看见并且修改数据,即使这些数据已被加密。然后第三方可以将连接信息和数据转送给原来的服务器,使得它不可能检测到攻击。这样做的通常途径包括 DNS 污染和地址劫持,借此客户端被重定向到一个不同的服务器。还有几种其他的攻击方式能够完成这种攻击。SSL使用证书验证让客户端认证服务器,就可以阻止这种攻击。 - + + 如果第三方能修改客户端与服务器之间传输的数据,就可以冒充服务器,进而查看和修改数据,即使数据已经加密。随后,第三方可以将连接信息和数据转发给原来的服务器,使攻击无法被察觉。常见的手段包括 DNS 污染和地址劫持,从而将客户端引向预期之外的服务器。还有其他几种攻击手段可以达到同样的目的。SSL 使用证书验证,让客户端认证服务器身份,以防范这种攻击。 + - 模仿 + 冒充 - 如果一个第三方能假装是一个授权的客户端,它能够简单地访问它本不能访问的数据。通常这可以由不安全的密码管理所致。SSL使用客户端证书来确保只有持有合法证书的客户端才能访问服务器,这样就能阻止这种攻击。 - + + 如果第三方能冒充获授权的客户端,就能直接访问其无权访问的数据。这通常可能由不安全的密码管理导致。SSL 使用客户端证书,确保只有持有有效证书的客户端才能访问服务器,以防范这种攻击。 + - 对于一个已知受 SSL 保护的连接,在连接建立之前,必须在客户端和服务器两端都配置 SSL。如果只在服务器端配置,客户端在得知服务器要求高安全性之前,可能就已经开始发送敏感信息(例如密码)。在 libpq 中,要确保连接安全,可以把sslmode参数设置为verify-fullverify-ca,并为系统提供一个用于验证的根证书。这类似于使用https URL浏览加密网页。 + 要确保连接受到 SSL 保护,必须在建立连接之前,在客户端和服务器两端配置 SSL。如果仅在服务器上配置,客户端可能在得知服务器要求高安全性之前就已发送敏感信息(例如密码)。在 libpq 中,可以将 sslmode 参数设为 verify-fullverify-ca,并向系统提供用于验证的根证书,以确保连接安全。这类似于使用 https URL 进行加密的网页浏览。 - 一旦服务器已经被认证,客户端可以传递敏感数据。这意味着直到这一点,客户端都不需要知道是否证书将被用于认证,这样只需要在服务器配置中指定就比较安全。 + 服务器通过身份认证后,客户端便可以传送敏感数据。这意味着,在此之前,客户端无需知道是否会使用证书进行认证,因此可以安全地仅在服务器配置中指定这一点。 - 所有SSL选项都带来了加密和密钥交换的负荷,因此必须在性能和安全性之间做出平衡。不同sslmode值所保护的风险,以及它们是怎样看待安全性和负荷的。 + 所有 SSL 选项都会产生加密和密钥交换的开销,因此必须在性能与安全性之间作出权衡。 说明了不同 sslmode 值所能防范的风险,以及它们所表达的对安全性和开销的取舍。
@@ -5732,7 +5630,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) disable - 我不关心安全性,并且我不想为加密增加负荷。 + 我不关心安全性,并且我不想为加密增加开销。 @@ -5740,7 +5638,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) allow 可能 - 我不关心安全性,但如果服务器坚持,我将承担加密带来的负荷。 + 我不关心安全性,但如果服务器坚持,我将承担加密带来的开销。 @@ -5748,7 +5646,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) prefer 可能 - 我不关心安全性,但如果服务器支持,我希望承担加密带来的负荷。 + 我不关心加密,但如果服务器支持,我希望承担加密带来的开销。 @@ -5756,7 +5654,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) require - 我想要对数据加密,并且我接受因此带来的负荷。我信任该网络会保证我总是连接到想要连接的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我信任该网络会保证我总是连接到想要连接的服务器。 @@ -5764,7 +5662,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-ca 取决于 CA 策略 - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器。 @@ -5772,7 +5670,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-full - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 @@ -5785,7 +5683,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - sslmode的默认值是prefer。如表中所示,这在安全性的角度来说没有意义,并且它只承诺可能的性能负荷。提供它作为默认值只是为了向后兼容,并且我们不推荐在安全部署中使用它。 + sslmode 的默认值是 prefer。如表所示,从安全角度看,这一设置没有意义;它只会在可能时带来性能开销。将其作为默认值仅出于向后兼容的考虑,不建议在有安全要求的部署中使用。 @@ -5827,8 +5725,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) ~/.postgresql/root.crt - 可信的证书机构 - 检查服务器证书是由一个可信的证书机构签发 + 受信任的证书机构 + 检查服务器证书是由一个受信任的证书机构签发 @@ -5846,9 +5744,9 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) SSL 库初始化 - 如果您的应用程序初始化libssl和/或libcrypto库,并且libpq - 构建时带有SSL支持,您应该调用告诉libpq - libssl和/或libcrypto库已被您的应用程序初始化,以便 + 如果你的应用程序初始化libssl和/或libcrypto库,并且libpq + 构建时带有SSL支持,你应该调用告诉libpq + libssl和/或libcrypto库已被你的应用程序初始化,以便 libpq不会再初始化这些库。 但是,当使用OpenSSL版本1.1.0或更高版本时,无需这样做,因为重复初始化不再成问题。 @@ -5860,7 +5758,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 允许应用选择要初始化哪个安全性库。 + 允许应用程序选择要初始化的安全库。 void PQinitOpenSSL(int do_ssl, int do_crypto); @@ -5884,7 +5782,7 @@ void PQinitOpenSSL(int do_ssl, int do_crypto); PQinitSSLPQinitSSL - 允许应用选择要初始化哪个安全性库。 + 允许应用程序选择要初始化的安全库。 void PQinitSSL(int do_ssl); @@ -5909,7 +5807,7 @@ void PQinitSSL(int do_ssl); - 在线程化程序中的行为 + 多线程程序中的行为 线程 @@ -5943,7 +5841,9 @@ int PQisthreadsafe(); PGresult对象在创建后通常是只读的,因此可以在线程之间自由传递。不过,如果你使用中描述的任何会修改PGresult的函数,则需要自行避免对同一个PGresult执行并发操作。 - 已弃用的 函数不是线程安全的,不应在多线程程序中使用。可以用 替代 ,用 替代 + + 已弃用的函数 不是线程安全的,不应在多线程程序中使用。 可以用 替代; 可以用 替代。 + 如果你在应用程序中使用 Kerberos(除了libpq内部之外),则需要在 Kerberos 调用周围加锁,因为 Kerberos 函数不是线程安全的。可参考libpq源代码中的PQregisterThreadLock函数,它提供了一种在libpq与应用程序之间协作加锁的方法。 @@ -5953,7 +5853,7 @@ int PQisthreadsafe(); - 编译 <application>libpq</application> 程序 + 构建 <application>libpq</application> 程序 编译 @@ -5961,16 +5861,16 @@ int PQisthreadsafe(); - 要编译(即编译并且链接)一个使用libpq的程序,你需要做下列所有的事情: + 要构建(即编译和链接)一个使用 libpq 的程序,需要完成以下所有步骤: - 包括libpq-fe.h头文件: + 包含 libpq-fe.h 头文件: #include <libpq-fe.h> - 如果你无法这样做,那么你通常会从你的编译器得到像这样的错误消息: +如果没有这样做,编译器通常会给出类似以下内容的错误消息: foo.c: In function `main': foo.c:34: `PGconn' undeclared (first use in this function) @@ -5979,24 +5879,24 @@ foo.c:54: `CONNECTION_BAD' undeclared (first use in this function) foo.c:68: `PGRES_COMMAND_OK' undeclared (first use in this function) foo.c:95: `PGRES_TUPLES_OK' undeclared (first use in this function) - + - 通过为你的编译器提供-Idirectory选项,向你的编译器指出PostgreSQL头文件安装在哪里(在某些情况下编译器默认将查看该目录,因此你可以忽略这个选项)。例如你的编译命令行可能看起来像: + 向编译器提供 -Idirectory 选项,指定 PostgreSQL 头文件的安装目录。(某些情况下,编译器默认会搜索该目录,此时可以省略这个选项。)例如,编译命令行可以是: cc -c -I/usr/local/pgsql/include testprog.c - 如果你在使用 makefile,那么把该选项加到CPPFLAGS变量中: +如果使用 makefile,请将该选项添加到 CPPFLAGS 变量中: CPPFLAGS += -I/usr/local/pgsql/include - + 如果你的程序可能由其他用户编译,那么你不应该像那样硬编码目录位置。你可以运行工具pg_configpg_configwith libpq在本地系统上找出头文件在哪里: + sortas="libpq">用于 libpq在本地系统上找出头文件在哪里: $ pg_config --includedir /usr/local/include @@ -6004,8 +5904,7 @@ CPPFLAGS += -I/usr/local/pgsql/include - 如果你安装了pkg-configpkg-configwith - libpq,你可以运行: + 如果你安装了pkg-configpkg-config用于 libpq,你可以运行: $ pkg-config --cflags libpq -I/usr/local/include @@ -6014,20 +5913,20 @@ CPPFLAGS += -I/usr/local/pgsql/include - 无法为编译器指定正确的选项将导致一个错误消息,例如: + 未向编译器指定正确的选项将导致类似以下内容的错误消息: testlibpq.c:8:22: libpq-fe.h: No such file or directory - + - 当链接最终的程序时,指定选项-lpq,这样libpq库会被编译进去,也可以用选项-Ldirectory向编译器指出libpq库所在的位置(再次,编译器将默认搜索某些目录)。为了最大的可移植性,将选项放在选项前面。例如: + 链接最终程序时,指定 -lpq 选项以链接 libpq 库,同时指定 -Ldirectory 选项,告知编译器 libpq 库所在的目录。(同样,编译器默认会搜索某些目录。)为获得最大的可移植性,请将 选项放在 选项之前。例如: cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq - + 你也可以使用pg_config找出库目录: @@ -6054,7 +5953,7 @@ testlibpq.o(.text+0x60): undefined reference to `PQsetdbLogin' testlibpq.o(.text+0x71): undefined reference to `PQstatus' testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' - 这意味着你忘了 . + 这意味着你忘记了 /usr/bin/ld: cannot find -lpq @@ -6071,7 +5970,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' 示例程序 - 这些示例和其他示例可以在源代码发布的src/test/examples目录中找到。 + 这些示例和其他示例可在源代码发行包的src/test/examples目录中找到。 @@ -6085,7 +5984,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' * * testlibpq.c * - * Test the C version of libpq, the PostgreSQL frontend library. + * 测试 PostgreSQL 前端库 libpq 的 C 语言版本。 */ #include #include @@ -6109,19 +6008,18 @@ main(int argc, char **argv) j; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "Connection to database failed: %s", @@ -6129,7 +6027,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -6140,19 +6038,17 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Our test case here involves using a cursor, for which we must be inside - * a transaction block. We could do the whole thing with a single - * PQexec() of "select * from pg_database", but that's too trivial to make - * a good example. + * 这里的测试用例使用游标,因此必须处于事务块内。 + * 只需调用一次 PQexec() 执行 "select * from pg_database" 就能完成全部操作, + * 但这太简单了,不足以作为一个好的示例。 */ - /* Start a transaction block */ + /* 开始一个事务块 */ res = PQexec(conn, "BEGIN"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -6163,7 +6059,7 @@ main(int argc, char **argv) PQclear(res); /* - * Fetch rows from pg_database, the system catalog of databases + * 从数据库系统目录 pg_database 中获取行 */ res = PQexec(conn, "DECLARE myportal CURSOR FOR select * from pg_database"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -6182,13 +6078,13 @@ main(int argc, char **argv) exit_nicely(conn); } - /* first, print out the attribute names */ + /* 首先,打印属性名 */ nFields = PQnfields(res); for (i = 0; i < nFields; i++) printf("%-15s", PQfname(res, i)); printf("\n\n"); - /* next, print out the rows */ + /* 接着,打印各行 */ for (i = 0; i < PQntuples(res); i++) { for (j = 0; j < nFields; j++) @@ -6198,15 +6094,15 @@ main(int argc, char **argv) PQclear(res); - /* close the portal ... we don't bother to check for errors ... */ + /* 关闭 portal……这里不再检查错误…… */ res = PQexec(conn, "CLOSE myportal"); PQclear(res); - /* end the transaction */ + /* 结束事务 */ res = PQexec(conn, "END"); PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -6225,15 +6121,15 @@ main(int argc, char **argv) * * * testlibpq2.c - * Test of the asynchronous notification interface + * 测试异步通知接口 * - * Start this program, then from psql in another window do + * 启动此程序,然后在另一个窗口中通过 psql 执行 * NOTIFY TBL2; - * Repeat four times to get this program to exit. + * 重复四次后,此程序便会退出。 * - * Or, if you want to get fancy, try this: - * populate a database with the following commands - * (provided in src/test/examples/testlibpq2.sql): + * 或者,可以尝试更复杂的示例: + * 使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq2.sql 中): * * CREATE SCHEMA TESTLIBPQ2; * SET search_path = TESTLIBPQ2; @@ -6242,7 +6138,7 @@ main(int argc, char **argv) * CREATE RULE r1 AS ON INSERT TO TBL1 DO * (INSERT INTO TBL2 VALUES (new.i); NOTIFY TBL2); * - * Start this program, then from psql do this four times: + * 启动此程序,然后通过 psql 将以下命令执行四次: * * INSERT INTO TESTLIBPQ2.TBL1 VALUES (10); */ @@ -6279,19 +6175,18 @@ main(int argc, char **argv) int nnotifies; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "Connection to database failed: %s", @@ -6299,7 +6194,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -6310,13 +6205,12 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Issue LISTEN command to enable notifications from the rule's NOTIFY. + * 发出 LISTEN 命令,以接收规则中的 NOTIFY 发出的通知。 */ res = PQexec(conn, "LISTEN TBL2"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -6327,14 +6221,13 @@ main(int argc, char **argv) } PQclear(res); - /* Quit after four notifies are received. */ + /* 收到四次通知后退出。 */ nnotifies = 0; while (nnotifies < 4) { /* - * Sleep until something happens on the connection. We use select(2) - * to wait for input, but you could also use poll() or similar - * facilities. + * 休眠,直到连接上有事件发生。这里使用 select(2) 等待输入, + * 也可以使用 poll() 或类似机制。 */ int sock; fd_set input_mask; @@ -6342,7 +6235,7 @@ main(int argc, char **argv) sock = PQsocket(conn); if (sock < 0) - break; /* shouldn't happen */ + break; /* 不应发生 */ FD_ZERO(&input_mask); FD_SET(sock, &input_mask); @@ -6353,7 +6246,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Now check for input */ + /* 现在检查是否有输入 */ PQconsumeInput(conn); while ((notify = PQnotifies(conn)) != NULL) { @@ -6368,7 +6261,7 @@ main(int argc, char **argv) fprintf(stderr, "Done.\n"); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -6387,10 +6280,10 @@ main(int argc, char **argv) * * * testlibpq3.c - * Test out-of-line parameters and binary I/O. + * 测试在 SQL 命令文本之外独立传递的参数和二进制 I/O。 * - * Before running this, populate a database with the following commands - * (provided in src/test/examples/testlibpq3.sql): + * 运行前,使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq3.sql 中): * * CREATE SCHEMA testlibpq3; * SET search_path = testlibpq3; @@ -6399,7 +6292,7 @@ main(int argc, char **argv) * INSERT INTO test1 values (1, 'joe''s place', '\000\001\002\003\004'); * INSERT INTO test1 values (2, 'ho there', '\004\003\002\001\000'); * - * The expected output is: + * 预期输出为: * * tuple 0: got * i = (4 bytes) 1 @@ -6423,7 +6316,7 @@ main(int argc, char **argv) #include #include "libpq-fe.h" -/* for ntohl/htonl */ +/* 用于 ntohl/htonl */ #include #include @@ -6436,9 +6329,8 @@ exit_nicely(PGconn *conn) } /* - * This function prints a query result that is a binary-format fetch from - * a table defined as in the comment above. We split it out because the - * main() function uses it twice. + * 此函数打印从上面注释所定义的表中以二进制格式获取的查询结果。 + * 由于 main() 会使用它两次,因此将它单独提取成一个函数。 */ static void show_binary_results(PGresult *res) @@ -6449,7 +6341,7 @@ show_binary_results(PGresult *res) t_fnum, b_fnum; - /* Use PQfnumber to avoid assumptions about field order in result */ + /* 使用 PQfnumber,以避免对结果中的字段顺序作出假设 */ i_fnum = PQfnumber(res, "i"); t_fnum = PQfnumber(res, "t"); b_fnum = PQfnumber(res, "b"); @@ -6462,24 +6354,22 @@ show_binary_results(PGresult *res) int blen; int ival; - /* Get the field values (we ignore possibility they are null!) */ + /* 获取字段值(这里忽略它们可能为 null 的情况!) */ iptr = PQgetvalue(res, i, i_fnum); tptr = PQgetvalue(res, i, t_fnum); bptr = PQgetvalue(res, i, b_fnum); /* - * The binary representation of INT4 is in network byte order, which - * we'd better coerce to the local byte order. + * INT4 的二进制表示采用网络字节序,最好将其转换为本机字节序。 */ ival = ntohl(*((uint32_t *) iptr)); /* - * The binary representation of TEXT is, well, text, and since libpq - * was nice enough to append a zero byte to it, it'll work just fine - * as a C string. + * TEXT 的二进制表示就是文本,而 libpq 会在其后追加一个零字节, + * 因此可以直接将其用作 C 字符串。 * - * The binary representation of BYTEA is a bunch of bytes, which could - * include embedded nulls so we have to pay attention to field length. + * BYTEA 的二进制表示是一组字节,其中可能嵌有零字节, + * 因此必须注意字段长度。 */ blen = PQgetlength(res, i, b_fnum); @@ -6507,19 +6397,18 @@ main(int argc, char **argv) uint32_t binaryIntVal; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "Connection to database failed: %s", @@ -6527,7 +6416,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SET search_path = testlibpq3"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -6538,27 +6427,25 @@ main(int argc, char **argv) PQclear(res); /* - * The point of this program is to illustrate use of PQexecParams() with - * out-of-line parameters, as well as binary transmission of data. + * 此程序旨在演示如何使用 PQexecParams() 在 SQL 命令文本之外独立传递参数, + * 以及如何以二进制方式传输数据。 * - * This first example transmits the parameters as text, but receives the - * results in binary format. By using out-of-line parameters we can avoid - * a lot of tedious mucking about with quoting and escaping, even though - * the data is text. Notice how we don't have to do anything special with - * the quote mark in the parameter value. + * 第一个示例以文本形式传输参数,但以二进制格式接收结果。 + * 通过在 SQL 命令文本之外独立传递参数,即使数据是文本,也可以避免 + * 许多繁琐的引号和转义处理。注意,参数值中的引号无需任何特殊处理。 */ - /* Here is our out-of-line parameter value */ + /* 这是在 SQL 命令文本之外独立传递的参数值 */ paramValues[0] = "joe's place"; res = PQexecParams(conn, "SELECT * FROM test1 WHERE t = $1", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, - NULL, /* don't need param lengths since text */ - NULL, /* default to all text params */ - 1); /* ask for binary results */ + NULL, /* 文本参数无需指定长度 */ + NULL, /* 默认所有参数均为文本 */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -6572,31 +6459,29 @@ main(int argc, char **argv) PQclear(res); /* - * In this second example we transmit an integer parameter in binary form, - * and again retrieve the results in binary form. + * 第二个示例以二进制形式传输一个整数参数,并同样以二进制形式获取结果。 * - * Although we tell PQexecParams we are letting the backend deduce - * parameter type, we really force the decision by casting the parameter - * symbol in the query text. This is a good safety measure when sending - * binary parameters. + * 虽然我们告诉 PQexecParams 让后端推断参数类型,但实际上, + * 查询文本中的参数符号经过强制类型转换,因此其类型已经确定。 + * 发送二进制参数时,这是一项良好的安全措施。 */ - /* Convert integer value "2" to network byte order */ + /* 将整数值 "2" 转换为网络字节序 */ binaryIntVal = htonl((uint32_t) 2); - /* Set up parameter arrays for PQexecParams */ + /* 为 PQexecParams 设置参数数组 */ paramValues[0] = (char *) &binaryIntVal; paramLengths[0] = sizeof(binaryIntVal); - paramFormats[0] = 1; /* binary */ + paramFormats[0] = 1; /* 二进制 */ res = PQexecParams(conn, "SELECT * FROM test1 WHERE i = $1::int4", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, paramLengths, paramFormats, - 1); /* ask for binary results */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -6609,7 +6494,7 @@ main(int argc, char **argv) PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; diff --git a/zh/13/lobj.sgml b/zh/13/lobj.sgml index 7ec0267c..b3cd20f0 100644 --- a/zh/13/lobj.sgml +++ b/zh/13/lobj.sgml @@ -3,8 +3,8 @@ 大对象 - large object - BLOBlarge object + 大对象 + BLOB大对象 PostgreSQL提供一种大对象机制,允许以流式方式访问存储在专用大对象结构中的用户数据。在处理大到无法方便地整体操作的数据值时,这种流式访问非常有用。 @@ -19,7 +19,7 @@ TOAST - versus large objects + 与大对象对比 @@ -188,11 +188,11 @@ inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE); int lo_write(PGconn *conn, int fd, const char *buf, size_t len); - 将buf中的len字节(其大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 + 将buf中的len字节(缓冲区大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -209,7 +209,7 @@ int lo_read(PGconn *conn, int fd, char *buf, size_t len); - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -275,7 +275,7 @@ pg_int64 lo_tell64(PGconn *conn, int fd); int lo_truncate(PGconn *conn, int fd, size_t len); - 该函数把大对象描述符fd截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用空字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 + 该函数把大对象描述符fd对应的大对象截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用零字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 @@ -424,16 +424,16 @@ CREATE TABLE image ( raster oid ); -SELECT lo_creat(-1); -- returns OID of new, empty large object +SELECT lo_creat(-1); -- 返回新建的空大对象的 OID -SELECT lo_create(43213); -- attempts to create large object with OID 43213 +SELECT lo_create(43213); -- 尝试创建 OID 为 43213 的大对象 -SELECT lo_unlink(173454); -- deletes large object with OID 173454 +SELECT lo_unlink(173454); -- 删除 OID 为 173454 的大对象 INSERT INTO image (name, raster) VALUES ('beautiful image', lo_import('/etc/motd')); -INSERT INTO image (name, raster) -- same as above, but specify OID to use +INSERT INTO image (name, raster) -- 与上例相同,但指定要使用的 OID VALUES ('beautiful image', lo_import('/etc/motd', 68583)); SELECT lo_export(image.raster, '/tmp/motd') FROM image @@ -442,7 +442,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image - 服务器端的lo_importlo_export函数与其客户端对应函数的行为差异很大。这两个函数在服务器的文件系统中读写文件,使用数据库所有者的权限。因此,默认情况下它们的使用仅限于超级用户。相比之下,客户端导入和导出函数在客户端的文件系统中读写文件,使用客户端程序的权限。客户端函数不需要任何数据库权限,除了读取或写入相关大对象所需的权限。 + 服务器端的lo_importlo_export函数与其客户端对应函数的行为差异很大。这两个函数在服务器的文件系统中读写文件,使用运行数据库服务器的操作系统用户的权限。因此,默认情况下它们的使用仅限于超级用户。相比之下,客户端导入和导出函数在客户端的文件系统中读写文件,使用客户端程序的权限。客户端函数不需要任何数据库权限,除了读取或写入相关大对象所需的权限。 @@ -461,7 +461,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image 示例程序 - 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行版的src/test/examples/testlo.c中找到。 + 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行包的src/test/examples/testlo.c中找到。 @@ -470,13 +470,13 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /*----------------------------------------------------------------- * * testlo.c - * test using large objects with libpq + * 测试使用 libpq 操作大对象 * * Portions Copyright (c) 1996-2020, PostgreSQL Global Development Group * Portions Copyright (c) 1994, Regents of the University of California * * - * IDENTIFICATION + * 标识 * src/test/examples/testlo.c * *----------------------------------------------------------------- @@ -496,7 +496,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /* * importFile - - * import file "in_filename" into database as large object "lobjOid" + * 将文件 "in_filename" 作为大对象 "lobjOid" 导入数据库 * */ static Oid @@ -510,16 +510,16 @@ importFile(PGconn *conn, char *filename) int fd; /* - * open the file to be read in + * 打开要读取的文件 */ fd = open(filename, O_RDONLY, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"\n", filename); } /* - * create the large object + * 创建大对象 */ lobjId = lo_creat(conn, INV_READ | INV_WRITE); if (lobjId == 0) @@ -528,7 +528,7 @@ importFile(PGconn *conn, char *filename) lobj_fd = lo_open(conn, lobjId, INV_WRITE); /* - * read in from the Unix file and write to the inversion file + * 从 Unix 文件读取数据并写入大对象 */ while ((nbytes = read(fd, buf, BUFSIZE)) > 0) { @@ -566,7 +566,7 @@ pickout(PGconn *conn, Oid lobjId, int start, int len) fprintf(stderr, ">>> %s", buf); nread += nbytes; if (nbytes <= 0) - break; /* no more data? */ + break; /* 没有更多数据? */ } free(buf); fprintf(stderr, "\n"); @@ -612,7 +612,7 @@ overwrite(PGconn *conn, Oid lobjId, int start, int len) /* * exportFile - - * export large object "lobjOid" to file "out_filename" + * 将大对象 "lobjOid" 导出到文件 "out_filename" * */ static void @@ -625,24 +625,24 @@ exportFile(PGconn *conn, Oid lobjId, char *filename) int fd; /* - * open the large object + * 打开大对象 */ lobj_fd = lo_open(conn, lobjId, INV_READ); if (lobj_fd < 0) fprintf(stderr, "cannot open large object %u", lobjId); /* - * open the file to be written to + * 打开要写入的文件 */ fd = open(filename, O_CREAT | O_WRONLY | O_TRUNC, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"", filename); } /* - * read in from the inversion file and write to the Unix file + * 从大对象读取数据并写入 Unix 文件 */ while ((nbytes = lo_read(conn, lobj_fd, buf, BUFSIZE)) > 0) { @@ -689,11 +689,11 @@ main(int argc, char **argv) out_filename = argv[3]; /* - * set up the connection + * 建立连接 */ conn = PQsetdb(NULL, NULL, NULL, NULL, database); - /* check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "Connection to database failed: %s", @@ -701,7 +701,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) diff --git a/zh/13/monitoring.sgml b/zh/13/monitoring.sgml index b634ce44..2da6fc70 100644 --- a/zh/13/monitoring.sgml +++ b/zh/13/monitoring.sgml @@ -2906,7 +2906,8 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i checksum_failures bigint - 在此数据库(或共享对象)中检测到的数据页校验码失败数,如果没有启用数据校验码则为NULL。 + 在此数据库(或共享对象)中检测到的数据页校验和失败次数,如果未启用 + 数据校验和则为 NULL。 @@ -2915,7 +2916,8 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i checksum_last_failure timestamp with time zone - 在此数据库(或共享对象)中检测到最后一个数据页校验码失败的时间,如果没有启用数据校验码则为NULL。 + 在此数据库(或共享对象)中最后一次检测到数据页校验和失败的时间, + 如果未启用数据校验和则为 NULL。 diff --git a/zh/13/pgtrgm.sgml b/zh/13/pgtrgm.sgml index 762ba8a6..42a452a5 100644 --- a/zh/13/pgtrgm.sgml +++ b/zh/13/pgtrgm.sgml @@ -422,11 +422,11 @@ SELECT * FROM test_trgm WHERE t ~ '(foo|bar)'; - 文本搜索集成 + 文本检索集成 与全文索引结合使用时,三字符组匹配是非常有用的工具。 - 尤其是,它有助于识别那些因拼写错误而无法被全文搜索机制直接匹配的输入词。 + 尤其是,它有助于识别那些因拼写错误而无法被全文检索机制直接匹配的输入词。 diff --git a/zh/13/protocol.sgml b/zh/13/protocol.sgml index 856f9698..68210450 100644 --- a/zh/13/protocol.sgml +++ b/zh/13/protocol.sgml @@ -33,7 +33,7 @@ - 会话通常由前端选择终止,但在某些情况下也可能由后端强制终止。无论哪种情况,后端在关闭连接前都会回滚所有打开的(未完成的)事务。 + 会话通常由前端选择终止,但在某些情况下也可能由后端强制终止。无论哪种情况,后端关闭连接时,都会在退出前回滚所有打开的(未完成的)事务。 @@ -72,9 +72,7 @@ 整个执行周期包括一个解析步骤,它从文本查询字符串创建预备语句; 一个绑定步骤,它根据预备语句和所需参数值创建 portal; - 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询 - (SELECTSHOW等),可以要求执行步骤只取回 - 有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 + 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询(SELECTSHOW等),可以要求执行步骤只取回有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 @@ -91,8 +89,8 @@ - 文本形式的数值是特定数据类型的输入/输出转换函数生成或接受的任何字符串。在传输形式上,字符串没有末尾空字符;如果前端要想把收到的值当作C字符串处理,那么必须自己加上一个(顺便说一下,文本格式不允许嵌入空字符)。 - + 值的文本表示是相应数据类型的输入/输出转换函数生成和接受的字符串。在传输形式中,值的末尾没有空字符;前端若要将收到的值作为 C 字符串处理,必须自行添加一个。(文本格式也不允许内嵌空字符。) + 整数的二进制表示采用网络字节序(最高有效字节在前)。至于其他数据类型,请查阅文档或源代码了解其二进制表示形式。要注意,复杂数据类型的二进制表示可能会在不同服务器版本之间发生变化;文本格式通常是可移植性更好的选择。 @@ -112,7 +110,7 @@ 启动 - 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,判断该连接在初步上是否可接受,以及是否需要额外的认证。 + 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,初步判断是否接受该连接,以及需要何种额外认证(如果需要)。 @@ -355,7 +353,7 @@ 表示即将返回行作为对SELECTFETCH等查询的响应。 - 此消息的内容描述了行的列布局。这将跟随每个返回给前端的行的DataRow消息。 + 此消息的内容描述了行的列布局。该消息之后,每个返回给前端的行都对应一条 DataRow 消息。 @@ -434,15 +432,15 @@ - 我们建议的方法是把前端代码写成状态机的风格,它可以在任何时刻接受任何有意义的消息类型,而不是假设消息的序列总是准确。 - + 建议以状态机的方式编写前端,使其能够在任何合理的时机接收相应类型的消息,而不把消息确切顺序的假设写死在代码中。 + 一个简单查询中的多条语句 - 当一个简单查询消息中包含多于一条SQL语句(被分号分隔)时,那些语句会被当做一个事务中执行,除非其中包括显式事务控制命令来强制不同的行为。例如,如果消息包括 + 当一个简单查询消息中包含多于一条SQL语句(被分号分隔)时,这些语句会作为单个事务执行,除非其中包括显式事务控制命令来强制不同的行为。例如,如果消息包括 INSERT INTO mytable VALUES(1); SELECT 1/0; @@ -464,15 +462,15 @@ SELECT 1/0; - 这种行为通过在一个隐式事务块中的一个多语句Query消息中运行那些语句来实现,除非它们运行在某个显式事务块中。隐式事务块与常规事务块之间的区别在于隐式块会在Query消息结束时自动被关闭,或者是在没有错误的情况下由一个隐式提交关闭,或者是在有错误时由一个隐式的回滚关闭。这类似于一个语句自己执行(当不在事务块中时)时发生的隐式提交或回滚。 - + 这种行为的实现方式是:除非已有显式事务块可供这些语句执行,否则就在一个隐式事务块中执行多语句 Query 消息中的语句。隐式事务块与常规事务块的主要区别在于,隐式块会在 Query 消息结束时自动关闭:没有错误时隐式提交,发生错误时隐式回滚。这类似于单独执行一条语句(不在事务块中)时发生的隐式提交或回滚。 + - 如果会话已经在一个事务块中,作为前面某个消息中BEGIN的结果,那么Query消息会简单地继续那个事务块,不管该消息包含一个语句还是多个语句。不过,如果该Query消息包含一个关闭现有事务块的COMMIT或者ROLLBACK,那么任何接下来的语句都会在一个隐式事务块中被执行。反过来,如果在多语句Query消息中出现一个BEGIN,那么它会开始一个常规事务块,这个常规事务块将只能被一个显式的COMMIT或者ROLLBACK终止,不管这两种命令是出现在这个Query消息还是后面的一个Query消息中。如果BEGIN跟在一些作为隐式事务块执行的语句后面,那些语句不会被立刻提交。实际上,它们会被包括到新的常规事务块中。 + 如果会话因前面某条消息中的BEGIN而已经处于事务块中,那么 Query 消息会继续该事务块,不管该消息包含一个语句还是多个语句。不过,如果该Query消息包含一个关闭现有事务块的COMMIT或者ROLLBACK,那么任何接下来的语句都会在一个隐式事务块中被执行。反过来,如果在多语句Query消息中出现一个BEGIN,那么它会开始一个常规事务块,这个常规事务块将只能被一个显式的COMMIT或者ROLLBACK终止,不管这两种命令是出现在这个Query消息还是后面的一个Query消息中。如果BEGIN跟在一些作为隐式事务块执行的语句后面,那些语句不会被立刻提交。实际上,它们会被包括到新的常规事务块中。 - 出现在一个隐式事务块中的COMMIT或者ROLLBACK会被正常执行并且关闭该隐式块。不过,由于没有先前的BEGIN配对的COMMIT或者ROLLBACK表示一种错误,所以将会发出一个警告。如果后面还有更多语句,将会为它们开始一个新的隐式事务块。 + 出现在一个隐式事务块中的COMMIT或者ROLLBACK会被正常执行并且关闭该隐式块。不过,由于没有先前的BEGIN配对的COMMIT或者ROLLBACK可能表示误操作,所以会发出警告。如果后面还有更多语句,将会为它们开始一个新的隐式事务块。 @@ -480,17 +478,17 @@ SELECT 1/0; - 记住,不管任何事务控制命令存不存在,Query消息的执行会在第一个错误时停止。因此,对于下面的在一个Query消息中的示例 + 请记住,无论消息中是否包含事务控制命令,Query 消息的执行都会在第一个错误处停止。例如,单条 Query 消息包含以下内容时: BEGIN; SELECT 1/0; ROLLBACK; - 会话中将留下一个失败的常规事务块,因为在出现除零错误后不会到达ROLLBACK。将需要另一个ROLLBACK把会话恢复到一种可用的状态。 - +会话会停留在失败的常规事务块内,因为发生除零错误后不会再执行ROLLBACK。需要另发一条ROLLBACK,才能将会话恢复到可用状态。 + - 另一种要注意的行为是,最初的词法和语法分析是在整个查询字符串被执行之前进行的。因此后面的语句中的简单错误(例如拼写错误的关键词)可能会阻止任何语句的执行。这通常对用户是不可见的,因为在当作一个隐式事务块执行时,这些语句不管怎样都会全部被回滚。不过,在尝试于一个多语句Query中执行多个事务时,这种现象可能是可见的。例如,如果一个拼写错误把我们之前的示例变成 + 另一种要注意的行为是,在执行任何语句之前,会先对整个查询字符串进行词法和语法分析。因此后面的语句中的简单错误(例如拼写错误的关键词)可能会阻止任何语句的执行。这通常对用户是不可见的,因为在当作一个隐式事务块执行时,这些语句不管怎样都会全部被回滚。不过,在尝试于一个多语句Query中执行多个事务时,这种现象可能是可见的。例如,如果一个拼写错误把我们之前的示例变成 BEGIN; INSERT INTO mytable VALUES(1); @@ -557,11 +555,11 @@ SELCT 1/0; - 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是执行不会导致后端发送 ReadyForQuery 或 RowDescription。 + 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是 Execute 不会导致后端发送 ReadyForQuery 或 RowDescription。 - 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息之一结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 + 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息中的恰好一条结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 @@ -576,7 +574,7 @@ SELCT 1/0; - 除了这些基本的、必须的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 + 除了这些基本的、必需的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 @@ -612,46 +610,40 @@ SELCT 1/0; - 流水线处理 + 管道化 - 流水线处理 + 管道化 协议规范 - 使用扩展查询协议允许流水线处理,这意味着发送一系列查询而无需等待先前的查询完成。 - 这减少了完成一系列操作所需的网络往返次数。然而,用户必须仔细考虑所需的行为,如果其中一步失败, - 因为后续查询已经在传输到服务器的过程中。 - + 扩展查询协议允许管道化,即连续发送一系列查询,而不等待先前查询完成。这减少了完成一组操作所需的网络往返次数。不过,用户必须仔细考虑其中某个步骤失败时所需的行为,因为后续查询已经在发往服务器的途中。 + - 处理这个问题的一种方法是将整个查询系列作为一个事务处理,即将其包装在BEGIN... - COMMIT中。然而,如果希望其中一些命令独立于其他命令提交,这并没有帮助。 - + 处理这个问题的一种方式是让整组查询成为单个事务,即用BEGIN ... COMMIT包围它们。不过,如果希望其中某些命令独立于其他命令提交,这种方式就无法满足要求。 + - 扩展查询协议提供了另一种管理这个问题的方式,即在依赖的步骤之间省略发送同步消息。 - 由于在错误后,后端会跳过命令消息直到找到同步消息,这允许在管道中的后续命令在前面的命令失败时自动跳过,而无需客户端明确地使用BEGINCOMMIT来管理。 - 管道中可以通过同步消息分隔独立可提交的段。 - + 扩展查询协议提供了另一种处理方式,即省略相互依赖的步骤之间的 Sync 消息。发生错误后,后端会跳过命令消息,直到遇到 Sync,因此当前面的命令失败时,管道中的后续命令便会自动跳过,而不必由客户端用BEGINCOMMIT显式管理。管道中可独立提交的各段可以用 Sync 消息分隔。 + - 如果客户端没有发出显式 BEGIN,则会启动一个隐式事务块。每个 Sync 通常会在前序步骤成功时导致隐式 COMMIT,失败时导致隐式 ROLLBACK。服务器只有在第一个命令结束且尚未收到 Sync 时,才能识别这种隐式事务块。有一些 DDL 命令(例如 CREATE DATABASE)不能在事务块内执行;若这类命令在管道中执行,除非它是某个 Sync 之后的第一条命令,否则会失败。此外,它成功后会强制立即提交以保持数据库一致性。因此,紧随这些命令之后的 Sync 除了返回 ReadyForQuery 外不会产生额外效果。 - + 如果客户端没有发出显式的BEGIN,那么每个 Sync 通常会在前序步骤成功时引发隐式的COMMIT,失败时引发隐式的ROLLBACK。不过,少数 DDL 命令(例如CREATE DATABASE)不能在事务块中执行。如果这类命令在管道中执行,除非它是管道中的第一条命令,否则会失败。此外,它成功后会强制立即提交,以保持数据库一致性。因此,紧随这类命令之后的 Sync 除了返回 ReadyForQuery 外,不产生其他效果。 + - 当使用这种方法时,必须通过计算ReadyForQuery消息的数量并等待达到发送的Syncs数量来确定管道的完成。 - 计算命令完成响应是不可靠的,因为其中一些命令可能会被跳过,因此不会产生完成消息。 - + 使用这种方式时,必须统计 ReadyForQuery 消息的数量,并等待该数量达到已发送的 Sync 消息数量,才能确定管道已完成。统计命令完成响应并不可靠,因为某些命令可能被跳过,因而不会产生完成消息。 + 函数调用 - 函数调用子协议允许客户端请求一个对存在于数据库pg_proc系统表中的任意函数的直接调用。客户端必须在该函数上有执行的权限。 - + 函数调用子协议允许客户端请求直接调用数据库pg_proc系统目录中的任意函数。客户端必须具有该函数的执行权限。 + @@ -661,8 +653,8 @@ SELCT 1/0; - 一个函数调用周期是由前端向后端发送一条FunctionCall消息初始化的。然后后端根据函数调用的结果发送一条或者更多响应消息,并且最后是一条ReadyForQuery响应消息。ReadyForQuery通知前端它可以安全地发送一个新的查询或者函数调用了。 - + 函数调用周期由前端向后端发送一条 FunctionCall 消息来启动。后端随后根据函数调用的结果发送一条或多条响应消息,最后发送一条 ReadyForQuery 响应消息。ReadyForQuery 告知前端,可以安全地发送新的查询或函数调用。 + 来自后端的可能的响应消息是: @@ -681,7 +673,7 @@ SELCT 1/0; FunctionCallResponse - 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者集合类型的结果)。 + 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者结果集合)。 @@ -715,7 +707,7 @@ SELCT 1/0; - 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(表示成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 + 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(允许成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 @@ -723,11 +715,11 @@ SELCT 1/0; - 在拷贝入模式下,后端将忽略所收到的Flush和Sync消息。收到任何其他非拷贝消息类型都会造成一个错误,它将导致上面所描述的拷贝入状态中断(Flush和Sync的例外是为了方便客户端库,它们总是在一个Execute消息之后发送Flush和Sync,而不检查被执行的命令是否为一个COPY FROM STDIN)。 - + 后端会忽略在拷贝入模式期间收到的 Flush 和 Sync 消息。收到任何其他非拷贝类型的消息都会构成错误,并按上述方式中止拷贝入状态。(Flush 和 Sync 的例外是为了方便那些总是在 Execute 消息之后发送 Flush 或 Sync、而不检查待执行命令是否为COPY FROM STDIN的客户端库。) + - 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句的时候初始化的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能退出传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 + 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句时启动的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能中止传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 @@ -735,16 +727,16 @@ SELCT 1/0; - 在CopyData消息中间可能会散布有NoticeResponse和ParameterStatus消息。前端必须处理这些情况,并且应该也为异步消息类型(参见)准备好。除此之外,可以将任何除 CopyData 或 CopyDone 以外的消息类型视为拷贝出模式的终止标志。 - + NoticeResponse 和 ParameterStatus 消息可能穿插在 CopyData 消息之间;前端必须处理这些情况,并应准备好处理其他异步消息类型(参见)。除此之外,可以将任何除 CopyData 或 CopyDone 以外的消息类型视为拷贝出模式的终止标志。 + - 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许数据以高速批量方式在客户端与服务器之间双向传输。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见。 + 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许高速批量地向服务器发送数据以及从服务器接收数据。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见 - CopyInResponse、CopyOutResponse和CopyBothResponse消息包括域和格式代码,域告诉前端每行的列数,而格式代码则用于具体每个列(就目前的实现而言,一个给定COPY操作中的所有列都将使用同样的格式,但是消息设计并不做这个假设)。 - + CopyInResponse、CopyOutResponse 和 CopyBothResponse 消息包含一些字段,用于告知前端每行的列数以及每列所使用的格式代码。(在当前实现中,同一次COPY操作的所有列都使用相同格式,但消息设计并不作此假设。) + @@ -771,8 +763,8 @@ SELCT 1/0; - 如果前端发出一个LISTEN命令, 那么无论何时在为同一个通道名NOTIFY时,后端将发送一个NotificationResponse消息(不要和NoticeResponse搞混!)。 - + 如果前端发出LISTEN命令,那么每当针对同一通道名执行NOTIFY命令时,后端都会发送一条 NotificationResponse 消息(不要与 NoticeResponse 混淆)。 + @@ -790,11 +782,11 @@ SELCT 1/0; - 要发出一条取消请求,前端打开一个与服务器的新连接并且发送一条CancelRequest消息, 而不是通常在新连接中经常发送的StartupMessage消息。服务器将处理这个请求然后关闭连接。 出于安全原因,对取消请求消息不做直接的响应。 - + 要发出取消请求,前端会新建到服务器的连接,并发送 CancelRequest 消息,而不是新连接通常发送的 StartupMessage 消息。服务器处理该请求后便会关闭连接。出于安全原因,服务器不会直接回复取消请求消息。 + - 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的关键数据(PID和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则退出当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 + 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的密钥数据(PID 和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则中止当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 @@ -802,7 +794,7 @@ SELCT 1/0; - 这么做是对安全性和有效性通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 + 这么做是对安全性和效率通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 @@ -822,11 +814,11 @@ SELCT 1/0; - 其他终止场景来自各种故障,例如任一端发生内核转储、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 + 其他终止场景来自各种故障,例如任一端发生 core dump、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 - 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果很可能在得知断开之前被提交。 + 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果可能在发现连接断开之前被提交。 @@ -839,20 +831,24 @@ SELCT 1/0; 要发起一条使用SSL加密的连接,前端首先发送 SSLRequest 消息,而不是 StartupMessage。随后服务器会响应一个包含SN的单字节,分别表示它愿意或不愿意执行SSL加密。如果前端对该响应不满意,此时可以关闭连接。若要在收到S后继续,就先与服务器完成SSL启动握手(这里不做描述,它属于SSL规范的一部分)。如果成功,再继续发送通常的 StartupMessage。在这种情况下,StartupMessage 以及后续所有数据都会被SSL加密。若要在收到N后继续,则发送通常的 StartupMessage,并在不使用加密的情况下继续。 - (另外,可以在 N 响应之后发出 GSSENCRequest 消息,尝试使用 GSSAPI 加密代替 SSL。) + (另外,可以在 N 响应之后发出 GSSENCRequest 消息,尝试使用 GSSAPI 加密代替 SSL。) - 前端也应准备处理服务器对 SSLRequest 返回的 ErrorMessage。前端不应将该错误直接展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 SSL 的情况下继续。 + 前端也应准备处理服务器对 SSLRequest 返回的 ErrorMessage。前端不应将该错误展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 SSL 的情况下继续。 - 当可以执行 SSL 加密时,服务器预计仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给他们的 SSL 库,要么在发现他们已经读取到额外的字节时将其视为协议违规。 + 当可以执行 SSL 加密时,服务器应仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给所用的 SSL 库,要么在发现已经读取到额外的字节时将其视为协议违规。 - 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 SSLRequest。 + + 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 SSLRequest。 + - 虽然协议本身没有提供让服务器强制使用 SSL 加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + + 虽然协议本身没有提供让服务器强制使用SSL加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + @@ -865,24 +861,24 @@ SELCT 1/0; 要建立 GSSAPI 加密连接,前端首先发送 GSSENCRequest 消息,而不是 StartupMessage。服务器随后以单个字节响应,内容为 GN,分别表示愿意或不愿意使用 GSSAPI 加密。如果前端对响应不满意,可以在此时关闭连接。收到 G 后要继续,应使用 RFC2744 中介绍的 GSSAPI C 绑定或等效接口,在循环中调用 gss_init_sec_context() 来执行 GSSAPI 初始化,并将结果发送给服务器:先使用空输入,再依次使用服务器返回的每个结果,直到该调用不再产生输出。将 gss_init_sec_context() 的结果发送给服务器时,应在前面加上消息长度,以网络字节序的四字节整数表示。收到 N 后要继续,则发送通常的 StartupMessage,以不加密的方式继续。(也允许在收到 N 响应后发送 SSLRequest 消息,尝试使用 SSL 加密代替 GSSAPI。) - 前端也应准备处理服务器对 GSSENCRequest 返回的 ErrorMessage。前端不应将该错误直接展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 GSSAPI 加密的情况下继续。 + 前端也应准备处理服务器对 GSSENCRequest 返回的 ErrorMessage。前端不应将该错误展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 GSSAPI 加密的情况下继续。 - 当GSSAPI加密可用时,服务器预计只发送单个G字节,然后等待前端启动GSSAPI握手。此时如果还有其他可读字节,很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应编写代码,要么从套接字中恰好读取一个字节后再把套接字交给其 GSSAPI 库,要么在发现自己已经读到额外字节时将其视为协议违规。 + 当GSSAPI加密可用时,服务器应只发送单个G字节,然后等待前端启动GSSAPI握手。此时如果还有其他可读字节,很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应编写代码,要么从套接字中恰好读取一个字节后再把套接字交给其 GSSAPI 库,要么在发现自己已经读到额外字节时将其视为协议违规。 - 初始 GSSENCRequest 也可用于那些正在建立、目的是发送 CancelRequest 消息的连接。 - + 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 GSSENCRequest。 + 一旦成功建立GSSAPI加密连接,就应使用gss_wrap()加密通常的 StartupMessage 以及后续所有数据,并在实际加密负载前附上gss_wrap()结果长度,该长度以网络字节序的四字节整数表示。请注意,服务器只接受来自客户端、长度小于 16kB 的加密数据包。客户端应使用gss_wrap_size_limit()确定符合该限制的未加密消息大小,较大的消息则应拆分为多次gss_wrap()调用。典型分段是 8kB 的未加密数据,对应得到略大于 8kB 但明显小于 16kB 的加密数据包。通常可以认为,服务器不会向客户端发送大于 16kB 的加密数据包。 - 虽然协议本身并不为服务器提供强制启用GSSAPI加密的方法,但管理员可以把服务器配置为拒绝未加密会话,把它作为认证检查的一个副作用。 - + 虽然协议本身没有提供让服务器强制使用GSSAPI加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + @@ -904,24 +900,21 @@ SELCT 1/0; - 客户端从列表中选择一个支持的机制,并向服务器发送一个SASLInitialResponse消息。 - 该消息包括所选机制的名称,以及如果所选机制使用的话,还包括一个可选的初始客户端响应。 - + 客户端从列表中选择一种受支持的机制,并向服务器发送 SASLInitialResponse 消息。消息包含所选机制的名称;如果该机制使用初始客户端响应,消息还可以包含这一可选响应。 + - 一个或多个服务器挑战和客户端响应消息将随后而来。每个服务器挑战都是在一个 - AuthenticationSASLContinue 消息中发送的,随后是客户端在一个 SASLResponse - 消息中的响应。这些消息的具体内容是特定于机制的。 - + 随后会进行一轮或多轮服务器挑战和客户端响应。每次服务器挑战都通过 AuthenticationSASLContinue 消息发送,随后客户端通过 SASLResponse 消息响应。消息的具体内容取决于所用机制。 + - 最后,当认证交换成功完成时,服务器会发送可选的 AuthenticationSASLFinal 消息,随后立即发送 AuthenticationOk。AuthenticationSASLFinal 包含机制特定的附加数据;若该机制不需要完成时附加数据,则不会发送 AuthenticationSASLFinal。 - + 最后,认证交换成功完成时,服务器会发送 AuthenticationSASLFinal 消息,紧接着发送 AuthenticationOk 消息。AuthenticationSASLFinal 包含从服务器发给客户端的附加数据,其具体内容取决于所选认证机制。如果该认证机制不使用在完成时发送的附加数据,则不会发送 AuthenticationSASLFinal 消息。 + @@ -941,31 +934,22 @@ SELCT 1/0; - SCRAM规范规定密码也必须是UTF-8编码,并且使用SASLprep算法处理。 - 然而,PostgreSQL不要求密码必须使用UTF-8编码。 - 当用户设置密码时,无论实际使用的编码是什么,都会像使用UTF-8一样使用SASLprep进行处理。 - 但是,如果密码不是合法的UTF-8字节序列,或者包含SASLprep算法禁止的UTF-8字节序列, - 则会使用原始密码而不进行SASLprep处理,而不是抛出错误。这样可以在密码为UTF-8时对其进行规范化, - 但仍允许使用非UTF-8密码,并且不需要系统知道密码使用的编码方式。 - + SCRAM 规范规定密码也必须采用 UTF-8 编码,并通过SASLprep算法处理。不过,PostgreSQL并不要求密码使用 UTF-8。设置用户密码时,无论实际采用何种编码,都会将其视作 UTF-8 并用 SASLprep 处理。但是,如果密码不是合法的 UTF-8 字节序列,或者包含 SASLprep 算法禁止的 UTF-8 字节序列,就会直接使用未经 SASLprep 处理的原始密码,而不抛出错误。这样既能对 UTF-8 密码进行规范化,又允许使用非 UTF-8 密码,而且不要求系统知道密码采用何种编码。 + - Channel binding在支持SSL的PostgreSQL构建中受支持。带有通道绑定的SCRAM的SASL机制名称是 + 通道绑定在支持SSL的PostgreSQL构建中受支持。带有通道绑定的SCRAM的SASL机制名称是 SCRAM-SHA-256-PLUS。PostgreSQL使用的通道绑定类型是 tls-server-end-point - 在没有通道绑定的SCRAM中,服务器选择一个随机数, - 传输给客户端,与用户提供的密码在传输的密码哈希中混合。虽然这可以 - 防止密码哈希在后续会话中被成功重新传输,但无法阻止真实服务器和客 - 户端之间的虚假服务器通过服务器的随机值并成功进行认证。 - + 在不带通道绑定的SCRAM中,服务器会选择一个随机数并发送给客户端,将它与用户提供的密码混合,形成所传输的密码 hash。虽然这样可以防止在后续会话中成功重放该密码 hash,但无法阻止位于真实服务器与客户端之间的伪造服务器转发服务器的随机值并成功通过认证。 + - SCRAM与通道绑定一起防止这种中间人攻击,通过将服务器证书的签名混合到传输的密码哈希中。 - 虽然伪造服务器可以重新传输真实服务器的证书,但它无法访问与该证书匹配的私钥,因此无法证明自己是所有者,导致SSL连接失败。 - + 带通道绑定的SCRAM会将服务器证书的签名混入所传输的密码 hash,从而防止此类中间人攻击。虽然伪造服务器可以转发真实服务器的证书,但它无法取得与证书匹配的私钥,因此无法证明自己是证书所有者,最终导致 SSL 连接失败。 + @@ -1034,21 +1018,27 @@ SELCT 1/0; 无论是物理复制还是逻辑复制的 walsender 模式,都只能使用简单查询协议。 -为了测试复制命令,可以通过psql或其他使用libpq的工具建立复制连接,连接字符串中应包含replication选项,例如: + + 为了测试复制命令,可以通过 psql 或其他使用 libpq 的工具建立复制连接,连接字符串中应包含 replication 选项,例如: + psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" -不过,通常更有用的做法是使用(用于物理复制)或(用于逻辑复制)。 + +不过,通常更有用的做法是使用 (用于物理复制)或 (用于逻辑复制)。 + - 复制命令在服务器日志中记录,当启用时。 + 启用 后,复制命令会记录到服务器日志中。 复制模式接受以下命令: IDENTIFY_SYSTEM - 识别系统 + IDENTIFY_SYSTEM - 请求服务器标识自身。服务器返回一个只有一行的结果集,包含四个字段: + + 请求服务器标识自身。服务器会返回一个包含四个字段的单行结果集: + @@ -1057,7 +1047,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" systemid (text) - 标识数据库集簇的唯一系统标识符。可用于检查初始化备库的基础备份是否来自同一个数据库集簇。 + + 用于标识该集簇的唯一系统标识符。它可用于检查初始化备库所用的基础备份是否来自同一个集簇。 + @@ -1082,7 +1074,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" dbname (text) - 所连接的数据库,或 null。 + + 当前连接到的数据库,或为 null。 + @@ -1141,7 +1135,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" content (bytea) - 时间线历史文件的内容。 + + 时间线历史文件的内容。 + @@ -1248,22 +1244,16 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" START_REPLICATION [ SLOT slot_name ] [ PHYSICAL ] XXX/XXX [ TIMELINE tli ] - 开始复制 + START_REPLICATION - 指示服务器开始流式传输WAL,从WAL位置XXX/XXX开始。 - 如果指定了TIMELINE选项,则流式传输将从时间线tli开始; - 否则,将选择服务器当前的时间线。如果请求的WAL部分已经被回收,服务器可能会回复错误。 - 成功时,服务器将用CopyBothResponse消息回复,然后开始向前端流式传输WAL。 - + 指示服务器从 WAL 位置 XXX/XXX 开始流式传输 WAL。如果指定了 TIMELINE 选项,则从时间线 tli 开始传输;否则选择服务器当前的时间线。服务器可以返回错误,例如请求的 WAL 部分已被回收时。成功时,服务器返回 CopyBothResponse 消息,然后开始向前端流式传输 WAL。 + - 如果通过slot_name提供了复制槽名称, - 那么在复制进行期间会更新该复制槽,以便服务器知道哪些 WAL 段, - 以及在启用了 hot_standby_feedback 时,哪些事务 - 仍然被备库所需要。 - + 如果通过 slot_name 提供了复制槽名称,该复制槽会随着复制的进行而更新,使服务器知道备库仍需要哪些 WAL 段,以及在启用 hot_standby_feedback 时仍需要哪些事务。 + 如果客户端请求的时间线不是最新时间线,但属于服务器的历史,服务器会从请求的起点开始,流式传输该时间线上的所有 WAL,直到服务器切换到另一条时间线的位置。如果客户端请求的流式传输起点恰好位于旧时间线的末尾,服务器会立即返回 CommandComplete,而不进入 COPY 模式。 @@ -1523,7 +1513,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" DROP_REPLICATION_SLOT slot_name WAIT - 删除复制槽 + DROP_REPLICATION_SLOT @@ -1571,9 +1561,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 设置备份的标签。如果未指定,则将使用base backup作为备份标签。 - 标签的引号使用规则与打开的标准SQL字符串相同。 - + 设置备份标签。如果未指定,则使用 base backup 作为备份标签。标签的引号规则与启用 时的标准 SQL 字符串相同。 + @@ -1707,8 +1696,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" size (int8) - 表空间的大致大小,以千字节(1024字节)为单位,如果已请求进度报告;否则为null。 - + 如果请求了进度报告,则为表空间的大致大小,以千字节(1024 字节)为单位;否则为 null。 + @@ -1772,7 +1761,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 逻辑复制协议 + 逻辑流复制协议 本节介绍逻辑复制协议,它是一种以复制命令START_REPLICATION @@ -1781,7 +1770,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 逻辑复制协议构建在物理流复制协议的底层机制之上。 + 逻辑流复制协议构建在物理流复制协议的基本机制之上。 @@ -1841,7 +1830,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 逻辑复制协议逐个发送事务。这意味着,一对 Begin 和 Commit 消息之间的所有消息都属于同一个事务。 - 每个被发送的事务都包含零条或多条 DML 消息(插入、更新、删除)。在级联场景下,它还会包含 Origin 消息。Origin 消息表示该事务产生于另一个复制节点。由于逻辑复制协议中的复制节点可以是任意实现,因此唯一标识符就是该源头的名称。下游是否以及如何处理这一信息,由其自行决定。Origin 消息总是在事务中的任何 DML 消息之前发送。 + 每个发送的事务都包含零条或多条 DML 消息(Insert、Update、Delete)。在级联配置中,还可能包含 Origin 消息。Origin 消息表示该事务源自另一个复制节点。由于逻辑复制协议中的复制节点几乎可以是任何实现,因此唯一的标识符就是复制源的名称。下游负责按需处理这一信息(如果需要处理)。Origin 消息总是在事务中的任何 DML 消息之前发送。 @@ -1906,9 +1895,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 对后端返回的字符串长度,没有预定义的限制。 - 前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。 - 如果做不到这一点,就应读取完整字符串,并丢弃不适合固定大小缓冲区的尾随字符。 + 后端返回的字符串长度没有预定义的限制。前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。如果做不到这一点,就应读取完整字符串,并丢弃固定大小的缓冲区容纳不下的尾随字符。 @@ -1933,8 +1920,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 消息格式 - 本节描述每条消息的详细格式。每条消息都标记了可由前端(F)、后端(B)或双方(F&B)发送。 - 请注意,虽然每条消息开头都带有字节计数,但大多数消息格式都定义为无需参考该计数也能确定消息边界。这一设计最初是出于历史原因(早期已废弃的协议 v2 没有显式长度字段),同时也有助于有效性校验。 + 本节描述每条消息的详细格式。每条消息都标明它可以由前端(F)、后端(B)或双方(F & B)发送。注意,虽然每条消息开头都有字节计数,但消息格式的定义使得无需参考该计数也能确定消息的结束位置。这有助于检查消息的有效性。(CopyData 消息是例外,因为它构成数据流的一部分,任何单条 CopyData 消息的内容都无法独立解释。) @@ -1955,7 +1941,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -1986,7 +1972,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2016,7 +2002,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2046,7 +2032,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(12) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2083,7 +2069,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2114,7 +2100,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2145,7 +2131,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2176,7 +2162,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2213,7 +2199,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2251,7 +2237,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2288,7 +2274,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2325,7 +2311,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(12) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2362,7 +2348,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2380,13 +2366,13 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int16 -后续参数格式码的数量(下文以 C 表示)。可以为零,表示没有参数,或者所有参数都使用默认格式(文本);也可以为一,此时指定的格式码应用于所有参数;还可以等于实际参数数量。 +后续参数格式代码的数量(下文以 C 表示)。可以为零,表示没有参数,或者所有参数都使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有参数;还可以等于实际参数数量。 Int16[C] -参数格式码。目前每个格式码必须为零(文本)或一(二进制)。 +参数格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -2405,20 +2391,20 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byten -参数值,格式由对应的格式码指明。n 为上述长度。 +参数值,格式由对应的格式代码指明。n 为上述长度。 最后一个参数之后是以下字段: Int16 -后续结果列格式码的数量(下文以 R 表示)。可以为零,表示没有结果列,或者所有结果列都应使用默认格式(文本);也可以为一,此时指定的格式码应用于所有结果列(如果有);还可以等于查询实际的结果列数量。 +后续结果列格式代码的数量(下文以 R 表示)。可以为零,表示没有结果列,或者所有结果列都应使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有结果列(如果有);还可以等于查询实际的结果列数量。 Int16[R] -结果列格式码。目前每个格式码必须为零(文本)或一(二进制)。 +结果列格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -2442,7 +2428,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2466,7 +2452,7 @@ CancelRequest (F) - 消息内容的长度,以字节为单位,包括此长度字段本身。 + 消息内容的长度(以字节为单位),包括其自身。 @@ -2522,7 +2508,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2558,7 +2544,7 @@ CancelRequest (F) Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2583,7 +2569,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2656,7 +2642,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2693,7 +2679,7 @@ CancelRequest (F) Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2722,7 +2708,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2751,13 +2737,13 @@ CancelRequest (F) Byte1('G') -标识消息为开始复制输入的响应。前端此时必须发送复制输入数据(如果尚未准备好,应发送 CopyFail 消息)。 +将该消息标识为开始 COPY 输入的响应。前端此时必须发送 COPY 输入数据(如果尚未准备好,应发送 CopyFail 消息)。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2806,13 +2792,13 @@ CancelRequest (F) Byte1('H') -标识消息为开始复制输出的响应。该消息之后会发送复制输出数据。 +将该消息标识为开始 COPY 输出的响应。此消息之后会发送 COPY 输出数据。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2861,13 +2847,13 @@ CancelRequest (F) Byte1('W') -标识消息为开始双向复制的响应。此消息仅用于流复制。 +将该消息标识为开始双向 COPY 的响应。此消息仅用于流复制。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2923,7 +2909,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -2938,7 +2924,7 @@ CancelRequest (F) Int32 -列值的长度,以字节为单位(不包括本长度字段自身)。可以为零。特殊值 -1 表示列值为 NULL,此时后面没有值字节。 +列值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 列值。为 NULL 时,后面不再有值的字节。 @@ -2969,14 +2955,14 @@ CancelRequest (F) - 标识消息为描述命令。 + 将该消息标识为 Describe 命令。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3019,7 +3005,7 @@ CancelRequest (F) Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3048,7 +3034,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -3087,14 +3073,14 @@ CancelRequest (F) - 标识消息为一个执行命令。 + 将该消息标识为 Execute 命令。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3129,14 +3115,14 @@ CancelRequest (F) - 将消息标识为Flush命令。 + 将该消息标识为 Flush 命令。 Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3165,7 +3151,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3198,7 +3184,7 @@ CancelRequest (F) Int32 -参数值的长度,以字节为单位(不包括本长度字段自身)。可以为零。特殊值 -1 表示参数值为 NULL,此时后面没有值字节。 +参数值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 参数值。为 NULL 时,后面不再有值的字节。 @@ -3243,13 +3229,13 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 Int32 -函数结果值的长度,以字节为单位(不包括本长度字段自身)。可以为零。特殊值 -1 表示函数结果为 NULL,此时后面没有值字节。 +函数结果值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 函数结果。为 NULL 时,后面不再有值的字节。 @@ -3288,7 +3274,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3323,7 +3309,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3371,7 +3357,7 @@ CancelRequest (F) Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3400,7 +3386,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -3446,7 +3432,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3464,7 +3450,7 @@ CancelRequest (F) String -通知进程传来的载荷字符串。 +通知进程传来的有效载荷字符串。 @@ -3493,7 +3479,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3536,7 +3522,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3569,14 +3555,14 @@ CancelRequest (F) - 将消息标识为解析命令。 + 将该消息标识为 Parse 命令。 Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3625,14 +3611,14 @@ CancelRequest (F) - 将消息标识为解析完成指示器。 + 将该消息标识为 Parse 完成指示。 Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3662,7 +3648,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3691,15 +3677,14 @@ CancelRequest (F) - 标识消息为 portal 挂起指示器。 - 请注意,仅当执行消息的行数限制达到时才会出现此消息。 + 将该消息标识为 portal 挂起指示。注意,仅当达到 Execute 消息指定的行数限制时,才会出现此消息。 Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3728,7 +3713,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3765,7 +3750,7 @@ CancelRequest (F) Int32(5) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3804,7 +3789,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3863,7 +3848,7 @@ CancelRequest (F) Int16 -字段所使用的格式代码。目前为零(文本)或一(二进制)。对于 Describe 的语句变体所返回的 RowDescription,格式代码尚未确定,始终为零。 +字段所使用的格式代码。目前为零(文本)或一(二进制)。对于 Describe 针对预备语句的变体所返回的 RowDescription,格式代码尚未确定,始终为零。 @@ -3893,7 +3878,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3944,7 +3929,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -3970,7 +3955,7 @@ CancelRequest (F) Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -4000,7 +3985,7 @@ CancelRequest (F) Int32(8) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -4030,7 +4015,7 @@ CancelRequest (F) Int32 -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -4114,14 +4099,14 @@ CancelRequest (F) - 将消息标识为同步命令。 + 将该消息标识为 Sync 命令。 Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -4150,7 +4135,7 @@ CancelRequest (F) Int32(4) -消息内容的长度,以字节为单位,包括此长度字段本身。 +消息内容的长度(以字节为单位),包括其自身。 @@ -4166,7 +4151,7 @@ CancelRequest (F) -错误和通知消息域 +错误和通知消息字段 本节描述了ErrorResponse和NoticeResponse消息中可能出现的字段。每个字段类型都有一个单字节的标识符。 @@ -4180,11 +4165,7 @@ CancelRequest (F) - 严重性: 字段内容为ERROR, FATAL, 或 - PANIC (在错误消息中), 或 - WARNING, NOTICE, DEBUG, - INFO, 或 LOG (在通知消息中), - 或者这些内容的本地化翻译。始终存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中),或这些内容的本地化翻译。始终存在。 @@ -4194,11 +4175,7 @@ CancelRequest (F) - 严重性:字段内容为 ERRORFATAL 或 - PANIC(在错误消息中),或 WARNINGNOTICEDEBUG、 - INFOLOG(在通知消息中)。 - 这与S字段相同,只是内容不会被本地化。仅在由PostgreSQL版本9.6 - 及更高版本生成的消息中存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中)。它与 S 字段相同,只是内容从不本地化。仅在 PostgreSQL 9.6 及更高版本生成的消息中存在。 @@ -4208,7 +4185,7 @@ CancelRequest (F) - Code: 错误的SQLSTATE代码(参见)。不可本地化。始终存在。 + 代码:错误的 SQLSTATE 代码(见 )。不可本地化。始终存在。 @@ -4218,9 +4195,7 @@ CancelRequest (F) - 消息: 主要的人类可读错误消息。 - 这应该准确但简洁(通常一行)。 - 总是存在。 + 消息:主要的可读错误消息。应准确而简洁(通常为一行)。始终存在。 @@ -4230,7 +4205,7 @@ CancelRequest (F) - 详细信息:一个可选的次要错误消息,提供有关问题的更多详细信息。可能会跨多行。 + 详细信息:可选的次要错误消息,提供有关该问题的更多细节。可能占多行。 @@ -4240,9 +4215,7 @@ CancelRequest (F) - 提示: 关于问题应该怎么做的一个可选建议。 - 这意在与细节不同,它提供建议(可能不合适)而不是硬性事实。 - 可能会跨越多行。 + 提示:可选的建议,说明如何处理该问题。它与详细信息的区别在于,它提供建议(可能并不合适),而非确凿事实。可能占多行。 @@ -4284,9 +4257,7 @@ CancelRequest (F) - Where: 错误发生的上下文指示。 - 目前包括活动的过程语言函数和内部生成查询的调用堆栈回溯。 - 跟踪每行一个条目,最近的在前。 + 上下文:说明错误发生时的上下文。目前包括活跃的过程语言函数和内部生成的查询的调用栈回溯。回溯每行一个条目,最近的调用在前。 @@ -4296,7 +4267,7 @@ CancelRequest (F) - Schema name: 如果错误与特定数据库对象相关联,则为包含该对象的模式的名称(如果有)。 + 模式名:如果错误与某个特定数据库对象有关,则为包含该对象的模式名称(如果有)。 @@ -4306,7 +4277,7 @@ CancelRequest (F) - 表名: 如果错误与特定表相关联,则为表的名称。(有关表模式名称的名称,请参考模式名称字段。) + 表名:如果错误与某个特定表有关,则为该表的名称。(表所在模式的名称见模式名字段。) @@ -4316,7 +4287,7 @@ CancelRequest (F) - 列名: 如果错误与特定表列相关联,则为列的名称。(请参考模式和表名字段以识别表。) + 列名:如果错误与某个特定表列有关,则为该列的名称。(通过模式名和表名字段确定该表。) @@ -4326,8 +4297,7 @@ CancelRequest (F) - 数据类型名称: 如果错误与特定数据类型相关联,则为数据类型的名称。 - (有关数据类型模式的名称,请参阅模式名称字段。) + 数据类型名:如果错误与某个特定数据类型有关,则为该数据类型的名称。(数据类型所在模式的名称见模式名字段。) @@ -4337,8 +4307,7 @@ CancelRequest (F) - 约束名称: 如果错误与特定约束相关联,则为约束的名称。请参考上面列出的字段,了解相关表或域。 - (为此,即使索引不是使用约束语法创建的,也将其视为约束。) + 约束名:如果错误与某个特定约束有关,则为该约束的名称。相关的表或域见上述字段。(这里将索引也视为约束,即使它不是用约束语法创建的。) @@ -4348,7 +4317,7 @@ CancelRequest (F) - 文件: 报告错误的源代码位置的文件名。 + 文件:报告错误的源代码位置所在的文件名。 @@ -4358,7 +4327,7 @@ CancelRequest (F) - Line: 源代码位置的行号,报告错误的位置。 + 行号:报告错误的源代码位置所在的行号。 @@ -4368,7 +4337,7 @@ CancelRequest (F) - Routine: 报告错误的源代码例程的名称。 + 例程:报告错误的源代码例程的名称。 @@ -4378,15 +4347,12 @@ CancelRequest (F) - 模式名称、表名称、列名称、数据类型名称和约束名称的字段仅针对有限数量的错误类型提供; - 请参阅。前端不应假设任何这些字段的存在就保证了另一个字段的存在。 - 核心错误源观察到上述相互关系,但用户定义的函数可能以其他方式使用这些字段。 - 同样地,客户端不应假设这些字段表示当前数据库中的当代对象。 + 模式名、表名、列名、数据类型名和约束名字段仅针对有限的几类错误提供,见 。前端不应假设其中任何字段的存在就保证了另一个字段的存在。核心错误源遵循上述相互关系,但用户定义的函数可能以其他方式使用这些字段。同样,客户端不应假设这些字段表示当前数据库中现存的对象。 - 客户端负责格式化显示的信息以满足其需求;特别是应根据需要换行。错误消息字段中出现的换行符应被视为段落分隔符,而不是换行符。 + 客户端负责按自身需要格式化显示的信息;尤其应根据需要将长行断开。错误消息字段中的换行符应视为段落分隔符,而非行分隔符。 @@ -4414,7 +4380,7 @@ CancelRequest (F) - 将消息标识为开始消息。 + 将该消息标识为 Begin 消息。 @@ -4458,7 +4424,7 @@ CancelRequest (F) - 标识消息为提交消息。 + 将该消息标识为 Commit 消息。 @@ -4507,7 +4473,7 @@ CancelRequest (F) Byte1('O') -标识消息为复制源消息。 +将该消息标识为 Origin 消息。 @@ -4529,7 +4495,7 @@ CancelRequest (F) - 请注意,在单个事务中可能存在多个Origin消息。 + 注意,单个事务中可能有多条 Origin 消息。 @@ -4544,7 +4510,7 @@ CancelRequest (F) Byte1('R') -将该消息标识为关系消息。 +将该消息标识为 Relation 消息。 @@ -4571,7 +4537,7 @@ CancelRequest (F) - 关系的复制标识设置(与relreplidentpg_class中相同)。 + 关系的复制标识设置(与 pg_class 中的 relreplident 相同)。 @@ -4606,7 +4572,7 @@ CancelRequest (F) - 列的类型修饰符 (atttypmod)。 + 列的类型修饰符(atttypmod)。 @@ -4625,7 +4591,7 @@ CancelRequest (F) Byte1('Y') -将该消息标识为类型消息。 +将该消息标识为 Type 消息。 @@ -4661,13 +4627,13 @@ CancelRequest (F) Byte1('I') -将该消息标识为插入消息。 +将该消息标识为 Insert 消息。 Int32 -关系的 ID,与关系消息中的 ID 对应。 +关系的 ID,与 Relation 消息中的 ID 对应。 @@ -4698,13 +4664,13 @@ CancelRequest (F) Byte1('U') -将该消息标识为更新消息。 +将该消息标识为 Update 消息。 Int32 -关系的 ID,与关系消息中的 ID 对应。 +关系的 ID,与 Relation 消息中的 ID 对应。 @@ -4760,13 +4726,13 @@ CancelRequest (F) Byte1('D') -将该消息标识为删除消息。 +将该消息标识为 Delete 消息。 Int32 -关系的 ID,与关系消息中的 ID 对应。 +关系的 ID,与 Relation 消息中的 ID 对应。 @@ -4807,7 +4773,7 @@ CancelRequest (F) Byte1('T') -将该消息标识为截断消息。 +将该消息标识为 Truncate 消息。 @@ -4828,7 +4794,7 @@ CancelRequest (F) Int32 -关系的 ID,与关系消息中的 ID 对应。每个关系都重复出现此字段。 +关系的 ID,与 Relation 消息中的 ID 对应。每个关系都重复出现此字段。 diff --git a/zh/13/rangetypes.sgml b/zh/13/rangetypes.sgml index e29cda85..e9983d1d 100644 --- a/zh/13/rangetypes.sgml +++ b/zh/13/rangetypes.sgml @@ -4,7 +4,7 @@ 范围类型 - range type + 范围类型 @@ -18,7 +18,9 @@ 内置范围类型 - PostgreSQL 提供以下内置范围类型: + + PostgreSQL 自带下列内置范围类型: + int4rangeinteger 的范围 @@ -37,7 +39,9 @@ daterangedate 的范围 - 此外,还可以定义自己的范围类型;参见了解更多信息。 + + 此外,你还可以定义自己的范围类型;详见。 + @@ -92,15 +96,15 @@ SELECT isempty(numrange(1, 5)); 无限(无界)范围 - 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作 +/-infinity,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的 +/-infinity 值。 + 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作正负无穷大,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的正负无穷大值。 - 具有infinity概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 + 具有无穷大概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 - 函数lower_infupper_inf分别测试范围的下界和上界是否为无限。 + 函数lower_infupper_inf分别测试范围是否没有下界和上界。 @@ -259,23 +263,23 @@ SELECT '[11:10, 23:00]'::timerange; 索引 - range type - indexes on + 范围类型 + 索引 可以为范围类型的表列创建 GiST 和 SP-GiST 索引。例如,创建 GiST 索引: CREATE INDEX reservation_idx ON reservation USING GIST (during); -GiST 或 SP-GiST 索引可以加速涉及以下范围操作符的查询:=, - &&, - <@, - @>, - <<, - >>, - -|-, +GiST 或 SP-GiST 索引可以加速涉及以下范围操作符的查询:=、 + &&、 + <@、 + @>、 + <<、 + >>、 + -|-&<&>(参见了解更多信息)。 - 此外,也可以为范围类型的表列创建 B-树和哈希索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和哈希支持主要是为了允许在查询内部进行排序和哈希,而不是用于创建实际的索引。 + 此外,也可以为范围类型的表列创建 B-树和 hash 索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和 hash 支持主要是为了允许在查询内部进行排序和 hash 运算,而不是用于创建实际的索引。 @@ -284,8 +288,8 @@ CREATE INDEX reservation_idx ON reservation USING GIST (during); 范围上的约束 - range type - exclude + 范围类型 + 排他约束 diff --git a/zh/13/ref/alter_extension.sgml b/zh/13/ref/alter_extension.sgml index 86286dec..ed782ba4 100644 --- a/zh/13/ref/alter_extension.sgml +++ b/zh/13/ref/alter_extension.sgml @@ -170,7 +170,7 @@ ALTER EXTENSION name DROP 要添加到扩展中或从扩展中移除的对象名称。表、聚合、域、外部表、函数、 - 操作符、操作符类、操作符族、过程、例程、序列、文本搜索对象、类型和视图的名称 + 操作符、操作符类、操作符族、过程、例程、序列、文本检索对象、类型和视图的名称 可以带模式限定。 diff --git a/zh/13/ref/alter_tsconfig.sgml b/zh/13/ref/alter_tsconfig.sgml index 453d7ee7..02e172c8 100644 --- a/zh/13/ref/alter_tsconfig.sgml +++ b/zh/13/ref/alter_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义 + 更改一个文本检索配置的定义 @@ -45,7 +45,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义。你可以修改其从记号类型到字典的映射, + 更改一个文本检索配置的定义。你可以修改其从词元类型到词典的映射, 或者更改该配置的名称或拥有者。 @@ -67,7 +67,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 一个现有文本搜索配置的名称(可以是模式限定的)。 + 一个现有文本检索配置的名称(可以是模式限定的)。 @@ -78,7 +78,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 由该配置的解析器发出的记号类型的名称。 + 由该配置的解析器发出的词元类型的名称。 @@ -89,7 +89,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 用于指定记号类型的文本搜索字典名称。如果列出了多个字典, + 用于指定词元类型的文本检索词典名称。如果列出了多个词典, 将按指定顺序依次查阅它们。 @@ -101,7 +101,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 在映射中要替换的文本搜索字典的名称。 + 在映射中要替换的文本检索词典的名称。 @@ -113,7 +113,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA 被用来替代old_dictionary - 的文本搜索字典的名称。 + 的文本检索词典的名称。 @@ -124,7 +124,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新名称。 + 该文本检索配置的新名称。 @@ -135,7 +135,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新拥有者。 + 该文本检索配置的新拥有者。 @@ -146,21 +146,21 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新模式。 + 该文本检索配置的新模式。 - ADD MAPPING FOR形式为指定的词元类型安装要查询的字典列表;如果任何词元类型已经存在映射,则会报错。ALTER MAPPING FOR形式执行相同操作,但会先移除这些词元类型的现有映射。ALTER MAPPING REPLACE形式在任何出现旧字典的地方用new_dictionary替换old_dictionary。当出现FOR时,只对指定的词元类型执行此操作;不出现时,则对该配置的所有映射执行。DROP MAPPING形式移除指定词元类型的所有字典,使这些类型的词元被文本搜索配置忽略。如果词元类型没有映射,则会报错,除非出现IF EXISTS + ADD MAPPING FOR形式为指定的词元类型安装要查询的词典列表;如果任何词元类型已经存在映射,则会报错。ALTER MAPPING FOR形式执行相同操作,但会先移除这些词元类型的现有映射。ALTER MAPPING REPLACE形式在任何出现旧词典的地方用new_dictionary替换old_dictionary。当出现FOR时,只对指定的词元类型执行此操作;不出现时,则对该配置的所有映射执行。DROP MAPPING形式移除指定词元类型的所有词典,使这些类型的词元被文本检索配置忽略。如果词元类型没有映射,则会报错,除非出现IF EXISTS 示例 - 以下示例在my_config中使用english的任何地方,都将english字典替换为swedish字典。 + 以下示例在my_config中使用english的任何地方,都将english词典替换为swedish词典。 ALTER TEXT SEARCH CONFIGURATION my_config diff --git a/zh/13/ref/alter_tsdictionary.sgml b/zh/13/ref/alter_tsdictionary.sgml index 9fedf32d..76c28ac6 100644 --- a/zh/13/ref/alter_tsdictionary.sgml +++ b/zh/13/ref/alter_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH DICTIONARY - 更改一个文本搜索字典的定义 + 更改一个文本检索词典的定义 @@ -37,14 +37,14 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - ALTER TEXT SEARCH DICTIONARY更改文本搜索字典的 - 定义。你可以更改该字典的模板相关选项,也可以更改该字典的名称或拥有者。 + ALTER TEXT SEARCH DICTIONARY更改文本检索词典的 + 定义。你可以更改该词典的模板相关选项,也可以更改该词典的名称或拥有者。 - 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该字典 + 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该词典 的拥有者。 @@ -59,7 +59,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 一个现有文本搜索字典的名称(可以是模式限定的)。 + 一个现有文本检索词典的名称(可以是模式限定的)。 @@ -70,7 +70,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -81,7 +81,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 模板相关选项要使用的新值。如果省略等号和值,则会从该字典中移除 + 模板相关选项要使用的新值。如果省略等号和值,则会从该词典中移除 该选项之前的设置,从而允许使用默认值。 @@ -93,7 +93,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新名称。 + 该文本检索词典的新名称。 @@ -104,7 +104,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新拥有者。 + 该文本检索词典的新拥有者。 @@ -115,7 +115,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新模式。 + 该文本检索词典的新模式。 @@ -134,7 +134,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 下面的示例命令更改了一个基于 Snowball 的字典的停用词列表。其他参数 + 下面的示例命令更改了一个基于 Snowball 的词典的停用词列表。其他参数 保持不变。 @@ -160,7 +160,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( language = dutch, StopWords ); - 下面的示例命令更新了该字典的定义,但实际上并没有做 + 下面的示例命令更新了该词典的定义,但实际上并没有做 任何更改。 @@ -168,7 +168,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( dummy ); (之所以可行,是因为选项移除代码在不存在该选项时也不会报错。) - 这种技巧在修改该字典的配置文件时很有用:ALTER + 这种技巧在修改该词典的配置文件时很有用:ALTER 会强制现有数据库会话重新读取配置文件,而如果它们先前已经读取过这 些文件,本来是不会再次读取的。 diff --git a/zh/13/ref/alter_tsparser.sgml b/zh/13/ref/alter_tsparser.sgml index 0844cb0a..ccc73f05 100644 --- a/zh/13/ref/alter_tsparser.sgml +++ b/zh/13/ref/alter_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH PARSER - 更改一个全文检索解析器的定义 + 更改一个文本检索解析器的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA 描述 - ALTER TEXT SEARCH PARSER更改全文检索解析器的定义。 + ALTER TEXT SEARCH PARSER更改文本检索解析器的定义。 当前唯一支持的功能是更改该解析器的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA name - 一个现有全文检索解析器的名称(可以是模式限定的)。 + 一个现有文本检索解析器的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_name - 该全文检索解析器的新名称。 + 该文本检索解析器的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_schema - 该全文检索解析器的新模式。 + 该文本检索解析器的新模式。 diff --git a/zh/13/ref/alter_tstemplate.sgml b/zh/13/ref/alter_tstemplate.sgml index a3eec599..9c9dfc2c 100644 --- a/zh/13/ref/alter_tstemplate.sgml +++ b/zh/13/ref/alter_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH TEMPLATE - 更改一个文本搜索模板的定义 + 更改一个文本检索模板的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA 描述 - ALTER TEXT SEARCH TEMPLATE更改文本搜索模板的定义。 + ALTER TEXT SEARCH TEMPLATE更改文本检索模板的定义。 当前唯一支持的功能是更改该模板的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA name - 一个现有文本搜索模板的名称(可以是模式限定的)。 + 一个现有文本检索模板的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_name - 该文本搜索模板的新名称。 + 该文本检索模板的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_schema - 该文本搜索模板的新模式。 + 该文本检索模板的新模式。 diff --git a/zh/13/ref/comment.sgml b/zh/13/ref/comment.sgml index 89b06fe3..68533da6 100644 --- a/zh/13/ref/comment.sgml +++ b/zh/13/ref/comment.sgml @@ -116,7 +116,7 @@ COMMENT ON rule_name trigger_name - 要添加注释的对象名称。表、聚合、排序规则、转换、域、外部表、函数、索引、操作符、操作符类、操作符族、过程、例程、序列、统计信息、文本搜索对象、类型和视图的名称可以带模式限定。为列添加注释时,relation_name必须引用表、视图、复合类型或外部表。 + 要添加注释的对象名称。表、聚合、排序规则、转换、域、外部表、函数、索引、操作符、操作符类、操作符族、过程、例程、序列、统计信息、文本检索对象、类型和视图的名称可以带模式限定。为列添加注释时,relation_name必须引用表、视图、复合类型或外部表。 diff --git a/zh/13/ref/create_tsconfig.sgml b/zh/13/ref/create_tsconfig.sgml index 974ef42a..1d4ceca2 100644 --- a/zh/13/ref/create_tsconfig.sgml +++ b/zh/13/ref/create_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH CONFIGURATION - 定义一个新的文本搜索配置 + 定义一个新的文本检索配置 @@ -33,24 +33,24 @@ CREATE TEXT SEARCH CONFIGURATION name CREATE TEXT SEARCH CONFIGURATION - 创建一个新的文本搜索配置。文本搜索配置指定一个能把字符串拆分为记号 - 的文本搜索解析器,以及一些可用于判断哪些记号对搜索有意义的词典。 + 创建一个新的文本检索配置。文本检索配置指定一个能把字符串拆分为词元 + 的文本检索解析器,以及一些可用于判断哪些词元对搜索有意义的词典。 - 如果只指定了解析器,那么新文本搜索配置最初没有从记号类型到词典的映射, + 如果只指定了解析器,那么新文本检索配置最初没有从词元类型到词典的映射, 因而会忽略所有词。要让该配置真正可用,必须使用后续的ALTER TEXT SEARCH CONFIGURATION命令创建映射。 - 另一种方式是复制一个现有的文本搜索配置。 + 另一种方式是复制一个现有的文本检索配置。 - 如果给出了一个模式名称,则文本搜索配置会被创建在指定的模式中。否则它将会 + 如果给出了一个模式名称,则文本检索配置会被创建在指定的模式中。否则它将会 被创建在当前模式中。 - 定义该文本搜索配置的用户会成为其拥有者。 + 定义该文本检索配置的用户会成为其拥有者。 @@ -66,7 +66,7 @@ CREATE TEXT SEARCH CONFIGURATION namename - 要创建的文本搜索配置的名称。该名称可以是模式限定的。 + 要创建的文本检索配置的名称。该名称可以是模式限定的。 @@ -75,7 +75,7 @@ CREATE TEXT SEARCH CONFIGURATION nameparser_name - 此配置要使用的文本搜索解析器的名称。 + 此配置要使用的文本检索解析器的名称。 @@ -84,7 +84,7 @@ CREATE TEXT SEARCH CONFIGURATION namesource_config - 要复制的现有文本搜索配置的名称。 + 要复制的现有文本检索配置的名称。 diff --git a/zh/13/ref/create_tsdictionary.sgml b/zh/13/ref/create_tsdictionary.sgml index 2dbca552..75218295 100644 --- a/zh/13/ref/create_tsdictionary.sgml +++ b/zh/13/ref/create_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH DICTIONARY - 定义一个新的文本搜索字典 + 定义一个新的文本检索词典 @@ -33,19 +33,19 @@ CREATE TEXT SEARCH DICTIONARY name CREATE TEXT SEARCH DICTIONARY创建一个 - 新的文本搜索字典。文本搜索字典指定一种在搜索时识别哪些词值得关注、 - 哪些词不值得关注的方式。字典依赖于文本搜索模板,后者规定了实际执行 - 这项工作的函数。通常,字典会提供一些选项,用来控制模板函数的具体 + 新的文本检索词典。文本检索词典指定一种在搜索时识别哪些词值得关注、 + 哪些词不值得关注的方式。词典依赖于文本检索模板,后者规定了实际执行 + 这项工作的函数。通常,词典会提供一些选项,用来控制模板函数的具体 行为。 - 如果给出了一个模式名称,那么该文本搜索字典会被创建在指定的模式中。 + 如果给出了一个模式名称,那么该文本检索词典会被创建在指定的模式中。 否则它会被创建在当前模式中。 - 定义文本搜索字典的用户将成为其拥有者。 + 定义文本检索词典的用户将成为其拥有者。 @@ -61,7 +61,7 @@ CREATE TEXT SEARCH DICTIONARY name name - 要创建的文本搜索字典的名称。该名称可以被模式限定。 + 要创建的文本检索词典的名称。该名称可以被模式限定。 @@ -70,7 +70,7 @@ CREATE TEXT SEARCH DICTIONARY name template - 用于定义该字典基本行为的文本搜索模板名称。 + 用于定义该词典基本行为的文本检索模板名称。 @@ -79,7 +79,7 @@ CREATE TEXT SEARCH DICTIONARY name option - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -105,7 +105,7 @@ CREATE TEXT SEARCH DICTIONARY name 下面的示例命令创建了一个基于 Snowball 且使用非标准停用词列表的 - 字典。 + 词典。 diff --git a/zh/13/ref/create_tsparser.sgml b/zh/13/ref/create_tsparser.sgml index 6af67ab8..5f2e5184 100644 --- a/zh/13/ref/create_tsparser.sgml +++ b/zh/13/ref/create_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH PARSER - 定义一个新的全文检索解析器 + 定义一个新的文本检索解析器 @@ -36,19 +36,19 @@ CREATE TEXT SEARCH PARSER name ( CREATE TEXT SEARCH PARSER创建一个 - 新的全文检索解析器。全文检索解析器定义了一种方法,用于将文本字符串 - 拆分成记号并为这些记号指定类型(类别)。解析器本身并没有太大用处, - 必须与一些全文检索字典一起绑定到一个全文检索配置中,才能用于搜索。 + 新的文本检索解析器。文本检索解析器定义了一种方法,用于将文本字符串 + 拆分成词元并为这些词元指定类型(类别)。解析器本身并没有太大用处, + 必须与一些文本检索词典一起绑定到一个文本检索配置中,才能用于搜索。 - 如果给出了一个模式名称,那么全文检索解析器将被创建在指定的模式中。 + 如果给出了一个模式名称,那么文本检索解析器将被创建在指定的模式中。 否则它会被创建在当前模式中。 要使用CREATE TEXT SEARCH PARSER,你必须是超级用户。 - 之所以有此限制,是因为错误的全文检索解析器定义可能会让服务器陷入 + 之所以有此限制,是因为错误的文本检索解析器定义可能会让服务器陷入 混乱,甚至崩溃。 @@ -65,7 +65,7 @@ CREATE TEXT SEARCH PARSER name ( name - 要创建的全文检索解析器的名称。该名称可以是模式限定的。 + 要创建的文本检索解析器的名称。该名称可以是模式限定的。 @@ -83,7 +83,7 @@ CREATE TEXT SEARCH PARSER name ( gettoken_function - 该解析器的获取下一个记号的函数名称。 + 该解析器的获取下一个词元的函数名称。 @@ -101,7 +101,7 @@ CREATE TEXT SEARCH PARSER name ( lextypes_function - 该解析器的 lextypes 函数的名称(该函数返回它所产生的记号类型集合的 + 该解析器的 lextypes 函数的名称(该函数返回它所产生的词元类型集合的 信息)。 @@ -111,7 +111,7 @@ CREATE TEXT SEARCH PARSER name ( headline_function - 该解析器的 headline 函数的名称(该函数对一组记号生成摘要)。 + 该解析器的 headline 函数的名称(该函数对一组词元生成摘要)。 diff --git a/zh/13/ref/create_tstemplate.sgml b/zh/13/ref/create_tstemplate.sgml index 5dd2e1c0..24ee925e 100644 --- a/zh/13/ref/create_tstemplate.sgml +++ b/zh/13/ref/create_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH TEMPLATE - 定义一个新的全文检索模板 + 定义一个新的文本检索模板 @@ -33,22 +33,22 @@ CREATE TEXT SEARCH TEMPLATE name ( CREATE TEXT SEARCH TEMPLATE创建一个 - 新的全文检索模板。全文检索模板定义实现全文检索字典的函数。模板本身 - 并无直接用途,必须先实例化为字典后才能使用。字典通常会指定要传递给 + 新的文本检索模板。文本检索模板定义实现文本检索词典的函数。模板本身 + 并无直接用途,必须先实例化为词典后才能使用。词典通常会指定要传递给 模板函数的参数。 - 如果给出了模式名称,则全文检索模板会被创建在指定模式中。否则它会被 + 如果给出了模式名称,则文本检索模板会被创建在指定模式中。否则它会被 创建在当前模式中。 要使用CREATE TEXT SEARCH TEMPLATE,你 - 必须是超级用户。之所以有此限制,是因为错误的全文检索模板定义可能使 - 服务器陷入混乱,甚至崩溃。将模板与字典分离的原因在于,模板封装了定 - 义字典时那些不安全的方面。而在定义字典时可设置的参数, - 对非特权用户来说是安全的,因此创建字典不必是特权操作。 + 必须是超级用户。之所以有此限制,是因为错误的文本检索模板定义可能使 + 服务器陷入混乱,甚至崩溃。将模板与词典分离的原因在于,模板封装了定 + 义词典时那些不安全的方面。而在定义词典时可设置的参数, + 由普通用户设置也是安全的,因此创建词典不必是特权操作。 @@ -64,7 +64,7 @@ CREATE TEXT SEARCH TEMPLATE name ( name - 要创建的全文检索模板名称。该名称可以是模式限定的。 + 要创建的文本检索模板名称。该名称可以是模式限定的。 diff --git a/zh/13/ref/drop_opclass.sgml b/zh/13/ref/drop_opclass.sgml index 9d67dc64..545a2517 100644 --- a/zh/13/ref/drop_opclass.sgml +++ b/zh/13/ref/drop_opclass.sgml @@ -110,7 +110,7 @@ DROP OPERATOR CLASS [ IF EXISTS ] name示例 - 移除 B-tree 操作符类widget_ops: + 移除 B-树操作符类widget_ops DROP OPERATOR CLASS widget_ops USING btree; diff --git a/zh/13/ref/drop_tsconfig.sgml b/zh/13/ref/drop_tsconfig.sgml index ea139802..b3ebb9d1 100644 --- a/zh/13/ref/drop_tsconfig.sgml +++ b/zh/13/ref/drop_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH CONFIGURATION - 移除一个文本搜索配置 + 移除一个文本检索配置 @@ -29,7 +29,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 描述 - DROP TEXT SEARCH CONFIGURATION删除一个现有文本搜索配置。 + DROP TEXT SEARCH CONFIGURATION删除一个现有文本检索配置。 要执行此命令,你必须是该配置的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name IF EXISTS - 如果该文本搜索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name name - 现有文本搜索配置的名称(可以被模式限定)。 + 现有文本检索配置的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name CASCADE - 自动删除依赖于该文本搜索配置的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索配置的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name RESTRICT - 如果有任何对象依赖于该文本搜索配置,则拒绝删除该配置。这是默认值。 + 如果有任何对象依赖于该文本检索配置,则拒绝删除该配置。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 示例 - 移除文本搜索配置my_english: + 移除文本检索配置my_english DROP TEXT SEARCH CONFIGURATION my_english; 如果已有索引在to_tsvector调用中引用了该配置, - 此命令将不会成功。加上CASCADE可以在删除该文本搜索配置的同时删除这类索引。 + 此命令将不会成功。加上CASCADE可以在删除该文本检索配置的同时删除这类索引。 diff --git a/zh/13/ref/drop_tsdictionary.sgml b/zh/13/ref/drop_tsdictionary.sgml index 316c5d00..0f7751a1 100644 --- a/zh/13/ref/drop_tsdictionary.sgml +++ b/zh/13/ref/drop_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH DICTIONARY - 移除一个文本搜索字典 + 移除一个文本检索词典 @@ -29,8 +29,8 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name描述 - DROP TEXT SEARCH DICTIONARY删除一个现有文本搜索字典。 - 要执行此命令,你必须是该字典的拥有者。 + DROP TEXT SEARCH DICTIONARY删除一个现有文本检索词典。 + 要执行此命令,你必须是该词典的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索字典不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索词典不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] namename - 一个现有文本搜索字典的名称(可以被模式限定)。 + 一个现有文本检索词典的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索字典的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索词典的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索字典,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索词典,则拒绝删除它。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name示例 - 移除文本搜索字典english: + 移除文本检索词典english DROP TEXT SEARCH DICTIONARY english; - 如果已有文本搜索配置使用该字典,此命令将不会成功。 - 加上CASCADE可以在删除字典的同时删除这类配置。 + 如果已有文本检索配置使用该词典,此命令将不会成功。 + 加上CASCADE可以在删除词典的同时删除这类配置。 diff --git a/zh/13/ref/drop_tsparser.sgml b/zh/13/ref/drop_tsparser.sgml index a65f47be..ea74f0f8 100644 --- a/zh/13/ref/drop_tsparser.sgml +++ b/zh/13/ref/drop_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH PARSER - 移除一个文本搜索解析器 + 移除一个文本检索解析器 @@ -29,7 +29,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name描述 - DROP TEXT SEARCH PARSER删除一个现有文本搜索解析器。 + DROP TEXT SEARCH PARSER删除一个现有文本检索解析器。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] namename - 一个现有文本搜索解析器的名称(可以被模式限定)。 + 一个现有文本检索解析器的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索解析器的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索解析器的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索解析器,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索解析器,则拒绝删除它。这是默认值。 @@ -82,13 +82,13 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name示例 - 移除文本搜索解析器my_parser: + 移除文本检索解析器my_parser DROP TEXT SEARCH PARSER my_parser; - 如果已有文本搜索配置使用该解析器,此命令将不会成功。 + 如果已有文本检索配置使用该解析器,此命令将不会成功。 加上CASCADE可以在删除解析器的同时删除这类配置。 diff --git a/zh/13/ref/drop_tstemplate.sgml b/zh/13/ref/drop_tstemplate.sgml index fa1faab0..3a44c927 100644 --- a/zh/13/ref/drop_tstemplate.sgml +++ b/zh/13/ref/drop_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH TEMPLATE - 移除一个文本搜索模板 + 移除一个文本检索模板 @@ -29,7 +29,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name描述 - DROP TEXT SEARCH TEMPLATE删除一个现有文本搜索模板。 + DROP TEXT SEARCH TEMPLATE删除一个现有文本检索模板。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] namename - 现有文本搜索模板的名称(可以被模式限定)。 + 现有文本检索模板的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索模板的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索模板的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索模板,则拒绝删除该模板。这是默认值。 + 如果有任何对象依赖于该文本检索模板,则拒绝删除该模板。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name示例 - 移除文本搜索模板thesaurus: + 移除文本检索模板thesaurus DROP TEXT SEARCH TEMPLATE thesaurus; - 如果已有文本搜索字典使用该模板,此命令将不会成功。加上CASCADE - 可以在删除该模板的同时删除这类字典。 + 如果已有文本检索词典使用该模板,此命令将不会成功。加上CASCADE + 可以在删除该模板的同时删除这类词典。 diff --git a/zh/13/ref/initdb.sgml b/zh/13/ref/initdb.sgml index 067e24f9..a577a4d7 100644 --- a/zh/13/ref/initdb.sgml +++ b/zh/13/ref/initdb.sgml @@ -142,7 +142,7 @@ PostgreSQL documentation - + @@ -154,7 +154,7 @@ PostgreSQL documentation - + @@ -214,7 +214,7 @@ PostgreSQL documentation - 使initdb从文件中读取引导超级用户的密码。文件的第一行会被当作密码。 + 使initdb从文件中读取数据库超级用户的密码。文件的第一行会被当作密码。 @@ -234,7 +234,7 @@ PostgreSQL documentation - 设置默认文本搜索配置。更多信息见 + 设置默认文本检索配置。更多信息见 @@ -245,10 +245,9 @@ PostgreSQL documentation - 选择数据库超级用户的用户名。默认值是运行 - initdb的实际用户名称。超级用户的名称本身 - 并不重要,不过即使操作系统用户名称不同,人们也可能选择沿用惯常 - 的名称postgres。 + 选择数据库超级用户的用户名。默认值是运行initdb的有效用户的名称。 + 超级用户的名称本身并不重要,不过即使操作系统用户名称不同,也可以选择沿用惯常的名称 + postgres @@ -258,7 +257,7 @@ PostgreSQL documentation - 使initdb提示输入要赋给引导超级用户的密码。如果不打算使用密码认证, + 使initdb提示输入要赋给数据库超级用户的密码。如果不打算使用密码认证, 这一点并不重要。否则,在设置密码之前将无法使用密码认证。 diff --git a/zh/13/ref/pgbench.sgml b/zh/13/ref/pgbench.sgml index 8cf1c187..798fac60 100644 --- a/zh/13/ref/pgbench.sgml +++ b/zh/13/ref/pgbench.sgml @@ -36,7 +36,7 @@ PostgreSQL documentation 描述 - pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,必要时可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 + pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,也可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 @@ -57,13 +57,15 @@ tps = 85.296346 (excluding connections establishing) 前六行报告了一些最重要的参数设置。下一行报告已完成的事务数和预期的事务数(后者就是客户端数与每个客户端的事务数的乘积);除非运行在完成前失败,否则这两个数应该相等。(在 模式下,只打印实际的事务数。)最后两行报告每秒事务数,分别计入和不计入启动数据库会话的时间。 - 默认的类 TPC-B 事务测试要求预先建立特定的表。pgbench应使用(初始化)选项调用,以创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: + + 默认的类 TPC-B 事务测试要求预先建立特定的表。应使用(初始化)选项调用pgbench来创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: + + pgbench -i other-options dbname - 其中, - dbname是已创建好的、用于执行测试的数据库名称。(可能还需要使用, - 和/或选项来指定如何连接到数据库服务器。) + 其中dbname是已创建好的、用于执行测试的数据库名称。(可能还需要使用和/或选项来指定如何连接到数据库服务器。) + @@ -76,14 +78,14 @@ pgbench -i other-options 在默认的比例因子 1 下,这些表最初包含如下行数: -table # of rows +表 行数 --------------------------------- pgbench_branches 1 pgbench_tellers 10 pgbench_accounts 100000 pgbench_history 0 - 可以使用(比例因子)选项来增加行数,而且在大多数场景下也确实应该这样做。此时还可以配合使用(fillfactor)选项。 + 可以使用(比例因子)选项来增加行数,而且在大多数场景下通常也应该这样做。此时还可以配合使用(fillfactor)选项。 @@ -102,14 +104,14 @@ pgbench options d 选项 - 下面分成三个部分。数据库初始化期间使用的选项和运行基准时会使用不同的选项,但也有一些选项在两种情况下都使用。 + 以下内容分为三个小节。数据库初始化和运行基准测试时使用不同的选项,但有些选项在这两种情况下都适用。 初始化选项 - pgbench 接受以下用于初始化的命令行参数: + pgbench 接受以下命令行初始化参数: @@ -176,7 +178,7 @@ pgbench options d 使用G(服务器端生成数据)时, pgbench客户端只发送较小的查询,随后实际数据在服务器端生成。 - 这种方式几乎不需要额外带宽,但服务器会承担更多工作。 + 这种方式不需要大量带宽,但服务器会承担更多工作。 使用G时,生成数据期间不会打印任何进度消息。 @@ -346,7 +348,7 @@ pgbench options d 基准测试选项 - pgbench 接受以下用于基准测试的命令行参数: + pgbench 接受以下命令行基准测试参数: @@ -482,13 +484,13 @@ pgbench options d 用于向服务器提交查询的协议: - simple: 使用简单查询协议。 + simple:使用简单查询协议。 - extended: 使用扩展查询协议。 + extended:使用扩展查询协议。 - prepared: 使用带有预备语句的扩展查询协议。 + prepared:使用带有预备语句的扩展查询协议。 prepared模式下,pgbench从第二次查询迭代开始复用解析分析结果,因此pgbench比其他模式运行得更快。 @@ -573,7 +575,7 @@ pgbench options d 较高的计划滞后时间表明,在所选客户端数和线程数下,系统无法以指定速率处理事务。 当平均事务执行时间长于事务之间的计划间隔时,后续事务会不断进一步落后, - 而计划滞后时间也会随着测试持续时间增加。在这种情况下,只能降低指定的事务速率。 + 而计划滞后时间也会随着测试持续时间增加。在这种情况下,需要降低指定的事务速率。 @@ -585,7 +587,7 @@ pgbench options d pgbench输出中报告指定的比例因子。 - 对于内置测试,这通常没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 + 对于内置测试,这没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 但在只测试自定义基准(选项)时, 除非使用此选项,否则比例因子会被报告为 1。 @@ -884,7 +886,7 @@ pgbench options d - 在PostgreSQL 9.6 之前,脚本文件中的 SQL 命令以换行符结束,因此不能跨行续写。现在,连续的 SQL 命令之间必须用分号分隔(不过,如果 SQL 命令后面跟着元命令,则不需要分号)。如果需要创建适用于新旧版本pgbench的脚本文件,请务必将每条 SQL 命令写在单独一行,并以分号结尾。 + 在PostgreSQL 9.6 之前,脚本文件中的 SQL 命令以换行结束,因此不能跨行。现在连续 SQL 命令之间必须用分号分隔(如果 SQL 命令后面跟着一个元命令,则不需要分号)。如果需要创建一个既能在旧版也能在新版pgbench下工作的脚本文件,务必将每个 SQL 命令写在单独一行,并以分号结束。 @@ -919,7 +921,7 @@ pgbench options d default_seed - 默认在哈希函数中使用的种子 + 默认在 hash 函数中使用的种子 @@ -936,7 +938,7 @@ pgbench options d
- 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令及其参数之间以空白分隔。支持的元命令如下: + 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令的参数以空白分隔。支持的元命令如下: @@ -967,7 +969,7 @@ UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid RETURNING abalance \gset --- compound of two queries +-- 两个查询的组合 SELECT 1 \; SELECT 2 AS two, 3 AS three \gset p_ SELECT 4 AS four \; SELECT 5 AS five \aset @@ -1058,7 +1060,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset
- command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在其开头再写一个冒号。 + command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在argument开头再写一个冒号。 @@ -1378,7 +1380,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 加 + 加法 5 + 4 @@ -1392,7 +1394,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 减 + 减法 3 - 2.0 @@ -1406,7 +1408,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 乘 + 乘法 5 * 4 @@ -1420,7 +1422,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 除法(如果两个输入都是整数,则将结果截断为零) + 除法(如果两个输入都是整数,则将结果向零截断) 5 / 3 @@ -1448,7 +1450,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 取反 + 取相反数 - 2.0 @@ -1535,7 +1537,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset double - 指数(e 的给定次幂) + 指数函数(e 的给定次幂) exp(1.0) @@ -1577,7 +1579,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算 FNV-1a 哈希。 + 计算 FNV-1a hash hash_fnv1a(10, 5432) @@ -1591,7 +1593,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算 MurmurHash2 哈希。 + 计算 MurmurHash2 hash hash_murmur2(10, 5432) @@ -1697,7 +1699,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset random(1, 10) - an integer between 1 and 10 + 介于1和10之间的整数 @@ -1707,11 +1709,11 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer
- 计算[lb, ub]中的指数分布随机整数,如下所示。 + 计算[lb, ub]中的指数分布随机整数,详见下文。 random_exponential(1, 10, 3.0) - an integer between 1 and 10 + 介于1和10之间的整数 @@ -1721,11 +1723,11 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer
- 计算[lb, ub]中的高斯分布随机整数,如下所示。 + 计算[lb, ub]中的高斯分布随机整数,详见下文。 random_gaussian(1, 10, 2.5) - an integer between 1 and 10 + 介于1和10之间的整数 @@ -1739,7 +1741,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset
random_zipfian(1, 10, 1.5) - an integer between 1 and 10 + 介于1和10之间的整数 @@ -1766,33 +1768,36 @@ SELECT 4 AS four \; SELECT 5 AS five \aset - 对于指数分布,parameter通过在以下位置截断一个快速衰减的指数分布来控制分布:parameter,然后将其投影到边界之间的整数上。准确地说,令 + + 对于指数分布,parameter通过在parameter处截断一个快速衰减的指数分布,再将其投影到边界之间的整数上,从而控制分布。准确地说,令 + f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) -则值i 位于 min 和 - max 之间(包括端点),被抽到的概率为: - f(i) - f(i + 1)。 + + 则minmax之间(含边界)的值i会以f(i) - f(i + 1)的概率被抽中。 - 直观地说,parameter越大,接近min的值被访问得越频繁,而接近max的值被访问得越少。parameter越接近 0,访问分布就越平坦(越均匀)。对该分布的一个粗略近似是:范围内最常出现的 1% 的值,即接近min的那些值,会在parameter% 的时间里被抽中。parameter的值必须严格为正。 + + 直观地说,parameter越大,越靠近min的值越容易被抽到,而越靠近max的值越不容易被抽到。parameter越接近 0,分布就越平坦(也就越均匀)。对这种分布的一个粗略近似是:范围内出现频率最高的 1% 的值,即最靠近min的那些值,大约会占到parameter% 的抽样次数。parameter必须严格大于 0。 + - 对于高斯分布,该区间映射到标准正态分布(经典的钟形高斯曲线),左侧截断于 -parameter,右侧截断于 +parameter。区间中部的值更容易被抽到。准确地说,如果 PHI(x) 为标准正态分布的累积分布函数,均值 mu 定义为 (max + min) / 2.0,并且 - + 对于高斯分布,该区间会映射到一个标准正态分布(经典钟形高斯曲线),并在左侧-parameter和右侧+parameter处截断。区间中部的值更容易被抽到。准确地说,如果PHI(x)是标准正态分布的累积分布函数,均值mu定义为(max + min) / 2.0,则有 + f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / (2.0 * PHI(parameter) - 1) - 那么,值 i 位于 min 和 - max 之间(包括端点),被抽到的概率为: - f(i + 0.5) - f(i - 0.5)。直观地说,parameter 越大,越靠近区间中部的值被抽到的频率就越高,而越靠近 min 和 - max 边界的值被抽到的频率就越低。约 67% 的值抽自区间中间的 1.0 / parameter,即均值周围相对 0.5 / parameter 的范围;95% 的值抽自区间中间的 2.0 / parameter,即均值周围相对 1.0 / parameter 的范围。例如,如果 parameter 为 4.0,则 67% 的值抽自区间中间四分之一(1.0 / 4.0)的范围(即从 - 3.0 / 8.05.0 / 8.0),95% 的值抽自区间中间一半(2.0 / 4.0)内,也就是第二和第三四分位。允许的最小parameter值为 2.0。 + 则minmax(包含边界)之间的值i被抽中的概率为:f(i + 0.5) - f(i - 0.5)。直观地说,parameter越大,越靠近区间中间的值被抽到的频率越高,而越靠近minmax边界的值被抽到的频率越低。大约 67% 的值会落在区间中部1.0 / parameter这一段内,也就是均值两侧各占区间长度0.5 / parameter的范围内;约 95% 的值会落在区间中部2.0 / parameter这一段内,也就是均值两侧各占区间长度1.0 / parameter的范围内。例如,如果parameter为 4.0,则 67% 的值会落在区间中间四分之一(1.0 / 4.0)内,也就是从3.0 / 8.05.0 / 8.0;95% 的值会落在区间中间一半(2.0 / 4.0)内,也就是第二和第三四分位。允许的最小parameter值为 2.0。 +
- random_zipfian会生成一个有界的 Zipfian 分布。parameter定义该分布的倾斜程度。parameter越大,越靠近区间起始处的值被抽到的频率就越高。这种分布满足:假设范围从 1 开始,抽到k与抽到k+1的概率之比为((k+1)/k)**parameter。例如,random_zipfian(1, ..., 2.5)生成值1的频率大约是生成2(2/1)**2.5 = - 5.66倍,而后者的生成频率又大约是生成3(3/2)**2.5 = 2.76倍,依此类推。 + random_zipfian会生成一个有界的 Zipfian 分布。 + parameter定义该分布的倾斜程度。parameter越大,越靠近区间起始处的值被抽到的频率就越高。 + 这种分布满足:假设范围从 1 开始,抽到k与抽到k+1的概率之比为 + ((k+1)/k)**parameter。 + 例如,random_zipfian(1, ..., 2.5)生成值1的频率大约是生成2(2/1)**2.5 = 5.66倍,而生成2的频率又大约是生成3(3/2)**2.5 = 2.76倍,依此类推。 pgbench的实现基于《Non-Uniform Random Variate Generation》,Luc Devroye,Springer 1986,第 550-551 页。 @@ -1802,8 +1807,8 @@ f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / - 哈希函数 hashhash_murmur2 和 - hash_fnv1a 接受一个输入值和一个可选的种子参数。如果未提供种子,则使用 :default_seed 的值,该值随机初始化,除非通过命令行 -D 选项设置。哈希函数可以用来打散随机函数的分布,例如 random_zipfian 或 + Hash 函数 hashhash_murmur2 和 + hash_fnv1a 接受一个输入值和一个可选的种子参数。如果未提供种子,则使用 :default_seed 的值,该值随机初始化,除非通过命令行 -D 选项设置。Hash 函数可以用来打散随机函数的分布,例如 random_zipfianrandom_exponential。例如,以下 pgbench 脚本模拟了社交媒体和博客平台中可能出现的典型真实工作负载,其中少数账户产生了过多的负载: @@ -1865,8 +1870,7 @@ END; - 下面是单个客户端运行时生成的日志文件片段: - + 这里是在单个客户端运行中生成的一个日志文件的片段: 0 199 2241 0 1175850568 995598 0 200 2465 0 1175850568 998079 @@ -1874,9 +1878,8 @@ END; 0 202 2038 0 1175850569 2663 - 下面是另一个使用 --rate=100--latency-limit=5 的示例(请注意额外的 - schedule_lag 列): - + 另一个示例使用的是--rate=100以及--latency-limit=5(注意额外的 + schedule_lag列): 0 81 4621 0 1412881037 912698 3005 0 82 6173 0 1412881037 914578 4304 @@ -1886,7 +1889,8 @@ END; 0 84 4142 0 1412881037 918023 2333 0 85 2465 0 1412881037 919759 740 - 在这个示例中,事务 82 超时了,因为其延迟(6.173 ms)超过了 5 ms 的限制。接下来的两个事务被跳过,因为它们在开始前就已经超时。 + 在这个示例中,事务 82 迟到了,因为它的延迟(6.173 ms)超过了 + 5 ms 限制。接下来的两个事务被跳过,因为它们在开始之前就已经迟到了。 @@ -1911,7 +1915,7 @@ END; sum_latency_2 是区间内事务延迟的平方和, min_latency 是区间内的最小延迟,而 max_latency 是区间内的最大延迟。接下来的字段 - sum_lagsum_lag_2min_lagmax_lag 仅在使用 选项时出现。它们提供各事务等待前一事务完成的时间统计,即各事务计划开始时间与实际开始时间之间的差值。最后一个字段 skipped 仅在还使用 选项时出现。它记录因开始时间过晚而被跳过的事务数。每个事务都计入其提交时所在的时间区间。 + sum_lagsum_lag_2min_lagmax_lag 仅在使用 选项时出现。它们提供各事务等待前一事务完成的时间统计,即各事务计划开始时间与实际开始时间之间的差值。最后一个字段 skipped 仅在还使用 选项时出现。它记录因开始时间过晚而被跳过的事务数。每个事务都计入其提交时所在的时间区间。 @@ -1931,7 +1935,7 @@ END; - 逐语句报告 + 逐语句延迟 使用选项时,pgbench会收集每个客户端执行的每条语句所经过的事务时间。基准测试完成后,它会报告这些值的平均值,称为每条语句的延迟。 @@ -1968,11 +1972,11 @@ statement latencies in milliseconds: - 所有数值都是针对每个客户端执行的每条语句计算的,并在基准测试完成后报告。 + 如果指定了多个脚本文件,则会分别为每个脚本文件报告平均值。 - 请注意,收集计算每条语句延迟所需的额外计时信息会增加一些开销。这会降低平均执行速度,使计算出的 TPS 下降。减速程度因平台和硬件而异,差别可能很大。比较启用和未启用延迟报告时的平均 TPS 值,是衡量计时开销是否显著的好方法。 + 注意,为逐语句延迟计算收集额外的计时信息会带来一定开销。这会拖慢平均执行速度,并降低计算出的 TPS。减速幅度在很大程度上取决于平台和硬件。比较启用和未启用延迟报告时的平均 TPS 值,是判断这一计时开销是否显著的好方法。 @@ -1993,7 +1997,7 @@ statement latencies in milliseconds: - 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和空闲空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 + 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和无效空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 diff --git a/zh/13/ref/psql-ref.sgml b/zh/13/ref/psql-ref.sgml index c71a8faa..b6c88214 100644 --- a/zh/13/ref/psql-ref.sgml +++ b/zh/13/ref/psql-ref.sgml @@ -47,7 +47,7 @@ PostgreSQL documentation - 把所有非空输入行按照它们被读入的形式打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 + 在读入时将所有非空输入行打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 all @@ -78,10 +78,10 @@ PostgreSQL documentation - 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,直到它处理完序列中所有的选项之后终止。 + 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,而是在按顺序处理完所有选项后终止。 - command必须是一个服务器完全可解析的命令字符串(即不包含psql相关的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: + command必须是一个服务器完全可解析的命令字符串(即不包含psql专有的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: psql -c '\x' -c 'SELECT * FROM foo;' @@ -94,7 +94,7 @@ echo '\x \\ SELECT * FROM foo;' | psql 每个SQL命令字符串传递给都作为一个单独的请求发送到服务器。 因此,即使字符串包含多个SQL命令,服务器也会将其作为单个事务执行, - 除非字符串中包含明确的BEGIN/COMMIT命令将其分成多个事务。 + 除非字符串中包含显式的BEGIN/COMMIT命令将其分成多个事务。 (有关服务器如何处理多查询字符串的更多详细信息,请参见。) 此外,psql只打印字符串中最后一条SQL命令的结果。这与从文件读取同一字符串或将其送入psql标准输入时的行为不同,因为在这些情况下,psql会分别发送每条SQL命令。 @@ -157,7 +157,7 @@ EOF - 如果filename-(连字符),则会读取标准输入,直到遇到 EOF 指示或\q元命令。这可用于将交互式输入与文件输入交错使用。不过请注意,这种情况下不会使用 Readline(很像指定了时的情况)。 + 如果filename-(连字符),则会读取标准输入,直到遇到 EOF 指示或\q元命令。这可用于将交互式输入与文件输入交错使用。不过请注意,这种情况下不会使用 Readline(很像指定了时的情况)。 @@ -171,7 +171,7 @@ EOF - 使用separator作为非对齐输出的域分隔符。这等效于\pset fieldsep或者\f。 + 使用separator作为非对齐输出的字段分隔符。这等效于\pset fieldsep或者\f
@@ -225,7 +225,7 @@ EOF - 不要使用Readline进行行编辑,也不要使用命令历史记录。这有助于在剪切和粘贴时关闭制表符展开。 + 不要使用Readline进行行编辑,也不要使用命令历史记录。这有助于在剪切和粘贴时关闭TAB 补全。
@@ -245,7 +245,7 @@ EOF - 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。 + 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展名。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。
@@ -265,7 +265,7 @@ EOF - 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息以及多种输出。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon。 + 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息和各种提示信息。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon @@ -285,7 +285,7 @@ EOF - 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户一个可以取消执行的选项。使用这个选项可以调试脚本。 + 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户,并允许取消执行。使用这个选项可以调试脚本。 @@ -295,7 +295,7 @@ EOF - 运行在单行模式中,其中新行会终止一个 SQL 命令,就像分号的作用一样。 + 运行在单行模式中,其中换行符会终止一个 SQL 命令,就像分号的作用一样。 @@ -321,7 +321,7 @@ EOF - 指定要替换HTML table标签的选项。详见\pset tableattr。 + 指定要放在HTML table标签内的选项。详见\pset tableattr @@ -342,7 +342,7 @@ EOF - 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要重置一个变量,去掉等号就行。要把一个变量置为空值,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 + 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要取消变量的设置,去掉等号就行。要把一个变量设为空字符串,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 @@ -404,7 +404,7 @@ EOF - 不读取启动文件(要么是系统范围的psqlrc文件,要么是用户的~/.psqlrc文件)。 + 不读取启动文件(既不读取系统范围的psqlrc文件,也不读取用户的~/.psqlrc文件)。 @@ -414,7 +414,7 @@ EOF - 设置非对齐输出的域分隔符为零字节。这等效于\pset fieldsep_zero。 + 设置非对齐输出的字段分隔符为零字节。这等效于\pset fieldsep_zero @@ -424,7 +424,7 @@ EOF - 设置非对齐输出的记录分隔符为零字节。例如,这对与xargs -0配合有关。这等效于\pset recordsep_zero。 + 设置非对齐输出的记录分隔符为零字节。例如,这有助于与xargs -0配合使用。这等效于\pset recordsep_zero @@ -484,10 +484,9 @@ EOF 分别指定这些参数。如果遇到一个不属于任何选项的参数, 它将被解释为数据库名(如果数据库名已经给出,则解释为数据库用户名)。 并非所有这些选项都是必需的;它们都有有用的默认值。如果省略主机名, - psql 在 Unix 上将通过 Unix 域套接字连接到本地主机上的服务器, - 在 Windows 上则通过 TCP/IP 连接到 localhost。默认端口号在编译时确定。 + psql 将通过 Unix 域套接字连接到本地主机上的服务器,而在没有 Unix 域套接字的机器上则通过 TCP/IP 连接到 localhost。默认端口号在编译时确定。 由于数据库服务器使用相同的默认值,因此在大多数情况下不必指定端口。 - 默认数据库用户名是你的操作系统用户名。数据库用户名确定后,它也会被用作默认数据库名。 + 默认用户名是你的操作系统用户名,默认数据库名也是如此。 请注意,你不能随意以任意数据库用户名连接到任意数据库。数据库管理员应当已经告知你拥有的访问权限。
@@ -548,7 +547,7 @@ testdb=> 元命令 - 你输入到psql中的任何以未加引用的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 + 你输入到psql中的任何以未加引号的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 @@ -565,7 +564,7 @@ testdb=> - 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉尾随换行)会替换反引号中的文本。在反引号包围的文本内部,不会发生特殊引用或其他处理,只有一种例外:如果出现:variable_name,且variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会被适当地引用成单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于回车和换行字符在所有平台上都无法安全引用,当变量值中出现这类字符时,:'variable_name'这种形式会打印错误消息,并且不会替换变量值。 + 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉末尾的换行符)会替换反引号中的文本。在反引号包围的文本内部,不会进行特殊的引号处理或其他处理,但出现:variable_name时,如果variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会适当地加上引号,使其成为单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于无法保证在所有平台上都能对回车和换行字符安全地加引号,当变量值中出现这类字符时,:'variable_name'形式会打印错误消息,并且不会替换变量值。 @@ -588,7 +587,7 @@ testdb=> \a - 如果当前表格输出格式是不对齐,则切换为对齐;否则切换为不对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset。 + 如果当前表格输出格式是非对齐,则切换为对齐;否则切换为非对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset @@ -609,7 +608,7 @@ testdb=> 默认情况下,参数在位置语法中被重用,但在给定conninfo字符串时不会被重用。 传递-reuse-previous=on-reuse-previous=off作为第一个参数将覆盖该默认设置。 如果参数被重用,则任何未明确指定为位置参数或在conninfo字符串中的参数将从现有连接的参数中获取。 - 一个例外是,如果使用位置语法将host设置更改为其先前值,则现有连接参数中存在的任何hostaddr设置将被删除。 + 一个例外是,如果使用位置语法更改host设置,使其不同于先前的值,则现有连接参数中存在的任何hostaddr设置将被删除。 此外,仅当用户、主机和端口设置未更改时,才会重用现有连接使用的任何密码。 当命令既不指定也不重用特定参数时,将使用libpq的默认值。 @@ -625,7 +624,7 @@ testdb=> => \c mydb myuser host.dom 6432 => \c service=foo => \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable" -=> \c -reuse-previous=on sslmode=require -- changes only sslmode +=> \c -reuse-previous=on sslmode=require -- 仅更改 sslmode => \c postgresql://tom@localhost/mydb?application_name=myapp
@@ -767,7 +766,9 @@ testdb=> \da[S] [ pattern ] - 列出聚合函数及其返回类型和操作的数据类型。如果指定了pattern,则只显示名称匹配该模式的聚合函数。默认只显示用户创建的对象;提供模式或S修饰符可包含系统对象。 + + 列出聚合函数,以及它们的返回类型和所作用的数据类型。如果指定了 pattern,则只显示名称与模式匹配的聚合。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 @@ -775,21 +776,28 @@ testdb=> \dA[+] [ pattern ] - 列出访问方法。如果指定了pattern,则只显示名称匹配该模式的访问方法。如果在命令名后附加+,还会列出每个访问方法关联的处理函数和描述。 + + 列出访问方法。如果指定了 pattern,则只显示名称与模式匹配的访问方法。如果在命令名后追加 +,则每个访问方法都会连同其关联的处理器函数和描述一起列出。 + \dAc[+] [access-method-pattern [input-type-pattern]] - 列出操作符类(见)。如果指定了access-method-pattern,则只列出关联访问方法的名称匹配该模式的操作符类。如果指定了input-type-pattern,则只列出关联输入类型的名称匹配该模式的操作符类。如果在命令名后附加+,还会列出每个操作符类关联的操作符族和拥有者。 + + 列出操作符类(参见 )。如果指定了 access-method-pattern,则只列出与名称匹配该模式的访问方法关联的操作符类。如果指定了 input-type-pattern,则只列出与名称匹配该模式的输入类型关联的操作符类。如果在命令名后追加 +,则每个操作符类都会连同其关联的操作符族和所有者一起列出。 + \dAf[+] [access-method-pattern [input-type-pattern]] - 列出操作符族(见)。如果指定了access-method-pattern,则只列出关联访问方法的名称匹配该模式的操作符族。如果指定了input-type-pattern,则只列出关联输入类型的名称匹配该模式的操作符族。如果在命令名后附加+,还会列出每个操作符族的拥有者。 + + 列出操作符族(参见 )。如果指定了 access-method-pattern,则只列出与名称匹配该模式的访问方法关联的操作符族。如果指定了 input-type-pattern,则只列出与名称匹配该模式的输入类型关联的操作符族。如果在命令名后追加 +,则每个操作符族都会连同其所有者一起列出。 + @@ -804,7 +812,9 @@ testdb=> \dAp[+] [access-method-pattern [operator-family-pattern]] - 列出与操作符族关联的支持函数(见)。如果指定了access-method-pattern,则只列出关联访问方法的名称匹配该模式的操作符族函数。如果指定了operator-family-pattern,则只列出名称匹配该模式的操作符族函数。如果在命令名后附加+,则详细显示函数,包括其实际参数列表。 + + 列出与操作符族关联的支持函数(参见 )。如果指定了 access-method-pattern,则只列出与名称匹配该模式的访问方法所关联的操作符族函数。如果指定了 operator-family-pattern,则只列出名称与该模式匹配的操作符族函数。如果在命令名后追加 +,函数会以详细形式显示,并带有其实际参数列表。 + @@ -812,7 +822,10 @@ testdb=> \db[+] [ pattern ] - 列出表空间。如果指定了pattern,则只显示名称匹配该模式的表空间。如果在命令名后附加+,还会列出每个表空间关联的选项、磁盘大小、权限和描述。 + + 列出表空间。如果指定了 pattern,则只显示名称与模式匹配的表空间。如果在命令名后追加 +,则每个表空间都会连同其关联选项、磁盘大小、权限和描述一起列出。 + @@ -820,7 +833,9 @@ testdb=> \dc[S+] [ pattern ] - 列出字符集编码之间的转换。如果指定了pattern,则只列出名称匹配该模式的转换。默认只显示用户创建的对象;提供模式或S修饰符可包含系统对象。如果在命令名后附加+,还会列出每个对象关联的描述。 + + 列出字符集编码之间的转换。如果指定了 pattern,则只列出名称与模式匹配的转换。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 +,则每个对象都会连同其相关描述一起列出。 + @@ -850,7 +865,10 @@ testdb=> \dD[S+] [ pattern ] - 列出域。如果指定了pattern,则只显示名称匹配该模式的域。默认只显示用户创建的对象;提供模式或S修饰符可包含系统对象。如果在命令名后附加+,还会列出每个对象关联的权限和描述。 + + 列出域。如果指定了 pattern,则只显示名称与模式匹配的域。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 +,则每个对象都会连同其相关权限和描述一起列出。 + @@ -876,7 +894,12 @@ testdb=> \dv[S+] [ pattern ] - 在这组命令中,字母Eimstv分别代表外部表、索引、物化视图、序列、表和视图。可以按任意顺序指定这些字母中的任意一个或全部,以获取相应类型的对象列表。例如,\dti列出表和索引。如果在命令名后附加+,还会列出每个对象的持久性状态(永久、临时或不记录 WAL)、磁盘上的物理大小以及关联的描述(如果有)。如果指定了pattern,则只列出名称匹配该模式的对象。默认只显示用户创建的对象;提供模式或S修饰符可包含系统对象。 + + 在这组命令中,字母 E、 + ims、 + tv + 分别表示外部表、索引、物化视图、序列、表和视图。你可以按任意顺序指定其中任意一个或多个字母,以获取这些类型对象的列表。例如,\dti 会列出表和索引。如果在命令名后追加 +,则每个对象都会连同其持久性状态(永久、临时或不记录 WAL)、磁盘上的物理大小以及相关描述(如果有)一起列出。如果指定了 pattern,则只列出名称与模式匹配的对象。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 + @@ -933,28 +956,28 @@ testdb=> \dF[+] [ pattern ] - 列出文本搜索配置。如果指定了pattern,则只显示名称匹配该模式的配置。如果使用\dF+形式,则显示每个配置的完整说明,包括底层文本搜索解析器和每种解析器词元类型的词典列表。 + 列出全文检索配置。如果指定了pattern,则只显示名称匹配该模式的配置。如果使用\dF+形式,则显示每个配置的完整说明,包括底层全文检索解析器和每种解析器词元类型的词典列表。 \dFd[+] [ pattern ] - 列出文本搜索词典。如果指定了pattern,则只显示名称匹配该模式的词典。如果使用\dFd+形式,还会显示每个选中词典的附加信息,包括底层文本搜索模板和选项值。 + 列出全文检索词典。如果指定了pattern,则只显示名称匹配该模式的词典。如果使用\dFd+形式,还会显示每个选中词典的附加信息,包括底层全文检索模板和选项值。 \dFp[+] [ pattern ] - 列出文本搜索解析器。如果指定了pattern,则只显示名称匹配该模式的解析器。如果使用\dFp+形式,则显示每个解析器的完整说明,包括底层函数和可识别的词元类型列表。 + 列出全文检索解析器。如果指定了pattern,则只显示名称匹配该模式的解析器。如果使用\dFp+形式,则显示每个解析器的完整说明,包括底层函数和可识别的词元类型列表。 \dFt[+] [ pattern ] - 列出文本搜索模板。如果指定了pattern,则只显示名称匹配该模式的模板。如果使用\dFt+形式,还会显示每个模板的附加信息,包括底层函数名。 + 列出全文检索模板。如果指定了pattern,则只显示名称匹配该模式的模板。如果使用\dFt+形式,还会显示每个模板的附加信息,包括底层函数名。 @@ -977,7 +1000,10 @@ testdb=> \dL[S+] [ pattern ] - 列出过程语言。如果指定了pattern,则只列出名称匹配该模式的语言。默认只显示用户创建的语言;提供S修饰符可包含系统对象。如果在命令名后附加+,还会列出每种语言的调用处理程序、验证器、访问权限,以及它是否为系统对象。 + + 列出过程语言。如果指定了 pattern,则只列出名称与模式匹配的语言。默认情况下,只显示用户创建的语言;提供 S 修饰符可包括系统对象。如果在命令名后追加 +,则每种语言都会连同其调用处理器、验证器、访问权限以及它是否为系统对象一起列出。 + @@ -986,7 +1012,10 @@ testdb=> \dn[S+] [ pattern ] - 列出模式(命名空间)。如果指定了pattern,则只列出名称匹配该模式的模式。默认只显示用户创建的对象;提供模式或S修饰符可包含系统对象。如果在命令名后附加+,还会列出每个对象关联的权限和描述(如果有)。 + + 列出模式(命名空间)。如果指定了 pattern,则只列出名称与模式匹配的模式。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 +,则每个对象都会连同其相关权限和描述(如果有)一起列出。 + @@ -1002,7 +1031,9 @@ testdb=> \dO[S+] [ pattern ] - 列出排序规则。如果指定了pattern,则只列出名称匹配该模式的排序规则。默认只显示用户创建的对象;提供模式或S修饰符可包含系统对象。如果在命令名后附加+,还会列出每个排序规则关联的描述(如果有)。请注意,只会显示可用于当前数据库编码的排序规则,因此同一安装中的不同数据库可能会得到不同结果。 + + 列出排序规则。如果指定了 pattern,则只列出名称与模式匹配的排序规则。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 +,则每个排序规则都会连同其相关描述(如果有)一起列出。请注意,只会显示与当前数据库编码兼容的排序规则,因此在同一安装中的不同数据库里结果可能不同。 + @@ -1036,7 +1067,7 @@ testdb=> \drds [ role-pattern [ database-pattern ] ] - 列出已定义的配置设置。这些设置可以专属于角色、专属于数据库,或同时专属于两者。role-patterndatabase-pattern分别用于选择要列出的特定角色和数据库。如果省略,或指定了*,则列出所有设置,分别包括非角色专属或非数据库专属的设置。 + 列出已定义的配置设置。这些设置可以特定于角色、特定于数据库,或同时特定于两者。role-patterndatabase-pattern分别用于选择要列出的角色和数据库。省略某个模式参数或将其指定为*时,不会按该参数筛选,还会分别包含不特定于角色或不特定于数据库的设置。 命令用于定义角色专属和数据库专属的配置设置。 @@ -1052,7 +1083,9 @@ testdb=> \dRs[+] [ pattern ] - 列出复制订阅。如果指定了pattern,则只列出名称匹配该模式的订阅。如果在命令名后附加+,还会显示订阅的附加属性。 + + 列出逻辑复制订阅。如果指定了 pattern,则只列出名称与模式匹配的订阅。如果在命令名后追加 +,则会显示订阅的其他属性。 + @@ -1082,7 +1115,9 @@ testdb=> \dy[+] [ pattern ] - 列出事件触发器。如果指定了pattern,则只列出名称匹配该模式的事件触发器。如果在命令名后附加+,还会列出每个对象关联的描述。 + + 列出事件触发器。如果指定了 pattern,则只列出名称与模式匹配的事件触发器。如果在命令名后追加 +,则每个对象都会连同其相关描述一起列出。 + @@ -1160,7 +1195,9 @@ Tue Oct 26 21:40:57 CEST 1999 \encoding [ encoding ] - 设置客户端字符集编码。如果没有参数,则显示当前编码。 + + 设置客户端字符集编码。没有参数时,此命令显示当前编码。 + @@ -1207,7 +1244,7 @@ Tue Oct 26 21:40:57 CEST 1999 - 设置未对齐查询输出的字段分隔符。默认值是竖线(|)。 + 设置非对齐查询输出的字段分隔符。默认值是竖线(|)。 它等同于\pset fieldsep @@ -1219,16 +1256,16 @@ Tue Oct 26 21:40:57 CEST 1999 \g [ (option=value [...]) ] [ |command ] 将当前查询缓冲区发送给服务器执行。 - 如果在\g后面出现括号,则括号中是用空格分隔的option=格式选项子句列表。这些子句的解释方式与\pset + 如果在\g后面出现括号,则括号中是用空格分隔的option=value格式选项子句列表。这些子句的解释方式与\pset option - 命令相同,但仅在此查询执行期间生效。在此列表中,=符号周围不允许有空格,但选项子句之间必须有空格。如果=被省略,则指定的option会按以下命令的方式更改:\pset option,其中不显式指定。 + value命令相同,但仅在此查询执行期间生效。在此列表中,=符号周围不允许有空格,但选项子句之间必须有空格。如果=value被省略,则指定的option会按以下命令的方式更改:\pset option,其中不显式指定value 如果给出了filename|command参数,查询输出就会写入指定文件,或通过管道传给指定的 shell 命令,而不是照常显示。只有当查询成功返回零个或多个元组时,才会向文件或命令写入;如果查询失败,或执行的是不返回数据的 SQL 命令,则不会写入。 如果当前查询缓冲区为空,则最近发送的查询将被重新执行。除此之外,没有任何参数的\g基本上等同于一个分号。 带有参数的\g提供了一个一次性替代\o命令的选择,并且还允许一次性调整通常由\pset设置的输出格式选项。 - 当最后一个参数以|开头时,该行剩余的全部内容都会被视为要执行的command,其中既不进行变量插值,也不进行反引号展开。该行剩余部分会直接按字面传给 shell。 + 当最后一个参数以|开头时,该行剩余的全部内容都会被视为要执行的command,其中既不进行变量插值,也不进行反引号扩展。该行剩余部分会直接按字面传给 shell。 @@ -1281,7 +1318,7 @@ CREATE INDEX hello 10
- 如果指定了前缀,则会将该字符串加到查询的列名前面,以构成要使用的变量名: + 如果指定了prefix,则会将该字符串加到查询的列名前面,以构成要使用的变量名: => SELECT 'hello' AS var1, 10 AS var2 -> \gset result_ => \echo :result_var1 :result_var2 @@ -1299,7 +1336,10 @@ hello 10 \gx [ (option=value [...]) ] [ filename ] \gx [ (option=value [...]) ] [ |command ] - \gx等价于\g,但它会对当前查询强制使用扩展输出模式,就像在\pset选项列表中包含了expanded=on一样。另请参见\x + + \gx 等同于 \g,不同之处在于它强制为此查询启用扩展输出模式, + 就好像在\pset选项列表中包含了expanded=on一样。另请参见\x。 + @@ -1310,7 +1350,7 @@ hello 10 给出指定SQL命令的语法帮助。如果未指定command, 则psql将列出所有可用语法帮助的命令。如果command是星号 - (*),则显示所有SQL命令的语法帮助。 + (*),则显示所有SQL命令的语法帮助。 @@ -1331,9 +1371,7 @@ hello 10 \H\html - 打开HTML查询输出格式。如果HTML格式已经打开, - 则切换回默认的对齐文本格式。此命令用于兼容性和便利性,但请参阅\pset - 有关设置其他输出选项。 + 打开HTML查询输出格式。如果HTML格式已经打开,则切换回默认的对齐文本格式。此命令是为兼容性和便利性而保留的;设置其他输出选项的方法见\pset @@ -1343,13 +1381,10 @@ hello 10 \i\include filename - 从文件filename中读取输入,并将其执行为 - 好像它是在键盘上键入的一样。 + 从文件filename中读取输入,并像在键盘上输入一样执行它。 - 如果filename- - (连字符),那么标准输入将被读取,直到EOF指示或\q元命令。 - 这可用于将交互式输入与文件输入交错使用。请注意,仅当在最外层级别处于活动状态时,Readline行为才会被使用。 + 如果filename-(连字符),则从标准输入读取,直到遇到 EOF 指示或\q元命令。这可用于将交互式输入与文件输入交错使用。请注意,只有在最外层启用了 Readline,此处才会使用 Readline 功能。 @@ -1368,36 +1403,20 @@ hello 10 这组命令实现了可嵌套的条件块。条件块必须以\if开始,以\endif结束。中间可以包含任意数量的\elif子句,后面还可以选择跟随一个\else子句。普通查询和其他类型的反斜线命令可以(通常也会)出现在构成条件块的命令之间。 - \if\elif命令读取它们的参数,并将其作为布尔表达式进行评估。 - 如果表达式为true,则处理将继续进行;否则,直到达到匹配的\elif、 - \else\endif为止,将跳过行。一旦\if或 - \elif测试成功,同一块中后续\elif命令的参数不会被评估,而是被视为false。 - 在\else之后的行只有在没有早期匹配的\if\elif成功时才会被处理。 + \if\elif命令读取其参数,并将其作为布尔表达式求值。如果表达式的值为true,则正常继续处理;否则,跳过后续行,直到遇到匹配的\elif\else\endif。一旦\if\elif测试成功,同一块中后续\elif命令的参数就不再求值,而是被视为假。只有前面所有匹配的\if\elif测试都未成功时,才会处理\else后面的行。 - expression参数 - 是\if\elif命令的参数, - 受变量插值和反引号扩展的影响,就像任何其他反斜杠命令参数一样。 - 之后,它被评估为一个开/关选项变量的值。因此,有效值是以下任何一个不 - 含糊的不区分大小写匹配之一: - true, false, 1, - 0, on, off, - yes, no。例如, - t, TtR - 都将被视为true。 + 与其他反斜线命令的参数一样,\if\elif命令的expression参数会经过变量插值和反引号扩展。随后,按开/关选项变量值的规则对结果求值。因此,有效值是以下值的不区分大小写且无歧义的匹配:truefalse10onoffyesno。例如,tTtR都会被视为true 不能正确求值为真或假的表达式会产生警告,并被视为假。 - 被跳过的行仍会正常解析,以识别查询和反斜线命令,但查询不会发送给服务器,条件命令(\if\elif\else\endif)以外的反斜线命令会被忽略。对于条件命令,只检查嵌套是否合法。被跳过的行中的变量引用不会展开,也不会执行反引号展开。 + 被跳过的行仍会正常解析,以识别查询和反斜线命令,但查询不会发送给服务器,条件命令(\if\elif\else\endif)以外的反斜线命令会被忽略。对于条件命令,只检查嵌套是否合法。被跳过的行中的变量引用不会展开,也不会执行反引号扩展。 - 所有给定条件块的反斜杠命令必须出现在同一个源文件中。如果在主输入文件或一个 - \include的文件上达到文件结束之前,所有本地 - \if块都没有关闭, - 那么psql将会引发错误。 + 同一个条件块的所有反斜线命令必须出现在同一个源文件中。如果主输入文件或通过\include引入的文件到达 EOF 时,仍有本地\if块未关闭,psql就会报错。 下面是一个示例: --- check for the existence of two separate records in the database and store --- the results in separate psql variables +-- 检查数据库中是否存在两条不同的记录,并将 +-- 结果分别存入不同的 psql 变量 SELECT EXISTS(SELECT 1 FROM customer WHERE customer_id = 123) as is_customer, EXISTS(SELECT 1 FROM employee WHERE employee_id = 456) as is_employee @@ -1443,7 +1462,7 @@ SELECT 从数据库中读取具有OIDloid的大对象,并将其写入filename。请注意,这与服务器函数 - lo_export略有不同,后者使用数据库服务器运行的用户权限, + lo_export略有不同,后者使用运行数据库服务器的用户的权限, 并在服务器的文件系统上操作。 @@ -1482,7 +1501,7 @@ lo_import 152801 - 从数据库中删除具有OIDloid的大对象。 + 从数据库中删除OIDloid的大对象。 @@ -1500,10 +1519,10 @@ lo_import 152801 将后续查询结果保存到文件filename,或通过管道传给 shell 命令command。如果没有指定参数,查询输出将恢复为标准输出。 - 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号展开。该行剩余的内容只会原样传递给 shell。 + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 - 查询结果包括从数据库服务器获取的所有表、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 + 查询结果包括从数据库服务器获取的所有表格、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 @@ -1518,7 +1537,10 @@ lo_import 152801 \p\print - 将当前查询缓冲区打印到标准输出。如果当前查询缓冲区为空,则改为打印最近执行的查询。 + + 将当前查询缓冲区打印到标准输出。 + 如果当前查询缓冲区为空,则打印最近执行的查询。 + @@ -1536,8 +1558,11 @@ lo_import 152801 \prompt [ text ] name - 提示用户提供文本,将其赋值给变量名称。还可以指定可选的提示字符串text。(对于多个单词的提示,用单引号括起文本。) + + 提示用户提供文本,将其赋值给变量name。 + 可以指定一个可选的提示字符串text。 + (对于多个单词的提示,用单引号括起文本。) + 默认情况下,\prompt 使用终端进行输入和输出。然而,如果使用了 @@ -1571,7 +1596,7 @@ lo_import 152801 零(默认值)会导致目标宽度由环境变量COLUMNS控制,或者如果未设置 COLUMNS则由检测到的屏幕宽度控制。 另外,如果columns为零,则wrapped格式仅影响屏幕输出。 - 如果columns为非零,则文件和管道输出也会被包装到该宽度。 + 如果columns为非零,则文件和管道输出也会按该宽度折行。 @@ -1631,12 +1656,12 @@ lo_import 152801 按逗号分隔的列值输出,并应用 RFC 4180 - 中描述的引用规则。 + 中描述的加引号规则。 此输出与服务器的CSV格式的 COPY命令兼容。 - 生成包含列名的标题行,除非 + 生成包含列名的表头行,除非 tuples_only参数设置为 - on。不打印标题和页脚。 + on。不打印表格标题和页脚。 每行以系统相关的行结束字符结束, 对于类Unix系统通常是单个换行符(\n), 对于Microsoft Windows则是回车和换行序列 @@ -1647,11 +1672,11 @@ lo_import 152801 wrapped格式与aligned相似,但会将较宽的数据值折成多行,使输出适应目标列宽。目标宽度的确定方式见columns选项的说明。请注意,psql不会尝试对列标题折行;因此,如果列标题所需的总宽度超过目标宽度,wrapped格式的行为就与aligned相同。 - asciidochtml, - latexlatex-longtable,和 + asciidochtml、 + latexlatex-longtabletroff-ms格式生成的表格旨在包含在使用相应标记语言的文档中。 它们不是完整的文档!这在HTML中可能不是必需的,但在 - LaTeX中,则必须有一个完整的文档包装器。 + LaTeX中,则必须有一个完整文档的外层结构。 latex格式使用LaTeXtabular 环境。 latex-longtable格式需要LaTeX @@ -1671,25 +1696,19 @@ lo_import 152801 - ascii样式使用普通的ASCII字符。数据中的换行使用右边边缘的+符号显示。 - 当wrapped格式将数据从一行换到下一行而没有换行符时,在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 + ascii样式使用普通的ASCII字符。数据中的换行符以右边缘的+符号表示。当wrapped格式在没有换行符的位置把数据折到下一行时,会在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 - old-ascii样式使用普通的ASCII字符,使用在PostgreSQL 8.4及更早版本中使用的格式样式。 - 数据中的换行符使用:符号代替左侧列分隔符显示。 - 当数据从一行换行到下一行而没有换行符时,使用;符号代替左侧列分隔符。 + old-ascii样式使用普通的ASCII字符,采用PostgreSQL 8.4 及更早版本的格式样式。数据中的换行符以替代左侧列分隔符的:符号表示。当数据在没有换行符的位置折到下一行时,则用;符号替代左侧列分隔符。 - unicode样式使用Unicode绘图字符。数据中的换行使用右边距中的回车符号显示。 - 当数据从一行换行到下一行而没有换行符时,第一行的右边距显示省略号符号, - 接着在下一行的左边距再次显示省略号符号。 + unicode样式使用 Unicode 框线绘制字符。数据中的换行符以右边缘的回车符号表示。当数据在没有换行符的位置折到下一行时,会在第一行的右边缘显示省略号符号,并在下一行的左边缘再次显示。 - 当border设置大于零时,linestyle选项还确定了用哪些字符绘制边框线。 - 普通的ASCII字符在任何地方都有效,但在识别Unicode字符的显示器上看起来更好。 + 当border设置大于零时,linestyle选项还决定用哪些字符绘制边框线。普通的ASCII字符在任何环境中都可用,但在支持 Unicode 的显示设备上,Unicode 字符更美观。 @@ -1809,7 +1828,7 @@ lo_import 152801 \qecho text [ ... ] - 这个命令与\echo命令相同,只是输出将被写入查询输出通道,由\o设置。 + 这个命令与\echo相同,只是输出会写入由\o设置的查询输出通道。 @@ -1826,8 +1845,13 @@ lo_import 152801 \restrict restrict_key - 使用给定的密钥进入“受限”模式。在该模式下,唯一允许的元命令是用于退出受限模式的\unrestrict。密钥只能包含字母数字字符。 - 这个命令主要用于pg_dumppg_dumpallpg_restore生成的纯文本转储,但也可能在其他场景中有用。 + + 使用给定的密钥进入受限模式。在该模式下,唯一允许的元命令是用于退出受限模式的\unrestrict。密钥只能包含字母数字字符。 + + + 此命令主要用于pg_dumppg_dumpall + 和pg_restore生成的纯文本转储文件中,但在其他场景下也可能有用。 + @@ -1848,9 +1872,7 @@ lo_import 152801 \set [ name [ value [ ... ] ] ] - psql变量名称设置为,如果给出多个值,则设置为所有值的串接。如果只给出一个参数,则将变量设置为空字符串值。要取消变量设置,请使用\unset命令。 + psql变量name设置为value,如果给出多个值,则设置为所有值的串接。如果只给出一个参数,则将变量设置为空字符串值。要取消变量设置,请使用\unset命令。 \set没有任何参数时,显示当前设置的所有psql变量的名称和值。 @@ -1871,9 +1893,10 @@ lo_import 152801 \setenv name [ value ] - 将环境变量名称设置为;如果没有提供,则取消设置该环境变量。例如: + + 设置环境变量namevalue, + 或者如果未提供value,则取消设置环境变量。示例: + testdb=> \setenv PAGER less testdb=> \setenv LESS -imx4F @@ -1907,8 +1930,7 @@ testdb=> \setenv LESS -imx4F - 这个命令获取并显示指定视图的定义,以CREATE OR REPLACE VIEW命令的形式。 - 定义将打印到当前查询输出通道,由\o设置。 + 这个命令获取指定视图的定义,并以CREATE OR REPLACE VIEW命令的形式显示。定义会打印到由\o设置的当前查询输出通道。 @@ -1975,7 +1997,7 @@ testdb=> \setenv LESS -imx4F 将当前查询缓冲区写入文件filename,或通过管道传递给 shell 命令command。如果当前查询缓冲区为空,则改为写入最近执行的查询。 - 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号展开。该行剩余的内容只会原样传递给 shell。 + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 @@ -1993,8 +2015,13 @@ testdb=> \setenv LESS -imx4F \watch [ seconds ] - 重复执行当前查询缓冲区(如同\g),直到被中断或查询失败。每次执行之间等待指定的秒数(默认为 2)。每个查询结果都会显示一个标题,其中包含\pset title字符串(如果有)、查询开始时间和延迟间隔。 - 如果当前查询缓冲区为空,则改为重新执行最近发送的查询。 + + 重复执行当前查询缓冲区(如同 \g 一样),直到被中断或查询失败。两次执行之间等待指定的秒数(默认 2 秒)。每次查询结果都会带有一个头部,其中包含 \pset title + 字符串(如果有)、查询开始时的时间以及延迟间隔。 + + + 如果当前查询缓冲区为空,则重新执行最近发送的查询。 + @@ -2023,13 +2050,11 @@ testdb=> \setenv LESS -imx4F \! [ command ] - 不带参数时,转义到一个子shell;psql在子shell退出时恢复。 - 带参数时,执行shell命令command。 + 不带参数时,进入一个子 shell;子 shell 退出后,psql恢复运行。带参数时,执行 shell 命令command - 与大多数其他元命令不同,整个行的剩余部分始终被视为\!的参数, - 在参数中不执行变量插值或反引号扩展。行的其余部分被直接传递给shell。 + 与大多数其他元命令不同,该行剩余的全部内容始终被视为\!的参数,其中不会进行变量插值或反引号扩展。该行剩余内容会原样传给 shell。 @@ -2041,7 +2066,7 @@ testdb=> \setenv LESS -imx4F 显示帮助信息。可选的topic参数 (默认为commands)选择要解释的psql的哪个部分: - commands描述psql的反斜杠命令; + commands描述psql的反斜线命令; options描述可以传递给psql的命令行选项; 而variables显示关于psql配置变量的帮助。 @@ -2066,16 +2091,16 @@ select 1\; select 2\; select 3; - + 模式 - patterns + 模式 在 psql 和 pg_dump 中 - 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要把它写成两个相邻的双引号,这同样是符合 SQL 引用标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你不能只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 + 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要在双引号包围的文本内把它写成两个相邻的双引号,这同样是符合 SQL 加引号标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你可以只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 @@ -2097,7 +2122,7 @@ select 1\; select 2\; select 3; 高级特性 - + 变量 @@ -2118,7 +2143,7 @@ bar - 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要重置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 + 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要取消设置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 @@ -2132,7 +2157,7 @@ bar - 控制psql行为的变量通常不能被重置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse。 + 控制psql行为的变量通常不能被取消设置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse @@ -2150,7 +2175,7 @@ bar - 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被重置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交打开模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身即不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 + 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被取消设置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交关闭模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身既不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 @@ -2180,7 +2205,7 @@ bar DBNAME - 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -2189,7 +2214,7 @@ bar ECHO - 如果被设置为all,所有非空输入行会被按照读入它们的样子打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被重置或者设置为none(默认值)则不会显示任何查询。 + 如果被设置为all,所有非空输入行会在读入时打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被设置为none(默认值)则不会显示任何查询。 @@ -2207,7 +2232,7 @@ bar ENCODING - 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者重置。 + 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者取消设置。 @@ -2225,12 +2250,12 @@ bar FETCH_COUNT - 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每一组就会包括这么多个行。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 + 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每组包含的行数等于该整数值。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 - 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT个行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 + 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 @@ -2249,7 +2274,7 @@ bar HISTCONTROL - 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则匹配之前的历史行的行不会被放入。值ignoreboth组合了上述两种值。如果被重置或者被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 + 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则与上一条历史记录相同的行不会被放入。值ignoreboth组合了上述两种值。如果被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 @@ -2291,7 +2316,7 @@ bar HOST - 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -2300,7 +2325,7 @@ bar IGNOREEOF - 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须键入多个连续的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 + 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须连续键入与该数值相等数量的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 @@ -2314,8 +2339,8 @@ bar LASTOID - 最后被影响的 OID 的值,这可能会由INSERT或者\lo_import命令返回。这个变量只保证在下一个SQL命令被显示完之前有效。 - PostgreSQL 服务器从12版开始不再支持 OID 系统列,因此,在面向此类服务器时,跟随在INSERT后面的 LASTOID 将始终为0。 + 最后被影响的 OID 的值,这可能会由INSERT或者\lo_import命令返回。这个变量仅保证在下一个SQL命令的结果显示完之前有效。 + PostgreSQL 服务器从12版开始不再支持 OID 系统列,因此,在面向此类服务器时,执行INSERT后的 LASTOID 将始终为0。 @@ -2340,7 +2365,7 @@ bar - 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被重置或者设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 + 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 @@ -2358,7 +2383,7 @@ bar PORT - 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -2397,7 +2422,7 @@ bar SERVER_VERSION_NUM - 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者重设。 + 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者取消设置。 @@ -2406,7 +2431,7 @@ bar SHOW_CONTEXT - 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT域。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 + 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT字段。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 当VERBOSITY被设置为tersesqlstate时,这个设置无效(另见\errverbose,它可以用来得到刚遇到的错误的详细信息)。 @@ -2425,7 +2450,7 @@ bar SINGLESTEP - 设置这个变量为on等效于命令选项。 + 设置这个变量为on等效于命令行选项 @@ -2443,7 +2468,7 @@ bar USER - 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -2452,7 +2477,7 @@ bar VERBOSITY - 这个变量可以被设置为值defaultverboseterse或者sqlstate来控制错误报告的详细程度(另见\errverbose,在想得到之前的错误的详细版本时使用)。 + 这个变量可以被设置为值defaultverboseterse或者sqlstate来控制错误报告的详细程度(另见\errverbose,在想得到刚遇到的错误的详细信息时使用)。 @@ -2463,7 +2488,7 @@ bar VERSION_NUM - 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或重设。 + 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或取消设置。 @@ -2472,11 +2497,11 @@ bar - - <acronym>SQL</acronym> 中插入变量 + + <acronym>SQL</acronym> 插值 - psql变量的一个关键特性是可以把它们替换(插入)到常规SQL语句中,也可以把它们作为元命令的参数。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。插入一个值而不加引号的语法是在变量名前面加上一个冒号(:)。例如, + psql变量的一个关键特性是可以把它们替换(插值)到常规SQL语句中,也可以把它们替换到元命令的参数中。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。不加引号地插值一个值的语法是在变量名前面加上一个冒号(:)。例如, testdb=> \set foo 'my_table' testdb=> SELECT * FROM :foo; @@ -2485,7 +2510,7 @@ testdb=> SELECT * FROM :foo; - 当一个值被用作 SQL 文本或者标识符时,最安全的是把它加上引用。要引用一个变量的值作为 SQL 文本,可以把变量名称放在单引号中并且在引号前面写一个冒号。要引用作为 SQL 标识符,则可以把变量名称放在双引号中并且在引号前面写一个冒号。这种结构可以正确地处理变量值中嵌入的引号和其他特殊字符。之前的示例用这种方法写会更安全: + 当一个值要用作 SQL 字面量或标识符时,最安全的做法是为它加上引号。要将变量值作为 SQL 字面量加引号,应写一个冒号,后面跟用单引号括起来的变量名。要将变量值作为 SQL 标识符加引号,则在冒号后面用双引号括起变量名。这些写法能正确处理变量值中嵌入的引号和其他特殊字符。前面的示例可用以下更安全的写法: testdb=> \set foo 'my_table' testdb=> SELECT * FROM :"foo"; @@ -2493,11 +2518,11 @@ testdb=> SELECT * FROM :"foo"; - 在被引用的SQL文本和标识符中将不会执行变量插入。因此,一个诸如':foo'的结构不会从一个变量的值产生一个被引用的文本(即便能够也会不安全,因为无法正确地处理嵌入在值中的引号)。 + 在加引号的SQL字面量和标识符内部,不会执行变量插值。因此,':foo'这样的写法不能根据变量值生成加引号的字面量(即使能够生效,也不安全,因为它无法正确处理变量值中嵌入的引号)。 - 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个被引用的字符串插入: + 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个加引号的字符串进行插值: testdb=> \set content `cat my_file.txt` testdb=> INSERT INTO my_table VALUES (:'content'); @@ -2506,7 +2531,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 因为冒号可以合法地出现在 SQL 命令中,一次明显的插入尝试(即:name:'name'或者:"name")不会被替换,除非所提及的变量就是当前被设置的。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 + 因为冒号可以合法地出现在 SQL 命令中,一次明显的插值尝试(即:name:'name'或者:"name")不会被替换,除非所指的变量当前已设置。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 @@ -2514,19 +2539,22 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 文本或者标识符的冒号引用语法是一种psql扩展。 + 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 字面量或者标识符的冒号加引号语法是一种psql扩展。 - + 提示符 psql 发出的提示符可以按你的喜好进行定制。PROMPT1PROMPT2PROMPT3 这三个变量包含描述提示符外观的字符串和特殊转义序列。提示符 1 是 psql 请求新命令时发出的常规提示符。提示符 2 会在录入命令期间还需要更多输入时发出,例如命令尚未以分号结束,或者引号尚未闭合时。在执行 SQL COPY FROM STDIN 命令并需要在终端中输入一行值时,会发出提示符 3。 - 所选提示符变量的值会原样打印,除非遇到百分号(%)。此时会根据下一个字符替换为其他文本。已定义的替换项如下: + + 选中的提示符变量值会按字面输出,除非遇到百分号(%)。根据下一个字符的不同,会替换成某些其他文本。已定义的替换如下: + + %M @@ -2549,10 +2577,11 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %n - 数据库会话用户名。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的展开结果。) + 数据库会话用户名。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) + %/ 当前数据库的名称。 @@ -2560,28 +2589,30 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %~ - %/相同,但如果该数据库是你的默认数据库,则输出~(波浪号)。 + 类似 %/,但如果该数据库是你的默认数据库,则输出 ~ + (波浪号)。 %# - 如果会话用户是数据库超级用户,则为#,否则为>。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的展开结果。) + 如果会话用户是数据库超级用户,则为#,否则为>。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) %p - 当前连接的后端的进程 ID。 + 当前所连接后端的进程 ID。 + %R - 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 dollar-quoted 字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 + 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 美元引用字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 @@ -2608,7 +2639,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %digits - 带有所示八进制码的字符被替换。 + 替换为指定八进制代码对应的字符。 @@ -2661,7 +2692,13 @@ testdb=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# ' - 要在提示符中插入百分号,请写为%%。默认情况下,提示符 1 和 2 为'%/%R%x%# ',提示符 3 为'>> ' + + + 要在提示符中插入百分号,请写成 + %%。默认提示符是: + 提示符 1 和 2 使用 '%/%R%x%# ', + 提示符 3 使用 '>> '。 + @@ -2686,7 +2723,7 @@ $endif - + 环境 @@ -2771,9 +2808,9 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 如果查询结果无法在屏幕上显示完整,它们将通过此命令进行传输。典型的值是moreless。 + 如果查询结果无法在屏幕上显示完整,它们会通过管道传给此命令。典型的值是moreless。 可以通过将PSQL_PAGERPAGER设置为空字符串,或通过调整\pset命令的与分页相关的选项来禁用分页器。 - 这些变量按照列出的顺序进行检查;首先设置的变量将被使用。 + 这些变量按照列出的顺序进行检查;使用按该顺序找到的第一个已设置的变量。 如果它们都没有设置,默认情况下在大多数平台上使用more,但在Cygwin上使用less @@ -2834,11 +2871,11 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' 用户的个人启动文件名为.psqlrc,并且在调用用户的主目录中寻找。 - 在Windows上,个人启动文件的名称改为%APPDATA%\postgresql\psqlrc.conf。 + Windows 没有主目录这一概念,在 Windows 上,个人启动文件的名称为%APPDATA%\postgresql\psqlrc.conf。 在任何情况下,可以通过设置PSQLRC环境变量来覆盖此默认文件路径。 - 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加连字符和PostgreSQL的主版本或次版本号来使其与psql版本相关, + 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加连字符和PostgreSQL的大版本或小版本号来使其与psql版本相关, 例如~/.psqlrc-9.2~/.psqlrc-9.2.5。 最具体版本匹配的文件将优先读取,而不是非特定版本的文件。 @@ -2865,14 +2902,14 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - psql最适合与相同或较旧主要版本的服务器配合使用。 - 如果服务器的版本比psql本身更新,反斜杠命令特别容易失败。 - 然而,\d系列的反斜杠命令应该可以在版本回溯到9.2的服务器上运行, + psql最适合与相同或较旧大版本的服务器配合使用。 + 如果服务器的版本比psql本身更新,反斜线命令特别容易失败。 + 然而,\d系列的反斜线命令应该可以在最低至 7.4 版本的服务器上运行, 但不一定适用于比psql本身更新的服务器。运行SQL命令和显示查询结果的一般功能 - 也应该可以在更新主要版本的服务器上运行,但不能保证在所有情况下都能实现。 + 也应该可以在更新大版本的服务器上运行,但不能保证在所有情况下都能实现。 - 如果你想用psql连接到多个具有不同主版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个主版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 + 如果你想用psql连接到多个具有不同大版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个大版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 @@ -2886,7 +2923,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空格。现在则要求一些空格。 + 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空白。现在则要求用空白分隔。 @@ -2919,23 +2956,31 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' 示例 - 第一个示例展示如何将一个命令分散在多行输入中。请注意提示符的变化: + + 第一个示例展示了如何把一条命令分散到多行输入中。注意提示符的变化: + testdb=> CREATE TABLE my_table ( testdb(> first integer not null default 0, testdb(> second text) testdb-> ; CREATE TABLE -现在再看看表定义: + + 现在再来看一下这个表的定义: + testdb=> \d my_table Table "public.my_table" Column | Type | Collation | Nullable | Default --------+---------+-----------+----------+--------- first | integer | | not null | 0 second | text | | | -现在我们把提示符改得更有趣一些: + + 现在我们把提示符改成更有趣的形式: + testdb=> \set PROMPT1 '%n@%m %~%R%# ' peter@localhost testdb=> -假设你已经在表中填入数据,并想查看一下: + + 假设你已经向表中填入数据,并想看一看: + peter@localhost testdb=> SELECT * FROM my_table; first | second -------+-------- @@ -2944,7 +2989,10 @@ peter@localhost testdb=> SELECT * FROM my_table; 3 | three 4 | four (4 rows) -要以不同方式显示表格,可以使用\pset命令: + + 你可以使用 + \pset 命令以不同方式显示表格: + peter@localhost testdb=> \pset border 2 Border style is 2. peter@localhost testdb=> SELECT * FROM my_table; @@ -2989,7 +3037,9 @@ one 1 two 2 three 3 four 4 -也可以使用简短命令: + + 或者使用短命令: + peter@localhost testdb=> \a \t \x Output format is aligned. Tuples only is off. @@ -3050,10 +3100,10 @@ testdb=> \crosstabview first second (4 rows) 第二个示例显示一个乘法表,行按数值降序排列,列则独立地按数值升序排列。 testdb=> SELECT t1.first as "A", t2.first+100 AS "B", t1.first*(t2.first+100) as "AxB", -testdb(> row_number() over(order by t2.first) AS ord -testdb(> FROM my_table t1 CROSS JOIN my_table t2 ORDER BY 1 DESC -testdb(> \crosstabview "A" "B" "AxB" ord - A | 101 | 102 | 103 | 104 +testdb-> row_number() over(order by t2.first) AS ord +testdb-> FROM my_table t1 CROSS JOIN my_table t2 ORDER BY 1 DESC +testdb-> \crosstabview "A" "B" "AxB" ord + A | 101 | 102 | 103 | 104 ---+-----+-----+-----+----- 4 | 404 | 408 | 412 | 416 3 | 303 | 306 | 309 | 312 diff --git a/zh/13/release-13.sgml b/zh/13/release-13.sgml index d75bbfa8..97a07d92 100644 --- a/zh/13/release-13.sgml +++ b/zh/13/release-13.sgml @@ -9664,7 +9664,7 @@ Branch: REL_12_STABLE [3b4580f5c] 2023-06-24 17:18:08 -0400 Branch: REL_11_STABLE [c7f33a197] 2023-06-24 17:18:08 -0400 --> - 防止非常复杂的文本搜索模式导致栈溢出崩溃 + 防止非常复杂的文本检索模式导致栈溢出崩溃 (Tom Lane) § @@ -11801,7 +11801,7 @@ Branch: REL_12_STABLE [1aed4c4fd] 2022-11-21 17:07:07 -0500 Branch: REL_11_STABLE [c0eed8891] 2022-11-21 17:07:07 -0500 --> - 确保在执行短语匹配时可以取消全文搜索查询的执行(Tom Lane) + 确保在执行短语匹配时可以取消全文检索查询的执行(Tom Lane) § @@ -23628,7 +23628,7 @@ Author: Peter Eisentraut 2019-07-04 [7b925e127] Sync our Snowball stemmer dictionaries with current upst --> - 更新全文搜索使用的 Snowball 词干提取器词典(Panagiotis Mavrogiorgos) § + 更新全文检索使用的 Snowball 词干分析器词典(Panagiotis Mavrogiorgos) § 这增加了希腊语词干提取,并改进了丹麦语和法语的词干提取。 diff --git a/zh/13/rowtypes.sgml b/zh/13/rowtypes.sgml index 69a9df49..da3df234 100644 --- a/zh/13/rowtypes.sgml +++ b/zh/13/rowtypes.sgml @@ -58,17 +58,21 @@ SELECT price_extension(item, 10) FROM on_hand; - 每当创建一张表时,也会自动创建一个与该表同名的复合类型,用来表示表的行类型。例如,假如我们执行了: + + 每当你创建一个表时,系统也会自动创建一个与该表同名的复合类型,用来表示该表的行类型。例如,如果我们这样写: + CREATE TABLE inventory_item ( name text, supplier_id integer REFERENCES suppliers, price numeric CHECK (price > 0) ); -那么,与上文相同的inventory_item复合类型就会随之产生,而且可以像上文那样使用。不过,请注意当前实现的一个重要限制:由于复合类型本身不关联任何约束,表定义中的约束并不适用于表外的复合类型值。(要解决这一问题,可以在复合类型上创建一个域,并将所需约束定义为该域的 CHECK 约束。) + + 那么上面展示的同一个inventory_item复合类型也会顺带生成,并且同样可以像前面那样使用。不过,当前实现有一个重要限制:由于复合类型本身不关联任何约束,表定义中给出的那些约束在表之外的复合类型值上并不适用。(解决办法是:在该复合类型之上创建一个域,并把所需的约束作为该域的CHECK约束。) + - 构造组合值 + 构造复合值 复合类型 @@ -76,7 +80,7 @@ CREATE TABLE inventory_item ( - 要把组合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,组合常量的一般格式如下: + 要把复合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,复合常量的一般格式如下: '( val1 , val2 , ... )' @@ -96,16 +100,21 @@ CREATE TABLE inventory_item ( - (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。必要时可能需要显式指定类型。) + (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。可能需要显式指定类型,以指明应将该常量转换为哪种类型。) - 这种ROW表达式语法也可以用于构造复合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: + + ROW表达式语法也可以用于构造复合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: + ROW('fuzzy dice', 42, 1.99) ROW('', 42, NULL) -只要表达式中有多个字段,ROW 关键字实际上是可选的,因此这些可以简写为: + + 只要表达式中有多个字段,ROW 关键字实际上是可选的,因此这些可以简写为: + ('fuzzy dice', 42, 1.99) ('', 42, NULL) -这种ROW表达式语法的更多细节见。 + + 关于ROW表达式语法的更多细节,见 @@ -114,7 +123,7 @@ ROW('', 42, NULL) 访问复合类型 - 要访问组合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: + 要访问复合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: SELECT item.name FROM on_hand WHERE item.price > 9.99; @@ -136,7 +145,7 @@ SELECT (on_hand.item).name FROM on_hand WHERE (on_hand.item).price > 9.99; - 无论何时从组合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回组合值的函数结果中只选取一个字段,你需要这样写: + 无论何时从复合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回复合值的函数结果中只选取一个字段,你需要这样写: SELECT (my_func(...)).field FROM ... @@ -151,10 +160,10 @@ SELECT (my_func(...)).field FROM ... - 修改组合值 + 修改复合类型 - 下面是一些插入和更新组合列时正确语法的示例。先看插入或更新整个列值的情况: + 下面是一些插入和更新复合列时正确语法的示例。先看插入或更新整个列值的情况: INSERT INTO mytab (complex_col) VALUES((1.1,2.2)); @@ -166,7 +175,7 @@ UPDATE mytab SET complex_col = ROW(1.1,2.2) WHERE ...; - 我们也可以更新组合列中的单个子字段: + 我们也可以更新复合列中的单个子字段: UPDATE mytab SET complex_col.r = (complex_col).r + 1 WHERE ...; @@ -194,11 +203,11 @@ INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2); - 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的组合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: + 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的复合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: SELECT c FROM inventory_item c; - 这个查询会产生一个单独的组合值列,因此我们可能得到如下输出: + 这个查询会产生一个单独的复合值列,因此我们可能得到如下输出: c ------------------------ @@ -209,7 +218,7 @@ SELECT c FROM inventory_item c; - 普通的限定列名语法table_name.column_name可以理解为对该表当前行的组合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) + 普通的限定列名语法table_name.column_name可以理解为对该表当前行的复合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) @@ -237,16 +246,23 @@ SELECT (myfunc(x)).a, (myfunc(x)).b, (myfunc(x)).c FROM some_table; - PostgreSQL处理列展开时,实际上会把第一种形式转换成第二种形式。因此,在这个示例中,myfunc()每行都会被调用三次,无论采用哪种语法。如果它是一个开销较大的函数,你可能希望避免这种情况,可以使用如下查询: + PostgreSQL处理列展开时,实际上会把第一种形式转换成第二种形式。因此,在这个示例中,无论使用哪种语法,myfunc()每行都会被调用三次。如果它是一个开销较大的函数,你可能希望避免这种情况,可以使用如下查询: + SELECT m.* FROM some_table, LATERAL myfunc(x) AS m; -将函数放在一个 LATERAL FROM 项中,可以避免它在每行上被调用多次。m.* 仍会展开成 m.a, m.b, m.c,但现在这些变量只是引用 FROM 项的输出。(LATERAL 关键字在这里是可选的,但我们把它写出来,以明确该函数所取得的 x 来自 some_table。) + + 把该函数放在LATERAL FROM项中,可以避免它在每行上被调用多次。m.*仍会展开为m.a, m.b, m.c,但现在这些变量只是对该FROM项输出的引用。(这里的LATERAL关键字其实是可选的,不过我们把它写出来,是为了明确该函数会从some_table中取得x。) - 这里的composite_value.*语法在以下结构的顶层出现时会产生这类列展开:(SELECT输出列表)、RETURNING列表(位于INSERT/UPDATE/DELETE)、VALUES子句,或行构造器。在所有其他上下文中(包括嵌套在上述结构之内时),将.*附加到复合值上不会改变该值,因为它表示所有列,因此结果仍然是同一个复合值。例如,如果somefunc()接受一个复合值参数,这些查询就是等价的: + + 当composite_value.*出现在SELECT输出列表、INSERT/UPDATE/DELETE中的RETURNING列表、VALUES子句或行构造器的顶层时,就会产生这种列展开行为。在所有其他上下文中(包括嵌套在上述结构之内时),给复合值附加.*不会改变其值,因为它表示所有列,因此结果仍然是同一个复合值。例如,如果somefunc()接受一个复合值参数,这些查询就是等价的: + + SELECT somefunc(c.*) FROM inventory_item c; SELECT somefunc(c) FROM inventory_item c; -在这两种情况下,inventory_item的当前行都会作为单个复合值参数传递给该函数。即使.*在这种情况下不起作用,使用它仍是良好的风格,因为它明确表示这里需要的是复合值。特别是,解析器会将c(位于c.*)解释为表名或别名,而不是列名,因此不存在歧义;但如果没有.*,就不能明确判断c表示表名还是列名,而且会优先采用列名解释,只要存在一列名为c。 + + + 在这两种情况下,inventory_item的当前行都会作为单个复合值参数传递给该函数。尽管.*在这种场合并不起作用,使用它仍是一种良好风格,因为它能明确表明这里想要的是复合值。特别是,解析器会把c.*中的c视为表名或别名,而不是列名,因此不会产生歧义;而没有.*时,就不清楚c究竟表示表名还是列名,而且如果存在名为c的列,实际上会优先按列名解释。 @@ -256,7 +272,7 @@ SELECT * FROM inventory_item c ORDER BY c; SELECT * FROM inventory_item c ORDER BY c.*; SELECT * FROM inventory_item c ORDER BY ROW(c.*); - 所有这些ORDER BY子句都指定了该行的组合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: + 所有这些ORDER BY子句都指定了该行的复合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: SELECT * FROM inventory_item c ORDER BY ROW(c.name, c.supplier_id, c.price); SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); @@ -265,7 +281,7 @@ SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); - 另一种与组合值有关的特殊语法行为是,我们可以使用函数记法来提取组合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: + 另一种与复合值有关的特殊语法行为是,我们可以使用函数记法来提取复合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: SELECT c.name FROM inventory_item c WHERE c.price > 1000; @@ -284,11 +300,11 @@ SELECT c.somefunc FROM inventory_item c; 函数记法与字段记法之间的这种等价性,使得我们可以通过在复合类型上使用函数来实现计算字段 - computed field + 计算字段 - field - computed + 字段 + 计算 使用上面最后一种查询形式的应用程序,无需直接知道somefunc并不是该表中的真实列。 @@ -306,7 +322,7 @@ SELECT c.somefunc FROM inventory_item c; 复合类型的输入和输出语法 - 组合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明组合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 + 复合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明复合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 '( 42)' @@ -314,7 +330,7 @@ SELECT c.somefunc FROM inventory_item c; - 如前所示,在写组合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让组合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的组合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作组合语法的数据字符。 + 如前所示,在写复合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让复合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的复合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作复合语法的数据字符。 @@ -328,18 +344,18 @@ SELECT c.somefunc FROM inventory_item c; - 记住,你在 SQL 命令中写的内容会先被解释为字符串字面量,然后才会被解释为组合值。这会使所需的反斜杠数量翻倍(假定使用的是转义字符串语法)。例如,要在组合值中插入一个包含双引号和反斜杠的text字段,需要写成: + 记住,你在 SQL 命令中写的内容会先被解释为字符串字面量,然后才会被解释为复合值。这会使所需的反斜杠数量翻倍(假定使用的是转义字符串语法)。例如,要在复合值中插入一个包含双引号和反斜杠的text字段,需要写成: INSERT ... VALUES ('("\"\\")'); - 字符串字面量处理器会去掉一层反斜杠,因此传到组合值解析器时看起来是("\"\\")。随后,送入text数据类型输入例程的字符串就变成了"\。(如果我们使用的数据类型的输入例程也会把反斜杠当作特殊字符处理,例如bytea,那么为了在存储的组合字段中得到一个反斜杠,命令里可能需要多达八个反斜杠。)美元引用(见)可用于避免反斜杠加倍的需要。 + 字符串字面量处理器会去掉一层反斜杠,因此传到复合值解析器时看起来是("\"\\")。随后,送入text数据类型输入例程的字符串就变成了"\。(如果我们使用的数据类型的输入例程也会把反斜杠当作特殊字符处理,例如bytea,那么为了在存储的复合字段中得到一个反斜杠,命令里可能需要多达八个反斜杠。)美元引用(见)可用于避免反斜杠加倍的需要。 - 在 SQL 命令中编写组合值时,ROW构造器语法通常比组合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是组合成员时完全相同。 + 在 SQL 命令中编写复合值时,ROW构造器语法通常比复合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是复合成员时完全相同。 diff --git a/zh/13/textsearch.sgml b/zh/13/textsearch.sgml index 5766af8c..87115c3a 100644 --- a/zh/13/textsearch.sgml +++ b/zh/13/textsearch.sgml @@ -1,21 +1,21 @@ - 全文搜索 + 全文检索 - 全文搜索 + 全文检索 - 文本搜索 + 文本检索 介绍 - 全文检索(或简称文本搜索)提供了识别满足 + 全文检索(或简称文本检索)提供了识别满足 查询条件的自然语言文档的能力, 并且可按它们与查询的相关度进行排序。最常见的搜索类型,是找出所有包含给定 查询词的文档,并按它们与查询的相似性 @@ -25,7 +25,7 @@ - 文本搜索操作符在数据库中已经存在很多年了。 + 文本检索操作符在数据库中已经存在很多年了。 PostgreSQL为文本数据类型提供了 ~~*LIKEILIKE 操作符,但它们缺少现代信息系统所要求的许多关键特性: @@ -138,7 +138,7 @@ ()。围绕这两种数据类型还有许多函数和 操作符(),其中最重要的是匹配操作符 @@,我们将在中介绍。 - 全文搜索还可以借助索引加速()。 + 全文检索还可以借助索引加速()。 @@ -147,11 +147,11 @@ 文档 - 全文搜索 + 文本检索 - 文档是全文搜索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本搜索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 + 文档是全文检索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本检索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 @@ -179,7 +179,7 @@ WHERE m.mid = d.did AND m.mid = 12; - 为了进行文本搜索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 + 为了进行文本检索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 @@ -187,7 +187,7 @@ WHERE m.mid = d.did AND m.mid = 12; 基本文本匹配 - 在PostgreSQL中,全文搜索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: + 在PostgreSQL中,全文检索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: SELECT 'a fat cat sat on a mat and ate a fat rat'::tsvector @@ 'cat & rat'::tsquery; @@ -203,7 +203,7 @@ SELECT 'fat & cow'::tsquery @@ 'a fat cat sat on a mat and ate a fat rat'::t - 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索术语,这些术语必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个术语组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本搜索匹配更像是这样: + 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索词,这些搜索词必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个搜索词组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本检索匹配更像是这样: SELECT to_tsvector('fat cats ate fat rats') @@ to_tsquery('fat & rat'); @@ -221,7 +221,7 @@ SELECT 'fat cats ate fat rats'::tsvector @@ to_tsquery('fat & rat'); f - 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,默认假定已经正规化,因此 rats 不会匹配 rat。 + 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,被假定为已经正规化,因此 rats 不会匹配 rat @@ -290,49 +290,49 @@ SELECT phraseto_tsquery('the cats ate the rats'); 配置 - 前述的都是简单的文本搜索示例。正如前面所提到的,全文搜索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如基于空白之外的解析。这个功能由文本搜索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 + 前述的都是简单的文本检索示例。正如前面所提到的,全文检索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如不局限于按空白划分的解析。这个功能由文本检索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 - 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本搜索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config。 + 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本检索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config - 依赖一个配置的每一个文本搜索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当这个参数被忽略时,default_text_search_config才被使用。 + 依赖一个配置的每一个文本检索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当省略这个参数时,default_text_search_config才被使用。 - 为了让建立自定义文本搜索配置更容易,一个配置可以从更简单的数据库对象来建立。PostgreSQL的文本搜索功能提供了四类配置相关的数据库对象: + 为了便于构建自定义文本检索配置,配置由更简单的数据库对象组合而成。PostgreSQL 的文本检索功能提供了四类与配置相关的数据库对象: - 文本搜索解析器将文档拆分成词元并分类每个词元(例如,作为词或者数字)。 + 文本检索解析器将文档拆分成词元并对每个词元分类(例如,作为词或者数字)。 - 文本搜索词典将词元转变成正规化的形式并拒绝停用词。 + 文本检索词典将词元转变成正规化的形式并拒绝停用词。 - 文本搜索模板提供位于词典底层的函数(一个词典简单地指定一个模板和一组用于模板的参数)。 + 文本检索模板提供位于词典底层的函数(词典只需指定一个模板及其一组参数)。 - 文本搜索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 + 文本检索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 - 文本搜索解析器和模板是从低层 C 函数构建而来,因此它要求 C 编程能力来开发新的解析器和模板,并且还需要超级用户权限来把它们安装到一个数据库中(在PostgreSQL发布的contrib/区域中有一些附加的解析器和模板的示例)。由于词典和配置只是对底层解析器和模板的参数化和连接,不需要特殊的权限来创建一个新词典或配置。创建定制词典和配置的示例将在本章稍后的部分给出。 + 文本检索解析器和模板由底层 C 函数构成,因此开发新的解析器和模板需要 C 编程能力,将它们安装到数据库中则需要超级用户权限。(PostgreSQL 发行版的 contrib/ 目录中有附加解析器和模板的示例。)词典和配置只是为底层解析器和模板设置参数并将它们连接起来,因此创建新词典或配置不需要特殊权限。本章后面会给出创建自定义词典和配置的示例。 @@ -343,14 +343,14 @@ SELECT phraseto_tsquery('the cats ate the rats'); 表和索引 - 在前一节中的示例演示了使用简单常数字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 + 在前一节中的示例演示了使用简单常量字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 搜索表 - 即使没有索引,也可以执行全文搜索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend: + 即使没有索引,也可以执行全文检索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend SELECT title @@ -374,7 +374,7 @@ WHERE to_tsvector(body) @@ to_tsquery('friend'); - 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 中同时包含 createtable: + 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 合在一起包含 createtable SELECT title @@ -388,7 +388,7 @@ LIMIT 10; - 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本搜索在实际使用中通常都需要建立索引。 + 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本检索在实际使用中通常都需要建立索引。 @@ -396,9 +396,15 @@ LIMIT 10; 创建索引 - 我们可以创建一个GIN索引()来加速文本搜索: + + 我们可以创建一个GIN索引()来加速文本检索: + + CREATE INDEX pgweb_idx ON pgweb USING GIN (to_tsvector('english', body)); -注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本搜索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含tsvector,它们使用不同的文本搜索配置创建,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 + + + 注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本检索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含使用不同文本检索配置创建的tsvector,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 + 由于上面的索引使用了 to_tsvector 的双参数版本,因此只有同样使用相同配置名的双参数版 to_tsvector 查询,才能使用该索引。也就是说,WHERE to_tsvector('english', body) @@ 'a & b' 可以使用该索引,而 WHERE to_tsvector(body) @@ 'a & b' 则不能。这样可以保证索引只会和创建索引项时所用的同一配置配合使用。 @@ -414,15 +420,24 @@ CREATE INDEX pgweb_idx ON pgweb USING GIN (to_tsvector('english', title || ' ' | - 另一种方法是创建一个单独的tsvector列来保存to_tsvector的输出。若要让该列与其源数据自动保持同步,可以使用存储生成列。下面的示例把titlebody串接起来,并用coalesce保证一个字段仍然可以被建立索引,即使另一个字段为NULL: + + 另一种方法是创建一个单独的tsvector列来保存to_tsvector的输出。若要让该列与其源数据自动保持同步,可以使用存储生成列。下面的示例把titlebody串接起来,并用coalesce保证其中一个字段为NULL时,另一个字段仍然可以被建立索引: ALTER TABLE pgweb ADD COLUMN textsearchable_index_col tsvector GENERATED ALWAYS AS (to_tsvector('english', coalesce(title, '') || ' ' || coalesce(body, ''))) STORED; -然后我们创建一个GIN索引来加速搜索: + + + 然后我们创建一个GIN索引来加速搜索: + + CREATE INDEX textsearch_idx ON pgweb USING GIN (textsearchable_index_col); -现在可以执行快速全文检索了: + + + 现在我们准备好执行一个快速的全文检索了: + + SELECT title FROM pgweb WHERE textsearchable_index_col @@ to_tsquery('create & table') @@ -432,7 +447,7 @@ LIMIT 10; - 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本搜索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 + 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本检索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 @@ -440,10 +455,10 @@ LIMIT 10; - 控制文本搜索 + 控制文本检索 - 要实现全文搜索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 + 要实现全文检索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 @@ -462,7 +477,7 @@ to_tsvector( config - to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本搜索配置进行处理。下面是一个简单示例: + to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本检索配置进行处理。下面是一个简单示例: SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); @@ -477,7 +492,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每类词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本搜索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english。 + to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每个词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本检索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english @@ -485,7 +500,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为空,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: + 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为 NULL,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: UPDATE tt SET ti = @@ -516,22 +531,35 @@ to_tsquery( config - to_tsquery创建一个tsquery值,其来源为querytext,其中必须是由以下 tsquery 操作符分隔的单个词元:&(AND)、|(OR)、!(NOT)以及 <->(FOLLOWED BY),也可以使用括号分组。换句话说,to_tsquery 的输入必须已经遵循 tsquery 输入的一般规则,如 所述。区别在于,基本的 tsquery 输入会直接使用词元,而 to_tsquery 会使用指定或默认的配置将每个词元正规化为词位,并丢弃根据该配置判定为停用词的词元。例如: + to_tsquery 根据 querytext 创建一个 tsquery 值。输入必须由单个词元组成,这些词元之间使用 tsquery 操作符 &(AND)、|(OR)、!(NOT)和 <->(FOLLOWED BY)分隔,并可使用圆括号分组。换句话说,传给 to_tsquery 的输入,必须已经遵循 中描述的 tsquery 一般输入规则。不同之处在于,基础 tsquery 输入是按字面接受词元,而 to_tsquery 会使用指定或默认配置,把每个词元正规化为词位,并丢弃那些按该配置被判定为停用词的词元。例如: + + SELECT to_tsquery('english', 'The & Fat & Rats'); to_tsquery --------------- 'fat' & 'rat' -与基本的 tsquery 输入一样,可以给每个词位附加权重,以限制它只匹配 tsvector 中具有这些权重的词位。例如: + + + 与基础tsquery输入一样,可以为每个词位附加权重,以限制它只匹配具有这些权重的tsvector词位。例如: + + SELECT to_tsquery('english', 'Fat | Rats:AB'); to_tsquery ------------------ 'fat' | 'rat':AB -此外,可以把 * 附加到词位上来指定前缀匹配: + + + 此外,还可以在词位后附加*来指定前缀匹配: + + SELECT to_tsquery('supern:*A & star:A*B'); to_tsquery -------------------------- 'supern':*A & 'star':*AB -这样的词位将匹配 tsvector 中以给定字符串开头的任何单词。 + + + 这样的词位将匹配tsvector中任何以给定字符串开头的单词。 + to_tsquery也可以接受单引号括起来的短语。当配置中包含可能在这类短语上触发的分类词典时,这一点尤其有用。在下面的例子中,一个分类词典包含规则 supernovae @@ -559,17 +587,27 @@ plainto_tsquery( config < plainto_tsquery把未格式化的文本querytext转换成一个tsquery值。该文本会像to_tsvector那样被解析并正规化,然后在保留下来的词之间插入&(AND)tsquery操作符。 - 示例: + + 示例: + + SELECT plainto_tsquery('english', 'The Fat Rats'); plainto_tsquery ----------------- 'fat' & 'rat' -注意,plainto_tsquery不会识别其输入中的tsquery操作符、权重标签或前缀匹配标签: + + + 注意,plainto_tsquery不会识别输入中的tsquery操作符、权重标签或前缀匹配标签: + + SELECT plainto_tsquery('english', 'The Fat & Rats:C'); plainto_tsquery --------------------- 'fat' & 'rat' & 'c' -这里,输入中的所有标点都被丢弃了。 + + + 在这里,输入中的所有标点都被丢弃了。 + phraseto_tsquery @@ -583,12 +621,19 @@ phraseto_tsquery( config phraseto_tsquery的行为很像plainto_tsquery,不过它会在保留下来的词之间插入<->(FOLLOWED BY)操作符,而不是&(AND)操作符。此外,停用词也不是简单地丢弃,而是通过插入<N>操作符(而不是<->操作符)来体现。在搜索精确词位序列时,这个函数很有用,因为 FOLLOWED BY 操作符不仅检查所有词位是否存在,还检查词位的顺序。 - 示例: + + 示例: + + SELECT phraseto_tsquery('english', 'The Fat Rats'); phraseto_tsquery ------------------ 'fat' <-> 'rat' -plainto_tsquery一样,phraseto_tsquery函数也不会识别其输入中的tsquery操作符、权重标签或前缀匹配标签: + + + 与plainto_tsquery一样,phraseto_tsquery函数也不会识别输入中的tsquery操作符、权重标签或前缀匹配标签: + + SELECT phraseto_tsquery('english', 'The Fat & Rats:C'); phraseto_tsquery ----------------------------- @@ -604,12 +649,12 @@ websearch_to_tsquery( configwebsearch_to_tsquery创建一个tsquery值,其来源为querytext,采用一种替代语法,其中简单的无格式文本就是一个有效查询。不同于plainto_tsqueryphraseto_tsquery,它还识别某些操作符。此外,这个函数绝不会引发语法错误,因此可以直接使用用户提供的原始输入进行搜索。支持以下语法: - 无引号文本:不在引号中的文本会被转换为由&操作符分隔的词,就像经过plainto_tsquery处理一样。 + 未加引号的文本:不在引号中的文本会被转换为由&操作符分隔的词,就像经过plainto_tsquery处理一样。 - "引号文本":引号中的文本会被转换为由<->操作符分隔的词,就像经过phraseto_tsquery处理一样。 + "加引号的文本":引号中的文本会被转换为由<->操作符分隔的词,就像经过phraseto_tsquery处理一样。 @@ -664,7 +709,7 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); 搜索结果排名 - 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及它们出现于文档中哪个部分。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 + 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及这些词所处文档部分的重要程度。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 目前可用的两种排名函数是: @@ -711,11 +756,21 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 对这两个函数来说,可选的weights参数允许根据词实例的标注情况赋予它们不同权重。权重数组按如下顺序指定各类词的权重: -{D-weight, C-weight, B-weight, A-weight} -如果没有提供weights,则使用如下默认值: + + 对这两个函数来说,可选的 weights 参数允许根据词实例的标注情况赋予它们不同权重。权重数组按如下顺序指定各类词的权重: + + +{D-权重, C-权重, B-权重, A-权重} + + + 如果没有提供 weights,则使用如下默认值: + + {0.1, 0.2, 0.4, 1.0} -通常,权重用于标注文档中特殊部分的词,例如标题或开头的摘要,从而使它们相对于正文中的词具有更高或更低的重要性。 + + + 通常,权重用于标记来自文档特定区域的词,例如标题或开头摘要中的词,从而使它们相较于正文中的词被赋予更高或更低的重要性。 + 由于较长的文档更有机会包含查询词,因此把文档大小纳入考量是合理的。例如,一个一百词的文档里某个搜索词出现五次,通常会比一个一千词的文档里同一搜索词也只出现五次更相关。两种排名函数都接受一个整数 normalization 选项,用于指定文档长度是否影响排名,以及具体如何影响。该整数选项控制多种行为,因此它是一个位掩码:你可以使用 | 指定一种或多种行为(例如 2|4)。 @@ -743,12 +798,12 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 8 用文档中唯一词的数量除排名 + 8 用文档中不同词的数量除排名 - 16 用 1 + 文档中唯一词数量的对数除排名 + 16 用 1 + 文档中不同词数量的对数除排名 @@ -762,7 +817,7 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。正规化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 + 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。归一化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 @@ -834,9 +889,7 @@ ts_headline( config ts_headline 接收文档和查询,并返回文档中一段 - 高亮查询词条的摘录。具体而言,该函数会先用查询选择相关文本片段,然后 - 高亮查询中出现的所有词,即使这些词的位置并不满足查询本身的位置限制。 - 用于解析文档的配置可通过 config 指定; + 高亮查询词的摘录。用于解析文档的配置可通过 config 指定; 若省略 config,则使用 default_text_search_config 配置。 @@ -879,7 +932,7 @@ ts_headline( config - 警告:跨站脚本(XSS)安全 + 警告:跨站脚本(XSS)安全性 ts_headline 的输出不保证可安全直接嵌入网页。 当 HighlightAllfalse(默认值)时, @@ -935,7 +988,7 @@ occurrences to display in the result.', 附加特性 - 本节介绍一些在文本搜索中很有用的附加函数和操作符。 + 本节介绍一些在文本检索中很有用的附加函数和操作符。 @@ -1048,7 +1101,7 @@ occurrences to display in the result.', - 返回用 AND 结合的两个给定查询。 + 返回两个给定查询的 AND 组合。 @@ -1062,7 +1115,7 @@ occurrences to display in the result.', - 返回用 OR 结合的两个给定查询。 + 返回两个给定查询的 OR 组合。 @@ -1115,7 +1168,7 @@ SELECT to_tsquery('fat') <-> to_tsquery('cat | rat'); - 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: + 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在其后距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: SELECT tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10); @@ -1206,8 +1259,10 @@ SELECT querytree(to_tsquery('!defined')); - 这种形式的ts_rewrite 只应用一条重写规则:target 会被替换成 substitute,替换范围是整个 query。例如: + + 这种形式的 ts_rewrite 只应用一条重写规则:无论 targetquery 中的何处出现,都用 substitute 替换它。例如: + + SELECT ts_rewrite('a & b'::tsquery, 'a'::tsquery, 'c'::tsquery); ts_rewrite ------------ @@ -1224,7 +1279,10 @@ SELECT ts_rewrite('a & b'::tsquery, 'a'::tsquery, 'c'::tsquery); - 这种形式的ts_rewrite接受一个起始query和一个 SQLselect命令,该命令以文本字符串给出。该select必须产生两列tsquery类型的值。对于select结果中的每一行,第一列值(目标)的各次出现都会被第二列值(替换)取代,替换范围为当前query值。例如: + + 这种形式的 ts_rewrite 接受一个起始 query 和一个以文本字符串给出的 SQL select 命令。该 select 必须产生两列 tsquery 类型的值。对于 select 结果中的每一行,第一列值(目标)在当前 query 值中的所有出现都会被第二列值(替换)取代。例如: + + CREATE TABLE aliases (t tsquery PRIMARY KEY, s tsquery); INSERT INTO aliases VALUES('a', 'c'); @@ -1309,7 +1367,10 @@ tsvector_update_trigger(tsvector_column_nametsvector_column_name,&zwsp; config_column_name, text_column_name , ... ) - 这些触发器函数会自动计算一个tsvector列,其值来自一个或多个文本列,并受以下命令中所指定参数的控制:CREATE TRIGGER。下面是一个用法示例: + + 这些触发器函数会在 CREATE TRIGGER 命令中给定参数的控制下,从一个或多个文本列自动计算出一个 tsvector 列。下面是它们的一个使用示例: + + CREATE TABLE messages ( title text, body text, @@ -1331,13 +1392,19 @@ SELECT title, body FROM messages WHERE tsv @@ to_tsquery('title & body'); title | body ------------+----------------------- title here | the body text is here -创建这个触发器后,titlebody中的任何更改都会自动反映到tsv中,应用无需为此操心。 + + + 创建该触发器之后,对titlebody的任何修改都会自动反映到tsv中,而应用程序无需关心这一点。 + - 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本搜索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 + 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本检索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 - 这些内置触发器有一个限制,即它们会一视同仁地处理所有输入列。要对不同列采用不同处理方式 — 例如,给标题赋予与正文不同的权重 — 就需要编写自定义触发器。下面是一个使用PL/pgSQL作为触发器语言的示例: + + 这些内置触发器的一个限制是,它们会以相同方式处理所有输入列。若要对列做不同处理 — 例如让标题和正文具有不同权重 — 就需要编写自定义触发器。下面是一个使用 PL/pgSQL 作为触发器语言的示例: + + CREATE FUNCTION messages_trigger() RETURNS trigger AS $$ begin new.tsv := @@ -1398,7 +1465,7 @@ ts_stat(sqlquery text, - 如果提供了 weights,则只统计具有这些权重之一的出现。 + 如果提供了 weights,则只统计具有这些权重之一的词的出现次数。 @@ -1427,7 +1494,7 @@ LIMIT 10; 解析器 - 文本搜索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 + 文本检索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 @@ -1450,12 +1517,12 @@ LIMIT 10; asciiword - 单词,所有 ASCII 字母 + 单词,全部由 ASCII 字母组成 elephant word - 单词,所有字母 + 单词,全部由字母组成 mañana @@ -1465,12 +1532,12 @@ LIMIT 10; asciihword - 带连字符的单词,所有 ASCII + 带连字符的单词,全部为 ASCII 字符 up-to-date hword - 带连字符的单词,所有字母 + 带连字符的单词,由字母组成 lógico-matemática @@ -1480,12 +1547,12 @@ LIMIT 10; hword_asciipart - 带连字符的单词部分,所有 ASCII + 带连字符的单词部分,全部为 ASCII 字符 postgresql-beta1 上下文中的 postgresql hword_part - 带连字符的单词部分,所有字母 + 带连字符的单词部分,全部由字母组成 lógico-matemática 上下文中的 lógicomatemática @@ -1560,8 +1627,8 @@ LIMIT 10; blank - 空格符号 - (其他不识别的任意空白或标点符号) + 空白符号 + (未被识别为其他类型的空白或标点符号) @@ -1569,12 +1636,12 @@ LIMIT 10; - 解析器的一个字母的概念由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时可以用来区别它们。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 + 解析器对字母的界定由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时区分它们会很有用。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 email不支持所有由RFC 5322定义的有效电子邮件字符。 - 具体来说,电子邮件用户名仅支持句号、短横线和下划线这些非字母数字字符。 + 具体来说,电子邮件用户名仅支持句点、短横线和下划线这些非字母数字字符。 @@ -1623,7 +1690,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h 词典 - 词典用于消除不应参与搜索的词(stop words),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 + 词典用于消除不应参与搜索的词(停用词),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 一些正规化的示例: @@ -1635,7 +1702,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - URL地址可以被正规化,以便让等价的 URL 匹配: + URL 地址可以规范化,以便让等价的 URL 匹配: @@ -1680,32 +1747,32 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤字典) + 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤词典 - 如果字典知道该词元但它是一个停用词,则返回一个空数组 + 如果词典知道该词元但它是一个停用词,则返回一个空数组 - 如果字典不识别该输入词元,则返回NULL + 如果词典不识别该输入词元,则返回NULL - PostgreSQL为许多语言提供了预定义的字典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发布的contrib/区域。 + PostgreSQL为许多语言提供了预定义的词典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发行版的contrib/目录。 - 文本搜索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 + 文本检索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 - 配置词典列表的一般规则是,把最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语分类词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: + 配置词典列表的一般规则是,把适用范围最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语同义词词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: ALTER TEXT SEARCH CONFIGURATION astro_en @@ -1714,14 +1781,14 @@ ALTER TEXT SEARCH CONFIGURATION astro_en - 过滤词典可以放在列表中的任何位置,只是不能放在最后,因为放在最后就没有意义了。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 + 过滤词典可以放在列表中的任何位置,但放在末尾没有用处。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 停用词 - 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文搜索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: + 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文检索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: SELECT to_tsvector('english', 'in the list of stop words'); @@ -1853,7 +1920,7 @@ SELECT * FROM ts_debug('english', 'Paris'); - synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基本名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 + synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 @@ -1915,28 +1982,28 @@ mydb=# SELECT 'indexes are very useful'::tsvector @@ to_tsquery('tst', 'indices' - 基本上一个分类词典会用一个首选词替换所有非首选词,并且也可选择地保留原始术语用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典要求一个下列格式的配置文件: + 分类词典基本上会用一个首选词替换所有非首选词,并且也可以选择保留原始词用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典需要一个采用以下格式的配置文件: -# this is a comment -sample word(s) : indexed word(s) -more sample word(s) : more indexed word(s) +# 这是一条注释 +示例词(一个或多个) : 索引词(一个或多个) +更多示例词(一个或多个) : 更多索引词(一个或多个) ... - 其中冒号(:)符号扮演了一个短语及其替换之间的定界符。 + 其中冒号(:)符号用作短语及其替换词之间的分隔符。 - 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过对子词典的应用,但所有样例词都必须能被子词典识别。 + 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过将子词典应用于该词,但所有样例词都必须能被子词典识别。 - 如果有多个短语匹配输入,则分类词典选择最长的那一个,并且使用最后的定义打破连结。 + 如果有多个短语匹配输入,分类词典会选择最长的匹配;长度相同时使用最后的定义。 - 由子词典识别的特定停用词不能够被指定;改用?标记任何可以出现停用词的地方。例如,假定根据子词典athe是停用词: + 由子词典识别的特定停用词不能够被指定;改用?标记可出现任意停用词的位置。例如,假定根据子词典athe是停用词: ? one ? two : swsw @@ -1978,7 +2045,7 @@ CREATE TEXT SEARCH DICTIONARY thesaurus_simple ( - mythesaurus是分类词典配置文件的基础名称(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 + mythesaurus是分类词典配置文件的基名(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 @@ -2003,7 +2070,7 @@ ALTER TEXT SEARCH CONFIGURATION russian 分类词典示例 - 考虑简单的天文词库 thesaurus_astro,其中包含一些天文单词组合: + 考虑一个简单的天文分类词典 thesaurus_astro,其中包含一些天文单词组合: supernovae stars : sn @@ -2071,7 +2138,7 @@ SELECT plainto_tsquery('supernova star'); <application>Ispell</application> 词典 - Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以把搜索词 bank 的词尾变化和词形变化对应起来,例如 bankingbankedbanksbanks'bank's。 + Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以匹配搜索词 bank 的所有变格和变位形式,例如 bankingbankedbanksbanks'bank's @@ -2083,12 +2150,12 @@ SELECT plainto_tsquery('supernova star'); - 要创建一个Ispell词典,执行这三步: + 要创建一个Ispell词典,请执行以下步骤: - 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。有必要抽取.aff.dic文件,把扩展改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): + 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。需要提取.aff.dic文件,将扩展名改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): iconv -f ISO_8859-1 -t UTF-8 -o nn_no.affix nn_NO.aff iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic @@ -2097,7 +2164,7 @@ iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic - 拷贝文件到$SHAREDIR/tsearch_data目录 + 复制文件到$SHAREDIR/tsearch_data目录 @@ -2115,11 +2182,11 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( - 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基础名称。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 + 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基名。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 - Ispell 词典通常识别一个有限集合的词,这样它们后面应该跟着另一个更广义的词典;例如,一个 Snowball 词典,它可以识别所有东西。 + Ispell 词典通常只能识别有限的词,因此其后应跟着另一个覆盖范围更广的词典;例如,一个 Snowball 词典,它可以识别所有输入。 @@ -2127,13 +2194,13 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( prefixes flag *A: - . > RE # As in enter > reenter + . > RE # 例如 enter > reenter suffixes flag T: - E > ST # As in late > latest - [^AEIOU]Y > -Y,IEST # As in dirty > dirtiest - [AEIOU]Y > EST # As in gray > grayest - [^EY] > EST # As in small > smallest + E > ST # 例如 late > latest + [^AEIOU]Y > -Y,IEST # 例如 dirty > dirtiest + [AEIOU]Y > EST # 例如 gray > grayest + [^EY] > EST # 例如 small > smallest @@ -2149,14 +2216,14 @@ lark/MRS .dict文件的格式是: -basic_form/affix_class_name +基本词形/词缀类名 .affix文件中,每一个词缀标志以下面的格式描述: -condition > [-stripping_letters,] adding_affix +条件 > [-删除的字母,] 添加的词缀 @@ -2165,7 +2232,7 @@ condition > [-stripping_letters,] adding_affix - Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,它标记可以参与到复合格式中的词典词: + Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,用于标记词典中可以参与构成复合词的词: compoundwords controlled z @@ -2195,7 +2262,7 @@ SFX T 0 est [^ey] - 一个词缀类的第一行是头部。头部后面列出了词缀规则的域: + 一个词缀类的第一行是首部。首部后面列出了词缀规则的字段: @@ -2247,7 +2314,7 @@ largehearted <application>Snowball</application> 词典 - Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每一个算法懂得按照其语言中的拼写,如何缩减词的常见变体形式为一个基础或词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择地指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。例如,有一个内置的定义等效于 + Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每种算法都知道如何把其语言中词的常见变体约简为基本拼写形式,也就是词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。例如,有一个内置的定义等效于 CREATE TEXT SEARCH DICTIONARY english_stem ( @@ -2261,7 +2328,7 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( - 一个Snowball词典识别所有的东西,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 + 一个Snowball词典识别所有输入,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 @@ -2272,11 +2339,11 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( 配置示例 - 一个文本搜索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本搜索配置来执行其处理。配置参数指定了默认配置的名称,如果忽略了显式的配置参数,文本搜索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 + 一个文本检索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本检索配置来执行其处理。配置参数指定了默认配置的名称,如果省略了显式的配置参数,文本检索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 - 有一些预定义的文本搜索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本搜索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本搜索对象()的信息。 + 有一些预定义的文本检索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本检索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本检索对象()的信息。 @@ -2368,17 +2435,17 @@ SHOW default_text_search_config; - 测试和调试文本搜索 + 测试和调试文本检索 - 一个自定义文本搜索配置的行为很容易变得混乱。本节中描述的函数对于测试文本搜索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 + 一个自定义文本检索配置的行为很容易让人困惑。本节中描述的函数对于测试文本检索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 配置测试 - 函数ts_debug允许简单地测试一个文本搜索配置。 + 函数ts_debug可方便地测试一个文本检索配置。 @@ -2397,7 +2464,7 @@ ts_debug( config re - ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果该参数被忽略则使用default_text_search_config指定的配置。 + ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果省略该参数则使用default_text_search_config指定的配置。 @@ -2472,7 +2539,7 @@ SELECT * FROM ts_debug('english', 'a fat cat sat on a mat - it ate a fat rats') - 为了一个更广泛的示范,我们先为英语语言创建一个public.english配置和 Ispell 词典: + 为了做更完整的演示,我们先为英语创建一个public.english配置和 Ispell 词典: @@ -2501,7 +2568,7 @@ SELECT * FROM ts_debug('public.english', 'The Brightest supernovaes'); - 在这个示例中,词Brightest被解析器识别为一个ASCII word(别名asciiword)。对于这种词元类型,词典列表是english_ispellenglish_stem。该词被english_ispell识别,并被这个词典归约为名词bright。词supernovaesenglish_ispell词典来说是未知的,因此它会被传递给下一个词典;幸运的是,它随后被识别了。(实际上,english_stem是一个 Snowball 词典,它能够识别所有输入;这也是为什么它被放在词典列表末尾。) + 在这个示例中,词Brightest被解析器识别为一个ASCII 词(别名asciiword)。对于这种词元类型,词典列表是english_ispellenglish_stem。该词被english_ispell识别,并被这个词典归约为词位bright。词supernovaesenglish_ispell词典来说是未知的,因此它会被传递给下一个词典;幸运的是,它随后被识别了。(实际上,english_stem是一个 Snowball 词典,它能够识别所有输入;这也是为什么它被放在词典列表末尾。) @@ -2530,7 +2597,7 @@ FROM ts_debug('public.english', 'The Brightest supernovaes'); 解析器测试 - 下列函数允许直接测试一个文本搜索解析器。 + 下列函数允许直接测试一个文本检索解析器。 @@ -2572,7 +2639,7 @@ ts_token_type(parser_oid oid< - ts_token_type返回一个表,描述指定解析器能够识别的每一种词元。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: + ts_token_type返回一个表,描述指定解析器能够识别的每一种词元类型。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: SELECT * FROM ts_token_type('default'); @@ -2610,7 +2677,7 @@ SELECT * FROM ts_token_type('default'); 词典测试 - ts_lexize函数帮助词典测试。 + ts_lexize函数便于测试词典。 @@ -2668,17 +2735,17 @@ SELECT plainto_tsquery('supernovae stars'); - 文本搜索的首选索引类型 + 文本检索的首选索引类型 - 文本搜索 + 文本检索 索引 - 有两种索引可以用来加速全文搜索:GIN和 + 有两种索引可以用来加速全文检索:GINGiST。 - 请注意,索引对于全文搜索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 + 请注意,索引对于全文检索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 要创建这样的索引,可以采用下面的任一种方式: @@ -2689,7 +2756,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GIN - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIN (column); @@ -2709,7 +2776,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GiST - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIST (column [ { DEFAULT | tsvector_ops } (siglen = number) ] ); @@ -2719,7 +2786,7 @@ SELECT plainto_tsquery('supernovae stars'); 创建基于 GiST(广义搜索树)的索引。 column可以是tsvectortsquery类型。 - 可选的整数参数siglen确定签名长度(有关详细信息,请参见下文)。 + 可选的整数参数siglen确定以字节为单位的签名长度(有关详细信息,请参见下文)。 @@ -2728,7 +2795,7 @@ SELECT plainto_tsquery('supernovae stars'); - GIN 索引是文本搜索的首选索引类型。作为倒排索引,每个词(词位)在 + GIN 索引是文本检索的首选索引类型。作为倒排索引,每个词(词位)在 其中都有一个索引项,其中有压缩过的匹配位置的列表。多词搜索可以找到 第一个匹配,然后使用该索引移除缺少额外词的行。GIN 索引只存储 tsvector值的词(词位),并且不存储它们的权重标签。因此, @@ -2736,19 +2803,19 @@ SELECT plainto_tsquery('supernovae stars'); - 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。以字节为单位的签名长度由可选整数参数 siglen 的值决定。 默认签名长度(未指定 siglen 时)为 124 字节,最大签名长度为 2024 字节。该签名通过哈希每一个词到一个 n 位串中的一个单一位来产生,通过将所有这些位 OR 在一起产生一个 n 位的文档签名。当两个词哈希到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。更长的签名导致更精确的搜索(扫描索引的一小部分和更少的堆页面),但代价是更大的索引。 + 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。以字节为单位的签名长度由可选整数参数 siglen 的值决定。 默认签名长度(未指定 siglen 时)为 124 字节,最大签名长度为 2024 字节。该签名通过将每个词 hash 到一个 n 位串中的一位,再将所有这些位进行 OR 运算来生成,结果是一个 n 位的文档签名。当两个词 hash 到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。更长的签名导致更精确的搜索(扫描更小比例的索引和更少的堆页面),但代价是更大的索引。 - GiST 可以构建为覆盖索引,例如使用 INCLUDE 子句。被包含的列可以具有没有任何 GiST 操作符类的数据类型。被包含的属性会以未压缩形式存储。 + GiST 可以构建为覆盖索引,即使用 INCLUDE 子句。被包含的列可以具有没有任何 GiST 操作符类的数据类型。被包含的属性会以未压缩形式存储。 - 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的可用性。假匹配的可能性取决于几个因素,特别是唯一词的数量,因此推荐使用词典来缩减这个数量。 + 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的实用性。假匹配的可能性取决于几个因素,特别是不同词的数量,因此推荐使用词典来缩减这个数量。 - 注意GIN索引的构件时间常常可以通过增加来改进,而GiST索引的构建时间则与该参数无关。 + 注意GIN索引的构建时间常常可以通过增加来改进,而GiST索引的构建时间则对该参数不敏感。 @@ -2762,7 +2829,7 @@ SELECT plainto_tsquery('supernovae stars'); <application>psql</application> 支持 - 关于文本搜索配置对象的信息可以在psql中使用一组命令获得: + 关于文本检索配置对象的信息可以在psql中使用一组命令获得: \dF{d,p,t}+ PATTERN @@ -2770,7 +2837,7 @@ SELECT plainto_tsquery('supernovae stars'); - 可选参数 PATTERN 可以是文本搜索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: + 可选参数 PATTERN 可以是文本检索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: => \dF *fulltext* @@ -2796,7 +2863,9 @@ SELECT plainto_tsquery('supernovae stars'); \dF+ PATTERN - 列出文本搜索配置(添加 +可获得更详细的信息)。 + + 列出文本检索配置(加上 + 可显示更多细节)。 + => \dF russian List of text search configurations Schema | Name | Description @@ -2835,7 +2904,9 @@ Parser: "pg_catalog.default" \dFd+ PATTERN - 列出文本搜索词典(加上+可获得更详细的信息)。 + + 列出文本检索词典(加上 + 可显示更多细节)。 + => \dFd List of text search dictionaries Schema | Name | Description @@ -2871,7 +2942,9 @@ Parser: "pg_catalog.default" \dFp+ PATTERN - 列出文本搜索解析器(添加 +可获得更详细的信息)。 + + 列出文本检索解析器(加上 + 可显示更多细节)。 + => \dFp List of text search parsers Schema | Name | Description @@ -2922,7 +2995,9 @@ Parser: "pg_catalog.default" \dFt+ PATTERN - 列出文本搜索模板(添加 +可获得更详细的信息)。 + + 列出文本检索模板(加上 + 可显示更多细节)。 + => \dFt List of text search templates Schema | Name | Description @@ -2943,7 +3018,7 @@ Parser: "pg_catalog.default" 限制 - 目前,PostgreSQL的文本搜索功能存在以下限制: + 目前,PostgreSQL的文本检索功能存在以下限制: 每个词位的长度必须小于 2 千字节 @@ -2970,12 +3045,12 @@ Parser: "pg_catalog.default" - 为了对比,PostgreSQL 8.1 的文档包含 10,441 个唯一词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 + 为了对比,PostgreSQL 8.1 的文档包含 10,441 个不同词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 - 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个唯一词。 + 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个不同词。 diff --git a/zh/13/unaccent.sgml b/zh/13/unaccent.sgml index 59509878..53e8fc06 100644 --- a/zh/13/unaccent.sgml +++ b/zh/13/unaccent.sgml @@ -8,11 +8,11 @@ - unaccent是一个文本搜索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤字典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文搜索能够以不区分重音的方式处理文本。 + unaccent是一个文本检索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤词典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文检索能够以不区分重音的方式处理文本。 - unaccent当前的实现还不能作为thesaurus词典的正规化字典使用。 + unaccent当前的实现还不能作为thesaurus词典的正规化词典使用。 @@ -65,7 +65,7 @@ - 与其他PostgreSQL文本搜索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含无法转换的字符的行都会被静默忽略,因此规则文件可以包含不适用于当前编码的规则。 + 与其他PostgreSQL文本检索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含无法转换的字符的行都会被静默忽略,因此规则文件可以包含不适用于当前编码的规则。 @@ -78,7 +78,7 @@ 用法 - 安装unaccent扩展会创建一个文本搜索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 + 安装unaccent扩展会创建一个文本检索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 mydb=# ALTER TEXT SEARCH DICTIONARY unaccent (RULES='my_rules'); @@ -99,7 +99,7 @@ mydb=# select ts_lexize('unaccent','Hôtel'); - 下面的示例展示了如何将unaccent词典插入到文本搜索配置中: + 下面的示例展示了如何将unaccent词典插入到文本检索配置中: mydb=# CREATE TEXT SEARCH CONFIGURATION fr ( COPY = french ); mydb=# ALTER TEXT SEARCH CONFIGURATION fr @@ -130,7 +130,7 @@ mydb=# select ts_headline('fr','Hôtel de la Mer',to_tsquery('fr','Hotels') 函数 - unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本搜索环境之外使用。 + unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本检索环境之外使用。 @@ -142,7 +142,7 @@ unaccent(dictionary - 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本搜索词典。 + 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本检索词典。 diff --git a/zh/14/array.sgml b/zh/14/array.sgml index 10cc5e41..1d2a2443 100644 --- a/zh/14/array.sgml +++ b/zh/14/array.sgml @@ -4,7 +4,7 @@ 数组 - array + 数组 @@ -15,8 +15,8 @@ 数组类型的声明 - array - declaration + 数组 + 声明 @@ -64,8 +64,8 @@ CREATE TABLE tictactoe ( 数组值输入 - array - constant + 数组 + 常量 @@ -86,7 +86,7 @@ CREATE TABLE tictactoe ( (这类数组常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。必要时可能需要显式指定类型。) + linkend="sql-syntax-constants-generic"/>中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。可能需要显式指定类型。) @@ -119,15 +119,14 @@ SELECT * FROM sal_emp; - 多维数组在每个维度上的范围必须匹配。不匹配会导致错误,例如: + 多维数组的各个子数组在每个维度上的长度必须匹配。不匹配会导致错误,例如: INSERT INTO sal_emp VALUES ('Bill', '{10000, 10000, 10000, 10000}', '{{"meeting", "lunch"}, {"meeting"}}'); -ERROR: malformed array literal: "{{"meeting", "lunch"}, {"meeting"}}" -DETAIL: Multidimensional arrays must have sub-arrays with matching dimensions. +ERROR: multidimensional arrays must have array expressions with matching dimensions @@ -152,8 +151,8 @@ INSERT INTO sal_emp 访问数组 - array - accessing + 数组 + 访问 @@ -186,9 +185,9 @@ SELECT pay_by_quarter[3] FROM sal_emp; - 我们还可以访问数组或子数组的任意矩形切片。数组切片通过在一个或多个数组维度上写成 + 我们还可以访问数组的任意矩形切片,即子数组。数组切片通过在一个或多个数组维度上写成 lower-bound:upper-bound - 的形式来表示。例如,下面这个查询取回 Bill 在一周前两天日程安排中的第一个项目: + 的形式来表示。例如,下面这个查询取回 Bill 在一周中前两天里每天的首项日程: SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill'; @@ -235,11 +234,11 @@ SELECT schedule[:][1:1] FROM sal_emp WHERE name = 'Bill'; - 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回空值。此外,如果下标超出数组边界,也会返回空值(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是空值而不是错误。 + 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回 NULL。此外,如果下标超出数组边界,也会返回 NULL(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是 NULL 而不是错误。 - 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回空值。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是空值。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回空值。 + 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回 NULL。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是 NULL。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回 NULL。 @@ -293,8 +292,8 @@ SELECT cardinality(schedule) FROM sal_emp WHERE name = 'Carol'; 修改数组 - array - modifying + 数组 + 修改 @@ -331,7 +330,7 @@ UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}' - 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用空值填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含空值。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 + 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用 NULL 填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含 NULL。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 @@ -443,21 +442,21 @@ SELECT array_cat(ARRAY[5,6], ARRAY[[1,2],[3,4]]); 在简单情况下,优先使用上面讨论的连接操作符,而不是直接调用这些函数。不过,由于连接操作符被重载以同时服务于这三种情形,所以在某些场景下使用这些函数之一有助于避免歧义。例如,考虑: -SELECT ARRAY[1, 2] || '{3, 4}'; -- the untyped literal is taken as an array +SELECT ARRAY[1, 2] || '{3, 4}'; -- 未指定类型的字面量被当作数组 ?column? ----------- {1,2,3,4} -SELECT ARRAY[1, 2] || '7'; -- so is this one +SELECT ARRAY[1, 2] || '7'; -- 这个字面量也一样 ERROR: malformed array literal: "7" -SELECT ARRAY[1, 2] || NULL; -- so is an undecorated NULL +SELECT ARRAY[1, 2] || NULL; -- 未加类型修饰的 NULL 也一样 ?column? ---------- {1,2} (1 row) -SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant +SELECT array_append(ARRAY[1, 2], NULL); -- 这可能才是原本想表达的意思 array_append -------------- {1,2,NULL} @@ -471,8 +470,8 @@ SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant 在数组中搜索 - array - searching + 数组 + 搜索 @@ -552,7 +551,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); 数组输入和输出语法 - array + 数组 I/O @@ -565,7 +564,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); - 默认情况下,数组各维度的下界索引值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: + 默认情况下,数组各维度的下界下标值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2 FROM (SELECT '[1:1][-2:-1][3:5]={{{1,2,3},{4,5,6}}}'::int[] AS f1) AS ss; diff --git a/zh/14/catalogs.sgml b/zh/14/catalogs.sgml index 5e74b5ee..d25cd01e 100644 --- a/zh/14/catalogs.sgml +++ b/zh/14/catalogs.sgml @@ -310,27 +310,27 @@ pg_ts_config - 文本搜索配置 + 文本检索配置 pg_ts_config_map - 文本搜索配置的词元映射 + 文本检索配置的词元映射 pg_ts_dict - 文本搜索字典 + 文本检索词典 pg_ts_parser - 文本搜索分析器 + 文本检索解析器 pg_ts_template - 文本搜索模板 + 文本检索模板 @@ -7347,12 +7347,12 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config目录包含表示文本搜索配置的条目。一个配置指定某个特定的文本搜索分析器,以及针对该分析器每种输出词元类型所定义的字典列表。分析器由pg_ts_config项表示,而词元到字典的映射则由pg_ts_config系统目录包含表示文本检索配置的条目。一个配置指定某个特定的文本检索解析器,以及针对该解析器每种输出词元类型所定义的词典列表。解析器记录在pg_ts_config条目中,而词元到词典的映射则由pg_ts_config_map中的辅助项定义。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。 @@ -7384,7 +7384,7 @@ SCRAM-SHA-256$<iteration count>:&l cfgname name - 文本搜索配置名 + 文本检索配置名 @@ -7414,7 +7414,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_ts_parser.oid - 该配置的文本搜索分析器的OID + 该配置的文本检索解析器的 OID @@ -7431,11 +7431,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config_map目录包含的项展示了对于每一个文本搜索配置的每一种输出词元类型,有哪些文本搜索字典可供查询以及以何种顺序。 + pg_ts_config_map 系统目录中的条目说明了,对于每个文本检索配置所用解析器的每种输出词元类型,应当查询哪些文本检索词典以及查询的顺序。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7468,7 +7468,7 @@ SCRAM-SHA-256$<iteration count>:&l maptokentype int4 - 一种由配置的分析器送出的词元类型 + 一种由配置的解析器送出的词元类型 @@ -7487,7 +7487,7 @@ SCRAM-SHA-256$<iteration count>:&l (参考 pg_ts_dict.oid - 要查询的文本搜索字典的OID + 要查询的文本检索词典的 OID @@ -7504,11 +7504,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_dict目录包含定义文本搜索字典的项。一个字典依赖于一个文本搜索模板,它指定了所有需要的函数实现,字典本身则为模板支持的用户可设置参数提供值。这种分工允许无权限的用户创建字典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 + pg_ts_dict系统目录包含定义文本检索词典的项。一个词典依赖于一个文本检索模板,它指定了所有需要的实现函数,词典本身则为模板支持的用户可设置参数提供值。这种分工允许普通用户创建词典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7540,7 +7540,7 @@ SCRAM-SHA-256$<iteration count>:&l dictname name - 文本搜索字典名 + 文本检索词典名 @@ -7550,7 +7550,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_namespace.oid - 包含该字典的名字空间OID + 包含该词典的名字空间的 OID @@ -7560,7 +7560,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_authid.oid - 字典的拥有者 + 词典的拥有者 @@ -7570,7 +7570,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_ts_template.oid - 该字典的文本搜索模板的OID + 该词典的文本检索模板的 OID @@ -7596,11 +7596,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_parser目录包含定义文本搜索分析器的项。一个分析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个分析器必须用C语言级别的函数实现,创建新分析器的工作只限于数据库的超级用户。 + pg_ts_parser系统目录包含定义文本检索解析器的项。一个解析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个解析器必须用 C 语言级别的函数实现,创建新解析器的工作只限于数据库的超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7632,7 +7632,7 @@ SCRAM-SHA-256$<iteration count>:&l prsname name - 文本搜索分析器的名字 + 文本检索解析器的名字 @@ -7642,7 +7642,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_namespace.oid - 包含此分析器的名字空间的OID + 包含此解析器的名字空间的 OID @@ -7652,7 +7652,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器启动函数的OID + 解析器启动函数的 OID @@ -7662,7 +7662,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的下一词元函数的OID + 解析器的下一词元函数的 OID @@ -7672,7 +7672,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的关闭函数的OID + 解析器的关闭函数的 OID @@ -7682,7 +7682,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器标题函数的 OID(如果没有则为零) + 解析器的 headline 函数的 OID(如果没有则为零) @@ -7692,7 +7692,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的词汇类型函数的OID + 解析器的 lextype 函数的 OID @@ -7709,11 +7709,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_template目录包含定义文本搜索模板的项。一个模板是一类文本搜索字典的实现骨架。由于一个模板必须用C语言级别的函数实现,新模板的创建只限于数据库超级用户。 + pg_ts_template系统目录包含定义文本检索模板的项。一个模板是一类文本检索词典的实现骨架。由于一个模板必须用 C 语言级别的函数实现,新模板的创建只限于数据库超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7745,7 +7745,7 @@ SCRAM-SHA-256$<iteration count>:&l tmplname name - 文本搜索模板的名字 + 文本检索模板的名字 diff --git a/zh/14/config.sgml b/zh/14/config.sgml index 300baec5..421841b5 100644 --- a/zh/14/config.sgml +++ b/zh/14/config.sgml @@ -2668,7 +2668,7 @@ include_dir 'conf.d' 配置 恢复 - 一个备库 + 备库 @@ -3059,7 +3059,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows - 列出安装在 所指定位置中、同时也被信任可供复制客户端用作逻辑输出插件的库。 + 列出安装在 所指定位置中、同时也受信任、可供复制客户端用作逻辑输出插件的库。 任何针对其他库的逻辑解码或 复制请求都将被拒绝。所有用户都受此限制。 默认值为 'pgoutput, test_decoding',它们是标准 @@ -3681,8 +3681,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( )。 + 设置规划器对一系列顺序磁盘页面读取中单次读取的代价估计。默认值是 1.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -4040,7 +4035,7 @@ ANY num_sync ( )。 + 设置规划器对一次非顺序磁盘页面读取的代价估计。默认值是 4.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -4053,14 +4048,13 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( 。 如果指定值时没有单位,则以块为单位,即BLCKSZ字节,通常为8kB。默认值是512千字节(512kB)。 @@ -4186,13 +4180,13 @@ ANY num_sync ( num_sync ( - 遗传查询优化 + 遗传查询优化器 - GEQO是一个使用探索式搜索来执行查询规划的算法。它可以降低负载查询的规划时间。 同时,GEQO的检索是随机的,因此它的规划可能会不可确定。 更多信息参阅Chapter 50。 - 遗传查询规划器(GEQO)是一种使用启发式搜索来进行查询规划的算法。它可以降低对于复杂查询(连接很多表的查询)的规划时间,但是代价是它产生的计划有时候要差于使用穷举搜索算法找到的计划。详见。 + 遗传查询优化器(GEQO)是一种使用启发式搜索进行查询规划的算法。它可以缩短复杂查询(连接很多关系的查询)的规划时间,代价是生成的计划有时不如常规穷举搜索算法找到的计划。更多信息见 @@ -4273,7 +4266,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( .) + 目前,约束排除仅在通常用于通过继承树实现表分区的情况下默认启用。为所有表启用它会增加额外的规划开销,这在简单查询上相当明显,而且通常不会为简单查询带来好处。如果没有通过传统继承方式进行分区的表,你可能希望完全关闭它。(注意,分区表的等效功能由另一个参数控制。) @@ -4522,13 +4512,7 @@ SELECT * FROM parent WHERE key = 2400; - 准备语句(显式准备或隐式生成的,例如 PL/pgSQL)可以使用自定义或通用计划执行。 - 使用其特定的参数值集为每个执行重新生成自定义计划,而通用计划不依赖于参数值,并且可以在执行中重复使用。 - 因此,使用通用计划可以节省计划时间,但如果理想计划严重依赖参数值,则通用计划可能效率低下。 - 这些选项之间的选择通常是自动进行的,但可以通过plan_cache_mode覆盖它。 - 允许的值为 auto (默认的),force_custom_planforce_generic_plan。 - 这个设置是在执行缓存计划时考虑,而不是在准备计划时考虑。 - 更多信息请参阅 . + 预备语句(无论是显式预备的,还是由 PL/pgSQL 等隐式生成的)可以使用自定义计划或通用计划执行。自定义计划会根据每次执行的具体参数值重新生成,而通用计划不依赖参数值,可以在多次执行之间复用。因此,使用通用计划能够节省规划时间,但如果理想计划高度依赖参数值,通用计划可能效率较低。系统通常会自动选择这两种计划,但可以通过plan_cache_mode覆盖这一选择。允许的值为auto(默认值)、force_custom_planforce_generic_plan。系统在执行缓存计划时考虑此设置,而不是在预备计划时。更多信息见 @@ -4548,7 +4532,7 @@ SELECT * FROM parent WHERE key = 2400; - 在哪里做日志 + 日志记录到哪里 日志写到哪里 @@ -4556,7 +4540,7 @@ SELECT * FROM parent WHERE key = 2400; current_logfiles - 和日志_目的地配置参数 + 和 log_destination 配置参数 @@ -4569,48 +4553,22 @@ SELECT * FROM parent WHERE key = 2400; - - PostgreSQL支持多种记录服务器消息的方法,包括 - stderrcsvlog, - jsonlog和 - syslog。在Windows上, - eventlog也受支持。将此参数设置为以逗号分隔的所需日志目的地列表。默认情况下仅记录到 - stderr。 - 此参数只能在postgresql.conf - 文件或服务器命令行中设置。 - - + PostgreSQL支持多种记录服务器消息的方法,包括stderrcsvlogsyslog。在 Windows 上,还支持eventlog。将此参数设为所需日志目的地的逗号分隔列表。默认只将日志记录到stderr。此参数只能在postgresql.conf文件中或在服务器命令行上设置。 如果csvlog被包括在log_destination中,日志项会以逗号分隔值CSV)格式被输出,这样可以很方便地把日志载入到程序中。详见。要产生 CSV 格式的日志输出,必须启用 - - - 如果jsonlog包含在log_destination中, - 日志条目将以JSON格式输出,这对将日志加载到程序中很方便。 - 有关详细信息,请参见。 - 必须启用才能生成JSON格式的日志输出。 - - - - 当包含stderrcsvlogjsonlog时, - 文件current_logfiles会被创建,记录日志收集器当前使用的日志文件位置和相关的日志目的地。 - 这提供了一种方便的方式来查找实例当前使用的日志。以下是该文件内容的示例: - + 如果包含stderrcsvlog,就会创建文件current_logfiles,记录日志收集器当前使用的日志文件位置及相关日志目的地。这样便于找到实例当前使用的日志。以下是此文件内容的示例: stderr log/postgresql.log csvlog log/postgresql.csv -jsonlog log/postgresql.json - 当由于轮换而创建新的日志文件时,以及重新加载log_destination时,current_logfiles会被重新创建。 - 当log_destination中不包含stderrcsvlogjsonlog, - 以及日志收集器被禁用时,它会被移除。 - + current_logfiles会在日志轮转产生新日志文件时重新创建,也会在重新载入log_destination时重新创建。如果stderrcsvlog均未包含在log_destination中,或者禁用了日志收集器,则会移除此文件。 - 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设备LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: + 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设施LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: local0.* /var/log/postgresql @@ -4618,7 +4576,7 @@ local0.* /var/log/postgresql - 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源极其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见。 + 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源及其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见 @@ -4634,20 +4592,20 @@ local0.* /var/log/postgresql - 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 + 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息可能不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 - 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供方法来轮转日志文件。还有,在某些不使用日志收集器的平台上可能会导致丢失或者混淆日志输出,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 + 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供便捷的方法来轮转日志文件。还有,在某些平台上,不使用日志收集器可能会导致日志输出丢失或混杂,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 - 日志收集器被设计成从来不会丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 + 日志收集器被设计成从来不会丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它可能会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 @@ -4681,7 +4639,7 @@ local0.* /var/log/postgresql logging_collector被启用时,这个参数设置被创建的日志文件的文件名。 - 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何时区独立的%转义,计算将在由指定的时区中完成)。 + 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何依赖时区的%转义,计算将在由指定的时区中完成)。 被支持的%转义和开放组织的strftime说明中列举的类似。 注意系统的strftime不会被直接使用,因此平台相关(非标准)的扩展无法工作。 默认是postgresql-%Y-%m-%d_%H%M%S.log。 @@ -4695,13 +4653,7 @@ local0.* /var/log/postgresql 如果在log_destination中启用了 CSV 格式输出,.csv将会被追加到时间戳日志文件名中来创建 CSV 格式输出(如果log_filename.log结尾,该后缀会被替换)。 - - 如果在log_destination中启用了JSON格式的输出, - 时间戳日志文件名将会在末尾添加.json, - 以创建JSON格式输出的文件名。 - (如果log_filename.log结尾, - 则会替换掉这个后缀。) - + 这个参数只能在postgresql.conf文件中或通过服务器命令行进行设置。 @@ -4719,7 +4671,7 @@ local0.* /var/log/postgresql - 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的十进制格式,该数字必须以一个0(零)开始)。 + 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的八进制格式,该数字必须以一个0(零)开始)。 @@ -4785,7 +4737,7 @@ local0.* /var/log/postgresql - 示例:要保留 24 小时的日志,每个小时一个日志文件,但是在日志文件尺寸超过 1GB 时轮转。可以这样做:将log_filename设置为server_log.%H%M、 + 示例:要保留 24 小时的日志,每个小时一个日志文件,如果日志文件尺寸超过 1GB,也会提前轮转。可以这样做:将log_filename设置为server_log.%H%M、 将log_truncate_on_rotation设置为on、 将log_rotation_age设置为60并且 将log_rotation_size设置为1000000。 @@ -4804,7 +4756,7 @@ local0.* /var/log/postgresql - 当启用了向syslog记录时,这个参数决定要使用的syslog设备。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4、 + 当启用了向syslog记录时,这个参数决定要使用的syslog设施。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4LOCAL5LOCAL6LOCAL7中选择,默认值是LOCAL0。还请参阅系统的syslog守护进程的文档。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -4859,7 +4811,7 @@ local0.* /var/log/postgresql - 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,有必要让消息保持逻辑上的整体性(也更加有用)。 + 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,让消息保持逻辑上的完整性可能是必要的,也可能更有用。 @@ -4878,7 +4830,7 @@ local0.* /var/log/postgresql - 当启用了向事件日志记录时,这个参数决定用来标识日志中PostgreSQL消息的程序名。默认值是PostgreSQL。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 当启用了向事件日志记录时,这个参数决定用来标识日志中PostgreSQL消息的程序名。默认值是PostgreSQL。这个参数只能在服务器启动时设置。 @@ -4924,9 +4876,7 @@ local0.* /var/log/postgresql - 控制在服务器日志中记录哪些导致错误条件的SQL语句。当前的SQL语句将包含在任何指定 - severity - 或更高消息的日志条目中。 + 控制在服务器日志中记录哪些导致错误条件的SQL语句。对于达到指定严重级别或更高级别的消息,其日志条目中会包含当前 SQL 语句。 有效值为DEBUG5DEBUG4DEBUG3DEBUG2DEBUG1、 @@ -4966,7 +4916,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -5004,7 +4954,7 @@ local0.* /var/log/postgresql - log_min_duration_statement的其他注释也适用于此设置。 + log_min_duration_statement的其他说明也适用于此设置。 @@ -5019,8 +4969,8 @@ local0.* /var/log/postgresql - 确定持续时间超过的语句的比例将被记录。 - 采样是随机的,例如0.5表示统计上有一半的机会任何给定的语句将被记录。 + 确定持续时间超过的语句中,将被记录的语句比例。 + 采样是随机的,例如0.5表示任意给定语句被记录的统计概率为二分之一。 默认值为1.0,表示记录所有采样的语句。 将此设置为零将禁用采样语句持续时间记录,与将log_min_duration_sample设置为-1相同。 只有超级用户能更改这个设置。 @@ -5038,7 +4988,7 @@ local0.* /var/log/postgresql - 设置所有语句都被记录的事务的比例,除了其他原因记录的语句。它适用于每个新事务,无论其语句的持续时间如何。 + 设置需要记录全部语句的事务比例,这些记录是在因其他原因记录的语句之外额外进行的。它适用于每个新事务,无论其语句的持续时间如何。 采样是随机的,例如0.1表示任何给定事务被记录的统计概率是十分之一。 log_transaction_sample_rate可以帮助构建事务样本。 默认值为0,表示不记录任何额外事务的语句。将其设置为1会记录所有事务的所有语句。 @@ -5083,7 +5033,7 @@ local0.* /var/log/postgresql DEBUG1 .. DEBUG5 - 为开发者提供连续的更详细的信息。 + 为开发者提供逐级更加详细的信息。 DEBUG INFORMATION @@ -5143,7 +5093,7 @@ local0.* /var/log/postgresql - 记录什么到日志 + 记录哪些内容 @@ -5164,7 +5114,7 @@ local0.* /var/log/postgresql - application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。它也会被通过包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为问号(?)。 + application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。也可以通过将其包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为问号(?)。 @@ -5191,7 +5141,6 @@ local0.* /var/log/postgresql - 这个参数启用发出各种调试输出。当设置时,会打印生成的解析树, 查询重写输出,或执行的每个查询的执行计划。这些信息是在LOG 信息级别发出,因此默认的,它们会出现在服务器日志中,但不会发送给客户端。 可以通过 client_min_messages和/或log_min_messages 来设置。这些参数缺省是off。 这些参数将会让多种调试输出被发出。当被设置时,它们为每一个被执行的查询打印结果分析树、查询重写器输出或执行计划。这些消息在LOG消息级别上被发出,因此默认情况下它们将出现在服务器日志中但不会被发送到客户端。你可以通过调整和/或来改变这种情况。这些参数默认是关闭的。 @@ -5225,10 +5174,10 @@ local0.* /var/log/postgresql - 每次由自动清理执行的操作都会被记录,如果运行时间至少达到指定时间。将此设置为零会记录所有自动清理操作。 + 当自动清理执行的操作运行时间至少达到指定时间时,就会记录该操作。将此设置为零会记录所有自动清理操作。 -1(默认值)会禁用记录自动清理操作。如果未指定单位,则将其视为毫秒。 例如,如果将其设置为250ms,则所有运行时间为250ms或更长的自动清理和分析都将被记录。 - 此外,当此参数设置为任何值而不是-1时,如果由于冲突的锁定或同时删除的关系而跳过自动清理操作,则会记录消息。 + 此外,当此参数设置为任何非-1值时,如果由于冲突锁或关系被并发删除而跳过自动清理操作,则会记录消息。 启用此参数可帮助跟踪自动清理活动。 此参数只能在postgresql.conf文件或服务器命令行中设置;但可以通过更改表存储参数来覆盖对单个表的设置。 @@ -5247,7 +5196,7 @@ local0.* /var/log/postgresql 导致检查点和重启点在服务器日志中记录。日志消息中包括一些统计信息, 包括写入的缓冲区数量和写入它们所花费的时间。此参数只能在 - postgresql.conf文件或服务器命令行中设置。默认值为开启。 + postgresql.conf文件或服务器命令行中设置。默认值为关闭。 @@ -5285,7 +5234,7 @@ local0.* /var/log/postgresql 导致会话终止被记录。日志输出提供类似于log_connections的信息,以及会话的持续时间。 - 只有超级用户和具有适当SET权限的用户可以在会话开始时更改此参数,而且在会话中根本无法更改。 + 只有超级用户可以在会话开始时更改此参数,而且在会话中根本无法更改。 默认值为off @@ -5307,7 +5256,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -5330,7 +5279,7 @@ local0.* /var/log/postgresql 控制在服务器日志中记录的每条消息的详细程度。有效值为TERSE, - DEFAULTVERBOSE,每个值都会添加更多字段到显示的消息中。 + DEFAULTVERBOSE,它们依次在显示的消息中增加更多字段。 TERSE不包括DETAILHINTQUERYCONTEXT错误信息的记录。 VERBOSE输出包括SQLSTATE错误代码 @@ -5350,7 +5299,7 @@ local0.* /var/log/postgresql - 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致很微小的性能损失。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致不可忽视的性能开销。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -5369,7 +5318,7 @@ local0.* /var/log/postgresql %字符开始转义序列,它将被按照下文描述的替换成状态信息。 未识别的转义被忽略。其他字符被直接复制到日志行。某些转义只被会话进程识别并且被主服务器进程等后台进程当作空。 通过指定一个在%之后和该选项之前的数字可以让状态信息左对齐或右对齐。 - 负值将导致在右边用空格填充状态信息已达到最小宽度,而正值则在左边填充。填充对于日志文件的人类可读性大有帮助。 + 负值将导致在右边用空格填充状态信息以达到最小宽度,而正值则在左边填充。填充对于日志文件的人类可读性大有帮助。 @@ -5432,8 +5381,8 @@ local0.* /var/log/postgresql %P - 并行组leader的进程ID,如果该进程是一个并行查询worker - no + 如果该进程是并行查询工作进程,则为并行组领导者的进程 ID + @@ -5450,8 +5399,8 @@ local0.* /var/log/postgresql %n - 带毫秒的时间戳(作为 Unix 时代) - no + 带毫秒精度的 Unix 时间戳 + @@ -5506,7 +5455,7 @@ local0.* /var/log/postgresql %Q 当前查询的查询标识符。 查询标识符默认是不计算的,所以这个部分将是零,除非 参数被激活或者配置了计算查询标识符的第三方模块 - yes + @@ -5525,7 +5474,7 @@ local0.* /var/log/postgresql %c转义打印一个准唯一的会话标识符,它由两个 4 字节的十六进制数(不带先导零)组成,以点号分隔。 - 这些数字是进程启动时间和进程 ID,因此%c也可以被用作保存打印这些项的方式的空间。 + 这些数字是进程启动时间和进程 ID,因此%c也可以用来节省空间地输出这两项信息。 例如,要从pg_stat_activity生成会话标识符,使用这个查询: SELECT to_hex(trunc(EXTRACT(EPOCH FROM backend_start))::integer) || '.' || @@ -5563,7 +5512,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 对于输出的行,%Q 总是报告零标识符, - 因为log_statement在标识符能被计算之前生成输出,包括无效标识符不能计算的无效语句。 + 因为log_statement在标识符能被计算之前生成输出,也包括无法计算标识符的无效语句。 @@ -5596,8 +5545,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 控制启动进程等待时间超过针对恢复冲突的deadlock_timeout的时候是否产生日志消息。 - 这对于决定恢复冲突是否会阻止恢复应用WAL有所帮助。 + 控制启动进程因恢复冲突而等待超过deadlock_timeout时是否产生日志消息。这有助于判断恢复冲突是否阻碍了恢复过程应用 WAL。 @@ -5627,8 +5575,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 此设置仅影响作为结果打印的日志消息,, 和相关的设置。 - 该设置的非零值会增加一些开销,特别是当参数以二进制形式发送时,因为需要转换为文本。 + 此设置仅影响由及相关设置产生的日志消息。此设置为非零值时会增加一些开销,特别是以二进制形式发送参数时,因为需要将参数转换为文本。 @@ -5672,7 +5619,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' UPDATEDELETETRUNCATE, 和COPY FROM。 如果PREPAREEXECUTE和 - EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个执行消息时会产生日志并且会包括绑定参数的值(任何内嵌的单引号会被双写)。 + EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个 Execute 消息时会产生日志并且会包括 Bind 参数的值(任何内嵌的单引号会被双写)。 @@ -5683,7 +5630,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在执行阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 + 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在 Execute 阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 @@ -5722,7 +5669,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 控制临时文件名和大小的日志记录。 - 临时文件可以用于排序、哈希和临时查询结果。 + 临时文件可以用于排序、hash 和临时查询结果。 如果通过此设置启用,每当删除临时文件时都会发出日志记录。 值为零时记录所有临时文件信息,而正值仅记录大小大于或等于指定数据量的文件。 如果未指定单位,则将其视为千字节。 @@ -5759,7 +5706,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 用户名、 数据库名、 进程 ID、 - 客户端主机和端口号、 + 客户端主机:端口号、 会话 ID、 每个会话的行号、 命令标签、 @@ -5776,7 +5723,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 错误上下文、 导致错误的用户查询(如果有且被log_min_error_statement启用)、 错误位置所在的字符计数、 - 在 PostgreSQL 源代码中错误的位置(如果log_error_verbosity被设置为verbose)以及应用名,后端类型,并行组leader的进程ID和查询ID。 + 在 PostgreSQL 源代码中错误的位置(如果log_error_verbosity被设置为verbose)、应用名、后端类型、并行组领导者的进程 ID 和查询 ID。 下面是一个定义用来存储 CSV 格式日志输出的样表: @@ -5828,7 +5775,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 设置log_filenamelog_rotation_age为你的日志文件提供一种一致的、可预测的命名空间。这让你预测文件名会是怎样以及知道什么时候一个个体日志文件完成并且因此准备好被导入。 + 设置log_filenamelog_rotation_age,为日志文件提供一致且可预测的命名方案。这样就能预测文件名,并知道单个日志文件何时已完成写入、可以导入。 @@ -5852,222 +5799,14 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - - - 使用JSON格式的日志输出 - - - 包括jsonloglog_destination列表中提供了一种方便的方式将日志文件导入到许多不同的程序中。此选项以JSON格式发出日志行。 - - - - 字段值为null的字符串字段将被排除在输出之外。 - 未来可能会添加其他字段。处理jsonlog输出的用户应忽略未知字段。 - - - - 每个日志行都被序列化为一个JSON对象,其中包含一组键和它们对应的值,如中所示。 - -
- - JSON日志条目的键和值 - - - - - 键名 - 类型 - 描述 - - - - - - timestamp - string - 带毫秒的时间戳 - - - - user - string - 用户名 - - - - dbname - string - 数据库名称 - - - - pid - number - 进程ID - - - - remote_host - string - 客户端主机 - - - - remote_port - number - 客户端端口 - - - - session_id - string - 会话ID - - - - line_num - number - 每个会话的行号 - - - - ps - string - 当前ps显示 - - - - session_start - string - 会话开始时间 - - - - vxid - string - 虚拟事务ID - - - - txid - string - 常规交易ID - - - - error_severity - string - 错误严重性 - - - - state_code - string - SQLSTATE代码 - - - - message - string - 错误消息 - - - - detail - string - 错误消息的详细信息 - - - - hint - string - 错误消息提示 - - - - internal_query - string - 导致错误的内部查询 - - - - internal_position - number - 内部查询的游标索引 - - - - context - string - 错误上下文 - - - - statement - string - 客户提供的查询字符串 - - - - cursor_position - number - 查询字符串中的光标索引 - - - - func_name - string - 错误位置函数名称 - - - - file_name - string - 错误位置的文件名 - - - - file_line_num - number - 错误位置的文件行号 - - - - application_name - string - 客户端应用程序名称 - - - - backend_type - string - 后端类型 - - - - leader_pid - number - 活动并行工作者的领导者进程ID - - - - query_id - number - 查询ID - - - -
- 进程标题 - 这些设置控制服务器进程的进程标题如何被修改。进程标题通常可以用ps或者 Windows 上的进程浏览器等程序来查看。详见。 + 这些设置控制服务器进程的进程标题如何修改。通常可以通过ps等程序查看进程标题,在 Windows 上则可以使用Process Explorer。详情参见 @@ -6101,7 +5840,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 每次服务器接收到新的SQL命令时,都可以更新进程标题。 + 启用后,每次服务器接收到新的 SQL 命令时都会更新进程标题。 在大多数平台上,默认情况下此设置为on,但在Windows上默认为off, 因为该平台更新进程标题的开销较大。 只有超级用户能更改这个设置。 @@ -6141,7 +5880,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对每个会话当前执行命令的信息收集,包括其标识符和命令开始执行的时间。 - 此参数默认为开启状态。请注意,即使启用了此信息,只有超级用户、具有 + 此参数默认为开启状态。请注意,即使启用了此参数,只有超级用户、具有 pg_read_all_stats角色权限的角色和拥有被报告会话的用户 (包括属于他们具有权限的角色的会话)才能看到此信息,因此不应构成安全风险。 只有超级用户能更改这个设置。 @@ -6159,7 +5898,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 为每个活动会话指定存储当前执行命令的文本所保留的内存量,它们被用于pg_stat_activity.query域。 + 为每个活动会话指定存储当前执行命令的文本所预留的内存量,它们被用于pg_stat_activity.query字段。 如果指定值时没有单位,则以字节为单位。默认值是 1024字节。这个参数只能在服务器启动时被设置。 @@ -6176,7 +5915,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对数据库活动的统计信息收集。 - 此参数默认为开启,因为自动清理守护进程需要收集的信息。 + 此参数默认为开启,因为自动清理守护进程需要这些收集到的信息。 只有超级用户能更改这个设置。 @@ -6229,7 +5968,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用函数调用次数和时间的跟踪。指定pl以仅跟踪过程语言函数, + 启用函数调用次数和耗时的跟踪。指定pl以仅跟踪过程语言函数, all以同时跟踪SQL和C语言函数。默认值为none, 即禁用函数统计跟踪。只有超级用户能更改这个设置。 @@ -6278,21 +6017,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用查询标识符的内核计算。 - 查询标识符可以在 pg_stat_activity - 视图中显示,使用 EXPLAIN,或者如果通过 - 参数进行配置,则可以在日志中发出。 - 扩展还需要计算查询标识符。 - 请注意,如果内核查询标识符计算方法不可接受,也可以使用外部模块。 - 在这种情况下,必须始终禁用内核计算。 - 有效值为 off(始终禁用), - on(始终启用),auto, - 允许诸如 这样的模块 - 自动启用它,并且 regress 具有与 - auto 相同的效果,只是查询标识符不会显示在 - EXPLAIN 输出中,以便促进自动回归测试。 - 默认值为 auto。 + 启用内置的查询标识符计算功能。查询标识符可以显示在pg_stat_activity视图或EXPLAIN的输出中,也可以通过参数配置后写入日志。扩展也要求计算查询标识符。注意,如果内置的查询标识符计算方法不符合要求,可以改用外部模块。在这种情况下,必须始终禁用内置计算功能。有效值为off(始终禁用)、on(始终启用)、auto(允许等模块自动启用此功能),以及regress。后者与auto效果相同,但不会在EXPLAIN输出中显示查询标识符,以便进行自动回归测试。默认值为auto @@ -6332,9 +6057,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 对于每个查询,将各自模块的性能统计输出到服务器日志中。这是一个简单的性能分析工具,类似于Unix getrusage()操作系统功能。 - log_statement_stats报告总语句统计,而其他选项报告每个模块的统计信息。 + log_statement_stats报告整个语句的统计信息,而其他选项报告每个模块的统计信息。 log_statement_stats不能与任何单独模块选项一起启用。所有这些选项默认情况下都是禁用的。 - 只有超级用户和具有适当SET权限的用户才能更改这些设置。 + 只有超级用户才能更改这些设置。 @@ -6617,7 +6342,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; DEBUG1LOGNOTICEWARNINGERROR。 每个级别都包括其后的所有级别。级别越靠后,被发送的消息越少。默认值是NOTICE。 - 注意LOG在这里有与中不同的排名。 + 注意LOG在这里的排序与中的不同。
@@ -6637,15 +6362,15 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,用于进行搜索该对象的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 + 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,搜索该对象时的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 - search_path的值必需是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被安静地忽略。 + search_path的值必须是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被静默忽略。 - 如果列表项之一是特殊名$user,则具有SESSION_USER返回的名字的模式将取代它(如果有这样一个模式并且该用户有该模式的USAGE权限;如果没有,$user会被忽略)。 + 如果列表项之一是特殊名$user,则具有CURRENT_USER返回的名字的模式将取代它(如果有这样一个模式并且该用户有该模式的USAGE权限;如果没有,$user会被忽略)。 @@ -6670,11 +6395,12 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个参数的缺省值是"$user", public。这种设置支持一个数据库(其中没有用户拥有私有模式,并且所有人共享使用public)、每个用户私有模式及其组合的共享使用。其它效果可以通过全局或者针对每个用户修改默认搜索路径设置获得。 + 这个参数的默认值是"$user", public。这种设置支持共享使用数据库(用户没有私有模式,所有人共享使用public)、每个用户拥有私有模式,以及二者的组合。 + 还可以通过全局或针对每个用户修改默认搜索路径设置来获得其他效果。 - 更多有关方案处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 + 更多有关模式处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 @@ -6694,7 +6420,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,只要有至少一条策略被应用则查询就会失败。默认为on。受限的行可见性会导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS)属性的角色没有效果。 + 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,原本会应用至少一条策略的查询就会失败。默认为on。受限的行可见性可能导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS属性的角色)没有效果。 @@ -6713,8 +6439,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个参数指定了在创建表或物化视图时使用的默认表访问方法,如果CREATE命令没有明确指定访问方法, - 或者当使用SELECT ... INTO时,不允许指定表访问方法。默认值是heap。 + 创建表或物化视图时,如果CREATE命令没有显式指定访问方法,或者使用了不允许指定表访问方法的SELECT ... INTO,则使用此参数指定的默认表访问方法。默认值为heap @@ -6734,7 +6459,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建企图将失败。 + 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建尝试将失败。 @@ -6742,7 +6467,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当创建数据库时也会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 + 创建数据库时也不会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 @@ -6791,11 +6516,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被放置在里表中的连续表空间中。如果列表被选中元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 + 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被依次放置在列表中的连续表空间中。如果列表中被选中的元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 - 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,类似于为用户指定一个不具有CREATE权限的表空间。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特殊地,使用一个在postgresql.conf中设置的值时,这条规则起效。 + 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,指定一个用户不具有CREATE权限的表空间也同样是错误。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特别是,使用一个在postgresql.conf中设置的值时,这条规则起效。 @@ -6820,7 +6545,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 这个参数通常为打开。 当设置为off时,它禁用期间对例程体字符串的验证。 - 禁用验证避免了验证处理的副作用,特别避免了如向前引用导致的伪肯定。 + 禁用验证避免了验证处理的副作用,特别是避免前向引用等问题导致的误报。 在代表其他用户载入函数之前设置这个参数为offpg_dump会自动这样做。 @@ -6863,7 +6588,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态 。默认是off(读/写)。 + 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态。默认是off(读/写)。 @@ -6886,11 +6611,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当运行在可串行化隔离级别时,一个可延迟只读 SQL 事务可以在它被允许继续之前延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的负荷;因此串行化代码将没有任何理由因为并发更新而强制它中断,使得这个选项适合于长时间运行的只读事务。 + 当运行在serializable隔离级别时,一个可延迟只读 SQL 事务可能在获准继续之前被延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的开销;因此串行化代码将没有任何理由因为并发更新而强制它中止,使得这个选项适合于长时间运行的只读事务。 - 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些操作在低于可串行化隔离级别上的事务无效。默认值是off。 + 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些运行在低于serializable隔离级别上的事务无效。默认值是off @@ -6934,7 +6659,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的只读状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -6954,7 +6679,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的可延迟性状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -6969,16 +6694,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 控制当前会话中复制相关触发器和规则的触发。 - 可能的值是origin(默认值), - replicalocal。 - 设置此参数会导致丢弃先前缓存的任何查询计划。 - 只有超级用户能更改这个设置。 + 控制当前会话中复制相关触发器和规则的触发。设置此变量需要超级用户权限,并会丢弃任何先前缓存的查询计划。 + 可用值为origin(默认值)、replicalocal 这个设置的预期用途是由逻辑复制系统在应用所复制的更改时将它设置为replica。 - 其效果将是触发器和规则(没有对其默认配置做修改)在复制机上将不会被触发。 + 其效果将是触发器和规则(没有对其默认配置做修改)在副本上将不会被触发。 更多信息请参考ALTER TABLE的子句ENABLE TRIGGER以及ENABLE RULE @@ -7008,9 +6730,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 超时从命令到达服务器的时间开始计算,一直到它被服务器完成为止。 - 如果单个简单查询消息中出现多个 SQL 语句,超时将分别应用于每个语句。(PostgreSQL 13 之前的版本通常将超时应用于整个查询字符串。 - 在扩展查询协议中,当任何与查询相关的消息(解析、绑定、执行、描述)到达时,超时就开始运行,并且可以通过执行完成或同步消息来取消超时。 + 超时从命令到达服务器时开始计算,直到服务器完成该命令为止。 + 如果单个简单查询消息中出现多个 SQL 语句,超时将分别应用于每个语句。 + (PostgreSQL 13 之前的版本通常将超时应用于整个查询字符串。) + 在扩展查询协议中,当任何与查询相关的消息(Parse、Bind、Execute、Describe)到达时开始计时, + 并在处理完 Execute 或 Sync 消息时取消计时。 @@ -7031,13 +6755,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 如果任何语句在试图获取表、索引、行或其他数据库对象上的锁时等到超过指定的时间量,该语句将被中止。 + 如果任何语句在试图获取表、索引、行或其他数据库对象上的锁时等待超过指定的时间量,该语句将被中止。 该时间限制独立地应用于每一次锁获取尝试。该限制会应用到显式锁定请求(如LOCK TABLE或不带NOWAITSELECT FOR UPDATE)和隐式获得的锁。 如果指定值时没有单位,则以毫秒为单位。一个零值(默认)将禁用超时。 - 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为事务超时将总是第一个被触发。 + 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为语句超时将总是第一个被触发。 如果log_min_error_statement 被设置为ERROR 或更低,超时的语句将被记录。 @@ -7057,15 +6781,14 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 终止任何已经闲置(这是指,等待客户端查询)超过这个参数所指定时间量的打开事务的会话。 - 如果这个值指定时没有单位,它被设为毫秒。 - 零值(默认)禁用超时。 + 终止在打开的事务中空闲(即等待客户端查询)超过指定时长的任何会话。 + 如果指定值时不带单位,则以毫秒为单位。零值(默认值)禁用此超时。 - 此选项可以用于确保空闲会话不会在不合理的时间内持有锁。 - 即使在没有持有重要锁的时候,打开的事务也会阻止清理最近死亡、且可能只对该事务可见的元组;所以长时间保持空闲会导致表膨胀。 - 详见。 + 此选项可确保空闲会话不会持有锁过长时间。 + 即使没有持有重要的锁,打开的事务也会阻止清理最近死亡、且可能只对该事务可见的元组;因此长时间空闲可能造成表膨胀。 + 更多详情参见 @@ -7080,9 +6803,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 终止任何空闲的会话(也就是,等待客户端查询),但不在打开的事务中,且超过指定的时间量。 - 如果指定值时不带单位,其单位采用毫秒。 - 零值时(默认)禁用超时。 + 终止不在打开的事务中、且空闲(即等待客户端查询)超过指定时长的任何会话。 + 如果指定值时不带单位,则以毫秒为单位。零值(默认值)禁用此超时。 @@ -7090,8 +6812,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 注意不要对通过连接池软件或其他中间件建立的连接强制执行此超时,因为这样的层可能不会很好地响应意外的连接关闭。 - 只对交互会话启用此超时可能是帮助的,也许只对特定用户应用它。 + 应谨慎对通过连接池软件或其他中间件建立的连接强制执行此超时,因为这样的层可能不会很好地响应意外的连接关闭。 + 只对交互会话启用此超时可能有所帮助,也许只对特定用户应用它。 @@ -7103,8 +6825,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
+ - 当表的pg_class.relfrozenxid字段达到该设置指定的年龄时,VACUUM会执行激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值是 1.5 亿个事务。尽管用户可以将该值设置为 0 到 20 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的 95%,从而在触发防回卷 autovacuum 之前仍有机会执行一次常规手工VACUUM。更多信息请参见。 + 如果表的pg_class.relfrozenxid字段达到此设置指定的年龄,VACUUM就会执行一次激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值为 1.5 亿个事务。尽管用户可以将该值设置在 0 到 20 亿之间,VACUUM仍会悄悄将其有效值限制为不超过的 95%,以便在针对该表启动防回卷自动清理之前,周期性手工VACUUM仍有机会运行。详见 @@ -7117,7 +6840,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 指定VACUUM在扫描表时用来决定是否冻结行版本的切断年龄(以事务计)。默认值是 5000 万个事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见。 + 指定VACUUM在扫描表时用来决定是否冻结行版本的截止年龄(以事务计)。默认值是 5000 万个事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见 @@ -7130,13 +6853,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 指定表的pg_class.relfrozenxid字段在VACUUM采取特别措施以避免系统范围事务 ID 回卷失败之前所允许达到的最大年龄(以事务计)。这是VACUUM的最后防线。失效保护通常会在防止事务 ID 回卷的 autovacuum 已经运行了一段时间后触发,但也有可能在任何VACUUM期间触发。 + 指定表的pg_class.relfrozenxid字段在VACUUM采取非常措施以避免系统范围事务 ID 回卷失败之前所允许达到的最大年龄(以事务数计)。这是VACUUM的最后手段。失效保护通常会在为防止事务 ID 回卷而启动的自动清理已经运行一段时间后触发,但也可能在任何一次VACUUM期间触发。 当失效保护被触发时,将不再应用任何有效的基于代价的延迟,并且会跳过进一步的非关键维护任务(例如索引清理)。 - 默认值为 16 亿个事务。尽管用户可以将该值设置为 0 到 21 亿之间的任意值,VACUUM会悄悄将有效值调整为不低于的 105%。 + 默认值为 16 亿个事务。尽管用户可以将该值设置在 0 到 21 亿之间,VACUUM仍会悄悄将其有效值调整为不低于的 105%。 @@ -7148,8 +6871,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; + - 当表的pg_class.relminmxid字段达到该设置指定的年龄时,VACUUM会执行激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不是只扫描那些可能包含死元组的页面。默认值是 1.5 亿个多事务。尽管用户可以将该值设置为 0 到 20 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的 95%,从而在触发防回卷 autovacuum 之前仍有机会执行一次常规手工VACUUM。更多信息请参见。 + 如果表的pg_class.relminmxid字段达到此设置指定的年龄,VACUUM就会执行一次激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值为 1.5 亿个多事务。尽管用户可以将该值设置在 0 到 20 亿之间,VACUUM仍会悄悄将其有效值限制为不超过的 95%,以便在针对该表启动防回卷清理之前,周期性手工VACUUM仍有机会运行。详见 @@ -7162,7 +6886,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 指定VACUUM在扫描表时用来决定是否将多事务 ID 替换为较新的事务 ID 或多事务 ID 的切断年龄(以多事务计)。默认值是 500 万个多事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见。 + 指定VACUUM在扫描表时用来决定是否将多事务 ID 替换为较新的事务 ID 或多事务 ID 的截止年龄(以多事务计)。默认值是 500 万个多事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见 @@ -7215,7 +6939,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
- 这里的实际选择都是根据爱好做出的,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码将比 base64 编码更大。 + 这里的实际选择主要取决于偏好,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码会比 base64 编码略大。 @@ -7236,7 +6960,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当在XML和字符串值之间进行转换时,无论设置DOCUMENT或 CONTENT都是隐式的。可参阅Section 8.13。 有效值是DOCUMENT和CONTENT。 缺省值是CONTENT。当在 XML 和字符串值之间进行转换时,设置DOCUMENTCONTENT都是隐式的。详见。有效值是DOCUMENTCONTENT。默认值是CONTENT。 + 设置在 XML 与字符串值之间进行转换时,隐含采用DOCUMENT还是CONTENT。 + 有关说明参见。有效值是DOCUMENTCONTENT。默认值是CONTENT @@ -7271,7 +6996,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; restrict_nonsystem_relation_kind (string) - restrict_nonsystem_relation_kind配置参数 + restrict_nonsystem_relation_kind + 配置参数 @@ -7286,7 +7012,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 区域和格式化 + 区域设置和格式化 @@ -7300,7 +7026,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域行为的设置初始化配置文件。 + 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域设置行为的设置初始化配置文件。 @@ -7315,11 +7041,14 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置间隔值的显示格式。值sql_standard将产生匹配 SQL 标准间隔文本的输出。当参数被设置为ISO时,值postgres(默认)将产生匹配PostgreSQL发行 8.4 之前的输出。当DateStyle参数被设置为非ISO输出时,值postgres_verbose会产生匹配PostgreSQL发行 8.4 之前的输出。值iso_8601会产生匹配在 ISO 8601 的 4.4.3.2 节中定义的带标志符格式的时间间隔的输出。 + 设置时间间隔值的显示格式。值sql_standard会生成符合SQL标准时间间隔字面量的输出。 + 值postgres(默认值)的输出与PostgreSQL 8.4 之前版本中设为ISO时的输出一致。 + 值postgres_verbose的输出与PostgreSQL 8.4 之前版本中DateStyle设为非ISO输出时的输出一致。 + 值iso_8601会生成符合 ISO 8601 第 4.4.3.2 节定义的时间间隔带标志符格式的输出。 - IntervalStyle参数也可以影响对有歧义的间隔输入的解释。详见。 + IntervalStyle参数也会影响对有歧义的时间间隔输入的解释。详见 @@ -7377,23 +7106,23 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 如果值为1(默认值)或更高,浮点值被输出为最短-精度格式;参见。 + 如果值为 1(默认值)或更高,浮点值被输出为最短精确格式;参见。 实际生成的位数只取决于输出的值,而不取决于此参数的值。 - float8 值最多需要 17 位数字,float4值最多需要9位数字。 + float8 值最多需要 17 位数字,float4值最多需要9位数字。 这种格式既快速又精确,在正确读取时精确地保留了原始的二进制浮点值。为了历史兼容性,允许的值最大为3。 如果值为零或负,则输出四舍五入为给定的十进制精度。 - 使用的精度是根据此参数的值减小的类型((FLT_DIGDBL_DIG,视情况而定)的标准位数。 + 所用精度以该类型的标准位数(根据类型使用FLT_DIGDBL_DIG)为基础,再按此参数的值减少。 (例如,指定 -1 将导致float4 值输出四舍五入为 5 位有效数字,而float8值四舍五入为 14 位。) - 此格式较慢,不会保留二进制浮点值的所有位,但可能令人更易于阅读。 + 此格式较慢,不会保留二进制浮点值的所有位,但可能更便于阅读。 此参数的含义,以及其默认值,在 PostgreSQL 12 中发生了变化; - 参见 以便进一步讨论。 + 参见 了解进一步讨论。 @@ -7429,11 +7158,11 @@ SET XML OPTION { DOCUMENT | CONTENT };
- 在一些系统上,这个区域分类并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 + 在一些系统上,这个区域设置类别并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 - 只有超级用户能更改这个设置。 + 只有超级用户能更改这个设置,因为它会同时影响发送到服务器日志和客户端的消息,设置不当可能降低服务器日志的可读性。 @@ -7448,7 +7177,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化货币量的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化货币量的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -7463,7 +7192,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化数字的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化数字的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -7478,7 +7207,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化日期和时间的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化日期和时间的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -7495,7 +7224,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 选择被那些没有显式参数指定配置的文本搜索函数变体使用的文本搜索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配区域的配置,initdb将用对应于选中的lc_ctype区域的设置初始化配置文件。 + 选择被那些没有显式参数指定配置的文本检索函数变体使用的文本检索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配该区域设置的配置,initdb将用对应于选中的lc_ctype区域设置的值初始化配置文件。 @@ -7510,7 +7239,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 为了载入附加的功能或者达到提高性能的目的,可用多个设置来预先载入共享库到服务器中。 - 例如'$libdir/mylib'设置可能会导致mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 + 例如'$libdir/mylib'设置会使mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 @@ -7519,12 +7248,12 @@ SET XML OPTION { DOCUMENT | CONTENT }; 只有特别为与PostgreSQL一起使用设计的共享库才能以这种方式载入。每一个PostgreSQL支持 - 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非PostgreSQL无法 + 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非 PostgreSQL 库无法 以这种方式被载入。你可能可以使用操作系统的工具(如LD_PRELOAD)载入它。 - 总之,请参考特定模块的文档来用推荐的方法载入它。 + 一般来说,请参考特定模块的文档来用推荐的方法载入它。 @@ -7558,9 +7287,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 这个特性的目的是允许非特权用户在特定的会话中载入正在调试的或者性能度量库, - 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客 - 户端的PGOPTIONS环境变量或者 + 这个特性的目的是允许非特权用户在特定的会话中载入用于调试或性能测量的库, + 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客户端的PGOPTIONS环境变量或者 ALTER ROLE SET来设置这个参数。 @@ -7598,7 +7326,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 不同,相对于在库被第一次使用 - 时载入它,在会话开始时载入库并没有什么性能优势。不过,当使用连接池时这样做还是有一些 + 时载入它,在会话开始时载入库并没有明显的性能优势。不过,当使用连接池时这样做还是有一些 优势。 @@ -7638,9 +7366,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 在 Windows 主机上,在服务器启动时预载入一个库并不会减少启动每个新服务器进程所需的 - 时间;每一个服务器进程将会重新载入预载入的库。不过,对于那些要在postmaster启动时 + 时间;每一个服务器进程将会重新载入所有预载入的库。不过,对于那些要在postmaster启动时 执行操作的库来说,Windows 主机上的 - shared_preload_libraries任然有用。 + shared_preload_libraries仍然有用。 @@ -7689,13 +7417,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 如果需要打开一个可以动态装载的模块并且在CREATE FUNCTIONLOAD命令中指定的文件名没有目录部分(即名字中不包含斜线),那么系统将搜索这个路径以查找所需的文件。
- - dynamic_library_path的值必须是一个冒号分隔(或者在 Windows 上以分号分隔)的绝对目录路径的列表。如果一个列表元素以特殊字符串开始,$libdir会被替换为PostgreSQL包中已编译好的库目录。这里是PostgreSQL发布提供的模块被安装的位置(使用pg_config --pkglibdir来找到这个目录的名字)。例如: - + 参数dynamic_library_path的值必须是由冒号(Windows上为分号)分隔的绝对目录路径列表。如果某个列表元素以特殊字符串$libdir开头,则会使用编译时确定的PostgreSQL软件包的库目录来替换$libdir;该目录是标准PostgreSQL发行版所提供模块的安装位置。(使用pg_config --pkglibdir可以找出此目录的名称。)例如: dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir' - - 或者在 Windows 环境中: - +或者,在 Windows 环境中: dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' @@ -7705,7 +7429,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数可以由超级用户和具有适当SET权限的用户在运行时更改, + 这个参数可以由超级用户在运行时更改, 但以这种方式进行的设置只会持续到客户端连接结束,因此这种方法应该保留用于开发目的。 推荐设置此参数的方法是在postgresql.conf配置文件中。 @@ -7724,7 +7448,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - GIN 索引返回的集合尺寸的软上限。详见。 + GIN 索引扫描返回的集合尺寸的软上限。详见 @@ -7757,18 +7481,18 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这是在锁上等待的时间,然后再检查是否存在死锁条件。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 + 指定在检查是否发生死锁之前等待锁的时间。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 我们乐观地假设在生产应用程序中死锁并不常见,所以在检查死锁之前只是等待一段时间。 增加此值会减少在不必要的死锁检查中浪费的时间,但会减慢实际死锁错误的报告速度。 如果未指定单位,则将其视为毫秒。 - 默认值为一秒(1s),这可能是您在实践中想要的最小值。 - 在负载较重的服务器上,您可能希望提高它。 - 理想情况下,设置应超过您的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 + 默认值为一秒(1s),这可能是你在实践中想要的最小值。 + 在负载较重的服务器上,你可能希望提高它。 + 理想情况下,设置应超过你的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 只有超级用户能更改这个设置。 - 当被设置时,这个参数还可以决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 + 当被设置时,这个参数也决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 @@ -7821,7 +7545,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制在谓词锁被提升为覆盖整个关系之前,该谓词锁能够在单个关系上锁住多少页面或元组。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个关系之前,可以对单个关系中的多少页面或元组加谓词锁。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -7836,7 +7560,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制在谓词锁被提升为覆盖整个页面之前,该谓词锁能在单一页面上锁住多少行。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个页面之前,可以对单个页面中的多少行加谓词锁。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -7864,7 +7588,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个空数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。对于那些要求旧行为的应用的向后兼容性,这个变量可以被设置为off。 + 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个值为空值的数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。为了向后兼容那些要求旧行为的应用,这个变量可以被设置为off @@ -7884,11 +7608,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制字符串文本中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\'。如果客户端代码没有做到正确转义,那么将会导致 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 + 这个参数控制字符串字面量中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\。如果客户端代码没有做到正确转义,那么就可能遭到 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 - 注意在符合标准的字符串文本中,\就表示\。这个参数只影响不符合标准的文本的处理,包括转义字符串语法(E'...')。 + 注意在符合标准的字符串字面量中,\就表示\。这个参数只影响不符合标准的字面量的处理,包括转义字符串语法(E'...')。 @@ -7904,11 +7628,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 打开时,如果在普通字符串文本中('...'语法)出现了 一个反斜线(\)并且standard_conforming_strings为关闭,那么就会发出一个警告。默认值是on。 + 打开时,如果在普通字符串字面量中('...'语法)出现了 一个反斜线(\)并且standard_conforming_strings为关闭,那么就会发出一个警告。默认值是on - 希望使用反斜线作为转义符的应用应该被修改来使用转义字符串语法(E'...'),因为在 SQL 标准中普通字符串的默认行为是将反斜线视作一个普通字符。这个变量可以被启用来帮助定位需要被更改的代码。 + 希望使用反斜线作为转义符的应用应该被修改来使用转义字符串语法(E'...'),因为按照 SQL 标准,普通字符串现在默认将反斜线视作一个普通字符。这个变量可以被启用来帮助定位需要被更改的代码。 @@ -7929,7 +7653,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 设置这个参数不会禁用所有与大对象相关的安全检查 — 除了那些在PostgreSQL 9.0中已经修改了的默认行为。 + 设置此变量不会禁用所有与大对象相关的安全检查 — 只禁用那些在PostgreSQL 9.0 中默认行为发生变化的检查。 @@ -7952,7 +7676,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' standard_conforming_strings (boolean) - 字符串标准符合 + 字符串符合标准 standard_conforming_strings配置参数 @@ -7960,7 +7684,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 控制普通字符串文本('...')是否按照 SQL 标准把反斜线当普通文本。从PostgreSQL 9.1 开始,默认值为on(之前的发行中默认值为off)。应用可以检查这个参数来判断字符串文本如何被处理。这个参数的存在也可以被当做转义字符串语法(E'...')被支持的标志。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 + 控制普通字符串字面量('...')是否按照 SQL 标准把反斜线当普通文本。从PostgreSQL 9.1 开始,默认值为on(之前的发行中默认值为off)。应用可以检查这个参数来判断字符串字面量如何被处理。这个参数的存在也可以被当做转义字符串语法(E'...')被支持的标志。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 @@ -7975,7 +7699,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询来,这样的扫描会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on。 + 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询,这样的扫描可能会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on @@ -7999,15 +7723,15 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr得出空值值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空(未知)。因此这个参数默认为off。 + 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr计算结果为空值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空值(未知)。因此这个参数默认为off - 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释)。它们不是非常有用并且在普通应用中也不常见,在应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及 空值的表达式的语义上感到困惑,因此这个选项默认为关闭。 + 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释),它们不是非常有用并且在普通应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及空值的表达式语义感到困惑,因此这个选项默认为关闭。 - 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不是劣质程序的一般修复。 + 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不能普遍修复错误的程序写法。 @@ -8053,7 +7777,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 当被设置为开(on),PostgreSQL将在一次后端崩溃后自动重新初始化。 + 当设置为 on(默认值)时,PostgreSQL将在一次后端崩溃后自动重新初始化。 让这个值设置为开(on)通常是将数据库可用性最大化的最佳方法。但是在某些环境中,例如PostgreSQL被集群软件调用时,禁用重启可能很有用,这样集群软件可以得到控制并且采取它认为适当的行动。 @@ -8073,7 +7797,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果设置为关(off),PostgreSQL在将修改的数据文件刷新到文件系统失败时,将引发PANIC级错误。 + 当设置为 off(默认值)时,PostgreSQL在将修改后的数据文件刷盘到文件系统失败时,将引发PANIC级错误。 这样会导致数据库服务器崩溃。这个参数只能在服务器启动时被设置。 @@ -8082,8 +7806,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果设置为开(on),PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷新操作。 - 仅在调查操作系统假如回写失败时对缓冲数据的处理方式的情况下,才将其设置为开(on)。 + 如果设置为开(on),PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷盘操作。 + 只有在调查清楚操作系统在回写失败时如何处理缓冲数据之后,才应将其设置为开(on)。 @@ -8100,14 +7824,14 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 当设置为fsync,也就是默认值,PostgreSQL将在崩溃恢复开始之前递归地打开并同步数据目录中的所有文件。 对文件的搜索将遵循WAL目录和每个配置表空间的符号链接(而不是任何其它符号链接)。 - 这是为了确保在重现更改之前,所有WAL和数据文件都持久地存储在硬盘上。 - 这适用于在启动没有完全关闭的数据库集簇时,包括由pg_basebackup创建的副本。 + 这是为了确保在重放更改之前,所有WAL和数据文件都持久地存储在磁盘上。 + 这适用于每次启动未正常关闭的数据库集簇时,包括由pg_basebackup创建的副本。 - 在Linux上,可以用syncfs代替,请求操作系统来同步包含数据目录的整个文件系统,WAL文件和每个表空间(但不是通过符号链接可访问到的任何其他文件系统)。 + 在Linux上,可以用syncfs代替,请求操作系统来同步数据目录、WAL 文件和各个表空间所在的整个文件系统(但不是通过符号链接可访问到的任何其他文件系统)。 这可能比fsync设置快得多,因为它不需要逐个打开每个文件。 - 另一方面,如果一个文件系统是被其他需要修改大量文件的应用程序共享的,它可能会慢一些,因为这些文件也将写入硬盘。 + 另一方面,如果一个文件系统是被其他需要修改大量文件的应用程序共享的,它可能会慢一些,因为这些文件也将写入磁盘。 此外,在5.8之前的Linux版本中,向磁盘写入数据时遇到的I/O错误可能不会报告给PostgreSQL,相关的错误消息可能只出现在内核日志中。 @@ -8126,11 +7850,10 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 预置选项 - 下列参数是只读的。 - 同样,它们被排除在postgresql.conf文件示例之外。 - 这些选项报告特定应用可能感兴趣的多种PostgreSQL行为,特别是管理前端相关的行为。 - 所有这些都是在PostgreSQL被编译或者它被安装时决定的。 - + 下列参数是只读的,因此未列入示例 postgresql.conf 文件。 + 这些选项报告 PostgreSQL 行为的各个方面,某些应用(特别是管理前端)可能对此感兴趣。 + 其中大多数参数在编译或安装 PostgreSQL 时确定。 +
@@ -8159,7 +7882,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告对这个集簇是否启用了数据校验码。详见。 + 报告对这个集簇是否启用了数据校验和。详见 @@ -8174,7 +7897,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 在Unix系统上,这个参数报告启动时的数据目录(由定义)的权限。 + 在 Unix 系统上,这个参数报告服务器启动时数据目录(由定义)的权限。 (在Microsoft Windows上这个参数将总是显示0700。) 更多信息请参考 @@ -8212,7 +7935,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告PostgreSQL是否在编译时打开了 64 位整数日期和时间。从PostgreSQL 10起,这个值总是on。 + 报告PostgreSQL是否在编译时启用了对 64 位整数日期和时间的支持。从PostgreSQL 10起,这个值总是on @@ -8228,9 +7951,9 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 报告服务器当前是否处于热备模式。 - 当这个是on的时候,所有的事务强制为只读。 - 在会话中,这个只能在服务器提升为主库的时候变更。 - 更多信息参见 + 当此值为 on 时,所有事务都被强制为只读。 + 在会话中,此值只有在服务器被提升为主库时才会改变。 + 更多信息参见 @@ -8272,7 +7995,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定的。默认值是 100 个参数。 + 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定。默认值是 100 个参数。 @@ -8287,7 +8010,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64 ;因此max_identifier_length的默认值是 63,但是在使用多字节编码时可以少于 63 个字符。 + 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64;因此max_identifier_length的默认值是 63 字节,在使用多字节编码时,这可能不足 63 个字符。 @@ -8350,7 +8073,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告服务器版本数值。它是由编译服务器时的PG_VERSION值决定的。 + 报告服务器的版本号。它是由编译服务器时的PG_VERSION值决定的。 @@ -8365,7 +8088,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告服务器版本数值的整数值。它是由编译服务器时的PG_VERSION_NUM值决定的。 + 以整数形式报告服务器的版本号。它是由编译服务器时的PG_VERSION_NUM值决定的。 @@ -8384,8 +8107,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告此PostgreSQL服务器已构建的 SSL 库的名称(即使此实例当前未配置或使用 SSL), - 例如OpenSSL,或一个空字符串(如果没有)。 + 报告此PostgreSQL服务器在构建时使用的 SSL 库的名称(即使此实例当前未配置或使用 SSL), + 例如OpenSSL,如果没有使用 SSL 库,则报告空字符串。 @@ -8428,11 +8151,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 自定义选项 - 这个特性被设计用来由附加模块向PostgreSQL添加通常不为系统知道的参数(例如过程语言)。这允许使用标准方法配置扩展模块。 + 这个特性允许附加模块(例如过程语言)向PostgreSQL添加系统通常不认识的参数。这样便能以标准方式配置扩展模块。 - 自定义选项有两部分名称:一个扩展名,然后是一个句点,再然后是正确的参数名,就像 SQL 中的合格名称。一个示例是plpgsql.variable_conflict。 + 自定义选项的名称由两部分组成:扩展名称和参数名本身,中间用句点分隔,类似于 SQL 中的限定名。例如plpgsql.variable_conflict @@ -8440,7 +8163,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' PostgreSQL将接受任何两部分参数名称的设置。 这些变量被视为占位符,在定义它们的模块加载之前没有任何功能。 当加载扩展模块时,它将添加其变量定义并根据这些定义转换任何占位符值。 - 如果存在以其扩展名开头的任何未识别的占位符,将发出警告并删除这些占位符。 + 如果存在以其扩展名称开头的任何未识别的占位符,将发出警告。 @@ -8449,11 +8172,10 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 开发者选项 - 下面的参数目的是用在开发测试上, 并且永远不能用于生产数据库。 - 但是,它们中的一些能够用于帮助恢复严重损坏的数据库。 - 同样,它们被从示例postgresql.conf文件中排除。 - 请注意许多这些参数要求特殊的源代码编译标志才能工作。 - + 以下参数用于开发者测试,切勿用于生产数据库。不过,其中一些参数可用于辅助恢复严重损坏的数据库。 + 因此,它们未列入示例postgresql.conf文件。 + 请注意,许多参数需要特殊的源代码编译标志才能起作用。 + @@ -8466,7 +8188,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 允许将表空间创建为pg_tblspc内的目录,当CREATE TABLESPACE命令提供空位置字符串时。 + 当向CREATE TABLESPACE命令提供空的位置字符串时,允许将表空间创建为pg_tblspc内的目录。 这旨在允许测试主库和备库在同一台机器上运行的复制场景。这样的目录可能会混淆备份工具,因为这些工具期望在该位置只找到符号链接。 只有超级用户能更改这个设置。 @@ -8483,8 +8205,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 允许修改系统表的结构以及对系统表进行某些其他风险操作。即使对于超级用户,这也通常是不允许的。 - 不明智地使用此设置可能导致无法检索的数据丢失或严重损坏数据库系统。 + 允许修改系统表的结构以及对系统表进行某些其他风险操作。否则,即使超级用户也不允许执行这些操作。 + 不明智地使用此设置可能导致无法挽回的数据丢失或严重损坏数据库系统。 只有超级用户能更改这个设置。 @@ -8527,14 +8249,14 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 当设置为1时,每个系统目录缓存条目在第一个可能的机会时失效,不管任何使之无效的事情是否真的发生。 - 作为结果,系统目录的缓存被有效地禁用,因此服务器将运行得非常缓慢。 - 较高的值递归地运行缓存失效,这样会更慢,而且只用于测试缓存逻辑自身。 + 当设置为1时,每个系统目录缓存条目都会在最早可能的时刻被置为无效,无论是否真的发生了使其失效的事件。 + 这实际上禁用了系统目录缓存,因此服务器将运行得非常缓慢。 + 较高的值递归地运行缓存失效,这样会更慢,而且仅对测试缓存逻辑本身有用。 默认值0选择正常的目录缓存行为。 - 当试图触发涉及并发目录更改的难以复现的错误时,此参数非常有用,但除此之外它不太被需要。 + 当试图触发涉及并发目录更改的难以复现的错误时,此参数非常有用,但除此之外很少需要使用它。 详情请参见源码文件inval.cpg_config_manual.h @@ -8596,7 +8318,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据的时有用。这个参数在会话开始之后不能被更改。 + 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据时有用。这个参数在会话开始之后不能被更改。 @@ -8611,8 +8333,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 执行认证过程后启动新服务器进程时延迟的时间量。这是为了给开发者们一个机会在一个服务器进程上附加一个调试器。 - 如果指定值时没有单位,则以秒为单位。0值(默认值)禁用延迟。这个参数在会话开始之后不能被更改。 + 新服务器进程启动并完成认证过程之后的延迟时间。这旨在给开发者一个机会,用调试器附加到服务器进程上。 + 如果指定值时没有单位,则以秒为单位。零值(默认值)禁用延迟。这个参数在会话开始之后不能被更改。 @@ -8627,8 +8349,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 在新服务器进程分叉后,在进行认证过程之前,延迟的时间量。这是为了给开发者们一个机会在一个服务器进程上附加一个调试器来跟踪认证过程中的不当行为。 - 如果指定值时没有单位,则以秒为单位。0值(默认值)禁用延迟。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 新服务器进程刚刚派生之后、执行认证过程之前的延迟时间。这旨在给开发者一个机会,用调试器附加到服务器进程上,跟踪认证过程中的异常行为。 + 如果指定值时没有单位,则以秒为单位。零值(默认值)禁用延迟。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -8643,7 +8365,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 + 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 @@ -8675,7 +8397,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果打开,发出在排序操作中的资源使用的相关信息。只有在编译PostgreSQL时定义了TRACE_SORT宏, 这个参数才可用(不过,当前在默认情况下就定义了TRACE_SORT)。 + 如果开启,输出排序操作中的资源使用信息。只有在编译PostgreSQL时定义了TRACE_SORT宏, 这个参数才可用(不过,当前在默认情况下就定义了TRACE_SORT)。 @@ -8690,7 +8412,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。对每一种锁类型,已授权锁和等待锁的计数也会被一起转储。一个日志文件输出的示例如下: + 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。还会转储每种锁类型已授予的锁数、等待的锁数,以及它们的总数。一个日志文件输出的示例如下: LOG: LockAcquire: new: lock(0xb7acd844) id(24688,24696,0,0,0,1) grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0 @@ -8762,7 +8484,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果设置,不会跟踪小于这个 OID 的锁(用于避免在系统表上的输出)。 + 如果设置,不会跟踪 OID 小于此值的表上的锁(用于避免在系统表上的输出)。 @@ -8838,7 +8560,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,被修改的任何缓冲区的整页镜像及其WAL记录都被加入到记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 + 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,与该 WAL 记录相关的所有已修改缓冲区的整页镜像都会被添加到该记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 @@ -8846,8 +8568,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 或者设置为逗号分隔的资源管理器列表,以仅检查来自这些资源管理器的记录。目前支持的资源管理器有 heapheap2btreehashgingistsequencespgist、 - bringeneric。扩展可以定义额外的资源管理器。只有超级用户和具有 - 适当SET权限的用户才能更改此设置。 + bringeneric。只有超级用户才能更改此设置。 @@ -8882,11 +8603,11 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 在读取过程中检测到校验和失败通常会导致PostgreSQL报告错误,中止当前事务。 - 将ignore_checksum_failure设置为on会导致系统忽略失败(但仍然报告警告),并继续处理。 - 这种行为可能导致崩溃,传播或隐藏损坏,或其他严重问题。然而,它可能允许您跳过错误, - 并检索可能仍然存在于表中的未损坏的元组,如果块头仍然正常。如果头部损坏,即使启用此选项也会报告错误。 - 默认设置为off。 - 只有超级用户能更改这个设置。 + 将ignore_checksum_failure设置为 on 会使系统忽略失败(但仍报告警告),并继续处理。 + 这种行为可能导致崩溃、传播或隐藏损坏,或引发其他严重问题。 + 但是,如果块首部仍然正常,它可能允许你跳过错误,检索表中可能仍然存在的未损坏元组。 + 如果首部损坏,即使启用此选项也会报告错误。默认设置为off。 + 只有超级用户才能更改此设置。 @@ -8903,7 +8624,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 检测到损坏的页面头通常会导致PostgreSQL报告错误,中止当前事务。 将zero_damaged_pages设置为on会导致系统报告警告,将内存中的损坏页面清零,并继续处理。 - 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许您跳过错误,并从表中可能存在的未损坏页面中检索行。 + 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许你跳过错误,并从表中可能存在的未损坏页面中检索行。 如果由于硬件或软件错误而发生损坏,这对于恢复数据很有用。通常在放弃从表的损坏页面恢复数据的希望之前,不应将其设置为on。 清零的页面不会强制写入磁盘,因此建议在再次关闭此参数之前重新创建表或索引。默认设置为off。 只有超级用户能更改这个设置。 @@ -8923,9 +8644,9 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 如果设置为 off(默认值),则在恢复期间检测到引用无效页面的 WAL 记录会导致 PostgreSQL 引发 PANIC 级别错误,中止恢复。 将ignore_invalid_pages设置为on会导致系统忽略 WAL 记录中的无效页面引用(但仍报告警告),并继续恢复。 - 此行为可能会导致崩溃、数据丢失、传播或隐藏腐败,或其他严重问题。 - 但是,它可能允许你通过 PANIC 级错误,完成恢复,并启动服务器。 - 参数只能在服务器启动时设置。它仅在恢复期间或待机模式下生效。 + 此行为可能会导致崩溃、数据丢失、传播或隐藏损坏,或其他严重问题。 + 但是,它可能允许你跳过 PANIC 级错误,完成恢复,并启动服务器。 + 参数只能在服务器启动时设置。它仅在恢复期间或备库模式下生效。 @@ -8940,7 +8661,8 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果LLVM有所需要的功能,用GDB注册所生成的函数。这会让调试更加容易。默认设置是off。只有超级用户可以在会话开始时更改这个参数,并且在会话内完全不能更改它。 + 如果 LLVM 具有所需的功能,则向GDB注册生成的函数。 + 这会让调试更加容易。默认设置为off。只有超级用户才能在会话开始时更改此参数,并且在会话内完全不能更改它。 @@ -8956,7 +8678,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 将生成的LLVM IR写入文件系统,位于内。 - 这仅对于在JIT实现内部工作时有用。默认设置为off。 + 这仅对开发 JIT 的内部实现有用。默认设置为off。 只有超级用户能更改这个设置。 @@ -8987,10 +8709,9 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果LLVM有所需的功能,发出需要的数据以允许perf对JIT生成的函数画像。 - 这会写出文件到~/.debug/jit/中,如果需要,由用户负责对其执行清除。 - 默认设置是off。 - 只有超级用户可以在会话开始时更改这个参数,并且在会话内完全不能更改它。 + 如果 LLVM 具有所需的功能,则输出让perf对 JIT 生成的函数进行性能分析所需的数据。 + 这会将文件写入~/.debug/jit/;用户应在需要时自行清理。 + 默认设置为off。只有超级用户才能在会话开始时更改此参数,并且在会话内完全不能更改它。 @@ -9020,8 +8741,8 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 当设置为on时,这是默认值,PostgreSQL将在后端崩溃后自动删除临时文件。 - 如果禁用,文件将被保留,并且也许可用于调试,例如。 + 当设置为on(默认值)时,PostgreSQL将在后端崩溃后自动删除临时文件。 + 如果禁用,文件将被保留,例如可用于调试。 重复的崩溃可能会导致无用文件的积累。 该参数只能在postgresql.conf文件中或服务器命令行中设置。 @@ -9041,12 +8762,12 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 短选项 - 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,并且它们作为一个单字母选项存在并不表示它们会被大量使用。 + 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,它们以单字母选项的形式存在,并不一定表示鼓励频繁使用这些选项。 - 短选项键 + 短选项对照 diff --git a/zh/14/datatype.sgml b/zh/14/datatype.sgml index 9f720564..41b70de0 100644 --- a/zh/14/datatype.sgml +++ b/zh/14/datatype.sgml @@ -151,7 +151,7 @@ line - 平面上的无限长的线 + 平面上的无限直线 @@ -163,19 +163,19 @@ macaddr - MAC(Media Access Control)地址 + MAC(媒体访问控制)地址 macaddr8 - MAC(Media Access Control)地址(EUI-64格式) + MAC(媒体访问控制)地址(EUI-64格式) money - 货币数量 + 货币额 @@ -183,7 +183,7 @@ s) ] decimal [ (p, s) ] - 可选择精度的精确数字 + 可选择精度的精确数值 @@ -195,7 +195,7 @@ pg_lsn - PostgreSQL日志序列号类型 + PostgreSQL 日志序列号 @@ -273,13 +273,13 @@ tsquery - 文本搜索查询 + 文本检索查询 tsvector - 文本搜索文档 + 文本检索文档 @@ -420,14 +420,14 @@
- 数字类型常量的语法在里描述。数字类型有一整套对应的数学操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 + 数字类型常量的语法在里描述。数字类型有一整套对应的算术操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 整数类型 - 整数 + integer @@ -440,7 +440,7 @@ int4 - 整数 + integer @@ -460,11 +460,11 @@ - 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。而只有在integer的范围不够的时候才使用bigint。 + 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。bigint则设计用于integer的范围不够的情况。 - SQL只声明了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在许多其它SQL数据库系统中使用。 + SQL只规定了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在某些其他SQL数据库系统中使用。 @@ -473,11 +473,11 @@ 任意精度数值 - 数字(数据类型) + numeric(数据类型) - 任意精度数字 + 任意精度数值 @@ -523,8 +523,8 @@ NUMERIC - 在numeric类型声明中可显式指定的最大精度为 1000。 - 无约束的numeric列受 + 在NUMERIC类型声明中可显式指定的最大精度为 1000。 + 无约束的NUMERIC列受 中所述限制的约束。 @@ -532,13 +532,7 @@ NUMERIC 如果要存储的值的小数位数大于该列声明的小数位数,系统会把该值 舍入到指定的小数位数。然后,如果小数点左侧的位数超过了声明的 - 精度减去声明的小数位数,就会报错。例如,声明为 - -NUMERIC(3, 1) - - 的列会把值舍入到 1 位小数,并且可以存储 -99.9 到 99.9 - 之间(含边界)的值。 - + 精度减去声明的小数位数,就会报错。 @@ -551,18 +545,18 @@ NUMERIC(3, 1) - infinity - numeric (数据类型) + 无穷大 + numeric(数据类型) NaN - 非数字 + 非数 - 非数字 - 数字(数据类型) + 非数 + numeric(数据类型) @@ -649,7 +643,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 双精度 + double precision @@ -659,7 +653,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; float8 - 双精度 + double precision @@ -712,8 +706,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; 默认情况下,浮点值会以最短且精确的十进制表示形式输出; - 生成的十进制值比同一二进制精度下任何其他可表示值都更接近真实 - 存储的二进制值。(不过,为了避免输入例程普遍存在的一个错误, + 所生成的十进制值与实际存储的二进制值之间的距离,小于它与任何其他可用相同二进制精度表示的值之间的距离。(不过,为了避免输入例程普遍存在的一个错误, 即未能正确遵守舍入到最近偶数规则,当前输出值绝不会 恰好位于两个可表示值的正中间。) 对于float8值,最多使用 17 位有效十进制数字; @@ -722,14 +715,14 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 生成这种最短且精确的输出格式,比历史上的圆整格式要快得多。 + 生成这种最短且精确的输出格式,比历史上的舍入格式要快得多。 为了兼容旧版本PostgreSQL生成的输出, 并允许降低输出精度,可以使用 - 参数改为选择圆整后的 + 参数改为选择舍入后的 十进制输出。将该参数设置为 0 会恢复之前的默认行为,也就是把值 舍入为 6 位(对于float4)或 15 位 (对于float8)有效十进制数字。设置为负值会 @@ -743,7 +736,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 过去那些需要精确值的应用,往往必须把 + 过去那些需要精确值的应用,必须把 设置为 3 才能获得它们。 为了在版本之间获得最大兼容性,这类应用应继续这样做。 @@ -751,12 +744,12 @@ FROM generate_series(-3.5, 3.5, 1) as x; 无穷大 - 浮点型 + 浮点 - 非数字 - 浮点型 + 非数 + 浮点 @@ -828,13 +821,13 @@ FROM generate_series(-3.5, 3.5, 1) as x; - auto-increment + 自动递增 serial - sequence - and serial type + 序列 + 与 serial 类型 @@ -887,7 +880,7 @@ ALTER SEQUENCE tablename_ - 要向 serial 列插入序列中的下一个值,应指定让该列 + 要向 serial 列插入序列中的下一个值,应指定让serial列 使用其默认值。这既可以通过在 INSERT 语句的 列表中省略该列来实现,也可以通过使用 DEFAULT 关键字来实现。 @@ -963,7 +956,7 @@ ALTER SEQUENCE tablename_ SELECT '12.34'::float8::numeric::money; - 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有圆整错误。 + 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有舍入误差。 @@ -975,7 +968,7 @@ SELECT '52093.89'::money::numeric::float8; 一个 money 值除以一个整数值时,会朝零方向截去小数 - 部分。要得到圆整结果,可以除以一个浮点值,或者在除法前先把 + 部分。要得到舍入后的结果,可以除以一个浮点值,或者在除法前先把 money 转换为 numeric,再在除法后转换回 money(如果要避免精度丢失风险,后一种做法更好)。 当一个 money 值被另一个 money 值除时, @@ -994,12 +987,12 @@ SELECT '52093.89'::money::numeric::float8; - string + 字符串 - 字符 + character @@ -1034,7 +1027,7 @@ SELECT '52093.89'::money::numeric::float8; character(n), char(n) - 定长,空白填充 + 定长,空格填充 text @@ -1075,7 +1068,7 @@ SELECT '52093.89'::money::numeric::float8; char(n) 分别是 character varying(n)character(n) 的别名。 - 如果指定了长度,n 必须大于 0,且不能 + 如果指定了长度,该长度必须大于零,且不能 超过 10485760。character 若不带长度说明则等同于 character(1)。如果 character varying 不带长度说明,则该类型接受任意长度的字符串。这是 @@ -1106,7 +1099,7 @@ SELECT '52093.89'::money::numeric::float8; - 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储代码为零的字符(有时称为NUL)。有关更多信息,请参阅。 + 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储编码值为零的字符(有时称为NUL)。有关更多信息,请参阅 @@ -1125,7 +1118,7 @@ SELECT '52093.89'::money::numeric::float8; - 这三种类型之间没有性能差别,除了使用空白填充类型时会占用更多存储 + 这三种类型之间没有性能差别,除了使用空格填充类型时会占用更多存储 空间,以及在写入带长度约束的列时需要少量额外 CPU 周期来检查长度。 虽然在某些其他数据库系统中,character(n) 可能有一定性能优势,但在 PostgreSQL @@ -1160,7 +1153,7 @@ INSERT INTO test2 VALUES ('ok'); INSERT INTO test2 VALUES ('good '); INSERT INTO test2 VALUES ('too long'); ERROR: value too long for type character varying(5) -INSERT INTO test2 VALUES ('too long'::varchar(5)); -- explicit truncation +INSERT INTO test2 VALUES ('too long'::varchar(5)); -- 显式截断 SELECT b, char_length(b) FROM test2; b | char_length @@ -1181,15 +1174,13 @@ SELECT b, char_length(b) FROM test2; PostgreSQL 中还有两种固定长度字符类型, - 如 所示。它们 - 并非供一般用途使用,而仅用于内部系统目录。name - 类型用于存储标识符。它的长度目前定义为 64 字节 - (63 个可用字符加结束符),但在 C 源代码中 - 应使用常量 NAMEDATALEN 来引用。这个长度是在 - 编译时设定的(因此可以针对特殊用途调整);默认最大长度在未来 - 版本中可能会变化。类型 "char"(注意带引号)不同于 - char(1),因为它只使用 1 个字节存储,因此只能保存 - 单个 ASCII 字符。它在系统目录中被用作一种简单的枚举类型。 + 如 所示。name + 类型用于在内部系统目录中存储标识符,并非供一般用户使用。 + 它的长度目前定义为 64 字节(63 个可用字符加结束符),但在 C + 源代码中应使用常量 NAMEDATALEN 来引用。这个长度是在 + 编译时设定的(因此可以针对特殊用途调整);默认最大长度在未来版本中可能会变化。 + 类型 "char"(注意带引号)不同于 char(1),因为它只使用 + 1 个字节存储。它在系统目录中被用作一种简单的枚举类型。 @@ -1284,7 +1275,7 @@ SELECT b, char_length(b) FROM test2; 开头(以便与转义格式区分)。在某些上下文中,这个开头的反斜线 可能需要通过双写进行转义(见 )。作为输入时,十六进制数字 - 可以使用大写或小写,并且在两个数字组成的一组之间允许出现空白 + 可以使用大写或小写,并且每两个数字组成一组,组与组之间允许出现空白 (但组内以及起始的 \x 序列中不能有空白)。 十六进制格式与大量外部应用和协议兼容,并且通常比转义格式转换得 更快,因此更推荐使用。 @@ -1348,7 +1339,7 @@ SELECT '\xDEADBEEF'::bytea; 0 - 0字节 + 零值字节 '\000' '\000'::bytea \x00 @@ -1493,10 +1484,10 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; time - 不带时区的时间 + time without time zone - 带时区的时间 + time with time zone timestamp @@ -1505,13 +1496,13 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; timestamptz - 带时区的时间戳 + timestamp with time zone - 不带时区的时间戳 + timestamp without time zone - 间隔 + interval 时间跨度 @@ -1595,7 +1586,7 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; - SQL 要求仅写 timestamp 时,应等效于 + SQL 标准要求仅写 timestamp 时,应等效于 timestamp without time zone,而 PostgreSQL 也遵循这种行为。 timestamptz 被接受为 @@ -1676,7 +1667,7 @@ MINUTE TO SECOND 其中 p 是可选的精度说明,给出秒字段中 保留的小数位数。精度可用于 timetimestampinterval 类型, - 范围是 0 到 6。这与前文描述的取值一致。如果在常量声明中没有指定 + 范围是 0 到 6。如果在常量声明中没有指定 精度,则默认采用该字面值本身的精度(但不超过 6 位)。 @@ -1705,7 +1696,7 @@ MINUTE TO SECOND 1999-01-08 - ISO 8601; 任何模式下的1月8日 + ISO 8601; 任何模式下的1月8日 (推荐格式) @@ -1741,27 +1732,27 @@ MINUTE TO SECOND 99-Jan-08 - YMD模式中的1月8日,否则错误 + YMD模式中的1月8日,否则报错 08-Jan-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 Jan-08-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 19990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 1999.008 - 年和一年中的日子 + 年和一年中的第几天 J2451187 @@ -1783,10 +1774,10 @@ MINUTE TO SECOND time - 无时区的时间 + time without time zone - 带时区的时间 + time with time zone @@ -1865,11 +1856,11 @@ MINUTE TO SECOND 040506+0730 - ISO 8601,以分数小时形式给出 UTC 偏移 + ISO 8601,时区的 UTC 偏移不是整小时 040506+07:30:00 - UTC偏移量指定为秒(ISO 8601中不允许) + UTC 偏移精确到秒(ISO 8601中不允许) 04:05:06 PST @@ -1946,11 +1937,11 @@ MINUTE TO SECOND - 带时区的时间戳 + timestamp with time zone - 无时区的时间戳 + timestamp without time zone @@ -1975,29 +1966,12 @@ January 8 04:05:06 1999 PST 也被支持。 - - SQL 标准通过时间后面是否带有 - +- 符号以及时区偏移,来区分 - timestamp without time zone 和 - timestamp with time zone 常量。因此,根据标准, - - + 按照SQL标准,timestamp without time zonetimestamp with time zone字面量的区别在于,时间后是否有+-符号及其后的时区偏移。因此,按照该标准, TIMESTAMP '2004-10-19 10:23:54' - - - 属于 timestamp without time zone,而 - - +timestamp without time zone,而 TIMESTAMP '2004-10-19 10:23:54+02' - - - 属于 timestamp with time zone。 - PostgreSQL 在确定字符串类型之前从不检查 - 其内容,因此会把上述两个值都视为 - timestamp without time zone。要确保一个常量被视为 - timestamp with time zone,应为其指定正确的显式类型: - - +timestamp with time zone。 + PostgreSQL在确定字符串字面量的类型之前,从不检查其内容,因此会把上述两者都视为timestamp without time zone。为确保字面量被视为timestamp with time zone,应为它显式指定正确类型: TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' @@ -2042,12 +2016,12 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' time - constants + 常量 date - constants + 常量 @@ -2079,12 +2053,12 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' infinity - date, timestamp, interval + date, timestamp 晚于所有其他时间戳 -infinity - date, timestamp, interval + date, timestamp 早于所有其他时间戳 @@ -2148,13 +2122,13 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' date 输出格式 - formatting + 格式化 time 输出格式 - formatting + 格式化 @@ -2187,7 +2161,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' ISO - ISO 8601, SQL标准 + ISO 8601,SQL 标准 1997-12-17 07:37:16-08 @@ -2218,7 +2192,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' - SQL和POSTGRES风格中,如果DMY域顺序被指定,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。 + SQL和POSTGRES风格中,如果指定了 DMY 字段顺序,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。
@@ -2266,10 +2240,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 时区有通用的字母缩写,就会显示该缩写;否则会以 ISO 8601 基本 格式的有符号数字偏移显示 (hh 或 - hhmm)。这些样式中显示的字母缩写, - 取自当前由 运行时参数选中的 IANA - 时区数据库条目;它们不受 - 设置影响。 + hhmm)。 @@ -2288,7 +2259,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 时区 - time zone + 时区 @@ -2373,8 +2344,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 除了时区名称和缩写之外, PostgreSQL 还接受 POSIX 风格的 时区说明,见 。 - 这个选项通常不如使用具名时区更合适,但如果没有可用的 IANA - 时区条目,它可能就是必需的。 + 这个选项通常不如使用具名时区更合适,但如果没有合适的 IANA 时区条目可用,它可能就是必需的。 @@ -2389,19 +2359,12 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 中午(UTC-5),无论当天名义上是否正在实行夏令时。 - - - POSIX 风格时区说明中的符号,其含义与 ISO 8601 日期时间值中的 - 符号正好相反。例如,与 - 2014-06-04 12:00+04 对应的 POSIX 风格时区写法 - 会是 UTC-4。 - - + 更复杂的是,一些司法辖区在不同时间使用同一时区缩写来表示不同的 UTC 偏移;例如在莫斯科,MSK 在某些年份表示 - UTC+3,在另一些年份则表示 UTC+4。PostgreSQL + UTC+3,在另一些年份则表示 UTC+4。PostgreSQL 会按照该缩写在所给日期上的含义(或最近一次的含义)来解释这类缩写; 但与上面的 EST 例子一样,这并不一定等同于该日期的 当地民用时间。 @@ -2417,7 +2380,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 时区名称和缩写并不是硬编码在服务器中的;它们来自安装目录下 .../share/timezone/ 和 - .../share/timezonesets/ 子目录中的数据 + .../share/timezonesets/ 子目录中的配置文件 (见 )。 @@ -2455,13 +2418,13 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' - interval值可以使用下列语法书写: + interval值可以使用下列详细语法书写: @ quantity unit quantity unit... direction - 其中quantity是一个数字(很可能是有符号的); + 其中quantity是一个数字(可以带有符号); unitmicrosecondmillisecondsecondminutehourday、 @@ -2495,7 +2458,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' P quantity unit quantity unit ... T quantity unit ... 字符串必须以 P 开头,并且可以包含一个 - T 来引出一天中时间单位。可用的单位缩写见 + T 来引出一天中的时间单位。可用的单位缩写见 。单位可以省略, 也可以按任意顺序出现,但小于一天的单位必须出现在 T 之后。特别是,M 的含义 @@ -2534,7 +2497,7 @@ P quantity unit M - 分钟 (在时间部分中) + 分钟(在时间部分中) S @@ -2602,7 +2565,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; '1.5 weeks''01:02:03.45'。然而,由于 interval 在内部只存储整数字段,小数值必须转换成更小 - 的单位。大于月的单位的小数部分会被舍入为整数个月,例如 + 的单位。大于月的单位的小数部分会被截断为整数个月,例如 '1.5 years' 会变成 '1 year 6 mons'。周和天的小数部分会在假定 每月 30 天、每天 24 小时的前提下,计算成整数天和微秒,例如 @@ -2639,7 +2602,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; P1Y2M3DT4H5M6S - 带标志符的ISO 8601 格式:含义同上 + ISO 8601 带标志符的格式:含义同上 P0001-02-03T04:05:06 @@ -2657,7 +2620,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; interval 输出格式 - formatting + 格式化 @@ -2706,7 +2669,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; iso_8601 风格的输出符合 ISO 8601 标准 - 4.4.3.2 节描述的带标志符格式。 + 4.4.3.2 节描述的带标志符的格式
@@ -2757,7 +2720,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; 布尔类型 - Boolean + 布尔 数据类型 @@ -2868,15 +2831,15 @@ SELECT * FROM test1 WHERE a; 数据类型 - enumerated (enum) + 枚举(enum) - enumerated types + 枚举类型 - 枚举(enum)类型是由一个静态、值的有序集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的日期,或者一个数据的状态值集合。 + 枚举(enum)类型是由一个静态的有序值集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的各天,或者一个数据的状态值集合。 @@ -2985,7 +2948,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 实现细节 - 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空格也是有意义的。 + 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空白也是有意义的。 @@ -2997,7 +2960,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 从内部枚举值到文本标签的翻译被保存在系统目录pg_enum中。可以直接查询该目录。 + 从内部枚举值到文本标签的转换关系被保存在系统目录pg_enum中。直接查询该目录可能会有所帮助。 @@ -3042,13 +3005,13 @@ SELECT person.name, holidays.num_weeks FROM person, holidays lseg32字节有限线段 - [(x1,y1),(x2,y2)] + ((x1,y1),(x2,y2)) box 32字节 矩形框 - (x1,y1),(x2,y2) + ((x1,y1),(x2,y2)) path @@ -3072,7 +3035,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays circle 24字节 - <(x,y),r>(中心点和半径) + <(x,y),r>(圆心和半径) @@ -3085,7 +3048,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 我们提供了丰富的函数和操作符来进行各种几何操作,例如缩放、平移、 - 旋转以及计算相交等,详见 。 + 旋转以及求交等,详见 @@ -3096,7 +3059,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 点是几何类型的基本二维构造块。用下面的语法描述point类型的值: + 点是几何类型的基本二维构造块。用下面任一种语法描述point类型的值: ( x , y ) @@ -3112,14 +3075,14 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线 + 直线 line - 线由线性方程Ax + By + C = 0 + 直线由线性方程Ax + By + C = 0 表示,其中AB不能同时为零。类型line 的值采用以下形式输入和输出: @@ -3139,7 +3102,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays (x1,y1)(x2,y2) - 是线上不同的两点。 + 是直线上不同的两点。 @@ -3155,7 +3118,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线段用一对线段的端点来表示。lseg类型的值用下面的语法声明: + 线段用一对线段的端点来表示。lseg类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ( x2 , y2 ) ] @@ -3179,15 +3142,15 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 方框 - box (data type) + box(数据类型) - rectangle + 矩形 - 方框用其对角的点对表示。box类型的值使用下面的语法指定: + 方框用其对角的点对表示。box类型的值使用下面任一种语法指定: ( ( x1 , y1 ) , ( x2 , y2 ) ) @@ -3206,7 +3169,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 在输入时可以提供任意两个对角,但是值将根据需要被按顺序记录为右上角和左下角。 + 在输入时可以提供任意两个对角,但是值将根据需要被重新排列,并依次存储为右上角和左下角。 @@ -3214,7 +3177,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 路径 - path (data type) + path(数据类型) @@ -3222,7 +3185,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - path类型的值用下面的语法声明: + path类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ... , ( xn , yn ) ] @@ -3232,11 +3195,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays x1 , y1 , ... , xn , yn - 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被忽略时,路径将被假定为封闭。 + 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被省略时,路径将被假定为封闭。 - 路径的输出使用第一种或第二种语法。 + 路径的输出视情况使用第一种或第二种语法。 @@ -3260,7 +3223,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - polygon类型的值用下列语法声明: + polygon类型的值用下列任一种语法指定: ( ( x1 , y1 ) , ... , ( xn , yn ) ) @@ -3285,7 +3248,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 圆由一个圆心和一个半径代表。circle类型的值用下面的语法指定: + 圆由一个圆心和一个半径代表。circle类型的值用下面任一种语法指定: < ( x , y ) , r > @@ -3308,7 +3271,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 网络地址类型 - network + 网络 数据类型 @@ -3365,8 +3328,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 在对 inetcidr 数据类型排序时,IPv4 - 地址总是排在 IPv6 地址之前,包括那些封装在 IPv6 地址中或映射到 - IPv6 地址中的 IPv4 地址,例如 ::10.2.3.4 或 + 地址总是排在 IPv6 地址之前,即使后者是封装或映射 IPv4 地址所得的 IPv6 地址,例如 ::10.2.3.4::ffff:10.4.3.2 @@ -3522,7 +3484,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - <type>inet</type> vs. <type>cidr</type> + <type>inet</type> 与 <type>cidr</type> inetcidr 两种数据类型的本质区别在于: @@ -3548,12 +3510,12 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - MAC地址 + MAC 地址 macaddr - macaddr类型存储 MAC 地址,也就是以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: + macaddr类型存储 MAC 地址,例如以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: '08:00:2b:01:02:03' @@ -3587,11 +3549,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays <type>macaddr8</type> - macaddr8 (data type) + macaddr8(数据类型) - MAC地址(EUI-64格式) + MAC 地址(EUI-64 格式) macaddr @@ -3718,31 +3680,31 @@ SELECT * FROM test; - 一个 bit 串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 + 一个位串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 开销,具体取决于串的长度。(不过,长值可能会被压缩或移到行外存储, 与 中对字符串的说明相同。) - 文本搜索类型 + 文本检索类型 - 全文搜索 + 全文检索 数据类型 - 文本搜索 + 文本检索 数据类型 - PostgreSQL 提供了两种专为支持全文搜索而 - 设计的数据类型。所谓全文搜索,是指在一组自然语言 + PostgreSQL 提供了两种专为支持全文检索而 + 设计的数据类型。所谓全文检索,是指在一组自然语言 文档中查找最匹配某个 查询的文档。tsvector 类型以 - 适合文本搜索的优化形式表示文档,tsquery 类型则表示 + 适合文本检索的优化形式表示文档,tsquery 类型则表示 文本查询。关于这一功能的详细解释见 ; 相关函数和操作符的概览见 @@ -3757,7 +3719,7 @@ SELECT * FROM test; tsvector 值是一个排好序且互不重复的 词位(lexeme)列表,这些词已经过 - 规范化,以便把同一单词的不同变体合并起来 + 正规化,以便把同一单词的不同变体合并起来 (详见 )。排序和去重会在输入时自动 完成,如下例所示: @@ -3816,12 +3778,12 @@ SELECT 'a:1A fat:2B,4C cat:5D'::tsvector; 权重通常用于反映文档结构,例如把标题中的词和正文中的词区分开来。 - 文本搜索排序函数可以为不同的权重标记分配不同优先级。 + 文本检索排序函数可以为不同的权重标记分配不同优先级。 必须认识到,tsvector 类型本身并不会执行任何词语 - 规范化;它假定输入的词已经按照应用需求完成规范化。例如: + 正规化;它假定输入的词已经按照应用需求完成正规化。例如: SELECT 'The Fat Rats'::tsvector; @@ -3830,9 +3792,9 @@ SELECT 'The Fat Rats'::tsvector; 'Fat' 'Rats' 'The' - 对于大多数英文全文搜索应用来说,上述词会被视为尚未规范化,但 + 对于大多数英文全文检索应用来说,上述词会被视为尚未正规化,但 tsvector 并不在意。原始文档文本通常应先经过 - to_tsvector,以按搜索需要对词语进行规范化: + to_tsvector,以按检索需要对词语进行正规化: SELECT to_tsvector('english', 'The Fat Rats'); @@ -3921,9 +3883,9 @@ SELECT 'super:*'::tsquery; 引号的使用规则与前面介绍 tsvector 时相同;同样, - 与 tsvector 一样,任何需要的词语规范化都必须在 + 与 tsvector 一样,任何需要的词语正规化都必须在 转换为 tsquery 类型之前完成。to_tsquery - 函数很适合用来实现这种规范化: + 函数很适合用来实现这种正规化: SELECT to_tsquery('Fat:ab & Cats'); @@ -3949,8 +3911,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); ---------------+------------ 'postgradu':1 | 'postgr':* - 因而它能够匹配其带前缀的后继形式 - postgraduate。 + 因而它能够匹配postgraduate 词干化后的形式。 @@ -3968,7 +3929,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); uuid 数据类型用于存储由 RFC 4122、 ISO/IEC 9834-8:2005 及相关标准定义的通用唯一标识符(UUID)。 - (有些系统把这种数据类型称为全局唯一标识符,或 GUID, + (有些系统把这种数据类型称为全局唯一标识符,或 GUID GUID。)这种标识符是一个 128 位的量,由某种算法生成,该算法被设计为使同一算法在已知宇宙中 被其他人生成出相同标识符的概率极低。因此,对于分布式系统而言, @@ -3985,7 +3946,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11 PostgreSQL 也接受其他输入形式:可以使用 - 大写字母、用花括号包围标准格式、忽略部分或全部连字符,或者在任意 + 大写字母、用花括号包围标准格式、省略部分或全部连字符,或者在任意 4 位分组后额外加上连字符。例如: A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11 @@ -4067,7 +4028,7 @@ xml 'bar' 反向操作,也就是从 xml 生成字符串值,则使用函数 xmlserializexmlserialize -XMLSERIALIZE ( { DOCUMENT | CONTENT } value AS type [ [ NO ] INDENT ] ) +XMLSERIALIZE ( { DOCUMENT | CONTENT } value AS type ) type 可以是 charactercharacter varying 或 @@ -4076,18 +4037,14 @@ XMLSERIALIZE ( { DOCUMENT | CONTENT } value AS PostgreSQL 也允许你直接进行类型转换。 - - INDENT 选项会让结果以美化格式输出,而 - NO INDENT(默认值)则只输出原始输入字符串。 - 直接转换为字符类型时,也会得到原始字符串。 - + 当字符串值在不经过 XMLPARSEXMLSERIALIZE 的情况下与 xml 类型互相转换时, 选择 DOCUMENT 还是 CONTENT - 由会话配置参数 XML option - XML option 决定,可以使用 + 由会话配置参数 XML 选项 + XML 选项 决定,可以使用 标准命令设置: SET XML OPTION { DOCUMENT | CONTENT }; @@ -4104,20 +4061,20 @@ SET xmloption TO { DOCUMENT | CONTENT }; 编码处理 - 在客户端、服务器以及其间传输的 XML 数据上处理多字符编码时, + 在客户端、服务器以及其间传输的 XML 数据上处理多种字符编码时, 必须格外小心。使用文本模式向服务器发送查询并把查询结果返回给 - 客户端时,PostgreSQL 会将客户端与 + 客户端时(这是通常使用的模式),PostgreSQL 会将客户端与 服务器之间传输的所有字符数据转换为目标端的字符编码,参见 。这也包括表示 XML 值的字符串,如上例 所示。这通常意味着,由于字符数据在客户端和服务器之间传输时可能被 转换为其他编码,XML 数据中包含的编码声明可能会失效,因为内嵌的 编码声明本身并不会被修改。为处理这种情况,表示 xml 类型输入值的字符串中所包含的编码声明会被 - 忽略,其内容被假定为当前服务器编码。随后, + 忽略,其内容被假定为当前服务器编码。因此, 为了正确处理,客户端发出的 XML 数据字符串必须采用当前客户端编码。 客户端负责在将文档发送给服务器之前把它们转换为当前客户端编码, 或适当调整客户端编码。输出时,xml 类型值不会带有 - 编码声明,而客户端会假定所有数据都采用当前客户端编码。 + 编码声明,而客户端应假定所有数据都采用当前客户端编码。 @@ -4151,7 +4108,7 @@ SET xmloption TO { DOCUMENT | CONTENT }; xml 数据类型有些特殊,因为它不提供任何比较操作符。 这是因为对 XML 数据并不存在良定义且通用的比较算法。其结果是, - 你无法通过把某个 xml 值与搜索值比较来检索行。 + 你无法通过把某个 xml 列与搜索值比较来检索行。 因此,XML 值通常应伴随一个独立的键字段,例如 ID。另一种比较 XML 值的办法,是先把它们转换成字符串;但请注意,字符串比较对 XML 的比较需求通常帮助不大。 @@ -4159,14 +4116,14 @@ SET xmloption TO { DOCUMENT | CONTENT }; 由于 xml 数据类型没有可用的比较操作符,因此无法直接 - 在这种类型上创建索引。如果需要在 XML 中快速搜索,可行方案包括: + 在这种类型的列上创建索引。如果需要在 XML 中快速搜索,可行方案包括: 将表达式转换为字符串类型后为其建立索引,或者为某个 XPath 表达式 建立索引。当然,实际查询也必须相应调整为使用该被索引的表达式。 - PostgreSQL 的文本搜索功能也可用于加速 - XML 数据的全文搜索。不过,目前 PostgreSQL 发行版中仍缺少所需的 + PostgreSQL 的文本检索功能也可用于加速 + XML 数据的全文检索。不过,目前 PostgreSQL 发行版中仍缺少所需的 预处理支持。 @@ -4181,12 +4138,12 @@ SET xmloption TO { DOCUMENT | CONTENT }; 域类型 - domain + - data type - domain + 数据类型 + @@ -4198,13 +4155,13 @@ SET xmloption TO { DOCUMENT | CONTENT }; CREATE DOMAIN posint AS integer CHECK (VALUE > 0); CREATE TABLE mytable (id posint); -INSERT INTO mytable VALUES(1); -- works -INSERT INTO mytable VALUES(-1); -- fails +INSERT INTO mytable VALUES(1); -- 成功 +INSERT INTO mytable VALUES(-1); -- 失败 - 当底层类型的一个操作符或函数适用于一个域值时,域会被自动向下转换为底层类型。因此,mytable.id - 1的结果会被认为是类型integer而不是posint。我们可以写成(mytable.id - 1)::posint来把结果转换回posint,这会导致域的约束被重新检查。在这种情况下,如果该表达式被应用于一个值为1的id就会错误。把底层类型的值赋给域类型的一个字段或者变量不需要写显式的类型转换,但是域的约束将会被检查。 + 当底层类型的一个操作符或函数被应用于一个域值时,域会被自动向下转换为底层类型。因此,mytable.id - 1的结果会被认为是类型integer而不是posint。我们可以写成(mytable.id - 1)::posint来把结果转换回posint,这会导致域的约束被重新检查。在这种情况下,如果该表达式被应用于一个值为1的id就会报错。把底层类型的值赋给域类型的一个字段或者变量不需要写显式的类型转换,但是域的约束将会被检查。 @@ -4287,7 +4244,7 @@ INSERT INTO mytable VALUES(-1); -- fails 对象标识符(OID)在 PostgreSQL 内部被用作 若干系统表的主键。类型 oid 表示一个对象标识符。 - 此外还有若干 oid 的别名类型,统称为 + 此外还有若干 oid 的别名类型,其名称均形如 regsomething 给出了概要说明。 @@ -4364,14 +4321,14 @@ SELECT * FROM pg_attribute regconfig pg_ts_config - 文本搜索配置 + 文本检索配置 english regdictionary pg_ts_dict - 文本搜索字典 + 文本检索词典 simple @@ -4407,7 +4364,7 @@ SELECT * FROM pg_attribute regprocedure pg_proc - 函数与参数类型 + 带参数类型的函数 sum(int4) @@ -4443,7 +4400,7 @@ SELECT * FROM pg_attribute - 这些类型的输入函数允许在各个标记之间插入空白,并且会把大写字母 + 这些类型的输入函数允许在各个词元之间插入空白,并且会把大写字母 折叠为小写,双引号内除外;这样做是为了让语法规则更接近 SQL 中 书写对象名的方式。反过来,如果需要让输出成为有效的 SQL 标识符, 输出函数会自动加上双引号。例如,一个名为 Foo @@ -4518,8 +4475,7 @@ WHERE ... 它就会对被引用对象建立依赖。例如,如果某列的默认表达式是 nextval('my_seq'::regclass)PostgreSQL 就会知道该默认表达式依赖于 - 序列 my_seq,因此系统在删除该序列之前,必须先 - 移除该默认表达式。改用 + 序列 my_seq,因此系统不允许在尚未移除该默认表达式时删除序列。改用 nextval('my_seq'::text) 则不会建立依赖。 (regrole 是这一特性的例外:该类型的常量不允许出现在 存储表达式中。) @@ -4719,7 +4675,7 @@ WHERE ... anyarray - 表示一个函数可以接受任意数组数据类型(参见 + 表示一个函数可以接受任意数组数据类型(参见)。 @@ -4838,7 +4794,7 @@ WHERE ... unknown - 标识一种尚未解析出的类型,例如未修饰的字符串字面值。 + 标识一种尚未解析出的类型,例如未修饰的字符串字面值的类型。 @@ -4856,7 +4812,7 @@ WHERE ... voidrecord 用作结果类型 (如果函数被用作触发器或事件触发器,则也允许 triggerevent_trigger 作为结果类型)。 - 有些语言还支持借助多态伪类型来实现多态函数;详见 + 有些语言还支持借助上面列出的多态伪类型来实现多态函数;详见 diff --git a/zh/14/dict-int.sgml b/zh/14/dict-int.sgml index ccca92cc..63d7ccf8 100644 --- a/zh/14/dict-int.sgml +++ b/zh/14/dict-int.sgml @@ -1,16 +1,16 @@ - dict_int — 用于整数的示例全文搜索词典 + dict_int — 用于整数的示例全文检索词典 dict_int - dict_int是一个全文搜索附加词典模板的示例。 + dict_int是一个全文检索附加词典模板的示例。 引入这个示例词典是为了控制整数(有符号和无符号)的索引, - 使这类数字能够被索引,同时又避免唯一词的数量过度增长, + 使这类数字能够被索引,同时又避免不同词的数量过度增长, 因为那会严重影响搜索性能。 @@ -54,7 +54,7 @@ 用法 - 安装dict_int扩展后,会创建一个文本搜索模板 + 安装dict_int扩展后,会创建一个文本检索模板 intdict_template以及一个基于该模板、使用默认参数的词典 intdict。你可以修改这些参数,例如: @@ -77,7 +77,7 @@ mydb# select ts_lexize('intdict', '12345678'); 但在实际使用中,通常需要像所述那样, - 将它包含到某个文本搜索配置中。可能类似如下: + 将它包含到某个文本检索配置中。可能类似如下: ALTER TEXT SEARCH CONFIGURATION english diff --git a/zh/14/func.sgml b/zh/14/func.sgml index 2a1c07d9..b41e7343 100644 --- a/zh/14/func.sgml +++ b/zh/14/func.sgml @@ -10895,7 +10895,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 文本搜索函数和操作符 + 文本检索函数和操作符 全文检索 @@ -10903,7 +10903,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 文本搜索 + 文本检索 函数和操作符 @@ -10911,12 +10911,12 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple 以及 - 总结了为全文检索提供的函数和操作符。PostgreSQL的文本搜索功能的详细解释可参考。 + 总结了为全文检索提供的函数和操作符。PostgreSQL的文本检索功能的详细解释可参考
- 文本搜索操作符 + 文本检索操作符 @@ -11092,12 +11092,12 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple 除了这些专用操作符之外, 中所示的常用比较操作符也适用于tsvectortsquery类型。 - 这些操作符对文本搜索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。 + 这些操作符对文本检索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。
- 文本搜索函数 + 文本检索函数 @@ -11142,7 +11142,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple regconfig - 返回当前默认文本搜索配置的OID(由 所设定的). + 返回当前默认文本检索配置的 OID(由 设置)。 get_current_ts_config() @@ -11677,18 +11677,18 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 所有接受一个可选的regconfig参数的文本搜索函数在省略该参数时,会使用由指定的配置。 + 所有接受一个可选的regconfig参数的文本检索函数在省略该参数时,会使用由指定的配置。 - 中的函数被单独列出,因为它们通常不被用于日常的文本搜索操作。 - 它们主要有助于开发和调试新的文本搜索配置。 + 中的函数被单独列出,因为它们通常不被用于日常的文本检索操作。 + 它们主要有助于开发和调试新的文本检索配置。
- 文本搜索调试函数 + 文本检索调试函数 @@ -11724,7 +11724,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple lexemestext[] ) - 根据指定的或默认的文本搜索配置从document中提取和正规化词元,并返回关于每个词元是如何处理的信息。 + 根据指定的或默认的文本检索配置从document中提取和正规化词元,并返回关于每个词元是如何处理的信息。 详情参见 diff --git a/zh/14/gist.sgml b/zh/14/gist.sgml index fa8263bc..c31a9e83 100644 --- a/zh/14/gist.sgml +++ b/zh/14/gist.sgml @@ -984,7 +984,7 @@ my_sortsupport(PG_FUNCTION_ARGS) 示例 - PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本搜索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: + PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本检索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: diff --git a/zh/14/json.sgml b/zh/14/json.sgml index 8fa2a192..deaa1613 100644 --- a/zh/14/json.sgml +++ b/zh/14/json.sgml @@ -38,7 +38,7 @@ - 由于 json 类型存储的是输入文本的精确副本,因此它会保留标记 + 由于 json 类型存储的是输入文本的精确副本,因此它会保留词元 之间在语义上无关紧要的空白,以及 JSON 对象内部键的顺序。此外,如果值中 的某个 JSON 对象包含同一个键多次,所有键/值对都会被保留下来(处理函数会 将最后一个值视为生效值)。相比之下,jsonb 不保留空白,不保留 @@ -86,7 +86,7 @@ 当把文本形式的 JSON 输入转换为 jsonb 时, - RFC 7159 描述的基本类型会有效映射到原生的 + RFC 7159 描述的基本类型实际上会映射到原生的 PostgreSQL 类型上,如 所示。因此,什么样的数据构成 有效的 jsonb 会有一些额外但较小的限制,这些限制不适用于 @@ -137,7 +137,7 @@ null - (无) + (无) SQL NULL 是不同的概念 @@ -152,18 +152,18 @@ 以下都是有效的 json(或 jsonb)表达式: --- Simple scalar/primitive value --- Primitive values can be numbers, quoted strings, true, false, or null +-- 简单的标量/基本值 +-- 基本值可以是数字、加引号的字符串、true、false 或 null SELECT '5'::json; --- Array of zero or more elements (elements need not be of same type) +-- 包含零个或多个元素的数组(元素不必是同一类型) SELECT '[1, 2, "foo", null]'::json; --- Object containing pairs of keys and values --- Note that object keys must always be quoted strings +-- 包含键值对的对象 +-- 注意,对象的键必须始终是加引号的字符串 SELECT '{"bar": "baz", "balance": 7.77, "active": false}'::json; --- Arrays and objects can be nested arbitrarily +-- 数组和对象可以任意嵌套 SELECT '{"foo": [true, "bar"], "tags": {"a": 1, "b": null}}'::json; @@ -219,8 +219,7 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 当 JSON 数据存储在表中时,它与任何其他数据类型一样,都要面对相同的并发控 制考量。虽然存储大型文档是可行的,但要记住,任何更新都会在整行上获取一个 行级锁。应考虑将 JSON 文档限制在可管理的大小,以减少更新事务之间的锁争用。 - 理想情况下,每个 JSON 文档都应表示一个原子数据项,按照业务规则,它不应被 - 合理地进一步拆分为更小且可独立修改的数据项。 + 理想情况下,每个 JSON 文档都应表示一个原子数据项,根据业务规则,无法再合理地将它细分为更小且可独立修改的数据项。 @@ -228,11 +227,11 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; <type>jsonb</type> 包含与存在 jsonb - containment + 包含 jsonb - existence + 存在 测试 包含jsonb 的一项重要能力。 @@ -241,33 +240,32 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 示例都返回真: --- Simple scalar/primitive values contain only the identical value: +-- 简单的标量/基本值只包含相同的值: SELECT '"foo"'::jsonb @> '"foo"'::jsonb; --- The array on the right side is contained within the one on the left: +-- 左侧数组包含右侧数组: SELECT '[1, 2, 3]'::jsonb @> '[1, 3]'::jsonb; --- Order of array elements is not significant, so this is also true: +-- 数组元素的顺序无关紧要,因此下面的结果也为真: SELECT '[1, 2, 3]'::jsonb @> '[3, 1]'::jsonb; --- Duplicate array elements don't matter either: +-- 重复的数组元素也无关紧要: SELECT '[1, 2, 3]'::jsonb @> '[1, 2, 2]'::jsonb; --- The object with a single pair on the right side is contained --- within the object on the left side: +-- 左侧对象包含右侧只有一个键值对的对象: SELECT '{"product": "PostgreSQL", "version": 9.4, "jsonb": true}'::jsonb @> '{"version": 9.4}'::jsonb; --- The array on the right side is not considered contained within the --- array on the left, even though a similar array is nested within it: -SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- yields false +-- 左侧数组被认为包含右侧数组, +-- 尽管其中嵌套了一个类似的数组: +SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- 结果为假 --- But with a layer of nesting, it is contained: +-- 但增加一层嵌套后,就构成了包含关系: SELECT '[1, 2, [1, 3]]'::jsonb @> '[[1, 3]]'::jsonb; --- Similarly, containment is not reported here: -SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- yields false +-- 同样,下面也不构成包含关系: +SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- 结果为假 --- A top-level key and an empty object is contained: +-- 包含由顶层键和空对象构成的对象: SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; @@ -282,11 +280,11 @@ SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; 对于结构必须匹配这一一般原则,有一个特殊例外:数组可以包含一个基本值: --- This array contains the primitive string value: +-- 这个数组包含该基本字符串值: SELECT '["foo", "bar"]'::jsonb @> '"bar"'::jsonb; --- This exception is not reciprocal -- non-containment is reported here: -SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false +-- 这个例外并不对称——下面的结果表示不包含: +SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- 结果为假 @@ -296,19 +294,19 @@ SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false 外,下面这些示例都返回真: --- String exists as array element: +-- 字符串作为数组元素存在: SELECT '["foo", "bar", "baz"]'::jsonb ? 'bar'; --- String exists as object key: +-- 字符串作为对象键存在: SELECT '{"foo": "bar"}'::jsonb ? 'foo'; --- Object values are not considered: -SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- yields false +-- 不考虑对象的值: +SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- 结果为假 --- As with containment, existence must match at the top level: -SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- yields false +-- 与包含关系一样,存在性必须在顶层匹配: +SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- 结果为假 --- A string is considered to exist if it matches a primitive JSON string: +-- 如果字符串与一个基本 JSON 字符串匹配,则认为它存在: SELECT '"foo"'::jsonb ? 'foo'; @@ -322,8 +320,7 @@ SELECT '"foo"'::jsonb ? 'foo'; 由于 JSON 包含是嵌套的,因此适当的查询可以跳过对子对象的显式选择。例如, 假设我们有一个 doc 列,其顶层是对象,而且大 多数对象都带有 tags 字段,该字段中包含子对象数组。下面 - 这个查询会找出那些包含同时带有 "term":"paris" 和 - "term":"food" 的子对象的项,同时忽略 + 这个查询会找出同时出现包含 "term":"paris" 的子对象和包含 "term":"food" 的子对象的项,同时忽略 tags 数组之外的任何此类键: SELECT doc->'site_name' FROM websites @@ -353,7 +350,7 @@ SELECT doc->'site_name' FROM websites <type>jsonb</type> 索引 jsonb - indexes on + 索引 @@ -403,14 +400,14 @@ CREATE INDEX idxginp ON api USING GIN (jdoc jsonb_path_ops); 名为 jdocjsonb 列里。 如果在该列上创建了 GIN 索引,那么下面这样的查询就可以利用这个索引: --- Find documents in which the key "company" has value "Magnafone" +-- 查找键 "company" 的值为 "Magnafone" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"company": "Magnafone"}'; 但是,类似下面这样的查询就无法使用该索引,因为虽然操作符 ? 可索引,但它并未直接应用到被索引的列 jdoc 上: --- Find documents in which the key "tags" contains key or array element "qui" +-- 查找键 "tags" 包含键或数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc -> 'tags' ? 'qui'; 不过,只要适当地使用表达式索引,上述查询也可以利用索引。如果经常查询 @@ -428,7 +425,7 @@ CREATE INDEX idxgintags ON api USING GIN ((jdoc -> 'tags')); 另一种查询方法是利用包含,例如: --- Find documents in which the key "tags" contains array element "qui" +-- 查找键 "tags" 包含数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qui"]}'; jdoc 列上的简单 GIN 索引可以支持这个查询。 @@ -449,8 +446,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; 对于这些操作符,GIN 索引会从 jsonpath 模式中提取出形如 - accessors_chain - == constant 的子句,并根据其中提到 + accessors_chain = constant 的子句,并根据其中提到 的键和值进行索引搜索。访问器链可以包含 .key[*] 和 @@ -466,7 +462,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; @@ 操作符的查询,但相较于默认操作符类 jsonb_ops,它具有显著的性能优势。 jsonb_path_ops 索引通常比相同数据上的 - jsonb_ops 索引小得多,而且搜索条件也更具特异性,尤其是在 + jsonb_ops 索引小得多,而且搜索也更有针对性,尤其是在 查询中包含数据里频繁出现的键时。因此,搜索操作通常比使用默认操作符类时 性能更佳。 @@ -482,9 +478,9 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; 基本上,每个 jsonb_path_ops 索引项都是该值连同 - 通向该值的键一起计算出的哈希。例如,要索引 + 通向该值的键一起计算出的 hash。例如,要索引 {"foo": {"bar": "baz"}},会创建一个单独的索引项, - 其哈希值中同时纳入 foobar 和 + 其 hash 值中同时纳入 foobarbaz 这三者。因此,查找这一结构的包含查询会得到一次 非常精确的索引搜索;但完全没有办法据此找出 foo 是否 作为键出现。另一方面,jsonb_ops 索引会分别创建三个 @@ -506,7 +502,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; jsonb 还支持 btreehash 索引。通常只有在需要检查完整 JSON 文档是否相等时, 它们才有用。btreejsonb 数据项的 - 排序通常没什么太大意义,但为了完整起见,其规则如下: + 排序顺序通常很少受到关注,但为了完整起见,其规则如下: 对象 > 数组 > 布尔值 > 数字 > 字符串 > null @@ -561,27 +557,24 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; --- Extract object value by key +-- 按键提取对象的值 SELECT ('{"a": 1}'::jsonb)['a']; --- Extract nested object value by key path +-- 按键路径提取嵌套对象的值 SELECT ('{"a": {"b": {"c": 1}}}'::jsonb)['a']['b']['c']; --- Extract array element by index +-- 按下标提取数组元素 SELECT ('[1, "2", null]'::jsonb)[1]; --- Update object value by key. Note the quotes around '1': the assigned --- value must be of the jsonb type as well +-- 按键更新对象的值。注意 '1' 两边的引号:赋予的值也必须是 jsonb 类型 UPDATE table_name SET jsonb_field['key'] = '1'; --- This will raise an error if any record's jsonb_field['a']['b'] is something --- other than an object. For example, the value {"a": 1} has a numeric value --- of the key 'a'. +-- 如果任何记录的 jsonb_field['a']['b'] 不是对象,就会报错。 +-- 例如,值 {"a": 1} 的键 'a' 对应的值是数字。 UPDATE table_name SET jsonb_field['a']['b']['c'] = '1'; --- Filter records using a WHERE clause with subscripting. Since the result of --- subscripting is jsonb, the value we compare it against must also be jsonb. --- The double quotes make "value" also a valid jsonb string. +-- 使用带下标的 WHERE 子句筛选记录。由于下标操作的结果是 jsonb, +-- 与之比较的值也必须是 jsonb。双引号使 "value" 也成为合法的 jsonb 字符串。 SELECT * FROM table_name WHERE jsonb_field['key'] = '"value"'; @@ -591,19 +584,19 @@ SELECT * FROM table_name WHERE jsonb_field['key'] = '"value"'; (对象或数组)的空 JSON 值来处理: --- Where jsonb_field was NULL, it is now {"a": 1} +-- 原先为 NULL 的 jsonb_field 现在为 {"a": 1} UPDATE table_name SET jsonb_field['a'] = '1'; --- Where jsonb_field was NULL, it is now [1] +-- 原先为 NULL 的 jsonb_field 现在为 [1] UPDATE table_name SET jsonb_field[0] = '1'; - 如果对一个元素数量不足的数组指定了某个索引,就会不断追加 - NULL 元素,直到该索引可达并且可以设置该值为止。 + 如果对一个元素数量不足的数组指定了某个下标,就会不断追加 + NULL 元素,直到该下标可达并且可以设置该值为止。 --- Where jsonb_field was [], it is now [null, null, 2]; --- where jsonb_field was [0], it is now [0, null, 2] +-- 原先为 [] 的 jsonb_field 现在为 [null, null, 2]; +-- 原先为 [0] 的 jsonb_field 现在为 [0, null, 2] UPDATE table_name SET jsonb_field[2] = '2'; @@ -614,10 +607,10 @@ UPDATE table_name SET jsonb_field[2] = '2'; null 填充,直到能够放入被赋值的值为止。 --- Where jsonb_field was {}, it is now {"a": [{"b": 1}]} +-- 原先为 {} 的 jsonb_field 现在为 {"a": [{"b": 1}]} UPDATE table_name SET jsonb_field['a'][0]['b'] = '1'; --- Where jsonb_field was [], it is now [null, {"a": 1}] +-- 原先为 [] 的 jsonb_field 现在为 [null, {"a": 1}] UPDATE table_name SET jsonb_field[1]['a'] = '1'; @@ -634,7 +627,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; PL/Perl 的扩展名为 jsonb_plperljsonb_plperlu。如果使用它们, - jsonb 值会按适当方式映射为 Perl 数组、哈希和标量。 + jsonb 值会按适当方式映射为 Perl 数组、hash 和标量。 @@ -711,7 +704,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; - 路径表达式由一系列路径元素构成,可以是下列任意一种: + 路径表达式由一系列路径元素构成,这些元素可以是下列任意一种: @@ -850,7 +843,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; 类似 .**,但只选择 JSON 层次结构中指定的层级。 - 嵌套层级以整数指定。层级零对应当前对象。若要访问最低的嵌套层级, + 嵌套层级以整数指定。层级零对应当前对象。若要访问最深的嵌套层级, 可以使用 last 关键字。这是 PostgreSQL 对 SQL/JSON 标准的扩展。 @@ -868,13 +861,13 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; 可以用两种形式给出: indexstart_index to end_index。 - 第一种形式按索引返回单个数组元素。第二种形式按索引范围返回数组切片, + 第一种形式按下标返回单个数组元素。第二种形式按下标范围返回数组切片, 其中包括与给定 start_indexend_index 对应的元素。 指定的 index 可以是整数,也可以是返回单个 - 数值的表达式,该表达式会自动转换为整数。索引零对应第一个数组元素。 + 数值的表达式,该数值会自动转换为整数。下标零对应第一个数组元素。 你也可以使用 last 关键字来表示最后一个数组元素, 这对于处理长度未知的数组很有用。 diff --git a/zh/14/libpq.sgml b/zh/14/libpq.sgml index 7c618301..4bfc9d25 100644 --- a/zh/14/libpq.sgml +++ b/zh/14/libpq.sgml @@ -2,7 +2,7 @@ - <application>libpq</application> - C 库 + <application>libpq</application> — C 库 libpq @@ -13,33 +13,27 @@ - libpq是应用程序员使用PostgreSQLC接口。libpq是一个库函数的集合,它们允许客户端程序传递查询给PostgreSQL后端服务器并且接收这些查询的结果。 + libpqPostgreSQLC应用程序编程接口。libpq是一组库函数,客户端程序可用它们向PostgreSQL后端服务器发送查询并接收查询结果。 - libpq也是很多其他PostgreSQL应用接口的底层引擎,包括为 C++、Perl、Python、Tcl 和 ECPG编写的接口。如果你使用那些包,某些方面的libpq行为将会对你很重要。特别是,描述了任何使用libpq的应用的用户可见的行为。 + libpq也是其他几个PostgreSQL应用程序接口的底层引擎,包括为 C++、Perl、Python、Tcl 和ECPG编写的接口。因此,对于这些包的用户,libpq行为的某些方面也很重要。特别是,描述了任何使用libpq的应用程序的用户都能观察到的行为。 - 在本章的末尾()包括了一些短程序来展示如何编写使用libpq的应用。在源代码发布的src/test/examples目录中还有一些完整的libpq应用的示例。 + 本章末尾()包含一些简短程序,展示如何编写使用libpq的程序。源代码发行包的src/test/examples目录中还提供了几个完整的libpq应用程序示例。 - 使用libpq的客户端程序必须包括头文件libpq-fe.hlibpq-fe.h并必须与libpq库链接在一起。 + 使用libpq的客户端程序必须包含头文件libpq-fe.hlibpq-fe.h,并且必须与libpq库链接。 数据库连接控制函数 - - 下列函数会建立到一个PostgreSQL后端服务器的连接。 - 一个应用程序可以在一个时刻打开多个后端连接(原因之一就是为了访问多个数据库)。 - 每个连接用一个PGconnPGconn对象表示,它从函数,或得到。 - 注意这些函数将总是返回一个非空的对象指针,除非正好没有内存来分配PGconn对象。 - 在通过该连接对象发送查询之前,应该调用函数来检查返回值以确定是否得到了一个成功的连接。 - - + 以下函数用于建立到PostgreSQL后端服务器的连接。应用程序可以同时保持多个后端连接。(这样做的原因之一是访问多个数据库。)每个连接由一个PGconnPGconn对象表示,该对象可以通过以下函数获取:, + 。注意,这些函数总是返回非空的对象指针,除非内存不足,甚至无法分配PGconn对象。应调用函数检查返回值,确认连接成功后,再通过连接对象发送查询。 如果不受信任的用户能够访问一个没有采用模式的安全使用方式的数据库,那么每个会话开始时都应从search_path中移除公开可写的模式。可以把参数关键词options设置为-csearch_path=。也可以在连接后发出PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)")。这种考虑并非专门针对libpq;它适用于每一种可执行任意 SQL 命令的接口。 @@ -47,7 +41,7 @@ - 在 Unix 上,复制一个拥有打开 libpq 连接的进程可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行代码是安全的。 + 在 Unix 上,对持有已打开 libpq 连接的进程执行 fork 操作可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行程序是安全的。 @@ -74,32 +68,32 @@ PGconn *PQconnectdbParams(const char * const *keywords, - 被传递的数组可以为空,这样就会使用所有默认参数。 - 也可以只包含一个或几个参数设置。他们在长度上必须匹配。 - 对于参数数组的处理将会停止于keywords数组中第一个NULL元素。 - 而且,如果与非-NULL keywords条目相关联的values条目为NULL或者空字符串,则忽略该项并继续处理下一对数组项。 + 传入的数组可以为空,以使用所有默认参数,也可以包含一个或多个参数设置。 + 两个数组的长度必须相同。处理会在 keywords 数组的第一个 NULL 元素处停止。 + 如果某个非 NULLkeywords 元素所对应的 + values 元素为 NULL 或空字符串,则忽略这一项,继续处理下一对数组元素。 - 当expand_dbname为非零时,会检查第一个dbname关键词的值以查看它是否为一个连接字符串。 - 如果是,它被扩展到从字符串中提取的单独的连接参数。 - 该值被认为是一个连接字符串,而不仅是一个数据库名称,如果它包含一个等号(=)或者它以URI模式标志符开头, - (有关连接字符串格式的更多详情可见。) - 只有dbname的第一次出现会按这种方式处理,任何后续dbname值会被当做一个普通数据库名处理。 + 当 expand_dbname 非零时,会检查第一个 dbname 关键词的值是否为 + 连接字符串。如果是,就将其展开为从该字符串中提取的各个连接参数。 + 如果该值包含等号(=),或以 URI 方案标识符开头,就会将其视为连接字符串,而非单纯的数据库名。 + (连接字符串格式的详细说明见。) + 只有第一次出现的 dbname 会按这种方式处理;后续的 dbname 参数都作为普通数据库名处理。 - 通常,参数数组从开头到结尾进行处理。 - 当关键词有重复时,使用最后一个值(不是 NULL 或空)。 - 此规则特别适用于连接字符串中的关键字与一个出现在keywords数组中的关键字冲突的情况。 - 因此,程序员可以决定数组条目是否能被覆盖或用连接字符串获取的值覆盖。 - 出现在扩展的dbname条目之前的数组条目可以被连接字符串的字段所覆盖,反之,这些字段被dbname之后出现的数组条目所覆盖。(但是,再有,只有在那些条目支持非空值时。) + 通常会从头到尾处理参数数组。如果某个关键词重复出现,则采用最后一个非 NULL 且非空的值。 + 此规则也适用于连接字符串中的关键词与 keywords 数组中的关键词冲突的情况。 + 因此,程序员可以决定数组元素是覆盖连接字符串中的值,还是被这些值覆盖。 + 出现在要展开的 dbname 元素之前的数组元素,可以被连接字符串中的字段覆盖; + 而这些字段又会被出现在 dbname 之后的数组元素覆盖(同样,只有这些元素提供非空值时才会覆盖)。 - 在处理完所有数组条目和任何扩展的连接字符串后,所有未设置的连接参数都将使用默认值填充。 - 如果一个未设置参数的相关环境变量(参见 )被设置了,它的值会被使用。 - 如果环境变量未被设置,则使用参数的内置默认值。 + 处理完所有数组元素及展开的连接字符串后,仍未设置的连接参数将填入默认值。 + 如果某个未设置参数对应的环境变量(见)已经设置,就使用该环境变量的值; + 否则使用该参数的内置默认值。 @@ -121,7 +115,7 @@ PGconn *PQconnectdb(const char *conninfo); - 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空格分隔的一个或多个参数设置,还可以包含一个URI。详见。 + 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空白分隔的一个或多个参数设置,还可以包含一个URI。详见 @@ -144,11 +138,11 @@ PGconn *PQsetdbLogin(const char *pghost, - 这是的带有固定参数集合的前辈。它具有相同的功能,不过其中缺失的参数将总是采用默认值。对任意一个固定参数写NULL或一个空字符串将会使它采用默认值。 + 这是 的前身,使用固定的一组参数。除缺失参数始终采用默认值之外,功能相同。对于要使用默认值的任意固定参数,请传入 NULL 或空字符串。 - 如果dbName包含一个=符号或者具有一个合法的连接URI前缀,它会被当作一个conninfo字符串,就好像它已经被传递给了,并且剩余的参数则被应用为指定给。 + 如果 dbName 包含 = 符号,或具有有效的连接 URI 前缀,就会将其当作 conninfo 字符串处理,方式与将其传给 完全相同,然后按照 的规则应用其余参数。 @@ -183,7 +177,7 @@ PGconn *PQsetdb(char *pghost, PQconnectPollPQconnectPoll - nonblocking connection + 非阻塞连接 以非阻塞的方式建立一个到数据库服务器的连接。 @@ -209,18 +203,14 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); 在PQconnectStart中,数据库连接使用从字符串conninfo中取得的参数创建,这和之前描述的相同。 - - 只要满足一些限制,PQconnectStartPQconnectPoll都不会阻塞: - + 无论是还是PQconnectStart还是PQconnectPoll都不会阻塞,只要满足以下限制: - - 必须正确使用 hostaddr 参数,以避免执行 DNS 查询。详细信息请参见中该参数的说明。 - + 必须正确使用 hostaddr 参数,以避免执行 DNS 查询。详细信息请参见中该参数的说明。 - 如果你调用,确保你追踪的该流对象不会阻塞。 + 如果你调用,确保接收追踪输出的流对象不会阻塞。 @@ -233,17 +223,14 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 要开始无阻塞的连接请求,可调用PQconnectStart或者。如果结果为空,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 + 要开始非阻塞连接请求,可调用PQconnectStart或者。如果结果为空指针,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 如果PQconnectStart成功,下一个阶段是轮询libpq,这样它能够继续进行连接序列。使用PQsocket(conn)来获得该数据库连接底层的套接字描述符(警告:不要假定在PQconnectPoll调用之间套接字会保持相同)。这样循环:如果PQconnectPoll(conn)上一次返回PGRES_POLLING_READING,等到该套接字准备好读取(按照select()poll()或类似的系统函数所指示的)。则再次调用PQconnectPoll(conn)。反之,如果PQconnectPoll(conn)上一次返回PGRES_POLLING_WRITING,等到该套接字准备好写入,则再次调用PQconnectPoll(conn)。在第一次迭代时,即如果你还没有调用PQconnectPoll,行为就像是它上次返回了PGRES_POLLING_WRITING。持续这个循环直到PQconnectPoll(conn)返回PGRES_POLLING_FAILED指示连接过程已经失败,或者返回PGRES_POLLING_OK指示连接已经被成功地建立。 - - 在连接期间的任意时刻,该连接的状态可以通过调用来检查。如果这个调用返回CONNECTION_BAD,那么连接过程已经失败。如果该调用返回CONNECTION_OK,则该连接已经准备好。如前所述,这些状态同样都可以从PQconnectPoll的返回值检测。在一个异步连接过程中(也只有在这个过程中)也可能出现其他状态。这些状态指示该连接过程的当前阶段,并且可能有助于为用户提供反馈。这些状态是: - - + 在连接过程中的任何时刻,都可以调用来检查连接状态。如果调用返回CONNECTION_BAD,则连接过程失败;如果调用返回CONNECTION_OK,则连接已就绪。这两种状态也同样可以通过以下函数的返回值检测:PQconnectPoll,详见上文。在异步连接过程中还可能出现其他状态,而且它们仅在此过程中出现。这些状态表示连接过程的当前阶段,例如可用于向用户提供反馈。这些状态包括: CONNECTION_STARTED @@ -315,10 +302,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - - - 注意,尽管这些常数将被保留(为了维护兼容性),一个应用永远不应该依赖这些状态按照特定顺序出现,或者根本就不依赖它们,或者不依赖状态总是这些文档中所说的值。一个应用可能做些这样的事情: - + 注意,虽然为保持兼容性会保留这些常量,但应用程序不应依赖它们按特定顺序出现、不应假定它们一定出现,也不应假定状态值一定是这里列出的某个值。应用程序可以采用如下方式: switch(PQstatus(conn)) { case CONNECTION_STARTED: @@ -338,11 +322,11 @@ switch(PQstatus(conn)) - 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。否则,PQconnectStart后面跟着PQconnectPoll循环等效于。 + 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。除此之外,PQconnectStart后面跟着PQconnectPoll循环等效于 - 注意当PQconnectStart返回一个非空的指针时,你必须在用完它之后调用来处理那些结构体和任何相关的内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 + 注意当PQconnectStart返回一个非空的指针时,你必须在用完它之后调用来释放该结构体及其关联的所有内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 @@ -358,21 +342,21 @@ PQconninfoOption *PQconndefaults(void); typedef struct { char *keyword; /* 该选项的关键词 */ - char *envvar; /* 依赖的环境变量名 */ - char *compiled; /* 依赖的内置默认值 */ + char *envvar; /* 后备环境变量名 */ + char *compiled; /* 编译时设置的后备默认值 */ char *val; /* 选项的当前值,或者 NULL */ - char *label; /* 连接对话框中域的标签 */ - char *dispchar; /* 指示如何在一个连接对话框中显示这个域。值是: + char *label; /* 连接对话框中字段的标签 */ + char *dispchar; /* 指示如何在连接对话框中显示此字段。可取值: "" 显示输入的值 - "*" 密码域 - 隐藏值 + "*" 密码字段 - 隐藏值 "D" 调试选项 - 默认不显示 */ - int dispsize; /* 用于对话框的以字符计的域尺寸 */ + int dispsize; /* 对话框中的字段宽度,以字符计 */ } PQconninfoOption; - 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前缺省值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回该空指针。注意当前缺省值(val域)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 + 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前默认值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回空指针。注意当前默认值(val字段)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 @@ -393,9 +377,7 @@ PQconninfoOption *PQconninfo(PGconn *conn); - 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前缺省值。 - 返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。 - 上述所有对于的注解也适用于的结果。 + 返回一个连接选项数组。可以用它确定所有可能的 选项,以及实际用于连接服务器的值。返回值指向一个 PQconninfoOption 结构体数组,该数组以 keyword 指针为空的条目结束。上文针对 的所有注意事项,也适用于 的结果。 @@ -421,7 +403,9 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); - 如果errmsg不是NULL,那么成功时*errmsg会被设置为NULL, 否则设置为被malloc过的错误字符串以说明该问题(也可以将*errmsg设置为NULL并且函数返回NULL,这表示一种内存耗尽的情况)。 + 如果 errmsg 不是 NULL,则成功时将 *errmsg 设为 NULL; + 失败时将其设为由 malloc 分配的、用于说明问题的错误字符串。 + (也可能出现 *errmsg 被设为 NULL,同时函数返回 NULL 的情况;这表示内存不足。) @@ -451,7 +435,7 @@ void PQfinish(PGconn *conn); PQresetPQreset - 重置与服务器的通讯通道。 + 重置与服务器的通信通道。 void PQreset(PGconn *conn); @@ -469,7 +453,7 @@ void PQreset(PGconn *conn); PQresetPollPQresetPoll - 以非阻塞方式重置与服务器的通讯通道。 + 以非阻塞方式重置与服务器的通信通道。 int PQresetStart(PGconn *conn); @@ -486,7 +470,7 @@ PostgresPollingStatusType PQresetPoll(PGconn *conn); - 要发起一次连接重置,调用。如果它返回 0,那么重置失败。如果返回 1,就按使用PQresetPoll建立连接时相同的方法,继续调用PQresetPoll来重置连接。 + 要开始重置连接,请调用 。如果返回 0,表示重置失败。如果返回 1,则使用 PQresetPoll 轮询重置过程,方式与使用 PQconnectPoll 建立连接完全相同。 @@ -581,7 +565,7 @@ void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook); int callback_fn(char *buf, int size, PGconn *conn); - 随后,libpq会调用该回调,而不是调用其默认的PQdefaultSSLKeyPassHook_OpenSSL处理程序。 + 随后,libpq会调用该回调,而不是调用其默认的PQdefaultSSLKeyPassHook_OpenSSL处理程序。 回调函数应确定密钥密码,并将其复制到大小为size的结果缓冲区buf中。 buf中的字符串必须以空字符结尾。 回调函数必须返回存储在buf中的密码长度,不包括结尾的空字符。 @@ -600,7 +584,7 @@ int callback_fn(char *buf, int size, PGconn *conn); - 除了异常、longjmp(...)等情况外,回调务必不可跳出正常控制流。它必须正常返回。 + 回调不得通过异常、longjmp(...)等方式跳出正常控制流。它必须正常返回。 @@ -637,9 +621,9 @@ PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void); 几个libpq函数解析用户指定的字符串以获取连接参数。 - 这些字符串有两种被接受的格式:普通的关键字/值字符串和URI。URI通常遵循 + 这些字符串有两种被接受的格式:普通的关键词/值字符串和URI。URI通常遵循 RFC - 3986,除了允许多主机连接字符串,如下面进一步描述的那样。 + 3986,但也允许使用多主机连接字符串,详见下文。 @@ -647,10 +631,10 @@ PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void); 关键词/值连接字符串 - 在关键词/值格式中,每一个参数设置的形式都是关键词 = ,在设置之间有空白。 - 设置的等号周围的空白是可选的。 - 要写一个空值或一个包含空白的值,将它用单引号包围,例如关键词 = 'a value'。 - 值里面的单引号和反斜线必须用一个反斜线转义,即\'\\。 + 在关键词/值格式中,每一个参数设置的形式都是关键词 = ,设置之间以空格分隔。 + 设置的等号周围的空格是可选的。 + 要写一个空值或一个包含空格的值,将它用单引号包围,例如keyword = 'a value'。 + 值里面的单引号和反斜杠必须用一个反斜杠转义,即\'\\ @@ -674,22 +658,22 @@ host=localhost port=5432 dbname=mydb connect_timeout=10 postgresql://userspec@hostspec/dbname?paramspec -where userspec is: +其中 userspec 为: user:password -and hostspec is: +hostspec 为: host:port,... -and paramspec is: +paramspec 为: name=value&... - URI模式标志符可以是postgresql://postgres://。 + URI方案标识符可以是postgresql://postgres://。 每一个剩下的URI部分都是可选的。 下列示例展示了合法的URI语法: @@ -706,19 +690,15 @@ postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application postgresql:///mydb?host=localhost&port=5433 - 全部的命名参数必须匹配中列出的关键词,除了与JDBC连接URI兼容之外,ssl=true的实例转换到sslmode=require。 + 所有命名参数都必须与中列出的关键词匹配;唯一的例外是,为兼容 JDBC 连接 URI,会将 ssl=true 转换为 sslmode=require - 连接URI需要使用百分号编码 - 对其进行编码,如果其中包含具有特殊含义的符号。这里是一个示例,其中等号(=)被替换为 - %3D,空格字符被替换为 - %20: + 如果连接 URI 的任意部分包含具有特殊含义的符号,就需要使用百分号编码。下面的示例将等号(=)替换为 %3D,将空格字符替换为 %20 postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff - + 主机部分可能是主机名或一个 IP 地址。要指定一个 IPv6 地址,将它封闭在方括号中: @@ -731,7 +711,7 @@ postgresql://[2001:db8::1234]/database 主机组件会被按照参数对应的描述来解释。 特别地,如果主机部分是空或看起来像一个绝对路径名称,将使用一个 Unix 域套接字连接,否则将启动一个 TCP/IP 连接。 不过要注意,斜线是 URI 层次部分中的一个保留字符。 - 因此,要指定一个非标准的 Unix 域套接字目录,要么忽略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: + 因此,要指定一个非标准的 Unix 域套接字目录,要么省略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: postgresql:///dbname?host=/var/lib/postgresql postgresql://%2Fvar%2Flib%2Fpostgresql/dbname @@ -741,7 +721,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以在一个URI中指定多个主机,每一个都有一个可选的端口。 一个形式为postgresql://host1:port1,host2:port2,host3:port3/的URI等效于host=host1,host2,host3 port=port1,port2,port3形式的连接字符串。 - 如下所述,每一个主机都将被尝试,直到成功地建立一个连接。 + 如下所述,每一个主机都将被依次尝试,直到成功地建立一个连接。 @@ -751,7 +731,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以指定多个要连接的主机,这样它们会按给定的顺序被尝试。 - 在键/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 + 在关键词/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 在指定的每一个选项中都必须给出相同数量的元素,这样第一个hostaddr对应于第一个主机名,第二个hostaddr对应于第二个主机名,以此类推。 不过,如果仅指定一个port,它将被应用于所有的主机。 @@ -761,11 +741,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 不管是哪一种格式,单一的主机名可以被翻译成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 + 不管是哪一种格式,单一的主机名可以被解析成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 - 当多个主机被指定时或者单个主机名被翻译成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。 + 当多个主机被指定时或者单个主机名被解析成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。 @@ -787,14 +767,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 要连接的主机名。主机名如果主机名看起来像绝对路径名, - 则指定的是Unix域通信而不是TCP/IP通信;该值是存储套接字文件的目录的名称。 - (在Unix上,绝对路径名以斜杠开头。在Windows上,以驱动器号开头的路径也被识别。) - 如果主机名以@开头,则将其视为抽象命名空间中的Unix域套接字(目前在Linux和Windows上支持)。 - 当未指定host或为空时,默认行为是连接到Unix域套接字Unix域套接字在 - /tmp(或在构建PostgreSQL时指定的套接字目录)中。在Windows和 - 没有Unix域套接字的机器上,默认是连接到localhost。 - + 要连接的主机名。主机名如果主机名看起来像绝对路径名, + 则指定的是 Unix 域通信,而非 TCP/IP 通信;此值是存放套接字文件的目录名。 + (在 Unix 上,绝对路径名以斜杠开头。在 Windows 上,也会识别以驱动器号开头的路径。)如果主机名以 @ 开头,则将其视为抽象命名空间中的 Unix 域套接字(目前在 Linux 和 Windows 上支持)。 + 当未指定 host 或其值为空时,默认连接到 /tmp + (或构建 PostgreSQL 时指定的套接字目录)中的 Unix 域套接字。 + Unix 域套接字在 Windows 和没有 Unix 域套接字的机器上,默认连接到 localhost。 + 也可以接受一个逗号分隔的主机名列表,此时列表中的每个主机名将按顺序尝试; @@ -806,23 +785,18 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname hostaddr - 要连接的主机的数字IP地址。这应该是标准的IPv4地址格式,例如,172.28.40.9。 如果您的机器支持IPv6,也可以使用这些地址。当为此参数指定非空字符串时,总是使用TCP/IP通信。 如果未指定此参数,则将查找host的值以查找相应的IP地址 — 或者,如果host指定了IP地址,则将直接使用该值。 - - 使用hostaddr允许应用程序避免主机名查找,这在有时间限制的应用程序中可能很重要。 - 但是,对于GSSAPI或SSPI认证方法以及verify-full SSL证书验证,需要主机名。 - 使用以下规则: - + 使用hostaddr可以避免主机名查找,这对于有时间限制的应用程序可能很重要。但是,采用 GSSAPI 或 SSPI 认证方式,以及进行verify-fullSSL 证书验证时,都需要主机名。遵循以下规则: 如果指定了host而没有指定hostaddr,则会发生主机名查找。 (当使用PQconnectPoll时,查找发生在PQconnectPoll首次考虑此主机名时, - 并且可能导致PQconnectPoll阻塞一段时间。) + 并且可能导致PQconnectPoll阻塞相当长的时间。) @@ -834,17 +808,10 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果同时指定了hosthostaddr, - 则hostaddr的值给出服务器的网络地址。 - 除非认证方法需要,否则host的值将被忽略, - 在这种情况下,它将用作主机名。 - + 如果同时指定了 hosthostaddr,则 hostaddr 的值给出服务器的网络地址。只有认证方法需要主机名时,才会将 host 的值用作主机名;否则忽略该值。 + - - 请注意,如果host不是网络地址hostaddr上服务器的名称, - 则认证可能会失败。 - 此外,当同时指定hosthostaddr时, - host用于在密码文件中标识连接(请参阅)。 + 注意,以下情况很可能导致认证失败:host不是位于网络地址hostaddr的服务器名称。另外,同时指定hosthostaddr时,将使用host来标识密码文件中的连接(参见)。 @@ -852,7 +819,6 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 列表中的空项会导致使用相应的主机名,如果主机名也为空,则使用默认主机名。详见 - 没有主机名或主机地址, libpq将使用本地的Unix域套接字进行连接; @@ -891,8 +857,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - PostgreSQL用户连接的用户名。 - 默认为运行应用程序的操作系统用户名相同。 + 建立连接所用的 PostgreSQL 用户名。默认与运行应用程序的操作系统用户名相同。 @@ -902,7 +867,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果服务器要求密码认证,则使用密码。 + 服务器要求密码认证时所使用的密码。 @@ -929,7 +894,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 这个选项控制客户端对通道绑定的使用。设置为require表示连接必须使用通道绑定, prefer表示客户端将在可用时选择通道绑定, 而disable则阻止使用通道绑定。默认情况下, - 如果PostgreSQL是使用SSL支持编译的,则默认为prefer; + 如果PostgreSQL是使用SSL支持编译的,则默认为prefer; 否则默认为disable @@ -993,9 +958,9 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 指定配置参数的回退值。 + 指定配置参数的后备值。 如果没有通过连接参数或PGAPPNAME环境变量为application_name指定值, - 则将使用此值。在通用实用程序中指定回退名称很有用,该程序希望设置默认应用程序名称, + 则将使用此值。在通用实用程序中指定后备名称很有用,该程序希望设置默认应用程序名称, 但允许用户覆盖它。 @@ -1006,9 +971,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制是否使用客户端TCP保持活动。默认值为1,表示开启,但如果不想要保持活动,可以将其更改为0,表示关闭。 - 对于通过Unix域套接字进行的连接,此参数将被忽略。 - + 控制是否使用客户端 TCP keepalive。默认值为 1,表示开启;如果不需要 keepalive,可以将其设为 0,表示关闭。对于通过 Unix 域套接字建立的连接,此参数会被忽略。 + @@ -1017,11 +981,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在多少秒的不活动后,TCP应向服务器发送保持活动消息。值为零使用系统默认值。 - 对通过Unix域套接字进行的连接或禁用保持活动的连接,此参数将被忽略。 - 仅在支持TCP_KEEPIDLE或等效套接字选项的系统以及Windows上支持; - 在其他系统上,它没有任何效果。 - + 控制在多久没有活动后,TCP 应向服务器发送 keepalive 消息,以秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPIDLE 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -1030,11 +991,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在服务器未确认的情况下重新传输TCP保持活动消息的秒数。值为零时使用系统默认值。 - 此参数在通过Unix域套接字进行连接或禁用保持活动时将被忽略。 - 仅在支持TCP_KEEPINTVL或等效套接字选项的系统和Windows上支持; - 在其他系统上,此参数无效。 - + 控制未被服务器确认收到的 TCP keepalive 消息在多少秒后应被重传。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPINTVL 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -1043,11 +1001,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在客户端与服务器之间连接被视为断开之前可以丢失的TCP keepalive数量。 - 值为零时使用系统默认值。对通过Unix域套接字建立的连接或禁用keepalives的连接,此参数将被忽略。 - 仅在支持TCP_KEEPCNT或等效套接字选项的系统上受支持; - 在其他系统上,此参数无效。 - + 控制在客户端与服务器之间的连接被视为中断之前,可以丢失多少个 TCP keepalive 消息。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPCNT 或等效套接字选项的系统上受支持;在其他系统上无效。 + @@ -1056,10 +1011,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在连接在强制关闭之前,传输数据可以保持未被确认的毫秒数。 - 值为零时使用系统默认值。此参数对通过Unix域套接字进行的连接无效。 - 仅在支持TCP_USER_TIMEOUT的系统上受支持;在其他系统上,它没有效果。 - + 控制已发送的数据在连接被强制关闭之前最多可以保持未确认状态多长时间,以毫秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,此参数会被忽略。此参数仅在支持 TCP_USER_TIMEOUT 的系统上受支持;在其他系统上无效。 + @@ -1122,25 +1075,25 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个选项确定是否以及如何优先与服务器协商安全的GSS TCP/IP连接。有三种模式: + 这个选项确定是否以及以何种优先级与服务器协商安全的GSS TCP/IP连接。有三种模式: disable - 仅尝试非GSSAPI加密连接 + 仅尝试未经GSSAPI加密的连接 - prefer (默认) + prefer (默认) 如果存在GSSAPI凭据(即在凭据缓存中),首先尝试 GSSAPI加密连接;如果失败或没有凭据,则尝试 - 非GSSAPI加密连接。这是在编译PostgreSQL时使用GSSAPI支持时的默认设置。 + 未经GSSAPI加密的连接。这是在编译PostgreSQL时使用GSSAPI支持时的默认设置。 @@ -1159,7 +1112,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname gssencmode在Unix域套接字通信中被忽略。如果PostgreSQL没有编译GSSAPI支持, 使用require选项将导致错误,而prefer将被接受,但libpq实际上不会尝试 - 进行GSSAPI加密连接。GSSAPI与libpq + 进行GSSAPI加密连接。GSSAPI在 libpq 中 @@ -1191,7 +1144,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - prefer (默认) + prefer (默认) 首先尝试SSL连接;如果失败,则尝试非SSL连接 @@ -1231,22 +1184,18 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - sslmode被忽略用于Unix域套接字通信。 - 如果PostgreSQL没有SSL支持编译, + 在 Unix 域套接字通信中,sslmode 会被忽略。 + 如果PostgreSQL编译时未启用 SSL 支持, 使用选项requireverify-caverify-full会导致错误,而选项allowprefer 将被接受,但libpq实际上不会尝试建立SSL 连接。SSL使用libpq的SSL + sortas="libpq">在 libpq 中 - 请注意,如果可能使用GSSAPI加密, - 则优先使用该加密,而不考虑SSL的值。要在具有可用GSSAPI - 基础设施(如Kerberos服务器)的环境中强制使用 - SSL加密,还需将 - gssencmode设置为disable。 - + 注意,如果可以使用 GSSAPI 加密,就会优先使用它而不是 SSL 加密,无论 sslmode 的值是什么。在具有可用 GSSAPI 基础设施(例如 Kerberos 服务器)的环境中,要强制使用 SSL 加密,还应将 gssencmode 设为 disable。 + @@ -1255,15 +1204,15 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 此选项已被sslmode设置所取代。 - + 此选项已弃用,请改用 sslmode 设置。 + 如果设置为1,则需要与服务器建立SSL连接(这相当于sslmode require)。libpq将拒绝连接,如果服务器不接受 SSL连接。如果设置为0(默认值), libpq将与服务器协商连接类型(相当于sslmode - prefer)。此选项仅在PostgreSQL编译时启用SSL支持。 + prefer)。此选项仅在 PostgreSQL 编译时启用了 SSL 支持的情况下可用。 @@ -1286,7 +1235,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果安全性不是主要考虑因素,压缩可以提高吞吐量,如果网络是瓶颈的话。如果CPU性能是限制因素,禁用压缩可以提高响应时间和吞吐量。 + 如果安全性不是主要考虑因素,压缩可以提高吞吐量,如果网络是瓶颈的话。如果CPU性能是限制因素,禁用压缩可以缩短响应时间并提高吞吐量。 @@ -1310,7 +1259,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 这个参数指定了用于客户端证书的密钥的位置。它可以指定一个文件名,该文件名将被用来替代默认的 ~/.postgresql/postgresql.key,或者它可以指定一个从外部引擎 - (引擎是OpenSSL可加载模块)获取的密钥。外部引擎规范应该包括一个由冒号分隔的引擎名称和 + (引擎是OpenSSL可加载模块)获取的密钥。外部引擎的指定形式应包含一个由冒号分隔的引擎名称和 一个引擎特定的密钥标识符。如果没有进行SSL连接,则此参数将被忽略。 @@ -1327,10 +1276,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 指定此参数为任何非空值将抑制Enter PEM pass phrase: - 当提供加密的客户端证书密钥给libpq时, - OpenSSL默认会发出的提示。 - + 当向 libpq 提供加密的客户端证书密钥时,将此参数指定为任意非空值,都将抑制 OpenSSL 默认发出的 Enter PEM pass phrase: 提示。 + 如果密钥未加密,则忽略此参数。该参数对由OpenSSL引擎指定的密钥没有影响,除非引擎使用OpenSSL密码回调机制进行提示。 @@ -1362,10 +1309,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定SSL服务器证书吊销列表(CRL)的文件名。如果存在该文件中列出的证书,在尝试验证服务器证书时将被拒绝。 - 如果既没有设置也没有设置, - 则将采用~/.postgresql/root.crl。 - + 此参数指定 SSL 服务器证书吊销列表(CRL)的文件名。如果该文件存在,在验证服务器证书时,会拒绝其中列出的证书。如果既未设置,也未设置,则采用 ~/.postgresql/root.crl。 + @@ -1374,8 +1319,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定SSL服务器证书吊销列表(CRL)的目录名称。如果存在该目录中的文件中列出的证书,在尝试验证服务器证书时将被拒绝。 - + 此参数指定 SSL 服务器证书吊销列表(CRL)的目录名。如果该目录存在,在验证服务器证书时,会拒绝该目录下文件中列出的证书。 + 目录需要使用OpenSSL命令 @@ -1390,11 +1335,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - sslsniServer Name Indication + sslsni服务器名称指示 - 如果设置为1(默认值),libpq会在启用SSL的连接上设置TLS扩展Server Name IndicationSNI)。 + 如果设置为1(默认值),libpq会在启用SSL的连接上设置TLS扩展服务器名称指示SNI)。 通过将此参数设置为0,可以关闭此功能。 @@ -1427,8 +1372,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定连接允许的最低SSL/TLS协议版本。有效值为TLSv1, - TLSv1.1TLSv1.2和 + 这个参数指定连接允许的最低SSL/TLS协议版本。有效值为TLSv1、 + TLSv1.1TLSv1.2TLSv1.3。支持的协议取决于所使用的 OpenSSL版本,旧版本不支持最现代的协议版本。 如果未指定,默认值为TLSv1.2,符合本文撰写时的行业最佳实践。 @@ -1441,11 +1386,10 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定连接允许的最大SSL/TLS协议版本。有效值为TLSv1, - TLSv1.1TLSv1.2和 + 这个参数指定连接允许的最大SSL/TLS协议版本。有效值为TLSv1、 + TLSv1.1TLSv1.2TLSv1.3。支持的协议取决于使用的OpenSSL - 版本,旧版本不支持最新的协议版本。如果未设置,将忽略此参数,并且连接将使用后端定义的最大限制, - 如果设置。设置最大协议版本主要用于测试或者某些组件无法使用较新协议时。 + 版本,旧版本不支持最新的协议版本。如果未设置,则忽略此参数;如果后端定义了最大限制,连接将使用该限制。设置最大协议版本主要用于测试或者某些组件无法使用较新协议时。 @@ -1459,13 +1403,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 用于使用GSSAPI进行认证时要使用的Kerberos服务名称。 + 使用 GSSAPI 认证时所用的 Kerberos 服务名。 这必须与服务器配置中指定的Kerberos认证服务名称匹配,才能成功进行认证。 (另请参见。) 默认值通常为postgres, - 但在构建PostgreSQL时可以通过 - 选项进行更改 - configure。 + 但在构建 PostgreSQL 时,可以通过 configure 选项更改。 在大多数环境中,通常不需要更改此参数。 一些Kerberos实现可能需要不同的服务名称, 例如Microsoft Active Directory需要服务名称为大写(POSTGRES)。 @@ -1590,23 +1532,21 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 连接状态函数 - 这些函数可以被用来询问一个已有数据库连接对象的状态。 + 这些函数可用于查询现有数据库连接对象的状态。 - libpq-fe.h - libpq-int.h - libpq应用程序员应该小心地维护PGconn抽象。使用下面描述的访问函数来理解PGconn的内容。我们不推荐使用libpq-int.h引用内部的PGconn域,因为它们可能在未来改变。 - + libpq-fe.h + libpq-int.h + 编写 libpq 应用程序时,应注意维护 PGconn 的抽象。请使用下述访问函数获取 PGconn 的内容。不建议通过 libpq-int.h 引用 PGconn 的内部字段,因为这些字段将来可能改变。 + - 下列函数返回一个连接所建立的参数值。这些值在连接的生命期中是固定的。 - 如果使用的是多主机连接字符串,如果使用同一个PGconn对象建立新连接,,, 和 可能会改变。其他值在PGconn对象的一生中都是固定的。 - - + 以下函数返回建立连接时确定的参数值。这些值在连接存续期间保持不变。如果使用多主机连接字符串,并使用同一个 PGconn 对象建立新连接,则 的返回值可能改变。其他值在 PGconn 对象的整个生命周期内保持不变。 + PQdbPQdb @@ -1656,7 +1596,7 @@ char *PQpass(const PGconn *conn); - 返回活跃连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 + 返回活动连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 char *PQhost(const PGconn *conn); @@ -1668,7 +1608,7 @@ char *PQhost(const PGconn *conn); - 如果conn参数是NULL,则返回NULL。否则,如果有一个错误产生主机信息(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成主机信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1689,8 +1629,7 @@ char *PQhostaddr(const PGconn *conn); - 如果conn 参数为 NULL 返回 NULL 。 - 否则,如果生成主机信息时出现错误(如果连接尚未完全建立或出现错误),则返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成主机信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1700,7 +1639,7 @@ char *PQhostaddr(const PGconn *conn); - 返回活跃连接的端口。 + 返回活动连接的端口。 char *PQport(const PGconn *conn); @@ -1712,7 +1651,7 @@ char *PQport(const PGconn *conn); - 如果conn参数是NULL,则返回NULL。否则,如果有一个错误产生端口信息(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成端口信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1726,9 +1665,7 @@ char *PQport(const PGconn *conn); - 这个函数不再做任何事,但是它保持了向后兼容。 - 这个函数总是返回一个空字符串,或者NULL,如果connNULL。 - + 此函数已不再执行任何操作,但为保持向后兼容仍予以保留。如果 conn 参数为 NULL,则返回 NULL;否则始终返回空字符串。 char *PQtty(const PGconn *conn); @@ -1741,7 +1678,7 @@ char *PQtty(const PGconn *conn); - 返回被传递给连接请求的命令行选项。 + 返回连接请求中传递的命令行选项。 char *PQoptions(const PGconn *conn); @@ -1749,12 +1686,11 @@ char *PQoptions(const PGconn *conn); - + - 下列函数返回会随着在PGconn对象上执行的操作改变的状态数据。 - - + 以下函数返回的状态数据,可能随着对 PGconn 对象执行操作而改变。 + PQstatusPQstatus @@ -1790,7 +1726,7 @@ ConnStatusType PQstatus(const PGconn *conn); PGTransactionStatusType PQtransactionStatus(const PGconn *conn); - 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个合法的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接损坏,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE。 + 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个有效的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接异常,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE @@ -1831,13 +1767,11 @@ const char *PQparameterStatus(const PGconn *conn, const char *paramName); - 询问所使用的 前端/后端协议。 + 查询正在使用的前端/后端协议。 int PQprotocolVersion(const PGconn *conn); - 应用可能希望用这个函数来确定某些特性是否被支持。当前,可能值是3(3.0 协议)或零(连接损坏)。 - 协议版本在连接启动完成后将不会改变,但是理论上在连接重置期间是可以改变的。 - 3.0 协议被PostgreSQL 7.4 或以后的服务器版本所支持。 +应用程序可以使用此函数判断是否支持某些特性。目前,可能的值为 3(协议 3.0)或零(连接异常)。连接启动完成后,协议版本不会改变,但理论上可能在连接重置期间改变。PostgreSQL 7.4 及更高版本的服务器支持协议 3.0。 @@ -1858,11 +1792,11 @@ int PQserverVersion(const PGconn *conn); - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 + 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,为每个部分使用两位数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 + 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。在所有主版本系列中,各次版本(缺陷修复版本)之间只有最后两位数字不同。 @@ -1881,9 +1815,7 @@ char *PQerrorMessage(const PGconn *conn); - 几乎所有的libpq在失败时都会为设置一个消息。 - 注意按照libpq习惯,一个非空结果由多行构成,并且将包括一个尾部新行。 - 调用者不应该直接释放结果。当相关的PGconn句柄被传递给时,它将被释放。在PGconn结构体上的多个操作之间,不能指望结果字符串会保持不变。 + 几乎所有 libpq 函数在失败时都会设置一条供 返回的消息。注意,按照 libpq 的约定,非空的 结果可能包含多行,并以换行符结尾。调用者不应直接释放该结果;当关联的 PGconn 句柄被传给 时,结果会被释放。不能假定在对 PGconn 结构体执行其他操作后,结果字符串仍保持不变。 @@ -1892,7 +1824,7 @@ char *PQerrorMessage(const PGconn *conn); PQsocketPQsocket - 获得到服务器连接套接字的文件描述符号。一个合法的描述符将会大于等于零。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 + 获取与服务器相连的套接字的文件描述符编号。有效描述符大于或等于 0。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 int PQsocket(const PGconn *conn); @@ -1909,7 +1841,7 @@ int PQsocket(const PGconn *conn); 返回处理这个连接的后端进程的进程ID(PID)。 PID 确定服务器进程的 PID - in libpq + 在 libpq 中 @@ -1918,7 +1850,7 @@ int PQbackendPID(const PGconn *conn); - 后端PID有助于调试目的并且可用于与NOTIFY消息(它包括发出提示的后端进程的PID)进行比较。注意PID属于一个在数据库服务器主机上执行的进程,而不是本地主机进程! + 后端 PID 可用于调试,也可与 NOTIFY 消息进行比较(消息包含发出通知的后端进程的 PID)。注意,该 PID 属于在数据库服务器主机上运行的进程,而非本地主机上的进程! @@ -1957,19 +1889,18 @@ int PQconnectionUsedPassword(const PGconn *conn); - + - 以下函数返回与SSL相关的信息。这些信息通常在建立连接后不会更改。 - - + 以下函数返回与 SSL 相关的信息。这些信息通常在连接建立后不会改变。 + PQsslInUsePQsslInUse - 返回true(1)如果连接使用SSL,返回false(0)如果不使用。 + 如果连接使用 SSL,则返回真(1);否则返回假(0)。 int PQsslInUse(const PGconn *conn); @@ -1985,7 +1916,7 @@ int PQsslInUse(const PGconn *conn); - 返回与连接相关的SSL信息。 + 返回连接的 SSL 相关信息。 const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); @@ -1993,11 +1924,11 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); - 可用属性列表因使用的SSL库和连接类型而异。如果连接不使用SSL或指定的属性名称对于所使用的库未定义,则返回NULL。 + 可用属性列表因所使用的 SSL 库和连接类型而异。如果某个属性不可用,则返回 NULL。 - 常见的属性如下: + 通常可以获取以下属性: library @@ -2043,12 +1974,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); - - 作为一个特例,可以在没有连接的情况下通过将NULL作为conn参数来查询library属性。 - 结果将是默认的SSL库名称,或者如果libpq在没有任何SSL支持的情况下编译,则为NULL。 - (在PostgreSQL版本15之前,将NULL作为conn参数传递总是导致NULL。 - 需要区分这种情况的新旧实现的客户端程序可以检查LIBPQ_HAS_SSL_LIBRARY_DETECTION特征宏。) - + @@ -2073,18 +1999,14 @@ const char * const * PQsslAttributeNames(const PGconn *conn); - 返回一个指向描述连接的SSL实现特定对象的指针。如果连接未加密或SSL实现不提供连接的请求对象类型,则返回NULL。 + 返回指向描述此连接的对象的指针,该对象的类型由 SSL 实现决定。 void *PQsslStruct(const PGconn *conn, const char *struct_name); - 可用的结构体取决于正在使用的SSL实现。 - 对于OpenSSL,有一个结构体, - 可以通过名称OpenSSL获得, - 并返回一个指向OpenSSLSSL结构体的指针。 - 要使用这个函数,可以使用以下代码: + 可用的结构体取决于所使用的 SSL 实现。对于 OpenSSL,可以通过名称 "OpenSSL" 获取一个结构体,函数返回指向 OpenSSLSSL 结构体的指针。可以使用如下代码调用此函数: #include @@ -2135,7 +2057,7 @@ void *PQgetssl(const PGconn *conn); - + @@ -2144,7 +2066,7 @@ void *PQgetssl(const PGconn *conn); 命令执行函数 - 一旦到一个数据库服务器的连接被成功建立,这里描述的函数可以被用来执行 SQL 查询和命令。 + 与数据库服务器的连接成功建立后,此处描述的函数用于执行 SQL 查询和命令。 @@ -2166,11 +2088,8 @@ PGresult *PQexec(PGconn *conn, const char *command); - 返回一个PGresult指针或者可能是一个空指针。 - 除了内存不足的情况或者由于严重错误无法将命令发送给服务器之外,一般都会返回一个非空指针。 - 函数应当被调用来检查返回值是否代表错误(包括空指针的值,它会返回PGRES_FATAL_ERROR)。 - 用可得到关于那些错误的详细信息。 - + 返回一个 PGresult 指针,也可能返回空指针。除内存不足或无法向服务器发送命令等严重错误外,通常都会返回非空指针。应调用 函数检查返回值是否表示错误(也应检查空指针,此时该函数返回 PGRES_FATAL_ERROR)。使用 获取此类错误的更多信息。 + @@ -2251,8 +2170,8 @@ PGresult *PQexecParams(PGconn *conn, paramValues[] - 指定参数的实际值。这个数组中的一个空指针表示对应的参数为空,否则该指针指向一个以零终止的文本字符串(用于文本格式)或者以服务器所期待格式的二进制数据(用于二进制格式)。 - + 指定参数的实际值。数组中的空指针表示对应参数为 null;否则,指针指向以零结尾的文本字符串(文本格式),或采用服务器所要求格式的二进制数据(二进制格式)。 + @@ -2260,8 +2179,8 @@ PGresult *PQexecParams(PGconn *conn, paramLengths[] - 指定二进制格式参数的实际数据长度。它对空参数和文本格式参数被忽略。当没有二进制参数时,该数组指针可以为空。 - + 指定二进制格式参数的实际数据长度。对于 null 参数和文本格式参数,该值会被忽略。如果没有二进制参数,数组指针可以为空指针。 + @@ -2269,11 +2188,11 @@ PGresult *PQexecParams(PGconn *conn, paramFormats[] - 指定参数是否为文本(在参数相应的数组项中放一个零)或二进制(在参数相应的数组项中放一个一)。如果该数组指针为空,那么所有参数都会被假定为文本串。 - + 指定参数采用文本格式(在对应数组元素中填入零)还是二进制格式(填入一)。如果数组指针为空指针,则将所有参数视为文本字符串。 + - 以二进制格式传递的值要求后端所期待的内部表示形式的知识。例如,整数必须以网络字节序被传递。传递numeric值要求关于服务器存储格式的知识,正如src/backend/utils/adt/numeric.c::numeric_send()以及src/backend/utils/adt/numeric.c::numeric_recv()中所实现的。 - + 以二进制格式传递值时,需要了解后端所要求的内部表示形式。例如,整数必须以网络字节序传递。传递 numeric 值时,需要了解服务器的存储格式,其实现见 src/backend/utils/adt/numeric.c::numeric_send()src/backend/utils/adt/numeric.c::numeric_recv()。 + @@ -2281,8 +2200,8 @@ PGresult *PQexecParams(PGconn *conn, resultFormat - 指定零来得到文本格式的结果,或者指定一来得到二进制格式的结果(目前没有规定要求以不同格式得到不同的结果列,尽管在底层协议中这是可以实现的)。 - + 指定零以获取文本格式的结果,指定一以获取二进制格式的结果。(目前无法让不同结果列使用不同格式,尽管底层协议支持这样做。) + @@ -2293,8 +2212,8 @@ PGresult *PQexecParams(PGconn *conn, - 相对于的主要优点是参数值可以从命令串中分离,因此避免了冗长的书写、容易发生错误的引用以及转义。 - + 相对于 的主要优点是可以将参数值与命令字符串分开,从而避免繁琐且容易出错的加引号和转义工作。 + 不同,至多允许在给定串中出现一个 SQL 命令(其中可以有分号,但是不能有超过一个非空命令)。这是底层协议的一个限制,但是有助于抵抗 SQL 注入攻击。 @@ -2303,12 +2222,12 @@ PGresult *PQexecParams(PGconn *conn, - 通过 OID 指定参数类型很罗嗦,特别是如果你不愿意将特定的 OID 值硬编码到你的程序中时。不过,即使服务器本身也无法确定参数的类型,你可以避免这样做,或者选择一种与你想要的不同的类型。在 SQL 命令文本中,附加一个显式类型转换给参数符号来表示你将发送什么样的数据类型。例如: + 通过 OID 指定参数类型较为繁琐,尤其是在不希望将具体 OID 值写死在程序中时。不过,即使服务器无法自行确定参数类型,或者推断出的类型与你所需的不同,也可以避免直接指定 OID。在 SQL 命令文本中,为参数符号添加显式类型转换,即可指定要发送的数据类型。例如: SELECT * FROM mytable WHERE x = $1::bigint; - 这强制参数$1被当作bigint,而默认情况下它将被赋予与x相同的类型。当以二进制格式发送参数值时,我们强烈推荐以这种方式或通过指定一个数字类型的 OID 来强制参数类型决定。因为二进制格式比文本格式具有更少的冗余,并且因此服务器将不会有更多机会为你检测一个类型匹配错误。 - +这会强制将参数 $1 当作 bigint,而默认情况下会为它分配与 x 相同的类型。以二进制格式发送参数值时,强烈建议采用这种方式,或直接指定类型的数值 OID,来明确决定参数类型。因为二进制格式的冗余比文本格式更少,服务器发现类型不匹配错误的机会也更少。 + @@ -2329,15 +2248,15 @@ PGresult *PQprepare(PGconn *conn, - 创建一个后面会由执行的预备语句。 + 创建一个预备语句,供随后使用 执行。 这个特性允许命令被反复执行而无需每次都进行解析和规划,详见。 - + 该函数从query串创建一个名为stmtName的预备语句,该串必须包含一个单一 SQL 命令。 stmtName可以是""来创建一个未命名语句,在这种情况下任何已存在未命名语句将被自动替换。 否则,如果语句名称已经在当前会话中被定义,则是一种错误。如果使用了任何参数,它们在查询中以$1$2等引用。 - nParams是参数的个数,其类型在数组paramTypes[]中被预先指定(当nParams为零时,该数组指针可以是NULL)。 + nParams 是在数组 paramTypes[] 中预先指定了类型的参数数量(当nParams为零时,该数组指针可以是NULL)。 paramTypes[]通过 OID 指定要赋予给参数符号的数据类型。 如果paramTypesNULL或者该数组中任何特定元素为零,服务器会用对待未指定类型的字符串字面量的方式为参数符号推测一种数据类型。 还有,查询能够使用编号高于nParams的参数符号,它们的数据类型也会被自动推测(找出推测出的数据类型的方法见)。 @@ -2345,7 +2264,7 @@ PGresult *PQprepare(PGconn *conn, 正如一样,结果通常是一个PGresult对象,其内容代表服务器端成功或失败。 - 一个空结果表示内存不足或者根本无法发送命令。关于错误的更多信息请见。 + 返回空指针表示内存不足,或者根本无法发送命令。关于错误的更多信息请见 @@ -2378,9 +2297,9 @@ PGresult *PQexecPrepared(PGconn *conn, 类似于, - 但要执行的命令是通过指定先前准备好的语句来指定,而不是提供查询字符串。 - 此功能允许重复使用的命令只被解析和计划一次,而不是每次执行时都要进行。 - 该语句必须在当前会话中先前准备好。 + 但它通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。 + 此功能使重复使用的命令只需解析和规划一次,而不必在每次执行时都进行这些工作。 + 该语句必须事先在当前会话中创建为预备语句。 @@ -2397,23 +2316,23 @@ PGresult *PQexecPrepared(PGconn *conn, - 提交请求以获取有关指定准备好的语句的信息,并等待完成。 + 提交请求以获取有关指定预备语句的信息,并等待完成。 PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - 允许应用程序获取关于先前准备的语句的信息。 + 允许应用程序获取关于先前创建的预备语句的信息。 stmtName可以是""NULL来引用 - 未命名的语句,否则必须是现有准备好的语句的名称。成功时,返回一个 + 未命名的语句,否则必须是现有预备语句的名称。成功时,返回一个 状态为PGRES_COMMAND_OKPGresult。 函数可以应用于此 - PGresult以获取有关准备语句参数的信息, + PGresult以获取有关预备语句参数的信息, 函数等提供有关语句的结果列(如果有)的信息。 @@ -2427,16 +2346,15 @@ PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - 提交请求以获取有关指定门户的信息,并等待完成。 + 提交请求以获取有关指定 portal 的信息,并等待完成。 PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - 允许应用程序获取有关先前创建的 portal 的信息。 - (libpq不直接提供对 portal 的访问,但你可以使用此函数检查通过DECLARE CURSOR SQL 命令创建的游标的属性。) - + 允许应用程序获取先前创建的 portal 的信息。(libpq 不提供对 portal 的直接访问,但可以用此函数检查通过 DECLARE CURSOR SQL 命令创建的游标的属性。) + portalName可以是""NULL来引用未命名的 portal, @@ -2454,9 +2372,8 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - PGresultPGresult结构体封装了由服务器返回的结果。libpq应用程序员应该小心地维护PGresult的抽象。使用下面的存储器函数来得到PGresult的内容。避免直接引用PGresult结构体的域,因为它们可能在未来更改。 - - + PGresultPGresult 结构体封装服务器返回的结果。编写 libpq 应用程序时,应注意维护 PGresult 的抽象。请使用下述访问函数获取 PGresult 的内容。避免直接引用 PGresult 结构体的字段,因为这些字段将来可能改变。 + PQresultStatusPQresultStatus @@ -2557,7 +2474,7 @@ ExecStatusType PQresultStatus(const PGresult *res); PGRES_SINGLE_TUPLE - PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单一行模式时发生(见)。 + PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单行模式时发生(见)。 @@ -2583,7 +2500,7 @@ ExecStatusType PQresultStatus(const PGresult *res); - 如果结果状态是PGRES_TUPLES_OKPGRES_SINGLE_TUPLEPGRES_TUPLES_CHUNK,则可以使用下面描述的函数来提取查询返回的行。注意,恰好检索到零行的SELECT命令仍然显示为PGRES_TUPLES_OKPGRES_COMMAND_OK用于永远不会返回行的命令(例如没有RETURNING子句的INSERTUPDATE等)。返回PGRES_EMPTY_QUERY可能表示客户端软件中存在缺陷。 + 如果结果状态是PGRES_TUPLES_OKPGRES_SINGLE_TUPLE,则可以使用下面描述的函数来提取查询返回的行。注意,恰好检索到零行的SELECT命令仍然显示为PGRES_TUPLES_OKPGRES_COMMAND_OK用于永远不会返回行的命令(例如没有RETURNING子句的INSERTUPDATE等)。返回PGRES_EMPTY_QUERY可能表示客户端软件中存在缺陷。 @@ -2597,12 +2514,11 @@ ExecStatusType PQresultStatus(const PGresult *res); - 将返回的枚举转换成描述状态编码的字符串常量。调用者不应该释放结果。 - + 将 返回的枚举值转换为描述该状态码的字符串常量。调用者不应释放此结果。 char *PQresStatus(ExecStatusType status); - + @@ -2611,12 +2527,12 @@ char *PQresStatus(ExecStatusType status); - 返回与该命令相关的错误消息,如果有错误则会返回一个空字符串。 + 返回与命令关联的错误消息;如果没有错误,则返回空字符串。 char *PQresultErrorMessage(const PGresult *res); - 如果有一个错误,被返回的字符串将包含一个收尾的新行。调用者不应该直接释放结果。它将在相关的PGresult句柄被传递给之后被释放。 - +如果发生了错误,返回的字符串会以换行符结尾。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 + 紧跟着一个调用,(在连接上)将返回与相同的字符串(在结果上)。 @@ -2632,16 +2548,14 @@ char *PQresultErrorMessage(const PGresult *res); - 返回与PGresult对象相关的错误消息的重新格式化的版本。 + 返回与 PGresult 对象关联的错误消息的重新格式化版本。 char *PQresultVerboseErrorMessage(const PGresult *res, PGVerbosity verbosity, PGContextVisibility show_context); - 在有些情况下,客户端可能希望得到之前报告过的错误的更加详尽的版本。 - 如果在产生给定PGresult的连接上 verbosity 设置有效,会通过计算已经被产生过的消息来满足这种需求。 - 如果PGresult不是一个错误结果,则会报告PG 结果不是错误结果。返回的字符串包括一个新行作为结尾。 - +有时客户端希望获取先前报告过的错误的更详细版本。 可满足这一需求:它按指定的详细程度设置重新生成消息。假如在生成给定 PGresult 时,连接已经采用这些设置,那么 返回的就会是这条消息。如果 PGresult 不是错误结果,则改为报告 PGresult is not an error result。返回的字符串以换行符结尾。 + 和大部分从PGresult中提取数据的其他函数不同,这个函数的结果是一个全新分配的字符串。调用者在不需要这个字符串以后,必须使用PQfreemem()释放它。 @@ -2657,24 +2571,21 @@ char *PQresultVerboseErrorMessage(const PGresult *res, PQresultErrorFieldPQresultErrorField - 返回一个错误报告的一个域。 + 返回错误报告中的单个字段。 char *PQresultErrorField(const PGresult *res, int fieldcode); - fieldcode是一个错误域标识符,见下列符号。 - 如果PGresult不是一个错误或者警告结果或者不包括指定域,会返回NULL。 - 域通常不包括一个收尾的新行。调用者不应该直接释放结果。 - 它将在相关的PGresult句柄被传递给之后被释放。 - +fieldcode 是错误字段标识符,参见下文列出的符号。如果 PGresult 不是错误或警告结果,或者不包含指定字段,则返回 NULL。字段值通常不含末尾换行符。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 + - 下列域代码可用: + 下列字段代码可用: PG_DIAG_SEVERITY - 严重性。域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 @@ -2683,17 +2594,17 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_SEVERITY_NONLOCALIZED - 域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY域相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 版本以后产生的报告中。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY字段相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 及更高版本产生的报告中。 PG_DIAG_SQLSTATEerror codeslibpq + >错误码libpq - 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个域无法被本地化,并且总是存在。 + 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个字段无法被本地化,并且总是存在。 @@ -2720,7 +2631,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_MESSAGE_HINT - 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是铁的事实。可能有多行。 + 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是确切事实。可能有多行。 @@ -2738,7 +2649,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_INTERNAL_POSITION - 这被定义为与PG_DIAG_STATEMENT_POSITION域相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个域出现时,PG_DIAG_INTERNAL_QUERY域将总是出现。 + 这被定义为与PG_DIAG_STATEMENT_POSITION字段相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个字段出现时,PG_DIAG_INTERNAL_QUERY字段将总是出现。 @@ -2756,7 +2667,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONTEXT - 指示错误发生的环境。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 + 指示错误发生的上下文。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 @@ -2774,7 +2685,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_TABLE_NAME - 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名域)。 + 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名字段)。 @@ -2783,7 +2694,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_COLUMN_NAME - 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名域来标识该表)。 + 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名字段来标识该表)。 @@ -2792,7 +2703,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_DATATYPE_NAME - 如果错误与一个特定数据类型相关,这里是该数据了行的名字(该数据类型的模式名参考模式名域)。 + 如果错误与一个特定数据类型相关,这里是该数据类型的名字(该数据类型的模式名参考模式名字段)。 @@ -2801,7 +2712,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONSTRAINT_NAME - 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的域(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 + 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的字段(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 @@ -2837,16 +2748,16 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); - 用于模式名、表名、列名、数据类型名和约束名的域只提供给有限的错误类型,见。不要假定任何这些域的存在保证另一个域的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些域。同样地,不要假定这些域代表当前数据库中同类的对象。 + 用于模式名、表名、列名、数据类型名和约束名的字段只提供给有限的错误类型,见。不要假定任何这些字段的存在保证另一个字段的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些字段。同样地,不要假定这些字段代表当前数据库中现存的对象。 - 客户端负责格式化显示信息来迎合它的需要,特别是根据需要打断长的行。出现在错误消息域中的新行字符应该被当作分段而不是换行。 + 客户端负责按自身需要格式化所显示的信息,尤其应在需要时将长行折行。错误消息字段中的换行符应当视为段落分隔,而非行分隔。 - libpq内部产生的错误将有严重和主要消息,但是通常没有其他域。 + libpq内部产生的错误将包含严重性和主要消息,但是通常没有其他字段。 @@ -2859,14 +2770,11 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PQclearPQclear - 释放与一个PGresult关联的存储。每个命令结果在不再需要时都应通过释放。 - + 释放与 PGresult 关联的存储空间。每个命令结果在不再需要时都应通过 释放。 void PQclear(PGresult *res); - - 如果参数是NULL指针,则不会执行任何操作。 - + 你可以在需要时一直保留PGresult对象;它不会在你发出新命令时消失,甚至在关闭连接后也不会消失。要销毁它,你必须调用。否则应用程序会发生内存泄漏。 @@ -2874,7 +2782,7 @@ void PQclear(PGresult *res); - + @@ -2882,8 +2790,8 @@ void PQclear(PGresult *res); 检索查询结果信息 - 这些函数被用来从一个代表成功查询结果(也就是状态为PGRES_TUPLES_OK或者PGRES_SINGLE_TUPLE)的PGresult对象中抽取信息。它们也可以被用来从一个成功的 Describe 操作中抽取信息:一个 Describe 的结果具有和该查询被实际执行所提供的完全相同的列信息,但是它没有行。对于其他状态值的对象,这些函数会认为结果具有零行和零列。 - + 这些函数用于从表示成功查询结果的 PGresult 对象中提取信息,即状态为 PGRES_TUPLES_OKPGRES_SINGLE_TUPLE 的对象。它们也可用于提取成功 Describe 操作的结果信息:Describe 结果包含的列信息与实际执行查询时相同,但行数为零。对于其他状态值的对象,这些函数会将结果视为零行、零列。 + @@ -2910,7 +2818,7 @@ int PQntuples(const PGresult *res); - 返回查询结果中每一行的列(域)数。 + 返回查询结果中每一行的列(字段)数。 int PQnfields(const PGresult *res); @@ -2926,7 +2834,7 @@ int PQnfields(const PGresult *res); - 返回与给定列号相关联的列名。列号从 0 开始。调用者不应该直接释放该结果。它将在相关的PGresult句柄被传递给之后被释放。 + 返回给定列号对应的列名。列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 char *PQfname(const PGresult *res, int column_number); @@ -2958,11 +2866,11 @@ int PQfnumber(const PGresult *res, - 给定的名称被视作一个 SQL 命令中的一个标识符,也就是说,除非被双引号引用,它是小写形式的。例如,给定一个 SQL 命令: + 给定名称按 SQL 命令中的标识符处理,即除非用双引号引用,否则会转换为小写。例如,对于以下 SQL 命令生成的查询结果: SELECT 1 AS FOO, 2 AS "BAR"; - 我们将得到结果: +会得到以下结果: PQfname(res, 0) foo PQfname(res, 1) BAR @@ -2982,7 +2890,7 @@ PQfnumber(res, "\"BAR\"") 1 - 返回给定列从中取出的表的 OID。列号从 0 开始。 + 返回给定列所取自的表的 OID。列号从 0 开始。 Oid PQftable(const PGresult *res, int column_number); @@ -2995,7 +2903,7 @@ Oid PQftable(const PGresult *res, - 当你包括libpq头文件,类型oid以及常数InvalidOid将被定义。它们将都是某种整数类型。 + 包含 libpq 头文件后,将定义类型 Oid 和常量 InvalidOid。它们都属于某种整数类型。 @@ -3007,7 +2915,7 @@ Oid PQftable(const PGresult *res, - 返回构成指定查询结果列的列(在其表中)的列号。查询结果列号从 0 开始,但是表列具有非零编号。 + 返回指定查询结果列所对应的表列在表中的列号。查询结果的列号从 0 开始,而表列的编号非零。 int PQftablecol(const PGresult *res, int column_number); @@ -3027,7 +2935,7 @@ int PQftablecol(const PGresult *res, - 返回指示给定列格式的格式编码。列号从 0 开始。 + 返回表示给定列格式的格式代码。列号从 0 开始。 int PQfformat(const PGresult *res, int column_number); @@ -3035,7 +2943,7 @@ int PQfformat(const PGresult *res, - 格式代码零指示文本数据表示,而格式代码一表示二进制表示(其他代码被保留用于未来的定义)。 + 格式代码零表示文本数据,格式代码一表示二进制数据。(其他代码保留供将来定义。) @@ -3055,7 +2963,7 @@ Oid PQftype(const PGresult *res, - 你可以查询系统表pg_type来得到多个数据类型的名字和属性。 + 你可以查询系统表pg_type来获取各种数据类型的名称和属性。 内置数据类型的OID被定义在PostgreSQL安装的include目录中的catalog/pg_type_d.h文件中。 @@ -3068,7 +2976,7 @@ Oid PQftype(const PGresult *res, - 返回与给定列号相关联的列的修饰符类型。列号从 0 开始。 + 返回与给定列号相关联的列的类型修饰符。列号从 0 开始。 int PQfmod(const PGresult *res, int column_number); @@ -3076,7 +2984,7 @@ int PQfmod(const PGresult *res, - 修饰符值的解释是与类型相关的,它们通常指示精度或尺寸限制。值 -1 被用来指示没有信息可用。大部分的数据类型不适用修饰符,在那种情况中值总是 -1。 + 修饰符值的含义由数据类型决定,通常表示精度或大小限制。值 -1 表示没有可用信息。大多数数据类型不使用修饰符,此时该值始终为 -1。 @@ -3088,7 +2996,7 @@ int PQfmod(const PGresult *res, - 返回与给定列号相关的列的尺寸(以字节计)。列号从 0 开始。 + 返回给定列号对应列的大小,以字节计。列号从 0 开始。 int PQfsize(const PGresult *res, int column_number); @@ -3096,7 +3004,7 @@ int PQfsize(const PGresult *res, - 返回在一个数据库行中为这个列分配的空间,换句话说是服务器对该数据类型的内部表示的尺寸(因此,它对客户端并不是真地非常有用)。一个负值指示该数据类型是变长的。 + 返回数据库行中为该列分配的空间,即服务器内部表示该数据类型所需的大小。(因此,它对客户端用处不大。)负值表示该数据类型是变长类型。 @@ -3115,8 +3023,7 @@ int PQbinaryTuples(const PGresult *res); - 这个函数已经被废弃(除了与COPY一起使用),因为一个单一PGresult可以在某些列中包含文本数据而且在另一些列中包含二进制数据。 - 要更好。只有结果的所有列是二进制(格式 1)时才返回 1。 + 此函数已弃用(与 COPY 配合使用的情况除外),因为单个 PGresult 可能在部分列中包含文本数据,而在其他列中包含二进制数据。推荐使用 。只有结果中的所有列都采用二进制格式(格式 1)时, 才返回 1。 @@ -3128,8 +3035,7 @@ int PQbinaryTuples(const PGresult *res); - 返回一个PGresult的一行的单一域值。行和列号从 0 开始。调用者不应该直接释放该结果。 - 它将在相关的PGresult句柄被传递给之后被释放。 + 返回 PGresult 中某一行的单个字段值。行号和列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 char *PQgetvalue(const PGresult *res, int row_number, @@ -3138,15 +3044,15 @@ char *PQgetvalue(const PGresult *res, - 对于文本格式的数据,返回的值是该域值的一种空值结束的字符串表示。对于二进制格式的数据,该值是由该数据类型的typsendtypreceive函数决定的二进制表示(在这种情况下该值实际上也跟随着一个零字节,但是这通常没有用处,因为该值很可能包含嵌入的空)。 + 对于文本格式的数据, 返回字段值的字符串表示,以零字节结尾。对于二进制格式的数据,返回值采用该数据类型的 typsendtypreceive 函数所决定的二进制表示。(这种情况下,值后面实际上也有一个零字节,但通常没有用处,因为值本身很可能包含零字节。) - 如果该域值为空,则返回一个空串。关于区分空值和空字符串值请见。 + 如果字段值为 null,则返回空字符串。关于如何区分 null 值与空字符串值,参见 - 返回的指针指向作为PGresult结构体一部分的存储。我们不应该修改它指向的数据,并且如果要在超过PGresult结构体本身的生命期之外使用它,我们必须显式地把该数据拷贝到其他存储中。 + 返回的指针指向属于 PGresult 结构体的存储空间。不应修改它所指向的数据;如果需要在 PGresult 结构体的生命周期结束后继续使用这些数据,就必须显式地将数据复制到其他存储空间。 @@ -3155,12 +3061,12 @@ char *PQgetvalue(const PGresult *res, PQgetisnullPQgetisnullnull valuein libpq + >null 值libpq 中的 - 测试一个域是否为空值。行号和列号从 0 开始。 + 检查字段是否为 null 值。行号和列号从 0 开始。 int PQgetisnull(const PGresult *res, int row_number, @@ -3169,7 +3075,7 @@ int PQgetisnull(const PGresult *res, - 如果该域是空,这个函数返回 1。如果它包含一个非空值,则返回 0(注意将为一个空域返回一个空串,不是一个空指针)。 + 如果字段为 null,此函数返回 1;如果包含非 null 值,则返回 0。(注意,对于 null 字段, 返回空字符串,而非空指针。) @@ -3181,7 +3087,7 @@ int PQgetisnull(const PGresult *res, - 返回一个域值的真实长度,以字节计。行号和列号从 0 开始。 + 返回字段值的实际长度,以字节计。行号和列号从 0 开始。 int PQgetlength(const PGresult *res, int row_number, @@ -3190,9 +3096,7 @@ int PQgetlength(const PGresult *res, - 这是特定数据值的真实数据长度,也就是指向的对象的尺寸。 - 对于文本数据格式,这和strlen()相同。对于二进制格式这是基本信息。 - 注意我们应该依赖于来得到真值的数据长度。 + 这是该数据值的实际数据长度,即 所指对象的大小。对于文本格式的数据,它与 strlen() 的结果相同。对于二进制格式,这是必不可少的信息。注意,不应依赖 来获取实际数据长度。 @@ -3242,29 +3146,29 @@ Oid PQparamtype(const PGresult *res, int param_number); - 将所有的行打印到指定的输出流,以及有选择地将列名打印到指定的输出流。 + 将所有行输出到指定的输出流,并可选择输出列名。 void PQprint(FILE *fout, /* 输出流 */ const PGresult *res, const PQprintOpt *po); typedef struct { - pqbool header; /* 打印输出域标题和行计数 */ - pqbool align; /* 填充对齐域 */ - pqbool standard; /* 旧的格式 */ + pqbool header; /* 打印输出字段标题和行数 */ + pqbool align; /* 填充并对齐字段 */ + pqbool standard; /* 旧的简陋格式 */ pqbool html3; /* 输出 HTML 表格 */ - pqbool expanded; /* 扩展表格 */ - pqbool pager; /* 如果必要为输出使用页 */ - char *fieldSep; /* 域分隔符 */ + pqbool expanded; /* 展开表格 */ + pqbool pager; /* 需要时使用分页器输出 */ + char *fieldSep; /* 字段分隔符 */ char *tableOpt; /* 用于 HTML 表格元素的属性 */ char *caption; /* HTML 表格标题 */ - char **fieldName; /* 替换域名称的空终止数组 */ + char **fieldName; /* 以空指针结尾的替换字段名数组 */ } PQprintOpt; - 这个函数以前被psql用来打印查询结果,但是现在不是这样了。注意它假定所有的数据都是文本格式。 + psql 以前用此函数打印查询结果,现在已不再使用。注意,此函数假定所有数据都是文本格式。 @@ -3313,13 +3217,7 @@ char *PQcmdTuples(PGresult *res); - 该函数返回一个字符串,其中包含由生成PGresultSQL语句影响的行数。 - 该函数只能在执行SELECTCREATE TABLE AS、 - INSERTUPDATEDELETE、 - MERGEMOVEFETCHCOPY语句, - 或包含INSERTUPDATEDELETEMERGE语句的预处理查询的EXECUTE之后使用。 - 如果生成PGresult的命令是其他任何命令,将返回一个空字符串。 - 调用者不应直接释放返回值。当关联的PGresult句柄传递给时,它将被释放。 + 此函数返回一个字符串,其中包含产生该 PGresultSQL 语句所影响的行数。此函数只能在执行 SELECTCREATE TABLE ASINSERTUPDATEDELETEMOVEFETCHCOPY 语句之后使用,也可以在对包含 INSERTUPDATEDELETE 语句的预备查询执行 EXECUTE 之后使用。如果产生 PGresult 的是其他命令, 将返回空字符串。调用者不应直接释放返回值;当关联的 PGresult 句柄被传给 时,返回值会被释放。 @@ -3331,7 +3229,7 @@ char *PQcmdTuples(PGresult *res); - 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDin libpq。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid。 + 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDlibpq 中的。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid Oid PQoidValue(const PGresult *res); @@ -3346,7 +3244,7 @@ Oid PQoidValue(const PGresult *res); - 这个函数已经被取代,并且不是线程安全的。它返回包含被插入行的 OID 的一个字符串,而返回 OID 值。 + 此函数不是线程安全的,现已弃用,推荐改用 。它返回包含插入行 OID 的字符串,而 返回 OID 值。 char *PQoidStatus(const PGresult *res); @@ -3364,7 +3262,7 @@ char *PQoidStatus(const PGresult *res); 转义字符串 - in libpq + libpq 中的 @@ -3382,17 +3280,13 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); 为了让一个字符串可用于 SQL 命令,会对它进行转义。 - 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜线)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 + 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜杠)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 执行这种操作。 - 返回一个str参数的已被转义版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - 返回字符串中的所有特殊字符都会被替换,这样它们就能被PostgreSQL字符串字面量解析器正确处理。 - 结果中也会附加一个终止零字节,并包含包围PostgreSQL字符串字面量所需的单引号。 - + 返回 str 参数的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便 PostgreSQL 字符串字面量解析器正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号包含在结果字符串中。 + 发生错误时,返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -3406,7 +3300,7 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); - 注意,当一个数据值被作为或其兄弟例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 + 注意,当一个数据值被作为或相关例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 @@ -3424,15 +3318,12 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - 转义一个要用作 SQL 标识符的字符串,例如表名、列名或函数名。当一个用户提供的标识符可能包含被 SQL 解析器解释为标识符一部分的特殊字符时,或者当该标识符可能包含大小写形式应该被保留的大写字符时,这个函数很有用。 - + 对字符串进行转义,使其可用作 SQL 标识符,例如表名、列名或函数名。当用户提供的标识符可能包含未经转义就不会被 SQL 解析器视为标识符一部分的特殊字符,或包含需要保留大小写的大写字符时,此函数很有用。 + - 返回一个str参数的已被转义为 SQL 标识符的版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - 返回串中的所有特殊字符都被替换掉,这样它们能被作为一个 SQL 标识符正确地处理。还会加上一个终止零字节。返回串也将被双引号包围。 - + 返回 str 参数作为 SQL 标识符的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,必须使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便正确地作为 SQL 标识符处理。还会添加一个末尾零字节,并用双引号包围返回的字符串。 + 发生错误时,返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -3441,7 +3332,7 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - 与字符串一样,要阻止 SQL 注入攻击,当从一个不可信的来源接收到 SQL 标识符时,它们必须被转义。 + 与字符串字面量一样,为防止 SQL 注入攻击,从不可信来源接收到的 SQL 标识符必须经过转义。 @@ -3462,18 +3353,12 @@ size_t PQescapeStringConn(PGconn *conn, - 转义字符串,它很像。 - 与不一样的是,调用者负责提供一个合适尺寸的缓冲区。 - 此外,不产生必须包围PostgreSQL字符串的单引号。 - 它们应该在结果要插入的 SQL 命令中提供。参数from指向要被转义的串的第一个字符,并且length参数给出了这个串中的字节数。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - to应当指向一个缓冲区,它能够保持至少比length值的两倍还要多至少一个字节,否则该行为是未被定义的。 - 如果tofrom串重叠,行为也是未被定义的。 - + 对字符串字面量进行转义,与 类似。与 不同,调用者需要提供大小合适的缓冲区。此外, 不会生成包围 PostgreSQL 字符串字面量所需的单引号;应在包含转义结果的 SQL 命令中提供这些引号。from 参数指向待转义字符串的首字符,length 参数给出该字符串的字节数。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)to 必须指向一个缓冲区,其容量至少为 length 的两倍加一个字节,否则行为未定义。如果 tofrom 字符串重叠,行为同样未定义。 + - 如果error参数不是NULL,那么成功时*error被设置为零,错误时设置为非零。当前唯一可能的错误情况涉及源串中非法的多字节编码。错误时仍然会产生输出串,但是可以预期服务器将认为它是畸形的并且拒绝它。在发生错误时,一个合适的消息被存储在conn对象中,不管error是不是NULL。 - + 如果 error 参数不是 NULL,则成功时将 *error 设为零,出错时设为非零。目前唯一可能的错误是源字符串中存在无效的多字节编码。出错时仍会生成输出字符串,但预计服务器会因其格式错误而拒绝它。发生错误时,无论 error 是否为 NULL,都会在 conn 对象中保存相应消息。 + 返回写到to的字节数,不包括终止的零字节。 @@ -3488,21 +3373,19 @@ size_t PQescapeStringConn(PGconn *conn, - 是一个更老的被废弃的版本。 + 的旧版本,现已弃用。 size_t PQescapeString (char *to, const char *from, size_t length); - + - 之间的唯一区别是不需要PGconnerror参数。 - 正因为如此,它不能基于连接属性(例如字符编码)调整它的行为并且因此它可能给出错误的结果。还有,它没有方法报告错误情况。 - + 与 唯一的区别是, 不接受 PGconnerror 参数。因此,它无法根据连接属性(例如字符编码)调整行为,可能给出错误的结果。此外,它也无法报告错误情况。 + - 可以在一次只使用一个PostgreSQL连接的客户端程序中安全地使用(在这种情况下它可以在现象后面找出它需要知道的东西)。 - 在其他环境中它是一个安全性灾难并且应该用来避免。 - + 可以在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。在其他情形下,它存在安全隐患,应改用 。 + @@ -3513,7 +3396,7 @@ size_t PQescapeString (char *to, const char *from, size_t length); - 把要用于一个 SQL 命令的二进制数据用类型bytea转义。和一样,只有在将数据直接插入到一个 SQL 命令串时才使用它。 + 对二进制数据进行转义,使其能够在 SQL 命令中用作 bytea 类型的值。与 一样,这仅用于将数据直接插入 SQL 命令字符串的情况。 unsigned char *PQescapeByteaConn(PGconn *conn, const unsigned char *from, @@ -3528,14 +3411,11 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - from参数指向要被转义的串的第一个字节,并且from_length参数给出这个二进制串中的字节数(一个终止的零字节是不需要的也是不被计算的)。to_length参数指向一个将保持生成的已转义串长度的变量。这个结果串长度包括结果的终止零字节。 + from 参数指向待转义字符串的首字节,from_length 参数给出该二进制字符串的字节数。(末尾零字节既不需要,也不计入长度。)to_length 参数指向用于保存转义后字符串长度的变量。该结果字符串长度包含结果末尾的零字节。 - 返回一个from参数的已被转义为二进制串的版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 返回串中的所有特殊字符都被替换掉,这样它们能被PostgreSQL的字符串解析器以及bytea输入函数正确地处理。 - 还会加上一个终止零字节。不是结果串一部分的PostgreSQL字符串必须被单引号包围。 + 返回 from 参数所指二进制字符串的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。返回字符串中的所有特殊字符都已替换,以便 PostgreSQL 字符串字面量解析器和 bytea 输入函数正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号不包含在结果字符串中。 @@ -3551,7 +3431,7 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - 是一个更老的被废弃的版本。 + 的旧版本,现已弃用。 unsigned char *PQescapeBytea(const unsigned char *from, size_t from_length, @@ -3560,9 +3440,7 @@ unsigned char *PQescapeBytea(const unsigned char *from, - 与的唯一区别是不用一个PGconn参数。 - 正因为这样,只能在一次只使用一个PostgreSQL连接的客户端程序中安全地使用(在这种情况下它可以在现象后面找出它需要知道的东西)。 - 如果在有多个数据库连接的程序中使用,它可能给出错误的结果(在那种情况下使用)。 + 与 唯一的区别是, 不接受 PGconn 参数。因此, 只能在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。如果在使用多个数据库连接的程序中使用,它可能给出错误的结果(此时应使用 )。 @@ -3634,21 +3512,15 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - 总是收集命令的整个结果,把它缓存在一个单一的PGresult中。虽然这简化了应用的错误处理逻辑,它对于包含很多行的结果并不现实。 - + 总是收集命令的完整结果,并将其缓存在单个 PGresult 中。这简化了应用程序的错误处理逻辑,但对于包含大量行的结果,可能不切实际。 + - 如果应用程序不希望受到这些限制,可以改用构成的底层函数:。此外,还有, - , - , - ,以及,它们可以与配合使用,分别实现以下函数的功能:, - , - , - ,以及。 - - + + 如果应用程序不希望受到这些限制,可以改用构成 的底层函数:。此外, 可以与 配合使用,分别实现 的功能。 + PQsendQueryPQsendQuery @@ -3656,18 +3528,15 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - 提交一个命令到服务器,而不等待结果。 - 如果成功发送命令,则返回1,如果失败则返回0(在这种情况下,使用获取更多关于失败的信息)。 + 向服务器提交命令,不等待结果。命令发送成功时返回 1,否则返回 0(此时可使用 获取更多失败信息)。 int PQsendQuery(PGconn *conn, const char *command); - - 成功调用后,调用一次或多次来获取结果。 - 在返回空指针,表示命令执行完成之前,无法再次调用(在同一连接上)。 +成功调用 后,应调用 一次或多次来获取结果。在 返回空指针、表明命令已完成之前,不得在同一连接上再次调用 - 在管道模式下,此函数被禁止使用。 + 在管道模式下,不允许命令字符串包含多个 SQL 命令。 @@ -3679,7 +3548,7 @@ int PQsendQuery(PGconn *conn, const char *command); - 提交一个命令和参数到服务器,而不等待结果。 + 向服务器提交命令及独立指定的参数,不等待结果。 int PQsendQueryParams(PGconn *conn, const char *command, @@ -3690,9 +3559,7 @@ int PQsendQueryParams(PGconn *conn, const int *paramFormats, int resultFormat); - - 这相当于,不同之处在于可以单独指定查询参数而不是与查询字符串一起指定。 - 函数的参数处理方式与完全相同。与一样,它在查询字符串中只允许一个命令。 +该函数等价于 ,但查询参数可以与查询字符串分开指定。函数参数的处理方式与 相同。与 一样,查询字符串中只允许包含一条命令。 @@ -3704,7 +3571,7 @@ int PQsendQueryParams(PGconn *conn, - 发送一个请求来创建一个带有给定参数的预备语句,而不等待完成。 + 发送按给定参数创建预备语句的请求,不等待完成。 int PQsendPrepare(PGconn *conn, const char *stmtName, @@ -3712,10 +3579,7 @@ int PQsendPrepare(PGconn *conn, int nParams, const Oid *paramTypes); - - 这是的异步版本:如果能够分派请求,则返回1,否则返回0。 - 成功调用后,调用来确定服务器是否成功创建了预备语句。 - 该函数的参数处理方式与完全相同。 +这是 的异步版本:请求发送成功时返回 1,否则返回 0。调用成功后,再调用 ,确定服务器是否成功创建了预备语句。函数参数的处理方式与 相同。 @@ -3727,7 +3591,7 @@ int PQsendPrepare(PGconn *conn, - 发送一个请求来执行一个准备好的语句,带有给定的参数,而不等待结果。 + 发送使用给定参数执行预备语句的请求,不等待结果。 int PQsendQueryPrepared(PGconn *conn, const char *stmtName, @@ -3737,9 +3601,7 @@ int PQsendQueryPrepared(PGconn *conn, const int *paramFormats, int resultFormat); - - 这类似于,但要执行的命令是通过指定一个之前准备好的语句的名称来指定,而不是提供一个查询字符串。 - 函数的参数处理方式与完全相同。 +该函数类似于 ,但通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。函数参数的处理方式与 相同。 @@ -3771,7 +3633,7 @@ int PQsendDescribePrepared(PGconn *conn, const char *stmtName); - 提交请求以获取有关指定门户的信息,而无需等待完成。 + 提交请求以获取有关指定 portal 的信息,而无需等待完成。 int PQsendDescribePortal(PGconn *conn, const char *portalName); @@ -3810,13 +3672,7 @@ PGresult *PQgetResult(PGconn *conn); - 必须重复调用直到返回空指针,表示命令已完成。 - (如果在没有活动命令时调用, - 将立即返回空指针。)每个非空结果从 - 应该使用先前描述的相同PGresult访问器函数进行处理。 - 完成后不要忘记使用释放每个结果对象。请注意, - 仅在有命令处于活动状态且必要的响应数据尚未被 - 读取时才会阻塞。 + 必须反复调用 ,直到它返回空指针,表明命令已经完成。(如果当前没有正在执行的命令,调用 会立即返回空指针。)对于 返回的非空指针,应使用前文介绍的 PGresult 访问函数处理相应结果。使用完毕后,不要忘记调用 释放每个结果对象。注意,只有存在正在执行的命令,且所需响应数据尚未被 读取时, 才会阻塞。 @@ -3839,41 +3695,37 @@ PGresult *PQgetResult(PGconn *conn); - + - 使用解决了的一个问题:如果一个命令字符串包含多个SQL命令,这些命令的结果可以被个别地获得(顺便说一句:这样就允许一种简单的重叠处理形式, 客户端可以处理一个命令的结果,而同时服务器可以继续处理同一命令字符串中后面的查询)。 - + 使用 可以解决 的一个问题:如果命令字符串包含多个 SQL 命令,就能分别获取这些命令的结果。(这也支持一种简单的重叠处理方式:客户端可以处理某条命令的结果,同时服务器继续处理同一命令字符串中后面的查询。) + - 可以被获得的另一种常常想要的特性是一次从大型结果中检索一行。这会在中讨论。 - + 使用 还可以实现另一项常见需求:从大型查询结果中一次读取一行。详见 。 + - 就其本身而言,调用将仍会导致客户端阻塞,直到服务器完成下一个SQL命令。可以通过正确使用两个函数来避免这种情况: - - + 仅仅调用 仍会使客户端阻塞,直到服务器完成下一条 SQL 命令。可以通过正确使用另外两个函数来避免这种情况: + PQconsumeInputPQconsumeInput - 如果有来自服务器的输入可用,则使用之。 + 如果服务器有可读取的输入,则读取这些输入。 int PQconsumeInput(PGconn *conn); - 通常返回 1 表明没有错误,而返回 0 表明有某种麻烦发生(此时可以用)。 - 注意该结果并不表明是否真正收集了任何输入数据。在调用之后,应用可以检查和/或PQnotifies来看看它们的状态是否改变。 + 通常返回 1,表示没有错误;发生问题时则返回 0(此时可查看 )。注意,返回值并不说明是否实际读取了输入数据。调用 后,应用程序可以检查 和/或 PQnotifies,以确定其状态是否发生变化。 - 即使应用还不准备处理一个结果或通知,也可以被调用。 - 这个函数将读取可用的数 据并且把它保存在一个缓冲区中,从而导致一个select()的读准备好指示消失。 - 因此应用可以使用立即清除select()条件,并且在空闲时再检查结果。 + 即使应用程序尚未准备好处理结果或通知,也可以调用 。此函数会读取可用数据并将其保存在缓冲区中,从而清除 select() 的可读就绪指示。因此,应用程序可以用 立即清除 select() 的就绪条件,随后在合适的时候检查结果。 @@ -3895,15 +3747,11 @@ int PQisBusy(PGconn *conn); - + - 一个使用这些函数的典型应用将有一个主循环,在主循环中会使用select()poll()等待所有它必须响应的情况。 - 其中之一将是来自服务器的输入可用,对select()来说意味着标识的文件描述符上有可读的数据。 - 当主循环检测到输入准备好时,它将调用读取输入。 - 然后它可以调用,如果返回假(0)则接着调用。 - 它还可以调用PQnotifies检测NOTIFY消息(见)。 - + 使用这些函数的典型应用程序会在主循环中通过 select()poll() 等待需要响应的各种条件。其中一个条件是服务器有可读取的输入;对于 select(),这意味着 标识的文件描述符上有可读数据。主循环检测到输入就绪时,应调用 读取输入,然后调用 。如果 返回假(0),就可以接着调用 。还可以调用 PQnotifies 检测 NOTIFY 消息(见 )。 + 一个使用/的客户端也可以尝试取消一个正在被服务器处理的命令,见。 @@ -3911,13 +3759,8 @@ int PQisBusy(PGconn *conn); - 通过使用上面描述的函数,可以避免在等待来自数据库服务器的输入时阻塞。 - 然而,应用程序仍然可能会在等待向服务器发送输出时阻塞。 - 这在发送非常长的SQL命令或数据值时可能会发生,尽管这相对不常见。 - (如果应用程序通过COPY IN发送数据,则更有可能发生。) - 为了防止这种可能性并实现完全非阻塞的数据库操作,可以使用以下附加函数。 - - + 使用上述函数可以避免在等待数据库服务器输入时阻塞。不过,应用程序仍可能在等待向服务器发送输出时阻塞。这种情况较少见,但发送很长的 SQL 命令或数据值时可能发生。(如果应用程序通过 COPY IN 发送数据,发生的可能性则大得多。)为了防止这种情况,实现完全非阻塞的数据库操作,可以使用以下附加函数。 + PQsetnonblockingPQsetnonblocking @@ -3935,11 +3778,7 @@ int PQsetnonblocking(PGconn *conn, int arg); - 在非阻塞状态下,成功调用、 - 、 - 不会阻塞; - 它们的更改将存储在本地输出缓冲区中,直到刷新为止。 - 不成功的调用将返回错误,必须重试。 + 在非阻塞状态下,成功调用 不会阻塞;产生的数据保存在本地输出缓冲区中,等待发送。失败的调用会返回错误,必须重试。 @@ -3970,9 +3809,7 @@ int PQisnonblocking(const PGconn *conn); - 尝试将任何排队的输出数据刷新到服务器。如果成功(或发送队列为空),则返回0; - 如果由于某种原因失败,则返回-1;如果尚未能够发送发送队列中的所有数据(只有在连接为非阻塞时才会发生此情况), - 则返回1。 + 尝试将发送队列中的输出数据发送到服务器。成功(或发送队列为空)时返回 0;因某种原因失败时返回 -1;如果尚未能发送队列中的全部数据,则返回 1(这种情况只可能发生在非阻塞连接上)。 int PQflush(PGconn *conn); @@ -3980,15 +3817,11 @@ int PQflush(PGconn *conn); - + - 在一个非阻塞连接上发送任何命令或者数据之后,要调用。 - 如果它返回 1,就要等待套接字变成读准备好或写准备好。如果它变为写准备好,应再次调用。 - 如果它变为读准备好,则应先调用,然后再调用。 - 一直重复直到返回 0(有必要检查读准备好并且用耗尽输入,因为服务器可能阻塞给我们发送数据的尝试,例如 NOTICE 消息,并且在我们读它的数据之前它都不会读我们的数据)。 - 一旦返回 0,应等待套接字变成读准备好并且接着按照上文所述读取响应。 - + 在非阻塞连接上发送命令或数据后,应调用 。如果返回 1,就等待套接字变为可读或可写。套接字可写时,再次调用 ;可读时,先调用 ,再调用 。重复上述步骤,直到 返回 0。(必须检查套接字是否可读,并用 读完输入,因为服务器可能在尝试向客户端发送数据时阻塞,例如发送 NOTICE 消息;在客户端读取这些数据之前,服务器不会读取客户端发送的数据。)当 返回 0 后,等待套接字变为可读,再按前述方法读取响应。 + @@ -4002,29 +3835,26 @@ int PQflush(PGconn *conn); - pipelining - in libpq + 管道化 + 在 libpq 中 - batch mode - in libpq + 批处理模式 + 在 libpq 中 - libpq 管道模式允许应用发送查询而无需读取先前发送查询的结果。 - 利用管道模式的优点,客户端将对服务器等待的更少,因为可以在单个网络事务中发送/接收多个查询/结果。 - + libpq 的管道模式允许应用程序在尚未读取先前查询结果时继续发送查询。多个查询及其结果可以在一次网络交互中发送和接收,从而减少客户端等待服务器的时间。 + - 虽然管道模式提供了显著的性能提升, - 使用管道模式写客户端会更加复杂,因为它涉及到管理一个挂起查询的队列,并查找队列中的哪个结果对应于哪个查询。 - + 管道模式可以显著提升性能,但使用它编写客户端也更复杂,因为需要管理待处理查询队列,并确定每个结果对应队列中的哪个查询。 + - 管道模式通常也会在客户端和服务器上面消耗更多的内存,尽管仔细和积极地管理发送/接收队列可以减轻这种消耗。 - 这适用于连接是否处于阻塞或非阻塞模式。 - + 管道模式通常也会增加客户端和服务器的内存消耗,不过仔细、主动地管理发送和接收队列可以缓解这一问题。无论连接处于阻塞还是非阻塞模式,都是如此。 + 虽然libpq的管道API是在PostgreSQL 14中引入的, @@ -4037,24 +3867,8 @@ int PQflush(PGconn *conn); 使用管道模式 - 要发出管道命令,应用程序必须将连接切换到管道模式, - 可以通过来完成。 - 可以使用来测试管道模式是否激活。 - 在管道模式下,只允许使用扩展查询协议的异步操作, - 不允许包含多个SQL命令的命令字符串,也不允许使用COPY命令。 - 使用同步命令执行函数,如PQfn、 - PQexec、 - PQexecParams、 - PQprepare、 - PQexecPrepared、 - PQdescribePrepared、 - PQdescribePortal, - 都会导致错误。 - 也不允许使用PQsendQuery,因为它使用简单查询协议。 - 一旦所有已分派的命令的结果已被处理,并且 - 结束管道结果已被消耗,应用程序可以通过返回 - 到非管道模式。 - + 要使用管道,应用程序必须通过 将连接切换到管道模式。可用 检查管道模式是否已启用。在管道模式下,只允许异步操作,不允许命令字符串包含多个 SQL 命令,也不允许 COPY。调用同步命令执行函数,例如 PQfnPQexecPQexecParamsPQpreparePQexecPreparedPQdescribePreparedPQdescribePortal,会导致错误。所有已发送命令的结果及管道结束结果都读取处理完毕后,应用程序便可通过 返回非管道模式。 + @@ -4063,9 +3877,8 @@ int PQflush(PGconn *conn); 如果在阻塞模式下使用,它可能发生客户端/服务器死锁。 - 客户端将阻止尝试发送查询到服务器,但服务器将阻止从它已经处理的查询向客户端发送结果。 - 这只有当客户端在它切换到处理从服务器的输入之前发送足够的查询来填充其输出缓冲区和服务器的接收缓冲区,才会发生这种情况,但很难准确预测何时将发生。 - + 客户端在尝试向服务器发送查询时阻塞,而服务器在尝试将已处理查询的结果发送给客户端时阻塞。只有当客户端在转而处理服务器输入之前,发送了足够多的查询,填满自身的输出缓冲区和服务器的接收缓冲区,才会发生这种情况;但很难准确预测何时会发生。 + @@ -4106,8 +3919,8 @@ int PQflush(PGconn *conn); - PQisBusyPQconsumeInput 等函数在处理管道结果时照常工作。特别地,在管道处理过程中调用 PQisBusy 时,如果到目前为止已发出查询的所有结果均已被消费,则返回 0。 - + PQisBusyPQconsumeInput 等函数在处理管道结果时照常工作。特别地,在管道处理过程中调用 PQisBusy 时,如果到目前为止已发出查询的所有结果均已被读取,则返回 0。 + libpq 不向应用程序提供当前正在处理哪个查询的信息(除了 PQgetResult 返回空指针,表示开始返回下一个查询的结果)。应用程序必须跟踪查询的发送顺序,以便将查询与对应结果关联起来。应用程序通常会使用状态机或 FIFO 队列实现这一点。 @@ -4120,21 +3933,16 @@ int PQflush(PGconn *conn); 错误处理 - 从客户端的视角,在PQresultStatus返回PGRES_FATAL_ERROR之后,管道被标记为中止。 - PQresultStatus将报告一个PGRES_PIPELINE_ABORTED结果,对中止的管道中的每一个剩余的排队操作。 - PQpipelineSync的结果报告为PGRES_PIPELINE_SYNC,以表示中止管道的结束并恢复正常的结果处理。 - + 从客户端的角度看,PQresultStatus 返回 PGRES_FATAL_ERROR 后,管道就会被标记为中止。对于已中止管道中剩余的每个排队操作,PQresultStatus 都会报告一个 PGRES_PIPELINE_ABORTED 结果。PQpipelineSync 的结果报告为 PGRES_PIPELINE_SYNC,表示已中止的管道结束,并恢复正常的结果处理。 + 在错误恢复时,客户端必须 使用 PQgetResult处理结果。 - 如果管道使用隐式事务,那么已经执行的操作将被回滚,而排队跟在失败操作的操作将被完全跳过。 - 同样的行为也会发生,如果管道开始并提交单个显式事务(也就是,第一个语句是BEGIN ,最后一个是COMMIT),除非会话在管道结束时保持在中止事务状态。 - 如果管道包含多个显式事务,所有在错误发生前已提交的事务都会继续保留,当前正在进行的事务会被中止,所有后续操作都会被完全跳过,包括后续事务在内。 - 如果管道同步点发生时显式事务块为中止状态,则下一个管道将立即中止,除非下一个命令使用ROLLBACK将事务置于正常模式。 - + 如果管道使用隐式事务,已经执行的操作会被回滚,而失败操作之后排队的操作会全部跳过。如果管道开始并提交单个显式事务(即第一条语句为 BEGIN,最后一条为 COMMIT),行为也相同,不过在管道结束时,会话仍处于事务中止状态。如果管道包含多个显式事务,错误发生前已经提交的事务仍保持已提交状态,当前正在进行的事务会中止,所有后续操作都会被跳过,包括后续事务。如果到达管道同步点时,显式事务块仍处于中止状态,下一个管道会立即中止,除非下一条命令使用 ROLLBACK 将事务恢复为正常状态。 + @@ -4147,24 +3955,19 @@ int PQflush(PGconn *conn); - 交叉结果处理和查询分派 + 交错处理结果与发送查询 - 为避免大型管道上的死锁,客户端将被围绕非阻塞事件循环构建,通过使用操作系统工具,如select, poll, WaitForMultipleObjectEx等等, - + 为避免大型管道发生死锁,客户端应围绕非阻塞事件循环组织,使用 selectpollWaitForMultipleObjectEx 等操作系统机制。 + - 客户端应用通常应该维护一个尚未分派的工作队列和一个已分派但尚未处理结果的工作队列。 - 当套接字是可写时,它将可以分派更多的工作。 - 当套接字是可读时,它将读取结果并处理它们,将它们匹配到相应结果队列中的下一个条目。 - 基于可用内存,来自套接字的结果将被经常读取:这里不需要等到管道结束才读取结果。 - 管道将范围涵盖到工作的逻辑单元,通常(但不是必然)每个管道一个事务。 - 在管道之间,不需要退出管道模式再重新进入管道模式,也不需要等待一个管道结束后再发送下一个。 - + 客户端应用程序通常应维护两个队列:一个存放尚未发送的工作,另一个存放已经发送但尚未处理结果的工作。套接字可写时,应继续发送工作;套接字可读时,应读取并处理结果,将其与相应结果队列中的下一个条目匹配。应根据可用内存情况,频繁地从套接字读取结果,无需等到管道结束。每个管道应对应一个逻辑工作单元,通常是一个事务,但并非必须如此。管道之间无需退出再重新进入管道模式,也无需等待一个管道完成后才发送下一个。 + - 一个使用select()和一个简单状态机来跟踪发送和接收工作的示例,在PostgreSQL源代码发行版的src/test/modules/libpq_pipeline/libpq_pipeline.c文件中。 - + PostgreSQL 源代码发行版的 src/test/modules/libpq_pipeline/libpq_pipeline.c 中提供了一个示例,使用 select() 和简单状态机跟踪已发送和已接收的工作。 + @@ -4208,7 +4011,7 @@ PGpipelineStatus PQpipelineStatus(const PGconn *conn); - libpq 连接 是管道模式。 + libpq 连接处于管道模式。 @@ -4237,18 +4040,14 @@ PGpipelineStatus PQpipelineStatus(const PGconn *conn); - 造成连接进入管道模式,如果它当前空闲或已经是管道模式。 - + 如果连接当前空闲或已处于管道模式,则使该连接进入管道模式。 int PQenterPipelineMode(PGconn *conn); - - 成功返回1. - 如果连接当前不是空闲的,返回0并且无影响,也就是说,它已经有了一个结果,或者它正在等待服务器的更多输入,等等。 - 这个函数实际上不向服务器发送任何东西,它只是更改libpq连接状态。 + 成功时返回 1。如果连接当前不空闲,例如已有结果可供读取,或正在等待服务器的更多输入,则返回 0,且不产生任何影响。此函数实际上不向服务器发送任何内容,只改变 libpq 的连接状态。 @@ -4260,16 +4059,14 @@ int PQenterPipelineMode(PGconn *conn); - 造成连接退出管道模式,如果连接当前以空队列处于管道模式,并且没有待处理的结果。 + 如果连接当前处于管道模式、队列为空且没有待读取的结果,则使该连接退出管道模式。 int PQexitPipelineMode(PGconn *conn); - 成功则返回1。 - 如果不是管道模式,则返回1并且不采取操作。 - 如果当前语句没有完成处理,或者PQgetResult尚未被调用以收集所有先前发送查询的结果,则返回0(在这种情况下,使用以获取关于故障的更多信息)。 + 成功时返回 1。如果连接不处于管道模式,也返回 1,且不执行任何操作。如果当前语句尚未处理完毕,或尚未调用 PQgetResult 读取先前发送的所有查询的结果,则返回 0(此时可使用 获取更多失败信息)。 @@ -4281,17 +4078,14 @@ int PQexitPipelineMode(PGconn *conn); - 通过发送sync message并刷新发送缓冲区的方式来标记管道中的同步点。 - 它用作隐式事务的定界符和错误恢复点;参见。 - + 通过发送同步消息并将发送缓冲区中的数据发往服务器,在管道中标记同步点。同步点作为隐式事务的分界符和错误恢复点;见 int PQpipelineSync(PGconn *conn); - 成功就返回1。 - 如果连接不是管道模式或者发送sync message失败,则返回0。 + 成功时返回 1。如果连接不处于管道模式,或发送同步消息失败,则返回 0。 @@ -4305,21 +4099,19 @@ int PQpipelineSync(PGconn *conn); - 发送一个请求到服务器以刷新它的输出缓冲区。 + 请求服务器发送其输出缓冲区中的数据。 int PQsendFlushRequest(PGconn *conn); - + - 成功就返回1。 - 任何失败则返回0。 - + 成功时返回 1;发生任何失败时返回 0。 + - 当调用PQpipelineSync,或者在非管道模式下发出任何请求时,服务器都会自动刷新其输出缓冲区;这个函数用于使服务器在不建立同步点的情况下,也能在管道模式下刷新其输出缓冲区。 - 请注意,请求本身不会自动刷新到服务器;如果需要,请使用PQflush。 - + 调用 PQpipelineSync 后,或者在非管道模式下收到任何请求时,服务器都会自动发送其输出缓冲区中的数据。此函数可让服务器在管道模式下发送输出缓冲区中的数据,而不建立同步点。注意,该请求本身不会自动发送到服务器;必要时可使用 PQflush。 + @@ -4330,43 +4122,36 @@ int PQsendFlushRequest(PGconn *conn); 何时使用管道模式 - 非常像异步查询模式,在使用管道模式时没有明显的性能开销。 - 它增加了客户端应用的复杂性,并且需要特别注意以防止客户端/服务器死锁。 - 但是管道模式可以提供相当大的性能改进,代价是因为状态保留更久而增加内存使用。 - + 与异步查询模式类似,使用管道模式不会带来明显的性能开销。它增加了客户端应用程序的复杂性,需要格外注意防止客户端与服务器之间的死锁,但也能显著提升性能,代价是状态保留更久,因而占用更多内存。 + - 当服务器比较远,即网络延迟(ping time)高的时候,管道模式最有用,以及在许多小操作正在快速连续执行的时候。 - 当每个查询的执行时间是客户端/服务器往返时间的许多倍时,使用管道命令的优势通常会更少。 - 不使用管道模式时,在往返时间为 300 毫秒的服务器上运行一个包含 100 条语句的操作,仅网络延迟就需要 30 秒;使用管道时,等待来自服务器的结果可能只消耗 0.3 秒。 - + 当服务器距离较远,即网络延迟(ping 时间)较高,或者需要快速连续执行许多小操作时,管道模式最有用。如果每个查询的执行时间是客户端与服务器往返时间的许多倍,使用管道命令的收益通常较小。在往返时间为 300 毫秒的服务器上执行一个包含 100 条语句的操作,不使用管道时,仅网络延迟就需要 30 秒;使用管道时,等待服务器结果的时间可能低至 0.3 秒。 + - 当你的应用需要完成很多小的INSERT, UPDATEDELETE 操作,并且不能方便的转换到集合操作或者 COPY操作时,用管道命令。 - + 如果应用程序需要执行大量小型 INSERTUPDATEDELETE 操作,而这些操作又难以转换为集合操作或 COPY 操作,就可以使用管道命令。 + - 当来自一个操作的信息需要客户端产生下一个操作时,管道模式是没有用的。 - 在这种情况下,客户机将不得不引入一个同步点,并等待完整的客户端/服务器往返以获取它需要的结果。 - 但是,通常可以调整客户端设计以交换服务器端所需的信息。 - 读-修改-写循环是非常好的选择;例如: + 如果客户端必须获得前一个操作的信息,才能生成下一个操作,管道模式就没有帮助。在这种情况下,客户端必须引入同步点,并等待一次完整的客户端与服务器往返,才能获得所需结果。不过,通常可以调整客户端设计,让所需信息在服务器端交换。读取、修改、写入的循环尤其适合这样改进。例如: BEGIN; SELECT x FROM mytable WHERE id = 42 FOR UPDATE; --- result: x=2 --- client adds 1 to x: +-- 结果:x=2 +-- 客户端将 x 加 1: UPDATE mytable SET x = 3 WHERE id = 42; COMMIT; - 可以更有效地开展以下工作: +可以改写为以下效率更高的操作: UPDATE mytable SET x = x + 1 WHERE id = 42; - + - 当单个管道包含多个事务时,管道的作用更小,而且更复杂(参见)。 - + 当单个管道包含多个事务时,使用管道的收益较小,复杂度也更高(见 )。 + @@ -4399,7 +4184,7 @@ int PQsetSingleRowMode(PGconn *conn); - 此函数只能在调用或其某个兄弟函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活单行模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 + 此函数只能在调用或其某个同类函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活单行模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 @@ -4485,7 +4270,7 @@ int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize); - 的一个已废弃变体。 + 的一个已弃用变体。 int PQrequestCancel(PGconn *conn); @@ -4506,7 +4291,7 @@ int PQrequestCancel(PGconn *conn); 快速路径接口 - fast path + 快速路径 @@ -4516,8 +4301,8 @@ int PQrequestCancel(PGconn *conn); - 这个接口不安全,不应使用。当result_is_int被设置为0时,PQfn可能会在result_buf末尾之外写入数据,而不管缓冲区是否有足够空间容纳所请求的字节数。此外,它已经废弃,因为可以通过创建一个定义该函数调用的预备语句来达到类似的性能并获得更强大的功能。然后,用参数和结果的二进制传输执行该语句,从而取代快速路径函数调用。 - + 此接口不安全,不应使用。当 result_is_int 设为 0 时,PQfn 可能越过 result_buf 的末尾写入数据,无论缓冲区是否有足够空间容纳请求的字节数。此外,此接口已经过时:可以通过创建预备语句来定义函数调用,获得相近的性能和更强的功能;再以二进制形式传输参数和结果来执行该语句,即可替代快速路径函数调用。 + @@ -4545,27 +4330,24 @@ typedef struct - fnid参数是要被执行的函数的 OID。argsnargs定义了要传递给函数的参数;它们必须匹配已声明的函数参数列表。当一个参数结构体的isint域为真时,u.integer值被以指定长度(必须是 1、2 或者 4 字节)整数的形式发送给服务器;这时候会发生恰当的字节交换。当isint为假时,*u.ptr中指定数量的字节将不做任何处理被发送出去;这些数据必须是服务器 预期的用于该函数参数数据类型的二进制传输的格式(由于历史原因u.ptr被声明为类型int *,其实把它考虑成void *会更好)。result_buf是放置该函数返回值的缓冲区。调用者必须已经分配了足够的空间来存储返回值(这里没有检查!)。实际的结果长度将被放在result_len指向的整数中返回。如果预期结果是 2 或 4 字节整数,把result_is_int设为 1;否则设为 0。把result_is_int设为 1 导致libpq在必要时对值进行交换字节,这样它就作为对客户端机器正确的int值被传输,注意对任一种允许的结果大小都会传递一个 4 字节到*result_buf。当result_is_int是 0 时,服务器发送的二进制格式字节将不做修改直接返回(在这种情况下,把result_buf考虑为类型void *更好)。 - + fnid 参数是要执行函数的 OID。argsnargs 指定传给函数的参数,必须与函数声明中的参数列表匹配。参数结构体的 isint 字段为真时,u.integer 值会以指定长度的整数发送到服务器,该长度必须是 2 或 4 字节,并会进行适当的字节序转换。isint 为假时,位于 *u.ptr 的指定数量字节会原样发送;数据必须符合服务器对该函数参数数据类型的二进制传输格式要求。(将 u.ptr 声明为 int * 是历史原因;将其视为 void * 更合适。)result_buf 指向用于存放函数返回值的缓冲区。调用者必须事先分配足够空间来保存返回值,这里不会检查!实际结果长度以字节为单位,返回到 result_len 指向的整数中。如果预期结果是 2 或 4 字节整数,将 result_is_int 设为 1,否则设为 0。将 result_is_int 设为 1 后,libpq 会按需转换字节序,使结果成为适合客户端机器的 int 值;注意,无论是哪种允许的结果大小,传入 *result_buf 的都是 4 字节整数。result_is_int 为 0 时,服务器发送的二进制格式字节串会原样返回。(此时,将 result_buf 视为 void * 更合适。) + - PQfn总是返回一个有效的PGresult指针,包括状态PGRES_COMMAND_OK 表示成功或者PGRES_FATAL_ERROR在出现什么问题时。 - 在使用结果之前应该检查结果状态。 - 当结果不再使用后,调用者有义务使用释放PGresult。 - + PQfn 总是返回有效的 PGresult 指针:成功时状态为 PGRES_COMMAND_OK,遇到问题时为 PGRES_FATAL_ERROR。使用结果前应检查其状态。不再需要结果时,调用者负责使用 释放 PGresult。 + - 要传递NULL参数到函数,将参数结构体的len字段设置为-1isintu 字段就不相关了。 - + 要向函数传入 NULL 参数,将该参数结构体的 len 字段设为 -1;此时,isintu 字段便不再相关。 + - 如果函数返回 NULL, *result_len 被设置为 -1, 并且 *result_buf 不调整。 - + 如果函数返回 NULL,则将 *result_len 设为 -1,而不修改 *result_buf。 + - 注意在使用此接口时,不能够处理集-值结果。 - 此外,函数必须是一个普通函数,而不是聚合、窗口函数或过程。 - + 注意,使用此接口时无法处理集合值结果。此外,函数必须是普通函数,不能是聚合函数、窗口函数或过程。 + @@ -4575,7 +4357,7 @@ typedef struct NOTIFY - in libpq + 在 libpq 中 @@ -4584,39 +4366,36 @@ typedef struct libpq应用把LISTENUNLISTENNOTIFY命令作为普通 SQL 命令提交。 - 随后通过调用PQnotifies.PQnotifies来检测NOTIFY消息的到达。 + 随后通过调用PQnotifiesPQnotifies来检测NOTIFY消息的到达。 - 函数PQnotifies从服务器发来的未处理通知消息列表中返回下一条通知。如果没有待处理通知,则返回空指针。一旦PQnotifies返回一条通知,该通知就被视为已处理,并会从通知列表中删除。 - + 函数 PQnotifies 从已收到但尚未处理的服务器通知消息列表中返回下一条通知。没有待处理通知时返回空指针。一旦 PQnotifies 返回一条通知,该通知就被视为已处理,并从通知列表中移除。 PGnotify *PQnotifies(PGconn *conn); typedef struct pgNotify { - char *relname; /* notification channel name */ - int be_pid; /* process ID of notifying server process */ - char *extra; /* notification payload string */ + char *relname; /* 通知通道名称 */ + int be_pid; /* 发送通知的服务器进程 ID */ + char *extra; /* 通知载荷字符串 */ } PGnotify; - - 在处理完PQnotifies返回的PGnotify对象后,别忘了用把它释放。 - 释放PGnotify指针本身就足够了;relnameextra域并不表示独立分配的内存(这些域名是历史遗留的,尤其是通道名称与关系名称并无关联)。 - +处理完 PQnotifies 返回的 PGnotify 对象后,务必使用 释放它。只需释放 PGnotify 指针;relnameextra 字段并非独立分配。(这些字段名称是历史遗留的;尤其是,通道名称与关系名称不必有任何关联。) + 给出了一个示例程序展示异步通知的使用。 - PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数吸收的消息。 + PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数读取的消息。 在较早版本的libpq中,及时收到NOTIFY消息的唯一方法是不断提交命令,哪怕是空命令,然后在每次后检查PQnotifies。 - 虽然这种方法仍然有效,但由于效率过低,现已废弃。 + 虽然这种方法仍然有效,但由于浪费处理能力,现已弃用。 - 当你没有可用的命令提交时,一种更好的检查NOTIFY消息的方法是调用,然后检查PQnotifies。 + 当没有需要执行的实际命令时,一种更好的检查NOTIFY消息的方法是调用,然后检查PQnotifies。 你可以使用select()等待服务器数据到达,这样在无事可做时就不会浪费CPU资源(参见以获得可传给select()的文件描述符)。 注意不管是用/提交命令还是简单地使用,这种方法都能正常工作。 不过,你应该记住在每次之后检查PQnotifies,看看在命令的处理过程中是否有通知到达。 @@ -4630,20 +4409,16 @@ typedef struct pgNotify COPY - with libpq + 使用 libpq - PostgreSQL中的COPY命令有用于libpq的对网络连接读出或者写入的选项。这一节描述的函数允许应用通过提供或者消耗已拷贝的数据来充分利用这个功能。 - + PostgreSQLCOPY 命令提供了选项,可以通过 libpq 使用的网络连接读取或写入数据。本节介绍的函数允许应用程序通过提供或接收复制数据来使用这一能力。 + - 整个处理是应用首先通过或者一个等效的函数发出 SQL COPY命令。 - 对这个命令的响应(如果命令无误)将是一个状态代码是PGRES_COPY_OUT或 者PGRES_COPY_IN(取决于指定的拷贝方向)的PGresult对象。 - 应用然后就应该使用这一节的函数接收或者传送数据行。在数据传输结束之后,另外一个PGresult对象会被返回以表明传输的成功或者失败。 - 它的状态将是:PGRES_COMMAND_OK表示成功,PGRES_FATAL_ERROR表示发生了一些问题。 - 此时我们可以通过发出进一步的 SQL 命令(在COPY操作的处理过程中,不能用同一个连接执行其它 SQL 命令)。 - + 整体流程如下:应用程序先通过 或等效函数发出 SQL COPY 命令。如果命令没有错误,响应就是一个 PGresult 对象,其状态码为 PGRES_COPY_OUTPGRES_COPY_IN,取决于指定的复制方向。应用程序随后应使用本节函数接收或发送数据行。数据传输完成后,会返回另一个 PGresult 对象,表示传输成功或失败:成功时状态为 PGRES_COMMAND_OK,出现问题时为 PGRES_FATAL_ERROR。此时可以通过 继续发出 SQL 命令。(COPY 操作进行期间,不能在同一连接上执行其他 SQL 命令。) + 如果一个COPY命令是通过在一个可能包含额外命令的字符串中发出的,那么应用在完成COPY序列之后必须继续用取得结果。 @@ -4651,17 +4426,15 @@ typedef struct pgNotify - 这一节的函数应该只在从获得了PGRES_COPY_OUTPGRES_COPY_IN结果状态的后执行。 - + 只有从 获得 PGRES_COPY_OUTPGRES_COPY_IN 结果状态后,才应调用本节函数。 + - 一个PGresult对象具有这些状态值之一,携带有关COPY操作开始的一些附加数据。 - 可以使用与查询结果相关的函数来获取这些附加数据: - - + 带有上述某个状态值的 PGresult 对象,还会携带关于即将开始的 COPY 操作的附加数据。这些数据可以通过下列函数获取,这些函数也用于查询结果: + PQnfieldsPQnfieldswith COPY + >PQnfields用于 COPY @@ -4672,7 +4445,7 @@ typedef struct pgNotify PQbinaryTuplesPQbinaryTupleswith COPY + >PQbinaryTuples用于 COPY @@ -4684,7 +4457,7 @@ typedef struct pgNotify PQfformatPQfformatwith COPY + >PQfformat用于 COPY @@ -4696,15 +4469,15 @@ typedef struct pgNotify - + 用于发送<command>COPY</command>数据的函数 - 这些函数用于在COPY FROM STDIN期间发送数据。如果在连接不是COPY_IN状态,调用它们会失败。 - + 这些函数用于在 COPY FROM STDIN 期间发送数据。如果连接不处于 COPY_IN 状态,调用它们会失败。 + @@ -4723,12 +4496,11 @@ int PQputCopyData(PGconn *conn, - 传输指定buffer中长度为nbytesCOPY数据到服务器。 - 如果数据被放在队列中,结果是 1;如果因为缓冲区满而无法被放在队列中(只可能发生在连接是非阻塞模式时),那么结果是零;如果发生错误,结果为 -1(如果返回值为 -1,那么使用检索细节。如果值是零,那么等待写准备好然后重试)。 + 将指定 buffer 中长度为 nbytesCOPY 数据传输到服务器。数据成功加入队列时返回 1;因缓冲区已满而无法加入队列时返回零(仅可能发生在非阻塞模式下);发生错误时返回 -1。(返回 -1 时,可用 获取详细信息。返回零时,应等待可写就绪后重试。) - 应用可以把COPY数据流划分成任意方便的大小放到缓冲区中。在发送时,缓冲区载荷的边界没有什么语意。数据流的内容必须匹配COPY命令预期的数据格式;详见。 + 应用程序可以将 COPY 数据流分成任意方便大小的数据块,逐块装入缓冲区。发送时,这些数据块的边界没有语义含义。数据流内容必须符合 COPY 命令预期的数据格式;详见 @@ -4748,21 +4520,15 @@ int PQputCopyEnd(PGconn *conn, - 如果errormsgNULL,则成功结束COPY_IN操作。 - 如果errormsg不是NULLCOPY被强制失败,errormsg指向的字符串是错误消息。 - (不过,我们不应假定这个准确的错误信息将会从服务器传回,因为服务器可能已经因为其自身原因导致COPY失败。)。 + 如果 errormsgNULL,则成功结束 COPY_IN 操作。如果 errormsg 不为 NULL,则强制 COPY 失败,并将 errormsg 指向的字符串用作错误消息。(但不应假定服务器一定会返回这条完全相同的错误消息,因为服务器可能已经因自身原因使 COPY 失败。) - 如果终止消息被发送,则结果为 1;在非阻塞模式中,结果为 1 也可能只表示终止消息被成功地放在了发送队列中 - (在非阻塞模式中,要确认数据确实被发送出去,你应该接着等待写准备好并且调用,重复这些直到返回零)。 - 零表示该函数由于缓冲区满而无法将该终止消息放在队列中,这只会发生在非阻塞模式中(在这种情况下,等待写准备好并且再次尝试调用)。 - 如果发生系统错误,则返回 -1,可以使用检索详情。 + 终止消息已发送时返回 1;在非阻塞模式下,返回 1 也可能仅表示该消息已成功加入发送队列。(在非阻塞模式下,要确认数据已经发送,应接着等待可写就绪并调用 ,反复执行直到返回零。)返回零表示缓冲区已满,无法将终止消息加入队列;这种情况仅可能发生在非阻塞模式下。(此时,应等待可写就绪,再次调用 。)发生严重错误时返回 -1,可用 获取详细信息。 - 在成功调用之后,调用获取COPY命令的最终结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 成功调用 后,调用 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -4795,29 +4561,19 @@ int PQgetCopyData(PGconn *conn, - 在一个COPY期间尝试从服务器获取另外一行数据。数据总是以每次一个数据行的方式被返回;如果只有一个部分行可用,那么它不会被返回。 - 成功返回一个数据行涉及到分配一块内存来保存该数据。buffer参数必须为非NULL。 - *buffer被设置为指向分配到的内存的指针,或者是在没有返回缓冲区的情况下指向NULL。 - 一个非NULL的结果缓冲区在不需要时必须用释放。 + 在 COPY 期间尝试从服务器获取下一行数据。每次总是返回一个完整数据行;如果只有部分行可用,则不返回。成功返回数据行时,会分配一块内存保存数据。buffer 参数必须为非 NULL*buffer 会被设置为指向所分配的内存;如果没有返回缓冲区,则设为 NULL。非 NULL 的结果缓冲区在不再需要时应使用 释放。 - 在成功返回一行之后,返回的值就是该数据行里数据的字节数(将是大于零)。 - 被返回的字符串总是空终止的,虽然这可能只是对文本COPY有用。 - 一个零结果表示该COPY仍然在处理中,但是还没有可用的行(只在async为真时才可能)。 - 一个 -1 结果表示COPY已经完成。-2 结果表示发生了错误(参考获取原因)。 + 成功返回一行时,返回值是该行的数据字节数,始终大于零。返回的字符串总是以零字节结尾,不过这可能仅对文本 COPY 有用。返回零表示 COPY 仍在进行,但尚无可用行(仅在 async 为真时可能发生)。返回 -1 表示 COPY 已完成;返回 -2 表示发生了错误(可用 查看原因)。 - 当async为真时(非零),将不会阻塞等待输入; - 如果COPY仍在处理过程中并且没有可用的完整行,那么它将返回零 - (在这种情况下等待读准备好,然后在再次调用之前,调用)。 - 当async为假(零)时,将阻塞,直到数据可用或者操作完成。 + 当 async 为真(非零)时, 不会阻塞等待输入;如果 COPY 仍在进行,但没有完整行可用,则返回零。(此时,应等待读就绪,先调用 ,再调用 。)当 async 为假(零)时, 会阻塞,直到数据可用或操作完成。 - 在返回 -1 之后,调用获取COPY命令的最后结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 在 返回 -1 后,调用 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -4827,11 +4583,11 @@ int PQgetCopyData(PGconn *conn, - 用于<command>COPY</command>的废弃函数 + 用于<command>COPY</command>的过时函数 - 这些函数代表了以前的处理COPY的方法。尽管它们还能用,但是现在已经被废弃,因为它们的错误处理很糟糕、检测结束数据的方法也不方便,并且缺少对二进制或非阻塞传输的支持。 - + 这些函数使用较旧的方式处理 COPY。虽然仍然可用,但由于错误处理欠佳、检测数据结束的方式不便,而且缺少对二进制或非阻塞传输的支持,已被弃用。 + @@ -4841,7 +4597,7 @@ int PQgetCopyData(PGconn *conn, - 读取一个以新行终止的字符行到(由服务器传输) 到一个长度为length的字符串缓冲区。 + 将服务器传来的、以换行符结尾的一行字符读入大小为 length 的字符串缓冲区。 int PQgetline(PGconn *conn, char *buffer, @@ -4850,12 +4606,11 @@ int PQgetline(PGconn *conn, - 这个函数拷贝最多length-1 个字符到该缓冲区中,并且把终止的新行转换成一个零字节。 - 在输入结束时返回EOF,如果整行都被读取则返回 0,如果缓冲区填满了而还没有遇到结束的新行则返回 1。 - + 此函数最多将 length-1 个字符复制到缓冲区,并将末尾的换行符转换为零字节。 在输入结束时返回 EOF,读完一整行时返回 0,缓冲区已满但尚未读到末尾换行符时返回 1。 + - 注意,应用必须检查是否一个新行包含两个字符\.,这表明服务器 已经完成了COPY命令的结果发送。如果应用可能收到超过length-1 字符长的行, 我们就应该确保正确识别\.行(例如,不要把一个长数据行的结束当作一个终止行)。 + 注意,应用程序必须检查新读入的一行是否仅由 \. 两个字符组成,这表示服务器已发送完 COPY 命令的结果。如果可能收到长度超过 length-1 个字符的行,必须确保正确识别 \. 行,例如不能把长数据行的末尾误当作终止行。 @@ -4867,7 +4622,7 @@ int PQgetline(PGconn *conn, - 不阻塞地读取一行COPY数据(由服务器传输)到一个缓冲区中。 + 以非阻塞方式将服务器传来的一行 COPY 数据读入缓冲区。 int PQgetlineAsync(PGconn *conn, char *buffer, @@ -4876,23 +4631,19 @@ int PQgetlineAsync(PGconn *conn, - 这个函数类似于,但是可以被用于那些必须异步读取COPY数据的应用, 也就是不阻塞的应用。 - 在发出了COPY命令并得到了PGRES_COPY_OUT响应之后, - 应用应该调用直到检测到结束数据的信号。 - + 此函数类似于 ,但可用于必须异步读取 COPY 数据的应用程序,即读取时不阻塞。发出 COPY 命令并收到 PGRES_COPY_OUT 响应后,应用程序应调用 ,直到检测到数据结束信号。 + - 不像,这个函数负责检测结束数据。 + 与 不同,此函数会负责检测数据结束。 - 在每次调用时,如果libpq的输入缓冲区中有一个完整的数据行可用,都将返回数据。 - 否则,在剩余行到达之前不会返回数据。如果识别到拷贝数据结束的标志,此函数返回 -1;如果没有可用数据则返回 0; - 或者是给出一个正数给出被返回的字节数。如果返回 -1,调用者下一步必须调用,然后回到正常处理。 + 每次调用时,如果 libpq 的输入缓冲区中有完整数据行, 就会返回数据;否则,要等该行剩余部分到达后才返回数据。识别到复制数据结束标记时返回 -1,没有可用数据时返回 0,否则返回正数,表示返回的数据字节数。返回 -1 后,调用者必须接着调用 ,然后恢复正常处理。 - 返回的数据将不超过一个数据行的范围。如果可能,每次将返回一个完整行。但如果调用者提供的缓冲区太小不足以容下服务器发送的行,那么将返回部分行。对于文本数据,这可以通过测试返回的最后一个字节是否\n来检测(在二进制COPY中, 需要对COPY数据格式进行实际的分析,以便做相同的判断)。被返回的字符串不是空结尾的(如果你想增加一个终止空,确保传递一个比实际可用空间少一字节的bufsize)。 + 返回的数据不会跨越数据行边界。只要可能,每次就返回一整行;但如果调用者提供的缓冲区太小,容不下服务器发送的一行,则只返回部分行。对于文本数据,可检查最后返回的字节是否为 \n,以判断是否返回了完整行。(对于二进制 COPY,则必须实际解析 COPY 数据格式才能作出相同判断。)返回的字符串不以零字节结尾。(如果要自行添加末尾的零字节,务必将传入的 bufsize 设置为比实际可用空间少一字节。) @@ -4904,7 +4655,7 @@ int PQgetlineAsync(PGconn *conn, - 向服务器发送一个空终止的字符串。如果 OK 则返回 0;如果不能发送字符串则返回EOF。 + 向服务器发送以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputline(PGconn *conn, const char *string); @@ -4912,17 +4663,14 @@ int PQputline(PGconn *conn, - 一系列调用发送的COPY数据流和返回的数据具有相同的格式, - 只是应用不需要每次调用中发送刚好一个数据行;在每次调用中发送多行或者部分行都是可以的。 + 连续调用 发送的 COPY 数据流,与 返回的数据格式相同。不过,应用程序不必在每次 调用中恰好发送一个数据行;每次发送部分行或多行也可以。 - 在PostgreSQL协议 3.0 之前,应用必须显式地发送两个字符\.作为最后一行来指示服务器已经完成发送COPY数据。 - 虽然这么做仍然有效,但是它已经被废弃并且\.的特殊含义可能在将来的版本中删除。 - 在发送完实际数据之后, 调用就足够了。 - + 在 PostgreSQL 协议 3.0 之前,应用程序必须显式发送由 \. 两个字符组成的最后一行,告知服务器应用程序已发送完 COPY 数据。虽然这种方式仍然有效,但已被弃用,\. 的特殊含义预计会在未来版本中移除。发送完实际数据后,调用 即可。 + @@ -4934,7 +4682,7 @@ int PQputline(PGconn *conn, - 向服务器发送一个非空终止的字符串。如果 OK 则返回 0,如果不能发送字符串则返回EOF。 + 向服务器发送不以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputnbytes(PGconn *conn, const char *buffer, @@ -4943,7 +4691,7 @@ int PQputnbytes(PGconn *conn, - 这个函数类似,除了数据缓冲区不需要是空终止,因为要发送的字节数是直接指定的。在发送二进制数据时使用这个过程。 + 此函数与 完全相同,只是直接指定了要发送的字节数,因此数据缓冲区不必以零字节结尾。发送二进制数据时可使用此函数。 @@ -4959,15 +4707,11 @@ int PQputnbytes(PGconn *conn, int PQendcopy(PGconn *conn); - 这个函数等待服务器完成拷贝。当最后一个字符串已经用发送给服务器时或者当最后一个字符串已经用PQgetline从服务器接收到时,就会发出这个函数。 - 这个函数必须被发出,否则服务器将会和客户端不同步。从这个函数返回后,服务器就已经准备好接收下一个 SQL 命令了。函数成功完成时返回值为 0,否则返回非零值(如果返回值为非零值,用检索详情)。 +此函数会等待服务器完成复制。应在使用 向服务器发送最后一个字符串后,或使用 PQgetline 从服务器接收最后一个字符串后调用它。必须调用此函数,否则服务器与客户端会失去同步。函数返回后,服务器便准备好接收下一条 SQL 命令。成功完成时返回 0,否则返回非零值。(返回非零值时,可用 获取详细信息。) - 在使用时,应用应该通过反复调用并且在看到终止行后调用来响应PGRES_COPY_OUT结果。 - 然后它应该返回到循环直到返回一个空指针。 - 类似地,PGRES_COPY_IN结果会用一系列加上之后的来处理,然后返 回到循环。 - 这样的安排将保证嵌入到一系列SQL命令中的COPY命令将被正确执行。 + 使用 时,收到 PGRES_COPY_OUT 结果后,应用程序应反复调用 ,并在看到终止行后调用 。随后应回到 循环,直到 返回空指针。类似地,收到 PGRES_COPY_IN 结果后,应连续调用 ,再调用 ,然后回到 循环。这样可以保证嵌在一系列 SQL 命令中的 COPY 命令正确执行。 @@ -4987,8 +4731,8 @@ int PQendcopy(PGconn *conn); 控制函数 - 这些函数控制libpq行为各种各样的细节。 - + 这些函数控制 libpq 行为的各种细节。 + @@ -4998,17 +4742,15 @@ int PQendcopy(PGconn *conn); - 返回客户端编码。 + 返回客户端编码。 int PQclientEncoding(const PGconn *conn); - - 请注意,它返回的是编码 ID,而不是一个符号串字符串,如EUC_JP。如果不成功,它会返回 -1。要把一个编码 ID 转换为为一个编码名称,可以用: - +注意,返回的是编码 ID,而不是 EUC_JP 这样的符号字符串。失败时返回 -1。要将编码 ID 转换为编码名称,可以使用: char *pg_encoding_to_char(int encoding_id); - + @@ -5018,14 +4760,11 @@ char *pg_encoding_to_char(int encoding_id); - - 设置客户端编码。 - + 设置客户端编码。 int PQsetClientEncoding(PGconn *conn, const char *encoding); - conn是一个到服务器的连接,而encoding是你想使用的编码。 - 如果函数成功地设置编码,则返回 0,否则返回 -1。这个连接的当前编码可以使用确定。 + conn是到服务器的连接,而encoding是要使用的编码。如果成功设置编码,函数返回 0,否则返回 -1。此连接的当前编码可以通过以下函数确定: @@ -5037,7 +4776,7 @@ int PQsetClientEncoding(PGconn *conn, const char * - 决定返回的消息的细节程度。 + 设置 所返回消息的详细程度。 typedef enum { @@ -5049,19 +4788,12 @@ typedef enum PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); - - 设置细节模式,并返回该连接的前一个设置。 - 在TERSE模式下,返回的消息只包括严重性、主要文本以及位置;这些东西通常放在一个单一行中。 - DEFAULT模式生成的消息包括上面的信息加上任何细节、提示或者上下文域(这些可能跨越多行)。 - VERBOSE模式包括所有可以可用的域。修改细节模式不会影响来自已有PGresult对象中的可用消息。 - 只有随后创建的PGresult对象才受到影响。 - SQLSTATE模式仅包括错误严重性和SQLSTATE错误代码,如果其中之一是可用的(如果没有,输出类似于TERSE模式)。 - + 设置详细程度模式,并返回该连接先前的设置。在 TERSE 模式下,返回的消息只包含严重级别、主要文本和位置;通常一行就能容纳。DEFAULT 模式生成的消息除上述内容外,还包含所有详细信息、提示或上下文字段(这些内容可能跨越多行)。VERBOSE 模式包含所有可用字段。SQLSTATE 模式仅包含错误严重级别,以及可用时的 SQLSTATE 错误代码(如果没有错误代码,则输出与 TERSE 模式相同)。 + - 更改详细程度设置不会影响已存在的PGresult对象的可用的消息,只会影响随后创建的对象。 - (如果想要用不同的详细程度打印之前的错误,请见 ) - + 更改详细程度设置不会影响从既有 PGresult 对象中取得的消息,只影响随后创建的对象。(如果希望以不同的详细程度打印之前的错误,请参见 。) + @@ -5072,7 +4804,7 @@ PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); - 决定如何处理返回的消息中的CONTEXT域。 + 确定 所返回消息中 CONTEXT 字段的处理方式。 typedef enum { @@ -5083,18 +4815,12 @@ typedef enum PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibility show_context); - - 设置上下文显示模式,返回该连接上之前的设置。 - 这个模式控制消息中是否包括CONTEXT域。 - NEVER模式不会包括CONTEXT,而ALWAYS则尽可能地包括这个域。 - 在ERRORS模式(默认)中,只在错误消息中包括CONTEXT域,而在通知和警告消息中不会包括。 - (但是,如果详细程度设置为 TERSESQLSTATE,则无论上下文显示模式如何,都会省略CONTEXT字段。) - + 设置上下文显示模式,并返回连接先前的设置。此模式控制消息中是否包含 CONTEXT 字段。NEVER 模式从不包含 CONTEXT,而 ALWAYS 模式在该字段可用时总是包含它。在 ERRORS 模式(默认)下,CONTEXT 字段只包含在错误消息中,不包含在通知和警告中。(不过,如果详细程度设置为 TERSESQLSTATE,则无论上下文显示模式如何,都会省略 CONTEXT 字段。) + - 更改这个模式不会影响从已经存在的PGresult对象项中得到的消息,只会影响后续创建的PGresult对象 - (如果想要用不同的详细程度打印之前的错误,请见)。 - + 更改此模式不会影响从既有 PGresult 对象中取得的消息,只影响随后创建的对象。(如果希望使用不同的显示模式打印之前的错误,请参见 。) + @@ -5105,25 +4831,20 @@ PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibilit - 启用对客户端/服务器通讯的跟踪,把跟踪信息输出到一个调试文件流中。 + 启用客户端/服务器通信跟踪,将跟踪信息写入调试文件流。 void PQtrace(PGconn *conn, FILE *stream); - + - 每行包括:一个可选的时间戳,一个方向指示器(F 表示从客户端到服务器的消息,B 表示从服务器到客户端的消息),以及消息长度、消息类型和消息内容。 - 非消息内容字段(时间戳、方向、长度和消息类型)由一个制表符分隔。 - 消息内容用空格分隔。 - 协议字符串用双引号括起来,而用作数据值的字符串用单引号括起来。 - 不可打印的字符被打印为十六进制转义。 - 更多消息-类型-特定的详情可以在中发现。 - + 每行包含可选的时间戳、方向指示符(F 表示客户端发往服务器的消息,B 表示服务器发往客户端的消息)、消息长度、消息类型和消息内容。消息内容之外的字段(时间戳、方向、长度和消息类型)以制表符分隔。消息内容以空格分隔。协议字符串用双引号括起,用作数据值的字符串用单引号括起。不可打印字符以十六进制转义形式输出。各消息类型的进一步说明见 。 + - 在 Windows上,如果libpq库和应用使用了不同的标志编译,那么这个函数调用会导致应用崩溃,因为FILE指针的内部表达是不一样的。特别是多线程/单线程、发布/调试 以及静态/动态标志应该是库和所有使用库的应用都一致。 + 在 Windows 上,如果 libpq 库与应用程序使用不同的标志编译,调用此函数会导致应用程序崩溃,因为 FILE 指针的内部表示不同。具体而言,库与所有使用它的应用程序都应使用相同的多线程/单线程、发布/调试和静态/动态标志。 @@ -5144,11 +4865,8 @@ void PQsetTraceFlags(PGconn *conn, int flags); - flags包含描述跟踪的操作模式的标志位。 - 如果flags包含PQTRACE_SUPPRESS_TIMESTAMPS,则在打印每条消息时不包括时间戳。 - 如果flags包含PQTRACE_REGRESS_MODE,那么在打印每个消息时将修改一些字段,例如对象OIDs,以使输出在测试框架中更方便地使用。 - 这个函数必须在调用PQtrace之后调用。 - + flags 包含描述跟踪工作模式的标志位。如果 flags 包含 PQTRACE_SUPPRESS_TIMESTAMPS,则打印每条消息时不包含时间戳。如果 flags 包含 PQTRACE_REGRESS_MODE,则打印每条消息时会隐去某些字段,例如对象 OID,以便在测试框架中使用输出。必须在调用 PQtrace 之后调用此函数。 + @@ -5160,11 +4878,11 @@ void PQsetTraceFlags(PGconn *conn, int flags); - 禁用打开的跟踪。 + 禁用由 启动的跟踪。 void PQuntrace(PGconn *conn); - + @@ -5194,11 +4912,8 @@ void PQfreemem(void *ptr); - 释放libpq分配的内存,尤其是,,,和PQnotifies分配的内存。 - 特别重要的是,在微软 Windows 上使用这个函数,而不是free()。 - 这是因为只有 DLL 和应用的当多线程/单线程、发布/调试以及静态/动态标志相同时,才能在一个 DLL 中分配内存并且在应用中释放它。 - 在非微软 Windows 平台上,这个函数与标准库函数free()相同。 - + 释放 libpq 分配的内存,特别是 PQnotifies 分配的内存。在 Microsoft Windows 上,务必使用此函数,而不是 free()。这是因为只有 DLL 与应用程序使用相同的多线程/单线程、发布/调试和静态/动态标志,才能在 DLL 中分配内存并在应用程序中释放它。在 Microsoft Windows 以外的平台上,此函数与标准库函数 free() 相同。 + @@ -5216,8 +4931,8 @@ void PQconninfoFree(PQconninfoOption *connOptions); - 一个简单的不会做这些,因为数组包含对子字符串的引用。 - + 仅调用 不足以完成此项释放,因为数组还包含指向附属字符串的引用。 + @@ -5241,8 +4956,8 @@ char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, 当前支持的算法是md5scram-sha-256onoff也被接受作为md5的别名,用于与较老的服务器版本兼容)。 注意,对scram-sha-256支持是在PostgreSQL版本10中引入的,并且在老的服务器版本上无法工作。 如果algorithmNULL,这个函数将向服务器查询设置的当前值。 - 这种行为可能会阻塞当前事务,并且当前事务被中止或者连接正忙于执行另一个查询时会失败。 - 如果希望为服务器使用默认的算法但避免阻塞,应在调用之前查询你自己的password_encryption,并且将该值作为algorithm传入。 + 这一查询可能阻塞,并且当前事务被中止或者连接正忙于执行另一个查询时会失败。 + 如果希望为服务器使用默认的算法但避免阻塞,应在调用之前自行查询password_encryption,并且将该值作为algorithm传入。 @@ -5288,8 +5003,8 @@ PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); 这是libpq内部用于分配并初始化一个空PGresult对象的函数。 如果无法分配内存,此函数返回NULL。 将它导出供外部调用,是因为一些应用需要自行生成结果对象,特别是带有错误状态的对象。 - 如果conn非空,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 - 此外,如果conn非空,连接中注册的所有事件过程也会被复制到PGresult中。 + 如果conn 不为 null,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 + 此外,如果conn 不为 null,连接中注册的所有事件过程也会被复制到PGresult中。 (这些过程不会收到PGEVT_RESULTCREATE调用,但可参见。) 注意,最终应对该对象调用,就像处理libpq自身返回的PGresult一样。 @@ -5310,16 +5025,16 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); - conn参数被传送给事件过程,但不会被直接使用。如果事件过程不使用它,则会返回NULL。 - + conn 参数会传递给事件过程,但此函数不会直接使用它。如果事件过程不使用此参数,则可以传入 NULL。 + 已经接收到这个对象的PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件过程不会被再次触发。 - 这个函数与分开的主要原因是在调用事件过程之前创建一个PGresult并且填充它常常是合适的。 - + 此函数与 分开的主要原因是,通常适合先创建 PGresult 并填充数据,然后再调用事件过程。 + @@ -5330,13 +5045,11 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); - 为一个PGresult对象创建一个拷贝。 - 这个拷贝不会以任何方式链接到源结果,并且当该拷贝不再需要时,必须调用进行清理。如果函数失败,返回NULL。 - + 创建 PGresult 对象的副本。副本与源结果没有任何关联,不再需要副本时必须调用 。函数失败时返回 NULL PGresult *PQcopyResult(const PGresult *src, int flags); - + 这不是为了制作一个精确的副本。返回的结果总是放在PGRES_TUPLES_OK状态中,并且不复制源中的任何错误消息。 @@ -5345,7 +5058,7 @@ PGresult *PQcopyResult(const PGresult *src, int flags); PG_COPYRES_TUPLES指定复制源结果的元组。(这也意味着复制属性。) PG_COPYRES_NOTICEHOOKS指定复制源结果的通知钩子。 PG_COPYRES_EVENTS指定复制源结果的事件。(但不复制与源相关的任何实例数据。) - 事件程序接收PGEVT_RESULTCOPY事件。 + @@ -5376,18 +5089,15 @@ int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs); - 设置一个PGresult对象的一个元组域值。 + 设置 PGresult 对象中某个元组的字段值。 int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len); - + - 这个函数将自动按需增加结果的内部元组数组。但是,tup_num参数必须小于等于,意味着这个函数对元组数组一次只能增加一个元组。 - 但已存在的任意元组中的任意域可以以任意顺序进行调整。如果field_num的一个值已经存在,它会被覆盖。 - 如果len是 -1,或valueNULL, 该域值会被设置为一个 SQL 空值。 - value会被复制到结果的私有存储中,因此函数返回后就不再需要了。如果函数失败,返回值是 0。如果函数成功,返回值会是非 0。 - + 此函数会根据需要自动扩展结果内部的元组数组。不过,tup_num 参数必须小于或等于 ,也就是说,每次只能向元组数组增加一个元组。已有元组的任何字段都可以按任意顺序修改。如果 field_num 指定的位置已有值,该值会被覆盖。如果 len 为 -1 或 valueNULL,则将该字段设置为 SQL null 值。value 会被复制到结果的私有存储中,因此函数返回后就不再需要它。函数失败时返回零,成功时返回非零值。 + @@ -5405,8 +5115,8 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); - 当res被清除时,这个函数分配的内存也会被释放掉。如果函数失败,返回值是NULL。结果被保证为按照数据的任意类型充分地对齐,正如malloc所作的。 - + 使用此函数分配的所有内存都会在清除 res 时释放。函数失败时返回 NULL。与 malloc 一样,返回的内存保证满足任意数据类型的对齐要求。 + @@ -5417,15 +5127,15 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); - 检索为PGresult对象分配的字节数。 + 获取为 PGresult 对象分配的字节数。 size_t PQresultMemorySize(const PGresult *res); - + - 此值是与PGresult对象关联的所有malloc请求的总和,就是说,将释放的所有空间。此信息可用于管理内存消耗。 - + 此值是与 PGresult 对象相关的所有 malloc 请求所分配字节数的总和,即 将释放的全部内存。这一信息有助于管理内存消耗。 + @@ -5444,28 +5154,25 @@ int PQlibVersion(void); - 在运行时,这个函数的结果可以被用来决定在当前已载入的 libpq 版本中特定的功能是否可用。 - 例如,这个函数可以被用来决定哪些选项可以被用于。 - + 可在运行时根据此函数的结果,判断当前已加载的 libpq 版本是否具有特定功能。例如,可用它判断 支持哪些连接选项。 + - 结果通过将库的主版本号乘以10000再加上次版本号形成。例如,版本10.1将被返回为100001,而版本11.0将被返回为110000。 - + 返回值等于库的主版本号乘以 10000 再加上次版本号。例如,版本 10.1 返回 100001,版本 11.0 返回 110000。 + - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。 - 对于那些版本,为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - + 在主版本 10 之前,PostgreSQL 使用由三个部分组成的版本号,前两个部分共同表示主版本。对于这些版本, 用两位数字表示每个部分;例如,版本 9.1.5 返回 90105,版本 9.2.0 返回 90200。 + - 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。 - 在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 - + 因此,为了判断功能兼容性,应用程序应将 的结果除以 100 而非 10000,得到逻辑上的主版本号。在所有版本系列中,次版本(错误修复版本)之间只有最后两位数字不同。 + - 这个函数出现于PostgreSQL版本 9.1,因此它不能被用来在早期的版本中检测所需的功能,因为调用它将会创建一个对版本9.1及其后版本的链接依赖。 + 此函数从 PostgreSQL 9.1 起提供,因而不能用它检测更早版本是否具有所需功能:调用它会建立对 9.1 或更高版本的链接依赖。 @@ -5480,13 +5187,13 @@ int PQlibVersion(void); 通知处理 - notice processing - in libpq + 通知处理 + 在 libpq 中 - 服务器产生的通知和警告消息不会被查询执行函数返回,因为它们不代表查询失败。它们可以被传递给一个通知处理函数,并且在处理者返回后执行会继续正常进行。默认的处理函数会把消息打印在stderr上,但是应用可以通过提供它自己的处理函数来重载这种行为。 - + 服务器生成的通知和警告消息不由查询执行函数返回,因为它们并不表示查询失败。这些消息会传递给通知处理函数,处理函数返回后,执行正常继续。默认通知处理函数将消息打印到 stderr,应用程序也可以提供自己的处理函数来替换这一行为。 + 由于历史原因,通知处理有两个级别,称为通知接收器和通知处理器。通知接收器的默认行为是格式化通知并且将一个字符串传递给通知处理器来打印。不过,如果一个应用选择提供自己的通知接收器,它通常会忽略通知处理器层并且在通知接收器中完成所有工作。 @@ -5494,10 +5201,10 @@ int PQlibVersion(void); 函数PQsetNoticeReceiver - notice receiver + 通知接收器 PQsetNoticeReceiver为一个连接对象设置或者检查当前的通知接收器。 相似地,PQsetNoticeProcessor - notice processor + 通知处理器 PQsetNoticeProcessor设置或检查当前的通知处理器。 @@ -5520,19 +5227,16 @@ PQsetNoticeProcessor(PGconn *conn, - 当接收到一个服务器产生的或者libpq内部产生的通知或警告消息,通知接收器函数会被调用。 - 它会以一种PGRES_NONFATAL_ERROR PGresult的形式传递该消息 - (这允许接收器使用抽取个别的域,或者使用或者得到一个完整的预格式化的消息)。 - 被传递给PQsetNoticeReceiver的同一个空指针也被传递(必要时,这个指针可以被用来访问应用相关的状态)。 - + 从服务器收到通知或警告消息,或者 libpq 内部生成这类消息时,便会调用通知接收器函数。消息以状态为 PGRES_NONFATAL_ERRORPGresult 对象传给该函数。(接收器可使用 提取单个字段,也可使用 获取完整的预格式化消息。)传给 PQsetNoticeReceiver 的同一个 void 指针也会传入。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知接收器会简单地抽取消息(使用)并且将它传递给通知处理器。 - 通知处理器负责处理一个以文本形式给出的通知或警告消息。该消息的字符串文本(包括一个收尾的新行)被传递给通知处理器,外加一个同时被传递给PQsetNoticeProcessor的空指针(必要时,这个指针可以被用来访问应用相关的状态)。 - + 通知处理器负责处理以文本形式提供的通知或警告消息。传给它的参数包括消息字符串(含末尾的换行符),以及先前传给 PQsetNoticeProcessor 的同一个 void 指针。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知处理器很简单: @@ -5546,9 +5250,8 @@ defaultNoticeProcessor(void *arg, const char *message) - 一旦你设定了一个通知接收器或处理器,你应该期待只要PGconn对象或者从它构造出的PGresult对象存在,该函数就应该能被调用。 - 在一个PGresult创建时,PGconn的当前通知处理指针被复制到PGresult中,以备类似的函数使用。 - + 设置通知接收器或处理器后,应当预期:只要 PGconn 对象或由它生成的 PGresult 对象仍存在,就可能调用该函数。创建 PGresult 时,会将 PGconn 当前的通知处理指针复制到 PGresult 中,供 等函数在需要时使用。 + @@ -5557,19 +5260,19 @@ defaultNoticeProcessor(void *arg, const char *message) 事件系统 - libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和毁灭。一种主要的使用情况是这允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 + libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和销毁。一个主要用途是允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 - 每个注册的事件处理程序都与两个数据相关联,libpq仅将其视为不透明的void *指针。 - 有一个透传指针,当事件处理程序与PGconn注册时,应用程序提供。 + 每个注册的事件处理程序都与两项数据相关联,libpq仅将其视为不透明的void *指针。 + 有一个透传指针,由应用程序在向 PGconn 注册事件处理程序时提供。 透传指针在PGconn及其生成的所有PGresult的生命周期内永远不会更改; 因此,如果使用,它必须指向长期存在的数据。 此外,还有一个实例数据指针,在每个PGconnPGresult中一开始都是NULL。 可以使用函数来操作此指针。 请注意,与透传指针不同,PGconn的实例数据不会自动继承到从中创建的PGresult。 - libpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 —— 这是事件处理程序的责任。 + libpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 — 这是事件处理程序的责任。 @@ -5584,65 +5287,38 @@ defaultNoticeProcessor(void *arg, const char *message) PGEVT_REGISTER - - - 注册事件发生在调用时。这是初始化任何事件过程可能需要的instanceData的理想时间。每个事件处理程序每个连接只会触发一次注册事件。如果事件过程失败(返回零),注册将被取消。 - - + 注册事件在被调用时触发。此时最适合初始化事件过程可能需要的instanceData。每个连接中的每个事件过程只会触发一次注册事件。如果事件过程失败,则中止注册。 typedef struct { PGconn *conn; } PGEventRegister; - - - 当接收到PGEVT_REGISTER事件时,evtInfo指针应该转换为PGEventRegister *。这个结构体包含一个应该处于CONNECTION_OK状态的PGconn;如果在获得一个良好的PGconn后立即调用,则保证这一点。当返回一个失败代码时,所有清理工作必须完成,因为不会发送任何PGEVT_CONNDESTROY事件。 - +收到PGEVT_REGISTER事件时,应将evtInfo指针强制转换为PGEventRegister *。此结构体包含一个PGconn,它应处于CONNECTION_OK状态;如果调用紧接在取得正常的PGconn之后,就能保证这一点。返回失败代码时,必须完成全部清理工作,因为不会发送PGEVT_CONNDESTROY事件。 PGEVT_CONNRESET - - - 连接重置事件在完成PQresetPoll后触发。 - 在这两种情况下,只有在重置成功时才会触发事件。 - 在PostgreSQL v15及更高版本中,事件过程的返回值将被忽略。 - 然而,在早期版本中,重要的是返回成功(非零),否则连接将被中止。 + 连接重置事件会在完成以下调用时触发:PQresetPoll。在这两种情况下,只有重置成功才会触发该事件。如果事件过程失败,整个连接重置就会失败;PGconn会被置于CONNECTION_BAD状态,并且PQresetPoll将返回PGRES_POLLING_FAILED typedef struct { PGconn *conn; } PGEventConnReset; - - - 当接收到PGEVT_CONNRESET事件时,evtInfo指针应转换为PGEventConnReset *。 - 尽管包含的PGconn刚刚被重置,但所有事件数据仍保持不变。 - 此事件应用于重置/重新加载/重新查询任何相关的instanceData。 - 请注意,即使事件过程未能处理PGEVT_CONNRESET,当连接关闭时仍会收到PGEVT_CONNDESTROY事件。 - +收到PGEVT_CONNRESET事件时,应将evtInfo指针强制转换为PGEventConnReset *。虽然其中的PGconn刚刚被重置,但所有事件数据都保持不变。应利用此事件重置、重新加载或重新查询相关联的instanceData。注意,即使事件过程未能处理PGEVT_CONNRESET,它仍会在连接关闭时收到PGEVT_CONNDESTROY事件。 PGEVT_CONNDESTROY - - - 为了响应,连接销毁事件会被触发。由于 libpq 没有能力管理事件数据,事件过程有责任正确地清理它的事件数据。清理失败将会导致内存泄露。 - - + 连接销毁事件由以下调用触发:。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGconn *conn; } PGEventConnDestroy; - - - 当接收到一个PGEVT_CONNDESTROY事件时,evtInfo指针应该被类型转换为PGEventConnDestroy *。 - 这个事件在执行任何其他清理之前被触发。 - 该事件过程的返回值被忽略,因为没有办法指示一个来自的失败。还有,一个事件过程失败不该中断对不需要的内存的清理。 - +收到PGEVT_CONNDESTROY事件时,应将evtInfo指针强制转换为PGEventConnDestroy *。该事件触发于以下函数执行任何其他清理工作之前:。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:。此外,事件过程失败不应中止清理不再使用的内存的过程。 @@ -5675,44 +5351,25 @@ typedef struct PGEVT_RESULTCOPY - - - 结果复制事件是响应于而触发的。此事件仅在复制完成后触发。 - 只有成功处理源结果的PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件过程才会接收PGEVT_RESULTCOPY事件。 - - + 结果复制事件会在调用时触发。只有复制完成后才会触发该事件。只有为源结果成功处理过PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件过程,才会收到PGEVT_RESULTCOPY事件。 typedef struct { const PGresult *src; PGresult *dest; } PGEventResultCopy; - - - 当接收到PGEVT_RESULTCOPY事件时,evtInfo指针应转换为PGEventResultCopy *。 - src结果是被复制的内容,而dest结果是复制的目标。此事件可用于提供instanceData的深度复制,因为PQcopyResult无法做到这一点。 - 如果事件过程失败(返回零),那个事件过程将在新结果的剩余生命周期内被忽略;也就是说,它将不会接收PGEVT_RESULTCOPYPGEVT_RESULTDESTROY事件,无论是针对该结果还是针对从中复制的结果。 - +收到PGEVT_RESULTCOPY事件时,应将evtInfo指针强制转换为PGEventResultCopy *。其中,src结果是复制源,而dest结果是复制目标。可以利用此事件对instanceData进行深复制,因为PQcopyResult无法完成这项工作。如果事件过程失败,整个复制操作就会失败,并且dest结果将被清除。返回失败代码时,必须完成所有清理工作,因为不会为目标结果发送PGEVT_RESULTDESTROY事件。 PGEVT_RESULTDESTROY - - - 为了响应,结果销毁事件会被触发。由于 libpq 没有能力管理事件数据,事件过程有责任正确地清理它的事件数据。清理失败将会导致内存泄露。 - - + 结果销毁事件由以下调用触发:。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGresult *result; } PGEventResultDestroy; - - - 当接收到一个PGEVT_RESULTDESTROY事件时,evtInfo指针应该被类型转换为PGEventResultDestroy *。 - 这个事件在执行任何其他清理之前被触发。该事件过程的返回值被忽略,因为没有办法指示来自的失败。 - 还有,一个事件过程失败不该中断不需要的内存的清理过程。 - +收到PGEVT_RESULTDESTROY事件时,应将evtInfo指针强制转换为PGEventResultDestroy *。该事件触发于以下函数执行任何其他清理工作之前:。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:。此外,事件过程失败不应中止清理不再使用的内存的过程。 @@ -5720,7 +5377,7 @@ typedef struct - 事件回调函数 + 事件回调过程 @@ -5730,16 +5387,11 @@ typedef struct - PGEventProc是到一个事件过程的指针的 typedef,也就是从 libpq 接收事件的用户回调函数。一个事件过程的原型必须是 - + PGEventProc 是通过 typedef 定义的事件过程指针类型,也就是接收 libpq 事件的用户回调函数的指针类型。事件过程的签名必须为: int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) - - evtId指示发生了哪一个PGEVT事件。 - evtInfo指针必须被类型转换为合适的结构体类型才能获得关于事件的进一步信息。 - 当事件过程已被注册时,passThrough参数是提供给的指针。 - 如果成功,该函数应该返回非零值,失败则返回零。 +evtId 参数指示发生了哪一种 PGEVT 事件。必须将 evtInfo 指针强制转换为适当的结构体类型,以获取关于该事件的更多信息。passThrough 参数是在注册事件过程时传给 的指针。函数应在成功时返回非零值,在失败时返回零。 @@ -5749,8 +5401,8 @@ int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) - 在 Windows 上,函数能够有两个不同的地址:一个对 DLL 之外可见而另一个对 DLL 之内可见。我们应当小心只有其中之一会被用于libpq的事件过程函数,否则将会产生混淆。编写代码的最简单规则是将所有的事件过程声明为static。如果过程的地址必须对它自己的源代码文件之外可见,提供一个单独的函数来返回该地址。 - + 在 Windows 上,函数可能有两个不同的地址:一个在 DLL 外部可见,另一个在 DLL 内部可见。使用 libpq 的事件过程函数时,务必始终使用其中同一个地址,否则会产生混淆。确保代码正常工作的最简单做法,是将事件过程声明为 static。如果需要在过程所在的源文件之外取得其地址,应提供一个单独的函数来返回该地址。 + @@ -5778,7 +5430,7 @@ int PQregisterEventProc(PGconn *conn, PGEventProc proc, - 在每一个你想要接收事件的PGconn上必须注册一个事件过程。和内存不同,没有限制说一个连接上能注册多少个事件过程。如果该函数成功,它会返回一个非零值。如果它失败,则会返回零。 + 对于希望接收其事件的每个 PGconn,都必须注册一次事件过程。一个连接可注册的事件过程数量只受内存限制。函数成功时返回非零值,失败时返回零。 @@ -5823,16 +5475,14 @@ void *PQinstanceData(const PGconn *conn, PGEventProc proc); - 把结果的用于procinstanceData设置为data。成功返回非零,失败返回零(只有proc没有被正确地注册在conn中,才可能会失败)。 - + 将结果中针对 procinstanceData 设置为 data。成功时返回非零值,失败时返回零。(只有当 proc 未在结果中正确注册时,才可能失败。) int PQresultSetInstanceData(PGresult *res, PGEventProc proc, void *data); - 请注意,data表示的任何存储都不会由考虑,除非使用分配。 - (这样做是值得推荐的,因为它消除了在销毁结果时显式释放此类存储的需要。) + 注意,data 所指的存储不会计入 ,除非使用 分配它。(推荐这样做,因为结果销毁时便不必显式释放这部分存储。) @@ -5856,18 +5506,18 @@ void *PQresultInstanceData(const PGresult *res, PGEventProc proc); - 事件实例 + 事件示例 - 这里是一个管理与 libpq 连接和结果相关的私有数据的示例的框架。 - + 下面给出一个示例框架,用于管理与 libpq 连接和结果关联的私有数据。 + -/* The instanceData */ +/* instanceData 数据 */ typedef struct { int n; @@ -5887,14 +5537,14 @@ main(void) if (PQstatus(conn) != CONNECTION_OK) { - /* PQerrorMessage's result includes a trailing newline */ + /* PQerrorMessage 的结果包含末尾的换行符 */ fprintf(stderr, "%s", PQerrorMessage(conn)); PQfinish(conn); return 1; } - /* called once on any connection that should receive events. - * Sends a PGEVT_REGISTER to myEventProc. + /* 在每个需要接收事件的连接上调用一次。 + * 向 myEventProc 发送 PGEVT_REGISTER 事件。 */ if (!PQregisterEventProc(conn, myEventProc, "mydata_proc", NULL)) { @@ -5903,28 +5553,28 @@ main(void) return 1; } - /* conn instanceData is available */ + /* 可以取得 conn 的 instanceData */ data = PQinstanceData(conn, myEventProc); - /* Sends a PGEVT_RESULTCREATE to myEventProc */ + /* 向 myEventProc 发送 PGEVT_RESULTCREATE 事件 */ res = PQexec(conn, "SELECT 1 + 1"); - /* result instanceData is available */ + /* 可以取得结果的 instanceData */ data = PQresultInstanceData(res, myEventProc); - /* If PG_COPYRES_EVENTS is used, sends a PGEVT_RESULTCOPY to myEventProc */ + /* 使用 PG_COPYRES_EVENTS 时,向 myEventProc 发送 PGEVT_RESULTCOPY 事件 */ res_copy = PQcopyResult(res, PG_COPYRES_TUPLES | PG_COPYRES_EVENTS); - /* result instanceData is available if PG_COPYRES_EVENTS was - * used during the PQcopyResult call. + /* 如果调用 PQcopyResult 时使用了 PG_COPYRES_EVENTS, + * 就可以取得结果的 instanceData。 */ data = PQresultInstanceData(res_copy, myEventProc); - /* Both clears send a PGEVT_RESULTDESTROY to myEventProc */ + /* 两次清除操作都会向 myEventProc 发送 PGEVT_RESULTDESTROY 事件 */ PQclear(res); PQclear(res_copy); - /* Sends a PGEVT_CONNDESTROY to myEventProc */ + /* 向 myEventProc 发送 PGEVT_CONNDESTROY 事件 */ PQfinish(conn); return 0; @@ -5940,7 +5590,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventRegister *e = (PGEventRegister *)evtInfo; mydata *data = get_mydata(e->conn); - /* associate app specific data with connection */ + /* 将应用程序特有的数据与连接关联 */ PQsetInstanceData(e->conn, myEventProc, data); break; } @@ -5960,7 +5610,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventConnDestroy *e = (PGEventConnDestroy *)evtInfo; mydata *data = PQinstanceData(e->conn, myEventProc); - /* free instance data because the conn is being destroyed */ + /* 连接正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; @@ -5972,7 +5622,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *conn_data = PQinstanceData(e->conn, myEventProc); mydata *res_data = dup_mydata(conn_data); - /* associate app specific data with result (copy it from conn) */ + /* 将应用程序特有的数据与结果关联(从 conn 复制) */ PQresultSetInstanceData(e->result, myEventProc, res_data); break; } @@ -5983,7 +5633,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *src_data = PQresultInstanceData(e->src, myEventProc); mydata *dest_data = dup_mydata(src_data); - /* associate app specific data with result (copy it from a result) */ + /* 将应用程序特有的数据与结果关联(从另一个结果复制) */ PQresultSetInstanceData(e->dest, myEventProc, dest_data); break; } @@ -5993,18 +5643,18 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventResultDestroy *e = (PGEventResultDestroy *)evtInfo; mydata *data = PQresultInstanceData(e->result, myEventProc); - /* free instance data because the result is being destroyed */ + /* 结果正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; } - /* unknown event ID, just return true. */ + /* 未知的事件 ID,直接返回 true。 */ default: break; } - return true; /* event processing succeeded */ + return true; /* 事件处理成功 */ } ]]> @@ -6020,9 +5670,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 以下环境变量可用于选择默认连接参数值,这些值将被使用,如果调用代码没有直接指定值。这些对于避免将数据库连接信息硬编码到简单的客户端应用程序中非常有用,例如。 - - + 以下环境变量可用于选择连接参数的默认值,供 在调用代码未直接指定参数值时使用。例如,这样可以避免在简单的客户端应用程序中硬编码数据库连接信息。 + @@ -6130,9 +5779,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSERVICEFILE - PGSERVICEFILE指定每个用户的连接服务文件的名称 - (参见)。 - 默认为~/.pg_service.conf,或者在Microsoft Windows上为%APPDATA%\postgresql\.pg_service.conf。 + PGSERVICEFILE指定每个用户的连接服务文件的名称(参见)。 + 默认为~/.pg_service.conf,或者在 Microsoft Windows 上为%APPDATA%\postgresql\.pg_service.conf @@ -6177,7 +5825,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGREQUIRESSL的行为与连接参数相同。 - 这个环境变量已被弃用,推荐使用PGSSLMODE变量;设置这两个变量会抑制这个变量的效果。 + 这个环境变量已被弃用,推荐使用PGSSLMODE变量;同时设置这两个变量时,前者不再生效。 @@ -6360,9 +6008,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 下面的环境变量可用来为每一个PostgreSQL会话指定默认行为(为每一个用户或每一个数据库设置默认行为的方法还可见命令)。 - - + 以下环境变量可用于指定每个 PostgreSQL 会话的默认行为。(也可参见 命令,了解按用户或按数据库设置默认行为的方法。) + @@ -6390,8 +6037,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - - 这些环境变量的正确值可参考SQL 命令 。 +有关这些环境变量的正确取值,请参见 SQL 命令 @@ -6436,16 +6082,12 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) 用户主目录中的.pgpass文件可保存密码,供连接需要密码且尚未通过其他方式指定密码时使用。在 Microsoft Windows 上,文件名为%APPDATA%\postgresql\pgpass.conf(其中%APPDATA%指用户配置文件中的应用数据子目录)。也可以通过连接参数或环境变量PGPASSFILE指定要使用的密码文件。 - - 这个文件应该包含下列格式的行: - + 该文件中的行应采用以下格式: hostname:port:database:username:password - - (你可以向该文件增加一个提醒:把上面的行复制到该文件并且在前面加上#)。前四个字段的每一个都可以是字面值或者匹配任何东西的*。第一个匹配当前连接参数的行中的密码字段将被使用(因此,在使用通配符时把更特殊的项放在前面)。如果一个条目需要包含:或者\,用\对该字符转义。如果指定了host连接参数,主机名字段会被匹配到host,否则如果指定了hostaddr参数则匹配到hostaddr,如果两者都没有给出,则会搜索主机名localhost。当连接是一个Unix域套接字连接并且host参数匹配libpq的默认套接字目录路径时,也会搜索主机名localhost。在一台备库上,值为replication的数据库字段匹配连接到主库的流复制连接。否则数据库字段的用途有限,因为用户对同一个集簇中的所有数据库都有相同的密码。 - +(可以复制上面这一行,并在行首加上#,在文件中加入提示注释。)前四个字段中的每一个都可以是字面值,或者是*,后者可以匹配任何内容。将使用与当前连接参数匹配的第一行中的密码字段。(因此,使用通配符时,应将更具体的条目放在前面。)如果条目需要包含:\,请使用\转义该字符。主机名字段首先匹配已指定的host连接参数;否则匹配已指定的hostaddr参数。如果两者都未指定,则查找主机名localhost。在以下情况下也会查找主机名localhost:连接使用 Unix 域套接字,且host参数与libpq的默认套接字目录路径匹配。在备库中,数据库字段为replication时,匹配连接到主库的流复制连接。除此之外,数据库字段的用途有限,因为同一用户在同一数据库集簇的所有数据库中使用相同的密码。 - 在 Unix 系统上,密码文件上的权限必须不允许所有人或组内访问,可以用chmod 0600 ~/.pgpass这样的命令实现。如果权限没有这么严格,该文件将被忽略。在微软 Windows 上,该文件被假定存储在一个安全的目录中,因此不会进行特别的权限检查。 + 在 Unix 系统上,密码文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.pgpass 这样的命令实现。如果权限没有这么严格,该文件将被忽略。在 Microsoft Windows 上,假定该文件存储在安全的目录中,因此不进行特殊的权限检查。 @@ -6466,10 +6108,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 连接服务文件允许 libpq 连接参数与一个单一服务名称关联。 - 那个服务名称可以在一个 libpq 连接字符串里面指定,与其相关的设置将被使用。 - 这允许在不重新编译使用 libpq 的应用的前提下修改连接参数。 - 服务名称也可以被使用PGSERVICE环境变量来指定。 + 连接服务文件允许将 libpq 连接参数与单个服务名称关联。随后可以在 libpq 连接字符串中指定该服务名称,从而使用关联的设置。这样便可以修改连接参数,而无需重新编译使用 libpq 的应用程序。也可以使用 PGSERVICE 环境变量指定服务名称。 @@ -6485,23 +6124,19 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 或者服务文件使用一种INI 文件格式,其中小节名是服务名并且参数是连接参数。 - 列表见。例如: + 两种服务文件均使用 INI 文件 格式,其中配置段名称是服务名称,参数是连接参数;参数列表见 。例如: -# comment +# 注释 [mydb] host=somehost port=5433 user=admin - 在PostgreSQL安装的share/pg_service.conf.sample中提供了一个示例文件。 +PostgreSQL 安装目录中的 share/pg_service.conf.sample 提供了一个示例文件。 - 从服务文件中获取的连接参数与从其他来源获取的参数相结合。 - 服务文件设置覆盖相应的环境变量,然后反过来可以由连接字符串中直接给出的值覆盖。 - 例如,使用上面的服务文件,连接字符串service=mydb port=5434将使用主机somehost,端口5434, - 用户admin,以及由环境变量或内置默认所设置的其他参数。 + 从服务文件中获取的连接参数会与其他来源的参数合并。服务文件中的设置会覆盖相应的环境变量,而连接字符串中直接给出的值又会覆盖服务文件中的设置。例如,使用上述服务文件时,连接字符串 service=mydb port=5434 将使用主机 somehost、端口 5434、用户 admin,以及由环境变量或内置默认值设置的其他参数。 @@ -6517,24 +6152,14 @@ user=admin 如果libpq已经在编译时打开了 LDAP 支持(configure的选项),就可以通过 LDAP 从一个中央服务器检索hostdbname之类的连接参数。这样做的好处是如果一个数据库的连接参数改变,不需要在所有的客户端机器上更新连接信息。 - - LDAP连接参数查找使用连接服务文件pg_service.conf(参见)。 - 在pg_service.conf段落中以ldap://开头的行将被识别为LDAP URL,并执行LDAP查询。 - 结果必须是一组keyword = value对,将用于设置连接选项。 - URL必须符合RFC 1959的形式为 - + LDAP 连接参数查询使用连接服务文件pg_service.conf(参见)。在pg_service.conf的配置段中,以ldap://开头的行会被识别为 LDAP URL,并执行 LDAP 查询。结果必须是一个keyword = value键值对列表,用于设置连接选项。URL 必须符合 RFC 1959,格式如下: ldap://[hostname[:port]]/search_base?attribute?search_scope?filter - - 其中hostname默认为localhostport默认为389。 - +其中,hostname默认为localhostport默认为 389。 - - 一次成功的 LDAP 查找后,pg_service.conf的处理被终止。但是如果联系不上 LDAP 则会继续处理pg_service.conf。这就提供了后手,可以加入更多指向不同 LDAP 服务器的 LDAP URL 行、经典的keyword = value对或者默认连接选项。如果你宁愿在这种情况下得到一个错误消息,在该 LDAP URL 之后增加一个语法错误的行。 - + LDAP 查找成功后就会停止处理 pg_service.conf;如果无法联系 LDAP 服务器,则会继续处理。这使后续指向其他 LDAP 服务器的 LDAP URL 行、常规的 keyword = value 对或默认连接选项能够作为后备。如果希望在这种情况下得到错误消息,可以在 LDAP URL 后添加一个语法不正确的行。 - - 一个和 LDIF 文件一起创建的 LDAP 条目实例 - + 例如,使用以下 LDIF 文件创建的 LDAP 条目: version:1 dn:cn=mydatabase,dc=mycompany,dc=com changetype:add @@ -6546,9 +6171,7 @@ description:port=5439 description:dbname=mydb description:user=mydb_user description:sslmode=require - - 可以用下面的 LDAP URL 查询: - +可以通过以下 LDAP URL 查询: ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase) @@ -6556,7 +6179,7 @@ ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase) 你也可以将常规的服务文件条目和 LDAP 查找混合。pg_service.conf中一节的完整示例: -# 只有主机和端口存储在LDAP中,显式指定dbname和user。 +# 仅 host 和 port 存储在 LDAP 中;显式指定 dbname 和 user [customerdb] dbname=customer user=appuser @@ -6572,13 +6195,9 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) SSL - TLS - - PostgreSQL具有原生支持使用SSL连接来加密客户端/服务器通信, - 使用TLS协议以提高安全性。有关服务器端SSL功能的详细信息,请参见。 - + PostgreSQL 原生支持使用 SSL 连接来加密客户端与服务器之间的通信,以提高安全性。有关服务器端 SSL 功能的详细信息,请参见 libpq读取系统范围的OpenSSL配置文件。默认情况下,这个文件被命名为openssl.cnf并且位于openssl version -d所报告的目录中。可以通过设置环境变量OPENSSL_CONF把这个默认值覆盖为想要的配置文件的名称。 @@ -6586,40 +6205,17 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 服务器证书的客户端验证 + 客户端对服务器证书的验证 - 默认情况下,PostgreSQL将不会执行服务器证书的任何验证。这意味着可以在不被客户端知晓的情况下伪造服务器身份(例如通过修改一个 DNS 记录或者接管服务器的 IP 地址)。为了阻止哄骗,客户端必须能够通过一条信任链验证服务器的身份。信任链可以这样建立:在一台计算机上放置一个根(自签名的)证书机构(CA)的证书并且在另一台计算机上放置一个由根证书签发的叶子证书。还可以使用一种中间证书,它由根证书签发并且可以签发叶子证书。 + 默认情况下,PostgreSQL 不会对服务器证书执行任何验证。这意味着可以在客户端不知情的情况下伪造服务器身份,例如修改 DNS 记录或接管服务器的 IP 地址。要防止身份伪造,客户端必须能够通过信任链验证服务器身份。建立信任链的方法是:在一台计算机上放置根证书机构(CA)的自签名证书,在另一台计算机上放置由根证书签发的叶证书。也可以使用由根证书签发、又用于签发叶证书的中间证书。 - - 为了允许客户端验证服务器的身份,在客户端上放置一份根证书并且在服务器上放置由根证书签发的叶子证书。为了允许服务器验证客户端的身份,在服务器上放置一份根证书并且在客户端上放置由根证书签发的叶子证书。也可以使用一个或者更多个中间证书(通常与叶子证书存在一起)来将叶子证书链接到根证书。 - - - - 一旦信任链被建立起来,客户端有两种方法验证服务器发过来的叶子证书。如果参数sslmode被设置为verify-ca,libpq将通过检查该证书是否链接到存储在客户端上的根证书来验证服务器。如果sslmode被设置为verify-full,libpq将验证服务器的主机名匹配存储在服务器证书中的名称。如果服务器证书无法被验证,则SSL连接将失败。在大部分对安全性很敏感的环境中,推荐使用verify-full。 - - - - 在verify-full模式下,主机名将与证书的主体替代名称属性(SAN)匹配, - 或者与通用名称属性匹配,如果没有类型为dNSName的SAN存在。 - 如果证书的名称属性以星号(*)开头,那么星号将被视为通配符, - 可以匹配所有字符,除了点(.)。 - 这意味着证书将不匹配子域。如果连接使用IP地址而不是主机名进行, - 则IP地址将与类型为iPAddressdNSName的SAN匹配 - (不进行任何DNS查找)。如果没有iPAddress SAN存在, - 也没有匹配的dNSName SAN存在,则主机IP地址将与通用名称属性匹配。 - + 要让客户端验证服务器的身份,请在客户端放置根证书,并在服务器上放置由该根证书签发的叶证书。要让服务器验证客户端的身份,请在服务器上放置根证书,并在客户端放置由该根证书签发的叶证书。也可以使用一个或多个中间证书(通常与叶证书存储在一起),将叶证书链接到根证书。 - + 建立信任链后,客户端可以通过两种方式验证服务器发送的叶证书。如果参数 sslmode 设为 verify-ca,libpq 会沿证书链检查到存储在客户端上的根证书,以验证服务器是否可信。如果 sslmode 设为 verify-full,libpq 还会验证服务器主机名是否与服务器证书中存储的名称匹配。如果无法验证服务器证书,SSL 连接将失败。在大多数对安全敏感的环境中,建议使用 verify-full - - 为了与早期版本的PostgreSQL向后兼容,主机IP地址的验证方式与 - RFC 6125中的方式不同。 - 主机IP地址始终与dNSName SANs以及iPAddress SANs匹配, - 如果不存在相关的SANs,则可以与通用名称属性匹配。 - - + verify-full 模式下,会将主机名与证书的主体替代名称属性匹配;如果不存在类型为 dNSName 的主体替代名称,则与通用名称属性匹配。如果证书的名称属性以星号(*)开头,该星号会被视为通配符,匹配点(.)以外的所有字符。这意味着该证书不会匹配子域。如果使用 IP 地址而不是主机名建立连接,则会匹配该 IP 地址(不执行任何 DNS 查询)。 要允许服务器证书验证,必须将一个或者更多个根证书放置在用户主目录下的~/.postgresql/root.crt文件中(在Microsoft Windows上该文件名为%APPDATA%\postgresql\root.crt)。如果需要把服务器发来的证书链链接到存储在客户端的根证书,还应该将中间证书加到该文件中。 @@ -6638,8 +6234,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 为了与 PostgreSQL 的早期版本达到向后兼容,如果存在一个根 CA 文件,sslmode=require的行为将与verify-ca相同,即服务器证书根据 CA 验证。我们鼓励依赖这种行为,并且需要证书验证的应用应该总是使用verify-ca或者verify-full。 - + 为与 PostgreSQL 的早期版本向后兼容,如果存在根 CA 文件,sslmode=require 的行为将与 verify-ca 相同,即根据 CA 验证服务器证书。不建议依赖这种行为;需要证书验证的应用程序应始终使用 verify-caverify-full。 + @@ -6648,44 +6244,27 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 客户端证书 - 如果服务器尝试通过请求客户端的叶证书来验证客户端的身份, - libpq将发送存储在文件 - ~/.postgresql/postgresql.crt中的证书,该文件位于用户的主目录中。 - 证书必须链到服务器信任的根证书。匹配的 - 私钥文件~/.postgresql/postgresql.key也必须存在。 - 在Microsoft Windows上,这些文件的名称分别为 - %APPDATA%\postgresql\postgresql.crt和 - %APPDATA%\postgresql\postgresql.key。 - 证书和密钥文件的位置可以通过连接参数 - sslcertsslkey, - 或通过环境变量PGSSLCERTPGSSLKEY来覆盖。 - + 如果服务器请求客户端的叶证书以验证客户端身份,libpq 将发送用户主目录下 ~/.postgresql/postgresql.crt 文件中存储的证书。这些证书必须通过证书链连接到服务器信任的根证书。还必须存在匹配的私钥文件 ~/.postgresql/postgresql.key。在 Microsoft Windows 上,这两个文件分别名为 %APPDATA%\postgresql\postgresql.crt%APPDATA%\postgresql\postgresql.key。可以通过连接参数 sslcertsslkey,或环境变量 PGSSLCERTPGSSLKEY,覆盖证书和密钥文件的位置。 + - 在Unix系统上,私钥文件的权限必须禁止任何对世界或组的访问;可以通过类似以下命令来实现: - chmod 0600 ~/.postgresql/postgresql.key。 - 或者,该文件可以由root拥有并具有组读取权限(即0640权限)。 - 该设置适用于由操作系统管理证书和密钥文件的安装。然后,libpq的用户应该成为具有对这些证书和密钥文件访问权限的组的成员。 - (在Microsoft Windows上,没有文件权限检查,因为假定%APPDATA%\postgresql目录是安全的。) - + 在 Unix 系统上,私钥文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.postgresql/postgresql.key 这样的命令实现。另一种做法是使文件归 root 所有,并允许组用户读取(即 0640 权限)。这种设置适用于由操作系统管理证书和密钥文件的安装环境。此时,应将 libpq 用户加入有权访问这些证书和密钥文件的组。(在 Microsoft Windows 上,不检查文件权限,因为假定 %APPDATA%\postgresql 目录是安全的。) + postgresql.crt中的第一个证书必须是客户端的证书,因为它必须匹配客户端的私钥。可以选择将中间证书追加到该文件 — 这样做避免了在服务器上存放中间证书的要求()。 - 证书和密钥可能是 PEM 或 ASN.1 DER 格式。 + 证书和密钥可以采用 PEM 或 ASN.1 DER 格式。 - 密钥可以以明文存储,也可以使用OpenSSL支持的任何算法(例如AES-128)使用密码进行加密。 - 如果密钥是加密存储的,那么可以在连接选项中提供密码。 - 如果提供了加密密钥,而且sslpassword选项不存在或为空,那么只要 TTY 可用,OpenSSL就会以Enter PEM pass phrase:提示交互式输入密码。 - 应用程序可以通过提供自己的密钥密码回调,覆盖客户端证书提示以及sslpassword参数的处理;参见。 + 密钥可以以明文存储,也可以使用密码,按 OpenSSL 支持的任意算法(例如 AES-128)进行加密。如果密钥以加密形式存储,可以在 连接选项中提供密码。如果提供了加密密钥,而 sslpassword 选项缺失或为空,则在有 TTY 可用时,OpenSSL 会显示 Enter PEM pass phrase: 提示,交互式地请求输入密码。应用程序可以提供自己的密钥密码回调,以覆盖客户端证书提示及 sslpassword 参数的处理;参见 - 创建证书的指令请参考。 + 有关创建证书的说明,请参见 @@ -6694,8 +6273,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 不同模式中提供的保护 - sslmode参数的不同值提供了不同级别的保护。SSL 能够针对三类攻击提供保护: - + sslmode 参数的不同值提供不同级别的保护。SSL 可以防范三类攻击: 窃听 @@ -6708,31 +6286,33 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 中间人(MITM - 如果一个第三方能对客户端和服务器之间传送的数据进行修改,它就能假装是服务器并且因此能看见并且修改数据,即使这些数据已被加密。然后第三方可以将连接信息和数据转送给原来的服务器,使得它不可能检测到攻击。这样做的通常途径包括 DNS 污染和地址劫持,借此客户端被重定向到一个不同的服务器。还有几种其他的攻击方式能够完成这种攻击。SSL使用证书验证让客户端认证服务器,就可以阻止这种攻击。 - + + 如果第三方能修改客户端与服务器之间传输的数据,就可以冒充服务器,进而查看和修改数据,即使数据已经加密。随后,第三方可以将连接信息和数据转发给原来的服务器,使攻击无法被察觉。常见的手段包括 DNS 污染和地址劫持,从而将客户端引向预期之外的服务器。还有其他几种攻击手段可以达到同样的目的。SSL 使用证书验证,让客户端认证服务器身份,以防范这种攻击。 + - 模仿 + 冒充 - 如果一个第三方能假装是一个授权的客户端,它能够简单地访问它本不能访问的数据。通常这可以由不安全的密码管理所致。SSL使用客户端证书来确保只有持有合法证书的客户端才能访问服务器,这样就能阻止这种攻击。 - + + 如果第三方能冒充获授权的客户端,就能直接访问其无权访问的数据。这通常可能由不安全的密码管理导致。SSL 使用客户端证书,确保只有持有有效证书的客户端才能访问服务器,以防范这种攻击。 + - 对于一个已知受 SSL 保护的连接,在连接建立之前,必须在客户端和服务器两端都配置 SSL。如果只在服务器端配置,客户端在得知服务器要求高安全性之前,可能就已经开始发送敏感信息(例如密码)。在 libpq 中,要确保连接安全,可以把sslmode参数设置为verify-fullverify-ca,并为系统提供一个用于验证的根证书。这类似于使用https URL浏览加密网页。 + 要确保连接受到 SSL 保护,必须在建立连接之前,在客户端和服务器两端配置 SSL。如果仅在服务器上配置,客户端可能在得知服务器要求高安全性之前就已发送敏感信息(例如密码)。在 libpq 中,可以将 sslmode 参数设为 verify-fullverify-ca,并向系统提供用于验证的根证书,以确保连接安全。这类似于使用 https URL 进行加密的网页浏览。 - 一旦服务器已经被认证,客户端可以传递敏感数据。这意味着直到这一点,客户端都不需要知道是否证书将被用于认证,这样只需要在服务器配置中指定就比较安全。 + 服务器通过身份认证后,客户端便可以传送敏感数据。这意味着,在此之前,客户端无需知道是否会使用证书进行认证,因此可以安全地仅在服务器配置中指定这一点。 - 所有SSL选项都带来了加密和密钥交换的负荷,因此必须在性能和安全性之间做出平衡。不同sslmode值所保护的风险,以及它们是怎样看待安全性和负荷的。 + 所有 SSL 选项都会产生加密和密钥交换的开销,因此必须在性能与安全性之间作出权衡。 说明了不同 sslmode 值所能防范的风险,以及它们所表达的对安全性和开销的取舍。
@@ -6748,7 +6328,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) sslmode 窃听保护 - 中间人攻击防护 + MITM 防护 声明 @@ -6759,7 +6339,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) disable - 我不关心安全性,并且我不想为加密增加负荷。 + 我不关心安全性,并且我不想为加密增加开销。 @@ -6767,7 +6347,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) allow 可能 - 我不关心安全性,但如果服务器坚持,我将承担加密带来的负荷。 + 我不关心安全性,但如果服务器坚持,我将承担加密带来的开销。 @@ -6775,7 +6355,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) prefer 可能 - 我不关心安全性,但如果服务器支持,我希望承担加密带来的负荷。 + 我不关心加密,但如果服务器支持,我希望承担加密带来的开销。 @@ -6783,7 +6363,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) require - 我想要对数据加密,并且我接受因此带来的负荷。我信任该网络会保证我总是连接到想要连接的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我信任该网络会保证我总是连接到想要连接的服务器。 @@ -6791,7 +6371,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-ca 取决于 CA 策略 - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器。 @@ -6799,7 +6379,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-full - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 @@ -6808,11 +6388,11 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
- verify-caverify-full之间的区别取决于根CA的策略。如果使用了一个公共CAverify-ca允许连接到那些可能已经被其他人注册到该CA的服务器。在这种情况下,总是应该使用verify-full。如果使用了一个本地CA或者甚至是一个自签名的证书,使用verify-ca常常就可以提供足够的保护。 + verify-caverify-full之间的区别取决于根CA的策略。如果使用了一个公共CAverify-ca允许连接到那些可能已经被其他人注册到该CA的服务器。在这种情况下,总是应该使用verify-full。如果使用了一个本地CA或者甚至是一个自签名的证书,使用verify-ca常常就可以提供足够的保护。 - sslmode的默认值是prefer。如表中所示,这在安全性的角度来说没有意义,并且它只承诺可能的性能负荷。提供它作为默认值只是为了向后兼容,并且我们不推荐在安全部署中使用它。 + sslmode 的默认值是 prefer。如表所示,从安全角度看,这一设置没有意义;它只会在可能时带来性能开销。将其作为默认值仅出于向后兼容的考虑,不建议在有安全要求的部署中使用。 @@ -6854,8 +6434,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) ~/.postgresql/root.crt - 可信的证书机构 - 检查服务器证书是由一个可信的证书机构签发 + 受信任的证书机构 + 检查服务器证书是由一个受信任的证书机构签发 @@ -6874,9 +6454,9 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) SSL 库初始化 - 如果您的应用程序初始化libssl和/或libcrypto库,并且libpq - 构建时带有SSL支持,您应该调用告诉libpq - libssl和/或libcrypto库已被您的应用程序初始化,以便 + 如果你的应用程序初始化libssl和/或libcrypto库,并且libpq + 构建时带有SSL支持,你应该调用告诉libpq + libssl和/或libcrypto库已被你的应用程序初始化,以便 libpq不会再初始化这些库。 但是,当使用OpenSSL版本1.1.0或更高版本时,无需这样做,因为重复初始化不再成问题。 @@ -6888,7 +6468,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 允许应用选择要初始化哪个安全性库。 + 允许应用程序选择要初始化的安全库。 void PQinitOpenSSL(int do_ssl, int do_crypto); @@ -6912,7 +6492,7 @@ void PQinitOpenSSL(int do_ssl, int do_crypto); PQinitSSLPQinitSSL - 允许应用选择要初始化哪个安全性库。 + 允许应用程序选择要初始化的安全库。 void PQinitSSL(int do_ssl); @@ -6938,7 +6518,7 @@ void PQinitSSL(int do_ssl); - 在线程化程序中的行为 + 多线程程序中的行为 线程 @@ -6972,7 +6552,9 @@ int PQisthreadsafe(); PGresult对象在创建后通常是只读的,因此可以在线程之间自由传递。不过,如果你使用中描述的任何会修改PGresult的函数,则需要自行避免对同一个PGresult执行并发操作。 - 已弃用的 函数不是线程安全的,不应在多线程程序中使用。可以用 替代 ,用 替代 + + 已弃用的函数 不是线程安全的,不应在多线程程序中使用。 可以用 替代; 可以用 替代。 + 如果你在应用程序中使用 Kerberos(除了libpq内部之外),则需要在 Kerberos 调用周围加锁,因为 Kerberos 函数不是线程安全的。可参考libpq源代码中的PQregisterThreadLock函数,它提供了一种在libpq与应用程序之间协作加锁的方法。 @@ -6981,7 +6563,7 @@ int PQisthreadsafe(); - 编译 <application>libpq</application> 程序 + 构建 <application>libpq</application> 程序 编译 @@ -6989,16 +6571,16 @@ int PQisthreadsafe(); - 要编译(即编译并且链接)一个使用libpq的程序,你需要做下列所有的事情: + 要构建(即编译和链接)一个使用 libpq 的程序,需要完成以下所有步骤: - 包括libpq-fe.h头文件: + 包含 libpq-fe.h 头文件: #include <libpq-fe.h> - 如果你无法这样做,那么你通常会从你的编译器得到像这样的错误消息: +如果没有这样做,编译器通常会给出类似以下内容的错误消息: foo.c: In function `main': foo.c:34: `PGconn' undeclared (first use in this function) @@ -7007,24 +6589,24 @@ foo.c:54: `CONNECTION_BAD' undeclared (first use in this function) foo.c:68: `PGRES_COMMAND_OK' undeclared (first use in this function) foo.c:95: `PGRES_TUPLES_OK' undeclared (first use in this function) - + - 通过为你的编译器提供-Idirectory选项,向你的编译器指出PostgreSQL头文件安装在哪里(在某些情况下编译器默认将查看该目录,因此你可以忽略这个选项)。例如你的编译命令行可能看起来像: + 向编译器提供 -Idirectory 选项,指定 PostgreSQL 头文件的安装目录。(某些情况下,编译器默认会搜索该目录,此时可以省略这个选项。)例如,编译命令行可以是: cc -c -I/usr/local/pgsql/include testprog.c - 如果你在使用 makefile,那么把该选项加到CPPFLAGS变量中: +如果使用 makefile,请将该选项添加到 CPPFLAGS 变量中: CPPFLAGS += -I/usr/local/pgsql/include - + 如果你的程序可能由其他用户编译,那么你不应该像那样硬编码目录位置。你可以运行工具pg_configpg_configwith libpq在本地系统上找出头文件在哪里: + sortas="libpq">用于 libpq
在本地系统上找出头文件在哪里: $ pg_config --includedir /usr/local/include @@ -7032,8 +6614,7 @@ CPPFLAGS += -I/usr/local/pgsql/include - 如果你安装了pkg-configpkg-configwith - libpq,你可以运行: + 如果你安装了pkg-configpkg-config用于 libpq,你可以运行: $ pkg-config --cflags libpq -I/usr/local/include @@ -7042,20 +6623,20 @@ CPPFLAGS += -I/usr/local/pgsql/include - 无法为编译器指定正确的选项将导致一个错误消息,例如: + 未向编译器指定正确的选项将导致类似以下内容的错误消息: testlibpq.c:8:22: libpq-fe.h: No such file or directory - +
- 当链接最终的程序时,指定选项-lpq,这样libpq库会被编译进去,也可以用选项-Ldirectory向编译器指出libpq库所在的位置(再次,编译器将默认搜索某些目录)。为了最大的可移植性,将选项放在选项前面。例如: + 链接最终程序时,指定 -lpq 选项以链接 libpq 库,同时指定 -Ldirectory 选项,告知编译器 libpq 库所在的目录。(同样,编译器默认会搜索某些目录。)为获得最大的可移植性,请将 选项放在 选项之前。例如: cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq - + 你也可以使用pg_config找出库目录: @@ -7082,7 +6663,7 @@ testlibpq.o(.text+0x60): undefined reference to `PQsetdbLogin' testlibpq.o(.text+0x71): undefined reference to `PQstatus' testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' - 这意味着你忘了 . + 这意味着你忘记了 /usr/bin/ld: cannot find -lpq @@ -7099,7 +6680,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' 示例程序 - 这些示例和其他示例可以在源代码发布的src/test/examples目录中找到。 + 这些示例和其他示例可在源代码发行包的src/test/examples目录中找到。 @@ -7114,7 +6695,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' * * testlibpq.c * - * Test the C version of libpq, the PostgreSQL frontend library. + * 测试 PostgreSQL 前端库 libpq 的 C 语言版本。 */ #include #include @@ -7138,26 +6719,25 @@ main(int argc, char **argv) j; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -7168,19 +6748,17 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Our test case here involves using a cursor, for which we must be inside - * a transaction block. We could do the whole thing with a single - * PQexec() of "select * from pg_database", but that's too trivial to make - * a good example. + * 这里的测试用例使用游标,因此必须处于事务块内。 + * 只需调用一次 PQexec() 执行 "select * from pg_database" 就能完成全部操作, + * 但这太简单了,不足以作为一个好的示例。 */ - /* Start a transaction block */ + /* 开始一个事务块 */ res = PQexec(conn, "BEGIN"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -7191,7 +6769,7 @@ main(int argc, char **argv) PQclear(res); /* - * Fetch rows from pg_database, the system catalog of databases + * 从数据库系统目录 pg_database 中获取行 */ res = PQexec(conn, "DECLARE myportal CURSOR FOR select * from pg_database"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -7210,13 +6788,13 @@ main(int argc, char **argv) exit_nicely(conn); } - /* first, print out the attribute names */ + /* 首先,打印属性名 */ nFields = PQnfields(res); for (i = 0; i < nFields; i++) printf("%-15s", PQfname(res, i)); printf("\n\n"); - /* next, print out the rows */ + /* 接着,打印各行 */ for (i = 0; i < PQntuples(res); i++) { for (j = 0; j < nFields; j++) @@ -7226,15 +6804,15 @@ main(int argc, char **argv) PQclear(res); - /* close the portal ... we don't bother to check for errors ... */ + /* 关闭 portal……这里不再检查错误…… */ res = PQexec(conn, "CLOSE myportal"); PQclear(res); - /* end the transaction */ + /* 结束事务 */ res = PQexec(conn, "END"); PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -7254,15 +6832,15 @@ main(int argc, char **argv) * * * testlibpq2.c - * Test of the asynchronous notification interface + * 测试异步通知接口 * - * Start this program, then from psql in another window do + * 启动此程序,然后在另一个窗口中通过 psql 执行 * NOTIFY TBL2; - * Repeat four times to get this program to exit. + * 重复四次后,此程序便会退出。 * - * Or, if you want to get fancy, try this: - * populate a database with the following commands - * (provided in src/test/examples/testlibpq2.sql): + * 或者,可以尝试更复杂的示例: + * 使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq2.sql 中): * * CREATE SCHEMA TESTLIBPQ2; * SET search_path = TESTLIBPQ2; @@ -7271,7 +6849,7 @@ main(int argc, char **argv) * CREATE RULE r1 AS ON INSERT TO TBL1 DO * (INSERT INTO TBL2 VALUES (new.i); NOTIFY TBL2); * - * Start this program, then from psql do this four times: + * 启动此程序,然后通过 psql 将以下命令执行四次: * * INSERT INTO TESTLIBPQ2.TBL1 VALUES (10); */ @@ -7308,26 +6886,25 @@ main(int argc, char **argv) int nnotifies; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -7338,13 +6915,12 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Issue LISTEN command to enable notifications from the rule's NOTIFY. + * 发出 LISTEN 命令,以接收规则中的 NOTIFY 发出的通知。 */ res = PQexec(conn, "LISTEN TBL2"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -7355,14 +6931,13 @@ main(int argc, char **argv) } PQclear(res); - /* Quit after four notifies are received. */ + /* 收到四次通知后退出。 */ nnotifies = 0; while (nnotifies < 4) { /* - * Sleep until something happens on the connection. We use select(2) - * to wait for input, but you could also use poll() or similar - * facilities. + * 休眠,直到连接上有事件发生。这里使用 select(2) 等待输入, + * 也可以使用 poll() 或类似机制。 */ int sock; fd_set input_mask; @@ -7370,7 +6945,7 @@ main(int argc, char **argv) sock = PQsocket(conn); if (sock < 0) - break; /* shouldn't happen */ + break; /* 不应发生 */ FD_ZERO(&input_mask); FD_SET(sock, &input_mask); @@ -7381,7 +6956,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Now check for input */ + /* 现在检查是否有输入 */ PQconsumeInput(conn); while ((notify = PQnotifies(conn)) != NULL) { @@ -7396,7 +6971,7 @@ main(int argc, char **argv) fprintf(stderr, "Done.\n"); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -7416,10 +6991,10 @@ main(int argc, char **argv) * * * testlibpq3.c - * Test out-of-line parameters and binary I/O. + * 测试在 SQL 命令文本之外独立传递的参数和二进制 I/O。 * - * Before running this, populate a database with the following commands - * (provided in src/test/examples/testlibpq3.sql): + * 运行前,使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq3.sql 中): * * CREATE SCHEMA testlibpq3; * SET search_path = testlibpq3; @@ -7428,7 +7003,7 @@ main(int argc, char **argv) * INSERT INTO test1 values (1, 'joe''s place', '\000\001\002\003\004'); * INSERT INTO test1 values (2, 'ho there', '\004\003\002\001\000'); * - * The expected output is: + * 预期输出为: * * tuple 0: got * i = (4 bytes) 1 @@ -7452,7 +7027,7 @@ main(int argc, char **argv) #include #include "libpq-fe.h" -/* for ntohl/htonl */ +/* 用于 ntohl/htonl */ #include #include @@ -7464,9 +7039,8 @@ exit_nicely(PGconn *conn) } /* - * This function prints a query result that is a binary-format fetch from - * a table defined as in the comment above. We split it out because the - * main() function uses it twice. + * 此函数打印从上面注释所定义的表中以二进制格式获取的查询结果。 + * 由于 main() 会使用它两次,因此将它单独提取成一个函数。 */ static void show_binary_results(PGresult *res) @@ -7477,7 +7051,7 @@ show_binary_results(PGresult *res) t_fnum, b_fnum; - /* Use PQfnumber to avoid assumptions about field order in result */ + /* 使用 PQfnumber,以避免对结果中的字段顺序作出假设 */ i_fnum = PQfnumber(res, "i"); t_fnum = PQfnumber(res, "t"); b_fnum = PQfnumber(res, "b"); @@ -7490,24 +7064,22 @@ show_binary_results(PGresult *res) int blen; int ival; - /* Get the field values (we ignore possibility they are null!) */ + /* 获取字段值(这里忽略它们可能为 null 的情况!) */ iptr = PQgetvalue(res, i, i_fnum); tptr = PQgetvalue(res, i, t_fnum); bptr = PQgetvalue(res, i, b_fnum); /* - * The binary representation of INT4 is in network byte order, which - * we'd better coerce to the local byte order. + * INT4 的二进制表示采用网络字节序,最好将其转换为本机字节序。 */ ival = ntohl(*((uint32_t *) iptr)); /* - * The binary representation of TEXT is, well, text, and since libpq - * was nice enough to append a zero byte to it, it'll work just fine - * as a C string. + * TEXT 的二进制表示就是文本,而 libpq 会在其后追加一个零字节, + * 因此可以直接将其用作 C 字符串。 * - * The binary representation of BYTEA is a bunch of bytes, which could - * include embedded nulls so we have to pay attention to field length. + * BYTEA 的二进制表示是一组字节,其中可能嵌有零字节, + * 因此必须注意字段长度。 */ blen = PQgetlength(res, i, b_fnum); @@ -7535,26 +7107,25 @@ main(int argc, char **argv) uint32_t binaryIntVal; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SET search_path = testlibpq3"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -7565,27 +7136,25 @@ main(int argc, char **argv) PQclear(res); /* - * The point of this program is to illustrate use of PQexecParams() with - * out-of-line parameters, as well as binary transmission of data. + * 此程序旨在演示如何使用 PQexecParams() 在 SQL 命令文本之外独立传递参数, + * 以及如何以二进制方式传输数据。 * - * This first example transmits the parameters as text, but receives the - * results in binary format. By using out-of-line parameters we can avoid - * a lot of tedious mucking about with quoting and escaping, even though - * the data is text. Notice how we don't have to do anything special with - * the quote mark in the parameter value. + * 第一个示例以文本形式传输参数,但以二进制格式接收结果。 + * 通过在 SQL 命令文本之外独立传递参数,即使数据是文本,也可以避免 + * 许多繁琐的引号和转义处理。注意,参数值中的引号无需任何特殊处理。 */ - /* Here is our out-of-line parameter value */ + /* 这是在 SQL 命令文本之外独立传递的参数值 */ paramValues[0] = "joe's place"; res = PQexecParams(conn, "SELECT * FROM test1 WHERE t = $1", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, - NULL, /* don't need param lengths since text */ - NULL, /* default to all text params */ - 1); /* ask for binary results */ + NULL, /* 文本参数无需指定长度 */ + NULL, /* 默认所有参数均为文本 */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -7599,31 +7168,29 @@ main(int argc, char **argv) PQclear(res); /* - * In this second example we transmit an integer parameter in binary form, - * and again retrieve the results in binary form. + * 第二个示例以二进制形式传输一个整数参数,并同样以二进制形式获取结果。 * - * Although we tell PQexecParams we are letting the backend deduce - * parameter type, we really force the decision by casting the parameter - * symbol in the query text. This is a good safety measure when sending - * binary parameters. + * 虽然我们告诉 PQexecParams 让后端推断参数类型,但实际上, + * 查询文本中的参数符号经过强制类型转换,因此其类型已经确定。 + * 发送二进制参数时,这是一项良好的安全措施。 */ - /* Convert integer value "2" to network byte order */ + /* 将整数值 "2" 转换为网络字节序 */ binaryIntVal = htonl((uint32_t) 2); - /* Set up parameter arrays for PQexecParams */ + /* 为 PQexecParams 设置参数数组 */ paramValues[0] = (char *) &binaryIntVal; paramLengths[0] = sizeof(binaryIntVal); - paramFormats[0] = 1; /* binary */ + paramFormats[0] = 1; /* 二进制 */ res = PQexecParams(conn, "SELECT * FROM test1 WHERE i = $1::int4", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, paramLengths, paramFormats, - 1); /* ask for binary results */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -7636,7 +7203,7 @@ main(int argc, char **argv) PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; diff --git a/zh/14/lobj.sgml b/zh/14/lobj.sgml index c86a2a7b..7c59fc54 100644 --- a/zh/14/lobj.sgml +++ b/zh/14/lobj.sgml @@ -3,8 +3,8 @@ 大对象 - large object - BLOBlarge object + 大对象 + BLOB大对象 PostgreSQL提供一种大对象机制,允许以流式方式访问存储在专用大对象结构中的用户数据。在处理大到无法方便地整体操作的数据值时,这种流式访问非常有用。 @@ -19,7 +19,7 @@ TOAST - versus large objects + 与大对象对比 @@ -192,11 +192,11 @@ inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE); int lo_write(PGconn *conn, int fd, const char *buf, size_t len); - 将buf中的len字节(其大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 + 将buf中的len字节(缓冲区大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -213,7 +213,7 @@ int lo_read(PGconn *conn, int fd, char *buf, size_t len); - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -279,7 +279,7 @@ pg_int64 lo_tell64(PGconn *conn, int fd); int lo_truncate(PGconn *conn, int fd, size_t len); - 该函数把大对象描述符fd截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用空字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 + 该函数把大对象描述符fd对应的大对象截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用零字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 @@ -428,16 +428,16 @@ CREATE TABLE image ( raster oid ); -SELECT lo_creat(-1); -- returns OID of new, empty large object +SELECT lo_creat(-1); -- 返回新建的空大对象的 OID -SELECT lo_create(43213); -- attempts to create large object with OID 43213 +SELECT lo_create(43213); -- 尝试创建 OID 为 43213 的大对象 -SELECT lo_unlink(173454); -- deletes large object with OID 173454 +SELECT lo_unlink(173454); -- 删除 OID 为 173454 的大对象 INSERT INTO image (name, raster) VALUES ('beautiful image', lo_import('/etc/motd')); -INSERT INTO image (name, raster) -- same as above, but specify OID to use +INSERT INTO image (name, raster) -- 与上例相同,但指定要使用的 OID VALUES ('beautiful image', lo_import('/etc/motd', 68583)); SELECT lo_export(image.raster, '/tmp/motd') FROM image @@ -446,7 +446,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image - 服务器端的lo_importlo_export函数与其客户端对应函数的行为差异很大。这两个函数在服务器的文件系统中读写文件,使用数据库所有者的权限。因此,默认情况下它们的使用仅限于超级用户。相比之下,客户端导入和导出函数在客户端的文件系统中读写文件,使用客户端程序的权限。客户端函数不需要任何数据库权限,除了读取或写入相关大对象所需的权限。 + 服务器端的lo_importlo_export函数与其客户端对应函数的行为差异很大。这两个函数在服务器的文件系统中读写文件,使用运行数据库服务器的操作系统用户的权限。因此,默认情况下它们的使用仅限于超级用户。相比之下,客户端导入和导出函数在客户端的文件系统中读写文件,使用客户端程序的权限。客户端函数不需要任何数据库权限,除了读取或写入相关大对象所需的权限。 @@ -465,7 +465,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image 示例程序 - 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行版的src/test/examples/testlo.c中找到。 + 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行包的src/test/examples/testlo.c中找到。 @@ -474,13 +474,13 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /*----------------------------------------------------------------- * * testlo.c - * test using large objects with libpq + * 测试使用 libpq 操作大对象 * * Portions Copyright (c) 1996-2021, PostgreSQL Global Development Group * Portions Copyright (c) 1994, Regents of the University of California * * - * IDENTIFICATION + * 标识 * src/test/examples/testlo.c * *----------------------------------------------------------------- @@ -500,7 +500,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /* * importFile - - * import file "in_filename" into database as large object "lobjOid" + * 将文件 "in_filename" 作为大对象 "lobjOid" 导入数据库 * */ static Oid @@ -514,16 +514,16 @@ importFile(PGconn *conn, char *filename) int fd; /* - * open the file to be read in + * 打开要读取的文件 */ fd = open(filename, O_RDONLY, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"\n", filename); } /* - * create the large object + * 创建大对象 */ lobjId = lo_creat(conn, INV_READ | INV_WRITE); if (lobjId == 0) @@ -532,7 +532,7 @@ importFile(PGconn *conn, char *filename) lobj_fd = lo_open(conn, lobjId, INV_WRITE); /* - * read in from the Unix file and write to the inversion file + * 从 Unix 文件读取数据并写入大对象 */ while ((nbytes = read(fd, buf, BUFSIZE)) > 0) { @@ -570,7 +570,7 @@ pickout(PGconn *conn, Oid lobjId, int start, int len) fprintf(stderr, ">>> %s", buf); nread += nbytes; if (nbytes <= 0) - break; /* no more data? */ + break; /* 没有更多数据? */ } free(buf); fprintf(stderr, "\n"); @@ -616,7 +616,7 @@ overwrite(PGconn *conn, Oid lobjId, int start, int len) /* * exportFile - - * export large object "lobjOid" to file "out_filename" + * 将大对象 "lobjOid" 导出到文件 "out_filename" * */ static void @@ -629,24 +629,24 @@ exportFile(PGconn *conn, Oid lobjId, char *filename) int fd; /* - * open the large object + * 打开大对象 */ lobj_fd = lo_open(conn, lobjId, INV_READ); if (lobj_fd < 0) fprintf(stderr, "cannot open large object %u", lobjId); /* - * open the file to be written to + * 打开要写入的文件 */ fd = open(filename, O_CREAT | O_WRONLY | O_TRUNC, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"", filename); } /* - * read in from the inversion file and write to the Unix file + * 从大对象读取数据并写入 Unix 文件 */ while ((nbytes = lo_read(conn, lobj_fd, buf, BUFSIZE)) > 0) { @@ -691,18 +691,18 @@ main(int argc, char **argv) out_filename = argv[3]; /* - * set up the connection + * 建立连接 */ conn = PQsetdb(NULL, NULL, NULL, NULL, database); - /* check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) diff --git a/zh/14/monitoring.sgml b/zh/14/monitoring.sgml index a70d558e..52e88989 100644 --- a/zh/14/monitoring.sgml +++ b/zh/14/monitoring.sgml @@ -3479,7 +3479,8 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i checksum_failures bigint - 在此数据库(或共享对象)中检测到的数据页校验码失败数,如果没有启用数据校验码则为NULL。 + 在此数据库(或共享对象)中检测到的数据页校验和失败次数,如果未启用 + 数据校验和则为 NULL。 @@ -3488,7 +3489,8 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i checksum_last_failure timestamp with time zone - 在此数据库(或共享对象)中检测到最后一个数据页校验码失败的时间,如果没有启用数据校验码则为NULL。 + 在此数据库(或共享对象)中最后一次检测到数据页校验和失败的时间, + 如果未启用数据校验和则为 NULL。 diff --git a/zh/14/pgtrgm.sgml b/zh/14/pgtrgm.sgml index f2d84768..159dbe44 100644 --- a/zh/14/pgtrgm.sgml +++ b/zh/14/pgtrgm.sgml @@ -513,11 +513,11 @@ SELECT * FROM test_trgm WHERE t ~ '(foo|bar)'; - 文本搜索集成 + 文本检索集成 与全文索引结合使用时,三字符组匹配是非常有用的工具。 - 尤其是,它有助于识别那些因拼写错误而无法被全文搜索机制直接匹配的输入词。 + 尤其是,它有助于识别那些因拼写错误而无法被全文检索机制直接匹配的输入词。 diff --git a/zh/14/protocol.sgml b/zh/14/protocol.sgml index 5049a748..031b8c5b 100644 --- a/zh/14/protocol.sgml +++ b/zh/14/protocol.sgml @@ -34,7 +34,7 @@ - 会话通常由前端选择终止,但在某些情况下也可能由后端强制终止。无论哪种情况,后端在关闭连接前都会回滚所有打开的(未完成的)事务。 + 会话通常由前端选择终止,但在某些情况下也可能由后端强制终止。无论哪种情况,后端关闭连接时,都会在退出前回滚所有打开的(未完成的)事务。 @@ -73,9 +73,7 @@ 整个执行周期包括一个解析步骤,它从文本查询字符串创建预备语句; 一个绑定步骤,它根据预备语句和所需参数值创建 portal; - 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询 - (SELECTSHOW等),可以要求执行步骤只取回 - 有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 + 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询(SELECTSHOW等),可以要求执行步骤只取回有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 @@ -92,8 +90,8 @@ - 文本形式的数值是特定数据类型的输入/输出转换函数生成或接受的任何字符串。在传输形式上,字符串没有末尾空字符;如果前端要想把收到的值当作C字符串处理,那么必须自己加上一个(顺便说一下,文本格式不允许嵌入空字符)。 - + 值的文本表示是相应数据类型的输入/输出转换函数生成和接受的字符串。在传输形式中,值的末尾没有空字符;前端若要将收到的值作为 C 字符串处理,必须自行添加一个。(文本格式也不允许内嵌空字符。) + 整数的二进制表示采用网络字节序(最高有效字节在前)。至于其他数据类型,请查阅文档或源代码了解其二进制表示形式。要注意,复杂数据类型的二进制表示可能会在不同服务器版本之间发生变化;文本格式通常是可移植性更好的选择。 @@ -115,7 +113,7 @@ 启动 - 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,判断该连接在初步上是否可接受,以及是否需要额外的认证。 + 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,初步判断是否接受该连接,以及需要何种额外认证(如果需要)。 @@ -362,7 +360,7 @@ 表示即将返回行作为对SELECTFETCH等查询的响应。 - 此消息的内容描述了行的列布局。这将跟随每个返回给前端的行的DataRow消息。 + 此消息的内容描述了行的列布局。该消息之后,每个返回给前端的行都对应一条 DataRow 消息。 @@ -418,9 +416,7 @@
- - 对 SELECT 查询(或其他返回行集的查询,如 EXPLAINSHOW)的响应,通常包含 RowDescription、零条或多条 DataRow 消息,以及最后的 CommandComplete。向前端 COPY 或从前端 COPY 会调用中描述的特殊协议。所有其他类型的查询通常只产生一条 CommandComplete 消息。 - + SELECT 查询(或其他返回行集的查询,如 EXPLAINSHOW)的响应通常包含 RowDescription、零条或多条 DataRow 消息,以及最后的 CommandComplete。在前端与服务器之间执行 COPY 输入或输出时,会使用 所述的特殊协议。所有其他类型的查询通常只产生一条 CommandComplete 消息。 由于查询字符串可能包含若干条查询(以分号分隔),因此在后端完成整个查询字符串的处理之前,可能会出现多个这样的响应序列。只有在整个字符串处理完毕且后端已准备好接受新的查询字符串时,才会发出 ReadyForQuery 消息。 @@ -443,15 +439,15 @@ - 我们建议的方法是把前端代码写成状态机的风格,它可以在任何时刻接受任何有意义的消息类型,而不是假设消息的序列总是准确。 - + 建议以状态机的方式编写前端,使其能够在任何合理的时机接收相应类型的消息,而不把消息确切顺序的假设写死在代码中。 + 一个简单查询中的多条语句 - 当一个简单查询消息中包含多于一条SQL语句(被分号分隔)时,那些语句会被当做一个事务中执行,除非其中包括显式事务控制命令来强制不同的行为。例如,如果消息包括 + 当一个简单查询消息中包含多于一条SQL语句(被分号分隔)时,这些语句会作为单个事务执行,除非其中包括显式事务控制命令来强制不同的行为。例如,如果消息包括 INSERT INTO mytable VALUES(1); SELECT 1/0; @@ -473,15 +469,15 @@ SELECT 1/0; - 这种行为通过在一个隐式事务块中的一个多语句Query消息中运行那些语句来实现,除非它们运行在某个显式事务块中。隐式事务块与常规事务块之间的区别在于隐式块会在Query消息结束时自动被关闭,或者是在没有错误的情况下由一个隐式提交关闭,或者是在有错误时由一个隐式的回滚关闭。这类似于一个语句自己执行(当不在事务块中时)时发生的隐式提交或回滚。 - + 这种行为的实现方式是:除非已有显式事务块可供这些语句执行,否则就在一个隐式事务块中执行多语句 Query 消息中的语句。隐式事务块与常规事务块的主要区别在于,隐式块会在 Query 消息结束时自动关闭:没有错误时隐式提交,发生错误时隐式回滚。这类似于单独执行一条语句(不在事务块中)时发生的隐式提交或回滚。 + - 如果会话已经在一个事务块中,作为前面某个消息中BEGIN的结果,那么Query消息会简单地继续那个事务块,不管该消息包含一个语句还是多个语句。不过,如果该Query消息包含一个关闭现有事务块的COMMIT或者ROLLBACK,那么任何接下来的语句都会在一个隐式事务块中被执行。反过来,如果在多语句Query消息中出现一个BEGIN,那么它会开始一个常规事务块,这个常规事务块将只能被一个显式的COMMIT或者ROLLBACK终止,不管这两种命令是出现在这个Query消息还是后面的一个Query消息中。如果BEGIN跟在一些作为隐式事务块执行的语句后面,那些语句不会被立刻提交。实际上,它们会被包括到新的常规事务块中。 + 如果会话因前面某条消息中的BEGIN而已经处于事务块中,那么 Query 消息会继续该事务块,不管该消息包含一个语句还是多个语句。不过,如果该Query消息包含一个关闭现有事务块的COMMIT或者ROLLBACK,那么任何接下来的语句都会在一个隐式事务块中被执行。反过来,如果在多语句Query消息中出现一个BEGIN,那么它会开始一个常规事务块,这个常规事务块将只能被一个显式的COMMIT或者ROLLBACK终止,不管这两种命令是出现在这个Query消息还是后面的一个Query消息中。如果BEGIN跟在一些作为隐式事务块执行的语句后面,那些语句不会被立刻提交。实际上,它们会被包括到新的常规事务块中。 - 出现在一个隐式事务块中的COMMIT或者ROLLBACK会被正常执行并且关闭该隐式块。不过,由于没有先前的BEGIN配对的COMMIT或者ROLLBACK表示一种错误,所以将会发出一个警告。如果后面还有更多语句,将会为它们开始一个新的隐式事务块。 + 出现在一个隐式事务块中的COMMIT或者ROLLBACK会被正常执行并且关闭该隐式块。不过,由于没有先前的BEGIN配对的COMMIT或者ROLLBACK可能表示误操作,所以会发出警告。如果后面还有更多语句,将会为它们开始一个新的隐式事务块。 @@ -489,17 +485,17 @@ SELECT 1/0; - 记住,不管任何事务控制命令存不存在,Query消息的执行会在第一个错误时停止。因此,对于下面的在一个Query消息中的示例 + 请记住,无论消息中是否包含事务控制命令,Query 消息的执行都会在第一个错误处停止。例如,单条 Query 消息包含以下内容时: BEGIN; SELECT 1/0; ROLLBACK; - 会话中将留下一个失败的常规事务块,因为在出现除零错误后不会到达ROLLBACK。将需要另一个ROLLBACK把会话恢复到一种可用的状态。 - +会话会停留在失败的常规事务块内,因为发生除零错误后不会再执行ROLLBACK。需要另发一条ROLLBACK,才能将会话恢复到可用状态。 + - 另一种要注意的行为是,最初的词法和语法分析是在整个查询字符串被执行之前进行的。因此后面的语句中的简单错误(例如拼写错误的关键词)可能会阻止任何语句的执行。这通常对用户是不可见的,因为在当作一个隐式事务块执行时,这些语句不管怎样都会全部被回滚。不过,在尝试于一个多语句Query中执行多个事务时,这种现象可能是可见的。例如,如果一个拼写错误把我们之前的示例变成 + 另一种要注意的行为是,在执行任何语句之前,会先对整个查询字符串进行词法和语法分析。因此后面的语句中的简单错误(例如拼写错误的关键词)可能会阻止任何语句的执行。这通常对用户是不可见的,因为在当作一个隐式事务块执行时,这些语句不管怎样都会全部被回滚。不过,在尝试于一个多语句Query中执行多个事务时,这种现象可能是可见的。例如,如果一个拼写错误把我们之前的示例变成 BEGIN; INSERT INTO mytable VALUES(1); @@ -566,11 +562,11 @@ SELCT 1/0; - 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是执行不会导致后端发送 ReadyForQuery 或 RowDescription。 + 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是 Execute 不会导致后端发送 ReadyForQuery 或 RowDescription。 - 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息之一结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 + 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息中的恰好一条结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 @@ -585,7 +581,7 @@ SELCT 1/0; - 除了这些基本的、必须的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 + 除了这些基本的、必需的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 @@ -621,38 +617,32 @@ SELCT 1/0; - 流水线处理 + 管道化 - 流水线处理 + 管道化 协议规范 - 使用扩展查询协议允许流水线处理,这意味着发送一系列查询而无需等待先前的查询完成。 - 这减少了完成一系列操作所需的网络往返次数。然而,用户必须仔细考虑所需的行为,如果其中一步失败, - 因为后续查询已经在传输到服务器的过程中。 - + 扩展查询协议允许管道化,即连续发送一系列查询,而不等待先前查询完成。这减少了完成一组操作所需的网络往返次数。不过,用户必须仔细考虑其中某个步骤失败时所需的行为,因为后续查询已经在发往服务器的途中。 + - 处理这个问题的一种方法是将整个查询系列作为一个事务处理,即将其包装在BEGIN... - COMMIT中。然而,如果希望其中一些命令独立于其他命令提交,这并没有帮助。 - + 处理这个问题的一种方式是让整组查询成为单个事务,即用BEGIN ... COMMIT包围它们。不过,如果希望其中某些命令独立于其他命令提交,这种方式就无法满足要求。 + - 扩展查询协议提供了另一种管理这个问题的方式,即在依赖的步骤之间省略发送同步消息。 - 由于在错误后,后端会跳过命令消息直到找到同步消息,这允许在管道中的后续命令在前面的命令失败时自动跳过,而无需客户端明确地使用BEGINCOMMIT来管理。 - 管道中可以通过同步消息分隔独立可提交的段。 - + 扩展查询协议提供了另一种处理方式,即省略相互依赖的步骤之间的 Sync 消息。发生错误后,后端会跳过命令消息,直到遇到 Sync,因此当前面的命令失败时,管道中的后续命令便会自动跳过,而不必由客户端用BEGINCOMMIT显式管理。管道中可独立提交的各段可以用 Sync 消息分隔。 + - 如果客户端没有发出显式 BEGIN,则会启动一个隐式事务块。每个 Sync 通常会在前序步骤成功时导致隐式 COMMIT,失败时导致隐式 ROLLBACK。服务器只有在第一个命令结束且尚未收到 Sync 时,才能识别这种隐式事务块。有一些 DDL 命令(例如 CREATE DATABASE)不能在事务块内执行;若这类命令在管道中执行,除非它是某个 Sync 之后的第一条命令,否则会失败。此外,它成功后会强制立即提交以保持数据库一致性。因此,紧随这些命令之后的 Sync 除了返回 ReadyForQuery 外不会产生额外效果。 - + 如果客户端没有发出显式的BEGIN,那么每个 Sync 通常会在前序步骤成功时引发隐式的COMMIT,失败时引发隐式的ROLLBACK。不过,少数 DDL 命令(例如CREATE DATABASE)不能在事务块中执行。如果这类命令在管道中执行,除非它是管道中的第一条命令,否则会失败。此外,它成功后会强制立即提交,以保持数据库一致性。因此,紧随这类命令之后的 Sync 除了返回 ReadyForQuery 外,不产生其他效果。 + - 当使用这种方法时,必须通过计算ReadyForQuery消息的数量并等待达到发送的Syncs数量来确定管道的完成。 - 计算命令完成响应是不可靠的,因为其中一些命令可能会被跳过,因此不会产生完成消息。 - + 使用这种方式时,必须统计 ReadyForQuery 消息的数量,并等待该数量达到已发送的 Sync 消息数量,才能确定管道已完成。统计命令完成响应并不可靠,因为某些命令可能被跳过,因而不会产生完成消息。 + @@ -660,8 +650,8 @@ SELCT 1/0; 函数调用 - 函数调用子协议允许客户端请求一个对存在于数据库pg_proc系统表中的任意函数的直接调用。客户端必须在该函数上有执行的权限。 - + 函数调用子协议允许客户端请求直接调用数据库pg_proc系统目录中的任意函数。客户端必须具有该函数的执行权限。 + @@ -671,8 +661,8 @@ SELCT 1/0; - 一个函数调用周期是由前端向后端发送一条FunctionCall消息初始化的。然后后端根据函数调用的结果发送一条或者更多响应消息,并且最后是一条ReadyForQuery响应消息。ReadyForQuery通知前端它可以安全地发送一个新的查询或者函数调用了。 - + 函数调用周期由前端向后端发送一条 FunctionCall 消息来启动。后端随后根据函数调用的结果发送一条或多条响应消息,最后发送一条 ReadyForQuery 响应消息。ReadyForQuery 告知前端,可以安全地发送新的查询或函数调用。 + 来自后端的可能的响应消息是: @@ -691,7 +681,7 @@ SELCT 1/0; FunctionCallResponse - 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者集合类型的结果)。 + 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者结果集合)。 @@ -726,7 +716,7 @@ SELCT 1/0; - 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(表示成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 + 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(允许成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 @@ -734,11 +724,11 @@ SELCT 1/0; - 在拷贝入模式下,后端将忽略所收到的Flush和Sync消息。收到任何其他非拷贝消息类型都会造成一个错误,它将导致上面所描述的拷贝入状态中断(Flush和Sync的例外是为了方便客户端库,它们总是在一个Execute消息之后发送Flush和Sync,而不检查被执行的命令是否为一个COPY FROM STDIN)。 - + 后端会忽略在拷贝入模式期间收到的 Flush 和 Sync 消息。收到任何其他非拷贝类型的消息都会构成错误,并按上述方式中止拷贝入状态。(Flush 和 Sync 的例外是为了方便那些总是在 Execute 消息之后发送 Flush 或 Sync、而不检查待执行命令是否为COPY FROM STDIN的客户端库。) + - 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句的时候初始化的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能退出传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 + 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句时启动的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能中止传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 @@ -746,16 +736,16 @@ SELCT 1/0; - 在CopyData消息中间可能会散布有NoticeResponse和ParameterStatus消息。前端必须处理这些情况,并且应该也为异步消息类型(参见)准备好。否则任何除CopyData或CopyDone之外的消息类型都会被认为是要中止拷贝出模式。 - + NoticeResponse 和 ParameterStatus 消息可能穿插在 CopyData 消息之间;前端必须处理这些情况,并应准备好处理其他异步消息类型(参见)。除此之外,可以将任何除 CopyData 或 CopyDone 以外的消息类型视为拷贝出模式的终止标志。 + - 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许数据以高速批量方式在客户端与服务器之间双向传输。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见。 + 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许高速批量地向服务器发送数据以及从服务器接收数据。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见 - CopyInResponse、CopyOutResponse和CopyBothResponse消息包括域和格式代码,域告诉前端每行的列数,而格式代码则用于具体每个列(就目前的实现而言,一个给定COPY操作中的所有列都将使用同样的格式,但是消息设计并不做这个假设)。 - + CopyInResponse、CopyOutResponse 和 CopyBothResponse 消息包含一些字段,用于告知前端每行的列数以及每列所使用的格式代码。(在当前实现中,同一次COPY操作的所有列都使用相同格式,但消息设计并不作此假设。) + @@ -783,8 +773,8 @@ SELCT 1/0; - 如果前端发出一个LISTEN命令, 那么无论何时在为同一个通道名NOTIFY时,后端将发送一个NotificationResponse消息(不要和NoticeResponse搞混!)。 - + 如果前端发出LISTEN命令,那么每当针对同一通道名执行NOTIFY命令时,后端都会发送一条 NotificationResponse 消息(不要与 NoticeResponse 混淆)。 + @@ -803,11 +793,11 @@ SELCT 1/0; - 要发出一条取消请求,前端打开一个与服务器的新连接并且发送一条CancelRequest消息, 而不是通常在新连接中经常发送的StartupMessage消息。服务器将处理这个请求然后关闭连接。 出于安全原因,对取消请求消息不做直接的响应。 - + 要发出取消请求,前端会新建到服务器的连接,并发送 CancelRequest 消息,而不是新连接通常发送的 StartupMessage 消息。服务器处理该请求后便会关闭连接。出于安全原因,服务器不会直接回复取消请求消息。 + - 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的关键数据(PID和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则退出当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 + 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的密钥数据(PID 和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则中止当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 @@ -815,7 +805,7 @@ SELCT 1/0; - 这么做是对安全性和有效性通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 + 这么做是对安全性和效率通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 @@ -836,11 +826,11 @@ SELCT 1/0; - 其他终止场景来自各种故障,例如任一端发生内核转储、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 + 其他终止场景来自各种故障,例如任一端发生 core dump、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 - 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果很可能在得知断开之前被提交。 + 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果可能在发现连接断开之前被提交。 @@ -854,32 +844,28 @@ SELCT 1/0; 要发起一条使用SSL加密的连接,前端首先发送 SSLRequest 消息,而不是 StartupMessage。随后服务器会响应一个包含SN的单字节,分别表示它愿意或不愿意执行SSL加密。如果前端对该响应不满意,此时可以关闭连接。若要在收到S后继续,就先与服务器完成SSL启动握手(这里不做描述,它属于SSL规范的一部分)。如果成功,再继续发送通常的 StartupMessage。在这种情况下,StartupMessage 以及后续所有数据都会被SSL加密。若要在收到N后继续,则发送通常的 StartupMessage,并在不使用加密的情况下继续。 - (另外,可以在 N 响应之后发出 GSSENCRequest 消息,尝试使用 GSSAPI 加密代替 SSL。) + (另外,可以在 N 响应之后发出 GSSENCRequest 消息,尝试使用 GSSAPI 加密代替 SSL。) - 前端也应准备处理服务器对 SSLRequest 返回的 ErrorMessage。前端不应将该错误直接展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 SSL 的情况下继续。 + 前端也应准备处理服务器对 SSLRequest 返回的 ErrorMessage。前端不应将该错误展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 SSL 的情况下继续。 - 当可以执行 SSL 加密时,服务器预计仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给他们的 SSL 库,要么在发现他们已经读取到额外的字节时将其视为协议违规。 + 当可以执行 SSL 加密时,服务器应仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给所用的 SSL 库,要么在发现已经读取到额外的字节时将其视为协议违规。 - - 同样,服务器也期望客户端在收到服务器对 SSLRequest 的单字节响应之后,再开始SSL协商。如果客户端不等服务器响应到达就立即开始SSL协商,可以减少一次网络往返时延;但代价是无法处理服务器对SSL请求返回否定响应的情况。在这种情况下,服务器通常会直接断开连接,而不会继续回退到 GSSAPI、未加密连接或协议错误流程。 - - - 初始 SSLRequest 也可以用于那些正在建立、目的是发送 CancelRequest 消息的连接。 - - 还支持第二种发起SSL加密的方式:客户端可以在不发送任何 SSLRequest 包的情况下,直接开始SSL协商。SSL连接建立后,服务器会在加密通道上继续等待普通的启动请求包并继续协商。在这种情况下,任何其他的加密请求都会被拒绝。这种方法不适合通用工具,因为它既不能协商出最佳的连接加密方式,也不能处理未加密连接;但在客户端和服务器都由同一方控制的环境中,它很有用,因为它可以减少一次往返时延,并允许使用依赖标准SSL连接的网络工具。使用这种风格的SSL连接时,客户端必须使用由 RFC 7301 定义的 ALPN 扩展,以防范协议混淆攻击。PostgreSQL 协议对应的 ALPN 标识是 postgresql,见 IANA TLS ALPN Protocol IDs 注册表。 - + 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 SSLRequest。 + + + - 虽然协议本身并不提供让服务器强制启用SSL加密的方法,但管理员可以把服务器配置为拒绝未加密会话,把它作为认证检查的一个副作用。 - + 虽然协议本身没有提供让服务器强制使用SSL加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + @@ -890,37 +876,27 @@ SELCT 1/0; 如果PostgreSQL构建时启用了GSSAPI支持,就可以使用GSSAPI对前端/后端通信进行加密。这为攻击者可能截获会话流量的环境提供了通信安全性。有关使用GSSAPI加密PostgreSQL会话的详细信息,请参阅。 - - 要启动一个GSSAPI加密连接,前端最初发送一个GSSENCRequest消息,而不是一个StartupMessage。 - 服务器随后会响应一个包含GN的单个字节,分别表示愿意或不愿意执行GSSAPI加密。 - 如果前端对响应不满意,可能会在此时关闭连接。 - 要在G之后继续,使用GSSAPI C绑定,如在RFC 2744 - 中讨论的,或等效的,通过在循环中调用gss_init_sec_context()来执行GSSAPI初始化, - 并将结果发送给服务器,从一个空输入开始,然后对每个来自服务器的结果进行处理,直到不再返回输出为止。 - 在将gss_init_sec_context()的结果发送给服务器时,在消息前加上以网络字节顺序表示的四字节整数的长度。 - 要在N之后继续,发送通常的StartupMessage,并在没有加密的情况下继续进行。 - (或者,可以在N响应后发出一个SSLRequest消息,尝试使用SSL加密代替GSSAPI。) - + 要建立 GSSAPI 加密连接,前端首先发送 GSSENCRequest 消息,而不是 StartupMessage。服务器随后以单个字节响应,内容为 GN,分别表示愿意或不愿意使用 GSSAPI 加密。如果前端对响应不满意,可以在此时关闭连接。收到 G 后要继续,应使用 RFC 2744 中介绍的 GSSAPI C 绑定或等效接口,在循环中调用 gss_init_sec_context() 来执行 GSSAPI 初始化,并将结果发送给服务器:先使用空输入,再依次使用服务器返回的每个结果,直到该调用不再产生输出。将 gss_init_sec_context() 的结果发送给服务器时,应在前面加上消息长度,以网络字节序的四字节整数表示。收到 N 后要继续,则发送通常的 StartupMessage,以不加密的方式继续。(也允许在收到 N 响应后发送 SSLRequest 消息,尝试使用 SSL 加密代替 GSSAPI。) - 前端也应准备处理服务器对 GSSENCRequest 返回的 ErrorMessage。前端不应将该错误直接展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 GSSAPI 加密的情况下继续。 + 前端也应准备处理服务器对 GSSENCRequest 返回的 ErrorMessage。前端不应将该错误展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 GSSAPI 加密的情况下继续。 - 当GSSAPI加密可用时,服务器预计只发送单个G字节,然后等待前端启动GSSAPI握手。此时如果还有其他可读字节,很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应编写代码,要么从套接字中恰好读取一个字节后再把套接字交给其 GSSAPI 库,要么在发现自己已经读到额外字节时将其视为协议违规。 + 当GSSAPI加密可用时,服务器应只发送单个G字节,然后等待前端启动GSSAPI握手。此时如果还有其他可读字节,很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应编写代码,要么从套接字中恰好读取一个字节后再把套接字交给其 GSSAPI 库,要么在发现自己已经读到额外字节时将其视为协议违规。 - 初始 GSSENCRequest 也可用于那些正在建立、目的是发送 CancelRequest 消息的连接。 - + 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 GSSENCRequest。 + 一旦成功建立GSSAPI加密连接,就应使用gss_wrap()加密通常的 StartupMessage 以及后续所有数据,并在实际加密负载前附上gss_wrap()结果长度,该长度以网络字节序的四字节整数表示。请注意,服务器只接受来自客户端、长度小于 16kB 的加密数据包。客户端应使用gss_wrap_size_limit()确定符合该限制的未加密消息大小,较大的消息则应拆分为多次gss_wrap()调用。典型分段是 8kB 的未加密数据,对应得到略大于 8kB 但明显小于 16kB 的加密数据包。通常可以认为,服务器不会向客户端发送大于 16kB 的加密数据包。 - 虽然协议本身并不为服务器提供强制启用GSSAPI加密的方法,但管理员可以把服务器配置为拒绝未加密会话,把它作为认证检查的一个副作用。 - + 虽然协议本身没有提供让服务器强制使用GSSAPI加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + @@ -928,9 +904,7 @@ SELCT 1/0; SASL认证 - - SASL是面向连接协议中的认证框架。目前,PostgreSQL实现了两种 SASL 认证机制:SCRAM-SHA-256 和 SCRAM-SHA-256-PLUS。将来可能增加更多机制。下面的步骤说明 SASL 认证的一般流程,下一小节则详细介绍 SCRAM-SHA-256 和 SCRAM-SHA-256-PLUS。 - + SASL 是面向连接协议中的认证框架。目前,PostgreSQL 实现了两种 SASL 认证机制:SCRAM-SHA-256 和 SCRAM-SHA-256-PLUS。将来可能增加更多机制。以下步骤说明 SASL 认证的一般流程,下一小节则详细介绍 SCRAM-SHA-256 和 SCRAM-SHA-256-PLUS。 @@ -946,25 +920,22 @@ SELCT 1/0; - 客户端从列表中选择一个支持的机制,并向服务器发送一个SASLInitialResponse消息。 - 该消息包括所选机制的名称,以及如果所选机制使用的话,还包括一个可选的初始客户端响应。 - + 客户端从列表中选择一种受支持的机制,并向服务器发送 SASLInitialResponse 消息。消息包含所选机制的名称;如果该机制使用初始客户端响应,消息还可以包含这一可选响应。 + - 一个或多个服务器挑战和客户端响应消息将随后而来。每个服务器挑战都是在一个 - AuthenticationSASLContinue 消息中发送的,随后是客户端在一个 SASLResponse - 消息中的响应。这些消息的具体内容是特定于机制的。 - + 随后会进行一轮或多轮服务器挑战和客户端响应。每次服务器挑战都通过 AuthenticationSASLContinue 消息发送,随后客户端通过 SASLResponse 消息响应。消息的具体内容取决于所用机制。 + - 最后,当认证交换成功完成时,服务器会发送可选的 AuthenticationSASLFinal 消息,随后立即发送 AuthenticationOk。AuthenticationSASLFinal 包含机制特定的附加数据;若该机制不需要完成时附加数据,则不会发送 AuthenticationSASLFinal。 - + 最后,认证交换成功完成时,服务器会发送 AuthenticationSASLFinal 消息,紧接着发送 AuthenticationOk 消息。AuthenticationSASLFinal 包含从服务器发给客户端的附加数据,其具体内容取决于所选认证机制。如果该认证机制不使用在完成时发送的附加数据,则不会发送 AuthenticationSASLFinal 消息。 + @@ -976,12 +947,7 @@ SELCT 1/0; SCRAM-SHA-256认证 - - SCRAM-SHA-256 及其带通道绑定的变体 - SCRAM-SHA-256-PLUS 是基于密码的认证机制。它们在 - RFC 7677 - 和RFC 5802中有详细描述。 - + 目前实现的 SASL 机制是 SCRAM-SHA-256 及其带通道绑定的变体 SCRAM-SHA-256-PLUSRFC 7677RFC 5802 对它们有详细描述。 当在PostgreSQL中使用SCRAM-SHA-256时,服务器将忽略客户端在client-first-message中发送的用户名。 @@ -990,31 +956,22 @@ SELCT 1/0; - SCRAM规范规定密码也必须是UTF-8编码,并且使用SASLprep算法处理。 - 然而,PostgreSQL不要求密码必须使用UTF-8编码。 - 当用户设置密码时,无论实际使用的编码是什么,都会像使用UTF-8一样使用SASLprep进行处理。 - 但是,如果密码不是合法的UTF-8字节序列,或者包含SASLprep算法禁止的UTF-8字节序列, - 则会使用原始密码而不进行SASLprep处理,而不是抛出错误。这样可以在密码为UTF-8时对其进行规范化, - 但仍允许使用非UTF-8密码,并且不需要系统知道密码使用的编码方式。 - + SCRAM 规范规定密码也必须采用 UTF-8 编码,并通过SASLprep算法处理。不过,PostgreSQL并不要求密码使用 UTF-8。设置用户密码时,无论实际采用何种编码,都会将其视作 UTF-8 并用 SASLprep 处理。但是,如果密码不是合法的 UTF-8 字节序列,或者包含 SASLprep 算法禁止的 UTF-8 字节序列,就会直接使用未经 SASLprep 处理的原始密码,而不抛出错误。这样既能对 UTF-8 密码进行规范化,又允许使用非 UTF-8 密码,而且不要求系统知道密码采用何种编码。 + - Channel binding在支持SSL的PostgreSQL构建中受支持。带有通道绑定的SCRAM的SASL机制名称是 + 通道绑定在支持SSL的PostgreSQL构建中受支持。带有通道绑定的SCRAM的SASL机制名称是 SCRAM-SHA-256-PLUS。PostgreSQL使用的通道绑定类型是 tls-server-end-point - 在没有通道绑定的SCRAM中,服务器选择一个随机数, - 传输给客户端,与用户提供的密码在传输的密码哈希中混合。虽然这可以 - 防止密码哈希在后续会话中被成功重新传输,但无法阻止真实服务器和客 - 户端之间的虚假服务器通过服务器的随机值并成功进行认证。 - + 在不带通道绑定的SCRAM中,服务器会选择一个随机数并发送给客户端,将它与用户提供的密码混合,形成所传输的密码 hash。虽然这样可以防止在后续会话中成功重放该密码 hash,但无法阻止位于真实服务器与客户端之间的伪造服务器转发服务器的随机值并成功通过认证。 + - SCRAM与通道绑定一起防止这种中间人攻击,通过将服务器证书的签名混合到传输的密码哈希中。 - 虽然伪造服务器可以重新传输真实服务器的证书,但它无法访问与该证书匹配的私钥,因此无法证明自己是所有者,导致SSL连接失败。 - + 带通道绑定的SCRAM会将服务器证书的签名混入所传输的密码 hash,从而防止此类中间人攻击。虽然伪造服务器可以转发真实服务器的证书,但它无法取得与证书匹配的私钥,因此无法证明自己是证书所有者,最终导致 SSL 连接失败。 + @@ -1086,16 +1043,15 @@ SELCT 1/0; - 为了测试复制命令,可以通过psql或任何其他使用连接字符串且包含replication选项的libpq工具建立复制连接, - 例如: + 为了测试复制命令,可以通过 psql 或其他使用 libpq 的工具建立复制连接,连接字符串中应包含 replication 选项,例如: psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 然而,更常用的是使用(用于物理复制)或(用于逻辑复制)。 - +不过,通常更有用的做法是使用 (用于物理复制)或 (用于逻辑复制)。 + - 复制命令在服务器日志中记录,当启用时。 + 启用 后,复制命令会记录到服务器日志中。 @@ -1105,7 +1061,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" IDENTIFY_SYSTEM - 识别系统 + IDENTIFY_SYSTEM @@ -1141,9 +1097,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" xlogpos (text) - - 当前 WAL 刷新位置。用于获得预写式日志中的一个已知位置,以便从该处开始流式传输。 - + 当前 WAL 刷盘位置。可用于获取预写式日志中一个已知的位置,以便从该处开始流式传输。 @@ -1195,10 +1149,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 请求服务器发送时间线历史文件以获取时间线tli。 - 服务器回复一行结果集,包含两个字段。虽然这些字段被标记为text, - 但它们实际上返回原始字节,没有编码转换: - + 请求服务器发送时间线 tli 的历史文件。服务器返回一个包含两个字段的单行结果集。虽然这些字段标记为 text,但实际返回的是原始字节,不进行编码转换: + @@ -1326,35 +1278,29 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" START_REPLICATION [ SLOT slot_name ] [ PHYSICAL ] XXX/XXX [ TIMELINE tli ] - 开始复制 + START_REPLICATION - 指示服务器开始流式传输WAL,从WAL位置XXX/XXX开始。 - 如果指定了TIMELINE选项,则流式传输将从时间线tli开始; - 否则,将选择服务器当前的时间线。如果请求的WAL部分已经被回收,服务器可能会回复错误。 - 成功时,服务器将用CopyBothResponse消息回复,然后开始向前端流式传输WAL。 - + 指示服务器从 WAL 位置 XXX/XXX 开始流式传输 WAL。如果指定了 TIMELINE 选项,则从时间线 tli 开始传输;否则选择服务器当前的时间线。服务器可以返回错误,例如请求的 WAL 部分已被回收时。成功时,服务器返回 CopyBothResponse 消息,然后开始向前端流式传输 WAL。 + - 如果通过slot_name提供了复制槽名称, - 那么在复制进行期间会更新该复制槽,以便服务器知道哪些 WAL 段, - 以及在启用了 hot_standby_feedback 时,哪些事务 - 仍然被备库所需要。 - + 如果通过 slot_name 提供了复制槽名称,该复制槽会随着复制的进行而更新,使服务器知道备库仍需要哪些 WAL 段,以及在启用 hot_standby_feedback 时仍需要哪些事务。 + - 如果客户端请求的 timeline 不是最新的,但属于服务器历史的一部分,服务器会从请求的起点开始流式传输该 timeline 上的全部 WAL,直到服务器切换到另一个 timeline 的位置为止。如果客户端请求的位置正好是旧 timeline 的末尾,服务器将完全跳过 COPY 模式。 - + 如果客户端请求的时间线不是最新时间线,但属于服务器的历史,服务器会从请求的起点开始,流式传输该时间线上的所有 WAL,直到服务器切换到另一条时间线的位置。如果客户端请求的流式传输起点恰好位于旧时间线的末尾,服务器会完全跳过 COPY 模式。 + 在非最新时间线上流式传输完全部 WAL 后,服务器会通过退出 COPY 模式来结束流式传输。当客户端也通过退出 COPY 模式来确认时,服务器会发送一个包含一行两列的结果集,指示该服务器历史中的下一条时间线。第一列是下一条时间线的 ID(类型为 int8),第二列是发生切换的 WAL 位置(类型为 text)。通常,切换位置就是所流式传输 WAL 的末尾,但也存在一些边界情况,服务器可能会先发送一些自己在提升前尚未重放的旧时间线 WAL。最后,服务器会发送两个 CommandComplete 消息(一个结束 CopyData,另一个结束 START_REPLICATION 本身),然后准备接受新的命令。 - WAL 数据会作为一系列 CopyData 消息发送;详见 。(这使其他信息可与之交错发送;特别是服务器在开始流式传输后若遇到失败,仍可发送 ErrorResponse。)从服务器到客户端的每个 CopyData 消息负载都属于以下格式之一: - + WAL 数据通过一系列 CopyData 消息发送,详见 。(这样可以混合发送其他信息;尤其是服务器在开始流式传输后遇到故障时,可以发送 ErrorResponse 消息。)服务器发给客户端的每条 CopyData 消息,其有效载荷都包含一条具有下列格式之一的消息: + @@ -1367,9 +1313,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('w') - - 将消息标识为WAL数据。 - + 将该消息标识为 WAL 数据。 @@ -1378,9 +1322,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 该消息中 WAL 数据的起始点。 - + 本消息中 WAL 数据的起始位置。 @@ -1389,9 +1331,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 服务器上当前的WAL结束位置。 - + 服务器上当前的 WAL 末尾位置。 @@ -1400,9 +1340,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 传输时服务器的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时服务器的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1411,15 +1349,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byten - - WAL数据流的一个部分。 - + WAL 数据流的一个片段。 - - 单个 WAL 记录绝不会拆分为两个 XLogData 消息。 - 当 WAL 记录跨越 WAL 页面边界,并因此已使用连续记录进行拆分时,它可以在页面边界处进行拆分。 - 换句话说,第一个主 WAL 记录及其连续记录可以在不同的 XLogData 消息中发送。 - + 单条 WAL 记录绝不会被拆分到两条 XLogData 消息中。当 WAL 记录跨越 WAL 页边界,因而已经通过续接记录拆分时,可以在页边界处分开发送。换句话说,最初的主 WAL 记录及其续接记录可以在不同的 XLogData 消息中发送。 @@ -1428,7 +1360,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 主库 keepalive 消息 (B) + 主库保活消息 (B) @@ -1436,9 +1368,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('k') - - 将该消息标识为发送方 keepalive。 - + 将该消息标识为发送端保活消息。 @@ -1447,9 +1377,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 服务器上当前的WAL结束位置。 - + 服务器上当前的 WAL 末尾位置。 @@ -1458,9 +1386,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 传输时服务器的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时服务器的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1469,9 +1395,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1 - - 1 表示客户端应尽快回复此消息,以避免超时断开连接。否则为0。 - + 1 表示客户端应尽快回复此消息,以避免超时断开连接;否则为 0。
@@ -1479,9 +1403,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - - 接收进程可以随时使用以下某种消息格式向发送方回传响应(同样放在 CopyData 消息的负载中): - + 接收进程可以随时使用以下消息格式之一回复发送端(同样放在 CopyData 消息的有效载荷中): @@ -1494,9 +1416,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('r') - - 将该消息标识为接收方状态更新。 - + 将该消息标识为接收端状态更新。 @@ -1505,9 +1425,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已接收并写入磁盘的 WAL 字节位置 + 1。 - + 备库已接收并写入磁盘的最后一个 WAL 字节的位置加 1。 @@ -1516,9 +1434,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已刷写到磁盘的 WAL 字节位置 + 1。 - + 备库已刷盘的最后一个 WAL 字节的位置加 1。 @@ -1527,9 +1443,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已应用的 WAL 字节位置 + 1。 - + 备库已应用的最后一个 WAL 字节的位置加 1。 @@ -1538,9 +1452,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 客户端在传输时的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时客户端的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1549,9 +1461,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1 - - 如果为 1,则客户端请求服务器立即回复此消息。这可用于 ping 服务器,以测试连接是否仍然健康。 - + 如果为 1,表示客户端请求服务器立即回复此消息。可用它向服务器发送探测请求,以测试连接是否仍然正常。 @@ -1568,9 +1478,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('h') - - 将该消息标识为热备反馈消息。 - + 将该消息标识为热备反馈消息。 @@ -1579,9 +1487,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 客户端在传输时的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时客户端的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1590,9 +1496,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 - - 备库当前的全局 xmin,不包括任何复制槽中的 catalog_xmin。如果该值和后面的 catalog_xmin 都为 0,则视为通知:此连接后续将不再发送热备反馈。之后的非零消息可能会重新启动反馈机制。 - + 备库当前的全局 xmin,不包括任何复制槽的 catalog_xmin。如果此值及后面的 catalog_xmin 都为 0,则视为通知服务器:此连接将不再发送热备反馈。之后的非零消息可以重新启动反馈机制。 @@ -1601,9 +1505,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 - - 备库上全局 xmin xid 的纪元。 - + 备库全局 xmin 事务 ID 的纪元。 @@ -1612,9 +1514,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 - - 备库上任何复制槽中的最低 catalog_xmin。如果备库上不存在 catalog_xmin,或已禁用热备反馈,则设为 0。 - + 备库上所有复制槽中最小的 catalog_xmin。如果备库上不存在 catalog_xmin,或者正在禁用热备反馈,则设为 0。 @@ -1623,9 +1523,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 - - 备库上 catalog_xmin xid 的纪元。 - + 备库 catalog_xmin 事务 ID 的纪元。 @@ -1706,7 +1604,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" DROP_REPLICATION_SLOT slot_name WAIT - 删除复制槽 + DROP_REPLICATION_SLOT @@ -1754,9 +1652,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" LABEL 'label' - 设置备份的标签。如果未指定,则将使用base backup作为备份标签。 - 标签的引号使用规则与打开的标准SQL字符串相同。 - + 设置备份标签。如果未指定,则使用 base backup 作为备份标签。标签的引号规则与启用 时的标准 SQL 字符串相同。 + @@ -1887,8 +1784,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" size (int8) - 表空间的大致大小,以千字节(1024字节)为单位,如果已请求进度报告;否则为null。 - + 如果请求了进度报告,则为表空间的大致大小,以千字节(1024 字节)为单位;否则为 null。 + @@ -1951,7 +1848,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 逻辑复制协议 + 逻辑流复制协议 本节介绍逻辑复制协议,它是一种以复制命令START_REPLICATION @@ -1960,7 +1857,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 逻辑复制协议构建在物理流复制协议的底层机制之上。 + 逻辑流复制协议构建在物理流复制协议的基本机制之上。 @@ -1973,7 +1870,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 逻辑流复制参数 - 使用 START_REPLICATION 命令时,pgoutput 接受以下选项: + 使用START_REPLICATION命令,pgoutput接受以下选项: @@ -2063,14 +1960,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 逻辑复制协议按事务逐个发送数据。这意味着,一对 Begin 与 Commit 消息之间的所有消息都属于同一事务。 - 同样,一对 Begin Prepare 与 Prepare 消息之间的所有消息也属于同一事务。 - 对于大型进行中事务,它还会在一对 Stream Start 与 Stream Stop 消息之间发送其更改。 - 这类事务的最后一个流会包含 Stream Commit 或 Stream Abort 消息。 + 逻辑复制协议逐个发送事务。这意味着,一对 Begin 和 Commit 消息之间的所有消息都属于同一个事务。对于进行中的大型事务,它还会在一对 Stream Start 和 Stream Stop 消息之间发送变更。这类事务的最后一个流包含 Stream Commit 或 Stream Abort 消息。 - 每个被发送的事务都包含零条或多条 DML 消息(插入、更新、删除)。在级联场景下,它还会包含 Origin 消息。Origin 消息表示该事务产生于另一个复制节点。由于逻辑复制协议中的复制节点可以是任意实现,因此唯一标识符就是该源头的名称。下游是否以及如何处理这一信息,由其自行决定。Origin 消息总是在事务中的任何 DML 消息之前发送。 + 每个发送的事务都包含零条或多条 DML 消息(Insert、Update、Delete)。在级联配置中,还可能包含 Origin 消息。Origin 消息表示该事务源自另一个复制节点。由于逻辑复制协议中的复制节点几乎可以是任何实现,因此唯一的标识符就是复制源的名称。下游负责按需处理这一信息(如果需要处理)。Origin 消息总是在事务中的任何 DML 消息之前发送。 @@ -2135,9 +2029,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 对后端返回的字符串长度,没有预定义的限制。 - 前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。 - 如果做不到这一点,就应读取完整字符串,并丢弃不适合固定大小缓冲区的尾随字符。 + 后端返回的字符串长度没有预定义的限制。前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。如果做不到这一点,就应读取完整字符串,并丢弃固定大小的缓冲区容纳不下的尾随字符。 @@ -2163,8 +2055,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 消息格式 - 本节描述每条消息的详细格式。每条消息都标记了可由前端(F)、后端(B)或双方(F&B)发送。 - 请注意,虽然每条消息开头都带有字节计数,但大多数消息格式都定义为无需参考该计数也能确定消息边界。这一设计最初是出于历史原因(早期已废弃的协议 v2 没有显式长度字段),同时也有助于有效性校验。 + 本节描述每条消息的详细格式。每条消息都标明它可以由前端(F)、后端(B)或双方(F & B)发送。注意,虽然每条消息开头都有字节计数,但消息格式的定义使得无需参考该计数也能确定消息的结束位置。这有助于检查消息的有效性。(CopyData 消息是例外,因为它构成数据流的一部分,任何单条 CopyData 消息的内容都无法独立解释。) @@ -2179,7 +2070,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2201,7 +2092,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定认证成功。 + 表示认证成功。 @@ -2221,7 +2112,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2243,7 +2134,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 Kerberos V5 认证。 + 表示需要 Kerberos V5 认证。 @@ -2263,7 +2154,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2285,7 +2176,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要明文密码。 + 表示需要明文密码。 @@ -2304,7 +2195,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2326,7 +2217,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要MD5加密的密码。 + 表示需要经过 MD5 加密的密码。 @@ -2337,7 +2228,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 用于加密密码时使用的盐。 + 加密密码时使用的盐。 @@ -2345,7 +2236,37 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - + +AuthenticationSCMCredential (B) + + + + + +Byte1('R') + +将该消息标识为认证请求。 + + + +Int32(8) + +消息内容的长度(以字节为单位),包括其自身。 + + + +Int32(6) + +表示需要 SCM 凭证消息。 + + + + + + + + + AuthenticationGSS (B) @@ -2356,7 +2277,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2377,7 +2298,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 GSSAPI 认证。 + 表示需要 GSSAPI 认证。 @@ -2396,7 +2317,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2418,7 +2339,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定此消息包含GSSAPI或SSPI数据。 + 表示此消息包含 GSSAPI 或 SSPI 数据。 @@ -2448,7 +2369,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2470,7 +2391,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 SSPI 认证。 + 表示需要 SSPI 认证。 @@ -2489,7 +2410,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2511,14 +2432,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 SASL 认证。 + 表示需要 SASL 认证。 - 消息正文是服务器首选的 SASL 认证机制列表。在最后一个认证机制名称后需要一个零字节作为终止符。对于每个机制,有以下内容: + 消息体是按服务器偏好顺序排列的 SASL 认证机制列表。在最后一个认证机制名称之后,必须有一个零字节作为终止符。每个机制包含以下内容: @@ -2545,7 +2466,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2567,7 +2488,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定此消息包含一个SASL挑战。 + 表示此消息包含 SASL 挑战。 @@ -2578,7 +2499,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - SASL数据,特定于正在使用的SASL机制。 + SASL 数据,具体内容取决于所使用的 SASL 机制。 @@ -2597,7 +2518,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2619,7 +2540,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定SASL认证已完成。 + 表示 SASL 认证已完成。 @@ -2630,7 +2551,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - SASL结果"附加数据",特定于正在使用的SASL机制。 + SASL 结果的“附加数据”,具体内容取决于所使用的 SASL 机制。 @@ -2649,8 +2570,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为取消键数据。 - 如果前端希望能够稍后发出CancelRequest消息,必须保存这些值。 + 将此消息标识为取消请求密钥数据。如果前端希望以后能够发送 CancelRequest 消息,就必须保存这些值。 @@ -2672,7 +2592,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 这个后端的进程ID。 + 此后端的进程 ID。 @@ -2683,7 +2603,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 该后端的 secret key。 + 此后端的密钥。 @@ -2703,7 +2623,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为绑定命令。 + 将该消息标识为 Bind 命令。 @@ -2747,10 +2667,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后面跟着的参数格式代码的数量(以下标记为C)。 - 这可以是零,表示没有参数或者所有参数都使用默认格式(文本); - 或者是一个,这种情况下指定的格式代码应用于所有参数; - 或者等于实际参数的数量。 + 后续参数格式代码的数量(下文以 C 表示)。可以为零,表示没有参数,或者所有参数都使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有参数;还可以等于实际参数数量。 @@ -2761,7 +2678,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数格式代码。每个目前必须是零(文本)或一(二进制)。 + 参数格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -2772,15 +2689,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后面跟着的参数值的数量(可能为零)。 - 这个数量必须与查询所需的参数数量匹配。 + 后续参数值的数量(可以为零)。必须与查询所需的参数数量一致。 - 接下来,对于每个参数,都会出现以下一对字段: + 接下来,每个参数都有以下一对字段: @@ -2790,9 +2706,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数值的长度,以字节为单位(此计数不包括自身)。可以为零。 - 作为特殊情况,-1表示空参数值。 - 在空参数值的情况下,不会跟随任何值字节。 + 参数值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 参数值。为 NULL 时,后面不再有值的字节。 @@ -2803,15 +2717,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数的值,以相关格式代码指示的格式表示。 - n是上述长度。 + 参数值,格式由对应的格式代码指明。n 为上述长度。 - 在最后一个参数之后,出现以下字段: + 最后一个参数之后是以下字段: @@ -2821,10 +2734,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后跟的结果列格式代码数量(以下标记为R)。 - 这可以是零,表示没有结果列,或者所有结果列应该使用默认格式(文本); - 或者是一个,此时指定的格式代码将应用于所有结果列(如果有); - 或者等于查询的实际结果列数。 + 后续结果列格式代码的数量(下文以 R 表示)。可以为零,表示没有结果列,或者所有结果列都应使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有结果列(如果有);还可以等于查询实际的结果列数量。 @@ -2835,7 +2745,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 结果列格式代码。每个目前必须是零(文本)或一(二进制)。 + 结果列格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -2854,7 +2764,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为绑定完成指示器。 + 将该消息标识为 Bind 完成指示。 @@ -2888,7 +2798,7 @@ CancelRequest (F) - 消息内容的长度,以字节为单位,包括此长度字段本身。 + 消息内容的长度(以字节为单位),包括其自身。 @@ -2939,7 +2849,7 @@ CancelRequest (F) - 将消息标识为关闭命令。 + 将该消息标识为 Close 命令。 @@ -2961,8 +2871,7 @@ CancelRequest (F) - 'S' 表示关闭一个预备语句;或者 - 'P' 表示关闭一个 portal。 + “S”表示关闭预备语句;“P”表示关闭 portal。 @@ -2992,7 +2901,7 @@ CancelRequest (F) - 标识消息为关闭完成指示符。 + 将该消息标识为 Close 完成指示。 @@ -3022,7 +2931,7 @@ CancelRequest (F) - 标识消息为命令完成响应。 + 将该消息标识为命令完成响应。 @@ -3044,7 +2953,7 @@ CancelRequest (F) - 命令标签。这通常是一个单词,用于标识已完成的SQL命令。 + 命令标签。通常是一个单词,用来标识已完成的 SQL 命令。 @@ -3068,10 +2977,7 @@ CancelRequest (F) 其中rows是更新的行数。 - - 对于MERGE命令,标签是MERGE rows, - 其中rows是插入、更新或删除的行数。 - + 对于SELECTCREATE TABLE AS命令,标签是SELECT rows, @@ -3089,10 +2995,7 @@ CancelRequest (F) - 对于COPY命令,标签是 - COPY rows,其中 - rows是复制的行数。 - (注意:行数仅出现在PostgreSQL 8.2及更高版本中。) + 对于 COPY 命令,标签为 COPY rows,其中 rows 是复制的行数。(注意:行数仅出现在 PostgreSQL 8.2 及更高版本中。) @@ -3223,8 +3126,7 @@ CancelRequest (F) - 标识消息为开始复制响应。 - 前端现在必须发送复制数据(如果没有准备好,发送CopyFail消息)。 + 将该消息标识为开始 COPY 输入的响应。前端此时必须发送 COPY 输入数据(如果尚未准备好,应发送 CopyFail 消息)。 @@ -3270,9 +3172,7 @@ CancelRequest (F) - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -3291,8 +3191,7 @@ CancelRequest (F) - 标识消息为开始复制输出响应。 - 该消息将被复制输出数据跟随。 + 将该消息标识为开始 COPY 输出的响应。此消息之后会发送 COPY 输出数据。 @@ -3314,8 +3213,9 @@ CancelRequest (F) - 0表示整体COPY格式为文本格式(行由换行符分隔,列由分隔符字符分隔等)。 - 1表示整体复制格式为二进制格式(类似于DataRow格式)。更多信息请参见。 + 0表示整体COPY格式是文本的(行由换行符分隔,列由分隔符分隔等)。 + 1表示整体复制格式是二进制的(类似于DataRow格式)。 + 更多信息请参见 @@ -3337,9 +3237,7 @@ CancelRequest (F) - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -3358,7 +3256,7 @@ CancelRequest (F) - 标识消息为开始复制双响应。此消息仅用于流复制。 + 将该消息标识为开始双向 COPY 的响应。此消息仅用于流复制。 @@ -3380,8 +3278,9 @@ CancelRequest (F) - 0表示整体COPY格式为文本格式(行由换行符分隔,列由分隔符字符分隔等)。 - 1表示整体复制格式为二进制格式(类似于DataRow格式)。更多信息请参见。 + 0表示整体COPY格式是文本的(行由换行符分隔,列由分隔符分隔等)。 + 1表示整体复制格式是二进制的(类似于DataRow格式)。 + 更多信息请参见 @@ -3403,9 +3302,7 @@ CancelRequest (F) - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -3453,7 +3350,7 @@ CancelRequest (F) - 接下来,对于每一列,都会出现以下一对字段: + 接下来,每列都有以下两个字段: @@ -3463,8 +3360,7 @@ CancelRequest (F) - 列值的长度,以字节为单位(此计数不包括其本身)。可以为零。 - 作为特殊情况,-1表示空列值。在空值情况下,不跟随任何值字节。 + 列值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 列值。为 NULL 时,后面不再有值的字节。 @@ -3495,7 +3391,7 @@ CancelRequest (F) - 标识消息为描述命令。 + 将该消息标识为 Describe 命令。 @@ -3548,7 +3444,7 @@ CancelRequest (F) - 将消息标识为对空查询字符串的响应。(这相当于CommandComplete。) + 标识消息为对空查询字符串的响应。(此消息替代 CommandComplete。) @@ -3596,7 +3492,7 @@ CancelRequest (F) - 消息正文由一个或多个已识别的字段组成,后跟一个零字节作为终止符。字段可以以任何顺序出现。对于每个字段,都有以下内容: + 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -3619,7 +3515,7 @@ CancelRequest (F) - 字段数值。 + 字段值。 @@ -3638,7 +3534,7 @@ CancelRequest (F) - 标识消息为一个执行命令。 + 将该消息标识为 Execute 命令。 @@ -3671,7 +3567,7 @@ CancelRequest (F) - 如果 portal 包含返回行的查询,则为要返回的最大行数(否则忽略)。零表示没有限制。 + 如果 portal 包含返回行的查询,则这是最多返回的行数(否则忽略此值)。零表示无限制 @@ -3690,7 +3586,7 @@ CancelRequest (F) - 将消息标识为Flush命令。 + 将该消息标识为 Flush 命令。 @@ -3742,7 +3638,7 @@ CancelRequest (F) - 指定要调用的函数的对象ID。 + 指定要调用的函数的对象 ID。 @@ -3753,10 +3649,7 @@ CancelRequest (F) - 后面跟着的参数格式代码的数量(以下标记为C)。 - 这可以是零,表示没有参数或所有参数都使用默认格式(文本); - 或者是一个,这种情况下指定的格式代码应用于所有参数; - 或者等于实际参数的数量。 + 后续参数格式代码的数量(以下用 C 表示)。可以为零,表示没有参数,或所有参数都采用默认格式(文本);也可以为一,表示将指定的格式代码用于所有参数;还可以等于实际参数数量。 @@ -3785,7 +3678,7 @@ CancelRequest (F) - 接下来,对于每个参数,都会出现以下一对字段: + 接下来,每个参数都有以下两个字段: @@ -3795,9 +3688,7 @@ CancelRequest (F) - 参数值的长度,以字节为单位(此计数不包括自身)。可以为零。 - 作为特殊情况,-1表示空参数值。 - 在空参数值的情况下,不会跟随任何值字节。 + 参数值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 参数值。为 NULL 时,后面不再有值的字节。 @@ -3816,7 +3707,7 @@ CancelRequest (F) - 在最后一个参数之后,出现以下字段: + 最后一个参数之后还有以下字段: @@ -3826,7 +3717,7 @@ CancelRequest (F) - 函数结果的格式代码。目前必须是零(文本)或一(二进制)。 + 函数结果的格式代码。目前必须为零(文本)或一(二进制)。 @@ -3867,9 +3758,7 @@ CancelRequest (F) - 函数结果值的长度,以字节为单位(此计数不包括本身)。可以为零。 - 作为特殊情况,-1表示NULL函数结果。 - 在NULL情况下,不会跟随任何值字节。 + 函数结果值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 函数结果。为 NULL 时,后面不再有值的字节。 @@ -3995,7 +3884,7 @@ CancelRequest (F) - 服务器支持的最新次要协议版本,用于客户端请求的主要协议版本。 + 对于客户端请求的协议主版本,服务器所支持的最新协议次版本。 @@ -4006,14 +3895,14 @@ CancelRequest (F) - 服务器未识别的协议选项数量。 + 服务器无法识别的协议选项数量。 - 然后,对于服务器未识别的协议选项,有以下内容: + 接下来,对于服务器无法识别的每个协议选项,都有以下内容: @@ -4090,7 +3979,7 @@ CancelRequest (F) - 消息正文由一个或多个已识别的字段组成,后跟一个零字节作为终止符。字段可以以任何顺序出现。对于每个字段,都有以下内容: + 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -4113,7 +4002,7 @@ CancelRequest (F) - 字段数值。 + 字段值。 @@ -4154,7 +4043,7 @@ CancelRequest (F) - 通知后端进程的进程ID。 + 发出通知的后端进程的进程 ID。 @@ -4165,7 +4054,7 @@ CancelRequest (F) - 通知被触发的频道名称。 + 发出该通知的通道名称。 @@ -4176,7 +4065,7 @@ CancelRequest (F) - 从通知进程传递的有效负载字符串。 + 通知进程传来的有效载荷字符串。 @@ -4224,7 +4113,7 @@ CancelRequest (F) - 然后,对于每个参数,都有以下内容: + 接下来,每个参数都有以下内容: @@ -4234,7 +4123,7 @@ CancelRequest (F) - 指定参数数据类型的对象ID。 + 指定参数数据类型的对象 ID。 @@ -4275,7 +4164,7 @@ CancelRequest (F) - 正在报告的运行时参数的名称。 + 所报告的运行时参数的名称。 @@ -4305,7 +4194,7 @@ CancelRequest (F) - 将消息标识为解析命令。 + 将该消息标识为 Parse 命令。 @@ -4357,7 +4246,7 @@ CancelRequest (F) - 然后,对于每个参数,都有以下内容: + 接下来,每个参数都有以下内容: @@ -4367,7 +4256,7 @@ CancelRequest (F) - 指定参数数据类型的对象ID。在这里放置零相当于未指定类型。 + 指定参数数据类型的对象 ID。此处填零等同于不指定类型。 @@ -4386,7 +4275,7 @@ CancelRequest (F) - 将消息标识为解析完成指示器。 + 将该消息标识为 Parse 完成指示。 @@ -4458,8 +4347,7 @@ CancelRequest (F) - 标识消息为 portal 挂起指示器。 - 请注意,仅当执行消息的行数限制达到时才会出现此消息。 + 将该消息标识为 portal 挂起指示。注意,仅当达到 Execute 消息指定的行数限制时,才会出现此消息。 @@ -4595,14 +4483,14 @@ CancelRequest (F) - 指定一行中的字段数(可以为零)。 + 指定一行中的字段数量(可以为零)。 - 然后,对于每个字段,都有以下内容: + 接下来,每个字段都有以下内容: @@ -4623,7 +4511,7 @@ CancelRequest (F) - 如果该字段可以被识别为特定表的列,则为该表的对象ID;否则为零。 + 如果能够确定该字段是某个特定表的列,则为该表的对象 ID;否则为零。 @@ -4634,7 +4522,7 @@ CancelRequest (F) - 如果该字段可以被识别为特定表的列,则为该列的属性编号;否则为零。 + 如果能够确定该字段是某个特定表的列,则为该列的属性编号;否则为零。 @@ -4645,7 +4533,7 @@ CancelRequest (F) - 字段数据类型的对象ID。 + 字段数据类型的对象 ID。 @@ -4680,7 +4568,7 @@ CancelRequest (F) - 正在使用的字段格式代码。目前将为零(文本)或一(二进制)。在从描述语句变体返回的RowDescription中,格式代码尚未知晓,将始终为零。 + 字段所使用的格式代码。目前为零(文本)或一(二进制)。对于 Describe 针对预备语句的变体所返回的 RowDescription,格式代码尚未确定,始终为零。 @@ -4733,7 +4621,7 @@ CancelRequest (F) - 长度为SASL机制特定的“初始客户端响应”,如果没有初始响应,则为-1。 + 后续 SASL 机制特有的“客户端初始响应”的长度;如果没有初始响应,则为 -1。 @@ -4848,17 +4736,14 @@ CancelRequest (F) - 协议版本号。最重要的16位是主版本号(此处描述的协议为3)。 - 最不重要的16位是次版本号(此处描述的协议为2)。 + 协议版本号。高 16 位为主版本号(此处描述的协议为 3);低 16 位为次版本号(此处描述的协议为 0)。 - 协议版本号后面跟着一个或多个参数名和值字符串对。在最后一个名/值对之后需要一个零字节作为终止符。 - 参数可以以任何顺序出现。user是必需的,其他是可选的。 - 每个参数的指定方式为: + 协议版本号之后是一个或多个参数名与参数值字符串对。最后一个名称/值对之后必须有一个零字节作为终止符。参数可以按任意顺序出现。其中,user是必需的,其余均为可选。每个参数按以下方式指定: @@ -4868,7 +4753,7 @@ CancelRequest (F) - 参数名称。当前识别的名称包括: + 参数名称。目前能够识别的名称如下: @@ -4908,7 +4793,7 @@ CancelRequest (F) - 除上述之外,还可以列出其他参数。以_pq_.开头的参数名称保留用于协议扩展,而其他参数被视为后端启动时设置的运行时参数。这些设置将在后端启动时应用(在解析命令行参数后,如果有的话),并将作为会话默认值。 + 除上述参数外,还可以列出其他参数。以_pq_.开头的参数名称保留用于协议扩展,其余参数则作为运行时参数,在后端启动时设置。这些设置会在后端启动期间应用(在解析命令行参数之后,如果有的话),并作为会话默认值。 @@ -4919,7 +4804,7 @@ CancelRequest (F) - 参数数值。 + 参数值。 @@ -4938,7 +4823,7 @@ CancelRequest (F) - 将消息标识为同步命令。 + 将该消息标识为 Sync 命令。 @@ -4991,7 +4876,7 @@ CancelRequest (F) - 错误和通知消息域 + 错误和通知消息字段 本节描述了ErrorResponse和NoticeResponse消息中可能出现的字段。每个字段类型都有一个单字节的标识符。 @@ -5004,11 +4889,7 @@ CancelRequest (F) - 严重性: 字段内容为ERROR, FATAL, 或 - PANIC (在错误消息中), 或 - WARNING, NOTICE, DEBUG, - INFO, 或 LOG (在通知消息中), - 或者这些内容的本地化翻译。始终存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中),或这些内容的本地化翻译。始终存在。 @@ -5018,11 +4899,7 @@ CancelRequest (F) - 严重性:字段内容为 ERRORFATAL 或 - PANIC(在错误消息中),或 WARNINGNOTICEDEBUG、 - INFOLOG(在通知消息中)。 - 这与S字段相同,只是内容不会被本地化。仅在由PostgreSQL版本9.6 - 及更高版本生成的消息中存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中)。它与 S 字段相同,只是内容从不本地化。仅在 PostgreSQL 9.6 及更高版本生成的消息中存在。 @@ -5032,7 +4909,7 @@ CancelRequest (F) - Code: 错误的SQLSTATE代码(参见)。不可本地化。始终存在。 + 代码:错误的 SQLSTATE 代码(见 )。不可本地化。始终存在。 @@ -5042,9 +4919,7 @@ CancelRequest (F) - 消息: 主要的人类可读错误消息。 - 这应该准确但简洁(通常一行)。 - 总是存在。 + 消息:主要的可读错误消息。应准确而简洁(通常为一行)。始终存在。 @@ -5054,7 +4929,7 @@ CancelRequest (F) - 详细信息:一个可选的次要错误消息,提供有关问题的更多详细信息。可能会跨多行。 + 详细信息:可选的次要错误消息,提供有关该问题的更多细节。可能占多行。 @@ -5064,9 +4939,7 @@ CancelRequest (F) - 提示: 关于问题应该怎么做的一个可选建议。 - 这意在与细节不同,它提供建议(可能不合适)而不是硬性事实。 - 可能会跨越多行。 + 提示:可选的建议,说明如何处理该问题。它与详细信息的区别在于,它提供建议(可能并不合适),而非确凿事实。可能占多行。 @@ -5109,9 +4982,7 @@ CancelRequest (F) - Where: 错误发生的上下文指示。 - 目前包括活动的过程语言函数和内部生成查询的调用堆栈回溯。 - 跟踪每行一个条目,最近的在前。 + 上下文:说明错误发生时的上下文。目前包括活跃的过程语言函数和内部生成的查询的调用栈回溯。回溯每行一个条目,最近的调用在前。 @@ -5121,7 +4992,7 @@ CancelRequest (F) - Schema name: 如果错误与特定数据库对象相关联,则为包含该对象的模式的名称(如果有)。 + 模式名:如果错误与某个特定数据库对象有关,则为包含该对象的模式名称(如果有)。 @@ -5131,7 +5002,7 @@ CancelRequest (F) - 表名: 如果错误与特定表相关联,则为表的名称。(有关表模式名称的名称,请参考模式名称字段。) + 表名:如果错误与某个特定表有关,则为该表的名称。(表所在模式的名称见模式名字段。) @@ -5141,7 +5012,7 @@ CancelRequest (F) - 列名: 如果错误与特定表列相关联,则为列的名称。(请参考模式和表名字段以识别表。) + 列名:如果错误与某个特定表列有关,则为该列的名称。(通过模式名和表名字段确定该表。) @@ -5151,8 +5022,7 @@ CancelRequest (F) - 数据类型名称: 如果错误与特定数据类型相关联,则为数据类型的名称。 - (有关数据类型模式的名称,请参阅模式名称字段。) + 数据类型名:如果错误与某个特定数据类型有关,则为该数据类型的名称。(数据类型所在模式的名称见模式名字段。) @@ -5162,8 +5032,7 @@ CancelRequest (F) - 约束名称: 如果错误与特定约束相关联,则为约束的名称。请参考上面列出的字段,了解相关表或域。 - (为此,即使索引不是使用约束语法创建的,也将其视为约束。) + 约束名:如果错误与某个特定约束有关,则为该约束的名称。相关的表或域见上述字段。(这里将索引也视为约束,即使它不是用约束语法创建的。) @@ -5173,7 +5042,7 @@ CancelRequest (F) - 文件: 报告错误的源代码位置的文件名。 + 文件:报告错误的源代码位置所在的文件名。 @@ -5183,7 +5052,7 @@ CancelRequest (F) - Line: 源代码位置的行号,报告错误的位置。 + 行号:报告错误的源代码位置所在的行号。 @@ -5193,7 +5062,7 @@ CancelRequest (F) - Routine: 报告错误的源代码例程的名称。 + 例程:报告错误的源代码例程的名称。 @@ -5202,15 +5071,12 @@ CancelRequest (F) - 模式名称、表名称、列名称、数据类型名称和约束名称的字段仅针对有限数量的错误类型提供; - 请参阅。前端不应假设任何这些字段的存在就保证了另一个字段的存在。 - 核心错误源观察到上述相互关系,但用户定义的函数可能以其他方式使用这些字段。 - 同样地,客户端不应假设这些字段表示当前数据库中的当代对象。 + 模式名、表名、列名、数据类型名和约束名字段仅针对有限的几类错误提供,见 。前端不应假设其中任何字段的存在就保证了另一个字段的存在。核心错误源遵循上述相互关系,但用户定义的函数可能以其他方式使用这些字段。同样,客户端不应假设这些字段表示当前数据库中现存的对象。 - 客户端负责格式化显示的信息以满足其需求;特别是应根据需要换行。错误消息字段中出现的换行符应被视为段落分隔符,而不是换行符。 + 客户端负责按自身需要格式化显示的信息;尤其应根据需要将长行断开。错误消息字段中的换行符应视为段落分隔符,而非行分隔符。 @@ -5236,40 +5102,46 @@ CancelRequest (F) - 将消息标识为开始消息。 + 将该消息标识为 Begin 消息。 - Int64(XLogRecPtr) + + Int64 + - 事务的最终LSN。 + 事务的最终 LSN。 - Int64 (TimestampTz) + + Int64 + - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 - Int32 (TransactionId) + + Int32 + - 事务的Xid。 + 事务的 Xid。 @@ -5295,12 +5167,13 @@ CancelRequest (F) - Int32 (TransactionId) + + Int32 + - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -5311,14 +5184,16 @@ CancelRequest (F) - 标志; 逻辑解码消息是非事务性的时为0,是事务性的时为1。 + 标志:0 表示没有标志;1 表示该逻辑解码消息是事务性的。 - Int64(XLogRecPtr) + + Int64 + @@ -5374,51 +5249,59 @@ CancelRequest (F) - 标识消息为提交消息。 + 将该消息标识为 Commit 消息。 - Int8(0) + + Int8 + - 标志; 目前未使用。 + 标志;目前未使用(必须为 0)。 - Int64(XLogRecPtr) + + Int64 + - 提交的LSN。 + 提交的 LSN。 - Int64(XLogRecPtr) + + Int64 + - 事务的结束LSN。 + 事务的结束 LSN。 - Int64 (TimestampTz) + + Int64 + - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -5437,18 +5320,20 @@ CancelRequest (F) - 将消息标识为原始消息。 + 将该消息标识为 Origin 消息。 - Int64(XLogRecPtr) + + Int64 + - 原始服务器上提交的LSN。 + 源服务器上提交的 LSN。 @@ -5459,14 +5344,14 @@ CancelRequest (F) - 原点的名称。 + 复制源的名称。 - 请注意,在单个事务中可能存在多个Origin消息。 + 注意,单个事务中可能有多条 Origin 消息。 @@ -5482,30 +5367,33 @@ CancelRequest (F) - 标识消息为关系消息。 + 将该消息标识为 Relation 消息。 - Int32 (TransactionId) + + Int32 + - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 - Int32 (Oid) + + Int32 + - 关系的OID。 + 关系的 ID。 @@ -5516,7 +5404,7 @@ CancelRequest (F) - 命名空间(pg_catalog为空字符串)。 + 命名空间(对于 pg_catalog 为空字符串)。 @@ -5538,7 +5426,7 @@ CancelRequest (F) - 关系的复制标识设置(与relreplidentpg_class中相同)。 + 关系的复制标识设置(与 pg_class 中的 relreplident 相同)。 @@ -5556,7 +5444,7 @@ CancelRequest (F) - 接下来,对于出版物中包含的每一列(除了生成的列),会出现以下消息部分: + 接下来,每列(生成列除外)都有以下消息部分: @@ -5566,7 +5454,7 @@ CancelRequest (F) - 列的标志。目前可以是0表示没有标志,或者是1表示将该列标记为键的一部分。 + 列的标志。目前可以为 0,表示没有标志;或为 1,标记该列是键的一部分。 @@ -5584,11 +5472,13 @@ CancelRequest (F) - Int32 (Oid) + + Int32 + - 列数据类型的OID。 + 列的数据类型 ID。 @@ -5599,7 +5489,7 @@ CancelRequest (F) - 列的类型修饰符 (atttypmod)。 + 列的类型修饰符(atttypmod)。 @@ -5618,30 +5508,33 @@ CancelRequest (F) - 将消息标识为类型消息。 + 将该消息标识为 Type 消息。 - Int32 (TransactionId) + + Int32 + - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 - Int32 (Oid) + + Int32 + - 数据类型的OID。 + 数据类型的 ID。 @@ -5652,7 +5545,7 @@ CancelRequest (F) - 命名空间(pg_catalog为空字符串)。 + 命名空间(对于 pg_catalog 为空字符串)。 @@ -5682,30 +5575,33 @@ CancelRequest (F) - 标识消息为插入消息。 + 将该消息标识为 Insert 消息。 - Int32 (TransactionId) + + Int32 + - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 - Int32 (Oid) + + Int32 + - 与关系消息中ID对应的关系的OID。 + 关系的 ID,与 Relation 消息中的 ID 对应。 @@ -5716,7 +5612,7 @@ CancelRequest (F) - 标识以下TupleData消息为新元组。 + 将后续 TupleData 消息标识为新元组。 @@ -5727,7 +5623,7 @@ CancelRequest (F) - TupleData消息部分,表示新元组的内容。 + 表示新元组内容的 TupleData 消息部分。 @@ -5746,30 +5642,33 @@ CancelRequest (F) - 标识消息为更新消息。 + 将该消息标识为 Update 消息。 - Int32 (TransactionId) + + Int32 + - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 - Int32 (Oid) + + Int32 + - 与关系消息中ID对应的关系的OID。 + 关系的 ID,与 Relation 消息中的 ID 对应。 @@ -5780,8 +5679,7 @@ CancelRequest (F) - 标识以下TupleData子消息为键。 - 此字段是可选的,仅在更新更改了属于REPLICA IDENTITY索引的任何列的数据时才存在。 + 将后续 TupleData 子消息标识为键。此字段可选,仅在更新更改了属于 REPLICA IDENTITY 索引的某一列或多列的数据时出现。 @@ -5792,8 +5690,7 @@ CancelRequest (F) - 标识以下TupleData子消息为旧元组。 - 此字段是可选的,仅在发生更新的表中REPLICA IDENTITY设置为FULL时才存在。 + 将后续 TupleData 子消息标识为旧元组。此字段可选,仅在发生更新的表将 REPLICA IDENTITY 设为 FULL 时出现。 @@ -5804,7 +5701,7 @@ CancelRequest (F) - TupleData消息部分表示旧元组或主键的内容。仅在先前的'O'或'K'部分存在时才存在。 + 表示旧元组或主键内容的 TupleData 消息部分。仅在前面的'O'或'K'部分存在时出现。 @@ -5815,7 +5712,7 @@ CancelRequest (F) - 标识以下TupleData消息为新元组。 + 将后续 TupleData 消息标识为新元组。 @@ -5826,14 +5723,14 @@ CancelRequest (F) - TupleData消息部分表示新元组的内容。 + 表示新元组内容的 TupleData 消息部分。 - 更新消息可能包含一个'K'消息部分,也可能包含一个'O'消息部分,或者两者都不包含,但绝不会同时包含两者。 + Update 消息可以包含 'K' 消息部分或 'O' 消息部分,也可以两者都不包含,但绝不会同时包含两者。 @@ -5849,30 +5746,33 @@ CancelRequest (F) - 标识消息为删除消息。 + 将该消息标识为 Delete 消息。 - Int32 (TransactionId) + + Int32 + - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 - Int32 (Oid) + + Int32 + - 与关系消息中ID对应的关系的OID。 + 关系的 ID,与 Relation 消息中的 ID 对应。 @@ -5883,8 +5783,7 @@ CancelRequest (F) - 标识以下TupleData子消息为键。 - 如果发生删除操作的表使用索引作为REPLICA IDENTITY,则存在此字段。 + 将后续 TupleData 子消息标识为键。如果发生删除的表使用索引作为 REPLICA IDENTITY,则出现此字段。 @@ -5895,8 +5794,7 @@ CancelRequest (F) - 标识以下TupleData消息为旧元组。 - 如果发生删除操作的表的REPLICA IDENTITY设置为FULL,则存在此字段。 + 将后续 TupleData 消息标识为旧元组。如果发生删除的表将 REPLICA IDENTITY 设为 FULL,则出现此字段。 @@ -5907,14 +5805,14 @@ CancelRequest (F) - TupleData消息部分,表示旧元组或主键的内容,取决于前一个字段。 + 表示旧元组或主键内容的 TupleData 消息部分,具体取决于前一个字段。 - 删除消息可能包含一个'K'消息部分或一个'O'消息部分,但绝不会同时包含两者。 + Delete 消息可以包含 'K' 消息部分或 'O' 消息部分,但绝不会同时包含两者。 @@ -5930,19 +5828,20 @@ CancelRequest (F) - 将消息标识为截断消息。 + 将该消息标识为 Truncate 消息。 - Int32 (TransactionId) + + Int32 + - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -5972,11 +5871,13 @@ CancelRequest (F) - Int32 (Oid) + + Int32 + - 与关系消息中ID对应的关系的OID。该字段对每个关系都重复。 + 关系的 ID,与 Relation 消息中的 ID 对应。每个关系都重复出现此字段。 @@ -6001,18 +5902,20 @@ CancelRequest (F) - 标识消息为流开始消息。 + 将该消息标识为 Stream Start 消息。 - Int32 (TransactionId) + + Int32 + - 事务的Xid。 + 事务的 Xid。 @@ -6042,7 +5945,7 @@ CancelRequest (F) - 标识消息为流停止消息。 + 将该消息标识为 Stream Stop 消息。 @@ -6061,62 +5964,72 @@ CancelRequest (F) - 将消息标识为流提交消息。 + 将该消息标识为 Stream Commit 消息。 - Int32 (TransactionId) + + Int32 + - 事务的Xid。 + 事务的 Xid。 - Int8(0) + + Int8 + - 标志; 目前未使用。 + 标志;目前未使用(必须为 0)。 - Int64(XLogRecPtr) + + Int64 + - 提交的LSN。 + 提交的 LSN。 - Int64(XLogRecPtr) + + Int64 + - 事务的结束LSN。 + 事务的结束 LSN。 - Int64 (TimestampTz) + + Int64 + - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6135,25 +6048,29 @@ CancelRequest (F) - 将消息标识为流中止消息。 + 将该消息标识为 Stream Abort 消息。 - Int32 (TransactionId) + + Int32 + - 事务的Xid。 + 事务的 Xid。 - Int32 (TransactionId) + + Int32 + @@ -6189,14 +6106,14 @@ CancelRequest (F) - 接下来,对于每一列(除了生成的列),会出现以下子消息之一: + 接下来,每一列(生成列除外)都会出现以下子消息之一: Byte1('n') - 将数据标识为NULL值。 + 将该数据标识为 NULL 值。 @@ -6207,7 +6124,7 @@ CancelRequest (F) Byte1('u') - 将TOASTed值标识为未更改的值(实际值未发送)。 + 标识未更改的 TOAST 值(不发送实际值)。 @@ -6218,7 +6135,7 @@ CancelRequest (F) Byte1('t') - 将数据标识为文本格式化值。 + 将该数据标识为文本格式的值。 @@ -6229,7 +6146,7 @@ CancelRequest (F) Byte1('b') - 将数据标识为二进制格式化值。 + 将该数据标识为二进制格式的值。 @@ -6247,9 +6164,7 @@ CancelRequest (F) Byten - 列的值,以二进制或文本格式呈现。 - (如前述格式字节中指定)。 - n是上述长度。 + 列值,采用二进制或文本格式(由前面的格式字节指定)。n 为上述长度。 diff --git a/zh/14/rangetypes.sgml b/zh/14/rangetypes.sgml index 68409fa3..5badec6c 100644 --- a/zh/14/rangetypes.sgml +++ b/zh/14/rangetypes.sgml @@ -5,11 +5,11 @@ 范围类型 - range type + 范围类型 - multirange type + 多范围类型 @@ -21,7 +21,7 @@ - 每种范围类型都有一个对应的多范围类型。多范围是由多个彼此不连续、非空且非 NULL 的范围构成的有序列表。大多数范围操作符也可作用于多范围,并且多范围还有一些专用函数。 + 每种范围类型都有一个对应的多范围类型。多范围是一个有序列表,其中的范围彼此不连续,且均非空、非 NULL。大多数范围操作符也可作用于多范围,并且多范围还有一些专用函数。 @@ -124,15 +124,15 @@ SELECT isempty(numrange(1, 5)); 无限(无界)范围 - 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作 +/-infinity,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的 +/-infinity 值。 + 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作正负无穷大,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的正负无穷大值。 - 具有infinity概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 + 具有无穷大概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 - 函数lower_infupper_inf分别测试范围的下界和上界是否为无限。 + 函数lower_infupper_inf分别测试范围是否没有下界和上界。 @@ -324,8 +324,8 @@ SELECT '[11:10, 23:00]'::timerange; 索引 - range type - indexes on + 范围类型 + 索引 @@ -357,7 +357,7 @@ CREATE INDEX reservation_idx ON reservation USING GIST (during); - 此外,也可以为范围类型的表列创建 B-树和哈希索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和哈希支持主要是为了允许在查询内部进行排序和哈希,而不是用于创建实际的索引。 + 此外,也可以为范围类型的表列创建 B-树和 hash 索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和 hash 支持主要是为了允许在查询内部进行排序和 hash 运算,而不是用于创建实际的索引。 @@ -366,8 +366,8 @@ CREATE INDEX reservation_idx ON reservation USING GIST (during); 范围上的约束 - range type - exclude + 范围类型 + 排他约束 diff --git a/zh/14/ref/alter_extension.sgml b/zh/14/ref/alter_extension.sgml index 3ceae003..b5824a68 100644 --- a/zh/14/ref/alter_extension.sgml +++ b/zh/14/ref/alter_extension.sgml @@ -170,7 +170,7 @@ ALTER EXTENSION name DROP 要添加到扩展中或从扩展中移除的对象名称。表、聚合、域、外部表、函数、 - 操作符、操作符类、操作符族、过程、例程、序列、文本搜索对象、类型和视图的名称 + 操作符、操作符类、操作符族、过程、例程、序列、文本检索对象、类型和视图的名称 可以带模式限定。 diff --git a/zh/14/ref/alter_tsconfig.sgml b/zh/14/ref/alter_tsconfig.sgml index 891dce66..0845a229 100644 --- a/zh/14/ref/alter_tsconfig.sgml +++ b/zh/14/ref/alter_tsconfig.sgml @@ -19,7 +19,7 @@ PostgreSQL documentation ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义 + 更改一个文本检索配置的定义 @@ -51,7 +51,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义。你可以修改其从记号类型到字典的映射, + 更改一个文本检索配置的定义。你可以修改其从词元类型到词典的映射, 或者更改该配置的名称或拥有者。 @@ -75,7 +75,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 一个现有文本搜索配置的名称(可以是模式限定的)。 + 一个现有文本检索配置的名称(可以是模式限定的)。 @@ -86,7 +86,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 由该配置的解析器发出的记号类型的名称。 + 由该配置的解析器发出的词元类型的名称。 @@ -97,7 +97,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 用于指定记号类型的文本搜索字典名称。如果列出了多个字典, + 用于指定词元类型的文本检索词典名称。如果列出了多个词典, 将按指定顺序依次查阅它们。 @@ -109,7 +109,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 在映射中要替换的文本搜索字典的名称。 + 在映射中要替换的文本检索词典的名称。 @@ -121,7 +121,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA 被用来替代old_dictionary - 的文本搜索字典的名称。 + 的文本检索词典的名称。 @@ -132,7 +132,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新名称。 + 该文本检索配置的新名称。 @@ -143,7 +143,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新拥有者。 + 该文本检索配置的新拥有者。 @@ -154,7 +154,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新模式。 + 该文本检索配置的新模式。 @@ -163,17 +163,17 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - ADD MAPPING FOR形式会为指定记号类型设置要查阅的字典列表; - 如果任一记号类型已经有映射,则会报错。ALTER MAPPING FOR - 形式作用相同,但会先移除这些记号类型的任何现有映射。 + ADD MAPPING FOR形式会为指定词元类型设置要查阅的词典列表; + 如果任一词元类型已经有映射,则会报错。ALTER MAPPING FOR + 形式作用相同,但会先移除这些词元类型的任何现有映射。 ALTER MAPPING REPLACE形式会在 old_dictionary出现的任何位置, 用new_dictionary替换它。 - 如果出现FOR,则只对指定的记号类型这样做;如果未出现 + 如果出现FOR,则只对指定的词元类型这样做;如果未出现 FOR,则对该配置的所有映射这样做。 - DROP MAPPING形式会移除指定记号类型的所有字典,使这些类型的 - 记号被文本搜索配置忽略。除非出现IF EXISTS,否则如果这些 - 记号类型没有映射就会报错。 + DROP MAPPING形式会移除指定词元类型的所有词典,使这些类型的 + 词元被文本检索配置忽略。除非出现IF EXISTS,否则如果这些 + 词元类型没有映射就会报错。 @@ -187,7 +187,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA 下面的示例将my_config中凡是使用 - english字典的地方,都替换为swedish字典。 + english词典的地方,都替换为swedish词典。 diff --git a/zh/14/ref/alter_tsdictionary.sgml b/zh/14/ref/alter_tsdictionary.sgml index 163d788b..798c6734 100644 --- a/zh/14/ref/alter_tsdictionary.sgml +++ b/zh/14/ref/alter_tsdictionary.sgml @@ -19,7 +19,7 @@ PostgreSQL documentation ALTER TEXT SEARCH DICTIONARY - 更改一个文本搜索字典的定义 + 更改一个文本检索词典的定义 @@ -43,14 +43,14 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - ALTER TEXT SEARCH DICTIONARY更改文本搜索字典的 - 定义。你可以更改该字典的模板相关选项,也可以更改该字典的名称或拥有者。 + ALTER TEXT SEARCH DICTIONARY更改文本检索词典的 + 定义。你可以更改该词典的模板相关选项,也可以更改该词典的名称或拥有者。 - 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该字典 + 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该词典 的拥有者。 @@ -67,7 +67,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 一个现有文本搜索字典的名称(可以是模式限定的)。 + 一个现有文本检索词典的名称(可以是模式限定的)。 @@ -78,7 +78,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -89,7 +89,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 模板相关选项要使用的新值。如果省略等号和值,则会从该字典中移除 + 模板相关选项要使用的新值。如果省略等号和值,则会从该词典中移除 该选项之前的设置,从而允许使用默认值。 @@ -101,7 +101,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新名称。 + 该文本检索词典的新名称。 @@ -112,7 +112,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新拥有者。 + 该文本检索词典的新拥有者。 @@ -123,7 +123,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新模式。 + 该文本检索词典的新模式。 @@ -144,7 +144,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 下面的示例命令更改了一个基于 Snowball 的字典的停用词列表。其他参数 + 下面的示例命令更改了一个基于 Snowball 的词典的停用词列表。其他参数 保持不变。 @@ -170,7 +170,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( language = dutch, StopWords ); - 下面的示例命令更新了该字典的定义,但实际上并没有做 + 下面的示例命令更新了该词典的定义,但实际上并没有做 任何更改。 @@ -178,7 +178,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( dummy ); (之所以可行,是因为选项移除代码在不存在该选项时也不会报错。) - 这种技巧在修改该字典的配置文件时很有用:ALTER + 这种技巧在修改该词典的配置文件时很有用:ALTER 会强制现有数据库会话重新读取配置文件,而如果它们先前已经读取过这 些文件,本来是不会再次读取的。 diff --git a/zh/14/ref/alter_tsparser.sgml b/zh/14/ref/alter_tsparser.sgml index 0844cb0a..ccc73f05 100644 --- a/zh/14/ref/alter_tsparser.sgml +++ b/zh/14/ref/alter_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH PARSER - 更改一个全文检索解析器的定义 + 更改一个文本检索解析器的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA 描述 - ALTER TEXT SEARCH PARSER更改全文检索解析器的定义。 + ALTER TEXT SEARCH PARSER更改文本检索解析器的定义。 当前唯一支持的功能是更改该解析器的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA name - 一个现有全文检索解析器的名称(可以是模式限定的)。 + 一个现有文本检索解析器的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_name - 该全文检索解析器的新名称。 + 该文本检索解析器的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_schema - 该全文检索解析器的新模式。 + 该文本检索解析器的新模式。 diff --git a/zh/14/ref/alter_tstemplate.sgml b/zh/14/ref/alter_tstemplate.sgml index a3eec599..9c9dfc2c 100644 --- a/zh/14/ref/alter_tstemplate.sgml +++ b/zh/14/ref/alter_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH TEMPLATE - 更改一个文本搜索模板的定义 + 更改一个文本检索模板的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA 描述 - ALTER TEXT SEARCH TEMPLATE更改文本搜索模板的定义。 + ALTER TEXT SEARCH TEMPLATE更改文本检索模板的定义。 当前唯一支持的功能是更改该模板的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA name - 一个现有文本搜索模板的名称(可以是模式限定的)。 + 一个现有文本检索模板的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_name - 该文本搜索模板的新名称。 + 该文本检索模板的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_schema - 该文本搜索模板的新模式。 + 该文本检索模板的新模式。 diff --git a/zh/14/ref/create_tsconfig.sgml b/zh/14/ref/create_tsconfig.sgml index 52970b36..fc77edb9 100644 --- a/zh/14/ref/create_tsconfig.sgml +++ b/zh/14/ref/create_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH CONFIGURATION - 定义一个新的文本搜索配置 + 定义一个新的文本检索配置 @@ -33,24 +33,24 @@ CREATE TEXT SEARCH CONFIGURATION name CREATE TEXT SEARCH CONFIGURATION - 创建一个新的文本搜索配置。文本搜索配置指定一个能把字符串拆分为记号 - 的文本搜索解析器,以及一些可用于判断哪些记号对搜索有意义的词典。 + 创建一个新的文本检索配置。文本检索配置指定一个能把字符串拆分为词元 + 的文本检索解析器,以及一些可用于判断哪些词元对搜索有意义的词典。 - 如果只指定了解析器,那么新文本搜索配置最初没有从记号类型到词典的映射, + 如果只指定了解析器,那么新文本检索配置最初没有从词元类型到词典的映射, 因而会忽略所有词。要让该配置真正可用,必须使用后续的ALTER TEXT SEARCH CONFIGURATION命令创建映射。 - 另一种方式是复制一个现有的文本搜索配置。 + 另一种方式是复制一个现有的文本检索配置。 - 如果给出了一个模式名称,则文本搜索配置会被创建在指定的模式中。否则它将会 + 如果给出了一个模式名称,则文本检索配置会被创建在指定的模式中。否则它将会 被创建在当前模式中。 - 定义该文本搜索配置的用户会成为其拥有者。 + 定义该文本检索配置的用户会成为其拥有者。 @@ -66,7 +66,7 @@ CREATE TEXT SEARCH CONFIGURATION namename - 要创建的文本搜索配置的名称。该名称可以是模式限定的。 + 要创建的文本检索配置的名称。该名称可以是模式限定的。 @@ -75,7 +75,7 @@ CREATE TEXT SEARCH CONFIGURATION nameparser_name - 此配置要使用的文本搜索解析器的名称。 + 此配置要使用的文本检索解析器的名称。 @@ -84,7 +84,7 @@ CREATE TEXT SEARCH CONFIGURATION namesource_config - 要复制的现有文本搜索配置的名称。 + 要复制的现有文本检索配置的名称。 diff --git a/zh/14/ref/create_tsdictionary.sgml b/zh/14/ref/create_tsdictionary.sgml index c45a7240..823710b7 100644 --- a/zh/14/ref/create_tsdictionary.sgml +++ b/zh/14/ref/create_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH DICTIONARY - 定义一个新的文本搜索字典 + 定义一个新的文本检索词典 @@ -33,19 +33,19 @@ CREATE TEXT SEARCH DICTIONARY name CREATE TEXT SEARCH DICTIONARY创建一个 - 新的文本搜索字典。文本搜索字典指定一种在搜索时识别哪些词值得关注、 - 哪些词不值得关注的方式。字典依赖于文本搜索模板,后者规定了实际执行 - 这项工作的函数。通常,字典会提供一些选项,用来控制模板函数的具体 + 新的文本检索词典。文本检索词典指定一种在搜索时识别哪些词值得关注、 + 哪些词不值得关注的方式。词典依赖于文本检索模板,后者规定了实际执行 + 这项工作的函数。通常,词典会提供一些选项,用来控制模板函数的具体 行为。 - 如果给出了一个模式名称,那么该文本搜索字典会被创建在指定的模式中。 + 如果给出了一个模式名称,那么该文本检索词典会被创建在指定的模式中。 否则它会被创建在当前模式中。 - 定义文本搜索字典的用户将成为其拥有者。 + 定义文本检索词典的用户将成为其拥有者。 @@ -61,7 +61,7 @@ CREATE TEXT SEARCH DICTIONARY name name - 要创建的文本搜索字典的名称。该名称可以被模式限定。 + 要创建的文本检索词典的名称。该名称可以被模式限定。 @@ -70,7 +70,7 @@ CREATE TEXT SEARCH DICTIONARY name template - 用于定义该字典基本行为的文本搜索模板名称。 + 用于定义该词典基本行为的文本检索模板名称。 @@ -79,7 +79,7 @@ CREATE TEXT SEARCH DICTIONARY name option - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -105,7 +105,7 @@ CREATE TEXT SEARCH DICTIONARY name 下面的示例命令创建了一个基于 Snowball 且使用非标准停用词列表的 - 字典。 + 词典。 diff --git a/zh/14/ref/create_tsparser.sgml b/zh/14/ref/create_tsparser.sgml index 358152ce..88be54e6 100644 --- a/zh/14/ref/create_tsparser.sgml +++ b/zh/14/ref/create_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH PARSER - 定义一个新的全文检索解析器 + 定义一个新的文本检索解析器 @@ -36,19 +36,19 @@ CREATE TEXT SEARCH PARSER name ( CREATE TEXT SEARCH PARSER创建一个 - 新的全文检索解析器。全文检索解析器定义了一种方法,用于将文本字符串 - 拆分成记号并为这些记号指定类型(类别)。解析器本身并没有太大用处, - 必须与一些全文检索字典一起绑定到一个全文检索配置中,才能用于搜索。 + 新的文本检索解析器。文本检索解析器定义了一种方法,用于将文本字符串 + 拆分成词元并为这些词元指定类型(类别)。解析器本身并没有太大用处, + 必须与一些文本检索词典一起绑定到一个文本检索配置中,才能用于搜索。 - 如果给出了一个模式名称,那么全文检索解析器将被创建在指定的模式中。 + 如果给出了一个模式名称,那么文本检索解析器将被创建在指定的模式中。 否则它会被创建在当前模式中。 要使用CREATE TEXT SEARCH PARSER,你必须是超级用户。 - 之所以有此限制,是因为错误的全文检索解析器定义可能会让服务器陷入 + 之所以有此限制,是因为错误的文本检索解析器定义可能会让服务器陷入 混乱,甚至崩溃。 @@ -65,7 +65,7 @@ CREATE TEXT SEARCH PARSER name ( name - 要创建的全文检索解析器的名称。该名称可以是模式限定的。 + 要创建的文本检索解析器的名称。该名称可以是模式限定的。 @@ -83,7 +83,7 @@ CREATE TEXT SEARCH PARSER name ( gettoken_function - 该解析器的获取下一个记号的函数名称。 + 该解析器的获取下一个词元的函数名称。 @@ -101,7 +101,7 @@ CREATE TEXT SEARCH PARSER name ( lextypes_function - 该解析器的 lextypes 函数的名称(该函数返回它所产生的记号类型集合的 + 该解析器的 lextypes 函数的名称(该函数返回它所产生的词元类型集合的 信息)。 @@ -111,7 +111,7 @@ CREATE TEXT SEARCH PARSER name ( headline_function - 该解析器的 headline 函数的名称(该函数对一组记号生成摘要)。 + 该解析器的 headline 函数的名称(该函数对一组词元生成摘要)。 diff --git a/zh/14/ref/create_tstemplate.sgml b/zh/14/ref/create_tstemplate.sgml index 702233e4..0f1b4e1a 100644 --- a/zh/14/ref/create_tstemplate.sgml +++ b/zh/14/ref/create_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH TEMPLATE - 定义一个新的全文检索模板 + 定义一个新的文本检索模板 @@ -33,22 +33,22 @@ CREATE TEXT SEARCH TEMPLATE name ( CREATE TEXT SEARCH TEMPLATE创建一个 - 新的全文检索模板。全文检索模板定义实现全文检索字典的函数。模板本身 - 并无直接用途,必须先实例化为字典后才能使用。字典通常会指定要传递给 + 新的文本检索模板。文本检索模板定义实现文本检索词典的函数。模板本身 + 并无直接用途,必须先实例化为词典后才能使用。词典通常会指定要传递给 模板函数的参数。 - 如果给出了模式名称,则全文检索模板会被创建在指定模式中。否则它会被 + 如果给出了模式名称,则文本检索模板会被创建在指定模式中。否则它会被 创建在当前模式中。 要使用CREATE TEXT SEARCH TEMPLATE,你 - 必须是超级用户。之所以有此限制,是因为错误的全文检索模板定义可能使 - 服务器陷入混乱,甚至崩溃。将模板与字典分离的原因在于,模板封装了定 - 义字典时那些不安全的方面。而在定义字典时可设置的参数, - 对非特权用户来说是安全的,因此创建字典不必是特权操作。 + 必须是超级用户。之所以有此限制,是因为错误的文本检索模板定义可能使 + 服务器陷入混乱,甚至崩溃。将模板与词典分离的原因在于,模板封装了定 + 义词典时那些不安全的方面。而在定义词典时可设置的参数, + 由普通用户设置也是安全的,因此创建词典不必是特权操作。 @@ -64,7 +64,7 @@ CREATE TEXT SEARCH TEMPLATE name ( name - 要创建的全文检索模板名称。该名称可以是模式限定的。 + 要创建的文本检索模板名称。该名称可以是模式限定的。 diff --git a/zh/14/ref/drop_opclass.sgml b/zh/14/ref/drop_opclass.sgml index 9d67dc64..545a2517 100644 --- a/zh/14/ref/drop_opclass.sgml +++ b/zh/14/ref/drop_opclass.sgml @@ -110,7 +110,7 @@ DROP OPERATOR CLASS [ IF EXISTS ] name示例 - 移除 B-tree 操作符类widget_ops: + 移除 B-树操作符类widget_ops DROP OPERATOR CLASS widget_ops USING btree; diff --git a/zh/14/ref/drop_tsconfig.sgml b/zh/14/ref/drop_tsconfig.sgml index ea139802..b3ebb9d1 100644 --- a/zh/14/ref/drop_tsconfig.sgml +++ b/zh/14/ref/drop_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH CONFIGURATION - 移除一个文本搜索配置 + 移除一个文本检索配置 @@ -29,7 +29,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 描述 - DROP TEXT SEARCH CONFIGURATION删除一个现有文本搜索配置。 + DROP TEXT SEARCH CONFIGURATION删除一个现有文本检索配置。 要执行此命令,你必须是该配置的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name IF EXISTS - 如果该文本搜索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name name - 现有文本搜索配置的名称(可以被模式限定)。 + 现有文本检索配置的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name CASCADE - 自动删除依赖于该文本搜索配置的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索配置的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name RESTRICT - 如果有任何对象依赖于该文本搜索配置,则拒绝删除该配置。这是默认值。 + 如果有任何对象依赖于该文本检索配置,则拒绝删除该配置。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 示例 - 移除文本搜索配置my_english: + 移除文本检索配置my_english DROP TEXT SEARCH CONFIGURATION my_english; 如果已有索引在to_tsvector调用中引用了该配置, - 此命令将不会成功。加上CASCADE可以在删除该文本搜索配置的同时删除这类索引。 + 此命令将不会成功。加上CASCADE可以在删除该文本检索配置的同时删除这类索引。 diff --git a/zh/14/ref/drop_tsdictionary.sgml b/zh/14/ref/drop_tsdictionary.sgml index 316c5d00..0f7751a1 100644 --- a/zh/14/ref/drop_tsdictionary.sgml +++ b/zh/14/ref/drop_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH DICTIONARY - 移除一个文本搜索字典 + 移除一个文本检索词典 @@ -29,8 +29,8 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name描述 - DROP TEXT SEARCH DICTIONARY删除一个现有文本搜索字典。 - 要执行此命令,你必须是该字典的拥有者。 + DROP TEXT SEARCH DICTIONARY删除一个现有文本检索词典。 + 要执行此命令,你必须是该词典的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索字典不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索词典不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] namename - 一个现有文本搜索字典的名称(可以被模式限定)。 + 一个现有文本检索词典的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索字典的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索词典的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索字典,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索词典,则拒绝删除它。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name示例 - 移除文本搜索字典english: + 移除文本检索词典english DROP TEXT SEARCH DICTIONARY english; - 如果已有文本搜索配置使用该字典,此命令将不会成功。 - 加上CASCADE可以在删除字典的同时删除这类配置。 + 如果已有文本检索配置使用该词典,此命令将不会成功。 + 加上CASCADE可以在删除词典的同时删除这类配置。 diff --git a/zh/14/ref/drop_tsparser.sgml b/zh/14/ref/drop_tsparser.sgml index a65f47be..ea74f0f8 100644 --- a/zh/14/ref/drop_tsparser.sgml +++ b/zh/14/ref/drop_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH PARSER - 移除一个文本搜索解析器 + 移除一个文本检索解析器 @@ -29,7 +29,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name描述 - DROP TEXT SEARCH PARSER删除一个现有文本搜索解析器。 + DROP TEXT SEARCH PARSER删除一个现有文本检索解析器。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] namename - 一个现有文本搜索解析器的名称(可以被模式限定)。 + 一个现有文本检索解析器的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索解析器的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索解析器的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索解析器,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索解析器,则拒绝删除它。这是默认值。 @@ -82,13 +82,13 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name示例 - 移除文本搜索解析器my_parser: + 移除文本检索解析器my_parser DROP TEXT SEARCH PARSER my_parser; - 如果已有文本搜索配置使用该解析器,此命令将不会成功。 + 如果已有文本检索配置使用该解析器,此命令将不会成功。 加上CASCADE可以在删除解析器的同时删除这类配置。 diff --git a/zh/14/ref/drop_tstemplate.sgml b/zh/14/ref/drop_tstemplate.sgml index fa1faab0..3a44c927 100644 --- a/zh/14/ref/drop_tstemplate.sgml +++ b/zh/14/ref/drop_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH TEMPLATE - 移除一个文本搜索模板 + 移除一个文本检索模板 @@ -29,7 +29,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name描述 - DROP TEXT SEARCH TEMPLATE删除一个现有文本搜索模板。 + DROP TEXT SEARCH TEMPLATE删除一个现有文本检索模板。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] namename - 现有文本搜索模板的名称(可以被模式限定)。 + 现有文本检索模板的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索模板的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索模板的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索模板,则拒绝删除该模板。这是默认值。 + 如果有任何对象依赖于该文本检索模板,则拒绝删除该模板。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name示例 - 移除文本搜索模板thesaurus: + 移除文本检索模板thesaurus DROP TEXT SEARCH TEMPLATE thesaurus; - 如果已有文本搜索字典使用该模板,此命令将不会成功。加上CASCADE - 可以在删除该模板的同时删除这类字典。 + 如果已有文本检索词典使用该模板,此命令将不会成功。加上CASCADE + 可以在删除该模板的同时删除这类词典。 diff --git a/zh/14/ref/initdb.sgml b/zh/14/ref/initdb.sgml index 134e90ed..7b7d4b87 100644 --- a/zh/14/ref/initdb.sgml +++ b/zh/14/ref/initdb.sgml @@ -36,22 +36,11 @@ PostgreSQL documentation 描述 - initdb创建一个新的PostgreSQL - 数据库集簇。 + initdb创建一个新的PostgreSQL数据库集簇。数据库集簇是由单个服务器实例管理的一组数据库。 - 创建数据库集簇包括创建用于存放集簇数据的 - 目录, - 生成共享系统目录表(属于整个集簇而不是某个特定数据库的表),以及创建 - postgrestemplate1 和 - template0 数据库。postgres - 数据库是一个默认数据库,供用户、工具程序和第三方应用程序使用。 - template1template0 - 用作后续CREATE DATABASE命令复制的源数据库。 - template0 不应被修改,但可以向 - template1 中添加对象,这些对象默认会被复制到以后创建的数据库中。 - 更多细节见。 + 创建数据库集簇包括创建用于存放数据库数据的目录,生成共享系统目录表(属于整个集簇而不是某个特定数据库的表),以及创建template1postgres数据库。以后创建新数据库时,会复制template1数据库中的所有内容。(因此,安装在template1中的任何东西都会自动复制到以后创建的每个数据库中。)postgres数据库是一个默认数据库,供用户、工具程序和第三方应用程序使用。 @@ -102,19 +91,11 @@ PostgreSQL documentation - 该选项指定pg_hba.conf中本地用户默认使用的认证方法 - (hostlocal 行)。有效值概览见 - 。 + 此选项指定pg_hba.conf中本地用户使用的默认认证方法(hostlocal行)。initdb会使用指定的认证方法,为非复制连接和复制连接预先填充pg_hba.conf条目。 - initdb会使用指定的认证方法预填充pg_hba.conf - 条目,既用于非复制连接,也用于复制连接。 - - - - 除非信任系统上的所有本地用户,否则不要使用trust。 - 为了便于安装,默认使用trust。 + 除非信任系统上的所有本地用户,否则不要使用trust。为便于安装,默认值为trust @@ -161,7 +142,7 @@ PostgreSQL documentation - + @@ -173,25 +154,16 @@ PostgreSQL documentation - - - - - + - 对数据页启用校验和,以帮助检测原本会悄无声息发生的、由 I/O 系统导致的损坏。 - 该项默认启用;使用可禁用校验和。 - - - - 启用校验和可能会带来小幅性能损失。如果启用,就会为所有数据库中的所有对象计算校验和。 - 所有校验和失败都会在 - - pg_stat_database视图中报告。详见 - 。 + 在数据页上使用校验和,帮助检测 I/O 系统造成的、否则可能悄无声息的数据损坏。 + 启用校验和可能会带来明显的性能损失。如果启用,就会为所有数据库中的所有对象计算校验和。 + 所有校验和失败都会在 + pg_stat_database视图中报告。 + 详见 @@ -231,15 +203,25 @@ PostgreSQL documentation + + + + + + 默认情况下,initdb会等待所有文件都安全写入磁盘。该选项使 + initdb在不等待的情况下返回,速度更快,但这意味着如果后续操作系统崩溃, + 数据目录可能会损坏。通常,该选项适用于测试,但不应用于创建生产环境安装。 + + + - - - - - + + - 不启用数据校验和。 + 默认情况下,initdb会在其输出末尾写出如何启动集簇的说明。 + 该选项会省略这些说明。它主要供那些对initdb进行平台特定封装的工具使用, + 因为在这种情况下那些说明很可能并不正确。 @@ -248,7 +230,17 @@ PostgreSQL documentation - 使initdb从文件中读取引导超级用户的密码。文件的第一行会被当作密码。 + 使initdb从文件中读取数据库超级用户的密码。文件的第一行会被当作密码。 + + + + + + + + + + 将所有数据库文件安全写入磁盘,然后退出。这不会执行任何常规initdb操作。 @@ -258,7 +250,7 @@ PostgreSQL documentation - 设置默认文本搜索配置。更多信息见 + 设置默认文本检索配置。更多信息见 @@ -269,10 +261,9 @@ PostgreSQL documentation - 选择数据库超级用户的用户名。默认值是运行 - initdb的实际用户名称。超级用户的名称本身 - 并不重要,不过即使操作系统用户名称不同,人们也可能选择沿用惯常 - 的名称postgres。 + 选择数据库超级用户的用户名。默认值是运行initdb的有效用户的名称。 + 超级用户的名称本身并不重要,不过即使操作系统用户名称不同,也可以选择沿用惯常的名称 + postgres @@ -282,7 +273,7 @@ PostgreSQL documentation - 使initdb提示输入要赋给引导超级用户的密码。如果不打算使用密码认证, + 使initdb提示输入要赋给数据库超级用户的密码。如果不打算使用密码认证, 这一点并不重要。否则,在设置密码之前将无法使用密码认证。 @@ -320,19 +311,6 @@ PostgreSQL documentation 还提供了其他一些较少使用的选项: - - - - - - 在initdb期间,强制将服务器参数name - 设为value,并把该设置写入生成的 - postgresql.conf文件,以便在今后的服务器运行中生效。 - 该选项可指定多次,以设置多个参数。它主要用于默认参数下服务器根本无法启动的环境。 - - - - @@ -374,91 +352,6 @@ PostgreSQL documentation - - - - - - - 默认情况下,initdb会等待所有文件都安全写入磁盘。该选项使 - initdb在不等待的情况下返回,速度更快,但这意味着如果后续操作系统崩溃, - 数据目录可能会损坏。通常,该选项适用于测试,但不应用于创建生产环境安装。 - - - - - - - - - 默认情况下,initdb会将所有数据库文件安全地写入磁盘。 - 该选项指示initdb跳过同步各个数据库目录中的所有文件、这些数据库目录本身 - 以及表空间目录,也就是base子目录中的所有内容和任何其他表空间目录。 - 其他文件,例如pg_walpg_xact中的文件, - 仍会被同步,除非也指定了。 - - - 请注意,如果与 - 一起使用,上述部分或全部文件与目录仍会被同步, - 因为syncfs处理的是整个文件系统。 - - - 该选项主要供那些会另行确保这些被跳过文件已同步到磁盘的工具在内部使用。 - - - - - - - - - 默认情况下,initdb会在其输出末尾写出如何启动集簇的说明。 - 该选项会省略这些说明。它主要供那些对initdb进行平台特定封装的工具使用, - 因为在这种情况下那些说明很可能并不正确。 - - - - - - - - - - 显示内部设置并退出,不执行其他操作。可用于调试initdb的安装。 - - - - - - - - - 设为fsync(默认值)时,initdb会递归打开并同步 - 数据目录中的所有文件。查找文件时会跟随 WAL 目录和每个已配置表空间的符号链接。 - - - 在 Linux 上,也可以改用syncfs,请求操作系统同步包含数据目录、 - WAL 文件以及每个表空间的整个文件系统。使用syncfs时需注意的事项见 - 。 - - - 使用时,该选项不起作用。 - - - - - - - - - - 将所有数据库文件安全地写入磁盘并退出。这不会执行任何常规的 - initdb操作。通常,该选项可用于在将 - off改为on后, - 确保能够可靠恢复。 - - - @@ -543,7 +436,6 @@ PostgreSQL documentation - diff --git a/zh/14/ref/pgbench.sgml b/zh/14/ref/pgbench.sgml index e0fa9e55..9ff57b13 100644 --- a/zh/14/ref/pgbench.sgml +++ b/zh/14/ref/pgbench.sgml @@ -39,37 +39,29 @@ PostgreSQL documentation 描述 - pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,必要时可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 + pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,也可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 典型的pgbench输出如下: - transaction type: <builtin: TPC-B (sort of)> scaling factor: 10 query mode: simple number of clients: 10 number of threads: 1 -maximum number of tries: 1 number of transactions per client: 1000 number of transactions actually processed: 10000/10000 -number of failed transactions: 0 (0.000%) latency average = 11.013 ms latency stddev = 7.351 ms initial connection time = 45.758 ms tps = 896.967014 (without initial connection time) - - 前七行给出了若干最重要的参数设置。 - 第六行报告了出现串行化或死锁错误时事务允许的最大尝试次数(更多信息见)。 - 第八行报告实际完成的事务数和预期事务数(后者仅为客户端数量与每个客户端事务数的乘积);除非运行在完成前失败,或者某些 SQL 命令执行失败,否则两者应当相等。(在模式下,只打印实际事务数。) - 下一行报告因串行化或死锁错误而失败的事务数(更多信息见)。 - 最后一行报告每秒事务数。 +前六行给出了若干最重要的参数设置。下一行报告实际完成的事务数和预期事务数(后者仅为客户端数量与每个客户端事务数的乘积);除非运行在完成前失败,否则两者应当相等。(在模式下,只打印实际事务数。)最后一行报告每秒事务数。 - 默认的类 TPC-B 事务测试要求预先建立特定的表。应使用(initialize)选项调用pgbench来创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: + 默认的类 TPC-B 事务测试要求预先建立特定的表。应使用(初始化)选项调用pgbench来创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: pgbench -i other-options dbname @@ -89,14 +81,14 @@ pgbench -i other-options 在默认的比例因子 1 下,这些表最初包含如下行数: -table # of rows +表 行数 --------------------------------- pgbench_branches 1 pgbench_tellers 10 pgbench_accounts 100000 pgbench_history 0 - 可以使用(比例因子)选项来增加行数,而且在大多数场景下也确实应该这样做。此时还可以配合使用(fillfactor)选项。 + 可以使用(比例因子)选项来增加行数,而且在大多数场景下通常也应该这样做。此时还可以配合使用(fillfactor)选项。 @@ -116,7 +108,7 @@ pgbench options d 选项 - 下面分成三个部分。数据库初始化期间使用的选项和运行基准时会使用不同的选项,但也有一些选项在两种情况下都使用。 + 以下内容分为三个小节。数据库初始化和运行基准测试时使用不同的选项,但有些选项在这两种情况下都适用。 @@ -129,8 +121,7 @@ pgbench options d - - + dbname @@ -155,15 +146,11 @@ pgbench options d - - 仅执行正常初始化步骤中的选定部分。 - init_steps指定要执行的初始化步骤,每个步骤用一个字符表示。 - 各步骤会按照指定顺序调用。 - 默认值为dtgvp。 - 可用步骤如下: + 仅执行选定的常规初始化步骤。 + init_steps 指定要执行的初始化步骤,每个步骤用一个字符表示。各步骤按照指定顺序调用。默认值为 dtgvp。可用步骤如下: - + d(删除) @@ -191,12 +178,12 @@ pgbench options d 生成数据并将其装载到标准表中,替换其中任何已有数据。 - 使用g(客户端生成数据)时,数据由pgbench客户端生成,再通过COPY发送到服务器,因此会大量占用客户端/服务器带宽。对于 14 及以上版本的PostgreSQLpgbench会在普通(非分区)表上使用选项装载数据,以加快后续的VACUUM。使用g时,在为所有表生成数据的过程中,每生成 100,000 行会输出一条日志消息。 + 使用g(客户端生成数据)时,数据由pgbench客户端生成,再通过COPY发送到服务器,因此会大量占用客户端/服务器带宽。使用g时,在为pgbench_accounts表生成数据的过程中,每生成 100,000 行会输出一条日志消息。 使用G(服务器端生成数据)时, pgbench客户端只发送较小的查询,随后实际数据在服务器端生成。 - 这种方式几乎不需要额外带宽,但服务器会承担更多工作。 + 这种方式不需要大量带宽,但服务器会承担更多工作。 使用G时,生成数据期间不会打印任何进度消息。 @@ -416,6 +403,16 @@ pgbench options d + + + + + + 打印调试输出。 + + + + varname=value varname=value @@ -476,23 +473,13 @@ pgbench options d limit limit - 持续时间超过limit毫秒的事务会被单独计数和报告,称为late - 使用限流()时,若某个事务落后于计划时间超过limit毫秒, 从而已经不可能满足延迟限制,则它根本不会被发送到服务器。此类事务会被单独计数并报告为skipped - - - 使用选项时,若某个事务因串行化异常或死锁而失败, - 且其所有尝试的总耗时大于limit毫秒,则不会再重试。 - 若只想限制尝试总时间而不限制尝试次数,请使用--max-tries=0。 - 默认情况下,为 1,出现串行化/死锁错误的事务不会重试。 - 有关此类事务重试的更多信息,见。 - @@ -505,13 +492,13 @@ pgbench options d 用于向服务器提交查询的协议: - simple: 使用简单查询协议。 + simple:使用简单查询协议。 - extended: 使用扩展查询协议。 + extended:使用扩展查询协议。 - prepared: 使用带有预备语句的扩展查询协议。 + prepared:使用带有预备语句的扩展查询协议。 @@ -556,23 +543,18 @@ pgbench options d sec sec - - 每sec秒显示一次进度报告。报告包括自运行开始以来的时间、自上次报告以来的 TPS、 - 自上次报告以来事务延迟的平均值和标准差,以及失败事务数。使用限流()时, - 延迟是相对于事务计划开始时间计算的,而不是实际开始时间,因此其中也包含平均计划滞后时间。 - 当使用启用事务在串行化/死锁错误后的重试时,报告还会包含发生过重试的事务数以及总重试次数。 + 每sec秒显示一次进度报告。报告包括自运行开始以来的时间、自上次报告以来的 TPS,以及自上次报告以来事务延迟的平均值和标准差。使用限流()时,延迟是相对于事务计划开始时间计算的,而不是实际开始时间,因此其中也包含平均计划滞后时间。 - + - - 在基准测试完成后,报告每条语句的以下统计信息:平均延迟(从客户端视角看到的语句执行时间)、失败次数,以及该语句因串行化或死锁错误而发生的重试次数。仅当选项不等于 1 时,报告才会显示重试统计信息。 + 在基准测试完成后,报告每条命令的平均语句延迟(从客户端视角看到的执行时间)。详情见下文。 @@ -607,7 +589,7 @@ pgbench options d 较高的计划滞后时间表明,在所选客户端数和线程数下,系统无法以指定速率处理事务。 当平均事务执行时间长于事务之间的计划间隔时,后续事务会不断进一步落后, - 而计划滞后时间也会随着测试持续时间增加。在这种情况下,只能降低指定的事务速率。 + 而计划滞后时间也会随着测试持续时间增加。在这种情况下,需要降低指定的事务速率。 @@ -619,7 +601,7 @@ pgbench options d pgbench输出中报告指定的比例因子。 - 对于内置测试,这通常没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 + 对于内置测试,这没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 但在只测试自定义基准(选项)时, 除非使用此选项,否则比例因子会被报告为 1。 @@ -686,36 +668,9 @@ pgbench options d - - - - - 当任一客户端因错误被中止时,立即退出。如果不指定该选项,即使某个客户端被中止,其他客户端仍可按的设定继续运行,此时pgbench会输出不完整的结果。 - - - 请注意,串行化失败或死锁失败不会中止客户端,因此不受该选项影响。更多信息见 。 - - - - - - - - 在逐事务日志、聚合日志以及主报告和逐脚本报告中,按以下类型分组报告失败: - - - 串行化失败; - - - 死锁失败; - - - 更多信息见。 - - - + @@ -727,20 +682,7 @@ pgbench options d - - - - - 启用对出现串行化/死锁错误的事务进行重试,并设置最大尝试次数。此选项可与 - 组合使用,后者限制所有事务尝试的总耗时; - 此外,如果没有, - 则不能使用无限次尝试(--max-tries=0)。 - 默认值为 1,出现串行化/死锁错误的事务不会重试。有关此类事务重试的更多信息,见 - 。 - - - @@ -808,15 +750,7 @@ pgbench options d - - - - - 打印关于所有错误和失败的消息(即不会重试的错误),包括超出了哪一种重试限制,以及对于串行化/死锁失败超出的幅度。(请注意,这种情况下输出量可能会显著增加。)更多信息见。 - - - @@ -828,18 +762,11 @@ pgbench options d 公共选项 - pgbench 还接受以下用于连接参数及其他通用设置的命令行参数: + pgbench 还接受以下用于连接参数的通用命令行参数: - - - - - 打印调试输出。 - - - + hostname @@ -901,9 +828,7 @@ pgbench options d 退出状态 - 成功运行会以状态 0 退出。状态 1 表示静态问题,例如无效的命令行选项,或者按理不应发生的内部错误。 - 在启动基准测试时发生的早期错误,例如初始连接失败,也会以状态 1 退出。 - 运行过程中出现的错误,例如数据库错误或脚本中的问题,会导致退出状态 2。在后一种情况下,如果未指定pgbench会打印部分结果。 + 成功运行会以状态 0 退出。退出状态 1 表示静态问题,例如无效的命令行选项。运行过程中出现的错误,例如数据库错误或脚本中的问题,会导致退出状态 2。在后一种情况下,pgbench会打印部分结果。 @@ -941,7 +866,7 @@ pgbench options d 注解 - + 在<application>pgbench</application>中实际执行的<quote>事务</quote>是什么? @@ -995,9 +920,7 @@ pgbench options d 在PostgreSQL 9.6 之前,脚本文件中的 SQL 命令以换行结束,因此不能跨行。现在连续 SQL 命令之间必须用分号分隔(如果 SQL 命令后面跟着一个元命令,则不需要分号)。如果需要创建一个既能在旧版也能在新版pgbench下工作的脚本文件,务必将每个 SQL 命令写在单独一行,并以分号结束。 - - 假定pgbench脚本不包含不完整的 SQL 事务块。如果在运行时客户端在尚未完成最后一个事务块时就到达脚本末尾,它将被中止。 - + @@ -1033,7 +956,7 @@ pgbench options d default_seed - 默认在哈希和伪随机置换函数中使用的种子 + 默认在 hash 和伪随机置换函数中使用的种子 @@ -1050,7 +973,7 @@ pgbench options d - 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令及其参数之间以空白分隔。支持的元命令如下: + 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令的参数以空白分隔。支持的元命令如下: @@ -1088,7 +1011,7 @@ UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid RETURNING abalance \gset --- compound of two queries +-- 两个查询的组合 SELECT 1 \; SELECT 2 AS two, 3 AS three \gset p_ SELECT 4 AS four \; SELECT 5 AS five \aset @@ -1180,7 +1103,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset - command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在其开头再写一个冒号。 + command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在argument开头再写一个冒号。 @@ -1212,13 +1135,13 @@ SELECT 4 AS four \; SELECT 5 AS five \aset \startpipeline - \syncpipeline + \endpipeline - 这组命令用于实现 SQL 语句的流水线执行。流水线必须以\startpipeline开始,并以\endpipeline结束;在两者之间可以出现任意数量的\syncpipeline,它会发送一个sync 消息,但不会结束当前流水线,同时会刷新发送缓冲区。在流水线模式下,语句会发送到服务器,而不等待前一条语句的结果。更多细节见。流水线模式要求使用扩展查询协议。 + 这些命令界定 SQL 语句管道的开始和结束。在管道模式下,语句会发送到服务器,而不等待前一条语句的结果。更多细节见。管道模式要求使用扩展查询协议。 @@ -1514,7 +1437,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 加 + 加法 5 + 4 @@ -1528,7 +1451,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 减 + 减法 3 - 2.0 @@ -1542,7 +1465,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 乘 + 乘法 5 * 4 @@ -1556,7 +1479,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 除法(如果两个输入都是整数,则将结果截断为零) + 除法(如果两个输入都是整数,则将结果向零截断) 5 / 3 @@ -1584,7 +1507,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 取反 + 取相反数 - 2.0 @@ -1674,7 +1597,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset double - 指数(e 的给定次幂) + 指数函数(e 的给定次幂) exp(1.0) @@ -1716,7 +1639,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算 FNV-1a 哈希。 + 计算 FNV-1a hash hash_fnv1a(10, 5432) @@ -1730,7 +1653,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算 MurmurHash2 哈希。 + 计算 MurmurHash2 hash hash_murmur2(10, 5432) @@ -1800,8 +1723,8 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - i的排列值,范围在[0, size)内。 - 它表示i(模size)在整数0...size-1的伪随机排列中的新位置;该排列由seed参数化,详见下文。 + i的置换值,范围在[0, size)内。 + 它表示i(模size)在整数0...size-1的伪随机置换中的新位置;该置换由seed参数化,详见下文。 permute(0, 4) @@ -1861,7 +1784,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算[lb, ub]中的指数分布随机整数,如下所示。 + 计算[lb, ub]中的指数分布随机整数,详见下文。 random_exponential(1, 10, 3.0) @@ -1875,7 +1798,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算[lb, ub]中的高斯分布随机整数,如下所示。 + 计算[lb, ub]中的高斯分布随机整数,详见下文。 random_gaussian(1, 10, 2.5) @@ -1922,7 +1845,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset - 对于指数分布,parameter通过在parameter处截断一个快速衰减的指数分布,再将其投影到边界之间的整数上,从而控制分布。准确地说, + 对于指数分布,parameter通过在parameter处截断一个快速衰减的指数分布,再将其投影到边界之间的整数上,从而控制分布。准确地说,令 f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) @@ -1930,7 +1853,7 @@ f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) - 直观地说,parameter越大,越靠近min的值越容易被抽到,而越靠近max的值越不容易被抽到。parameter越接近 0,分布就越平坦(也就越均匀)。对这种分布的一个粗略近似是:范围内最靠近min的那 1% 常见值,大约会占到parameter% 的抽样次数。parameter必须严格大于 0。 + 直观地说,parameter越大,越靠近min的值越容易被抽到,而越靠近max的值越不容易被抽到。parameter越接近 0,分布就越平坦(也就越均匀)。对这种分布的一个粗略近似是:范围内出现频率最高的 1% 的值,即最靠近min的那些值,大约会占到parameter% 的抽样次数。parameter必须严格大于 0。 @@ -1942,7 +1865,7 @@ f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / (2.0 * PHI(parameter) - 1) - 则minmax(包含边界)之间的值i被抽中的概率为:f(i + 0.5) - f(i - 0.5)。直观地说,parameter越大,越靠近区间中间的值被抽到的频率越高,而越靠近minmax边界的值被抽到的频率越低。大约 67% 的值会落在区间中部1.0 / parameter这一段内,也就是均值两侧各0.5 / parameter的范围内;约 95% 的值会落在区间中部2.0 / parameter这一段内,也就是均值两侧各1.0 / parameter的范围内。例如,如果parameter为 4.0,则 67% 的值会落在区间中间四分之一(1.0 / 4.0)内,也就是从3.0 / 8.05.0 / 8.0;95% 的值会落在区间中间一半(2.0 / 4.0)内,也就是第二和第三四分位。允许的最小parameter值为 2.0。 + 则minmax(包含边界)之间的值i被抽中的概率为:f(i + 0.5) - f(i - 0.5)。直观地说,parameter越大,越靠近区间中间的值被抽到的频率越高,而越靠近minmax边界的值被抽到的频率越低。大约 67% 的值会落在区间中部1.0 / parameter这一段内,也就是均值两侧各占区间长度0.5 / parameter的范围内;约 95% 的值会落在区间中部2.0 / parameter这一段内,也就是均值两侧各占区间长度1.0 / parameter的范围内。例如,如果parameter为 4.0,则 67% 的值会落在区间中间四分之一(1.0 / 4.0)内,也就是从3.0 / 8.05.0 / 8.0;95% 的值会落在区间中间一半(2.0 / 4.0)内,也就是第二和第三四分位。允许的最小parameter值为 2.0。 @@ -1974,12 +1897,12 @@ f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / - 哈希函数hashhash_murmur2hash_fnv1a都接受一个输入值和一个可选的种子参数。 - 如果没有提供种子,则会使用:default_seed的值;除非通过命令行选项覆盖,否则该值会被随机初始化。 + Hash 函数hashhash_murmur2hash_fnv1a都接受一个输入值和一个可选的种子参数。 + 如果没有提供种子,则会使用:default_seed的值;除非通过命令行-D选项覆盖,否则该值会被随机初始化。 - permute接受一个输入值、一个大小参数以及一个可选的种子参数。它会生成范围[0, size)内整数的伪随机排列,并返回输入值在该排列中的索引。如果未指定种子,则默认使用:default_seed。与哈希函数不同,permute保证输出值中不会出现冲突或空洞。区间之外的输入值会按size取模解释。如果size不是正数,该函数会报错。permute可用于打散诸如random_zipfianrandom_exponential这类非均匀随机函数的分布,使那些更常抽到的值不再具有显而易见的相关性。例如,下面的pgbench脚本模拟了社交媒体和博客平台中一种可能的真实工作负载,其中少数账户会产生过量负载: + permute接受一个输入值、一个大小参数以及一个可选的种子参数。它会生成范围[0, size)内整数的伪随机置换,并返回输入值在该置换中的索引。所选置换由种子参数决定;如果未指定种子,则默认使用:default_seed。与 hash 函数不同,permute保证输出值中不会出现冲突或空洞。区间之外的输入值会按size取模解释。如果size不是正数,该函数会报错。permute可用于打散诸如random_zipfianrandom_exponential这类非均匀随机函数的分布,使那些更常抽到的值不再具有显而易见的相关性。例如,下面的pgbench脚本模拟了社交媒体和博客平台中一种可能的真实工作负载,其中少数账户会产生过量负载: \set size 1000000 @@ -2028,7 +1951,6 @@ END; - 逐事务日志记录 @@ -2036,92 +1958,19 @@ END; - 每行日志文件描述一个事务。 - 它包含以下以空格分隔的字段: - - - - client_id - - - 标识运行事务的客户端会话 - - - - - - transaction_no - - - 统计该会话已执行的事务数量 - - - - - - time - - - 事务耗时,单位为微秒 - - - - - - script_no - - - 标识该事务所使用的脚本文件 - (当通过指定多个脚本时很有用) - - - - - - time_epoch - - - 事务完成时间,以 Unix 纪元时间戳表示 - - - - - - time_us - - - 事务完成时间的小数秒部分,以微秒为单位 - - - - - - schedule_lag - - - 事务开始延迟,即事务计划开始时间与实际开始时间之间的差值,单位为微秒 - (仅在指定时出现) - - - - - - retries - - - 该事务在发生串行化或死锁错误后的重试次数 - (仅当不等于 1 时出现) - - - - - - - - 当同时使用时, - 跳过事务的time将被报告为skipped。 - 如果事务以失败结束,其time将被报告为failed。 - 如果使用选项,失败事务的time会根据失败类型报告为serializationdeadlock(详见)。 + 日志格式如下: + + +client_id transaction_no time script_no time_epoch time_us schedule_lag + + + 其中, + client_id 表示运行该事务的客户端会话, + transaction_no 记录该会话已运行的事务数, + time 是事务经过的总时间,单位为微秒, + script_no 标识使用的脚本文件(在通过 指定多个脚本时很有用),而 time_epoch/time_us 分别是 Unix 纪元时间戳和以微秒计的偏移量(适合用来生成带小数秒的 ISO 8601 时间戳),表示事务完成的时间。 + schedule_lag 字段是事务计划开始时间与实际开始时间之间的差值,单位为微秒。它仅在使用 选项时出现。如果同时使用 ,则被跳过事务的 time 将报告为 + skipped @@ -2148,221 +1997,40 @@ END; 5 ms 限制。接下来的两个事务被跳过,因为它们在开始之前就已经迟到了。 - - 以下示例显示了一个带有失败和重试的日志文件片段,最大尝试次数设置为10(请注意额外的retries列): - -3 0 47423 0 1499414498 34501 3 -3 1 8333 0 1499414498 42848 0 -3 2 8358 0 1499414498 51219 0 -4 0 72345 0 1499414498 59433 6 -1 3 41718 0 1499414498 67879 4 -1 4 8416 0 1499414498 76311 0 -3 3 33235 0 1499414498 84469 3 -0 0 failed 0 1499414498 84905 9 -2 0 failed 0 1499414498 86248 9 -3 4 8307 0 1499414498 92788 0 - - - - - 如果使用选项,失败的类型将在time中报告,如下所示: - -3 0 47423 0 1499414498 34501 3 -3 1 8333 0 1499414498 42848 0 -3 2 8358 0 1499414498 51219 0 -4 0 72345 0 1499414498 59433 6 -1 3 41718 0 1499414498 67879 4 -1 4 8416 0 1499414498 76311 0 -3 3 33235 0 1499414498 84469 3 -0 0 serialization 0 1499414498 84905 9 -2 0 serialization 0 1499414498 86248 9 -3 4 8307 0 1499414498 92788 0 - - - 在能够处理大量事务的硬件上运行长时间测试时,日志文件可能会变得非常大。可以使用选项,仅记录事务的随机样本。 - 聚合日志记录 - 使用选项时,日志文件会采用不同的格式。每一行日志描述一个聚合时间间隔,包含以下以空格分隔的字段: - - - - interval_start - - - - 该时间间隔的起始时间,以 Unix 纪元时间戳表示 - - - - - - num_transactions - - - - 该时间间隔内的事务数 - - - - - - sum_latency - - - - 事务延迟的总和 - - - - - - sum_latency_2 - - - - 事务延迟的平方和 - - - - - - min_latency - - - - 最小事务延迟 - - - - - - max_latency - - - - 最大事务延迟 - - - - - - sum_lag - - - - 事务开始延迟的总和 - (除非指定了,否则为零) - - - - - - sum_lag_2 - - - - 事务开始延迟的平方和 - (除非指定了,否则为零) - - - - - - min_lag - - - - 最小事务开始延迟 - (除非指定了,否则为零) - - - - - - max_lag - - - - 最大事务开始延迟 - (除非指定了,否则为零) - - - - - - skipped - - - - 因为启动时间会太晚而被跳过的事务数 - (除非指定了,否则为零) - - - - - - retried - - - - 发生过重试的事务数 - (除非不等于 1,否则为零) - - - - - - retries - - - - 串行化或死锁错误后的重试总次数 - (除非不等于 1,否则为零) - - - - - - serialization_failures - - - - 发生串行化错误且其后未再重试的事务数 - (除非指定了,否则为零) - - - - - - deadlock_failures - - - - 发生死锁错误且其后未再重试的事务数 - (除非指定了,否则为零) - - - - - + 使用 选项时,日志文件采用另一种格式: + + +interval_start num_transactions&zwsp; sum_latency sum_latency_2 min_latency max_latency&zwsp; sum_lag sum_lag_2 min_lag max_lag skipped + + + 其中, + interval_start 是时间区间的开始时间(以 Unix 纪元时间戳表示), + num_transactions 是区间内的事务数, + sum_latency 是区间内事务延迟的总和, + sum_latency_2 是区间内事务延迟的平方和, + min_latency 是区间内的最小延迟,而 + max_latency 是区间内的最大延迟。接下来的字段 + sum_lagsum_lag_2min_lagmax_lag 仅在使用 选项时出现。它们提供各事务等待前一事务完成的时间统计,即各事务计划开始时间与实际开始时间之间的差值。最后一个字段 skipped 仅在还使用 选项时出现。它记录因开始时间过晚而被跳过的事务数。每个事务都计入其提交时所在的时间区间。 + - 下面是使用该选项生成的示例输出: - -pgbench --aggregate-interval=10 --time=20 --client=10 --log --rate=1000 --latency-limit=10 --failures-detailed --max-tries=10 test - -1650260552 5178 26171317 177284491527 1136 44462 2647617 7321113867 0 9866 64 7564 28340 4148 0 -1650260562 4808 25573984 220121792172 1171 62083 3037380 9666800914 0 9998 598 7392 26621 4527 0 - - + 下面是一些输出示例: + +1345828501 5601 1542744 483552416 61 2573 +1345828503 7884 1979812 565806736 60 1479 +1345828505 7208 1979422 567277552 59 1391 +1345828507 7685 1980268 569784714 60 1398 +1345828509 7073 1979779 573489941 236 1411 + 请注意,普通(未聚合)日志格式会显示每个事务所使用的脚本,而聚合格式不会。因此,如果需要按脚本区分的数据,就必须自行聚合。 @@ -2371,39 +2039,11 @@ END; - - 逐语句报告 - - - 使用选项,pgbench为每个语句收集以下统计信息: - - - - latency — 每条语句的耗时。pgbench报告该语句所有成功执行的平均值。 - - - - - 该语句的失败次数。更多信息请参见。 - - - - - 该语句因串行化或死锁错误而发生的重试次数。更多信息请参见。 - - - - - - - 报告仅在选项不等于1时显示重试统计信息。 - - - - 所有数值都是针对每个客户端执行的每条语句计算的,并在基准测试完成后报告。 +逐语句延迟 + + 使用选项时,pgbench会收集每个客户端执行的每条语句所经过的事务时间。基准测试完成后,它会报告这些值的平均值,称为每条语句的延迟。 - - + 对于默认脚本,输出将类似如下: starting vacuum...end. @@ -2412,166 +2052,37 @@ scaling factor: 1 query mode: simple number of clients: 10 number of threads: 1 -maximum number of tries: 1 number of transactions per client: 1000 number of transactions actually processed: 10000/10000 -number of failed transactions: 0 (0.000%) -number of transactions above the 50.0 ms latency limit: 1311/10000 (13.110 %) -latency average = 28.488 ms -latency stddev = 21.009 ms -initial connection time = 69.068 ms -tps = 346.224794 (without initial connection time) -statement latencies in milliseconds and failures: - 0.012 0 \set aid random(1, 100000 * :scale) - 0.002 0 \set bid random(1, 1 * :scale) - 0.002 0 \set tid random(1, 10 * :scale) - 0.002 0 \set delta random(-5000, 5000) - 0.319 0 BEGIN; - 0.834 0 UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid; - 0.641 0 SELECT abalance FROM pgbench_accounts WHERE aid = :aid; - 11.126 0 UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid; - 12.961 0 UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid; - 0.634 0 INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP); - 1.957 0 END; - - - 使用可串行化默认事务隔离级别的默认脚本的另一个输出示例 - (PGOPTIONS='-c default_transaction_isolation=serializable' pgbench ...): - -starting vacuum...end. -transaction type: <builtin: TPC-B (sort of)> -scaling factor: 1 -query mode: simple -number of clients: 10 -number of threads: 1 -maximum number of tries: 10 -number of transactions per client: 1000 -number of transactions actually processed: 6317/10000 -number of failed transactions: 3683 (36.830%) -number of transactions retried: 7667 (76.670%) -total number of retries: 45339 -number of transactions above the 50.0 ms latency limit: 106/6317 (1.678 %) -latency average = 17.016 ms -latency stddev = 13.283 ms -initial connection time = 45.017 ms -tps = 186.792667 (without initial connection time) -statement latencies in milliseconds, failures and retries: - 0.006 0 0 \set aid random(1, 100000 * :scale) - 0.001 0 0 \set bid random(1, 1 * :scale) - 0.001 0 0 \set tid random(1, 10 * :scale) - 0.001 0 0 \set delta random(-5000, 5000) - 0.385 0 0 BEGIN; - 0.773 0 1 UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid; - 0.624 0 0 SELECT abalance FROM pgbench_accounts WHERE aid = :aid; - 1.098 320 3762 UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid; - 0.582 3363 41576 UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid; - 0.465 0 0 INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP); - 1.933 0 0 END; +latency average = 10.870 ms +latency stddev = 7.341 ms +initial connection time = 30.954 ms +tps = 907.949122 (without initial connection time) +statement latencies in milliseconds: + 0.001 \set aid random(1, 100000 * :scale) + 0.001 \set bid random(1, 1 * :scale) + 0.001 \set tid random(1, 10 * :scale) + 0.000 \set delta random(-5000, 5000) + 0.046 BEGIN; + 0.151 UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid; + 0.107 SELECT abalance FROM pgbench_accounts WHERE aid = :aid; + 4.241 UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid; + 5.245 UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid; + 0.102 INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP); + 0.974 END; - - - - 如果指定了多个脚本文件,则会分别为每个脚本文件报告所有统计信息。 - - - 注意,为逐语句延迟计算收集额外的计时信息会带来一定开销。这会拖慢平均执行速度,并降低计算出的 TPS。减速幅度在很大程度上取决于平台和硬件。比较启用和未启用延迟报告时的平均 TPS 值,是判断这一计时开销是否显著的好方法。 + + 如果指定了多个脚本文件,则会分别为每个脚本文件报告平均值。 - - - - - 失败和串行化/死锁重试 - - - 在执行pgbench时,有三种主要类型的错误: - - - - 主程序错误。它们最为严重,总是会导致pgbench立即退出,并显示相应的错误消息。它们包括: - - - - pgbench开始执行时的错误(例如选项值无效); - - - - - 初始化模式中的错误(例如,用于创建内置脚本所需表的查询失败); - - - - - 在线程启动之前发生的错误(例如无法连接到数据库服务器、元命令中有语法错误、线程创建失败); - - - - - 内部pgbench错误(理论上永远不该发生……)。 - - - - - - - 线程在管理其客户端时发生的错误(例如,客户端无法开始连接数据库服务器,或客户端连接数据库服务器所用的套接字已经失效)。在这种情况下,该线程的所有客户端都会停止,而其他线程继续工作;但是,如果指定了,则所有线程都会立即停止。 - - - - - 直接客户端错误。在发生内部pgbench错误(理论上不应发生)或指定了时,它们会导致pgbench立即退出并显示相应错误消息。否则,最坏情况下只会中止失败的客户端,而其他客户端继续运行(但某些客户端错误会在不中止客户端的情况下处理并单独报告,见下文)。本节后续默认讨论的都是直接客户端错误,而不是内部pgbench错误。 - - - - - - - 客户端在发生严重错误时会中止运行;例如,与数据库服务器的连接丢失,或者脚本在最后一个事务尚未完成时就结束了。 - 另外,如果 SQL 或元命令执行失败,且原因不是串行化或死锁错误,客户端也会中止。 - 否则,如果 SQL 命令因串行化或死锁错误而失败,客户端不会中止。 - 在这种情况下,当前事务会回滚,也包括将客户端变量设置为此事务运行之前的状态 - (假设一个事务脚本只包含一个事务;详见了解更多信息)。 - 发生串行化或死锁错误的事务会在回滚后重新执行,直到成功完成,或者达到最大尝试次数(由指定)、达到最大重试时间(由指定),或者基准测试结束(由指定)。如果最后一次尝试仍然失败,该事务会被报告为失败,但客户端不会中止,而是继续工作。 - - - - - - 不指定选项时,事务在发生串行化或死锁错误后永远不会重试,因为其默认值为 1。可以使用无限次尝试(--max-tries=0)并配合选项,仅限制重试的最长时间。也可以使用选项,在无限次尝试的情况下限制基准测试持续时间。 - - - - 在重复包含多个事务的脚本时要小心:脚本总是完全重试,因此成功的事务可能会执行多次。 - - - - 使用 shell 命令重试事务时要小心。与 SQL 命令的结果不同,shell 命令的结果不会回滚,唯一的例外是\setshell命令设置的变量值。 - - - - - 成功事务的延迟包括事务执行的整个时间,包括回滚和重试。延迟仅针对成功的事务和命令进行测量,而不针对失败的事务或命令。 + + 注意,为逐语句延迟计算收集额外的计时信息会带来一定开销。这会拖慢平均执行速度,并降低计算出的 TPS。减速幅度在很大程度上取决于平台和硬件。比较启用和未启用延迟报告时的平均 TPS 值,是判断这一计时开销是否显著的好方法。 + - - 主报告包含失败事务的数量。如果选项不等于 1,主报告还会包含与重试相关的统计信息:发生过重试的事务总数以及重试总次数。每个脚本报告都会继承主报告中的这些字段。逐语句报告仅在选项不等于 1 时显示重试统计信息。 - - - 如果希望在逐事务日志、聚合日志以及主报告和逐脚本报告中按基本类型对失败进行分组,请使用选项。如果还希望按类型区分所有错误和失败(即不会重试的错误),包括超出了哪一种重试限制,以及串行化/死锁失败超出了多少,请使用选项。 - - - - 表访问方法 - - 可以为 pgbench 表指定表访问方法。环境变量PGOPTIONS用于指定通过命令行传递给 PostgreSQL 的数据库配置选项(见)。例如,可以用如下方式为 pgbench 创建的表指定一个名为wuzza的假想默认表访问方法: - -PGOPTIONS='-c default_table_access_method=wuzza' - - - @@ -2590,7 +2101,7 @@ PGOPTIONS='-c default_table_access_method=wuzza' - 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和空闲空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 + 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和无效空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 diff --git a/zh/14/ref/psql-ref.sgml b/zh/14/ref/psql-ref.sgml index 3077773a..23d648c3 100644 --- a/zh/14/ref/psql-ref.sgml +++ b/zh/14/ref/psql-ref.sgml @@ -47,7 +47,7 @@ PostgreSQL documentation - 把所有非空输入行按照它们被读入的形式打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 + 在读入时将所有非空输入行打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 all @@ -58,7 +58,7 @@ PostgreSQL documentation - 切换到非对齐输出模式(默认输出模式是对齐的)。这等效于\pset format unaligned。 + 切换到非对齐输出模式(默认输出模式是aligned)。这等效于\pset format unaligned @@ -78,10 +78,10 @@ PostgreSQL documentation - 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,直到它处理完序列中所有的选项之后终止。 + 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,而是在按顺序处理完所有选项后终止。 - command必须是一个服务器完全可解析的命令字符串(即不包含psql相关的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: + command必须是一个服务器完全可解析的命令字符串(即不包含psql专有的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: psql -c '\x' -c 'SELECT * FROM foo;' @@ -94,13 +94,12 @@ echo '\x \\ SELECT * FROM foo;' | psql 每个SQL命令字符串传递给都作为一个单独的请求发送到服务器。 因此,即使字符串包含多个SQL命令,服务器也会将其作为单个事务执行, - 除非字符串中包含明确的BEGIN/COMMIT命令将其分成多个事务。 + 除非字符串中包含显式的BEGIN/COMMIT命令将其分成多个事务。 (有关服务器如何处理多查询字符串的更多详细信息,请参见。) + 此外,psql只打印字符串中最后一条SQL命令的结果。这与从文件读取同一字符串或将其送入psql标准输入时的行为不同,因为在这些情况下,psql会分别发送每条SQL命令。 - 如果不希望在一个事务中执行多个命令,可以使用重复的命令, - 或将多个命令输入到psql的标准输入, - 可以像上面示例中使用echo,也可以通过shell的here-document,例如: + 由于这种行为,在单个 字符串中放入多条 SQL 命令常常会产生意外结果。最好重复使用 命令,或将多条命令送入 psql 的标准输入,可以像上面所示使用 echo,也可以使用 shell 的 here-document,例如: psql <<EOF \x @@ -172,7 +171,7 @@ EOF - 使用separator作为非对齐输出的域分隔符。这等效于\pset fieldsep或者\f。 + 使用separator作为非对齐输出的字段分隔符。这等效于\pset fieldsep或者\f @@ -226,7 +225,7 @@ EOF - 不要使用Readline进行行编辑,也不要使用命令历史记录(请参见下面的)。 + 不要使用Readline进行行编辑,也不要使用命令历史记录。这有助于在剪切和粘贴时关闭TAB 补全。 @@ -246,7 +245,7 @@ EOF - 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。 + 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展名。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。 @@ -266,7 +265,7 @@ EOF - 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息以及多种输出。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon。 + 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息和各种提示信息。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon @@ -286,7 +285,7 @@ EOF - 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户一个可以取消执行的选项。使用这个选项可以调试脚本。 + 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户,并允许取消执行。使用这个选项可以调试脚本。 @@ -296,7 +295,7 @@ EOF - 运行在单行模式中,其中新行会终止一个 SQL 命令,就像分号的作用一样。 + 运行在单行模式中,其中换行符会终止一个 SQL 命令,就像分号的作用一样。 @@ -322,7 +321,7 @@ EOF - 指定要替换HTML table标签的选项。详见\pset tableattr。 + 指定要放在HTML table标签内的选项。详见\pset tableattr @@ -343,7 +342,7 @@ EOF - 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要重置一个变量,去掉等号就行。要把一个变量置为空值,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 + 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要取消变量的设置,去掉等号就行。要把一个变量设为空字符串,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 @@ -405,7 +404,7 @@ EOF - 不读取启动文件(要么是系统范围的psqlrc文件,要么是用户的~/.psqlrc文件)。 + 不读取启动文件(既不读取系统范围的psqlrc文件,也不读取用户的~/.psqlrc文件)。 @@ -415,7 +414,7 @@ EOF - 设置非对齐输出的域分隔符为零字节。这等效于\pset fieldsep_zero。 + 设置非对齐输出的字段分隔符为零字节。这等效于\pset fieldsep_zero @@ -425,7 +424,7 @@ EOF - 设置非对齐输出的记录分隔符为零字节。例如,这对与xargs -0配合有关。这等效于\pset recordsep_zero。 + 设置非对齐输出的记录分隔符为零字节。例如,这有助于与xargs -0配合使用。这等效于\pset recordsep_zero @@ -438,7 +437,6 @@ EOF 这个选项只能与一个或多个和/或选项结合使用。 它会导致psql在第一个这样的选项之前发出一个BEGIN命令, 并在最后一个选项之后发出一个COMMIT命令,从而将所有命令包装成一个单独的事务。 - 如果任何命令失败且变量ON_ERROR_STOP被设置,那么会发送一个ROLLBACK命令。 这确保要么所有命令都成功完成,要么不应用任何更改。 @@ -486,10 +484,9 @@ EOF 分别指定这些参数。如果遇到一个不属于任何选项的参数, 它将被解释为数据库名(如果数据库名已经给出,则解释为数据库用户名)。 并非所有这些选项都是必需的;它们都有有用的默认值。如果省略主机名, - psql 在 Unix 上将通过 Unix 域套接字连接到本地主机上的服务器, - 在 Windows 上则通过 TCP/IP 连接到 localhost。默认端口号在编译时确定。 + psql 将通过 Unix 域套接字连接到本地主机上的服务器,而在没有 Unix 域套接字的机器上则通过 TCP/IP 连接到 localhost。默认端口号在编译时确定。 由于数据库服务器使用相同的默认值,因此在大多数情况下不必指定端口。 - 默认数据库用户名是你的操作系统用户名。数据库用户名确定后,它也会被用作默认数据库名。 + 默认用户名是你的操作系统用户名,默认数据库名也是如此。 请注意,你不能随意以任意数据库用户名连接到任意数据库。数据库管理员应当已经告知你拥有的访问权限。 @@ -550,7 +547,7 @@ testdb=> 元命令 - 你输入到psql中的任何以未加引用的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 + 你输入到psql中的任何以未加引号的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 @@ -567,7 +564,7 @@ testdb=> - 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉尾随换行)会替换反引号中的文本。在反引号包围的文本内部,不会发生特殊引用或其他处理,只有一种例外:如果出现:variable_name,且variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会被适当地引用成单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于回车和换行字符在所有平台上都无法安全引用,当变量值中出现这类字符时,:'variable_name'这种形式会打印错误消息,并且不会替换变量值。 + 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉末尾的换行符)会替换反引号中的文本。在反引号包围的文本内部,不会进行特殊的引号处理或其他处理,但出现:variable_name时,如果variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会适当地加上引号,使其成为单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于无法保证在所有平台上都能对回车和换行字符安全地加引号,当变量值中出现这类字符时,:'variable_name'形式会打印错误消息,并且不会替换变量值。 @@ -579,8 +576,8 @@ testdb=> - 很多元命令作用在当前查询缓冲区上。这就是一个缓冲区而已,它保存任何已经被键入但是还没有发送到服务器执行的SQL命令文本。这将包括之前输入的行以及在该元命令同一行上出现在前面的任何文本。 - + 许多元命令作用于当前查询缓冲区。这只是一个保存已输入但尚未发送到服务器执行的 SQL 命令文本的缓冲区。其中既包括先前输入的行,也包括同一行上位于元命令之前的文本。 + @@ -591,7 +588,7 @@ testdb=> \a - 如果当前表格输出格式是不对齐,则切换为对齐;否则切换为不对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset。 + 如果当前表格输出格式是非对齐,则切换为对齐;否则切换为非对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset @@ -602,7 +599,7 @@ testdb=> \c\connect [ -reuse-previous=on|off ] [ dbname [ username ] [ host ] [ port ] | conninfo ] - 建立到PostgreSQL服务器的新连接。可以使用位置语法(数据库名称、用户、主机和端口中的一个或多个)指定要使用的连接参数,也可以使用详细说明在中的conninfo连接字符串。如果没有给出参数,则使用与之前相同的参数建立新连接。 + 建立到PostgreSQL服务器的新连接。可以使用位置语法(数据库名称、用户、主机和端口中的一个或多个)指定要使用的连接参数,也可以使用conninfo连接字符串,详见。如果没有给出参数,则使用与之前相同的参数建立新连接。 @@ -618,7 +615,7 @@ testdb=> 默认情况下,参数在位置语法中被重用,但在给定conninfo字符串时不会被重用。 传递-reuse-previous=on-reuse-previous=off作为第一个参数将覆盖该默认设置。 如果参数被重用,则任何未明确指定为位置参数或在conninfo字符串中的参数将从现有连接的参数中获取。 - 一个例外是,如果使用位置语法将host设置更改为其先前值,则现有连接参数中存在的任何hostaddr设置将被删除。 + 一个例外是,如果使用位置语法更改host设置,使其不同于先前的值,则现有连接参数中存在的任何hostaddr设置将被删除。 此外,仅当用户、主机和端口设置未更改时,才会重用现有连接使用的任何密码。 当命令既不指定也不重用特定参数时,将使用libpq的默认值。 @@ -640,7 +637,7 @@ testdb=> => \c mydb myuser host.dom 6432 => \c service=foo => \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable" -=> \c -reuse-previous=on sslmode=require -- changes only sslmode +=> \c -reuse-previous=on sslmode=require -- 仅更改 sslmode => \c postgresql://tom@localhost/mydb?application_name=myapp @@ -650,11 +647,8 @@ testdb=> \C [ title ] - 设置作为查询结果打印的任何表格的标题,或取消任何这样的标题。此命令等效于 - \pset title title。(此命令的名称源自caption, - 因为它以前仅用于设置HTML表格中的标题。) - + 设置作为查询结果打印的表的标题,或取消此类标题。该命令等价于\pset title title。(此命令的名称源自caption,因为它过去只用于设置HTML表的标题。) + @@ -662,14 +656,11 @@ testdb=> \cd [ directory ] - 将当前工作目录更改为 - directory。如果没有参数,则切换到当前用户的主目录。关于如何确定主目录,请参见 。 - + 将当前工作目录更改为directory。如果没有参数,则切换到当前用户的主目录。 + - - 要打印当前工作目录,请使用\! pwd。 - + 要打印当前工作目录,请使用\! pwd @@ -678,14 +669,7 @@ testdb=> \conninfo - - 输出当前数据库连接的信息;如果正在使用 SSL,也包括与 SSL 相关的信息。 - - - 请注意,Client User 字段显示的是连接建立时的用户,而 - Superuser 字段表示当前用户(在当前执行上下文中)是否具有超级用户权限。这两个用户通常相同,但也可能不同,例如当前用户曾通过 - SET ROLE 命令被更改。 - + 输出当前数据库连接的信息。 @@ -734,9 +718,7 @@ testdb=> - 这些操作不如以文件或程序作为数据源或目标的 SQL - COPY 命令高效,因为所有数据都必须通过客户端/服务器连接传输。对于大量数据,使用 SQL - 命令可能更合适。 + 这些操作不如以文件或程序作为数据源或目标的SQL COPY命令高效,因为所有数据都必须通过客户端/服务器连接传输。对于大量数据,使用SQL命令可能更合适。另外,由于采用这种数据转送方式,CSV模式下的\copy ... from会错误地把单独占据一行的\.数据值当作输入结束标记。 @@ -762,46 +744,24 @@ testdb=> ] ] ] ] - 执行当前查询缓冲区(类似于\g)并在交叉表格中显示结果。 - 查询必须返回至少三列。 - 由colV标识的输出列成为垂直标题, - 由colH标识的输出列成为水平标题。 - colD标识要在网格中显示的输出列。 - sortcolH标识水平标题的可选排序列。 - + 执行当前查询缓冲区(与\g类似),并以交叉表网格显示结果。查询必须返回至少三列。由colV标识的输出列成为纵向表头,由colH标识的输出列成为横向表头。colD标识要在网格中显示的输出列。sortcolH标识横向表头的可选排序列。 + - 每个列规范可以是列号(从1开始)或列名。列名遵循通常的SQL大小写折叠和引用规则。如果省略, - colV被视为第1列, - colH被视为第2列。 - colH必须与 - colV不同。 - 如果未指定colD,则查询结果中必须恰好有三列, - 并且既不是colV也不是 - colH的列被视为 - colD。 - + 每个列指定都可以是列号(从 1 开始)或列名。通常的 SQL 大小写折叠和加引号规则适用于列名。如果省略,colV取第 1 列,colH取第 2 列。colH必须不同于colV。如果未指定colD,查询结果必须恰好有三列,既不是colV也不是colH的那一列被用作colD。 + - 垂直标题显示为最左侧的列,包含在列colV中找到的值, - 与查询结果中的顺序相同,但删除了重复项。 - + 纵向表头显示为最左列,包含colV列中的值,其顺序与查询结果中相同,但会移除重复值。 + - 水平标题作为第一行显示,包含在列colH中找到的值,去除重复项。 - 默认情况下,这些值按照查询结果中的顺序显示。但是,如果给定可选的sortcolH参数, - 它标识一个列,其值必须是整数,colH中的值将按照相应的 - sortcolH值排序后显示在水平标题中。 - + 横向表头显示为第一行,包含colH列中的值,并移除重复值。默认情况下,它们按查询结果中的相同顺序显示。但如果给出了可选的sortcolH参数,它所标识的列的值必须是整数,而colH中的值会按照对应的sortcolH值排序后显示在横向表头中。 + - 在交叉表格中,对于每个colH列的非重复值x, - 和每个colV列的非重复值y, - 位于交点(x,y)的单元格包含查询结果行中colD列的值, - 其中colH列的值为x, - colV列的值为y。 - 如果没有这样的行,则单元格为空。如果有多个这样的行,则报告错误。 - + 在交叉表网格中,对于colH中的每个不同值xcolV中的每个不同值y,交点(x,y)处的单元格包含查询结果中colD列的值,该结果行的colH值为xcolV值为y。如果没有这样的行,单元格为空。如果存在多条这样的行,则报错。 + @@ -823,11 +783,7 @@ testdb=> - 命令形式\d+与前者相同,只是会显示更多信息:显示与表列相关的任何注释, - 表中的OID的存在,如果关系是视图,则显示视图定义,非默认的 - 复制标识设置以及 - 如果关系具有访问方法,则显示 - 访问方法名称。 + 命令形式\d+与前者相同,但会显示更多信息:表列关联的注释、表是否包含 OID、当关系为视图时的视图定义、非默认的复制标识设置,以及当关系具有访问方法时的访问方法名称。 @@ -902,9 +858,7 @@ testdb=> - - 列出与操作符族关联的操作符(参见 )。如果指定了 access-method-pattern,则只列出与名称匹配该模式的访问方法所关联的操作符族成员。如果指定了 operator-family-pattern,则只列出名称与该模式匹配的操作符族成员。如果在命令名后追加 +,则每个操作符都会连同其排序操作符族(如果它是排序操作符)以及其底层函数是否防漏一起列出。 - + 列出与操作符族关联的操作符(见)。如果指定了access-method-pattern,则只列出关联访问方法的名称匹配该模式的操作符族成员。如果指定了operator-family-pattern,则只列出名称匹配该模式的操作符族成员。如果在命令名后附加+,还会列出每个操作符的排序操作符族(如果它是一个排序操作符)。 @@ -949,9 +903,7 @@ testdb=> \dC[+] [ pattern ] - - 列出类型转换。如果指定了 pattern,则只列出其源类型或目标类型与模式匹配的类型转换。如果在命令名后追加 +,则会显示每个类型转换的附加信息,包括其底层函数是否防漏,以及该类型转换的描述。 - + 列出类型转换。如果指定了pattern,则只列出源类型或目标类型匹配该模式的类型转换。如果在命令名后附加+,还会列出每个对象关联的描述。 @@ -962,7 +914,7 @@ testdb=> 显示constraintoperator classoperator familyrule和 - trigger类型对象的描述。所有其他注释可以通过相应的反斜杠命令查看这些对象类型。 + trigger类型对象的描述。其他注释可通过对应对象类型的反斜线命令查看。 \dd 显示与 @@ -987,7 +939,7 @@ testdb=> - \ddp[ pattern ] + \ddp [ pattern ] 列出默认访问权限设置。对于每个默认权限设置已偏离内置默认值的角色(以及适用时的模式),都会显示一条记录。如果指定了 pattern,则只列出角色名或模式名与模式匹配的记录。 @@ -1022,10 +974,7 @@ testdb=> \des[+] [ pattern ] - - 列出外部服务器(助记符:external - servers)。如果指定了 pattern,则只列出名称与模式匹配的服务器。如果在命令名后追加 +,则会显示每个服务器的完整描述,包括服务器的访问权限、类型、版本、选项和描述。 - + 列出外部服务器(助记词:external servers)。如果指定了pattern,则只列出名称匹配该模式的服务器。如果使用\des+形式,则显示每个服务器的完整说明,包括服务器的访问权限、类型、版本、选项和描述。 @@ -1033,9 +982,7 @@ testdb=> \det[+] [ pattern ] - - 列出外部表(助记符:external tables)。如果指定了 pattern,则只列出表名或模式名与模式匹配的条目。如果在命令名后追加 +,则还会显示通用选项以及外部表描述。 - + 列出外部表(助记词:external tables)。如果指定了pattern,则只列出表名或模式名匹配该模式的条目。如果使用\det+形式,还会显示通用选项和外部表描述。 @@ -1043,15 +990,10 @@ testdb=> \deu[+] [ pattern ] - - 列出用户映射(助记符:external - users)。如果指定了 pattern,则只列出用户名与模式匹配的映射。如果在命令名后追加 +,则会显示每个映射的附加信息。 - + 列出用户映射(助记词:external users)。如果指定了pattern,则只列出用户名匹配该模式的映射。如果使用\deu+形式,还会显示每个映射的附加信息。 - - \deu+可能还会显示远程用户的用户名和密码,因此应注意不要泄露它们。 - + \deu+还可能显示远程用户的用户名和密码,因此应注意不要泄露它们。 @@ -1060,10 +1002,7 @@ testdb=> \dew[+] [ pattern ] - - 列出外部数据包装器(助记符:external - wrappers)。如果指定了 pattern,则只列出名称与模式匹配的外部数据包装器。如果在命令名后追加 +,则还会显示外部数据包装器的访问权限、选项和描述。 - + 列出外部数据包装器(助记词:external wrappers)。如果指定了pattern,则只列出名称匹配该模式的外部数据包装器。如果使用\dew+形式,还会显示外部数据包装器的访问权限、选项和描述。 @@ -1074,8 +1013,8 @@ testdb=> 列出函数,以及它们的结果数据类型、参数数据类型和函数类型,函数类型分为 agg(聚合)、normalproceduretriggerwindow。要只显示特定类型的函数,请在命令后添加相应的字母 anptw。如果指定了 pattern,则只显示名称与模式匹配的函数。任何附加参数都是类型名模式,分别与函数第一、第二等参数的类型名匹配。(匹配到的函数可以比你指定的参数更多;若要防止这种情况,可将破折号 - 写成最后一个 arg_pattern。)默认情况下,只显示用户创建的对象;提供模式或 S - 修饰符可包括系统对象。如果在命令名后追加 +,则会显示每个函数的附加信息,包括易变性、并行安全性、所有者、安全分类、是否防漏、访问权限、语言、内部名称(仅适用于 C 和 internal 函数)以及描述。特定函数的源代码可通过 \sf 查看。 + class="parameter">pattern,则只显示名称与模式匹配的函数。任何附加参数都是类型名模式,分别与函数第一、第二等参数的类型名匹配。(匹配到的函数可以比你指定的参数更多;若要防止这种情况,可将连字符 - 写成最后一个 arg_pattern。)默认情况下,只显示用户创建的对象;提供模式或 S + 修饰符可包括系统对象。如果使用 \df+ 形式,则会显示每个函数的附加信息,包括易变性、并行安全性、所有者、安全分类、访问权限、语言、源代码和描述。 @@ -1084,36 +1023,28 @@ testdb=> \dF[+] [ pattern ] - - 列出文本搜索配置。如果指定了 pattern,则只显示名称与模式匹配的配置。如果在命令名后追加 +,则会显示每个配置的完整描述,包括底层文本搜索解析器以及每种记号类型对应的词典列表。 - + 列出全文检索配置。如果指定了pattern,则只显示名称匹配该模式的配置。如果使用\dF+形式,则显示每个配置的完整说明,包括底层全文检索解析器和每种解析器词元类型的词典列表。 \dFd[+] [ pattern ] - - 列出文本搜索词典。如果指定了 pattern,则只显示名称与模式匹配的词典。如果在命令名后追加 +,则会显示每个所选词典的附加信息,包括底层文本搜索模板和选项值。 - + 列出全文检索词典。如果指定了pattern,则只显示名称匹配该模式的词典。如果使用\dFd+形式,还会显示每个选中词典的附加信息,包括底层全文检索模板和选项值。 \dFp[+] [ pattern ] - - 列出文本搜索解析器。如果指定了 pattern,则只显示名称与模式匹配的解析器。如果在命令名后追加 +,则会显示每个解析器的完整描述,包括底层函数和已识别的记号类型列表。 - + 列出全文检索解析器。如果指定了pattern,则只显示名称匹配该模式的解析器。如果使用\dFp+形式,则显示每个解析器的完整说明,包括底层函数和可识别的词元类型列表。 \dFt[+] [ pattern ] - - 列出文本搜索模板。如果指定了 pattern,则只显示名称与模式匹配的模板。如果在命令名后追加 +,则会显示每个模板的附加信息,包括底层函数名。 - + 列出全文检索模板。如果指定了pattern,则只显示名称匹配该模式的模板。如果使用\dFt+形式,还会显示每个模板的附加信息,包括底层函数名。 @@ -1121,11 +1052,7 @@ testdb=> \dg[S+] [ pattern ] - - 列出数据库角色。(由于 usersgroups 的概念已经统一为 roles,此命令现在等同于 - \du。)默认情况下,只显示用户创建的角色;提供 - S 修饰符可包括系统角色。如果指定了 pattern,则只列出名称与模式匹配的角色。如果在命令名后追加 +,则会显示每个角色的附加信息;目前这会增加每个角色的注释。 - + 列出数据库角色。(由于用户的概念已经统一为角色,此命令现在等价于\du。)默认只显示用户创建的角色;提供S修饰符可包含系统角色。如果指定了pattern,则只列出名称匹配该模式的角色。如果使用\dg+形式,还会显示每个角色的附加信息;目前会增加每个角色的注释。 @@ -1133,9 +1060,7 @@ testdb=> \dl - - 这是 \lo_list 的别名,后者会显示大对象列表。 - + 这是\lo_list的别名,用于显示大对象列表。 @@ -1166,7 +1091,7 @@ testdb=> \do[S+] [ pattern [ arg_pattern [ arg_pattern ] ] ] - 列出操作符及其操作数类型和结果类型。如果指定了 pattern,则只列出名称与模式匹配的操作符。如果指定了一个 arg_pattern,则只列出其右参数类型名称与该模式匹配的前缀操作符。如果指定了两个 arg_pattern,则只列出参数类型名称与这些模式匹配的二元操作符。(对于一元操作符未使用的参数,也可以写成 -。)默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 +,则会显示每个操作符的附加信息,包括底层函数名以及它是否防漏。 + 列出操作符及其操作数类型和结果类型。如果指定了 pattern,则只列出名称与模式匹配的操作符。如果指定了一个 arg_pattern,则只列出其右参数类型名称与该模式匹配的前缀操作符。如果指定了两个 arg_pattern,则只列出参数类型名称与这些模式匹配的二元操作符。(对于一元操作符未使用的参数,也可以写成 -。)默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 +,则会显示每个操作符的附加信息,目前仅包括底层函数名。 @@ -1186,7 +1111,7 @@ testdb=> \dp [ pattern ] - 列出表、视图和序列及其相关访问权限。如果指定了 pattern,则只列出名称与模式匹配的表、视图和序列。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 + 列出表、视图和序列及其相关访问权限。如果指定了 pattern,则只列出名称与模式匹配的表、视图和序列。 GRANT和 @@ -1201,34 +1126,20 @@ testdb=> \dP[itn+] [ pattern ] - - 列出分区关系。 - 如果pattern被指定, - 则只列出名称与模式匹配的条目。 - 修饰符t(表)和i(索引) - 可以附加到命令,过滤要列出的关系类型。默认情况下,列出分区表和索引。 - + 列出分区关系。如果指定了pattern,则只列出名称匹配该模式的条目。可以在命令后附加修饰符t(表)和i(索引),筛选要列出的关系类型。默认会列出分区表和分区索引。 - - 如果使用修饰符nnested), - 或指定了模式,则将包括非根分区关系,并显示一个列,显示每个 - 分区关系的父级。 - + 如果使用了修饰符nnested),或指定了模式,则会包含非根分区关系,并显示一列,列出每个分区关系的父关系。 - -如果在命令名后追加 +,则还会显示每个关系分区大小的总和以及关系描述。如果 n+ 组合使用,则会显示两个大小:一个包括直接附加的叶分区的总大小,另一个显示包括间接附加子分区在内的所有分区总大小。 - + 如果在命令名后附加+,还会显示每个关系的各个分区的大小之和,以及该关系的描述。如果将n+结合使用,则显示两个大小:一个是直接附加的叶子分区的总大小,另一个是所有分区的总大小,包括间接附加的子分区。 - \drds[ role-pattern [ database-pattern ] ] + \drds [ role-pattern [ database-pattern ] ] - 列出已定义的配置设置。这些设置可以是特定于角色、特定于数据库,或者两者兼有。role-pattern 和 - database-pattern 分别用于选择要列出的特定角色和数据库。如果省略,或者指定了 - *,则会列出所有设置,包括那些未指定角色或数据库的设置。 + 列出已定义的配置设置。这些设置可以特定于角色、特定于数据库,或同时特定于两者。role-patterndatabase-pattern分别用于选择要列出的角色和数据库。省略某个模式参数或将其指定为*时,不会按该参数筛选,还会分别包含不特定于角色或不特定于数据库的设置。 ALTER ROLE和 @@ -1244,9 +1155,7 @@ testdb=> \dRp[+] [ pattern ] - - 列出逻辑复制发布。如果指定了 pattern,则只列出名称与模式匹配的发布。如果在命令名后追加 +,则还会显示与每个发布关联的表和模式。 - + 列出复制发布。如果指定了pattern,则只列出名称匹配该模式的发布。如果在命令名后附加+,还会显示与每个发布关联的表。 @@ -1263,7 +1172,7 @@ testdb=> \dT[S+] [ pattern ] - 列出数据类型。如果指定了 pattern,则只列出名称与模式匹配的类型。如果在命令名后追加 +,则每个类型都会连同其内部名称和大小一起列出;对于 enum 类型,还会显示其允许值以及相关权限。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 + 列出数据类型。如果指定了 pattern,则只列出名称与模式匹配的类型。如果在命令名后追加 +,则每个类型都会连同其内部名称、大小以及相关权限一起列出;对于 enum 类型,还会显示其允许值。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 @@ -1271,25 +1180,19 @@ testdb=> \du[S+] [ pattern ] - - 列出数据库角色。(由于 usersgroups 的概念已经统一为 roles,此命令现在等同于 - \dg。)默认情况下,只显示用户创建的角色;提供 - S 修饰符可包括系统角色。如果指定了 pattern,则只列出名称与模式匹配的角色。如果在命令名后追加 +,则会显示每个角色的附加信息;目前这会增加每个角色的注释。 - + 列出数据库角色。(由于用户的概念已经统一为角色,此命令现在等价于\dg。)默认只显示用户创建的角色;提供S修饰符可包含系统角色。如果指定了pattern,则只列出名称匹配该模式的角色。如果使用\du+形式,还会显示每个角色的附加信息;目前会增加每个角色的注释。 \dx[+] [ pattern ] - - 列出已安装的扩展。如果指定了 pattern,则只列出名称与模式匹配的扩展。如果在命令名后追加 +,则会列出属于每个匹配扩展的全部对象。 - + 列出已安装的扩展。如果指定了pattern,则只列出名称匹配该模式的扩展。如果使用\dx+形式,则列出属于每个匹配扩展的所有对象。 - \dX[ pattern ] + \dX [ pattern ] 列出扩展统计信息。如果指定了 pattern,则只列出名称与模式匹配的扩展统计信息。 @@ -1312,7 +1215,7 @@ testdb=> - \e\edit filename 行号 + \e\edit filename line_number @@ -1324,7 +1227,7 @@ testdb=> 如果编辑文件或上一个查询后在未修改文件的情况下退出编辑器,则查询缓冲区将被清除。 否则,查询缓冲区的新内容将根据psql的正常规则重新解析, - 将整个缓冲区视为单行。任何完整的查询将立即执行;也就是说,如果查询缓冲区包含或以分号结尾, + 将整个缓冲区视为单行。任何完整的查询将立即执行;也就是说,如果查询缓冲区包含分号或以分号结尾, 则执行并从查询缓冲区中删除到该点的所有内容。查询缓冲区中剩余的内容将重新显示。 输入分号或\g发送它,或输入\r通过清除查询缓冲区来取消。 @@ -1336,7 +1239,7 @@ testdb=> 如果指定了行号,psql将光标定位在文件或查询缓冲区的指定行上。 - 请注意,如果给出一个全是数字的参数, + 请注意,如果只给出一个全是数字的参数, psql会假定它是一个行号,而不是文件名。 @@ -1351,14 +1254,10 @@ testdb=> \echo text [ ... ] - - 将求值后的参数打印到标准输出,用空格分隔,并在末尾加上换行符。这对于在脚本输出中穿插信息很有用。例如: - + 将求值后的参数打印到标准输出,用空格分隔,并在末尾加上换行符。这对于在脚本输出中穿插信息很有用。例如: => \echo `date` Tue Oct 26 21:40:57 CEST 1999 - - 如果第一个参数是未引用的-n,则不会写入尾随的换行符(也不会写入第一个参数)。 - +如果第一个参数是未加引号的-n,则不会写入尾随的换行符(也不会写入第一个参数)。 @@ -1466,7 +1365,7 @@ Tue Oct 26 21:40:57 CEST 1999 - 设置未对齐查询输出的字段分隔符。默认值是竖线(|)。 + 设置非对齐查询输出的字段分隔符。默认值是竖线(|)。 它等同于\pset fieldsep @@ -1477,25 +1376,17 @@ Tue Oct 26 21:40:57 CEST 1999 \g [ (option=value [...]) ] [ filename ] \g [ (option=value [...]) ] [ |command ] - - 将当前查询缓冲区发送到服务器以执行。 - - - 如果在\g后面出现括号,则括号中包围着一个空格分隔的option=value格式选项子句的列表,这些选项子句的解释方式与\psetoptionvalue命令相同,但仅在此查询的持续时间内生效。在此列表中,不允许在=符号周围有空格,但在选项子句之间需要空格。 - 如果省略了=value,则命名的option将以与\psetoption没有显式value时相同的方式更改。 - - - 如果提供了一个filename|command参数, - 查询的输出将被写入到指定的文件或通过给定的shell命令进行传输,而不是像通常那样显示出来。只有在查询成功返回零个或多个元组时,文件或命令才会被写入,而不是在查询失败或是非数据返回的SQL命令时。 + 将当前查询缓冲区发送给服务器执行。 + 如果在\g后面出现括号,则括号中是用空格分隔的option=value格式选项子句列表。这些子句的解释方式与\pset + option + value命令相同,但仅在此查询执行期间生效。在此列表中,=符号周围不允许有空格,但选项子句之间必须有空格。如果=value被省略,则指定的option会按以下命令的方式更改:\pset option,其中不显式指定value + 如果给出了filename|command参数,查询输出就会写入指定文件,或通过管道传给指定的 shell 命令,而不是照常显示。只有当查询成功返回零个或多个元组时,才会向文件或命令写入;如果查询失败,或执行的是不返回数据的 SQL 命令,则不会写入。 如果当前查询缓冲区为空,则最近发送的查询将被重新执行。除此之外,没有任何参数的\g基本上等同于一个分号。 带有参数的\g提供了一个一次性替代\o命令的选择,并且还允许一次性调整通常由\pset设置的输出格式选项。 - - 当最后一个参数以|开头时,整行剩余部分被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分将被直接传递给shell。 - + 当最后一个参数以|开头时,该行剩余的全部内容都会被视为要执行的command,其中既不进行变量插值,也不进行反引号扩展。该行剩余部分会直接按字面传给 shell。 @@ -1504,14 +1395,9 @@ Tue Oct 26 21:40:57 CEST 1999 \gdesc - - 显示当前查询缓冲区结果的描述(即列名和数据类型)。 - 查询不会实际执行;但是,如果包含某种语法错误,该错误将以正常方式报告。 - + 显示当前查询缓冲区中查询结果的描述(即列名和数据类型)。查询并不会实际执行;不过,如果其中存在语法错误,会按通常的方式报告。 - - 如果当前查询缓冲区为空,则描述最近发送的查询。 - + 如果当前查询缓冲区为空,则改为描述最近发送的查询。 @@ -1552,37 +1438,23 @@ CREATE INDEX \gset [ prefix ] - - 将当前查询缓冲区发送到服务器,并将查询的输出存储到psql变量中 - (参见下面的)。 - 要执行的查询必须返回一行。该行的每一列都存储在一个单独的变量中,变量名与列名相同。例如: - + 将当前查询缓冲区发送给服务器,并将查询输出存入 psql 变量(参见下面的)。要执行的查询必须恰好返回一行。该行的每一列分别存入一个变量,变量名与列名相同。例如: => SELECT 'hello' AS var1, 10 AS var2 -> \gset => \echo :var1 :var2 hello 10 - - 如果指定了一个prefix, - 该字符串将被添加到查询的列名前,以创建要使用的变量名: - + 如果指定了prefix,则会将该字符串加到查询的列名前面,以构成要使用的变量名: => SELECT 'hello' AS var1, 10 AS var2 -> \gset result_ => \echo :result_var1 :result_var2 hello 10 - - 如果列的结果为NULL,则相应的变量将被取消设置,而不是被设置。 - - - 如果查询失败或者没有返回一行结果, - 则不会改变任何变量。 - - - 如果当前查询缓冲区为空,则重新执行最近发送的查询。 - + 如果某一列的结果为 NULL,则取消设置对应的变量,而不是设置它。 + 如果查询失败或没有恰好返回一行,则不会更改任何变量。 + 如果当前查询缓冲区为空,则改为重新执行最近发送的查询。 @@ -1605,7 +1477,7 @@ hello 10 给出指定SQL命令的语法帮助。如果未指定command, 则psql将列出所有可用语法帮助的命令。如果command是星号 - (*),则显示所有SQL命令的语法帮助。 + (*),则显示所有SQL命令的语法帮助。 @@ -1626,9 +1498,7 @@ hello 10 \H\html - 打开HTML查询输出格式。如果HTML格式已经打开, - 则切换回默认的对齐文本格式。此命令用于兼容性和便利性,但请参阅\pset - 有关设置其他输出选项。 + 打开HTML查询输出格式。如果HTML格式已经打开,则切换回默认的对齐文本格式。此命令是为兼容性和便利性而保留的;设置其他输出选项的方法见\pset @@ -1640,13 +1510,10 @@ hello 10 - 从文件filename中读取输入,并将其执行为 - 好像它是在键盘上键入的一样。 + 从文件filename中读取输入,并像在键盘上输入一样执行它。 - 如果filename- - (连字符),那么标准输入将被读取,直到EOF指示或\q元命令。 - 这可用于将交互式输入与文件输入交错使用。请注意,仅当在最外层级别处于活动状态时,Readline行为才会被使用。 + 如果filename-(连字符),则从标准输入读取,直到遇到 EOF 指示或\q元命令。这可用于将交互式输入与文件输入交错使用。请注意,只有在最外层启用了 Readline,此处才会使用 Readline 功能。 @@ -1666,42 +1533,26 @@ hello 10 这组命令实现了可嵌套的条件块。条件块必须以\if开始,并以\endif结束。 在两者之间可以有任意数量的\elif子句,后面可以选择性地跟着一个\else子句。 - 在形成条件块的命令之间通常会出现普通查询和其他类型的反斜杠命令。 + 在形成条件块的命令之间通常会出现普通查询和其他类型的反斜线命令。 - \if\elif命令读取它们的参数,并将其作为布尔表达式进行评估。 - 如果表达式为true,则处理将继续进行;否则,直到达到匹配的\elif、 - \else\endif为止,将跳过行。一旦\if或 - \elif测试成功,同一块中后续\elif命令的参数不会被评估,而是被视为false。 - 在\else之后的行只有在没有早期匹配的\if\elif成功时才会被处理。 + \if\elif命令读取其参数,并将其作为布尔表达式求值。如果表达式的值为true,则正常继续处理;否则,跳过后续行,直到遇到匹配的\elif\else\endif。一旦\if\elif测试成功,同一块中后续\elif命令的参数就不再求值,而是被视为假。只有前面所有匹配的\if\elif测试都未成功时,才会处理\else后面的行。 - expression参数 - 是\if\elif命令的参数, - 受变量插值和反引号扩展的影响,就像任何其他反斜杠命令参数一样。 - 之后,它被评估为一个开/关选项变量的值。因此,有效值是以下任何一个不 - 含糊的不区分大小写匹配之一: - true, false, 1, - 0, on, off, - yes, no。例如, - t, TtR - 都将被视为true。 + 与其他反斜线命令的参数一样,\if\elif命令的expression参数会经过变量插值和反引号扩展。随后,按开/关选项变量值的规则对结果求值。因此,有效值是以下值的不区分大小写且无歧义的匹配:truefalse10onoffyesno。例如,tTtR都会被视为true - 不正确评估为真或假的表达式将生成警告,并被视为假。 + 不能正确求值为真或假的表达式会产生警告,并被视为假。 - 被跳过的行会被正常解析以识别查询和反斜杠命令,但查询不会发送到服务器, - 而且除了条件命令(\if\elif, - \else\endif)之外的反斜杠命令会被忽略。 + 被跳过的行会被正常解析以识别查询和反斜线命令,但查询不会发送到服务器, + 而且除了条件命令(\if\elif、 + \else\endif)之外的反斜线命令会被忽略。 仅检查跳过行中条件命令的有效嵌套。跳过行中的变量引用不会被展开, 也不会执行反引号扩展。 - 所有给定条件块的反斜杠命令必须出现在同一个源文件中。如果在主输入文件或一个 - \include的文件上达到文件结束之前,所有本地 - \if块都没有关闭, - 那么psql将会引发错误。 + 同一个条件块的所有反斜线命令必须出现在同一个源文件中。如果主输入文件或通过\include引入的文件到达 EOF 时,仍有本地\if块未关闭,psql就会报错。 下面是一个示例: @@ -1735,17 +1586,13 @@ SELECT \ir\include_relative filename - - \ir命令类似于\i,但是解析相对文件名的方式不同。 - 在交互模式下执行时,这两个命令的行为是相同的。然而,在脚本中调用时, - \ir会将文件名解释为相对于脚本所在目录,而不是当前工作目录。 - + \ir命令与\i相似,但解析相对文件名的方式不同。在交互模式下执行时,这两个命令的行为相同。不过,在脚本中调用时,\ir会相对于脚本所在的目录来解释文件名,而不是相对于当前工作目录。 - \l[+] or \list[+] [ pattern ] + \l[+]\list[+] [ pattern ] 列出服务器中的数据库,并显示其名称、所有者、字符集编码和访问权限。如果指定了 pattern,则只列出名称与模式匹配的数据库。如果在命令名后追加 +,则还会显示数据库大小、默认表空间和描述。当前用户对其拥有 CONNECT 权限的数据库可以显示大小信息;如果当前用户是超级用户或具有 pg_read_all_stats 角色的权限,也可以显示大小信息。 @@ -1762,7 +1609,7 @@ SELECT 从数据库中读取具有OIDloid的大对象,并将其写入filename。请注意,这与服务器函数 - lo_export略有不同,后者使用数据库服务器运行的用户权限, + lo_export略有不同,后者使用运行数据库服务器的用户的权限, 并在服务器的文件系统上操作。 @@ -1778,14 +1625,10 @@ SELECT \lo_import filename [ comment ] - - 将文件存储到一个PostgreSQL大对象中。可选地,它将给定的注释与对象关联起来。例如: - + 将文件存储到一个PostgreSQL大对象中。可选地,它将给定的注释与对象关联起来。例如: foo=> \lo_import '/home/peter/pictures/photo.xcf' 'a picture of me' lo_import 152801 - - 响应表明大对象收到了对象ID 152801,这个ID可以用来在将来访问新创建的大对象。为了可读性起见,建议始终将一个可读的注释与每个对象关联起来。OID和注释都可以用\lo_list命令查看。 - +响应表明大对象获得了对象 ID 152801,这个 ID 可以用来在将来访问新创建的大对象。为便于阅读,建议始终为每个对象关联一条便于人阅读的注释。查看 OID 和注释时,可以使用\lo_list命令。 请注意,此命令与服务器端的lo_import略有不同,因为它作为本地用户在本地文件系统上操作,而不是服务器的用户和文件系统。 @@ -1796,10 +1639,7 @@ lo_import 152801 \lo_list - - 显示当前存储在数据库中的全部 PostgreSQL - 大对象列表,以及为它们提供的任何注释。 - + 列出当前存储在数据库中的所有PostgreSQL大对象,以及为它们提供的注释。 @@ -1808,7 +1648,7 @@ lo_import 152801 - 从数据库中删除具有OIDloid的大对象。 + 从数据库中删除OIDloid的大对象。 @@ -1824,19 +1664,12 @@ lo_import 152801 \o\out [ filename ] \o\out [ |command ] - - 安排将未来的查询结果保存到文件filename, - 或将未来的结果传输到shell命令command。 - 如果未指定参数,则查询输出重置为标准输出。 - + 将后续查询结果保存到文件filename,或通过管道传给 shell 命令command。如果没有指定参数,查询输出将恢复为标准输出。 - - 如果参数以|开头,则整个剩余部分的行被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分的行会被直接传递给shell。 - + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 - 查询结果包括从数据库服务器获取的所有表、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 + 查询结果包括从数据库服务器获取的所有表格、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 @@ -1890,30 +1723,15 @@ lo_import 152801 \pset [ option [ value ] ] - - 这个命令设置影响查询结果表输出的选项。 - option - 指示要设置哪个选项。根据所选选项,value的语义会有所不同。 - 对于某些选项,省略value会导致该选项被切换或取消设置,具体描述在特定选项下。 - 如果没有提到这样的行为,那么省略value只会显示当前设置。 - + 这个命令设置影响查询结果表输出的选项。option指定要设置哪个选项。value的含义取决于所选的选项。对于某些选项,省略value会切换或取消设置该选项,具体见各选项的说明。如果没有提及这类行为,那么省略value只会显示当前设置。 - - \pset不带任何参数时,显示所有打印选项的当前状态。 - + 不带任何参数的\pset会显示所有打印选项的当前状态。 - - 可调整打印选项有: - + 可调整的打印选项如下: border - - value必须是一个数字。一般来说,数字越高,表格的边框和线条就越多, - 但具体细节取决于特定格式。在HTML格式中,这将直接转换为border=...属性。 - 在大多数其他格式中,只有值0(无边框)、1(内部分隔线)和2(表框)有意义,值大于2将被视为border = 2。 - latexlatex-longtable格式还允许值为3,以在数据行之间添加分隔线。 - + value必须是数字。一般来说,数字越大,表格的边框和分隔线就越多,但细节取决于具体格式。在HTML格式中,它会直接转换为border=...属性。在大多数其他格式中,只有值 0(无边框)、1(内部分隔线)和 2(表格外框)有意义,大于 2 的值会与border = 2作相同处理。latexlatex-longtable格式还允许使用值 3,以在数据行之间添加分隔线。 @@ -1926,7 +1744,7 @@ lo_import 152801 零(默认值)会导致目标宽度由环境变量COLUMNS控制,或者如果未设置 COLUMNS则由检测到的屏幕宽度控制。 另外,如果columns为零,则wrapped格式仅影响屏幕输出。 - 如果columns为非零,则文件和管道输出也会被包装到该宽度。 + 如果columns为非零,则文件和管道输出也会按该宽度折行。 @@ -1945,63 +1763,35 @@ lo_import 152801 expanded(或x - - 如果指定了value,它必须是onoff, - 这将启用或禁用扩展模式,或者是auto。 - 如果省略了value,则命令在开启和关闭设置之间切换。 - 启用扩展模式时,查询结果以两列显示,左侧是列名,右侧是数据。 - 如果数据在正常的水平模式下无法完全显示在屏幕上,则此模式很有用。 - 在自动设置中,当查询输出具有多列且宽度超过屏幕时,将使用扩展模式;否则,将使用常规模式。 - 自动设置仅在对齐和换行格式中有效。在其他格式中,它始终表现为扩展模式已关闭。 - + 如果指定了value,它必须是onoff(分别启用或禁用扩展模式),或者是auto。如果省略value,该命令会在开启和关闭设置之间切换。启用扩展模式时,查询结果以两列显示,左侧为列名,右侧为数据。如果数据在通常的横向模式下无法适应屏幕,这种模式就很有用。在自动设置下,当查询输出包含多列且宽度超过屏幕时,会使用扩展模式;否则使用常规模式。自动设置只在对齐和折行格式中有效。在其他格式中,它的行为始终与关闭扩展模式相同。 fieldsep - - 指定在未对齐的输出格式中使用的字段分隔符。这样,可以创建例如制表符分隔的输出, - 其他程序可能更喜欢。要将制表符设置为字段分隔符,请键入 - \pset fieldsep '\t'。默认字段分隔符是 - '|'(一根竖线)。 - + 指定非对齐输出格式使用的字段分隔符。这样可以创建例如制表符分隔的输出,这可能更符合其他程序的需要。要将制表符设置为字段分隔符,请输入\pset fieldsep '\t'。默认字段分隔符是'|'(竖线)。 fieldsep_zero - - 将未对齐输出格式中使用的字段分隔符设置为零字节。 - + 将非对齐输出格式使用的字段分隔符设置为零字节。 footer - - 如果指定了value, - 它必须是onoff, - 这将启用或禁用表格页脚的显示 - ((n 行)计数)。 - 如果省略了value, - 命令将切换页脚的显示或隐藏。 - + 如果指定了value,它必须是onoff,分别启用或禁用表格页脚((n rows)计数)的显示。如果省略value,该命令会切换页脚显示的开关状态。 format - - 设置输出格式为alignedasciidoc、 - csvhtmllatex、 - latex-longtabletroff-ms、 - unalignedwrapped。 - 允许使用唯一缩写。 - + 设置输出格式为alignedasciidoccsvhtmllatexlatex-longtabletroff-msunalignedwrapped。允许使用唯一缩写。 aligned格式是标准的、适合人阅读且排版整齐的文本输出;这是默认格式。 @@ -2014,12 +1804,12 @@ lo_import 152801 按逗号分隔的列值输出,并应用 RFC 4180 - 中描述的引用规则。 + 中描述的加引号规则。 此输出与服务器的CSV格式的 COPY命令兼容。 - 生成包含列名的标题行,除非 + 生成包含列名的表头行,除非 tuples_only参数设置为 - on。不打印标题和页脚。 + on。不打印表格标题和页脚。 每行以系统相关的行结束字符结束, 对于类Unix系统通常是单个换行符(\n), 对于Microsoft Windows则是回车和换行序列 @@ -2027,17 +1817,14 @@ lo_import 152801 可以用\pset csv_fieldsep选择逗号以外的字段分隔字符。 - wrapped格式类似于aligned,但会将宽数据值跨行包装,以使输出适合目标列宽。 - 目标宽度由columns选项下描述的方式确定。请注意,psql不会尝试包装列标题; - 因此,如果列标题所需的总宽度超过目标宽度,则wrapped格式的行为与aligned相同。 - + wrapped格式与aligned相似,但会将较宽的数据值折成多行,使输出适应目标列宽。目标宽度的确定方式见columns选项的说明。请注意,psql不会尝试对列标题折行;因此,如果列标题所需的总宽度超过目标宽度,wrapped格式的行为就与aligned相同。 - asciidochtml, - latexlatex-longtable,和 + asciidochtml、 + latexlatex-longtabletroff-ms格式生成的表格旨在包含在使用相应标记语言的文档中。 它们不是完整的文档!这在HTML中可能不是必需的,但在 - LaTeX中,则必须有一个完整的文档包装器。 + LaTeX中,则必须有一个完整文档的外层结构。 latex格式使用LaTeXtabular 环境。 latex-longtable格式需要LaTeX @@ -2057,25 +1844,19 @@ lo_import 152801 - ascii样式使用普通的ASCII字符。数据中的换行使用右边边缘的+符号显示。 - 当wrapped格式将数据从一行换到下一行而没有换行符时,在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 + ascii样式使用普通的ASCII字符。数据中的换行符以右边缘的+符号表示。当wrapped格式在没有换行符的位置把数据折到下一行时,会在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 - old-ascii样式使用普通的ASCII字符,使用在PostgreSQL 8.4及更早版本中使用的格式样式。 - 数据中的换行符使用:符号代替左侧列分隔符显示。 - 当数据从一行换行到下一行而没有换行符时,使用;符号代替左侧列分隔符。 + old-ascii样式使用普通的ASCII字符,采用PostgreSQL 8.4 及更早版本的格式样式。数据中的换行符以替代左侧列分隔符的:符号表示。当数据在没有换行符的位置折到下一行时,则用;符号替代左侧列分隔符。 - unicode样式使用Unicode绘图字符。数据中的换行使用右边距中的回车符号显示。 - 当数据从一行换行到下一行而没有换行符时,第一行的右边距显示省略号符号, - 接着在下一行的左边距再次显示省略号符号。 + unicode样式使用 Unicode 框线绘制字符。数据中的换行符以右边缘的回车符号表示。当数据在没有换行符的位置折到下一行时,会在第一行的右边缘显示省略号符号,并在下一行的左边缘再次显示。 - 当border设置大于零时,linestyle选项还确定了用哪些字符绘制边框线。 - 普通的ASCII字符在任何地方都有效,但在识别Unicode字符的显示器上看起来更好。 + 当border设置大于零时,linestyle选项还决定用哪些字符绘制边框线。普通的ASCII字符在任何环境中都可用,但在支持 Unicode 的显示设备上,Unicode 字符更美观。 @@ -2083,180 +1864,93 @@ lo_import 152801 null - - 设置要打印在空值位置的字符串。默认情况下是不打印任何内容,这很容易被误解为空字符串。 - 例如,一个人可能更喜欢\pset null '(null)'。 - + 设置用于代替空值打印的字符串。默认不打印任何内容,这很容易被误认为空字符串。例如,你可能更喜欢使用\pset null '(null)' numericlocale - - 如果指定了value, - 它必须是onoff, - 这将启用或禁用显示一个特定于区域设置的字符, - 用于将小数点左侧的数字分组。如果省略了 - value, - 命令在常规和特定于区域设置的数字输出之间切换。 - + 如果指定了value,它必须是onoff,分别启用或禁用使用区域设置特定的字符来分隔小数点左侧的数字组。如果省略value,该命令会在常规数字输出和区域设置特定的数字输出之间切换。 pager - - 控制查询和psql帮助输出时使用分页程序的方式。 - 当pager选项为off时,不使用分页程序。 - 当pager选项为on时,在适当的情况下使用分页程序,即当输出到终端且不适合在屏幕上显示时。 - pager选项也可以设置为always,这会导致分页程序用于所有终端输出,无论是否适合在屏幕上显示。 - \pset pager 不带value时,会在开启和关闭分页器之间切换。 - - - - 如果环境变量PSQL_PAGERPAGER被设置, - 输出将被分页传输到指定的程序。否则,将使用一个平台相关的默认程序 - (例如more)。 - + 控制查询和psql帮助输出是否使用分页器程序。如果设置了环境变量PSQL_PAGERPAGER,输出会通过管道传递给指定的程序。否则,使用与平台有关的默认程序(如more)。 - - 当使用 \watch 命令重复执行查询时,在 Unix 系统上会改用环境变量 PSQL_WATCH_PAGER - 来查找分页器程序。之所以单独配置它,是因为这种用法可能会让传统分页器无法正常工作;但它可用于把输出发送给能够理解 - psql 输出格式的工具(例如 - pspg --stream)。 - + pager选项为off时,不使用分页器程序。当pager选项为on时,会在适当时使用分页器,即输出目标为终端且内容无法在屏幕上完整显示时。pager选项也可以设为always,这样所有终端输出都会使用分页器,无论内容是否能在屏幕上完整显示。不带value\pset pager会切换分页器的使用状态。 pager_min_lines - - 如果pager_min_lines设置为大于页面高度的数字, - 则除非至少有这么多行的输出要显示,否则不会调用分页程序。默认设置为0。 - + 如果将pager_min_lines设置为大于页面高度的数字,那么只有待显示的输出至少达到这么多行时,才会调用分页器程序。默认设置为 0。 recordsep - - 指定在未对齐的输出格式中使用的记录(行)分隔符。默认为换行符。 - + 指定非对齐输出格式使用的记录(行)分隔符。默认为换行符。 recordsep_zero - - 设置未对齐输出格式中使用的记录分隔符为零字节。 - + 将非对齐输出格式使用的记录分隔符设置为零字节。 tableattr(或T - - 在HTML格式中,这指定要放置在table标签内的属性。 - 这可能是cellpaddingbgcolor等。 - 请注意,这里通常不需要指定border,因为它已经由\pset border处理。 - 如果没有给出value,则取消表格属性。 - - - 在latex-longtable格式中,这控制了包含左对齐数据类型的每列的比例宽度。 - 它被指定为一个以空格分隔的值列表,例如,'0.2 0.2 0.6'。 - 未指定输出列使用最后指定的值。 - + HTML格式中,这指定要放在table标签内的属性,例如cellpaddingbgcolor。请注意,你可能不需要在这里指定border,因为\pset border已经负责处理它。如果没有给出value,则取消设置表格属性。 + latex-longtable格式中,这控制每个包含左对齐数据类型的列的宽度比例。它以空白分隔的值列表指定,例如'0.2 0.2 0.6'。未指定的输出列使用最后指定的值。 - title(或者C + title(或C - - 设置后续打印的任何表的标题。这可以用来为输出提供说明性标签。 - 如果没有给出value,则标题将被取消设置。 - + 设置随后打印的所有表格的标题。这可以为输出提供描述性标签。如果没有给出value,则取消设置标题。 tuples_only(或t - - 如果指定了value,它必须是onoff, - 这将启用或禁用仅元组模式。如果省略了value, - 命令将在常规输出和仅元组输出之间切换。常规输出包括额外信息,如列标题、标题和各种页脚。 - 在仅元组模式下,只显示实际的表数据。 - + 如果指定了value,它必须是onoff,分别启用或禁用仅元组模式。如果省略value,该命令会在常规输出和仅元组输出之间切换。常规输出包含列标题、表格标题和各种页脚等附加信息。在仅元组模式下,只显示实际的表格数据。 unicode_border_linestyle - - 设置unicode线条样式的边框绘制样式为singledouble之一。 - + unicode线条样式的边框绘制样式设置为singledouble unicode_column_linestyle - - 设置unicode线条样式的列绘制样式为singledouble之一。 - + unicode线条样式的列分隔线绘制样式设置为singledouble unicode_header_linestyle - - 设置unicode线条样式的标题绘制样式为singledouble之一。 - - - - - - xheader_width - - - 将扩展输出的标题最大宽度设置为以下之一: - full(默认值)、 - columnpage 或 - 整数值。 - - - - full:扩展标题不截断,其宽度与最宽的输出行相同。 - - - - column:将标题行截断为第一列的宽度。 - - - - page:将标题行截断为终端宽度。 - - - - 整数值:指定标题行的确切最大宽度。 - + unicode线条样式的表头分隔线绘制样式设置为singledouble - - 这些不同格式的示例可以在下面的中看到。 - + 这些不同格式的外观示例可参见下面的 @@ -2273,10 +1967,7 @@ lo_import 152801 \q\quit - - 退出psql程序。 - 在脚本文件中,只有该脚本的执行被终止。 - + 退出psql程序。在脚本文件中,只会终止该脚本的执行。 @@ -2285,7 +1976,7 @@ lo_import 152801 \qecho text [ ... ] - 这个命令与\echo命令相同,只是输出将被写入查询输出通道,由\o设置。 + 这个命令与\echo相同,只是输出会写入由\o设置的查询输出通道。 @@ -2294,9 +1985,7 @@ lo_import 152801 \r\reset - - 重置(清除)查询缓冲区。 - + 重置(清空)查询缓冲区。 @@ -2383,14 +2072,9 @@ testdb=> \setenv LESS -imx4F 定义将打印到当前查询输出通道,由\o设置。 - - 目标函数可以仅通过名称指定,也可以通过名称和参数指定,例如foo(integer, text)。 - 如果有多个同名函数,则必须给出参数类型。 - + 目标函数可以只用名称指定,也可以同时给出名称和参数,例如foo(integer, text)。如果存在多个同名函数,就必须给出参数类型。 - - 如果在命令名称后添加+,则输出的行将被编号,函数体的第一行将被标记为第1行。 - + 如果在命令名后附加+,输出行会带上行号,函数体的第一行编号为 1。 与大多数其他元命令不同,整个行的剩余部分始终被视为\sf的参数, @@ -2405,8 +2089,7 @@ testdb=> \setenv LESS -imx4F - 这个命令获取并显示指定视图的定义,以CREATE OR REPLACE VIEW命令的形式。 - 定义将打印到当前查询输出通道,由\o设置。 + 这个命令获取指定视图的定义,并以CREATE OR REPLACE VIEW命令的形式显示。定义会打印到由\o设置的当前查询输出通道。 @@ -2425,10 +2108,7 @@ testdb=> \setenv LESS -imx4F \t - - 切换显示输出列名标题和行数页脚。此命令等效于\pset tuples_only, - 仅为方便起见提供。 - + 切换输出中的列名标题和行数页脚的显示状态。这个命令等价于\pset tuples_only,提供它是为了使用方便。 @@ -2436,10 +2116,7 @@ testdb=> \setenv LESS -imx4F \T table_options - - 指定在table标签中放置的属性,在HTML输出格式中。 - 该命令等效于\pset tableattr table_options。 - + 指定在HTML输出格式中放在table标签内的属性。这个命令等价于\pset tableattr table_options @@ -2447,10 +2124,7 @@ testdb=> \setenv LESS -imx4F \timing [ on | off ] - - 使用参数,打开或关闭显示每个SQL语句执行时间的功能。没有参数时,切换显示开关。 - 显示的时间单位为毫秒;超过1秒的时间间隔也以分钟:秒的格式显示,如有必要还会显示小时和天。 - + 带参数时,开启或关闭每条 SQL 语句执行耗时的显示。不带参数时,切换显示的开关状态。耗时以毫秒显示;超过 1 秒的时间间隔还会以分钟:秒的格式显示,必要时添加小时和天字段。 @@ -2477,15 +2151,9 @@ testdb=> \setenv LESS -imx4F \unset name - - 取消设置(删除)psql变量name。 - + 取消设置(删除)psql变量name - - 大多数控制psql行为的变量不能被取消设置;相反,\unset命令被解释为将它们设置为默认值。 - 请参见下面的。 - + 大多数控制psql行为的变量不能取消设置;对于这些变量,\unset命令会被解释为将其设置为默认值。参见下面的 @@ -2494,15 +2162,9 @@ testdb=> \setenv LESS -imx4F \w\write filename \w\write |command - - 将当前查询缓冲区写入文件filename,或者通过管道传给 shell 命令command。 - 如果当前查询缓冲区为空,则写入最近执行的查询。 - + 将当前查询缓冲区写入文件filename,或通过管道传递给 shell 命令command。如果当前查询缓冲区为空,则改为写入最近执行的查询。 - - 如果参数以|开头,则整个剩余部分的行被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分的行会被直接传递给shell。 - + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 @@ -2534,9 +2196,7 @@ testdb=> \setenv LESS -imx4F \x [ on | off | auto ] - - 设置或切换扩展表格格式模式。因此,它等同于\pset expanded。 - + 设置或切换扩展表格格式模式。它等价于\pset expanded @@ -2544,8 +2204,7 @@ testdb=> \setenv LESS -imx4F \z [ pattern ] - - 列出表、视图和序列及其相关访问权限。如果指定了 pattern,则只列出名称与模式匹配的表、视图和序列。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 + 列出表、视图和序列及其关联的访问权限。如果指定了pattern,则只列出名称匹配该模式的表、视图和序列。 这是\dp的别名(显示权限)。 @@ -2558,13 +2217,11 @@ testdb=> \setenv LESS -imx4F \! [ command ] - 不带参数时,转义到一个子shell;psql在子shell退出时恢复。 - 带参数时,执行shell命令command。 + 不带参数时,进入一个子 shell;子 shell 退出后,psql恢复运行。带参数时,执行 shell 命令command - 与大多数其他元命令不同,整个行的剩余部分始终被视为\!的参数, - 在参数中不执行变量插值或反引号扩展。行的其余部分被直接传递给shell。 + 与大多数其他元命令不同,该行剩余的全部内容始终被视为\!的参数,其中不会进行变量插值或反引号扩展。该行剩余内容会原样传给 shell。 @@ -2576,7 +2233,7 @@ testdb=> \setenv LESS -imx4F 显示帮助信息。可选的topic参数 (默认为commands)选择要解释的psql的哪个部分: - commands描述psql的反斜杠命令; + commands描述psql的反斜线命令; options描述可以传递给psql的命令行选项; 而variables显示关于psql配置变量的帮助。 @@ -2587,21 +2244,13 @@ testdb=> \setenv LESS -imx4F \; - - 反斜杠分号不像前面的命令那样是一个元命令;相反,它只是在不进行进一步处理的情况下将一个分号添加到查询缓冲区中。 - + 反斜线加分号并不是与前述命令相同的元命令;它只是将一个分号添加到查询缓冲区,而不进行任何进一步处理。 - - 通常,psql会在到达命令结束的分号时立即将SQL命令发送到服务器,即使当前行还有更多输入。因此,例如输入 - + 通常,psql一遇到结束命令的分号,就会将 SQL 命令发送给服务器,即使当前行仍有更多输入也是如此。例如,输入 select 1; select 2; select 3; - - 将导致三个SQL命令分别发送到服务器,每个命令的结果在继续下一个命令之前显示。然而,输入为\;的分号不会触发命令处理,因此它之前和之后的命令实际上被合并并作为一个请求发送到服务器。因此,例如 - +会将这三条 SQL 命令分别发送给服务器,每条命令的结果会在继续处理下一条命令之前显示。不过,以以下形式输入的分号:\;,不会触发命令处理,因此它前后的命令实际上会合并到一个请求中发送给服务器。例如,输入 select 1\; select 2\; select 3; - - 在到达非反斜杠分号时将三个SQL命令发送到服务器的单个请求中。 - 服务器将执行此类请求作为单个事务,除非字符串中包含明确的BEGIN/COMMIT命令将其分成多个事务。(有关服务器如何处理多查询字符串的更多详细信息,请参见。) +会在遇到未加反斜线的分号时,将这三条 SQL 命令作为一个请求发送给服务器。服务器会将这样的请求作为单个事务执行,除非字符串中包含显式的BEGIN/COMMIT命令,将其划分为多个事务。(有关服务器如何处理多查询字符串的更多细节,请参见。)psql对每个请求只打印收到的最后一个查询结果;在这个示例中,虽然三条SELECT命令确实都会执行,但psql只打印3 @@ -2609,16 +2258,16 @@ select 1\; select 2\; select 3; - + 模式 - patterns + 模式 在 psql 和 pg_dump 中 - 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要把它写成两个相邻的双引号,这同样是符合 SQL 引用标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你不能只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 + 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要在双引号包围的文本内把它写成两个相邻的双引号,这同样是符合 SQL 加引号标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你可以只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 @@ -2630,21 +2279,15 @@ select 1\; select 2\; select 3; - 包含点(.)的关系模式被解释为模式名称后跟对象名称模式。例如, - \dt foo*.*bar*显示所有位于模式名以foo开头的模式中、且表名包含bar的表。当没有出现点时,模式仅匹配当前模式搜索路径中可见的对象。 - 再次,双引号内的点失去其特殊含义,被视为字面匹配。包含两个点(.)的关系模式 - 被解释为数据库名称后跟模式名称后跟对象名称模式。数据库名称部分不会被视为模式,必须匹配当前连接的数据库名称, - 否则将引发错误。 + 如果用于匹配关系名的模式包含一个点(.),则会被解释为模式名的匹配模式,后接对象名的匹配模式。例如,\dt foo*.*bar*会显示所有位于模式名以foo开头的模式中、且表名包含bar的表。如果没有点,则只匹配当前模式搜索路径中可见的对象。同样,双引号内的点会失去特殊含义,按字面匹配。如果用于匹配关系名的模式包含两个点(.),则会被解释为数据库名、模式名的匹配模式和对象名的匹配模式。数据库名部分不会被当作匹配模式,必须与当前连接的数据库名相同,否则会报错。 - 包含一个点(.)的模式被解释为数据库名称后跟模式的模式名称。例如, - \dn mydb.*foo*显示所有包含foo的模式。数据库名称部分不会被视为模式, - 必须匹配当前连接数据库的名称,否则将引发错误。 + 如果用于匹配模式名的模式包含一个点(.),则会被解释为数据库名,后接模式名的匹配模式。例如,\dn mydb.*foo*会显示名称中包含foo的所有模式。数据库名部分不会被当作匹配模式,必须与当前连接的数据库名相同,否则会报错。 - 高级用户可以使用字符类等正则表达式记法,如[0-9]可以匹配任意数字。所有的正则表达式特殊字符都按照所说的工作,以下字符除外:.会按照上面所说的作为一种分隔符,*会被翻译成正则表达式记号.*?会被翻译成.,而$则按字面意思匹配。根据需要,可以通过书写?(R+|)(R|)R?来分别模拟模式字符.R*R?$不需要作为一个正则表达式字符,因为模式必须匹配整个名称,而不是像正则表达式的常规用法那样解释(换句话说,$会被自动地追加到模式上)。如果不希望该模式的匹配位置被固定,可以在开头或者结尾写上*。注意在双引号内,所有的正则表达式特殊字符会失去其特殊含义并且按照其字面意思进行匹配。还有,在操作符名称模式中(即作为\do的参数),正则表达式特殊字符也按照字面意思进行匹配。 + 高级用户可以使用字符类等正则表达式记法,如[0-9]可以匹配任意数字。所有的正则表达式特殊字符都按照所说的工作,以下字符除外:.会按照上面所说的作为一种分隔符,*会被翻译成正则表达式记号.*?会被翻译成.,而$则按字面意思匹配。根据需要,可以用?模拟.,用(R+|)模拟R*,或用(R|)模拟R?$不需要作为一个正则表达式字符,因为模式必须匹配整个名称,而不是像正则表达式的常规用法那样解释(换句话说,$会被自动地追加到模式上)。如果不希望该模式的匹配位置被固定,可以在开头或者结尾写上*。注意在双引号内,所有的正则表达式特殊字符会失去其特殊含义并且按照其字面意思进行匹配。还有,在操作符名称模式中(即作为\do的参数),正则表达式特殊字符也按照字面意思进行匹配。 @@ -2652,7 +2295,7 @@ select 1\; select 2\; select 3; 高级特性 - + 变量 @@ -2673,7 +2316,7 @@ bar - 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要重置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 + 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要取消设置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 @@ -2687,7 +2330,7 @@ bar - 控制psql行为的变量通常不能被重置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse。 + 控制psql行为的变量通常不能被取消设置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse @@ -2705,7 +2348,7 @@ bar - 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被重置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交打开模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身即不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 + 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被取消设置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交关闭模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身既不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 @@ -2735,7 +2378,7 @@ bar DBNAME - 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -2744,7 +2387,7 @@ bar ECHO - 如果被设置为all,所有非空输入行会被按照读入它们的样子打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被重置或者设置为none(默认值)则不会显示任何查询。 + 如果被设置为all,所有非空输入行会在读入时打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被设置为none(默认值)则不会显示任何查询。 @@ -2762,7 +2405,7 @@ bar ENCODING - 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者重置。 + 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者取消设置。 @@ -2780,12 +2423,12 @@ bar FETCH_COUNT - 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每一组就会包括这么多个行。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 + 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每组包含的行数等于该整数值。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 - 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT个行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 + 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 @@ -2814,7 +2457,7 @@ bar HISTCONTROL - 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则匹配之前的历史行的行不会被放入。值ignoreboth组合了上述两种值。如果被重置或者被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 + 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则与上一条历史记录相同的行不会被放入。值ignoreboth组合了上述两种值。如果被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 @@ -2828,7 +2471,7 @@ bar HISTFILE - 该文件名将被用于存储历史列表。如果被重设,文件名将从PSQL_HISTORY环境变量中取得。如果该环境变量也没有被设置,则默认值是~/.psql_history,在Windows上是%APPDATA%\postgresql\psql_history。例如, + 该文件名将被用于存储历史列表。如果未设置该变量,文件名将从PSQL_HISTORY环境变量中取得。如果该环境变量也没有被设置,则默认值是~/.psql_history,在Windows上是%APPDATA%\postgresql\psql_history。例如, \set HISTFILE ~/.psql_history-:DBNAME @@ -2860,7 +2503,7 @@ bar HOST - 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -2869,7 +2512,7 @@ bar IGNOREEOF - 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须键入多个连续的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 + 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须连续键入与该数值相等数量的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 @@ -2883,8 +2526,8 @@ bar LASTOID - 最后被影响的 OID 的值,这可能会由INSERT或者\lo_import命令返回。这个变量只保证在下一个SQL命令被显示完之前有效。 - PostgreSQL 服务器从12版开始不再支持 OID 系统列,因此,在面向此类服务器时,跟随在INSERT后面的 LASTOID 将始终为0。 + 最后被影响的 OID 的值,这可能会由INSERT或者\lo_import命令返回。这个变量仅保证在下一个SQL命令的结果显示完之前有效。 + PostgreSQL 服务器从12版开始不再支持 OID 系统列,因此,在面向此类服务器时,执行INSERT后的 LASTOID 将始终为0。 @@ -2909,7 +2552,7 @@ bar - 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被重置或者设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 + 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 @@ -2930,7 +2573,7 @@ bar PORT - 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -2969,7 +2612,7 @@ bar SERVER_VERSION_NUM - 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者重设。 + 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者取消设置。 @@ -2982,7 +2625,7 @@ bar SHOW_CONTEXT - 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT域。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 + 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT字段。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 当VERBOSITY被设置为tersesqlstate时,这个设置无效(另见\errverbose,它可以用来得到刚遇到的错误的详细信息)。 @@ -3001,7 +2644,7 @@ bar SINGLESTEP - 设置这个变量为on等效于命令选项。 + 设置这个变量为on等效于命令行选项 @@ -3019,7 +2662,7 @@ bar USER - 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -3028,7 +2671,7 @@ bar VERBOSITY - 这个变量可以被设置为值defaultverboseterse或者sqlstate来控制错误报告的详细程度(另见\errverbose,在想得到之前的错误的详细版本时使用)。 + 这个变量可以被设置为值defaultverboseterse或者sqlstate来控制错误报告的详细程度(另见\errverbose,在想得到刚遇到的错误的详细信息时使用)。 @@ -3039,7 +2682,7 @@ bar VERSION_NUM - 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或重设。 + 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或取消设置。 @@ -3049,11 +2692,11 @@ bar - - <acronym>SQL</acronym> 中插入变量 + + <acronym>SQL</acronym> 插值 - psql变量的一个关键特性是可以把它们替换(插入)到常规SQL语句中,也可以把它们作为元命令的参数。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。插入一个值而不加引号的语法是在变量名前面加上一个冒号(:)。例如, + psql变量的一个关键特性是可以把它们替换(插值)到常规SQL语句中,也可以把它们替换到元命令的参数中。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。不加引号地插值一个值的语法是在变量名前面加上一个冒号(:)。例如, testdb=> \set foo 'my_table' testdb=> SELECT * FROM :foo; @@ -3062,7 +2705,7 @@ testdb=> SELECT * FROM :foo; - 当一个值被用作 SQL 文本或者标识符时,最安全的是把它加上引用。要引用一个变量的值作为 SQL 文本,可以把变量名称放在单引号中并且在引号前面写一个冒号。要引用作为 SQL 标识符,则可以把变量名称放在双引号中并且在引号前面写一个冒号。这种结构可以正确地处理变量值中嵌入的引号和其他特殊字符。之前的示例用这种方法写会更安全: + 当一个值要用作 SQL 字面量或标识符时,最安全的做法是为它加上引号。要将变量值作为 SQL 字面量加引号,应写一个冒号,后面跟用单引号括起来的变量名。要将变量值作为 SQL 标识符加引号,则在冒号后面用双引号括起变量名。这些写法能正确处理变量值中嵌入的引号和其他特殊字符。前面的示例可用以下更安全的写法: testdb=> \set foo 'my_table' testdb=> SELECT * FROM :"foo"; @@ -3070,11 +2713,11 @@ testdb=> SELECT * FROM :"foo"; - 在被引用的SQL文本和标识符中将不会执行变量插入。因此,一个诸如':foo'的结构不会从一个变量的值产生一个被引用的文本(即便能够也会不安全,因为无法正确地处理嵌入在值中的引号)。 + 在加引号的SQL字面量和标识符内部,不会执行变量插值。因此,':foo'这样的写法不能根据变量值生成加引号的字面量(即使能够生效,也不安全,因为它无法正确处理变量值中嵌入的引号)。 - 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个被引用的字符串插入: + 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个加引号的字符串进行插值: testdb=> \set content `cat my_file.txt` testdb=> INSERT INTO my_table VALUES (:'content'); @@ -3083,7 +2726,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 因为冒号可以合法地出现在 SQL 命令中,一次明显的插入尝试(即:name:'name'或者:"name")不会被替换,除非所提及的变量就是当前被设置的。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 + 因为冒号可以合法地出现在 SQL 命令中,一次明显的插值尝试(即:name:'name'或者:"name")不会被替换,除非所指的变量当前已设置。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 @@ -3091,12 +2734,12 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 文本或者标识符的冒号引用语法是一种psql扩展。 + 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 字面量或者标识符的冒号加引号语法是一种psql扩展。 - + 提示符 @@ -3110,33 +2753,26 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %M - - 数据库服务器的完整主机名(带域名);如果连接通过 Unix 域套接字建立,则为 [local];如果 Unix 域套接字不在编译时默认位置,则为 [local:/dir/name]。 - + 数据库服务器的完整主机名(含域名);如果通过 Unix 域套接字连接,则为[local];如果 Unix 域套接字不在编译时指定的默认位置,则为[local:/dir/name] %m - - 数据库服务器的主机名,在第一个点处分截;如果连接通过 Unix 域套接字建立,则为 [local]。 - + 数据库服务器的主机名,在第一个点号处截断;如果通过 Unix 域套接字连接,则为[local] %> - 数据库服务器正在监听的端口号。 + 数据库服务器监听的端口号。 %n - - 数据库会话用户名。(由于 SET SESSION - AUTHORIZATION 命令的作用,该值在数据库会话期间可能会发生变化。) - + 数据库会话用户名。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) @@ -3155,11 +2791,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %# - - 如果会话用户是数据库超级用户,则输出 - #,否则输出 >。(由于 SET SESSION - AUTHORIZATION 命令的作用,该值的展开在数据库会话期间可能会发生变化。) - + 如果会话用户是数据库超级用户,则为#,否则为>。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) @@ -3175,7 +2807,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %R - 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 dollar-quoted 字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 + 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 美元引用字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 @@ -3202,7 +2834,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %digits - 带有所示八进制码的字符被替换。 + 替换为指定八进制代码对应的字符。 @@ -3274,44 +2906,19 @@ testdb=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# ' 命令行编辑 - - Readline - 在 psql 中 - - - libedit - 在 psql 中 - - - 如果可用,psql 会使用Readlinelibedit库,以便进行便捷的行编辑和历史检索。当psql退出时,命令历史会自动保存;当psql启动时,又会重新载入。输入上箭头或 control-P 可以取回之前的行。 - - - - 在许多(绝非全部)上下文中,还可以使用 TAB 补全部分输入的关键字和 SQL 对象名。例如,在命令开头输入ins并按下 TAB 键,会补全为insert into 。然后输入表名或模式名的几个字符,再按下TAB键,就会补全尚未输完的名称;如果有多个候选项,则会给出可能的补全菜单。(具体取决于所使用的库,可能需要按多次TAB键才能看到菜单。) - - - - 对 SQL 对象名进行 TAB 补全时,需要向服务器发送查询来查找可能的匹配项。在某些上下文中,这可能会干扰其他操作。 - 例如,在BEGIN之后,如果中间发出了一次 TAB 补全查询,那么再发出SET TRANSACTION ISOLATION LEVEL就为时已晚了。 - 如果根本不想使用 TAB 补全,可以把下面的内容放到主目录中名为.inputrc的文件里,从而永久关闭它: - + psql支持 Readline 库,便于编辑和检索输入行。命令历史记录会在 psql 退出时自动保存,并在 psql 启动时重新载入。也支持 Tab 补全,不过其补全逻辑并不声称自己是 SQL 解析器。Tab 补全生成的查询还可能干扰其他 SQL 命令,例如 SET + TRANSACTION ISOLATION LEVEL。如果出于某种原因你不喜欢 Tab 补全,可以将以下内容放入主目录下名为 .inputrc 的文件中,将其关闭: $if psql set disable-completion on $endif - - (这不是psql而是一个Readline功能。阅读其文档以获取更多详细信息。) - - - - )命令行选项也可用于在单次运行psql时禁用 Readline。这会阻止制表补全、命令行历史的使用或记录,以及多行命令的编辑。当你需要复制粘贴包含 TAB 字符的文本时,它尤其有用。 - +(这不是 psql 的功能,而是 Readline 的功能。更多细节请阅读其文档。) - + 环境 @@ -3396,29 +3003,16 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 如果查询结果无法在屏幕上显示完整,它们将通过此命令进行传输。典型的值是moreless。 + 如果查询结果无法在屏幕上显示完整,它们会通过管道传给此命令。典型的值是moreless。 可以通过将PSQL_PAGERPAGER设置为空字符串,或通过调整\pset命令的与分页相关的选项来禁用分页器。 - 这些变量按照列出的顺序进行检查;首先设置的变量将被使用。 + 这些变量按照列出的顺序进行检查;使用按该顺序找到的第一个已设置的变量。 如果它们都没有设置,默认情况下在大多数平台上使用more,但在Cygwin上使用less - - PSQL_WATCH_PAGER - - - - 当使用 \watch - 命令重复执行查询时,默认不会使用分页器。在 Unix 系统上,可以通过将 PSQL_WATCH_PAGER 设置为分页器命令来改变这一行为。pspg 分页器(不是 - PostgreSQL 的一部分,但在许多开源软件发行版中可用)如果以 - --stream 选项启动,就可以显示 - \watch 的输出。 - - - PSQLRC @@ -3474,14 +3068,13 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' 用户的个人启动文件名为.psqlrc,并且在调用用户的主目录中寻找。 - 在Windows上,个人启动文件的名称改为%APPDATA%\postgresql\psqlrc.conf。 + Windows 没有主目录这一概念,在 Windows 上,个人启动文件的名称为%APPDATA%\postgresql\psqlrc.conf。 在任何情况下,可以通过设置PSQLRC环境变量来覆盖此默认文件路径。 - 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加破折号和PostgreSQL的主要或次要版本标识符来使其与psql版本相关, - 例如~/.psqlrc-&majorversion;~/.psqlrc-&version;。 + 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加连字符和PostgreSQL的大版本或小版本号来使其与psql版本相关, + 例如~/.psqlrc-9.2~/.psqlrc-9.2.5。 最具体版本匹配的文件将优先读取,而不是非特定版本的文件。 - 这些版本后缀是在确定文件路径后添加的,如上所述。 @@ -3506,14 +3099,14 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - psql最适合与相同或较旧主要版本的服务器配合使用。 - 如果服务器的版本比psql本身更新,反斜杠命令特别容易失败。 - 然而,\d系列的反斜杠命令应该可以在版本回溯到9.2的服务器上运行, + psql最适合与相同或较旧大版本的服务器配合使用。 + 如果服务器的版本比psql本身更新,反斜线命令特别容易失败。 + 然而,\d系列的反斜线命令应该可以在最低至 7.4 版本的服务器上运行, 但不一定适用于比psql本身更新的服务器。运行SQL命令和显示查询结果的一般功能 - 也应该可以在更新主要版本的服务器上运行,但不能保证在所有情况下都能实现。 + 也应该可以在更新大版本的服务器上运行,但不能保证在所有情况下都能实现。 - 如果你想用psql连接到多个具有不同主版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个主版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 + 如果你想用psql连接到多个具有不同大版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个大版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 @@ -3527,7 +3120,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空格。现在则要求一些空格。 + 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空白。现在则要求用空白分隔。 @@ -3700,9 +3293,7 @@ testdb=> \df int*pl * bigint - - 在适合的情况下,可以使用 \crosstabview 命令将查询结果显示为交叉表: - + 在适当的情况下,要以交叉表形式显示查询结果,可以使用\crosstabview命令: testdb=> SELECT first, second, first > 2 AS gt2 FROM my_table; first | second | gt2 -------+--------+----- @@ -3720,10 +3311,7 @@ testdb=> \crosstabview first second 3 | | | t | 4 | | | | t (4 rows) - - -第二个示例展示了一个乘法表,其中行按数字倒序排列,而列按独立的升序数字排列。 - +第二个示例显示一个乘法表,行按数值降序排列,列则独立地按数值升序排列。 testdb=> SELECT t1.first as "A", t2.first+100 AS "B", t1.first*(t2.first+100) as "AxB", testdb-> row_number() over(order by t2.first) AS ord testdb-> FROM my_table t1 CROSS JOIN my_table t2 ORDER BY 1 DESC diff --git a/zh/14/release-14.sgml b/zh/14/release-14.sgml index 6737a778..7493dcf1 100644 --- a/zh/14/release-14.sgml +++ b/zh/14/release-14.sgml @@ -1508,7 +1508,7 @@ Branch: REL_14_STABLE [dda622edc] 2026-08-02 16:49:18 -0400 --> - 修复为文本搜索词典创建缓存条目的过程中发生内存不足后导致的崩溃 + 修复为文本检索词典创建缓存条目的过程中发生内存不足后导致的崩溃 (Tom Lane) § @@ -3210,7 +3210,7 @@ Branch: REL_14_STABLE [6cae0c2bd] 2026-04-22 11:09:21 -0400 损坏或恶意的词缀文件可能使服务器崩溃。 - 这不被视为安全问题,因为文本搜索配置文件被假定为可信, + 这不被视为安全问题,因为文本检索配置文件被假定为可信, 但仍然值得修复。 @@ -15636,7 +15636,7 @@ Branch: REL_12_STABLE [3b4580f5c] 2023-06-24 17:18:08 -0400 Branch: REL_11_STABLE [c7f33a197] 2023-06-24 17:18:08 -0400 --> - 防止非常复杂的文本搜索模式导致栈溢出崩溃 + 防止非常复杂的文本检索模式导致栈溢出崩溃 (Tom Lane) § @@ -18131,7 +18131,7 @@ Branch: REL_12_STABLE [1aed4c4fd] 2022-11-21 17:07:07 -0500 Branch: REL_11_STABLE [c0eed8891] 2022-11-21 17:07:07 -0500 --> - 确保在执行短语匹配时可以取消全文搜索查询的执行(Tom Lane) + 确保在执行短语匹配时可以取消全文检索查询的执行(Tom Lane) § diff --git a/zh/14/rowtypes.sgml b/zh/14/rowtypes.sgml index 6e5f9eab..2ac62b5b 100644 --- a/zh/14/rowtypes.sgml +++ b/zh/14/rowtypes.sgml @@ -75,7 +75,7 @@ CREATE TABLE inventory_item ( - 构造组合值 + 构造复合值 复合类型 @@ -83,7 +83,7 @@ CREATE TABLE inventory_item ( - 要把组合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,组合常量的一般格式如下: + 要把复合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,复合常量的一般格式如下: '( val1 , val2 , ... )' @@ -103,11 +103,11 @@ CREATE TABLE inventory_item ( - (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。必要时可能需要显式指定类型。) + (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。可能需要显式指定类型,以指明应将该常量转换为哪种类型。) - ROW表达式语法也可以用于构造组合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: + ROW表达式语法也可以用于构造复合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: ROW('fuzzy dice', 42, 1.99) ROW('', 42, NULL) @@ -126,7 +126,7 @@ ROW('', 42, NULL) 访问复合类型 - 要访问组合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: + 要访问复合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: SELECT item.name FROM on_hand WHERE item.price > 9.99; @@ -148,7 +148,7 @@ SELECT (on_hand.item).name FROM on_hand WHERE (on_hand.item).price > 9.99; - 无论何时从组合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回组合值的函数结果中只选取一个字段,你需要这样写: + 无论何时从复合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回复合值的函数结果中只选取一个字段,你需要这样写: SELECT (my_func(...)).field FROM ... @@ -164,10 +164,10 @@ SELECT (my_func(...)).field FROM ... - 修改组合值 + 修改复合类型 - 下面是一些插入和更新组合列时正确语法的示例。先看插入或更新整个列值的情况: + 下面是一些插入和更新复合列时正确语法的示例。先看插入或更新整个列值的情况: INSERT INTO mytab (complex_col) VALUES((1.1,2.2)); @@ -179,7 +179,7 @@ UPDATE mytab SET complex_col = ROW(1.1,2.2) WHERE ...; - 我们也可以更新组合列中的单个子字段: + 我们也可以更新复合列中的单个子字段: UPDATE mytab SET complex_col.r = (complex_col).r + 1 WHERE ...; @@ -208,11 +208,11 @@ INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2); - 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的组合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: + 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的复合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: SELECT c FROM inventory_item c; - 这个查询会产生一个单独的组合值列,因此我们可能得到如下输出: + 这个查询会产生一个单独的复合值列,因此我们可能得到如下输出: c ------------------------ @@ -223,7 +223,7 @@ SELECT c FROM inventory_item c; - 普通的限定列名语法table_name.column_name可以理解为对该表当前行的组合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) + 普通的限定列名语法table_name.column_name可以理解为对该表当前行的复合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) @@ -256,19 +256,19 @@ SELECT (myfunc(x)).a, (myfunc(x)).b, (myfunc(x)).c FROM some_table; SELECT m.* FROM some_table, LATERAL myfunc(x) AS m; - 把该函数放在LATERAL FROM项中,可以防止它对每一行被调用多于一次。m.*仍会展开为m.a, m.b, m.c,但现在这些变量只是对该FROM项输出的引用。(这里的LATERAL关键字其实是可选的,不过我们把它写出来,是为了明确该函数会从some_table中取得x。) + 把该函数放在LATERAL FROM项中,可以避免它在每行上被调用多次。m.*仍会展开为m.a, m.b, m.c,但现在这些变量只是对该FROM项输出的引用。(这里的LATERAL关键字其实是可选的,不过我们把它写出来,是为了明确该函数会从some_table中取得x。) - 当composite_value.*出现在SELECT输出列表、INSERT/UPDATE/DELETE/MERGE中的RETURNING列表、VALUES子句或行构造器的顶层时,就会产生这种列展开行为。在所有其他上下文中(包括嵌套在上述结构之内时),给组合值附加.*不会改变其值,因为它表示所有列,因此结果仍然是同一个组合值。例如,如果somefunc()接受一个组合值参数,这些查询就是等价的: + 当composite_value.*出现在SELECT输出列表、INSERT/UPDATE/DELETE中的RETURNING列表、VALUES子句或行构造器的顶层时,就会产生这种列展开行为。在所有其他上下文中(包括嵌套在上述结构之内时),给复合值附加.*不会改变其值,因为它表示所有列,因此结果仍然是同一个复合值。例如,如果somefunc()接受一个复合值参数,这些查询就是等价的: SELECT somefunc(c.*) FROM inventory_item c; SELECT somefunc(c) FROM inventory_item c; - 在这两种情况下,inventory_item的当前行都会作为单个组合值参数传递给该函数。尽管.*在这种场合并不起作用,使用它仍是一种良好风格,因为它能明确表明这里想要的是组合值。特别是,解析器会把c.*中的c视为表名或别名,而不是列名,因此不会产生歧义;而没有.*时,就不清楚c究竟表示表名还是列名,而且如果存在名为c的列,实际上会优先按列名解释。 + 在这两种情况下,inventory_item的当前行都会作为单个复合值参数传递给该函数。尽管.*在这种场合并不起作用,使用它仍是一种良好风格,因为它能明确表明这里想要的是复合值。特别是,解析器会把c.*中的c视为表名或别名,而不是列名,因此不会产生歧义;而没有.*时,就不清楚c究竟表示表名还是列名,而且如果存在名为c的列,实际上会优先按列名解释。 @@ -278,7 +278,7 @@ SELECT * FROM inventory_item c ORDER BY c; SELECT * FROM inventory_item c ORDER BY c.*; SELECT * FROM inventory_item c ORDER BY ROW(c.*); - 所有这些ORDER BY子句都指定了该行的组合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: + 所有这些ORDER BY子句都指定了该行的复合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: SELECT * FROM inventory_item c ORDER BY ROW(c.name, c.supplier_id, c.price); SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); @@ -287,7 +287,7 @@ SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); - 另一种与组合值有关的特殊语法行为是,我们可以使用函数记法来提取组合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: + 另一种与复合值有关的特殊语法行为是,我们可以使用函数记法来提取复合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: SELECT c.name FROM inventory_item c WHERE c.price > 1000; @@ -306,11 +306,11 @@ SELECT c.somefunc FROM inventory_item c; 函数记法与字段记法之间的这种等价性,使得我们可以通过在复合类型上使用函数来实现计算字段 - computed field + 计算字段 - field - computed + 字段 + 计算 使用上面最后一种查询形式的应用程序,无需直接知道somefunc并不是该表中的真实列。 @@ -328,7 +328,7 @@ SELECT c.somefunc FROM inventory_item c; 复合类型的输入和输出语法 - 组合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明组合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 + 复合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明复合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 '( 42)' @@ -336,7 +336,7 @@ SELECT c.somefunc FROM inventory_item c; - 如前所示,在写组合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让组合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的组合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作组合语法的数据字符。 + 如前所示,在写复合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让复合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的复合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作复合语法的数据字符。 @@ -350,18 +350,18 @@ SELECT c.somefunc FROM inventory_item c; - 记住,你在 SQL 命令中写的内容会先被解释为字符串字面量,然后才会被解释为组合值。这会使所需的反斜杠数量翻倍(假定使用的是转义字符串语法)。例如,要在组合值中插入一个包含双引号和反斜杠的text字段,需要写成: + 记住,你在 SQL 命令中写的内容会先被解释为字符串字面量,然后才会被解释为复合值。这会使所需的反斜杠数量翻倍(假定使用的是转义字符串语法)。例如,要在复合值中插入一个包含双引号和反斜杠的text字段,需要写成: INSERT ... VALUES ('("\"\\")'); - 字符串字面量处理器会去掉一层反斜杠,因此传到组合值解析器时看起来是("\"\\")。随后,送入text数据类型输入例程的字符串就变成了"\。(如果我们使用的数据类型的输入例程也会把反斜杠当作特殊字符处理,例如bytea,那么为了在存储的组合字段中得到一个反斜杠,命令里可能需要多达八个反斜杠。)美元引用(见)可用于避免反斜杠加倍的需要。 + 字符串字面量处理器会去掉一层反斜杠,因此传到复合值解析器时看起来是("\"\\")。随后,送入text数据类型输入例程的字符串就变成了"\。(如果我们使用的数据类型的输入例程也会把反斜杠当作特殊字符处理,例如bytea,那么为了在存储的复合字段中得到一个反斜杠,命令里可能需要多达八个反斜杠。)美元引用(见)可用于避免反斜杠加倍的需要。 - 在 SQL 命令中编写组合值时,ROW构造器语法通常比组合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是组合成员时完全相同。 + 在 SQL 命令中编写复合值时,ROW构造器语法通常比复合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是复合成员时完全相同。 diff --git a/zh/14/textsearch.sgml b/zh/14/textsearch.sgml index 51eea368..47c386ab 100644 --- a/zh/14/textsearch.sgml +++ b/zh/14/textsearch.sgml @@ -1,21 +1,21 @@ - 全文搜索 + 全文检索 - 全文搜索 + 全文检索 - 文本搜索 + 文本检索 介绍 - 全文搜索(或简称文本搜索)提供了识别满足 + 全文检索(或简称文本检索)提供了识别满足 查询条件的自然语言文档的能力, 并且可按它们与查询的相关度进行排序。最常见的搜索类型,是找出所有包含给定 查询词的文档,并按它们与查询的相似性 @@ -25,7 +25,7 @@ - 文本搜索操作符在数据库中已经存在很多年了。 + 文本检索操作符在数据库中已经存在很多年了。 PostgreSQL为文本数据类型提供了 ~~*LIKEILIKE 操作符,但它们缺少现代信息系统所要求的许多关键特性: @@ -138,7 +138,7 @@ ()。围绕这两种数据类型还有许多函数和 操作符(),其中最重要的是匹配操作符 @@,我们将在中介绍。 - 全文搜索还可以借助索引加速()。 + 全文检索还可以借助索引加速()。 @@ -147,11 +147,11 @@ 文档 - 全文搜索 + 文本检索 - 文档是全文搜索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本搜索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 + 文档是全文检索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本检索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 @@ -179,7 +179,7 @@ WHERE m.mid = d.did AND m.mid = 12; - 为了进行文本搜索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 + 为了进行文本检索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 @@ -187,7 +187,7 @@ WHERE m.mid = d.did AND m.mid = 12; 基本文本匹配 - 在PostgreSQL中,全文搜索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: + 在PostgreSQL中,全文检索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: SELECT 'a fat cat sat on a mat and ate a fat rat'::tsvector @@ 'cat & rat'::tsquery; @@ -203,7 +203,7 @@ SELECT 'fat & cow'::tsquery @@ 'a fat cat sat on a mat and ate a fat rat'::t - 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索术语,这些术语必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个术语组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本搜索匹配更像是这样: + 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索词,这些搜索词必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个搜索词组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本检索匹配更像是这样: SELECT to_tsvector('fat cats ate fat rats') @@ to_tsquery('fat & rat'); @@ -221,7 +221,7 @@ SELECT 'fat cats ate fat rats'::tsvector @@ to_tsquery('fat & rat'); f - 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,默认假定已经正规化,因此 rats 不会匹配 rat。 + 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,被假定为已经正规化,因此 rats 不会匹配 rat @@ -290,49 +290,49 @@ SELECT phraseto_tsquery('the cats ate the rats'); 配置 - 前述的都是简单的文本搜索示例。正如前面所提到的,全文搜索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如基于空白之外的解析。这个功能由文本搜索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 + 前述的都是简单的文本检索示例。正如前面所提到的,全文检索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如不局限于按空白划分的解析。这个功能由文本检索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 - 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本搜索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config。 + 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本检索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config - 依赖一个配置的每一个文本搜索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当这个参数被忽略时,default_text_search_config才被使用。 + 依赖一个配置的每一个文本检索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当省略这个参数时,default_text_search_config才被使用。 - 为了让建立自定义文本搜索配置更容易,一个配置可以从更简单的数据库对象来建立。PostgreSQL的文本搜索功能提供了四类配置相关的数据库对象: + 为了便于构建自定义文本检索配置,配置由更简单的数据库对象组合而成。PostgreSQL 的文本检索功能提供了四类与配置相关的数据库对象: - 文本搜索解析器将文档拆分成词元并分类每个词元(例如,作为词或者数字)。 + 文本检索解析器将文档拆分成词元并对每个词元分类(例如,作为词或者数字)。 - 文本搜索词典将词元转变成正规化的形式并拒绝停用词。 + 文本检索词典将词元转变成正规化的形式并拒绝停用词。 - 文本搜索模板提供位于词典底层的函数(一个词典简单地指定一个模板和一组用于模板的参数)。 + 文本检索模板提供位于词典底层的函数(词典只需指定一个模板及其一组参数)。 - 文本搜索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 + 文本检索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 - 文本搜索解析器和模板是从低层 C 函数构建而来,因此它要求 C 编程能力来开发新的解析器和模板,并且还需要超级用户权限来把它们安装到一个数据库中(在PostgreSQL发布的contrib/区域中有一些附加的解析器和模板的示例)。由于词典和配置只是对底层解析器和模板的参数化和连接,不需要特殊的权限来创建一个新词典或配置。创建定制词典和配置的示例将在本章稍后的部分给出。 + 文本检索解析器和模板由底层 C 函数构成,因此开发新的解析器和模板需要 C 编程能力,将它们安装到数据库中则需要超级用户权限。(PostgreSQL 发行版的 contrib/ 目录中有附加解析器和模板的示例。)词典和配置只是为底层解析器和模板设置参数并将它们连接起来,因此创建新词典或配置不需要特殊权限。本章后面会给出创建自定义词典和配置的示例。 @@ -343,14 +343,14 @@ SELECT phraseto_tsquery('the cats ate the rats'); 表和索引 - 在前一节中的示例演示了使用简单常数字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 + 在前一节中的示例演示了使用简单常量字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 搜索表 - 即使没有索引,也可以执行全文搜索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend: + 即使没有索引,也可以执行全文检索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend SELECT title @@ -374,7 +374,7 @@ WHERE to_tsvector(body) @@ to_tsquery('friend'); - 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 中同时包含 createtable: + 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 合在一起包含 createtable SELECT title @@ -388,7 +388,7 @@ LIMIT 10; - 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本搜索在实际使用中通常都需要建立索引。 + 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本检索在实际使用中通常都需要建立索引。 @@ -397,13 +397,13 @@ LIMIT 10; 创建索引 - 我们可以创建一个GIN索引()来加速文本搜索: + 我们可以创建一个GIN索引()来加速文本检索: CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector('english', body)); - 注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本搜索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含使用不同文本搜索配置创建的tsvector,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 + 注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本检索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含使用不同文本检索配置创建的tsvector,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 @@ -420,10 +420,7 @@ CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector(config_name, body)); 这里 config_namepgweb 表中的一个列。这样就允许在同一个索引中混合使用不同配置,同时记录每个索引项使用的是哪一种配置。例如,如果文档集合中包含不同语言的文档,这就会很有用。同样,打算使用该索引的查询也必须写成对应的形式,例如 WHERE to_tsvector(config_name, body) @@ 'a & b' - - 索引甚至可以连接列: - - + 索引甚至可以串接多个列: CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector('english', title || ' ' || body)); @@ -443,7 +440,7 @@ ALTER TABLE pgweb CREATE INDEX textsearch_idx ON pgweb USING GIN(textsearchable_index_col); - 现在我们准备好执行一个快速的全文搜索了: + 现在我们准备好执行一个快速的全文检索了: SELECT title @@ -455,7 +452,7 @@ LIMIT 10; - 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本搜索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 + 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本检索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 @@ -463,10 +460,10 @@ LIMIT 10; - 控制文本搜索 + 控制文本检索 - 要实现全文搜索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 + 要实现全文检索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 @@ -485,7 +482,7 @@ to_tsvector( config - to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本搜索配置进行处理。下面是一个简单示例: + to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本检索配置进行处理。下面是一个简单示例: SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); @@ -500,7 +497,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每类词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本搜索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english。 + to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每个词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本检索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english @@ -508,7 +505,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为空,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: + 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为 NULL,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: UPDATE tt SET ti = @@ -659,12 +656,12 @@ websearch_to_tsquery( config - 无引号文本:不在引号中的文本会被转换为由&操作符分隔的词,就像经过plainto_tsquery处理一样。 + 未加引号的文本:不在引号中的文本会被转换为由&操作符分隔的词,就像经过plainto_tsquery处理一样。 - "引号文本":引号中的文本会被转换为由<->操作符分隔的词,就像经过phraseto_tsquery处理一样。 + "加引号的文本":引号中的文本会被转换为由<->操作符分隔的词,就像经过phraseto_tsquery处理一样。 @@ -722,7 +719,7 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); 搜索结果排名 - 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及它们出现于文档中哪个部分。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 + 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及这些词所处文档部分的重要程度。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 @@ -813,12 +810,12 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 8 用文档中唯一词的数量除排名 + 8 用文档中不同词的数量除排名 - 16 用 1 + 文档中唯一词数量的对数除排名 + 16 用 1 + 文档中不同词数量的对数除排名 @@ -832,7 +829,7 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。正规化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 + 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。归一化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 @@ -904,9 +901,7 @@ ts_headline( config ts_headline 接收文档和查询,并返回文档中一段 - 高亮查询词条的摘录。具体而言,该函数会先用查询选择相关文本片段,然后 - 高亮查询中出现的所有词,即使这些词的位置并不满足查询本身的位置限制。 - 用于解析文档的配置可通过 config 指定; + 高亮查询词的摘录。用于解析文档的配置可通过 config 指定; 若省略 config,则使用 default_text_search_config 配置。 @@ -952,7 +947,7 @@ ts_headline( config - 警告:跨站脚本(XSS)安全 + 警告:跨站脚本(XSS)安全性 ts_headline 的输出不保证可安全直接嵌入网页。 当 HighlightAllfalse(默认值)时, @@ -1011,7 +1006,7 @@ occurrences to display in the result.', 附加特性 - 本节介绍一些在文本搜索中很有用的附加函数和操作符。 + 本节介绍一些在文本检索中很有用的附加函数和操作符。 @@ -1124,7 +1119,7 @@ occurrences to display in the result.', - 返回用 AND 结合的两个给定查询。 + 返回两个给定查询的 AND 组合。 @@ -1138,7 +1133,7 @@ occurrences to display in the result.', - 返回用 OR 结合的两个给定查询。 + 返回两个给定查询的 OR 组合。 @@ -1191,7 +1186,7 @@ SELECT to_tsquery('fat') <-> to_tsquery('cat | rat'); - 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: + 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在其后距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: SELECT tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10); @@ -1245,10 +1240,7 @@ SELECT numnode('foo & bar'::tsquery); - - 返回可用于索引搜索的tsquery部分。这个函数可用于检测不可索引的查询,例如只包含停用词或只包含否定项的查询。例如: - - + 返回一个tsquery中可用于搜索索引的部分。此函数可用于检测无法使用索引的查询,例如只包含停用词或只包含否定词项的查询。例如: SELECT querytree(to_tsquery('defined')); querytree ----------- @@ -1424,7 +1416,7 @@ SELECT title, body FROM messages WHERE tsv @@ to_tsquery('title & body'); - 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本搜索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 + 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本检索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 @@ -1491,7 +1483,7 @@ ts_stat(sqlquery text, - 如果提供了 weights,则只统计具有这些权重之一的出现。 + 如果提供了 weights,则只统计具有这些权重之一的词的出现次数。 @@ -1520,7 +1512,7 @@ LIMIT 10; 解析器 - 文本搜索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 + 文本检索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 @@ -1543,12 +1535,12 @@ LIMIT 10; asciiword - 单词,所有 ASCII 字母 + 单词,全部由 ASCII 字母组成 elephant word - 单词,所有字母 + 单词,全部由字母组成 mañana @@ -1558,12 +1550,12 @@ LIMIT 10; asciihword - 带连字符的单词,所有 ASCII + 带连字符的单词,全部为 ASCII 字符 up-to-date hword - 带连字符的单词,所有字母 + 带连字符的单词,由字母组成 lógico-matemática @@ -1573,12 +1565,12 @@ LIMIT 10; hword_asciipart - 带连字符的单词部分,所有 ASCII + 带连字符的单词部分,全部为 ASCII 字符 postgresql-beta1 上下文中的 postgresql hword_part - 带连字符的单词部分,所有字母 + 带连字符的单词部分,全部由字母组成 lógico-matemática 上下文中的 lógicomatemática @@ -1653,8 +1645,8 @@ LIMIT 10; blank - 空格符号 - (其他不识别的任意空白或标点符号) + 空白符号 + (未被识别为其他类型的空白或标点符号) @@ -1662,12 +1654,12 @@ LIMIT 10; - 解析器的一个字母的概念由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时可以用来区别它们。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 + 解析器对字母的界定由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时区分它们会很有用。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 email不支持所有由RFC 5322定义的有效电子邮件字符。 - 具体来说,电子邮件用户名仅支持句号、短横线和下划线这些非字母数字字符。 + 具体来说,电子邮件用户名仅支持句点、短横线和下划线这些非字母数字字符。 @@ -1716,7 +1708,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h 词典 - 词典用于消除不应参与搜索的词(stop words),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 + 词典用于消除不应参与搜索的词(停用词),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 @@ -1731,7 +1723,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - URL地址可以被正规化,以便让等价的 URL 匹配: + URL 地址可以规范化,以便让等价的 URL 匹配: @@ -1776,32 +1768,32 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤字典) + 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤词典 - 如果字典知道该词元但它是一个停用词,则返回一个空数组 + 如果词典知道该词元但它是一个停用词,则返回一个空数组 - 如果字典不识别该输入词元,则返回NULL + 如果词典不识别该输入词元,则返回NULL - PostgreSQL为许多语言提供了预定义的字典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发布的contrib/区域。 + PostgreSQL为许多语言提供了预定义的词典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发行版的contrib/目录。 - 文本搜索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 + 文本检索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 - 配置词典列表的一般规则是,把最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语分类词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: + 配置词典列表的一般规则是,把适用范围最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语同义词词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: ALTER TEXT SEARCH CONFIGURATION astro_en @@ -1810,14 +1802,14 @@ ALTER TEXT SEARCH CONFIGURATION astro_en - 过滤词典可以放在列表中的任何位置,只是不能放在最后,因为放在最后就没有意义了。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 + 过滤词典可以放在列表中的任何位置,但放在末尾没有用处。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 停用词 - 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文搜索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: + 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文检索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: SELECT to_tsvector('english', 'in the list of stop words'); @@ -1949,7 +1941,7 @@ SELECT * FROM ts_debug('english', 'Paris'); - synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基本名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 + synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 @@ -2011,28 +2003,28 @@ mydb=# SELECT 'indexes are very useful'::tsvector @@ to_tsquery('tst', 'indices' - 基本上一个分类词典会用一个首选词替换所有非首选词,并且也可选择地保留原始术语用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典要求一个下列格式的配置文件: + 分类词典基本上会用一个首选词替换所有非首选词,并且也可以选择保留原始词用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典需要一个采用以下格式的配置文件: -# this is a comment -sample word(s) : indexed word(s) -more sample word(s) : more indexed word(s) +# 这是一条注释 +示例词(一个或多个) : 索引词(一个或多个) +更多示例词(一个或多个) : 更多索引词(一个或多个) ... - 其中冒号(:)符号扮演了一个短语及其替换之间的定界符。 + 其中冒号(:)符号用作短语及其替换词之间的分隔符。 - 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过对子词典的应用,但所有样例词都必须能被子词典识别。 + 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过将子词典应用于该词,但所有样例词都必须能被子词典识别。 - 如果有多个短语匹配输入,则分类词典选择最长的那一个,并且使用最后的定义打破连结。 + 如果有多个短语匹配输入,分类词典会选择最长的匹配;长度相同时使用最后的定义。 - 由子词典识别的特定停用词不能够被指定;改用?标记任何可以出现停用词的地方。例如,假定根据子词典athe是停用词: + 由子词典识别的特定停用词不能够被指定;改用?标记可出现任意停用词的位置。例如,假定根据子词典athe是停用词: ? one ? two : swsw @@ -2074,7 +2066,7 @@ CREATE TEXT SEARCH DICTIONARY thesaurus_simple ( - mythesaurus是分类词典配置文件的基础名称(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 + mythesaurus是分类词典配置文件的基名(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 @@ -2099,7 +2091,7 @@ ALTER TEXT SEARCH CONFIGURATION russian 分类词典示例 - 考虑简单的天文词库 thesaurus_astro,其中包含一些天文单词组合: + 考虑一个简单的天文分类词典 thesaurus_astro,其中包含一些天文单词组合: supernovae stars : sn @@ -2167,7 +2159,7 @@ SELECT plainto_tsquery('supernova star'); <application>Ispell</application> 词典 - Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以把搜索词 bank 的词尾变化和词形变化对应起来,例如 bankingbankedbanksbanks'bank's。 + Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以匹配搜索词 bank 的所有变格和变位形式,例如 bankingbankedbanksbanks'bank's @@ -2179,12 +2171,12 @@ SELECT plainto_tsquery('supernova star'); - 要创建一个Ispell词典,执行这三步: + 要创建一个Ispell词典,请执行以下步骤: - 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。有必要抽取.aff.dic文件,把扩展改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): + 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。需要提取.aff.dic文件,将扩展名改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): iconv -f ISO_8859-1 -t UTF-8 -o nn_no.affix nn_NO.aff iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic @@ -2193,7 +2185,7 @@ iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic - 拷贝文件到$SHAREDIR/tsearch_data目录 + 复制文件到$SHAREDIR/tsearch_data目录 @@ -2211,11 +2203,11 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( - 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基础名称。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 + 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基名。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 - Ispell 词典通常识别一个有限集合的词,这样它们后面应该跟着另一个更广义的词典;例如,一个 Snowball 词典,它可以识别所有东西。 + Ispell 词典通常只能识别有限的词,因此其后应跟着另一个覆盖范围更广的词典;例如,一个 Snowball 词典,它可以识别所有输入。 @@ -2223,13 +2215,13 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( prefixes flag *A: - . > RE # As in enter > reenter + . > RE # 例如 enter > reenter suffixes flag T: - E > ST # As in late > latest - [^AEIOU]Y > -Y,IEST # As in dirty > dirtiest - [AEIOU]Y > EST # As in gray > grayest - [^EY] > EST # As in small > smallest + E > ST # 例如 late > latest + [^AEIOU]Y > -Y,IEST # 例如 dirty > dirtiest + [AEIOU]Y > EST # 例如 gray > grayest + [^EY] > EST # 例如 small > smallest @@ -2245,14 +2237,14 @@ lark/MRS .dict文件的格式是: -basic_form/affix_class_name +基本词形/词缀类名 .affix文件中,每一个词缀标志以下面的格式描述: -condition > [-stripping_letters,] adding_affix +条件 > [-删除的字母,] 添加的词缀 @@ -2261,7 +2253,7 @@ condition > [-stripping_letters,] adding_affix - Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,它标记可以参与到复合格式中的词典词: + Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,用于标记词典中可以参与构成复合词的词: compoundwords controlled z @@ -2291,7 +2283,7 @@ SFX T 0 est [^ey] - 一个词缀类的第一行是头部。头部后面列出了词缀规则的域: + 一个词缀类的第一行是首部。首部后面列出了词缀规则的字段: @@ -2343,7 +2335,7 @@ largehearted <application>Snowball</application> 词典 - Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每一个算法懂得按照其语言中的拼写,如何缩减词的常见变体形式为一个基础或词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择地指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。例如,有一个内置的定义等效于 + Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每种算法都知道如何把其语言中词的常见变体约简为基本拼写形式,也就是词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。例如,有一个内置的定义等效于 CREATE TEXT SEARCH DICTIONARY english_stem ( @@ -2357,7 +2349,7 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( - 一个Snowball词典识别所有的东西,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 + 一个Snowball词典识别所有输入,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 @@ -2368,11 +2360,11 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( 配置示例 - 一个文本搜索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本搜索配置来执行其处理。配置参数指定了默认配置的名称,如果忽略了显式的配置参数,文本搜索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 + 一个文本检索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本检索配置来执行其处理。配置参数指定了默认配置的名称,如果省略了显式的配置参数,文本检索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 - 有一些预定义的文本搜索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本搜索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本搜索对象()的信息。 + 有一些预定义的文本检索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本检索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本检索对象()的信息。 @@ -2464,17 +2456,17 @@ SHOW default_text_search_config; - 测试和调试文本搜索 + 测试和调试文本检索 - 一个自定义文本搜索配置的行为很容易变得混乱。本节中描述的函数对于测试文本搜索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 + 一个自定义文本检索配置的行为很容易让人困惑。本节中描述的函数对于测试文本检索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 配置测试 - 函数ts_debug允许简单地测试一个文本搜索配置。 + 函数ts_debug可方便地测试一个文本检索配置。 @@ -2493,7 +2485,7 @@ ts_debug( config re - ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果该参数被忽略则使用default_text_search_config指定的配置。 + ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果省略该参数则使用default_text_search_config指定的配置。 @@ -2568,7 +2560,7 @@ SELECT * FROM ts_debug('english', 'a fat cat sat on a mat - it ate a fat rats') - 为了一个更广泛的示范,我们先为英语语言创建一个public.english配置和 Ispell 词典: + 为了做更完整的演示,我们先为英语创建一个public.english配置和 Ispell 词典: @@ -2626,7 +2618,7 @@ FROM ts_debug('public.english', 'The Brightest supernovaes'); 解析器测试 - 下列函数允许直接测试一个文本搜索解析器。 + 下列函数允许直接测试一个文本检索解析器。 @@ -2668,7 +2660,7 @@ ts_token_type(parser_oid oid< - ts_token_type返回一个表,描述指定解析器能够识别的每一种词元。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: + ts_token_type返回一个表,描述指定解析器能够识别的每一种词元类型。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: SELECT * FROM ts_token_type('default'); @@ -2706,7 +2698,7 @@ SELECT * FROM ts_token_type('default'); 词典测试 - ts_lexize函数帮助词典测试。 + ts_lexize函数便于测试词典。 @@ -2764,17 +2756,17 @@ SELECT plainto_tsquery('supernovae stars'); - 文本搜索的首选索引类型 + 文本检索的首选索引类型 - 文本搜索 + 文本检索 索引 - 有两种索引可以用来加速全文搜索:GIN和 + 有两种索引可以用来加速全文检索:GINGiST。 - 请注意,索引对于全文搜索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 + 请注意,索引对于全文检索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 @@ -2788,7 +2780,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GIN - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIN (column); @@ -2808,7 +2800,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GiST - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIST (column [ { DEFAULT | tsvector_ops } (siglen = number) ] ); @@ -2818,7 +2810,7 @@ SELECT plainto_tsquery('supernovae stars'); 创建基于 GiST(广义搜索树)的索引。 column可以是tsvectortsquery类型。 - 可选的整数参数siglen确定签名长度(有关详细信息,请参见下文)。 + 可选的整数参数siglen确定以字节为单位的签名长度(有关详细信息,请参见下文)。 @@ -2827,7 +2819,7 @@ SELECT plainto_tsquery('supernovae stars'); - GIN 索引是文本搜索的首选索引类型。作为倒排索引,每个词(词位)在 + GIN 索引是文本检索的首选索引类型。作为倒排索引,每个词(词位)在 其中都有一个索引项,其中有压缩过的匹配位置的列表。多词搜索可以找到 第一个匹配,然后使用该索引移除缺少额外词的行。GIN 索引只存储 tsvector值的词(词位),并且不存储它们的权重标签。因此, @@ -2835,19 +2827,19 @@ SELECT plainto_tsquery('supernovae stars'); - 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。以字节为单位的签名长度由可选整数参数 siglen 的值决定。 默认签名长度(未指定 siglen 时)为 124 字节,最大签名长度为 2024 字节。该签名通过哈希每一个词到一个 n 位串中的一个单一位来产生,通过将所有这些位 OR 在一起产生一个 n 位的文档签名。当两个词哈希到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。更长的签名导致更精确的搜索(扫描索引的一小部分和更少的堆页面),但代价是更大的索引。 + 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。以字节为单位的签名长度由可选整数参数 siglen 的值决定。 默认签名长度(未指定 siglen 时)为 124 字节,最大签名长度为 2024 字节。该签名通过将每个词 hash 到一个 n 位串中的一位,再将所有这些位进行 OR 运算来生成,结果是一个 n 位的文档签名。当两个词 hash 到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。更长的签名导致更精确的搜索(扫描更小比例的索引和更少的堆页面),但代价是更大的索引。 - GiST 可以构建为覆盖索引,例如使用 INCLUDE 子句。被包含的列可以具有没有任何 GiST 操作符类的数据类型。被包含的属性会以未压缩形式存储。 + GiST 可以构建为覆盖索引,即使用 INCLUDE 子句。被包含的列可以具有没有任何 GiST 操作符类的数据类型。被包含的属性会以未压缩形式存储。 - 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的可用性。假匹配的可能性取决于几个因素,特别是唯一词的数量,因此推荐使用词典来缩减这个数量。 + 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的实用性。假匹配的可能性取决于几个因素,特别是不同词的数量,因此推荐使用词典来缩减这个数量。 - 注意GIN索引的构件时间常常可以通过增加来改进,而GiST索引的构建时间则与该参数无关。 + 注意GIN索引的构建时间常常可以通过增加来改进,而GiST索引的构建时间则对该参数不敏感。 @@ -2861,7 +2853,7 @@ SELECT plainto_tsquery('supernovae stars'); <application>psql</application> 支持 - 关于文本搜索配置对象的信息可以在psql中使用一组命令获得: + 关于文本检索配置对象的信息可以在psql中使用一组命令获得: \dF{d,p,t}+ PATTERN @@ -2869,7 +2861,7 @@ SELECT plainto_tsquery('supernovae stars'); - 可选参数 PATTERN 可以是文本搜索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: + 可选参数 PATTERN 可以是文本检索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: => \dF *fulltext* @@ -2896,7 +2888,7 @@ SELECT plainto_tsquery('supernovae stars'); \dF+ PATTERN - 列出文本搜索配置(加上 + 可显示更多细节)。 + 列出文本检索配置(加上 + 可显示更多细节)。 => \dF russian List of text search configurations @@ -2937,7 +2929,7 @@ Parser: "pg_catalog.default" \dFd+ PATTERN - 列出文本搜索词典(加上 + 可显示更多细节)。 + 列出文本检索词典(加上 + 可显示更多细节)。 => \dFd List of text search dictionaries @@ -2950,7 +2942,6 @@ Parser: "pg_catalog.default" pg_catalog | danish_stem | snowball stemmer for danish language pg_catalog | dutch_stem | snowball stemmer for dutch language pg_catalog | english_stem | snowball stemmer for english language - pg_catalog | estonian_stem | snowball stemmer for estonian language pg_catalog | finnish_stem | snowball stemmer for finnish language pg_catalog | french_stem | snowball stemmer for french language pg_catalog | german_stem | snowball stemmer for german language @@ -2982,7 +2973,7 @@ Parser: "pg_catalog.default" \dFp+ PATTERN - 列出文本搜索解析器(加上 + 可显示更多细节)。 + 列出文本检索解析器(加上 + 可显示更多细节)。 => \dFp List of text search parsers @@ -3035,7 +3026,7 @@ Parser: "pg_catalog.default" \dFt+ PATTERN - 列出文本搜索模板(加上 + 可显示更多细节)。 + 列出文本检索模板(加上 + 可显示更多细节)。 => \dFt List of text search templates @@ -3058,7 +3049,7 @@ Parser: "pg_catalog.default" 限制 - PostgreSQL 当前文本搜索特性的限制如下: + PostgreSQL 当前文本检索特性的限制如下: 每个词位的长度必须小于 2 千字节 @@ -3086,12 +3077,12 @@ Parser: "pg_catalog.default" - 为了对比,PostgreSQL 8.1 的文档包含 10,441 个唯一词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 + 为了对比,PostgreSQL 8.1 的文档包含 10,441 个不同词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 - 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个唯一词。 + 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个不同词。 diff --git a/zh/14/unaccent.sgml b/zh/14/unaccent.sgml index e72b6d9d..6e408133 100644 --- a/zh/14/unaccent.sgml +++ b/zh/14/unaccent.sgml @@ -8,11 +8,11 @@ - unaccent是一个文本搜索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤字典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文搜索能够以不区分重音的方式处理文本。 + unaccent是一个文本检索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤词典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文检索能够以不区分重音的方式处理文本。 - unaccent当前的实现还不能作为thesaurus词典的正规化字典使用。 + unaccent当前的实现还不能作为thesaurus词典的正规化词典使用。 @@ -64,22 +64,11 @@ - - - 某些字符(例如数字符号)在其转换规则中可能需要空白字符。在这种情况下,可以用双引号把转换后的字符括起来。如果转换后的字符中本身要包含双引号,则需要再用一个双引号对其转义。例如: - -¼ " 1/4" -½ " 1/2" -¾ " 3/4" -“ """" -” """" - - - + - 与其他PostgreSQL文本搜索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含不可转换字符的行都会被静默忽略,因此规则文件中可以包含不适用于当前编码的规则。 + 与其他PostgreSQL文本检索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含不可转换字符的行都会被静默忽略,因此规则文件中可以包含不适用于当前编码的规则。 @@ -93,7 +82,7 @@ 用法 - 安装unaccent扩展会创建一个文本搜索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 + 安装unaccent扩展会创建一个文本检索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 mydb=# ALTER TEXT SEARCH DICTIONARY unaccent (RULES='my_rules'); @@ -114,7 +103,7 @@ mydb=# select ts_lexize('unaccent','Hôtel'); - 下面的示例展示了如何将unaccent词典插入到文本搜索配置中: + 下面的示例展示了如何将unaccent词典插入到文本检索配置中: mydb=# CREATE TEXT SEARCH CONFIGURATION fr ( COPY = french ); mydb=# ALTER TEXT SEARCH CONFIGURATION fr @@ -145,7 +134,7 @@ mydb=# select ts_headline('fr','Hôtel de la Mer',to_tsquery('fr','Hotels') 函数 - unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本搜索环境之外使用。 + unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本检索环境之外使用。 @@ -157,7 +146,7 @@ unaccent(dictionary - 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本搜索词典。 + 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本检索词典。 diff --git a/zh/15/array.sgml b/zh/15/array.sgml index a13b47e0..1d2a2443 100644 --- a/zh/15/array.sgml +++ b/zh/15/array.sgml @@ -4,7 +4,7 @@ 数组 - array + 数组 @@ -15,8 +15,8 @@ 数组类型的声明 - array - declaration + 数组 + 声明 @@ -48,7 +48,7 @@ CREATE TABLE tictactoe ( - 另一种使用关键字 ARRAY 且符合 SQL 标准的语法也可用于一维数组。pay_by_quarter 也可以定义为: + 另一种使用关键字 ARRAY、并且符合 SQL 标准的语法可用于一维数组。pay_by_quarter 也可以定义为: pay_by_quarter integer ARRAY[4], @@ -64,8 +64,8 @@ CREATE TABLE tictactoe ( 数组值输入 - array - constant + 数组 + 常量 @@ -86,7 +86,7 @@ CREATE TABLE tictactoe ( (这类数组常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。必要时可能需要显式指定类型。) + linkend="sql-syntax-constants-generic"/>中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。可能需要显式指定类型。) @@ -119,15 +119,14 @@ SELECT * FROM sal_emp; - 多维数组在每个维度上的范围必须匹配。不匹配会导致错误,例如: + 多维数组的各个子数组在每个维度上的长度必须匹配。不匹配会导致错误,例如: INSERT INTO sal_emp VALUES ('Bill', '{10000, 10000, 10000, 10000}', '{{"meeting", "lunch"}, {"meeting"}}'); -ERROR: malformed array literal: "{{"meeting", "lunch"}, {"meeting"}}" -DETAIL: Multidimensional arrays must have sub-arrays with matching dimensions. +ERROR: multidimensional arrays must have array expressions with matching dimensions @@ -152,8 +151,8 @@ INSERT INTO sal_emp 访问数组 - array - accessing + 数组 + 访问 @@ -186,9 +185,9 @@ SELECT pay_by_quarter[3] FROM sal_emp; - 我们还可以访问数组或子数组的任意矩形切片。数组切片通过在一个或多个数组维度上写成 + 我们还可以访问数组的任意矩形切片,即子数组。数组切片通过在一个或多个数组维度上写成 lower-bound:upper-bound - 的形式来表示。例如,下面这个查询取回 Bill 在一周前两天日程安排中的第一个项目: + 的形式来表示。例如,下面这个查询取回 Bill 在一周中前两天里每天的首项日程: SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill'; @@ -235,11 +234,11 @@ SELECT schedule[:][1:1] FROM sal_emp WHERE name = 'Bill'; - 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回空值。此外,如果下标超出数组边界,也会返回空值(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是空值而不是错误。 + 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回 NULL。此外,如果下标超出数组边界,也会返回 NULL(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是 NULL 而不是错误。 - 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回空值。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是空值。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回空值。 + 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回 NULL。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是 NULL。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回 NULL。 @@ -293,8 +292,8 @@ SELECT cardinality(schedule) FROM sal_emp WHERE name = 'Carol'; 修改数组 - array - modifying + 数组 + 修改 @@ -331,7 +330,7 @@ UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}' - 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用空值填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含空值。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 + 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用 NULL 填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含 NULL。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 @@ -443,21 +442,21 @@ SELECT array_cat(ARRAY[5,6], ARRAY[[1,2],[3,4]]); 在简单情况下,优先使用上面讨论的连接操作符,而不是直接调用这些函数。不过,由于连接操作符被重载以同时服务于这三种情形,所以在某些场景下使用这些函数之一有助于避免歧义。例如,考虑: -SELECT ARRAY[1, 2] || '{3, 4}'; -- the untyped literal is taken as an array +SELECT ARRAY[1, 2] || '{3, 4}'; -- 未指定类型的字面量被当作数组 ?column? ----------- {1,2,3,4} -SELECT ARRAY[1, 2] || '7'; -- so is this one +SELECT ARRAY[1, 2] || '7'; -- 这个字面量也一样 ERROR: malformed array literal: "7" -SELECT ARRAY[1, 2] || NULL; -- so is an undecorated NULL +SELECT ARRAY[1, 2] || NULL; -- 未加类型修饰的 NULL 也一样 ?column? ---------- {1,2} (1 row) -SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant +SELECT array_append(ARRAY[1, 2], NULL); -- 这可能才是原本想表达的意思 array_append -------------- {1,2,NULL} @@ -471,8 +470,8 @@ SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant 在数组中搜索 - array - searching + 数组 + 搜索 @@ -552,7 +551,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); 数组输入和输出语法 - array + 数组 I/O @@ -565,7 +564,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); - 默认情况下,数组各维度的下界索引值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: + 默认情况下,数组各维度的下界下标值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2 FROM (SELECT '[1:1][-2:-1][3:5]={{{1,2,3},{4,5,6}}}'::int[] AS f1) AS ss; diff --git a/zh/15/catalogs.sgml b/zh/15/catalogs.sgml index 6a93f7bf..d98c8cd7 100644 --- a/zh/15/catalogs.sgml +++ b/zh/15/catalogs.sgml @@ -320,27 +320,27 @@ pg_ts_config - 文本搜索配置 + 文本检索配置 pg_ts_config_map - 文本搜索配置的词元映射 + 文本检索配置的词元映射 pg_ts_dict - 文本搜索字典 + 文本检索词典 pg_ts_parser - 文本搜索分析器 + 文本检索解析器 pg_ts_template - 文本搜索模板 + 文本检索模板 @@ -7602,12 +7602,12 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config目录包含表示文本搜索配置的条目。一个配置指定某个特定的文本搜索分析器,以及针对该分析器每种输出词元类型所定义的字典列表。分析器由pg_ts_config项表示,而词元到字典的映射则由pg_ts_config系统目录包含表示文本检索配置的条目。一个配置指定某个特定的文本检索解析器,以及针对该解析器每种输出词元类型所定义的词典列表。解析器记录在pg_ts_config条目中,而词元到词典的映射则由pg_ts_config_map中的辅助项定义。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。 @@ -7639,7 +7639,7 @@ SCRAM-SHA-256$<iteration count>:&l cfgname name - 文本搜索配置名 + 文本检索配置名 @@ -7669,7 +7669,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_ts_parser.oid - 该配置的文本搜索分析器的OID + 该配置的文本检索解析器的 OID @@ -7686,11 +7686,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config_map目录包含的项展示了对于每一个文本搜索配置的每一种输出词元类型,有哪些文本搜索字典可供查询以及以何种顺序。 + pg_ts_config_map 系统目录中的条目说明了,对于每个文本检索配置所用解析器的每种输出词元类型,应当查询哪些文本检索词典以及查询的顺序。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7723,7 +7723,7 @@ SCRAM-SHA-256$<iteration count>:&l maptokentype int4 - 一种由配置的分析器送出的词元类型 + 一种由配置的解析器送出的词元类型 @@ -7742,7 +7742,7 @@ SCRAM-SHA-256$<iteration count>:&l (参考 pg_ts_dict.oid - 要查询的文本搜索字典的OID + 要查询的文本检索词典的 OID @@ -7759,11 +7759,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_dict目录包含定义文本搜索字典的项。一个字典依赖于一个文本搜索模板,它指定了所有需要的函数实现,字典本身则为模板支持的用户可设置参数提供值。这种分工允许无权限的用户创建字典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 + pg_ts_dict系统目录包含定义文本检索词典的项。一个词典依赖于一个文本检索模板,它指定了所有需要的实现函数,词典本身则为模板支持的用户可设置参数提供值。这种分工允许普通用户创建词典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7795,7 +7795,7 @@ SCRAM-SHA-256$<iteration count>:&l dictname name - 文本搜索字典名 + 文本检索词典名 @@ -7805,7 +7805,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_namespace.oid - 包含该字典的名字空间OID + 包含该词典的名字空间的 OID @@ -7815,7 +7815,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_authid.oid - 字典的拥有者 + 词典的拥有者 @@ -7825,7 +7825,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_ts_template.oid - 该字典的文本搜索模板的OID + 该词典的文本检索模板的 OID @@ -7851,11 +7851,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_parser目录包含定义文本搜索分析器的项。一个分析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个分析器必须用C语言级别的函数实现,创建新分析器的工作只限于数据库的超级用户。 + pg_ts_parser系统目录包含定义文本检索解析器的项。一个解析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个解析器必须用 C 语言级别的函数实现,创建新解析器的工作只限于数据库的超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7887,7 +7887,7 @@ SCRAM-SHA-256$<iteration count>:&l prsname name - 文本搜索分析器的名字 + 文本检索解析器的名字 @@ -7897,7 +7897,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_namespace.oid - 包含此分析器的名字空间的OID + 包含此解析器的名字空间的 OID @@ -7907,7 +7907,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器启动函数的OID + 解析器启动函数的 OID @@ -7917,7 +7917,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的下一词元函数的OID + 解析器的下一词元函数的 OID @@ -7927,7 +7927,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的关闭函数的OID + 解析器的关闭函数的 OID @@ -7937,7 +7937,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器标题函数的 OID(如果没有则为零) + 解析器的 headline 函数的 OID(如果没有则为零) @@ -7947,7 +7947,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的词汇类型函数的OID + 解析器的 lextype 函数的 OID @@ -7964,11 +7964,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_template目录包含定义文本搜索模板的项。一个模板是一类文本搜索字典的实现骨架。由于一个模板必须用C语言级别的函数实现,新模板的创建只限于数据库超级用户。 + pg_ts_template系统目录包含定义文本检索模板的项。一个模板是一类文本检索词典的实现骨架。由于一个模板必须用 C 语言级别的函数实现,新模板的创建只限于数据库超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -8000,7 +8000,7 @@ SCRAM-SHA-256$<iteration count>:&l tmplname name - 文本搜索模板的名字 + 文本检索模板的名字 diff --git a/zh/15/config.sgml b/zh/15/config.sgml index 76ae116d..c1b35831 100644 --- a/zh/15/config.sgml +++ b/zh/15/config.sgml @@ -2587,7 +2587,7 @@ include_dir 'conf.d' 配置 恢复 - general settings + 一般设置 @@ -2644,7 +2644,7 @@ include_dir 'conf.d' 配置 恢复 - of a standby server + 备库 @@ -2944,7 +2944,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows 发送服务器 - 这些参数适用于向一个或多个备库发送复制数据的服务器。主库总是发送服务器,因此这些参数通常需要在主库上设置。 + 这些参数可以在任何发送复制数据给一个或多个备库的服务器上设置。主库总是一个发送服务器,因此这些参数总是要在主库上设置。这些参数的角色和含义不会在一个备库变成主库后改变。 @@ -3003,7 +3003,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows - 列出安装在 所指定位置中、同时也被信任可供复制客户端用作逻辑输出插件的库。 + 列出安装在 所指定位置中、同时也受信任、可供复制客户端用作逻辑输出插件的库。 任何针对其他库的逻辑解码或 复制请求都将被拒绝。所有用户都受此限制。 默认值为 'pgoutput, test_decoding',它们是标准 @@ -3580,8 +3580,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( )。 + 设置规划器对一系列顺序磁盘页面读取中单次读取的代价估计。默认值是 1.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -3903,7 +3898,7 @@ ANY num_sync ( )。 + 设置规划器对一次非顺序磁盘页面读取的代价估计。默认值是 4.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -3916,13 +3911,13 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( 。 如果指定值时没有单位,则以块为单位,即BLCKSZ字节,通常为8kB。默认值是512千字节(512kB)。 @@ -4048,13 +4043,13 @@ ANY num_sync ( num_sync ( - 遗传查询优化 + 遗传查询优化器 - GEQO是一个使用探索式搜索来执行查询规划的算法。它可以降低负载查询的规划时间。 同时,GEQO的检索是随机的,因此它的规划可能会不可确定。 更多信息参阅Chapter 50。 - 遗传查询规划器(GEQO)是一种使用启发式搜索来进行查询规划的算法。它可以降低对于复杂查询(连接很多表的查询)的规划时间,但是代价是它产生的计划有时候要差于使用穷举搜索算法找到的计划。详见。 + 遗传查询优化器(GEQO)是一种使用启发式搜索进行查询规划的算法。它可以缩短复杂查询(连接很多关系的查询)的规划时间,代价是生成的计划有时不如常规穷举搜索算法找到的计划。更多信息见 @@ -4135,7 +4129,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( .) + 目前,约束排除仅在通常用于通过继承树实现表分区的情况下默认启用。为所有表启用它会增加额外的规划开销,这在简单查询上相当明显,而且通常不会为简单查询带来好处。如果没有通过传统继承方式进行分区的表,你可能希望完全关闭它。(注意,分区表的等效功能由另一个参数控制。) @@ -4384,13 +4375,7 @@ SELECT * FROM parent WHERE key = 2400; - 准备语句(显式准备或隐式生成的,例如 PL/pgSQL)可以使用自定义或通用计划执行。 - 使用其特定的参数值集为每个执行重新生成自定义计划,而通用计划不依赖于参数值,并且可以在执行中重复使用。 - 因此,使用通用计划可以节省计划时间,但如果理想计划严重依赖参数值,则通用计划可能效率低下。 - 这些选项之间的选择通常是自动进行的,但可以通过plan_cache_mode覆盖它。 - 允许的值为 auto (默认的),force_custom_planforce_generic_plan。 - 这个设置是在执行缓存计划时考虑,而不是在准备计划时考虑。 - 更多信息请参阅 . + 预备语句(无论是显式预备的,还是由 PL/pgSQL 等隐式生成的)可以使用自定义计划或通用计划执行。自定义计划会根据每次执行的具体参数值重新生成,而通用计划不依赖参数值,可以在多次执行之间复用。因此,使用通用计划能够节省规划时间,但如果理想计划高度依赖参数值,通用计划可能效率较低。系统通常会自动选择这两种计划,但可以通过plan_cache_mode覆盖这一选择。允许的值为auto(默认值)、force_custom_planforce_generic_plan。系统在执行缓存计划时考虑此设置,而不是在预备计划时。更多信息见 @@ -4408,7 +4393,7 @@ SELECT * FROM parent WHERE key = 2400; 设置规划器对递归查询 的工作表的平均大小的估计值,作为查询初始非递归项的估计大小的倍数。 这有助于规划器选择将工作表与查询的其他表连接的最合适方法。 - 默认值为10.0。当递归从一步到下一步的fan-out较低时,如最短路径查询中的示例,使用较小的值(如1.0)可能有所帮助。 + 默认值为10.0。当递归从一步到下一步的扇出较低时,例如最短路径查询,使用较小的值(如1.0)可能有所帮助。 图分析查询可能会从大于默认值的设置中受益。 @@ -4427,7 +4412,7 @@ SELECT * FROM parent WHERE key = 2400; - 在哪里做日志 + 日志记录到哪里 日志写到哪里 @@ -4435,7 +4420,7 @@ SELECT * FROM parent WHERE key = 2400; current_logfiles - 和日志_目的地配置参数 + 和 log_destination 配置参数 @@ -4483,13 +4468,13 @@ jsonlog log/postgresql.json 当由于轮换而创建新的日志文件时,以及重新加载log_destination时,current_logfiles会被重新创建。 当log_destination中不包含stderrcsvlogjsonlog, - 以及日志收集器被禁用时,它会被移除。 + 或者日志收集器被禁用时,它会被移除。 - 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设备LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: + 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设施LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: local0.* /var/log/postgresql @@ -4497,7 +4482,7 @@ local0.* /var/log/postgresql - 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源极其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见。 + 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源及其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见 @@ -4513,20 +4498,20 @@ local0.* /var/log/postgresql - 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 + 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息可能不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 - 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供方法来轮转日志文件。还有,在某些不使用日志收集器的平台上可能会导致丢失或者混淆日志输出,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 + 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供便捷的方法来轮转日志文件。还有,在某些平台上,不使用日志收集器可能会导致日志输出丢失或混杂,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 - 日志收集器被设计成从来不会丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 + 日志收集器被设计成从来不会丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它可能会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 @@ -4560,7 +4545,7 @@ local0.* /var/log/postgresql logging_collector被启用时,这个参数设置被创建的日志文件的文件名。 - 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何时区独立的%转义,计算将在由指定的时区中完成)。 + 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何依赖时区的%转义,计算将在由指定的时区中完成)。 被支持的%转义和开放组织的strftime说明中列举的类似。 注意系统的strftime不会被直接使用,因此平台相关(非标准)的扩展无法工作。 默认是postgresql-%Y-%m-%d_%H%M%S.log。 @@ -4598,7 +4583,7 @@ local0.* /var/log/postgresql - 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的十进制格式,该数字必须以一个0(零)开始)。 + 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的八进制格式,该数字必须以一个0(零)开始)。 @@ -4664,7 +4649,7 @@ local0.* /var/log/postgresql - 示例:要保留 24 小时的日志,每个小时一个日志文件,但是在日志文件尺寸超过 1GB 时轮转。可以这样做:将log_filename设置为server_log.%H%M、 + 示例:要保留 24 小时的日志,每个小时一个日志文件,如果日志文件尺寸超过 1GB,也会提前轮转。可以这样做:将log_filename设置为server_log.%H%M、 将log_truncate_on_rotation设置为on、 将log_rotation_age设置为60并且 将log_rotation_size设置为1000000。 @@ -4683,7 +4668,7 @@ local0.* /var/log/postgresql - 当启用了向syslog记录时,这个参数决定要使用的syslog设备。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4、 + 当启用了向syslog记录时,这个参数决定要使用的syslog设施。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4LOCAL5LOCAL6LOCAL7中选择,默认值是LOCAL0。还请参阅系统的syslog守护进程的文档。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -4738,7 +4723,7 @@ local0.* /var/log/postgresql - 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,有必要让消息保持逻辑上的整体性(也更加有用)。 + 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,让消息保持逻辑上的完整性可能是必要的,也可能更有用。 @@ -4757,7 +4742,7 @@ local0.* /var/log/postgresql - 当启用了向事件日志记录时,这个参数决定用来标识日志中PostgreSQL消息的程序名。默认值是PostgreSQL。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 当启用了向事件日志记录时,这个参数决定用来标识日志中PostgreSQL消息的程序名。默认值是PostgreSQL。这个参数只能在服务器启动时设置。 @@ -4803,9 +4788,7 @@ local0.* /var/log/postgresql - 控制在服务器日志中记录哪些导致错误条件的SQL语句。当前的SQL语句将包含在任何指定 - severity - 或更高消息的日志条目中。 + 控制在服务器日志中记录哪些导致错误条件的SQL语句。对于达到指定严重级别或更高级别的消息,其日志条目中会包含当前 SQL 语句。 有效值为DEBUG5DEBUG4DEBUG3DEBUG2DEBUG1、 @@ -4845,7 +4828,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -4883,7 +4866,7 @@ local0.* /var/log/postgresql - log_min_duration_statement的其他注释也适用于此设置。 + log_min_duration_statement的其他说明也适用于此设置。 @@ -4898,8 +4881,8 @@ local0.* /var/log/postgresql - 确定持续时间超过的语句的比例将被记录。 - 采样是随机的,例如0.5表示统计上有一半的机会任何给定的语句将被记录。 + 确定持续时间超过的语句中,将被记录的语句比例。 + 采样是随机的,例如0.5表示任意给定语句被记录的统计概率为二分之一。 默认值为1.0,表示记录所有采样的语句。 将此设置为零将禁用采样语句持续时间记录,与将log_min_duration_sample设置为-1相同。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -4917,7 +4900,7 @@ local0.* /var/log/postgresql - 设置所有语句都被记录的事务的比例,除了其他原因记录的语句。它适用于每个新事务,无论其语句的持续时间如何。 + 设置需要记录全部语句的事务比例,这些记录是在因其他原因记录的语句之外额外进行的。它适用于每个新事务,无论其语句的持续时间如何。 采样是随机的,例如0.1表示任何给定事务被记录的统计概率是十分之一。 log_transaction_sample_rate可以帮助构建事务样本。 默认值为0,表示不记录任何额外事务的语句。将其设置为1会记录所有事务的所有语句。 @@ -4942,8 +4925,7 @@ local0.* /var/log/postgresql - 设置启动进程在长时间运行的操作仍在进行时记录消息的时间间隔, - 以及该操作进一步进展消息之间的间隔时间。默认值为10秒。 + 设置启动进程在长时间运行的操作开始后,等待多久才记录第一条进度消息,以及此后该操作的进度消息之间的时间间隔。默认值为10秒。 设置为0会禁用该功能。如果未指定单位, 则将其视为毫秒。此设置分别应用于每个操作。 此参数只能在postgresql.conf文件或服务器命令行中设置。 @@ -4985,7 +4967,7 @@ local0.* /var/log/postgresql DEBUG1 .. DEBUG5 - 为开发者提供连续的更详细的信息。 + 为开发者提供逐级更加详细的信息。 DEBUG INFORMATION @@ -5045,7 +5027,7 @@ local0.* /var/log/postgresql - 记录什么到日志 + 记录哪些内容 @@ -5066,7 +5048,7 @@ local0.* /var/log/postgresql - application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。它也会被通过包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为问号(?)。 + application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。也可以通过将其包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为问号(?)。 @@ -5093,7 +5075,6 @@ local0.* /var/log/postgresql - 这个参数启用发出各种调试输出。当设置时,会打印生成的解析树, 查询重写输出,或执行的每个查询的执行计划。这些信息是在LOG 信息级别发出,因此默认的,它们会出现在服务器日志中,但不会发送给客户端。 可以通过 client_min_messages和/或log_min_messages 来设置。这些参数缺省是off。 这些参数将会让多种调试输出被发出。当被设置时,它们为每一个被执行的查询打印结果分析树、查询重写器输出或执行计划。这些消息在LOG消息级别上被发出,因此默认情况下它们将出现在服务器日志中但不会被发送到客户端。你可以通过调整和/或来改变这种情况。这些参数默认是关闭的。 @@ -5127,10 +5108,10 @@ local0.* /var/log/postgresql - 每次由自动清理执行的操作都会被记录,如果运行时间至少达到指定时间。将此设置为零会记录所有自动清理操作。 + 当自动清理执行的操作运行时间至少达到指定时间时,就会记录该操作。将此设置为零会记录所有自动清理操作。 -1会禁用记录自动清理操作。如果未指定单位,则将其视为毫秒。 例如,如果将其设置为250ms,则所有运行时间为250ms或更长的自动清理和分析都将被记录。 - 此外,当此参数设置为任何值而不是-1时,如果由于冲突的锁定或同时删除的关系而跳过自动清理操作,则会记录消息。 + 此外,当此参数设置为任何非-1值时,如果由于冲突锁或关系被并发删除而跳过自动清理操作,则会记录消息。 默认值为10min。启用此参数可帮助跟踪自动清理活动。 此参数只能在postgresql.conf文件或服务器命令行中设置;但可以通过更改表存储参数来覆盖对单个表的设置。 @@ -5209,7 +5190,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -5232,7 +5213,7 @@ local0.* /var/log/postgresql 控制在服务器日志中记录的每条消息的详细程度。有效值为TERSE, - DEFAULTVERBOSE,每个值都会添加更多字段到显示的消息中。 + DEFAULTVERBOSE,它们依次在显示的消息中增加更多字段。 TERSE不包括DETAILHINTQUERYCONTEXT错误信息的记录。 VERBOSE输出包括SQLSTATE错误代码 @@ -5252,7 +5233,7 @@ local0.* /var/log/postgresql - 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致很微小的性能损失。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致不可忽视的性能开销。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -5271,7 +5252,7 @@ local0.* /var/log/postgresql %字符开始转义序列,它将被按照下文描述的替换成状态信息。 未识别的转义被忽略。其他字符被直接复制到日志行。某些转义只被会话进程识别并且被主服务器进程等后台进程当作空。 通过指定一个在%之后和该选项之前的数字可以让状态信息左对齐或右对齐。 - 负值将导致在右边用空格填充状态信息已达到最小宽度,而正值则在左边填充。填充对于日志文件的人类可读性大有帮助。 + 负值将导致在右边用空格填充状态信息以达到最小宽度,而正值则在左边填充。填充对于日志文件的人类可读性大有帮助。 @@ -5334,8 +5315,8 @@ local0.* /var/log/postgresql %P - 并行组leader的进程ID,如果该进程是一个并行查询worker - no + 如果该进程是并行查询工作进程,则为并行组领导者的进程 ID + @@ -5352,8 +5333,8 @@ local0.* /var/log/postgresql %n - 带毫秒的时间戳(作为 Unix 时代) - no + 带毫秒精度的 Unix 时间戳 + @@ -5408,7 +5389,7 @@ local0.* /var/log/postgresql %Q 当前查询的查询标识符。 查询标识符默认是不计算的,所以这个部分将是零,除非 参数被激活或者配置了计算查询标识符的第三方模块 - yes + @@ -5427,7 +5408,7 @@ local0.* /var/log/postgresql %c转义打印一个准唯一的会话标识符,它由两个 4 字节的十六进制数(不带先导零)组成,以点号分隔。 - 这些数字是进程启动时间和进程 ID,因此%c也可以被用作保存打印这些项的方式的空间。 + 这些数字是进程启动时间和进程 ID,因此%c也可以用来节省空间地输出这两项信息。 例如,要从pg_stat_activity生成会话标识符,使用这个查询: SELECT to_hex(trunc(EXTRACT(EPOCH FROM backend_start))::integer) || '.' || @@ -5465,7 +5446,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 对于输出的行,%Q 总是报告零标识符, - 因为log_statement在标识符能被计算之前生成输出,包括无效标识符不能计算的无效语句。 + 因为log_statement在标识符能被计算之前生成输出,也包括无法计算标识符的无效语句。 @@ -5498,8 +5479,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 控制启动进程等待时间超过针对恢复冲突的deadlock_timeout的时候是否产生日志消息。 - 这对于决定恢复冲突是否会阻止恢复应用WAL有所帮助。 + 控制启动进程因恢复冲突而等待超过deadlock_timeout时是否产生日志消息。这有助于判断恢复冲突是否阻碍了恢复过程应用 WAL。 @@ -5529,8 +5509,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 此设置仅影响作为结果打印的日志消息,, 和相关的设置。 - 该设置的非零值会增加一些开销,特别是当参数以二进制形式发送时,因为需要转换为文本。 + 此设置仅影响由及相关设置产生的日志消息。此设置为非零值时会增加一些开销,特别是以二进制形式发送参数时,因为需要将参数转换为文本。 @@ -5574,7 +5553,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' UPDATEDELETETRUNCATE, 和COPY FROM。 如果PREPAREEXECUTE和 - EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个执行消息时会产生日志并且会包括绑定参数的值(任何内嵌的单引号会被双写)。 + EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个 Execute 消息时会产生日志并且会包括 Bind 参数的值(任何内嵌的单引号会被双写)。 @@ -5585,7 +5564,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在执行阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 + 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在 Execute 阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 @@ -5624,7 +5603,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 控制临时文件名和大小的日志记录。 - 临时文件可以用于排序、哈希和临时查询结果。 + 临时文件可以用于排序、hash 和临时查询结果。 如果通过此设置启用,每当删除临时文件时都会发出日志记录。 值为零时记录所有临时文件信息,而正值仅记录大小大于或等于指定数据量的文件。 如果未指定单位,则将其视为千字节。 @@ -5678,7 +5657,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 错误上下文、 导致错误的用户查询(如果有且被log_min_error_statement启用)、 错误位置所在的字符计数、 - 在 PostgreSQL 源代码中错误的位置(如果log_error_verbosity被设置为verbose)以及应用名,后端类型,并行组leader的进程ID和查询ID。 + 在 PostgreSQL 源代码中错误的位置(如果log_error_verbosity被设置为verbose)、应用名、后端类型、并行组领导者的进程 ID 和查询 ID。 下面是一个定义用来存储 CSV 格式日志输出的样表: @@ -5730,7 +5709,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 设置log_filenamelog_rotation_age为你的日志文件提供一种一致的、可预测的命名空间。这让你预测文件名会是怎样以及知道什么时候一个个体日志文件完成并且因此准备好被导入。 + 设置log_filenamelog_rotation_age,为日志文件提供一致且可预测的命名方案。这样就能预测文件名,并知道单个日志文件何时已完成写入、可以导入。 @@ -5759,12 +5738,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 使用JSON格式的日志输出 - 包括jsonloglog_destination列表中提供了一种方便的方式将日志文件导入到许多不同的程序中。此选项以JSON格式发出日志行。 + 将jsonlog加入log_destination列表,可以方便地将日志文件导入多种不同的程序。此选项以JSON格式输出日志行。 - 字段值为null的字符串字段将被排除在输出之外。 - 未来可能会添加其他字段。处理jsonlog输出的用户应忽略未知字段。 + 值为空值的字符串字段不会输出。将来可能会添加其他字段。处理jsonlog输出的用户应用程序应忽略未知字段。 @@ -5909,13 +5887,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; statement string - 客户提供的查询字符串 + 客户端提供的查询字符串 cursor_position number - 查询字符串中的光标索引 + 查询字符串中的游标索引 @@ -5969,7 +5947,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 进程标题 - 这些设置控制服务器进程的进程标题如何被修改。进程标题通常可以用ps或者 Windows 上的进程浏览器等程序来查看。详见。 + 这些设置控制服务器进程的进程标题如何修改。通常可以通过ps等程序查看进程标题,在 Windows 上则可以使用Process Explorer。详情参见 @@ -6003,7 +5981,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 每次服务器接收到新的SQL命令时,都可以更新进程标题。 + 启用后,每次服务器接收到新的 SQL 命令时都会更新进程标题。 在大多数平台上,默认情况下此设置为on,但在Windows上默认为off, 因为该平台更新进程标题的开销较大。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -6041,7 +6019,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对每个会话当前执行命令的信息收集,包括其标识符和命令开始执行的时间。 - 此参数默认为开启状态。请注意,即使启用了此信息,只有超级用户、具有 + 此参数默认为开启状态。请注意,即使启用了此参数,只有超级用户、具有 pg_read_all_stats角色权限的角色和拥有被报告会话的用户 (包括属于他们具有权限的角色的会话)才能看到此信息,因此不应构成安全风险。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -6059,7 +6037,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 为每个活动会话指定存储当前执行命令的文本所保留的内存量,它们被用于pg_stat_activity.query域。 + 为每个活动会话指定存储当前执行命令的文本所预留的内存量,它们被用于pg_stat_activity.query字段。 如果指定值时没有单位,则以字节为单位。默认值是 1024字节。这个参数只能在服务器启动时被设置。 @@ -6076,7 +6054,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对数据库活动的统计信息收集。 - 此参数默认为开启,因为自动清理守护进程需要收集的信息。 + 此参数默认为开启,因为自动清理守护进程需要这些收集到的信息。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -6131,7 +6109,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用函数调用次数和时间的跟踪。指定pl以仅跟踪过程语言函数, + 启用函数调用次数和耗时的跟踪。指定pl以仅跟踪过程语言函数, all以同时跟踪SQL和C语言函数。默认值为none, 即禁用函数统计跟踪。只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -6166,7 +6144,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - none适用于监控系统。如果值只被访问一次,它是最有效的。 + none最适合监控系统。如果值只被访问一次,它是最有效的。 cache确保重复访问产生相同的值,这对涉及自连接的查询很重要。 snapshot在交互式检查统计信息时可能很有用,但开销较高, 特别是存在许多数据库对象时。 @@ -6193,21 +6171,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用查询标识符的内核计算。 - 查询标识符可以在 pg_stat_activity - 视图中显示,使用 EXPLAIN,或者如果通过 - 参数进行配置,则可以在日志中发出。 - 扩展还需要计算查询标识符。 - 请注意,如果内核查询标识符计算方法不可接受,也可以使用外部模块。 - 在这种情况下,必须始终禁用内核计算。 - 有效值为 off(始终禁用), - on(始终启用),auto, - 允许诸如 这样的模块 - 自动启用它,并且 regress 具有与 - auto 相同的效果,只是查询标识符不会显示在 - EXPLAIN 输出中,以便促进自动回归测试。 - 默认值为 auto。 + 启用内置的查询标识符计算功能。查询标识符可以显示在pg_stat_activity视图或EXPLAIN的输出中,也可以通过参数配置后写入日志。扩展也要求计算查询标识符。注意,如果内置的查询标识符计算方法不符合要求,可以改用外部模块。在这种情况下,必须始终禁用内置计算功能。有效值为off(始终禁用)、on(始终启用)、auto(允许等模块自动启用此功能),以及regress。后者与auto效果相同,但不会在EXPLAIN输出中显示查询标识符,以便进行自动回归测试。默认值为auto @@ -6247,7 +6211,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 对于每个查询,将各自模块的性能统计输出到服务器日志中。这是一个简单的性能分析工具,类似于Unix getrusage()操作系统功能。 - log_statement_stats报告总语句统计,而其他选项报告每个模块的统计信息。 + log_statement_stats报告整个语句的统计信息,而其他选项报告每个模块的统计信息。 log_statement_stats不能与任何单独模块选项一起启用。所有这些选项默认情况下都是禁用的。 只有超级用户和具有适当SET权限的用户才能更改这些设置。 @@ -6532,7 +6496,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; DEBUG1LOGNOTICEWARNINGERROR。 每个级别都包括其后的所有级别。级别越靠后,被发送的消息越少。默认值是NOTICE。 - 注意LOG在这里有与中不同的排名。 + 注意LOG在这里的排序与中的不同。 @@ -6552,15 +6516,15 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,用于进行搜索该对象的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 + 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,搜索该对象时的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 - search_path的值必需是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被安静地忽略。 + search_path的值必须是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被静默忽略。 - 如果列表项之一是特殊名$user,则具有SESSION_USER返回的名字的模式将取代它(如果有这样一个模式并且该用户有该模式的USAGE权限;如果没有,$user会被忽略)。 + 如果列表项之一是特殊名$user,则具有CURRENT_USER返回的名字的模式将取代它(如果有这样一个模式并且该用户有该模式的USAGE权限;如果没有,$user会被忽略)。 @@ -6585,11 +6549,12 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个参数的缺省值是"$user", public。这种设置支持一个数据库(其中没有用户拥有私有模式,并且所有人共享使用public)、每个用户私有模式及其组合的共享使用。其它效果可以通过全局或者针对每个用户修改默认搜索路径设置获得。 + 这个参数的默认值是"$user", public。这种设置支持共享使用数据库(用户没有私有模式,所有人共享使用public)、每个用户拥有私有模式,以及二者的组合。 + 还可以通过全局或针对每个用户修改默认搜索路径设置来获得其他效果。 - 更多有关方案处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 + 更多有关模式处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 @@ -6609,7 +6574,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,只要有至少一条策略被应用则查询就会失败。默认为on。受限的行可见性会导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS)属性的角色没有效果。 + 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,原本会应用至少一条策略的查询就会失败。默认为on。受限的行可见性可能导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS属性的角色)没有效果。 @@ -6628,8 +6593,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个参数指定了在创建表或物化视图时使用的默认表访问方法,如果CREATE命令没有明确指定访问方法, - 或者当使用SELECT ... INTO时,不允许指定表访问方法。默认值是heap。 + 创建表或物化视图时,如果CREATE命令没有显式指定访问方法,或者使用了不允许指定表访问方法的SELECT ... INTO,则使用此参数指定的默认表访问方法。默认值为heap @@ -6649,7 +6613,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建企图将失败。 + 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建尝试将失败。 @@ -6657,7 +6621,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当创建数据库时也会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 + 创建数据库时也不会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 @@ -6706,11 +6670,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被放置在里表中的连续表空间中。如果列表被选中元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 + 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被依次放置在列表中的连续表空间中。如果列表中被选中的元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 - 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,类似于为用户指定一个不具有CREATE权限的表空间。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特殊地,使用一个在postgresql.conf中设置的值时,这条规则起效。 + 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,指定一个用户不具有CREATE权限的表空间也同样是错误。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特别是,使用一个在postgresql.conf中设置的值时,这条规则起效。 @@ -6735,7 +6699,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 这个参数通常为打开。 当设置为off时,它禁用期间对例程体字符串的验证。 - 禁用验证避免了验证处理的副作用,特别避免了如向前引用导致的伪肯定。 + 禁用验证避免了验证处理的副作用,特别是避免前向引用等问题导致的误报。 在代表其他用户载入函数之前设置这个参数为offpg_dump会自动这样做。 @@ -6778,7 +6742,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态 。默认是off(读/写)。 + 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态。默认是off(读/写)。 @@ -6801,11 +6765,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当运行在可串行化隔离级别时,一个可延迟只读 SQL 事务可以在它被允许继续之前延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的负荷;因此串行化代码将没有任何理由因为并发更新而强制它中断,使得这个选项适合于长时间运行的只读事务。 + 当运行在serializable隔离级别时,一个可延迟只读 SQL 事务可能在获准继续之前被延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的开销;因此串行化代码将没有任何理由因为并发更新而强制它中止,使得这个选项适合于长时间运行的只读事务。 - 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些操作在低于可串行化隔离级别上的事务无效。默认值是off。 + 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些运行在低于serializable隔离级别上的事务无效。默认值是off @@ -6849,7 +6813,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的只读状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -6869,7 +6833,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的可延迟性状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -6893,7 +6857,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 这个设置的预期用途是由逻辑复制系统在应用所复制的更改时将它设置为replica。 - 其效果将是触发器和规则(没有对其默认配置做修改)在复制机上将不会被触发。 + 其效果将是触发器和规则(没有对其默认配置做修改)在副本上将不会被触发。 更多信息请参考ALTER TABLE的子句ENABLE TRIGGER以及ENABLE RULE @@ -6923,9 +6887,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 超时从命令到达服务器的时间开始计算,一直到它被服务器完成为止。 - 如果单个简单查询消息中出现多个 SQL 语句,超时将分别应用于每个语句。(PostgreSQL 13 之前的版本通常将超时应用于整个查询字符串。 - 在扩展查询协议中,当任何与查询相关的消息(解析、绑定、执行、描述)到达时,超时就开始运行,并且可以通过执行完成或同步消息来取消超时。 + 超时从命令到达服务器时开始计算,直到服务器完成该命令为止。 + 如果单个简单查询消息中出现多个 SQL 语句,超时将分别应用于每个语句。 + (PostgreSQL 13 之前的版本通常将超时应用于整个查询字符串。) + 在扩展查询协议中,当任何与查询相关的消息(Parse、Bind、Execute、Describe)到达时开始计时, + 并在处理完 Execute 或 Sync 消息时取消计时。 @@ -6946,13 +6912,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 如果任何语句在试图获取表、索引、行或其他数据库对象上的锁时等到超过指定的时间量,该语句将被中止。 + 如果任何语句在试图获取表、索引、行或其他数据库对象上的锁时等待超过指定的时间量,该语句将被中止。 该时间限制独立地应用于每一次锁获取尝试。该限制会应用到显式锁定请求(如LOCK TABLE或不带NOWAITSELECT FOR UPDATE)和隐式获得的锁。 如果指定值时没有单位,则以毫秒为单位。一个零值(默认)将禁用超时。 - 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为事务超时将总是第一个被触发。 + 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为语句超时将总是第一个被触发。 如果log_min_error_statement 被设置为ERROR 或更低,超时的语句将被记录。 @@ -6972,15 +6938,14 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 终止任何已经闲置(这是指,等待客户端查询)超过这个参数所指定时间量的打开事务的会话。 - 如果这个值指定时没有单位,它被设为毫秒。 - 零值(默认)禁用超时。 + 终止在打开的事务中空闲(即等待客户端查询)超过指定时长的任何会话。 + 如果指定值时不带单位,则以毫秒为单位。零值(默认值)禁用此超时。 - 此选项可以用于确保空闲会话不会在不合理的时间内持有锁。 - 即使没有持有重要的锁的时候,打开的事务也会防止清理最近死亡的可能只对这个事务可见的元组;所以长时间保持空闲会导致表膨胀。 - 详见。 + 此选项可确保空闲会话不会持有锁过长时间。 + 即使没有持有重要的锁,打开的事务也会阻止清理最近死亡、且可能只对该事务可见的元组;因此长时间空闲可能造成表膨胀。 + 更多详情参见 @@ -6995,9 +6960,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 终止任何空闲的会话(也就是,等待客户端查询),但不在打开的事务中,且超过指定的时间量。 - 如果指定值时不带单位,其单位采用毫秒。 - 零值时(默认)禁用超时。 + 终止不在打开的事务中、且空闲(即等待客户端查询)超过指定时长的任何会话。 + 如果指定值时不带单位,则以毫秒为单位。零值(默认值)禁用此超时。 @@ -7005,8 +6969,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 注意不要对通过连接池软件或其他中间件建立的连接强制执行此超时,因为这样的层可能不会很好地响应意外的连接关闭。 - 只对交互会话启用此超时可能是帮助的,也许只对特定用户应用它。 + 应谨慎对通过连接池软件或其他中间件建立的连接强制执行此超时,因为这样的层可能不会很好地响应意外的连接关闭。 + 只对交互会话启用此超时可能有所帮助,也许只对特定用户应用它。 @@ -7018,8 +6982,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; + - 当表的pg_class.relfrozenxid字段达到该设置指定的年龄时,VACUUM会执行激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值是 1.5 亿个事务。尽管用户可以将该值设置为 0 到 20 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的 95%,从而在触发防回卷 autovacuum 之前仍有机会执行一次常规手工VACUUM。更多信息请参见。 + 如果表的pg_class.relfrozenxid字段达到此设置指定的年龄,VACUUM就会执行一次激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值为 1.5 亿个事务。尽管用户可以将该值设置在 0 到 20 亿之间,VACUUM仍会悄悄将其有效值限制为不超过的 95%,以便在针对该表启动防回卷自动清理之前,周期性手工VACUUM仍有机会运行。详见 @@ -7032,7 +6997,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 指定VACUUM在扫描表时用来决定是否冻结行版本的切断年龄(以事务计)。默认值是 5000 万个事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见。 + 指定VACUUM在扫描表时用来决定是否冻结行版本的截止年龄(以事务计)。默认值是 5000 万个事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见 @@ -7045,13 +7010,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 指定表的pg_class.relfrozenxid字段在VACUUM采取特别措施以避免系统范围事务 ID 回卷失败之前所允许达到的最大年龄(以事务计)。这是VACUUM的最后防线。失效保护通常会在防止事务 ID 回卷的 autovacuum 已经运行了一段时间后触发,但也有可能在任何VACUUM期间触发。 + 指定表的pg_class.relfrozenxid字段在VACUUM采取非常措施以避免系统范围事务 ID 回卷失败之前所允许达到的最大年龄(以事务数计)。这是VACUUM的最后手段。失效保护通常会在为防止事务 ID 回卷而启动的自动清理已经运行一段时间后触发,但也可能在任何一次VACUUM期间触发。 当失效保护被触发时,将不再应用任何有效的基于代价的延迟,并且会跳过进一步的非关键维护任务(例如索引清理)。 - 默认值为 16 亿个事务。尽管用户可以将该值设置为 0 到 21 亿之间的任意值,VACUUM会悄悄将有效值调整为不低于的 105%。 + 默认值为 16 亿个事务。尽管用户可以将该值设置在 0 到 21 亿之间,VACUUM仍会悄悄将其有效值调整为不低于的 105%。 @@ -7063,8 +7028,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; + - 当表的pg_class.relminmxid字段达到该设置指定的年龄时,VACUUM会执行激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不是只扫描那些可能包含死元组的页面。默认值是 1.5 亿个多事务。尽管用户可以将该值设置为 0 到 20 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的 95%,从而在触发防回卷 autovacuum 之前仍有机会执行一次常规手工VACUUM。更多信息请参见。 + 如果表的pg_class.relminmxid字段达到此设置指定的年龄,VACUUM就会执行一次激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值为 1.5 亿个多事务。尽管用户可以将该值设置在 0 到 20 亿之间,VACUUM仍会悄悄将其有效值限制为不超过的 95%,以便在针对该表启动防回卷清理之前,周期性手工VACUUM仍有机会运行。详见 @@ -7077,7 +7043,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 指定VACUUM在扫描表时用来决定是否将多事务 ID 替换为较新的事务 ID 或多事务 ID 的切断年龄(以多事务计)。默认值是 500 万个多事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见。 + 指定VACUUM在扫描表时用来决定是否将多事务 ID 替换为较新的事务 ID 或多事务 ID 的截止年龄(以多事务计)。默认值是 500 万个多事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见 @@ -7130,7 +7096,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这里的实际选择都是根据爱好做出的,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码将比 base64 编码更大。 + 这里的实际选择主要取决于偏好,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码会比 base64 编码略大。 @@ -7151,7 +7117,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当在XML和字符串值之间进行转换时,无论设置DOCUMENT或 CONTENT都是隐式的。可参阅Section 8.13。 有效值是DOCUMENT和CONTENT。 缺省值是CONTENT。当在 XML 和字符串值之间进行转换时,设置DOCUMENTCONTENT都是隐式的。详见。有效值是DOCUMENTCONTENT。默认值是CONTENT。 + 设置在 XML 与字符串值之间进行转换时,隐含采用DOCUMENT还是CONTENT。 + 有关说明参见。有效值是DOCUMENTCONTENT。默认值是CONTENT @@ -7186,7 +7153,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; restrict_nonsystem_relation_kind (string) - restrict_nonsystem_relation_kind配置参数 + restrict_nonsystem_relation_kind + 配置参数 @@ -7201,7 +7169,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 区域和格式化 + 区域设置和格式化 @@ -7215,7 +7183,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域行为的设置初始化配置文件。 + 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域设置行为的设置初始化配置文件。 @@ -7230,11 +7198,14 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置间隔值的显示格式。值sql_standard将产生匹配 SQL 标准间隔文本的输出。当参数被设置为ISO时,值postgres(默认)将产生匹配PostgreSQL发行 8.4 之前的输出。当DateStyle参数被设置为非ISO输出时,值postgres_verbose会产生匹配PostgreSQL发行 8.4 之前的输出。值iso_8601会产生匹配在 ISO 8601 的 4.4.3.2 节中定义的带标志符格式的时间间隔的输出。 + 设置时间间隔值的显示格式。值sql_standard会生成符合SQL标准时间间隔字面量的输出。 + 值postgres(默认值)的输出与PostgreSQL 8.4 之前版本中设为ISO时的输出一致。 + 值postgres_verbose的输出与PostgreSQL 8.4 之前版本中DateStyle设为非ISO输出时的输出一致。 + 值iso_8601会生成符合 ISO 8601 第 4.4.3.2 节定义的时间间隔带标志符格式的输出。 - IntervalStyle参数也可以影响对有歧义的间隔输入的解释。详见。 + IntervalStyle参数也会影响对有歧义的时间间隔输入的解释。详见 @@ -7292,23 +7263,23 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 如果值为1(默认值)或更高,浮点值被输出为最短-精度格式;参见。 + 如果值为 1(默认值)或更高,浮点值被输出为最短精确格式;参见。 实际生成的位数只取决于输出的值,而不取决于此参数的值。 - float8 值最多需要 17 位数字,float4值最多需要9位数字。 + float8 值最多需要 17 位数字,float4值最多需要9位数字。 这种格式既快速又精确,在正确读取时精确地保留了原始的二进制浮点值。为了历史兼容性,允许的值最大为3。 如果值为零或负,则输出四舍五入为给定的十进制精度。 - 使用的精度是根据此参数的值减小的类型((FLT_DIGDBL_DIG,视情况而定)的标准位数。 + 所用精度以该类型的标准位数(根据类型使用FLT_DIGDBL_DIG)为基础,再按此参数的值减少。 (例如,指定 -1 将导致float4 值输出四舍五入为 5 位有效数字,而float8值四舍五入为 14 位。) - 此格式较慢,不会保留二进制浮点值的所有位,但可能令人更易于阅读。 + 此格式较慢,不会保留二进制浮点值的所有位,但可能更便于阅读。 此参数的含义,以及其默认值,在 PostgreSQL 12 中发生了变化; - 参见 以便进一步讨论。 + 参见 了解进一步讨论。 @@ -7344,7 +7315,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 在一些系统上,这个区域分类并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 + 在一些系统上,这个区域设置类别并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 @@ -7363,7 +7334,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化货币量的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化货币量的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -7378,7 +7349,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化数字的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化数字的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -7393,7 +7364,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化日期和时间的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化日期和时间的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -7410,7 +7381,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 选择被那些没有显式参数指定配置的文本搜索函数变体使用的文本搜索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配区域的配置,initdb将用对应于选中的lc_ctype区域的设置初始化配置文件。 + 选择被那些没有显式参数指定配置的文本检索函数变体使用的文本检索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配该区域设置的配置,initdb将用对应于选中的lc_ctype区域设置的值初始化配置文件。 @@ -7425,7 +7396,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 为了载入附加的功能或者达到提高性能的目的,可用多个设置来预先载入共享库到服务器中。 - 例如'$libdir/mylib'设置可能会导致mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 + 例如'$libdir/mylib'设置会使mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 @@ -7434,12 +7405,12 @@ SET XML OPTION { DOCUMENT | CONTENT }; 只有特别为与PostgreSQL一起使用设计的共享库才能以这种方式载入。每一个PostgreSQL支持 - 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非PostgreSQL无法 + 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非 PostgreSQL 库无法 以这种方式被载入。你可能可以使用操作系统的工具(如LD_PRELOAD)载入它。 - 总之,请参考特定模块的文档来用推荐的方法载入它。 + 一般来说,请参考特定模块的文档来用推荐的方法载入它。 @@ -7473,9 +7444,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 这个特性的目的是允许非特权用户在特定的会话中载入正在调试的或者性能度量库, - 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客 - 户端的PGOPTIONS环境变量或者 + 这个特性的目的是允许非特权用户在特定的会话中载入用于调试或性能测量的库, + 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客户端的PGOPTIONS环境变量或者 ALTER ROLE SET来设置这个参数。 @@ -7513,7 +7483,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 不同,相对于在库被第一次使用 - 时载入它,在会话开始时载入库并没有什么性能优势。不过,当使用连接池时这样做还是有一些 + 时载入它,在会话开始时载入库并没有明显的性能优势。不过,当使用连接池时这样做还是有一些 优势。 @@ -7553,9 +7523,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 在 Windows 主机上,在服务器启动时预载入一个库并不会减少启动每个新服务器进程所需的 - 时间;每一个服务器进程将会重新载入预载入的库。不过,对于那些要在postmaster启动时 + 时间;每一个服务器进程将会重新载入所有预载入的库。不过,对于那些要在postmaster启动时 执行操作的库来说,Windows 主机上的 - shared_preload_libraries任然有用。 + shared_preload_libraries仍然有用。 @@ -7603,13 +7573,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 如果需要打开一个可以动态装载的模块并且在CREATE FUNCTIONLOAD命令中指定的文件名没有目录部分(即名字中不包含斜线),那么系统将搜索这个路径以查找所需的文件。 - - dynamic_library_path的值必须是一个冒号分隔(或者在 Windows 上以分号分隔)的绝对目录路径的列表。如果一个列表元素以特殊字符串开始,$libdir会被替换为PostgreSQL包中已编译好的库目录。这里是PostgreSQL发布提供的模块被安装的位置(使用pg_config --pkglibdir来找到这个目录的名字)。例如: - + 参数dynamic_library_path的值必须是由冒号(Windows上为分号)分隔的绝对目录路径列表。如果某个列表元素以特殊字符串$libdir开头,则会使用编译时确定的PostgreSQL软件包的库目录来替换$libdir;该目录是标准PostgreSQL发行版所提供模块的安装位置。(使用pg_config --pkglibdir可以找出此目录的名称。)例如: dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir' - - 或者在 Windows 环境中: - +或者,在 Windows 环境中: dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' @@ -7638,7 +7604,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - GIN 索引返回的集合尺寸的软上限。详见。 + GIN 索引扫描返回的集合尺寸的软上限。详见 @@ -7671,18 +7637,18 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这是在锁上等待的时间,然后再检查是否存在死锁条件。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 + 指定在检查是否发生死锁之前等待锁的时间。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 我们乐观地假设在生产应用程序中死锁并不常见,所以在检查死锁之前只是等待一段时间。 增加此值会减少在不必要的死锁检查中浪费的时间,但会减慢实际死锁错误的报告速度。 如果未指定单位,则将其视为毫秒。 - 默认值为一秒(1s),这可能是您在实践中想要的最小值。 - 在负载较重的服务器上,您可能希望提高它。 - 理想情况下,设置应超过您的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 + 默认值为一秒(1s),这可能是你在实践中想要的最小值。 + 在负载较重的服务器上,你可能希望提高它。 + 理想情况下,设置应超过你的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 只有超级用户和具有适当SET权限的用户才能更改此设置。 - 当被设置时,这个参数还可以决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 + 当被设置时,这个参数也决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 @@ -7735,7 +7701,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制在谓词锁被提升为覆盖整个关系之前,该谓词锁能够在单个关系上锁住多少页面或元组。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个关系之前,可以对单个关系中的多少页面或元组加谓词锁。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -7750,7 +7716,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制在谓词锁被提升为覆盖整个页面之前,该谓词锁能在单一页面上锁住多少行。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个页面之前,可以对单个页面中的多少行加谓词锁。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -7778,7 +7744,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个空数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。对于那些要求旧行为的应用的向后兼容性,这个变量可以被设置为off。 + 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个值为空值的数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。为了向后兼容那些要求旧行为的应用,这个变量可以被设置为off @@ -7798,11 +7764,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制字符串文本中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\'。如果客户端代码没有做到正确转义,那么将会导致 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 + 这个参数控制字符串字面量中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\。如果客户端代码没有做到正确转义,那么就可能遭到 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 - 注意在符合标准的字符串文本中,\就表示\。这个参数只影响不符合标准的文本的处理,包括转义字符串语法(E'...')。 + 注意在符合标准的字符串字面量中,\就表示\。这个参数只影响不符合标准的字面量的处理,包括转义字符串语法(E'...')。 @@ -7818,11 +7784,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 打开时,如果在普通字符串文本中('...'语法)出现了 一个反斜线(\)并且standard_conforming_strings为关闭,那么就会发出一个警告。默认值是on。 + 打开时,如果在普通字符串字面量中('...'语法)出现了 一个反斜线(\)并且standard_conforming_strings为关闭,那么就会发出一个警告。默认值是on - 希望使用反斜线作为转义符的应用应该被修改来使用转义字符串语法(E'...'),因为在 SQL 标准中普通字符串的默认行为是将反斜线视作一个普通字符。这个变量可以被启用来帮助定位需要被更改的代码。 + 希望使用反斜线作为转义符的应用应该被修改来使用转义字符串语法(E'...'),因为按照 SQL 标准,普通字符串现在默认将反斜线视作一个普通字符。这个变量可以被启用来帮助定位需要被更改的代码。 @@ -7843,7 +7809,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 设置这个参数不会禁用所有与大对象相关的安全检查 — 除了那些在PostgreSQL 9.0中已经修改了的默认行为。 + 设置此变量不会禁用所有与大对象相关的安全检查 — 只禁用那些在PostgreSQL 9.0 中默认行为发生变化的检查。 @@ -7866,7 +7832,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' standard_conforming_strings (boolean) - 字符串标准符合 + 字符串符合标准 standard_conforming_strings配置参数 @@ -7874,7 +7840,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 控制普通字符串文本('...')是否按照 SQL 标准把反斜线当普通文本。从PostgreSQL 9.1 开始,默认值为on(之前的发行中默认值为off)。应用可以检查这个参数来判断字符串文本如何被处理。这个参数的存在也可以被当做转义字符串语法(E'...')被支持的标志。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 + 控制普通字符串字面量('...')是否按照 SQL 标准把反斜线当普通文本。从PostgreSQL 9.1 开始,默认值为on(之前的发行中默认值为off)。应用可以检查这个参数来判断字符串字面量如何被处理。这个参数的存在也可以被当做转义字符串语法(E'...')被支持的标志。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 @@ -7889,7 +7855,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询来,这样的扫描会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on。 + 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询,这样的扫描可能会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on @@ -7913,15 +7879,15 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr得出空值值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空(未知)。因此这个参数默认为off。 + 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr计算结果为空值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空值(未知)。因此这个参数默认为off - 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释)。它们不是非常有用并且在普通应用中也不常见,在应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及 空值的表达式的语义上感到困惑,因此这个选项默认为关闭。 + 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释),它们不是非常有用并且在普通应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及空值的表达式语义感到困惑,因此这个选项默认为关闭。 - 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不是劣质程序的一般修复。 + 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不能普遍修复错误的程序写法。 @@ -7967,7 +7933,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 当被设置为开(on),PostgreSQL将在一次后端崩溃后自动重新初始化。 + 当设置为 on(默认值)时,PostgreSQL将在一次后端崩溃后自动重新初始化。 让这个值设置为开(on)通常是将数据库可用性最大化的最佳方法。但是在某些环境中,例如PostgreSQL被集群软件调用时,禁用重启可能很有用,这样集群软件可以得到控制并且采取它认为适当的行动。 @@ -7987,7 +7953,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果设置为关(off),PostgreSQL在将修改的数据文件刷新到文件系统失败时,将引发PANIC级错误。 + 当设置为 off(默认值)时,PostgreSQL在将修改后的数据文件刷盘到文件系统失败时,将引发PANIC级错误。 这样会导致数据库服务器崩溃。这个参数只能在服务器启动时被设置。 @@ -7996,8 +7962,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果设置为开(on),PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷新操作。 - 仅在调查操作系统假如回写失败时对缓冲数据的处理方式的情况下,才将其设置为开(on)。 + 如果设置为开(on),PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷盘操作。 + 只有在调查清楚操作系统在回写失败时如何处理缓冲数据之后,才应将其设置为开(on)。 @@ -8014,14 +7980,14 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 当设置为fsync,也就是默认值,PostgreSQL将在崩溃恢复开始之前递归地打开并同步数据目录中的所有文件。 对文件的搜索将遵循WAL目录和每个配置表空间的符号链接(而不是任何其它符号链接)。 - 这是为了确保在重现更改之前,所有WAL和数据文件都持久地存储在硬盘上。 - 这适用于在启动没有完全关闭的数据库集簇时,包括由pg_basebackup创建的副本。 + 这是为了确保在重放更改之前,所有WAL和数据文件都持久地存储在磁盘上。 + 这适用于每次启动未正常关闭的数据库集簇时,包括由pg_basebackup创建的副本。 - 在Linux上,可以用syncfs代替,请求操作系统来同步包含数据目录的整个文件系统,WAL文件和每个表空间(但不是通过符号链接可访问到的任何其他文件系统)。 + 在Linux上,可以用syncfs代替,请求操作系统来同步数据目录、WAL 文件和各个表空间所在的整个文件系统(但不是通过符号链接可访问到的任何其他文件系统)。 这可能比fsync设置快得多,因为它不需要逐个打开每个文件。 - 另一方面,如果一个文件系统是被其他需要修改大量文件的应用程序共享的,它可能会慢一些,因为这些文件也将写入硬盘。 + 另一方面,如果一个文件系统是被其他需要修改大量文件的应用程序共享的,它可能会慢一些,因为这些文件也将写入磁盘。 此外,在5.8之前的Linux版本中,向磁盘写入数据时遇到的I/O错误可能不会报告给PostgreSQL,相关的错误消息可能只出现在内核日志中。 @@ -8040,11 +8006,10 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 预置选项 - 下列参数是只读的。 - 同样,它们被排除在postgresql.conf文件示例之外。 - 这些选项报告特定应用可能感兴趣的多种PostgreSQL行为,特别是管理前端相关的行为。 - 所有这些都是在PostgreSQL被编译或者它被安装时决定的。 - + 下列参数是只读的,因此未列入示例 postgresql.conf 文件。 + 这些选项报告 PostgreSQL 行为的各个方面,某些应用(特别是管理前端)可能对此感兴趣。 + 其中大多数参数在编译或安装 PostgreSQL 时确定。 + @@ -8073,7 +8038,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告对这个集簇是否启用了数据校验码。详见。 + 报告对这个集簇是否启用了数据校验和。详见 @@ -8088,7 +8053,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 在Unix系统上,这个参数报告启动时的数据目录(由定义)的权限。 + 在 Unix 系统上,这个参数报告服务器启动时数据目录(由定义)的权限。 (在Microsoft Windows上这个参数将总是显示0700。) 更多信息请参考 @@ -8126,7 +8091,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告PostgreSQL是否在编译时打开了 64 位整数日期和时间。从PostgreSQL 10起,这个值总是on。 + 报告PostgreSQL是否在编译时启用了对 64 位整数日期和时间的支持。从PostgreSQL 10起,这个值总是on @@ -8142,9 +8107,9 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 报告服务器当前是否处于热备模式。 - 当这个是on的时候,所有的事务强制为只读。 - 在会话中,这个只能在服务器提升为主库的时候变更。 - 更多信息参见 + 当此值为 on 时,所有事务都被强制为只读。 + 在会话中,此值只有在服务器被提升为主库时才会改变。 + 更多信息参见 @@ -8186,7 +8151,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定的。默认值是 100 个参数。 + 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定。默认值是 100 个参数。 @@ -8201,7 +8166,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64 ;因此max_identifier_length的默认值是 63,但是在使用多字节编码时可以少于 63 个字符。 + 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64;因此max_identifier_length的默认值是 63 字节,在使用多字节编码时,这可能不足 63 个字符。 @@ -8264,7 +8229,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告服务器版本数值。它是由编译服务器时的PG_VERSION值决定的。 + 报告服务器的版本号。它是由编译服务器时的PG_VERSION值决定的。 @@ -8279,7 +8244,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告服务器版本数值的整数值。它是由编译服务器时的PG_VERSION_NUM值决定的。 + 以整数形式报告服务器的版本号。它是由编译服务器时的PG_VERSION_NUM值决定的。 @@ -8294,7 +8259,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告主共享内存区域的大小,四舍五入到最接近的兆字节。 + 报告主共享内存区域的大小,向上取整到整数兆字节。 @@ -8331,8 +8296,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告此PostgreSQL服务器已构建的 SSL 库的名称(即使此实例当前未配置或使用 SSL), - 例如OpenSSL,或一个空字符串(如果没有)。 + 报告此PostgreSQL服务器在构建时使用的 SSL 库的名称(即使此实例当前未配置或使用 SSL), + 例如OpenSSL,如果没有使用 SSL 库,则报告空字符串。 @@ -8375,11 +8340,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 自定义选项 - 这个特性被设计用来由附加模块向PostgreSQL添加通常不为系统知道的参数(例如过程语言)。这允许使用标准方法配置扩展模块。 + 这个特性允许附加模块(例如过程语言)向PostgreSQL添加系统通常不认识的参数。这样便能以标准方式配置扩展模块。 - 自定义选项有两部分名称:一个扩展名,然后是一个句点,再然后是正确的参数名,就像 SQL 中的合格名称。一个示例是plpgsql.variable_conflict。 + 自定义选项的名称由两部分组成:扩展名称和参数名本身,中间用句点分隔,类似于 SQL 中的限定名。例如plpgsql.variable_conflict @@ -8387,7 +8352,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' PostgreSQL将接受任何两部分参数名称的设置。 这些变量被视为占位符,在定义它们的模块加载之前没有任何功能。 当加载扩展模块时,它将添加其变量定义并根据这些定义转换任何占位符值。 - 如果存在以其扩展名开头的任何未识别的占位符,将发出警告并删除这些占位符。 + 如果存在以其扩展名称开头的任何未识别的占位符,将发出警告并删除这些占位符。 @@ -8396,11 +8361,10 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 开发者选项 - 下面的参数目的是用在开发测试上, 并且永远不能用于生产数据库。 - 但是,它们中的一些能够用于帮助恢复严重损坏的数据库。 - 同样,它们被从示例postgresql.conf文件中排除。 - 请注意许多这些参数要求特殊的源代码编译标志才能工作。 - + 以下参数用于开发者测试,切勿用于生产数据库。不过,其中一些参数可用于辅助恢复严重损坏的数据库。 + 因此,它们未列入示例postgresql.conf文件。 + 请注意,许多参数需要特殊的源代码编译标志才能起作用。 + @@ -8413,7 +8377,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 允许将表空间创建为pg_tblspc内的目录,当CREATE TABLESPACE命令提供空位置字符串时。 + 当向CREATE TABLESPACE命令提供空的位置字符串时,允许将表空间创建为pg_tblspc内的目录。 这旨在允许测试主库和备库在同一台机器上运行的复制场景。这样的目录可能会混淆备份工具,因为这些工具期望在该位置只找到符号链接。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -8430,8 +8394,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 允许修改系统表的结构以及对系统表进行某些其他风险操作。即使对于超级用户,这也通常是不允许的。 - 不明智地使用此设置可能导致无法检索的数据丢失或严重损坏数据库系统。 + 允许修改系统表的结构以及对系统表进行某些其他风险操作。否则,即使超级用户也不允许执行这些操作。 + 不明智地使用此设置可能导致无法挽回的数据丢失或严重损坏数据库系统。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -8474,14 +8438,14 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 当设置为1时,每个系统目录缓存条目在第一个可能的机会时失效,不管任何使之无效的事情是否真的发生。 - 作为结果,系统目录的缓存被有效地禁用,因此服务器将运行得非常缓慢。 - 较高的值递归地运行缓存失效,这样会更慢,而且只用于测试缓存逻辑自身。 + 当设置为1时,每个系统目录缓存条目都会在最早可能的时刻被置为无效,无论是否真的发生了使其失效的事件。 + 这实际上禁用了系统目录缓存,因此服务器将运行得非常缓慢。 + 较高的值递归地运行缓存失效,这样会更慢,而且仅对测试缓存逻辑本身有用。 默认值0选择正常的目录缓存行为。 - 当试图触发涉及并发目录更改的难以复现的错误时,此参数非常有用,但除此之外它不太被需要。 + 当试图触发涉及并发目录更改的难以复现的错误时,此参数非常有用,但除此之外很少需要使用它。 详情请参见源码文件inval.cpg_config_manual.h @@ -8543,7 +8507,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据的时有用。这个参数在会话开始之后不能被更改。 + 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据时有用。这个参数在会话开始之后不能被更改。 @@ -8558,8 +8522,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 执行认证过程后启动新服务器进程时延迟的时间量。这是为了给开发者们一个机会在一个服务器进程上附加一个调试器。 - 如果指定值时没有单位,则以秒为单位。0值(默认值)禁用延迟。这个参数在会话开始之后不能被更改。 + 新服务器进程启动并完成认证过程之后的延迟时间。这旨在给开发者一个机会,用调试器附加到服务器进程上。 + 如果指定值时没有单位,则以秒为单位。零值(默认值)禁用延迟。这个参数在会话开始之后不能被更改。 @@ -8574,8 +8538,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 在新服务器进程分叉后,在进行认证过程之前,延迟的时间量。这是为了给开发者们一个机会在一个服务器进程上附加一个调试器来跟踪认证过程中的不当行为。 - 如果指定值时没有单位,则以秒为单位。0值(默认值)禁用延迟。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 新服务器进程刚刚派生之后、执行认证过程之前的延迟时间。这旨在给开发者一个机会,用调试器附加到服务器进程上,跟踪认证过程中的异常行为。 + 如果指定值时没有单位,则以秒为单位。零值(默认值)禁用延迟。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -8590,7 +8554,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 + 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 @@ -8622,7 +8586,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果打开,发出在排序操作中的资源使用的相关信息。只有在编译PostgreSQL时定义了TRACE_SORT宏, 这个参数才可用(不过,当前在默认情况下就定义了TRACE_SORT)。 + 如果开启,输出排序操作中的资源使用信息。只有在编译PostgreSQL时定义了TRACE_SORT宏, 这个参数才可用(不过,当前在默认情况下就定义了TRACE_SORT)。 @@ -8637,7 +8601,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。对每一种锁类型,已授权锁和等待锁的计数也会被一起转储。一个日志文件输出的示例如下: + 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。还会转储每种锁类型已授予的锁数、等待的锁数,以及它们的总数。一个日志文件输出的示例如下: LOG: LockAcquire: new: lock(0xb7acd844) id(24688,24696,0,0,0,1) grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0 @@ -8709,7 +8673,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果设置,不会跟踪小于这个 OID 的锁(用于避免在系统表上的输出)。 + 如果设置,不会跟踪 OID 小于此值的表上的锁(用于避免在系统表上的输出)。 @@ -8785,7 +8749,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,被修改的任何缓冲区的整页镜像及其WAL记录都被加入到记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 + 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,与该 WAL 记录相关的所有已修改缓冲区的整页镜像都会被添加到该记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 @@ -8829,10 +8793,10 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 在读取过程中检测到校验和失败通常会导致PostgreSQL报告错误,中止当前事务。 - 将ignore_checksum_failure设置为on会导致系统忽略失败(但仍然报告警告),并继续处理。 - 这种行为可能导致崩溃,传播或隐藏损坏,或其他严重问题。然而,它可能允许您跳过错误, - 并检索可能仍然存在于表中的未损坏的元组,如果块头仍然正常。如果头部损坏,即使启用此选项也会报告错误。 - 默认设置为off。 + 将ignore_checksum_failure设置为 on 会使系统忽略失败(但仍报告警告),并继续处理。 + 这种行为可能导致崩溃、传播或隐藏损坏,或引发其他严重问题。 + 但是,如果块首部仍然正常,它可能允许你跳过错误,检索表中可能仍然存在的未损坏元组。 + 如果首部损坏,即使启用此选项也会报告错误。默认设置为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -8850,7 +8814,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 检测到损坏的页面头通常会导致PostgreSQL报告错误,中止当前事务。 将zero_damaged_pages设置为on会导致系统报告警告,将内存中的损坏页面清零,并继续处理。 - 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许您跳过错误,并从表中可能存在的未损坏页面中检索行。 + 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许你跳过错误,并从表中可能存在的未损坏页面中检索行。 如果由于硬件或软件错误而发生损坏,这对于恢复数据很有用。通常在放弃从表的损坏页面恢复数据的希望之前,不应将其设置为on。 清零的页面不会强制写入磁盘,因此建议在再次关闭此参数之前重新创建表或索引。默认设置为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -8870,8 +8834,8 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 如果设置为 off(默认值),则在恢复期间检测到引用无效页面的 WAL 记录会导致 PostgreSQL 引发 PANIC 级别错误,中止恢复。 将ignore_invalid_pages设置为on会导致系统忽略 WAL 记录中的无效页面引用(但仍报告警告),并继续恢复。 - 此行为可能会导致崩溃、数据丢失、传播或隐藏腐败,或其他严重问题。 - 但是,它可能允许你通过 PANIC 级错误,完成恢复,并启动服务器。 + 此行为可能会导致崩溃、数据丢失、传播或隐藏损坏,或其他严重问题。 + 但是,它可能允许你跳过 PANIC 级错误,完成恢复,并启动服务器。 参数只能在服务器启动时设置。它仅在恢复期间或备库模式下生效。 @@ -8887,7 +8851,8 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果LLVM有所需要的功能,用GDB注册所生成的函数。这会让调试更加容易。默认设置是off。只有超级用户和具有适当SET权限的用户可以在会话开始时更改这个参数,并且在会话内完全不能更改它。 + 如果 LLVM 具有所需的功能,则向GDB注册生成的函数。 + 这会让调试更加容易。默认设置为off。只有超级用户和具有适当SET权限的用户才能在会话开始时更改此参数,并且在会话内完全不能更改它。 @@ -8903,7 +8868,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 将生成的LLVM IR写入文件系统,位于内。 - 这仅对于在JIT实现内部工作时有用。默认设置为off。 + 这仅对开发 JIT 的内部实现有用。默认设置为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -8934,10 +8899,9 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果LLVM有所需的功能,发出需要的数据以允许perf对JIT生成的函数画像。 - 这会写出文件到~/.debug/jit/中,如果需要,由用户负责对其执行清除。 - 默认设置是off。 - 只有超级用户和具有适当SET权限的用户可以在会话开始时更改这个参数,并且在会话内完全不能更改它。 + 如果 LLVM 具有所需的功能,则输出让perf对 JIT 生成的函数进行性能分析所需的数据。 + 这会将文件写入~/.debug/jit/;用户应在需要时自行清理。 + 默认设置为off。只有超级用户和具有适当SET权限的用户才能在会话开始时更改此参数,并且在会话内完全不能更改它。 @@ -8967,8 +8931,8 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 当设置为on时,这是默认值,PostgreSQL将在后端崩溃后自动删除临时文件。 - 如果禁用,文件将被保留,并且也许可用于调试,例如。 + 当设置为on(默认值)时,PostgreSQL将在后端崩溃后自动删除临时文件。 + 如果禁用,文件将被保留,例如可用于调试。 重复的崩溃可能会导致无用文件的积累。 该参数只能在postgresql.conf文件中或服务器命令行中设置。 @@ -8989,12 +8953,12 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 短选项 - 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,并且它们作为一个单字母选项存在并不表示它们会被大量使用。 + 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,它们以单字母选项的形式存在,并不一定表示鼓励频繁使用这些选项。
- 短选项键 + 短选项对照 diff --git a/zh/15/datatype.sgml b/zh/15/datatype.sgml index 3f085e36..fa1cb9dd 100644 --- a/zh/15/datatype.sgml +++ b/zh/15/datatype.sgml @@ -151,7 +151,7 @@ line - 平面上的无限长的线 + 平面上的无限直线 @@ -175,7 +175,7 @@ money - 货币数量 + 货币额 @@ -183,7 +183,7 @@ s) ] decimal [ (p, s) ] - 可选择精度的精确数字 + 可选择精度的精确数值 @@ -195,7 +195,7 @@ pg_lsn - PostgreSQL日志序列号类型 + PostgreSQL 日志序列号 @@ -273,13 +273,13 @@ tsquery - 文本搜索查询 + 文本检索查询 tsvector - 文本搜索文档 + 文本检索文档 @@ -420,14 +420,14 @@
- 数字类型常量的语法在里描述。数字类型有一整套对应的数学操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 + 数字类型常量的语法在里描述。数字类型有一整套对应的算术操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 整数类型 - 整数 + integer @@ -440,7 +440,7 @@ int4 - 整数 + integer @@ -460,11 +460,11 @@
- 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。而只有在integer的范围不够的时候才使用bigint。 + 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。bigint则设计用于integer的范围不够的情况。 - SQL只声明了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在许多其它SQL数据库系统中使用。 + SQL只规定了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在某些其他SQL数据库系统中使用。 @@ -473,11 +473,11 @@ 任意精度数值 - 数字(数据类型) + numeric(数据类型) - 任意精度数字 + 任意精度数值 @@ -578,18 +578,18 @@ NUMERIC(3, 5)
- infinity - numeric (数据类型) + 无穷大 + numeric(数据类型) NaN - 非数字 + 非数 - 非数字 - 数字(数据类型) + 非数 + numeric(数据类型) @@ -676,7 +676,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 双精度 + double precision @@ -686,7 +686,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; float8 - 双精度 + double precision @@ -739,8 +739,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; 默认情况下,浮点值会以最短且精确的十进制表示形式输出; - 生成的十进制值比同一二进制精度下任何其他可表示值都更接近真实 - 存储的二进制值。(不过,为了避免输入例程普遍存在的一个错误, + 所生成的十进制值与实际存储的二进制值之间的距离,小于它与任何其他可用相同二进制精度表示的值之间的距离。(不过,为了避免输入例程普遍存在的一个错误, 即未能正确遵守舍入到最近偶数规则,当前输出值绝不会 恰好位于两个可表示值的正中间。) 对于float8值,最多使用 17 位有效十进制数字; @@ -749,14 +748,14 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 生成这种最短且精确的输出格式,比历史上的圆整格式要快得多。 + 生成这种最短且精确的输出格式,比历史上的舍入格式要快得多。 为了兼容旧版本PostgreSQL生成的输出, 并允许降低输出精度,可以使用 - 参数改为选择圆整后的 + 参数改为选择舍入后的 十进制输出。将该参数设置为 0 会恢复之前的默认行为,也就是把值 舍入为 6 位(对于float4)或 15 位 (对于float8)有效十进制数字。设置为负值会 @@ -770,7 +769,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 过去那些需要精确值的应用,往往必须把 + 过去那些需要精确值的应用,必须把 设置为 3 才能获得它们。 为了在版本之间获得最大兼容性,这类应用应继续这样做。 @@ -778,12 +777,12 @@ FROM generate_series(-3.5, 3.5, 1) as x; 无穷大 - 浮点型 + 浮点 - 非数字 - 浮点型 + 非数 + 浮点 @@ -855,13 +854,13 @@ FROM generate_series(-3.5, 3.5, 1) as x; - auto-increment + 自动递增 serial - sequence - and serial type + 序列 + 与 serial 类型 @@ -914,7 +913,7 @@ ALTER SEQUENCE tablename_ - 要向 serial 列插入序列中的下一个值,应指定让该列 + 要向 serial 列插入序列中的下一个值,应指定让serial列 使用其默认值。这既可以通过在 INSERT 语句的 列表中省略该列来实现,也可以通过使用 DEFAULT 关键字来实现。 @@ -990,7 +989,7 @@ ALTER SEQUENCE tablename_ SELECT '12.34'::float8::numeric::money; - 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有圆整错误。 + 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有舍入误差。 @@ -1002,7 +1001,7 @@ SELECT '52093.89'::money::numeric::float8; 一个 money 值除以一个整数值时,会朝零方向截去小数 - 部分。要得到圆整结果,可以除以一个浮点值,或者在除法前先把 + 部分。要得到舍入后的结果,可以除以一个浮点值,或者在除法前先把 money 转换为 numeric,再在除法后转换回 money(如果要避免精度丢失风险,后一种做法更好)。 当一个 money 值被另一个 money 值除时, @@ -1021,12 +1020,12 @@ SELECT '52093.89'::money::numeric::float8; - string + 字符串 - 字符 + character @@ -1061,7 +1060,7 @@ SELECT '52093.89'::money::numeric::float8; character(n), char(n) - 定长,空白填充 + 定长,空格填充 text @@ -1097,14 +1096,14 @@ SELECT '52093.89'::money::numeric::float8; - 类型名 varchar(n) 和 + varchar(n)char(n) 分别是 character varying(n)character(n) 的别名。 - 如果指定了长度,n 必须大于 0,且不能超过 - 10485760。character 若不带长度说明则等同于 - character(1)character varying 若不带长度 - 说明则接受任意大小的字符串。后者是 + 如果指定了长度,该长度必须大于零,且不能 + 超过 10485760。character 若不带长度说明则等同于 + character(1)。如果 character varying + 不带长度说明,则该类型接受任意长度的字符串。这是 PostgreSQL 的扩展。 @@ -1132,7 +1131,7 @@ SELECT '52093.89'::money::numeric::float8;
- 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储代码为零的字符(有时称为NUL)。有关更多信息,请参阅。 + 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储编码值为零的字符(有时称为NUL)。有关更多信息,请参阅 @@ -1151,7 +1150,7 @@ SELECT '52093.89'::money::numeric::float8; - 这三种类型之间没有性能差别,除了使用空白填充类型时会占用更多存储 + 这三种类型之间没有性能差别,除了使用空格填充类型时会占用更多存储 空间,以及在写入带长度约束的列时需要少量额外 CPU 周期来检查长度。 虽然在某些其他数据库系统中,character(n) 可能有一定性能优势,但在 PostgreSQL @@ -1186,7 +1185,7 @@ INSERT INTO test2 VALUES ('ok'); INSERT INTO test2 VALUES ('good '); INSERT INTO test2 VALUES ('too long'); ERROR: value too long for type character varying(5) -INSERT INTO test2 VALUES ('too long'::varchar(5)); -- explicit truncation +INSERT INTO test2 VALUES ('too long'::varchar(5)); -- 显式截断 SELECT b, char_length(b) FROM test2; b | char_length @@ -1310,7 +1309,7 @@ SELECT b, char_length(b) FROM test2; 开头(以便与转义格式区分)。在某些上下文中,这个开头的反斜线 可能需要通过双写进行转义(见 )。作为输入时,十六进制数字 - 可以使用大写或小写,并且在两个数字组成的一组之间允许出现空白 + 可以使用大写或小写,并且每两个数字组成一组,组与组之间允许出现空白 (但组内以及起始的 \x 序列中不能有空白)。 十六进制格式与大量外部应用和协议兼容,并且通常比转义格式转换得 更快,因此更推荐使用。 @@ -1374,7 +1373,7 @@ SELECT '\xDEADBEEF'::bytea; 0 - 0字节 + 零值字节 '\000' '\000'::bytea \x00 @@ -1519,10 +1518,10 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; time - 不带时区的时间 + time without time zone - 带时区的时间 + time with time zone timestamp @@ -1531,13 +1530,13 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; timestamptz - 带时区的时间戳 + timestamp with time zone - 不带时区的时间戳 + timestamp without time zone - 间隔 + interval 时间跨度 @@ -1621,7 +1620,7 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; - SQL 要求仅写 timestamp 时,应等效于 + SQL 标准要求仅写 timestamp 时,应等效于 timestamp without time zone,而 PostgreSQL 也遵循这种行为。 timestamptz 被接受为 @@ -1702,7 +1701,7 @@ MINUTE TO SECOND 其中 p 是可选的精度说明,给出秒字段中 保留的小数位数。精度可用于 timetimestampinterval 类型, - 范围是 0 到 6。这与前文描述的取值一致。如果在常量声明中没有指定 + 范围是 0 到 6。如果在常量声明中没有指定 精度,则默认采用该字面值本身的精度(但不超过 6 位)。 @@ -1731,7 +1730,7 @@ MINUTE TO SECOND 1999-01-08 - ISO 8601; 任何模式下的1月8日 + ISO 8601; 任何模式下的1月8日 (推荐格式) @@ -1767,27 +1766,27 @@ MINUTE TO SECOND 99-Jan-08 - YMD模式中的1月8日,否则错误 + YMD模式中的1月8日,否则报错 08-Jan-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 Jan-08-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 19990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 1999.008 - 年和一年中的日子 + 年和一年中的第几天 J2451187 @@ -1809,10 +1808,10 @@ MINUTE TO SECOND time - 无时区的时间 + time without time zone - 带时区的时间 + time with time zone @@ -1891,11 +1890,11 @@ MINUTE TO SECOND 040506+0730 - ISO 8601,以分数小时形式给出 UTC 偏移 + ISO 8601,时区的 UTC 偏移不是整小时 040506+07:30:00 - UTC偏移量指定为秒(ISO 8601中不允许) + UTC 偏移精确到秒(ISO 8601中不允许) 04:05:06 PST @@ -1972,11 +1971,11 @@ MINUTE TO SECOND - 带时区的时间戳 + timestamp with time zone - 无时区的时间戳 + timestamp without time zone @@ -2001,29 +2000,12 @@ January 8 04:05:06 1999 PST 也被支持。 - - SQL 标准通过时间后面是否带有 - +- 符号以及时区偏移,来区分 - timestamp without time zone 和 - timestamp with time zone 常量。因此,根据标准, - - + 按照SQL标准,timestamp without time zonetimestamp with time zone字面量的区别在于,时间后是否有+-符号及其后的时区偏移。因此,按照该标准, TIMESTAMP '2004-10-19 10:23:54' - - - 属于 timestamp without time zone,而 - - +timestamp without time zone,而 TIMESTAMP '2004-10-19 10:23:54+02' - - - 属于 timestamp with time zone。 - PostgreSQL 在确定字符串类型之前从不检查 - 其内容,因此会把上述两个值都视为 - timestamp without time zone。要确保一个常量被视为 - timestamp with time zone,应为其指定正确的显式类型: - - +timestamp with time zone。 + PostgreSQL在确定字符串字面量的类型之前,从不检查其内容,因此会把上述两者都视为timestamp without time zone。为确保字面量被视为timestamp with time zone,应为它显式指定正确类型: TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' @@ -2068,12 +2050,12 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' time - constants + 常量 date - constants + 常量 @@ -2105,12 +2087,12 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' infinity - date, timestamp, interval + date, timestamp 晚于所有其他时间戳 -infinity - date, timestamp, interval + date, timestamp 早于所有其他时间戳 @@ -2174,13 +2156,13 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' date 输出格式 - formatting + 格式化 time 输出格式 - formatting + 格式化 @@ -2213,7 +2195,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' ISO - ISO 8601, SQL标准 + ISO 8601,SQL 标准 1997-12-17 07:37:16-08 @@ -2244,7 +2226,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' - SQL和POSTGRES风格中,如果DMY域顺序被指定,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。 + SQL和POSTGRES风格中,如果指定了 DMY 字段顺序,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。 @@ -2292,10 +2274,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 时区有通用的字母缩写,就会显示该缩写;否则会以 ISO 8601 基本 格式的有符号数字偏移显示 (hh 或 - hhmm)。这些样式中显示的字母缩写, - 取自当前由 运行时参数选中的 IANA - 时区数据库条目;它们不受 - 设置影响。 + hhmm)。 @@ -2314,7 +2293,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 时区 - time zone + 时区 @@ -2399,8 +2378,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 除了时区名称和缩写之外, PostgreSQL 还接受 POSIX 风格的 时区说明,见 。 - 这个选项通常不如使用具名时区更合适,但如果没有可用的 IANA - 时区条目,它可能就是必需的。 + 这个选项通常不如使用具名时区更合适,但如果没有合适的 IANA 时区条目可用,它可能就是必需的。 @@ -2415,19 +2393,12 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 中午(UTC-5),无论当天名义上是否正在实行夏令时。 - - - POSIX 风格时区说明中的符号,其含义与 ISO 8601 日期时间值中的 - 符号正好相反。例如,与 - 2014-06-04 12:00+04 对应的 POSIX 风格时区写法 - 会是 UTC-4。 - - + 更复杂的是,一些司法辖区在不同时间使用同一时区缩写来表示不同的 UTC 偏移;例如在莫斯科,MSK 在某些年份表示 - UTC+3,在另一些年份则表示 UTC+4。PostgreSQL + UTC+3,在另一些年份则表示 UTC+4。PostgreSQL 会按照该缩写在所给日期上的含义(或最近一次的含义)来解释这类缩写; 但与上面的 EST 例子一样,这并不一定等同于该日期的 当地民用时间。 @@ -2443,7 +2414,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 时区名称和缩写并不是硬编码在服务器中的;它们来自安装目录下 .../share/timezone/ 和 - .../share/timezonesets/ 子目录中的数据 + .../share/timezonesets/ 子目录中的配置文件 (见 )。 @@ -2481,13 +2452,13 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' - interval值可以使用下列语法书写: + interval值可以使用下列详细语法书写: @ quantity unit quantity unit... direction - 其中quantity是一个数字(很可能是有符号的); + 其中quantity是一个数字(可以带有符号); unitmicrosecondmillisecondsecondminutehourday、 @@ -2521,7 +2492,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' P quantity unit quantity unit ... T quantity unit ... 字符串必须以 P 开头,并且可以包含一个 - T 来引出一天中时间单位。可用的单位缩写见 + T 来引出一天中的时间单位。可用的单位缩写见 。单位可以省略, 也可以按任意顺序出现,但小于一天的单位必须出现在 T 之后。特别是,M 的含义 @@ -2560,7 +2531,7 @@ P quantity unit M - 分钟 (在时间部分中) + 分钟(在时间部分中) S @@ -2665,7 +2636,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; P1Y2M3DT4H5M6S - 带标志符的ISO 8601 格式:含义同上 + ISO 8601 带标志符的格式:含义同上 P0001-02-03T04:05:06 @@ -2683,7 +2654,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; interval 输出格式 - formatting + 格式化 @@ -2732,7 +2703,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; iso_8601 风格的输出符合 ISO 8601 标准 - 4.4.3.2 节描述的带标志符格式。 + 4.4.3.2 节描述的带标志符的格式
@@ -2783,7 +2754,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; 布尔类型 - Boolean + 布尔 数据类型 @@ -2894,15 +2865,15 @@ SELECT * FROM test1 WHERE a; 数据类型 - enumerated (enum) + 枚举(enum) - enumerated types + 枚举类型 - 枚举(enum)类型是由一个静态、值的有序集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的日期,或者一个数据的状态值集合。 + 枚举(enum)类型是由一个静态的有序值集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的各天,或者一个数据的状态值集合。 @@ -3011,7 +2982,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 实现细节 - 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空格也是有意义的。 + 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空白也是有意义的。 @@ -3023,7 +2994,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 从内部枚举值到文本标签的翻译被保存在系统目录pg_enum中。可以直接查询该目录。 + 从内部枚举值到文本标签的转换关系被保存在系统目录pg_enum中。直接查询该目录可能会有所帮助。 @@ -3068,13 +3039,13 @@ SELECT person.name, holidays.num_weeks FROM person, holidays lseg32字节有限线段 - [(x1,y1),(x2,y2)] + ((x1,y1),(x2,y2)) box 32字节 矩形框 - (x1,y1),(x2,y2) + ((x1,y1),(x2,y2)) path @@ -3098,7 +3069,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays circle 24字节 - <(x,y),r>(中心点和半径) + <(x,y),r>(圆心和半径) @@ -3111,7 +3082,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 我们提供了丰富的函数和操作符来进行各种几何操作,例如缩放、平移、 - 旋转以及计算相交等,详见 。 + 旋转以及求交等,详见 @@ -3122,7 +3093,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 点是几何类型的基本二维构造块。用下面的语法描述point类型的值: + 点是几何类型的基本二维构造块。用下面任一种语法描述point类型的值: ( x , y ) @@ -3138,14 +3109,14 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线 + 直线 line - 线由线性方程Ax + By + C = 0 + 直线由线性方程Ax + By + C = 0 表示,其中AB不能同时为零。类型line 的值采用以下形式输入和输出: @@ -3165,7 +3136,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays (x1,y1)(x2,y2) - 是线上不同的两点。 + 是直线上不同的两点。 @@ -3181,7 +3152,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线段用一对线段的端点来表示。lseg类型的值用下面的语法声明: + 线段用一对线段的端点来表示。lseg类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ( x2 , y2 ) ] @@ -3205,15 +3176,15 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 方框 - box (data type) + box(数据类型) - rectangle + 矩形 - 方框用其对角的点对表示。box类型的值使用下面的语法指定: + 方框用其对角的点对表示。box类型的值使用下面任一种语法指定: ( ( x1 , y1 ) , ( x2 , y2 ) ) @@ -3232,7 +3203,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 在输入时可以提供任意两个对角,但是值将根据需要被按顺序记录为右上角和左下角。 + 在输入时可以提供任意两个对角,但是值将根据需要被重新排列,并依次存储为右上角和左下角。 @@ -3240,7 +3211,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 路径 - path (data type) + path(数据类型) @@ -3248,7 +3219,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - path类型的值用下面的语法声明: + path类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ... , ( xn , yn ) ] @@ -3258,11 +3229,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays x1 , y1 , ... , xn , yn - 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被忽略时,路径将被假定为封闭。 + 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被省略时,路径将被假定为封闭。 - 路径的输出使用第一种或第二种语法。 + 路径的输出视情况使用第一种或第二种语法。 @@ -3286,7 +3257,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - polygon类型的值用下列语法声明: + polygon类型的值用下列任一种语法指定: ( ( x1 , y1 ) , ... , ( xn , yn ) ) @@ -3311,7 +3282,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 圆由一个圆心和一个半径代表。circle类型的值用下面的语法指定: + 圆由一个圆心和一个半径代表。circle类型的值用下面任一种语法指定: < ( x , y ) , r > @@ -3334,7 +3305,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 网络地址类型 - network + 网络 数据类型 @@ -3391,8 +3362,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 在对 inetcidr 数据类型排序时,IPv4 - 地址总是排在 IPv6 地址之前,包括那些封装在 IPv6 地址中或映射到 - IPv6 地址中的 IPv4 地址,例如 ::10.2.3.4 或 + 地址总是排在 IPv6 地址之前,即使后者是封装或映射 IPv4 地址所得的 IPv6 地址,例如 ::10.2.3.4::ffff:10.4.3.2 @@ -3548,7 +3518,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - <type>inet</type> vs. <type>cidr</type> + <type>inet</type> 与 <type>cidr</type> inetcidr 两种数据类型的本质区别在于: @@ -3574,12 +3544,12 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - MAC地址 + MAC 地址 macaddr - macaddr类型存储 MAC 地址,也就是以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: + macaddr类型存储 MAC 地址,例如以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: '08:00:2b:01:02:03' @@ -3613,11 +3583,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays <type>macaddr8</type> - macaddr8 (data type) + macaddr8(数据类型) - MAC地址(EUI-64格式) + MAC 地址(EUI-64 格式) macaddr @@ -3744,31 +3714,31 @@ SELECT * FROM test; - 一个 bit 串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 + 一个位串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 开销,具体取决于串的长度。(不过,长值可能会被压缩或移到行外存储, 与 中对字符串的说明相同。) - 文本搜索类型 + 文本检索类型 - 全文搜索 + 全文检索 数据类型 - 文本搜索 + 文本检索 数据类型 - PostgreSQL 提供了两种专为支持全文搜索而 - 设计的数据类型。所谓全文搜索,是指在一组自然语言 + PostgreSQL 提供了两种专为支持全文检索而 + 设计的数据类型。所谓全文检索,是指在一组自然语言 文档中查找最匹配某个 查询的文档。tsvector 类型以 - 适合文本搜索的优化形式表示文档,tsquery 类型则表示 + 适合文本检索的优化形式表示文档,tsquery 类型则表示 文本查询。关于这一功能的详细解释见 ; 相关函数和操作符的概览见 @@ -3783,7 +3753,7 @@ SELECT * FROM test; tsvector 值是一个排好序且互不重复的 词位(lexeme)列表,这些词已经过 - 规范化,以便把同一单词的不同变体合并起来 + 正规化,以便把同一单词的不同变体合并起来 (详见 )。排序和去重会在输入时自动 完成,如下例所示: @@ -3842,12 +3812,12 @@ SELECT 'a:1A fat:2B,4C cat:5D'::tsvector; 权重通常用于反映文档结构,例如把标题中的词和正文中的词区分开来。 - 文本搜索排序函数可以为不同的权重标记分配不同优先级。 + 文本检索排序函数可以为不同的权重标记分配不同优先级。 必须认识到,tsvector 类型本身并不会执行任何词语 - 规范化;它假定输入的词已经按照应用需求完成规范化。例如: + 正规化;它假定输入的词已经按照应用需求完成正规化。例如: SELECT 'The Fat Rats'::tsvector; @@ -3856,9 +3826,9 @@ SELECT 'The Fat Rats'::tsvector; 'Fat' 'Rats' 'The' - 对于大多数英文全文搜索应用来说,上述词会被视为尚未规范化,但 + 对于大多数英文全文检索应用来说,上述词会被视为尚未正规化,但 tsvector 并不在意。原始文档文本通常应先经过 - to_tsvector,以按搜索需要对词语进行规范化: + to_tsvector,以按检索需要对词语进行正规化: SELECT to_tsvector('english', 'The Fat Rats'); @@ -3947,9 +3917,9 @@ SELECT 'super:*'::tsquery; 引号的使用规则与前面介绍 tsvector 时相同;同样, - 与 tsvector 一样,任何需要的词语规范化都必须在 + 与 tsvector 一样,任何需要的词语正规化都必须在 转换为 tsquery 类型之前完成。to_tsquery - 函数很适合用来实现这种规范化: + 函数很适合用来实现这种正规化: SELECT to_tsquery('Fat:ab & Cats'); @@ -3975,8 +3945,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); ---------------+------------ 'postgradu':1 | 'postgr':* - 因而它能够匹配其带前缀的后继形式 - postgraduate。 + 因而它能够匹配postgraduate 词干化后的形式。 @@ -3992,9 +3961,9 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); uuid 数据类型用于存储由 - RFC 9562、 + RFC 4122、 ISO/IEC 9834-8:2005 及相关标准定义的通用唯一标识符(UUID)。 - (有些系统把这种数据类型称为全局唯一标识符,或 GUID, + (有些系统把这种数据类型称为全局唯一标识符,或 GUID GUID。)这种标识符是一个 128 位的量,由某种算法生成,该算法被设计为使同一算法在已知宇宙中 被其他人生成出相同标识符的概率极低。因此,对于分布式系统而言, @@ -4002,14 +3971,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); 单个数据库内唯一。 - - RFC 9562 定义了 8 种不同的 UUID 版本。每个版本对生成新 UUID 值 - 都有各自的要求,也各自具备不同的优缺点。 - PostgreSQL 原生支持使用 UUIDv4 和 - UUIDv7 算法生成 UUID。或者,也可以在数据库外部使用任意算法生成 - UUID 值。uuid 数据类型可用于存储任何 UUID, - 无论其来源和版本为何。 - + UUID 写作一串小写十六进制数字,并用连字符分隔成若干组: @@ -4020,7 +3982,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11 PostgreSQL 也接受其他输入形式:可以使用 - 大写字母、用花括号包围标准格式、忽略部分或全部连字符,或者在任意 + 大写字母、用花括号包围标准格式、省略部分或全部连字符,或者在任意 4 位分组后额外加上连字符。例如: A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11 @@ -4102,7 +4064,7 @@ xml 'bar' 反向操作,也就是从 xml 生成字符串值,则使用函数 xmlserializexmlserialize -XMLSERIALIZE ( { DOCUMENT | CONTENT } value AS type [ [ NO ] INDENT ] ) +XMLSERIALIZE ( { DOCUMENT | CONTENT } value AS type ) type 可以是 charactercharacter varying 或 @@ -4111,18 +4073,14 @@ XMLSERIALIZE ( { DOCUMENT | CONTENT } value AS PostgreSQL 也允许你直接进行类型转换。 - - INDENT 选项会让结果以美化格式输出,而 - NO INDENT(默认值)则只输出原始输入字符串。 - 直接转换为字符类型时,也会得到原始字符串。 - + 当字符串值在不经过 XMLPARSEXMLSERIALIZE 的情况下与 xml 类型互相转换时, 选择 DOCUMENT 还是 CONTENT - 由会话配置参数 XML option - XML option 决定,可以使用 + 由会话配置参数 XML 选项 + XML 选项 决定,可以使用 标准命令设置: SET XML OPTION { DOCUMENT | CONTENT }; @@ -4139,20 +4097,20 @@ SET xmloption TO { DOCUMENT | CONTENT }; 编码处理 - 在客户端、服务器以及其间传输的 XML 数据上处理多字符编码时, + 在客户端、服务器以及其间传输的 XML 数据上处理多种字符编码时, 必须格外小心。使用文本模式向服务器发送查询并把查询结果返回给 - 客户端时,PostgreSQL 会将客户端与 + 客户端时(这是通常使用的模式),PostgreSQL 会将客户端与 服务器之间传输的所有字符数据转换为目标端的字符编码,参见 。这也包括表示 XML 值的字符串,如上例 所示。这通常意味着,由于字符数据在客户端和服务器之间传输时可能被 转换为其他编码,XML 数据中包含的编码声明可能会失效,因为内嵌的 编码声明本身并不会被修改。为处理这种情况,表示 xml 类型输入值的字符串中所包含的编码声明会被 - 忽略,其内容被假定为当前服务器编码。随后, + 忽略,其内容被假定为当前服务器编码。因此, 为了正确处理,客户端发出的 XML 数据字符串必须采用当前客户端编码。 客户端负责在将文档发送给服务器之前把它们转换为当前客户端编码, 或适当调整客户端编码。输出时,xml 类型值不会带有 - 编码声明,而客户端会假定所有数据都采用当前客户端编码。 + 编码声明,而客户端应假定所有数据都采用当前客户端编码。 @@ -4186,7 +4144,7 @@ SET xmloption TO { DOCUMENT | CONTENT }; xml 数据类型有些特殊,因为它不提供任何比较操作符。 这是因为对 XML 数据并不存在良定义且通用的比较算法。其结果是, - 你无法通过把某个 xml 值与搜索值比较来检索行。 + 你无法通过把某个 xml 列与搜索值比较来检索行。 因此,XML 值通常应伴随一个独立的键字段,例如 ID。另一种比较 XML 值的办法,是先把它们转换成字符串;但请注意,字符串比较对 XML 的比较需求通常帮助不大。 @@ -4194,14 +4152,14 @@ SET xmloption TO { DOCUMENT | CONTENT }; 由于 xml 数据类型没有可用的比较操作符,因此无法直接 - 在这种类型上创建索引。如果需要在 XML 中快速搜索,可行方案包括: + 在这种类型的列上创建索引。如果需要在 XML 中快速搜索,可行方案包括: 将表达式转换为字符串类型后为其建立索引,或者为某个 XPath 表达式 建立索引。当然,实际查询也必须相应调整为使用该被索引的表达式。 - PostgreSQL 的文本搜索功能也可用于加速 - XML 数据的全文搜索。不过,目前 PostgreSQL 发行版中仍缺少所需的 + PostgreSQL 的文本检索功能也可用于加速 + XML 数据的全文检索。不过,目前 PostgreSQL 发行版中仍缺少所需的 预处理支持。 @@ -4216,12 +4174,12 @@ SET xmloption TO { DOCUMENT | CONTENT }; 域类型 - domain + - data type - domain + 数据类型 + @@ -4233,13 +4191,13 @@ SET xmloption TO { DOCUMENT | CONTENT }; CREATE DOMAIN posint AS integer CHECK (VALUE > 0); CREATE TABLE mytable (id posint); -INSERT INTO mytable VALUES(1); -- works -INSERT INTO mytable VALUES(-1); -- fails +INSERT INTO mytable VALUES(1); -- 成功 +INSERT INTO mytable VALUES(-1); -- 失败 - 当底层类型的一个操作符或函数适用于一个域值时,域会被自动向下转换为底层类型。因此,mytable.id - 1的结果会被认为是类型integer而不是posint。我们可以写成(mytable.id - 1)::posint来把结果转换回posint,这会导致域的约束被重新检查。在这种情况下,如果该表达式被应用于一个值为1的id就会错误。把底层类型的值赋给域类型的一个字段或者变量不需要写显式的类型转换,但是域的约束将会被检查。 + 当底层类型的一个操作符或函数被应用于一个域值时,域会被自动向下转换为底层类型。因此,mytable.id - 1的结果会被认为是类型integer而不是posint。我们可以写成(mytable.id - 1)::posint来把结果转换回posint,这会导致域的约束被重新检查。在这种情况下,如果该表达式被应用于一个值为1的id就会报错。把底层类型的值赋给域类型的一个字段或者变量不需要写显式的类型转换,但是域的约束将会被检查。 @@ -4322,7 +4280,7 @@ INSERT INTO mytable VALUES(-1); -- fails 对象标识符(OID)在 PostgreSQL 内部被用作 若干系统表的主键。类型 oid 表示一个对象标识符。 - 此外还有若干 oid 的别名类型,统称为 + 此外还有若干 oid 的别名类型,其名称均形如 regsomething 给出了概要说明。 @@ -4399,14 +4357,14 @@ SELECT * FROM pg_attribute regconfig pg_ts_config - 文本搜索配置 + 文本检索配置 english regdictionary pg_ts_dict - 文本搜索字典 + 文本检索词典 simple @@ -4442,7 +4400,7 @@ SELECT * FROM pg_attribute regprocedure pg_proc - 函数与参数类型 + 带参数类型的函数 sum(int4) @@ -4478,7 +4436,7 @@ SELECT * FROM pg_attribute - 这些类型的输入函数允许在各个标记之间插入空白,并且会把大写字母 + 这些类型的输入函数允许在各个词元之间插入空白,并且会把大写字母 折叠为小写,双引号内除外;这样做是为了让语法规则更接近 SQL 中 书写对象名的方式。反过来,如果需要让输出成为有效的 SQL 标识符, 输出函数会自动加上双引号。例如,一个名为 Foo @@ -4553,8 +4511,7 @@ WHERE ... 它就会对被引用对象建立依赖。例如,如果某列的默认表达式是 nextval('my_seq'::regclass)PostgreSQL 就会知道该默认表达式依赖于 - 序列 my_seq,因此系统在删除该序列之前,必须先 - 移除该默认表达式。改用 + 序列 my_seq,因此系统不允许在尚未移除该默认表达式时删除序列。改用 nextval('my_seq'::text) 则不会建立依赖。 (regrole 是这一特性的例外:该类型的常量不允许出现在 存储表达式中。) @@ -4754,7 +4711,7 @@ WHERE ... anyarray - 表示一个函数可以接受任意数组数据类型(参见 + 表示一个函数可以接受任意数组数据类型(参见)。 @@ -4873,7 +4830,7 @@ WHERE ... unknown - 标识一种尚未解析出的类型,例如未修饰的字符串字面值。 + 标识一种尚未解析出的类型,例如未修饰的字符串字面值的类型。 @@ -4891,7 +4848,7 @@ WHERE ... voidrecord 用作结果类型 (如果函数被用作触发器或事件触发器,则也允许 triggerevent_trigger 作为结果类型)。 - 有些语言还支持借助多态伪类型来实现多态函数;详见 + 有些语言还支持借助上面列出的多态伪类型来实现多态函数;详见 diff --git a/zh/15/dict-int.sgml b/zh/15/dict-int.sgml index edd9251c..31120457 100644 --- a/zh/15/dict-int.sgml +++ b/zh/15/dict-int.sgml @@ -1,16 +1,16 @@ - dict_int — 用于整数的示例全文搜索词典 + dict_int — 用于整数的示例全文检索词典 dict_int - dict_int是一个全文搜索附加词典模板的示例。 + dict_int是一个全文检索附加词典模板的示例。 引入这个示例词典是为了控制整数(有符号和无符号)的索引, - 使这类数字能够被索引,同时又避免唯一词的数量过度增长, + 使这类数字能够被索引,同时又避免不同词的数量过度增长, 因为那会严重影响搜索性能。 @@ -54,7 +54,7 @@ 用法 - 安装dict_int扩展后,会创建一个文本搜索模板 + 安装dict_int扩展后,会创建一个文本检索模板 intdict_template以及一个基于该模板、使用默认参数的词典 intdict。你可以修改这些参数,例如: @@ -77,7 +77,7 @@ mydb# select ts_lexize('intdict', '12345678'); 但在实际使用中,通常需要像所述那样, - 将它包含到某个文本搜索配置中。可能类似如下: + 将它包含到某个文本检索配置中。可能类似如下: ALTER TEXT SEARCH CONFIGURATION english diff --git a/zh/15/func.sgml b/zh/15/func.sgml index d89c54bd..92b7cc4e 100644 --- a/zh/15/func.sgml +++ b/zh/15/func.sgml @@ -2543,7 +2543,7 @@ repeat('Pg', 4) PgPgPgPg 还有其他字符串操作函数和操作符,列在中。 (其中一些用于内部实现中列出的SQL标准字符串函数。) - 此外,中还描述了模式匹配操作符,中则描述了全文搜索操作符。 + 此外,中还描述了模式匹配操作符,中则描述了全文检索操作符。
@@ -11289,7 +11289,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 文本搜索函数和操作符 + 文本检索函数和操作符 全文检索 @@ -11297,7 +11297,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 文本搜索 + 文本检索 函数和操作符 @@ -11305,12 +11305,12 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple 以及 - 总结了为全文检索提供的函数和操作符。PostgreSQL的文本搜索功能的详细解释可参考。 + 总结了为全文检索提供的函数和操作符。PostgreSQL的文本检索功能的详细解释可参考
- 文本搜索操作符 + 文本检索操作符 @@ -11486,12 +11486,12 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple 除了这些专用操作符之外, 中所示的常用比较操作符也适用于tsvectortsquery类型。 - 这些操作符对文本搜索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。 + 这些操作符对文本检索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。
- 文本搜索函数 + 文本检索函数 @@ -11538,7 +11538,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple regconfig - 返回当前默认文本搜索配置的OID(由 所设定的). + 返回当前默认文本检索配置的 OID(由 设置)。 get_current_ts_config() @@ -12074,18 +12074,18 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 所有接受一个可选的regconfig参数的文本搜索函数在省略该参数时,会使用由指定的配置。 + 所有接受一个可选的regconfig参数的文本检索函数在省略该参数时,会使用由指定的配置。 - 中的函数被单独列出,因为它们通常不被用于日常的文本搜索操作。 - 它们主要有助于开发和调试新的文本搜索配置。 + 中的函数被单独列出,因为它们通常不被用于日常的文本检索操作。 + 它们主要有助于开发和调试新的文本检索配置。
- 文本搜索调试函数 + 文本检索调试函数 @@ -12121,7 +12121,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple lexemestext[] ) - 根据指定的或默认的文本搜索配置从document中提取和正规化词元,并返回关于每个词元是如何处理的信息。 + 根据指定的或默认的文本检索配置从document中提取和正规化词元,并返回关于每个词元是如何处理的信息。 详情参见 diff --git a/zh/15/gist.sgml b/zh/15/gist.sgml index 21a5960f..10538292 100644 --- a/zh/15/gist.sgml +++ b/zh/15/gist.sgml @@ -983,7 +983,7 @@ my_sortsupport(PG_FUNCTION_ARGS) 示例 - PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本搜索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: + PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本检索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: diff --git a/zh/15/json.sgml b/zh/15/json.sgml index d0f9c3fa..4e8f4e34 100644 --- a/zh/15/json.sgml +++ b/zh/15/json.sgml @@ -38,7 +38,7 @@ - 由于 json 类型存储的是输入文本的精确副本,因此它会保留标记 + 由于 json 类型存储的是输入文本的精确副本,因此它会保留词元 之间在语义上无关紧要的空白,以及 JSON 对象内部键的顺序。此外,如果值中 的某个 JSON 对象包含同一个键多次,所有键/值对都会被保留下来(处理函数会 将最后一个值视为生效值)。相比之下,jsonb 不保留空白,不保留 @@ -86,7 +86,7 @@ 当把文本形式的 JSON 输入转换为 jsonb 时, - RFC 7159 描述的基本类型会有效映射到原生的 + RFC 7159 描述的基本类型实际上会映射到原生的 PostgreSQL 类型上,如 所示。因此,什么样的数据构成 有效的 jsonb 会有一些额外但较小的限制,这些限制不适用于 @@ -137,7 +137,7 @@ null - (无) + (无) SQL NULL 是不同的概念 @@ -152,18 +152,18 @@ 以下都是有效的 json(或 jsonb)表达式: --- Simple scalar/primitive value --- Primitive values can be numbers, quoted strings, true, false, or null +-- 简单的标量/基本值 +-- 基本值可以是数字、加引号的字符串、true、false 或 null SELECT '5'::json; --- Array of zero or more elements (elements need not be of same type) +-- 包含零个或多个元素的数组(元素不必是同一类型) SELECT '[1, 2, "foo", null]'::json; --- Object containing pairs of keys and values --- Note that object keys must always be quoted strings +-- 包含键值对的对象 +-- 注意,对象的键必须始终是加引号的字符串 SELECT '{"bar": "baz", "balance": 7.77, "active": false}'::json; --- Arrays and objects can be nested arbitrarily +-- 数组和对象可以任意嵌套 SELECT '{"foo": [true, "bar"], "tags": {"a": 1, "b": null}}'::json; @@ -219,8 +219,7 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 当 JSON 数据存储在表中时,它与任何其他数据类型一样,都要面对相同的并发控 制考量。虽然存储大型文档是可行的,但要记住,任何更新都会在整行上获取一个 行级锁。应考虑将 JSON 文档限制在可管理的大小,以减少更新事务之间的锁争用。 - 理想情况下,每个 JSON 文档都应表示一个原子数据项,按照业务规则,它不应被 - 合理地进一步拆分为更小且可独立修改的数据项。 + 理想情况下,每个 JSON 文档都应表示一个原子数据项,根据业务规则,无法再合理地将它细分为更小且可独立修改的数据项。 @@ -228,11 +227,11 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; <type>jsonb</type> 包含与存在 jsonb - containment + 包含 jsonb - existence + 存在 测试 包含jsonb 的一项重要能力。 @@ -241,33 +240,32 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 示例都返回真: --- Simple scalar/primitive values contain only the identical value: +-- 简单的标量/基本值只包含相同的值: SELECT '"foo"'::jsonb @> '"foo"'::jsonb; --- The array on the right side is contained within the one on the left: +-- 左侧数组包含右侧数组: SELECT '[1, 2, 3]'::jsonb @> '[1, 3]'::jsonb; --- Order of array elements is not significant, so this is also true: +-- 数组元素的顺序无关紧要,因此下面的结果也为真: SELECT '[1, 2, 3]'::jsonb @> '[3, 1]'::jsonb; --- Duplicate array elements don't matter either: +-- 重复的数组元素也无关紧要: SELECT '[1, 2, 3]'::jsonb @> '[1, 2, 2]'::jsonb; --- The object with a single pair on the right side is contained --- within the object on the left side: +-- 左侧对象包含右侧只有一个键值对的对象: SELECT '{"product": "PostgreSQL", "version": 9.4, "jsonb": true}'::jsonb @> '{"version": 9.4}'::jsonb; --- The array on the right side is not considered contained within the --- array on the left, even though a similar array is nested within it: -SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- yields false +-- 左侧数组被认为包含右侧数组, +-- 尽管其中嵌套了一个类似的数组: +SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- 结果为假 --- But with a layer of nesting, it is contained: +-- 但增加一层嵌套后,就构成了包含关系: SELECT '[1, 2, [1, 3]]'::jsonb @> '[[1, 3]]'::jsonb; --- Similarly, containment is not reported here: -SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- yields false +-- 同样,下面也不构成包含关系: +SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- 结果为假 --- A top-level key and an empty object is contained: +-- 包含由顶层键和空对象构成的对象: SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; @@ -282,11 +280,11 @@ SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; 对于结构必须匹配这一一般原则,有一个特殊例外:数组可以包含一个基本值: --- This array contains the primitive string value: +-- 这个数组包含该基本字符串值: SELECT '["foo", "bar"]'::jsonb @> '"bar"'::jsonb; --- This exception is not reciprocal -- non-containment is reported here: -SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false +-- 这个例外并不对称——下面的结果表示不包含: +SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- 结果为假 @@ -296,19 +294,19 @@ SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false 外,下面这些示例都返回真: --- String exists as array element: +-- 字符串作为数组元素存在: SELECT '["foo", "bar", "baz"]'::jsonb ? 'bar'; --- String exists as object key: +-- 字符串作为对象键存在: SELECT '{"foo": "bar"}'::jsonb ? 'foo'; --- Object values are not considered: -SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- yields false +-- 不考虑对象的值: +SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- 结果为假 --- As with containment, existence must match at the top level: -SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- yields false +-- 与包含关系一样,存在性必须在顶层匹配: +SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- 结果为假 --- A string is considered to exist if it matches a primitive JSON string: +-- 如果字符串与一个基本 JSON 字符串匹配,则认为它存在: SELECT '"foo"'::jsonb ? 'foo'; @@ -322,8 +320,7 @@ SELECT '"foo"'::jsonb ? 'foo'; 由于 JSON 包含是嵌套的,因此适当的查询可以跳过对子对象的显式选择。例如, 假设我们有一个 doc 列,其顶层是对象,而且大 多数对象都带有 tags 字段,该字段中包含子对象数组。下面 - 这个查询会找出那些包含同时带有 "term":"paris" 和 - "term":"food" 的子对象的项,同时忽略 + 这个查询会找出同时出现包含 "term":"paris" 的子对象和包含 "term":"food" 的子对象的项,同时忽略 tags 数组之外的任何此类键: SELECT doc->'site_name' FROM websites @@ -353,7 +350,7 @@ SELECT doc->'site_name' FROM websites <type>jsonb</type> 索引 jsonb - indexes on + 索引 @@ -403,14 +400,14 @@ CREATE INDEX idxginp ON api USING GIN (jdoc jsonb_path_ops); 名为 jdocjsonb 列里。 如果在该列上创建了 GIN 索引,那么下面这样的查询就可以利用这个索引: --- Find documents in which the key "company" has value "Magnafone" +-- 查找键 "company" 的值为 "Magnafone" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"company": "Magnafone"}'; 但是,类似下面这样的查询就无法使用该索引,因为虽然操作符 ? 可索引,但它并未直接应用到被索引的列 jdoc 上: --- Find documents in which the key "tags" contains key or array element "qui" +-- 查找键 "tags" 包含键或数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc -> 'tags' ? 'qui'; 不过,只要适当地使用表达式索引,上述查询也可以利用索引。如果经常查询 @@ -428,7 +425,7 @@ CREATE INDEX idxgintags ON api USING GIN ((jdoc -> 'tags')); 另一种查询方法是利用包含,例如: --- Find documents in which the key "tags" contains array element "qui" +-- 查找键 "tags" 包含数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qui"]}'; jdoc 列上的简单 GIN 索引可以支持这个查询。 @@ -449,8 +446,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; 对于这些操作符,GIN 索引会从 jsonpath 模式中提取出形如 - accessors_chain - == constant 的子句,并根据其中提到 + accessors_chain = constant 的子句,并根据其中提到 的键和值进行索引搜索。访问器链可以包含 .key[*] 和 @@ -466,7 +462,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; @@ 操作符的查询,但相较于默认操作符类 jsonb_ops,它具有显著的性能优势。 jsonb_path_ops 索引通常比相同数据上的 - jsonb_ops 索引小得多,而且搜索条件也更具特异性,尤其是在 + jsonb_ops 索引小得多,而且搜索也更有针对性,尤其是在 查询中包含数据里频繁出现的键时。因此,搜索操作通常比使用默认操作符类时 性能更佳。 @@ -482,9 +478,9 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; 基本上,每个 jsonb_path_ops 索引项都是该值连同 - 通向该值的键一起计算出的哈希。例如,要索引 + 通向该值的键一起计算出的 hash。例如,要索引 {"foo": {"bar": "baz"}},会创建一个单独的索引项, - 其哈希值中同时纳入 foobar 和 + 其 hash 值中同时纳入 foobarbaz 这三者。因此,查找这一结构的包含查询会得到一次 非常精确的索引搜索;但完全没有办法据此找出 foo 是否 作为键出现。另一方面,jsonb_ops 索引会分别创建三个 @@ -506,7 +502,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; jsonb 还支持 btreehash 索引。通常只有在需要检查完整 JSON 文档是否相等时, 它们才有用。btreejsonb 数据项的 - 排序通常没什么太大意义,但为了完整起见,其规则如下: + 排序顺序通常很少受到关注,但为了完整起见,其规则如下: 对象 > 数组 > 布尔值 > 数字 > 字符串 > null @@ -561,27 +557,24 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; --- Extract object value by key +-- 按键提取对象的值 SELECT ('{"a": 1}'::jsonb)['a']; --- Extract nested object value by key path +-- 按键路径提取嵌套对象的值 SELECT ('{"a": {"b": {"c": 1}}}'::jsonb)['a']['b']['c']; --- Extract array element by index +-- 按下标提取数组元素 SELECT ('[1, "2", null]'::jsonb)[1]; --- Update object value by key. Note the quotes around '1': the assigned --- value must be of the jsonb type as well +-- 按键更新对象的值。注意 '1' 两边的引号:赋予的值也必须是 jsonb 类型 UPDATE table_name SET jsonb_field['key'] = '1'; --- This will raise an error if any record's jsonb_field['a']['b'] is something --- other than an object. For example, the value {"a": 1} has a numeric value --- of the key 'a'. +-- 如果任何记录的 jsonb_field['a']['b'] 不是对象,就会报错。 +-- 例如,值 {"a": 1} 的键 'a' 对应的值是数字。 UPDATE table_name SET jsonb_field['a']['b']['c'] = '1'; --- Filter records using a WHERE clause with subscripting. Since the result of --- subscripting is jsonb, the value we compare it against must also be jsonb. --- The double quotes make "value" also a valid jsonb string. +-- 使用带下标的 WHERE 子句筛选记录。由于下标操作的结果是 jsonb, +-- 与之比较的值也必须是 jsonb。双引号使 "value" 也成为合法的 jsonb 字符串。 SELECT * FROM table_name WHERE jsonb_field['key'] = '"value"'; @@ -591,19 +584,19 @@ SELECT * FROM table_name WHERE jsonb_field['key'] = '"value"'; (对象或数组)的空 JSON 值来处理: --- Where jsonb_field was NULL, it is now {"a": 1} +-- 原先为 NULL 的 jsonb_field 现在为 {"a": 1} UPDATE table_name SET jsonb_field['a'] = '1'; --- Where jsonb_field was NULL, it is now [1] +-- 原先为 NULL 的 jsonb_field 现在为 [1] UPDATE table_name SET jsonb_field[0] = '1'; - 如果对一个元素数量不足的数组指定了某个索引,就会不断追加 - NULL 元素,直到该索引可达并且可以设置该值为止。 + 如果对一个元素数量不足的数组指定了某个下标,就会不断追加 + NULL 元素,直到该下标可达并且可以设置该值为止。 --- Where jsonb_field was [], it is now [null, null, 2]; --- where jsonb_field was [0], it is now [0, null, 2] +-- 原先为 [] 的 jsonb_field 现在为 [null, null, 2]; +-- 原先为 [0] 的 jsonb_field 现在为 [0, null, 2] UPDATE table_name SET jsonb_field[2] = '2'; @@ -614,10 +607,10 @@ UPDATE table_name SET jsonb_field[2] = '2'; null 填充,直到能够放入被赋值的值为止。 --- Where jsonb_field was {}, it is now {"a": [{"b": 1}]} +-- 原先为 {} 的 jsonb_field 现在为 {"a": [{"b": 1}]} UPDATE table_name SET jsonb_field['a'][0]['b'] = '1'; --- Where jsonb_field was [], it is now [null, {"a": 1}] +-- 原先为 [] 的 jsonb_field 现在为 [null, {"a": 1}] UPDATE table_name SET jsonb_field[1]['a'] = '1'; @@ -634,7 +627,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; PL/Perl 的扩展名为 jsonb_plperljsonb_plperlu。如果使用它们, - jsonb 值会按适当方式映射为 Perl 数组、哈希和标量。 + jsonb 值会按适当方式映射为 Perl 数组、hash 和标量。 @@ -712,7 +705,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; - 路径表达式由一系列路径元素构成,可以是下列任意一种: + 路径表达式由一系列路径元素构成,这些元素可以是下列任意一种: @@ -851,7 +844,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; 类似 .**,但只选择 JSON 层次结构中指定的层级。 - 嵌套层级以整数指定。层级零对应当前对象。若要访问最低的嵌套层级, + 嵌套层级以整数指定。层级零对应当前对象。若要访问最深的嵌套层级, 可以使用 last 关键字。这是 PostgreSQL 对 SQL/JSON 标准的扩展。 @@ -869,13 +862,13 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; 可以用两种形式给出: indexstart_index to end_index。 - 第一种形式按索引返回单个数组元素。第二种形式按索引范围返回数组切片, + 第一种形式按下标返回单个数组元素。第二种形式按下标范围返回数组切片, 其中包括与给定 start_indexend_index 对应的元素。 指定的 index 可以是整数,也可以是返回单个 - 数值的表达式,该表达式会自动转换为整数。索引零对应第一个数组元素。 + 数值的表达式,该数值会自动转换为整数。下标零对应第一个数组元素。 你也可以使用 last 关键字来表示最后一个数组元素, 这对于处理长度未知的数组很有用。 diff --git a/zh/15/libpq.sgml b/zh/15/libpq.sgml index 345c915f..c03ad68f 100644 --- a/zh/15/libpq.sgml +++ b/zh/15/libpq.sgml @@ -2,7 +2,7 @@ - <application>libpq</application> - C 库 + <application>libpq</application> — C 库 libpq @@ -13,33 +13,27 @@ - libpq是应用程序员使用PostgreSQLC接口。libpq是一个库函数的集合,它们允许客户端程序传递查询给PostgreSQL后端服务器并且接收这些查询的结果。 + libpqPostgreSQLC应用程序编程接口。libpq是一组库函数,客户端程序可用它们向PostgreSQL后端服务器发送查询并接收查询结果。 - libpq也是很多其他PostgreSQL应用接口的底层引擎,包括为 C++、Perl、Python、Tcl 和 ECPG编写的接口。如果你使用那些包,某些方面的libpq行为将会对你很重要。特别是,描述了任何使用libpq的应用的用户可见的行为。 + libpq也是其他几个PostgreSQL应用程序接口的底层引擎,包括为 C++、Perl、Python、Tcl 和ECPG编写的接口。因此,对于这些包的用户,libpq行为的某些方面也很重要。特别是,描述了任何使用libpq的应用程序的用户都能观察到的行为。 - 在本章的末尾()包括了一些短程序来展示如何编写使用libpq的应用。在源代码发布的src/test/examples目录中还有一些完整的libpq应用的示例。 + 本章末尾()包含一些简短程序,展示如何编写使用libpq的程序。源代码发行包的src/test/examples目录中还提供了几个完整的libpq应用程序示例。 - 使用libpq的客户端程序必须包括头文件libpq-fe.hlibpq-fe.h并必须与libpq库链接在一起。 + 使用libpq的客户端程序必须包含头文件libpq-fe.hlibpq-fe.h,并且必须与libpq库链接。 数据库连接控制函数 - - 下列函数会建立到一个PostgreSQL后端服务器的连接。 - 一个应用程序可以在一个时刻打开多个后端连接(原因之一就是为了访问多个数据库)。 - 每个连接用一个PGconnPGconn对象表示,它从函数,或得到。 - 注意这些函数将总是返回一个非空的对象指针,除非正好没有内存来分配PGconn对象。 - 在通过该连接对象发送查询之前,应该调用函数来检查返回值以确定是否得到了一个成功的连接。 - - + 以下函数用于建立到PostgreSQL后端服务器的连接。应用程序可以同时保持多个后端连接。(这样做的原因之一是访问多个数据库。)每个连接由一个PGconnPGconn对象表示,该对象可以通过以下函数获取:, + 。注意,这些函数总是返回非空的对象指针,除非内存不足,甚至无法分配PGconn对象。应调用函数检查返回值,确认连接成功后,再通过连接对象发送查询。 如果不受信任的用户能够访问一个没有采用模式的安全使用方式的数据库,那么每个会话开始时都应从search_path中移除公开可写的模式。可以把参数关键词options设置为-csearch_path=。也可以在连接后发出PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)")。这种考虑并非专门针对libpq;它适用于每一种可执行任意 SQL 命令的接口。 @@ -47,7 +41,7 @@ - 在 Unix 上,复制一个拥有打开 libpq 连接的进程可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行代码是安全的。 + 在 Unix 上,对持有已打开 libpq 连接的进程执行 fork 操作可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行程序是安全的。 @@ -74,32 +68,32 @@ PGconn *PQconnectdbParams(const char * const *keywords, - 被传递的数组可以为空,这样就会使用所有默认参数。 - 也可以只包含一个或几个参数设置。他们在长度上必须匹配。 - 对于参数数组的处理将会停止于keywords数组中第一个NULL元素。 - 而且,如果与非-NULL keywords条目相关联的values条目为NULL或者空字符串,则忽略该项并继续处理下一对数组项。 + 传入的数组可以为空,以使用所有默认参数,也可以包含一个或多个参数设置。 + 两个数组的长度必须相同。处理会在 keywords 数组的第一个 NULL 元素处停止。 + 如果某个非 NULLkeywords 元素所对应的 + values 元素为 NULL 或空字符串,则忽略这一项,继续处理下一对数组元素。 - 当expand_dbname为非零时,会检查第一个dbname关键词的值以查看它是否为一个连接字符串。 - 如果是,它被扩展到从字符串中提取的单独的连接参数。 - 该值被认为是一个连接字符串,而不仅是一个数据库名称,如果它包含一个等号(=)或者它以URI模式标志符开头, - (有关连接字符串格式的更多详情可见。) - 只有dbname的第一次出现会按这种方式处理,任何后续dbname值会被当做一个普通数据库名处理。 + 当 expand_dbname 非零时,会检查第一个 dbname 关键词的值是否为 + 连接字符串。如果是,就将其展开为从该字符串中提取的各个连接参数。 + 如果该值包含等号(=),或以 URI 方案标识符开头,就会将其视为连接字符串,而非单纯的数据库名。 + (连接字符串格式的详细说明见。) + 只有第一次出现的 dbname 会按这种方式处理;后续的 dbname 参数都作为普通数据库名处理。 - 通常,参数数组从开头到结尾进行处理。 - 当关键词有重复时,使用最后一个值(不是 NULL 或空)。 - 此规则特别适用于连接字符串中的关键字与一个出现在keywords数组中的关键字冲突的情况。 - 因此,程序员可以决定数组条目是否能被覆盖或用连接字符串获取的值覆盖。 - 出现在扩展的dbname条目之前的数组条目可以被连接字符串的字段所覆盖,反之,这些字段被dbname之后出现的数组条目所覆盖。(但是,再有,只有在那些条目支持非空值时。) + 通常会从头到尾处理参数数组。如果某个关键词重复出现,则采用最后一个非 NULL 且非空的值。 + 此规则也适用于连接字符串中的关键词与 keywords 数组中的关键词冲突的情况。 + 因此,程序员可以决定数组元素是覆盖连接字符串中的值,还是被这些值覆盖。 + 出现在要展开的 dbname 元素之前的数组元素,可以被连接字符串中的字段覆盖; + 而这些字段又会被出现在 dbname 之后的数组元素覆盖(同样,只有这些元素提供非空值时才会覆盖)。 - 在处理完所有数组条目和任何扩展的连接字符串后,所有未设置的连接参数都将使用默认值填充。 - 如果一个未设置参数的相关环境变量(参见 )被设置了,它的值会被使用。 - 如果环境变量未被设置,则使用参数的内置默认值。 + 处理完所有数组元素及展开的连接字符串后,仍未设置的连接参数将填入默认值。 + 如果某个未设置参数对应的环境变量(见)已经设置,就使用该环境变量的值; + 否则使用该参数的内置默认值。 @@ -121,7 +115,7 @@ PGconn *PQconnectdb(const char *conninfo); - 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空格分隔的一个或多个参数设置,还可以包含一个URI。详见。 + 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空白分隔的一个或多个参数设置,还可以包含一个URI。详见 @@ -144,11 +138,11 @@ PGconn *PQsetdbLogin(const char *pghost, - 这是的带有固定参数集合的前辈。它具有相同的功能,不过其中缺失的参数将总是采用默认值。对任意一个固定参数写NULL或一个空字符串将会使它采用默认值。 + 这是 的前身,使用固定的一组参数。除缺失参数始终采用默认值之外,功能相同。对于要使用默认值的任意固定参数,请传入 NULL 或空字符串。 - 如果dbName包含一个=符号或者具有一个合法的连接URI前缀,它会被当作一个conninfo字符串,就好像它已经被传递给了,并且剩余的参数则被应用为指定给。 + 如果 dbName 包含 = 符号,或具有有效的连接 URI 前缀,就会将其当作 conninfo 字符串处理,方式与将其传给 完全相同,然后按照 的规则应用其余参数。 @@ -209,18 +203,14 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); 在PQconnectStart中,数据库连接使用从字符串conninfo中取得的参数创建,这和之前描述的相同。 - - 只要满足一些限制,PQconnectStartPQconnectPoll都不会阻塞: - + 无论是还是PQconnectStart还是PQconnectPoll都不会阻塞,只要满足以下限制: - - 必须正确使用 hostaddr 参数,以避免执行 DNS 查询。详细信息请参见中该参数的说明。 - + 必须正确使用 hostaddr 参数,以避免执行 DNS 查询。详细信息请参见中该参数的说明。 - 如果你调用,确保你追踪的该流对象不会阻塞。 + 如果你调用,确保接收追踪输出的流对象不会阻塞。 @@ -233,17 +223,14 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 要开始无阻塞的连接请求,可调用PQconnectStart或者。如果结果为空,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 + 要开始非阻塞连接请求,可调用PQconnectStart或者。如果结果为空指针,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 如果PQconnectStart成功,下一个阶段是轮询libpq,这样它能够继续进行连接序列。使用PQsocket(conn)来获得该数据库连接底层的套接字描述符(警告:不要假定在PQconnectPoll调用之间套接字会保持相同)。这样循环:如果PQconnectPoll(conn)上一次返回PGRES_POLLING_READING,等到该套接字准备好读取(按照select()poll()或类似的系统函数所指示的)。则再次调用PQconnectPoll(conn)。反之,如果PQconnectPoll(conn)上一次返回PGRES_POLLING_WRITING,等到该套接字准备好写入,则再次调用PQconnectPoll(conn)。在第一次迭代时,即如果你还没有调用PQconnectPoll,行为就像是它上次返回了PGRES_POLLING_WRITING。持续这个循环直到PQconnectPoll(conn)返回PGRES_POLLING_FAILED指示连接过程已经失败,或者返回PGRES_POLLING_OK指示连接已经被成功地建立。 - - 在连接期间的任意时刻,该连接的状态可以通过调用来检查。如果这个调用返回CONNECTION_BAD,那么连接过程已经失败。如果该调用返回CONNECTION_OK,则该连接已经准备好。如前所述,这些状态同样都可以从PQconnectPoll的返回值检测。在一个异步连接过程中(也只有在这个过程中)也可能出现其他状态。这些状态指示该连接过程的当前阶段,并且可能有助于为用户提供反馈。这些状态是: - - + 在连接过程中的任何时刻,都可以调用来检查连接状态。如果调用返回CONNECTION_BAD,则连接过程失败;如果调用返回CONNECTION_OK,则连接已就绪。这两种状态也同样可以通过以下函数的返回值检测:PQconnectPoll,详见上文。在异步连接过程中还可能出现其他状态,而且它们仅在此过程中出现。这些状态表示连接过程的当前阶段,例如可用于向用户提供反馈。这些状态包括: CONNECTION_STARTED @@ -315,10 +302,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - - - 注意,尽管这些常数将被保留(为了维护兼容性),一个应用永远不应该依赖这些状态按照特定顺序出现,或者根本就不依赖它们,或者不依赖状态总是这些文档中所说的值。一个应用可能做些这样的事情: - + 注意,虽然为保持兼容性会保留这些常量,但应用程序不应依赖它们按特定顺序出现、不应假定它们一定出现,也不应假定状态值一定是这里列出的某个值。应用程序可以采用如下方式: switch(PQstatus(conn)) { case CONNECTION_STARTED: @@ -338,11 +322,11 @@ switch(PQstatus(conn)) - 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。否则,PQconnectStart后面跟着PQconnectPoll循环等效于。 + 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。除此之外,PQconnectStart后面跟着PQconnectPoll循环等效于 - 注意当PQconnectStart返回一个非空的指针时,你必须在用完它之后调用来处理那些结构体和任何相关的内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 + 注意当PQconnectStart返回一个非空的指针时,你必须在用完它之后调用来释放该结构体及其关联的所有内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 @@ -358,21 +342,21 @@ PQconninfoOption *PQconndefaults(void); typedef struct { char *keyword; /* 该选项的关键词 */ - char *envvar; /* 依赖的环境变量名 */ - char *compiled; /* 依赖的内置默认值 */ + char *envvar; /* 后备环境变量名 */ + char *compiled; /* 编译时设置的后备默认值 */ char *val; /* 选项的当前值,或者 NULL */ - char *label; /* 连接对话框中域的标签 */ - char *dispchar; /* 指示如何在一个连接对话框中显示这个域。值是: + char *label; /* 连接对话框中字段的标签 */ + char *dispchar; /* 指示如何在连接对话框中显示此字段。可取值: "" 显示输入的值 - "*" 密码域 - 隐藏值 + "*" 密码字段 - 隐藏值 "D" 调试选项 - 默认不显示 */ - int dispsize; /* 用于对话框的以字符计的域尺寸 */ + int dispsize; /* 对话框中的字段宽度,以字符计 */ } PQconninfoOption; - 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前缺省值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回该空指针。注意当前缺省值(val域)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 + 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前默认值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回空指针。注意当前默认值(val字段)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 @@ -393,9 +377,7 @@ PQconninfoOption *PQconninfo(PGconn *conn); - 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前缺省值。 - 返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。 - 上述所有对于的注解也适用于的结果。 + 返回一个连接选项数组。可以用它确定所有可能的 选项,以及实际用于连接服务器的值。返回值指向一个 PQconninfoOption 结构体数组,该数组以 keyword 指针为空的条目结束。上文针对 的所有注意事项,也适用于 的结果。 @@ -421,7 +403,9 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); - 如果errmsg不是NULL,那么成功时*errmsg会被设置为NULL, 否则设置为被malloc过的错误字符串以说明该问题(也可以将*errmsg设置为NULL并且函数返回NULL,这表示一种内存耗尽的情况)。 + 如果 errmsg 不是 NULL,则成功时将 *errmsg 设为 NULL; + 失败时将其设为由 malloc 分配的、用于说明问题的错误字符串。 + (也可能出现 *errmsg 被设为 NULL,同时函数返回 NULL 的情况;这表示内存不足。) @@ -451,7 +435,7 @@ void PQfinish(PGconn *conn); PQresetPQreset - 重置与服务器的通讯通道。 + 重置与服务器的通信通道。 void PQreset(PGconn *conn); @@ -469,7 +453,7 @@ void PQreset(PGconn *conn); PQresetPollPQresetPoll - 以非阻塞方式重置与服务器的通讯通道。 + 以非阻塞方式重置与服务器的通信通道。 int PQresetStart(PGconn *conn); @@ -486,7 +470,7 @@ PostgresPollingStatusType PQresetPoll(PGconn *conn); - 要发起一次连接重置,调用。如果它返回 0,那么重置失败。如果返回 1,就按使用PQresetPoll建立连接时相同的方法,继续调用PQresetPoll来重置连接。 + 要开始重置连接,请调用 。如果返回 0,表示重置失败。如果返回 1,则使用 PQresetPoll 轮询重置过程,方式与使用 PQconnectPoll 建立连接完全相同。 @@ -581,7 +565,7 @@ void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook); int callback_fn(char *buf, int size, PGconn *conn); - 随后,libpq会调用该回调,而不是调用其默认的PQdefaultSSLKeyPassHook_OpenSSL处理程序。 + 随后,libpq会调用该回调,而不是调用其默认的PQdefaultSSLKeyPassHook_OpenSSL处理程序。 回调函数应确定密钥密码,并将其复制到大小为size的结果缓冲区buf中。 buf中的字符串必须以空字符结尾。 回调函数必须返回存储在buf中的密码长度,不包括结尾的空字符。 @@ -600,7 +584,7 @@ int callback_fn(char *buf, int size, PGconn *conn); - 除了异常、longjmp(...)等情况外,回调务必不可跳出正常控制流。它必须正常返回。 + 回调不得通过异常、longjmp(...)等方式跳出正常控制流。它必须正常返回。 @@ -637,9 +621,9 @@ PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void); 几个libpq函数解析用户指定的字符串以获取连接参数。 - 这些字符串有两种被接受的格式:普通的关键字/值字符串和URI。URI通常遵循 + 这些字符串有两种被接受的格式:普通的关键词/值字符串和URI。URI通常遵循 RFC - 3986,除了允许多主机连接字符串,如下面进一步描述的那样。 + 3986,但也允许使用多主机连接字符串,详见下文。 @@ -647,10 +631,10 @@ PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void); 关键词/值连接字符串 - 在关键词/值格式中,每一个参数设置的形式都是关键词 = ,在设置之间有空白。 - 设置的等号周围的空白是可选的。 - 要写一个空值或一个包含空白的值,将它用单引号包围,例如关键词 = 'a value'。 - 值里面的单引号和反斜线必须用一个反斜线转义,即\'\\。 + 在关键词/值格式中,每一个参数设置的形式都是关键词 = ,设置之间以空格分隔。 + 设置的等号周围的空格是可选的。 + 要写一个空值或一个包含空格的值,将它用单引号包围,例如keyword = 'a value'。 + 值里面的单引号和反斜杠必须用一个反斜杠转义,即\'\\ @@ -674,22 +658,22 @@ host=localhost port=5432 dbname=mydb connect_timeout=10 postgresql://userspec@hostspec/dbname?paramspec -where userspec is: +其中 userspec 为: user:password -and hostspec is: +hostspec 为: host:port,... -and paramspec is: +paramspec 为: name=value&... - URI模式标志符可以是postgresql://postgres://。 + URI方案标识符可以是postgresql://postgres://。 每一个剩下的URI部分都是可选的。 下列示例展示了合法的URI语法: @@ -706,19 +690,15 @@ postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application postgresql:///mydb?host=localhost&port=5433 - 全部的命名参数必须匹配中列出的关键词,除了与JDBC连接URI兼容之外,ssl=true的实例转换到sslmode=require。 + 所有命名参数都必须与中列出的关键词匹配;唯一的例外是,为兼容 JDBC 连接 URI,会将 ssl=true 转换为 sslmode=require - 连接URI需要使用百分号编码 - 对其进行编码,如果其中包含具有特殊含义的符号。这里是一个示例,其中等号(=)被替换为 - %3D,空格字符被替换为 - %20: + 如果连接 URI 的任意部分包含具有特殊含义的符号,就需要使用百分号编码。下面的示例将等号(=)替换为 %3D,将空格字符替换为 %20 postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff - + 主机部分可能是主机名或一个 IP 地址。要指定一个 IPv6 地址,将它封闭在方括号中: @@ -731,7 +711,7 @@ postgresql://[2001:db8::1234]/database 主机组件会被按照参数对应的描述来解释。 特别地,如果主机部分是空或看起来像一个绝对路径名称,将使用一个 Unix 域套接字连接,否则将启动一个 TCP/IP 连接。 不过要注意,斜线是 URI 层次部分中的一个保留字符。 - 因此,要指定一个非标准的 Unix 域套接字目录,要么忽略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: + 因此,要指定一个非标准的 Unix 域套接字目录,要么省略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: postgresql:///dbname?host=/var/lib/postgresql postgresql://%2Fvar%2Flib%2Fpostgresql/dbname @@ -741,7 +721,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以在一个URI中指定多个主机,每一个都有一个可选的端口。 一个形式为postgresql://host1:port1,host2:port2,host3:port3/的URI等效于host=host1,host2,host3 port=port1,port2,port3形式的连接字符串。 - 如下所述,每一个主机都将被尝试,直到成功地建立一个连接。 + 如下所述,每一个主机都将被依次尝试,直到成功地建立一个连接。 @@ -751,7 +731,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以指定多个要连接的主机,这样它们会按给定的顺序被尝试。 - 在键/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 + 在关键词/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 在指定的每一个选项中都必须给出相同数量的元素,这样第一个hostaddr对应于第一个主机名,第二个hostaddr对应于第二个主机名,以此类推。 不过,如果仅指定一个port,它将被应用于所有的主机。 @@ -761,11 +741,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 不管是哪一种格式,单一的主机名可以被翻译成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 + 不管是哪一种格式,单一的主机名可以被解析成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 - 当多个主机被指定时或者单个主机名被翻译成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。 + 当多个主机被指定时或者单个主机名被解析成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。 @@ -787,14 +767,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 要连接的主机名。主机名如果主机名看起来像绝对路径名, - 则指定的是Unix域通信而不是TCP/IP通信;该值是存储套接字文件的目录的名称。 - (在Unix上,绝对路径名以斜杠开头。在Windows上,以驱动器号开头的路径也被识别。) - 如果主机名以@开头,则将其视为抽象命名空间中的Unix域套接字(目前在Linux和Windows上支持)。 - 当未指定host或为空时,默认行为是连接到Unix域套接字Unix域套接字在 - /tmp(或在构建PostgreSQL时指定的套接字目录)中。在Windows和 - 没有Unix域套接字的机器上,默认是连接到localhost。 - + 要连接的主机名。主机名如果主机名看起来像绝对路径名, + 则指定的是 Unix 域通信,而非 TCP/IP 通信;此值是存放套接字文件的目录名。 + (在 Unix 上,绝对路径名以斜杠开头。在 Windows 上,也会识别以驱动器号开头的路径。)如果主机名以 @ 开头,则将其视为抽象命名空间中的 Unix 域套接字(目前在 Linux 和 Windows 上支持)。 + 当未指定 host 或其值为空时,默认连接到 /tmp + (或构建 PostgreSQL 时指定的套接字目录)中的 Unix 域套接字。 + Unix 域套接字在 Windows 和没有 Unix 域套接字的机器上,默认连接到 localhost。 + 也可以接受一个逗号分隔的主机名列表,此时列表中的每个主机名将按顺序尝试; @@ -806,23 +785,18 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname hostaddr - 要连接的主机的数字IP地址。这应该是标准的IPv4地址格式,例如,172.28.40.9。 如果您的机器支持IPv6,也可以使用这些地址。当为此参数指定非空字符串时,总是使用TCP/IP通信。 如果未指定此参数,则将查找host的值以查找相应的IP地址 — 或者,如果host指定了IP地址,则将直接使用该值。 - - 使用hostaddr允许应用程序避免主机名查找,这在有时间限制的应用程序中可能很重要。 - 但是,对于GSSAPI或SSPI认证方法以及verify-full SSL证书验证,需要主机名。 - 使用以下规则: - + 使用hostaddr可以避免主机名查找,这对于有时间限制的应用程序可能很重要。但是,采用 GSSAPI 或 SSPI 认证方式,以及进行verify-fullSSL 证书验证时,都需要主机名。遵循以下规则: 如果指定了host而没有指定hostaddr,则会发生主机名查找。 (当使用PQconnectPoll时,查找发生在PQconnectPoll首次考虑此主机名时, - 并且可能导致PQconnectPoll阻塞一段时间。) + 并且可能导致PQconnectPoll阻塞相当长的时间。) @@ -834,17 +808,10 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果同时指定了hosthostaddr, - 则hostaddr的值给出服务器的网络地址。 - 除非认证方法需要,否则host的值将被忽略, - 在这种情况下,它将用作主机名。 - + 如果同时指定了 hosthostaddr,则 hostaddr 的值给出服务器的网络地址。只有认证方法需要主机名时,才会将 host 的值用作主机名;否则忽略该值。 + - - 请注意,如果host不是网络地址hostaddr上服务器的名称, - 则认证可能会失败。 - 此外,当同时指定hosthostaddr时, - host用于在密码文件中标识连接(请参阅)。 + 注意,以下情况很可能导致认证失败:host不是位于网络地址hostaddr的服务器名称。另外,同时指定hosthostaddr时,将使用host来标识密码文件中的连接(参见)。 @@ -852,7 +819,6 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 列表中的空项会导致使用相应的主机名,如果主机名也为空,则使用默认主机名。详见 - 没有主机名或主机地址, libpq将使用本地的Unix域套接字进行连接; @@ -891,8 +857,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - PostgreSQL用户连接的用户名。 - 默认为运行应用程序的操作系统用户名相同。 + 建立连接所用的 PostgreSQL 用户名。默认与运行应用程序的操作系统用户名相同。 @@ -902,7 +867,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果服务器要求密码认证,则使用密码。 + 服务器要求密码认证时所使用的密码。 @@ -929,7 +894,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 这个选项控制客户端对通道绑定的使用。设置为require表示连接必须使用通道绑定, prefer表示客户端将在可用时选择通道绑定, 而disable则阻止使用通道绑定。默认情况下, - 如果PostgreSQL是使用SSL支持编译的,则默认为prefer; + 如果PostgreSQL是使用SSL支持编译的,则默认为prefer; 否则默认为disable @@ -993,9 +958,9 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 指定配置参数的回退值。 + 指定配置参数的后备值。 如果没有通过连接参数或PGAPPNAME环境变量为application_name指定值, - 则将使用此值。在通用实用程序中指定回退名称很有用,该程序希望设置默认应用程序名称, + 则将使用此值。在通用实用程序中指定后备名称很有用,该程序希望设置默认应用程序名称, 但允许用户覆盖它。 @@ -1006,9 +971,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制是否使用客户端TCP保持活动。默认值为1,表示开启,但如果不想要保持活动,可以将其更改为0,表示关闭。 - 对于通过Unix域套接字进行的连接,此参数将被忽略。 - + 控制是否使用客户端 TCP keepalive。默认值为 1,表示开启;如果不需要 keepalive,可以将其设为 0,表示关闭。对于通过 Unix 域套接字建立的连接,此参数会被忽略。 + @@ -1017,11 +981,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在多少秒的不活动后,TCP应向服务器发送保持活动消息。值为零使用系统默认值。 - 对通过Unix域套接字进行的连接或禁用保持活动的连接,此参数将被忽略。 - 仅在支持TCP_KEEPIDLE或等效套接字选项的系统以及Windows上支持; - 在其他系统上,它没有任何效果。 - + 控制在多久没有活动后,TCP 应向服务器发送 keepalive 消息,以秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPIDLE 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -1030,11 +991,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在服务器未确认的情况下重新传输TCP保持活动消息的秒数。值为零时使用系统默认值。 - 此参数在通过Unix域套接字进行连接或禁用保持活动时将被忽略。 - 仅在支持TCP_KEEPINTVL或等效套接字选项的系统和Windows上支持; - 在其他系统上,此参数无效。 - + 控制未被服务器确认收到的 TCP keepalive 消息在多少秒后应被重传。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPINTVL 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -1043,11 +1001,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在客户端与服务器之间连接被视为断开之前可以丢失的TCP keepalive数量。 - 值为零时使用系统默认值。对通过Unix域套接字建立的连接或禁用keepalives的连接,此参数将被忽略。 - 仅在支持TCP_KEEPCNT或等效套接字选项的系统上受支持; - 在其他系统上,此参数无效。 - + 控制在客户端与服务器之间的连接被视为中断之前,可以丢失多少个 TCP keepalive 消息。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPCNT 或等效套接字选项的系统上受支持;在其他系统上无效。 + @@ -1056,10 +1011,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在连接在强制关闭之前,传输数据可以保持未被确认的毫秒数。 - 值为零时使用系统默认值。此参数对通过Unix域套接字进行的连接无效。 - 仅在支持TCP_USER_TIMEOUT的系统上受支持;在其他系统上,它没有效果。 - + 控制已发送的数据在连接被强制关闭之前最多可以保持未确认状态多长时间,以毫秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,此参数会被忽略。此参数仅在支持 TCP_USER_TIMEOUT 的系统上受支持;在其他系统上无效。 + @@ -1122,25 +1075,25 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个选项确定是否以及如何优先与服务器协商安全的GSS TCP/IP连接。有三种模式: + 这个选项确定是否以及以何种优先级与服务器协商安全的GSS TCP/IP连接。有三种模式: disable - 仅尝试非GSSAPI加密连接 + 仅尝试未经GSSAPI加密的连接 - prefer (默认) + prefer (默认) 如果存在GSSAPI凭据(即在凭据缓存中),首先尝试 GSSAPI加密连接;如果失败或没有凭据,则尝试 - 非GSSAPI加密连接。这是在编译PostgreSQL时使用GSSAPI支持时的默认设置。 + 未经GSSAPI加密的连接。这是在编译PostgreSQL时使用GSSAPI支持时的默认设置。 @@ -1159,7 +1112,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname gssencmode在Unix域套接字通信中被忽略。如果PostgreSQL没有编译GSSAPI支持, 使用require选项将导致错误,而prefer将被接受,但libpq实际上不会尝试 - 进行GSSAPI加密连接。GSSAPI与libpq + 进行GSSAPI加密连接。GSSAPI在 libpq 中 @@ -1191,7 +1144,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - prefer (默认) + prefer (默认) 首先尝试SSL连接;如果失败,则尝试非SSL连接 @@ -1231,22 +1184,18 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - sslmode被忽略用于Unix域套接字通信。 - 如果PostgreSQL没有SSL支持编译, + 在 Unix 域套接字通信中,sslmode 会被忽略。 + 如果PostgreSQL编译时未启用 SSL 支持, 使用选项requireverify-caverify-full会导致错误,而选项allowprefer 将被接受,但libpq实际上不会尝试建立SSL 连接。SSL使用libpq的SSL + sortas="libpq">在 libpq 中 - 请注意,如果可能使用GSSAPI加密, - 则优先使用该加密,而不考虑SSL的值。要在具有可用GSSAPI - 基础设施(如Kerberos服务器)的环境中强制使用 - SSL加密,还需将 - gssencmode设置为disable。 - + 注意,如果可以使用 GSSAPI 加密,就会优先使用它而不是 SSL 加密,无论 sslmode 的值是什么。在具有可用 GSSAPI 基础设施(例如 Kerberos 服务器)的环境中,要强制使用 SSL 加密,还应将 gssencmode 设为 disable。 + @@ -1255,15 +1204,15 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 此选项已被sslmode设置所取代。 - + 此选项已弃用,请改用 sslmode 设置。 + 如果设置为1,则需要与服务器建立SSL连接(这相当于sslmode require)。libpq将拒绝连接,如果服务器不接受 SSL连接。如果设置为0(默认值), libpq将与服务器协商连接类型(相当于sslmode - prefer)。此选项仅在PostgreSQL编译时启用SSL支持。 + prefer)。此选项仅在 PostgreSQL 编译时启用了 SSL 支持的情况下可用。 @@ -1286,7 +1235,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果安全性不是主要考虑因素,压缩可以提高吞吐量,如果网络是瓶颈的话。如果CPU性能是限制因素,禁用压缩可以提高响应时间和吞吐量。 + 如果安全性不是主要考虑因素,压缩可以提高吞吐量,如果网络是瓶颈的话。如果CPU性能是限制因素,禁用压缩可以缩短响应时间并提高吞吐量。 @@ -1310,7 +1259,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 这个参数指定了用于客户端证书的密钥的位置。它可以指定一个文件名,该文件名将被用来替代默认的 ~/.postgresql/postgresql.key,或者它可以指定一个从外部引擎 - (引擎是OpenSSL可加载模块)获取的密钥。外部引擎规范应该包括一个由冒号分隔的引擎名称和 + (引擎是OpenSSL可加载模块)获取的密钥。外部引擎的指定形式应包含一个由冒号分隔的引擎名称和 一个引擎特定的密钥标识符。如果没有进行SSL连接,则此参数将被忽略。 @@ -1327,10 +1276,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 指定此参数为任何非空值将抑制Enter PEM pass phrase: - 当提供加密的客户端证书密钥给libpq时, - OpenSSL默认会发出的提示。 - + 当向 libpq 提供加密的客户端证书密钥时,将此参数指定为任意非空值,都将抑制 OpenSSL 默认发出的 Enter PEM pass phrase: 提示。 + 如果密钥未加密,则忽略此参数。该参数对由OpenSSL引擎指定的密钥没有影响,除非引擎使用OpenSSL密码回调机制进行提示。 @@ -1362,10 +1309,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定SSL服务器证书吊销列表(CRL)的文件名。如果存在该文件中列出的证书,在尝试验证服务器证书时将被拒绝。 - 如果既没有设置也没有设置, - 则将采用~/.postgresql/root.crl。 - + 此参数指定 SSL 服务器证书吊销列表(CRL)的文件名。如果该文件存在,在验证服务器证书时,会拒绝其中列出的证书。如果既未设置,也未设置,则采用 ~/.postgresql/root.crl。 + @@ -1374,8 +1319,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定SSL服务器证书吊销列表(CRL)的目录名称。如果存在该目录中的文件中列出的证书,在尝试验证服务器证书时将被拒绝。 - + 此参数指定 SSL 服务器证书吊销列表(CRL)的目录名。如果该目录存在,在验证服务器证书时,会拒绝该目录下文件中列出的证书。 + 目录需要使用OpenSSL命令 @@ -1390,11 +1335,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - sslsniServer Name Indication + sslsni服务器名称指示 - 如果设置为1(默认值),libpq会在启用SSL的连接上设置TLS扩展Server Name IndicationSNI)。 + 如果设置为1(默认值),libpq会在启用SSL的连接上设置TLS扩展服务器名称指示SNI)。 通过将此参数设置为0,可以关闭此功能。 @@ -1427,8 +1372,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定连接允许的最低SSL/TLS协议版本。有效值为TLSv1, - TLSv1.1TLSv1.2和 + 这个参数指定连接允许的最低SSL/TLS协议版本。有效值为TLSv1、 + TLSv1.1TLSv1.2TLSv1.3。支持的协议取决于所使用的 OpenSSL版本,旧版本不支持最现代的协议版本。 如果未指定,默认值为TLSv1.2,符合本文撰写时的行业最佳实践。 @@ -1441,11 +1386,10 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定连接允许的最大SSL/TLS协议版本。有效值为TLSv1, - TLSv1.1TLSv1.2和 + 这个参数指定连接允许的最大SSL/TLS协议版本。有效值为TLSv1、 + TLSv1.1TLSv1.2TLSv1.3。支持的协议取决于使用的OpenSSL - 版本,旧版本不支持最新的协议版本。如果未设置,将忽略此参数,并且连接将使用后端定义的最大限制, - 如果设置。设置最大协议版本主要用于测试或者某些组件无法使用较新协议时。 + 版本,旧版本不支持最新的协议版本。如果未设置,则忽略此参数;如果后端定义了最大限制,连接将使用该限制。设置最大协议版本主要用于测试或者某些组件无法使用较新协议时。 @@ -1459,13 +1403,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 用于使用GSSAPI进行认证时要使用的Kerberos服务名称。 + 使用 GSSAPI 认证时所用的 Kerberos 服务名。 这必须与服务器配置中指定的Kerberos认证服务名称匹配,才能成功进行认证。 (另请参见。) 默认值通常为postgres, - 但在构建PostgreSQL时可以通过 - 选项进行更改 - configure。 + 但在构建 PostgreSQL 时,可以通过 configure 选项更改。 在大多数环境中,通常不需要更改此参数。 一些Kerberos实现可能需要不同的服务名称, 例如Microsoft Active Directory需要服务名称为大写(POSTGRES)。 @@ -1590,23 +1532,21 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 连接状态函数 - 这些函数可以被用来询问一个已有数据库连接对象的状态。 + 这些函数可用于查询现有数据库连接对象的状态。 - libpq-fe.h - libpq-int.h - libpq应用程序员应该小心地维护PGconn抽象。使用下面描述的访问函数来理解PGconn的内容。我们不推荐使用libpq-int.h引用内部的PGconn域,因为它们可能在未来改变。 - + libpq-fe.h + libpq-int.h + 编写 libpq 应用程序时,应注意维护 PGconn 的抽象。请使用下述访问函数获取 PGconn 的内容。不建议通过 libpq-int.h 引用 PGconn 的内部字段,因为这些字段将来可能改变。 + - 下列函数返回一个连接所建立的参数值。这些值在连接的生命期中是固定的。 - 如果使用的是多主机连接字符串,如果使用同一个PGconn对象建立新连接,,, 和 可能会改变。其他值在PGconn对象的一生中都是固定的。 - - + 以下函数返回建立连接时确定的参数值。这些值在连接存续期间保持不变。如果使用多主机连接字符串,并使用同一个 PGconn 对象建立新连接,则 的返回值可能改变。其他值在 PGconn 对象的整个生命周期内保持不变。 + PQdbPQdb @@ -1656,7 +1596,7 @@ char *PQpass(const PGconn *conn); - 返回活跃连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 + 返回活动连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 char *PQhost(const PGconn *conn); @@ -1668,7 +1608,7 @@ char *PQhost(const PGconn *conn); - 如果conn参数是NULL,则返回NULL。否则,如果有一个错误产生主机信息(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成主机信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1689,8 +1629,7 @@ char *PQhostaddr(const PGconn *conn); - 如果conn 参数为 NULL 返回 NULL 。 - 否则,如果生成主机信息时出现错误(如果连接尚未完全建立或出现错误),则返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成主机信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1700,7 +1639,7 @@ char *PQhostaddr(const PGconn *conn); - 返回活跃连接的端口。 + 返回活动连接的端口。 char *PQport(const PGconn *conn); @@ -1712,7 +1651,7 @@ char *PQport(const PGconn *conn); - 如果conn参数是NULL,则返回NULL。否则,如果有一个错误产生端口信息(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成端口信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1726,9 +1665,7 @@ char *PQport(const PGconn *conn); - 这个函数不再做任何事,但是它保持了向后兼容。 - 这个函数总是返回一个空字符串,或者NULL,如果connNULL。 - + 此函数已不再执行任何操作,但为保持向后兼容仍予以保留。如果 conn 参数为 NULL,则返回 NULL;否则始终返回空字符串。 char *PQtty(const PGconn *conn); @@ -1741,7 +1678,7 @@ char *PQtty(const PGconn *conn); - 返回被传递给连接请求的命令行选项。 + 返回连接请求中传递的命令行选项。 char *PQoptions(const PGconn *conn); @@ -1749,12 +1686,11 @@ char *PQoptions(const PGconn *conn); - + - 下列函数返回会随着在PGconn对象上执行的操作改变的状态数据。 - - + 以下函数返回的状态数据,可能随着对 PGconn 对象执行操作而改变。 + PQstatusPQstatus @@ -1790,7 +1726,7 @@ ConnStatusType PQstatus(const PGconn *conn); PGTransactionStatusType PQtransactionStatus(const PGconn *conn); - 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个合法的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接损坏,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE。 + 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个有效的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接异常,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE @@ -1831,13 +1767,11 @@ const char *PQparameterStatus(const PGconn *conn, const char *paramName); - 询问所使用的 前端/后端协议。 + 查询正在使用的前端/后端协议。 int PQprotocolVersion(const PGconn *conn); - 应用可能希望用这个函数来确定某些特性是否被支持。当前,可能值是3(3.0 协议)或零(连接损坏)。 - 协议版本在连接启动完成后将不会改变,但是理论上在连接重置期间是可以改变的。 - 3.0 协议被PostgreSQL 7.4 或以后的服务器版本所支持。 +应用程序可以使用此函数判断是否支持某些特性。目前,可能的值为 3(协议 3.0)或零(连接异常)。连接启动完成后,协议版本不会改变,但理论上可能在连接重置期间改变。PostgreSQL 7.4 及更高版本的服务器支持协议 3.0。 @@ -1858,11 +1792,11 @@ int PQserverVersion(const PGconn *conn); - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 + 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,为每个部分使用两位数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 + 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。在所有主版本系列中,各次版本(缺陷修复版本)之间只有最后两位数字不同。 @@ -1881,9 +1815,7 @@ char *PQerrorMessage(const PGconn *conn); - 几乎所有的libpq在失败时都会为设置一个消息。 - 注意按照libpq习惯,一个非空结果由多行构成,并且将包括一个尾部新行。 - 调用者不应该直接释放结果。当相关的PGconn句柄被传递给时,它将被释放。在PGconn结构体上的多个操作之间,不能指望结果字符串会保持不变。 + 几乎所有 libpq 函数在失败时都会设置一条供 返回的消息。注意,按照 libpq 的约定,非空的 结果可能包含多行,并以换行符结尾。调用者不应直接释放该结果;当关联的 PGconn 句柄被传给 时,结果会被释放。不能假定在对 PGconn 结构体执行其他操作后,结果字符串仍保持不变。 @@ -1892,7 +1824,7 @@ char *PQerrorMessage(const PGconn *conn); PQsocketPQsocket - 获得到服务器连接套接字的文件描述符号。一个合法的描述符将会大于等于零。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 + 获取与服务器相连的套接字的文件描述符编号。有效描述符大于或等于 0。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 int PQsocket(const PGconn *conn); @@ -1909,7 +1841,7 @@ int PQsocket(const PGconn *conn); 返回处理这个连接的后端进程的进程ID(PID)。 PID 确定服务器进程的 PID - in libpq + 在 libpq 中 @@ -1918,7 +1850,7 @@ int PQbackendPID(const PGconn *conn); - 后端PID有助于调试目的并且可用于与NOTIFY消息(它包括发出提示的后端进程的PID)进行比较。注意PID属于一个在数据库服务器主机上执行的进程,而不是本地主机进程! + 后端 PID 可用于调试,也可与 NOTIFY 消息进行比较(消息包含发出通知的后端进程的 PID)。注意,该 PID 属于在数据库服务器主机上运行的进程,而非本地主机上的进程! @@ -1957,19 +1889,18 @@ int PQconnectionUsedPassword(const PGconn *conn); - + - 以下函数返回与SSL相关的信息。这些信息通常在建立连接后不会更改。 - - + 以下函数返回与 SSL 相关的信息。这些信息通常在连接建立后不会改变。 + PQsslInUsePQsslInUse - 返回true(1)如果连接使用SSL,返回false(0)如果不使用。 + 如果连接使用 SSL,则返回真(1);否则返回假(0)。 int PQsslInUse(const PGconn *conn); @@ -1985,7 +1916,7 @@ int PQsslInUse(const PGconn *conn); - 返回与连接相关的SSL信息。 + 返回连接的 SSL 相关信息。 const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); @@ -1997,7 +1928,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); - 常见的属性如下: + 通常可以获取以下属性: library @@ -2073,18 +2004,14 @@ const char * const * PQsslAttributeNames(const PGconn *conn); - 返回一个指向描述连接的SSL实现特定对象的指针。如果连接未加密或SSL实现不提供连接的请求对象类型,则返回NULL。 + 返回指向描述此连接的对象的指针,该对象的类型由 SSL 实现决定。如果连接未加密,或连接所用的 SSL 实现不提供所请求的对象类型,则返回 NULL。 void *PQsslStruct(const PGconn *conn, const char *struct_name); - 可用的结构体取决于正在使用的SSL实现。 - 对于OpenSSL,有一个结构体, - 可以通过名称OpenSSL获得, - 并返回一个指向OpenSSLSSL结构体的指针。 - 要使用这个函数,可以使用以下代码: + 可用的结构体取决于所使用的 SSL 实现。对于 OpenSSL,可以通过名称 OpenSSL 获取一个结构体,函数返回指向 OpenSSLSSL 结构体的指针。可以使用如下代码调用此函数: #include @@ -2135,7 +2062,7 @@ void *PQgetssl(const PGconn *conn); - + @@ -2144,7 +2071,7 @@ void *PQgetssl(const PGconn *conn); 命令执行函数 - 一旦到一个数据库服务器的连接被成功建立,这里描述的函数可以被用来执行 SQL 查询和命令。 + 与数据库服务器的连接成功建立后,此处描述的函数用于执行 SQL 查询和命令。 @@ -2166,11 +2093,8 @@ PGresult *PQexec(PGconn *conn, const char *command); - 返回一个PGresult指针或者可能是一个空指针。 - 除了内存不足的情况或者由于严重错误无法将命令发送给服务器之外,一般都会返回一个非空指针。 - 函数应当被调用来检查返回值是否代表错误(包括空指针的值,它会返回PGRES_FATAL_ERROR)。 - 用可得到关于那些错误的详细信息。 - + 返回一个 PGresult 指针,也可能返回空指针。除内存不足或无法向服务器发送命令等严重错误外,通常都会返回非空指针。应调用 函数检查返回值是否表示错误(也应检查空指针,此时该函数返回 PGRES_FATAL_ERROR)。使用 获取此类错误的更多信息。 + @@ -2251,8 +2175,8 @@ PGresult *PQexecParams(PGconn *conn, paramValues[] - 指定参数的实际值。这个数组中的一个空指针表示对应的参数为空,否则该指针指向一个以零终止的文本字符串(用于文本格式)或者以服务器所期待格式的二进制数据(用于二进制格式)。 - + 指定参数的实际值。数组中的空指针表示对应参数为 null;否则,指针指向以零结尾的文本字符串(文本格式),或采用服务器所要求格式的二进制数据(二进制格式)。 + @@ -2260,8 +2184,8 @@ PGresult *PQexecParams(PGconn *conn, paramLengths[] - 指定二进制格式参数的实际数据长度。它对空参数和文本格式参数被忽略。当没有二进制参数时,该数组指针可以为空。 - + 指定二进制格式参数的实际数据长度。对于 null 参数和文本格式参数,该值会被忽略。如果没有二进制参数,数组指针可以为空指针。 + @@ -2269,11 +2193,11 @@ PGresult *PQexecParams(PGconn *conn, paramFormats[] - 指定参数是否为文本(在参数相应的数组项中放一个零)或二进制(在参数相应的数组项中放一个一)。如果该数组指针为空,那么所有参数都会被假定为文本串。 - + 指定参数采用文本格式(在对应数组元素中填入零)还是二进制格式(填入一)。如果数组指针为空指针,则将所有参数视为文本字符串。 + - 以二进制格式传递的值要求后端所期待的内部表示形式的知识。例如,整数必须以网络字节序被传递。传递numeric值要求关于服务器存储格式的知识,正如src/backend/utils/adt/numeric.c::numeric_send()以及src/backend/utils/adt/numeric.c::numeric_recv()中所实现的。 - + 以二进制格式传递值时,需要了解后端所要求的内部表示形式。例如,整数必须以网络字节序传递。传递 numeric 值时,需要了解服务器的存储格式,其实现见 src/backend/utils/adt/numeric.c::numeric_send()src/backend/utils/adt/numeric.c::numeric_recv()。 + @@ -2281,8 +2205,8 @@ PGresult *PQexecParams(PGconn *conn, resultFormat - 指定零来得到文本格式的结果,或者指定一来得到二进制格式的结果(目前没有规定要求以不同格式得到不同的结果列,尽管在底层协议中这是可以实现的)。 - + 指定零以获取文本格式的结果,指定一以获取二进制格式的结果。(目前无法让不同结果列使用不同格式,尽管底层协议支持这样做。) + @@ -2293,8 +2217,8 @@ PGresult *PQexecParams(PGconn *conn, - 相对于的主要优点是参数值可以从命令串中分离,因此避免了冗长的书写、容易发生错误的引用以及转义。 - + 相对于 的主要优点是可以将参数值与命令字符串分开,从而避免繁琐且容易出错的加引号和转义工作。 + 不同,至多允许在给定串中出现一个 SQL 命令(其中可以有分号,但是不能有超过一个非空命令)。这是底层协议的一个限制,但是有助于抵抗 SQL 注入攻击。 @@ -2303,12 +2227,12 @@ PGresult *PQexecParams(PGconn *conn, - 通过 OID 指定参数类型很罗嗦,特别是如果你不愿意将特定的 OID 值硬编码到你的程序中时。不过,即使服务器本身也无法确定参数的类型,你可以避免这样做,或者选择一种与你想要的不同的类型。在 SQL 命令文本中,附加一个显式类型转换给参数符号来表示你将发送什么样的数据类型。例如: + 通过 OID 指定参数类型较为繁琐,尤其是在不希望将具体 OID 值写死在程序中时。不过,即使服务器无法自行确定参数类型,或者推断出的类型与你所需的不同,也可以避免直接指定 OID。在 SQL 命令文本中,为参数符号添加显式类型转换,即可指定要发送的数据类型。例如: SELECT * FROM mytable WHERE x = $1::bigint; - 这强制参数$1被当作bigint,而默认情况下它将被赋予与x相同的类型。当以二进制格式发送参数值时,我们强烈推荐以这种方式或通过指定一个数字类型的 OID 来强制参数类型决定。因为二进制格式比文本格式具有更少的冗余,并且因此服务器将不会有更多机会为你检测一个类型匹配错误。 - +这会强制将参数 $1 当作 bigint,而默认情况下会为它分配与 x 相同的类型。以二进制格式发送参数值时,强烈建议采用这种方式,或直接指定类型的数值 OID,来明确决定参数类型。因为二进制格式的冗余比文本格式更少,服务器发现类型不匹配错误的机会也更少。 + @@ -2329,15 +2253,15 @@ PGresult *PQprepare(PGconn *conn, - 创建一个后面会由执行的预备语句。 + 创建一个预备语句,供随后使用 执行。 这个特性允许命令被反复执行而无需每次都进行解析和规划,详见。 - + 该函数从query串创建一个名为stmtName的预备语句,该串必须包含一个单一 SQL 命令。 stmtName可以是""来创建一个未命名语句,在这种情况下任何已存在未命名语句将被自动替换。 否则,如果语句名称已经在当前会话中被定义,则是一种错误。如果使用了任何参数,它们在查询中以$1$2等引用。 - nParams是参数的个数,其类型在数组paramTypes[]中被预先指定(当nParams为零时,该数组指针可以是NULL)。 + nParams 是在数组 paramTypes[] 中预先指定了类型的参数数量(当nParams为零时,该数组指针可以是NULL)。 paramTypes[]通过 OID 指定要赋予给参数符号的数据类型。 如果paramTypesNULL或者该数组中任何特定元素为零,服务器会用对待未指定类型的字符串字面量的方式为参数符号推测一种数据类型。 还有,查询能够使用编号高于nParams的参数符号,它们的数据类型也会被自动推测(找出推测出的数据类型的方法见)。 @@ -2345,7 +2269,7 @@ PGresult *PQprepare(PGconn *conn, 正如一样,结果通常是一个PGresult对象,其内容代表服务器端成功或失败。 - 一个空结果表示内存不足或者根本无法发送命令。关于错误的更多信息请见。 + 返回空指针表示内存不足,或者根本无法发送命令。关于错误的更多信息请见 @@ -2378,9 +2302,9 @@ PGresult *PQexecPrepared(PGconn *conn, 类似于, - 但要执行的命令是通过指定先前准备好的语句来指定,而不是提供查询字符串。 - 此功能允许重复使用的命令只被解析和计划一次,而不是每次执行时都要进行。 - 该语句必须在当前会话中先前准备好。 + 但它通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。 + 此功能使重复使用的命令只需解析和规划一次,而不必在每次执行时都进行这些工作。 + 该语句必须事先在当前会话中创建为预备语句。 @@ -2397,23 +2321,23 @@ PGresult *PQexecPrepared(PGconn *conn, - 提交请求以获取有关指定准备好的语句的信息,并等待完成。 + 提交请求以获取有关指定预备语句的信息,并等待完成。 PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - 允许应用程序获取关于先前准备的语句的信息。 + 允许应用程序获取关于先前创建的预备语句的信息。 stmtName可以是""NULL来引用 - 未命名的语句,否则必须是现有准备好的语句的名称。成功时,返回一个 + 未命名的语句,否则必须是现有预备语句的名称。成功时,返回一个 状态为PGRES_COMMAND_OKPGresult。 函数可以应用于此 - PGresult以获取有关准备语句参数的信息, + PGresult以获取有关预备语句参数的信息, 函数等提供有关语句的结果列(如果有)的信息。 @@ -2427,22 +2351,21 @@ PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - 提交请求以获取有关指定门户的信息,并等待完成。 + 提交请求以获取有关指定 portal 的信息,并等待完成。 PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - 允许应用程序获取有关先前创建的portal的信息。 - (libpq不直接提供对portals的访问,但您可以使用此函数检查使用DECLARE CURSOR SQL命令创建的游标的属性。) - + 允许应用程序获取先前创建的 portal 的信息。(libpq 不提供对 portal 的直接访问,但可以用此函数检查通过 DECLARE CURSOR SQL 命令创建的游标的属性。) + - portalName可以是""NULL来引用未命名的portal, - 否则必须是现有portal的名称。成功时,将返回一个带有状态PGRES_COMMAND_OKPGresult。 + portalName可以是""NULL来引用未命名的 portal, + 否则必须是现有 portal 的名称。成功时,将返回一个带有状态PGRES_COMMAND_OKPGresult。 函数等可应用于 - PGresult,以获取有关portal的结果列(如果有)的信息。 + PGresult,以获取有关 portal 的结果列(如果有)的信息。 @@ -2454,9 +2377,8 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - PGresultPGresult结构体封装了由服务器返回的结果。libpq应用程序员应该小心地维护PGresult的抽象。使用下面的存储器函数来得到PGresult的内容。避免直接引用PGresult结构体的域,因为它们可能在未来更改。 - - + PGresultPGresult 结构体封装服务器返回的结果。编写 libpq 应用程序时,应注意维护 PGresult 的抽象。请使用下述访问函数获取 PGresult 的内容。避免直接引用 PGresult 结构体的字段,因为这些字段将来可能改变。 + PQresultStatusPQresultStatus @@ -2557,7 +2479,7 @@ ExecStatusType PQresultStatus(const PGresult *res); PGRES_SINGLE_TUPLE - PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单一行模式时发生(见)。 + PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单行模式时发生(见)。 @@ -2583,7 +2505,7 @@ ExecStatusType PQresultStatus(const PGresult *res); - 如果结果状态是PGRES_TUPLES_OKPGRES_SINGLE_TUPLEPGRES_TUPLES_CHUNK,则可以使用下面描述的函数来提取查询返回的行。注意,恰好检索到零行的SELECT命令仍然显示为PGRES_TUPLES_OKPGRES_COMMAND_OK用于永远不会返回行的命令(例如没有RETURNING子句的INSERTUPDATE等)。返回PGRES_EMPTY_QUERY可能表示客户端软件中存在缺陷。 + 如果结果状态是PGRES_TUPLES_OKPGRES_SINGLE_TUPLE,则可以使用下面描述的函数来提取查询返回的行。注意,恰好检索到零行的SELECT命令仍然显示为PGRES_TUPLES_OKPGRES_COMMAND_OK用于永远不会返回行的命令(例如没有RETURNING子句的INSERTUPDATE等)。返回PGRES_EMPTY_QUERY可能表示客户端软件中存在缺陷。 @@ -2597,12 +2519,11 @@ ExecStatusType PQresultStatus(const PGresult *res); - 将返回的枚举转换成描述状态编码的字符串常量。调用者不应该释放结果。 - + 将 返回的枚举值转换为描述该状态码的字符串常量。调用者不应释放此结果。 char *PQresStatus(ExecStatusType status); - + @@ -2611,12 +2532,12 @@ char *PQresStatus(ExecStatusType status); - 返回与该命令相关的错误消息,如果有错误则会返回一个空字符串。 + 返回与命令关联的错误消息;如果没有错误,则返回空字符串。 char *PQresultErrorMessage(const PGresult *res); - 如果有一个错误,被返回的字符串将包含一个收尾的新行。调用者不应该直接释放结果。它将在相关的PGresult句柄被传递给之后被释放。 - +如果发生了错误,返回的字符串会以换行符结尾。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 + 紧跟着一个调用,(在连接上)将返回与相同的字符串(在结果上)。 @@ -2632,16 +2553,14 @@ char *PQresultErrorMessage(const PGresult *res); - 返回与PGresult对象相关的错误消息的重新格式化的版本。 + 返回与 PGresult 对象关联的错误消息的重新格式化版本。 char *PQresultVerboseErrorMessage(const PGresult *res, PGVerbosity verbosity, PGContextVisibility show_context); - 在有些情况下,客户端可能希望得到之前报告过的错误的更加详尽的版本。 - 如果在产生给定PGresult的连接上 verbosity 设置有效,会通过计算已经被产生过的消息来满足这种需求。 - 如果PGresult不是一个错误结果,则会报告PG 结果不是错误结果。返回的字符串包括一个新行作为结尾。 - +有时客户端希望获取先前报告过的错误的更详细版本。 可满足这一需求:它按指定的详细程度设置重新生成消息。假如在生成给定 PGresult 时,连接已经采用这些设置,那么 返回的就会是这条消息。如果 PGresult 不是错误结果,则改为报告 PGresult is not an error result。返回的字符串以换行符结尾。 + 和大部分从PGresult中提取数据的其他函数不同,这个函数的结果是一个全新分配的字符串。调用者在不需要这个字符串以后,必须使用PQfreemem()释放它。 @@ -2657,24 +2576,21 @@ char *PQresultVerboseErrorMessage(const PGresult *res, PQresultErrorFieldPQresultErrorField - 返回一个错误报告的一个域。 + 返回错误报告中的单个字段。 char *PQresultErrorField(const PGresult *res, int fieldcode); - fieldcode是一个错误域标识符,见下列符号。 - 如果PGresult不是一个错误或者警告结果或者不包括指定域,会返回NULL。 - 域通常不包括一个收尾的新行。调用者不应该直接释放结果。 - 它将在相关的PGresult句柄被传递给之后被释放。 - +fieldcode 是错误字段标识符,参见下文列出的符号。如果 PGresult 不是错误或警告结果,或者不包含指定字段,则返回 NULL。字段值通常不含末尾换行符。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 + - 下列域代码可用: + 下列字段代码可用: PG_DIAG_SEVERITY - 严重性。域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 @@ -2683,17 +2599,17 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_SEVERITY_NONLOCALIZED - 域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY域相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 版本以后产生的报告中。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY字段相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 及更高版本产生的报告中。 PG_DIAG_SQLSTATEerror codeslibpq + >错误码libpq - 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个域无法被本地化,并且总是存在。 + 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个字段无法被本地化,并且总是存在。 @@ -2720,7 +2636,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_MESSAGE_HINT - 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是铁的事实。可能有多行。 + 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是确切事实。可能有多行。 @@ -2738,7 +2654,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_INTERNAL_POSITION - 这被定义为与PG_DIAG_STATEMENT_POSITION域相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个域出现时,PG_DIAG_INTERNAL_QUERY域将总是出现。 + 这被定义为与PG_DIAG_STATEMENT_POSITION字段相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个字段出现时,PG_DIAG_INTERNAL_QUERY字段将总是出现。 @@ -2756,7 +2672,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONTEXT - 指示错误发生的环境。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 + 指示错误发生的上下文。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 @@ -2774,7 +2690,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_TABLE_NAME - 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名域)。 + 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名字段)。 @@ -2783,7 +2699,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_COLUMN_NAME - 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名域来标识该表)。 + 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名字段来标识该表)。 @@ -2792,7 +2708,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_DATATYPE_NAME - 如果错误与一个特定数据类型相关,这里是该数据了行的名字(该数据类型的模式名参考模式名域)。 + 如果错误与一个特定数据类型相关,这里是该数据类型的名字(该数据类型的模式名参考模式名字段)。 @@ -2801,7 +2717,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONSTRAINT_NAME - 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的域(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 + 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的字段(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 @@ -2837,16 +2753,16 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); - 用于模式名、表名、列名、数据类型名和约束名的域只提供给有限的错误类型,见。不要假定任何这些域的存在保证另一个域的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些域。同样地,不要假定这些域代表当前数据库中同类的对象。 + 用于模式名、表名、列名、数据类型名和约束名的字段只提供给有限的错误类型,见。不要假定任何这些字段的存在保证另一个字段的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些字段。同样地,不要假定这些字段代表当前数据库中现存的对象。 - 客户端负责格式化显示信息来迎合它的需要,特别是根据需要打断长的行。出现在错误消息域中的新行字符应该被当作分段而不是换行。 + 客户端负责按自身需要格式化所显示的信息,尤其应在需要时将长行折行。错误消息字段中的换行符应当视为段落分隔,而非行分隔。 - libpq内部产生的错误将有严重和主要消息,但是通常没有其他域。 + libpq内部产生的错误将包含严重性和主要消息,但是通常没有其他字段。 @@ -2859,14 +2775,11 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PQclearPQclear - 释放与一个PGresult关联的存储。每个命令结果在不再需要时都应通过释放。 - + 释放与 PGresult 关联的存储空间。每个命令结果在不再需要时都应通过 释放。 void PQclear(PGresult *res); - - 如果参数是NULL指针,则不会执行任何操作。 - + 你可以在需要时一直保留PGresult对象;它不会在你发出新命令时消失,甚至在关闭连接后也不会消失。要销毁它,你必须调用。否则应用程序会发生内存泄漏。 @@ -2874,7 +2787,7 @@ void PQclear(PGresult *res); - + @@ -2882,8 +2795,8 @@ void PQclear(PGresult *res); 检索查询结果信息 - 这些函数被用来从一个代表成功查询结果(也就是状态为PGRES_TUPLES_OK或者PGRES_SINGLE_TUPLE)的PGresult对象中抽取信息。它们也可以被用来从一个成功的 Describe 操作中抽取信息:一个 Describe 的结果具有和该查询被实际执行所提供的完全相同的列信息,但是它没有行。对于其他状态值的对象,这些函数会认为结果具有零行和零列。 - + 这些函数用于从表示成功查询结果的 PGresult 对象中提取信息,即状态为 PGRES_TUPLES_OKPGRES_SINGLE_TUPLE 的对象。它们也可用于提取成功 Describe 操作的结果信息:Describe 结果包含的列信息与实际执行查询时相同,但行数为零。对于其他状态值的对象,这些函数会将结果视为零行、零列。 + @@ -2910,7 +2823,7 @@ int PQntuples(const PGresult *res); - 返回查询结果中每一行的列(域)数。 + 返回查询结果中每一行的列(字段)数。 int PQnfields(const PGresult *res); @@ -2926,7 +2839,7 @@ int PQnfields(const PGresult *res); - 返回与给定列号相关联的列名。列号从 0 开始。调用者不应该直接释放该结果。它将在相关的PGresult句柄被传递给之后被释放。 + 返回给定列号对应的列名。列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 char *PQfname(const PGresult *res, int column_number); @@ -2958,11 +2871,11 @@ int PQfnumber(const PGresult *res, - 给定的名称被视作一个 SQL 命令中的一个标识符,也就是说,除非被双引号引用,它是小写形式的。例如,给定一个 SQL 命令: + 给定名称按 SQL 命令中的标识符处理,即除非用双引号引用,否则会转换为小写。例如,对于以下 SQL 命令生成的查询结果: SELECT 1 AS FOO, 2 AS "BAR"; - 我们将得到结果: +会得到以下结果: PQfname(res, 0) foo PQfname(res, 1) BAR @@ -2982,7 +2895,7 @@ PQfnumber(res, "\"BAR\"") 1 - 返回给定列从中取出的表的 OID。列号从 0 开始。 + 返回给定列所取自的表的 OID。列号从 0 开始。 Oid PQftable(const PGresult *res, int column_number); @@ -2995,7 +2908,7 @@ Oid PQftable(const PGresult *res, - 当你包括libpq头文件,类型oid以及常数InvalidOid将被定义。它们将都是某种整数类型。 + 包含 libpq 头文件后,将定义类型 Oid 和常量 InvalidOid。它们都属于某种整数类型。 @@ -3007,7 +2920,7 @@ Oid PQftable(const PGresult *res, - 返回构成指定查询结果列的列(在其表中)的列号。查询结果列号从 0 开始,但是表列具有非零编号。 + 返回指定查询结果列所对应的表列在表中的列号。查询结果的列号从 0 开始,而表列的编号非零。 int PQftablecol(const PGresult *res, int column_number); @@ -3027,7 +2940,7 @@ int PQftablecol(const PGresult *res, - 返回指示给定列格式的格式编码。列号从 0 开始。 + 返回表示给定列格式的格式代码。列号从 0 开始。 int PQfformat(const PGresult *res, int column_number); @@ -3035,7 +2948,7 @@ int PQfformat(const PGresult *res, - 格式代码零指示文本数据表示,而格式代码一表示二进制表示(其他代码被保留用于未来的定义)。 + 格式代码零表示文本数据,格式代码一表示二进制数据。(其他代码保留供将来定义。) @@ -3055,7 +2968,7 @@ Oid PQftype(const PGresult *res, - 你可以查询系统表pg_type来得到多个数据类型的名字和属性。 + 你可以查询系统表pg_type来获取各种数据类型的名称和属性。 内置数据类型的OID被定义在PostgreSQL安装的include目录中的catalog/pg_type_d.h文件中。 @@ -3068,7 +2981,7 @@ Oid PQftype(const PGresult *res, - 返回与给定列号相关联的列的修饰符类型。列号从 0 开始。 + 返回与给定列号相关联的列的类型修饰符。列号从 0 开始。 int PQfmod(const PGresult *res, int column_number); @@ -3076,7 +2989,7 @@ int PQfmod(const PGresult *res, - 修饰符值的解释是与类型相关的,它们通常指示精度或尺寸限制。值 -1 被用来指示没有信息可用。大部分的数据类型不适用修饰符,在那种情况中值总是 -1。 + 修饰符值的含义由数据类型决定,通常表示精度或大小限制。值 -1 表示没有可用信息。大多数数据类型不使用修饰符,此时该值始终为 -1。 @@ -3088,7 +3001,7 @@ int PQfmod(const PGresult *res, - 返回与给定列号相关的列的尺寸(以字节计)。列号从 0 开始。 + 返回给定列号对应列的大小,以字节计。列号从 0 开始。 int PQfsize(const PGresult *res, int column_number); @@ -3096,7 +3009,7 @@ int PQfsize(const PGresult *res, - 返回在一个数据库行中为这个列分配的空间,换句话说是服务器对该数据类型的内部表示的尺寸(因此,它对客户端并不是真地非常有用)。一个负值指示该数据类型是变长的。 + 返回数据库行中为该列分配的空间,即服务器内部表示该数据类型所需的大小。(因此,它对客户端用处不大。)负值表示该数据类型是变长类型。 @@ -3115,8 +3028,7 @@ int PQbinaryTuples(const PGresult *res); - 这个函数已经被废弃(除了与COPY一起使用),因为一个单一PGresult可以在某些列中包含文本数据而且在另一些列中包含二进制数据。 - 要更好。只有结果的所有列是二进制(格式 1)时才返回 1。 + 此函数已弃用(与 COPY 配合使用的情况除外),因为单个 PGresult 可能在部分列中包含文本数据,而在其他列中包含二进制数据。推荐使用 。只有结果中的所有列都采用二进制格式(格式 1)时, 才返回 1。 @@ -3128,8 +3040,7 @@ int PQbinaryTuples(const PGresult *res); - 返回一个PGresult的一行的单一域值。行和列号从 0 开始。调用者不应该直接释放该结果。 - 它将在相关的PGresult句柄被传递给之后被释放。 + 返回 PGresult 中某一行的单个字段值。行号和列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 char *PQgetvalue(const PGresult *res, int row_number, @@ -3138,15 +3049,15 @@ char *PQgetvalue(const PGresult *res, - 对于文本格式的数据,返回的值是该域值的一种空值结束的字符串表示。对于二进制格式的数据,该值是由该数据类型的typsendtypreceive函数决定的二进制表示(在这种情况下该值实际上也跟随着一个零字节,但是这通常没有用处,因为该值很可能包含嵌入的空)。 + 对于文本格式的数据, 返回字段值的字符串表示,以零字节结尾。对于二进制格式的数据,返回值采用该数据类型的 typsendtypreceive 函数所决定的二进制表示。(这种情况下,值后面实际上也有一个零字节,但通常没有用处,因为值本身很可能包含零字节。) - 如果该域值为空,则返回一个空串。关于区分空值和空字符串值请见。 + 如果字段值为 null,则返回空字符串。关于如何区分 null 值与空字符串值,参见 - 返回的指针指向作为PGresult结构体一部分的存储。我们不应该修改它指向的数据,并且如果要在超过PGresult结构体本身的生命期之外使用它,我们必须显式地把该数据拷贝到其他存储中。 + 返回的指针指向属于 PGresult 结构体的存储空间。不应修改它所指向的数据;如果需要在 PGresult 结构体的生命周期结束后继续使用这些数据,就必须显式地将数据复制到其他存储空间。 @@ -3155,12 +3066,12 @@ char *PQgetvalue(const PGresult *res, PQgetisnullPQgetisnullnull valuein libpq + >null 值libpq 中的 - 测试一个域是否为空值。行号和列号从 0 开始。 + 检查字段是否为 null 值。行号和列号从 0 开始。 int PQgetisnull(const PGresult *res, int row_number, @@ -3169,7 +3080,7 @@ int PQgetisnull(const PGresult *res, - 如果该域是空,这个函数返回 1。如果它包含一个非空值,则返回 0(注意将为一个空域返回一个空串,不是一个空指针)。 + 如果字段为 null,此函数返回 1;如果包含非 null 值,则返回 0。(注意,对于 null 字段, 返回空字符串,而非空指针。) @@ -3181,7 +3092,7 @@ int PQgetisnull(const PGresult *res, - 返回一个域值的真实长度,以字节计。行号和列号从 0 开始。 + 返回字段值的实际长度,以字节计。行号和列号从 0 开始。 int PQgetlength(const PGresult *res, int row_number, @@ -3190,9 +3101,7 @@ int PQgetlength(const PGresult *res, - 这是特定数据值的真实数据长度,也就是指向的对象的尺寸。 - 对于文本数据格式,这和strlen()相同。对于二进制格式这是基本信息。 - 注意我们应该依赖于来得到真值的数据长度。 + 这是该数据值的实际数据长度,即 所指对象的大小。对于文本格式的数据,它与 strlen() 的结果相同。对于二进制格式,这是必不可少的信息。注意,不应依赖 来获取实际数据长度。 @@ -3242,29 +3151,29 @@ Oid PQparamtype(const PGresult *res, int param_number); - 将所有的行打印到指定的输出流,以及有选择地将列名打印到指定的输出流。 + 将所有行输出到指定的输出流,并可选择输出列名。 void PQprint(FILE *fout, /* 输出流 */ const PGresult *res, const PQprintOpt *po); typedef struct { - pqbool header; /* 打印输出域标题和行计数 */ - pqbool align; /* 填充对齐域 */ - pqbool standard; /* 旧的格式 */ + pqbool header; /* 打印输出字段标题和行数 */ + pqbool align; /* 填充并对齐字段 */ + pqbool standard; /* 旧的简陋格式 */ pqbool html3; /* 输出 HTML 表格 */ - pqbool expanded; /* 扩展表格 */ - pqbool pager; /* 如果必要为输出使用页 */ - char *fieldSep; /* 域分隔符 */ + pqbool expanded; /* 展开表格 */ + pqbool pager; /* 需要时使用分页器输出 */ + char *fieldSep; /* 字段分隔符 */ char *tableOpt; /* 用于 HTML 表格元素的属性 */ char *caption; /* HTML 表格标题 */ - char **fieldName; /* 替换域名称的空终止数组 */ + char **fieldName; /* 以空指针结尾的替换字段名数组 */ } PQprintOpt; - 这个函数以前被psql用来打印查询结果,但是现在不是这样了。注意它假定所有的数据都是文本格式。 + psql 以前用此函数打印查询结果,现在已不再使用。注意,此函数假定所有数据都是文本格式。 @@ -3313,13 +3222,7 @@ char *PQcmdTuples(PGresult *res); - 该函数返回一个字符串,其中包含由生成PGresultSQL语句影响的行数。 - 该函数只能在执行SELECTCREATE TABLE AS、 - INSERTUPDATEDELETE、 - MERGEMOVEFETCHCOPY语句, - 或包含INSERTUPDATEDELETEMERGE语句的预处理查询的EXECUTE之后使用。 - 如果生成PGresult的命令是其他任何命令,将返回一个空字符串。 - 调用者不应直接释放返回值。当关联的PGresult句柄传递给时,它将被释放。 + 此函数返回一个字符串,其中包含产生该 PGresultSQL 语句所影响的行数。此函数只能在执行 SELECTCREATE TABLE ASINSERTUPDATEDELETEMERGEMOVEFETCHCOPY 语句之后使用,也可以在对包含 INSERTUPDATEDELETEMERGE 语句的预备查询执行 EXECUTE 之后使用。如果产生 PGresult 的是其他命令, 将返回空字符串。调用者不应直接释放返回值;当关联的 PGresult 句柄被传给 时,返回值会被释放。 @@ -3331,7 +3234,7 @@ char *PQcmdTuples(PGresult *res); - 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDin libpq。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid。 + 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDlibpq 中的。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid Oid PQoidValue(const PGresult *res); @@ -3346,7 +3249,7 @@ Oid PQoidValue(const PGresult *res); - 这个函数已经被取代,并且不是线程安全的。它返回包含被插入行的 OID 的一个字符串,而返回 OID 值。 + 此函数不是线程安全的,现已弃用,推荐改用 。它返回包含插入行 OID 的字符串,而 返回 OID 值。 char *PQoidStatus(const PGresult *res); @@ -3364,7 +3267,7 @@ char *PQoidStatus(const PGresult *res); 转义字符串 - in libpq + libpq 中的 @@ -3382,17 +3285,13 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); 为了让一个字符串可用于 SQL 命令,会对它进行转义。 - 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜线)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 + 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜杠)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 执行这种操作。 - 返回一个str参数的已被转义版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - 返回字符串中的所有特殊字符都会被替换,这样它们就能被PostgreSQL字符串字面量解析器正确处理。 - 结果中也会附加一个终止零字节,并包含包围PostgreSQL字符串字面量所需的单引号。 - + 返回 str 参数的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便 PostgreSQL 字符串字面量解析器正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号包含在结果字符串中。 + 发生错误时,返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -3406,7 +3305,7 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); - 注意,当一个数据值被作为或其兄弟例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 + 注意,当一个数据值被作为或相关例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 @@ -3424,15 +3323,12 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - 转义一个要用作 SQL 标识符的字符串,例如表名、列名或函数名。当一个用户提供的标识符可能包含被 SQL 解析器解释为标识符一部分的特殊字符时,或者当该标识符可能包含大小写形式应该被保留的大写字符时,这个函数很有用。 - + 对字符串进行转义,使其可用作 SQL 标识符,例如表名、列名或函数名。当用户提供的标识符可能包含未经转义就不会被 SQL 解析器视为标识符一部分的特殊字符,或包含需要保留大小写的大写字符时,此函数很有用。 + - 返回一个str参数的已被转义为 SQL 标识符的版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - 返回串中的所有特殊字符都被替换掉,这样它们能被作为一个 SQL 标识符正确地处理。还会加上一个终止零字节。返回串也将被双引号包围。 - + 返回 str 参数作为 SQL 标识符的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,必须使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便正确地作为 SQL 标识符处理。还会添加一个末尾零字节,并用双引号包围返回的字符串。 + 发生错误时,返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -3441,7 +3337,7 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - 与字符串一样,要阻止 SQL 注入攻击,当从一个不可信的来源接收到 SQL 标识符时,它们必须被转义。 + 与字符串字面量一样,为防止 SQL 注入攻击,从不可信来源接收到的 SQL 标识符必须经过转义。 @@ -3462,18 +3358,12 @@ size_t PQescapeStringConn(PGconn *conn, - 转义字符串,它很像。 - 与不一样的是,调用者负责提供一个合适尺寸的缓冲区。 - 此外,不产生必须包围PostgreSQL字符串的单引号。 - 它们应该在结果要插入的 SQL 命令中提供。参数from指向要被转义的串的第一个字符,并且length参数给出了这个串中的字节数。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - to应当指向一个缓冲区,它能够保持至少比length值的两倍还要多至少一个字节,否则该行为是未被定义的。 - 如果tofrom串重叠,行为也是未被定义的。 - + 对字符串字面量进行转义,与 类似。与 不同,调用者需要提供大小合适的缓冲区。此外, 不会生成包围 PostgreSQL 字符串字面量所需的单引号;应在包含转义结果的 SQL 命令中提供这些引号。from 参数指向待转义字符串的首字符,length 参数给出该字符串的字节数。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)to 必须指向一个缓冲区,其容量至少为 length 的两倍加一个字节,否则行为未定义。如果 tofrom 字符串重叠,行为同样未定义。 + - 如果error参数不是NULL,那么成功时*error被设置为零,错误时设置为非零。当前唯一可能的错误情况涉及源串中非法的多字节编码。错误时仍然会产生输出串,但是可以预期服务器将认为它是畸形的并且拒绝它。在发生错误时,一个合适的消息被存储在conn对象中,不管error是不是NULL。 - + 如果 error 参数不是 NULL,则成功时将 *error 设为零,出错时设为非零。目前唯一可能的错误是源字符串中存在无效的多字节编码。出错时仍会生成输出字符串,但预计服务器会因其格式错误而拒绝它。发生错误时,无论 error 是否为 NULL,都会在 conn 对象中保存相应消息。 + 返回写到to的字节数,不包括终止的零字节。 @@ -3488,21 +3378,19 @@ size_t PQescapeStringConn(PGconn *conn, - 是一个更老的被废弃的版本。 + 的旧版本,现已弃用。 size_t PQescapeString (char *to, const char *from, size_t length); - + - 之间的唯一区别是不需要PGconnerror参数。 - 正因为如此,它不能基于连接属性(例如字符编码)调整它的行为并且因此它可能给出错误的结果。还有,它没有方法报告错误情况。 - + 与 唯一的区别是, 不接受 PGconnerror 参数。因此,它无法根据连接属性(例如字符编码)调整行为,可能给出错误的结果。此外,它也无法报告错误情况。 + - 可以在一次只使用一个PostgreSQL连接的客户端程序中安全地使用(在这种情况下它可以在现象后面找出它需要知道的东西)。 - 在其他环境中它是一个安全性灾难并且应该用来避免。 - + 可以在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。在其他情形下,它存在安全隐患,应改用 。 + @@ -3513,7 +3401,7 @@ size_t PQescapeString (char *to, const char *from, size_t length); - 把要用于一个 SQL 命令的二进制数据用类型bytea转义。和一样,只有在将数据直接插入到一个 SQL 命令串时才使用它。 + 对二进制数据进行转义,使其能够在 SQL 命令中用作 bytea 类型的值。与 一样,这仅用于将数据直接插入 SQL 命令字符串的情况。 unsigned char *PQescapeByteaConn(PGconn *conn, const unsigned char *from, @@ -3528,14 +3416,11 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - from参数指向要被转义的串的第一个字节,并且from_length参数给出这个二进制串中的字节数(一个终止的零字节是不需要的也是不被计算的)。to_length参数指向一个将保持生成的已转义串长度的变量。这个结果串长度包括结果的终止零字节。 + from 参数指向待转义字符串的首字节,from_length 参数给出该二进制字符串的字节数。(末尾零字节既不需要,也不计入长度。)to_length 参数指向用于保存转义后字符串长度的变量。该结果字符串长度包含结果末尾的零字节。 - 返回一个from参数的已被转义为二进制串的版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 返回串中的所有特殊字符都被替换掉,这样它们能被PostgreSQL的字符串解析器以及bytea输入函数正确地处理。 - 还会加上一个终止零字节。不是结果串一部分的PostgreSQL字符串必须被单引号包围。 + 返回 from 参数所指二进制字符串的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。返回字符串中的所有特殊字符都已替换,以便 PostgreSQL 字符串字面量解析器和 bytea 输入函数正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号不包含在结果字符串中。 @@ -3551,7 +3436,7 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - 是一个更老的被废弃的版本。 + 的旧版本,现已弃用。 unsigned char *PQescapeBytea(const unsigned char *from, size_t from_length, @@ -3560,9 +3445,7 @@ unsigned char *PQescapeBytea(const unsigned char *from, - 与的唯一区别是不用一个PGconn参数。 - 正因为这样,只能在一次只使用一个PostgreSQL连接的客户端程序中安全地使用(在这种情况下它可以在现象后面找出它需要知道的东西)。 - 如果在有多个数据库连接的程序中使用,它可能给出错误的结果(在那种情况下使用)。 + 与 唯一的区别是, 不接受 PGconn 参数。因此, 只能在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。如果在使用多个数据库连接的程序中使用,它可能给出错误的结果(此时应使用 )。 @@ -3634,21 +3517,15 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - 总是收集命令的整个结果,把它缓存在一个单一的PGresult中。虽然这简化了应用的错误处理逻辑,它对于包含很多行的结果并不现实。 - + 总是收集命令的完整结果,并将其缓存在单个 PGresult 中。这简化了应用程序的错误处理逻辑,但对于包含大量行的结果,可能不切实际。 + - 如果应用程序不希望受到这些限制,可以改用构成的底层函数:。此外,还有, - , - , - ,以及,它们可以与配合使用,分别实现以下函数的功能:, - , - , - ,以及。 - - + + 如果应用程序不希望受到这些限制,可以改用构成 的底层函数:。此外, 可以与 配合使用,分别实现 的功能。 + PQsendQueryPQsendQuery @@ -3656,14 +3533,11 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - 提交一个命令到服务器,而不等待结果。 - 如果成功发送命令,则返回1,如果失败则返回0(在这种情况下,使用获取更多关于失败的信息)。 + 向服务器提交命令,不等待结果。命令发送成功时返回 1,否则返回 0(此时可使用 获取更多失败信息)。 int PQsendQuery(PGconn *conn, const char *command); - - 成功调用后,调用一次或多次来获取结果。 - 在返回空指针,表示命令执行完成之前,无法再次调用(在同一连接上)。 +成功调用 后,应调用 一次或多次来获取结果。在 返回空指针、表明命令已完成之前,不得在同一连接上再次调用 @@ -3679,7 +3553,7 @@ int PQsendQuery(PGconn *conn, const char *command); - 提交一个命令和参数到服务器,而不等待结果。 + 向服务器提交命令及独立指定的参数,不等待结果。 int PQsendQueryParams(PGconn *conn, const char *command, @@ -3690,9 +3564,7 @@ int PQsendQueryParams(PGconn *conn, const int *paramFormats, int resultFormat); - - 这相当于,不同之处在于可以单独指定查询参数而不是与查询字符串一起指定。 - 函数的参数处理方式与完全相同。与一样,它在查询字符串中只允许一个命令。 +该函数等价于 ,但查询参数可以与查询字符串分开指定。函数参数的处理方式与 相同。与 一样,查询字符串中只允许包含一条命令。 @@ -3704,7 +3576,7 @@ int PQsendQueryParams(PGconn *conn, - 发送一个请求来创建一个带有给定参数的预备语句,而不等待完成。 + 发送按给定参数创建预备语句的请求,不等待完成。 int PQsendPrepare(PGconn *conn, const char *stmtName, @@ -3712,10 +3584,7 @@ int PQsendPrepare(PGconn *conn, int nParams, const Oid *paramTypes); - - 这是的异步版本:如果能够分派请求,则返回1,否则返回0。 - 成功调用后,调用来确定服务器是否成功创建了预备语句。 - 该函数的参数处理方式与完全相同。 +这是 的异步版本:请求发送成功时返回 1,否则返回 0。调用成功后,再调用 ,确定服务器是否成功创建了预备语句。函数参数的处理方式与 相同。 @@ -3727,7 +3596,7 @@ int PQsendPrepare(PGconn *conn, - 发送一个请求来执行一个准备好的语句,带有给定的参数,而不等待结果。 + 发送使用给定参数执行预备语句的请求,不等待结果。 int PQsendQueryPrepared(PGconn *conn, const char *stmtName, @@ -3737,9 +3606,7 @@ int PQsendQueryPrepared(PGconn *conn, const int *paramFormats, int resultFormat); - - 这类似于,但要执行的命令是通过指定一个之前准备好的语句的名称来指定,而不是提供一个查询字符串。 - 函数的参数处理方式与完全相同。 +该函数类似于 ,但通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。函数参数的处理方式与 相同。 @@ -3771,7 +3638,7 @@ int PQsendDescribePrepared(PGconn *conn, const char *stmtName); - 提交请求以获取有关指定门户的信息,而无需等待完成。 + 提交请求以获取有关指定 portal 的信息,而无需等待完成。 int PQsendDescribePortal(PGconn *conn, const char *portalName); @@ -3810,13 +3677,7 @@ PGresult *PQgetResult(PGconn *conn); - 必须重复调用直到返回空指针,表示命令已完成。 - (如果在没有活动命令时调用, - 将立即返回空指针。)每个非空结果从 - 应该使用先前描述的相同PGresult访问器函数进行处理。 - 完成后不要忘记使用释放每个结果对象。请注意, - 仅在有命令处于活动状态且必要的响应数据尚未被 - 读取时才会阻塞。 + 必须反复调用 ,直到它返回空指针,表明命令已经完成。(如果当前没有正在执行的命令,调用 会立即返回空指针。)对于 返回的非空指针,应使用前文介绍的 PGresult 访问函数处理相应结果。使用完毕后,不要忘记调用 释放每个结果对象。注意,只有存在正在执行的命令,且所需响应数据尚未被 读取时, 才会阻塞。 @@ -3839,41 +3700,37 @@ PGresult *PQgetResult(PGconn *conn); - + - 使用解决了的一个问题:如果一个命令字符串包含多个SQL命令,这些命令的结果可以被个别地获得(顺便说一句:这样就允许一种简单的重叠处理形式, 客户端可以处理一个命令的结果,而同时服务器可以继续处理同一命令字符串中后面的查询)。 - + 使用 可以解决 的一个问题:如果命令字符串包含多个 SQL 命令,就能分别获取这些命令的结果。(这也支持一种简单的重叠处理方式:客户端可以处理某条命令的结果,同时服务器继续处理同一命令字符串中后面的查询。) + - 可以被获得的另一种常常想要的特性是一次从大型结果中检索一行。这会在中讨论。 - + 使用 还可以实现另一项常见需求:从大型查询结果中一次读取一行。详见 。 + - 就其本身而言,调用将仍会导致客户端阻塞,直到服务器完成下一个SQL命令。可以通过正确使用两个函数来避免这种情况: - - + 仅仅调用 仍会使客户端阻塞,直到服务器完成下一条 SQL 命令。可以通过正确使用另外两个函数来避免这种情况: + PQconsumeInputPQconsumeInput - 如果有来自服务器的输入可用,则使用之。 + 如果服务器有可读取的输入,则读取这些输入。 int PQconsumeInput(PGconn *conn); - 通常返回 1 表明没有错误,而返回 0 表明有某种麻烦发生(此时可以用)。 - 注意该结果并不表明是否真正收集了任何输入数据。在调用之后,应用可以检查和/或PQnotifies来看看它们的状态是否改变。 + 通常返回 1,表示没有错误;发生问题时则返回 0(此时可查看 )。注意,返回值并不说明是否实际读取了输入数据。调用 后,应用程序可以检查 和/或 PQnotifies,以确定其状态是否发生变化。 - 即使应用还不准备处理一个结果或通知,也可以被调用。 - 这个函数将读取可用的数 据并且把它保存在一个缓冲区中,从而导致一个select()的读准备好指示消失。 - 因此应用可以使用立即清除select()条件,并且在空闲时再检查结果。 + 即使应用程序尚未准备好处理结果或通知,也可以调用 。此函数会读取可用数据并将其保存在缓冲区中,从而清除 select() 的可读就绪指示。因此,应用程序可以用 立即清除 select() 的就绪条件,随后在合适的时候检查结果。 @@ -3895,15 +3752,11 @@ int PQisBusy(PGconn *conn); - + - 一个使用这些函数的典型应用将有一个主循环,在主循环中会使用select()poll()等待所有它必须响应的情况。 - 其中之一将是来自服务器的输入可用,对select()来说意味着标识的文件描述符上有可读的数据。 - 当主循环检测到输入准备好时,它将调用读取输入。 - 然后它可以调用,如果返回假(0)则接着调用。 - 它还可以调用PQnotifies检测NOTIFY消息(见)。 - + 使用这些函数的典型应用程序会在主循环中通过 select()poll() 等待需要响应的各种条件。其中一个条件是服务器有可读取的输入;对于 select(),这意味着 标识的文件描述符上有可读数据。主循环检测到输入就绪时,应调用 读取输入,然后调用 。如果 返回假(0),就可以接着调用 。还可以调用 PQnotifies 检测 NOTIFY 消息(见 )。 + 一个使用/的客户端也可以尝试取消一个正在被服务器处理的命令,见。 @@ -3911,13 +3764,8 @@ int PQisBusy(PGconn *conn); - 通过使用上面描述的函数,可以避免在等待来自数据库服务器的输入时阻塞。 - 然而,应用程序仍然可能会在等待向服务器发送输出时阻塞。 - 这在发送非常长的SQL命令或数据值时可能会发生,尽管这相对不常见。 - (如果应用程序通过COPY IN发送数据,则更有可能发生。) - 为了防止这种可能性并实现完全非阻塞的数据库操作,可以使用以下附加函数。 - - + 使用上述函数可以避免在等待数据库服务器输入时阻塞。不过,应用程序仍可能在等待向服务器发送输出时阻塞。这种情况较少见,但发送很长的 SQL 命令或数据值时可能发生。(如果应用程序通过 COPY IN 发送数据,发生的可能性则大得多。)为了防止这种情况,实现完全非阻塞的数据库操作,可以使用以下附加函数。 + PQsetnonblockingPQsetnonblocking @@ -3935,11 +3783,7 @@ int PQsetnonblocking(PGconn *conn, int arg); - 在非阻塞状态下,成功调用、 - 、 - 不会阻塞; - 它们的更改将存储在本地输出缓冲区中,直到刷新为止。 - 不成功的调用将返回错误,必须重试。 + 在非阻塞状态下,成功调用 不会阻塞;产生的数据保存在本地输出缓冲区中,等待发送。失败的调用会返回错误,必须重试。 @@ -3970,9 +3814,7 @@ int PQisnonblocking(const PGconn *conn); - 尝试将任何排队的输出数据刷新到服务器。如果成功(或发送队列为空),则返回0; - 如果由于某种原因失败,则返回-1;如果尚未能够发送发送队列中的所有数据(只有在连接为非阻塞时才会发生此情况), - 则返回1。 + 尝试将发送队列中的输出数据发送到服务器。成功(或发送队列为空)时返回 0;因某种原因失败时返回 -1;如果尚未能发送队列中的全部数据,则返回 1(这种情况只可能发生在非阻塞连接上)。 int PQflush(PGconn *conn); @@ -3980,15 +3822,11 @@ int PQflush(PGconn *conn); - + - 在一个非阻塞连接上发送任何命令或者数据之后,要调用。 - 如果它返回 1,就要等待套接字变成读准备好或写准备好。如果它变为写准备好,应再次调用。 - 如果它变为读准备好,则应先调用,然后再调用。 - 一直重复直到返回 0(有必要检查读准备好并且用耗尽输入,因为服务器可能阻塞给我们发送数据的尝试,例如 NOTICE 消息,并且在我们读它的数据之前它都不会读我们的数据)。 - 一旦返回 0,应等待套接字变成读准备好并且接着按照上文所述读取响应。 - + 在非阻塞连接上发送命令或数据后,应调用 。如果返回 1,就等待套接字变为可读或可写。套接字可写时,再次调用 ;可读时,先调用 ,再调用 。重复上述步骤,直到 返回 0。(必须检查套接字是否可读,并用 读完输入,因为服务器可能在尝试向客户端发送数据时阻塞,例如发送 NOTICE 消息;在客户端读取这些数据之前,服务器不会读取客户端发送的数据。)当 返回 0 后,等待套接字变为可读,再按前述方法读取响应。 + @@ -4002,29 +3840,26 @@ int PQflush(PGconn *conn); - pipelining - in libpq + 管道化 + 在 libpq 中 - batch mode - in libpq + 批处理模式 + 在 libpq 中 - libpq 管道模式允许应用发送查询而无需读取先前发送查询的结果。 - 利用管道模式的优点,客户端将对服务器等待的更少,因为可以在单个网络事务中发送/接收多个查询/结果。 - + libpq 的管道模式允许应用程序在尚未读取先前查询结果时继续发送查询。多个查询及其结果可以在一次网络交互中发送和接收,从而减少客户端等待服务器的时间。 + - 虽然管道模式提供了显著的性能提升, - 使用管道模式写客户端会更加复杂,因为它涉及到管理一个挂起查询的队列,并查找队列中的哪个结果对应于哪个查询。 - + 管道模式可以显著提升性能,但使用它编写客户端也更复杂,因为需要管理待处理查询队列,并确定每个结果对应队列中的哪个查询。 + - 管道模式通常也会在客户端和服务器上面消耗更多的内存,尽管仔细和积极地管理发送/接收队列可以减轻这种消耗。 - 这适用于连接是否处于阻塞或非阻塞模式。 - + 管道模式通常也会增加客户端和服务器的内存消耗,不过仔细、主动地管理发送和接收队列可以缓解这一问题。无论连接处于阻塞还是非阻塞模式,都是如此。 + 虽然libpq的管道API是在PostgreSQL 14中引入的, @@ -4037,24 +3872,8 @@ int PQflush(PGconn *conn); 使用管道模式 - 要发出管道命令,应用程序必须将连接切换到管道模式, - 可以通过来完成。 - 可以使用来测试管道模式是否激活。 - 在管道模式下,只允许使用扩展查询协议的异步操作, - 不允许包含多个SQL命令的命令字符串,也不允许使用COPY命令。 - 使用同步命令执行函数,如PQfn、 - PQexec、 - PQexecParams、 - PQprepare、 - PQexecPrepared、 - PQdescribePrepared、 - PQdescribePortal, - 都会导致错误。 - 也不允许使用PQsendQuery,因为它使用简单查询协议。 - 一旦所有已分派的命令的结果已被处理,并且 - 结束管道结果已被消耗,应用程序可以通过返回 - 到非管道模式。 - + 要使用管道,应用程序必须通过 将连接切换到管道模式。可用 检查管道模式是否已启用。在管道模式下,只允许使用扩展查询协议的异步操作,不允许命令字符串包含多个 SQL 命令,也不允许 COPY。调用同步命令执行函数,例如 PQfnPQexecPQexecParamsPQpreparePQexecPreparedPQdescribePreparedPQdescribePortal,会导致错误。也不允许使用 PQsendQuery,因为它使用简单查询协议。所有已发送命令的结果及管道结束结果都读取处理完毕后,应用程序便可通过 返回非管道模式。 + @@ -4063,9 +3882,8 @@ int PQflush(PGconn *conn); 如果在阻塞模式下使用,它可能发生客户端/服务器死锁。 - 客户端将阻止尝试发送查询到服务器,但服务器将阻止从它已经处理的查询向客户端发送结果。 - 这只有当客户端在它切换到处理从服务器的输入之前发送足够的查询来填充其输出缓冲区和服务器的接收缓冲区,才会发生这种情况,但很难准确预测何时将发生。 - + 客户端在尝试向服务器发送查询时阻塞,而服务器在尝试将已处理查询的结果发送给客户端时阻塞。只有当客户端在转而处理服务器输入之前,发送了足够多的查询,填满自身的输出缓冲区和服务器的接收缓冲区,才会发生这种情况;但很难准确预测何时会发生。 + @@ -4106,8 +3924,8 @@ int PQflush(PGconn *conn); - PQisBusyPQconsumeInput 等函数在处理管道结果时照常工作。特别地,在管道处理过程中调用 PQisBusy 时,如果到目前为止已发出查询的所有结果均已被消费,则返回 0。 - + PQisBusyPQconsumeInput 等函数在处理管道结果时照常工作。特别地,在管道处理过程中调用 PQisBusy 时,如果到目前为止已发出查询的所有结果均已被读取,则返回 0。 + libpq 不向应用程序提供当前正在处理哪个查询的信息(除了 PQgetResult 返回空指针,表示开始返回下一个查询的结果)。应用程序必须跟踪查询的发送顺序,以便将查询与对应结果关联起来。应用程序通常会使用状态机或 FIFO 队列实现这一点。 @@ -4120,21 +3938,16 @@ int PQflush(PGconn *conn); 错误处理 - 从客户端的视角,在PQresultStatus返回PGRES_FATAL_ERROR之后,管道被标记为中止。 - PQresultStatus将报告一个PGRES_PIPELINE_ABORTED结果,对中止的管道中的每一个剩余的排队操作。 - PQpipelineSync的结果报告为PGRES_PIPELINE_SYNC,以表示中止管道的结束并恢复正常的结果处理。 - + 从客户端的角度看,PQresultStatus 返回 PGRES_FATAL_ERROR 后,管道就会被标记为中止。对于已中止管道中剩余的每个排队操作,PQresultStatus 都会报告一个 PGRES_PIPELINE_ABORTED 结果。PQpipelineSync 的结果报告为 PGRES_PIPELINE_SYNC,表示已中止的管道结束,并恢复正常的结果处理。 + 在错误恢复时,客户端必须 使用 PQgetResult处理结果。 - 如果管道使用隐式事务,那么已经执行的操作将被回滚,而排队跟在失败操作的操作将被完全跳过。 - 同样的行为也会发生,如果管道开始并提交单个显式事务(也就是,第一个语句是BEGIN ,最后一个是COMMIT),除非会话在管道结束时保持在中止事务状态。 - 如果管道包含多个显式事务,所有在错误发生前已提交的事务都会继续保留,当前正在进行的事务会被中止,所有后续操作都会被完全跳过,包括后续事务在内。 - 如果管道同步点发生时显式事务块为中止状态,则下一个管道将立即中止,除非下一个命令使用ROLLBACK将事务置于正常模式。 - + 如果管道使用隐式事务,已经执行的操作会被回滚,而失败操作之后排队的操作会全部跳过。如果管道开始并提交单个显式事务(即第一条语句为 BEGIN,最后一条为 COMMIT),行为也相同,不过在管道结束时,会话仍处于事务中止状态。如果管道包含多个显式事务,错误发生前已经提交的事务仍保持已提交状态,当前正在进行的事务会中止,所有后续操作都会被跳过,包括后续事务。如果到达管道同步点时,显式事务块仍处于中止状态,下一个管道会立即中止,除非下一条命令使用 ROLLBACK 将事务恢复为正常状态。 + @@ -4147,24 +3960,19 @@ int PQflush(PGconn *conn); - 交叉结果处理和查询分派 + 交错处理结果与发送查询 - 为避免大型管道上的死锁,客户端将被围绕非阻塞事件循环构建,通过使用操作系统工具,如select, poll, WaitForMultipleObjectEx等等, - + 为避免大型管道发生死锁,客户端应围绕非阻塞事件循环组织,使用 selectpollWaitForMultipleObjectEx 等操作系统机制。 + - 客户端应用通常应该维护一个尚未分派的工作队列和一个已分派但尚未处理结果的工作队列。 - 当套接字是可写时,它将可以分派更多的工作。 - 当套接字是可读时,它将读取结果并处理它们,将它们匹配到相应结果队列中的下一个条目。 - 基于可用内存,来自套接字的结果将被经常读取:这里不需要等到管道结束才读取结果。 - 管道将范围涵盖到工作的逻辑单元,通常(但不是必然)每个管道一个事务。 - 在管道之间,不需要退出管道模式再重新进入管道模式,也不需要等待一个管道结束后再发送下一个。 - + 客户端应用程序通常应维护两个队列:一个存放尚未发送的工作,另一个存放已经发送但尚未处理结果的工作。套接字可写时,应继续发送工作;套接字可读时,应读取并处理结果,将其与相应结果队列中的下一个条目匹配。应根据可用内存情况,频繁地从套接字读取结果,无需等到管道结束。每个管道应对应一个逻辑工作单元,通常是一个事务,但并非必须如此。管道之间无需退出再重新进入管道模式,也无需等待一个管道完成后才发送下一个。 + - 一个使用select()和一个简单状态机来跟踪发送和接收工作的示例,在PostgreSQL源代码发行版的src/test/modules/libpq_pipeline/libpq_pipeline.c文件中。 - + PostgreSQL 源代码发行版的 src/test/modules/libpq_pipeline/libpq_pipeline.c 中提供了一个示例,使用 select() 和简单状态机跟踪已发送和已接收的工作。 + @@ -4208,7 +4016,7 @@ PGpipelineStatus PQpipelineStatus(const PGconn *conn); - libpq 连接 是管道模式。 + libpq 连接处于管道模式。 @@ -4237,18 +4045,14 @@ PGpipelineStatus PQpipelineStatus(const PGconn *conn); - 造成连接进入管道模式,如果它当前空闲或已经是管道模式。 - + 如果连接当前空闲或已处于管道模式,则使该连接进入管道模式。 int PQenterPipelineMode(PGconn *conn); - - 成功返回1. - 如果连接当前不是空闲的,返回0并且无影响,也就是说,它已经有了一个结果,或者它正在等待服务器的更多输入,等等。 - 这个函数实际上不向服务器发送任何东西,它只是更改libpq连接状态。 + 成功时返回 1。如果连接当前不空闲,例如已有结果可供读取,或正在等待服务器的更多输入,则返回 0,且不产生任何影响。此函数实际上不向服务器发送任何内容,只改变 libpq 的连接状态。 @@ -4260,16 +4064,14 @@ int PQenterPipelineMode(PGconn *conn); - 造成连接退出管道模式,如果连接当前以空队列处于管道模式,并且没有待处理的结果。 + 如果连接当前处于管道模式、队列为空且没有待读取的结果,则使该连接退出管道模式。 int PQexitPipelineMode(PGconn *conn); - 成功则返回1。 - 如果不是管道模式,则返回1并且不采取操作。 - 如果当前语句没有完成处理,或者PQgetResult尚未被调用以收集所有先前发送查询的结果,则返回0(在这种情况下,使用以获取关于故障的更多信息)。 + 成功时返回 1。如果连接不处于管道模式,也返回 1,且不执行任何操作。如果当前语句尚未处理完毕,或尚未调用 PQgetResult 读取先前发送的所有查询的结果,则返回 0(此时可使用 获取更多失败信息)。 @@ -4281,17 +4083,14 @@ int PQexitPipelineMode(PGconn *conn); - 通过发送sync message并刷新发送缓冲区的方式来标记管道中的同步点。 - 它用作隐式事务的定界符和错误恢复点;参见。 - + 通过发送同步消息并将发送缓冲区中的数据发往服务器,在管道中标记同步点。同步点作为隐式事务的分界符和错误恢复点;见 int PQpipelineSync(PGconn *conn); - 成功就返回1。 - 如果连接不是管道模式或者发送sync message失败,则返回0。 + 成功时返回 1。如果连接不处于管道模式,或发送同步消息失败,则返回 0。 @@ -4305,21 +4104,19 @@ int PQpipelineSync(PGconn *conn); - 发送一个请求到服务器以刷新它的输出缓冲区。 + 请求服务器发送其输出缓冲区中的数据。 int PQsendFlushRequest(PGconn *conn); - + - 成功就返回1。 - 任何失败则返回0。 - + 成功时返回 1;发生任何失败时返回 0。 + - 当PQpipelineSync被调用的结果,或者在非管道模式下的任何请求时,服务器自动刷新它的输出缓冲区;这个函数用于使得服务器在不建立同步点的情况下以管道模式刷新其输出缓冲区。 - 请注意,请求不是自身能自动刷新到服务器;如果需要时使用PQflush。 - + 调用 PQpipelineSync 后,或者在非管道模式下收到任何请求时,服务器都会自动发送其输出缓冲区中的数据。此函数可让服务器在管道模式下发送输出缓冲区中的数据,而不建立同步点。注意,该请求本身不会自动发送到服务器;必要时可使用 PQflush。 + @@ -4330,43 +4127,36 @@ int PQsendFlushRequest(PGconn *conn); 何时使用管道模式 - 非常像异步查询模式,在使用管道模式时没有明显的性能开销。 - 它增加了客户端应用的复杂性,并且需要特别注意以防止客户端/服务器死锁。 - 但是管道模式可以提供相当大的性能改进,代价是因为状态保留更久而增加内存使用。 - + 与异步查询模式类似,使用管道模式不会带来明显的性能开销。它增加了客户端应用程序的复杂性,需要格外注意防止客户端与服务器之间的死锁,但也能显著提升性能,代价是状态保留更久,因而占用更多内存。 + - 当服务器比较远,即网络延迟(ping time)高的时候,管道模式最有用,以及在许多小操作正在快速连续执行的时候。 - 当每个查询的执行时间是客户端/服务器往返时间的许多倍时,使用管道命令的优势通常会更少。 - 不用管道模式,在往返时间为300毫秒的服务器上运行一个100条语句的操作,仅网络延迟就需要30秒;使用管道,等待来自服务器的结果可能只消耗仅仅0.3秒。 - + 当服务器距离较远,即网络延迟(ping 时间)较高,或者需要快速连续执行许多小操作时,管道模式最有用。如果每个查询的执行时间是客户端与服务器往返时间的许多倍,使用管道命令的收益通常较小。在往返时间为 300 毫秒的服务器上执行一个包含 100 条语句的操作,不使用管道时,仅网络延迟就需要 30 秒;使用管道时,等待服务器结果的时间可能低至 0.3 秒。 + - 当你的应用需要完成很多小的INSERT, UPDATEDELETE 操作,并且不能方便的转换到集合操作或者 COPY操作时,用管道命令。 - + 如果应用程序需要执行大量小型 INSERTUPDATEDELETE 操作,而这些操作又难以转换为集合操作或 COPY 操作,就可以使用管道命令。 + - 当来自一个操作的信息需要客户端产生下一个操作时,管道模式是没有用的。 - 在这种情况下,客户机将不得不引入一个同步点,并等待完整的客户端/服务器往返以获取它需要的结果。 - 但是,通常可以调整客户端设计以交换服务器端所需的信息。 - 读-修改-写循环是非常好的选择;例如: + 如果客户端必须获得前一个操作的信息,才能生成下一个操作,管道模式就没有帮助。在这种情况下,客户端必须引入同步点,并等待一次完整的客户端与服务器往返,才能获得所需结果。不过,通常可以调整客户端设计,让所需信息在服务器端交换。读取、修改、写入的循环尤其适合这样改进。例如: BEGIN; SELECT x FROM mytable WHERE id = 42 FOR UPDATE; --- result: x=2 --- client adds 1 to x: +-- 结果:x=2 +-- 客户端将 x 加 1: UPDATE mytable SET x = 3 WHERE id = 42; COMMIT; - 可以更有效地开展以下工作: +可以改写为以下效率更高的操作: UPDATE mytable SET x = x + 1 WHERE id = 42; - + - 当单个管道包含多个事务时,管道的作用更小,而且更复杂(参见)。 - + 当单个管道包含多个事务时,使用管道的收益较小,复杂度也更高(见 )。 + @@ -4399,7 +4189,7 @@ int PQsetSingleRowMode(PGconn *conn); - 此函数只能在调用或其某个兄弟函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活单行模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 + 此函数只能在调用或其某个同类函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活单行模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 @@ -4485,7 +4275,7 @@ int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize); - 的一个已废弃变体。 + 的一个已弃用变体。 int PQrequestCancel(PGconn *conn); @@ -4506,7 +4296,7 @@ int PQrequestCancel(PGconn *conn); 快速路径接口 - fast path + 快速路径 @@ -4516,8 +4306,8 @@ int PQrequestCancel(PGconn *conn); - 这个接口不安全,不应使用。当result_is_int被设置为0时,PQfn可能会在result_buf末尾之外写入数据,而不管缓冲区是否有足够空间容纳所请求的字节数。此外,它已经废弃,因为可以通过创建一个定义该函数调用的预备语句来达到类似的性能并获得更强大的功能。然后,用参数和结果的二进制传输执行该语句,从而取代快速路径函数调用。 - + 此接口不安全,不应使用。当 result_is_int 设为 0 时,PQfn 可能越过 result_buf 的末尾写入数据,无论缓冲区是否有足够空间容纳请求的字节数。此外,此接口已经过时:可以通过创建预备语句来定义函数调用,获得相近的性能和更强的功能;再以二进制形式传输参数和结果来执行该语句,即可替代快速路径函数调用。 + @@ -4545,27 +4335,24 @@ typedef struct - fnid参数是要被执行的函数的 OID。argsnargs定义了要传递给函数的参数;它们必须匹配已声明的函数参数列表。当一个参数结构体的isint域为真时,u.integer值被以指定长度(必须是 1、2 或者 4 字节)整数的形式发送给服务器;这时候会发生恰当的字节交换。当isint为假时,*u.ptr中指定数量的字节将不做任何处理被发送出去;这些数据必须是服务器 预期的用于该函数参数数据类型的二进制传输的格式(由于历史原因u.ptr被声明为类型int *,其实把它考虑成void *会更好)。result_buf是放置该函数返回值的缓冲区。调用者必须已经分配了足够的空间来存储返回值(这里没有检查!)。实际的结果长度将被放在result_len指向的整数中返回。如果预期结果是 2 或 4 字节整数,把result_is_int设为 1;否则设为 0。把result_is_int设为 1 导致libpq在必要时对值进行交换字节,这样它就作为对客户端机器正确的int值被传输,注意对任一种允许的结果大小都会传递一个 4 字节到*result_buf。当result_is_int是 0 时,服务器发送的二进制格式字节将不做修改直接返回(在这种情况下,把result_buf考虑为类型void *更好)。 - + fnid 参数是要执行函数的 OID。argsnargs 指定传给函数的参数,必须与函数声明中的参数列表匹配。参数结构体的 isint 字段为真时,u.integer 值会以指定长度的整数发送到服务器,该长度必须是 2 或 4 字节,并会进行适当的字节序转换。isint 为假时,位于 *u.ptr 的指定数量字节会原样发送;数据必须符合服务器对该函数参数数据类型的二进制传输格式要求。(将 u.ptr 声明为 int * 是历史原因;将其视为 void * 更合适。)result_buf 指向用于存放函数返回值的缓冲区。调用者必须事先分配足够空间来保存返回值,这里不会检查!实际结果长度以字节为单位,返回到 result_len 指向的整数中。如果预期结果是 2 或 4 字节整数,将 result_is_int 设为 1,否则设为 0。将 result_is_int 设为 1 后,libpq 会按需转换字节序,使结果成为适合客户端机器的 int 值;注意,无论是哪种允许的结果大小,传入 *result_buf 的都是 4 字节整数。result_is_int 为 0 时,服务器发送的二进制格式字节串会原样返回。(此时,将 result_buf 视为 void * 更合适。) + - PQfn总是返回一个有效的PGresult指针,包括状态PGRES_COMMAND_OK 表示成功或者PGRES_FATAL_ERROR在出现什么问题时。 - 在使用结果之前应该检查结果状态。 - 当结果不再使用后,调用者有义务使用释放PGresult。 - + PQfn 总是返回有效的 PGresult 指针:成功时状态为 PGRES_COMMAND_OK,遇到问题时为 PGRES_FATAL_ERROR。使用结果前应检查其状态。不再需要结果时,调用者负责使用 释放 PGresult。 + - 要传递NULL参数到函数,将参数结构体的len字段设置为-1isintu 字段就不相关了。 - + 要向函数传入 NULL 参数,将该参数结构体的 len 字段设为 -1;此时,isintu 字段便不再相关。 + - 如果函数返回 NULL, *result_len 被设置为 -1, 并且 *result_buf 不调整。 - + 如果函数返回 NULL,则将 *result_len 设为 -1,而不修改 *result_buf。 + - 注意在使用此接口时,不能够处理集-值结果。 - 此外,函数必须是一个普通函数,而不是聚合、窗口函数或过程。 - + 注意,使用此接口时无法处理集合值结果。此外,函数必须是普通函数,不能是聚合函数、窗口函数或过程。 + @@ -4575,7 +4362,7 @@ typedef struct NOTIFY - in libpq + 在 libpq 中 @@ -4584,39 +4371,36 @@ typedef struct libpq应用把LISTENUNLISTENNOTIFY命令作为普通 SQL 命令提交。 - 随后通过调用PQnotifies.PQnotifies来检测NOTIFY消息的到达。 + 随后通过调用PQnotifiesPQnotifies来检测NOTIFY消息的到达。 - 函数PQnotifies从服务器发来的未处理通知消息列表中返回下一条通知。如果没有待处理通知,则返回空指针。一旦PQnotifies返回一条通知,该通知就被视为已处理,并会从通知列表中删除。 - + 函数 PQnotifies 从已收到但尚未处理的服务器通知消息列表中返回下一条通知。没有待处理通知时返回空指针。一旦 PQnotifies 返回一条通知,该通知就被视为已处理,并从通知列表中移除。 PGnotify *PQnotifies(PGconn *conn); typedef struct pgNotify { - char *relname; /* notification channel name */ - int be_pid; /* process ID of notifying server process */ - char *extra; /* notification payload string */ + char *relname; /* 通知通道名称 */ + int be_pid; /* 发送通知的服务器进程 ID */ + char *extra; /* 通知载荷字符串 */ } PGnotify; - - 在处理完PQnotifies返回的PGnotify对象后,别忘了用把它释放。 - 释放PGnotify指针本身就足够了;relnameextra域并不表示独立分配的内存(这些域名是历史遗留的,尤其是通道名称与关系名称并无关联)。 - +处理完 PQnotifies 返回的 PGnotify 对象后,务必使用 释放它。只需释放 PGnotify 指针;relnameextra 字段并非独立分配。(这些字段名称是历史遗留的;尤其是,通道名称与关系名称不必有任何关联。) + 给出了一个示例程序展示异步通知的使用。 - PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数吸收的消息。 + PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数读取的消息。 在较早版本的libpq中,及时收到NOTIFY消息的唯一方法是不断提交命令,哪怕是空命令,然后在每次后检查PQnotifies。 - 虽然这种方法仍然有效,但由于效率过低,现已废弃。 + 虽然这种方法仍然有效,但由于浪费处理能力,现已弃用。 - 当你没有可用的命令提交时,一种更好的检查NOTIFY消息的方法是调用,然后检查PQnotifies。 + 当没有需要执行的实际命令时,一种更好的检查NOTIFY消息的方法是调用,然后检查PQnotifies。 你可以使用select()等待服务器数据到达,这样在无事可做时就不会浪费CPU资源(参见以获得可传给select()的文件描述符)。 注意不管是用/提交命令还是简单地使用,这种方法都能正常工作。 不过,你应该记住在每次之后检查PQnotifies,看看在命令的处理过程中是否有通知到达。 @@ -4630,20 +4414,16 @@ typedef struct pgNotify COPY - with libpq + 使用 libpq - PostgreSQL中的COPY命令有用于libpq的对网络连接读出或者写入的选项。这一节描述的函数允许应用通过提供或者消耗已拷贝的数据来充分利用这个功能。 - + PostgreSQLCOPY 命令提供了选项,可以通过 libpq 使用的网络连接读取或写入数据。本节介绍的函数允许应用程序通过提供或接收复制数据来使用这一能力。 + - 整个处理是应用首先通过或者一个等效的函数发出 SQL COPY命令。 - 对这个命令的响应(如果命令无误)将是一个状态代码是PGRES_COPY_OUT或 者PGRES_COPY_IN(取决于指定的拷贝方向)的PGresult对象。 - 应用然后就应该使用这一节的函数接收或者传送数据行。在数据传输结束之后,另外一个PGresult对象会被返回以表明传输的成功或者失败。 - 它的状态将是:PGRES_COMMAND_OK表示成功,PGRES_FATAL_ERROR表示发生了一些问题。 - 此时我们可以通过发出进一步的 SQL 命令(在COPY操作的处理过程中,不能用同一个连接执行其它 SQL 命令)。 - + 整体流程如下:应用程序先通过 或等效函数发出 SQL COPY 命令。如果命令没有错误,响应就是一个 PGresult 对象,其状态码为 PGRES_COPY_OUTPGRES_COPY_IN,取决于指定的复制方向。应用程序随后应使用本节函数接收或发送数据行。数据传输完成后,会返回另一个 PGresult 对象,表示传输成功或失败:成功时状态为 PGRES_COMMAND_OK,出现问题时为 PGRES_FATAL_ERROR。此时可以通过 继续发出 SQL 命令。(COPY 操作进行期间,不能在同一连接上执行其他 SQL 命令。) + 如果一个COPY命令是通过在一个可能包含额外命令的字符串中发出的,那么应用在完成COPY序列之后必须继续用取得结果。 @@ -4651,17 +4431,15 @@ typedef struct pgNotify - 这一节的函数应该只在从获得了PGRES_COPY_OUTPGRES_COPY_IN结果状态的后执行。 - + 只有从 获得 PGRES_COPY_OUTPGRES_COPY_IN 结果状态后,才应调用本节函数。 + - 一个PGresult对象具有这些状态值之一,携带有关COPY操作开始的一些附加数据。 - 可以使用与查询结果相关的函数来获取这些附加数据: - - + 带有上述某个状态值的 PGresult 对象,还会携带关于即将开始的 COPY 操作的附加数据。这些数据可以通过下列函数获取,这些函数也用于查询结果: + PQnfieldsPQnfieldswith COPY + >PQnfields用于 COPY @@ -4672,7 +4450,7 @@ typedef struct pgNotify PQbinaryTuplesPQbinaryTupleswith COPY + >PQbinaryTuples用于 COPY @@ -4684,7 +4462,7 @@ typedef struct pgNotify PQfformatPQfformatwith COPY + >PQfformat用于 COPY @@ -4696,15 +4474,15 @@ typedef struct pgNotify - + 用于发送<command>COPY</command>数据的函数 - 这些函数用于在COPY FROM STDIN期间发送数据。如果在连接不是COPY_IN状态,调用它们会失败。 - + 这些函数用于在 COPY FROM STDIN 期间发送数据。如果连接不处于 COPY_IN 状态,调用它们会失败。 + @@ -4723,12 +4501,11 @@ int PQputCopyData(PGconn *conn, - 传输指定buffer中长度为nbytesCOPY数据到服务器。 - 如果数据被放在队列中,结果是 1;如果因为缓冲区满而无法被放在队列中(只可能发生在连接是非阻塞模式时),那么结果是零;如果发生错误,结果为 -1(如果返回值为 -1,那么使用检索细节。如果值是零,那么等待写准备好然后重试)。 + 将指定 buffer 中长度为 nbytesCOPY 数据传输到服务器。数据成功加入队列时返回 1;因缓冲区已满而无法加入队列时返回零(仅可能发生在非阻塞模式下);发生错误时返回 -1。(返回 -1 时,可用 获取详细信息。返回零时,应等待可写就绪后重试。) - 应用可以把COPY数据流划分成任意方便的大小放到缓冲区中。在发送时,缓冲区载荷的边界没有什么语意。数据流的内容必须匹配COPY命令预期的数据格式;详见。 + 应用程序可以将 COPY 数据流分成任意方便大小的数据块,逐块装入缓冲区。发送时,这些数据块的边界没有语义含义。数据流内容必须符合 COPY 命令预期的数据格式;详见 @@ -4748,21 +4525,15 @@ int PQputCopyEnd(PGconn *conn, - 如果errormsgNULL,则成功结束COPY_IN操作。 - 如果errormsg不是NULLCOPY被强制失败,errormsg指向的字符串是错误消息。 - (不过,我们不应假定这个准确的错误信息将会从服务器传回,因为服务器可能已经因为其自身原因导致COPY失败。)。 + 如果 errormsgNULL,则成功结束 COPY_IN 操作。如果 errormsg 不为 NULL,则强制 COPY 失败,并将 errormsg 指向的字符串用作错误消息。(但不应假定服务器一定会返回这条完全相同的错误消息,因为服务器可能已经因自身原因使 COPY 失败。) - 如果终止消息被发送,则结果为 1;在非阻塞模式中,结果为 1 也可能只表示终止消息被成功地放在了发送队列中 - (在非阻塞模式中,要确认数据确实被发送出去,你应该接着等待写准备好并且调用,重复这些直到返回零)。 - 零表示该函数由于缓冲区满而无法将该终止消息放在队列中,这只会发生在非阻塞模式中(在这种情况下,等待写准备好并且再次尝试调用)。 - 如果发生系统错误,则返回 -1,可以使用检索详情。 + 终止消息已发送时返回 1;在非阻塞模式下,返回 1 也可能仅表示该消息已成功加入发送队列。(在非阻塞模式下,要确认数据已经发送,应接着等待可写就绪并调用 ,反复执行直到返回零。)返回零表示缓冲区已满,无法将终止消息加入队列;这种情况仅可能发生在非阻塞模式下。(此时,应等待可写就绪,再次调用 。)发生严重错误时返回 -1,可用 获取详细信息。 - 在成功调用之后,调用获取COPY命令的最终结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 成功调用 后,调用 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -4795,29 +4566,19 @@ int PQgetCopyData(PGconn *conn, - 在一个COPY期间尝试从服务器获取另外一行数据。数据总是以每次一个数据行的方式被返回;如果只有一个部分行可用,那么它不会被返回。 - 成功返回一个数据行涉及到分配一块内存来保存该数据。buffer参数必须为非NULL。 - *buffer被设置为指向分配到的内存的指针,或者是在没有返回缓冲区的情况下指向NULL。 - 一个非NULL的结果缓冲区在不需要时必须用释放。 + 在 COPY 期间尝试从服务器获取下一行数据。每次总是返回一个完整数据行;如果只有部分行可用,则不返回。成功返回数据行时,会分配一块内存保存数据。buffer 参数必须为非 NULL*buffer 会被设置为指向所分配的内存;如果没有返回缓冲区,则设为 NULL。非 NULL 的结果缓冲区在不再需要时应使用 释放。 - 在成功返回一行之后,返回的值就是该数据行里数据的字节数(将是大于零)。 - 被返回的字符串总是空终止的,虽然这可能只是对文本COPY有用。 - 一个零结果表示该COPY仍然在处理中,但是还没有可用的行(只在async为真时才可能)。 - 一个 -1 结果表示COPY已经完成。-2 结果表示发生了错误(参考获取原因)。 + 成功返回一行时,返回值是该行的数据字节数,始终大于零。返回的字符串总是以零字节结尾,不过这可能仅对文本 COPY 有用。返回零表示 COPY 仍在进行,但尚无可用行(仅在 async 为真时可能发生)。返回 -1 表示 COPY 已完成;返回 -2 表示发生了错误(可用 查看原因)。 - 当async为真时(非零),将不会阻塞等待输入; - 如果COPY仍在处理过程中并且没有可用的完整行,那么它将返回零 - (在这种情况下等待读准备好,然后在再次调用之前,调用)。 - 当async为假(零)时,将阻塞,直到数据可用或者操作完成。 + 当 async 为真(非零)时, 不会阻塞等待输入;如果 COPY 仍在进行,但没有完整行可用,则返回零。(此时,应等待读就绪,先调用 ,再调用 。)当 async 为假(零)时, 会阻塞,直到数据可用或操作完成。 - 在返回 -1 之后,调用获取COPY命令的最后结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 在 返回 -1 后,调用 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -4827,11 +4588,11 @@ int PQgetCopyData(PGconn *conn, - 用于<command>COPY</command>的废弃函数 + 用于<command>COPY</command>的过时函数 - 这些函数代表了以前的处理COPY的方法。尽管它们还能用,但是现在已经被废弃,因为它们的错误处理很糟糕、检测结束数据的方法也不方便,并且缺少对二进制或非阻塞传输的支持。 - + 这些函数使用较旧的方式处理 COPY。虽然仍然可用,但由于错误处理欠佳、检测数据结束的方式不便,而且缺少对二进制或非阻塞传输的支持,已被弃用。 + @@ -4841,7 +4602,7 @@ int PQgetCopyData(PGconn *conn, - 读取一个以新行终止的字符行到(由服务器传输) 到一个长度为length的字符串缓冲区。 + 将服务器传来的、以换行符结尾的一行字符读入大小为 length 的字符串缓冲区。 int PQgetline(PGconn *conn, char *buffer, @@ -4850,12 +4611,11 @@ int PQgetline(PGconn *conn, - 这个函数拷贝最多length-1 个字符到该缓冲区中,并且把终止的新行转换成一个零字节。 - 在输入结束时返回EOF,如果整行都被读取则返回 0,如果缓冲区填满了而还没有遇到结束的新行则返回 1。 - + 此函数最多将 length-1 个字符复制到缓冲区,并将末尾的换行符转换为零字节。 在输入结束时返回 EOF,读完一整行时返回 0,缓冲区已满但尚未读到末尾换行符时返回 1。 + - 注意,应用必须检查是否一个新行包含两个字符\.,这表明服务器 已经完成了COPY命令的结果发送。如果应用可能收到超过length-1 字符长的行, 我们就应该确保正确识别\.行(例如,不要把一个长数据行的结束当作一个终止行)。 + 注意,应用程序必须检查新读入的一行是否仅由 \. 两个字符组成,这表示服务器已发送完 COPY 命令的结果。如果可能收到长度超过 length-1 个字符的行,必须确保正确识别 \. 行,例如不能把长数据行的末尾误当作终止行。 @@ -4867,7 +4627,7 @@ int PQgetline(PGconn *conn, - 不阻塞地读取一行COPY数据(由服务器传输)到一个缓冲区中。 + 以非阻塞方式将服务器传来的一行 COPY 数据读入缓冲区。 int PQgetlineAsync(PGconn *conn, char *buffer, @@ -4876,23 +4636,19 @@ int PQgetlineAsync(PGconn *conn, - 这个函数类似于,但是可以被用于那些必须异步读取COPY数据的应用, 也就是不阻塞的应用。 - 在发出了COPY命令并得到了PGRES_COPY_OUT响应之后, - 应用应该调用直到检测到结束数据的信号。 - + 此函数类似于 ,但可用于必须异步读取 COPY 数据的应用程序,即读取时不阻塞。发出 COPY 命令并收到 PGRES_COPY_OUT 响应后,应用程序应调用 ,直到检测到数据结束信号。 + - 不像,这个函数负责检测结束数据。 + 与 不同,此函数会负责检测数据结束。 - 在每次调用时,如果libpq的输入缓冲区中有一个完整的数据行可用,都将返回数据。 - 否则,在剩余行到达之前不会返回数据。如果识别到拷贝数据结束的标志,此函数返回 -1;如果没有可用数据则返回 0; - 或者是给出一个正数给出被返回的字节数。如果返回 -1,调用者下一步必须调用,然后回到正常处理。 + 每次调用时,如果 libpq 的输入缓冲区中有完整数据行, 就会返回数据;否则,要等该行剩余部分到达后才返回数据。识别到复制数据结束标记时返回 -1,没有可用数据时返回 0,否则返回正数,表示返回的数据字节数。返回 -1 后,调用者必须接着调用 ,然后恢复正常处理。 - 返回的数据将不超过一个数据行的范围。如果可能,每次将返回一个完整行。但如果调用者提供的缓冲区太小不足以容下服务器发送的行,那么将返回部分行。对于文本数据,这可以通过测试返回的最后一个字节是否\n来检测(在二进制COPY中, 需要对COPY数据格式进行实际的分析,以便做相同的判断)。被返回的字符串不是空结尾的(如果你想增加一个终止空,确保传递一个比实际可用空间少一字节的bufsize)。 + 返回的数据不会跨越数据行边界。只要可能,每次就返回一整行;但如果调用者提供的缓冲区太小,容不下服务器发送的一行,则只返回部分行。对于文本数据,可检查最后返回的字节是否为 \n,以判断是否返回了完整行。(对于二进制 COPY,则必须实际解析 COPY 数据格式才能作出相同判断。)返回的字符串不以零字节结尾。(如果要自行添加末尾的零字节,务必将传入的 bufsize 设置为比实际可用空间少一字节。) @@ -4904,7 +4660,7 @@ int PQgetlineAsync(PGconn *conn, - 向服务器发送一个空终止的字符串。如果 OK 则返回 0;如果不能发送字符串则返回EOF。 + 向服务器发送以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputline(PGconn *conn, const char *string); @@ -4912,17 +4668,14 @@ int PQputline(PGconn *conn, - 一系列调用发送的COPY数据流和返回的数据具有相同的格式, - 只是应用不需要每次调用中发送刚好一个数据行;在每次调用中发送多行或者部分行都是可以的。 + 连续调用 发送的 COPY 数据流,与 返回的数据格式相同。不过,应用程序不必在每次 调用中恰好发送一个数据行;每次发送部分行或多行也可以。 - 在PostgreSQL协议 3.0 之前,应用必须显式地发送两个字符\.作为最后一行来指示服务器已经完成发送COPY数据。 - 虽然这么做仍然有效,但是它已经被废弃并且\.的特殊含义可能在将来的版本中删除。 - 在发送完实际数据之后, 调用就足够了。 - + 在 PostgreSQL 协议 3.0 之前,应用程序必须显式发送由 \. 两个字符组成的最后一行,告知服务器应用程序已发送完 COPY 数据。虽然这种方式仍然有效,但已被弃用,\. 的特殊含义预计会在未来版本中移除。发送完实际数据后,调用 即可。 + @@ -4934,7 +4687,7 @@ int PQputline(PGconn *conn, - 向服务器发送一个非空终止的字符串。如果 OK 则返回 0,如果不能发送字符串则返回EOF。 + 向服务器发送不以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputnbytes(PGconn *conn, const char *buffer, @@ -4943,7 +4696,7 @@ int PQputnbytes(PGconn *conn, - 这个函数类似,除了数据缓冲区不需要是空终止,因为要发送的字节数是直接指定的。在发送二进制数据时使用这个过程。 + 此函数与 完全相同,只是直接指定了要发送的字节数,因此数据缓冲区不必以零字节结尾。发送二进制数据时可使用此函数。 @@ -4959,15 +4712,11 @@ int PQputnbytes(PGconn *conn, int PQendcopy(PGconn *conn); - 这个函数等待服务器完成拷贝。当最后一个字符串已经用发送给服务器时或者当最后一个字符串已经用PQgetline从服务器接收到时,就会发出这个函数。 - 这个函数必须被发出,否则服务器将会和客户端不同步。从这个函数返回后,服务器就已经准备好接收下一个 SQL 命令了。函数成功完成时返回值为 0,否则返回非零值(如果返回值为非零值,用检索详情)。 +此函数会等待服务器完成复制。应在使用 向服务器发送最后一个字符串后,或使用 PQgetline 从服务器接收最后一个字符串后调用它。必须调用此函数,否则服务器与客户端会失去同步。函数返回后,服务器便准备好接收下一条 SQL 命令。成功完成时返回 0,否则返回非零值。(返回非零值时,可用 获取详细信息。) - 在使用时,应用应该通过反复调用并且在看到终止行后调用来响应PGRES_COPY_OUT结果。 - 然后它应该返回到循环直到返回一个空指针。 - 类似地,PGRES_COPY_IN结果会用一系列加上之后的来处理,然后返 回到循环。 - 这样的安排将保证嵌入到一系列SQL命令中的COPY命令将被正确执行。 + 使用 时,收到 PGRES_COPY_OUT 结果后,应用程序应反复调用 ,并在看到终止行后调用 。随后应回到 循环,直到 返回空指针。类似地,收到 PGRES_COPY_IN 结果后,应连续调用 ,再调用 ,然后回到 循环。这样可以保证嵌在一系列 SQL 命令中的 COPY 命令正确执行。 @@ -4987,8 +4736,8 @@ int PQendcopy(PGconn *conn); 控制函数 - 这些函数控制libpq行为各种各样的细节。 - + 这些函数控制 libpq 行为的各种细节。 + @@ -4998,17 +4747,15 @@ int PQendcopy(PGconn *conn); - 返回客户端编码。 + 返回客户端编码。 int PQclientEncoding(const PGconn *conn); - - 请注意,它返回的是编码 ID,而不是一个符号串字符串,如EUC_JP。如果不成功,它会返回 -1。要把一个编码 ID 转换为为一个编码名称,可以用: - +注意,返回的是编码 ID,而不是 EUC_JP 这样的符号字符串。失败时返回 -1。要将编码 ID 转换为编码名称,可以使用: char *pg_encoding_to_char(int encoding_id); - + @@ -5018,14 +4765,11 @@ char *pg_encoding_to_char(int encoding_id); - - 设置客户端编码。 - + 设置客户端编码。 int PQsetClientEncoding(PGconn *conn, const char *encoding); - conn是一个到服务器的连接,而encoding是你想使用的编码。 - 如果函数成功地设置编码,则返回 0,否则返回 -1。这个连接的当前编码可以使用确定。 + conn是到服务器的连接,而encoding是要使用的编码。如果成功设置编码,函数返回 0,否则返回 -1。此连接的当前编码可以通过以下函数确定: @@ -5037,7 +4781,7 @@ int PQsetClientEncoding(PGconn *conn, const char * - 决定返回的消息的细节程度。 + 设置 所返回消息的详细程度。 typedef enum { @@ -5049,19 +4793,12 @@ typedef enum PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); - - 设置细节模式,并返回该连接的前一个设置。 - 在TERSE模式下,返回的消息只包括严重性、主要文本以及位置;这些东西通常放在一个单一行中。 - DEFAULT模式生成的消息包括上面的信息加上任何细节、提示或者上下文域(这些可能跨越多行)。 - VERBOSE模式包括所有可以可用的域。修改细节模式不会影响来自已有PGresult对象中的可用消息。 - 只有随后创建的PGresult对象才受到影响。 - SQLSTATE模式仅包括错误严重性和SQLSTATE错误代码,如果其中之一是可用的(如果没有,输出类似于TERSE模式)。 - + 设置详细程度模式,并返回该连接先前的设置。在 TERSE 模式下,返回的消息只包含严重级别、主要文本和位置;通常一行就能容纳。DEFAULT 模式生成的消息除上述内容外,还包含所有详细信息、提示或上下文字段(这些内容可能跨越多行)。VERBOSE 模式包含所有可用字段。SQLSTATE 模式仅包含错误严重级别,以及可用时的 SQLSTATE 错误代码(如果没有错误代码,则输出与 TERSE 模式相同)。 + - 更改详细程度设置不会影响已存在的PGresult对象的可用的消息,只会影响随后创建的对象。 - (如果想要用不同的详细程度打印之前的错误,请见 ) - + 更改详细程度设置不会影响从既有 PGresult 对象中取得的消息,只影响随后创建的对象。(如果希望以不同的详细程度打印之前的错误,请参见 。) + @@ -5072,7 +4809,7 @@ PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); - 决定如何处理返回的消息中的CONTEXT域。 + 确定 所返回消息中 CONTEXT 字段的处理方式。 typedef enum { @@ -5083,18 +4820,12 @@ typedef enum PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibility show_context); - - 设置上下文显示模式,返回该连接上之前的设置。 - 这个模式控制消息中是否包括CONTEXT域。 - NEVER模式不会包括CONTEXT,而ALWAYS则尽可能地包括这个域。 - 在ERRORS模式(默认)中,只在错误消息中包括CONTEXT域,而在通知和警告消息中不会包括。 - (但是,如果详细程度设置为 TERSESQLSTATE,则无论上下文显示模式如何,都会省略CONTEXT字段。) - + 设置上下文显示模式,并返回连接先前的设置。此模式控制消息中是否包含 CONTEXT 字段。NEVER 模式从不包含 CONTEXT,而 ALWAYS 模式在该字段可用时总是包含它。在 ERRORS 模式(默认)下,CONTEXT 字段只包含在错误消息中,不包含在通知和警告中。(不过,如果详细程度设置为 TERSESQLSTATE,则无论上下文显示模式如何,都会省略 CONTEXT 字段。) + - 更改这个模式不会影响从已经存在的PGresult对象项中得到的消息,只会影响后续创建的PGresult对象 - (如果想要用不同的详细程度打印之前的错误,请见)。 - + 更改此模式不会影响从既有 PGresult 对象中取得的消息,只影响随后创建的对象。(如果希望使用不同的显示模式打印之前的错误,请参见 。) + @@ -5105,25 +4836,20 @@ PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibilit - 启用对客户端/服务器通讯的跟踪,把跟踪信息输出到一个调试文件流中。 + 启用客户端/服务器通信跟踪,将跟踪信息写入调试文件流。 void PQtrace(PGconn *conn, FILE *stream); - + - 每行包括:一个可选的时间戳,一个方向指示器(F表示从客户端到服务器的消息或B表示从服务器到客户端的消息),消息长度、消息类型、和消息内容。 - 非消息内容字段(时间戳、方向、长度和消息类型)由一个制表符分隔。 - 消息内容用空格分隔。 - 协议字符串用双引号括起来,而用作数据值的字符串用单引号括起来。 - 不可打印的字符被打印为十六进制转义。 - 更多消息-类型-特定的详情可以在中发现。 - + 每行包含可选的时间戳、方向指示符(F 表示客户端发往服务器的消息,B 表示服务器发往客户端的消息)、消息长度、消息类型和消息内容。消息内容之外的字段(时间戳、方向、长度和消息类型)以制表符分隔。消息内容以空格分隔。协议字符串用双引号括起,用作数据值的字符串用单引号括起。不可打印字符以十六进制转义形式输出。各消息类型的进一步说明见 。 + - 在 Windows上,如果libpq库和应用使用了不同的标志编译,那么这个函数调用会导致应用崩溃,因为FILE指针的内部表达是不一样的。特别是多线程/单线程、发布/调试 以及静态/动态标志应该是库和所有使用库的应用都一致。 + 在 Windows 上,如果 libpq 库与应用程序使用不同的标志编译,调用此函数会导致应用程序崩溃,因为 FILE 指针的内部表示不同。具体而言,库与所有使用它的应用程序都应使用相同的多线程/单线程、发布/调试和静态/动态标志。 @@ -5144,11 +4870,8 @@ void PQsetTraceFlags(PGconn *conn, int flags); - flags包含描述跟踪的操作模式的标志位。 - 如果flags包含PQTRACE_SUPPRESS_TIMESTAMPS,则在打印每条消息时不包括时间戳。 - 如果flags包含PQTRACE_REGRESS_MODE,那么在打印每个消息时将修改一些字段,例如对象OIDs,以使输出在测试框架中更方便地使用。 - 这个函数必须在调用PQtrace之后调用。 - + flags 包含描述跟踪工作模式的标志位。如果 flags 包含 PQTRACE_SUPPRESS_TIMESTAMPS,则打印每条消息时不包含时间戳。如果 flags 包含 PQTRACE_REGRESS_MODE,则打印每条消息时会隐去某些字段,例如对象 OID,以便在测试框架中使用输出。必须在调用 PQtrace 之后调用此函数。 + @@ -5160,11 +4883,11 @@ void PQsetTraceFlags(PGconn *conn, int flags); - 禁用打开的跟踪。 + 禁用由 启动的跟踪。 void PQuntrace(PGconn *conn); - + @@ -5194,11 +4917,8 @@ void PQfreemem(void *ptr); - 释放libpq分配的内存,尤其是,,,和PQnotifies分配的内存。 - 特别重要的是,在微软 Windows 上使用这个函数,而不是free()。 - 这是因为只有 DLL 和应用的当多线程/单线程、发布/调试以及静态/动态标志相同时,才能在一个 DLL 中分配内存并且在应用中释放它。 - 在非微软 Windows 平台上,这个函数与标准库函数free()相同。 - + 释放 libpq 分配的内存,特别是 PQnotifies 分配的内存。在 Microsoft Windows 上,务必使用此函数,而不是 free()。这是因为只有 DLL 与应用程序使用相同的多线程/单线程、发布/调试和静态/动态标志,才能在 DLL 中分配内存并在应用程序中释放它。在 Microsoft Windows 以外的平台上,此函数与标准库函数 free() 相同。 + @@ -5216,8 +4936,8 @@ void PQconninfoFree(PQconninfoOption *connOptions); - 一个简单的不会做这些,因为数组包含对子字符串的引用。 - + 仅调用 不足以完成此项释放,因为数组还包含指向附属字符串的引用。 + @@ -5241,8 +4961,8 @@ char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, 当前支持的算法是md5scram-sha-256onoff也被接受作为md5的别名,用于与较老的服务器版本兼容)。 注意,对scram-sha-256支持是在PostgreSQL版本10中引入的,并且在老的服务器版本上无法工作。 如果algorithmNULL,这个函数将向服务器查询设置的当前值。 - 这种行为可能会阻塞当前事务,并且当前事务被中止或者连接正忙于执行另一个查询时会失败。 - 如果希望为服务器使用默认的算法但避免阻塞,应在调用之前查询你自己的password_encryption,并且将该值作为algorithm传入。 + 这一查询可能阻塞,并且当前事务被中止或者连接正忙于执行另一个查询时会失败。 + 如果希望为服务器使用默认的算法但避免阻塞,应在调用之前自行查询password_encryption,并且将该值作为algorithm传入。 @@ -5288,8 +5008,8 @@ PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); 这是libpq内部用于分配并初始化一个空PGresult对象的函数。 如果无法分配内存,此函数返回NULL。 将它导出供外部调用,是因为一些应用需要自行生成结果对象,特别是带有错误状态的对象。 - 如果conn非空,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 - 此外,如果conn非空,连接中注册的所有事件过程也会被复制到PGresult中。 + 如果conn 不为 null,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 + 此外,如果conn 不为 null,连接中注册的所有事件过程也会被复制到PGresult中。 (这些过程不会收到PGEVT_RESULTCREATE调用,但可参见。) 注意,最终应对该对象调用,就像处理libpq自身返回的PGresult一样。 @@ -5310,16 +5030,16 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); - conn参数被传送给事件过程,但不会被直接使用。如果事件过程不使用它,则会返回NULL。 - + conn 参数会传递给事件过程,但此函数不会直接使用它。如果事件过程不使用此参数,则可以传入 NULL。 + 已经接收到这个对象的PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件过程不会被再次触发。 - 这个函数与分开的主要原因是在调用事件过程之前创建一个PGresult并且填充它常常是合适的。 - + 此函数与 分开的主要原因是,通常适合先创建 PGresult 并填充数据,然后再调用事件过程。 + @@ -5330,13 +5050,11 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); - 为一个PGresult对象创建一个拷贝。 - 这个拷贝不会以任何方式链接到源结果,并且当该拷贝不再需要时,必须调用进行清理。如果函数失败,返回NULL。 - + 创建 PGresult 对象的副本。副本与源结果没有任何关联,不再需要副本时必须调用 。函数失败时返回 NULL PGresult *PQcopyResult(const PGresult *src, int flags); - + 这不是为了制作一个精确的副本。返回的结果总是放在PGRES_TUPLES_OK状态中,并且不复制源中的任何错误消息。 @@ -5345,7 +5063,7 @@ PGresult *PQcopyResult(const PGresult *src, int flags); PG_COPYRES_TUPLES指定复制源结果的元组。(这也意味着复制属性。) PG_COPYRES_NOTICEHOOKS指定复制源结果的通知钩子。 PG_COPYRES_EVENTS指定复制源结果的事件。(但不复制与源相关的任何实例数据。) - 事件程序接收PGEVT_RESULTCOPY事件。 + 事件过程会收到 PGEVT_RESULTCOPY 事件。 @@ -5376,18 +5094,15 @@ int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs); - 设置一个PGresult对象的一个元组域值。 + 设置 PGresult 对象中某个元组的字段值。 int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len); - + - 这个函数将自动按需增加结果的内部元组数组。但是,tup_num参数必须小于等于,意味着这个函数对元组数组一次只能增加一个元组。 - 但已存在的任意元组中的任意域可以以任意顺序进行调整。如果field_num的一个值已经存在,它会被覆盖。 - 如果len是 -1,或valueNULL, 该域值会被设置为一个 SQL 空值。 - value会被复制到结果的私有存储中,因此函数返回后就不再需要了。如果函数失败,返回值是 0。如果函数成功,返回值会是非 0。 - + 此函数会根据需要自动扩展结果内部的元组数组。不过,tup_num 参数必须小于或等于 ,也就是说,每次只能向元组数组增加一个元组。已有元组的任何字段都可以按任意顺序修改。如果 field_num 指定的位置已有值,该值会被覆盖。如果 len 为 -1 或 valueNULL,则将该字段设置为 SQL null 值。value 会被复制到结果的私有存储中,因此函数返回后就不再需要它。函数失败时返回零,成功时返回非零值。 + @@ -5405,8 +5120,8 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); - 当res被清除时,这个函数分配的内存也会被释放掉。如果函数失败,返回值是NULL。结果被保证为按照数据的任意类型充分地对齐,正如malloc所作的。 - + 使用此函数分配的所有内存都会在清除 res 时释放。函数失败时返回 NULL。与 malloc 一样,返回的内存保证满足任意数据类型的对齐要求。 + @@ -5417,15 +5132,15 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); - 检索为PGresult对象分配的字节数。 + 获取为 PGresult 对象分配的字节数。 size_t PQresultMemorySize(const PGresult *res); - + - 此值是与PGresult对象关联的所有malloc请求的总和,就是说,将释放的所有空间。此信息可用于管理内存消耗。 - + 此值是与 PGresult 对象相关的所有 malloc 请求所分配字节数的总和,即 将释放的全部内存。这一信息有助于管理内存消耗。 + @@ -5444,28 +5159,25 @@ int PQlibVersion(void); - 在运行时,这个函数的结果可以被用来决定在当前已载入的 libpq 版本中特定的功能是否可用。 - 例如,这个函数可以被用来决定哪些选项可以被用于。 - + 可在运行时根据此函数的结果,判断当前已加载的 libpq 版本是否具有特定功能。例如,可用它判断 支持哪些连接选项。 + - 结果通过将库的主版本号乘以10000再加上次版本号形成。例如,版本10.1将被返回为100001,而版本11.0将被返回为110000。 - + 返回值等于库的主版本号乘以 10000 再加上次版本号。例如,版本 10.1 返回 100001,版本 11.0 返回 110000。 + - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。 - 对于那些版本,为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - + 在主版本 10 之前,PostgreSQL 使用由三个部分组成的版本号,前两个部分共同表示主版本。对于这些版本, 用两位数字表示每个部分;例如,版本 9.1.5 返回 90105,版本 9.2.0 返回 90200。 + - 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。 - 在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 - + 因此,为了判断功能兼容性,应用程序应将 的结果除以 100 而非 10000,得到逻辑上的主版本号。在所有版本系列中,次版本(错误修复版本)之间只有最后两位数字不同。 + - 这个函数出现于PostgreSQL版本 9.1,因此它不能被用来在早期的版本中检测所需的功能,因为调用它将会创建一个对版本9.1及其后版本的链接依赖。 + 此函数从 PostgreSQL 9.1 起提供,因而不能用它检测更早版本是否具有所需功能:调用它会建立对 9.1 或更高版本的链接依赖。 @@ -5480,13 +5192,13 @@ int PQlibVersion(void); 通知处理 - notice processing - in libpq + 通知处理 + 在 libpq 中 - 服务器产生的通知和警告消息不会被查询执行函数返回,因为它们不代表查询失败。它们可以被传递给一个通知处理函数,并且在处理者返回后执行会继续正常进行。默认的处理函数会把消息打印在stderr上,但是应用可以通过提供它自己的处理函数来重载这种行为。 - + 服务器生成的通知和警告消息不由查询执行函数返回,因为它们并不表示查询失败。这些消息会传递给通知处理函数,处理函数返回后,执行正常继续。默认通知处理函数将消息打印到 stderr,应用程序也可以提供自己的处理函数来替换这一行为。 + 由于历史原因,通知处理有两个级别,称为通知接收器和通知处理器。通知接收器的默认行为是格式化通知并且将一个字符串传递给通知处理器来打印。不过,如果一个应用选择提供自己的通知接收器,它通常会忽略通知处理器层并且在通知接收器中完成所有工作。 @@ -5494,10 +5206,10 @@ int PQlibVersion(void); 函数PQsetNoticeReceiver - notice receiver + 通知接收器 PQsetNoticeReceiver为一个连接对象设置或者检查当前的通知接收器。 相似地,PQsetNoticeProcessor - notice processor + 通知处理器 PQsetNoticeProcessor设置或检查当前的通知处理器。 @@ -5520,19 +5232,16 @@ PQsetNoticeProcessor(PGconn *conn, - 当接收到一个服务器产生的或者libpq内部产生的通知或警告消息,通知接收器函数会被调用。 - 它会以一种PGRES_NONFATAL_ERROR PGresult的形式传递该消息 - (这允许接收器使用抽取个别的域,或者使用或者得到一个完整的预格式化的消息)。 - 被传递给PQsetNoticeReceiver的同一个空指针也被传递(必要时,这个指针可以被用来访问应用相关的状态)。 - + 从服务器收到通知或警告消息,或者 libpq 内部生成这类消息时,便会调用通知接收器函数。消息以状态为 PGRES_NONFATAL_ERRORPGresult 对象传给该函数。(接收器可使用 提取单个字段,也可使用 获取完整的预格式化消息。)传给 PQsetNoticeReceiver 的同一个 void 指针也会传入。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知接收器会简单地抽取消息(使用)并且将它传递给通知处理器。 - 通知处理器负责处理一个以文本形式给出的通知或警告消息。该消息的字符串文本(包括一个收尾的新行)被传递给通知处理器,外加一个同时被传递给PQsetNoticeProcessor的空指针(必要时,这个指针可以被用来访问应用相关的状态)。 - + 通知处理器负责处理以文本形式提供的通知或警告消息。传给它的参数包括消息字符串(含末尾的换行符),以及先前传给 PQsetNoticeProcessor 的同一个 void 指针。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知处理器很简单: @@ -5546,9 +5255,8 @@ defaultNoticeProcessor(void *arg, const char *message) - 一旦你设定了一个通知接收器或处理器,你应该期待只要PGconn对象或者从它构造出的PGresult对象存在,该函数就应该能被调用。 - 在一个PGresult创建时,PGconn的当前通知处理指针被复制到PGresult中,以备类似的函数使用。 - + 设置通知接收器或处理器后,应当预期:只要 PGconn 对象或由它生成的 PGresult 对象仍存在,就可能调用该函数。创建 PGresult 时,会将 PGconn 当前的通知处理指针复制到 PGresult 中,供 等函数在需要时使用。 + @@ -5557,19 +5265,19 @@ defaultNoticeProcessor(void *arg, const char *message) 事件系统 - libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和毁灭。一种主要的使用情况是这允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 + libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和销毁。一个主要用途是允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 - 每个注册的事件处理程序都与两个数据相关联,libpq仅将其视为不透明的void *指针。 - 有一个透传指针,当事件处理程序与PGconn注册时,应用程序提供。 + 每个注册的事件处理程序都与两项数据相关联,libpq仅将其视为不透明的void *指针。 + 有一个透传指针,由应用程序在向 PGconn 注册事件处理程序时提供。 透传指针在PGconn及其生成的所有PGresult的生命周期内永远不会更改; 因此,如果使用,它必须指向长期存在的数据。 此外,还有一个实例数据指针,在每个PGconnPGresult中一开始都是NULL。 可以使用函数来操作此指针。 请注意,与透传指针不同,PGconn的实例数据不会自动继承到从中创建的PGresult。 - libpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 —— 这是事件处理程序的责任。 + libpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 — 这是事件处理程序的责任。 @@ -5628,21 +5336,12 @@ typedef struct PGEVT_CONNDESTROY - - - 为了响应,连接销毁事件会被触发。由于 libpq 没有能力管理事件数据,事件过程有责任正确地清理它的事件数据。清理失败将会导致内存泄露。 - - + 连接销毁事件由以下调用触发:。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGconn *conn; } PGEventConnDestroy; - - - 当接收到一个PGEVT_CONNDESTROY事件时,evtInfo指针应该被类型转换为PGEventConnDestroy *。 - 这个事件在执行任何其他清理之前被触发。 - 该事件过程的返回值被忽略,因为没有办法指示一个来自的失败。还有,一个事件过程失败不该中断对不需要的内存的清理。 - +收到PGEVT_CONNDESTROY事件时,应将evtInfo指针强制转换为PGEventConnDestroy *。该事件触发于以下函数执行任何其他清理工作之前:。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:。此外,事件过程失败不应中止清理不再使用的内存的过程。 @@ -5698,21 +5397,12 @@ typedef struct PGEVT_RESULTDESTROY - - - 为了响应,结果销毁事件会被触发。由于 libpq 没有能力管理事件数据,事件过程有责任正确地清理它的事件数据。清理失败将会导致内存泄露。 - - + 结果销毁事件由以下调用触发:。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGresult *result; } PGEventResultDestroy; - - - 当接收到一个PGEVT_RESULTDESTROY事件时,evtInfo指针应该被类型转换为PGEventResultDestroy *。 - 这个事件在执行任何其他清理之前被触发。该事件过程的返回值被忽略,因为没有办法指示来自的失败。 - 还有,一个事件过程失败不该中断不需要的内存的清理过程。 - +收到PGEVT_RESULTDESTROY事件时,应将evtInfo指针强制转换为PGEventResultDestroy *。该事件触发于以下函数执行任何其他清理工作之前:。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:。此外,事件过程失败不应中止清理不再使用的内存的过程。 @@ -5720,7 +5410,7 @@ typedef struct - 事件回调函数 + 事件回调过程 @@ -5730,16 +5420,11 @@ typedef struct - PGEventProc是到一个事件过程的指针的 typedef,也就是从 libpq 接收事件的用户回调函数。一个事件过程的原型必须是 - + PGEventProc 是通过 typedef 定义的事件过程指针类型,也就是接收 libpq 事件的用户回调函数的指针类型。事件过程的签名必须为: int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) - - evtId指示发生了哪一个PGEVT事件。 - evtInfo指针必须被类型转换为合适的结构体类型才能获得关于事件的进一步信息。 - 当事件过程已被注册时,passThrough参数是提供给的指针。 - 如果成功,该函数应该返回非零值,失败则返回零。 +evtId 参数指示发生了哪一种 PGEVT 事件。必须将 evtInfo 指针强制转换为适当的结构体类型,以获取关于该事件的更多信息。passThrough 参数是在注册事件过程时传给 的指针。函数应在成功时返回非零值,在失败时返回零。 @@ -5749,8 +5434,8 @@ int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) - 在 Windows 上,函数能够有两个不同的地址:一个对 DLL 之外可见而另一个对 DLL 之内可见。我们应当小心只有其中之一会被用于libpq的事件过程函数,否则将会产生混淆。编写代码的最简单规则是将所有的事件过程声明为static。如果过程的地址必须对它自己的源代码文件之外可见,提供一个单独的函数来返回该地址。 - + 在 Windows 上,函数可能有两个不同的地址:一个在 DLL 外部可见,另一个在 DLL 内部可见。使用 libpq 的事件过程函数时,务必始终使用其中同一个地址,否则会产生混淆。确保代码正常工作的最简单做法,是将事件过程声明为 static。如果需要在过程所在的源文件之外取得其地址,应提供一个单独的函数来返回该地址。 + @@ -5778,7 +5463,7 @@ int PQregisterEventProc(PGconn *conn, PGEventProc proc, - 在每一个你想要接收事件的PGconn上必须注册一个事件过程。和内存不同,没有限制说一个连接上能注册多少个事件过程。如果该函数成功,它会返回一个非零值。如果它失败,则会返回零。 + 对于希望接收其事件的每个 PGconn,都必须注册一次事件过程。一个连接可注册的事件过程数量只受内存限制。函数成功时返回非零值,失败时返回零。 @@ -5823,16 +5508,14 @@ void *PQinstanceData(const PGconn *conn, PGEventProc proc); - 把结果的用于procinstanceData设置为data。成功返回非零,失败返回零(只有proc没有被正确地注册在conn中,才可能会失败)。 - + 将结果中针对 procinstanceData 设置为 data。成功时返回非零值,失败时返回零。(只有当 proc 未在结果中正确注册时,才可能失败。) int PQresultSetInstanceData(PGresult *res, PGEventProc proc, void *data); - 请注意,data表示的任何存储都不会由考虑,除非使用分配。 - (这样做是值得推荐的,因为它消除了在销毁结果时显式释放此类存储的需要。) + 注意,data 所指的存储不会计入 ,除非使用 分配它。(推荐这样做,因为结果销毁时便不必显式释放这部分存储。) @@ -5856,18 +5539,18 @@ void *PQresultInstanceData(const PGresult *res, PGEventProc proc); - 事件实例 + 事件示例 - 这里是一个管理与 libpq 连接和结果相关的私有数据的示例的框架。 - + 下面给出一个示例框架,用于管理与 libpq 连接和结果关联的私有数据。 + -/* The instanceData */ +/* instanceData 数据 */ typedef struct { int n; @@ -5887,14 +5570,14 @@ main(void) if (PQstatus(conn) != CONNECTION_OK) { - /* PQerrorMessage's result includes a trailing newline */ + /* PQerrorMessage 的结果包含末尾的换行符 */ fprintf(stderr, "%s", PQerrorMessage(conn)); PQfinish(conn); return 1; } - /* called once on any connection that should receive events. - * Sends a PGEVT_REGISTER to myEventProc. + /* 在每个需要接收事件的连接上调用一次。 + * 向 myEventProc 发送 PGEVT_REGISTER 事件。 */ if (!PQregisterEventProc(conn, myEventProc, "mydata_proc", NULL)) { @@ -5903,28 +5586,28 @@ main(void) return 1; } - /* conn instanceData is available */ + /* 可以取得 conn 的 instanceData */ data = PQinstanceData(conn, myEventProc); - /* Sends a PGEVT_RESULTCREATE to myEventProc */ + /* 向 myEventProc 发送 PGEVT_RESULTCREATE 事件 */ res = PQexec(conn, "SELECT 1 + 1"); - /* result instanceData is available */ + /* 可以取得结果的 instanceData */ data = PQresultInstanceData(res, myEventProc); - /* If PG_COPYRES_EVENTS is used, sends a PGEVT_RESULTCOPY to myEventProc */ + /* 使用 PG_COPYRES_EVENTS 时,向 myEventProc 发送 PGEVT_RESULTCOPY 事件 */ res_copy = PQcopyResult(res, PG_COPYRES_TUPLES | PG_COPYRES_EVENTS); - /* result instanceData is available if PG_COPYRES_EVENTS was - * used during the PQcopyResult call. + /* 如果调用 PQcopyResult 时使用了 PG_COPYRES_EVENTS, + * 就可以取得结果的 instanceData。 */ data = PQresultInstanceData(res_copy, myEventProc); - /* Both clears send a PGEVT_RESULTDESTROY to myEventProc */ + /* 两次清除操作都会向 myEventProc 发送 PGEVT_RESULTDESTROY 事件 */ PQclear(res); PQclear(res_copy); - /* Sends a PGEVT_CONNDESTROY to myEventProc */ + /* 向 myEventProc 发送 PGEVT_CONNDESTROY 事件 */ PQfinish(conn); return 0; @@ -5940,7 +5623,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventRegister *e = (PGEventRegister *)evtInfo; mydata *data = get_mydata(e->conn); - /* associate app specific data with connection */ + /* 将应用程序特有的数据与连接关联 */ PQsetInstanceData(e->conn, myEventProc, data); break; } @@ -5960,7 +5643,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventConnDestroy *e = (PGEventConnDestroy *)evtInfo; mydata *data = PQinstanceData(e->conn, myEventProc); - /* free instance data because the conn is being destroyed */ + /* 连接正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; @@ -5972,7 +5655,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *conn_data = PQinstanceData(e->conn, myEventProc); mydata *res_data = dup_mydata(conn_data); - /* associate app specific data with result (copy it from conn) */ + /* 将应用程序特有的数据与结果关联(从 conn 复制) */ PQresultSetInstanceData(e->result, myEventProc, res_data); break; } @@ -5983,7 +5666,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *src_data = PQresultInstanceData(e->src, myEventProc); mydata *dest_data = dup_mydata(src_data); - /* associate app specific data with result (copy it from a result) */ + /* 将应用程序特有的数据与结果关联(从另一个结果复制) */ PQresultSetInstanceData(e->dest, myEventProc, dest_data); break; } @@ -5993,18 +5676,18 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventResultDestroy *e = (PGEventResultDestroy *)evtInfo; mydata *data = PQresultInstanceData(e->result, myEventProc); - /* free instance data because the result is being destroyed */ + /* 结果正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; } - /* unknown event ID, just return true. */ + /* 未知的事件 ID,直接返回 true。 */ default: break; } - return true; /* event processing succeeded */ + return true; /* 事件处理成功 */ } ]]> @@ -6020,9 +5703,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 以下环境变量可用于选择默认连接参数值,这些值将被使用,如果调用代码没有直接指定值。这些对于避免将数据库连接信息硬编码到简单的客户端应用程序中非常有用,例如。 - - + 以下环境变量可用于选择连接参数的默认值,供 在调用代码未直接指定参数值时使用。例如,这样可以避免在简单的客户端应用程序中硬编码数据库连接信息。 + @@ -6130,9 +5812,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSERVICEFILE - PGSERVICEFILE指定每个用户的连接服务文件的名称 - (参见)。 - 默认为~/.pg_service.conf,或者在Microsoft Windows上为%APPDATA%\postgresql\.pg_service.conf。 + PGSERVICEFILE指定每个用户的连接服务文件的名称(参见)。 + 默认为~/.pg_service.conf,或者在 Microsoft Windows 上为%APPDATA%\postgresql\.pg_service.conf @@ -6177,7 +5858,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGREQUIRESSL的行为与连接参数相同。 - 这个环境变量已被弃用,推荐使用PGSSLMODE变量;设置这两个变量会抑制这个变量的效果。 + 这个环境变量已被弃用,推荐使用PGSSLMODE变量;同时设置这两个变量时,前者不再生效。 @@ -6360,9 +6041,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 下面的环境变量可用来为每一个PostgreSQL会话指定默认行为(为每一个用户或每一个数据库设置默认行为的方法还可见命令)。 - - + 以下环境变量可用于指定每个 PostgreSQL 会话的默认行为。(也可参见 命令,了解按用户或按数据库设置默认行为的方法。) + @@ -6390,8 +6070,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - - 这些环境变量的正确值可参考SQL 命令 。 +有关这些环境变量的正确取值,请参见 SQL 命令 @@ -6436,16 +6115,12 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) 用户主目录中的.pgpass文件可保存密码,供连接需要密码且尚未通过其他方式指定密码时使用。在 Microsoft Windows 上,文件名为%APPDATA%\postgresql\pgpass.conf(其中%APPDATA%指用户配置文件中的应用数据子目录)。也可以通过连接参数或环境变量PGPASSFILE指定要使用的密码文件。 - - 这个文件应该包含下列格式的行: - + 该文件中的行应采用以下格式: hostname:port:database:username:password - - (你可以向该文件增加一个提醒:把上面的行复制到该文件并且在前面加上#)。前四个字段的每一个都可以是字面值或者匹配任何东西的*。第一个匹配当前连接参数的行中的密码字段将被使用(因此,在使用通配符时把更特殊的项放在前面)。如果一个条目需要包含:或者\,用\对该字符转义。如果指定了host连接参数,主机名字段会被匹配到host,否则如果指定了hostaddr参数则匹配到hostaddr,如果两者都没有给出,则会搜索主机名localhost。当连接是一个Unix域套接字连接并且host参数匹配libpq的默认套接字目录路径时,也会搜索主机名localhost。在一台备库上,值为replication的数据库字段匹配连接到主库的流复制连接。否则数据库字段的用途有限,因为用户对同一个集簇中的所有数据库都有相同的密码。 - +(可以复制上面这一行,并在行首加上#,在文件中加入提示注释。)前四个字段中的每一个都可以是字面值,或者是*,后者可以匹配任何内容。将使用与当前连接参数匹配的第一行中的密码字段。(因此,使用通配符时,应将更具体的条目放在前面。)如果条目需要包含:\,请使用\转义该字符。主机名字段首先匹配已指定的host连接参数;否则匹配已指定的hostaddr参数。如果两者都未指定,则查找主机名localhost。在以下情况下也会查找主机名localhost:连接使用 Unix 域套接字,且host参数与libpq的默认套接字目录路径匹配。在备库中,数据库字段为replication时,匹配连接到主库的流复制连接。除此之外,数据库字段的用途有限,因为同一用户在同一数据库集簇的所有数据库中使用相同的密码。 - 在 Unix 系统上,密码文件上的权限必须不允许所有人或组内访问,可以用chmod 0600 ~/.pgpass这样的命令实现。如果权限没有这么严格,该文件将被忽略。在微软 Windows 上,该文件被假定存储在一个安全的目录中,因此不会进行特别的权限检查。 + 在 Unix 系统上,密码文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.pgpass 这样的命令实现。如果权限没有这么严格,该文件将被忽略。在 Microsoft Windows 上,假定该文件存储在安全的目录中,因此不进行特殊的权限检查。 @@ -6466,10 +6141,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 连接服务文件允许 libpq 连接参数与一个单一服务名称关联。 - 那个服务名称可以在一个 libpq 连接字符串里面指定,与其相关的设置将被使用。 - 这允许在不重新编译使用 libpq 的应用的前提下修改连接参数。 - 服务名称也可以被使用PGSERVICE环境变量来指定。 + 连接服务文件允许将 libpq 连接参数与单个服务名称关联。随后可以在 libpq 连接字符串中指定该服务名称,从而使用关联的设置。这样便可以修改连接参数,而无需重新编译使用 libpq 的应用程序。也可以使用 PGSERVICE 环境变量指定服务名称。 @@ -6485,23 +6157,19 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 或者服务文件使用一种INI 文件格式,其中小节名是服务名并且参数是连接参数。 - 列表见。例如: + 两种服务文件均使用 INI 文件 格式,其中配置段名称是服务名称,参数是连接参数;参数列表见 。例如: -# comment +# 注释 [mydb] host=somehost port=5433 user=admin - 在PostgreSQL安装的share/pg_service.conf.sample中提供了一个示例文件。 +PostgreSQL 安装目录中的 share/pg_service.conf.sample 提供了一个示例文件。 - 从服务文件中获取的连接参数与从其他来源获取的参数相结合。 - 服务文件设置覆盖相应的环境变量,然后反过来可以由连接字符串中直接给出的值覆盖。 - 例如,使用上面的服务文件,连接字符串service=mydb port=5434将使用主机somehost,端口5434, - 用户admin,以及由环境变量或内置默认所设置的其他参数。 + 从服务文件中获取的连接参数会与其他来源的参数合并。服务文件中的设置会覆盖相应的环境变量,而连接字符串中直接给出的值又会覆盖服务文件中的设置。例如,使用上述服务文件时,连接字符串 service=mydb port=5434 将使用主机 somehost、端口 5434、用户 admin,以及由环境变量或内置默认值设置的其他参数。 @@ -6517,24 +6185,14 @@ user=admin 如果libpq已经在编译时打开了 LDAP 支持(configure的选项),就可以通过 LDAP 从一个中央服务器检索hostdbname之类的连接参数。这样做的好处是如果一个数据库的连接参数改变,不需要在所有的客户端机器上更新连接信息。 - - LDAP连接参数查找使用连接服务文件pg_service.conf(参见)。 - 在pg_service.conf段落中以ldap://开头的行将被识别为LDAP URL,并执行LDAP查询。 - 结果必须是一组keyword = value对,将用于设置连接选项。 - URL必须符合RFC 1959的形式为 - + LDAP 连接参数查询使用连接服务文件pg_service.conf(参见)。在pg_service.conf的配置段中,以ldap://开头的行会被识别为 LDAP URL,并执行 LDAP 查询。结果必须是一个keyword = value键值对列表,用于设置连接选项。URL 必须符合 RFC 1959,格式如下: ldap://[hostname[:port]]/search_base?attribute?search_scope?filter - - 其中hostname默认为localhostport默认为389。 - +其中,hostname默认为localhostport默认为 389。 - - 一次成功的 LDAP 查找后,pg_service.conf的处理被终止。但是如果联系不上 LDAP 则会继续处理pg_service.conf。这就提供了后手,可以加入更多指向不同 LDAP 服务器的 LDAP URL 行、经典的keyword = value对或者默认连接选项。如果你宁愿在这种情况下得到一个错误消息,在该 LDAP URL 之后增加一个语法错误的行。 - + LDAP 查找成功后就会停止处理 pg_service.conf;如果无法联系 LDAP 服务器,则会继续处理。这使后续指向其他 LDAP 服务器的 LDAP URL 行、常规的 keyword = value 对或默认连接选项能够作为后备。如果希望在这种情况下得到错误消息,可以在 LDAP URL 后添加一个语法不正确的行。 - - 一个和 LDIF 文件一起创建的 LDAP 条目实例 - + 例如,使用以下 LDIF 文件创建的 LDAP 条目: version:1 dn:cn=mydatabase,dc=mycompany,dc=com changetype:add @@ -6546,9 +6204,7 @@ description:port=5439 description:dbname=mydb description:user=mydb_user description:sslmode=require - - 可以用下面的 LDAP URL 查询: - +可以通过以下 LDAP URL 查询: ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase) @@ -6556,7 +6212,7 @@ ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase) 你也可以将常规的服务文件条目和 LDAP 查找混合。pg_service.conf中一节的完整示例: -# 只有主机和端口存储在LDAP中,显式指定dbname和user。 +# 仅 host 和 port 存储在 LDAP 中;显式指定 dbname 和 user [customerdb] dbname=customer user=appuser @@ -6576,9 +6232,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - PostgreSQL具有原生支持使用SSL连接来加密客户端/服务器通信, - 使用TLS协议以提高安全性。有关服务器端SSL功能的详细信息,请参见。 - + PostgreSQL 原生支持使用 SSL 连接,通过 TLS 协议加密客户端与服务器之间的通信,以提高安全性。有关服务器端 SSL 功能的详细信息,请参见 。 + libpq读取系统范围的OpenSSL配置文件。默认情况下,这个文件被命名为openssl.cnf并且位于openssl version -d所报告的目录中。可以通过设置环境变量OPENSSL_CONF把这个默认值覆盖为想要的配置文件的名称。 @@ -6586,39 +6241,25 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 服务器证书的客户端验证 + 客户端对服务器证书的验证 - 默认情况下,PostgreSQL将不会执行服务器证书的任何验证。这意味着可以在不被客户端知晓的情况下伪造服务器身份(例如通过修改一个 DNS 记录或者接管服务器的 IP 地址)。为了阻止哄骗,客户端必须能够通过一条信任链验证服务器的身份。信任链可以这样建立:在一台计算机上放置一个根(自签名的)证书机构(CA)的证书并且在另一台计算机上放置一个由根证书签发的叶子证书。还可以使用一种中间证书,它由根证书签发并且可以签发叶子证书。 + 默认情况下,PostgreSQL 不会对服务器证书执行任何验证。这意味着可以在客户端不知情的情况下伪造服务器身份,例如修改 DNS 记录或接管服务器的 IP 地址。要防止身份伪造,客户端必须能够通过信任链验证服务器身份。建立信任链的方法是:在一台计算机上放置根证书机构(CA)的自签名证书,在另一台计算机上放置由根证书签发的叶证书。也可以使用由根证书签发、又用于签发叶证书的中间证书。 - - 为了允许客户端验证服务器的身份,在客户端上放置一份根证书并且在服务器上放置由根证书签发的叶子证书。为了允许服务器验证客户端的身份,在服务器上放置一份根证书并且在客户端上放置由根证书签发的叶子证书。也可以使用一个或者更多个中间证书(通常与叶子证书存在一起)来将叶子证书链接到根证书。 - + 要让客户端验证服务器的身份,请在客户端放置根证书,并在服务器上放置由该根证书签发的叶证书。要让服务器验证客户端的身份,请在服务器上放置根证书,并在客户端放置由该根证书签发的叶证书。也可以使用一个或多个中间证书(通常与叶证书存储在一起),将叶证书链接到根证书。 - - 一旦信任链被建立起来,客户端有两种方法验证服务器发过来的叶子证书。如果参数sslmode被设置为verify-ca,libpq将通过检查该证书是否链接到存储在客户端上的根证书来验证服务器。如果sslmode被设置为verify-full,libpq将验证服务器的主机名匹配存储在服务器证书中的名称。如果服务器证书无法被验证,则SSL连接将失败。在大部分对安全性很敏感的环境中,推荐使用verify-full。 - + 建立信任链后,客户端可以通过两种方式验证服务器发送的叶证书。如果参数 sslmode 设为 verify-ca,libpq 会沿证书链检查到存储在客户端上的根证书,以验证服务器是否可信。如果 sslmode 设为 verify-full,libpq 还会验证服务器主机名是否与服务器证书中存储的名称匹配。如果无法验证服务器证书,SSL 连接将失败。在大多数对安全敏感的环境中,建议使用 verify-full - 在verify-full模式下,主机名将与证书的主体替代名称属性(SAN)匹配, - 或者与通用名称属性匹配,如果没有类型为dNSName的SAN存在。 - 如果证书的名称属性以星号(*)开头,那么星号将被视为通配符, - 可以匹配所有字符,除了点(.)。 - 这意味着证书将不匹配子域。如果连接使用IP地址而不是主机名进行, - 则IP地址将与类型为iPAddressdNSName的SAN匹配 - (不进行任何DNS查找)。如果没有iPAddress SAN存在, - 也没有匹配的dNSName SAN存在,则主机IP地址将与通用名称属性匹配。 - + 在 verify-full 模式下,会将主机名与证书的主体替代名称属性(SAN)匹配;如果不存在类型为 dNSName 的 SAN,则与通用名称属性匹配。如果证书的名称属性以星号(*)开头,该星号会被视为通配符,匹配点(.)以外的所有字符。这意味着该证书不会匹配子域。如果使用 IP 地址而不是主机名建立连接,则会将该 IP 地址与类型为 iPAddressdNSName 的 SAN 匹配(不执行任何 DNS 查询)。如果不存在 iPAddress SAN,也不存在匹配的 dNSName SAN,则将主机 IP 地址与通用名称属性匹配。 + - 为了与早期版本的PostgreSQL向后兼容,主机IP地址的验证方式与 - RFC 6125中的方式不同。 - 主机IP地址始终与dNSName SANs以及iPAddress SANs匹配, - 如果不存在相关的SANs,则可以与通用名称属性匹配。 - + 为与 PostgreSQL 的早期版本向后兼容,主机 IP 地址的验证方式与 RFC 6125 不同。主机 IP 地址始终会与 dNSName SAN 以及 iPAddress SAN 匹配;如果不存在相关的 SAN,还可以与通用名称属性匹配。 + @@ -6638,8 +6279,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 为了与 PostgreSQL 的早期版本达到向后兼容,如果存在一个根 CA 文件,sslmode=require的行为将与verify-ca相同,即服务器证书根据 CA 验证。我们鼓励依赖这种行为,并且需要证书验证的应用应该总是使用verify-ca或者verify-full。 - + 为与 PostgreSQL 的早期版本向后兼容,如果存在根 CA 文件,sslmode=require 的行为将与 verify-ca 相同,即根据 CA 验证服务器证书。不建议依赖这种行为;需要证书验证的应用程序应始终使用 verify-caverify-full。 + @@ -6648,44 +6289,27 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 客户端证书 - 如果服务器尝试通过请求客户端的叶证书来验证客户端的身份, - libpq将发送存储在文件 - ~/.postgresql/postgresql.crt中的证书,该文件位于用户的主目录中。 - 证书必须链到服务器信任的根证书。匹配的 - 私钥文件~/.postgresql/postgresql.key也必须存在。 - 在Microsoft Windows上,这些文件的名称分别为 - %APPDATA%\postgresql\postgresql.crt和 - %APPDATA%\postgresql\postgresql.key。 - 证书和密钥文件的位置可以通过连接参数 - sslcertsslkey, - 或通过环境变量PGSSLCERTPGSSLKEY来覆盖。 - + 如果服务器请求客户端的叶证书以验证客户端身份,libpq 将发送用户主目录下 ~/.postgresql/postgresql.crt 文件中存储的证书。这些证书必须通过证书链连接到服务器信任的根证书。还必须存在匹配的私钥文件 ~/.postgresql/postgresql.key。在 Microsoft Windows 上,这两个文件分别名为 %APPDATA%\postgresql\postgresql.crt%APPDATA%\postgresql\postgresql.key。可以通过连接参数 sslcertsslkey,或环境变量 PGSSLCERTPGSSLKEY,覆盖证书和密钥文件的位置。 + - 在Unix系统上,私钥文件的权限必须禁止任何对世界或组的访问;可以通过类似以下命令来实现: - chmod 0600 ~/.postgresql/postgresql.key。 - 或者,该文件可以由root拥有并具有组读取权限(即0640权限)。 - 该设置适用于由操作系统管理证书和密钥文件的安装。然后,libpq的用户应该成为具有对这些证书和密钥文件访问权限的组的成员。 - (在Microsoft Windows上,没有文件权限检查,因为假定%APPDATA%\postgresql目录是安全的。) - + 在 Unix 系统上,私钥文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.postgresql/postgresql.key 这样的命令实现。另一种做法是使文件归 root 所有,并允许组用户读取(即 0640 权限)。这种设置适用于由操作系统管理证书和密钥文件的安装环境。此时,应将 libpq 用户加入有权访问这些证书和密钥文件的组。(在 Microsoft Windows 上,不检查文件权限,因为假定 %APPDATA%\postgresql 目录是安全的。) + postgresql.crt中的第一个证书必须是客户端的证书,因为它必须匹配客户端的私钥。可以选择将中间证书追加到该文件 — 这样做避免了在服务器上存放中间证书的要求()。 - 证书和密钥可能是 PEM 或 ASN.1 DER 格式。 + 证书和密钥可以采用 PEM 或 ASN.1 DER 格式。 - 密钥可以以明文存储,也可以使用OpenSSL支持的任何算法(例如AES-128)使用密码进行加密。 - 如果密钥是加密存储的,那么可以在连接选项中提供密码。 - 如果提供了加密密钥,而且sslpassword选项不存在或为空,那么只要 TTY 可用,OpenSSL就会以Enter PEM pass phrase:提示交互式输入密码。 - 应用程序可以通过提供自己的密钥密码回调,覆盖客户端证书提示以及sslpassword参数的处理;参见。 + 密钥可以以明文存储,也可以使用密码,按 OpenSSL 支持的任意算法(例如 AES-128)进行加密。如果密钥以加密形式存储,可以在 连接选项中提供密码。如果提供了加密密钥,而 sslpassword 选项缺失或为空,则在有 TTY 可用时,OpenSSL 会显示 Enter PEM pass phrase: 提示,交互式地请求输入密码。应用程序可以提供自己的密钥密码回调,以覆盖客户端证书提示及 sslpassword 参数的处理;参见 - 创建证书的指令请参考。 + 有关创建证书的说明,请参见 @@ -6694,8 +6318,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 不同模式中提供的保护 - sslmode参数的不同值提供了不同级别的保护。SSL 能够针对三类攻击提供保护: - + sslmode 参数的不同值提供不同级别的保护。SSL 可以防范三类攻击: 窃听 @@ -6708,31 +6331,33 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 中间人(MITM - 如果一个第三方能对客户端和服务器之间传送的数据进行修改,它就能假装是服务器并且因此能看见并且修改数据,即使这些数据已被加密。然后第三方可以将连接信息和数据转送给原来的服务器,使得它不可能检测到攻击。这样做的通常途径包括 DNS 污染和地址劫持,借此客户端被重定向到一个不同的服务器。还有几种其他的攻击方式能够完成这种攻击。SSL使用证书验证让客户端认证服务器,就可以阻止这种攻击。 - + + 如果第三方能修改客户端与服务器之间传输的数据,就可以冒充服务器,进而查看和修改数据,即使数据已经加密。随后,第三方可以将连接信息和数据转发给原来的服务器,使攻击无法被察觉。常见的手段包括 DNS 污染和地址劫持,从而将客户端引向预期之外的服务器。还有其他几种攻击手段可以达到同样的目的。SSL 使用证书验证,让客户端认证服务器身份,以防范这种攻击。 + - 模仿 + 冒充 - 如果一个第三方能假装是一个授权的客户端,它能够简单地访问它本不能访问的数据。通常这可以由不安全的密码管理所致。SSL使用客户端证书来确保只有持有合法证书的客户端才能访问服务器,这样就能阻止这种攻击。 - + + 如果第三方能冒充获授权的客户端,就能直接访问其无权访问的数据。这通常可能由不安全的密码管理导致。SSL 使用客户端证书,确保只有持有有效证书的客户端才能访问服务器,以防范这种攻击。 + - 对于一个已知受 SSL 保护的连接,在连接建立之前,必须在客户端和服务器两端都配置 SSL。如果只在服务器端配置,客户端在得知服务器要求高安全性之前,可能就已经开始发送敏感信息(例如密码)。在 libpq 中,要确保连接安全,可以把sslmode参数设置为verify-fullverify-ca,并为系统提供一个用于验证的根证书。这类似于使用https URL浏览加密网页。 + 要确保连接受到 SSL 保护,必须在建立连接之前,在客户端和服务器两端配置 SSL。如果仅在服务器上配置,客户端可能在得知服务器要求高安全性之前就已发送敏感信息(例如密码)。在 libpq 中,可以将 sslmode 参数设为 verify-fullverify-ca,并向系统提供用于验证的根证书,以确保连接安全。这类似于使用 https URL 进行加密的网页浏览。 - 一旦服务器已经被认证,客户端可以传递敏感数据。这意味着直到这一点,客户端都不需要知道是否证书将被用于认证,这样只需要在服务器配置中指定就比较安全。 + 服务器通过身份认证后,客户端便可以传送敏感数据。这意味着,在此之前,客户端无需知道是否会使用证书进行认证,因此可以安全地仅在服务器配置中指定这一点。 - 所有SSL选项都带来了加密和密钥交换的负荷,因此必须在性能和安全性之间做出平衡。不同sslmode值所保护的风险,以及它们是怎样看待安全性和负荷的。 + 所有 SSL 选项都会产生加密和密钥交换的开销,因此必须在性能与安全性之间作出权衡。 说明了不同 sslmode 值所能防范的风险,以及它们所表达的对安全性和开销的取舍。
@@ -6748,7 +6373,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) sslmode 窃听保护 - 中间人攻击防护 + MITM 防护 声明 @@ -6759,7 +6384,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) disable - 我不关心安全性,并且我不想为加密增加负荷。 + 我不关心安全性,并且我不想为加密增加开销。 @@ -6767,7 +6392,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) allow 可能 - 我不关心安全性,但如果服务器坚持,我将承担加密带来的负荷。 + 我不关心安全性,但如果服务器坚持,我将承担加密带来的开销。 @@ -6775,7 +6400,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) prefer 可能 - 我不关心安全性,但如果服务器支持,我希望承担加密带来的负荷。 + 我不关心加密,但如果服务器支持,我希望承担加密带来的开销。 @@ -6783,7 +6408,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) require - 我想要对数据加密,并且我接受因此带来的负荷。我信任该网络会保证我总是连接到想要连接的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我信任该网络会保证我总是连接到想要连接的服务器。 @@ -6791,7 +6416,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-ca 取决于 CA 策略 - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器。 @@ -6799,7 +6424,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-full - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 @@ -6808,11 +6433,11 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
- verify-caverify-full之间的区别取决于根CA的策略。如果使用了一个公共CAverify-ca允许连接到那些可能已经被其他人注册到该CA的服务器。在这种情况下,总是应该使用verify-full。如果使用了一个本地CA或者甚至是一个自签名的证书,使用verify-ca常常就可以提供足够的保护。 + verify-caverify-full之间的区别取决于根CA的策略。如果使用了一个公共CAverify-ca允许连接到那些可能已经被其他人注册到该CA的服务器。在这种情况下,总是应该使用verify-full。如果使用了一个本地CA或者甚至是一个自签名的证书,使用verify-ca常常就可以提供足够的保护。 - sslmode的默认值是prefer。如表中所示,这在安全性的角度来说没有意义,并且它只承诺可能的性能负荷。提供它作为默认值只是为了向后兼容,并且我们不推荐在安全部署中使用它。 + sslmode 的默认值是 prefer。如表所示,从安全角度看,这一设置没有意义;它只会在可能时带来性能开销。将其作为默认值仅出于向后兼容的考虑,不建议在有安全要求的部署中使用。 @@ -6854,8 +6479,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) ~/.postgresql/root.crt - 可信的证书机构 - 检查服务器证书是由一个可信的证书机构签发 + 受信任的证书机构 + 检查服务器证书是由一个受信任的证书机构签发 @@ -6874,9 +6499,9 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) SSL 库初始化 - 如果您的应用程序初始化libssl和/或libcrypto库,并且libpq - 构建时带有SSL支持,您应该调用告诉libpq - libssl和/或libcrypto库已被您的应用程序初始化,以便 + 如果你的应用程序初始化libssl和/或libcrypto库,并且libpq + 构建时带有SSL支持,你应该调用告诉libpq + libssl和/或libcrypto库已被你的应用程序初始化,以便 libpq不会再初始化这些库。 但是,当使用OpenSSL版本1.1.0或更高版本时,无需这样做,因为重复初始化不再成问题。 @@ -6888,7 +6513,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 允许应用选择要初始化哪个安全性库。 + 允许应用程序选择要初始化的安全库。 void PQinitOpenSSL(int do_ssl, int do_crypto); @@ -6912,7 +6537,7 @@ void PQinitOpenSSL(int do_ssl, int do_crypto); PQinitSSLPQinitSSL - 允许应用选择要初始化哪个安全性库。 + 允许应用程序选择要初始化的安全库。 void PQinitSSL(int do_ssl); @@ -6938,7 +6563,7 @@ void PQinitSSL(int do_ssl); - 在线程化程序中的行为 + 多线程程序中的行为 线程 @@ -6972,7 +6597,9 @@ int PQisthreadsafe(); PGresult对象在创建后通常是只读的,因此可以在线程之间自由传递。不过,如果你使用中描述的任何会修改PGresult的函数,则需要自行避免对同一个PGresult执行并发操作。 - 已弃用的 函数不是线程安全的,不应在多线程程序中使用。可以用 替代 ,用 替代 + + 已弃用的函数 不是线程安全的,不应在多线程程序中使用。 可以用 替代; 可以用 替代。 + 如果你在应用程序中使用 Kerberos(除了libpq内部之外),则需要在 Kerberos 调用周围加锁,因为 Kerberos 函数不是线程安全的。可参考libpq源代码中的PQregisterThreadLock函数,它提供了一种在libpq与应用程序之间协作加锁的方法。 @@ -6981,7 +6608,7 @@ int PQisthreadsafe(); - 编译 <application>libpq</application> 程序 + 构建 <application>libpq</application> 程序 编译 @@ -6989,16 +6616,16 @@ int PQisthreadsafe(); - 要编译(即编译并且链接)一个使用libpq的程序,你需要做下列所有的事情: + 要构建(即编译和链接)一个使用 libpq 的程序,需要完成以下所有步骤: - 包括libpq-fe.h头文件: + 包含 libpq-fe.h 头文件: #include <libpq-fe.h> - 如果你无法这样做,那么你通常会从你的编译器得到像这样的错误消息: +如果没有这样做,编译器通常会给出类似以下内容的错误消息: foo.c: In function `main': foo.c:34: `PGconn' undeclared (first use in this function) @@ -7007,24 +6634,24 @@ foo.c:54: `CONNECTION_BAD' undeclared (first use in this function) foo.c:68: `PGRES_COMMAND_OK' undeclared (first use in this function) foo.c:95: `PGRES_TUPLES_OK' undeclared (first use in this function) - + - 通过为你的编译器提供-Idirectory选项,向你的编译器指出PostgreSQL头文件安装在哪里(在某些情况下编译器默认将查看该目录,因此你可以忽略这个选项)。例如你的编译命令行可能看起来像: + 向编译器提供 -Idirectory 选项,指定 PostgreSQL 头文件的安装目录。(某些情况下,编译器默认会搜索该目录,此时可以省略这个选项。)例如,编译命令行可以是: cc -c -I/usr/local/pgsql/include testprog.c - 如果你在使用 makefile,那么把该选项加到CPPFLAGS变量中: +如果使用 makefile,请将该选项添加到 CPPFLAGS 变量中: CPPFLAGS += -I/usr/local/pgsql/include - + 如果你的程序可能由其他用户编译,那么你不应该像那样硬编码目录位置。你可以运行工具pg_configpg_configwith libpq在本地系统上找出头文件在哪里: + sortas="libpq">用于 libpq在本地系统上找出头文件在哪里: $ pg_config --includedir /usr/local/include @@ -7032,8 +6659,7 @@ CPPFLAGS += -I/usr/local/pgsql/include - 如果你安装了pkg-configpkg-configwith - libpq,你可以运行: + 如果你安装了pkg-configpkg-config用于 libpq,你可以运行: $ pkg-config --cflags libpq -I/usr/local/include @@ -7042,20 +6668,20 @@ CPPFLAGS += -I/usr/local/pgsql/include - 无法为编译器指定正确的选项将导致一个错误消息,例如: + 未向编译器指定正确的选项将导致类似以下内容的错误消息: testlibpq.c:8:22: libpq-fe.h: No such file or directory - +
- 当链接最终的程序时,指定选项-lpq,这样libpq库会被编译进去,也可以用选项-Ldirectory向编译器指出libpq库所在的位置(再次,编译器将默认搜索某些目录)。为了最大的可移植性,将选项放在选项前面。例如: + 链接最终程序时,指定 -lpq 选项以链接 libpq 库,同时指定 -Ldirectory 选项,告知编译器 libpq 库所在的目录。(同样,编译器默认会搜索某些目录。)为获得最大的可移植性,请将 选项放在 选项之前。例如: cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq - +
你也可以使用pg_config找出库目录: @@ -7082,7 +6708,7 @@ testlibpq.o(.text+0x60): undefined reference to `PQsetdbLogin' testlibpq.o(.text+0x71): undefined reference to `PQstatus' testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage'
- 这意味着你忘了 . + 这意味着你忘记了 /usr/bin/ld: cannot find -lpq @@ -7099,7 +6725,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' 示例程序 - 这些示例和其他示例可以在源代码发布的src/test/examples目录中找到。 + 这些示例和其他示例可在源代码发行包的src/test/examples目录中找到。 @@ -7114,7 +6740,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' * * testlibpq.c * - * Test the C version of libpq, the PostgreSQL frontend library. + * 测试 PostgreSQL 前端库 libpq 的 C 语言版本。 */ #include #include @@ -7138,26 +6764,25 @@ main(int argc, char **argv) j; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -7168,19 +6793,17 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Our test case here involves using a cursor, for which we must be inside - * a transaction block. We could do the whole thing with a single - * PQexec() of "select * from pg_database", but that's too trivial to make - * a good example. + * 这里的测试用例使用游标,因此必须处于事务块内。 + * 只需调用一次 PQexec() 执行 "select * from pg_database" 就能完成全部操作, + * 但这太简单了,不足以作为一个好的示例。 */ - /* Start a transaction block */ + /* 开始一个事务块 */ res = PQexec(conn, "BEGIN"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -7191,7 +6814,7 @@ main(int argc, char **argv) PQclear(res); /* - * Fetch rows from pg_database, the system catalog of databases + * 从数据库系统目录 pg_database 中获取行 */ res = PQexec(conn, "DECLARE myportal CURSOR FOR select * from pg_database"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -7210,13 +6833,13 @@ main(int argc, char **argv) exit_nicely(conn); } - /* first, print out the attribute names */ + /* 首先,打印属性名 */ nFields = PQnfields(res); for (i = 0; i < nFields; i++) printf("%-15s", PQfname(res, i)); printf("\n\n"); - /* next, print out the rows */ + /* 接着,打印各行 */ for (i = 0; i < PQntuples(res); i++) { for (j = 0; j < nFields; j++) @@ -7226,15 +6849,15 @@ main(int argc, char **argv) PQclear(res); - /* close the portal ... we don't bother to check for errors ... */ + /* 关闭 portal……这里不再检查错误…… */ res = PQexec(conn, "CLOSE myportal"); PQclear(res); - /* end the transaction */ + /* 结束事务 */ res = PQexec(conn, "END"); PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -7254,15 +6877,15 @@ main(int argc, char **argv) * * * testlibpq2.c - * Test of the asynchronous notification interface + * 测试异步通知接口 * - * Start this program, then from psql in another window do + * 启动此程序,然后在另一个窗口中通过 psql 执行 * NOTIFY TBL2; - * Repeat four times to get this program to exit. + * 重复四次后,此程序便会退出。 * - * Or, if you want to get fancy, try this: - * populate a database with the following commands - * (provided in src/test/examples/testlibpq2.sql): + * 或者,可以尝试更复杂的示例: + * 使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq2.sql 中): * * CREATE SCHEMA TESTLIBPQ2; * SET search_path = TESTLIBPQ2; @@ -7271,7 +6894,7 @@ main(int argc, char **argv) * CREATE RULE r1 AS ON INSERT TO TBL1 DO * (INSERT INTO TBL2 VALUES (new.i); NOTIFY TBL2); * - * Start this program, then from psql do this four times: + * 启动此程序,然后通过 psql 将以下命令执行四次: * * INSERT INTO TESTLIBPQ2.TBL1 VALUES (10); */ @@ -7308,26 +6931,25 @@ main(int argc, char **argv) int nnotifies; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -7338,13 +6960,12 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Issue LISTEN command to enable notifications from the rule's NOTIFY. + * 发出 LISTEN 命令,以接收规则中的 NOTIFY 发出的通知。 */ res = PQexec(conn, "LISTEN TBL2"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -7355,14 +6976,13 @@ main(int argc, char **argv) } PQclear(res); - /* Quit after four notifies are received. */ + /* 收到四次通知后退出。 */ nnotifies = 0; while (nnotifies < 4) { /* - * Sleep until something happens on the connection. We use select(2) - * to wait for input, but you could also use poll() or similar - * facilities. + * 休眠,直到连接上有事件发生。这里使用 select(2) 等待输入, + * 也可以使用 poll() 或类似机制。 */ int sock; fd_set input_mask; @@ -7370,7 +6990,7 @@ main(int argc, char **argv) sock = PQsocket(conn); if (sock < 0) - break; /* shouldn't happen */ + break; /* 不应发生 */ FD_ZERO(&input_mask); FD_SET(sock, &input_mask); @@ -7381,7 +7001,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Now check for input */ + /* 现在检查是否有输入 */ PQconsumeInput(conn); while ((notify = PQnotifies(conn)) != NULL) { @@ -7396,7 +7016,7 @@ main(int argc, char **argv) fprintf(stderr, "Done.\n"); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -7416,10 +7036,10 @@ main(int argc, char **argv) * * * testlibpq3.c - * Test out-of-line parameters and binary I/O. + * 测试在 SQL 命令文本之外独立传递的参数和二进制 I/O。 * - * Before running this, populate a database with the following commands - * (provided in src/test/examples/testlibpq3.sql): + * 运行前,使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq3.sql 中): * * CREATE SCHEMA testlibpq3; * SET search_path = testlibpq3; @@ -7428,7 +7048,7 @@ main(int argc, char **argv) * INSERT INTO test1 values (1, 'joe''s place', '\000\001\002\003\004'); * INSERT INTO test1 values (2, 'ho there', '\004\003\002\001\000'); * - * The expected output is: + * 预期输出为: * * tuple 0: got * i = (4 bytes) 1 @@ -7452,7 +7072,7 @@ main(int argc, char **argv) #include #include "libpq-fe.h" -/* for ntohl/htonl */ +/* 用于 ntohl/htonl */ #include #include @@ -7464,9 +7084,8 @@ exit_nicely(PGconn *conn) } /* - * This function prints a query result that is a binary-format fetch from - * a table defined as in the comment above. We split it out because the - * main() function uses it twice. + * 此函数打印从上面注释所定义的表中以二进制格式获取的查询结果。 + * 由于 main() 会使用它两次,因此将它单独提取成一个函数。 */ static void show_binary_results(PGresult *res) @@ -7477,7 +7096,7 @@ show_binary_results(PGresult *res) t_fnum, b_fnum; - /* Use PQfnumber to avoid assumptions about field order in result */ + /* 使用 PQfnumber,以避免对结果中的字段顺序作出假设 */ i_fnum = PQfnumber(res, "i"); t_fnum = PQfnumber(res, "t"); b_fnum = PQfnumber(res, "b"); @@ -7490,24 +7109,22 @@ show_binary_results(PGresult *res) int blen; int ival; - /* Get the field values (we ignore possibility they are null!) */ + /* 获取字段值(这里忽略它们可能为 null 的情况!) */ iptr = PQgetvalue(res, i, i_fnum); tptr = PQgetvalue(res, i, t_fnum); bptr = PQgetvalue(res, i, b_fnum); /* - * The binary representation of INT4 is in network byte order, which - * we'd better coerce to the local byte order. + * INT4 的二进制表示采用网络字节序,最好将其转换为本机字节序。 */ ival = ntohl(*((uint32_t *) iptr)); /* - * The binary representation of TEXT is, well, text, and since libpq - * was nice enough to append a zero byte to it, it'll work just fine - * as a C string. + * TEXT 的二进制表示就是文本,而 libpq 会在其后追加一个零字节, + * 因此可以直接将其用作 C 字符串。 * - * The binary representation of BYTEA is a bunch of bytes, which could - * include embedded nulls so we have to pay attention to field length. + * BYTEA 的二进制表示是一组字节,其中可能嵌有零字节, + * 因此必须注意字段长度。 */ blen = PQgetlength(res, i, b_fnum); @@ -7535,26 +7152,25 @@ main(int argc, char **argv) uint32_t binaryIntVal; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SET search_path = testlibpq3"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -7565,27 +7181,25 @@ main(int argc, char **argv) PQclear(res); /* - * The point of this program is to illustrate use of PQexecParams() with - * out-of-line parameters, as well as binary transmission of data. + * 此程序旨在演示如何使用 PQexecParams() 在 SQL 命令文本之外独立传递参数, + * 以及如何以二进制方式传输数据。 * - * This first example transmits the parameters as text, but receives the - * results in binary format. By using out-of-line parameters we can avoid - * a lot of tedious mucking about with quoting and escaping, even though - * the data is text. Notice how we don't have to do anything special with - * the quote mark in the parameter value. + * 第一个示例以文本形式传输参数,但以二进制格式接收结果。 + * 通过在 SQL 命令文本之外独立传递参数,即使数据是文本,也可以避免 + * 许多繁琐的引号和转义处理。注意,参数值中的引号无需任何特殊处理。 */ - /* Here is our out-of-line parameter value */ + /* 这是在 SQL 命令文本之外独立传递的参数值 */ paramValues[0] = "joe's place"; res = PQexecParams(conn, "SELECT * FROM test1 WHERE t = $1", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, - NULL, /* don't need param lengths since text */ - NULL, /* default to all text params */ - 1); /* ask for binary results */ + NULL, /* 文本参数无需指定长度 */ + NULL, /* 默认所有参数均为文本 */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -7599,31 +7213,29 @@ main(int argc, char **argv) PQclear(res); /* - * In this second example we transmit an integer parameter in binary form, - * and again retrieve the results in binary form. + * 第二个示例以二进制形式传输一个整数参数,并同样以二进制形式获取结果。 * - * Although we tell PQexecParams we are letting the backend deduce - * parameter type, we really force the decision by casting the parameter - * symbol in the query text. This is a good safety measure when sending - * binary parameters. + * 虽然我们告诉 PQexecParams 让后端推断参数类型,但实际上, + * 查询文本中的参数符号经过强制类型转换,因此其类型已经确定。 + * 发送二进制参数时,这是一项良好的安全措施。 */ - /* Convert integer value "2" to network byte order */ + /* 将整数值 "2" 转换为网络字节序 */ binaryIntVal = htonl((uint32_t) 2); - /* Set up parameter arrays for PQexecParams */ + /* 为 PQexecParams 设置参数数组 */ paramValues[0] = (char *) &binaryIntVal; paramLengths[0] = sizeof(binaryIntVal); - paramFormats[0] = 1; /* binary */ + paramFormats[0] = 1; /* 二进制 */ res = PQexecParams(conn, "SELECT * FROM test1 WHERE i = $1::int4", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, paramLengths, paramFormats, - 1); /* ask for binary results */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -7636,7 +7248,7 @@ main(int argc, char **argv) PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; diff --git a/zh/15/lobj.sgml b/zh/15/lobj.sgml index bb405a74..c43e5fda 100644 --- a/zh/15/lobj.sgml +++ b/zh/15/lobj.sgml @@ -3,8 +3,8 @@ 大对象 - large object - BLOBlarge object + 大对象 + BLOB大对象 PostgreSQL提供一种大对象机制,允许以流式方式访问存储在专用大对象结构中的用户数据。在处理大到无法方便地整体操作的数据值时,这种流式访问非常有用。 @@ -19,7 +19,7 @@ TOAST - versus large objects + 与大对象对比 @@ -190,11 +190,11 @@ inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE); int lo_write(PGconn *conn, int fd, const char *buf, size_t len); - 将buf中的len字节(其大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 + 将buf中的len字节(缓冲区大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -211,7 +211,7 @@ int lo_read(PGconn *conn, int fd, char *buf, size_t len); - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -231,7 +231,7 @@ int lo_lseek(PGconn *conn, int fd, int offset, int whence); lo_lseek64 当处理大小可能超过 2 GB 的大对象时,改用 -int64_t lo_lseek64(PGconn *conn, int fd, int64_t offset, int whence); +pg_int64 lo_lseek64(PGconn *conn, int fd, pg_int64 offset, int whence); 该函数的行为与lo_lseek相同,但它既可以接受大于 2 GB 的offset,也可以返回大于 2 GB 的结果。请注意,如果新位置指针会大于 2 GB,lo_lseek将失败。
@@ -258,7 +258,7 @@ int lo_tell(PGconn *conn, int fd); lo_tell64 当处理大小可能超过 2 GB 的大对象时,改用 -int64_t lo_tell64(PGconn *conn, int fd); +pg_int64 lo_tell64(PGconn *conn, int fd); 该函数的行为与lo_tell相同,但它可以返回大于 2 GB 的结果。请注意,如果当前读/写位置大于 2 GB,lo_tell将失败。
@@ -277,7 +277,7 @@ int64_t lo_tell64(PGconn *conn, int fd); int lo_truncate(PGconn *conn, int fd, size_t len); - 该函数把大对象描述符fd截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用空字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 + 该函数把大对象描述符fd对应的大对象截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用零字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 @@ -292,7 +292,7 @@ int lo_truncate(PGconn *conn, int fd, size_t len); lo_truncate64 当处理大小可能超过 2 GB 的大对象时,改用 -int lo_truncate64(PGconn *conn, int fd, int64_t len); +int lo_truncate64(PGconn *conn, int fd, pg_int64 len); 该函数的行为与lo_truncate相同,但它可以接受大于 2 GB 的len值。 @@ -426,16 +426,16 @@ CREATE TABLE image ( raster oid ); -SELECT lo_creat(-1); -- returns OID of new, empty large object +SELECT lo_creat(-1); -- 返回新建的空大对象的 OID -SELECT lo_create(43213); -- attempts to create large object with OID 43213 +SELECT lo_create(43213); -- 尝试创建 OID 为 43213 的大对象 -SELECT lo_unlink(173454); -- deletes large object with OID 173454 +SELECT lo_unlink(173454); -- 删除 OID 为 173454 的大对象 INSERT INTO image (name, raster) VALUES ('beautiful image', lo_import('/etc/motd')); -INSERT INTO image (name, raster) -- same as above, but specify OID to use +INSERT INTO image (name, raster) -- 与上例相同,但指定要使用的 OID VALUES ('beautiful image', lo_import('/etc/motd', 68583)); SELECT lo_export(image.raster, '/tmp/motd') FROM image @@ -444,7 +444,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image - 服务器端的lo_importlo_export函数与其客户端对应函数的行为差异很大。这两个函数在服务器的文件系统中读写文件,使用数据库所有者的权限。因此,默认情况下它们的使用仅限于超级用户。相比之下,客户端导入和导出函数在客户端的文件系统中读写文件,使用客户端程序的权限。客户端函数不需要任何数据库权限,除了读取或写入相关大对象所需的权限。 + 服务器端的lo_importlo_export函数与其客户端对应函数的行为差异很大。这两个函数在服务器的文件系统中读写文件,使用运行数据库服务器的操作系统用户的权限。因此,默认情况下它们的使用仅限于超级用户。相比之下,客户端导入和导出函数在客户端的文件系统中读写文件,使用客户端程序的权限。客户端函数不需要任何数据库权限,除了读取或写入相关大对象所需的权限。 @@ -463,7 +463,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image 示例程序 - 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行版的src/test/examples/testlo.c中找到。 + 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行包的src/test/examples/testlo.c中找到。 @@ -472,13 +472,13 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /*----------------------------------------------------------------- * * testlo.c - * test using large objects with libpq + * 测试使用 libpq 操作大对象 * * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group * Portions Copyright (c) 1994, Regents of the University of California * * - * IDENTIFICATION + * 标识 * src/test/examples/testlo.c * *----------------------------------------------------------------- @@ -498,7 +498,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /* * importFile - - * import file "in_filename" into database as large object "lobjOid" + * 将文件 "in_filename" 作为大对象 "lobjOid" 导入数据库 * */ static Oid @@ -512,16 +512,16 @@ importFile(PGconn *conn, char *filename) int fd; /* - * open the file to be read in + * 打开要读取的文件 */ fd = open(filename, O_RDONLY, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"\n", filename); } /* - * create the large object + * 创建大对象 */ lobjId = lo_creat(conn, INV_READ | INV_WRITE); if (lobjId == 0) @@ -530,7 +530,7 @@ importFile(PGconn *conn, char *filename) lobj_fd = lo_open(conn, lobjId, INV_WRITE); /* - * read in from the Unix file and write to the inversion file + * 从 Unix 文件读取数据并写入大对象 */ while ((nbytes = read(fd, buf, BUFSIZE)) > 0) { @@ -568,7 +568,7 @@ pickout(PGconn *conn, Oid lobjId, int start, int len) fprintf(stderr, ">>> %s", buf); nread += nbytes; if (nbytes <= 0) - break; /* no more data? */ + break; /* 没有更多数据? */ } free(buf); fprintf(stderr, "\n"); @@ -614,7 +614,7 @@ overwrite(PGconn *conn, Oid lobjId, int start, int len) /* * exportFile - - * export large object "lobjOid" to file "out_filename" + * 将大对象 "lobjOid" 导出到文件 "out_filename" * */ static void @@ -627,24 +627,24 @@ exportFile(PGconn *conn, Oid lobjId, char *filename) int fd; /* - * open the large object + * 打开大对象 */ lobj_fd = lo_open(conn, lobjId, INV_READ); if (lobj_fd < 0) fprintf(stderr, "cannot open large object %u", lobjId); /* - * open the file to be written to + * 打开要写入的文件 */ fd = open(filename, O_CREAT | O_WRONLY | O_TRUNC, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"", filename); } /* - * read in from the inversion file and write to the Unix file + * 从大对象读取数据并写入 Unix 文件 */ while ((nbytes = lo_read(conn, lobj_fd, buf, BUFSIZE)) > 0) { @@ -689,18 +689,18 @@ main(int argc, char **argv) out_filename = argv[3]; /* - * set up the connection + * 建立连接 */ conn = PQsetdb(NULL, NULL, NULL, NULL, database); - /* check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) diff --git a/zh/15/monitoring.sgml b/zh/15/monitoring.sgml index a39037a5..627f20b1 100644 --- a/zh/15/monitoring.sgml +++ b/zh/15/monitoring.sgml @@ -3755,7 +3755,8 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i checksum_failures bigint - 在此数据库(或共享对象)中检测到的数据页校验码失败数,如果没有启用数据校验码则为NULL。 + 在此数据库(或共享对象)中检测到的数据页校验和失败次数,如果未启用 + 数据校验和则为 NULL。 @@ -3764,7 +3765,8 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i checksum_last_failure timestamp with time zone - 在此数据库(或共享对象)中检测到最后一个数据页校验码失败的时间,如果没有启用数据校验码则为NULL。 + 在此数据库(或共享对象)中最后一次检测到数据页校验和失败的时间, + 如果未启用数据校验和则为 NULL。 diff --git a/zh/15/pgtrgm.sgml b/zh/15/pgtrgm.sgml index bd603763..b5230e5a 100644 --- a/zh/15/pgtrgm.sgml +++ b/zh/15/pgtrgm.sgml @@ -512,11 +512,11 @@ SELECT * FROM test_trgm WHERE t ~ '(foo|bar)'; - 文本搜索集成 + 文本检索集成 与全文索引结合使用时,三字符组匹配是非常有用的工具。 - 尤其是,它有助于识别那些因拼写错误而无法被全文搜索机制直接匹配的输入词。 + 尤其是,它有助于识别那些因拼写错误而无法被全文检索机制直接匹配的输入词。 diff --git a/zh/15/protocol.sgml b/zh/15/protocol.sgml index c0a2fb6d..a998ee2e 100644 --- a/zh/15/protocol.sgml +++ b/zh/15/protocol.sgml @@ -26,15 +26,15 @@ 概述 - 协议在启动和正常操作过程中有不同的阶段。在启动阶段里,前端打开一个到服务器的连接并且认证自身以满足服务器(这可能涉及到一条或多条消息,取决于使用的认证方法)。 如果一切正常,服务器就发送状态信息给前端,并最后进入正常操作。除了最初的启动请求消息之外,协议的这个部分是服务器驱动的。 + 协议分为启动和正常操作两个阶段。在启动阶段,前端打开到服务器的连接,并完成服务器所要求的认证。(这可能只涉及一条消息,也可能因所用认证方法不同而需要多条消息。)如果一切顺利,服务器随后会向前端发送状态信息,并最终进入正常操作。除最初的启动请求消息外,协议的这一部分由服务器驱动。 - 在正常操作中,前端发送查询和其它命令到后端,然后后端返回查询结果和其它响应。在少数几种情况(比如NOTIFY)中,后端会发送未被请求的消息,但这个会话中的绝大多部分都是由前端请求驱动的。 + 在正常操作中,前端向后端发送查询及其他命令,后端则返回查询结果和其他响应。少数情况下(例如 NOTIFY),后端会发送未请求的消息,但会话中的绝大多数交互仍由前端请求驱动。 - 会话的终止通常是由前端来选择的,但是也可以在某些情况下由后端强制执行。不管在那种情况下,如果后端关闭连接,那么它将在退出之前回滚所有打开的(未完成的)事务。 + 会话通常由前端选择终止,但在某些情况下也可能由后端强制终止。无论哪种情况,后端关闭连接时,都会在退出前回滚所有打开的(未完成的)事务。 @@ -73,9 +73,7 @@ 整个执行周期包括一个解析步骤,它从文本查询字符串创建预备语句; 一个绑定步骤,它根据预备语句和所需参数值创建 portal; - 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询 - (SELECTSHOW等),可以要求执行步骤只取回 - 有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 + 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询(SELECTSHOW等),可以要求执行步骤只取回有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 @@ -92,8 +90,8 @@ - 文本形式的数值是特定数据类型的输入/输出转换函数生成或接受的任何字符串。在传输形式上,字符串没有末尾空字符;如果前端要想把收到的值当作C字符串处理,那么必须自己加上一个(顺便说一下,文本格式不允许嵌入空字符)。 - + 值的文本表示是相应数据类型的输入/输出转换函数生成和接受的字符串。在传输形式中,值的末尾没有空字符;前端若要将收到的值作为 C 字符串处理,必须自行添加一个。(文本格式也不允许内嵌空字符。) + 整数的二进制表示采用网络字节序(最高有效字节在前)。至于其他数据类型,请查阅文档或源代码了解其二进制表示形式。要注意,复杂数据类型的二进制表示可能会在不同服务器版本之间发生变化;文本格式通常是可移植性更好的选择。 @@ -114,7 +112,7 @@ 启动 - 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,判断该连接在初步上是否可接受,以及是否需要额外的认证。 + 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,初步判断是否接受该连接,以及需要何种额外认证(如果需要)。 @@ -242,11 +240,8 @@ NegotiateProtocolVersion - 如果服务器不支持客户端请求的协议次版本,但支持更早的协议版本,就会发送该消息并指明其支持的最高次版本。如果客户端在启动包中请求了不受支持的协议选项(即以 _pq_. 开头),也会发送该消息。 - - - 在该消息之后,认证会继续使用服务器指明的协议版本。如果客户端不支持该较旧版本,就应立即关闭连接。如果服务器没有发送该消息,则表示它支持客户端请求的协议版本以及所有协议选项。 - + 服务器不支持客户端请求的协议次版本,但支持更早的协议版本;此消息指明其所支持的最高次版本。如果客户端在启动包中请求了不受支持的协议选项(即以 _pq_. 开头的选项),也会发送此消息。此消息后面会跟随一条 ErrorResponse 或一条指示认证成功或失败的消息。 + @@ -275,9 +270,7 @@ 该消息提供密钥数据。如果前端希望稍后发送取消请求,就必须保存这些数据。前端不应响应该消息,而应继续等待 ReadyForQuery 消息。 - - PostgreSQL 服务器总会发送该消息,但已知一些不支持查询取消的第三方后端实现不会发送。 - + @@ -368,7 +361,7 @@ 表示即将返回行作为对SELECTFETCH等查询的响应。 - 此消息的内容描述了行的列布局。这将跟随每个返回给前端的行的DataRow消息。 + 此消息的内容描述了行的列布局。该消息之后,每个返回给前端的行都对应一条 DataRow 消息。 @@ -424,9 +417,7 @@ - - 对 SELECT 查询(或其他返回行集的查询,如 EXPLAINSHOW)的响应,通常包含 RowDescription、零条或多条 DataRow 消息,以及最后的 CommandComplete。向前端 COPY 或从前端 COPY 会调用中描述的特殊协议。所有其他类型的查询通常只产生一条 CommandComplete 消息。 - + SELECT 查询(或其他返回行集的查询,如 EXPLAINSHOW)的响应通常包含 RowDescription、零条或多条 DataRow 消息,以及最后的 CommandComplete。在前端与服务器之间执行 COPY 输入或输出时,会使用 所述的特殊协议。所有其他类型的查询通常只产生一条 CommandComplete 消息。 由于查询字符串可能包含若干条查询(以分号分隔),因此在后端完成整个查询字符串的处理之前,可能会出现多个这样的响应序列。只有在整个字符串处理完毕且后端已准备好接受新的查询字符串时,才会发出 ReadyForQuery 消息。 @@ -449,15 +440,15 @@ - 我们建议的方法是把前端代码写成状态机的风格,它可以在任何时刻接受任何有意义的消息类型,而不是假设消息的序列总是准确。 - + 建议以状态机的方式编写前端,使其能够在任何合理的时机接收相应类型的消息,而不把消息确切顺序的假设写死在代码中。 + 一个简单查询中的多条语句 - 当一个简单查询消息中包含多于一条SQL语句(被分号分隔)时,那些语句会被当做一个事务中执行,除非其中包括显式事务控制命令来强制不同的行为。例如,如果消息包括 + 当一个简单查询消息中包含多于一条SQL语句(被分号分隔)时,这些语句会作为单个事务执行,除非其中包括显式事务控制命令来强制不同的行为。例如,如果消息包括 INSERT INTO mytable VALUES(1); SELECT 1/0; @@ -479,15 +470,15 @@ SELECT 1/0; - 这种行为通过在一个隐式事务块中的一个多语句Query消息中运行那些语句来实现,除非它们运行在某个显式事务块中。隐式事务块与常规事务块之间的区别在于隐式块会在Query消息结束时自动被关闭,或者是在没有错误的情况下由一个隐式提交关闭,或者是在有错误时由一个隐式的回滚关闭。这类似于一个语句自己执行(当不在事务块中时)时发生的隐式提交或回滚。 - + 这种行为的实现方式是:除非已有显式事务块可供这些语句执行,否则就在一个隐式事务块中执行多语句 Query 消息中的语句。隐式事务块与常规事务块的主要区别在于,隐式块会在 Query 消息结束时自动关闭:没有错误时隐式提交,发生错误时隐式回滚。这类似于单独执行一条语句(不在事务块中)时发生的隐式提交或回滚。 + - 如果会话已经在一个事务块中,作为前面某个消息中BEGIN的结果,那么Query消息会简单地继续那个事务块,不管该消息包含一个语句还是多个语句。不过,如果该Query消息包含一个关闭现有事务块的COMMIT或者ROLLBACK,那么任何接下来的语句都会在一个隐式事务块中被执行。反过来,如果在多语句Query消息中出现一个BEGIN,那么它会开始一个常规事务块,这个常规事务块将只能被一个显式的COMMIT或者ROLLBACK终止,不管这两种命令是出现在这个Query消息还是后面的一个Query消息中。如果BEGIN跟在一些作为隐式事务块执行的语句后面,那些语句不会被立刻提交。实际上,它们会被包括到新的常规事务块中。 + 如果会话因前面某条消息中的BEGIN而已经处于事务块中,那么 Query 消息会继续该事务块,不管该消息包含一个语句还是多个语句。不过,如果该Query消息包含一个关闭现有事务块的COMMIT或者ROLLBACK,那么任何接下来的语句都会在一个隐式事务块中被执行。反过来,如果在多语句Query消息中出现一个BEGIN,那么它会开始一个常规事务块,这个常规事务块将只能被一个显式的COMMIT或者ROLLBACK终止,不管这两种命令是出现在这个Query消息还是后面的一个Query消息中。如果BEGIN跟在一些作为隐式事务块执行的语句后面,那些语句不会被立刻提交。实际上,它们会被包括到新的常规事务块中。 - 出现在一个隐式事务块中的COMMIT或者ROLLBACK会被正常执行并且关闭该隐式块。不过,由于没有先前的BEGIN配对的COMMIT或者ROLLBACK表示一种错误,所以将会发出一个警告。如果后面还有更多语句,将会为它们开始一个新的隐式事务块。 + 出现在一个隐式事务块中的COMMIT或者ROLLBACK会被正常执行并且关闭该隐式块。不过,由于没有先前的BEGIN配对的COMMIT或者ROLLBACK可能表示误操作,所以会发出警告。如果后面还有更多语句,将会为它们开始一个新的隐式事务块。 @@ -495,17 +486,17 @@ SELECT 1/0; - 记住,不管任何事务控制命令存不存在,Query消息的执行会在第一个错误时停止。因此,对于下面的在一个Query消息中的示例 + 请记住,无论消息中是否包含事务控制命令,Query 消息的执行都会在第一个错误处停止。例如,单条 Query 消息包含以下内容时: BEGIN; SELECT 1/0; ROLLBACK; - 会话中将留下一个失败的常规事务块,因为在出现除零错误后不会到达ROLLBACK。将需要另一个ROLLBACK把会话恢复到一种可用的状态。 - +会话会停留在失败的常规事务块内,因为发生除零错误后不会再执行ROLLBACK。需要另发一条ROLLBACK,才能将会话恢复到可用状态。 + - 另一种要注意的行为是,最初的词法和语法分析是在整个查询字符串被执行之前进行的。因此后面的语句中的简单错误(例如拼写错误的关键词)可能会阻止任何语句的执行。这通常对用户是不可见的,因为在当作一个隐式事务块执行时,这些语句不管怎样都会全部被回滚。不过,在尝试于一个多语句Query中执行多个事务时,这种现象可能是可见的。例如,如果一个拼写错误把我们之前的示例变成 + 另一种要注意的行为是,在执行任何语句之前,会先对整个查询字符串进行词法和语法分析。因此后面的语句中的简单错误(例如拼写错误的关键词)可能会阻止任何语句的执行。这通常对用户是不可见的,因为在当作一个隐式事务块执行时,这些语句不管怎样都会全部被回滚。不过,在尝试于一个多语句Query中执行多个事务时,这种现象可能是可见的。例如,如果一个拼写错误把我们之前的示例变成 BEGIN; INSERT INTO mytable VALUES(1); @@ -572,11 +563,11 @@ SELCT 1/0; - 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是执行不会导致后端发送 ReadyForQuery 或 RowDescription。 + 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是 Execute 不会导致后端发送 ReadyForQuery 或 RowDescription。 - 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息之一结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 + 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息中的恰好一条结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 @@ -591,7 +582,7 @@ SELCT 1/0; - 除了这些基本的、必须的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 + 除了这些基本的、必需的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 @@ -627,38 +618,32 @@ SELCT 1/0; - 流水线处理 + 管道化 - 流水线处理 + 管道化 协议规范 - 使用扩展查询协议允许流水线处理,这意味着发送一系列查询而无需等待先前的查询完成。 - 这减少了完成一系列操作所需的网络往返次数。然而,用户必须仔细考虑所需的行为,如果其中一步失败, - 因为后续查询已经在传输到服务器的过程中。 - + 扩展查询协议允许管道化,即连续发送一系列查询,而不等待先前查询完成。这减少了完成一组操作所需的网络往返次数。不过,用户必须仔细考虑其中某个步骤失败时所需的行为,因为后续查询已经在发往服务器的途中。 + - 处理这个问题的一种方法是将整个查询系列作为一个事务处理,即将其包装在BEGIN... - COMMIT中。然而,如果希望其中一些命令独立于其他命令提交,这并没有帮助。 - + 处理这个问题的一种方式是让整组查询成为单个事务,即用BEGIN ... COMMIT包围它们。不过,如果希望其中某些命令独立于其他命令提交,这种方式就无法满足要求。 + - 扩展查询协议提供了另一种管理这个问题的方式,即在依赖的步骤之间省略发送同步消息。 - 由于在错误后,后端会跳过命令消息直到找到同步消息,这允许在管道中的后续命令在前面的命令失败时自动跳过,而无需客户端明确地使用BEGINCOMMIT来管理。 - 管道中可以通过同步消息分隔独立可提交的段。 - + 扩展查询协议提供了另一种处理方式,即省略相互依赖的步骤之间的 Sync 消息。发生错误后,后端会跳过命令消息,直到遇到 Sync,因此当前面的命令失败时,管道中的后续命令便会自动跳过,而不必由客户端用BEGINCOMMIT显式管理。管道中可独立提交的各段可以用 Sync 消息分隔。 + - 如果客户端没有发出显式 BEGIN,则会启动一个隐式事务块。每个 Sync 通常会在前序步骤成功时导致隐式 COMMIT,失败时导致隐式 ROLLBACK。服务器只有在第一个命令结束且尚未收到 Sync 时,才能识别这种隐式事务块。有一些 DDL 命令(例如 CREATE DATABASE)不能在事务块内执行;若这类命令在管道中执行,除非它是某个 Sync 之后的第一条命令,否则会失败。此外,它成功后会强制立即提交以保持数据库一致性。因此,紧随这些命令之后的 Sync 除了返回 ReadyForQuery 外不会产生额外效果。 - + 如果客户端没有发出显式的BEGIN,那么每个 Sync 通常会在前序步骤成功时引发隐式的COMMIT,失败时引发隐式的ROLLBACK。不过,少数 DDL 命令(例如CREATE DATABASE)不能在事务块中执行。如果这类命令在管道中执行,除非它是管道中的第一条命令,否则会失败。此外,它成功后会强制立即提交,以保持数据库一致性。因此,紧随这类命令之后的 Sync 除了返回 ReadyForQuery 外,不产生其他效果。 + - 当使用这种方法时,必须通过计算ReadyForQuery消息的数量并等待达到发送的Syncs数量来确定管道的完成。 - 计算命令完成响应是不可靠的,因为其中一些命令可能会被跳过,因此不会产生完成消息。 - + 使用这种方式时,必须统计 ReadyForQuery 消息的数量,并等待该数量达到已发送的 Sync 消息数量,才能确定管道已完成。统计命令完成响应并不可靠,因为某些命令可能被跳过,因而不会产生完成消息。 + @@ -666,19 +651,19 @@ SELCT 1/0; 函数调用 - 函数调用子协议允许客户端请求一个对存在于数据库pg_proc系统表中的任意函数的直接调用。客户端必须在该函数上有执行的权限。 - + 函数调用子协议允许客户端请求直接调用数据库pg_proc系统目录中的任意函数。客户端必须具有该函数的执行权限。 + - 函数调用子协议是一个遗留的特性,在新代码里可能最好避免用它。类似的结果可以通过设置一个执行SELECT function($1, ...)的预备语句得到。这样函数调用流程就可以用 Bind/Execute 代替。 + 函数调用子协议是一个遗留的特性,在新代码里可能最好避免用它。类似的结果可以通过设置一个执行SELECT function($1, ...)的预备语句得到。这样函数调用周期就可以用 Bind/Execute 代替。 - 一个函数调用流程是由前端向后端发送一条FunctionCall消息初始化的。然后后端根据函数调用的结果发送一条或者更多响应消息,并且最后是一条ReadyForQuery响应消息。ReadyForQuery通知前端它可以安全地发送一个新的查询或者函数调用了。 - + 函数调用周期由前端向后端发送一条 FunctionCall 消息来启动。后端随后根据函数调用的结果发送一条或多条响应消息,最后发送一条 ReadyForQuery 响应消息。ReadyForQuery 告知前端,可以安全地发送新的查询或函数调用。 + 来自后端的可能的响应消息是: @@ -697,7 +682,7 @@ SELCT 1/0; FunctionCallResponse - 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者集合类型的结果)。 + 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者结果集合)。 @@ -732,7 +717,7 @@ SELCT 1/0; - 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(表示成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 + 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(允许成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 @@ -740,11 +725,11 @@ SELCT 1/0; - 在拷贝入模式下,后端将忽略所收到的Flush和Sync消息。收到任何其他非拷贝消息类型都会造成一个错误,它将导致上面所描述的拷贝入状态中断(Flush和Sync的例外是为了方便客户端库,它们总是在一个Execute消息之后发送Flush和Sync,而不检查被执行的命令是否为一个COPY FROM STDIN)。 - + 后端会忽略在拷贝入模式期间收到的 Flush 和 Sync 消息。收到任何其他非拷贝类型的消息都会构成错误,并按上述方式中止拷贝入状态。(Flush 和 Sync 的例外是为了方便那些总是在 Execute 消息之后发送 Flush 或 Sync、而不检查待执行命令是否为COPY FROM STDIN的客户端库。) + - 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句的时候初始化的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能退出传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 + 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句时启动的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能中止传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 @@ -752,16 +737,16 @@ SELCT 1/0; - 在CopyData消息中间可能会散布有NoticeResponse和ParameterStatus消息。前端必须处理这些情况,并且应该也为异步消息类型(参见)准备好。否则任何除CopyData或CopyDone之外的消息类型都会被认为是要中止拷贝出模式。 - + NoticeResponse 和 ParameterStatus 消息可能穿插在 CopyData 消息之间;前端必须处理这些情况,并应准备好处理其他异步消息类型(参见)。除此之外,可以将任何除 CopyData 或 CopyDone 以外的消息类型视为拷贝出模式的终止标志。 + - 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许数据以高速批量方式在客户端与服务器之间双向传输。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见。 + 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许高速批量地向服务器发送数据以及从服务器接收数据。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见 - CopyInResponse、CopyOutResponse和CopyBothResponse消息包括域和格式代码,域告诉前端每行的列数,而格式代码则用于具体每个列(就目前的实现而言,一个给定COPY操作中的所有列都将使用同样的格式,但是消息设计并不做这个假设)。 - + CopyInResponse、CopyOutResponse 和 CopyBothResponse 消息包含一些字段,用于告知前端每行的列数以及每列所使用的格式代码。(在当前实现中,同一次COPY操作的所有列都使用相同格式,但消息设计并不作此假设。) + @@ -789,8 +774,8 @@ SELCT 1/0; - 如果前端发出一个LISTEN命令, 那么无论何时在为同一个通道名NOTIFY时,后端将发送一个NotificationResponse消息(不要和NoticeResponse搞混!)。 - + 如果前端发出LISTEN命令,那么每当针对同一通道名执行NOTIFY命令时,后端都会发送一条 NotificationResponse 消息(不要与 NoticeResponse 混淆)。 + @@ -809,11 +794,11 @@ SELCT 1/0; - 要发出一条取消请求,前端打开一个与服务器的新连接并且发送一条CancelRequest消息, 而不是通常在新连接中经常发送的StartupMessage消息。服务器将处理这个请求然后关闭连接。 出于安全原因,对取消请求消息不做直接的响应。 - + 要发出取消请求,前端会新建到服务器的连接,并发送 CancelRequest 消息,而不是新连接通常发送的 StartupMessage 消息。服务器处理该请求后便会关闭连接。出于安全原因,服务器不会直接回复取消请求消息。 + - 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的关键数据(PID和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则退出当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 + 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的密钥数据(PID 和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则中止当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 @@ -821,7 +806,7 @@ SELCT 1/0; - 这么做是对安全性和有效性通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 + 这么做是对安全性和效率通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 @@ -842,11 +827,11 @@ SELCT 1/0; - 其他终止场景来自各种故障,例如任一端发生内核转储、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 + 其他终止场景来自各种故障,例如任一端发生 core dump、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 - 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果很可能在得知断开之前被提交。 + 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果可能在发现连接断开之前被提交。 @@ -860,32 +845,28 @@ SELCT 1/0; 要发起一条使用SSL加密的连接,前端首先发送 SSLRequest 消息,而不是 StartupMessage。随后服务器会响应一个包含SN的单字节,分别表示它愿意或不愿意执行SSL加密。如果前端对该响应不满意,此时可以关闭连接。若要在收到S后继续,就先与服务器完成SSL启动握手(这里不做描述,它属于SSL规范的一部分)。如果成功,再继续发送通常的 StartupMessage。在这种情况下,StartupMessage 以及后续所有数据都会被SSL加密。若要在收到N后继续,则发送通常的 StartupMessage,并在不使用加密的情况下继续。 - (另外,可以在 N 响应之后发出 GSSENCRequest 消息,尝试使用 GSSAPI 加密代替 SSL。) + (另外,可以在 N 响应之后发出 GSSENCRequest 消息,尝试使用 GSSAPI 加密代替 SSL。) - 前端也应准备处理服务器对 SSLRequest 返回的 ErrorMessage。前端不应将该错误直接展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 SSL 的情况下继续。 + 前端也应准备处理服务器对 SSLRequest 返回的 ErrorMessage。前端不应将该错误展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 SSL 的情况下继续。 - 当可以执行 SSL 加密时,服务器预计仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给他们的 SSL 库,要么在发现他们已经读取到额外的字节时将其视为协议违规。 + 当可以执行 SSL 加密时,服务器应仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给所用的 SSL 库,要么在发现已经读取到额外的字节时将其视为协议违规。 - - 同样,服务器也期望客户端在收到服务器对 SSLRequest 的单字节响应之后,再开始SSL协商。如果客户端不等服务器响应到达就立即开始SSL协商,可以减少一次网络往返时延;但代价是无法处理服务器对SSL请求返回否定响应的情况。在这种情况下,服务器通常会直接断开连接,而不会继续回退到 GSSAPI、未加密连接或协议错误流程。 - - - 初始 SSLRequest 也可以用于那些正在建立、目的是发送 CancelRequest 消息的连接。 - - 还支持第二种发起SSL加密的方式:客户端可以在不发送任何 SSLRequest 包的情况下,直接开始SSL协商。SSL连接建立后,服务器会在加密通道上继续等待普通的启动请求包并继续协商。在这种情况下,任何其他的加密请求都会被拒绝。这种方法不适合通用工具,因为它既不能协商出最佳的连接加密方式,也不能处理未加密连接;但在客户端和服务器都由同一方控制的环境中,它很有用,因为它可以减少一次往返时延,并允许使用依赖标准SSL连接的网络工具。使用这种风格的SSL连接时,客户端必须使用由 RFC 7301 定义的 ALPN 扩展,以防范协议混淆攻击。PostgreSQL 协议对应的 ALPN 标识是 postgresql,见 IANA TLS ALPN Protocol IDs 注册表。 - + 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 SSLRequest。 + + + - 虽然协议本身并不提供让服务器强制启用SSL加密的方法,但管理员可以把服务器配置为拒绝未加密会话,把它作为认证检查的一个副作用。 - + 虽然协议本身没有提供让服务器强制使用SSL加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + @@ -896,37 +877,27 @@ SELCT 1/0; 如果PostgreSQL构建时启用了GSSAPI支持,就可以使用GSSAPI对前端/后端通信进行加密。这为攻击者可能截获会话流量的环境提供了通信安全性。有关使用GSSAPI加密PostgreSQL会话的详细信息,请参阅。 - - 要启动一个GSSAPI加密连接,前端最初发送一个GSSENCRequest消息,而不是一个StartupMessage。 - 服务器随后会响应一个包含GN的单个字节,分别表示愿意或不愿意执行GSSAPI加密。 - 如果前端对响应不满意,可能会在此时关闭连接。 - 要在G之后继续,使用GSSAPI C绑定,如在RFC 2744 - 中讨论的,或等效的,通过在循环中调用gss_init_sec_context()来执行GSSAPI初始化, - 并将结果发送给服务器,从一个空输入开始,然后对每个来自服务器的结果进行处理,直到不再返回输出为止。 - 在将gss_init_sec_context()的结果发送给服务器时,在消息前加上以网络字节顺序表示的四字节整数的长度。 - 要在N之后继续,发送通常的StartupMessage,并在没有加密的情况下继续进行。 - (或者,可以在N响应后发出一个SSLRequest消息,尝试使用SSL加密代替GSSAPI。) - + 要建立 GSSAPI 加密连接,前端首先发送 GSSENCRequest 消息,而不是 StartupMessage。服务器随后以单个字节响应,内容为 GN,分别表示愿意或不愿意使用 GSSAPI 加密。如果前端对响应不满意,可以在此时关闭连接。收到 G 后要继续,应使用 RFC 2744 中介绍的 GSSAPI C 绑定或等效接口,在循环中调用 gss_init_sec_context() 来执行 GSSAPI 初始化,并将结果发送给服务器:先使用空输入,再依次使用服务器返回的每个结果,直到该调用不再产生输出。将 gss_init_sec_context() 的结果发送给服务器时,应在前面加上消息长度,以网络字节序的四字节整数表示。收到 N 后要继续,则发送通常的 StartupMessage,以不加密的方式继续。(也允许在收到 N 响应后发送 SSLRequest 消息,尝试使用 SSL 加密代替 GSSAPI。) - 前端也应准备处理服务器对 GSSENCRequest 返回的 ErrorMessage。前端不应将该错误直接展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 GSSAPI 加密的情况下继续。 + 前端也应准备处理服务器对 GSSENCRequest 返回的 ErrorMessage。前端不应将该错误展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 GSSAPI 加密的情况下继续。 - 当GSSAPI加密可用时,服务器预计只发送单个G字节,然后等待前端启动GSSAPI握手。此时如果还有其他可读字节,很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应编写代码,要么从套接字中恰好读取一个字节后再把套接字交给其 GSSAPI 库,要么在发现自己已经读到额外字节时将其视为协议违规。 + 当GSSAPI加密可用时,服务器应只发送单个G字节,然后等待前端启动GSSAPI握手。此时如果还有其他可读字节,很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应编写代码,要么从套接字中恰好读取一个字节后再把套接字交给其 GSSAPI 库,要么在发现自己已经读到额外字节时将其视为协议违规。 - 初始 GSSENCRequest 也可用于那些正在建立、目的是发送 CancelRequest 消息的连接。 - + 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 GSSENCRequest。 + 一旦成功建立GSSAPI加密连接,就应使用gss_wrap()加密通常的 StartupMessage 以及后续所有数据,并在实际加密负载前附上gss_wrap()结果长度,该长度以网络字节序的四字节整数表示。请注意,服务器只接受来自客户端、长度小于 16kB 的加密数据包。客户端应使用gss_wrap_size_limit()确定符合该限制的未加密消息大小,较大的消息则应拆分为多次gss_wrap()调用。典型分段是 8kB 的未加密数据,对应得到略大于 8kB 但明显小于 16kB 的加密数据包。通常可以认为,服务器不会向客户端发送大于 16kB 的加密数据包。 - 虽然协议本身并不为服务器提供强制启用GSSAPI加密的方法,但管理员可以把服务器配置为拒绝未加密会话,把它作为认证检查的一个副作用。 - + 虽然协议本身没有提供让服务器强制使用GSSAPI加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + @@ -934,9 +905,7 @@ SELCT 1/0; SASL认证 - - SASL是面向连接协议中的认证框架。目前,PostgreSQL实现了两种 SASL 认证机制:SCRAM-SHA-256 和 SCRAM-SHA-256-PLUS。将来可能增加更多机制。下面的步骤说明 SASL 认证的一般流程,下一小节则详细介绍 SCRAM-SHA-256 和 SCRAM-SHA-256-PLUS。 - + SASL 是面向连接协议中的认证框架。目前,PostgreSQL 实现了两种 SASL 认证机制:SCRAM-SHA-256 和 SCRAM-SHA-256-PLUS。将来可能增加更多机制。以下步骤说明 SASL 认证的一般流程,下一小节则详细介绍 SCRAM-SHA-256 和 SCRAM-SHA-256-PLUS。 @@ -952,25 +921,22 @@ SELCT 1/0; - 客户端从列表中选择一个支持的机制,并向服务器发送一个SASLInitialResponse消息。 - 该消息包括所选机制的名称,以及如果所选机制使用的话,还包括一个可选的初始客户端响应。 - + 客户端从列表中选择一种受支持的机制,并向服务器发送 SASLInitialResponse 消息。消息包含所选机制的名称;如果该机制使用初始客户端响应,消息还可以包含这一可选响应。 + - 一个或多个服务器挑战和客户端响应消息将随后而来。每个服务器挑战都是在一个 - AuthenticationSASLContinue 消息中发送的,随后是客户端在一个 SASLResponse - 消息中的响应。这些消息的具体内容是特定于机制的。 - + 随后会进行一轮或多轮服务器挑战和客户端响应。每次服务器挑战都通过 AuthenticationSASLContinue 消息发送,随后客户端通过 SASLResponse 消息响应。消息的具体内容取决于所用机制。 + - 最后,当认证交换成功完成时,服务器会发送可选的 AuthenticationSASLFinal 消息,随后立即发送 AuthenticationOk。AuthenticationSASLFinal 包含机制特定的附加数据;若该机制不需要完成时附加数据,则不会发送 AuthenticationSASLFinal。 - + 最后,认证交换成功完成时,服务器会发送 AuthenticationSASLFinal 消息,紧接着发送 AuthenticationOk 消息。AuthenticationSASLFinal 包含从服务器发给客户端的附加数据,其具体内容取决于所选认证机制。如果该认证机制不使用在完成时发送的附加数据,则不会发送 AuthenticationSASLFinal 消息。 + @@ -982,12 +948,7 @@ SELCT 1/0; SCRAM-SHA-256认证 - - SCRAM-SHA-256 及其带通道绑定的变体 - SCRAM-SHA-256-PLUS 是基于密码的认证机制。它们在 - RFC 7677 - 和RFC 5802中有详细描述。 - + 目前实现的 SASL 机制是 SCRAM-SHA-256 及其带通道绑定的变体 SCRAM-SHA-256-PLUSRFC 7677RFC 5802 对它们有详细描述。 当在PostgreSQL中使用SCRAM-SHA-256时,服务器将忽略客户端在client-first-message中发送的用户名。 @@ -996,13 +957,8 @@ SELCT 1/0; - SCRAM规范规定密码也必须是UTF-8编码,并且使用SASLprep算法处理。 - 然而,PostgreSQL不要求密码必须使用UTF-8编码。 - 当用户设置密码时,无论实际使用的编码是什么,都会像使用UTF-8一样使用SASLprep进行处理。 - 但是,如果密码不是合法的UTF-8字节序列,或者包含SASLprep算法禁止的UTF-8字节序列, - 则会使用原始密码而不进行SASLprep处理,而不是抛出错误。这样可以在密码为UTF-8时对其进行规范化, - 但仍允许使用非UTF-8密码,并且不需要系统知道密码使用的编码方式。 - + SCRAM 规范规定密码也必须采用 UTF-8 编码,并通过SASLprep算法处理。不过,PostgreSQL并不要求密码使用 UTF-8。设置用户密码时,无论实际采用何种编码,都会将其视作 UTF-8 并用 SASLprep 处理。但是,如果密码不是合法的 UTF-8 字节序列,或者包含 SASLprep 算法禁止的 UTF-8 字节序列,就会直接使用未经 SASLprep 处理的原始密码,而不抛出错误。这样既能对 UTF-8 密码进行规范化,又允许使用非 UTF-8 密码,而且不要求系统知道密码采用何种编码。 + 通道绑定在支持SSL的PostgreSQL构建中受支持。带有通道绑定的SCRAM的SASL机制名称是 @@ -1011,16 +967,12 @@ SELCT 1/0; - 在没有通道绑定的SCRAM中,服务器选择一个随机数, - 传输给客户端,与用户提供的密码在传输的密码哈希中混合。虽然这可以 - 防止密码哈希在后续会话中被成功重新传输,但无法阻止真实服务器和客 - 户端之间的虚假服务器通过服务器的随机值并成功进行认证。 - + 在不带通道绑定的SCRAM中,服务器会选择一个随机数并发送给客户端,将它与用户提供的密码混合,形成所传输的密码 hash。虽然这样可以防止在后续会话中成功重放该密码 hash,但无法阻止位于真实服务器与客户端之间的伪造服务器转发服务器的随机值并成功通过认证。 + - SCRAM与通道绑定一起防止这种中间人攻击,通过将服务器证书的签名混合到传输的密码哈希中。 - 虽然伪造服务器可以重新传输真实服务器的证书,但它无法访问与该证书匹配的私钥,因此无法证明自己是所有者,导致SSL连接失败。 - + 带通道绑定的SCRAM会将服务器证书的签名混入所传输的密码 hash,从而防止此类中间人攻击。虽然伪造服务器可以转发真实服务器的证书,但它无法取得与证书匹配的私钥,因此无法证明自己是证书所有者,最终导致 SSL 连接失败。 + @@ -1092,16 +1044,15 @@ SELCT 1/0; - 为了测试复制命令,可以通过psql或任何其他使用连接字符串且包含replication选项的libpq工具建立复制连接, - 例如: + 为了测试复制命令,可以通过 psql 或其他使用 libpq 的工具建立复制连接,连接字符串中应包含 replication 选项,例如: psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 然而,更常用的是使用(用于物理复制)或(用于逻辑复制)。 - +不过,通常更有用的做法是使用 (用于物理复制)或 (用于逻辑复制)。 + - 复制命令在服务器日志中记录,当启用时。 + 启用 后,复制命令会记录到服务器日志中。 @@ -1111,7 +1062,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" IDENTIFY_SYSTEM - 识别系统 + IDENTIFY_SYSTEM @@ -1133,7 +1084,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - timeline (int8) + timeline (int4) @@ -1147,9 +1098,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" xlogpos (text) - - 当前 WAL 刷新位置。用于获得预写式日志中的一个已知位置,以便从该处开始流式传输。 - + 当前 WAL 刷盘位置。可用于获取预写式日志中一个已知的位置,以便从该处开始流式传输。 @@ -1201,10 +1150,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 请求服务器发送时间线历史文件以获取时间线tli。 - 服务器回复一行结果集,包含两个字段。虽然这些字段被标记为text, - 但它们实际上返回原始字节,没有编码转换: - + 请求服务器发送时间线 tli 的历史文件。服务器返回一个包含两个字段的单行结果集。虽然这些字段标记为 text,但实际返回的是原始字节,不进行编码转换: + @@ -1284,12 +1231,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果为 true,则该逻辑复制槽支持两阶段提交的解码。使用此选项后,与两阶段提交相关的命令,如 - PREPARE TRANSACTIONCOMMIT PREPARED - 和ROLLBACK PREPARED将被解码和传输。 - 事务将在PREPARE TRANSACTION时解码和传输。 - 默认值为false。 - + 如果为 true,则该逻辑复制槽支持对两阶段提交进行解码。使用此选项后,PREPARE TRANSACTIONCOMMIT PREPAREDROLLBACK PREPARED 等两阶段提交命令会被解码并传输。事务会在 PREPARE TRANSACTION 时解码并传输。默认值为 false。 + @@ -1300,10 +1243,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果为 true,则该物理复制槽会立即保留WAL。 - 否则,WAL仅在从流复制客户端连接时保留。 - 默认值为false。 - + 如果为 true,则该物理复制槽会立即保留 WAL。否则,只有在流复制客户端连接时才会保留 WAL。默认值为 false。 + @@ -1374,60 +1315,19 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - - ALTER_REPLICATION_SLOT slot_name ( option [, ...] ) - ALTER_REPLICATION_SLOT - - - - 修改复制槽定义。参见 。当前仅支持逻辑复制槽。 - - - - slot_name - - - 要修改的复制槽名称,必须是合法复制槽名(见 )。 - - - - - 支持以下选项: - - - TWO_PHASE [ boolean ] - - - 若为 true,则该逻辑复制槽支持两阶段提交解码。与两阶段提交相关的命令(如 PREPARE TRANSACTIONCOMMIT PREPAREDROLLBACK PREPARED)会被解码并发送;事务在 PREPARE TRANSACTION 时解码并发送。 - - - - - - - FAILOVER [ boolean ] - - - 若为 true,则该复制槽会同步到备库,从而在故障切换后恢复逻辑复制。 - - - - - - + READ_REPLICATION_SLOT slot_name - 读取复制槽 + READ_REPLICATION_SLOT - 读取与复制槽相关的一些信息。如果复制槽不存在,则返回一个包含NULL值的元组。 - 当前仅支持物理复制槽的此命令。 - + 读取与复制槽关联的一些信息。如果复制槽不存在,则返回包含 NULL 值的元组。此命令目前仅支持物理复制槽。 + 在响应此命令时,服务器将返回一个包含以下字段的单行结果集: @@ -1454,8 +1354,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" restart_tliint8 - 与restart_lsn相关联的时间线ID,遵循当前时间线历史。 - + 根据当前时间线的历史,与 restart_lsn 对应的时间线 ID。 + @@ -1467,35 +1367,29 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" START_REPLICATION [ SLOT slot_name ] [ PHYSICAL ] XXX/XXX [ TIMELINE tli ] - 开始复制 + START_REPLICATION - 指示服务器开始流式传输WAL,从WAL位置XXX/XXX开始。 - 如果指定了TIMELINE选项,则流式传输将从时间线tli开始; - 否则,将选择服务器当前的时间线。如果请求的WAL部分已经被回收,服务器可能会回复错误。 - 成功时,服务器将用CopyBothResponse消息回复,然后开始向前端流式传输WAL。 - + 指示服务器从 WAL 位置 XXX/XXX 开始流式传输 WAL。如果指定了 TIMELINE 选项,则从时间线 tli 开始传输;否则选择服务器当前的时间线。服务器可以返回错误,例如请求的 WAL 部分已被回收时。成功时,服务器返回 CopyBothResponse 消息,然后开始向前端流式传输 WAL。 + - 如果通过slot_name提供了复制槽名称, - 那么在复制进行期间会更新该复制槽,以便服务器知道哪些 WAL 段, - 以及在启用了 hot_standby_feedback 时,哪些事务 - 仍然被备库所需要。 - + 如果通过 slot_name 提供了复制槽名称,该复制槽会随着复制的进行而更新,使服务器知道备库仍需要哪些 WAL 段,以及在启用 hot_standby_feedback 时仍需要哪些事务。 + - 如果客户端请求的 timeline 不是最新的,但属于服务器历史的一部分,服务器会从请求的起点开始流式传输该 timeline 上的全部 WAL,直到服务器切换到另一个 timeline 的位置为止。如果客户端请求的位置正好是旧 timeline 的末尾,服务器将完全跳过 COPY 模式。 - + 如果客户端请求的时间线不是最新时间线,但属于服务器的历史,服务器会从请求的起点开始,流式传输该时间线上的所有 WAL,直到服务器切换到另一条时间线的位置。如果客户端请求的流式传输起点恰好位于旧时间线的末尾,服务器会完全跳过 COPY 模式。 + 在非最新时间线上流式传输完全部 WAL 后,服务器会通过退出 COPY 模式来结束流式传输。当客户端也通过退出 COPY 模式来确认时,服务器会发送一个包含一行两列的结果集,指示该服务器历史中的下一条时间线。第一列是下一条时间线的 ID(类型为 int8),第二列是发生切换的 WAL 位置(类型为 text)。通常,切换位置就是所流式传输 WAL 的末尾,但也存在一些边界情况,服务器可能会先发送一些自己在提升前尚未重放的旧时间线 WAL。最后,服务器会发送两个 CommandComplete 消息(一个结束 CopyData,另一个结束 START_REPLICATION 本身),然后准备接受新的命令。 - WAL 数据会作为一系列 CopyData 消息发送;详见 。(这使其他信息可与之交错发送;特别是服务器在开始流式传输后若遇到失败,仍可发送 ErrorResponse。)从服务器到客户端的每个 CopyData 消息负载都属于以下格式之一: - + WAL 数据通过一系列 CopyData 消息发送,详见 。(这样可以混合发送其他信息;尤其是服务器在开始流式传输后遇到故障时,可以发送 ErrorResponse 消息。)服务器发给客户端的每条 CopyData 消息,其有效载荷都包含一条具有下列格式之一的消息: + @@ -1508,9 +1402,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('w') - - 将消息标识为WAL数据。 - + 将该消息标识为 WAL 数据。 @@ -1519,9 +1411,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 该消息中 WAL 数据的起始点。 - + 本消息中 WAL 数据的起始位置。 @@ -1530,9 +1420,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 服务器上当前的WAL结束位置。 - + 服务器上当前的 WAL 末尾位置。 @@ -1541,9 +1429,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 传输时服务器的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时服务器的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1552,15 +1438,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byten - - WAL数据流的一个部分。 - + WAL 数据流的一个片段。 - - 单个 WAL 记录绝不会拆分为两个 XLogData 消息。 - 当 WAL 记录跨越 WAL 页面边界,并因此已使用连续记录进行拆分时,它可以在页面边界处进行拆分。 - 换句话说,第一个主 WAL 记录及其连续记录可以在不同的 XLogData 消息中发送。 - + 单条 WAL 记录绝不会被拆分到两条 XLogData 消息中。当 WAL 记录跨越 WAL 页边界,因而已经通过续接记录拆分时,可以在页边界处分开发送。换句话说,最初的主 WAL 记录及其续接记录可以在不同的 XLogData 消息中发送。 @@ -1569,7 +1449,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 主库 keepalive 消息 (B) + 主库保活消息 (B) @@ -1577,9 +1457,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('k') - - 将该消息标识为发送方 keepalive。 - + 将该消息标识为发送端保活消息。 @@ -1588,9 +1466,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 服务器上当前的WAL结束位置。 - + 服务器上当前的 WAL 末尾位置。 @@ -1599,9 +1475,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 传输时服务器的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时服务器的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1610,9 +1484,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1 - - 1 表示客户端应尽快回复此消息,以避免超时断开连接。否则为0。 - + 1 表示客户端应尽快回复此消息,以避免超时断开连接;否则为 0。 @@ -1620,9 +1492,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - - 接收进程可以随时使用以下某种消息格式向发送方回传响应(同样放在 CopyData 消息的负载中): - + 接收进程可以随时使用以下消息格式之一回复发送端(同样放在 CopyData 消息的有效载荷中): @@ -1635,9 +1505,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('r') - - 将该消息标识为接收方状态更新。 - + 将该消息标识为接收端状态更新。 @@ -1646,9 +1514,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已接收并写入磁盘的 WAL 字节位置 + 1。 - + 备库已接收并写入磁盘的最后一个 WAL 字节的位置加 1。 @@ -1657,9 +1523,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已刷写到磁盘的 WAL 字节位置 + 1。 - + 备库已刷盘的最后一个 WAL 字节的位置加 1。 @@ -1668,9 +1532,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已应用的 WAL 字节位置 + 1。 - + 备库已应用的最后一个 WAL 字节的位置加 1。 @@ -1679,9 +1541,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 客户端在传输时的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时客户端的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1690,9 +1550,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1 - - 如果为 1,则客户端请求服务器立即回复此消息。这可用于 ping 服务器,以测试连接是否仍然健康。 - + 如果为 1,表示客户端请求服务器立即回复此消息。可用它向服务器发送探测请求,以测试连接是否仍然正常。 @@ -1720,9 +1578,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 客户端在传输时的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时客户端的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1742,9 +1598,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 - - 备库上全局 xmin xid 的纪元。 - + 备库全局 xmin 事务 ID 的纪元。 @@ -1753,9 +1607,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 - - 备库上任何复制槽中的最低 catalog_xmin。如果备库上不存在 catalog_xmin,或已禁用热备反馈,则设为 0。 - + 备库上所有复制槽中最小的 catalog_xmin。如果备库上不存在 catalog_xmin,或者正在禁用热备反馈,则设为 0。 @@ -1764,9 +1616,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 - - 备库上 catalog_xmin xid 的纪元。 - + 备库 catalog_xmin 事务 ID 的纪元。 @@ -1852,7 +1702,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" DROP_REPLICATION_SLOT slot_name WAIT - 删除复制槽 + DROP_REPLICATION_SLOT @@ -1902,9 +1752,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" LABEL 'label' - 设置备份的标签。如果未指定,则将使用base backup作为备份标签。 - 标签的引号使用规则与打开的标准SQL字符串相同。 - + 设置备份标签。如果未指定,则使用 base backup 作为备份标签。标签的引号规则与启用 时的标准 SQL 字符串相同。 + @@ -2000,16 +1849,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - level关键字设置压缩级别。 - 对于gzip,压缩级别应该是一个介于19之间的整数 - (默认为Z_DEFAULT_COMPRESSION-1), - 对于lz4,压缩级别应该是介于1和12之间的整数 - (默认为0用于快速压缩模式), - 对于zstd,压缩级别应该是介于ZSTD_minCLevel() - (通常为-131072)和ZSTD_maxCLevel() - (通常为22)之间, - (默认为ZSTD_CLEVEL_DEFAULT3)。 - + level 关键字设置压缩级别。对于 gzip,压缩级别应为 19 之间的整数(默认为 Z_DEFAULT_COMPRESSION,即 -1);对于 lz4,应为 1 到 12 之间的整数(默认为 0,表示快速压缩模式);对于 zstd,应为 ZSTD_minCLevel()(通常为 -131072)到 ZSTD_maxCLevel()(通常为 22)之间的整数(默认为 ZSTD_CLEVEL_DEFAULT,即 3)。 + workers关键字设置应该用于并行压缩的线程数。并行压缩仅支持zstd。 @@ -2116,17 +1957,16 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" size (int8) - 表空间的大致大小,以千字节(1024字节)为单位,如果已请求进度报告;否则为null。 - + 如果请求了进度报告,则为表空间的大致大小,以千字节(1024 字节)为单位;否则为 null。 + - 在第二个常规结果集之后,将发送一个CopyOutResponse。 - 每个CopyData消息的有效负载将包含以下格式之一的消息: - + 第二个普通结果集之后,会发送一条 CopyOutResponse。每条 CopyData 消息的有效载荷都包含一条具有下列格式之一的消息: + @@ -2303,7 +2143,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 逻辑复制协议 + 逻辑流复制协议 本节介绍逻辑复制协议,它是一种以复制命令START_REPLICATION @@ -2312,7 +2152,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 逻辑复制协议构建在物理流复制协议的底层机制之上。 + 逻辑流复制协议构建在物理流复制协议的基本机制之上。 @@ -2325,7 +2165,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 逻辑流复制参数 - 使用 START_REPLICATION 命令时,pgoutput 接受以下选项: + 使用START_REPLICATION命令,pgoutput接受以下选项: @@ -2443,7 +2283,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每个被发送的事务都包含零条或多条 DML 消息(插入、更新、删除)。在级联场景下,它还会包含 Origin 消息。Origin 消息表示该事务产生于另一个复制节点。由于逻辑复制协议中的复制节点可以是任意实现,因此唯一标识符就是该源头的名称。下游是否以及如何处理这一信息,由其自行决定。Origin 消息总是在事务中的任何 DML 消息之前发送。 + 每个发送的事务都包含零条或多条 DML 消息(Insert、Update、Delete)。在级联配置中,还可能包含 Origin 消息。Origin 消息表示该事务源自另一个复制节点。由于逻辑复制协议中的复制节点几乎可以是任何实现,因此唯一的标识符就是复制源的名称。下游负责按需处理这一信息(如果需要处理)。Origin 消息总是在事务中的任何 DML 消息之前发送。 @@ -2508,9 +2348,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 对后端返回的字符串长度,没有预定义的限制。 - 前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。 - 如果做不到这一点,就应读取完整字符串,并丢弃不适合固定大小缓冲区的尾随字符。 + 后端返回的字符串长度没有预定义的限制。前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。如果做不到这一点,就应读取完整字符串,并丢弃固定大小的缓冲区容纳不下的尾随字符。 @@ -2536,8 +2374,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 消息格式 - 本节描述每条消息的详细格式。每条消息都标记了可由前端(F)、后端(B)或双方(F&B)发送。 - 请注意,虽然每条消息开头都带有字节计数,但大多数消息格式都定义为无需参考该计数也能确定消息边界。这一设计最初是出于历史原因(早期已废弃的协议 v2 没有显式长度字段),同时也有助于有效性校验。 + 本节描述每条消息的详细格式。每条消息都标明它可以由前端(F)、后端(B)或双方(F & B)发送。注意,虽然每条消息开头都有字节计数,但消息格式的定义使得无需参考该计数也能确定消息的结束位置。这有助于检查消息的有效性。(CopyData 消息是例外,因为它构成数据流的一部分,任何单条 CopyData 消息的内容都无法独立解释。) @@ -2552,7 +2389,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2574,7 +2411,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定认证成功。 + 表示认证成功。 @@ -2594,7 +2431,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2616,7 +2453,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 Kerberos V5 认证。 + 表示需要 Kerberos V5 认证。 @@ -2636,7 +2473,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2658,7 +2495,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要明文密码。 + 表示需要明文密码。 @@ -2677,7 +2514,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2699,7 +2536,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要MD5加密的密码。 + 表示需要经过 MD5 加密的密码。 @@ -2710,7 +2547,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 用于加密密码时使用的盐。 + 加密密码时使用的盐。 @@ -2726,7 +2563,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('R') - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2744,7 +2581,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(6) - 指定需要 SCM 凭据消息。 + 表示需要 SCM 凭证消息。 @@ -2763,7 +2600,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2784,7 +2621,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 GSSAPI 认证。 + 表示需要 GSSAPI 认证。 @@ -2803,7 +2640,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2825,7 +2662,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定此消息包含GSSAPI或SSPI数据。 + 表示此消息包含 GSSAPI 或 SSPI 数据。 @@ -2855,7 +2692,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2877,7 +2714,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 SSPI 认证。 + 表示需要 SSPI 认证。 @@ -2896,7 +2733,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2918,14 +2755,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 SASL 认证。 + 表示需要 SASL 认证。 - 消息正文是服务器首选的 SASL 认证机制列表。在最后一个认证机制名称后需要一个零字节作为终止符。对于每个机制,有以下内容: + 消息体是按服务器偏好顺序排列的 SASL 认证机制列表。在最后一个认证机制名称之后,必须有一个零字节作为终止符。每个机制包含以下内容: @@ -2952,7 +2789,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2974,7 +2811,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定此消息包含一个SASL挑战。 + 表示此消息包含 SASL 挑战。 @@ -2985,7 +2822,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - SASL数据,特定于正在使用的SASL机制。 + SASL 数据,具体内容取决于所使用的 SASL 机制。 @@ -3004,7 +2841,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -3026,7 +2863,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定SASL认证已完成。 + 表示 SASL 认证已完成。 @@ -3037,7 +2874,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - SASL结果"附加数据",特定于正在使用的SASL机制。 + SASL 结果的“附加数据”,具体内容取决于所使用的 SASL 机制。 @@ -3056,8 +2893,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为取消键数据。 - 如果前端希望能够稍后发出CancelRequest消息,必须保存这些值。 + 将此消息标识为取消请求密钥数据。如果前端希望以后能够发送 CancelRequest 消息,就必须保存这些值。 @@ -3079,7 +2915,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 这个后端的进程ID。 + 此后端的进程 ID。 @@ -3090,7 +2926,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 该后端的 secret key。 + 此后端的密钥。 @@ -3109,7 +2945,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为绑定命令。 + 将该消息标识为 Bind 命令。 @@ -3153,10 +2989,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后面跟着的参数格式代码的数量(以下标记为C)。 - 这可以是零,表示没有参数或者所有参数都使用默认格式(文本); - 或者是一个,这种情况下指定的格式代码应用于所有参数; - 或者等于实际参数的数量。 + 后续参数格式代码的数量(下文以 C 表示)。可以为零,表示没有参数,或者所有参数都使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有参数;还可以等于实际参数数量。 @@ -3167,7 +3000,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数格式代码。每个目前必须是零(文本)或一(二进制)。 + 参数格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -3178,15 +3011,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后面跟着的参数值的数量(可能为零)。 - 这个数量必须与查询所需的参数数量匹配。 + 后续参数值的数量(可以为零)。必须与查询所需的参数数量一致。 - 接下来,对于每个参数,都会出现以下一对字段: + 接下来,每个参数都有以下一对字段: @@ -3196,9 +3028,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数值的长度,以字节为单位(此计数不包括自身)。可以为零。 - 作为特殊情况,-1表示空参数值。 - 在空参数值的情况下,不会跟随任何值字节。 + 参数值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 参数值。为 NULL 时,后面不再有值的字节。 @@ -3209,15 +3039,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数的值,以相关格式代码指示的格式表示。 - n是上述长度。 + 参数值,格式由对应的格式代码指明。n 为上述长度。 - 在最后一个参数之后,出现以下字段: + 最后一个参数之后是以下字段: @@ -3227,10 +3056,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后跟的结果列格式代码数量(以下标记为R)。 - 这可以是零,表示没有结果列,或者所有结果列应该使用默认格式(文本); - 或者是一个,此时指定的格式代码将应用于所有结果列(如果有); - 或者等于查询的实际结果列数。 + 后续结果列格式代码的数量(下文以 R 表示)。可以为零,表示没有结果列,或者所有结果列都应使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有结果列(如果有);还可以等于查询实际的结果列数量。 @@ -3241,7 +3067,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 结果列格式代码。每个目前必须是零(文本)或一(二进制)。 + 结果列格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -3260,7 +3086,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为绑定完成指示器。 + 将该消息标识为 Bind 完成指示。 @@ -3288,7 +3114,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(16) - 消息内容的长度,以字节为单位,包括此长度字段本身。 + 消息内容的长度(以字节为单位),包括其自身。 @@ -3334,7 +3160,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为关闭命令。 + 将该消息标识为 Close 命令。 @@ -3356,8 +3182,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 'S' 表示关闭一个预备语句;或者 - 'P' 表示关闭一个 portal。 + “S”表示关闭预备语句;“P”表示关闭 portal。 @@ -3387,7 +3212,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为关闭完成指示符。 + 将该消息标识为 Close 完成指示。 @@ -3417,7 +3242,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为命令完成响应。 + 将该消息标识为命令完成响应。 @@ -3439,7 +3264,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 命令标签。这通常是一个单词,用于标识已完成的SQL命令。 + 命令标签。通常是一个单词,用来标识已完成的 SQL 命令。 @@ -3484,10 +3309,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 对于COPY命令,标签是 - COPY rows,其中 - rows是复制的行数。 - (注意:行数仅出现在PostgreSQL 8.2及更高版本中。) + 对于 COPY 命令,标签为 COPY rows,其中 rows 是复制的行数。(注意:行数仅出现在 PostgreSQL 8.2 及更高版本中。) @@ -3618,8 +3440,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为开始复制响应。 - 前端现在必须发送复制数据(如果没有准备好,发送CopyFail消息)。 + 将该消息标识为开始 COPY 输入的响应。前端此时必须发送 COPY 输入数据(如果尚未准备好,应发送 CopyFail 消息)。 @@ -3665,9 +3486,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -3686,8 +3505,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为开始复制输出响应。 - 该消息将被复制输出数据跟随。 + 将该消息标识为开始 COPY 输出的响应。此消息之后会发送 COPY 输出数据。 @@ -3709,8 +3527,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 0表示整体COPY格式为文本格式(行由换行符分隔,列由分隔符字符分隔等)。 - 1表示整体复制格式为二进制格式(类似于DataRow格式)。更多信息请参见。 + 0表示整体COPY格式是文本的(行由换行符分隔,列由分隔符分隔等)。 + 1表示整体复制格式是二进制的(类似于DataRow格式)。 + 更多信息请参见 @@ -3732,9 +3551,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -3753,7 +3570,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为开始复制双响应。此消息仅用于流复制。 + 将该消息标识为开始双向 COPY 的响应。此消息仅用于流复制。 @@ -3775,8 +3592,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 0表示整体COPY格式为文本格式(行由换行符分隔,列由分隔符字符分隔等)。 - 1表示整体复制格式为二进制格式(类似于DataRow格式)。更多信息请参见。 + 0表示整体COPY格式是文本的(行由换行符分隔,列由分隔符分隔等)。 + 1表示整体复制格式是二进制的(类似于DataRow格式)。 + 更多信息请参见 @@ -3798,9 +3616,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -3848,7 +3664,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于每一列,都会出现以下一对字段: + 接下来,每列都有以下两个字段: @@ -3858,8 +3674,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列值的长度,以字节为单位(此计数不包括其本身)。可以为零。 - 作为特殊情况,-1表示空列值。在空值情况下,不跟随任何值字节。 + 列值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 列值。为 NULL 时,后面不再有值的字节。 @@ -3890,7 +3705,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为描述命令。 + 将该消息标识为 Describe 命令。 @@ -3943,7 +3758,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为对空查询字符串的响应。(这相当于CommandComplete。) + 标识消息为对空查询字符串的响应。(此消息替代 CommandComplete。) @@ -3991,7 +3806,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 消息正文由一个或多个已识别的字段组成,后跟一个零字节作为终止符。字段可以以任何顺序出现。对于每个字段,都有以下内容: + 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -4014,7 +3829,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 字段数值。 + 字段值。 @@ -4033,7 +3848,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为一个执行命令。 + 将该消息标识为 Execute 命令。 @@ -4066,7 +3881,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果 portal 包含返回行的查询,则为要返回的最大行数(否则忽略)。零表示没有限制。 + 如果 portal 包含返回行的查询,则这是最多返回的行数(否则忽略此值)。零表示无限制 @@ -4085,7 +3900,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为Flush命令。 + 将该消息标识为 Flush 命令。 @@ -4137,7 +3952,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定要调用的函数的对象ID。 + 指定要调用的函数的对象 ID。 @@ -4148,10 +3963,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后面跟着的参数格式代码的数量(以下标记为C)。 - 这可以是零,表示没有参数或所有参数都使用默认格式(文本); - 或者是一个,这种情况下指定的格式代码应用于所有参数; - 或者等于实际参数的数量。 + 后续参数格式代码的数量(以下用 C 表示)。可以为零,表示没有参数,或所有参数都采用默认格式(文本);也可以为一,表示将指定的格式代码用于所有参数;还可以等于实际参数数量。 @@ -4180,7 +3992,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于每个参数,都会出现以下一对字段: + 接下来,每个参数都有以下两个字段: @@ -4190,9 +4002,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数值的长度,以字节为单位(此计数不包括自身)。可以为零。 - 作为特殊情况,-1表示空参数值。 - 在空参数值的情况下,不会跟随任何值字节。 + 参数值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 参数值。为 NULL 时,后面不再有值的字节。 @@ -4211,7 +4021,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 在最后一个参数之后,出现以下字段: + 最后一个参数之后还有以下字段: @@ -4221,7 +4031,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 函数结果的格式代码。目前必须是零(文本)或一(二进制)。 + 函数结果的格式代码。目前必须为零(文本)或一(二进制)。 @@ -4262,9 +4072,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 函数结果值的长度,以字节为单位(此计数不包括本身)。可以为零。 - 作为特殊情况,-1表示NULL函数结果。 - 在NULL情况下,不会跟随任何值字节。 + 函数结果值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 函数结果。为 NULL 时,后面不再有值的字节。 @@ -4390,7 +4198,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 服务器支持的最新次要协议版本,用于客户端请求的主要协议版本。 + 对于客户端请求的协议主版本,服务器所支持的最新协议次版本。 @@ -4401,14 +4209,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 服务器未识别的协议选项数量。 + 服务器无法识别的协议选项数量。 - 然后,对于服务器未识别的协议选项,有以下内容: + 接下来,对于服务器无法识别的每个协议选项,都有以下内容: @@ -4485,7 +4293,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 消息正文由一个或多个已识别的字段组成,后跟一个零字节作为终止符。字段可以以任何顺序出现。对于每个字段,都有以下内容: + 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -4508,7 +4316,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 字段数值。 + 字段值。 @@ -4549,7 +4357,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 通知后端进程的进程ID。 + 发出通知的后端进程的进程 ID。 @@ -4560,7 +4368,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 通知被触发的频道名称。 + 发出该通知的通道名称。 @@ -4571,7 +4379,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 从通知进程传递的有效负载字符串。 + 通知进程传来的有效载荷字符串。 @@ -4619,7 +4427,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 然后,对于每个参数,都有以下内容: + 接下来,每个参数都有以下内容: @@ -4629,7 +4437,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定参数数据类型的对象ID。 + 指定参数数据类型的对象 ID。 @@ -4670,7 +4478,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 正在报告的运行时参数的名称。 + 所报告的运行时参数的名称。 @@ -4700,7 +4508,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为解析命令。 + 将该消息标识为 Parse 命令。 @@ -4752,7 +4560,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 然后,对于每个参数,都有以下内容: + 接下来,每个参数都有以下内容: @@ -4762,7 +4570,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定参数数据类型的对象ID。在这里放置零相当于未指定类型。 + 指定参数数据类型的对象 ID。此处填零等同于不指定类型。 @@ -4781,7 +4589,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为解析完成指示器。 + 将该消息标识为 Parse 完成指示。 @@ -4853,8 +4661,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为 portal 挂起指示器。 - 请注意,仅当执行消息的行数限制达到时才会出现此消息。 + 将该消息标识为 portal 挂起指示。注意,仅当达到 Execute 消息指定的行数限制时,才会出现此消息。 @@ -4990,14 +4797,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定一行中的字段数(可以为零)。 + 指定一行中的字段数量(可以为零)。 - 然后,对于每个字段,都有以下内容: + 接下来,每个字段都有以下内容: @@ -5018,7 +4825,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果该字段可以被识别为特定表的列,则为该表的对象ID;否则为零。 + 如果能够确定该字段是某个特定表的列,则为该表的对象 ID;否则为零。 @@ -5029,7 +4836,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果该字段可以被识别为特定表的列,则为该列的属性编号;否则为零。 + 如果能够确定该字段是某个特定表的列,则为该列的属性编号;否则为零。 @@ -5040,7 +4847,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 字段数据类型的对象ID。 + 字段数据类型的对象 ID。 @@ -5075,7 +4882,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 正在使用的字段格式代码。目前将为零(文本)或一(二进制)。在从描述语句变体返回的RowDescription中,格式代码尚未知晓,将始终为零。 + 字段所使用的格式代码。目前为零(文本)或一(二进制)。对于 Describe 针对预备语句的变体所返回的 RowDescription,格式代码尚未确定,始终为零。 @@ -5128,7 +4935,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 长度为SASL机制特定的“初始客户端响应”,如果没有初始响应,则为-1。 + 后续 SASL 机制特有的“客户端初始响应”的长度;如果没有初始响应,则为 -1。 @@ -5243,17 +5050,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 协议版本号。最重要的16位是主版本号(此处描述的协议为3)。 - 最不重要的16位是次版本号(此处描述的协议为2)。 + 协议版本号。高 16 位为主版本号(此处描述的协议为 3);低 16 位为次版本号(此处描述的协议为 0)。 - 协议版本号后面跟着一个或多个参数名和值字符串对。在最后一个名/值对之后需要一个零字节作为终止符。 - 参数可以以任何顺序出现。user是必需的,其他是可选的。 - 每个参数的指定方式为: + 协议版本号之后是一个或多个参数名与参数值字符串对。最后一个名称/值对之后必须有一个零字节作为终止符。参数可以按任意顺序出现。其中,user是必需的,其余均为可选。每个参数按以下方式指定: @@ -5263,7 +5067,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数名称。当前识别的名称包括: + 参数名称。目前能够识别的名称如下: @@ -5303,7 +5107,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 除上述之外,还可以列出其他参数。以_pq_.开头的参数名称保留用于协议扩展,而其他参数被视为后端启动时设置的运行时参数。这些设置将在后端启动时应用(在解析命令行参数后,如果有的话),并将作为会话默认值。 + 除上述参数外,还可以列出其他参数。以_pq_.开头的参数名称保留用于协议扩展,其余参数则作为运行时参数,在后端启动时设置。这些设置会在后端启动期间应用(在解析命令行参数之后,如果有的话),并作为会话默认值。 @@ -5314,7 +5118,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数数值。 + 参数值。 @@ -5333,7 +5137,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为同步命令。 + 将该消息标识为 Sync 命令。 @@ -5386,7 +5190,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 错误和通知消息域 + 错误和通知消息字段 本节描述了ErrorResponse和NoticeResponse消息中可能出现的字段。每个字段类型都有一个单字节的标识符。 @@ -5399,11 +5203,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 严重性: 字段内容为ERROR, FATAL, 或 - PANIC (在错误消息中), 或 - WARNING, NOTICE, DEBUG, - INFO, 或 LOG (在通知消息中), - 或者这些内容的本地化翻译。始终存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中),或这些内容的本地化翻译。始终存在。 @@ -5413,11 +5213,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 严重性:字段内容为ERRORFATAL或 - PANIC(在错误消息中),或WARNINGNOTICEDEBUG、 - INFOLOG(在通知消息中)。 - 这与S字段相同,只是内容不会被本地化。仅在由PostgreSQL版本9.6 - 及更高版本生成的消息中存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中)。它与 S 字段相同,只是内容从不本地化。仅在 PostgreSQL 9.6 及更高版本生成的消息中存在。 @@ -5427,7 +5223,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Code: 错误的SQLSTATE代码(参见)。不可本地化。始终存在。 + 代码:错误的 SQLSTATE 代码(见 )。不可本地化。始终存在。 @@ -5437,9 +5233,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 消息: 主要的人类可读错误消息。 - 这应该准确但简洁(通常一行)。 - 总是存在。 + 消息:主要的可读错误消息。应准确而简洁(通常为一行)。始终存在。 @@ -5449,7 +5243,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 详细信息:一个可选的次要错误消息,提供有关问题的更多详细信息。可能会跨多行。 + 详细信息:可选的次要错误消息,提供有关该问题的更多细节。可能占多行。 @@ -5459,9 +5253,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 提示: 关于问题应该怎么做的一个可选建议。 - 这意在与细节不同,它提供建议(可能不合适)而不是硬性事实。 - 可能会跨越多行。 + 提示:可选的建议,说明如何处理该问题。它与详细信息的区别在于,它提供建议(可能并不合适),而非确凿事实。可能占多行。 @@ -5504,9 +5296,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Where: 错误发生的上下文指示。 - 目前包括活动的过程语言函数和内部生成查询的调用堆栈回溯。 - 跟踪每行一个条目,最近的在前。 + 上下文:说明错误发生时的上下文。目前包括活跃的过程语言函数和内部生成的查询的调用栈回溯。回溯每行一个条目,最近的调用在前。 @@ -5516,7 +5306,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Schema name: 如果错误与特定数据库对象相关联,则为包含该对象的模式的名称(如果有)。 + 模式名:如果错误与某个特定数据库对象有关,则为包含该对象的模式名称(如果有)。 @@ -5526,7 +5316,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 表名: 如果错误与特定表相关联,则为表的名称。(有关表模式名称的名称,请参考模式名称字段。) + 表名:如果错误与某个特定表有关,则为该表的名称。(表所在模式的名称见模式名字段。) @@ -5536,7 +5326,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列名: 如果错误与特定表列相关联,则为列的名称。(请参考模式和表名字段以识别表。) + 列名:如果错误与某个特定表列有关,则为该列的名称。(通过模式名和表名字段确定该表。) @@ -5546,8 +5336,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 数据类型名称: 如果错误与特定数据类型相关联,则为数据类型的名称。 - (有关数据类型模式的名称,请参阅模式名称字段。) + 数据类型名:如果错误与某个特定数据类型有关,则为该数据类型的名称。(数据类型所在模式的名称见模式名字段。) @@ -5557,8 +5346,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 约束名称: 如果错误与特定约束相关联,则为约束的名称。请参考上面列出的字段,了解相关表或域。 - (为此,即使索引不是使用约束语法创建的,也将其视为约束。) + 约束名:如果错误与某个特定约束有关,则为该约束的名称。相关的表或域见上述字段。(这里将索引也视为约束,即使它不是用约束语法创建的。) @@ -5568,7 +5356,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 文件: 报告错误的源代码位置的文件名。 + 文件:报告错误的源代码位置所在的文件名。 @@ -5578,7 +5366,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Line: 源代码位置的行号,报告错误的位置。 + 行号:报告错误的源代码位置所在的行号。 @@ -5588,7 +5376,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Routine: 报告错误的源代码例程的名称。 + 例程:报告错误的源代码例程的名称。 @@ -5597,15 +5385,12 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 模式名称、表名称、列名称、数据类型名称和约束名称的字段仅针对有限数量的错误类型提供; - 请参阅。前端不应假设任何这些字段的存在就保证了另一个字段的存在。 - 核心错误源观察到上述相互关系,但用户定义的函数可能以其他方式使用这些字段。 - 同样地,客户端不应假设这些字段表示当前数据库中的当代对象。 + 模式名、表名、列名、数据类型名和约束名字段仅针对有限的几类错误提供,见 。前端不应假设其中任何字段的存在就保证了另一个字段的存在。核心错误源遵循上述相互关系,但用户定义的函数可能以其他方式使用这些字段。同样,客户端不应假设这些字段表示当前数据库中现存的对象。 - 客户端负责格式化显示的信息以满足其需求;特别是应根据需要换行。错误消息字段中出现的换行符应被视为段落分隔符,而不是换行符。 + 客户端负责按自身需要格式化显示的信息;尤其应根据需要将长行断开。错误消息字段中的换行符应视为段落分隔符,而非行分隔符。 @@ -5631,18 +5416,18 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为开始消息。 + 将该消息标识为 Begin 消息。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 事务的最终LSN。 + 事务的最终 LSN。 @@ -5653,7 +5438,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -5664,7 +5449,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -5694,8 +5479,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -5706,14 +5490,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标志; 逻辑解码消息是非事务性的时为0,是事务性的时为1。 + 标志:0 表示没有标志;1 表示该逻辑解码消息是事务性的。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -5769,7 +5553,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为提交消息。 + 将该消息标识为 Commit 消息。 @@ -5787,22 +5571,22 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 提交的LSN。 + 提交的 LSN。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 事务的结束LSN。 + 事务的结束 LSN。 @@ -5813,7 +5597,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -5832,18 +5616,18 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为原始消息。 + 将该消息标识为 Origin 消息。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 原始服务器上提交的LSN。 + 源服务器上提交的 LSN。 @@ -5854,14 +5638,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 原点的名称。 + 复制源的名称。 - 请注意,在单个事务中可能存在多个Origin消息。 + 注意,单个事务中可能有多条 Origin 消息。 @@ -5877,7 +5661,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为关系消息。 + 将该消息标识为 Relation 消息。 @@ -5888,8 +5672,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -5911,7 +5694,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 命名空间(pg_catalog为空字符串)。 + 命名空间(对于 pg_catalog 为空字符串)。 @@ -5933,7 +5716,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 关系的复制标识设置(与relreplidentpg_class中相同)。 + 关系的复制标识设置(与 pg_class 中的 relreplident 相同)。 @@ -5951,7 +5734,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于出版物中包含的每一列(除了生成的列),会出现以下消息部分: + 接下来,发布中包含的每一列(生成列除外)都会出现以下消息部分: @@ -5961,7 +5744,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列的标志。目前可以是0表示没有标志,或者是1表示将该列标记为键的一部分。 + 列的标志。目前可以为 0,表示没有标志;或为 1,标记该列是键的一部分。 @@ -5994,7 +5777,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列的类型修饰符 (atttypmod)。 + 列的类型修饰符(atttypmod)。 @@ -6013,7 +5796,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为类型消息。 + 将该消息标识为 Type 消息。 @@ -6024,8 +5807,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6047,7 +5829,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 命名空间(pg_catalog为空字符串)。 + 命名空间(对于 pg_catalog 为空字符串)。 @@ -6077,7 +5859,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为插入消息。 + 将该消息标识为 Insert 消息。 @@ -6088,8 +5870,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6100,7 +5881,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。 + 关系的 OID,与 Relation 消息中的 ID 对应。 @@ -6111,7 +5892,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData消息为新元组。 + 将后续 TupleData 消息标识为新元组。 @@ -6122,7 +5903,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分,表示新元组的内容。 + 表示新元组内容的 TupleData 消息部分。 @@ -6141,7 +5922,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为更新消息。 + 将该消息标识为 Update 消息。 @@ -6152,8 +5933,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6164,7 +5944,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。 + 关系的 OID,与 Relation 消息中的 ID 对应。 @@ -6175,8 +5955,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData子消息为键。 - 此字段是可选的,仅在更新更改了属于REPLICA IDENTITY索引的任何列的数据时才存在。 + 将后续 TupleData 子消息标识为键。此字段可选,仅在更新更改了属于 REPLICA IDENTITY 索引的某一列或多列的数据时出现。 @@ -6187,8 +5966,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData子消息为旧元组。 - 此字段是可选的,仅在发生更新的表中REPLICA IDENTITY设置为FULL时才存在。 + 将后续 TupleData 子消息标识为旧元组。此字段可选,仅在发生更新的表将 REPLICA IDENTITY 设为 FULL 时出现。 @@ -6199,7 +5977,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分表示旧元组或主键的内容。仅在先前的'O'或'K'部分存在时才存在。 + 表示旧元组或主键内容的 TupleData 消息部分。仅在前面的'O'或'K'部分存在时出现。 @@ -6210,7 +5988,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData消息为新元组。 + 将后续 TupleData 消息标识为新元组。 @@ -6221,14 +5999,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分表示新元组的内容。 + 表示新元组内容的 TupleData 消息部分。 - 更新消息可能包含一个'K'消息部分,也可能包含一个'O'消息部分,或者两者都不包含,但绝不会同时包含两者。 + Update 消息可以包含 'K' 消息部分或 'O' 消息部分,也可以两者都不包含,但绝不会同时包含两者。 @@ -6244,7 +6022,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为删除消息。 + 将该消息标识为 Delete 消息。 @@ -6255,8 +6033,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6267,7 +6044,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。 + 关系的 OID,与 Relation 消息中的 ID 对应。 @@ -6278,8 +6055,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData子消息为键。 - 如果发生删除操作的表使用索引作为REPLICA IDENTITY,则存在此字段。 + 将后续 TupleData 子消息标识为键。如果发生删除的表使用索引作为 REPLICA IDENTITY,则出现此字段。 @@ -6290,8 +6066,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData消息为旧元组。 - 如果发生删除操作的表的REPLICA IDENTITY设置为FULL,则存在此字段。 + 将后续 TupleData 消息标识为旧元组。如果发生删除的表将 REPLICA IDENTITY 设为 FULL,则出现此字段。 @@ -6302,14 +6077,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分,表示旧元组或主键的内容,取决于前一个字段。 + 表示旧元组或主键内容的 TupleData 消息部分,具体取决于前一个字段。 - 删除消息可能包含一个'K'消息部分或一个'O'消息部分,但绝不会同时包含两者。 + Delete 消息可以包含 'K' 消息部分或 'O' 消息部分,但绝不会同时包含两者。 @@ -6325,7 +6100,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为截断消息。 + 将该消息标识为 Truncate 消息。 @@ -6336,8 +6111,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6371,7 +6145,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。该字段对每个关系都重复。 + 关系的 OID,与 Relation 消息中的 ID 对应。每个关系都重复出现此字段。 @@ -6396,7 +6170,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为流开始消息。 + 将该消息标识为 Stream Start 消息。 @@ -6407,7 +6181,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6437,7 +6211,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为流停止消息。 + 将该消息标识为 Stream Stop 消息。 @@ -6456,7 +6230,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为流提交消息。 + 将该消息标识为 Stream Commit 消息。 @@ -6467,7 +6241,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6485,22 +6259,22 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 提交的LSN。 + 提交的 LSN。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 事务的结束LSN。 + 事务的结束 LSN。 @@ -6511,7 +6285,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6530,7 +6304,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为流中止消息。 + 将该消息标识为 Stream Abort 消息。 @@ -6541,7 +6315,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6577,14 +6351,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务开始消息。 + 将该消息标识为 Begin Prepare 消息。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6595,7 +6369,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6610,7 +6384,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6621,7 +6395,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6651,7 +6425,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务消息。 + 将该消息标识为 Prepare 消息。 @@ -6669,7 +6443,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6680,7 +6454,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6695,7 +6469,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6706,7 +6480,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6736,7 +6510,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务提交消息。 + 将该消息标识为 Commit Prepared 消息。 @@ -6754,7 +6528,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6765,7 +6539,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6780,7 +6554,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6791,7 +6565,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6821,7 +6595,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务回滚消息。 + 将该消息标识为 Rollback Prepared 消息。 @@ -6839,7 +6613,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6850,7 +6624,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6865,7 +6639,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6887,7 +6661,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6917,7 +6691,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为流式预备事务消息。 + 将该消息标识为 Stream Prepare 消息。 @@ -6935,7 +6709,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6946,7 +6720,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6961,7 +6735,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6972,7 +6746,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -7015,14 +6789,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于每一列(除了生成的列),会出现以下子消息之一: + 接下来,每一列(生成列除外)都会出现以下子消息之一: Byte1('n') - 将数据标识为NULL值。 + 将该数据标识为 NULL 值。 @@ -7033,7 +6807,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('u') - 将TOASTed值标识为未更改的值(实际值未发送)。 + 标识未更改的 TOAST 值(不发送实际值)。 @@ -7044,7 +6818,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('t') - 将数据标识为文本格式化值。 + 将该数据标识为文本格式的值。 @@ -7055,7 +6829,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('b') - 将数据标识为二进制格式化值。 + 将该数据标识为二进制格式的值。 @@ -7073,9 +6847,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byten - 列的值,以二进制或文本格式呈现。 - (如前述格式字节中指定)。 - n是上述长度。 + 列值,采用二进制或文本格式(由前面的格式字节指定)。n 为上述长度。 diff --git a/zh/15/rangetypes.sgml b/zh/15/rangetypes.sgml index 68409fa3..5badec6c 100644 --- a/zh/15/rangetypes.sgml +++ b/zh/15/rangetypes.sgml @@ -5,11 +5,11 @@ 范围类型 - range type + 范围类型 - multirange type + 多范围类型 @@ -21,7 +21,7 @@ - 每种范围类型都有一个对应的多范围类型。多范围是由多个彼此不连续、非空且非 NULL 的范围构成的有序列表。大多数范围操作符也可作用于多范围,并且多范围还有一些专用函数。 + 每种范围类型都有一个对应的多范围类型。多范围是一个有序列表,其中的范围彼此不连续,且均非空、非 NULL。大多数范围操作符也可作用于多范围,并且多范围还有一些专用函数。 @@ -124,15 +124,15 @@ SELECT isempty(numrange(1, 5)); 无限(无界)范围 - 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作 +/-infinity,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的 +/-infinity 值。 + 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作正负无穷大,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的正负无穷大值。 - 具有infinity概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 + 具有无穷大概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 - 函数lower_infupper_inf分别测试范围的下界和上界是否为无限。 + 函数lower_infupper_inf分别测试范围是否没有下界和上界。 @@ -324,8 +324,8 @@ SELECT '[11:10, 23:00]'::timerange; 索引 - range type - indexes on + 范围类型 + 索引 @@ -357,7 +357,7 @@ CREATE INDEX reservation_idx ON reservation USING GIST (during); - 此外,也可以为范围类型的表列创建 B-树和哈希索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和哈希支持主要是为了允许在查询内部进行排序和哈希,而不是用于创建实际的索引。 + 此外,也可以为范围类型的表列创建 B-树和 hash 索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和 hash 支持主要是为了允许在查询内部进行排序和 hash 运算,而不是用于创建实际的索引。 @@ -366,8 +366,8 @@ CREATE INDEX reservation_idx ON reservation USING GIST (during); 范围上的约束 - range type - exclude + 范围类型 + 排他约束 diff --git a/zh/15/ref/alter_extension.sgml b/zh/15/ref/alter_extension.sgml index 3ceae003..b5824a68 100644 --- a/zh/15/ref/alter_extension.sgml +++ b/zh/15/ref/alter_extension.sgml @@ -170,7 +170,7 @@ ALTER EXTENSION name DROP 要添加到扩展中或从扩展中移除的对象名称。表、聚合、域、外部表、函数、 - 操作符、操作符类、操作符族、过程、例程、序列、文本搜索对象、类型和视图的名称 + 操作符、操作符类、操作符族、过程、例程、序列、文本检索对象、类型和视图的名称 可以带模式限定。 diff --git a/zh/15/ref/alter_tsconfig.sgml b/zh/15/ref/alter_tsconfig.sgml index 891dce66..0845a229 100644 --- a/zh/15/ref/alter_tsconfig.sgml +++ b/zh/15/ref/alter_tsconfig.sgml @@ -19,7 +19,7 @@ PostgreSQL documentation ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义 + 更改一个文本检索配置的定义 @@ -51,7 +51,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义。你可以修改其从记号类型到字典的映射, + 更改一个文本检索配置的定义。你可以修改其从词元类型到词典的映射, 或者更改该配置的名称或拥有者。 @@ -75,7 +75,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 一个现有文本搜索配置的名称(可以是模式限定的)。 + 一个现有文本检索配置的名称(可以是模式限定的)。 @@ -86,7 +86,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 由该配置的解析器发出的记号类型的名称。 + 由该配置的解析器发出的词元类型的名称。 @@ -97,7 +97,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 用于指定记号类型的文本搜索字典名称。如果列出了多个字典, + 用于指定词元类型的文本检索词典名称。如果列出了多个词典, 将按指定顺序依次查阅它们。 @@ -109,7 +109,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 在映射中要替换的文本搜索字典的名称。 + 在映射中要替换的文本检索词典的名称。 @@ -121,7 +121,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA 被用来替代old_dictionary - 的文本搜索字典的名称。 + 的文本检索词典的名称。 @@ -132,7 +132,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新名称。 + 该文本检索配置的新名称。 @@ -143,7 +143,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新拥有者。 + 该文本检索配置的新拥有者。 @@ -154,7 +154,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新模式。 + 该文本检索配置的新模式。 @@ -163,17 +163,17 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - ADD MAPPING FOR形式会为指定记号类型设置要查阅的字典列表; - 如果任一记号类型已经有映射,则会报错。ALTER MAPPING FOR - 形式作用相同,但会先移除这些记号类型的任何现有映射。 + ADD MAPPING FOR形式会为指定词元类型设置要查阅的词典列表; + 如果任一词元类型已经有映射,则会报错。ALTER MAPPING FOR + 形式作用相同,但会先移除这些词元类型的任何现有映射。 ALTER MAPPING REPLACE形式会在 old_dictionary出现的任何位置, 用new_dictionary替换它。 - 如果出现FOR,则只对指定的记号类型这样做;如果未出现 + 如果出现FOR,则只对指定的词元类型这样做;如果未出现 FOR,则对该配置的所有映射这样做。 - DROP MAPPING形式会移除指定记号类型的所有字典,使这些类型的 - 记号被文本搜索配置忽略。除非出现IF EXISTS,否则如果这些 - 记号类型没有映射就会报错。 + DROP MAPPING形式会移除指定词元类型的所有词典,使这些类型的 + 词元被文本检索配置忽略。除非出现IF EXISTS,否则如果这些 + 词元类型没有映射就会报错。 @@ -187,7 +187,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA 下面的示例将my_config中凡是使用 - english字典的地方,都替换为swedish字典。 + english词典的地方,都替换为swedish词典。 diff --git a/zh/15/ref/alter_tsdictionary.sgml b/zh/15/ref/alter_tsdictionary.sgml index 163d788b..798c6734 100644 --- a/zh/15/ref/alter_tsdictionary.sgml +++ b/zh/15/ref/alter_tsdictionary.sgml @@ -19,7 +19,7 @@ PostgreSQL documentation ALTER TEXT SEARCH DICTIONARY - 更改一个文本搜索字典的定义 + 更改一个文本检索词典的定义 @@ -43,14 +43,14 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - ALTER TEXT SEARCH DICTIONARY更改文本搜索字典的 - 定义。你可以更改该字典的模板相关选项,也可以更改该字典的名称或拥有者。 + ALTER TEXT SEARCH DICTIONARY更改文本检索词典的 + 定义。你可以更改该词典的模板相关选项,也可以更改该词典的名称或拥有者。 - 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该字典 + 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该词典 的拥有者。 @@ -67,7 +67,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 一个现有文本搜索字典的名称(可以是模式限定的)。 + 一个现有文本检索词典的名称(可以是模式限定的)。 @@ -78,7 +78,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -89,7 +89,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 模板相关选项要使用的新值。如果省略等号和值,则会从该字典中移除 + 模板相关选项要使用的新值。如果省略等号和值,则会从该词典中移除 该选项之前的设置,从而允许使用默认值。 @@ -101,7 +101,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新名称。 + 该文本检索词典的新名称。 @@ -112,7 +112,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新拥有者。 + 该文本检索词典的新拥有者。 @@ -123,7 +123,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新模式。 + 该文本检索词典的新模式。 @@ -144,7 +144,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 下面的示例命令更改了一个基于 Snowball 的字典的停用词列表。其他参数 + 下面的示例命令更改了一个基于 Snowball 的词典的停用词列表。其他参数 保持不变。 @@ -170,7 +170,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( language = dutch, StopWords ); - 下面的示例命令更新了该字典的定义,但实际上并没有做 + 下面的示例命令更新了该词典的定义,但实际上并没有做 任何更改。 @@ -178,7 +178,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( dummy ); (之所以可行,是因为选项移除代码在不存在该选项时也不会报错。) - 这种技巧在修改该字典的配置文件时很有用:ALTER + 这种技巧在修改该词典的配置文件时很有用:ALTER 会强制现有数据库会话重新读取配置文件,而如果它们先前已经读取过这 些文件,本来是不会再次读取的。 diff --git a/zh/15/ref/alter_tsparser.sgml b/zh/15/ref/alter_tsparser.sgml index 0844cb0a..ccc73f05 100644 --- a/zh/15/ref/alter_tsparser.sgml +++ b/zh/15/ref/alter_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH PARSER - 更改一个全文检索解析器的定义 + 更改一个文本检索解析器的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA 描述 - ALTER TEXT SEARCH PARSER更改全文检索解析器的定义。 + ALTER TEXT SEARCH PARSER更改文本检索解析器的定义。 当前唯一支持的功能是更改该解析器的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA name - 一个现有全文检索解析器的名称(可以是模式限定的)。 + 一个现有文本检索解析器的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_name - 该全文检索解析器的新名称。 + 该文本检索解析器的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_schema - 该全文检索解析器的新模式。 + 该文本检索解析器的新模式。 diff --git a/zh/15/ref/alter_tstemplate.sgml b/zh/15/ref/alter_tstemplate.sgml index a3eec599..9c9dfc2c 100644 --- a/zh/15/ref/alter_tstemplate.sgml +++ b/zh/15/ref/alter_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH TEMPLATE - 更改一个文本搜索模板的定义 + 更改一个文本检索模板的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA 描述 - ALTER TEXT SEARCH TEMPLATE更改文本搜索模板的定义。 + ALTER TEXT SEARCH TEMPLATE更改文本检索模板的定义。 当前唯一支持的功能是更改该模板的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA name - 一个现有文本搜索模板的名称(可以是模式限定的)。 + 一个现有文本检索模板的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_name - 该文本搜索模板的新名称。 + 该文本检索模板的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_schema - 该文本搜索模板的新模式。 + 该文本检索模板的新模式。 diff --git a/zh/15/ref/create_tsconfig.sgml b/zh/15/ref/create_tsconfig.sgml index 52970b36..fc77edb9 100644 --- a/zh/15/ref/create_tsconfig.sgml +++ b/zh/15/ref/create_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH CONFIGURATION - 定义一个新的文本搜索配置 + 定义一个新的文本检索配置 @@ -33,24 +33,24 @@ CREATE TEXT SEARCH CONFIGURATION name CREATE TEXT SEARCH CONFIGURATION - 创建一个新的文本搜索配置。文本搜索配置指定一个能把字符串拆分为记号 - 的文本搜索解析器,以及一些可用于判断哪些记号对搜索有意义的词典。 + 创建一个新的文本检索配置。文本检索配置指定一个能把字符串拆分为词元 + 的文本检索解析器,以及一些可用于判断哪些词元对搜索有意义的词典。 - 如果只指定了解析器,那么新文本搜索配置最初没有从记号类型到词典的映射, + 如果只指定了解析器,那么新文本检索配置最初没有从词元类型到词典的映射, 因而会忽略所有词。要让该配置真正可用,必须使用后续的ALTER TEXT SEARCH CONFIGURATION命令创建映射。 - 另一种方式是复制一个现有的文本搜索配置。 + 另一种方式是复制一个现有的文本检索配置。 - 如果给出了一个模式名称,则文本搜索配置会被创建在指定的模式中。否则它将会 + 如果给出了一个模式名称,则文本检索配置会被创建在指定的模式中。否则它将会 被创建在当前模式中。 - 定义该文本搜索配置的用户会成为其拥有者。 + 定义该文本检索配置的用户会成为其拥有者。 @@ -66,7 +66,7 @@ CREATE TEXT SEARCH CONFIGURATION namename - 要创建的文本搜索配置的名称。该名称可以是模式限定的。 + 要创建的文本检索配置的名称。该名称可以是模式限定的。 @@ -75,7 +75,7 @@ CREATE TEXT SEARCH CONFIGURATION nameparser_name - 此配置要使用的文本搜索解析器的名称。 + 此配置要使用的文本检索解析器的名称。 @@ -84,7 +84,7 @@ CREATE TEXT SEARCH CONFIGURATION namesource_config - 要复制的现有文本搜索配置的名称。 + 要复制的现有文本检索配置的名称。 diff --git a/zh/15/ref/create_tsdictionary.sgml b/zh/15/ref/create_tsdictionary.sgml index c45a7240..823710b7 100644 --- a/zh/15/ref/create_tsdictionary.sgml +++ b/zh/15/ref/create_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH DICTIONARY - 定义一个新的文本搜索字典 + 定义一个新的文本检索词典 @@ -33,19 +33,19 @@ CREATE TEXT SEARCH DICTIONARY name CREATE TEXT SEARCH DICTIONARY创建一个 - 新的文本搜索字典。文本搜索字典指定一种在搜索时识别哪些词值得关注、 - 哪些词不值得关注的方式。字典依赖于文本搜索模板,后者规定了实际执行 - 这项工作的函数。通常,字典会提供一些选项,用来控制模板函数的具体 + 新的文本检索词典。文本检索词典指定一种在搜索时识别哪些词值得关注、 + 哪些词不值得关注的方式。词典依赖于文本检索模板,后者规定了实际执行 + 这项工作的函数。通常,词典会提供一些选项,用来控制模板函数的具体 行为。 - 如果给出了一个模式名称,那么该文本搜索字典会被创建在指定的模式中。 + 如果给出了一个模式名称,那么该文本检索词典会被创建在指定的模式中。 否则它会被创建在当前模式中。 - 定义文本搜索字典的用户将成为其拥有者。 + 定义文本检索词典的用户将成为其拥有者。 @@ -61,7 +61,7 @@ CREATE TEXT SEARCH DICTIONARY name name - 要创建的文本搜索字典的名称。该名称可以被模式限定。 + 要创建的文本检索词典的名称。该名称可以被模式限定。 @@ -70,7 +70,7 @@ CREATE TEXT SEARCH DICTIONARY name template - 用于定义该字典基本行为的文本搜索模板名称。 + 用于定义该词典基本行为的文本检索模板名称。 @@ -79,7 +79,7 @@ CREATE TEXT SEARCH DICTIONARY name option - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -105,7 +105,7 @@ CREATE TEXT SEARCH DICTIONARY name 下面的示例命令创建了一个基于 Snowball 且使用非标准停用词列表的 - 字典。 + 词典。 diff --git a/zh/15/ref/create_tsparser.sgml b/zh/15/ref/create_tsparser.sgml index 358152ce..88be54e6 100644 --- a/zh/15/ref/create_tsparser.sgml +++ b/zh/15/ref/create_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH PARSER - 定义一个新的全文检索解析器 + 定义一个新的文本检索解析器 @@ -36,19 +36,19 @@ CREATE TEXT SEARCH PARSER name ( CREATE TEXT SEARCH PARSER创建一个 - 新的全文检索解析器。全文检索解析器定义了一种方法,用于将文本字符串 - 拆分成记号并为这些记号指定类型(类别)。解析器本身并没有太大用处, - 必须与一些全文检索字典一起绑定到一个全文检索配置中,才能用于搜索。 + 新的文本检索解析器。文本检索解析器定义了一种方法,用于将文本字符串 + 拆分成词元并为这些词元指定类型(类别)。解析器本身并没有太大用处, + 必须与一些文本检索词典一起绑定到一个文本检索配置中,才能用于搜索。 - 如果给出了一个模式名称,那么全文检索解析器将被创建在指定的模式中。 + 如果给出了一个模式名称,那么文本检索解析器将被创建在指定的模式中。 否则它会被创建在当前模式中。 要使用CREATE TEXT SEARCH PARSER,你必须是超级用户。 - 之所以有此限制,是因为错误的全文检索解析器定义可能会让服务器陷入 + 之所以有此限制,是因为错误的文本检索解析器定义可能会让服务器陷入 混乱,甚至崩溃。 @@ -65,7 +65,7 @@ CREATE TEXT SEARCH PARSER name ( name - 要创建的全文检索解析器的名称。该名称可以是模式限定的。 + 要创建的文本检索解析器的名称。该名称可以是模式限定的。 @@ -83,7 +83,7 @@ CREATE TEXT SEARCH PARSER name ( gettoken_function - 该解析器的获取下一个记号的函数名称。 + 该解析器的获取下一个词元的函数名称。 @@ -101,7 +101,7 @@ CREATE TEXT SEARCH PARSER name ( lextypes_function - 该解析器的 lextypes 函数的名称(该函数返回它所产生的记号类型集合的 + 该解析器的 lextypes 函数的名称(该函数返回它所产生的词元类型集合的 信息)。 @@ -111,7 +111,7 @@ CREATE TEXT SEARCH PARSER name ( headline_function - 该解析器的 headline 函数的名称(该函数对一组记号生成摘要)。 + 该解析器的 headline 函数的名称(该函数对一组词元生成摘要)。 diff --git a/zh/15/ref/create_tstemplate.sgml b/zh/15/ref/create_tstemplate.sgml index 702233e4..0f1b4e1a 100644 --- a/zh/15/ref/create_tstemplate.sgml +++ b/zh/15/ref/create_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH TEMPLATE - 定义一个新的全文检索模板 + 定义一个新的文本检索模板 @@ -33,22 +33,22 @@ CREATE TEXT SEARCH TEMPLATE name ( CREATE TEXT SEARCH TEMPLATE创建一个 - 新的全文检索模板。全文检索模板定义实现全文检索字典的函数。模板本身 - 并无直接用途,必须先实例化为字典后才能使用。字典通常会指定要传递给 + 新的文本检索模板。文本检索模板定义实现文本检索词典的函数。模板本身 + 并无直接用途,必须先实例化为词典后才能使用。词典通常会指定要传递给 模板函数的参数。 - 如果给出了模式名称,则全文检索模板会被创建在指定模式中。否则它会被 + 如果给出了模式名称,则文本检索模板会被创建在指定模式中。否则它会被 创建在当前模式中。 要使用CREATE TEXT SEARCH TEMPLATE,你 - 必须是超级用户。之所以有此限制,是因为错误的全文检索模板定义可能使 - 服务器陷入混乱,甚至崩溃。将模板与字典分离的原因在于,模板封装了定 - 义字典时那些不安全的方面。而在定义字典时可设置的参数, - 对非特权用户来说是安全的,因此创建字典不必是特权操作。 + 必须是超级用户。之所以有此限制,是因为错误的文本检索模板定义可能使 + 服务器陷入混乱,甚至崩溃。将模板与词典分离的原因在于,模板封装了定 + 义词典时那些不安全的方面。而在定义词典时可设置的参数, + 由普通用户设置也是安全的,因此创建词典不必是特权操作。 @@ -64,7 +64,7 @@ CREATE TEXT SEARCH TEMPLATE name ( name - 要创建的全文检索模板名称。该名称可以是模式限定的。 + 要创建的文本检索模板名称。该名称可以是模式限定的。 diff --git a/zh/15/ref/drop_opclass.sgml b/zh/15/ref/drop_opclass.sgml index 9d67dc64..545a2517 100644 --- a/zh/15/ref/drop_opclass.sgml +++ b/zh/15/ref/drop_opclass.sgml @@ -110,7 +110,7 @@ DROP OPERATOR CLASS [ IF EXISTS ] name示例 - 移除 B-tree 操作符类widget_ops: + 移除 B-树操作符类widget_ops DROP OPERATOR CLASS widget_ops USING btree; diff --git a/zh/15/ref/drop_tsconfig.sgml b/zh/15/ref/drop_tsconfig.sgml index ea139802..b3ebb9d1 100644 --- a/zh/15/ref/drop_tsconfig.sgml +++ b/zh/15/ref/drop_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH CONFIGURATION - 移除一个文本搜索配置 + 移除一个文本检索配置 @@ -29,7 +29,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 描述 - DROP TEXT SEARCH CONFIGURATION删除一个现有文本搜索配置。 + DROP TEXT SEARCH CONFIGURATION删除一个现有文本检索配置。 要执行此命令,你必须是该配置的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name IF EXISTS - 如果该文本搜索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name name - 现有文本搜索配置的名称(可以被模式限定)。 + 现有文本检索配置的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name CASCADE - 自动删除依赖于该文本搜索配置的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索配置的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name RESTRICT - 如果有任何对象依赖于该文本搜索配置,则拒绝删除该配置。这是默认值。 + 如果有任何对象依赖于该文本检索配置,则拒绝删除该配置。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 示例 - 移除文本搜索配置my_english: + 移除文本检索配置my_english DROP TEXT SEARCH CONFIGURATION my_english; 如果已有索引在to_tsvector调用中引用了该配置, - 此命令将不会成功。加上CASCADE可以在删除该文本搜索配置的同时删除这类索引。 + 此命令将不会成功。加上CASCADE可以在删除该文本检索配置的同时删除这类索引。 diff --git a/zh/15/ref/drop_tsdictionary.sgml b/zh/15/ref/drop_tsdictionary.sgml index 316c5d00..0f7751a1 100644 --- a/zh/15/ref/drop_tsdictionary.sgml +++ b/zh/15/ref/drop_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH DICTIONARY - 移除一个文本搜索字典 + 移除一个文本检索词典 @@ -29,8 +29,8 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name描述 - DROP TEXT SEARCH DICTIONARY删除一个现有文本搜索字典。 - 要执行此命令,你必须是该字典的拥有者。 + DROP TEXT SEARCH DICTIONARY删除一个现有文本检索词典。 + 要执行此命令,你必须是该词典的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索字典不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索词典不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] namename - 一个现有文本搜索字典的名称(可以被模式限定)。 + 一个现有文本检索词典的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索字典的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索词典的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索字典,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索词典,则拒绝删除它。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name示例 - 移除文本搜索字典english: + 移除文本检索词典english DROP TEXT SEARCH DICTIONARY english; - 如果已有文本搜索配置使用该字典,此命令将不会成功。 - 加上CASCADE可以在删除字典的同时删除这类配置。 + 如果已有文本检索配置使用该词典,此命令将不会成功。 + 加上CASCADE可以在删除词典的同时删除这类配置。 diff --git a/zh/15/ref/drop_tsparser.sgml b/zh/15/ref/drop_tsparser.sgml index a65f47be..ea74f0f8 100644 --- a/zh/15/ref/drop_tsparser.sgml +++ b/zh/15/ref/drop_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH PARSER - 移除一个文本搜索解析器 + 移除一个文本检索解析器 @@ -29,7 +29,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name描述 - DROP TEXT SEARCH PARSER删除一个现有文本搜索解析器。 + DROP TEXT SEARCH PARSER删除一个现有文本检索解析器。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] namename - 一个现有文本搜索解析器的名称(可以被模式限定)。 + 一个现有文本检索解析器的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索解析器的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索解析器的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索解析器,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索解析器,则拒绝删除它。这是默认值。 @@ -82,13 +82,13 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name示例 - 移除文本搜索解析器my_parser: + 移除文本检索解析器my_parser DROP TEXT SEARCH PARSER my_parser; - 如果已有文本搜索配置使用该解析器,此命令将不会成功。 + 如果已有文本检索配置使用该解析器,此命令将不会成功。 加上CASCADE可以在删除解析器的同时删除这类配置。 diff --git a/zh/15/ref/drop_tstemplate.sgml b/zh/15/ref/drop_tstemplate.sgml index fa1faab0..3a44c927 100644 --- a/zh/15/ref/drop_tstemplate.sgml +++ b/zh/15/ref/drop_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH TEMPLATE - 移除一个文本搜索模板 + 移除一个文本检索模板 @@ -29,7 +29,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name描述 - DROP TEXT SEARCH TEMPLATE删除一个现有文本搜索模板。 + DROP TEXT SEARCH TEMPLATE删除一个现有文本检索模板。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] namename - 现有文本搜索模板的名称(可以被模式限定)。 + 现有文本检索模板的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索模板的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索模板的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索模板,则拒绝删除该模板。这是默认值。 + 如果有任何对象依赖于该文本检索模板,则拒绝删除该模板。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name示例 - 移除文本搜索模板thesaurus: + 移除文本检索模板thesaurus DROP TEXT SEARCH TEMPLATE thesaurus; - 如果已有文本搜索字典使用该模板,此命令将不会成功。加上CASCADE - 可以在删除该模板的同时删除这类字典。 + 如果已有文本检索词典使用该模板,此命令将不会成功。加上CASCADE + 可以在删除该模板的同时删除这类词典。 diff --git a/zh/15/ref/initdb.sgml b/zh/15/ref/initdb.sgml index 16df267e..011f1460 100644 --- a/zh/15/ref/initdb.sgml +++ b/zh/15/ref/initdb.sgml @@ -36,13 +36,11 @@ PostgreSQL documentation 描述 - initdb创建一个新的PostgreSQL - 数据库集簇。 + initdb创建一个新的PostgreSQL数据库集簇。数据库集簇是由单个服务器实例管理的一组数据库。 - 创建数据库集簇包括创建用于存放集簇数据的 - 目录, + 创建数据库集簇包括创建用于存放数据库数据的目录, 生成共享系统目录表(属于整个集簇而不是某个特定数据库的表),以及创建 postgrestemplate1template0 数据库。postgres @@ -182,7 +180,7 @@ PostgreSQL documentation - + @@ -203,23 +201,16 @@ PostgreSQL documentation - - - + - 对数据页启用校验和,以帮助检测原本会悄无声息发生的、由 I/O 系统导致的损坏。 - 该项默认启用;使用可禁用校验和。 - - - - 启用校验和可能会带来小幅性能损失。如果启用,就会为所有数据库中的所有对象计算校验和。 - 所有校验和失败都会在 - - pg_stat_database视图中报告。详见 - 。 + 在数据页上使用校验和,帮助检测 I/O 系统造成的、否则可能悄无声息的数据损坏。 + 启用校验和可能会带来明显的性能损失。如果启用,就会为所有数据库中的所有对象计算校验和。 + 所有校验和失败都会在 + pg_stat_database视图中报告。 + 详见 @@ -259,8 +250,6 @@ PostgreSQL documentation - - @@ -272,11 +261,25 @@ PostgreSQL documentation - - + + + - 不启用数据校验和。 + 默认情况下,initdb会等待所有文件都安全写入磁盘。该选项使 + initdb在不等待的情况下返回,速度更快,但这意味着如果后续操作系统崩溃, + 数据目录可能会损坏。通常,该选项适用于测试,但不应用于创建生产环境安装。 + + + + + + + + + 默认情况下,initdb会在其输出末尾写出如何启动集簇的说明。 + 该选项会省略这些说明。它主要供那些对initdb进行平台特定封装的工具使用, + 因为在这种情况下那些说明很可能并不正确。 @@ -285,7 +288,20 @@ PostgreSQL documentation - 使initdb从文件中读取引导超级用户的密码。文件的第一行会被当作密码。 + 使initdb从文件中读取数据库超级用户的密码。文件的第一行会被当作密码。 + + + + + + + + + + 将所有数据库文件安全地写入磁盘并退出。这不会执行任何常规的 + initdb操作。通常,该选项可用于在将 + off改为on后, + 确保能够可靠恢复。 @@ -295,7 +311,7 @@ PostgreSQL documentation - 设置默认文本搜索配置。更多信息见 + 设置默认文本检索配置。更多信息见 @@ -306,8 +322,9 @@ PostgreSQL documentation - 选择数据库超级用户的用户名。 - 默认值是运行initdb的操作系统用户名。 + 选择数据库超级用户的用户名。默认值是运行initdb的有效用户的名称。 + 超级用户的名称本身并不重要,不过即使操作系统用户名称不同,也可以选择沿用惯常的名称 + postgres @@ -317,7 +334,7 @@ PostgreSQL documentation - 使initdb提示输入要赋给引导超级用户的密码。如果不打算使用密码认证, + 使initdb提示输入要赋给数据库超级用户的密码。如果不打算使用密码认证, 这一点并不重要。否则,在设置密码之前将无法使用密码认证。 @@ -355,19 +372,6 @@ PostgreSQL documentation 还提供了其他一些较少使用的选项: - - - - - - 在initdb期间,强制将服务器参数name - 设为value,并把该设置写入生成的 - postgresql.conf文件,以便在今后的服务器运行中生效。 - 该选项可指定多次,以设置多个参数。它主要用于默认参数下服务器根本无法启动的环境。 - - - - @@ -409,91 +413,6 @@ PostgreSQL documentation - - - - - - - 默认情况下,initdb会等待所有文件都安全写入磁盘。该选项使 - initdb在不等待的情况下返回,速度更快,但这意味着如果后续操作系统崩溃, - 数据目录可能会损坏。通常,该选项适用于测试,但不应用于创建生产环境安装。 - - - - - - - - - 默认情况下,initdb会将所有数据库文件安全地写入磁盘。 - 该选项指示initdb跳过同步各个数据库目录中的所有文件、这些数据库目录本身 - 以及表空间目录,也就是base子目录中的所有内容和任何其他表空间目录。 - 其他文件,例如pg_walpg_xact中的文件, - 仍会被同步,除非也指定了。 - - - 请注意,如果与 - 一起使用,上述部分或全部文件与目录仍会被同步, - 因为syncfs处理的是整个文件系统。 - - - 该选项主要供那些会另行确保这些被跳过文件已同步到磁盘的工具在内部使用。 - - - - - - - - - 默认情况下,initdb会在其输出末尾写出如何启动集簇的说明。 - 该选项会省略这些说明。它主要供那些对initdb进行平台特定封装的工具使用, - 因为在这种情况下那些说明很可能并不正确。 - - - - - - - - - - 显示内部设置并退出,不执行其他操作。可用于调试initdb的安装。 - - - - - - - - - 设为fsync(默认值)时,initdb会递归打开并同步 - 数据目录中的所有文件。查找文件时会跟随 WAL 目录和每个已配置表空间的符号链接。 - - - 在 Linux 上,也可以改用syncfs,请求操作系统同步包含数据目录、 - WAL 文件以及每个表空间的整个文件系统。使用syncfs时需注意的事项见 - 。 - - - 使用时,该选项不起作用。 - - - - - - - - - - 将所有数据库文件安全地写入磁盘并退出。这不会执行任何常规的 - initdb操作。通常,该选项可用于在将 - off改为on后, - 确保能够可靠恢复。 - - - diff --git a/zh/15/ref/pgbench.sgml b/zh/15/ref/pgbench.sgml index f699e735..370c1a18 100644 --- a/zh/15/ref/pgbench.sgml +++ b/zh/15/ref/pgbench.sgml @@ -39,7 +39,7 @@ PostgreSQL documentation 描述 - pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,必要时可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 + pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,也可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 @@ -69,7 +69,7 @@ tps = 896.967014 (without initial connection time) - 默认的类 TPC-B 事务测试要求预先建立特定的表。应使用(initialize)选项调用pgbench来创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: + 默认的类 TPC-B 事务测试要求预先建立特定的表。应使用(初始化)选项调用pgbench来创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: pgbench -i other-options dbname @@ -89,14 +89,14 @@ pgbench -i other-options 在默认的比例因子 1 下,这些表最初包含如下行数: -table # of rows +表 行数 --------------------------------- pgbench_branches 1 pgbench_tellers 10 pgbench_accounts 100000 pgbench_history 0 - 可以使用(比例因子)选项来增加行数,而且在大多数场景下也确实应该这样做。此时还可以配合使用(fillfactor)选项。 + 可以使用(比例因子)选项来增加行数,而且在大多数场景下通常也应该这样做。此时还可以配合使用(fillfactor)选项。 @@ -116,7 +116,7 @@ pgbench options d 选项 - 下面分成三个部分。数据库初始化期间使用的选项和运行基准时会使用不同的选项,但也有一些选项在两种情况下都使用。 + 以下内容分为三个小节。数据库初始化和运行基准测试时使用不同的选项,但有些选项在这两种情况下都适用。 @@ -129,8 +129,7 @@ pgbench options d - - + dbname @@ -191,12 +190,12 @@ pgbench options d 生成数据并将其装载到标准表中,替换其中任何已有数据。 - 使用g(客户端生成数据)时,数据由pgbench客户端生成,再通过COPY发送到服务器,因此会大量占用客户端/服务器带宽。对于 14 及以上版本的PostgreSQLpgbench会在普通(非分区)表上使用选项装载数据,以加快后续的VACUUM。使用g时,在为所有表生成数据的过程中,每生成 100,000 行会输出一条日志消息。 + 使用g(客户端生成数据)时,数据由pgbench客户端生成,再通过COPY发送到服务器,因此会大量占用客户端/服务器带宽。对于 14 及以上版本的PostgreSQL,除非启用了分区,pgbench会使用 FREEZE 选项,以加快后续的VACUUM。使用g时,在为pgbench_accounts表生成数据的过程中,每生成 100,000 行会输出一条日志消息。 使用G(服务器端生成数据)时, pgbench客户端只发送较小的查询,随后实际数据在服务器端生成。 - 这种方式几乎不需要额外带宽,但服务器会承担更多工作。 + 这种方式不需要大量带宽,但服务器会承担更多工作。 使用G时,生成数据期间不会打印任何进度消息。 @@ -416,6 +415,16 @@ pgbench options d + + + + + + 打印调试输出。 + + + + varname=value varname=value @@ -505,13 +514,13 @@ pgbench options d 用于向服务器提交查询的协议: - simple: 使用简单查询协议。 + simple:使用简单查询协议。 - extended: 使用扩展查询协议。 + extended:使用扩展查询协议。 - prepared: 使用带有预备语句的扩展查询协议。 + prepared:使用带有预备语句的扩展查询协议。 @@ -572,7 +581,7 @@ pgbench options d - 在基准测试完成后,报告每条语句的以下统计信息:平均延迟(从客户端视角看到的语句执行时间)、失败次数,以及该语句因串行化或死锁错误而发生的重试次数。仅当选项不等于 1 时,报告才会显示重试统计信息。 + 在基准测试完成后,报告每条命令的以下统计信息:平均延迟(从客户端视角看到的语句执行时间)、失败次数,以及该命令因串行化或死锁错误而发生的重试次数。仅当选项不等于 1 时,报告才会显示重试统计信息。 @@ -607,7 +616,7 @@ pgbench options d 较高的计划滞后时间表明,在所选客户端数和线程数下,系统无法以指定速率处理事务。 当平均事务执行时间长于事务之间的计划间隔时,后续事务会不断进一步落后, - 而计划滞后时间也会随着测试持续时间增加。在这种情况下,只能降低指定的事务速率。 + 而计划滞后时间也会随着测试持续时间增加。在这种情况下,需要降低指定的事务速率。 @@ -619,7 +628,7 @@ pgbench options d pgbench输出中报告指定的比例因子。 - 对于内置测试,这通常没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 + 对于内置测试,这没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 但在只测试自定义基准(选项)时, 除非使用此选项,否则比例因子会被报告为 1。 @@ -686,17 +695,7 @@ pgbench options d - - - - - 当任一客户端因错误被中止时,立即退出。如果不指定该选项,即使某个客户端被中止,其他客户端仍可按的设定继续运行,此时pgbench会输出不完整的结果。 - - - 请注意,串行化失败或死锁失败不会中止客户端,因此不受该选项影响。更多信息见 。 - - - + @@ -733,7 +732,7 @@ pgbench options d 启用对出现串行化/死锁错误的事务进行重试,并设置最大尝试次数。此选项可与 - 组合使用,后者限制所有事务尝试的总耗时; + 组合使用,后者限制同一事务所有尝试的总耗时; 此外,如果没有, 则不能使用无限次尝试(--max-tries=0)。 默认值为 1,出现串行化/死锁错误的事务不会重试。有关此类事务重试的更多信息,见 @@ -813,7 +812,7 @@ pgbench options d - 打印关于所有错误和失败的消息(即不会重试的错误),包括超出了哪一种重试限制,以及对于串行化/死锁失败超出的幅度。(请注意,这种情况下输出量可能会显著增加。)更多信息见。 + 打印关于所有错误和失败(不再重试的错误)的消息,包括超出了哪一种重试限制,以及对于串行化/死锁失败超出的幅度。(请注意,这种情况下输出量可能会显著增加。)更多信息见 @@ -828,18 +827,11 @@ pgbench options d 公共选项 - pgbench 还接受以下用于连接参数及其他通用设置的命令行参数: + pgbench 还接受以下用于连接参数的通用命令行参数: - - - - - 打印调试输出。 - - - + hostname @@ -903,7 +895,7 @@ pgbench options d 成功运行会以状态 0 退出。状态 1 表示静态问题,例如无效的命令行选项,或者按理不应发生的内部错误。 在启动基准测试时发生的早期错误,例如初始连接失败,也会以状态 1 退出。 - 运行过程中出现的错误,例如数据库错误或脚本中的问题,会导致退出状态 2。在后一种情况下,如果未指定pgbench会打印部分结果。 + 运行过程中出现的错误,例如数据库错误或脚本中的问题,会导致退出状态 2。在后一种情况下,pgbench会打印部分结果。 @@ -941,7 +933,7 @@ pgbench options d 注解 - + 在<application>pgbench</application>中实际执行的<quote>事务</quote>是什么? @@ -996,7 +988,7 @@ pgbench options d - 假定pgbench脚本不包含不完整的 SQL 事务块。如果在运行时客户端在尚未完成最后一个事务块时就到达脚本末尾,它将被中止。 + 假定pgbench脚本不包含不完整的 SQL 事务块。如果在运行时客户端在尚未完成最后一个事务块时就到达脚本末尾,该客户端将被中止。 @@ -1033,7 +1025,7 @@ pgbench options d default_seed - 默认在哈希和伪随机置换函数中使用的种子 + 默认在 hash 和伪随机置换函数中使用的种子 @@ -1050,7 +1042,7 @@ pgbench options d - 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令及其参数之间以空白分隔。支持的元命令如下: + 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令的参数以空白分隔。支持的元命令如下: @@ -1088,7 +1080,7 @@ UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid RETURNING abalance \gset --- compound of two queries +-- 两个查询的组合 SELECT 1 \; SELECT 2 AS two, 3 AS three \gset p_ SELECT 4 AS four \; SELECT 5 AS five \aset @@ -1180,7 +1172,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset - command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在其开头再写一个冒号。 + command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在argument开头再写一个冒号。 @@ -1212,13 +1204,13 @@ SELECT 4 AS four \; SELECT 5 AS five \aset \startpipeline - \syncpipeline + \endpipeline - 这组命令用于实现 SQL 语句的流水线执行。流水线必须以\startpipeline开始,并以\endpipeline结束;在两者之间可以出现任意数量的\syncpipeline,它会发送一个sync 消息,但不会结束当前流水线,同时会刷新发送缓冲区。在流水线模式下,语句会发送到服务器,而不等待前一条语句的结果。更多细节见。流水线模式要求使用扩展查询协议。 + 这些命令界定 SQL 语句管道的开始和结束。在管道模式下,语句会发送到服务器,而不等待前一条语句的结果。更多细节见。管道模式要求使用扩展查询协议。 @@ -1514,7 +1506,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 加 + 加法 5 + 4 @@ -1528,7 +1520,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 减 + 减法 3 - 2.0 @@ -1542,7 +1534,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 乘 + 乘法 5 * 4 @@ -1556,7 +1548,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 除法(如果两个输入都是整数,则将结果截断为零) + 除法(如果两个输入都是整数,则将结果向零截断) 5 / 3 @@ -1584,7 +1576,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 取反 + 取相反数 - 2.0 @@ -1674,7 +1666,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset double - 指数(e 的给定次幂) + 指数函数(e 的给定次幂) exp(1.0) @@ -1716,7 +1708,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算 FNV-1a 哈希。 + 计算 FNV-1a hash hash_fnv1a(10, 5432) @@ -1730,7 +1722,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算 MurmurHash2 哈希。 + 计算 MurmurHash2 hash hash_murmur2(10, 5432) @@ -1800,8 +1792,8 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - i的排列值,范围在[0, size)内。 - 它表示i(模size)在整数0...size-1的伪随机排列中的新位置;该排列由seed参数化,详见下文。 + i的置换值,范围在[0, size)内。 + 它表示i(模size)在整数0...size-1的伪随机置换中的新位置;该置换由seed参数化,详见下文。 permute(0, 4) @@ -1861,7 +1853,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算[lb, ub]中的指数分布随机整数,如下所示。 + 计算[lb, ub]中的指数分布随机整数,详见下文。 random_exponential(1, 10, 3.0) @@ -1875,7 +1867,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算[lb, ub]中的高斯分布随机整数,如下所示。 + 计算[lb, ub]中的高斯分布随机整数,详见下文。 random_gaussian(1, 10, 2.5) @@ -1922,7 +1914,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset - 对于指数分布,parameter通过在parameter处截断一个快速衰减的指数分布,再将其投影到边界之间的整数上,从而控制分布。准确地说, + 对于指数分布,parameter通过在parameter处截断一个快速衰减的指数分布,再将其投影到边界之间的整数上,从而控制分布。准确地说,令 f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) @@ -1930,7 +1922,7 @@ f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) - 直观地说,parameter越大,越靠近min的值越容易被抽到,而越靠近max的值越不容易被抽到。parameter越接近 0,分布就越平坦(也就越均匀)。对这种分布的一个粗略近似是:范围内最靠近min的那 1% 常见值,大约会占到parameter% 的抽样次数。parameter必须严格大于 0。 + 直观地说,parameter越大,越靠近min的值越容易被抽到,而越靠近max的值越不容易被抽到。parameter越接近 0,分布就越平坦(也就越均匀)。对这种分布的一个粗略近似是:范围内出现频率最高的 1% 的值,即最靠近min的那些值,大约会占到parameter% 的抽样次数。parameter必须严格大于 0。 @@ -1942,7 +1934,7 @@ f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / (2.0 * PHI(parameter) - 1) - 则minmax(包含边界)之间的值i被抽中的概率为:f(i + 0.5) - f(i - 0.5)。直观地说,parameter越大,越靠近区间中间的值被抽到的频率越高,而越靠近minmax边界的值被抽到的频率越低。大约 67% 的值会落在区间中部1.0 / parameter这一段内,也就是均值两侧各0.5 / parameter的范围内;约 95% 的值会落在区间中部2.0 / parameter这一段内,也就是均值两侧各1.0 / parameter的范围内。例如,如果parameter为 4.0,则 67% 的值会落在区间中间四分之一(1.0 / 4.0)内,也就是从3.0 / 8.05.0 / 8.0;95% 的值会落在区间中间一半(2.0 / 4.0)内,也就是第二和第三四分位。允许的最小parameter值为 2.0。 + 则minmax(包含边界)之间的值i被抽中的概率为:f(i + 0.5) - f(i - 0.5)。直观地说,parameter越大,越靠近区间中间的值被抽到的频率越高,而越靠近minmax边界的值被抽到的频率越低。大约 67% 的值会落在区间中部1.0 / parameter这一段内,也就是均值两侧各占区间长度0.5 / parameter的范围内;约 95% 的值会落在区间中部2.0 / parameter这一段内,也就是均值两侧各占区间长度1.0 / parameter的范围内。例如,如果parameter为 4.0,则 67% 的值会落在区间中间四分之一(1.0 / 4.0)内,也就是从3.0 / 8.05.0 / 8.0;95% 的值会落在区间中间一半(2.0 / 4.0)内,也就是第二和第三四分位。允许的最小parameter值为 2.0。 @@ -1974,12 +1966,12 @@ f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / - 哈希函数hashhash_murmur2hash_fnv1a都接受一个输入值和一个可选的种子参数。 - 如果没有提供种子,则会使用:default_seed的值;除非通过命令行选项覆盖,否则该值会被随机初始化。 + Hash 函数hashhash_murmur2hash_fnv1a都接受一个输入值和一个可选的种子参数。 + 如果没有提供种子,则会使用:default_seed的值;除非通过命令行-D选项覆盖,否则该值会被随机初始化。 - permute接受一个输入值、一个大小参数以及一个可选的种子参数。它会生成范围[0, size)内整数的伪随机排列,并返回输入值在该排列中的索引。如果未指定种子,则默认使用:default_seed。与哈希函数不同,permute保证输出值中不会出现冲突或空洞。区间之外的输入值会按size取模解释。如果size不是正数,该函数会报错。permute可用于打散诸如random_zipfianrandom_exponential这类非均匀随机函数的分布,使那些更常抽到的值不再具有显而易见的相关性。例如,下面的pgbench脚本模拟了社交媒体和博客平台中一种可能的真实工作负载,其中少数账户会产生过量负载: + permute接受一个输入值、一个大小参数以及一个可选的种子参数。它会生成范围[0, size)内整数的伪随机置换,并返回输入值在该置换中的索引。所选置换由种子参数决定;如果未指定种子,则默认使用:default_seed。与 hash 函数不同,permute保证输出值中不会出现冲突或空洞。区间之外的输入值会按size取模解释。如果size不是正数,该函数会报错。permute可用于打散诸如random_zipfianrandom_exponential这类非均匀随机函数的分布,使那些更常抽到的值不再具有显而易见的相关性。例如,下面的pgbench脚本模拟了社交媒体和博客平台中一种可能的真实工作负载,其中少数账户会产生过量负载: \set size 1000000 @@ -2036,7 +2028,7 @@ END; - 每行日志文件描述一个事务。 + 日志文件的每一行描述一个事务。 它包含以下以空格分隔的字段: @@ -2355,7 +2347,7 @@ END; - 下面是使用该选项生成的示例输出: + 下面是使用这些选项生成的示例输出: pgbench --aggregate-interval=10 --time=20 --client=10 --log --rate=1000 --latency-limit=10 --failures-detailed --max-tries=10 test @@ -2436,7 +2428,7 @@ statement latencies in milliseconds and failures: 使用可串行化默认事务隔离级别的默认脚本的另一个输出示例 - (PGOPTIONS='-c default_transaction_isolation=serializable' pgbench ...): + (PGOPTIONS='-c default_transaction_isolation=serializable' pgbench ...): starting vacuum...end. transaction type: <builtin: TPC-B (sort of)> @@ -2479,7 +2471,7 @@ statement latencies in milliseconds, failures and retries: - + 失败和串行化/死锁重试 @@ -2514,12 +2506,12 @@ statement latencies in milliseconds, failures and retries: - 线程在管理其客户端时发生的错误(例如,客户端无法开始连接数据库服务器,或客户端连接数据库服务器所用的套接字已经失效)。在这种情况下,该线程的所有客户端都会停止,而其他线程继续工作;但是,如果指定了,则所有线程都会立即停止。 + 线程在管理其客户端时发生的错误(例如,客户端无法开始连接数据库服务器,或客户端连接数据库服务器所用的套接字已经失效)。在这种情况下,该线程的所有客户端都会停止,而其他线程继续工作。 - 直接客户端错误。在发生内部pgbench错误(理论上不应发生)或指定了时,它们会导致pgbench立即退出并显示相应错误消息。否则,最坏情况下只会中止失败的客户端,而其他客户端继续运行(但某些客户端错误会在不中止客户端的情况下处理并单独报告,见下文)。本节后续默认讨论的都是直接客户端错误,而不是内部pgbench错误。 + 直接客户端错误。只有在发生内部pgbench错误(理论上不应发生)时,它们才会导致pgbench立即退出并显示相应错误消息。否则,最坏情况下只会中止失败的客户端,而其他客户端继续运行(但某些客户端错误会在不中止客户端的情况下处理并单独报告,见下文)。本节后续默认讨论的都是直接客户端错误,而不是内部pgbench错误。 @@ -2537,7 +2529,7 @@ statement latencies in milliseconds, failures and retries: - 不指定选项时,事务在发生串行化或死锁错误后永远不会重试,因为其默认值为 1。可以使用无限次尝试(--max-tries=0)并配合选项,仅限制重试的最长时间。也可以使用选项,在无限次尝试的情况下限制基准测试持续时间。 + 不指定选项时,事务在发生串行化或死锁错误后永远不会重试,因为其默认值为 1。可以使用无限次尝试(--max-tries=0)并配合选项,仅限制尝试的最长总时间。也可以使用选项,在无限次尝试的情况下限制基准测试持续时间。 @@ -2558,20 +2550,11 @@ statement latencies in milliseconds, failures and retries: - 如果希望在逐事务日志、聚合日志以及主报告和逐脚本报告中按基本类型对失败进行分组,请使用选项。如果还希望按类型区分所有错误和失败(即不会重试的错误),包括超出了哪一种重试限制,以及串行化/死锁失败超出了多少,请使用选项。 + 如果希望在逐事务日志、聚合日志以及主报告和逐脚本报告中按基本类型对失败进行分组,请使用选项。如果还希望按类型区分所有错误和失败(不再重试的错误),包括超出了哪一种重试限制,以及串行化/死锁失败超出了多少,请使用选项。 - - 表访问方法 - - 可以为 pgbench 表指定表访问方法。环境变量PGOPTIONS用于指定通过命令行传递给 PostgreSQL 的数据库配置选项。例如,可以用如下方式为 pgbench 创建的表指定一个名为wuzza的假想默认表访问方法: - -PGOPTIONS='-c default_table_access_method=wuzza' - - - @@ -2590,7 +2573,7 @@ PGOPTIONS='-c default_table_access_method=wuzza' - 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和空闲空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 + 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和无效空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 diff --git a/zh/15/ref/psql-ref.sgml b/zh/15/ref/psql-ref.sgml index 18d7884c..254e2c72 100644 --- a/zh/15/ref/psql-ref.sgml +++ b/zh/15/ref/psql-ref.sgml @@ -47,7 +47,7 @@ PostgreSQL documentation - 把所有非空输入行按照它们被读入的形式打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 + 在读入时将所有非空输入行打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 all @@ -58,7 +58,7 @@ PostgreSQL documentation - 切换到非对齐输出模式(默认输出模式是对齐的)。这等效于\pset format unaligned。 + 切换到非对齐输出模式(默认输出模式是aligned)。这等效于\pset format unaligned @@ -78,10 +78,10 @@ PostgreSQL documentation - 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,直到它处理完序列中所有的选项之后终止。 + 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,而是在按顺序处理完所有选项后终止。 - command必须是一个服务器完全可解析的命令字符串(即不包含psql相关的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: + command必须是一个服务器完全可解析的命令字符串(即不包含psql专有的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: psql -c '\x' -c 'SELECT * FROM foo;' @@ -172,7 +172,7 @@ EOF - 使用separator作为非对齐输出的域分隔符。这等效于\pset fieldsep或者\f。 + 使用separator作为非对齐输出的字段分隔符。这等效于\pset fieldsep或者\f @@ -246,7 +246,7 @@ EOF - 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。 + 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展名。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。 @@ -266,7 +266,7 @@ EOF - 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息以及多种输出。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon。 + 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息和各种提示信息。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon @@ -286,7 +286,7 @@ EOF - 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户一个可以取消执行的选项。使用这个选项可以调试脚本。 + 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户,并允许取消执行。使用这个选项可以调试脚本。 @@ -296,7 +296,7 @@ EOF - 运行在单行模式中,其中新行会终止一个 SQL 命令,就像分号的作用一样。 + 运行在单行模式中,其中换行符会终止一个 SQL 命令,就像分号的作用一样。 @@ -322,7 +322,7 @@ EOF - 指定要替换HTML table标签的选项。详见\pset tableattr。 + 指定要放在HTML table标签内的选项。详见\pset tableattr @@ -343,7 +343,7 @@ EOF - 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要重置一个变量,去掉等号就行。要把一个变量置为空值,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 + 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要取消变量的设置,去掉等号就行。要把一个变量设为空字符串,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 @@ -405,7 +405,7 @@ EOF - 不读取启动文件(要么是系统范围的psqlrc文件,要么是用户的~/.psqlrc文件)。 + 不读取启动文件(既不读取系统范围的psqlrc文件,也不读取用户的~/.psqlrc文件)。 @@ -415,7 +415,7 @@ EOF - 设置非对齐输出的域分隔符为零字节。这等效于\pset fieldsep_zero。 + 设置非对齐输出的字段分隔符为零字节。这等效于\pset fieldsep_zero @@ -425,7 +425,7 @@ EOF - 设置非对齐输出的记录分隔符为零字节。例如,这对与xargs -0配合有关。这等效于\pset recordsep_zero。 + 设置非对齐输出的记录分隔符为零字节。例如,这有助于与xargs -0配合使用。这等效于\pset recordsep_zero @@ -438,7 +438,7 @@ EOF 这个选项只能与一个或多个和/或选项结合使用。 它会导致psql在第一个这样的选项之前发出一个BEGIN命令, 并在最后一个选项之后发出一个COMMIT命令,从而将所有命令包装成一个单独的事务。 - 如果任何命令失败且变量ON_ERROR_STOP被设置,那么会发送一个ROLLBACK命令。 + 如果任何命令失败且变量ON_ERROR_STOP被设置,则会改为发送一个ROLLBACK命令。 这确保要么所有命令都成功完成,要么不应用任何更改。 @@ -486,10 +486,9 @@ EOF 分别指定这些参数。如果遇到一个不属于任何选项的参数, 它将被解释为数据库名(如果数据库名已经给出,则解释为数据库用户名)。 并非所有这些选项都是必需的;它们都有有用的默认值。如果省略主机名, - psql 在 Unix 上将通过 Unix 域套接字连接到本地主机上的服务器, - 在 Windows 上则通过 TCP/IP 连接到 localhost。默认端口号在编译时确定。 + psql 将通过 Unix 域套接字连接到本地主机上的服务器,而在没有 Unix 域套接字的机器上则通过 TCP/IP 连接到 localhost。默认端口号在编译时确定。 由于数据库服务器使用相同的默认值,因此在大多数情况下不必指定端口。 - 默认数据库用户名是你的操作系统用户名。数据库用户名确定后,它也会被用作默认数据库名。 + 默认用户名是你的操作系统用户名,默认数据库名也是如此。 请注意,你不能随意以任意数据库用户名连接到任意数据库。数据库管理员应当已经告知你拥有的访问权限。 @@ -550,7 +549,7 @@ testdb=> 元命令 - 你输入到psql中的任何以未加引用的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 + 你输入到psql中的任何以未加引号的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 @@ -567,7 +566,7 @@ testdb=> - 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉尾随换行)会替换反引号中的文本。在反引号包围的文本内部,不会发生特殊引用或其他处理,只有一种例外:如果出现:variable_name,且variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会被适当地引用成单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于回车和换行字符在所有平台上都无法安全引用,当变量值中出现这类字符时,:'variable_name'这种形式会打印错误消息,并且不会替换变量值。 + 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉末尾的换行符)会替换反引号中的文本。在反引号包围的文本内部,不会进行特殊的引号处理或其他处理,但出现:variable_name时,如果variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会适当地加上引号,使其成为单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于无法保证在所有平台上都能对回车和换行字符安全地加引号,当变量值中出现这类字符时,:'variable_name'形式会打印错误消息,并且不会替换变量值。 @@ -579,8 +578,8 @@ testdb=> - 很多元命令作用在当前查询缓冲区上。这就是一个缓冲区而已,它保存任何已经被键入但是还没有发送到服务器执行的SQL命令文本。这将包括之前输入的行以及在该元命令同一行上出现在前面的任何文本。 - + 许多元命令作用于当前查询缓冲区。这只是一个保存已输入但尚未发送到服务器执行的 SQL 命令文本的缓冲区。其中既包括先前输入的行,也包括同一行上位于元命令之前的文本。 + @@ -591,7 +590,7 @@ testdb=> \a - 如果当前表格输出格式是不对齐,则切换为对齐;否则切换为不对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset。 + 如果当前表格输出格式是非对齐,则切换为对齐;否则切换为非对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset @@ -602,7 +601,7 @@ testdb=> \c\connect [ -reuse-previous=on|off ] [ dbname [ username ] [ host ] [ port ] | conninfo ] - 建立到PostgreSQL服务器的新连接。可以使用位置语法(数据库名称、用户、主机和端口中的一个或多个)指定要使用的连接参数,也可以使用详细说明在中的conninfo连接字符串。如果没有给出参数,则使用与之前相同的参数建立新连接。 + 建立到PostgreSQL服务器的新连接。可以使用位置语法(数据库名称、用户、主机和端口中的一个或多个)指定要使用的连接参数,也可以使用conninfo连接字符串,详见。如果没有给出参数,则使用与之前相同的参数建立新连接。 @@ -618,7 +617,7 @@ testdb=> 默认情况下,参数在位置语法中被重用,但在给定conninfo字符串时不会被重用。 传递-reuse-previous=on-reuse-previous=off作为第一个参数将覆盖该默认设置。 如果参数被重用,则任何未明确指定为位置参数或在conninfo字符串中的参数将从现有连接的参数中获取。 - 一个例外是,如果使用位置语法将host设置更改为其先前值,则现有连接参数中存在的任何hostaddr设置将被删除。 + 一个例外是,如果使用位置语法更改host设置,使其不同于先前的值,则现有连接参数中存在的任何hostaddr设置将被删除。 此外,仅当用户、主机和端口设置未更改时,才会重用现有连接使用的任何密码。 当命令既不指定也不重用特定参数时,将使用libpq的默认值。 @@ -640,7 +639,7 @@ testdb=> => \c mydb myuser host.dom 6432 => \c service=foo => \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable" -=> \c -reuse-previous=on sslmode=require -- changes only sslmode +=> \c -reuse-previous=on sslmode=require -- 仅更改 sslmode => \c postgresql://tom@localhost/mydb?application_name=myapp @@ -650,11 +649,8 @@ testdb=> \C [ title ] - 设置作为查询结果打印的任何表格的标题,或取消任何这样的标题。此命令等效于 - \pset title title。(此命令的名称源自caption, - 因为它以前仅用于设置HTML表格中的标题。) - + 设置作为查询结果打印的表的标题,或取消此类标题。该命令等价于\pset title title。(此命令的名称源自caption,因为它过去只用于设置HTML表的标题。) + @@ -662,14 +658,11 @@ testdb=> \cd [ directory ] - 将当前工作目录更改为 - directory。如果没有参数,则切换到当前用户的主目录。关于如何确定主目录,请参见 。 - + 将当前工作目录更改为directory。如果没有参数,则切换到当前用户的主目录。 + - - 要打印当前工作目录,请使用\! pwd。 - + 要打印当前工作目录,请使用\! pwd @@ -678,14 +671,7 @@ testdb=> \conninfo - - 输出当前数据库连接的信息;如果正在使用 SSL,也包括与 SSL 相关的信息。 - - - 请注意,Client User 字段显示的是连接建立时的用户,而 - Superuser 字段表示当前用户(在当前执行上下文中)是否具有超级用户权限。这两个用户通常相同,但也可能不同,例如当前用户曾通过 - SET ROLE 命令被更改。 - + 输出当前数据库连接的信息。 @@ -734,9 +720,7 @@ testdb=> - 这些操作不如以文件或程序作为数据源或目标的 SQL - COPY 命令高效,因为所有数据都必须通过客户端/服务器连接传输。对于大量数据,使用 SQL - 命令可能更合适。 + 这些操作不如以文件或程序作为数据源或目标的SQL COPY命令高效,因为所有数据都必须通过客户端/服务器连接传输。对于大量数据,使用SQL命令可能更合适。另外,由于采用这种数据转送方式,CSV模式下的\copy ... from会错误地把单独占据一行的\.数据值当作输入结束标记。 @@ -762,46 +746,24 @@ testdb=> ] ] ] ] - 执行当前查询缓冲区(类似于\g)并在交叉表格中显示结果。 - 查询必须返回至少三列。 - 由colV标识的输出列成为垂直标题, - 由colH标识的输出列成为水平标题。 - colD标识要在网格中显示的输出列。 - sortcolH标识水平标题的可选排序列。 - + 执行当前查询缓冲区(与\g类似),并以交叉表网格显示结果。查询必须返回至少三列。由colV标识的输出列成为纵向表头,由colH标识的输出列成为横向表头。colD标识要在网格中显示的输出列。sortcolH标识横向表头的可选排序列。 + - 每个列规范可以是列号(从1开始)或列名。列名遵循通常的SQL大小写折叠和引用规则。如果省略, - colV被视为第1列, - colH被视为第2列。 - colH必须与 - colV不同。 - 如果未指定colD,则查询结果中必须恰好有三列, - 并且既不是colV也不是 - colH的列被视为 - colD。 - + 每个列指定都可以是列号(从 1 开始)或列名。通常的 SQL 大小写折叠和加引号规则适用于列名。如果省略,colV取第 1 列,colH取第 2 列。colH必须不同于colV。如果未指定colD,查询结果必须恰好有三列,既不是colV也不是colH的那一列被用作colD。 + - 垂直标题显示为最左侧的列,包含在列colV中找到的值, - 与查询结果中的顺序相同,但删除了重复项。 - + 纵向表头显示为最左列,包含colV列中的值,其顺序与查询结果中相同,但会移除重复值。 + - 水平标题作为第一行显示,包含在列colH中找到的值,去除重复项。 - 默认情况下,这些值按照查询结果中的顺序显示。但是,如果给定可选的sortcolH参数, - 它标识一个列,其值必须是整数,colH中的值将按照相应的 - sortcolH值排序后显示在水平标题中。 - + 横向表头显示为第一行,包含colH列中的值,并移除重复值。默认情况下,它们按查询结果中的相同顺序显示。但如果给出了可选的sortcolH参数,它所标识的列的值必须是整数,而colH中的值会按照对应的sortcolH值排序后显示在横向表头中。 + - 在交叉表格中,对于每个colH列的非重复值x, - 和每个colV列的非重复值y, - 位于交点(x,y)的单元格包含查询结果行中colD列的值, - 其中colH列的值为x, - colV列的值为y。 - 如果没有这样的行,则单元格为空。如果有多个这样的行,则报告错误。 - + 在交叉表网格中,对于colH中的每个不同值xcolV中的每个不同值y,交点(x,y)处的单元格包含查询结果中colD列的值,该结果行的colH值为xcolV值为y。如果没有这样的行,单元格为空。如果存在多条这样的行,则报错。 + @@ -823,11 +785,7 @@ testdb=> - 命令形式\d+与前者相同,只是会显示更多信息:显示与表列相关的任何注释, - 表中的OID的存在,如果关系是视图,则显示视图定义,非默认的 - 复制标识设置以及 - 如果关系具有访问方法,则显示 - 访问方法名称。 + 命令形式\d+与前者相同,但会显示更多信息:表列关联的注释、表是否包含 OID、当关系为视图时的视图定义、非默认的复制标识设置,以及当关系具有访问方法时的访问方法名称。 @@ -902,9 +860,7 @@ testdb=> - - 列出与操作符族关联的操作符(参见 )。如果指定了 access-method-pattern,则只列出与名称匹配该模式的访问方法所关联的操作符族成员。如果指定了 operator-family-pattern,则只列出名称与该模式匹配的操作符族成员。如果在命令名后追加 +,则每个操作符都会连同其排序操作符族(如果它是排序操作符)以及其底层函数是否防漏一起列出。 - + 列出与操作符族关联的操作符(见)。如果指定了access-method-pattern,则只列出关联访问方法的名称匹配该模式的操作符族成员。如果指定了operator-family-pattern,则只列出名称匹配该模式的操作符族成员。如果在命令名后附加+,还会列出每个操作符的排序操作符族(如果它是一个排序操作符)。 @@ -957,9 +913,7 @@ testdb=> \dC[+] [ pattern ] - - 列出类型转换。如果指定了 pattern,则只列出其源类型或目标类型与模式匹配的类型转换。如果在命令名后追加 +,则会显示每个类型转换的附加信息,包括其底层函数是否防漏,以及该类型转换的描述。 - + 列出类型转换。如果指定了pattern,则只列出源类型或目标类型匹配该模式的类型转换。如果在命令名后附加+,还会列出每个对象关联的描述。 @@ -970,7 +924,7 @@ testdb=> 显示constraintoperator classoperator familyrule和 - trigger类型对象的描述。所有其他注释可以通过相应的反斜杠命令查看这些对象类型。 + trigger类型对象的描述。其他注释可通过对应对象类型的反斜线命令查看。 \dd 显示与 @@ -995,7 +949,7 @@ testdb=> - \ddp[ pattern ] + \ddp [ pattern ] 列出默认访问权限设置。对于每个默认权限设置已偏离内置默认值的角色(以及适用时的模式),都会显示一条记录。如果指定了 pattern,则只列出角色名或模式名与模式匹配的记录。 @@ -1030,10 +984,7 @@ testdb=> \des[+] [ pattern ] - - 列出外部服务器(助记符:external - servers)。如果指定了 pattern,则只列出名称与模式匹配的服务器。如果在命令名后追加 +,则会显示每个服务器的完整描述,包括服务器的访问权限、类型、版本、选项和描述。 - + 列出外部服务器(助记词:external servers)。如果指定了pattern,则只列出名称匹配该模式的服务器。如果使用\des+形式,则显示每个服务器的完整说明,包括服务器的访问权限、类型、版本、选项和描述。 @@ -1041,9 +992,7 @@ testdb=> \det[+] [ pattern ] - - 列出外部表(助记符:external tables)。如果指定了 pattern,则只列出表名或模式名与模式匹配的条目。如果在命令名后追加 +,则还会显示通用选项以及外部表描述。 - + 列出外部表(助记词:external tables)。如果指定了pattern,则只列出表名或模式名匹配该模式的条目。如果使用\det+形式,还会显示通用选项和外部表描述。 @@ -1051,15 +1000,10 @@ testdb=> \deu[+] [ pattern ] - - 列出用户映射(助记符:external - users)。如果指定了 pattern,则只列出用户名与模式匹配的映射。如果在命令名后追加 +,则会显示每个映射的附加信息。 - + 列出用户映射(助记词:external users)。如果指定了pattern,则只列出用户名匹配该模式的映射。如果使用\deu+形式,还会显示每个映射的附加信息。 - - \deu+可能还会显示远程用户的用户名和密码,因此应注意不要泄露它们。 - + \deu+还可能显示远程用户的用户名和密码,因此应注意不要泄露它们。 @@ -1068,10 +1012,7 @@ testdb=> \dew[+] [ pattern ] - - 列出外部数据包装器(助记符:external - wrappers)。如果指定了 pattern,则只列出名称与模式匹配的外部数据包装器。如果在命令名后追加 +,则还会显示外部数据包装器的访问权限、选项和描述。 - + 列出外部数据包装器(助记词:external wrappers)。如果指定了pattern,则只列出名称匹配该模式的外部数据包装器。如果使用\dew+形式,还会显示外部数据包装器的访问权限、选项和描述。 @@ -1082,8 +1023,8 @@ testdb=> 列出函数,以及它们的结果数据类型、参数数据类型和函数类型,函数类型分为 agg(聚合)、normalproceduretriggerwindow。要只显示特定类型的函数,请在命令后添加相应的字母 anptw。如果指定了 pattern,则只显示名称与模式匹配的函数。任何附加参数都是类型名模式,分别与函数第一、第二等参数的类型名匹配。(匹配到的函数可以比你指定的参数更多;若要防止这种情况,可将破折号 - 写成最后一个 arg_pattern。)默认情况下,只显示用户创建的对象;提供模式或 S - 修饰符可包括系统对象。如果在命令名后追加 +,则会显示每个函数的附加信息,包括易变性、并行安全性、所有者、安全分类、是否防漏、访问权限、语言、内部名称(仅适用于 C 和 internal 函数)以及描述。特定函数的源代码可通过 \sf 查看。 + class="parameter">pattern,则只显示名称与模式匹配的函数。任何附加参数都是类型名模式,分别与函数第一、第二等参数的类型名匹配。(匹配到的函数可以比你指定的参数更多;若要防止这种情况,可将连字符 - 写成最后一个 arg_pattern。)默认情况下,只显示用户创建的对象;提供模式或 S + 修饰符可包括系统对象。如果使用 \df+ 形式,则会显示每个函数的附加信息,包括易变性、并行安全性、所有者、安全分类、访问权限、语言、源代码和描述。 @@ -1092,36 +1033,28 @@ testdb=> \dF[+] [ pattern ] - - 列出文本搜索配置。如果指定了 pattern,则只显示名称与模式匹配的配置。如果在命令名后追加 +,则会显示每个配置的完整描述,包括底层文本搜索解析器以及每种记号类型对应的词典列表。 - + 列出全文检索配置。如果指定了pattern,则只显示名称匹配该模式的配置。如果使用\dF+形式,则显示每个配置的完整说明,包括底层全文检索解析器和每种解析器词元类型的词典列表。 \dFd[+] [ pattern ] - - 列出文本搜索词典。如果指定了 pattern,则只显示名称与模式匹配的词典。如果在命令名后追加 +,则会显示每个所选词典的附加信息,包括底层文本搜索模板和选项值。 - + 列出全文检索词典。如果指定了pattern,则只显示名称匹配该模式的词典。如果使用\dFd+形式,还会显示每个选中词典的附加信息,包括底层全文检索模板和选项值。 \dFp[+] [ pattern ] - - 列出文本搜索解析器。如果指定了 pattern,则只显示名称与模式匹配的解析器。如果在命令名后追加 +,则会显示每个解析器的完整描述,包括底层函数和已识别的记号类型列表。 - + 列出全文检索解析器。如果指定了pattern,则只显示名称匹配该模式的解析器。如果使用\dFp+形式,则显示每个解析器的完整说明,包括底层函数和可识别的词元类型列表。 \dFt[+] [ pattern ] - - 列出文本搜索模板。如果指定了 pattern,则只显示名称与模式匹配的模板。如果在命令名后追加 +,则会显示每个模板的附加信息,包括底层函数名。 - + 列出全文检索模板。如果指定了pattern,则只显示名称匹配该模式的模板。如果使用\dFt+形式,还会显示每个模板的附加信息,包括底层函数名。 @@ -1129,11 +1062,7 @@ testdb=> \dg[S+] [ pattern ] - - 列出数据库角色。(由于 usersgroups 的概念已经统一为 roles,此命令现在等同于 - \du。)默认情况下,只显示用户创建的角色;提供 - S 修饰符可包括系统角色。如果指定了 pattern,则只列出名称与模式匹配的角色。如果在命令名后追加 +,则会显示每个角色的附加信息;目前这会增加每个角色的注释。 - + 列出数据库角色。(由于用户的概念已经统一为角色,此命令现在等价于\du。)默认只显示用户创建的角色;提供S修饰符可包含系统角色。如果指定了pattern,则只列出名称匹配该模式的角色。如果使用\dg+形式,还会显示每个角色的附加信息;目前会增加每个角色的注释。 @@ -1174,7 +1103,7 @@ testdb=> \do[S+] [ pattern [ arg_pattern [ arg_pattern ] ] ] - 列出操作符及其操作数类型和结果类型。如果指定了 pattern,则只列出名称与模式匹配的操作符。如果指定了一个 arg_pattern,则只列出其右参数类型名称与该模式匹配的前缀操作符。如果指定了两个 arg_pattern,则只列出参数类型名称与这些模式匹配的二元操作符。(对于一元操作符未使用的参数,也可以写成 -。)默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 +,则会显示每个操作符的附加信息,包括底层函数名以及它是否防漏。 + 列出操作符及其操作数类型和结果类型。如果指定了 pattern,则只列出名称与模式匹配的操作符。如果指定了一个 arg_pattern,则只列出其右参数类型名称与该模式匹配的前缀操作符。如果指定了两个 arg_pattern,则只列出参数类型名称与这些模式匹配的二元操作符。(对于一元操作符未使用的参数,也可以写成 -。)默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 +,则会显示每个操作符的附加信息,目前仅包括底层函数名。 @@ -1194,7 +1123,7 @@ testdb=> \dp [ pattern ] - 列出表、视图和序列及其相关访问权限。如果指定了 pattern,则只列出名称与模式匹配的表、视图和序列。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 + 列出表、视图和序列及其相关访问权限。如果指定了 pattern,则只列出名称与模式匹配的表、视图和序列。 GRANT和 @@ -1209,34 +1138,20 @@ testdb=> \dP[itn+] [ pattern ] - - 列出分区关系。 - 如果pattern被指定, - 则只列出名称与模式匹配的条目。 - 修饰符t(表)和i(索引) - 可以附加到命令,过滤要列出的关系类型。默认情况下,列出分区表和索引。 - + 列出分区关系。如果指定了pattern,则只列出名称匹配该模式的条目。可以在命令后附加修饰符t(表)和i(索引),筛选要列出的关系类型。默认会列出分区表和分区索引。 - - 如果使用修饰符nnested), - 或指定了模式,则将包括非根分区关系,并显示一个列,显示每个 - 分区关系的父级。 - + 如果使用了修饰符nnested),或指定了模式,则会包含非根分区关系,并显示一列,列出每个分区关系的父关系。 - -如果在命令名后追加 +,则还会显示每个关系分区大小的总和以及关系描述。如果 n+ 组合使用,则会显示两个大小:一个包括直接附加的叶分区的总大小,另一个显示包括间接附加子分区在内的所有分区总大小。 - + 如果在命令名后附加+,还会显示每个关系的各个分区的大小之和,以及该关系的描述。如果将n+结合使用,则显示两个大小:一个是直接附加的叶子分区的总大小,另一个是所有分区的总大小,包括间接附加的子分区。 - \drds[ role-pattern [ database-pattern ] ] + \drds [ role-pattern [ database-pattern ] ] - 列出已定义的配置设置。这些设置可以是特定于角色、特定于数据库,或者两者兼有。role-pattern 和 - database-pattern 分别用于选择要列出的特定角色和数据库。如果省略,或者指定了 - *,则会列出所有设置,包括那些未指定角色或数据库的设置。 + 列出已定义的配置设置。这些设置可以特定于角色、特定于数据库,或同时特定于两者。role-patterndatabase-pattern分别用于选择要列出的角色和数据库。省略某个模式参数或将其指定为*时,不会按该参数筛选,还会分别包含不特定于角色或不特定于数据库的设置。 ALTER ROLE和 @@ -1271,7 +1186,7 @@ testdb=> \dT[S+] [ pattern ] - 列出数据类型。如果指定了 pattern,则只列出名称与模式匹配的类型。如果在命令名后追加 +,则每个类型都会连同其内部名称和大小一起列出;对于 enum 类型,还会显示其允许值以及相关权限。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 + 列出数据类型。如果指定了 pattern,则只列出名称与模式匹配的类型。如果在命令名后追加 +,则每个类型都会连同其内部名称、大小以及相关权限一起列出;对于 enum 类型,还会显示其允许值。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 @@ -1279,25 +1194,19 @@ testdb=> \du[S+] [ pattern ] - - 列出数据库角色。(由于 usersgroups 的概念已经统一为 roles,此命令现在等同于 - \dg。)默认情况下,只显示用户创建的角色;提供 - S 修饰符可包括系统角色。如果指定了 pattern,则只列出名称与模式匹配的角色。如果在命令名后追加 +,则会显示每个角色的附加信息;目前这会增加每个角色的注释。 - + 列出数据库角色。(由于用户的概念已经统一为角色,此命令现在等价于\dg。)默认只显示用户创建的角色;提供S修饰符可包含系统角色。如果指定了pattern,则只列出名称匹配该模式的角色。如果使用\du+形式,还会显示每个角色的附加信息;目前会增加每个角色的注释。 \dx[+] [ pattern ] - - 列出已安装的扩展。如果指定了 pattern,则只列出名称与模式匹配的扩展。如果在命令名后追加 +,则会列出属于每个匹配扩展的全部对象。 - + 列出已安装的扩展。如果指定了pattern,则只列出名称匹配该模式的扩展。如果使用\dx+形式,则列出属于每个匹配扩展的所有对象。 - \dX[ pattern ] + \dX [ pattern ] 列出扩展统计信息。如果指定了 pattern,则只列出名称与模式匹配的扩展统计信息。 @@ -1320,7 +1229,7 @@ testdb=> - \e\edit filename 行号 + \e\edit filename line_number @@ -1332,7 +1241,7 @@ testdb=> 如果编辑文件或上一个查询后在未修改文件的情况下退出编辑器,则查询缓冲区将被清除。 否则,查询缓冲区的新内容将根据psql的正常规则重新解析, - 将整个缓冲区视为单行。任何完整的查询将立即执行;也就是说,如果查询缓冲区包含或以分号结尾, + 将整个缓冲区视为单行。任何完整的查询将立即执行;也就是说,如果查询缓冲区包含分号或以分号结尾, 则执行并从查询缓冲区中删除到该点的所有内容。查询缓冲区中剩余的内容将重新显示。 输入分号或\g发送它,或输入\r通过清除查询缓冲区来取消。 @@ -1344,7 +1253,7 @@ testdb=> 如果指定了行号,psql将光标定位在文件或查询缓冲区的指定行上。 - 请注意,如果给出一个全是数字的参数, + 请注意,如果只给出一个全是数字的参数, psql会假定它是一个行号,而不是文件名。 @@ -1359,14 +1268,10 @@ testdb=> \echo text [ ... ] - - 将求值后的参数打印到标准输出,用空格分隔,并在末尾加上换行符。这对于在脚本输出中穿插信息很有用。例如: - + 将求值后的参数打印到标准输出,用空格分隔,并在末尾加上换行符。这对于在脚本输出中穿插信息很有用。例如: => \echo `date` Tue Oct 26 21:40:57 CEST 1999 - - 如果第一个参数是未引用的-n,则不会写入尾随的换行符(也不会写入第一个参数)。 - +如果第一个参数是未加引号的-n,则不会写入尾随的换行符(也不会写入第一个参数)。 @@ -1474,7 +1379,7 @@ Tue Oct 26 21:40:57 CEST 1999 - 设置未对齐查询输出的字段分隔符。默认值是竖线(|)。 + 设置非对齐查询输出的字段分隔符。默认值是竖线(|)。 它等同于\pset fieldsep @@ -1485,25 +1390,17 @@ Tue Oct 26 21:40:57 CEST 1999 \g [ (option=value [...]) ] [ filename ] \g [ (option=value [...]) ] [ |command ] - - 将当前查询缓冲区发送到服务器以执行。 - - - 如果在\g后面出现括号,则括号中包围着一个空格分隔的option=value格式选项子句的列表,这些选项子句的解释方式与\psetoptionvalue命令相同,但仅在此查询的持续时间内生效。在此列表中,不允许在=符号周围有空格,但在选项子句之间需要空格。 - 如果省略了=value,则命名的option将以与\psetoption没有显式value时相同的方式更改。 - - - 如果提供了一个filename|command参数, - 查询的输出将被写入到指定的文件或通过给定的shell命令进行传输,而不是像通常那样显示出来。只有在查询成功返回零个或多个元组时,文件或命令才会被写入,而不是在查询失败或是非数据返回的SQL命令时。 + 将当前查询缓冲区发送给服务器执行。 + 如果在\g后面出现括号,则括号中是用空格分隔的option=value格式选项子句列表。这些子句的解释方式与\pset + option + value命令相同,但仅在此查询执行期间生效。在此列表中,=符号周围不允许有空格,但选项子句之间必须有空格。如果=value被省略,则指定的option会按以下命令的方式更改:\pset option,其中不显式指定value + 如果给出了filename|command参数,查询输出就会写入指定文件,或通过管道传给指定的 shell 命令,而不是照常显示。只有当查询成功返回零个或多个元组时,才会向文件或命令写入;如果查询失败,或执行的是不返回数据的 SQL 命令,则不会写入。 如果当前查询缓冲区为空,则最近发送的查询将被重新执行。除此之外,没有任何参数的\g基本上等同于一个分号。 带有参数的\g提供了一个一次性替代\o命令的选择,并且还允许一次性调整通常由\pset设置的输出格式选项。 - - 当最后一个参数以|开头时,整行剩余部分被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分将被直接传递给shell。 - + 当最后一个参数以|开头时,该行剩余的全部内容都会被视为要执行的command,其中既不进行变量插值,也不进行反引号扩展。该行剩余部分会直接按字面传给 shell。 @@ -1512,14 +1409,9 @@ Tue Oct 26 21:40:57 CEST 1999 \gdesc - - 显示当前查询缓冲区结果的描述(即列名和数据类型)。 - 查询不会实际执行;但是,如果包含某种语法错误,该错误将以正常方式报告。 - + 显示当前查询缓冲区中查询结果的描述(即列名和数据类型)。查询并不会实际执行;不过,如果其中存在语法错误,会按通常的方式报告。 - - 如果当前查询缓冲区为空,则描述最近发送的查询。 - + 如果当前查询缓冲区为空,则改为描述最近发送的查询。 @@ -1574,37 +1466,23 @@ CREATE INDEX \gset [ prefix ] - - 将当前查询缓冲区发送到服务器,并将查询的输出存储到psql变量中 - (参见下面的)。 - 要执行的查询必须返回一行。该行的每一列都存储在一个单独的变量中,变量名与列名相同。例如: - + 将当前查询缓冲区发送给服务器,并将查询输出存入 psql 变量(参见下面的)。要执行的查询必须恰好返回一行。该行的每一列分别存入一个变量,变量名与列名相同。例如: => SELECT 'hello' AS var1, 10 AS var2 -> \gset => \echo :var1 :var2 hello 10 - - 如果指定了一个prefix, - 该字符串将被添加到查询的列名前,以创建要使用的变量名: - + 如果指定了prefix,则会将该字符串加到查询的列名前面,以构成要使用的变量名: => SELECT 'hello' AS var1, 10 AS var2 -> \gset result_ => \echo :result_var1 :result_var2 hello 10 - - 如果列的结果为NULL,则相应的变量将被取消设置,而不是被设置。 - - - 如果查询失败或者没有返回一行结果, - 则不会改变任何变量。 - - - 如果当前查询缓冲区为空,则重新执行最近发送的查询。 - + 如果某一列的结果为 NULL,则取消设置对应的变量,而不是设置它。 + 如果查询失败或没有恰好返回一行,则不会更改任何变量。 + 如果当前查询缓冲区为空,则改为重新执行最近发送的查询。 @@ -1627,7 +1505,7 @@ hello 10 给出指定SQL命令的语法帮助。如果未指定command, 则psql将列出所有可用语法帮助的命令。如果command是星号 - (*),则显示所有SQL命令的语法帮助。 + (*),则显示所有SQL命令的语法帮助。 @@ -1648,9 +1526,7 @@ hello 10 \H\html - 打开HTML查询输出格式。如果HTML格式已经打开, - 则切换回默认的对齐文本格式。此命令用于兼容性和便利性,但请参阅\pset - 有关设置其他输出选项。 + 打开HTML查询输出格式。如果HTML格式已经打开,则切换回默认的对齐文本格式。此命令是为兼容性和便利性而保留的;设置其他输出选项的方法见\pset @@ -1662,13 +1538,10 @@ hello 10 - 从文件filename中读取输入,并将其执行为 - 好像它是在键盘上键入的一样。 + 从文件filename中读取输入,并像在键盘上输入一样执行它。 - 如果filename- - (连字符),那么标准输入将被读取,直到EOF指示或\q元命令。 - 这可用于将交互式输入与文件输入交错使用。请注意,仅当在最外层级别处于活动状态时,Readline行为才会被使用。 + 如果filename-(连字符),则从标准输入读取,直到遇到 EOF 指示或\q元命令。这可用于将交互式输入与文件输入交错使用。请注意,只有在最外层启用了 Readline,此处才会使用 Readline 功能。 @@ -1688,42 +1561,26 @@ hello 10 这组命令实现了可嵌套的条件块。条件块必须以\if开始,并以\endif结束。 在两者之间可以有任意数量的\elif子句,后面可以选择性地跟着一个\else子句。 - 在形成条件块的命令之间通常会出现普通查询和其他类型的反斜杠命令。 + 在形成条件块的命令之间通常会出现普通查询和其他类型的反斜线命令。 - \if\elif命令读取它们的参数,并将其作为布尔表达式进行评估。 - 如果表达式为true,则处理将继续进行;否则,直到达到匹配的\elif、 - \else\endif为止,将跳过行。一旦\if或 - \elif测试成功,同一块中后续\elif命令的参数不会被评估,而是被视为false。 - 在\else之后的行只有在没有早期匹配的\if\elif成功时才会被处理。 + \if\elif命令读取其参数,并将其作为布尔表达式求值。如果表达式的值为true,则正常继续处理;否则,跳过后续行,直到遇到匹配的\elif\else\endif。一旦\if\elif测试成功,同一块中后续\elif命令的参数就不再求值,而是被视为假。只有前面所有匹配的\if\elif测试都未成功时,才会处理\else后面的行。 - expression参数 - 是\if\elif命令的参数, - 受变量插值和反引号扩展的影响,就像任何其他反斜杠命令参数一样。 - 之后,它被评估为一个开/关选项变量的值。因此,有效值是以下任何一个不 - 含糊的不区分大小写匹配之一: - true, false, 1, - 0, on, off, - yes, no。例如, - t, TtR - 都将被视为true。 + 与其他反斜线命令的参数一样,\if\elif命令的expression参数会经过变量插值和反引号扩展。随后,按开/关选项变量值的规则对结果求值。因此,有效值是以下值的不区分大小写且无歧义的匹配:truefalse10onoffyesno。例如,tTtR都会被视为true - 不正确评估为真或假的表达式将生成警告,并被视为假。 + 不能正确求值为真或假的表达式会产生警告,并被视为假。 - 被跳过的行会被正常解析以识别查询和反斜杠命令,但查询不会发送到服务器, - 而且除了条件命令(\if\elif, - \else\endif)之外的反斜杠命令会被忽略。 + 被跳过的行会被正常解析以识别查询和反斜线命令,但查询不会发送到服务器, + 而且除了条件命令(\if\elif、 + \else\endif)之外的反斜线命令会被忽略。 仅检查跳过行中条件命令的有效嵌套。跳过行中的变量引用不会被展开, 也不会执行反引号扩展。 - 所有给定条件块的反斜杠命令必须出现在同一个源文件中。如果在主输入文件或一个 - \include的文件上达到文件结束之前,所有本地 - \if块都没有关闭, - 那么psql将会引发错误。 + 同一个条件块的所有反斜线命令必须出现在同一个源文件中。如果主输入文件或通过\include引入的文件到达 EOF 时,仍有本地\if块未关闭,psql就会报错。 下面是一个示例: @@ -1757,17 +1614,13 @@ SELECT \ir\include_relative filename - - \ir命令类似于\i,但是解析相对文件名的方式不同。 - 在交互模式下执行时,这两个命令的行为是相同的。然而,在脚本中调用时, - \ir会将文件名解释为相对于脚本所在目录,而不是当前工作目录。 - + \ir命令与\i相似,但解析相对文件名的方式不同。在交互模式下执行时,这两个命令的行为相同。不过,在脚本中调用时,\ir会相对于脚本所在的目录来解释文件名,而不是相对于当前工作目录。 - \l[+] or \list[+] [ pattern ] + \l[+]\list[+] [ pattern ] 列出服务器中的数据库,并显示其名称、所有者、字符集编码和访问权限。如果指定了 pattern,则只列出名称与模式匹配的数据库。如果在命令名后追加 +,则还会显示数据库大小、默认表空间和描述。当前用户对其拥有 CONNECT 权限的数据库可以显示大小信息;如果当前用户是超级用户或具有 pg_read_all_stats 角色的权限,也可以显示大小信息。 @@ -1784,7 +1637,7 @@ SELECT 从数据库中读取具有OIDloid的大对象,并将其写入filename。请注意,这与服务器函数 - lo_export略有不同,后者使用数据库服务器运行的用户权限, + lo_export略有不同,后者使用运行数据库服务器的用户的权限, 并在服务器的文件系统上操作。 @@ -1800,14 +1653,10 @@ SELECT \lo_import filename [ comment ] - - 将文件存储到一个PostgreSQL大对象中。可选地,它将给定的注释与对象关联起来。例如: - + 将文件存储到一个PostgreSQL大对象中。可选地,它将给定的注释与对象关联起来。例如: foo=> \lo_import '/home/peter/pictures/photo.xcf' 'a picture of me' lo_import 152801 - - 响应表明大对象收到了对象ID 152801,这个ID可以用来在将来访问新创建的大对象。为了可读性起见,建议始终将一个可读的注释与每个对象关联起来。OID和注释都可以用\lo_list命令查看。 - +响应表明大对象获得了对象 ID 152801,这个 ID 可以用来在将来访问新创建的大对象。为便于阅读,建议始终为每个对象关联一条便于人阅读的注释。查看 OID 和注释时,可以使用\lo_list命令。 请注意,此命令与服务器端的lo_import略有不同,因为它作为本地用户在本地文件系统上操作,而不是服务器的用户和文件系统。 @@ -1830,7 +1679,7 @@ lo_import 152801 - 从数据库中删除具有OIDloid的大对象。 + 从数据库中删除OIDloid的大对象。 @@ -1846,19 +1695,12 @@ lo_import 152801 \o\out [ filename ] \o\out [ |command ] - - 安排将未来的查询结果保存到文件filename, - 或将未来的结果传输到shell命令command。 - 如果未指定参数,则查询输出重置为标准输出。 - + 将后续查询结果保存到文件filename,或通过管道传给 shell 命令command。如果没有指定参数,查询输出将恢复为标准输出。 - - 如果参数以|开头,则整个剩余部分的行被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分的行会被直接传递给shell。 - + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 - 查询结果包括从数据库服务器获取的所有表、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 + 查询结果包括从数据库服务器获取的所有表格、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 @@ -1912,30 +1754,15 @@ lo_import 152801 \pset [ option [ value ] ] - - 这个命令设置影响查询结果表输出的选项。 - option - 指示要设置哪个选项。根据所选选项,value的语义会有所不同。 - 对于某些选项,省略value会导致该选项被切换或取消设置,具体描述在特定选项下。 - 如果没有提到这样的行为,那么省略value只会显示当前设置。 - + 这个命令设置影响查询结果表输出的选项。option指定要设置哪个选项。value的含义取决于所选的选项。对于某些选项,省略value会切换或取消设置该选项,具体见各选项的说明。如果没有提及这类行为,那么省略value只会显示当前设置。 - - \pset不带任何参数时,显示所有打印选项的当前状态。 - + 不带任何参数的\pset会显示所有打印选项的当前状态。 - - 可调整打印选项有: - + 可调整的打印选项如下: border - - value必须是一个数字。一般来说,数字越高,表格的边框和线条就越多, - 但具体细节取决于特定格式。在HTML格式中,这将直接转换为border=...属性。 - 在大多数其他格式中,只有值0(无边框)、1(内部分隔线)和2(表框)有意义,值大于2将被视为border = 2。 - latexlatex-longtable格式还允许值为3,以在数据行之间添加分隔线。 - + value必须是数字。一般来说,数字越大,表格的边框和分隔线就越多,但细节取决于具体格式。在HTML格式中,它会直接转换为border=...属性。在大多数其他格式中,只有值 0(无边框)、1(内部分隔线)和 2(表格外框)有意义,大于 2 的值会与border = 2作相同处理。latexlatex-longtable格式还允许使用值 3,以在数据行之间添加分隔线。 @@ -1948,7 +1775,7 @@ lo_import 152801 零(默认值)会导致目标宽度由环境变量COLUMNS控制,或者如果未设置 COLUMNS则由检测到的屏幕宽度控制。 另外,如果columns为零,则wrapped格式仅影响屏幕输出。 - 如果columns为非零,则文件和管道输出也会被包装到该宽度。 + 如果columns为非零,则文件和管道输出也会按该宽度折行。 @@ -1967,63 +1794,35 @@ lo_import 152801 expanded(或x - - 如果指定了value,它必须是onoff, - 这将启用或禁用扩展模式,或者是auto。 - 如果省略了value,则命令在开启和关闭设置之间切换。 - 启用扩展模式时,查询结果以两列显示,左侧是列名,右侧是数据。 - 如果数据在正常的水平模式下无法完全显示在屏幕上,则此模式很有用。 - 在自动设置中,当查询输出具有多列且宽度超过屏幕时,将使用扩展模式;否则,将使用常规模式。 - 自动设置仅在对齐和换行格式中有效。在其他格式中,它始终表现为扩展模式已关闭。 - + 如果指定了value,它必须是onoff(分别启用或禁用扩展模式),或者是auto。如果省略value,该命令会在开启和关闭设置之间切换。启用扩展模式时,查询结果以两列显示,左侧为列名,右侧为数据。如果数据在通常的横向模式下无法适应屏幕,这种模式就很有用。在自动设置下,当查询输出包含多列且宽度超过屏幕时,会使用扩展模式;否则使用常规模式。自动设置只在对齐和折行格式中有效。在其他格式中,它的行为始终与关闭扩展模式相同。 fieldsep - - 指定在未对齐的输出格式中使用的字段分隔符。这样,可以创建例如制表符分隔的输出, - 其他程序可能更喜欢。要将制表符设置为字段分隔符,请键入 - \pset fieldsep '\t'。默认字段分隔符是 - '|'(一根竖线)。 - + 指定非对齐输出格式使用的字段分隔符。这样可以创建例如制表符分隔的输出,这可能更符合其他程序的需要。要将制表符设置为字段分隔符,请输入\pset fieldsep '\t'。默认字段分隔符是'|'(竖线)。 fieldsep_zero - - 将未对齐输出格式中使用的字段分隔符设置为零字节。 - + 将非对齐输出格式使用的字段分隔符设置为零字节。 footer - - 如果指定了value, - 它必须是onoff, - 这将启用或禁用表格页脚的显示 - ((n 行)计数)。 - 如果省略了value, - 命令将切换页脚的显示或隐藏。 - + 如果指定了value,它必须是onoff,分别启用或禁用表格页脚((n rows)计数)的显示。如果省略value,该命令会切换页脚显示的开关状态。 format - - 设置输出格式为alignedasciidoc、 - csvhtmllatex、 - latex-longtabletroff-ms、 - unalignedwrapped。 - 允许使用唯一缩写。 - + 设置输出格式为alignedasciidoccsvhtmllatexlatex-longtabletroff-msunalignedwrapped。允许使用唯一缩写。 aligned格式是标准的、适合人阅读且排版整齐的文本输出;这是默认格式。 @@ -2036,12 +1835,12 @@ lo_import 152801 按逗号分隔的列值输出,并应用 RFC 4180 - 中描述的引用规则。 + 中描述的加引号规则。 此输出与服务器的CSV格式的 COPY命令兼容。 - 生成包含列名的标题行,除非 + 生成包含列名的表头行,除非 tuples_only参数设置为 - on。不打印标题和页脚。 + on。不打印表格标题和页脚。 每行以系统相关的行结束字符结束, 对于类Unix系统通常是单个换行符(\n), 对于Microsoft Windows则是回车和换行序列 @@ -2049,17 +1848,14 @@ lo_import 152801 可以用\pset csv_fieldsep选择逗号以外的字段分隔字符。 - wrapped格式类似于aligned,但会将宽数据值跨行包装,以使输出适合目标列宽。 - 目标宽度由columns选项下描述的方式确定。请注意,psql不会尝试包装列标题; - 因此,如果列标题所需的总宽度超过目标宽度,则wrapped格式的行为与aligned相同。 - + wrapped格式与aligned相似,但会将较宽的数据值折成多行,使输出适应目标列宽。目标宽度的确定方式见columns选项的说明。请注意,psql不会尝试对列标题折行;因此,如果列标题所需的总宽度超过目标宽度,wrapped格式的行为就与aligned相同。 - asciidochtml, - latexlatex-longtable,和 + asciidochtml、 + latexlatex-longtabletroff-ms格式生成的表格旨在包含在使用相应标记语言的文档中。 它们不是完整的文档!这在HTML中可能不是必需的,但在 - LaTeX中,则必须有一个完整的文档包装器。 + LaTeX中,则必须有一个完整文档的外层结构。 latex格式使用LaTeXtabular 环境。 latex-longtable格式需要LaTeX @@ -2079,25 +1875,19 @@ lo_import 152801 - ascii样式使用普通的ASCII字符。数据中的换行使用右边边缘的+符号显示。 - 当wrapped格式将数据从一行换到下一行而没有换行符时,在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 + ascii样式使用普通的ASCII字符。数据中的换行符以右边缘的+符号表示。当wrapped格式在没有换行符的位置把数据折到下一行时,会在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 - old-ascii样式使用普通的ASCII字符,使用在PostgreSQL 8.4及更早版本中使用的格式样式。 - 数据中的换行符使用:符号代替左侧列分隔符显示。 - 当数据从一行换行到下一行而没有换行符时,使用;符号代替左侧列分隔符。 + old-ascii样式使用普通的ASCII字符,采用PostgreSQL 8.4 及更早版本的格式样式。数据中的换行符以替代左侧列分隔符的:符号表示。当数据在没有换行符的位置折到下一行时,则用;符号替代左侧列分隔符。 - unicode样式使用Unicode绘图字符。数据中的换行使用右边距中的回车符号显示。 - 当数据从一行换行到下一行而没有换行符时,第一行的右边距显示省略号符号, - 接着在下一行的左边距再次显示省略号符号。 + unicode样式使用 Unicode 框线绘制字符。数据中的换行符以右边缘的回车符号表示。当数据在没有换行符的位置折到下一行时,会在第一行的右边缘显示省略号符号,并在下一行的左边缘再次显示。 - 当border设置大于零时,linestyle选项还确定了用哪些字符绘制边框线。 - 普通的ASCII字符在任何地方都有效,但在识别Unicode字符的显示器上看起来更好。 + 当border设置大于零时,linestyle选项还决定用哪些字符绘制边框线。普通的ASCII字符在任何环境中都可用,但在支持 Unicode 的显示设备上,Unicode 字符更美观。 @@ -2105,24 +1895,14 @@ lo_import 152801 null - - 设置要打印在空值位置的字符串。默认情况下是不打印任何内容,这很容易被误解为空字符串。 - 例如,一个人可能更喜欢\pset null '(null)'。 - + 设置用于代替空值打印的字符串。默认不打印任何内容,这很容易被误认为空字符串。例如,你可能更喜欢使用\pset null '(null)' numericlocale - - 如果指定了value, - 它必须是onoff, - 这将启用或禁用显示一个特定于区域设置的字符, - 用于将小数点左侧的数字分组。如果省略了 - value, - 命令在常规和特定于区域设置的数字输出之间切换。 - + 如果指定了value,它必须是onoff,分别启用或禁用使用区域设置特定的字符来分隔小数点左侧的数字组。如果省略value,该命令会在常规数字输出和区域设置特定的数字输出之间切换。 @@ -2130,17 +1910,11 @@ lo_import 152801 pager - 控制查询和psql帮助输出时使用分页程序的方式。 - 当pager选项为off时,不使用分页程序。 - 当pager选项为on时,在适当的情况下使用分页程序,即当输出到终端且不适合在屏幕上显示时。 - pager选项也可以设置为always,这会导致分页程序用于所有终端输出,无论是否适合在屏幕上显示。 - \pset pager 不带value时,会在开启和关闭分页器之间切换。 + 控制查询和psql帮助输出是否使用分页器程序。当pager选项为off时,不使用分页器程序。当pager选项为on时,会在适当时使用分页器,即输出目标为终端且内容无法在屏幕上完整显示时。pager选项也可以设为always,这样所有终端输出都会使用分页器,无论内容是否能在屏幕上完整显示。不带value\pset pager会切换分页器的使用状态。 - 如果环境变量PSQL_PAGERPAGER被设置, - 输出将被分页传输到指定的程序。否则,将使用一个平台相关的默认程序 - (例如more)。 + 如果设置了环境变量PSQL_PAGERPAGER,需要分页的输出会通过管道传给指定程序。否则,使用与平台有关的默认程序(如more)。 @@ -2155,130 +1929,70 @@ lo_import 152801 pager_min_lines - - 如果pager_min_lines设置为大于页面高度的数字, - 则除非至少有这么多行的输出要显示,否则不会调用分页程序。默认设置为0。 - + 如果将pager_min_lines设置为大于页面高度的数字,那么只有待显示的输出至少达到这么多行时,才会调用分页器程序。默认设置为 0。 recordsep - - 指定在未对齐的输出格式中使用的记录(行)分隔符。默认为换行符。 - + 指定非对齐输出格式使用的记录(行)分隔符。默认为换行符。 recordsep_zero - - 设置未对齐输出格式中使用的记录分隔符为零字节。 - + 将非对齐输出格式使用的记录分隔符设置为零字节。 tableattr(或T - - 在HTML格式中,这指定要放置在table标签内的属性。 - 这可能是cellpaddingbgcolor等。 - 请注意,这里通常不需要指定border,因为它已经由\pset border处理。 - 如果没有给出value,则取消表格属性。 - - - 在latex-longtable格式中,这控制了包含左对齐数据类型的每列的比例宽度。 - 它被指定为一个以空格分隔的值列表,例如,'0.2 0.2 0.6'。 - 未指定输出列使用最后指定的值。 - + HTML格式中,这指定要放在table标签内的属性,例如cellpaddingbgcolor。请注意,你可能不需要在这里指定border,因为\pset border已经负责处理它。如果没有给出value,则取消设置表格属性。 + latex-longtable格式中,这控制每个包含左对齐数据类型的列的宽度比例。它以空白分隔的值列表指定,例如'0.2 0.2 0.6'。未指定的输出列使用最后指定的值。 - title(或者C + title(或C - - 设置后续打印的任何表的标题。这可以用来为输出提供说明性标签。 - 如果没有给出value,则标题将被取消设置。 - + 设置随后打印的所有表格的标题。这可以为输出提供描述性标签。如果没有给出value,则取消设置标题。 tuples_only(或t - - 如果指定了value,它必须是onoff, - 这将启用或禁用仅元组模式。如果省略了value, - 命令将在常规输出和仅元组输出之间切换。常规输出包括额外信息,如列标题、标题和各种页脚。 - 在仅元组模式下,只显示实际的表数据。 - + 如果指定了value,它必须是onoff,分别启用或禁用仅元组模式。如果省略value,该命令会在常规输出和仅元组输出之间切换。常规输出包含列标题、表格标题和各种页脚等附加信息。在仅元组模式下,只显示实际的表格数据。 unicode_border_linestyle - - 设置unicode线条样式的边框绘制样式为singledouble之一。 - + unicode线条样式的边框绘制样式设置为singledouble unicode_column_linestyle - - 设置unicode线条样式的列绘制样式为singledouble之一。 - + unicode线条样式的列分隔线绘制样式设置为singledouble unicode_header_linestyle - - 设置unicode线条样式的标题绘制样式为singledouble之一。 - - - - - - xheader_width - - - 将扩展输出的标题最大宽度设置为以下之一: - full(默认值)、 - columnpage 或 - 整数值。 - - - - full:扩展标题不截断,其宽度与最宽的输出行相同。 - - - - column:将标题行截断为第一列的宽度。 - - - - page:将标题行截断为终端宽度。 - - - - 整数值:指定标题行的确切最大宽度。 - + unicode线条样式的表头分隔线绘制样式设置为singledouble - - 这些不同格式的示例可以在下面的中看到。 - + 这些不同格式的外观示例可参见下面的 @@ -2295,10 +2009,7 @@ lo_import 152801 \q\quit - - 退出psql程序。 - 在脚本文件中,只有该脚本的执行被终止。 - + 退出psql程序。在脚本文件中,只会终止该脚本的执行。 @@ -2307,7 +2018,7 @@ lo_import 152801 \qecho text [ ... ] - 这个命令与\echo命令相同,只是输出将被写入查询输出通道,由\o设置。 + 这个命令与\echo相同,只是输出会写入由\o设置的查询输出通道。 @@ -2316,9 +2027,7 @@ lo_import 152801 \r\reset - - 重置(清除)查询缓冲区。 - + 重置(清空)查询缓冲区。 @@ -2405,14 +2114,9 @@ testdb=> \setenv LESS -imx4F 定义将打印到当前查询输出通道,由\o设置。 - - 目标函数可以仅通过名称指定,也可以通过名称和参数指定,例如foo(integer, text)。 - 如果有多个同名函数,则必须给出参数类型。 - + 目标函数可以只用名称指定,也可以同时给出名称和参数,例如foo(integer, text)。如果存在多个同名函数,就必须给出参数类型。 - - 如果在命令名称后添加+,则输出的行将被编号,函数体的第一行将被标记为第1行。 - + 如果在命令名后附加+,输出行会带上行号,函数体的第一行编号为 1。 与大多数其他元命令不同,整个行的剩余部分始终被视为\sf的参数, @@ -2427,8 +2131,7 @@ testdb=> \setenv LESS -imx4F - 这个命令获取并显示指定视图的定义,以CREATE OR REPLACE VIEW命令的形式。 - 定义将打印到当前查询输出通道,由\o设置。 + 这个命令获取指定视图的定义,并以CREATE OR REPLACE VIEW命令的形式显示。定义会打印到由\o设置的当前查询输出通道。 @@ -2447,10 +2150,7 @@ testdb=> \setenv LESS -imx4F \t - - 切换显示输出列名标题和行数页脚。此命令等效于\pset tuples_only, - 仅为方便起见提供。 - + 切换输出中的列名标题和行数页脚的显示状态。这个命令等价于\pset tuples_only,提供它是为了使用方便。 @@ -2458,10 +2158,7 @@ testdb=> \setenv LESS -imx4F \T table_options - - 指定在table标签中放置的属性,在HTML输出格式中。 - 该命令等效于\pset tableattr table_options。 - + 指定在HTML输出格式中放在table标签内的属性。这个命令等价于\pset tableattr table_options @@ -2469,10 +2166,7 @@ testdb=> \setenv LESS -imx4F \timing [ on | off ] - - 使用参数,打开或关闭显示每个SQL语句执行时间的功能。没有参数时,切换显示开关。 - 显示的时间单位为毫秒;超过1秒的时间间隔也以分钟:秒的格式显示,如有必要还会显示小时和天。 - + 带参数时,开启或关闭每条 SQL 语句执行耗时的显示。不带参数时,切换显示的开关状态。耗时以毫秒显示;超过 1 秒的时间间隔还会以分钟:秒的格式显示,必要时添加小时和天字段。 @@ -2499,15 +2193,9 @@ testdb=> \setenv LESS -imx4F \unset name - - 取消设置(删除)psql变量name。 - + 取消设置(删除)psql变量name - - 大多数控制psql行为的变量不能被取消设置;相反,\unset命令被解释为将它们设置为默认值。 - 请参见下面的。 - + 大多数控制psql行为的变量不能取消设置;对于这些变量,\unset命令会被解释为将其设置为默认值。参见下面的 @@ -2516,15 +2204,9 @@ testdb=> \setenv LESS -imx4F \w\write filename \w\write |command - - 将当前查询缓冲区写入文件filename,或者通过管道传给 shell 命令command。 - 如果当前查询缓冲区为空,则写入最近执行的查询。 - + 将当前查询缓冲区写入文件filename,或通过管道传递给 shell 命令command。如果当前查询缓冲区为空,则改为写入最近执行的查询。 - - 如果参数以|开头,则整个剩余部分的行被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分的行会被直接传递给shell。 - + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 @@ -2556,9 +2238,7 @@ testdb=> \setenv LESS -imx4F \x [ on | off | auto ] - - 设置或切换扩展表格格式模式。因此,它等同于\pset expanded。 - + 设置或切换扩展表格格式模式。它等价于\pset expanded @@ -2566,8 +2246,7 @@ testdb=> \setenv LESS -imx4F \z [ pattern ] - - 列出表、视图和序列及其相关访问权限。如果指定了 pattern,则只列出名称与模式匹配的表、视图和序列。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 + 列出表、视图和序列及其关联的访问权限。如果指定了pattern,则只列出名称匹配该模式的表、视图和序列。 这是\dp的别名(显示权限)。 @@ -2580,13 +2259,11 @@ testdb=> \setenv LESS -imx4F \! [ command ] - 不带参数时,转义到一个子shell;psql在子shell退出时恢复。 - 带参数时,执行shell命令command。 + 不带参数时,进入一个子 shell;子 shell 退出后,psql恢复运行。带参数时,执行 shell 命令command - 与大多数其他元命令不同,整个行的剩余部分始终被视为\!的参数, - 在参数中不执行变量插值或反引号扩展。行的其余部分被直接传递给shell。 + 与大多数其他元命令不同,该行剩余的全部内容始终被视为\!的参数,其中不会进行变量插值或反引号扩展。该行剩余内容会原样传给 shell。 @@ -2598,7 +2275,7 @@ testdb=> \setenv LESS -imx4F 显示帮助信息。可选的topic参数 (默认为commands)选择要解释的psql的哪个部分: - commands描述psql的反斜杠命令; + commands描述psql的反斜线命令; options描述可以传递给psql的命令行选项; 而variables显示关于psql配置变量的帮助。 @@ -2610,7 +2287,7 @@ testdb=> \setenv LESS -imx4F \; - 反斜杠分号不像前面的命令那样是一个元命令;相反,它只是在不进行进一步处理的情况下将一个分号添加到查询缓冲区中。 + 反斜线分号不像前面的命令那样是一个元命令;相反,它只是在不进行进一步处理的情况下将一个分号添加到查询缓冲区中。 @@ -2622,8 +2299,8 @@ select 1; select 2; select 3; select 1\; select 2\; select 3; - 在到达非反斜杠分号时将三个SQL命令发送到服务器的单个请求中。 - 服务器将执行此类请求作为单个事务,除非字符串中包含明确的BEGIN/COMMIT命令将其分成多个事务。(有关服务器如何处理多查询字符串的更多详细信息,请参见。) + 会在遇到前面没有反斜线的分号时,将这三个 SQL 命令作为单个请求发送到服务器。 + 服务器会将此类请求作为单个事务执行,除非字符串中包含显式的BEGIN/COMMIT命令将其分成多个事务。(有关服务器如何处理多查询字符串的更多详细信息,请参见。) @@ -2631,16 +2308,16 @@ select 1\; select 2\; select 3; - + 模式 - patterns + 模式 在 psql 和 pg_dump 中 - 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要把它写成两个相邻的双引号,这同样是符合 SQL 引用标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你不能只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 + 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要在双引号包围的文本内把它写成两个相邻的双引号,这同样是符合 SQL 加引号标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你可以只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 @@ -2652,21 +2329,15 @@ select 1\; select 2\; select 3; - 包含点(.)的关系模式被解释为模式名称后跟对象名称模式。例如, - \dt foo*.*bar*显示所有位于模式名以foo开头的模式中、且表名包含bar的表。当没有出现点时,模式仅匹配当前模式搜索路径中可见的对象。 - 再次,双引号内的点失去其特殊含义,被视为字面匹配。包含两个点(.)的关系模式 - 被解释为数据库名称后跟模式名称后跟对象名称模式。数据库名称部分不会被视为模式,必须匹配当前连接的数据库名称, - 否则将引发错误。 + 如果用于匹配关系名的模式包含一个点(.),则会被解释为模式名的匹配模式,后接对象名的匹配模式。例如,\dt foo*.*bar*会显示所有位于模式名以foo开头的模式中、且表名包含bar的表。如果没有点,则只匹配当前模式搜索路径中可见的对象。同样,双引号内的点会失去特殊含义,按字面匹配。如果用于匹配关系名的模式包含两个点(.),则会被解释为数据库名、模式名的匹配模式和对象名的匹配模式。数据库名部分不会被当作匹配模式,必须与当前连接的数据库名相同,否则会报错。 - 包含一个点(.)的模式被解释为数据库名称后跟模式的模式名称。例如, - \dn mydb.*foo*显示所有包含foo的模式。数据库名称部分不会被视为模式, - 必须匹配当前连接数据库的名称,否则将引发错误。 + 如果用于匹配模式名的模式包含一个点(.),则会被解释为数据库名,后接模式名的匹配模式。例如,\dn mydb.*foo*会显示名称中包含foo的所有模式。数据库名部分不会被当作匹配模式,必须与当前连接的数据库名相同,否则会报错。 - 高级用户可以使用字符类等正则表达式记法,如[0-9]可以匹配任意数字。所有的正则表达式特殊字符都按照所说的工作,以下字符除外:.会按照上面所说的作为一种分隔符,*会被翻译成正则表达式记号.*?会被翻译成.,而$则按字面意思匹配。根据需要,可以通过书写?(R+|)(R|)R?来分别模拟模式字符.R*R?$不需要作为一个正则表达式字符,因为模式必须匹配整个名称,而不是像正则表达式的常规用法那样解释(换句话说,$会被自动地追加到模式上)。如果不希望该模式的匹配位置被固定,可以在开头或者结尾写上*。注意在双引号内,所有的正则表达式特殊字符会失去其特殊含义并且按照其字面意思进行匹配。还有,在操作符名称模式中(即作为\do的参数),正则表达式特殊字符也按照字面意思进行匹配。 + 高级用户可以使用字符类等正则表达式记法,如[0-9]可以匹配任意数字。所有的正则表达式特殊字符都按照所说的工作,以下字符除外:.会按照上面所说的作为一种分隔符,*会被翻译成正则表达式记号.*?会被翻译成.,而$则按字面意思匹配。根据需要,可以用?模拟.,用(R+|)模拟R*,或用(R|)模拟R?$不需要作为一个正则表达式字符,因为模式必须匹配整个名称,而不是像正则表达式的常规用法那样解释(换句话说,$会被自动地追加到模式上)。如果不希望该模式的匹配位置被固定,可以在开头或者结尾写上*。注意在双引号内,所有的正则表达式特殊字符会失去其特殊含义并且按照其字面意思进行匹配。还有,在操作符名称模式中(即作为\do的参数),正则表达式特殊字符也按照字面意思进行匹配。 @@ -2674,7 +2345,7 @@ select 1\; select 2\; select 3; 高级特性 - + 变量 @@ -2695,7 +2366,7 @@ bar - 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要重置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 + 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要取消设置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 @@ -2709,7 +2380,7 @@ bar - 控制psql行为的变量通常不能被重置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse。 + 控制psql行为的变量通常不能被取消设置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse @@ -2727,7 +2398,7 @@ bar - 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被重置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交打开模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身即不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 + 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被取消设置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交关闭模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身既不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 @@ -2757,7 +2428,7 @@ bar DBNAME - 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -2766,7 +2437,7 @@ bar ECHO - 如果被设置为all,所有非空输入行会被按照读入它们的样子打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被重置或者设置为none(默认值)则不会显示任何查询。 + 如果被设置为all,所有非空输入行会在读入时打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被设置为none(默认值)则不会显示任何查询。 @@ -2784,7 +2455,7 @@ bar ENCODING - 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者重置。 + 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者取消设置。 @@ -2802,12 +2473,12 @@ bar FETCH_COUNT - 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每一组就会包括这么多个行。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 + 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每组包含的行数等于该整数值。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 - 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT个行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 + 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 @@ -2836,7 +2507,7 @@ bar HISTCONTROL - 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则匹配之前的历史行的行不会被放入。值ignoreboth组合了上述两种值。如果被重置或者被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 + 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则与上一条历史记录相同的行不会被放入。值ignoreboth组合了上述两种值。如果被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 @@ -2850,7 +2521,7 @@ bar HISTFILE - 该文件名将被用于存储历史列表。如果被重设,文件名将从PSQL_HISTORY环境变量中取得。如果该环境变量也没有被设置,则默认值是~/.psql_history,在Windows上是%APPDATA%\postgresql\psql_history。例如, + 该文件名将被用于存储历史列表。如果未设置该变量,文件名将从PSQL_HISTORY环境变量中取得。如果该环境变量也没有被设置,则默认值是~/.psql_history,在Windows上是%APPDATA%\postgresql\psql_history。例如, \set HISTFILE ~/.psql_history-:DBNAME @@ -2882,7 +2553,7 @@ bar HOST - 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -2891,7 +2562,7 @@ bar IGNOREEOF - 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须键入多个连续的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 + 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须连续键入与该数值相等数量的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 @@ -2905,8 +2576,8 @@ bar LASTOID - 最后被影响的 OID 的值,这可能会由INSERT或者\lo_import命令返回。这个变量只保证在下一个SQL命令被显示完之前有效。 - PostgreSQL 服务器从12版开始不再支持 OID 系统列,因此,在面向此类服务器时,跟随在INSERT后面的 LASTOID 将始终为0。 + 最后被影响的 OID 的值,这可能会由INSERT或者\lo_import命令返回。这个变量仅保证在下一个SQL命令的结果显示完之前有效。 + PostgreSQL 服务器从12版开始不再支持 OID 系统列,因此,在面向此类服务器时,执行INSERT后的 LASTOID 将始终为0。 @@ -2931,7 +2602,7 @@ bar - 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被重置或者设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 + 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 @@ -2952,7 +2623,7 @@ bar PORT - 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -2991,7 +2662,7 @@ bar SERVER_VERSION_NUM - 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者重设。 + 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者取消设置。 @@ -3013,7 +2684,7 @@ bar SHOW_CONTEXT - 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT域。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 + 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT字段。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 当VERBOSITY被设置为tersesqlstate时,这个设置无效(另见\errverbose,它可以用来得到刚遇到的错误的详细信息)。 @@ -3032,7 +2703,7 @@ bar SINGLESTEP - 设置这个变量为on等效于命令选项。 + 设置这个变量为on等效于命令行选项 @@ -3050,7 +2721,7 @@ bar USER - 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -3059,7 +2730,7 @@ bar VERBOSITY - 这个变量可以被设置为值defaultverboseterse或者sqlstate来控制错误报告的详细程度(另见\errverbose,在想得到之前的错误的详细版本时使用)。 + 这个变量可以被设置为值defaultverboseterse或者sqlstate来控制错误报告的详细程度(另见\errverbose,在想得到刚遇到的错误的详细信息时使用)。 @@ -3070,7 +2741,7 @@ bar VERSION_NUM - 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或重设。 + 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或取消设置。 @@ -3080,11 +2751,11 @@ bar - - <acronym>SQL</acronym> 中插入变量 + + <acronym>SQL</acronym> 插值 - psql变量的一个关键特性是可以把它们替换(插入)到常规SQL语句中,也可以把它们作为元命令的参数。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。插入一个值而不加引号的语法是在变量名前面加上一个冒号(:)。例如, + psql变量的一个关键特性是可以把它们替换(插值)到常规SQL语句中,也可以把它们替换到元命令的参数中。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。不加引号地插值一个值的语法是在变量名前面加上一个冒号(:)。例如, testdb=> \set foo 'my_table' testdb=> SELECT * FROM :foo; @@ -3093,7 +2764,7 @@ testdb=> SELECT * FROM :foo; - 当一个值被用作 SQL 文本或者标识符时,最安全的是把它加上引用。要引用一个变量的值作为 SQL 文本,可以把变量名称放在单引号中并且在引号前面写一个冒号。要引用作为 SQL 标识符,则可以把变量名称放在双引号中并且在引号前面写一个冒号。这种结构可以正确地处理变量值中嵌入的引号和其他特殊字符。之前的示例用这种方法写会更安全: + 当一个值要用作 SQL 字面量或标识符时,最安全的做法是为它加上引号。要将变量值作为 SQL 字面量加引号,应写一个冒号,后面跟用单引号括起来的变量名。要将变量值作为 SQL 标识符加引号,则在冒号后面用双引号括起变量名。这些写法能正确处理变量值中嵌入的引号和其他特殊字符。前面的示例可用以下更安全的写法: testdb=> \set foo 'my_table' testdb=> SELECT * FROM :"foo"; @@ -3101,11 +2772,11 @@ testdb=> SELECT * FROM :"foo"; - 在被引用的SQL文本和标识符中将不会执行变量插入。因此,一个诸如':foo'的结构不会从一个变量的值产生一个被引用的文本(即便能够也会不安全,因为无法正确地处理嵌入在值中的引号)。 + 在加引号的SQL字面量和标识符内部,不会执行变量插值。因此,':foo'这样的写法不能根据变量值生成加引号的字面量(即使能够生效,也不安全,因为它无法正确处理变量值中嵌入的引号)。 - 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个被引用的字符串插入: + 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个加引号的字符串进行插值: testdb=> \set content `cat my_file.txt` testdb=> INSERT INTO my_table VALUES (:'content'); @@ -3114,7 +2785,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 因为冒号可以合法地出现在 SQL 命令中,一次明显的插入尝试(即:name:'name'或者:"name")不会被替换,除非所提及的变量就是当前被设置的。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 + 因为冒号可以合法地出现在 SQL 命令中,一次明显的插值尝试(即:name:'name'或者:"name")不会被替换,除非所指的变量当前已设置。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 @@ -3122,12 +2793,12 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 文本或者标识符的冒号引用语法是一种psql扩展。 + 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 字面量或者标识符的冒号加引号语法是一种psql扩展。 - + 提示符 @@ -3141,33 +2812,26 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %M - - 数据库服务器的完整主机名(带域名);如果连接通过 Unix 域套接字建立,则为 [local];如果 Unix 域套接字不在编译时默认位置,则为 [local:/dir/name]。 - + 数据库服务器的完整主机名(含域名);如果通过 Unix 域套接字连接,则为[local];如果 Unix 域套接字不在编译时指定的默认位置,则为[local:/dir/name] %m - - 数据库服务器的主机名,在第一个点处分截;如果连接通过 Unix 域套接字建立,则为 [local]。 - + 数据库服务器的主机名,在第一个点号处截断;如果通过 Unix 域套接字连接,则为[local] %> - 数据库服务器正在监听的端口号。 + 数据库服务器监听的端口号。 %n - - 数据库会话用户名。(由于 SET SESSION - AUTHORIZATION 命令的作用,该值在数据库会话期间可能会发生变化。) - + 数据库会话用户名。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) @@ -3186,11 +2850,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %# - - 如果会话用户是数据库超级用户,则输出 - #,否则输出 >。(由于 SET SESSION - AUTHORIZATION 命令的作用,该值的展开在数据库会话期间可能会发生变化。) - + 如果会话用户是数据库超级用户,则为#,否则为>。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) @@ -3206,7 +2866,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %R - 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 dollar-quoted 字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 + 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 美元引用字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 @@ -3233,7 +2893,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %digits - 带有所示八进制码的字符被替换。 + 替换为指定八进制代码对应的字符。 @@ -3335,14 +2995,14 @@ $endif - )命令行选项也可用于在单次运行psql时禁用 Readline。这会阻止制表补全、命令行历史的使用或记录,以及多行命令的编辑。当你需要复制粘贴包含 TAB 字符的文本时,它尤其有用。 + )命令行选项也可用于在单次运行psql时禁用 Readline。这会阻止TAB 补全、命令行历史的使用或记录,以及多行命令的编辑。当你需要复制粘贴包含 TAB 字符的文本时,它尤其有用。 - + 环境 @@ -3427,9 +3087,9 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 如果查询结果无法在屏幕上显示完整,它们将通过此命令进行传输。典型的值是moreless。 + 如果查询结果无法在屏幕上显示完整,它们会通过管道传给此命令。典型的值是moreless。 可以通过将PSQL_PAGERPAGER设置为空字符串,或通过调整\pset命令的与分页相关的选项来禁用分页器。 - 这些变量按照列出的顺序进行检查;首先设置的变量将被使用。 + 这些变量按照列出的顺序进行检查;使用按该顺序找到的第一个已设置的变量。 如果它们都没有设置,默认情况下在大多数平台上使用more,但在Cygwin上使用less @@ -3509,7 +3169,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' 在任何情况下,可以通过设置PSQLRC环境变量来覆盖此默认文件路径。 - 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加破折号和PostgreSQL的主要或次要版本标识符来使其与psql版本相关, + 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加连字符和PostgreSQL的大版本或小版本标识符来使其与psql版本相关, 例如~/.psqlrc-&majorversion;~/.psqlrc-&version;。 最具体版本匹配的文件将优先读取,而不是非特定版本的文件。 这些版本后缀是在确定文件路径后添加的,如上所述。 @@ -3537,14 +3197,14 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - psql最适合与相同或较旧主要版本的服务器配合使用。 - 如果服务器的版本比psql本身更新,反斜杠命令特别容易失败。 - 然而,\d系列的反斜杠命令应该可以在版本回溯到9.2的服务器上运行, + psql最适合与相同或较旧大版本的服务器配合使用。 + 如果服务器的版本比psql本身更新,反斜线命令特别容易失败。 + 然而,\d系列的反斜线命令应该可以在最低至 9.2 版本的服务器上运行, 但不一定适用于比psql本身更新的服务器。运行SQL命令和显示查询结果的一般功能 - 也应该可以在更新主要版本的服务器上运行,但不能保证在所有情况下都能实现。 + 也应该可以在更新大版本的服务器上运行,但不能保证在所有情况下都能实现。 - 如果你想用psql连接到多个具有不同主版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个主版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 + 如果你想用psql连接到多个具有不同大版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个大版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 @@ -3558,7 +3218,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空格。现在则要求一些空格。 + 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空白。现在则要求用空白分隔。 @@ -3731,9 +3391,7 @@ testdb=> \df int*pl * bigint - - 在适合的情况下,可以使用 \crosstabview 命令将查询结果显示为交叉表: - + 在适当的情况下,要以交叉表形式显示查询结果,可以使用\crosstabview命令: testdb=> SELECT first, second, first > 2 AS gt2 FROM my_table; first | second | gt2 -------+--------+----- @@ -3751,10 +3409,7 @@ testdb=> \crosstabview first second 3 | | | t | 4 | | | | t (4 rows) - - -第二个示例展示了一个乘法表,其中行按数字倒序排列,而列按独立的升序数字排列。 - +第二个示例显示一个乘法表,行按数值降序排列,列则独立地按数值升序排列。 testdb=> SELECT t1.first as "A", t2.first+100 AS "B", t1.first*(t2.first+100) as "AxB", testdb-> row_number() over(order by t2.first) AS ord testdb-> FROM my_table t1 CROSS JOIN my_table t2 ORDER BY 1 DESC diff --git a/zh/15/release-15.sgml b/zh/15/release-15.sgml index e96f60da..4fa15e63 100644 --- a/zh/15/release-15.sgml +++ b/zh/15/release-15.sgml @@ -1528,7 +1528,7 @@ Branch: REL_14_STABLE [dda622edc] 2026-08-02 16:49:18 -0400 --> - 修复为文本搜索词典创建缓存条目的过程中发生内存不足后导致的崩溃 + 修复为文本检索词典创建缓存条目的过程中发生内存不足后导致的崩溃 (Tom Lane) § @@ -3403,7 +3403,7 @@ Branch: REL_14_STABLE [6cae0c2bd] 2026-04-22 11:09:21 -0400 损坏或恶意的词缀文件可能使服务器崩溃。 - 这不被视为安全问题,因为文本搜索配置文件被假定为可信, + 这不被视为安全问题,因为文本检索配置文件被假定为可信, 但仍然值得修复。 @@ -16478,7 +16478,7 @@ Branch: REL_12_STABLE [3b4580f5c] 2023-06-24 17:18:08 -0400 Branch: REL_11_STABLE [c7f33a197] 2023-06-24 17:18:08 -0400 --> - 防止使用非常复杂的文本搜索模式时的栈溢出崩溃 + 防止使用非常复杂的文本检索模式时的栈溢出崩溃 (Tom Lane) § @@ -17414,7 +17414,7 @@ Branch: master [f413941f4] 2023-03-17 12:08:46 -0700 Branch: REL_15_STABLE [8b87e9291] 2023-03-17 12:07:47 -0700 --> - 调整全文搜索相关的字符分类逻辑,以正确检测当前区域设置是否为 + 调整文本检索相关的字符分类逻辑,以正确检测当前区域设置是否为 C(Jeff Davis) § @@ -19449,7 +19449,7 @@ Branch: REL_12_STABLE [1aed4c4fd] 2022-11-21 17:07:07 -0500 Branch: REL_11_STABLE [c0eed8891] 2022-11-21 17:07:07 -0500 --> - 确保在执行短语匹配时可以取消全文搜索查询的执行(Tom Lane) + 确保在执行短语匹配时可以取消全文检索查询的执行(Tom Lane) § diff --git a/zh/15/rowtypes.sgml b/zh/15/rowtypes.sgml index c4b09f72..dd68ebdf 100644 --- a/zh/15/rowtypes.sgml +++ b/zh/15/rowtypes.sgml @@ -75,7 +75,7 @@ CREATE TABLE inventory_item ( - 构造组合值 + 构造复合值 复合类型 @@ -83,7 +83,7 @@ CREATE TABLE inventory_item ( - 要把组合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,组合常量的一般格式如下: + 要把复合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,复合常量的一般格式如下: '( val1 , val2 , ... )' @@ -103,11 +103,11 @@ CREATE TABLE inventory_item ( - (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。必要时可能需要显式指定类型。) + (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。可能需要显式指定类型,以指明应将该常量转换为哪种类型。) - ROW表达式语法也可以用于构造组合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: + ROW表达式语法也可以用于构造复合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: ROW('fuzzy dice', 42, 1.99) ROW('', 42, NULL) @@ -126,7 +126,7 @@ ROW('', 42, NULL) 访问复合类型 - 要访问组合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: + 要访问复合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: SELECT item.name FROM on_hand WHERE item.price > 9.99; @@ -148,7 +148,7 @@ SELECT (on_hand.item).name FROM on_hand WHERE (on_hand.item).price > 9.99; - 无论何时从组合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回组合值的函数结果中只选取一个字段,你需要这样写: + 无论何时从复合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回复合值的函数结果中只选取一个字段,你需要这样写: SELECT (my_func(...)).field FROM ... @@ -164,10 +164,10 @@ SELECT (my_func(...)).field FROM ... - 修改组合值 + 修改复合类型 - 下面是一些插入和更新组合列时正确语法的示例。先看插入或更新整个列值的情况: + 下面是一些插入和更新复合列时正确语法的示例。先看插入或更新整个列值的情况: INSERT INTO mytab (complex_col) VALUES((1.1,2.2)); @@ -179,7 +179,7 @@ UPDATE mytab SET complex_col = ROW(1.1,2.2) WHERE ...; - 我们也可以更新组合列中的单个子字段: + 我们也可以更新复合列中的单个子字段: UPDATE mytab SET complex_col.r = (complex_col).r + 1 WHERE ...; @@ -208,11 +208,11 @@ INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2); - 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的组合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: + 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的复合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: SELECT c FROM inventory_item c; - 这个查询会产生一个单独的组合值列,因此我们可能得到如下输出: + 这个查询会产生一个单独的复合值列,因此我们可能得到如下输出: c ------------------------ @@ -223,7 +223,7 @@ SELECT c FROM inventory_item c; - 普通的限定列名语法table_name.column_name可以理解为对该表当前行的组合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) + 普通的限定列名语法table_name.column_name可以理解为对该表当前行的复合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) @@ -256,19 +256,19 @@ SELECT (myfunc(x)).a, (myfunc(x)).b, (myfunc(x)).c FROM some_table; SELECT m.* FROM some_table, LATERAL myfunc(x) AS m; - 把该函数放在LATERAL FROM项中,可以防止它对每一行被调用多于一次。m.*仍会展开为m.a, m.b, m.c,但现在这些变量只是对该FROM项输出的引用。(这里的LATERAL关键字其实是可选的,不过我们把它写出来,是为了明确该函数会从some_table中取得x。) + 把该函数放在LATERAL FROM项中,可以避免它在每行上被调用多次。m.*仍会展开为m.a, m.b, m.c,但现在这些变量只是对该FROM项输出的引用。(这里的LATERAL关键字其实是可选的,不过我们把它写出来,是为了明确该函数会从some_table中取得x。) - 当composite_value.*出现在SELECT输出列表、INSERT/UPDATE/DELETE/MERGE中的RETURNING列表、VALUES子句或行构造器的顶层时,就会产生这种列展开行为。在所有其他上下文中(包括嵌套在上述结构之内时),给组合值附加.*不会改变其值,因为它表示所有列,因此结果仍然是同一个组合值。例如,如果somefunc()接受一个组合值参数,这些查询就是等价的: + 当composite_value.*出现在SELECT输出列表、INSERT/UPDATE/DELETE中的RETURNING列表、VALUES子句或行构造器的顶层时,就会产生这种列展开行为。在所有其他上下文中(包括嵌套在上述结构之内时),给复合值附加.*不会改变其值,因为它表示所有列,因此结果仍然是同一个复合值。例如,如果somefunc()接受一个复合值参数,这些查询就是等价的: SELECT somefunc(c.*) FROM inventory_item c; SELECT somefunc(c) FROM inventory_item c; - 在这两种情况下,inventory_item的当前行都会作为单个组合值参数传递给该函数。尽管.*在这种场合并不起作用,使用它仍是一种良好风格,因为它能明确表明这里想要的是组合值。特别是,解析器会把c.*中的c视为表名或别名,而不是列名,因此不会产生歧义;而没有.*时,就不清楚c究竟表示表名还是列名,而且如果存在名为c的列,实际上会优先按列名解释。 + 在这两种情况下,inventory_item的当前行都会作为单个复合值参数传递给该函数。尽管.*在这种场合并不起作用,使用它仍是一种良好风格,因为它能明确表明这里想要的是复合值。特别是,解析器会把c.*中的c视为表名或别名,而不是列名,因此不会产生歧义;而没有.*时,就不清楚c究竟表示表名还是列名,而且如果存在名为c的列,实际上会优先按列名解释。 @@ -278,7 +278,7 @@ SELECT * FROM inventory_item c ORDER BY c; SELECT * FROM inventory_item c ORDER BY c.*; SELECT * FROM inventory_item c ORDER BY ROW(c.*); - 所有这些ORDER BY子句都指定了该行的组合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: + 所有这些ORDER BY子句都指定了该行的复合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: SELECT * FROM inventory_item c ORDER BY ROW(c.name, c.supplier_id, c.price); SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); @@ -287,7 +287,7 @@ SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); - 另一种与组合值有关的特殊语法行为是,我们可以使用函数记法来提取组合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: + 另一种与复合值有关的特殊语法行为是,我们可以使用函数记法来提取复合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: SELECT c.name FROM inventory_item c WHERE c.price > 1000; @@ -328,7 +328,7 @@ SELECT c.somefunc FROM inventory_item c; 复合类型的输入和输出语法 - 组合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明组合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 + 复合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明复合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 '( 42)' @@ -336,7 +336,7 @@ SELECT c.somefunc FROM inventory_item c; - 如前所示,在写组合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让组合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的组合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作组合语法的数据字符。 + 如前所示,在写复合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让复合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的复合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作复合语法的数据字符。 @@ -350,18 +350,18 @@ SELECT c.somefunc FROM inventory_item c; - 记住,你在 SQL 命令中写的内容会先被解释为字符串字面量,然后才会被解释为组合值。这会使所需的反斜杠数量翻倍(假定使用的是转义字符串语法)。例如,要在组合值中插入一个包含双引号和反斜杠的text字段,需要写成: + 记住,你在 SQL 命令中写的内容会先被解释为字符串字面量,然后才会被解释为复合值。这会使所需的反斜杠数量翻倍(假定使用的是转义字符串语法)。例如,要在复合值中插入一个包含双引号和反斜杠的text字段,需要写成: INSERT ... VALUES ('("\"\\")'); - 字符串字面量处理器会去掉一层反斜杠,因此传到组合值解析器时看起来是("\"\\")。随后,送入text数据类型输入例程的字符串就变成了"\。(如果我们使用的数据类型的输入例程也会把反斜杠当作特殊字符处理,例如bytea,那么为了在存储的组合字段中得到一个反斜杠,命令里可能需要多达八个反斜杠。)美元引用(见)可用于避免反斜杠加倍的需要。 + 字符串字面量处理器会去掉一层反斜杠,因此传到复合值解析器时看起来是("\"\\")。随后,送入text数据类型输入例程的字符串就变成了"\。(如果我们使用的数据类型的输入例程也会把反斜杠当作特殊字符处理,例如bytea,那么为了在存储的复合字段中得到一个反斜杠,命令里可能需要多达八个反斜杠。)美元引用(见)可用于避免反斜杠加倍的需要。 - 在 SQL 命令中编写组合值时,ROW构造器语法通常比组合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是组合成员时完全相同。 + 在 SQL 命令中编写复合值时,ROW构造器语法通常比复合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是复合成员时完全相同。 diff --git a/zh/15/textsearch.sgml b/zh/15/textsearch.sgml index f08b7bc3..47c386ab 100644 --- a/zh/15/textsearch.sgml +++ b/zh/15/textsearch.sgml @@ -1,21 +1,21 @@ - 全文搜索 + 全文检索 - 全文搜索 + 全文检索 - 文本搜索 + 文本检索 介绍 - 全文搜索(或简称文本搜索)提供了识别满足 + 全文检索(或简称文本检索)提供了识别满足 查询条件的自然语言文档的能力, 并且可按它们与查询的相关度进行排序。最常见的搜索类型,是找出所有包含给定 查询词的文档,并按它们与查询的相似性 @@ -25,7 +25,7 @@ - 文本搜索操作符在数据库中已经存在很多年了。 + 文本检索操作符在数据库中已经存在很多年了。 PostgreSQL为文本数据类型提供了 ~~*LIKEILIKE 操作符,但它们缺少现代信息系统所要求的许多关键特性: @@ -138,7 +138,7 @@ ()。围绕这两种数据类型还有许多函数和 操作符(),其中最重要的是匹配操作符 @@,我们将在中介绍。 - 全文搜索还可以借助索引加速()。 + 全文检索还可以借助索引加速()。 @@ -147,11 +147,11 @@ 文档 - 全文搜索 + 文本检索 - 文档是全文搜索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本搜索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 + 文档是全文检索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本检索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 @@ -179,7 +179,7 @@ WHERE m.mid = d.did AND m.mid = 12; - 为了进行文本搜索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 + 为了进行文本检索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 @@ -187,7 +187,7 @@ WHERE m.mid = d.did AND m.mid = 12; 基本文本匹配 - 在PostgreSQL中,全文搜索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: + 在PostgreSQL中,全文检索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: SELECT 'a fat cat sat on a mat and ate a fat rat'::tsvector @@ 'cat & rat'::tsquery; @@ -203,7 +203,7 @@ SELECT 'fat & cow'::tsquery @@ 'a fat cat sat on a mat and ate a fat rat'::t - 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索术语,这些术语必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个术语组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本搜索匹配更像是这样: + 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索词,这些搜索词必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个搜索词组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本检索匹配更像是这样: SELECT to_tsvector('fat cats ate fat rats') @@ to_tsquery('fat & rat'); @@ -221,7 +221,7 @@ SELECT 'fat cats ate fat rats'::tsvector @@ to_tsquery('fat & rat'); f - 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,默认假定已经正规化,因此 rats 不会匹配 rat。 + 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,被假定为已经正规化,因此 rats 不会匹配 rat @@ -290,49 +290,49 @@ SELECT phraseto_tsquery('the cats ate the rats'); 配置 - 前述的都是简单的文本搜索示例。正如前面所提到的,全文搜索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如基于空白之外的解析。这个功能由文本搜索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 + 前述的都是简单的文本检索示例。正如前面所提到的,全文检索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如不局限于按空白划分的解析。这个功能由文本检索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 - 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本搜索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config。 + 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本检索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config - 依赖一个配置的每一个文本搜索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当这个参数被忽略时,default_text_search_config才被使用。 + 依赖一个配置的每一个文本检索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当省略这个参数时,default_text_search_config才被使用。 - 为了让建立自定义文本搜索配置更容易,一个配置可以从更简单的数据库对象来建立。PostgreSQL的文本搜索功能提供了四类配置相关的数据库对象: + 为了便于构建自定义文本检索配置,配置由更简单的数据库对象组合而成。PostgreSQL 的文本检索功能提供了四类与配置相关的数据库对象: - 文本搜索解析器将文档拆分成词元并分类每个词元(例如,作为词或者数字)。 + 文本检索解析器将文档拆分成词元并对每个词元分类(例如,作为词或者数字)。 - 文本搜索词典将词元转变成正规化的形式并拒绝停用词。 + 文本检索词典将词元转变成正规化的形式并拒绝停用词。 - 文本搜索模板提供位于词典底层的函数(一个词典简单地指定一个模板和一组用于模板的参数)。 + 文本检索模板提供位于词典底层的函数(词典只需指定一个模板及其一组参数)。 - 文本搜索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 + 文本检索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 - 文本搜索解析器和模板是从低层 C 函数构建而来,因此它要求 C 编程能力来开发新的解析器和模板,并且还需要超级用户权限来把它们安装到一个数据库中(在PostgreSQL发布的contrib/区域中有一些附加的解析器和模板的示例)。由于词典和配置只是对底层解析器和模板的参数化和连接,不需要特殊的权限来创建一个新词典或配置。创建定制词典和配置的示例将在本章稍后的部分给出。 + 文本检索解析器和模板由底层 C 函数构成,因此开发新的解析器和模板需要 C 编程能力,将它们安装到数据库中则需要超级用户权限。(PostgreSQL 发行版的 contrib/ 目录中有附加解析器和模板的示例。)词典和配置只是为底层解析器和模板设置参数并将它们连接起来,因此创建新词典或配置不需要特殊权限。本章后面会给出创建自定义词典和配置的示例。 @@ -343,14 +343,14 @@ SELECT phraseto_tsquery('the cats ate the rats'); 表和索引 - 在前一节中的示例演示了使用简单常数字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 + 在前一节中的示例演示了使用简单常量字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 搜索表 - 即使没有索引,也可以执行全文搜索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend: + 即使没有索引,也可以执行全文检索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend SELECT title @@ -374,7 +374,7 @@ WHERE to_tsvector(body) @@ to_tsquery('friend'); - 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 中同时包含 createtable: + 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 合在一起包含 createtable SELECT title @@ -388,7 +388,7 @@ LIMIT 10; - 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本搜索在实际使用中通常都需要建立索引。 + 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本检索在实际使用中通常都需要建立索引。 @@ -397,13 +397,13 @@ LIMIT 10; 创建索引 - 我们可以创建一个GIN索引()来加速文本搜索: + 我们可以创建一个GIN索引()来加速文本检索: CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector('english', body)); - 注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本搜索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含使用不同文本搜索配置创建的tsvector,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 + 注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本检索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含使用不同文本检索配置创建的tsvector,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 @@ -420,10 +420,7 @@ CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector(config_name, body)); 这里 config_namepgweb 表中的一个列。这样就允许在同一个索引中混合使用不同配置,同时记录每个索引项使用的是哪一种配置。例如,如果文档集合中包含不同语言的文档,这就会很有用。同样,打算使用该索引的查询也必须写成对应的形式,例如 WHERE to_tsvector(config_name, body) @@ 'a & b' - - 索引甚至可以连接列: - - + 索引甚至可以串接多个列: CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector('english', title || ' ' || body)); @@ -443,7 +440,7 @@ ALTER TABLE pgweb CREATE INDEX textsearch_idx ON pgweb USING GIN(textsearchable_index_col); - 现在我们准备好执行一个快速的全文搜索了: + 现在我们准备好执行一个快速的全文检索了: SELECT title @@ -455,7 +452,7 @@ LIMIT 10; - 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本搜索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 + 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本检索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 @@ -463,10 +460,10 @@ LIMIT 10; - 控制文本搜索 + 控制文本检索 - 要实现全文搜索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 + 要实现全文检索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 @@ -485,7 +482,7 @@ to_tsvector( config - to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本搜索配置进行处理。下面是一个简单示例: + to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本检索配置进行处理。下面是一个简单示例: SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); @@ -500,7 +497,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每类词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本搜索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english。 + to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每个词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本检索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english @@ -508,7 +505,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为空,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: + 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为 NULL,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: UPDATE tt SET ti = @@ -659,12 +656,12 @@ websearch_to_tsquery( config
- 无引号文本:不在引号中的文本会被转换为由&操作符分隔的词,就像经过plainto_tsquery处理一样。 + 未加引号的文本:不在引号中的文本会被转换为由&操作符分隔的词,就像经过plainto_tsquery处理一样。 - "引号文本":引号中的文本会被转换为由<->操作符分隔的词,就像经过phraseto_tsquery处理一样。 + "加引号的文本":引号中的文本会被转换为由<->操作符分隔的词,就像经过phraseto_tsquery处理一样。 @@ -722,7 +719,7 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); 搜索结果排名 - 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及它们出现于文档中哪个部分。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 + 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及这些词所处文档部分的重要程度。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 @@ -813,12 +810,12 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 8 用文档中唯一词的数量除排名 + 8 用文档中不同词的数量除排名 - 16 用 1 + 文档中唯一词数量的对数除排名 + 16 用 1 + 文档中不同词数量的对数除排名 @@ -832,7 +829,7 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。正规化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 + 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。归一化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 @@ -904,7 +901,7 @@ ts_headline( config ts_headline 接收文档和查询,并返回文档中一段 - 高亮查询词条的摘录。用于解析文档的配置可通过 config 指定; + 高亮查询词的摘录。用于解析文档的配置可通过 config 指定; 若省略 config,则使用 default_text_search_config 配置。 @@ -1009,7 +1006,7 @@ occurrences to display in the result.', 附加特性 - 本节介绍一些在文本搜索中很有用的附加函数和操作符。 + 本节介绍一些在文本检索中很有用的附加函数和操作符。 @@ -1122,7 +1119,7 @@ occurrences to display in the result.', - 返回用 AND 结合的两个给定查询。 + 返回两个给定查询的 AND 组合。 @@ -1136,7 +1133,7 @@ occurrences to display in the result.', - 返回用 OR 结合的两个给定查询。 + 返回两个给定查询的 OR 组合。 @@ -1189,7 +1186,7 @@ SELECT to_tsquery('fat') <-> to_tsquery('cat | rat'); - 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: + 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在其后距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: SELECT tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10); @@ -1243,10 +1240,7 @@ SELECT numnode('foo & bar'::tsquery); - - 返回可用于索引搜索的tsquery部分。这个函数可用于检测不可索引的查询,例如只包含停用词或只包含否定项的查询。例如: - - + 返回一个tsquery中可用于搜索索引的部分。此函数可用于检测无法使用索引的查询,例如只包含停用词或只包含否定词项的查询。例如: SELECT querytree(to_tsquery('defined')); querytree ----------- @@ -1422,7 +1416,7 @@ SELECT title, body FROM messages WHERE tsv @@ to_tsquery('title & body'); - 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本搜索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 + 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本检索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 @@ -1489,7 +1483,7 @@ ts_stat(sqlquery text, - 如果提供了 weights,则只统计具有这些权重之一的出现。 + 如果提供了 weights,则只统计具有这些权重之一的词的出现次数。 @@ -1518,7 +1512,7 @@ LIMIT 10; 解析器 - 文本搜索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 + 文本检索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 @@ -1541,12 +1535,12 @@ LIMIT 10; asciiword - 单词,所有 ASCII 字母 + 单词,全部由 ASCII 字母组成 elephant word - 单词,所有字母 + 单词,全部由字母组成 mañana @@ -1556,12 +1550,12 @@ LIMIT 10; asciihword - 带连字符的单词,所有 ASCII + 带连字符的单词,全部为 ASCII 字符 up-to-date hword - 带连字符的单词,所有字母 + 带连字符的单词,由字母组成 lógico-matemática @@ -1571,12 +1565,12 @@ LIMIT 10; hword_asciipart - 带连字符的单词部分,所有 ASCII + 带连字符的单词部分,全部为 ASCII 字符 postgresql-beta1 上下文中的 postgresql hword_part - 带连字符的单词部分,所有字母 + 带连字符的单词部分,全部由字母组成 lógico-matemática 上下文中的 lógicomatemática @@ -1651,8 +1645,8 @@ LIMIT 10; blank - 空格符号 - (其他不识别的任意空白或标点符号) + 空白符号 + (未被识别为其他类型的空白或标点符号) @@ -1660,12 +1654,12 @@ LIMIT 10; - 解析器的一个字母的概念由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时可以用来区别它们。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 + 解析器对字母的界定由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时区分它们会很有用。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 email不支持所有由RFC 5322定义的有效电子邮件字符。 - 具体来说,电子邮件用户名仅支持句号、短横线和下划线这些非字母数字字符。 + 具体来说,电子邮件用户名仅支持句点、短横线和下划线这些非字母数字字符。 @@ -1714,7 +1708,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h 词典 - 词典用于消除不应参与搜索的词(stop words),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 + 词典用于消除不应参与搜索的词(停用词),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 @@ -1729,7 +1723,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - URL地址可以被正规化,以便让等价的 URL 匹配: + URL 地址可以规范化,以便让等价的 URL 匹配: @@ -1774,32 +1768,32 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤字典) + 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤词典 - 如果字典知道该词元但它是一个停用词,则返回一个空数组 + 如果词典知道该词元但它是一个停用词,则返回一个空数组 - 如果字典不识别该输入词元,则返回NULL + 如果词典不识别该输入词元,则返回NULL - PostgreSQL为许多语言提供了预定义的字典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发布的contrib/区域。 + PostgreSQL为许多语言提供了预定义的词典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发行版的contrib/目录。 - 文本搜索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 + 文本检索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 - 配置词典列表的一般规则是,把最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语分类词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: + 配置词典列表的一般规则是,把适用范围最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语同义词词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: ALTER TEXT SEARCH CONFIGURATION astro_en @@ -1808,14 +1802,14 @@ ALTER TEXT SEARCH CONFIGURATION astro_en - 过滤词典可以放在列表中的任何位置,只是不能放在最后,因为放在最后就没有意义了。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 + 过滤词典可以放在列表中的任何位置,但放在末尾没有用处。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 停用词 - 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文搜索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: + 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文检索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: SELECT to_tsvector('english', 'in the list of stop words'); @@ -1947,7 +1941,7 @@ SELECT * FROM ts_debug('english', 'Paris'); - synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基本名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 + synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 @@ -2009,28 +2003,28 @@ mydb=# SELECT 'indexes are very useful'::tsvector @@ to_tsquery('tst', 'indices' - 基本上一个分类词典会用一个首选词替换所有非首选词,并且也可选择地保留原始术语用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典要求一个下列格式的配置文件: + 分类词典基本上会用一个首选词替换所有非首选词,并且也可以选择保留原始词用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典需要一个采用以下格式的配置文件: -# this is a comment -sample word(s) : indexed word(s) -more sample word(s) : more indexed word(s) +# 这是一条注释 +示例词(一个或多个) : 索引词(一个或多个) +更多示例词(一个或多个) : 更多索引词(一个或多个) ... - 其中冒号(:)符号扮演了一个短语及其替换之间的定界符。 + 其中冒号(:)符号用作短语及其替换词之间的分隔符。 - 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过对子词典的应用,但所有样例词都必须能被子词典识别。 + 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过将子词典应用于该词,但所有样例词都必须能被子词典识别。 - 如果有多个短语匹配输入,则分类词典选择最长的那一个,并且使用最后的定义打破连结。 + 如果有多个短语匹配输入,分类词典会选择最长的匹配;长度相同时使用最后的定义。 - 由子词典识别的特定停用词不能够被指定;改用?标记任何可以出现停用词的地方。例如,假定根据子词典athe是停用词: + 由子词典识别的特定停用词不能够被指定;改用?标记可出现任意停用词的位置。例如,假定根据子词典athe是停用词: ? one ? two : swsw @@ -2072,7 +2066,7 @@ CREATE TEXT SEARCH DICTIONARY thesaurus_simple ( - mythesaurus是分类词典配置文件的基础名称(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 + mythesaurus是分类词典配置文件的基名(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 @@ -2097,7 +2091,7 @@ ALTER TEXT SEARCH CONFIGURATION russian 分类词典示例 - 考虑简单的天文词库 thesaurus_astro,其中包含一些天文单词组合: + 考虑一个简单的天文分类词典 thesaurus_astro,其中包含一些天文单词组合: supernovae stars : sn @@ -2165,7 +2159,7 @@ SELECT plainto_tsquery('supernova star'); <application>Ispell</application> 词典 - Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以把搜索词 bank 的词尾变化和词形变化对应起来,例如 bankingbankedbanksbanks'bank's。 + Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以匹配搜索词 bank 的所有变格和变位形式,例如 bankingbankedbanksbanks'bank's @@ -2177,12 +2171,12 @@ SELECT plainto_tsquery('supernova star'); - 要创建一个Ispell词典,执行这三步: + 要创建一个Ispell词典,请执行以下步骤: - 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。有必要抽取.aff.dic文件,把扩展改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): + 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。需要提取.aff.dic文件,将扩展名改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): iconv -f ISO_8859-1 -t UTF-8 -o nn_no.affix nn_NO.aff iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic @@ -2191,7 +2185,7 @@ iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic - 拷贝文件到$SHAREDIR/tsearch_data目录 + 复制文件到$SHAREDIR/tsearch_data目录 @@ -2209,11 +2203,11 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( - 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基础名称。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 + 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基名。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 - Ispell 词典通常识别一个有限集合的词,这样它们后面应该跟着另一个更广义的词典;例如,一个 Snowball 词典,它可以识别所有东西。 + Ispell 词典通常只能识别有限的词,因此其后应跟着另一个覆盖范围更广的词典;例如,一个 Snowball 词典,它可以识别所有输入。 @@ -2221,13 +2215,13 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( prefixes flag *A: - . > RE # As in enter > reenter + . > RE # 例如 enter > reenter suffixes flag T: - E > ST # As in late > latest - [^AEIOU]Y > -Y,IEST # As in dirty > dirtiest - [AEIOU]Y > EST # As in gray > grayest - [^EY] > EST # As in small > smallest + E > ST # 例如 late > latest + [^AEIOU]Y > -Y,IEST # 例如 dirty > dirtiest + [AEIOU]Y > EST # 例如 gray > grayest + [^EY] > EST # 例如 small > smallest @@ -2243,14 +2237,14 @@ lark/MRS .dict文件的格式是: -basic_form/affix_class_name +基本词形/词缀类名 .affix文件中,每一个词缀标志以下面的格式描述: -condition > [-stripping_letters,] adding_affix +条件 > [-删除的字母,] 添加的词缀 @@ -2259,7 +2253,7 @@ condition > [-stripping_letters,] adding_affix - Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,它标记可以参与到复合格式中的词典词: + Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,用于标记词典中可以参与构成复合词的词: compoundwords controlled z @@ -2289,7 +2283,7 @@ SFX T 0 est [^ey] - 一个词缀类的第一行是头部。头部后面列出了词缀规则的域: + 一个词缀类的第一行是首部。首部后面列出了词缀规则的字段: @@ -2341,7 +2335,7 @@ largehearted <application>Snowball</application> 词典 - Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每一个算法懂得按照其语言中的拼写,如何缩减词的常见变体形式为一个基础或词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择地指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。例如,有一个内置的定义等效于 + Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每种算法都知道如何把其语言中词的常见变体约简为基本拼写形式,也就是词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。例如,有一个内置的定义等效于 CREATE TEXT SEARCH DICTIONARY english_stem ( @@ -2355,7 +2349,7 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( - 一个Snowball词典识别所有的东西,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 + 一个Snowball词典识别所有输入,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 @@ -2366,11 +2360,11 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( 配置示例 - 一个文本搜索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本搜索配置来执行其处理。配置参数指定了默认配置的名称,如果忽略了显式的配置参数,文本搜索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 + 一个文本检索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本检索配置来执行其处理。配置参数指定了默认配置的名称,如果省略了显式的配置参数,文本检索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 - 有一些预定义的文本搜索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本搜索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本搜索对象()的信息。 + 有一些预定义的文本检索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本检索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本检索对象()的信息。 @@ -2462,17 +2456,17 @@ SHOW default_text_search_config; - 测试和调试文本搜索 + 测试和调试文本检索 - 一个自定义文本搜索配置的行为很容易变得混乱。本节中描述的函数对于测试文本搜索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 + 一个自定义文本检索配置的行为很容易让人困惑。本节中描述的函数对于测试文本检索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 配置测试 - 函数ts_debug允许简单地测试一个文本搜索配置。 + 函数ts_debug可方便地测试一个文本检索配置。 @@ -2491,7 +2485,7 @@ ts_debug( config re - ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果该参数被忽略则使用default_text_search_config指定的配置。 + ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果省略该参数则使用default_text_search_config指定的配置。 @@ -2566,7 +2560,7 @@ SELECT * FROM ts_debug('english', 'a fat cat sat on a mat - it ate a fat rats') - 为了一个更广泛的示范,我们先为英语语言创建一个public.english配置和 Ispell 词典: + 为了做更完整的演示,我们先为英语创建一个public.english配置和 Ispell 词典: @@ -2624,7 +2618,7 @@ FROM ts_debug('public.english', 'The Brightest supernovaes'); 解析器测试 - 下列函数允许直接测试一个文本搜索解析器。 + 下列函数允许直接测试一个文本检索解析器。 @@ -2666,7 +2660,7 @@ ts_token_type(parser_oid oid< - ts_token_type返回一个表,描述指定解析器能够识别的每一种词元。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: + ts_token_type返回一个表,描述指定解析器能够识别的每一种词元类型。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: SELECT * FROM ts_token_type('default'); @@ -2704,7 +2698,7 @@ SELECT * FROM ts_token_type('default'); 词典测试 - ts_lexize函数帮助词典测试。 + ts_lexize函数便于测试词典。 @@ -2762,17 +2756,17 @@ SELECT plainto_tsquery('supernovae stars'); - 文本搜索的首选索引类型 + 文本检索的首选索引类型 - 文本搜索 + 文本检索 索引 - 有两种索引可以用来加速全文搜索:GIN和 + 有两种索引可以用来加速全文检索:GINGiST。 - 请注意,索引对于全文搜索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 + 请注意,索引对于全文检索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 @@ -2786,7 +2780,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GIN - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIN (column); @@ -2806,7 +2800,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GiST - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIST (column [ { DEFAULT | tsvector_ops } (siglen = number) ] ); @@ -2816,7 +2810,7 @@ SELECT plainto_tsquery('supernovae stars'); 创建基于 GiST(广义搜索树)的索引。 column可以是tsvectortsquery类型。 - 可选的整数参数siglen确定签名长度(有关详细信息,请参见下文)。 + 可选的整数参数siglen确定以字节为单位的签名长度(有关详细信息,请参见下文)。 @@ -2825,7 +2819,7 @@ SELECT plainto_tsquery('supernovae stars'); - GIN 索引是文本搜索的首选索引类型。作为倒排索引,每个词(词位)在 + GIN 索引是文本检索的首选索引类型。作为倒排索引,每个词(词位)在 其中都有一个索引项,其中有压缩过的匹配位置的列表。多词搜索可以找到 第一个匹配,然后使用该索引移除缺少额外词的行。GIN 索引只存储 tsvector值的词(词位),并且不存储它们的权重标签。因此, @@ -2833,19 +2827,19 @@ SELECT plainto_tsquery('supernovae stars'); - 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。以字节为单位的签名长度由可选整数参数 siglen 的值决定。 默认签名长度(未指定 siglen 时)为 124 字节,最大签名长度为 2024 字节。该签名通过哈希每一个词到一个 n 位串中的一个单一位来产生,通过将所有这些位 OR 在一起产生一个 n 位的文档签名。当两个词哈希到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。更长的签名导致更精确的搜索(扫描索引的一小部分和更少的堆页面),但代价是更大的索引。 + 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。以字节为单位的签名长度由可选整数参数 siglen 的值决定。 默认签名长度(未指定 siglen 时)为 124 字节,最大签名长度为 2024 字节。该签名通过将每个词 hash 到一个 n 位串中的一位,再将所有这些位进行 OR 运算来生成,结果是一个 n 位的文档签名。当两个词 hash 到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。更长的签名导致更精确的搜索(扫描更小比例的索引和更少的堆页面),但代价是更大的索引。 - GiST 可以构建为覆盖索引,例如使用 INCLUDE 子句。被包含的列可以具有没有任何 GiST 操作符类的数据类型。被包含的属性会以未压缩形式存储。 + GiST 可以构建为覆盖索引,即使用 INCLUDE 子句。被包含的列可以具有没有任何 GiST 操作符类的数据类型。被包含的属性会以未压缩形式存储。 - 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的可用性。假匹配的可能性取决于几个因素,特别是唯一词的数量,因此推荐使用词典来缩减这个数量。 + 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的实用性。假匹配的可能性取决于几个因素,特别是不同词的数量,因此推荐使用词典来缩减这个数量。 - 注意GIN索引的构件时间常常可以通过增加来改进,而GiST索引的构建时间则与该参数无关。 + 注意GIN索引的构建时间常常可以通过增加来改进,而GiST索引的构建时间则对该参数不敏感。 @@ -2859,7 +2853,7 @@ SELECT plainto_tsquery('supernovae stars'); <application>psql</application> 支持 - 关于文本搜索配置对象的信息可以在psql中使用一组命令获得: + 关于文本检索配置对象的信息可以在psql中使用一组命令获得: \dF{d,p,t}+ PATTERN @@ -2867,7 +2861,7 @@ SELECT plainto_tsquery('supernovae stars'); - 可选参数 PATTERN 可以是文本搜索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: + 可选参数 PATTERN 可以是文本检索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: => \dF *fulltext* @@ -2894,7 +2888,7 @@ SELECT plainto_tsquery('supernovae stars'); \dF+ PATTERN - 列出文本搜索配置(加上 + 可显示更多细节)。 + 列出文本检索配置(加上 + 可显示更多细节)。 => \dF russian List of text search configurations @@ -2935,7 +2929,7 @@ Parser: "pg_catalog.default" \dFd+ PATTERN - 列出文本搜索词典(加上 + 可显示更多细节)。 + 列出文本检索词典(加上 + 可显示更多细节)。 => \dFd List of text search dictionaries @@ -2948,7 +2942,6 @@ Parser: "pg_catalog.default" pg_catalog | danish_stem | snowball stemmer for danish language pg_catalog | dutch_stem | snowball stemmer for dutch language pg_catalog | english_stem | snowball stemmer for english language - pg_catalog | estonian_stem | snowball stemmer for estonian language pg_catalog | finnish_stem | snowball stemmer for finnish language pg_catalog | french_stem | snowball stemmer for french language pg_catalog | german_stem | snowball stemmer for german language @@ -2980,7 +2973,7 @@ Parser: "pg_catalog.default" \dFp+ PATTERN - 列出文本搜索解析器(加上 + 可显示更多细节)。 + 列出文本检索解析器(加上 + 可显示更多细节)。 => \dFp List of text search parsers @@ -3033,7 +3026,7 @@ Parser: "pg_catalog.default" \dFt+ PATTERN - 列出文本搜索模板(加上 + 可显示更多细节)。 + 列出文本检索模板(加上 + 可显示更多细节)。 => \dFt List of text search templates @@ -3056,7 +3049,7 @@ Parser: "pg_catalog.default" 限制 - PostgreSQL 当前文本搜索特性的限制如下: + PostgreSQL 当前文本检索特性的限制如下: 每个词位的长度必须小于 2 千字节 @@ -3084,12 +3077,12 @@ Parser: "pg_catalog.default" - 为了对比,PostgreSQL 8.1 的文档包含 10,441 个唯一词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 + 为了对比,PostgreSQL 8.1 的文档包含 10,441 个不同词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 - 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个唯一词。 + 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个不同词。 diff --git a/zh/15/unaccent.sgml b/zh/15/unaccent.sgml index b98d832e..00149b22 100644 --- a/zh/15/unaccent.sgml +++ b/zh/15/unaccent.sgml @@ -8,11 +8,11 @@ - unaccent是一个文本搜索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤字典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文搜索能够以不区分重音的方式处理文本。 + unaccent是一个文本检索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤词典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文检索能够以不区分重音的方式处理文本。 - unaccent当前的实现还不能作为thesaurus词典的正规化字典使用。 + unaccent当前的实现还不能作为thesaurus词典的正规化词典使用。 @@ -64,22 +64,11 @@ - - - 某些字符(例如数字符号)在其转换规则中可能需要空白字符。在这种情况下,可以用双引号把转换后的字符括起来。如果转换后的字符中本身要包含双引号,则需要再用一个双引号对其转义。例如: - -¼ " 1/4" -½ " 1/2" -¾ " 3/4" -“ """" -” """" - - - + - 与其他PostgreSQL文本搜索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含不可转换字符的行都会被静默忽略,因此规则文件中可以包含不适用于当前编码的规则。 + 与其他PostgreSQL文本检索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含不可转换字符的行都会被静默忽略,因此规则文件中可以包含不适用于当前编码的规则。 @@ -93,7 +82,7 @@ 用法 - 安装unaccent扩展会创建一个文本搜索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 + 安装unaccent扩展会创建一个文本检索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 mydb=# ALTER TEXT SEARCH DICTIONARY unaccent (RULES='my_rules'); @@ -114,7 +103,7 @@ mydb=# select ts_lexize('unaccent','Hôtel'); - 下面的示例展示了如何将unaccent词典插入到文本搜索配置中: + 下面的示例展示了如何将unaccent词典插入到文本检索配置中: mydb=# CREATE TEXT SEARCH CONFIGURATION fr ( COPY = french ); mydb=# ALTER TEXT SEARCH CONFIGURATION fr @@ -145,7 +134,7 @@ mydb=# select ts_headline('fr','Hôtel de la Mer',to_tsquery('fr','Hotels') 函数 - unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本搜索环境之外使用。 + unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本检索环境之外使用。 @@ -157,7 +146,7 @@ unaccent(dictionary - 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本搜索词典。 + 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本检索词典。 diff --git a/zh/16/array.sgml b/zh/16/array.sgml index a9464b0b..1d2a2443 100644 --- a/zh/16/array.sgml +++ b/zh/16/array.sgml @@ -4,7 +4,7 @@ 数组 - array + 数组 @@ -15,8 +15,8 @@ 数组类型的声明 - array - declaration + 数组 + 声明 @@ -64,8 +64,8 @@ CREATE TABLE tictactoe ( 数组值输入 - array - constant + 数组 + 常量 @@ -86,7 +86,7 @@ CREATE TABLE tictactoe ( (这类数组常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。必要时可能需要显式指定类型。) + linkend="sql-syntax-constants-generic"/>中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。可能需要显式指定类型。) @@ -119,7 +119,7 @@ SELECT * FROM sal_emp; - 多维数组在每个维度上的范围必须匹配。不匹配会导致错误,例如: + 多维数组的各个子数组在每个维度上的长度必须匹配。不匹配会导致错误,例如: INSERT INTO sal_emp @@ -151,8 +151,8 @@ INSERT INTO sal_emp 访问数组 - array - accessing + 数组 + 访问 @@ -185,9 +185,9 @@ SELECT pay_by_quarter[3] FROM sal_emp; - 我们还可以访问数组或子数组的任意矩形切片。数组切片通过在一个或多个数组维度上写成 + 我们还可以访问数组的任意矩形切片,即子数组。数组切片通过在一个或多个数组维度上写成 lower-bound:upper-bound - 的形式来表示。例如,下面这个查询取回 Bill 在一周前两天日程安排中的第一个项目: + 的形式来表示。例如,下面这个查询取回 Bill 在一周中前两天里每天的首项日程: SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill'; @@ -234,11 +234,11 @@ SELECT schedule[:][1:1] FROM sal_emp WHERE name = 'Bill'; - 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回空值。此外,如果下标超出数组边界,也会返回空值(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是空值而不是错误。 + 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回 NULL。此外,如果下标超出数组边界,也会返回 NULL(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是 NULL 而不是错误。 - 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回空值。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是空值。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回空值。 + 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回 NULL。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是 NULL。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回 NULL。 @@ -292,8 +292,8 @@ SELECT cardinality(schedule) FROM sal_emp WHERE name = 'Carol'; 修改数组 - array - modifying + 数组 + 修改 @@ -330,7 +330,7 @@ UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}' - 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用空值填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含空值。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 + 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用 NULL 填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含 NULL。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 @@ -442,21 +442,21 @@ SELECT array_cat(ARRAY[5,6], ARRAY[[1,2],[3,4]]); 在简单情况下,优先使用上面讨论的连接操作符,而不是直接调用这些函数。不过,由于连接操作符被重载以同时服务于这三种情形,所以在某些场景下使用这些函数之一有助于避免歧义。例如,考虑: -SELECT ARRAY[1, 2] || '{3, 4}'; -- the untyped literal is taken as an array +SELECT ARRAY[1, 2] || '{3, 4}'; -- 未指定类型的字面量被当作数组 ?column? ----------- {1,2,3,4} -SELECT ARRAY[1, 2] || '7'; -- so is this one +SELECT ARRAY[1, 2] || '7'; -- 这个字面量也一样 ERROR: malformed array literal: "7" -SELECT ARRAY[1, 2] || NULL; -- so is an undecorated NULL +SELECT ARRAY[1, 2] || NULL; -- 未加类型修饰的 NULL 也一样 ?column? ---------- {1,2} (1 row) -SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant +SELECT array_append(ARRAY[1, 2], NULL); -- 这可能才是原本想表达的意思 array_append -------------- {1,2,NULL} @@ -470,8 +470,8 @@ SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant 在数组中搜索 - array - searching + 数组 + 搜索 @@ -551,7 +551,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); 数组输入和输出语法 - array + 数组 I/O @@ -564,7 +564,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); - 默认情况下,数组各维度的下界索引值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: + 默认情况下,数组各维度的下界下标值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2 FROM (SELECT '[1:1][-2:-1][3:5]={{{1,2,3},{4,5,6}}}'::int[] AS f1) AS ss; diff --git a/zh/16/catalogs.sgml b/zh/16/catalogs.sgml index df29145e..9636fac1 100644 --- a/zh/16/catalogs.sgml +++ b/zh/16/catalogs.sgml @@ -320,27 +320,27 @@ pg_ts_config - 文本搜索配置 + 文本检索配置 pg_ts_config_map - 文本搜索配置的词元映射 + 文本检索配置的词元映射 pg_ts_dict - 文本搜索字典 + 文本检索词典 pg_ts_parser - 文本搜索分析器 + 文本检索解析器 pg_ts_template - 文本搜索模板 + 文本检索模板 @@ -7671,12 +7671,12 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config目录包含表示文本搜索配置的条目。一个配置指定某个特定的文本搜索分析器,以及针对该分析器每种输出词元类型所定义的字典列表。分析器由pg_ts_config项表示,而词元到字典的映射则由pg_ts_config系统目录包含表示文本检索配置的条目。一个配置指定某个特定的文本检索解析器,以及针对该解析器每种输出词元类型所定义的词典列表。解析器记录在pg_ts_config条目中,而词元到词典的映射则由pg_ts_config_map中的辅助项定义。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。 @@ -7708,7 +7708,7 @@ SCRAM-SHA-256$<iteration count>:&l cfgname name - 文本搜索配置名 + 文本检索配置名 @@ -7738,7 +7738,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_ts_parser.oid - 该配置的文本搜索分析器的OID + 该配置的文本检索解析器的 OID @@ -7755,11 +7755,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config_map目录包含的项展示了对于每一个文本搜索配置的每一种输出词元类型,有哪些文本搜索字典可供查询以及以何种顺序。 + pg_ts_config_map 系统目录中的条目说明了,对于每个文本检索配置所用解析器的每种输出词元类型,应当查询哪些文本检索词典以及查询的顺序。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7792,7 +7792,7 @@ SCRAM-SHA-256$<iteration count>:&l maptokentype int4 - 一种由配置的分析器送出的词元类型 + 一种由配置的解析器送出的词元类型 @@ -7811,7 +7811,7 @@ SCRAM-SHA-256$<iteration count>:&l (参考 pg_ts_dict.oid - 要查询的文本搜索字典的OID + 要查询的文本检索词典的 OID @@ -7828,11 +7828,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_dict目录包含定义文本搜索字典的项。一个字典依赖于一个文本搜索模板,它指定了所有需要的函数实现,字典本身则为模板支持的用户可设置参数提供值。这种分工允许无权限的用户创建字典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 + pg_ts_dict系统目录包含定义文本检索词典的项。一个词典依赖于一个文本检索模板,它指定了所有需要的实现函数,词典本身则为模板支持的用户可设置参数提供值。这种分工允许普通用户创建词典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7864,7 +7864,7 @@ SCRAM-SHA-256$<iteration count>:&l dictname name - 文本搜索字典名 + 文本检索词典名 @@ -7874,7 +7874,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_namespace.oid - 包含该字典的名字空间OID + 包含该词典的名字空间的 OID @@ -7884,7 +7884,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_authid.oid - 字典的拥有者 + 词典的拥有者 @@ -7894,7 +7894,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_ts_template.oid - 该字典的文本搜索模板的OID + 该词典的文本检索模板的 OID @@ -7920,11 +7920,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_parser目录包含定义文本搜索分析器的项。一个分析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个分析器必须用C语言级别的函数实现,创建新分析器的工作只限于数据库的超级用户。 + pg_ts_parser系统目录包含定义文本检索解析器的项。一个解析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个解析器必须用 C 语言级别的函数实现,创建新解析器的工作只限于数据库的超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7956,7 +7956,7 @@ SCRAM-SHA-256$<iteration count>:&l prsname name - 文本搜索分析器的名字 + 文本检索解析器的名字 @@ -7966,7 +7966,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_namespace.oid - 包含此分析器的名字空间的OID + 包含此解析器的名字空间的 OID @@ -7976,7 +7976,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器启动函数的OID + 解析器启动函数的 OID @@ -7986,7 +7986,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的下一词元函数的OID + 解析器的下一词元函数的 OID @@ -7996,7 +7996,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的关闭函数的OID + 解析器的关闭函数的 OID @@ -8006,7 +8006,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器标题函数的 OID(如果没有则为零) + 解析器的 headline 函数的 OID(如果没有则为零) @@ -8016,7 +8016,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的词汇类型函数的OID + 解析器的 lextype 函数的 OID @@ -8033,11 +8033,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_template目录包含定义文本搜索模板的项。一个模板是一类文本搜索字典的实现骨架。由于一个模板必须用C语言级别的函数实现,新模板的创建只限于数据库超级用户。 + pg_ts_template系统目录包含定义文本检索模板的项。一个模板是一类文本检索词典的实现骨架。由于一个模板必须用 C 语言级别的函数实现,新模板的创建只限于数据库超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -8069,7 +8069,7 @@ SCRAM-SHA-256$<iteration count>:&l tmplname name - 文本搜索模板的名字 + 文本检索模板的名字 diff --git a/zh/16/config.sgml b/zh/16/config.sgml index 2c14776e..73200651 100644 --- a/zh/16/config.sgml +++ b/zh/16/config.sgml @@ -2779,7 +2779,7 @@ include_dir 'conf.d' 配置 - 恢复的 + 恢复 一般设置 @@ -2841,7 +2841,7 @@ include_dir 'conf.d' 配置 恢复 - 一个备库 + 备库 @@ -3245,7 +3245,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows - 列出安装在 所指定位置中、同时也被信任可供复制客户端用作逻辑输出插件的库。 + 列出安装在 所指定位置中、同时也受信任、可供复制客户端用作逻辑输出插件的库。 任何针对其他库的逻辑解码或 复制请求都将被拒绝。所有用户都受此限制。 默认值为 'pgoutput, test_decoding',它们是标准 @@ -3740,7 +3740,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( )。 + 设置规划器对一系列顺序磁盘页面读取中单次读取的代价估计。默认值是 1.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -4226,7 +4219,7 @@ ANY num_sync ( )。 + 设置规划器对一次非顺序磁盘页面读取的代价估计。默认值是 4.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -4239,14 +4232,13 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( 。 如果指定值时没有单位,则以块为单位,即BLCKSZ字节,通常为8kB。默认值是512千字节(512kB)。 @@ -4372,13 +4364,13 @@ ANY num_sync ( num_sync ( - 遗传查询优化 + 遗传查询优化器 - GEQO是一个使用探索式搜索来执行查询规划的算法。它可以降低负载查询的规划时间。 同时,GEQO的检索是随机的,因此它的规划可能会不可确定。 更多信息参阅Chapter 50。 - 遗传查询规划器(GEQO)是一种使用启发式搜索来进行查询规划的算法。它可以降低对于复杂查询(连接很多表的查询)的规划时间,但是代价是它产生的计划有时候要差于使用穷举搜索算法找到的计划。详见。 + 遗传查询优化器(GEQO)是一种使用启发式搜索进行查询规划的算法。它可以缩短复杂查询(连接很多关系的查询)的规划时间,代价是生成的计划有时不如常规穷举搜索算法找到的计划。更多信息见 @@ -4459,7 +4450,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( .) + 目前,约束排除仅在通常用于通过继承树实现表分区的情况下默认启用。为所有表启用它会增加额外的规划开销,这在简单查询上相当明显,而且通常不会为简单查询带来好处。如果没有通过传统继承方式进行分区的表,你可能希望完全关闭它。(注意,分区表的等效功能由另一个参数控制。) @@ -4708,13 +4696,7 @@ SELECT * FROM parent WHERE key = 2400; - 准备语句(显式准备或隐式生成的,例如 PL/pgSQL)可以使用自定义或通用计划执行。 - 使用其特定的参数值集为每个执行重新生成自定义计划,而通用计划不依赖于参数值,并且可以在执行中重复使用。 - 因此,使用通用计划可以节省计划时间,但如果理想计划严重依赖参数值,则通用计划可能效率低下。 - 这些选项之间的选择通常是自动进行的,但可以通过plan_cache_mode覆盖它。 - 允许的值为 auto (默认的),force_custom_planforce_generic_plan。 - 这个设置是在执行缓存计划时考虑,而不是在准备计划时考虑。 - 更多信息请参阅 . + 预备语句(无论是显式预备的,还是由 PL/pgSQL 等隐式生成的)可以使用自定义计划或通用计划执行。自定义计划会根据每次执行的具体参数值重新生成,而通用计划不依赖参数值,可以在多次执行之间复用。因此,使用通用计划能够节省规划时间,但如果理想计划高度依赖参数值,通用计划可能效率较低。系统通常会自动选择这两种计划,但可以通过plan_cache_mode覆盖这一选择。允许的值为auto(默认值)、force_custom_planforce_generic_plan。系统在执行缓存计划时考虑此设置,而不是在预备计划时。更多信息见 @@ -4732,7 +4714,7 @@ SELECT * FROM parent WHERE key = 2400; 设置规划器对递归查询 的工作表的平均大小的估计值,作为查询初始非递归项的估计大小的倍数。 这有助于规划器选择将工作表与查询的其他表连接的最合适方法。 - 默认值为10.0。当递归从一步到下一步的fan-out较低时,如最短路径查询中的示例,使用较小的值(如1.0)可能有所帮助。 + 默认值为10.0。当递归从一步到下一步的扇出较低时,例如最短路径查询,使用较小的值(如1.0)可能有所帮助。 图分析查询可能会从大于默认值的设置中受益。 @@ -4751,7 +4733,7 @@ SELECT * FROM parent WHERE key = 2400; - 在哪里做日志 + 日志记录到哪里 日志写到哪里 @@ -4759,7 +4741,7 @@ SELECT * FROM parent WHERE key = 2400; current_logfiles - 和日志_目的地配置参数 + 和 log_destination 配置参数 @@ -4807,13 +4789,13 @@ jsonlog log/postgresql.json 当由于轮换而创建新的日志文件时,以及重新加载log_destination时,current_logfiles会被重新创建。 当log_destination中不包含stderrcsvlogjsonlog, - 以及日志收集器被禁用时,它会被移除。 + 或者日志收集器被禁用时,它会被移除。 - 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设备LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: + 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设施LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: local0.* /var/log/postgresql @@ -4821,7 +4803,7 @@ local0.* /var/log/postgresql - 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源极其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见。 + 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源及其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见 @@ -4837,20 +4819,20 @@ local0.* /var/log/postgresql - 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 + 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息可能不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 - 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供方法来轮转日志文件。还有,在某些不使用日志收集器的平台上可能会导致丢失或者混淆日志输出,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 + 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供便捷的方法来轮转日志文件。还有,在某些平台上,不使用日志收集器可能会导致日志输出丢失或混杂,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 - 日志收集器被设计成从来不会丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 + 日志收集器被设计成从来不会丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它可能会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 @@ -4884,7 +4866,7 @@ local0.* /var/log/postgresql logging_collector被启用时,这个参数设置被创建的日志文件的文件名。 - 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何时区独立的%转义,计算将在由指定的时区中完成)。 + 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何依赖时区的%转义,计算将在由指定的时区中完成)。 被支持的%转义和开放组织的strftime说明中列举的类似。 注意系统的strftime不会被直接使用,因此平台相关(非标准)的扩展无法工作。 默认是postgresql-%Y-%m-%d_%H%M%S.log。 @@ -4922,7 +4904,7 @@ local0.* /var/log/postgresql - 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的十进制格式,该数字必须以一个0(零)开始)。 + 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的八进制格式,该数字必须以一个0(零)开始)。 @@ -4988,7 +4970,7 @@ local0.* /var/log/postgresql - 示例:要保留 24 小时的日志,每个小时一个日志文件,但是在日志文件尺寸超过 1GB 时轮转。可以这样做:将log_filename设置为server_log.%H%M、 + 示例:要保留 24 小时的日志,每个小时一个日志文件,如果日志文件尺寸超过 1GB,也会提前轮转。可以这样做:将log_filename设置为server_log.%H%M、 将log_truncate_on_rotation设置为on、 将log_rotation_age设置为60并且 将log_rotation_size设置为1000000。 @@ -5007,7 +4989,7 @@ local0.* /var/log/postgresql - 当启用了向syslog记录时,这个参数决定要使用的syslog设备。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4、 + 当启用了向syslog记录时,这个参数决定要使用的syslog设施。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4LOCAL5LOCAL6LOCAL7中选择,默认值是LOCAL0。还请参阅系统的syslog守护进程的文档。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -5062,7 +5044,7 @@ local0.* /var/log/postgresql - 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,有必要让消息保持逻辑上的整体性(也更加有用)。 + 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,让消息保持逻辑上的完整性可能是必要的,也可能更有用。 @@ -5081,7 +5063,7 @@ local0.* /var/log/postgresql - 当启用了向事件日志记录时,这个参数决定用来标识日志中PostgreSQL消息的程序名。默认值是PostgreSQL。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 当启用了向事件日志记录时,这个参数决定用来标识日志中PostgreSQL消息的程序名。默认值是PostgreSQL。这个参数只能在服务器启动时设置。 @@ -5127,9 +5109,7 @@ local0.* /var/log/postgresql - 控制在服务器日志中记录哪些导致错误条件的SQL语句。当前的SQL语句将包含在任何指定 - severity - 或更高消息的日志条目中。 + 控制在服务器日志中记录哪些导致错误条件的SQL语句。对于达到指定严重级别或更高级别的消息,其日志条目中会包含当前 SQL 语句。 有效值为DEBUG5DEBUG4DEBUG3DEBUG2DEBUG1、 @@ -5169,7 +5149,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -5207,7 +5187,7 @@ local0.* /var/log/postgresql - log_min_duration_statement的其他注释也适用于此设置。 + log_min_duration_statement的其他说明也适用于此设置。 @@ -5222,8 +5202,8 @@ local0.* /var/log/postgresql - 确定持续时间超过的语句的比例将被记录。 - 采样是随机的,例如0.5表示统计上有一半的机会任何给定的语句将被记录。 + 确定持续时间超过的语句中,将被记录的语句比例。 + 采样是随机的,例如0.5表示任意给定语句被记录的统计概率为二分之一。 默认值为1.0,表示记录所有采样的语句。 将此设置为零将禁用采样语句持续时间记录,与将log_min_duration_sample设置为-1相同。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -5241,7 +5221,7 @@ local0.* /var/log/postgresql - 设置所有语句都被记录的事务的比例,除了其他原因记录的语句。它适用于每个新事务,无论其语句的持续时间如何。 + 设置需要记录全部语句的事务比例,这些记录是在因其他原因记录的语句之外额外进行的。它适用于每个新事务,无论其语句的持续时间如何。 采样是随机的,例如0.1表示任何给定事务被记录的统计概率是十分之一。 log_transaction_sample_rate可以帮助构建事务样本。 默认值为0,表示不记录任何额外事务的语句。将其设置为1会记录所有事务的所有语句。 @@ -5266,8 +5246,7 @@ local0.* /var/log/postgresql - 设置启动进程在长时间运行的操作仍在进行时记录消息的时间间隔, - 以及该操作进一步进展消息之间的间隔时间。默认值为10秒。 + 设置启动进程在长时间运行的操作开始后,等待多久才记录第一条进度消息,以及此后该操作的进度消息之间的时间间隔。默认值为10秒。 设置为0会禁用该功能。如果未指定单位, 则将其视为毫秒。此设置分别应用于每个操作。 此参数只能在postgresql.conf文件或服务器命令行中设置。 @@ -5309,7 +5288,7 @@ local0.* /var/log/postgresql DEBUG1 .. DEBUG5 - 为开发者提供连续的更详细的信息。 + 为开发者提供逐级更加详细的信息。 DEBUG INFORMATION @@ -5369,7 +5348,7 @@ local0.* /var/log/postgresql - 记录什么到日志 + 记录哪些内容 @@ -5390,7 +5369,7 @@ local0.* /var/log/postgresql - application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。它也会被通过包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为C 风格的十六进制转义序列。 + application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。也可以通过将其包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为C 风格的十六进制转义序列。 @@ -5417,7 +5396,6 @@ local0.* /var/log/postgresql - 这个参数启用发出各种调试输出。当设置时,会打印生成的解析树, 查询重写输出,或执行的每个查询的执行计划。这些信息是在LOG 信息级别发出,因此默认的,它们会出现在服务器日志中,但不会发送给客户端。 可以通过 client_min_messages和/或log_min_messages 来设置。这些参数缺省是off。 这些参数将会让多种调试输出被发出。当被设置时,它们为每一个被执行的查询打印结果分析树、查询重写器输出或执行计划。这些消息在LOG消息级别上被发出,因此默认情况下它们将出现在服务器日志中但不会被发送到客户端。你可以通过调整和/或来改变这种情况。这些参数默认是关闭的。 @@ -5451,10 +5429,10 @@ local0.* /var/log/postgresql - 每次由自动清理执行的操作都会被记录,如果运行时间至少达到指定时间。将此设置为零会记录所有自动清理操作。 + 当自动清理执行的操作运行时间至少达到指定时间时,就会记录该操作。将此设置为零会记录所有自动清理操作。 -1会禁用记录自动清理操作。如果未指定单位,则将其视为毫秒。 例如,如果将其设置为250ms,则所有运行时间为250ms或更长的自动清理和分析都将被记录。 - 此外,当此参数设置为任何值而不是-1时,如果由于冲突的锁定或同时删除的关系而跳过自动清理操作,则会记录消息。 + 此外,当此参数设置为任何非-1值时,如果由于冲突锁或关系被并发删除而跳过自动清理操作,则会记录消息。 默认值为10min。启用此参数可帮助跟踪自动清理活动。 此参数只能在postgresql.conf文件或服务器命令行中设置;但可以通过更改表存储参数来覆盖对单个表的设置。 @@ -5533,7 +5511,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -5556,7 +5534,7 @@ local0.* /var/log/postgresql 控制在服务器日志中记录的每条消息的详细程度。有效值为TERSE, - DEFAULTVERBOSE,每个值都会添加更多字段到显示的消息中。 + DEFAULTVERBOSE,它们依次在显示的消息中增加更多字段。 TERSE不包括DETAILHINTQUERYCONTEXT错误信息的记录。 VERBOSE输出包括SQLSTATE错误代码 @@ -5576,7 +5554,7 @@ local0.* /var/log/postgresql - 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致很微小的性能损失。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致不可忽视的性能开销。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -5595,7 +5573,7 @@ local0.* /var/log/postgresql %字符开始转义序列,它将被按照下文描述的替换成状态信息。 未识别的转义被忽略。其他字符被直接复制到日志行。某些转义只被会话进程识别并且被主服务器进程等后台进程当作空。 通过指定一个在%之后和该选项之前的数字可以让状态信息左对齐或右对齐。 - 负值将导致在右边用空格填充状态信息已达到最小宽度,而正值则在左边填充。填充对于日志文件的人类可读性大有帮助。 + 负值将导致在右边用空格填充状态信息以达到最小宽度,而正值则在左边填充。填充对于日志文件的人类可读性大有帮助。 @@ -5658,8 +5636,8 @@ local0.* /var/log/postgresql %P - 并行组leader的进程ID,如果该进程是一个并行查询worker - no + 如果该进程是并行查询工作进程,则为并行组领导者的进程 ID + @@ -5676,8 +5654,8 @@ local0.* /var/log/postgresql %n - 带毫秒的时间戳(作为 Unix 时代) - no + 带毫秒精度的 Unix 时间戳 + @@ -5732,7 +5710,7 @@ local0.* /var/log/postgresql %Q 当前查询的查询标识符。 查询标识符默认是不计算的,所以这个部分将是零,除非 参数被激活或者配置了计算查询标识符的第三方模块 - yes + @@ -5751,7 +5729,7 @@ local0.* /var/log/postgresql %c转义打印一个准唯一的会话标识符,它由两个 4 字节的十六进制数(不带先导零)组成,以点号分隔。 - 这些数字是进程启动时间和进程 ID,因此%c也可以被用作保存打印这些项的方式的空间。 + 这些数字是进程启动时间和进程 ID,因此%c也可以用来节省空间地输出这两项信息。 例如,要从pg_stat_activity生成会话标识符,使用这个查询: SELECT to_hex(trunc(EXTRACT(EPOCH FROM backend_start))::integer) || '.' || @@ -5789,7 +5767,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 对于输出的行,%Q 总是报告零标识符, - 因为log_statement在标识符能被计算之前生成输出,包括无效标识符不能计算的无效语句。 + 因为log_statement在标识符能被计算之前生成输出,也包括无法计算标识符的无效语句。 @@ -5822,8 +5800,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 控制启动进程等待时间超过针对恢复冲突的deadlock_timeout的时候是否产生日志消息。 - 这对于决定恢复冲突是否会阻止恢复应用WAL有所帮助。 + 控制启动进程因恢复冲突而等待超过deadlock_timeout时是否产生日志消息。这有助于判断恢复冲突是否阻碍了恢复过程应用 WAL。 @@ -5851,8 +5828,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 此设置仅影响作为结果打印的日志消息,, 和相关的设置。 - 该设置的非零值会增加一些开销,特别是当参数以二进制形式发送时,因为需要转换为文本。 + 此设置仅影响由及相关设置产生的日志消息。此设置为非零值时会增加一些开销,特别是以二进制形式发送参数时,因为需要将参数转换为文本。 @@ -5896,7 +5872,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' UPDATEDELETETRUNCATE, 和COPY FROM。 如果PREPAREEXECUTE和 - EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个执行消息时会产生日志并且会包括绑定参数的值(任何内嵌的单引号会被双写)。 + EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个 Execute 消息时会产生日志并且会包括 Bind 参数的值(任何内嵌的单引号会被双写)。 @@ -5907,7 +5883,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在执行阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 + 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在 Execute 阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 @@ -5946,8 +5922,8 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 控制临时文件名和大小的日志记录。 - 临时文件可以用于排序、哈希和临时查询结果。 - 如果通过此设置启用,每当删除临时文件时都会发出日志记录。 + 临时文件可以用于排序、hash 和临时查询结果。 + 如果通过此设置启用,每当删除临时文件时都会发出日志记录,其中文件大小以字节为单位。 值为零时记录所有临时文件信息,而正值仅记录大小大于或等于指定数据量的文件。 如果未指定单位,则将其视为千字节。 默认设置为-1,禁用此类日志记录。 @@ -6000,7 +5976,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 错误上下文、 导致错误的用户查询(如果有且被log_min_error_statement启用)、 错误位置所在的字符计数、 - 在 PostgreSQL 源代码中错误的位置(如果log_error_verbosity被设置为verbose)以及应用名,后端类型,并行组leader的进程ID和查询ID。 + 在 PostgreSQL 源代码中错误的位置(如果log_error_verbosity被设置为verbose)、应用名、后端类型、并行组领导者的进程 ID 和查询 ID。 下面是一个定义用来存储 CSV 格式日志输出的样表: @@ -6052,7 +6028,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 设置log_filenamelog_rotation_age为你的日志文件提供一种一致的、可预测的命名空间。这让你预测文件名会是怎样以及知道什么时候一个个体日志文件完成并且因此准备好被导入。 + 设置log_filenamelog_rotation_age,为日志文件提供一致且可预测的命名方案。这样就能预测文件名,并知道单个日志文件何时已完成写入、可以导入。 @@ -6081,12 +6057,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 使用JSON格式的日志输出 - 包括jsonloglog_destination列表中提供了一种方便的方式将日志文件导入到许多不同的程序中。此选项以JSON格式发出日志行。 + 将jsonlog加入log_destination列表,可以方便地将日志文件导入多种不同的程序。此选项以JSON格式输出日志行。 - 字段值为null的字符串字段将被排除在输出之外。 - 未来可能会添加其他字段。处理jsonlog输出的用户应忽略未知字段。 + 值为空值的字符串字段不会输出。将来可能会添加其他字段。处理jsonlog输出的用户应用程序应忽略未知字段。 @@ -6231,13 +6206,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; statement string - 客户提供的查询字符串 + 客户端提供的查询字符串 cursor_position number - 查询字符串中的光标索引 + 查询字符串中的游标索引 @@ -6291,7 +6266,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 进程标题 - 这些设置控制服务器进程的进程标题如何被修改。进程标题通常可以用ps或者 Windows 上的进程浏览器等程序来查看。详见。 + 这些设置控制服务器进程的进程标题如何修改。通常可以通过ps等程序查看进程标题,在 Windows 上则可以使用Process Explorer。详情参见 @@ -6325,7 +6300,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 每次服务器接收到新的SQL命令时,都可以更新进程标题。 + 启用后,每次服务器接收到新的 SQL 命令时都会更新进程标题。 在大多数平台上,默认情况下此设置为on,但在Windows上默认为off, 因为该平台更新进程标题的开销较大。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -6363,7 +6338,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对每个会话当前执行命令的信息收集,包括其标识符和命令开始执行的时间。 - 此参数默认为开启状态。请注意,即使启用了此信息,只有超级用户、具有 + 此参数默认为开启状态。请注意,即使启用了此参数,只有超级用户、具有 pg_read_all_stats角色权限的角色和拥有被报告会话的用户 (包括属于他们具有权限的角色的会话)才能看到此信息,因此不应构成安全风险。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -6381,7 +6356,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 为每个活动会话指定存储当前执行命令的文本所保留的内存量,它们被用于pg_stat_activity.query域。 + 为每个活动会话指定存储当前执行命令的文本所预留的内存量,它们被用于pg_stat_activity.query字段。 如果指定值时没有单位,则以字节为单位。默认值是 1024字节。这个参数只能在服务器启动时被设置。 @@ -6398,7 +6373,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对数据库活动的统计信息收集。 - 此参数默认为开启,因为自动清理守护进程需要收集的信息。 + 此参数默认为开启,因为自动清理守护进程需要这些收集到的信息。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -6452,7 +6427,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用函数调用次数和时间的跟踪。指定pl以仅跟踪过程语言函数, + 启用函数调用次数和耗时的跟踪。指定pl以仅跟踪过程语言函数, all以同时跟踪SQL和C语言函数。默认值为none, 即禁用函数统计跟踪。只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -6487,7 +6462,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - none适用于监控系统。如果值只被访问一次,它是最有效的。 + none最适合监控系统。如果值只被访问一次,它是最有效的。 cache确保重复访问产生相同的值,这对涉及自连接的查询很重要。 snapshot在交互式检查统计信息时可能很有用,但开销较高, 特别是存在许多数据库对象时。 @@ -6514,21 +6489,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用查询标识符的内核计算。 - 查询标识符可以在 pg_stat_activity - 视图中显示,使用 EXPLAIN,或者如果通过 - 参数进行配置,则可以在日志中发出。 - 扩展还需要计算查询标识符。 - 请注意,如果内核查询标识符计算方法不可接受,也可以使用外部模块。 - 在这种情况下,必须始终禁用内核计算。 - 有效值为 off(始终禁用), - on(始终启用),auto, - 允许诸如 这样的模块 - 自动启用它,并且 regress 具有与 - auto 相同的效果,只是查询标识符不会显示在 - EXPLAIN 输出中,以便促进自动回归测试。 - 默认值为 auto。 + 启用内置的查询标识符计算功能。查询标识符可以显示在pg_stat_activity视图或EXPLAIN的输出中,也可以通过参数配置后写入日志。扩展也要求计算查询标识符。注意,如果内置的查询标识符计算方法不符合要求,可以改用外部模块。在这种情况下,必须始终禁用内置计算功能。有效值为off(始终禁用)、on(始终启用)、auto(允许等模块自动启用此功能),以及regress。后者与auto效果相同,但不会在EXPLAIN输出中显示查询标识符,以便进行自动回归测试。默认值为auto @@ -6568,7 +6529,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 对于每个查询,将各自模块的性能统计输出到服务器日志中。这是一个简单的性能分析工具,类似于Unix getrusage()操作系统功能。 - log_statement_stats报告总语句统计,而其他选项报告每个模块的统计信息。 + log_statement_stats报告整个语句的统计信息,而其他选项报告每个模块的统计信息。 log_statement_stats不能与任何单独模块选项一起启用。所有这些选项默认情况下都是禁用的。 只有超级用户和具有适当SET权限的用户才能更改这些设置。 @@ -6585,7 +6546,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 自动清理 - autovacuum + 自动清理 配置参数 @@ -6860,7 +6821,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; DEBUG1LOGNOTICEWARNINGERROR。 每个级别都包括其后的所有级别。级别越靠后,被发送的消息越少。默认值是NOTICE。 - 注意LOG在这里有与中不同的排名。 + 注意LOG在这里的排序与中的不同。 @@ -6880,15 +6841,15 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,用于进行搜索该对象的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 + 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,搜索该对象时的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 - search_path的值必需是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被安静地忽略。 + search_path的值必须是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被静默忽略。 - 如果列表项之一是特殊名$user,则具有SESSION_USER返回的名字的模式将取代它(如果有这样一个模式并且该用户有该模式的USAGE权限;如果没有,$user会被忽略)。 + 如果列表项之一是特殊名$user,则具有CURRENT_USER返回的名字的模式将取代它(如果有这样一个模式并且该用户有该模式的USAGE权限;如果没有,$user会被忽略)。 @@ -6913,11 +6874,12 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个参数的缺省值是"$user", public。这种设置支持一个数据库(其中没有用户拥有私有模式,并且所有人共享使用public)、每个用户私有模式及其组合的共享使用。其它效果可以通过全局或者针对每个用户修改默认搜索路径设置获得。 + 这个参数的默认值是"$user", public。这种设置支持共享使用数据库(用户没有私有模式,所有人共享使用public)、每个用户拥有私有模式,以及二者的组合。 + 还可以通过全局或针对每个用户修改默认搜索路径设置来获得其他效果。 - 更多有关方案处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 + 更多有关模式处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 @@ -6937,7 +6899,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,只要有至少一条策略被应用则查询就会失败。默认为on。受限的行可见性会导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS)属性的角色没有效果。 + 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,原本会应用至少一条策略的查询就会失败。默认为on。受限的行可见性可能导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS属性的角色)没有效果。 @@ -6956,8 +6918,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个参数指定了在创建表或物化视图时使用的默认表访问方法,如果CREATE命令没有明确指定访问方法, - 或者当使用SELECT ... INTO时,不允许指定表访问方法。默认值是heap。 + 创建表或物化视图时,如果CREATE命令没有显式指定访问方法,或者使用了不允许指定表访问方法的SELECT ... INTO,则使用此参数指定的默认表访问方法。默认值为heap @@ -6977,7 +6938,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建企图将失败。 + 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建尝试将失败。 @@ -6985,7 +6946,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当创建数据库时也会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 + 创建数据库时也不会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 @@ -7034,11 +6995,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被放置在里表中的连续表空间中。如果列表被选中元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 + 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被依次放置在列表中的连续表空间中。如果列表中被选中的元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 - 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,类似于为用户指定一个不具有CREATE权限的表空间。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特殊地,使用一个在postgresql.conf中设置的值时,这条规则起效。 + 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,指定一个用户不具有CREATE权限的表空间也同样是错误。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特别是,使用一个在postgresql.conf中设置的值时,这条规则起效。 @@ -7063,7 +7024,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 这个参数通常为打开。 当设置为off时,它禁用期间对例程体字符串的验证。 - 禁用验证避免了验证处理的副作用,特别避免了如向前引用导致的伪肯定。 + 禁用验证避免了验证处理的副作用,特别是避免前向引用等问题导致的误报。 在代表其他用户载入函数之前设置这个参数为offpg_dump会自动这样做。 @@ -7106,7 +7067,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态 。默认是off(读/写)。 + 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态。默认是off(读/写)。 @@ -7129,11 +7090,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当运行在可串行化隔离级别时,一个可延迟只读 SQL 事务可以在它被允许继续之前延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的负荷;因此串行化代码将没有任何理由因为并发更新而强制它中断,使得这个选项适合于长时间运行的只读事务。 + 当运行在serializable隔离级别时,一个可延迟只读 SQL 事务可能在获准继续之前被延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的开销;因此串行化代码将没有任何理由因为并发更新而强制它中止,使得这个选项适合于长时间运行的只读事务。 - 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些操作在低于可串行化隔离级别上的事务无效。默认值是off。 + 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些运行在低于serializable隔离级别上的事务无效。默认值是off @@ -7177,7 +7138,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的只读状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -7197,7 +7158,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的可延迟性状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -7221,7 +7182,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 这个设置的预期用途是由逻辑复制系统在应用所复制的更改时将它设置为replica。 - 其效果将是触发器和规则(没有对其默认配置做修改)在复制机上将不会被触发。 + 其效果将是触发器和规则(没有对其默认配置做修改)在副本上将不会被触发。 更多信息请参考ALTER TABLE的子句ENABLE TRIGGER以及ENABLE RULE @@ -7251,9 +7212,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 超时从命令到达服务器的时间开始计算,一直到它被服务器完成为止。 - 如果单个简单查询消息中出现多个 SQL 语句,超时将分别应用于每个语句。(PostgreSQL 13 之前的版本通常将超时应用于整个查询字符串。 - 在扩展查询协议中,当任何与查询相关的消息(解析、绑定、执行、描述)到达时,超时就开始运行,并且可以通过执行完成或同步消息来取消超时。 + 超时从命令到达服务器时开始计算,直到服务器完成该命令为止。 + 如果单个简单查询消息中出现多个 SQL 语句,超时将分别应用于每个语句。 + (PostgreSQL 13 之前的版本通常将超时应用于整个查询字符串。) + 在扩展查询协议中,当任何与查询相关的消息(Parse、Bind、Execute、Describe)到达时开始计时, + 并在处理完 Execute 或 Sync 消息时取消计时。 @@ -7272,13 +7235,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 如果任何语句在试图获取表、索引、行或其他数据库对象上的锁时等到超过指定的时间量,该语句将被中止。 + 如果任何语句在试图获取表、索引、行或其他数据库对象上的锁时等待超过指定的时间量,该语句将被中止。 该时间限制独立地应用于每一次锁获取尝试。该限制会应用到显式锁定请求(如LOCK TABLE或不带NOWAITSELECT FOR UPDATE)和隐式获得的锁。 如果指定值时没有单位,则以毫秒为单位。一个零值(默认)将禁用超时。 - 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为事务超时将总是第一个被触发。 + 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为语句超时将总是第一个被触发。 如果log_min_error_statement 被设置为ERROR 或更低,超时的语句将被记录。 @@ -7298,15 +7261,14 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 终止任何已经闲置(这是指,等待客户端查询)超过这个参数所指定时间量的打开事务的会话。 - 如果这个值指定时没有单位,它被设为毫秒。 - 零值(默认)禁用超时。 + 终止在打开的事务中空闲(即等待客户端查询)超过指定时长的任何会话。 + 如果指定值时不带单位,则以毫秒为单位。零值(默认值)禁用此超时。 - 此选项可以用于确保空闲会话不会在不合理的时间内持有锁。 - 即使没有持有重要的锁的时候,打开的事务也会防止清理最近死亡的可能只对这个事务可见的元组;所以长时间保持空闲会导致表膨胀。 - 详见。 + 此选项可确保空闲会话不会持有锁过长时间。 + 即使没有持有重要的锁,打开的事务也会阻止清理最近死亡、且可能只对该事务可见的元组;因此长时间空闲可能造成表膨胀。 + 更多详情参见 @@ -7321,9 +7283,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 终止任何空闲的会话(也就是,等待客户端查询),但不在打开的事务中,且超过指定的时间量。 - 如果指定值时不带单位,其单位采用毫秒。 - 零值时(默认)禁用超时。 + 终止不在打开的事务中、且空闲(即等待客户端查询)超过指定时长的任何会话。 + 如果指定值时不带单位,则以毫秒为单位。零值(默认值)禁用此超时。 @@ -7331,8 +7292,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 注意不要对通过连接池软件或其他中间件建立的连接强制执行此超时,因为这样的层可能不会很好地响应意外的连接关闭。 - 只对交互会话启用此超时可能是帮助的,也许只对特定用户应用它。 + 应谨慎对通过连接池软件或其他中间件建立的连接强制执行此超时,因为这样的层可能不会很好地响应意外的连接关闭。 + 只对交互会话启用此超时可能有所帮助,也许只对特定用户应用它。 @@ -7344,8 +7305,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; + - 当表的pg_class.relfrozenxid字段达到该设置指定的年龄时,VACUUM会执行激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值是 1.5 亿个事务。尽管用户可以将该值设置为 0 到 20 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的 95%,从而在触发防回卷 autovacuum 之前仍有机会执行一次常规手工VACUUM。更多信息请参见。 + 如果表的pg_class.relfrozenxid字段达到此设置指定的年龄,VACUUM就会执行一次激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值为 1.5 亿个事务。尽管用户可以将该值设置在 0 到 20 亿之间,VACUUM仍会悄悄将其有效值限制为不超过的 95%,以便在针对该表启动防回卷自动清理之前,周期性手工VACUUM仍有机会运行。详见 @@ -7357,8 +7319,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; + - 指定VACUUM用来决定是否触发对含有较旧 XID 的页面进行冻结的截止年龄(以事务计)。默认值是 5000 万个事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见。 + 指定VACUUM在决定是否冻结带有较旧 XID 的页面时应采用的截止年龄(以事务数计)。默认值为 5000 万个事务。尽管用户可以将该值设置在 0 到 10 亿之间,VACUUM仍会悄悄将其有效值限制为不超过的一半,以避免强制自动清理之间的间隔过短。详见 @@ -7370,17 +7333,15 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; + - 指定表的pg_class.relfrozenxid字段在VACUUM采取特别措施以避免系统范围事务 ID 回卷失败之前所允许达到的最大年龄(以事务计)。这是VACUUM的最后防线。失效保护通常会在防止事务 ID 回卷的 autovacuum 已经运行了一段时间后触发,但也有可能在任何VACUUM期间触发。 + 指定表的pg_class.relfrozenxid字段在VACUUM采取非常措施以避免系统范围事务 ID 回卷失败之前所允许达到的最大年龄(以事务数计)。这是VACUUM的最后手段。失效保护通常会在为防止事务 ID 回卷而启动的自动清理已经运行一段时间后触发,但也可能在任何一次VACUUM期间触发。 - 当失效保护被触发时,将不再应用任何有效的基于代价的延迟,并且会跳过进一步的非关键维护任务(例如索引清理),而且任何正在使用的 - 缓冲区访问策略 - 都会被禁用,使 VACUUM 可以自由使用全部 - 共享缓冲区。 + 当触发失效保护时,当前生效的任何基于代价的延迟都将不再应用,进一步的非关键维护任务(例如索引清理)会被跳过,并且正在使用的任何缓冲区访问策略都会被禁用,从而使VACUUM可以自由使用全部共享缓冲区 - 默认值为 16 亿个事务。尽管用户可以将该值设置为 0 到 21 亿之间的任意值,VACUUM会悄悄将有效值调整为不低于的 105%。 + 默认值为 16 亿个事务。尽管用户可以将该值设置在 0 到 21 亿之间,VACUUM仍会悄悄将其有效值调整为不低于的 105%。 @@ -7392,8 +7353,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; + - 当表的pg_class.relminmxid字段达到该设置指定的年龄时,VACUUM会执行激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不是只扫描那些可能包含死元组的页面。默认值是 1.5 亿个多事务。尽管用户可以将该值设置为 0 到 20 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的 95%,从而在触发防回卷 autovacuum 之前仍有机会执行一次常规手工VACUUM。更多信息请参见。 + 如果表的pg_class.relminmxid字段达到此设置指定的年龄,VACUUM就会执行一次激进扫描。激进扫描与常规VACUUM不同,它会访问每一个可能包含未冻结 XID 或 MXID 的页面,而不仅仅是那些可能包含死元组的页面。默认值为 1.5 亿个多事务。尽管用户可以将该值设置在 0 到 20 亿之间,VACUUM仍会悄悄将其有效值限制为不超过的 95%,以便在针对该表启动防回卷清理之前,周期性手工VACUUM仍有机会运行。详见 @@ -7405,8 +7367,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; + - 指定VACUUM用来决定是否触发对含有较旧多事务 ID 的页面进行冻结的截止年龄(以多事务计)。默认值是 500 万个多事务。尽管用户可以将该值设置为 0 到 10 亿之间的任意值,VACUUM会悄悄将有效值限制为不超过的一半,这样强制 autovacuum 之间就不会间隔过短。更多信息请参见。 + 指定VACUUM在决定是否冻结带有较旧多事务 ID 的页面时应采用的截止年龄(以多事务计)。默认值为 500 万个多事务。尽管用户可以将该值设置在 0 到 10 亿之间,VACUUM仍会悄悄将其有效值限制为不超过的一半,以避免强制自动清理之间的间隔过短。详见 @@ -7459,7 +7422,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这里的实际选择都是根据爱好做出的,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码将比 base64 编码更大。 + 这里的实际选择主要取决于偏好,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码会比 base64 编码略大。 @@ -7480,7 +7443,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当在XML和字符串值之间进行转换时,无论设置DOCUMENT或 CONTENT都是隐式的。可参阅Section 8.13。 有效值是DOCUMENT和CONTENT。 缺省值是CONTENT。当在 XML 和字符串值之间进行转换时,设置DOCUMENTCONTENT都是隐式的。详见。有效值是DOCUMENTCONTENT。默认值是CONTENT。 + 设置在 XML 与字符串值之间进行转换时,隐含采用DOCUMENT还是CONTENT。 + 有关说明参见。有效值是DOCUMENTCONTENT。默认值是CONTENT @@ -7515,7 +7479,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; createrole_self_grant (string) - createrole_self_grant配置参数 + createrole_self_grant + 配置参数 @@ -7524,9 +7489,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 该值必须是setinherit或它们的逗号分隔列表。默认值为空字符串,这会禁用此功能。 - 此选项的目的是允许非超级用户的CREATEROLE用户自动继承或自动获得对新创建角色执行SET ROLE的能力。 + 此选项的目的是允许非超级用户的CREATEROLE用户自动继承所创建用户的权限,或自动获得对这些用户执行SET ROLE的能力。 由于CREATEROLE用户始终会隐式获得其所创建角色的ADMIN OPTION,因此该用户总是可以通过执行GRANT语句达到相同效果,但自动授予在可用性上更方便。 - 超级用户会自动继承每个角色的权限,并且始终可以切换到任何角色;此设置可让CREATEROLE用户对其创建的用户获得类似的行为。 + 超级用户会自动继承每个角色的权限,并且始终可以对任何角色执行SET ROLE;此设置可让CREATEROLE用户对其创建的用户获得类似的行为。 @@ -7534,7 +7499,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; restrict_nonsystem_relation_kind (string) - restrict_nonsystem_relation_kind配置参数 + restrict_nonsystem_relation_kind + 配置参数 @@ -7549,7 +7515,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 区域和格式化 + 区域设置和格式化 @@ -7563,7 +7529,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域行为的设置初始化配置文件。 + 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域设置行为的设置初始化配置文件。 @@ -7578,11 +7544,14 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置间隔值的显示格式。值sql_standard将产生匹配 SQL 标准间隔文本的输出。当参数被设置为ISO时,值postgres(默认)将产生匹配PostgreSQL发行 8.4 之前的输出。当DateStyle参数被设置为非ISO输出时,值postgres_verbose会产生匹配PostgreSQL发行 8.4 之前的输出。值iso_8601会产生匹配在 ISO 8601 的 4.4.3.2 节中定义的带标志符格式的时间间隔的输出。 + 设置时间间隔值的显示格式。值sql_standard会生成符合SQL标准时间间隔字面量的输出。 + 值postgres(默认值)的输出与PostgreSQL 8.4 之前版本中设为ISO时的输出一致。 + 值postgres_verbose的输出与PostgreSQL 8.4 之前版本中DateStyle设为非ISO输出时的输出一致。 + 值iso_8601会生成符合 ISO 8601 第 4.4.3.2 节定义的时间间隔带标志符格式的输出。 - IntervalStyle参数也可以影响对有歧义的间隔输入的解释。详见。 + IntervalStyle参数也会影响对有歧义的时间间隔输入的解释。详见 @@ -7640,23 +7609,23 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 如果值为1(默认值)或更高,浮点值被输出为最短-精度格式;参见。 + 如果值为 1(默认值)或更高,浮点值被输出为最短精确格式;参见。 实际生成的位数只取决于输出的值,而不取决于此参数的值。 - float8 值最多需要 17 位数字,float4值最多需要9位数字。 + float8 值最多需要 17 位数字,float4值最多需要9位数字。 这种格式既快速又精确,在正确读取时精确地保留了原始的二进制浮点值。为了历史兼容性,允许的值最大为3。 如果值为零或负,则输出四舍五入为给定的十进制精度。 - 使用的精度是根据此参数的值减小的类型((FLT_DIGDBL_DIG,视情况而定)的标准位数。 + 所用精度以该类型的标准位数(根据类型使用FLT_DIGDBL_DIG)为基础,再按此参数的值减少。 (例如,指定 -1 将导致float4 值输出四舍五入为 5 位有效数字,而float8值四舍五入为 14 位。) - 此格式较慢,不会保留二进制浮点值的所有位,但可能令人更易于阅读。 + 此格式较慢,不会保留二进制浮点值的所有位,但可能更便于阅读。 此参数的含义,以及其默认值,在 PostgreSQL 12 中发生了变化; - 参见 以便进一步讨论。 + 参见 了解进一步讨论。 @@ -7692,7 +7661,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 在一些系统上,这个区域分类并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 + 在一些系统上,这个区域设置类别并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 @@ -7711,7 +7680,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化货币量的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化货币量的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -7726,7 +7695,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化数字的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化数字的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -7741,7 +7710,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化日期和时间的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化日期和时间的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -7773,7 +7742,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 选择被那些没有显式参数指定配置的文本搜索函数变体使用的文本搜索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配区域的配置,initdb将用对应于选中的lc_ctype区域的设置初始化配置文件。 + 选择被那些没有显式参数指定配置的文本检索函数变体使用的文本检索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配该区域设置的配置,initdb将用对应于选中的lc_ctype区域设置的值初始化配置文件。 @@ -7788,7 +7757,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 为了载入附加的功能或者达到提高性能的目的,可用多个设置来预先载入共享库到服务器中。 - 例如'$libdir/mylib'设置可能会导致mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 + 例如'$libdir/mylib'设置会使mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 @@ -7797,12 +7766,12 @@ SET XML OPTION { DOCUMENT | CONTENT }; 只有特别为与PostgreSQL一起使用设计的共享库才能以这种方式载入。每一个PostgreSQL支持 - 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非PostgreSQL无法 + 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非 PostgreSQL 库无法 以这种方式被载入。你可能可以使用操作系统的工具(如LD_PRELOAD)载入它。 - 总之,请参考特定模块的文档来用推荐的方法载入它。 + 一般来说,请参考特定模块的文档来用推荐的方法载入它。 @@ -7836,9 +7805,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 这个特性的目的是允许非特权用户在特定的会话中载入正在调试的或者性能度量库, - 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客 - 户端的PGOPTIONS环境变量或者 + 这个特性的目的是允许非特权用户在特定的会话中载入用于调试或性能测量的库, + 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客户端的PGOPTIONS环境变量或者 ALTER ROLE SET来设置这个参数。 @@ -7876,7 +7844,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 不同,相对于在库被第一次使用 - 时载入它,在会话开始时载入库并没有什么性能优势。不过,当使用连接池时这样做还是有一些 + 时载入它,在会话开始时载入库并没有明显的性能优势。不过,当使用连接池时这样做还是有一些 优势。 @@ -7916,9 +7884,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 在 Windows 主机上,在服务器启动时预载入一个库并不会减少启动每个新服务器进程所需的 - 时间;每一个服务器进程将会重新载入预载入的库。不过,对于那些要在postmaster启动时 + 时间;每一个服务器进程将会重新载入所有预载入的库。不过,对于那些要在postmaster启动时 执行操作的库来说,Windows 主机上的 - shared_preload_libraries任然有用。 + shared_preload_libraries仍然有用。 @@ -7966,13 +7934,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 如果需要打开一个可以动态装载的模块并且在CREATE FUNCTIONLOAD命令中指定的文件名没有目录部分(即名字中不包含斜线),那么系统将搜索这个路径以查找所需的文件。 - - dynamic_library_path的值必须是一个冒号分隔(或者在 Windows 上以分号分隔)的绝对目录路径的列表。如果一个列表元素以特殊字符串开始,$libdir会被替换为PostgreSQL包中已编译好的库目录。这里是PostgreSQL发布提供的模块被安装的位置(使用pg_config --pkglibdir来找到这个目录的名字)。例如: - + 参数dynamic_library_path的值必须是由冒号(Windows上为分号)分隔的绝对目录路径列表。如果某个列表元素以特殊字符串$libdir开头,则会使用编译时确定的PostgreSQL软件包的库目录来替换$libdir;该目录是标准PostgreSQL发行版所提供模块的安装位置。(使用pg_config --pkglibdir可以找出此目录的名称。)例如: dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir' - - 或者在 Windows 环境中: - +或者,在 Windows 环境中: dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' @@ -7999,7 +7963,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - GIN 索引返回的集合尺寸的软上限。详见。 + GIN 索引扫描返回的集合尺寸的软上限。详见 @@ -8032,18 +7996,18 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这是在锁上等待的时间,然后再检查是否存在死锁条件。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 + 指定在检查是否发生死锁之前等待锁的时间。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 我们乐观地假设在生产应用程序中死锁并不常见,所以在检查死锁之前只是等待一段时间。 增加此值会减少在不必要的死锁检查中浪费的时间,但会减慢实际死锁错误的报告速度。 如果未指定单位,则将其视为毫秒。 - 默认值为一秒(1s),这可能是您在实践中想要的最小值。 - 在负载较重的服务器上,您可能希望提高它。 - 理想情况下,设置应超过您的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 + 默认值为一秒(1s),这可能是你在实践中想要的最小值。 + 在负载较重的服务器上,你可能希望提高它。 + 理想情况下,设置应超过你的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 只有超级用户和具有适当SET权限的用户才能更改此设置。 - 当被设置时,这个参数还可以决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 + 当被设置时,这个参数也决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 @@ -8092,7 +8056,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制在谓词锁被提升为覆盖整个关系之前,该谓词锁能够在单个关系上锁住多少页面或元组。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个关系之前,可以对单个关系中的多少页面或元组加谓词锁。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -8107,7 +8071,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制在谓词锁被提升为覆盖整个页面之前,该谓词锁能在单一页面上锁住多少行。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个页面之前,可以对单个页面中的多少行加谓词锁。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -8135,7 +8099,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个空数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。对于那些要求旧行为的应用的向后兼容性,这个变量可以被设置为off。 + 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个值为空值的数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。为了向后兼容那些要求旧行为的应用,这个变量可以被设置为off @@ -8155,11 +8119,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制字符串文本中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\'。如果客户端代码没有做到正确转义,那么将会导致 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 + 这个参数控制字符串字面量中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\。如果客户端代码没有做到正确转义,那么就可能遭到 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 - 注意在符合标准的字符串文本中,\就表示\。这个参数只影响不符合标准的文本的处理,包括转义字符串语法(E'...')。 + 注意在符合标准的字符串字面量中,\就表示\。这个参数只影响不符合标准的字面量的处理,包括转义字符串语法(E'...')。 @@ -8175,11 +8139,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 打开时,如果在普通字符串文本中('...'语法)出现了 一个反斜线(\)并且standard_conforming_strings为关闭,那么就会发出一个警告。默认值是on。 + 打开时,如果在普通字符串字面量中('...'语法)出现了 一个反斜线(\)并且standard_conforming_strings为关闭,那么就会发出一个警告。默认值是on - 希望使用反斜线作为转义符的应用应该被修改来使用转义字符串语法(E'...'),因为在 SQL 标准中普通字符串的默认行为是将反斜线视作一个普通字符。这个变量可以被启用来帮助定位需要被更改的代码。 + 希望使用反斜线作为转义符的应用应该被修改来使用转义字符串语法(E'...'),因为按照 SQL 标准,普通字符串现在默认将反斜线视作一个普通字符。这个变量可以被启用来帮助定位需要被更改的代码。 @@ -8200,7 +8164,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 设置这个参数不会禁用所有与大对象相关的安全检查 — 除了那些在PostgreSQL 9.0中已经修改了的默认行为。 + 设置此变量不会禁用所有与大对象相关的安全检查 — 只禁用那些在PostgreSQL 9.0 中默认行为发生变化的检查。 @@ -8223,7 +8187,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' standard_conforming_strings (boolean) - 字符串标准符合 + 字符串符合标准 standard_conforming_strings配置参数 @@ -8231,7 +8195,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 控制普通字符串文本('...')是否按照 SQL 标准把反斜线当普通文本。从PostgreSQL 9.1 开始,默认值为on(之前的发行中默认值为off)。应用可以检查这个参数来判断字符串文本如何被处理。这个参数的存在也可以被当做转义字符串语法(E'...')被支持的标志。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 + 控制普通字符串字面量('...')是否按照 SQL 标准把反斜线当普通文本。从PostgreSQL 9.1 开始,默认值为on(之前的发行中默认值为off)。应用可以检查这个参数来判断字符串字面量如何被处理。这个参数的存在也可以被当做转义字符串语法(E'...')被支持的标志。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 @@ -8246,7 +8210,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询来,这样的扫描会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on。 + 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询,这样的扫描可能会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on @@ -8270,15 +8234,15 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr得出空值值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空(未知)。因此这个参数默认为off。 + 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr计算结果为空值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空值(未知)。因此这个参数默认为off - 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释)。它们不是非常有用并且在普通应用中也不常见,在应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及 空值的表达式的语义上感到困惑,因此这个选项默认为关闭。 + 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释),它们不是非常有用并且在普通应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及空值的表达式语义感到困惑,因此这个选项默认为关闭。 - 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不是劣质程序的一般修复。 + 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不能普遍修复错误的程序写法。 @@ -8322,7 +8286,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 当被设置为开(on),PostgreSQL将在一次后端崩溃后自动重新初始化。 + 当设置为 on(默认值)时,PostgreSQL将在一次后端崩溃后自动重新初始化。 让这个值设置为开(on)通常是将数据库可用性最大化的最佳方法。但是在某些环境中,例如PostgreSQL被集群软件调用时,禁用重启可能很有用,这样集群软件可以得到控制并且采取它认为适当的行动。 @@ -8342,7 +8306,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果设置为关(off),PostgreSQL在将修改的数据文件刷新到文件系统失败时,将引发PANIC级错误。 + 当设置为 off(默认值)时,PostgreSQL在将修改后的数据文件刷盘到文件系统失败时,将引发PANIC级错误。 这样会导致数据库服务器崩溃。这个参数只能在服务器启动时被设置。 @@ -8351,8 +8315,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果设置为开(on),PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷新操作。 - 仅在调查操作系统假如回写失败时对缓冲数据的处理方式的情况下,才将其设置为开(on)。 + 如果设置为开(on),PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷盘操作。 + 只有在调查清楚操作系统在回写失败时如何处理缓冲数据之后,才应将其设置为开(on)。 @@ -8369,14 +8333,14 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 当设置为fsync,也就是默认值,PostgreSQL将在崩溃恢复开始之前递归地打开并同步数据目录中的所有文件。 对文件的搜索将遵循WAL目录和每个配置表空间的符号链接(而不是任何其它符号链接)。 - 这是为了确保在重现更改之前,所有WAL和数据文件都持久地存储在硬盘上。 - 这适用于在启动没有完全关闭的数据库集簇时,包括由pg_basebackup创建的副本。 + 这是为了确保在重放更改之前,所有WAL和数据文件都持久地存储在磁盘上。 + 这适用于每次启动未正常关闭的数据库集簇时,包括由pg_basebackup创建的副本。 - 在Linux上,可以用syncfs代替,请求操作系统来同步包含数据目录的整个文件系统,WAL文件和每个表空间(但不是通过符号链接可访问到的任何其他文件系统)。 + 在Linux上,可以用syncfs代替,请求操作系统来同步数据目录、WAL 文件和各个表空间所在的整个文件系统(但不是通过符号链接可访问到的任何其他文件系统)。 这可能比fsync设置快得多,因为它不需要逐个打开每个文件。 - 另一方面,如果一个文件系统是被其他需要修改大量文件的应用程序共享的,它可能会慢一些,因为这些文件也将写入硬盘。 + 另一方面,如果一个文件系统是被其他需要修改大量文件的应用程序共享的,它可能会慢一些,因为这些文件也将写入磁盘。 此外,在5.8之前的Linux版本中,向磁盘写入数据时遇到的I/O错误可能不会报告给PostgreSQL,相关的错误消息可能只出现在内核日志中。 @@ -8395,11 +8359,10 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 预置选项 - 下列参数是只读的。 - 同样,它们被排除在postgresql.conf文件示例之外。 - 这些选项报告特定应用可能感兴趣的多种PostgreSQL行为,特别是管理前端相关的行为。 - 所有这些都是在PostgreSQL被编译或者它被安装时决定的。 - + 下列参数是只读的,因此未列入示例 postgresql.conf 文件。 + 这些选项报告 PostgreSQL 行为的各个方面,某些应用(特别是管理前端)可能对此感兴趣。 + 其中大多数参数在编译或安装 PostgreSQL 时确定。 + @@ -8428,7 +8391,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告对这个集簇是否启用了数据校验码。详见。 + 报告对这个集簇是否启用了数据校验和。详见 @@ -8443,7 +8406,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 在Unix系统上,这个参数报告启动时的数据目录(由定义)的权限。 + 在 Unix 系统上,这个参数报告服务器启动时数据目录(由定义)的权限。 (在Microsoft Windows上这个参数将总是显示0700。) 更多信息请参考 @@ -8479,7 +8442,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告PostgreSQL是否在编译时打开了 64 位整数日期和时间。从PostgreSQL 10起,这个值总是on。 + 报告PostgreSQL是否在编译时启用了对 64 位整数日期和时间的支持。从PostgreSQL 10起,这个值总是on @@ -8495,9 +8458,9 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 报告服务器当前是否处于热备模式。 - 当这个是on的时候,所有的事务强制为只读。 - 在会话中,这个只能在服务器提升为主库的时候变更。 - 更多信息参见 + 当此值为 on 时,所有事务都被强制为只读。 + 在会话中,此值只有在服务器被提升为主库时才会改变。 + 更多信息参见 @@ -8511,7 +8474,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定的。默认值是 100 个参数。 + 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定。默认值是 100 个参数。 @@ -8526,7 +8489,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64 ;因此max_identifier_length的默认值是 63,但是在使用多字节编码时可以少于 63 个字符。 + 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64;因此max_identifier_length的默认值是 63 字节,在使用多字节编码时,这可能不足 63 个字符。 @@ -8587,7 +8550,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告服务器版本数值。它是由编译服务器时的PG_VERSION值决定的。 + 报告服务器的版本号。它是由编译服务器时的PG_VERSION值决定的。 @@ -8602,7 +8565,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告服务器版本数值的整数值。它是由编译服务器时的PG_VERSION_NUM值决定的。 + 以整数形式报告服务器的版本号。它是由编译服务器时的PG_VERSION_NUM值决定的。 @@ -8617,7 +8580,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告主共享内存区域的大小,四舍五入到最接近的兆字节。 + 报告主共享内存区域的大小,向上取整到整数兆字节。 @@ -8654,8 +8617,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告此PostgreSQL服务器已构建的 SSL 库的名称(即使此实例当前未配置或使用 SSL), - 例如OpenSSL,或一个空字符串(如果没有)。 + 报告此PostgreSQL服务器在构建时使用的 SSL 库的名称(即使此实例当前未配置或使用 SSL), + 例如OpenSSL,如果没有使用 SSL 库,则报告空字符串。 @@ -8698,11 +8661,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 自定义选项 - 这个特性被设计用来由附加模块向PostgreSQL添加通常不为系统知道的参数(例如过程语言)。这允许使用标准方法配置扩展模块。 + 这个特性允许附加模块(例如过程语言)向PostgreSQL添加系统通常不认识的参数。这样便能以标准方式配置扩展模块。 - 自定义选项有两部分名称:一个扩展名,然后是一个句点,再然后是正确的参数名,就像 SQL 中的合格名称。一个示例是plpgsql.variable_conflict。 + 自定义选项的名称由两部分组成:扩展名称和参数名本身,中间用句点分隔,类似于 SQL 中的限定名。例如plpgsql.variable_conflict @@ -8710,7 +8673,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' PostgreSQL将接受任何两部分参数名称的设置。 这些变量被视为占位符,在定义它们的模块加载之前没有任何功能。 当加载扩展模块时,它将添加其变量定义并根据这些定义转换任何占位符值。 - 如果存在以其扩展名开头的任何未识别的占位符,将发出警告并删除这些占位符。 + 如果存在以其扩展名称开头的任何未识别的占位符,将发出警告并删除这些占位符。 @@ -8719,11 +8682,10 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 开发者选项 - 下面的参数目的是用在开发测试上, 并且永远不能用于生产数据库。 - 但是,它们中的一些能够用于帮助恢复严重损坏的数据库。 - 同样,它们被从示例postgresql.conf文件中排除。 - 请注意许多这些参数要求特殊的源代码编译标志才能工作。 - + 以下参数用于开发者测试,切勿用于生产数据库。不过,其中一些参数可用于辅助恢复严重损坏的数据库。 + 因此,它们未列入示例postgresql.conf文件。 + 请注意,许多参数需要特殊的源代码编译标志才能起作用。 + @@ -8736,7 +8698,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 允许将表空间创建为pg_tblspc内的目录,当CREATE TABLESPACE命令提供空位置字符串时。 + 当向CREATE TABLESPACE命令提供空的位置字符串时,允许将表空间创建为pg_tblspc内的目录。 这旨在允许测试主库和备库在同一台机器上运行的复制场景。这样的目录可能会混淆备份工具,因为这些工具期望在该位置只找到符号链接。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -8753,8 +8715,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 允许修改系统表的结构以及对系统表进行某些其他风险操作。即使对于超级用户,这也通常是不允许的。 - 不明智地使用此设置可能导致无法检索的数据丢失或严重损坏数据库系统。 + 允许修改系统表的结构以及对系统表进行某些其他风险操作。否则,即使超级用户也不允许执行这些操作。 + 不明智地使用此设置可能导致无法挽回的数据丢失或严重损坏数据库系统。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -8795,14 +8757,14 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 当设置为1时,每个系统目录缓存条目在第一个可能的机会时失效,不管任何使之无效的事情是否真的发生。 - 作为结果,系统目录的缓存被有效地禁用,因此服务器将运行得非常缓慢。 - 较高的值递归地运行缓存失效,这样会更慢,而且只用于测试缓存逻辑自身。 + 当设置为1时,每个系统目录缓存条目都会在最早可能的时刻被置为无效,无论是否真的发生了使其失效的事件。 + 这实际上禁用了系统目录缓存,因此服务器将运行得非常缓慢。 + 较高的值递归地运行缓存失效,这样会更慢,而且仅对测试缓存逻辑本身有用。 默认值0选择正常的目录缓存行为。 - 当试图触发涉及并发目录更改的难以复现的错误时,此参数非常有用,但除此之外它不太被需要。 + 当试图触发涉及并发目录更改的难以复现的错误时,此参数非常有用,但除此之外很少需要使用它。 详情请参见源码文件inval.cpg_config_manual.h @@ -8887,7 +8849,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据的时有用。这个参数在会话开始之后不能被更改。 + 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据时有用。这个参数在会话开始之后不能被更改。 @@ -8902,8 +8864,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 执行认证过程后启动新服务器进程时延迟的时间量。这是为了给开发者们一个机会在一个服务器进程上附加一个调试器。 - 如果指定值时没有单位,则以秒为单位。0值(默认值)禁用延迟。这个参数在会话开始之后不能被更改。 + 新服务器进程启动并完成认证过程之后的延迟时间。这旨在给开发者一个机会,用调试器附加到服务器进程上。 + 如果指定值时没有单位,则以秒为单位。零值(默认值)禁用延迟。这个参数在会话开始之后不能被更改。 @@ -8918,8 +8880,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 在新服务器进程分叉后,在进行认证过程之前,延迟的时间量。这是为了给开发者们一个机会在一个服务器进程上附加一个调试器来跟踪认证过程中的不当行为。 - 如果指定值时没有单位,则以秒为单位。0值(默认值)禁用延迟。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 新服务器进程刚刚派生之后、执行认证过程之前的延迟时间。这旨在给开发者一个机会,用调试器附加到服务器进程上,跟踪认证过程中的异常行为。 + 如果指定值时没有单位,则以秒为单位。零值(默认值)禁用延迟。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -8934,7 +8896,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 + 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 @@ -8966,7 +8928,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果打开,发出在排序操作中的资源使用的相关信息。只有在编译PostgreSQL时定义了TRACE_SORT宏, 这个参数才可用(不过,当前在默认情况下就定义了TRACE_SORT)。 + 如果开启,输出排序操作中的资源使用信息。只有在编译PostgreSQL时定义了TRACE_SORT宏, 这个参数才可用(不过,当前在默认情况下就定义了TRACE_SORT)。 @@ -8981,7 +8943,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。对每一种锁类型,已授权锁和等待锁的计数也会被一起转储。一个日志文件输出的示例如下: + 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。还会转储每种锁类型已授予的锁数、等待的锁数,以及它们的总数。一个日志文件输出的示例如下: LOG: LockAcquire: new: lock(0xb7acd844) id(24688,24696,0,0,0,1) grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0 @@ -9053,7 +9015,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果设置,不会跟踪小于这个 OID 的锁(用于避免在系统表上的输出)。 + 如果设置,不会跟踪 OID 小于此值的表上的锁(用于避免在系统表上的输出)。 @@ -9129,7 +9091,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,被修改的任何缓冲区的整页镜像及其WAL记录都被加入到记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 + 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,与该 WAL 记录相关的所有已修改缓冲区的整页镜像都会被添加到该记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 @@ -9173,10 +9135,10 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 在读取过程中检测到校验和失败通常会导致PostgreSQL报告错误,中止当前事务。 - 将ignore_checksum_failure设置为on会导致系统忽略失败(但仍然报告警告),并继续处理。 - 这种行为可能导致崩溃,传播或隐藏损坏,或其他严重问题。然而,它可能允许您跳过错误, - 并检索可能仍然存在于表中的未损坏的元组,如果块头仍然正常。如果头部损坏,即使启用此选项也会报告错误。 - 默认设置为off。 + 将ignore_checksum_failure设置为 on 会使系统忽略失败(但仍报告警告),并继续处理。 + 这种行为可能导致崩溃、传播或隐藏损坏,或引发其他严重问题。 + 但是,如果块首部仍然正常,它可能允许你跳过错误,检索表中可能仍然存在的未损坏元组。 + 如果首部损坏,即使启用此选项也会报告错误。默认设置为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -9194,7 +9156,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 检测到损坏的页面头通常会导致PostgreSQL报告错误,中止当前事务。 将zero_damaged_pages设置为on会导致系统报告警告,将内存中的损坏页面清零,并继续处理。 - 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许您跳过错误,并从表中可能存在的未损坏页面中检索行。 + 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许你跳过错误,并从表中可能存在的未损坏页面中检索行。 如果由于硬件或软件错误而发生损坏,这对于恢复数据很有用。通常在放弃从表的损坏页面恢复数据的希望之前,不应将其设置为on。 清零的页面不会强制写入磁盘,因此建议在再次关闭此参数之前重新创建表或索引。默认设置为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -9214,9 +9176,9 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 如果设置为 off(默认值),则在恢复期间检测到引用无效页面的 WAL 记录会导致 PostgreSQL 引发 PANIC 级别错误,中止恢复。 将ignore_invalid_pages设置为on会导致系统忽略 WAL 记录中的无效页面引用(但仍报告警告),并继续恢复。 - 此行为可能会导致崩溃、数据丢失、传播或隐藏腐败,或其他严重问题。 - 但是,它可能允许你通过 PANIC 级错误,完成恢复,并启动服务器。 - 参数只能在服务器启动时设置。它仅在恢复期间或待机模式下生效。 + 此行为可能会导致崩溃、数据丢失、传播或隐藏损坏,或其他严重问题。 + 但是,它可能允许你跳过 PANIC 级错误,完成恢复,并启动服务器。 + 参数只能在服务器启动时设置。它仅在恢复期间或备库模式下生效。 @@ -9231,7 +9193,8 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果LLVM有所需要的功能,用GDB注册所生成的函数。这会让调试更加容易。默认设置是off。只有超级用户和具有适当SET权限的用户可以在会话开始时更改这个参数,并且在会话内完全不能更改它。 + 如果 LLVM 具有所需的功能,则向GDB注册生成的函数。 + 这会让调试更加容易。默认设置为off。只有超级用户和具有适当SET权限的用户才能在会话开始时更改此参数,并且在会话内完全不能更改它。 @@ -9247,7 +9210,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 将生成的LLVM IR写入文件系统,位于内。 - 这仅对于在JIT实现内部工作时有用。默认设置为off。 + 这仅对开发 JIT 的内部实现有用。默认设置为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -9278,10 +9241,9 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果LLVM有所需的功能,发出需要的数据以允许perf对JIT生成的函数画像。 - 这会写出文件到~/.debug/jit/中,如果需要,由用户负责对其执行清除。 - 默认设置是off。 - 只有超级用户和具有适当SET权限的用户可以在会话开始时更改这个参数,并且在会话内完全不能更改它。 + 如果 LLVM 具有所需的功能,则输出让perf对 JIT 生成的函数进行性能分析所需的数据。 + 这会将文件写入~/.debug/jit/;用户应在需要时自行清理。 + 默认设置为off。只有超级用户和具有适当SET权限的用户才能在会话开始时更改此参数,并且在会话内完全不能更改它。 @@ -9311,8 +9273,8 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 当设置为on时,这是默认值,PostgreSQL将在后端崩溃后自动删除临时文件。 - 如果禁用,文件将被保留,并且也许可用于调试,例如。 + 当设置为on(默认值)时,PostgreSQL将在后端崩溃后自动删除临时文件。 + 如果禁用,文件将被保留,例如可用于调试。 重复的崩溃可能会导致无用文件的积累。 该参数只能在postgresql.conf文件中或服务器命令行中设置。 @@ -9364,23 +9326,23 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 允许值为bufferedimmediate。默认值为buffered。 这个参数旨在用于测试逻辑解码以及大型事务的复制。 - debug_logical_replication_streaming对发布端和订阅端的影响不同。 + debug_logical_replication_streaming对发布者和订阅者的影响不同。 - 在发布端,debug_logical_replication_streaming允许在逻辑解码中立即流式传输或序列化更改。 + 在发布者端,debug_logical_replication_streaming允许在逻辑解码中立即流式传输或序列化更改。 当设置为immediate时,如果 - streaming选项在 + streaming选项在 CREATE SUBSCRIPTION中已启用, 则每条更改都会被流式传输;否则会序列化每条更改。设置为buffered时, 会在达到logical_decoding_work_mem后再流式传输或序列化更改。 - 在订阅端,如果streaming选项被设置为parallel, - 则debug_logical_replication_streaming可用于控制主应用工作进程是将更改发送到共享内存队列, - 还是将所有更改序列化到文件。设置为buffered时,主进程通过共享内存队列将更改发送给并行应用工作进程。 - 设置为immediate时,主进程会将所有更改序列化到文件,并通知并行应用工作进程在事务结束时读取并应用这些更改。 + 在订阅者端,如果streaming选项被设置为parallel, + 则debug_logical_replication_streaming可用于控制领导者应用工作进程是将更改发送到共享内存队列, + 还是将所有更改序列化到文件。设置为buffered时,领导者通过共享内存队列将更改发送给并行应用工作进程。 + 设置为immediate时,领导者会将所有更改序列化到文件,并通知并行应用工作进程在事务结束时读取并应用这些更改。 @@ -9392,12 +9354,12 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 短选项 - 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,并且它们作为一个单字母选项存在并不表示它们会被大量使用。 + 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,它们以单字母选项的形式存在,并不一定表示鼓励频繁使用这些选项。
- 短选项键 + 短选项对照 diff --git a/zh/16/datatype.sgml b/zh/16/datatype.sgml index 31e349dd..9e970bf7 100644 --- a/zh/16/datatype.sgml +++ b/zh/16/datatype.sgml @@ -151,7 +151,7 @@ line - 平面上的无限长的线 + 平面上的无限直线 @@ -163,19 +163,19 @@ macaddr - MAC(Media Access Control)地址 + MAC(媒体访问控制)地址 macaddr8 - MAC(Media Access Control)地址(EUI-64格式) + MAC(媒体访问控制)地址(EUI-64格式) money - 货币数量 + 货币额 @@ -183,7 +183,7 @@ s) ] decimal [ (p, s) ] - 可选择精度的精确数字 + 可选择精度的精确数值 @@ -195,7 +195,7 @@ pg_lsn - PostgreSQL日志序列号类型 + PostgreSQL 日志序列号 @@ -273,13 +273,13 @@ tsquery - 文本搜索查询 + 文本检索查询 tsvector - 文本搜索文档 + 文本检索文档 @@ -420,14 +420,14 @@
- 数字类型常量的语法在里描述。数字类型有一整套对应的数学操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 + 数字类型常量的语法在里描述。数字类型有一整套对应的算术操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 整数类型 - 整数 + integer @@ -440,7 +440,7 @@ int4 - 整数 + integer @@ -460,11 +460,11 @@
- 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。而只有在integer的范围不够的时候才使用bigint。 + 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。bigint则设计用于integer的范围不够的情况。 - SQL只声明了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在许多其它SQL数据库系统中使用。 + SQL只规定了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在某些其他SQL数据库系统中使用。 @@ -473,11 +473,11 @@ 任意精度数值 - 数字(数据类型) + numeric(数据类型) - 任意精度数字 + 任意精度数值 @@ -578,18 +578,18 @@ NUMERIC(3, 5)
- infinity - numeric (数据类型) + 无穷大 + numeric(数据类型) NaN - 非数字 + 非数 - 非数字 - 数字(数据类型) + 非数 + numeric(数据类型) @@ -676,7 +676,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 双精度 + double precision @@ -686,7 +686,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; float8 - 双精度 + double precision @@ -739,8 +739,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; 默认情况下,浮点值会以最短且精确的十进制表示形式输出; - 生成的十进制值比同一二进制精度下任何其他可表示值都更接近真实 - 存储的二进制值。(不过,为了避免输入例程普遍存在的一个错误, + 所生成的十进制值与实际存储的二进制值之间的距离,小于它与任何其他可用相同二进制精度表示的值之间的距离。(不过,为了避免输入例程普遍存在的一个错误, 即未能正确遵守舍入到最近偶数规则,当前输出值绝不会 恰好位于两个可表示值的正中间。) 对于float8值,最多使用 17 位有效十进制数字; @@ -749,14 +748,14 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 生成这种最短且精确的输出格式,比历史上的圆整格式要快得多。 + 生成这种最短且精确的输出格式,比历史上的舍入格式要快得多。 为了兼容旧版本PostgreSQL生成的输出, 并允许降低输出精度,可以使用 - 参数改为选择圆整后的 + 参数改为选择舍入后的 十进制输出。将该参数设置为 0 会恢复之前的默认行为,也就是把值 舍入为 6 位(对于float4)或 15 位 (对于float8)有效十进制数字。设置为负值会 @@ -770,7 +769,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 过去那些需要精确值的应用,往往必须把 + 过去那些需要精确值的应用,必须把 设置为 3 才能获得它们。 为了在版本之间获得最大兼容性,这类应用应继续这样做。 @@ -778,12 +777,12 @@ FROM generate_series(-3.5, 3.5, 1) as x; 无穷大 - 浮点型 + 浮点 - 非数字 - 浮点型 + 非数 + 浮点 @@ -855,13 +854,13 @@ FROM generate_series(-3.5, 3.5, 1) as x; - auto-increment + 自动递增 serial - sequence - and serial type + 序列 + 与 serial 类型 @@ -914,7 +913,7 @@ ALTER SEQUENCE tablename_ - 要向 serial 列插入序列中的下一个值,应指定让该列 + 要向 serial 列插入序列中的下一个值,应指定让serial列 使用其默认值。这既可以通过在 INSERT 语句的 列表中省略该列来实现,也可以通过使用 DEFAULT 关键字来实现。 @@ -990,7 +989,7 @@ ALTER SEQUENCE tablename_ SELECT '12.34'::float8::numeric::money; - 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有圆整错误。 + 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有舍入误差。 @@ -1002,7 +1001,7 @@ SELECT '52093.89'::money::numeric::float8; 一个 money 值除以一个整数值时,会朝零方向截去小数 - 部分。要得到圆整结果,可以除以一个浮点值,或者在除法前先把 + 部分。要得到舍入后的结果,可以除以一个浮点值,或者在除法前先把 money 转换为 numeric,再在除法后转换回 money(如果要避免精度丢失风险,后一种做法更好)。 当一个 money 值被另一个 money 值除时, @@ -1021,12 +1020,12 @@ SELECT '52093.89'::money::numeric::float8; - string + 字符串 - 字符 + character @@ -1065,11 +1064,11 @@ SELECT '52093.89'::money::numeric::float8; character(n), char(n), bpchar(n) - 定长,空白填充 + 定长,空格填充 bpchar - 无限长度的变长,忽略尾随空白 + 无限长度的变长,忽略尾随空格 text @@ -1128,7 +1127,7 @@ SELECT '52093.89'::money::numeric::float8; 超过 10,485,760。若 character varying (或 varchar)没有长度说明,则该类型接受任意长度 的字符串。若 bpchar 没有长度说明,它也接受任意 - 长度的字符串,但尾随空白在语义上不重要。若 + 长度的字符串,但尾随空格在语义上不重要。若 character(或 char)缺少长度说明, 则等同于 character(1) @@ -1150,7 +1149,7 @@ SELECT '52093.89'::money::numeric::float8;
- 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储代码为零的字符(有时称为NUL)。有关更多信息,请参阅。 + 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储编码值为零的字符(有时称为NUL)。有关更多信息,请参阅 @@ -1169,7 +1168,7 @@ SELECT '52093.89'::money::numeric::float8; - 这三种类型之间没有性能差别,除了使用空白填充类型时会占用更多存储 + 这三种类型之间没有性能差别,除了使用空格填充类型时会占用更多存储 空间,以及在写入带长度约束的列时需要少量额外 CPU 周期来检查长度。 虽然在某些其他数据库系统中,character(n) 可能有一定性能优势,但在 PostgreSQL @@ -1204,7 +1203,7 @@ INSERT INTO test2 VALUES ('ok'); INSERT INTO test2 VALUES ('good '); INSERT INTO test2 VALUES ('too long'); ERROR: value too long for type character varying(5) -INSERT INTO test2 VALUES ('too long'::varchar(5)); -- explicit truncation +INSERT INTO test2 VALUES ('too long'::varchar(5)); -- 显式截断 SELECT b, char_length(b) FROM test2; b | char_length @@ -1328,7 +1327,7 @@ SELECT b, char_length(b) FROM test2; 开头(以便与转义格式区分)。在某些上下文中,这个开头的反斜线 可能需要通过双写进行转义(见 )。作为输入时,十六进制数字 - 可以使用大写或小写,并且在两个数字组成的一组之间允许出现空白 + 可以使用大写或小写,并且每两个数字组成一组,组与组之间允许出现空白 (但组内以及起始的 \x 序列中不能有空白)。 十六进制格式与大量外部应用和协议兼容,并且通常比转义格式转换得 更快,因此更推荐使用。 @@ -1392,7 +1391,7 @@ SELECT '\xDEADBEEF'::bytea; 0 - 0字节 + 零值字节 '\000' '\000'::bytea \x00 @@ -1537,10 +1536,10 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; time - 不带时区的时间 + time without time zone - 带时区的时间 + time with time zone timestamp @@ -1549,13 +1548,13 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; timestamptz - 带时区的时间戳 + timestamp with time zone - 不带时区的时间戳 + timestamp without time zone - 间隔 + interval 时间跨度 @@ -1639,7 +1638,7 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; - SQL 要求仅写 timestamp 时,应等效于 + SQL 标准要求仅写 timestamp 时,应等效于 timestamp without time zone,而 PostgreSQL 也遵循这种行为。 timestamptz 被接受为 @@ -1720,7 +1719,7 @@ MINUTE TO SECOND 其中 p 是可选的精度说明,给出秒字段中 保留的小数位数。精度可用于 timetimestampinterval 类型, - 范围是 0 到 6。这与前文描述的取值一致。如果在常量声明中没有指定 + 范围是 0 到 6。如果在常量声明中没有指定 精度,则默认采用该字面值本身的精度(但不超过 6 位)。 @@ -1749,7 +1748,7 @@ MINUTE TO SECOND 1999-01-08 - ISO 8601; 任何模式下的1月8日 + ISO 8601; 任何模式下的1月8日 (推荐格式) @@ -1785,27 +1784,27 @@ MINUTE TO SECOND 99-Jan-08 - YMD模式中的1月8日,否则错误 + YMD模式中的1月8日,否则报错 08-Jan-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 Jan-08-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 19990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 1999.008 - 年和一年中的日子 + 年和一年中的第几天 J2451187 @@ -1827,10 +1826,10 @@ MINUTE TO SECOND time - 无时区的时间 + time without time zone - 带时区的时间 + time with time zone @@ -1909,11 +1908,11 @@ MINUTE TO SECOND 040506+0730 - ISO 8601,以分数小时形式给出 UTC 偏移 + ISO 8601,时区的 UTC 偏移不是整小时 040506+07:30:00 - UTC偏移量指定为秒(ISO 8601中不允许) + UTC 偏移精确到秒(ISO 8601中不允许) 04:05:06 PST @@ -1990,11 +1989,11 @@ MINUTE TO SECOND - 带时区的时间戳 + timestamp with time zone - 无时区的时间戳 + timestamp without time zone @@ -2019,29 +2018,12 @@ January 8 04:05:06 1999 PST 也被支持。 - - SQL 标准通过时间后面是否带有 - +- 符号以及时区偏移,来区分 - timestamp without time zone 和 - timestamp with time zone 常量。因此,根据标准, - - + 按照SQL标准,timestamp without time zonetimestamp with time zone字面量的区别在于,时间后是否有+-符号及其后的时区偏移。因此,按照该标准, TIMESTAMP '2004-10-19 10:23:54' - - - 属于 timestamp without time zone,而 - - +timestamp without time zone,而 TIMESTAMP '2004-10-19 10:23:54+02' - - - 属于 timestamp with time zone。 - PostgreSQL 在确定字符串类型之前从不检查 - 其内容,因此会把上述两个值都视为 - timestamp without time zone。要确保一个常量被视为 - timestamp with time zone,应为其指定正确的显式类型: - - +timestamp with time zone。 + PostgreSQL在确定字符串字面量的类型之前,从不检查其内容,因此会把上述两者都视为timestamp without time zone。为确保字面量被视为timestamp with time zone,应为它显式指定正确类型: TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' @@ -2086,12 +2068,12 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' time - constants + 常量 date - constants + 常量 @@ -2123,12 +2105,12 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' infinity - date, timestamp, interval + date, timestamp 晚于所有其他时间戳 -infinity - date, timestamp, interval + date, timestamp 早于所有其他时间戳 @@ -2192,13 +2174,13 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' date 输出格式 - formatting + 格式化 time 输出格式 - formatting + 格式化 @@ -2231,7 +2213,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' ISO - ISO 8601, SQL标准 + ISO 8601,SQL 标准 1997-12-17 07:37:16-08 @@ -2262,7 +2244,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' - SQL和POSTGRES风格中,如果DMY域顺序被指定,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。 + SQL和POSTGRES风格中,如果指定了 DMY 字段顺序,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。 @@ -2310,10 +2292,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 时区有通用的字母缩写,就会显示该缩写;否则会以 ISO 8601 基本 格式的有符号数字偏移显示 (hh 或 - hhmm)。这些样式中显示的字母缩写, - 取自当前由 运行时参数选中的 IANA - 时区数据库条目;它们不受 - 设置影响。 + hhmm)。 @@ -2332,7 +2311,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 时区 - time zone + 时区 @@ -2417,8 +2396,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 除了时区名称和缩写之外, PostgreSQL 还接受 POSIX 风格的 时区说明,见 。 - 这个选项通常不如使用具名时区更合适,但如果没有可用的 IANA - 时区条目,它可能就是必需的。 + 这个选项通常不如使用具名时区更合适,但如果没有合适的 IANA 时区条目可用,它可能就是必需的。 @@ -2433,14 +2411,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 中午(UTC-5),无论当天名义上是否正在实行夏令时。 - - - POSIX 风格时区说明中的符号,其含义与 ISO 8601 日期时间值中的 - 符号正好相反。例如,与 - 2014-06-04 12:00+04 对应的 POSIX 风格时区写法 - 会是 UTC-4。 - - + 更复杂的是,一些司法辖区在不同时间使用同一时区缩写来表示不同的 @@ -2461,7 +2432,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 时区名称和缩写并不是硬编码在服务器中的;它们来自安装目录下 .../share/timezone/ 和 - .../share/timezonesets/ 子目录中的数据 + .../share/timezonesets/ 子目录中的配置文件 (见 )。 @@ -2499,13 +2470,13 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' - interval值可以使用下列语法书写: + interval值可以使用下列详细语法书写: @ quantity unit quantity unit... direction - 其中quantity是一个数字(很可能是有符号的); + 其中quantity是一个数字(可以带有符号); unitmicrosecondmillisecondsecondminutehourday、 @@ -2539,7 +2510,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' P quantity unit quantity unit ... T quantity unit ... 字符串必须以 P 开头,并且可以包含一个 - T 来引出一天中时间单位。可用的单位缩写见 + T 来引出一天中的时间单位。可用的单位缩写见 。单位可以省略, 也可以按任意顺序出现,但小于一天的单位必须出现在 T 之后。特别是,M 的含义 @@ -2578,7 +2549,7 @@ P quantity unit M - 分钟 (在时间部分中) + 分钟(在时间部分中) S @@ -2683,7 +2654,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; P1Y2M3DT4H5M6S - 带标志符的ISO 8601 格式:含义同上 + ISO 8601 带标志符的格式:含义同上 P0001-02-03T04:05:06 @@ -2701,7 +2672,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; interval 输出格式 - formatting + 格式化 @@ -2750,7 +2721,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; iso_8601 风格的输出符合 ISO 8601 标准 - 4.4.3.2 节描述的带标志符格式。 + 4.4.3.2 节描述的带标志符的格式
@@ -2801,7 +2772,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; 布尔类型 - Boolean + 布尔 数据类型 @@ -2912,15 +2883,15 @@ SELECT * FROM test1 WHERE a; 数据类型 - enumerated (enum) + 枚举(enum) - enumerated types + 枚举类型 - 枚举(enum)类型是由一个静态、值的有序集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的日期,或者一个数据的状态值集合。 + 枚举(enum)类型是由一个静态的有序值集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的各天,或者一个数据的状态值集合。 @@ -3029,7 +3000,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 实现细节 - 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空格也是有意义的。 + 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空白也是有意义的。 @@ -3041,7 +3012,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 从内部枚举值到文本标签的翻译被保存在系统目录pg_enum中。可以直接查询该目录。 + 从内部枚举值到文本标签的转换关系被保存在系统目录pg_enum中。直接查询该目录可能会有所帮助。 @@ -3086,13 +3057,13 @@ SELECT person.name, holidays.num_weeks FROM person, holidays lseg32字节有限线段 - [(x1,y1),(x2,y2)] + ((x1,y1),(x2,y2)) box 32字节 矩形框 - (x1,y1),(x2,y2) + ((x1,y1),(x2,y2)) path @@ -3116,7 +3087,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays circle 24字节 - <(x,y),r>(中心点和半径) + <(x,y),r>(圆心和半径) @@ -3129,7 +3100,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 我们提供了丰富的函数和操作符来进行各种几何操作,例如缩放、平移、 - 旋转以及计算相交等,详见 。 + 旋转以及求交等,详见 @@ -3140,7 +3111,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 点是几何类型的基本二维构造块。用下面的语法描述point类型的值: + 点是几何类型的基本二维构造块。用下面任一种语法描述point类型的值: ( x , y ) @@ -3156,14 +3127,14 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线 + 直线 line - 线由线性方程Ax + By + C = 0 + 直线由线性方程Ax + By + C = 0 表示,其中AB不能同时为零。类型line 的值采用以下形式输入和输出: @@ -3183,7 +3154,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays (x1,y1)(x2,y2) - 是线上不同的两点。 + 是直线上不同的两点。 @@ -3199,7 +3170,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线段用一对线段的端点来表示。lseg类型的值用下面的语法声明: + 线段用一对线段的端点来表示。lseg类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ( x2 , y2 ) ] @@ -3223,15 +3194,15 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 方框 - box (data type) + box(数据类型) - rectangle + 矩形 - 方框用其对角的点对表示。box类型的值使用下面的语法指定: + 方框用其对角的点对表示。box类型的值使用下面任一种语法指定: ( ( x1 , y1 ) , ( x2 , y2 ) ) @@ -3250,7 +3221,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 在输入时可以提供任意两个对角,但是值将根据需要被按顺序记录为右上角和左下角。 + 在输入时可以提供任意两个对角,但是值将根据需要被重新排列,并依次存储为右上角和左下角。 @@ -3258,7 +3229,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 路径 - path (data type) + path(数据类型) @@ -3266,7 +3237,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - path类型的值用下面的语法声明: + path类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ... , ( xn , yn ) ] @@ -3276,11 +3247,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays x1 , y1 , ... , xn , yn - 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被忽略时,路径将被假定为封闭。 + 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被省略时,路径将被假定为封闭。 - 路径的输出使用第一种或第二种语法。 + 路径的输出视情况使用第一种或第二种语法。 @@ -3304,7 +3275,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - polygon类型的值用下列语法声明: + polygon类型的值用下列任一种语法指定: ( ( x1 , y1 ) , ... , ( xn , yn ) ) @@ -3329,7 +3300,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 圆由一个圆心和一个半径代表。circle类型的值用下面的语法指定: + 圆由一个圆心和一个半径代表。circle类型的值用下面任一种语法指定: < ( x , y ) , r > @@ -3352,7 +3323,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 网络地址类型 - network + 网络 数据类型 @@ -3409,8 +3380,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 在对 inetcidr 数据类型排序时,IPv4 - 地址总是排在 IPv6 地址之前,包括那些封装在 IPv6 地址中或映射到 - IPv6 地址中的 IPv4 地址,例如 ::10.2.3.4 或 + 地址总是排在 IPv6 地址之前,即使后者是封装或映射 IPv4 地址所得的 IPv6 地址,例如 ::10.2.3.4::ffff:10.4.3.2 @@ -3566,7 +3536,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - <type>inet</type> vs. <type>cidr</type> + <type>inet</type> 与 <type>cidr</type> inetcidr 两种数据类型的本质区别在于: @@ -3592,12 +3562,12 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - MAC地址 + MAC 地址 macaddr - macaddr类型存储 MAC 地址,也就是以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: + macaddr类型存储 MAC 地址,例如以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: '08:00:2b:01:02:03' @@ -3631,11 +3601,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays <type>macaddr8</type> - macaddr8 (data type) + macaddr8(数据类型) - MAC地址(EUI-64格式) + MAC 地址(EUI-64 格式) macaddr @@ -3762,31 +3732,31 @@ SELECT * FROM test; - 一个 bit 串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 + 一个位串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 开销,具体取决于串的长度。(不过,长值可能会被压缩或移到行外存储, 与 中对字符串的说明相同。) - 文本搜索类型 + 文本检索类型 - 全文搜索 + 全文检索 数据类型 - 文本搜索 + 文本检索 数据类型 - PostgreSQL 提供了两种专为支持全文搜索而 - 设计的数据类型。所谓全文搜索,是指在一组自然语言 + PostgreSQL 提供了两种专为支持全文检索而 + 设计的数据类型。所谓全文检索,是指在一组自然语言 文档中查找最匹配某个 查询的文档。tsvector 类型以 - 适合文本搜索的优化形式表示文档,tsquery 类型则表示 + 适合文本检索的优化形式表示文档,tsquery 类型则表示 文本查询。关于这一功能的详细解释见 ; 相关函数和操作符的概览见 @@ -3801,7 +3771,7 @@ SELECT * FROM test; tsvector 值是一个排好序且互不重复的 词位(lexeme)列表,这些词已经过 - 规范化,以便把同一单词的不同变体合并起来 + 正规化,以便把同一单词的不同变体合并起来 (详见 )。排序和去重会在输入时自动 完成,如下例所示: @@ -3860,12 +3830,12 @@ SELECT 'a:1A fat:2B,4C cat:5D'::tsvector; 权重通常用于反映文档结构,例如把标题中的词和正文中的词区分开来。 - 文本搜索排序函数可以为不同的权重标记分配不同优先级。 + 文本检索排序函数可以为不同的权重标记分配不同优先级。 必须认识到,tsvector 类型本身并不会执行任何词语 - 规范化;它假定输入的词已经按照应用需求完成规范化。例如: + 正规化;它假定输入的词已经按照应用需求完成正规化。例如: SELECT 'The Fat Rats'::tsvector; @@ -3874,9 +3844,9 @@ SELECT 'The Fat Rats'::tsvector; 'Fat' 'Rats' 'The' - 对于大多数英文全文搜索应用来说,上述词会被视为尚未规范化,但 + 对于大多数英文全文检索应用来说,上述词会被视为尚未正规化,但 tsvector 并不在意。原始文档文本通常应先经过 - to_tsvector,以按搜索需要对词语进行规范化: + to_tsvector,以按检索需要对词语进行正规化: SELECT to_tsvector('english', 'The Fat Rats'); @@ -3965,9 +3935,9 @@ SELECT 'super:*'::tsquery; 引号的使用规则与前面介绍 tsvector 时相同;同样, - 与 tsvector 一样,任何需要的词语规范化都必须在 + 与 tsvector 一样,任何需要的词语正规化都必须在 转换为 tsquery 类型之前完成。to_tsquery - 函数很适合用来实现这种规范化: + 函数很适合用来实现这种正规化: SELECT to_tsquery('Fat:ab & Cats'); @@ -3993,8 +3963,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); ---------------+------------ 'postgradu':1 | 'postgr':* - 因而它能够匹配其带前缀的后继形式 - postgraduate。 + 因而它能够匹配postgraduate 词干化后的形式。 @@ -4010,9 +3979,9 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); uuid 数据类型用于存储由 - RFC 9562、 + RFC 4122、 ISO/IEC 9834-8:2005 及相关标准定义的通用唯一标识符(UUID)。 - (有些系统把这种数据类型称为全局唯一标识符,或 GUID, + (有些系统把这种数据类型称为全局唯一标识符,或 GUID GUID。)这种标识符是一个 128 位的量,由某种算法生成,该算法被设计为使同一算法在已知宇宙中 被其他人生成出相同标识符的概率极低。因此,对于分布式系统而言, @@ -4020,14 +3989,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); 单个数据库内唯一。 - - RFC 9562 定义了 8 种不同的 UUID 版本。每个版本对生成新 UUID 值 - 都有各自的要求,也各自具备不同的优缺点。 - PostgreSQL 原生支持使用 UUIDv4 和 - UUIDv7 算法生成 UUID。或者,也可以在数据库外部使用任意算法生成 - UUID 值。uuid 数据类型可用于存储任何 UUID, - 无论其来源和版本为何。 - + UUID 写作一串小写十六进制数字,并用连字符分隔成若干组: @@ -4038,7 +4000,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11 PostgreSQL 也接受其他输入形式:可以使用 - 大写字母、用花括号包围标准格式、忽略部分或全部连字符,或者在任意 + 大写字母、用花括号包围标准格式、省略部分或全部连字符,或者在任意 4 位分组后额外加上连字符。例如: A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11 @@ -4139,8 +4101,8 @@ XMLSERIALIZE ( { DOCUMENT | CONTENT } value AS XMLPARSE 或 XMLSERIALIZE 的情况下与 xml 类型互相转换时, 选择 DOCUMENT 还是 CONTENT - 由会话配置参数 XML option - XML option 决定,可以使用 + 由会话配置参数 XML 选项 + XML 选项 决定,可以使用 标准命令设置: SET XML OPTION { DOCUMENT | CONTENT }; @@ -4157,20 +4119,20 @@ SET xmloption TO { DOCUMENT | CONTENT }; 编码处理 - 在客户端、服务器以及其间传输的 XML 数据上处理多字符编码时, + 在客户端、服务器以及其间传输的 XML 数据上处理多种字符编码时, 必须格外小心。使用文本模式向服务器发送查询并把查询结果返回给 - 客户端时,PostgreSQL 会将客户端与 + 客户端时(这是通常使用的模式),PostgreSQL 会将客户端与 服务器之间传输的所有字符数据转换为目标端的字符编码,参见 。这也包括表示 XML 值的字符串,如上例 所示。这通常意味着,由于字符数据在客户端和服务器之间传输时可能被 转换为其他编码,XML 数据中包含的编码声明可能会失效,因为内嵌的 编码声明本身并不会被修改。为处理这种情况,表示 xml 类型输入值的字符串中所包含的编码声明会被 - 忽略,其内容被假定为当前服务器编码。随后, + 忽略,其内容被假定为当前服务器编码。因此, 为了正确处理,客户端发出的 XML 数据字符串必须采用当前客户端编码。 客户端负责在将文档发送给服务器之前把它们转换为当前客户端编码, 或适当调整客户端编码。输出时,xml 类型值不会带有 - 编码声明,而客户端会假定所有数据都采用当前客户端编码。 + 编码声明,而客户端应假定所有数据都采用当前客户端编码。 @@ -4204,7 +4166,7 @@ SET xmloption TO { DOCUMENT | CONTENT }; xml 数据类型有些特殊,因为它不提供任何比较操作符。 这是因为对 XML 数据并不存在良定义且通用的比较算法。其结果是, - 你无法通过把某个 xml 值与搜索值比较来检索行。 + 你无法通过把某个 xml 列与搜索值比较来检索行。 因此,XML 值通常应伴随一个独立的键字段,例如 ID。另一种比较 XML 值的办法,是先把它们转换成字符串;但请注意,字符串比较对 XML 的比较需求通常帮助不大。 @@ -4212,14 +4174,14 @@ SET xmloption TO { DOCUMENT | CONTENT }; 由于 xml 数据类型没有可用的比较操作符,因此无法直接 - 在这种类型上创建索引。如果需要在 XML 中快速搜索,可行方案包括: + 在这种类型的列上创建索引。如果需要在 XML 中快速搜索,可行方案包括: 将表达式转换为字符串类型后为其建立索引,或者为某个 XPath 表达式 建立索引。当然,实际查询也必须相应调整为使用该被索引的表达式。 - PostgreSQL 的文本搜索功能也可用于加速 - XML 数据的全文搜索。不过,目前 PostgreSQL 发行版中仍缺少所需的 + PostgreSQL 的文本检索功能也可用于加速 + XML 数据的全文检索。不过,目前 PostgreSQL 发行版中仍缺少所需的 预处理支持。 @@ -4234,12 +4196,12 @@ SET xmloption TO { DOCUMENT | CONTENT }; 域类型 - domain + - data type - domain + 数据类型 + @@ -4251,13 +4213,13 @@ SET xmloption TO { DOCUMENT | CONTENT }; CREATE DOMAIN posint AS integer CHECK (VALUE > 0); CREATE TABLE mytable (id posint); -INSERT INTO mytable VALUES(1); -- works -INSERT INTO mytable VALUES(-1); -- fails +INSERT INTO mytable VALUES(1); -- 成功 +INSERT INTO mytable VALUES(-1); -- 失败 - 当底层类型的一个操作符或函数适用于一个域值时,域会被自动向下转换为底层类型。因此,mytable.id - 1的结果会被认为是类型integer而不是posint。我们可以写成(mytable.id - 1)::posint来把结果转换回posint,这会导致域的约束被重新检查。在这种情况下,如果该表达式被应用于一个值为1的id就会错误。把底层类型的值赋给域类型的一个字段或者变量不需要写显式的类型转换,但是域的约束将会被检查。 + 当底层类型的一个操作符或函数被应用于一个域值时,域会被自动向下转换为底层类型。因此,mytable.id - 1的结果会被认为是类型integer而不是posint。我们可以写成(mytable.id - 1)::posint来把结果转换回posint,这会导致域的约束被重新检查。在这种情况下,如果该表达式被应用于一个值为1的id就会报错。把底层类型的值赋给域类型的一个字段或者变量不需要写显式的类型转换,但是域的约束将会被检查。 @@ -4340,7 +4302,7 @@ INSERT INTO mytable VALUES(-1); -- fails 对象标识符(OID)在 PostgreSQL 内部被用作 若干系统表的主键。类型 oid 表示一个对象标识符。 - 此外还有若干 oid 的别名类型,统称为 + 此外还有若干 oid 的别名类型,其名称均形如 regsomething 给出了概要说明。 @@ -4417,14 +4379,14 @@ SELECT * FROM pg_attribute regconfig pg_ts_config - 文本搜索配置 + 文本检索配置 english regdictionary pg_ts_dict - 文本搜索字典 + 文本检索词典 simple @@ -4460,7 +4422,7 @@ SELECT * FROM pg_attribute regprocedure pg_proc - 函数与参数类型 + 带参数类型的函数 sum(int4) @@ -4496,7 +4458,7 @@ SELECT * FROM pg_attribute - 这些类型的输入函数允许在各个标记之间插入空白,并且会把大写字母 + 这些类型的输入函数允许在各个词元之间插入空白,并且会把大写字母 折叠为小写,双引号内除外;这样做是为了让语法规则更接近 SQL 中 书写对象名的方式。反过来,如果需要让输出成为有效的 SQL 标识符, 输出函数会自动加上双引号。例如,一个名为 Foo @@ -4571,8 +4533,7 @@ WHERE ... 它就会对被引用对象建立依赖。例如,如果某列的默认表达式是 nextval('my_seq'::regclass)PostgreSQL 就会知道该默认表达式依赖于 - 序列 my_seq,因此系统在删除该序列之前,必须先 - 移除该默认表达式。改用 + 序列 my_seq,因此系统不允许在尚未移除该默认表达式时删除序列。改用 nextval('my_seq'::text) 则不会建立依赖。 (regrole 是这一特性的例外:该类型的常量不允许出现在 存储表达式中。) @@ -4772,7 +4733,7 @@ WHERE ... anyarray - 表示一个函数可以接受任意数组数据类型(参见 + 表示一个函数可以接受任意数组数据类型(参见)。 @@ -4891,7 +4852,7 @@ WHERE ... unknown - 标识一种尚未解析出的类型,例如未修饰的字符串字面值。 + 标识一种尚未解析出的类型,例如未修饰的字符串字面值的类型。 @@ -4909,7 +4870,7 @@ WHERE ... voidrecord 用作结果类型 (如果函数被用作触发器或事件触发器,则也允许 triggerevent_trigger 作为结果类型)。 - 有些语言还支持借助多态伪类型来实现多态函数;详见 + 有些语言还支持借助上面列出的多态伪类型来实现多态函数;详见 diff --git a/zh/16/dict-int.sgml b/zh/16/dict-int.sgml index ccca92cc..63d7ccf8 100644 --- a/zh/16/dict-int.sgml +++ b/zh/16/dict-int.sgml @@ -1,16 +1,16 @@ - dict_int — 用于整数的示例全文搜索词典 + dict_int — 用于整数的示例全文检索词典 dict_int - dict_int是一个全文搜索附加词典模板的示例。 + dict_int是一个全文检索附加词典模板的示例。 引入这个示例词典是为了控制整数(有符号和无符号)的索引, - 使这类数字能够被索引,同时又避免唯一词的数量过度增长, + 使这类数字能够被索引,同时又避免不同词的数量过度增长, 因为那会严重影响搜索性能。 @@ -54,7 +54,7 @@ 用法 - 安装dict_int扩展后,会创建一个文本搜索模板 + 安装dict_int扩展后,会创建一个文本检索模板 intdict_template以及一个基于该模板、使用默认参数的词典 intdict。你可以修改这些参数,例如: @@ -77,7 +77,7 @@ mydb# select ts_lexize('intdict', '12345678'); 但在实际使用中,通常需要像所述那样, - 将它包含到某个文本搜索配置中。可能类似如下: + 将它包含到某个文本检索配置中。可能类似如下: ALTER TEXT SEARCH CONFIGURATION english diff --git a/zh/16/func.sgml b/zh/16/func.sgml index e75f23e6..45c0ed6a 100644 --- a/zh/16/func.sgml +++ b/zh/16/func.sgml @@ -2688,7 +2688,7 @@ repeat('Pg', 4) PgPgPgPg 还有其他字符串操作函数和操作符,列在中。 (其中一些用于内部实现中列出的SQL标准字符串函数。) - 此外,中还描述了模式匹配操作符,中则描述了全文搜索操作符。 + 此外,中还描述了模式匹配操作符,中则描述了全文检索操作符。
@@ -11382,7 +11382,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 文本搜索函数和操作符 + 文本检索函数和操作符 全文检索 @@ -11390,7 +11390,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 文本搜索 + 文本检索 函数和操作符 @@ -11398,12 +11398,12 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple 以及 - 总结了为全文检索提供的函数和操作符。PostgreSQL的文本搜索功能的详细解释可参考。 + 总结了为全文检索提供的函数和操作符。PostgreSQL的文本检索功能的详细解释可参考
- 文本搜索操作符 + 文本检索操作符 @@ -11579,12 +11579,12 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple 除了这些专用操作符之外, 中所示的常用比较操作符也适用于tsvectortsquery类型。 - 这些操作符对文本搜索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。 + 这些操作符对文本检索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。
- 文本搜索函数 + 文本检索函数 @@ -11631,7 +11631,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple regconfig - 返回当前默认文本搜索配置的OID(由 所设定的). + 返回当前默认文本检索配置的 OID(由 设置)。 get_current_ts_config() @@ -12167,18 +12167,18 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 所有接受一个可选的regconfig参数的文本搜索函数在省略该参数时,会使用由指定的配置。 + 所有接受一个可选的regconfig参数的文本检索函数在省略该参数时,会使用由指定的配置。 - 中的函数被单独列出,因为它们通常不被用于日常的文本搜索操作。 - 它们主要有助于开发和调试新的文本搜索配置。 + 中的函数被单独列出,因为它们通常不被用于日常的文本检索操作。 + 它们主要有助于开发和调试新的文本检索配置。
- 文本搜索调试函数 + 文本检索调试函数 @@ -12214,7 +12214,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple lexemestext[] ) - 根据指定的或默认的文本搜索配置从document中提取和正规化词元,并返回关于每个词元是如何处理的信息。 + 根据指定的或默认的文本检索配置从document中提取和正规化词元,并返回关于每个词元是如何处理的信息。 详情参见 diff --git a/zh/16/gist.sgml b/zh/16/gist.sgml index 2413cefa..0d74f0ab 100644 --- a/zh/16/gist.sgml +++ b/zh/16/gist.sgml @@ -983,7 +983,7 @@ my_sortsupport(PG_FUNCTION_ARGS) 示例 - PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本搜索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: + PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本检索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: diff --git a/zh/16/json.sgml b/zh/16/json.sgml index bbbbf9e0..ccfe033d 100644 --- a/zh/16/json.sgml +++ b/zh/16/json.sgml @@ -38,7 +38,7 @@ - 由于 json 类型存储的是输入文本的精确副本,因此它会保留标记 + 由于 json 类型存储的是输入文本的精确副本,因此它会保留词元 之间在语义上无关紧要的空白,以及 JSON 对象内部键的顺序。此外,如果值中 的某个 JSON 对象包含同一个键多次,所有键/值对都会被保留下来(处理函数会 将最后一个值视为生效值)。相比之下,jsonb 不保留空白,不保留 @@ -86,7 +86,7 @@ 当把文本形式的 JSON 输入转换为 jsonb 时, - RFC 7159 描述的基本类型会有效映射到原生的 + RFC 7159 描述的基本类型实际上会映射到原生的 PostgreSQL 类型上,如 所示。因此,什么样的数据构成 有效的 jsonb 会有一些额外但较小的限制,这些限制不适用于 @@ -137,7 +137,7 @@ null - (无) + (无) SQL NULL 是不同的概念 @@ -152,18 +152,18 @@ 以下都是有效的 json(或 jsonb)表达式: --- Simple scalar/primitive value --- Primitive values can be numbers, quoted strings, true, false, or null +-- 简单的标量/基本值 +-- 基本值可以是数字、加引号的字符串、true、false 或 null SELECT '5'::json; --- Array of zero or more elements (elements need not be of same type) +-- 包含零个或多个元素的数组(元素不必是同一类型) SELECT '[1, 2, "foo", null]'::json; --- Object containing pairs of keys and values --- Note that object keys must always be quoted strings +-- 包含键值对的对象 +-- 注意,对象的键必须始终是加引号的字符串 SELECT '{"bar": "baz", "balance": 7.77, "active": false}'::json; --- Arrays and objects can be nested arbitrarily +-- 数组和对象可以任意嵌套 SELECT '{"foo": [true, "bar"], "tags": {"a": 1, "b": null}}'::json; @@ -219,8 +219,7 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 当 JSON 数据存储在表中时,它与任何其他数据类型一样,都要面对相同的并发控 制考量。虽然存储大型文档是可行的,但要记住,任何更新都会在整行上获取一个 行级锁。应考虑将 JSON 文档限制在可管理的大小,以减少更新事务之间的锁争用。 - 理想情况下,每个 JSON 文档都应表示一个原子数据项,按照业务规则,它不应被 - 合理地进一步拆分为更小且可独立修改的数据项。 + 理想情况下,每个 JSON 文档都应表示一个原子数据项,根据业务规则,无法再合理地将它细分为更小且可独立修改的数据项。 @@ -228,11 +227,11 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; <type>jsonb</type> 包含与存在 jsonb - containment + 包含 jsonb - existence + 存在 测试 包含jsonb 的一项重要能力。 @@ -241,33 +240,32 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 示例都返回真: --- Simple scalar/primitive values contain only the identical value: +-- 简单的标量/基本值只包含相同的值: SELECT '"foo"'::jsonb @> '"foo"'::jsonb; --- The array on the right side is contained within the one on the left: +-- 左侧数组包含右侧数组: SELECT '[1, 2, 3]'::jsonb @> '[1, 3]'::jsonb; --- Order of array elements is not significant, so this is also true: +-- 数组元素的顺序无关紧要,因此下面的结果也为真: SELECT '[1, 2, 3]'::jsonb @> '[3, 1]'::jsonb; --- Duplicate array elements don't matter either: +-- 重复的数组元素也无关紧要: SELECT '[1, 2, 3]'::jsonb @> '[1, 2, 2]'::jsonb; --- The object with a single pair on the right side is contained --- within the object on the left side: +-- 左侧对象包含右侧只有一个键值对的对象: SELECT '{"product": "PostgreSQL", "version": 9.4, "jsonb": true}'::jsonb @> '{"version": 9.4}'::jsonb; --- The array on the right side is not considered contained within the --- array on the left, even though a similar array is nested within it: -SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- yields false +-- 左侧数组被认为包含右侧数组, +-- 尽管其中嵌套了一个类似的数组: +SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- 结果为假 --- But with a layer of nesting, it is contained: +-- 但增加一层嵌套后,就构成了包含关系: SELECT '[1, 2, [1, 3]]'::jsonb @> '[[1, 3]]'::jsonb; --- Similarly, containment is not reported here: -SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- yields false +-- 同样,下面也不构成包含关系: +SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- 结果为假 --- A top-level key and an empty object is contained: +-- 包含由顶层键和空对象构成的对象: SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; @@ -282,11 +280,11 @@ SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; 对于结构必须匹配这一一般原则,有一个特殊例外:数组可以包含一个基本值: --- This array contains the primitive string value: +-- 这个数组包含该基本字符串值: SELECT '["foo", "bar"]'::jsonb @> '"bar"'::jsonb; --- This exception is not reciprocal -- non-containment is reported here: -SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false +-- 这个例外并不对称——下面的结果表示不包含: +SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- 结果为假 @@ -296,19 +294,19 @@ SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false 外,下面这些示例都返回真: --- String exists as array element: +-- 字符串作为数组元素存在: SELECT '["foo", "bar", "baz"]'::jsonb ? 'bar'; --- String exists as object key: +-- 字符串作为对象键存在: SELECT '{"foo": "bar"}'::jsonb ? 'foo'; --- Object values are not considered: -SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- yields false +-- 不考虑对象的值: +SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- 结果为假 --- As with containment, existence must match at the top level: -SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- yields false +-- 与包含关系一样,存在性必须在顶层匹配: +SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- 结果为假 --- A string is considered to exist if it matches a primitive JSON string: +-- 如果字符串与一个基本 JSON 字符串匹配,则认为它存在: SELECT '"foo"'::jsonb ? 'foo'; @@ -322,8 +320,7 @@ SELECT '"foo"'::jsonb ? 'foo'; 由于 JSON 包含是嵌套的,因此适当的查询可以跳过对子对象的显式选择。例如, 假设我们有一个 doc 列,其顶层是对象,而且大 多数对象都带有 tags 字段,该字段中包含子对象数组。下面 - 这个查询会找出那些包含同时带有 "term":"paris" 和 - "term":"food" 的子对象的项,同时忽略 + 这个查询会找出同时出现包含 "term":"paris" 的子对象和包含 "term":"food" 的子对象的项,同时忽略 tags 数组之外的任何此类键: SELECT doc->'site_name' FROM websites @@ -353,7 +350,7 @@ SELECT doc->'site_name' FROM websites <type>jsonb</type> 索引 jsonb - indexes on + 索引 @@ -403,14 +400,14 @@ CREATE INDEX idxginp ON api USING GIN (jdoc jsonb_path_ops); 名为 jdocjsonb 列里。 如果在该列上创建了 GIN 索引,那么下面这样的查询就可以利用这个索引: --- Find documents in which the key "company" has value "Magnafone" +-- 查找键 "company" 的值为 "Magnafone" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"company": "Magnafone"}'; 但是,类似下面这样的查询就无法使用该索引,因为虽然操作符 ? 可索引,但它并未直接应用到被索引的列 jdoc 上: --- Find documents in which the key "tags" contains key or array element "qui" +-- 查找键 "tags" 包含键或数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc -> 'tags' ? 'qui'; 不过,只要适当地使用表达式索引,上述查询也可以利用索引。如果经常查询 @@ -428,7 +425,7 @@ CREATE INDEX idxgintags ON api USING GIN ((jdoc -> 'tags')); 另一种查询方法是利用包含,例如: --- Find documents in which the key "tags" contains array element "qui" +-- 查找键 "tags" 包含数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qui"]}'; jdoc 列上的简单 GIN 索引可以支持这个查询。 @@ -449,8 +446,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; 对于这些操作符,GIN 索引会从 jsonpath 模式中提取出形如 - accessors_chain - == constant 的子句,并根据其中提到 + accessors_chain = constant 的子句,并根据其中提到 的键和值进行索引搜索。访问器链可以包含 .key[*] 和 @@ -466,7 +462,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; @@ 操作符的查询,但相较于默认操作符类 jsonb_ops,它具有显著的性能优势。 jsonb_path_ops 索引通常比相同数据上的 - jsonb_ops 索引小得多,而且搜索条件也更具特异性,尤其是在 + jsonb_ops 索引小得多,而且搜索也更有针对性,尤其是在 查询中包含数据里频繁出现的键时。因此,搜索操作通常比使用默认操作符类时 性能更佳。 @@ -482,9 +478,9 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; 基本上,每个 jsonb_path_ops 索引项都是该值连同 - 通向该值的键一起计算出的哈希。例如,要索引 + 通向该值的键一起计算出的 hash。例如,要索引 {"foo": {"bar": "baz"}},会创建一个单独的索引项, - 其哈希值中同时纳入 foobar 和 + 其 hash 值中同时纳入 foobarbaz 这三者。因此,查找这一结构的包含查询会得到一次 非常精确的索引搜索;但完全没有办法据此找出 foo 是否 作为键出现。另一方面,jsonb_ops 索引会分别创建三个 @@ -506,7 +502,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; jsonb 还支持 btreehash 索引。通常只有在需要检查完整 JSON 文档是否相等时, 它们才有用。btreejsonb 数据项的 - 排序通常没什么太大意义,但为了完整起见,其规则如下: + 排序顺序通常很少受到关注,但为了完整起见,其规则如下: 对象 > 数组 > 布尔值 > 数字 > 字符串 > null @@ -561,27 +557,24 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; --- Extract object value by key +-- 按键提取对象的值 SELECT ('{"a": 1}'::jsonb)['a']; --- Extract nested object value by key path +-- 按键路径提取嵌套对象的值 SELECT ('{"a": {"b": {"c": 1}}}'::jsonb)['a']['b']['c']; --- Extract array element by index +-- 按下标提取数组元素 SELECT ('[1, "2", null]'::jsonb)[1]; --- Update object value by key. Note the quotes around '1': the assigned --- value must be of the jsonb type as well +-- 按键更新对象的值。注意 '1' 两边的引号:赋予的值也必须是 jsonb 类型 UPDATE table_name SET jsonb_field['key'] = '1'; --- This will raise an error if any record's jsonb_field['a']['b'] is something --- other than an object. For example, the value {"a": 1} has a numeric value --- of the key 'a'. +-- 如果任何记录的 jsonb_field['a']['b'] 不是对象,就会报错。 +-- 例如,值 {"a": 1} 的键 'a' 对应的值是数字。 UPDATE table_name SET jsonb_field['a']['b']['c'] = '1'; --- Filter records using a WHERE clause with subscripting. Since the result of --- subscripting is jsonb, the value we compare it against must also be jsonb. --- The double quotes make "value" also a valid jsonb string. +-- 使用带下标的 WHERE 子句筛选记录。由于下标操作的结果是 jsonb, +-- 与之比较的值也必须是 jsonb。双引号使 "value" 也成为合法的 jsonb 字符串。 SELECT * FROM table_name WHERE jsonb_field['key'] = '"value"'; @@ -591,19 +584,19 @@ SELECT * FROM table_name WHERE jsonb_field['key'] = '"value"'; (对象或数组)的空 JSON 值来处理: --- Where jsonb_field was NULL, it is now {"a": 1} +-- 原先为 NULL 的 jsonb_field 现在为 {"a": 1} UPDATE table_name SET jsonb_field['a'] = '1'; --- Where jsonb_field was NULL, it is now [1] +-- 原先为 NULL 的 jsonb_field 现在为 [1] UPDATE table_name SET jsonb_field[0] = '1'; - 如果对一个元素数量不足的数组指定了某个索引,就会不断追加 - NULL 元素,直到该索引可达并且可以设置该值为止。 + 如果对一个元素数量不足的数组指定了某个下标,就会不断追加 + NULL 元素,直到该下标可达并且可以设置该值为止。 --- Where jsonb_field was [], it is now [null, null, 2]; --- where jsonb_field was [0], it is now [0, null, 2] +-- 原先为 [] 的 jsonb_field 现在为 [null, null, 2]; +-- 原先为 [0] 的 jsonb_field 现在为 [0, null, 2] UPDATE table_name SET jsonb_field[2] = '2'; @@ -614,10 +607,10 @@ UPDATE table_name SET jsonb_field[2] = '2'; null 填充,直到能够放入被赋值的值为止。 --- Where jsonb_field was {}, it is now {"a": [{"b": 1}]} +-- 原先为 {} 的 jsonb_field 现在为 {"a": [{"b": 1}]} UPDATE table_name SET jsonb_field['a'][0]['b'] = '1'; --- Where jsonb_field was [], it is now [null, {"a": 1}] +-- 原先为 [] 的 jsonb_field 现在为 [null, {"a": 1}] UPDATE table_name SET jsonb_field[1]['a'] = '1'; @@ -634,7 +627,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; PL/Perl 的扩展名为 jsonb_plperljsonb_plperlu。如果使用它们, - jsonb 值会按适当方式映射为 Perl 数组、哈希和标量。 + jsonb 值会按适当方式映射为 Perl 数组、hash 和标量。 @@ -694,7 +687,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; 的。还支持非十进制整数字面量和下划线分隔符,例如 1_000_0000x1EEE_FFFF0o2730b100101。在 SQL/JSON - 路径中(以及 JavaScript 中,但不包括严格意义上的 SQL),基数前缀后面不能 + 路径中(以及 JavaScript 中,但 SQL 本身并非如此),基数前缀后面不能 直接出现下划线分隔符。 @@ -723,7 +716,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; - 路径表达式由一系列路径元素构成,可以是下列任意一种: + 路径表达式由一系列路径元素构成,这些元素可以是下列任意一种: @@ -862,7 +855,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; 类似 .**,但只选择 JSON 层次结构中指定的层级。 - 嵌套层级以整数指定。层级零对应当前对象。若要访问最低的嵌套层级, + 嵌套层级以整数指定。层级零对应当前对象。若要访问最深的嵌套层级, 可以使用 last 关键字。这是 PostgreSQL 对 SQL/JSON 标准的扩展。 @@ -880,13 +873,13 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; 可以用两种形式给出: indexstart_index to end_index。 - 第一种形式按索引返回单个数组元素。第二种形式按索引范围返回数组切片, + 第一种形式按下标返回单个数组元素。第二种形式按下标范围返回数组切片, 其中包括与给定 start_indexend_index 对应的元素。 指定的 index 可以是整数,也可以是返回单个 - 数值的表达式,该表达式会自动转换为整数。索引零对应第一个数组元素。 + 数值的表达式,该数值会自动转换为整数。下标零对应第一个数组元素。 你也可以使用 last 关键字来表示最后一个数组元素, 这对于处理长度未知的数组很有用。 diff --git a/zh/16/libpq.sgml b/zh/16/libpq.sgml index 48f1214a..1292287d 100644 --- a/zh/16/libpq.sgml +++ b/zh/16/libpq.sgml @@ -2,7 +2,7 @@ - <application>libpq</application> - C 库 + <application>libpq</application> — C 库 libpq @@ -13,33 +13,27 @@ - libpq是应用程序员使用PostgreSQLC接口。libpq是一个库函数的集合,它们允许客户端程序传递查询给PostgreSQL后端服务器并且接收这些查询的结果。 + libpqPostgreSQLC应用程序编程接口。libpq是一组库函数,客户端程序可用它们向PostgreSQL后端服务器发送查询并接收查询结果。 - libpq也是很多其他PostgreSQL应用接口的底层引擎,包括为 C++、Perl、Python、Tcl 和 ECPG编写的接口。如果你使用那些包,某些方面的libpq行为将会对你很重要。特别是,描述了任何使用libpq的应用的用户可见的行为。 + libpq也是其他几个PostgreSQL应用程序接口的底层引擎,包括为 C++、Perl、Python、Tcl 和ECPG编写的接口。因此,对于这些包的用户,libpq行为的某些方面也很重要。特别是,描述了任何使用libpq的应用程序的用户都能观察到的行为。 - 在本章的末尾()包括了一些短程序来展示如何编写使用libpq的应用。在源代码发布的src/test/examples目录中还有一些完整的libpq应用的示例。 + 本章末尾()包含一些简短程序,展示如何编写使用libpq的程序。源代码发行包的src/test/examples目录中还提供了几个完整的libpq应用程序示例。 - 使用libpq的客户端程序必须包括头文件libpq-fe.hlibpq-fe.h并必须与libpq库链接在一起。 + 使用libpq的客户端程序必须包含头文件libpq-fe.hlibpq-fe.h,并且必须与libpq库链接。 数据库连接控制函数 - - 下列函数会建立到一个PostgreSQL后端服务器的连接。 - 一个应用程序可以在一个时刻打开多个后端连接(原因之一就是为了访问多个数据库)。 - 每个连接用一个PGconnPGconn对象表示,它从函数,或得到。 - 注意这些函数将总是返回一个非空的对象指针,除非正好没有内存来分配PGconn对象。 - 在通过该连接对象发送查询之前,应该调用函数来检查返回值以确定是否得到了一个成功的连接。 - - + 以下函数用于建立到PostgreSQL后端服务器的连接。应用程序可以同时保持多个后端连接。(这样做的原因之一是访问多个数据库。)每个连接由一个PGconnPGconn对象表示,该对象可以通过以下函数获取:, + 。注意,这些函数总是返回非空的对象指针,除非内存不足,甚至无法分配PGconn对象。应调用函数检查返回值,确认连接成功后,再通过连接对象发送查询。 如果不受信任的用户能够访问一个没有采用模式的安全使用方式的数据库,那么每个会话开始时都应从search_path中移除公开可写的模式。可以把参数关键词options设置为-csearch_path=。也可以在连接后发出PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)")。这种考虑并非专门针对libpq;它适用于每一种可执行任意 SQL 命令的接口。 @@ -47,7 +41,7 @@ - 在 Unix 上,复制一个拥有打开 libpq 连接的进程可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行代码是安全的。 + 在 Unix 上,对持有已打开 libpq 连接的进程执行 fork 操作可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行程序是安全的。 @@ -74,32 +68,32 @@ PGconn *PQconnectdbParams(const char * const *keywords, - 被传递的数组可以为空,这样就会使用所有默认参数。 - 也可以只包含一个或几个参数设置。他们在长度上必须匹配。 - 对于参数数组的处理将会停止于keywords数组中第一个NULL元素。 - 而且,如果与非-NULL keywords条目相关联的values条目为NULL或者空字符串,则忽略该项并继续处理下一对数组项。 + 传入的数组可以为空,以使用所有默认参数,也可以包含一个或多个参数设置。 + 两个数组的长度必须相同。处理会在 keywords 数组的第一个 NULL 元素处停止。 + 如果某个非 NULLkeywords 元素所对应的 + values 元素为 NULL 或空字符串,则忽略这一项,继续处理下一对数组元素。 - 当expand_dbname为非零时,会检查第一个dbname关键词的值以查看它是否为一个连接字符串。 - 如果是,它被扩展到从字符串中提取的单独的连接参数。 - 该值被认为是一个连接字符串,而不仅是一个数据库名称,如果它包含一个等号(=)或者它以URI模式标志符开头, - (有关连接字符串格式的更多详情可见。) - 只有dbname的第一次出现会按这种方式处理,任何后续dbname值会被当做一个普通数据库名处理。 + 当 expand_dbname 非零时,会检查第一个 dbname 关键词的值是否为 + 连接字符串。如果是,就将其展开为从该字符串中提取的各个连接参数。 + 如果该值包含等号(=),或以 URI 方案标识符开头,就会将其视为连接字符串,而非单纯的数据库名。 + (连接字符串格式的详细说明见。) + 只有第一次出现的 dbname 会按这种方式处理;后续的 dbname 参数都作为普通数据库名处理。 - 通常,参数数组从开头到结尾进行处理。 - 当关键词有重复时,使用最后一个值(不是 NULL 或空)。 - 此规则特别适用于连接字符串中的关键字与一个出现在keywords数组中的关键字冲突的情况。 - 因此,程序员可以决定数组条目是否能被覆盖或用连接字符串获取的值覆盖。 - 出现在扩展的dbname条目之前的数组条目可以被连接字符串的字段所覆盖,反之,这些字段被dbname之后出现的数组条目所覆盖。(但是,再有,只有在那些条目支持非空值时。) + 通常会从头到尾处理参数数组。如果某个关键词重复出现,则采用最后一个非 NULL 且非空的值。 + 此规则也适用于连接字符串中的关键词与 keywords 数组中的关键词冲突的情况。 + 因此,程序员可以决定数组元素是覆盖连接字符串中的值,还是被这些值覆盖。 + 出现在要展开的 dbname 元素之前的数组元素,可以被连接字符串中的字段覆盖; + 而这些字段又会被出现在 dbname 之后的数组元素覆盖(同样,只有这些元素提供非空值时才会覆盖)。 - 在处理完所有数组条目和任何扩展的连接字符串后,所有未设置的连接参数都将使用默认值填充。 - 如果一个未设置参数的相关环境变量(参见 )被设置了,它的值会被使用。 - 如果环境变量未被设置,则使用参数的内置默认值。 + 处理完所有数组元素及展开的连接字符串后,仍未设置的连接参数将填入默认值。 + 如果某个未设置参数对应的环境变量(见)已经设置,就使用该环境变量的值; + 否则使用该参数的内置默认值。 @@ -121,7 +115,7 @@ PGconn *PQconnectdb(const char *conninfo); - 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空格分隔的一个或多个参数设置,还可以包含一个URI。详见。 + 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空白分隔的一个或多个参数设置,还可以包含一个URI。详见 @@ -144,11 +138,11 @@ PGconn *PQsetdbLogin(const char *pghost, - 这是的带有固定参数集合的前辈。它具有相同的功能,不过其中缺失的参数将总是采用默认值。对任意一个固定参数写NULL或一个空字符串将会使它采用默认值。 + 这是 的前身,使用固定的一组参数。除缺失参数始终采用默认值之外,功能相同。对于要使用默认值的任意固定参数,请传入 NULL 或空字符串。 - 如果dbName包含一个=符号或者具有一个合法的连接URI前缀,它会被当作一个conninfo字符串,就好像它已经被传递给了,并且剩余的参数则被应用为指定给。 + 如果 dbName 包含 = 符号,或具有有效的连接 URI 前缀,就会将其当作 conninfo 字符串处理,方式与将其传给 完全相同,然后按照 的规则应用其余参数。 @@ -183,7 +177,7 @@ PGconn *PQsetdb(char *pghost, PQconnectPollPQconnectPoll - nonblocking connection + 非阻塞连接 以非阻塞的方式建立一个到数据库服务器的连接。 @@ -209,18 +203,14 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); 在PQconnectStart中,数据库连接使用从字符串conninfo中取得的参数创建,这和之前描述的相同。 - - 只要满足一些限制,PQconnectStartPQconnectPoll都不会阻塞: - + 无论是还是PQconnectStart还是PQconnectPoll都不会阻塞,只要满足以下限制: - - 必须正确使用 hostaddr 参数,以避免执行 DNS 查询。详细信息请参见中该参数的说明。 - + 必须正确使用 hostaddr 参数,以避免执行 DNS 查询。详细信息请参见中该参数的说明。 - 如果你调用,确保你追踪的该流对象不会阻塞。 + 如果你调用,确保接收追踪输出的流对象不会阻塞。 @@ -233,17 +223,14 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 要开始无阻塞的连接请求,可调用PQconnectStart或者。如果结果为空,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 + 要开始非阻塞连接请求,可调用PQconnectStart或者。如果结果为空指针,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 如果PQconnectStart成功,下一个阶段是轮询libpq,这样它能够继续进行连接序列。使用PQsocket(conn)来获得该数据库连接底层的套接字描述符(警告:不要假定在PQconnectPoll调用之间套接字会保持相同)。这样循环:如果PQconnectPoll(conn)上一次返回PGRES_POLLING_READING,等到该套接字准备好读取(按照select()poll()或类似的系统函数所指示的)。则再次调用PQconnectPoll(conn)。反之,如果PQconnectPoll(conn)上一次返回PGRES_POLLING_WRITING,等到该套接字准备好写入,则再次调用PQconnectPoll(conn)。在第一次迭代时,即如果你还没有调用PQconnectPoll,行为就像是它上次返回了PGRES_POLLING_WRITING。持续这个循环直到PQconnectPoll(conn)返回PGRES_POLLING_FAILED指示连接过程已经失败,或者返回PGRES_POLLING_OK指示连接已经被成功地建立。 - - 在连接期间的任意时刻,该连接的状态可以通过调用来检查。如果这个调用返回CONNECTION_BAD,那么连接过程已经失败。如果该调用返回CONNECTION_OK,则该连接已经准备好。如前所述,这些状态同样都可以从PQconnectPoll的返回值检测。在一个异步连接过程中(也只有在这个过程中)也可能出现其他状态。这些状态指示该连接过程的当前阶段,并且可能有助于为用户提供反馈。这些状态是: - - + 在连接过程中的任何时刻,都可以调用来检查连接状态。如果调用返回CONNECTION_BAD,则连接过程失败;如果调用返回CONNECTION_OK,则连接已就绪。这两种状态也同样可以通过以下函数的返回值检测:PQconnectPoll,详见上文。在异步连接过程中还可能出现其他状态,而且它们仅在此过程中出现。这些状态表示连接过程的当前阶段,例如可用于向用户提供反馈。这些状态包括: CONNECTION_STARTED @@ -315,10 +302,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - - - 注意,尽管这些常数将被保留(为了维护兼容性),一个应用永远不应该依赖这些状态按照特定顺序出现,或者根本就不依赖它们,或者不依赖状态总是这些文档中所说的值。一个应用可能做些这样的事情: - + 注意,虽然为保持兼容性会保留这些常量,但应用程序不应依赖它们按特定顺序出现、不应假定它们一定出现,也不应假定状态值一定是这里列出的某个值。应用程序可以采用如下方式: switch(PQstatus(conn)) { case CONNECTION_STARTED: @@ -338,11 +322,11 @@ switch(PQstatus(conn)) - 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。否则,PQconnectStart后面跟着PQconnectPoll循环等效于。 + 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。除此之外,PQconnectStart后面跟着PQconnectPoll循环等效于 - 注意当PQconnectStart返回一个非空的指针时,你必须在用完它之后调用来处理那些结构体和任何相关的内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 + 注意当PQconnectStart返回一个非空的指针时,你必须在用完它之后调用来释放该结构体及其关联的所有内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 @@ -358,21 +342,21 @@ PQconninfoOption *PQconndefaults(void); typedef struct { char *keyword; /* 该选项的关键词 */ - char *envvar; /* 依赖的环境变量名 */ - char *compiled; /* 依赖的内置默认值 */ + char *envvar; /* 后备环境变量名 */ + char *compiled; /* 编译时设置的后备默认值 */ char *val; /* 选项的当前值,或者 NULL */ - char *label; /* 连接对话框中域的标签 */ - char *dispchar; /* 指示如何在一个连接对话框中显示这个域。值是: + char *label; /* 连接对话框中字段的标签 */ + char *dispchar; /* 指示如何在连接对话框中显示此字段。可取值: "" 显示输入的值 - "*" 密码域 - 隐藏值 + "*" 密码字段 - 隐藏值 "D" 调试选项 - 默认不显示 */ - int dispsize; /* 用于对话框的以字符计的域尺寸 */ + int dispsize; /* 对话框中的字段宽度,以字符计 */ } PQconninfoOption; - 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前缺省值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回该空指针。注意当前缺省值(val域)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 + 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前默认值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回空指针。注意当前默认值(val字段)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 @@ -393,9 +377,7 @@ PQconninfoOption *PQconninfo(PGconn *conn); - 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前缺省值。 - 返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。 - 上述所有对于的注解也适用于的结果。 + 返回一个连接选项数组。可以用它确定所有可能的 选项,以及实际用于连接服务器的值。返回值指向一个 PQconninfoOption 结构体数组,该数组以 keyword 指针为空的条目结束。上文针对 的所有注意事项,也适用于 的结果。 @@ -421,7 +403,9 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); - 如果errmsg不是NULL,那么成功时*errmsg会被设置为NULL, 否则设置为被malloc过的错误字符串以说明该问题(也可以将*errmsg设置为NULL并且函数返回NULL,这表示一种内存耗尽的情况)。 + 如果 errmsg 不是 NULL,则成功时将 *errmsg 设为 NULL; + 失败时将其设为由 malloc 分配的、用于说明问题的错误字符串。 + (也可能出现 *errmsg 被设为 NULL,同时函数返回 NULL 的情况;这表示内存不足。) @@ -451,7 +435,7 @@ void PQfinish(PGconn *conn); PQresetPQreset - 重置与服务器的通讯通道。 + 重置与服务器的通信通道。 void PQreset(PGconn *conn); @@ -469,7 +453,7 @@ void PQreset(PGconn *conn); PQresetPollPQresetPoll - 以非阻塞方式重置与服务器的通讯通道。 + 以非阻塞方式重置与服务器的通信通道。 int PQresetStart(PGconn *conn); @@ -486,7 +470,7 @@ PostgresPollingStatusType PQresetPoll(PGconn *conn); - 要发起一次连接重置,调用。如果它返回 0,那么重置失败。如果返回 1,就按使用PQresetPoll建立连接时相同的方法,继续调用PQresetPoll来重置连接。 + 要开始重置连接,请调用 。如果返回 0,表示重置失败。如果返回 1,则使用 PQresetPoll 轮询重置过程,方式与使用 PQconnectPoll 建立连接完全相同。 @@ -581,7 +565,7 @@ void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook); int callback_fn(char *buf, int size, PGconn *conn); - 随后,libpq会调用该回调,而不是调用其默认的PQdefaultSSLKeyPassHook_OpenSSL处理程序。 + 随后,libpq会调用该回调,而不是调用其默认的PQdefaultSSLKeyPassHook_OpenSSL处理程序。 回调函数应确定密钥密码,并将其复制到大小为size的结果缓冲区buf中。 buf中的字符串必须以空字符结尾。 回调函数必须返回存储在buf中的密码长度,不包括结尾的空字符。 @@ -600,7 +584,7 @@ int callback_fn(char *buf, int size, PGconn *conn); - 除了异常、longjmp(...)等情况外,回调务必不可跳出正常控制流。它必须正常返回。 + 回调不得通过异常、longjmp(...)等方式跳出正常控制流。它必须正常返回。 @@ -637,9 +621,9 @@ PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void); 几个libpq函数解析用户指定的字符串以获取连接参数。 - 这些字符串有两种被接受的格式:普通的关键字/值字符串和URI。URI通常遵循 + 这些字符串有两种被接受的格式:普通的关键词/值字符串和URI。URI通常遵循 RFC - 3986,除了允许多主机连接字符串,如下面进一步描述的那样。 + 3986,但也允许使用多主机连接字符串,详见下文。 @@ -647,10 +631,10 @@ PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void); 关键词/值连接字符串 - 在关键词/值格式中,每一个参数设置的形式都是关键词 = ,在设置之间有空白。 - 设置的等号周围的空白是可选的。 - 要写一个空值或一个包含空白的值,将它用单引号包围,例如关键词 = 'a value'。 - 值里面的单引号和反斜线必须用一个反斜线转义,即\'\\。 + 在关键词/值格式中,每一个参数设置的形式都是关键词 = ,设置之间以空格分隔。 + 设置的等号周围的空格是可选的。 + 要写一个空值或一个包含空格的值,将它用单引号包围,例如keyword = 'a value'。 + 值里面的单引号和反斜杠必须用一个反斜杠转义,即\'\\ @@ -674,22 +658,22 @@ host=localhost port=5432 dbname=mydb connect_timeout=10 postgresql://userspec@hostspec/dbname?paramspec -where userspec is: +其中 userspec 为: user:password -and hostspec is: +hostspec 为: host:port,... -and paramspec is: +paramspec 为: name=value&... - URI模式标志符可以是postgresql://postgres://。 + URI方案标识符可以是postgresql://postgres://。 每一个剩下的URI部分都是可选的。 下列示例展示了合法的URI语法: @@ -706,19 +690,15 @@ postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application postgresql:///mydb?host=localhost&port=5433 - 全部的命名参数必须匹配中列出的关键词,除了与JDBC连接URI兼容之外,ssl=true的实例转换到sslmode=require。 + 所有命名参数都必须与中列出的关键词匹配;唯一的例外是,为兼容 JDBC 连接 URI,会将 ssl=true 转换为 sslmode=require - 连接URI需要使用百分号编码 - 对其进行编码,如果其中包含具有特殊含义的符号。这里是一个示例,其中等号(=)被替换为 - %3D,空格字符被替换为 - %20: + 如果连接 URI 的任意部分包含具有特殊含义的符号,就需要使用百分号编码。下面的示例将等号(=)替换为 %3D,将空格字符替换为 %20 postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff - + 主机部分可能是主机名或一个 IP 地址。要指定一个 IPv6 地址,将它封闭在方括号中: @@ -731,7 +711,7 @@ postgresql://[2001:db8::1234]/database 主机组件会被按照参数对应的描述来解释。 特别地,如果主机部分是空或看起来像一个绝对路径名称,将使用一个 Unix 域套接字连接,否则将启动一个 TCP/IP 连接。 不过要注意,斜线是 URI 层次部分中的一个保留字符。 - 因此,要指定一个非标准的 Unix 域套接字目录,要么忽略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: + 因此,要指定一个非标准的 Unix 域套接字目录,要么省略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: postgresql:///dbname?host=/var/lib/postgresql postgresql://%2Fvar%2Flib%2Fpostgresql/dbname @@ -741,7 +721,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以在一个URI中指定多个主机,每一个都有一个可选的端口。 一个形式为postgresql://host1:port1,host2:port2,host3:port3/的URI等效于host=host1,host2,host3 port=port1,port2,port3形式的连接字符串。 - 如下所述,每一个主机都将被尝试,直到成功地建立一个连接。 + 如下所述,每一个主机都将被依次尝试,直到成功地建立一个连接。 @@ -751,7 +731,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以指定多个要连接的主机,这样它们会按给定的顺序被尝试。 - 在键/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 + 在关键词/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 在指定的每一个选项中都必须给出相同数量的元素,这样第一个hostaddr对应于第一个主机名,第二个hostaddr对应于第二个主机名,以此类推。 不过,如果仅指定一个port,它将被应用于所有的主机。 @@ -761,11 +741,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 不管是哪一种格式,单一的主机名可以被翻译成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 + 不管是哪一种格式,单一的主机名可以被解析成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 - 当多个主机被指定时或者单个主机名被翻译成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。 + 当多个主机被指定时或者单个主机名被解析成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。 @@ -787,14 +767,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 要连接的主机名。主机名如果主机名看起来像绝对路径名, - 则指定的是Unix域通信而不是TCP/IP通信;该值是存储套接字文件的目录的名称。 - (在Unix上,绝对路径名以斜杠开头。在Windows上,以驱动器号开头的路径也被识别。) - 如果主机名以@开头,则将其视为抽象命名空间中的Unix域套接字(目前在Linux和Windows上支持)。 - 当未指定host或为空时,默认行为是连接到Unix域套接字Unix域套接字在 - /tmp(或在构建PostgreSQL时指定的套接字目录)中。在Windows和 - 没有Unix域套接字的机器上,默认是连接到localhost。 - + 要连接的主机名。主机名如果主机名看起来像绝对路径名, + 则指定的是 Unix 域通信,而非 TCP/IP 通信;此值是存放套接字文件的目录名。 + (在 Unix 上,绝对路径名以斜杠开头。在 Windows 上,也会识别以驱动器号开头的路径。)如果主机名以 @ 开头,则将其视为抽象命名空间中的 Unix 域套接字(目前在 Linux 和 Windows 上支持)。 + 当未指定 host 或其值为空时,默认连接到 /tmp + (或构建 PostgreSQL 时指定的套接字目录)中的 Unix 域套接字。 + Unix 域套接字在 Windows 上,默认连接到 localhost。 + 也可以接受一个逗号分隔的主机名列表,此时列表中的每个主机名将按顺序尝试; @@ -822,7 +801,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 如果指定了host而没有指定hostaddr,则会发生主机名查找。 (当使用PQconnectPoll时,查找发生在PQconnectPoll首次考虑此主机名时, - 并且可能导致PQconnectPoll阻塞一段时间。) + 并且可能导致PQconnectPoll阻塞相当长的时间。) @@ -834,11 +813,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果同时指定了hosthostaddr, - 则hostaddr的值给出服务器的网络地址。 - 除非认证方法需要,否则host的值将被忽略, - 在这种情况下,它将用作主机名。 - + 如果同时指定了 hosthostaddr,则 hostaddr 的值给出服务器的网络地址。只有认证方法需要主机名时,才会将 host 的值用作主机名;否则忽略该值。 + 请注意,如果host不是网络地址hostaddr上服务器的名称, @@ -854,10 +830,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 没有主机名或主机地址, - libpq将使用本地的Unix域套接字进行连接; - 或者在Windows和没有Unix域套接字的机器上,它将尝试连接到localhost。 - + 如果既没有主机名也没有主机地址,libpq 会使用本地 Unix 域套接字连接;在 Windows 上,则会尝试连接到 localhost。 + @@ -891,8 +865,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - PostgreSQL用户连接的用户名。 - 默认为运行应用程序的操作系统用户名相同。 + 建立连接所用的 PostgreSQL 用户名。默认与运行应用程序的操作系统用户名相同。 @@ -902,7 +875,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果服务器要求密码认证,则使用密码。 + 服务器要求密码认证时所使用的密码。 @@ -923,7 +896,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname require_auth - 指定客户端要求服务器采用的认证方法。如果服务器没有使用所要求的方法来认证客户端,或者服务器没有完整完成认证握手,则连接将失败。也可以提供一个以逗号分隔的方法列表,此时服务器必须准确使用其中一种方法,连接才会成功。默认情况下接受任意认证方法,并且服务器也可以完全跳过认证。 + 指定客户端要求服务器采用的认证方法。如果服务器没有使用所要求的方法来认证客户端,或者服务器没有完整完成认证握手,则连接将失败。也可以提供一个以逗号分隔的方法列表,此时服务器必须恰好使用其中一种方法,连接才会成功。默认情况下接受任意认证方法,并且服务器也可以完全跳过认证。 可以在方法名前加上!前缀以表示否定,此时服务器不得尝试所列方法;除此之外,任何其他方法都可接受,并且服务器也可以完全不认证客户端。如果提供的是逗号分隔列表,服务器不得尝试其中任何一个被否定的方法。否定形式和非否定形式不能在同一设置中混用。 @@ -1001,7 +974,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 这个选项控制客户端对通道绑定的使用。设置为require表示连接必须使用通道绑定, prefer表示客户端将在可用时选择通道绑定, 而disable则阻止使用通道绑定。默认情况下, - 如果PostgreSQL是使用SSL支持编译的,则默认为prefer; + 如果PostgreSQL是使用SSL支持编译的,则默认为prefer; 否则默认为disable @@ -1065,9 +1038,9 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 指定配置参数的回退值。 + 指定配置参数的后备值。 如果没有通过连接参数或PGAPPNAME环境变量为application_name指定值, - 则将使用此值。在通用实用程序中指定回退名称很有用,该程序希望设置默认应用程序名称, + 则将使用此值。在通用实用程序中指定后备名称很有用,该程序希望设置默认应用程序名称, 但允许用户覆盖它。 @@ -1078,9 +1051,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制是否使用客户端TCP保持活动。默认值为1,表示开启,但如果不想要保持活动,可以将其更改为0,表示关闭。 - 对于通过Unix域套接字进行的连接,此参数将被忽略。 - + 控制是否使用客户端 TCP keepalive。默认值为 1,表示开启;如果不需要 keepalive,可以将其设为 0,表示关闭。对于通过 Unix 域套接字建立的连接,此参数会被忽略。 + @@ -1089,11 +1061,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在多少秒的不活动后,TCP应向服务器发送保持活动消息。值为零使用系统默认值。 - 对通过Unix域套接字进行的连接或禁用保持活动的连接,此参数将被忽略。 - 仅在支持TCP_KEEPIDLE或等效套接字选项的系统以及Windows上支持; - 在其他系统上,它没有任何效果。 - + 控制在多久没有活动后,TCP 应向服务器发送 keepalive 消息,以秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPIDLE 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -1102,11 +1071,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在服务器未确认的情况下重新传输TCP保持活动消息的秒数。值为零时使用系统默认值。 - 此参数在通过Unix域套接字进行连接或禁用保持活动时将被忽略。 - 仅在支持TCP_KEEPINTVL或等效套接字选项的系统和Windows上支持; - 在其他系统上,此参数无效。 - + 控制未被服务器确认收到的 TCP keepalive 消息在多少秒后应被重传。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPINTVL 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -1115,11 +1081,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在客户端与服务器之间连接被视为断开之前可以丢失的TCP keepalive数量。 - 值为零时使用系统默认值。对通过Unix域套接字建立的连接或禁用keepalives的连接,此参数将被忽略。 - 仅在支持TCP_KEEPCNT或等效套接字选项的系统上受支持; - 在其他系统上,此参数无效。 - + 控制在客户端与服务器之间的连接被视为中断之前,可以丢失多少个 TCP keepalive 消息。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPCNT 或等效套接字选项的系统上受支持;在其他系统上无效。 + @@ -1128,10 +1091,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在连接在强制关闭之前,传输数据可以保持未被确认的毫秒数。 - 值为零时使用系统默认值。此参数对通过Unix域套接字进行的连接无效。 - 仅在支持TCP_USER_TIMEOUT的系统上受支持;在其他系统上,它没有效果。 - + 控制已发送的数据在连接被强制关闭之前最多可以保持未确认状态多长时间,以毫秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,此参数会被忽略。此参数仅在支持 TCP_USER_TIMEOUT 的系统上受支持;在其他系统上无效。 + @@ -1194,25 +1155,25 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个选项确定是否以及如何优先与服务器协商安全的GSS TCP/IP连接。有三种模式: + 这个选项确定是否以及以何种优先级与服务器协商安全的GSS TCP/IP连接。有三种模式: disable - 仅尝试非GSSAPI加密连接 + 仅尝试未经GSSAPI加密的连接 - prefer (默认) + prefer (默认) 如果存在GSSAPI凭据(即在凭据缓存中),首先尝试 GSSAPI加密连接;如果失败或没有凭据,则尝试 - 非GSSAPI加密连接。这是在编译PostgreSQL时使用GSSAPI支持时的默认设置。 + 未经GSSAPI加密的连接。这是在编译PostgreSQL时使用GSSAPI支持时的默认设置。 @@ -1231,7 +1192,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname gssencmode在Unix域套接字通信中被忽略。如果PostgreSQL没有编译GSSAPI支持, 使用require选项将导致错误,而prefer将被接受,但libpq实际上不会尝试 - 进行GSSAPI加密连接。GSSAPI与libpq + 进行GSSAPI加密连接。GSSAPI在 libpq 中 @@ -1263,7 +1224,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - prefer (默认) + prefer (默认) 首先尝试SSL连接;如果失败,则尝试非SSL连接 @@ -1303,22 +1264,18 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - sslmode被忽略用于Unix域套接字通信。 - 如果PostgreSQL没有SSL支持编译, + 在 Unix 域套接字通信中,sslmode 会被忽略。 + 如果PostgreSQL编译时未启用 SSL 支持, 使用选项requireverify-caverify-full会导致错误,而选项allowprefer 将被接受,但libpq实际上不会尝试建立SSL 连接。SSL使用libpq的SSL + sortas="libpq">在 libpq 中 - 请注意,如果可能使用GSSAPI加密, - 则优先使用该加密,而不考虑SSL的值。要在具有可用GSSAPI - 基础设施(如Kerberos服务器)的环境中强制使用 - SSL加密,还需将 - gssencmode设置为disable。 - + 注意,如果可以使用 GSSAPI 加密,就会优先使用它而不是 SSL 加密,无论 sslmode 的值是什么。在具有可用 GSSAPI 基础设施(例如 Kerberos 服务器)的环境中,要强制使用 SSL 加密,还应将 gssencmode 设为 disable。 + @@ -1327,15 +1284,15 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 此选项已被sslmode设置所取代。 - + 此选项已弃用,请改用 sslmode 设置。 + 如果设置为1,则需要与服务器建立SSL连接(这相当于sslmode require)。libpq将拒绝连接,如果服务器不接受 SSL连接。如果设置为0(默认值), libpq将与服务器协商连接类型(相当于sslmode - prefer)。此选项仅在PostgreSQL编译时启用SSL支持。 + prefer)。此选项仅在 PostgreSQL 编译时启用了 SSL 支持的情况下可用。 @@ -1358,7 +1315,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果安全性不是主要考虑因素,压缩可以提高吞吐量,如果网络是瓶颈的话。如果CPU性能是限制因素,禁用压缩可以提高响应时间和吞吐量。 + 如果安全性不是主要考虑因素,压缩可以提高吞吐量,如果网络是瓶颈的话。如果CPU性能是限制因素,禁用压缩可以缩短响应时间并提高吞吐量。 @@ -1382,7 +1339,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 这个参数指定了用于客户端证书的密钥的位置。它可以指定一个文件名,该文件名将被用来替代默认的 ~/.postgresql/postgresql.key,或者它可以指定一个从外部引擎 - (引擎是OpenSSL可加载模块)获取的密钥。外部引擎规范应该包括一个由冒号分隔的引擎名称和 + (引擎是OpenSSL可加载模块)获取的密钥。外部引擎的指定形式应包含一个由冒号分隔的引擎名称和 一个引擎特定的密钥标识符。如果没有进行SSL连接,则此参数将被忽略。 @@ -1399,10 +1356,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 指定此参数为任何非空值将抑制Enter PEM pass phrase: - 当提供加密的客户端证书密钥给libpq时, - OpenSSL默认会发出的提示。 - + 当向 libpq 提供加密的客户端证书密钥时,将此参数指定为任意非空值,都将抑制 OpenSSL 默认发出的 Enter PEM pass phrase: 提示。 + 如果密钥未加密,则忽略此参数。该参数对由OpenSSL引擎指定的密钥没有影响,除非引擎使用OpenSSL密码回调机制进行提示。 @@ -1484,10 +1439,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定SSL服务器证书吊销列表(CRL)的文件名。如果存在该文件中列出的证书,在尝试验证服务器证书时将被拒绝。 - 如果既没有设置也没有设置, - 则将采用~/.postgresql/root.crl。 - + 此参数指定 SSL 服务器证书吊销列表(CRL)的文件名。如果该文件存在,在验证服务器证书时,会拒绝其中列出的证书。如果既未设置,也未设置,则采用 ~/.postgresql/root.crl。 + @@ -1496,8 +1449,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定SSL服务器证书吊销列表(CRL)的目录名称。如果存在该目录中的文件中列出的证书,在尝试验证服务器证书时将被拒绝。 - + 此参数指定 SSL 服务器证书吊销列表(CRL)的目录名。如果该目录存在,在验证服务器证书时,会拒绝该目录下文件中列出的证书。 + 目录需要使用OpenSSL命令 @@ -1512,11 +1465,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - sslsniServer Name Indication + sslsni服务器名称指示 - 如果设置为1(默认值),libpq会在启用SSL的连接上设置TLS扩展Server Name IndicationSNI)。 + 如果设置为1(默认值),libpq会在启用SSL的连接上设置TLS扩展服务器名称指示SNI)。 通过将此参数设置为0,可以关闭此功能。 @@ -1549,8 +1502,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定连接允许的最低SSL/TLS协议版本。有效值为TLSv1, - TLSv1.1TLSv1.2和 + 这个参数指定连接允许的最低SSL/TLS协议版本。有效值为TLSv1、 + TLSv1.1TLSv1.2TLSv1.3。支持的协议取决于所使用的 OpenSSL版本,旧版本不支持最现代的协议版本。 如果未指定,默认值为TLSv1.2,符合本文撰写时的行业最佳实践。 @@ -1563,11 +1516,10 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定连接允许的最大SSL/TLS协议版本。有效值为TLSv1, - TLSv1.1TLSv1.2和 + 这个参数指定连接允许的最大SSL/TLS协议版本。有效值为TLSv1、 + TLSv1.1TLSv1.2TLSv1.3。支持的协议取决于使用的OpenSSL - 版本,旧版本不支持最新的协议版本。如果未设置,将忽略此参数,并且连接将使用后端定义的最大限制, - 如果设置。设置最大协议版本主要用于测试或者某些组件无法使用较新协议时。 + 版本,旧版本不支持最新的协议版本。如果未设置,则忽略此参数;如果后端定义了最大限制,连接将使用该限制。设置最大协议版本主要用于测试或者某些组件无法使用较新协议时。 @@ -1581,13 +1533,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 用于使用GSSAPI进行认证时要使用的Kerberos服务名称。 + 使用 GSSAPI 认证时所用的 Kerberos 服务名。 这必须与服务器配置中指定的Kerberos认证服务名称匹配,才能成功进行认证。 (另请参见。) 默认值通常为postgres, - 但在构建PostgreSQL时可以通过 - 选项进行更改 - configure。 + 但在构建 PostgreSQL 时,可以通过 configure 选项更改。 在大多数环境中,通常不需要更改此参数。 一些Kerberos实现可能需要不同的服务名称, 例如Microsoft Active Directory需要服务名称为大写(POSTGRES)。 @@ -1611,7 +1561,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname gssdelegation - 将 GSS 凭证转发(委派)给服务器。默认值为0,表示不向服务器转发凭证。将其设置为1时,会在可能的情况下转发凭证。 + 将 GSS 凭据转发(委派)给服务器。默认值为0,表示不向服务器转发凭据。将其设置为1时,会在可能的情况下转发凭据。 @@ -1752,23 +1702,21 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 连接状态函数 - 这些函数可以被用来询问一个已有数据库连接对象的状态。 + 这些函数可用于查询现有数据库连接对象的状态。 - libpq-fe.h - libpq-int.h - libpq应用程序员应该小心地维护PGconn抽象。使用下面描述的访问函数来理解PGconn的内容。我们不推荐使用libpq-int.h引用内部的PGconn域,因为它们可能在未来改变。 - + libpq-fe.h + libpq-int.h + 编写 libpq 应用程序时,应注意维护 PGconn 的抽象。请使用下述访问函数获取 PGconn 的内容。不建议通过 libpq-int.h 引用 PGconn 的内部字段,因为这些字段将来可能改变。 + - 下列函数返回一个连接所建立的参数值。这些值在连接的生命期中是固定的。 - 如果使用的是多主机连接字符串,如果使用同一个PGconn对象建立新连接,,, 和 可能会改变。其他值在PGconn对象的一生中都是固定的。 - - + 以下函数返回建立连接时确定的参数值。这些值在连接存续期间保持不变。如果使用多主机连接字符串,并使用同一个 PGconn 对象建立新连接,则 的返回值可能改变。其他值在 PGconn 对象的整个生命周期内保持不变。 + PQdbPQdb @@ -1818,7 +1766,7 @@ char *PQpass(const PGconn *conn); - 返回活跃连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 + 返回活动连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 char *PQhost(const PGconn *conn); @@ -1830,7 +1778,7 @@ char *PQhost(const PGconn *conn); - 如果conn参数是NULL,则返回NULL。否则,如果有一个错误产生主机信息(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成主机信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1851,8 +1799,7 @@ char *PQhostaddr(const PGconn *conn); - 如果conn 参数为 NULL 返回 NULL 。 - 否则,如果生成主机信息时出现错误(如果连接尚未完全建立或出现错误),则返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成主机信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1862,7 +1809,7 @@ char *PQhostaddr(const PGconn *conn); - 返回活跃连接的端口。 + 返回活动连接的端口。 char *PQport(const PGconn *conn); @@ -1874,7 +1821,7 @@ char *PQport(const PGconn *conn); - 如果conn参数是NULL,则返回NULL。否则,如果有一个错误产生端口信息(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成端口信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1888,9 +1835,7 @@ char *PQport(const PGconn *conn); - 这个函数不再做任何事,但是它保持了向后兼容。 - 这个函数总是返回一个空字符串,或者NULL,如果connNULL。 - + 此函数已不再执行任何操作,但为保持向后兼容仍予以保留。如果 conn 参数为 NULL,则返回 NULL;否则始终返回空字符串。 char *PQtty(const PGconn *conn); @@ -1903,7 +1848,7 @@ char *PQtty(const PGconn *conn); - 返回被传递给连接请求的命令行选项。 + 返回连接请求中传递的命令行选项。 char *PQoptions(const PGconn *conn); @@ -1911,12 +1856,11 @@ char *PQoptions(const PGconn *conn); - + - 下列函数返回会随着在PGconn对象上执行的操作改变的状态数据。 - - + 以下函数返回的状态数据,可能随着对 PGconn 对象执行操作而改变。 + PQstatusPQstatus @@ -1952,7 +1896,7 @@ ConnStatusType PQstatus(const PGconn *conn); PGTransactionStatusType PQtransactionStatus(const PGconn *conn); - 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个合法的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接损坏,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE。 + 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个有效的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接异常,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE @@ -2008,13 +1952,11 @@ const char *PQparameterStatus(const PGconn *conn, const char *paramName); - 询问所使用的 前端/后端协议。 + 查询正在使用的前端/后端协议。 int PQprotocolVersion(const PGconn *conn); - 应用可能希望用这个函数来确定某些特性是否被支持。当前,可能值是3(3.0 协议)或零(连接损坏)。 - 协议版本在连接启动完成后将不会改变,但是理论上在连接重置期间是可以改变的。 - 3.0 协议被PostgreSQL 7.4 或以后的服务器版本所支持。 +应用程序可以使用此函数判断是否支持某些特性。目前,可能的值为 3(协议 3.0)或零(连接异常)。连接启动完成后,协议版本不会改变,但理论上可能在连接重置期间改变。PostgreSQL 7.4 及更高版本的服务器支持协议 3.0。 @@ -2035,11 +1977,11 @@ int PQserverVersion(const PGconn *conn); - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 + 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,为每个部分使用两位数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 + 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。在所有主版本系列中,各次版本(缺陷修复版本)之间只有最后两位数字不同。 @@ -2058,9 +2000,7 @@ char *PQerrorMessage(const PGconn *conn); - 几乎所有的libpq在失败时都会为设置一个消息。 - 注意按照libpq习惯,一个非空结果由多行构成,并且将包括一个尾部新行。 - 调用者不应该直接释放结果。当相关的PGconn句柄被传递给时,它将被释放。在PGconn结构体上的多个操作之间,不能指望结果字符串会保持不变。 + 几乎所有 libpq 函数在失败时都会设置一条供 返回的消息。注意,按照 libpq 的约定,非空的 结果可能包含多行,并以换行符结尾。调用者不应直接释放该结果;当关联的 PGconn 句柄被传给 时,结果会被释放。不能假定在对 PGconn 结构体执行其他操作后,结果字符串仍保持不变。 @@ -2069,7 +2009,7 @@ char *PQerrorMessage(const PGconn *conn); PQsocketPQsocket - 获得到服务器连接套接字的文件描述符号。一个合法的描述符将会大于等于零。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 + 获取与服务器相连的套接字的文件描述符编号。有效描述符大于或等于 0。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 int PQsocket(const PGconn *conn); @@ -2086,7 +2026,7 @@ int PQsocket(const PGconn *conn); 返回处理这个连接的后端进程的进程ID(PID)。 PID 确定服务器进程的 PID - in libpq + 在 libpq 中 @@ -2095,7 +2035,7 @@ int PQbackendPID(const PGconn *conn); - 后端PID有助于调试目的并且可用于与NOTIFY消息(它包括发出提示的后端进程的PID)进行比较。注意PID属于一个在数据库服务器主机上执行的进程,而不是本地主机进程! + 后端 PID 可用于调试,也可与 NOTIFY 消息进行比较(消息包含发出通知的后端进程的 PID)。注意,该 PID 属于在数据库服务器主机上运行的进程,而非本地主机上的进程! @@ -2150,19 +2090,18 @@ int PQconnectionUsedGSSAPI(const PGconn *conn); - + - 以下函数返回与SSL相关的信息。这些信息通常在建立连接后不会更改。 - - + 以下函数返回与 SSL 相关的信息。这些信息通常在连接建立后不会改变。 + PQsslInUsePQsslInUse - 返回true(1)如果连接使用SSL,返回false(0)如果不使用。 + 如果连接使用 SSL,则返回真(1);否则返回假(0)。 int PQsslInUse(const PGconn *conn); @@ -2178,7 +2117,7 @@ int PQsslInUse(const PGconn *conn); - 返回与连接相关的SSL信息。 + 返回连接的 SSL 相关信息。 const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); @@ -2190,7 +2129,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); - 常见的属性如下: + 通常可以获取以下属性: library @@ -2269,18 +2208,14 @@ const char * const * PQsslAttributeNames(const PGconn *conn); - 返回一个指向描述连接的SSL实现特定对象的指针。如果连接未加密或SSL实现不提供连接的请求对象类型,则返回NULL。 + 返回指向描述此连接的对象的指针,该对象的类型由 SSL 实现决定。如果连接未加密,或连接所用的 SSL 实现不提供所请求的对象类型,则返回 NULL。 void *PQsslStruct(const PGconn *conn, const char *struct_name); - 可用的结构体取决于正在使用的SSL实现。 - 对于OpenSSL,有一个结构体, - 可以通过名称OpenSSL获得, - 并返回一个指向OpenSSLSSL结构体的指针。 - 要使用这个函数,可以使用以下代码: + 可用的结构体取决于所使用的 SSL 实现。对于 OpenSSL,可以通过名称 OpenSSL 获取一个结构体,函数返回指向 OpenSSLSSL 结构体的指针。可以使用如下代码调用此函数: #include @@ -2331,7 +2266,7 @@ void *PQgetssl(const PGconn *conn); - + @@ -2340,7 +2275,7 @@ void *PQgetssl(const PGconn *conn); 命令执行函数 - 一旦到一个数据库服务器的连接被成功建立,这里描述的函数可以被用来执行 SQL 查询和命令。 + 与数据库服务器的连接成功建立后,此处描述的函数用于执行 SQL 查询和命令。 @@ -2362,11 +2297,8 @@ PGresult *PQexec(PGconn *conn, const char *command); - 返回一个PGresult指针或者可能是一个空指针。 - 除了内存不足的情况或者由于严重错误无法将命令发送给服务器之外,一般都会返回一个非空指针。 - 函数应当被调用来检查返回值是否代表错误(包括空指针的值,它会返回PGRES_FATAL_ERROR)。 - 用可得到关于那些错误的详细信息。 - + 返回一个 PGresult 指针,也可能返回空指针。除内存不足或无法向服务器发送命令等严重错误外,通常都会返回非空指针。应调用 函数检查返回值是否表示错误(也应检查空指针,此时该函数返回 PGRES_FATAL_ERROR)。使用 获取此类错误的更多信息。 + @@ -2447,8 +2379,8 @@ PGresult *PQexecParams(PGconn *conn, paramValues[] - 指定参数的实际值。这个数组中的一个空指针表示对应的参数为空,否则该指针指向一个以零终止的文本字符串(用于文本格式)或者以服务器所期待格式的二进制数据(用于二进制格式)。 - + 指定参数的实际值。数组中的空指针表示对应参数为 null;否则,指针指向以零结尾的文本字符串(文本格式),或采用服务器所要求格式的二进制数据(二进制格式)。 + @@ -2456,8 +2388,8 @@ PGresult *PQexecParams(PGconn *conn, paramLengths[] - 指定二进制格式参数的实际数据长度。它对空参数和文本格式参数被忽略。当没有二进制参数时,该数组指针可以为空。 - + 指定二进制格式参数的实际数据长度。对于 null 参数和文本格式参数,该值会被忽略。如果没有二进制参数,数组指针可以为空指针。 + @@ -2465,11 +2397,11 @@ PGresult *PQexecParams(PGconn *conn, paramFormats[] - 指定参数是否为文本(在参数相应的数组项中放一个零)或二进制(在参数相应的数组项中放一个一)。如果该数组指针为空,那么所有参数都会被假定为文本串。 - + 指定参数采用文本格式(在对应数组元素中填入零)还是二进制格式(填入一)。如果数组指针为空指针,则将所有参数视为文本字符串。 + - 以二进制格式传递的值要求后端所期待的内部表示形式的知识。例如,整数必须以网络字节序被传递。传递numeric值要求关于服务器存储格式的知识,正如src/backend/utils/adt/numeric.c::numeric_send()以及src/backend/utils/adt/numeric.c::numeric_recv()中所实现的。 - + 以二进制格式传递值时,需要了解后端所要求的内部表示形式。例如,整数必须以网络字节序传递。传递 numeric 值时,需要了解服务器的存储格式,其实现见 src/backend/utils/adt/numeric.c::numeric_send()src/backend/utils/adt/numeric.c::numeric_recv()。 + @@ -2477,8 +2409,8 @@ PGresult *PQexecParams(PGconn *conn, resultFormat - 指定零来得到文本格式的结果,或者指定一来得到二进制格式的结果(目前没有规定要求以不同格式得到不同的结果列,尽管在底层协议中这是可以实现的)。 - + 指定零以获取文本格式的结果,指定一以获取二进制格式的结果。(目前无法让不同结果列使用不同格式,尽管底层协议支持这样做。) + @@ -2489,8 +2421,8 @@ PGresult *PQexecParams(PGconn *conn, - 相对于的主要优点是参数值可以从命令串中分离,因此避免了冗长的书写、容易发生错误的引用以及转义。 - + 相对于 的主要优点是可以将参数值与命令字符串分开,从而避免繁琐且容易出错的加引号和转义工作。 + 不同,至多允许在给定串中出现一个 SQL 命令(其中可以有分号,但是不能有超过一个非空命令)。这是底层协议的一个限制,但是有助于抵抗 SQL 注入攻击。 @@ -2499,12 +2431,12 @@ PGresult *PQexecParams(PGconn *conn, - 通过 OID 指定参数类型很罗嗦,特别是如果你不愿意将特定的 OID 值硬编码到你的程序中时。不过,即使服务器本身也无法确定参数的类型,你可以避免这样做,或者选择一种与你想要的不同的类型。在 SQL 命令文本中,附加一个显式类型转换给参数符号来表示你将发送什么样的数据类型。例如: + 通过 OID 指定参数类型较为繁琐,尤其是在不希望将具体 OID 值写死在程序中时。不过,即使服务器无法自行确定参数类型,或者推断出的类型与你所需的不同,也可以避免直接指定 OID。在 SQL 命令文本中,为参数符号添加显式类型转换,即可指定要发送的数据类型。例如: SELECT * FROM mytable WHERE x = $1::bigint; - 这强制参数$1被当作bigint,而默认情况下它将被赋予与x相同的类型。当以二进制格式发送参数值时,我们强烈推荐以这种方式或通过指定一个数字类型的 OID 来强制参数类型决定。因为二进制格式比文本格式具有更少的冗余,并且因此服务器将不会有更多机会为你检测一个类型匹配错误。 - +这会强制将参数 $1 当作 bigint,而默认情况下会为它分配与 x 相同的类型。以二进制格式发送参数值时,强烈建议采用这种方式,或直接指定类型的数值 OID,来明确决定参数类型。因为二进制格式的冗余比文本格式更少,服务器发现类型不匹配错误的机会也更少。 + @@ -2525,15 +2457,15 @@ PGresult *PQprepare(PGconn *conn, - 创建一个后面会由执行的预备语句。 + 创建一个预备语句,供随后使用 执行。 这个特性允许命令被反复执行而无需每次都进行解析和规划,详见。 - + 该函数从query串创建一个名为stmtName的预备语句,该串必须包含一个单一 SQL 命令。 stmtName可以是""来创建一个未命名语句,在这种情况下任何已存在未命名语句将被自动替换。 否则,如果语句名称已经在当前会话中被定义,则是一种错误。如果使用了任何参数,它们在查询中以$1$2等引用。 - nParams是参数的个数,其类型在数组paramTypes[]中被预先指定(当nParams为零时,该数组指针可以是NULL)。 + nParams 是在数组 paramTypes[] 中预先指定了类型的参数数量(当nParams为零时,该数组指针可以是NULL)。 paramTypes[]通过 OID 指定要赋予给参数符号的数据类型。 如果paramTypesNULL或者该数组中任何特定元素为零,服务器会用对待未指定类型的字符串字面量的方式为参数符号推测一种数据类型。 还有,查询能够使用编号高于nParams的参数符号,它们的数据类型也会被自动推测(找出推测出的数据类型的方法见)。 @@ -2541,7 +2473,7 @@ PGresult *PQprepare(PGconn *conn, 正如一样,结果通常是一个PGresult对象,其内容代表服务器端成功或失败。 - 一个空结果表示内存不足或者根本无法发送命令。关于错误的更多信息请见。 + 返回空指针表示内存不足,或者根本无法发送命令。关于错误的更多信息请见 @@ -2574,9 +2506,9 @@ PGresult *PQexecPrepared(PGconn *conn, 类似于, - 但要执行的命令是通过指定先前准备好的语句来指定,而不是提供查询字符串。 - 此功能允许重复使用的命令只被解析和计划一次,而不是每次执行时都要进行。 - 该语句必须在当前会话中先前准备好。 + 但它通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。 + 此功能使重复使用的命令只需解析和规划一次,而不必在每次执行时都进行这些工作。 + 该语句必须事先在当前会话中创建为预备语句。 @@ -2593,23 +2525,23 @@ PGresult *PQexecPrepared(PGconn *conn, - 提交请求以获取有关指定准备好的语句的信息,并等待完成。 + 提交请求以获取有关指定预备语句的信息,并等待完成。 PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - 允许应用程序获取关于先前准备的语句的信息。 + 允许应用程序获取关于先前创建的预备语句的信息。 stmtName可以是""NULL来引用 - 未命名的语句,否则必须是现有准备好的语句的名称。成功时,返回一个 + 未命名的语句,否则必须是现有预备语句的名称。成功时,返回一个 状态为PGRES_COMMAND_OKPGresult。 函数可以应用于此 - PGresult以获取有关准备语句参数的信息, + PGresult以获取有关预备语句参数的信息, 函数等提供有关语句的结果列(如果有)的信息。 @@ -2623,22 +2555,21 @@ PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - 提交请求以获取有关指定门户的信息,并等待完成。 + 提交请求以获取有关指定 portal 的信息,并等待完成。 PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - 允许应用程序获取有关先前创建的portal的信息。 - (libpq不直接提供对portals的访问,但您可以使用此函数检查使用DECLARE CURSOR SQL命令创建的游标的属性。) - + 允许应用程序获取先前创建的 portal 的信息。(libpq 不提供对 portal 的直接访问,但可以用此函数检查通过 DECLARE CURSOR SQL 命令创建的游标的属性。) + - portalName可以是""NULL来引用未命名的portal, - 否则必须是现有portal的名称。成功时,将返回一个带有状态PGRES_COMMAND_OKPGresult。 + portalName可以是""NULL来引用未命名的 portal, + 否则必须是现有 portal 的名称。成功时,将返回一个带有状态PGRES_COMMAND_OKPGresult。 函数等可应用于 - PGresult,以获取有关portal的结果列(如果有)的信息。 + PGresult,以获取有关 portal 的结果列(如果有)的信息。 @@ -2650,9 +2581,8 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - PGresultPGresult结构体封装了由服务器返回的结果。libpq应用程序员应该小心地维护PGresult的抽象。使用下面的存储器函数来得到PGresult的内容。避免直接引用PGresult结构体的域,因为它们可能在未来更改。 - - + PGresultPGresult 结构体封装服务器返回的结果。编写 libpq 应用程序时,应注意维护 PGresult 的抽象。请使用下述访问函数获取 PGresult 的内容。避免直接引用 PGresult 结构体的字段,因为这些字段将来可能改变。 + PQresultStatusPQresultStatus @@ -2753,7 +2683,7 @@ ExecStatusType PQresultStatus(const PGresult *res); PGRES_SINGLE_TUPLE - PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单一行模式时发生(见)。 + PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单行模式时发生(见)。 @@ -2779,7 +2709,7 @@ ExecStatusType PQresultStatus(const PGresult *res); - 如果结果状态是PGRES_TUPLES_OKPGRES_SINGLE_TUPLEPGRES_TUPLES_CHUNK,则可以使用下面描述的函数来提取查询返回的行。注意,恰好检索到零行的SELECT命令仍然显示为PGRES_TUPLES_OKPGRES_COMMAND_OK用于永远不会返回行的命令(例如没有RETURNING子句的INSERTUPDATE等)。返回PGRES_EMPTY_QUERY可能表示客户端软件中存在缺陷。 + 如果结果状态是PGRES_TUPLES_OKPGRES_SINGLE_TUPLE,则可以使用下面描述的函数来提取查询返回的行。注意,恰好检索到零行的SELECT命令仍然显示为PGRES_TUPLES_OKPGRES_COMMAND_OK用于永远不会返回行的命令(例如没有RETURNING子句的INSERTUPDATE等)。返回PGRES_EMPTY_QUERY可能表示客户端软件中存在缺陷。 @@ -2793,12 +2723,11 @@ ExecStatusType PQresultStatus(const PGresult *res); - 将返回的枚举转换成描述状态编码的字符串常量。调用者不应该释放结果。 - + 将 返回的枚举值转换为描述该状态码的字符串常量。调用者不应释放此结果。 char *PQresStatus(ExecStatusType status); - + @@ -2807,12 +2736,12 @@ char *PQresStatus(ExecStatusType status); - 返回与该命令相关的错误消息,如果有错误则会返回一个空字符串。 + 返回与命令关联的错误消息;如果没有错误,则返回空字符串。 char *PQresultErrorMessage(const PGresult *res); - 如果有一个错误,被返回的字符串将包含一个收尾的新行。调用者不应该直接释放结果。它将在相关的PGresult句柄被传递给之后被释放。 - +如果发生了错误,返回的字符串会以换行符结尾。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 + 紧跟着一个调用,(在连接上)将返回与相同的字符串(在结果上)。 @@ -2828,16 +2757,14 @@ char *PQresultErrorMessage(const PGresult *res); - 返回与PGresult对象相关的错误消息的重新格式化的版本。 + 返回与 PGresult 对象关联的错误消息的重新格式化版本。 char *PQresultVerboseErrorMessage(const PGresult *res, PGVerbosity verbosity, PGContextVisibility show_context); - 在有些情况下,客户端可能希望得到之前报告过的错误的更加详尽的版本。 - 如果在产生给定PGresult的连接上 verbosity 设置有效,会通过计算已经被产生过的消息来满足这种需求。 - 如果PGresult不是一个错误结果,则会报告PG 结果不是错误结果。返回的字符串包括一个新行作为结尾。 - +有时客户端希望获取先前报告过的错误的更详细版本。 可满足这一需求:它按指定的详细程度设置重新生成消息。假如在生成给定 PGresult 时,连接已经采用这些设置,那么 返回的就会是这条消息。如果 PGresult 不是错误结果,则改为报告 PGresult is not an error result。返回的字符串以换行符结尾。 + 和大部分从PGresult中提取数据的其他函数不同,这个函数的结果是一个全新分配的字符串。调用者在不需要这个字符串以后,必须使用PQfreemem()释放它。 @@ -2853,24 +2780,21 @@ char *PQresultVerboseErrorMessage(const PGresult *res, PQresultErrorFieldPQresultErrorField - 返回一个错误报告的一个域。 + 返回错误报告中的单个字段。 char *PQresultErrorField(const PGresult *res, int fieldcode); - fieldcode是一个错误域标识符,见下列符号。 - 如果PGresult不是一个错误或者警告结果或者不包括指定域,会返回NULL。 - 域通常不包括一个收尾的新行。调用者不应该直接释放结果。 - 它将在相关的PGresult句柄被传递给之后被释放。 - +fieldcode 是错误字段标识符,参见下文列出的符号。如果 PGresult 不是错误或警告结果,或者不包含指定字段,则返回 NULL。字段值通常不含末尾换行符。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 + - 下列域代码可用: + 下列字段代码可用: PG_DIAG_SEVERITY - 严重性。域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 @@ -2879,17 +2803,17 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_SEVERITY_NONLOCALIZED - 域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY域相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 版本以后产生的报告中。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY字段相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 及更高版本产生的报告中。 PG_DIAG_SQLSTATEerror codeslibpq + >错误码libpq - 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个域无法被本地化,并且总是存在。 + 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个字段无法被本地化,并且总是存在。 @@ -2916,7 +2840,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_MESSAGE_HINT - 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是铁的事实。可能有多行。 + 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是确切事实。可能有多行。 @@ -2934,7 +2858,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_INTERNAL_POSITION - 这被定义为与PG_DIAG_STATEMENT_POSITION域相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个域出现时,PG_DIAG_INTERNAL_QUERY域将总是出现。 + 这被定义为与PG_DIAG_STATEMENT_POSITION字段相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个字段出现时,PG_DIAG_INTERNAL_QUERY字段将总是出现。 @@ -2952,7 +2876,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONTEXT - 指示错误发生的环境。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 + 指示错误发生的上下文。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 @@ -2970,7 +2894,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_TABLE_NAME - 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名域)。 + 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名字段)。 @@ -2979,7 +2903,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_COLUMN_NAME - 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名域来标识该表)。 + 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名字段来标识该表)。 @@ -2988,7 +2912,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_DATATYPE_NAME - 如果错误与一个特定数据类型相关,这里是该数据了行的名字(该数据类型的模式名参考模式名域)。 + 如果错误与一个特定数据类型相关,这里是该数据类型的名字(该数据类型的模式名参考模式名字段)。 @@ -2997,7 +2921,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONSTRAINT_NAME - 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的域(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 + 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的字段(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 @@ -3033,16 +2957,16 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); - 用于模式名、表名、列名、数据类型名和约束名的域只提供给有限的错误类型,见。不要假定任何这些域的存在保证另一个域的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些域。同样地,不要假定这些域代表当前数据库中同类的对象。 + 用于模式名、表名、列名、数据类型名和约束名的字段只提供给有限的错误类型,见。不要假定任何这些字段的存在保证另一个字段的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些字段。同样地,不要假定这些字段代表当前数据库中现存的对象。 - 客户端负责格式化显示信息来迎合它的需要,特别是根据需要打断长的行。出现在错误消息域中的新行字符应该被当作分段而不是换行。 + 客户端负责按自身需要格式化所显示的信息,尤其应在需要时将长行折行。错误消息字段中的换行符应当视为段落分隔,而非行分隔。 - libpq内部产生的错误将有严重和主要消息,但是通常没有其他域。 + libpq内部产生的错误将包含严重性和主要消息,但是通常没有其他字段。 @@ -3055,14 +2979,12 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PQclearPQclear - 释放与一个PGresult关联的存储。每个命令结果在不再需要时都应通过释放。 - + 释放与 PGresult 关联的存储空间。每个命令结果在不再需要时都应通过 释放。 void PQclear(PGresult *res); - - 如果参数是NULL指针,则不会执行任何操作。 - +如果参数是 NULL 指针,则不执行任何操作。 + 你可以在需要时一直保留PGresult对象;它不会在你发出新命令时消失,甚至在关闭连接后也不会消失。要销毁它,你必须调用。否则应用程序会发生内存泄漏。 @@ -3070,7 +2992,7 @@ void PQclear(PGresult *res); - + @@ -3078,8 +3000,8 @@ void PQclear(PGresult *res); 检索查询结果信息 - 这些函数被用来从一个代表成功查询结果(也就是状态为PGRES_TUPLES_OK或者PGRES_SINGLE_TUPLE)的PGresult对象中抽取信息。它们也可以被用来从一个成功的 Describe 操作中抽取信息:一个 Describe 的结果具有和该查询被实际执行所提供的完全相同的列信息,但是它没有行。对于其他状态值的对象,这些函数会认为结果具有零行和零列。 - + 这些函数用于从表示成功查询结果的 PGresult 对象中提取信息,即状态为 PGRES_TUPLES_OKPGRES_SINGLE_TUPLE 的对象。它们也可用于提取成功 Describe 操作的结果信息:Describe 结果包含的列信息与实际执行查询时相同,但行数为零。对于其他状态值的对象,这些函数会将结果视为零行、零列。 + @@ -3106,7 +3028,7 @@ int PQntuples(const PGresult *res); - 返回查询结果中每一行的列(域)数。 + 返回查询结果中每一行的列(字段)数。 int PQnfields(const PGresult *res); @@ -3122,7 +3044,7 @@ int PQnfields(const PGresult *res); - 返回与给定列号相关联的列名。列号从 0 开始。调用者不应该直接释放该结果。它将在相关的PGresult句柄被传递给之后被释放。 + 返回给定列号对应的列名。列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 char *PQfname(const PGresult *res, int column_number); @@ -3154,11 +3076,11 @@ int PQfnumber(const PGresult *res, - 给定的名称被视作一个 SQL 命令中的一个标识符,也就是说,除非被双引号引用,它是小写形式的。例如,给定一个 SQL 命令: + 给定名称按 SQL 命令中的标识符处理,即除非用双引号引用,否则会转换为小写。例如,对于以下 SQL 命令生成的查询结果: SELECT 1 AS FOO, 2 AS "BAR"; - 我们将得到结果: +会得到以下结果: PQfname(res, 0) foo PQfname(res, 1) BAR @@ -3178,7 +3100,7 @@ PQfnumber(res, "\"BAR\"") 1 - 返回给定列从中取出的表的 OID。列号从 0 开始。 + 返回给定列所取自的表的 OID。列号从 0 开始。 Oid PQftable(const PGresult *res, int column_number); @@ -3191,7 +3113,7 @@ Oid PQftable(const PGresult *res, - 当你包括libpq头文件,类型oid以及常数InvalidOid将被定义。它们将都是某种整数类型。 + 包含 libpq 头文件后,将定义类型 Oid 和常量 InvalidOid。它们都属于某种整数类型。 @@ -3203,7 +3125,7 @@ Oid PQftable(const PGresult *res, - 返回构成指定查询结果列的列(在其表中)的列号。查询结果列号从 0 开始,但是表列具有非零编号。 + 返回指定查询结果列所对应的表列在表中的列号。查询结果的列号从 0 开始,而表列的编号非零。 int PQftablecol(const PGresult *res, int column_number); @@ -3223,7 +3145,7 @@ int PQftablecol(const PGresult *res, - 返回指示给定列格式的格式编码。列号从 0 开始。 + 返回表示给定列格式的格式代码。列号从 0 开始。 int PQfformat(const PGresult *res, int column_number); @@ -3231,7 +3153,7 @@ int PQfformat(const PGresult *res, - 格式代码零指示文本数据表示,而格式代码一表示二进制表示(其他代码被保留用于未来的定义)。 + 格式代码零表示文本数据,格式代码一表示二进制数据。(其他代码保留供将来定义。) @@ -3251,7 +3173,7 @@ Oid PQftype(const PGresult *res, - 你可以查询系统表pg_type来得到多个数据类型的名字和属性。 + 你可以查询系统表pg_type来获取各种数据类型的名称和属性。 内置数据类型的OID被定义在PostgreSQL安装的include目录中的catalog/pg_type_d.h文件中。 @@ -3264,7 +3186,7 @@ Oid PQftype(const PGresult *res, - 返回与给定列号相关联的列的修饰符类型。列号从 0 开始。 + 返回与给定列号相关联的列的类型修饰符。列号从 0 开始。 int PQfmod(const PGresult *res, int column_number); @@ -3272,7 +3194,7 @@ int PQfmod(const PGresult *res, - 修饰符值的解释是与类型相关的,它们通常指示精度或尺寸限制。值 -1 被用来指示没有信息可用。大部分的数据类型不适用修饰符,在那种情况中值总是 -1。 + 修饰符值的含义由数据类型决定,通常表示精度或大小限制。值 -1 表示没有可用信息。大多数数据类型不使用修饰符,此时该值始终为 -1。 @@ -3284,7 +3206,7 @@ int PQfmod(const PGresult *res, - 返回与给定列号相关的列的尺寸(以字节计)。列号从 0 开始。 + 返回给定列号对应列的大小,以字节计。列号从 0 开始。 int PQfsize(const PGresult *res, int column_number); @@ -3292,7 +3214,7 @@ int PQfsize(const PGresult *res, - 返回在一个数据库行中为这个列分配的空间,换句话说是服务器对该数据类型的内部表示的尺寸(因此,它对客户端并不是真地非常有用)。一个负值指示该数据类型是变长的。 + 返回数据库行中为该列分配的空间,即服务器内部表示该数据类型所需的大小。(因此,它对客户端用处不大。)负值表示该数据类型是变长类型。 @@ -3311,8 +3233,7 @@ int PQbinaryTuples(const PGresult *res); - 这个函数已经被废弃(除了与COPY一起使用),因为一个单一PGresult可以在某些列中包含文本数据而且在另一些列中包含二进制数据。 - 要更好。只有结果的所有列是二进制(格式 1)时才返回 1。 + 此函数已弃用(与 COPY 配合使用的情况除外),因为单个 PGresult 可能在部分列中包含文本数据,而在其他列中包含二进制数据。推荐使用 。只有结果中的所有列都采用二进制格式(格式 1)时, 才返回 1。 @@ -3324,8 +3245,7 @@ int PQbinaryTuples(const PGresult *res); - 返回一个PGresult的一行的单一域值。行和列号从 0 开始。调用者不应该直接释放该结果。 - 它将在相关的PGresult句柄被传递给之后被释放。 + 返回 PGresult 中某一行的单个字段值。行号和列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 char *PQgetvalue(const PGresult *res, int row_number, @@ -3334,15 +3254,15 @@ char *PQgetvalue(const PGresult *res, - 对于文本格式的数据,返回的值是该域值的一种空值结束的字符串表示。对于二进制格式的数据,该值是由该数据类型的typsendtypreceive函数决定的二进制表示(在这种情况下该值实际上也跟随着一个零字节,但是这通常没有用处,因为该值很可能包含嵌入的空)。 + 对于文本格式的数据, 返回字段值的字符串表示,以零字节结尾。对于二进制格式的数据,返回值采用该数据类型的 typsendtypreceive 函数所决定的二进制表示。(这种情况下,值后面实际上也有一个零字节,但通常没有用处,因为值本身很可能包含零字节。) - 如果该域值为空,则返回一个空串。关于区分空值和空字符串值请见。 + 如果字段值为 null,则返回空字符串。关于如何区分 null 值与空字符串值,参见 - 返回的指针指向作为PGresult结构体一部分的存储。我们不应该修改它指向的数据,并且如果要在超过PGresult结构体本身的生命期之外使用它,我们必须显式地把该数据拷贝到其他存储中。 + 返回的指针指向属于 PGresult 结构体的存储空间。不应修改它所指向的数据;如果需要在 PGresult 结构体的生命周期结束后继续使用这些数据,就必须显式地将数据复制到其他存储空间。 @@ -3351,12 +3271,12 @@ char *PQgetvalue(const PGresult *res, PQgetisnullPQgetisnullnull valuein libpq + >null 值libpq 中的 - 测试一个域是否为空值。行号和列号从 0 开始。 + 检查字段是否为 null 值。行号和列号从 0 开始。 int PQgetisnull(const PGresult *res, int row_number, @@ -3365,7 +3285,7 @@ int PQgetisnull(const PGresult *res, - 如果该域是空,这个函数返回 1。如果它包含一个非空值,则返回 0(注意将为一个空域返回一个空串,不是一个空指针)。 + 如果字段为 null,此函数返回 1;如果包含非 null 值,则返回 0。(注意,对于 null 字段, 返回空字符串,而非空指针。) @@ -3377,7 +3297,7 @@ int PQgetisnull(const PGresult *res, - 返回一个域值的真实长度,以字节计。行号和列号从 0 开始。 + 返回字段值的实际长度,以字节计。行号和列号从 0 开始。 int PQgetlength(const PGresult *res, int row_number, @@ -3386,9 +3306,7 @@ int PQgetlength(const PGresult *res, - 这是特定数据值的真实数据长度,也就是指向的对象的尺寸。 - 对于文本数据格式,这和strlen()相同。对于二进制格式这是基本信息。 - 注意我们应该依赖于来得到真值的数据长度。 + 这是该数据值的实际数据长度,即 所指对象的大小。对于文本格式的数据,它与 strlen() 的结果相同。对于二进制格式,这是必不可少的信息。注意,不应依赖 来获取实际数据长度。 @@ -3407,7 +3325,7 @@ int PQnparams(const PGresult *res); - 只有在查看的结果时,这个函数才有用。对于其他类型的查询,它将返回零。 + 只有在查看的结果时,这个函数才有用。对于其他类型的结果,它将返回零。 @@ -3426,7 +3344,7 @@ Oid PQparamtype(const PGresult *res, int param_number); - 只有在查看的结果时,这个函数才有用。对于其他类型的查询,它将返回零。 + 只有在查看的结果时,这个函数才有用。对于其他类型的结果,它将返回零。 @@ -3438,29 +3356,29 @@ Oid PQparamtype(const PGresult *res, int param_number); - 将所有的行打印到指定的输出流,以及有选择地将列名打印到指定的输出流。 + 将所有行输出到指定的输出流,并可选择输出列名。 void PQprint(FILE *fout, /* 输出流 */ const PGresult *res, const PQprintOpt *po); typedef struct { - pqbool header; /* 打印输出域标题和行计数 */ - pqbool align; /* 填充对齐域 */ - pqbool standard; /* 旧的格式 */ + pqbool header; /* 打印输出字段标题和行数 */ + pqbool align; /* 填充并对齐字段 */ + pqbool standard; /* 旧的简陋格式 */ pqbool html3; /* 输出 HTML 表格 */ - pqbool expanded; /* 扩展表格 */ - pqbool pager; /* 如果必要为输出使用页 */ - char *fieldSep; /* 域分隔符 */ + pqbool expanded; /* 展开表格 */ + pqbool pager; /* 需要时使用分页器输出 */ + char *fieldSep; /* 字段分隔符 */ char *tableOpt; /* 用于 HTML 表格元素的属性 */ char *caption; /* HTML 表格标题 */ - char **fieldName; /* 替换域名称的空终止数组 */ + char **fieldName; /* 以空指针结尾的替换字段名数组 */ } PQprintOpt; - 这个函数以前被psql用来打印查询结果,但是现在不是这样了。注意它假定所有的数据都是文本格式。 + psql 以前用此函数打印查询结果,现在已不再使用。注意,此函数假定所有数据都是文本格式。 @@ -3509,13 +3427,7 @@ char *PQcmdTuples(PGresult *res); - 该函数返回一个字符串,其中包含由生成PGresultSQL语句影响的行数。 - 该函数只能在执行SELECTCREATE TABLE AS、 - INSERTUPDATEDELETE、 - MERGEMOVEFETCHCOPY语句, - 或包含INSERTUPDATEDELETEMERGE语句的预处理查询的EXECUTE之后使用。 - 如果生成PGresult的命令是其他任何命令,将返回一个空字符串。 - 调用者不应直接释放返回值。当关联的PGresult句柄传递给时,它将被释放。 + 此函数返回一个字符串,其中包含产生该 PGresultSQL 语句所影响的行数。此函数只能在执行 SELECTCREATE TABLE ASINSERTUPDATEDELETEMERGEMOVEFETCHCOPY 语句之后使用,也可以在对包含 INSERTUPDATEDELETEMERGE 语句的预备查询执行 EXECUTE 之后使用。如果产生 PGresult 的是其他命令, 将返回空字符串。调用者不应直接释放返回值;当关联的 PGresult 句柄被传给 时,返回值会被释放。 @@ -3527,7 +3439,7 @@ char *PQcmdTuples(PGresult *res); - 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDin libpq。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid。 + 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDlibpq 中的。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid Oid PQoidValue(const PGresult *res); @@ -3542,7 +3454,7 @@ Oid PQoidValue(const PGresult *res); - 这个函数已经被取代,并且不是线程安全的。它返回包含被插入行的 OID 的一个字符串,而返回 OID 值。 + 此函数不是线程安全的,现已弃用,推荐改用 。它返回包含插入行 OID 的字符串,而 返回 OID 值。 char *PQoidStatus(const PGresult *res); @@ -3560,7 +3472,7 @@ char *PQoidStatus(const PGresult *res); 转义字符串 - in libpq + libpq 中的 @@ -3578,17 +3490,13 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); 为了让一个字符串可用于 SQL 命令,会对它进行转义。 - 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜线)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 + 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜杠)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 执行这种操作。 - 返回一个str参数的已被转义版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - 返回字符串中的所有特殊字符都会被替换,这样它们就能被PostgreSQL字符串字面量解析器正确处理。 - 结果中也会附加一个终止零字节,并包含包围PostgreSQL字符串字面量所需的单引号。 - + 返回 str 参数的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便 PostgreSQL 字符串字面量解析器正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号包含在结果字符串中。 + 发生错误时,返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -3602,7 +3510,7 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); - 注意,当一个数据值被作为或其兄弟例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 + 注意,当一个数据值被作为或相关例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 @@ -3620,15 +3528,12 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - 转义一个要用作 SQL 标识符的字符串,例如表名、列名或函数名。当一个用户提供的标识符可能包含被 SQL 解析器解释为标识符一部分的特殊字符时,或者当该标识符可能包含大小写形式应该被保留的大写字符时,这个函数很有用。 - + 对字符串进行转义,使其可用作 SQL 标识符,例如表名、列名或函数名。当用户提供的标识符可能包含未经转义就不会被 SQL 解析器视为标识符一部分的特殊字符,或包含需要保留大小写的大写字符时,此函数很有用。 + - 返回一个str参数的已被转义为 SQL 标识符的版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - 返回串中的所有特殊字符都被替换掉,这样它们能被作为一个 SQL 标识符正确地处理。还会加上一个终止零字节。返回串也将被双引号包围。 - + 返回 str 参数作为 SQL 标识符的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,必须使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便正确地作为 SQL 标识符处理。还会添加一个末尾零字节,并用双引号包围返回的字符串。 + 发生错误时,返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -3637,7 +3542,7 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - 与字符串一样,要阻止 SQL 注入攻击,当从一个不可信的来源接收到 SQL 标识符时,它们必须被转义。 + 与字符串字面量一样,为防止 SQL 注入攻击,从不可信来源接收到的 SQL 标识符必须经过转义。 @@ -3658,18 +3563,12 @@ size_t PQescapeStringConn(PGconn *conn, - 转义字符串,它很像。 - 与不一样的是,调用者负责提供一个合适尺寸的缓冲区。 - 此外,不产生必须包围PostgreSQL字符串的单引号。 - 它们应该在结果要插入的 SQL 命令中提供。参数from指向要被转义的串的第一个字符,并且length参数给出了这个串中的字节数。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - to应当指向一个缓冲区,它能够保持至少比length值的两倍还要多至少一个字节,否则该行为是未被定义的。 - 如果tofrom串重叠,行为也是未被定义的。 - + 对字符串字面量进行转义,与 类似。与 不同,调用者需要提供大小合适的缓冲区。此外, 不会生成包围 PostgreSQL 字符串字面量所需的单引号;应在包含转义结果的 SQL 命令中提供这些引号。from 参数指向待转义字符串的首字符,length 参数给出该字符串的字节数。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)to 必须指向一个缓冲区,其容量至少为 length 的两倍加一个字节,否则行为未定义。如果 tofrom 字符串重叠,行为同样未定义。 + - 如果error参数不是NULL,那么成功时*error被设置为零,错误时设置为非零。当前唯一可能的错误情况涉及源串中非法的多字节编码。错误时仍然会产生输出串,但是可以预期服务器将认为它是畸形的并且拒绝它。在发生错误时,一个合适的消息被存储在conn对象中,不管error是不是NULL。 - + 如果 error 参数不是 NULL,则成功时将 *error 设为零,出错时设为非零。目前唯一可能的错误是源字符串中存在无效的多字节编码。出错时仍会生成输出字符串,但预计服务器会因其格式错误而拒绝它。发生错误时,无论 error 是否为 NULL,都会在 conn 对象中保存相应消息。 + 返回写到to的字节数,不包括终止的零字节。 @@ -3684,21 +3583,19 @@ size_t PQescapeStringConn(PGconn *conn, - 是一个更老的被废弃的版本。 + 的旧版本,现已弃用。 size_t PQescapeString (char *to, const char *from, size_t length); - + - 之间的唯一区别是不需要PGconnerror参数。 - 正因为如此,它不能基于连接属性(例如字符编码)调整它的行为并且因此它可能给出错误的结果。还有,它没有方法报告错误情况。 - + 与 唯一的区别是, 不接受 PGconnerror 参数。因此,它无法根据连接属性(例如字符编码)调整行为,可能给出错误的结果。此外,它也无法报告错误情况。 + - 可以在一次只使用一个PostgreSQL连接的客户端程序中安全地使用(在这种情况下它可以在现象后面找出它需要知道的东西)。 - 在其他环境中它是一个安全性灾难并且应该用来避免。 - + 可以在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。在其他情形下,它存在安全隐患,应改用 。 + @@ -3709,7 +3606,7 @@ size_t PQescapeString (char *to, const char *from, size_t length); - 把要用于一个 SQL 命令的二进制数据用类型bytea转义。和一样,只有在将数据直接插入到一个 SQL 命令串时才使用它。 + 对二进制数据进行转义,使其能够在 SQL 命令中用作 bytea 类型的值。与 一样,这仅用于将数据直接插入 SQL 命令字符串的情况。 unsigned char *PQescapeByteaConn(PGconn *conn, const unsigned char *from, @@ -3724,14 +3621,11 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - from参数指向要被转义的串的第一个字节,并且from_length参数给出这个二进制串中的字节数(一个终止的零字节是不需要的也是不被计算的)。to_length参数指向一个将保持生成的已转义串长度的变量。这个结果串长度包括结果的终止零字节。 + from 参数指向待转义字符串的首字节,from_length 参数给出该二进制字符串的字节数。(末尾零字节既不需要,也不计入长度。)to_length 参数指向用于保存转义后字符串长度的变量。该结果字符串长度包含结果末尾的零字节。 - 返回一个from参数的已被转义为二进制串的版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 返回串中的所有特殊字符都被替换掉,这样它们能被PostgreSQL的字符串解析器以及bytea输入函数正确地处理。 - 还会加上一个终止零字节。不是结果串一部分的PostgreSQL字符串必须被单引号包围。 + 返回 from 参数所指二进制字符串的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。返回字符串中的所有特殊字符都已替换,以便 PostgreSQL 字符串字面量解析器和 bytea 输入函数正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号不包含在结果字符串中。 @@ -3747,7 +3641,7 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - 是一个更老的被废弃的版本。 + 的旧版本,现已弃用。 unsigned char *PQescapeBytea(const unsigned char *from, size_t from_length, @@ -3756,9 +3650,7 @@ unsigned char *PQescapeBytea(const unsigned char *from, - 与的唯一区别是不用一个PGconn参数。 - 正因为这样,只能在一次只使用一个PostgreSQL连接的客户端程序中安全地使用(在这种情况下它可以在现象后面找出它需要知道的东西)。 - 如果在有多个数据库连接的程序中使用,它可能给出错误的结果(在那种情况下使用)。 + 与 唯一的区别是, 不接受 PGconn 参数。因此, 只能在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。如果在使用多个数据库连接的程序中使用,它可能给出错误的结果(此时应使用 )。 @@ -3830,21 +3722,15 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - 总是收集命令的整个结果,把它缓存在一个单一的PGresult中。虽然这简化了应用的错误处理逻辑,它对于包含很多行的结果并不现实。 - + 总是收集命令的完整结果,并将其缓存在单个 PGresult 中。这简化了应用程序的错误处理逻辑,但对于包含大量行的结果,可能不切实际。 + - 如果应用程序不希望受到这些限制,可以改用构成的底层函数:。此外,还有, - , - , - ,以及,它们可以与配合使用,分别实现以下函数的功能:, - , - , - ,以及。 - - + + 如果应用程序不希望受到这些限制,可以改用构成 的底层函数:。此外, 可以与 配合使用,分别实现 的功能。 + PQsendQueryPQsendQuery @@ -3852,14 +3738,11 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - 提交一个命令到服务器,而不等待结果。 - 如果成功发送命令,则返回1,如果失败则返回0(在这种情况下,使用获取更多关于失败的信息)。 + 向服务器提交命令,不等待结果。命令发送成功时返回 1,否则返回 0(此时可使用 获取更多失败信息)。 int PQsendQuery(PGconn *conn, const char *command); - - 成功调用后,调用一次或多次来获取结果。 - 在返回空指针,表示命令执行完成之前,无法再次调用(在同一连接上)。 +成功调用 后,应调用 一次或多次来获取结果。在 返回空指针、表明命令已完成之前,不得在同一连接上再次调用 @@ -3875,7 +3758,7 @@ int PQsendQuery(PGconn *conn, const char *command); - 提交一个命令和参数到服务器,而不等待结果。 + 向服务器提交命令及独立指定的参数,不等待结果。 int PQsendQueryParams(PGconn *conn, const char *command, @@ -3886,9 +3769,7 @@ int PQsendQueryParams(PGconn *conn, const int *paramFormats, int resultFormat); - - 这相当于,不同之处在于可以单独指定查询参数而不是与查询字符串一起指定。 - 函数的参数处理方式与完全相同。与一样,它在查询字符串中只允许一个命令。 +该函数等价于 ,但查询参数可以与查询字符串分开指定。函数参数的处理方式与 相同。与 一样,查询字符串中只允许包含一条命令。 @@ -3900,7 +3781,7 @@ int PQsendQueryParams(PGconn *conn, - 发送一个请求来创建一个带有给定参数的预备语句,而不等待完成。 + 发送按给定参数创建预备语句的请求,不等待完成。 int PQsendPrepare(PGconn *conn, const char *stmtName, @@ -3908,10 +3789,7 @@ int PQsendPrepare(PGconn *conn, int nParams, const Oid *paramTypes); - - 这是的异步版本:如果能够分派请求,则返回1,否则返回0。 - 成功调用后,调用来确定服务器是否成功创建了预备语句。 - 该函数的参数处理方式与完全相同。 +这是 的异步版本:请求发送成功时返回 1,否则返回 0。调用成功后,再调用 ,确定服务器是否成功创建了预备语句。函数参数的处理方式与 相同。 @@ -3923,7 +3801,7 @@ int PQsendPrepare(PGconn *conn, - 发送一个请求来执行一个准备好的语句,带有给定的参数,而不等待结果。 + 发送使用给定参数执行预备语句的请求,不等待结果。 int PQsendQueryPrepared(PGconn *conn, const char *stmtName, @@ -3933,9 +3811,7 @@ int PQsendQueryPrepared(PGconn *conn, const int *paramFormats, int resultFormat); - - 这类似于,但要执行的命令是通过指定一个之前准备好的语句的名称来指定,而不是提供一个查询字符串。 - 函数的参数处理方式与完全相同。 +该函数类似于 ,但通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。函数参数的处理方式与 相同。 @@ -3967,7 +3843,7 @@ int PQsendDescribePrepared(PGconn *conn, const char *stmtName); - 提交请求以获取有关指定门户的信息,而无需等待完成。 + 提交请求以获取有关指定 portal 的信息,而无需等待完成。 int PQsendDescribePortal(PGconn *conn, const char *portalName); @@ -4006,13 +3882,7 @@ PGresult *PQgetResult(PGconn *conn); - 必须重复调用直到返回空指针,表示命令已完成。 - (如果在没有活动命令时调用, - 将立即返回空指针。)每个非空结果从 - 应该使用先前描述的相同PGresult访问器函数进行处理。 - 完成后不要忘记使用释放每个结果对象。请注意, - 仅在有命令处于活动状态且必要的响应数据尚未被 - 读取时才会阻塞。 + 必须反复调用 ,直到它返回空指针,表明命令已经完成。(如果当前没有正在执行的命令,调用 会立即返回空指针。)对于 返回的非空指针,应使用前文介绍的 PGresult 访问函数处理相应结果。使用完毕后,不要忘记调用 释放每个结果对象。注意,只有存在正在执行的命令,且所需响应数据尚未被 读取时, 才会阻塞。 @@ -4035,41 +3905,37 @@ PGresult *PQgetResult(PGconn *conn); - + - 使用解决了的一个问题:如果一个命令字符串包含多个SQL命令,这些命令的结果可以被个别地获得(顺便说一句:这样就允许一种简单的重叠处理形式, 客户端可以处理一个命令的结果,而同时服务器可以继续处理同一命令字符串中后面的查询)。 - + 使用 可以解决 的一个问题:如果命令字符串包含多个 SQL 命令,就能分别获取这些命令的结果。(这也支持一种简单的重叠处理方式:客户端可以处理某条命令的结果,同时服务器继续处理同一命令字符串中后面的查询。) + - 可以被获得的另一种常常想要的特性是一次从大型结果中检索一行。这会在中讨论。 - + 使用 还可以实现另一项常见需求:从大型查询结果中一次读取一行。详见 。 + - 就其本身而言,调用将仍会导致客户端阻塞,直到服务器完成下一个SQL命令。可以通过正确使用两个函数来避免这种情况: - - + 仅仅调用 仍会使客户端阻塞,直到服务器完成下一条 SQL 命令。可以通过正确使用另外两个函数来避免这种情况: + PQconsumeInputPQconsumeInput - 如果有来自服务器的输入可用,则使用之。 + 如果服务器有可读取的输入,则读取这些输入。 int PQconsumeInput(PGconn *conn); - 通常返回 1 表明没有错误,而返回 0 表明有某种麻烦发生(此时可以用)。 - 注意该结果并不表明是否真正收集了任何输入数据。在调用之后,应用可以检查和/或PQnotifies来看看它们的状态是否改变。 + 通常返回 1,表示没有错误;发生问题时则返回 0(此时可查看 )。注意,返回值并不说明是否实际读取了输入数据。调用 后,应用程序可以检查 和/或 PQnotifies,以确定其状态是否发生变化。 - 即使应用还不准备处理一个结果或通知,也可以被调用。 - 这个函数将读取可用的数 据并且把它保存在一个缓冲区中,从而导致一个select()的读准备好指示消失。 - 因此应用可以使用立即清除select()条件,并且在空闲时再检查结果。 + 即使应用程序尚未准备好处理结果或通知,也可以调用 。此函数会读取可用数据并将其保存在缓冲区中,从而清除 select() 的可读就绪指示。因此,应用程序可以用 立即清除 select() 的就绪条件,随后在合适的时候检查结果。 @@ -4091,15 +3957,11 @@ int PQisBusy(PGconn *conn); - + - 一个使用这些函数的典型应用将有一个主循环,在主循环中会使用select()poll()等待所有它必须响应的情况。 - 其中之一将是来自服务器的输入可用,对select()来说意味着标识的文件描述符上有可读的数据。 - 当主循环检测到输入准备好时,它将调用读取输入。 - 然后它可以调用,如果返回假(0)则接着调用。 - 它还可以调用PQnotifies检测NOTIFY消息(见)。 - + 使用这些函数的典型应用程序会在主循环中通过 select()poll() 等待需要响应的各种条件。其中一个条件是服务器有可读取的输入;对于 select(),这意味着 标识的文件描述符上有可读数据。主循环检测到输入就绪时,应调用 读取输入,然后调用 。如果 返回假(0),就可以接着调用 。还可以调用 PQnotifies 检测 NOTIFY 消息(见 )。 + 一个使用/的客户端也可以尝试取消一个正在被服务器处理的命令,见。 @@ -4107,13 +3969,8 @@ int PQisBusy(PGconn *conn); - 通过使用上面描述的函数,可以避免在等待来自数据库服务器的输入时阻塞。 - 然而,应用程序仍然可能会在等待向服务器发送输出时阻塞。 - 这在发送非常长的SQL命令或数据值时可能会发生,尽管这相对不常见。 - (如果应用程序通过COPY IN发送数据,则更有可能发生。) - 为了防止这种可能性并实现完全非阻塞的数据库操作,可以使用以下附加函数。 - - + 使用上述函数可以避免在等待数据库服务器输入时阻塞。不过,应用程序仍可能在等待向服务器发送输出时阻塞。这种情况较少见,但发送很长的 SQL 命令或数据值时可能发生。(如果应用程序通过 COPY IN 发送数据,发生的可能性则大得多。)为了防止这种情况,实现完全非阻塞的数据库操作,可以使用以下附加函数。 + PQsetnonblockingPQsetnonblocking @@ -4131,11 +3988,7 @@ int PQsetnonblocking(PGconn *conn, int arg); - 在非阻塞状态下,成功调用、 - 、 - 不会阻塞; - 它们的更改将存储在本地输出缓冲区中,直到刷新为止。 - 不成功的调用将返回错误,必须重试。 + 在非阻塞状态下,成功调用 不会阻塞;产生的数据保存在本地输出缓冲区中,等待发送。失败的调用会返回错误,必须重试。 @@ -4166,9 +4019,7 @@ int PQisnonblocking(const PGconn *conn); - 尝试将任何排队的输出数据刷新到服务器。如果成功(或发送队列为空),则返回0; - 如果由于某种原因失败,则返回-1;如果尚未能够发送发送队列中的所有数据(只有在连接为非阻塞时才会发生此情况), - 则返回1。 + 尝试将发送队列中的输出数据发送到服务器。成功(或发送队列为空)时返回 0;因某种原因失败时返回 -1;如果尚未能发送队列中的全部数据,则返回 1(这种情况只可能发生在非阻塞连接上)。 int PQflush(PGconn *conn); @@ -4176,15 +4027,11 @@ int PQflush(PGconn *conn); - + - 在一个非阻塞连接上发送任何命令或者数据之后,要调用。 - 如果它返回 1,就要等待套接字变成读准备好或写准备好。如果它变为写准备好,应再次调用。 - 如果它变为读准备好,则应先调用,然后再调用。 - 一直重复直到返回 0(有必要检查读准备好并且用耗尽输入,因为服务器可能阻塞给我们发送数据的尝试,例如 NOTICE 消息,并且在我们读它的数据之前它都不会读我们的数据)。 - 一旦返回 0,应等待套接字变成读准备好并且接着按照上文所述读取响应。 - + 在非阻塞连接上发送命令或数据后,应调用 。如果返回 1,就等待套接字变为可读或可写。套接字可写时,再次调用 ;可读时,先调用 ,再调用 。重复上述步骤,直到 返回 0。(必须检查套接字是否可读,并用 读完输入,因为服务器可能在尝试向客户端发送数据时阻塞,例如发送 NOTICE 消息;在客户端读取这些数据之前,服务器不会读取客户端发送的数据。)当 返回 0 后,等待套接字变为可读,再按前述方法读取响应。 + @@ -4198,29 +4045,26 @@ int PQflush(PGconn *conn); - pipelining - in libpq + 管道化 + 在 libpq 中 - batch mode - in libpq + 批处理模式 + 在 libpq 中 - libpq 管道模式允许应用发送查询而无需读取先前发送查询的结果。 - 利用管道模式的优点,客户端将对服务器等待的更少,因为可以在单个网络事务中发送/接收多个查询/结果。 - + libpq 的管道模式允许应用程序在尚未读取先前查询结果时继续发送查询。多个查询及其结果可以在一次网络交互中发送和接收,从而减少客户端等待服务器的时间。 + - 虽然管道模式提供了显著的性能提升, - 使用管道模式写客户端会更加复杂,因为它涉及到管理一个挂起查询的队列,并查找队列中的哪个结果对应于哪个查询。 - + 管道模式可以显著提升性能,但使用它编写客户端也更复杂,因为需要管理待处理查询队列,并确定每个结果对应队列中的哪个查询。 + - 管道模式通常也会在客户端和服务器上面消耗更多的内存,尽管仔细和积极地管理发送/接收队列可以减轻这种消耗。 - 这适用于连接是否处于阻塞或非阻塞模式。 - + 管道模式通常也会增加客户端和服务器的内存消耗,不过仔细、主动地管理发送和接收队列可以缓解这一问题。无论连接处于阻塞还是非阻塞模式,都是如此。 + 虽然libpq的管道API是在PostgreSQL 14中引入的, @@ -4233,24 +4077,8 @@ int PQflush(PGconn *conn); 使用管道模式 - 要发出管道命令,应用程序必须将连接切换到管道模式, - 可以通过来完成。 - 可以使用来测试管道模式是否激活。 - 在管道模式下,只允许使用扩展查询协议的异步操作, - 不允许包含多个SQL命令的命令字符串,也不允许使用COPY命令。 - 使用同步命令执行函数,如PQfn、 - PQexec、 - PQexecParams、 - PQprepare、 - PQexecPrepared、 - PQdescribePrepared、 - PQdescribePortal, - 都会导致错误。 - 也不允许使用PQsendQuery,因为它使用简单查询协议。 - 一旦所有已分派的命令的结果已被处理,并且 - 结束管道结果已被消耗,应用程序可以通过返回 - 到非管道模式。 - + 要使用管道,应用程序必须通过 将连接切换到管道模式。可用 检查管道模式是否已启用。在管道模式下,只允许使用扩展查询协议的异步操作,不允许命令字符串包含多个 SQL 命令,也不允许 COPY。调用同步命令执行函数,例如 PQfnPQexecPQexecParamsPQpreparePQexecPreparedPQdescribePreparedPQdescribePortal,会导致错误。也不允许使用 PQsendQuery,因为它使用简单查询协议。所有已发送命令的结果及管道结束结果都读取处理完毕后,应用程序便可通过 返回非管道模式。 + @@ -4259,9 +4087,8 @@ int PQflush(PGconn *conn); 如果在阻塞模式下使用,它可能发生客户端/服务器死锁。 - 客户端将阻止尝试发送查询到服务器,但服务器将阻止从它已经处理的查询向客户端发送结果。 - 这只有当客户端在它切换到处理从服务器的输入之前发送足够的查询来填充其输出缓冲区和服务器的接收缓冲区,才会发生这种情况,但很难准确预测何时将发生。 - + 客户端在尝试向服务器发送查询时阻塞,而服务器在尝试将已处理查询的结果发送给客户端时阻塞。只有当客户端在转而处理服务器输入之前,发送了足够多的查询,填满自身的输出缓冲区和服务器的接收缓冲区,才会发生这种情况;但很难准确预测何时会发生。 + @@ -4302,8 +4129,8 @@ int PQflush(PGconn *conn); - PQisBusyPQconsumeInput 等函数在处理管道结果时照常工作。特别地,在管道处理过程中调用 PQisBusy 时,如果到目前为止已发出查询的所有结果均已被消费,则返回 0。 - + PQisBusyPQconsumeInput 等函数在处理管道结果时照常工作。特别地,在管道处理过程中调用 PQisBusy 时,如果到目前为止已发出查询的所有结果均已被读取,则返回 0。 + libpq 不向应用程序提供当前正在处理哪个查询的信息(除了 PQgetResult 返回空指针,表示开始返回下一个查询的结果)。应用程序必须跟踪查询的发送顺序,以便将查询与对应结果关联起来。应用程序通常会使用状态机或 FIFO 队列实现这一点。 @@ -4316,21 +4143,16 @@ int PQflush(PGconn *conn); 错误处理 - 从客户端的视角,在PQresultStatus返回PGRES_FATAL_ERROR之后,管道被标记为中止。 - PQresultStatus将报告一个PGRES_PIPELINE_ABORTED结果,对中止的管道中的每一个剩余的排队操作。 - PQpipelineSync的结果报告为PGRES_PIPELINE_SYNC,以表示中止管道的结束并恢复正常的结果处理。 - + 从客户端的角度看,PQresultStatus 返回 PGRES_FATAL_ERROR 后,管道就会被标记为中止。对于已中止管道中剩余的每个排队操作,PQresultStatus 都会报告一个 PGRES_PIPELINE_ABORTED 结果。PQpipelineSync 的结果报告为 PGRES_PIPELINE_SYNC,表示已中止的管道结束,并恢复正常的结果处理。 + 在错误恢复时,客户端必须 使用 PQgetResult处理结果。 - 如果管道使用隐式事务,那么已经执行的操作将被回滚,而排队跟在失败操作的操作将被完全跳过。 - 同样的行为也会发生,如果管道开始并提交单个显式事务(也就是,第一个语句是BEGIN ,最后一个是COMMIT),除非会话在管道结束时保持在中止事务状态。 - 如果管道包含多个显式事务,所有在错误发生前已提交的事务都会继续保留,当前正在进行的事务会被中止,所有后续操作都会被完全跳过,包括后续事务在内。 - 如果管道同步点发生时显式事务块为中止状态,则下一个管道将立即中止,除非下一个命令使用ROLLBACK将事务置于正常模式。 - + 如果管道使用隐式事务,已经执行的操作会被回滚,而失败操作之后排队的操作会全部跳过。如果管道开始并提交单个显式事务(即第一条语句为 BEGIN,最后一条为 COMMIT),行为也相同,不过在管道结束时,会话仍处于事务中止状态。如果管道包含多个显式事务,错误发生前已经提交的事务仍保持已提交状态,当前正在进行的事务会中止,所有后续操作都会被跳过,包括后续事务。如果到达管道同步点时,显式事务块仍处于中止状态,下一个管道会立即中止,除非下一条命令使用 ROLLBACK 将事务恢复为正常状态。 + @@ -4343,24 +4165,19 @@ int PQflush(PGconn *conn); - 交叉结果处理和查询分派 + 交错处理结果与发送查询 - 为避免大型管道上的死锁,客户端将被围绕非阻塞事件循环构建,通过使用操作系统工具,如select, poll, WaitForMultipleObjectEx等等, - + 为避免大型管道发生死锁,客户端应围绕非阻塞事件循环组织,使用 selectpollWaitForMultipleObjectEx 等操作系统机制。 + - 客户端应用通常应该维护一个尚未分派的工作队列和一个已分派但尚未处理结果的工作队列。 - 当套接字是可写时,它将可以分派更多的工作。 - 当套接字是可读时,它将读取结果并处理它们,将它们匹配到相应结果队列中的下一个条目。 - 基于可用内存,来自套接字的结果将被经常读取:这里不需要等到管道结束才读取结果。 - 管道将范围涵盖到工作的逻辑单元,通常(但不是必然)每个管道一个事务。 - 在管道之间,不需要退出管道模式再重新进入管道模式,也不需要等待一个管道结束后再发送下一个。 - + 客户端应用程序通常应维护两个队列:一个存放尚未发送的工作,另一个存放已经发送但尚未处理结果的工作。套接字可写时,应继续发送工作;套接字可读时,应读取并处理结果,将其与相应结果队列中的下一个条目匹配。应根据可用内存情况,频繁地从套接字读取结果,无需等到管道结束。每个管道应对应一个逻辑工作单元,通常是一个事务,但并非必须如此。管道之间无需退出再重新进入管道模式,也无需等待一个管道完成后才发送下一个。 + - 一个使用select()和一个简单状态机来跟踪发送和接收工作的示例,在PostgreSQL源代码发行版的src/test/modules/libpq_pipeline/libpq_pipeline.c文件中。 - + PostgreSQL 源代码发行版的 src/test/modules/libpq_pipeline/libpq_pipeline.c 中提供了一个示例,使用 select() 和简单状态机跟踪已发送和已接收的工作。 + @@ -4404,7 +4221,7 @@ PGpipelineStatus PQpipelineStatus(const PGconn *conn); - libpq 连接 是管道模式。 + libpq 连接处于管道模式。 @@ -4433,18 +4250,14 @@ PGpipelineStatus PQpipelineStatus(const PGconn *conn); - 造成连接进入管道模式,如果它当前空闲或已经是管道模式。 - + 如果连接当前空闲或已处于管道模式,则使该连接进入管道模式。 int PQenterPipelineMode(PGconn *conn); - - 成功返回1. - 如果连接当前不是空闲的,返回0并且无影响,也就是说,它已经有了一个结果,或者它正在等待服务器的更多输入,等等。 - 这个函数实际上不向服务器发送任何东西,它只是更改libpq连接状态。 + 成功时返回 1。如果连接当前不空闲,例如已有结果可供读取,或正在等待服务器的更多输入,则返回 0,且不产生任何影响。此函数实际上不向服务器发送任何内容,只改变 libpq 的连接状态。 @@ -4456,16 +4269,14 @@ int PQenterPipelineMode(PGconn *conn); - 造成连接退出管道模式,如果连接当前以空队列处于管道模式,并且没有待处理的结果。 + 如果连接当前处于管道模式、队列为空且没有待读取的结果,则使该连接退出管道模式。 int PQexitPipelineMode(PGconn *conn); - 成功则返回1。 - 如果不是管道模式,则返回1并且不采取操作。 - 如果当前语句没有完成处理,或者PQgetResult尚未被调用以收集所有先前发送查询的结果,则返回0(在这种情况下,使用以获取关于故障的更多信息)。 + 成功时返回 1。如果连接不处于管道模式,也返回 1,且不执行任何操作。如果当前语句尚未处理完毕,或尚未调用 PQgetResult 读取先前发送的所有查询的结果,则返回 0(此时可使用 获取更多失败信息)。 @@ -4477,17 +4288,14 @@ int PQexitPipelineMode(PGconn *conn); - 通过发送sync message并刷新发送缓冲区的方式来标记管道中的同步点。 - 它用作隐式事务的定界符和错误恢复点;参见。 - + 通过发送同步消息并将发送缓冲区中的数据发往服务器,在管道中标记同步点。同步点作为隐式事务的分界符和错误恢复点;见 int PQpipelineSync(PGconn *conn); - 成功就返回1。 - 如果连接不是管道模式或者发送sync message失败,则返回0。 + 成功时返回 1。如果连接不处于管道模式,或发送同步消息失败,则返回 0。 @@ -4501,21 +4309,19 @@ int PQpipelineSync(PGconn *conn); - 发送一个请求到服务器以刷新它的输出缓冲区。 + 请求服务器发送其输出缓冲区中的数据。 int PQsendFlushRequest(PGconn *conn); - + - 成功就返回1。 - 任何失败则返回0。 - + 成功时返回 1;发生任何失败时返回 0。 + - 当PQpipelineSync被调用的结果,或者在非管道模式下的任何请求时,服务器自动刷新它的输出缓冲区;这个函数用于使得服务器在不建立同步点的情况下以管道模式刷新其输出缓冲区。 - 请注意,请求不是自身能自动刷新到服务器;如果需要时使用PQflush。 - + 调用 PQpipelineSync 后,或者在非管道模式下收到任何请求时,服务器都会自动发送其输出缓冲区中的数据。此函数可让服务器在管道模式下发送输出缓冲区中的数据,而不建立同步点。注意,该请求本身不会自动发送到服务器;必要时可使用 PQflush。 + @@ -4526,43 +4332,36 @@ int PQsendFlushRequest(PGconn *conn); 何时使用管道模式 - 非常像异步查询模式,在使用管道模式时没有明显的性能开销。 - 它增加了客户端应用的复杂性,并且需要特别注意以防止客户端/服务器死锁。 - 但是管道模式可以提供相当大的性能改进,代价是因为状态保留更久而增加内存使用。 - + 与异步查询模式类似,使用管道模式不会带来明显的性能开销。它增加了客户端应用程序的复杂性,需要格外注意防止客户端与服务器之间的死锁,但也能显著提升性能,代价是状态保留更久,因而占用更多内存。 + - 当服务器比较远,即网络延迟(ping time)高的时候,管道模式最有用,以及在许多小操作正在快速连续执行的时候。 - 当每个查询的执行时间是客户端/服务器往返时间的许多倍时,使用管道命令的优势通常会更少。 - 不用管道模式,在往返时间为300毫秒的服务器上运行一个100条语句的操作,仅网络延迟就需要30秒;使用管道,等待来自服务器的结果可能只消耗仅仅0.3秒。 - + 当服务器距离较远,即网络延迟(ping 时间)较高,或者需要快速连续执行许多小操作时,管道模式最有用。如果每个查询的执行时间是客户端与服务器往返时间的许多倍,使用管道命令的收益通常较小。在往返时间为 300 毫秒的服务器上执行一个包含 100 条语句的操作,不使用管道时,仅网络延迟就需要 30 秒;使用管道时,等待服务器结果的时间可能低至 0.3 秒。 + - 当你的应用需要完成很多小的INSERT, UPDATEDELETE 操作,并且不能方便的转换到集合操作或者 COPY操作时,用管道命令。 - + 如果应用程序需要执行大量小型 INSERTUPDATEDELETE 操作,而这些操作又难以转换为集合操作或 COPY 操作,就可以使用管道命令。 + - 当来自一个操作的信息需要客户端产生下一个操作时,管道模式是没有用的。 - 在这种情况下,客户机将不得不引入一个同步点,并等待完整的客户端/服务器往返以获取它需要的结果。 - 但是,通常可以调整客户端设计以交换服务器端所需的信息。 - 读-修改-写循环是非常好的选择;例如: + 如果客户端必须获得前一个操作的信息,才能生成下一个操作,管道模式就没有帮助。在这种情况下,客户端必须引入同步点,并等待一次完整的客户端与服务器往返,才能获得所需结果。不过,通常可以调整客户端设计,让所需信息在服务器端交换。读取、修改、写入的循环尤其适合这样改进。例如: BEGIN; SELECT x FROM mytable WHERE id = 42 FOR UPDATE; --- result: x=2 --- client adds 1 to x: +-- 结果:x=2 +-- 客户端将 x 加 1: UPDATE mytable SET x = 3 WHERE id = 42; COMMIT; - 可以更有效地开展以下工作: +可以改写为以下效率更高的操作: UPDATE mytable SET x = x + 1 WHERE id = 42; - + - 当单个管道包含多个事务时,管道的作用更小,而且更复杂(参见)。 - + 当单个管道包含多个事务时,使用管道的收益较小,复杂度也更高(见 )。 + @@ -4595,7 +4394,7 @@ int PQsetSingleRowMode(PGconn *conn); - 此函数只能在调用或其某个兄弟函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活单行模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 + 此函数只能在调用或其某个同类函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活单行模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 @@ -4681,7 +4480,7 @@ int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize); - 的一个已废弃变体。 + 的一个已弃用变体。 int PQrequestCancel(PGconn *conn); @@ -4702,7 +4501,7 @@ int PQrequestCancel(PGconn *conn); 快速路径接口 - fast path + 快速路径 @@ -4712,8 +4511,8 @@ int PQrequestCancel(PGconn *conn); - 这个接口不安全,不应使用。当result_is_int被设置为0时,PQfn可能会在result_buf末尾之外写入数据,而不管缓冲区是否有足够空间容纳所请求的字节数。此外,它已经废弃,因为可以通过创建一个定义该函数调用的预备语句来达到类似的性能并获得更强大的功能。然后,用参数和结果的二进制传输执行该语句,从而取代快速路径函数调用。 - + 此接口不安全,不应使用。当 result_is_int 设为 0 时,PQfn 可能越过 result_buf 的末尾写入数据,无论缓冲区是否有足够空间容纳请求的字节数。此外,此接口已经过时:可以通过创建预备语句来定义函数调用,获得相近的性能和更强的功能;再以二进制形式传输参数和结果来执行该语句,即可替代快速路径函数调用。 + @@ -4741,27 +4540,24 @@ typedef struct - fnid参数是要被执行的函数的 OID。argsnargs定义了要传递给函数的参数;它们必须匹配已声明的函数参数列表。当一个参数结构体的isint域为真时,u.integer值被以指定长度(必须是 1、2 或者 4 字节)整数的形式发送给服务器;这时候会发生恰当的字节交换。当isint为假时,*u.ptr中指定数量的字节将不做任何处理被发送出去;这些数据必须是服务器 预期的用于该函数参数数据类型的二进制传输的格式(由于历史原因u.ptr被声明为类型int *,其实把它考虑成void *会更好)。result_buf是放置该函数返回值的缓冲区。调用者必须已经分配了足够的空间来存储返回值(这里没有检查!)。实际的结果长度将被放在result_len指向的整数中返回。如果预期结果是 2 或 4 字节整数,把result_is_int设为 1;否则设为 0。把result_is_int设为 1 导致libpq在必要时对值进行交换字节,这样它就作为对客户端机器正确的int值被传输,注意对任一种允许的结果大小都会传递一个 4 字节到*result_buf。当result_is_int是 0 时,服务器发送的二进制格式字节将不做修改直接返回(在这种情况下,把result_buf考虑为类型void *更好)。 - + fnid 参数是要执行函数的 OID。argsnargs 指定传给函数的参数,必须与函数声明中的参数列表匹配。参数结构体的 isint 字段为真时,u.integer 值会以指定长度的整数发送到服务器,该长度必须是 2 或 4 字节,并会进行适当的字节序转换。isint 为假时,位于 *u.ptr 的指定数量字节会原样发送;数据必须符合服务器对该函数参数数据类型的二进制传输格式要求。(将 u.ptr 声明为 int * 是历史原因;将其视为 void * 更合适。)result_buf 指向用于存放函数返回值的缓冲区。调用者必须事先分配足够空间来保存返回值,这里不会检查!实际结果长度以字节为单位,返回到 result_len 指向的整数中。如果预期结果是 2 或 4 字节整数,将 result_is_int 设为 1,否则设为 0。将 result_is_int 设为 1 后,libpq 会按需转换字节序,使结果成为适合客户端机器的 int 值;注意,无论是哪种允许的结果大小,传入 *result_buf 的都是 4 字节整数。result_is_int 为 0 时,服务器发送的二进制格式字节串会原样返回。(此时,将 result_buf 视为 void * 更合适。) + - PQfn总是返回一个有效的PGresult指针,包括状态PGRES_COMMAND_OK 表示成功或者PGRES_FATAL_ERROR在出现什么问题时。 - 在使用结果之前应该检查结果状态。 - 当结果不再使用后,调用者有义务使用释放PGresult。 - + PQfn 总是返回有效的 PGresult 指针:成功时状态为 PGRES_COMMAND_OK,遇到问题时为 PGRES_FATAL_ERROR。使用结果前应检查其状态。不再需要结果时,调用者负责使用 释放 PGresult。 + - 要传递NULL参数到函数,将参数结构体的len字段设置为-1isintu 字段就不相关了。 - + 要向函数传入 NULL 参数,将该参数结构体的 len 字段设为 -1;此时,isintu 字段便不再相关。 + - 如果函数返回 NULL, *result_len 被设置为 -1, 并且 *result_buf 不调整。 - + 如果函数返回 NULL,则将 *result_len 设为 -1,而不修改 *result_buf。 + - 注意在使用此接口时,不能够处理集-值结果。 - 此外,函数必须是一个普通函数,而不是聚合、窗口函数或过程。 - + 注意,使用此接口时无法处理集合值结果。此外,函数必须是普通函数,不能是聚合函数、窗口函数或过程。 + @@ -4771,7 +4567,7 @@ typedef struct NOTIFY - in libpq + 在 libpq 中 @@ -4780,39 +4576,36 @@ typedef struct libpq应用把LISTENUNLISTENNOTIFY命令作为普通 SQL 命令提交。 - 随后通过调用PQnotifies.PQnotifies来检测NOTIFY消息的到达。 + 随后通过调用PQnotifiesPQnotifies来检测NOTIFY消息的到达。 - 函数PQnotifies从服务器发来的未处理通知消息列表中返回下一条通知。如果没有待处理通知,则返回空指针。一旦PQnotifies返回一条通知,该通知就被视为已处理,并会从通知列表中删除。 - + 函数 PQnotifies 从已收到但尚未处理的服务器通知消息列表中返回下一条通知。没有待处理通知时返回空指针。一旦 PQnotifies 返回一条通知,该通知就被视为已处理,并从通知列表中移除。 PGnotify *PQnotifies(PGconn *conn); typedef struct pgNotify { - char *relname; /* notification channel name */ - int be_pid; /* process ID of notifying server process */ - char *extra; /* notification payload string */ + char *relname; /* 通知通道名称 */ + int be_pid; /* 发送通知的服务器进程 ID */ + char *extra; /* 通知载荷字符串 */ } PGnotify; - - 在处理完PQnotifies返回的PGnotify对象后,别忘了用把它释放。 - 释放PGnotify指针本身就足够了;relnameextra域并不表示独立分配的内存(这些域名是历史遗留的,尤其是通道名称与关系名称并无关联)。 - +处理完 PQnotifies 返回的 PGnotify 对象后,务必使用 释放它。只需释放 PGnotify 指针;relnameextra 字段并非独立分配。(这些字段名称是历史遗留的;尤其是,通道名称与关系名称不必有任何关联。) + 给出了一个示例程序展示异步通知的使用。 - PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数吸收的消息。 + PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数读取的消息。 在较早版本的libpq中,及时收到NOTIFY消息的唯一方法是不断提交命令,哪怕是空命令,然后在每次后检查PQnotifies。 - 虽然这种方法仍然有效,但由于效率过低,现已废弃。 + 虽然这种方法仍然有效,但由于浪费处理能力,现已弃用。 - 当你没有可用的命令提交时,一种更好的检查NOTIFY消息的方法是调用,然后检查PQnotifies。 + 当没有需要执行的实际命令时,一种更好的检查NOTIFY消息的方法是调用,然后检查PQnotifies。 你可以使用select()等待服务器数据到达,这样在无事可做时就不会浪费CPU资源(参见以获得可传给select()的文件描述符)。 注意不管是用/提交命令还是简单地使用,这种方法都能正常工作。 不过,你应该记住在每次之后检查PQnotifies,看看在命令的处理过程中是否有通知到达。 @@ -4826,20 +4619,16 @@ typedef struct pgNotify COPY - with libpq + 使用 libpq - PostgreSQL中的COPY命令有用于libpq的对网络连接读出或者写入的选项。这一节描述的函数允许应用通过提供或者消耗已拷贝的数据来充分利用这个功能。 - + PostgreSQLCOPY 命令提供了选项,可以通过 libpq 使用的网络连接读取或写入数据。本节介绍的函数允许应用程序通过提供或接收复制数据来使用这一能力。 + - 整个处理是应用首先通过或者一个等效的函数发出 SQL COPY命令。 - 对这个命令的响应(如果命令无误)将是一个状态代码是PGRES_COPY_OUT或 者PGRES_COPY_IN(取决于指定的拷贝方向)的PGresult对象。 - 应用然后就应该使用这一节的函数接收或者传送数据行。在数据传输结束之后,另外一个PGresult对象会被返回以表明传输的成功或者失败。 - 它的状态将是:PGRES_COMMAND_OK表示成功,PGRES_FATAL_ERROR表示发生了一些问题。 - 此时我们可以通过发出进一步的 SQL 命令(在COPY操作的处理过程中,不能用同一个连接执行其它 SQL 命令)。 - + 整体流程如下:应用程序先通过 或等效函数发出 SQL COPY 命令。如果命令没有错误,响应就是一个 PGresult 对象,其状态码为 PGRES_COPY_OUTPGRES_COPY_IN,取决于指定的复制方向。应用程序随后应使用本节函数接收或发送数据行。数据传输完成后,会返回另一个 PGresult 对象,表示传输成功或失败:成功时状态为 PGRES_COMMAND_OK,出现问题时为 PGRES_FATAL_ERROR。此时可以通过 继续发出 SQL 命令。(COPY 操作进行期间,不能在同一连接上执行其他 SQL 命令。) + 如果一个COPY命令是通过在一个可能包含额外命令的字符串中发出的,那么应用在完成COPY序列之后必须继续用取得结果。 @@ -4847,17 +4636,15 @@ typedef struct pgNotify - 这一节的函数应该只在从获得了PGRES_COPY_OUTPGRES_COPY_IN结果状态的后执行。 - + 只有从 获得 PGRES_COPY_OUTPGRES_COPY_IN 结果状态后,才应调用本节函数。 + - 一个PGresult对象具有这些状态值之一,携带有关COPY操作开始的一些附加数据。 - 可以使用与查询结果相关的函数来获取这些附加数据: - - + 带有上述某个状态值的 PGresult 对象,还会携带关于即将开始的 COPY 操作的附加数据。这些数据可以通过下列函数获取,这些函数也用于查询结果: + PQnfieldsPQnfieldswith COPY + >PQnfields用于 COPY @@ -4868,7 +4655,7 @@ typedef struct pgNotify PQbinaryTuplesPQbinaryTupleswith COPY + >PQbinaryTuples用于 COPY @@ -4880,7 +4667,7 @@ typedef struct pgNotify PQfformatPQfformatwith COPY + >PQfformat用于 COPY @@ -4892,15 +4679,15 @@ typedef struct pgNotify - + 用于发送<command>COPY</command>数据的函数 - 这些函数用于在COPY FROM STDIN期间发送数据。如果在连接不是COPY_IN状态,调用它们会失败。 - + 这些函数用于在 COPY FROM STDIN 期间发送数据。如果连接不处于 COPY_IN 状态,调用它们会失败。 + @@ -4919,12 +4706,11 @@ int PQputCopyData(PGconn *conn, - 传输指定buffer中长度为nbytesCOPY数据到服务器。 - 如果数据被放在队列中,结果是 1;如果因为缓冲区满而无法被放在队列中(只可能发生在连接是非阻塞模式时),那么结果是零;如果发生错误,结果为 -1(如果返回值为 -1,那么使用检索细节。如果值是零,那么等待写准备好然后重试)。 + 将指定 buffer 中长度为 nbytesCOPY 数据传输到服务器。数据成功加入队列时返回 1;因缓冲区已满而无法加入队列时返回零(仅可能发生在非阻塞模式下);发生错误时返回 -1。(返回 -1 时,可用 获取详细信息。返回零时,应等待可写就绪后重试。) - 应用可以把COPY数据流划分成任意方便的大小放到缓冲区中。在发送时,缓冲区载荷的边界没有什么语意。数据流的内容必须匹配COPY命令预期的数据格式;详见。 + 应用程序可以将 COPY 数据流分成任意方便大小的数据块,逐块装入缓冲区。发送时,这些数据块的边界没有语义含义。数据流内容必须符合 COPY 命令预期的数据格式;详见 @@ -4944,21 +4730,15 @@ int PQputCopyEnd(PGconn *conn, - 如果errormsgNULL,则成功结束COPY_IN操作。 - 如果errormsg不是NULLCOPY被强制失败,errormsg指向的字符串是错误消息。 - (不过,我们不应假定这个准确的错误信息将会从服务器传回,因为服务器可能已经因为其自身原因导致COPY失败。)。 + 如果 errormsgNULL,则成功结束 COPY_IN 操作。如果 errormsg 不为 NULL,则强制 COPY 失败,并将 errormsg 指向的字符串用作错误消息。(但不应假定服务器一定会返回这条完全相同的错误消息,因为服务器可能已经因自身原因使 COPY 失败。) - 如果终止消息被发送,则结果为 1;在非阻塞模式中,结果为 1 也可能只表示终止消息被成功地放在了发送队列中 - (在非阻塞模式中,要确认数据确实被发送出去,你应该接着等待写准备好并且调用,重复这些直到返回零)。 - 零表示该函数由于缓冲区满而无法将该终止消息放在队列中,这只会发生在非阻塞模式中(在这种情况下,等待写准备好并且再次尝试调用)。 - 如果发生系统错误,则返回 -1,可以使用检索详情。 + 终止消息已发送时返回 1;在非阻塞模式下,返回 1 也可能仅表示该消息已成功加入发送队列。(在非阻塞模式下,要确认数据已经发送,应接着等待可写就绪并调用 ,反复执行直到返回零。)返回零表示缓冲区已满,无法将终止消息加入队列;这种情况仅可能发生在非阻塞模式下。(此时,应等待可写就绪,再次调用 。)发生严重错误时返回 -1,可用 获取详细信息。 - 在成功调用之后,调用获取COPY命令的最终结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 成功调用 后,调用 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -4991,29 +4771,19 @@ int PQgetCopyData(PGconn *conn, - 在一个COPY期间尝试从服务器获取另外一行数据。数据总是以每次一个数据行的方式被返回;如果只有一个部分行可用,那么它不会被返回。 - 成功返回一个数据行涉及到分配一块内存来保存该数据。buffer参数必须为非NULL。 - *buffer被设置为指向分配到的内存的指针,或者是在没有返回缓冲区的情况下指向NULL。 - 一个非NULL的结果缓冲区在不需要时必须用释放。 + 在 COPY 期间尝试从服务器获取下一行数据。每次总是返回一个完整数据行;如果只有部分行可用,则不返回。成功返回数据行时,会分配一块内存保存数据。buffer 参数必须为非 NULL*buffer 会被设置为指向所分配的内存;如果没有返回缓冲区,则设为 NULL。非 NULL 的结果缓冲区在不再需要时应使用 释放。 - 在成功返回一行之后,返回的值就是该数据行里数据的字节数(将是大于零)。 - 被返回的字符串总是空终止的,虽然这可能只是对文本COPY有用。 - 一个零结果表示该COPY仍然在处理中,但是还没有可用的行(只在async为真时才可能)。 - 一个 -1 结果表示COPY已经完成。-2 结果表示发生了错误(参考获取原因)。 + 成功返回一行时,返回值是该行的数据字节数,始终大于零。返回的字符串总是以零字节结尾,不过这可能仅对文本 COPY 有用。返回零表示 COPY 仍在进行,但尚无可用行(仅在 async 为真时可能发生)。返回 -1 表示 COPY 已完成;返回 -2 表示发生了错误(可用 查看原因)。 - 当async为真时(非零),将不会阻塞等待输入; - 如果COPY仍在处理过程中并且没有可用的完整行,那么它将返回零 - (在这种情况下等待读准备好,然后在再次调用之前,调用)。 - 当async为假(零)时,将阻塞,直到数据可用或者操作完成。 + 当 async 为真(非零)时, 不会阻塞等待输入;如果 COPY 仍在进行,但没有完整行可用,则返回零。(此时,应等待读就绪,先调用 ,再调用 。)当 async 为假(零)时, 会阻塞,直到数据可用或操作完成。 - 在返回 -1 之后,调用获取COPY命令的最后结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 在 返回 -1 后,调用 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -5023,11 +4793,11 @@ int PQgetCopyData(PGconn *conn, - 用于<command>COPY</command>的废弃函数 + 用于<command>COPY</command>的过时函数 - 这些函数代表了以前的处理COPY的方法。尽管它们还能用,但是现在已经被废弃,因为它们的错误处理很糟糕、检测结束数据的方法也不方便,并且缺少对二进制或非阻塞传输的支持。 - + 这些函数使用较旧的方式处理 COPY。虽然仍然可用,但由于错误处理欠佳、检测数据结束的方式不便,而且缺少对二进制或非阻塞传输的支持,已被弃用。 + @@ -5037,7 +4807,7 @@ int PQgetCopyData(PGconn *conn, - 读取一个以新行终止的字符行到(由服务器传输) 到一个长度为length的字符串缓冲区。 + 将服务器传来的、以换行符结尾的一行字符读入大小为 length 的字符串缓冲区。 int PQgetline(PGconn *conn, char *buffer, @@ -5046,12 +4816,11 @@ int PQgetline(PGconn *conn, - 这个函数拷贝最多length-1 个字符到该缓冲区中,并且把终止的新行转换成一个零字节。 - 在输入结束时返回EOF,如果整行都被读取则返回 0,如果缓冲区填满了而还没有遇到结束的新行则返回 1。 - + 此函数最多将 length-1 个字符复制到缓冲区,并将末尾的换行符转换为零字节。 在输入结束时返回 EOF,读完一整行时返回 0,缓冲区已满但尚未读到末尾换行符时返回 1。 + - 注意,应用必须检查是否一个新行包含两个字符\.,这表明服务器 已经完成了COPY命令的结果发送。如果应用可能收到超过length-1 字符长的行, 我们就应该确保正确识别\.行(例如,不要把一个长数据行的结束当作一个终止行)。 + 注意,应用程序必须检查新读入的一行是否仅由 \. 两个字符组成,这表示服务器已发送完 COPY 命令的结果。如果可能收到长度超过 length-1 个字符的行,必须确保正确识别 \. 行,例如不能把长数据行的末尾误当作终止行。 @@ -5063,7 +4832,7 @@ int PQgetline(PGconn *conn, - 不阻塞地读取一行COPY数据(由服务器传输)到一个缓冲区中。 + 以非阻塞方式将服务器传来的一行 COPY 数据读入缓冲区。 int PQgetlineAsync(PGconn *conn, char *buffer, @@ -5072,23 +4841,19 @@ int PQgetlineAsync(PGconn *conn, - 这个函数类似于,但是可以被用于那些必须异步读取COPY数据的应用, 也就是不阻塞的应用。 - 在发出了COPY命令并得到了PGRES_COPY_OUT响应之后, - 应用应该调用直到检测到结束数据的信号。 - + 此函数类似于 ,但可用于必须异步读取 COPY 数据的应用程序,即读取时不阻塞。发出 COPY 命令并收到 PGRES_COPY_OUT 响应后,应用程序应调用 ,直到检测到数据结束信号。 + - 不像,这个函数负责检测结束数据。 + 与 不同,此函数会负责检测数据结束。 - 在每次调用时,如果libpq的输入缓冲区中有一个完整的数据行可用,都将返回数据。 - 否则,在剩余行到达之前不会返回数据。如果识别到拷贝数据结束的标志,此函数返回 -1;如果没有可用数据则返回 0; - 或者是给出一个正数给出被返回的字节数。如果返回 -1,调用者下一步必须调用,然后回到正常处理。 + 每次调用时,如果 libpq 的输入缓冲区中有完整数据行, 就会返回数据;否则,要等该行剩余部分到达后才返回数据。识别到复制数据结束标记时返回 -1,没有可用数据时返回 0,否则返回正数,表示返回的数据字节数。返回 -1 后,调用者必须接着调用 ,然后恢复正常处理。 - 返回的数据将不超过一个数据行的范围。如果可能,每次将返回一个完整行。但如果调用者提供的缓冲区太小不足以容下服务器发送的行,那么将返回部分行。对于文本数据,这可以通过测试返回的最后一个字节是否\n来检测(在二进制COPY中, 需要对COPY数据格式进行实际的分析,以便做相同的判断)。被返回的字符串不是空结尾的(如果你想增加一个终止空,确保传递一个比实际可用空间少一字节的bufsize)。 + 返回的数据不会跨越数据行边界。只要可能,每次就返回一整行;但如果调用者提供的缓冲区太小,容不下服务器发送的一行,则只返回部分行。对于文本数据,可检查最后返回的字节是否为 \n,以判断是否返回了完整行。(对于二进制 COPY,则必须实际解析 COPY 数据格式才能作出相同判断。)返回的字符串不以零字节结尾。(如果要自行添加末尾的零字节,务必将传入的 bufsize 设置为比实际可用空间少一字节。) @@ -5100,7 +4865,7 @@ int PQgetlineAsync(PGconn *conn, - 向服务器发送一个空终止的字符串。如果 OK 则返回 0;如果不能发送字符串则返回EOF。 + 向服务器发送以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputline(PGconn *conn, const char *string); @@ -5108,17 +4873,14 @@ int PQputline(PGconn *conn, - 一系列调用发送的COPY数据流和返回的数据具有相同的格式, - 只是应用不需要每次调用中发送刚好一个数据行;在每次调用中发送多行或者部分行都是可以的。 + 连续调用 发送的 COPY 数据流,与 返回的数据格式相同。不过,应用程序不必在每次 调用中恰好发送一个数据行;每次发送部分行或多行也可以。 - 在PostgreSQL协议 3.0 之前,应用必须显式地发送两个字符\.作为最后一行来指示服务器已经完成发送COPY数据。 - 虽然这么做仍然有效,但是它已经被废弃并且\.的特殊含义可能在将来的版本中删除。 - 在发送完实际数据之后, 调用就足够了。 - + 在 PostgreSQL 协议 3.0 之前,应用程序必须显式发送由 \. 两个字符组成的最后一行,告知服务器应用程序已发送完 COPY 数据。虽然这种方式仍然有效,但已被弃用,\. 的特殊含义预计会在未来版本中移除。发送完实际数据后,调用 即可。 + @@ -5130,7 +4892,7 @@ int PQputline(PGconn *conn, - 向服务器发送一个非空终止的字符串。如果 OK 则返回 0,如果不能发送字符串则返回EOF。 + 向服务器发送不以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputnbytes(PGconn *conn, const char *buffer, @@ -5139,7 +4901,7 @@ int PQputnbytes(PGconn *conn, - 这个函数类似,除了数据缓冲区不需要是空终止,因为要发送的字节数是直接指定的。在发送二进制数据时使用这个过程。 + 此函数与 完全相同,只是直接指定了要发送的字节数,因此数据缓冲区不必以零字节结尾。发送二进制数据时可使用此函数。 @@ -5155,15 +4917,11 @@ int PQputnbytes(PGconn *conn, int PQendcopy(PGconn *conn); - 这个函数等待服务器完成拷贝。当最后一个字符串已经用发送给服务器时或者当最后一个字符串已经用PQgetline从服务器接收到时,就会发出这个函数。 - 这个函数必须被发出,否则服务器将会和客户端不同步。从这个函数返回后,服务器就已经准备好接收下一个 SQL 命令了。函数成功完成时返回值为 0,否则返回非零值(如果返回值为非零值,用检索详情)。 +此函数会等待服务器完成复制。应在使用 向服务器发送最后一个字符串后,或使用 PQgetline 从服务器接收最后一个字符串后调用它。必须调用此函数,否则服务器与客户端会失去同步。函数返回后,服务器便准备好接收下一条 SQL 命令。成功完成时返回 0,否则返回非零值。(返回非零值时,可用 获取详细信息。) - 在使用时,应用应该通过反复调用并且在看到终止行后调用来响应PGRES_COPY_OUT结果。 - 然后它应该返回到循环直到返回一个空指针。 - 类似地,PGRES_COPY_IN结果会用一系列加上之后的来处理,然后返 回到循环。 - 这样的安排将保证嵌入到一系列SQL命令中的COPY命令将被正确执行。 + 使用 时,收到 PGRES_COPY_OUT 结果后,应用程序应反复调用 ,并在看到终止行后调用 。随后应回到 循环,直到 返回空指针。类似地,收到 PGRES_COPY_IN 结果后,应连续调用 ,再调用 ,然后回到 循环。这样可以保证嵌在一系列 SQL 命令中的 COPY 命令正确执行。 @@ -5183,8 +4941,8 @@ int PQendcopy(PGconn *conn); 控制函数 - 这些函数控制libpq行为各种各样的细节。 - + 这些函数控制 libpq 行为的各种细节。 + @@ -5194,17 +4952,15 @@ int PQendcopy(PGconn *conn); - 返回客户端编码。 + 返回客户端编码。 int PQclientEncoding(const PGconn *conn); - - 请注意,它返回的是编码 ID,而不是一个符号串字符串,如EUC_JP。如果不成功,它会返回 -1。要把一个编码 ID 转换为为一个编码名称,可以用: - +注意,返回的是编码 ID,而不是 EUC_JP 这样的符号字符串。失败时返回 -1。要将编码 ID 转换为编码名称,可以使用: char *pg_encoding_to_char(int encoding_id); - + @@ -5214,14 +4970,11 @@ char *pg_encoding_to_char(int encoding_id); - - 设置客户端编码。 - + 设置客户端编码。 int PQsetClientEncoding(PGconn *conn, const char *encoding); - conn是一个到服务器的连接,而encoding是你想使用的编码。 - 如果函数成功地设置编码,则返回 0,否则返回 -1。这个连接的当前编码可以使用确定。 + conn是到服务器的连接,而encoding是要使用的编码。如果成功设置编码,函数返回 0,否则返回 -1。此连接的当前编码可以通过以下函数确定: @@ -5233,7 +4986,7 @@ int PQsetClientEncoding(PGconn *conn, const char * - 决定返回的消息的细节程度。 + 设置 所返回消息的详细程度。 typedef enum { @@ -5245,19 +4998,12 @@ typedef enum PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); - - 设置细节模式,并返回该连接的前一个设置。 - 在TERSE模式下,返回的消息只包括严重性、主要文本以及位置;这些东西通常放在一个单一行中。 - DEFAULT模式生成的消息包括上面的信息加上任何细节、提示或者上下文域(这些可能跨越多行)。 - VERBOSE模式包括所有可以可用的域。修改细节模式不会影响来自已有PGresult对象中的可用消息。 - 只有随后创建的PGresult对象才受到影响。 - SQLSTATE模式仅包括错误严重性和SQLSTATE错误代码,如果其中之一是可用的(如果没有,输出类似于TERSE模式)。 - + 设置详细程度模式,并返回该连接先前的设置。在 TERSE 模式下,返回的消息只包含严重级别、主要文本和位置;通常一行就能容纳。DEFAULT 模式生成的消息除上述内容外,还包含所有详细信息、提示或上下文字段(这些内容可能跨越多行)。VERBOSE 模式包含所有可用字段。SQLSTATE 模式仅包含错误严重级别,以及可用时的 SQLSTATE 错误代码(如果没有错误代码,则输出与 TERSE 模式相同)。 + - 更改详细程度设置不会影响已存在的PGresult对象的可用的消息,只会影响随后创建的对象。 - (如果想要用不同的详细程度打印之前的错误,请见 ) - + 更改详细程度设置不会影响从既有 PGresult 对象中取得的消息,只影响随后创建的对象。(如果希望以不同的详细程度打印之前的错误,请参见 。) + @@ -5268,7 +5014,7 @@ PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); - 决定如何处理返回的消息中的CONTEXT域。 + 确定 所返回消息中 CONTEXT 字段的处理方式。 typedef enum { @@ -5279,18 +5025,12 @@ typedef enum PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibility show_context); - - 设置上下文显示模式,返回该连接上之前的设置。 - 这个模式控制消息中是否包括CONTEXT域。 - NEVER模式不会包括CONTEXT,而ALWAYS则尽可能地包括这个域。 - 在ERRORS模式(默认)中,只在错误消息中包括CONTEXT域,而在通知和警告消息中不会包括。 - (但是,如果详细程度设置为 TERSESQLSTATE,则无论上下文显示模式如何,都会省略CONTEXT字段。) - + 设置上下文显示模式,并返回连接先前的设置。此模式控制消息中是否包含 CONTEXT 字段。NEVER 模式从不包含 CONTEXT,而 ALWAYS 模式在该字段可用时总是包含它。在 ERRORS 模式(默认)下,CONTEXT 字段只包含在错误消息中,不包含在通知和警告中。(不过,如果详细程度设置为 TERSESQLSTATE,则无论上下文显示模式如何,都会省略 CONTEXT 字段。) + - 更改这个模式不会影响从已经存在的PGresult对象项中得到的消息,只会影响后续创建的PGresult对象 - (如果想要用不同的详细程度打印之前的错误,请见)。 - + 更改此模式不会影响从既有 PGresult 对象中取得的消息,只影响随后创建的对象。(如果希望使用不同的显示模式打印之前的错误,请参见 。) + @@ -5301,25 +5041,20 @@ PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibilit - 启用对客户端/服务器通讯的跟踪,把跟踪信息输出到一个调试文件流中。 + 启用客户端/服务器通信跟踪,将跟踪信息写入调试文件流。 void PQtrace(PGconn *conn, FILE *stream); - + - 每行包括:一个可选的时间戳,一个方向指示器(F表示从客户端到服务器的消息或B表示从服务器到客户端的消息),消息长度、消息类型、和消息内容。 - 非消息内容字段(时间戳、方向、长度和消息类型)由一个制表符分隔。 - 消息内容用空格分隔。 - 协议字符串用双引号括起来,而用作数据值的字符串用单引号括起来。 - 不可打印的字符被打印为十六进制转义。 - 更多消息-类型-特定的详情可以在中发现。 - + 每行包含可选的时间戳、方向指示符(F 表示客户端发往服务器的消息,B 表示服务器发往客户端的消息)、消息长度、消息类型和消息内容。消息内容之外的字段(时间戳、方向、长度和消息类型)以制表符分隔。消息内容以空格分隔。协议字符串用双引号括起,用作数据值的字符串用单引号括起。不可打印字符以十六进制转义形式输出。各消息类型的进一步说明见 。 + - 在 Windows上,如果libpq库和应用使用了不同的标志编译,那么这个函数调用会导致应用崩溃,因为FILE指针的内部表达是不一样的。特别是多线程/单线程、发布/调试 以及静态/动态标志应该是库和所有使用库的应用都一致。 + 在 Windows 上,如果 libpq 库与应用程序使用不同的标志编译,调用此函数会导致应用程序崩溃,因为 FILE 指针的内部表示不同。具体而言,库与所有使用它的应用程序都应使用相同的多线程/单线程、发布/调试和静态/动态标志。 @@ -5340,11 +5075,8 @@ void PQsetTraceFlags(PGconn *conn, int flags); - flags包含描述跟踪的操作模式的标志位。 - 如果flags包含PQTRACE_SUPPRESS_TIMESTAMPS,则在打印每条消息时不包括时间戳。 - 如果flags包含PQTRACE_REGRESS_MODE,那么在打印每个消息时将修改一些字段,例如对象OIDs,以使输出在测试框架中更方便地使用。 - 这个函数必须在调用PQtrace之后调用。 - + flags 包含描述跟踪工作模式的标志位。如果 flags 包含 PQTRACE_SUPPRESS_TIMESTAMPS,则打印每条消息时不包含时间戳。如果 flags 包含 PQTRACE_REGRESS_MODE,则打印每条消息时会隐去某些字段,例如对象 OID,以便在测试框架中使用输出。必须在调用 PQtrace 之后调用此函数。 + @@ -5356,11 +5088,11 @@ void PQsetTraceFlags(PGconn *conn, int flags); - 禁用打开的跟踪。 + 禁用由 启动的跟踪。 void PQuntrace(PGconn *conn); - + @@ -5390,11 +5122,8 @@ void PQfreemem(void *ptr); - 释放libpq分配的内存,尤其是,,,和PQnotifies分配的内存。 - 特别重要的是,在微软 Windows 上使用这个函数,而不是free()。 - 这是因为只有 DLL 和应用的当多线程/单线程、发布/调试以及静态/动态标志相同时,才能在一个 DLL 中分配内存并且在应用中释放它。 - 在非微软 Windows 平台上,这个函数与标准库函数free()相同。 - + 释放 libpq 分配的内存,特别是 PQnotifies 分配的内存。在 Microsoft Windows 上,务必使用此函数,而不是 free()。这是因为只有 DLL 与应用程序使用相同的多线程/单线程、发布/调试和静态/动态标志,才能在 DLL 中分配内存并在应用程序中释放它。在 Microsoft Windows 以外的平台上,此函数与标准库函数 free() 相同。 + @@ -5405,15 +5134,16 @@ void PQfreemem(void *ptr); - 释放分配的数据结构。 + 释放 分配的数据结构。 void PQconninfoFree(PQconninfoOption *connOptions); - +如果参数为 NULL 指针,则不执行任何操作。 + - 一个简单的不会做这些,因为数组包含对子字符串的引用。 - + 仅调用 不足以完成此项释放,因为数组还包含指向附属字符串的引用。 + @@ -5437,8 +5167,8 @@ char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, 当前支持的算法是md5scram-sha-256onoff也被接受作为md5的别名,用于与较老的服务器版本兼容)。 注意,对scram-sha-256支持是在PostgreSQL版本10中引入的,并且在老的服务器版本上无法工作。 如果algorithmNULL,这个函数将向服务器查询设置的当前值。 - 这种行为可能会阻塞当前事务,并且当前事务被中止或者连接正忙于执行另一个查询时会失败。 - 如果希望为服务器使用默认的算法但避免阻塞,应在调用之前查询你自己的password_encryption,并且将该值作为algorithm传入。 + 这一查询可能阻塞,并且当前事务被中止或者连接正忙于执行另一个查询时会失败。 + 如果希望为服务器使用默认的算法但避免阻塞,应在调用之前自行查询password_encryption,并且将该值作为algorithm传入。 @@ -5484,8 +5214,8 @@ PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); 这是libpq内部用于分配并初始化一个空PGresult对象的函数。 如果无法分配内存,此函数返回NULL。 将它导出供外部调用,是因为一些应用需要自行生成结果对象,特别是带有错误状态的对象。 - 如果conn非空,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 - 此外,如果conn非空,连接中注册的所有事件过程也会被复制到PGresult中。 + 如果conn 不为 null,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 + 此外,如果conn 不为 null,连接中注册的所有事件过程也会被复制到PGresult中。 (这些过程不会收到PGEVT_RESULTCREATE调用,但可参见。) 注意,最终应对该对象调用,就像处理libpq自身返回的PGresult一样。 @@ -5506,16 +5236,16 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); - conn参数被传送给事件过程,但不会被直接使用。如果事件过程不使用它,则会返回NULL。 - + conn 参数会传递给事件过程,但此函数不会直接使用它。如果事件过程不使用此参数,则可以传入 NULL。 + 已经接收到这个对象的PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件过程不会被再次触发。 - 这个函数与分开的主要原因是在调用事件过程之前创建一个PGresult并且填充它常常是合适的。 - + 此函数与 分开的主要原因是,通常适合先创建 PGresult 并填充数据,然后再调用事件过程。 + @@ -5526,13 +5256,11 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); - 为一个PGresult对象创建一个拷贝。 - 这个拷贝不会以任何方式链接到源结果,并且当该拷贝不再需要时,必须调用进行清理。如果函数失败,返回NULL。 - + 创建 PGresult 对象的副本。副本与源结果没有任何关联,不再需要副本时必须调用 。函数失败时返回 NULL PGresult *PQcopyResult(const PGresult *src, int flags); - + 这不是为了制作一个精确的副本。返回的结果总是放在PGRES_TUPLES_OK状态中,并且不复制源中的任何错误消息。 @@ -5541,7 +5269,7 @@ PGresult *PQcopyResult(const PGresult *src, int flags); PG_COPYRES_TUPLES指定复制源结果的元组。(这也意味着复制属性。) PG_COPYRES_NOTICEHOOKS指定复制源结果的通知钩子。 PG_COPYRES_EVENTS指定复制源结果的事件。(但不复制与源相关的任何实例数据。) - 事件程序接收PGEVT_RESULTCOPY事件。 + 事件过程会收到 PGEVT_RESULTCOPY 事件。 @@ -5572,18 +5300,15 @@ int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs); - 设置一个PGresult对象的一个元组域值。 + 设置 PGresult 对象中某个元组的字段值。 int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len); - + - 这个函数将自动按需增加结果的内部元组数组。但是,tup_num参数必须小于等于,意味着这个函数对元组数组一次只能增加一个元组。 - 但已存在的任意元组中的任意域可以以任意顺序进行调整。如果field_num的一个值已经存在,它会被覆盖。 - 如果len是 -1,或valueNULL, 该域值会被设置为一个 SQL 空值。 - value会被复制到结果的私有存储中,因此函数返回后就不再需要了。如果函数失败,返回值是 0。如果函数成功,返回值会是非 0。 - + 此函数会根据需要自动扩展结果内部的元组数组。不过,tup_num 参数必须小于或等于 ,也就是说,每次只能向元组数组增加一个元组。已有元组的任何字段都可以按任意顺序修改。如果 field_num 指定的位置已有值,该值会被覆盖。如果 len 为 -1 或 valueNULL,则将该字段设置为 SQL null 值。value 会被复制到结果的私有存储中,因此函数返回后就不再需要它。函数失败时返回零,成功时返回非零值。 + @@ -5601,8 +5326,8 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); - 当res被清除时,这个函数分配的内存也会被释放掉。如果函数失败,返回值是NULL。结果被保证为按照数据的任意类型充分地对齐,正如malloc所作的。 - + 使用此函数分配的所有内存都会在清除 res 时释放。函数失败时返回 NULL。与 malloc 一样,返回的内存保证满足任意数据类型的对齐要求。 + @@ -5613,15 +5338,15 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); - 检索为PGresult对象分配的字节数。 + 获取为 PGresult 对象分配的字节数。 size_t PQresultMemorySize(const PGresult *res); - + - 此值是与PGresult对象关联的所有malloc请求的总和,就是说,将释放的所有空间。此信息可用于管理内存消耗。 - + 此值是与 PGresult 对象相关的所有 malloc 请求所分配字节数的总和,即 将释放的全部内存。这一信息有助于管理内存消耗。 + @@ -5640,28 +5365,25 @@ int PQlibVersion(void); - 在运行时,这个函数的结果可以被用来决定在当前已载入的 libpq 版本中特定的功能是否可用。 - 例如,这个函数可以被用来决定哪些选项可以被用于。 - + 可在运行时根据此函数的结果,判断当前已加载的 libpq 版本是否具有特定功能。例如,可用它判断 支持哪些连接选项。 + - 结果通过将库的主版本号乘以10000再加上次版本号形成。例如,版本10.1将被返回为100001,而版本11.0将被返回为110000。 - + 返回值等于库的主版本号乘以 10000 再加上次版本号。例如,版本 10.1 返回 100001,版本 11.0 返回 110000。 + - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。 - 对于那些版本,为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - + 在主版本 10 之前,PostgreSQL 使用由三个部分组成的版本号,前两个部分共同表示主版本。对于这些版本, 用两位数字表示每个部分;例如,版本 9.1.5 返回 90105,版本 9.2.0 返回 90200。 + - 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。 - 在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 - + 因此,为了判断功能兼容性,应用程序应将 的结果除以 100 而非 10000,得到逻辑上的主版本号。在所有版本系列中,次版本(错误修复版本)之间只有最后两位数字不同。 + - 这个函数出现于PostgreSQL版本 9.1,因此它不能被用来在早期的版本中检测所需的功能,因为调用它将会创建一个对版本9.1及其后版本的链接依赖。 + 此函数从 PostgreSQL 9.1 起提供,因而不能用它检测更早版本是否具有所需功能:调用它会建立对 9.1 或更高版本的链接依赖。 @@ -5676,13 +5398,13 @@ int PQlibVersion(void); 通知处理 - notice processing - in libpq + 通知处理 + 在 libpq 中 - 服务器产生的通知和警告消息不会被查询执行函数返回,因为它们不代表查询失败。它们可以被传递给一个通知处理函数,并且在处理者返回后执行会继续正常进行。默认的处理函数会把消息打印在stderr上,但是应用可以通过提供它自己的处理函数来重载这种行为。 - + 服务器生成的通知和警告消息不由查询执行函数返回,因为它们并不表示查询失败。这些消息会传递给通知处理函数,处理函数返回后,执行正常继续。默认通知处理函数将消息打印到 stderr,应用程序也可以提供自己的处理函数来替换这一行为。 + 由于历史原因,通知处理有两个级别,称为通知接收器和通知处理器。通知接收器的默认行为是格式化通知并且将一个字符串传递给通知处理器来打印。不过,如果一个应用选择提供自己的通知接收器,它通常会忽略通知处理器层并且在通知接收器中完成所有工作。 @@ -5690,10 +5412,10 @@ int PQlibVersion(void); 函数PQsetNoticeReceiver - notice receiver + 通知接收器 PQsetNoticeReceiver为一个连接对象设置或者检查当前的通知接收器。 相似地,PQsetNoticeProcessor - notice processor + 通知处理器 PQsetNoticeProcessor设置或检查当前的通知处理器。 @@ -5716,19 +5438,16 @@ PQsetNoticeProcessor(PGconn *conn, - 当接收到一个服务器产生的或者libpq内部产生的通知或警告消息,通知接收器函数会被调用。 - 它会以一种PGRES_NONFATAL_ERROR PGresult的形式传递该消息 - (这允许接收器使用抽取个别的域,或者使用或者得到一个完整的预格式化的消息)。 - 被传递给PQsetNoticeReceiver的同一个空指针也被传递(必要时,这个指针可以被用来访问应用相关的状态)。 - + 从服务器收到通知或警告消息,或者 libpq 内部生成这类消息时,便会调用通知接收器函数。消息以状态为 PGRES_NONFATAL_ERRORPGresult 对象传给该函数。(接收器可使用 提取单个字段,也可使用 获取完整的预格式化消息。)传给 PQsetNoticeReceiver 的同一个 void 指针也会传入。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知接收器会简单地抽取消息(使用)并且将它传递给通知处理器。 - 通知处理器负责处理一个以文本形式给出的通知或警告消息。该消息的字符串文本(包括一个收尾的新行)被传递给通知处理器,外加一个同时被传递给PQsetNoticeProcessor的空指针(必要时,这个指针可以被用来访问应用相关的状态)。 - + 通知处理器负责处理以文本形式提供的通知或警告消息。传给它的参数包括消息字符串(含末尾的换行符),以及先前传给 PQsetNoticeProcessor 的同一个 void 指针。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知处理器很简单: @@ -5742,9 +5461,8 @@ defaultNoticeProcessor(void *arg, const char *message) - 一旦你设定了一个通知接收器或处理器,你应该期待只要PGconn对象或者从它构造出的PGresult对象存在,该函数就应该能被调用。 - 在一个PGresult创建时,PGconn的当前通知处理指针被复制到PGresult中,以备类似的函数使用。 - + 设置通知接收器或处理器后,应当预期:只要 PGconn 对象或由它生成的 PGresult 对象仍存在,就可能调用该函数。创建 PGresult 时,会将 PGconn 当前的通知处理指针复制到 PGresult 中,供 等函数在需要时使用。 + @@ -5753,19 +5471,19 @@ defaultNoticeProcessor(void *arg, const char *message) 事件系统 - libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和毁灭。一种主要的使用情况是这允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 + libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和销毁。一个主要用途是允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 - 每个注册的事件处理程序都与两个数据相关联,libpq仅将其视为不透明的void *指针。 - 有一个透传指针,当事件处理程序与PGconn注册时,应用程序提供。 + 每个注册的事件处理程序都与两项数据相关联,libpq仅将其视为不透明的void *指针。 + 有一个透传指针,由应用程序在向 PGconn 注册事件处理程序时提供。 透传指针在PGconn及其生成的所有PGresult的生命周期内永远不会更改; 因此,如果使用,它必须指向长期存在的数据。 此外,还有一个实例数据指针,在每个PGconnPGresult中一开始都是NULL。 可以使用函数来操作此指针。 请注意,与透传指针不同,PGconn的实例数据不会自动继承到从中创建的PGresult。 - libpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 —— 这是事件处理程序的责任。 + libpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 — 这是事件处理程序的责任。 @@ -5824,21 +5542,12 @@ typedef struct PGEVT_CONNDESTROY - - - 为了响应,连接销毁事件会被触发。由于 libpq 没有能力管理事件数据,事件过程有责任正确地清理它的事件数据。清理失败将会导致内存泄露。 - - + 连接销毁事件由以下调用触发:。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGconn *conn; } PGEventConnDestroy; - - - 当接收到一个PGEVT_CONNDESTROY事件时,evtInfo指针应该被类型转换为PGEventConnDestroy *。 - 这个事件在执行任何其他清理之前被触发。 - 该事件过程的返回值被忽略,因为没有办法指示一个来自的失败。还有,一个事件过程失败不该中断对不需要的内存的清理。 - +收到PGEVT_CONNDESTROY事件时,应将evtInfo指针强制转换为PGEventConnDestroy *。该事件触发于以下函数执行任何其他清理工作之前:。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:。此外,事件过程失败不应中止清理不再使用的内存的过程。 @@ -5894,21 +5603,12 @@ typedef struct PGEVT_RESULTDESTROY - - - 为了响应,结果销毁事件会被触发。由于 libpq 没有能力管理事件数据,事件过程有责任正确地清理它的事件数据。清理失败将会导致内存泄露。 - - + 结果销毁事件由以下调用触发:。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGresult *result; } PGEventResultDestroy; - - - 当接收到一个PGEVT_RESULTDESTROY事件时,evtInfo指针应该被类型转换为PGEventResultDestroy *。 - 这个事件在执行任何其他清理之前被触发。该事件过程的返回值被忽略,因为没有办法指示来自的失败。 - 还有,一个事件过程失败不该中断不需要的内存的清理过程。 - +收到PGEVT_RESULTDESTROY事件时,应将evtInfo指针强制转换为PGEventResultDestroy *。该事件触发于以下函数执行任何其他清理工作之前:。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:。此外,事件过程失败不应中止清理不再使用的内存的过程。 @@ -5916,7 +5616,7 @@ typedef struct - 事件回调函数 + 事件回调过程 @@ -5926,16 +5626,11 @@ typedef struct - PGEventProc是到一个事件过程的指针的 typedef,也就是从 libpq 接收事件的用户回调函数。一个事件过程的原型必须是 - + PGEventProc 是通过 typedef 定义的事件过程指针类型,也就是接收 libpq 事件的用户回调函数的指针类型。事件过程的签名必须为: int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) - - evtId指示发生了哪一个PGEVT事件。 - evtInfo指针必须被类型转换为合适的结构体类型才能获得关于事件的进一步信息。 - 当事件过程已被注册时,passThrough参数是提供给的指针。 - 如果成功,该函数应该返回非零值,失败则返回零。 +evtId 参数指示发生了哪一种 PGEVT 事件。必须将 evtInfo 指针强制转换为适当的结构体类型,以获取关于该事件的更多信息。passThrough 参数是在注册事件过程时传给 的指针。函数应在成功时返回非零值,在失败时返回零。 @@ -5945,8 +5640,8 @@ int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) - 在 Windows 上,函数能够有两个不同的地址:一个对 DLL 之外可见而另一个对 DLL 之内可见。我们应当小心只有其中之一会被用于libpq的事件过程函数,否则将会产生混淆。编写代码的最简单规则是将所有的事件过程声明为static。如果过程的地址必须对它自己的源代码文件之外可见,提供一个单独的函数来返回该地址。 - + 在 Windows 上,函数可能有两个不同的地址:一个在 DLL 外部可见,另一个在 DLL 内部可见。使用 libpq 的事件过程函数时,务必始终使用其中同一个地址,否则会产生混淆。确保代码正常工作的最简单做法,是将事件过程声明为 static。如果需要在过程所在的源文件之外取得其地址,应提供一个单独的函数来返回该地址。 + @@ -5974,7 +5669,7 @@ int PQregisterEventProc(PGconn *conn, PGEventProc proc, - 在每一个你想要接收事件的PGconn上必须注册一个事件过程。和内存不同,没有限制说一个连接上能注册多少个事件过程。如果该函数成功,它会返回一个非零值。如果它失败,则会返回零。 + 对于希望接收其事件的每个 PGconn,都必须注册一次事件过程。一个连接可注册的事件过程数量只受内存限制。函数成功时返回非零值,失败时返回零。 @@ -6019,16 +5714,14 @@ void *PQinstanceData(const PGconn *conn, PGEventProc proc); - 把结果的用于procinstanceData设置为data。成功返回非零,失败返回零(只有proc没有被正确地注册在conn中,才可能会失败)。 - + 将结果中针对 procinstanceData 设置为 data。成功时返回非零值,失败时返回零。(只有当 proc 未在结果中正确注册时,才可能失败。) int PQresultSetInstanceData(PGresult *res, PGEventProc proc, void *data); - 请注意,data表示的任何存储都不会由考虑,除非使用分配。 - (这样做是值得推荐的,因为它消除了在销毁结果时显式释放此类存储的需要。) + 注意,data 所指的存储不会计入 ,除非使用 分配它。(推荐这样做,因为结果销毁时便不必显式释放这部分存储。) @@ -6052,18 +5745,18 @@ void *PQresultInstanceData(const PGresult *res, PGEventProc proc); - 事件实例 + 事件示例 - 这里是一个管理与 libpq 连接和结果相关的私有数据的示例的框架。 - + 下面给出一个示例框架,用于管理与 libpq 连接和结果关联的私有数据。 + -/* The instanceData */ +/* instanceData 数据 */ typedef struct { int n; @@ -6083,14 +5776,14 @@ main(void) if (PQstatus(conn) != CONNECTION_OK) { - /* PQerrorMessage's result includes a trailing newline */ + /* PQerrorMessage 的结果包含末尾的换行符 */ fprintf(stderr, "%s", PQerrorMessage(conn)); PQfinish(conn); return 1; } - /* called once on any connection that should receive events. - * Sends a PGEVT_REGISTER to myEventProc. + /* 在每个需要接收事件的连接上调用一次。 + * 向 myEventProc 发送 PGEVT_REGISTER 事件。 */ if (!PQregisterEventProc(conn, myEventProc, "mydata_proc", NULL)) { @@ -6099,28 +5792,28 @@ main(void) return 1; } - /* conn instanceData is available */ + /* 可以取得 conn 的 instanceData */ data = PQinstanceData(conn, myEventProc); - /* Sends a PGEVT_RESULTCREATE to myEventProc */ + /* 向 myEventProc 发送 PGEVT_RESULTCREATE 事件 */ res = PQexec(conn, "SELECT 1 + 1"); - /* result instanceData is available */ + /* 可以取得结果的 instanceData */ data = PQresultInstanceData(res, myEventProc); - /* If PG_COPYRES_EVENTS is used, sends a PGEVT_RESULTCOPY to myEventProc */ + /* 使用 PG_COPYRES_EVENTS 时,向 myEventProc 发送 PGEVT_RESULTCOPY 事件 */ res_copy = PQcopyResult(res, PG_COPYRES_TUPLES | PG_COPYRES_EVENTS); - /* result instanceData is available if PG_COPYRES_EVENTS was - * used during the PQcopyResult call. + /* 如果调用 PQcopyResult 时使用了 PG_COPYRES_EVENTS, + * 就可以取得结果的 instanceData。 */ data = PQresultInstanceData(res_copy, myEventProc); - /* Both clears send a PGEVT_RESULTDESTROY to myEventProc */ + /* 两次清除操作都会向 myEventProc 发送 PGEVT_RESULTDESTROY 事件 */ PQclear(res); PQclear(res_copy); - /* Sends a PGEVT_CONNDESTROY to myEventProc */ + /* 向 myEventProc 发送 PGEVT_CONNDESTROY 事件 */ PQfinish(conn); return 0; @@ -6136,7 +5829,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventRegister *e = (PGEventRegister *)evtInfo; mydata *data = get_mydata(e->conn); - /* associate app specific data with connection */ + /* 将应用程序特有的数据与连接关联 */ PQsetInstanceData(e->conn, myEventProc, data); break; } @@ -6156,7 +5849,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventConnDestroy *e = (PGEventConnDestroy *)evtInfo; mydata *data = PQinstanceData(e->conn, myEventProc); - /* free instance data because the conn is being destroyed */ + /* 连接正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; @@ -6168,7 +5861,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *conn_data = PQinstanceData(e->conn, myEventProc); mydata *res_data = dup_mydata(conn_data); - /* associate app specific data with result (copy it from conn) */ + /* 将应用程序特有的数据与结果关联(从 conn 复制) */ PQresultSetInstanceData(e->result, myEventProc, res_data); break; } @@ -6179,7 +5872,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *src_data = PQresultInstanceData(e->src, myEventProc); mydata *dest_data = dup_mydata(src_data); - /* associate app specific data with result (copy it from a result) */ + /* 将应用程序特有的数据与结果关联(从另一个结果复制) */ PQresultSetInstanceData(e->dest, myEventProc, dest_data); break; } @@ -6189,18 +5882,18 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventResultDestroy *e = (PGEventResultDestroy *)evtInfo; mydata *data = PQresultInstanceData(e->result, myEventProc); - /* free instance data because the result is being destroyed */ + /* 结果正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; } - /* unknown event ID, just return true. */ + /* 未知的事件 ID,直接返回 true。 */ default: break; } - return true; /* event processing succeeded */ + return true; /* 事件处理成功 */ } ]]> @@ -6216,10 +5909,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 以下环境变量可用于选择默认连接参数值,这些值将被使用,如果调用代码没有直接指定值。这些对于避免将数据库连接信息硬编码到简单的客户端应用程序中非常有用,例如。 - - - + 以下环境变量可用于选择连接参数的默认值,供 在调用代码未直接指定参数值时使用。例如,这样可以避免在简单的客户端应用程序中硬编码数据库连接信息。 + + @@ -6229,8 +5921,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-host"/>连接参数相同。 - - + @@ -6241,8 +5932,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) 这可以替代或者与PGHOST一起设置,以避免DNS查找开销。 - - + @@ -6252,8 +5942,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-port"/>连接参数相同。 - - + @@ -6263,8 +5952,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-dbname"/>连接参数相同。 - - + @@ -6274,8 +5962,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-user"/>连接参数相同。 - - + @@ -6286,8 +5973,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) 而应考虑使用密码文件(参见)。 - - + @@ -6297,8 +5983,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-passfile"/>连接参数相同。 - - + PGREQUIREAUTH @@ -6306,8 +5991,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGREQUIREAUTH的行为与连接参数相同。 - - + @@ -6317,8 +6001,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-channel-binding"/>连接参数相同。 - - + @@ -6328,20 +6011,17 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-service"/>连接参数相同。 - - + PGSERVICEFILE - PGSERVICEFILE指定每个用户的连接服务文件的名称 - (参见)。 - 默认为~/.pg_service.conf,或者在Microsoft Windows上为%APPDATA%\postgresql\.pg_service.conf。 + PGSERVICEFILE指定每个用户的连接服务文件的名称(参见)。 + 默认为~/.pg_service.conf,或者在 Microsoft Windows 上为%APPDATA%\postgresql\.pg_service.conf - - + @@ -6351,8 +6031,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-options"/>连接参数相同。 - - + @@ -6362,8 +6041,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-application-name"/>连接参数相同。 - - + @@ -6373,8 +6051,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslmode"/>连接参数相同。 - - + @@ -6382,11 +6059,10 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGREQUIRESSL的行为与连接参数相同。 - 这个环境变量已被弃用,推荐使用PGSSLMODE变量;设置这两个变量会抑制这个变量的效果。 + 这个环境变量已被弃用,推荐使用PGSSLMODE变量;同时设置这两个变量时,前者不再生效。 - - + @@ -6396,8 +6072,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslcompression"/>连接参数相同。 - - + @@ -6407,8 +6082,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslcert"/>连接参数相同。 - - + @@ -6418,8 +6092,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslkey"/>连接参数相同。 - - + PGSSLCERTMODE @@ -6427,8 +6100,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSSLCERTMODE的行为与连接参数相同。 - - + @@ -6438,8 +6110,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslrootcert"/>连接参数相同。 - - + @@ -6449,8 +6120,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslcrl"/>连接参数相同。 - - + @@ -6460,8 +6130,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslcrldir"/>连接参数相同。 - - + @@ -6471,8 +6140,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslsni"/>连接参数相同。 - - + @@ -6482,8 +6150,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-requirepeer"/>连接参数相同。 - - + @@ -6493,8 +6160,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-ssl-min-protocol-version"/>连接参数相同。 - - + @@ -6504,8 +6170,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-ssl-max-protocol-version"/>连接参数相同。 - - + @@ -6515,8 +6180,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-gssencmode"/>连接参数相同。 - - + @@ -6526,8 +6190,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-krbsrvname"/>连接参数相同。 - - + @@ -6537,8 +6200,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-gsslib"/>连接参数相同。 - - + PGGSSDELEGATION @@ -6546,8 +6208,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGGSSDELEGATION的行为与连接参数相同。 - - + @@ -6557,8 +6218,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-connect-timeout"/>连接参数相同。 - - + @@ -6568,8 +6228,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-client-encoding"/>连接参数相同。 - - + @@ -6579,14 +6238,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-target-session-attrs"/>连接参数相同。 - - - - - 下面的环境变量可用来为每一个PostgreSQL会话指定默认行为(为每一个用户或每一个数据库设置默认行为的方法还可见命令)。 - - - + PGLOADBALANCEHOSTS @@ -6594,8 +6246,13 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGLOADBALANCEHOSTS的行为与连接参数相同。 + + - + + 以下环境变量可用于指定每个 PostgreSQL 会话的默认行为。(也可参见 命令,了解按用户或按数据库设置默认行为的方法。) + + PGDATESTYLE @@ -6603,8 +6260,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGDATESTYLE设置日期/时间表示的默认风格(等同于SET datestyle TO ...)。 - - + PGTZ @@ -6612,8 +6268,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGTZ设置默认的时区(等同于SET timezone TO ...)。 - - + PGGEQO @@ -6622,8 +6277,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - - 这些环境变量的正确值可参考SQL 命令 。 +有关这些环境变量的正确取值,请参见 SQL 命令 @@ -6668,16 +6322,12 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) 用户主目录中的.pgpass文件可保存密码,供连接需要密码且尚未通过其他方式指定密码时使用。在 Microsoft Windows 上,文件名为%APPDATA%\postgresql\pgpass.conf(其中%APPDATA%指用户配置文件中的应用数据子目录)。也可以通过连接参数或环境变量PGPASSFILE指定要使用的密码文件。 - - 这个文件应该包含下列格式的行: - + 该文件中的行应采用以下格式: hostname:port:database:username:password - - (你可以向该文件增加一个提醒:把上面的行复制到该文件并且在前面加上#)。前四个字段的每一个都可以是字面值或者匹配任何东西的*。第一个匹配当前连接参数的行中的密码字段将被使用(因此,在使用通配符时把更特殊的项放在前面)。如果一个条目需要包含:或者\,用\对该字符转义。如果指定了host连接参数,主机名字段会被匹配到host,否则如果指定了hostaddr参数则匹配到hostaddr,如果两者都没有给出,则会搜索主机名localhost。当连接是一个Unix域套接字连接并且host参数匹配libpq的默认套接字目录路径时,也会搜索主机名localhost。在一台备库上,值为replication的数据库字段匹配连接到主库的流复制连接。否则数据库字段的用途有限,因为用户对同一个集簇中的所有数据库都有相同的密码。 - +(可以复制上面这一行,并在行首加上#,在文件中加入提示注释。)前四个字段中的每一个都可以是字面值,或者是*,后者可以匹配任何内容。将使用与当前连接参数匹配的第一行中的密码字段。(因此,使用通配符时,应将更具体的条目放在前面。)如果条目需要包含:\,请使用\转义该字符。主机名字段首先匹配已指定的host连接参数;否则匹配已指定的hostaddr参数。如果两者都未指定,则查找主机名localhost。在以下情况下也会查找主机名localhost:连接使用 Unix 域套接字,且host参数与libpq的默认套接字目录路径匹配。在备库中,数据库字段为replication时,匹配连接到主库的流复制连接。除此之外,数据库字段的用途有限,因为同一用户在同一数据库集簇的所有数据库中使用相同的密码。 - 在 Unix 系统上,密码文件上的权限必须不允许所有人或组内访问,可以用chmod 0600 ~/.pgpass这样的命令实现。如果权限没有这么严格,该文件将被忽略。在微软 Windows 上,该文件被假定存储在一个安全的目录中,因此不会进行特别的权限检查。 + 在 Unix 系统上,密码文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.pgpass 这样的命令实现。如果权限没有这么严格,该文件将被忽略。在 Microsoft Windows 上,假定该文件存储在安全的目录中,因此不进行特殊的权限检查。 @@ -6698,10 +6348,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 连接服务文件允许 libpq 连接参数与一个单一服务名称关联。 - 那个服务名称可以在一个 libpq 连接字符串里面指定,与其相关的设置将被使用。 - 这允许在不重新编译使用 libpq 的应用的前提下修改连接参数。 - 服务名称也可以被使用PGSERVICE环境变量来指定。 + 连接服务文件允许将 libpq 连接参数与单个服务名称关联。随后可以在 libpq 连接字符串中指定该服务名称,从而使用关联的设置。这样便可以修改连接参数,而无需重新编译使用 libpq 的应用程序。也可以使用 PGSERVICE 环境变量指定服务名称。 @@ -6717,23 +6364,19 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 或者服务文件使用一种INI 文件格式,其中小节名是服务名并且参数是连接参数。 - 列表见。例如: + 两种服务文件均使用 INI 文件 格式,其中配置段名称是服务名称,参数是连接参数;参数列表见 。例如: -# comment +# 注释 [mydb] host=somehost port=5433 user=admin - 在PostgreSQL安装的share/pg_service.conf.sample中提供了一个示例文件。 +PostgreSQL 安装目录中的 share/pg_service.conf.sample 提供了一个示例文件。 - 从服务文件中获取的连接参数与从其他来源获取的参数相结合。 - 服务文件设置覆盖相应的环境变量,然后反过来可以由连接字符串中直接给出的值覆盖。 - 例如,使用上面的服务文件,连接字符串service=mydb port=5434将使用主机somehost,端口5434, - 用户admin,以及由环境变量或内置默认所设置的其他参数。 + 从服务文件中获取的连接参数会与其他来源的参数合并。服务文件中的设置会覆盖相应的环境变量,而连接字符串中直接给出的值又会覆盖服务文件中的设置。例如,使用上述服务文件时,连接字符串 service=mydb port=5434 将使用主机 somehost、端口 5434、用户 admin,以及由环境变量或内置默认值设置的其他参数。 @@ -6749,24 +6392,14 @@ user=admin 如果libpq已经在编译时打开了 LDAP 支持(configure的选项),就可以通过 LDAP 从一个中央服务器检索hostdbname之类的连接参数。这样做的好处是如果一个数据库的连接参数改变,不需要在所有的客户端机器上更新连接信息。 - - LDAP连接参数查找使用连接服务文件pg_service.conf(参见)。 - 在pg_service.conf段落中以ldap://开头的行将被识别为LDAP URL,并执行LDAP查询。 - 结果必须是一组keyword = value对,将用于设置连接选项。 - URL必须符合RFC 1959的形式为 - + LDAP 连接参数查询使用连接服务文件pg_service.conf(参见)。在pg_service.conf的配置段中,以ldap://开头的行会被识别为 LDAP URL,并执行 LDAP 查询。结果必须是一个keyword = value键值对列表,用于设置连接选项。URL 必须符合 RFC 1959,格式如下: ldap://[hostname[:port]]/search_base?attribute?search_scope?filter - - 其中hostname默认为localhostport默认为389。 - +其中,hostname默认为localhostport默认为 389。 - - 一次成功的 LDAP 查找后,pg_service.conf的处理被终止。但是如果联系不上 LDAP 则会继续处理pg_service.conf。这就提供了后手,可以加入更多指向不同 LDAP 服务器的 LDAP URL 行、经典的keyword = value对或者默认连接选项。如果你宁愿在这种情况下得到一个错误消息,在该 LDAP URL 之后增加一个语法错误的行。 - + LDAP 查找成功后就会停止处理 pg_service.conf;如果无法联系 LDAP 服务器,则会继续处理。这使后续指向其他 LDAP 服务器的 LDAP URL 行、常规的 keyword = value 对或默认连接选项能够作为后备。如果希望在这种情况下得到错误消息,可以在 LDAP URL 后添加一个语法不正确的行。 - - 一个和 LDIF 文件一起创建的 LDAP 条目实例 - + 例如,使用以下 LDIF 文件创建的 LDAP 条目: version:1 dn:cn=mydatabase,dc=mycompany,dc=com changetype:add @@ -6778,9 +6411,7 @@ description:port=5439 description:dbname=mydb description:user=mydb_user description:sslmode=require - - 可以用下面的 LDAP URL 查询: - +可以通过以下 LDAP URL 查询: ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase) @@ -6788,7 +6419,7 @@ ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase) 你也可以将常规的服务文件条目和 LDAP 查找混合。pg_service.conf中一节的完整示例: -# 只有主机和端口存储在LDAP中,显式指定dbname和user。 +# 仅 host 和 port 存储在 LDAP 中;显式指定 dbname 和 user [customerdb] dbname=customer user=appuser @@ -6808,9 +6439,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - PostgreSQL具有原生支持使用SSL连接来加密客户端/服务器通信, - 使用TLS协议以提高安全性。有关服务器端SSL功能的详细信息,请参见。 - + PostgreSQL 原生支持使用 SSL 连接,通过 TLS 协议加密客户端与服务器之间的通信,以提高安全性。有关服务器端 SSL 功能的详细信息,请参见 。 + libpq读取系统范围的OpenSSL配置文件。默认情况下,这个文件被命名为openssl.cnf并且位于openssl version -d所报告的目录中。可以通过设置环境变量OPENSSL_CONF把这个默认值覆盖为想要的配置文件的名称。 @@ -6818,39 +6448,25 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 服务器证书的客户端验证 + 客户端对服务器证书的验证 - 默认情况下,PostgreSQL将不会执行服务器证书的任何验证。这意味着可以在不被客户端知晓的情况下伪造服务器身份(例如通过修改一个 DNS 记录或者接管服务器的 IP 地址)。为了阻止哄骗,客户端必须能够通过一条信任链验证服务器的身份。信任链可以这样建立:在一台计算机上放置一个根(自签名的)证书机构(CA)的证书并且在另一台计算机上放置一个由根证书签发的叶子证书。还可以使用一种中间证书,它由根证书签发并且可以签发叶子证书。 + 默认情况下,PostgreSQL 不会对服务器证书执行任何验证。这意味着可以在客户端不知情的情况下伪造服务器身份,例如修改 DNS 记录或接管服务器的 IP 地址。要防止身份伪造,客户端必须能够通过信任链验证服务器身份。建立信任链的方法是:在一台计算机上放置根证书机构(CA)的自签名证书,在另一台计算机上放置由根证书签发的叶证书。也可以使用由根证书签发、又用于签发叶证书的中间证书。 - - 为了允许客户端验证服务器的身份,在客户端上放置一份根证书并且在服务器上放置由根证书签发的叶子证书。为了允许服务器验证客户端的身份,在服务器上放置一份根证书并且在客户端上放置由根证书签发的叶子证书。也可以使用一个或者更多个中间证书(通常与叶子证书存在一起)来将叶子证书链接到根证书。 - + 要让客户端验证服务器的身份,请在客户端放置根证书,并在服务器上放置由该根证书签发的叶证书。要让服务器验证客户端的身份,请在服务器上放置根证书,并在客户端放置由该根证书签发的叶证书。也可以使用一个或多个中间证书(通常与叶证书存储在一起),将叶证书链接到根证书。 - - 一旦信任链被建立起来,客户端有两种方法验证服务器发过来的叶子证书。如果参数sslmode被设置为verify-ca,libpq将通过检查该证书是否链接到存储在客户端上的根证书来验证服务器。如果sslmode被设置为verify-full,libpq将验证服务器的主机名匹配存储在服务器证书中的名称。如果服务器证书无法被验证,则SSL连接将失败。在大部分对安全性很敏感的环境中,推荐使用verify-full。 - + 建立信任链后,客户端可以通过两种方式验证服务器发送的叶证书。如果参数 sslmode 设为 verify-ca,libpq 会沿证书链检查到存储在客户端上的根证书,以验证服务器是否可信。如果 sslmode 设为 verify-full,libpq 还会验证服务器主机名是否与服务器证书中存储的名称匹配。如果无法验证服务器证书,SSL 连接将失败。在大多数对安全敏感的环境中,建议使用 verify-full - 在verify-full模式下,主机名将与证书的主体替代名称属性(SAN)匹配, - 或者与通用名称属性匹配,如果没有类型为dNSName的SAN存在。 - 如果证书的名称属性以星号(*)开头,那么星号将被视为通配符, - 可以匹配所有字符,除了点(.)。 - 这意味着证书将不匹配子域。如果连接使用IP地址而不是主机名进行, - 则IP地址将与类型为iPAddressdNSName的SAN匹配 - (不进行任何DNS查找)。如果没有iPAddress SAN存在, - 也没有匹配的dNSName SAN存在,则主机IP地址将与通用名称属性匹配。 - + 在 verify-full 模式下,会将主机名与证书的主体替代名称属性(SAN)匹配;如果不存在类型为 dNSName 的 SAN,则与通用名称属性匹配。如果证书的名称属性以星号(*)开头,该星号会被视为通配符,匹配点(.)以外的所有字符。这意味着该证书不会匹配子域。如果使用 IP 地址而不是主机名建立连接,则会将该 IP 地址与类型为 iPAddressdNSName 的 SAN 匹配(不执行任何 DNS 查询)。如果不存在 iPAddress SAN,也不存在匹配的 dNSName SAN,则将主机 IP 地址与通用名称属性匹配。 + - 为了与早期版本的PostgreSQL向后兼容,主机IP地址的验证方式与 - RFC 6125中的方式不同。 - 主机IP地址始终与dNSName SANs以及iPAddress SANs匹配, - 如果不存在相关的SANs,则可以与通用名称属性匹配。 - + 为与 PostgreSQL 的早期版本向后兼容,主机 IP 地址的验证方式与 RFC 6125 不同。主机 IP 地址始终会与 dNSName SAN 以及 iPAddress SAN 匹配;如果不存在相关的 SAN,还可以与通用名称属性匹配。 + @@ -6870,8 +6486,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 为了与 PostgreSQL 的早期版本达到向后兼容,如果存在一个根 CA 文件,sslmode=require的行为将与verify-ca相同,即服务器证书根据 CA 验证。我们鼓励依赖这种行为,并且需要证书验证的应用应该总是使用verify-ca或者verify-full。 - + 为与 PostgreSQL 的早期版本向后兼容,如果存在根 CA 文件,sslmode=require 的行为将与 verify-ca 相同,即根据 CA 验证服务器证书。不建议依赖这种行为;需要证书验证的应用程序应始终使用 verify-caverify-full。 + @@ -6880,44 +6496,27 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 客户端证书 - 如果服务器尝试通过请求客户端的叶证书来验证客户端的身份, - libpq将发送存储在文件 - ~/.postgresql/postgresql.crt中的证书,该文件位于用户的主目录中。 - 证书必须链到服务器信任的根证书。匹配的 - 私钥文件~/.postgresql/postgresql.key也必须存在。 - 在Microsoft Windows上,这些文件的名称分别为 - %APPDATA%\postgresql\postgresql.crt和 - %APPDATA%\postgresql\postgresql.key。 - 证书和密钥文件的位置可以通过连接参数 - sslcertsslkey, - 或通过环境变量PGSSLCERTPGSSLKEY来覆盖。 - + 如果服务器请求客户端的叶证书以验证客户端身份,libpq 将发送用户主目录下 ~/.postgresql/postgresql.crt 文件中存储的证书。这些证书必须通过证书链连接到服务器信任的根证书。还必须存在匹配的私钥文件 ~/.postgresql/postgresql.key。在 Microsoft Windows 上,这两个文件分别名为 %APPDATA%\postgresql\postgresql.crt%APPDATA%\postgresql\postgresql.key。可以通过连接参数 sslcertsslkey,或环境变量 PGSSLCERTPGSSLKEY,覆盖证书和密钥文件的位置。 + - 在Unix系统上,私钥文件的权限必须禁止任何对世界或组的访问;可以通过类似以下命令来实现: - chmod 0600 ~/.postgresql/postgresql.key。 - 或者,该文件可以由root拥有并具有组读取权限(即0640权限)。 - 该设置适用于由操作系统管理证书和密钥文件的安装。然后,libpq的用户应该成为具有对这些证书和密钥文件访问权限的组的成员。 - (在Microsoft Windows上,没有文件权限检查,因为假定%APPDATA%\postgresql目录是安全的。) - + 在 Unix 系统上,私钥文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.postgresql/postgresql.key 这样的命令实现。另一种做法是使文件归 root 所有,并允许组用户读取(即 0640 权限)。这种设置适用于由操作系统管理证书和密钥文件的安装环境。此时,应将 libpq 用户加入有权访问这些证书和密钥文件的组。(在 Microsoft Windows 上,不检查文件权限,因为假定 %APPDATA%\postgresql 目录是安全的。) + postgresql.crt中的第一个证书必须是客户端的证书,因为它必须匹配客户端的私钥。可以选择将中间证书追加到该文件 — 这样做避免了在服务器上存放中间证书的要求()。 - 证书和密钥可能是 PEM 或 ASN.1 DER 格式。 + 证书和密钥可以采用 PEM 或 ASN.1 DER 格式。 - 密钥可以以明文存储,也可以使用OpenSSL支持的任何算法(例如AES-128)使用密码进行加密。 - 如果密钥是加密存储的,那么可以在连接选项中提供密码。 - 如果提供了加密密钥,而且sslpassword选项不存在或为空,那么只要 TTY 可用,OpenSSL就会以Enter PEM pass phrase:提示交互式输入密码。 - 应用程序可以通过提供自己的密钥密码回调,覆盖客户端证书提示以及sslpassword参数的处理;参见。 + 密钥可以以明文存储,也可以使用密码,按 OpenSSL 支持的任意算法(例如 AES-128)进行加密。如果密钥以加密形式存储,可以在 连接选项中提供密码。如果提供了加密密钥,而 sslpassword 选项缺失或为空,则在有 TTY 可用时,OpenSSL 会显示 Enter PEM pass phrase: 提示,交互式地请求输入密码。应用程序可以提供自己的密钥密码回调,以覆盖客户端证书提示及 sslpassword 参数的处理;参见 - 创建证书的指令请参考。 + 有关创建证书的说明,请参见 @@ -6926,8 +6525,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 不同模式中提供的保护 - sslmode参数的不同值提供了不同级别的保护。SSL 能够针对三类攻击提供保护: - + sslmode 参数的不同值提供不同级别的保护。SSL 可以防范三类攻击: 窃听 @@ -6940,31 +6538,33 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 中间人(MITM - 如果一个第三方能对客户端和服务器之间传送的数据进行修改,它就能假装是服务器并且因此能看见并且修改数据,即使这些数据已被加密。然后第三方可以将连接信息和数据转送给原来的服务器,使得它不可能检测到攻击。这样做的通常途径包括 DNS 污染和地址劫持,借此客户端被重定向到一个不同的服务器。还有几种其他的攻击方式能够完成这种攻击。SSL使用证书验证让客户端认证服务器,就可以阻止这种攻击。 - + + 如果第三方能修改客户端与服务器之间传输的数据,就可以冒充服务器,进而查看和修改数据,即使数据已经加密。随后,第三方可以将连接信息和数据转发给原来的服务器,使攻击无法被察觉。常见的手段包括 DNS 污染和地址劫持,从而将客户端引向预期之外的服务器。还有其他几种攻击手段可以达到同样的目的。SSL 使用证书验证,让客户端认证服务器身份,以防范这种攻击。 + - 模仿 + 冒充 - 如果一个第三方能假装是一个授权的客户端,它能够简单地访问它本不能访问的数据。通常这可以由不安全的密码管理所致。SSL使用客户端证书来确保只有持有合法证书的客户端才能访问服务器,这样就能阻止这种攻击。 - + + 如果第三方能冒充获授权的客户端,就能直接访问其无权访问的数据。这通常可能由不安全的密码管理导致。SSL 使用客户端证书,确保只有持有有效证书的客户端才能访问服务器,以防范这种攻击。 + - 对于一个已知受 SSL 保护的连接,在连接建立之前,必须在客户端和服务器两端都配置 SSL。如果只在服务器端配置,客户端在得知服务器要求高安全性之前,可能就已经开始发送敏感信息(例如密码)。在 libpq 中,要确保连接安全,可以把sslmode参数设置为verify-fullverify-ca,并为系统提供一个用于验证的根证书。这类似于使用https URL浏览加密网页。 + 要确保连接受到 SSL 保护,必须在建立连接之前,在客户端和服务器两端配置 SSL。如果仅在服务器上配置,客户端可能在得知服务器要求高安全性之前就已发送敏感信息(例如密码)。在 libpq 中,可以将 sslmode 参数设为 verify-fullverify-ca,并向系统提供用于验证的根证书,以确保连接安全。这类似于使用 https URL 进行加密的网页浏览。 - 一旦服务器已经被认证,客户端可以传递敏感数据。这意味着直到这一点,客户端都不需要知道是否证书将被用于认证,这样只需要在服务器配置中指定就比较安全。 + 服务器通过身份认证后,客户端便可以传送敏感数据。这意味着,在此之前,客户端无需知道是否会使用证书进行认证,因此可以安全地仅在服务器配置中指定这一点。 - 所有SSL选项都带来了加密和密钥交换的负荷,因此必须在性能和安全性之间做出平衡。不同sslmode值所保护的风险,以及它们是怎样看待安全性和负荷的。 + 所有 SSL 选项都会产生加密和密钥交换的开销,因此必须在性能与安全性之间作出权衡。 说明了不同 sslmode 值所能防范的风险,以及它们所表达的对安全性和开销的取舍。
@@ -6980,7 +6580,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) sslmode 窃听保护 - 中间人攻击防护 + MITM 防护 声明 @@ -6991,7 +6591,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) disable - 我不关心安全性,并且我不想为加密增加负荷。 + 我不关心安全性,并且我不想为加密增加开销。 @@ -6999,7 +6599,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) allow 可能 - 我不关心安全性,但如果服务器坚持,我将承担加密带来的负荷。 + 我不关心安全性,但如果服务器坚持,我将承担加密带来的开销。 @@ -7007,7 +6607,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) prefer 可能 - 我不关心安全性,但如果服务器支持,我希望承担加密带来的负荷。 + 我不关心加密,但如果服务器支持,我希望承担加密带来的开销。 @@ -7015,7 +6615,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) require - 我想要对数据加密,并且我接受因此带来的负荷。我信任该网络会保证我总是连接到想要连接的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我信任该网络会保证我总是连接到想要连接的服务器。 @@ -7023,7 +6623,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-ca 取决于 CA 策略 - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器。 @@ -7031,7 +6631,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-full - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 @@ -7040,11 +6640,11 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
- verify-caverify-full之间的区别取决于根CA的策略。如果使用了一个公共CAverify-ca允许连接到那些可能已经被其他人注册到该CA的服务器。在这种情况下,总是应该使用verify-full。如果使用了一个本地CA或者甚至是一个自签名的证书,使用verify-ca常常就可以提供足够的保护。 + verify-caverify-full之间的区别取决于根CA的策略。如果使用了一个公共CAverify-ca允许连接到那些可能已经被其他人注册到该CA的服务器。在这种情况下,总是应该使用verify-full。如果使用了一个本地CA或者甚至是一个自签名的证书,使用verify-ca常常就可以提供足够的保护。 - sslmode的默认值是prefer。如表中所示,这在安全性的角度来说没有意义,并且它只承诺可能的性能负荷。提供它作为默认值只是为了向后兼容,并且我们不推荐在安全部署中使用它。 + sslmode 的默认值是 prefer。如表所示,从安全角度看,这一设置没有意义;它只会在可能时带来性能开销。将其作为默认值仅出于向后兼容的考虑,不建议在有安全要求的部署中使用。 @@ -7086,8 +6686,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) ~/.postgresql/root.crt - 可信的证书机构 - 检查服务器证书是由一个可信的证书机构签发 + 受信任的证书机构 + 检查服务器证书是由一个受信任的证书机构签发 @@ -7106,9 +6706,9 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) SSL 库初始化 - 如果您的应用程序初始化libssl和/或libcrypto库,并且libpq - 构建时带有SSL支持,您应该调用告诉libpq - libssl和/或libcrypto库已被您的应用程序初始化,以便 + 如果你的应用程序初始化libssl和/或libcrypto库,并且libpq + 构建时带有SSL支持,你应该调用告诉libpq + libssl和/或libcrypto库已被你的应用程序初始化,以便 libpq不会再初始化这些库。 但是,当使用OpenSSL版本1.1.0或更高版本时,无需这样做,因为重复初始化不再成问题。 @@ -7120,7 +6720,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 允许应用选择要初始化哪个安全性库。 + 允许应用程序选择要初始化的安全库。 void PQinitOpenSSL(int do_ssl, int do_crypto); @@ -7144,7 +6744,7 @@ void PQinitOpenSSL(int do_ssl, int do_crypto); PQinitSSLPQinitSSL - 允许应用选择要初始化哪个安全性库。 + 允许应用程序选择要初始化的安全库。 void PQinitSSL(int do_ssl); @@ -7170,7 +6770,7 @@ void PQinitSSL(int do_ssl); - 在线程化程序中的行为 + 多线程程序中的行为 线程 @@ -7204,7 +6804,9 @@ int PQisthreadsafe(); PGresult对象在创建后通常是只读的,因此可以在线程之间自由传递。不过,如果你使用中描述的任何会修改PGresult的函数,则需要自行避免对同一个PGresult执行并发操作。 - 已弃用的 函数不是线程安全的,不应在多线程程序中使用。可以用 替代 ,用 替代 + + 已弃用的函数 不是线程安全的,不应在多线程程序中使用。 可以用 替代; 可以用 替代。 + 如果你在应用程序中使用 Kerberos(除了libpq内部之外),则需要在 Kerberos 调用周围加锁,因为 Kerberos 函数不是线程安全的。可参考libpq源代码中的PQregisterThreadLock函数,它提供了一种在libpq与应用程序之间协作加锁的方法。 @@ -7213,7 +6815,7 @@ int PQisthreadsafe(); - 编译 <application>libpq</application> 程序 + 构建 <application>libpq</application> 程序 编译 @@ -7221,16 +6823,16 @@ int PQisthreadsafe(); - 要编译(即编译并且链接)一个使用libpq的程序,你需要做下列所有的事情: + 要构建(即编译和链接)一个使用 libpq 的程序,需要完成以下所有步骤: - 包括libpq-fe.h头文件: + 包含 libpq-fe.h 头文件: #include <libpq-fe.h> - 如果你无法这样做,那么你通常会从你的编译器得到像这样的错误消息: +如果没有这样做,编译器通常会给出类似以下内容的错误消息: foo.c: In function `main': foo.c:34: `PGconn' undeclared (first use in this function) @@ -7239,24 +6841,24 @@ foo.c:54: `CONNECTION_BAD' undeclared (first use in this function) foo.c:68: `PGRES_COMMAND_OK' undeclared (first use in this function) foo.c:95: `PGRES_TUPLES_OK' undeclared (first use in this function) - + - 通过为你的编译器提供-Idirectory选项,向你的编译器指出PostgreSQL头文件安装在哪里(在某些情况下编译器默认将查看该目录,因此你可以忽略这个选项)。例如你的编译命令行可能看起来像: + 向编译器提供 -Idirectory 选项,指定 PostgreSQL 头文件的安装目录。(某些情况下,编译器默认会搜索该目录,此时可以省略这个选项。)例如,编译命令行可以是: cc -c -I/usr/local/pgsql/include testprog.c - 如果你在使用 makefile,那么把该选项加到CPPFLAGS变量中: +如果使用 makefile,请将该选项添加到 CPPFLAGS 变量中: CPPFLAGS += -I/usr/local/pgsql/include - + 如果你的程序可能由其他用户编译,那么你不应该像那样硬编码目录位置。你可以运行工具pg_configpg_configwith libpq在本地系统上找出头文件在哪里: + sortas="libpq">用于 libpq在本地系统上找出头文件在哪里: $ pg_config --includedir /usr/local/include @@ -7264,8 +6866,7 @@ CPPFLAGS += -I/usr/local/pgsql/include - 如果你安装了pkg-configpkg-configwith - libpq,你可以运行: + 如果你安装了pkg-configpkg-config用于 libpq,你可以运行: $ pkg-config --cflags libpq -I/usr/local/include @@ -7274,20 +6875,20 @@ CPPFLAGS += -I/usr/local/pgsql/include - 无法为编译器指定正确的选项将导致一个错误消息,例如: + 未向编译器指定正确的选项将导致类似以下内容的错误消息: testlibpq.c:8:22: libpq-fe.h: No such file or directory - +
- 当链接最终的程序时,指定选项-lpq,这样libpq库会被编译进去,也可以用选项-Ldirectory向编译器指出libpq库所在的位置(再次,编译器将默认搜索某些目录)。为了最大的可移植性,将选项放在选项前面。例如: + 链接最终程序时,指定 -lpq 选项以链接 libpq 库,同时指定 -Ldirectory 选项,告知编译器 libpq 库所在的目录。(同样,编译器默认会搜索某些目录。)为获得最大的可移植性,请将 选项放在 选项之前。例如: cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq - +
你也可以使用pg_config找出库目录: @@ -7314,7 +6915,7 @@ testlibpq.o(.text+0x60): undefined reference to `PQsetdbLogin' testlibpq.o(.text+0x71): undefined reference to `PQstatus' testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage'
- 这意味着你忘了 . + 这意味着你忘记了 /usr/bin/ld: cannot find -lpq @@ -7331,7 +6932,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' 示例程序 - 这些示例和其他示例可以在源代码发布的src/test/examples目录中找到。 + 这些示例和其他示例可在源代码发行包的src/test/examples目录中找到。 @@ -7346,7 +6947,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' * * testlibpq.c * - * Test the C version of libpq, the PostgreSQL frontend library. + * 测试 PostgreSQL 前端库 libpq 的 C 语言版本。 */ #include #include @@ -7370,26 +6971,25 @@ main(int argc, char **argv) j; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -7400,19 +7000,17 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Our test case here involves using a cursor, for which we must be inside - * a transaction block. We could do the whole thing with a single - * PQexec() of "select * from pg_database", but that's too trivial to make - * a good example. + * 这里的测试用例使用游标,因此必须处于事务块内。 + * 只需调用一次 PQexec() 执行 "select * from pg_database" 就能完成全部操作, + * 但这太简单了,不足以作为一个好的示例。 */ - /* Start a transaction block */ + /* 开始一个事务块 */ res = PQexec(conn, "BEGIN"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -7423,7 +7021,7 @@ main(int argc, char **argv) PQclear(res); /* - * Fetch rows from pg_database, the system catalog of databases + * 从数据库系统目录 pg_database 中获取行 */ res = PQexec(conn, "DECLARE myportal CURSOR FOR select * from pg_database"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -7442,13 +7040,13 @@ main(int argc, char **argv) exit_nicely(conn); } - /* first, print out the attribute names */ + /* 首先,打印属性名 */ nFields = PQnfields(res); for (i = 0; i < nFields; i++) printf("%-15s", PQfname(res, i)); printf("\n\n"); - /* next, print out the rows */ + /* 接着,打印各行 */ for (i = 0; i < PQntuples(res); i++) { for (j = 0; j < nFields; j++) @@ -7458,15 +7056,15 @@ main(int argc, char **argv) PQclear(res); - /* close the portal ... we don't bother to check for errors ... */ + /* 关闭 portal……这里不再检查错误…… */ res = PQexec(conn, "CLOSE myportal"); PQclear(res); - /* end the transaction */ + /* 结束事务 */ res = PQexec(conn, "END"); PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -7486,15 +7084,15 @@ main(int argc, char **argv) * * * testlibpq2.c - * Test of the asynchronous notification interface + * 测试异步通知接口 * - * Start this program, then from psql in another window do + * 启动此程序,然后在另一个窗口中通过 psql 执行 * NOTIFY TBL2; - * Repeat four times to get this program to exit. + * 重复四次后,此程序便会退出。 * - * Or, if you want to get fancy, try this: - * populate a database with the following commands - * (provided in src/test/examples/testlibpq2.sql): + * 或者,可以尝试更复杂的示例: + * 使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq2.sql 中): * * CREATE SCHEMA TESTLIBPQ2; * SET search_path = TESTLIBPQ2; @@ -7503,7 +7101,7 @@ main(int argc, char **argv) * CREATE RULE r1 AS ON INSERT TO TBL1 DO * (INSERT INTO TBL2 VALUES (new.i); NOTIFY TBL2); * - * Start this program, then from psql do this four times: + * 启动此程序,然后通过 psql 将以下命令执行四次: * * INSERT INTO TESTLIBPQ2.TBL1 VALUES (10); */ @@ -7515,11 +7113,9 @@ main(int argc, char **argv) #include #include #include +#include #include #include -#ifdef HAVE_SYS_SELECT_H -#include -#endif #include "libpq-fe.h" @@ -7540,26 +7136,25 @@ main(int argc, char **argv) int nnotifies; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -7570,13 +7165,12 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Issue LISTEN command to enable notifications from the rule's NOTIFY. + * 发出 LISTEN 命令,以接收规则中的 NOTIFY 发出的通知。 */ res = PQexec(conn, "LISTEN TBL2"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -7587,14 +7181,13 @@ main(int argc, char **argv) } PQclear(res); - /* Quit after four notifies are received. */ + /* 收到四次通知后退出。 */ nnotifies = 0; while (nnotifies < 4) { /* - * Sleep until something happens on the connection. We use select(2) - * to wait for input, but you could also use poll() or similar - * facilities. + * 休眠,直到连接上有事件发生。这里使用 select(2) 等待输入, + * 也可以使用 poll() 或类似机制。 */ int sock; fd_set input_mask; @@ -7602,7 +7195,7 @@ main(int argc, char **argv) sock = PQsocket(conn); if (sock < 0) - break; /* shouldn't happen */ + break; /* 不应发生 */ FD_ZERO(&input_mask); FD_SET(sock, &input_mask); @@ -7613,7 +7206,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Now check for input */ + /* 现在检查是否有输入 */ PQconsumeInput(conn); while ((notify = PQnotifies(conn)) != NULL) { @@ -7628,7 +7221,7 @@ main(int argc, char **argv) fprintf(stderr, "Done.\n"); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -7648,10 +7241,10 @@ main(int argc, char **argv) * * * testlibpq3.c - * Test out-of-line parameters and binary I/O. + * 测试在 SQL 命令文本之外独立传递的参数和二进制 I/O。 * - * Before running this, populate a database with the following commands - * (provided in src/test/examples/testlibpq3.sql): + * 运行前,使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq3.sql 中): * * CREATE SCHEMA testlibpq3; * SET search_path = testlibpq3; @@ -7660,7 +7253,7 @@ main(int argc, char **argv) * INSERT INTO test1 values (1, 'joe''s place', '\000\001\002\003\004'); * INSERT INTO test1 values (2, 'ho there', '\004\003\002\001\000'); * - * The expected output is: + * 预期输出为: * * tuple 0: got * i = (4 bytes) 1 @@ -7684,7 +7277,7 @@ main(int argc, char **argv) #include #include "libpq-fe.h" -/* for ntohl/htonl */ +/* 用于 ntohl/htonl */ #include #include @@ -7696,9 +7289,8 @@ exit_nicely(PGconn *conn) } /* - * This function prints a query result that is a binary-format fetch from - * a table defined as in the comment above. We split it out because the - * main() function uses it twice. + * 此函数打印从上面注释所定义的表中以二进制格式获取的查询结果。 + * 由于 main() 会使用它两次,因此将它单独提取成一个函数。 */ static void show_binary_results(PGresult *res) @@ -7709,7 +7301,7 @@ show_binary_results(PGresult *res) t_fnum, b_fnum; - /* Use PQfnumber to avoid assumptions about field order in result */ + /* 使用 PQfnumber,以避免对结果中的字段顺序作出假设 */ i_fnum = PQfnumber(res, "i"); t_fnum = PQfnumber(res, "t"); b_fnum = PQfnumber(res, "b"); @@ -7722,24 +7314,22 @@ show_binary_results(PGresult *res) int blen; int ival; - /* Get the field values (we ignore possibility they are null!) */ + /* 获取字段值(这里忽略它们可能为 null 的情况!) */ iptr = PQgetvalue(res, i, i_fnum); tptr = PQgetvalue(res, i, t_fnum); bptr = PQgetvalue(res, i, b_fnum); /* - * The binary representation of INT4 is in network byte order, which - * we'd better coerce to the local byte order. + * INT4 的二进制表示采用网络字节序,最好将其转换为本机字节序。 */ ival = ntohl(*((uint32_t *) iptr)); /* - * The binary representation of TEXT is, well, text, and since libpq - * was nice enough to append a zero byte to it, it'll work just fine - * as a C string. + * TEXT 的二进制表示就是文本,而 libpq 会在其后追加一个零字节, + * 因此可以直接将其用作 C 字符串。 * - * The binary representation of BYTEA is a bunch of bytes, which could - * include embedded nulls so we have to pay attention to field length. + * BYTEA 的二进制表示是一组字节,其中可能嵌有零字节, + * 因此必须注意字段长度。 */ blen = PQgetlength(res, i, b_fnum); @@ -7767,26 +7357,25 @@ main(int argc, char **argv) uint32_t binaryIntVal; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SET search_path = testlibpq3"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -7797,27 +7386,25 @@ main(int argc, char **argv) PQclear(res); /* - * The point of this program is to illustrate use of PQexecParams() with - * out-of-line parameters, as well as binary transmission of data. + * 此程序旨在演示如何使用 PQexecParams() 在 SQL 命令文本之外独立传递参数, + * 以及如何以二进制方式传输数据。 * - * This first example transmits the parameters as text, but receives the - * results in binary format. By using out-of-line parameters we can avoid - * a lot of tedious mucking about with quoting and escaping, even though - * the data is text. Notice how we don't have to do anything special with - * the quote mark in the parameter value. + * 第一个示例以文本形式传输参数,但以二进制格式接收结果。 + * 通过在 SQL 命令文本之外独立传递参数,即使数据是文本,也可以避免 + * 许多繁琐的引号和转义处理。注意,参数值中的引号无需任何特殊处理。 */ - /* Here is our out-of-line parameter value */ + /* 这是在 SQL 命令文本之外独立传递的参数值 */ paramValues[0] = "joe's place"; res = PQexecParams(conn, "SELECT * FROM test1 WHERE t = $1", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, - NULL, /* don't need param lengths since text */ - NULL, /* default to all text params */ - 1); /* ask for binary results */ + NULL, /* 文本参数无需指定长度 */ + NULL, /* 默认所有参数均为文本 */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -7831,31 +7418,29 @@ main(int argc, char **argv) PQclear(res); /* - * In this second example we transmit an integer parameter in binary form, - * and again retrieve the results in binary form. + * 第二个示例以二进制形式传输一个整数参数,并同样以二进制形式获取结果。 * - * Although we tell PQexecParams we are letting the backend deduce - * parameter type, we really force the decision by casting the parameter - * symbol in the query text. This is a good safety measure when sending - * binary parameters. + * 虽然我们告诉 PQexecParams 让后端推断参数类型,但实际上, + * 查询文本中的参数符号经过强制类型转换,因此其类型已经确定。 + * 发送二进制参数时,这是一项良好的安全措施。 */ - /* Convert integer value "2" to network byte order */ + /* 将整数值 "2" 转换为网络字节序 */ binaryIntVal = htonl((uint32_t) 2); - /* Set up parameter arrays for PQexecParams */ + /* 为 PQexecParams 设置参数数组 */ paramValues[0] = (char *) &binaryIntVal; paramLengths[0] = sizeof(binaryIntVal); - paramFormats[0] = 1; /* binary */ + paramFormats[0] = 1; /* 二进制 */ res = PQexecParams(conn, "SELECT * FROM test1 WHERE i = $1::int4", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, paramLengths, paramFormats, - 1); /* ask for binary results */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -7868,7 +7453,7 @@ main(int argc, char **argv) PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; diff --git a/zh/16/lobj.sgml b/zh/16/lobj.sgml index ee9815e3..98c11de9 100644 --- a/zh/16/lobj.sgml +++ b/zh/16/lobj.sgml @@ -3,8 +3,8 @@ 大对象 - large object - BLOBlarge object + 大对象 + BLOB大对象 PostgreSQL提供一种大对象机制,允许以流式方式访问存储在专用大对象结构中的用户数据。在处理大到无法方便地整体操作的数据值时,这种流式访问非常有用。 @@ -19,7 +19,7 @@ TOAST - versus large objects + 与大对象对比 @@ -190,11 +190,11 @@ inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE); int lo_write(PGconn *conn, int fd, const char *buf, size_t len); - 将buf中的len字节(其大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 + 将buf中的len字节(缓冲区大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -211,7 +211,7 @@ int lo_read(PGconn *conn, int fd, char *buf, size_t len); - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -231,7 +231,7 @@ int lo_lseek(PGconn *conn, int fd, int offset, int whence); lo_lseek64 当处理大小可能超过 2 GB 的大对象时,改用 -int64_t lo_lseek64(PGconn *conn, int fd, int64_t offset, int whence); +pg_int64 lo_lseek64(PGconn *conn, int fd, pg_int64 offset, int whence); 该函数的行为与lo_lseek相同,但它既可以接受大于 2 GB 的offset,也可以返回大于 2 GB 的结果。请注意,如果新位置指针会大于 2 GB,lo_lseek将失败。
@@ -258,7 +258,7 @@ int lo_tell(PGconn *conn, int fd); lo_tell64 当处理大小可能超过 2 GB 的大对象时,改用 -int64_t lo_tell64(PGconn *conn, int fd); +pg_int64 lo_tell64(PGconn *conn, int fd); 该函数的行为与lo_tell相同,但它可以返回大于 2 GB 的结果。请注意,如果当前读/写位置大于 2 GB,lo_tell将失败。
@@ -277,7 +277,7 @@ int64_t lo_tell64(PGconn *conn, int fd); int lo_truncate(PGconn *conn, int fd, size_t len); - 该函数把大对象描述符fd截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用空字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 + 该函数把大对象描述符fd对应的大对象截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用零字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 @@ -292,7 +292,7 @@ int lo_truncate(PGconn *conn, int fd, size_t len); lo_truncate64 当处理大小可能超过 2 GB 的大对象时,改用 -int lo_truncate64(PGconn *conn, int fd, int64_t len); +int lo_truncate64(PGconn *conn, int fd, pg_int64 len); 该函数的行为与lo_truncate相同,但它可以接受大于 2 GB 的len值。 @@ -426,16 +426,16 @@ CREATE TABLE image ( raster oid ); -SELECT lo_creat(-1); -- returns OID of new, empty large object +SELECT lo_creat(-1); -- 返回新建的空大对象的 OID -SELECT lo_create(43213); -- attempts to create large object with OID 43213 +SELECT lo_create(43213); -- 尝试创建 OID 为 43213 的大对象 -SELECT lo_unlink(173454); -- deletes large object with OID 173454 +SELECT lo_unlink(173454); -- 删除 OID 为 173454 的大对象 INSERT INTO image (name, raster) VALUES ('beautiful image', lo_import('/etc/motd')); -INSERT INTO image (name, raster) -- same as above, but specify OID to use +INSERT INTO image (name, raster) -- 与上例相同,但指定要使用的 OID VALUES ('beautiful image', lo_import('/etc/motd', 68583)); SELECT lo_export(image.raster, '/tmp/motd') FROM image @@ -444,7 +444,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image - 服务器端的lo_importlo_export函数与其客户端对应函数的行为差异很大。这两个函数在服务器的文件系统中读写文件,使用数据库所有者的权限。因此,默认情况下它们的使用仅限于超级用户。相比之下,客户端导入和导出函数在客户端的文件系统中读写文件,使用客户端程序的权限。客户端函数不需要任何数据库权限,除了读取或写入相关大对象所需的权限。 + 服务器端的lo_importlo_export函数与其客户端对应函数的行为差异很大。这两个函数在服务器的文件系统中读写文件,使用运行数据库服务器的操作系统用户的权限。因此,默认情况下它们的使用仅限于超级用户。相比之下,客户端导入和导出函数在客户端的文件系统中读写文件,使用客户端程序的权限。客户端函数不需要任何数据库权限,除了读取或写入相关大对象所需的权限。 @@ -463,7 +463,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image 示例程序 - 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行版的src/test/examples/testlo.c中找到。 + 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行包的src/test/examples/testlo.c中找到。 @@ -472,13 +472,13 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /*----------------------------------------------------------------- * * testlo.c - * test using large objects with libpq + * 测试使用 libpq 操作大对象 * - * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group + * Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group * Portions Copyright (c) 1994, Regents of the University of California * * - * IDENTIFICATION + * 标识 * src/test/examples/testlo.c * *----------------------------------------------------------------- @@ -498,7 +498,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /* * importFile - - * import file "in_filename" into database as large object "lobjOid" + * 将文件 "in_filename" 作为大对象 "lobjOid" 导入数据库 * */ static Oid @@ -512,16 +512,16 @@ importFile(PGconn *conn, char *filename) int fd; /* - * open the file to be read in + * 打开要读取的文件 */ fd = open(filename, O_RDONLY, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"\n", filename); } /* - * create the large object + * 创建大对象 */ lobjId = lo_creat(conn, INV_READ | INV_WRITE); if (lobjId == 0) @@ -530,7 +530,7 @@ importFile(PGconn *conn, char *filename) lobj_fd = lo_open(conn, lobjId, INV_WRITE); /* - * read in from the Unix file and write to the inversion file + * 从 Unix 文件读取数据并写入大对象 */ while ((nbytes = read(fd, buf, BUFSIZE)) > 0) { @@ -568,7 +568,7 @@ pickout(PGconn *conn, Oid lobjId, int start, int len) fprintf(stderr, ">>> %s", buf); nread += nbytes; if (nbytes <= 0) - break; /* no more data? */ + break; /* 没有更多数据? */ } free(buf); fprintf(stderr, "\n"); @@ -614,7 +614,7 @@ overwrite(PGconn *conn, Oid lobjId, int start, int len) /* * exportFile - - * export large object "lobjOid" to file "out_filename" + * 将大对象 "lobjOid" 导出到文件 "out_filename" * */ static void @@ -627,24 +627,24 @@ exportFile(PGconn *conn, Oid lobjId, char *filename) int fd; /* - * open the large object + * 打开大对象 */ lobj_fd = lo_open(conn, lobjId, INV_READ); if (lobj_fd < 0) fprintf(stderr, "cannot open large object %u", lobjId); /* - * open the file to be written to + * 打开要写入的文件 */ fd = open(filename, O_CREAT | O_WRONLY | O_TRUNC, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"", filename); } /* - * read in from the inversion file and write to the Unix file + * 从大对象读取数据并写入 Unix 文件 */ while ((nbytes = lo_read(conn, lobj_fd, buf, BUFSIZE)) > 0) { @@ -689,18 +689,18 @@ main(int argc, char **argv) out_filename = argv[3]; /* - * set up the connection + * 建立连接 */ conn = PQsetdb(NULL, NULL, NULL, NULL, database); - /* check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) diff --git a/zh/16/monitoring.sgml b/zh/16/monitoring.sgml index 77b98004..ab023cc0 100644 --- a/zh/16/monitoring.sgml +++ b/zh/16/monitoring.sgml @@ -4121,7 +4121,8 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i checksum_failures bigint - 在此数据库(或共享对象)中检测到的数据页校验码失败数,如果没有启用数据校验码则为NULL。 + 在此数据库(或共享对象)中检测到的数据页校验和失败次数,如果未启用 + 数据校验和则为 NULL。 @@ -4130,7 +4131,8 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i checksum_last_failure timestamp with time zone - 在此数据库(或共享对象)中检测到最后一个数据页校验码失败的时间,如果没有启用数据校验码则为NULL。 + 在此数据库(或共享对象)中最后一次检测到数据页校验和失败的时间, + 如果未启用数据校验和则为 NULL。 diff --git a/zh/16/pgtrgm.sgml b/zh/16/pgtrgm.sgml index 09cc6fe5..fa60934c 100644 --- a/zh/16/pgtrgm.sgml +++ b/zh/16/pgtrgm.sgml @@ -513,11 +513,11 @@ SELECT * FROM test_trgm WHERE t ~ '(foo|bar)'; - 文本搜索集成 + 文本检索集成 与全文索引结合使用时,三字符组匹配是非常有用的工具。 - 尤其是,它有助于识别那些因拼写错误而无法被全文搜索机制直接匹配的输入词。 + 尤其是,它有助于识别那些因拼写错误而无法被全文检索机制直接匹配的输入词。 diff --git a/zh/16/protocol.sgml b/zh/16/protocol.sgml index 2b6c491a..8cb03a9a 100644 --- a/zh/16/protocol.sgml +++ b/zh/16/protocol.sgml @@ -26,15 +26,15 @@ 概述 - 协议在启动和正常操作过程中有不同的阶段。在启动阶段里,前端打开一个到服务器的连接并且认证自身以满足服务器(这可能涉及到一条或多条消息,取决于使用的认证方法)。 如果一切正常,服务器就发送状态信息给前端,并最后进入正常操作。除了最初的启动请求消息之外,协议的这个部分是服务器驱动的。 + 协议分为启动和正常操作两个阶段。在启动阶段,前端打开到服务器的连接,并完成服务器所要求的认证。(这可能只涉及一条消息,也可能因所用认证方法不同而需要多条消息。)如果一切顺利,服务器随后会向前端发送状态信息,并最终进入正常操作。除最初的启动请求消息外,协议的这一部分由服务器驱动。 - 在正常操作中,前端发送查询和其它命令到后端,然后后端返回查询结果和其它响应。在少数几种情况(比如NOTIFY)中,后端会发送未被请求的消息,但这个会话中的绝大多部分都是由前端请求驱动的。 + 在正常操作中,前端向后端发送查询及其他命令,后端则返回查询结果和其他响应。少数情况下(例如 NOTIFY),后端会发送未请求的消息,但会话中的绝大多数交互仍由前端请求驱动。 - 会话的终止通常是由前端来选择的,但是也可以在某些情况下由后端强制执行。不管在那种情况下,如果后端关闭连接,那么它将在退出之前回滚所有打开的(未完成的)事务。 + 会话通常由前端选择终止,但在某些情况下也可能由后端强制终止。无论哪种情况,后端关闭连接时,都会在退出前回滚所有打开的(未完成的)事务。 @@ -73,9 +73,7 @@ 整个执行周期包括一个解析步骤,它从文本查询字符串创建预备语句; 一个绑定步骤,它根据预备语句和所需参数值创建 portal; - 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询 - (SELECTSHOW等),可以要求执行步骤只取回 - 有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 + 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询(SELECTSHOW等),可以要求执行步骤只取回有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 @@ -92,8 +90,8 @@ - 文本形式的数值是特定数据类型的输入/输出转换函数生成或接受的任何字符串。在传输形式上,字符串没有末尾空字符;如果前端要想把收到的值当作C字符串处理,那么必须自己加上一个(顺便说一下,文本格式不允许嵌入空字符)。 - + 值的文本表示是相应数据类型的输入/输出转换函数生成和接受的字符串。在传输形式中,值的末尾没有空字符;前端若要将收到的值作为 C 字符串处理,必须自行添加一个。(文本格式也不允许内嵌空字符。) + 整数的二进制表示采用网络字节序(最高有效字节在前)。至于其他数据类型,请查阅文档或源代码了解其二进制表示形式。要注意,复杂数据类型的二进制表示可能会在不同服务器版本之间发生变化;文本格式通常是可移植性更好的选择。 @@ -114,7 +112,7 @@ 启动 - 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,判断该连接在初步上是否可接受,以及是否需要额外的认证。 + 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,初步判断是否接受该连接,以及需要何种额外认证(如果需要)。 @@ -233,11 +231,8 @@ NegotiateProtocolVersion - 如果服务器不支持客户端请求的协议次版本,但支持更早的协议版本,就会发送该消息并指明其支持的最高次版本。如果客户端在启动包中请求了不受支持的协议选项(即以 _pq_. 开头),也会发送该消息。 - - - 在该消息之后,认证会继续使用服务器指明的协议版本。如果客户端不支持该较旧版本,就应立即关闭连接。如果服务器没有发送该消息,则表示它支持客户端请求的协议版本以及所有协议选项。 - + 服务器不支持客户端请求的协议次版本,但支持更早的协议版本;此消息指明其所支持的最高次版本。如果客户端在启动包中请求了不受支持的协议选项(即以 _pq_. 开头的选项),也会发送此消息。此消息后面会跟随一条 ErrorResponse 或一条指示认证成功或失败的消息。 + @@ -266,9 +261,7 @@ 该消息提供密钥数据。如果前端希望稍后发送取消请求,就必须保存这些数据。前端不应响应该消息,而应继续等待 ReadyForQuery 消息。 - - PostgreSQL 服务器总会发送该消息,但已知一些不支持查询取消的第三方后端实现不会发送。 - + @@ -359,7 +352,7 @@ 表示即将返回行作为对SELECTFETCH等查询的响应。 - 此消息的内容描述了行的列布局。这将跟随每个返回给前端的行的DataRow消息。 + 此消息的内容描述了行的列布局。该消息之后,每个返回给前端的行都对应一条 DataRow 消息。 @@ -415,9 +408,7 @@ - - 对 SELECT 查询(或其他返回行集的查询,如 EXPLAINSHOW)的响应,通常包含 RowDescription、零条或多条 DataRow 消息,以及最后的 CommandComplete。向前端 COPY 或从前端 COPY 会调用中描述的特殊协议。所有其他类型的查询通常只产生一条 CommandComplete 消息。 - + SELECT 查询(或其他返回行集的查询,如 EXPLAINSHOW)的响应通常包含 RowDescription、零条或多条 DataRow 消息,以及最后的 CommandComplete。在前端与服务器之间执行 COPY 输入或输出时,会使用 所述的特殊协议。所有其他类型的查询通常只产生一条 CommandComplete 消息。 由于查询字符串可能包含若干条查询(以分号分隔),因此在后端完成整个查询字符串的处理之前,可能会出现多个这样的响应序列。只有在整个字符串处理完毕且后端已准备好接受新的查询字符串时,才会发出 ReadyForQuery 消息。 @@ -440,15 +431,15 @@ - 我们建议的方法是把前端代码写成状态机的风格,它可以在任何时刻接受任何有意义的消息类型,而不是假设消息的序列总是准确。 - + 建议以状态机的方式编写前端,使其能够在任何合理的时机接收相应类型的消息,而不把消息确切顺序的假设写死在代码中。 + 一个简单查询中的多条语句 - 当一个简单查询消息中包含多于一条SQL语句(被分号分隔)时,那些语句会被当做一个事务中执行,除非其中包括显式事务控制命令来强制不同的行为。例如,如果消息包括 + 当一个简单查询消息中包含多于一条SQL语句(被分号分隔)时,这些语句会作为单个事务执行,除非其中包括显式事务控制命令来强制不同的行为。例如,如果消息包括 INSERT INTO mytable VALUES(1); SELECT 1/0; @@ -470,15 +461,15 @@ SELECT 1/0; - 这种行为通过在一个隐式事务块中的一个多语句Query消息中运行那些语句来实现,除非它们运行在某个显式事务块中。隐式事务块与常规事务块之间的区别在于隐式块会在Query消息结束时自动被关闭,或者是在没有错误的情况下由一个隐式提交关闭,或者是在有错误时由一个隐式的回滚关闭。这类似于一个语句自己执行(当不在事务块中时)时发生的隐式提交或回滚。 - + 这种行为的实现方式是:除非已有显式事务块可供这些语句执行,否则就在一个隐式事务块中执行多语句 Query 消息中的语句。隐式事务块与常规事务块的主要区别在于,隐式块会在 Query 消息结束时自动关闭:没有错误时隐式提交,发生错误时隐式回滚。这类似于单独执行一条语句(不在事务块中)时发生的隐式提交或回滚。 + - 如果会话已经在一个事务块中,作为前面某个消息中BEGIN的结果,那么Query消息会简单地继续那个事务块,不管该消息包含一个语句还是多个语句。不过,如果该Query消息包含一个关闭现有事务块的COMMIT或者ROLLBACK,那么任何接下来的语句都会在一个隐式事务块中被执行。反过来,如果在多语句Query消息中出现一个BEGIN,那么它会开始一个常规事务块,这个常规事务块将只能被一个显式的COMMIT或者ROLLBACK终止,不管这两种命令是出现在这个Query消息还是后面的一个Query消息中。如果BEGIN跟在一些作为隐式事务块执行的语句后面,那些语句不会被立刻提交。实际上,它们会被包括到新的常规事务块中。 + 如果会话因前面某条消息中的BEGIN而已经处于事务块中,那么 Query 消息会继续该事务块,不管该消息包含一个语句还是多个语句。不过,如果该Query消息包含一个关闭现有事务块的COMMIT或者ROLLBACK,那么任何接下来的语句都会在一个隐式事务块中被执行。反过来,如果在多语句Query消息中出现一个BEGIN,那么它会开始一个常规事务块,这个常规事务块将只能被一个显式的COMMIT或者ROLLBACK终止,不管这两种命令是出现在这个Query消息还是后面的一个Query消息中。如果BEGIN跟在一些作为隐式事务块执行的语句后面,那些语句不会被立刻提交。实际上,它们会被包括到新的常规事务块中。 - 出现在一个隐式事务块中的COMMIT或者ROLLBACK会被正常执行并且关闭该隐式块。不过,由于没有先前的BEGIN配对的COMMIT或者ROLLBACK表示一种错误,所以将会发出一个警告。如果后面还有更多语句,将会为它们开始一个新的隐式事务块。 + 出现在一个隐式事务块中的COMMIT或者ROLLBACK会被正常执行并且关闭该隐式块。不过,由于没有先前的BEGIN配对的COMMIT或者ROLLBACK可能表示误操作,所以会发出警告。如果后面还有更多语句,将会为它们开始一个新的隐式事务块。 @@ -486,17 +477,17 @@ SELECT 1/0; - 记住,不管任何事务控制命令存不存在,Query消息的执行会在第一个错误时停止。因此,对于下面的在一个Query消息中的示例 + 请记住,无论消息中是否包含事务控制命令,Query 消息的执行都会在第一个错误处停止。例如,单条 Query 消息包含以下内容时: BEGIN; SELECT 1/0; ROLLBACK; - 会话中将留下一个失败的常规事务块,因为在出现除零错误后不会到达ROLLBACK。将需要另一个ROLLBACK把会话恢复到一种可用的状态。 - +会话会停留在失败的常规事务块内,因为发生除零错误后不会再执行ROLLBACK。需要另发一条ROLLBACK,才能将会话恢复到可用状态。 + - 另一种要注意的行为是,最初的词法和语法分析是在整个查询字符串被执行之前进行的。因此后面的语句中的简单错误(例如拼写错误的关键词)可能会阻止任何语句的执行。这通常对用户是不可见的,因为在当作一个隐式事务块执行时,这些语句不管怎样都会全部被回滚。不过,在尝试于一个多语句Query中执行多个事务时,这种现象可能是可见的。例如,如果一个拼写错误把我们之前的示例变成 + 另一种要注意的行为是,在执行任何语句之前,会先对整个查询字符串进行词法和语法分析。因此后面的语句中的简单错误(例如拼写错误的关键词)可能会阻止任何语句的执行。这通常对用户是不可见的,因为在当作一个隐式事务块执行时,这些语句不管怎样都会全部被回滚。不过,在尝试于一个多语句Query中执行多个事务时,这种现象可能是可见的。例如,如果一个拼写错误把我们之前的示例变成 BEGIN; INSERT INTO mytable VALUES(1); @@ -563,11 +554,11 @@ SELCT 1/0; - 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是执行不会导致后端发送 ReadyForQuery 或 RowDescription。 + 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是 Execute 不会导致后端发送 ReadyForQuery 或 RowDescription。 - 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息之一结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 + 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息中的恰好一条结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 @@ -582,7 +573,7 @@ SELCT 1/0; - 除了这些基本的、必须的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 + 除了这些基本的、必需的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 @@ -618,38 +609,32 @@ SELCT 1/0; - 流水线处理 + 管道化 - 流水线处理 + 管道化 协议规范 - 使用扩展查询协议允许流水线处理,这意味着发送一系列查询而无需等待先前的查询完成。 - 这减少了完成一系列操作所需的网络往返次数。然而,用户必须仔细考虑所需的行为,如果其中一步失败, - 因为后续查询已经在传输到服务器的过程中。 - + 扩展查询协议允许管道化,即连续发送一系列查询,而不等待先前查询完成。这减少了完成一组操作所需的网络往返次数。不过,用户必须仔细考虑其中某个步骤失败时所需的行为,因为后续查询已经在发往服务器的途中。 + - 处理这个问题的一种方法是将整个查询系列作为一个事务处理,即将其包装在BEGIN... - COMMIT中。然而,如果希望其中一些命令独立于其他命令提交,这并没有帮助。 - + 处理这个问题的一种方式是让整组查询成为单个事务,即用BEGIN ... COMMIT包围它们。不过,如果希望其中某些命令独立于其他命令提交,这种方式就无法满足要求。 + - 扩展查询协议提供了另一种管理这个问题的方式,即在依赖的步骤之间省略发送同步消息。 - 由于在错误后,后端会跳过命令消息直到找到同步消息,这允许在管道中的后续命令在前面的命令失败时自动跳过,而无需客户端明确地使用BEGINCOMMIT来管理。 - 管道中可以通过同步消息分隔独立可提交的段。 - + 扩展查询协议提供了另一种处理方式,即省略相互依赖的步骤之间的 Sync 消息。发生错误后,后端会跳过命令消息,直到遇到 Sync,因此当前面的命令失败时,管道中的后续命令便会自动跳过,而不必由客户端用BEGINCOMMIT显式管理。管道中可独立提交的各段可以用 Sync 消息分隔。 + - 如果客户端没有发出显式 BEGIN,则会启动一个隐式事务块。每个 Sync 通常会在前序步骤成功时导致隐式 COMMIT,失败时导致隐式 ROLLBACK。服务器只有在第一个命令结束且尚未收到 Sync 时,才能识别这种隐式事务块。有一些 DDL 命令(例如 CREATE DATABASE)不能在事务块内执行;若这类命令在管道中执行,除非它是某个 Sync 之后的第一条命令,否则会失败。此外,它成功后会强制立即提交以保持数据库一致性。因此,紧随这些命令之后的 Sync 除了返回 ReadyForQuery 外不会产生额外效果。 - + 如果客户端没有发出显式的BEGIN,那么每个 Sync 通常会在前序步骤成功时引发隐式的COMMIT,失败时引发隐式的ROLLBACK。不过,少数 DDL 命令(例如CREATE DATABASE)不能在事务块中执行。如果这类命令在管道中执行,除非它是管道中的第一条命令,否则会失败。此外,它成功后会强制立即提交,以保持数据库一致性。因此,紧随这类命令之后的 Sync 除了返回 ReadyForQuery 外,不产生其他效果。 + - 当使用这种方法时,必须通过计算ReadyForQuery消息的数量并等待达到发送的Syncs数量来确定管道的完成。 - 计算命令完成响应是不可靠的,因为其中一些命令可能会被跳过,因此不会产生完成消息。 - + 使用这种方式时,必须统计 ReadyForQuery 消息的数量,并等待该数量达到已发送的 Sync 消息数量,才能确定管道已完成。统计命令完成响应并不可靠,因为某些命令可能被跳过,因而不会产生完成消息。 + @@ -657,8 +642,8 @@ SELCT 1/0; 函数调用 - 函数调用子协议允许客户端请求一个对存在于数据库pg_proc系统表中的任意函数的直接调用。客户端必须在该函数上有执行的权限。 - + 函数调用子协议允许客户端请求直接调用数据库pg_proc系统目录中的任意函数。客户端必须具有该函数的执行权限。 + @@ -668,8 +653,8 @@ SELCT 1/0; - 一个函数调用周期是由前端向后端发送一条FunctionCall消息初始化的。然后后端根据函数调用的结果发送一条或者更多响应消息,并且最后是一条ReadyForQuery响应消息。ReadyForQuery通知前端它可以安全地发送一个新的查询或者函数调用了。 - + 函数调用周期由前端向后端发送一条 FunctionCall 消息来启动。后端随后根据函数调用的结果发送一条或多条响应消息,最后发送一条 ReadyForQuery 响应消息。ReadyForQuery 告知前端,可以安全地发送新的查询或函数调用。 + 来自后端的可能的响应消息是: @@ -688,7 +673,7 @@ SELCT 1/0; FunctionCallResponse - 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者集合类型的结果)。 + 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者结果集合)。 @@ -723,7 +708,7 @@ SELCT 1/0; - 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(表示成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 + 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(允许成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 @@ -731,11 +716,11 @@ SELCT 1/0; - 在拷贝入模式下,后端将忽略所收到的Flush和Sync消息。收到任何其他非拷贝消息类型都会造成一个错误,它将导致上面所描述的拷贝入状态中断(Flush和Sync的例外是为了方便客户端库,它们总是在一个Execute消息之后发送Flush和Sync,而不检查被执行的命令是否为一个COPY FROM STDIN)。 - + 后端会忽略在拷贝入模式期间收到的 Flush 和 Sync 消息。收到任何其他非拷贝类型的消息都会构成错误,并按上述方式中止拷贝入状态。(Flush 和 Sync 的例外是为了方便那些总是在 Execute 消息之后发送 Flush 或 Sync、而不检查待执行命令是否为COPY FROM STDIN的客户端库。) + - 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句的时候初始化的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能退出传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 + 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句时启动的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能中止传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 @@ -743,16 +728,16 @@ SELCT 1/0; - 在CopyData消息中间可能会散布有NoticeResponse和ParameterStatus消息。前端必须处理这些情况,并且应该也为异步消息类型(参见)准备好。否则任何除CopyData或CopyDone之外的消息类型都会被认为是要中止拷贝出模式。 - + NoticeResponse 和 ParameterStatus 消息可能穿插在 CopyData 消息之间;前端必须处理这些情况,并应准备好处理其他异步消息类型(参见)。除此之外,可以将任何除 CopyData 或 CopyDone 以外的消息类型视为拷贝出模式的终止标志。 + - 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许数据以高速批量方式在客户端与服务器之间双向传输。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见。 + 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许高速批量地向服务器发送数据以及从服务器接收数据。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见 - CopyInResponse、CopyOutResponse和CopyBothResponse消息包括域和格式代码,域告诉前端每行的列数,而格式代码则用于具体每个列(就目前的实现而言,一个给定COPY操作中的所有列都将使用同样的格式,但是消息设计并不做这个假设)。 - + CopyInResponse、CopyOutResponse 和 CopyBothResponse 消息包含一些字段,用于告知前端每行的列数以及每列所使用的格式代码。(在当前实现中,同一次COPY操作的所有列都使用相同格式,但消息设计并不作此假设。) + @@ -795,8 +780,8 @@ SELCT 1/0; - 如果前端发出一个LISTEN命令, 那么无论何时在为同一个通道名NOTIFY时,后端将发送一个NotificationResponse消息(不要和NoticeResponse搞混!)。 - + 如果前端发出LISTEN命令,那么每当针对同一通道名执行NOTIFY命令时,后端都会发送一条 NotificationResponse 消息(不要与 NoticeResponse 混淆)。 + @@ -815,11 +800,11 @@ SELCT 1/0; - 要发出一条取消请求,前端打开一个与服务器的新连接并且发送一条CancelRequest消息, 而不是通常在新连接中经常发送的StartupMessage消息。服务器将处理这个请求然后关闭连接。 出于安全原因,对取消请求消息不做直接的响应。 - + 要发出取消请求,前端会新建到服务器的连接,并发送 CancelRequest 消息,而不是新连接通常发送的 StartupMessage 消息。服务器处理该请求后便会关闭连接。出于安全原因,服务器不会直接回复取消请求消息。 + - 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的关键数据(PID和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则退出当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 + 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的密钥数据(PID 和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则中止当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 @@ -827,7 +812,7 @@ SELCT 1/0; - 这么做是对安全性和有效性通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 + 这么做是对安全性和效率通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 @@ -848,11 +833,11 @@ SELCT 1/0; - 其他终止场景来自各种故障,例如任一端发生内核转储、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 + 其他终止场景来自各种故障,例如任一端发生 core dump、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 - 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果很可能在得知断开之前被提交。 + 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果可能在发现连接断开之前被提交。 @@ -866,32 +851,28 @@ SELCT 1/0; 要发起一条使用SSL加密的连接,前端首先发送 SSLRequest 消息,而不是 StartupMessage。随后服务器会响应一个包含SN的单字节,分别表示它愿意或不愿意执行SSL加密。如果前端对该响应不满意,此时可以关闭连接。若要在收到S后继续,就先与服务器完成SSL启动握手(这里不做描述,它属于SSL规范的一部分)。如果成功,再继续发送通常的 StartupMessage。在这种情况下,StartupMessage 以及后续所有数据都会被SSL加密。若要在收到N后继续,则发送通常的 StartupMessage,并在不使用加密的情况下继续。 - (另外,可以在 N 响应之后发出 GSSENCRequest 消息,尝试使用 GSSAPI 加密代替 SSL。) + (另外,可以在 N 响应之后发出 GSSENCRequest 消息,尝试使用 GSSAPI 加密代替 SSL。) - 前端也应准备处理服务器对 SSLRequest 返回的 ErrorMessage。前端不应将该错误直接展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 SSL 的情况下继续。 + 前端也应准备处理服务器对 SSLRequest 返回的 ErrorMessage。前端不应将该错误展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 SSL 的情况下继续。 - 当可以执行 SSL 加密时,服务器预计仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给他们的 SSL 库,要么在发现他们已经读取到额外的字节时将其视为协议违规。 + 当可以执行 SSL 加密时,服务器应仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给所用的 SSL 库,要么在发现已经读取到额外的字节时将其视为协议违规。 - - 同样,服务器也期望客户端在收到服务器对 SSLRequest 的单字节响应之后,再开始SSL协商。如果客户端不等服务器响应到达就立即开始SSL协商,可以减少一次网络往返时延;但代价是无法处理服务器对SSL请求返回否定响应的情况。在这种情况下,服务器通常会直接断开连接,而不会继续回退到 GSSAPI、未加密连接或协议错误流程。 - - - 初始 SSLRequest 也可以用于那些正在建立、目的是发送 CancelRequest 消息的连接。 - - 还支持第二种发起SSL加密的方式:客户端可以在不发送任何 SSLRequest 包的情况下,直接开始SSL协商。SSL连接建立后,服务器会在加密通道上继续等待普通的启动请求包并继续协商。在这种情况下,任何其他的加密请求都会被拒绝。这种方法不适合通用工具,因为它既不能协商出最佳的连接加密方式,也不能处理未加密连接;但在客户端和服务器都由同一方控制的环境中,它很有用,因为它可以减少一次往返时延,并允许使用依赖标准SSL连接的网络工具。使用这种风格的SSL连接时,客户端必须使用由 RFC 7301 定义的 ALPN 扩展,以防范协议混淆攻击。PostgreSQL 协议对应的 ALPN 标识是 postgresql,见 IANA TLS ALPN Protocol IDs 注册表。 - + 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 SSLRequest。 + + + - 虽然协议本身并不提供让服务器强制启用SSL加密的方法,但管理员可以把服务器配置为拒绝未加密会话,把它作为认证检查的一个副作用。 - + 虽然协议本身没有提供让服务器强制使用SSL加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + @@ -902,37 +883,27 @@ SELCT 1/0; 如果PostgreSQL构建时启用了GSSAPI支持,就可以使用GSSAPI对前端/后端通信进行加密。这为攻击者可能截获会话流量的环境提供了通信安全性。有关使用GSSAPI加密PostgreSQL会话的详细信息,请参阅。 - - 要启动一个GSSAPI加密连接,前端最初发送一个GSSENCRequest消息,而不是一个StartupMessage。 - 服务器随后会响应一个包含GN的单个字节,分别表示愿意或不愿意执行GSSAPI加密。 - 如果前端对响应不满意,可能会在此时关闭连接。 - 要在G之后继续,使用GSSAPI C绑定,如在RFC 2744 - 中讨论的,或等效的,通过在循环中调用gss_init_sec_context()来执行GSSAPI初始化, - 并将结果发送给服务器,从一个空输入开始,然后对每个来自服务器的结果进行处理,直到不再返回输出为止。 - 在将gss_init_sec_context()的结果发送给服务器时,在消息前加上以网络字节顺序表示的四字节整数的长度。 - 要在N之后继续,发送通常的StartupMessage,并在没有加密的情况下继续进行。 - (或者,可以在N响应后发出一个SSLRequest消息,尝试使用SSL加密代替GSSAPI。) - + 要建立 GSSAPI 加密连接,前端首先发送 GSSENCRequest 消息,而不是 StartupMessage。服务器随后以单个字节响应,内容为 GN,分别表示愿意或不愿意使用 GSSAPI 加密。如果前端对响应不满意,可以在此时关闭连接。收到 G 后要继续,应使用 RFC 2744 中介绍的 GSSAPI C 绑定或等效接口,在循环中调用 gss_init_sec_context() 来执行 GSSAPI 初始化,并将结果发送给服务器:先使用空输入,再依次使用服务器返回的每个结果,直到该调用不再产生输出。将 gss_init_sec_context() 的结果发送给服务器时,应在前面加上消息长度,以网络字节序的四字节整数表示。收到 N 后要继续,则发送通常的 StartupMessage,以不加密的方式继续。(也允许在收到 N 响应后发送 SSLRequest 消息,尝试使用 SSL 加密代替 GSSAPI。) - 前端也应准备处理服务器对 GSSENCRequest 返回的 ErrorMessage。前端不应将该错误直接展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 GSSAPI 加密的情况下继续。 + 前端也应准备处理服务器对 GSSENCRequest 返回的 ErrorMessage。前端不应将该错误展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 GSSAPI 加密的情况下继续。 - 当GSSAPI加密可用时,服务器预计只发送单个G字节,然后等待前端启动GSSAPI握手。此时如果还有其他可读字节,很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应编写代码,要么从套接字中恰好读取一个字节后再把套接字交给其 GSSAPI 库,要么在发现自己已经读到额外字节时将其视为协议违规。 + 当GSSAPI加密可用时,服务器应只发送单个G字节,然后等待前端启动GSSAPI握手。此时如果还有其他可读字节,很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应编写代码,要么从套接字中恰好读取一个字节后再把套接字交给其 GSSAPI 库,要么在发现自己已经读到额外字节时将其视为协议违规。 - 初始 GSSENCRequest 也可用于那些正在建立、目的是发送 CancelRequest 消息的连接。 - + 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 GSSENCRequest。 + 一旦成功建立GSSAPI加密连接,就应使用gss_wrap()加密通常的 StartupMessage 以及后续所有数据,并在实际加密负载前附上gss_wrap()结果长度,该长度以网络字节序的四字节整数表示。请注意,服务器只接受来自客户端、长度小于 16kB 的加密数据包。客户端应使用gss_wrap_size_limit()确定符合该限制的未加密消息大小,较大的消息则应拆分为多次gss_wrap()调用。典型分段是 8kB 的未加密数据,对应得到略大于 8kB 但明显小于 16kB 的加密数据包。通常可以认为,服务器不会向客户端发送大于 16kB 的加密数据包。 - 虽然协议本身并不为服务器提供强制启用GSSAPI加密的方法,但管理员可以把服务器配置为拒绝未加密会话,把它作为认证检查的一个副作用。 - + 虽然协议本身没有提供让服务器强制使用GSSAPI加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + @@ -940,9 +911,7 @@ SELCT 1/0; SASL认证 - - SASL是面向连接协议中的认证框架。目前,PostgreSQL实现了两种 SASL 认证机制:SCRAM-SHA-256 和 SCRAM-SHA-256-PLUS。将来可能增加更多机制。下面的步骤说明 SASL 认证的一般流程,下一小节则详细介绍 SCRAM-SHA-256 和 SCRAM-SHA-256-PLUS。 - + SASL 是面向连接协议中的认证框架。目前,PostgreSQL 实现了两种 SASL 认证机制:SCRAM-SHA-256 和 SCRAM-SHA-256-PLUS。将来可能增加更多机制。以下步骤说明 SASL 认证的一般流程,下一小节则详细介绍 SCRAM-SHA-256 和 SCRAM-SHA-256-PLUS。 @@ -958,25 +927,22 @@ SELCT 1/0; - 客户端从列表中选择一个支持的机制,并向服务器发送一个SASLInitialResponse消息。 - 该消息包括所选机制的名称,以及如果所选机制使用的话,还包括一个可选的初始客户端响应。 - + 客户端从列表中选择一种受支持的机制,并向服务器发送 SASLInitialResponse 消息。消息包含所选机制的名称;如果该机制使用初始客户端响应,消息还可以包含这一可选响应。 + - 一个或多个服务器挑战和客户端响应消息将随后而来。每个服务器挑战都是在一个 - AuthenticationSASLContinue 消息中发送的,随后是客户端在一个 SASLResponse - 消息中的响应。这些消息的具体内容是特定于机制的。 - + 随后会进行一轮或多轮服务器挑战和客户端响应。每次服务器挑战都通过 AuthenticationSASLContinue 消息发送,随后客户端通过 SASLResponse 消息响应。消息的具体内容取决于所用机制。 + - 最后,当认证交换成功完成时,服务器会发送可选的 AuthenticationSASLFinal 消息,随后立即发送 AuthenticationOk。AuthenticationSASLFinal 包含机制特定的附加数据;若该机制不需要完成时附加数据,则不会发送 AuthenticationSASLFinal。 - + 最后,认证交换成功完成时,服务器会发送 AuthenticationSASLFinal 消息,紧接着发送 AuthenticationOk 消息。AuthenticationSASLFinal 包含从服务器发给客户端的附加数据,其具体内容取决于所选认证机制。如果该认证机制不使用在完成时发送的附加数据,则不会发送 AuthenticationSASLFinal 消息。 + @@ -988,12 +954,7 @@ SELCT 1/0; SCRAM-SHA-256认证 - - SCRAM-SHA-256 及其带通道绑定的变体 - SCRAM-SHA-256-PLUS 是基于密码的认证机制。它们在 - RFC 7677 - 和RFC 5802中有详细描述。 - + 目前实现的 SASL 机制是 SCRAM-SHA-256 及其带通道绑定的变体 SCRAM-SHA-256-PLUSRFC 7677RFC 5802 对它们有详细描述。 当在PostgreSQL中使用SCRAM-SHA-256时,服务器将忽略客户端在client-first-message中发送的用户名。 @@ -1002,31 +963,22 @@ SELCT 1/0; - SCRAM规范规定密码也必须是UTF-8编码,并且使用SASLprep算法处理。 - 然而,PostgreSQL不要求密码必须使用UTF-8编码。 - 当用户设置密码时,无论实际使用的编码是什么,都会像使用UTF-8一样使用SASLprep进行处理。 - 但是,如果密码不是合法的UTF-8字节序列,或者包含SASLprep算法禁止的UTF-8字节序列, - 则会使用原始密码而不进行SASLprep处理,而不是抛出错误。这样可以在密码为UTF-8时对其进行规范化, - 但仍允许使用非UTF-8密码,并且不需要系统知道密码使用的编码方式。 - + SCRAM 规范规定密码也必须采用 UTF-8 编码,并通过SASLprep算法处理。不过,PostgreSQL并不要求密码使用 UTF-8。设置用户密码时,无论实际采用何种编码,都会将其视作 UTF-8 并用 SASLprep 处理。但是,如果密码不是合法的 UTF-8 字节序列,或者包含 SASLprep 算法禁止的 UTF-8 字节序列,就会直接使用未经 SASLprep 处理的原始密码,而不抛出错误。这样既能对 UTF-8 密码进行规范化,又允许使用非 UTF-8 密码,而且不要求系统知道密码采用何种编码。 + - Channel binding在支持SSL的PostgreSQL构建中受支持。带有通道绑定的SCRAM的SASL机制名称是 + 通道绑定在支持SSL的PostgreSQL构建中受支持。带有通道绑定的SCRAM的SASL机制名称是 SCRAM-SHA-256-PLUS。PostgreSQL使用的通道绑定类型是 tls-server-end-point - 在没有通道绑定的SCRAM中,服务器选择一个随机数, - 传输给客户端,与用户提供的密码在传输的密码哈希中混合。虽然这可以 - 防止密码哈希在后续会话中被成功重新传输,但无法阻止真实服务器和客 - 户端之间的虚假服务器通过服务器的随机值并成功进行认证。 - + 在不带通道绑定的SCRAM中,服务器会选择一个随机数并发送给客户端,将它与用户提供的密码混合,形成所传输的密码 hash。虽然这样可以防止在后续会话中成功重放该密码 hash,但无法阻止位于真实服务器与客户端之间的伪造服务器转发服务器的随机值并成功通过认证。 + - SCRAM与通道绑定一起防止这种中间人攻击,通过将服务器证书的签名混合到传输的密码哈希中。 - 虽然伪造服务器可以重新传输真实服务器的证书,但它无法访问与该证书匹配的私钥,因此无法证明自己是所有者,导致SSL连接失败。 - + 带通道绑定的SCRAM会将服务器证书的签名混入所传输的密码 hash,从而防止此类中间人攻击。虽然伪造服务器可以转发真实服务器的证书,但它无法取得与证书匹配的私钥,因此无法证明自己是证书所有者,最终导致 SSL 连接失败。 + @@ -1098,16 +1050,15 @@ SELCT 1/0; - 为了测试复制命令,可以通过psql或任何其他使用连接字符串且包含replication选项的libpq工具建立复制连接, - 例如: + 为了测试复制命令,可以通过 psql 或其他使用 libpq 的工具建立复制连接,连接字符串中应包含 replication 选项,例如: psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 然而,更常用的是使用(用于物理复制)或(用于逻辑复制)。 - +不过,通常更有用的做法是使用 (用于物理复制)或 (用于逻辑复制)。 + - 复制命令在服务器日志中记录,当启用时。 + 启用 后,复制命令会记录到服务器日志中。 @@ -1117,7 +1068,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" IDENTIFY_SYSTEM - 识别系统 + IDENTIFY_SYSTEM @@ -1153,9 +1104,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" xlogpos (text) - - 当前 WAL 刷新位置。用于获得预写式日志中的一个已知位置,以便从该处开始流式传输。 - + 当前 WAL 刷盘位置。可用于获取预写式日志中一个已知的位置,以便从该处开始流式传输。 @@ -1207,10 +1156,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 请求服务器发送时间线历史文件以获取时间线tli。 - 服务器回复一行结果集,包含两个字段。虽然这些字段被标记为text, - 但它们实际上返回原始字节,没有编码转换: - + 请求服务器发送时间线 tli 的历史文件。服务器返回一个包含两个字段的单行结果集。虽然这些字段标记为 text,但实际返回的是原始字节,不进行编码转换: + @@ -1290,12 +1237,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果为 true,则该逻辑复制槽支持两阶段提交的解码。使用此选项后,与两阶段提交相关的命令,如 - PREPARE TRANSACTIONCOMMIT PREPARED - 和ROLLBACK PREPARED将被解码和传输。 - 事务将在PREPARE TRANSACTION时解码和传输。 - 默认值为false。 - + 如果为 true,则该逻辑复制槽支持对两阶段提交进行解码。使用此选项后,PREPARE TRANSACTIONCOMMIT PREPAREDROLLBACK PREPARED 等两阶段提交命令会被解码并传输。事务会在 PREPARE TRANSACTION 时解码并传输。默认值为 false。 + @@ -1306,10 +1249,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果为 true,则该物理复制槽会立即保留WAL。 - 否则,WAL仅在从流复制客户端连接时保留。 - 默认值为false。 - + 如果为 true,则该物理复制槽会立即保留 WAL。否则,只有在流复制客户端连接时才会保留 WAL。默认值为 false。 + @@ -1380,60 +1321,19 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - - ALTER_REPLICATION_SLOT slot_name ( option [, ...] ) - ALTER_REPLICATION_SLOT - - - - 修改复制槽定义。参见 。当前仅支持逻辑复制槽。 - - - - slot_name - - - 要修改的复制槽名称,必须是合法复制槽名(见 )。 - - - - - 支持以下选项: - - - TWO_PHASE [ boolean ] - - - 若为 true,则该逻辑复制槽支持两阶段提交解码。与两阶段提交相关的命令(如 PREPARE TRANSACTIONCOMMIT PREPAREDROLLBACK PREPARED)会被解码并发送;事务在 PREPARE TRANSACTION 时解码并发送。 - - - - - - - FAILOVER [ boolean ] - - - 若为 true,则该复制槽会同步到备库,从而在故障切换后恢复逻辑复制。 - - - - - - + READ_REPLICATION_SLOT slot_name - 读取复制槽 + READ_REPLICATION_SLOT - 读取与复制槽相关的一些信息。如果复制槽不存在,则返回一个包含NULL值的元组。 - 当前仅支持物理复制槽的此命令。 - + 读取与复制槽关联的一些信息。如果复制槽不存在,则返回包含 NULL 值的元组。此命令目前仅支持物理复制槽。 + 在响应此命令时,服务器将返回一个包含以下字段的单行结果集: @@ -1460,8 +1360,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" restart_tliint8 - 与restart_lsn相关联的时间线ID,遵循当前时间线历史。 - + 根据当前时间线的历史,与 restart_lsn 对应的时间线 ID。 + @@ -1473,35 +1373,29 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" START_REPLICATION [ SLOT slot_name ] [ PHYSICAL ] XXX/XXX [ TIMELINE tli ] - 开始复制 + START_REPLICATION - 指示服务器开始流式传输WAL,从WAL位置XXX/XXX开始。 - 如果指定了TIMELINE选项,则流式传输将从时间线tli开始; - 否则,将选择服务器当前的时间线。如果请求的WAL部分已经被回收,服务器可能会回复错误。 - 成功时,服务器将用CopyBothResponse消息回复,然后开始向前端流式传输WAL。 - + 指示服务器从 WAL 位置 XXX/XXX 开始流式传输 WAL。如果指定了 TIMELINE 选项,则从时间线 tli 开始传输;否则选择服务器当前的时间线。服务器可以返回错误,例如请求的 WAL 部分已被回收时。成功时,服务器返回 CopyBothResponse 消息,然后开始向前端流式传输 WAL。 + - 如果通过slot_name提供了复制槽名称, - 那么在复制进行期间会更新该复制槽,以便服务器知道哪些 WAL 段, - 以及在启用了 hot_standby_feedback 时,哪些事务 - 仍然被备库所需要。 - + 如果通过 slot_name 提供了复制槽名称,该复制槽会随着复制的进行而更新,使服务器知道备库仍需要哪些 WAL 段,以及在启用 hot_standby_feedback 时仍需要哪些事务。 + - 如果客户端请求的 timeline 不是最新的,但属于服务器历史的一部分,服务器会从请求的起点开始流式传输该 timeline 上的全部 WAL,直到服务器切换到另一个 timeline 的位置为止。如果客户端请求的位置正好是旧 timeline 的末尾,服务器将完全跳过 COPY 模式。 - + 如果客户端请求的时间线不是最新时间线,但属于服务器的历史,服务器会从请求的起点开始,流式传输该时间线上的所有 WAL,直到服务器切换到另一条时间线的位置。如果客户端请求的流式传输起点恰好位于旧时间线的末尾,服务器会完全跳过 COPY 模式。 + 在非最新时间线上流式传输完全部 WAL 后,服务器会通过退出 COPY 模式来结束流式传输。当客户端也通过退出 COPY 模式来确认时,服务器会发送一个包含一行两列的结果集,指示该服务器历史中的下一条时间线。第一列是下一条时间线的 ID(类型为 int8),第二列是发生切换的 WAL 位置(类型为 text)。通常,切换位置就是所流式传输 WAL 的末尾,但也存在一些边界情况,服务器可能会先发送一些自己在提升前尚未重放的旧时间线 WAL。最后,服务器会发送两个 CommandComplete 消息(一个结束 CopyData,另一个结束 START_REPLICATION 本身),然后准备接受新的命令。 - WAL 数据会作为一系列 CopyData 消息发送;详见 。(这使其他信息可与之交错发送;特别是服务器在开始流式传输后若遇到失败,仍可发送 ErrorResponse。)从服务器到客户端的每个 CopyData 消息负载都属于以下格式之一: - + WAL 数据通过一系列 CopyData 消息发送,详见 。(这样可以混合发送其他信息;尤其是服务器在开始流式传输后遇到故障时,可以发送 ErrorResponse 消息。)服务器发给客户端的每条 CopyData 消息,其有效载荷都包含一条具有下列格式之一的消息: + @@ -1514,9 +1408,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('w') - - 将消息标识为WAL数据。 - + 将该消息标识为 WAL 数据。 @@ -1525,9 +1417,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 该消息中 WAL 数据的起始点。 - + 本消息中 WAL 数据的起始位置。 @@ -1536,9 +1426,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 服务器上当前的WAL结束位置。 - + 服务器上当前的 WAL 末尾位置。 @@ -1547,9 +1435,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 传输时服务器的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时服务器的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1558,15 +1444,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byten - - WAL数据流的一个部分。 - + WAL 数据流的一个片段。 - - 单个 WAL 记录绝不会拆分为两个 XLogData 消息。 - 当 WAL 记录跨越 WAL 页面边界,并因此已使用连续记录进行拆分时,它可以在页面边界处进行拆分。 - 换句话说,第一个主 WAL 记录及其连续记录可以在不同的 XLogData 消息中发送。 - + 单条 WAL 记录绝不会被拆分到两条 XLogData 消息中。当 WAL 记录跨越 WAL 页边界,因而已经通过续接记录拆分时,可以在页边界处分开发送。换句话说,最初的主 WAL 记录及其续接记录可以在不同的 XLogData 消息中发送。 @@ -1575,7 +1455,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 主库 keepalive 消息 (B) + 主库保活消息 (B) @@ -1583,9 +1463,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('k') - - 将该消息标识为发送方 keepalive。 - + 将该消息标识为发送端保活消息。 @@ -1594,9 +1472,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 服务器上当前的WAL结束位置。 - + 服务器上当前的 WAL 末尾位置。 @@ -1605,9 +1481,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 传输时服务器的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时服务器的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1616,9 +1490,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1 - - 1 表示客户端应尽快回复此消息,以避免超时断开连接。否则为0。 - + 1 表示客户端应尽快回复此消息,以避免超时断开连接;否则为 0。 @@ -1626,9 +1498,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - - 接收进程可以随时使用以下某种消息格式向发送方回传响应(同样放在 CopyData 消息的负载中): - + 接收进程可以随时使用以下消息格式之一回复发送端(同样放在 CopyData 消息的有效载荷中): @@ -1641,9 +1511,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('r') - - 将该消息标识为接收方状态更新。 - + 将该消息标识为接收端状态更新。 @@ -1652,9 +1520,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已接收并写入磁盘的 WAL 字节位置 + 1。 - + 备库已接收并写入磁盘的最后一个 WAL 字节的位置加 1。 @@ -1663,9 +1529,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已刷写到磁盘的 WAL 字节位置 + 1。 - + 备库已刷盘的最后一个 WAL 字节的位置加 1。 @@ -1674,9 +1538,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已应用的 WAL 字节位置 + 1。 - + 备库已应用的最后一个 WAL 字节的位置加 1。 @@ -1685,9 +1547,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 客户端在传输时的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时客户端的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1696,9 +1556,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1 - - 如果为 1,则客户端请求服务器立即回复此消息。这可用于 ping 服务器,以测试连接是否仍然健康。 - + 如果为 1,表示客户端请求服务器立即回复此消息。可用它向服务器发送探测请求,以测试连接是否仍然正常。 @@ -1726,9 +1584,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 客户端在传输时的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时客户端的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1748,9 +1604,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 - - 备库上全局 xmin xid 的纪元。 - + 备库全局 xmin 事务 ID 的纪元。 @@ -1759,9 +1613,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 - - 备库上任何复制槽中的最低 catalog_xmin。如果备库上不存在 catalog_xmin,或已禁用热备反馈,则设为 0。 - + 备库上所有复制槽中最小的 catalog_xmin。如果备库上不存在 catalog_xmin,或者正在禁用热备反馈,则设为 0。 @@ -1770,9 +1622,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 - - 备库上 catalog_xmin xid 的纪元。 - + 备库 catalog_xmin 事务 ID 的纪元。 @@ -1858,7 +1708,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" DROP_REPLICATION_SLOT slot_name WAIT - 删除复制槽 + DROP_REPLICATION_SLOT @@ -1908,9 +1758,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" LABEL 'label' - 设置备份的标签。如果未指定,则将使用base backup作为备份标签。 - 标签的引号使用规则与打开的标准SQL字符串相同。 - + 设置备份标签。如果未指定,则使用 base backup 作为备份标签。标签的引号规则与启用 时的标准 SQL 字符串相同。 + @@ -2008,16 +1857,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - level关键字设置压缩级别。 - 对于gzip,压缩级别应该是一个介于19之间的整数 - (默认为Z_DEFAULT_COMPRESSION-1), - 对于lz4,压缩级别应该是介于1和12之间的整数 - (默认为0用于快速压缩模式), - 对于zstd,压缩级别应该是介于ZSTD_minCLevel() - (通常为-131072)和ZSTD_maxCLevel() - (通常为22)之间, - (默认为ZSTD_CLEVEL_DEFAULT3)。 - + level 关键字设置压缩级别。对于 gzip,压缩级别应为 19 之间的整数(默认为 Z_DEFAULT_COMPRESSION,即 -1);对于 lz4,应为 1 到 12 之间的整数(默认为 0,表示快速压缩模式);对于 zstd,应为 ZSTD_minCLevel()(通常为 -131072)到 ZSTD_maxCLevel()(通常为 22)之间的整数(默认为 ZSTD_CLEVEL_DEFAULT,即 3)。 + long 关键字用于启用长距离匹配模式,可提高压缩比,但会增加内存使用。长距离模式仅支持 zstd。 @@ -2128,17 +1969,16 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" size (int8) - 表空间的大致大小,以千字节(1024字节)为单位,如果已请求进度报告;否则为null。 - + 如果请求了进度报告,则为表空间的大致大小,以千字节(1024 字节)为单位;否则为 null。 + - 在第二个常规结果集之后,将发送一个CopyOutResponse。 - 每个CopyData消息的有效负载将包含以下格式之一的消息: - + 第二个普通结果集之后,会发送一条 CopyOutResponse。每条 CopyData 消息的有效载荷都包含一条具有下列格式之一的消息: + @@ -2316,7 +2156,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 逻辑复制协议 + 逻辑流复制协议 本节介绍逻辑复制协议,它是一种以复制命令START_REPLICATION @@ -2325,7 +2165,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 逻辑复制协议构建在物理流复制协议的底层机制之上。 + 逻辑流复制协议构建在物理流复制协议的基本机制之上。 @@ -2338,7 +2178,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 逻辑流复制参数 - 使用 START_REPLICATION 命令时,pgoutput 接受以下选项: + 使用START_REPLICATION命令,pgoutput接受以下选项: @@ -2356,7 +2196,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 版本 3 仅在服务器版本 15 及以上受支持,允许流式传输两阶段提交。 - 版本 4 仅在服务器版本 16 及以上受支持,允许并行应用正在进行的大型事务的流。 + 版本 4 仅在服务器版本 16 及以上受支持,允许并行应用进行中的大型事务流。 @@ -2466,7 +2306,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每个被发送的事务都包含零条或多条 DML 消息(插入、更新、删除)。在级联场景下,它还会包含 Origin 消息。Origin 消息表示该事务产生于另一个复制节点。由于逻辑复制协议中的复制节点可以是任意实现,因此唯一标识符就是该源头的名称。下游是否以及如何处理这一信息,由其自行决定。Origin 消息总是在事务中的任何 DML 消息之前发送。 + 每个发送的事务都包含零条或多条 DML 消息(Insert、Update、Delete)。在级联配置中,还可能包含 Origin 消息。Origin 消息表示该事务源自另一个复制节点。由于逻辑复制协议中的复制节点几乎可以是任何实现,因此唯一的标识符就是复制源的名称。下游负责按需处理这一信息(如果需要处理)。Origin 消息总是在事务中的任何 DML 消息之前发送。 @@ -2531,9 +2371,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 对后端返回的字符串长度,没有预定义的限制。 - 前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。 - 如果做不到这一点,就应读取完整字符串,并丢弃不适合固定大小缓冲区的尾随字符。 + 后端返回的字符串长度没有预定义的限制。前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。如果做不到这一点,就应读取完整字符串,并丢弃固定大小的缓冲区容纳不下的尾随字符。 @@ -2559,8 +2397,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 消息格式 - 本节描述每条消息的详细格式。每条消息都标记了可由前端(F)、后端(B)或双方(F&B)发送。 - 请注意,虽然每条消息开头都带有字节计数,但大多数消息格式都定义为无需参考该计数也能确定消息边界。这一设计最初是出于历史原因(早期已废弃的协议 v2 没有显式长度字段),同时也有助于有效性校验。 + 本节描述每条消息的详细格式。每条消息都标明它可以由前端(F)、后端(B)或双方(F & B)发送。注意,虽然每条消息开头都有字节计数,但消息格式的定义使得无需参考该计数也能确定消息的结束位置。这有助于检查消息的有效性。(CopyData 消息是例外,因为它构成数据流的一部分,任何单条 CopyData 消息的内容都无法独立解释。) @@ -2575,7 +2412,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2597,7 +2434,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定认证成功。 + 表示认证成功。 @@ -2617,7 +2454,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2639,7 +2476,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 Kerberos V5 认证。 + 表示需要 Kerberos V5 认证。 @@ -2659,7 +2496,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2681,7 +2518,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要明文密码。 + 表示需要明文密码。 @@ -2700,7 +2537,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2722,7 +2559,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要MD5加密的密码。 + 表示需要经过 MD5 加密的密码。 @@ -2733,7 +2570,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 用于加密密码时使用的盐。 + 加密密码时使用的盐。 @@ -2752,7 +2589,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2773,7 +2610,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 GSSAPI 认证。 + 表示需要 GSSAPI 认证。 @@ -2792,7 +2629,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2814,7 +2651,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定此消息包含GSSAPI或SSPI数据。 + 表示此消息包含 GSSAPI 或 SSPI 数据。 @@ -2844,7 +2681,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2866,7 +2703,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 SSPI 认证。 + 表示需要 SSPI 认证。 @@ -2885,7 +2722,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2907,14 +2744,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 SASL 认证。 + 表示需要 SASL 认证。 - 消息正文是服务器首选的 SASL 认证机制列表。在最后一个认证机制名称后需要一个零字节作为终止符。对于每个机制,有以下内容: + 消息体是按服务器偏好顺序排列的 SASL 认证机制列表。在最后一个认证机制名称之后,必须有一个零字节作为终止符。每个机制包含以下内容: @@ -2941,7 +2778,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2963,7 +2800,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定此消息包含一个SASL挑战。 + 表示此消息包含 SASL 挑战。 @@ -2974,7 +2811,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - SASL数据,特定于正在使用的SASL机制。 + SASL 数据,具体内容取决于所使用的 SASL 机制。 @@ -2993,7 +2830,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -3015,7 +2852,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定SASL认证已完成。 + 表示 SASL 认证已完成。 @@ -3026,7 +2863,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - SASL结果"附加数据",特定于正在使用的SASL机制。 + SASL 结果的“附加数据”,具体内容取决于所使用的 SASL 机制。 @@ -3045,8 +2882,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为取消键数据。 - 如果前端希望能够稍后发出CancelRequest消息,必须保存这些值。 + 将此消息标识为取消请求密钥数据。如果前端希望以后能够发送 CancelRequest 消息,就必须保存这些值。 @@ -3068,7 +2904,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 这个后端的进程ID。 + 此后端的进程 ID。 @@ -3079,7 +2915,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 该后端的 secret key。 + 此后端的密钥。 @@ -3098,7 +2934,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为绑定命令。 + 将该消息标识为 Bind 命令。 @@ -3142,10 +2978,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后面跟着的参数格式代码的数量(以下标记为C)。 - 这可以是零,表示没有参数或者所有参数都使用默认格式(文本); - 或者是一个,这种情况下指定的格式代码应用于所有参数; - 或者等于实际参数的数量。 + 后续参数格式代码的数量(下文以 C 表示)。可以为零,表示没有参数,或者所有参数都使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有参数;还可以等于实际参数数量。 @@ -3156,7 +2989,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数格式代码。每个目前必须是零(文本)或一(二进制)。 + 参数格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -3167,15 +3000,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后面跟着的参数值的数量(可能为零)。 - 这个数量必须与查询所需的参数数量匹配。 + 后续参数值的数量(可以为零)。必须与查询所需的参数数量一致。 - 接下来,对于每个参数,都会出现以下一对字段: + 接下来,每个参数都有以下一对字段: @@ -3185,9 +3017,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数值的长度,以字节为单位(此计数不包括自身)。可以为零。 - 作为特殊情况,-1表示空参数值。 - 在空参数值的情况下,不会跟随任何值字节。 + 参数值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 参数值。为 NULL 时,后面不再有值的字节。 @@ -3198,15 +3028,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数的值,以相关格式代码指示的格式表示。 - n是上述长度。 + 参数值,格式由对应的格式代码指明。n 为上述长度。 - 在最后一个参数之后,出现以下字段: + 最后一个参数之后是以下字段: @@ -3216,10 +3045,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后跟的结果列格式代码数量(以下标记为R)。 - 这可以是零,表示没有结果列,或者所有结果列应该使用默认格式(文本); - 或者是一个,此时指定的格式代码将应用于所有结果列(如果有); - 或者等于查询的实际结果列数。 + 后续结果列格式代码的数量(下文以 R 表示)。可以为零,表示没有结果列,或者所有结果列都应使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有结果列(如果有);还可以等于查询实际的结果列数量。 @@ -3230,7 +3056,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 结果列格式代码。每个目前必须是零(文本)或一(二进制)。 + 结果列格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -3249,7 +3075,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为绑定完成指示器。 + 将该消息标识为 Bind 完成指示。 @@ -3277,7 +3103,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(16) - 消息内容的长度,以字节为单位,包括此长度字段本身。 + 消息内容的长度(以字节为单位),包括其自身。 @@ -3323,7 +3149,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为关闭命令。 + 将该消息标识为 Close 命令。 @@ -3345,8 +3171,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 'S' 表示关闭一个预备语句;或者 - 'P' 表示关闭一个 portal。 + “S”表示关闭预备语句;“P”表示关闭 portal。 @@ -3376,7 +3201,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为关闭完成指示符。 + 将该消息标识为 Close 完成指示。 @@ -3406,7 +3231,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为命令完成响应。 + 将该消息标识为命令完成响应。 @@ -3428,7 +3253,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 命令标签。这通常是一个单词,用于标识已完成的SQL命令。 + 命令标签。通常是一个单词,用来标识已完成的 SQL 命令。 @@ -3473,10 +3298,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 对于COPY命令,标签是 - COPY rows,其中 - rows是复制的行数。 - (注意:行数仅出现在PostgreSQL 8.2及更高版本中。) + 对于 COPY 命令,标签为 COPY rows,其中 rows 是复制的行数。(注意:行数仅出现在 PostgreSQL 8.2 及更高版本中。) @@ -3607,8 +3429,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为开始复制响应。 - 前端现在必须发送复制数据(如果没有准备好,发送CopyFail消息)。 + 将该消息标识为开始 COPY 输入的响应。前端此时必须发送 COPY 输入数据(如果尚未准备好,应发送 CopyFail 消息)。 @@ -3654,9 +3475,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -3675,8 +3494,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为开始复制输出响应。 - 该消息将被复制输出数据跟随。 + 将该消息标识为开始 COPY 输出的响应。此消息之后会发送 COPY 输出数据。 @@ -3698,8 +3516,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 0表示整体COPY格式为文本格式(行由换行符分隔,列由分隔符字符分隔等)。 - 1表示整体复制格式为二进制格式(类似于DataRow格式)。更多信息请参见。 + 0表示整体COPY格式是文本的(行由换行符分隔,列由分隔符分隔等)。 + 1表示整体复制格式是二进制的(类似于DataRow格式)。 + 更多信息请参见 @@ -3721,9 +3540,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -3742,7 +3559,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为开始复制双响应。此消息仅用于流复制。 + 将该消息标识为开始双向 COPY 的响应。此消息仅用于流复制。 @@ -3764,8 +3581,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 0表示整体COPY格式为文本格式(行由换行符分隔,列由分隔符字符分隔等)。 - 1表示整体复制格式为二进制格式(类似于DataRow格式)。更多信息请参见。 + 0表示整体COPY格式是文本的(行由换行符分隔,列由分隔符分隔等)。 + 1表示整体复制格式是二进制的(类似于DataRow格式)。 + 更多信息请参见 @@ -3787,9 +3605,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -3837,7 +3653,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于每一列,都会出现以下一对字段: + 接下来,每列都有以下两个字段: @@ -3847,8 +3663,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列值的长度,以字节为单位(此计数不包括其本身)。可以为零。 - 作为特殊情况,-1表示空列值。在空值情况下,不跟随任何值字节。 + 列值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 列值。为 NULL 时,后面不再有值的字节。 @@ -3879,7 +3694,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为描述命令。 + 将该消息标识为 Describe 命令。 @@ -3932,7 +3747,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为对空查询字符串的响应。(这相当于CommandComplete。) + 标识消息为对空查询字符串的响应。(此消息替代 CommandComplete。) @@ -3980,7 +3795,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 消息正文由一个或多个已识别的字段组成,后跟一个零字节作为终止符。字段可以以任何顺序出现。对于每个字段,都有以下内容: + 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -4003,7 +3818,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 字段数值。 + 字段值。 @@ -4022,7 +3837,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为一个执行命令。 + 将该消息标识为 Execute 命令。 @@ -4055,7 +3870,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果 portal 包含返回行的查询,则为要返回的最大行数(否则忽略)。零表示没有限制。 + 如果 portal 包含返回行的查询,则这是最多返回的行数(否则忽略此值)。零表示无限制 @@ -4074,7 +3889,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为Flush命令。 + 将该消息标识为 Flush 命令。 @@ -4126,7 +3941,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定要调用的函数的对象ID。 + 指定要调用的函数的对象 ID。 @@ -4137,10 +3952,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后面跟着的参数格式代码的数量(以下标记为C)。 - 这可以是零,表示没有参数或所有参数都使用默认格式(文本); - 或者是一个,这种情况下指定的格式代码应用于所有参数; - 或者等于实际参数的数量。 + 后续参数格式代码的数量(以下用 C 表示)。可以为零,表示没有参数,或所有参数都采用默认格式(文本);也可以为一,表示将指定的格式代码用于所有参数;还可以等于实际参数数量。 @@ -4169,7 +3981,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于每个参数,都会出现以下一对字段: + 接下来,每个参数都有以下两个字段: @@ -4179,9 +3991,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数值的长度,以字节为单位(此计数不包括自身)。可以为零。 - 作为特殊情况,-1表示空参数值。 - 在空参数值的情况下,不会跟随任何值字节。 + 参数值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 参数值。为 NULL 时,后面不再有值的字节。 @@ -4200,7 +4010,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 在最后一个参数之后,出现以下字段: + 最后一个参数之后还有以下字段: @@ -4210,7 +4020,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 函数结果的格式代码。目前必须是零(文本)或一(二进制)。 + 函数结果的格式代码。目前必须为零(文本)或一(二进制)。 @@ -4251,9 +4061,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 函数结果值的长度,以字节为单位(此计数不包括本身)。可以为零。 - 作为特殊情况,-1表示NULL函数结果。 - 在NULL情况下,不会跟随任何值字节。 + 函数结果值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 函数结果。为 NULL 时,后面不再有值的字节。 @@ -4379,7 +4187,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 服务器支持的最新次要协议版本,用于客户端请求的主要协议版本。 + 对于客户端请求的协议主版本,服务器所支持的最新协议次版本。 @@ -4390,14 +4198,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 服务器未识别的协议选项数量。 + 服务器无法识别的协议选项数量。 - 然后,对于服务器未识别的协议选项,有以下内容: + 接下来,对于服务器无法识别的每个协议选项,都有以下内容: @@ -4474,7 +4282,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 消息正文由一个或多个已识别的字段组成,后跟一个零字节作为终止符。字段可以以任何顺序出现。对于每个字段,都有以下内容: + 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -4497,7 +4305,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 字段数值。 + 字段值。 @@ -4538,7 +4346,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 通知后端进程的进程ID。 + 发出通知的后端进程的进程 ID。 @@ -4549,7 +4357,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 通知被触发的频道名称。 + 发出该通知的通道名称。 @@ -4560,7 +4368,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 从通知进程传递的有效负载字符串。 + 通知进程传来的有效载荷字符串。 @@ -4608,7 +4416,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 然后,对于每个参数,都有以下内容: + 接下来,每个参数都有以下内容: @@ -4618,7 +4426,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定参数数据类型的对象ID。 + 指定参数数据类型的对象 ID。 @@ -4659,7 +4467,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 正在报告的运行时参数的名称。 + 所报告的运行时参数的名称。 @@ -4689,7 +4497,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为解析命令。 + 将该消息标识为 Parse 命令。 @@ -4741,7 +4549,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 然后,对于每个参数,都有以下内容: + 接下来,每个参数都有以下内容: @@ -4751,7 +4559,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定参数数据类型的对象ID。在这里放置零相当于未指定类型。 + 指定参数数据类型的对象 ID。此处填零等同于不指定类型。 @@ -4770,7 +4578,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为解析完成指示器。 + 将该消息标识为 Parse 完成指示。 @@ -4842,8 +4650,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为 portal 挂起指示器。 - 请注意,仅当执行消息的行数限制达到时才会出现此消息。 + 将该消息标识为 portal 挂起指示。注意,仅当达到 Execute 消息指定的行数限制时,才会出现此消息。 @@ -4979,14 +4786,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定一行中的字段数(可以为零)。 + 指定一行中的字段数量(可以为零)。 - 然后,对于每个字段,都有以下内容: + 接下来,每个字段都有以下内容: @@ -5007,7 +4814,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果该字段可以被识别为特定表的列,则为该表的对象ID;否则为零。 + 如果能够确定该字段是某个特定表的列,则为该表的对象 ID;否则为零。 @@ -5018,7 +4825,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果该字段可以被识别为特定表的列,则为该列的属性编号;否则为零。 + 如果能够确定该字段是某个特定表的列,则为该列的属性编号;否则为零。 @@ -5029,7 +4836,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 字段数据类型的对象ID。 + 字段数据类型的对象 ID。 @@ -5064,7 +4871,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 正在使用的字段格式代码。目前将为零(文本)或一(二进制)。在从描述语句变体返回的RowDescription中,格式代码尚未知晓,将始终为零。 + 字段所使用的格式代码。目前为零(文本)或一(二进制)。对于 Describe 针对预备语句的变体所返回的 RowDescription,格式代码尚未确定,始终为零。 @@ -5117,7 +4924,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 长度为SASL机制特定的“初始客户端响应”,如果没有初始响应,则为-1。 + 后续 SASL 机制特有的“客户端初始响应”的长度;如果没有初始响应,则为 -1。 @@ -5232,17 +5039,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 协议版本号。最重要的16位是主版本号(此处描述的协议为3)。 - 最不重要的16位是次版本号(此处描述的协议为2)。 + 协议版本号。高 16 位为主版本号(此处描述的协议为 3);低 16 位为次版本号(此处描述的协议为 0)。 - 协议版本号后面跟着一个或多个参数名和值字符串对。在最后一个名/值对之后需要一个零字节作为终止符。 - 参数可以以任何顺序出现。user是必需的,其他是可选的。 - 每个参数的指定方式为: + 协议版本号之后是一个或多个参数名与参数值字符串对。最后一个名称/值对之后必须有一个零字节作为终止符。参数可以按任意顺序出现。其中,user是必需的,其余均为可选。每个参数按以下方式指定: @@ -5252,7 +5056,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数名称。当前识别的名称包括: + 参数名称。目前能够识别的名称如下: @@ -5292,7 +5096,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 除上述之外,还可以列出其他参数。以_pq_.开头的参数名称保留用于协议扩展,而其他参数被视为后端启动时设置的运行时参数。这些设置将在后端启动时应用(在解析命令行参数后,如果有的话),并将作为会话默认值。 + 除上述参数外,还可以列出其他参数。以_pq_.开头的参数名称保留用于协议扩展,其余参数则作为运行时参数,在后端启动时设置。这些设置会在后端启动期间应用(在解析命令行参数之后,如果有的话),并作为会话默认值。 @@ -5303,7 +5107,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数数值。 + 参数值。 @@ -5322,7 +5126,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为同步命令。 + 将该消息标识为 Sync 命令。 @@ -5375,7 +5179,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 错误和通知消息域 + 错误和通知消息字段 本节描述了ErrorResponse和NoticeResponse消息中可能出现的字段。每个字段类型都有一个单字节的标识符。 @@ -5388,11 +5192,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 严重性: 字段内容为ERROR, FATAL, 或 - PANIC (在错误消息中), 或 - WARNING, NOTICE, DEBUG, - INFO, 或 LOG (在通知消息中), - 或者这些内容的本地化翻译。始终存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中),或这些内容的本地化翻译。始终存在。 @@ -5402,11 +5202,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 严重性:字段内容为ERRORFATAL或 - PANIC(在错误消息中),或WARNINGNOTICEDEBUG、 - INFOLOG(在通知消息中)。 - 这与S字段相同,只是内容不会被本地化。仅在由PostgreSQL版本9.6 - 及更高版本生成的消息中存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中)。它与 S 字段相同,只是内容从不本地化。仅在 PostgreSQL 9.6 及更高版本生成的消息中存在。 @@ -5416,7 +5212,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Code: 错误的SQLSTATE代码(参见)。不可本地化。始终存在。 + 代码:错误的 SQLSTATE 代码(见 )。不可本地化。始终存在。 @@ -5426,9 +5222,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 消息: 主要的人类可读错误消息。 - 这应该准确但简洁(通常一行)。 - 总是存在。 + 消息:主要的可读错误消息。应准确而简洁(通常为一行)。始终存在。 @@ -5438,7 +5232,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 详细信息:一个可选的次要错误消息,提供有关问题的更多详细信息。可能会跨多行。 + 详细信息:可选的次要错误消息,提供有关该问题的更多细节。可能占多行。 @@ -5448,9 +5242,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 提示: 关于问题应该怎么做的一个可选建议。 - 这意在与细节不同,它提供建议(可能不合适)而不是硬性事实。 - 可能会跨越多行。 + 提示:可选的建议,说明如何处理该问题。它与详细信息的区别在于,它提供建议(可能并不合适),而非确凿事实。可能占多行。 @@ -5493,9 +5285,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Where: 错误发生的上下文指示。 - 目前包括活动的过程语言函数和内部生成查询的调用堆栈回溯。 - 跟踪每行一个条目,最近的在前。 + 上下文:说明错误发生时的上下文。目前包括活跃的过程语言函数和内部生成的查询的调用栈回溯。回溯每行一个条目,最近的调用在前。 @@ -5505,7 +5295,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Schema name: 如果错误与特定数据库对象相关联,则为包含该对象的模式的名称(如果有)。 + 模式名:如果错误与某个特定数据库对象有关,则为包含该对象的模式名称(如果有)。 @@ -5515,7 +5305,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 表名: 如果错误与特定表相关联,则为表的名称。(有关表模式名称的名称,请参考模式名称字段。) + 表名:如果错误与某个特定表有关,则为该表的名称。(表所在模式的名称见模式名字段。) @@ -5525,7 +5315,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列名: 如果错误与特定表列相关联,则为列的名称。(请参考模式和表名字段以识别表。) + 列名:如果错误与某个特定表列有关,则为该列的名称。(通过模式名和表名字段确定该表。) @@ -5535,8 +5325,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 数据类型名称: 如果错误与特定数据类型相关联,则为数据类型的名称。 - (有关数据类型模式的名称,请参阅模式名称字段。) + 数据类型名:如果错误与某个特定数据类型有关,则为该数据类型的名称。(数据类型所在模式的名称见模式名字段。) @@ -5546,8 +5335,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 约束名称: 如果错误与特定约束相关联,则为约束的名称。请参考上面列出的字段,了解相关表或域。 - (为此,即使索引不是使用约束语法创建的,也将其视为约束。) + 约束名:如果错误与某个特定约束有关,则为该约束的名称。相关的表或域见上述字段。(这里将索引也视为约束,即使它不是用约束语法创建的。) @@ -5557,7 +5345,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 文件: 报告错误的源代码位置的文件名。 + 文件:报告错误的源代码位置所在的文件名。 @@ -5567,7 +5355,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Line: 源代码位置的行号,报告错误的位置。 + 行号:报告错误的源代码位置所在的行号。 @@ -5577,7 +5365,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Routine: 报告错误的源代码例程的名称。 + 例程:报告错误的源代码例程的名称。 @@ -5586,15 +5374,12 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 模式名称、表名称、列名称、数据类型名称和约束名称的字段仅针对有限数量的错误类型提供; - 请参阅。前端不应假设任何这些字段的存在就保证了另一个字段的存在。 - 核心错误源观察到上述相互关系,但用户定义的函数可能以其他方式使用这些字段。 - 同样地,客户端不应假设这些字段表示当前数据库中的当代对象。 + 模式名、表名、列名、数据类型名和约束名字段仅针对有限的几类错误提供,见 。前端不应假设其中任何字段的存在就保证了另一个字段的存在。核心错误源遵循上述相互关系,但用户定义的函数可能以其他方式使用这些字段。同样,客户端不应假设这些字段表示当前数据库中现存的对象。 - 客户端负责格式化显示的信息以满足其需求;特别是应根据需要换行。错误消息字段中出现的换行符应被视为段落分隔符,而不是换行符。 + 客户端负责按自身需要格式化显示的信息;尤其应根据需要将长行断开。错误消息字段中的换行符应视为段落分隔符,而非行分隔符。 @@ -5620,18 +5405,18 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为开始消息。 + 将该消息标识为 Begin 消息。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 事务的最终LSN。 + 事务的最终 LSN。 @@ -5642,7 +5427,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -5653,7 +5438,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -5683,8 +5468,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -5695,14 +5479,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标志; 逻辑解码消息是非事务性的时为0,是事务性的时为1。 + 标志:0 表示没有标志;1 表示该逻辑解码消息是事务性的。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -5758,7 +5542,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为提交消息。 + 将该消息标识为 Commit 消息。 @@ -5776,22 +5560,22 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 提交的LSN。 + 提交的 LSN。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 事务的结束LSN。 + 事务的结束 LSN。 @@ -5802,7 +5586,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -5821,18 +5605,18 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为原始消息。 + 将该消息标识为 Origin 消息。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 原始服务器上提交的LSN。 + 源服务器上提交的 LSN。 @@ -5843,14 +5627,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 原点的名称。 + 复制源的名称。 - 请注意,在单个事务中可能存在多个Origin消息。 + 注意,单个事务中可能有多条 Origin 消息。 @@ -5866,7 +5650,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为关系消息。 + 将该消息标识为 Relation 消息。 @@ -5877,8 +5661,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -5900,7 +5683,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 命名空间(pg_catalog为空字符串)。 + 命名空间(对于 pg_catalog 为空字符串)。 @@ -5922,7 +5705,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 关系的复制标识设置(与relreplidentpg_class中相同)。 + 关系的复制标识设置(与 pg_class 中的 relreplident 相同)。 @@ -5940,7 +5723,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于出版物中包含的每一列(除了生成的列),会出现以下消息部分: + 接下来,发布中包含的每一列(生成列除外)都会出现以下消息部分: @@ -5950,7 +5733,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列的标志。目前可以是0表示没有标志,或者是1表示将该列标记为键的一部分。 + 列的标志。目前可以为 0,表示没有标志;或为 1,标记该列是键的一部分。 @@ -5983,7 +5766,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列的类型修饰符 (atttypmod)。 + 列的类型修饰符(atttypmod)。 @@ -6002,7 +5785,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为类型消息。 + 将该消息标识为 Type 消息。 @@ -6013,8 +5796,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6036,7 +5818,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 命名空间(pg_catalog为空字符串)。 + 命名空间(对于 pg_catalog 为空字符串)。 @@ -6066,7 +5848,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为插入消息。 + 将该消息标识为 Insert 消息。 @@ -6077,8 +5859,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6089,7 +5870,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。 + 关系的 OID,与 Relation 消息中的 ID 对应。 @@ -6100,7 +5881,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData消息为新元组。 + 将后续 TupleData 消息标识为新元组。 @@ -6111,7 +5892,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分,表示新元组的内容。 + 表示新元组内容的 TupleData 消息部分。 @@ -6130,7 +5911,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为更新消息。 + 将该消息标识为 Update 消息。 @@ -6141,8 +5922,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6153,7 +5933,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。 + 关系的 OID,与 Relation 消息中的 ID 对应。 @@ -6164,8 +5944,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData子消息为键。 - 此字段是可选的,仅在更新更改了属于REPLICA IDENTITY索引的任何列的数据时才存在。 + 将后续 TupleData 子消息标识为键。此字段可选,仅在更新更改了属于 REPLICA IDENTITY 索引的某一列或多列的数据时出现。 @@ -6176,8 +5955,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData子消息为旧元组。 - 此字段是可选的,仅在发生更新的表中REPLICA IDENTITY设置为FULL时才存在。 + 将后续 TupleData 子消息标识为旧元组。此字段可选,仅在发生更新的表将 REPLICA IDENTITY 设为 FULL 时出现。 @@ -6188,7 +5966,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分表示旧元组或主键的内容。仅在先前的'O'或'K'部分存在时才存在。 + 表示旧元组或主键内容的 TupleData 消息部分。仅在前面的'O'或'K'部分存在时出现。 @@ -6199,7 +5977,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData消息为新元组。 + 将后续 TupleData 消息标识为新元组。 @@ -6210,14 +5988,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分表示新元组的内容。 + 表示新元组内容的 TupleData 消息部分。 - 更新消息可能包含一个'K'消息部分,也可能包含一个'O'消息部分,或者两者都不包含,但绝不会同时包含两者。 + Update 消息可以包含 'K' 消息部分或 'O' 消息部分,也可以两者都不包含,但绝不会同时包含两者。 @@ -6233,7 +6011,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为删除消息。 + 将该消息标识为 Delete 消息。 @@ -6244,8 +6022,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6256,7 +6033,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。 + 关系的 OID,与 Relation 消息中的 ID 对应。 @@ -6267,8 +6044,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData子消息为键。 - 如果发生删除操作的表使用索引作为REPLICA IDENTITY,则存在此字段。 + 将后续 TupleData 子消息标识为键。如果发生删除的表使用索引作为 REPLICA IDENTITY,则出现此字段。 @@ -6279,8 +6055,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData消息为旧元组。 - 如果发生删除操作的表的REPLICA IDENTITY设置为FULL,则存在此字段。 + 将后续 TupleData 消息标识为旧元组。如果发生删除的表将 REPLICA IDENTITY 设为 FULL,则出现此字段。 @@ -6291,14 +6066,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分,表示旧元组或主键的内容,取决于前一个字段。 + 表示旧元组或主键内容的 TupleData 消息部分,具体取决于前一个字段。 - 删除消息可能包含一个'K'消息部分或一个'O'消息部分,但绝不会同时包含两者。 + Delete 消息可以包含 'K' 消息部分或 'O' 消息部分,但绝不会同时包含两者。 @@ -6314,7 +6089,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为截断消息。 + 将该消息标识为 Truncate 消息。 @@ -6325,8 +6100,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6360,7 +6134,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。该字段对每个关系都重复。 + 关系的 OID,与 Relation 消息中的 ID 对应。每个关系都重复出现此字段。 @@ -6385,7 +6159,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为流开始消息。 + 将该消息标识为 Stream Start 消息。 @@ -6396,7 +6170,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6426,7 +6200,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为流停止消息。 + 将该消息标识为 Stream Stop 消息。 @@ -6445,7 +6219,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为流提交消息。 + 将该消息标识为 Stream Commit 消息。 @@ -6456,7 +6230,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6474,22 +6248,22 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 提交的LSN。 + 提交的 LSN。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 事务的结束LSN。 + 事务的结束 LSN。 @@ -6500,7 +6274,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6519,7 +6293,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为流中止消息。 + 将该消息标识为 Stream Abort 消息。 @@ -6530,7 +6304,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6587,14 +6361,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务开始消息。 + 将该消息标识为 Begin Prepare 消息。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6605,7 +6379,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6620,7 +6394,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6631,7 +6405,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6661,7 +6435,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务消息。 + 将该消息标识为 Prepare 消息。 @@ -6679,7 +6453,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6690,7 +6464,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6705,7 +6479,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6716,7 +6490,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6746,7 +6520,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务提交消息。 + 将该消息标识为 Commit Prepared 消息。 @@ -6764,7 +6538,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6775,7 +6549,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6790,7 +6564,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6801,7 +6575,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6831,7 +6605,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务回滚消息。 + 将该消息标识为 Rollback Prepared 消息。 @@ -6849,7 +6623,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6860,7 +6634,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6875,7 +6649,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6897,7 +6671,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6927,7 +6701,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为流式预备事务消息。 + 将该消息标识为 Stream Prepare 消息。 @@ -6945,7 +6719,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6956,7 +6730,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6971,7 +6745,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6982,7 +6756,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -7025,14 +6799,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于每一列(除了生成的列),会出现以下子消息之一: + 接下来,每一列(生成列除外)都会出现以下子消息之一: Byte1('n') - 将数据标识为NULL值。 + 将该数据标识为 NULL 值。 @@ -7043,7 +6817,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('u') - 将TOASTed值标识为未更改的值(实际值未发送)。 + 标识未更改的 TOAST 值(不发送实际值)。 @@ -7054,7 +6828,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('t') - 将数据标识为文本格式化值。 + 将该数据标识为文本格式的值。 @@ -7065,7 +6839,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('b') - 将数据标识为二进制格式化值。 + 将该数据标识为二进制格式的值。 @@ -7083,9 +6857,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byten - 列的值,以二进制或文本格式呈现。 - (如前述格式字节中指定)。 - n是上述长度。 + 列值,采用二进制或文本格式(由前面的格式字节指定)。n 为上述长度。 diff --git a/zh/16/rangetypes.sgml b/zh/16/rangetypes.sgml index 68409fa3..5badec6c 100644 --- a/zh/16/rangetypes.sgml +++ b/zh/16/rangetypes.sgml @@ -5,11 +5,11 @@ 范围类型 - range type + 范围类型 - multirange type + 多范围类型 @@ -21,7 +21,7 @@ - 每种范围类型都有一个对应的多范围类型。多范围是由多个彼此不连续、非空且非 NULL 的范围构成的有序列表。大多数范围操作符也可作用于多范围,并且多范围还有一些专用函数。 + 每种范围类型都有一个对应的多范围类型。多范围是一个有序列表,其中的范围彼此不连续,且均非空、非 NULL。大多数范围操作符也可作用于多范围,并且多范围还有一些专用函数。 @@ -124,15 +124,15 @@ SELECT isempty(numrange(1, 5)); 无限(无界)范围 - 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作 +/-infinity,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的 +/-infinity 值。 + 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作正负无穷大,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的正负无穷大值。 - 具有infinity概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 + 具有无穷大概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 - 函数lower_infupper_inf分别测试范围的下界和上界是否为无限。 + 函数lower_infupper_inf分别测试范围是否没有下界和上界。 @@ -324,8 +324,8 @@ SELECT '[11:10, 23:00]'::timerange; 索引 - range type - indexes on + 范围类型 + 索引 @@ -357,7 +357,7 @@ CREATE INDEX reservation_idx ON reservation USING GIST (during); - 此外,也可以为范围类型的表列创建 B-树和哈希索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和哈希支持主要是为了允许在查询内部进行排序和哈希,而不是用于创建实际的索引。 + 此外,也可以为范围类型的表列创建 B-树和 hash 索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和 hash 支持主要是为了允许在查询内部进行排序和 hash 运算,而不是用于创建实际的索引。 @@ -366,8 +366,8 @@ CREATE INDEX reservation_idx ON reservation USING GIST (during); 范围上的约束 - range type - exclude + 范围类型 + 排他约束 diff --git a/zh/16/ref/alter_extension.sgml b/zh/16/ref/alter_extension.sgml index 3ceae003..b5824a68 100644 --- a/zh/16/ref/alter_extension.sgml +++ b/zh/16/ref/alter_extension.sgml @@ -170,7 +170,7 @@ ALTER EXTENSION name DROP 要添加到扩展中或从扩展中移除的对象名称。表、聚合、域、外部表、函数、 - 操作符、操作符类、操作符族、过程、例程、序列、文本搜索对象、类型和视图的名称 + 操作符、操作符类、操作符族、过程、例程、序列、文本检索对象、类型和视图的名称 可以带模式限定。 diff --git a/zh/16/ref/alter_tsconfig.sgml b/zh/16/ref/alter_tsconfig.sgml index 891dce66..0845a229 100644 --- a/zh/16/ref/alter_tsconfig.sgml +++ b/zh/16/ref/alter_tsconfig.sgml @@ -19,7 +19,7 @@ PostgreSQL documentation ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义 + 更改一个文本检索配置的定义 @@ -51,7 +51,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义。你可以修改其从记号类型到字典的映射, + 更改一个文本检索配置的定义。你可以修改其从词元类型到词典的映射, 或者更改该配置的名称或拥有者。 @@ -75,7 +75,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 一个现有文本搜索配置的名称(可以是模式限定的)。 + 一个现有文本检索配置的名称(可以是模式限定的)。 @@ -86,7 +86,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 由该配置的解析器发出的记号类型的名称。 + 由该配置的解析器发出的词元类型的名称。 @@ -97,7 +97,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 用于指定记号类型的文本搜索字典名称。如果列出了多个字典, + 用于指定词元类型的文本检索词典名称。如果列出了多个词典, 将按指定顺序依次查阅它们。 @@ -109,7 +109,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 在映射中要替换的文本搜索字典的名称。 + 在映射中要替换的文本检索词典的名称。 @@ -121,7 +121,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA 被用来替代old_dictionary - 的文本搜索字典的名称。 + 的文本检索词典的名称。 @@ -132,7 +132,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新名称。 + 该文本检索配置的新名称。 @@ -143,7 +143,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新拥有者。 + 该文本检索配置的新拥有者。 @@ -154,7 +154,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新模式。 + 该文本检索配置的新模式。 @@ -163,17 +163,17 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - ADD MAPPING FOR形式会为指定记号类型设置要查阅的字典列表; - 如果任一记号类型已经有映射,则会报错。ALTER MAPPING FOR - 形式作用相同,但会先移除这些记号类型的任何现有映射。 + ADD MAPPING FOR形式会为指定词元类型设置要查阅的词典列表; + 如果任一词元类型已经有映射,则会报错。ALTER MAPPING FOR + 形式作用相同,但会先移除这些词元类型的任何现有映射。 ALTER MAPPING REPLACE形式会在 old_dictionary出现的任何位置, 用new_dictionary替换它。 - 如果出现FOR,则只对指定的记号类型这样做;如果未出现 + 如果出现FOR,则只对指定的词元类型这样做;如果未出现 FOR,则对该配置的所有映射这样做。 - DROP MAPPING形式会移除指定记号类型的所有字典,使这些类型的 - 记号被文本搜索配置忽略。除非出现IF EXISTS,否则如果这些 - 记号类型没有映射就会报错。 + DROP MAPPING形式会移除指定词元类型的所有词典,使这些类型的 + 词元被文本检索配置忽略。除非出现IF EXISTS,否则如果这些 + 词元类型没有映射就会报错。 @@ -187,7 +187,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA 下面的示例将my_config中凡是使用 - english字典的地方,都替换为swedish字典。 + english词典的地方,都替换为swedish词典。 diff --git a/zh/16/ref/alter_tsdictionary.sgml b/zh/16/ref/alter_tsdictionary.sgml index 163d788b..798c6734 100644 --- a/zh/16/ref/alter_tsdictionary.sgml +++ b/zh/16/ref/alter_tsdictionary.sgml @@ -19,7 +19,7 @@ PostgreSQL documentation ALTER TEXT SEARCH DICTIONARY - 更改一个文本搜索字典的定义 + 更改一个文本检索词典的定义 @@ -43,14 +43,14 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - ALTER TEXT SEARCH DICTIONARY更改文本搜索字典的 - 定义。你可以更改该字典的模板相关选项,也可以更改该字典的名称或拥有者。 + ALTER TEXT SEARCH DICTIONARY更改文本检索词典的 + 定义。你可以更改该词典的模板相关选项,也可以更改该词典的名称或拥有者。 - 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该字典 + 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该词典 的拥有者。 @@ -67,7 +67,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 一个现有文本搜索字典的名称(可以是模式限定的)。 + 一个现有文本检索词典的名称(可以是模式限定的)。 @@ -78,7 +78,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -89,7 +89,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 模板相关选项要使用的新值。如果省略等号和值,则会从该字典中移除 + 模板相关选项要使用的新值。如果省略等号和值,则会从该词典中移除 该选项之前的设置,从而允许使用默认值。 @@ -101,7 +101,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新名称。 + 该文本检索词典的新名称。 @@ -112,7 +112,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新拥有者。 + 该文本检索词典的新拥有者。 @@ -123,7 +123,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新模式。 + 该文本检索词典的新模式。 @@ -144,7 +144,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 下面的示例命令更改了一个基于 Snowball 的字典的停用词列表。其他参数 + 下面的示例命令更改了一个基于 Snowball 的词典的停用词列表。其他参数 保持不变。 @@ -170,7 +170,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( language = dutch, StopWords ); - 下面的示例命令更新了该字典的定义,但实际上并没有做 + 下面的示例命令更新了该词典的定义,但实际上并没有做 任何更改。 @@ -178,7 +178,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( dummy ); (之所以可行,是因为选项移除代码在不存在该选项时也不会报错。) - 这种技巧在修改该字典的配置文件时很有用:ALTER + 这种技巧在修改该词典的配置文件时很有用:ALTER 会强制现有数据库会话重新读取配置文件,而如果它们先前已经读取过这 些文件,本来是不会再次读取的。 diff --git a/zh/16/ref/alter_tsparser.sgml b/zh/16/ref/alter_tsparser.sgml index 0844cb0a..ccc73f05 100644 --- a/zh/16/ref/alter_tsparser.sgml +++ b/zh/16/ref/alter_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH PARSER - 更改一个全文检索解析器的定义 + 更改一个文本检索解析器的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA 描述 - ALTER TEXT SEARCH PARSER更改全文检索解析器的定义。 + ALTER TEXT SEARCH PARSER更改文本检索解析器的定义。 当前唯一支持的功能是更改该解析器的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA name - 一个现有全文检索解析器的名称(可以是模式限定的)。 + 一个现有文本检索解析器的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_name - 该全文检索解析器的新名称。 + 该文本检索解析器的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_schema - 该全文检索解析器的新模式。 + 该文本检索解析器的新模式。 diff --git a/zh/16/ref/alter_tstemplate.sgml b/zh/16/ref/alter_tstemplate.sgml index a3eec599..9c9dfc2c 100644 --- a/zh/16/ref/alter_tstemplate.sgml +++ b/zh/16/ref/alter_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH TEMPLATE - 更改一个文本搜索模板的定义 + 更改一个文本检索模板的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA 描述 - ALTER TEXT SEARCH TEMPLATE更改文本搜索模板的定义。 + ALTER TEXT SEARCH TEMPLATE更改文本检索模板的定义。 当前唯一支持的功能是更改该模板的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA name - 一个现有文本搜索模板的名称(可以是模式限定的)。 + 一个现有文本检索模板的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_name - 该文本搜索模板的新名称。 + 该文本检索模板的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_schema - 该文本搜索模板的新模式。 + 该文本检索模板的新模式。 diff --git a/zh/16/ref/create_tsconfig.sgml b/zh/16/ref/create_tsconfig.sgml index 52970b36..fc77edb9 100644 --- a/zh/16/ref/create_tsconfig.sgml +++ b/zh/16/ref/create_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH CONFIGURATION - 定义一个新的文本搜索配置 + 定义一个新的文本检索配置 @@ -33,24 +33,24 @@ CREATE TEXT SEARCH CONFIGURATION name CREATE TEXT SEARCH CONFIGURATION - 创建一个新的文本搜索配置。文本搜索配置指定一个能把字符串拆分为记号 - 的文本搜索解析器,以及一些可用于判断哪些记号对搜索有意义的词典。 + 创建一个新的文本检索配置。文本检索配置指定一个能把字符串拆分为词元 + 的文本检索解析器,以及一些可用于判断哪些词元对搜索有意义的词典。 - 如果只指定了解析器,那么新文本搜索配置最初没有从记号类型到词典的映射, + 如果只指定了解析器,那么新文本检索配置最初没有从词元类型到词典的映射, 因而会忽略所有词。要让该配置真正可用,必须使用后续的ALTER TEXT SEARCH CONFIGURATION命令创建映射。 - 另一种方式是复制一个现有的文本搜索配置。 + 另一种方式是复制一个现有的文本检索配置。 - 如果给出了一个模式名称,则文本搜索配置会被创建在指定的模式中。否则它将会 + 如果给出了一个模式名称,则文本检索配置会被创建在指定的模式中。否则它将会 被创建在当前模式中。 - 定义该文本搜索配置的用户会成为其拥有者。 + 定义该文本检索配置的用户会成为其拥有者。 @@ -66,7 +66,7 @@ CREATE TEXT SEARCH CONFIGURATION namename - 要创建的文本搜索配置的名称。该名称可以是模式限定的。 + 要创建的文本检索配置的名称。该名称可以是模式限定的。 @@ -75,7 +75,7 @@ CREATE TEXT SEARCH CONFIGURATION nameparser_name - 此配置要使用的文本搜索解析器的名称。 + 此配置要使用的文本检索解析器的名称。 @@ -84,7 +84,7 @@ CREATE TEXT SEARCH CONFIGURATION namesource_config - 要复制的现有文本搜索配置的名称。 + 要复制的现有文本检索配置的名称。 diff --git a/zh/16/ref/create_tsdictionary.sgml b/zh/16/ref/create_tsdictionary.sgml index c45a7240..823710b7 100644 --- a/zh/16/ref/create_tsdictionary.sgml +++ b/zh/16/ref/create_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH DICTIONARY - 定义一个新的文本搜索字典 + 定义一个新的文本检索词典 @@ -33,19 +33,19 @@ CREATE TEXT SEARCH DICTIONARY name CREATE TEXT SEARCH DICTIONARY创建一个 - 新的文本搜索字典。文本搜索字典指定一种在搜索时识别哪些词值得关注、 - 哪些词不值得关注的方式。字典依赖于文本搜索模板,后者规定了实际执行 - 这项工作的函数。通常,字典会提供一些选项,用来控制模板函数的具体 + 新的文本检索词典。文本检索词典指定一种在搜索时识别哪些词值得关注、 + 哪些词不值得关注的方式。词典依赖于文本检索模板,后者规定了实际执行 + 这项工作的函数。通常,词典会提供一些选项,用来控制模板函数的具体 行为。 - 如果给出了一个模式名称,那么该文本搜索字典会被创建在指定的模式中。 + 如果给出了一个模式名称,那么该文本检索词典会被创建在指定的模式中。 否则它会被创建在当前模式中。 - 定义文本搜索字典的用户将成为其拥有者。 + 定义文本检索词典的用户将成为其拥有者。 @@ -61,7 +61,7 @@ CREATE TEXT SEARCH DICTIONARY name name - 要创建的文本搜索字典的名称。该名称可以被模式限定。 + 要创建的文本检索词典的名称。该名称可以被模式限定。 @@ -70,7 +70,7 @@ CREATE TEXT SEARCH DICTIONARY name template - 用于定义该字典基本行为的文本搜索模板名称。 + 用于定义该词典基本行为的文本检索模板名称。 @@ -79,7 +79,7 @@ CREATE TEXT SEARCH DICTIONARY name option - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -105,7 +105,7 @@ CREATE TEXT SEARCH DICTIONARY name 下面的示例命令创建了一个基于 Snowball 且使用非标准停用词列表的 - 字典。 + 词典。 diff --git a/zh/16/ref/create_tsparser.sgml b/zh/16/ref/create_tsparser.sgml index 358152ce..88be54e6 100644 --- a/zh/16/ref/create_tsparser.sgml +++ b/zh/16/ref/create_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH PARSER - 定义一个新的全文检索解析器 + 定义一个新的文本检索解析器 @@ -36,19 +36,19 @@ CREATE TEXT SEARCH PARSER name ( CREATE TEXT SEARCH PARSER创建一个 - 新的全文检索解析器。全文检索解析器定义了一种方法,用于将文本字符串 - 拆分成记号并为这些记号指定类型(类别)。解析器本身并没有太大用处, - 必须与一些全文检索字典一起绑定到一个全文检索配置中,才能用于搜索。 + 新的文本检索解析器。文本检索解析器定义了一种方法,用于将文本字符串 + 拆分成词元并为这些词元指定类型(类别)。解析器本身并没有太大用处, + 必须与一些文本检索词典一起绑定到一个文本检索配置中,才能用于搜索。 - 如果给出了一个模式名称,那么全文检索解析器将被创建在指定的模式中。 + 如果给出了一个模式名称,那么文本检索解析器将被创建在指定的模式中。 否则它会被创建在当前模式中。 要使用CREATE TEXT SEARCH PARSER,你必须是超级用户。 - 之所以有此限制,是因为错误的全文检索解析器定义可能会让服务器陷入 + 之所以有此限制,是因为错误的文本检索解析器定义可能会让服务器陷入 混乱,甚至崩溃。 @@ -65,7 +65,7 @@ CREATE TEXT SEARCH PARSER name ( name - 要创建的全文检索解析器的名称。该名称可以是模式限定的。 + 要创建的文本检索解析器的名称。该名称可以是模式限定的。 @@ -83,7 +83,7 @@ CREATE TEXT SEARCH PARSER name ( gettoken_function - 该解析器的获取下一个记号的函数名称。 + 该解析器的获取下一个词元的函数名称。 @@ -101,7 +101,7 @@ CREATE TEXT SEARCH PARSER name ( lextypes_function - 该解析器的 lextypes 函数的名称(该函数返回它所产生的记号类型集合的 + 该解析器的 lextypes 函数的名称(该函数返回它所产生的词元类型集合的 信息)。 @@ -111,7 +111,7 @@ CREATE TEXT SEARCH PARSER name ( headline_function - 该解析器的 headline 函数的名称(该函数对一组记号生成摘要)。 + 该解析器的 headline 函数的名称(该函数对一组词元生成摘要)。 diff --git a/zh/16/ref/create_tstemplate.sgml b/zh/16/ref/create_tstemplate.sgml index 702233e4..0f1b4e1a 100644 --- a/zh/16/ref/create_tstemplate.sgml +++ b/zh/16/ref/create_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH TEMPLATE - 定义一个新的全文检索模板 + 定义一个新的文本检索模板 @@ -33,22 +33,22 @@ CREATE TEXT SEARCH TEMPLATE name ( CREATE TEXT SEARCH TEMPLATE创建一个 - 新的全文检索模板。全文检索模板定义实现全文检索字典的函数。模板本身 - 并无直接用途,必须先实例化为字典后才能使用。字典通常会指定要传递给 + 新的文本检索模板。文本检索模板定义实现文本检索词典的函数。模板本身 + 并无直接用途,必须先实例化为词典后才能使用。词典通常会指定要传递给 模板函数的参数。 - 如果给出了模式名称,则全文检索模板会被创建在指定模式中。否则它会被 + 如果给出了模式名称,则文本检索模板会被创建在指定模式中。否则它会被 创建在当前模式中。 要使用CREATE TEXT SEARCH TEMPLATE,你 - 必须是超级用户。之所以有此限制,是因为错误的全文检索模板定义可能使 - 服务器陷入混乱,甚至崩溃。将模板与字典分离的原因在于,模板封装了定 - 义字典时那些不安全的方面。而在定义字典时可设置的参数, - 对非特权用户来说是安全的,因此创建字典不必是特权操作。 + 必须是超级用户。之所以有此限制,是因为错误的文本检索模板定义可能使 + 服务器陷入混乱,甚至崩溃。将模板与词典分离的原因在于,模板封装了定 + 义词典时那些不安全的方面。而在定义词典时可设置的参数, + 由普通用户设置也是安全的,因此创建词典不必是特权操作。 @@ -64,7 +64,7 @@ CREATE TEXT SEARCH TEMPLATE name ( name - 要创建的全文检索模板名称。该名称可以是模式限定的。 + 要创建的文本检索模板名称。该名称可以是模式限定的。 diff --git a/zh/16/ref/drop_opclass.sgml b/zh/16/ref/drop_opclass.sgml index 9d67dc64..545a2517 100644 --- a/zh/16/ref/drop_opclass.sgml +++ b/zh/16/ref/drop_opclass.sgml @@ -110,7 +110,7 @@ DROP OPERATOR CLASS [ IF EXISTS ] name示例 - 移除 B-tree 操作符类widget_ops: + 移除 B-树操作符类widget_ops DROP OPERATOR CLASS widget_ops USING btree; diff --git a/zh/16/ref/drop_tsconfig.sgml b/zh/16/ref/drop_tsconfig.sgml index ea139802..b3ebb9d1 100644 --- a/zh/16/ref/drop_tsconfig.sgml +++ b/zh/16/ref/drop_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH CONFIGURATION - 移除一个文本搜索配置 + 移除一个文本检索配置 @@ -29,7 +29,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 描述 - DROP TEXT SEARCH CONFIGURATION删除一个现有文本搜索配置。 + DROP TEXT SEARCH CONFIGURATION删除一个现有文本检索配置。 要执行此命令,你必须是该配置的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name IF EXISTS - 如果该文本搜索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name name - 现有文本搜索配置的名称(可以被模式限定)。 + 现有文本检索配置的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name CASCADE - 自动删除依赖于该文本搜索配置的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索配置的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name RESTRICT - 如果有任何对象依赖于该文本搜索配置,则拒绝删除该配置。这是默认值。 + 如果有任何对象依赖于该文本检索配置,则拒绝删除该配置。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 示例 - 移除文本搜索配置my_english: + 移除文本检索配置my_english DROP TEXT SEARCH CONFIGURATION my_english; 如果已有索引在to_tsvector调用中引用了该配置, - 此命令将不会成功。加上CASCADE可以在删除该文本搜索配置的同时删除这类索引。 + 此命令将不会成功。加上CASCADE可以在删除该文本检索配置的同时删除这类索引。 diff --git a/zh/16/ref/drop_tsdictionary.sgml b/zh/16/ref/drop_tsdictionary.sgml index 316c5d00..0f7751a1 100644 --- a/zh/16/ref/drop_tsdictionary.sgml +++ b/zh/16/ref/drop_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH DICTIONARY - 移除一个文本搜索字典 + 移除一个文本检索词典 @@ -29,8 +29,8 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name描述 - DROP TEXT SEARCH DICTIONARY删除一个现有文本搜索字典。 - 要执行此命令,你必须是该字典的拥有者。 + DROP TEXT SEARCH DICTIONARY删除一个现有文本检索词典。 + 要执行此命令,你必须是该词典的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索字典不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索词典不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] namename - 一个现有文本搜索字典的名称(可以被模式限定)。 + 一个现有文本检索词典的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索字典的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索词典的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索字典,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索词典,则拒绝删除它。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name示例 - 移除文本搜索字典english: + 移除文本检索词典english DROP TEXT SEARCH DICTIONARY english; - 如果已有文本搜索配置使用该字典,此命令将不会成功。 - 加上CASCADE可以在删除字典的同时删除这类配置。 + 如果已有文本检索配置使用该词典,此命令将不会成功。 + 加上CASCADE可以在删除词典的同时删除这类配置。 diff --git a/zh/16/ref/drop_tsparser.sgml b/zh/16/ref/drop_tsparser.sgml index a65f47be..ea74f0f8 100644 --- a/zh/16/ref/drop_tsparser.sgml +++ b/zh/16/ref/drop_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH PARSER - 移除一个文本搜索解析器 + 移除一个文本检索解析器 @@ -29,7 +29,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name描述 - DROP TEXT SEARCH PARSER删除一个现有文本搜索解析器。 + DROP TEXT SEARCH PARSER删除一个现有文本检索解析器。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] namename - 一个现有文本搜索解析器的名称(可以被模式限定)。 + 一个现有文本检索解析器的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索解析器的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索解析器的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索解析器,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索解析器,则拒绝删除它。这是默认值。 @@ -82,13 +82,13 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name示例 - 移除文本搜索解析器my_parser: + 移除文本检索解析器my_parser DROP TEXT SEARCH PARSER my_parser; - 如果已有文本搜索配置使用该解析器,此命令将不会成功。 + 如果已有文本检索配置使用该解析器,此命令将不会成功。 加上CASCADE可以在删除解析器的同时删除这类配置。 diff --git a/zh/16/ref/drop_tstemplate.sgml b/zh/16/ref/drop_tstemplate.sgml index fa1faab0..3a44c927 100644 --- a/zh/16/ref/drop_tstemplate.sgml +++ b/zh/16/ref/drop_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH TEMPLATE - 移除一个文本搜索模板 + 移除一个文本检索模板 @@ -29,7 +29,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name描述 - DROP TEXT SEARCH TEMPLATE删除一个现有文本搜索模板。 + DROP TEXT SEARCH TEMPLATE删除一个现有文本检索模板。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] namename - 现有文本搜索模板的名称(可以被模式限定)。 + 现有文本检索模板的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索模板的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索模板的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索模板,则拒绝删除该模板。这是默认值。 + 如果有任何对象依赖于该文本检索模板,则拒绝删除该模板。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name示例 - 移除文本搜索模板thesaurus: + 移除文本检索模板thesaurus DROP TEXT SEARCH TEMPLATE thesaurus; - 如果已有文本搜索字典使用该模板,此命令将不会成功。加上CASCADE - 可以在删除该模板的同时删除这类字典。 + 如果已有文本检索词典使用该模板,此命令将不会成功。加上CASCADE + 可以在删除该模板的同时删除这类词典。 diff --git a/zh/16/ref/initdb.sgml b/zh/16/ref/initdb.sgml index e1a9c9e5..36a012c7 100644 --- a/zh/16/ref/initdb.sgml +++ b/zh/16/ref/initdb.sgml @@ -192,7 +192,7 @@ PostgreSQL documentation - + @@ -223,21 +223,16 @@ PostgreSQL documentation - + - 对数据页启用校验和,以帮助检测原本会悄无声息发生的、由 I/O 系统导致的损坏。 - 该项默认启用;使用可禁用校验和。 - - - - 启用校验和可能会带来小幅性能损失。如果启用,就会为所有数据库中的所有对象计算校验和。 - 所有校验和失败都会在 - - pg_stat_database视图中报告。详见 - 。 + 在数据页上使用校验和,帮助检测 I/O 系统造成的、否则可能悄无声息的数据损坏。 + 启用校验和可能会带来明显的性能损失。如果启用,就会为所有数据库中的所有对象计算校验和。 + 所有校验和失败都会在 + pg_stat_database视图中报告。 + 详见 @@ -277,8 +272,6 @@ PostgreSQL documentation - - @@ -290,11 +283,25 @@ PostgreSQL documentation - - + + + - 不启用数据校验和。 + 默认情况下,initdb会等待所有文件都安全写入磁盘。该选项使 + initdb在不等待的情况下返回,速度更快,但这意味着如果后续操作系统崩溃, + 数据目录可能会损坏。通常,该选项适用于测试,但不应用于创建生产环境安装。 + + + + + + + + + 默认情况下,initdb会在其输出末尾写出如何启动集簇的说明。 + 该选项会省略这些说明。它主要供那些对initdb进行平台特定封装的工具使用, + 因为在这种情况下那些说明很可能并不正确。 @@ -308,12 +315,25 @@ PostgreSQL documentation + + + + + + 将所有数据库文件安全地写入磁盘并退出。这不会执行任何常规的 + initdb操作。通常,该选项可用于在将 + off改为on后, + 确保能够可靠恢复。 + + + + - 设置默认文本搜索配置。更多信息见 + 设置默认文本检索配置。更多信息见 @@ -427,91 +447,6 @@ PostgreSQL documentation - - - - - - - 默认情况下,initdb会等待所有文件都安全写入磁盘。该选项使 - initdb在不等待的情况下返回,速度更快,但这意味着如果后续操作系统崩溃, - 数据目录可能会损坏。通常,该选项适用于测试,但不应用于创建生产环境安装。 - - - - - - - - - 默认情况下,initdb会将所有数据库文件安全地写入磁盘。 - 该选项指示initdb跳过同步各个数据库目录中的所有文件、这些数据库目录本身 - 以及表空间目录,也就是base子目录中的所有内容和任何其他表空间目录。 - 其他文件,例如pg_walpg_xact中的文件, - 仍会被同步,除非也指定了。 - - - 请注意,如果与 - 一起使用,上述部分或全部文件与目录仍会被同步, - 因为syncfs处理的是整个文件系统。 - - - 该选项主要供那些会另行确保这些被跳过文件已同步到磁盘的工具在内部使用。 - - - - - - - - - 默认情况下,initdb会在其输出末尾写出如何启动集簇的说明。 - 该选项会省略这些说明。它主要供那些对initdb进行平台特定封装的工具使用, - 因为在这种情况下那些说明很可能并不正确。 - - - - - - - - - - 显示内部设置并退出,不执行其他操作。可用于调试initdb的安装。 - - - - - - - - - 设为fsync(默认值)时,initdb会递归打开并同步 - 数据目录中的所有文件。查找文件时会跟随 WAL 目录和每个已配置表空间的符号链接。 - - - 在 Linux 上,也可以改用syncfs,请求操作系统同步包含数据目录、 - WAL 文件以及每个表空间的整个文件系统。使用syncfs时需注意的事项见 - 。 - - - 使用时,该选项不起作用。 - - - - - - - - - - 将所有数据库文件安全地写入磁盘并退出。这不会执行任何常规的 - initdb操作。通常,该选项可用于在将 - off改为on后, - 确保能够可靠恢复。 - - - diff --git a/zh/16/ref/pgbench.sgml b/zh/16/ref/pgbench.sgml index e0fa9e55..66c44e71 100644 --- a/zh/16/ref/pgbench.sgml +++ b/zh/16/ref/pgbench.sgml @@ -39,7 +39,7 @@ PostgreSQL documentation 描述 - pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,必要时可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 + pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,也可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 @@ -69,7 +69,7 @@ tps = 896.967014 (without initial connection time) - 默认的类 TPC-B 事务测试要求预先建立特定的表。应使用(initialize)选项调用pgbench来创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: + 默认的类 TPC-B 事务测试要求预先建立特定的表。应使用(初始化)选项调用pgbench来创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: pgbench -i other-options dbname @@ -89,14 +89,14 @@ pgbench -i other-options 在默认的比例因子 1 下,这些表最初包含如下行数: -table # of rows +表 行数 --------------------------------- pgbench_branches 1 pgbench_tellers 10 pgbench_accounts 100000 pgbench_history 0 - 可以使用(比例因子)选项来增加行数,而且在大多数场景下也确实应该这样做。此时还可以配合使用(fillfactor)选项。 + 可以使用(比例因子)选项来增加行数,而且在大多数场景下通常也应该这样做。此时还可以配合使用(fillfactor)选项。 @@ -116,7 +116,7 @@ pgbench options d 选项 - 下面分成三个部分。数据库初始化期间使用的选项和运行基准时会使用不同的选项,但也有一些选项在两种情况下都使用。 + 以下内容分为三个小节。数据库初始化和运行基准测试时使用不同的选项,但有些选项在这两种情况下都适用。 @@ -129,8 +129,7 @@ pgbench options d - - + dbname @@ -191,12 +190,12 @@ pgbench options d 生成数据并将其装载到标准表中,替换其中任何已有数据。 - 使用g(客户端生成数据)时,数据由pgbench客户端生成,再通过COPY发送到服务器,因此会大量占用客户端/服务器带宽。对于 14 及以上版本的PostgreSQLpgbench会在普通(非分区)表上使用选项装载数据,以加快后续的VACUUM。使用g时,在为所有表生成数据的过程中,每生成 100,000 行会输出一条日志消息。 + 使用g(客户端生成数据)时,数据由pgbench客户端生成,再通过COPY发送到服务器,因此会大量占用客户端/服务器带宽。对于 14 及以上版本的PostgreSQL,除非启用了分区,pgbench会使用 FREEZE 选项,以加快后续的VACUUM。使用g时,在为pgbench_accounts表生成数据的过程中,每生成 100,000 行会输出一条日志消息。 使用G(服务器端生成数据)时, pgbench客户端只发送较小的查询,随后实际数据在服务器端生成。 - 这种方式几乎不需要额外带宽,但服务器会承担更多工作。 + 这种方式不需要大量带宽,但服务器会承担更多工作。 使用G时,生成数据期间不会打印任何进度消息。 @@ -416,6 +415,16 @@ pgbench options d + + + + + + 打印调试输出。 + + + + varname=value varname=value @@ -505,13 +514,13 @@ pgbench options d 用于向服务器提交查询的协议: - simple: 使用简单查询协议。 + simple:使用简单查询协议。 - extended: 使用扩展查询协议。 + extended:使用扩展查询协议。 - prepared: 使用带有预备语句的扩展查询协议。 + prepared:使用带有预备语句的扩展查询协议。 @@ -572,7 +581,7 @@ pgbench options d - 在基准测试完成后,报告每条语句的以下统计信息:平均延迟(从客户端视角看到的语句执行时间)、失败次数,以及该语句因串行化或死锁错误而发生的重试次数。仅当选项不等于 1 时,报告才会显示重试统计信息。 + 在基准测试完成后,报告每条命令的以下统计信息:平均延迟(从客户端视角看到的语句执行时间)、失败次数,以及该命令因串行化或死锁错误而发生的重试次数。仅当选项不等于 1 时,报告才会显示重试统计信息。 @@ -607,7 +616,7 @@ pgbench options d 较高的计划滞后时间表明,在所选客户端数和线程数下,系统无法以指定速率处理事务。 当平均事务执行时间长于事务之间的计划间隔时,后续事务会不断进一步落后, - 而计划滞后时间也会随着测试持续时间增加。在这种情况下,只能降低指定的事务速率。 + 而计划滞后时间也会随着测试持续时间增加。在这种情况下,需要降低指定的事务速率。 @@ -619,7 +628,7 @@ pgbench options d pgbench输出中报告指定的比例因子。 - 对于内置测试,这通常没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 + 对于内置测试,这没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 但在只测试自定义基准(选项)时, 除非使用此选项,否则比例因子会被报告为 1。 @@ -686,17 +695,7 @@ pgbench options d - - - - - 当任一客户端因错误被中止时,立即退出。如果不指定该选项,即使某个客户端被中止,其他客户端仍可按的设定继续运行,此时pgbench会输出不完整的结果。 - - - 请注意,串行化失败或死锁失败不会中止客户端,因此不受该选项影响。更多信息见 。 - - - + @@ -733,7 +732,7 @@ pgbench options d 启用对出现串行化/死锁错误的事务进行重试,并设置最大尝试次数。此选项可与 - 组合使用,后者限制所有事务尝试的总耗时; + 组合使用,后者限制同一事务所有尝试的总耗时; 此外,如果没有, 则不能使用无限次尝试(--max-tries=0)。 默认值为 1,出现串行化/死锁错误的事务不会重试。有关此类事务重试的更多信息,见 @@ -813,7 +812,7 @@ pgbench options d - 打印关于所有错误和失败的消息(即不会重试的错误),包括超出了哪一种重试限制,以及对于串行化/死锁失败超出的幅度。(请注意,这种情况下输出量可能会显著增加。)更多信息见。 + 打印关于所有错误和失败(不再重试的错误)的消息,包括超出了哪一种重试限制,以及对于串行化/死锁失败超出的幅度。(请注意,这种情况下输出量可能会显著增加。)更多信息见 @@ -828,18 +827,11 @@ pgbench options d 公共选项 - pgbench 还接受以下用于连接参数及其他通用设置的命令行参数: + pgbench 还接受以下用于连接参数的通用命令行参数: - - - - - 打印调试输出。 - - - + hostname @@ -903,7 +895,7 @@ pgbench options d 成功运行会以状态 0 退出。状态 1 表示静态问题,例如无效的命令行选项,或者按理不应发生的内部错误。 在启动基准测试时发生的早期错误,例如初始连接失败,也会以状态 1 退出。 - 运行过程中出现的错误,例如数据库错误或脚本中的问题,会导致退出状态 2。在后一种情况下,如果未指定pgbench会打印部分结果。 + 运行过程中出现的错误,例如数据库错误或脚本中的问题,会导致退出状态 2。在后一种情况下,pgbench会打印部分结果。 @@ -941,7 +933,7 @@ pgbench options d 注解 - + 在<application>pgbench</application>中实际执行的<quote>事务</quote>是什么? @@ -996,7 +988,7 @@ pgbench options d - 假定pgbench脚本不包含不完整的 SQL 事务块。如果在运行时客户端在尚未完成最后一个事务块时就到达脚本末尾,它将被中止。 + 假定pgbench脚本不包含不完整的 SQL 事务块。如果在运行时客户端在尚未完成最后一个事务块时就到达脚本末尾,该客户端将被中止。 @@ -1033,7 +1025,7 @@ pgbench options d default_seed - 默认在哈希和伪随机置换函数中使用的种子 + 默认在 hash 和伪随机置换函数中使用的种子 @@ -1050,7 +1042,7 @@ pgbench options d - 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令及其参数之间以空白分隔。支持的元命令如下: + 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令的参数以空白分隔。支持的元命令如下: @@ -1088,7 +1080,7 @@ UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid RETURNING abalance \gset --- compound of two queries +-- 两个查询的组合 SELECT 1 \; SELECT 2 AS two, 3 AS three \gset p_ SELECT 4 AS four \; SELECT 5 AS five \aset @@ -1180,7 +1172,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset - command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在其开头再写一个冒号。 + command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在argument开头再写一个冒号。 @@ -1212,13 +1204,13 @@ SELECT 4 AS four \; SELECT 5 AS five \aset \startpipeline - \syncpipeline + \endpipeline - 这组命令用于实现 SQL 语句的流水线执行。流水线必须以\startpipeline开始,并以\endpipeline结束;在两者之间可以出现任意数量的\syncpipeline,它会发送一个sync 消息,但不会结束当前流水线,同时会刷新发送缓冲区。在流水线模式下,语句会发送到服务器,而不等待前一条语句的结果。更多细节见。流水线模式要求使用扩展查询协议。 + 这些命令界定 SQL 语句管道的开始和结束。在管道模式下,语句会发送到服务器,而不等待前一条语句的结果。更多细节见。管道模式要求使用扩展查询协议。 @@ -1514,7 +1506,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 加 + 加法 5 + 4 @@ -1528,7 +1520,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 减 + 减法 3 - 2.0 @@ -1542,7 +1534,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 乘 + 乘法 5 * 4 @@ -1556,7 +1548,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 除法(如果两个输入都是整数,则将结果截断为零) + 除法(如果两个输入都是整数,则将结果向零截断) 5 / 3 @@ -1584,7 +1576,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 取反 + 取相反数 - 2.0 @@ -1674,7 +1666,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset double - 指数(e 的给定次幂) + 指数函数(e 的给定次幂) exp(1.0) @@ -1716,7 +1708,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算 FNV-1a 哈希。 + 计算 FNV-1a hash hash_fnv1a(10, 5432) @@ -1730,7 +1722,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算 MurmurHash2 哈希。 + 计算 MurmurHash2 hash hash_murmur2(10, 5432) @@ -1800,8 +1792,8 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - i的排列值,范围在[0, size)内。 - 它表示i(模size)在整数0...size-1的伪随机排列中的新位置;该排列由seed参数化,详见下文。 + i的置换值,范围在[0, size)内。 + 它表示i(模size)在整数0...size-1的伪随机置换中的新位置;该置换由seed参数化,详见下文。 permute(0, 4) @@ -1861,7 +1853,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算[lb, ub]中的指数分布随机整数,如下所示。 + 计算[lb, ub]中的指数分布随机整数,详见下文。 random_exponential(1, 10, 3.0) @@ -1875,7 +1867,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算[lb, ub]中的高斯分布随机整数,如下所示。 + 计算[lb, ub]中的高斯分布随机整数,详见下文。 random_gaussian(1, 10, 2.5) @@ -1922,7 +1914,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset - 对于指数分布,parameter通过在parameter处截断一个快速衰减的指数分布,再将其投影到边界之间的整数上,从而控制分布。准确地说, + 对于指数分布,parameter通过在parameter处截断一个快速衰减的指数分布,再将其投影到边界之间的整数上,从而控制分布。准确地说,令 f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) @@ -1930,7 +1922,7 @@ f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) - 直观地说,parameter越大,越靠近min的值越容易被抽到,而越靠近max的值越不容易被抽到。parameter越接近 0,分布就越平坦(也就越均匀)。对这种分布的一个粗略近似是:范围内最靠近min的那 1% 常见值,大约会占到parameter% 的抽样次数。parameter必须严格大于 0。 + 直观地说,parameter越大,越靠近min的值越容易被抽到,而越靠近max的值越不容易被抽到。parameter越接近 0,分布就越平坦(也就越均匀)。对这种分布的一个粗略近似是:范围内出现频率最高的 1% 的值,即最靠近min的那些值,大约会占到parameter% 的抽样次数。parameter必须严格大于 0。 @@ -1942,7 +1934,7 @@ f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / (2.0 * PHI(parameter) - 1) - 则minmax(包含边界)之间的值i被抽中的概率为:f(i + 0.5) - f(i - 0.5)。直观地说,parameter越大,越靠近区间中间的值被抽到的频率越高,而越靠近minmax边界的值被抽到的频率越低。大约 67% 的值会落在区间中部1.0 / parameter这一段内,也就是均值两侧各0.5 / parameter的范围内;约 95% 的值会落在区间中部2.0 / parameter这一段内,也就是均值两侧各1.0 / parameter的范围内。例如,如果parameter为 4.0,则 67% 的值会落在区间中间四分之一(1.0 / 4.0)内,也就是从3.0 / 8.05.0 / 8.0;95% 的值会落在区间中间一半(2.0 / 4.0)内,也就是第二和第三四分位。允许的最小parameter值为 2.0。 + 则minmax(包含边界)之间的值i被抽中的概率为:f(i + 0.5) - f(i - 0.5)。直观地说,parameter越大,越靠近区间中间的值被抽到的频率越高,而越靠近minmax边界的值被抽到的频率越低。大约 67% 的值会落在区间中部1.0 / parameter这一段内,也就是均值两侧各占区间长度0.5 / parameter的范围内;约 95% 的值会落在区间中部2.0 / parameter这一段内,也就是均值两侧各占区间长度1.0 / parameter的范围内。例如,如果parameter为 4.0,则 67% 的值会落在区间中间四分之一(1.0 / 4.0)内,也就是从3.0 / 8.05.0 / 8.0;95% 的值会落在区间中间一半(2.0 / 4.0)内,也就是第二和第三四分位。允许的最小parameter值为 2.0。 @@ -1974,12 +1966,12 @@ f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / - 哈希函数hashhash_murmur2hash_fnv1a都接受一个输入值和一个可选的种子参数。 - 如果没有提供种子,则会使用:default_seed的值;除非通过命令行选项覆盖,否则该值会被随机初始化。 + Hash 函数hashhash_murmur2hash_fnv1a都接受一个输入值和一个可选的种子参数。 + 如果没有提供种子,则会使用:default_seed的值;除非通过命令行-D选项覆盖,否则该值会被随机初始化。 - permute接受一个输入值、一个大小参数以及一个可选的种子参数。它会生成范围[0, size)内整数的伪随机排列,并返回输入值在该排列中的索引。如果未指定种子,则默认使用:default_seed。与哈希函数不同,permute保证输出值中不会出现冲突或空洞。区间之外的输入值会按size取模解释。如果size不是正数,该函数会报错。permute可用于打散诸如random_zipfianrandom_exponential这类非均匀随机函数的分布,使那些更常抽到的值不再具有显而易见的相关性。例如,下面的pgbench脚本模拟了社交媒体和博客平台中一种可能的真实工作负载,其中少数账户会产生过量负载: + permute接受一个输入值、一个大小参数以及一个可选的种子参数。它会生成范围[0, size)内整数的伪随机置换,并返回输入值在该置换中的索引。所选置换由种子参数决定;如果未指定种子,则默认使用:default_seed。与 hash 函数不同,permute保证输出值中不会出现冲突或空洞。区间之外的输入值会按size取模解释。如果size不是正数,该函数会报错。permute可用于打散诸如random_zipfianrandom_exponential这类非均匀随机函数的分布,使那些更常抽到的值不再具有显而易见的相关性。例如,下面的pgbench脚本模拟了社交媒体和博客平台中一种可能的真实工作负载,其中少数账户会产生过量负载: \set size 1000000 @@ -2036,7 +2028,7 @@ END; - 每行日志文件描述一个事务。 + 日志文件的每一行描述一个事务。 它包含以下以空格分隔的字段: @@ -2355,7 +2347,7 @@ END; - 下面是使用该选项生成的示例输出: + 下面是使用这些选项生成的示例输出: pgbench --aggregate-interval=10 --time=20 --client=10 --log --rate=1000 --latency-limit=10 --failures-detailed --max-tries=10 test @@ -2436,7 +2428,7 @@ statement latencies in milliseconds and failures: 使用可串行化默认事务隔离级别的默认脚本的另一个输出示例 - (PGOPTIONS='-c default_transaction_isolation=serializable' pgbench ...): + (PGOPTIONS='-c default_transaction_isolation=serializable' pgbench ...): starting vacuum...end. transaction type: <builtin: TPC-B (sort of)> @@ -2479,7 +2471,7 @@ statement latencies in milliseconds, failures and retries: - + 失败和串行化/死锁重试 @@ -2514,12 +2506,12 @@ statement latencies in milliseconds, failures and retries: - 线程在管理其客户端时发生的错误(例如,客户端无法开始连接数据库服务器,或客户端连接数据库服务器所用的套接字已经失效)。在这种情况下,该线程的所有客户端都会停止,而其他线程继续工作;但是,如果指定了,则所有线程都会立即停止。 + 线程在管理其客户端时发生的错误(例如,客户端无法开始连接数据库服务器,或客户端连接数据库服务器所用的套接字已经失效)。在这种情况下,该线程的所有客户端都会停止,而其他线程继续工作。 - 直接客户端错误。在发生内部pgbench错误(理论上不应发生)或指定了时,它们会导致pgbench立即退出并显示相应错误消息。否则,最坏情况下只会中止失败的客户端,而其他客户端继续运行(但某些客户端错误会在不中止客户端的情况下处理并单独报告,见下文)。本节后续默认讨论的都是直接客户端错误,而不是内部pgbench错误。 + 直接客户端错误。只有在发生内部pgbench错误(理论上不应发生)时,它们才会导致pgbench立即退出并显示相应错误消息。否则,最坏情况下只会中止失败的客户端,而其他客户端继续运行(但某些客户端错误会在不中止客户端的情况下处理并单独报告,见下文)。本节后续默认讨论的都是直接客户端错误,而不是内部pgbench错误。 @@ -2537,7 +2529,7 @@ statement latencies in milliseconds, failures and retries: - 不指定选项时,事务在发生串行化或死锁错误后永远不会重试,因为其默认值为 1。可以使用无限次尝试(--max-tries=0)并配合选项,仅限制重试的最长时间。也可以使用选项,在无限次尝试的情况下限制基准测试持续时间。 + 不指定选项时,事务在发生串行化或死锁错误后永远不会重试,因为其默认值为 1。可以使用无限次尝试(--max-tries=0)并配合选项,仅限制尝试的最长总时间。也可以使用选项,在无限次尝试的情况下限制基准测试持续时间。 @@ -2558,7 +2550,7 @@ statement latencies in milliseconds, failures and retries: - 如果希望在逐事务日志、聚合日志以及主报告和逐脚本报告中按基本类型对失败进行分组,请使用选项。如果还希望按类型区分所有错误和失败(即不会重试的错误),包括超出了哪一种重试限制,以及串行化/死锁失败超出了多少,请使用选项。 + 如果希望在逐事务日志、聚合日志以及主报告和逐脚本报告中按基本类型对失败进行分组,请使用选项。如果还希望按类型区分所有错误和失败(不再重试的错误),包括超出了哪一种重试限制,以及串行化/死锁失败超出了多少,请使用选项。 @@ -2590,7 +2582,7 @@ PGOPTIONS='-c default_table_access_method=wuzza' - 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和空闲空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 + 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和无效空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 diff --git a/zh/16/ref/psql-ref.sgml b/zh/16/ref/psql-ref.sgml index 91e1496b..24e20757 100644 --- a/zh/16/ref/psql-ref.sgml +++ b/zh/16/ref/psql-ref.sgml @@ -47,7 +47,7 @@ PostgreSQL documentation - 把所有非空输入行按照它们被读入的形式打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 + 在读入时将所有非空输入行打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 all @@ -58,7 +58,7 @@ PostgreSQL documentation - 切换到非对齐输出模式(默认输出模式是对齐的)。这等效于\pset format unaligned。 + 切换到非对齐输出模式(默认输出模式是aligned)。这等效于\pset format unaligned @@ -78,10 +78,10 @@ PostgreSQL documentation - 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,直到它处理完序列中所有的选项之后终止。 + 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,而是在按顺序处理完所有选项后终止。 - command必须是一个服务器完全可解析的命令字符串(即不包含psql相关的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: + command必须是一个服务器完全可解析的命令字符串(即不包含psql专有的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: psql -c '\x' -c 'SELECT * FROM foo;' @@ -172,7 +172,7 @@ EOF - 使用separator作为非对齐输出的域分隔符。这等效于\pset fieldsep或者\f。 + 使用separator作为非对齐输出的字段分隔符。这等效于\pset fieldsep或者\f @@ -246,7 +246,7 @@ EOF - 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。 + 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展名。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。 @@ -266,7 +266,7 @@ EOF - 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息以及多种输出。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon。 + 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息和各种提示信息。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon @@ -286,7 +286,7 @@ EOF - 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户一个可以取消执行的选项。使用这个选项可以调试脚本。 + 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户,并允许取消执行。使用这个选项可以调试脚本。 @@ -296,7 +296,7 @@ EOF - 运行在单行模式中,其中新行会终止一个 SQL 命令,就像分号的作用一样。 + 运行在单行模式中,其中换行符会终止一个 SQL 命令,就像分号的作用一样。 @@ -322,7 +322,7 @@ EOF - 指定要替换HTML table标签的选项。详见\pset tableattr。 + 指定要放在HTML table标签内的选项。详见\pset tableattr @@ -343,7 +343,7 @@ EOF - 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要重置一个变量,去掉等号就行。要把一个变量置为空值,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 + 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要取消变量的设置,去掉等号就行。要把一个变量设为空字符串,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 @@ -405,7 +405,7 @@ EOF - 不读取启动文件(要么是系统范围的psqlrc文件,要么是用户的~/.psqlrc文件)。 + 不读取启动文件(既不读取系统范围的psqlrc文件,也不读取用户的~/.psqlrc文件)。 @@ -415,7 +415,7 @@ EOF - 设置非对齐输出的域分隔符为零字节。这等效于\pset fieldsep_zero。 + 设置非对齐输出的字段分隔符为零字节。这等效于\pset fieldsep_zero @@ -425,7 +425,7 @@ EOF - 设置非对齐输出的记录分隔符为零字节。例如,这对与xargs -0配合有关。这等效于\pset recordsep_zero。 + 设置非对齐输出的记录分隔符为零字节。例如,这有助于与xargs -0配合使用。这等效于\pset recordsep_zero @@ -438,7 +438,7 @@ EOF 这个选项只能与一个或多个和/或选项结合使用。 它会导致psql在第一个这样的选项之前发出一个BEGIN命令, 并在最后一个选项之后发出一个COMMIT命令,从而将所有命令包装成一个单独的事务。 - 如果任何命令失败且变量ON_ERROR_STOP被设置,那么会发送一个ROLLBACK命令。 + 如果任何命令失败且变量ON_ERROR_STOP被设置,则会改为发送一个ROLLBACK命令。 这确保要么所有命令都成功完成,要么不应用任何更改。 @@ -550,7 +550,7 @@ testdb=> 元命令 - 你输入到psql中的任何以未加引用的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 + 你输入到psql中的任何以未加引号的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 @@ -567,7 +567,7 @@ testdb=> - 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉尾随换行)会替换反引号中的文本。在反引号包围的文本内部,不会发生特殊引用或其他处理,只有一种例外:如果出现:variable_name,且variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会被适当地引用成单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于回车和换行字符在所有平台上都无法安全引用,当变量值中出现这类字符时,:'variable_name'这种形式会打印错误消息,并且不会替换变量值。 + 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉末尾的换行符)会替换反引号中的文本。在反引号包围的文本内部,不会进行特殊的引号处理或其他处理,但出现:variable_name时,如果variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会适当地加上引号,使其成为单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于无法保证在所有平台上都能对回车和换行字符安全地加引号,当变量值中出现这类字符时,:'variable_name'形式会打印错误消息,并且不会替换变量值。 @@ -579,8 +579,8 @@ testdb=> - 很多元命令作用在当前查询缓冲区上。这就是一个缓冲区而已,它保存任何已经被键入但是还没有发送到服务器执行的SQL命令文本。这将包括之前输入的行以及在该元命令同一行上出现在前面的任何文本。 - + 许多元命令作用于当前查询缓冲区。这只是一个保存已输入但尚未发送到服务器执行的 SQL 命令文本的缓冲区。其中既包括先前输入的行,也包括同一行上位于元命令之前的文本。 + @@ -591,7 +591,7 @@ testdb=> \a - 如果当前表格输出格式是不对齐,则切换为对齐;否则切换为不对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset。 + 如果当前表格输出格式是非对齐,则切换为对齐;否则切换为非对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset @@ -628,7 +628,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \c\connect [ -reuse-previous=on|off ] [ dbname [ username ] [ host ] [ port ] | conninfo ] - 建立到PostgreSQL服务器的新连接。可以使用位置语法(数据库名称、用户、主机和端口中的一个或多个)指定要使用的连接参数,也可以使用详细说明在中的conninfo连接字符串。如果没有给出参数,则使用与之前相同的参数建立新连接。 + 建立到PostgreSQL服务器的新连接。可以使用位置语法(数据库名称、用户、主机和端口中的一个或多个)指定要使用的连接参数,也可以使用conninfo连接字符串,详见。如果没有给出参数,则使用与之前相同的参数建立新连接。 @@ -644,7 +644,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g 默认情况下,参数在位置语法中被重用,但在给定conninfo字符串时不会被重用。 传递-reuse-previous=on-reuse-previous=off作为第一个参数将覆盖该默认设置。 如果参数被重用,则任何未明确指定为位置参数或在conninfo字符串中的参数将从现有连接的参数中获取。 - 一个例外是,如果使用位置语法将host设置更改为其先前值,则现有连接参数中存在的任何hostaddr设置将被删除。 + 一个例外是,如果使用位置语法更改host设置,使其不同于先前的值,则现有连接参数中存在的任何hostaddr设置将被删除。 此外,仅当用户、主机和端口设置未更改时,才会重用现有连接使用的任何密码。 当命令既不指定也不重用特定参数时,将使用libpq的默认值。 @@ -666,7 +666,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g => \c mydb myuser host.dom 6432 => \c service=foo => \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable" -=> \c -reuse-previous=on sslmode=require -- changes only sslmode +=> \c -reuse-previous=on sslmode=require -- 仅更改 sslmode => \c postgresql://tom@localhost/mydb?application_name=myapp @@ -676,11 +676,8 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \C [ title ] - 设置作为查询结果打印的任何表格的标题,或取消任何这样的标题。此命令等效于 - \pset title title。(此命令的名称源自caption, - 因为它以前仅用于设置HTML表格中的标题。) - + 设置作为查询结果打印的表的标题,或取消此类标题。该命令等价于\pset title title。(此命令的名称源自caption,因为它过去只用于设置HTML表的标题。) + @@ -688,14 +685,11 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \cd [ directory ] - 将当前工作目录更改为 - directory。如果没有参数,则切换到当前用户的主目录。关于如何确定主目录,请参见 。 - + 将当前工作目录更改为directory。如果没有参数,则切换到当前用户的主目录。 + - - 要打印当前工作目录,请使用\! pwd。 - + 要打印当前工作目录,请使用\! pwd @@ -704,14 +698,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \conninfo - - 输出当前数据库连接的信息;如果正在使用 SSL,也包括与 SSL 相关的信息。 - - - 请注意,Client User 字段显示的是连接建立时的用户,而 - Superuser 字段表示当前用户(在当前执行上下文中)是否具有超级用户权限。这两个用户通常相同,但也可能不同,例如当前用户曾通过 - SET ROLE 命令被更改。 - + 输出当前数据库连接的信息。 @@ -760,9 +747,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g - 这些操作不如以文件或程序作为数据源或目标的 SQL - COPY 命令高效,因为所有数据都必须通过客户端/服务器连接传输。对于大量数据,使用 SQL - 命令可能更合适。 + 这些操作不如以文件或程序作为数据源或目标的SQL COPY命令高效,因为所有数据都必须通过客户端/服务器连接传输。对于大量数据,使用SQL命令可能更合适。另外,由于采用这种数据转送方式,CSV模式下的\copy ... from会错误地把单独占据一行的\.数据值当作输入结束标记。 @@ -788,46 +773,24 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g ] ] ] ] - 执行当前查询缓冲区(类似于\g)并在交叉表格中显示结果。 - 查询必须返回至少三列。 - 由colV标识的输出列成为垂直标题, - 由colH标识的输出列成为水平标题。 - colD标识要在网格中显示的输出列。 - sortcolH标识水平标题的可选排序列。 - + 执行当前查询缓冲区(与\g类似),并以交叉表网格显示结果。查询必须返回至少三列。由colV标识的输出列成为纵向表头,由colH标识的输出列成为横向表头。colD标识要在网格中显示的输出列。sortcolH标识横向表头的可选排序列。 + - 每个列规范可以是列号(从1开始)或列名。列名遵循通常的SQL大小写折叠和引用规则。如果省略, - colV被视为第1列, - colH被视为第2列。 - colH必须与 - colV不同。 - 如果未指定colD,则查询结果中必须恰好有三列, - 并且既不是colV也不是 - colH的列被视为 - colD。 - + 每个列指定都可以是列号(从 1 开始)或列名。通常的 SQL 大小写折叠和加引号规则适用于列名。如果省略,colV取第 1 列,colH取第 2 列。colH必须不同于colV。如果未指定colD,查询结果必须恰好有三列,既不是colV也不是colH的那一列被用作colD。 + - 垂直标题显示为最左侧的列,包含在列colV中找到的值, - 与查询结果中的顺序相同,但删除了重复项。 - + 纵向表头显示为最左列,包含colV列中的值,其顺序与查询结果中相同,但会移除重复值。 + - 水平标题作为第一行显示,包含在列colH中找到的值,去除重复项。 - 默认情况下,这些值按照查询结果中的顺序显示。但是,如果给定可选的sortcolH参数, - 它标识一个列,其值必须是整数,colH中的值将按照相应的 - sortcolH值排序后显示在水平标题中。 - + 横向表头显示为第一行,包含colH列中的值,并移除重复值。默认情况下,它们按查询结果中的相同顺序显示。但如果给出了可选的sortcolH参数,它所标识的列的值必须是整数,而colH中的值会按照对应的sortcolH值排序后显示在横向表头中。 + - 在交叉表格中,对于每个colH列的非重复值x, - 和每个colV列的非重复值y, - 位于交点(x,y)的单元格包含查询结果行中colD列的值, - 其中colH列的值为x, - colV列的值为y。 - 如果没有这样的行,则单元格为空。如果有多个这样的行,则报告错误。 - + 在交叉表网格中,对于colH中的每个不同值xcolV中的每个不同值y,交点(x,y)处的单元格包含查询结果中colD列的值,该结果行的colH值为xcolV值为y。如果没有这样的行,单元格为空。如果存在多条这样的行,则报错。 + @@ -849,11 +812,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g - 命令形式\d+与前者相同,只是会显示更多信息:显示与表列相关的任何注释, - 表中的OID的存在,如果关系是视图,则显示视图定义,非默认的 - 复制标识设置以及 - 如果关系具有访问方法,则显示 - 访问方法名称。 + 命令形式\d+与前者相同,但会显示更多信息:表列关联的注释、表是否包含 OID、当关系为视图时的视图定义、非默认的复制标识设置,以及当关系具有访问方法时的访问方法名称。 @@ -928,9 +887,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g - - 列出与操作符族关联的操作符(参见 )。如果指定了 access-method-pattern,则只列出与名称匹配该模式的访问方法所关联的操作符族成员。如果指定了 operator-family-pattern,则只列出名称与该模式匹配的操作符族成员。如果在命令名后追加 +,则每个操作符都会连同其排序操作符族(如果它是排序操作符)以及其底层函数是否防漏一起列出。 - + 列出与操作符族关联的操作符(见)。如果指定了access-method-pattern,则只列出关联访问方法的名称匹配该模式的操作符族成员。如果指定了operator-family-pattern,则只列出名称匹配该模式的操作符族成员。如果在命令名后附加+,还会列出每个操作符的排序操作符族(如果它是一个排序操作符)。 @@ -983,9 +940,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \dC[+] [ pattern ] - - 列出类型转换。如果指定了 pattern,则只列出其源类型或目标类型与模式匹配的类型转换。如果在命令名后追加 +,则会显示每个类型转换的附加信息,包括其底层函数是否防漏,以及该类型转换的描述。 - + 列出类型转换。如果指定了pattern,则只列出源类型或目标类型匹配该模式的类型转换。如果在命令名后附加+,还会列出每个对象关联的描述。 @@ -996,7 +951,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g 显示constraintoperator classoperator familyrule和 - trigger类型对象的描述。所有其他注释可以通过相应的反斜杠命令查看这些对象类型。 + trigger类型对象的描述。其他注释可通过对应对象类型的反斜线命令查看。 \dd 显示与 @@ -1021,7 +976,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g - \ddp[ pattern ] + \ddp [ pattern ] 列出默认访问权限设置。对于每个默认权限设置已偏离内置默认值的角色(以及适用时的模式),都会显示一条记录。如果指定了 pattern,则只列出角色名或模式名与模式匹配的记录。 @@ -1056,10 +1011,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \des[+] [ pattern ] - - 列出外部服务器(助记符:external - servers)。如果指定了 pattern,则只列出名称与模式匹配的服务器。如果在命令名后追加 +,则会显示每个服务器的完整描述,包括服务器的访问权限、类型、版本、选项和描述。 - + 列出外部服务器(助记词:external servers)。如果指定了pattern,则只列出名称匹配该模式的服务器。如果使用\des+形式,则显示每个服务器的完整说明,包括服务器的访问权限、类型、版本、选项和描述。 @@ -1067,9 +1019,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \det[+] [ pattern ] - - 列出外部表(助记符:external tables)。如果指定了 pattern,则只列出表名或模式名与模式匹配的条目。如果在命令名后追加 +,则还会显示通用选项以及外部表描述。 - + 列出外部表(助记词:external tables)。如果指定了pattern,则只列出表名或模式名匹配该模式的条目。如果使用\det+形式,还会显示通用选项和外部表描述。 @@ -1077,15 +1027,10 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \deu[+] [ pattern ] - - 列出用户映射(助记符:external - users)。如果指定了 pattern,则只列出用户名与模式匹配的映射。如果在命令名后追加 +,则会显示每个映射的附加信息。 - + 列出用户映射(助记词:external users)。如果指定了pattern,则只列出用户名匹配该模式的映射。如果使用\deu+形式,还会显示每个映射的附加信息。 - - \deu+可能还会显示远程用户的用户名和密码,因此应注意不要泄露它们。 - + \deu+还可能显示远程用户的用户名和密码,因此应注意不要泄露它们。 @@ -1094,10 +1039,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \dew[+] [ pattern ] - - 列出外部数据包装器(助记符:external - wrappers)。如果指定了 pattern,则只列出名称与模式匹配的外部数据包装器。如果在命令名后追加 +,则还会显示外部数据包装器的访问权限、选项和描述。 - + 列出外部数据包装器(助记词:external wrappers)。如果指定了pattern,则只列出名称匹配该模式的外部数据包装器。如果使用\dew+形式,还会显示外部数据包装器的访问权限、选项和描述。 @@ -1108,8 +1050,8 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g 列出函数,以及它们的结果数据类型、参数数据类型和函数类型,函数类型分为 agg(聚合)、normalproceduretriggerwindow。要只显示特定类型的函数,请在命令后添加相应的字母 anptw。如果指定了 pattern,则只显示名称与模式匹配的函数。任何附加参数都是类型名模式,分别与函数第一、第二等参数的类型名匹配。(匹配到的函数可以比你指定的参数更多;若要防止这种情况,可将破折号 - 写成最后一个 arg_pattern。)默认情况下,只显示用户创建的对象;提供模式或 S - 修饰符可包括系统对象。如果在命令名后追加 +,则会显示每个函数的附加信息,包括易变性、并行安全性、所有者、安全分类、是否防漏、访问权限、语言、内部名称(仅适用于 C 和 internal 函数)以及描述。特定函数的源代码可通过 \sf 查看。 + class="parameter">pattern,则只显示名称与模式匹配的函数。任何附加参数都是类型名模式,分别与函数第一、第二等参数的类型名匹配。(匹配到的函数可以比你指定的参数更多;若要防止这种情况,可将连字符 - 写成最后一个 arg_pattern。)默认情况下,只显示用户创建的对象;提供模式或 S + 修饰符可包括系统对象。如果使用 \df+ 形式,则会显示每个函数的附加信息,包括易变性、并行安全性、所有者、安全分类、访问权限、语言、内部名称(仅适用于 C 和 internal 函数)以及描述。特定函数的源代码可通过 \sf 查看。 @@ -1118,36 +1060,28 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \dF[+] [ pattern ] - - 列出文本搜索配置。如果指定了 pattern,则只显示名称与模式匹配的配置。如果在命令名后追加 +,则会显示每个配置的完整描述,包括底层文本搜索解析器以及每种记号类型对应的词典列表。 - + 列出全文检索配置。如果指定了pattern,则只显示名称匹配该模式的配置。如果使用\dF+形式,则显示每个配置的完整说明,包括底层全文检索解析器和每种解析器词元类型的词典列表。 \dFd[+] [ pattern ] - - 列出文本搜索词典。如果指定了 pattern,则只显示名称与模式匹配的词典。如果在命令名后追加 +,则会显示每个所选词典的附加信息,包括底层文本搜索模板和选项值。 - + 列出全文检索词典。如果指定了pattern,则只显示名称匹配该模式的词典。如果使用\dFd+形式,还会显示每个选中词典的附加信息,包括底层全文检索模板和选项值。 \dFp[+] [ pattern ] - - 列出文本搜索解析器。如果指定了 pattern,则只显示名称与模式匹配的解析器。如果在命令名后追加 +,则会显示每个解析器的完整描述,包括底层函数和已识别的记号类型列表。 - + 列出全文检索解析器。如果指定了pattern,则只显示名称匹配该模式的解析器。如果使用\dFp+形式,则显示每个解析器的完整说明,包括底层函数和可识别的词元类型列表。 \dFt[+] [ pattern ] - - 列出文本搜索模板。如果指定了 pattern,则只显示名称与模式匹配的模板。如果在命令名后追加 +,则会显示每个模板的附加信息,包括底层函数名。 - + 列出全文检索模板。如果指定了pattern,则只显示名称匹配该模式的模板。如果使用\dFt+形式,还会显示每个模板的附加信息,包括底层函数名。 @@ -1155,11 +1089,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \dg[S+] [ pattern ] - - 列出数据库角色。(由于 usersgroups 的概念已经统一为 roles,此命令现在等同于 - \du。)默认情况下,只显示用户创建的角色;提供 - S 修饰符可包括系统角色。如果指定了 pattern,则只列出名称与模式匹配的角色。如果在命令名后追加 +,则会显示每个角色的附加信息;目前这会增加每个角色的注释。 - + 列出数据库角色。(由于用户的概念已经统一为角色,此命令现在等价于\du。)默认只显示用户创建的角色;提供S修饰符可包含系统角色。如果指定了pattern,则只列出名称匹配该模式的角色。如果使用\dg+形式,还会显示每个角色的附加信息;目前会增加每个角色的注释。 @@ -1200,7 +1130,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \do[S+] [ pattern [ arg_pattern [ arg_pattern ] ] ] - 列出操作符及其操作数类型和结果类型。如果指定了 pattern,则只列出名称与模式匹配的操作符。如果指定了一个 arg_pattern,则只列出其右参数类型名称与该模式匹配的前缀操作符。如果指定了两个 arg_pattern,则只列出参数类型名称与这些模式匹配的二元操作符。(对于一元操作符未使用的参数,也可以写成 -。)默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 +,则会显示每个操作符的附加信息,包括底层函数名以及它是否防漏。 + 列出操作符及其操作数类型和结果类型。如果指定了 pattern,则只列出名称与模式匹配的操作符。如果指定了一个 arg_pattern,则只列出其右参数类型名称与该模式匹配的前缀操作符。如果指定了两个 arg_pattern,则只列出参数类型名称与这些模式匹配的二元操作符。(对于一元操作符未使用的参数,也可以写成 -。)默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 +,则会显示每个操作符的附加信息,目前仅包括底层函数名。 @@ -1235,34 +1165,20 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \dP[itn+] [ pattern ] - - 列出分区关系。 - 如果pattern被指定, - 则只列出名称与模式匹配的条目。 - 修饰符t(表)和i(索引) - 可以附加到命令,过滤要列出的关系类型。默认情况下,列出分区表和索引。 - + 列出分区关系。如果指定了pattern,则只列出名称匹配该模式的条目。可以在命令后附加修饰符t(表)和i(索引),筛选要列出的关系类型。默认会列出分区表和分区索引。 - - 如果使用修饰符nnested), - 或指定了模式,则将包括非根分区关系,并显示一个列,显示每个 - 分区关系的父级。 - + 如果使用了修饰符nnested),或指定了模式,则会包含非根分区关系,并显示一列,列出每个分区关系的父关系。 - -如果在命令名后追加 +,则还会显示每个关系分区大小的总和以及关系描述。如果 n+ 组合使用,则会显示两个大小:一个包括直接附加的叶分区的总大小,另一个显示包括间接附加子分区在内的所有分区总大小。 - + 如果在命令名后附加+,还会显示每个关系的各个分区的大小之和,以及该关系的描述。如果将n+结合使用,则显示两个大小:一个是直接附加的叶子分区的总大小,另一个是所有分区的总大小,包括间接附加的子分区。 - \drds[ role-pattern [ database-pattern ] ] + \drds [ role-pattern [ database-pattern ] ] - 列出已定义的配置设置。这些设置可以是特定于角色、特定于数据库,或者两者兼有。role-pattern 和 - database-pattern 分别用于选择要列出的特定角色和数据库。如果省略,或者指定了 - *,则会列出所有设置,包括那些未指定角色或数据库的设置。 + 列出已定义的配置设置。这些设置可以特定于角色、特定于数据库,或同时特定于两者。role-patterndatabase-pattern分别用于选择要列出的角色和数据库。省略某个模式参数或将其指定为*时,不会按该参数筛选,还会分别包含不特定于角色或不特定于数据库的设置。 ALTER ROLE和 @@ -1283,7 +1199,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g 默认情况下,只显示授予用户创建角色的成员身份;提供 - S 修饰符可包括系统角色。如果指定了 pattern,则只列出名称与模式匹配的角色。 + S 修饰符可包括系统角色。如果指定了 pattern,则只列出授予名称与模式匹配的角色的成员身份。 @@ -1310,7 +1226,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \dT[S+] [ pattern ] - 列出数据类型。如果指定了 pattern,则只列出名称与模式匹配的类型。如果在命令名后追加 +,则每个类型都会连同其内部名称和大小一起列出;对于 enum 类型,还会显示其允许值以及相关权限。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 + 列出数据类型。如果指定了 pattern,则只列出名称与模式匹配的类型。如果在命令名后追加 +,则每个类型都会连同其内部名称、大小以及相关权限一起列出;对于 enum 类型,还会显示其允许值。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 @@ -1318,25 +1234,19 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \du[S+] [ pattern ] - - 列出数据库角色。(由于 usersgroups 的概念已经统一为 roles,此命令现在等同于 - \dg。)默认情况下,只显示用户创建的角色;提供 - S 修饰符可包括系统角色。如果指定了 pattern,则只列出名称与模式匹配的角色。如果在命令名后追加 +,则会显示每个角色的附加信息;目前这会增加每个角色的注释。 - + 列出数据库角色。(由于用户的概念已经统一为角色,此命令现在等价于\dg。)默认只显示用户创建的角色;提供S修饰符可包含系统角色。如果指定了pattern,则只列出名称匹配该模式的角色。如果使用\du+形式,还会显示每个角色的附加信息;目前会增加每个角色的注释。 \dx[+] [ pattern ] - - 列出已安装的扩展。如果指定了 pattern,则只列出名称与模式匹配的扩展。如果在命令名后追加 +,则会列出属于每个匹配扩展的全部对象。 - + 列出已安装的扩展。如果指定了pattern,则只列出名称匹配该模式的扩展。如果使用\dx+形式,则列出属于每个匹配扩展的所有对象。 - \dX[ pattern ] + \dX [ pattern ] 列出扩展统计信息。如果指定了 pattern,则只列出名称与模式匹配的扩展统计信息。 @@ -1359,7 +1269,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g - \e\edit filename 行号 + \e\edit filename line_number @@ -1371,7 +1281,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g 如果编辑文件或上一个查询后在未修改文件的情况下退出编辑器,则查询缓冲区将被清除。 否则,查询缓冲区的新内容将根据psql的正常规则重新解析, - 将整个缓冲区视为单行。任何完整的查询将立即执行;也就是说,如果查询缓冲区包含或以分号结尾, + 将整个缓冲区视为单行。任何完整的查询将立即执行;也就是说,如果查询缓冲区包含分号或以分号结尾, 则执行并从查询缓冲区中删除到该点的所有内容。查询缓冲区中剩余的内容将重新显示。 输入分号或\g发送它,或输入\r通过清除查询缓冲区来取消。 @@ -1383,7 +1293,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g 如果指定了行号,psql将光标定位在文件或查询缓冲区的指定行上。 - 请注意,如果给出一个全是数字的参数, + 请注意,如果只给出一个全是数字的参数, psql会假定它是一个行号,而不是文件名。 @@ -1398,14 +1308,10 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \echo text [ ... ] - - 将求值后的参数打印到标准输出,用空格分隔,并在末尾加上换行符。这对于在脚本输出中穿插信息很有用。例如: - + 将求值后的参数打印到标准输出,用空格分隔,并在末尾加上换行符。这对于在脚本输出中穿插信息很有用。例如: => \echo `date` Tue Oct 26 21:40:57 CEST 1999 - - 如果第一个参数是未引用的-n,则不会写入尾随的换行符(也不会写入第一个参数)。 - +如果第一个参数是未加引号的-n,则不会写入尾随的换行符(也不会写入第一个参数)。 @@ -1513,7 +1419,7 @@ Tue Oct 26 21:40:57 CEST 1999 - 设置未对齐查询输出的字段分隔符。默认值是竖线(|)。 + 设置非对齐查询输出的字段分隔符。默认值是竖线(|)。 它等同于\pset fieldsep @@ -1524,25 +1430,17 @@ Tue Oct 26 21:40:57 CEST 1999 \g [ (option=value [...]) ] [ filename ] \g [ (option=value [...]) ] [ |command ] - - 将当前查询缓冲区发送到服务器以执行。 - - - 如果在\g后面出现括号,则括号中包围着一个空格分隔的option=value格式选项子句的列表,这些选项子句的解释方式与\psetoptionvalue命令相同,但仅在此查询的持续时间内生效。在此列表中,不允许在=符号周围有空格,但在选项子句之间需要空格。 - 如果省略了=value,则命名的option将以与\psetoption没有显式value时相同的方式更改。 - - - 如果提供了一个filename|command参数, - 查询的输出将被写入到指定的文件或通过给定的shell命令进行传输,而不是像通常那样显示出来。只有在查询成功返回零个或多个元组时,文件或命令才会被写入,而不是在查询失败或是非数据返回的SQL命令时。 + 将当前查询缓冲区发送给服务器执行。 + 如果在\g后面出现括号,则括号中是用空格分隔的option=value格式选项子句列表。这些子句的解释方式与\pset + option + value命令相同,但仅在此查询执行期间生效。在此列表中,=符号周围不允许有空格,但选项子句之间必须有空格。如果=value被省略,则指定的option会按以下命令的方式更改:\pset option,其中不显式指定value + 如果给出了filename|command参数,查询输出就会写入指定文件,或通过管道传给指定的 shell 命令,而不是照常显示。只有当查询成功返回零个或多个元组时,才会向文件或命令写入;如果查询失败,或执行的是不返回数据的 SQL 命令,则不会写入。 如果当前查询缓冲区为空,则最近发送的查询将被重新执行。除此之外,没有任何参数的\g基本上等同于一个分号。 带有参数的\g提供了一个一次性替代\o命令的选择,并且还允许一次性调整通常由\pset设置的输出格式选项。 - - 当最后一个参数以|开头时,整行剩余部分被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分将被直接传递给shell。 - + 当最后一个参数以|开头时,该行剩余的全部内容都会被视为要执行的command,其中既不进行变量插值,也不进行反引号扩展。该行剩余部分会直接按字面传给 shell。 @@ -1551,14 +1449,9 @@ Tue Oct 26 21:40:57 CEST 1999 \gdesc - - 显示当前查询缓冲区结果的描述(即列名和数据类型)。 - 查询不会实际执行;但是,如果包含某种语法错误,该错误将以正常方式报告。 - + 显示当前查询缓冲区中查询结果的描述(即列名和数据类型)。查询并不会实际执行;不过,如果其中存在语法错误,会按通常的方式报告。 - - 如果当前查询缓冲区为空,则描述最近发送的查询。 - + 如果当前查询缓冲区为空,则改为描述最近发送的查询。 @@ -1613,37 +1506,23 @@ CREATE INDEX \gset [ prefix ] - - 将当前查询缓冲区发送到服务器,并将查询的输出存储到psql变量中 - (参见下面的)。 - 要执行的查询必须返回一行。该行的每一列都存储在一个单独的变量中,变量名与列名相同。例如: - + 将当前查询缓冲区发送给服务器,并将查询输出存入 psql 变量(参见下面的)。要执行的查询必须恰好返回一行。该行的每一列分别存入一个变量,变量名与列名相同。例如: => SELECT 'hello' AS var1, 10 AS var2 -> \gset => \echo :var1 :var2 hello 10 - - 如果指定了一个prefix, - 该字符串将被添加到查询的列名前,以创建要使用的变量名: - + 如果指定了prefix,则会将该字符串加到查询的列名前面,以构成要使用的变量名: => SELECT 'hello' AS var1, 10 AS var2 -> \gset result_ => \echo :result_var1 :result_var2 hello 10 - - 如果列的结果为NULL,则相应的变量将被取消设置,而不是被设置。 - - - 如果查询失败或者没有返回一行结果, - 则不会改变任何变量。 - - - 如果当前查询缓冲区为空,则重新执行最近发送的查询。 - + 如果某一列的结果为 NULL,则取消设置对应的变量,而不是设置它。 + 如果查询失败或没有恰好返回一行,则不会更改任何变量。 + 如果当前查询缓冲区为空,则改为重新执行最近发送的查询。 @@ -1666,7 +1545,7 @@ hello 10 给出指定SQL命令的语法帮助。如果未指定command, 则psql将列出所有可用语法帮助的命令。如果command是星号 - (*),则显示所有SQL命令的语法帮助。 + (*),则显示所有SQL命令的语法帮助。 @@ -1687,9 +1566,7 @@ hello 10 \H\html - 打开HTML查询输出格式。如果HTML格式已经打开, - 则切换回默认的对齐文本格式。此命令用于兼容性和便利性,但请参阅\pset - 有关设置其他输出选项。 + 打开HTML查询输出格式。如果HTML格式已经打开,则切换回默认的对齐文本格式。此命令是为兼容性和便利性而保留的;设置其他输出选项的方法见\pset @@ -1701,13 +1578,10 @@ hello 10 - 从文件filename中读取输入,并将其执行为 - 好像它是在键盘上键入的一样。 + 从文件filename中读取输入,并像在键盘上输入一样执行它。 - 如果filename- - (连字符),那么标准输入将被读取,直到EOF指示或\q元命令。 - 这可用于将交互式输入与文件输入交错使用。请注意,仅当在最外层级别处于活动状态时,Readline行为才会被使用。 + 如果filename-(连字符),则从标准输入读取,直到遇到 EOF 指示或\q元命令。这可用于将交互式输入与文件输入交错使用。请注意,只有在最外层启用了 Readline,此处才会使用 Readline 功能。 @@ -1727,42 +1601,26 @@ hello 10 这组命令实现了可嵌套的条件块。条件块必须以\if开始,并以\endif结束。 在两者之间可以有任意数量的\elif子句,后面可以选择性地跟着一个\else子句。 - 在形成条件块的命令之间通常会出现普通查询和其他类型的反斜杠命令。 + 在形成条件块的命令之间通常会出现普通查询和其他类型的反斜线命令。 - \if\elif命令读取它们的参数,并将其作为布尔表达式进行评估。 - 如果表达式为true,则处理将继续进行;否则,直到达到匹配的\elif、 - \else\endif为止,将跳过行。一旦\if或 - \elif测试成功,同一块中后续\elif命令的参数不会被评估,而是被视为false。 - 在\else之后的行只有在没有早期匹配的\if\elif成功时才会被处理。 + \if\elif命令读取其参数,并将其作为布尔表达式求值。如果表达式的值为true,则正常继续处理;否则,跳过后续行,直到遇到匹配的\elif\else\endif。一旦\if\elif测试成功,同一块中后续\elif命令的参数就不再求值,而是被视为假。只有前面所有匹配的\if\elif测试都未成功时,才会处理\else后面的行。 - expression参数 - 是\if\elif命令的参数, - 受变量插值和反引号扩展的影响,就像任何其他反斜杠命令参数一样。 - 之后,它被评估为一个开/关选项变量的值。因此,有效值是以下任何一个不 - 含糊的不区分大小写匹配之一: - true, false, 1, - 0, on, off, - yes, no。例如, - t, TtR - 都将被视为true。 + 与其他反斜线命令的参数一样,\if\elif命令的expression参数会经过变量插值和反引号扩展。随后,按开/关选项变量值的规则对结果求值。因此,有效值是以下值的不区分大小写且无歧义的匹配:truefalse10onoffyesno。例如,tTtR都会被视为true - 不正确评估为真或假的表达式将生成警告,并被视为假。 + 不能正确求值为真或假的表达式会产生警告,并被视为假。 - 被跳过的行会被正常解析以识别查询和反斜杠命令,但查询不会发送到服务器, - 而且除了条件命令(\if\elif, - \else\endif)之外的反斜杠命令会被忽略。 + 被跳过的行会被正常解析以识别查询和反斜线命令,但查询不会发送到服务器, + 而且除了条件命令(\if\elif、 + \else\endif)之外的反斜线命令会被忽略。 仅检查跳过行中条件命令的有效嵌套。跳过行中的变量引用不会被展开, 也不会执行反引号扩展。 - 所有给定条件块的反斜杠命令必须出现在同一个源文件中。如果在主输入文件或一个 - \include的文件上达到文件结束之前,所有本地 - \if块都没有关闭, - 那么psql将会引发错误。 + 同一个条件块的所有反斜线命令必须出现在同一个源文件中。如果主输入文件或通过\include引入的文件到达 EOF 时,仍有本地\if块未关闭,psql就会报错。 下面是一个示例: @@ -1796,17 +1654,13 @@ SELECT \ir\include_relative filename - - \ir命令类似于\i,但是解析相对文件名的方式不同。 - 在交互模式下执行时,这两个命令的行为是相同的。然而,在脚本中调用时, - \ir会将文件名解释为相对于脚本所在目录,而不是当前工作目录。 - + \ir命令与\i相似,但解析相对文件名的方式不同。在交互模式下执行时,这两个命令的行为相同。不过,在脚本中调用时,\ir会相对于脚本所在的目录来解释文件名,而不是相对于当前工作目录。 - \l[+] or \list[+] [ pattern ] + \l[+]\list[+] [ pattern ] 列出服务器中的数据库,并显示其名称、所有者、字符集编码和访问权限。如果指定了 pattern,则只列出名称与模式匹配的数据库。如果在命令名后追加 +,则还会显示数据库大小、默认表空间和描述。当前用户对其拥有 CONNECT 权限的数据库可以显示大小信息;如果当前用户是超级用户或具有 pg_read_all_stats 角色的权限,也可以显示大小信息。 @@ -1823,7 +1677,7 @@ SELECT 从数据库中读取具有OIDloid的大对象,并将其写入filename。请注意,这与服务器函数 - lo_export略有不同,后者使用数据库服务器运行的用户权限, + lo_export略有不同,后者使用运行数据库服务器的用户的权限, 并在服务器的文件系统上操作。 @@ -1839,14 +1693,10 @@ SELECT \lo_import filename [ comment ] - - 将文件存储到一个PostgreSQL大对象中。可选地,它将给定的注释与对象关联起来。例如: - + 将文件存储到一个PostgreSQL大对象中。可选地,它将给定的注释与对象关联起来。例如: foo=> \lo_import '/home/peter/pictures/photo.xcf' 'a picture of me' lo_import 152801 - - 响应表明大对象收到了对象ID 152801,这个ID可以用来在将来访问新创建的大对象。为了可读性起见,建议始终将一个可读的注释与每个对象关联起来。OID和注释都可以用\lo_list命令查看。 - +响应表明大对象获得了对象 ID 152801,这个 ID 可以用来在将来访问新创建的大对象。为便于阅读,建议始终为每个对象关联一条便于人阅读的注释。查看 OID 和注释时,可以使用\lo_list命令。 请注意,此命令与服务器端的lo_import略有不同,因为它作为本地用户在本地文件系统上操作,而不是服务器的用户和文件系统。 @@ -1869,7 +1719,7 @@ lo_import 152801 - 从数据库中删除具有OIDloid的大对象。 + 从数据库中删除OIDloid的大对象。 @@ -1885,19 +1735,12 @@ lo_import 152801 \o\out [ filename ] \o\out [ |command ] - - 安排将未来的查询结果保存到文件filename, - 或将未来的结果传输到shell命令command。 - 如果未指定参数,则查询输出重置为标准输出。 - + 将后续查询结果保存到文件filename,或通过管道传给 shell 命令command。如果没有指定参数,查询输出将恢复为标准输出。 - - 如果参数以|开头,则整个剩余部分的行被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分的行会被直接传递给shell。 - + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 - 查询结果包括从数据库服务器获取的所有表、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 + 查询结果包括从数据库服务器获取的所有表格、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 @@ -1951,17 +1794,9 @@ lo_import 152801 \pset [ option [ value ] ] - - 这个命令设置影响查询结果表输出的选项。 - option - 指示要设置哪个选项。根据所选选项,value的语义会有所不同。 - 对于某些选项,省略value会导致该选项被切换或取消设置,具体描述在特定选项下。 - 如果没有提到这样的行为,那么省略value只会显示当前设置。 - + 这个命令设置影响查询结果表输出的选项。option指定要设置哪个选项。value的含义取决于所选的选项。对于某些选项,省略value会切换或取消设置该选项,具体见各选项的说明。如果没有提及这类行为,那么省略value只会显示当前设置。 - - \pset不带任何参数时,显示所有打印选项的当前状态。 - + 不带任何参数的\pset会显示所有打印选项的当前状态。 可调整打印选项有: @@ -1969,12 +1804,7 @@ lo_import 152801 border - - value必须是一个数字。一般来说,数字越高,表格的边框和线条就越多, - 但具体细节取决于特定格式。在HTML格式中,这将直接转换为border=...属性。 - 在大多数其他格式中,只有值0(无边框)、1(内部分隔线)和2(表框)有意义,值大于2将被视为border = 2。 - latexlatex-longtable格式还允许值为3,以在数据行之间添加分隔线。 - + value必须是数字。一般来说,数字越大,表格的边框和分隔线就越多,但细节取决于具体格式。在HTML格式中,它会直接转换为border=...属性。在大多数其他格式中,只有值 0(无边框)、1(内部分隔线)和 2(表格外框)有意义,大于 2 的值会与border = 2作相同处理。latexlatex-longtable格式还允许使用值 3,以在数据行之间添加分隔线。 @@ -1987,7 +1817,7 @@ lo_import 152801 零(默认值)会导致目标宽度由环境变量COLUMNS控制,或者如果未设置 COLUMNS则由检测到的屏幕宽度控制。 另外,如果columns为零,则wrapped格式仅影响屏幕输出。 - 如果columns为非零,则文件和管道输出也会被包装到该宽度。 + 如果columns为非零,则文件和管道输出也会按该宽度折行。 @@ -2006,63 +1836,35 @@ lo_import 152801 expanded(或x - - 如果指定了value,它必须是onoff, - 这将启用或禁用扩展模式,或者是auto。 - 如果省略了value,则命令在开启和关闭设置之间切换。 - 启用扩展模式时,查询结果以两列显示,左侧是列名,右侧是数据。 - 如果数据在正常的水平模式下无法完全显示在屏幕上,则此模式很有用。 - 在自动设置中,当查询输出具有多列且宽度超过屏幕时,将使用扩展模式;否则,将使用常规模式。 - 自动设置仅在对齐和换行格式中有效。在其他格式中,它始终表现为扩展模式已关闭。 - + 如果指定了value,它必须是onoff(分别启用或禁用扩展模式),或者是auto。如果省略value,该命令会在开启和关闭设置之间切换。启用扩展模式时,查询结果以两列显示,左侧为列名,右侧为数据。如果数据在通常的横向模式下无法适应屏幕,这种模式就很有用。在自动设置下,当查询输出包含多列且宽度超过屏幕时,会使用扩展模式;否则使用常规模式。自动设置只在对齐和折行格式中有效。在其他格式中,它的行为始终与关闭扩展模式相同。 fieldsep - - 指定在未对齐的输出格式中使用的字段分隔符。这样,可以创建例如制表符分隔的输出, - 其他程序可能更喜欢。要将制表符设置为字段分隔符,请键入 - \pset fieldsep '\t'。默认字段分隔符是 - '|'(一根竖线)。 - + 指定非对齐输出格式使用的字段分隔符。这样可以创建例如制表符分隔的输出,这可能更符合其他程序的需要。要将制表符设置为字段分隔符,请输入\pset fieldsep '\t'。默认字段分隔符是'|'(竖线)。 fieldsep_zero - - 将未对齐输出格式中使用的字段分隔符设置为零字节。 - + 将非对齐输出格式使用的字段分隔符设置为零字节。 footer - - 如果指定了value, - 它必须是onoff, - 这将启用或禁用表格页脚的显示 - ((n 行)计数)。 - 如果省略了value, - 命令将切换页脚的显示或隐藏。 - + 如果指定了value,它必须是onoff,分别启用或禁用表格页脚((n rows)计数)的显示。如果省略value,该命令会切换页脚显示的开关状态。 format - - 设置输出格式为alignedasciidoc、 - csvhtmllatex、 - latex-longtabletroff-ms、 - unalignedwrapped。 - 允许使用唯一缩写。 - + 设置输出格式为alignedasciidoccsvhtmllatexlatex-longtabletroff-msunalignedwrapped。允许使用唯一缩写。 aligned格式是标准的、适合人阅读且排版整齐的文本输出;这是默认格式。 @@ -2075,12 +1877,12 @@ lo_import 152801 按逗号分隔的列值输出,并应用 RFC 4180 - 中描述的引用规则。 + 中描述的加引号规则。 此输出与服务器的CSV格式的 COPY命令兼容。 - 生成包含列名的标题行,除非 + 生成包含列名的表头行,除非 tuples_only参数设置为 - on。不打印标题和页脚。 + on。不打印表格标题和页脚。 每行以系统相关的行结束字符结束, 对于类Unix系统通常是单个换行符(\n), 对于Microsoft Windows则是回车和换行序列 @@ -2088,17 +1890,14 @@ lo_import 152801 可以用\pset csv_fieldsep选择逗号以外的字段分隔字符。 - wrapped格式类似于aligned,但会将宽数据值跨行包装,以使输出适合目标列宽。 - 目标宽度由columns选项下描述的方式确定。请注意,psql不会尝试包装列标题; - 因此,如果列标题所需的总宽度超过目标宽度,则wrapped格式的行为与aligned相同。 - + wrapped格式与aligned相似,但会将较宽的数据值折成多行,使输出适应目标列宽。目标宽度的确定方式见columns选项的说明。请注意,psql不会尝试对列标题折行;因此,如果列标题所需的总宽度超过目标宽度,wrapped格式的行为就与aligned相同。 - asciidochtml, - latexlatex-longtable,和 + asciidochtml、 + latexlatex-longtabletroff-ms格式生成的表格旨在包含在使用相应标记语言的文档中。 它们不是完整的文档!这在HTML中可能不是必需的,但在 - LaTeX中,则必须有一个完整的文档包装器。 + LaTeX中,则必须有一个完整文档的外层结构。 latex格式使用LaTeXtabular 环境。 latex-longtable格式需要LaTeX @@ -2118,25 +1917,19 @@ lo_import 152801 - ascii样式使用普通的ASCII字符。数据中的换行使用右边边缘的+符号显示。 - 当wrapped格式将数据从一行换到下一行而没有换行符时,在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 + ascii样式使用普通的ASCII字符。数据中的换行符以右边缘的+符号表示。当wrapped格式在没有换行符的位置把数据折到下一行时,会在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 - old-ascii样式使用普通的ASCII字符,使用在PostgreSQL 8.4及更早版本中使用的格式样式。 - 数据中的换行符使用:符号代替左侧列分隔符显示。 - 当数据从一行换行到下一行而没有换行符时,使用;符号代替左侧列分隔符。 + old-ascii样式使用普通的ASCII字符,采用PostgreSQL 8.4 及更早版本的格式样式。数据中的换行符以替代左侧列分隔符的:符号表示。当数据在没有换行符的位置折到下一行时,则用;符号替代左侧列分隔符。 - unicode样式使用Unicode绘图字符。数据中的换行使用右边距中的回车符号显示。 - 当数据从一行换行到下一行而没有换行符时,第一行的右边距显示省略号符号, - 接着在下一行的左边距再次显示省略号符号。 + unicode样式使用 Unicode 框线绘制字符。数据中的换行符以右边缘的回车符号表示。当数据在没有换行符的位置折到下一行时,会在第一行的右边缘显示省略号符号,并在下一行的左边缘再次显示。 - 当border设置大于零时,linestyle选项还确定了用哪些字符绘制边框线。 - 普通的ASCII字符在任何地方都有效,但在识别Unicode字符的显示器上看起来更好。 + 当border设置大于零时,linestyle选项还决定用哪些字符绘制边框线。普通的ASCII字符在任何环境中都可用,但在支持 Unicode 的显示设备上,Unicode 字符更美观。 @@ -2144,24 +1937,14 @@ lo_import 152801 null - - 设置要打印在空值位置的字符串。默认情况下是不打印任何内容,这很容易被误解为空字符串。 - 例如,一个人可能更喜欢\pset null '(null)'。 - + 设置用于代替空值打印的字符串。默认不打印任何内容,这很容易被误认为空字符串。例如,你可能更喜欢使用\pset null '(null)' numericlocale - - 如果指定了value, - 它必须是onoff, - 这将启用或禁用显示一个特定于区域设置的字符, - 用于将小数点左侧的数字分组。如果省略了 - value, - 命令在常规和特定于区域设置的数字输出之间切换。 - + 如果指定了value,它必须是onoff,分别启用或禁用使用区域设置特定的字符来分隔小数点左侧的数字组。如果省略value,该命令会在常规数字输出和区域设置特定的数字输出之间切换。 @@ -2169,17 +1952,11 @@ lo_import 152801 pager - 控制查询和psql帮助输出时使用分页程序的方式。 - 当pager选项为off时,不使用分页程序。 - 当pager选项为on时,在适当的情况下使用分页程序,即当输出到终端且不适合在屏幕上显示时。 - pager选项也可以设置为always,这会导致分页程序用于所有终端输出,无论是否适合在屏幕上显示。 - \pset pager 不带value时,会在开启和关闭分页器之间切换。 + 控制查询和psql帮助输出是否使用分页器程序。当pager选项为off时,不使用分页器程序。当pager选项为on时,会在适当时使用分页器,即输出目标为终端且内容无法在屏幕上完整显示时。pager选项也可以设为always,这样所有终端输出都会使用分页器,无论内容是否能在屏幕上完整显示。不带value\pset pager会切换分页器的使用状态。 - 如果环境变量PSQL_PAGERPAGER被设置, - 输出将被分页传输到指定的程序。否则,将使用一个平台相关的默认程序 - (例如more)。 + 如果设置了环境变量PSQL_PAGERPAGER,需要分页的输出会通过管道传给指定程序。否则,使用与平台有关的默认程序(如more)。 @@ -2194,94 +1971,64 @@ lo_import 152801 pager_min_lines - - 如果pager_min_lines设置为大于页面高度的数字, - 则除非至少有这么多行的输出要显示,否则不会调用分页程序。默认设置为0。 - + 如果将pager_min_lines设置为大于页面高度的数字,那么只有待显示的输出至少达到这么多行时,才会调用分页器程序。默认设置为 0。 recordsep - - 指定在未对齐的输出格式中使用的记录(行)分隔符。默认为换行符。 - + 指定非对齐输出格式使用的记录(行)分隔符。默认为换行符。 recordsep_zero - - 设置未对齐输出格式中使用的记录分隔符为零字节。 - + 将非对齐输出格式使用的记录分隔符设置为零字节。 tableattr(或T - - 在HTML格式中,这指定要放置在table标签内的属性。 - 这可能是cellpaddingbgcolor等。 - 请注意,这里通常不需要指定border,因为它已经由\pset border处理。 - 如果没有给出value,则取消表格属性。 - - - 在latex-longtable格式中,这控制了包含左对齐数据类型的每列的比例宽度。 - 它被指定为一个以空格分隔的值列表,例如,'0.2 0.2 0.6'。 - 未指定输出列使用最后指定的值。 - + HTML格式中,这指定要放在table标签内的属性,例如cellpaddingbgcolor。请注意,你可能不需要在这里指定border,因为\pset border已经负责处理它。如果没有给出value,则取消设置表格属性。 + latex-longtable格式中,这控制每个包含左对齐数据类型的列的宽度比例。它以空白分隔的值列表指定,例如'0.2 0.2 0.6'。未指定的输出列使用最后指定的值。 - title(或者C + title(或C - - 设置后续打印的任何表的标题。这可以用来为输出提供说明性标签。 - 如果没有给出value,则标题将被取消设置。 - + 设置随后打印的所有表格的标题。这可以为输出提供描述性标签。如果没有给出value,则取消设置标题。 tuples_only(或t - - 如果指定了value,它必须是onoff, - 这将启用或禁用仅元组模式。如果省略了value, - 命令将在常规输出和仅元组输出之间切换。常规输出包括额外信息,如列标题、标题和各种页脚。 - 在仅元组模式下,只显示实际的表数据。 - + 如果指定了value,它必须是onoff,分别启用或禁用仅元组模式。如果省略value,该命令会在常规输出和仅元组输出之间切换。常规输出包含列标题、表格标题和各种页脚等附加信息。在仅元组模式下,只显示实际的表格数据。 unicode_border_linestyle - - 设置unicode线条样式的边框绘制样式为singledouble之一。 - + unicode线条样式的边框绘制样式设置为singledouble unicode_column_linestyle - - 设置unicode线条样式的列绘制样式为singledouble之一。 - + unicode线条样式的列分隔线绘制样式设置为singledouble unicode_header_linestyle - - 设置unicode线条样式的标题绘制样式为singledouble之一。 - + unicode线条样式的表头分隔线绘制样式设置为singledouble @@ -2289,35 +2036,33 @@ lo_import 152801 xheader_width - 将扩展输出的标题最大宽度设置为以下之一: + 将扩展输出的表头最大宽度设置为以下之一: full(默认值)、 columnpage整数值 - full:扩展标题不截断,其宽度与最宽的输出行相同。 + full:扩展表头不截断,其宽度与最宽的输出行相同。 - column:将标题行截断为第一列的宽度。 + column:将表头行截断为第一列的宽度。 - page:将标题行截断为终端宽度。 + page:将表头行截断为终端宽度。 - 整数值:指定标题行的确切最大宽度。 + 整数值:指定表头行的确切最大宽度。 - - 这些不同格式的示例可以在下面的中看到。 - + 这些不同格式的外观示例可参见下面的 @@ -2334,10 +2079,7 @@ lo_import 152801 \q\quit - - 退出psql程序。 - 在脚本文件中,只有该脚本的执行被终止。 - + 退出psql程序。在脚本文件中,只会终止该脚本的执行。 @@ -2346,7 +2088,7 @@ lo_import 152801 \qecho text [ ... ] - 这个命令与\echo命令相同,只是输出将被写入查询输出通道,由\o设置。 + 这个命令与\echo相同,只是输出会写入由\o设置的查询输出通道。 @@ -2355,9 +2097,7 @@ lo_import 152801 \r\reset - - 重置(清除)查询缓冲区。 - + 重置(清空)查询缓冲区。 @@ -2444,14 +2184,9 @@ testdb=> \setenv LESS -imx4F 定义将打印到当前查询输出通道,由\o设置。 - - 目标函数可以仅通过名称指定,也可以通过名称和参数指定,例如foo(integer, text)。 - 如果有多个同名函数,则必须给出参数类型。 - + 目标函数可以只用名称指定,也可以同时给出名称和参数,例如foo(integer, text)。如果存在多个同名函数,就必须给出参数类型。 - - 如果在命令名称后添加+,则输出的行将被编号,函数体的第一行将被标记为第1行。 - + 如果在命令名后附加+,输出行会带上行号,函数体的第一行编号为 1。 与大多数其他元命令不同,整个行的剩余部分始终被视为\sf的参数, @@ -2466,8 +2201,7 @@ testdb=> \setenv LESS -imx4F - 这个命令获取并显示指定视图的定义,以CREATE OR REPLACE VIEW命令的形式。 - 定义将打印到当前查询输出通道,由\o设置。 + 这个命令获取指定视图的定义,并以CREATE OR REPLACE VIEW命令的形式显示。定义会打印到由\o设置的当前查询输出通道。 @@ -2486,10 +2220,7 @@ testdb=> \setenv LESS -imx4F \t - - 切换显示输出列名标题和行数页脚。此命令等效于\pset tuples_only, - 仅为方便起见提供。 - + 切换输出中的列名标题和行数页脚的显示状态。这个命令等价于\pset tuples_only,提供它是为了使用方便。 @@ -2497,10 +2228,7 @@ testdb=> \setenv LESS -imx4F \T table_options - - 指定在table标签中放置的属性,在HTML输出格式中。 - 该命令等效于\pset tableattr table_options。 - + 指定在HTML输出格式中放在table标签内的属性。这个命令等价于\pset tableattr table_options @@ -2508,10 +2236,7 @@ testdb=> \setenv LESS -imx4F \timing [ on | off ] - - 使用参数,打开或关闭显示每个SQL语句执行时间的功能。没有参数时,切换显示开关。 - 显示的时间单位为毫秒;超过1秒的时间间隔也以分钟:秒的格式显示,如有必要还会显示小时和天。 - + 带参数时,开启或关闭每条 SQL 语句执行耗时的显示。不带参数时,切换显示的开关状态。耗时以毫秒显示;超过 1 秒的时间间隔还会以分钟:秒的格式显示,必要时添加小时和天字段。 @@ -2538,15 +2263,9 @@ testdb=> \setenv LESS -imx4F \unset name - - 取消设置(删除)psql变量name。 - + 取消设置(删除)psql变量name - - 大多数控制psql行为的变量不能被取消设置;相反,\unset命令被解释为将它们设置为默认值。 - 请参见下面的。 - + 大多数控制psql行为的变量不能取消设置;对于这些变量,\unset命令会被解释为将其设置为默认值。参见下面的 @@ -2555,15 +2274,9 @@ testdb=> \setenv LESS -imx4F \w\write filename \w\write |command - - 将当前查询缓冲区写入文件filename,或者通过管道传给 shell 命令command。 - 如果当前查询缓冲区为空,则写入最近执行的查询。 - + 将当前查询缓冲区写入文件filename,或通过管道传递给 shell 命令command。如果当前查询缓冲区为空,则改为写入最近执行的查询。 - - 如果参数以|开头,则整个剩余部分的行被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分的行会被直接传递给shell。 - + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 @@ -2596,9 +2309,7 @@ testdb=> \setenv LESS -imx4F \x [ on | off | auto ] - - 设置或切换扩展表格格式模式。因此,它等同于\pset expanded。 - + 设置或切换扩展表格格式模式。它等价于\pset expanded @@ -2620,13 +2331,11 @@ testdb=> \setenv LESS -imx4F \! [ command ] - 不带参数时,转义到一个子shell;psql在子shell退出时恢复。 - 带参数时,执行shell命令command。 + 不带参数时,进入一个子 shell;子 shell 退出后,psql恢复运行。带参数时,执行 shell 命令command - 与大多数其他元命令不同,整个行的剩余部分始终被视为\!的参数, - 在参数中不执行变量插值或反引号扩展。行的其余部分被直接传递给shell。 + 与大多数其他元命令不同,该行剩余的全部内容始终被视为\!的参数,其中不会进行变量插值或反引号扩展。该行剩余内容会原样传给 shell。 @@ -2638,7 +2347,7 @@ testdb=> \setenv LESS -imx4F 显示帮助信息。可选的topic参数 (默认为commands)选择要解释的psql的哪个部分: - commands描述psql的反斜杠命令; + commands描述psql的反斜线命令; options描述可以传递给psql的命令行选项; 而variables显示关于psql配置变量的帮助。 @@ -2650,7 +2359,7 @@ testdb=> \setenv LESS -imx4F \; - 反斜杠分号不像前面的命令那样是一个元命令;相反,它只是在不进行进一步处理的情况下将一个分号添加到查询缓冲区中。 + 反斜线分号不像前面的命令那样是一个元命令;相反,它只是在不进行进一步处理的情况下将一个分号添加到查询缓冲区中。 @@ -2662,8 +2371,8 @@ select 1; select 2; select 3; select 1\; select 2\; select 3; - 在到达非反斜杠分号时将三个SQL命令发送到服务器的单个请求中。 - 服务器将执行此类请求作为单个事务,除非字符串中包含明确的BEGIN/COMMIT命令将其分成多个事务。(有关服务器如何处理多查询字符串的更多详细信息,请参见。) + 会在遇到前面没有反斜线的分号时,将这三个 SQL 命令作为单个请求发送到服务器。 + 服务器会将此类请求作为单个事务执行,除非字符串中包含显式的BEGIN/COMMIT命令将其分成多个事务。(有关服务器如何处理多查询字符串的更多详细信息,请参见。) @@ -2671,16 +2380,16 @@ select 1\; select 2\; select 3; - + 模式 - patterns + 模式 在 psql 和 pg_dump 中 - 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要把它写成两个相邻的双引号,这同样是符合 SQL 引用标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你不能只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 + 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要在双引号包围的文本内把它写成两个相邻的双引号,这同样是符合 SQL 加引号标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你可以只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 @@ -2692,21 +2401,15 @@ select 1\; select 2\; select 3; - 包含点(.)的关系模式被解释为模式名称后跟对象名称模式。例如, - \dt foo*.*bar*显示所有位于模式名以foo开头的模式中、且表名包含bar的表。当没有出现点时,模式仅匹配当前模式搜索路径中可见的对象。 - 再次,双引号内的点失去其特殊含义,被视为字面匹配。包含两个点(.)的关系模式 - 被解释为数据库名称后跟模式名称后跟对象名称模式。数据库名称部分不会被视为模式,必须匹配当前连接的数据库名称, - 否则将引发错误。 + 如果用于匹配关系名的模式包含一个点(.),则会被解释为模式名的匹配模式,后接对象名的匹配模式。例如,\dt foo*.*bar*会显示所有位于模式名以foo开头的模式中、且表名包含bar的表。如果没有点,则只匹配当前模式搜索路径中可见的对象。同样,双引号内的点会失去特殊含义,按字面匹配。如果用于匹配关系名的模式包含两个点(.),则会被解释为数据库名、模式名的匹配模式和对象名的匹配模式。数据库名部分不会被当作匹配模式,必须与当前连接的数据库名相同,否则会报错。 - 包含一个点(.)的模式被解释为数据库名称后跟模式的模式名称。例如, - \dn mydb.*foo*显示所有包含foo的模式。数据库名称部分不会被视为模式, - 必须匹配当前连接数据库的名称,否则将引发错误。 + 如果用于匹配模式名的模式包含一个点(.),则会被解释为数据库名,后接模式名的匹配模式。例如,\dn mydb.*foo*会显示名称中包含foo的所有模式。数据库名部分不会被当作匹配模式,必须与当前连接的数据库名相同,否则会报错。 - 高级用户可以使用字符类等正则表达式记法,如[0-9]可以匹配任意数字。所有的正则表达式特殊字符都按照所说的工作,以下字符除外:.会按照上面所说的作为一种分隔符,*会被翻译成正则表达式记号.*?会被翻译成.,而$则按字面意思匹配。根据需要,可以通过书写?(R+|)(R|)R?来分别模拟模式字符.R*R?$不需要作为一个正则表达式字符,因为模式必须匹配整个名称,而不是像正则表达式的常规用法那样解释(换句话说,$会被自动地追加到模式上)。如果不希望该模式的匹配位置被固定,可以在开头或者结尾写上*。注意在双引号内,所有的正则表达式特殊字符会失去其特殊含义并且按照其字面意思进行匹配。还有,在操作符名称模式中(即作为\do的参数),正则表达式特殊字符也按照字面意思进行匹配。 + 高级用户可以使用字符类等正则表达式记法,如[0-9]可以匹配任意数字。所有的正则表达式特殊字符都按照所说的工作,以下字符除外:.会按照上面所说的作为一种分隔符,*会被翻译成正则表达式记号.*?会被翻译成.,而$则按字面意思匹配。根据需要,可以用?模拟.,用(R+|)模拟R*,或用(R|)模拟R?$不需要作为一个正则表达式字符,因为模式必须匹配整个名称,而不是像正则表达式的常规用法那样解释(换句话说,$会被自动地追加到模式上)。如果不希望该模式的匹配位置被固定,可以在开头或者结尾写上*。注意在双引号内,所有的正则表达式特殊字符会失去其特殊含义并且按照其字面意思进行匹配。还有,在操作符名称模式中(即作为\do的参数),正则表达式特殊字符也按照字面意思进行匹配。 @@ -2714,7 +2417,7 @@ select 1\; select 2\; select 3; 高级特性 - + 变量 @@ -2735,7 +2438,7 @@ bar - 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要重置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 + 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要取消设置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 @@ -2749,7 +2452,7 @@ bar - 控制psql行为的变量通常不能被重置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse。 + 控制psql行为的变量通常不能被取消设置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse @@ -2767,7 +2470,7 @@ bar - 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被重置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交打开模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身即不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 + 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被取消设置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交关闭模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身既不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 @@ -2797,7 +2500,7 @@ bar DBNAME - 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -2806,7 +2509,7 @@ bar ECHO - 如果被设置为all,所有非空输入行会被按照读入它们的样子打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被重置或者设置为none(默认值)则不会显示任何查询。 + 如果被设置为all,所有非空输入行会在读入时打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被设置为none(默认值)则不会显示任何查询。 @@ -2824,7 +2527,7 @@ bar ENCODING - 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者重置。 + 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者取消设置。 @@ -2842,12 +2545,12 @@ bar FETCH_COUNT - 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每一组就会包括这么多个行。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 + 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每组包含的行数等于该整数值。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 - 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT个行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 + 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 @@ -2876,7 +2579,7 @@ bar HISTCONTROL - 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则匹配之前的历史行的行不会被放入。值ignoreboth组合了上述两种值。如果被重置或者被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 + 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则与上一条历史记录相同的行不会被放入。值ignoreboth组合了上述两种值。如果被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 @@ -2890,7 +2593,7 @@ bar HISTFILE - 该文件名将被用于存储历史列表。如果被重设,文件名将从PSQL_HISTORY环境变量中取得。如果该环境变量也没有被设置,则默认值是~/.psql_history,在Windows上是%APPDATA%\postgresql\psql_history。例如, + 该文件名将被用于存储历史列表。如果未设置该变量,文件名将从PSQL_HISTORY环境变量中取得。如果该环境变量也没有被设置,则默认值是~/.psql_history,在Windows上是%APPDATA%\postgresql\psql_history。例如, \set HISTFILE ~/.psql_history-:DBNAME @@ -2922,7 +2625,7 @@ bar HOST - 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -2931,7 +2634,7 @@ bar IGNOREEOF - 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须键入多个连续的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 + 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须连续键入与该数值相等数量的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 @@ -2945,8 +2648,8 @@ bar LASTOID - 最后被影响的 OID 的值,这可能会由INSERT或者\lo_import命令返回。这个变量只保证在下一个SQL命令被显示完之前有效。 - PostgreSQL 服务器从12版开始不再支持 OID 系统列,因此,在面向此类服务器时,跟随在INSERT后面的 LASTOID 将始终为0。 + 最后被影响的 OID 的值,这可能会由INSERT或者\lo_import命令返回。这个变量仅保证在下一个SQL命令的结果显示完之前有效。 + PostgreSQL 服务器从12版开始不再支持 OID 系统列,因此,在面向此类服务器时,执行INSERT后的 LASTOID 将始终为0。 @@ -2971,7 +2674,7 @@ bar - 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被重置或者设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 + 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 @@ -2992,7 +2695,7 @@ bar PORT - 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -3031,7 +2734,7 @@ bar SERVER_VERSION_NUM - 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者重设。 + 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者取消设置。 @@ -3043,7 +2746,7 @@ bar 如果最后一个 shell 命令失败,则为 true;如果成功,则为 false。这适用于通过 \!\g\o\w - 和 \copy 元命令调用的 shell 命令,也适用于反引号(`)展开。请注意,对于 \o,该变量会在下一个 \o 命令关闭输出管道时更新。 + 和 \copy 元命令调用的 shell 命令,也适用于反引号(`)扩展。请注意,对于 \o,该变量会在下一个 \o 命令关闭输出管道时更新。 另见 SHELL_EXIT_CODE @@ -3055,7 +2758,7 @@ bar 最后一个 shell 命令返回的退出状态。0–127 表示程序退出码,128–255 表示因信号而终止,-1 表示未能启动程序或未能取得其退出状态。这适用于通过 \!\g\o\w - 和 \copy 元命令调用的 shell 命令,也适用于反引号(`)展开。请注意,对于 \o,该变量会在下一个 \o 命令关闭输出管道时更新。 + 和 \copy 元命令调用的 shell 命令,也适用于反引号(`)扩展。请注意,对于 \o,该变量会在下一个 \o 命令关闭输出管道时更新。 另见 SHELL_ERROR @@ -3075,7 +2778,7 @@ bar SHOW_CONTEXT - 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT域。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 + 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT字段。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 当VERBOSITY被设置为tersesqlstate时,这个设置无效(另见\errverbose,它可以用来得到刚遇到的错误的详细信息)。 @@ -3094,7 +2797,7 @@ bar SINGLESTEP - 设置这个变量为on等效于命令选项。 + 设置这个变量为on等效于命令行选项 @@ -3112,7 +2815,7 @@ bar USER - 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -3121,7 +2824,7 @@ bar VERBOSITY - 这个变量可以被设置为值defaultverboseterse或者sqlstate来控制错误报告的详细程度(另见\errverbose,在想得到之前的错误的详细版本时使用)。 + 这个变量可以被设置为值defaultverboseterse或者sqlstate来控制错误报告的详细程度(另见\errverbose,在想得到刚遇到的错误的详细信息时使用)。 @@ -3132,7 +2835,7 @@ bar VERSION_NUM - 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或重设。 + 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或取消设置。 @@ -3142,11 +2845,11 @@ bar - - <acronym>SQL</acronym> 中插入变量 + + <acronym>SQL</acronym> 插值 - psql变量的一个关键特性是可以把它们替换(插入)到常规SQL语句中,也可以把它们作为元命令的参数。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。插入一个值而不加引号的语法是在变量名前面加上一个冒号(:)。例如, + psql变量的一个关键特性是可以把它们替换(插值)到常规SQL语句中,也可以把它们替换到元命令的参数中。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。不加引号地插值一个值的语法是在变量名前面加上一个冒号(:)。例如, testdb=> \set foo 'my_table' testdb=> SELECT * FROM :foo; @@ -3155,7 +2858,7 @@ testdb=> SELECT * FROM :foo; - 当一个值被用作 SQL 文本或者标识符时,最安全的是把它加上引用。要引用一个变量的值作为 SQL 文本,可以把变量名称放在单引号中并且在引号前面写一个冒号。要引用作为 SQL 标识符,则可以把变量名称放在双引号中并且在引号前面写一个冒号。这种结构可以正确地处理变量值中嵌入的引号和其他特殊字符。之前的示例用这种方法写会更安全: + 当一个值要用作 SQL 字面量或标识符时,最安全的做法是为它加上引号。要将变量值作为 SQL 字面量加引号,应写一个冒号,后面跟用单引号括起来的变量名。要将变量值作为 SQL 标识符加引号,则在冒号后面用双引号括起变量名。这些写法能正确处理变量值中嵌入的引号和其他特殊字符。前面的示例可用以下更安全的写法: testdb=> \set foo 'my_table' testdb=> SELECT * FROM :"foo"; @@ -3163,11 +2866,11 @@ testdb=> SELECT * FROM :"foo"; - 在被引用的SQL文本和标识符中将不会执行变量插入。因此,一个诸如':foo'的结构不会从一个变量的值产生一个被引用的文本(即便能够也会不安全,因为无法正确地处理嵌入在值中的引号)。 + 在加引号的SQL字面量和标识符内部,不会执行变量插值。因此,':foo'这样的写法不能根据变量值生成加引号的字面量(即使能够生效,也不安全,因为它无法正确处理变量值中嵌入的引号)。 - 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个被引用的字符串插入: + 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个加引号的字符串进行插值: testdb=> \set content `cat my_file.txt` testdb=> INSERT INTO my_table VALUES (:'content'); @@ -3176,7 +2879,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 因为冒号可以合法地出现在 SQL 命令中,一次明显的插入尝试(即:name:'name'或者:"name")不会被替换,除非所提及的变量就是当前被设置的。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 + 因为冒号可以合法地出现在 SQL 命令中,一次明显的插值尝试(即:name:'name'或者:"name")不会被替换,除非所指的变量当前已设置。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 @@ -3184,12 +2887,12 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 文本或者标识符的冒号引用语法是一种psql扩展。 + 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 字面量或者标识符的冒号加引号语法是一种psql扩展。 - + 提示符 @@ -3203,33 +2906,26 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %M - - 数据库服务器的完整主机名(带域名);如果连接通过 Unix 域套接字建立,则为 [local];如果 Unix 域套接字不在编译时默认位置,则为 [local:/dir/name]。 - + 数据库服务器的完整主机名(含域名);如果通过 Unix 域套接字连接,则为[local];如果 Unix 域套接字不在编译时指定的默认位置,则为[local:/dir/name] %m - - 数据库服务器的主机名,在第一个点处分截;如果连接通过 Unix 域套接字建立,则为 [local]。 - + 数据库服务器的主机名,在第一个点号处截断;如果通过 Unix 域套接字连接,则为[local] %> - 数据库服务器正在监听的端口号。 + 数据库服务器监听的端口号。 %n - - 数据库会话用户名。(由于 SET SESSION - AUTHORIZATION 命令的作用,该值在数据库会话期间可能会发生变化。) - + 数据库会话用户名。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) @@ -3248,11 +2944,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %# - - 如果会话用户是数据库超级用户,则输出 - #,否则输出 >。(由于 SET SESSION - AUTHORIZATION 命令的作用,该值的展开在数据库会话期间可能会发生变化。) - + 如果会话用户是数据库超级用户,则为#,否则为>。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) @@ -3268,7 +2960,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %R - 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 dollar-quoted 字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 + 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 美元引用字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 @@ -3295,7 +2987,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %digits - 带有所示八进制码的字符被替换。 + 替换为指定八进制代码对应的字符。 @@ -3397,14 +3089,14 @@ $endif - )命令行选项也可用于在单次运行psql时禁用 Readline。这会阻止制表补全、命令行历史的使用或记录,以及多行命令的编辑。当你需要复制粘贴包含 TAB 字符的文本时,它尤其有用。 + )命令行选项也可用于在单次运行psql时禁用 Readline。这会阻止TAB 补全、命令行历史的使用或记录,以及多行命令的编辑。当你需要复制粘贴包含 TAB 字符的文本时,它尤其有用。 - + 环境 @@ -3489,9 +3181,9 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 如果查询结果无法在屏幕上显示完整,它们将通过此命令进行传输。典型的值是moreless。 + 如果查询结果无法在屏幕上显示完整,它们会通过管道传给此命令。典型的值是moreless。 可以通过将PSQL_PAGERPAGER设置为空字符串,或通过调整\pset命令的与分页相关的选项来禁用分页器。 - 这些变量按照列出的顺序进行检查;首先设置的变量将被使用。 + 这些变量按照列出的顺序进行检查;使用按该顺序找到的第一个已设置的变量。 如果它们都没有设置,默认情况下在大多数平台上使用more,但在Cygwin上使用less @@ -3571,7 +3263,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' 在任何情况下,可以通过设置PSQLRC环境变量来覆盖此默认文件路径。 - 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加破折号和PostgreSQL的主要或次要版本标识符来使其与psql版本相关, + 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加连字符和PostgreSQL的大版本或小版本标识符来使其与psql版本相关, 例如~/.psqlrc-&majorversion;~/.psqlrc-&version;。 最具体版本匹配的文件将优先读取,而不是非特定版本的文件。 这些版本后缀是在确定文件路径后添加的,如上所述。 @@ -3599,14 +3291,14 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - psql最适合与相同或较旧主要版本的服务器配合使用。 - 如果服务器的版本比psql本身更新,反斜杠命令特别容易失败。 - 然而,\d系列的反斜杠命令应该可以在版本回溯到9.2的服务器上运行, + psql最适合与相同或较旧大版本的服务器配合使用。 + 如果服务器的版本比psql本身更新,反斜线命令特别容易失败。 + 然而,\d系列的反斜线命令应该可以在最低至 9.2 版本的服务器上运行, 但不一定适用于比psql本身更新的服务器。运行SQL命令和显示查询结果的一般功能 - 也应该可以在更新主要版本的服务器上运行,但不能保证在所有情况下都能实现。 + 也应该可以在更新大版本的服务器上运行,但不能保证在所有情况下都能实现。 - 如果你想用psql连接到多个具有不同主版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个主版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 + 如果你想用psql连接到多个具有不同大版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个大版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 @@ -3620,7 +3312,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空格。现在则要求一些空格。 + 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空白。现在则要求用空白分隔。 @@ -3793,9 +3485,7 @@ testdb=> \df int*pl * bigint - - 在适合的情况下,可以使用 \crosstabview 命令将查询结果显示为交叉表: - + 在适当的情况下,要以交叉表形式显示查询结果,可以使用\crosstabview命令: testdb=> SELECT first, second, first > 2 AS gt2 FROM my_table; first | second | gt2 -------+--------+----- @@ -3813,10 +3503,7 @@ testdb=> \crosstabview first second 3 | | | t | 4 | | | | t (4 rows) - - -第二个示例展示了一个乘法表,其中行按数字倒序排列,而列按独立的升序数字排列。 - +第二个示例显示一个乘法表,行按数值降序排列,列则独立地按数值升序排列。 testdb=> SELECT t1.first as "A", t2.first+100 AS "B", t1.first*(t2.first+100) as "AxB", testdb-> row_number() over(order by t2.first) AS ord testdb-> FROM my_table t1 CROSS JOIN my_table t2 ORDER BY 1 DESC diff --git a/zh/16/release-16.sgml b/zh/16/release-16.sgml index b468b6af..8a08fc15 100644 --- a/zh/16/release-16.sgml +++ b/zh/16/release-16.sgml @@ -1648,7 +1648,7 @@ Branch: REL_14_STABLE [dda622edc] 2026-08-02 16:49:18 -0400 --> - 修复为文本搜索词典创建缓存条目的过程中发生内存不足后导致的崩溃 + 修复为文本检索词典创建缓存条目的过程中发生内存不足后导致的崩溃 (Tom Lane) § @@ -3658,7 +3658,7 @@ Branch: REL_14_STABLE [6cae0c2bd] 2026-04-22 11:09:21 -0400 损坏或恶意的词缀文件可能使服务器崩溃。 - 这不被视为安全问题,因为文本搜索配置文件被假定为可信, + 这不被视为安全问题,因为文本检索配置文件被假定为可信, 但仍然值得修复。 diff --git a/zh/16/rowtypes.sgml b/zh/16/rowtypes.sgml index 7782828c..dd68ebdf 100644 --- a/zh/16/rowtypes.sgml +++ b/zh/16/rowtypes.sgml @@ -75,7 +75,7 @@ CREATE TABLE inventory_item ( - 构造组合值 + 构造复合值 复合类型 @@ -83,7 +83,7 @@ CREATE TABLE inventory_item ( - 要把组合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,组合常量的一般格式如下: + 要把复合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,复合常量的一般格式如下: '( val1 , val2 , ... )' @@ -103,11 +103,11 @@ CREATE TABLE inventory_item ( - (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。必要时可能需要显式指定类型。) + (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。可能需要显式指定类型,以指明应将该常量转换为哪种类型。) - ROW表达式语法也可以用于构造组合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: + ROW表达式语法也可以用于构造复合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: ROW('fuzzy dice', 42, 1.99) ROW('', 42, NULL) @@ -126,7 +126,7 @@ ROW('', 42, NULL) 访问复合类型 - 要访问组合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: + 要访问复合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: SELECT item.name FROM on_hand WHERE item.price > 9.99; @@ -148,7 +148,7 @@ SELECT (on_hand.item).name FROM on_hand WHERE (on_hand.item).price > 9.99; - 无论何时从组合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回组合值的函数结果中只选取一个字段,你需要这样写: + 无论何时从复合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回复合值的函数结果中只选取一个字段,你需要这样写: SELECT (my_func(...)).field FROM ... @@ -164,10 +164,10 @@ SELECT (my_func(...)).field FROM ... - 修改组合值 + 修改复合类型 - 下面是一些插入和更新组合列时正确语法的示例。先看插入或更新整个列值的情况: + 下面是一些插入和更新复合列时正确语法的示例。先看插入或更新整个列值的情况: INSERT INTO mytab (complex_col) VALUES((1.1,2.2)); @@ -179,7 +179,7 @@ UPDATE mytab SET complex_col = ROW(1.1,2.2) WHERE ...; - 我们也可以更新组合列中的单个子字段: + 我们也可以更新复合列中的单个子字段: UPDATE mytab SET complex_col.r = (complex_col).r + 1 WHERE ...; @@ -208,11 +208,11 @@ INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2); - 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的组合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: + 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的复合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: SELECT c FROM inventory_item c; - 这个查询会产生一个单独的组合值列,因此我们可能得到如下输出: + 这个查询会产生一个单独的复合值列,因此我们可能得到如下输出: c ------------------------ @@ -223,7 +223,7 @@ SELECT c FROM inventory_item c; - 普通的限定列名语法table_name.column_name可以理解为对该表当前行的组合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) + 普通的限定列名语法table_name.column_name可以理解为对该表当前行的复合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) @@ -256,19 +256,19 @@ SELECT (myfunc(x)).a, (myfunc(x)).b, (myfunc(x)).c FROM some_table; SELECT m.* FROM some_table, LATERAL myfunc(x) AS m; - 把该函数放在LATERAL FROM项中,可以防止它对每一行被调用多于一次。m.*仍会展开为m.a, m.b, m.c,但现在这些变量只是对该FROM项输出的引用。(这里的LATERAL关键字其实是可选的,不过我们把它写出来,是为了明确该函数会从some_table中取得x。) + 把该函数放在LATERAL FROM项中,可以避免它在每行上被调用多次。m.*仍会展开为m.a, m.b, m.c,但现在这些变量只是对该FROM项输出的引用。(这里的LATERAL关键字其实是可选的,不过我们把它写出来,是为了明确该函数会从some_table中取得x。) - 当composite_value.*出现在SELECT输出列表、INSERT/UPDATE/DELETE/MERGE中的RETURNING列表、VALUES子句或行构造器的顶层时,就会产生这种列展开行为。在所有其他上下文中(包括嵌套在上述结构之内时),给组合值附加.*不会改变其值,因为它表示所有列,因此结果仍然是同一个组合值。例如,如果somefunc()接受一个组合值参数,这些查询就是等价的: + 当composite_value.*出现在SELECT输出列表、INSERT/UPDATE/DELETE中的RETURNING列表、VALUES子句或行构造器的顶层时,就会产生这种列展开行为。在所有其他上下文中(包括嵌套在上述结构之内时),给复合值附加.*不会改变其值,因为它表示所有列,因此结果仍然是同一个复合值。例如,如果somefunc()接受一个复合值参数,这些查询就是等价的: SELECT somefunc(c.*) FROM inventory_item c; SELECT somefunc(c) FROM inventory_item c; - 在这两种情况下,inventory_item的当前行都会作为单个组合值参数传递给该函数。尽管.*在这种场合并不起作用,使用它仍是一种良好风格,因为它能明确表明这里想要的是组合值。特别是,解析器会把c.*中的c视为表名或别名,而不是列名,因此不会产生歧义;而没有.*时,就不清楚c究竟表示表名还是列名,而且如果存在名为c的列,实际上会优先按列名解释。 + 在这两种情况下,inventory_item的当前行都会作为单个复合值参数传递给该函数。尽管.*在这种场合并不起作用,使用它仍是一种良好风格,因为它能明确表明这里想要的是复合值。特别是,解析器会把c.*中的c视为表名或别名,而不是列名,因此不会产生歧义;而没有.*时,就不清楚c究竟表示表名还是列名,而且如果存在名为c的列,实际上会优先按列名解释。 @@ -278,7 +278,7 @@ SELECT * FROM inventory_item c ORDER BY c; SELECT * FROM inventory_item c ORDER BY c.*; SELECT * FROM inventory_item c ORDER BY ROW(c.*); - 所有这些ORDER BY子句都指定了该行的组合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: + 所有这些ORDER BY子句都指定了该行的复合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: SELECT * FROM inventory_item c ORDER BY ROW(c.name, c.supplier_id, c.price); SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); @@ -287,7 +287,7 @@ SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); - 另一种与组合值有关的特殊语法行为是,我们可以使用函数记法来提取组合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: + 另一种与复合值有关的特殊语法行为是,我们可以使用函数记法来提取复合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: SELECT c.name FROM inventory_item c WHERE c.price > 1000; @@ -306,11 +306,11 @@ SELECT c.somefunc FROM inventory_item c; 函数记法与字段记法之间的这种等价性,使得我们可以通过在复合类型上使用函数来实现计算字段 - computed field + 计算字段 - field - computed + 字段 + 计算 使用上面最后一种查询形式的应用程序,无需直接知道somefunc并不是该表中的真实列。 @@ -328,7 +328,7 @@ SELECT c.somefunc FROM inventory_item c; 复合类型的输入和输出语法 - 组合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明组合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 + 复合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明复合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 '( 42)' @@ -336,7 +336,7 @@ SELECT c.somefunc FROM inventory_item c; - 如前所示,在写组合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让组合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的组合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作组合语法的数据字符。 + 如前所示,在写复合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让复合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的复合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作复合语法的数据字符。 @@ -350,18 +350,18 @@ SELECT c.somefunc FROM inventory_item c; - 记住,你在 SQL 命令中写的内容会先被解释为字符串字面量,然后才会被解释为组合值。这会使所需的反斜杠数量翻倍(假定使用的是转义字符串语法)。例如,要在组合值中插入一个包含双引号和反斜杠的text字段,需要写成: + 记住,你在 SQL 命令中写的内容会先被解释为字符串字面量,然后才会被解释为复合值。这会使所需的反斜杠数量翻倍(假定使用的是转义字符串语法)。例如,要在复合值中插入一个包含双引号和反斜杠的text字段,需要写成: INSERT ... VALUES ('("\"\\")'); - 字符串字面量处理器会去掉一层反斜杠,因此传到组合值解析器时看起来是("\"\\")。随后,送入text数据类型输入例程的字符串就变成了"\。(如果我们使用的数据类型的输入例程也会把反斜杠当作特殊字符处理,例如bytea,那么为了在存储的组合字段中得到一个反斜杠,命令里可能需要多达八个反斜杠。)美元引用(见)可用于避免反斜杠加倍的需要。 + 字符串字面量处理器会去掉一层反斜杠,因此传到复合值解析器时看起来是("\"\\")。随后,送入text数据类型输入例程的字符串就变成了"\。(如果我们使用的数据类型的输入例程也会把反斜杠当作特殊字符处理,例如bytea,那么为了在存储的复合字段中得到一个反斜杠,命令里可能需要多达八个反斜杠。)美元引用(见)可用于避免反斜杠加倍的需要。 - 在 SQL 命令中编写组合值时,ROW构造器语法通常比组合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是组合成员时完全相同。 + 在 SQL 命令中编写复合值时,ROW构造器语法通常比复合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是复合成员时完全相同。 diff --git a/zh/16/textsearch.sgml b/zh/16/textsearch.sgml index d4e1462f..6bbff3a7 100644 --- a/zh/16/textsearch.sgml +++ b/zh/16/textsearch.sgml @@ -1,21 +1,21 @@ - 全文搜索 + 全文检索 - 全文搜索 + 全文检索 - 文本搜索 + 文本检索 介绍 - 全文搜索(或简称文本搜索)提供了识别满足 + 全文检索(或简称文本检索)提供了识别满足 查询条件的自然语言文档的能力, 并且可按它们与查询的相关度进行排序。最常见的搜索类型,是找出所有包含给定 查询词的文档,并按它们与查询的相似性 @@ -25,7 +25,7 @@ - 文本搜索操作符在数据库中已经存在很多年了。 + 文本检索操作符在数据库中已经存在很多年了。 PostgreSQL为文本数据类型提供了 ~~*LIKEILIKE 操作符,但它们缺少现代信息系统所要求的许多关键特性: @@ -138,7 +138,7 @@ ()。围绕这两种数据类型还有许多函数和 操作符(),其中最重要的是匹配操作符 @@,我们将在中介绍。 - 全文搜索还可以借助索引加速()。 + 全文检索还可以借助索引加速()。 @@ -147,11 +147,11 @@ 文档 - 全文搜索 + 文本检索 - 文档是全文搜索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本搜索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 + 文档是全文检索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本检索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 @@ -179,7 +179,7 @@ WHERE m.mid = d.did AND m.mid = 12; - 为了进行文本搜索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 + 为了进行文本检索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 @@ -187,7 +187,7 @@ WHERE m.mid = d.did AND m.mid = 12; 基本文本匹配 - 在PostgreSQL中,全文搜索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: + 在PostgreSQL中,全文检索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: SELECT 'a fat cat sat on a mat and ate a fat rat'::tsvector @@ 'cat & rat'::tsquery; @@ -203,7 +203,7 @@ SELECT 'fat & cow'::tsquery @@ 'a fat cat sat on a mat and ate a fat rat'::t - 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索术语,这些术语必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个术语组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本搜索匹配更像是这样: + 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索词,这些搜索词必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个搜索词组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本检索匹配更像是这样: SELECT to_tsvector('fat cats ate fat rats') @@ to_tsquery('fat & rat'); @@ -221,7 +221,7 @@ SELECT 'fat cats ate fat rats'::tsvector @@ to_tsquery('fat & rat'); f - 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,默认假定已经正规化,因此 rats 不会匹配 rat。 + 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,被假定为已经正规化,因此 rats 不会匹配 rat @@ -290,49 +290,49 @@ SELECT phraseto_tsquery('the cats ate the rats'); 配置 - 前述的都是简单的文本搜索示例。正如前面所提到的,全文搜索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如基于空白之外的解析。这个功能由文本搜索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 + 前述的都是简单的文本检索示例。正如前面所提到的,全文检索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如不局限于按空白划分的解析。这个功能由文本检索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 - 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本搜索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config。 + 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本检索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config - 依赖一个配置的每一个文本搜索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当这个参数被忽略时,default_text_search_config才被使用。 + 依赖一个配置的每一个文本检索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当省略这个参数时,default_text_search_config才被使用。 - 为了让建立自定义文本搜索配置更容易,一个配置可以从更简单的数据库对象来建立。PostgreSQL的文本搜索功能提供了四类配置相关的数据库对象: + 为了便于构建自定义文本检索配置,配置由更简单的数据库对象组合而成。PostgreSQL 的文本检索功能提供了四类与配置相关的数据库对象: - 文本搜索解析器将文档拆分成词元并分类每个词元(例如,作为词或者数字)。 + 文本检索解析器将文档拆分成词元并对每个词元分类(例如,作为词或者数字)。 - 文本搜索词典将词元转变成正规化的形式并拒绝停用词。 + 文本检索词典将词元转变成正规化的形式并拒绝停用词。 - 文本搜索模板提供位于词典底层的函数(一个词典简单地指定一个模板和一组用于模板的参数)。 + 文本检索模板提供位于词典底层的函数(词典只需指定一个模板及其一组参数)。 - 文本搜索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 + 文本检索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 - 文本搜索解析器和模板是从低层 C 函数构建而来,因此它要求 C 编程能力来开发新的解析器和模板,并且还需要超级用户权限来把它们安装到一个数据库中(在PostgreSQL发布的contrib/区域中有一些附加的解析器和模板的示例)。由于词典和配置只是对底层解析器和模板的参数化和连接,不需要特殊的权限来创建一个新词典或配置。创建定制词典和配置的示例将在本章稍后的部分给出。 + 文本检索解析器和模板由底层 C 函数构成,因此开发新的解析器和模板需要 C 编程能力,将它们安装到数据库中则需要超级用户权限。(PostgreSQL 发行版的 contrib/ 目录中有附加解析器和模板的示例。)词典和配置只是为底层解析器和模板设置参数并将它们连接起来,因此创建新词典或配置不需要特殊权限。本章后面会给出创建自定义词典和配置的示例。 @@ -343,14 +343,14 @@ SELECT phraseto_tsquery('the cats ate the rats'); 表和索引 - 在前一节中的示例演示了使用简单常数字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 + 在前一节中的示例演示了使用简单常量字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 搜索表 - 即使没有索引,也可以执行全文搜索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend: + 即使没有索引,也可以执行全文检索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend SELECT title @@ -374,7 +374,7 @@ WHERE to_tsvector(body) @@ to_tsquery('friend'); - 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 中同时包含 createtable: + 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 合在一起包含 createtable SELECT title @@ -388,7 +388,7 @@ LIMIT 10; - 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本搜索在实际使用中通常都需要建立索引。 + 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本检索在实际使用中通常都需要建立索引。 @@ -397,13 +397,13 @@ LIMIT 10; 创建索引 - 我们可以创建一个GIN索引()来加速文本搜索: + 我们可以创建一个GIN索引()来加速文本检索: CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector('english', body)); - 注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本搜索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含使用不同文本搜索配置创建的tsvector,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 + 注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本检索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含使用不同文本检索配置创建的tsvector,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 @@ -420,10 +420,7 @@ CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector(config_name, body)); 这里 config_namepgweb 表中的一个列。这样就允许在同一个索引中混合使用不同配置,同时记录每个索引项使用的是哪一种配置。例如,如果文档集合中包含不同语言的文档,这就会很有用。同样,打算使用该索引的查询也必须写成对应的形式,例如 WHERE to_tsvector(config_name, body) @@ 'a & b' - - 索引甚至可以连接列: - - + 索引甚至可以串接多个列: CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector('english', title || ' ' || body)); @@ -443,7 +440,7 @@ ALTER TABLE pgweb CREATE INDEX textsearch_idx ON pgweb USING GIN(textsearchable_index_col); - 现在我们准备好执行一个快速的全文搜索了: + 现在我们准备好执行一个快速的全文检索了: SELECT title @@ -455,7 +452,7 @@ LIMIT 10; - 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本搜索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 + 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本检索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 @@ -463,10 +460,10 @@ LIMIT 10; - 控制文本搜索 + 控制文本检索 - 要实现全文搜索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 + 要实现全文检索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 @@ -485,7 +482,7 @@ to_tsvector( config - to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本搜索配置进行处理。下面是一个简单示例: + to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本检索配置进行处理。下面是一个简单示例: SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); @@ -500,7 +497,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每类词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本搜索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english。 + to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每个词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本检索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english @@ -508,7 +505,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为空,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: + 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为 NULL,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: UPDATE tt SET ti = @@ -659,12 +656,12 @@ websearch_to_tsquery( config
- 无引号文本:不在引号中的文本会被转换为由&操作符分隔的词,就像经过plainto_tsquery处理一样。 + 未加引号的文本:不在引号中的文本会被转换为由&操作符分隔的词,就像经过plainto_tsquery处理一样。 - "引号文本":引号中的文本会被转换为由<->操作符分隔的词,就像经过phraseto_tsquery处理一样。 + "加引号的文本":引号中的文本会被转换为由<->操作符分隔的词,就像经过phraseto_tsquery处理一样。 @@ -722,7 +719,7 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); 搜索结果排名 - 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及它们出现于文档中哪个部分。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 + 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及这些词所处文档部分的重要程度。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 @@ -813,12 +810,12 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 8 用文档中唯一词的数量除排名 + 8 用文档中不同词的数量除排名 - 16 用 1 + 文档中唯一词数量的对数除排名 + 16 用 1 + 文档中不同词数量的对数除排名 @@ -832,7 +829,7 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。正规化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 + 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。归一化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 @@ -904,7 +901,7 @@ ts_headline( config ts_headline 接收文档和查询,并返回文档中一段 - 高亮查询词条的摘录。具体而言,该函数会先用查询选择相关文本片段,然后 + 高亮查询词的摘录。具体而言,该函数会先用查询选择相关文本片段,然后 高亮查询中出现的所有词,即使这些词的位置并不满足查询本身的位置限制。 用于解析文档的配置可通过 config 指定; 若省略 config,则使用 @@ -1011,7 +1008,7 @@ occurrences to display in the result.', 附加特性 - 本节介绍一些在文本搜索中很有用的附加函数和操作符。 + 本节介绍一些在文本检索中很有用的附加函数和操作符。 @@ -1124,7 +1121,7 @@ occurrences to display in the result.', - 返回用 AND 结合的两个给定查询。 + 返回两个给定查询的 AND 组合。 @@ -1138,7 +1135,7 @@ occurrences to display in the result.', - 返回用 OR 结合的两个给定查询。 + 返回两个给定查询的 OR 组合。 @@ -1191,7 +1188,7 @@ SELECT to_tsquery('fat') <-> to_tsquery('cat | rat'); - 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: + 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在其后距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: SELECT tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10); @@ -1245,10 +1242,7 @@ SELECT numnode('foo & bar'::tsquery); - - 返回可用于索引搜索的tsquery部分。这个函数可用于检测不可索引的查询,例如只包含停用词或只包含否定项的查询。例如: - - + 返回一个tsquery中可用于搜索索引的部分。此函数可用于检测无法使用索引的查询,例如只包含停用词或只包含否定词项的查询。例如: SELECT querytree(to_tsquery('defined')); querytree ----------- @@ -1424,7 +1418,7 @@ SELECT title, body FROM messages WHERE tsv @@ to_tsquery('title & body'); - 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本搜索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 + 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本检索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 @@ -1491,7 +1485,7 @@ ts_stat(sqlquery text, - 如果提供了 weights,则只统计具有这些权重之一的出现。 + 如果提供了 weights,则只统计具有这些权重之一的词的出现次数。 @@ -1520,7 +1514,7 @@ LIMIT 10; 解析器 - 文本搜索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 + 文本检索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 @@ -1543,12 +1537,12 @@ LIMIT 10; asciiword - 单词,所有 ASCII 字母 + 单词,全部由 ASCII 字母组成 elephant word - 单词,所有字母 + 单词,全部由字母组成 mañana @@ -1558,12 +1552,12 @@ LIMIT 10; asciihword - 带连字符的单词,所有 ASCII + 带连字符的单词,全部为 ASCII 字符 up-to-date hword - 带连字符的单词,所有字母 + 带连字符的单词,由字母组成 lógico-matemática @@ -1573,12 +1567,12 @@ LIMIT 10; hword_asciipart - 带连字符的单词部分,所有 ASCII + 带连字符的单词部分,全部为 ASCII 字符 postgresql-beta1 上下文中的 postgresql hword_part - 带连字符的单词部分,所有字母 + 带连字符的单词部分,全部由字母组成 lógico-matemática 上下文中的 lógicomatemática @@ -1653,8 +1647,8 @@ LIMIT 10; blank - 空格符号 - (其他不识别的任意空白或标点符号) + 空白符号 + (未被识别为其他类型的空白或标点符号) @@ -1662,12 +1656,12 @@ LIMIT 10; - 解析器的一个字母的概念由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时可以用来区别它们。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 + 解析器对字母的界定由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时区分它们会很有用。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 email不支持所有由RFC 5322定义的有效电子邮件字符。 - 具体来说,电子邮件用户名仅支持句号、短横线和下划线这些非字母数字字符。 + 具体来说,电子邮件用户名仅支持句点、短横线和下划线这些非字母数字字符。 @@ -1716,7 +1710,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h 词典 - 词典用于消除不应参与搜索的词(stop words),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 + 词典用于消除不应参与搜索的词(停用词),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 @@ -1731,7 +1725,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - URL地址可以被正规化,以便让等价的 URL 匹配: + URL 地址可以规范化,以便让等价的 URL 匹配: @@ -1776,32 +1770,32 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤字典) + 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤词典 - 如果字典知道该词元但它是一个停用词,则返回一个空数组 + 如果词典知道该词元但它是一个停用词,则返回一个空数组 - 如果字典不识别该输入词元,则返回NULL + 如果词典不识别该输入词元,则返回NULL - PostgreSQL为许多语言提供了预定义的字典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发布的contrib/区域。 + PostgreSQL为许多语言提供了预定义的词典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发行版的contrib/目录。 - 文本搜索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 + 文本检索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 - 配置词典列表的一般规则是,把最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语分类词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: + 配置词典列表的一般规则是,把适用范围最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语同义词词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: ALTER TEXT SEARCH CONFIGURATION astro_en @@ -1810,14 +1804,14 @@ ALTER TEXT SEARCH CONFIGURATION astro_en - 过滤词典可以放在列表中的任何位置,只是不能放在最后,因为放在最后就没有意义了。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 + 过滤词典可以放在列表中的任何位置,但放在末尾没有用处。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 停用词 - 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文搜索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: + 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文检索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: SELECT to_tsvector('english', 'in the list of stop words'); @@ -1949,7 +1943,7 @@ SELECT * FROM ts_debug('english', 'Paris'); - synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基本名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 + synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 @@ -2011,28 +2005,28 @@ mydb=# SELECT 'indexes are very useful'::tsvector @@ to_tsquery('tst', 'indices' - 基本上一个分类词典会用一个首选词替换所有非首选词,并且也可选择地保留原始术语用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典要求一个下列格式的配置文件: + 分类词典基本上会用一个首选词替换所有非首选词,并且也可以选择保留原始词用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典需要一个采用以下格式的配置文件: -# this is a comment -sample word(s) : indexed word(s) -more sample word(s) : more indexed word(s) +# 这是一条注释 +示例词(一个或多个) : 索引词(一个或多个) +更多示例词(一个或多个) : 更多索引词(一个或多个) ... - 其中冒号(:)符号扮演了一个短语及其替换之间的定界符。 + 其中冒号(:)符号用作短语及其替换词之间的分隔符。 - 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过对子词典的应用,但所有样例词都必须能被子词典识别。 + 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过将子词典应用于该词,但所有样例词都必须能被子词典识别。 - 如果有多个短语匹配输入,则分类词典选择最长的那一个,并且使用最后的定义打破连结。 + 如果有多个短语匹配输入,分类词典会选择最长的匹配;长度相同时使用最后的定义。 - 由子词典识别的特定停用词不能够被指定;改用?标记任何可以出现停用词的地方。例如,假定根据子词典athe是停用词: + 由子词典识别的特定停用词不能够被指定;改用?标记可出现任意停用词的位置。例如,假定根据子词典athe是停用词: ? one ? two : swsw @@ -2074,7 +2068,7 @@ CREATE TEXT SEARCH DICTIONARY thesaurus_simple ( - mythesaurus是分类词典配置文件的基础名称(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 + mythesaurus是分类词典配置文件的基名(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 @@ -2099,7 +2093,7 @@ ALTER TEXT SEARCH CONFIGURATION russian 分类词典示例 - 考虑简单的天文词库 thesaurus_astro,其中包含一些天文单词组合: + 考虑一个简单的天文分类词典 thesaurus_astro,其中包含一些天文单词组合: supernovae stars : sn @@ -2167,7 +2161,7 @@ SELECT plainto_tsquery('supernova star'); <application>Ispell</application> 词典 - Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以把搜索词 bank 的词尾变化和词形变化对应起来,例如 bankingbankedbanksbanks'bank's。 + Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以匹配搜索词 bank 的所有变格和变位形式,例如 bankingbankedbanksbanks'bank's @@ -2179,12 +2173,12 @@ SELECT plainto_tsquery('supernova star'); - 要创建一个Ispell词典,执行这三步: + 要创建一个Ispell词典,请执行以下步骤: - 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。有必要抽取.aff.dic文件,把扩展改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): + 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。需要提取.aff.dic文件,将扩展名改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): iconv -f ISO_8859-1 -t UTF-8 -o nn_no.affix nn_NO.aff iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic @@ -2193,7 +2187,7 @@ iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic - 拷贝文件到$SHAREDIR/tsearch_data目录 + 复制文件到$SHAREDIR/tsearch_data目录 @@ -2211,11 +2205,11 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( - 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基础名称。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 + 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基名。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 - Ispell 词典通常识别一个有限集合的词,这样它们后面应该跟着另一个更广义的词典;例如,一个 Snowball 词典,它可以识别所有东西。 + Ispell 词典通常只能识别有限的词,因此其后应跟着另一个覆盖范围更广的词典;例如,一个 Snowball 词典,它可以识别所有输入。 @@ -2223,13 +2217,13 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( prefixes flag *A: - . > RE # As in enter > reenter + . > RE # 例如 enter > reenter suffixes flag T: - E > ST # As in late > latest - [^AEIOU]Y > -Y,IEST # As in dirty > dirtiest - [AEIOU]Y > EST # As in gray > grayest - [^EY] > EST # As in small > smallest + E > ST # 例如 late > latest + [^AEIOU]Y > -Y,IEST # 例如 dirty > dirtiest + [AEIOU]Y > EST # 例如 gray > grayest + [^EY] > EST # 例如 small > smallest @@ -2245,14 +2239,14 @@ lark/MRS .dict文件的格式是: -basic_form/affix_class_name +基本词形/词缀类名 .affix文件中,每一个词缀标志以下面的格式描述: -condition > [-stripping_letters,] adding_affix +条件 > [-删除的字母,] 添加的词缀 @@ -2261,7 +2255,7 @@ condition > [-stripping_letters,] adding_affix - Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,它标记可以参与到复合格式中的词典词: + Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,用于标记词典中可以参与构成复合词的词: compoundwords controlled z @@ -2291,7 +2285,7 @@ SFX T 0 est [^ey] - 一个词缀类的第一行是头部。头部后面列出了词缀规则的域: + 一个词缀类的第一行是首部。首部后面列出了词缀规则的字段: @@ -2343,7 +2337,7 @@ largehearted <application>Snowball</application> 词典 - Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每一个算法懂得按照其语言中的拼写,如何缩减词的常见变体形式为一个基础或词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择地指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。例如,有一个内置的定义等效于 + Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每种算法都知道如何把其语言中词的常见变体约简为基本拼写形式,也就是词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。例如,有一个内置的定义等效于 CREATE TEXT SEARCH DICTIONARY english_stem ( @@ -2357,7 +2351,7 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( - 一个Snowball词典识别所有的东西,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 + 一个Snowball词典识别所有输入,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 @@ -2368,11 +2362,11 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( 配置示例 - 一个文本搜索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本搜索配置来执行其处理。配置参数指定了默认配置的名称,如果忽略了显式的配置参数,文本搜索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 + 一个文本检索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本检索配置来执行其处理。配置参数指定了默认配置的名称,如果省略了显式的配置参数,文本检索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 - 有一些预定义的文本搜索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本搜索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本搜索对象()的信息。 + 有一些预定义的文本检索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本检索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本检索对象()的信息。 @@ -2464,17 +2458,17 @@ SHOW default_text_search_config; - 测试和调试文本搜索 + 测试和调试文本检索 - 一个自定义文本搜索配置的行为很容易变得混乱。本节中描述的函数对于测试文本搜索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 + 一个自定义文本检索配置的行为很容易让人困惑。本节中描述的函数对于测试文本检索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 配置测试 - 函数ts_debug允许简单地测试一个文本搜索配置。 + 函数ts_debug可方便地测试一个文本检索配置。 @@ -2493,7 +2487,7 @@ ts_debug( config re - ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果该参数被忽略则使用default_text_search_config指定的配置。 + ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果省略该参数则使用default_text_search_config指定的配置。 @@ -2568,7 +2562,7 @@ SELECT * FROM ts_debug('english', 'a fat cat sat on a mat - it ate a fat rats') - 为了一个更广泛的示范,我们先为英语语言创建一个public.english配置和 Ispell 词典: + 为了做更完整的演示,我们先为英语创建一个public.english配置和 Ispell 词典: @@ -2626,7 +2620,7 @@ FROM ts_debug('public.english', 'The Brightest supernovaes'); 解析器测试 - 下列函数允许直接测试一个文本搜索解析器。 + 下列函数允许直接测试一个文本检索解析器。 @@ -2668,7 +2662,7 @@ ts_token_type(parser_oid oid< - ts_token_type返回一个表,描述指定解析器能够识别的每一种词元。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: + ts_token_type返回一个表,描述指定解析器能够识别的每一种词元类型。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: SELECT * FROM ts_token_type('default'); @@ -2706,7 +2700,7 @@ SELECT * FROM ts_token_type('default'); 词典测试 - ts_lexize函数帮助词典测试。 + ts_lexize函数便于测试词典。 @@ -2764,17 +2758,17 @@ SELECT plainto_tsquery('supernovae stars'); - 文本搜索的首选索引类型 + 文本检索的首选索引类型 - 文本搜索 + 文本检索 索引 - 有两种索引可以用来加速全文搜索:GIN和 + 有两种索引可以用来加速全文检索:GINGiST。 - 请注意,索引对于全文搜索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 + 请注意,索引对于全文检索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 @@ -2788,7 +2782,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GIN - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIN (column); @@ -2808,7 +2802,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GiST - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIST (column [ { DEFAULT | tsvector_ops } (siglen = number) ] ); @@ -2818,7 +2812,7 @@ SELECT plainto_tsquery('supernovae stars'); 创建基于 GiST(广义搜索树)的索引。 column可以是tsvectortsquery类型。 - 可选的整数参数siglen确定签名长度(有关详细信息,请参见下文)。 + 可选的整数参数siglen确定以字节为单位的签名长度(有关详细信息,请参见下文)。 @@ -2827,7 +2821,7 @@ SELECT plainto_tsquery('supernovae stars'); - GIN 索引是文本搜索的首选索引类型。作为倒排索引,每个词(词位)在 + GIN 索引是文本检索的首选索引类型。作为倒排索引,每个词(词位)在 其中都有一个索引项,其中有压缩过的匹配位置的列表。多词搜索可以找到 第一个匹配,然后使用该索引移除缺少额外词的行。GIN 索引只存储 tsvector值的词(词位),并且不存储它们的权重标签。因此, @@ -2835,19 +2829,19 @@ SELECT plainto_tsquery('supernovae stars'); - 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。以字节为单位的签名长度由可选整数参数 siglen 的值决定。 默认签名长度(未指定 siglen 时)为 124 字节,最大签名长度为 2024 字节。该签名通过哈希每一个词到一个 n 位串中的一个单一位来产生,通过将所有这些位 OR 在一起产生一个 n 位的文档签名。当两个词哈希到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。更长的签名导致更精确的搜索(扫描索引的一小部分和更少的堆页面),但代价是更大的索引。 + 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。以字节为单位的签名长度由可选整数参数 siglen 的值决定。 默认签名长度(未指定 siglen 时)为 124 字节,最大签名长度为 2024 字节。该签名通过将每个词 hash 到一个 n 位串中的一位,再将所有这些位进行 OR 运算来生成,结果是一个 n 位的文档签名。当两个词 hash 到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。更长的签名导致更精确的搜索(扫描更小比例的索引和更少的堆页面),但代价是更大的索引。 - GiST 可以构建为覆盖索引,例如使用 INCLUDE 子句。被包含的列可以具有没有任何 GiST 操作符类的数据类型。被包含的属性会以未压缩形式存储。 + GiST 可以构建为覆盖索引,即使用 INCLUDE 子句。被包含的列可以具有没有任何 GiST 操作符类的数据类型。被包含的属性会以未压缩形式存储。 - 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的可用性。假匹配的可能性取决于几个因素,特别是唯一词的数量,因此推荐使用词典来缩减这个数量。 + 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的实用性。假匹配的可能性取决于几个因素,特别是不同词的数量,因此推荐使用词典来缩减这个数量。 - 注意GIN索引的构件时间常常可以通过增加来改进,而GiST索引的构建时间则与该参数无关。 + 注意GIN索引的构建时间常常可以通过增加来改进,而GiST索引的构建时间则对该参数不敏感。 @@ -2861,7 +2855,7 @@ SELECT plainto_tsquery('supernovae stars'); <application>psql</application> 支持 - 关于文本搜索配置对象的信息可以在psql中使用一组命令获得: + 关于文本检索配置对象的信息可以在psql中使用一组命令获得: \dF{d,p,t}+ PATTERN @@ -2869,7 +2863,7 @@ SELECT plainto_tsquery('supernovae stars'); - 可选参数 PATTERN 可以是文本搜索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: + 可选参数 PATTERN 可以是文本检索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: => \dF *fulltext* @@ -2896,7 +2890,7 @@ SELECT plainto_tsquery('supernovae stars'); \dF+ PATTERN - 列出文本搜索配置(加上 + 可显示更多细节)。 + 列出文本检索配置(加上 + 可显示更多细节)。 => \dF russian List of text search configurations @@ -2937,7 +2931,7 @@ Parser: "pg_catalog.default" \dFd+ PATTERN - 列出文本搜索词典(加上 + 可显示更多细节)。 + 列出文本检索词典(加上 + 可显示更多细节)。 => \dFd List of text search dictionaries @@ -2950,7 +2944,6 @@ Parser: "pg_catalog.default" pg_catalog | danish_stem | snowball stemmer for danish language pg_catalog | dutch_stem | snowball stemmer for dutch language pg_catalog | english_stem | snowball stemmer for english language - pg_catalog | estonian_stem | snowball stemmer for estonian language pg_catalog | finnish_stem | snowball stemmer for finnish language pg_catalog | french_stem | snowball stemmer for french language pg_catalog | german_stem | snowball stemmer for german language @@ -2982,7 +2975,7 @@ Parser: "pg_catalog.default" \dFp+ PATTERN - 列出文本搜索解析器(加上 + 可显示更多细节)。 + 列出文本检索解析器(加上 + 可显示更多细节)。 => \dFp List of text search parsers @@ -3035,7 +3028,7 @@ Parser: "pg_catalog.default" \dFt+ PATTERN - 列出文本搜索模板(加上 + 可显示更多细节)。 + 列出文本检索模板(加上 + 可显示更多细节)。 => \dFt List of text search templates @@ -3058,7 +3051,7 @@ Parser: "pg_catalog.default" 限制 - PostgreSQL 当前文本搜索特性的限制如下: + PostgreSQL 当前文本检索特性的限制如下: 每个词位的长度必须小于 2 千字节 @@ -3086,12 +3079,12 @@ Parser: "pg_catalog.default" - 为了对比,PostgreSQL 8.1 的文档包含 10,441 个唯一词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 + 为了对比,PostgreSQL 8.1 的文档包含 10,441 个不同词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 - 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个唯一词。 + 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个不同词。 diff --git a/zh/16/unaccent.sgml b/zh/16/unaccent.sgml index be5b7974..e537c27e 100644 --- a/zh/16/unaccent.sgml +++ b/zh/16/unaccent.sgml @@ -1,18 +1,18 @@ - unaccent — 去除变音符号的文本搜索词典 + unaccent — 去除变音符号的文本检索词典 unaccent - unaccent是一个文本搜索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤字典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文搜索能够以不区分重音的方式处理文本。 + unaccent是一个文本检索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤词典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文检索能够以不区分重音的方式处理文本。 - unaccent当前的实现还不能作为thesaurus词典的正规化字典使用。 + unaccent当前的实现还不能作为thesaurus词典的正规化词典使用。 @@ -64,22 +64,11 @@ - - - 某些字符(例如数字符号)在其转换规则中可能需要空白字符。在这种情况下,可以用双引号把转换后的字符括起来。如果转换后的字符中本身要包含双引号,则需要再用一个双引号对其转义。例如: - -¼ " 1/4" -½ " 1/2" -¾ " 3/4" -“ """" -” """" - - - + - 与其他PostgreSQL文本搜索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含不可转换字符的行都会被静默忽略,因此规则文件中可以包含不适用于当前编码的规则。 + 与其他PostgreSQL文本检索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含不可转换字符的行都会被静默忽略,因此规则文件中可以包含不适用于当前编码的规则。 @@ -93,7 +82,7 @@ 用法 - 安装unaccent扩展会创建一个文本搜索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 + 安装unaccent扩展会创建一个文本检索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 mydb=# ALTER TEXT SEARCH DICTIONARY unaccent (RULES='my_rules'); @@ -114,7 +103,7 @@ mydb=# select ts_lexize('unaccent','Hôtel'); - 下面的示例展示了如何将unaccent词典插入到文本搜索配置中: + 下面的示例展示了如何将unaccent词典插入到文本检索配置中: mydb=# CREATE TEXT SEARCH CONFIGURATION fr ( COPY = french ); mydb=# ALTER TEXT SEARCH CONFIGURATION fr @@ -145,7 +134,7 @@ mydb=# select ts_headline('fr','Hôtel de la Mer',to_tsquery('fr','Hotels') 函数 - unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本搜索环境之外使用。 + unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本检索环境之外使用。 @@ -157,7 +146,7 @@ unaccent(dictionary - 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本搜索词典。 + 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本检索词典。 diff --git a/zh/17/array.sgml b/zh/17/array.sgml index 10cc5e41..ead7c881 100644 --- a/zh/17/array.sgml +++ b/zh/17/array.sgml @@ -4,7 +4,7 @@ 数组 - array + 数组 @@ -15,8 +15,8 @@ 数组类型的声明 - array - declaration + 数组 + 声明 @@ -64,8 +64,8 @@ CREATE TABLE tictactoe ( 数组值输入 - array - constant + 数组 + 常量 @@ -86,7 +86,7 @@ CREATE TABLE tictactoe ( (这类数组常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。必要时可能需要显式指定类型。) + linkend="sql-syntax-constants-generic"/>中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。可能需要显式指定类型。) @@ -119,7 +119,7 @@ SELECT * FROM sal_emp; - 多维数组在每个维度上的范围必须匹配。不匹配会导致错误,例如: + 多维数组的各个子数组在每个维度上的长度必须匹配。不匹配会导致错误,例如: INSERT INTO sal_emp @@ -152,8 +152,8 @@ INSERT INTO sal_emp 访问数组 - array - accessing + 数组 + 访问 @@ -186,9 +186,9 @@ SELECT pay_by_quarter[3] FROM sal_emp; - 我们还可以访问数组或子数组的任意矩形切片。数组切片通过在一个或多个数组维度上写成 + 我们还可以访问数组的任意矩形切片,即子数组。数组切片通过在一个或多个数组维度上写成 lower-bound:upper-bound - 的形式来表示。例如,下面这个查询取回 Bill 在一周前两天日程安排中的第一个项目: + 的形式来表示。例如,下面这个查询取回 Bill 在一周中前两天里每天的首项日程: SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill'; @@ -235,11 +235,11 @@ SELECT schedule[:][1:1] FROM sal_emp WHERE name = 'Bill'; - 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回空值。此外,如果下标超出数组边界,也会返回空值(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是空值而不是错误。 + 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回 NULL。此外,如果下标超出数组边界,也会返回 NULL(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是 NULL 而不是错误。 - 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回空值。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是空值。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回空值。 + 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回 NULL。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是 NULL。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回 NULL。 @@ -293,8 +293,8 @@ SELECT cardinality(schedule) FROM sal_emp WHERE name = 'Carol'; 修改数组 - array - modifying + 数组 + 修改 @@ -331,7 +331,7 @@ UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}' - 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用空值填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含空值。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 + 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用 NULL 填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含 NULL。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 @@ -443,21 +443,21 @@ SELECT array_cat(ARRAY[5,6], ARRAY[[1,2],[3,4]]); 在简单情况下,优先使用上面讨论的连接操作符,而不是直接调用这些函数。不过,由于连接操作符被重载以同时服务于这三种情形,所以在某些场景下使用这些函数之一有助于避免歧义。例如,考虑: -SELECT ARRAY[1, 2] || '{3, 4}'; -- the untyped literal is taken as an array +SELECT ARRAY[1, 2] || '{3, 4}'; -- 未指定类型的字面量被当作数组 ?column? ----------- {1,2,3,4} -SELECT ARRAY[1, 2] || '7'; -- so is this one +SELECT ARRAY[1, 2] || '7'; -- 这个字面量也一样 ERROR: malformed array literal: "7" -SELECT ARRAY[1, 2] || NULL; -- so is an undecorated NULL +SELECT ARRAY[1, 2] || NULL; -- 未加类型修饰的 NULL 也一样 ?column? ---------- {1,2} (1 row) -SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant +SELECT array_append(ARRAY[1, 2], NULL); -- 这可能才是原本想表达的意思 array_append -------------- {1,2,NULL} @@ -471,8 +471,8 @@ SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant 在数组中搜索 - array - searching + 数组 + 搜索 @@ -552,7 +552,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); 数组输入和输出语法 - array + 数组 I/O @@ -565,7 +565,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); - 默认情况下,数组各维度的下界索引值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: + 默认情况下,数组各维度的下界下标值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2 FROM (SELECT '[1:1][-2:-1][3:5]={{{1,2,3},{4,5,6}}}'::int[] AS f1) AS ss; diff --git a/zh/17/catalogs.sgml b/zh/17/catalogs.sgml index 9ff7716f..2a69f115 100644 --- a/zh/17/catalogs.sgml +++ b/zh/17/catalogs.sgml @@ -320,27 +320,27 @@ pg_ts_config - 文本搜索配置 + 文本检索配置 pg_ts_config_map - 文本搜索配置的词元映射 + 文本检索配置的词元映射 pg_ts_dict - 文本搜索字典 + 文本检索词典 pg_ts_parser - 文本搜索分析器 + 文本检索解析器 pg_ts_template - 文本搜索模板 + 文本检索模板 @@ -7695,12 +7695,12 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config目录包含表示文本搜索配置的条目。一个配置指定某个特定的文本搜索分析器,以及针对该分析器每种输出词元类型所定义的字典列表。分析器由pg_ts_config项表示,而词元到字典的映射则由pg_ts_config系统目录包含表示文本检索配置的条目。一个配置指定某个特定的文本检索解析器,以及针对该解析器每种输出词元类型所定义的词典列表。解析器记录在pg_ts_config条目中,而词元到词典的映射则由pg_ts_config_map中的辅助项定义。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。 @@ -7732,7 +7732,7 @@ SCRAM-SHA-256$<iteration count>:&l cfgname name - 文本搜索配置名 + 文本检索配置名 @@ -7762,7 +7762,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_ts_parser.oid - 该配置的文本搜索分析器的OID + 该配置的文本检索解析器的 OID @@ -7779,11 +7779,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config_map目录包含的项展示了对于每一个文本搜索配置的每一种输出词元类型,有哪些文本搜索字典可供查询以及以何种顺序。 + pg_ts_config_map 系统目录中的条目说明了,对于每个文本检索配置所用解析器的每种输出词元类型,应当查询哪些文本检索词典以及查询的顺序。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7816,7 +7816,7 @@ SCRAM-SHA-256$<iteration count>:&l maptokentype int4 - 一种由配置的分析器送出的词元类型 + 一种由配置的解析器送出的词元类型 @@ -7835,7 +7835,7 @@ SCRAM-SHA-256$<iteration count>:&l (参考 pg_ts_dict.oid - 要查询的文本搜索字典的OID + 要查询的文本检索词典的 OID @@ -7852,11 +7852,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_dict目录包含定义文本搜索字典的项。一个字典依赖于一个文本搜索模板,它指定了所有需要的函数实现,字典本身则为模板支持的用户可设置参数提供值。这种分工允许无权限的用户创建字典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 + pg_ts_dict系统目录包含定义文本检索词典的项。一个词典依赖于一个文本检索模板,它指定了所有需要的实现函数,词典本身则为模板支持的用户可设置参数提供值。这种分工允许普通用户创建词典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7888,7 +7888,7 @@ SCRAM-SHA-256$<iteration count>:&l dictname name - 文本搜索字典名 + 文本检索词典名 @@ -7898,7 +7898,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_namespace.oid - 包含该字典的名字空间OID + 包含该词典的名字空间的 OID @@ -7908,7 +7908,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_authid.oid - 字典的拥有者 + 词典的拥有者 @@ -7918,7 +7918,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_ts_template.oid - 该字典的文本搜索模板的OID + 该词典的文本检索模板的 OID @@ -7944,11 +7944,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_parser目录包含定义文本搜索分析器的项。一个分析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个分析器必须用C语言级别的函数实现,创建新分析器的工作只限于数据库的超级用户。 + pg_ts_parser系统目录包含定义文本检索解析器的项。一个解析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个解析器必须用 C 语言级别的函数实现,创建新解析器的工作只限于数据库的超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7980,7 +7980,7 @@ SCRAM-SHA-256$<iteration count>:&l prsname name - 文本搜索分析器的名字 + 文本检索解析器的名字 @@ -7990,7 +7990,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_namespace.oid - 包含此分析器的名字空间的OID + 包含此解析器的名字空间的 OID @@ -8000,7 +8000,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器启动函数的OID + 解析器启动函数的 OID @@ -8010,7 +8010,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的下一词元函数的OID + 解析器的下一词元函数的 OID @@ -8020,7 +8020,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的关闭函数的OID + 解析器的关闭函数的 OID @@ -8030,7 +8030,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器标题函数的 OID(如果没有则为零) + 解析器的 headline 函数的 OID(如果没有则为零) @@ -8040,7 +8040,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的词汇类型函数的OID + 解析器的 lextype 函数的 OID @@ -8057,11 +8057,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_template目录包含定义文本搜索模板的项。一个模板是一类文本搜索字典的实现骨架。由于一个模板必须用C语言级别的函数实现,新模板的创建只限于数据库超级用户。 + pg_ts_template系统目录包含定义文本检索模板的项。一个模板是一类文本检索词典的实现骨架。由于一个模板必须用 C 语言级别的函数实现,新模板的创建只限于数据库超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -8093,7 +8093,7 @@ SCRAM-SHA-256$<iteration count>:&l tmplname name - 文本搜索模板的名字 + 文本检索模板的名字 diff --git a/zh/17/config.sgml b/zh/17/config.sgml index cf744a0a..410b33af 100644 --- a/zh/17/config.sgml +++ b/zh/17/config.sgml @@ -2835,7 +2835,7 @@ include_dir 'conf.d' 配置 - 恢复的 + 恢复 一般设置 @@ -2897,7 +2897,7 @@ include_dir 'conf.d' 配置 恢复 - 一个备库 + 备库 @@ -3348,7 +3348,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows - 列出安装在 所指定位置中、同时也被信任可供复制客户端用作逻辑输出插件的库。 + 列出安装在 所指定位置中、同时也受信任、可供复制客户端用作逻辑输出插件的库。 任何针对其他库的逻辑解码或 复制请求都将被拒绝。所有用户都受此限制。 默认值为 'pgoutput, test_decoding',它们是标准 @@ -3886,16 +3886,18 @@ ANY num_sync ( ),从而实际上限制了服务器上可以创建多少逻辑复制订阅。 - 将其设置为低于当前正在跟踪的复制源数量(体现在pg_replication_origin_status中)会阻止服务器启动。 - 默认值为 10。该参数只能在服务器启动时设置。 - max_replication_slots至少必须设置为订阅者上要添加的订阅数量,再加上一些用于表同步的预留。 - - + + 指定可以同时跟踪多少个复制源(参见),从而实际上限制了服务器上可以创建多少个逻辑复制订阅。将它设置为低于当前正在跟踪的复制源数量(可在pg_replication_origin_status中看到)会阻止服务器启动。max_replication_slots 至少必须设置为订阅者上要添加的订阅数量,再加上一些用于表同步的预留。 + + + + 注意,这个参数在发送服务器上也适用,但含义不同。 + + @@ -4003,8 +4005,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( )。 + 设置规划器对一系列顺序磁盘页面读取中单次读取的代价估计。默认值是 1.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -4382,7 +4377,7 @@ ANY num_sync ( )。 + 设置规划器对一次非顺序磁盘页面读取的代价估计。默认值是 4.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -4395,14 +4390,13 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( 。 如果指定值时没有单位,则以块为单位,即BLCKSZ字节,通常为8kB。默认值是512千字节(512kB)。 @@ -4528,13 +4522,13 @@ ANY num_sync ( num_sync ( - 遗传查询优化 + 遗传查询优化器 - GEQO是一个使用探索式搜索来执行查询规划的算法。它可以降低负载查询的规划时间。 同时,GEQO的检索是随机的,因此它的规划可能会不可确定。 更多信息参阅Chapter 50。 - 遗传查询规划器(GEQO)是一种使用启发式搜索来进行查询规划的算法。它可以降低对于复杂查询(连接很多表的查询)的规划时间,但是代价是它产生的计划有时候要差于使用穷举搜索算法找到的计划。详见。 + 遗传查询优化器(GEQO)是一种使用启发式搜索进行查询规划的算法。它可以缩短复杂查询(连接很多关系的查询)的规划时间,代价是生成的计划有时不如常规穷举搜索算法找到的计划。更多信息见 @@ -4615,7 +4608,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( .) + 目前,约束排除仅在通常用于通过继承树实现表分区的情况下默认启用。为所有表启用它会增加额外的规划开销,这在简单查询上相当明显,而且通常不会为简单查询带来好处。如果没有通过传统继承方式进行分区的表,你可能希望完全关闭它。(注意,分区表的等效功能由另一个参数控制。) @@ -4864,13 +4854,7 @@ SELECT * FROM parent WHERE key = 2400; - 准备语句(显式准备或隐式生成的,例如 PL/pgSQL)可以使用自定义或通用计划执行。 - 使用其特定的参数值集为每个执行重新生成自定义计划,而通用计划不依赖于参数值,并且可以在执行中重复使用。 - 因此,使用通用计划可以节省计划时间,但如果理想计划严重依赖参数值,则通用计划可能效率低下。 - 这些选项之间的选择通常是自动进行的,但可以通过plan_cache_mode覆盖它。 - 允许的值为 auto (默认的),force_custom_planforce_generic_plan。 - 这个设置是在执行缓存计划时考虑,而不是在准备计划时考虑。 - 更多信息请参阅 . + 预备语句(无论是显式预备的,还是由 PL/pgSQL 等隐式生成的)可以使用自定义计划或通用计划执行。自定义计划会根据每次执行的具体参数值重新生成,而通用计划不依赖参数值,可以在多次执行之间复用。因此,使用通用计划能够节省规划时间,但如果理想计划高度依赖参数值,通用计划可能效率较低。系统通常会自动选择这两种计划,但可以通过plan_cache_mode覆盖这一选择。允许的值为auto(默认值)、force_custom_planforce_generic_plan。系统在执行缓存计划时考虑此设置,而不是在预备计划时。更多信息见 @@ -4888,7 +4872,7 @@ SELECT * FROM parent WHERE key = 2400; 设置规划器对递归查询 的工作表的平均大小的估计值,作为查询初始非递归项的估计大小的倍数。 这有助于规划器选择将工作表与查询的其他表连接的最合适方法。 - 默认值为10.0。当递归从一步到下一步的fan-out较低时,如最短路径查询中的示例,使用较小的值(如1.0)可能有所帮助。 + 默认值为10.0。当递归从一步到下一步的扇出较低时,例如最短路径查询,使用较小的值(如1.0)可能有所帮助。 图分析查询可能会从大于默认值的设置中受益。 @@ -4907,7 +4891,7 @@ SELECT * FROM parent WHERE key = 2400; - 在哪里做日志 + 日志记录到哪里 日志写到哪里 @@ -4915,7 +4899,7 @@ SELECT * FROM parent WHERE key = 2400; current_logfiles - 和日志_目的地配置参数 + 和 log_destination 配置参数 @@ -4963,13 +4947,13 @@ jsonlog log/postgresql.json 当由于轮换而创建新的日志文件时,以及重新加载log_destination时,current_logfiles会被重新创建。 当log_destination中不包含stderrcsvlogjsonlog, - 以及日志收集器被禁用时,它会被移除。 + 或者日志收集器被禁用时,它会被移除。 - 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设备LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: + 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设施LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: local0.* /var/log/postgresql @@ -4977,7 +4961,7 @@ local0.* /var/log/postgresql - 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源极其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见。 + 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源及其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见 @@ -4993,20 +4977,20 @@ local0.* /var/log/postgresql - 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 + 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息可能不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 - 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供方法来轮转日志文件。还有,在某些不使用日志收集器的平台上可能会导致丢失或者混淆日志输出,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 + 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供便捷的方法来轮转日志文件。还有,在某些平台上,不使用日志收集器可能会导致日志输出丢失或混杂,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 - 日志收集器被设计成从来不会丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 + 日志收集器被设计成从来不会丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它可能会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 @@ -5040,7 +5024,7 @@ local0.* /var/log/postgresql logging_collector被启用时,这个参数设置被创建的日志文件的文件名。 - 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何时区独立的%转义,计算将在由指定的时区中完成)。 + 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何依赖时区的%转义,计算将在由指定的时区中完成)。 被支持的%转义和开放组织的strftime说明中列举的类似。 注意系统的strftime不会被直接使用,因此平台相关(非标准)的扩展无法工作。 默认是postgresql-%Y-%m-%d_%H%M%S.log。 @@ -5078,7 +5062,7 @@ local0.* /var/log/postgresql - 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的十进制格式,该数字必须以一个0(零)开始)。 + 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的八进制格式,该数字必须以一个0(零)开始)。 @@ -5144,7 +5128,7 @@ local0.* /var/log/postgresql - 示例:要保留 24 小时的日志,每个小时一个日志文件,但是在日志文件尺寸超过 1GB 时轮转。可以这样做:将log_filename设置为server_log.%H%M、 + 示例:要保留 24 小时的日志,每个小时一个日志文件,如果日志文件尺寸超过 1GB,也会提前轮转。可以这样做:将log_filename设置为server_log.%H%M、 将log_truncate_on_rotation设置为on、 将log_rotation_age设置为60并且 将log_rotation_size设置为1000000。 @@ -5163,7 +5147,7 @@ local0.* /var/log/postgresql - 当启用了向syslog记录时,这个参数决定要使用的syslog设备。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4、 + 当启用了向syslog记录时,这个参数决定要使用的syslog设施。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4LOCAL5LOCAL6LOCAL7中选择,默认值是LOCAL0。还请参阅系统的syslog守护进程的文档。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -5218,7 +5202,7 @@ local0.* /var/log/postgresql - 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,有必要让消息保持逻辑上的整体性(也更加有用)。 + 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,让消息保持逻辑上的完整性可能是必要的,也可能更有用。 @@ -5237,7 +5221,7 @@ local0.* /var/log/postgresql - 当启用了向事件日志记录时,这个参数决定用来标识日志中PostgreSQL消息的程序名。默认值是PostgreSQL。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 当启用了向事件日志记录时,这个参数决定用来标识日志中PostgreSQL消息的程序名。默认值是PostgreSQL。这个参数只能在服务器启动时设置。 @@ -5283,9 +5267,7 @@ local0.* /var/log/postgresql - 控制在服务器日志中记录哪些导致错误条件的SQL语句。当前的SQL语句将包含在任何指定 - severity - 或更高消息的日志条目中。 + 控制在服务器日志中记录哪些导致错误条件的SQL语句。对于达到指定严重级别或更高级别的消息,其日志条目中会包含当前 SQL 语句。 有效值为DEBUG5DEBUG4DEBUG3DEBUG2DEBUG1、 @@ -5325,7 +5307,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -5363,7 +5345,7 @@ local0.* /var/log/postgresql - log_min_duration_statement的其他注释也适用于此设置。 + log_min_duration_statement的其他说明也适用于此设置。 @@ -5378,8 +5360,8 @@ local0.* /var/log/postgresql - 确定持续时间超过的语句的比例将被记录。 - 采样是随机的,例如0.5表示统计上有一半的机会任何给定的语句将被记录。 + 确定持续时间超过的语句中,将被记录的语句比例。 + 采样是随机的,例如0.5表示任意给定语句被记录的统计概率为二分之一。 默认值为1.0,表示记录所有采样的语句。 将此设置为零将禁用采样语句持续时间记录,与将log_min_duration_sample设置为-1相同。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -5397,7 +5379,7 @@ local0.* /var/log/postgresql - 设置所有语句都被记录的事务的比例,除了其他原因记录的语句。它适用于每个新事务,无论其语句的持续时间如何。 + 设置需要记录全部语句的事务比例,这些记录是在因其他原因记录的语句之外额外进行的。它适用于每个新事务,无论其语句的持续时间如何。 采样是随机的,例如0.1表示任何给定事务被记录的统计概率是十分之一。 log_transaction_sample_rate可以帮助构建事务样本。 默认值为0,表示不记录任何额外事务的语句。将其设置为1会记录所有事务的所有语句。 @@ -5422,8 +5404,7 @@ local0.* /var/log/postgresql - 设置启动进程在长时间运行的操作仍在进行时记录消息的时间间隔, - 以及该操作进一步进展消息之间的间隔时间。默认值为10秒。 + 设置启动进程在长时间运行的操作开始后,等待多久才记录第一条进度消息,以及此后该操作的进度消息之间的时间间隔。默认值为10秒。 设置为0会禁用该功能。如果未指定单位, 则将其视为毫秒。此设置分别应用于每个操作。 此参数只能在postgresql.conf文件或服务器命令行中设置。 @@ -5465,7 +5446,7 @@ local0.* /var/log/postgresql DEBUG1 .. DEBUG5 - 为开发者提供连续的更详细的信息。 + 为开发者提供逐级更加详细的信息。 DEBUG INFORMATION @@ -5525,7 +5506,7 @@ local0.* /var/log/postgresql - 记录什么到日志 + 记录哪些内容 @@ -5546,7 +5527,7 @@ local0.* /var/log/postgresql - application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。它也会被通过包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为C 风格的十六进制转义序列。 + application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。也可以通过将其包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为C 风格的十六进制转义序列。 @@ -5573,7 +5554,6 @@ local0.* /var/log/postgresql - 这个参数启用发出各种调试输出。当设置时,会打印生成的解析树, 查询重写输出,或执行的每个查询的执行计划。这些信息是在LOG 信息级别发出,因此默认的,它们会出现在服务器日志中,但不会发送给客户端。 可以通过 client_min_messages和/或log_min_messages 来设置。这些参数缺省是off。 这些参数将会让多种调试输出被发出。当被设置时,它们为每一个被执行的查询打印结果分析树、查询重写器输出或执行计划。这些消息在LOG消息级别上被发出,因此默认情况下它们将出现在服务器日志中但不会被发送到客户端。你可以通过调整和/或来改变这种情况。这些参数默认是关闭的。 @@ -5607,10 +5587,10 @@ local0.* /var/log/postgresql - 每次由自动清理执行的操作都会被记录,如果运行时间至少达到指定时间。将此设置为零会记录所有自动清理操作。 + 当自动清理执行的操作运行时间至少达到指定时间时,就会记录该操作。将此设置为零会记录所有自动清理操作。 -1会禁用记录自动清理操作。如果未指定单位,则将其视为毫秒。 例如,如果将其设置为250ms,则所有运行时间为250ms或更长的自动清理和分析都将被记录。 - 此外,当此参数设置为任何值而不是-1时,如果由于冲突的锁定或同时删除的关系而跳过自动清理操作,则会记录消息。 + 此外,当此参数设置为任何非-1值时,如果由于冲突锁或关系被并发删除而跳过自动清理操作,则会记录消息。 默认值为10min。启用此参数可帮助跟踪自动清理活动。 此参数只能在postgresql.conf文件或服务器命令行中设置;但可以通过更改表存储参数来覆盖对单个表的设置。 @@ -5689,7 +5669,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -5712,7 +5692,7 @@ local0.* /var/log/postgresql 控制在服务器日志中记录的每条消息的详细程度。有效值为TERSE, - DEFAULTVERBOSE,每个值都会添加更多字段到显示的消息中。 + DEFAULTVERBOSE,它们依次在显示的消息中增加更多字段。 TERSE不包括DETAILHINTQUERYCONTEXT错误信息的记录。 VERBOSE输出包括SQLSTATE错误代码 @@ -5732,7 +5712,7 @@ local0.* /var/log/postgresql - 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致很微小的性能损失。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致不可忽视的性能开销。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -5751,7 +5731,7 @@ local0.* /var/log/postgresql %字符开始转义序列,它将被按照下文描述的替换成状态信息。 未识别的转义被忽略。其他字符被直接复制到日志行。某些转义只被会话进程识别并且被主服务器进程等后台进程当作空。 通过指定一个在%之后和该选项之前的数字可以让状态信息左对齐或右对齐。 - 负值将导致在右边用空格填充状态信息已达到最小宽度,而正值则在左边填充。填充对于日志文件的人类可读性大有帮助。 + 负值将导致在右边用空格填充状态信息以达到最小宽度,而正值则在左边填充。填充对于日志文件的人类可读性大有帮助。 @@ -5814,8 +5794,8 @@ local0.* /var/log/postgresql %P - 并行组leader的进程ID,如果该进程是一个并行查询worker - no + 如果该进程是并行查询工作进程,则为并行组领导者的进程 ID + @@ -5832,8 +5812,8 @@ local0.* /var/log/postgresql %n - 带毫秒的时间戳(作为 Unix 时代) - no + 带毫秒精度的 Unix 时间戳 + @@ -5888,7 +5868,7 @@ local0.* /var/log/postgresql %Q 当前查询的查询标识符。 查询标识符默认是不计算的,所以这个部分将是零,除非 参数被激活或者配置了计算查询标识符的第三方模块 - yes + @@ -5907,7 +5887,7 @@ local0.* /var/log/postgresql %c转义打印一个准唯一的会话标识符,它由两个 4 字节的十六进制数(不带先导零)组成,以点号分隔。 - 这些数字是进程启动时间和进程 ID,因此%c也可以被用作保存打印这些项的方式的空间。 + 这些数字是进程启动时间和进程 ID,因此%c也可以用来节省空间地输出这两项信息。 例如,要从pg_stat_activity生成会话标识符,使用这个查询: SELECT to_hex(trunc(EXTRACT(EPOCH FROM backend_start))::integer) || '.' || @@ -5945,7 +5925,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 对于输出的行,%Q 总是报告零标识符, - 因为log_statement在标识符能被计算之前生成输出,包括无效标识符不能计算的无效语句。 + 因为log_statement在标识符能被计算之前生成输出,也包括无法计算标识符的无效语句。 @@ -5978,8 +5958,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 控制启动进程等待时间超过针对恢复冲突的deadlock_timeout的时候是否产生日志消息。 - 这对于决定恢复冲突是否会阻止恢复应用WAL有所帮助。 + 控制启动进程因恢复冲突而等待超过deadlock_timeout时是否产生日志消息。这有助于判断恢复冲突是否阻碍了恢复过程应用 WAL。 @@ -6006,8 +5985,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 此设置仅影响作为结果打印的日志消息,, 和相关的设置。 - 该设置的非零值会增加一些开销,特别是当参数以二进制形式发送时,因为需要转换为文本。 + 此设置仅影响由及相关设置产生的日志消息。此设置为非零值时会增加一些开销,特别是以二进制形式发送参数时,因为需要将参数转换为文本。 @@ -6051,7 +6029,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' UPDATEDELETETRUNCATE, 和COPY FROM。 如果PREPAREEXECUTE和 - EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个执行消息时会产生日志并且会包括绑定参数的值(任何内嵌的单引号会被双写)。 + EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个 Execute 消息时会产生日志并且会包括 Bind 参数的值(任何内嵌的单引号会被双写)。 @@ -6062,7 +6040,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在执行阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 + 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在 Execute 阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 @@ -6082,7 +6060,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 每个复制命令都会被记录在服务器日志中。 + 在服务器日志中记录每个复制命令,以及walsender进程获取和释放复制槽的操作。 有关复制命令的更多信息,请参见。 默认值为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -6101,8 +6079,8 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 控制临时文件名和大小的日志记录。 - 临时文件可以用于排序、哈希和临时查询结果。 - 如果通过此设置启用,每当删除临时文件时都会发出日志记录。 + 临时文件可以用于排序、hash 和临时查询结果。 + 如果通过此设置启用,每当删除临时文件时都会发出日志记录,其中文件大小以字节为单位。 值为零时记录所有临时文件信息,而正值仅记录大小大于或等于指定数据量的文件。 如果未指定单位,则将其视为千字节。 默认设置为-1,禁用此类日志记录。 @@ -6155,7 +6133,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 错误上下文、 导致错误的用户查询(如果有且被log_min_error_statement启用)、 错误位置所在的字符计数、 - 在 PostgreSQL 源代码中错误的位置(如果log_error_verbosity被设置为verbose)以及应用名,后端类型,并行组leader的进程ID和查询ID。 + 在 PostgreSQL 源代码中错误的位置(如果log_error_verbosity被设置为verbose)、应用名、后端类型、并行组领导者的进程 ID 和查询 ID。 下面是一个定义用来存储 CSV 格式日志输出的样表: @@ -6207,7 +6185,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 设置log_filenamelog_rotation_age为你的日志文件提供一种一致的、可预测的命名空间。这让你预测文件名会是怎样以及知道什么时候一个个体日志文件完成并且因此准备好被导入。 + 设置log_filenamelog_rotation_age,为日志文件提供一致且可预测的命名方案。这样就能预测文件名,并知道单个日志文件何时已完成写入、可以导入。 @@ -6236,12 +6214,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 使用JSON格式的日志输出 - 包括jsonloglog_destination列表中提供了一种方便的方式将日志文件导入到许多不同的程序中。此选项以JSON格式发出日志行。 + 将jsonlog加入log_destination列表,可以方便地将日志文件导入多种不同的程序。此选项以JSON格式输出日志行。 - 字段值为null的字符串字段将被排除在输出之外。 - 未来可能会添加其他字段。处理jsonlog输出的用户应忽略未知字段。 + 值为空值的字符串字段不会输出。将来可能会添加其他字段。处理jsonlog输出的用户应用程序应忽略未知字段。 @@ -6386,13 +6363,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; statement string - 客户提供的查询字符串 + 客户端提供的查询字符串 cursor_position number - 查询字符串中的光标索引 + 查询字符串中的游标索引 @@ -6446,7 +6423,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 进程标题 - 这些设置控制服务器进程的进程标题如何被修改。进程标题通常可以用ps或者 Windows 上的进程浏览器等程序来查看。详见。 + 这些设置控制服务器进程的进程标题如何修改。通常可以通过ps等程序查看进程标题,在 Windows 上则可以使用Process Explorer。详情参见 @@ -6480,7 +6457,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 每次服务器接收到新的SQL命令时,都可以更新进程标题。 + 启用后,每次服务器接收到新的 SQL 命令时都会更新进程标题。 在大多数平台上,默认情况下此设置为on,但在Windows上默认为off, 因为该平台更新进程标题的开销较大。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -6518,7 +6495,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对每个会话当前执行命令的信息收集,包括其标识符和命令开始执行的时间。 - 此参数默认为开启状态。请注意,即使启用了此信息,只有超级用户、具有 + 此参数默认为开启状态。请注意,即使启用了此参数,只有超级用户、具有 pg_read_all_stats角色权限的角色和拥有被报告会话的用户 (包括属于他们具有权限的角色的会话)才能看到此信息,因此不应构成安全风险。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -6536,7 +6513,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 为每个活动会话指定存储当前执行命令的文本所保留的内存量,它们被用于pg_stat_activity.query域。 + 为每个活动会话指定存储当前执行命令的文本所预留的内存量,它们被用于pg_stat_activity.query字段。 如果指定值时没有单位,则以字节为单位。默认值是 1024字节。这个参数只能在服务器启动时被设置。 @@ -6553,7 +6530,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对数据库活动的统计信息收集。 - 此参数默认为开启,因为自动清理守护进程需要收集的信息。 + 此参数默认为开启,因为自动清理守护进程需要这些收集到的信息。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -6606,7 +6583,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用函数调用次数和时间的跟踪。指定pl以仅跟踪过程语言函数, + 启用函数调用次数和耗时的跟踪。指定pl以仅跟踪过程语言函数, all以同时跟踪SQL和C语言函数。默认值为none, 即禁用函数统计跟踪。只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -6641,7 +6618,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - none适用于监控系统。如果值只被访问一次,它是最有效的。 + none最适合监控系统。如果值只被访问一次,它是最有效的。 cache确保重复访问产生相同的值,这对涉及自连接的查询很重要。 snapshot在交互式检查统计信息时可能很有用,但开销较高, 特别是存在许多数据库对象时。 @@ -6668,21 +6645,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用查询标识符的内核计算。 - 查询标识符可以在 pg_stat_activity - 视图中显示,使用 EXPLAIN,或者如果通过 - 参数进行配置,则可以在日志中发出。 - 扩展还需要计算查询标识符。 - 请注意,如果内核查询标识符计算方法不可接受,也可以使用外部模块。 - 在这种情况下,必须始终禁用内核计算。 - 有效值为 off(始终禁用), - on(始终启用),auto, - 允许诸如 这样的模块 - 自动启用它,并且 regress 具有与 - auto 相同的效果,只是查询标识符不会显示在 - EXPLAIN 输出中,以便促进自动回归测试。 - 默认值为 auto。 + 启用内置的查询标识符计算功能。查询标识符可以显示在pg_stat_activity视图或EXPLAIN的输出中,也可以通过参数配置后写入日志。扩展也要求计算查询标识符。注意,如果内置的查询标识符计算方法不符合要求,可以改用外部模块。在这种情况下,必须始终禁用内置计算功能。有效值为off(始终禁用)、on(始终启用)、auto(允许等模块自动启用此功能),以及regress。后者与auto效果相同,但不会在EXPLAIN输出中显示查询标识符,以便进行自动回归测试。默认值为auto @@ -6722,7 +6685,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 对于每个查询,将各自模块的性能统计输出到服务器日志中。这是一个简单的性能分析工具,类似于Unix getrusage()操作系统功能。 - log_statement_stats报告总语句统计,而其他选项报告每个模块的统计信息。 + log_statement_stats报告整个语句的统计信息,而其他选项报告每个模块的统计信息。 log_statement_stats不能与任何单独模块选项一起启用。所有这些选项默认情况下都是禁用的。 只有超级用户和具有适当SET权限的用户才能更改这些设置。 @@ -7003,7 +6966,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; DEBUG1LOGNOTICEWARNINGERROR。 每个级别都包括其后的所有级别。级别越靠后,被发送的消息越少。默认值是NOTICE。 - 注意LOG在这里有与中不同的排名。 + 注意LOG在这里的排序与中的不同。 @@ -7023,15 +6986,15 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,用于进行搜索该对象的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 + 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,搜索该对象时的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 - search_path的值必需是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被安静地忽略。 + search_path的值必须是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被静默忽略。 - 如果列表项之一是特殊名$user,则具有SESSION_USER返回的名字的模式将取代它(如果有这样一个模式并且该用户有该模式的USAGE权限;如果没有,$user会被忽略)。 + 如果列表项之一是特殊名$user,则具有CURRENT_USER返回的名字的模式将取代它(如果有这样一个模式并且该用户有该模式的USAGE权限;如果没有,$user会被忽略)。 @@ -7056,11 +7019,12 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个参数的缺省值是"$user", public。这种设置支持一个数据库(其中没有用户拥有私有模式,并且所有人共享使用public)、每个用户私有模式及其组合的共享使用。其它效果可以通过全局或者针对每个用户修改默认搜索路径设置获得。 + 这个参数的默认值是"$user", public。这种设置支持共享使用数据库(用户没有私有模式,所有人共享使用public)、每个用户拥有私有模式,以及二者的组合。 + 还可以通过全局或针对每个用户修改默认搜索路径设置来获得其他效果。 - 更多有关方案处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 + 更多有关模式处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 @@ -7080,7 +7044,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,只要有至少一条策略被应用则查询就会失败。默认为on。受限的行可见性会导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS)属性的角色没有效果。 + 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,原本会应用至少一条策略的查询就会失败。默认为on。受限的行可见性可能导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS属性的角色)没有效果。 @@ -7099,8 +7063,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个参数指定了在创建表或物化视图时使用的默认表访问方法,如果CREATE命令没有明确指定访问方法, - 或者当使用SELECT ... INTO时,不允许指定表访问方法。默认值是heap。 + 创建表或物化视图时,如果CREATE命令没有显式指定访问方法,或者使用了不允许指定表访问方法的SELECT ... INTO,则使用此参数指定的默认表访问方法。默认值为heap @@ -7120,7 +7083,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建企图将失败。 + 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建尝试将失败。 @@ -7128,7 +7091,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当创建数据库时也会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 + 创建数据库时也不会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 @@ -7177,11 +7140,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被放置在里表中的连续表空间中。如果列表被选中元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 + 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被依次放置在列表中的连续表空间中。如果列表中被选中的元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 - 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,类似于为用户指定一个不具有CREATE权限的表空间。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特殊地,使用一个在postgresql.conf中设置的值时,这条规则起效。 + 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,指定一个用户不具有CREATE权限的表空间也同样是错误。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特别是,使用一个在postgresql.conf中设置的值时,这条规则起效。 @@ -7206,7 +7169,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 这个参数通常为打开。 当设置为off时,它禁用期间对例程体字符串的验证。 - 禁用验证避免了验证处理的副作用,特别避免了如向前引用导致的伪肯定。 + 禁用验证避免了验证处理的副作用,特别是避免前向引用等问题导致的误报。 在代表其他用户载入函数之前设置这个参数为offpg_dump会自动这样做。 @@ -7249,7 +7212,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态 。默认是off(读/写)。 + 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态。默认是off(读/写)。 @@ -7272,11 +7235,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当运行在可串行化隔离级别时,一个可延迟只读 SQL 事务可以在它被允许继续之前延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的负荷;因此串行化代码将没有任何理由因为并发更新而强制它中断,使得这个选项适合于长时间运行的只读事务。 + 当运行在serializable隔离级别时,一个可延迟只读 SQL 事务可能在获准继续之前被延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的开销;因此串行化代码将没有任何理由因为并发更新而强制它中止,使得这个选项适合于长时间运行的只读事务。 - 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些操作在低于可串行化隔离级别上的事务无效。默认值是off。 + 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些运行在低于serializable隔离级别上的事务无效。默认值是off @@ -7320,7 +7283,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的只读状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -7340,7 +7303,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的可延迟性状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -7364,7 +7327,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 这个设置的预期用途是由逻辑复制系统在应用所复制的更改时将它设置为replica。 - 其效果将是触发器和规则(没有对其默认配置做修改)在复制机上将不会被触发。 + 其效果将是触发器和规则(没有对其默认配置做修改)在副本上将不会被触发。 更多信息请参考ALTER TABLE的子句ENABLE TRIGGER以及ENABLE RULE @@ -7394,9 +7357,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 超时从命令到达服务器的时间开始计算,一直到它被服务器完成为止。 - 如果单个简单查询消息中出现多个 SQL 语句,超时将分别应用于每个语句。(PostgreSQL 13 之前的版本通常将超时应用于整个查询字符串。 - 在扩展查询协议中,当任何与查询相关的消息(解析、绑定、执行、描述)到达时,超时就开始运行,并且可以通过执行完成或同步消息来取消超时。 + 超时从命令到达服务器时开始计算,直到服务器完成该命令为止。 + 如果单个简单查询消息中出现多个 SQL 语句,超时将分别应用于每个语句。 + (PostgreSQL 13 之前的版本通常将超时应用于整个查询字符串。) + 在扩展查询协议中,当任何与查询相关的消息(Parse、Bind、Execute、Describe)到达时开始计时, + 并在处理完 Execute 或 Sync 消息时取消计时。 @@ -7440,13 +7405,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 如果任何语句在试图获取表、索引、行或其他数据库对象上的锁时等到超过指定的时间量,该语句将被中止。 + 如果任何语句在试图获取表、索引、行或其他数据库对象上的锁时等待超过指定的时间量,该语句将被中止。 该时间限制独立地应用于每一次锁获取尝试。该限制会应用到显式锁定请求(如LOCK TABLE或不带NOWAITSELECT FOR UPDATE)和隐式获得的锁。 如果指定值时没有单位,则以毫秒为单位。一个零值(默认)将禁用超时。 - 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为事务超时将总是第一个被触发。 + 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为语句超时将总是第一个被触发。 如果log_min_error_statement 被设置为ERROR 或更低,超时的语句将被记录。 @@ -7466,15 +7431,14 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 终止任何已经闲置(这是指,等待客户端查询)超过这个参数所指定时间量的打开事务的会话。 - 如果这个值指定时没有单位,它被设为毫秒。 - 零值(默认)禁用超时。 + 终止在打开的事务中空闲(即等待客户端查询)超过指定时长的任何会话。 + 如果指定值时不带单位,则以毫秒为单位。零值(默认值)禁用此超时。 - 此选项可以用于确保空闲会话不会在不合理的时间内持有锁。 - 即使没有持有重要的锁的时候,打开的事务也会防止清理最近死亡的可能只对这个事务可见的元组;所以长时间保持空闲会导致表膨胀。 - 详见。 + 此选项可确保空闲会话不会持有锁过长时间。 + 即使没有持有重要的锁,打开的事务也会阻止清理最近死亡、且可能只对该事务可见的元组;因此长时间空闲可能造成表膨胀。 + 更多详情参见 @@ -7489,9 +7453,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 终止任何空闲的会话(也就是,等待客户端查询),但不在打开的事务中,且超过指定的时间量。 - 如果指定值时不带单位,其单位采用毫秒。 - 零值时(默认)禁用超时。 + 终止不在打开的事务中、且空闲(即等待客户端查询)超过指定时长的任何会话。 + 如果指定值时不带单位,则以毫秒为单位。零值(默认值)禁用此超时。 @@ -7499,8 +7462,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 注意不要对通过连接池软件或其他中间件建立的连接强制执行此超时,因为这样的层可能不会很好地响应意外的连接关闭。 - 只对交互会话启用此超时可能是帮助的,也许只对特定用户应用它。 + 应谨慎对通过连接池软件或其他中间件建立的连接强制执行此超时,因为这样的层可能不会很好地响应意外的连接关闭。 + 只对交互会话启用此超时可能有所帮助,也许只对特定用户应用它。 @@ -7636,7 +7599,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这里的实际选择都是根据爱好做出的,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码将比 base64 编码更大。 + 这里的实际选择主要取决于偏好,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码会比 base64 编码略大。 @@ -7657,7 +7620,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当在XML和字符串值之间进行转换时,无论设置DOCUMENT或 CONTENT都是隐式的。可参阅Section 8.13。 有效值是DOCUMENT和CONTENT。 缺省值是CONTENT。当在 XML 和字符串值之间进行转换时,设置DOCUMENTCONTENT都是隐式的。详见。有效值是DOCUMENTCONTENT。默认值是CONTENT。 + 设置在 XML 与字符串值之间进行转换时,隐含采用DOCUMENT还是CONTENT。 + 有关说明参见。有效值是DOCUMENTCONTENT。默认值是CONTENT @@ -7692,7 +7656,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; createrole_self_grant (string) - createrole_self_grant配置参数 + createrole_self_grant + 配置参数 @@ -7701,9 +7666,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 该值必须是setinherit或它们的逗号分隔列表。默认值为空字符串,这会禁用此功能。 - 此选项的目的是允许非超级用户的CREATEROLE用户自动继承或自动获得对新创建角色执行SET ROLE的能力。 + 此选项的目的是允许非超级用户的CREATEROLE用户自动继承所创建用户的权限,或自动获得对这些用户执行SET ROLE的能力。 由于CREATEROLE用户始终会隐式获得其所创建角色的ADMIN OPTION,因此该用户总是可以通过执行GRANT语句达到相同效果,但自动授予在可用性上更方便。 - 超级用户会自动继承每个角色的权限,并且始终可以切换到任何角色;此设置可让CREATEROLE用户对其创建的用户获得类似的行为。 + 超级用户会自动继承每个角色的权限,并且始终可以对任何角色执行SET ROLE;此设置可让CREATEROLE用户对其创建的用户获得类似的行为。 @@ -7711,7 +7676,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; event_triggers (boolean) - event_triggers配置参数 + event_triggers + 配置参数 @@ -7726,7 +7692,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; restrict_nonsystem_relation_kind (string) - restrict_nonsystem_relation_kind配置参数 + restrict_nonsystem_relation_kind + 配置参数 @@ -7741,7 +7708,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 区域和格式化 + 区域设置和格式化 @@ -7755,7 +7722,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域行为的设置初始化配置文件。 + 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域设置行为的设置初始化配置文件。 @@ -7770,11 +7737,14 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置间隔值的显示格式。值sql_standard将产生匹配 SQL 标准间隔文本的输出。当参数被设置为ISO时,值postgres(默认)将产生匹配PostgreSQL发行 8.4 之前的输出。当DateStyle参数被设置为非ISO输出时,值postgres_verbose会产生匹配PostgreSQL发行 8.4 之前的输出。值iso_8601会产生匹配在 ISO 8601 的 4.4.3.2 节中定义的带标志符格式的时间间隔的输出。 + 设置时间间隔值的显示格式。值sql_standard会生成符合SQL标准时间间隔字面量的输出。 + 值postgres(默认值)的输出与PostgreSQL 8.4 之前版本中设为ISO时的输出一致。 + 值postgres_verbose的输出与PostgreSQL 8.4 之前版本中DateStyle设为非ISO输出时的输出一致。 + 值iso_8601会生成符合 ISO 8601 第 4.4.3.2 节定义的时间间隔带标志符格式的输出。 - IntervalStyle参数也可以影响对有歧义的间隔输入的解释。详见。 + IntervalStyle参数也会影响对有歧义的时间间隔输入的解释。详见 @@ -7832,23 +7802,23 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 如果值为1(默认值)或更高,浮点值被输出为最短-精度格式;参见。 + 如果值为 1(默认值)或更高,浮点值被输出为最短精确格式;参见。 实际生成的位数只取决于输出的值,而不取决于此参数的值。 - float8 值最多需要 17 位数字,float4值最多需要9位数字。 + float8 值最多需要 17 位数字,float4值最多需要9位数字。 这种格式既快速又精确,在正确读取时精确地保留了原始的二进制浮点值。为了历史兼容性,允许的值最大为3。 如果值为零或负,则输出四舍五入为给定的十进制精度。 - 使用的精度是根据此参数的值减小的类型((FLT_DIGDBL_DIG,视情况而定)的标准位数。 + 所用精度以该类型的标准位数(根据类型使用FLT_DIGDBL_DIG)为基础,再按此参数的值减少。 (例如,指定 -1 将导致float4 值输出四舍五入为 5 位有效数字,而float8值四舍五入为 14 位。) - 此格式较慢,不会保留二进制浮点值的所有位,但可能令人更易于阅读。 + 此格式较慢,不会保留二进制浮点值的所有位,但可能更便于阅读。 此参数的含义,以及其默认值,在 PostgreSQL 12 中发生了变化; - 参见 以便进一步讨论。 + 参见 了解进一步讨论。 @@ -7884,7 +7854,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 在一些系统上,这个区域分类并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 + 在一些系统上,这个区域设置类别并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 @@ -7903,7 +7873,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化货币量的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化货币量的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -7918,7 +7888,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化数字的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化数字的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -7933,7 +7903,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化日期和时间的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化日期和时间的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -7965,7 +7935,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 选择被那些没有显式参数指定配置的文本搜索函数变体使用的文本搜索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配区域的配置,initdb将用对应于选中的lc_ctype区域的设置初始化配置文件。 + 选择被那些没有显式参数指定配置的文本检索函数变体使用的文本检索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配该区域设置的配置,initdb将用对应于选中的lc_ctype区域设置的值初始化配置文件。 @@ -7980,7 +7950,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 为了载入附加的功能或者达到提高性能的目的,可用多个设置来预先载入共享库到服务器中。 - 例如'$libdir/mylib'设置可能会导致mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 + 例如'$libdir/mylib'设置会使mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 @@ -7989,12 +7959,12 @@ SET XML OPTION { DOCUMENT | CONTENT }; 只有特别为与PostgreSQL一起使用设计的共享库才能以这种方式载入。每一个PostgreSQL支持 - 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非PostgreSQL无法 + 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非 PostgreSQL 库无法 以这种方式被载入。你可能可以使用操作系统的工具(如LD_PRELOAD)载入它。 - 总之,请参考特定模块的文档来用推荐的方法载入它。 + 一般来说,请参考特定模块的文档来用推荐的方法载入它。 @@ -8028,9 +7998,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 这个特性的目的是允许非特权用户在特定的会话中载入正在调试的或者性能度量库, - 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客 - 户端的PGOPTIONS环境变量或者 + 这个特性的目的是允许非特权用户在特定的会话中载入用于调试或性能测量的库, + 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客户端的PGOPTIONS环境变量或者 ALTER ROLE SET来设置这个参数。 @@ -8068,7 +8037,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 不同,相对于在库被第一次使用 - 时载入它,在会话开始时载入库并没有什么性能优势。不过,当使用连接池时这样做还是有一些 + 时载入它,在会话开始时载入库并没有明显的性能优势。不过,当使用连接池时这样做还是有一些 优势。 @@ -8108,9 +8077,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 在 Windows 主机上,在服务器启动时预载入一个库并不会减少启动每个新服务器进程所需的 - 时间;每一个服务器进程将会重新载入预载入的库。不过,对于那些要在postmaster启动时 + 时间;每一个服务器进程将会重新载入所有预载入的库。不过,对于那些要在postmaster启动时 执行操作的库来说,Windows 主机上的 - shared_preload_libraries任然有用。 + shared_preload_libraries仍然有用。 @@ -8158,13 +8127,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 如果需要打开一个可以动态装载的模块并且在CREATE FUNCTIONLOAD命令中指定的文件名没有目录部分(即名字中不包含斜线),那么系统将搜索这个路径以查找所需的文件。 - - dynamic_library_path的值必须是一个冒号分隔(或者在 Windows 上以分号分隔)的绝对目录路径的列表。如果一个列表元素以特殊字符串开始,$libdir会被替换为PostgreSQL包中已编译好的库目录。这里是PostgreSQL发布提供的模块被安装的位置(使用pg_config --pkglibdir来找到这个目录的名字)。例如: - + 参数dynamic_library_path的值必须是由冒号(Windows上为分号)分隔的绝对目录路径列表。如果某个列表元素以特殊字符串$libdir开头,则会使用编译时确定的PostgreSQL软件包的库目录来替换$libdir;该目录是标准PostgreSQL发行版所提供模块的安装位置。(使用pg_config --pkglibdir可以找出此目录的名称。)例如: dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir' - - 或者在 Windows 环境中: - +或者,在 Windows 环境中: dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' @@ -8190,7 +8155,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - GIN 索引返回的集合尺寸的软上限。详见。 + GIN 索引扫描返回的集合尺寸的软上限。详见 @@ -8223,18 +8188,18 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这是在锁上等待的时间,然后再检查是否存在死锁条件。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 + 指定在检查是否发生死锁之前等待锁的时间。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 我们乐观地假设在生产应用程序中死锁并不常见,所以在检查死锁之前只是等待一段时间。 增加此值会减少在不必要的死锁检查中浪费的时间,但会减慢实际死锁错误的报告速度。 如果未指定单位,则将其视为毫秒。 - 默认值为一秒(1s),这可能是您在实践中想要的最小值。 - 在负载较重的服务器上,您可能希望提高它。 - 理想情况下,设置应超过您的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 + 默认值为一秒(1s),这可能是你在实践中想要的最小值。 + 在负载较重的服务器上,你可能希望提高它。 + 理想情况下,设置应超过你的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 只有超级用户和具有适当SET权限的用户才能更改此设置。 - 当被设置时,这个参数还可以决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 + 当被设置时,这个参数也决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 @@ -8283,7 +8248,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制在谓词锁被提升为覆盖整个关系之前,该谓词锁能够在单个关系上锁住多少页面或元组。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个关系之前,可以对单个关系中的多少页面或元组加谓词锁。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -8298,7 +8263,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制在谓词锁被提升为覆盖整个页面之前,该谓词锁能在单一页面上锁住多少行。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个页面之前,可以对单个页面中的多少行加谓词锁。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -8326,7 +8291,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个空数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。对于那些要求旧行为的应用的向后兼容性,这个变量可以被设置为off。 + 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个值为空值的数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。为了向后兼容那些要求旧行为的应用,这个变量可以被设置为off @@ -8346,11 +8311,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 这个参数控制字符串文本中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\'。如果客户端代码没有做到正确转义,那么将会导致 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 + 这个参数控制字符串字面量中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\。如果客户端代码没有做到正确转义,那么就可能遭到 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 - 注意在符合标准的字符串文本中,\就表示\。这个参数只影响不符合标准的文本的处理,包括转义字符串语法(E'...')。 + 注意在符合标准的字符串字面量中,\就表示\。这个参数只影响不符合标准的字面量的处理,包括转义字符串语法(E'...')。 @@ -8366,11 +8331,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 打开时,如果在普通字符串文本中('...'语法)出现了 一个反斜线(\)并且standard_conforming_strings为关闭,那么就会发出一个警告。默认值是on。 + 打开时,如果在普通字符串字面量中('...'语法)出现了 一个反斜线(\)并且standard_conforming_strings为关闭,那么就会发出一个警告。默认值是on - 希望使用反斜线作为转义符的应用应该被修改来使用转义字符串语法(E'...'),因为在 SQL 标准中普通字符串的默认行为是将反斜线视作一个普通字符。这个变量可以被启用来帮助定位需要被更改的代码。 + 希望使用反斜线作为转义符的应用应该被修改来使用转义字符串语法(E'...'),因为按照 SQL 标准,普通字符串现在默认将反斜线视作一个普通字符。这个变量可以被启用来帮助定位需要被更改的代码。 @@ -8391,7 +8356,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 设置这个参数不会禁用所有与大对象相关的安全检查 — 除了那些在PostgreSQL 9.0中已经修改了的默认行为。 + 设置此变量不会禁用所有与大对象相关的安全检查 — 只禁用那些在PostgreSQL 9.0 中默认行为发生变化的检查。 @@ -8414,7 +8379,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' standard_conforming_strings (boolean) - 字符串标准符合 + 字符串符合标准 standard_conforming_strings配置参数 @@ -8422,7 +8387,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 控制普通字符串文本('...')是否按照 SQL 标准把反斜线当普通文本。从PostgreSQL 9.1 开始,默认值为on(之前的发行中默认值为off)。应用可以检查这个参数来判断字符串文本如何被处理。这个参数的存在也可以被当做转义字符串语法(E'...')被支持的标志。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 + 控制普通字符串字面量('...')是否按照 SQL 标准把反斜线当普通文本。从PostgreSQL 9.1 开始,默认值为on(之前的发行中默认值为off)。应用可以检查这个参数来判断字符串字面量如何被处理。这个参数的存在也可以被当做转义字符串语法(E'...')被支持的标志。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 @@ -8437,7 +8402,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询来,这样的扫描会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on。 + 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询,这样的扫描可能会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on @@ -8461,15 +8426,15 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr得出空值值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空(未知)。因此这个参数默认为off。 + 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr计算结果为空值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空值(未知)。因此这个参数默认为off - 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释)。它们不是非常有用并且在普通应用中也不常见,在应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及 空值的表达式的语义上感到困惑,因此这个选项默认为关闭。 + 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释),它们不是非常有用并且在普通应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及空值的表达式语义感到困惑,因此这个选项默认为关闭。 - 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不是劣质程序的一般修复。 + 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不能普遍修复错误的程序写法。 @@ -8545,7 +8510,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 当被设置为开(on),PostgreSQL将在一次后端崩溃后自动重新初始化。 + 当设置为 on(默认值)时,PostgreSQL将在一次后端崩溃后自动重新初始化。 让这个值设置为开(on)通常是将数据库可用性最大化的最佳方法。但是在某些环境中,例如PostgreSQL被集群软件调用时,禁用重启可能很有用,这样集群软件可以得到控制并且采取它认为适当的行动。 @@ -8565,7 +8530,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果设置为关(off),PostgreSQL在将修改的数据文件刷新到文件系统失败时,将引发PANIC级错误。 + 当设置为 off(默认值)时,PostgreSQL在将修改后的数据文件刷盘到文件系统失败时,将引发PANIC级错误。 这样会导致数据库服务器崩溃。这个参数只能在服务器启动时被设置。 @@ -8574,8 +8539,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果设置为开(on),PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷新操作。 - 仅在调查操作系统假如回写失败时对缓冲数据的处理方式的情况下,才将其设置为开(on)。 + 如果设置为开(on),PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷盘操作。 + 只有在调查清楚操作系统在回写失败时如何处理缓冲数据之后,才应将其设置为开(on)。 @@ -8592,14 +8557,14 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 当设置为fsync,也就是默认值,PostgreSQL将在崩溃恢复开始之前递归地打开并同步数据目录中的所有文件。 对文件的搜索将遵循WAL目录和每个配置表空间的符号链接(而不是任何其它符号链接)。 - 这是为了确保在重现更改之前,所有WAL和数据文件都持久地存储在硬盘上。 - 这适用于在启动没有完全关闭的数据库集簇时,包括由pg_basebackup创建的副本。 + 这是为了确保在重放更改之前,所有WAL和数据文件都持久地存储在磁盘上。 + 这适用于每次启动未正常关闭的数据库集簇时,包括由pg_basebackup创建的副本。 - 在Linux上,可以用syncfs代替,请求操作系统来同步包含数据目录的整个文件系统,WAL文件和每个表空间(但不是通过符号链接可访问到的任何其他文件系统)。 + 在Linux上,可以用syncfs代替,请求操作系统来同步数据目录、WAL 文件和各个表空间所在的文件系统(但不是通过符号链接可访问到的任何其他文件系统)。 这可能比fsync设置快得多,因为它不需要逐个打开每个文件。 - 另一方面,如果一个文件系统是被其他需要修改大量文件的应用程序共享的,它可能会慢一些,因为这些文件也将写入硬盘。 + 另一方面,如果一个文件系统是被其他需要修改大量文件的应用程序共享的,它可能会慢一些,因为这些文件也将写入磁盘。 此外,在5.8之前的Linux版本中,向磁盘写入数据时遇到的I/O错误可能不会报告给PostgreSQL,相关的错误消息可能只出现在内核日志中。 @@ -8618,11 +8583,10 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 预置选项 - 下列参数是只读的。 - 同样,它们被排除在postgresql.conf文件示例之外。 - 这些选项报告特定应用可能感兴趣的多种PostgreSQL行为,特别是管理前端相关的行为。 - 所有这些都是在PostgreSQL被编译或者它被安装时决定的。 - + 下列参数是只读的,因此未列入示例 postgresql.conf 文件。 + 这些选项报告 PostgreSQL 行为的各个方面,某些应用(特别是管理前端)可能对此感兴趣。 + 其中大多数参数在编译或安装 PostgreSQL 时确定。 + @@ -8651,7 +8615,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告对这个集簇是否启用了数据校验码。详见。 + 报告对这个集簇是否启用了数据校验和。详见 @@ -8666,7 +8630,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 在Unix系统上,这个参数报告启动时的数据目录(由定义)的权限。 + 在 Unix 系统上,这个参数报告服务器启动时数据目录(由定义)的权限。 (在Microsoft Windows上这个参数将总是显示0700。) 更多信息请参考 @@ -8718,7 +8682,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告PostgreSQL是否在编译时打开了 64 位整数日期和时间。从PostgreSQL 10起,这个值总是on。 + 报告PostgreSQL是否在编译时启用了对 64 位整数日期和时间的支持。从PostgreSQL 10起,这个值总是on @@ -8734,9 +8698,9 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 报告服务器当前是否处于热备模式。 - 当这个是on的时候,所有的事务强制为只读。 - 在会话中,这个只能在服务器提升为主库的时候变更。 - 更多信息参见 + 当此值为 on 时,所有事务都被强制为只读。 + 在会话中,此值只有在服务器被提升为主库时才会改变。 + 更多信息参见 @@ -8750,7 +8714,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定的。默认值是 100 个参数。 + 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定。默认值是 100 个参数。 @@ -8765,7 +8729,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64 ;因此max_identifier_length的默认值是 63,但是在使用多字节编码时可以少于 63 个字符。 + 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64;因此max_identifier_length的默认值是 63 字节,在使用多字节编码时,这可能不足 63 个字符。 @@ -8825,7 +8789,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告服务器版本数值。它是由编译服务器时的PG_VERSION值决定的。 + 报告服务器的版本号。它是由编译服务器时的PG_VERSION值决定的。 @@ -8840,7 +8804,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告服务器版本数值的整数值。它是由编译服务器时的PG_VERSION_NUM值决定的。 + 以整数形式报告服务器的版本号。它是由编译服务器时的PG_VERSION_NUM值决定的。 @@ -8855,7 +8819,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告主共享内存区域的大小,四舍五入到最接近的兆字节。 + 报告主共享内存区域的大小,向上取整到整数兆字节。 @@ -8892,8 +8856,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 报告此PostgreSQL服务器已构建的 SSL 库的名称(即使此实例当前未配置或使用 SSL), - 例如OpenSSL,或一个空字符串(如果没有)。 + 报告此PostgreSQL服务器在构建时使用的 SSL 库的名称(即使此实例当前未配置或使用 SSL), + 例如OpenSSL,如果没有使用 SSL 库,则报告空字符串。 @@ -8936,11 +8900,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 自定义选项 - 这个特性被设计用来由附加模块向PostgreSQL添加通常不为系统知道的参数(例如过程语言)。这允许使用标准方法配置扩展模块。 + 这个特性允许附加模块(例如过程语言)向PostgreSQL添加系统通常不认识的参数。这样便能以标准方式配置扩展模块。 - 自定义选项有两部分名称:一个扩展名,然后是一个句点,再然后是正确的参数名,就像 SQL 中的合格名称。一个示例是plpgsql.variable_conflict。 + 自定义选项的名称由两部分组成:扩展名称和参数名本身,中间用句点分隔,类似于 SQL 中的限定名。例如plpgsql.variable_conflict @@ -8948,7 +8912,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' PostgreSQL将接受任何两部分参数名称的设置。 这些变量被视为占位符,在定义它们的模块加载之前没有任何功能。 当加载扩展模块时,它将添加其变量定义并根据这些定义转换任何占位符值。 - 如果存在以其扩展名开头的任何未识别的占位符,将发出警告并删除这些占位符。 + 如果存在以其扩展名称开头的任何未识别的占位符,将发出警告并删除这些占位符。 @@ -8957,11 +8921,10 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' 开发者选项 - 下面的参数目的是用在开发测试上, 并且永远不能用于生产数据库。 - 但是,它们中的一些能够用于帮助恢复严重损坏的数据库。 - 同样,它们被从示例postgresql.conf文件中排除。 - 请注意许多这些参数要求特殊的源代码编译标志才能工作。 - + 以下参数用于开发者测试,切勿用于生产数据库。不过,其中一些参数可用于辅助恢复严重损坏的数据库。 + 因此,它们未列入示例postgresql.conf文件。 + 请注意,许多参数需要特殊的源代码编译标志才能起作用。 + @@ -8974,7 +8937,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 允许将表空间创建为pg_tblspc内的目录,当CREATE TABLESPACE命令提供空位置字符串时。 + 当向CREATE TABLESPACE命令提供空的位置字符串时,允许将表空间创建为pg_tblspc内的目录。 这旨在允许测试主库和备库在同一台机器上运行的复制场景。这样的目录可能会混淆备份工具,因为这些工具期望在该位置只找到符号链接。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -8991,8 +8954,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 允许修改系统表的结构以及对系统表进行某些其他风险操作。即使对于超级用户,这也通常是不允许的。 - 不明智地使用此设置可能导致无法检索的数据丢失或严重损坏数据库系统。 + 允许修改系统表的结构以及对系统表进行某些其他风险操作。否则,即使超级用户也不允许执行这些操作。 + 不明智地使用此设置可能导致无法挽回的数据丢失或严重损坏数据库系统。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -9032,14 +8995,14 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 当设置为1时,每个系统目录缓存条目在第一个可能的机会时失效,不管任何使之无效的事情是否真的发生。 - 作为结果,系统目录的缓存被有效地禁用,因此服务器将运行得非常缓慢。 - 较高的值递归地运行缓存失效,这样会更慢,而且只用于测试缓存逻辑自身。 + 当设置为1时,每个系统目录缓存条目都会在最早可能的时刻被置为无效,无论是否真的发生了使其失效的事件。 + 这实际上禁用了系统目录缓存,因此服务器将运行得非常缓慢。 + 较高的值递归地运行缓存失效,这样会更慢,而且仅对测试缓存逻辑本身有用。 默认值0选择正常的目录缓存行为。 - 当试图触发涉及并发目录更改的难以复现的错误时,此参数非常有用,但除此之外它不太被需要。 + 当试图触发涉及并发目录更改的难以复现的错误时,此参数非常有用,但除此之外很少需要使用它。 详情请参见源码文件inval.cpg_config_manual.h @@ -9123,7 +9086,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据的时有用。这个参数在会话开始之后不能被更改。 + 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据时有用。这个参数在会话开始之后不能被更改。 @@ -9138,8 +9101,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 执行认证过程后启动新服务器进程时延迟的时间量。这是为了给开发者们一个机会在一个服务器进程上附加一个调试器。 - 如果指定值时没有单位,则以秒为单位。0值(默认值)禁用延迟。这个参数在会话开始之后不能被更改。 + 新服务器进程启动并完成认证过程之后的延迟时间。这旨在给开发者一个机会,用调试器附加到服务器进程上。 + 如果指定值时没有单位,则以秒为单位。零值(默认值)禁用延迟。这个参数在会话开始之后不能被更改。 @@ -9154,8 +9117,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 在新服务器进程分叉后,在进行认证过程之前,延迟的时间量。这是为了给开发者们一个机会在一个服务器进程上附加一个调试器来跟踪认证过程中的不当行为。 - 如果指定值时没有单位,则以秒为单位。0值(默认值)禁用延迟。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 新服务器进程刚刚派生之后、执行认证过程之前的延迟时间。这旨在给开发者一个机会,用调试器附加到服务器进程上,跟踪认证过程中的异常行为。 + 如果指定值时没有单位,则以秒为单位。零值(默认值)禁用延迟。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -9170,7 +9133,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 + 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 @@ -9184,7 +9147,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果打开,发出在排序操作中的资源使用的相关信息。只有在编译PostgreSQL时定义了TRACE_SORT宏, 这个参数才可用(不过,当前在默认情况下就定义了TRACE_SORT)。 + 如果开启,输出排序操作中的资源使用信息。只有在编译PostgreSQL时定义了TRACE_SORT宏, 这个参数才可用(不过,当前在默认情况下就定义了TRACE_SORT)。 @@ -9199,7 +9162,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。对每一种锁类型,已授权锁和等待锁的计数也会被一起转储。一个日志文件输出的示例如下: + 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。还会转储每种锁类型已授予的锁数、等待的锁数,以及它们的总数。一个日志文件输出的示例如下: LOG: LockAcquire: new: lock(0xb7acd844) id(24688,24696,0,0,0,1) grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0 @@ -9271,7 +9234,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果设置,不会跟踪小于这个 OID 的锁(用于避免在系统表上的输出)。 + 如果设置,不会跟踪 OID 小于此值的表上的锁(用于避免在系统表上的输出)。 @@ -9347,7 +9310,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,被修改的任何缓冲区的整页镜像及其WAL记录都被加入到记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 + 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,与该 WAL 记录相关的所有已修改缓冲区的整页镜像都会被添加到该记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 @@ -9391,10 +9354,10 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 在读取过程中检测到校验和失败通常会导致PostgreSQL报告错误,中止当前事务。 - 将ignore_checksum_failure设置为on会导致系统忽略失败(但仍然报告警告),并继续处理。 - 这种行为可能导致崩溃,传播或隐藏损坏,或其他严重问题。然而,它可能允许您跳过错误, - 并检索可能仍然存在于表中的未损坏的元组,如果块头仍然正常。如果头部损坏,即使启用此选项也会报告错误。 - 默认设置为off。 + 将ignore_checksum_failure设置为 on 会使系统忽略失败(但仍报告警告),并继续处理。 + 这种行为可能导致崩溃、传播或隐藏损坏,或引发其他严重问题。 + 但是,如果块首部仍然正常,它可能允许你跳过错误,检索表中可能仍然存在的未损坏元组。 + 如果首部损坏,即使启用此选项也会报告错误。默认设置为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -9412,7 +9375,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 检测到损坏的页面头通常会导致PostgreSQL报告错误,中止当前事务。 将zero_damaged_pages设置为on会导致系统报告警告,将内存中的损坏页面清零,并继续处理。 - 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许您跳过错误,并从表中可能存在的未损坏页面中检索行。 + 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许你跳过错误,并从表中可能存在的未损坏页面中检索行。 如果由于硬件或软件错误而发生损坏,这对于恢复数据很有用。通常在放弃从表的损坏页面恢复数据的希望之前,不应将其设置为on。 清零的页面不会强制写入磁盘,因此建议在再次关闭此参数之前重新创建表或索引。默认设置为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -9432,9 +9395,9 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 如果设置为 off(默认值),则在恢复期间检测到引用无效页面的 WAL 记录会导致 PostgreSQL 引发 PANIC 级别错误,中止恢复。 将ignore_invalid_pages设置为on会导致系统忽略 WAL 记录中的无效页面引用(但仍报告警告),并继续恢复。 - 此行为可能会导致崩溃、数据丢失、传播或隐藏腐败,或其他严重问题。 - 但是,它可能允许你通过 PANIC 级错误,完成恢复,并启动服务器。 - 参数只能在服务器启动时设置。它仅在恢复期间或待机模式下生效。 + 此行为可能会导致崩溃、数据丢失、传播或隐藏损坏,或其他严重问题。 + 但是,它可能允许你跳过 PANIC 级错误,完成恢复,并启动服务器。 + 参数只能在服务器启动时设置。它仅在恢复期间或备库模式下生效。 @@ -9449,7 +9412,8 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果LLVM有所需要的功能,用GDB注册所生成的函数。这会让调试更加容易。默认设置是off。只有超级用户和具有适当SET权限的用户可以在会话开始时更改这个参数,并且在会话内完全不能更改它。 + 如果 LLVM 具有所需的功能,则向GDB注册生成的函数。 + 这会让调试更加容易。默认设置为off。只有超级用户和具有适当SET权限的用户才能在会话开始时更改此参数,并且在会话内完全不能更改它。 @@ -9465,7 +9429,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 将生成的LLVM IR写入文件系统,位于内。 - 这仅对于在JIT实现内部工作时有用。默认设置为off。 + 这仅对开发 JIT 的内部实现有用。默认设置为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -9496,10 +9460,9 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果LLVM有所需的功能,发出需要的数据以允许perf对JIT生成的函数画像。 - 这会写出文件到~/.debug/jit/中,如果需要,由用户负责对其执行清除。 - 默认设置是off。 - 只有超级用户和具有适当SET权限的用户可以在会话开始时更改这个参数,并且在会话内完全不能更改它。 + 如果 LLVM 具有所需的功能,则输出让perf对 JIT 生成的函数进行性能分析所需的数据。 + 这会将文件写入~/.debug/jit/;用户应在需要时自行清理。 + 默认设置为off。只有超级用户和具有适当SET权限的用户才能在会话开始时更改此参数,并且在会话内完全不能更改它。 @@ -9529,8 +9492,8 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 当设置为on时,这是默认值,PostgreSQL将在后端崩溃后自动删除临时文件。 - 如果禁用,文件将被保留,并且也许可用于调试,例如。 + 当设置为on(默认值)时,PostgreSQL将在后端崩溃后自动删除临时文件。 + 如果禁用,文件将被保留,例如可用于调试。 重复的崩溃可能会导致无用文件的积累。 该参数只能在postgresql.conf文件中或服务器命令行中设置。 @@ -9582,11 +9545,11 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 允许值为bufferedimmediate。默认值为buffered。 这个参数旨在用于测试逻辑解码以及大型事务的复制。 - debug_logical_replication_streaming对发布端和订阅端的影响不同。 + debug_logical_replication_streaming对发布者和订阅者的影响不同。 - 在发布端,debug_logical_replication_streaming允许在逻辑解码中立即流式传输或序列化更改。 + 在发布者端,debug_logical_replication_streaming允许在逻辑解码中立即流式传输或序列化更改。 当设置为immediate时,如果 streaming选项在 CREATE SUBSCRIPTION中已启用, @@ -9595,10 +9558,10 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 在订阅端,如果streaming选项被设置为parallel, - 则debug_logical_replication_streaming可用于控制主应用工作进程是将更改发送到共享内存队列, - 还是将所有更改序列化到文件。设置为buffered时,主进程通过共享内存队列将更改发送给并行应用工作进程。 - 设置为immediate时,主进程会将所有更改序列化到文件,并通知并行应用工作进程在事务结束时读取并应用这些更改。 + 在订阅者端,如果streaming选项被设置为parallel, + 则debug_logical_replication_streaming可用于控制领导者应用工作进程是将更改发送到共享内存队列, + 还是将所有更改序列化到文件。设置为buffered时,领导者通过共享内存队列将更改发送给并行应用工作进程。 + 设置为immediate时,领导者会将所有更改序列化到文件,并通知并行应用工作进程在事务结束时读取并应用这些更改。 @@ -9610,12 +9573,12 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 短选项 - 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,并且它们作为一个单字母选项存在并不表示它们会被大量使用。 + 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,它们以单字母选项的形式存在,并不一定表示鼓励频繁使用这些选项。
- 短选项键 + 短选项对照 diff --git a/zh/17/datatype.sgml b/zh/17/datatype.sgml index e8c68135..f0527f92 100644 --- a/zh/17/datatype.sgml +++ b/zh/17/datatype.sgml @@ -151,7 +151,7 @@ line - 平面上的无限长的线 + 平面上的无限直线 @@ -163,19 +163,19 @@ macaddr - MAC(Media Access Control)地址 + MAC(媒体访问控制)地址 macaddr8 - MAC(Media Access Control)地址(EUI-64格式) + MAC(媒体访问控制)地址(EUI-64格式) money - 货币数量 + 货币额 @@ -183,7 +183,7 @@ s) ] decimal [ (p, s) ] - 可选择精度的精确数字 + 可选择精度的精确数值 @@ -195,7 +195,7 @@ pg_lsn - PostgreSQL日志序列号类型 + PostgreSQL 日志序列号 @@ -273,13 +273,13 @@ tsquery - 文本搜索查询 + 文本检索查询 tsvector - 文本搜索文档 + 文本检索文档 @@ -420,14 +420,14 @@
- 数字类型常量的语法在里描述。数字类型有一整套对应的数学操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 + 数字类型常量的语法在里描述。数字类型有一整套对应的算术操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 整数类型 - 整数 + integer @@ -440,7 +440,7 @@ int4 - 整数 + integer @@ -460,11 +460,11 @@
- 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。而只有在integer的范围不够的时候才使用bigint。 + 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。bigint则设计用于integer的范围不够的情况。 - SQL只声明了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在许多其它SQL数据库系统中使用。 + SQL只规定了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在某些其他SQL数据库系统中使用。 @@ -473,11 +473,11 @@ 任意精度数值 - 数字(数据类型) + numeric(数据类型) - 任意精度数字 + 任意精度数值 @@ -578,18 +578,18 @@ NUMERIC(3, 5)
- infinity - numeric (数据类型) + 无穷大 + numeric(数据类型) NaN - 非数字 + 非数 - 非数字 - 数字(数据类型) + 非数 + numeric(数据类型) @@ -676,7 +676,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 双精度 + double precision @@ -686,7 +686,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; float8 - 双精度 + double precision @@ -739,8 +739,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; 默认情况下,浮点值会以最短且精确的十进制表示形式输出; - 生成的十进制值比同一二进制精度下任何其他可表示值都更接近真实 - 存储的二进制值。(不过,为了避免输入例程普遍存在的一个错误, + 所生成的十进制值与实际存储的二进制值之间的距离,小于它与任何其他可用相同二进制精度表示的值之间的距离。(不过,为了避免输入例程普遍存在的一个错误, 即未能正确遵守舍入到最近偶数规则,当前输出值绝不会 恰好位于两个可表示值的正中间。) 对于float8值,最多使用 17 位有效十进制数字; @@ -749,14 +748,14 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 生成这种最短且精确的输出格式,比历史上的圆整格式要快得多。 + 生成这种最短且精确的输出格式,比历史上的舍入格式要快得多。 为了兼容旧版本PostgreSQL生成的输出, 并允许降低输出精度,可以使用 - 参数改为选择圆整后的 + 参数改为选择舍入后的 十进制输出。将该参数设置为 0 会恢复之前的默认行为,也就是把值 舍入为 6 位(对于float4)或 15 位 (对于float8)有效十进制数字。设置为负值会 @@ -770,7 +769,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 过去那些需要精确值的应用,往往必须把 + 过去那些需要精确值的应用,必须把 设置为 3 才能获得它们。 为了在版本之间获得最大兼容性,这类应用应继续这样做。 @@ -778,12 +777,12 @@ FROM generate_series(-3.5, 3.5, 1) as x; 无穷大 - 浮点型 + 浮点 - 非数字 - 浮点型 + 非数 + 浮点 @@ -855,13 +854,13 @@ FROM generate_series(-3.5, 3.5, 1) as x; - auto-increment + 自动递增 serial - sequence - and serial type + 序列 + 与 serial 类型 @@ -914,7 +913,7 @@ ALTER SEQUENCE tablename_ - 要向 serial 列插入序列中的下一个值,应指定让该列 + 要向 serial 列插入序列中的下一个值,应指定让serial列 使用其默认值。这既可以通过在 INSERT 语句的 列表中省略该列来实现,也可以通过使用 DEFAULT 关键字来实现。 @@ -990,7 +989,7 @@ ALTER SEQUENCE tablename_ SELECT '12.34'::float8::numeric::money; - 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有圆整错误。 + 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有舍入误差。 @@ -1002,7 +1001,7 @@ SELECT '52093.89'::money::numeric::float8; 一个 money 值除以一个整数值时,会朝零方向截去小数 - 部分。要得到圆整结果,可以除以一个浮点值,或者在除法前先把 + 部分。要得到舍入后的结果,可以除以一个浮点值,或者在除法前先把 money 转换为 numeric,再在除法后转换回 money(如果要避免精度丢失风险,后一种做法更好)。 当一个 money 值被另一个 money 值除时, @@ -1021,12 +1020,12 @@ SELECT '52093.89'::money::numeric::float8; - string + 字符串 - 字符 + character @@ -1065,11 +1064,11 @@ SELECT '52093.89'::money::numeric::float8; character(n), char(n), bpchar(n) - 定长,空白填充 + 定长,空格填充 bpchar - 无限长度的变长,忽略尾随空白 + 无限长度的变长,忽略尾随空格 text @@ -1128,7 +1127,7 @@ SELECT '52093.89'::money::numeric::float8; 超过 10,485,760。若 character varying (或 varchar)没有长度说明,则该类型接受任意长度 的字符串。若 bpchar 没有长度说明,它也接受任意 - 长度的字符串,但尾随空白在语义上不重要。若 + 长度的字符串,但尾随空格在语义上不重要。若 character(或 char)缺少长度说明, 则等同于 character(1) @@ -1150,7 +1149,7 @@ SELECT '52093.89'::money::numeric::float8;
- 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储代码为零的字符(有时称为NUL)。有关更多信息,请参阅。 + 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储编码值为零的字符(有时称为NUL)。有关更多信息,请参阅 @@ -1169,7 +1168,7 @@ SELECT '52093.89'::money::numeric::float8; - 这三种类型之间没有性能差别,除了使用空白填充类型时会占用更多存储 + 这三种类型之间没有性能差别,除了使用空格填充类型时会占用更多存储 空间,以及在写入带长度约束的列时需要少量额外 CPU 周期来检查长度。 虽然在某些其他数据库系统中,character(n) 可能有一定性能优势,但在 PostgreSQL @@ -1204,7 +1203,7 @@ INSERT INTO test2 VALUES ('ok'); INSERT INTO test2 VALUES ('good '); INSERT INTO test2 VALUES ('too long'); ERROR: value too long for type character varying(5) -INSERT INTO test2 VALUES ('too long'::varchar(5)); -- explicit truncation +INSERT INTO test2 VALUES ('too long'::varchar(5)); -- 显式截断 SELECT b, char_length(b) FROM test2; b | char_length @@ -1328,7 +1327,7 @@ SELECT b, char_length(b) FROM test2; 开头(以便与转义格式区分)。在某些上下文中,这个开头的反斜线 可能需要通过双写进行转义(见 )。作为输入时,十六进制数字 - 可以使用大写或小写,并且在两个数字组成的一组之间允许出现空白 + 可以使用大写或小写,并且每两个数字组成一组,组与组之间允许出现空白 (但组内以及起始的 \x 序列中不能有空白)。 十六进制格式与大量外部应用和协议兼容,并且通常比转义格式转换得 更快,因此更推荐使用。 @@ -1392,7 +1391,7 @@ SELECT '\xDEADBEEF'::bytea; 0 - 0字节 + 零值字节 '\000' '\000'::bytea \x00 @@ -1537,10 +1536,10 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; time - 不带时区的时间 + time without time zone - 带时区的时间 + time with time zone timestamp @@ -1549,13 +1548,13 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; timestamptz - 带时区的时间戳 + timestamp with time zone - 不带时区的时间戳 + timestamp without time zone - 间隔 + interval 时间跨度 @@ -1639,7 +1638,7 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; - SQL 要求仅写 timestamp 时,应等效于 + SQL 标准要求仅写 timestamp 时,应等效于 timestamp without time zone,而 PostgreSQL 也遵循这种行为。 timestamptz 被接受为 @@ -1720,7 +1719,7 @@ MINUTE TO SECOND 其中 p 是可选的精度说明,给出秒字段中 保留的小数位数。精度可用于 timetimestampinterval 类型, - 范围是 0 到 6。这与前文描述的取值一致。如果在常量声明中没有指定 + 范围是 0 到 6。如果在常量声明中没有指定 精度,则默认采用该字面值本身的精度(但不超过 6 位)。 @@ -1749,7 +1748,7 @@ MINUTE TO SECOND 1999-01-08 - ISO 8601; 任何模式下的1月8日 + ISO 8601; 任何模式下的1月8日 (推荐格式) @@ -1785,27 +1784,27 @@ MINUTE TO SECOND 99-Jan-08 - YMD模式中的1月8日,否则错误 + YMD模式中的1月8日,否则报错 08-Jan-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 Jan-08-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 19990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 1999.008 - 年和一年中的日子 + 年和一年中的第几天 J2451187 @@ -1827,10 +1826,10 @@ MINUTE TO SECOND time - 无时区的时间 + time without time zone - 带时区的时间 + time with time zone @@ -1909,11 +1908,11 @@ MINUTE TO SECOND 040506+0730 - ISO 8601,以分数小时形式给出 UTC 偏移 + ISO 8601,时区的 UTC 偏移不是整小时 040506+07:30:00 - UTC偏移量指定为秒(ISO 8601中不允许) + UTC 偏移精确到秒(ISO 8601中不允许) 04:05:06 PST @@ -1990,11 +1989,11 @@ MINUTE TO SECOND - 带时区的时间戳 + timestamp with time zone - 无时区的时间戳 + timestamp without time zone @@ -2019,29 +2018,12 @@ January 8 04:05:06 1999 PST 也被支持。 - - SQL 标准通过时间后面是否带有 - +- 符号以及时区偏移,来区分 - timestamp without time zone 和 - timestamp with time zone 常量。因此,根据标准, - - + 按照SQL标准,timestamp without time zonetimestamp with time zone字面量的区别在于,时间后是否有+-符号及其后的时区偏移。因此,按照该标准, TIMESTAMP '2004-10-19 10:23:54' - - - 属于 timestamp without time zone,而 - - +timestamp without time zone,而 TIMESTAMP '2004-10-19 10:23:54+02' - - - 属于 timestamp with time zone。 - PostgreSQL 在确定字符串类型之前从不检查 - 其内容,因此会把上述两个值都视为 - timestamp without time zone。要确保一个常量被视为 - timestamp with time zone,应为其指定正确的显式类型: - - +timestamp with time zone。 + PostgreSQL在确定字符串字面量的类型之前,从不检查其内容,因此会把上述两者都视为timestamp without time zone。为确保字面量被视为timestamp with time zone,应为它显式指定正确类型: TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' @@ -2086,12 +2068,12 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' time - constants + 常量 date - constants + 常量 @@ -2192,13 +2174,13 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' date 输出格式 - formatting + 格式化 time 输出格式 - formatting + 格式化 @@ -2231,7 +2213,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' ISO - ISO 8601, SQL标准 + ISO 8601,SQL 标准 1997-12-17 07:37:16-08 @@ -2262,7 +2244,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' - SQL和POSTGRES风格中,如果DMY域顺序被指定,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。 + SQL和POSTGRES风格中,如果指定了 DMY 字段顺序,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。 @@ -2329,7 +2311,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 时区 - time zone + 时区 @@ -2414,8 +2396,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 除了时区名称和缩写之外, PostgreSQL 还接受 POSIX 风格的 时区说明,见 。 - 这个选项通常不如使用具名时区更合适,但如果没有可用的 IANA - 时区条目,它可能就是必需的。 + 这个选项通常不如使用具名时区更合适,但如果没有合适的 IANA 时区条目可用,它可能就是必需的。 @@ -2449,7 +2430,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 时区名称和缩写并不是硬编码在服务器中的;它们来自安装目录下 .../share/timezone/ 和 - .../share/timezonesets/ 子目录中的数据 + .../share/timezonesets/ 子目录中的配置文件 (见 )。 @@ -2487,13 +2468,13 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' - interval值可以使用下列语法书写: + interval值可以使用下列详细语法书写: @ quantity unit quantity unit... direction - 其中quantity是一个数字(很可能是有符号的); + 其中quantity是一个数字(可以带有符号); unitmicrosecondmillisecondsecondminutehourday、 @@ -2527,7 +2508,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' P quantity unit quantity unit ... T quantity unit ... 字符串必须以 P 开头,并且可以包含一个 - T 来引出一天中时间单位。可用的单位缩写见 + T 来引出一天中的时间单位。可用的单位缩写见 。单位可以省略, 也可以按任意顺序出现,但小于一天的单位必须出现在 T 之后。特别是,M 的含义 @@ -2566,7 +2547,7 @@ P quantity unit M - 分钟 (在时间部分中) + 分钟(在时间部分中) S @@ -2671,7 +2652,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; P1Y2M3DT4H5M6S - 带标志符的ISO 8601 格式:含义同上 + ISO 8601 带标志符的格式:含义同上 P0001-02-03T04:05:06 @@ -2689,7 +2670,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; interval 输出格式 - formatting + 格式化 @@ -2738,7 +2719,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; iso_8601 风格的输出符合 ISO 8601 标准 - 4.4.3.2 节描述的带标志符格式。 + 4.4.3.2 节描述的带标志符的格式
@@ -2789,7 +2770,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; 布尔类型 - Boolean + 布尔 数据类型 @@ -2900,15 +2881,15 @@ SELECT * FROM test1 WHERE a; 数据类型 - enumerated (enum) + 枚举(enum) - enumerated types + 枚举类型 - 枚举(enum)类型是由一个静态、值的有序集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的日期,或者一个数据的状态值集合。 + 枚举(enum)类型是由一个静态的有序值集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的各天,或者一个数据的状态值集合。 @@ -3017,7 +2998,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 实现细节 - 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空格也是有意义的。 + 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空白也是有意义的。 @@ -3029,7 +3010,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 从内部枚举值到文本标签的翻译被保存在系统目录pg_enum中。可以直接查询该目录。 + 从内部枚举值到文本标签的转换关系被保存在系统目录pg_enum中。直接查询该目录可能会有所帮助。 @@ -3104,7 +3085,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays circle24字节 - <(x,y),r>(中心点和半径) + <(x,y),r>(圆心和半径) @@ -3117,7 +3098,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 我们提供了丰富的函数和操作符来进行各种几何操作,例如缩放、平移、 - 旋转以及计算相交等,详见 。 + 旋转以及求交等,详见 @@ -3128,7 +3109,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 点是几何类型的基本二维构造块。用下面的语法描述point类型的值: + 点是几何类型的基本二维构造块。用下面任一种语法描述point类型的值: ( x , y ) @@ -3144,14 +3125,14 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线 + 直线 line - 线由线性方程Ax + By + C = 0 + 直线由线性方程Ax + By + C = 0 表示,其中AB不能同时为零。类型line 的值采用以下形式输入和输出: @@ -3171,7 +3152,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays (x1,y1)(x2,y2) - 是线上不同的两点。 + 是直线上不同的两点。 @@ -3187,7 +3168,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线段用一对线段的端点来表示。lseg类型的值用下面的语法声明: + 线段用一对线段的端点来表示。lseg类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ( x2 , y2 ) ] @@ -3211,15 +3192,15 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 方框 - box (data type) + box(数据类型) - rectangle + 矩形 - 方框用其对角的点对表示。box类型的值使用下面的语法指定: + 方框用其对角的点对表示。box类型的值使用下面任一种语法指定: ( ( x1 , y1 ) , ( x2 , y2 ) ) @@ -3238,7 +3219,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 在输入时可以提供任意两个对角,但是值将根据需要被按顺序记录为右上角和左下角。 + 在输入时可以提供任意两个对角,但是值将根据需要被重新排列,并依次存储为右上角和左下角。 @@ -3246,7 +3227,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 路径 - path (data type) + path(数据类型) @@ -3254,7 +3235,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - path类型的值用下面的语法声明: + path类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ... , ( xn , yn ) ] @@ -3264,11 +3245,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays x1 , y1 , ... , xn , yn - 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被忽略时,路径将被假定为封闭。 + 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被省略时,路径将被假定为封闭。 - 路径的输出使用第一种或第二种语法。 + 路径的输出视情况使用第一种或第二种语法。 @@ -3292,7 +3273,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - polygon类型的值用下列语法声明: + polygon类型的值用下列任一种语法指定: ( ( x1 , y1 ) , ... , ( xn , yn ) ) @@ -3317,7 +3298,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 圆由一个圆心和一个半径代表。circle类型的值用下面的语法指定: + 圆由一个圆心和一个半径代表。circle类型的值用下面任一种语法指定: < ( x , y ) , r > @@ -3340,7 +3321,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 网络地址类型 - network + 网络 数据类型 @@ -3397,8 +3378,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 在对 inetcidr 数据类型排序时,IPv4 - 地址总是排在 IPv6 地址之前,包括那些封装在 IPv6 地址中或映射到 - IPv6 地址中的 IPv4 地址,例如 ::10.2.3.4 或 + 地址总是排在 IPv6 地址之前,即使后者是封装或映射 IPv4 地址所得的 IPv6 地址,例如 ::10.2.3.4::ffff:10.4.3.2 @@ -3554,7 +3534,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - <type>inet</type> vs. <type>cidr</type> + <type>inet</type> 与 <type>cidr</type> inetcidr 两种数据类型的本质区别在于: @@ -3580,12 +3560,12 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - MAC地址 + MAC 地址 macaddr - macaddr类型存储 MAC 地址,也就是以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: + macaddr类型存储 MAC 地址,例如以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: '08:00:2b:01:02:03' @@ -3619,11 +3599,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays <type>macaddr8</type> - macaddr8 (data type) + macaddr8(数据类型) - MAC地址(EUI-64格式) + MAC 地址(EUI-64 格式) macaddr @@ -3750,31 +3730,31 @@ SELECT * FROM test; - 一个 bit 串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 + 一个位串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 开销,具体取决于串的长度。(不过,长值可能会被压缩或移到行外存储, 与 中对字符串的说明相同。) - 文本搜索类型 + 文本检索类型 - 全文搜索 + 全文检索 数据类型 - 文本搜索 + 文本检索 数据类型 - PostgreSQL 提供了两种专为支持全文搜索而 - 设计的数据类型。所谓全文搜索,是指在一组自然语言 + PostgreSQL 提供了两种专为支持全文检索而 + 设计的数据类型。所谓全文检索,是指在一组自然语言 文档中查找最匹配某个 查询的文档。tsvector 类型以 - 适合文本搜索的优化形式表示文档,tsquery 类型则表示 + 适合文本检索的优化形式表示文档,tsquery 类型则表示 文本查询。关于这一功能的详细解释见 ; 相关函数和操作符的概览见 @@ -3789,7 +3769,7 @@ SELECT * FROM test; tsvector 值是一个排好序且互不重复的 词位(lexeme)列表,这些词已经过 - 规范化,以便把同一单词的不同变体合并起来 + 正规化,以便把同一单词的不同变体合并起来 (详见 )。排序和去重会在输入时自动 完成,如下例所示: @@ -3848,12 +3828,12 @@ SELECT 'a:1A fat:2B,4C cat:5D'::tsvector; 权重通常用于反映文档结构,例如把标题中的词和正文中的词区分开来。 - 文本搜索排序函数可以为不同的权重标记分配不同优先级。 + 文本检索排序函数可以为不同的权重标记分配不同优先级。 必须认识到,tsvector 类型本身并不会执行任何词语 - 规范化;它假定输入的词已经按照应用需求完成规范化。例如: + 正规化;它假定输入的词已经按照应用需求完成正规化。例如: SELECT 'The Fat Rats'::tsvector; @@ -3862,9 +3842,9 @@ SELECT 'The Fat Rats'::tsvector; 'Fat' 'Rats' 'The' - 对于大多数英文全文搜索应用来说,上述词会被视为尚未规范化,但 + 对于大多数英文全文检索应用来说,上述词会被视为尚未正规化,但 tsvector 并不在意。原始文档文本通常应先经过 - to_tsvector,以按搜索需要对词语进行规范化: + to_tsvector,以按检索需要对词语进行正规化: SELECT to_tsvector('english', 'The Fat Rats'); @@ -3953,9 +3933,9 @@ SELECT 'super:*'::tsquery; 引号的使用规则与前面介绍 tsvector 时相同;同样, - 与 tsvector 一样,任何需要的词语规范化都必须在 + 与 tsvector 一样,任何需要的词语正规化都必须在 转换为 tsquery 类型之前完成。to_tsquery - 函数很适合用来实现这种规范化: + 函数很适合用来实现这种正规化: SELECT to_tsquery('Fat:ab & Cats'); @@ -3981,8 +3961,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); ---------------+------------ 'postgradu':1 | 'postgr':* - 因而它能够匹配其带前缀的后继形式 - postgraduate。 + 因而它能够匹配postgraduate 词干化后的形式。 @@ -4000,7 +3979,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); uuid 数据类型用于存储由 RFC 4122、 ISO/IEC 9834-8:2005 及相关标准定义的通用唯一标识符(UUID)。 - (有些系统把这种数据类型称为全局唯一标识符,或 GUID, + (有些系统把这种数据类型称为全局唯一标识符,或 GUID GUID。)这种标识符是一个 128 位的量,由某种算法生成,该算法被设计为使同一算法在已知宇宙中 被其他人生成出相同标识符的概率极低。因此,对于分布式系统而言, @@ -4017,7 +3996,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11 PostgreSQL 也接受其他输入形式:可以使用 - 大写字母、用花括号包围标准格式、忽略部分或全部连字符,或者在任意 + 大写字母、用花括号包围标准格式、省略部分或全部连字符,或者在任意 4 位分组后额外加上连字符。例如: A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11 @@ -4118,8 +4097,8 @@ XMLSERIALIZE ( { DOCUMENT | CONTENT } value AS XMLPARSE 或 XMLSERIALIZE 的情况下与 xml 类型互相转换时, 选择 DOCUMENT 还是 CONTENT - 由会话配置参数 XML option - XML option 决定,可以使用 + 由会话配置参数 XML 选项 + XML 选项 决定,可以使用 标准命令设置: SET XML OPTION { DOCUMENT | CONTENT }; @@ -4136,20 +4115,20 @@ SET xmloption TO { DOCUMENT | CONTENT }; 编码处理 - 在客户端、服务器以及其间传输的 XML 数据上处理多字符编码时, + 在客户端、服务器以及其间传输的 XML 数据上处理多种字符编码时, 必须格外小心。使用文本模式向服务器发送查询并把查询结果返回给 - 客户端时,PostgreSQL 会将客户端与 + 客户端时(这是通常使用的模式),PostgreSQL 会将客户端与 服务器之间传输的所有字符数据转换为目标端的字符编码,参见 。这也包括表示 XML 值的字符串,如上例 所示。这通常意味着,由于字符数据在客户端和服务器之间传输时可能被 转换为其他编码,XML 数据中包含的编码声明可能会失效,因为内嵌的 编码声明本身并不会被修改。为处理这种情况,表示 xml 类型输入值的字符串中所包含的编码声明会被 - 忽略,其内容被假定为当前服务器编码。随后, + 忽略,其内容被假定为当前服务器编码。因此, 为了正确处理,客户端发出的 XML 数据字符串必须采用当前客户端编码。 客户端负责在将文档发送给服务器之前把它们转换为当前客户端编码, 或适当调整客户端编码。输出时,xml 类型值不会带有 - 编码声明,而客户端会假定所有数据都采用当前客户端编码。 + 编码声明,而客户端应假定所有数据都采用当前客户端编码。 @@ -4183,7 +4162,7 @@ SET xmloption TO { DOCUMENT | CONTENT }; xml 数据类型有些特殊,因为它不提供任何比较操作符。 这是因为对 XML 数据并不存在良定义且通用的比较算法。其结果是, - 你无法通过把某个 xml 值与搜索值比较来检索行。 + 你无法通过把某个 xml 列与搜索值比较来检索行。 因此,XML 值通常应伴随一个独立的键字段,例如 ID。另一种比较 XML 值的办法,是先把它们转换成字符串;但请注意,字符串比较对 XML 的比较需求通常帮助不大。 @@ -4191,14 +4170,14 @@ SET xmloption TO { DOCUMENT | CONTENT }; 由于 xml 数据类型没有可用的比较操作符,因此无法直接 - 在这种类型上创建索引。如果需要在 XML 中快速搜索,可行方案包括: + 在这种类型的列上创建索引。如果需要在 XML 中快速搜索,可行方案包括: 将表达式转换为字符串类型后为其建立索引,或者为某个 XPath 表达式 建立索引。当然,实际查询也必须相应调整为使用该被索引的表达式。 - PostgreSQL 的文本搜索功能也可用于加速 - XML 数据的全文搜索。不过,目前 PostgreSQL 发行版中仍缺少所需的 + PostgreSQL 的文本检索功能也可用于加速 + XML 数据的全文检索。不过,目前 PostgreSQL 发行版中仍缺少所需的 预处理支持。 @@ -4213,12 +4192,12 @@ SET xmloption TO { DOCUMENT | CONTENT }; 域类型 - domain + - data type - domain + 数据类型 + @@ -4230,13 +4209,13 @@ SET xmloption TO { DOCUMENT | CONTENT }; CREATE DOMAIN posint AS integer CHECK (VALUE > 0); CREATE TABLE mytable (id posint); -INSERT INTO mytable VALUES(1); -- works -INSERT INTO mytable VALUES(-1); -- fails +INSERT INTO mytable VALUES(1); -- 成功 +INSERT INTO mytable VALUES(-1); -- 失败 - 当底层类型的一个操作符或函数适用于一个域值时,域会被自动向下转换为底层类型。因此,mytable.id - 1的结果会被认为是类型integer而不是posint。我们可以写成(mytable.id - 1)::posint来把结果转换回posint,这会导致域的约束被重新检查。在这种情况下,如果该表达式被应用于一个值为1的id就会错误。把底层类型的值赋给域类型的一个字段或者变量不需要写显式的类型转换,但是域的约束将会被检查。 + 当底层类型的一个操作符或函数被应用于一个域值时,域会被自动向下转换为底层类型。因此,mytable.id - 1的结果会被认为是类型integer而不是posint。我们可以写成(mytable.id - 1)::posint来把结果转换回posint,这会导致域的约束被重新检查。在这种情况下,如果该表达式被应用于一个值为1的id就会报错。把底层类型的值赋给域类型的一个字段或者变量不需要写显式的类型转换,但是域的约束将会被检查。 @@ -4319,7 +4298,7 @@ INSERT INTO mytable VALUES(-1); -- fails 对象标识符(OID)在 PostgreSQL 内部被用作 若干系统表的主键。类型 oid 表示一个对象标识符。 - 此外还有若干 oid 的别名类型,统称为 + 此外还有若干 oid 的别名类型,其名称均形如 regsomething 给出了概要说明。 @@ -4396,14 +4375,14 @@ SELECT * FROM pg_attribute regconfig pg_ts_config - 文本搜索配置 + 文本检索配置 english regdictionary pg_ts_dict - 文本搜索字典 + 文本检索词典 simple @@ -4439,7 +4418,7 @@ SELECT * FROM pg_attribute regprocedure pg_proc - 函数与参数类型 + 带参数类型的函数 sum(int4) @@ -4475,7 +4454,7 @@ SELECT * FROM pg_attribute - 这些类型的输入函数允许在各个标记之间插入空白,并且会把大写字母 + 这些类型的输入函数允许在各个词元之间插入空白,并且会把大写字母 折叠为小写,双引号内除外;这样做是为了让语法规则更接近 SQL 中 书写对象名的方式。反过来,如果需要让输出成为有效的 SQL 标识符, 输出函数会自动加上双引号。例如,一个名为 Foo @@ -4550,8 +4529,7 @@ WHERE ... 它就会对被引用对象建立依赖。例如,如果某列的默认表达式是 nextval('my_seq'::regclass)PostgreSQL 就会知道该默认表达式依赖于 - 序列 my_seq,因此系统在删除该序列之前,必须先 - 移除该默认表达式。改用 + 序列 my_seq,因此系统不允许在尚未移除该默认表达式时删除序列。改用 nextval('my_seq'::text) 则不会建立依赖。 (regrole 是这一特性的例外:该类型的常量不允许出现在 存储表达式中。) @@ -4751,7 +4729,7 @@ WHERE ... anyarray - 表示一个函数可以接受任意数组数据类型(参见 + 表示一个函数可以接受任意数组数据类型(参见)。 @@ -4870,7 +4848,7 @@ WHERE ... unknown - 标识一种尚未解析出的类型,例如未修饰的字符串字面值。 + 标识一种尚未解析出的类型,例如未修饰的字符串字面值的类型。 @@ -4888,7 +4866,7 @@ WHERE ... voidrecord 用作结果类型 (如果函数被用作触发器或事件触发器,则也允许 triggerevent_trigger 作为结果类型)。 - 有些语言还支持借助多态伪类型来实现多态函数;详见 + 有些语言还支持借助上面列出的多态伪类型来实现多态函数;详见 diff --git a/zh/17/dict-int.sgml b/zh/17/dict-int.sgml index ccca92cc..63d7ccf8 100644 --- a/zh/17/dict-int.sgml +++ b/zh/17/dict-int.sgml @@ -1,16 +1,16 @@ - dict_int — 用于整数的示例全文搜索词典 + dict_int — 用于整数的示例全文检索词典 dict_int - dict_int是一个全文搜索附加词典模板的示例。 + dict_int是一个全文检索附加词典模板的示例。 引入这个示例词典是为了控制整数(有符号和无符号)的索引, - 使这类数字能够被索引,同时又避免唯一词的数量过度增长, + 使这类数字能够被索引,同时又避免不同词的数量过度增长, 因为那会严重影响搜索性能。 @@ -54,7 +54,7 @@ 用法 - 安装dict_int扩展后,会创建一个文本搜索模板 + 安装dict_int扩展后,会创建一个文本检索模板 intdict_template以及一个基于该模板、使用默认参数的词典 intdict。你可以修改这些参数,例如: @@ -77,7 +77,7 @@ mydb# select ts_lexize('intdict', '12345678'); 但在实际使用中,通常需要像所述那样, - 将它包含到某个文本搜索配置中。可能类似如下: + 将它包含到某个文本检索配置中。可能类似如下: ALTER TEXT SEARCH CONFIGURATION english diff --git a/zh/17/func.sgml b/zh/17/func.sgml index 2ba7f97d..03ed655e 100644 --- a/zh/17/func.sgml +++ b/zh/17/func.sgml @@ -2739,7 +2739,7 @@ SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -- 检测至少有一个 null 还有其他字符串操作函数和操作符,列在中。 (其中一些用于内部实现中列出的SQL标准字符串函数。) - 此外,中还描述了模式匹配操作符,中则描述了全文搜索操作符。 + 此外,中还描述了模式匹配操作符,中则描述了全文检索操作符。
@@ -11585,7 +11585,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 文本搜索函数和操作符 + 文本检索函数和操作符 全文检索 @@ -11593,7 +11593,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 文本搜索 + 文本检索 函数和操作符 @@ -11601,12 +11601,12 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple 以及 - 总结了为全文检索提供的函数和操作符。PostgreSQL的文本搜索功能的详细解释可参考。 + 总结了为全文检索提供的函数和操作符。PostgreSQL的文本检索功能的详细解释可参考
- 文本搜索操作符 + 文本检索操作符 @@ -11766,12 +11766,12 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple 除了这些专用操作符之外, 中所示的常用比较操作符也适用于tsvectortsquery类型。 - 这些操作符对文本搜索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。 + 这些操作符对文本检索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。
- 文本搜索函数 + 文本检索函数 @@ -11818,7 +11818,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple regconfig - 返回当前默认文本搜索配置的OID(由 所设定的). + 返回当前默认文本检索配置的 OID(由 设置)。 get_current_ts_config() @@ -12354,18 +12354,18 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 所有接受一个可选的regconfig参数的文本搜索函数在省略该参数时,会使用由指定的配置。 + 所有接受一个可选的regconfig参数的文本检索函数在省略该参数时,会使用由指定的配置。 - 中的函数被单独列出,因为它们通常不被用于日常的文本搜索操作。 - 它们主要有助于开发和调试新的文本搜索配置。 + 中的函数被单独列出,因为它们通常不被用于日常的文本检索操作。 + 它们主要有助于开发和调试新的文本检索配置。
- 文本搜索调试函数 + 文本检索调试函数 @@ -12401,7 +12401,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple lexemestext[] ) - 根据指定的或默认的文本搜索配置从document中提取和正规化词元,并返回关于每个词元是如何处理的信息。 + 根据指定的或默认的文本检索配置从document中提取和正规化词元,并返回关于每个词元是如何处理的信息。 详情参见 diff --git a/zh/17/gist.sgml b/zh/17/gist.sgml index ea363b26..4ce60de5 100644 --- a/zh/17/gist.sgml +++ b/zh/17/gist.sgml @@ -983,7 +983,7 @@ my_sortsupport(PG_FUNCTION_ARGS) 示例 - PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本搜索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: + PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本检索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: diff --git a/zh/17/json.sgml b/zh/17/json.sgml index bbbbf9e0..58e024c8 100644 --- a/zh/17/json.sgml +++ b/zh/17/json.sgml @@ -38,7 +38,7 @@ - 由于 json 类型存储的是输入文本的精确副本,因此它会保留标记 + 由于 json 类型存储的是输入文本的精确副本,因此它会保留词元 之间在语义上无关紧要的空白,以及 JSON 对象内部键的顺序。此外,如果值中 的某个 JSON 对象包含同一个键多次,所有键/值对都会被保留下来(处理函数会 将最后一个值视为生效值)。相比之下,jsonb 不保留空白,不保留 @@ -86,7 +86,7 @@ 当把文本形式的 JSON 输入转换为 jsonb 时, - RFC 7159 描述的基本类型会有效映射到原生的 + RFC 7159 描述的基本类型实际上会映射到原生的 PostgreSQL 类型上,如 所示。因此,什么样的数据构成 有效的 jsonb 会有一些额外但较小的限制,这些限制不适用于 @@ -137,7 +137,7 @@ null - (无) + (无) SQL NULL 是不同的概念 @@ -152,18 +152,18 @@ 以下都是有效的 json(或 jsonb)表达式: --- Simple scalar/primitive value --- Primitive values can be numbers, quoted strings, true, false, or null +-- 简单的标量/基本值 +-- 基本值可以是数字、加引号的字符串、true、false 或 null SELECT '5'::json; --- Array of zero or more elements (elements need not be of same type) +-- 包含零个或多个元素的数组(元素不必是同一类型) SELECT '[1, 2, "foo", null]'::json; --- Object containing pairs of keys and values --- Note that object keys must always be quoted strings +-- 包含键值对的对象 +-- 注意,对象的键必须始终是加引号的字符串 SELECT '{"bar": "baz", "balance": 7.77, "active": false}'::json; --- Arrays and objects can be nested arbitrarily +-- 数组和对象可以任意嵌套 SELECT '{"foo": [true, "bar"], "tags": {"a": 1, "b": null}}'::json; @@ -219,8 +219,7 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 当 JSON 数据存储在表中时,它与任何其他数据类型一样,都要面对相同的并发控 制考量。虽然存储大型文档是可行的,但要记住,任何更新都会在整行上获取一个 行级锁。应考虑将 JSON 文档限制在可管理的大小,以减少更新事务之间的锁争用。 - 理想情况下,每个 JSON 文档都应表示一个原子数据项,按照业务规则,它不应被 - 合理地进一步拆分为更小且可独立修改的数据项。 + 理想情况下,每个 JSON 文档都应表示一个原子数据项,根据业务规则,无法再合理地将它细分为更小且可独立修改的数据项。 @@ -228,11 +227,11 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; <type>jsonb</type> 包含与存在 jsonb - containment + 包含 jsonb - existence + 存在 测试 包含jsonb 的一项重要能力。 @@ -241,33 +240,32 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 示例都返回真: --- Simple scalar/primitive values contain only the identical value: +-- 简单的标量/基本值只包含相同的值: SELECT '"foo"'::jsonb @> '"foo"'::jsonb; --- The array on the right side is contained within the one on the left: +-- 左侧数组包含右侧数组: SELECT '[1, 2, 3]'::jsonb @> '[1, 3]'::jsonb; --- Order of array elements is not significant, so this is also true: +-- 数组元素的顺序无关紧要,因此下面的结果也为真: SELECT '[1, 2, 3]'::jsonb @> '[3, 1]'::jsonb; --- Duplicate array elements don't matter either: +-- 重复的数组元素也无关紧要: SELECT '[1, 2, 3]'::jsonb @> '[1, 2, 2]'::jsonb; --- The object with a single pair on the right side is contained --- within the object on the left side: +-- 左侧对象包含右侧只有一个键值对的对象: SELECT '{"product": "PostgreSQL", "version": 9.4, "jsonb": true}'::jsonb @> '{"version": 9.4}'::jsonb; --- The array on the right side is not considered contained within the --- array on the left, even though a similar array is nested within it: -SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- yields false +-- 左侧数组被认为包含右侧数组, +-- 尽管其中嵌套了一个类似的数组: +SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- 结果为假 --- But with a layer of nesting, it is contained: +-- 但增加一层嵌套后,就构成了包含关系: SELECT '[1, 2, [1, 3]]'::jsonb @> '[[1, 3]]'::jsonb; --- Similarly, containment is not reported here: -SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- yields false +-- 同样,下面也不构成包含关系: +SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- 结果为假 --- A top-level key and an empty object is contained: +-- 包含由顶层键和空对象构成的对象: SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; @@ -282,11 +280,11 @@ SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; 对于结构必须匹配这一一般原则,有一个特殊例外:数组可以包含一个基本值: --- This array contains the primitive string value: +-- 这个数组包含该基本字符串值: SELECT '["foo", "bar"]'::jsonb @> '"bar"'::jsonb; --- This exception is not reciprocal -- non-containment is reported here: -SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false +-- 这个例外并不对称——下面的结果表示不包含: +SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- 结果为假 @@ -296,19 +294,19 @@ SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false 外,下面这些示例都返回真: --- String exists as array element: +-- 字符串作为数组元素存在: SELECT '["foo", "bar", "baz"]'::jsonb ? 'bar'; --- String exists as object key: +-- 字符串作为对象键存在: SELECT '{"foo": "bar"}'::jsonb ? 'foo'; --- Object values are not considered: -SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- yields false +-- 不考虑对象的值: +SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- 结果为假 --- As with containment, existence must match at the top level: -SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- yields false +-- 与包含关系一样,存在性必须在顶层匹配: +SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- 结果为假 --- A string is considered to exist if it matches a primitive JSON string: +-- 如果字符串与一个基本 JSON 字符串匹配,则认为它存在: SELECT '"foo"'::jsonb ? 'foo'; @@ -322,8 +320,7 @@ SELECT '"foo"'::jsonb ? 'foo'; 由于 JSON 包含是嵌套的,因此适当的查询可以跳过对子对象的显式选择。例如, 假设我们有一个 doc 列,其顶层是对象,而且大 多数对象都带有 tags 字段,该字段中包含子对象数组。下面 - 这个查询会找出那些包含同时带有 "term":"paris" 和 - "term":"food" 的子对象的项,同时忽略 + 这个查询会找出同时出现包含 "term":"paris" 的子对象和包含 "term":"food" 的子对象的项,同时忽略 tags 数组之外的任何此类键: SELECT doc->'site_name' FROM websites @@ -353,7 +350,7 @@ SELECT doc->'site_name' FROM websites <type>jsonb</type> 索引 jsonb - indexes on + 索引 @@ -403,14 +400,14 @@ CREATE INDEX idxginp ON api USING GIN (jdoc jsonb_path_ops); 名为 jdocjsonb 列里。 如果在该列上创建了 GIN 索引,那么下面这样的查询就可以利用这个索引: --- Find documents in which the key "company" has value "Magnafone" +-- 查找键 "company" 的值为 "Magnafone" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"company": "Magnafone"}'; 但是,类似下面这样的查询就无法使用该索引,因为虽然操作符 ? 可索引,但它并未直接应用到被索引的列 jdoc 上: --- Find documents in which the key "tags" contains key or array element "qui" +-- 查找键 "tags" 包含键或数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc -> 'tags' ? 'qui'; 不过,只要适当地使用表达式索引,上述查询也可以利用索引。如果经常查询 @@ -428,7 +425,7 @@ CREATE INDEX idxgintags ON api USING GIN ((jdoc -> 'tags')); 另一种查询方法是利用包含,例如: --- Find documents in which the key "tags" contains array element "qui" +-- 查找键 "tags" 包含数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qui"]}'; jdoc 列上的简单 GIN 索引可以支持这个查询。 @@ -466,7 +463,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; @@ 操作符的查询,但相较于默认操作符类 jsonb_ops,它具有显著的性能优势。 jsonb_path_ops 索引通常比相同数据上的 - jsonb_ops 索引小得多,而且搜索条件也更具特异性,尤其是在 + jsonb_ops 索引小得多,而且搜索也更有针对性,尤其是在 查询中包含数据里频繁出现的键时。因此,搜索操作通常比使用默认操作符类时 性能更佳。 @@ -482,9 +479,9 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; 基本上,每个 jsonb_path_ops 索引项都是该值连同 - 通向该值的键一起计算出的哈希。例如,要索引 + 通向该值的键一起计算出的 hash。例如,要索引 {"foo": {"bar": "baz"}},会创建一个单独的索引项, - 其哈希值中同时纳入 foobar 和 + 其 hash 值中同时纳入 foobarbaz 这三者。因此,查找这一结构的包含查询会得到一次 非常精确的索引搜索;但完全没有办法据此找出 foo 是否 作为键出现。另一方面,jsonb_ops 索引会分别创建三个 @@ -506,7 +503,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; jsonb 还支持 btreehash 索引。通常只有在需要检查完整 JSON 文档是否相等时, 它们才有用。btreejsonb 数据项的 - 排序通常没什么太大意义,但为了完整起见,其规则如下: + 排序顺序通常很少受到关注,但为了完整起见,其规则如下: 对象 > 数组 > 布尔值 > 数字 > 字符串 > null @@ -561,27 +558,24 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; --- Extract object value by key +-- 按键提取对象的值 SELECT ('{"a": 1}'::jsonb)['a']; --- Extract nested object value by key path +-- 按键路径提取嵌套对象的值 SELECT ('{"a": {"b": {"c": 1}}}'::jsonb)['a']['b']['c']; --- Extract array element by index +-- 按下标提取数组元素 SELECT ('[1, "2", null]'::jsonb)[1]; --- Update object value by key. Note the quotes around '1': the assigned --- value must be of the jsonb type as well +-- 按键更新对象的值。注意 '1' 两边的引号:赋予的值也必须是 jsonb 类型 UPDATE table_name SET jsonb_field['key'] = '1'; --- This will raise an error if any record's jsonb_field['a']['b'] is something --- other than an object. For example, the value {"a": 1} has a numeric value --- of the key 'a'. +-- 如果任何记录的 jsonb_field['a']['b'] 不是对象,就会报错。 +-- 例如,值 {"a": 1} 的键 'a' 对应的值是数字。 UPDATE table_name SET jsonb_field['a']['b']['c'] = '1'; --- Filter records using a WHERE clause with subscripting. Since the result of --- subscripting is jsonb, the value we compare it against must also be jsonb. --- The double quotes make "value" also a valid jsonb string. +-- 使用带下标的 WHERE 子句筛选记录。由于下标操作的结果是 jsonb, +-- 与之比较的值也必须是 jsonb。双引号使 "value" 也成为合法的 jsonb 字符串。 SELECT * FROM table_name WHERE jsonb_field['key'] = '"value"'; @@ -591,19 +585,19 @@ SELECT * FROM table_name WHERE jsonb_field['key'] = '"value"'; (对象或数组)的空 JSON 值来处理: --- Where jsonb_field was NULL, it is now {"a": 1} +-- 原先为 NULL 的 jsonb_field 现在为 {"a": 1} UPDATE table_name SET jsonb_field['a'] = '1'; --- Where jsonb_field was NULL, it is now [1] +-- 原先为 NULL 的 jsonb_field 现在为 [1] UPDATE table_name SET jsonb_field[0] = '1'; - 如果对一个元素数量不足的数组指定了某个索引,就会不断追加 - NULL 元素,直到该索引可达并且可以设置该值为止。 + 如果对一个元素数量不足的数组指定了某个下标,就会不断追加 + NULL 元素,直到该下标可达并且可以设置该值为止。 --- Where jsonb_field was [], it is now [null, null, 2]; --- where jsonb_field was [0], it is now [0, null, 2] +-- 原先为 [] 的 jsonb_field 现在为 [null, null, 2]; +-- 原先为 [0] 的 jsonb_field 现在为 [0, null, 2] UPDATE table_name SET jsonb_field[2] = '2'; @@ -614,10 +608,10 @@ UPDATE table_name SET jsonb_field[2] = '2'; null 填充,直到能够放入被赋值的值为止。 --- Where jsonb_field was {}, it is now {"a": [{"b": 1}]} +-- 原先为 {} 的 jsonb_field 现在为 {"a": [{"b": 1}]} UPDATE table_name SET jsonb_field['a'][0]['b'] = '1'; --- Where jsonb_field was [], it is now [null, {"a": 1}] +-- 原先为 [] 的 jsonb_field 现在为 [null, {"a": 1}] UPDATE table_name SET jsonb_field[1]['a'] = '1'; @@ -634,7 +628,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; PL/Perl 的扩展名为 jsonb_plperljsonb_plperlu。如果使用它们, - jsonb 值会按适当方式映射为 Perl 数组、哈希和标量。 + jsonb 值会按适当方式映射为 Perl 数组、hash 和标量。 @@ -694,7 +688,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; 的。还支持非十进制整数字面量和下划线分隔符,例如 1_000_0000x1EEE_FFFF0o2730b100101。在 SQL/JSON - 路径中(以及 JavaScript 中,但不包括严格意义上的 SQL),基数前缀后面不能 + 路径中(以及 JavaScript 中,但 SQL 本身并非如此),基数前缀后面不能 直接出现下划线分隔符。 @@ -723,7 +717,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; - 路径表达式由一系列路径元素构成,可以是下列任意一种: + 路径表达式由一系列路径元素构成,这些元素可以是下列任意一种: @@ -862,7 +856,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; 类似 .**,但只选择 JSON 层次结构中指定的层级。 - 嵌套层级以整数指定。层级零对应当前对象。若要访问最低的嵌套层级, + 嵌套层级以整数指定。层级零对应当前对象。若要访问最深的嵌套层级, 可以使用 last 关键字。这是 PostgreSQL 对 SQL/JSON 标准的扩展。 @@ -880,13 +874,13 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; 可以用两种形式给出: indexstart_index to end_index。 - 第一种形式按索引返回单个数组元素。第二种形式按索引范围返回数组切片, + 第一种形式按下标返回单个数组元素。第二种形式按下标范围返回数组切片, 其中包括与给定 start_indexend_index 对应的元素。 指定的 index 可以是整数,也可以是返回单个 - 数值的表达式,该表达式会自动转换为整数。索引零对应第一个数组元素。 + 数值的表达式,该数值会自动转换为整数。下标零对应第一个数组元素。 你也可以使用 last 关键字来表示最后一个数组元素, 这对于处理长度未知的数组很有用。 diff --git a/zh/17/libpq.sgml b/zh/17/libpq.sgml index 438d2407..b92c7a89 100644 --- a/zh/17/libpq.sgml +++ b/zh/17/libpq.sgml @@ -2,7 +2,7 @@ - <application>libpq</application> - C 库 + <application>libpq</application> — C 库 libpq @@ -13,35 +13,27 @@ - libpq是应用程序员使用PostgreSQLC接口。libpq是一个库函数的集合,它们允许客户端程序传递查询给PostgreSQL后端服务器并且接收这些查询的结果。 + libpqPostgreSQLC应用程序编程接口。libpq是一组库函数,客户端程序可用它们向PostgreSQL后端服务器发送查询并接收查询结果。 - libpq也是很多其他PostgreSQL应用接口的底层引擎,包括为 C++、Perl、Python、Tcl 和 ECPG编写的接口。如果你使用那些包,某些方面的libpq行为将会对你很重要。特别是,描述了任何使用libpq的应用的用户可见的行为。 + libpq也是其他几个PostgreSQL应用程序接口的底层引擎,包括为 C++、Perl、Python、Tcl 和ECPG编写的接口。因此,对于这些包的用户,libpq行为的某些方面也很重要。特别是,描述了任何使用libpq的应用程序的用户都能观察到的行为。 - 在本章的末尾()包括了一些短程序来展示如何编写使用libpq的应用。在源代码发布的src/test/examples目录中还有一些完整的libpq应用的示例。 + 本章末尾()包含一些简短程序,展示如何编写使用libpq的程序。源代码发行包的src/test/examples目录中还提供了几个完整的libpq应用程序示例。 - 使用 libpq 的客户端程序必须包含头文件 - libpq-fe.hlibpq-fe.h, - 并且必须与 libpq 库链接。 + 使用libpq的客户端程序必须包含头文件libpq-fe.hlibpq-fe.h,并且必须与libpq库链接。 数据库连接控制函数 - - 下列函数会建立到一个PostgreSQL后端服务器的连接。 - 一个应用程序可以在一个时刻打开多个后端连接(原因之一就是为了访问多个数据库)。 - 每个连接用一个PGconnPGconn对象表示,它从函数,或得到。 - 注意这些函数将总是返回一个非空的对象指针,除非正好没有内存来分配PGconn对象。 - 在通过该连接对象发送查询之前,应该调用函数来检查返回值以确定是否得到了一个成功的连接。 - - + 以下函数用于建立到PostgreSQL后端服务器的连接。应用程序可以同时保持多个后端连接。(这样做的原因之一是访问多个数据库。)每个连接由一个PGconnPGconn对象表示,该对象可以通过以下函数获取:, + 。注意,这些函数总是返回非空的对象指针,除非内存不足,甚至无法分配PGconn对象。应调用函数检查返回值,确认连接成功后,再通过连接对象发送查询。 如果不受信任的用户能够访问一个没有采用模式的安全使用方式的数据库,那么每个会话开始时都应从search_path中移除公开可写的模式。可以把参数关键词options设置为-csearch_path=。也可以在连接后发出PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)")。这种考虑并非专门针对libpq;它适用于每一种可执行任意 SQL 命令的接口。 @@ -49,7 +41,7 @@ - 在 Unix 上,复制一个拥有打开 libpq 连接的进程可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行代码是安全的。 + 在 Unix 上,对持有已打开 libpq 连接的进程执行 fork 操作可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行程序是安全的。 @@ -76,32 +68,32 @@ PGconn *PQconnectdbParams(const char * const *keywords, - 被传递的数组可以为空,这样就会使用所有默认参数。 - 也可以只包含一个或几个参数设置。他们在长度上必须匹配。 - 对于参数数组的处理将会停止于keywords数组中第一个NULL元素。 - 而且,如果与非-NULL keywords条目相关联的values条目为NULL或者空字符串,则忽略该项并继续处理下一对数组项。 + 传入的数组可以为空,以使用所有默认参数,也可以包含一个或多个参数设置。 + 两个数组的长度必须相同。处理会在 keywords 数组的第一个 NULL 元素处停止。 + 如果某个非 NULLkeywords 元素所对应的 + values 元素为 NULL 或空字符串,则忽略这一项,继续处理下一对数组元素。 - 当expand_dbname为非零时,会检查第一个dbname关键词的值以查看它是否为一个连接字符串。 - 如果是,它被扩展到从字符串中提取的单独的连接参数。 - 该值被认为是一个连接字符串,而不仅是一个数据库名称,如果它包含一个等号(=)或者它以URI模式标志符开头, - (有关连接字符串格式的更多详情可见。) - 只有dbname的第一次出现会按这种方式处理,任何后续dbname值会被当做一个普通数据库名处理。 + 当 expand_dbname 非零时,会检查第一个 dbname 关键词的值是否为 + 连接字符串。如果是,就将其展开为从该字符串中提取的各个连接参数。 + 如果该值包含等号(=),或以 URI 方案标识符开头,就会将其视为连接字符串,而非单纯的数据库名。 + (连接字符串格式的详细说明见。) + 只有第一次出现的 dbname 会按这种方式处理;后续的 dbname 参数都作为普通数据库名处理。 - 通常,参数数组从开头到结尾进行处理。 - 当关键词有重复时,使用最后一个值(不是 NULL 或空)。 - 此规则特别适用于连接字符串中的关键字与一个出现在keywords数组中的关键字冲突的情况。 - 因此,程序员可以决定数组条目是否能被覆盖或用连接字符串获取的值覆盖。 - 出现在扩展的dbname条目之前的数组条目可以被连接字符串的字段所覆盖,反之,这些字段被dbname之后出现的数组条目所覆盖。(但是,再有,只有在那些条目支持非空值时。) + 通常会从头到尾处理参数数组。如果某个关键词重复出现,则采用最后一个非 NULL 且非空的值。 + 此规则也适用于连接字符串中的关键词与 keywords 数组中的关键词冲突的情况。 + 因此,程序员可以决定数组元素是覆盖连接字符串中的值,还是被这些值覆盖。 + 出现在要展开的 dbname 元素之前的数组元素,可以被连接字符串中的字段覆盖; + 而这些字段又会被出现在 dbname 之后的数组元素覆盖(同样,只有这些元素提供非空值时才会覆盖)。 - 在处理完所有数组条目和任何扩展的连接字符串后,所有未设置的连接参数都将使用默认值填充。 - 如果一个未设置参数的相关环境变量(参见 )被设置了,它的值会被使用。 - 如果环境变量未被设置,则使用参数的内置默认值。 + 处理完所有数组元素及展开的连接字符串后,仍未设置的连接参数将填入默认值。 + 如果某个未设置参数对应的环境变量(见)已经设置,就使用该环境变量的值; + 否则使用该参数的内置默认值。 @@ -123,7 +115,7 @@ PGconn *PQconnectdb(const char *conninfo); - 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空格分隔的一个或多个参数设置,还可以包含一个URI。详见。 + 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空白分隔的一个或多个参数设置,还可以包含一个URI。详见 @@ -146,11 +138,11 @@ PGconn *PQsetdbLogin(const char *pghost, - 这是的带有固定参数集合的前辈。它具有相同的功能,不过其中缺失的参数将总是采用默认值。对任意一个固定参数写NULL或一个空字符串将会使它采用默认值。 + 这是 的前身,使用固定的一组参数。除缺失参数始终采用默认值之外,功能相同。对于要使用默认值的任意固定参数,请传入 NULL 或空字符串。 - 如果dbName包含一个=符号或者具有一个合法的连接URI前缀,它会被当作一个conninfo字符串,就好像它已经被传递给了,并且剩余的参数则被应用为指定给。 + 如果 dbName 包含 = 符号,或具有有效的连接 URI 前缀,就会将其当作 conninfo 字符串处理,方式与将其传给 完全相同,然后按照 的规则应用其余参数。 @@ -185,7 +177,7 @@ PGconn *PQsetdb(char *pghost, PQconnectPollPQconnectPoll - nonblocking connection + 非阻塞连接 以非阻塞的方式建立一个到数据库服务器的连接。 @@ -222,7 +214,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 如果你调用,确保你追踪的该流对象不会阻塞。 + 如果你调用,确保接收追踪输出的流对象不会阻塞。 @@ -235,11 +227,11 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 要开始无阻塞的连接请求,可调用PQconnectStart或者。如果结果为空,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 + 要开始非阻塞连接请求,可调用PQconnectStart或者。如果结果为空指针,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 - 如果PQconnectStart成功,下一个阶段是轮询libpq,这样它能够继续进行连接序列。使用PQsocket(conn)来获得该数据库连接底层的套接字描述符(警告:不要假定在PQconnectPoll调用之间套接字会保持相同)。这样循环:如果PQconnectPoll(conn)上一次返回PGRES_POLLING_READING,等到该套接字准备好读取(按照select()poll()或类似的系统函数所指示的)。注意,如果你的系统提供该函数,PQsocketPoll可以帮助减少对select(2)poll(2)的样板代码。然后再次调用PQconnectPoll(conn)。反之,如果PQconnectPoll(conn)上一次返回PGRES_POLLING_WRITING,等到该套接字准备好写入,则再次调用PQconnectPoll(conn)。在第一次迭代时,即如果你还没有调用PQconnectPoll,行为就像是它上次返回了PGRES_POLLING_WRITING。持续这个循环直到PQconnectPoll(conn)返回PGRES_POLLING_FAILED指示连接过程已经失败,或者返回PGRES_POLLING_OK指示连接已经被成功地建立。 + 如果PQconnectStart成功,下一个阶段是轮询libpq,这样它能够继续进行连接序列。使用PQsocket(conn)来获得该数据库连接底层的套接字描述符(警告:不要假定在PQconnectPoll调用之间套接字会保持相同)。这样循环:如果PQconnectPoll(conn)上一次返回PGRES_POLLING_READING,等到该套接字准备好读取(按照select()poll()或类似的系统函数所指示的)。注意,PQsocketPoll封装了select(2)poll(2)(如果系统支持)的设置,可减少重复代码。然后再次调用PQconnectPoll(conn)。反之,如果PQconnectPoll(conn)上一次返回PGRES_POLLING_WRITING,等到该套接字准备好写入,则再次调用PQconnectPoll(conn)。在第一次迭代时,即如果你还没有调用PQconnectPoll,行为就像是它上次返回了PGRES_POLLING_WRITING。持续这个循环直到PQconnectPoll(conn)返回PGRES_POLLING_FAILED指示连接过程已经失败,或者返回PGRES_POLLING_OK指示连接已经被成功地建立。 @@ -329,7 +321,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 注意,尽管这些常数将被保留(为了维护兼容性),一个应用永远不应该依赖这些状态按照特定顺序出现,或者根本就不依赖它们,或者不依赖状态总是这些文档中所说的值。一个应用可能做些这样的事情: + 注意,虽然为保持兼容性会保留这些常量,但应用程序不应依赖它们按特定顺序出现,不应假定它们一定出现,也不应假定状态值一定是这里列出的某个值。应用程序可以采用如下方式: switch(PQstatus(conn)) { @@ -350,11 +342,11 @@ switch(PQstatus(conn)) - 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。否则,PQconnectStart后面跟着PQconnectPoll循环等效于。 + 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。除此之外,PQconnectStart后面跟着PQconnectPoll循环等效于 - 注意当PQconnectStart返回一个非空的指针时,你必须在用完它之后调用来处理那些结构体和任何相关的内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 + 注意当PQconnectStart返回一个非空的指针时,你必须在用完它之后调用来释放该结构体及其关联的所有内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 @@ -402,21 +394,21 @@ PQconninfoOption *PQconndefaults(void); typedef struct { char *keyword; /* 该选项的关键词 */ - char *envvar; /* 依赖的环境变量名 */ - char *compiled; /* 依赖的内置默认值 */ + char *envvar; /* 后备环境变量名 */ + char *compiled; /* 编译时设置的后备默认值 */ char *val; /* 选项的当前值,或者 NULL */ - char *label; /* 连接对话框中域的标签 */ - char *dispchar; /* 指示如何在一个连接对话框中显示这个域。值是: + char *label; /* 连接对话框中字段的标签 */ + char *dispchar; /* 指示如何在连接对话框中显示此字段。可取值: "" 显示输入的值 - "*" 密码域 - 隐藏值 + "*" 密码字段 - 隐藏值 "D" 调试选项 - 默认不显示 */ - int dispsize; /* 用于对话框的以字符计的域尺寸 */ + int dispsize; /* 对话框中的字段宽度,以字符计 */ } PQconninfoOption; - 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前缺省值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回该空指针。注意当前缺省值(val域)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 + 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前默认值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回空指针。注意当前默认值(val字段)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 @@ -437,9 +429,7 @@ PQconninfoOption *PQconninfo(PGconn *conn); - 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前缺省值。 - 返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。 - 上述所有对于的注解也适用于的结果。 + 返回一个连接选项数组。可以用它确定所有可能的 选项,以及实际用于连接服务器的值。返回值指向一个 PQconninfoOption 结构体数组,该数组以 keyword 指针为空的条目结束。上文针对 的所有注意事项,也适用于 的结果。 @@ -465,7 +455,9 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); - 如果errmsg不是NULL,那么成功时*errmsg会被设置为NULL, 否则设置为被malloc过的错误字符串以说明该问题(也可以将*errmsg设置为NULL并且函数返回NULL,这表示一种内存耗尽的情况)。 + 如果 errmsg 不是 NULL,则成功时将 *errmsg 设为 NULL; + 失败时将其设为由 malloc 分配的、用于说明问题的错误字符串。 + (也可能出现 *errmsg 被设为 NULL,同时函数返回 NULL 的情况;这表示内存不足。) @@ -495,7 +487,7 @@ void PQfinish(PGconn *conn); PQresetPQreset - 重置与服务器的通讯通道。 + 重置与服务器的通信通道。 void PQreset(PGconn *conn); @@ -513,7 +505,7 @@ void PQreset(PGconn *conn); PQresetPollPQresetPoll - 以非阻塞方式重置与服务器的通讯通道。 + 以非阻塞方式重置与服务器的通信通道。 int PQresetStart(PGconn *conn); @@ -530,7 +522,7 @@ PostgresPollingStatusType PQresetPoll(PGconn *conn); - 要发起一次连接重置,调用。如果它返回 0,那么重置失败。如果返回 1,就按使用PQresetPoll建立连接时相同的方法,继续调用PQresetPoll来重置连接。 + 要开始重置连接,请调用 。如果返回 0,表示重置失败。如果返回 1,则使用 PQresetPoll 轮询重置过程,方式与使用 PQconnectPoll 建立连接完全相同。 @@ -625,7 +617,7 @@ void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook); int callback_fn(char *buf, int size, PGconn *conn); - 随后,libpq会调用该回调,而不是调用其默认的PQdefaultSSLKeyPassHook_OpenSSL处理程序。 + 随后,libpq会调用该回调,而不是调用其默认的PQdefaultSSLKeyPassHook_OpenSSL处理程序。 回调函数应确定密钥密码,并将其复制到大小为size的结果缓冲区buf中。 buf中的字符串必须以空字符结尾。 回调函数必须返回存储在buf中的密码长度,不包括结尾的空字符。 @@ -644,7 +636,7 @@ int callback_fn(char *buf, int size, PGconn *conn); - 除了异常、longjmp(...)等情况外,回调务必不可跳出正常控制流。它必须正常返回。 + 回调不得通过异常、longjmp(...)等方式跳出正常控制流。它必须正常返回。 @@ -681,9 +673,9 @@ PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void); 几个libpq函数解析用户指定的字符串以获取连接参数。 - 这些字符串有两种被接受的格式:普通的关键字/值字符串和URI。URI通常遵循 + 这些字符串有两种被接受的格式:普通的关键词/值字符串和URI。URI通常遵循 RFC - 3986,除了允许多主机连接字符串,如下面进一步描述的那样。 + 3986,但也允许使用多主机连接字符串,详见下文。 @@ -691,10 +683,10 @@ PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void); 关键词/值连接字符串 - 在关键词/值格式中,每一个参数设置的形式都是关键词 = ,在设置之间有空白。 - 设置的等号周围的空白是可选的。 - 要写一个空值或一个包含空白的值,将它用单引号包围,例如关键词 = 'a value'。 - 值里面的单引号和反斜线必须用一个反斜线转义,即\'\\。 + 在关键词/值格式中,每一个参数设置的形式都是关键词 = ,设置之间以空格分隔。 + 设置的等号周围的空格是可选的。 + 要写一个空值或一个包含空格的值,将它用单引号包围,例如keyword = 'a value'。 + 值里面的单引号和反斜杠必须用一个反斜杠转义,即\'\\ @@ -718,22 +710,22 @@ host=localhost port=5432 dbname=mydb connect_timeout=10 postgresql://userspec@hostspec/dbname?paramspec -where userspec is: +其中 userspec 为: user:password -and hostspec is: +hostspec 为: host:port,... -and paramspec is: +paramspec 为: name=value&... - URI模式标志符可以是postgresql://postgres://。 + URI方案标识符可以是postgresql://postgres://。 每一个剩下的URI部分都是可选的。 下列示例展示了合法的URI语法: @@ -750,19 +742,15 @@ postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application postgresql:///mydb?host=localhost&port=5433 - 全部的命名参数必须匹配中列出的关键词,除了与JDBC连接URI兼容之外,ssl=true的实例转换到sslmode=require。 + 所有命名参数都必须与中列出的关键词匹配;唯一的例外是,为兼容 JDBC 连接 URI,会将 ssl=true 转换为 sslmode=require - 连接URI需要使用百分号编码 - 对其进行编码,如果其中包含具有特殊含义的符号。这里是一个示例,其中等号(=)被替换为 - %3D,空格字符被替换为 - %20: + 如果连接 URI 的任意部分包含具有特殊含义的符号,就需要使用百分号编码。下面的示例将等号(=)替换为 %3D,将空格字符替换为 %20 postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff - + 主机部分可能是主机名或一个 IP 地址。要指定一个 IPv6 地址,将它封闭在方括号中: @@ -775,7 +763,7 @@ postgresql://[2001:db8::1234]/database 主机组件会被按照参数对应的描述来解释。 特别地,如果主机部分是空或看起来像一个绝对路径名称,将使用一个 Unix 域套接字连接,否则将启动一个 TCP/IP 连接。 不过要注意,斜线是 URI 层次部分中的一个保留字符。 - 因此,要指定一个非标准的 Unix 域套接字目录,要么忽略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: + 因此,要指定一个非标准的 Unix 域套接字目录,要么省略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: postgresql:///dbname?host=/var/lib/postgresql postgresql://%2Fvar%2Flib%2Fpostgresql/dbname @@ -785,7 +773,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以在一个URI中指定多个主机,每一个都有一个可选的端口。 一个形式为postgresql://host1:port1,host2:port2,host3:port3/的URI等效于host=host1,host2,host3 port=port1,port2,port3形式的连接字符串。 - 如下所述,每一个主机都将被尝试,直到成功地建立一个连接。 + 如下所述,每一个主机都将被依次尝试,直到成功地建立一个连接。 @@ -795,7 +783,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以指定多个要连接的主机,这样它们会按给定的顺序被尝试。 - 在键/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 + 在关键词/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 在指定的每一个选项中都必须给出相同数量的元素,这样第一个hostaddr对应于第一个主机名,第二个hostaddr对应于第二个主机名,以此类推。 不过,如果仅指定一个port,它将被应用于所有的主机。 @@ -805,11 +793,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 不管是哪一种格式,单一的主机名可以被翻译成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 + 不管是哪一种格式,单一的主机名可以被解析成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 - 当多个主机被指定时或者单个主机名被翻译成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。 + 当多个主机被指定时或者单个主机名被解析成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。 @@ -831,14 +819,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 要连接的主机名。主机名如果主机名看起来像绝对路径名, - 则指定的是Unix域通信而不是TCP/IP通信;该值是存储套接字文件的目录的名称。 - (在Unix上,绝对路径名以斜杠开头。在Windows上,以驱动器号开头的路径也被识别。) - 如果主机名以@开头,则将其视为抽象命名空间中的Unix域套接字(目前在Linux和Windows上支持)。 - 当未指定host或为空时,默认行为是连接到Unix域套接字Unix域套接字在 - /tmp(或在构建PostgreSQL时指定的套接字目录)中。在Windows和 - 没有Unix域套接字的机器上,默认是连接到localhost。 - + 要连接的主机名。主机名如果主机名看起来像绝对路径名, + 则指定的是 Unix 域通信,而非 TCP/IP 通信;此值是存放套接字文件的目录名。 + (在 Unix 上,绝对路径名以斜杠开头。在 Windows 上,也会识别以驱动器号开头的路径。)如果主机名以 @ 开头,则将其视为抽象命名空间中的 Unix 域套接字(目前在 Linux 和 Windows 上支持)。 + 当未指定 host 或其值为空时,默认连接到 /tmp + (或构建 PostgreSQL 时指定的套接字目录)中的 Unix 域套接字。 + Unix 域套接字在 Windows 上,默认连接到 localhost。 + 也可以接受一个逗号分隔的主机名列表,此时列表中的每个主机名将按顺序尝试; @@ -866,7 +853,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 如果指定了host而没有指定hostaddr,则会发生主机名查找。 (当使用PQconnectPoll时,查找发生在PQconnectPoll首次考虑此主机名时, - 并且可能导致PQconnectPoll阻塞一段时间。) + 并且可能导致PQconnectPoll阻塞相当长的时间。) @@ -878,11 +865,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果同时指定了hosthostaddr, - 则hostaddr的值给出服务器的网络地址。 - 除非认证方法需要,否则host的值将被忽略, - 在这种情况下,它将用作主机名。 - + 如果同时指定了 hosthostaddr,则 hostaddr 的值给出服务器的网络地址。只有认证方法需要主机名时,才会将 host 的值用作主机名;否则忽略该值。 + 请注意,如果host不是网络地址hostaddr上服务器的名称, @@ -898,10 +882,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 没有主机名或主机地址, - libpq将使用本地的Unix域套接字进行连接; - 或者在Windows和没有Unix域套接字的机器上,它将尝试连接到localhost。 - + 如果既没有主机名也没有主机地址,libpq 会使用本地 Unix 域套接字连接;在 Windows 上,则会尝试连接到 localhost。 + @@ -935,8 +917,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - PostgreSQL用户连接的用户名。 - 默认为运行应用程序的操作系统用户名相同。 + 建立连接所用的 PostgreSQL 用户名。默认与运行应用程序的操作系统用户名相同。 @@ -946,7 +927,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果服务器要求密码认证,则使用密码。 + 服务器要求密码认证时所使用的密码。 @@ -967,7 +948,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname require_auth - 指定客户端要求服务器采用的认证方法。如果服务器没有使用所要求的方法来认证客户端,或者服务器没有完整完成认证握手,则连接将失败。也可以提供一个以逗号分隔的方法列表,此时服务器必须准确使用其中一种方法,连接才会成功。默认情况下接受任意认证方法,并且服务器也可以完全跳过认证。 + 指定客户端要求服务器采用的认证方法。如果服务器没有使用所要求的方法来认证客户端,或者服务器没有完整完成认证握手,则连接将失败。也可以提供一个以逗号分隔的方法列表,此时服务器必须恰好使用其中一种方法,连接才会成功。默认情况下接受任意认证方法,并且服务器也可以完全跳过认证。 可以在方法名前加上!前缀以表示否定,此时服务器不得尝试所列方法;除此之外,任何其他方法都可接受,并且服务器也可以完全不认证客户端。如果提供的是逗号分隔列表,服务器不得尝试其中任何一个被否定的方法。否定形式和非否定形式不能在同一设置中混用。 @@ -1045,7 +1026,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 这个选项控制客户端对通道绑定的使用。设置为require表示连接必须使用通道绑定, prefer表示客户端将在可用时选择通道绑定, 而disable则阻止使用通道绑定。默认情况下, - 如果PostgreSQL是使用SSL支持编译的,则默认为prefer; + 如果PostgreSQL是使用SSL支持编译的,则默认为prefer; 否则默认为disable @@ -1061,9 +1042,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 连接时的最长等待时间,以秒为单位(写成十进制整数,例如,10)。 - 零、负值或未指定表示无限等待。最小允许的超时时间为2秒,因此 - 1的值被解释为2。 - 此超时时间分别适用于每个主机名或IP地址。 + 零、负值或未指定表示无限等待。此超时时间分别适用于每个主机名或IP地址。 例如,如果指定了两个主机和connect_timeout 为5,如果在5秒内没有建立连接,每个主机将超时, 因此等待连接的总时间可能长达10秒。 @@ -1109,9 +1088,9 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 指定配置参数的回退值。 + 指定配置参数的后备值。 如果没有通过连接参数或PGAPPNAME环境变量为application_name指定值, - 则将使用此值。在通用实用程序中指定回退名称很有用,该程序希望设置默认应用程序名称, + 则将使用此值。在通用实用程序中指定后备名称很有用,该程序希望设置默认应用程序名称, 但允许用户覆盖它。 @@ -1122,9 +1101,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制是否使用客户端TCP保持活动。默认值为1,表示开启,但如果不想要保持活动,可以将其更改为0,表示关闭。 - 对于通过Unix域套接字进行的连接,此参数将被忽略。 - + 控制是否使用客户端 TCP keepalive。默认值为 1,表示开启;如果不需要 keepalive,可以将其设为 0,表示关闭。对于通过 Unix 域套接字建立的连接,此参数会被忽略。 + @@ -1133,11 +1111,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在多少秒的不活动后,TCP应向服务器发送保持活动消息。值为零使用系统默认值。 - 对通过Unix域套接字进行的连接或禁用保持活动的连接,此参数将被忽略。 - 仅在支持TCP_KEEPIDLE或等效套接字选项的系统以及Windows上支持; - 在其他系统上,它没有任何效果。 - + 控制在多久没有活动后,TCP 应向服务器发送 keepalive 消息,以秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPIDLE 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -1146,11 +1121,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在服务器未确认的情况下重新传输TCP保持活动消息的秒数。值为零时使用系统默认值。 - 此参数在通过Unix域套接字进行连接或禁用保持活动时将被忽略。 - 仅在支持TCP_KEEPINTVL或等效套接字选项的系统和Windows上支持; - 在其他系统上,此参数无效。 - + 控制未被服务器确认收到的 TCP keepalive 消息在多少秒后应被重传。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPINTVL 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -1159,11 +1131,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在客户端与服务器之间连接被视为断开之前可以丢失的TCP keepalive数量。 - 值为零时使用系统默认值。对通过Unix域套接字建立的连接或禁用keepalives的连接,此参数将被忽略。 - 仅在支持TCP_KEEPCNT或等效套接字选项的系统上受支持; - 在其他系统上,此参数无效。 - + 控制在客户端与服务器之间的连接被视为中断之前,可以丢失多少个 TCP keepalive 消息。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPCNT 或等效套接字选项的系统上受支持;在其他系统上无效。 + @@ -1172,10 +1141,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在连接在强制关闭之前,传输数据可以保持未被确认的毫秒数。 - 值为零时使用系统默认值。此参数对通过Unix域套接字进行的连接无效。 - 仅在支持TCP_USER_TIMEOUT的系统上受支持;在其他系统上,它没有效果。 - + 控制已发送的数据在连接被强制关闭之前最多可以保持未确认状态多长时间,以毫秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,此参数会被忽略。此参数仅在支持 TCP_USER_TIMEOUT 的系统上受支持;在其他系统上无效。 + @@ -1238,25 +1205,25 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个选项确定是否以及如何优先与服务器协商安全的GSS TCP/IP连接。有三种模式: + 这个选项确定是否以及以何种优先级与服务器协商安全的GSS TCP/IP连接。有三种模式: disable - 仅尝试非GSSAPI加密连接 + 仅尝试未经GSSAPI加密的连接 - prefer (默认) + prefer (默认) 如果存在GSSAPI凭据(即在凭据缓存中),首先尝试 GSSAPI加密连接;如果失败或没有凭据,则尝试 - 非GSSAPI加密连接。这是在编译PostgreSQL时使用GSSAPI支持时的默认设置。 + 未经GSSAPI加密的连接。这是在编译PostgreSQL时使用GSSAPI支持时的默认设置。 @@ -1275,7 +1242,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname gssencmode在Unix域套接字通信中被忽略。如果PostgreSQL没有编译GSSAPI支持, 使用require选项将导致错误,而prefer将被接受,但libpq实际上不会尝试 - 进行GSSAPI加密连接。GSSAPI与libpq + 进行GSSAPI加密连接。GSSAPI在 libpq 中 @@ -1307,7 +1274,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - prefer (默认) + prefer (默认) 首先尝试SSL连接;如果失败,则尝试非SSL连接 @@ -1347,22 +1314,18 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - sslmode被忽略用于Unix域套接字通信。 - 如果PostgreSQL没有SSL支持编译, + 在 Unix 域套接字通信中,sslmode 会被忽略。 + 如果PostgreSQL编译时未启用 SSL 支持, 使用选项requireverify-caverify-full会导致错误,而选项allowprefer 将被接受,但libpq实际上不会尝试建立SSL 连接。SSL使用libpq的SSL + sortas="libpq">在 libpq 中 - 请注意,如果可能使用GSSAPI加密, - 则优先使用该加密,而不考虑SSL的值。要在具有可用GSSAPI - 基础设施(如Kerberos服务器)的环境中强制使用 - SSL加密,还需将 - gssencmode设置为disable。 - + 注意,如果可以使用 GSSAPI 加密,就会优先使用它而不是 SSL 加密,无论 sslmode 的值是什么。在具有可用 GSSAPI 基础设施(例如 Kerberos 服务器)的环境中,要强制使用 SSL 加密,还应将 gssencmode 设为 disable。 + @@ -1371,15 +1334,15 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 此选项已被sslmode设置所取代。 - + 此选项已弃用,请改用 sslmode 设置。 + 如果设置为1,则需要与服务器建立SSL连接(这相当于sslmode require)。libpq将拒绝连接,如果服务器不接受 SSL连接。如果设置为0(默认值), libpq将与服务器协商连接类型(相当于sslmode - prefer)。此选项仅在PostgreSQL编译时启用SSL支持。 + prefer)。此选项仅在 PostgreSQL 编译时启用了 SSL 支持的情况下可用。 @@ -1429,7 +1392,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果安全性不是主要考虑因素,压缩可以提高吞吐量,如果网络是瓶颈的话。如果CPU性能是限制因素,禁用压缩可以提高响应时间和吞吐量。 + 如果安全性不是主要考虑因素,压缩可以提高吞吐量,如果网络是瓶颈的话。如果CPU性能是限制因素,禁用压缩可以缩短响应时间并提高吞吐量。 @@ -1453,7 +1416,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 这个参数指定了用于客户端证书的密钥的位置。它可以指定一个文件名,该文件名将被用来替代默认的 ~/.postgresql/postgresql.key,或者它可以指定一个从外部引擎 - (引擎是OpenSSL可加载模块)获取的密钥。外部引擎规范应该包括一个由冒号分隔的引擎名称和 + (引擎是OpenSSL可加载模块)获取的密钥。外部引擎的指定形式应包含一个由冒号分隔的引擎名称和 一个引擎特定的密钥标识符。如果没有进行SSL连接,则此参数将被忽略。 @@ -1468,10 +1431,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 指定此参数为任何非空值将抑制Enter PEM pass phrase: - 当提供加密的客户端证书密钥给libpq时, - OpenSSL默认会发出的提示。 - + 当向 libpq 提供加密的客户端证书密钥时,将此参数指定为任意非空值,都将抑制 OpenSSL 默认发出的 Enter PEM pass phrase: 提示。 + 如果密钥未加密,则忽略此参数。该参数对由OpenSSL引擎指定的密钥没有影响,除非引擎使用OpenSSL密码回调机制进行提示。 @@ -1553,10 +1514,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定SSL服务器证书吊销列表(CRL)的文件名。如果存在该文件中列出的证书,在尝试验证服务器证书时将被拒绝。 - 如果既没有设置也没有设置, - 则将采用~/.postgresql/root.crl。 - + 此参数指定 SSL 服务器证书吊销列表(CRL)的文件名。如果该文件存在,在验证服务器证书时,会拒绝其中列出的证书。如果既未设置,也未设置,则采用 ~/.postgresql/root.crl。 + @@ -1565,8 +1524,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定SSL服务器证书吊销列表(CRL)的目录名称。如果存在该目录中的文件中列出的证书,在尝试验证服务器证书时将被拒绝。 - + 此参数指定 SSL 服务器证书吊销列表(CRL)的目录名。如果该目录存在,在验证服务器证书时,会拒绝该目录下文件中列出的证书。 + 目录需要使用OpenSSL命令 @@ -1581,19 +1540,17 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - sslsniServer Name Indication + sslsni服务器名称指示 - 如果设置为1(默认值),libpq会在启用SSL的连接上设置TLS扩展Server Name IndicationSNI)。 + 如果设置为1(默认值),libpq会在启用SSL的连接上设置TLS扩展服务器名称指示SNI)。 通过将此参数设置为0,可以关闭此功能。 - 服务器名称指示可以被SSL感知代理使用,以便在不解密SSL流的情况下路由连接。 - (请注意,这需要一个了解PostgreSQL协议握手的代理,而不仅仅是任何SSL代理。) - 然而,SNI会使目标主机名以明文形式出现在网络流量中,因此在某些情况下可能不希望使用。 - + 支持 SSL 的代理可以利用服务器名称指示来路由连接,而无需解密 SSL 流。(注意,除非代理能够识别 PostgreSQL 协议握手,否则需要将 sslnegotiation 设为 direct。)不过,SNI 会使目标主机名以明文形式出现在网络流量中,因此在某些情况下可能不希望使用它。 + @@ -1618,8 +1575,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定连接允许的最低SSL/TLS协议版本。有效值为TLSv1, - TLSv1.1TLSv1.2和 + 这个参数指定连接允许的最低SSL/TLS协议版本。有效值为TLSv1、 + TLSv1.1TLSv1.2TLSv1.3。支持的协议取决于所使用的 OpenSSL版本,旧版本不支持最现代的协议版本。 如果未指定,默认值为TLSv1.2,符合本文撰写时的行业最佳实践。 @@ -1632,11 +1589,10 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定连接允许的最大SSL/TLS协议版本。有效值为TLSv1, - TLSv1.1TLSv1.2和 + 这个参数指定连接允许的最大SSL/TLS协议版本。有效值为TLSv1、 + TLSv1.1TLSv1.2TLSv1.3。支持的协议取决于使用的OpenSSL - 版本,旧版本不支持最新的协议版本。如果未设置,将忽略此参数,并且连接将使用后端定义的最大限制, - 如果设置。设置最大协议版本主要用于测试或者某些组件无法使用较新协议时。 + 版本,旧版本不支持最新的协议版本。如果未设置,则忽略此参数;如果后端定义了最大限制,连接将使用该限制。设置最大协议版本主要用于测试或者某些组件无法使用较新协议时。 @@ -1646,13 +1602,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 用于使用GSSAPI进行认证时要使用的Kerberos服务名称。 + 使用 GSSAPI 认证时所用的 Kerberos 服务名。 这必须与服务器配置中指定的Kerberos认证服务名称匹配,才能成功进行认证。 (另请参见。) 默认值通常为postgres, - 但在构建PostgreSQL时可以通过 - 选项进行更改 - configure。 + 但在构建 PostgreSQL 时,可以通过 configure 选项更改。 在大多数环境中,通常不需要更改此参数。 一些Kerberos实现可能需要不同的服务名称, 例如Microsoft Active Directory需要服务名称为大写(POSTGRES)。 @@ -1676,7 +1630,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname gssdelegation - 将 GSS 凭证转发(委派)给服务器。默认值为0,表示不向服务器转发凭证。将其设置为1时,会在可能的情况下转发凭证。 + 将 GSS 凭据转发(委派)给服务器。默认值为0,表示不向服务器转发凭据。将其设置为1时,会在可能的情况下转发凭据。 @@ -1805,23 +1759,21 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 连接状态函数 - 这些函数可以被用来询问一个已有数据库连接对象的状态。 + 这些函数可用于查询现有数据库连接对象的状态。 - libpq-fe.h - libpq-int.h - libpq应用程序员应该小心地维护PGconn抽象。使用下面描述的访问函数来理解PGconn的内容。我们不推荐使用libpq-int.h引用内部的PGconn域,因为它们可能在未来改变。 - + libpq-fe.h + libpq-int.h + 编写 libpq 应用程序时,应注意维护 PGconn 的抽象。请使用下述访问函数获取 PGconn 的内容。不建议通过 libpq-int.h 引用 PGconn 的内部字段,因为这些字段将来可能改变。 + - 下列函数返回一个连接所建立的参数值。这些值在连接的生命期中是固定的。 - 如果使用的是多主机连接字符串,如果使用同一个PGconn对象建立新连接,,, 和 可能会改变。其他值在PGconn对象的一生中都是固定的。 - - + 以下函数返回建立连接时确定的参数值。这些值在连接存续期间保持不变。如果使用多主机连接字符串,并使用同一个 PGconn 对象建立新连接,则 的返回值可能改变。其他值在 PGconn 对象的整个生命周期内保持不变。 + PQdbPQdb @@ -1871,7 +1823,7 @@ char *PQpass(const PGconn *conn); - 返回活跃连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 + 返回活动连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 char *PQhost(const PGconn *conn); @@ -1883,7 +1835,7 @@ char *PQhost(const PGconn *conn); - 如果conn参数是NULL,则返回NULL。否则,如果有一个错误产生主机信息(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成主机信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1904,8 +1856,7 @@ char *PQhostaddr(const PGconn *conn); - 如果conn 参数为 NULL 返回 NULL 。 - 否则,如果生成主机信息时出现错误(如果连接尚未完全建立或出现错误),则返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成主机信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1915,7 +1866,7 @@ char *PQhostaddr(const PGconn *conn); - 返回活跃连接的端口。 + 返回活动连接的端口。 char *PQport(const PGconn *conn); @@ -1927,7 +1878,7 @@ char *PQport(const PGconn *conn); - 如果conn参数是NULL,则返回NULL。否则,如果有一个错误产生端口信息(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成端口信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -1941,9 +1892,7 @@ char *PQport(const PGconn *conn); - 这个函数不再做任何事,但是它保持了向后兼容。 - 这个函数总是返回一个空字符串,或者NULL,如果connNULL。 - + 此函数已不再执行任何操作,但为保持向后兼容仍予以保留。如果 conn 参数为 NULL,则返回 NULL;否则始终返回空字符串。 char *PQtty(const PGconn *conn); @@ -1956,7 +1905,7 @@ char *PQtty(const PGconn *conn); - 返回被传递给连接请求的命令行选项。 + 返回连接请求中传递的命令行选项。 char *PQoptions(const PGconn *conn); @@ -1964,12 +1913,11 @@ char *PQoptions(const PGconn *conn); - + - 下列函数返回会随着在PGconn对象上执行的操作改变的状态数据。 - - + 以下函数返回的状态数据,可能随着对 PGconn 对象执行操作而改变。 + PQstatusPQstatus @@ -2005,7 +1953,7 @@ ConnStatusType PQstatus(const PGconn *conn); PGTransactionStatusType PQtransactionStatus(const PGconn *conn); - 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个合法的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接损坏,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE。 + 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个有效的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接异常,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE @@ -2061,13 +2009,11 @@ const char *PQparameterStatus(const PGconn *conn, const char *paramName); - 询问所使用的 前端/后端协议。 + 查询正在使用的前端/后端协议。 int PQprotocolVersion(const PGconn *conn); - 应用可能希望用这个函数来确定某些特性是否被支持。当前,可能值是3(3.0 协议)或零(连接损坏)。 - 协议版本在连接启动完成后将不会改变,但是理论上在连接重置期间是可以改变的。 - 3.0 协议被PostgreSQL 7.4 或以后的服务器版本所支持。 +应用程序可以使用此函数判断是否支持某些特性。目前,可能的值为 3(协议 3.0)或零(连接异常)。连接启动完成后,协议版本不会改变,但理论上可能在连接重置期间改变。PostgreSQL 7.4 及更高版本的服务器支持协议 3.0。 @@ -2088,21 +2034,21 @@ int PQserverVersion(const PGconn *conn); - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 + 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,为每个部分使用两位数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 + 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。在所有主版本系列中,各次版本(缺陷修复版本)之间只有最后两位数字不同。 - PQerrorMessagePQerrorMessage + PQerrorMessagePQerrorMessage错误消息PGconn - 错误消息返回连接上的一个操作最近产生的错误消息。 + 返回连接上的一个操作最近产生的错误消息。 char *PQerrorMessage(const PGconn *conn); @@ -2111,9 +2057,7 @@ char *PQerrorMessage(const PGconn *conn); - 几乎所有的libpq在失败时都会为设置一个消息。 - 注意按照libpq习惯,一个非空结果由多行构成,并且将包括一个尾部新行。 - 调用者不应该直接释放结果。当相关的PGconn句柄被传递给时,它将被释放。在PGconn结构体上的多个操作之间,不能指望结果字符串会保持不变。 + 几乎所有 libpq 函数在失败时都会设置一条供 返回的消息。注意,按照 libpq 的约定,非空的 结果可能包含多行,并以换行符结尾。调用者不应直接释放该结果;当关联的 PGconn 句柄被传给 时,结果会被释放。不能假定在对 PGconn 结构体执行其他操作后,结果字符串仍保持不变。 @@ -2122,7 +2066,7 @@ char *PQerrorMessage(const PGconn *conn); PQsocketPQsocket - 获得到服务器连接套接字的文件描述符号。一个合法的描述符将会大于等于零。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 + 获取与服务器相连的套接字的文件描述符编号。有效描述符大于或等于 0。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 int PQsocket(const PGconn *conn); @@ -2139,7 +2083,7 @@ int PQsocket(const PGconn *conn); 返回处理这个连接的后端进程的进程ID(PID)。 PID 确定服务器进程的 PID - in libpq + 在 libpq 中 @@ -2148,7 +2092,7 @@ int PQbackendPID(const PGconn *conn); - 后端PID有助于调试目的并且可用于与NOTIFY消息(它包括发出提示的后端进程的PID)进行比较。注意PID属于一个在数据库服务器主机上执行的进程,而不是本地主机进程! + 后端 PID 可用于调试,也可与 NOTIFY 消息进行比较(消息包含发出通知的后端进程的 PID)。注意,该 PID 属于在数据库服务器主机上运行的进程,而非本地主机上的进程! @@ -2203,19 +2147,18 @@ int PQconnectionUsedGSSAPI(const PGconn *conn); - + - 以下函数返回与SSL相关的信息。这些信息通常在建立连接后不会更改。 - - + 以下函数返回与 SSL 相关的信息。这些信息通常在连接建立后不会改变。 + PQsslInUsePQsslInUse - 返回true(1)如果连接使用SSL,返回false(0)如果不使用。 + 如果连接使用 SSL,则返回真(1);否则返回假(0)。 int PQsslInUse(const PGconn *conn); @@ -2231,7 +2174,7 @@ int PQsslInUse(const PGconn *conn); - 返回与连接相关的SSL信息。 + 返回连接的 SSL 相关信息。 const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); @@ -2243,7 +2186,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); - 常见的属性如下: + 通常可以获取以下属性: library @@ -2330,18 +2273,14 @@ const char * const * PQsslAttributeNames(const PGconn *conn); - 返回一个指向描述连接的SSL实现特定对象的指针。如果连接未加密或SSL实现不提供连接的请求对象类型,则返回NULL。 + 返回指向描述此连接的对象的指针,该对象的类型由 SSL 实现决定。如果连接未加密,或连接所用的 SSL 实现不提供所请求的对象类型,则返回 NULL。 void *PQsslStruct(const PGconn *conn, const char *struct_name); - 可用的结构体取决于正在使用的SSL实现。 - 对于OpenSSL,有一个结构体, - 可以通过名称OpenSSL获得, - 并返回一个指向OpenSSLSSL结构体的指针。 - 要使用这个函数,可以使用以下代码: + 可用的结构体取决于所使用的 SSL 实现。对于 OpenSSL,可以通过名称 OpenSSL 获取一个结构体,函数返回指向 OpenSSLSSL 结构体的指针。可以使用如下代码调用此函数: #include @@ -2392,7 +2331,7 @@ void *PQgetssl(const PGconn *conn); - + @@ -2401,7 +2340,7 @@ void *PQgetssl(const PGconn *conn); 命令执行函数 - 一旦到一个数据库服务器的连接被成功建立,这里描述的函数可以被用来执行 SQL 查询和命令。 + 与数据库服务器的连接成功建立后,此处描述的函数用于执行 SQL 查询和命令。 @@ -2423,11 +2362,8 @@ PGresult *PQexec(PGconn *conn, const char *command); - 返回一个PGresult指针或者可能是一个空指针。 - 除了内存不足的情况或者由于严重错误无法将命令发送给服务器之外,一般都会返回一个非空指针。 - 函数应当被调用来检查返回值是否代表错误(包括空指针的值,它会返回PGRES_FATAL_ERROR)。 - 用可得到关于那些错误的详细信息。 - + 返回一个 PGresult 指针,也可能返回空指针。除内存不足或无法向服务器发送命令等严重错误外,通常都会返回非空指针。应调用 函数检查返回值是否表示错误(也应检查空指针,此时该函数返回 PGRES_FATAL_ERROR)。使用 获取此类错误的更多信息。 + @@ -2508,8 +2444,8 @@ PGresult *PQexecParams(PGconn *conn, paramValues[] - 指定参数的实际值。这个数组中的一个空指针表示对应的参数为空,否则该指针指向一个以零终止的文本字符串(用于文本格式)或者以服务器所期待格式的二进制数据(用于二进制格式)。 - + 指定参数的实际值。数组中的空指针表示对应参数为 null;否则,指针指向以零结尾的文本字符串(文本格式),或采用服务器所要求格式的二进制数据(二进制格式)。 + @@ -2517,8 +2453,8 @@ PGresult *PQexecParams(PGconn *conn, paramLengths[] - 指定二进制格式参数的实际数据长度。它对空参数和文本格式参数被忽略。当没有二进制参数时,该数组指针可以为空。 - + 指定二进制格式参数的实际数据长度。对于 null 参数和文本格式参数,该值会被忽略。如果没有二进制参数,数组指针可以为空指针。 + @@ -2526,11 +2462,11 @@ PGresult *PQexecParams(PGconn *conn, paramFormats[] - 指定参数是否为文本(在参数相应的数组项中放一个零)或二进制(在参数相应的数组项中放一个一)。如果该数组指针为空,那么所有参数都会被假定为文本串。 - + 指定参数采用文本格式(在对应数组元素中填入零)还是二进制格式(填入一)。如果数组指针为空指针,则将所有参数视为文本字符串。 + - 以二进制格式传递的值要求后端所期待的内部表示形式的知识。例如,整数必须以网络字节序被传递。传递numeric值要求关于服务器存储格式的知识,正如src/backend/utils/adt/numeric.c::numeric_send()以及src/backend/utils/adt/numeric.c::numeric_recv()中所实现的。 - + 以二进制格式传递值时,需要了解后端所要求的内部表示形式。例如,整数必须以网络字节序传递。传递 numeric 值时,需要了解服务器的存储格式,其实现见 src/backend/utils/adt/numeric.c::numeric_send()src/backend/utils/adt/numeric.c::numeric_recv()。 + @@ -2538,8 +2474,8 @@ PGresult *PQexecParams(PGconn *conn, resultFormat - 指定零来得到文本格式的结果,或者指定一来得到二进制格式的结果(目前没有规定要求以不同格式得到不同的结果列,尽管在底层协议中这是可以实现的)。 - + 指定零以获取文本格式的结果,指定一以获取二进制格式的结果。(目前无法让不同结果列使用不同格式,尽管底层协议支持这样做。) + @@ -2550,8 +2486,8 @@ PGresult *PQexecParams(PGconn *conn, - 相对于的主要优点是参数值可以从命令串中分离,因此避免了冗长的书写、容易发生错误的引用以及转义。 - + 相对于 的主要优点是可以将参数值与命令字符串分开,从而避免繁琐且容易出错的加引号和转义工作。 + 不同,至多允许在给定串中出现一个 SQL 命令(其中可以有分号,但是不能有超过一个非空命令)。这是底层协议的一个限制,但是有助于抵抗 SQL 注入攻击。 @@ -2560,12 +2496,12 @@ PGresult *PQexecParams(PGconn *conn, - 通过 OID 指定参数类型很罗嗦,特别是如果你不愿意将特定的 OID 值硬编码到你的程序中时。不过,即使服务器本身也无法确定参数的类型,你可以避免这样做,或者选择一种与你想要的不同的类型。在 SQL 命令文本中,附加一个显式类型转换给参数符号来表示你将发送什么样的数据类型。例如: + 通过 OID 指定参数类型较为繁琐,尤其是在不希望将具体 OID 值写死在程序中时。不过,即使服务器无法自行确定参数类型,或者推断出的类型与你所需的不同,也可以避免直接指定 OID。在 SQL 命令文本中,为参数符号添加显式类型转换,即可指定要发送的数据类型。例如: SELECT * FROM mytable WHERE x = $1::bigint; - 这强制参数$1被当作bigint,而默认情况下它将被赋予与x相同的类型。当以二进制格式发送参数值时,我们强烈推荐以这种方式或通过指定一个数字类型的 OID 来强制参数类型决定。因为二进制格式比文本格式具有更少的冗余,并且因此服务器将不会有更多机会为你检测一个类型匹配错误。 - +这会强制将参数 $1 当作 bigint,而默认情况下会为它分配与 x 相同的类型。以二进制格式发送参数值时,强烈建议采用这种方式,或直接指定类型的数值 OID,来明确决定参数类型。因为二进制格式的冗余比文本格式更少,服务器发现类型不匹配错误的机会也更少。 + @@ -2586,15 +2522,15 @@ PGresult *PQprepare(PGconn *conn, - 创建一个后面会由执行的预备语句。 + 创建一个预备语句,供随后使用 执行。 这个特性允许命令被反复执行而无需每次都进行解析和规划,详见。 - + 该函数从query串创建一个名为stmtName的预备语句,该串必须包含一个单一 SQL 命令。 stmtName可以是""来创建一个未命名语句,在这种情况下任何已存在未命名语句将被自动替换。 否则,如果语句名称已经在当前会话中被定义,则是一种错误。如果使用了任何参数,它们在查询中以$1$2等引用。 - nParams是参数的个数,其类型在数组paramTypes[]中被预先指定(当nParams为零时,该数组指针可以是NULL)。 + nParams 是在数组 paramTypes[] 中预先指定了类型的参数数量(当nParams为零时,该数组指针可以是NULL)。 paramTypes[]通过 OID 指定要赋予给参数符号的数据类型。 如果paramTypesNULL或者该数组中任何特定元素为零,服务器会用对待未指定类型的字符串字面量的方式为参数符号推测一种数据类型。 还有,查询能够使用编号高于nParams的参数符号,它们的数据类型也会被自动推测(找出推测出的数据类型的方法见)。 @@ -2602,7 +2538,7 @@ PGresult *PQprepare(PGconn *conn, 正如一样,结果通常是一个PGresult对象,其内容代表服务器端成功或失败。 - 一个空结果表示内存不足或者根本无法发送命令。关于错误的更多信息请见。 + 返回空指针表示内存不足,或者根本无法发送命令。关于错误的更多信息请见 @@ -2634,9 +2570,9 @@ PGresult *PQexecPrepared(PGconn *conn, 类似于, - 但要执行的命令是通过指定先前准备好的语句来指定,而不是提供查询字符串。 - 此功能允许重复使用的命令只被解析和计划一次,而不是每次执行时都要进行。 - 该语句必须在当前会话中先前准备好。 + 但它通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。 + 此功能使重复使用的命令只需解析和规划一次,而不必在每次执行时都进行这些工作。 + 该语句必须事先在当前会话中创建为预备语句。 @@ -2653,23 +2589,23 @@ PGresult *PQexecPrepared(PGconn *conn, - 提交请求以获取有关指定准备好的语句的信息,并等待完成。 + 提交请求以获取有关指定预备语句的信息,并等待完成。 PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - 允许应用程序获取关于先前准备的语句的信息。 + 允许应用程序获取关于先前创建的预备语句的信息。 stmtName可以是""NULL来引用 - 未命名的语句,否则必须是现有准备好的语句的名称。成功时,返回一个 + 未命名的语句,否则必须是现有预备语句的名称。成功时,返回一个 状态为PGRES_COMMAND_OKPGresult。 函数可以应用于此 - PGresult以获取有关准备语句参数的信息, + PGresult以获取有关预备语句参数的信息, 函数等提供有关语句的结果列(如果有)的信息。 @@ -2683,22 +2619,21 @@ PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - 提交请求以获取有关指定门户的信息,并等待完成。 + 提交请求以获取有关指定 portal 的信息,并等待完成。 PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - 允许应用程序获取有关先前创建的portal的信息。 - (libpq不直接提供对portals的访问,但您可以使用此函数检查使用DECLARE CURSOR SQL命令创建的游标的属性。) - + 允许应用程序获取先前创建的 portal 的信息。(libpq 不提供对 portal 的直接访问,但可以用此函数检查通过 DECLARE CURSOR SQL 命令创建的游标的属性。) + - portalName可以是""NULL来引用未命名的portal, - 否则必须是现有portal的名称。成功时,将返回一个带有状态PGRES_COMMAND_OKPGresult。 + portalName可以是""NULL来引用未命名的 portal, + 否则必须是现有 portal 的名称。成功时,将返回一个带有状态PGRES_COMMAND_OKPGresult。 函数等可应用于 - PGresult,以获取有关portal的结果列(如果有)的信息。 + PGresult,以获取有关 portal 的结果列(如果有)的信息。 @@ -2715,11 +2650,11 @@ PGresult *PQclosePrepared(PGconn *conn, const char *stmtName); - 允许应用程序关闭先前准备好的预备语句。关闭语句会释放它在服务器上的全部相关资源,并允许重复使用其名称。 + 允许应用程序关闭先前创建的预备语句。关闭语句会释放它在服务器上的全部相关资源,并允许重复使用其名称。 - stmtName可以是""NULL来引用未命名语句。如果不存在该名称的语句也没有关系;在这种情况下,该操作不会执行任何操作。成功时,会返回一个状态为PGRES_COMMAND_OKPGresult。 + stmtName可以是""NULL来引用未命名语句。如果不存在该名称的语句也没有关系;在这种情况下,不执行任何操作。成功时,会返回一个状态为PGRES_COMMAND_OKPGresult @@ -2736,11 +2671,11 @@ PGresult *PQclosePortal(PGconn *conn, const char *portalName); - 允许应用程序关闭先前创建的 portal。关闭 portal 会释放它在服务器上的全部相关资源,并允许重复使用其名称。(libpq不直接提供对 portal 的访问,但你可以使用这个函数来关闭通过DECLARE CURSOR SQL 命令创建的游标。) + 允许应用程序关闭先前创建的 portal。关闭 portal 会释放它在服务器上的全部相关资源,并允许重复使用其名称。(libpq不直接提供对 portal 的访问,但你可以使用这个函数来关闭通过DECLARE CURSOR SQL 命令创建的游标。) - portalName可以是""NULL来引用未命名的 portal。如果不存在该名称的 portal 也没有关系;在这种情况下,该操作不会执行任何操作。成功时,会返回一个状态为PGRES_COMMAND_OKPGresult。 + portalName可以是""NULL来引用未命名的 portal。如果不存在该名称的 portal 也没有关系;在这种情况下,不执行任何操作。成功时,会返回一个状态为PGRES_COMMAND_OKPGresult @@ -2748,9 +2683,8 @@ PGresult *PQclosePortal(PGconn *conn, const char *portalName); - PGresultPGresult结构体封装了由服务器返回的结果。libpq应用程序员应该小心地维护PGresult的抽象。使用下面的存储器函数来得到PGresult的内容。避免直接引用PGresult结构体的域,因为它们可能在未来更改。 - - + PGresultPGresult 结构体封装服务器返回的结果。编写 libpq 应用程序时,应注意维护 PGresult 的抽象。请使用下述访问函数获取 PGresult 的内容。避免直接引用 PGresult 结构体的字段,因为这些字段将来可能改变。 + PQresultStatusPQresultStatus @@ -2851,7 +2785,7 @@ ExecStatusType PQresultStatus(const PGresult *res); PGRES_SINGLE_TUPLE - PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单一行模式时发生(见)。 + PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单行模式时发生(见)。 @@ -2899,12 +2833,11 @@ ExecStatusType PQresultStatus(const PGresult *res); - 将返回的枚举转换成描述状态编码的字符串常量。调用者不应该释放结果。 - + 将 返回的枚举值转换为描述该状态码的字符串常量。调用者不应释放此结果。 char *PQresStatus(ExecStatusType status); - + @@ -2913,12 +2846,12 @@ char *PQresStatus(ExecStatusType status); - 返回与该命令相关的错误消息,如果有错误则会返回一个空字符串。 + 返回与命令关联的错误消息;如果没有错误,则返回空字符串。 char *PQresultErrorMessage(const PGresult *res); - 如果有一个错误,被返回的字符串将包含一个收尾的新行。调用者不应该直接释放结果。它将在相关的PGresult句柄被传递给之后被释放。 - +如果发生了错误,返回的字符串会以换行符结尾。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 + 紧跟着一个调用,(在连接上)将返回与相同的字符串(在结果上)。 @@ -2934,16 +2867,14 @@ char *PQresultErrorMessage(const PGresult *res); - 返回与PGresult对象相关的错误消息的重新格式化的版本。 + 返回与 PGresult 对象关联的错误消息的重新格式化版本。 char *PQresultVerboseErrorMessage(const PGresult *res, PGVerbosity verbosity, PGContextVisibility show_context); - 在有些情况下,客户端可能希望得到之前报告过的错误的更加详尽的版本。 - 如果在产生给定PGresult的连接上 verbosity 设置有效,会通过计算已经被产生过的消息来满足这种需求。 - 如果PGresult不是一个错误结果,则会报告PG 结果不是错误结果。返回的字符串包括一个新行作为结尾。 - +有时客户端希望获取先前报告过的错误的更详细版本。 可满足这一需求:它按指定的详细程度设置重新生成消息。假如在生成给定 PGresult 时,连接已经采用这些设置,那么 返回的就会是这条消息。如果 PGresult 不是错误结果,则改为报告 PGresult is not an error result。返回的字符串以换行符结尾。 + 和大部分从PGresult中提取数据的其他函数不同,这个函数的结果是一个全新分配的字符串。调用者在不需要这个字符串以后,必须使用PQfreemem()释放它。 @@ -2959,24 +2890,21 @@ char *PQresultVerboseErrorMessage(const PGresult *res, PQresultErrorFieldPQresultErrorField - 返回一个错误报告的一个域。 + 返回错误报告中的单个字段。 char *PQresultErrorField(const PGresult *res, int fieldcode); - fieldcode是一个错误域标识符,见下列符号。 - 如果PGresult不是一个错误或者警告结果或者不包括指定域,会返回NULL。 - 域通常不包括一个收尾的新行。调用者不应该直接释放结果。 - 它将在相关的PGresult句柄被传递给之后被释放。 - +fieldcode 是错误字段标识符,参见下文列出的符号。如果 PGresult 不是错误或警告结果,或者不包含指定字段,则返回 NULL。字段值通常不含末尾换行符。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 + - 下列域代码可用: + 下列字段代码可用: PG_DIAG_SEVERITY - 严重性。域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 @@ -2985,17 +2913,17 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_SEVERITY_NONLOCALIZED - 域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY域相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 版本以后产生的报告中。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY字段相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 及更高版本产生的报告中。 PG_DIAG_SQLSTATEerror codeslibpq + >错误码libpq - 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个域无法被本地化,并且总是存在。 + 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个字段无法被本地化,并且总是存在。 @@ -3022,7 +2950,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_MESSAGE_HINT - 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是铁的事实。可能有多行。 + 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是确切事实。可能有多行。 @@ -3040,7 +2968,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_INTERNAL_POSITION - 这被定义为与PG_DIAG_STATEMENT_POSITION域相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个域出现时,PG_DIAG_INTERNAL_QUERY域将总是出现。 + 这被定义为与PG_DIAG_STATEMENT_POSITION字段相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个字段出现时,PG_DIAG_INTERNAL_QUERY字段将总是出现。 @@ -3058,7 +2986,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONTEXT - 指示错误发生的环境。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 + 指示错误发生的上下文。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 @@ -3076,7 +3004,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_TABLE_NAME - 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名域)。 + 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名字段)。 @@ -3085,7 +3013,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_COLUMN_NAME - 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名域来标识该表)。 + 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名字段来标识该表)。 @@ -3094,7 +3022,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_DATATYPE_NAME - 如果错误与一个特定数据类型相关,这里是该数据了行的名字(该数据类型的模式名参考模式名域)。 + 如果错误与一个特定数据类型相关,这里是该数据类型的名字(该数据类型的模式名参考模式名字段)。 @@ -3103,7 +3031,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONSTRAINT_NAME - 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的域(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 + 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的字段(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 @@ -3139,16 +3067,16 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); - 用于模式名、表名、列名、数据类型名和约束名的域只提供给有限的错误类型,见。不要假定任何这些域的存在保证另一个域的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些域。同样地,不要假定这些域代表当前数据库中同类的对象。 + 用于模式名、表名、列名、数据类型名和约束名的字段只提供给有限的错误类型,见。不要假定任何这些字段的存在保证另一个字段的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些字段。同样地,不要假定这些字段代表当前数据库中现存的对象。 - 客户端负责格式化显示信息来迎合它的需要,特别是根据需要打断长的行。出现在错误消息域中的新行字符应该被当作分段而不是换行。 + 客户端负责按自身需要格式化所显示的信息,尤其应在需要时将长行折行。错误消息字段中的换行符应当视为段落分隔,而非行分隔。 - libpq内部产生的错误将有严重和主要消息,但是通常没有其他域。 + libpq内部产生的错误将包含严重性和主要消息,但是通常没有其他字段。 @@ -3161,14 +3089,12 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PQclearPQclear - 释放与一个PGresult关联的存储。每个命令结果在不再需要时都应通过释放。 - + 释放与 PGresult 关联的存储空间。每个命令结果在不再需要时都应通过 释放。 void PQclear(PGresult *res); - - 如果参数是NULL指针,则不会执行任何操作。 - +如果参数是 NULL 指针,则不执行任何操作。 + 你可以在需要时一直保留PGresult对象;它不会在你发出新命令时消失,甚至在关闭连接后也不会消失。要销毁它,你必须调用。否则应用程序会发生内存泄漏。 @@ -3176,7 +3102,7 @@ void PQclear(PGresult *res); - + @@ -3184,8 +3110,8 @@ void PQclear(PGresult *res); 检索查询结果信息 - 这些函数被用来从一个代表成功查询结果(也就是状态为PGRES_TUPLES_OK或者PGRES_SINGLE_TUPLE)的PGresult对象中抽取信息。它们也可以被用来从一个成功的 Describe 操作中抽取信息:一个 Describe 的结果具有和该查询被实际执行所提供的完全相同的列信息,但是它没有行。对于其他状态值的对象,这些函数会认为结果具有零行和零列。 - + 这些函数用于从表示成功查询结果的 PGresult 对象中提取信息,即状态为 PGRES_TUPLES_OKPGRES_SINGLE_TUPLEPGRES_TUPLES_CHUNK 的对象。它们也可用于提取成功 Describe 操作的结果信息:Describe 结果包含的列信息与实际执行查询时相同,但行数为零。对于其他状态值的对象,这些函数会将结果视为零行、零列。 + @@ -3212,7 +3138,7 @@ int PQntuples(const PGresult *res); - 返回查询结果中每一行的列(域)数。 + 返回查询结果中每一行的列(字段)数。 int PQnfields(const PGresult *res); @@ -3228,7 +3154,7 @@ int PQnfields(const PGresult *res); - 返回与给定列号相关联的列名。列号从 0 开始。调用者不应该直接释放该结果。它将在相关的PGresult句柄被传递给之后被释放。 + 返回给定列号对应的列名。列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 char *PQfname(const PGresult *res, int column_number); @@ -3260,11 +3186,11 @@ int PQfnumber(const PGresult *res, - 给定的名称被视作一个 SQL 命令中的一个标识符,也就是说,除非被双引号引用,它是小写形式的。例如,给定一个 SQL 命令: + 给定名称按 SQL 命令中的标识符处理,即除非用双引号引用,否则会转换为小写。例如,对于以下 SQL 命令生成的查询结果: SELECT 1 AS FOO, 2 AS "BAR"; - 我们将得到结果: +会得到以下结果: PQfname(res, 0) foo PQfname(res, 1) BAR @@ -3284,7 +3210,7 @@ PQfnumber(res, "\"BAR\"") 1 - 返回给定列从中取出的表的 OID。列号从 0 开始。 + 返回给定列所取自的表的 OID。列号从 0 开始。 Oid PQftable(const PGresult *res, int column_number); @@ -3297,7 +3223,7 @@ Oid PQftable(const PGresult *res, - 当你包括libpq头文件,类型oid以及常数InvalidOid将被定义。它们将都是某种整数类型。 + 包含 libpq 头文件后,将定义类型 Oid 和常量 InvalidOid。它们都属于某种整数类型。 @@ -3309,7 +3235,7 @@ Oid PQftable(const PGresult *res, - 返回构成指定查询结果列的列(在其表中)的列号。查询结果列号从 0 开始,但是表列具有非零编号。 + 返回指定查询结果列所对应的表列在表中的列号。查询结果的列号从 0 开始,而表列的编号非零。 int PQftablecol(const PGresult *res, int column_number); @@ -3329,7 +3255,7 @@ int PQftablecol(const PGresult *res, - 返回指示给定列格式的格式编码。列号从 0 开始。 + 返回表示给定列格式的格式代码。列号从 0 开始。 int PQfformat(const PGresult *res, int column_number); @@ -3337,7 +3263,7 @@ int PQfformat(const PGresult *res, - 格式代码零指示文本数据表示,而格式代码一表示二进制表示(其他代码被保留用于未来的定义)。 + 格式代码零表示文本数据,格式代码一表示二进制数据。(其他代码保留供将来定义。) @@ -3357,7 +3283,7 @@ Oid PQftype(const PGresult *res, - 你可以查询系统表pg_type来得到多个数据类型的名字和属性。 + 你可以查询系统表pg_type来获取各种数据类型的名称和属性。 内置数据类型的OID被定义在PostgreSQL安装的include目录中的catalog/pg_type_d.h文件中。 @@ -3370,7 +3296,7 @@ Oid PQftype(const PGresult *res, - 返回与给定列号相关联的列的修饰符类型。列号从 0 开始。 + 返回与给定列号相关联的列的类型修饰符。列号从 0 开始。 int PQfmod(const PGresult *res, int column_number); @@ -3378,7 +3304,7 @@ int PQfmod(const PGresult *res, - 修饰符值的解释是与类型相关的,它们通常指示精度或尺寸限制。值 -1 被用来指示没有信息可用。大部分的数据类型不适用修饰符,在那种情况中值总是 -1。 + 修饰符值的含义由数据类型决定,通常表示精度或大小限制。值 -1 表示没有可用信息。大多数数据类型不使用修饰符,此时该值始终为 -1。 @@ -3390,7 +3316,7 @@ int PQfmod(const PGresult *res, - 返回与给定列号相关的列的尺寸(以字节计)。列号从 0 开始。 + 返回给定列号对应列的大小,以字节计。列号从 0 开始。 int PQfsize(const PGresult *res, int column_number); @@ -3398,7 +3324,7 @@ int PQfsize(const PGresult *res, - 返回在一个数据库行中为这个列分配的空间,换句话说是服务器对该数据类型的内部表示的尺寸(因此,它对客户端并不是真地非常有用)。一个负值指示该数据类型是变长的。 + 返回数据库行中为该列分配的空间,即服务器内部表示该数据类型所需的大小。(因此,它对客户端用处不大。)负值表示该数据类型是变长类型。 @@ -3417,8 +3343,7 @@ int PQbinaryTuples(const PGresult *res); - 这个函数已经被废弃(除了与COPY一起使用),因为一个单一PGresult可以在某些列中包含文本数据而且在另一些列中包含二进制数据。 - 要更好。只有结果的所有列是二进制(格式 1)时才返回 1。 + 此函数已弃用(与 COPY 配合使用的情况除外),因为单个 PGresult 可能在部分列中包含文本数据,而在其他列中包含二进制数据。推荐使用 。只有结果中的所有列都采用二进制格式(格式 1)时, 才返回 1。 @@ -3430,8 +3355,7 @@ int PQbinaryTuples(const PGresult *res); - 返回一个PGresult的一行的单一域值。行和列号从 0 开始。调用者不应该直接释放该结果。 - 它将在相关的PGresult句柄被传递给之后被释放。 + 返回 PGresult 中某一行的单个字段值。行号和列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 char *PQgetvalue(const PGresult *res, int row_number, @@ -3440,15 +3364,15 @@ char *PQgetvalue(const PGresult *res, - 对于文本格式的数据,返回的值是该域值的一种空值结束的字符串表示。对于二进制格式的数据,该值是由该数据类型的typsendtypreceive函数决定的二进制表示(在这种情况下该值实际上也跟随着一个零字节,但是这通常没有用处,因为该值很可能包含嵌入的空)。 + 对于文本格式的数据, 返回字段值的字符串表示,以零字节结尾。对于二进制格式的数据,返回值采用该数据类型的 typsendtypreceive 函数所决定的二进制表示。(这种情况下,值后面实际上也有一个零字节,但通常没有用处,因为值本身很可能包含零字节。) - 如果该域值为空,则返回一个空串。关于区分空值和空字符串值请见。 + 如果字段值为 null,则返回空字符串。关于如何区分 null 值与空字符串值,参见 - 返回的指针指向作为PGresult结构体一部分的存储。我们不应该修改它指向的数据,并且如果要在超过PGresult结构体本身的生命期之外使用它,我们必须显式地把该数据拷贝到其他存储中。 + 返回的指针指向属于 PGresult 结构体的存储空间。不应修改它所指向的数据;如果需要在 PGresult 结构体的生命周期结束后继续使用这些数据,就必须显式地将数据复制到其他存储空间。 @@ -3457,12 +3381,12 @@ char *PQgetvalue(const PGresult *res, PQgetisnullPQgetisnullnull valuein libpq + >null 值libpq 中的 - 测试一个域是否为空值。行号和列号从 0 开始。 + 检查字段是否为 null 值。行号和列号从 0 开始。 int PQgetisnull(const PGresult *res, int row_number, @@ -3471,7 +3395,7 @@ int PQgetisnull(const PGresult *res, - 如果该域是空,这个函数返回 1。如果它包含一个非空值,则返回 0(注意将为一个空域返回一个空串,不是一个空指针)。 + 如果字段为 null,此函数返回 1;如果包含非 null 值,则返回 0。(注意,对于 null 字段, 返回空字符串,而非空指针。) @@ -3483,7 +3407,7 @@ int PQgetisnull(const PGresult *res, - 返回一个域值的真实长度,以字节计。行号和列号从 0 开始。 + 返回字段值的实际长度,以字节计。行号和列号从 0 开始。 int PQgetlength(const PGresult *res, int row_number, @@ -3492,9 +3416,7 @@ int PQgetlength(const PGresult *res, - 这是特定数据值的真实数据长度,也就是指向的对象的尺寸。 - 对于文本数据格式,这和strlen()相同。对于二进制格式这是基本信息。 - 注意我们应该依赖于来得到真值的数据长度。 + 这是该数据值的实际数据长度,即 所指对象的大小。对于文本格式的数据,它与 strlen() 的结果相同。对于二进制格式,这是必不可少的信息。注意,不应依赖 来获取实际数据长度。 @@ -3513,7 +3435,7 @@ int PQnparams(const PGresult *res); - 只有在查看的结果时,这个函数才有用。对于其他类型的查询,它将返回零。 + 只有在查看的结果时,这个函数才有用。对于其他类型的结果,它将返回零。 @@ -3532,7 +3454,7 @@ Oid PQparamtype(const PGresult *res, int param_number); - 只有在查看的结果时,这个函数才有用。对于其他类型的查询,它将返回零。 + 只有在查看的结果时,这个函数才有用。对于其他类型的结果,它将返回零。 @@ -3544,29 +3466,29 @@ Oid PQparamtype(const PGresult *res, int param_number); - 将所有的行打印到指定的输出流,以及有选择地将列名打印到指定的输出流。 + 将所有行输出到指定的输出流,并可选择输出列名。 void PQprint(FILE *fout, /* 输出流 */ const PGresult *res, const PQprintOpt *po); typedef struct { - pqbool header; /* 打印输出域标题和行计数 */ - pqbool align; /* 填充对齐域 */ - pqbool standard; /* 旧的格式 */ + pqbool header; /* 打印输出字段标题和行数 */ + pqbool align; /* 填充并对齐字段 */ + pqbool standard; /* 旧的简陋格式 */ pqbool html3; /* 输出 HTML 表格 */ - pqbool expanded; /* 扩展表格 */ - pqbool pager; /* 如果必要为输出使用页 */ - char *fieldSep; /* 域分隔符 */ + pqbool expanded; /* 展开表格 */ + pqbool pager; /* 需要时使用分页器输出 */ + char *fieldSep; /* 字段分隔符 */ char *tableOpt; /* 用于 HTML 表格元素的属性 */ char *caption; /* HTML 表格标题 */ - char **fieldName; /* 替换域名称的空终止数组 */ + char **fieldName; /* 以空指针结尾的替换字段名数组 */ } PQprintOpt; - 这个函数以前被psql用来打印查询结果,但是现在不是这样了。注意它假定所有的数据都是文本格式。 + psql 以前用此函数打印查询结果,现在已不再使用。注意,此函数假定所有数据都是文本格式。 @@ -3615,13 +3537,7 @@ char *PQcmdTuples(PGresult *res); - 该函数返回一个字符串,其中包含由生成PGresultSQL语句影响的行数。 - 该函数只能在执行SELECTCREATE TABLE AS、 - INSERTUPDATEDELETE、 - MERGEMOVEFETCHCOPY语句, - 或包含INSERTUPDATEDELETEMERGE语句的预处理查询的EXECUTE之后使用。 - 如果生成PGresult的命令是其他任何命令,将返回一个空字符串。 - 调用者不应直接释放返回值。当关联的PGresult句柄传递给时,它将被释放。 + 此函数返回一个字符串,其中包含产生该 PGresultSQL 语句所影响的行数。此函数只能在执行 SELECTCREATE TABLE ASINSERTUPDATEDELETEMERGEMOVEFETCHCOPY 语句之后使用,也可以在对包含 INSERTUPDATEDELETEMERGE 语句的预备查询执行 EXECUTE 之后使用。如果产生 PGresult 的是其他命令, 将返回空字符串。调用者不应直接释放返回值;当关联的 PGresult 句柄被传给 时,返回值会被释放。 @@ -3633,7 +3549,7 @@ char *PQcmdTuples(PGresult *res); - 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDin libpq。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid。 + 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDlibpq 中的。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid Oid PQoidValue(const PGresult *res); @@ -3648,7 +3564,7 @@ Oid PQoidValue(const PGresult *res); - 这个函数已经被取代,并且不是线程安全的。它返回包含被插入行的 OID 的一个字符串,而返回 OID 值。 + 此函数不是线程安全的,现已弃用,推荐改用 。它返回包含插入行 OID 的字符串,而 返回 OID 值。 char *PQoidStatus(const PGresult *res); @@ -3666,7 +3582,7 @@ char *PQoidStatus(const PGresult *res); 转义字符串 - in libpq + libpq 中的 @@ -3684,17 +3600,13 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); 为了让一个字符串可用于 SQL 命令,会对它进行转义。 - 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜线)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 + 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜杠)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 执行这种操作。 - 返回一个str参数的已被转义版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - 返回字符串中的所有特殊字符都会被替换,这样它们就能被PostgreSQL字符串字面量解析器正确处理。 - 结果中也会附加一个终止零字节,并包含包围PostgreSQL字符串字面量所需的单引号。 - + 返回 str 参数的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便 PostgreSQL 字符串字面量解析器正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号包含在结果字符串中。 + 发生错误时,返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -3708,7 +3620,7 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); - 注意,当一个数据值被作为或其兄弟例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 + 注意,当一个数据值被作为或相关例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 @@ -3726,15 +3638,12 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - 转义一个要用作 SQL 标识符的字符串,例如表名、列名或函数名。当一个用户提供的标识符可能包含被 SQL 解析器解释为标识符一部分的特殊字符时,或者当该标识符可能包含大小写形式应该被保留的大写字符时,这个函数很有用。 - + 对字符串进行转义,使其可用作 SQL 标识符,例如表名、列名或函数名。当用户提供的标识符可能包含未经转义就不会被 SQL 解析器视为标识符一部分的特殊字符,或包含需要保留大小写的大写字符时,此函数很有用。 + - 返回一个str参数的已被转义为 SQL 标识符的版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - 返回串中的所有特殊字符都被替换掉,这样它们能被作为一个 SQL 标识符正确地处理。还会加上一个终止零字节。返回串也将被双引号包围。 - + 返回 str 参数作为 SQL 标识符的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,必须使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便正确地作为 SQL 标识符处理。还会添加一个末尾零字节,并用双引号包围返回的字符串。 + 发生错误时,返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -3743,7 +3652,7 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - 与字符串一样,要阻止 SQL 注入攻击,当从一个不可信的来源接收到 SQL 标识符时,它们必须被转义。 + 与字符串字面量一样,为防止 SQL 注入攻击,从不可信来源接收到的 SQL 标识符必须经过转义。 @@ -3764,18 +3673,12 @@ size_t PQescapeStringConn(PGconn *conn, - 转义字符串,它很像。 - 与不一样的是,调用者负责提供一个合适尺寸的缓冲区。 - 此外,不产生必须包围PostgreSQL字符串的单引号。 - 它们应该在结果要插入的 SQL 命令中提供。参数from指向要被转义的串的第一个字符,并且length参数给出了这个串中的字节数。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - to应当指向一个缓冲区,它能够保持至少比length值的两倍还要多至少一个字节,否则该行为是未被定义的。 - 如果tofrom串重叠,行为也是未被定义的。 - + 对字符串字面量进行转义,与 类似。与 不同,调用者需要提供大小合适的缓冲区。此外, 不会生成包围 PostgreSQL 字符串字面量所需的单引号;应在包含转义结果的 SQL 命令中提供这些引号。from 参数指向待转义字符串的首字符,length 参数给出该字符串的字节数。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)to 必须指向一个缓冲区,其容量至少为 length 的两倍加一个字节,否则行为未定义。如果 tofrom 字符串重叠,行为同样未定义。 + - 如果error参数不是NULL,那么成功时*error被设置为零,错误时设置为非零。当前唯一可能的错误情况涉及源串中非法的多字节编码。错误时仍然会产生输出串,但是可以预期服务器将认为它是畸形的并且拒绝它。在发生错误时,一个合适的消息被存储在conn对象中,不管error是不是NULL。 - + 如果 error 参数不是 NULL,则成功时将 *error 设为零,出错时设为非零。目前唯一可能的错误是源字符串中存在无效的多字节编码。出错时仍会生成输出字符串,但预计服务器会因其格式错误而拒绝它。发生错误时,无论 error 是否为 NULL,都会在 conn 对象中保存相应消息。 + 返回写到to的字节数,不包括终止的零字节。 @@ -3790,21 +3693,19 @@ size_t PQescapeStringConn(PGconn *conn, - 是一个更老的被废弃的版本。 + 的旧版本,现已弃用。 size_t PQescapeString (char *to, const char *from, size_t length); - + - 之间的唯一区别是不需要PGconnerror参数。 - 正因为如此,它不能基于连接属性(例如字符编码)调整它的行为并且因此它可能给出错误的结果。还有,它没有方法报告错误情况。 - + 与 唯一的区别是, 不接受 PGconnerror 参数。因此,它无法根据连接属性(例如字符编码)调整行为,可能给出错误的结果。此外,它也无法报告错误情况。 + - 可以在一次只使用一个PostgreSQL连接的客户端程序中安全地使用(在这种情况下它可以在现象后面找出它需要知道的东西)。 - 在其他环境中它是一个安全性灾难并且应该用来避免。 - + 可以在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。在其他情形下,它存在安全隐患,应改用 。 + @@ -3815,7 +3716,7 @@ size_t PQescapeString (char *to, const char *from, size_t length); - 把要用于一个 SQL 命令的二进制数据用类型bytea转义。和一样,只有在将数据直接插入到一个 SQL 命令串时才使用它。 + 对二进制数据进行转义,使其能够在 SQL 命令中用作 bytea 类型的值。与 一样,这仅用于将数据直接插入 SQL 命令字符串的情况。 unsigned char *PQescapeByteaConn(PGconn *conn, const unsigned char *from, @@ -3830,14 +3731,11 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - from参数指向要被转义的串的第一个字节,并且from_length参数给出这个二进制串中的字节数(一个终止的零字节是不需要的也是不被计算的)。to_length参数指向一个将保持生成的已转义串长度的变量。这个结果串长度包括结果的终止零字节。 + from 参数指向待转义字符串的首字节,from_length 参数给出该二进制字符串的字节数。(末尾零字节既不需要,也不计入长度。)to_length 参数指向用于保存转义后字符串长度的变量。该结果字符串长度包含结果末尾的零字节。 - 返回一个from参数的已被转义为二进制串的版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 返回串中的所有特殊字符都被替换掉,这样它们能被PostgreSQL的字符串解析器以及bytea输入函数正确地处理。 - 还会加上一个终止零字节。不是结果串一部分的PostgreSQL字符串必须被单引号包围。 + 返回 from 参数所指二进制字符串的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。返回字符串中的所有特殊字符都已替换,以便 PostgreSQL 字符串字面量解析器和 bytea 输入函数正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号不包含在结果字符串中。 @@ -3853,7 +3751,7 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - 是一个更老的被废弃的版本。 + 的旧版本,现已弃用。 unsigned char *PQescapeBytea(const unsigned char *from, size_t from_length, @@ -3862,9 +3760,7 @@ unsigned char *PQescapeBytea(const unsigned char *from, - 与的唯一区别是不用一个PGconn参数。 - 正因为这样,只能在一次只使用一个PostgreSQL连接的客户端程序中安全地使用(在这种情况下它可以在现象后面找出它需要知道的东西)。 - 如果在有多个数据库连接的程序中使用,它可能给出错误的结果(在那种情况下使用)。 + 与 唯一的区别是, 不接受 PGconn 参数。因此, 只能在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。如果在使用多个数据库连接的程序中使用,它可能给出错误的结果(此时应使用 )。 @@ -3936,25 +3832,15 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - 总是收集命令的整个结果,把它缓存在一个单一的PGresult中。虽然这简化了应用的错误处理逻辑,它对于包含很多行的结果并不现实。 - + 总是收集命令的完整结果,并将其缓存在单个 PGresult 中。这简化了应用程序的错误处理逻辑,但对于包含大量行的结果,可能不切实际。 + - 如果应用程序不希望受到这些限制,可以改用构成的底层函数:。此外,还有, - , - , - , - , - ,以及,它们可以与配合使用,分别实现以下函数的功能:, - , - , - , - , - ,以及。 - - + + 如果应用程序不希望受到这些限制,可以改用构成 的底层函数:。此外, 可以与 配合使用,分别实现 的功能。 + PQsendQueryPQsendQuery @@ -3962,14 +3848,11 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - 提交一个命令到服务器,而不等待结果。 - 如果成功发送命令,则返回1,如果失败则返回0(在这种情况下,使用获取更多关于失败的信息)。 + 向服务器提交命令,不等待结果。命令发送成功时返回 1,否则返回 0(此时可使用 获取更多失败信息)。 int PQsendQuery(PGconn *conn, const char *command); - - 成功调用后,调用一次或多次来获取结果。 - 在返回空指针,表示命令执行完成之前,无法再次调用(在同一连接上)。 +成功调用 后,应调用 一次或多次来获取结果。在 返回空指针、表明命令已完成之前,不得在同一连接上再次调用 @@ -3985,7 +3868,7 @@ int PQsendQuery(PGconn *conn, const char *command); - 提交一个命令和参数到服务器,而不等待结果。 + 向服务器提交命令及独立指定的参数,不等待结果。 int PQsendQueryParams(PGconn *conn, const char *command, @@ -3996,9 +3879,7 @@ int PQsendQueryParams(PGconn *conn, const int *paramFormats, int resultFormat); - - 这相当于,不同之处在于可以单独指定查询参数而不是与查询字符串一起指定。 - 函数的参数处理方式与完全相同。与一样,它在查询字符串中只允许一个命令。 +该函数等价于 ,但查询参数可以与查询字符串分开指定。函数参数的处理方式与 相同。与 一样,查询字符串中只允许包含一条命令。 @@ -4010,7 +3891,7 @@ int PQsendQueryParams(PGconn *conn, - 发送一个请求来创建一个带有给定参数的预备语句,而不等待完成。 + 发送按给定参数创建预备语句的请求,不等待完成。 int PQsendPrepare(PGconn *conn, const char *stmtName, @@ -4018,10 +3899,7 @@ int PQsendPrepare(PGconn *conn, int nParams, const Oid *paramTypes); - - 这是的异步版本:如果能够分派请求,则返回1,否则返回0。 - 成功调用后,调用来确定服务器是否成功创建了预备语句。 - 该函数的参数处理方式与完全相同。 +这是 的异步版本:请求发送成功时返回 1,否则返回 0。调用成功后,再调用 ,确定服务器是否成功创建了预备语句。函数参数的处理方式与 相同。 @@ -4033,7 +3911,7 @@ int PQsendPrepare(PGconn *conn, - 发送一个请求来执行一个准备好的语句,带有给定的参数,而不等待结果。 + 发送使用给定参数执行预备语句的请求,不等待结果。 int PQsendQueryPrepared(PGconn *conn, const char *stmtName, @@ -4043,9 +3921,7 @@ int PQsendQueryPrepared(PGconn *conn, const int *paramFormats, int resultFormat); - - 这类似于,但要执行的命令是通过指定一个之前准备好的语句的名称来指定,而不是提供一个查询字符串。 - 函数的参数处理方式与完全相同。 +该函数类似于 ,但通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。函数参数的处理方式与 相同。 @@ -4077,7 +3953,7 @@ int PQsendDescribePrepared(PGconn *conn, const char *stmtName); - 提交请求以获取有关指定门户的信息,而无需等待完成。 + 提交请求以获取有关指定 portal 的信息,而无需等待完成。 int PQsendDescribePortal(PGconn *conn, const char *portalName); @@ -4143,13 +4019,7 @@ PGresult *PQgetResult(PGconn *conn); - 必须重复调用直到返回空指针,表示命令已完成。 - (如果在没有活动命令时调用, - 将立即返回空指针。)每个非空结果从 - 应该使用先前描述的相同PGresult访问器函数进行处理。 - 完成后不要忘记使用释放每个结果对象。请注意, - 仅在有命令处于活动状态且必要的响应数据尚未被 - 读取时才会阻塞。 + 必须反复调用 ,直到它返回空指针,表明命令已经完成。(如果当前没有正在执行的命令,调用 会立即返回空指针。)对于 返回的非空指针,应使用前文介绍的 PGresult 访问函数处理相应结果。使用完毕后,不要忘记调用 释放每个结果对象。注意,只有存在正在执行的命令,且所需响应数据尚未被 读取时, 才会阻塞。 @@ -4172,41 +4042,37 @@ PGresult *PQgetResult(PGconn *conn); - + - 使用解决了的一个问题:如果一个命令字符串包含多个SQL命令,这些命令的结果可以被个别地获得(顺便说一句:这样就允许一种简单的重叠处理形式, 客户端可以处理一个命令的结果,而同时服务器可以继续处理同一命令字符串中后面的查询)。 - + 使用 可以解决 的一个问题:如果命令字符串包含多个 SQL 命令,就能分别获取这些命令的结果。(这也支持一种简单的重叠处理方式:客户端可以处理某条命令的结果,同时服务器继续处理同一命令字符串中后面的查询。) + - 可以被获得的另一种常常想要的特性是一次从大型结果中检索一行。这会在中讨论。 - + 使用 还可以实现另一项常见需求:从大型查询结果中一次读取有限行数。详见 。 + - 就其本身而言,调用将仍会导致客户端阻塞,直到服务器完成下一个SQL命令。可以通过正确使用两个函数来避免这种情况: - - + 仅仅调用 仍会使客户端阻塞,直到服务器完成下一条 SQL 命令。可以通过正确使用另外两个函数来避免这种情况: + PQconsumeInputPQconsumeInput - 如果有来自服务器的输入可用,则使用之。 + 如果服务器有可读取的输入,则读取这些输入。 int PQconsumeInput(PGconn *conn); - 通常返回 1 表明没有错误,而返回 0 表明有某种麻烦发生(此时可以用)。 - 注意该结果并不表明是否真正收集了任何输入数据。在调用之后,应用可以检查和/或PQnotifies来看看它们的状态是否改变。 + 通常返回 1,表示没有错误;发生问题时则返回 0(此时可查看 )。注意,返回值并不说明是否实际读取了输入数据。调用 后,应用程序可以检查 和/或 PQnotifies,以确定其状态是否发生变化。 - 即使应用还不准备处理一个结果或通知,也可以被调用。 - 这个函数将读取可用的数 据并且把它保存在一个缓冲区中,从而导致一个select()的读准备好指示消失。 - 因此应用可以使用立即清除select()条件,并且在空闲时再检查结果。 + 即使应用程序尚未准备好处理结果或通知,也可以调用 。此函数会读取可用数据并将其保存在缓冲区中,从而清除 select() 的可读就绪指示。因此,应用程序可以用 立即清除 select() 的就绪条件,随后在合适的时候检查结果。 @@ -4228,15 +4094,11 @@ int PQisBusy(PGconn *conn); - + - 一个使用这些函数的典型应用将有一个主循环,在主循环中会使用select()poll()等待所有它必须响应的情况。 - 其中之一将是来自服务器的输入可用,对select()来说意味着标识的文件描述符上有可读的数据。 - 当主循环检测到输入准备好时,它将调用读取输入。 - 然后它可以调用,如果返回假(0)则接着调用。 - 它还可以调用PQnotifies检测NOTIFY消息(见)。 - + 使用这些函数的典型应用程序会在主循环中通过 select()poll() 等待需要响应的各种条件。其中一个条件是服务器有可读取的输入;对于 select(),这意味着 标识的文件描述符上有可读数据。主循环检测到输入就绪时,应调用 读取输入,然后调用 。如果 返回假(0),就可以接着调用 。还可以调用 PQnotifies 检测 NOTIFY 消息(见 )。 + 一个使用/的客户端也可以尝试取消一个正在被服务器处理的命令,见。 @@ -4244,13 +4106,8 @@ int PQisBusy(PGconn *conn); - 通过使用上面描述的函数,可以避免在等待来自数据库服务器的输入时阻塞。 - 然而,应用程序仍然可能会在等待向服务器发送输出时阻塞。 - 这在发送非常长的SQL命令或数据值时可能会发生,尽管这相对不常见。 - (如果应用程序通过COPY IN发送数据,则更有可能发生。) - 为了防止这种可能性并实现完全非阻塞的数据库操作,可以使用以下附加函数。 - - + 使用上述函数可以避免在等待数据库服务器输入时阻塞。不过,应用程序仍可能在等待向服务器发送输出时阻塞。这种情况较少见,但发送很长的 SQL 命令或数据值时可能发生。(如果应用程序通过 COPY IN 发送数据,发生的可能性则大得多。)为了防止这种情况,实现完全非阻塞的数据库操作,可以使用以下附加函数。 + PQsetnonblockingPQsetnonblocking @@ -4268,11 +4125,7 @@ int PQsetnonblocking(PGconn *conn, int arg); - 在非阻塞状态下,成功调用、 - 、 - 不会阻塞; - 它们的更改将存储在本地输出缓冲区中,直到刷新为止。 - 不成功的调用将返回错误,必须重试。 + 在非阻塞状态下,成功调用 不会阻塞;产生的数据保存在本地输出缓冲区中,等待发送。失败的调用会返回错误,必须重试。 @@ -4303,9 +4156,7 @@ int PQisnonblocking(const PGconn *conn); - 尝试将任何排队的输出数据刷新到服务器。如果成功(或发送队列为空),则返回0; - 如果由于某种原因失败,则返回-1;如果尚未能够发送发送队列中的所有数据(只有在连接为非阻塞时才会发生此情况), - 则返回1。 + 尝试将发送队列中的输出数据发送到服务器。成功(或发送队列为空)时返回 0;因某种原因失败时返回 -1;如果尚未能发送队列中的全部数据,则返回 1(这种情况只可能发生在非阻塞连接上)。 int PQflush(PGconn *conn); @@ -4313,15 +4164,11 @@ int PQflush(PGconn *conn); - + - 在一个非阻塞连接上发送任何命令或者数据之后,要调用。 - 如果它返回 1,就要等待套接字变成读准备好或写准备好。如果它变为写准备好,应再次调用。 - 如果它变为读准备好,则应先调用,然后再调用。 - 一直重复直到返回 0(有必要检查读准备好并且用耗尽输入,因为服务器可能阻塞给我们发送数据的尝试,例如 NOTICE 消息,并且在我们读它的数据之前它都不会读我们的数据)。 - 一旦返回 0,应等待套接字变成读准备好并且接着按照上文所述读取响应。 - + 在非阻塞连接上发送命令或数据后,应调用 。如果返回 1,就等待套接字变为可读或可写。套接字可写时,再次调用 ;可读时,先调用 ,再调用 。重复上述步骤,直到 返回 0。(必须检查套接字是否可读,并用 读完输入,因为服务器可能在尝试向客户端发送数据时阻塞,例如发送 NOTICE 消息;在客户端读取这些数据之前,服务器不会读取客户端发送的数据。)当 返回 0 后,等待套接字变为可读,再按前述方法读取响应。 + @@ -4335,29 +4182,26 @@ int PQflush(PGconn *conn); - pipelining - in libpq + 管道化 + 在 libpq 中 - batch mode - in libpq + 批处理模式 + 在 libpq 中 - libpq 管道模式允许应用发送查询而无需读取先前发送查询的结果。 - 利用管道模式的优点,客户端将对服务器等待的更少,因为可以在单个网络事务中发送/接收多个查询/结果。 - + libpq 的管道模式允许应用程序在尚未读取先前查询结果时继续发送查询。多个查询及其结果可以在一次网络交互中发送和接收,从而减少客户端等待服务器的时间。 + - 虽然管道模式提供了显著的性能提升, - 使用管道模式写客户端会更加复杂,因为它涉及到管理一个挂起查询的队列,并查找队列中的哪个结果对应于哪个查询。 - + 管道模式可以显著提升性能,但使用它编写客户端也更复杂,因为需要管理待处理查询队列,并确定每个结果对应队列中的哪个查询。 + - 管道模式通常也会在客户端和服务器上面消耗更多的内存,尽管仔细和积极地管理发送/接收队列可以减轻这种消耗。 - 这适用于连接是否处于阻塞或非阻塞模式。 - + 管道模式通常也会增加客户端和服务器的内存消耗,不过仔细、主动地管理发送和接收队列可以缓解这一问题。无论连接处于阻塞还是非阻塞模式,都是如此。 + 虽然libpq的管道API是在PostgreSQL 14中引入的, @@ -4370,24 +4214,8 @@ int PQflush(PGconn *conn); 使用管道模式 - 要发出管道命令,应用程序必须将连接切换到管道模式, - 可以通过来完成。 - 可以使用来测试管道模式是否激活。 - 在管道模式下,只允许使用扩展查询协议的异步操作, - 不允许包含多个SQL命令的命令字符串,也不允许使用COPY命令。 - 使用同步命令执行函数,如PQfn、 - PQexec、 - PQexecParams、 - PQprepare、 - PQexecPrepared、 - PQdescribePrepared、 - PQdescribePortal, - 都会导致错误。 - 也不允许使用PQsendQuery,因为它使用简单查询协议。 - 一旦所有已分派的命令的结果已被处理,并且 - 结束管道结果已被消耗,应用程序可以通过返回 - 到非管道模式。 - + 要使用管道,应用程序必须通过 将连接切换到管道模式。可用 检查管道模式是否已启用。在管道模式下,只允许使用扩展查询协议的异步操作,不允许命令字符串包含多个 SQL 命令,也不允许 COPY。调用同步命令执行函数,例如 PQfnPQexecPQexecParamsPQpreparePQexecPreparedPQdescribePreparedPQdescribePortalPQclosePreparedPQclosePortal,会导致错误。也不允许使用 PQsendQuery,因为它使用简单查询协议。所有已发送命令的结果及管道结束结果都读取处理完毕后,应用程序便可通过 返回非管道模式。 + @@ -4396,9 +4224,8 @@ int PQflush(PGconn *conn); 如果在阻塞模式下使用,它可能发生客户端/服务器死锁。 - 客户端将阻止尝试发送查询到服务器,但服务器将阻止从它已经处理的查询向客户端发送结果。 - 这只有当客户端在它切换到处理从服务器的输入之前发送足够的查询来填充其输出缓冲区和服务器的接收缓冲区,才会发生这种情况,但很难准确预测何时将发生。 - + 客户端在尝试向服务器发送查询时阻塞,而服务器在尝试将已处理查询的结果发送给客户端时阻塞。只有当客户端在转而处理服务器输入之前,发送了足够多的查询,填满自身的输出缓冲区和服务器的接收缓冲区,才会发生这种情况;但很难准确预测何时会发生。 + @@ -4435,8 +4262,8 @@ int PQflush(PGconn *conn); - PQisBusyPQconsumeInput 等函数在处理管道结果时照常工作。特别地,在管道处理过程中调用 PQisBusy 时,如果到目前为止已发出查询的所有结果均已被消费,则返回 0。 - + PQisBusyPQconsumeInput 等函数在处理管道结果时照常工作。特别地,在管道处理过程中调用 PQisBusy 时,如果到目前为止已发出查询的所有结果均已被读取,则返回 0。 + libpq 不向应用程序提供当前正在处理哪个查询的信息(除了 PQgetResult 返回空指针,表示开始返回下一个查询的结果)。应用程序必须跟踪查询的发送顺序,以便将查询与对应结果关联起来。应用程序通常会使用状态机或 FIFO 队列实现这一点。 @@ -4449,21 +4276,16 @@ int PQflush(PGconn *conn); 错误处理 - 从客户端的视角,在PQresultStatus返回PGRES_FATAL_ERROR之后,管道被标记为中止。 - PQresultStatus将报告一个PGRES_PIPELINE_ABORTED结果,对中止的管道中的每一个剩余的排队操作。 - PQpipelineSync的结果报告为PGRES_PIPELINE_SYNC,以表示中止管道的结束并恢复正常的结果处理。 - + 从客户端的角度看,PQresultStatus 返回 PGRES_FATAL_ERROR 后,管道就会被标记为中止。对于已中止管道中剩余的每个排队操作,PQresultStatus 都会报告一个 PGRES_PIPELINE_ABORTED 结果。PQpipelineSyncPQsendPipelineSync 的结果报告为 PGRES_PIPELINE_SYNC,表示已中止的管道结束,并恢复正常的结果处理。 + 在错误恢复时,客户端必须 使用 PQgetResult处理结果。 - 如果管道使用隐式事务,那么已经执行的操作将被回滚,而排队跟在失败操作的操作将被完全跳过。 - 同样的行为也会发生,如果管道开始并提交单个显式事务(也就是,第一个语句是BEGIN ,最后一个是COMMIT),除非会话在管道结束时保持在中止事务状态。 - 如果管道包含多个显式事务,所有在错误发生前已提交的事务都会继续保留,当前正在进行的事务会被中止,所有后续操作都会被完全跳过,包括后续事务在内。 - 如果管道同步点发生时显式事务块为中止状态,则下一个管道将立即中止,除非下一个命令使用ROLLBACK将事务置于正常模式。 - + 如果管道使用隐式事务,已经执行的操作会被回滚,而失败操作之后排队的操作会全部跳过。如果管道开始并提交单个显式事务(即第一条语句为 BEGIN,最后一条为 COMMIT),行为也相同,不过在管道结束时,会话仍处于事务中止状态。如果管道包含多个显式事务,错误发生前已经提交的事务仍保持已提交状态,当前正在进行的事务会中止,所有后续操作都会被跳过,包括后续事务。如果到达管道同步点时,显式事务块仍处于中止状态,下一个管道会立即中止,除非下一条命令使用 ROLLBACK 将事务恢复为正常状态。 + @@ -4476,24 +4298,19 @@ int PQflush(PGconn *conn); - 交叉结果处理和查询分派 + 交错处理结果与发送查询 - 为避免大型管道上的死锁,客户端将被围绕非阻塞事件循环构建,通过使用操作系统工具,如select, poll, WaitForMultipleObjectEx等等, - + 为避免大型管道发生死锁,客户端应围绕非阻塞事件循环组织,使用 selectpollWaitForMultipleObjectEx 等操作系统机制。 + - 客户端应用通常应该维护一个尚未分派的工作队列和一个已分派但尚未处理结果的工作队列。 - 当套接字是可写时,它将可以分派更多的工作。 - 当套接字是可读时,它将读取结果并处理它们,将它们匹配到相应结果队列中的下一个条目。 - 基于可用内存,来自套接字的结果将被经常读取:这里不需要等到管道结束才读取结果。 - 管道将范围涵盖到工作的逻辑单元,通常(但不是必然)每个管道一个事务。 - 在管道之间,不需要退出管道模式再重新进入管道模式,也不需要等待一个管道结束后再发送下一个。 - + 客户端应用程序通常应维护两个队列:一个存放尚未发送的工作,另一个存放已经发送但尚未处理结果的工作。套接字可写时,应继续发送工作;套接字可读时,应读取并处理结果,将其与相应结果队列中的下一个条目匹配。应根据可用内存情况,频繁地从套接字读取结果,无需等到管道结束。每个管道应对应一个逻辑工作单元,通常是一个事务,但并非必须如此。管道之间无需退出再重新进入管道模式,也无需等待一个管道完成后才发送下一个。 + - 一个使用select()和一个简单状态机来跟踪发送和接收工作的示例,在PostgreSQL源代码发行版的src/test/modules/libpq_pipeline/libpq_pipeline.c文件中。 - + PostgreSQL 源代码发行版的 src/test/modules/libpq_pipeline/libpq_pipeline.c 中提供了一个示例,使用 select() 和简单状态机跟踪已发送和已接收的工作。 + @@ -4537,7 +4354,7 @@ PGpipelineStatus PQpipelineStatus(const PGconn *conn); - libpq 连接 是管道模式。 + libpq 连接处于管道模式。 @@ -4566,18 +4383,14 @@ PGpipelineStatus PQpipelineStatus(const PGconn *conn); - 造成连接进入管道模式,如果它当前空闲或已经是管道模式。 - + 如果连接当前空闲或已处于管道模式,则使该连接进入管道模式。 int PQenterPipelineMode(PGconn *conn); - - 成功返回1. - 如果连接当前不是空闲的,返回0并且无影响,也就是说,它已经有了一个结果,或者它正在等待服务器的更多输入,等等。 - 这个函数实际上不向服务器发送任何东西,它只是更改libpq连接状态。 + 成功时返回 1。如果连接当前不空闲,例如已有结果可供读取,或正在等待服务器的更多输入,则返回 0,且不产生任何影响。此函数实际上不向服务器发送任何内容,只改变 libpq 的连接状态。 @@ -4589,16 +4402,14 @@ int PQenterPipelineMode(PGconn *conn); - 造成连接退出管道模式,如果连接当前以空队列处于管道模式,并且没有待处理的结果。 + 如果连接当前处于管道模式、队列为空且没有待读取的结果,则使该连接退出管道模式。 int PQexitPipelineMode(PGconn *conn); - 成功则返回1。 - 如果不是管道模式,则返回1并且不采取操作。 - 如果当前语句没有完成处理,或者PQgetResult尚未被调用以收集所有先前发送查询的结果,则返回0(在这种情况下,使用以获取关于故障的更多信息)。 + 成功时返回 1。如果连接不处于管道模式,也返回 1,且不执行任何操作。如果当前语句尚未处理完毕,或尚未调用 PQgetResult 读取先前发送的所有查询的结果,则返回 0(此时可使用 获取更多失败信息)。 @@ -4610,17 +4421,14 @@ int PQexitPipelineMode(PGconn *conn); - 通过发送sync message并刷新发送缓冲区的方式来标记管道中的同步点。 - 它用作隐式事务的定界符和错误恢复点;参见。 - + 通过发送同步消息并将发送缓冲区中的数据发往服务器,在管道中标记同步点。同步点作为隐式事务的分界符和错误恢复点;见 int PQpipelineSync(PGconn *conn); - 成功就返回1。 - 如果连接不是管道模式或者发送sync message失败,则返回0。 + 成功时返回 1。如果连接不处于管道模式,或发送同步消息失败,则返回 0。 @@ -4630,14 +4438,13 @@ int PQpipelineSync(PGconn *conn); - 通过发送sync message但不刷新发送缓冲区,来标记管道中的一个同步点。它可作为隐式事务的分界符和错误恢复点;参见。 - + 通过发送同步消息在管道中标记同步点,但不刷新发送缓冲区。同步点作为隐式事务的分界符和错误恢复点;见 int PQsendPipelineSync(PGconn *conn); - 成功时返回 1。如果连接不处于管道模式,或者发送sync message失败,则返回 0。请注意,该消息本身不会自动刷新到服务器;必要时请使用PQflush。 + 成功时返回 1。如果连接不处于管道模式,或发送同步消息失败,则返回 0。注意,该消息本身不会自动发送到服务器;必要时可使用 PQflush @@ -4649,21 +4456,19 @@ int PQsendPipelineSync(PGconn *conn); - 发送一个请求到服务器以刷新它的输出缓冲区。 + 请求服务器发送其输出缓冲区中的数据。 int PQsendFlushRequest(PGconn *conn); - + - 成功就返回1。 - 任何失败则返回0。 - + 成功时返回 1;发生任何失败时返回 0。 + - 当PQpipelineSync被调用的结果,或者在非管道模式下的任何请求时,服务器自动刷新它的输出缓冲区;这个函数用于使得服务器在不建立同步点的情况下以管道模式刷新其输出缓冲区。 - 请注意,请求不是自身能自动刷新到服务器;如果需要时使用PQflush。 - + 调用 PQpipelineSync 后,或者在非管道模式下收到任何请求时,服务器都会自动发送其输出缓冲区中的数据。此函数可让服务器在管道模式下发送输出缓冲区中的数据,而不建立同步点。注意,该请求本身不会自动发送到服务器;必要时可使用 PQflush。 + @@ -4674,43 +4479,36 @@ int PQsendFlushRequest(PGconn *conn); 何时使用管道模式 - 非常像异步查询模式,在使用管道模式时没有明显的性能开销。 - 它增加了客户端应用的复杂性,并且需要特别注意以防止客户端/服务器死锁。 - 但是管道模式可以提供相当大的性能改进,代价是因为状态保留更久而增加内存使用。 - + 与异步查询模式类似,使用管道模式不会带来明显的性能开销。它增加了客户端应用程序的复杂性,需要格外注意防止客户端与服务器之间的死锁,但也能显著提升性能,代价是状态保留更久,因而占用更多内存。 + - 当服务器比较远,即网络延迟(ping time)高的时候,管道模式最有用,以及在许多小操作正在快速连续执行的时候。 - 当每个查询的执行时间是客户端/服务器往返时间的许多倍时,使用管道命令的优势通常会更少。 - 不用管道模式,在往返时间为300毫秒的服务器上运行一个100条语句的操作,仅网络延迟就需要30秒;使用管道,等待来自服务器的结果可能只消耗仅仅0.3秒。 - + 当服务器距离较远,即网络延迟(ping 时间)较高,或者需要快速连续执行许多小操作时,管道模式最有用。如果每个查询的执行时间是客户端与服务器往返时间的许多倍,使用管道命令的收益通常较小。在往返时间为 300 毫秒的服务器上执行一个包含 100 条语句的操作,不使用管道时,仅网络延迟就需要 30 秒;使用管道时,等待服务器结果的时间可能低至 0.3 秒。 + - 当你的应用需要完成很多小的INSERT, UPDATEDELETE 操作,并且不能方便的转换到集合操作或者 COPY操作时,用管道命令。 - + 如果应用程序需要执行大量小型 INSERTUPDATEDELETE 操作,而这些操作又难以转换为集合操作或 COPY 操作,就可以使用管道命令。 + - 当来自一个操作的信息需要客户端产生下一个操作时,管道模式是没有用的。 - 在这种情况下,客户机将不得不引入一个同步点,并等待完整的客户端/服务器往返以获取它需要的结果。 - 但是,通常可以调整客户端设计以交换服务器端所需的信息。 - 读-修改-写循环是非常好的选择;例如: + 如果客户端必须获得前一个操作的信息,才能生成下一个操作,管道模式就没有帮助。在这种情况下,客户端必须引入同步点,并等待一次完整的客户端与服务器往返,才能获得所需结果。不过,通常可以调整客户端设计,让所需信息在服务器端交换。读取、修改、写入的循环尤其适合这样改进。例如: BEGIN; SELECT x FROM mytable WHERE id = 42 FOR UPDATE; --- result: x=2 --- client adds 1 to x: +-- 结果:x=2 +-- 客户端将 x 加 1: UPDATE mytable SET x = 3 WHERE id = 42; COMMIT; - 可以更有效地开展以下工作: +可以改写为以下效率更高的操作: UPDATE mytable SET x = x + 1 WHERE id = 42; - + - 当单个管道包含多个事务时,管道的作用更小,而且更复杂(参见)。 - + 当单个管道包含多个事务时,使用管道的收益较小,复杂度也更高(见 )。 + @@ -4732,7 +4530,7 @@ UPDATE mytable SET x = x + 1 WHERE id = 42; - 要进入这些模式之一,请在成功调用(或其兄弟函数)后立即调用。这种模式选择只对当前正在执行的查询生效。然后按所述,反复调用直到其返回空指针。如果查询返回了任何行,这些行会作为一个或多个PGresult对象返回。它们看起来与普通查询结果相同,只是状态码在单行模式下为PGRES_SINGLE_TUPLE,在分块模式下为PGRES_TUPLES_CHUNK,而不是PGRES_TUPLES_OK。每个PGRES_SINGLE_TUPLE对象恰好包含一行结果,而PGRES_TUPLES_CHUNK对象至少包含一行、至多包含指定的每块行数。最后一行之后,或者如果查询返回零行,则会返回一个状态为PGRES_TUPLES_OK且不含行的对象,表示不会再有更多行到达。(但请注意,仍然必须继续调用直到其返回空指针。)所有这些PGresult对象都会包含与普通查询结果相同的行描述数据(列名、类型等)。每个对象在使用完之后都应像往常一样通过释放。 + 要进入这些模式之一,请在成功调用(或其同类函数)后立即调用。这种模式选择只对当前正在执行的查询生效。然后按所述,反复调用直到其返回空指针。如果查询返回了任何行,这些行会作为一个或多个PGresult对象返回。它们看起来与普通查询结果相同,只是状态码在单行模式下为PGRES_SINGLE_TUPLE,在分块模式下为PGRES_TUPLES_CHUNK,而不是PGRES_TUPLES_OK。每个PGRES_SINGLE_TUPLE对象恰好包含一行结果,而PGRES_TUPLES_CHUNK对象至少包含一行、至多包含指定的每块行数。最后一行之后,会返回一个状态为PGRES_TUPLES_OK且不含行的对象;如果查询返回零行,则立即返回该对象。这表示不会再有更多行到达。(但请注意,仍然必须继续调用直到其返回空指针。)所有这些PGresult对象都会包含与该查询的普通PGresult对象相同的行描述数据(列名、类型等)。每个对象在使用完之后都应像往常一样通过释放。 @@ -4754,7 +4552,7 @@ int PQsetSingleRowMode(PGconn *conn); - 此函数只能在调用或其某个兄弟函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活单行模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 + 此函数只能在调用或其某个同类函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活单行模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 @@ -4772,7 +4570,7 @@ int PQsetChunkedRowsMode(PGconn *conn, int chunkSize); - 该函数与类似,不同之处在于它指定每个PGresult最多返回chunkSize行,而不一定只返回一行。此函数也只能在调用或其某个兄弟函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活分块模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 + 该函数与类似,不同之处在于它指定每个PGresult最多返回chunkSize行,而不一定只返回一行。此函数也只能在调用或其某个同类函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活分块模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 @@ -4791,10 +4589,10 @@ int PQsetChunkedRowsMode(PGconn *conn, int chunkSize); 取消进行中的查询 - canceling SQL queries + 取消 SQL 查询 - query cancellation + 查询取消 @@ -4812,7 +4610,7 @@ PGcancelConn *PQcancelCreate(PGconn *conn); - 创建一个PGcancelConnPGcancelConn对象,但不会立即通过这条连接发送取消请求。可以使用以阻塞方式发送取消请求,或者使用以非阻塞方式发送。返回值可以传给,以检查该PGcancelConn对象是否成功创建。PGcancelConn是不透明结构体,不应由应用程序直接访问。它可用于以线程安全的方式取消原始连接上正在执行的查询。 + 创建一个PGcancelConnPGcancelConn对象,但不会立即通过这条连接发送取消请求。可以使用以阻塞方式发送取消请求,或者使用以非阻塞方式发送。返回值可以传给,以检查该PGcancelConn对象是否成功创建。PGcancelConn是不透明结构体,不应由应用程序直接访问。这个PGcancelConn对象可用于以线程安全的方式取消原始连接上正在执行的查询。 @@ -4865,7 +4663,7 @@ PostgresPollingStatusType PQcancelPoll(PGcancelConn *cancelConn); - 如果PQcancelStart成功,下一阶段就是轮询libpq,使其继续推进取消连接序列。使用获取底层套接字描述符。(注意:不要假定该套接字在多次调用PQcancelPoll之间保持不变。)循环规则如下:如果PQcancelPoll(cancelConn)上一次返回PGRES_POLLING_READING,就等待该套接字准备好可读(由select()poll()或类似系统函数指示),然后再次调用PQcancelPoll(cancelConn)。反之,如果其上一次返回PGRES_POLLING_WRITING,就等待套接字准备好可写,然后再次调用。第一次迭代时,也就是尚未调用过PQcancelPoll(cancelConn)时,按其上次返回PGRES_POLLING_WRITING来处理。持续这一循环,直到PQcancelPoll(cancelConn)返回PGRES_POLLING_FAILED,表示连接过程失败,或者返回PGRES_POLLING_OK,表示取消请求已成功分派。 + 如果PQcancelStart成功,下一阶段就是轮询libpq,使其继续进行取消连接的建立过程。使用获取数据库连接底层套接字的描述符。(注意:不要假定该套接字在多次调用PQcancelPoll之间保持不变。)循环规则如下:如果PQcancelPoll(cancelConn)上一次返回PGRES_POLLING_READING,就等待该套接字准备好可读(由select()poll()或类似系统函数指示),然后再次调用PQcancelPoll(cancelConn)。反之,如果PQcancelPoll(cancelConn)上一次返回PGRES_POLLING_WRITING,就等待套接字准备好可写,然后再次调用PQcancelPoll(cancelConn)。第一次迭代时,也就是尚未调用过PQcancelPoll(cancelConn)时,按其上次返回PGRES_POLLING_WRITING来处理。持续这一循环,直到PQcancelPoll(cancelConn)返回PGRES_POLLING_FAILED,表示连接过程失败,或者返回PGRES_POLLING_OK,表示取消请求已成功分派。 @@ -4931,7 +4729,7 @@ PostgresPollingStatusType PQcancelPoll(PGcancelConn *cancelConn); - 请注意,尽管这些常量会继续保留(为了保持兼容性),应用程序也绝不应依赖它们按某个特定顺序出现,甚至不应依赖它们一定会出现,或者依赖状态值始终属于这些已记录的取值之一。应用程序可以这样写: + 请注意,尽管这些常量会继续保留(为了保持兼容性),应用程序也绝不应依赖它们按某个特定顺序出现,甚至不应依赖它们一定会出现,或者依赖状态值始终属于本节列出的取值之一。应用程序可以这样写: switch(PQcancelStatus(conn)) { @@ -5002,7 +4800,7 @@ int PQcancelSocket(const PGcancelConn *cancelConn); PQcancelErrorMessagePQcancelErrorMessage - error messagein PGcancelConn + 错误消息PGcancelConn @@ -5061,8 +4859,8 @@ void PQcancelReset(PGcancelConn *cancelConn); 发送取消请求的过时函数 - 这些函数代表较旧的取消请求发送方式。虽然它们仍然可以工作,但由于即使原始连接通过sslmodegssencmode要求加密,它们发送取消请求时也不会以加密方式进行,因此已被废弃。因此,强烈不建议在新代码中继续使用这些旧方法,已有代码也建议迁移到新的函数。 - + 这些函数使用较旧的方式发送取消请求。即使原始连接通过 sslmodegssencmode 要求加密,它们也不会加密取消请求,因此虽然仍可使用,却已被弃用。强烈不建议在新代码中使用这些旧方法,也建议将现有代码改为使用新函数。 + @@ -5158,7 +4956,7 @@ int PQrequestCancel(PGconn *conn); 快速路径接口 - fast path + 快速路径 @@ -5168,8 +4966,8 @@ int PQrequestCancel(PGconn *conn); - 这个接口不安全,不应使用。当result_is_int被设置为0时,PQfn可能会在result_buf末尾之外写入数据,而不管缓冲区是否有足够空间容纳所请求的字节数。此外,它已经废弃,因为可以通过创建一个定义该函数调用的预备语句来达到类似的性能并获得更强大的功能。然后,用参数和结果的二进制传输执行该语句,从而取代快速路径函数调用。 - + 此接口不安全,不应使用。当 result_is_int 设为 0 时,PQfn 可能越过 result_buf 的末尾写入数据,无论缓冲区是否有足够空间容纳请求的字节数。此外,此接口已经过时:可以通过创建预备语句来定义函数调用,获得相近的性能和更强的功能;再以二进制形式传输参数和结果来执行该语句,即可替代快速路径函数调用。 + @@ -5197,27 +4995,24 @@ typedef struct - fnid参数是要被执行的函数的 OID。argsnargs定义了要传递给函数的参数;它们必须匹配已声明的函数参数列表。当一个参数结构体的isint域为真时,u.integer值被以指定长度(必须是 1、2 或者 4 字节)整数的形式发送给服务器;这时候会发生恰当的字节交换。当isint为假时,*u.ptr中指定数量的字节将不做任何处理被发送出去;这些数据必须是服务器 预期的用于该函数参数数据类型的二进制传输的格式(由于历史原因u.ptr被声明为类型int *,其实把它考虑成void *会更好)。result_buf是放置该函数返回值的缓冲区。调用者必须已经分配了足够的空间来存储返回值(这里没有检查!)。实际的结果长度将被放在result_len指向的整数中返回。如果预期结果是 2 或 4 字节整数,把result_is_int设为 1;否则设为 0。把result_is_int设为 1 导致libpq在必要时对值进行交换字节,这样它就作为对客户端机器正确的int值被传输,注意对任一种允许的结果大小都会传递一个 4 字节到*result_buf。当result_is_int是 0 时,服务器发送的二进制格式字节将不做修改直接返回(在这种情况下,把result_buf考虑为类型void *更好)。 - + fnid 参数是要执行函数的 OID。argsnargs 指定传给函数的参数,必须与函数声明中的参数列表匹配。参数结构体的 isint 字段为真时,u.integer 值会以指定长度的整数发送到服务器,该长度必须是 2 或 4 字节,并会进行适当的字节序转换。isint 为假时,位于 *u.ptr 的指定数量字节会原样发送;数据必须符合服务器对该函数参数数据类型的二进制传输格式要求。(将 u.ptr 声明为 int * 是历史原因;将其视为 void * 更合适。)result_buf 指向用于存放函数返回值的缓冲区。调用者必须事先分配足够空间来保存返回值,这里不会检查!实际结果长度以字节为单位,返回到 result_len 指向的整数中。如果预期结果是 2 或 4 字节整数,将 result_is_int 设为 1,否则设为 0。将 result_is_int 设为 1 后,libpq 会按需转换字节序,使结果成为适合客户端机器的 int 值;注意,无论是哪种允许的结果大小,传入 *result_buf 的都是 4 字节整数。result_is_int 为 0 时,服务器发送的二进制格式字节串会原样返回。(此时,将 result_buf 视为 void * 更合适。) + - PQfn总是返回一个有效的PGresult指针,包括状态PGRES_COMMAND_OK 表示成功或者PGRES_FATAL_ERROR在出现什么问题时。 - 在使用结果之前应该检查结果状态。 - 当结果不再使用后,调用者有义务使用释放PGresult。 - + PQfn 总是返回有效的 PGresult 指针:成功时状态为 PGRES_COMMAND_OK,遇到问题时为 PGRES_FATAL_ERROR。使用结果前应检查其状态。不再需要结果时,调用者负责使用 释放 PGresult。 + - 要传递NULL参数到函数,将参数结构体的len字段设置为-1isintu 字段就不相关了。 - + 要向函数传入 NULL 参数,将该参数结构体的 len 字段设为 -1;此时,isintu 字段便不再相关。 + - 如果函数返回 NULL, *result_len 被设置为 -1, 并且 *result_buf 不调整。 - + 如果函数返回 NULL,则将 *result_len 设为 -1,而不修改 *result_buf。 + - 注意在使用此接口时,不能够处理集-值结果。 - 此外,函数必须是一个普通函数,而不是聚合、窗口函数或过程。 - + 注意,使用此接口时无法处理集合值结果。此外,函数必须是普通函数,不能是聚合函数、窗口函数或过程。 + @@ -5227,7 +5022,7 @@ typedef struct NOTIFY - in libpq + 在 libpq 中 @@ -5236,39 +5031,36 @@ typedef struct libpq应用把LISTENUNLISTENNOTIFY命令作为普通 SQL 命令提交。 - 随后通过调用PQnotifies.PQnotifies来检测NOTIFY消息的到达。 + 随后通过调用PQnotifiesPQnotifies来检测NOTIFY消息的到达。 - 函数PQnotifies从服务器发来的未处理通知消息列表中返回下一条通知。如果没有待处理通知,则返回空指针。一旦PQnotifies返回一条通知,该通知就被视为已处理,并会从通知列表中删除。 - + 函数 PQnotifies 从已收到但尚未处理的服务器通知消息列表中返回下一条通知。没有待处理通知时返回空指针。一旦 PQnotifies 返回一条通知,该通知就被视为已处理,并从通知列表中移除。 PGnotify *PQnotifies(PGconn *conn); typedef struct pgNotify { - char *relname; /* notification channel name */ - int be_pid; /* process ID of notifying server process */ - char *extra; /* notification payload string */ + char *relname; /* 通知通道名称 */ + int be_pid; /* 发送通知的服务器进程 ID */ + char *extra; /* 通知载荷字符串 */ } PGnotify; - - 在处理完PQnotifies返回的PGnotify对象后,别忘了用把它释放。 - 释放PGnotify指针本身就足够了;relnameextra域并不表示独立分配的内存(这些域名是历史遗留的,尤其是通道名称与关系名称并无关联)。 - +处理完 PQnotifies 返回的 PGnotify 对象后,务必使用 释放它。只需释放 PGnotify 指针;relnameextra 字段并非独立分配。(这些字段名称是历史遗留的;尤其是,通道名称与关系名称不必有任何关联。) + 给出了一个示例程序展示异步通知的使用。 - PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数吸收的消息。 + PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数读取的消息。 在较早版本的libpq中,及时收到NOTIFY消息的唯一方法是不断提交命令,哪怕是空命令,然后在每次后检查PQnotifies。 - 虽然这种方法仍然有效,但由于效率过低,现已废弃。 + 虽然这种方法仍然有效,但由于浪费处理能力,现已弃用。 - 当你没有可用的命令提交时,一种更好的检查NOTIFY消息的方法是调用,然后检查PQnotifies。 + 当没有需要执行的实际命令时,一种更好的检查NOTIFY消息的方法是调用,然后检查PQnotifies。 你可以使用select()等待服务器数据到达,这样在无事可做时就不会浪费CPU资源(参见以获得可传给select()的文件描述符)。 注意不管是用/提交命令还是简单地使用,这种方法都能正常工作。 不过,你应该记住在每次之后检查PQnotifies,看看在命令的处理过程中是否有通知到达。 @@ -5282,20 +5074,16 @@ typedef struct pgNotify COPY - with libpq + 使用 libpq - PostgreSQL中的COPY命令有用于libpq的对网络连接读出或者写入的选项。这一节描述的函数允许应用通过提供或者消耗已拷贝的数据来充分利用这个功能。 - + PostgreSQLCOPY 命令提供了选项,可以通过 libpq 使用的网络连接读取或写入数据。本节介绍的函数允许应用程序通过提供或接收复制数据来使用这一能力。 + - 整个处理是应用首先通过或者一个等效的函数发出 SQL COPY命令。 - 对这个命令的响应(如果命令无误)将是一个状态代码是PGRES_COPY_OUT或 者PGRES_COPY_IN(取决于指定的拷贝方向)的PGresult对象。 - 应用然后就应该使用这一节的函数接收或者传送数据行。在数据传输结束之后,另外一个PGresult对象会被返回以表明传输的成功或者失败。 - 它的状态将是:PGRES_COMMAND_OK表示成功,PGRES_FATAL_ERROR表示发生了一些问题。 - 此时我们可以通过发出进一步的 SQL 命令(在COPY操作的处理过程中,不能用同一个连接执行其它 SQL 命令)。 - + 整体流程如下:应用程序先通过 或等效函数发出 SQL COPY 命令。如果命令没有错误,响应就是一个 PGresult 对象,其状态码为 PGRES_COPY_OUTPGRES_COPY_IN,取决于指定的复制方向。应用程序随后应使用本节函数接收或发送数据行。数据传输完成后,会返回另一个 PGresult 对象,表示传输成功或失败:成功时状态为 PGRES_COMMAND_OK,出现问题时为 PGRES_FATAL_ERROR。此时可以通过 继续发出 SQL 命令。(COPY 操作进行期间,不能在同一连接上执行其他 SQL 命令。) + 如果一个COPY命令是通过在一个可能包含额外命令的字符串中发出的,那么应用在完成COPY序列之后必须继续用取得结果。 @@ -5303,17 +5091,15 @@ typedef struct pgNotify - 这一节的函数应该只在从获得了PGRES_COPY_OUTPGRES_COPY_IN结果状态的后执行。 - + 只有从 获得 PGRES_COPY_OUTPGRES_COPY_IN 结果状态后,才应调用本节函数。 + - 一个PGresult对象具有这些状态值之一,携带有关COPY操作开始的一些附加数据。 - 可以使用与查询结果相关的函数来获取这些附加数据: - - + 带有上述某个状态值的 PGresult 对象,还会携带关于即将开始的 COPY 操作的附加数据。这些数据可以通过下列函数获取,这些函数也用于查询结果: + PQnfieldsPQnfieldswith COPY + >PQnfields用于 COPY @@ -5324,7 +5110,7 @@ typedef struct pgNotify PQbinaryTuplesPQbinaryTupleswith COPY + >PQbinaryTuples用于 COPY @@ -5336,7 +5122,7 @@ typedef struct pgNotify PQfformatPQfformatwith COPY + >PQfformat用于 COPY @@ -5348,15 +5134,15 @@ typedef struct pgNotify - + 用于发送<command>COPY</command>数据的函数 - 这些函数用于在COPY FROM STDIN期间发送数据。如果在连接不是COPY_IN状态,调用它们会失败。 - + 这些函数用于在 COPY FROM STDIN 期间发送数据。如果连接不处于 COPY_IN 状态,调用它们会失败。 + @@ -5375,12 +5161,11 @@ int PQputCopyData(PGconn *conn, - 传输指定buffer中长度为nbytesCOPY数据到服务器。 - 如果数据被放在队列中,结果是 1;如果因为缓冲区满而无法被放在队列中(只可能发生在连接是非阻塞模式时),那么结果是零;如果发生错误,结果为 -1(如果返回值为 -1,那么使用检索细节。如果值是零,那么等待写准备好然后重试)。 + 将指定 buffer 中长度为 nbytesCOPY 数据传输到服务器。数据成功加入队列时返回 1;因缓冲区已满而无法加入队列时返回零(仅可能发生在非阻塞模式下);发生错误时返回 -1。(返回 -1 时,可用 获取详细信息。返回零时,应等待可写就绪后重试。) - 应用可以把COPY数据流划分成任意方便的大小放到缓冲区中。在发送时,缓冲区载荷的边界没有什么语意。数据流的内容必须匹配COPY命令预期的数据格式;详见。 + 应用程序可以将 COPY 数据流分成任意方便大小的数据块,逐块装入缓冲区。发送时,这些数据块的边界没有语义含义。数据流内容必须符合 COPY 命令预期的数据格式;详见 @@ -5400,21 +5185,15 @@ int PQputCopyEnd(PGconn *conn, - 如果errormsgNULL,则成功结束COPY_IN操作。 - 如果errormsg不是NULLCOPY被强制失败,errormsg指向的字符串是错误消息。 - (不过,我们不应假定这个准确的错误信息将会从服务器传回,因为服务器可能已经因为其自身原因导致COPY失败。)。 + 如果 errormsgNULL,则成功结束 COPY_IN 操作。如果 errormsg 不为 NULL,则强制 COPY 失败,并将 errormsg 指向的字符串用作错误消息。(但不应假定服务器一定会返回这条完全相同的错误消息,因为服务器可能已经因自身原因使 COPY 失败。) - 如果终止消息被发送,则结果为 1;在非阻塞模式中,结果为 1 也可能只表示终止消息被成功地放在了发送队列中 - (在非阻塞模式中,要确认数据确实被发送出去,你应该接着等待写准备好并且调用,重复这些直到返回零)。 - 零表示该函数由于缓冲区满而无法将该终止消息放在队列中,这只会发生在非阻塞模式中(在这种情况下,等待写准备好并且再次尝试调用)。 - 如果发生系统错误,则返回 -1,可以使用检索详情。 + 终止消息已发送时返回 1;在非阻塞模式下,返回 1 也可能仅表示该消息已成功加入发送队列。(在非阻塞模式下,要确认数据已经发送,应接着等待可写就绪并调用 ,反复执行直到返回零。)返回零表示缓冲区已满,无法将终止消息加入队列;这种情况仅可能发生在非阻塞模式下。(此时,应等待可写就绪,再次调用 。)发生严重错误时返回 -1,可用 获取详细信息。 - 在成功调用之后,调用获取COPY命令的最终结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 成功调用 后,调用 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -5447,29 +5226,19 @@ int PQgetCopyData(PGconn *conn, - 在一个COPY期间尝试从服务器获取另外一行数据。数据总是以每次一个数据行的方式被返回;如果只有一个部分行可用,那么它不会被返回。 - 成功返回一个数据行涉及到分配一块内存来保存该数据。buffer参数必须为非NULL。 - *buffer被设置为指向分配到的内存的指针,或者是在没有返回缓冲区的情况下指向NULL。 - 一个非NULL的结果缓冲区在不需要时必须用释放。 + 在 COPY 期间尝试从服务器获取下一行数据。每次总是返回一个完整数据行;如果只有部分行可用,则不返回。成功返回数据行时,会分配一块内存保存数据。buffer 参数必须为非 NULL*buffer 会被设置为指向所分配的内存;如果没有返回缓冲区,则设为 NULL。非 NULL 的结果缓冲区在不再需要时应使用 释放。 - 在成功返回一行之后,返回的值就是该数据行里数据的字节数(将是大于零)。 - 被返回的字符串总是空终止的,虽然这可能只是对文本COPY有用。 - 一个零结果表示该COPY仍然在处理中,但是还没有可用的行(只在async为真时才可能)。 - 一个 -1 结果表示COPY已经完成。-2 结果表示发生了错误(参考获取原因)。 + 成功返回一行时,返回值是该行的数据字节数,始终大于零。返回的字符串总是以零字节结尾,不过这可能仅对文本 COPY 有用。返回零表示 COPY 仍在进行,但尚无可用行(仅在 async 为真时可能发生)。返回 -1 表示 COPY 已完成;返回 -2 表示发生了错误(可用 查看原因)。 - 当async为真时(非零),将不会阻塞等待输入; - 如果COPY仍在处理过程中并且没有可用的完整行,那么它将返回零 - (在这种情况下等待读准备好,然后在再次调用之前,调用)。 - 当async为假(零)时,将阻塞,直到数据可用或者操作完成。 + 当 async 为真(非零)时, 不会阻塞等待输入;如果 COPY 仍在进行,但没有完整行可用,则返回零。(此时,应等待读就绪,先调用 ,再调用 。)当 async 为假(零)时, 会阻塞,直到数据可用或操作完成。 - 在返回 -1 之后,调用获取COPY命令的最后结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 在 返回 -1 后,调用 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -5479,11 +5248,11 @@ int PQgetCopyData(PGconn *conn, - 用于<command>COPY</command>的废弃函数 + 用于<command>COPY</command>的过时函数 - 这些函数代表了以前的处理COPY的方法。尽管它们还能用,但是现在已经被废弃,因为它们的错误处理很糟糕、检测结束数据的方法也不方便,并且缺少对二进制或非阻塞传输的支持。 - + 这些函数使用较旧的方式处理 COPY。虽然仍然可用,但由于错误处理欠佳、检测数据结束的方式不便,而且缺少对二进制或非阻塞传输的支持,已被弃用。 + @@ -5493,7 +5262,7 @@ int PQgetCopyData(PGconn *conn, - 读取一个以新行终止的字符行到(由服务器传输) 到一个长度为length的字符串缓冲区。 + 将服务器传来的、以换行符结尾的一行字符读入大小为 length 的字符串缓冲区。 int PQgetline(PGconn *conn, char *buffer, @@ -5502,12 +5271,11 @@ int PQgetline(PGconn *conn, - 这个函数拷贝最多length-1 个字符到该缓冲区中,并且把终止的新行转换成一个零字节。 - 在输入结束时返回EOF,如果整行都被读取则返回 0,如果缓冲区填满了而还没有遇到结束的新行则返回 1。 - + 此函数最多将 length-1 个字符复制到缓冲区,并将末尾的换行符转换为零字节。 在输入结束时返回 EOF,读完一整行时返回 0,缓冲区已满但尚未读到末尾换行符时返回 1。 + - 注意,应用必须检查是否一个新行包含两个字符\.,这表明服务器 已经完成了COPY命令的结果发送。如果应用可能收到超过length-1 字符长的行, 我们就应该确保正确识别\.行(例如,不要把一个长数据行的结束当作一个终止行)。 + 注意,应用程序必须检查新读入的一行是否仅由 \. 两个字符组成,这表示服务器已发送完 COPY 命令的结果。如果可能收到长度超过 length-1 个字符的行,必须确保正确识别 \. 行,例如不能把长数据行的末尾误当作终止行。 @@ -5519,7 +5287,7 @@ int PQgetline(PGconn *conn, - 不阻塞地读取一行COPY数据(由服务器传输)到一个缓冲区中。 + 以非阻塞方式将服务器传来的一行 COPY 数据读入缓冲区。 int PQgetlineAsync(PGconn *conn, char *buffer, @@ -5528,23 +5296,19 @@ int PQgetlineAsync(PGconn *conn, - 这个函数类似于,但是可以被用于那些必须异步读取COPY数据的应用, 也就是不阻塞的应用。 - 在发出了COPY命令并得到了PGRES_COPY_OUT响应之后, - 应用应该调用直到检测到结束数据的信号。 - + 此函数类似于 ,但可用于必须异步读取 COPY 数据的应用程序,即读取时不阻塞。发出 COPY 命令并收到 PGRES_COPY_OUT 响应后,应用程序应调用 ,直到检测到数据结束信号。 + - 不像,这个函数负责检测结束数据。 + 与 不同,此函数会负责检测数据结束。 - 在每次调用时,如果libpq的输入缓冲区中有一个完整的数据行可用,都将返回数据。 - 否则,在剩余行到达之前不会返回数据。如果识别到拷贝数据结束的标志,此函数返回 -1;如果没有可用数据则返回 0; - 或者是给出一个正数给出被返回的字节数。如果返回 -1,调用者下一步必须调用,然后回到正常处理。 + 每次调用时,如果 libpq 的输入缓冲区中有完整数据行, 就会返回数据;否则,要等该行剩余部分到达后才返回数据。识别到复制数据结束标记时返回 -1,没有可用数据时返回 0,否则返回正数,表示返回的数据字节数。返回 -1 后,调用者必须接着调用 ,然后恢复正常处理。 - 返回的数据将不超过一个数据行的范围。如果可能,每次将返回一个完整行。但如果调用者提供的缓冲区太小不足以容下服务器发送的行,那么将返回部分行。对于文本数据,这可以通过测试返回的最后一个字节是否\n来检测(在二进制COPY中, 需要对COPY数据格式进行实际的分析,以便做相同的判断)。被返回的字符串不是空结尾的(如果你想增加一个终止空,确保传递一个比实际可用空间少一字节的bufsize)。 + 返回的数据不会跨越数据行边界。只要可能,每次就返回一整行;但如果调用者提供的缓冲区太小,容不下服务器发送的一行,则只返回部分行。对于文本数据,可检查最后返回的字节是否为 \n,以判断是否返回了完整行。(对于二进制 COPY,则必须实际解析 COPY 数据格式才能作出相同判断。)返回的字符串不以零字节结尾。(如果要自行添加末尾的零字节,务必将传入的 bufsize 设置为比实际可用空间少一字节。) @@ -5556,7 +5320,7 @@ int PQgetlineAsync(PGconn *conn, - 向服务器发送一个空终止的字符串。如果 OK 则返回 0;如果不能发送字符串则返回EOF。 + 向服务器发送以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputline(PGconn *conn, const char *string); @@ -5564,17 +5328,14 @@ int PQputline(PGconn *conn, - 一系列调用发送的COPY数据流和返回的数据具有相同的格式, - 只是应用不需要每次调用中发送刚好一个数据行;在每次调用中发送多行或者部分行都是可以的。 + 连续调用 发送的 COPY 数据流,与 返回的数据格式相同。不过,应用程序不必在每次 调用中恰好发送一个数据行;每次发送部分行或多行也可以。 - 在PostgreSQL协议 3.0 之前,应用必须显式地发送两个字符\.作为最后一行来指示服务器已经完成发送COPY数据。 - 虽然这么做仍然有效,但是它已经被废弃并且\.的特殊含义可能在将来的版本中删除。 - 在发送完实际数据之后, 调用就足够了。 - + 在 PostgreSQL 协议 3.0 之前,应用程序必须显式发送由 \. 两个字符组成的最后一行,告知服务器应用程序已发送完 COPY 数据。虽然这种方式仍然有效,但已被弃用,\. 的特殊含义预计会在未来版本中移除。发送完实际数据后,调用 即可。 + @@ -5586,7 +5347,7 @@ int PQputline(PGconn *conn, - 向服务器发送一个非空终止的字符串。如果 OK 则返回 0,如果不能发送字符串则返回EOF。 + 向服务器发送不以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputnbytes(PGconn *conn, const char *buffer, @@ -5595,7 +5356,7 @@ int PQputnbytes(PGconn *conn, - 这个函数类似,除了数据缓冲区不需要是空终止,因为要发送的字节数是直接指定的。在发送二进制数据时使用这个过程。 + 此函数与 完全相同,只是直接指定了要发送的字节数,因此数据缓冲区不必以零字节结尾。发送二进制数据时可使用此函数。 @@ -5611,15 +5372,11 @@ int PQputnbytes(PGconn *conn, int PQendcopy(PGconn *conn); - 这个函数等待服务器完成拷贝。当最后一个字符串已经用发送给服务器时或者当最后一个字符串已经用PQgetline从服务器接收到时,就会发出这个函数。 - 这个函数必须被发出,否则服务器将会和客户端不同步。从这个函数返回后,服务器就已经准备好接收下一个 SQL 命令了。函数成功完成时返回值为 0,否则返回非零值(如果返回值为非零值,用检索详情)。 +此函数会等待服务器完成复制。应在使用 向服务器发送最后一个字符串后,或使用 PQgetline 从服务器接收最后一个字符串后调用它。必须调用此函数,否则服务器与客户端会失去同步。函数返回后,服务器便准备好接收下一条 SQL 命令。成功完成时返回 0,否则返回非零值。(返回非零值时,可用 获取详细信息。) - 在使用时,应用应该通过反复调用并且在看到终止行后调用来响应PGRES_COPY_OUT结果。 - 然后它应该返回到循环直到返回一个空指针。 - 类似地,PGRES_COPY_IN结果会用一系列加上之后的来处理,然后返 回到循环。 - 这样的安排将保证嵌入到一系列SQL命令中的COPY命令将被正确执行。 + 使用 时,收到 PGRES_COPY_OUT 结果后,应用程序应反复调用 ,并在看到终止行后调用 。随后应回到 循环,直到 返回空指针。类似地,收到 PGRES_COPY_IN 结果后,应连续调用 ,再调用 ,然后回到 循环。这样可以保证嵌在一系列 SQL 命令中的 COPY 命令正确执行。 @@ -5639,8 +5396,8 @@ int PQendcopy(PGconn *conn); 控制函数 - 这些函数控制libpq行为各种各样的细节。 - + 这些函数控制 libpq 行为的各种细节。 + @@ -5650,17 +5407,15 @@ int PQendcopy(PGconn *conn); - 返回客户端编码。 + 返回客户端编码。 int PQclientEncoding(const PGconn *conn); - - 请注意,它返回的是编码 ID,而不是一个符号串字符串,如EUC_JP。如果不成功,它会返回 -1。要把一个编码 ID 转换为为一个编码名称,可以用: - +注意,返回的是编码 ID,而不是 EUC_JP 这样的符号字符串。失败时返回 -1。要将编码 ID 转换为编码名称,可以使用: char *pg_encoding_to_char(int encoding_id); - + @@ -5670,14 +5425,11 @@ char *pg_encoding_to_char(int encoding_id); - - 设置客户端编码。 - + 设置客户端编码。 int PQsetClientEncoding(PGconn *conn, const char *encoding); - conn是一个到服务器的连接,而encoding是你想使用的编码。 - 如果函数成功地设置编码,则返回 0,否则返回 -1。这个连接的当前编码可以使用确定。 + conn是到服务器的连接,而encoding是要使用的编码。如果成功设置编码,函数返回 0,否则返回 -1。此连接的当前编码可以通过以下函数确定: @@ -5689,7 +5441,7 @@ int PQsetClientEncoding(PGconn *conn, const char * - 决定返回的消息的细节程度。 + 设置 所返回消息的详细程度。 typedef enum { @@ -5701,19 +5453,12 @@ typedef enum PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); - - 设置细节模式,并返回该连接的前一个设置。 - 在TERSE模式下,返回的消息只包括严重性、主要文本以及位置;这些东西通常放在一个单一行中。 - DEFAULT模式生成的消息包括上面的信息加上任何细节、提示或者上下文域(这些可能跨越多行)。 - VERBOSE模式包括所有可以可用的域。修改细节模式不会影响来自已有PGresult对象中的可用消息。 - 只有随后创建的PGresult对象才受到影响。 - SQLSTATE模式仅包括错误严重性和SQLSTATE错误代码,如果其中之一是可用的(如果没有,输出类似于TERSE模式)。 - + 设置详细程度模式,并返回该连接先前的设置。在 TERSE 模式下,返回的消息只包含严重级别、主要文本和位置;通常一行就能容纳。DEFAULT 模式生成的消息除上述内容外,还包含所有详细信息、提示或上下文字段(这些内容可能跨越多行)。VERBOSE 模式包含所有可用字段。SQLSTATE 模式仅包含错误严重级别,以及可用时的 SQLSTATE 错误代码(如果没有错误代码,则输出与 TERSE 模式相同)。 + - 更改详细程度设置不会影响已存在的PGresult对象的可用的消息,只会影响随后创建的对象。 - (如果想要用不同的详细程度打印之前的错误,请见 ) - + 更改详细程度设置不会影响从既有 PGresult 对象中取得的消息,只影响随后创建的对象。(如果希望以不同的详细程度打印之前的错误,请参见 。) + @@ -5724,7 +5469,7 @@ PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); - 决定如何处理返回的消息中的CONTEXT域。 + 确定 所返回消息中 CONTEXT 字段的处理方式。 typedef enum { @@ -5735,18 +5480,12 @@ typedef enum PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibility show_context); - - 设置上下文显示模式,返回该连接上之前的设置。 - 这个模式控制消息中是否包括CONTEXT域。 - NEVER模式不会包括CONTEXT,而ALWAYS则尽可能地包括这个域。 - 在ERRORS模式(默认)中,只在错误消息中包括CONTEXT域,而在通知和警告消息中不会包括。 - (但是,如果详细程度设置为 TERSESQLSTATE,则无论上下文显示模式如何,都会省略CONTEXT字段。) - + 设置上下文显示模式,并返回连接先前的设置。此模式控制消息中是否包含 CONTEXT 字段。NEVER 模式从不包含 CONTEXT,而 ALWAYS 模式在该字段可用时总是包含它。在 ERRORS 模式(默认)下,CONTEXT 字段只包含在错误消息中,不包含在通知和警告中。(不过,如果详细程度设置为 TERSESQLSTATE,则无论上下文显示模式如何,都会省略 CONTEXT 字段。) + - 更改这个模式不会影响从已经存在的PGresult对象项中得到的消息,只会影响后续创建的PGresult对象 - (如果想要用不同的详细程度打印之前的错误,请见)。 - + 更改此模式不会影响从既有 PGresult 对象中取得的消息,只影响随后创建的对象。(如果希望使用不同的显示模式打印之前的错误,请参见 。) + @@ -5757,25 +5496,20 @@ PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibilit - 启用对客户端/服务器通讯的跟踪,把跟踪信息输出到一个调试文件流中。 + 启用客户端/服务器通信跟踪,将跟踪信息写入调试文件流。 void PQtrace(PGconn *conn, FILE *stream); - + - 每行包括:一个可选的时间戳,一个方向指示器(F表示从客户端到服务器的消息或B表示从服务器到客户端的消息),消息长度、消息类型、和消息内容。 - 非消息内容字段(时间戳、方向、长度和消息类型)由一个制表符分隔。 - 消息内容用空格分隔。 - 协议字符串用双引号括起来,而用作数据值的字符串用单引号括起来。 - 不可打印的字符被打印为十六进制转义。 - 更多消息-类型-特定的详情可以在中发现。 - + 每行包含可选的时间戳、方向指示符(F 表示客户端发往服务器的消息,B 表示服务器发往客户端的消息)、消息长度、消息类型和消息内容。消息内容之外的字段(时间戳、方向、长度和消息类型)以制表符分隔。消息内容以空格分隔。协议字符串用双引号括起,用作数据值的字符串用单引号括起。不可打印字符以十六进制转义形式输出。各消息类型的进一步说明见 。 + - 在 Windows上,如果libpq库和应用使用了不同的标志编译,那么这个函数调用会导致应用崩溃,因为FILE指针的内部表达是不一样的。特别是多线程/单线程、发布/调试 以及静态/动态标志应该是库和所有使用库的应用都一致。 + 在 Windows 上,如果 libpq 库与应用程序使用不同的标志编译,调用此函数会导致应用程序崩溃,因为 FILE 指针的内部表示不同。具体而言,库与所有使用它的应用程序都应使用相同的多线程/单线程、发布/调试和静态/动态标志。 @@ -5796,11 +5530,8 @@ void PQsetTraceFlags(PGconn *conn, int flags); - flags包含描述跟踪的操作模式的标志位。 - 如果flags包含PQTRACE_SUPPRESS_TIMESTAMPS,则在打印每条消息时不包括时间戳。 - 如果flags包含PQTRACE_REGRESS_MODE,那么在打印每个消息时将修改一些字段,例如对象OIDs,以使输出在测试框架中更方便地使用。 - 这个函数必须在调用PQtrace之后调用。 - + flags 包含描述跟踪工作模式的标志位。如果 flags 包含 PQTRACE_SUPPRESS_TIMESTAMPS,则打印每条消息时不包含时间戳。如果 flags 包含 PQTRACE_REGRESS_MODE,则打印每条消息时会隐去某些字段,例如对象 OID,以便在测试框架中使用输出。必须在调用 PQtrace 之后调用此函数。 + @@ -5812,11 +5543,11 @@ void PQsetTraceFlags(PGconn *conn, int flags); - 禁用打开的跟踪。 + 禁用由 启动的跟踪。 void PQuntrace(PGconn *conn); - + @@ -5846,11 +5577,8 @@ void PQfreemem(void *ptr); - 释放libpq分配的内存,尤其是,,,和PQnotifies分配的内存。 - 特别重要的是,在微软 Windows 上使用这个函数,而不是free()。 - 这是因为只有 DLL 和应用的当多线程/单线程、发布/调试以及静态/动态标志相同时,才能在一个 DLL 中分配内存并且在应用中释放它。 - 在非微软 Windows 平台上,这个函数与标准库函数free()相同。 - + 释放 libpq 分配的内存,特别是 PQnotifies 分配的内存。在 Microsoft Windows 上,务必使用此函数,而不是 free()。这是因为只有 DLL 与应用程序使用相同的多线程/单线程、发布/调试和静态/动态标志,才能在 DLL 中分配内存并在应用程序中释放它。在 Microsoft Windows 以外的平台上,此函数与标准库函数 free() 相同。 + @@ -5861,15 +5589,16 @@ void PQfreemem(void *ptr); - 释放分配的数据结构。 + 释放 分配的数据结构。 void PQconninfoFree(PQconninfoOption *connOptions); - +如果参数为 NULL 指针,则不执行任何操作。 + - 一个简单的不会做这些,因为数组包含对子字符串的引用。 - + 仅调用 不足以完成此项释放,因为数组还包含指向附属字符串的引用。 + @@ -5893,8 +5622,8 @@ char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, 当前支持的算法是md5scram-sha-256onoff也被接受作为md5的别名,用于与较老的服务器版本兼容)。 注意,对scram-sha-256支持是在PostgreSQL版本10中引入的,并且在老的服务器版本上无法工作。 如果algorithmNULL,这个函数将向服务器查询设置的当前值。 - 这种行为可能会阻塞当前事务,并且当前事务被中止或者连接正忙于执行另一个查询时会失败。 - 如果希望为服务器使用默认的算法但避免阻塞,应在调用之前查询你自己的password_encryption,并且将该值作为algorithm传入。 + 这一查询可能阻塞,并且当前事务被中止或者连接正忙于执行另一个查询时会失败。 + 如果希望为服务器使用默认的算法但避免阻塞,应在调用之前自行查询password_encryption,并且将该值作为algorithm传入。 @@ -5960,8 +5689,8 @@ PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); 这是libpq内部用于分配并初始化一个空PGresult对象的函数。 如果无法分配内存,此函数返回NULL。 将它导出供外部调用,是因为一些应用需要自行生成结果对象,特别是带有错误状态的对象。 - 如果conn非空,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 - 此外,如果conn非空,连接中注册的所有事件过程也会被复制到PGresult中。 + 如果conn 不为 null,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 + 此外,如果conn 不为 null,连接中注册的所有事件过程也会被复制到PGresult中。 (这些过程不会收到PGEVT_RESULTCREATE调用,但可参见。) 注意,最终应对该对象调用,就像处理libpq自身返回的PGresult一样。 @@ -5982,16 +5711,16 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); - conn参数被传送给事件过程,但不会被直接使用。如果事件过程不使用它,则会返回NULL。 - + conn 参数会传递给事件过程,但此函数不会直接使用它。如果事件过程不使用此参数,则可以传入 NULL。 + 已经接收到这个对象的PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件过程不会被再次触发。 - 这个函数与分开的主要原因是在调用事件过程之前创建一个PGresult并且填充它常常是合适的。 - + 此函数与 分开的主要原因是,通常适合先创建 PGresult 并填充数据,然后再调用事件过程。 + @@ -6002,13 +5731,11 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); - 为一个PGresult对象创建一个拷贝。 - 这个拷贝不会以任何方式链接到源结果,并且当该拷贝不再需要时,必须调用进行清理。如果函数失败,返回NULL。 - + 创建 PGresult 对象的副本。副本与源结果没有任何关联,不再需要副本时必须调用 。函数失败时返回 NULL PGresult *PQcopyResult(const PGresult *src, int flags); - + 这不是为了制作一个精确的副本。返回的结果总是放在PGRES_TUPLES_OK状态中,并且不复制源中的任何错误消息。 @@ -6017,7 +5744,7 @@ PGresult *PQcopyResult(const PGresult *src, int flags); PG_COPYRES_TUPLES指定复制源结果的元组。(这也意味着复制属性。) PG_COPYRES_NOTICEHOOKS指定复制源结果的通知钩子。 PG_COPYRES_EVENTS指定复制源结果的事件。(但不复制与源相关的任何实例数据。) - 事件程序接收PGEVT_RESULTCOPY事件。 + 事件过程会收到 PGEVT_RESULTCOPY 事件。 @@ -6048,18 +5775,15 @@ int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs); - 设置一个PGresult对象的一个元组域值。 + 设置 PGresult 对象中某个元组的字段值。 int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len); - + - 这个函数将自动按需增加结果的内部元组数组。但是,tup_num参数必须小于等于,意味着这个函数对元组数组一次只能增加一个元组。 - 但已存在的任意元组中的任意域可以以任意顺序进行调整。如果field_num的一个值已经存在,它会被覆盖。 - 如果len是 -1,或valueNULL, 该域值会被设置为一个 SQL 空值。 - value会被复制到结果的私有存储中,因此函数返回后就不再需要了。如果函数失败,返回值是 0。如果函数成功,返回值会是非 0。 - + 此函数会根据需要自动扩展结果内部的元组数组。不过,tup_num 参数必须小于或等于 ,也就是说,每次只能向元组数组增加一个元组。已有元组的任何字段都可以按任意顺序修改。如果 field_num 指定的位置已有值,该值会被覆盖。如果 len 为 -1 或 valueNULL,则将该字段设置为 SQL null 值。value 会被复制到结果的私有存储中,因此函数返回后就不再需要它。函数失败时返回零,成功时返回非零值。 + @@ -6077,8 +5801,8 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); - 当res被清除时,这个函数分配的内存也会被释放掉。如果函数失败,返回值是NULL。结果被保证为按照数据的任意类型充分地对齐,正如malloc所作的。 - + 使用此函数分配的所有内存都会在清除 res 时释放。函数失败时返回 NULL。与 malloc 一样,返回的内存保证满足任意数据类型的对齐要求。 + @@ -6089,15 +5813,15 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); - 检索为PGresult对象分配的字节数。 + 获取为 PGresult 对象分配的字节数。 size_t PQresultMemorySize(const PGresult *res); - + - 此值是与PGresult对象关联的所有malloc请求的总和,就是说,将释放的所有空间。此信息可用于管理内存消耗。 - + 此值是与 PGresult 对象相关的所有 malloc 请求所分配字节数的总和,即 将释放的全部内存。这一信息有助于管理内存消耗。 + @@ -6116,28 +5840,25 @@ int PQlibVersion(void); - 在运行时,这个函数的结果可以被用来决定在当前已载入的 libpq 版本中特定的功能是否可用。 - 例如,这个函数可以被用来决定哪些选项可以被用于。 - + 可在运行时根据此函数的结果,判断当前已加载的 libpq 版本是否具有特定功能。例如,可用它判断 支持哪些连接选项。 + - 结果通过将库的主版本号乘以10000再加上次版本号形成。例如,版本10.1将被返回为100001,而版本11.0将被返回为110000。 - + 返回值等于库的主版本号乘以 10000 再加上次版本号。例如,版本 10.1 返回 100001,版本 11.0 返回 110000。 + - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。 - 对于那些版本,为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - + 在主版本 10 之前,PostgreSQL 使用由三个部分组成的版本号,前两个部分共同表示主版本。对于这些版本, 用两位数字表示每个部分;例如,版本 9.1.5 返回 90105,版本 9.2.0 返回 90200。 + - 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。 - 在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 - + 因此,为了判断功能兼容性,应用程序应将 的结果除以 100 而非 10000,得到逻辑上的主版本号。在所有版本系列中,次版本(错误修复版本)之间只有最后两位数字不同。 + - 这个函数出现于PostgreSQL版本 9.1,因此它不能被用来在早期的版本中检测所需的功能,因为调用它将会创建一个对版本9.1及其后版本的链接依赖。 + 此函数从 PostgreSQL 9.1 起提供,因而不能用它检测更早版本是否具有所需功能:调用它会建立对 9.1 或更高版本的链接依赖。 @@ -6169,13 +5890,13 @@ pg_usec_time_t PQgetCurrentTimeUSec(void); 通知处理 - notice processing - in libpq + 通知处理 + 在 libpq 中 - 服务器产生的通知和警告消息不会被查询执行函数返回,因为它们不代表查询失败。它们可以被传递给一个通知处理函数,并且在处理者返回后执行会继续正常进行。默认的处理函数会把消息打印在stderr上,但是应用可以通过提供它自己的处理函数来重载这种行为。 - + 服务器生成的通知和警告消息不由查询执行函数返回,因为它们并不表示查询失败。这些消息会传递给通知处理函数,处理函数返回后,执行正常继续。默认通知处理函数将消息打印到 stderr,应用程序也可以提供自己的处理函数来替换这一行为。 + 由于历史原因,通知处理有两个级别,称为通知接收器和通知处理器。通知接收器的默认行为是格式化通知并且将一个字符串传递给通知处理器来打印。不过,如果一个应用选择提供自己的通知接收器,它通常会忽略通知处理器层并且在通知接收器中完成所有工作。 @@ -6183,10 +5904,10 @@ pg_usec_time_t PQgetCurrentTimeUSec(void); 函数PQsetNoticeReceiver - notice receiver + 通知接收器 PQsetNoticeReceiver为一个连接对象设置或者检查当前的通知接收器。 相似地,PQsetNoticeProcessor - notice processor + 通知处理器 PQsetNoticeProcessor设置或检查当前的通知处理器。 @@ -6209,19 +5930,16 @@ PQsetNoticeProcessor(PGconn *conn, - 当接收到一个服务器产生的或者libpq内部产生的通知或警告消息,通知接收器函数会被调用。 - 它会以一种PGRES_NONFATAL_ERROR PGresult的形式传递该消息 - (这允许接收器使用抽取个别的域,或者使用或者得到一个完整的预格式化的消息)。 - 被传递给PQsetNoticeReceiver的同一个空指针也被传递(必要时,这个指针可以被用来访问应用相关的状态)。 - + 从服务器收到通知或警告消息,或者 libpq 内部生成这类消息时,便会调用通知接收器函数。消息以状态为 PGRES_NONFATAL_ERRORPGresult 对象传给该函数。(接收器可使用 提取单个字段,也可使用 获取完整的预格式化消息。)传给 PQsetNoticeReceiver 的同一个 void 指针也会传入。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知接收器会简单地抽取消息(使用)并且将它传递给通知处理器。 - 通知处理器负责处理一个以文本形式给出的通知或警告消息。该消息的字符串文本(包括一个收尾的新行)被传递给通知处理器,外加一个同时被传递给PQsetNoticeProcessor的空指针(必要时,这个指针可以被用来访问应用相关的状态)。 - + 通知处理器负责处理以文本形式提供的通知或警告消息。传给它的参数包括消息字符串(含末尾的换行符),以及先前传给 PQsetNoticeProcessor 的同一个 void 指针。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知处理器很简单: @@ -6235,9 +5953,8 @@ defaultNoticeProcessor(void *arg, const char *message) - 一旦你设定了一个通知接收器或处理器,你应该期待只要PGconn对象或者从它构造出的PGresult对象存在,该函数就应该能被调用。 - 在一个PGresult创建时,PGconn的当前通知处理指针被复制到PGresult中,以备类似的函数使用。 - + 设置通知接收器或处理器后,应当预期:只要 PGconn 对象或由它生成的 PGresult 对象仍存在,就可能调用该函数。创建 PGresult 时,会将 PGconn 当前的通知处理指针复制到 PGresult 中,供 等函数在需要时使用。 + @@ -6246,19 +5963,19 @@ defaultNoticeProcessor(void *arg, const char *message) 事件系统 - libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和毁灭。一种主要的使用情况是这允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 + libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和销毁。一个主要用途是允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 - 每个注册的事件处理程序都与两个数据相关联,libpq仅将其视为不透明的void *指针。 - 有一个透传指针,当事件处理程序与PGconn注册时,应用程序提供。 + 每个注册的事件处理程序都与两项数据相关联,libpq仅将其视为不透明的void *指针。 + 有一个透传指针,由应用程序在向 PGconn 注册事件处理程序时提供。 透传指针在PGconn及其生成的所有PGresult的生命周期内永远不会更改; 因此,如果使用,它必须指向长期存在的数据。 此外,还有一个实例数据指针,在每个PGconnPGresult中一开始都是NULL。 可以使用函数来操作此指针。 请注意,与透传指针不同,PGconn的实例数据不会自动继承到从中创建的PGresult。 - libpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 —— 这是事件处理程序的责任。 + libpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 — 这是事件处理程序的责任。 @@ -6317,21 +6034,12 @@ typedef struct PGEVT_CONNDESTROY - - - 为了响应,连接销毁事件会被触发。由于 libpq 没有能力管理事件数据,事件过程有责任正确地清理它的事件数据。清理失败将会导致内存泄露。 - - + 连接销毁事件由以下调用触发:。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGconn *conn; } PGEventConnDestroy; - - - 当接收到一个PGEVT_CONNDESTROY事件时,evtInfo指针应该被类型转换为PGEventConnDestroy *。 - 这个事件在执行任何其他清理之前被触发。 - 该事件过程的返回值被忽略,因为没有办法指示一个来自的失败。还有,一个事件过程失败不该中断对不需要的内存的清理。 - +收到PGEVT_CONNDESTROY事件时,应将evtInfo指针强制转换为PGEventConnDestroy *。该事件触发于以下函数执行任何其他清理工作之前:。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:。此外,事件过程失败不应中止清理不再使用的内存的过程。 @@ -6387,21 +6095,12 @@ typedef struct PGEVT_RESULTDESTROY - - - 为了响应,结果销毁事件会被触发。由于 libpq 没有能力管理事件数据,事件过程有责任正确地清理它的事件数据。清理失败将会导致内存泄露。 - - + 结果销毁事件由以下调用触发:。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGresult *result; } PGEventResultDestroy; - - - 当接收到一个PGEVT_RESULTDESTROY事件时,evtInfo指针应该被类型转换为PGEventResultDestroy *。 - 这个事件在执行任何其他清理之前被触发。该事件过程的返回值被忽略,因为没有办法指示来自的失败。 - 还有,一个事件过程失败不该中断不需要的内存的清理过程。 - +收到PGEVT_RESULTDESTROY事件时,应将evtInfo指针强制转换为PGEventResultDestroy *。该事件触发于以下函数执行任何其他清理工作之前:。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:。此外,事件过程失败不应中止清理不再使用的内存的过程。 @@ -6409,7 +6108,7 @@ typedef struct - 事件回调函数 + 事件回调过程 @@ -6419,16 +6118,11 @@ typedef struct - PGEventProc是到一个事件过程的指针的 typedef,也就是从 libpq 接收事件的用户回调函数。一个事件过程的原型必须是 - + PGEventProc 是通过 typedef 定义的事件过程指针类型,也就是接收 libpq 事件的用户回调函数的指针类型。事件过程的签名必须为: int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) - - evtId指示发生了哪一个PGEVT事件。 - evtInfo指针必须被类型转换为合适的结构体类型才能获得关于事件的进一步信息。 - 当事件过程已被注册时,passThrough参数是提供给的指针。 - 如果成功,该函数应该返回非零值,失败则返回零。 +evtId 参数指示发生了哪一种 PGEVT 事件。必须将 evtInfo 指针强制转换为适当的结构体类型,以获取关于该事件的更多信息。passThrough 参数是在注册事件过程时传给 的指针。函数应在成功时返回非零值,在失败时返回零。 @@ -6438,8 +6132,8 @@ int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) - 在 Windows 上,函数能够有两个不同的地址:一个对 DLL 之外可见而另一个对 DLL 之内可见。我们应当小心只有其中之一会被用于libpq的事件过程函数,否则将会产生混淆。编写代码的最简单规则是将所有的事件过程声明为static。如果过程的地址必须对它自己的源代码文件之外可见,提供一个单独的函数来返回该地址。 - + 在 Windows 上,函数可能有两个不同的地址:一个在 DLL 外部可见,另一个在 DLL 内部可见。使用 libpq 的事件过程函数时,务必始终使用其中同一个地址,否则会产生混淆。确保代码正常工作的最简单做法,是将事件过程声明为 static。如果需要在过程所在的源文件之外取得其地址,应提供一个单独的函数来返回该地址。 + @@ -6467,7 +6161,7 @@ int PQregisterEventProc(PGconn *conn, PGEventProc proc, - 在每一个你想要接收事件的PGconn上必须注册一个事件过程。和内存不同,没有限制说一个连接上能注册多少个事件过程。如果该函数成功,它会返回一个非零值。如果它失败,则会返回零。 + 对于希望接收其事件的每个 PGconn,都必须注册一次事件过程。一个连接可注册的事件过程数量只受内存限制。函数成功时返回非零值,失败时返回零。 @@ -6512,16 +6206,14 @@ void *PQinstanceData(const PGconn *conn, PGEventProc proc); - 把结果的用于procinstanceData设置为data。成功返回非零,失败返回零(只有proc没有被正确地注册在conn中,才可能会失败)。 - + 将结果中针对 procinstanceData 设置为 data。成功时返回非零值,失败时返回零。(只有当 proc 未在结果中正确注册时,才可能失败。) int PQresultSetInstanceData(PGresult *res, PGEventProc proc, void *data); - 请注意,data表示的任何存储都不会由考虑,除非使用分配。 - (这样做是值得推荐的,因为它消除了在销毁结果时显式释放此类存储的需要。) + 注意,data 所指的存储不会计入 ,除非使用 分配它。(推荐这样做,因为结果销毁时便不必显式释放这部分存储。) @@ -6545,18 +6237,18 @@ void *PQresultInstanceData(const PGresult *res, PGEventProc proc); - 事件实例 + 事件示例 - 这里是一个管理与 libpq 连接和结果相关的私有数据的示例的框架。 - + 下面给出一个示例框架,用于管理与 libpq 连接和结果关联的私有数据。 + -/* The instanceData */ +/* instanceData 数据 */ typedef struct { int n; @@ -6576,14 +6268,14 @@ main(void) if (PQstatus(conn) != CONNECTION_OK) { - /* PQerrorMessage's result includes a trailing newline */ + /* PQerrorMessage 的结果包含末尾的换行符 */ fprintf(stderr, "%s", PQerrorMessage(conn)); PQfinish(conn); return 1; } - /* called once on any connection that should receive events. - * Sends a PGEVT_REGISTER to myEventProc. + /* 在每个需要接收事件的连接上调用一次。 + * 向 myEventProc 发送 PGEVT_REGISTER 事件。 */ if (!PQregisterEventProc(conn, myEventProc, "mydata_proc", NULL)) { @@ -6592,28 +6284,28 @@ main(void) return 1; } - /* conn instanceData is available */ + /* 可以取得 conn 的 instanceData */ data = PQinstanceData(conn, myEventProc); - /* Sends a PGEVT_RESULTCREATE to myEventProc */ + /* 向 myEventProc 发送 PGEVT_RESULTCREATE 事件 */ res = PQexec(conn, "SELECT 1 + 1"); - /* result instanceData is available */ + /* 可以取得结果的 instanceData */ data = PQresultInstanceData(res, myEventProc); - /* If PG_COPYRES_EVENTS is used, sends a PGEVT_RESULTCOPY to myEventProc */ + /* 使用 PG_COPYRES_EVENTS 时,向 myEventProc 发送 PGEVT_RESULTCOPY 事件 */ res_copy = PQcopyResult(res, PG_COPYRES_TUPLES | PG_COPYRES_EVENTS); - /* result instanceData is available if PG_COPYRES_EVENTS was - * used during the PQcopyResult call. + /* 如果调用 PQcopyResult 时使用了 PG_COPYRES_EVENTS, + * 就可以取得结果的 instanceData。 */ data = PQresultInstanceData(res_copy, myEventProc); - /* Both clears send a PGEVT_RESULTDESTROY to myEventProc */ + /* 两次清除操作都会向 myEventProc 发送 PGEVT_RESULTDESTROY 事件 */ PQclear(res); PQclear(res_copy); - /* Sends a PGEVT_CONNDESTROY to myEventProc */ + /* 向 myEventProc 发送 PGEVT_CONNDESTROY 事件 */ PQfinish(conn); return 0; @@ -6629,7 +6321,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventRegister *e = (PGEventRegister *)evtInfo; mydata *data = get_mydata(e->conn); - /* associate app specific data with connection */ + /* 将应用程序特有的数据与连接关联 */ PQsetInstanceData(e->conn, myEventProc, data); break; } @@ -6649,7 +6341,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventConnDestroy *e = (PGEventConnDestroy *)evtInfo; mydata *data = PQinstanceData(e->conn, myEventProc); - /* free instance data because the conn is being destroyed */ + /* 连接正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; @@ -6661,7 +6353,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *conn_data = PQinstanceData(e->conn, myEventProc); mydata *res_data = dup_mydata(conn_data); - /* associate app specific data with result (copy it from conn) */ + /* 将应用程序特有的数据与结果关联(从 conn 复制) */ PQresultSetInstanceData(e->result, myEventProc, res_data); break; } @@ -6672,7 +6364,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *src_data = PQresultInstanceData(e->src, myEventProc); mydata *dest_data = dup_mydata(src_data); - /* associate app specific data with result (copy it from a result) */ + /* 将应用程序特有的数据与结果关联(从另一个结果复制) */ PQresultSetInstanceData(e->dest, myEventProc, dest_data); break; } @@ -6682,18 +6374,18 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventResultDestroy *e = (PGEventResultDestroy *)evtInfo; mydata *data = PQresultInstanceData(e->result, myEventProc); - /* free instance data because the result is being destroyed */ + /* 结果正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; } - /* unknown event ID, just return true. */ + /* 未知的事件 ID,直接返回 true。 */ default: break; } - return true; /* event processing succeeded */ + return true; /* 事件处理成功 */ } ]]> @@ -6709,10 +6401,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 以下环境变量可用于选择默认连接参数值,这些值将被使用,如果调用代码没有直接指定值。这些对于避免将数据库连接信息硬编码到简单的客户端应用程序中非常有用,例如。 - - - + 以下环境变量可用于选择连接参数的默认值,供 在调用代码未直接指定参数值时使用。例如,这样可以避免在简单的客户端应用程序中硬编码数据库连接信息。 + + @@ -6722,8 +6413,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-host"/>连接参数相同。 - - + PGSSLNEGOTIATION @@ -6731,8 +6421,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSSLNEGOTIATION的行为与连接参数相同。 - - + @@ -6743,8 +6432,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) 这可以替代或者与PGHOST一起设置,以避免DNS查找开销。 - - + @@ -6754,8 +6442,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-port"/>连接参数相同。 - - + @@ -6765,8 +6452,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-dbname"/>连接参数相同。 - - + @@ -6776,8 +6462,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-user"/>连接参数相同。 - - + @@ -6788,8 +6473,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) 而应考虑使用密码文件(参见)。 - - + @@ -6799,8 +6483,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-passfile"/>连接参数相同。 - - + PGREQUIREAUTH @@ -6808,8 +6491,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGREQUIREAUTH的行为与连接参数相同。 - - + @@ -6819,8 +6501,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-channel-binding"/>连接参数相同。 - - + @@ -6830,20 +6511,17 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-service"/>连接参数相同。 - - + PGSERVICEFILE - PGSERVICEFILE指定每个用户的连接服务文件的名称 - (参见)。 - 默认为~/.pg_service.conf,或者在Microsoft Windows上为%APPDATA%\postgresql\.pg_service.conf。 + PGSERVICEFILE指定每个用户的连接服务文件的名称(参见)。 + 默认为~/.pg_service.conf,或者在 Microsoft Windows 上为%APPDATA%\postgresql\.pg_service.conf - - + @@ -6853,8 +6531,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-options"/>连接参数相同。 - - + @@ -6864,8 +6541,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-application-name"/>连接参数相同。 - - + @@ -6875,8 +6551,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslmode"/>连接参数相同。 - - + @@ -6884,11 +6559,10 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGREQUIRESSL的行为与连接参数相同。 - 这个环境变量已被弃用,推荐使用PGSSLMODE变量;设置这两个变量会抑制这个变量的效果。 + 这个环境变量已被弃用,推荐使用PGSSLMODE变量;同时设置这两个变量时,前者不再生效。 - - + @@ -6898,8 +6572,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslcompression"/>连接参数相同。 - - + @@ -6909,8 +6582,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslcert"/>连接参数相同。 - - + @@ -6920,8 +6592,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslkey"/>连接参数相同。 - - + PGSSLCERTMODE @@ -6929,8 +6600,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSSLCERTMODE的行为与连接参数相同。 - - + @@ -6940,8 +6610,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslrootcert"/>连接参数相同。 - - + @@ -6951,8 +6620,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslcrl"/>连接参数相同。 - - + @@ -6962,8 +6630,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslcrldir"/>连接参数相同。 - - + @@ -6973,8 +6640,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslsni"/>连接参数相同。 - - + @@ -6984,8 +6650,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-requirepeer"/>连接参数相同。 - - + @@ -6995,8 +6660,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-ssl-min-protocol-version"/>连接参数相同。 - - + @@ -7006,8 +6670,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-ssl-max-protocol-version"/>连接参数相同。 - - + @@ -7017,8 +6680,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-gssencmode"/>连接参数相同。 - - + @@ -7028,8 +6690,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-krbsrvname"/>连接参数相同。 - - + @@ -7039,8 +6700,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-gsslib"/>连接参数相同。 - - + PGGSSDELEGATION @@ -7048,8 +6708,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGGSSDELEGATION的行为与连接参数相同。 - - + @@ -7059,8 +6718,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-connect-timeout"/>连接参数相同。 - - + @@ -7070,8 +6728,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-client-encoding"/>连接参数相同。 - - + @@ -7081,14 +6738,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-target-session-attrs"/>连接参数相同。 - - - - - 下面的环境变量可用来为每一个PostgreSQL会话指定默认行为(为每一个用户或每一个数据库设置默认行为的方法还可见命令)。 - - - + PGLOADBALANCEHOSTS @@ -7096,8 +6746,13 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGLOADBALANCEHOSTS的行为与连接参数相同。 + + - + + 以下环境变量可用于指定每个 PostgreSQL 会话的默认行为。(也可参见 命令,了解按用户或按数据库设置默认行为的方法。) + + PGDATESTYLE @@ -7105,8 +6760,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGDATESTYLE设置日期/时间表示的默认风格(等同于SET datestyle TO ...)。 - - + PGTZ @@ -7114,8 +6768,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGTZ设置默认的时区(等同于SET timezone TO ...)。 - - + PGGEQO @@ -7124,8 +6777,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - - 这些环境变量的正确值可参考SQL 命令 。 +有关这些环境变量的正确取值,请参见 SQL 命令 @@ -7170,16 +6822,12 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) 用户主目录中的.pgpass文件可保存密码,供连接需要密码且尚未通过其他方式指定密码时使用。在 Microsoft Windows 上,文件名为%APPDATA%\postgresql\pgpass.conf(其中%APPDATA%指用户配置文件中的应用数据子目录)。也可以通过连接参数或环境变量PGPASSFILE指定要使用的密码文件。 - - 这个文件应该包含下列格式的行: - + 该文件中的行应采用以下格式: hostname:port:database:username:password - - (你可以向该文件增加一个提醒:把上面的行复制到该文件并且在前面加上#)。前四个字段的每一个都可以是字面值或者匹配任何东西的*。第一个匹配当前连接参数的行中的密码字段将被使用(因此,在使用通配符时把更特殊的项放在前面)。如果一个条目需要包含:或者\,用\对该字符转义。如果指定了host连接参数,主机名字段会被匹配到host,否则如果指定了hostaddr参数则匹配到hostaddr,如果两者都没有给出,则会搜索主机名localhost。当连接是一个Unix域套接字连接并且host参数匹配libpq的默认套接字目录路径时,也会搜索主机名localhost。在一台备库上,值为replication的数据库字段匹配连接到主库的流复制连接。否则数据库字段的用途有限,因为用户对同一个集簇中的所有数据库都有相同的密码。 - +(可以复制上面这一行,并在行首加上#,在文件中加入提示注释。)前四个字段中的每一个都可以是字面值,或者是*,后者可以匹配任何内容。将使用与当前连接参数匹配的第一行中的密码字段。(因此,使用通配符时,应将更具体的条目放在前面。)如果条目需要包含:\,请使用\转义该字符。主机名字段首先匹配已指定的host连接参数;否则匹配已指定的hostaddr参数。如果两者都未指定,则查找主机名localhost。在以下情况下也会查找主机名localhost:连接使用 Unix 域套接字,且host参数与libpq的默认套接字目录路径匹配。在备库中,数据库字段为replication时,匹配连接到主库的流复制连接。除此之外,数据库字段的用途有限,因为同一用户在同一数据库集簇的所有数据库中使用相同的密码。 - 在 Unix 系统上,密码文件上的权限必须不允许所有人或组内访问,可以用chmod 0600 ~/.pgpass这样的命令实现。如果权限没有这么严格,该文件将被忽略。在微软 Windows 上,该文件被假定存储在一个安全的目录中,因此不会进行特别的权限检查。 + 在 Unix 系统上,密码文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.pgpass 这样的命令实现。如果权限没有这么严格,该文件将被忽略。在 Microsoft Windows 上,假定该文件存储在安全的目录中,因此不进行特殊的权限检查。 @@ -7200,10 +6848,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 连接服务文件允许 libpq 连接参数与一个单一服务名称关联。 - 那个服务名称可以在一个 libpq 连接字符串里面指定,与其相关的设置将被使用。 - 这允许在不重新编译使用 libpq 的应用的前提下修改连接参数。 - 服务名称也可以被使用PGSERVICE环境变量来指定。 + 连接服务文件允许将 libpq 连接参数与单个服务名称关联。随后可以在 libpq 连接字符串中指定该服务名称,从而使用关联的设置。这样便可以修改连接参数,而无需重新编译使用 libpq 的应用程序。也可以使用 PGSERVICE 环境变量指定服务名称。 @@ -7219,23 +6864,19 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 或者服务文件使用一种INI 文件格式,其中小节名是服务名并且参数是连接参数。 - 列表见。例如: + 两种服务文件均使用 INI 文件 格式,其中配置段名称是服务名称,参数是连接参数;参数列表见 。例如: -# comment +# 注释 [mydb] host=somehost port=5433 user=admin - 在PostgreSQL安装的share/pg_service.conf.sample中提供了一个示例文件。 +PostgreSQL 安装目录中的 share/pg_service.conf.sample 提供了一个示例文件。 - 从服务文件中获取的连接参数与从其他来源获取的参数相结合。 - 服务文件设置覆盖相应的环境变量,然后反过来可以由连接字符串中直接给出的值覆盖。 - 例如,使用上面的服务文件,连接字符串service=mydb port=5434将使用主机somehost,端口5434, - 用户admin,以及由环境变量或内置默认所设置的其他参数。 + 从服务文件中获取的连接参数会与其他来源的参数合并。服务文件中的设置会覆盖相应的环境变量,而连接字符串中直接给出的值又会覆盖服务文件中的设置。例如,使用上述服务文件时,连接字符串 service=mydb port=5434 将使用主机 somehost、端口 5434、用户 admin,以及由环境变量或内置默认值设置的其他参数。 @@ -7251,24 +6892,14 @@ user=admin 如果libpq已经在编译时打开了 LDAP 支持(configure的选项),就可以通过 LDAP 从一个中央服务器检索hostdbname之类的连接参数。这样做的好处是如果一个数据库的连接参数改变,不需要在所有的客户端机器上更新连接信息。 - - LDAP连接参数查找使用连接服务文件pg_service.conf(参见)。 - 在pg_service.conf段落中以ldap://开头的行将被识别为LDAP URL,并执行LDAP查询。 - 结果必须是一组keyword = value对,将用于设置连接选项。 - URL必须符合RFC 1959的形式为 - + LDAP 连接参数查询使用连接服务文件pg_service.conf(参见)。在pg_service.conf的配置段中,以ldap://开头的行会被识别为 LDAP URL,并执行 LDAP 查询。结果必须是一个keyword = value键值对列表,用于设置连接选项。URL 必须符合 RFC 1959,格式如下: ldap://[hostname[:port]]/search_base?attribute?search_scope?filter - - 其中hostname默认为localhostport默认为389。 - +其中,hostname默认为localhostport默认为 389。 - - 一次成功的 LDAP 查找后,pg_service.conf的处理被终止。但是如果联系不上 LDAP 则会继续处理pg_service.conf。这就提供了后手,可以加入更多指向不同 LDAP 服务器的 LDAP URL 行、经典的keyword = value对或者默认连接选项。如果你宁愿在这种情况下得到一个错误消息,在该 LDAP URL 之后增加一个语法错误的行。 - + LDAP 查找成功后就会停止处理 pg_service.conf;如果无法联系 LDAP 服务器,则会继续处理。这使后续指向其他 LDAP 服务器的 LDAP URL 行、常规的 keyword = value 对或默认连接选项能够作为后备。如果希望在这种情况下得到错误消息,可以在 LDAP URL 后添加一个语法不正确的行。 - - 一个和 LDIF 文件一起创建的 LDAP 条目实例 - + 例如,使用以下 LDIF 文件创建的 LDAP 条目: version:1 dn:cn=mydatabase,dc=mycompany,dc=com changetype:add @@ -7280,9 +6911,7 @@ description:port=5439 description:dbname=mydb description:user=mydb_user description:sslmode=require - - 可以用下面的 LDAP URL 查询: - +可以通过以下 LDAP URL 查询: ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase) @@ -7290,7 +6919,7 @@ ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase) 你也可以将常规的服务文件条目和 LDAP 查找混合。pg_service.conf中一节的完整示例: -# 只有主机和端口存储在LDAP中,显式指定dbname和user。 +# 仅 host 和 port 存储在 LDAP 中;显式指定 dbname 和 user [customerdb] dbname=customer user=appuser @@ -7310,9 +6939,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - PostgreSQL具有原生支持使用SSL连接来加密客户端/服务器通信, - 使用TLS协议以提高安全性。有关服务器端SSL功能的详细信息,请参见。 - + PostgreSQL 原生支持使用 SSL 连接,通过 TLS 协议加密客户端与服务器之间的通信,以提高安全性。有关服务器端 SSL 功能的详细信息,请参见 。 + libpq读取系统范围的OpenSSL配置文件。默认情况下,这个文件被命名为openssl.cnf并且位于openssl version -d所报告的目录中。可以通过设置环境变量OPENSSL_CONF把这个默认值覆盖为想要的配置文件的名称。 @@ -7320,39 +6948,25 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 服务器证书的客户端验证 + 客户端对服务器证书的验证 - 默认情况下,PostgreSQL将不会执行服务器证书的任何验证。这意味着可以在不被客户端知晓的情况下伪造服务器身份(例如通过修改一个 DNS 记录或者接管服务器的 IP 地址)。为了阻止哄骗,客户端必须能够通过一条信任链验证服务器的身份。信任链可以这样建立:在一台计算机上放置一个根(自签名的)证书机构(CA)的证书并且在另一台计算机上放置一个由根证书签发的叶子证书。还可以使用一种中间证书,它由根证书签发并且可以签发叶子证书。 + 默认情况下,PostgreSQL 不会对服务器证书执行任何验证。这意味着可以在客户端不知情的情况下伪造服务器身份,例如修改 DNS 记录或接管服务器的 IP 地址。要防止身份伪造,客户端必须能够通过信任链验证服务器身份。建立信任链的方法是:在一台计算机上放置根证书机构(CA)的自签名证书,在另一台计算机上放置由根证书签发的叶证书。也可以使用由根证书签发、又用于签发叶证书的中间证书。 - - 为了允许客户端验证服务器的身份,在客户端上放置一份根证书并且在服务器上放置由根证书签发的叶子证书。为了允许服务器验证客户端的身份,在服务器上放置一份根证书并且在客户端上放置由根证书签发的叶子证书。也可以使用一个或者更多个中间证书(通常与叶子证书存在一起)来将叶子证书链接到根证书。 - + 要让客户端验证服务器的身份,请在客户端放置根证书,并在服务器上放置由该根证书签发的叶证书。要让服务器验证客户端的身份,请在服务器上放置根证书,并在客户端放置由该根证书签发的叶证书。也可以使用一个或多个中间证书(通常与叶证书存储在一起),将叶证书链接到根证书。 - - 一旦信任链被建立起来,客户端有两种方法验证服务器发过来的叶子证书。如果参数sslmode被设置为verify-ca,libpq将通过检查该证书是否链接到存储在客户端上的根证书来验证服务器。如果sslmode被设置为verify-full,libpq将验证服务器的主机名匹配存储在服务器证书中的名称。如果服务器证书无法被验证,则SSL连接将失败。在大部分对安全性很敏感的环境中,推荐使用verify-full。 - + 建立信任链后,客户端可以通过两种方式验证服务器发送的叶证书。如果参数 sslmode 设为 verify-ca,libpq 会沿证书链检查到存储在客户端上的根证书,以验证服务器是否可信。如果 sslmode 设为 verify-full,libpq 还会验证服务器主机名是否与服务器证书中存储的名称匹配。如果无法验证服务器证书,SSL 连接将失败。在大多数对安全敏感的环境中,建议使用 verify-full - 在verify-full模式下,主机名将与证书的主体替代名称属性(SAN)匹配, - 或者与通用名称属性匹配,如果没有类型为dNSName的SAN存在。 - 如果证书的名称属性以星号(*)开头,那么星号将被视为通配符, - 可以匹配所有字符,除了点(.)。 - 这意味着证书将不匹配子域。如果连接使用IP地址而不是主机名进行, - 则IP地址将与类型为iPAddressdNSName的SAN匹配 - (不进行任何DNS查找)。如果没有iPAddress SAN存在, - 也没有匹配的dNSName SAN存在,则主机IP地址将与通用名称属性匹配。 - + 在 verify-full 模式下,会将主机名与证书的主体替代名称属性(SAN)匹配;如果不存在类型为 dNSName 的 SAN,则与通用名称属性匹配。如果证书的名称属性以星号(*)开头,该星号会被视为通配符,匹配点(.)以外的所有字符。这意味着该证书不会匹配子域。如果使用 IP 地址而不是主机名建立连接,则会将该 IP 地址与类型为 iPAddressdNSName 的 SAN 匹配(不执行任何 DNS 查询)。如果不存在 iPAddress SAN,也不存在匹配的 dNSName SAN,则将主机 IP 地址与通用名称属性匹配。 + - 为了与早期版本的PostgreSQL向后兼容,主机IP地址的验证方式与 - RFC 6125中的方式不同。 - 主机IP地址始终与dNSName SANs以及iPAddress SANs匹配, - 如果不存在相关的SANs,则可以与通用名称属性匹配。 - + 为与 PostgreSQL 的早期版本向后兼容,主机 IP 地址的验证方式与 RFC 6125 不同。主机 IP 地址始终会与 dNSName SAN 以及 iPAddress SAN 匹配;如果不存在相关的 SAN,还可以与通用名称属性匹配。 + @@ -7372,8 +6986,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 为了与 PostgreSQL 的早期版本达到向后兼容,如果存在一个根 CA 文件,sslmode=require的行为将与verify-ca相同,即服务器证书根据 CA 验证。我们鼓励依赖这种行为,并且需要证书验证的应用应该总是使用verify-ca或者verify-full。 - + 为与 PostgreSQL 的早期版本向后兼容,如果存在根 CA 文件,sslmode=require 的行为将与 verify-ca 相同,即根据 CA 验证服务器证书。不建议依赖这种行为;需要证书验证的应用程序应始终使用 verify-caverify-full。 + @@ -7382,44 +6996,27 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 客户端证书 - 如果服务器尝试通过请求客户端的叶证书来验证客户端的身份, - libpq将发送存储在文件 - ~/.postgresql/postgresql.crt中的证书,该文件位于用户的主目录中。 - 证书必须链到服务器信任的根证书。匹配的 - 私钥文件~/.postgresql/postgresql.key也必须存在。 - 在Microsoft Windows上,这些文件的名称分别为 - %APPDATA%\postgresql\postgresql.crt和 - %APPDATA%\postgresql\postgresql.key。 - 证书和密钥文件的位置可以通过连接参数 - sslcertsslkey, - 或通过环境变量PGSSLCERTPGSSLKEY来覆盖。 - + 如果服务器请求客户端的叶证书以验证客户端身份,libpq 将发送用户主目录下 ~/.postgresql/postgresql.crt 文件中存储的证书。这些证书必须通过证书链连接到服务器信任的根证书。还必须存在匹配的私钥文件 ~/.postgresql/postgresql.key。在 Microsoft Windows 上,这两个文件分别名为 %APPDATA%\postgresql\postgresql.crt%APPDATA%\postgresql\postgresql.key。可以通过连接参数 sslcertsslkey,或环境变量 PGSSLCERTPGSSLKEY,覆盖证书和密钥文件的位置。 + - 在Unix系统上,私钥文件的权限必须禁止任何对世界或组的访问;可以通过类似以下命令来实现: - chmod 0600 ~/.postgresql/postgresql.key。 - 或者,该文件可以由root拥有并具有组读取权限(即0640权限)。 - 该设置适用于由操作系统管理证书和密钥文件的安装。然后,libpq的用户应该成为具有对这些证书和密钥文件访问权限的组的成员。 - (在Microsoft Windows上,没有文件权限检查,因为假定%APPDATA%\postgresql目录是安全的。) - + 在 Unix 系统上,私钥文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.postgresql/postgresql.key 这样的命令实现。另一种做法是使文件归 root 所有,并允许组用户读取(即 0640 权限)。这种设置适用于由操作系统管理证书和密钥文件的安装环境。此时,应将 libpq 用户加入有权访问这些证书和密钥文件的组。(在 Microsoft Windows 上,不检查文件权限,因为假定 %APPDATA%\postgresql 目录是安全的。) + postgresql.crt中的第一个证书必须是客户端的证书,因为它必须匹配客户端的私钥。可以选择将中间证书追加到该文件 — 这样做避免了在服务器上存放中间证书的要求()。 - 证书和密钥可能是 PEM 或 ASN.1 DER 格式。 + 证书和密钥可以采用 PEM 或 ASN.1 DER 格式。 - 密钥可以以明文存储,也可以使用OpenSSL支持的任何算法(例如AES-128)使用密码进行加密。 - 如果密钥是加密存储的,那么可以在连接选项中提供密码。 - 如果提供了加密密钥,而且sslpassword选项不存在或为空,那么只要 TTY 可用,OpenSSL就会以Enter PEM pass phrase:提示交互式输入密码。 - 应用程序可以通过提供自己的密钥密码回调,覆盖客户端证书提示以及sslpassword参数的处理;参见。 + 密钥可以以明文存储,也可以使用密码,按 OpenSSL 支持的任意算法(例如 AES-128)进行加密。如果密钥以加密形式存储,可以在 连接选项中提供密码。如果提供了加密密钥,而 sslpassword 选项缺失或为空,则在有 TTY 可用时,OpenSSL 会显示 Enter PEM pass phrase: 提示,交互式地请求输入密码。应用程序可以提供自己的密钥密码回调,以覆盖客户端证书提示及 sslpassword 参数的处理;参见 - 创建证书的指令请参考。 + 有关创建证书的说明,请参见 @@ -7428,8 +7025,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 不同模式中提供的保护 - sslmode参数的不同值提供了不同级别的保护。SSL 能够针对三类攻击提供保护: - + sslmode 参数的不同值提供不同级别的保护。SSL 可以防范三类攻击: 窃听 @@ -7442,31 +7038,33 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 中间人(MITM - 如果一个第三方能对客户端和服务器之间传送的数据进行修改,它就能假装是服务器并且因此能看见并且修改数据,即使这些数据已被加密。然后第三方可以将连接信息和数据转送给原来的服务器,使得它不可能检测到攻击。这样做的通常途径包括 DNS 污染和地址劫持,借此客户端被重定向到一个不同的服务器。还有几种其他的攻击方式能够完成这种攻击。SSL使用证书验证让客户端认证服务器,就可以阻止这种攻击。 - + + 如果第三方能修改客户端与服务器之间传输的数据,就可以冒充服务器,进而查看和修改数据,即使数据已经加密。随后,第三方可以将连接信息和数据转发给原来的服务器,使攻击无法被察觉。常见的手段包括 DNS 污染和地址劫持,从而将客户端引向预期之外的服务器。还有其他几种攻击手段可以达到同样的目的。SSL 使用证书验证,让客户端认证服务器身份,以防范这种攻击。 + - 模仿 + 冒充 - 如果一个第三方能假装是一个授权的客户端,它能够简单地访问它本不能访问的数据。通常这可以由不安全的密码管理所致。SSL使用客户端证书来确保只有持有合法证书的客户端才能访问服务器,这样就能阻止这种攻击。 - + + 如果第三方能冒充获授权的客户端,就能直接访问其无权访问的数据。这通常可能由不安全的密码管理导致。SSL 使用客户端证书,确保只有持有有效证书的客户端才能访问服务器,以防范这种攻击。 + - 对于一个已知受 SSL 保护的连接,在连接建立之前,必须在客户端和服务器两端都配置 SSL。如果只在服务器端配置,客户端在得知服务器要求高安全性之前,可能就已经开始发送敏感信息(例如密码)。在 libpq 中,要确保连接安全,可以把sslmode参数设置为verify-fullverify-ca,并为系统提供一个用于验证的根证书。这类似于使用https URL浏览加密网页。 + 要确保连接受到 SSL 保护,必须在建立连接之前,在客户端和服务器两端配置 SSL。如果仅在服务器上配置,客户端可能在得知服务器要求高安全性之前就已发送敏感信息(例如密码)。在 libpq 中,可以将 sslmode 参数设为 verify-fullverify-ca,并向系统提供用于验证的根证书,以确保连接安全。这类似于使用 https URL 进行加密的网页浏览。 - 一旦服务器已经被认证,客户端可以传递敏感数据。这意味着直到这一点,客户端都不需要知道是否证书将被用于认证,这样只需要在服务器配置中指定就比较安全。 + 服务器通过身份认证后,客户端便可以传送敏感数据。这意味着,在此之前,客户端无需知道是否会使用证书进行认证,因此可以安全地仅在服务器配置中指定这一点。 - 所有SSL选项都带来了加密和密钥交换的负荷,因此必须在性能和安全性之间做出平衡。不同sslmode值所保护的风险,以及它们是怎样看待安全性和负荷的。 + 所有 SSL 选项都会产生加密和密钥交换的开销,因此必须在性能与安全性之间作出权衡。 说明了不同 sslmode 值所能防范的风险,以及它们所表达的对安全性和开销的取舍。
@@ -7482,7 +7080,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) sslmode 窃听保护 - 中间人攻击防护 + MITM 防护 声明 @@ -7493,7 +7091,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) disable - 我不关心安全性,并且我不想为加密增加负荷。 + 我不关心安全性,并且我不想为加密增加开销。 @@ -7501,7 +7099,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) allow 可能 - 我不关心安全性,但如果服务器坚持,我将承担加密带来的负荷。 + 我不关心安全性,但如果服务器坚持,我将承担加密带来的开销。 @@ -7509,7 +7107,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) prefer 可能 - 我不关心安全性,但如果服务器支持,我希望承担加密带来的负荷。 + 我不关心加密,但如果服务器支持,我希望承担加密带来的开销。 @@ -7517,7 +7115,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) require - 我想要对数据加密,并且我接受因此带来的负荷。我信任该网络会保证我总是连接到想要连接的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我信任该网络会保证我总是连接到想要连接的服务器。 @@ -7525,7 +7123,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-ca 取决于 CA 策略 - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器。 @@ -7533,7 +7131,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-full - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 @@ -7542,11 +7140,11 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
- verify-caverify-full之间的区别取决于根CA的策略。如果使用了一个公共CAverify-ca允许连接到那些可能已经被其他人注册到该CA的服务器。在这种情况下,总是应该使用verify-full。如果使用了一个本地CA或者甚至是一个自签名的证书,使用verify-ca常常就可以提供足够的保护。 + verify-caverify-full之间的区别取决于根CA的策略。如果使用了一个公共CAverify-ca允许连接到那些可能已经被其他人注册到该CA的服务器。在这种情况下,总是应该使用verify-full。如果使用了一个本地CA或者甚至是一个自签名的证书,使用verify-ca常常就可以提供足够的保护。 - sslmode的默认值是prefer。如表中所示,这在安全性的角度来说没有意义,并且它只承诺可能的性能负荷。提供它作为默认值只是为了向后兼容,并且我们不推荐在安全部署中使用它。 + sslmode 的默认值是 prefer。如表所示,从安全角度看,这一设置没有意义;它只会在可能时带来性能开销。将其作为默认值仅出于向后兼容的考虑,不建议在有安全要求的部署中使用。 @@ -7588,8 +7186,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) ~/.postgresql/root.crt - 可信的证书机构 - 检查服务器证书是由一个可信的证书机构签发 + 受信任的证书机构 + 检查服务器证书是由一个受信任的证书机构签发 @@ -7608,9 +7206,9 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) SSL 库初始化 - 如果您的应用程序初始化libssl和/或libcrypto库,并且libpq - 构建时带有SSL支持,您应该调用告诉libpq - libssl和/或libcrypto库已被您的应用程序初始化,以便 + 如果你的应用程序初始化libssl和/或libcrypto库,并且libpq + 构建时带有SSL支持,你应该调用告诉libpq + libssl和/或libcrypto库已被你的应用程序初始化,以便 libpq不会再初始化这些库。 但是,当使用OpenSSL版本1.1.0或更高版本时,无需这样做,因为重复初始化不再成问题。 @@ -7622,7 +7220,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 允许应用选择要初始化哪个安全性库。 + 允许应用程序选择要初始化的安全库。 void PQinitOpenSSL(int do_ssl, int do_crypto); @@ -7646,7 +7244,7 @@ void PQinitOpenSSL(int do_ssl, int do_crypto); PQinitSSLPQinitSSL - 允许应用选择要初始化哪个安全性库。 + 允许应用程序选择要初始化的安全库。 void PQinitSSL(int do_ssl); @@ -7670,7 +7268,7 @@ void PQinitSSL(int do_ssl); - 在线程化程序中的行为 + 多线程程序中的行为 线程 @@ -7709,7 +7307,7 @@ int PQisthreadsafe(); - 已废弃的函数不是线程安全的,不应在多线程程序中使用。可以用替代;可以用替代。 + 已弃用的函数 不是线程安全的,不应在多线程程序中使用。 可以用 替代; 可以用 替代。 @@ -7719,7 +7317,7 @@ int PQisthreadsafe(); - 编译 <application>libpq</application> 程序 + 构建 <application>libpq</application> 程序 编译 @@ -7727,16 +7325,16 @@ int PQisthreadsafe(); - 要编译(即编译并且链接)一个使用libpq的程序,你需要做下列所有的事情: + 要构建(即编译和链接)一个使用 libpq 的程序,需要完成以下所有步骤: - 包括libpq-fe.h头文件: + 包含 libpq-fe.h 头文件: #include <libpq-fe.h> - 如果你无法这样做,那么你通常会从你的编译器得到像这样的错误消息: +如果没有这样做,编译器通常会给出类似以下内容的错误消息: foo.c: In function `main': foo.c:34: `PGconn' undeclared (first use in this function) @@ -7745,24 +7343,24 @@ foo.c:54: `CONNECTION_BAD' undeclared (first use in this function) foo.c:68: `PGRES_COMMAND_OK' undeclared (first use in this function) foo.c:95: `PGRES_TUPLES_OK' undeclared (first use in this function) - + - 通过为你的编译器提供-Idirectory选项,向你的编译器指出PostgreSQL头文件安装在哪里(在某些情况下编译器默认将查看该目录,因此你可以忽略这个选项)。例如你的编译命令行可能看起来像: + 向编译器提供 -Idirectory 选项,指定 PostgreSQL 头文件的安装目录。(某些情况下,编译器默认会搜索该目录,此时可以省略这个选项。)例如,编译命令行可以是: cc -c -I/usr/local/pgsql/include testprog.c - 如果你在使用 makefile,那么把该选项加到CPPFLAGS变量中: +如果使用 makefile,请将该选项添加到 CPPFLAGS 变量中: CPPFLAGS += -I/usr/local/pgsql/include - + 如果你的程序可能由其他用户编译,那么你不应该像那样硬编码目录位置。你可以运行工具pg_configpg_configwith libpq在本地系统上找出头文件在哪里: + sortas="libpq">用于 libpq在本地系统上找出头文件在哪里: $ pg_config --includedir /usr/local/include @@ -7770,8 +7368,7 @@ CPPFLAGS += -I/usr/local/pgsql/include - 如果你安装了pkg-configpkg-configwith - libpq,你可以运行: + 如果你安装了pkg-configpkg-config用于 libpq,你可以运行: $ pkg-config --cflags libpq -I/usr/local/include @@ -7780,20 +7377,20 @@ CPPFLAGS += -I/usr/local/pgsql/include - 无法为编译器指定正确的选项将导致一个错误消息,例如: + 未向编译器指定正确的选项将导致类似以下内容的错误消息: testlibpq.c:8:22: libpq-fe.h: No such file or directory - +
- 当链接最终的程序时,指定选项-lpq,这样libpq库会被编译进去,也可以用选项-Ldirectory向编译器指出libpq库所在的位置(再次,编译器将默认搜索某些目录)。为了最大的可移植性,将选项放在选项前面。例如: + 链接最终程序时,指定 -lpq 选项以链接 libpq 库,同时指定 -Ldirectory 选项,告知编译器 libpq 库所在的目录。(同样,编译器默认会搜索某些目录。)为获得最大的可移植性,请将 选项放在 选项之前。例如: cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq - +
你也可以使用pg_config找出库目录: @@ -7820,7 +7417,7 @@ testlibpq.o(.text+0x60): undefined reference to `PQsetdbLogin' testlibpq.o(.text+0x71): undefined reference to `PQstatus' testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage'
- 这意味着你忘了 . + 这意味着你忘记了 /usr/bin/ld: cannot find -lpq @@ -7837,7 +7434,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' 示例程序 - 这些示例和其他示例可以在源代码发布的src/test/examples目录中找到。 + 这些示例和其他示例可在源代码发行包的src/test/examples目录中找到。 @@ -7852,7 +7449,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' * * testlibpq.c * - * Test the C version of libpq, the PostgreSQL frontend library. + * 测试 PostgreSQL 前端库 libpq 的 C 语言版本。 */ #include #include @@ -7876,26 +7473,25 @@ main(int argc, char **argv) j; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -7906,19 +7502,17 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Our test case here involves using a cursor, for which we must be inside - * a transaction block. We could do the whole thing with a single - * PQexec() of "select * from pg_database", but that's too trivial to make - * a good example. + * 这里的测试用例使用游标,因此必须处于事务块内。 + * 只需调用一次 PQexec() 执行 "select * from pg_database" 就能完成全部操作, + * 但这太简单了,不足以作为一个好的示例。 */ - /* Start a transaction block */ + /* 开始一个事务块 */ res = PQexec(conn, "BEGIN"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -7929,7 +7523,7 @@ main(int argc, char **argv) PQclear(res); /* - * Fetch rows from pg_database, the system catalog of databases + * 从数据库系统目录 pg_database 中获取行 */ res = PQexec(conn, "DECLARE myportal CURSOR FOR select * from pg_database"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -7948,13 +7542,13 @@ main(int argc, char **argv) exit_nicely(conn); } - /* first, print out the attribute names */ + /* 首先,打印属性名 */ nFields = PQnfields(res); for (i = 0; i < nFields; i++) printf("%-15s", PQfname(res, i)); printf("\n\n"); - /* next, print out the rows */ + /* 接着,打印各行 */ for (i = 0; i < PQntuples(res); i++) { for (j = 0; j < nFields; j++) @@ -7964,15 +7558,15 @@ main(int argc, char **argv) PQclear(res); - /* close the portal ... we don't bother to check for errors ... */ + /* 关闭 portal……这里不再检查错误…… */ res = PQexec(conn, "CLOSE myportal"); PQclear(res); - /* end the transaction */ + /* 结束事务 */ res = PQexec(conn, "END"); PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -7992,15 +7586,15 @@ main(int argc, char **argv) * * * testlibpq2.c - * Test of the asynchronous notification interface + * 测试异步通知接口 * - * Start this program, then from psql in another window do + * 启动此程序,然后在另一个窗口中通过 psql 执行 * NOTIFY TBL2; - * Repeat four times to get this program to exit. + * 重复四次后,此程序便会退出。 * - * Or, if you want to get fancy, try this: - * populate a database with the following commands - * (provided in src/test/examples/testlibpq2.sql): + * 或者,可以尝试更复杂的示例: + * 使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq2.sql 中): * * CREATE SCHEMA TESTLIBPQ2; * SET search_path = TESTLIBPQ2; @@ -8009,7 +7603,7 @@ main(int argc, char **argv) * CREATE RULE r1 AS ON INSERT TO TBL1 DO * (INSERT INTO TBL2 VALUES (new.i); NOTIFY TBL2); * - * Start this program, then from psql do this four times: + * 启动此程序,然后通过 psql 将以下命令执行四次: * * INSERT INTO TESTLIBPQ2.TBL1 VALUES (10); */ @@ -8021,11 +7615,9 @@ main(int argc, char **argv) #include #include #include +#include #include #include -#ifdef HAVE_SYS_SELECT_H -#include -#endif #include "libpq-fe.h" @@ -8046,26 +7638,25 @@ main(int argc, char **argv) int nnotifies; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -8076,13 +7667,12 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Issue LISTEN command to enable notifications from the rule's NOTIFY. + * 发出 LISTEN 命令,以接收规则中的 NOTIFY 发出的通知。 */ res = PQexec(conn, "LISTEN TBL2"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -8093,14 +7683,13 @@ main(int argc, char **argv) } PQclear(res); - /* Quit after four notifies are received. */ + /* 收到四次通知后退出。 */ nnotifies = 0; while (nnotifies < 4) { /* - * Sleep until something happens on the connection. We use select(2) - * to wait for input, but you could also use poll() or similar - * facilities. + * 休眠,直到连接上有事件发生。这里使用 select(2) 等待输入, + * 也可以使用 poll() 或类似机制。 */ int sock; fd_set input_mask; @@ -8108,7 +7697,7 @@ main(int argc, char **argv) sock = PQsocket(conn); if (sock < 0) - break; /* shouldn't happen */ + break; /* 不应发生 */ FD_ZERO(&input_mask); FD_SET(sock, &input_mask); @@ -8119,7 +7708,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Now check for input */ + /* 现在检查是否有输入 */ PQconsumeInput(conn); while ((notify = PQnotifies(conn)) != NULL) { @@ -8134,7 +7723,7 @@ main(int argc, char **argv) fprintf(stderr, "Done.\n"); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -8154,10 +7743,10 @@ main(int argc, char **argv) * * * testlibpq3.c - * Test out-of-line parameters and binary I/O. + * 测试在 SQL 命令文本之外独立传递的参数和二进制 I/O。 * - * Before running this, populate a database with the following commands - * (provided in src/test/examples/testlibpq3.sql): + * 运行前,使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq3.sql 中): * * CREATE SCHEMA testlibpq3; * SET search_path = testlibpq3; @@ -8166,7 +7755,7 @@ main(int argc, char **argv) * INSERT INTO test1 values (1, 'joe''s place', '\000\001\002\003\004'); * INSERT INTO test1 values (2, 'ho there', '\004\003\002\001\000'); * - * The expected output is: + * 预期输出为: * * tuple 0: got * i = (4 bytes) 1 @@ -8190,7 +7779,7 @@ main(int argc, char **argv) #include #include "libpq-fe.h" -/* for ntohl/htonl */ +/* 用于 ntohl/htonl */ #include #include @@ -8202,9 +7791,8 @@ exit_nicely(PGconn *conn) } /* - * This function prints a query result that is a binary-format fetch from - * a table defined as in the comment above. We split it out because the - * main() function uses it twice. + * 此函数打印从上面注释所定义的表中以二进制格式获取的查询结果。 + * 由于 main() 会使用它两次,因此将它单独提取成一个函数。 */ static void show_binary_results(PGresult *res) @@ -8215,7 +7803,7 @@ show_binary_results(PGresult *res) t_fnum, b_fnum; - /* Use PQfnumber to avoid assumptions about field order in result */ + /* 使用 PQfnumber,以避免对结果中的字段顺序作出假设 */ i_fnum = PQfnumber(res, "i"); t_fnum = PQfnumber(res, "t"); b_fnum = PQfnumber(res, "b"); @@ -8228,24 +7816,22 @@ show_binary_results(PGresult *res) int blen; int ival; - /* Get the field values (we ignore possibility they are null!) */ + /* 获取字段值(这里忽略它们可能为 null 的情况!) */ iptr = PQgetvalue(res, i, i_fnum); tptr = PQgetvalue(res, i, t_fnum); bptr = PQgetvalue(res, i, b_fnum); /* - * The binary representation of INT4 is in network byte order, which - * we'd better coerce to the local byte order. + * INT4 的二进制表示采用网络字节序,最好将其转换为本机字节序。 */ ival = ntohl(*((uint32_t *) iptr)); /* - * The binary representation of TEXT is, well, text, and since libpq - * was nice enough to append a zero byte to it, it'll work just fine - * as a C string. + * TEXT 的二进制表示就是文本,而 libpq 会在其后追加一个零字节, + * 因此可以直接将其用作 C 字符串。 * - * The binary representation of BYTEA is a bunch of bytes, which could - * include embedded nulls so we have to pay attention to field length. + * BYTEA 的二进制表示是一组字节,其中可能嵌有零字节, + * 因此必须注意字段长度。 */ blen = PQgetlength(res, i, b_fnum); @@ -8273,26 +7859,25 @@ main(int argc, char **argv) uint32_t binaryIntVal; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SET search_path = testlibpq3"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -8303,27 +7888,25 @@ main(int argc, char **argv) PQclear(res); /* - * The point of this program is to illustrate use of PQexecParams() with - * out-of-line parameters, as well as binary transmission of data. + * 此程序旨在演示如何使用 PQexecParams() 在 SQL 命令文本之外独立传递参数, + * 以及如何以二进制方式传输数据。 * - * This first example transmits the parameters as text, but receives the - * results in binary format. By using out-of-line parameters we can avoid - * a lot of tedious mucking about with quoting and escaping, even though - * the data is text. Notice how we don't have to do anything special with - * the quote mark in the parameter value. + * 第一个示例以文本形式传输参数,但以二进制格式接收结果。 + * 通过在 SQL 命令文本之外独立传递参数,即使数据是文本,也可以避免 + * 许多繁琐的引号和转义处理。注意,参数值中的引号无需任何特殊处理。 */ - /* Here is our out-of-line parameter value */ + /* 这是在 SQL 命令文本之外独立传递的参数值 */ paramValues[0] = "joe's place"; res = PQexecParams(conn, "SELECT * FROM test1 WHERE t = $1", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, - NULL, /* don't need param lengths since text */ - NULL, /* default to all text params */ - 1); /* ask for binary results */ + NULL, /* 文本参数无需指定长度 */ + NULL, /* 默认所有参数均为文本 */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -8337,31 +7920,29 @@ main(int argc, char **argv) PQclear(res); /* - * In this second example we transmit an integer parameter in binary form, - * and again retrieve the results in binary form. + * 第二个示例以二进制形式传输一个整数参数,并同样以二进制形式获取结果。 * - * Although we tell PQexecParams we are letting the backend deduce - * parameter type, we really force the decision by casting the parameter - * symbol in the query text. This is a good safety measure when sending - * binary parameters. + * 虽然我们告诉 PQexecParams 让后端推断参数类型,但实际上, + * 查询文本中的参数符号经过强制类型转换,因此其类型已经确定。 + * 发送二进制参数时,这是一项良好的安全措施。 */ - /* Convert integer value "2" to network byte order */ + /* 将整数值 "2" 转换为网络字节序 */ binaryIntVal = htonl((uint32_t) 2); - /* Set up parameter arrays for PQexecParams */ + /* 为 PQexecParams 设置参数数组 */ paramValues[0] = (char *) &binaryIntVal; paramLengths[0] = sizeof(binaryIntVal); - paramFormats[0] = 1; /* binary */ + paramFormats[0] = 1; /* 二进制 */ res = PQexecParams(conn, "SELECT * FROM test1 WHERE i = $1::int4", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, paramLengths, paramFormats, - 1); /* ask for binary results */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -8374,7 +7955,7 @@ main(int argc, char **argv) PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; diff --git a/zh/17/lobj.sgml b/zh/17/lobj.sgml index e7debfdb..b4d224c8 100644 --- a/zh/17/lobj.sgml +++ b/zh/17/lobj.sgml @@ -3,8 +3,8 @@ 大对象 - large object - BLOBlarge object + 大对象 + BLOB大对象 PostgreSQL提供一种大对象机制,允许以流式方式访问存储在专用大对象结构中的用户数据。在处理大到无法方便地整体操作的数据值时,这种流式访问非常有用。 @@ -19,7 +19,7 @@ TOAST - versus large objects + 与大对象对比 @@ -190,11 +190,11 @@ inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE); int lo_write(PGconn *conn, int fd, const char *buf, size_t len); - 将buf中的len字节(其大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 + 将buf中的len字节(缓冲区大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -211,7 +211,7 @@ int lo_read(PGconn *conn, int fd, char *buf, size_t len); - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -277,7 +277,7 @@ pg_int64 lo_tell64(PGconn *conn, int fd); int lo_truncate(PGconn *conn, int fd, size_t len); - 该函数把大对象描述符fd截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用空字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 + 该函数把大对象描述符fd对应的大对象截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用零字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。
@@ -426,16 +426,16 @@ CREATE TABLE image ( raster oid ); -SELECT lo_creat(-1); -- returns OID of new, empty large object +SELECT lo_creat(-1); -- 返回新建的空大对象的 OID -SELECT lo_create(43213); -- attempts to create large object with OID 43213 +SELECT lo_create(43213); -- 尝试创建 OID 为 43213 的大对象 -SELECT lo_unlink(173454); -- deletes large object with OID 173454 +SELECT lo_unlink(173454); -- 删除 OID 为 173454 的大对象 INSERT INTO image (name, raster) VALUES ('beautiful image', lo_import('/etc/motd')); -INSERT INTO image (name, raster) -- same as above, but specify OID to use +INSERT INTO image (name, raster) -- 与上例相同,但指定要使用的 OID VALUES ('beautiful image', lo_import('/etc/motd', 68583)); SELECT lo_export(image.raster, '/tmp/motd') FROM image @@ -444,7 +444,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image - 服务器端的lo_importlo_export函数与其客户端对应函数的行为差异很大。这两个函数在服务器的文件系统中读写文件,使用数据库所有者的权限。因此,默认情况下它们的使用仅限于超级用户。相比之下,客户端导入和导出函数在客户端的文件系统中读写文件,使用客户端程序的权限。客户端函数不需要任何数据库权限,除了读取或写入相关大对象所需的权限。 + 服务器端的lo_importlo_export函数与其客户端对应函数的行为差异很大。这两个函数在服务器的文件系统中读写文件,使用运行数据库服务器的操作系统用户的权限。因此,默认情况下它们的使用仅限于超级用户。相比之下,客户端导入和导出函数在客户端的文件系统中读写文件,使用客户端程序的权限。客户端函数不需要任何数据库权限,除了读取或写入相关大对象所需的权限。 @@ -463,7 +463,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image 示例程序 - 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行版的src/test/examples/testlo.c中找到。 + 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行包的src/test/examples/testlo.c中找到。 @@ -472,13 +472,13 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /*----------------------------------------------------------------- * * testlo.c - * test using large objects with libpq + * 测试使用 libpq 操作大对象 * * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group * Portions Copyright (c) 1994, Regents of the University of California * * - * IDENTIFICATION + * 标识 * src/test/examples/testlo.c * *----------------------------------------------------------------- @@ -498,7 +498,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /* * importFile - - * import file "in_filename" into database as large object "lobjOid" + * 将文件 "in_filename" 作为大对象 "lobjOid" 导入数据库 * */ static Oid @@ -512,16 +512,16 @@ importFile(PGconn *conn, char *filename) int fd; /* - * open the file to be read in + * 打开要读取的文件 */ fd = open(filename, O_RDONLY, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"\n", filename); } /* - * create the large object + * 创建大对象 */ lobjId = lo_creat(conn, INV_READ | INV_WRITE); if (lobjId == 0) @@ -530,7 +530,7 @@ importFile(PGconn *conn, char *filename) lobj_fd = lo_open(conn, lobjId, INV_WRITE); /* - * read in from the Unix file and write to the inversion file + * 从 Unix 文件读取数据并写入大对象 */ while ((nbytes = read(fd, buf, BUFSIZE)) > 0) { @@ -568,7 +568,7 @@ pickout(PGconn *conn, Oid lobjId, int start, int len) fprintf(stderr, ">>> %s", buf); nread += nbytes; if (nbytes <= 0) - break; /* no more data? */ + break; /* 没有更多数据? */ } free(buf); fprintf(stderr, "\n"); @@ -614,7 +614,7 @@ overwrite(PGconn *conn, Oid lobjId, int start, int len) /* * exportFile - - * export large object "lobjOid" to file "out_filename" + * 将大对象 "lobjOid" 导出到文件 "out_filename" * */ static void @@ -627,24 +627,24 @@ exportFile(PGconn *conn, Oid lobjId, char *filename) int fd; /* - * open the large object + * 打开大对象 */ lobj_fd = lo_open(conn, lobjId, INV_READ); if (lobj_fd < 0) fprintf(stderr, "cannot open large object %u", lobjId); /* - * open the file to be written to + * 打开要写入的文件 */ fd = open(filename, O_CREAT | O_WRONLY | O_TRUNC, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"", filename); } /* - * read in from the inversion file and write to the Unix file + * 从大对象读取数据并写入 Unix 文件 */ while ((nbytes = lo_read(conn, lobj_fd, buf, BUFSIZE)) > 0) { @@ -689,18 +689,18 @@ main(int argc, char **argv) out_filename = argv[3]; /* - * set up the connection + * 建立连接 */ conn = PQsetdb(NULL, NULL, NULL, NULL, database); - /* check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) diff --git a/zh/17/pgtrgm.sgml b/zh/17/pgtrgm.sgml index 09cc6fe5..fa60934c 100644 --- a/zh/17/pgtrgm.sgml +++ b/zh/17/pgtrgm.sgml @@ -513,11 +513,11 @@ SELECT * FROM test_trgm WHERE t ~ '(foo|bar)'; - 文本搜索集成 + 文本检索集成 与全文索引结合使用时,三字符组匹配是非常有用的工具。 - 尤其是,它有助于识别那些因拼写错误而无法被全文搜索机制直接匹配的输入词。 + 尤其是,它有助于识别那些因拼写错误而无法被全文检索机制直接匹配的输入词。 diff --git a/zh/17/protocol.sgml b/zh/17/protocol.sgml index f28ff9c9..1de61033 100644 --- a/zh/17/protocol.sgml +++ b/zh/17/protocol.sgml @@ -14,7 +14,7 @@ - 本文描述协议 3.0 版本,自 PostgreSQL 7.4 起实现。对早期协议版本的说明可参见之前发布的 PostgreSQL 文档。一台服务器可以支持多个协议版本。初始的启动请求消息会告知服务器客户端正在尝试使用哪个协议版本。如果客户端请求的主版本号不被服务器支持,连接将被拒绝(例如,如果客户端请求协议版本 4.0,在撰写本文时该版本尚不存在,就会发生这种情况)。如果客户端请求的次版本号不被服务器支持(如客户端请求 3.1 但服务器仅支持 3.0),服务器可能会拒绝连接,也可能会用一个 NegotiateProtocolVersion 消息进行响应,其中包含它所支持的最高次协议版本号。客户端可以选择使用指定的协议版本继续连接,也可以中止连接。 + 本文描述协议 3.0 版本,自 PostgreSQL 7.4 起实现。关于更早协议版本的说明,请参阅之前发布的 PostgreSQL 文档。一台服务器可以支持多个协议版本。初始启动请求消息会告知服务器客户端正尝试使用哪个协议版本。如果客户端请求的主版本号不被服务器支持,则连接会被拒绝(例如,如果客户端请求协议版本 4.0,而在本文编写时该版本并不存在,就会出现这种情况)。如果客户端请求的次版本号不被服务器支持(例如客户端请求 3.1,而服务器只支持 3.0),服务器可以拒绝连接,也可以返回一条 NegotiateProtocolVersion 消息,其中包含它所支持的最高次协议版本。客户端随后可以选择使用指定的协议版本继续连接,或者中止连接。 @@ -26,15 +26,15 @@ 概述 - 协议在启动和正常操作过程中有不同的阶段。在启动阶段里,前端打开一个到服务器的连接并且认证自身以满足服务器(这可能涉及到一条或多条消息,取决于使用的认证方法)。 如果一切正常,服务器就发送状态信息给前端,并最后进入正常操作。除了最初的启动请求消息之外,协议的这个部分是服务器驱动的。 + 协议分为启动和正常操作两个阶段。在启动阶段,前端打开到服务器的连接,并完成服务器所要求的认证。(这可能只涉及一条消息,也可能因所用认证方法不同而需要多条消息。)如果一切顺利,服务器随后会向前端发送状态信息,并最终进入正常操作。除最初的启动请求消息外,协议的这一部分由服务器驱动。 - 在正常操作中,前端发送查询和其它命令到后端,然后后端返回查询结果和其它响应。在少数几种情况(比如NOTIFY)中,后端会发送未被请求的消息,但这个会话中的绝大多部分都是由前端请求驱动的。 + 在正常操作中,前端向后端发送查询及其他命令,后端则返回查询结果和其他响应。少数情况下(例如 NOTIFY),后端会发送未请求的消息,但会话中的绝大多数交互仍由前端请求驱动。 - 会话的终止通常是由前端来选择的,但是也可以在某些情况下由后端强制执行。不管在那种情况下,如果后端关闭连接,那么它将在退出之前回滚所有打开的(未完成的)事务。 + 会话通常由前端选择终止,但在某些情况下也可能由后端强制终止。无论哪种情况,后端关闭连接时,都会在退出前回滚所有打开的(未完成的)事务。 @@ -73,9 +73,7 @@ 整个执行周期包括一个解析步骤,它从文本查询字符串创建预备语句; 一个绑定步骤,它根据预备语句和所需参数值创建 portal; - 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询 - (SELECTSHOW等),可以要求执行步骤只取回 - 有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 + 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询(SELECTSHOW等),可以要求执行步骤只取回有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 @@ -92,8 +90,8 @@ - 文本形式的数值是特定数据类型的输入/输出转换函数生成或接受的任何字符串。在传输形式上,字符串没有末尾空字符;如果前端要想把收到的值当作C字符串处理,那么必须自己加上一个(顺便说一下,文本格式不允许嵌入空字符)。 - + 值的文本表示是相应数据类型的输入/输出转换函数生成和接受的字符串。在传输形式中,值的末尾没有空字符;前端若要将收到的值作为 C 字符串处理,必须自行添加一个。(文本格式也不允许内嵌空字符。) + 整数的二进制表示采用网络字节序(最高有效字节在前)。至于其他数据类型,请查阅文档或源代码了解其二进制表示形式。要注意,复杂数据类型的二进制表示可能会在不同服务器版本之间发生变化;文本格式通常是可移植性更好的选择。 @@ -114,7 +112,7 @@ 启动 - 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,判断该连接在初步上是否可接受,以及是否需要额外的认证。 + 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,初步判断是否接受该连接,以及需要何种额外认证(如果需要)。 @@ -233,11 +231,8 @@ NegotiateProtocolVersion - 如果服务器不支持客户端请求的协议次版本,但支持更早的协议版本,就会发送该消息并指明其支持的最高次版本。如果客户端在启动包中请求了不受支持的协议选项(即以 _pq_. 开头),也会发送该消息。 - - - 在该消息之后,认证会继续使用服务器指明的协议版本。如果客户端不支持该较旧版本,就应立即关闭连接。如果服务器没有发送该消息,则表示它支持客户端请求的协议版本以及所有协议选项。 - + 服务器不支持客户端请求的协议次版本,但支持更早的协议版本;此消息指明其所支持的最高次版本。如果客户端在启动包中请求了不受支持的协议选项(即以 _pq_. 开头的选项),也会发送此消息。此消息后面会跟随一条 ErrorResponse 或一条指示认证成功或失败的消息。 + @@ -266,9 +261,7 @@ 该消息提供密钥数据。如果前端希望稍后发送取消请求,就必须保存这些数据。前端不应响应该消息,而应继续等待 ReadyForQuery 消息。 - - PostgreSQL 服务器总会发送该消息,但已知一些不支持查询取消的第三方后端实现不会发送。 - + @@ -359,7 +352,7 @@ 表示即将返回行作为对SELECTFETCH等查询的响应。 - 此消息的内容描述了行的列布局。这将跟随每个返回给前端的行的DataRow消息。 + 此消息的内容描述了行的列布局。该消息之后,每个返回给前端的行都对应一条 DataRow 消息。 @@ -415,9 +408,7 @@ - - 对 SELECT 查询(或其他返回行集的查询,如 EXPLAINSHOW)的响应,通常包含 RowDescription、零条或多条 DataRow 消息,以及最后的 CommandComplete。向前端 COPY 或从前端 COPY 会调用中描述的特殊协议。所有其他类型的查询通常只产生一条 CommandComplete 消息。 - + SELECT 查询(或其他返回行集的查询,如 EXPLAINSHOW)的响应通常包含 RowDescription、零条或多条 DataRow 消息,以及最后的 CommandComplete。在前端与服务器之间执行 COPY 输入或输出时,会使用 所述的特殊协议。所有其他类型的查询通常只产生一条 CommandComplete 消息。 由于查询字符串可能包含若干条查询(以分号分隔),因此在后端完成整个查询字符串的处理之前,可能会出现多个这样的响应序列。只有在整个字符串处理完毕且后端已准备好接受新的查询字符串时,才会发出 ReadyForQuery 消息。 @@ -440,15 +431,15 @@ - 我们建议的方法是把前端代码写成状态机的风格,它可以在任何时刻接受任何有意义的消息类型,而不是假设消息的序列总是准确。 - + 建议以状态机的方式编写前端,使其能够在任何合理的时机接收相应类型的消息,而不把消息确切顺序的假设写死在代码中。 + 一个简单查询中的多条语句 - 当一个简单查询消息中包含多于一条SQL语句(被分号分隔)时,那些语句会被当做一个事务中执行,除非其中包括显式事务控制命令来强制不同的行为。例如,如果消息包括 + 当一个简单查询消息中包含多于一条SQL语句(被分号分隔)时,这些语句会作为单个事务执行,除非其中包括显式事务控制命令来强制不同的行为。例如,如果消息包括 INSERT INTO mytable VALUES(1); SELECT 1/0; @@ -470,15 +461,15 @@ SELECT 1/0; - 这种行为通过在一个隐式事务块中的一个多语句Query消息中运行那些语句来实现,除非它们运行在某个显式事务块中。隐式事务块与常规事务块之间的区别在于隐式块会在Query消息结束时自动被关闭,或者是在没有错误的情况下由一个隐式提交关闭,或者是在有错误时由一个隐式的回滚关闭。这类似于一个语句自己执行(当不在事务块中时)时发生的隐式提交或回滚。 - + 这种行为的实现方式是:除非已有显式事务块可供这些语句执行,否则就在一个隐式事务块中执行多语句 Query 消息中的语句。隐式事务块与常规事务块的主要区别在于,隐式块会在 Query 消息结束时自动关闭:没有错误时隐式提交,发生错误时隐式回滚。这类似于单独执行一条语句(不在事务块中)时发生的隐式提交或回滚。 +
- 如果会话已经在一个事务块中,作为前面某个消息中BEGIN的结果,那么Query消息会简单地继续那个事务块,不管该消息包含一个语句还是多个语句。不过,如果该Query消息包含一个关闭现有事务块的COMMIT或者ROLLBACK,那么任何接下来的语句都会在一个隐式事务块中被执行。反过来,如果在多语句Query消息中出现一个BEGIN,那么它会开始一个常规事务块,这个常规事务块将只能被一个显式的COMMIT或者ROLLBACK终止,不管这两种命令是出现在这个Query消息还是后面的一个Query消息中。如果BEGIN跟在一些作为隐式事务块执行的语句后面,那些语句不会被立刻提交。实际上,它们会被包括到新的常规事务块中。 + 如果会话因前面某条消息中的BEGIN而已经处于事务块中,那么 Query 消息会继续该事务块,不管该消息包含一个语句还是多个语句。不过,如果该Query消息包含一个关闭现有事务块的COMMIT或者ROLLBACK,那么任何接下来的语句都会在一个隐式事务块中被执行。反过来,如果在多语句Query消息中出现一个BEGIN,那么它会开始一个常规事务块,这个常规事务块将只能被一个显式的COMMIT或者ROLLBACK终止,不管这两种命令是出现在这个Query消息还是后面的一个Query消息中。如果BEGIN跟在一些作为隐式事务块执行的语句后面,那些语句不会被立刻提交。实际上,它们会被包括到新的常规事务块中。 - 出现在一个隐式事务块中的COMMIT或者ROLLBACK会被正常执行并且关闭该隐式块。不过,由于没有先前的BEGIN配对的COMMIT或者ROLLBACK表示一种错误,所以将会发出一个警告。如果后面还有更多语句,将会为它们开始一个新的隐式事务块。 + 出现在一个隐式事务块中的COMMIT或者ROLLBACK会被正常执行并且关闭该隐式块。不过,由于没有先前的BEGIN配对的COMMIT或者ROLLBACK可能表示误操作,所以会发出警告。如果后面还有更多语句,将会为它们开始一个新的隐式事务块。 @@ -486,17 +477,17 @@ SELECT 1/0; - 记住,不管任何事务控制命令存不存在,Query消息的执行会在第一个错误时停止。因此,对于下面的在一个Query消息中的示例 + 请记住,无论消息中是否包含事务控制命令,Query 消息的执行都会在第一个错误处停止。例如,单条 Query 消息包含以下内容时: BEGIN; SELECT 1/0; ROLLBACK; - 会话中将留下一个失败的常规事务块,因为在出现除零错误后不会到达ROLLBACK。将需要另一个ROLLBACK把会话恢复到一种可用的状态。 - +会话会停留在失败的常规事务块内,因为发生除零错误后不会再执行ROLLBACK。需要另发一条ROLLBACK,才能将会话恢复到可用状态。 + - 另一种要注意的行为是,最初的词法和语法分析是在整个查询字符串被执行之前进行的。因此后面的语句中的简单错误(例如拼写错误的关键词)可能会阻止任何语句的执行。这通常对用户是不可见的,因为在当作一个隐式事务块执行时,这些语句不管怎样都会全部被回滚。不过,在尝试于一个多语句Query中执行多个事务时,这种现象可能是可见的。例如,如果一个拼写错误把我们之前的示例变成 + 另一种要注意的行为是,在执行任何语句之前,会先对整个查询字符串进行词法和语法分析。因此后面的语句中的简单错误(例如拼写错误的关键词)可能会阻止任何语句的执行。这通常对用户是不可见的,因为在当作一个隐式事务块执行时,这些语句不管怎样都会全部被回滚。不过,在尝试于一个多语句Query中执行多个事务时,这种现象可能是可见的。例如,如果一个拼写错误把我们之前的示例变成 BEGIN; INSERT INTO mytable VALUES(1); @@ -563,11 +554,11 @@ SELCT 1/0; - 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是执行不会导致后端发送 ReadyForQuery 或 RowDescription。 + 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是 Execute 不会导致后端发送 ReadyForQuery 或 RowDescription。 - 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息之一结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 + 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息中的恰好一条结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 @@ -582,7 +573,7 @@ SELCT 1/0; - 除了这些基本的、必须的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 + 除了这些基本的、必需的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 @@ -618,38 +609,32 @@ SELCT 1/0; - 流水线处理 + 管道化 - 流水线处理 + 管道化 协议规范 - 使用扩展查询协议允许流水线处理,这意味着发送一系列查询而无需等待先前的查询完成。 - 这减少了完成一系列操作所需的网络往返次数。然而,用户必须仔细考虑所需的行为,如果其中一步失败, - 因为后续查询已经在传输到服务器的过程中。 - + 扩展查询协议允许管道化,即连续发送一系列查询,而不等待先前查询完成。这减少了完成一组操作所需的网络往返次数。不过,用户必须仔细考虑其中某个步骤失败时所需的行为,因为后续查询已经在发往服务器的途中。 + - 处理这个问题的一种方法是将整个查询系列作为一个事务处理,即将其包装在BEGIN... - COMMIT中。然而,如果希望其中一些命令独立于其他命令提交,这并没有帮助。 - + 处理这个问题的一种方式是让整组查询成为单个事务,即用BEGIN ... COMMIT包围它们。不过,如果希望其中某些命令独立于其他命令提交,这种方式就无法满足要求。 + - 扩展查询协议提供了另一种管理这个问题的方式,即在依赖的步骤之间省略发送同步消息。 - 由于在错误后,后端会跳过命令消息直到找到同步消息,这允许在管道中的后续命令在前面的命令失败时自动跳过,而无需客户端明确地使用BEGINCOMMIT来管理。 - 管道中可以通过同步消息分隔独立可提交的段。 - + 扩展查询协议提供了另一种处理方式,即省略相互依赖的步骤之间的 Sync 消息。发生错误后,后端会跳过命令消息,直到遇到 Sync,因此当前面的命令失败时,管道中的后续命令便会自动跳过,而不必由客户端用BEGINCOMMIT显式管理。管道中可独立提交的各段可以用 Sync 消息分隔。 + - 如果客户端没有发出显式 BEGIN,则会启动一个隐式事务块。每个 Sync 通常会在前序步骤成功时导致隐式 COMMIT,失败时导致隐式 ROLLBACK。服务器只有在第一个命令结束且尚未收到 Sync 时,才能识别这种隐式事务块。有一些 DDL 命令(例如 CREATE DATABASE)不能在事务块内执行;若这类命令在管道中执行,除非它是某个 Sync 之后的第一条命令,否则会失败。此外,它成功后会强制立即提交以保持数据库一致性。因此,紧随这些命令之后的 Sync 除了返回 ReadyForQuery 外不会产生额外效果。 - + 如果客户端没有发出显式的BEGIN,那么每个 Sync 通常会在前序步骤成功时引发隐式的COMMIT,失败时引发隐式的ROLLBACK。不过,少数 DDL 命令(例如CREATE DATABASE)不能在事务块中执行。如果这类命令在管道中执行,除非它是管道中的第一条命令,否则会失败。此外,它成功后会强制立即提交,以保持数据库一致性。因此,紧随这类命令之后的 Sync 除了返回 ReadyForQuery 外,不产生其他效果。 + - 当使用这种方法时,必须通过计算ReadyForQuery消息的数量并等待达到发送的Syncs数量来确定管道的完成。 - 计算命令完成响应是不可靠的,因为其中一些命令可能会被跳过,因此不会产生完成消息。 - + 使用这种方式时,必须统计 ReadyForQuery 消息的数量,并等待该数量达到已发送的 Sync 消息数量,才能确定管道已完成。统计命令完成响应并不可靠,因为某些命令可能被跳过,因而不会产生完成消息。 + @@ -657,8 +642,8 @@ SELCT 1/0; 函数调用 - 函数调用子协议允许客户端请求一个对存在于数据库pg_proc系统表中的任意函数的直接调用。客户端必须在该函数上有执行的权限。 - + 函数调用子协议允许客户端请求直接调用数据库pg_proc系统目录中的任意函数。客户端必须具有该函数的执行权限。 + @@ -668,8 +653,8 @@ SELCT 1/0; - 一个函数调用周期是由前端向后端发送一条FunctionCall消息初始化的。然后后端根据函数调用的结果发送一条或者更多响应消息,并且最后是一条ReadyForQuery响应消息。ReadyForQuery通知前端它可以安全地发送一个新的查询或者函数调用了。 - + 函数调用周期由前端向后端发送一条 FunctionCall 消息来启动。后端随后根据函数调用的结果发送一条或多条响应消息,最后发送一条 ReadyForQuery 响应消息。ReadyForQuery 告知前端,可以安全地发送新的查询或函数调用。 + 来自后端的可能的响应消息是: @@ -688,7 +673,7 @@ SELCT 1/0; FunctionCallResponse - 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者集合类型的结果)。 + 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者结果集合)。 @@ -723,7 +708,7 @@ SELCT 1/0; - 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(表示成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 + 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(允许成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 @@ -731,11 +716,11 @@ SELCT 1/0; - 在拷贝入模式下,后端将忽略所收到的Flush和Sync消息。收到任何其他非拷贝消息类型都会造成一个错误,它将导致上面所描述的拷贝入状态中断(Flush和Sync的例外是为了方便客户端库,它们总是在一个Execute消息之后发送Flush和Sync,而不检查被执行的命令是否为一个COPY FROM STDIN)。 - + 后端会忽略在拷贝入模式期间收到的 Flush 和 Sync 消息。收到任何其他非拷贝类型的消息都会构成错误,并按上述方式中止拷贝入状态。(Flush 和 Sync 的例外是为了方便那些总是在 Execute 消息之后发送 Flush 或 Sync、而不检查待执行命令是否为COPY FROM STDIN的客户端库。) + - 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句的时候初始化的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能退出传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 + 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句时启动的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能中止传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 @@ -743,16 +728,16 @@ SELCT 1/0; - 在CopyData消息中间可能会散布有NoticeResponse和ParameterStatus消息。前端必须处理这些情况,并且应该也为异步消息类型(参见)准备好。否则任何除CopyData或CopyDone之外的消息类型都会被认为是要中止拷贝出模式。 - + NoticeResponse 和 ParameterStatus 消息可能穿插在 CopyData 消息之间;前端必须处理这些情况,并应准备好处理其他异步消息类型(参见)。除此之外,可以将任何除 CopyData 或 CopyDone 以外的消息类型视为拷贝出模式的终止标志。 + - 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许数据以高速批量方式在客户端与服务器之间双向传输。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见。 + 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许高速批量地向服务器发送数据以及从服务器接收数据。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见 - CopyInResponse、CopyOutResponse和CopyBothResponse消息包括域和格式代码,域告诉前端每行的列数,而格式代码则用于具体每个列(就目前的实现而言,一个给定COPY操作中的所有列都将使用同样的格式,但是消息设计并不做这个假设)。 - + CopyInResponse、CopyOutResponse 和 CopyBothResponse 消息包含一些字段,用于告知前端每行的列数以及每列所使用的格式代码。(在当前实现中,同一次COPY操作的所有列都使用相同格式,但消息设计并不作此假设。) + @@ -795,8 +780,8 @@ SELCT 1/0; - 如果前端发出一个LISTEN命令, 那么无论何时在为同一个通道名NOTIFY时,后端将发送一个NotificationResponse消息(不要和NoticeResponse搞混!)。 - + 如果前端发出LISTEN命令,那么每当针对同一通道名执行NOTIFY命令时,后端都会发送一条 NotificationResponse 消息(不要与 NoticeResponse 混淆)。 + @@ -815,11 +800,11 @@ SELCT 1/0; - 要发出一条取消请求,前端打开一个与服务器的新连接并且发送一条CancelRequest消息, 而不是通常在新连接中经常发送的StartupMessage消息。服务器将处理这个请求然后关闭连接。 出于安全原因,对取消请求消息不做直接的响应。 - + 要发出取消请求,前端会新建到服务器的连接,并发送 CancelRequest 消息,而不是新连接通常发送的 StartupMessage 消息。服务器处理该请求后便会关闭连接。出于安全原因,服务器不会直接回复取消请求消息。 + - 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的关键数据(PID和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则退出当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 + 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的密钥数据(PID 和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则中止当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 @@ -827,7 +812,7 @@ SELCT 1/0; - 这么做是对安全性和有效性通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 + 这么做是对安全性和效率通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 @@ -848,11 +833,11 @@ SELCT 1/0; - 其他终止场景来自各种故障,例如任一端发生内核转储、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 + 其他终止场景来自各种故障,例如任一端发生 core dump、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 - 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果很可能在得知断开之前被提交。 + 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果可能在发现连接断开之前被提交。 @@ -866,32 +851,32 @@ SELCT 1/0; 要发起一条使用SSL加密的连接,前端首先发送 SSLRequest 消息,而不是 StartupMessage。随后服务器会响应一个包含SN的单字节,分别表示它愿意或不愿意执行SSL加密。如果前端对该响应不满意,此时可以关闭连接。若要在收到S后继续,就先与服务器完成SSL启动握手(这里不做描述,它属于SSL规范的一部分)。如果成功,再继续发送通常的 StartupMessage。在这种情况下,StartupMessage 以及后续所有数据都会被SSL加密。若要在收到N后继续,则发送通常的 StartupMessage,并在不使用加密的情况下继续。 - (另外,可以在 N 响应之后发出 GSSENCRequest 消息,尝试使用 GSSAPI 加密代替 SSL。) + (另外,可以在 N 响应之后发出 GSSENCRequest 消息,尝试使用 GSSAPI 加密代替 SSL。) - 前端也应准备处理服务器对 SSLRequest 返回的 ErrorMessage。前端不应将该错误直接展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 SSL 的情况下继续。 + 前端也应准备处理服务器对 SSLRequest 返回的 ErrorMessage。前端不应将该错误展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 SSL 的情况下继续。 - 当可以执行 SSL 加密时,服务器预计仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给他们的 SSL 库,要么在发现他们已经读取到额外的字节时将其视为协议违规。 + 当可以执行 SSL 加密时,服务器应仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给所用的 SSL 库,要么在发现已经读取到额外的字节时将其视为协议违规。 - 同样,服务器也期望客户端在收到服务器对 SSLRequest 的单字节响应之后,再开始SSL协商。如果客户端不等服务器响应到达就立即开始SSL协商,可以减少一次网络往返时延;但代价是无法处理服务器对SSL请求返回否定响应的情况。在这种情况下,服务器通常会直接断开连接,而不会继续回退到 GSSAPI、未加密连接或协议错误流程。 + 同样,服务器也期望客户端在收到服务器对SSL请求的单字节响应之后,再开始SSL协商。如果客户端不等服务器响应到达就立即开始SSL协商,可以减少一次网络往返时延;但代价是无法处理服务器对SSL请求返回否定响应的情况。在这种情况下,服务器会直接断开连接,而不会继续使用 GSSAPI 或未加密连接,也不会返回协议错误。 - 初始 SSLRequest 也可以用于那些正在建立、目的是发送 CancelRequest 消息的连接。 - + 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 SSLRequest。 + - 还支持第二种发起SSL加密的方式:客户端可以在不发送任何 SSLRequest 包的情况下,直接开始SSL协商。SSL连接建立后,服务器会在加密通道上继续等待普通的启动请求包并继续协商。在这种情况下,任何其他的加密请求都会被拒绝。这种方法不适合通用工具,因为它既不能协商出最佳的连接加密方式,也不能处理未加密连接;但在客户端和服务器都由同一方控制的环境中,它很有用,因为它可以减少一次往返时延,并允许使用依赖标准SSL连接的网络工具。使用这种风格的SSL连接时,客户端必须使用由 RFC 7301 定义的 ALPN 扩展,以防范协议混淆攻击。PostgreSQL 协议对应的 ALPN 标识是 postgresql,见 IANA TLS ALPN Protocol IDs 注册表。 + 还支持第二种发起SSL加密的方式:服务器能识别未发送任何 SSLRequest 包就立即开始SSL协商的连接。SSL连接建立后,服务器会在加密通道上继续等待普通的启动请求包并继续协商。在这种情况下,任何其他的加密请求都会被拒绝。这种方法不是通用工具的首选,因为它既不能协商出最佳的连接加密方式,也不能处理未加密连接;但在客户端和服务器都由同一方控制的环境中,它很有用,因为它可以减少一次往返时延,并允许使用依赖标准SSL连接的网络工具。使用这种风格的SSL连接时,客户端必须使用由 RFC 7301 定义的 ALPN 扩展,以防范协议混淆攻击。PostgreSQL 协议对应的 ALPN 标识是 postgresql,见 IANA TLS ALPN Protocol IDs 注册表。 - 虽然协议本身并不提供让服务器强制启用SSL加密的方法,但管理员可以把服务器配置为拒绝未加密会话,把它作为认证检查的一个副作用。 - + 虽然协议本身没有提供让服务器强制使用SSL加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + @@ -902,37 +887,27 @@ SELCT 1/0; 如果PostgreSQL构建时启用了GSSAPI支持,就可以使用GSSAPI对前端/后端通信进行加密。这为攻击者可能截获会话流量的环境提供了通信安全性。有关使用GSSAPI加密PostgreSQL会话的详细信息,请参阅。 - - 要启动一个GSSAPI加密连接,前端最初发送一个GSSENCRequest消息,而不是一个StartupMessage。 - 服务器随后会响应一个包含GN的单个字节,分别表示愿意或不愿意执行GSSAPI加密。 - 如果前端对响应不满意,可能会在此时关闭连接。 - 要在G之后继续,使用GSSAPI C绑定,如在RFC 2744 - 中讨论的,或等效的,通过在循环中调用gss_init_sec_context()来执行GSSAPI初始化, - 并将结果发送给服务器,从一个空输入开始,然后对每个来自服务器的结果进行处理,直到不再返回输出为止。 - 在将gss_init_sec_context()的结果发送给服务器时,在消息前加上以网络字节顺序表示的四字节整数的长度。 - 要在N之后继续,发送通常的StartupMessage,并在没有加密的情况下继续进行。 - (或者,可以在N响应后发出一个SSLRequest消息,尝试使用SSL加密代替GSSAPI。) - + 要建立 GSSAPI 加密连接,前端首先发送 GSSENCRequest 消息,而不是 StartupMessage。服务器随后以单个字节响应,内容为 GN,分别表示愿意或不愿意使用 GSSAPI 加密。如果前端对响应不满意,可以在此时关闭连接。收到 G 后要继续,应使用 RFC 2744 中介绍的 GSSAPI C 绑定或等效接口,在循环中调用 gss_init_sec_context() 来执行 GSSAPI 初始化,并将结果发送给服务器:先使用空输入,再依次使用服务器返回的每个结果,直到该调用不再产生输出。将 gss_init_sec_context() 的结果发送给服务器时,应在前面加上消息长度,以网络字节序的四字节整数表示。收到 N 后要继续,则发送通常的 StartupMessage,以不加密的方式继续。(也允许在收到 N 响应后发送 SSLRequest 消息,尝试使用 SSL 加密代替 GSSAPI。) - 前端也应准备处理服务器对 GSSENCRequest 返回的 ErrorMessage。前端不应将该错误直接展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 GSSAPI 加密的情况下继续。 + 前端也应准备处理服务器对 GSSENCRequest 返回的 ErrorMessage。前端不应将该错误展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 GSSAPI 加密的情况下继续。 - 当GSSAPI加密可用时,服务器预计只发送单个G字节,然后等待前端启动GSSAPI握手。此时如果还有其他可读字节,很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应编写代码,要么从套接字中恰好读取一个字节后再把套接字交给其 GSSAPI 库,要么在发现自己已经读到额外字节时将其视为协议违规。 + 当GSSAPI加密可用时,服务器应只发送单个G字节,然后等待前端启动GSSAPI握手。此时如果还有其他可读字节,很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应编写代码,要么从套接字中恰好读取一个字节后再把套接字交给其 GSSAPI 库,要么在发现自己已经读到额外字节时将其视为协议违规。 - 初始 GSSENCRequest 也可用于那些正在建立、目的是发送 CancelRequest 消息的连接。 - + 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 GSSENCRequest。 + 一旦成功建立GSSAPI加密连接,就应使用gss_wrap()加密通常的 StartupMessage 以及后续所有数据,并在实际加密负载前附上gss_wrap()结果长度,该长度以网络字节序的四字节整数表示。请注意,服务器只接受来自客户端、长度小于 16kB 的加密数据包。客户端应使用gss_wrap_size_limit()确定符合该限制的未加密消息大小,较大的消息则应拆分为多次gss_wrap()调用。典型分段是 8kB 的未加密数据,对应得到略大于 8kB 但明显小于 16kB 的加密数据包。通常可以认为,服务器不会向客户端发送大于 16kB 的加密数据包。 - 虽然协议本身并不为服务器提供强制启用GSSAPI加密的方法,但管理员可以把服务器配置为拒绝未加密会话,把它作为认证检查的一个副作用。 - + 虽然协议本身没有提供让服务器强制使用GSSAPI加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + @@ -940,9 +915,7 @@ SELCT 1/0; SASL认证 - - SASL是面向连接协议中的认证框架。目前,PostgreSQL实现了两种 SASL 机制:SCRAM-SHA-256 和 SCRAM-SHA-256-PLUS。未来可能继续增加。下面的步骤说明 SASL 认证的一般流程,后续小节将介绍具体机制细节。 - + SASL 是面向连接协议中的认证框架。目前,PostgreSQL 实现了两种 SASL 认证机制:SCRAM-SHA-256 和 SCRAM-SHA-256-PLUS。将来可能增加更多机制。以下步骤说明 SASL 认证的一般流程,下一小节则详细介绍 SCRAM-SHA-256 和 SCRAM-SHA-256-PLUS。 @@ -958,25 +931,22 @@ SELCT 1/0; - 客户端从列表中选择一个支持的机制,并向服务器发送一个SASLInitialResponse消息。 - 该消息包括所选机制的名称,以及如果所选机制使用的话,还包括一个可选的初始客户端响应。 - + 客户端从列表中选择一种受支持的机制,并向服务器发送 SASLInitialResponse 消息。消息包含所选机制的名称;如果该机制使用初始客户端响应,消息还可以包含这一可选响应。 + - 一个或多个服务器挑战和客户端响应消息将随后而来。每个服务器挑战都是在一个 - AuthenticationSASLContinue 消息中发送的,随后是客户端在一个 SASLResponse - 消息中的响应。这些消息的具体内容是特定于机制的。 - + 随后会进行一轮或多轮服务器挑战和客户端响应。每次服务器挑战都通过 AuthenticationSASLContinue 消息发送,随后客户端通过 SASLResponse 消息响应。消息的具体内容取决于所用机制。 + - 最后,当认证交换成功完成时,服务器会发送可选的 AuthenticationSASLFinal 消息,随后立即发送 AuthenticationOk。AuthenticationSASLFinal 包含机制特定的附加数据;若该机制不需要完成时附加数据,则不会发送 AuthenticationSASLFinal。 - + 最后,认证交换成功完成时,服务器会发送 AuthenticationSASLFinal 消息,紧接着发送 AuthenticationOk 消息。AuthenticationSASLFinal 包含从服务器发给客户端的附加数据,其具体内容取决于所选认证机制。如果该认证机制不使用在完成时发送的附加数据,则不会发送 AuthenticationSASLFinal 消息。 + @@ -988,12 +958,7 @@ SELCT 1/0; SCRAM-SHA-256认证 - - SCRAM-SHA-256 及其带通道绑定的变体 - SCRAM-SHA-256-PLUS 是基于密码的认证机制。它们在 - RFC 7677 - 和RFC 5802中有详细描述。 - + 目前实现的 SASL 机制是 SCRAM-SHA-256 及其带通道绑定的变体 SCRAM-SHA-256-PLUSRFC 7677RFC 5802 对它们有详细描述。 当在PostgreSQL中使用SCRAM-SHA-256时,服务器将忽略客户端在client-first-message中发送的用户名。 @@ -1002,31 +967,22 @@ SELCT 1/0; - SCRAM规范规定密码也必须是UTF-8编码,并且使用SASLprep算法处理。 - 然而,PostgreSQL不要求密码必须使用UTF-8编码。 - 当用户设置密码时,无论实际使用的编码是什么,都会像使用UTF-8一样使用SASLprep进行处理。 - 但是,如果密码不是合法的UTF-8字节序列,或者包含SASLprep算法禁止的UTF-8字节序列, - 则会使用原始密码而不进行SASLprep处理,而不是抛出错误。这样可以在密码为UTF-8时对其进行规范化, - 但仍允许使用非UTF-8密码,并且不需要系统知道密码使用的编码方式。 - + SCRAM 规范规定密码也必须采用 UTF-8 编码,并通过SASLprep算法处理。不过,PostgreSQL并不要求密码使用 UTF-8。设置用户密码时,无论实际采用何种编码,都会将其视作 UTF-8 并用 SASLprep 处理。但是,如果密码不是合法的 UTF-8 字节序列,或者包含 SASLprep 算法禁止的 UTF-8 字节序列,就会直接使用未经 SASLprep 处理的原始密码,而不抛出错误。这样既能对 UTF-8 密码进行规范化,又允许使用非 UTF-8 密码,而且不要求系统知道密码采用何种编码。 + - Channel binding在支持SSL的PostgreSQL构建中受支持。带有通道绑定的SCRAM的SASL机制名称是 + 通道绑定在支持SSL的PostgreSQL构建中受支持。带有通道绑定的SCRAM的SASL机制名称是 SCRAM-SHA-256-PLUS。PostgreSQL使用的通道绑定类型是 tls-server-end-point - 在没有通道绑定的SCRAM中,服务器选择一个随机数, - 传输给客户端,与用户提供的密码在传输的密码哈希中混合。虽然这可以 - 防止密码哈希在后续会话中被成功重新传输,但无法阻止真实服务器和客 - 户端之间的虚假服务器通过服务器的随机值并成功进行认证。 - + 在不带通道绑定的SCRAM中,服务器会选择一个随机数并发送给客户端,将它与用户提供的密码混合,形成所传输的密码 hash。虽然这样可以防止在后续会话中成功重放该密码 hash,但无法阻止位于真实服务器与客户端之间的伪造服务器转发服务器的随机值并成功通过认证。 + - SCRAM与通道绑定一起防止这种中间人攻击,通过将服务器证书的签名混合到传输的密码哈希中。 - 虽然伪造服务器可以重新传输真实服务器的证书,但它无法访问与该证书匹配的私钥,因此无法证明自己是所有者,导致SSL连接失败。 - + 带通道绑定的SCRAM会将服务器证书的签名混入所传输的密码 hash,从而防止此类中间人攻击。虽然伪造服务器可以转发真实服务器的证书,但它无法取得与证书匹配的私钥,因此无法证明自己是证书所有者,最终导致 SSL 连接失败。 + @@ -1098,16 +1054,15 @@ SELCT 1/0; - 为了测试复制命令,可以通过psql或任何其他使用连接字符串且包含replication选项的libpq工具建立复制连接, - 例如: + 为了测试复制命令,可以通过 psql 或其他使用 libpq 的工具建立复制连接,连接字符串中应包含 replication 选项,例如: psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 然而,更常用的是使用(用于物理复制)或(用于逻辑复制)。 - +不过,通常更有用的做法是使用 (用于物理复制)或 (用于逻辑复制)。 + - 复制命令在服务器日志中记录,当启用时。 + 启用 后,复制命令会记录到服务器日志中。 @@ -1117,7 +1072,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" IDENTIFY_SYSTEM - 识别系统 + IDENTIFY_SYSTEM @@ -1153,9 +1108,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" xlogpos (text) - - 当前 WAL 刷新位置。用于获得预写式日志中的一个已知位置,以便从该处开始流式传输。 - + 当前 WAL 刷盘位置。可用于获取预写式日志中一个已知的位置,以便从该处开始流式传输。 @@ -1207,10 +1160,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 请求服务器发送时间线历史文件以获取时间线tli。 - 服务器回复一行结果集,包含两个字段。虽然这些字段被标记为text, - 但它们实际上返回原始字节,没有编码转换: - + 请求服务器发送时间线 tli 的历史文件。服务器返回一个包含两个字段的单行结果集。虽然这些字段标记为 text,但实际返回的是原始字节,不进行编码转换: + @@ -1290,12 +1241,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果为 true,则该逻辑复制槽支持两阶段提交的解码。使用此选项后,与两阶段提交相关的命令,如 - PREPARE TRANSACTIONCOMMIT PREPARED - 和ROLLBACK PREPARED将被解码和传输。 - 事务将在PREPARE TRANSACTION时解码和传输。 - 默认值为false。 - + 如果为 true,则该逻辑复制槽支持对两阶段提交进行解码。使用此选项后,PREPARE TRANSACTIONCOMMIT PREPAREDROLLBACK PREPARED 等两阶段提交命令会被解码并传输。事务会在 PREPARE TRANSACTION 时解码并传输。默认值为 false。 + @@ -1304,10 +1251,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果为 true,则该物理复制槽会立即保留WAL。 - 否则,WAL仅在从流复制客户端连接时保留。 - 默认值为false。 - + 如果为 true,则该物理复制槽会立即保留 WAL。否则,只有在流复制客户端连接时才会保留 WAL。默认值为 false。 + @@ -1391,8 +1336,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 修改复制槽定义。参见 。当前仅支持逻辑复制槽。 - + 修改复制槽的定义。有关复制槽的更多信息,参见 。此命令目前仅支持逻辑复制槽。 + slot_name @@ -1404,23 +1349,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 支持以下选项: - - - TWO_PHASE [ boolean ] - - - 若为 true,则该逻辑复制槽支持两阶段提交解码。与两阶段提交相关的命令(如 PREPARE TRANSACTIONCOMMIT PREPAREDROLLBACK PREPARED)会被解码并发送;事务在 PREPARE TRANSACTION 时解码并发送。 - - - - + FAILOVER [ boolean ] - 若为 true,则该复制槽会同步到备库,从而在故障切换后恢复逻辑复制。 - + 如果为 true,则允许该复制槽同步到备库,以便在故障切换后恢复逻辑复制。 + @@ -1431,14 +1367,13 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" READ_REPLICATION_SLOT slot_name - 读取复制槽 + READ_REPLICATION_SLOT - 读取与复制槽相关的一些信息。如果复制槽不存在,则返回一个包含NULL值的元组。 - 当前仅支持物理复制槽的此命令。 - + 读取与复制槽关联的一些信息。如果复制槽不存在,则返回包含 NULL 值的元组。此命令目前仅支持物理复制槽。 + 在响应此命令时,服务器将返回一个包含以下字段的单行结果集: @@ -1465,8 +1400,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" restart_tliint8 - 与restart_lsn相关联的时间线ID,遵循当前时间线历史。 - + 根据当前时间线的历史,与 restart_lsn 对应的时间线 ID。 + @@ -1478,35 +1413,29 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" START_REPLICATION [ SLOT slot_name ] [ PHYSICAL ] XXX/XXX [ TIMELINE tli ] - 开始复制 + START_REPLICATION - 指示服务器开始流式传输WAL,从WAL位置XXX/XXX开始。 - 如果指定了TIMELINE选项,则流式传输将从时间线tli开始; - 否则,将选择服务器当前的时间线。如果请求的WAL部分已经被回收,服务器可能会回复错误。 - 成功时,服务器将用CopyBothResponse消息回复,然后开始向前端流式传输WAL。 - + 指示服务器从 WAL 位置 XXX/XXX 开始流式传输 WAL。如果指定了 TIMELINE 选项,则从时间线 tli 开始传输;否则选择服务器当前的时间线。服务器可以返回错误,例如请求的 WAL 部分已被回收时。成功时,服务器返回 CopyBothResponse 消息,然后开始向前端流式传输 WAL。 + - 如果通过slot_name提供了复制槽名称, - 那么在复制进行期间会更新该复制槽,以便服务器知道哪些 WAL 段, - 以及在启用了 hot_standby_feedback 时,哪些事务 - 仍然被备库所需要。 - + 如果通过 slot_name 提供了复制槽名称,该复制槽会随着复制的进行而更新,使服务器知道备库仍需要哪些 WAL 段,以及在启用 hot_standby_feedback 时仍需要哪些事务。 + - 如果客户端请求的 timeline 不是最新的,但属于服务器历史的一部分,服务器会从请求的起点开始流式传输该 timeline 上的全部 WAL,直到服务器切换到另一个 timeline 的位置为止。如果客户端请求的位置正好是旧 timeline 的末尾,服务器将完全跳过 COPY 模式。 - + 如果客户端请求的时间线不是最新时间线,但属于服务器的历史,服务器会从请求的起点开始,流式传输该时间线上的所有 WAL,直到服务器切换到另一条时间线的位置。如果客户端请求的流式传输起点恰好位于旧时间线的末尾,服务器会完全跳过 COPY 模式。 + 在非最新时间线上流式传输完全部 WAL 后,服务器会通过退出 COPY 模式来结束流式传输。当客户端也通过退出 COPY 模式来确认时,服务器会发送一个包含一行两列的结果集,指示该服务器历史中的下一条时间线。第一列是下一条时间线的 ID(类型为 int8),第二列是发生切换的 WAL 位置(类型为 text)。通常,切换位置就是所流式传输 WAL 的末尾,但也存在一些边界情况,服务器可能会先发送一些自己在提升前尚未重放的旧时间线 WAL。最后,服务器会发送两个 CommandComplete 消息(一个结束 CopyData,另一个结束 START_REPLICATION 本身),然后准备接受新的命令。 - WAL 数据会作为一系列 CopyData 消息发送;详见 。(这使其他信息可与之交错发送;特别是服务器在开始流式传输后若遇到失败,仍可发送 ErrorResponse。)从服务器到客户端的每个 CopyData 消息负载都属于以下格式之一: - + WAL 数据通过一系列 CopyData 消息发送,详见 。(这样可以混合发送其他信息;尤其是服务器在开始流式传输后遇到故障时,可以发送 ErrorResponse 消息。)服务器发给客户端的每条 CopyData 消息,其有效载荷都包含一条具有下列格式之一的消息: + @@ -1519,9 +1448,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('w') - - 将消息标识为WAL数据。 - + 将该消息标识为 WAL 数据。 @@ -1530,9 +1457,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 该消息中 WAL 数据的起始点。 - + 本消息中 WAL 数据的起始位置。 @@ -1541,9 +1466,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 服务器上当前的WAL结束位置。 - + 服务器上当前的 WAL 末尾位置。 @@ -1552,9 +1475,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 传输时服务器的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时服务器的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1563,15 +1484,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byten - - WAL数据流的一个部分。 - + WAL 数据流的一个片段。 - - 单个 WAL 记录绝不会拆分为两个 XLogData 消息。 - 当 WAL 记录跨越 WAL 页面边界,并因此已使用连续记录进行拆分时,它可以在页面边界处进行拆分。 - 换句话说,第一个主 WAL 记录及其连续记录可以在不同的 XLogData 消息中发送。 - + 单条 WAL 记录绝不会被拆分到两条 XLogData 消息中。当 WAL 记录跨越 WAL 页边界,因而已经通过续接记录拆分时,可以在页边界处分开发送。换句话说,最初的主 WAL 记录及其续接记录可以在不同的 XLogData 消息中发送。 @@ -1580,7 +1495,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 主库 keepalive 消息 (B) + 主库保活消息 (B) @@ -1588,9 +1503,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('k') - - 将该消息标识为发送方 keepalive。 - + 将该消息标识为发送端保活消息。 @@ -1599,9 +1512,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 服务器上当前的WAL结束位置。 - + 服务器上当前的 WAL 末尾位置。 @@ -1610,9 +1521,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 传输时服务器的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时服务器的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1621,9 +1530,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1 - - 1 表示客户端应尽快回复此消息,以避免超时断开连接。否则为0。 - + 1 表示客户端应尽快回复此消息,以避免超时断开连接;否则为 0。 @@ -1631,9 +1538,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - - 接收进程可以随时使用以下某种消息格式向发送方回传响应(同样放在 CopyData 消息的负载中): - + 接收进程可以随时使用以下消息格式之一回复发送端(同样放在 CopyData 消息的有效载荷中): @@ -1646,9 +1551,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('r') - - 将该消息标识为接收方状态更新。 - + 将该消息标识为接收端状态更新。 @@ -1657,9 +1560,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已接收并写入磁盘的 WAL 字节位置 + 1。 - + 备库已接收并写入磁盘的最后一个 WAL 字节的位置加 1。 @@ -1668,9 +1569,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已刷写到磁盘的 WAL 字节位置 + 1。 - + 备库已刷盘的最后一个 WAL 字节的位置加 1。 @@ -1679,9 +1578,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已应用的 WAL 字节位置 + 1。 - + 备库已应用的最后一个 WAL 字节的位置加 1。 @@ -1690,9 +1587,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 客户端在传输时的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时客户端的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1701,9 +1596,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1 - - 如果为 1,则客户端请求服务器立即回复此消息。这可用于 ping 服务器,以测试连接是否仍然健康。 - + 如果为 1,表示客户端请求服务器立即回复此消息。可用它向服务器发送探测请求,以测试连接是否仍然正常。 @@ -1731,9 +1624,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 客户端在传输时的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时客户端的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1754,8 +1645,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 备库上全局 xmin xid 的纪元。 - + 备库全局 xmin 事务 ID 的纪元。 + @@ -1765,8 +1656,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 备库上任何复制槽中的最低 catalog_xmin。如果备库上不存在 catalog_xmin,或已禁用热备反馈,则设为 0。 - + 备库上所有复制槽中最小的 catalog_xmin。如果备库上不存在 catalog_xmin,或者正在禁用热备反馈,则设为 0。 + @@ -1776,8 +1667,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 备库上 catalog_xmin xid 的纪元。 - + 备库 catalog_xmin 事务 ID 的纪元。 + @@ -1863,7 +1754,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" DROP_REPLICATION_SLOT slot_name WAIT - 删除复制槽 + DROP_REPLICATION_SLOT @@ -1926,9 +1817,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 设置备份的标签。如果未指定,则将使用base backup作为备份标签。 - 标签的引号使用规则与打开的标准SQL字符串相同。 - + 设置备份标签。如果未指定,则使用 base backup 作为备份标签。标签的引号规则与启用 时的标准 SQL 字符串相同。 + @@ -2029,16 +1919,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - level关键字设置压缩级别。 - 对于gzip,压缩级别应该是一个介于19之间的整数 - (默认为Z_DEFAULT_COMPRESSION-1), - 对于lz4,压缩级别应该是介于1和12之间的整数 - (默认为0用于快速压缩模式), - 对于zstd,压缩级别应该是介于ZSTD_minCLevel() - (通常为-131072)和ZSTD_maxCLevel() - (通常为22)之间, - (默认为ZSTD_CLEVEL_DEFAULT3)。 - + level 关键字设置压缩级别。对于 gzip,压缩级别应为 19 之间的整数(默认为 Z_DEFAULT_COMPRESSION,即 -1);对于 lz4,应为 1 到 12 之间的整数(默认为 0,表示快速压缩模式);对于 zstd,应为 ZSTD_minCLevel()(通常为 -131072)到 ZSTD_maxCLevel()(通常为 22)之间的整数(默认为 ZSTD_CLEVEL_DEFAULT,即 3)。 + long 关键字用于启用长距离匹配模式,可提高压缩比,但会增加内存使用。长距离模式仅支持 zstd。 @@ -2160,17 +2042,16 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" size (int8) - 表空间的大致大小,以千字节(1024字节)为单位,如果已请求进度报告;否则为null。 - + 如果请求了进度报告,则为表空间的大致大小,以千字节(1024 字节)为单位;否则为 null。 + - 在第二个常规结果集之后,将发送一个CopyOutResponse。 - 每个CopyData消息的有效负载将包含以下格式之一的消息: - + 第二个普通结果集之后,会发送一条 CopyOutResponse。每条 CopyData 消息的有效载荷都包含一条具有下列格式之一的消息: + @@ -2351,11 +2232,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" + + 在上述所有命令中,指定 boolean 类型的参数时,可以省略 value 部分,这等同于指定 TRUE。 + - 逻辑复制协议 + 逻辑流复制协议 本节介绍逻辑复制协议,它是一种以复制命令START_REPLICATION @@ -2364,7 +2248,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 逻辑复制协议构建在物理流复制协议的底层机制之上。 + 逻辑流复制协议构建在物理流复制协议的基本机制之上。 @@ -2377,7 +2261,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 逻辑流复制参数 - 使用 START_REPLICATION 命令时,pgoutput 接受以下选项: + 使用START_REPLICATION命令,pgoutput接受以下选项: @@ -2395,7 +2279,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 版本 3 仅在服务器版本 15 及以上受支持,允许流式传输两阶段提交。 - 版本 4 仅在服务器版本 16 及以上受支持,允许并行应用正在进行的大型事务的流。 + 版本 4 仅在服务器版本 16 及以上受支持,允许并行应用进行中的大型事务流。 @@ -2505,7 +2389,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每个被发送的事务都包含零条或多条 DML 消息(插入、更新、删除)。在级联场景下,它还会包含 Origin 消息。Origin 消息表示该事务产生于另一个复制节点。由于逻辑复制协议中的复制节点可以是任意实现,因此唯一标识符就是该源头的名称。下游是否以及如何处理这一信息,由其自行决定。Origin 消息总是在事务中的任何 DML 消息之前发送。 + 每个发送的事务都包含零条或多条 DML 消息(Insert、Update、Delete)。在级联配置中,还可能包含 Origin 消息。Origin 消息表示该事务源自另一个复制节点。由于逻辑复制协议中的复制节点几乎可以是任何实现,因此唯一的标识符就是复制源的名称。下游负责按需处理这一信息(如果需要处理)。Origin 消息总是在事务中的任何 DML 消息之前发送。 @@ -2570,9 +2454,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 对后端返回的字符串长度,没有预定义的限制。 - 前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。 - 如果做不到这一点,就应读取完整字符串,并丢弃不适合固定大小缓冲区的尾随字符。 + 后端返回的字符串长度没有预定义的限制。前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。如果做不到这一点,就应读取完整字符串,并丢弃固定大小的缓冲区容纳不下的尾随字符。 @@ -2598,8 +2480,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 消息格式 - 本节描述每条消息的详细格式。每条消息都标记了可由前端(F)、后端(B)或双方(F&B)发送。 - 请注意,虽然每条消息开头都带有字节计数,但大多数消息格式都定义为无需参考该计数也能确定消息边界。这一设计最初是出于历史原因(早期已废弃的协议 v2 没有显式长度字段),同时也有助于有效性校验。 + 本节描述每条消息的详细格式。每条消息都标明它可以由前端(F)、后端(B)或双方(F & B)发送。注意,虽然每条消息开头都有字节计数,但消息格式的定义使得无需参考该计数也能确定消息的结束位置。这有助于检查消息的有效性。(CopyData 消息是例外,因为它构成数据流的一部分,任何单条 CopyData 消息的内容都无法独立解释。) @@ -2614,7 +2495,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2636,7 +2517,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定认证成功。 + 表示认证成功。 @@ -2656,7 +2537,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2678,7 +2559,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 Kerberos V5 认证。 + 表示需要 Kerberos V5 认证。 @@ -2698,7 +2579,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2720,7 +2601,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要明文密码。 + 表示需要明文密码。 @@ -2739,7 +2620,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2761,7 +2642,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要MD5加密的密码。 + 表示需要经过 MD5 加密的密码。 @@ -2772,7 +2653,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 用于加密密码时使用的盐。 + 加密密码时使用的盐。 @@ -2791,7 +2672,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2812,7 +2693,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 GSSAPI 认证。 + 表示需要 GSSAPI 认证。 @@ -2831,7 +2712,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2853,7 +2734,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定此消息包含GSSAPI或SSPI数据。 + 表示此消息包含 GSSAPI 或 SSPI 数据。 @@ -2883,7 +2764,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2905,7 +2786,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 SSPI 认证。 + 表示需要 SSPI 认证。 @@ -2924,7 +2805,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2946,14 +2827,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 SASL 认证。 + 表示需要 SASL 认证。 - 消息正文是服务器首选的 SASL 认证机制列表。在最后一个认证机制名称后需要一个零字节作为终止符。对于每个机制,有以下内容: + 消息体是按服务器偏好顺序排列的 SASL 认证机制列表。在最后一个认证机制名称之后,必须有一个零字节作为终止符。每个机制包含以下内容: @@ -2980,7 +2861,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -3002,7 +2883,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定此消息包含一个SASL挑战。 + 表示此消息包含 SASL 挑战。 @@ -3013,7 +2894,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - SASL数据,特定于正在使用的SASL机制。 + SASL 数据,具体内容取决于所使用的 SASL 机制。 @@ -3032,7 +2913,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -3054,7 +2935,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定SASL认证已完成。 + 表示 SASL 认证已完成。 @@ -3065,7 +2946,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - SASL结果"附加数据",特定于正在使用的SASL机制。 + SASL 结果的“附加数据”,具体内容取决于所使用的 SASL 机制。 @@ -3084,8 +2965,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为取消键数据。 - 如果前端希望能够稍后发出CancelRequest消息,必须保存这些值。 + 将此消息标识为取消请求密钥数据。如果前端希望以后能够发送 CancelRequest 消息,就必须保存这些值。 @@ -3107,7 +2987,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 这个后端的进程ID。 + 此后端的进程 ID。 @@ -3117,18 +2997,12 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 - - 该后端的 secret key。该字段长度由消息总长度决定,并一直延伸到消息末尾。 - - - key 的最小与最大长度分别为 4 和 256 字节。PostgreSQL 服务器当前发送不超过 32 字节的 key;更大的上限用于兼容未来版本及连接池/中间件使用更长 key 的需求。中间件也不宜用满全部字节,以便多层中间件叠加时仍可附加自身数据。 - + 此后端的密钥。 + - - secret key 为 4 字节。 - + @@ -3143,7 +3017,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为绑定命令。 + 将该消息标识为 Bind 命令。 @@ -3187,10 +3061,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后面跟着的参数格式代码的数量(以下标记为C)。 - 这可以是零,表示没有参数或者所有参数都使用默认格式(文本); - 或者是一个,这种情况下指定的格式代码应用于所有参数; - 或者等于实际参数的数量。 + 后续参数格式代码的数量(下文以 C 表示)。可以为零,表示没有参数,或者所有参数都使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有参数;还可以等于实际参数数量。 @@ -3201,7 +3072,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数格式代码。每个目前必须是零(文本)或一(二进制)。 + 参数格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -3212,15 +3083,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后面跟着的参数值的数量(可能为零)。 - 这个数量必须与查询所需的参数数量匹配。 + 后续参数值的数量(可以为零)。必须与查询所需的参数数量一致。 - 接下来,对于每个参数,都会出现以下一对字段: + 接下来,每个参数都有以下一对字段: @@ -3230,9 +3100,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数值的长度,以字节为单位(此计数不包括自身)。可以为零。 - 作为特殊情况,-1表示空参数值。 - 在空参数值的情况下,不会跟随任何值字节。 + 参数值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 参数值。为 NULL 时,后面不再有值的字节。 @@ -3243,15 +3111,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数的值,以相关格式代码指示的格式表示。 - n是上述长度。 + 参数值,格式由对应的格式代码指明。n 为上述长度。 - 在最后一个参数之后,出现以下字段: + 最后一个参数之后是以下字段: @@ -3261,10 +3128,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后跟的结果列格式代码数量(以下标记为R)。 - 这可以是零,表示没有结果列,或者所有结果列应该使用默认格式(文本); - 或者是一个,此时指定的格式代码将应用于所有结果列(如果有); - 或者等于查询的实际结果列数。 + 后续结果列格式代码的数量(下文以 R 表示)。可以为零,表示没有结果列,或者所有结果列都应使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有结果列(如果有);还可以等于查询实际的结果列数量。 @@ -3275,7 +3139,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 结果列格式代码。每个目前必须是零(文本)或一(二进制)。 + 结果列格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -3294,7 +3158,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为绑定完成指示器。 + 将该消息标识为 Bind 完成指示。 @@ -3322,7 +3186,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(16) - 消息内容的长度,以字节为单位,包括此长度字段本身。 + 消息内容的长度(以字节为单位),包括其自身。 @@ -3368,7 +3232,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为关闭命令。 + 将该消息标识为 Close 命令。 @@ -3390,8 +3254,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 'S' 表示关闭一个预备语句;或者 - 'P' 表示关闭一个 portal。 + “S”表示关闭预备语句;“P”表示关闭 portal。 @@ -3421,7 +3284,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为关闭完成指示符。 + 将该消息标识为 Close 完成指示。 @@ -3451,7 +3314,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为命令完成响应。 + 将该消息标识为命令完成响应。 @@ -3473,7 +3336,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 命令标签。这通常是一个单词,用于标识已完成的SQL命令。 + 命令标签。通常是一个单词,用来标识已完成的 SQL 命令。 @@ -3518,10 +3381,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 对于COPY命令,标签是 - COPY rows,其中 - rows是复制的行数。 - (注意:行数仅出现在PostgreSQL 8.2及更高版本中。) + 对于 COPY 命令,标签为 COPY rows,其中 rows 是复制的行数。(注意:行数仅出现在 PostgreSQL 8.2 及更高版本中。) @@ -3652,8 +3512,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为开始复制响应。 - 前端现在必须发送复制数据(如果没有准备好,发送CopyFail消息)。 + 将该消息标识为开始 COPY 输入的响应。前端此时必须发送 COPY 输入数据(如果尚未准备好,应发送 CopyFail 消息)。 @@ -3699,9 +3558,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -3720,8 +3577,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为开始复制输出响应。 - 该消息将被复制输出数据跟随。 + 将该消息标识为开始 COPY 输出的响应。此消息之后会发送 COPY 输出数据。 @@ -3743,8 +3599,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 0表示整体COPY格式为文本格式(行由换行符分隔,列由分隔符字符分隔等)。 - 1表示整体复制格式为二进制格式(类似于DataRow格式)。更多信息请参见。 + 0表示整体COPY格式是文本的(行由换行符分隔,列由分隔符分隔等)。 + 1表示整体复制格式是二进制的(类似于DataRow格式)。 + 更多信息请参见 @@ -3766,9 +3623,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -3787,7 +3642,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为开始复制双响应。此消息仅用于流复制。 + 将该消息标识为开始双向 COPY 的响应。此消息仅用于流复制。 @@ -3809,8 +3664,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 0表示整体COPY格式为文本格式(行由换行符分隔,列由分隔符字符分隔等)。 - 1表示整体复制格式为二进制格式(类似于DataRow格式)。更多信息请参见。 + 0表示整体COPY格式是文本的(行由换行符分隔,列由分隔符分隔等)。 + 1表示整体复制格式是二进制的(类似于DataRow格式)。 + 更多信息请参见 @@ -3832,9 +3688,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -3882,7 +3736,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于每一列,都会出现以下一对字段: + 接下来,每列都有以下两个字段: @@ -3892,8 +3746,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列值的长度,以字节为单位(此计数不包括其本身)。可以为零。 - 作为特殊情况,-1表示空列值。在空值情况下,不跟随任何值字节。 + 列值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 列值。为 NULL 时,后面不再有值的字节。 @@ -3924,7 +3777,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为描述命令。 + 将该消息标识为 Describe 命令。 @@ -3977,7 +3830,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为对空查询字符串的响应。(这相当于CommandComplete。) + 标识消息为对空查询字符串的响应。(此消息替代 CommandComplete。) @@ -4025,7 +3878,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 消息正文由一个或多个已识别的字段组成,后跟一个零字节作为终止符。字段可以以任何顺序出现。对于每个字段,都有以下内容: + 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -4048,7 +3901,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 字段数值。 + 字段值。 @@ -4067,7 +3920,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为一个执行命令。 + 将该消息标识为 Execute 命令。 @@ -4100,7 +3953,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果 portal 包含返回行的查询,则为要返回的最大行数(否则忽略)。零表示没有限制。 + 如果 portal 包含返回行的查询,则这是最多返回的行数(否则忽略此值)。零表示无限制 @@ -4119,7 +3972,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为Flush命令。 + 将该消息标识为 Flush 命令。 @@ -4171,7 +4024,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定要调用的函数的对象ID。 + 指定要调用的函数的对象 ID。 @@ -4182,10 +4035,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后面跟着的参数格式代码的数量(以下标记为C)。 - 这可以是零,表示没有参数或所有参数都使用默认格式(文本); - 或者是一个,这种情况下指定的格式代码应用于所有参数; - 或者等于实际参数的数量。 + 后续参数格式代码的数量(以下用 C 表示)。可以为零,表示没有参数,或所有参数都采用默认格式(文本);也可以为一,表示将指定的格式代码用于所有参数;还可以等于实际参数数量。 @@ -4214,7 +4064,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于每个参数,都会出现以下一对字段: + 接下来,每个参数都有以下两个字段: @@ -4224,9 +4074,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数值的长度,以字节为单位(此计数不包括自身)。可以为零。 - 作为特殊情况,-1表示空参数值。 - 在空参数值的情况下,不会跟随任何值字节。 + 参数值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 参数值。为 NULL 时,后面不再有值的字节。 @@ -4245,7 +4093,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 在最后一个参数之后,出现以下字段: + 最后一个参数之后还有以下字段: @@ -4255,7 +4103,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 函数结果的格式代码。目前必须是零(文本)或一(二进制)。 + 函数结果的格式代码。目前必须为零(文本)或一(二进制)。 @@ -4296,9 +4144,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 函数结果值的长度,以字节为单位(此计数不包括本身)。可以为零。 - 作为特殊情况,-1表示NULL函数结果。 - 在NULL情况下,不会跟随任何值字节。 + 函数结果值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 函数结果。为 NULL 时,后面不再有值的字节。 @@ -4424,7 +4270,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 服务器支持的最新次要协议版本,用于客户端请求的主要协议版本。 + 对于客户端请求的协议主版本,服务器所支持的最新协议次版本。 @@ -4435,14 +4281,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 服务器未识别的协议选项数量。 + 服务器无法识别的协议选项数量。 - 然后,对于服务器未识别的协议选项,有以下内容: + 接下来,对于服务器无法识别的每个协议选项,都有以下内容: @@ -4519,7 +4365,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 消息正文由一个或多个已识别的字段组成,后跟一个零字节作为终止符。字段可以以任何顺序出现。对于每个字段,都有以下内容: + 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -4542,7 +4388,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 字段数值。 + 字段值。 @@ -4583,7 +4429,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 通知后端进程的进程ID。 + 发出通知的后端进程的进程 ID。 @@ -4594,7 +4440,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 通知被触发的频道名称。 + 发出该通知的通道名称。 @@ -4605,7 +4451,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 从通知进程传递的有效负载字符串。 + 通知进程传来的有效载荷字符串。 @@ -4653,7 +4499,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 然后,对于每个参数,都有以下内容: + 接下来,每个参数都有以下内容: @@ -4663,7 +4509,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定参数数据类型的对象ID。 + 指定参数数据类型的对象 ID。 @@ -4704,7 +4550,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 正在报告的运行时参数的名称。 + 所报告的运行时参数的名称。 @@ -4734,7 +4580,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为解析命令。 + 将该消息标识为 Parse 命令。 @@ -4786,7 +4632,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 然后,对于每个参数,都有以下内容: + 接下来,每个参数都有以下内容: @@ -4796,7 +4642,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定参数数据类型的对象ID。在这里放置零相当于未指定类型。 + 指定参数数据类型的对象 ID。此处填零等同于不指定类型。 @@ -4815,7 +4661,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为解析完成指示器。 + 将该消息标识为 Parse 完成指示。 @@ -4887,8 +4733,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为 portal 挂起指示器。 - 请注意,仅当执行消息的行数限制达到时才会出现此消息。 + 将该消息标识为 portal 挂起指示。注意,仅当达到 Execute 消息指定的行数限制时,才会出现此消息。 @@ -5024,14 +4869,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定一行中的字段数(可以为零)。 + 指定一行中的字段数量(可以为零)。 - 然后,对于每个字段,都有以下内容: + 接下来,每个字段都有以下内容: @@ -5052,7 +4897,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果该字段可以被识别为特定表的列,则为该表的对象ID;否则为零。 + 如果能够确定该字段是某个特定表的列,则为该表的对象 ID;否则为零。 @@ -5063,7 +4908,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果该字段可以被识别为特定表的列,则为该列的属性编号;否则为零。 + 如果能够确定该字段是某个特定表的列,则为该列的属性编号;否则为零。 @@ -5074,7 +4919,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 字段数据类型的对象ID。 + 字段数据类型的对象 ID。 @@ -5109,7 +4954,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 正在使用的字段格式代码。目前将为零(文本)或一(二进制)。在从描述语句变体返回的RowDescription中,格式代码尚未知晓,将始终为零。 + 字段所使用的格式代码。目前为零(文本)或一(二进制)。对于 Describe 针对预备语句的变体所返回的 RowDescription,格式代码尚未确定,始终为零。 @@ -5162,7 +5007,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 长度为SASL机制特定的“初始客户端响应”,如果没有初始响应,则为-1。 + 后续 SASL 机制特有的“客户端初始响应”的长度;如果没有初始响应,则为 -1。 @@ -5277,17 +5122,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 协议版本号。最重要的16位是主版本号(此处描述的协议为3)。 - 最不重要的16位是次版本号(此处描述的协议为2)。 + 协议版本号。高 16 位为主版本号(此处描述的协议为 3);低 16 位为次版本号(此处描述的协议为 0)。 - 协议版本号后面跟着一个或多个参数名和值字符串对。在最后一个名/值对之后需要一个零字节作为终止符。 - 参数可以以任何顺序出现。user是必需的,其他是可选的。 - 每个参数的指定方式为: + 协议版本号之后是一个或多个参数名与参数值字符串对。最后一个名称/值对之后必须有一个零字节作为终止符。参数可以按任意顺序出现。其中,user是必需的,其余均为可选。每个参数按以下方式指定: @@ -5297,7 +5139,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数名称。当前识别的名称包括: + 参数名称。目前能够识别的名称如下: @@ -5337,7 +5179,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 除上述之外,还可以列出其他参数。以_pq_.开头的参数名称保留用于协议扩展,而其他参数被视为后端启动时设置的运行时参数。这些设置将在后端启动时应用(在解析命令行参数后,如果有的话),并将作为会话默认值。 + 除上述参数外,还可以列出其他参数。以_pq_.开头的参数名称保留用于协议扩展,其余参数则作为运行时参数,在后端启动时设置。这些设置会在后端启动期间应用(在解析命令行参数之后,如果有的话),并作为会话默认值。 @@ -5348,7 +5190,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数数值。 + 参数值。 @@ -5367,7 +5209,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为同步命令。 + 将该消息标识为 Sync 命令。 @@ -5420,7 +5262,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 错误和通知消息域 + 错误和通知消息字段 本节描述了ErrorResponse和NoticeResponse消息中可能出现的字段。每个字段类型都有一个单字节的标识符。 @@ -5433,11 +5275,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 严重性: 字段内容为ERROR, FATAL, 或 - PANIC (在错误消息中), 或 - WARNING, NOTICE, DEBUG, - INFO, 或 LOG (在通知消息中), - 或者这些内容的本地化翻译。始终存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中),或这些内容的本地化翻译。始终存在。 @@ -5447,11 +5285,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 严重性:字段内容为ERRORFATAL或 - PANIC(在错误消息中),或WARNINGNOTICEDEBUG、 - INFOLOG(在通知消息中)。 - 这与S字段相同,只是内容不会被本地化。仅在由PostgreSQL版本9.6 - 及更高版本生成的消息中存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中)。它与 S 字段相同,只是内容从不本地化。仅在 PostgreSQL 9.6 及更高版本生成的消息中存在。 @@ -5461,7 +5295,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Code: 错误的SQLSTATE代码(参见)。不可本地化。始终存在。 + 代码:错误的 SQLSTATE 代码(见 )。不可本地化。始终存在。 @@ -5471,9 +5305,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 消息: 主要的人类可读错误消息。 - 这应该准确但简洁(通常一行)。 - 总是存在。 + 消息:主要的可读错误消息。应准确而简洁(通常为一行)。始终存在。 @@ -5483,7 +5315,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 详细信息:一个可选的次要错误消息,提供有关问题的更多详细信息。可能会跨多行。 + 详细信息:可选的次要错误消息,提供有关该问题的更多细节。可能占多行。 @@ -5493,9 +5325,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 提示: 关于问题应该怎么做的一个可选建议。 - 这意在与细节不同,它提供建议(可能不合适)而不是硬性事实。 - 可能会跨越多行。 + 提示:可选的建议,说明如何处理该问题。它与详细信息的区别在于,它提供建议(可能并不合适),而非确凿事实。可能占多行。 @@ -5538,9 +5368,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Where: 错误发生的上下文指示。 - 目前包括活动的过程语言函数和内部生成查询的调用堆栈回溯。 - 跟踪每行一个条目,最近的在前。 + 上下文:说明错误发生时的上下文。目前包括活跃的过程语言函数和内部生成的查询的调用栈回溯。回溯每行一个条目,最近的调用在前。 @@ -5550,7 +5378,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Schema name: 如果错误与特定数据库对象相关联,则为包含该对象的模式的名称(如果有)。 + 模式名:如果错误与某个特定数据库对象有关,则为包含该对象的模式名称(如果有)。 @@ -5560,7 +5388,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 表名: 如果错误与特定表相关联,则为表的名称。(有关表模式名称的名称,请参考模式名称字段。) + 表名:如果错误与某个特定表有关,则为该表的名称。(表所在模式的名称见模式名字段。) @@ -5570,7 +5398,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列名: 如果错误与特定表列相关联,则为列的名称。(请参考模式和表名字段以识别表。) + 列名:如果错误与某个特定表列有关,则为该列的名称。(通过模式名和表名字段确定该表。) @@ -5580,8 +5408,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 数据类型名称: 如果错误与特定数据类型相关联,则为数据类型的名称。 - (有关数据类型模式的名称,请参阅模式名称字段。) + 数据类型名:如果错误与某个特定数据类型有关,则为该数据类型的名称。(数据类型所在模式的名称见模式名字段。) @@ -5591,8 +5418,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 约束名称: 如果错误与特定约束相关联,则为约束的名称。请参考上面列出的字段,了解相关表或域。 - (为此,即使索引不是使用约束语法创建的,也将其视为约束。) + 约束名:如果错误与某个特定约束有关,则为该约束的名称。相关的表或域见上述字段。(这里将索引也视为约束,即使它不是用约束语法创建的。) @@ -5602,7 +5428,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 文件: 报告错误的源代码位置的文件名。 + 文件:报告错误的源代码位置所在的文件名。 @@ -5612,7 +5438,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Line: 源代码位置的行号,报告错误的位置。 + 行号:报告错误的源代码位置所在的行号。 @@ -5622,7 +5448,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Routine: 报告错误的源代码例程的名称。 + 例程:报告错误的源代码例程的名称。 @@ -5631,15 +5457,12 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 模式名称、表名称、列名称、数据类型名称和约束名称的字段仅针对有限数量的错误类型提供; - 请参阅。前端不应假设任何这些字段的存在就保证了另一个字段的存在。 - 核心错误源观察到上述相互关系,但用户定义的函数可能以其他方式使用这些字段。 - 同样地,客户端不应假设这些字段表示当前数据库中的当代对象。 + 模式名、表名、列名、数据类型名和约束名字段仅针对有限的几类错误提供,见 。前端不应假设其中任何字段的存在就保证了另一个字段的存在。核心错误源遵循上述相互关系,但用户定义的函数可能以其他方式使用这些字段。同样,客户端不应假设这些字段表示当前数据库中现存的对象。 - 客户端负责格式化显示的信息以满足其需求;特别是应根据需要换行。错误消息字段中出现的换行符应被视为段落分隔符,而不是换行符。 + 客户端负责按自身需要格式化显示的信息;尤其应根据需要将长行断开。错误消息字段中的换行符应视为段落分隔符,而非行分隔符。 @@ -5665,18 +5488,18 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为开始消息。 + 将该消息标识为 Begin 消息。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 事务的最终LSN。 + 事务的最终 LSN。 @@ -5687,7 +5510,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -5698,7 +5521,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -5728,8 +5551,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -5740,14 +5562,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标志; 逻辑解码消息是非事务性的时为0,是事务性的时为1。 + 标志:0 表示没有标志;1 表示该逻辑解码消息是事务性的。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -5803,7 +5625,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为提交消息。 + 将该消息标识为 Commit 消息。 @@ -5821,22 +5643,22 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 提交的LSN。 + 提交的 LSN。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 事务的结束LSN。 + 事务的结束 LSN。 @@ -5847,7 +5669,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -5866,18 +5688,18 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为原始消息。 + 将该消息标识为 Origin 消息。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 原始服务器上提交的LSN。 + 源服务器上提交的 LSN。 @@ -5888,14 +5710,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 原点的名称。 + 复制源的名称。 - 请注意,在单个事务中可能存在多个Origin消息。 + 注意,单个事务中可能有多条 Origin 消息。 @@ -5911,7 +5733,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为关系消息。 + 将该消息标识为 Relation 消息。 @@ -5922,8 +5744,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -5945,7 +5766,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 命名空间(pg_catalog为空字符串)。 + 命名空间(对于 pg_catalog 为空字符串)。 @@ -5967,7 +5788,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 关系的复制标识设置(与relreplidentpg_class中相同)。 + 关系的复制标识设置(与 pg_class 中的 relreplident 相同)。 @@ -5985,7 +5806,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于出版物中包含的每一列(除了生成的列),会出现以下消息部分: + 接下来,发布中包含的每一列(生成列除外)都会出现以下消息部分: @@ -5995,7 +5816,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列的标志。目前可以是0表示没有标志,或者是1表示将该列标记为键的一部分。 + 列的标志。目前可以为 0,表示没有标志;或为 1,标记该列是键的一部分。 @@ -6028,7 +5849,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列的类型修饰符 (atttypmod)。 + 列的类型修饰符(atttypmod)。 @@ -6047,7 +5868,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为类型消息。 + 将该消息标识为 Type 消息。 @@ -6058,8 +5879,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6081,7 +5901,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 命名空间(pg_catalog为空字符串)。 + 命名空间(对于 pg_catalog 为空字符串)。 @@ -6111,7 +5931,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为插入消息。 + 将该消息标识为 Insert 消息。 @@ -6122,8 +5942,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6134,7 +5953,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。 + 关系的 OID,与 Relation 消息中的 ID 对应。 @@ -6145,7 +5964,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData消息为新元组。 + 将后续 TupleData 消息标识为新元组。 @@ -6156,7 +5975,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分,表示新元组的内容。 + 表示新元组内容的 TupleData 消息部分。 @@ -6175,7 +5994,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为更新消息。 + 将该消息标识为 Update 消息。 @@ -6186,8 +6005,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6198,7 +6016,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。 + 关系的 OID,与 Relation 消息中的 ID 对应。 @@ -6209,8 +6027,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData子消息为键。 - 此字段是可选的,仅在更新更改了属于REPLICA IDENTITY索引的任何列的数据时才存在。 + 将后续 TupleData 子消息标识为键。此字段可选,仅在更新更改了属于 REPLICA IDENTITY 索引的某一列或多列的数据时出现。 @@ -6221,8 +6038,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData子消息为旧元组。 - 此字段是可选的,仅在发生更新的表中REPLICA IDENTITY设置为FULL时才存在。 + 将后续 TupleData 子消息标识为旧元组。此字段可选,仅在发生更新的表将 REPLICA IDENTITY 设为 FULL 时出现。 @@ -6233,7 +6049,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分表示旧元组或主键的内容。仅在先前的'O'或'K'部分存在时才存在。 + 表示旧元组或主键内容的 TupleData 消息部分。仅在前面的'O'或'K'部分存在时出现。 @@ -6244,7 +6060,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData消息为新元组。 + 将后续 TupleData 消息标识为新元组。 @@ -6255,14 +6071,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分表示新元组的内容。 + 表示新元组内容的 TupleData 消息部分。 - 更新消息可能包含一个'K'消息部分,也可能包含一个'O'消息部分,或者两者都不包含,但绝不会同时包含两者。 + Update 消息可以包含 'K' 消息部分或 'O' 消息部分,也可以两者都不包含,但绝不会同时包含两者。 @@ -6278,7 +6094,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为删除消息。 + 将该消息标识为 Delete 消息。 @@ -6289,8 +6105,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6301,7 +6116,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。 + 关系的 OID,与 Relation 消息中的 ID 对应。 @@ -6312,8 +6127,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData子消息为键。 - 如果发生删除操作的表使用索引作为REPLICA IDENTITY,则存在此字段。 + 将后续 TupleData 子消息标识为键。如果发生删除的表使用索引作为 REPLICA IDENTITY,则出现此字段。 @@ -6324,8 +6138,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData消息为旧元组。 - 如果发生删除操作的表的REPLICA IDENTITY设置为FULL,则存在此字段。 + 将后续 TupleData 消息标识为旧元组。如果发生删除的表将 REPLICA IDENTITY 设为 FULL,则出现此字段。 @@ -6336,14 +6149,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分,表示旧元组或主键的内容,取决于前一个字段。 + 表示旧元组或主键内容的 TupleData 消息部分,具体取决于前一个字段。 - 删除消息可能包含一个'K'消息部分或一个'O'消息部分,但绝不会同时包含两者。 + Delete 消息可以包含 'K' 消息部分或 'O' 消息部分,但绝不会同时包含两者。 @@ -6359,7 +6172,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为截断消息。 + 将该消息标识为 Truncate 消息。 @@ -6370,8 +6183,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6405,7 +6217,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。该字段对每个关系都重复。 + 关系的 OID,与 Relation 消息中的 ID 对应。每个关系都重复出现此字段。 @@ -6430,7 +6242,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为流开始消息。 + 将该消息标识为 Stream Start 消息。 @@ -6441,7 +6253,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6471,7 +6283,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为流停止消息。 + 将该消息标识为 Stream Stop 消息。 @@ -6490,7 +6302,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为流提交消息。 + 将该消息标识为 Stream Commit 消息。 @@ -6501,7 +6313,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6519,22 +6331,22 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 提交的LSN。 + 提交的 LSN。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 事务的结束LSN。 + 事务的结束 LSN。 @@ -6545,7 +6357,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6564,7 +6376,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为流中止消息。 + 将该消息标识为 Stream Abort 消息。 @@ -6575,7 +6387,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6632,14 +6444,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务开始消息。 + 将该消息标识为 Begin Prepare 消息。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6650,7 +6462,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6665,7 +6477,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6676,7 +6488,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6706,7 +6518,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务消息。 + 将该消息标识为 Prepare 消息。 @@ -6724,7 +6536,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6735,7 +6547,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6750,7 +6562,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6761,7 +6573,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6791,7 +6603,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务提交消息。 + 将该消息标识为 Commit Prepared 消息。 @@ -6809,7 +6621,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6820,7 +6632,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6835,7 +6647,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6846,7 +6658,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6876,7 +6688,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务回滚消息。 + 将该消息标识为 Rollback Prepared 消息。 @@ -6894,7 +6706,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6905,7 +6717,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6920,7 +6732,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6942,7 +6754,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6972,7 +6784,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为流式预备事务消息。 + 将该消息标识为 Stream Prepare 消息。 @@ -6990,7 +6802,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -7001,7 +6813,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -7016,7 +6828,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -7027,7 +6839,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -7070,14 +6882,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于每一列(除了生成的列),会出现以下子消息之一: + 接下来,每一列(生成列除外)都会出现以下子消息之一: Byte1('n') - 将数据标识为NULL值。 + 将该数据标识为 NULL 值。 @@ -7088,7 +6900,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('u') - 将TOASTed值标识为未更改的值(实际值未发送)。 + 标识未更改的 TOAST 值(不发送实际值)。 @@ -7099,7 +6911,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('t') - 将数据标识为文本格式化值。 + 将该数据标识为文本格式的值。 @@ -7110,7 +6922,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('b') - 将数据标识为二进制格式化值。 + 将该数据标识为二进制格式的值。 @@ -7128,9 +6940,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byten - 列的值,以二进制或文本格式呈现。 - (如前述格式字节中指定)。 - n是上述长度。 + 列值,采用二进制或文本格式(由前面的格式字节指定)。n 为上述长度。 diff --git a/zh/17/rangetypes.sgml b/zh/17/rangetypes.sgml index 68409fa3..5badec6c 100644 --- a/zh/17/rangetypes.sgml +++ b/zh/17/rangetypes.sgml @@ -5,11 +5,11 @@ 范围类型 - range type + 范围类型 - multirange type + 多范围类型 @@ -21,7 +21,7 @@ - 每种范围类型都有一个对应的多范围类型。多范围是由多个彼此不连续、非空且非 NULL 的范围构成的有序列表。大多数范围操作符也可作用于多范围,并且多范围还有一些专用函数。 + 每种范围类型都有一个对应的多范围类型。多范围是一个有序列表,其中的范围彼此不连续,且均非空、非 NULL。大多数范围操作符也可作用于多范围,并且多范围还有一些专用函数。 @@ -124,15 +124,15 @@ SELECT isempty(numrange(1, 5)); 无限(无界)范围 - 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作 +/-infinity,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的 +/-infinity 值。 + 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作正负无穷大,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的正负无穷大值。 - 具有infinity概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 + 具有无穷大概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 - 函数lower_infupper_inf分别测试范围的下界和上界是否为无限。 + 函数lower_infupper_inf分别测试范围是否没有下界和上界。 @@ -324,8 +324,8 @@ SELECT '[11:10, 23:00]'::timerange; 索引 - range type - indexes on + 范围类型 + 索引 @@ -357,7 +357,7 @@ CREATE INDEX reservation_idx ON reservation USING GIST (during); - 此外,也可以为范围类型的表列创建 B-树和哈希索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和哈希支持主要是为了允许在查询内部进行排序和哈希,而不是用于创建实际的索引。 + 此外,也可以为范围类型的表列创建 B-树和 hash 索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和 hash 支持主要是为了允许在查询内部进行排序和 hash 运算,而不是用于创建实际的索引。 @@ -366,8 +366,8 @@ CREATE INDEX reservation_idx ON reservation USING GIST (during); 范围上的约束 - range type - exclude + 范围类型 + 排他约束 diff --git a/zh/17/ref/alter_extension.sgml b/zh/17/ref/alter_extension.sgml index 3ceae003..b5824a68 100644 --- a/zh/17/ref/alter_extension.sgml +++ b/zh/17/ref/alter_extension.sgml @@ -170,7 +170,7 @@ ALTER EXTENSION name DROP 要添加到扩展中或从扩展中移除的对象名称。表、聚合、域、外部表、函数、 - 操作符、操作符类、操作符族、过程、例程、序列、文本搜索对象、类型和视图的名称 + 操作符、操作符类、操作符族、过程、例程、序列、文本检索对象、类型和视图的名称 可以带模式限定。 diff --git a/zh/17/ref/alter_tsconfig.sgml b/zh/17/ref/alter_tsconfig.sgml index 891dce66..0845a229 100644 --- a/zh/17/ref/alter_tsconfig.sgml +++ b/zh/17/ref/alter_tsconfig.sgml @@ -19,7 +19,7 @@ PostgreSQL documentation ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义 + 更改一个文本检索配置的定义 @@ -51,7 +51,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义。你可以修改其从记号类型到字典的映射, + 更改一个文本检索配置的定义。你可以修改其从词元类型到词典的映射, 或者更改该配置的名称或拥有者。 @@ -75,7 +75,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 一个现有文本搜索配置的名称(可以是模式限定的)。 + 一个现有文本检索配置的名称(可以是模式限定的)。 @@ -86,7 +86,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 由该配置的解析器发出的记号类型的名称。 + 由该配置的解析器发出的词元类型的名称。 @@ -97,7 +97,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 用于指定记号类型的文本搜索字典名称。如果列出了多个字典, + 用于指定词元类型的文本检索词典名称。如果列出了多个词典, 将按指定顺序依次查阅它们。 @@ -109,7 +109,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 在映射中要替换的文本搜索字典的名称。 + 在映射中要替换的文本检索词典的名称。 @@ -121,7 +121,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA 被用来替代old_dictionary - 的文本搜索字典的名称。 + 的文本检索词典的名称。 @@ -132,7 +132,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新名称。 + 该文本检索配置的新名称。 @@ -143,7 +143,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新拥有者。 + 该文本检索配置的新拥有者。 @@ -154,7 +154,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新模式。 + 该文本检索配置的新模式。 @@ -163,17 +163,17 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - ADD MAPPING FOR形式会为指定记号类型设置要查阅的字典列表; - 如果任一记号类型已经有映射,则会报错。ALTER MAPPING FOR - 形式作用相同,但会先移除这些记号类型的任何现有映射。 + ADD MAPPING FOR形式会为指定词元类型设置要查阅的词典列表; + 如果任一词元类型已经有映射,则会报错。ALTER MAPPING FOR + 形式作用相同,但会先移除这些词元类型的任何现有映射。 ALTER MAPPING REPLACE形式会在 old_dictionary出现的任何位置, 用new_dictionary替换它。 - 如果出现FOR,则只对指定的记号类型这样做;如果未出现 + 如果出现FOR,则只对指定的词元类型这样做;如果未出现 FOR,则对该配置的所有映射这样做。 - DROP MAPPING形式会移除指定记号类型的所有字典,使这些类型的 - 记号被文本搜索配置忽略。除非出现IF EXISTS,否则如果这些 - 记号类型没有映射就会报错。 + DROP MAPPING形式会移除指定词元类型的所有词典,使这些类型的 + 词元被文本检索配置忽略。除非出现IF EXISTS,否则如果这些 + 词元类型没有映射就会报错。 @@ -187,7 +187,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA 下面的示例将my_config中凡是使用 - english字典的地方,都替换为swedish字典。 + english词典的地方,都替换为swedish词典。 diff --git a/zh/17/ref/alter_tsdictionary.sgml b/zh/17/ref/alter_tsdictionary.sgml index 163d788b..798c6734 100644 --- a/zh/17/ref/alter_tsdictionary.sgml +++ b/zh/17/ref/alter_tsdictionary.sgml @@ -19,7 +19,7 @@ PostgreSQL documentation ALTER TEXT SEARCH DICTIONARY - 更改一个文本搜索字典的定义 + 更改一个文本检索词典的定义 @@ -43,14 +43,14 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - ALTER TEXT SEARCH DICTIONARY更改文本搜索字典的 - 定义。你可以更改该字典的模板相关选项,也可以更改该字典的名称或拥有者。 + ALTER TEXT SEARCH DICTIONARY更改文本检索词典的 + 定义。你可以更改该词典的模板相关选项,也可以更改该词典的名称或拥有者。 - 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该字典 + 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该词典 的拥有者。 @@ -67,7 +67,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 一个现有文本搜索字典的名称(可以是模式限定的)。 + 一个现有文本检索词典的名称(可以是模式限定的)。 @@ -78,7 +78,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -89,7 +89,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 模板相关选项要使用的新值。如果省略等号和值,则会从该字典中移除 + 模板相关选项要使用的新值。如果省略等号和值,则会从该词典中移除 该选项之前的设置,从而允许使用默认值。 @@ -101,7 +101,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新名称。 + 该文本检索词典的新名称。 @@ -112,7 +112,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新拥有者。 + 该文本检索词典的新拥有者。 @@ -123,7 +123,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新模式。 + 该文本检索词典的新模式。 @@ -144,7 +144,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 下面的示例命令更改了一个基于 Snowball 的字典的停用词列表。其他参数 + 下面的示例命令更改了一个基于 Snowball 的词典的停用词列表。其他参数 保持不变。 @@ -170,7 +170,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( language = dutch, StopWords ); - 下面的示例命令更新了该字典的定义,但实际上并没有做 + 下面的示例命令更新了该词典的定义,但实际上并没有做 任何更改。 @@ -178,7 +178,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( dummy ); (之所以可行,是因为选项移除代码在不存在该选项时也不会报错。) - 这种技巧在修改该字典的配置文件时很有用:ALTER + 这种技巧在修改该词典的配置文件时很有用:ALTER 会强制现有数据库会话重新读取配置文件,而如果它们先前已经读取过这 些文件,本来是不会再次读取的。 diff --git a/zh/17/ref/alter_tsparser.sgml b/zh/17/ref/alter_tsparser.sgml index 0844cb0a..ccc73f05 100644 --- a/zh/17/ref/alter_tsparser.sgml +++ b/zh/17/ref/alter_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH PARSER - 更改一个全文检索解析器的定义 + 更改一个文本检索解析器的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA 描述 - ALTER TEXT SEARCH PARSER更改全文检索解析器的定义。 + ALTER TEXT SEARCH PARSER更改文本检索解析器的定义。 当前唯一支持的功能是更改该解析器的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA name - 一个现有全文检索解析器的名称(可以是模式限定的)。 + 一个现有文本检索解析器的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_name - 该全文检索解析器的新名称。 + 该文本检索解析器的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_schema - 该全文检索解析器的新模式。 + 该文本检索解析器的新模式。 diff --git a/zh/17/ref/alter_tstemplate.sgml b/zh/17/ref/alter_tstemplate.sgml index a3eec599..9c9dfc2c 100644 --- a/zh/17/ref/alter_tstemplate.sgml +++ b/zh/17/ref/alter_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH TEMPLATE - 更改一个文本搜索模板的定义 + 更改一个文本检索模板的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA 描述 - ALTER TEXT SEARCH TEMPLATE更改文本搜索模板的定义。 + ALTER TEXT SEARCH TEMPLATE更改文本检索模板的定义。 当前唯一支持的功能是更改该模板的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA name - 一个现有文本搜索模板的名称(可以是模式限定的)。 + 一个现有文本检索模板的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_name - 该文本搜索模板的新名称。 + 该文本检索模板的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_schema - 该文本搜索模板的新模式。 + 该文本检索模板的新模式。 diff --git a/zh/17/ref/create_tsconfig.sgml b/zh/17/ref/create_tsconfig.sgml index 52970b36..fc77edb9 100644 --- a/zh/17/ref/create_tsconfig.sgml +++ b/zh/17/ref/create_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH CONFIGURATION - 定义一个新的文本搜索配置 + 定义一个新的文本检索配置 @@ -33,24 +33,24 @@ CREATE TEXT SEARCH CONFIGURATION name CREATE TEXT SEARCH CONFIGURATION - 创建一个新的文本搜索配置。文本搜索配置指定一个能把字符串拆分为记号 - 的文本搜索解析器,以及一些可用于判断哪些记号对搜索有意义的词典。 + 创建一个新的文本检索配置。文本检索配置指定一个能把字符串拆分为词元 + 的文本检索解析器,以及一些可用于判断哪些词元对搜索有意义的词典。 - 如果只指定了解析器,那么新文本搜索配置最初没有从记号类型到词典的映射, + 如果只指定了解析器,那么新文本检索配置最初没有从词元类型到词典的映射, 因而会忽略所有词。要让该配置真正可用,必须使用后续的ALTER TEXT SEARCH CONFIGURATION命令创建映射。 - 另一种方式是复制一个现有的文本搜索配置。 + 另一种方式是复制一个现有的文本检索配置。 - 如果给出了一个模式名称,则文本搜索配置会被创建在指定的模式中。否则它将会 + 如果给出了一个模式名称,则文本检索配置会被创建在指定的模式中。否则它将会 被创建在当前模式中。 - 定义该文本搜索配置的用户会成为其拥有者。 + 定义该文本检索配置的用户会成为其拥有者。 @@ -66,7 +66,7 @@ CREATE TEXT SEARCH CONFIGURATION namename - 要创建的文本搜索配置的名称。该名称可以是模式限定的。 + 要创建的文本检索配置的名称。该名称可以是模式限定的。 @@ -75,7 +75,7 @@ CREATE TEXT SEARCH CONFIGURATION nameparser_name - 此配置要使用的文本搜索解析器的名称。 + 此配置要使用的文本检索解析器的名称。 @@ -84,7 +84,7 @@ CREATE TEXT SEARCH CONFIGURATION namesource_config - 要复制的现有文本搜索配置的名称。 + 要复制的现有文本检索配置的名称。 diff --git a/zh/17/ref/create_tsdictionary.sgml b/zh/17/ref/create_tsdictionary.sgml index c45a7240..823710b7 100644 --- a/zh/17/ref/create_tsdictionary.sgml +++ b/zh/17/ref/create_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH DICTIONARY - 定义一个新的文本搜索字典 + 定义一个新的文本检索词典 @@ -33,19 +33,19 @@ CREATE TEXT SEARCH DICTIONARY name CREATE TEXT SEARCH DICTIONARY创建一个 - 新的文本搜索字典。文本搜索字典指定一种在搜索时识别哪些词值得关注、 - 哪些词不值得关注的方式。字典依赖于文本搜索模板,后者规定了实际执行 - 这项工作的函数。通常,字典会提供一些选项,用来控制模板函数的具体 + 新的文本检索词典。文本检索词典指定一种在搜索时识别哪些词值得关注、 + 哪些词不值得关注的方式。词典依赖于文本检索模板,后者规定了实际执行 + 这项工作的函数。通常,词典会提供一些选项,用来控制模板函数的具体 行为。 - 如果给出了一个模式名称,那么该文本搜索字典会被创建在指定的模式中。 + 如果给出了一个模式名称,那么该文本检索词典会被创建在指定的模式中。 否则它会被创建在当前模式中。 - 定义文本搜索字典的用户将成为其拥有者。 + 定义文本检索词典的用户将成为其拥有者。 @@ -61,7 +61,7 @@ CREATE TEXT SEARCH DICTIONARY name name - 要创建的文本搜索字典的名称。该名称可以被模式限定。 + 要创建的文本检索词典的名称。该名称可以被模式限定。 @@ -70,7 +70,7 @@ CREATE TEXT SEARCH DICTIONARY name template - 用于定义该字典基本行为的文本搜索模板名称。 + 用于定义该词典基本行为的文本检索模板名称。 @@ -79,7 +79,7 @@ CREATE TEXT SEARCH DICTIONARY name option - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -105,7 +105,7 @@ CREATE TEXT SEARCH DICTIONARY name 下面的示例命令创建了一个基于 Snowball 且使用非标准停用词列表的 - 字典。 + 词典。 diff --git a/zh/17/ref/create_tsparser.sgml b/zh/17/ref/create_tsparser.sgml index 358152ce..88be54e6 100644 --- a/zh/17/ref/create_tsparser.sgml +++ b/zh/17/ref/create_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH PARSER - 定义一个新的全文检索解析器 + 定义一个新的文本检索解析器 @@ -36,19 +36,19 @@ CREATE TEXT SEARCH PARSER name ( CREATE TEXT SEARCH PARSER创建一个 - 新的全文检索解析器。全文检索解析器定义了一种方法,用于将文本字符串 - 拆分成记号并为这些记号指定类型(类别)。解析器本身并没有太大用处, - 必须与一些全文检索字典一起绑定到一个全文检索配置中,才能用于搜索。 + 新的文本检索解析器。文本检索解析器定义了一种方法,用于将文本字符串 + 拆分成词元并为这些词元指定类型(类别)。解析器本身并没有太大用处, + 必须与一些文本检索词典一起绑定到一个文本检索配置中,才能用于搜索。 - 如果给出了一个模式名称,那么全文检索解析器将被创建在指定的模式中。 + 如果给出了一个模式名称,那么文本检索解析器将被创建在指定的模式中。 否则它会被创建在当前模式中。 要使用CREATE TEXT SEARCH PARSER,你必须是超级用户。 - 之所以有此限制,是因为错误的全文检索解析器定义可能会让服务器陷入 + 之所以有此限制,是因为错误的文本检索解析器定义可能会让服务器陷入 混乱,甚至崩溃。 @@ -65,7 +65,7 @@ CREATE TEXT SEARCH PARSER name ( name - 要创建的全文检索解析器的名称。该名称可以是模式限定的。 + 要创建的文本检索解析器的名称。该名称可以是模式限定的。 @@ -83,7 +83,7 @@ CREATE TEXT SEARCH PARSER name ( gettoken_function - 该解析器的获取下一个记号的函数名称。 + 该解析器的获取下一个词元的函数名称。 @@ -101,7 +101,7 @@ CREATE TEXT SEARCH PARSER name ( lextypes_function - 该解析器的 lextypes 函数的名称(该函数返回它所产生的记号类型集合的 + 该解析器的 lextypes 函数的名称(该函数返回它所产生的词元类型集合的 信息)。 @@ -111,7 +111,7 @@ CREATE TEXT SEARCH PARSER name ( headline_function - 该解析器的 headline 函数的名称(该函数对一组记号生成摘要)。 + 该解析器的 headline 函数的名称(该函数对一组词元生成摘要)。 diff --git a/zh/17/ref/create_tstemplate.sgml b/zh/17/ref/create_tstemplate.sgml index 702233e4..0f1b4e1a 100644 --- a/zh/17/ref/create_tstemplate.sgml +++ b/zh/17/ref/create_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH TEMPLATE - 定义一个新的全文检索模板 + 定义一个新的文本检索模板 @@ -33,22 +33,22 @@ CREATE TEXT SEARCH TEMPLATE name ( CREATE TEXT SEARCH TEMPLATE创建一个 - 新的全文检索模板。全文检索模板定义实现全文检索字典的函数。模板本身 - 并无直接用途,必须先实例化为字典后才能使用。字典通常会指定要传递给 + 新的文本检索模板。文本检索模板定义实现文本检索词典的函数。模板本身 + 并无直接用途,必须先实例化为词典后才能使用。词典通常会指定要传递给 模板函数的参数。 - 如果给出了模式名称,则全文检索模板会被创建在指定模式中。否则它会被 + 如果给出了模式名称,则文本检索模板会被创建在指定模式中。否则它会被 创建在当前模式中。 要使用CREATE TEXT SEARCH TEMPLATE,你 - 必须是超级用户。之所以有此限制,是因为错误的全文检索模板定义可能使 - 服务器陷入混乱,甚至崩溃。将模板与字典分离的原因在于,模板封装了定 - 义字典时那些不安全的方面。而在定义字典时可设置的参数, - 对非特权用户来说是安全的,因此创建字典不必是特权操作。 + 必须是超级用户。之所以有此限制,是因为错误的文本检索模板定义可能使 + 服务器陷入混乱,甚至崩溃。将模板与词典分离的原因在于,模板封装了定 + 义词典时那些不安全的方面。而在定义词典时可设置的参数, + 由普通用户设置也是安全的,因此创建词典不必是特权操作。 @@ -64,7 +64,7 @@ CREATE TEXT SEARCH TEMPLATE name ( name - 要创建的全文检索模板名称。该名称可以是模式限定的。 + 要创建的文本检索模板名称。该名称可以是模式限定的。 diff --git a/zh/17/ref/drop_opclass.sgml b/zh/17/ref/drop_opclass.sgml index 9d67dc64..545a2517 100644 --- a/zh/17/ref/drop_opclass.sgml +++ b/zh/17/ref/drop_opclass.sgml @@ -110,7 +110,7 @@ DROP OPERATOR CLASS [ IF EXISTS ] name示例 - 移除 B-tree 操作符类widget_ops: + 移除 B-树操作符类widget_ops DROP OPERATOR CLASS widget_ops USING btree; diff --git a/zh/17/ref/drop_tsconfig.sgml b/zh/17/ref/drop_tsconfig.sgml index ea139802..b3ebb9d1 100644 --- a/zh/17/ref/drop_tsconfig.sgml +++ b/zh/17/ref/drop_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH CONFIGURATION - 移除一个文本搜索配置 + 移除一个文本检索配置 @@ -29,7 +29,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 描述 - DROP TEXT SEARCH CONFIGURATION删除一个现有文本搜索配置。 + DROP TEXT SEARCH CONFIGURATION删除一个现有文本检索配置。 要执行此命令,你必须是该配置的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name IF EXISTS - 如果该文本搜索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name name - 现有文本搜索配置的名称(可以被模式限定)。 + 现有文本检索配置的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name CASCADE - 自动删除依赖于该文本搜索配置的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索配置的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name RESTRICT - 如果有任何对象依赖于该文本搜索配置,则拒绝删除该配置。这是默认值。 + 如果有任何对象依赖于该文本检索配置,则拒绝删除该配置。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 示例 - 移除文本搜索配置my_english: + 移除文本检索配置my_english DROP TEXT SEARCH CONFIGURATION my_english; 如果已有索引在to_tsvector调用中引用了该配置, - 此命令将不会成功。加上CASCADE可以在删除该文本搜索配置的同时删除这类索引。 + 此命令将不会成功。加上CASCADE可以在删除该文本检索配置的同时删除这类索引。 diff --git a/zh/17/ref/drop_tsdictionary.sgml b/zh/17/ref/drop_tsdictionary.sgml index 316c5d00..0f7751a1 100644 --- a/zh/17/ref/drop_tsdictionary.sgml +++ b/zh/17/ref/drop_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH DICTIONARY - 移除一个文本搜索字典 + 移除一个文本检索词典 @@ -29,8 +29,8 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name描述 - DROP TEXT SEARCH DICTIONARY删除一个现有文本搜索字典。 - 要执行此命令,你必须是该字典的拥有者。 + DROP TEXT SEARCH DICTIONARY删除一个现有文本检索词典。 + 要执行此命令,你必须是该词典的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索字典不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索词典不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] namename - 一个现有文本搜索字典的名称(可以被模式限定)。 + 一个现有文本检索词典的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索字典的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索词典的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索字典,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索词典,则拒绝删除它。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name示例 - 移除文本搜索字典english: + 移除文本检索词典english DROP TEXT SEARCH DICTIONARY english; - 如果已有文本搜索配置使用该字典,此命令将不会成功。 - 加上CASCADE可以在删除字典的同时删除这类配置。 + 如果已有文本检索配置使用该词典,此命令将不会成功。 + 加上CASCADE可以在删除词典的同时删除这类配置。 diff --git a/zh/17/ref/drop_tsparser.sgml b/zh/17/ref/drop_tsparser.sgml index a65f47be..ea74f0f8 100644 --- a/zh/17/ref/drop_tsparser.sgml +++ b/zh/17/ref/drop_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH PARSER - 移除一个文本搜索解析器 + 移除一个文本检索解析器 @@ -29,7 +29,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name描述 - DROP TEXT SEARCH PARSER删除一个现有文本搜索解析器。 + DROP TEXT SEARCH PARSER删除一个现有文本检索解析器。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] namename - 一个现有文本搜索解析器的名称(可以被模式限定)。 + 一个现有文本检索解析器的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索解析器的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索解析器的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索解析器,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索解析器,则拒绝删除它。这是默认值。 @@ -82,13 +82,13 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name示例 - 移除文本搜索解析器my_parser: + 移除文本检索解析器my_parser DROP TEXT SEARCH PARSER my_parser; - 如果已有文本搜索配置使用该解析器,此命令将不会成功。 + 如果已有文本检索配置使用该解析器,此命令将不会成功。 加上CASCADE可以在删除解析器的同时删除这类配置。 diff --git a/zh/17/ref/drop_tstemplate.sgml b/zh/17/ref/drop_tstemplate.sgml index fa1faab0..3a44c927 100644 --- a/zh/17/ref/drop_tstemplate.sgml +++ b/zh/17/ref/drop_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH TEMPLATE - 移除一个文本搜索模板 + 移除一个文本检索模板 @@ -29,7 +29,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name描述 - DROP TEXT SEARCH TEMPLATE删除一个现有文本搜索模板。 + DROP TEXT SEARCH TEMPLATE删除一个现有文本检索模板。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] namename - 现有文本搜索模板的名称(可以被模式限定)。 + 现有文本检索模板的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索模板的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索模板的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索模板,则拒绝删除该模板。这是默认值。 + 如果有任何对象依赖于该文本检索模板,则拒绝删除该模板。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name示例 - 移除文本搜索模板thesaurus: + 移除文本检索模板thesaurus DROP TEXT SEARCH TEMPLATE thesaurus; - 如果已有文本搜索字典使用该模板,此命令将不会成功。加上CASCADE - 可以在删除该模板的同时删除这类字典。 + 如果已有文本检索词典使用该模板,此命令将不会成功。加上CASCADE + 可以在删除该模板的同时删除这类词典。 diff --git a/zh/17/ref/initdb.sgml b/zh/17/ref/initdb.sgml index dd5b2375..c8219102 100644 --- a/zh/17/ref/initdb.sgml +++ b/zh/17/ref/initdb.sgml @@ -192,7 +192,7 @@ PostgreSQL documentation - + @@ -223,21 +223,16 @@ PostgreSQL documentation - + - 对数据页启用校验和,以帮助检测原本会悄无声息发生的、由 I/O 系统导致的损坏。 - 该项默认启用;使用可禁用校验和。 - - - - 启用校验和可能会带来小幅性能损失。如果启用,就会为所有数据库中的所有对象计算校验和。 - 所有校验和失败都会在 - - pg_stat_database视图中报告。详见 - 。 + 在数据页上使用校验和,帮助检测 I/O 系统造成的、否则可能悄无声息的数据损坏。 + 启用校验和可能会带来明显的性能损失。如果启用,就会为所有数据库中的所有对象计算校验和。 + 所有校验和失败都会在 + pg_stat_database视图中报告。 + 详见 @@ -303,15 +298,6 @@ PostgreSQL documentation - - - - - 不启用数据校验和。 - - - - @@ -326,7 +312,7 @@ PostgreSQL documentation - 设置默认文本搜索配置。更多信息见 + 设置默认文本检索配置。更多信息见 @@ -453,27 +439,6 @@ PostgreSQL documentation - - - - - 默认情况下,initdb会将所有数据库文件安全地写入磁盘。 - 该选项指示initdb跳过同步各个数据库目录中的所有文件、这些数据库目录本身 - 以及表空间目录,也就是base子目录中的所有内容和任何其他表空间目录。 - 其他文件,例如pg_walpg_xact中的文件, - 仍会被同步,除非也指定了。 - - - 请注意,如果与 - 一起使用,上述部分或全部文件与目录仍会被同步, - 因为syncfs处理的是整个文件系统。 - - - 该选项主要供那些会另行确保这些被跳过文件已同步到磁盘的工具在内部使用。 - - - - diff --git a/zh/17/ref/pgbench.sgml b/zh/17/ref/pgbench.sgml index e0fa9e55..72e203d8 100644 --- a/zh/17/ref/pgbench.sgml +++ b/zh/17/ref/pgbench.sgml @@ -39,7 +39,7 @@ PostgreSQL documentation 描述 - pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,必要时可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 + pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,也可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 @@ -69,7 +69,7 @@ tps = 896.967014 (without initial connection time) - 默认的类 TPC-B 事务测试要求预先建立特定的表。应使用(initialize)选项调用pgbench来创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: + 默认的类 TPC-B 事务测试要求预先建立特定的表。应使用(初始化)选项调用pgbench来创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: pgbench -i other-options dbname @@ -89,14 +89,14 @@ pgbench -i other-options 在默认的比例因子 1 下,这些表最初包含如下行数: -table # of rows +表 行数 --------------------------------- pgbench_branches 1 pgbench_tellers 10 pgbench_accounts 100000 pgbench_history 0 - 可以使用(比例因子)选项来增加行数,而且在大多数场景下也确实应该这样做。此时还可以配合使用(fillfactor)选项。 + 可以使用(比例因子)选项来增加行数,而且在大多数场景下通常也应该这样做。此时还可以配合使用(fillfactor)选项。 @@ -116,7 +116,7 @@ pgbench options d 选项 - 下面分成三个部分。数据库初始化期间使用的选项和运行基准时会使用不同的选项,但也有一些选项在两种情况下都使用。 + 以下内容分为三个小节。数据库初始化和运行基准测试时使用不同的选项,但有些选项在这两种情况下都适用。 @@ -191,12 +191,12 @@ pgbench options d 生成数据并将其装载到标准表中,替换其中任何已有数据。 - 使用g(客户端生成数据)时,数据由pgbench客户端生成,再通过COPY发送到服务器,因此会大量占用客户端/服务器带宽。对于 14 及以上版本的PostgreSQLpgbench会在普通(非分区)表上使用选项装载数据,以加快后续的VACUUM。使用g时,在为所有表生成数据的过程中,每生成 100,000 行会输出一条日志消息。 + 使用g(客户端生成数据)时,数据由pgbench客户端生成,再通过COPY发送到服务器,因此会大量占用客户端/服务器带宽。对于 14 及以上版本的PostgreSQLpgbench会使用选项装载数据,以加快后续的VACUUM;但启用分区时,pgbench_accounts表除外。使用g时,在为所有表生成数据的过程中,每生成 100,000 行会输出一条日志消息。 使用G(服务器端生成数据)时, pgbench客户端只发送较小的查询,随后实际数据在服务器端生成。 - 这种方式几乎不需要额外带宽,但服务器会承担更多工作。 + 这种方式不需要大量带宽,但服务器会承担更多工作。 使用G时,生成数据期间不会打印任何进度消息。 @@ -505,13 +505,13 @@ pgbench options d 用于向服务器提交查询的协议: - simple: 使用简单查询协议。 + simple:使用简单查询协议。 - extended: 使用扩展查询协议。 + extended:使用扩展查询协议。 - prepared: 使用带有预备语句的扩展查询协议。 + prepared:使用带有预备语句的扩展查询协议。 @@ -572,7 +572,7 @@ pgbench options d - 在基准测试完成后,报告每条语句的以下统计信息:平均延迟(从客户端视角看到的语句执行时间)、失败次数,以及该语句因串行化或死锁错误而发生的重试次数。仅当选项不等于 1 时,报告才会显示重试统计信息。 + 在基准测试完成后,报告每条命令的以下统计信息:平均延迟(从客户端视角看到的语句执行时间)、失败次数,以及该命令因串行化或死锁错误而发生的重试次数。仅当选项不等于 1 时,报告才会显示重试统计信息。 @@ -607,7 +607,7 @@ pgbench options d 较高的计划滞后时间表明,在所选客户端数和线程数下,系统无法以指定速率处理事务。 当平均事务执行时间长于事务之间的计划间隔时,后续事务会不断进一步落后, - 而计划滞后时间也会随着测试持续时间增加。在这种情况下,只能降低指定的事务速率。 + 而计划滞后时间也会随着测试持续时间增加。在这种情况下,需要降低指定的事务速率。 @@ -619,7 +619,7 @@ pgbench options d pgbench输出中报告指定的比例因子。 - 对于内置测试,这通常没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 + 对于内置测试,这没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 但在只测试自定义基准(选项)时, 除非使用此选项,否则比例因子会被报告为 1。 @@ -733,7 +733,7 @@ pgbench options d 启用对出现串行化/死锁错误的事务进行重试,并设置最大尝试次数。此选项可与 - 组合使用,后者限制所有事务尝试的总耗时; + 组合使用,后者限制同一事务所有尝试的总耗时; 此外,如果没有, 则不能使用无限次尝试(--max-tries=0)。 默认值为 1,出现串行化/死锁错误的事务不会重试。有关此类事务重试的更多信息,见 @@ -813,7 +813,7 @@ pgbench options d - 打印关于所有错误和失败的消息(即不会重试的错误),包括超出了哪一种重试限制,以及对于串行化/死锁失败超出的幅度。(请注意,这种情况下输出量可能会显著增加。)更多信息见。 + 打印关于所有错误和失败(不再重试的错误)的消息,包括超出了哪一种重试限制,以及对于串行化/死锁失败超出的幅度。(请注意,这种情况下输出量可能会显著增加。)更多信息见 @@ -941,7 +941,7 @@ pgbench options d 注解 - + 在<application>pgbench</application>中实际执行的<quote>事务</quote>是什么? @@ -996,7 +996,7 @@ pgbench options d - 假定pgbench脚本不包含不完整的 SQL 事务块。如果在运行时客户端在尚未完成最后一个事务块时就到达脚本末尾,它将被中止。 + 假定pgbench脚本不包含不完整的 SQL 事务块。如果在运行时客户端在尚未完成最后一个事务块时就到达脚本末尾,该客户端将被中止。 @@ -1033,7 +1033,7 @@ pgbench options d default_seed - 默认在哈希和伪随机置换函数中使用的种子 + 默认在 hash 和伪随机置换函数中使用的种子 @@ -1050,7 +1050,7 @@ pgbench options d - 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令及其参数之间以空白分隔。支持的元命令如下: + 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令的参数以空白分隔。支持的元命令如下: @@ -1088,7 +1088,7 @@ UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid RETURNING abalance \gset --- compound of two queries +-- 两个查询的组合 SELECT 1 \; SELECT 2 AS two, 3 AS three \gset p_ SELECT 4 AS four \; SELECT 5 AS five \aset @@ -1180,7 +1180,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset - command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在其开头再写一个冒号。 + command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在argument开头再写一个冒号。 @@ -1218,7 +1218,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset - 这组命令用于实现 SQL 语句的流水线执行。流水线必须以\startpipeline开始,并以\endpipeline结束;在两者之间可以出现任意数量的\syncpipeline,它会发送一个sync 消息,但不会结束当前流水线,同时会刷新发送缓冲区。在流水线模式下,语句会发送到服务器,而不等待前一条语句的结果。更多细节见。流水线模式要求使用扩展查询协议。 + 这组命令用于实现 SQL 语句的管道执行。管道必须以\startpipeline开始,并以\endpipeline结束;在两者之间可以出现任意数量的\syncpipeline,它会发送一个sync 消息,既不会结束当前管道,也不会刷新发送缓冲区。在管道模式下,语句会发送到服务器,而不等待前一条语句的结果。更多细节见。管道模式要求使用扩展查询协议。 @@ -1514,7 +1514,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 加 + 加法 5 + 4 @@ -1528,7 +1528,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 减 + 减法 3 - 2.0 @@ -1542,7 +1542,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 乘 + 乘法 5 * 4 @@ -1556,7 +1556,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 除法(如果两个输入都是整数,则将结果截断为零) + 除法(如果两个输入都是整数,则将结果向零截断) 5 / 3 @@ -1584,7 +1584,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 取反 + 取相反数 - 2.0 @@ -1674,7 +1674,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset double - 指数(e 的给定次幂) + 指数函数(e 的给定次幂) exp(1.0) @@ -1716,7 +1716,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算 FNV-1a 哈希。 + 计算 FNV-1a hash hash_fnv1a(10, 5432) @@ -1730,7 +1730,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算 MurmurHash2 哈希。 + 计算 MurmurHash2 hash hash_murmur2(10, 5432) @@ -1800,8 +1800,8 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - i的排列值,范围在[0, size)内。 - 它表示i(模size)在整数0...size-1的伪随机排列中的新位置;该排列由seed参数化,详见下文。 + i的置换值,范围在[0, size)内。 + 它表示i(模size)在整数0...size-1的伪随机置换中的新位置;该置换由seed参数化,详见下文。 permute(0, 4) @@ -1861,7 +1861,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算[lb, ub]中的指数分布随机整数,如下所示。 + 计算[lb, ub]中的指数分布随机整数,详见下文。 random_exponential(1, 10, 3.0) @@ -1875,7 +1875,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算[lb, ub]中的高斯分布随机整数,如下所示。 + 计算[lb, ub]中的高斯分布随机整数,详见下文。 random_gaussian(1, 10, 2.5) @@ -1922,7 +1922,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset - 对于指数分布,parameter通过在parameter处截断一个快速衰减的指数分布,再将其投影到边界之间的整数上,从而控制分布。准确地说, + 对于指数分布,parameter通过在parameter处截断一个快速衰减的指数分布,再将其投影到边界之间的整数上,从而控制分布。准确地说,令 f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) @@ -1930,7 +1930,7 @@ f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) - 直观地说,parameter越大,越靠近min的值越容易被抽到,而越靠近max的值越不容易被抽到。parameter越接近 0,分布就越平坦(也就越均匀)。对这种分布的一个粗略近似是:范围内最靠近min的那 1% 常见值,大约会占到parameter% 的抽样次数。parameter必须严格大于 0。 + 直观地说,parameter越大,越靠近min的值越容易被抽到,而越靠近max的值越不容易被抽到。parameter越接近 0,分布就越平坦(也就越均匀)。对这种分布的一个粗略近似是:范围内出现频率最高的 1% 的值,即最靠近min的那些值,大约会占到parameter% 的抽样次数。parameter必须严格大于 0。 @@ -1942,7 +1942,7 @@ f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / (2.0 * PHI(parameter) - 1) - 则minmax(包含边界)之间的值i被抽中的概率为:f(i + 0.5) - f(i - 0.5)。直观地说,parameter越大,越靠近区间中间的值被抽到的频率越高,而越靠近minmax边界的值被抽到的频率越低。大约 67% 的值会落在区间中部1.0 / parameter这一段内,也就是均值两侧各0.5 / parameter的范围内;约 95% 的值会落在区间中部2.0 / parameter这一段内,也就是均值两侧各1.0 / parameter的范围内。例如,如果parameter为 4.0,则 67% 的值会落在区间中间四分之一(1.0 / 4.0)内,也就是从3.0 / 8.05.0 / 8.0;95% 的值会落在区间中间一半(2.0 / 4.0)内,也就是第二和第三四分位。允许的最小parameter值为 2.0。 + 则minmax(包含边界)之间的值i被抽中的概率为:f(i + 0.5) - f(i - 0.5)。直观地说,parameter越大,越靠近区间中间的值被抽到的频率越高,而越靠近minmax边界的值被抽到的频率越低。大约 67% 的值会落在区间中部1.0 / parameter这一段内,也就是均值两侧各占区间长度0.5 / parameter的范围内;约 95% 的值会落在区间中部2.0 / parameter这一段内,也就是均值两侧各占区间长度1.0 / parameter的范围内。例如,如果parameter为 4.0,则 67% 的值会落在区间中间四分之一(1.0 / 4.0)内,也就是从3.0 / 8.05.0 / 8.0;95% 的值会落在区间中间一半(2.0 / 4.0)内,也就是第二和第三四分位。允许的最小parameter值为 2.0。 @@ -1974,12 +1974,12 @@ f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / - 哈希函数hashhash_murmur2hash_fnv1a都接受一个输入值和一个可选的种子参数。 - 如果没有提供种子,则会使用:default_seed的值;除非通过命令行选项覆盖,否则该值会被随机初始化。 + Hash 函数hashhash_murmur2hash_fnv1a都接受一个输入值和一个可选的种子参数。 + 如果没有提供种子,则会使用:default_seed的值;除非通过命令行-D选项覆盖,否则该值会被随机初始化。 - permute接受一个输入值、一个大小参数以及一个可选的种子参数。它会生成范围[0, size)内整数的伪随机排列,并返回输入值在该排列中的索引。如果未指定种子,则默认使用:default_seed。与哈希函数不同,permute保证输出值中不会出现冲突或空洞。区间之外的输入值会按size取模解释。如果size不是正数,该函数会报错。permute可用于打散诸如random_zipfianrandom_exponential这类非均匀随机函数的分布,使那些更常抽到的值不再具有显而易见的相关性。例如,下面的pgbench脚本模拟了社交媒体和博客平台中一种可能的真实工作负载,其中少数账户会产生过量负载: + permute接受一个输入值、一个大小参数以及一个可选的种子参数。它会生成范围[0, size)内整数的伪随机置换,并返回输入值在该置换中的索引。所选置换由种子参数决定;如果未指定种子,则默认使用:default_seed。与 hash 函数不同,permute保证输出值中不会出现冲突或空洞。区间之外的输入值会按size取模解释。如果size不是正数,该函数会报错。permute可用于打散诸如random_zipfianrandom_exponential这类非均匀随机函数的分布,使那些更常抽到的值不再具有显而易见的相关性。例如,下面的pgbench脚本模拟了社交媒体和博客平台中一种可能的真实工作负载,其中少数账户会产生过量负载: \set size 1000000 @@ -2036,7 +2036,7 @@ END; - 每行日志文件描述一个事务。 + 日志文件的每一行描述一个事务。 它包含以下以空格分隔的字段: @@ -2436,7 +2436,7 @@ statement latencies in milliseconds and failures: 使用可串行化默认事务隔离级别的默认脚本的另一个输出示例 - (PGOPTIONS='-c default_transaction_isolation=serializable' pgbench ...): + (PGOPTIONS='-c default_transaction_isolation=serializable' pgbench ...): starting vacuum...end. transaction type: <builtin: TPC-B (sort of)> @@ -2479,7 +2479,7 @@ statement latencies in milliseconds, failures and retries: - + 失败和串行化/死锁重试 @@ -2537,7 +2537,7 @@ statement latencies in milliseconds, failures and retries: - 不指定选项时,事务在发生串行化或死锁错误后永远不会重试,因为其默认值为 1。可以使用无限次尝试(--max-tries=0)并配合选项,仅限制重试的最长时间。也可以使用选项,在无限次尝试的情况下限制基准测试持续时间。 + 不指定选项时,事务在发生串行化或死锁错误后永远不会重试,因为其默认值为 1。可以使用无限次尝试(--max-tries=0)并配合选项,仅限制尝试的最长总时间。也可以使用选项,在无限次尝试的情况下限制基准测试持续时间。 @@ -2558,7 +2558,7 @@ statement latencies in milliseconds, failures and retries: - 如果希望在逐事务日志、聚合日志以及主报告和逐脚本报告中按基本类型对失败进行分组,请使用选项。如果还希望按类型区分所有错误和失败(即不会重试的错误),包括超出了哪一种重试限制,以及串行化/死锁失败超出了多少,请使用选项。 + 如果希望在逐事务日志、聚合日志以及主报告和逐脚本报告中按基本类型对失败进行分组,请使用选项。如果还希望按类型区分所有错误和失败(不再重试的错误),包括超出了哪一种重试限制,以及串行化/死锁失败超出了多少,请使用选项。 @@ -2590,7 +2590,7 @@ PGOPTIONS='-c default_table_access_method=wuzza' - 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和空闲空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 + 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和无效空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 diff --git a/zh/17/ref/psql-ref.sgml b/zh/17/ref/psql-ref.sgml index 902beb87..c1ef7f48 100644 --- a/zh/17/ref/psql-ref.sgml +++ b/zh/17/ref/psql-ref.sgml @@ -47,7 +47,7 @@ PostgreSQL documentation - 把所有非空输入行按照它们被读入的形式打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 + 在读入时将所有非空输入行打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 all @@ -58,7 +58,7 @@ PostgreSQL documentation - 切换到非对齐输出模式(默认输出模式是对齐的)。这等效于\pset format unaligned。 + 切换到非对齐输出模式(默认输出模式是aligned)。这等效于\pset format unaligned @@ -78,10 +78,10 @@ PostgreSQL documentation - 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,直到它处理完序列中所有的选项之后终止。 + 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,而是在按顺序处理完所有选项后终止。 - command必须是一个服务器完全可解析的命令字符串(即不包含psql相关的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: + command必须是一个服务器完全可解析的命令字符串(即不包含psql专有的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: psql -c '\x' -c 'SELECT * FROM foo;' @@ -172,7 +172,7 @@ EOF - 使用separator作为非对齐输出的域分隔符。这等效于\pset fieldsep或者\f。 + 使用separator作为非对齐输出的字段分隔符。这等效于\pset fieldsep或者\f @@ -246,7 +246,7 @@ EOF - 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。 + 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展名。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。 @@ -266,7 +266,7 @@ EOF - 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息以及多种输出。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon。 + 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息和各种提示信息。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon @@ -286,7 +286,7 @@ EOF - 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户一个可以取消执行的选项。使用这个选项可以调试脚本。 + 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户,并允许取消执行。使用这个选项可以调试脚本。 @@ -296,7 +296,7 @@ EOF - 运行在单行模式中,其中新行会终止一个 SQL 命令,就像分号的作用一样。 + 运行在单行模式中,其中换行符会终止一个 SQL 命令,就像分号的作用一样。 @@ -322,7 +322,7 @@ EOF - 指定要替换HTML table标签的选项。详见\pset tableattr。 + 指定要放在HTML table标签内的选项。详见\pset tableattr @@ -343,7 +343,7 @@ EOF - 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要重置一个变量,去掉等号就行。要把一个变量置为空值,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 + 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要取消变量的设置,去掉等号就行。要把一个变量设为空字符串,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 @@ -405,7 +405,7 @@ EOF - 不读取启动文件(要么是系统范围的psqlrc文件,要么是用户的~/.psqlrc文件)。 + 不读取启动文件(既不读取系统范围的psqlrc文件,也不读取用户的~/.psqlrc文件)。 @@ -415,7 +415,7 @@ EOF - 设置非对齐输出的域分隔符为零字节。这等效于\pset fieldsep_zero。 + 设置非对齐输出的字段分隔符为零字节。这等效于\pset fieldsep_zero @@ -425,7 +425,7 @@ EOF - 设置非对齐输出的记录分隔符为零字节。例如,这对与xargs -0配合有关。这等效于\pset recordsep_zero。 + 设置非对齐输出的记录分隔符为零字节。例如,这有助于与xargs -0配合使用。这等效于\pset recordsep_zero @@ -438,7 +438,7 @@ EOF 这个选项只能与一个或多个和/或选项结合使用。 它会导致psql在第一个这样的选项之前发出一个BEGIN命令, 并在最后一个选项之后发出一个COMMIT命令,从而将所有命令包装成一个单独的事务。 - 如果任何命令失败且变量ON_ERROR_STOP被设置,那么会发送一个ROLLBACK命令。 + 如果任何命令失败且变量ON_ERROR_STOP被设置,则会改为发送一个ROLLBACK命令。 这确保要么所有命令都成功完成,要么不应用任何更改。 @@ -550,7 +550,7 @@ testdb=> 元命令 - 你输入到psql中的任何以未加引用的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 + 你输入到psql中的任何以未加引号的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 @@ -567,7 +567,7 @@ testdb=> - 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉尾随换行)会替换反引号中的文本。在反引号包围的文本内部,不会发生特殊引用或其他处理,只有一种例外:如果出现:variable_name,且variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会被适当地引用成单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于回车和换行字符在所有平台上都无法安全引用,当变量值中出现这类字符时,:'variable_name'这种形式会打印错误消息,并且不会替换变量值。 + 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉末尾的换行符)会替换反引号中的文本。在反引号包围的文本内部,不会进行特殊的引号处理或其他处理,但出现:variable_name时,如果variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会适当地加上引号,使其成为单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于无法保证在所有平台上都能对回车和换行字符安全地加引号,当变量值中出现这类字符时,:'variable_name'形式会打印错误消息,并且不会替换变量值。 @@ -579,8 +579,8 @@ testdb=> - 很多元命令作用在当前查询缓冲区上。这就是一个缓冲区而已,它保存任何已经被键入但是还没有发送到服务器执行的SQL命令文本。这将包括之前输入的行以及在该元命令同一行上出现在前面的任何文本。 - + 许多元命令作用于当前查询缓冲区。这只是一个保存已输入但尚未发送到服务器执行的 SQL 命令文本的缓冲区。其中既包括先前输入的行,也包括同一行上位于元命令之前的文本。 + @@ -591,7 +591,7 @@ testdb=> \a - 如果当前表格输出格式是不对齐,则切换为对齐;否则切换为不对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset。 + 如果当前表格输出格式是非对齐,则切换为对齐;否则切换为非对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset @@ -628,7 +628,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \c\connect [ -reuse-previous=on|off ] [ dbname [ username ] [ host ] [ port ] | conninfo ] - 建立到PostgreSQL服务器的新连接。可以使用位置语法(数据库名称、用户、主机和端口中的一个或多个)指定要使用的连接参数,也可以使用详细说明在中的conninfo连接字符串。如果没有给出参数,则使用与之前相同的参数建立新连接。 + 建立到PostgreSQL服务器的新连接。可以使用位置语法(数据库名称、用户、主机和端口中的一个或多个)指定要使用的连接参数,也可以使用conninfo连接字符串,详见。如果没有给出参数,则使用与之前相同的参数建立新连接。 @@ -644,7 +644,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g 默认情况下,参数在位置语法中被重用,但在给定conninfo字符串时不会被重用。 传递-reuse-previous=on-reuse-previous=off作为第一个参数将覆盖该默认设置。 如果参数被重用,则任何未明确指定为位置参数或在conninfo字符串中的参数将从现有连接的参数中获取。 - 一个例外是,如果使用位置语法将host设置更改为其先前值,则现有连接参数中存在的任何hostaddr设置将被删除。 + 一个例外是,如果使用位置语法更改host设置,使其不同于先前的值,则现有连接参数中存在的任何hostaddr设置将被删除。 此外,仅当用户、主机和端口设置未更改时,才会重用现有连接使用的任何密码。 当命令既不指定也不重用特定参数时,将使用libpq的默认值。 @@ -666,7 +666,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g => \c mydb myuser host.dom 6432 => \c service=foo => \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable" -=> \c -reuse-previous=on sslmode=require -- changes only sslmode +=> \c -reuse-previous=on sslmode=require -- 仅更改 sslmode => \c postgresql://tom@localhost/mydb?application_name=myapp @@ -676,11 +676,8 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \C [ title ] - 设置作为查询结果打印的任何表格的标题,或取消任何这样的标题。此命令等效于 - \pset title title。(此命令的名称源自caption, - 因为它以前仅用于设置HTML表格中的标题。) - + 设置作为查询结果打印的表的标题,或取消此类标题。该命令等价于\pset title title。(此命令的名称源自caption,因为它过去只用于设置HTML表的标题。) + @@ -688,14 +685,11 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \cd [ directory ] - 将当前工作目录更改为 - directory。如果没有参数,则切换到当前用户的主目录。关于如何确定主目录,请参见 。 - + 将当前工作目录更改为directory。如果没有参数,则切换到当前用户的主目录。 + - - 要打印当前工作目录,请使用\! pwd。 - + 要打印当前工作目录,请使用\! pwd @@ -704,14 +698,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \conninfo - - 输出当前数据库连接的信息;如果正在使用 SSL,也包括与 SSL 相关的信息。 - - - 请注意,Client User 字段显示的是连接建立时的用户,而 - Superuser 字段表示当前用户(在当前执行上下文中)是否具有超级用户权限。这两个用户通常相同,但也可能不同,例如当前用户曾通过 - SET ROLE 命令被更改。 - + 输出当前数据库连接的信息。 @@ -760,9 +747,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g - 这些操作不如以文件或程序作为数据源或目标的 SQL - COPY 命令高效,因为所有数据都必须通过客户端/服务器连接传输。对于大量数据,使用 SQL - 命令可能更合适。 + 这些操作不如以文件或程序作为数据源或目标的SQL COPY命令高效,因为所有数据都必须通过客户端/服务器连接传输。对于大量数据,使用SQL命令可能更合适。另外,由于采用这种数据转送方式,CSV模式下的\copy ... from会错误地把单独占据一行的\.数据值当作输入结束标记。 @@ -788,46 +773,24 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g ] ] ] ] - 执行当前查询缓冲区(类似于\g)并在交叉表格中显示结果。 - 查询必须返回至少三列。 - 由colV标识的输出列成为垂直标题, - 由colH标识的输出列成为水平标题。 - colD标识要在网格中显示的输出列。 - sortcolH标识水平标题的可选排序列。 - + 执行当前查询缓冲区(与\g类似),并以交叉表网格显示结果。查询必须返回至少三列。由colV标识的输出列成为纵向表头,由colH标识的输出列成为横向表头。colD标识要在网格中显示的输出列。sortcolH标识横向表头的可选排序列。 + - 每个列规范可以是列号(从1开始)或列名。列名遵循通常的SQL大小写折叠和引用规则。如果省略, - colV被视为第1列, - colH被视为第2列。 - colH必须与 - colV不同。 - 如果未指定colD,则查询结果中必须恰好有三列, - 并且既不是colV也不是 - colH的列被视为 - colD。 - + 每个列指定都可以是列号(从 1 开始)或列名。通常的 SQL 大小写折叠和加引号规则适用于列名。如果省略,colV取第 1 列,colH取第 2 列。colH必须不同于colV。如果未指定colD,查询结果必须恰好有三列,既不是colV也不是colH的那一列被用作colD。 + - 垂直标题显示为最左侧的列,包含在列colV中找到的值, - 与查询结果中的顺序相同,但删除了重复项。 - + 纵向表头显示为最左列,包含colV列中的值,其顺序与查询结果中相同,但会移除重复值。 + - 水平标题作为第一行显示,包含在列colH中找到的值,去除重复项。 - 默认情况下,这些值按照查询结果中的顺序显示。但是,如果给定可选的sortcolH参数, - 它标识一个列,其值必须是整数,colH中的值将按照相应的 - sortcolH值排序后显示在水平标题中。 - + 横向表头显示为第一行,包含colH列中的值,并移除重复值。默认情况下,它们按查询结果中的相同顺序显示。但如果给出了可选的sortcolH参数,它所标识的列的值必须是整数,而colH中的值会按照对应的sortcolH值排序后显示在横向表头中。 + - 在交叉表格中,对于每个colH列的非重复值x, - 和每个colV列的非重复值y, - 位于交点(x,y)的单元格包含查询结果行中colD列的值, - 其中colH列的值为x, - colV列的值为y。 - 如果没有这样的行,则单元格为空。如果有多个这样的行,则报告错误。 - + 在交叉表网格中,对于colH中的每个不同值xcolV中的每个不同值y,交点(x,y)处的单元格包含查询结果中colD列的值,该结果行的colH值为xcolV值为y。如果没有这样的行,单元格为空。如果存在多条这样的行,则报错。 + @@ -849,11 +812,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g - 命令形式\d+与前者相同,只是会显示更多信息:显示与表列相关的任何注释, - 表中的OID的存在,如果关系是视图,则显示视图定义,非默认的 - 复制标识设置以及 - 如果关系具有访问方法,则显示 - 访问方法名称。 + 命令形式\d+与前者相同,但会显示更多信息:表列关联的注释、表是否包含 OID、当关系为视图时的视图定义、非默认的复制标识设置,以及当关系具有访问方法时的访问方法名称。 @@ -928,9 +887,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g - - 列出与操作符族关联的操作符(参见 )。如果指定了 access-method-pattern,则只列出与名称匹配该模式的访问方法所关联的操作符族成员。如果指定了 operator-family-pattern,则只列出名称与该模式匹配的操作符族成员。如果在命令名后追加 +,则每个操作符都会连同其排序操作符族(如果它是排序操作符)以及其底层函数是否防漏一起列出。 - + 列出与操作符族关联的操作符(见)。如果指定了access-method-pattern,则只列出关联访问方法的名称匹配该模式的操作符族成员。如果指定了operator-family-pattern,则只列出名称匹配该模式的操作符族成员。如果在命令名后附加+,还会列出每个操作符的排序操作符族(如果它是一个排序操作符)。 @@ -983,9 +940,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \dC[+] [ pattern ] - - 列出类型转换。如果指定了 pattern,则只列出其源类型或目标类型与模式匹配的类型转换。如果在命令名后追加 +,则会显示每个类型转换的附加信息,包括其底层函数是否防漏,以及该类型转换的描述。 - + 列出类型转换。如果指定了pattern,则只列出源类型或目标类型匹配该模式的类型转换。如果在命令名后附加+,还会列出每个对象关联的描述。 @@ -996,7 +951,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g 显示constraintoperator classoperator familyrule和 - trigger类型对象的描述。所有其他注释可以通过相应的反斜杠命令查看这些对象类型。 + trigger类型对象的描述。其他注释可通过对应对象类型的反斜线命令查看。 \dd 显示与 @@ -1021,7 +976,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g - \ddp[ pattern ] + \ddp [ pattern ] 列出默认访问权限设置。对于每个默认权限设置已偏离内置默认值的角色(以及适用时的模式),都会显示一条记录。如果指定了 pattern,则只列出角色名或模式名与模式匹配的记录。 @@ -1056,10 +1011,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \des[+] [ pattern ] - - 列出外部服务器(助记符:external - servers)。如果指定了 pattern,则只列出名称与模式匹配的服务器。如果在命令名后追加 +,则会显示每个服务器的完整描述,包括服务器的访问权限、类型、版本、选项和描述。 - + 列出外部服务器(助记词:external servers)。如果指定了pattern,则只列出名称匹配该模式的服务器。如果使用\des+形式,则显示每个服务器的完整说明,包括服务器的访问权限、类型、版本、选项和描述。 @@ -1067,9 +1019,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \det[+] [ pattern ] - - 列出外部表(助记符:external tables)。如果指定了 pattern,则只列出表名或模式名与模式匹配的条目。如果在命令名后追加 +,则还会显示通用选项以及外部表描述。 - + 列出外部表(助记词:external tables)。如果指定了pattern,则只列出表名或模式名匹配该模式的条目。如果使用\det+形式,还会显示通用选项和外部表描述。 @@ -1077,15 +1027,10 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \deu[+] [ pattern ] - - 列出用户映射(助记符:external - users)。如果指定了 pattern,则只列出用户名与模式匹配的映射。如果在命令名后追加 +,则会显示每个映射的附加信息。 - + 列出用户映射(助记词:external users)。如果指定了pattern,则只列出用户名匹配该模式的映射。如果使用\deu+形式,还会显示每个映射的附加信息。 - - \deu+可能还会显示远程用户的用户名和密码,因此应注意不要泄露它们。 - + \deu+还可能显示远程用户的用户名和密码,因此应注意不要泄露它们。 @@ -1094,10 +1039,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \dew[+] [ pattern ] - - 列出外部数据包装器(助记符:external - wrappers)。如果指定了 pattern,则只列出名称与模式匹配的外部数据包装器。如果在命令名后追加 +,则还会显示外部数据包装器的访问权限、选项和描述。 - + 列出外部数据包装器(助记词:external wrappers)。如果指定了pattern,则只列出名称匹配该模式的外部数据包装器。如果使用\dew+形式,还会显示外部数据包装器的访问权限、选项和描述。 @@ -1108,8 +1050,8 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g 列出函数,以及它们的结果数据类型、参数数据类型和函数类型,函数类型分为 agg(聚合)、normalproceduretriggerwindow。要只显示特定类型的函数,请在命令后添加相应的字母 anptw。如果指定了 pattern,则只显示名称与模式匹配的函数。任何附加参数都是类型名模式,分别与函数第一、第二等参数的类型名匹配。(匹配到的函数可以比你指定的参数更多;若要防止这种情况,可将破折号 - 写成最后一个 arg_pattern。)默认情况下,只显示用户创建的对象;提供模式或 S - 修饰符可包括系统对象。如果在命令名后追加 +,则会显示每个函数的附加信息,包括易变性、并行安全性、所有者、安全分类、是否防漏、访问权限、语言、内部名称(仅适用于 C 和 internal 函数)以及描述。特定函数的源代码可通过 \sf 查看。 + class="parameter">pattern,则只显示名称与模式匹配的函数。任何附加参数都是类型名模式,分别与函数第一、第二等参数的类型名匹配。(匹配到的函数可以比你指定的参数更多;若要防止这种情况,可将连字符 - 写成最后一个 arg_pattern。)默认情况下,只显示用户创建的对象;提供模式或 S + 修饰符可包括系统对象。如果使用 \df+ 形式,则会显示每个函数的附加信息,包括易变性、并行安全性、所有者、安全分类、访问权限、语言、内部名称(仅适用于 C 和 internal 函数)以及描述。特定函数的源代码可通过 \sf 查看。 @@ -1118,36 +1060,28 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \dF[+] [ pattern ] - - 列出文本搜索配置。如果指定了 pattern,则只显示名称与模式匹配的配置。如果在命令名后追加 +,则会显示每个配置的完整描述,包括底层文本搜索解析器以及每种记号类型对应的词典列表。 - + 列出全文检索配置。如果指定了pattern,则只显示名称匹配该模式的配置。如果使用\dF+形式,则显示每个配置的完整说明,包括底层全文检索解析器和每种解析器词元类型的词典列表。 \dFd[+] [ pattern ] - - 列出文本搜索词典。如果指定了 pattern,则只显示名称与模式匹配的词典。如果在命令名后追加 +,则会显示每个所选词典的附加信息,包括底层文本搜索模板和选项值。 - + 列出全文检索词典。如果指定了pattern,则只显示名称匹配该模式的词典。如果使用\dFd+形式,还会显示每个选中词典的附加信息,包括底层全文检索模板和选项值。 \dFp[+] [ pattern ] - - 列出文本搜索解析器。如果指定了 pattern,则只显示名称与模式匹配的解析器。如果在命令名后追加 +,则会显示每个解析器的完整描述,包括底层函数和已识别的记号类型列表。 - + 列出全文检索解析器。如果指定了pattern,则只显示名称匹配该模式的解析器。如果使用\dFp+形式,则显示每个解析器的完整说明,包括底层函数和可识别的词元类型列表。 \dFt[+] [ pattern ] - - 列出文本搜索模板。如果指定了 pattern,则只显示名称与模式匹配的模板。如果在命令名后追加 +,则会显示每个模板的附加信息,包括底层函数名。 - + 列出全文检索模板。如果指定了pattern,则只显示名称匹配该模式的模板。如果使用\dFt+形式,还会显示每个模板的附加信息,包括底层函数名。 @@ -1155,11 +1089,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \dg[S+] [ pattern ] - - 列出数据库角色。(由于 usersgroups 的概念已经统一为 roles,此命令现在等同于 - \du。)默认情况下,只显示用户创建的角色;提供 - S 修饰符可包括系统角色。如果指定了 pattern,则只列出名称与模式匹配的角色。如果在命令名后追加 +,则会显示每个角色的附加信息;目前这会增加每个角色的注释。 - + 列出数据库角色。(由于用户的概念已经统一为角色,此命令现在等价于\du。)默认只显示用户创建的角色;提供S修饰符可包含系统角色。如果指定了pattern,则只列出名称匹配该模式的角色。如果使用\dg+形式,还会显示每个角色的附加信息;目前会增加每个角色的注释。 @@ -1200,7 +1130,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \do[S+] [ pattern [ arg_pattern [ arg_pattern ] ] ] - 列出操作符及其操作数类型和结果类型。如果指定了 pattern,则只列出名称与模式匹配的操作符。如果指定了一个 arg_pattern,则只列出其右参数类型名称与该模式匹配的前缀操作符。如果指定了两个 arg_pattern,则只列出参数类型名称与这些模式匹配的二元操作符。(对于一元操作符未使用的参数,也可以写成 -。)默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 +,则会显示每个操作符的附加信息,包括底层函数名以及它是否防漏。 + 列出操作符及其操作数类型和结果类型。如果指定了 pattern,则只列出名称与模式匹配的操作符。如果指定了一个 arg_pattern,则只列出其右参数类型名称与该模式匹配的前缀操作符。如果指定了两个 arg_pattern,则只列出参数类型名称与这些模式匹配的二元操作符。(对于一元操作符未使用的参数,也可以写成 -。)默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 +,则会显示每个操作符的附加信息,目前仅包括底层函数名。 @@ -1235,34 +1165,20 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \dP[itn+] [ pattern ] - - 列出分区关系。 - 如果pattern被指定, - 则只列出名称与模式匹配的条目。 - 修饰符t(表)和i(索引) - 可以附加到命令,过滤要列出的关系类型。默认情况下,列出分区表和索引。 - + 列出分区关系。如果指定了pattern,则只列出名称匹配该模式的条目。可以在命令后附加修饰符t(表)和i(索引),筛选要列出的关系类型。默认会列出分区表和分区索引。 - - 如果使用修饰符nnested), - 或指定了模式,则将包括非根分区关系,并显示一个列,显示每个 - 分区关系的父级。 - + 如果使用了修饰符nnested),或指定了模式,则会包含非根分区关系,并显示一列,列出每个分区关系的父关系。 - -如果在命令名后追加 +,则还会显示每个关系分区大小的总和以及关系描述。如果 n+ 组合使用,则会显示两个大小:一个包括直接附加的叶分区的总大小,另一个显示包括间接附加子分区在内的所有分区总大小。 - + 如果在命令名后附加+,还会显示每个关系的各个分区的大小之和,以及该关系的描述。如果将n+结合使用,则显示两个大小:一个是直接附加的叶子分区的总大小,另一个是所有分区的总大小,包括间接附加的子分区。 - \drds[ role-pattern [ database-pattern ] ] + \drds [ role-pattern [ database-pattern ] ] - 列出已定义的配置设置。这些设置可以是特定于角色、特定于数据库,或者两者兼有。role-pattern 和 - database-pattern 分别用于选择要列出的特定角色和数据库。如果省略,或者指定了 - *,则会列出所有设置,包括那些未指定角色或数据库的设置。 + 列出已定义的配置设置。这些设置可以特定于角色、特定于数据库,或同时特定于两者。role-patterndatabase-pattern分别用于选择要列出的角色和数据库。省略某个模式参数或将其指定为*时,不会按该参数筛选,还会分别包含不特定于角色或不特定于数据库的设置。 ALTER ROLE和 @@ -1283,7 +1199,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g 默认情况下,只显示授予用户创建角色的成员身份;提供 - S 修饰符可包括系统角色。如果指定了 pattern,则只列出名称与模式匹配的角色。 + S 修饰符可包括系统角色。如果指定了 pattern,则只列出授予名称与模式匹配的角色的成员身份。 @@ -1310,7 +1226,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \dT[S+] [ pattern ] - 列出数据类型。如果指定了 pattern,则只列出名称与模式匹配的类型。如果在命令名后追加 +,则每个类型都会连同其内部名称和大小一起列出;对于 enum 类型,还会显示其允许值以及相关权限。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 + 列出数据类型。如果指定了 pattern,则只列出名称与模式匹配的类型。如果在命令名后追加 +,则每个类型都会连同其内部名称、大小以及相关权限一起列出;对于 enum 类型,还会显示其允许值。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 @@ -1318,25 +1234,19 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \du[S+] [ pattern ] - - 列出数据库角色。(由于 usersgroups 的概念已经统一为 roles,此命令现在等同于 - \dg。)默认情况下,只显示用户创建的角色;提供 - S 修饰符可包括系统角色。如果指定了 pattern,则只列出名称与模式匹配的角色。如果在命令名后追加 +,则会显示每个角色的附加信息;目前这会增加每个角色的注释。 - + 列出数据库角色。(由于用户的概念已经统一为角色,此命令现在等价于\dg。)默认只显示用户创建的角色;提供S修饰符可包含系统角色。如果指定了pattern,则只列出名称匹配该模式的角色。如果使用\du+形式,还会显示每个角色的附加信息;目前会增加每个角色的注释。 \dx[+] [ pattern ] - - 列出已安装的扩展。如果指定了 pattern,则只列出名称与模式匹配的扩展。如果在命令名后追加 +,则会列出属于每个匹配扩展的全部对象。 - + 列出已安装的扩展。如果指定了pattern,则只列出名称匹配该模式的扩展。如果使用\dx+形式,则列出属于每个匹配扩展的所有对象。 - \dX[ pattern ] + \dX [ pattern ] 列出扩展统计信息。如果指定了 pattern,则只列出名称与模式匹配的扩展统计信息。 @@ -1359,7 +1269,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g - \e\edit filename 行号 + \e\edit filename line_number @@ -1371,7 +1281,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g 如果编辑文件或上一个查询后在未修改文件的情况下退出编辑器,则查询缓冲区将被清除。 否则,查询缓冲区的新内容将根据psql的正常规则重新解析, - 将整个缓冲区视为单行。任何完整的查询将立即执行;也就是说,如果查询缓冲区包含或以分号结尾, + 将整个缓冲区视为单行。任何完整的查询将立即执行;也就是说,如果查询缓冲区包含分号或以分号结尾, 则执行并从查询缓冲区中删除到该点的所有内容。查询缓冲区中剩余的内容将重新显示。 输入分号或\g发送它,或输入\r通过清除查询缓冲区来取消。 @@ -1383,7 +1293,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g 如果指定了行号,psql将光标定位在文件或查询缓冲区的指定行上。 - 请注意,如果给出一个全是数字的参数, + 请注意,如果只给出一个全是数字的参数, psql会假定它是一个行号,而不是文件名。 @@ -1398,14 +1308,10 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g \echo text [ ... ] - - 将求值后的参数打印到标准输出,用空格分隔,并在末尾加上换行符。这对于在脚本输出中穿插信息很有用。例如: - + 将求值后的参数打印到标准输出,用空格分隔,并在末尾加上换行符。这对于在脚本输出中穿插信息很有用。例如: => \echo `date` Tue Oct 26 21:40:57 CEST 1999 - - 如果第一个参数是未引用的-n,则不会写入尾随的换行符(也不会写入第一个参数)。 - +如果第一个参数是未加引号的-n,则不会写入尾随的换行符(也不会写入第一个参数)。 @@ -1513,7 +1419,7 @@ Tue Oct 26 21:40:57 CEST 1999 - 设置未对齐查询输出的字段分隔符。默认值是竖线(|)。 + 设置非对齐查询输出的字段分隔符。默认值是竖线(|)。 它等同于\pset fieldsep @@ -1524,25 +1430,17 @@ Tue Oct 26 21:40:57 CEST 1999 \g [ (option=value [...]) ] [ filename ] \g [ (option=value [...]) ] [ |command ] - - 将当前查询缓冲区发送到服务器以执行。 - - - 如果在\g后面出现括号,则括号中包围着一个空格分隔的option=value格式选项子句的列表,这些选项子句的解释方式与\psetoptionvalue命令相同,但仅在此查询的持续时间内生效。在此列表中,不允许在=符号周围有空格,但在选项子句之间需要空格。 - 如果省略了=value,则命名的option将以与\psetoption没有显式value时相同的方式更改。 - - - 如果提供了一个filename|command参数, - 查询的输出将被写入到指定的文件或通过给定的shell命令进行传输,而不是像通常那样显示出来。只有在查询成功返回零个或多个元组时,文件或命令才会被写入,而不是在查询失败或是非数据返回的SQL命令时。 + 将当前查询缓冲区发送给服务器执行。 + 如果在\g后面出现括号,则括号中是用空格分隔的option=value格式选项子句列表。这些子句的解释方式与\pset + option + value命令相同,但仅在此查询执行期间生效。在此列表中,=符号周围不允许有空格,但选项子句之间必须有空格。如果=value被省略,则指定的option会按以下命令的方式更改:\pset option,其中不显式指定value + 如果给出了filename|command参数,查询输出就会写入指定文件,或通过管道传给指定的 shell 命令,而不是照常显示。只有当查询成功返回零个或多个元组时,才会向文件或命令写入;如果查询失败,或执行的是不返回数据的 SQL 命令,则不会写入。 如果当前查询缓冲区为空,则最近发送的查询将被重新执行。除此之外,没有任何参数的\g基本上等同于一个分号。 带有参数的\g提供了一个一次性替代\o命令的选择,并且还允许一次性调整通常由\pset设置的输出格式选项。 - - 当最后一个参数以|开头时,整行剩余部分被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分将被直接传递给shell。 - + 当最后一个参数以|开头时,该行剩余的全部内容都会被视为要执行的command,其中既不进行变量插值,也不进行反引号扩展。该行剩余部分会直接按字面传给 shell。 @@ -1551,14 +1449,9 @@ Tue Oct 26 21:40:57 CEST 1999 \gdesc - - 显示当前查询缓冲区结果的描述(即列名和数据类型)。 - 查询不会实际执行;但是,如果包含某种语法错误,该错误将以正常方式报告。 - + 显示当前查询缓冲区中查询结果的描述(即列名和数据类型)。查询并不会实际执行;不过,如果其中存在语法错误,会按通常的方式报告。 - - 如果当前查询缓冲区为空,则描述最近发送的查询。 - + 如果当前查询缓冲区为空,则改为描述最近发送的查询。 @@ -1613,37 +1506,23 @@ CREATE INDEX \gset [ prefix ] - - 将当前查询缓冲区发送到服务器,并将查询的输出存储到psql变量中 - (参见下面的)。 - 要执行的查询必须返回一行。该行的每一列都存储在一个单独的变量中,变量名与列名相同。例如: - + 将当前查询缓冲区发送给服务器,并将查询输出存入 psql 变量(参见下面的)。要执行的查询必须恰好返回一行。该行的每一列分别存入一个变量,变量名与列名相同。例如: => SELECT 'hello' AS var1, 10 AS var2 -> \gset => \echo :var1 :var2 hello 10 - - 如果指定了一个prefix, - 该字符串将被添加到查询的列名前,以创建要使用的变量名: - + 如果指定了prefix,则会将该字符串加到查询的列名前面,以构成要使用的变量名: => SELECT 'hello' AS var1, 10 AS var2 -> \gset result_ => \echo :result_var1 :result_var2 hello 10 - - 如果列的结果为NULL,则相应的变量将被取消设置,而不是被设置。 - - - 如果查询失败或者没有返回一行结果, - 则不会改变任何变量。 - - - 如果当前查询缓冲区为空,则重新执行最近发送的查询。 - + 如果某一列的结果为 NULL,则取消设置对应的变量,而不是设置它。 + 如果查询失败或没有恰好返回一行,则不会更改任何变量。 + 如果当前查询缓冲区为空,则改为重新执行最近发送的查询。 @@ -1666,7 +1545,7 @@ hello 10 给出指定SQL命令的语法帮助。如果未指定command, 则psql将列出所有可用语法帮助的命令。如果command是星号 - (*),则显示所有SQL命令的语法帮助。 + (*),则显示所有SQL命令的语法帮助。 @@ -1687,9 +1566,7 @@ hello 10 \H\html - 打开HTML查询输出格式。如果HTML格式已经打开, - 则切换回默认的对齐文本格式。此命令用于兼容性和便利性,但请参阅\pset - 有关设置其他输出选项。 + 打开HTML查询输出格式。如果HTML格式已经打开,则切换回默认的对齐文本格式。此命令是为兼容性和便利性而保留的;设置其他输出选项的方法见\pset @@ -1701,13 +1578,10 @@ hello 10 - 从文件filename中读取输入,并将其执行为 - 好像它是在键盘上键入的一样。 + 从文件filename中读取输入,并像在键盘上输入一样执行它。 - 如果filename- - (连字符),那么标准输入将被读取,直到EOF指示或\q元命令。 - 这可用于将交互式输入与文件输入交错使用。请注意,仅当在最外层级别处于活动状态时,Readline行为才会被使用。 + 如果filename-(连字符),则从标准输入读取,直到遇到 EOF 指示或\q元命令。这可用于将交互式输入与文件输入交错使用。请注意,只有在最外层启用了 Readline,此处才会使用 Readline 功能。 @@ -1727,42 +1601,26 @@ hello 10 这组命令实现了可嵌套的条件块。条件块必须以\if开始,并以\endif结束。 在两者之间可以有任意数量的\elif子句,后面可以选择性地跟着一个\else子句。 - 在形成条件块的命令之间通常会出现普通查询和其他类型的反斜杠命令。 + 在形成条件块的命令之间通常会出现普通查询和其他类型的反斜线命令。 - \if\elif命令读取它们的参数,并将其作为布尔表达式进行评估。 - 如果表达式为true,则处理将继续进行;否则,直到达到匹配的\elif、 - \else\endif为止,将跳过行。一旦\if或 - \elif测试成功,同一块中后续\elif命令的参数不会被评估,而是被视为false。 - 在\else之后的行只有在没有早期匹配的\if\elif成功时才会被处理。 + \if\elif命令读取其参数,并将其作为布尔表达式求值。如果表达式的值为true,则正常继续处理;否则,跳过后续行,直到遇到匹配的\elif\else\endif。一旦\if\elif测试成功,同一块中后续\elif命令的参数就不再求值,而是被视为假。只有前面所有匹配的\if\elif测试都未成功时,才会处理\else后面的行。 - expression参数 - 是\if\elif命令的参数, - 受变量插值和反引号扩展的影响,就像任何其他反斜杠命令参数一样。 - 之后,它被评估为一个开/关选项变量的值。因此,有效值是以下任何一个不 - 含糊的不区分大小写匹配之一: - true, false, 1, - 0, on, off, - yes, no。例如, - t, TtR - 都将被视为true。 + 与其他反斜线命令的参数一样,\if\elif命令的expression参数会经过变量插值和反引号扩展。随后,按开/关选项变量值的规则对结果求值。因此,有效值是以下值的不区分大小写且无歧义的匹配:truefalse10onoffyesno。例如,tTtR都会被视为true - 不正确评估为真或假的表达式将生成警告,并被视为假。 + 不能正确求值为真或假的表达式会产生警告,并被视为假。 - 被跳过的行会被正常解析以识别查询和反斜杠命令,但查询不会发送到服务器, - 而且除了条件命令(\if\elif, - \else\endif)之外的反斜杠命令会被忽略。 + 被跳过的行会被正常解析以识别查询和反斜线命令,但查询不会发送到服务器, + 而且除了条件命令(\if\elif、 + \else\endif)之外的反斜线命令会被忽略。 仅检查跳过行中条件命令的有效嵌套。跳过行中的变量引用不会被展开, 也不会执行反引号扩展。 - 所有给定条件块的反斜杠命令必须出现在同一个源文件中。如果在主输入文件或一个 - \include的文件上达到文件结束之前,所有本地 - \if块都没有关闭, - 那么psql将会引发错误。 + 同一个条件块的所有反斜线命令必须出现在同一个源文件中。如果主输入文件或通过\include引入的文件到达 EOF 时,仍有本地\if块未关闭,psql就会报错。 下面是一个示例: @@ -1796,17 +1654,13 @@ SELECT \ir\include_relative filename - - \ir命令类似于\i,但是解析相对文件名的方式不同。 - 在交互模式下执行时,这两个命令的行为是相同的。然而,在脚本中调用时, - \ir会将文件名解释为相对于脚本所在目录,而不是当前工作目录。 - + \ir命令与\i相似,但解析相对文件名的方式不同。在交互模式下执行时,这两个命令的行为相同。不过,在脚本中调用时,\ir会相对于脚本所在的目录来解释文件名,而不是相对于当前工作目录。 - \l[+] or \list[+] [ pattern ] + \l[+]\list[+] [ pattern ] 列出服务器中的数据库,并显示其名称、所有者、字符集编码和访问权限。如果指定了 pattern,则只列出名称与模式匹配的数据库。如果在命令名后追加 +,则还会显示数据库大小、默认表空间和描述。当前用户对其拥有 CONNECT 权限的数据库可以显示大小信息;如果当前用户是超级用户或具有 pg_read_all_stats 角色的权限,也可以显示大小信息。 @@ -1823,7 +1677,7 @@ SELECT 从数据库中读取具有OIDloid的大对象,并将其写入filename。请注意,这与服务器函数 - lo_export略有不同,后者使用数据库服务器运行的用户权限, + lo_export略有不同,后者使用运行数据库服务器的用户的权限, 并在服务器的文件系统上操作。 @@ -1839,14 +1693,10 @@ SELECT \lo_import filename [ comment ] - - 将文件存储到一个PostgreSQL大对象中。可选地,它将给定的注释与对象关联起来。例如: - + 将文件存储到一个PostgreSQL大对象中。可选地,它将给定的注释与对象关联起来。例如: foo=> \lo_import '/home/peter/pictures/photo.xcf' 'a picture of me' lo_import 152801 - - 响应表明大对象收到了对象ID 152801,这个ID可以用来在将来访问新创建的大对象。为了可读性起见,建议始终将一个可读的注释与每个对象关联起来。OID和注释都可以用\lo_list命令查看。 - +响应表明大对象获得了对象 ID 152801,这个 ID 可以用来在将来访问新创建的大对象。为便于阅读,建议始终为每个对象关联一条便于人阅读的注释。查看 OID 和注释时,可以使用\lo_list命令。 请注意,此命令与服务器端的lo_import略有不同,因为它作为本地用户在本地文件系统上操作,而不是服务器的用户和文件系统。 @@ -1869,7 +1719,7 @@ lo_import 152801 - 从数据库中删除具有OIDloid的大对象。 + 从数据库中删除OIDloid的大对象。 @@ -1885,19 +1735,12 @@ lo_import 152801 \o\out [ filename ] \o\out [ |command ] - - 安排将未来的查询结果保存到文件filename, - 或将未来的结果传输到shell命令command。 - 如果未指定参数,则查询输出重置为标准输出。 - + 将后续查询结果保存到文件filename,或通过管道传给 shell 命令command。如果没有指定参数,查询输出将恢复为标准输出。 - - 如果参数以|开头,则整个剩余部分的行被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分的行会被直接传递给shell。 - + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 - 查询结果包括从数据库服务器获取的所有表、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 + 查询结果包括从数据库服务器获取的所有表格、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 @@ -1951,17 +1794,9 @@ lo_import 152801 \pset [ option [ value ] ] - - 这个命令设置影响查询结果表输出的选项。 - option - 指示要设置哪个选项。根据所选选项,value的语义会有所不同。 - 对于某些选项,省略value会导致该选项被切换或取消设置,具体描述在特定选项下。 - 如果没有提到这样的行为,那么省略value只会显示当前设置。 - + 这个命令设置影响查询结果表输出的选项。option指定要设置哪个选项。value的含义取决于所选的选项。对于某些选项,省略value会切换或取消设置该选项,具体见各选项的说明。如果没有提及这类行为,那么省略value只会显示当前设置。 - - \pset不带任何参数时,显示所有打印选项的当前状态。 - + 不带任何参数的\pset会显示所有打印选项的当前状态。 可调整打印选项有: @@ -1969,12 +1804,7 @@ lo_import 152801 border - - value必须是一个数字。一般来说,数字越高,表格的边框和线条就越多, - 但具体细节取决于特定格式。在HTML格式中,这将直接转换为border=...属性。 - 在大多数其他格式中,只有值0(无边框)、1(内部分隔线)和2(表框)有意义,值大于2将被视为border = 2。 - latexlatex-longtable格式还允许值为3,以在数据行之间添加分隔线。 - + value必须是数字。一般来说,数字越大,表格的边框和分隔线就越多,但细节取决于具体格式。在HTML格式中,它会直接转换为border=...属性。在大多数其他格式中,只有值 0(无边框)、1(内部分隔线)和 2(表格外框)有意义,大于 2 的值会与border = 2作相同处理。latexlatex-longtable格式还允许使用值 3,以在数据行之间添加分隔线。 @@ -1987,7 +1817,7 @@ lo_import 152801 零(默认值)会导致目标宽度由环境变量COLUMNS控制,或者如果未设置 COLUMNS则由检测到的屏幕宽度控制。 另外,如果columns为零,则wrapped格式仅影响屏幕输出。 - 如果columns为非零,则文件和管道输出也会被包装到该宽度。 + 如果columns为非零,则文件和管道输出也会按该宽度折行。 @@ -2006,63 +1836,35 @@ lo_import 152801 expanded(或x - - 如果指定了value,它必须是onoff, - 这将启用或禁用扩展模式,或者是auto。 - 如果省略了value,则命令在开启和关闭设置之间切换。 - 启用扩展模式时,查询结果以两列显示,左侧是列名,右侧是数据。 - 如果数据在正常的水平模式下无法完全显示在屏幕上,则此模式很有用。 - 在自动设置中,当查询输出具有多列且宽度超过屏幕时,将使用扩展模式;否则,将使用常规模式。 - 自动设置仅在对齐和换行格式中有效。在其他格式中,它始终表现为扩展模式已关闭。 - + 如果指定了value,它必须是onoff(分别启用或禁用扩展模式),或者是auto。如果省略value,该命令会在开启和关闭设置之间切换。启用扩展模式时,查询结果以两列显示,左侧为列名,右侧为数据。如果数据在通常的横向模式下无法适应屏幕,这种模式就很有用。在自动设置下,当查询输出包含多列且宽度超过屏幕时,会使用扩展模式;否则使用常规模式。自动设置只在对齐和折行格式中有效。在其他格式中,它的行为始终与关闭扩展模式相同。 fieldsep - - 指定在未对齐的输出格式中使用的字段分隔符。这样,可以创建例如制表符分隔的输出, - 其他程序可能更喜欢。要将制表符设置为字段分隔符,请键入 - \pset fieldsep '\t'。默认字段分隔符是 - '|'(一根竖线)。 - + 指定非对齐输出格式使用的字段分隔符。这样可以创建例如制表符分隔的输出,这可能更符合其他程序的需要。要将制表符设置为字段分隔符,请输入\pset fieldsep '\t'。默认字段分隔符是'|'(竖线)。 fieldsep_zero - - 将未对齐输出格式中使用的字段分隔符设置为零字节。 - + 将非对齐输出格式使用的字段分隔符设置为零字节。 footer - - 如果指定了value, - 它必须是onoff, - 这将启用或禁用表格页脚的显示 - ((n 行)计数)。 - 如果省略了value, - 命令将切换页脚的显示或隐藏。 - + 如果指定了value,它必须是onoff,分别启用或禁用表格页脚((n rows)计数)的显示。如果省略value,该命令会切换页脚显示的开关状态。 format - - 设置输出格式为alignedasciidoc、 - csvhtmllatex、 - latex-longtabletroff-ms、 - unalignedwrapped。 - 允许使用唯一缩写。 - + 设置输出格式为alignedasciidoccsvhtmllatexlatex-longtabletroff-msunalignedwrapped。允许使用唯一缩写。 aligned格式是标准的、适合人阅读且排版整齐的文本输出;这是默认格式。 @@ -2075,12 +1877,12 @@ lo_import 152801 按逗号分隔的列值输出,并应用 RFC 4180 - 中描述的引用规则。 + 中描述的加引号规则。 此输出与服务器的CSV格式的 COPY命令兼容。 - 生成包含列名的标题行,除非 + 生成包含列名的表头行,除非 tuples_only参数设置为 - on。不打印标题和页脚。 + on。不打印表格标题和页脚。 每行以系统相关的行结束字符结束, 对于类Unix系统通常是单个换行符(\n), 对于Microsoft Windows则是回车和换行序列 @@ -2088,17 +1890,14 @@ lo_import 152801 可以用\pset csv_fieldsep选择逗号以外的字段分隔字符。 - wrapped格式类似于aligned,但会将宽数据值跨行包装,以使输出适合目标列宽。 - 目标宽度由columns选项下描述的方式确定。请注意,psql不会尝试包装列标题; - 因此,如果列标题所需的总宽度超过目标宽度,则wrapped格式的行为与aligned相同。 - + wrapped格式与aligned相似,但会将较宽的数据值折成多行,使输出适应目标列宽。目标宽度的确定方式见columns选项的说明。请注意,psql不会尝试对列标题折行;因此,如果列标题所需的总宽度超过目标宽度,wrapped格式的行为就与aligned相同。 - asciidochtml, - latexlatex-longtable,和 + asciidochtml、 + latexlatex-longtabletroff-ms格式生成的表格旨在包含在使用相应标记语言的文档中。 它们不是完整的文档!这在HTML中可能不是必需的,但在 - LaTeX中,则必须有一个完整的文档包装器。 + LaTeX中,则必须有一个完整文档的外层结构。 latex格式使用LaTeXtabular 环境。 latex-longtable格式需要LaTeX @@ -2118,25 +1917,19 @@ lo_import 152801 - ascii样式使用普通的ASCII字符。数据中的换行使用右边边缘的+符号显示。 - 当wrapped格式将数据从一行换到下一行而没有换行符时,在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 + ascii样式使用普通的ASCII字符。数据中的换行符以右边缘的+符号表示。当wrapped格式在没有换行符的位置把数据折到下一行时,会在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 - old-ascii样式使用普通的ASCII字符,使用在PostgreSQL 8.4及更早版本中使用的格式样式。 - 数据中的换行符使用:符号代替左侧列分隔符显示。 - 当数据从一行换行到下一行而没有换行符时,使用;符号代替左侧列分隔符。 + old-ascii样式使用普通的ASCII字符,采用PostgreSQL 8.4 及更早版本的格式样式。数据中的换行符以替代左侧列分隔符的:符号表示。当数据在没有换行符的位置折到下一行时,则用;符号替代左侧列分隔符。 - unicode样式使用Unicode绘图字符。数据中的换行使用右边距中的回车符号显示。 - 当数据从一行换行到下一行而没有换行符时,第一行的右边距显示省略号符号, - 接着在下一行的左边距再次显示省略号符号。 + unicode样式使用 Unicode 框线绘制字符。数据中的换行符以右边缘的回车符号表示。当数据在没有换行符的位置折到下一行时,会在第一行的右边缘显示省略号符号,并在下一行的左边缘再次显示。 - 当border设置大于零时,linestyle选项还确定了用哪些字符绘制边框线。 - 普通的ASCII字符在任何地方都有效,但在识别Unicode字符的显示器上看起来更好。 + 当border设置大于零时,linestyle选项还决定用哪些字符绘制边框线。普通的ASCII字符在任何环境中都可用,但在支持 Unicode 的显示设备上,Unicode 字符更美观。 @@ -2144,24 +1937,14 @@ lo_import 152801 null - - 设置要打印在空值位置的字符串。默认情况下是不打印任何内容,这很容易被误解为空字符串。 - 例如,一个人可能更喜欢\pset null '(null)'。 - + 设置用于代替空值打印的字符串。默认不打印任何内容,这很容易被误认为空字符串。例如,你可能更喜欢使用\pset null '(null)' numericlocale - - 如果指定了value, - 它必须是onoff, - 这将启用或禁用显示一个特定于区域设置的字符, - 用于将小数点左侧的数字分组。如果省略了 - value, - 命令在常规和特定于区域设置的数字输出之间切换。 - + 如果指定了value,它必须是onoff,分别启用或禁用使用区域设置特定的字符来分隔小数点左侧的数字组。如果省略value,该命令会在常规数字输出和区域设置特定的数字输出之间切换。 @@ -2169,17 +1952,11 @@ lo_import 152801 pager - 控制查询和psql帮助输出时使用分页程序的方式。 - 当pager选项为off时,不使用分页程序。 - 当pager选项为on时,在适当的情况下使用分页程序,即当输出到终端且不适合在屏幕上显示时。 - pager选项也可以设置为always,这会导致分页程序用于所有终端输出,无论是否适合在屏幕上显示。 - \pset pager 不带value时,会在开启和关闭分页器之间切换。 + 控制查询和psql帮助输出是否使用分页器程序。当pager选项为off时,不使用分页器程序。当pager选项为on时,会在适当时使用分页器,即输出目标为终端且内容无法在屏幕上完整显示时。pager选项也可以设为always,这样所有终端输出都会使用分页器,无论内容是否能在屏幕上完整显示。不带value\pset pager会切换分页器的使用状态。 - 如果环境变量PSQL_PAGERPAGER被设置, - 输出将被分页传输到指定的程序。否则,将使用一个平台相关的默认程序 - (例如more)。 + 如果设置了环境变量PSQL_PAGERPAGER,需要分页的输出会通过管道传给指定程序。否则,使用与平台有关的默认程序(如more)。 @@ -2194,94 +1971,64 @@ lo_import 152801 pager_min_lines - - 如果pager_min_lines设置为大于页面高度的数字, - 则除非至少有这么多行的输出要显示,否则不会调用分页程序。默认设置为0。 - + 如果将pager_min_lines设置为大于页面高度的数字,那么只有待显示的输出至少达到这么多行时,才会调用分页器程序。默认设置为 0。 recordsep - - 指定在未对齐的输出格式中使用的记录(行)分隔符。默认为换行符。 - + 指定非对齐输出格式使用的记录(行)分隔符。默认为换行符。 recordsep_zero - - 设置未对齐输出格式中使用的记录分隔符为零字节。 - + 将非对齐输出格式使用的记录分隔符设置为零字节。 tableattr(或T - - 在HTML格式中,这指定要放置在table标签内的属性。 - 这可能是cellpaddingbgcolor等。 - 请注意,这里通常不需要指定border,因为它已经由\pset border处理。 - 如果没有给出value,则取消表格属性。 - - - 在latex-longtable格式中,这控制了包含左对齐数据类型的每列的比例宽度。 - 它被指定为一个以空格分隔的值列表,例如,'0.2 0.2 0.6'。 - 未指定输出列使用最后指定的值。 - + HTML格式中,这指定要放在table标签内的属性,例如cellpaddingbgcolor。请注意,你可能不需要在这里指定border,因为\pset border已经负责处理它。如果没有给出value,则取消设置表格属性。 + latex-longtable格式中,这控制每个包含左对齐数据类型的列的宽度比例。它以空白分隔的值列表指定,例如'0.2 0.2 0.6'。未指定的输出列使用最后指定的值。 - title(或者C + title(或C - - 设置后续打印的任何表的标题。这可以用来为输出提供说明性标签。 - 如果没有给出value,则标题将被取消设置。 - + 设置随后打印的所有表格的标题。这可以为输出提供描述性标签。如果没有给出value,则取消设置标题。 tuples_only(或t - - 如果指定了value,它必须是onoff, - 这将启用或禁用仅元组模式。如果省略了value, - 命令将在常规输出和仅元组输出之间切换。常规输出包括额外信息,如列标题、标题和各种页脚。 - 在仅元组模式下,只显示实际的表数据。 - + 如果指定了value,它必须是onoff,分别启用或禁用仅元组模式。如果省略value,该命令会在常规输出和仅元组输出之间切换。常规输出包含列标题、表格标题和各种页脚等附加信息。在仅元组模式下,只显示实际的表格数据。 unicode_border_linestyle - - 设置unicode线条样式的边框绘制样式为singledouble之一。 - + unicode线条样式的边框绘制样式设置为singledouble unicode_column_linestyle - - 设置unicode线条样式的列绘制样式为singledouble之一。 - + unicode线条样式的列分隔线绘制样式设置为singledouble unicode_header_linestyle - - 设置unicode线条样式的标题绘制样式为singledouble之一。 - + unicode线条样式的表头分隔线绘制样式设置为singledouble @@ -2289,35 +2036,33 @@ lo_import 152801 xheader_width - 将扩展输出的标题最大宽度设置为以下之一: + 将扩展输出的表头最大宽度设置为以下之一: full(默认值)、 columnpage整数值 - full:扩展标题不截断,其宽度与最宽的输出行相同。 + full:扩展表头不截断,其宽度与最宽的输出行相同。 - column:将标题行截断为第一列的宽度。 + column:将表头行截断为第一列的宽度。 - page:将标题行截断为终端宽度。 + page:将表头行截断为终端宽度。 - 整数值:指定标题行的确切最大宽度。 + 整数值:指定表头行的确切最大宽度。 - - 这些不同格式的示例可以在下面的中看到。 - + 这些不同格式的外观示例可参见下面的 @@ -2334,10 +2079,7 @@ lo_import 152801 \q\quit - - 退出psql程序。 - 在脚本文件中,只有该脚本的执行被终止。 - + 退出psql程序。在脚本文件中,只会终止该脚本的执行。 @@ -2346,7 +2088,7 @@ lo_import 152801 \qecho text [ ... ] - 这个命令与\echo命令相同,只是输出将被写入查询输出通道,由\o设置。 + 这个命令与\echo相同,只是输出会写入由\o设置的查询输出通道。 @@ -2355,9 +2097,7 @@ lo_import 152801 \r\reset - - 重置(清除)查询缓冲区。 - + 重置(清空)查询缓冲区。 @@ -2444,14 +2184,9 @@ testdb=> \setenv LESS -imx4F 定义将打印到当前查询输出通道,由\o设置。 - - 目标函数可以仅通过名称指定,也可以通过名称和参数指定,例如foo(integer, text)。 - 如果有多个同名函数,则必须给出参数类型。 - + 目标函数可以只用名称指定,也可以同时给出名称和参数,例如foo(integer, text)。如果存在多个同名函数,就必须给出参数类型。 - - 如果在命令名称后添加+,则输出的行将被编号,函数体的第一行将被标记为第1行。 - + 如果在命令名后附加+,输出行会带上行号,函数体的第一行编号为 1。 与大多数其他元命令不同,整个行的剩余部分始终被视为\sf的参数, @@ -2466,8 +2201,7 @@ testdb=> \setenv LESS -imx4F - 这个命令获取并显示指定视图的定义,以CREATE OR REPLACE VIEW命令的形式。 - 定义将打印到当前查询输出通道,由\o设置。 + 这个命令获取指定视图的定义,并以CREATE OR REPLACE VIEW命令的形式显示。定义会打印到由\o设置的当前查询输出通道。 @@ -2486,10 +2220,7 @@ testdb=> \setenv LESS -imx4F \t - - 切换显示输出列名标题和行数页脚。此命令等效于\pset tuples_only, - 仅为方便起见提供。 - + 切换输出中的列名标题和行数页脚的显示状态。这个命令等价于\pset tuples_only,提供它是为了使用方便。 @@ -2497,10 +2228,7 @@ testdb=> \setenv LESS -imx4F \T table_options - - 指定在table标签中放置的属性,在HTML输出格式中。 - 该命令等效于\pset tableattr table_options。 - + 指定在HTML输出格式中放在table标签内的属性。这个命令等价于\pset tableattr table_options @@ -2508,10 +2236,7 @@ testdb=> \setenv LESS -imx4F \timing [ on | off ] - - 使用参数,打开或关闭显示每个SQL语句执行时间的功能。没有参数时,切换显示开关。 - 显示的时间单位为毫秒;超过1秒的时间间隔也以分钟:秒的格式显示,如有必要还会显示小时和天。 - + 带参数时,开启或关闭每条 SQL 语句执行耗时的显示。不带参数时,切换显示的开关状态。耗时以毫秒显示;超过 1 秒的时间间隔还会以分钟:秒的格式显示,必要时添加小时和天字段。 @@ -2538,15 +2263,9 @@ testdb=> \setenv LESS -imx4F \unset name - - 取消设置(删除)psql变量name。 - + 取消设置(删除)psql变量name - - 大多数控制psql行为的变量不能被取消设置;相反,\unset命令被解释为将它们设置为默认值。 - 请参见下面的。 - + 大多数控制psql行为的变量不能取消设置;对于这些变量,\unset命令会被解释为将其设置为默认值。参见下面的 @@ -2555,15 +2274,9 @@ testdb=> \setenv LESS -imx4F \w\write filename \w\write |command - - 将当前查询缓冲区写入文件filename,或者通过管道传给 shell 命令command。 - 如果当前查询缓冲区为空,则写入最近执行的查询。 - + 将当前查询缓冲区写入文件filename,或通过管道传递给 shell 命令command。如果当前查询缓冲区为空,则改为写入最近执行的查询。 - - 如果参数以|开头,则整个剩余部分的行被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分的行会被直接传递给shell。 - + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 @@ -2596,9 +2309,7 @@ testdb=> \setenv LESS -imx4F \x [ on | off | auto ] - - 设置或切换扩展表格格式模式。因此,它等同于\pset expanded。 - + 设置或切换扩展表格格式模式。它等价于\pset expanded @@ -2620,13 +2331,11 @@ testdb=> \setenv LESS -imx4F \! [ command ] - 不带参数时,转义到一个子shell;psql在子shell退出时恢复。 - 带参数时,执行shell命令command。 + 不带参数时,进入一个子 shell;子 shell 退出后,psql恢复运行。带参数时,执行 shell 命令command - 与大多数其他元命令不同,整个行的剩余部分始终被视为\!的参数, - 在参数中不执行变量插值或反引号扩展。行的其余部分被直接传递给shell。 + 与大多数其他元命令不同,该行剩余的全部内容始终被视为\!的参数,其中不会进行变量插值或反引号扩展。该行剩余内容会原样传给 shell。 @@ -2638,7 +2347,7 @@ testdb=> \setenv LESS -imx4F 显示帮助信息。可选的topic参数 (默认为commands)选择要解释的psql的哪个部分: - commands描述psql的反斜杠命令; + commands描述psql的反斜线命令; options描述可以传递给psql的命令行选项; 而variables显示关于psql配置变量的帮助。 @@ -2650,7 +2359,7 @@ testdb=> \setenv LESS -imx4F \; - 反斜杠分号不像前面的命令那样是一个元命令;相反,它只是在不进行进一步处理的情况下将一个分号添加到查询缓冲区中。 + 反斜线分号不像前面的命令那样是一个元命令;相反,它只是在不进行进一步处理的情况下将一个分号添加到查询缓冲区中。 @@ -2662,8 +2371,8 @@ select 1; select 2; select 3; select 1\; select 2\; select 3; - 在到达非反斜杠分号时将三个SQL命令发送到服务器的单个请求中。 - 服务器将执行此类请求作为单个事务,除非字符串中包含明确的BEGIN/COMMIT命令将其分成多个事务。(有关服务器如何处理多查询字符串的更多详细信息,请参见。) + 会在遇到前面没有反斜线的分号时,将这三个 SQL 命令作为单个请求发送到服务器。 + 服务器会将此类请求作为单个事务执行,除非字符串中包含显式的BEGIN/COMMIT命令将其分成多个事务。(有关服务器如何处理多查询字符串的更多详细信息,请参见。) @@ -2671,16 +2380,16 @@ select 1\; select 2\; select 3; - + 模式 - patterns + 模式 在 psql 和 pg_dump 中 - 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要把它写成两个相邻的双引号,这同样是符合 SQL 引用标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你不能只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 + 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要在双引号包围的文本内把它写成两个相邻的双引号,这同样是符合 SQL 加引号标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你可以只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 @@ -2692,21 +2401,15 @@ select 1\; select 2\; select 3; - 包含点(.)的关系模式被解释为模式名称后跟对象名称模式。例如, - \dt foo*.*bar*显示所有位于模式名以foo开头的模式中、且表名包含bar的表。当没有出现点时,模式仅匹配当前模式搜索路径中可见的对象。 - 再次,双引号内的点失去其特殊含义,被视为字面匹配。包含两个点(.)的关系模式 - 被解释为数据库名称后跟模式名称后跟对象名称模式。数据库名称部分不会被视为模式,必须匹配当前连接的数据库名称, - 否则将引发错误。 + 如果用于匹配关系名的模式包含一个点(.),则会被解释为模式名的匹配模式,后接对象名的匹配模式。例如,\dt foo*.*bar*会显示所有位于模式名以foo开头的模式中、且表名包含bar的表。如果没有点,则只匹配当前模式搜索路径中可见的对象。同样,双引号内的点会失去特殊含义,按字面匹配。如果用于匹配关系名的模式包含两个点(.),则会被解释为数据库名、模式名的匹配模式和对象名的匹配模式。数据库名部分不会被当作匹配模式,必须与当前连接的数据库名相同,否则会报错。 - 包含一个点(.)的模式被解释为数据库名称后跟模式的模式名称。例如, - \dn mydb.*foo*显示所有包含foo的模式。数据库名称部分不会被视为模式, - 必须匹配当前连接数据库的名称,否则将引发错误。 + 如果用于匹配模式名的模式包含一个点(.),则会被解释为数据库名,后接模式名的匹配模式。例如,\dn mydb.*foo*会显示名称中包含foo的所有模式。数据库名部分不会被当作匹配模式,必须与当前连接的数据库名相同,否则会报错。 - 高级用户可以使用字符类等正则表达式记法,如[0-9]可以匹配任意数字。所有的正则表达式特殊字符都按照所说的工作,以下字符除外:.会按照上面所说的作为一种分隔符,*会被翻译成正则表达式记号.*?会被翻译成.,而$则按字面意思匹配。根据需要,可以通过书写?(R+|)(R|)R?来分别模拟模式字符.R*R?$不需要作为一个正则表达式字符,因为模式必须匹配整个名称,而不是像正则表达式的常规用法那样解释(换句话说,$会被自动地追加到模式上)。如果不希望该模式的匹配位置被固定,可以在开头或者结尾写上*。注意在双引号内,所有的正则表达式特殊字符会失去其特殊含义并且按照其字面意思进行匹配。还有,在操作符名称模式中(即作为\do的参数),正则表达式特殊字符也按照字面意思进行匹配。 + 高级用户可以使用字符类等正则表达式记法,如[0-9]可以匹配任意数字。所有的正则表达式特殊字符都按照所说的工作,以下字符除外:.会按照上面所说的作为一种分隔符,*会被翻译成正则表达式记号.*?会被翻译成.,而$则按字面意思匹配。根据需要,可以用?模拟.,用(R+|)模拟R*,或用(R|)模拟R?$不需要作为一个正则表达式字符,因为模式必须匹配整个名称,而不是像正则表达式的常规用法那样解释(换句话说,$会被自动地追加到模式上)。如果不希望该模式的匹配位置被固定,可以在开头或者结尾写上*。注意在双引号内,所有的正则表达式特殊字符会失去其特殊含义并且按照其字面意思进行匹配。还有,在操作符名称模式中(即作为\do的参数),正则表达式特殊字符也按照字面意思进行匹配。 @@ -2714,7 +2417,7 @@ select 1\; select 2\; select 3; 高级特性 - + 变量 @@ -2735,7 +2438,7 @@ bar - 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要重置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 + 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要取消设置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 @@ -2749,7 +2452,7 @@ bar - 控制psql行为的变量通常不能被重置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse。 + 控制psql行为的变量通常不能被取消设置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse @@ -2767,7 +2470,7 @@ bar - 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被重置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交打开模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身即不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 + 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被取消设置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交关闭模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身既不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 @@ -2797,7 +2500,7 @@ bar DBNAME - 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -2806,7 +2509,7 @@ bar ECHO - 如果被设置为all,所有非空输入行会被按照读入它们的样子打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被重置或者设置为none(默认值)则不会显示任何查询。 + 如果被设置为all,所有非空输入行会在读入时打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被设置为none(默认值)则不会显示任何查询。 @@ -2824,7 +2527,7 @@ bar ENCODING - 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者重置。 + 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者取消设置。 @@ -2842,12 +2545,12 @@ bar FETCH_COUNT - 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每一组就会包括这么多个行。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 + 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每组包含的行数等于该整数值。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 - 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT个行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 + 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 @@ -2876,7 +2579,7 @@ bar HISTCONTROL - 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则匹配之前的历史行的行不会被放入。值ignoreboth组合了上述两种值。如果被重置或者被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 + 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则与上一条历史记录相同的行不会被放入。值ignoreboth组合了上述两种值。如果被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 @@ -2890,7 +2593,7 @@ bar HISTFILE - 该文件名将被用于存储历史列表。如果被重设,文件名将从PSQL_HISTORY环境变量中取得。如果该环境变量也没有被设置,则默认值是~/.psql_history,在Windows上是%APPDATA%\postgresql\psql_history。例如, + 该文件名将被用于存储历史列表。如果未设置该变量,文件名将从PSQL_HISTORY环境变量中取得。如果该环境变量也没有被设置,则默认值是~/.psql_history,在Windows上是%APPDATA%\postgresql\psql_history。例如, \set HISTFILE ~/.psql_history-:DBNAME @@ -2922,7 +2625,7 @@ bar HOST - 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -2931,7 +2634,7 @@ bar IGNOREEOF - 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须键入多个连续的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 + 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须连续键入与该数值相等数量的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 @@ -2945,8 +2648,8 @@ bar LASTOID - 最后被影响的 OID 的值,这可能会由INSERT或者\lo_import命令返回。这个变量只保证在下一个SQL命令被显示完之前有效。 - PostgreSQL 服务器从12版开始不再支持 OID 系统列,因此,在面向此类服务器时,跟随在INSERT后面的 LASTOID 将始终为0。 + 最后被影响的 OID 的值,这可能会由INSERT或者\lo_import命令返回。这个变量仅保证在下一个SQL命令的结果显示完之前有效。 + PostgreSQL 服务器从12版开始不再支持 OID 系统列,因此,在面向此类服务器时,执行INSERT后的 LASTOID 将始终为0。 @@ -2971,7 +2674,7 @@ bar - 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被重置或者设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 + 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 @@ -2992,7 +2695,7 @@ bar PORT - 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -3031,7 +2734,7 @@ bar SERVER_VERSION_NUM - 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者重设。 + 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者取消设置。 @@ -3043,7 +2746,7 @@ bar 如果最后一个 shell 命令失败,则为 true;如果成功,则为 false。这适用于通过 \!\g\o\w - 和 \copy 元命令调用的 shell 命令,也适用于反引号(`)展开。请注意,对于 \o,该变量会在下一个 \o 命令关闭输出管道时更新。 + 和 \copy 元命令调用的 shell 命令,也适用于反引号(`)扩展。请注意,对于 \o,该变量会在下一个 \o 命令关闭输出管道时更新。 另见 SHELL_EXIT_CODE @@ -3055,7 +2758,7 @@ bar 最后一个 shell 命令返回的退出状态。0–127 表示程序退出码,128–255 表示因信号而终止,-1 表示未能启动程序或未能取得其退出状态。这适用于通过 \!\g\o\w - 和 \copy 元命令调用的 shell 命令,也适用于反引号(`)展开。请注意,对于 \o,该变量会在下一个 \o 命令关闭输出管道时更新。 + 和 \copy 元命令调用的 shell 命令,也适用于反引号(`)扩展。请注意,对于 \o,该变量会在下一个 \o 命令关闭输出管道时更新。 另见 SHELL_ERROR @@ -3075,7 +2778,7 @@ bar SHOW_CONTEXT - 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT域。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 + 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT字段。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 当VERBOSITY被设置为tersesqlstate时,这个设置无效(另见\errverbose,它可以用来得到刚遇到的错误的详细信息)。 @@ -3094,7 +2797,7 @@ bar SINGLESTEP - 设置这个变量为on等效于命令选项。 + 设置这个变量为on等效于命令行选项 @@ -3112,7 +2815,7 @@ bar USER - 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -3121,7 +2824,7 @@ bar VERBOSITY - 这个变量可以被设置为值defaultverboseterse或者sqlstate来控制错误报告的详细程度(另见\errverbose,在想得到之前的错误的详细版本时使用)。 + 这个变量可以被设置为值defaultverboseterse或者sqlstate来控制错误报告的详细程度(另见\errverbose,在想得到刚遇到的错误的详细信息时使用)。 @@ -3132,7 +2835,7 @@ bar VERSION_NUM - 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或重设。 + 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或取消设置。 @@ -3142,11 +2845,11 @@ bar - - <acronym>SQL</acronym> 中插入变量 + + <acronym>SQL</acronym> 插值 - psql变量的一个关键特性是可以把它们替换(插入)到常规SQL语句中,也可以把它们作为元命令的参数。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。插入一个值而不加引号的语法是在变量名前面加上一个冒号(:)。例如, + psql变量的一个关键特性是可以把它们替换(插值)到常规SQL语句中,也可以把它们替换到元命令的参数中。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。不加引号地插值一个值的语法是在变量名前面加上一个冒号(:)。例如, testdb=> \set foo 'my_table' testdb=> SELECT * FROM :foo; @@ -3155,7 +2858,7 @@ testdb=> SELECT * FROM :foo; - 当一个值被用作 SQL 文本或者标识符时,最安全的是把它加上引用。要引用一个变量的值作为 SQL 文本,可以把变量名称放在单引号中并且在引号前面写一个冒号。要引用作为 SQL 标识符,则可以把变量名称放在双引号中并且在引号前面写一个冒号。这种结构可以正确地处理变量值中嵌入的引号和其他特殊字符。之前的示例用这种方法写会更安全: + 当一个值要用作 SQL 字面量或标识符时,最安全的做法是为它加上引号。要将变量值作为 SQL 字面量加引号,应写一个冒号,后面跟用单引号括起来的变量名。要将变量值作为 SQL 标识符加引号,则在冒号后面用双引号括起变量名。这些写法能正确处理变量值中嵌入的引号和其他特殊字符。前面的示例可用以下更安全的写法: testdb=> \set foo 'my_table' testdb=> SELECT * FROM :"foo"; @@ -3163,11 +2866,11 @@ testdb=> SELECT * FROM :"foo"; - 在被引用的SQL文本和标识符中将不会执行变量插入。因此,一个诸如':foo'的结构不会从一个变量的值产生一个被引用的文本(即便能够也会不安全,因为无法正确地处理嵌入在值中的引号)。 + 在加引号的SQL字面量和标识符内部,不会执行变量插值。因此,':foo'这样的写法不能根据变量值生成加引号的字面量(即使能够生效,也不安全,因为它无法正确处理变量值中嵌入的引号)。 - 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个被引用的字符串插入: + 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个加引号的字符串进行插值: testdb=> \set content `cat my_file.txt` testdb=> INSERT INTO my_table VALUES (:'content'); @@ -3176,7 +2879,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 因为冒号可以合法地出现在 SQL 命令中,一次明显的插入尝试(即:name:'name'或者:"name")不会被替换,除非所提及的变量就是当前被设置的。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 + 因为冒号可以合法地出现在 SQL 命令中,一次明显的插值尝试(即:name:'name'或者:"name")不会被替换,除非所指的变量当前已设置。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 @@ -3184,12 +2887,12 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 文本或者标识符的冒号引用语法是一种psql扩展。 + 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 字面量或者标识符的冒号加引号语法是一种psql扩展。 - + 提示符 @@ -3203,33 +2906,26 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %M - - 数据库服务器的完整主机名(带域名);如果连接通过 Unix 域套接字建立,则为 [local];如果 Unix 域套接字不在编译时默认位置,则为 [local:/dir/name]。 - + 数据库服务器的完整主机名(含域名);如果通过 Unix 域套接字连接,则为[local];如果 Unix 域套接字不在编译时指定的默认位置,则为[local:/dir/name] %m - - 数据库服务器的主机名,在第一个点处分截;如果连接通过 Unix 域套接字建立,则为 [local]。 - + 数据库服务器的主机名,在第一个点号处截断;如果通过 Unix 域套接字连接,则为[local] %> - 数据库服务器正在监听的端口号。 + 数据库服务器监听的端口号。 %n - - 数据库会话用户名。(由于 SET SESSION - AUTHORIZATION 命令的作用,该值在数据库会话期间可能会发生变化。) - + 数据库会话用户名。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) @@ -3248,11 +2944,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %# - - 如果会话用户是数据库超级用户,则输出 - #,否则输出 >。(由于 SET SESSION - AUTHORIZATION 命令的作用,该值的展开在数据库会话期间可能会发生变化。) - + 如果会话用户是数据库超级用户,则为#,否则为>。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) @@ -3268,7 +2960,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %R - 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 dollar-quoted 字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 + 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 美元引用字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 @@ -3295,7 +2987,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %digits - 带有所示八进制码的字符被替换。 + 替换为指定八进制代码对应的字符。 @@ -3397,14 +3089,14 @@ $endif - )命令行选项也可用于在单次运行psql时禁用 Readline。这会阻止制表补全、命令行历史的使用或记录,以及多行命令的编辑。当你需要复制粘贴包含 TAB 字符的文本时,它尤其有用。 + )命令行选项也可用于在单次运行psql时禁用 Readline。这会阻止TAB 补全、命令行历史的使用或记录,以及多行命令的编辑。当你需要复制粘贴包含 TAB 字符的文本时,它尤其有用。 - + 环境 @@ -3489,9 +3181,9 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 如果查询结果无法在屏幕上显示完整,它们将通过此命令进行传输。典型的值是moreless。 + 如果查询结果无法在屏幕上显示完整,它们会通过管道传给此命令。典型的值是moreless。 可以通过将PSQL_PAGERPAGER设置为空字符串,或通过调整\pset命令的与分页相关的选项来禁用分页器。 - 这些变量按照列出的顺序进行检查;首先设置的变量将被使用。 + 这些变量按照列出的顺序进行检查;使用按该顺序找到的第一个已设置的变量。 如果它们都没有设置,默认情况下在大多数平台上使用more,但在Cygwin上使用less @@ -3571,7 +3263,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' 在任何情况下,可以通过设置PSQLRC环境变量来覆盖此默认文件路径。 - 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加破折号和PostgreSQL的主要或次要版本标识符来使其与psql版本相关, + 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加连字符和PostgreSQL的大版本或小版本标识符来使其与psql版本相关, 例如~/.psqlrc-&majorversion;~/.psqlrc-&version;。 最具体版本匹配的文件将优先读取,而不是非特定版本的文件。 这些版本后缀是在确定文件路径后添加的,如上所述。 @@ -3599,14 +3291,14 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - psql最适合与相同或较旧主要版本的服务器配合使用。 - 如果服务器的版本比psql本身更新,反斜杠命令特别容易失败。 - 然而,\d系列的反斜杠命令应该可以在版本回溯到9.2的服务器上运行, + psql最适合与相同或较旧大版本的服务器配合使用。 + 如果服务器的版本比psql本身更新,反斜线命令特别容易失败。 + 然而,\d系列的反斜线命令应该可以在最低至 9.2 版本的服务器上运行, 但不一定适用于比psql本身更新的服务器。运行SQL命令和显示查询结果的一般功能 - 也应该可以在更新主要版本的服务器上运行,但不能保证在所有情况下都能实现。 + 也应该可以在更新大版本的服务器上运行,但不能保证在所有情况下都能实现。 - 如果你想用psql连接到多个具有不同主版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个主版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 + 如果你想用psql连接到多个具有不同大版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个大版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 @@ -3620,7 +3312,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空格。现在则要求一些空格。 + 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空白。现在则要求用空白分隔。 diff --git a/zh/17/release-17.sgml b/zh/17/release-17.sgml index 81095a63..b831c95d 100644 --- a/zh/17/release-17.sgml +++ b/zh/17/release-17.sgml @@ -1690,7 +1690,7 @@ Branch: REL_14_STABLE [dda622edc] 2026-08-02 16:49:18 -0400 --> - 修复为文本搜索词典创建缓存条目的过程中发生内存不足后导致的崩溃 + 修复为文本检索词典创建缓存条目的过程中发生内存不足后导致的崩溃 (Tom Lane) § @@ -3924,7 +3924,7 @@ Branch: REL_14_STABLE [6cae0c2bd] 2026-04-22 11:09:21 -0400 损坏或恶意的词缀文件可能使服务器崩溃。 - 这不被视为安全问题,因为文本搜索配置文件被假定为可信, + 这不被视为安全问题,因为文本检索配置文件被假定为可信, 但仍然值得修复。 diff --git a/zh/17/rowtypes.sgml b/zh/17/rowtypes.sgml index 7782828c..47f3dccb 100644 --- a/zh/17/rowtypes.sgml +++ b/zh/17/rowtypes.sgml @@ -75,7 +75,7 @@ CREATE TABLE inventory_item ( - 构造组合值 + 构造复合值 复合类型 @@ -83,7 +83,7 @@ CREATE TABLE inventory_item ( - 要把组合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,组合常量的一般格式如下: + 要把复合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,复合常量的一般格式如下: '( val1 , val2 , ... )' @@ -103,11 +103,11 @@ CREATE TABLE inventory_item ( - (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。必要时可能需要显式指定类型。) + (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。可能需要显式指定类型,以指明应将该常量转换为哪种类型。) - ROW表达式语法也可以用于构造组合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: + ROW表达式语法也可以用于构造复合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: ROW('fuzzy dice', 42, 1.99) ROW('', 42, NULL) @@ -126,7 +126,7 @@ ROW('', 42, NULL) 访问复合类型 - 要访问组合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: + 要访问复合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: SELECT item.name FROM on_hand WHERE item.price > 9.99; @@ -148,7 +148,7 @@ SELECT (on_hand.item).name FROM on_hand WHERE (on_hand.item).price > 9.99; - 无论何时从组合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回组合值的函数结果中只选取一个字段,你需要这样写: + 无论何时从复合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回复合值的函数结果中只选取一个字段,你需要这样写: SELECT (my_func(...)).field FROM ... @@ -164,10 +164,10 @@ SELECT (my_func(...)).field FROM ... - 修改组合值 + 修改复合类型 - 下面是一些插入和更新组合列时正确语法的示例。先看插入或更新整个列值的情况: + 下面是一些插入和更新复合列时正确语法的示例。先看插入或更新整个列值的情况: INSERT INTO mytab (complex_col) VALUES((1.1,2.2)); @@ -179,7 +179,7 @@ UPDATE mytab SET complex_col = ROW(1.1,2.2) WHERE ...; - 我们也可以更新组合列中的单个子字段: + 我们也可以更新复合列中的单个子字段: UPDATE mytab SET complex_col.r = (complex_col).r + 1 WHERE ...; @@ -208,11 +208,11 @@ INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2); - 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的组合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: + 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的复合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: SELECT c FROM inventory_item c; - 这个查询会产生一个单独的组合值列,因此我们可能得到如下输出: + 这个查询会产生一个单独的复合值列,因此我们可能得到如下输出: c ------------------------ @@ -223,7 +223,7 @@ SELECT c FROM inventory_item c; - 普通的限定列名语法table_name.column_name可以理解为对该表当前行的组合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) + 普通的限定列名语法table_name.column_name可以理解为对该表当前行的复合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) @@ -256,19 +256,19 @@ SELECT (myfunc(x)).a, (myfunc(x)).b, (myfunc(x)).c FROM some_table; SELECT m.* FROM some_table, LATERAL myfunc(x) AS m; - 把该函数放在LATERAL FROM项中,可以防止它对每一行被调用多于一次。m.*仍会展开为m.a, m.b, m.c,但现在这些变量只是对该FROM项输出的引用。(这里的LATERAL关键字其实是可选的,不过我们把它写出来,是为了明确该函数会从some_table中取得x。) + 把该函数放在LATERAL FROM项中,可以避免它在每行上被调用多次。m.*仍会展开为m.a, m.b, m.c,但现在这些变量只是对该FROM项输出的引用。(这里的LATERAL关键字其实是可选的,不过我们把它写出来,是为了明确该函数会从some_table中取得x。) - 当composite_value.*出现在SELECT输出列表、INSERT/UPDATE/DELETE/MERGE中的RETURNING列表、VALUES子句或行构造器的顶层时,就会产生这种列展开行为。在所有其他上下文中(包括嵌套在上述结构之内时),给组合值附加.*不会改变其值,因为它表示所有列,因此结果仍然是同一个组合值。例如,如果somefunc()接受一个组合值参数,这些查询就是等价的: + 当composite_value.*出现在SELECT输出列表、INSERT/UPDATE/DELETE/MERGE中的RETURNING列表、VALUES子句或行构造器的顶层时,就会产生这种列展开行为。在所有其他上下文中(包括嵌套在上述结构之内时),给复合值附加.*不会改变其值,因为它表示所有列,因此结果仍然是同一个复合值。例如,如果somefunc()接受一个复合值参数,这些查询就是等价的: SELECT somefunc(c.*) FROM inventory_item c; SELECT somefunc(c) FROM inventory_item c; - 在这两种情况下,inventory_item的当前行都会作为单个组合值参数传递给该函数。尽管.*在这种场合并不起作用,使用它仍是一种良好风格,因为它能明确表明这里想要的是组合值。特别是,解析器会把c.*中的c视为表名或别名,而不是列名,因此不会产生歧义;而没有.*时,就不清楚c究竟表示表名还是列名,而且如果存在名为c的列,实际上会优先按列名解释。 + 在这两种情况下,inventory_item的当前行都会作为单个复合值参数传递给该函数。尽管.*在这种场合并不起作用,使用它仍是一种良好风格,因为它能明确表明这里想要的是复合值。特别是,解析器会把c.*中的c视为表名或别名,而不是列名,因此不会产生歧义;而没有.*时,就不清楚c究竟表示表名还是列名,而且如果存在名为c的列,实际上会优先按列名解释。 @@ -278,7 +278,7 @@ SELECT * FROM inventory_item c ORDER BY c; SELECT * FROM inventory_item c ORDER BY c.*; SELECT * FROM inventory_item c ORDER BY ROW(c.*); - 所有这些ORDER BY子句都指定了该行的组合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: + 所有这些ORDER BY子句都指定了该行的复合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: SELECT * FROM inventory_item c ORDER BY ROW(c.name, c.supplier_id, c.price); SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); @@ -287,7 +287,7 @@ SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); - 另一种与组合值有关的特殊语法行为是,我们可以使用函数记法来提取组合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: + 另一种与复合值有关的特殊语法行为是,我们可以使用函数记法来提取复合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: SELECT c.name FROM inventory_item c WHERE c.price > 1000; @@ -306,11 +306,11 @@ SELECT c.somefunc FROM inventory_item c; 函数记法与字段记法之间的这种等价性,使得我们可以通过在复合类型上使用函数来实现计算字段 - computed field + 计算字段 - field - computed + 字段 + 计算 使用上面最后一种查询形式的应用程序,无需直接知道somefunc并不是该表中的真实列。 @@ -328,7 +328,7 @@ SELECT c.somefunc FROM inventory_item c; 复合类型的输入和输出语法 - 组合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明组合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 + 复合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明复合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 '( 42)' @@ -336,7 +336,7 @@ SELECT c.somefunc FROM inventory_item c; - 如前所示,在写组合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让组合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的组合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作组合语法的数据字符。 + 如前所示,在写复合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让复合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的复合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作复合语法的数据字符。 @@ -350,18 +350,18 @@ SELECT c.somefunc FROM inventory_item c; - 记住,你在 SQL 命令中写的内容会先被解释为字符串字面量,然后才会被解释为组合值。这会使所需的反斜杠数量翻倍(假定使用的是转义字符串语法)。例如,要在组合值中插入一个包含双引号和反斜杠的text字段,需要写成: + 记住,你在 SQL 命令中写的内容会先被解释为字符串字面量,然后才会被解释为复合值。这会使所需的反斜杠数量翻倍(假定使用的是转义字符串语法)。例如,要在复合值中插入一个包含双引号和反斜杠的text字段,需要写成: INSERT ... VALUES ('("\"\\")'); - 字符串字面量处理器会去掉一层反斜杠,因此传到组合值解析器时看起来是("\"\\")。随后,送入text数据类型输入例程的字符串就变成了"\。(如果我们使用的数据类型的输入例程也会把反斜杠当作特殊字符处理,例如bytea,那么为了在存储的组合字段中得到一个反斜杠,命令里可能需要多达八个反斜杠。)美元引用(见)可用于避免反斜杠加倍的需要。 + 字符串字面量处理器会去掉一层反斜杠,因此传到复合值解析器时看起来是("\"\\")。随后,送入text数据类型输入例程的字符串就变成了"\。(如果我们使用的数据类型的输入例程也会把反斜杠当作特殊字符处理,例如bytea,那么为了在存储的复合字段中得到一个反斜杠,命令里可能需要多达八个反斜杠。)美元引用(见)可用于避免反斜杠加倍的需要。 - 在 SQL 命令中编写组合值时,ROW构造器语法通常比组合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是组合成员时完全相同。 + 在 SQL 命令中编写复合值时,ROW构造器语法通常比复合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是复合成员时完全相同。 diff --git a/zh/17/textsearch.sgml b/zh/17/textsearch.sgml index 0bb657b1..79a1a04e 100644 --- a/zh/17/textsearch.sgml +++ b/zh/17/textsearch.sgml @@ -1,21 +1,21 @@ - 全文搜索 + 全文检索 - 全文搜索 + 全文检索 - 文本搜索 + 文本检索 介绍 - 全文搜索(或简称文本搜索)提供了识别满足 + 全文检索(或简称文本检索)提供了识别满足 查询条件的自然语言文档的能力, 并且可按它们与查询的相关度进行排序。最常见的搜索类型,是找出所有包含给定 查询词的文档,并按它们与查询的相似性 @@ -25,7 +25,7 @@ - 文本搜索操作符在数据库中已经存在很多年了。 + 文本检索操作符在数据库中已经存在很多年了。 PostgreSQL为文本数据类型提供了 ~~*LIKEILIKE 操作符,但它们缺少现代信息系统所要求的许多关键特性: @@ -138,7 +138,7 @@ ()。围绕这两种数据类型还有许多函数和 操作符(),其中最重要的是匹配操作符 @@,我们将在中介绍。 - 全文搜索还可以借助索引加速()。 + 全文检索还可以借助索引加速()。 @@ -147,11 +147,11 @@ 文档 - 全文搜索 + 文本检索 - 文档是全文搜索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本搜索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 + 文档是全文检索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本检索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 @@ -179,7 +179,7 @@ WHERE m.mid = d.did AND m.mid = 12; - 为了进行文本搜索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 + 为了进行文本检索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 @@ -187,7 +187,7 @@ WHERE m.mid = d.did AND m.mid = 12; 基本文本匹配 - 在PostgreSQL中,全文搜索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: + 在PostgreSQL中,全文检索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: SELECT 'a fat cat sat on a mat and ate a fat rat'::tsvector @@ 'cat & rat'::tsquery; @@ -203,7 +203,7 @@ SELECT 'fat & cow'::tsquery @@ 'a fat cat sat on a mat and ate a fat rat'::t - 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索术语,这些术语必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个术语组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本搜索匹配更像是这样: + 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索词,这些搜索词必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个搜索词组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本检索匹配更像是这样: SELECT to_tsvector('fat cats ate fat rats') @@ to_tsquery('fat & rat'); @@ -221,7 +221,7 @@ SELECT 'fat cats ate fat rats'::tsvector @@ to_tsquery('fat & rat'); f - 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,默认假定已经正规化,因此 rats 不会匹配 rat。 + 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,被假定为已经正规化,因此 rats 不会匹配 rat @@ -290,49 +290,49 @@ SELECT phraseto_tsquery('the cats ate the rats'); 配置 - 前述的都是简单的文本搜索示例。正如前面所提到的,全文搜索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如基于空白之外的解析。这个功能由文本搜索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 + 前述的都是简单的文本检索示例。正如前面所提到的,全文检索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如不局限于按空白划分的解析。这个功能由文本检索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 - 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本搜索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config。 + 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本检索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config - 依赖一个配置的每一个文本搜索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当这个参数被忽略时,default_text_search_config才被使用。 + 依赖一个配置的每一个文本检索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当省略这个参数时,default_text_search_config才被使用。 - 为了让建立自定义文本搜索配置更容易,一个配置可以从更简单的数据库对象来建立。PostgreSQL的文本搜索功能提供了四类配置相关的数据库对象: + 为了便于构建自定义文本检索配置,配置由更简单的数据库对象组合而成。PostgreSQL 的文本检索功能提供了四类与配置相关的数据库对象: - 文本搜索解析器将文档拆分成词元并分类每个词元(例如,作为词或者数字)。 + 文本检索解析器将文档拆分成词元并对每个词元分类(例如,作为词或者数字)。 - 文本搜索词典将词元转变成正规化的形式并拒绝停用词。 + 文本检索词典将词元转变成正规化的形式并拒绝停用词。 - 文本搜索模板提供位于词典底层的函数(一个词典简单地指定一个模板和一组用于模板的参数)。 + 文本检索模板提供位于词典底层的函数(词典只需指定一个模板及其一组参数)。 - 文本搜索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 + 文本检索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 - 文本搜索解析器和模板是从低层 C 函数构建而来,因此它要求 C 编程能力来开发新的解析器和模板,并且还需要超级用户权限来把它们安装到一个数据库中(在PostgreSQL发布的contrib/区域中有一些附加的解析器和模板的示例)。由于词典和配置只是对底层解析器和模板的参数化和连接,不需要特殊的权限来创建一个新词典或配置。创建定制词典和配置的示例将在本章稍后的部分给出。 + 文本检索解析器和模板由底层 C 函数构成,因此开发新的解析器和模板需要 C 编程能力,将它们安装到数据库中则需要超级用户权限。(PostgreSQL 发行版的 contrib/ 目录中有附加解析器和模板的示例。)词典和配置只是为底层解析器和模板设置参数并将它们连接起来,因此创建新词典或配置不需要特殊权限。本章后面会给出创建自定义词典和配置的示例。 @@ -343,14 +343,14 @@ SELECT phraseto_tsquery('the cats ate the rats'); 表和索引 - 在前一节中的示例演示了使用简单常数字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 + 在前一节中的示例演示了使用简单常量字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 搜索表 - 即使没有索引,也可以执行全文搜索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend: + 即使没有索引,也可以执行全文检索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend SELECT title @@ -374,7 +374,7 @@ WHERE to_tsvector(body) @@ to_tsquery('friend'); - 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 中同时包含 createtable: + 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 合在一起包含 createtable SELECT title @@ -388,7 +388,7 @@ LIMIT 10; - 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本搜索在实际使用中通常都需要建立索引。 + 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本检索在实际使用中通常都需要建立索引。 @@ -397,13 +397,13 @@ LIMIT 10; 创建索引 - 我们可以创建一个GIN索引()来加速文本搜索: + 我们可以创建一个GIN索引()来加速文本检索: CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector('english', body)); - 注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本搜索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含使用不同文本搜索配置创建的tsvector,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 + 注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本检索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含使用不同文本检索配置创建的tsvector,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 @@ -420,10 +420,7 @@ CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector(config_name, body)); 这里 config_namepgweb 表中的一个列。这样就允许在同一个索引中混合使用不同配置,同时记录每个索引项使用的是哪一种配置。例如,如果文档集合中包含不同语言的文档,这就会很有用。同样,打算使用该索引的查询也必须写成对应的形式,例如 WHERE to_tsvector(config_name, body) @@ 'a & b' - - 索引甚至可以连接列: - - + 索引甚至可以串接多个列: CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector('english', title || ' ' || body)); @@ -443,7 +440,7 @@ ALTER TABLE pgweb CREATE INDEX textsearch_idx ON pgweb USING GIN(textsearchable_index_col); - 现在我们准备好执行一个快速的全文搜索了: + 现在我们准备好执行一个快速的全文检索了: SELECT title @@ -455,7 +452,7 @@ LIMIT 10; - 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本搜索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 + 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本检索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 @@ -463,10 +460,10 @@ LIMIT 10; - 控制文本搜索 + 控制文本检索 - 要实现全文搜索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 + 要实现全文检索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 @@ -485,7 +482,7 @@ to_tsvector( config - to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本搜索配置进行处理。下面是一个简单示例: + to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本检索配置进行处理。下面是一个简单示例: SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); @@ -500,7 +497,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每类词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本搜索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english。 + to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每个词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本检索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english @@ -508,7 +505,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为空,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: + 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为 NULL,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: UPDATE tt SET ti = @@ -659,12 +656,12 @@ websearch_to_tsquery( config - 无引号文本:不在引号中的文本会被转换为由&操作符分隔的词,就像经过plainto_tsquery处理一样。 + 未加引号的文本:不在引号中的文本会被转换为由&操作符分隔的词,就像经过plainto_tsquery处理一样。 - "引号文本":引号中的文本会被转换为由<->操作符分隔的词,就像经过phraseto_tsquery处理一样。 + "加引号的文本":引号中的文本会被转换为由<->操作符分隔的词,就像经过phraseto_tsquery处理一样。 @@ -722,7 +719,7 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); 搜索结果排名 - 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及它们出现于文档中哪个部分。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 + 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及这些词所处文档部分的重要程度。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 @@ -813,12 +810,12 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 8 用文档中唯一词的数量除排名 + 8 用文档中不同词的数量除排名 - 16 用 1 + 文档中唯一词数量的对数除排名 + 16 用 1 + 文档中不同词数量的对数除排名 @@ -832,7 +829,7 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。正规化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 + 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。归一化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 @@ -904,7 +901,7 @@ ts_headline( config ts_headline 接收文档和查询,并返回文档中一段 - 高亮查询词条的摘录。具体而言,该函数会先用查询选择相关文本片段,然后 + 高亮查询词的摘录。具体而言,该函数会先用查询选择相关文本片段,然后 高亮查询中出现的所有词,即使这些词的位置并不满足查询本身的位置限制。 用于解析文档的配置可通过 config 指定; 若省略 config,则使用 @@ -952,7 +949,7 @@ ts_headline( config - 警告:跨站脚本(XSS)安全 + 警告:跨站脚本(XSS)安全性 ts_headline 的输出不保证可安全直接嵌入网页。 当 HighlightAllfalse(默认值)时, @@ -1011,7 +1008,7 @@ occurrences to display in the result.', 附加特性 - 本节介绍一些在文本搜索中很有用的附加函数和操作符。 + 本节介绍一些在文本检索中很有用的附加函数和操作符。 @@ -1124,7 +1121,7 @@ occurrences to display in the result.', - 返回用 AND 结合的两个给定查询。 + 返回两个给定查询的 AND 组合。 @@ -1138,7 +1135,7 @@ occurrences to display in the result.', - 返回用 OR 结合的两个给定查询。 + 返回两个给定查询的 OR 组合。 @@ -1191,7 +1188,7 @@ SELECT to_tsquery('fat') <-> to_tsquery('cat | rat'); - 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: + 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在其后距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: SELECT tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10); @@ -1245,10 +1242,7 @@ SELECT numnode('foo & bar'::tsquery); - - 返回可用于索引搜索的tsquery部分。这个函数可用于检测不可索引的查询,例如只包含停用词或只包含否定项的查询。例如: - - + 返回一个tsquery中可用于搜索索引的部分。此函数可用于检测无法使用索引的查询,例如只包含停用词或只包含否定词项的查询。例如: SELECT querytree(to_tsquery('defined')); querytree ----------- @@ -1424,7 +1418,7 @@ SELECT title, body FROM messages WHERE tsv @@ to_tsquery('title & body'); - 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本搜索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 + 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本检索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 @@ -1491,7 +1485,7 @@ ts_stat(sqlquery text, - 如果提供了 weights,则只统计具有这些权重之一的出现。 + 如果提供了 weights,则只统计具有这些权重之一的词的出现次数。 @@ -1520,7 +1514,7 @@ LIMIT 10; 解析器 - 文本搜索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 + 文本检索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 @@ -1543,12 +1537,12 @@ LIMIT 10; asciiword - 单词,所有 ASCII 字母 + 单词,全部由 ASCII 字母组成 elephant word - 单词,所有字母 + 单词,全部由字母组成 mañana @@ -1558,12 +1552,12 @@ LIMIT 10; asciihword - 带连字符的单词,所有 ASCII + 带连字符的单词,全部为 ASCII 字符 up-to-date hword - 带连字符的单词,所有字母 + 带连字符的单词,由字母组成 lógico-matemática @@ -1573,12 +1567,12 @@ LIMIT 10; hword_asciipart - 带连字符的单词部分,所有 ASCII + 带连字符的单词部分,全部为 ASCII 字符 postgresql-beta1 上下文中的 postgresql hword_part - 带连字符的单词部分,所有字母 + 带连字符的单词部分,全部由字母组成 lógico-matemática 上下文中的 lógicomatemática @@ -1653,8 +1647,8 @@ LIMIT 10; blank - 空格符号 - (其他不识别的任意空白或标点符号) + 空白符号 + (未被识别为其他类型的空白或标点符号) @@ -1662,12 +1656,12 @@ LIMIT 10; - 解析器的一个字母的概念由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时可以用来区别它们。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 + 解析器对字母的界定由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时区分它们会很有用。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 email不支持所有由RFC 5322定义的有效电子邮件字符。 - 具体来说,电子邮件用户名仅支持句号、短横线和下划线这些非字母数字字符。 + 具体来说,电子邮件用户名仅支持句点、短横线和下划线这些非字母数字字符。 @@ -1716,7 +1710,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h 词典 - 词典用于消除不应参与搜索的词(stop words),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 + 词典用于消除不应参与搜索的词(停用词),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 @@ -1731,7 +1725,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - URL地址可以被正规化,以便让等价的 URL 匹配: + URL 地址可以规范化,以便让等价的 URL 匹配: @@ -1776,32 +1770,32 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤字典) + 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤词典 - 如果字典知道该词元但它是一个停用词,则返回一个空数组 + 如果词典知道该词元但它是一个停用词,则返回一个空数组 - 如果字典不识别该输入词元,则返回NULL + 如果词典不识别该输入词元,则返回NULL - PostgreSQL为许多语言提供了预定义的字典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发布的contrib/区域。 + PostgreSQL为许多语言提供了预定义的词典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发行版的contrib/目录。 - 文本搜索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 + 文本检索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 - 配置词典列表的一般规则是,把最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语分类词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: + 配置词典列表的一般规则是,把适用范围最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语同义词词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: ALTER TEXT SEARCH CONFIGURATION astro_en @@ -1810,14 +1804,14 @@ ALTER TEXT SEARCH CONFIGURATION astro_en - 过滤词典可以放在列表中的任何位置,只是不能放在最后,因为放在最后就没有意义了。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 + 过滤词典可以放在列表中的任何位置,但放在末尾没有用处。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 停用词 - 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文搜索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: + 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文检索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: SELECT to_tsvector('english', 'in the list of stop words'); @@ -1949,7 +1943,7 @@ SELECT * FROM ts_debug('english', 'Paris'); - synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基本名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 + synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 @@ -2011,28 +2005,28 @@ mydb=# SELECT 'indexes are very useful'::tsvector @@ to_tsquery('tst', 'indices' - 基本上一个分类词典会用一个首选词替换所有非首选词,并且也可选择地保留原始术语用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典要求一个下列格式的配置文件: + 分类词典基本上会用一个首选词替换所有非首选词,并且也可以选择保留原始词用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典需要一个采用以下格式的配置文件: -# this is a comment -sample word(s) : indexed word(s) -more sample word(s) : more indexed word(s) +# 这是一条注释 +示例词(一个或多个) : 索引词(一个或多个) +更多示例词(一个或多个) : 更多索引词(一个或多个) ... - 其中冒号(:)符号扮演了一个短语及其替换之间的定界符。 + 其中冒号(:)符号用作短语及其替换词之间的分隔符。 - 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过对子词典的应用,但所有样例词都必须能被子词典识别。 + 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过将子词典应用于该词,但所有样例词都必须能被子词典识别。 - 如果有多个短语匹配输入,则分类词典选择最长的那一个,并且使用最后的定义打破连结。 + 如果有多个短语匹配输入,分类词典会选择最长的匹配;长度相同时使用最后的定义。 - 由子词典识别的特定停用词不能够被指定;改用?标记任何可以出现停用词的地方。例如,假定根据子词典athe是停用词: + 由子词典识别的特定停用词不能够被指定;改用?标记可出现任意停用词的位置。例如,假定根据子词典athe是停用词: ? one ? two : swsw @@ -2074,7 +2068,7 @@ CREATE TEXT SEARCH DICTIONARY thesaurus_simple ( - mythesaurus是分类词典配置文件的基础名称(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 + mythesaurus是分类词典配置文件的基名(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 @@ -2099,7 +2093,7 @@ ALTER TEXT SEARCH CONFIGURATION russian 分类词典示例 - 考虑简单的天文词库 thesaurus_astro,其中包含一些天文单词组合: + 考虑一个简单的天文分类词典 thesaurus_astro,其中包含一些天文单词组合: supernovae stars : sn @@ -2167,7 +2161,7 @@ SELECT plainto_tsquery('supernova star'); <application>Ispell</application> 词典 - Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以把搜索词 bank 的词尾变化和词形变化对应起来,例如 bankingbankedbanksbanks'bank's。 + Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以匹配搜索词 bank 的所有变格和变位形式,例如 bankingbankedbanksbanks'bank's @@ -2179,12 +2173,12 @@ SELECT plainto_tsquery('supernova star'); - 要创建一个Ispell词典,执行这三步: + 要创建一个Ispell词典,请执行以下步骤: - 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。有必要抽取.aff.dic文件,把扩展改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): + 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。需要提取.aff.dic文件,将扩展名改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): iconv -f ISO_8859-1 -t UTF-8 -o nn_no.affix nn_NO.aff iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic @@ -2193,7 +2187,7 @@ iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic - 拷贝文件到$SHAREDIR/tsearch_data目录 + 复制文件到$SHAREDIR/tsearch_data目录 @@ -2211,11 +2205,11 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( - 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基础名称。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 + 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基名。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 - Ispell 词典通常识别一个有限集合的词,这样它们后面应该跟着另一个更广义的词典;例如,一个 Snowball 词典,它可以识别所有东西。 + Ispell 词典通常只能识别有限的词,因此其后应跟着另一个覆盖范围更广的词典;例如,一个 Snowball 词典,它可以识别所有输入。 @@ -2223,13 +2217,13 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( prefixes flag *A: - . > RE # As in enter > reenter + . > RE # 例如 enter > reenter suffixes flag T: - E > ST # As in late > latest - [^AEIOU]Y > -Y,IEST # As in dirty > dirtiest - [AEIOU]Y > EST # As in gray > grayest - [^EY] > EST # As in small > smallest + E > ST # 例如 late > latest + [^AEIOU]Y > -Y,IEST # 例如 dirty > dirtiest + [AEIOU]Y > EST # 例如 gray > grayest + [^EY] > EST # 例如 small > smallest @@ -2245,14 +2239,14 @@ lark/MRS .dict文件的格式是: -basic_form/affix_class_name +基本词形/词缀类名 .affix文件中,每一个词缀标志以下面的格式描述: -condition > [-stripping_letters,] adding_affix +条件 > [-删除的字母,] 添加的词缀 @@ -2261,7 +2255,7 @@ condition > [-stripping_letters,] adding_affix - Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,它标记可以参与到复合格式中的词典词: + Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,用于标记词典中可以参与构成复合词的词: compoundwords controlled z @@ -2291,7 +2285,7 @@ SFX T 0 est [^ey] - 一个词缀类的第一行是头部。头部后面列出了词缀规则的域: + 一个词缀类的第一行是首部。首部后面列出了词缀规则的字段: @@ -2343,7 +2337,7 @@ largehearted <application>Snowball</application> 词典 - Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每一个算法懂得按照其语言中的拼写,如何缩减词的常见变体形式为一个基础或词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择地指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。例如,有一个内置的定义等效于 + Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每种算法都知道如何把其语言中词的常见变体约简为基本拼写形式,也就是词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。例如,有一个内置的定义等效于 CREATE TEXT SEARCH DICTIONARY english_stem ( @@ -2357,7 +2351,7 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( - 一个Snowball词典识别所有的东西,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 + 一个Snowball词典识别所有输入,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 @@ -2368,11 +2362,11 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( 配置示例 - 一个文本搜索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本搜索配置来执行其处理。配置参数指定了默认配置的名称,如果忽略了显式的配置参数,文本搜索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 + 一个文本检索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本检索配置来执行其处理。配置参数指定了默认配置的名称,如果省略了显式的配置参数,文本检索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 - 有一些预定义的文本搜索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本搜索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本搜索对象()的信息。 + 有一些预定义的文本检索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本检索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本检索对象()的信息。 @@ -2464,17 +2458,17 @@ SHOW default_text_search_config; - 测试和调试文本搜索 + 测试和调试文本检索 - 一个自定义文本搜索配置的行为很容易变得混乱。本节中描述的函数对于测试文本搜索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 + 一个自定义文本检索配置的行为很容易让人困惑。本节中描述的函数对于测试文本检索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 配置测试 - 函数ts_debug允许简单地测试一个文本搜索配置。 + 函数ts_debug可方便地测试一个文本检索配置。 @@ -2493,7 +2487,7 @@ ts_debug( config re - ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果该参数被忽略则使用default_text_search_config指定的配置。 + ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果省略该参数则使用default_text_search_config指定的配置。 @@ -2568,7 +2562,7 @@ SELECT * FROM ts_debug('english', 'a fat cat sat on a mat - it ate a fat rats') - 为了一个更广泛的示范,我们先为英语语言创建一个public.english配置和 Ispell 词典: + 为了做更完整的演示,我们先为英语创建一个public.english配置和 Ispell 词典: @@ -2626,7 +2620,7 @@ FROM ts_debug('public.english', 'The Brightest supernovaes'); 解析器测试 - 下列函数允许直接测试一个文本搜索解析器。 + 下列函数允许直接测试一个文本检索解析器。 @@ -2668,7 +2662,7 @@ ts_token_type(parser_oid oid< - ts_token_type返回一个表,描述指定解析器能够识别的每一种词元。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: + ts_token_type返回一个表,描述指定解析器能够识别的每一种词元类型。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: SELECT * FROM ts_token_type('default'); @@ -2706,7 +2700,7 @@ SELECT * FROM ts_token_type('default'); 词典测试 - ts_lexize函数帮助词典测试。 + ts_lexize函数便于测试词典。 @@ -2764,17 +2758,17 @@ SELECT plainto_tsquery('supernovae stars'); - 文本搜索的首选索引类型 + 文本检索的首选索引类型 - 文本搜索 + 文本检索 索引 - 有两种索引可以用来加速全文搜索:GIN和 + 有两种索引可以用来加速全文检索:GINGiST。 - 请注意,索引对于全文搜索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 + 请注意,索引对于全文检索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 @@ -2788,7 +2782,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GIN - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIN (column); @@ -2808,7 +2802,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GiST - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIST (column [ { DEFAULT | tsvector_ops } (siglen = number) ] ); @@ -2818,7 +2812,7 @@ SELECT plainto_tsquery('supernovae stars'); 创建基于 GiST(广义搜索树)的索引。 column可以是tsvectortsquery类型。 - 可选的整数参数siglen确定签名长度(有关详细信息,请参见下文)。 + 可选的整数参数siglen确定以字节为单位的签名长度(有关详细信息,请参见下文)。 @@ -2827,7 +2821,7 @@ SELECT plainto_tsquery('supernovae stars'); - GIN 索引是文本搜索的首选索引类型。作为倒排索引,每个词(词位)在 + GIN 索引是文本检索的首选索引类型。作为倒排索引,每个词(词位)在 其中都有一个索引项,其中有压缩过的匹配位置的列表。多词搜索可以找到 第一个匹配,然后使用该索引移除缺少额外词的行。GIN 索引只存储 tsvector值的词(词位),并且不存储它们的权重标签。因此, @@ -2835,19 +2829,19 @@ SELECT plainto_tsquery('supernovae stars'); - 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。以字节为单位的签名长度由可选整数参数 siglen 的值决定。 默认签名长度(未指定 siglen 时)为 124 字节,最大签名长度为 2024 字节。该签名通过哈希每一个词到一个 n 位串中的一个单一位来产生,通过将所有这些位 OR 在一起产生一个 n 位的文档签名。当两个词哈希到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。更长的签名导致更精确的搜索(扫描索引的一小部分和更少的堆页面),但代价是更大的索引。 + 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。以字节为单位的签名长度由可选整数参数 siglen 的值决定。 默认签名长度(未指定 siglen 时)为 124 字节,最大签名长度为 2024 字节。该签名通过将每个词 hash 到一个 n 位串中的一位,再将所有这些位进行 OR 运算来生成,结果是一个 n 位的文档签名。当两个词 hash 到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。更长的签名导致更精确的搜索(扫描更小比例的索引和更少的堆页面),但代价是更大的索引。 - GiST 可以构建为覆盖索引,例如使用 INCLUDE 子句。被包含的列可以具有没有任何 GiST 操作符类的数据类型。被包含的属性会以未压缩形式存储。 + GiST 可以构建为覆盖索引,即使用 INCLUDE 子句。被包含的列可以具有没有任何 GiST 操作符类的数据类型。被包含的属性会以未压缩形式存储。 - 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的可用性。假匹配的可能性取决于几个因素,特别是唯一词的数量,因此推荐使用词典来缩减这个数量。 + 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的实用性。假匹配的可能性取决于几个因素,特别是不同词的数量,因此推荐使用词典来缩减这个数量。 - 注意GIN索引的构件时间常常可以通过增加来改进,而GiST索引的构建时间则与该参数无关。 + 注意GIN索引的构建时间常常可以通过增加来改进,而GiST索引的构建时间则对该参数不敏感。 @@ -2861,7 +2855,7 @@ SELECT plainto_tsquery('supernovae stars'); <application>psql</application> 支持 - 关于文本搜索配置对象的信息可以在psql中使用一组命令获得: + 关于文本检索配置对象的信息可以在psql中使用一组命令获得: \dF{d,p,t}+ PATTERN @@ -2869,7 +2863,7 @@ SELECT plainto_tsquery('supernovae stars'); - 可选参数 PATTERN 可以是文本搜索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: + 可选参数 PATTERN 可以是文本检索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: => \dF *fulltext* @@ -2896,7 +2890,7 @@ SELECT plainto_tsquery('supernovae stars'); \dF+ PATTERN - 列出文本搜索配置(加上 + 可显示更多细节)。 + 列出文本检索配置(加上 + 可显示更多细节)。 => \dF russian List of text search configurations @@ -2937,7 +2931,7 @@ Parser: "pg_catalog.default" \dFd+ PATTERN - 列出文本搜索词典(加上 + 可显示更多细节)。 + 列出文本检索词典(加上 + 可显示更多细节)。 => \dFd List of text search dictionaries @@ -2981,7 +2975,7 @@ Parser: "pg_catalog.default" \dFp+ PATTERN - 列出文本搜索解析器(加上 + 可显示更多细节)。 + 列出文本检索解析器(加上 + 可显示更多细节)。 => \dFp List of text search parsers @@ -3034,7 +3028,7 @@ Parser: "pg_catalog.default" \dFt+ PATTERN - 列出文本搜索模板(加上 + 可显示更多细节)。 + 列出文本检索模板(加上 + 可显示更多细节)。 => \dFt List of text search templates @@ -3057,7 +3051,7 @@ Parser: "pg_catalog.default" 限制 - PostgreSQL 当前文本搜索特性的限制如下: + PostgreSQL 当前文本检索特性的限制如下: 每个词位的长度必须小于 2 千字节 @@ -3085,12 +3079,12 @@ Parser: "pg_catalog.default" - 为了对比,PostgreSQL 8.1 的文档包含 10,441 个唯一词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 + 为了对比,PostgreSQL 8.1 的文档包含 10,441 个不同词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 - 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个唯一词。 + 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个不同词。 diff --git a/zh/17/unaccent.sgml b/zh/17/unaccent.sgml index be5b7974..187386a3 100644 --- a/zh/17/unaccent.sgml +++ b/zh/17/unaccent.sgml @@ -1,18 +1,18 @@ - unaccent — 去除变音符号的文本搜索词典 + unaccent — 去除变音符号的文本检索词典 unaccent - unaccent是一个文本搜索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤字典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文搜索能够以不区分重音的方式处理文本。 + unaccent是一个文本检索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤词典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文检索能够以不区分重音的方式处理文本。 - unaccent当前的实现还不能作为thesaurus词典的正规化字典使用。 + unaccent当前的实现还不能作为thesaurus词典的正规化词典使用。 @@ -79,7 +79,7 @@ - 与其他PostgreSQL文本搜索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含不可转换字符的行都会被静默忽略,因此规则文件中可以包含不适用于当前编码的规则。 + 与其他PostgreSQL文本检索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含不可转换字符的行都会被静默忽略,因此规则文件中可以包含不适用于当前编码的规则。 @@ -93,7 +93,7 @@ 用法 - 安装unaccent扩展会创建一个文本搜索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 + 安装unaccent扩展会创建一个文本检索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 mydb=# ALTER TEXT SEARCH DICTIONARY unaccent (RULES='my_rules'); @@ -114,7 +114,7 @@ mydb=# select ts_lexize('unaccent','Hôtel'); - 下面的示例展示了如何将unaccent词典插入到文本搜索配置中: + 下面的示例展示了如何将unaccent词典插入到文本检索配置中: mydb=# CREATE TEXT SEARCH CONFIGURATION fr ( COPY = french ); mydb=# ALTER TEXT SEARCH CONFIGURATION fr @@ -145,7 +145,7 @@ mydb=# select ts_headline('fr','Hôtel de la Mer',to_tsquery('fr','Hotels') 函数 - unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本搜索环境之外使用。 + unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本检索环境之外使用。 @@ -157,7 +157,7 @@ unaccent(dictionary - 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本搜索词典。 + 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本检索词典。 diff --git a/zh/18/array.sgml b/zh/18/array.sgml index 10cc5e41..ead7c881 100644 --- a/zh/18/array.sgml +++ b/zh/18/array.sgml @@ -4,7 +4,7 @@ 数组 - array + 数组 @@ -15,8 +15,8 @@ 数组类型的声明 - array - declaration + 数组 + 声明 @@ -64,8 +64,8 @@ CREATE TABLE tictactoe ( 数组值输入 - array - constant + 数组 + 常量 @@ -86,7 +86,7 @@ CREATE TABLE tictactoe ( (这类数组常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。必要时可能需要显式指定类型。) + linkend="sql-syntax-constants-generic"/>中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。可能需要显式指定类型。) @@ -119,7 +119,7 @@ SELECT * FROM sal_emp; - 多维数组在每个维度上的范围必须匹配。不匹配会导致错误,例如: + 多维数组的各个子数组在每个维度上的长度必须匹配。不匹配会导致错误,例如: INSERT INTO sal_emp @@ -152,8 +152,8 @@ INSERT INTO sal_emp 访问数组 - array - accessing + 数组 + 访问 @@ -186,9 +186,9 @@ SELECT pay_by_quarter[3] FROM sal_emp; - 我们还可以访问数组或子数组的任意矩形切片。数组切片通过在一个或多个数组维度上写成 + 我们还可以访问数组的任意矩形切片,即子数组。数组切片通过在一个或多个数组维度上写成 lower-bound:upper-bound - 的形式来表示。例如,下面这个查询取回 Bill 在一周前两天日程安排中的第一个项目: + 的形式来表示。例如,下面这个查询取回 Bill 在一周中前两天里每天的首项日程: SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill'; @@ -235,11 +235,11 @@ SELECT schedule[:][1:1] FROM sal_emp WHERE name = 'Bill'; - 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回空值。此外,如果下标超出数组边界,也会返回空值(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是空值而不是错误。 + 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回 NULL。此外,如果下标超出数组边界,也会返回 NULL(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是 NULL 而不是错误。 - 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回空值。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是空值。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回空值。 + 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回 NULL。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是 NULL。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回 NULL。 @@ -293,8 +293,8 @@ SELECT cardinality(schedule) FROM sal_emp WHERE name = 'Carol'; 修改数组 - array - modifying + 数组 + 修改 @@ -331,7 +331,7 @@ UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}' - 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用空值填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含空值。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 + 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用 NULL 填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含 NULL。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 @@ -443,21 +443,21 @@ SELECT array_cat(ARRAY[5,6], ARRAY[[1,2],[3,4]]); 在简单情况下,优先使用上面讨论的连接操作符,而不是直接调用这些函数。不过,由于连接操作符被重载以同时服务于这三种情形,所以在某些场景下使用这些函数之一有助于避免歧义。例如,考虑: -SELECT ARRAY[1, 2] || '{3, 4}'; -- the untyped literal is taken as an array +SELECT ARRAY[1, 2] || '{3, 4}'; -- 未指定类型的字面量被当作数组 ?column? ----------- {1,2,3,4} -SELECT ARRAY[1, 2] || '7'; -- so is this one +SELECT ARRAY[1, 2] || '7'; -- 这个字面量也一样 ERROR: malformed array literal: "7" -SELECT ARRAY[1, 2] || NULL; -- so is an undecorated NULL +SELECT ARRAY[1, 2] || NULL; -- 未加类型修饰的 NULL 也一样 ?column? ---------- {1,2} (1 row) -SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant +SELECT array_append(ARRAY[1, 2], NULL); -- 这可能才是原本想表达的意思 array_append -------------- {1,2,NULL} @@ -471,8 +471,8 @@ SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant 在数组中搜索 - array - searching + 数组 + 搜索 @@ -552,7 +552,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); 数组输入和输出语法 - array + 数组 I/O @@ -565,7 +565,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); - 默认情况下,数组各维度的下界索引值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: + 默认情况下,数组各维度的下界下标值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2 FROM (SELECT '[1:1][-2:-1][3:5]={{{1,2,3},{4,5,6}}}'::int[] AS f1) AS ss; diff --git a/zh/18/catalogs.sgml b/zh/18/catalogs.sgml index 6ae2f512..34200ade 100644 --- a/zh/18/catalogs.sgml +++ b/zh/18/catalogs.sgml @@ -320,27 +320,27 @@ pg_ts_config - 文本搜索配置 + 文本检索配置 pg_ts_config_map - 文本搜索配置的词元映射 + 文本检索配置的词元映射 pg_ts_dict - 文本搜索字典 + 文本检索词典 pg_ts_parser - 文本搜索分析器 + 文本检索解析器 pg_ts_template - 文本搜索模板 + 文本检索模板 @@ -7740,12 +7740,12 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config目录包含表示文本搜索配置的条目。一个配置指定某个特定的文本搜索分析器,以及针对该分析器每种输出词元类型所定义的字典列表。分析器由pg_ts_config项表示,而词元到字典的映射则由pg_ts_config系统目录包含表示文本检索配置的条目。一个配置指定某个特定的文本检索解析器,以及针对该解析器每种输出词元类型所定义的词典列表。解析器记录在pg_ts_config条目中,而词元到词典的映射则由pg_ts_config_map中的辅助项定义。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。 @@ -7777,7 +7777,7 @@ SCRAM-SHA-256$<iteration count>:&l cfgname name - 文本搜索配置名 + 文本检索配置名 @@ -7807,7 +7807,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_ts_parser.oid - 该配置的文本搜索分析器的OID + 该配置的文本检索解析器的 OID @@ -7824,11 +7824,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config_map目录包含的项展示了对于每一个文本搜索配置的每一种输出词元类型,有哪些文本搜索字典可供查询以及以何种顺序。 + pg_ts_config_map 系统目录中的条目说明了,对于每个文本检索配置所用解析器的每种输出词元类型,应当查询哪些文本检索词典以及查询的顺序。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7861,7 +7861,7 @@ SCRAM-SHA-256$<iteration count>:&l maptokentype int4 - 一种由配置的分析器送出的词元类型 + 一种由配置的解析器送出的词元类型 @@ -7880,7 +7880,7 @@ SCRAM-SHA-256$<iteration count>:&l (参考 pg_ts_dict.oid - 要查询的文本搜索字典的OID + 要查询的文本检索词典的 OID @@ -7897,11 +7897,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_dict目录包含定义文本搜索字典的项。一个字典依赖于一个文本搜索模板,它指定了所有需要的函数实现,字典本身则为模板支持的用户可设置参数提供值。这种分工允许无权限的用户创建字典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 + pg_ts_dict系统目录包含定义文本检索词典的项。一个词典依赖于一个文本检索模板,它指定了所有需要的实现函数,词典本身则为模板支持的用户可设置参数提供值。这种分工允许普通用户创建词典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -7933,7 +7933,7 @@ SCRAM-SHA-256$<iteration count>:&l dictname name - 文本搜索字典名 + 文本检索词典名 @@ -7943,7 +7943,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_namespace.oid - 包含该字典的名字空间OID + 包含该词典的名字空间的 OID @@ -7953,7 +7953,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_authid.oid - 字典的拥有者 + 词典的拥有者 @@ -7963,7 +7963,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_ts_template.oid - 该字典的文本搜索模板的OID + 该词典的文本检索模板的 OID @@ -7989,11 +7989,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_parser目录包含定义文本搜索分析器的项。一个分析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个分析器必须用C语言级别的函数实现,创建新分析器的工作只限于数据库的超级用户。 + pg_ts_parser系统目录包含定义文本检索解析器的项。一个解析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个解析器必须用 C 语言级别的函数实现,创建新解析器的工作只限于数据库的超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -8025,7 +8025,7 @@ SCRAM-SHA-256$<iteration count>:&l prsname name - 文本搜索分析器的名字 + 文本检索解析器的名字 @@ -8035,7 +8035,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_namespace.oid - 包含此分析器的名字空间的OID + 包含此解析器的名字空间的 OID @@ -8045,7 +8045,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器启动函数的OID + 解析器启动函数的 OID @@ -8055,7 +8055,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的下一词元函数的OID + 解析器的下一词元函数的 OID @@ -8065,7 +8065,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的关闭函数的OID + 解析器的关闭函数的 OID @@ -8075,7 +8075,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器标题函数的 OID(如果没有则为零) + 解析器的 headline 函数的 OID(如果没有则为零) @@ -8085,7 +8085,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的词汇类型函数的OID + 解析器的 lextype 函数的 OID @@ -8102,11 +8102,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_template目录包含定义文本搜索模板的项。一个模板是一类文本搜索字典的实现骨架。由于一个模板必须用C语言级别的函数实现,新模板的创建只限于数据库超级用户。 + pg_ts_template系统目录包含定义文本检索模板的项。一个模板是一类文本检索词典的实现骨架。由于一个模板必须用 C 语言级别的函数实现,新模板的创建只限于数据库超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -8138,7 +8138,7 @@ SCRAM-SHA-256$<iteration count>:&l tmplname name - 文本搜索模板的名字 + 文本检索模板的名字 diff --git a/zh/18/client-auth.sgml b/zh/18/client-auth.sgml index d103ebe1..020e6f4b 100644 --- a/zh/18/client-auth.sgml +++ b/zh/18/client-auth.sgml @@ -1780,7 +1780,7 @@ host ... radius radiusservers="server1,server2" radiussecrets="""secret one"","" scope - 一个以空格分隔的 OAuth 作用域(scope)列表,服务器需要借此既能授权客户端,又能认证用户。合适的取值由授权服务器以及所使用的 OAuth 验证模块决定(关于验证器的更多信息,见 )。此参数为必需项。 + 一个以空格分隔的 OAuth 授权范围列表,服务器需要借此既能授权客户端,又能认证用户。合适的取值由授权服务器以及所使用的 OAuth 验证模块决定(关于验证器的更多信息,见 )。此参数为必需项。 diff --git a/zh/18/config.sgml b/zh/18/config.sgml index 2ea829fd..d32bab4a 100644 --- a/zh/18/config.sgml +++ b/zh/18/config.sgml @@ -2948,7 +2948,7 @@ include_dir 'conf.d' 配置 - 恢复的 + 恢复 一般设置 @@ -3006,7 +3006,7 @@ include_dir 'conf.d' 配置 恢复 - 一个备库 + 备库 @@ -3453,7 +3453,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows - 列出安装在 所指定位置中、同时也被信任可供复制客户端用作逻辑输出插件的库。 + 列出安装在 所指定位置中、同时也受信任、可供复制客户端用作逻辑输出插件的库。 任何针对其他库的逻辑解码或 复制请求都将被拒绝。所有用户都受此限制。 默认值为 'pgoutput, test_decoding',它们是标准 @@ -4142,8 +4142,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( )。 + 设置规划器对一系列顺序磁盘页面读取中单次读取的代价估计。默认值是 1.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -4550,7 +4543,7 @@ ANY num_sync ( )。 + 设置规划器对一次非顺序磁盘页面读取的代价估计。默认值是 4.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -4563,14 +4556,13 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( 。 如果指定值时没有单位,则以块为单位,即BLCKSZ字节,通常为8kB。默认值是512千字节(512kB)。 @@ -4696,13 +4688,13 @@ ANY num_sync ( num_sync ( - 遗传查询优化 + 遗传查询优化器 - GEQO是一个使用探索式搜索来执行查询规划的算法。它可以降低负载查询的规划时间。 同时,GEQO的检索是随机的,因此它的规划可能会不可确定。 更多信息参阅Chapter 50。 - 遗传查询规划器(GEQO)是一种使用启发式搜索来进行查询规划的算法。它可以降低对于复杂查询(连接很多表的查询)的规划时间,但是代价是它产生的计划有时候要差于使用穷举搜索算法找到的计划。详见。 + 遗传查询优化器(GEQO)是一种使用启发式搜索进行查询规划的算法。它可以缩短复杂查询(连接很多关系的查询)的规划时间,代价是生成的计划有时不如常规穷举搜索算法找到的计划。更多信息见 @@ -4783,7 +4774,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( .) + 目前,约束排除仅在通常用于通过继承树实现表分区的情况下默认启用。为所有表启用它会增加额外的规划开销,这在简单查询上相当明显,而且通常不会为简单查询带来好处。如果没有通过传统继承方式进行分区的表,你可能希望完全关闭它。(注意,分区表的等效功能由另一个参数控制。) @@ -5032,13 +5020,7 @@ SELECT * FROM parent WHERE key = 2400; - 准备语句(显式准备或隐式生成的,例如 PL/pgSQL)可以使用自定义或通用计划执行。 - 使用其特定的参数值集为每个执行重新生成自定义计划,而通用计划不依赖于参数值,并且可以在执行中重复使用。 - 因此,使用通用计划可以节省计划时间,但如果理想计划严重依赖参数值,则通用计划可能效率低下。 - 这些选项之间的选择通常是自动进行的,但可以通过plan_cache_mode覆盖它。 - 允许的值为 auto (默认的),force_custom_planforce_generic_plan。 - 这个设置是在执行缓存计划时考虑,而不是在准备计划时考虑。 - 更多信息请参阅 . + 预备语句(无论是显式预备的,还是由 PL/pgSQL 等隐式生成的)可以使用自定义计划或通用计划执行。自定义计划会根据每次执行的具体参数值重新生成,而通用计划不依赖参数值,可以在多次执行之间复用。因此,使用通用计划能够节省规划时间,但如果理想计划高度依赖参数值,通用计划可能效率较低。系统通常会自动选择这两种计划,但可以通过plan_cache_mode覆盖这一选择。允许的值为auto(默认值)、force_custom_planforce_generic_plan。系统在执行缓存计划时考虑此设置,而不是在预备计划时。更多信息见 @@ -5056,7 +5038,7 @@ SELECT * FROM parent WHERE key = 2400; 设置规划器对递归查询 的工作表的平均大小的估计值,作为查询初始非递归项的估计大小的倍数。 这有助于规划器选择将工作表与查询的其他表连接的最合适方法。 - 默认值为10.0。当递归从一步到下一步的fan-out较低时,如最短路径查询中的示例,使用较小的值(如1.0)可能有所帮助。 + 默认值为10.0。当递归从一步到下一步的扇出较低时,例如最短路径查询,使用较小的值(如1.0)可能有所帮助。 图分析查询可能会从大于默认值的设置中受益。 @@ -5075,7 +5057,7 @@ SELECT * FROM parent WHERE key = 2400; - 在哪里做日志 + 日志记录到哪里 日志写到哪里 @@ -5083,7 +5065,7 @@ SELECT * FROM parent WHERE key = 2400; current_logfiles - 和日志_目的地配置参数 + 和 log_destination 配置参数 @@ -5131,13 +5113,13 @@ jsonlog log/postgresql.json 当由于轮换而创建新的日志文件时,以及重新加载log_destination时,current_logfiles会被重新创建。 当log_destination中不包含stderrcsvlogjsonlog, - 以及日志收集器被禁用时,它会被移除。 + 或者日志收集器被禁用时,它会被移除。 - 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设备LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: + 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设施LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: local0.* /var/log/postgresql @@ -5145,7 +5127,7 @@ local0.* /var/log/postgresql - 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源极其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见。 + 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源及其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见 @@ -5161,20 +5143,20 @@ local0.* /var/log/postgresql - 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 + 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息可能不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 - 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供方法来轮转日志文件。还有,在某些不使用日志收集器的平台上可能会导致丢失或者混淆日志输出,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 + 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供便捷的方法来轮转日志文件。还有,在某些平台上,不使用日志收集器可能会导致日志输出丢失或混杂,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 - 日志收集器被设计成从来不会丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 + 日志收集器被设计成从来不会丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它可能会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 @@ -5208,7 +5190,7 @@ local0.* /var/log/postgresql logging_collector被启用时,这个参数设置被创建的日志文件的文件名。 - 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何时区独立的%转义,计算将在由指定的时区中完成)。 + 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何依赖时区的%转义,计算将在由指定的时区中完成)。 被支持的%转义和开放组织的strftime说明中列举的类似。 注意系统的strftime不会被直接使用,因此平台相关(非标准)的扩展无法工作。 默认是postgresql-%Y-%m-%d_%H%M%S.log。 @@ -5246,7 +5228,7 @@ local0.* /var/log/postgresql - 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的十进制格式,该数字必须以一个0(零)开始)。 + 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的八进制格式,该数字必须以一个0(零)开始)。 @@ -5312,7 +5294,7 @@ local0.* /var/log/postgresql - 示例:要保留 24 小时的日志,每个小时一个日志文件,但是在日志文件尺寸超过 1GB 时轮转。可以这样做:将log_filename设置为server_log.%H%M、 + 示例:要保留 24 小时的日志,每个小时一个日志文件,如果日志文件尺寸超过 1GB,也会提前轮转。可以这样做:将log_filename设置为server_log.%H%M、 将log_truncate_on_rotation设置为on、 将log_rotation_age设置为60并且 将log_rotation_size设置为1000000。 @@ -5331,7 +5313,7 @@ local0.* /var/log/postgresql - 当启用了向syslog记录时,这个参数决定要使用的syslog设备。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4、 + 当启用了向syslog记录时,这个参数决定要使用的syslog设施。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4LOCAL5LOCAL6LOCAL7中选择,默认值是LOCAL0。还请参阅系统的syslog守护进程的文档。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -5386,7 +5368,7 @@ local0.* /var/log/postgresql - 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,有必要让消息保持逻辑上的整体性(也更加有用)。 + 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,让消息保持逻辑上的完整性可能是必要的,也可能更有用。 @@ -5405,7 +5387,7 @@ local0.* /var/log/postgresql - 当启用了向事件日志记录时,这个参数决定用来标识日志中PostgreSQL消息的程序名。默认值是PostgreSQL。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 当启用了向事件日志记录时,这个参数决定用来标识日志中PostgreSQL消息的程序名。默认值是PostgreSQL。这个参数只能在服务器启动时设置。 @@ -5451,9 +5433,7 @@ local0.* /var/log/postgresql - 控制在服务器日志中记录哪些导致错误条件的SQL语句。当前的SQL语句将包含在任何指定 - severity - 或更高消息的日志条目中。 + 控制在服务器日志中记录哪些导致错误条件的SQL语句。对于达到指定严重级别或更高级别的消息,其日志条目中会包含当前 SQL 语句。 有效值为DEBUG5DEBUG4DEBUG3DEBUG2DEBUG1、 @@ -5493,7 +5473,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -5531,7 +5511,7 @@ local0.* /var/log/postgresql - log_min_duration_statement的其他注释也适用于此设置。 + log_min_duration_statement的其他说明也适用于此设置。 @@ -5546,8 +5526,8 @@ local0.* /var/log/postgresql - 确定持续时间超过的语句的比例将被记录。 - 采样是随机的,例如0.5表示统计上有一半的机会任何给定的语句将被记录。 + 确定持续时间超过的语句中,将被记录的语句比例。 + 采样是随机的,例如0.5表示任意给定语句被记录的统计概率为二分之一。 默认值为1.0,表示记录所有采样的语句。 将此设置为零将禁用采样语句持续时间记录,与将log_min_duration_sample设置为-1相同。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -5565,7 +5545,7 @@ local0.* /var/log/postgresql - 设置所有语句都被记录的事务的比例,除了其他原因记录的语句。它适用于每个新事务,无论其语句的持续时间如何。 + 设置需要记录全部语句的事务比例,这些记录是在因其他原因记录的语句之外额外进行的。它适用于每个新事务,无论其语句的持续时间如何。 采样是随机的,例如0.1表示任何给定事务被记录的统计概率是十分之一。 log_transaction_sample_rate可以帮助构建事务样本。 默认值为0,表示不记录任何额外事务的语句。将其设置为1会记录所有事务的所有语句。 @@ -5590,8 +5570,7 @@ local0.* /var/log/postgresql - 设置启动进程在长时间运行的操作仍在进行时记录消息的时间间隔, - 以及该操作进一步进展消息之间的间隔时间。默认值为10秒。 + 设置启动进程在长时间运行的操作开始后,等待多久才记录第一条进度消息,以及此后该操作的进度消息之间的时间间隔。默认值为10秒。 设置为0会禁用该功能。如果未指定单位, 则将其视为毫秒。此设置分别应用于每个操作。 此参数只能在postgresql.conf文件或服务器命令行中设置。 @@ -5633,7 +5612,7 @@ local0.* /var/log/postgresql DEBUG1 .. DEBUG5 - 为开发者提供连续的更详细的信息。 + 为开发者提供逐级更加详细的信息。 DEBUG INFORMATION @@ -5693,7 +5672,7 @@ local0.* /var/log/postgresql - 记录什么到日志 + 记录哪些内容 @@ -5714,7 +5693,7 @@ local0.* /var/log/postgresql - application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。它也会被通过包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为C 风格的十六进制转义序列。 + application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。也可以通过将其包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为C 风格的十六进制转义序列。 @@ -5741,7 +5720,6 @@ local0.* /var/log/postgresql - 这个参数启用发出各种调试输出。当设置时,会打印生成的解析树, 查询重写输出,或执行的每个查询的执行计划。这些信息是在LOG 信息级别发出,因此默认的,它们会出现在服务器日志中,但不会发送给客户端。 可以通过 client_min_messages和/或log_min_messages 来设置。这些参数缺省是off。 这些参数将会让多种调试输出被发出。当被设置时,它们为每一个被执行的查询打印结果分析树、查询重写器输出或执行计划。这些消息在LOG消息级别上被发出,因此默认情况下它们将出现在服务器日志中但不会被发送到客户端。你可以通过调整和/或来改变这种情况。这些参数默认是关闭的。 @@ -5775,10 +5753,10 @@ local0.* /var/log/postgresql - 每次由自动清理执行的操作都会被记录,如果运行时间至少达到指定时间。将此设置为零会记录所有自动清理操作。 + 当自动清理执行的操作运行时间至少达到指定时间时,就会记录该操作。将此设置为零会记录所有自动清理操作。 -1会禁用记录自动清理操作。如果未指定单位,则将其视为毫秒。 例如,如果将其设置为250ms,则所有运行时间为250ms或更长的自动清理和分析都将被记录。 - 此外,当此参数设置为任何值而不是-1时,如果由于冲突的锁定或同时删除的关系而跳过自动清理操作,则会记录消息。 + 此外,当此参数设置为任何非-1值时,如果由于冲突锁或关系被并发删除而跳过自动清理操作,则会记录消息。 默认值为10min。启用此参数可帮助跟踪自动清理活动。 此参数只能在postgresql.conf文件或服务器命令行中设置;但可以通过更改表存储参数来覆盖对单个表的设置。 @@ -5912,7 +5890,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -5935,7 +5913,7 @@ local0.* /var/log/postgresql 控制在服务器日志中记录的每条消息的详细程度。有效值为TERSE, - DEFAULTVERBOSE,每个值都会添加更多字段到显示的消息中。 + DEFAULTVERBOSE,它们依次在显示的消息中增加更多字段。 TERSE不包括DETAILHINTQUERYCONTEXT错误信息的记录。 VERBOSE输出包括SQLSTATE错误代码 @@ -5955,7 +5933,7 @@ local0.* /var/log/postgresql - 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致很微小的性能损失。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致不可忽视的性能开销。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -5974,7 +5952,7 @@ local0.* /var/log/postgresql %字符开始转义序列,它将被按照下文描述的替换成状态信息。 未识别的转义被忽略。其他字符被直接复制到日志行。某些转义只被会话进程识别并且被主服务器进程等后台进程当作空。 通过指定一个在%之后和该选项之前的数字可以让状态信息左对齐或右对齐。 - 负值将导致在右边用空格填充状态信息已达到最小宽度,而正值则在左边填充。填充对于日志文件的人类可读性大有帮助。 + 负值将导致在右边用空格填充状态信息以达到最小宽度,而正值则在左边填充。填充对于日志文件的人类可读性大有帮助。 @@ -6042,8 +6020,8 @@ local0.* /var/log/postgresql %P - 并行组leader的进程ID,如果该进程是一个并行查询worker - no + 如果该进程是并行查询工作进程,则为并行组领导者的进程 ID + @@ -6060,8 +6038,8 @@ local0.* /var/log/postgresql %n - 带毫秒的时间戳(作为 Unix 时代) - no + 带毫秒精度的 Unix 时间戳 + @@ -6116,7 +6094,7 @@ local0.* /var/log/postgresql %Q 当前查询的查询标识符。 查询标识符默认是不计算的,所以这个部分将是零,除非 参数被激活或者配置了计算查询标识符的第三方模块 - yes + @@ -6135,7 +6113,7 @@ local0.* /var/log/postgresql %c转义打印一个准唯一的会话标识符,它由两个 4 字节的十六进制数(不带先导零)组成,以点号分隔。 - 这些数字是进程启动时间和进程 ID,因此%c也可以被用作保存打印这些项的方式的空间。 + 这些数字是进程启动时间和进程 ID,因此%c也可以用来节省空间地输出这两项信息。 例如,要从pg_stat_activity生成会话标识符,使用这个查询: SELECT to_hex(trunc(EXTRACT(EPOCH FROM backend_start))::integer) || '.' || @@ -6173,7 +6151,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 对于输出的行,%Q 总是报告零标识符, - 因为log_statement在标识符能被计算之前生成输出,包括无效标识符不能计算的无效语句。 + 因为log_statement在标识符能被计算之前生成输出,也包括无法计算标识符的无效语句。 @@ -6221,8 +6199,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 控制启动进程等待时间超过针对恢复冲突的deadlock_timeout的时候是否产生日志消息。 - 这对于决定恢复冲突是否会阻止恢复应用WAL有所帮助。 + 控制启动进程因恢复冲突而等待超过deadlock_timeout时是否产生日志消息。这有助于判断恢复冲突是否阻碍了恢复过程应用 WAL。 @@ -6250,8 +6227,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 此设置仅影响作为结果打印的日志消息,, 和相关的设置。 - 该设置的非零值会增加一些开销,特别是当参数以二进制形式发送时,因为需要转换为文本。 + 此设置仅影响由及相关设置产生的日志消息。此设置为非零值时会增加一些开销,特别是以二进制形式发送参数时,因为需要将参数转换为文本。 @@ -6295,7 +6271,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' UPDATEDELETETRUNCATE, 和COPY FROM。 如果PREPAREEXECUTE和 - EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个执行消息时会产生日志并且会包括绑定参数的值(任何内嵌的单引号会被双写)。 + EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个 Execute 消息时会产生日志并且会包括 Bind 参数的值(任何内嵌的单引号会被双写)。 @@ -6306,7 +6282,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在执行阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 + 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在 Execute 阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 @@ -6326,7 +6302,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 每个复制命令都会被记录在服务器日志中。 + 在服务器日志中记录每个复制命令,以及walsender进程获取和释放复制槽的操作。 有关复制命令的更多信息,请参见。 默认值为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -6345,8 +6321,8 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 控制临时文件名和大小的日志记录。 - 临时文件可以用于排序、哈希和临时查询结果。 - 如果通过此设置启用,每当删除临时文件时都会发出日志记录。 + 临时文件可以用于排序、hash 和临时查询结果。 + 如果通过此设置启用,每当删除临时文件时都会发出日志记录,其中文件大小以字节为单位。 值为零时记录所有临时文件信息,而正值仅记录大小大于或等于指定数据量的文件。 如果未指定单位,则将其视为千字节。 默认设置为-1,禁用此类日志记录。 @@ -6399,7 +6375,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 错误上下文、 导致错误的用户查询(如果有且被log_min_error_statement启用)、 错误位置所在的字符计数、 - 在 PostgreSQL 源代码中错误的位置(如果log_error_verbosity被设置为verbose)以及应用名,后端类型,并行组leader的进程ID和查询ID。 + 在 PostgreSQL 源代码中错误的位置(如果log_error_verbosity被设置为verbose)、应用名、后端类型、并行组领导者的进程 ID 和查询 ID。 下面是一个定义用来存储 CSV 格式日志输出的样表: @@ -6451,7 +6427,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 设置log_filenamelog_rotation_age为你的日志文件提供一种一致的、可预测的命名空间。这让你预测文件名会是怎样以及知道什么时候一个个体日志文件完成并且因此准备好被导入。 + 设置log_filenamelog_rotation_age,为日志文件提供一致且可预测的命名方案。这样就能预测文件名,并知道单个日志文件何时已完成写入、可以导入。 @@ -6480,12 +6456,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 使用JSON格式的日志输出 - 包括jsonloglog_destination列表中提供了一种方便的方式将日志文件导入到许多不同的程序中。此选项以JSON格式发出日志行。 + 将jsonlog加入log_destination列表,可以方便地将日志文件导入多种不同的程序。此选项以JSON格式输出日志行。 - 字段值为null的字符串字段将被排除在输出之外。 - 未来可能会添加其他字段。处理jsonlog输出的用户应忽略未知字段。 + 值为空值的字符串字段不会输出。将来可能会添加其他字段。处理jsonlog输出的用户应用程序应忽略未知字段。 @@ -6630,13 +6605,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; statement string - 客户提供的查询字符串 + 客户端提供的查询字符串 cursor_position number - 查询字符串中的光标索引 + 查询字符串中的游标索引 @@ -6690,7 +6665,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 进程标题 - 这些设置控制服务器进程的进程标题如何被修改。进程标题通常可以用ps或者 Windows 上的进程浏览器等程序来查看。详见。 + 这些设置控制服务器进程的进程标题如何修改。通常可以通过ps等程序查看进程标题,在 Windows 上则可以使用Process Explorer。详情参见 @@ -6724,7 +6699,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 每次服务器接收到新的SQL命令时,都可以更新进程标题。 + 启用后,每次服务器接收到新的 SQL 命令时都会更新进程标题。 在大多数平台上,默认情况下此设置为on,但在Windows上默认为off, 因为该平台更新进程标题的开销较大。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -6762,7 +6737,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对每个会话当前执行命令的信息收集,包括其标识符和命令开始执行的时间。 - 此参数默认为开启状态。请注意,即使启用了此信息,只有超级用户、具有 + 此参数默认为开启状态。请注意,即使启用了此参数,只有超级用户、具有 pg_read_all_stats角色权限的角色和拥有被报告会话的用户 (包括属于他们具有权限的角色的会话)才能看到此信息,因此不应构成安全风险。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -6780,7 +6755,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 为每个活动会话指定存储当前执行命令的文本所保留的内存量,它们被用于pg_stat_activity.query域。 + 为每个活动会话指定存储当前执行命令的文本所预留的内存量,它们被用于pg_stat_activity.query字段。 如果指定值时没有单位,则以字节为单位。默认值是 1024字节。这个参数只能在服务器启动时被设置。 @@ -6797,7 +6772,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对数据库活动的统计信息收集。 - 此参数默认为开启,因为自动清理守护进程需要收集的信息。 + 此参数默认为开启,因为自动清理守护进程需要这些收集到的信息。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -6873,7 +6848,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用函数调用次数和时间的跟踪。指定pl以仅跟踪过程语言函数, + 启用函数调用次数和耗时的跟踪。指定pl以仅跟踪过程语言函数, all以同时跟踪SQL和C语言函数。默认值为none, 即禁用函数统计跟踪。只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -6908,7 +6883,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - none适用于监控系统。如果值只被访问一次,它是最有效的。 + none最适合监控系统。如果值只被访问一次,它是最有效的。 cache确保重复访问产生相同的值,这对涉及自连接的查询很重要。 snapshot在交互式检查统计信息时可能很有用,但开销较高, 特别是存在许多数据库对象时。 @@ -6935,21 +6910,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用查询标识符的内核计算。 - 查询标识符可以在 pg_stat_activity - 视图中显示,使用 EXPLAIN,或者如果通过 - 参数进行配置,则可以在日志中发出。 - 扩展还需要计算查询标识符。 - 请注意,如果内核查询标识符计算方法不可接受,也可以使用外部模块。 - 在这种情况下,必须始终禁用内核计算。 - 有效值为 off(始终禁用), - on(始终启用),auto, - 允许诸如 这样的模块 - 自动启用它,并且 regress 具有与 - auto 相同的效果,只是查询标识符不会显示在 - EXPLAIN 输出中,以便促进自动回归测试。 - 默认值为 auto。 + 启用内置的查询标识符计算功能。查询标识符可以显示在pg_stat_activity视图或EXPLAIN的输出中,也可以通过参数配置后写入日志。扩展也要求计算查询标识符。注意,如果内置的查询标识符计算方法不符合要求,可以改用外部模块。在这种情况下,必须始终禁用内置计算功能。有效值为off(始终禁用)、on(始终启用)、auto(允许等模块自动启用此功能),以及regress。后者与auto效果相同,但不会在EXPLAIN输出中显示查询标识符,以便进行自动回归测试。默认值为auto @@ -6989,7 +6950,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 对于每个查询,将各自模块的性能统计输出到服务器日志中。这是一个简单的性能分析工具,类似于Unix getrusage()操作系统功能。 - log_statement_stats报告总语句统计,而其他选项报告每个模块的统计信息。 + log_statement_stats报告整个语句的统计信息,而其他选项报告每个模块的统计信息。 log_statement_stats不能与任何单独模块选项一起启用。所有这些选项默认情况下都是禁用的。 只有超级用户和具有适当SET权限的用户才能更改这些设置。 @@ -7576,7 +7537,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; DEBUG1LOGNOTICEWARNINGERROR。 每个级别都包括其后的所有级别。级别越靠后,被发送的消息越少。默认值是NOTICE。 - 注意LOG在这里有与中不同的排名。 + 注意LOG在这里的排序与中的不同。 @@ -7596,15 +7557,15 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,用于进行搜索该对象的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 + 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,搜索该对象时的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 - search_path的值必需是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被安静地忽略。 + search_path的值必须是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被静默忽略。 - 如果列表项之一是特殊名$user,则具有SESSION_USER返回的名字的模式将取代它(如果有这样一个模式并且该用户有该模式的USAGE权限;如果没有,$user会被忽略)。 + 如果列表项之一是特殊名$user,则具有CURRENT_USER返回的名字的模式将取代它(如果有这样一个模式并且该用户有该模式的USAGE权限;如果没有,$user会被忽略)。 @@ -7629,11 +7590,12 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个参数的缺省值是"$user", public。这种设置支持一个数据库(其中没有用户拥有私有模式,并且所有人共享使用public)、每个用户私有模式及其组合的共享使用。其它效果可以通过全局或者针对每个用户修改默认搜索路径设置获得。 + 这个参数的默认值是"$user", public。这种设置支持共享使用数据库(用户没有私有模式,所有人共享使用public)、每个用户拥有私有模式,以及二者的组合。 + 还可以通过全局或针对每个用户修改默认搜索路径设置来获得其他效果。 - 更多有关方案处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 + 更多有关模式处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 @@ -7653,7 +7615,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,只要有至少一条策略被应用则查询就会失败。默认为on。受限的行可见性会导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS)属性的角色没有效果。 + 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,原本会应用至少一条策略的查询就会失败。默认为on。受限的行可见性可能导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS属性的角色)没有效果。 @@ -7672,8 +7634,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个参数指定了在创建表或物化视图时使用的默认表访问方法,如果CREATE命令没有明确指定访问方法, - 或者当使用SELECT ... INTO时,不允许指定表访问方法。默认值是heap。 + 创建表或物化视图时,如果CREATE命令没有显式指定访问方法,或者使用了不允许指定表访问方法的SELECT ... INTO,则使用此参数指定的默认表访问方法。默认值为heap @@ -7693,7 +7654,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建企图将失败。 + 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建尝试将失败。 @@ -7701,7 +7662,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当创建数据库时也会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 + 创建数据库时也不会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 @@ -7750,11 +7711,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被放置在里表中的连续表空间中。如果列表被选中元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 + 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被依次放置在列表中的连续表空间中。如果列表中被选中的元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 - 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,类似于为用户指定一个不具有CREATE权限的表空间。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特殊地,使用一个在postgresql.conf中设置的值时,这条规则起效。 + 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,指定一个用户不具有CREATE权限的表空间也同样是错误。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特别是,使用一个在postgresql.conf中设置的值时,这条规则起效。 @@ -7779,7 +7740,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 这个参数通常为打开。 当设置为off时,它禁用期间对例程体字符串的验证。 - 禁用验证避免了验证处理的副作用,特别避免了如向前引用导致的伪肯定。 + 禁用验证避免了验证处理的副作用,特别是避免前向引用等问题导致的误报。 在代表其他用户载入函数之前设置这个参数为offpg_dump会自动这样做。 @@ -7822,7 +7783,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态 。默认是off(读/写)。 + 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态。默认是off(读/写)。 @@ -7845,11 +7806,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当运行在可串行化隔离级别时,一个可延迟只读 SQL 事务可以在它被允许继续之前延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的负荷;因此串行化代码将没有任何理由因为并发更新而强制它中断,使得这个选项适合于长时间运行的只读事务。 + 当运行在serializable隔离级别时,一个可延迟只读 SQL 事务可能在获准继续之前被延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的开销;因此串行化代码将没有任何理由因为并发更新而强制它中止,使得这个选项适合于长时间运行的只读事务。 - 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些操作在低于可串行化隔离级别上的事务无效。默认值是off。 + 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些运行在低于serializable隔离级别上的事务无效。默认值是off @@ -7893,7 +7854,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的只读状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -7913,7 +7874,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的可延迟性状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -7937,7 +7898,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 这个设置的预期用途是由逻辑复制系统在应用所复制的更改时将它设置为replica。 - 其效果将是触发器和规则(没有对其默认配置做修改)在复制机上将不会被触发。 + 其效果将是触发器和规则(没有对其默认配置做修改)在副本上将不会被触发。 更多信息请参考ALTER TABLE的子句ENABLE TRIGGER以及ENABLE RULE @@ -7967,9 +7928,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 超时从命令到达服务器的时间开始计算,一直到它被服务器完成为止。 - 如果单个简单查询消息中出现多个 SQL 语句,超时将分别应用于每个语句。(PostgreSQL 13 之前的版本通常将超时应用于整个查询字符串。 - 在扩展查询协议中,当任何与查询相关的消息(解析、绑定、执行、描述)到达时,超时就开始运行,并且可以通过执行完成或同步消息来取消超时。 + 超时从命令到达服务器时开始计算,直到服务器完成该命令为止。 + 如果单个简单查询消息中出现多个 SQL 语句,超时将分别应用于每个语句。 + (PostgreSQL 13 之前的版本通常将超时应用于整个查询字符串。) + 在扩展查询协议中,当任何与查询相关的消息(Parse、Bind、Execute、Describe)到达时开始计时, + 并在处理完 Execute 或 Sync 消息时取消计时。 @@ -8013,13 +7976,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 如果任何语句在试图获取表、索引、行或其他数据库对象上的锁时等到超过指定的时间量,该语句将被中止。 + 如果任何语句在试图获取表、索引、行或其他数据库对象上的锁时等待超过指定的时间量,该语句将被中止。 该时间限制独立地应用于每一次锁获取尝试。该限制会应用到显式锁定请求(如LOCK TABLE或不带NOWAITSELECT FOR UPDATE)和隐式获得的锁。 如果指定值时没有单位,则以毫秒为单位。一个零值(默认)将禁用超时。 - 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为事务超时将总是第一个被触发。 + 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为语句超时将总是第一个被触发。 如果log_min_error_statement 被设置为ERROR 或更低,超时的语句将被记录。 @@ -8039,15 +8002,14 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 终止任何已经闲置(这是指,等待客户端查询)超过这个参数所指定时间量的打开事务的会话。 - 如果这个值指定时没有单位,它被设为毫秒。 - 零值(默认)禁用超时。 + 终止在打开的事务中空闲(即等待客户端查询)超过指定时长的任何会话。 + 如果指定值时不带单位,则以毫秒为单位。零值(默认值)禁用此超时。 - 此选项可以用于确保空闲会话不会在不合理的时间内持有锁。 - 即使没有持有重要的锁的时候,打开的事务也会防止清理最近死亡的可能只对这个事务可见的元组;所以长时间保持空闲会导致表膨胀。 - 详见。 + 此选项可确保空闲会话不会持有锁过长时间。 + 即使没有持有重要的锁,打开的事务也会阻止清理最近死亡、且可能只对该事务可见的元组;因此长时间空闲可能造成表膨胀。 + 更多详情参见 @@ -8062,9 +8024,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 终止任何空闲的会话(也就是,等待客户端查询),但不在打开的事务中,且超过指定的时间量。 - 如果指定值时不带单位,其单位采用毫秒。 - 零值时(默认)禁用超时。 + 终止不在打开的事务中、且空闲(即等待客户端查询)超过指定时长的任何会话。 + 如果指定值时不带单位,则以毫秒为单位。零值(默认值)禁用此超时。 @@ -8072,8 +8033,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 注意不要对通过连接池软件或其他中间件建立的连接强制执行此超时,因为这样的层可能不会很好地响应意外的连接关闭。 - 只对交互会话启用此超时可能是帮助的,也许只对特定用户应用它。 + 应谨慎对通过连接池软件或其他中间件建立的连接强制执行此超时,因为这样的层可能不会很好地响应意外的连接关闭。 + 只对交互会话启用此超时可能有所帮助,也许只对特定用户应用它。 @@ -8107,7 +8068,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这里的实际选择都是根据爱好做出的,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码将比 base64 编码更大。 + 这里的实际选择主要取决于偏好,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码会比 base64 编码略大。 @@ -8128,7 +8089,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当在XML和字符串值之间进行转换时,无论设置DOCUMENT或 CONTENT都是隐式的。可参阅Section 8.13。 有效值是DOCUMENT和CONTENT。 缺省值是CONTENT。当在 XML 和字符串值之间进行转换时,设置DOCUMENTCONTENT都是隐式的。详见。有效值是DOCUMENTCONTENT。默认值是CONTENT。 + 设置在 XML 与字符串值之间进行转换时,隐含采用DOCUMENT还是CONTENT。 + 有关说明参见。有效值是DOCUMENTCONTENT。默认值是CONTENT @@ -8163,7 +8125,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; createrole_self_grant (string) - createrole_self_grant配置参数 + createrole_self_grant + 配置参数 @@ -8172,9 +8135,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 该值必须是setinherit或它们的逗号分隔列表。默认值为空字符串,这会禁用此功能。 - 此选项的目的是允许非超级用户的CREATEROLE用户自动继承或自动获得对新创建角色执行SET ROLE的能力。 + 此选项的目的是允许非超级用户的CREATEROLE用户自动继承所创建用户的权限,或自动获得对这些用户执行SET ROLE的能力。 由于CREATEROLE用户始终会隐式获得其所创建角色的ADMIN OPTION,因此该用户总是可以通过执行GRANT语句达到相同效果,但自动授予在可用性上更方便。 - 超级用户会自动继承每个角色的权限,并且始终可以切换到任何角色;此设置可让CREATEROLE用户对其创建的用户获得类似的行为。 + 超级用户会自动继承每个角色的权限,并且始终可以对任何角色执行SET ROLE;此设置可让CREATEROLE用户对其创建的用户获得类似的行为。 @@ -8182,7 +8145,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; event_triggers (boolean) - event_triggers配置参数 + event_triggers + 配置参数 @@ -8197,7 +8161,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; restrict_nonsystem_relation_kind (string) - restrict_nonsystem_relation_kind配置参数 + restrict_nonsystem_relation_kind + 配置参数 @@ -8212,7 +8177,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 区域和格式化 + 区域设置和格式化 @@ -8226,7 +8191,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域行为的设置初始化配置文件。 + 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域设置行为的设置初始化配置文件。 @@ -8241,11 +8206,14 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置间隔值的显示格式。值sql_standard将产生匹配 SQL 标准间隔文本的输出。当参数被设置为ISO时,值postgres(默认)将产生匹配PostgreSQL发行 8.4 之前的输出。当DateStyle参数被设置为非ISO输出时,值postgres_verbose会产生匹配PostgreSQL发行 8.4 之前的输出。值iso_8601会产生匹配在 ISO 8601 的 4.4.3.2 节中定义的带标志符格式的时间间隔的输出。 + 设置时间间隔值的显示格式。值sql_standard会生成符合SQL标准时间间隔字面量的输出。 + 值postgres(默认值)的输出与PostgreSQL 8.4 之前版本中设为ISO时的输出一致。 + 值postgres_verbose的输出与PostgreSQL 8.4 之前版本中DateStyle设为非ISO输出时的输出一致。 + 值iso_8601会生成符合 ISO 8601 第 4.4.3.2 节定义的时间间隔带标志符格式的输出。 - IntervalStyle参数也可以影响对有歧义的间隔输入的解释。详见。 + IntervalStyle参数也会影响对有歧义的时间间隔输入的解释。详见 @@ -8277,7 +8245,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置服务器接受的日期时间输入中使用的时区缩写集合。默认值为'Default', 这个集合在全世界大多数地方都能工作。也还有'Australia''India',以及可能为一种特定安装定义的其他集合。详见。 + 设置服务器在日期时间输入中接受的额外时区缩写集合(除当前TimeZone设置所定义的缩写之外)。默认值为'Default', 这个集合在全世界大多数地方都能工作。也还有'Australia''India',以及可能为一种特定安装定义的其他集合。详见 @@ -8303,23 +8271,23 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 如果值为1(默认值)或更高,浮点值被输出为最短-精度格式;参见。 + 如果值为 1(默认值)或更高,浮点值被输出为最短精确格式;参见。 实际生成的位数只取决于输出的值,而不取决于此参数的值。 - float8 值最多需要 17 位数字,float4值最多需要9位数字。 + float8 值最多需要 17 位数字,float4值最多需要9位数字。 这种格式既快速又精确,在正确读取时精确地保留了原始的二进制浮点值。为了历史兼容性,允许的值最大为3。 如果值为零或负,则输出四舍五入为给定的十进制精度。 - 使用的精度是根据此参数的值减小的类型((FLT_DIGDBL_DIG,视情况而定)的标准位数。 + 所用精度以该类型的标准位数(根据类型使用FLT_DIGDBL_DIG)为基础,再按此参数的值减少。 (例如,指定 -1 将导致float4 值输出四舍五入为 5 位有效数字,而float8值四舍五入为 14 位。) - 此格式较慢,不会保留二进制浮点值的所有位,但可能令人更易于阅读。 + 此格式较慢,不会保留二进制浮点值的所有位,但可能更便于阅读。 此参数的含义,以及其默认值,在 PostgreSQL 12 中发生了变化; - 参见 以便进一步讨论。 + 参见 了解进一步讨论。 @@ -8355,7 +8323,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 在一些系统上,这个区域分类并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 + 在一些系统上,这个区域设置类别并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 @@ -8374,7 +8342,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化货币量的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化货币量的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -8389,7 +8357,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化数字的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化数字的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -8404,7 +8372,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化日期和时间的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化日期和时间的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -8436,7 +8404,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 选择被那些没有显式参数指定配置的文本搜索函数变体使用的文本搜索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配区域的配置,initdb将用对应于选中的lc_ctype区域的设置初始化配置文件。 + 选择被那些没有显式参数指定配置的文本检索函数变体使用的文本检索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配该区域设置的配置,initdb将用对应于选中的lc_ctype区域设置的值初始化配置文件。 @@ -8451,7 +8419,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 为了载入附加的功能或者达到提高性能的目的,可用多个设置来预先载入共享库到服务器中。 - 例如'$libdir/mylib'设置可能会导致mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 + 例如'$libdir/mylib'设置会使mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 @@ -8460,12 +8428,12 @@ SET XML OPTION { DOCUMENT | CONTENT }; 只有特别为与PostgreSQL一起使用设计的共享库才能以这种方式载入。每一个PostgreSQL支持 - 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非PostgreSQL无法 + 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非 PostgreSQL 库无法 以这种方式被载入。你可能可以使用操作系统的工具(如LD_PRELOAD)载入它。 - 总之,请参考特定模块的文档来用推荐的方法载入它。 + 一般来说,请参考特定模块的文档来用推荐的方法载入它。 @@ -8499,9 +8467,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 这个特性的目的是允许非特权用户在特定的会话中载入正在调试的或者性能度量库, - 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客 - 户端的PGOPTIONS环境变量或者 + 这个特性的目的是允许非特权用户在特定的会话中载入用于调试或性能测量的库, + 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客户端的PGOPTIONS环境变量或者 ALTER ROLE SET来设置这个参数。 @@ -8539,7 +8506,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 不同,相对于在库被第一次使用 - 时载入它,在会话开始时载入库并没有什么性能优势。不过,当使用连接池时这样做还是有一些 + 时载入它,在会话开始时载入库并没有明显的性能优势。不过,当使用连接池时这样做还是有一些 优势。 @@ -8579,9 +8546,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 在 Windows 主机上,在服务器启动时预载入一个库并不会减少启动每个新服务器进程所需的 - 时间;每一个服务器进程将会重新载入预载入的库。不过,对于那些要在postmaster启动时 + 时间;每一个服务器进程将会重新载入所有预载入的库。不过,对于那些要在postmaster启动时 执行操作的库来说,Windows 主机上的 - shared_preload_libraries任然有用。 + shared_preload_libraries仍然有用。 @@ -8629,13 +8596,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 如果需要打开一个可以动态装载的模块并且在CREATE FUNCTIONLOAD命令中指定的文件名没有目录部分(即名字中不包含斜线),那么系统将搜索这个路径以查找所需的文件。 - - dynamic_library_path的值必须是一个冒号分隔(或者在 Windows 上以分号分隔)的绝对目录路径的列表。如果一个列表元素以特殊字符串开始,$libdir会被替换为PostgreSQL包中已编译好的库目录。这里是PostgreSQL发布提供的模块被安装的位置(使用pg_config --pkglibdir来找到这个目录的名字)。例如: - + 参数dynamic_library_path的值必须是由冒号(Windows上为分号)分隔的绝对目录路径列表。如果某个列表元素以特殊字符串$libdir开头,则会使用编译时确定的PostgreSQL软件包的库目录来替换$libdir;该目录是标准PostgreSQL发行版所提供模块的安装位置。(使用pg_config --pkglibdir可以找出此目录的名称。)例如: dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir' - - 或者在 Windows 环境中: - +或者,在 Windows 环境中: dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' @@ -8710,7 +8673,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - GIN 索引返回的集合尺寸的软上限。详见。 + GIN 索引扫描返回的集合尺寸的软上限。详见 @@ -8743,18 +8706,18 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 这是在锁上等待的时间,然后再检查是否存在死锁条件。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 + 指定在检查是否发生死锁之前等待锁的时间。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 我们乐观地假设在生产应用程序中死锁并不常见,所以在检查死锁之前只是等待一段时间。 增加此值会减少在不必要的死锁检查中浪费的时间,但会减慢实际死锁错误的报告速度。 如果未指定单位,则将其视为毫秒。 - 默认值为一秒(1s),这可能是您在实践中想要的最小值。 - 在负载较重的服务器上,您可能希望提高它。 - 理想情况下,设置应超过您的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 + 默认值为一秒(1s),这可能是你在实践中想要的最小值。 + 在负载较重的服务器上,你可能希望提高它。 + 理想情况下,设置应超过你的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 只有超级用户和具有适当SET权限的用户才能更改此设置。 - 当被设置时,这个参数还可以决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 + 当被设置时,这个参数也决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 @@ -8803,7 +8766,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 这个参数控制在谓词锁被提升为覆盖整个关系之前,该谓词锁能够在单个关系上锁住多少页面或元组。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个关系之前,可以对单个关系中的多少页面或元组加谓词锁。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -8818,7 +8781,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 这个参数控制在谓词锁被提升为覆盖整个页面之前,该谓词锁能在单一页面上锁住多少行。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个页面之前,可以对单个页面中的多少行加谓词锁。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -8846,7 +8809,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个空数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。对于那些要求旧行为的应用的向后兼容性,这个变量可以被设置为off。 + 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个值为空值的数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。为了向后兼容那些要求旧行为的应用,这个变量可以被设置为off @@ -8866,11 +8829,11 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 这个参数控制字符串文本中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\'。如果客户端代码没有做到正确转义,那么将会导致 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 + 这个参数控制字符串字面量中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\。如果客户端代码没有做到正确转义,那么就可能遭到 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 - 注意在符合标准的字符串文本中,\就表示\。这个参数只影响不符合标准的文本的处理,包括转义字符串语法(E'...')。 + 注意在符合标准的字符串字面量中,\就表示\。这个参数只影响不符合标准的字面量的处理,包括转义字符串语法(E'...')。 @@ -8886,11 +8849,11 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 打开时,如果在普通字符串文本中('...'语法)出现了 一个反斜线(\)并且standard_conforming_strings为关闭,那么就会发出一个警告。默认值是on。 + 打开时,如果在普通字符串字面量中('...'语法)出现了 一个反斜线(\)并且standard_conforming_strings为关闭,那么就会发出一个警告。默认值是on - 希望使用反斜线作为转义符的应用应该被修改来使用转义字符串语法(E'...'),因为在 SQL 标准中普通字符串的默认行为是将反斜线视作一个普通字符。这个变量可以被启用来帮助定位需要被更改的代码。 + 希望使用反斜线作为转义符的应用应该被修改来使用转义字符串语法(E'...'),因为按照 SQL 标准,普通字符串现在默认将反斜线视作一个普通字符。这个变量可以被启用来帮助定位需要被更改的代码。 @@ -8911,7 +8874,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 设置这个参数不会禁用所有与大对象相关的安全检查 — 除了那些在PostgreSQL 9.0中已经修改了的默认行为。 + 设置此变量不会禁用所有与大对象相关的安全检查 — 只禁用那些在PostgreSQL 9.0 中默认行为发生变化的检查。 @@ -8934,7 +8897,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' standard_conforming_strings (boolean) - 字符串标准符合 + 字符串符合标准 standard_conforming_strings配置参数 @@ -8942,7 +8905,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 控制普通字符串文本('...')是否按照 SQL 标准把反斜线当普通文本。从PostgreSQL 9.1 开始,默认值为on(之前的发行中默认值为off)。应用可以检查这个参数来判断字符串文本如何被处理。这个参数的存在也可以被当做转义字符串语法(E'...')被支持的标志。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 + 控制普通字符串字面量('...')是否按照 SQL 标准把反斜线当普通文本。从PostgreSQL 9.1 开始,默认值为on(之前的发行中默认值为off)。应用可以检查这个参数来判断字符串字面量如何被处理。这个参数的存在也可以被当做转义字符串语法(E'...')被支持的标志。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 @@ -8957,7 +8920,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询来,这样的扫描会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on。 + 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询,这样的扫描可能会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on @@ -8981,15 +8944,15 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr得出空值值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空(未知)。因此这个参数默认为off。 + 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr计算结果为空值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空值(未知)。因此这个参数默认为off - 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释)。它们不是非常有用并且在普通应用中也不常见,在应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及 空值的表达式的语义上感到困惑,因此这个选项默认为关闭。 + 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释),它们不是非常有用并且在普通应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及空值的表达式语义感到困惑,因此这个选项默认为关闭。 - 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不是劣质程序的一般修复。 + 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不能普遍修复错误的程序写法。 @@ -9065,7 +9028,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 当被设置为开(on),PostgreSQL将在一次后端崩溃后自动重新初始化。 + 当设置为 on(默认值)时,PostgreSQL将在一次后端崩溃后自动重新初始化。 让这个值设置为开(on)通常是将数据库可用性最大化的最佳方法。但是在某些环境中,例如PostgreSQL被集群软件调用时,禁用重启可能很有用,这样集群软件可以得到控制并且采取它认为适当的行动。 @@ -9085,7 +9048,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 如果设置为关(off),PostgreSQL在将修改的数据文件刷新到文件系统失败时,将引发PANIC级错误。 + 当设置为 off(默认值)时,PostgreSQL在将修改后的数据文件刷盘到文件系统失败时,将引发PANIC级错误。 这样会导致数据库服务器崩溃。这个参数只能在服务器启动时被设置。 @@ -9094,8 +9057,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 如果设置为开(on),PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷新操作。 - 仅在调查操作系统假如回写失败时对缓冲数据的处理方式的情况下,才将其设置为开(on)。 + 如果设置为开(on),PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷盘操作。 + 只有在调查清楚操作系统在回写失败时如何处理缓冲数据之后,才应将其设置为开(on)。 @@ -9112,14 +9075,14 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' 当设置为fsync,也就是默认值,PostgreSQL将在崩溃恢复开始之前递归地打开并同步数据目录中的所有文件。 对文件的搜索将遵循WAL目录和每个配置表空间的符号链接(而不是任何其它符号链接)。 - 这是为了确保在重现更改之前,所有WAL和数据文件都持久地存储在硬盘上。 - 这适用于在启动没有完全关闭的数据库集簇时,包括由pg_basebackup创建的副本。 + 这是为了确保在重放更改之前,所有WAL和数据文件都持久地存储在磁盘上。 + 这适用于每次启动未正常关闭的数据库集簇时,包括由pg_basebackup创建的副本。 - 在Linux上,可以用syncfs代替,请求操作系统来同步包含数据目录的整个文件系统,WAL文件和每个表空间(但不是通过符号链接可访问到的任何其他文件系统)。 + 在Linux上,可以用syncfs代替,请求操作系统来同步数据目录、WAL 文件和各个表空间所在的文件系统(但不是通过符号链接可访问到的任何其他文件系统)。 这可能比fsync设置快得多,因为它不需要逐个打开每个文件。 - 另一方面,如果一个文件系统是被其他需要修改大量文件的应用程序共享的,它可能会慢一些,因为这些文件也将写入硬盘。 + 另一方面,如果一个文件系统是被其他需要修改大量文件的应用程序共享的,它可能会慢一些,因为这些文件也将写入磁盘。 此外,在5.8之前的Linux版本中,向磁盘写入数据时遇到的I/O错误可能不会报告给PostgreSQL,相关的错误消息可能只出现在内核日志中。 @@ -9138,11 +9101,10 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' 预置选项 - 下列参数是只读的。 - 同样,它们被排除在postgresql.conf文件示例之外。 - 这些选项报告特定应用可能感兴趣的多种PostgreSQL行为,特别是管理前端相关的行为。 - 所有这些都是在PostgreSQL被编译或者它被安装时决定的。 - + 下列参数是只读的,因此未列入示例 postgresql.conf 文件。 + 这些选项报告 PostgreSQL 行为的各个方面,某些应用(特别是管理前端)可能对此感兴趣。 + 其中大多数参数在编译或安装 PostgreSQL 时确定。 + @@ -9171,7 +9133,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告对这个集簇是否启用了数据校验码。详见。 + 报告对这个集簇是否启用了数据校验和。详见 @@ -9186,9 +9148,9 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 在Unix系统上,这个参数报告启动时的数据目录(由定义)的权限。 + 在 Unix 系统上,这个参数报告服务器启动时数据目录(由定义)的权限。 (在Microsoft Windows上这个参数将总是显示0700。) - 更多信息请参考。 + 更多信息请参考initdb 选项。 @@ -9238,7 +9200,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告PostgreSQL是否在编译时打开了 64 位整数日期和时间。从PostgreSQL 10起,这个值总是on。 + 报告PostgreSQL是否在编译时启用了对 64 位整数日期和时间的支持。从PostgreSQL 10起,这个值总是on @@ -9254,9 +9216,9 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' 报告服务器当前是否处于热备模式。 - 当这个是on的时候,所有的事务强制为只读。 - 在会话中,这个只能在服务器提升为主库的时候变更。 - 更多信息参见 + 当此值为 on 时,所有事务都被强制为只读。 + 在会话中,此值只有在服务器被提升为主库时才会改变。 + 更多信息参见 @@ -9270,7 +9232,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定的。默认值是 100 个参数。 + 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定。默认值是 100 个参数。 @@ -9285,7 +9247,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64 ;因此max_identifier_length的默认值是 63,但是在使用多字节编码时可以少于 63 个字符。 + 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64;因此max_identifier_length的默认值是 63 字节,在使用多字节编码时,这可能不足 63 个字符。 @@ -9361,7 +9323,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告服务器版本数值。它是由编译服务器时的PG_VERSION值决定的。 + 报告服务器的版本号。它是由编译服务器时的PG_VERSION值决定的。 @@ -9376,7 +9338,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告服务器版本数值的整数值。它是由编译服务器时的PG_VERSION_NUM值决定的。 + 以整数形式报告服务器的版本号。它是由编译服务器时的PG_VERSION_NUM值决定的。 @@ -9391,7 +9353,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告主共享内存区域的大小,四舍五入到最接近的兆字节。 + 报告主共享内存区域的大小,向上取整到整数兆字节。 @@ -9428,8 +9390,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告此PostgreSQL服务器已构建的 SSL 库的名称(即使此实例当前未配置或使用 SSL), - 例如OpenSSL,或一个空字符串(如果没有)。 + 报告此PostgreSQL服务器在构建时使用的 SSL 库的名称(即使此实例当前未配置或使用 SSL), + 例如OpenSSL,如果没有使用 SSL 库,则报告空字符串。 @@ -9472,11 +9434,11 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' 自定义选项 - 这个特性被设计用来由附加模块向PostgreSQL添加通常不为系统知道的参数(例如过程语言)。这允许使用标准方法配置扩展模块。 + 这个特性允许附加模块(例如过程语言)向PostgreSQL添加系统通常不认识的参数。这样便能以标准方式配置扩展模块。 - 自定义选项有两部分名称:一个扩展名,然后是一个句点,再然后是正确的参数名,就像 SQL 中的合格名称。一个示例是plpgsql.variable_conflict。 + 自定义选项的名称由两部分组成:扩展名称和参数名本身,中间用句点分隔,类似于 SQL 中的限定名。例如plpgsql.variable_conflict @@ -9484,7 +9446,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' PostgreSQL将接受任何两部分参数名称的设置。 这些变量被视为占位符,在定义它们的模块加载之前没有任何功能。 当加载扩展模块时,它将添加其变量定义并根据这些定义转换任何占位符值。 - 如果存在以其扩展名开头的任何未识别的占位符,将发出警告并删除这些占位符。 + 如果存在以其扩展名称开头的任何未识别的占位符,将发出警告并删除这些占位符。 @@ -9493,11 +9455,10 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' 开发者选项 - 下面的参数目的是用在开发测试上, 并且永远不能用于生产数据库。 - 但是,它们中的一些能够用于帮助恢复严重损坏的数据库。 - 同样,它们被从示例postgresql.conf文件中排除。 - 请注意许多这些参数要求特殊的源代码编译标志才能工作。 - + 以下参数用于开发者测试,切勿用于生产数据库。不过,其中一些参数可用于辅助恢复严重损坏的数据库。 + 因此,它们未列入示例postgresql.conf文件。 + 请注意,许多参数需要特殊的源代码编译标志才能起作用。 + @@ -9510,7 +9471,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 允许将表空间创建为pg_tblspc内的目录,当CREATE TABLESPACE命令提供空位置字符串时。 + 当向CREATE TABLESPACE命令提供空的位置字符串时,允许将表空间创建为pg_tblspc内的目录。 这旨在允许测试主库和备库在同一台机器上运行的复制场景。这样的目录可能会混淆备份工具,因为这些工具期望在该位置只找到符号链接。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -9527,8 +9488,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 允许修改系统表的结构以及对系统表进行某些其他风险操作。即使对于超级用户,这也通常是不允许的。 - 不明智地使用此设置可能导致无法检索的数据丢失或严重损坏数据库系统。 + 允许修改系统表的结构以及对系统表进行某些其他风险操作。否则,即使超级用户也不允许执行这些操作。 + 不明智地使用此设置可能导致无法挽回的数据丢失或严重损坏数据库系统。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -9588,14 +9549,14 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 当设置为1时,每个系统目录缓存条目在第一个可能的机会时失效,不管任何使之无效的事情是否真的发生。 - 作为结果,系统目录的缓存被有效地禁用,因此服务器将运行得非常缓慢。 - 较高的值递归地运行缓存失效,这样会更慢,而且只用于测试缓存逻辑自身。 + 当设置为1时,每个系统目录缓存条目都会在最早可能的时刻被置为无效,无论是否真的发生了使其失效的事件。 + 这实际上禁用了系统目录缓存,因此服务器将运行得非常缓慢。 + 较高的值递归地运行缓存失效,这样会更慢,而且仅对测试缓存逻辑本身有用。 默认值0选择正常的目录缓存行为。 - 当试图触发涉及并发目录更改的难以复现的错误时,此参数非常有用,但除此之外它不太被需要。 + 当试图触发涉及并发目录更改的难以复现的错误时,此参数非常有用,但除此之外很少需要使用它。 详情请参见源码文件inval.cpg_config_manual.h @@ -9718,7 +9679,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据的时有用。这个参数在会话开始之后不能被更改。 + 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据时有用。这个参数在会话开始之后不能被更改。 @@ -9733,8 +9694,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 执行认证过程后启动新服务器进程时延迟的时间量。这是为了给开发者们一个机会在一个服务器进程上附加一个调试器。 - 如果指定值时没有单位,则以秒为单位。0值(默认值)禁用延迟。这个参数在会话开始之后不能被更改。 + 新服务器进程启动并完成认证过程之后的延迟时间。这旨在给开发者一个机会,用调试器附加到服务器进程上。 + 如果指定值时没有单位,则以秒为单位。零值(默认值)禁用延迟。这个参数在会话开始之后不能被更改。 @@ -9749,8 +9710,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 在新服务器进程分叉后,在进行认证过程之前,延迟的时间量。这是为了给开发者们一个机会在一个服务器进程上附加一个调试器来跟踪认证过程中的不当行为。 - 如果指定值时没有单位,则以秒为单位。0值(默认值)禁用延迟。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 新服务器进程刚刚派生之后、执行认证过程之前的延迟时间。这旨在给开发者一个机会,用调试器附加到服务器进程上,跟踪认证过程中的异常行为。 + 如果指定值时没有单位,则以秒为单位。零值(默认值)禁用延迟。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -9765,7 +9726,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 + 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 @@ -9779,7 +9740,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 如果打开,发出在排序操作中的资源使用的相关信息。只有在编译PostgreSQL时定义了TRACE_SORT宏, 这个参数才可用(不过,当前在默认情况下就定义了TRACE_SORT)。 + 如果开启,输出排序操作中的资源使用信息。 @@ -9794,7 +9755,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。对每一种锁类型,已授权锁和等待锁的计数也会被一起转储。一个日志文件输出的示例如下: + 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。还会转储每种锁类型已授予的锁数、等待的锁数,以及它们的总数。一个日志文件输出的示例如下: LOG: LockAcquire: new: lock(0xb7acd844) id(24688,24696,0,0,0,1) grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0 @@ -9866,7 +9827,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果设置,不会跟踪小于这个 OID 的锁(用于避免在系统表上的输出)。 + 如果设置,不会跟踪 OID 小于此值的表上的锁(用于避免在系统表上的输出)。 @@ -9942,7 +9903,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,被修改的任何缓冲区的整页镜像及其WAL记录都被加入到记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 + 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,与该 WAL 记录相关的所有已修改缓冲区的整页镜像都会被添加到该记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 @@ -9981,15 +9942,15 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 只有当数据校验和被启用时才有效。 + 只有启用数据校验和时才有效。 在读取过程中检测到校验和失败通常会导致PostgreSQL报告错误,中止当前事务。 - 将ignore_checksum_failure设置为on会导致系统忽略失败(但仍然报告警告),并继续处理。 - 这种行为可能导致崩溃,传播或隐藏损坏,或其他严重问题。然而,它可能允许您跳过错误, - 并检索可能仍然存在于表中的未损坏的元组,如果块头仍然正常。如果头部损坏,即使启用此选项也会报告错误。 - 默认设置为off。 + 将ignore_checksum_failure设置为 on 会使系统忽略失败(但仍报告警告),并继续处理。 + 这种行为可能导致崩溃、传播或隐藏损坏,或引发其他严重问题。 + 但是,如果块首部仍然正常,它可能允许你跳过错误,检索表中可能仍然存在的未损坏元组。 + 如果首部损坏,即使启用此选项也会报告错误。默认设置为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -10007,7 +9968,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 检测到损坏的页面头通常会导致PostgreSQL报告错误,中止当前事务。 将zero_damaged_pages设置为on会导致系统报告警告,将内存中的损坏页面清零,并继续处理。 - 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许您跳过错误,并从表中可能存在的未损坏页面中检索行。 + 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许你跳过错误,并从表中可能存在的未损坏页面中检索行。 如果由于硬件或软件错误而发生损坏,这对于恢复数据很有用。通常在放弃从表的损坏页面恢复数据的希望之前,不应将其设置为on。 清零的页面不会强制写入磁盘,因此建议在再次关闭此参数之前重新创建表或索引。默认设置为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -10027,9 +9988,9 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 如果设置为 off(默认值),则在恢复期间检测到引用无效页面的 WAL 记录会导致 PostgreSQL 引发 PANIC 级别错误,中止恢复。 将ignore_invalid_pages设置为on会导致系统忽略 WAL 记录中的无效页面引用(但仍报告警告),并继续恢复。 - 此行为可能会导致崩溃、数据丢失、传播或隐藏腐败,或其他严重问题。 - 但是,它可能允许你通过 PANIC 级错误,完成恢复,并启动服务器。 - 参数只能在服务器启动时设置。它仅在恢复期间或待机模式下生效。 + 此行为可能会导致崩溃、数据丢失、传播或隐藏损坏,或其他严重问题。 + 但是,它可能允许你跳过 PANIC 级错误,完成恢复,并启动服务器。 + 参数只能在服务器启动时设置。它仅在恢复期间或备库模式下生效。 @@ -10044,7 +10005,8 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果LLVM有所需要的功能,用GDB注册所生成的函数。这会让调试更加容易。默认设置是off。只有超级用户和具有适当SET权限的用户可以在会话开始时更改这个参数,并且在会话内完全不能更改它。 + 如果 LLVM 具有所需的功能,则向GDB注册生成的函数。 + 这会让调试更加容易。默认设置为off。只有超级用户和具有适当SET权限的用户才能在会话开始时更改此参数,并且在会话内完全不能更改它。 @@ -10060,7 +10022,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 将生成的LLVM IR写入文件系统,位于内。 - 这仅对于在JIT实现内部工作时有用。默认设置为off。 + 这仅对开发 JIT 的内部实现有用。默认设置为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -10091,10 +10053,9 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果LLVM有所需的功能,发出需要的数据以允许perf对JIT生成的函数画像。 - 这会写出文件到~/.debug/jit/中,如果需要,由用户负责对其执行清除。 - 默认设置是off。 - 只有超级用户和具有适当SET权限的用户可以在会话开始时更改这个参数,并且在会话内完全不能更改它。 + 如果 LLVM 具有所需的功能,则输出让perf对 JIT 生成的函数进行性能分析所需的数据。 + 这会将文件写入~/.debug/jit/;用户应在需要时自行清理。 + 默认设置为off。只有超级用户和具有适当SET权限的用户才能在会话开始时更改此参数,并且在会话内完全不能更改它。 @@ -10124,8 +10085,8 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 当设置为on时,这是默认值,PostgreSQL将在后端崩溃后自动删除临时文件。 - 如果禁用,文件将被保留,并且也许可用于调试,例如。 + 当设置为on(默认值)时,PostgreSQL将在后端崩溃后自动删除临时文件。 + 如果禁用,文件将被保留,例如可用于调试。 重复的崩溃可能会导致无用文件的积累。 该参数只能在postgresql.conf文件中或服务器命令行中设置。 @@ -10177,11 +10138,11 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 允许值为bufferedimmediate。默认值为buffered。 这个参数旨在用于测试逻辑解码以及大型事务的复制。 - debug_logical_replication_streaming对发布端和订阅端的影响不同。 + debug_logical_replication_streaming对发布者和订阅者的影响不同。 - 在发布端,debug_logical_replication_streaming允许在逻辑解码中立即流式传输或序列化更改。 + 在发布者端,debug_logical_replication_streaming允许在逻辑解码中立即流式传输或序列化更改。 当设置为immediate时,如果 streaming选项在 CREATE SUBSCRIPTION中已启用, @@ -10190,10 +10151,10 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 在订阅端,如果streaming选项被设置为parallel, - 则debug_logical_replication_streaming可用于控制主应用工作进程是将更改发送到共享内存队列, - 还是将所有更改序列化到文件。设置为buffered时,主进程通过共享内存队列将更改发送给并行应用工作进程。 - 设置为immediate时,主进程会将所有更改序列化到文件,并通知并行应用工作进程在事务结束时读取并应用这些更改。 + 在订阅者端,如果streaming选项被设置为parallel, + 则debug_logical_replication_streaming可用于控制领导者应用工作进程是将更改发送到共享内存队列, + 还是将所有更改序列化到文件。设置为buffered时,领导者通过共享内存队列将更改发送给并行应用工作进程。 + 设置为immediate时,领导者会将所有更改序列化到文件,并通知并行应用工作进程在事务结束时读取并应用这些更改。 @@ -10205,12 +10166,12 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 短选项 - 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,并且它们作为一个单字母选项存在并不表示它们会被大量使用。 + 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,它们以单字母选项的形式存在,并不一定表示鼓励频繁使用这些选项。
- 短选项键 + 短选项对照 diff --git a/zh/18/datatype.sgml b/zh/18/datatype.sgml index 07cf22ec..c8249fea 100644 --- a/zh/18/datatype.sgml +++ b/zh/18/datatype.sgml @@ -151,7 +151,7 @@ line - 平面上的无限长的线 + 平面上的无限直线 @@ -163,19 +163,19 @@ macaddr - MAC(Media Access Control)地址 + MAC(媒体访问控制)地址 macaddr8 - MAC(Media Access Control)地址(EUI-64格式) + MAC(媒体访问控制)地址(EUI-64格式) money - 货币数量 + 货币额 @@ -183,7 +183,7 @@ s) ] decimal [ (p, s) ] - 可选择精度的精确数字 + 可选择精度的精确数值 @@ -195,7 +195,7 @@ pg_lsn - PostgreSQL日志序列号类型 + PostgreSQL 日志序列号 @@ -273,13 +273,13 @@ tsquery - 文本搜索查询 + 文本检索查询 tsvector - 文本搜索文档 + 文本检索文档 @@ -420,14 +420,14 @@
- 数字类型常量的语法在里描述。数字类型有一整套对应的数学操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 + 数字类型常量的语法在里描述。数字类型有一整套对应的算术操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 整数类型 - 整数 + integer @@ -440,7 +440,7 @@ int4 - 整数 + integer @@ -460,11 +460,11 @@
- 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。而只有在integer的范围不够的时候才使用bigint。 + 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。bigint则设计用于integer的范围不够的情况。 - SQL只声明了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在许多其它SQL数据库系统中使用。 + SQL只规定了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在某些其他SQL数据库系统中使用。 @@ -473,11 +473,11 @@ 任意精度数值 - 数字(数据类型) + numeric(数据类型) - 任意精度数字 + 任意精度数值 @@ -578,18 +578,18 @@ NUMERIC(3, 5)
- infinity - numeric (数据类型) + 无穷大 + numeric(数据类型) NaN - 非数字 + 非数 - 非数字 - 数字(数据类型) + 非数 + numeric(数据类型) @@ -676,7 +676,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 双精度 + double precision @@ -686,7 +686,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; float8 - 双精度 + double precision @@ -739,8 +739,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; 默认情况下,浮点值会以最短且精确的十进制表示形式输出; - 生成的十进制值比同一二进制精度下任何其他可表示值都更接近真实 - 存储的二进制值。(不过,为了避免输入例程普遍存在的一个错误, + 所生成的十进制值与实际存储的二进制值之间的距离,小于它与任何其他可用相同二进制精度表示的值之间的距离。(不过,为了避免输入例程普遍存在的一个错误, 即未能正确遵守舍入到最近偶数规则,当前输出值绝不会 恰好位于两个可表示值的正中间。) 对于float8值,最多使用 17 位有效十进制数字; @@ -749,14 +748,14 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 生成这种最短且精确的输出格式,比历史上的圆整格式要快得多。 + 生成这种最短且精确的输出格式,比历史上的舍入格式要快得多。 为了兼容旧版本PostgreSQL生成的输出, 并允许降低输出精度,可以使用 - 参数改为选择圆整后的 + 参数改为选择舍入后的 十进制输出。将该参数设置为 0 会恢复之前的默认行为,也就是把值 舍入为 6 位(对于float4)或 15 位 (对于float8)有效十进制数字。设置为负值会 @@ -770,7 +769,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; - 过去那些需要精确值的应用,往往必须把 + 过去那些需要精确值的应用,必须把 设置为 3 才能获得它们。 为了在版本之间获得最大兼容性,这类应用应继续这样做。 @@ -778,12 +777,12 @@ FROM generate_series(-3.5, 3.5, 1) as x; 无穷大 - 浮点型 + 浮点 - 非数字 - 浮点型 + 非数 + 浮点 @@ -855,13 +854,13 @@ FROM generate_series(-3.5, 3.5, 1) as x; - auto-increment + 自动递增 serial - sequence - and serial type + 序列 + 与 serial 类型 @@ -914,7 +913,7 @@ ALTER SEQUENCE tablename_ - 要向 serial 列插入序列中的下一个值,应指定让该列 + 要向 serial 列插入序列中的下一个值,应指定让serial列 使用其默认值。这既可以通过在 INSERT 语句的 列表中省略该列来实现,也可以通过使用 DEFAULT 关键字来实现。 @@ -990,7 +989,7 @@ ALTER SEQUENCE tablename_ SELECT '12.34'::float8::numeric::money; - 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有圆整错误。 + 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有舍入误差。 @@ -1002,7 +1001,7 @@ SELECT '52093.89'::money::numeric::float8; 一个 money 值除以一个整数值时,会朝零方向截去小数 - 部分。要得到圆整结果,可以除以一个浮点值,或者在除法前先把 + 部分。要得到舍入后的结果,可以除以一个浮点值,或者在除法前先把 money 转换为 numeric,再在除法后转换回 money(如果要避免精度丢失风险,后一种做法更好)。 当一个 money 值被另一个 money 值除时, @@ -1021,12 +1020,12 @@ SELECT '52093.89'::money::numeric::float8; - string + 字符串 - 字符 + character @@ -1065,11 +1064,11 @@ SELECT '52093.89'::money::numeric::float8;
character(n), char(n), bpchar(n) - 定长,空白填充 + 定长,空格填充 bpchar - 无限长度的变长,忽略尾随空白 + 无限长度的变长,忽略尾随空格 text @@ -1128,7 +1127,7 @@ SELECT '52093.89'::money::numeric::float8; 超过 10,485,760。若 character varying (或 varchar)没有长度说明,则该类型接受任意长度 的字符串。若 bpchar 没有长度说明,它也接受任意 - 长度的字符串,但尾随空白在语义上不重要。若 + 长度的字符串,但尾随空格在语义上不重要。若 character(或 char)缺少长度说明, 则等同于 character(1)。 @@ -1150,7 +1149,7 @@ SELECT '52093.89'::money::numeric::float8; - 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储代码为零的字符(有时称为NUL)。有关更多信息,请参阅。 + 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储编码值为零的字符(有时称为NUL)。有关更多信息,请参阅 @@ -1169,7 +1168,7 @@ SELECT '52093.89'::money::numeric::float8; - 这三种类型之间没有性能差别,除了使用空白填充类型时会占用更多存储 + 这三种类型之间没有性能差别,除了使用空格填充类型时会占用更多存储 空间,以及在写入带长度约束的列时需要少量额外 CPU 周期来检查长度。 虽然在某些其他数据库系统中,character(n) 可能有一定性能优势,但在 PostgreSQL @@ -1204,7 +1203,7 @@ INSERT INTO test2 VALUES ('ok'); INSERT INTO test2 VALUES ('good '); INSERT INTO test2 VALUES ('too long'); ERROR: value too long for type character varying(5) -INSERT INTO test2 VALUES ('too long'::varchar(5)); -- explicit truncation +INSERT INTO test2 VALUES ('too long'::varchar(5)); -- 显式截断 SELECT b, char_length(b) FROM test2; b | char_length @@ -1328,7 +1327,7 @@ SELECT b, char_length(b) FROM test2; 开头(以便与转义格式区分)。在某些上下文中,这个开头的反斜线 可能需要通过双写进行转义(见 )。作为输入时,十六进制数字 - 可以使用大写或小写,并且在两个数字组成的一组之间允许出现空白 + 可以使用大写或小写,并且每两个数字组成一组,组与组之间允许出现空白 (但组内以及起始的 \x 序列中不能有空白)。 十六进制格式与大量外部应用和协议兼容,并且通常比转义格式转换得 更快,因此更推荐使用。 @@ -1392,7 +1391,7 @@ SELECT '\xDEADBEEF'::bytea; 0 - 0字节 + 零值字节 '\000' '\000'::bytea \x00 @@ -1537,10 +1536,10 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; time - 不带时区的时间 + time without time zone - 带时区的时间 + time with time zone timestamp @@ -1549,13 +1548,13 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; timestamptz - 带时区的时间戳 + timestamp with time zone - 不带时区的时间戳 + timestamp without time zone - 间隔 + interval 时间跨度 @@ -1639,7 +1638,7 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; - SQL 要求仅写 timestamp 时,应等效于 + SQL 标准要求仅写 timestamp 时,应等效于 timestamp without time zone,而 PostgreSQL 也遵循这种行为。 timestamptz 被接受为 @@ -1720,7 +1719,7 @@ MINUTE TO SECOND 其中 p 是可选的精度说明,给出秒字段中 保留的小数位数。精度可用于 timetimestampinterval 类型, - 范围是 0 到 6。这与前文描述的取值一致。如果在常量声明中没有指定 + 范围是 0 到 6。如果在常量声明中没有指定 精度,则默认采用该字面值本身的精度(但不超过 6 位)。 @@ -1749,7 +1748,7 @@ MINUTE TO SECOND 1999-01-08 - ISO 8601; 任何模式下的1月8日 + ISO 8601; 任何模式下的1月8日 (推荐格式) @@ -1785,27 +1784,27 @@ MINUTE TO SECOND 99-Jan-08 - YMD模式中的1月8日,否则错误 + YMD模式中的1月8日,否则报错 08-Jan-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 Jan-08-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 19990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 1999.008 - 年和一年中的日子 + 年和一年中的第几天 J2451187 @@ -1827,10 +1826,10 @@ MINUTE TO SECOND time - 无时区的时间 + time without time zone - 带时区的时间 + time with time zone @@ -1909,11 +1908,11 @@ MINUTE TO SECOND 040506+0730 - ISO 8601,以分数小时形式给出 UTC 偏移 + ISO 8601,时区的 UTC 偏移不是整小时 040506+07:30:00 - UTC偏移量指定为秒(ISO 8601中不允许) + UTC 偏移精确到秒(ISO 8601中不允许) 04:05:06 PST @@ -1990,11 +1989,11 @@ MINUTE TO SECOND - 带时区的时间戳 + timestamp with time zone - 无时区的时间戳 + timestamp without time zone @@ -2019,29 +2018,12 @@ January 8 04:05:06 1999 PST 也被支持。 - - SQL 标准通过时间后面是否带有 - +- 符号以及时区偏移,来区分 - timestamp without time zone 和 - timestamp with time zone 常量。因此,根据标准, - - + 按照SQL标准,timestamp without time zonetimestamp with time zone字面量的区别在于,时间后是否有+-符号及其后的时区偏移。因此,按照该标准, TIMESTAMP '2004-10-19 10:23:54' - - - 属于 timestamp without time zone,而 - - +timestamp without time zone,而 TIMESTAMP '2004-10-19 10:23:54+02' - - - 属于 timestamp with time zone。 - PostgreSQL 在确定字符串类型之前从不检查 - 其内容,因此会把上述两个值都视为 - timestamp without time zone。要确保一个常量被视为 - timestamp with time zone,应为其指定正确的显式类型: - - +timestamp with time zone。 + PostgreSQL在确定字符串字面量的类型之前,从不检查其内容,因此会把上述两者都视为timestamp without time zone。为确保字面量被视为timestamp with time zone,应为它显式指定正确类型: TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' @@ -2086,12 +2068,12 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' time - constants + 常量 date - constants + 常量 @@ -2192,13 +2174,13 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' date 输出格式 - formatting + 格式化 time 输出格式 - formatting + 格式化 @@ -2231,7 +2213,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' ISO - ISO 8601, SQL标准 + ISO 8601,SQL 标准 1997-12-17 07:37:16-08 @@ -2262,7 +2244,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' - SQL和POSTGRES风格中,如果DMY域顺序被指定,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。 + SQL和POSTGRES风格中,如果指定了 DMY 字段顺序,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。 @@ -2332,7 +2314,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 时区 - time zone + 时区 @@ -2417,8 +2399,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 除了时区名称和缩写之外, PostgreSQL 还接受 POSIX 风格的 时区说明,见 。 - 这个选项通常不如使用具名时区更合适,但如果没有可用的 IANA - 时区条目,它可能就是必需的。 + 这个选项通常不如使用具名时区更合适,但如果没有合适的 IANA 时区条目可用,它可能就是必需的。 @@ -2461,7 +2442,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 时区名称和缩写并不是硬编码在服务器中的;它们来自安装目录下 .../share/timezone/ 和 - .../share/timezonesets/ 子目录中的数据 + .../share/timezonesets/ 子目录中的配置文件 (见 )。 @@ -2499,13 +2480,13 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' - interval值可以使用下列语法书写: + interval值可以使用下列详细语法书写: @ quantity unit quantity unit... direction - 其中quantity是一个数字(很可能是有符号的); + 其中quantity是一个数字(可以带有符号); unitmicrosecondmillisecondsecondminutehourday、 @@ -2539,7 +2520,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' P quantity unit quantity unit ... T quantity unit ... 字符串必须以 P 开头,并且可以包含一个 - T 来引出一天中时间单位。可用的单位缩写见 + T 来引出一天中的时间单位。可用的单位缩写见 。单位可以省略, 也可以按任意顺序出现,但小于一天的单位必须出现在 T 之后。特别是,M 的含义 @@ -2578,7 +2559,7 @@ P quantity unit M - 分钟 (在时间部分中) + 分钟(在时间部分中) S @@ -2683,7 +2664,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; P1Y2M3DT4H5M6S - 带标志符的ISO 8601 格式:含义同上 + ISO 8601 带标志符的格式:含义同上 P0001-02-03T04:05:06 @@ -2701,7 +2682,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; interval 输出格式 - formatting + 格式化 @@ -2750,7 +2731,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; iso_8601 风格的输出符合 ISO 8601 标准 - 4.4.3.2 节描述的带标志符格式。 + 4.4.3.2 节描述的带标志符的格式
@@ -2801,7 +2782,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; 布尔类型 - Boolean + 布尔 数据类型 @@ -2912,15 +2893,15 @@ SELECT * FROM test1 WHERE a; 数据类型 - enumerated (enum) + 枚举(enum) - enumerated types + 枚举类型 - 枚举(enum)类型是由一个静态、值的有序集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的日期,或者一个数据的状态值集合。 + 枚举(enum)类型是由一个静态的有序值集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的各天,或者一个数据的状态值集合。 @@ -3029,7 +3010,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 实现细节 - 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空格也是有意义的。 + 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空白也是有意义的。 @@ -3041,7 +3022,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 从内部枚举值到文本标签的翻译被保存在系统目录pg_enum中。可以直接查询该目录。 + 从内部枚举值到文本标签的转换关系被保存在系统目录pg_enum中。直接查询该目录可能会有所帮助。 @@ -3116,7 +3097,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays circle24字节 - <(x,y),r>(中心点和半径) + <(x,y),r>(圆心和半径) @@ -3129,7 +3110,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 我们提供了丰富的函数和操作符来进行各种几何操作,例如缩放、平移、 - 旋转以及计算相交等,详见 。 + 旋转以及求交等,详见 @@ -3140,7 +3121,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 点是几何类型的基本二维构造块。用下面的语法描述point类型的值: + 点是几何类型的基本二维构造块。用下面任一种语法描述point类型的值: ( x , y ) @@ -3156,14 +3137,14 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线 + 直线 line - 线由线性方程Ax + By + C = 0 + 直线由线性方程Ax + By + C = 0 表示,其中AB不能同时为零。类型line 的值采用以下形式输入和输出: @@ -3183,7 +3164,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays (x1,y1)(x2,y2) - 是线上不同的两点。 + 是直线上不同的两点。 @@ -3199,7 +3180,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线段用一对线段的端点来表示。lseg类型的值用下面的语法声明: + 线段用一对线段的端点来表示。lseg类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ( x2 , y2 ) ] @@ -3223,15 +3204,15 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 方框 - box (data type) + box(数据类型) - rectangle + 矩形 - 方框用其对角的点对表示。box类型的值使用下面的语法指定: + 方框用其对角的点对表示。box类型的值使用下面任一种语法指定: ( ( x1 , y1 ) , ( x2 , y2 ) ) @@ -3250,7 +3231,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 在输入时可以提供任意两个对角,但是值将根据需要被按顺序记录为右上角和左下角。 + 在输入时可以提供任意两个对角,但是值将根据需要被重新排列,并依次存储为右上角和左下角。 @@ -3258,7 +3239,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 路径 - path (data type) + path(数据类型) @@ -3266,7 +3247,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - path类型的值用下面的语法声明: + path类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ... , ( xn , yn ) ] @@ -3276,11 +3257,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays x1 , y1 , ... , xn , yn - 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被忽略时,路径将被假定为封闭。 + 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被省略时,路径将被假定为封闭。 - 路径的输出使用第一种或第二种语法。 + 路径的输出视情况使用第一种或第二种语法。 @@ -3304,7 +3285,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - polygon类型的值用下列语法声明: + polygon类型的值用下列任一种语法指定: ( ( x1 , y1 ) , ... , ( xn , yn ) ) @@ -3329,7 +3310,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 圆由一个圆心和一个半径代表。circle类型的值用下面的语法指定: + 圆由一个圆心和一个半径代表。circle类型的值用下面任一种语法指定: < ( x , y ) , r > @@ -3352,7 +3333,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 网络地址类型 - network + 网络 数据类型 @@ -3409,8 +3390,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 在对 inetcidr 数据类型排序时,IPv4 - 地址总是排在 IPv6 地址之前,包括那些封装在 IPv6 地址中或映射到 - IPv6 地址中的 IPv4 地址,例如 ::10.2.3.4 或 + 地址总是排在 IPv6 地址之前,即使后者是封装或映射 IPv4 地址所得的 IPv6 地址,例如 ::10.2.3.4::ffff:10.4.3.2 @@ -3566,7 +3546,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - <type>inet</type> vs. <type>cidr</type> + <type>inet</type> 与 <type>cidr</type> inetcidr 两种数据类型的本质区别在于: @@ -3592,12 +3572,12 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - MAC地址 + MAC 地址 macaddr - macaddr类型存储 MAC 地址,也就是以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: + macaddr类型存储 MAC 地址,例如以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: '08:00:2b:01:02:03' @@ -3631,11 +3611,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays <type>macaddr8</type> - macaddr8 (data type) + macaddr8(数据类型) - MAC地址(EUI-64格式) + MAC 地址(EUI-64 格式) macaddr @@ -3762,31 +3742,31 @@ SELECT * FROM test; - 一个 bit 串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 + 一个位串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 开销,具体取决于串的长度。(不过,长值可能会被压缩或移到行外存储, 与 中对字符串的说明相同。) - 文本搜索类型 + 文本检索类型 - 全文搜索 + 全文检索 数据类型 - 文本搜索 + 文本检索 数据类型 - PostgreSQL 提供了两种专为支持全文搜索而 - 设计的数据类型。所谓全文搜索,是指在一组自然语言 + PostgreSQL 提供了两种专为支持全文检索而 + 设计的数据类型。所谓全文检索,是指在一组自然语言 文档中查找最匹配某个 查询的文档。tsvector 类型以 - 适合文本搜索的优化形式表示文档,tsquery 类型则表示 + 适合文本检索的优化形式表示文档,tsquery 类型则表示 文本查询。关于这一功能的详细解释见 ; 相关函数和操作符的概览见 @@ -3801,7 +3781,7 @@ SELECT * FROM test; tsvector 值是一个排好序且互不重复的 词位(lexeme)列表,这些词已经过 - 规范化,以便把同一单词的不同变体合并起来 + 正规化,以便把同一单词的不同变体合并起来 (详见 )。排序和去重会在输入时自动 完成,如下例所示: @@ -3860,12 +3840,12 @@ SELECT 'a:1A fat:2B,4C cat:5D'::tsvector; 权重通常用于反映文档结构,例如把标题中的词和正文中的词区分开来。 - 文本搜索排序函数可以为不同的权重标记分配不同优先级。 + 文本检索排序函数可以为不同的权重标记分配不同优先级。 必须认识到,tsvector 类型本身并不会执行任何词语 - 规范化;它假定输入的词已经按照应用需求完成规范化。例如: + 正规化;它假定输入的词已经按照应用需求完成正规化。例如: SELECT 'The Fat Rats'::tsvector; @@ -3874,9 +3854,9 @@ SELECT 'The Fat Rats'::tsvector; 'Fat' 'Rats' 'The' - 对于大多数英文全文搜索应用来说,上述词会被视为尚未规范化,但 + 对于大多数英文全文检索应用来说,上述词会被视为尚未正规化,但 tsvector 并不在意。原始文档文本通常应先经过 - to_tsvector,以按搜索需要对词语进行规范化: + to_tsvector,以按检索需要对词语进行正规化: SELECT to_tsvector('english', 'The Fat Rats'); @@ -3965,9 +3945,9 @@ SELECT 'super:*'::tsquery; 引号的使用规则与前面介绍 tsvector 时相同;同样, - 与 tsvector 一样,任何需要的词语规范化都必须在 + 与 tsvector 一样,任何需要的词语正规化都必须在 转换为 tsquery 类型之前完成。to_tsquery - 函数很适合用来实现这种规范化: + 函数很适合用来实现这种正规化: SELECT to_tsquery('Fat:ab & Cats'); @@ -3993,8 +3973,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); ---------------+------------ 'postgradu':1 | 'postgr':* - 因而它能够匹配其带前缀的后继形式 - postgraduate。 + 因而它能够匹配postgraduate 词干化后的形式。 @@ -4012,7 +3991,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); uuid 数据类型用于存储由 RFC 9562、 ISO/IEC 9834-8:2005 及相关标准定义的通用唯一标识符(UUID)。 - (有些系统把这种数据类型称为全局唯一标识符,或 GUID, + (有些系统把这种数据类型称为全局唯一标识符,或 GUID GUID。)这种标识符是一个 128 位的量,由某种算法生成,该算法被设计为使同一算法在已知宇宙中 被其他人生成出相同标识符的概率极低。因此,对于分布式系统而言, @@ -4038,7 +4017,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11 PostgreSQL 也接受其他输入形式:可以使用 - 大写字母、用花括号包围标准格式、忽略部分或全部连字符,或者在任意 + 大写字母、用花括号包围标准格式、省略部分或全部连字符,或者在任意 4 位分组后额外加上连字符。例如: A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11 @@ -4139,8 +4118,8 @@ XMLSERIALIZE ( { DOCUMENT | CONTENT } value AS XMLPARSE 或 XMLSERIALIZE 的情况下与 xml 类型互相转换时, 选择 DOCUMENT 还是 CONTENT - 由会话配置参数 XML option - XML option 决定,可以使用 + 由会话配置参数 XML 选项 + XML 选项 决定,可以使用 标准命令设置: SET XML OPTION { DOCUMENT | CONTENT }; @@ -4157,20 +4136,20 @@ SET xmloption TO { DOCUMENT | CONTENT }; 编码处理 - 在客户端、服务器以及其间传输的 XML 数据上处理多字符编码时, + 在客户端、服务器以及其间传输的 XML 数据上处理多种字符编码时, 必须格外小心。使用文本模式向服务器发送查询并把查询结果返回给 - 客户端时,PostgreSQL 会将客户端与 + 客户端时(这是通常使用的模式),PostgreSQL 会将客户端与 服务器之间传输的所有字符数据转换为目标端的字符编码,参见 。这也包括表示 XML 值的字符串,如上例 所示。这通常意味着,由于字符数据在客户端和服务器之间传输时可能被 转换为其他编码,XML 数据中包含的编码声明可能会失效,因为内嵌的 编码声明本身并不会被修改。为处理这种情况,表示 xml 类型输入值的字符串中所包含的编码声明会被 - 忽略,其内容被假定为当前服务器编码。随后, + 忽略,其内容被假定为当前服务器编码。因此, 为了正确处理,客户端发出的 XML 数据字符串必须采用当前客户端编码。 客户端负责在将文档发送给服务器之前把它们转换为当前客户端编码, 或适当调整客户端编码。输出时,xml 类型值不会带有 - 编码声明,而客户端会假定所有数据都采用当前客户端编码。 + 编码声明,而客户端应假定所有数据都采用当前客户端编码。 @@ -4204,7 +4183,7 @@ SET xmloption TO { DOCUMENT | CONTENT }; xml 数据类型有些特殊,因为它不提供任何比较操作符。 这是因为对 XML 数据并不存在良定义且通用的比较算法。其结果是, - 你无法通过把某个 xml 值与搜索值比较来检索行。 + 你无法通过把某个 xml 列与搜索值比较来检索行。 因此,XML 值通常应伴随一个独立的键字段,例如 ID。另一种比较 XML 值的办法,是先把它们转换成字符串;但请注意,字符串比较对 XML 的比较需求通常帮助不大。 @@ -4212,14 +4191,14 @@ SET xmloption TO { DOCUMENT | CONTENT }; 由于 xml 数据类型没有可用的比较操作符,因此无法直接 - 在这种类型上创建索引。如果需要在 XML 中快速搜索,可行方案包括: + 在这种类型的列上创建索引。如果需要在 XML 中快速搜索,可行方案包括: 将表达式转换为字符串类型后为其建立索引,或者为某个 XPath 表达式 建立索引。当然,实际查询也必须相应调整为使用该被索引的表达式。 - PostgreSQL 的文本搜索功能也可用于加速 - XML 数据的全文搜索。不过,目前 PostgreSQL 发行版中仍缺少所需的 + PostgreSQL 的文本检索功能也可用于加速 + XML 数据的全文检索。不过,目前 PostgreSQL 发行版中仍缺少所需的 预处理支持。 @@ -4234,12 +4213,12 @@ SET xmloption TO { DOCUMENT | CONTENT }; 域类型 - domain + - data type - domain + 数据类型 + @@ -4251,13 +4230,13 @@ SET xmloption TO { DOCUMENT | CONTENT }; CREATE DOMAIN posint AS integer CHECK (VALUE > 0); CREATE TABLE mytable (id posint); -INSERT INTO mytable VALUES(1); -- works -INSERT INTO mytable VALUES(-1); -- fails +INSERT INTO mytable VALUES(1); -- 成功 +INSERT INTO mytable VALUES(-1); -- 失败 - 当底层类型的一个操作符或函数适用于一个域值时,域会被自动向下转换为底层类型。因此,mytable.id - 1的结果会被认为是类型integer而不是posint。我们可以写成(mytable.id - 1)::posint来把结果转换回posint,这会导致域的约束被重新检查。在这种情况下,如果该表达式被应用于一个值为1的id就会错误。把底层类型的值赋给域类型的一个字段或者变量不需要写显式的类型转换,但是域的约束将会被检查。 + 当底层类型的一个操作符或函数被应用于一个域值时,域会被自动向下转换为底层类型。因此,mytable.id - 1的结果会被认为是类型integer而不是posint。我们可以写成(mytable.id - 1)::posint来把结果转换回posint,这会导致域的约束被重新检查。在这种情况下,如果该表达式被应用于一个值为1的id就会报错。把底层类型的值赋给域类型的一个字段或者变量不需要写显式的类型转换,但是域的约束将会被检查。 @@ -4340,7 +4319,7 @@ INSERT INTO mytable VALUES(-1); -- fails 对象标识符(OID)在 PostgreSQL 内部被用作 若干系统表的主键。类型 oid 表示一个对象标识符。 - 此外还有若干 oid 的别名类型,统称为 + 此外还有若干 oid 的别名类型,其名称均形如 regsomething 给出了概要说明。 @@ -4417,14 +4396,14 @@ SELECT * FROM pg_attribute regconfig pg_ts_config - 文本搜索配置 + 文本检索配置 english regdictionary pg_ts_dict - 文本搜索字典 + 文本检索词典 simple @@ -4460,7 +4439,7 @@ SELECT * FROM pg_attribute regprocedure pg_proc - 函数与参数类型 + 带参数类型的函数 sum(int4) @@ -4496,7 +4475,7 @@ SELECT * FROM pg_attribute - 这些类型的输入函数允许在各个标记之间插入空白,并且会把大写字母 + 这些类型的输入函数允许在各个词元之间插入空白,并且会把大写字母 折叠为小写,双引号内除外;这样做是为了让语法规则更接近 SQL 中 书写对象名的方式。反过来,如果需要让输出成为有效的 SQL 标识符, 输出函数会自动加上双引号。例如,一个名为 Foo @@ -4571,8 +4550,7 @@ WHERE ... 它就会对被引用对象建立依赖。例如,如果某列的默认表达式是 nextval('my_seq'::regclass)PostgreSQL 就会知道该默认表达式依赖于 - 序列 my_seq,因此系统在删除该序列之前,必须先 - 移除该默认表达式。改用 + 序列 my_seq,因此系统不允许在尚未移除该默认表达式时删除序列。改用 nextval('my_seq'::text) 则不会建立依赖。 (regrole 是这一特性的例外:该类型的常量不允许出现在 存储表达式中。) @@ -4772,7 +4750,7 @@ WHERE ... anyarray - 表示一个函数可以接受任意数组数据类型(参见 + 表示一个函数可以接受任意数组数据类型(参见)。 @@ -4891,7 +4869,7 @@ WHERE ... unknown - 标识一种尚未解析出的类型,例如未修饰的字符串字面值。 + 标识一种尚未解析出的类型,例如未修饰的字符串字面值的类型。 @@ -4909,7 +4887,7 @@ WHERE ... voidrecord 用作结果类型 (如果函数被用作触发器或事件触发器,则也允许 triggerevent_trigger 作为结果类型)。 - 有些语言还支持借助多态伪类型来实现多态函数;详见 + 有些语言还支持借助上面列出的多态伪类型来实现多态函数;详见 diff --git a/zh/18/dict-int.sgml b/zh/18/dict-int.sgml index ccca92cc..63d7ccf8 100644 --- a/zh/18/dict-int.sgml +++ b/zh/18/dict-int.sgml @@ -1,16 +1,16 @@ - dict_int — 用于整数的示例全文搜索词典 + dict_int — 用于整数的示例全文检索词典 dict_int - dict_int是一个全文搜索附加词典模板的示例。 + dict_int是一个全文检索附加词典模板的示例。 引入这个示例词典是为了控制整数(有符号和无符号)的索引, - 使这类数字能够被索引,同时又避免唯一词的数量过度增长, + 使这类数字能够被索引,同时又避免不同词的数量过度增长, 因为那会严重影响搜索性能。 @@ -54,7 +54,7 @@ 用法 - 安装dict_int扩展后,会创建一个文本搜索模板 + 安装dict_int扩展后,会创建一个文本检索模板 intdict_template以及一个基于该模板、使用默认参数的词典 intdict。你可以修改这些参数,例如: @@ -77,7 +77,7 @@ mydb# select ts_lexize('intdict', '12345678'); 但在实际使用中,通常需要像所述那样, - 将它包含到某个文本搜索配置中。可能类似如下: + 将它包含到某个文本检索配置中。可能类似如下: ALTER TEXT SEARCH CONFIGURATION english diff --git a/zh/18/func.sgml b/zh/18/func.sgml index d1b5038d..ff9e7cac 100644 --- a/zh/18/func.sgml +++ b/zh/18/func.sgml @@ -2779,7 +2779,7 @@ SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -- 检测至少有一个 null 还有其他字符串操作函数和操作符,列在中。 (其中一些用于内部实现中列出的SQL标准字符串函数。) - 此外,中还描述了模式匹配操作符,中则描述了全文搜索操作符。 + 此外,中还描述了模式匹配操作符,中则描述了全文检索操作符。
@@ -11742,7 +11742,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 文本搜索函数和操作符 + 文本检索函数和操作符 全文检索 @@ -11750,7 +11750,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 文本搜索 + 文本检索 函数和操作符 @@ -11758,12 +11758,12 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple 以及 - 总结了为全文检索提供的函数和操作符。PostgreSQL的文本搜索功能的详细解释可参考。 + 总结了为全文检索提供的函数和操作符。PostgreSQL的文本检索功能的详细解释可参考
- 文本搜索操作符 + 文本检索操作符 @@ -11923,12 +11923,12 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple 除了这些专用操作符之外, 中所示的常用比较操作符也适用于tsvectortsquery类型。 - 这些操作符对文本搜索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。 + 这些操作符对文本检索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。
- 文本搜索函数 + 文本检索函数 @@ -11975,7 +11975,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple regconfig - 返回当前默认文本搜索配置的OID(由 所设定的). + 返回当前默认文本检索配置的 OID(由 设置)。 get_current_ts_config() @@ -12511,18 +12511,18 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - 所有接受一个可选的regconfig参数的文本搜索函数在省略该参数时,会使用由指定的配置。 + 所有接受一个可选的regconfig参数的文本检索函数在省略该参数时,会使用由指定的配置。 - 中的函数被单独列出,因为它们通常不被用于日常的文本搜索操作。 - 它们主要有助于开发和调试新的文本搜索配置。 + 中的函数被单独列出,因为它们通常不被用于日常的文本检索操作。 + 它们主要有助于开发和调试新的文本检索配置。
- 文本搜索调试函数 + 文本检索调试函数 @@ -12558,7 +12558,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple lexemestext[] ) - 根据指定的或默认的文本搜索配置从document中提取和正规化词元,并返回关于每个词元是如何处理的信息。 + 根据指定的或默认的文本检索配置从document中提取和正规化词元,并返回关于每个词元是如何处理的信息。 详情参见 diff --git a/zh/18/gist.sgml b/zh/18/gist.sgml index 4f805fe8..c09a58d1 100644 --- a/zh/18/gist.sgml +++ b/zh/18/gist.sgml @@ -1046,7 +1046,7 @@ my_translate_cmptype(PG_FUNCTION_ARGS) 示例 - PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本搜索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: + PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本检索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: diff --git a/zh/18/json.sgml b/zh/18/json.sgml index bbbbf9e0..58e024c8 100644 --- a/zh/18/json.sgml +++ b/zh/18/json.sgml @@ -38,7 +38,7 @@ - 由于 json 类型存储的是输入文本的精确副本,因此它会保留标记 + 由于 json 类型存储的是输入文本的精确副本,因此它会保留词元 之间在语义上无关紧要的空白,以及 JSON 对象内部键的顺序。此外,如果值中 的某个 JSON 对象包含同一个键多次,所有键/值对都会被保留下来(处理函数会 将最后一个值视为生效值)。相比之下,jsonb 不保留空白,不保留 @@ -86,7 +86,7 @@ 当把文本形式的 JSON 输入转换为 jsonb 时, - RFC 7159 描述的基本类型会有效映射到原生的 + RFC 7159 描述的基本类型实际上会映射到原生的 PostgreSQL 类型上,如 所示。因此,什么样的数据构成 有效的 jsonb 会有一些额外但较小的限制,这些限制不适用于 @@ -137,7 +137,7 @@ null - (无) + (无) SQL NULL 是不同的概念 @@ -152,18 +152,18 @@ 以下都是有效的 json(或 jsonb)表达式: --- Simple scalar/primitive value --- Primitive values can be numbers, quoted strings, true, false, or null +-- 简单的标量/基本值 +-- 基本值可以是数字、加引号的字符串、true、false 或 null SELECT '5'::json; --- Array of zero or more elements (elements need not be of same type) +-- 包含零个或多个元素的数组(元素不必是同一类型) SELECT '[1, 2, "foo", null]'::json; --- Object containing pairs of keys and values --- Note that object keys must always be quoted strings +-- 包含键值对的对象 +-- 注意,对象的键必须始终是加引号的字符串 SELECT '{"bar": "baz", "balance": 7.77, "active": false}'::json; --- Arrays and objects can be nested arbitrarily +-- 数组和对象可以任意嵌套 SELECT '{"foo": [true, "bar"], "tags": {"a": 1, "b": null}}'::json; @@ -219,8 +219,7 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 当 JSON 数据存储在表中时,它与任何其他数据类型一样,都要面对相同的并发控 制考量。虽然存储大型文档是可行的,但要记住,任何更新都会在整行上获取一个 行级锁。应考虑将 JSON 文档限制在可管理的大小,以减少更新事务之间的锁争用。 - 理想情况下,每个 JSON 文档都应表示一个原子数据项,按照业务规则,它不应被 - 合理地进一步拆分为更小且可独立修改的数据项。 + 理想情况下,每个 JSON 文档都应表示一个原子数据项,根据业务规则,无法再合理地将它细分为更小且可独立修改的数据项。 @@ -228,11 +227,11 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; <type>jsonb</type> 包含与存在 jsonb - containment + 包含 jsonb - existence + 存在 测试 包含jsonb 的一项重要能力。 @@ -241,33 +240,32 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 示例都返回真: --- Simple scalar/primitive values contain only the identical value: +-- 简单的标量/基本值只包含相同的值: SELECT '"foo"'::jsonb @> '"foo"'::jsonb; --- The array on the right side is contained within the one on the left: +-- 左侧数组包含右侧数组: SELECT '[1, 2, 3]'::jsonb @> '[1, 3]'::jsonb; --- Order of array elements is not significant, so this is also true: +-- 数组元素的顺序无关紧要,因此下面的结果也为真: SELECT '[1, 2, 3]'::jsonb @> '[3, 1]'::jsonb; --- Duplicate array elements don't matter either: +-- 重复的数组元素也无关紧要: SELECT '[1, 2, 3]'::jsonb @> '[1, 2, 2]'::jsonb; --- The object with a single pair on the right side is contained --- within the object on the left side: +-- 左侧对象包含右侧只有一个键值对的对象: SELECT '{"product": "PostgreSQL", "version": 9.4, "jsonb": true}'::jsonb @> '{"version": 9.4}'::jsonb; --- The array on the right side is not considered contained within the --- array on the left, even though a similar array is nested within it: -SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- yields false +-- 左侧数组被认为包含右侧数组, +-- 尽管其中嵌套了一个类似的数组: +SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- 结果为假 --- But with a layer of nesting, it is contained: +-- 但增加一层嵌套后,就构成了包含关系: SELECT '[1, 2, [1, 3]]'::jsonb @> '[[1, 3]]'::jsonb; --- Similarly, containment is not reported here: -SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- yields false +-- 同样,下面也不构成包含关系: +SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- 结果为假 --- A top-level key and an empty object is contained: +-- 包含由顶层键和空对象构成的对象: SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; @@ -282,11 +280,11 @@ SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; 对于结构必须匹配这一一般原则,有一个特殊例外:数组可以包含一个基本值: --- This array contains the primitive string value: +-- 这个数组包含该基本字符串值: SELECT '["foo", "bar"]'::jsonb @> '"bar"'::jsonb; --- This exception is not reciprocal -- non-containment is reported here: -SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false +-- 这个例外并不对称——下面的结果表示不包含: +SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- 结果为假 @@ -296,19 +294,19 @@ SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false 外,下面这些示例都返回真: --- String exists as array element: +-- 字符串作为数组元素存在: SELECT '["foo", "bar", "baz"]'::jsonb ? 'bar'; --- String exists as object key: +-- 字符串作为对象键存在: SELECT '{"foo": "bar"}'::jsonb ? 'foo'; --- Object values are not considered: -SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- yields false +-- 不考虑对象的值: +SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- 结果为假 --- As with containment, existence must match at the top level: -SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- yields false +-- 与包含关系一样,存在性必须在顶层匹配: +SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- 结果为假 --- A string is considered to exist if it matches a primitive JSON string: +-- 如果字符串与一个基本 JSON 字符串匹配,则认为它存在: SELECT '"foo"'::jsonb ? 'foo'; @@ -322,8 +320,7 @@ SELECT '"foo"'::jsonb ? 'foo'; 由于 JSON 包含是嵌套的,因此适当的查询可以跳过对子对象的显式选择。例如, 假设我们有一个 doc 列,其顶层是对象,而且大 多数对象都带有 tags 字段,该字段中包含子对象数组。下面 - 这个查询会找出那些包含同时带有 "term":"paris" 和 - "term":"food" 的子对象的项,同时忽略 + 这个查询会找出同时出现包含 "term":"paris" 的子对象和包含 "term":"food" 的子对象的项,同时忽略 tags 数组之外的任何此类键: SELECT doc->'site_name' FROM websites @@ -353,7 +350,7 @@ SELECT doc->'site_name' FROM websites <type>jsonb</type> 索引 jsonb - indexes on + 索引 @@ -403,14 +400,14 @@ CREATE INDEX idxginp ON api USING GIN (jdoc jsonb_path_ops); 名为 jdocjsonb 列里。 如果在该列上创建了 GIN 索引,那么下面这样的查询就可以利用这个索引: --- Find documents in which the key "company" has value "Magnafone" +-- 查找键 "company" 的值为 "Magnafone" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"company": "Magnafone"}'; 但是,类似下面这样的查询就无法使用该索引,因为虽然操作符 ? 可索引,但它并未直接应用到被索引的列 jdoc 上: --- Find documents in which the key "tags" contains key or array element "qui" +-- 查找键 "tags" 包含键或数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc -> 'tags' ? 'qui'; 不过,只要适当地使用表达式索引,上述查询也可以利用索引。如果经常查询 @@ -428,7 +425,7 @@ CREATE INDEX idxgintags ON api USING GIN ((jdoc -> 'tags')); 另一种查询方法是利用包含,例如: --- Find documents in which the key "tags" contains array element "qui" +-- 查找键 "tags" 包含数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qui"]}'; jdoc 列上的简单 GIN 索引可以支持这个查询。 @@ -466,7 +463,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; @@ 操作符的查询,但相较于默认操作符类 jsonb_ops,它具有显著的性能优势。 jsonb_path_ops 索引通常比相同数据上的 - jsonb_ops 索引小得多,而且搜索条件也更具特异性,尤其是在 + jsonb_ops 索引小得多,而且搜索也更有针对性,尤其是在 查询中包含数据里频繁出现的键时。因此,搜索操作通常比使用默认操作符类时 性能更佳。 @@ -482,9 +479,9 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; 基本上,每个 jsonb_path_ops 索引项都是该值连同 - 通向该值的键一起计算出的哈希。例如,要索引 + 通向该值的键一起计算出的 hash。例如,要索引 {"foo": {"bar": "baz"}},会创建一个单独的索引项, - 其哈希值中同时纳入 foobar 和 + 其 hash 值中同时纳入 foobarbaz 这三者。因此,查找这一结构的包含查询会得到一次 非常精确的索引搜索;但完全没有办法据此找出 foo 是否 作为键出现。另一方面,jsonb_ops 索引会分别创建三个 @@ -506,7 +503,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; jsonb 还支持 btreehash 索引。通常只有在需要检查完整 JSON 文档是否相等时, 它们才有用。btreejsonb 数据项的 - 排序通常没什么太大意义,但为了完整起见,其规则如下: + 排序顺序通常很少受到关注,但为了完整起见,其规则如下: 对象 > 数组 > 布尔值 > 数字 > 字符串 > null @@ -561,27 +558,24 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; --- Extract object value by key +-- 按键提取对象的值 SELECT ('{"a": 1}'::jsonb)['a']; --- Extract nested object value by key path +-- 按键路径提取嵌套对象的值 SELECT ('{"a": {"b": {"c": 1}}}'::jsonb)['a']['b']['c']; --- Extract array element by index +-- 按下标提取数组元素 SELECT ('[1, "2", null]'::jsonb)[1]; --- Update object value by key. Note the quotes around '1': the assigned --- value must be of the jsonb type as well +-- 按键更新对象的值。注意 '1' 两边的引号:赋予的值也必须是 jsonb 类型 UPDATE table_name SET jsonb_field['key'] = '1'; --- This will raise an error if any record's jsonb_field['a']['b'] is something --- other than an object. For example, the value {"a": 1} has a numeric value --- of the key 'a'. +-- 如果任何记录的 jsonb_field['a']['b'] 不是对象,就会报错。 +-- 例如,值 {"a": 1} 的键 'a' 对应的值是数字。 UPDATE table_name SET jsonb_field['a']['b']['c'] = '1'; --- Filter records using a WHERE clause with subscripting. Since the result of --- subscripting is jsonb, the value we compare it against must also be jsonb. --- The double quotes make "value" also a valid jsonb string. +-- 使用带下标的 WHERE 子句筛选记录。由于下标操作的结果是 jsonb, +-- 与之比较的值也必须是 jsonb。双引号使 "value" 也成为合法的 jsonb 字符串。 SELECT * FROM table_name WHERE jsonb_field['key'] = '"value"'; @@ -591,19 +585,19 @@ SELECT * FROM table_name WHERE jsonb_field['key'] = '"value"'; (对象或数组)的空 JSON 值来处理: --- Where jsonb_field was NULL, it is now {"a": 1} +-- 原先为 NULL 的 jsonb_field 现在为 {"a": 1} UPDATE table_name SET jsonb_field['a'] = '1'; --- Where jsonb_field was NULL, it is now [1] +-- 原先为 NULL 的 jsonb_field 现在为 [1] UPDATE table_name SET jsonb_field[0] = '1'; - 如果对一个元素数量不足的数组指定了某个索引,就会不断追加 - NULL 元素,直到该索引可达并且可以设置该值为止。 + 如果对一个元素数量不足的数组指定了某个下标,就会不断追加 + NULL 元素,直到该下标可达并且可以设置该值为止。 --- Where jsonb_field was [], it is now [null, null, 2]; --- where jsonb_field was [0], it is now [0, null, 2] +-- 原先为 [] 的 jsonb_field 现在为 [null, null, 2]; +-- 原先为 [0] 的 jsonb_field 现在为 [0, null, 2] UPDATE table_name SET jsonb_field[2] = '2'; @@ -614,10 +608,10 @@ UPDATE table_name SET jsonb_field[2] = '2'; null 填充,直到能够放入被赋值的值为止。 --- Where jsonb_field was {}, it is now {"a": [{"b": 1}]} +-- 原先为 {} 的 jsonb_field 现在为 {"a": [{"b": 1}]} UPDATE table_name SET jsonb_field['a'][0]['b'] = '1'; --- Where jsonb_field was [], it is now [null, {"a": 1}] +-- 原先为 [] 的 jsonb_field 现在为 [null, {"a": 1}] UPDATE table_name SET jsonb_field[1]['a'] = '1'; @@ -634,7 +628,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; PL/Perl 的扩展名为 jsonb_plperljsonb_plperlu。如果使用它们, - jsonb 值会按适当方式映射为 Perl 数组、哈希和标量。 + jsonb 值会按适当方式映射为 Perl 数组、hash 和标量。 @@ -694,7 +688,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; 的。还支持非十进制整数字面量和下划线分隔符,例如 1_000_0000x1EEE_FFFF0o2730b100101。在 SQL/JSON - 路径中(以及 JavaScript 中,但不包括严格意义上的 SQL),基数前缀后面不能 + 路径中(以及 JavaScript 中,但 SQL 本身并非如此),基数前缀后面不能 直接出现下划线分隔符。 @@ -723,7 +717,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; - 路径表达式由一系列路径元素构成,可以是下列任意一种: + 路径表达式由一系列路径元素构成,这些元素可以是下列任意一种: @@ -862,7 +856,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; 类似 .**,但只选择 JSON 层次结构中指定的层级。 - 嵌套层级以整数指定。层级零对应当前对象。若要访问最低的嵌套层级, + 嵌套层级以整数指定。层级零对应当前对象。若要访问最深的嵌套层级, 可以使用 last 关键字。这是 PostgreSQL 对 SQL/JSON 标准的扩展。 @@ -880,13 +874,13 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; 可以用两种形式给出: indexstart_index to end_index。 - 第一种形式按索引返回单个数组元素。第二种形式按索引范围返回数组切片, + 第一种形式按下标返回单个数组元素。第二种形式按下标范围返回数组切片, 其中包括与给定 start_indexend_index 对应的元素。 指定的 index 可以是整数,也可以是返回单个 - 数值的表达式,该表达式会自动转换为整数。索引零对应第一个数组元素。 + 数值的表达式,该数值会自动转换为整数。下标零对应第一个数组元素。 你也可以使用 last 关键字来表示最后一个数组元素, 这对于处理长度未知的数组很有用。 diff --git a/zh/18/libpq.sgml b/zh/18/libpq.sgml index 6772cb49..bf7e2fbd 100644 --- a/zh/18/libpq.sgml +++ b/zh/18/libpq.sgml @@ -2,7 +2,7 @@ - <application>libpq</application> - C 库 + <application>libpq</application> — C 库 libpq @@ -13,33 +13,27 @@ - libpq是应用程序员使用PostgreSQLC接口。libpq是一个库函数的集合,它们允许客户端程序传递查询给PostgreSQL后端服务器并且接收这些查询的结果。 + libpqPostgreSQLC应用程序编程接口。libpq是一组库函数,客户端程序可用它们向PostgreSQL后端服务器发送查询并接收查询结果。 - libpq也是很多其他PostgreSQL应用接口的底层引擎,包括为 C++、Perl、Python、Tcl 和 ECPG编写的接口。如果你使用那些包,某些方面的libpq行为将会对你很重要。特别是,描述了任何使用libpq的应用的用户可见的行为。 + libpq也是其他几个PostgreSQL应用程序接口的底层引擎,包括为 C++、Perl、Python、Tcl 和ECPG编写的接口。因此,对于这些包的用户,libpq行为的某些方面也很重要。特别是,描述了任何使用libpq的应用程序的用户都能观察到的行为。 - 在本章的末尾()包括了一些短程序来展示如何编写使用libpq的应用。在源代码发布的src/test/examples目录中还有一些完整的libpq应用的示例。 + 本章末尾()包含一些简短程序,展示如何编写使用libpq的程序。源代码发行包的src/test/examples目录中还提供了几个完整的libpq应用程序示例。 - 使用libpq的客户端程序必须包括头文件libpq-fe.hlibpq-fe.h并必须与libpq库链接在一起。 + 使用libpq的客户端程序必须包含头文件libpq-fe.hlibpq-fe.h,并且必须与libpq库链接。 数据库连接控制函数 - - 下列函数会建立到一个PostgreSQL后端服务器的连接。 - 一个应用程序可以在一个时刻打开多个后端连接(原因之一就是为了访问多个数据库)。 - 每个连接用一个PGconnPGconn对象表示,它从函数,或得到。 - 注意这些函数将总是返回一个非空的对象指针,除非正好没有内存来分配PGconn对象。 - 在通过该连接对象发送查询之前,应该调用函数来检查返回值以确定是否得到了一个成功的连接。 - - + 以下函数用于建立到PostgreSQL后端服务器的连接。应用程序可以同时保持多个后端连接。(这样做的原因之一是访问多个数据库。)每个连接由一个PGconnPGconn对象表示,该对象可以通过以下函数获取:, + 。注意,这些函数总是返回非空的对象指针,除非内存不足,甚至无法分配PGconn对象。应调用函数检查返回值,确认连接成功后,再通过连接对象发送查询。 如果不受信任的用户能够访问一个没有采用模式的安全使用方式的数据库,那么每个会话开始时都应从search_path中移除公开可写的模式。可以把参数关键词options设置为-csearch_path=。也可以在连接后发出PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)")。这种考虑并非专门针对libpq;它适用于每一种可执行任意 SQL 命令的接口。 @@ -47,7 +41,7 @@ - 在 Unix 上,复制一个拥有打开 libpq 连接的进程可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行代码是安全的。 + 在 Unix 上,对持有已打开 libpq 连接的进程执行 fork 操作可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行程序是安全的。 @@ -74,32 +68,32 @@ PGconn *PQconnectdbParams(const char * const *keywords, - 被传递的数组可以为空,这样就会使用所有默认参数。 - 也可以只包含一个或几个参数设置。他们在长度上必须匹配。 - 对于参数数组的处理将会停止于keywords数组中第一个NULL元素。 - 而且,如果与非-NULL keywords条目相关联的values条目为NULL或者空字符串,则忽略该项并继续处理下一对数组项。 + 传入的数组可以为空,以使用所有默认参数,也可以包含一个或多个参数设置。 + 两个数组的长度必须相同。处理会在 keywords 数组的第一个 NULL 元素处停止。 + 如果某个非 NULLkeywords 元素所对应的 + values 元素为 NULL 或空字符串,则忽略这一项,继续处理下一对数组元素。 - 当expand_dbname为非零时,会检查第一个dbname关键词的值以查看它是否为一个连接字符串。 - 如果是,它被扩展到从字符串中提取的单独的连接参数。 - 该值被认为是一个连接字符串,而不仅是一个数据库名称,如果它包含一个等号(=)或者它以URI模式标志符开头, - (有关连接字符串格式的更多详情可见。) - 只有dbname的第一次出现会按这种方式处理,任何后续dbname值会被当做一个普通数据库名处理。 + 当 expand_dbname 非零时,会检查第一个 dbname 关键词的值是否为 + 连接字符串。如果是,就将其展开为从该字符串中提取的各个连接参数。 + 如果该值包含等号(=),或以 URI 方案标识符开头,就会将其视为连接字符串,而非单纯的数据库名。 + (连接字符串格式的详细说明见。) + 只有第一次出现的 dbname 会按这种方式处理;后续的 dbname 参数都作为普通数据库名处理。 - 通常,参数数组从开头到结尾进行处理。 - 当关键词有重复时,使用最后一个值(不是 NULL 或空)。 - 此规则特别适用于连接字符串中的关键字与一个出现在keywords数组中的关键字冲突的情况。 - 因此,程序员可以决定数组条目是否能被覆盖或用连接字符串获取的值覆盖。 - 出现在扩展的dbname条目之前的数组条目可以被连接字符串的字段所覆盖,反之,这些字段被dbname之后出现的数组条目所覆盖。(但是,再有,只有在那些条目支持非空值时。) + 通常会从头到尾处理参数数组。如果某个关键词重复出现,则采用最后一个非 NULL 且非空的值。 + 此规则也适用于连接字符串中的关键词与 keywords 数组中的关键词冲突的情况。 + 因此,程序员可以决定数组元素是覆盖连接字符串中的值,还是被这些值覆盖。 + 出现在要展开的 dbname 元素之前的数组元素,可以被连接字符串中的字段覆盖; + 而这些字段又会被出现在 dbname 之后的数组元素覆盖(同样,只有这些元素提供非空值时才会覆盖)。 - 在处理完所有数组条目和任何扩展的连接字符串后,所有未设置的连接参数都将使用默认值填充。 - 如果一个未设置参数的相关环境变量(参见 )被设置了,它的值会被使用。 - 如果环境变量未被设置,则使用参数的内置默认值。 + 处理完所有数组元素及展开的连接字符串后,仍未设置的连接参数将填入默认值。 + 如果某个未设置参数对应的环境变量(见)已经设置,就使用该环境变量的值; + 否则使用该参数的内置默认值。 @@ -121,7 +115,7 @@ PGconn *PQconnectdb(const char *conninfo); - 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空格分隔的一个或多个参数设置,还可以包含一个URI。详见。 + 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空白分隔的一个或多个参数设置,还可以包含一个URI。详见 @@ -144,11 +138,11 @@ PGconn *PQsetdbLogin(const char *pghost, - 这是的带有固定参数集合的前辈。它具有相同的功能,不过其中缺失的参数将总是采用默认值。对任意一个固定参数写NULL或一个空字符串将会使它采用默认值。 + 这是 的前身,使用固定的一组参数。除缺失参数始终采用默认值之外,功能相同。对于要使用默认值的任意固定参数,请传入 NULL 或空字符串。 - 如果dbName包含一个=符号或者具有一个合法的连接URI前缀,它会被当作一个conninfo字符串,就好像它已经被传递给了,并且剩余的参数则被应用为指定给。 + 如果 dbName 包含 = 符号,或具有有效的连接 URI 前缀,就会将其当作 conninfo 字符串处理,方式与将其传给 完全相同,然后按照 的规则应用其余参数。 @@ -183,7 +177,7 @@ PGconn *PQsetdb(char *pghost, PQconnectPollPQconnectPoll - nonblocking connection + 非阻塞连接 以非阻塞的方式建立一个到数据库服务器的连接。 @@ -220,7 +214,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 如果你调用,确保你追踪的该流对象不会阻塞。 + 如果你调用,确保接收追踪输出的流对象不会阻塞。 @@ -233,11 +227,11 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 要开始无阻塞的连接请求,可调用PQconnectStart或者。如果结果为空,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 + 要开始非阻塞连接请求,可调用PQconnectStart或者。如果结果为空指针,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 - 如果PQconnectStart成功,下一个阶段是轮询libpq,这样它能够继续进行连接序列。使用PQsocket(conn)来获得该数据库连接底层的套接字描述符(警告:不要假定在PQconnectPoll调用之间套接字会保持相同)。这样循环:如果PQconnectPoll(conn)上一次返回PGRES_POLLING_READING,等到该套接字准备好读取(按照select()poll()或类似的系统函数所指示的)。则再次调用PQconnectPoll(conn)。反之,如果PQconnectPoll(conn)上一次返回PGRES_POLLING_WRITING,等到该套接字准备好写入,则再次调用PQconnectPoll(conn)。在第一次迭代时,即如果你还没有调用PQconnectPoll,行为就像是它上次返回了PGRES_POLLING_WRITING。持续这个循环直到PQconnectPoll(conn)返回PGRES_POLLING_FAILED指示连接过程已经失败,或者返回PGRES_POLLING_OK指示连接已经被成功地建立。 + 如果PQconnectStart成功,下一个阶段是轮询libpq,这样它能够继续进行连接序列。使用PQsocket(conn)来获得该数据库连接底层的套接字描述符(警告:不要假定在PQconnectPoll调用之间套接字会保持相同)。这样循环:如果PQconnectPoll(conn)上一次返回PGRES_POLLING_READING,等到该套接字准备好读取(按照select()poll()或类似的系统函数所指示的)。注意,PQsocketPoll封装了select(2)poll(2)(如果系统支持)的设置,可减少重复代码。然后再次调用PQconnectPoll(conn)。反之,如果PQconnectPoll(conn)上一次返回PGRES_POLLING_WRITING,等到该套接字准备好写入,则再次调用PQconnectPoll(conn)。在第一次迭代时,即如果你还没有调用PQconnectPoll,行为就像是它上次返回了PGRES_POLLING_WRITING。持续这个循环直到PQconnectPoll(conn)返回PGRES_POLLING_FAILED指示连接过程已经失败,或者返回PGRES_POLLING_OK指示连接已经被成功地建立。 @@ -327,7 +321,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 注意,尽管这些常数将被保留(为了维护兼容性),一个应用永远不应该依赖这些状态按照特定顺序出现,或者根本就不依赖它们,或者不依赖状态总是这些文档中所说的值。一个应用可能做些这样的事情: + 注意,虽然为保持兼容性会保留这些常量,但应用程序不应依赖它们按特定顺序出现,不应假定它们一定出现,也不应假定状态值一定是这里列出的某个值。应用程序可以采用如下方式: switch(PQstatus(conn)) { @@ -348,11 +342,11 @@ switch(PQstatus(conn)) - 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。否则,PQconnectStart后面跟着PQconnectPoll循环等效于。 + 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。除此之外,PQconnectStart后面跟着PQconnectPoll循环等效于 - 注意当PQconnectStart返回一个非空的指针时,你必须在用完它之后调用来处理那些结构体和任何相关的内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 + 注意当PQconnectStart返回一个非空的指针时,你必须在用完它之后调用来释放该结构体及其关联的所有内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 @@ -400,21 +394,21 @@ PQconninfoOption *PQconndefaults(void); typedef struct { char *keyword; /* 该选项的关键词 */ - char *envvar; /* 依赖的环境变量名 */ - char *compiled; /* 依赖的内置默认值 */ + char *envvar; /* 后备环境变量名 */ + char *compiled; /* 编译时设置的后备默认值 */ char *val; /* 选项的当前值,或者 NULL */ - char *label; /* 连接对话框中域的标签 */ - char *dispchar; /* 指示如何在一个连接对话框中显示这个域。值是: + char *label; /* 连接对话框中字段的标签 */ + char *dispchar; /* 指示如何在连接对话框中显示此字段。可取值: "" 显示输入的值 - "*" 密码域 - 隐藏值 + "*" 密码字段 - 隐藏值 "D" 调试选项 - 默认不显示 */ - int dispsize; /* 用于对话框的以字符计的域尺寸 */ + int dispsize; /* 对话框中的字段宽度,以字符计 */ } PQconninfoOption; - 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前缺省值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回该空指针。注意当前缺省值(val域)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 + 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前默认值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回空指针。注意当前默认值(val字段)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 @@ -435,9 +429,7 @@ PQconninfoOption *PQconninfo(PGconn *conn); - 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前缺省值。 - 返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。 - 上述所有对于的注解也适用于的结果。 + 返回一个连接选项数组。可以用它确定所有可能的 选项,以及实际用于连接服务器的值。返回值指向一个 PQconninfoOption 结构体数组,该数组以 keyword 指针为空的条目结束。上文针对 的所有注意事项,也适用于 的结果。 @@ -463,7 +455,9 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); - 如果errmsg不是NULL,那么成功时*errmsg会被设置为NULL, 否则设置为被malloc过的错误字符串以说明该问题(也可以将*errmsg设置为NULL并且函数返回NULL,这表示一种内存耗尽的情况)。 + 如果 errmsg 不是 NULL,则成功时将 *errmsg 设为 NULL; + 失败时将其设为由 malloc 分配的、用于说明问题的错误字符串。 + (也可能出现 *errmsg 被设为 NULL,同时函数返回 NULL 的情况;这表示内存不足。) @@ -493,7 +487,7 @@ void PQfinish(PGconn *conn); PQresetPQreset - 重置与服务器的通讯通道。 + 重置与服务器的通信通道。 void PQreset(PGconn *conn); @@ -511,7 +505,7 @@ void PQreset(PGconn *conn); PQresetPollPQresetPoll - 以非阻塞方式重置与服务器的通讯通道。 + 以非阻塞方式重置与服务器的通信通道。 int PQresetStart(PGconn *conn); @@ -528,7 +522,7 @@ PostgresPollingStatusType PQresetPoll(PGconn *conn); - 要发起一次连接重置,调用。如果它返回 0,那么重置失败。如果返回 1,就按使用PQresetPoll建立连接时相同的方法,继续调用PQresetPoll来重置连接。 + 要开始重置连接,请调用 。如果返回 0,表示重置失败。如果返回 1,则使用 PQresetPoll 轮询重置过程,方式与使用 PQconnectPoll 建立连接完全相同。 @@ -623,7 +617,7 @@ void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook); int callback_fn(char *buf, int size, PGconn *conn); - 随后,libpq会调用该回调,而不是调用其默认的PQdefaultSSLKeyPassHook_OpenSSL处理程序。 + 随后,libpq会调用该回调,而不是调用其默认的PQdefaultSSLKeyPassHook_OpenSSL处理程序。 回调函数应确定密钥密码,并将其复制到大小为size的结果缓冲区buf中。 buf中的字符串必须以空字符结尾。 回调函数必须返回存储在buf中的密码长度,不包括结尾的空字符。 @@ -642,7 +636,7 @@ int callback_fn(char *buf, int size, PGconn *conn); - 除了异常、longjmp(...)等情况外,回调务必不可跳出正常控制流。它必须正常返回。 + 回调不得通过异常、longjmp(...)等方式跳出正常控制流。它必须正常返回。 @@ -679,9 +673,9 @@ PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void); 几个libpq函数解析用户指定的字符串以获取连接参数。 - 这些字符串有两种被接受的格式:普通的关键字/值字符串和URI。URI通常遵循 + 这些字符串有两种被接受的格式:普通的关键词/值字符串和URI。URI通常遵循 RFC - 3986,除了允许多主机连接字符串,如下面进一步描述的那样。 + 3986,但也允许使用多主机连接字符串,详见下文。 @@ -689,10 +683,10 @@ PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void); 关键词/值连接字符串 - 在关键词/值格式中,每一个参数设置的形式都是关键词 = ,在设置之间有空白。 - 设置的等号周围的空白是可选的。 - 要写一个空值或一个包含空白的值,将它用单引号包围,例如关键词 = 'a value'。 - 值里面的单引号和反斜线必须用一个反斜线转义,即\'\\。 + 在关键词/值格式中,每一个参数设置的形式都是关键词 = ,设置之间以空格分隔。 + 设置的等号周围的空格是可选的。 + 要写一个空值或一个包含空格的值,将它用单引号包围,例如keyword = 'a value'。 + 值里面的单引号和反斜杠必须用一个反斜杠转义,即\'\\ @@ -716,22 +710,22 @@ host=localhost port=5432 dbname=mydb connect_timeout=10 postgresql://userspec@hostspec/dbname?paramspec -where userspec is: +其中 userspec 为: user:password -and hostspec is: +hostspec 为: host:port,... -and paramspec is: +paramspec 为: name=value&... - URI模式标志符可以是postgresql://postgres://。 + URI方案标识符可以是postgresql://postgres://。 每一个剩下的URI部分都是可选的。 下列示例展示了合法的URI语法: @@ -748,19 +742,15 @@ postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application postgresql:///mydb?host=localhost&port=5433 - 全部的命名参数必须匹配中列出的关键词,除了与JDBC连接URI兼容之外,ssl=true的实例转换到sslmode=require。 + 所有命名参数都必须与中列出的关键词匹配;唯一的例外是,为兼容 JDBC 连接 URI,会将 ssl=true 转换为 sslmode=require - 连接URI需要使用百分号编码 - 对其进行编码,如果其中包含具有特殊含义的符号。这里是一个示例,其中等号(=)被替换为 - %3D,空格字符被替换为 - %20: + 如果连接 URI 的任意部分包含具有特殊含义的符号,就需要使用百分号编码。下面的示例将等号(=)替换为 %3D,将空格字符替换为 %20 postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff - + 主机部分可能是主机名或一个 IP 地址。要指定一个 IPv6 地址,将它封闭在方括号中: @@ -773,7 +763,7 @@ postgresql://[2001:db8::1234]/database 主机组件会被按照参数对应的描述来解释。 特别地,如果主机部分是空或看起来像一个绝对路径名称,将使用一个 Unix 域套接字连接,否则将启动一个 TCP/IP 连接。 不过要注意,斜线是 URI 层次部分中的一个保留字符。 - 因此,要指定一个非标准的 Unix 域套接字目录,要么忽略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: + 因此,要指定一个非标准的 Unix 域套接字目录,要么省略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: postgresql:///dbname?host=/var/lib/postgresql postgresql://%2Fvar%2Flib%2Fpostgresql/dbname @@ -783,7 +773,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以在一个URI中指定多个主机,每一个都有一个可选的端口。 一个形式为postgresql://host1:port1,host2:port2,host3:port3/的URI等效于host=host1,host2,host3 port=port1,port2,port3形式的连接字符串。 - 如下所述,每一个主机都将被尝试,直到成功地建立一个连接。 + 如下所述,每一个主机都将被依次尝试,直到成功地建立一个连接。 @@ -793,7 +783,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以指定多个要连接的主机,这样它们会按给定的顺序被尝试。 - 在键/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 + 在关键词/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 在指定的每一个选项中都必须给出相同数量的元素,这样第一个hostaddr对应于第一个主机名,第二个hostaddr对应于第二个主机名,以此类推。 不过,如果仅指定一个port,它将被应用于所有的主机。 @@ -803,11 +793,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 不管是哪一种格式,单一的主机名可以被翻译成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 + 不管是哪一种格式,单一的主机名可以被解析成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 - 当多个主机被指定时或者单个主机名被翻译成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。 + 当多个主机被指定时或者单个主机名被解析成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。 @@ -829,14 +819,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 要连接的主机名。主机名如果主机名看起来像绝对路径名, - 则指定的是Unix域通信而不是TCP/IP通信;该值是存储套接字文件的目录的名称。 - (在Unix上,绝对路径名以斜杠开头。在Windows上,以驱动器号开头的路径也被识别。) - 如果主机名以@开头,则将其视为抽象命名空间中的Unix域套接字(目前在Linux和Windows上支持)。 - 当未指定host或为空时,默认行为是连接到Unix域套接字Unix域套接字在 - /tmp(或在构建PostgreSQL时指定的套接字目录)中。在Windows和 - 没有Unix域套接字的机器上,默认是连接到localhost。 - + 要连接的主机名。主机名如果主机名看起来像绝对路径名, + 则指定的是 Unix 域通信,而非 TCP/IP 通信;此值是存放套接字文件的目录名。 + (在 Unix 上,绝对路径名以斜杠开头。在 Windows 上,也会识别以驱动器号开头的路径。)如果主机名以 @ 开头,则将其视为抽象命名空间中的 Unix 域套接字(目前在 Linux 和 Windows 上支持)。 + 当未指定 host 或其值为空时,默认连接到 /tmp + (或构建 PostgreSQL 时指定的套接字目录)中的 Unix 域套接字。 + Unix 域套接字在 Windows 上,默认连接到 localhost。 + 也可以接受一个逗号分隔的主机名列表,此时列表中的每个主机名将按顺序尝试; @@ -864,7 +853,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 如果指定了host而没有指定hostaddr,则会发生主机名查找。 (当使用PQconnectPoll时,查找发生在PQconnectPoll首次考虑此主机名时, - 并且可能导致PQconnectPoll阻塞一段时间。) + 并且可能导致PQconnectPoll阻塞相当长的时间。) @@ -876,11 +865,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果同时指定了hosthostaddr, - 则hostaddr的值给出服务器的网络地址。 - 除非认证方法需要,否则host的值将被忽略, - 在这种情况下,它将用作主机名。 - + 如果同时指定了 hosthostaddr,则 hostaddr 的值给出服务器的网络地址。只有认证方法需要主机名时,才会将 host 的值用作主机名;否则忽略该值。 + 请注意,如果host不是网络地址hostaddr上服务器的名称, @@ -896,10 +882,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 没有主机名或主机地址, - libpq将使用本地的Unix域套接字进行连接; - 或者在Windows和没有Unix域套接字的机器上,它将尝试连接到localhost。 - + 如果既没有主机名也没有主机地址,libpq 会使用本地 Unix 域套接字连接;在 Windows 上,则会尝试连接到 localhost。 + @@ -933,8 +917,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - PostgreSQL用户连接的用户名。 - 默认为运行应用程序的操作系统用户名相同。 + 建立连接所用的 PostgreSQL 用户名。默认与运行应用程序的操作系统用户名相同。 @@ -944,7 +927,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果服务器要求密码认证,则使用密码。 + 服务器要求密码认证时所使用的密码。 @@ -965,7 +948,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname require_auth - 指定客户端要求服务器采用的认证方法。如果服务器没有使用所要求的方法来认证客户端,或者服务器没有完整完成认证握手,则连接将失败。也可以提供一个以逗号分隔的方法列表,此时服务器必须准确使用其中一种方法,连接才会成功。默认情况下接受任意认证方法,并且服务器也可以完全跳过认证。 + 指定客户端要求服务器采用的认证方法。如果服务器没有使用所要求的方法来认证客户端,或者服务器没有完整完成认证握手,则连接将失败。也可以提供一个以逗号分隔的方法列表,此时服务器必须恰好使用其中一种方法,连接才会成功。默认情况下接受任意认证方法,并且服务器也可以完全跳过认证。 可以在方法名前加上!前缀以表示否定,此时服务器不得尝试所列方法;除此之外,任何其他方法都可接受,并且服务器也可以完全不认证客户端。如果提供的是逗号分隔列表,服务器不得尝试其中任何一个被否定的方法。否定形式和非否定形式不能在同一设置中混用。 @@ -1055,7 +1038,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 这个选项控制客户端对通道绑定的使用。设置为require表示连接必须使用通道绑定, prefer表示客户端将在可用时选择通道绑定, 而disable则阻止使用通道绑定。默认情况下, - 如果PostgreSQL是使用SSL支持编译的,则默认为prefer; + 如果PostgreSQL是使用SSL支持编译的,则默认为prefer; 否则默认为disable @@ -1071,9 +1054,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 连接时的最长等待时间,以秒为单位(写成十进制整数,例如,10)。 - 零、负值或未指定表示无限等待。最小允许的超时时间为2秒,因此 - 1的值被解释为2。 - 此超时时间分别适用于每个主机名或IP地址。 + 零、负值或未指定表示无限等待。此超时时间分别适用于每个主机名或IP地址。 例如,如果指定了两个主机和connect_timeout 为5,如果在5秒内没有建立连接,每个主机将超时, 因此等待连接的总时间可能长达10秒。 @@ -1119,9 +1100,9 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 指定配置参数的回退值。 + 指定配置参数的后备值。 如果没有通过连接参数或PGAPPNAME环境变量为application_name指定值, - 则将使用此值。在通用实用程序中指定回退名称很有用,该程序希望设置默认应用程序名称, + 则将使用此值。在通用实用程序中指定后备名称很有用,该程序希望设置默认应用程序名称, 但允许用户覆盖它。 @@ -1132,9 +1113,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制是否使用客户端TCP保持活动。默认值为1,表示开启,但如果不想要保持活动,可以将其更改为0,表示关闭。 - 对于通过Unix域套接字进行的连接,此参数将被忽略。 - + 控制是否使用客户端 TCP keepalive。默认值为 1,表示开启;如果不需要 keepalive,可以将其设为 0,表示关闭。对于通过 Unix 域套接字建立的连接,此参数会被忽略。 + @@ -1143,11 +1123,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在多少秒的不活动后,TCP应向服务器发送保持活动消息。值为零使用系统默认值。 - 对通过Unix域套接字进行的连接或禁用保持活动的连接,此参数将被忽略。 - 仅在支持TCP_KEEPIDLE或等效套接字选项的系统以及Windows上支持; - 在其他系统上,它没有任何效果。 - + 控制在多久没有活动后,TCP 应向服务器发送 keepalive 消息,以秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPIDLE 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -1156,11 +1133,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在服务器未确认的情况下重新传输TCP保持活动消息的秒数。值为零时使用系统默认值。 - 此参数在通过Unix域套接字进行连接或禁用保持活动时将被忽略。 - 仅在支持TCP_KEEPINTVL或等效套接字选项的系统和Windows上支持; - 在其他系统上,此参数无效。 - + 控制未被服务器确认收到的 TCP keepalive 消息在多少秒后应被重传。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPINTVL 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -1169,11 +1143,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在客户端与服务器之间连接被视为断开之前可以丢失的TCP keepalive数量。 - 值为零时使用系统默认值。对通过Unix域套接字建立的连接或禁用keepalives的连接,此参数将被忽略。 - 仅在支持TCP_KEEPCNT或等效套接字选项的系统上受支持; - 在其他系统上,此参数无效。 - + 控制在客户端与服务器之间的连接被视为中断之前,可以丢失多少个 TCP keepalive 消息。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPCNT 或等效套接字选项的系统上受支持;在其他系统上无效。 + @@ -1182,10 +1153,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在连接在强制关闭之前,传输数据可以保持未被确认的毫秒数。 - 值为零时使用系统默认值。此参数对通过Unix域套接字进行的连接无效。 - 仅在支持TCP_USER_TIMEOUT的系统上受支持;在其他系统上,它没有效果。 - + 控制已发送的数据在连接被强制关闭之前最多可以保持未确认状态多长时间,以毫秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,此参数会被忽略。此参数仅在支持 TCP_USER_TIMEOUT 的系统上受支持;在其他系统上无效。 + @@ -1248,25 +1217,25 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个选项确定是否以及如何优先与服务器协商安全的GSS TCP/IP连接。有三种模式: + 这个选项确定是否以及以何种优先级与服务器协商安全的GSS TCP/IP连接。有三种模式: disable - 仅尝试非GSSAPI加密连接 + 仅尝试未经GSSAPI加密的连接 - prefer (默认) + prefer (默认) 如果存在GSSAPI凭据(即在凭据缓存中),首先尝试 GSSAPI加密连接;如果失败或没有凭据,则尝试 - 非GSSAPI加密连接。这是在编译PostgreSQL时使用GSSAPI支持时的默认设置。 + 未经GSSAPI加密的连接。这是在编译PostgreSQL时使用GSSAPI支持时的默认设置。 @@ -1285,7 +1254,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname gssencmode在Unix域套接字通信中被忽略。如果PostgreSQL没有编译GSSAPI支持, 使用require选项将导致错误,而prefer将被接受,但libpq实际上不会尝试 - 进行GSSAPI加密连接。GSSAPI与libpq + 进行GSSAPI加密连接。GSSAPI在 libpq 中 @@ -1317,7 +1286,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - prefer (默认) + prefer (默认) 首先尝试SSL连接;如果失败,则尝试非SSL连接 @@ -1357,22 +1326,18 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - sslmode被忽略用于Unix域套接字通信。 - 如果PostgreSQL没有SSL支持编译, + 在 Unix 域套接字通信中,sslmode 会被忽略。 + 如果PostgreSQL编译时未启用 SSL 支持, 使用选项requireverify-caverify-full会导致错误,而选项allowprefer 将被接受,但libpq实际上不会尝试建立SSL 连接。SSL使用libpq的SSL + sortas="libpq">在 libpq 中 - 请注意,如果可能使用GSSAPI加密, - 则优先使用该加密,而不考虑SSL的值。要在具有可用GSSAPI - 基础设施(如Kerberos服务器)的环境中强制使用 - SSL加密,还需将 - gssencmode设置为disable。 - + 注意,如果可以使用 GSSAPI 加密,就会优先使用它而不是 SSL 加密,无论 sslmode 的值是什么。在具有可用 GSSAPI 基础设施(例如 Kerberos 服务器)的环境中,要强制使用 SSL 加密,还应将 gssencmode 设为 disable。 + @@ -1381,15 +1346,15 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 此选项已被sslmode设置所取代。 - + 此选项已弃用,请改用 sslmode 设置。 + 如果设置为1,则需要与服务器建立SSL连接(这相当于sslmode require)。libpq将拒绝连接,如果服务器不接受 SSL连接。如果设置为0(默认值), libpq将与服务器协商连接类型(相当于sslmode - prefer)。此选项仅在PostgreSQL编译时启用SSL支持。 + prefer)。此选项仅在 PostgreSQL 编译时启用了 SSL 支持的情况下可用。 @@ -1439,7 +1404,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果安全性不是主要考虑因素,压缩可以提高吞吐量,如果网络是瓶颈的话。如果CPU性能是限制因素,禁用压缩可以提高响应时间和吞吐量。 + 如果安全性不是主要考虑因素,压缩可以提高吞吐量,如果网络是瓶颈的话。如果CPU性能是限制因素,禁用压缩可以缩短响应时间并提高吞吐量。 @@ -1463,7 +1428,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 这个参数指定了用于客户端证书的密钥的位置。它可以指定一个文件名,该文件名将被用来替代默认的 ~/.postgresql/postgresql.key,或者它可以指定一个从外部引擎 - (引擎是OpenSSL可加载模块)获取的密钥。外部引擎规范应该包括一个由冒号分隔的引擎名称和 + (引擎是OpenSSL可加载模块)获取的密钥。外部引擎的指定形式应包含一个由冒号分隔的引擎名称和 一个引擎特定的密钥标识符。如果没有进行SSL连接,则此参数将被忽略。 @@ -1492,10 +1457,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 指定此参数为任何非空值将抑制Enter PEM pass phrase: - 当提供加密的客户端证书密钥给libpq时, - OpenSSL默认会发出的提示。 - + 当向 libpq 提供加密的客户端证书密钥时,将此参数指定为任意非空值,都将抑制 OpenSSL 默认发出的 Enter PEM pass phrase: 提示。 + 如果密钥未加密,则忽略此参数。该参数对由OpenSSL引擎指定的密钥没有影响,除非引擎使用OpenSSL密码回调机制进行提示。 @@ -1577,10 +1540,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定SSL服务器证书吊销列表(CRL)的文件名。如果存在该文件中列出的证书,在尝试验证服务器证书时将被拒绝。 - 如果既没有设置也没有设置, - 则将采用~/.postgresql/root.crl。 - + 此参数指定 SSL 服务器证书吊销列表(CRL)的文件名。如果该文件存在,在验证服务器证书时,会拒绝其中列出的证书。如果既未设置,也未设置,则采用 ~/.postgresql/root.crl。 + @@ -1589,8 +1550,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定SSL服务器证书吊销列表(CRL)的目录名称。如果存在该目录中的文件中列出的证书,在尝试验证服务器证书时将被拒绝。 - + 此参数指定 SSL 服务器证书吊销列表(CRL)的目录名。如果该目录存在,在验证服务器证书时,会拒绝该目录下文件中列出的证书。 + 目录需要使用OpenSSL命令 @@ -1605,19 +1566,17 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - sslsniServer Name Indication + sslsni服务器名称指示 - 如果设置为1(默认值),libpq会在启用SSL的连接上设置TLS扩展Server Name IndicationSNI)。 + 如果设置为1(默认值),libpq会在启用SSL的连接上设置TLS扩展服务器名称指示SNI)。 通过将此参数设置为0,可以关闭此功能。 - 服务器名称指示可以被SSL感知代理使用,以便在不解密SSL流的情况下路由连接。 - (请注意,这需要一个了解PostgreSQL协议握手的代理,而不仅仅是任何SSL代理。) - 然而,SNI会使目标主机名以明文形式出现在网络流量中,因此在某些情况下可能不希望使用。 - + 支持 SSL 的代理可以利用服务器名称指示来路由连接,而无需解密 SSL 流。(注意,除非代理能够识别 PostgreSQL 协议握手,否则需要将 sslnegotiation 设为 direct。)不过,SNI 会使目标主机名以明文形式出现在网络流量中,因此在某些情况下可能不希望使用它。 + @@ -1642,8 +1601,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定连接允许的最低SSL/TLS协议版本。有效值为TLSv1, - TLSv1.1TLSv1.2和 + 这个参数指定连接允许的最低SSL/TLS协议版本。有效值为TLSv1、 + TLSv1.1TLSv1.2TLSv1.3。支持的协议取决于所使用的 OpenSSL版本,旧版本不支持最现代的协议版本。 如果未指定,默认值为TLSv1.2,符合本文撰写时的行业最佳实践。 @@ -1656,11 +1615,10 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定连接允许的最大SSL/TLS协议版本。有效值为TLSv1, - TLSv1.1TLSv1.2和 + 这个参数指定连接允许的最大SSL/TLS协议版本。有效值为TLSv1、 + TLSv1.1TLSv1.2TLSv1.3。支持的协议取决于使用的OpenSSL - 版本,旧版本不支持最新的协议版本。如果未设置,将忽略此参数,并且连接将使用后端定义的最大限制, - 如果设置。设置最大协议版本主要用于测试或者某些组件无法使用较新协议时。 + 版本,旧版本不支持最新的协议版本。如果未设置,则忽略此参数;如果后端定义了最大限制,连接将使用该限制。设置最大协议版本主要用于测试或者某些组件无法使用较新协议时。 @@ -1712,13 +1670,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 用于使用GSSAPI进行认证时要使用的Kerberos服务名称。 + 使用 GSSAPI 认证时所用的 Kerberos 服务名。 这必须与服务器配置中指定的Kerberos认证服务名称匹配,才能成功进行认证。 (另请参见。) 默认值通常为postgres, - 但在构建PostgreSQL时可以通过 - 选项进行更改 - configure。 + 但在构建 PostgreSQL 时,可以通过 configure 选项更改。 在大多数环境中,通常不需要更改此参数。 一些Kerberos实现可能需要不同的服务名称, 例如Microsoft Active Directory需要服务名称为大写(POSTGRES)。 @@ -1742,7 +1698,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname gssdelegation - 将 GSS 凭证转发(委派)给服务器。默认值为0,表示不向服务器转发凭证。将其设置为1时,会在可能的情况下转发凭证。 + 将 GSS 凭据转发(委派)给服务器。默认值为0,表示不向服务器转发凭据。将其设置为1时,会在可能的情况下转发凭据。 @@ -1751,7 +1707,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname scram_client_key - 以 Base64 编码的 SCRAM 客户端密钥。外部数据包装器或类似中间件可以利用它启用透传式 SCRAM 认证。一个实现示例见。普通用户或客户端应用不应直接指定它。 + 以 Base64 编码的 SCRAM 客户端密钥。外部数据包装器或类似中间件可以利用它启用透传式 SCRAM 认证。一个实现示例见。用户或客户端应用不应直接指定它。 @@ -1760,7 +1716,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname scram_server_key - 以 Base64 编码的 SCRAM 服务器密钥。外部数据包装器或类似中间件可以利用它启用透传式 SCRAM 认证。一个实现示例见。普通用户或客户端应用不应直接指定它。 + 以 Base64 编码的 SCRAM 服务器密钥。外部数据包装器或类似中间件可以利用它启用透传式 SCRAM 认证。一个实现示例见。用户或客户端应用不应直接指定它。 @@ -1891,7 +1847,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname “混淆攻击(mix-up attacks)” - 你也可以显式把oauth_issuer设置为 OAuth 发现所使用的/.well-known/ URI。在这种情况下,如果服务器要求使用不同的 URL,连接就会失败;不过,自定义 OAuth 流程也许能够通过使用先前缓存的令牌来加速标准握手。(此时也建议设置,因为客户端将没有机会向服务器询问正确的 scope 设置,而令牌的默认 scope 可能不足以完成连接。)libpq当前支持以下 well-known 端点: + 你也可以显式把oauth_issuer设置为 OAuth 发现所使用的/.well-known/ URI。在这种情况下,如果服务器要求使用不同的 URL,连接就会失败;不过,自定义 OAuth 流程也许能够通过使用先前缓存的令牌来加速标准握手。(此时也建议设置,因为客户端将没有机会向服务器询问正确的授权范围设置,而令牌的默认授权范围可能不足以完成连接。)libpq当前支持以下 well-known 端点: /.well-known/openid-configuration /.well-known/oauth-authorization-server @@ -1918,8 +1874,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname oauth_client_secret - 与 OAuth 授权服务器通信时要使用的客户端密码(如果有)。该参数是否必需由 OAuth 提供者决定;“public” 客户端通常不使用 secret,而 “confidential” 客户端通常会使用。 - + 与 OAuth 授权服务器通信时要使用的客户端密码(如果有)。该参数是否必需由 OAuth 提供者决定;公开客户端(public client)通常不使用密钥,而机密客户端(confidential client)通常会使用。 + @@ -1927,13 +1883,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname oauth_scope - 发送给授权服务器的访问请求 scope,以 OAuth scope 标识符的空格分隔列表指定(该列表可以为空)。该参数是可选的,面向高级用法。 - + 发送给授权服务器的访问请求的授权范围,以空格分隔的 OAuth 授权范围标识符列表指定(列表可以为空)。该参数是可选的,面向高级用法。 + - 通常客户端会从PostgreSQL服务器获得合适的 scope 设置。如果使用这个参数,服务器请求的 scope 列表会被忽略。这可以防止不那么受信任的服务器向最终用户请求不恰当的访问 scope。不过,如果客户端的 scope 设置不包含服务器所要求的 scope,服务器很可能会拒绝已经签发的令牌,连接也会失败。 + 通常客户端会从PostgreSQL服务器获得合适的授权范围设置。如果使用这个参数,服务器请求的授权范围列表会被忽略。这可以防止不那么受信任的服务器向最终用户请求不恰当的访问授权范围。不过,如果客户端的授权范围设置不包含服务器所要求的授权范围,服务器很可能会拒绝已经签发的令牌,连接也会失败。 - 空 scope 列表的含义取决于提供者。OAuth 授权服务器可以选择签发带有“默认 scope”的令牌,不管那具体是什么;也可以完全拒绝该令牌请求。 + 空授权范围列表的含义取决于提供者。OAuth 授权服务器可以选择签发带有“默认授权范围”的令牌,不管那具体是什么;也可以完全拒绝该令牌请求。 @@ -1947,23 +1903,21 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 连接状态函数 - 这些函数可以被用来询问一个已有数据库连接对象的状态。 + 这些函数可用于查询现有数据库连接对象的状态。 - libpq-fe.h - libpq-int.h - libpq应用程序员应该小心地维护PGconn抽象。使用下面描述的访问函数来理解PGconn的内容。我们不推荐使用libpq-int.h引用内部的PGconn域,因为它们可能在未来改变。 - + libpq-fe.h + libpq-int.h + 编写 libpq 应用程序时,应注意维护 PGconn 的抽象。请使用下述访问函数获取 PGconn 的内容。不建议通过 libpq-int.h 引用 PGconn 的内部字段,因为这些字段将来可能改变。 + - 下列函数返回一个连接所建立的参数值。这些值在连接的生命期中是固定的。 - 如果使用的是多主机连接字符串,如果使用同一个PGconn对象建立新连接,,, 和 可能会改变。其他值在PGconn对象的一生中都是固定的。 - - + 以下函数返回建立连接时确定的参数值。这些值在连接存续期间保持不变。如果使用多主机连接字符串,并使用同一个 PGconn 对象建立新连接,则 的返回值可能改变。其他值在 PGconn 对象的整个生命周期内保持不变。 + PQdbPQdb @@ -2013,7 +1967,7 @@ char *PQpass(const PGconn *conn); - 返回活跃连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 + 返回活动连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 char *PQhost(const PGconn *conn); @@ -2025,7 +1979,7 @@ char *PQhost(const PGconn *conn); - 如果conn参数是NULL,则返回NULL。否则,如果有一个错误产生主机信息(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成主机信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -2046,8 +2000,7 @@ char *PQhostaddr(const PGconn *conn); - 如果conn 参数为 NULL 返回 NULL 。 - 否则,如果生成主机信息时出现错误(如果连接尚未完全建立或出现错误),则返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成主机信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -2057,7 +2010,7 @@ char *PQhostaddr(const PGconn *conn); - 返回活跃连接的端口。 + 返回活动连接的端口。 char *PQport(const PGconn *conn); @@ -2069,7 +2022,7 @@ char *PQport(const PGconn *conn); - 如果conn参数是NULL,则返回NULL。否则,如果有一个错误产生端口信息(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成端口信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -2083,9 +2036,7 @@ char *PQport(const PGconn *conn); - 这个函数不再做任何事,但是它保持了向后兼容。 - 这个函数总是返回一个空字符串,或者NULL,如果connNULL。 - + 此函数已不再执行任何操作,但为保持向后兼容仍予以保留。如果 conn 参数为 NULL,则返回 NULL;否则始终返回空字符串。 char *PQtty(const PGconn *conn); @@ -2098,7 +2049,7 @@ char *PQtty(const PGconn *conn); - 返回被传递给连接请求的命令行选项。 + 返回连接请求中传递的命令行选项。 char *PQoptions(const PGconn *conn); @@ -2106,12 +2057,11 @@ char *PQoptions(const PGconn *conn); - + - 下列函数返回会随着在PGconn对象上执行的操作改变的状态数据。 - - + 以下函数返回的状态数据,可能随着对 PGconn 对象执行操作而改变。 + PQstatusPQstatus @@ -2124,9 +2074,9 @@ ConnStatusType PQstatus(const PGconn *conn); - 该状态可以是一系列值之一。不过,其中只有两个在一个异步连接过程之外可见:CONNECTION_OKCONNECTION_BAD。 - 一个到数据库的完好连接的状态为CONNECTION_OK。一个失败的连接尝试则由状态CONNECTION_BAD表示。 - 通常,一个 OK 状态将一直保持到,但是一次通信失败可能导致该状态过早地改变为CONNECTION_BAD。 + 该状态可以是一系列值之一。不过,其中只有两个在一个异步连接过程之外可见:CONNECTION_OKCONNECTION_BAD。 + 一个到数据库的完好连接的状态为CONNECTION_OK。一个失败的连接尝试则由状态CONNECTION_BAD表示。 + 通常,一个 OK 状态将一直保持到,但是一次通信失败可能导致该状态过早地改变为CONNECTION_BAD。 在那种情况下,该应用可以通过调用尝试恢复。 @@ -2147,7 +2097,7 @@ ConnStatusType PQstatus(const PGconn *conn); PGTransactionStatusType PQtransactionStatus(const PGconn *conn); - 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个合法的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接损坏,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE。 + 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个有效的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接异常,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE。 @@ -2246,21 +2196,21 @@ int PQserverVersion(const PGconn *conn); - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 + 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,为每个部分使用两位数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 + 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。在所有主版本系列中,各次版本(缺陷修复版本)之间只有最后两位数字不同。 - PQerrorMessagePQerrorMessage + PQerrorMessagePQerrorMessage错误消息PGconn - 错误消息返回连接上的一个操作最近产生的错误消息。 + 返回连接上的一个操作最近产生的错误消息。 char *PQerrorMessage(const PGconn *conn); @@ -2269,9 +2219,7 @@ char *PQerrorMessage(const PGconn *conn); - 几乎所有的libpq在失败时都会为设置一个消息。 - 注意按照libpq习惯,一个非空结果由多行构成,并且将包括一个尾部新行。 - 调用者不应该直接释放结果。当相关的PGconn句柄被传递给时,它将被释放。在PGconn结构体上的多个操作之间,不能指望结果字符串会保持不变。 + 几乎所有 libpq 函数在失败时都会设置一条供 返回的消息。注意,按照 libpq 的约定,非空的 结果可能包含多行,并以换行符结尾。调用者不应直接释放该结果;当关联的 PGconn 句柄被传给 时,结果会被释放。不能假定在对 PGconn 结构体执行其他操作后,结果字符串仍保持不变。 @@ -2280,7 +2228,7 @@ char *PQerrorMessage(const PGconn *conn); PQsocketPQsocket - 获得到服务器连接套接字的文件描述符号。一个合法的描述符将会大于等于零。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 + 获取与服务器相连的套接字的文件描述符编号。有效描述符大于或等于 0。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 int PQsocket(const PGconn *conn); @@ -2297,7 +2245,7 @@ int PQsocket(const PGconn *conn); 返回处理这个连接的后端进程的进程ID(PID)。 PID 确定服务器进程的 PID - in libpq + 在 libpq 中 @@ -2306,7 +2254,7 @@ int PQbackendPID(const PGconn *conn); - 后端PID有助于调试目的并且可用于与NOTIFY消息(它包括发出提示的后端进程的PID)进行比较。注意PID属于一个在数据库服务器主机上执行的进程,而不是本地主机进程! + 后端 PID 可用于调试,也可与 NOTIFY 消息进行比较(消息包含发出通知的后端进程的 PID)。注意,该 PID 属于在数据库服务器主机上运行的进程,而非本地主机上的进程! @@ -2361,19 +2309,18 @@ int PQconnectionUsedGSSAPI(const PGconn *conn); - + - 以下函数返回与SSL相关的信息。这些信息通常在建立连接后不会更改。 - - + 以下函数返回与 SSL 相关的信息。这些信息通常在连接建立后不会改变。 + PQsslInUsePQsslInUse - 返回true(1)如果连接使用SSL,返回false(0)如果不使用。 + 如果连接使用 SSL,则返回真(1);否则返回假(0)。 int PQsslInUse(const PGconn *conn); @@ -2389,7 +2336,7 @@ int PQsslInUse(const PGconn *conn); - 返回与连接相关的SSL信息。 + 返回连接的 SSL 相关信息。 const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); @@ -2401,7 +2348,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); - 常见的属性如下: + 通常可以获取以下属性: library @@ -2488,18 +2435,14 @@ const char * const * PQsslAttributeNames(const PGconn *conn); - 返回一个指向描述连接的SSL实现特定对象的指针。如果连接未加密或SSL实现不提供连接的请求对象类型,则返回NULL。 + 返回指向描述此连接的对象的指针,该对象的类型由 SSL 实现决定。如果连接未加密,或连接所用的 SSL 实现不提供所请求的对象类型,则返回 NULL。 void *PQsslStruct(const PGconn *conn, const char *struct_name); - 可用的结构体取决于正在使用的SSL实现。 - 对于OpenSSL,有一个结构体, - 可以通过名称OpenSSL获得, - 并返回一个指向OpenSSLSSL结构体的指针。 - 要使用这个函数,可以使用以下代码: + 可用的结构体取决于所使用的 SSL 实现。对于 OpenSSL,可以通过名称 OpenSSL 获取一个结构体,函数返回指向 OpenSSLSSL 结构体的指针。可以使用如下代码调用此函数: #include @@ -2550,7 +2493,7 @@ void *PQgetssl(const PGconn *conn); - + @@ -2559,7 +2502,7 @@ void *PQgetssl(const PGconn *conn); 命令执行函数 - 一旦到一个数据库服务器的连接被成功建立,这里描述的函数可以被用来执行 SQL 查询和命令。 + 与数据库服务器的连接成功建立后,此处描述的函数用于执行 SQL 查询和命令。 @@ -2581,11 +2524,8 @@ PGresult *PQexec(PGconn *conn, const char *command); - 返回一个PGresult指针或者可能是一个空指针。 - 除了内存不足的情况或者由于严重错误无法将命令发送给服务器之外,一般都会返回一个非空指针。 - 函数应当被调用来检查返回值是否代表错误(包括空指针的值,它会返回PGRES_FATAL_ERROR)。 - 用可得到关于那些错误的详细信息。 - + 返回一个 PGresult 指针,也可能返回空指针。除内存不足或无法向服务器发送命令等严重错误外,通常都会返回非空指针。应调用 函数检查返回值是否表示错误(也应检查空指针,此时该函数返回 PGRES_FATAL_ERROR)。使用 获取此类错误的更多信息。 + @@ -2666,8 +2606,8 @@ PGresult *PQexecParams(PGconn *conn, paramValues[] - 指定参数的实际值。这个数组中的一个空指针表示对应的参数为空,否则该指针指向一个以零终止的文本字符串(用于文本格式)或者以服务器所期待格式的二进制数据(用于二进制格式)。 - + 指定参数的实际值。数组中的空指针表示对应参数为 null;否则,指针指向以零结尾的文本字符串(文本格式),或采用服务器所要求格式的二进制数据(二进制格式)。 + @@ -2675,8 +2615,8 @@ PGresult *PQexecParams(PGconn *conn, paramLengths[] - 指定二进制格式参数的实际数据长度。它对空参数和文本格式参数被忽略。当没有二进制参数时,该数组指针可以为空。 - + 指定二进制格式参数的实际数据长度。对于 null 参数和文本格式参数,该值会被忽略。如果没有二进制参数,数组指针可以为空指针。 + @@ -2684,11 +2624,11 @@ PGresult *PQexecParams(PGconn *conn, paramFormats[] - 指定参数是否为文本(在参数相应的数组项中放一个零)或二进制(在参数相应的数组项中放一个一)。如果该数组指针为空,那么所有参数都会被假定为文本串。 - + 指定参数采用文本格式(在对应数组元素中填入零)还是二进制格式(填入一)。如果数组指针为空指针,则将所有参数视为文本字符串。 + - 以二进制格式传递的值要求后端所期待的内部表示形式的知识。例如,整数必须以网络字节序被传递。传递numeric值要求关于服务器存储格式的知识,正如src/backend/utils/adt/numeric.c::numeric_send()以及src/backend/utils/adt/numeric.c::numeric_recv()中所实现的。 - + 以二进制格式传递值时,需要了解后端所要求的内部表示形式。例如,整数必须以网络字节序传递。传递 numeric 值时,需要了解服务器的存储格式,其实现见 src/backend/utils/adt/numeric.c::numeric_send()src/backend/utils/adt/numeric.c::numeric_recv()。 + @@ -2696,8 +2636,8 @@ PGresult *PQexecParams(PGconn *conn, resultFormat - 指定零来得到文本格式的结果,或者指定一来得到二进制格式的结果(目前没有规定要求以不同格式得到不同的结果列,尽管在底层协议中这是可以实现的)。 - + 指定零以获取文本格式的结果,指定一以获取二进制格式的结果。(目前无法让不同结果列使用不同格式,尽管底层协议支持这样做。) + @@ -2708,8 +2648,8 @@ PGresult *PQexecParams(PGconn *conn, - 相对于的主要优点是参数值可以从命令串中分离,因此避免了冗长的书写、容易发生错误的引用以及转义。 - + 相对于 的主要优点是可以将参数值与命令字符串分开,从而避免繁琐且容易出错的加引号和转义工作。 + 不同,至多允许在给定串中出现一个 SQL 命令(其中可以有分号,但是不能有超过一个非空命令)。这是底层协议的一个限制,但是有助于抵抗 SQL 注入攻击。 @@ -2718,12 +2658,12 @@ PGresult *PQexecParams(PGconn *conn, - 通过 OID 指定参数类型很罗嗦,特别是如果你不愿意将特定的 OID 值硬编码到你的程序中时。不过,即使服务器本身也无法确定参数的类型,你可以避免这样做,或者选择一种与你想要的不同的类型。在 SQL 命令文本中,附加一个显式类型转换给参数符号来表示你将发送什么样的数据类型。例如: + 通过 OID 指定参数类型较为繁琐,尤其是在不希望将具体 OID 值写死在程序中时。不过,即使服务器无法自行确定参数类型,或者推断出的类型与你所需的不同,也可以避免直接指定 OID。在 SQL 命令文本中,为参数符号添加显式类型转换,即可指定要发送的数据类型。例如: SELECT * FROM mytable WHERE x = $1::bigint; - 这强制参数$1被当作bigint,而默认情况下它将被赋予与x相同的类型。当以二进制格式发送参数值时,我们强烈推荐以这种方式或通过指定一个数字类型的 OID 来强制参数类型决定。因为二进制格式比文本格式具有更少的冗余,并且因此服务器将不会有更多机会为你检测一个类型匹配错误。 - +这会强制将参数 $1 当作 bigint,而默认情况下会为它分配与 x 相同的类型。以二进制格式发送参数值时,强烈建议采用这种方式,或直接指定类型的数值 OID,来明确决定参数类型。因为二进制格式的冗余比文本格式更少,服务器发现类型不匹配错误的机会也更少。 + @@ -2744,15 +2684,15 @@ PGresult *PQprepare(PGconn *conn, - 创建一个后面会由执行的预备语句。 + 创建一个预备语句,供随后使用 执行。 这个特性允许命令被反复执行而无需每次都进行解析和规划,详见。 - + 该函数从query串创建一个名为stmtName的预备语句,该串必须包含一个单一 SQL 命令。 stmtName可以是""来创建一个未命名语句,在这种情况下任何已存在未命名语句将被自动替换。 否则,如果语句名称已经在当前会话中被定义,则是一种错误。如果使用了任何参数,它们在查询中以$1$2等引用。 - nParams是参数的个数,其类型在数组paramTypes[]中被预先指定(当nParams为零时,该数组指针可以是NULL)。 + nParams 是在数组 paramTypes[] 中预先指定了类型的参数数量(当nParams为零时,该数组指针可以是NULL)。 paramTypes[]通过 OID 指定要赋予给参数符号的数据类型。 如果paramTypesNULL或者该数组中任何特定元素为零,服务器会用对待未指定类型的字符串字面量的方式为参数符号推测一种数据类型。 还有,查询能够使用编号高于nParams的参数符号,它们的数据类型也会被自动推测(找出推测出的数据类型的方法见)。 @@ -2760,7 +2700,7 @@ PGresult *PQprepare(PGconn *conn, 正如一样,结果通常是一个PGresult对象,其内容代表服务器端成功或失败。 - 一个空结果表示内存不足或者根本无法发送命令。关于错误的更多信息请见。 + 返回空指针表示内存不足,或者根本无法发送命令。关于错误的更多信息请见 @@ -2792,9 +2732,9 @@ PGresult *PQexecPrepared(PGconn *conn, 类似于, - 但要执行的命令是通过指定先前准备好的语句来指定,而不是提供查询字符串。 - 此功能允许重复使用的命令只被解析和计划一次,而不是每次执行时都要进行。 - 该语句必须在当前会话中先前准备好。 + 但它通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。 + 此功能使重复使用的命令只需解析和规划一次,而不必在每次执行时都进行这些工作。 + 该语句必须事先在当前会话中创建为预备语句。 @@ -2811,23 +2751,23 @@ PGresult *PQexecPrepared(PGconn *conn, - 提交请求以获取有关指定准备好的语句的信息,并等待完成。 + 提交请求以获取有关指定预备语句的信息,并等待完成。 PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - 允许应用程序获取关于先前准备的语句的信息。 + 允许应用程序获取关于先前创建的预备语句的信息。 stmtName可以是""NULL来引用 - 未命名的语句,否则必须是现有准备好的语句的名称。成功时,返回一个 + 未命名的语句,否则必须是现有预备语句的名称。成功时,返回一个 状态为PGRES_COMMAND_OKPGresult。 函数可以应用于此 - PGresult以获取有关准备语句参数的信息, + PGresult以获取有关预备语句参数的信息, 函数等提供有关语句的结果列(如果有)的信息。 @@ -2841,22 +2781,21 @@ PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - 提交请求以获取有关指定门户的信息,并等待完成。 + 提交请求以获取有关指定 portal 的信息,并等待完成。 PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - 允许应用程序获取有关先前创建的portal的信息。 - (libpq不直接提供对portals的访问,但您可以使用此函数检查使用DECLARE CURSOR SQL命令创建的游标的属性。) - + 允许应用程序获取先前创建的 portal 的信息。(libpq 不提供对 portal 的直接访问,但可以用此函数检查通过 DECLARE CURSOR SQL 命令创建的游标的属性。) + - portalName可以是""NULL来引用未命名的portal, - 否则必须是现有portal的名称。成功时,将返回一个带有状态PGRES_COMMAND_OKPGresult。 + portalName可以是""NULL来引用未命名的 portal, + 否则必须是现有 portal 的名称。成功时,将返回一个带有状态PGRES_COMMAND_OKPGresult。 函数等可应用于 - PGresult,以获取有关portal的结果列(如果有)的信息。 + PGresult,以获取有关 portal 的结果列(如果有)的信息。 @@ -2873,11 +2812,11 @@ PGresult *PQclosePrepared(PGconn *conn, const char *stmtName); - 允许应用程序关闭先前准备好的预备语句。关闭语句会释放它在服务器上的全部相关资源,并允许重复使用其名称。 + 允许应用程序关闭先前创建的预备语句。关闭语句会释放它在服务器上的全部相关资源,并允许重复使用其名称。 - stmtName可以是""NULL来引用未命名语句。如果不存在该名称的语句也没有关系;在这种情况下,该操作不会执行任何操作。成功时,会返回一个状态为PGRES_COMMAND_OKPGresult。 + stmtName可以是""NULL来引用未命名语句。如果不存在该名称的语句也没有关系;在这种情况下,不执行任何操作。成功时,会返回一个状态为PGRES_COMMAND_OKPGresult @@ -2894,11 +2833,11 @@ PGresult *PQclosePortal(PGconn *conn, const char *portalName); - 允许应用程序关闭先前创建的 portal。关闭 portal 会释放它在服务器上的全部相关资源,并允许重复使用其名称。(libpq不直接提供对 portal 的访问,但你可以使用这个函数来关闭通过DECLARE CURSOR SQL 命令创建的游标。) + 允许应用程序关闭先前创建的 portal。关闭 portal 会释放它在服务器上的全部相关资源,并允许重复使用其名称。(libpq不直接提供对 portal 的访问,但你可以使用这个函数来关闭通过DECLARE CURSOR SQL 命令创建的游标。) - portalName可以是""NULL来引用未命名的 portal。如果不存在该名称的 portal 也没有关系;在这种情况下,该操作不会执行任何操作。成功时,会返回一个状态为PGRES_COMMAND_OKPGresult。 + portalName可以是""NULL来引用未命名的 portal。如果不存在该名称的 portal 也没有关系;在这种情况下,不执行任何操作。成功时,会返回一个状态为PGRES_COMMAND_OKPGresult @@ -2906,9 +2845,8 @@ PGresult *PQclosePortal(PGconn *conn, const char *portalName); - PGresultPGresult结构体封装了由服务器返回的结果。libpq应用程序员应该小心地维护PGresult的抽象。使用下面的存储器函数来得到PGresult的内容。避免直接引用PGresult结构体的域,因为它们可能在未来更改。 - - + PGresultPGresult 结构体封装服务器返回的结果。编写 libpq 应用程序时,应注意维护 PGresult 的抽象。请使用下述访问函数获取 PGresult 的内容。避免直接引用 PGresult 结构体的字段,因为这些字段将来可能改变。 + PQresultStatusPQresultStatus @@ -3009,7 +2947,7 @@ ExecStatusType PQresultStatus(const PGresult *res); PGRES_SINGLE_TUPLE - PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单一行模式时发生(见)。 + PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单行模式时发生(见)。 @@ -3057,12 +2995,11 @@ ExecStatusType PQresultStatus(const PGresult *res); - 将返回的枚举转换成描述状态编码的字符串常量。调用者不应该释放结果。 - + 将 返回的枚举值转换为描述该状态码的字符串常量。调用者不应释放此结果。 char *PQresStatus(ExecStatusType status); - + @@ -3071,12 +3008,12 @@ char *PQresStatus(ExecStatusType status); - 返回与该命令相关的错误消息,如果有错误则会返回一个空字符串。 + 返回与命令关联的错误消息;如果没有错误,则返回空字符串。 char *PQresultErrorMessage(const PGresult *res); - 如果有一个错误,被返回的字符串将包含一个收尾的新行。调用者不应该直接释放结果。它将在相关的PGresult句柄被传递给之后被释放。 - +如果发生了错误,返回的字符串会以换行符结尾。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 + 紧跟着一个调用,(在连接上)将返回与相同的字符串(在结果上)。 @@ -3092,16 +3029,14 @@ char *PQresultErrorMessage(const PGresult *res); - 返回与PGresult对象相关的错误消息的重新格式化的版本。 + 返回与 PGresult 对象关联的错误消息的重新格式化版本。 char *PQresultVerboseErrorMessage(const PGresult *res, PGVerbosity verbosity, PGContextVisibility show_context); - 在有些情况下,客户端可能希望得到之前报告过的错误的更加详尽的版本。 - 如果在产生给定PGresult的连接上 verbosity 设置有效,会通过计算已经被产生过的消息来满足这种需求。 - 如果PGresult不是一个错误结果,则会报告PG 结果不是错误结果。返回的字符串包括一个新行作为结尾。 - +有时客户端希望获取先前报告过的错误的更详细版本。 可满足这一需求:它按指定的详细程度设置重新生成消息。假如在生成给定 PGresult 时,连接已经采用这些设置,那么 返回的就会是这条消息。如果 PGresult 不是错误结果,则改为报告 PGresult is not an error result。返回的字符串以换行符结尾。 + 和大部分从PGresult中提取数据的其他函数不同,这个函数的结果是一个全新分配的字符串。调用者在不需要这个字符串以后,必须使用PQfreemem()释放它。 @@ -3117,24 +3052,21 @@ char *PQresultVerboseErrorMessage(const PGresult *res, PQresultErrorFieldPQresultErrorField - 返回一个错误报告的一个域。 + 返回错误报告中的单个字段。 char *PQresultErrorField(const PGresult *res, int fieldcode); - fieldcode是一个错误域标识符,见下列符号。 - 如果PGresult不是一个错误或者警告结果或者不包括指定域,会返回NULL。 - 域通常不包括一个收尾的新行。调用者不应该直接释放结果。 - 它将在相关的PGresult句柄被传递给之后被释放。 - +fieldcode 是错误字段标识符,参见下文列出的符号。如果 PGresult 不是错误或警告结果,或者不包含指定字段,则返回 NULL。字段值通常不含末尾换行符。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 + - 下列域代码可用: + 下列字段代码可用: PG_DIAG_SEVERITY - 严重性。域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 @@ -3143,17 +3075,17 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_SEVERITY_NONLOCALIZED - 域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY域相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 版本以后产生的报告中。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY字段相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 及更高版本产生的报告中。 PG_DIAG_SQLSTATEerror codeslibpq + >错误码libpq - 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个域无法被本地化,并且总是存在。 + 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个字段无法被本地化,并且总是存在。 @@ -3180,7 +3112,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_MESSAGE_HINT - 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是铁的事实。可能有多行。 + 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是确切事实。可能有多行。 @@ -3198,7 +3130,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_INTERNAL_POSITION - 这被定义为与PG_DIAG_STATEMENT_POSITION域相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个域出现时,PG_DIAG_INTERNAL_QUERY域将总是出现。 + 这被定义为与PG_DIAG_STATEMENT_POSITION字段相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个字段出现时,PG_DIAG_INTERNAL_QUERY字段将总是出现。 @@ -3216,7 +3148,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONTEXT - 指示错误发生的环境。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 + 指示错误发生的上下文。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 @@ -3234,7 +3166,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_TABLE_NAME - 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名域)。 + 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名字段)。 @@ -3243,7 +3175,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_COLUMN_NAME - 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名域来标识该表)。 + 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名字段来标识该表)。 @@ -3252,7 +3184,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_DATATYPE_NAME - 如果错误与一个特定数据类型相关,这里是该数据了行的名字(该数据类型的模式名参考模式名域)。 + 如果错误与一个特定数据类型相关,这里是该数据类型的名字(该数据类型的模式名参考模式名字段)。 @@ -3261,7 +3193,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONSTRAINT_NAME - 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的域(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 + 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的字段(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 @@ -3297,16 +3229,16 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); - 用于模式名、表名、列名、数据类型名和约束名的域只提供给有限的错误类型,见。不要假定任何这些域的存在保证另一个域的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些域。同样地,不要假定这些域代表当前数据库中同类的对象。 + 用于模式名、表名、列名、数据类型名和约束名的字段只提供给有限的错误类型,见。不要假定任何这些字段的存在保证另一个字段的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些字段。同样地,不要假定这些字段代表当前数据库中现存的对象。 - 客户端负责格式化显示信息来迎合它的需要,特别是根据需要打断长的行。出现在错误消息域中的新行字符应该被当作分段而不是换行。 + 客户端负责按自身需要格式化所显示的信息,尤其应在需要时将长行折行。错误消息字段中的换行符应当视为段落分隔,而非行分隔。 - libpq内部产生的错误将有严重和主要消息,但是通常没有其他域。 + libpq内部产生的错误将包含严重性和主要消息,但是通常没有其他字段。 @@ -3319,14 +3251,12 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PQclearPQclear - 释放与一个PGresult关联的存储。每个命令结果在不再需要时都应通过释放。 - + 释放与 PGresult 关联的存储空间。每个命令结果在不再需要时都应通过 释放。 void PQclear(PGresult *res); - - 如果参数是NULL指针,则不会执行任何操作。 - +如果参数是 NULL 指针,则不执行任何操作。 + 你可以在需要时一直保留PGresult对象;它不会在你发出新命令时消失,甚至在关闭连接后也不会消失。要销毁它,你必须调用。否则应用程序会发生内存泄漏。 @@ -3334,7 +3264,7 @@ void PQclear(PGresult *res); - + @@ -3342,8 +3272,8 @@ void PQclear(PGresult *res); 检索查询结果信息 - 这些函数被用来从一个代表成功查询结果(也就是状态为PGRES_TUPLES_OK或者PGRES_SINGLE_TUPLE)的PGresult对象中抽取信息。它们也可以被用来从一个成功的 Describe 操作中抽取信息:一个 Describe 的结果具有和该查询被实际执行所提供的完全相同的列信息,但是它没有行。对于其他状态值的对象,这些函数会认为结果具有零行和零列。 - + 这些函数用于从表示成功查询结果的 PGresult 对象中提取信息,即状态为 PGRES_TUPLES_OKPGRES_SINGLE_TUPLEPGRES_TUPLES_CHUNK 的对象。它们也可用于提取成功 Describe 操作的结果信息:Describe 结果包含的列信息与实际执行查询时相同,但行数为零。对于其他状态值的对象,这些函数会将结果视为零行、零列。 + @@ -3370,7 +3300,7 @@ int PQntuples(const PGresult *res); - 返回查询结果中每一行的列(域)数。 + 返回查询结果中每一行的列(字段)数。 int PQnfields(const PGresult *res); @@ -3386,7 +3316,7 @@ int PQnfields(const PGresult *res); - 返回与给定列号相关联的列名。列号从 0 开始。调用者不应该直接释放该结果。它将在相关的PGresult句柄被传递给之后被释放。 + 返回给定列号对应的列名。列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 char *PQfname(const PGresult *res, int column_number); @@ -3418,11 +3348,11 @@ int PQfnumber(const PGresult *res, - 给定的名称被视作一个 SQL 命令中的一个标识符,也就是说,除非被双引号引用,它是小写形式的。例如,给定一个 SQL 命令: + 给定名称按 SQL 命令中的标识符处理,即除非用双引号引用,否则会转换为小写。例如,对于以下 SQL 命令生成的查询结果: SELECT 1 AS FOO, 2 AS "BAR"; - 我们将得到结果: +会得到以下结果: PQfname(res, 0) foo PQfname(res, 1) BAR @@ -3442,7 +3372,7 @@ PQfnumber(res, "\"BAR\"") 1 - 返回给定列从中取出的表的 OID。列号从 0 开始。 + 返回给定列所取自的表的 OID。列号从 0 开始。 Oid PQftable(const PGresult *res, int column_number); @@ -3455,7 +3385,7 @@ Oid PQftable(const PGresult *res, - 当你包括libpq头文件,类型oid以及常数InvalidOid将被定义。它们将都是某种整数类型。 + 包含 libpq 头文件后,将定义类型 Oid 和常量 InvalidOid。它们都属于某种整数类型。 @@ -3467,7 +3397,7 @@ Oid PQftable(const PGresult *res, - 返回构成指定查询结果列的列(在其表中)的列号。查询结果列号从 0 开始,但是表列具有非零编号。 + 返回指定查询结果列所对应的表列在表中的列号。查询结果的列号从 0 开始,而表列的编号非零。 int PQftablecol(const PGresult *res, int column_number); @@ -3487,7 +3417,7 @@ int PQftablecol(const PGresult *res, - 返回指示给定列格式的格式编码。列号从 0 开始。 + 返回表示给定列格式的格式代码。列号从 0 开始。 int PQfformat(const PGresult *res, int column_number); @@ -3495,7 +3425,7 @@ int PQfformat(const PGresult *res, - 格式代码零指示文本数据表示,而格式代码一表示二进制表示(其他代码被保留用于未来的定义)。 + 格式代码零表示文本数据,格式代码一表示二进制数据。(其他代码保留供将来定义。) @@ -3515,7 +3445,7 @@ Oid PQftype(const PGresult *res, - 你可以查询系统表pg_type来得到多个数据类型的名字和属性。 + 你可以查询系统表pg_type来获取各种数据类型的名称和属性。 内置数据类型的OID被定义在PostgreSQL安装的include目录中的catalog/pg_type_d.h文件中。 @@ -3528,7 +3458,7 @@ Oid PQftype(const PGresult *res, - 返回与给定列号相关联的列的修饰符类型。列号从 0 开始。 + 返回与给定列号相关联的列的类型修饰符。列号从 0 开始。 int PQfmod(const PGresult *res, int column_number); @@ -3536,7 +3466,7 @@ int PQfmod(const PGresult *res, - 修饰符值的解释是与类型相关的,它们通常指示精度或尺寸限制。值 -1 被用来指示没有信息可用。大部分的数据类型不适用修饰符,在那种情况中值总是 -1。 + 修饰符值的含义由数据类型决定,通常表示精度或大小限制。值 -1 表示没有可用信息。大多数数据类型不使用修饰符,此时该值始终为 -1。 @@ -3548,7 +3478,7 @@ int PQfmod(const PGresult *res, - 返回与给定列号相关的列的尺寸(以字节计)。列号从 0 开始。 + 返回给定列号对应列的大小,以字节计。列号从 0 开始。 int PQfsize(const PGresult *res, int column_number); @@ -3556,7 +3486,7 @@ int PQfsize(const PGresult *res, - 返回在一个数据库行中为这个列分配的空间,换句话说是服务器对该数据类型的内部表示的尺寸(因此,它对客户端并不是真地非常有用)。一个负值指示该数据类型是变长的。 + 返回数据库行中为该列分配的空间,即服务器内部表示该数据类型所需的大小。(因此,它对客户端用处不大。)负值表示该数据类型是变长类型。 @@ -3575,8 +3505,7 @@ int PQbinaryTuples(const PGresult *res); - 这个函数已经被废弃(除了与COPY一起使用),因为一个单一PGresult可以在某些列中包含文本数据而且在另一些列中包含二进制数据。 - 要更好。只有结果的所有列是二进制(格式 1)时才返回 1。 + 此函数已弃用(与 COPY 配合使用的情况除外),因为单个 PGresult 可能在部分列中包含文本数据,而在其他列中包含二进制数据。推荐使用 。只有结果中的所有列都采用二进制格式(格式 1)时, 才返回 1。 @@ -3588,8 +3517,7 @@ int PQbinaryTuples(const PGresult *res); - 返回一个PGresult的一行的单一域值。行和列号从 0 开始。调用者不应该直接释放该结果。 - 它将在相关的PGresult句柄被传递给之后被释放。 + 返回 PGresult 中某一行的单个字段值。行号和列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 char *PQgetvalue(const PGresult *res, int row_number, @@ -3598,15 +3526,15 @@ char *PQgetvalue(const PGresult *res, - 对于文本格式的数据,返回的值是该域值的一种空值结束的字符串表示。对于二进制格式的数据,该值是由该数据类型的typsendtypreceive函数决定的二进制表示(在这种情况下该值实际上也跟随着一个零字节,但是这通常没有用处,因为该值很可能包含嵌入的空)。 + 对于文本格式的数据, 返回字段值的字符串表示,以零字节结尾。对于二进制格式的数据,返回值采用该数据类型的 typsendtypreceive 函数所决定的二进制表示。(这种情况下,值后面实际上也有一个零字节,但通常没有用处,因为值本身很可能包含零字节。) - 如果该域值为空,则返回一个空串。关于区分空值和空字符串值请见。 + 如果字段值为 null,则返回空字符串。关于如何区分 null 值与空字符串值,参见 - 返回的指针指向作为PGresult结构体一部分的存储。我们不应该修改它指向的数据,并且如果要在超过PGresult结构体本身的生命期之外使用它,我们必须显式地把该数据拷贝到其他存储中。 + 返回的指针指向属于 PGresult 结构体的存储空间。不应修改它所指向的数据;如果需要在 PGresult 结构体的生命周期结束后继续使用这些数据,就必须显式地将数据复制到其他存储空间。 @@ -3615,12 +3543,12 @@ char *PQgetvalue(const PGresult *res, PQgetisnullPQgetisnullnull valuein libpq + >null 值libpq 中的 - 测试一个域是否为空值。行号和列号从 0 开始。 + 检查字段是否为 null 值。行号和列号从 0 开始。 int PQgetisnull(const PGresult *res, int row_number, @@ -3629,7 +3557,7 @@ int PQgetisnull(const PGresult *res, - 如果该域是空,这个函数返回 1。如果它包含一个非空值,则返回 0(注意将为一个空域返回一个空串,不是一个空指针)。 + 如果字段为 null,此函数返回 1;如果包含非 null 值,则返回 0。(注意,对于 null 字段, 返回空字符串,而非空指针。) @@ -3641,7 +3569,7 @@ int PQgetisnull(const PGresult *res, - 返回一个域值的真实长度,以字节计。行号和列号从 0 开始。 + 返回字段值的实际长度,以字节计。行号和列号从 0 开始。 int PQgetlength(const PGresult *res, int row_number, @@ -3650,9 +3578,7 @@ int PQgetlength(const PGresult *res, - 这是特定数据值的真实数据长度,也就是指向的对象的尺寸。 - 对于文本数据格式,这和strlen()相同。对于二进制格式这是基本信息。 - 注意我们应该依赖于来得到真值的数据长度。 + 这是该数据值的实际数据长度,即 所指对象的大小。对于文本格式的数据,它与 strlen() 的结果相同。对于二进制格式,这是必不可少的信息。注意,不应依赖 来获取实际数据长度。 @@ -3671,7 +3597,7 @@ int PQnparams(const PGresult *res); - 只有在查看的结果时,这个函数才有用。对于其他类型的查询,它将返回零。 + 只有在查看的结果时,这个函数才有用。对于其他类型的结果,它将返回零。 @@ -3690,7 +3616,7 @@ Oid PQparamtype(const PGresult *res, int param_number); - 只有在查看的结果时,这个函数才有用。对于其他类型的查询,它将返回零。 + 只有在查看的结果时,这个函数才有用。对于其他类型的结果,它将返回零。 @@ -3702,29 +3628,29 @@ Oid PQparamtype(const PGresult *res, int param_number); - 将所有的行打印到指定的输出流,以及有选择地将列名打印到指定的输出流。 + 将所有行输出到指定的输出流,并可选择输出列名。 void PQprint(FILE *fout, /* 输出流 */ const PGresult *res, const PQprintOpt *po); typedef struct { - pqbool header; /* 打印输出域标题和行计数 */ - pqbool align; /* 填充对齐域 */ - pqbool standard; /* 旧的格式 */ + pqbool header; /* 打印输出字段标题和行数 */ + pqbool align; /* 填充并对齐字段 */ + pqbool standard; /* 旧的简陋格式 */ pqbool html3; /* 输出 HTML 表格 */ - pqbool expanded; /* 扩展表格 */ - pqbool pager; /* 如果必要为输出使用页 */ - char *fieldSep; /* 域分隔符 */ + pqbool expanded; /* 展开表格 */ + pqbool pager; /* 需要时使用分页器输出 */ + char *fieldSep; /* 字段分隔符 */ char *tableOpt; /* 用于 HTML 表格元素的属性 */ char *caption; /* HTML 表格标题 */ - char **fieldName; /* 替换域名称的空终止数组 */ + char **fieldName; /* 以空指针结尾的替换字段名数组 */ } PQprintOpt; - 这个函数以前被psql用来打印查询结果,但是现在不是这样了。注意它假定所有的数据都是文本格式。 + psql 以前用此函数打印查询结果,现在已不再使用。注意,此函数假定所有数据都是文本格式。 @@ -3773,13 +3699,7 @@ char *PQcmdTuples(PGresult *res); - 该函数返回一个字符串,其中包含由生成PGresultSQL语句影响的行数。 - 该函数只能在执行SELECTCREATE TABLE AS、 - INSERTUPDATEDELETE、 - MERGEMOVEFETCHCOPY语句, - 或包含INSERTUPDATEDELETEMERGE语句的预处理查询的EXECUTE之后使用。 - 如果生成PGresult的命令是其他任何命令,将返回一个空字符串。 - 调用者不应直接释放返回值。当关联的PGresult句柄传递给时,它将被释放。 + 此函数返回一个字符串,其中包含产生该 PGresultSQL 语句所影响的行数。此函数只能在执行 SELECTCREATE TABLE ASINSERTUPDATEDELETEMERGEMOVEFETCHCOPY 语句之后使用,也可以在对包含 INSERTUPDATEDELETEMERGE 语句的预备查询执行 EXECUTE 之后使用。如果产生 PGresult 的是其他命令, 将返回空字符串。调用者不应直接释放返回值;当关联的 PGresult 句柄被传给 时,返回值会被释放。 @@ -3791,7 +3711,7 @@ char *PQcmdTuples(PGresult *res); - 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDin libpq。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid。 + 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDlibpq 中的。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid Oid PQoidValue(const PGresult *res); @@ -3806,7 +3726,7 @@ Oid PQoidValue(const PGresult *res); - 这个函数已经被取代,并且不是线程安全的。它返回包含被插入行的 OID 的一个字符串,而返回 OID 值。 + 此函数不是线程安全的,现已弃用,推荐改用 。它返回包含插入行 OID 的字符串,而 返回 OID 值。 char *PQoidStatus(const PGresult *res); @@ -3824,7 +3744,7 @@ char *PQoidStatus(const PGresult *res); 转义字符串 - in libpq + libpq 中的 @@ -3842,17 +3762,13 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); 为了让一个字符串可用于 SQL 命令,会对它进行转义。 - 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜线)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 + 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜杠)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 执行这种操作。 - 返回一个str参数的已被转义版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - 返回字符串中的所有特殊字符都会被替换,这样它们就能被PostgreSQL字符串字面量解析器正确处理。 - 结果中也会附加一个终止零字节,并包含包围PostgreSQL字符串字面量所需的单引号。 - + 返回 str 参数的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便 PostgreSQL 字符串字面量解析器正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号包含在结果字符串中。 + 发生错误时,返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -3866,7 +3782,7 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); - 注意,当一个数据值被作为或其兄弟例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 + 注意,当一个数据值被作为或相关例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 @@ -3884,15 +3800,12 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - 转义一个要用作 SQL 标识符的字符串,例如表名、列名或函数名。当一个用户提供的标识符可能包含被 SQL 解析器解释为标识符一部分的特殊字符时,或者当该标识符可能包含大小写形式应该被保留的大写字符时,这个函数很有用。 - + 对字符串进行转义,使其可用作 SQL 标识符,例如表名、列名或函数名。当用户提供的标识符可能包含未经转义就不会被 SQL 解析器视为标识符一部分的特殊字符,或包含需要保留大小写的大写字符时,此函数很有用。 + - 返回一个str参数的已被转义为 SQL 标识符的版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - 返回串中的所有特殊字符都被替换掉,这样它们能被作为一个 SQL 标识符正确地处理。还会加上一个终止零字节。返回串也将被双引号包围。 - + 返回 str 参数作为 SQL 标识符的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,必须使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便正确地作为 SQL 标识符处理。还会添加一个末尾零字节,并用双引号包围返回的字符串。 + 发生错误时,返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -3901,7 +3814,7 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - 与字符串一样,要阻止 SQL 注入攻击,当从一个不可信的来源接收到 SQL 标识符时,它们必须被转义。 + 与字符串字面量一样,为防止 SQL 注入攻击,从不可信来源接收到的 SQL 标识符必须经过转义。 @@ -3922,18 +3835,12 @@ size_t PQescapeStringConn(PGconn *conn, - 转义字符串,它很像。 - 与不一样的是,调用者负责提供一个合适尺寸的缓冲区。 - 此外,不产生必须包围PostgreSQL字符串的单引号。 - 它们应该在结果要插入的 SQL 命令中提供。参数from指向要被转义的串的第一个字符,并且length参数给出了这个串中的字节数。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - to应当指向一个缓冲区,它能够保持至少比length值的两倍还要多至少一个字节,否则该行为是未被定义的。 - 如果tofrom串重叠,行为也是未被定义的。 - + 对字符串字面量进行转义,与 类似。与 不同,调用者需要提供大小合适的缓冲区。此外, 不会生成包围 PostgreSQL 字符串字面量所需的单引号;应在包含转义结果的 SQL 命令中提供这些引号。from 参数指向待转义字符串的首字符,length 参数给出该字符串的字节数。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)to 必须指向一个缓冲区,其容量至少为 length 的两倍加一个字节,否则行为未定义。如果 tofrom 字符串重叠,行为同样未定义。 + - 如果error参数不是NULL,那么成功时*error被设置为零,错误时设置为非零。当前唯一可能的错误情况涉及源串中非法的多字节编码。错误时仍然会产生输出串,但是可以预期服务器将认为它是畸形的并且拒绝它。在发生错误时,一个合适的消息被存储在conn对象中,不管error是不是NULL。 - + 如果 error 参数不是 NULL,则成功时将 *error 设为零,出错时设为非零。目前唯一可能的错误是源字符串中存在无效的多字节编码。出错时仍会生成输出字符串,但预计服务器会因其格式错误而拒绝它。发生错误时,无论 error 是否为 NULL,都会在 conn 对象中保存相应消息。 + 返回写到to的字节数,不包括终止的零字节。 @@ -3948,21 +3855,19 @@ size_t PQescapeStringConn(PGconn *conn, - 是一个更老的被废弃的版本。 + 的旧版本,现已弃用。 size_t PQescapeString (char *to, const char *from, size_t length); - + - 之间的唯一区别是不需要PGconnerror参数。 - 正因为如此,它不能基于连接属性(例如字符编码)调整它的行为并且因此它可能给出错误的结果。还有,它没有方法报告错误情况。 - + 与 唯一的区别是, 不接受 PGconnerror 参数。因此,它无法根据连接属性(例如字符编码)调整行为,可能给出错误的结果。此外,它也无法报告错误情况。 + - 可以在一次只使用一个PostgreSQL连接的客户端程序中安全地使用(在这种情况下它可以在现象后面找出它需要知道的东西)。 - 在其他环境中它是一个安全性灾难并且应该用来避免。 - + 可以在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。在其他情形下,它存在安全隐患,应改用 。 + @@ -3973,7 +3878,7 @@ size_t PQescapeString (char *to, const char *from, size_t length); - 把要用于一个 SQL 命令的二进制数据用类型bytea转义。和一样,只有在将数据直接插入到一个 SQL 命令串时才使用它。 + 对二进制数据进行转义,使其能够在 SQL 命令中用作 bytea 类型的值。与 一样,这仅用于将数据直接插入 SQL 命令字符串的情况。 unsigned char *PQescapeByteaConn(PGconn *conn, const unsigned char *from, @@ -3988,14 +3893,11 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - from参数指向要被转义的串的第一个字节,并且from_length参数给出这个二进制串中的字节数(一个终止的零字节是不需要的也是不被计算的)。to_length参数指向一个将保持生成的已转义串长度的变量。这个结果串长度包括结果的终止零字节。 + from 参数指向待转义字符串的首字节,from_length 参数给出该二进制字符串的字节数。(末尾零字节既不需要,也不计入长度。)to_length 参数指向用于保存转义后字符串长度的变量。该结果字符串长度包含结果末尾的零字节。 - 返回一个from参数的已被转义为二进制串的版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 返回串中的所有特殊字符都被替换掉,这样它们能被PostgreSQL的字符串解析器以及bytea输入函数正确地处理。 - 还会加上一个终止零字节。不是结果串一部分的PostgreSQL字符串必须被单引号包围。 + 返回 from 参数所指二进制字符串的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。返回字符串中的所有特殊字符都已替换,以便 PostgreSQL 字符串字面量解析器和 bytea 输入函数正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号不包含在结果字符串中。 @@ -4011,7 +3913,7 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - 是一个更老的被废弃的版本。 + 的旧版本,现已弃用。 unsigned char *PQescapeBytea(const unsigned char *from, size_t from_length, @@ -4020,9 +3922,7 @@ unsigned char *PQescapeBytea(const unsigned char *from, - 与的唯一区别是不用一个PGconn参数。 - 正因为这样,只能在一次只使用一个PostgreSQL连接的客户端程序中安全地使用(在这种情况下它可以在现象后面找出它需要知道的东西)。 - 如果在有多个数据库连接的程序中使用,它可能给出错误的结果(在那种情况下使用)。 + 与 唯一的区别是, 不接受 PGconn 参数。因此, 只能在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。如果在使用多个数据库连接的程序中使用,它可能给出错误的结果(此时应使用 )。 @@ -4094,25 +3994,15 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - 总是收集命令的整个结果,把它缓存在一个单一的PGresult中。虽然这简化了应用的错误处理逻辑,它对于包含很多行的结果并不现实。 - + 总是收集命令的完整结果,并将其缓存在单个 PGresult 中。这简化了应用程序的错误处理逻辑,但对于包含大量行的结果,可能不切实际。 + - 如果应用程序不希望受到这些限制,可以改用构成的底层函数:。此外,还有, - , - , - , - , - ,以及,它们可以与配合使用,分别实现以下函数的功能:, - , - , - , - , - ,以及。 - - + + 如果应用程序不希望受到这些限制,可以改用构成 的底层函数:。此外, 可以与 配合使用,分别实现 的功能。 + PQsendQueryPQsendQuery @@ -4120,14 +4010,11 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - 提交一个命令到服务器,而不等待结果。 - 如果成功发送命令,则返回1,如果失败则返回0(在这种情况下,使用获取更多关于失败的信息)。 + 向服务器提交命令,不等待结果。命令发送成功时返回 1,否则返回 0(此时可使用 获取更多失败信息)。 int PQsendQuery(PGconn *conn, const char *command); - - 成功调用后,调用一次或多次来获取结果。 - 在返回空指针,表示命令执行完成之前,无法再次调用(在同一连接上)。 +成功调用 后,应调用 一次或多次来获取结果。在 返回空指针、表明命令已完成之前,不得在同一连接上再次调用 @@ -4143,7 +4030,7 @@ int PQsendQuery(PGconn *conn, const char *command); - 提交一个命令和参数到服务器,而不等待结果。 + 向服务器提交命令及独立指定的参数,不等待结果。 int PQsendQueryParams(PGconn *conn, const char *command, @@ -4154,9 +4041,7 @@ int PQsendQueryParams(PGconn *conn, const int *paramFormats, int resultFormat); - - 这相当于,不同之处在于可以单独指定查询参数而不是与查询字符串一起指定。 - 函数的参数处理方式与完全相同。与一样,它在查询字符串中只允许一个命令。 +该函数等价于 ,但查询参数可以与查询字符串分开指定。函数参数的处理方式与 相同。与 一样,查询字符串中只允许包含一条命令。 @@ -4168,7 +4053,7 @@ int PQsendQueryParams(PGconn *conn, - 发送一个请求来创建一个带有给定参数的预备语句,而不等待完成。 + 发送按给定参数创建预备语句的请求,不等待完成。 int PQsendPrepare(PGconn *conn, const char *stmtName, @@ -4176,10 +4061,7 @@ int PQsendPrepare(PGconn *conn, int nParams, const Oid *paramTypes); - - 这是的异步版本:如果能够分派请求,则返回1,否则返回0。 - 成功调用后,调用来确定服务器是否成功创建了预备语句。 - 该函数的参数处理方式与完全相同。 +这是 的异步版本:请求发送成功时返回 1,否则返回 0。调用成功后,再调用 ,确定服务器是否成功创建了预备语句。函数参数的处理方式与 相同。 @@ -4191,7 +4073,7 @@ int PQsendPrepare(PGconn *conn, - 发送一个请求来执行一个准备好的语句,带有给定的参数,而不等待结果。 + 发送使用给定参数执行预备语句的请求,不等待结果。 int PQsendQueryPrepared(PGconn *conn, const char *stmtName, @@ -4201,9 +4083,7 @@ int PQsendQueryPrepared(PGconn *conn, const int *paramFormats, int resultFormat); - - 这类似于,但要执行的命令是通过指定一个之前准备好的语句的名称来指定,而不是提供一个查询字符串。 - 函数的参数处理方式与完全相同。 +该函数类似于 ,但通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。函数参数的处理方式与 相同。 @@ -4235,7 +4115,7 @@ int PQsendDescribePrepared(PGconn *conn, const char *stmtName); - 提交请求以获取有关指定门户的信息,而无需等待完成。 + 提交请求以获取有关指定 portal 的信息,而无需等待完成。 int PQsendDescribePortal(PGconn *conn, const char *portalName); @@ -4301,13 +4181,7 @@ PGresult *PQgetResult(PGconn *conn); - 必须重复调用直到返回空指针,表示命令已完成。 - (如果在没有活动命令时调用, - 将立即返回空指针。)每个非空结果从 - 应该使用先前描述的相同PGresult访问器函数进行处理。 - 完成后不要忘记使用释放每个结果对象。请注意, - 仅在有命令处于活动状态且必要的响应数据尚未被 - 读取时才会阻塞。 + 必须反复调用 ,直到它返回空指针,表明命令已经完成。(如果当前没有正在执行的命令,调用 会立即返回空指针。)对于 返回的非空指针,应使用前文介绍的 PGresult 访问函数处理相应结果。使用完毕后,不要忘记调用 释放每个结果对象。注意,只有存在正在执行的命令,且所需响应数据尚未被 读取时, 才会阻塞。 @@ -4330,41 +4204,37 @@ PGresult *PQgetResult(PGconn *conn); - + - 使用解决了的一个问题:如果一个命令字符串包含多个SQL命令,这些命令的结果可以被个别地获得(顺便说一句:这样就允许一种简单的重叠处理形式, 客户端可以处理一个命令的结果,而同时服务器可以继续处理同一命令字符串中后面的查询)。 - + 使用 可以解决 的一个问题:如果命令字符串包含多个 SQL 命令,就能分别获取这些命令的结果。(这也支持一种简单的重叠处理方式:客户端可以处理某条命令的结果,同时服务器继续处理同一命令字符串中后面的查询。) + - 可以被获得的另一种常常想要的特性是一次从大型结果中检索一行。这会在中讨论。 - + 使用 还可以实现另一项常见需求:从大型查询结果中一次读取有限行数。详见 。 + - 就其本身而言,调用将仍会导致客户端阻塞,直到服务器完成下一个SQL命令。可以通过正确使用两个函数来避免这种情况: - - + 仅仅调用 仍会使客户端阻塞,直到服务器完成下一条 SQL 命令。可以通过正确使用另外两个函数来避免这种情况: + PQconsumeInputPQconsumeInput - 如果有来自服务器的输入可用,则使用之。 + 如果服务器有可读取的输入,则读取这些输入。 int PQconsumeInput(PGconn *conn); - 通常返回 1 表明没有错误,而返回 0 表明有某种麻烦发生(此时可以用)。 - 注意该结果并不表明是否真正收集了任何输入数据。在调用之后,应用可以检查和/或PQnotifies来看看它们的状态是否改变。 + 通常返回 1,表示没有错误;发生问题时则返回 0(此时可查看 )。注意,返回值并不说明是否实际读取了输入数据。调用 后,应用程序可以检查 和/或 PQnotifies,以确定其状态是否发生变化。 - 即使应用还不准备处理一个结果或通知,也可以被调用。 - 这个函数将读取可用的数 据并且把它保存在一个缓冲区中,从而导致一个select()的读准备好指示消失。 - 因此应用可以使用立即清除select()条件,并且在空闲时再检查结果。 + 即使应用程序尚未准备好处理结果或通知,也可以调用 。此函数会读取可用数据并将其保存在缓冲区中,从而清除 select() 的可读就绪指示。因此,应用程序可以用 立即清除 select() 的就绪条件,随后在合适的时候检查结果。 @@ -4386,15 +4256,11 @@ int PQisBusy(PGconn *conn); - + - 一个使用这些函数的典型应用将有一个主循环,在主循环中会使用select()poll()等待所有它必须响应的情况。 - 其中之一将是来自服务器的输入可用,对select()来说意味着标识的文件描述符上有可读的数据。 - 当主循环检测到输入准备好时,它将调用读取输入。 - 然后它可以调用,如果返回假(0)则接着调用。 - 它还可以调用PQnotifies检测NOTIFY消息(见)。 - + 使用这些函数的典型应用程序会在主循环中通过 select()poll() 等待需要响应的各种条件。其中一个条件是服务器有可读取的输入;对于 select(),这意味着 标识的文件描述符上有可读数据。主循环检测到输入就绪时,应调用 读取输入,然后调用 。如果 返回假(0),就可以接着调用 。还可以调用 PQnotifies 检测 NOTIFY 消息(见 )。 + 一个使用/的客户端也可以尝试取消一个正在被服务器处理的命令,见。 @@ -4402,13 +4268,8 @@ int PQisBusy(PGconn *conn); - 通过使用上面描述的函数,可以避免在等待来自数据库服务器的输入时阻塞。 - 然而,应用程序仍然可能会在等待向服务器发送输出时阻塞。 - 这在发送非常长的SQL命令或数据值时可能会发生,尽管这相对不常见。 - (如果应用程序通过COPY IN发送数据,则更有可能发生。) - 为了防止这种可能性并实现完全非阻塞的数据库操作,可以使用以下附加函数。 - - + 使用上述函数可以避免在等待数据库服务器输入时阻塞。不过,应用程序仍可能在等待向服务器发送输出时阻塞。这种情况较少见,但发送很长的 SQL 命令或数据值时可能发生。(如果应用程序通过 COPY IN 发送数据,发生的可能性则大得多。)为了防止这种情况,实现完全非阻塞的数据库操作,可以使用以下附加函数。 + PQsetnonblockingPQsetnonblocking @@ -4426,11 +4287,7 @@ int PQsetnonblocking(PGconn *conn, int arg); - 在非阻塞状态下,成功调用、 - 、 - 不会阻塞; - 它们的更改将存储在本地输出缓冲区中,直到刷新为止。 - 不成功的调用将返回错误,必须重试。 + 在非阻塞状态下,成功调用 不会阻塞;产生的数据保存在本地输出缓冲区中,等待发送。失败的调用会返回错误,必须重试。 @@ -4461,9 +4318,7 @@ int PQisnonblocking(const PGconn *conn); - 尝试将任何排队的输出数据刷新到服务器。如果成功(或发送队列为空),则返回0; - 如果由于某种原因失败,则返回-1;如果尚未能够发送发送队列中的所有数据(只有在连接为非阻塞时才会发生此情况), - 则返回1。 + 尝试将发送队列中的输出数据发送到服务器。成功(或发送队列为空)时返回 0;因某种原因失败时返回 -1;如果尚未能发送队列中的全部数据,则返回 1(这种情况只可能发生在非阻塞连接上)。 int PQflush(PGconn *conn); @@ -4471,15 +4326,11 @@ int PQflush(PGconn *conn); - + - 在一个非阻塞连接上发送任何命令或者数据之后,要调用。 - 如果它返回 1,就要等待套接字变成读准备好或写准备好。如果它变为写准备好,应再次调用。 - 如果它变为读准备好,则应先调用,然后再调用。 - 一直重复直到返回 0(有必要检查读准备好并且用耗尽输入,因为服务器可能阻塞给我们发送数据的尝试,例如 NOTICE 消息,并且在我们读它的数据之前它都不会读我们的数据)。 - 一旦返回 0,应等待套接字变成读准备好并且接着按照上文所述读取响应。 - + 在非阻塞连接上发送命令或数据后,应调用 。如果返回 1,就等待套接字变为可读或可写。套接字可写时,再次调用 ;可读时,先调用 ,再调用 。重复上述步骤,直到 返回 0。(必须检查套接字是否可读,并用 读完输入,因为服务器可能在尝试向客户端发送数据时阻塞,例如发送 NOTICE 消息;在客户端读取这些数据之前,服务器不会读取客户端发送的数据。)当 返回 0 后,等待套接字变为可读,再按前述方法读取响应。 + @@ -4493,29 +4344,26 @@ int PQflush(PGconn *conn); - pipelining - in libpq + 管道化 + 在 libpq 中 - batch mode - in libpq + 批处理模式 + 在 libpq 中 - libpq 管道模式允许应用发送查询而无需读取先前发送查询的结果。 - 利用管道模式的优点,客户端将对服务器等待的更少,因为可以在单个网络事务中发送/接收多个查询/结果。 - + libpq 的管道模式允许应用程序在尚未读取先前查询结果时继续发送查询。多个查询及其结果可以在一次网络交互中发送和接收,从而减少客户端等待服务器的时间。 + - 虽然管道模式提供了显著的性能提升, - 使用管道模式写客户端会更加复杂,因为它涉及到管理一个挂起查询的队列,并查找队列中的哪个结果对应于哪个查询。 - + 管道模式可以显著提升性能,但使用它编写客户端也更复杂,因为需要管理待处理查询队列,并确定每个结果对应队列中的哪个查询。 + - 管道模式通常也会在客户端和服务器上面消耗更多的内存,尽管仔细和积极地管理发送/接收队列可以减轻这种消耗。 - 这适用于连接是否处于阻塞或非阻塞模式。 - + 管道模式通常也会增加客户端和服务器的内存消耗,不过仔细、主动地管理发送和接收队列可以缓解这一问题。无论连接处于阻塞还是非阻塞模式,都是如此。 + 虽然libpq的管道API是在PostgreSQL 14中引入的, @@ -4528,24 +4376,8 @@ int PQflush(PGconn *conn); 使用管道模式 - 要发出管道命令,应用程序必须将连接切换到管道模式, - 可以通过来完成。 - 可以使用来测试管道模式是否激活。 - 在管道模式下,只允许使用扩展查询协议的异步操作, - 不允许包含多个SQL命令的命令字符串,也不允许使用COPY命令。 - 使用同步命令执行函数,如PQfn、 - PQexec、 - PQexecParams、 - PQprepare、 - PQexecPrepared、 - PQdescribePrepared、 - PQdescribePortal, - 都会导致错误。 - 也不允许使用PQsendQuery,因为它使用简单查询协议。 - 一旦所有已分派的命令的结果已被处理,并且 - 结束管道结果已被消耗,应用程序可以通过返回 - 到非管道模式。 - + 要使用管道,应用程序必须通过 将连接切换到管道模式。可用 检查管道模式是否已启用。在管道模式下,只允许使用扩展查询协议的异步操作,不允许命令字符串包含多个 SQL 命令,也不允许 COPY。调用同步命令执行函数,例如 PQfnPQexecPQexecParamsPQpreparePQexecPreparedPQdescribePreparedPQdescribePortalPQclosePreparedPQclosePortal,会导致错误。也不允许使用 PQsendQuery,因为它使用简单查询协议。所有已发送命令的结果及管道结束结果都读取处理完毕后,应用程序便可通过 返回非管道模式。 + @@ -4554,9 +4386,8 @@ int PQflush(PGconn *conn); 如果在阻塞模式下使用,它可能发生客户端/服务器死锁。 - 客户端将阻止尝试发送查询到服务器,但服务器将阻止从它已经处理的查询向客户端发送结果。 - 这只有当客户端在它切换到处理从服务器的输入之前发送足够的查询来填充其输出缓冲区和服务器的接收缓冲区,才会发生这种情况,但很难准确预测何时将发生。 - + 客户端在尝试向服务器发送查询时阻塞,而服务器在尝试将已处理查询的结果发送给客户端时阻塞。只有当客户端在转而处理服务器输入之前,发送了足够多的查询,填满自身的输出缓冲区和服务器的接收缓冲区,才会发生这种情况;但很难准确预测何时会发生。 + @@ -4593,8 +4424,8 @@ int PQflush(PGconn *conn); - PQisBusyPQconsumeInput 等函数在处理管道结果时照常工作。特别地,在管道处理过程中调用 PQisBusy 时,如果到目前为止已发出查询的所有结果均已被消费,则返回 0。 - + PQisBusyPQconsumeInput 等函数在处理管道结果时照常工作。特别地,在管道处理过程中调用 PQisBusy 时,如果到目前为止已发出查询的所有结果均已被读取,则返回 0。 + libpq 不向应用程序提供当前正在处理哪个查询的信息(除了 PQgetResult 返回空指针,表示开始返回下一个查询的结果)。应用程序必须跟踪查询的发送顺序,以便将查询与对应结果关联起来。应用程序通常会使用状态机或 FIFO 队列实现这一点。 @@ -4607,21 +4438,16 @@ int PQflush(PGconn *conn); 错误处理 - 从客户端的视角,在PQresultStatus返回PGRES_FATAL_ERROR之后,管道被标记为中止。 - PQresultStatus将报告一个PGRES_PIPELINE_ABORTED结果,对中止的管道中的每一个剩余的排队操作。 - PQpipelineSync的结果报告为PGRES_PIPELINE_SYNC,以表示中止管道的结束并恢复正常的结果处理。 - + 从客户端的角度看,PQresultStatus 返回 PGRES_FATAL_ERROR 后,管道就会被标记为中止。对于已中止管道中剩余的每个排队操作,PQresultStatus 都会报告一个 PGRES_PIPELINE_ABORTED 结果。PQpipelineSyncPQsendPipelineSync 的结果报告为 PGRES_PIPELINE_SYNC,表示已中止的管道结束,并恢复正常的结果处理。 + 在错误恢复时,客户端必须 使用 PQgetResult处理结果。 - 如果管道使用隐式事务,那么已经执行的操作将被回滚,而排队跟在失败操作的操作将被完全跳过。 - 同样的行为也会发生,如果管道开始并提交单个显式事务(也就是,第一个语句是BEGIN ,最后一个是COMMIT),除非会话在管道结束时保持在中止事务状态。 - 如果管道包含多个显式事务,所有在错误发生前已提交的事务都会继续保留,当前正在进行的事务会被中止,所有后续操作都会被完全跳过,包括后续事务在内。 - 如果管道同步点发生时显式事务块为中止状态,则下一个管道将立即中止,除非下一个命令使用ROLLBACK将事务置于正常模式。 - + 如果管道使用隐式事务,已经执行的操作会被回滚,而失败操作之后排队的操作会全部跳过。如果管道开始并提交单个显式事务(即第一条语句为 BEGIN,最后一条为 COMMIT),行为也相同,不过在管道结束时,会话仍处于事务中止状态。如果管道包含多个显式事务,错误发生前已经提交的事务仍保持已提交状态,当前正在进行的事务会中止,所有后续操作都会被跳过,包括后续事务。如果到达管道同步点时,显式事务块仍处于中止状态,下一个管道会立即中止,除非下一条命令使用 ROLLBACK 将事务恢复为正常状态。 + @@ -4634,24 +4460,19 @@ int PQflush(PGconn *conn); - 交叉结果处理和查询分派 + 交错处理结果与发送查询 - 为避免大型管道上的死锁,客户端将被围绕非阻塞事件循环构建,通过使用操作系统工具,如select, poll, WaitForMultipleObjectEx等等, - + 为避免大型管道发生死锁,客户端应围绕非阻塞事件循环组织,使用 selectpollWaitForMultipleObjectEx 等操作系统机制。 + - 客户端应用通常应该维护一个尚未分派的工作队列和一个已分派但尚未处理结果的工作队列。 - 当套接字是可写时,它将可以分派更多的工作。 - 当套接字是可读时,它将读取结果并处理它们,将它们匹配到相应结果队列中的下一个条目。 - 基于可用内存,来自套接字的结果将被经常读取:这里不需要等到管道结束才读取结果。 - 管道将范围涵盖到工作的逻辑单元,通常(但不是必然)每个管道一个事务。 - 在管道之间,不需要退出管道模式再重新进入管道模式,也不需要等待一个管道结束后再发送下一个。 - + 客户端应用程序通常应维护两个队列:一个存放尚未发送的工作,另一个存放已经发送但尚未处理结果的工作。套接字可写时,应继续发送工作;套接字可读时,应读取并处理结果,将其与相应结果队列中的下一个条目匹配。应根据可用内存情况,频繁地从套接字读取结果,无需等到管道结束。每个管道应对应一个逻辑工作单元,通常是一个事务,但并非必须如此。管道之间无需退出再重新进入管道模式,也无需等待一个管道完成后才发送下一个。 + - 一个使用select()和一个简单状态机来跟踪发送和接收工作的示例,在PostgreSQL源代码发行版的src/test/modules/libpq_pipeline/libpq_pipeline.c文件中。 - + PostgreSQL 源代码发行版的 src/test/modules/libpq_pipeline/libpq_pipeline.c 中提供了一个示例,使用 select() 和简单状态机跟踪已发送和已接收的工作。 + @@ -4695,7 +4516,7 @@ PGpipelineStatus PQpipelineStatus(const PGconn *conn); - libpq 连接 是管道模式。 + libpq 连接处于管道模式。 @@ -4724,18 +4545,14 @@ PGpipelineStatus PQpipelineStatus(const PGconn *conn); - 造成连接进入管道模式,如果它当前空闲或已经是管道模式。 - + 如果连接当前空闲或已处于管道模式,则使该连接进入管道模式。 int PQenterPipelineMode(PGconn *conn); - - 成功返回1. - 如果连接当前不是空闲的,返回0并且无影响,也就是说,它已经有了一个结果,或者它正在等待服务器的更多输入,等等。 - 这个函数实际上不向服务器发送任何东西,它只是更改libpq连接状态。 + 成功时返回 1。如果连接当前不空闲,例如已有结果可供读取,或正在等待服务器的更多输入,则返回 0,且不产生任何影响。此函数实际上不向服务器发送任何内容,只改变 libpq 的连接状态。 @@ -4747,16 +4564,14 @@ int PQenterPipelineMode(PGconn *conn); - 造成连接退出管道模式,如果连接当前以空队列处于管道模式,并且没有待处理的结果。 + 如果连接当前处于管道模式、队列为空且没有待读取的结果,则使该连接退出管道模式。 int PQexitPipelineMode(PGconn *conn); - 成功则返回1。 - 如果不是管道模式,则返回1并且不采取操作。 - 如果当前语句没有完成处理,或者PQgetResult尚未被调用以收集所有先前发送查询的结果,则返回0(在这种情况下,使用以获取关于故障的更多信息)。 + 成功时返回 1。如果连接不处于管道模式,也返回 1,且不执行任何操作。如果当前语句尚未处理完毕,或尚未调用 PQgetResult 读取先前发送的所有查询的结果,则返回 0(此时可使用 获取更多失败信息)。 @@ -4768,17 +4583,14 @@ int PQexitPipelineMode(PGconn *conn); - 通过发送sync message并刷新发送缓冲区的方式来标记管道中的同步点。 - 它用作隐式事务的定界符和错误恢复点;参见。 - + 通过发送同步消息并将发送缓冲区中的数据发往服务器,在管道中标记同步点。同步点作为隐式事务的分界符和错误恢复点;见 int PQpipelineSync(PGconn *conn); - 成功就返回1。 - 如果连接不是管道模式或者发送sync message失败,则返回0。 + 成功时返回 1。如果连接不处于管道模式,或发送同步消息失败,则返回 0。 @@ -4788,14 +4600,13 @@ int PQpipelineSync(PGconn *conn); - 通过发送sync message但不刷新发送缓冲区,来标记管道中的一个同步点。它可作为隐式事务的分界符和错误恢复点;参见。 - + 通过发送同步消息在管道中标记同步点,但不刷新发送缓冲区。同步点作为隐式事务的分界符和错误恢复点;见 int PQsendPipelineSync(PGconn *conn); - 成功时返回 1。如果连接不处于管道模式,或者发送sync message失败,则返回 0。请注意,该消息本身不会自动刷新到服务器;必要时请使用PQflush。 + 成功时返回 1。如果连接不处于管道模式,或发送同步消息失败,则返回 0。注意,该消息本身不会自动发送到服务器;必要时可使用 PQflush @@ -4807,21 +4618,19 @@ int PQsendPipelineSync(PGconn *conn); - 发送一个请求到服务器以刷新它的输出缓冲区。 + 请求服务器发送其输出缓冲区中的数据。 int PQsendFlushRequest(PGconn *conn); - + - 成功就返回1。 - 任何失败则返回0。 - + 成功时返回 1;发生任何失败时返回 0。 + - 当PQpipelineSync被调用的结果,或者在非管道模式下的任何请求时,服务器自动刷新它的输出缓冲区;这个函数用于使得服务器在不建立同步点的情况下以管道模式刷新其输出缓冲区。 - 请注意,请求不是自身能自动刷新到服务器;如果需要时使用PQflush。 - + 调用 PQpipelineSync 后,或者在非管道模式下收到任何请求时,服务器都会自动发送其输出缓冲区中的数据。此函数可让服务器在管道模式下发送输出缓冲区中的数据,而不建立同步点。注意,该请求本身不会自动发送到服务器;必要时可使用 PQflush。 + @@ -4832,43 +4641,36 @@ int PQsendFlushRequest(PGconn *conn); 何时使用管道模式 - 非常像异步查询模式,在使用管道模式时没有明显的性能开销。 - 它增加了客户端应用的复杂性,并且需要特别注意以防止客户端/服务器死锁。 - 但是管道模式可以提供相当大的性能改进,代价是因为状态保留更久而增加内存使用。 - + 与异步查询模式类似,使用管道模式不会带来明显的性能开销。它增加了客户端应用程序的复杂性,需要格外注意防止客户端与服务器之间的死锁,但也能显著提升性能,代价是状态保留更久,因而占用更多内存。 + - 当服务器比较远,即网络延迟(ping time)高的时候,管道模式最有用,以及在许多小操作正在快速连续执行的时候。 - 当每个查询的执行时间是客户端/服务器往返时间的许多倍时,使用管道命令的优势通常会更少。 - 不用管道模式,在往返时间为300毫秒的服务器上运行一个100条语句的操作,仅网络延迟就需要30秒;使用管道,等待来自服务器的结果可能只消耗仅仅0.3秒。 - + 当服务器距离较远,即网络延迟(ping 时间)较高,或者需要快速连续执行许多小操作时,管道模式最有用。如果每个查询的执行时间是客户端与服务器往返时间的许多倍,使用管道命令的收益通常较小。在往返时间为 300 毫秒的服务器上执行一个包含 100 条语句的操作,不使用管道时,仅网络延迟就需要 30 秒;使用管道时,等待服务器结果的时间可能低至 0.3 秒。 + - 当你的应用需要完成很多小的INSERT, UPDATEDELETE 操作,并且不能方便的转换到集合操作或者 COPY操作时,用管道命令。 - + 如果应用程序需要执行大量小型 INSERTUPDATEDELETE 操作,而这些操作又难以转换为集合操作或 COPY 操作,就可以使用管道命令。 + - 当来自一个操作的信息需要客户端产生下一个操作时,管道模式是没有用的。 - 在这种情况下,客户机将不得不引入一个同步点,并等待完整的客户端/服务器往返以获取它需要的结果。 - 但是,通常可以调整客户端设计以交换服务器端所需的信息。 - 读-修改-写循环是非常好的选择;例如: + 如果客户端必须获得前一个操作的信息,才能生成下一个操作,管道模式就没有帮助。在这种情况下,客户端必须引入同步点,并等待一次完整的客户端与服务器往返,才能获得所需结果。不过,通常可以调整客户端设计,让所需信息在服务器端交换。读取、修改、写入的循环尤其适合这样改进。例如: BEGIN; SELECT x FROM mytable WHERE id = 42 FOR UPDATE; --- result: x=2 --- client adds 1 to x: +-- 结果:x=2 +-- 客户端将 x 加 1: UPDATE mytable SET x = 3 WHERE id = 42; COMMIT; - 可以更有效地开展以下工作: +可以改写为以下效率更高的操作: UPDATE mytable SET x = x + 1 WHERE id = 42; - + - 当单个管道包含多个事务时,管道的作用更小,而且更复杂(参见)。 - + 当单个管道包含多个事务时,使用管道的收益较小,复杂度也更高(见 )。 + @@ -4890,7 +4692,7 @@ UPDATE mytable SET x = x + 1 WHERE id = 42; - 要进入这些模式之一,请在成功调用(或其兄弟函数)后立即调用。这种模式选择只对当前正在执行的查询生效。然后按所述,反复调用直到其返回空指针。如果查询返回了任何行,这些行会作为一个或多个PGresult对象返回。它们看起来与普通查询结果相同,只是状态码在单行模式下为PGRES_SINGLE_TUPLE,在分块模式下为PGRES_TUPLES_CHUNK,而不是PGRES_TUPLES_OK。每个PGRES_SINGLE_TUPLE对象恰好包含一行结果,而PGRES_TUPLES_CHUNK对象至少包含一行、至多包含指定的每块行数。最后一行之后,或者如果查询返回零行,则会返回一个状态为PGRES_TUPLES_OK且不含行的对象,表示不会再有更多行到达。(但请注意,仍然必须继续调用直到其返回空指针。)所有这些PGresult对象都会包含与普通查询结果相同的行描述数据(列名、类型等)。每个对象在使用完之后都应像往常一样通过释放。 + 要进入这些模式之一,请在成功调用(或其同类函数)后立即调用。这种模式选择只对当前正在执行的查询生效。然后按所述,反复调用直到其返回空指针。如果查询返回了任何行,这些行会作为一个或多个PGresult对象返回。它们看起来与普通查询结果相同,只是状态码在单行模式下为PGRES_SINGLE_TUPLE,在分块模式下为PGRES_TUPLES_CHUNK,而不是PGRES_TUPLES_OK。每个PGRES_SINGLE_TUPLE对象恰好包含一行结果,而PGRES_TUPLES_CHUNK对象至少包含一行、至多包含指定的每块行数。最后一行之后,会返回一个状态为PGRES_TUPLES_OK且不含行的对象;如果查询返回零行,则立即返回该对象。这表示不会再有更多行到达。(但请注意,仍然必须继续调用直到其返回空指针。)所有这些PGresult对象都会包含与该查询的普通PGresult对象相同的行描述数据(列名、类型等)。每个对象在使用完之后都应像往常一样通过释放。 @@ -4912,7 +4714,7 @@ int PQsetSingleRowMode(PGconn *conn); - 此函数只能在调用或其某个兄弟函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活单行模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 + 此函数只能在调用或其某个同类函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活单行模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 @@ -4930,7 +4732,7 @@ int PQsetChunkedRowsMode(PGconn *conn, int chunkSize); - 该函数与类似,不同之处在于它指定每个PGresult最多返回chunkSize行,而不一定只返回一行。此函数也只能在调用或其某个兄弟函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活分块模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 + 该函数与类似,不同之处在于它指定每个PGresult最多返回chunkSize行,而不一定只返回一行。此函数也只能在调用或其某个同类函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活分块模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 @@ -4949,10 +4751,10 @@ int PQsetChunkedRowsMode(PGconn *conn, int chunkSize); 取消进行中的查询 - canceling SQL queries + 取消 SQL 查询 - query cancellation + 查询取消 @@ -4970,7 +4772,7 @@ PGcancelConn *PQcancelCreate(PGconn *conn); - 创建一个PGcancelConnPGcancelConn对象,但不会立即通过这条连接发送取消请求。可以使用以阻塞方式发送取消请求,或者使用以非阻塞方式发送。返回值可以传给,以检查该PGcancelConn对象是否成功创建。PGcancelConn是不透明结构体,不应由应用程序直接访问。它可用于以线程安全的方式取消原始连接上正在执行的查询。 + 创建一个PGcancelConnPGcancelConn对象,但不会立即通过这条连接发送取消请求。可以使用以阻塞方式发送取消请求,或者使用以非阻塞方式发送。返回值可以传给,以检查该PGcancelConn对象是否成功创建。PGcancelConn是不透明结构体,不应由应用程序直接访问。这个PGcancelConn对象可用于以线程安全的方式取消原始连接上正在执行的查询。 @@ -5023,7 +4825,7 @@ PostgresPollingStatusType PQcancelPoll(PGcancelConn *cancelConn); - 如果PQcancelStart成功,下一阶段就是轮询libpq,使其继续推进取消连接序列。使用获取底层套接字描述符。(注意:不要假定该套接字在多次调用PQcancelPoll之间保持不变。)循环规则如下:如果PQcancelPoll(cancelConn)上一次返回PGRES_POLLING_READING,就等待该套接字准备好可读(由select()poll()或类似系统函数指示),然后再次调用PQcancelPoll(cancelConn)。反之,如果其上一次返回PGRES_POLLING_WRITING,就等待套接字准备好可写,然后再次调用。第一次迭代时,也就是尚未调用过PQcancelPoll(cancelConn)时,按其上次返回PGRES_POLLING_WRITING来处理。持续这一循环,直到PQcancelPoll(cancelConn)返回PGRES_POLLING_FAILED,表示连接过程失败,或者返回PGRES_POLLING_OK,表示取消请求已成功分派。 + 如果PQcancelStart成功,下一阶段就是轮询libpq,使其继续进行取消连接的建立过程。使用获取数据库连接底层套接字的描述符。(注意:不要假定该套接字在多次调用PQcancelPoll之间保持不变。)循环规则如下:如果PQcancelPoll(cancelConn)上一次返回PGRES_POLLING_READING,就等待该套接字准备好可读(由select()poll()或类似系统函数指示),然后再次调用PQcancelPoll(cancelConn)。反之,如果PQcancelPoll(cancelConn)上一次返回PGRES_POLLING_WRITING,就等待套接字准备好可写,然后再次调用PQcancelPoll(cancelConn)。第一次迭代时,也就是尚未调用过PQcancelPoll(cancelConn)时,按其上次返回PGRES_POLLING_WRITING来处理。持续这一循环,直到PQcancelPoll(cancelConn)返回PGRES_POLLING_FAILED,表示连接过程失败,或者返回PGRES_POLLING_OK,表示取消请求已成功分派。 @@ -5089,7 +4891,7 @@ PostgresPollingStatusType PQcancelPoll(PGcancelConn *cancelConn); - 请注意,尽管这些常量会继续保留(为了保持兼容性),应用程序也绝不应依赖它们按某个特定顺序出现,甚至不应依赖它们一定会出现,或者依赖状态值始终属于这些已记录的取值之一。应用程序可以这样写: + 请注意,尽管这些常量会继续保留(为了保持兼容性),应用程序也绝不应依赖它们按某个特定顺序出现,甚至不应依赖它们一定会出现,或者依赖状态值始终属于本节列出的取值之一。应用程序可以这样写: switch(PQcancelStatus(conn)) { @@ -5160,7 +4962,7 @@ int PQcancelSocket(const PGcancelConn *cancelConn); PQcancelErrorMessagePQcancelErrorMessage - error messagein PGcancelConn + 错误消息PGcancelConn @@ -5219,8 +5021,8 @@ void PQcancelReset(PGcancelConn *cancelConn); 发送取消请求的过时函数 - 这些函数代表较旧的取消请求发送方式。虽然它们仍然可以工作,但由于即使原始连接通过sslmodegssencmode要求加密,它们发送取消请求时也不会以加密方式进行,因此已被废弃。因此,强烈不建议在新代码中继续使用这些旧方法,已有代码也建议迁移到新的函数。 - + 这些函数使用较旧的方式发送取消请求。即使原始连接通过 sslmodegssencmode 要求加密,它们也不会加密取消请求,因此虽然仍可使用,却已被弃用。强烈不建议在新代码中使用这些旧方法,也建议将现有代码改为使用新函数。 + @@ -5316,7 +5118,7 @@ int PQrequestCancel(PGconn *conn); 快速路径接口 - fast path + 快速路径 @@ -5326,8 +5128,8 @@ int PQrequestCancel(PGconn *conn); - 这个接口不安全,不应使用。当result_is_int被设置为0时,PQfn可能会在result_buf末尾之外写入数据,而不管缓冲区是否有足够空间容纳所请求的字节数。此外,它已经废弃,因为可以通过创建一个定义该函数调用的预备语句来达到类似的性能并获得更强大的功能。然后,用参数和结果的二进制传输执行该语句,从而取代快速路径函数调用。 - + 此接口不安全,不应使用。当 result_is_int 设为 0 时,PQfn 可能越过 result_buf 的末尾写入数据,无论缓冲区是否有足够空间容纳请求的字节数。此外,此接口已经过时:可以通过创建预备语句来定义函数调用,获得相近的性能和更强的功能;再以二进制形式传输参数和结果来执行该语句,即可替代快速路径函数调用。 + @@ -5355,27 +5157,24 @@ typedef struct - fnid参数是要被执行的函数的 OID。argsnargs定义了要传递给函数的参数;它们必须匹配已声明的函数参数列表。当一个参数结构体的isint域为真时,u.integer值被以指定长度(必须是 1、2 或者 4 字节)整数的形式发送给服务器;这时候会发生恰当的字节交换。当isint为假时,*u.ptr中指定数量的字节将不做任何处理被发送出去;这些数据必须是服务器 预期的用于该函数参数数据类型的二进制传输的格式(由于历史原因u.ptr被声明为类型int *,其实把它考虑成void *会更好)。result_buf是放置该函数返回值的缓冲区。调用者必须已经分配了足够的空间来存储返回值(这里没有检查!)。实际的结果长度将被放在result_len指向的整数中返回。如果预期结果是 2 或 4 字节整数,把result_is_int设为 1;否则设为 0。把result_is_int设为 1 导致libpq在必要时对值进行交换字节,这样它就作为对客户端机器正确的int值被传输,注意对任一种允许的结果大小都会传递一个 4 字节到*result_buf。当result_is_int是 0 时,服务器发送的二进制格式字节将不做修改直接返回(在这种情况下,把result_buf考虑为类型void *更好)。 - + fnid 参数是要执行函数的 OID。argsnargs 指定传给函数的参数,必须与函数声明中的参数列表匹配。参数结构体的 isint 字段为真时,u.integer 值会以指定长度的整数发送到服务器,该长度必须是 2 或 4 字节,并会进行适当的字节序转换。isint 为假时,位于 *u.ptr 的指定数量字节会原样发送;数据必须符合服务器对该函数参数数据类型的二进制传输格式要求。(将 u.ptr 声明为 int * 是历史原因;将其视为 void * 更合适。)result_buf 指向用于存放函数返回值的缓冲区。调用者必须事先分配足够空间来保存返回值,这里不会检查!实际结果长度以字节为单位,返回到 result_len 指向的整数中。如果预期结果是 2 或 4 字节整数,将 result_is_int 设为 1,否则设为 0。将 result_is_int 设为 1 后,libpq 会按需转换字节序,使结果成为适合客户端机器的 int 值;注意,无论是哪种允许的结果大小,传入 *result_buf 的都是 4 字节整数。result_is_int 为 0 时,服务器发送的二进制格式字节串会原样返回。(此时,将 result_buf 视为 void * 更合适。) + - PQfn总是返回一个有效的PGresult指针,包括状态PGRES_COMMAND_OK 表示成功或者PGRES_FATAL_ERROR在出现什么问题时。 - 在使用结果之前应该检查结果状态。 - 当结果不再使用后,调用者有义务使用释放PGresult。 - + PQfn 总是返回有效的 PGresult 指针:成功时状态为 PGRES_COMMAND_OK,遇到问题时为 PGRES_FATAL_ERROR。使用结果前应检查其状态。不再需要结果时,调用者负责使用 释放 PGresult。 + - 要传递NULL参数到函数,将参数结构体的len字段设置为-1isintu 字段就不相关了。 - + 要向函数传入 NULL 参数,将该参数结构体的 len 字段设为 -1;此时,isintu 字段便不再相关。 + - 如果函数返回 NULL, *result_len 被设置为 -1, 并且 *result_buf 不调整。 - + 如果函数返回 NULL,则将 *result_len 设为 -1,而不修改 *result_buf。 + - 注意在使用此接口时,不能够处理集-值结果。 - 此外,函数必须是一个普通函数,而不是聚合、窗口函数或过程。 - + 注意,使用此接口时无法处理集合值结果。此外,函数必须是普通函数,不能是聚合函数、窗口函数或过程。 + @@ -5385,7 +5184,7 @@ typedef struct NOTIFY - in libpq + 在 libpq 中 @@ -5394,39 +5193,36 @@ typedef struct libpq应用把LISTENUNLISTENNOTIFY命令作为普通 SQL 命令提交。 - 随后通过调用PQnotifies.PQnotifies来检测NOTIFY消息的到达。 + 随后通过调用PQnotifiesPQnotifies来检测NOTIFY消息的到达。 - 函数PQnotifies从服务器发来的未处理通知消息列表中返回下一条通知。如果没有待处理通知,则返回空指针。一旦PQnotifies返回一条通知,该通知就被视为已处理,并会从通知列表中删除。 - + 函数 PQnotifies 从已收到但尚未处理的服务器通知消息列表中返回下一条通知。没有待处理通知时返回空指针。一旦 PQnotifies 返回一条通知,该通知就被视为已处理,并从通知列表中移除。 PGnotify *PQnotifies(PGconn *conn); typedef struct pgNotify { - char *relname; /* notification channel name */ - int be_pid; /* process ID of notifying server process */ - char *extra; /* notification payload string */ + char *relname; /* 通知通道名称 */ + int be_pid; /* 发送通知的服务器进程 ID */ + char *extra; /* 通知载荷字符串 */ } PGnotify; - - 在处理完PQnotifies返回的PGnotify对象后,别忘了用把它释放。 - 释放PGnotify指针本身就足够了;relnameextra域并不表示独立分配的内存(这些域名是历史遗留的,尤其是通道名称与关系名称并无关联)。 - +处理完 PQnotifies 返回的 PGnotify 对象后,务必使用 释放它。只需释放 PGnotify 指针;relnameextra 字段并非独立分配。(这些字段名称是历史遗留的;尤其是,通道名称与关系名称不必有任何关联。) + 给出了一个示例程序展示异步通知的使用。 - PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数吸收的消息。 + PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数读取的消息。 在较早版本的libpq中,及时收到NOTIFY消息的唯一方法是不断提交命令,哪怕是空命令,然后在每次后检查PQnotifies。 - 虽然这种方法仍然有效,但由于效率过低,现已废弃。 + 虽然这种方法仍然有效,但由于浪费处理能力,现已弃用。 - 当你没有可用的命令提交时,一种更好的检查NOTIFY消息的方法是调用,然后检查PQnotifies。 + 当没有需要执行的实际命令时,一种更好的检查NOTIFY消息的方法是调用,然后检查PQnotifies。 你可以使用select()等待服务器数据到达,这样在无事可做时就不会浪费CPU资源(参见以获得可传给select()的文件描述符)。 注意不管是用/提交命令还是简单地使用,这种方法都能正常工作。 不过,你应该记住在每次之后检查PQnotifies,看看在命令的处理过程中是否有通知到达。 @@ -5440,20 +5236,16 @@ typedef struct pgNotify COPY - with libpq + 使用 libpq - PostgreSQL中的COPY命令有用于libpq的对网络连接读出或者写入的选项。这一节描述的函数允许应用通过提供或者消耗已拷贝的数据来充分利用这个功能。 - + PostgreSQLCOPY 命令提供了选项,可以通过 libpq 使用的网络连接读取或写入数据。本节介绍的函数允许应用程序通过提供或接收复制数据来使用这一能力。 + - 整个处理是应用首先通过或者一个等效的函数发出 SQL COPY命令。 - 对这个命令的响应(如果命令无误)将是一个状态代码是PGRES_COPY_OUT或 者PGRES_COPY_IN(取决于指定的拷贝方向)的PGresult对象。 - 应用然后就应该使用这一节的函数接收或者传送数据行。在数据传输结束之后,另外一个PGresult对象会被返回以表明传输的成功或者失败。 - 它的状态将是:PGRES_COMMAND_OK表示成功,PGRES_FATAL_ERROR表示发生了一些问题。 - 此时我们可以通过发出进一步的 SQL 命令(在COPY操作的处理过程中,不能用同一个连接执行其它 SQL 命令)。 - + 整体流程如下:应用程序先通过 或等效函数发出 SQL COPY 命令。如果命令没有错误,响应就是一个 PGresult 对象,其状态码为 PGRES_COPY_OUTPGRES_COPY_IN,取决于指定的复制方向。应用程序随后应使用本节函数接收或发送数据行。数据传输完成后,会返回另一个 PGresult 对象,表示传输成功或失败:成功时状态为 PGRES_COMMAND_OK,出现问题时为 PGRES_FATAL_ERROR。此时可以通过 继续发出 SQL 命令。(COPY 操作进行期间,不能在同一连接上执行其他 SQL 命令。) + 如果一个COPY命令是通过在一个可能包含额外命令的字符串中发出的,那么应用在完成COPY序列之后必须继续用取得结果。 @@ -5461,17 +5253,15 @@ typedef struct pgNotify - 这一节的函数应该只在从获得了PGRES_COPY_OUTPGRES_COPY_IN结果状态的后执行。 - + 只有从 获得 PGRES_COPY_OUTPGRES_COPY_IN 结果状态后,才应调用本节函数。 + - 一个PGresult对象具有这些状态值之一,携带有关COPY操作开始的一些附加数据。 - 可以使用与查询结果相关的函数来获取这些附加数据: - - + 带有上述某个状态值的 PGresult 对象,还会携带关于即将开始的 COPY 操作的附加数据。这些数据可以通过下列函数获取,这些函数也用于查询结果: + PQnfieldsPQnfieldswith COPY + >PQnfields用于 COPY @@ -5482,7 +5272,7 @@ typedef struct pgNotify PQbinaryTuplesPQbinaryTupleswith COPY + >PQbinaryTuples用于 COPY @@ -5494,7 +5284,7 @@ typedef struct pgNotify PQfformatPQfformatwith COPY + >PQfformat用于 COPY @@ -5506,15 +5296,15 @@ typedef struct pgNotify - + 用于发送<command>COPY</command>数据的函数 - 这些函数用于在COPY FROM STDIN期间发送数据。如果在连接不是COPY_IN状态,调用它们会失败。 - + 这些函数用于在 COPY FROM STDIN 期间发送数据。如果连接不处于 COPY_IN 状态,调用它们会失败。 + @@ -5533,12 +5323,11 @@ int PQputCopyData(PGconn *conn, - 传输指定buffer中长度为nbytesCOPY数据到服务器。 - 如果数据被放在队列中,结果是 1;如果因为缓冲区满而无法被放在队列中(只可能发生在连接是非阻塞模式时),那么结果是零;如果发生错误,结果为 -1(如果返回值为 -1,那么使用检索细节。如果值是零,那么等待写准备好然后重试)。 + 将指定 buffer 中长度为 nbytesCOPY 数据传输到服务器。数据成功加入队列时返回 1;因缓冲区已满而无法加入队列时返回零(仅可能发生在非阻塞模式下);发生错误时返回 -1。(返回 -1 时,可用 获取详细信息。返回零时,应等待可写就绪后重试。) - 应用可以把COPY数据流划分成任意方便的大小放到缓冲区中。在发送时,缓冲区载荷的边界没有什么语意。数据流的内容必须匹配COPY命令预期的数据格式;详见。 + 应用程序可以将 COPY 数据流分成任意方便大小的数据块,逐块装入缓冲区。发送时,这些数据块的边界没有语义含义。数据流内容必须符合 COPY 命令预期的数据格式;详见 @@ -5558,21 +5347,15 @@ int PQputCopyEnd(PGconn *conn, - 如果errormsgNULL,则成功结束COPY_IN操作。 - 如果errormsg不是NULLCOPY被强制失败,errormsg指向的字符串是错误消息。 - (不过,我们不应假定这个准确的错误信息将会从服务器传回,因为服务器可能已经因为其自身原因导致COPY失败。)。 + 如果 errormsgNULL,则成功结束 COPY_IN 操作。如果 errormsg 不为 NULL,则强制 COPY 失败,并将 errormsg 指向的字符串用作错误消息。(但不应假定服务器一定会返回这条完全相同的错误消息,因为服务器可能已经因自身原因使 COPY 失败。) - 如果终止消息被发送,则结果为 1;在非阻塞模式中,结果为 1 也可能只表示终止消息被成功地放在了发送队列中 - (在非阻塞模式中,要确认数据确实被发送出去,你应该接着等待写准备好并且调用,重复这些直到返回零)。 - 零表示该函数由于缓冲区满而无法将该终止消息放在队列中,这只会发生在非阻塞模式中(在这种情况下,等待写准备好并且再次尝试调用)。 - 如果发生系统错误,则返回 -1,可以使用检索详情。 + 终止消息已发送时返回 1;在非阻塞模式下,返回 1 也可能仅表示该消息已成功加入发送队列。(在非阻塞模式下,要确认数据已经发送,应接着等待可写就绪并调用 ,反复执行直到返回零。)返回零表示缓冲区已满,无法将终止消息加入队列;这种情况仅可能发生在非阻塞模式下。(此时,应等待可写就绪,再次调用 。)发生严重错误时返回 -1,可用 获取详细信息。 - 在成功调用之后,调用获取COPY命令的最终结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 成功调用 后,调用 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -5605,29 +5388,19 @@ int PQgetCopyData(PGconn *conn, - 在一个COPY期间尝试从服务器获取另外一行数据。数据总是以每次一个数据行的方式被返回;如果只有一个部分行可用,那么它不会被返回。 - 成功返回一个数据行涉及到分配一块内存来保存该数据。buffer参数必须为非NULL。 - *buffer被设置为指向分配到的内存的指针,或者是在没有返回缓冲区的情况下指向NULL。 - 一个非NULL的结果缓冲区在不需要时必须用释放。 + 在 COPY 期间尝试从服务器获取下一行数据。每次总是返回一个完整数据行;如果只有部分行可用,则不返回。成功返回数据行时,会分配一块内存保存数据。buffer 参数必须为非 NULL*buffer 会被设置为指向所分配的内存;如果没有返回缓冲区,则设为 NULL。非 NULL 的结果缓冲区在不再需要时应使用 释放。 - 在成功返回一行之后,返回的值就是该数据行里数据的字节数(将是大于零)。 - 被返回的字符串总是空终止的,虽然这可能只是对文本COPY有用。 - 一个零结果表示该COPY仍然在处理中,但是还没有可用的行(只在async为真时才可能)。 - 一个 -1 结果表示COPY已经完成。-2 结果表示发生了错误(参考获取原因)。 + 成功返回一行时,返回值是该行的数据字节数,始终大于零。返回的字符串总是以零字节结尾,不过这可能仅对文本 COPY 有用。返回零表示 COPY 仍在进行,但尚无可用行(仅在 async 为真时可能发生)。返回 -1 表示 COPY 已完成;返回 -2 表示发生了错误(可用 查看原因)。 - 当async为真时(非零),将不会阻塞等待输入; - 如果COPY仍在处理过程中并且没有可用的完整行,那么它将返回零 - (在这种情况下等待读准备好,然后在再次调用之前,调用)。 - 当async为假(零)时,将阻塞,直到数据可用或者操作完成。 + 当 async 为真(非零)时, 不会阻塞等待输入;如果 COPY 仍在进行,但没有完整行可用,则返回零。(此时,应等待读就绪,先调用 ,再调用 。)当 async 为假(零)时, 会阻塞,直到数据可用或操作完成。 - 在返回 -1 之后,调用获取COPY命令的最后结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 在 返回 -1 后,调用 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -5637,11 +5410,11 @@ int PQgetCopyData(PGconn *conn, - 用于<command>COPY</command>的废弃函数 + 用于<command>COPY</command>的过时函数 - 这些函数代表了以前的处理COPY的方法。尽管它们还能用,但是现在已经被废弃,因为它们的错误处理很糟糕、检测结束数据的方法也不方便,并且缺少对二进制或非阻塞传输的支持。 - + 这些函数使用较旧的方式处理 COPY。虽然仍然可用,但由于错误处理欠佳、检测数据结束的方式不便,而且缺少对二进制或非阻塞传输的支持,已被弃用。 + @@ -5651,7 +5424,7 @@ int PQgetCopyData(PGconn *conn, - 读取一个以新行终止的字符行到(由服务器传输) 到一个长度为length的字符串缓冲区。 + 将服务器传来的、以换行符结尾的一行字符读入大小为 length 的字符串缓冲区。 int PQgetline(PGconn *conn, char *buffer, @@ -5660,12 +5433,11 @@ int PQgetline(PGconn *conn, - 这个函数拷贝最多length-1 个字符到该缓冲区中,并且把终止的新行转换成一个零字节。 - 在输入结束时返回EOF,如果整行都被读取则返回 0,如果缓冲区填满了而还没有遇到结束的新行则返回 1。 - + 此函数最多将 length-1 个字符复制到缓冲区,并将末尾的换行符转换为零字节。 在输入结束时返回 EOF,读完一整行时返回 0,缓冲区已满但尚未读到末尾换行符时返回 1。 + - 注意,应用必须检查是否一个新行包含两个字符\.,这表明服务器 已经完成了COPY命令的结果发送。如果应用可能收到超过length-1 字符长的行, 我们就应该确保正确识别\.行(例如,不要把一个长数据行的结束当作一个终止行)。 + 注意,应用程序必须检查新读入的一行是否仅由 \. 两个字符组成,这表示服务器已发送完 COPY 命令的结果。如果可能收到长度超过 length-1 个字符的行,必须确保正确识别 \. 行,例如不能把长数据行的末尾误当作终止行。 @@ -5677,7 +5449,7 @@ int PQgetline(PGconn *conn, - 不阻塞地读取一行COPY数据(由服务器传输)到一个缓冲区中。 + 以非阻塞方式将服务器传来的一行 COPY 数据读入缓冲区。 int PQgetlineAsync(PGconn *conn, char *buffer, @@ -5686,23 +5458,19 @@ int PQgetlineAsync(PGconn *conn, - 这个函数类似于,但是可以被用于那些必须异步读取COPY数据的应用, 也就是不阻塞的应用。 - 在发出了COPY命令并得到了PGRES_COPY_OUT响应之后, - 应用应该调用直到检测到结束数据的信号。 - + 此函数类似于 ,但可用于必须异步读取 COPY 数据的应用程序,即读取时不阻塞。发出 COPY 命令并收到 PGRES_COPY_OUT 响应后,应用程序应调用 ,直到检测到数据结束信号。 + - 不像,这个函数负责检测结束数据。 + 与 不同,此函数会负责检测数据结束。 - 在每次调用时,如果libpq的输入缓冲区中有一个完整的数据行可用,都将返回数据。 - 否则,在剩余行到达之前不会返回数据。如果识别到拷贝数据结束的标志,此函数返回 -1;如果没有可用数据则返回 0; - 或者是给出一个正数给出被返回的字节数。如果返回 -1,调用者下一步必须调用,然后回到正常处理。 + 每次调用时,如果 libpq 的输入缓冲区中有完整数据行, 就会返回数据;否则,要等该行剩余部分到达后才返回数据。识别到复制数据结束标记时返回 -1,没有可用数据时返回 0,否则返回正数,表示返回的数据字节数。返回 -1 后,调用者必须接着调用 ,然后恢复正常处理。 - 返回的数据将不超过一个数据行的范围。如果可能,每次将返回一个完整行。但如果调用者提供的缓冲区太小不足以容下服务器发送的行,那么将返回部分行。对于文本数据,这可以通过测试返回的最后一个字节是否\n来检测(在二进制COPY中, 需要对COPY数据格式进行实际的分析,以便做相同的判断)。被返回的字符串不是空结尾的(如果你想增加一个终止空,确保传递一个比实际可用空间少一字节的bufsize)。 + 返回的数据不会跨越数据行边界。只要可能,每次就返回一整行;但如果调用者提供的缓冲区太小,容不下服务器发送的一行,则只返回部分行。对于文本数据,可检查最后返回的字节是否为 \n,以判断是否返回了完整行。(对于二进制 COPY,则必须实际解析 COPY 数据格式才能作出相同判断。)返回的字符串不以零字节结尾。(如果要自行添加末尾的零字节,务必将传入的 bufsize 设置为比实际可用空间少一字节。) @@ -5714,7 +5482,7 @@ int PQgetlineAsync(PGconn *conn, - 向服务器发送一个空终止的字符串。如果 OK 则返回 0;如果不能发送字符串则返回EOF。 + 向服务器发送以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputline(PGconn *conn, const char *string); @@ -5722,17 +5490,14 @@ int PQputline(PGconn *conn, - 一系列调用发送的COPY数据流和返回的数据具有相同的格式, - 只是应用不需要每次调用中发送刚好一个数据行;在每次调用中发送多行或者部分行都是可以的。 + 连续调用 发送的 COPY 数据流,与 返回的数据格式相同。不过,应用程序不必在每次 调用中恰好发送一个数据行;每次发送部分行或多行也可以。 - 在PostgreSQL协议 3.0 之前,应用必须显式地发送两个字符\.作为最后一行来指示服务器已经完成发送COPY数据。 - 虽然这么做仍然有效,但是它已经被废弃并且\.的特殊含义可能在将来的版本中删除。 - 在发送完实际数据之后, 调用就足够了。 - + 在 PostgreSQL 协议 3.0 之前,应用程序必须显式发送由 \. 两个字符组成的最后一行,告知服务器应用程序已发送完 COPY 数据。虽然这种方式仍然有效,但已被弃用,\. 的特殊含义预计会在未来版本中移除。(在 CSV 模式下,这种做法已经会出现异常。)发送完实际数据后,调用 即可。 + @@ -5744,7 +5509,7 @@ int PQputline(PGconn *conn, - 向服务器发送一个非空终止的字符串。如果 OK 则返回 0,如果不能发送字符串则返回EOF。 + 向服务器发送不以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputnbytes(PGconn *conn, const char *buffer, @@ -5753,7 +5518,7 @@ int PQputnbytes(PGconn *conn, - 这个函数类似,除了数据缓冲区不需要是空终止,因为要发送的字节数是直接指定的。在发送二进制数据时使用这个过程。 + 此函数与 完全相同,只是直接指定了要发送的字节数,因此数据缓冲区不必以零字节结尾。发送二进制数据时可使用此函数。 @@ -5769,15 +5534,11 @@ int PQputnbytes(PGconn *conn, int PQendcopy(PGconn *conn); - 这个函数等待服务器完成拷贝。当最后一个字符串已经用发送给服务器时或者当最后一个字符串已经用PQgetline从服务器接收到时,就会发出这个函数。 - 这个函数必须被发出,否则服务器将会和客户端不同步。从这个函数返回后,服务器就已经准备好接收下一个 SQL 命令了。函数成功完成时返回值为 0,否则返回非零值(如果返回值为非零值,用检索详情)。 +此函数会等待服务器完成复制。应在使用 向服务器发送最后一个字符串后,或使用 PQgetline 从服务器接收最后一个字符串后调用它。必须调用此函数,否则服务器与客户端会失去同步。函数返回后,服务器便准备好接收下一条 SQL 命令。成功完成时返回 0,否则返回非零值。(返回非零值时,可用 获取详细信息。) - 在使用时,应用应该通过反复调用并且在看到终止行后调用来响应PGRES_COPY_OUT结果。 - 然后它应该返回到循环直到返回一个空指针。 - 类似地,PGRES_COPY_IN结果会用一系列加上之后的来处理,然后返 回到循环。 - 这样的安排将保证嵌入到一系列SQL命令中的COPY命令将被正确执行。 + 使用 时,收到 PGRES_COPY_OUT 结果后,应用程序应反复调用 ,并在看到终止行后调用 。随后应回到 循环,直到 返回空指针。类似地,收到 PGRES_COPY_IN 结果后,应连续调用 ,再调用 ,然后回到 循环。这样可以保证嵌在一系列 SQL 命令中的 COPY 命令正确执行。 @@ -5797,8 +5558,8 @@ int PQendcopy(PGconn *conn); 控制函数 - 这些函数控制libpq行为各种各样的细节。 - + 这些函数控制 libpq 行为的各种细节。 + @@ -5808,17 +5569,15 @@ int PQendcopy(PGconn *conn); - 返回客户端编码。 + 返回客户端编码。 int PQclientEncoding(const PGconn *conn); - - 请注意,它返回的是编码 ID,而不是一个符号串字符串,如EUC_JP。如果不成功,它会返回 -1。要把一个编码 ID 转换为为一个编码名称,可以用: - +注意,返回的是编码 ID,而不是 EUC_JP 这样的符号字符串。失败时返回 -1。要将编码 ID 转换为编码名称,可以使用: char *pg_encoding_to_char(int encoding_id); - + @@ -5828,14 +5587,11 @@ char *pg_encoding_to_char(int encoding_id); - - 设置客户端编码。 - + 设置客户端编码。 int PQsetClientEncoding(PGconn *conn, const char *encoding); - conn是一个到服务器的连接,而encoding是你想使用的编码。 - 如果函数成功地设置编码,则返回 0,否则返回 -1。这个连接的当前编码可以使用确定。 + conn是到服务器的连接,而encoding是要使用的编码。如果成功设置编码,函数返回 0,否则返回 -1。此连接的当前编码可以通过以下函数确定: @@ -5847,7 +5603,7 @@ int PQsetClientEncoding(PGconn *conn, const char * - 决定返回的消息的细节程度。 + 设置 所返回消息的详细程度。 typedef enum { @@ -5859,19 +5615,12 @@ typedef enum PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); - - 设置细节模式,并返回该连接的前一个设置。 - 在TERSE模式下,返回的消息只包括严重性、主要文本以及位置;这些东西通常放在一个单一行中。 - DEFAULT模式生成的消息包括上面的信息加上任何细节、提示或者上下文域(这些可能跨越多行)。 - VERBOSE模式包括所有可以可用的域。修改细节模式不会影响来自已有PGresult对象中的可用消息。 - 只有随后创建的PGresult对象才受到影响。 - SQLSTATE模式仅包括错误严重性和SQLSTATE错误代码,如果其中之一是可用的(如果没有,输出类似于TERSE模式)。 - + 设置详细程度模式,并返回该连接先前的设置。在 TERSE 模式下,返回的消息只包含严重级别、主要文本和位置;通常一行就能容纳。DEFAULT 模式生成的消息除上述内容外,还包含所有详细信息、提示或上下文字段(这些内容可能跨越多行)。VERBOSE 模式包含所有可用字段。SQLSTATE 模式仅包含错误严重级别,以及可用时的 SQLSTATE 错误代码(如果没有错误代码,则输出与 TERSE 模式相同)。 + - 更改详细程度设置不会影响已存在的PGresult对象的可用的消息,只会影响随后创建的对象。 - (如果想要用不同的详细程度打印之前的错误,请见 ) - + 更改详细程度设置不会影响从既有 PGresult 对象中取得的消息,只影响随后创建的对象。(如果希望以不同的详细程度打印之前的错误,请参见 。) + @@ -5882,7 +5631,7 @@ PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); - 决定如何处理返回的消息中的CONTEXT域。 + 确定 所返回消息中 CONTEXT 字段的处理方式。 typedef enum { @@ -5893,18 +5642,12 @@ typedef enum PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibility show_context); - - 设置上下文显示模式,返回该连接上之前的设置。 - 这个模式控制消息中是否包括CONTEXT域。 - NEVER模式不会包括CONTEXT,而ALWAYS则尽可能地包括这个域。 - 在ERRORS模式(默认)中,只在错误消息中包括CONTEXT域,而在通知和警告消息中不会包括。 - (但是,如果详细程度设置为 TERSESQLSTATE,则无论上下文显示模式如何,都会省略CONTEXT字段。) - + 设置上下文显示模式,并返回连接先前的设置。此模式控制消息中是否包含 CONTEXT 字段。NEVER 模式从不包含 CONTEXT,而 ALWAYS 模式在该字段可用时总是包含它。在 ERRORS 模式(默认)下,CONTEXT 字段只包含在错误消息中,不包含在通知和警告中。(不过,如果详细程度设置为 TERSESQLSTATE,则无论上下文显示模式如何,都会省略 CONTEXT 字段。) + - 更改这个模式不会影响从已经存在的PGresult对象项中得到的消息,只会影响后续创建的PGresult对象 - (如果想要用不同的详细程度打印之前的错误,请见)。 - + 更改此模式不会影响从既有 PGresult 对象中取得的消息,只影响随后创建的对象。(如果希望使用不同的显示模式打印之前的错误,请参见 。) + @@ -5915,25 +5658,20 @@ PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibilit - 启用对客户端/服务器通讯的跟踪,把跟踪信息输出到一个调试文件流中。 + 启用客户端/服务器通信跟踪,将跟踪信息写入调试文件流。 void PQtrace(PGconn *conn, FILE *stream); - + - 每行包括:一个可选的时间戳,一个方向指示器(F表示从客户端到服务器的消息或B表示从服务器到客户端的消息),消息长度、消息类型、和消息内容。 - 非消息内容字段(时间戳、方向、长度和消息类型)由一个制表符分隔。 - 消息内容用空格分隔。 - 协议字符串用双引号括起来,而用作数据值的字符串用单引号括起来。 - 不可打印的字符被打印为十六进制转义。 - 更多消息-类型-特定的详情可以在中发现。 - + 每行包含可选的时间戳、方向指示符(F 表示客户端发往服务器的消息,B 表示服务器发往客户端的消息)、消息长度、消息类型和消息内容。消息内容之外的字段(时间戳、方向、长度和消息类型)以制表符分隔。消息内容以空格分隔。协议字符串用双引号括起,用作数据值的字符串用单引号括起。不可打印字符以十六进制转义形式输出。各消息类型的进一步说明见 。 + - 在 Windows上,如果libpq库和应用使用了不同的标志编译,那么这个函数调用会导致应用崩溃,因为FILE指针的内部表达是不一样的。特别是多线程/单线程、发布/调试 以及静态/动态标志应该是库和所有使用库的应用都一致。 + 在 Windows 上,如果 libpq 库与应用程序使用不同的标志编译,调用此函数会导致应用程序崩溃,因为 FILE 指针的内部表示不同。具体而言,库与所有使用它的应用程序都应使用相同的多线程/单线程、发布/调试和静态/动态标志。 @@ -5954,11 +5692,8 @@ void PQsetTraceFlags(PGconn *conn, int flags); - flags包含描述跟踪的操作模式的标志位。 - 如果flags包含PQTRACE_SUPPRESS_TIMESTAMPS,则在打印每条消息时不包括时间戳。 - 如果flags包含PQTRACE_REGRESS_MODE,那么在打印每个消息时将修改一些字段,例如对象OIDs,以使输出在测试框架中更方便地使用。 - 这个函数必须在调用PQtrace之后调用。 - + flags 包含描述跟踪工作模式的标志位。如果 flags 包含 PQTRACE_SUPPRESS_TIMESTAMPS,则打印每条消息时不包含时间戳。如果 flags 包含 PQTRACE_REGRESS_MODE,则打印每条消息时会隐去某些字段,例如对象 OID,以便在测试框架中使用输出。必须在调用 PQtrace 之后调用此函数。 + @@ -5970,11 +5705,11 @@ void PQsetTraceFlags(PGconn *conn, int flags); - 禁用打开的跟踪。 + 禁用由 启动的跟踪。 void PQuntrace(PGconn *conn); - + @@ -6004,11 +5739,8 @@ void PQfreemem(void *ptr); - 释放libpq分配的内存,尤其是,,,和PQnotifies分配的内存。 - 特别重要的是,在微软 Windows 上使用这个函数,而不是free()。 - 这是因为只有 DLL 和应用的当多线程/单线程、发布/调试以及静态/动态标志相同时,才能在一个 DLL 中分配内存并且在应用中释放它。 - 在非微软 Windows 平台上,这个函数与标准库函数free()相同。 - + 释放 libpq 分配的内存,特别是 PQnotifies 分配的内存。在 Microsoft Windows 上,务必使用此函数,而不是 free()。这是因为只有 DLL 与应用程序使用相同的多线程/单线程、发布/调试和静态/动态标志,才能在 DLL 中分配内存并在应用程序中释放它。在 Microsoft Windows 以外的平台上,此函数与标准库函数 free() 相同。 + @@ -6019,15 +5751,16 @@ void PQfreemem(void *ptr); - 释放分配的数据结构。 + 释放 分配的数据结构。 void PQconninfoFree(PQconninfoOption *connOptions); - +如果参数为 NULL 指针,则不执行任何操作。 + - 一个简单的不会做这些,因为数组包含对子字符串的引用。 - + 仅调用 不足以完成此项释放,因为数组还包含指向附属字符串的引用。 + @@ -6051,8 +5784,8 @@ char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, 当前支持的算法是md5scram-sha-256onoff也被接受作为md5的别名,用于与较老的服务器版本兼容)。 注意,对scram-sha-256支持是在PostgreSQL版本10中引入的,并且在老的服务器版本上无法工作。 如果algorithmNULL,这个函数将向服务器查询设置的当前值。 - 这种行为可能会阻塞当前事务,并且当前事务被中止或者连接正忙于执行另一个查询时会失败。 - 如果希望为服务器使用默认的算法但避免阻塞,应在调用之前查询你自己的password_encryption,并且将该值作为algorithm传入。 + 这一查询可能阻塞,并且当前事务被中止或者连接正忙于执行另一个查询时会失败。 + 如果希望为服务器使用默认的算法但避免阻塞,应在调用之前自行查询password_encryption,并且将该值作为algorithm传入。 @@ -6118,8 +5851,8 @@ PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); 这是libpq内部用于分配并初始化一个空PGresult对象的函数。 如果无法分配内存,此函数返回NULL。 将它导出供外部调用,是因为一些应用需要自行生成结果对象,特别是带有错误状态的对象。 - 如果conn非空,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 - 此外,如果conn非空,连接中注册的所有事件过程也会被复制到PGresult中。 + 如果conn 不为 null,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 + 此外,如果conn 不为 null,连接中注册的所有事件过程也会被复制到PGresult中。 (这些过程不会收到PGEVT_RESULTCREATE调用,但可参见。) 注意,最终应对该对象调用,就像处理libpq自身返回的PGresult一样。 @@ -6140,16 +5873,16 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); - conn参数被传送给事件过程,但不会被直接使用。如果事件过程不使用它,则会返回NULL。 - + conn 参数会传递给事件过程,但此函数不会直接使用它。如果事件过程不使用此参数,则可以传入 NULL。 + 已经接收到这个对象的PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件过程不会被再次触发。 - 这个函数与分开的主要原因是在调用事件过程之前创建一个PGresult并且填充它常常是合适的。 - + 此函数与 分开的主要原因是,通常适合先创建 PGresult 并填充数据,然后再调用事件过程。 + @@ -6160,13 +5893,11 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); - 为一个PGresult对象创建一个拷贝。 - 这个拷贝不会以任何方式链接到源结果,并且当该拷贝不再需要时,必须调用进行清理。如果函数失败,返回NULL。 - + 创建 PGresult 对象的副本。副本与源结果没有任何关联,不再需要副本时必须调用 。函数失败时返回 NULL PGresult *PQcopyResult(const PGresult *src, int flags); - + 这不是为了制作一个精确的副本。返回的结果总是放在PGRES_TUPLES_OK状态中,并且不复制源中的任何错误消息。 @@ -6175,7 +5906,7 @@ PGresult *PQcopyResult(const PGresult *src, int flags); PG_COPYRES_TUPLES指定复制源结果的元组。(这也意味着复制属性。) PG_COPYRES_NOTICEHOOKS指定复制源结果的通知钩子。 PG_COPYRES_EVENTS指定复制源结果的事件。(但不复制与源相关的任何实例数据。) - 事件程序接收PGEVT_RESULTCOPY事件。 + 事件过程会收到 PGEVT_RESULTCOPY 事件。 @@ -6206,18 +5937,15 @@ int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs); - 设置一个PGresult对象的一个元组域值。 + 设置 PGresult 对象中某个元组的字段值。 int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len); - + - 这个函数将自动按需增加结果的内部元组数组。但是,tup_num参数必须小于等于,意味着这个函数对元组数组一次只能增加一个元组。 - 但已存在的任意元组中的任意域可以以任意顺序进行调整。如果field_num的一个值已经存在,它会被覆盖。 - 如果len是 -1,或valueNULL, 该域值会被设置为一个 SQL 空值。 - value会被复制到结果的私有存储中,因此函数返回后就不再需要了。如果函数失败,返回值是 0。如果函数成功,返回值会是非 0。 - + 此函数会根据需要自动扩展结果内部的元组数组。不过,tup_num 参数必须小于或等于 ,也就是说,每次只能向元组数组增加一个元组。已有元组的任何字段都可以按任意顺序修改。如果 field_num 指定的位置已有值,该值会被覆盖。如果 len 为 -1 或 valueNULL,则将该字段设置为 SQL null 值。value 会被复制到结果的私有存储中,因此函数返回后就不再需要它。函数失败时返回零,成功时返回非零值。 + @@ -6235,8 +5963,8 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); - 当res被清除时,这个函数分配的内存也会被释放掉。如果函数失败,返回值是NULL。结果被保证为按照数据的任意类型充分地对齐,正如malloc所作的。 - + 使用此函数分配的所有内存都会在清除 res 时释放。函数失败时返回 NULL。与 malloc 一样,返回的内存保证满足任意数据类型的对齐要求。 + @@ -6247,15 +5975,15 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); - 检索为PGresult对象分配的字节数。 + 获取为 PGresult 对象分配的字节数。 size_t PQresultMemorySize(const PGresult *res); - + - 此值是与PGresult对象关联的所有malloc请求的总和,就是说,将释放的所有空间。此信息可用于管理内存消耗。 - + 此值是与 PGresult 对象相关的所有 malloc 请求所分配字节数的总和,即 将释放的全部内存。这一信息有助于管理内存消耗。 + @@ -6267,35 +5995,32 @@ size_t PQresultMemorySize(const PGresult *res); - 返回所使用的libpq版本。 + 返回所使用的libpq版本。 int PQlibVersion(void); - 在运行时,这个函数的结果可以被用来决定在当前已载入的 libpq 版本中特定的功能是否可用。 - 例如,这个函数可以被用来决定哪些选项可以被用于。 - + 可在运行时根据此函数的结果,判断当前已加载的 libpq 版本是否具有特定功能。例如,可用它判断 支持哪些连接选项。 + - 结果通过将库的主版本号乘以10000再加上次版本号形成。例如,版本10.1将被返回为100001,而版本11.0将被返回为110000。 - + 返回值等于库的主版本号乘以 10000 再加上次版本号。例如,版本 10.1 返回 100001,版本 11.0 返回 110000。 + - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。 - 对于那些版本,为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - + 在主版本 10 之前,PostgreSQL 使用由三个部分组成的版本号,前两个部分共同表示主版本。对于这些版本, 用两位数字表示每个部分;例如,版本 9.1.5 返回 90105,版本 9.2.0 返回 90200。 + - 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。 - 在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 - + 因此,为了判断功能兼容性,应用程序应将 的结果除以 100 而非 10000,得到逻辑上的主版本号。在所有版本系列中,次版本(错误修复版本)之间只有最后两位数字不同。 + - 这个函数出现于PostgreSQL版本 9.1,因此它不能被用来在早期的版本中检测所需的功能,因为调用它将会创建一个对版本9.1及其后版本的链接依赖。 + 此函数从 PostgreSQL 9.1 起提供,因而不能用它检测更早版本是否具有所需功能:调用它会建立对 9.1 或更高版本的链接依赖。 @@ -6327,13 +6052,13 @@ pg_usec_time_t PQgetCurrentTimeUSec(void); 通知处理 - notice processing - in libpq + 通知处理 + 在 libpq 中 - 服务器产生的通知和警告消息不会被查询执行函数返回,因为它们不代表查询失败。它们可以被传递给一个通知处理函数,并且在处理者返回后执行会继续正常进行。默认的处理函数会把消息打印在stderr上,但是应用可以通过提供它自己的处理函数来重载这种行为。 - + 服务器生成的通知和警告消息不由查询执行函数返回,因为它们并不表示查询失败。这些消息会传递给通知处理函数,处理函数返回后,执行正常继续。默认通知处理函数将消息打印到 stderr,应用程序也可以提供自己的处理函数来替换这一行为。 + 由于历史原因,通知处理有两个级别,称为通知接收器和通知处理器。通知接收器的默认行为是格式化通知并且将一个字符串传递给通知处理器来打印。不过,如果一个应用选择提供自己的通知接收器,它通常会忽略通知处理器层并且在通知接收器中完成所有工作。 @@ -6341,10 +6066,10 @@ pg_usec_time_t PQgetCurrentTimeUSec(void); 函数PQsetNoticeReceiver - notice receiver + 通知接收器 PQsetNoticeReceiver为一个连接对象设置或者检查当前的通知接收器。 相似地,PQsetNoticeProcessor - notice processor + 通知处理器 PQsetNoticeProcessor设置或检查当前的通知处理器。 @@ -6367,19 +6092,16 @@ PQsetNoticeProcessor(PGconn *conn, - 当接收到一个服务器产生的或者libpq内部产生的通知或警告消息,通知接收器函数会被调用。 - 它会以一种PGRES_NONFATAL_ERROR PGresult的形式传递该消息 - (这允许接收器使用抽取个别的域,或者使用或者得到一个完整的预格式化的消息)。 - 被传递给PQsetNoticeReceiver的同一个空指针也被传递(必要时,这个指针可以被用来访问应用相关的状态)。 - + 从服务器收到通知或警告消息,或者 libpq 内部生成这类消息时,便会调用通知接收器函数。消息以状态为 PGRES_NONFATAL_ERRORPGresult 对象传给该函数。(接收器可使用 提取单个字段,也可使用 获取完整的预格式化消息。)传给 PQsetNoticeReceiver 的同一个 void 指针也会传入。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知接收器会简单地抽取消息(使用)并且将它传递给通知处理器。 - 通知处理器负责处理一个以文本形式给出的通知或警告消息。该消息的字符串文本(包括一个收尾的新行)被传递给通知处理器,外加一个同时被传递给PQsetNoticeProcessor的空指针(必要时,这个指针可以被用来访问应用相关的状态)。 - + 通知处理器负责处理以文本形式提供的通知或警告消息。传给它的参数包括消息字符串(含末尾的换行符),以及先前传给 PQsetNoticeProcessor 的同一个 void 指针。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知处理器很简单: @@ -6393,9 +6115,8 @@ defaultNoticeProcessor(void *arg, const char *message) - 一旦你设定了一个通知接收器或处理器,你应该期待只要PGconn对象或者从它构造出的PGresult对象存在,该函数就应该能被调用。 - 在一个PGresult创建时,PGconn的当前通知处理指针被复制到PGresult中,以备类似的函数使用。 - + 设置通知接收器或处理器后,应当预期:只要 PGconn 对象或由它生成的 PGresult 对象仍存在,就可能调用该函数。创建 PGresult 时,会将 PGconn 当前的通知处理指针复制到 PGresult 中,供 等函数在需要时使用。 + @@ -6404,19 +6125,19 @@ defaultNoticeProcessor(void *arg, const char *message) 事件系统 - libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和毁灭。一种主要的使用情况是这允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 + libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和销毁。一个主要用途是允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 - 每个注册的事件处理程序都与两个数据相关联,libpq仅将其视为不透明的void *指针。 - 有一个透传指针,当事件处理程序与PGconn注册时,应用程序提供。 + 每个注册的事件处理程序都与两项数据相关联,libpq仅将其视为不透明的void *指针。 + 有一个透传指针,由应用程序在向 PGconn 注册事件处理程序时提供。 透传指针在PGconn及其生成的所有PGresult的生命周期内永远不会更改; 因此,如果使用,它必须指向长期存在的数据。 此外,还有一个实例数据指针,在每个PGconnPGresult中一开始都是NULL。 可以使用函数来操作此指针。 请注意,与透传指针不同,PGconn的实例数据不会自动继承到从中创建的PGresult。 - libpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 —— 这是事件处理程序的责任。 + libpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 — 这是事件处理程序的责任。 @@ -6442,7 +6163,7 @@ typedef struct } PGEventRegister; - 当接收到PGEVT_REGISTER事件时,evtInfo指针应该转换为PGEventRegister *。这个结构体包含一个应该处于CONNECTION_OK状态的PGconn;如果在获得一个良好的PGconn后立即调用,则保证这一点。当返回一个失败代码时,所有清理工作必须完成,因为不会发送任何PGEVT_CONNDESTROY事件。 + 当接收到PGEVT_REGISTER事件时,evtInfo指针应该转换为PGEventRegister *。这个结构体包含一个应该处于CONNECTION_OK状态的PGconn;如果在获得一个良好的PGconn后立即调用,则保证这一点。当返回一个失败代码时,所有清理工作必须完成,因为不会发送任何PGEVT_CONNDESTROY事件。 @@ -6475,21 +6196,12 @@ typedef struct PGEVT_CONNDESTROY - - - 为了响应,连接销毁事件会被触发。由于 libpq 没有能力管理事件数据,事件过程有责任正确地清理它的事件数据。清理失败将会导致内存泄露。 - - + 连接销毁事件由以下调用触发:。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGconn *conn; } PGEventConnDestroy; - - - 当接收到一个PGEVT_CONNDESTROY事件时,evtInfo指针应该被类型转换为PGEventConnDestroy *。 - 这个事件在执行任何其他清理之前被触发。 - 该事件过程的返回值被忽略,因为没有办法指示一个来自的失败。还有,一个事件过程失败不该中断对不需要的内存的清理。 - +收到PGEVT_CONNDESTROY事件时,应将evtInfo指针强制转换为PGEventConnDestroy *。该事件触发于以下函数执行任何其他清理工作之前:。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:。此外,事件过程失败不应中止清理不再使用的内存的过程。 @@ -6545,21 +6257,12 @@ typedef struct PGEVT_RESULTDESTROY - - - 为了响应,结果销毁事件会被触发。由于 libpq 没有能力管理事件数据,事件过程有责任正确地清理它的事件数据。清理失败将会导致内存泄露。 - - + 结果销毁事件由以下调用触发:。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGresult *result; } PGEventResultDestroy; - - - 当接收到一个PGEVT_RESULTDESTROY事件时,evtInfo指针应该被类型转换为PGEventResultDestroy *。 - 这个事件在执行任何其他清理之前被触发。该事件过程的返回值被忽略,因为没有办法指示来自的失败。 - 还有,一个事件过程失败不该中断不需要的内存的清理过程。 - +收到PGEVT_RESULTDESTROY事件时,应将evtInfo指针强制转换为PGEventResultDestroy *。该事件触发于以下函数执行任何其他清理工作之前:。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:。此外,事件过程失败不应中止清理不再使用的内存的过程。 @@ -6567,7 +6270,7 @@ typedef struct - 事件回调函数 + 事件回调过程 @@ -6577,16 +6280,11 @@ typedef struct - PGEventProc是到一个事件过程的指针的 typedef,也就是从 libpq 接收事件的用户回调函数。一个事件过程的原型必须是 - + PGEventProc 是通过 typedef 定义的事件过程指针类型,也就是接收 libpq 事件的用户回调函数的指针类型。事件过程的签名必须为: int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) - - evtId指示发生了哪一个PGEVT事件。 - evtInfo指针必须被类型转换为合适的结构体类型才能获得关于事件的进一步信息。 - 当事件过程已被注册时,passThrough参数是提供给的指针。 - 如果成功,该函数应该返回非零值,失败则返回零。 +evtId 参数指示发生了哪一种 PGEVT 事件。必须将 evtInfo 指针强制转换为适当的结构体类型,以获取关于该事件的更多信息。passThrough 参数是在注册事件过程时传给 的指针。函数应在成功时返回非零值,在失败时返回零。 @@ -6596,8 +6294,8 @@ int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) - 在 Windows 上,函数能够有两个不同的地址:一个对 DLL 之外可见而另一个对 DLL 之内可见。我们应当小心只有其中之一会被用于libpq的事件过程函数,否则将会产生混淆。编写代码的最简单规则是将所有的事件过程声明为static。如果过程的地址必须对它自己的源代码文件之外可见,提供一个单独的函数来返回该地址。 - + 在 Windows 上,函数可能有两个不同的地址:一个在 DLL 外部可见,另一个在 DLL 内部可见。使用 libpq 的事件过程函数时,务必始终使用其中同一个地址,否则会产生混淆。确保代码正常工作的最简单做法,是将事件过程声明为 static。如果需要在过程所在的源文件之外取得其地址,应提供一个单独的函数来返回该地址。 + @@ -6625,7 +6323,7 @@ int PQregisterEventProc(PGconn *conn, PGEventProc proc, - 在每一个你想要接收事件的PGconn上必须注册一个事件过程。和内存不同,没有限制说一个连接上能注册多少个事件过程。如果该函数成功,它会返回一个非零值。如果它失败,则会返回零。 + 对于希望接收其事件的每个 PGconn,都必须注册一次事件过程。一个连接可注册的事件过程数量只受内存限制。函数成功时返回非零值,失败时返回零。 @@ -6670,16 +6368,14 @@ void *PQinstanceData(const PGconn *conn, PGEventProc proc); - 把结果的用于procinstanceData设置为data。成功返回非零,失败返回零(只有proc没有被正确地注册在conn中,才可能会失败)。 - + 将结果中针对 procinstanceData 设置为 data。成功时返回非零值,失败时返回零。(只有当 proc 未在结果中正确注册时,才可能失败。) int PQresultSetInstanceData(PGresult *res, PGEventProc proc, void *data); - 请注意,data表示的任何存储都不会由考虑,除非使用分配。 - (这样做是值得推荐的,因为它消除了在销毁结果时显式释放此类存储的需要。) + 注意,data 所指的存储不会计入 ,除非使用 分配它。(推荐这样做,因为结果销毁时便不必显式释放这部分存储。) @@ -6703,18 +6399,18 @@ void *PQresultInstanceData(const PGresult *res, PGEventProc proc); - 事件实例 + 事件示例 - 这里是一个管理与 libpq 连接和结果相关的私有数据的示例的框架。 - + 下面给出一个示例框架,用于管理与 libpq 连接和结果关联的私有数据。 + -/* The instanceData */ +/* instanceData 数据 */ typedef struct { int n; @@ -6734,14 +6430,14 @@ main(void) if (PQstatus(conn) != CONNECTION_OK) { - /* PQerrorMessage's result includes a trailing newline */ + /* PQerrorMessage 的结果包含末尾的换行符 */ fprintf(stderr, "%s", PQerrorMessage(conn)); PQfinish(conn); return 1; } - /* called once on any connection that should receive events. - * Sends a PGEVT_REGISTER to myEventProc. + /* 在每个需要接收事件的连接上调用一次。 + * 向 myEventProc 发送 PGEVT_REGISTER 事件。 */ if (!PQregisterEventProc(conn, myEventProc, "mydata_proc", NULL)) { @@ -6750,28 +6446,28 @@ main(void) return 1; } - /* conn instanceData is available */ + /* 可以取得 conn 的 instanceData */ data = PQinstanceData(conn, myEventProc); - /* Sends a PGEVT_RESULTCREATE to myEventProc */ + /* 向 myEventProc 发送 PGEVT_RESULTCREATE 事件 */ res = PQexec(conn, "SELECT 1 + 1"); - /* result instanceData is available */ + /* 可以取得结果的 instanceData */ data = PQresultInstanceData(res, myEventProc); - /* If PG_COPYRES_EVENTS is used, sends a PGEVT_RESULTCOPY to myEventProc */ + /* 使用 PG_COPYRES_EVENTS 时,向 myEventProc 发送 PGEVT_RESULTCOPY 事件 */ res_copy = PQcopyResult(res, PG_COPYRES_TUPLES | PG_COPYRES_EVENTS); - /* result instanceData is available if PG_COPYRES_EVENTS was - * used during the PQcopyResult call. + /* 如果调用 PQcopyResult 时使用了 PG_COPYRES_EVENTS, + * 就可以取得结果的 instanceData。 */ data = PQresultInstanceData(res_copy, myEventProc); - /* Both clears send a PGEVT_RESULTDESTROY to myEventProc */ + /* 两次清除操作都会向 myEventProc 发送 PGEVT_RESULTDESTROY 事件 */ PQclear(res); PQclear(res_copy); - /* Sends a PGEVT_CONNDESTROY to myEventProc */ + /* 向 myEventProc 发送 PGEVT_CONNDESTROY 事件 */ PQfinish(conn); return 0; @@ -6787,7 +6483,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventRegister *e = (PGEventRegister *)evtInfo; mydata *data = get_mydata(e->conn); - /* associate app specific data with connection */ + /* 将应用程序特有的数据与连接关联 */ PQsetInstanceData(e->conn, myEventProc, data); break; } @@ -6807,7 +6503,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventConnDestroy *e = (PGEventConnDestroy *)evtInfo; mydata *data = PQinstanceData(e->conn, myEventProc); - /* free instance data because the conn is being destroyed */ + /* 连接正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; @@ -6819,7 +6515,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *conn_data = PQinstanceData(e->conn, myEventProc); mydata *res_data = dup_mydata(conn_data); - /* associate app specific data with result (copy it from conn) */ + /* 将应用程序特有的数据与结果关联(从 conn 复制) */ PQresultSetInstanceData(e->result, myEventProc, res_data); break; } @@ -6830,7 +6526,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *src_data = PQresultInstanceData(e->src, myEventProc); mydata *dest_data = dup_mydata(src_data); - /* associate app specific data with result (copy it from a result) */ + /* 将应用程序特有的数据与结果关联(从另一个结果复制) */ PQresultSetInstanceData(e->dest, myEventProc, dest_data); break; } @@ -6840,18 +6536,18 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventResultDestroy *e = (PGEventResultDestroy *)evtInfo; mydata *data = PQresultInstanceData(e->result, myEventProc); - /* free instance data because the result is being destroyed */ + /* 结果正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; } - /* unknown event ID, just return true. */ + /* 未知的事件 ID,直接返回 true。 */ default: break; } - return true; /* event processing succeeded */ + return true; /* 事件处理成功 */ } ]]> @@ -6867,10 +6563,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 以下环境变量可用于选择默认连接参数值,这些值将被使用,如果调用代码没有直接指定值。这些对于避免将数据库连接信息硬编码到简单的客户端应用程序中非常有用,例如。 - - - + 以下环境变量可用于选择连接参数的默认值,供 在调用代码未直接指定参数值时使用。例如,这样可以避免在简单的客户端应用程序中硬编码数据库连接信息。 + + @@ -6880,8 +6575,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-host"/>连接参数相同。 - - + PGSSLNEGOTIATION @@ -6889,8 +6583,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSSLNEGOTIATION的行为与连接参数相同。 - - + @@ -6901,8 +6594,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) 这可以替代或者与PGHOST一起设置,以避免DNS查找开销。 - - + @@ -6912,8 +6604,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-port"/>连接参数相同。 - - + @@ -6923,8 +6614,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-dbname"/>连接参数相同。 - - + @@ -6934,8 +6624,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-user"/>连接参数相同。 - - + @@ -6946,8 +6635,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) 而应考虑使用密码文件(参见)。 - - + @@ -6957,8 +6645,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-passfile"/>连接参数相同。 - - + PGREQUIREAUTH @@ -6966,8 +6653,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGREQUIREAUTH的行为与连接参数相同。 - - + @@ -6977,8 +6663,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-channel-binding"/>连接参数相同。 - - + @@ -6988,20 +6673,17 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-service"/>连接参数相同。 - - + PGSERVICEFILE - PGSERVICEFILE指定每个用户的连接服务文件的名称 - (参见)。 - 默认为~/.pg_service.conf,或者在Microsoft Windows上为%APPDATA%\postgresql\.pg_service.conf。 + PGSERVICEFILE指定每个用户的连接服务文件的名称(参见)。 + 默认为~/.pg_service.conf,或者在 Microsoft Windows 上为%APPDATA%\postgresql\.pg_service.conf - - + @@ -7011,8 +6693,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-options"/>连接参数相同。 - - + @@ -7022,8 +6703,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-application-name"/>连接参数相同。 - - + @@ -7033,8 +6713,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslmode"/>连接参数相同。 - - + @@ -7042,11 +6721,10 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGREQUIRESSL的行为与连接参数相同。 - 这个环境变量已被弃用,推荐使用PGSSLMODE变量;设置这两个变量会抑制这个变量的效果。 + 这个环境变量已被弃用,推荐使用PGSSLMODE变量;同时设置这两个变量时,前者不再生效。 - - + @@ -7056,8 +6734,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslcompression"/>连接参数相同。 - - + @@ -7067,8 +6744,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslcert"/>连接参数相同。 - - + @@ -7078,8 +6754,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslkey"/>连接参数相同。 - - + PGSSLCERTMODE @@ -7087,8 +6762,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSSLCERTMODE的行为与连接参数相同。 - - + @@ -7098,8 +6772,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslrootcert"/>连接参数相同。 - - + @@ -7109,8 +6782,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslcrl"/>连接参数相同。 - - + @@ -7120,8 +6792,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslcrldir"/>连接参数相同。 - - + @@ -7131,8 +6802,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-sslsni"/>连接参数相同。 - - + @@ -7142,8 +6812,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-requirepeer"/>连接参数相同。 - - + @@ -7153,8 +6822,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-ssl-min-protocol-version"/>连接参数相同。 - - + @@ -7164,8 +6832,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-ssl-max-protocol-version"/>连接参数相同。 - - + @@ -7175,8 +6842,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-gssencmode"/>连接参数相同。 - - + @@ -7186,8 +6852,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-krbsrvname"/>连接参数相同。 - - + @@ -7197,8 +6862,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-gsslib"/>连接参数相同。 - - + PGGSSDELEGATION @@ -7206,8 +6870,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGGSSDELEGATION的行为与连接参数相同。 - - + @@ -7217,8 +6880,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-connect-timeout"/>连接参数相同。 - - + @@ -7228,8 +6890,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-client-encoding"/>连接参数相同。 - - + @@ -7239,14 +6900,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-target-session-attrs"/>连接参数相同。 - - - - - 下面的环境变量可用来为每一个PostgreSQL会话指定默认行为(为每一个用户或每一个数据库设置默认行为的方法还可见命令)。 - - - + PGLOADBALANCEHOSTS @@ -7254,8 +6908,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGLOADBALANCEHOSTS的行为与连接参数相同。 - - + PGMINPROTOCOLVERSION @@ -7263,8 +6916,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGMINPROTOCOLVERSION的行为与连接参数相同。 - - + PGMAXPROTOCOLVERSION @@ -7272,8 +6924,13 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGMAXPROTOCOLVERSION的行为与连接参数相同。 + + - + + 以下环境变量可用于指定每个 PostgreSQL 会话的默认行为。(也可参见 命令,了解按用户或按数据库设置默认行为的方法。) + + PGDATESTYLE @@ -7281,8 +6938,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGDATESTYLE设置日期/时间表示的默认风格(等同于SET datestyle TO ...)。 - - + PGTZ @@ -7290,8 +6946,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGTZ设置默认的时区(等同于SET timezone TO ...)。 - - + PGGEQO @@ -7300,8 +6955,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - - 这些环境变量的正确值可参考SQL 命令 。 +有关这些环境变量的正确取值,请参见 SQL 命令 @@ -7346,16 +7000,12 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) 用户主目录中的.pgpass文件可保存密码,供连接需要密码且尚未通过其他方式指定密码时使用。在 Unix 系统上,该目录可由HOME环境变量指定;如果未定义该变量,则使用有效用户的主目录。在 Microsoft Windows 上,文件名为%APPDATA%\postgresql\pgpass.conf(其中%APPDATA%指用户配置文件中的应用数据子目录)。也可以通过连接参数或环境变量PGPASSFILE指定要使用的密码文件。 - - 这个文件应该包含下列格式的行: - + 该文件中的行应采用以下格式: hostname:port:database:username:password - - (你可以向该文件增加一个提醒:把上面的行复制到该文件并且在前面加上#)。前四个字段的每一个都可以是字面值或者匹配任何东西的*。第一个匹配当前连接参数的行中的密码字段将被使用(因此,在使用通配符时把更特殊的项放在前面)。如果一个条目需要包含:或者\,用\对该字符转义。如果指定了host连接参数,主机名字段会被匹配到host,否则如果指定了hostaddr参数则匹配到hostaddr,如果两者都没有给出,则会搜索主机名localhost。当连接是一个Unix域套接字连接并且host参数匹配libpq的默认套接字目录路径时,也会搜索主机名localhost。在一台备库上,值为replication的数据库字段匹配连接到主库的流复制连接。否则数据库字段的用途有限,因为用户对同一个集簇中的所有数据库都有相同的密码。 - +(可以复制上面这一行,并在行首加上#,在文件中加入提示注释。)前四个字段中的每一个都可以是字面值,或者是*,后者可以匹配任何内容。将使用与当前连接参数匹配的第一行中的密码字段。(因此,使用通配符时,应将更具体的条目放在前面。)如果条目需要包含:\,请使用\转义该字符。主机名字段首先匹配已指定的host连接参数;否则匹配已指定的hostaddr参数。如果两者都未指定,则查找主机名localhost。在以下情况下也会查找主机名localhost:连接使用 Unix 域套接字,且host参数与libpq的默认套接字目录路径匹配。在备库中,数据库字段为replication时,匹配连接到主库的流复制连接。除此之外,数据库字段的用途有限,因为同一用户在同一数据库集簇的所有数据库中使用相同的密码。 - 在 Unix 系统上,密码文件上的权限必须不允许所有人或组内访问,可以用chmod 0600 ~/.pgpass这样的命令实现。如果权限没有这么严格,该文件将被忽略。在微软 Windows 上,该文件被假定存储在一个安全的目录中,因此不会进行特别的权限检查。 + 在 Unix 系统上,密码文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.pgpass 这样的命令实现。如果权限没有这么严格,该文件将被忽略。在 Microsoft Windows 上,假定该文件存储在安全的目录中,因此不进行特殊的权限检查。 @@ -7376,10 +7026,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 连接服务文件允许 libpq 连接参数与一个单一服务名称关联。 - 那个服务名称可以在一个 libpq 连接字符串里面指定,与其相关的设置将被使用。 - 这允许在不重新编译使用 libpq 的应用的前提下修改连接参数。 - 服务名称也可以被使用PGSERVICE环境变量来指定。 + 连接服务文件允许将 libpq 连接参数与单个服务名称关联。随后可以在 libpq 连接字符串中使用 service 关键字指定该服务名称,从而使用关联的设置。这样便可以修改连接参数,而无需重新编译使用 libpq 的应用程序。也可以使用 PGSERVICE 环境变量指定服务名称。 @@ -7395,23 +7042,19 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 或者服务文件使用一种INI 文件格式,其中小节名是服务名并且参数是连接参数。 - 列表见。例如: + 两种服务文件均使用 INI 文件 格式,其中配置段名称是服务名称,参数是连接参数;参数列表见 。例如: -# comment +# 注释 [mydb] host=somehost port=5433 user=admin - 在PostgreSQL安装的share/pg_service.conf.sample中提供了一个示例文件。 +PostgreSQL 安装目录中的 share/pg_service.conf.sample 提供了一个示例文件。 - 从服务文件中获取的连接参数与从其他来源获取的参数相结合。 - 服务文件设置覆盖相应的环境变量,然后反过来可以由连接字符串中直接给出的值覆盖。 - 例如,使用上面的服务文件,连接字符串service=mydb port=5434将使用主机somehost,端口5434, - 用户admin,以及由环境变量或内置默认所设置的其他参数。 + 从服务文件中获取的连接参数会与其他来源的参数合并。服务文件中的设置会覆盖相应的环境变量,而连接字符串中直接给出的值又会覆盖服务文件中的设置。例如,使用上述服务文件时,连接字符串 service=mydb port=5434 将使用主机 somehost、端口 5434、用户 admin,以及由环境变量或内置默认值设置的其他参数。 @@ -7427,24 +7070,14 @@ user=admin 如果libpq已经在编译时打开了 LDAP 支持(configure的选项),就可以通过 LDAP 从一个中央服务器检索hostdbname之类的连接参数。这样做的好处是如果一个数据库的连接参数改变,不需要在所有的客户端机器上更新连接信息。 - - LDAP连接参数查找使用连接服务文件pg_service.conf(参见)。 - 在pg_service.conf段落中以ldap://开头的行将被识别为LDAP URL,并执行LDAP查询。 - 结果必须是一组keyword = value对,将用于设置连接选项。 - URL必须符合RFC 1959的形式为 - + LDAP 连接参数查询使用连接服务文件pg_service.conf(参见)。在pg_service.conf的配置段中,以ldap://开头的行会被识别为 LDAP URL,并执行 LDAP 查询。结果必须是一个keyword = value键值对列表,用于设置连接选项。URL 必须符合 RFC 1959,格式如下: ldap://[hostname[:port]]/search_base?attribute?search_scope?filter - - 其中hostname默认为localhostport默认为389。 - +其中,hostname默认为localhostport默认为 389。 - - 一次成功的 LDAP 查找后,pg_service.conf的处理被终止。但是如果联系不上 LDAP 则会继续处理pg_service.conf。这就提供了后手,可以加入更多指向不同 LDAP 服务器的 LDAP URL 行、经典的keyword = value对或者默认连接选项。如果你宁愿在这种情况下得到一个错误消息,在该 LDAP URL 之后增加一个语法错误的行。 - + LDAP 查找成功后就会停止处理 pg_service.conf;如果无法联系 LDAP 服务器,则会继续处理。这使后续指向其他 LDAP 服务器的 LDAP URL 行、常规的 keyword = value 对或默认连接选项能够作为后备。如果希望在这种情况下得到错误消息,可以在 LDAP URL 后添加一个语法不正确的行。 - - 一个和 LDIF 文件一起创建的 LDAP 条目实例 - + 例如,使用以下 LDIF 文件创建的 LDAP 条目: version:1 dn:cn=mydatabase,dc=mycompany,dc=com changetype:add @@ -7456,9 +7089,7 @@ description:port=5439 description:dbname=mydb description:user=mydb_user description:sslmode=require - - 可以用下面的 LDAP URL 查询: - +可以通过以下 LDAP URL 查询: ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase) @@ -7466,7 +7097,7 @@ ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase) 你也可以将常规的服务文件条目和 LDAP 查找混合。pg_service.conf中一节的完整示例: -# 只有主机和端口存储在LDAP中,显式指定dbname和user。 +# 仅 host 和 port 存储在 LDAP 中;显式指定 dbname 和 user [customerdb] dbname=customer user=appuser @@ -7486,9 +7117,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - PostgreSQL具有原生支持使用SSL连接来加密客户端/服务器通信, - 使用TLS协议以提高安全性。有关服务器端SSL功能的详细信息,请参见。 - + PostgreSQL 原生支持使用 SSL 连接,通过 TLS 协议加密客户端与服务器之间的通信,以提高安全性。有关服务器端 SSL 功能的详细信息,请参见 。 + libpq读取系统范围的OpenSSL配置文件。默认情况下,这个文件被命名为openssl.cnf并且位于openssl version -d所报告的目录中。可以通过设置环境变量OPENSSL_CONF把这个默认值覆盖为想要的配置文件的名称。 @@ -7496,39 +7126,25 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 服务器证书的客户端验证 + 客户端对服务器证书的验证 - 默认情况下,PostgreSQL将不会执行服务器证书的任何验证。这意味着可以在不被客户端知晓的情况下伪造服务器身份(例如通过修改一个 DNS 记录或者接管服务器的 IP 地址)。为了阻止哄骗,客户端必须能够通过一条信任链验证服务器的身份。信任链可以这样建立:在一台计算机上放置一个根(自签名的)证书机构(CA)的证书并且在另一台计算机上放置一个由根证书签发的叶子证书。还可以使用一种中间证书,它由根证书签发并且可以签发叶子证书。 + 默认情况下,PostgreSQL 不会对服务器证书执行任何验证。这意味着可以在客户端不知情的情况下伪造服务器身份,例如修改 DNS 记录或接管服务器的 IP 地址。要防止身份伪造,客户端必须能够通过信任链验证服务器身份。建立信任链的方法是:在一台计算机上放置根证书机构(CA)的自签名证书,在另一台计算机上放置由根证书签发的叶证书。也可以使用由根证书签发、又用于签发叶证书的中间证书。 - - 为了允许客户端验证服务器的身份,在客户端上放置一份根证书并且在服务器上放置由根证书签发的叶子证书。为了允许服务器验证客户端的身份,在服务器上放置一份根证书并且在客户端上放置由根证书签发的叶子证书。也可以使用一个或者更多个中间证书(通常与叶子证书存在一起)来将叶子证书链接到根证书。 - + 要让客户端验证服务器的身份,请在客户端放置根证书,并在服务器上放置由该根证书签发的叶证书。要让服务器验证客户端的身份,请在服务器上放置根证书,并在客户端放置由该根证书签发的叶证书。也可以使用一个或多个中间证书(通常与叶证书存储在一起),将叶证书链接到根证书。 - - 一旦信任链被建立起来,客户端有两种方法验证服务器发过来的叶子证书。如果参数sslmode被设置为verify-ca,libpq将通过检查该证书是否链接到存储在客户端上的根证书来验证服务器。如果sslmode被设置为verify-full,libpq将验证服务器的主机名匹配存储在服务器证书中的名称。如果服务器证书无法被验证,则SSL连接将失败。在大部分对安全性很敏感的环境中,推荐使用verify-full。 - + 建立信任链后,客户端可以通过两种方式验证服务器发送的叶证书。如果参数 sslmode 设为 verify-ca,libpq 会沿证书链检查到存储在客户端上的根证书,以验证服务器是否可信。如果 sslmode 设为 verify-full,libpq 还会验证服务器主机名是否与服务器证书中存储的名称匹配。如果无法验证服务器证书,SSL 连接将失败。在大多数对安全敏感的环境中,建议使用 verify-full - 在verify-full模式下,主机名将与证书的主体替代名称属性(SAN)匹配, - 或者与通用名称属性匹配,如果没有类型为dNSName的SAN存在。 - 如果证书的名称属性以星号(*)开头,那么星号将被视为通配符, - 可以匹配所有字符,除了点(.)。 - 这意味着证书将不匹配子域。如果连接使用IP地址而不是主机名进行, - 则IP地址将与类型为iPAddressdNSName的SAN匹配 - (不进行任何DNS查找)。如果没有iPAddress SAN存在, - 也没有匹配的dNSName SAN存在,则主机IP地址将与通用名称属性匹配。 - + 在 verify-full 模式下,会将主机名与证书的主体替代名称属性(SAN)匹配;如果不存在类型为 dNSName 的 SAN,则与通用名称属性匹配。如果证书的名称属性以星号(*)开头,该星号会被视为通配符,匹配点(.)以外的所有字符。这意味着该证书不会匹配子域。如果使用 IP 地址而不是主机名建立连接,则会将该 IP 地址与类型为 iPAddressdNSName 的 SAN 匹配(不执行任何 DNS 查询)。如果不存在 iPAddress SAN,也不存在匹配的 dNSName SAN,则将主机 IP 地址与通用名称属性匹配。 + - 为了与早期版本的PostgreSQL向后兼容,主机IP地址的验证方式与 - RFC 6125中的方式不同。 - 主机IP地址始终与dNSName SANs以及iPAddress SANs匹配, - 如果不存在相关的SANs,则可以与通用名称属性匹配。 - + 为与 PostgreSQL 的早期版本向后兼容,主机 IP 地址的验证方式与 RFC 6125 不同。主机 IP 地址始终会与 dNSName SAN 以及 iPAddress SAN 匹配;如果不存在相关的 SAN,还可以与通用名称属性匹配。 + @@ -7548,8 +7164,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 为了与 PostgreSQL 的早期版本达到向后兼容,如果存在一个根 CA 文件,sslmode=require的行为将与verify-ca相同,即服务器证书根据 CA 验证。我们鼓励依赖这种行为,并且需要证书验证的应用应该总是使用verify-ca或者verify-full。 - + 为与 PostgreSQL 的早期版本向后兼容,如果存在根 CA 文件,sslmode=require 的行为将与 verify-ca 相同,即根据 CA 验证服务器证书。不建议依赖这种行为;需要证书验证的应用程序应始终使用 verify-caverify-full。 + @@ -7558,44 +7174,27 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 客户端证书 - 如果服务器尝试通过请求客户端的叶证书来验证客户端的身份, - libpq将发送存储在文件 - ~/.postgresql/postgresql.crt中的证书,该文件位于用户的主目录中。 - 证书必须链到服务器信任的根证书。匹配的 - 私钥文件~/.postgresql/postgresql.key也必须存在。 - 在Microsoft Windows上,这些文件的名称分别为 - %APPDATA%\postgresql\postgresql.crt和 - %APPDATA%\postgresql\postgresql.key。 - 证书和密钥文件的位置可以通过连接参数 - sslcertsslkey, - 或通过环境变量PGSSLCERTPGSSLKEY来覆盖。 - + 如果服务器请求客户端的叶证书以验证客户端身份,libpq 将发送用户主目录下 ~/.postgresql/postgresql.crt 文件中存储的证书。这些证书必须通过证书链连接到服务器信任的根证书。还必须存在匹配的私钥文件 ~/.postgresql/postgresql.key。在 Microsoft Windows 上,这两个文件分别名为 %APPDATA%\postgresql\postgresql.crt%APPDATA%\postgresql\postgresql.key。可以通过连接参数 sslcertsslkey,或环境变量 PGSSLCERTPGSSLKEY,覆盖证书和密钥文件的位置。 + - 在Unix系统上,私钥文件的权限必须禁止任何对世界或组的访问;可以通过类似以下命令来实现: - chmod 0600 ~/.postgresql/postgresql.key。 - 或者,该文件可以由root拥有并具有组读取权限(即0640权限)。 - 该设置适用于由操作系统管理证书和密钥文件的安装。然后,libpq的用户应该成为具有对这些证书和密钥文件访问权限的组的成员。 - (在Microsoft Windows上,没有文件权限检查,因为假定%APPDATA%\postgresql目录是安全的。) - + 在 Unix 系统上,私钥文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.postgresql/postgresql.key 这样的命令实现。另一种做法是使文件归 root 所有,并允许组用户读取(即 0640 权限)。这种设置适用于由操作系统管理证书和密钥文件的安装环境。此时,应将 libpq 用户加入有权访问这些证书和密钥文件的组。(在 Microsoft Windows 上,不检查文件权限,因为假定 %APPDATA%\postgresql 目录是安全的。) + postgresql.crt中的第一个证书必须是客户端的证书,因为它必须匹配客户端的私钥。可以选择将中间证书追加到该文件 — 这样做避免了在服务器上存放中间证书的要求()。 - 证书和密钥可能是 PEM 或 ASN.1 DER 格式。 + 证书和密钥可以采用 PEM 或 ASN.1 DER 格式。 - 密钥可以以明文存储,也可以使用OpenSSL支持的任何算法(例如AES-128)使用密码进行加密。 - 如果密钥是加密存储的,那么可以在连接选项中提供密码。 - 如果提供了加密密钥,而且sslpassword选项不存在或为空,那么只要 TTY 可用,OpenSSL就会以Enter PEM pass phrase:提示交互式输入密码。 - 应用程序可以通过提供自己的密钥密码回调,覆盖客户端证书提示以及sslpassword参数的处理;参见。 + 密钥可以以明文存储,也可以使用密码,按 OpenSSL 支持的任意算法(例如 AES-128)进行加密。如果密钥以加密形式存储,可以在 连接选项中提供密码。如果提供了加密密钥,而 sslpassword 选项缺失或为空,则在有 TTY 可用时,OpenSSL 会显示 Enter PEM pass phrase: 提示,交互式地请求输入密码。应用程序可以提供自己的密钥密码回调,以覆盖客户端证书提示及 sslpassword 参数的处理;参见 - 创建证书的指令请参考。 + 有关创建证书的说明,请参见 @@ -7604,8 +7203,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 不同模式中提供的保护 - sslmode参数的不同值提供了不同级别的保护。SSL 能够针对三类攻击提供保护: - + sslmode 参数的不同值提供不同级别的保护。SSL 可以防范三类攻击: 窃听 @@ -7618,31 +7216,33 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 中间人(MITM - 如果一个第三方能对客户端和服务器之间传送的数据进行修改,它就能假装是服务器并且因此能看见并且修改数据,即使这些数据已被加密。然后第三方可以将连接信息和数据转送给原来的服务器,使得它不可能检测到攻击。这样做的通常途径包括 DNS 污染和地址劫持,借此客户端被重定向到一个不同的服务器。还有几种其他的攻击方式能够完成这种攻击。SSL使用证书验证让客户端认证服务器,就可以阻止这种攻击。 - + + 如果第三方能修改客户端与服务器之间传输的数据,就可以冒充服务器,进而查看和修改数据,即使数据已经加密。随后,第三方可以将连接信息和数据转发给原来的服务器,使攻击无法被察觉。常见的手段包括 DNS 污染和地址劫持,从而将客户端引向预期之外的服务器。还有其他几种攻击手段可以达到同样的目的。SSL 使用证书验证,让客户端认证服务器身份,以防范这种攻击。 + - 模仿 + 冒充 - 如果一个第三方能假装是一个授权的客户端,它能够简单地访问它本不能访问的数据。通常这可以由不安全的密码管理所致。SSL使用客户端证书来确保只有持有合法证书的客户端才能访问服务器,这样就能阻止这种攻击。 - + + 如果第三方能冒充获授权的客户端,就能直接访问其无权访问的数据。这通常可能由不安全的密码管理导致。SSL 使用客户端证书,确保只有持有有效证书的客户端才能访问服务器,以防范这种攻击。 + - 对于一个已知受 SSL 保护的连接,在连接建立之前,必须在客户端和服务器两端都配置 SSL。如果只在服务器端配置,客户端在得知服务器要求高安全性之前,可能就已经开始发送敏感信息(例如密码)。在 libpq 中,要确保连接安全,可以把sslmode参数设置为verify-fullverify-ca,并为系统提供一个用于验证的根证书。这类似于使用https URL浏览加密网页。 + 要确保连接受到 SSL 保护,必须在建立连接之前,在客户端和服务器两端配置 SSL。如果仅在服务器上配置,客户端可能在得知服务器要求高安全性之前就已发送敏感信息(例如密码)。在 libpq 中,可以将 sslmode 参数设为 verify-fullverify-ca,并向系统提供用于验证的根证书,以确保连接安全。这类似于使用 https URL 进行加密的网页浏览。 - 一旦服务器已经被认证,客户端可以传递敏感数据。这意味着直到这一点,客户端都不需要知道是否证书将被用于认证,这样只需要在服务器配置中指定就比较安全。 + 服务器通过身份认证后,客户端便可以传送敏感数据。这意味着,在此之前,客户端无需知道是否会使用证书进行认证,因此可以安全地仅在服务器配置中指定这一点。 - 所有SSL选项都带来了加密和密钥交换的负荷,因此必须在性能和安全性之间做出平衡。不同sslmode值所保护的风险,以及它们是怎样看待安全性和负荷的。 + 所有 SSL 选项都会产生加密和密钥交换的开销,因此必须在性能与安全性之间作出权衡。 说明了不同 sslmode 值所能防范的风险,以及它们所表达的对安全性和开销的取舍。
@@ -7658,7 +7258,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) sslmode 窃听保护 - 中间人攻击防护 + MITM 防护 声明 @@ -7669,7 +7269,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) disable - 我不关心安全性,并且我不想为加密增加负荷。 + 我不关心安全性,并且我不想为加密增加开销。 @@ -7677,7 +7277,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) allow 可能 - 我不关心安全性,但如果服务器坚持,我将承担加密带来的负荷。 + 我不关心安全性,但如果服务器坚持,我将承担加密带来的开销。 @@ -7685,7 +7285,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) prefer 可能 - 我不关心安全性,但如果服务器支持,我希望承担加密带来的负荷。 + 我不关心加密,但如果服务器支持,我希望承担加密带来的开销。 @@ -7693,7 +7293,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) require - 我想要对数据加密,并且我接受因此带来的负荷。我信任该网络会保证我总是连接到想要连接的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我信任该网络会保证我总是连接到想要连接的服务器。 @@ -7701,7 +7301,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-ca 取决于 CA 策略 - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器。 @@ -7709,7 +7309,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-full - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 @@ -7718,11 +7318,11 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
- verify-caverify-full之间的区别取决于根CA的策略。如果使用了一个公共CAverify-ca允许连接到那些可能已经被其他人注册到该CA的服务器。在这种情况下,总是应该使用verify-full。如果使用了一个本地CA或者甚至是一个自签名的证书,使用verify-ca常常就可以提供足够的保护。 + verify-caverify-full之间的区别取决于根CA的策略。如果使用了一个公共CAverify-ca允许连接到那些可能已经被其他人注册到该CA的服务器。在这种情况下,总是应该使用verify-full。如果使用了一个本地CA或者甚至是一个自签名的证书,使用verify-ca常常就可以提供足够的保护。 - sslmode的默认值是prefer。如表中所示,这在安全性的角度来说没有意义,并且它只承诺可能的性能负荷。提供它作为默认值只是为了向后兼容,并且我们不推荐在安全部署中使用它。 + sslmode 的默认值是 prefer。如表所示,从安全角度看,这一设置没有意义;它只会在可能时带来性能开销。将其作为默认值仅出于向后兼容的考虑,不建议在有安全要求的部署中使用。 @@ -7764,8 +7364,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) ~/.postgresql/root.crt - 可信的证书机构 - 检查服务器证书是由一个可信的证书机构签发 + 受信任的证书机构 + 检查服务器证书是由一个受信任的证书机构签发 @@ -7783,7 +7383,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) SSL 库初始化 - 需要兼容旧版 PostgreSQL、使用 OpenSSL 1.0.2 或更早版本的应用程序,需要在使用 SSL 库之前初始化它。自行初始化 libssl 和/或 libcrypto 库的应用程序应调用 ,告知 libpq 这些库已由应用程序初始化,使 libpq 不再初始化它们。不过,使用 OpenSSL 1.1.0 或更高版本时无需这样做,因为重复初始化已不再造成问题。 + 需要兼容旧版 PostgreSQL、使用 OpenSSL 1.0.2 或更早版本的应用程序,需要在使用 SSL 库之前初始化它。自行初始化 libssl 和/或 libcrypto 库的应用程序应调用 ,告知 libpq libssl 和/或 libcrypto 库已由应用程序初始化,使 libpq 不再初始化它们。不过,使用 OpenSSL 1.1.0 或更高版本时无需这样做,因为重复初始化已不再造成问题。 有关这些函数的用法,请参阅目标 PostgreSQL 版本的文档。 @@ -7838,8 +7438,8 @@ void PQinitSSL(int do_ssl); OAuth 支持 - libpq通过一个可选模块实现了对 OAuth v2 Device Authorization 客户端流程的支持,该流程记录在 - RFC 8628中。关于如何启用内置的 Device Authorization 流程,请参见安装文档。 + libpq通过一个可选模块实现了对 OAuth v2 设备授权客户端流程的支持,该流程记录在 + RFC 8628中。关于如何启用内置的设备授权流程,请参见安装文档。 当启用支持并安装该可选模块后,如果服务器在认证期间请求 Bearer 令牌,libpq默认会使用内置流程。即使运行客户端应用的系统没有可用的 Web 浏览器,例如通过SSH运行客户端时,也可以使用这一流程。 @@ -7861,7 +7461,7 @@ Visit https://example.com/device and enter the code: ABCD-EFGH - 当前 Windows 上尚不支持内置的 Device Authorization 流程。不过,仍然可以实现自定义客户端流程。 + 当前 Windows 上尚不支持内置的设备授权流程。不过,仍然可以实现自定义客户端流程。 @@ -7885,10 +7485,10 @@ void PQsetAuthDataHook(PQauthDataHook_type hook); int hook_fn(PGauthData type, PGconn *conn, void *data); - 当应用程序需要执行某个动作时,libpq会调用该回调。type描述所提出的请求,conn是正在认证的连接句柄,而data指向该请求特有的元数据。这个指针所指内容由type决定;支持的列表见。 + 当需要应用程序执行某个操作时,libpq会调用该回调。type描述所提出的请求,conn是正在认证的连接句柄,而data指向该请求特有的元数据。这个指针所指内容由type决定;支持的列表见 - 钩子可以串联起来,以支持协作式和/或回退式行为。一般来说,钩子实现应检查传入的type(以及可能的请求元数据和/或当前conn的设置),以决定是否处理某一项 authdata。如果不处理,则应把请求委托给链中的前一个钩子(可通过PQgetAuthDataHook获取)。 + 钩子可以串联起来,以支持协作和/或后备行为。一般来说,钩子实现应检查传入的type(以及可能的请求元数据和/或当前conn的设置),以决定是否处理某一项 authdata。如果不处理,则应把请求委托给链中的前一个钩子(可通过PQgetAuthDataHook获取)。 返回一个大于零的整数表示成功。返回负整数表示发生错误并放弃此次连接尝试。(值零保留给默认实现。) @@ -7929,23 +7529,23 @@ PQauthDataHook_type PQgetAuthDataHook(void); typedef struct _PGpromptOAuthDevice { - const char *verification_uri; /* verification URI to visit */ - const char *user_code; /* user code to enter */ - const char *verification_uri_complete; /* optional combination of URI and - * code, or NULL */ - int expires_in; /* seconds until user code expires */ + const char *verification_uri; /* 要访问的验证 URI */ + const char *user_code; /* 要输入的用户代码 */ + const char *verification_uri_complete; /* 可选的 URI 与代码组合, + * 或为 NULL */ + int expires_in; /* 距用户代码过期的秒数 */ } PGpromptOAuthDevice; - 可被包含在libpq中的 OAuth Device Authorization 流程要求最终用户使用浏览器访问一个 URL,然后输入一个代码,以允许libpq代表其连接到服务器。默认提示只是把verification_uriuser_code打印到标准错误。替换实现可以按任意偏好的方式展示这些信息,例如使用 GUI。 + 可被包含在libpq中的 OAuth 设备授权流程要求最终用户使用浏览器访问一个 URL,然后输入一个代码,以允许libpq代表其连接到服务器。默认提示只是把verification_uriuser_code打印到标准错误。替换实现可以按任意偏好的方式展示这些信息,例如使用 GUI。 该回调只会在内置设备授权流程中被调用。如果应用程序安装了自定义 OAuth 流程,或者libpq构建时未启用内置流程支持,则不会使用这种 authdata 类型。 - 如果提供了非空的verification_uri_complete,则可以选择把它用于非文本形式的验证(例如显示二维码)。在这种情况下,仍应向最终用户显示 URL 和用户代码,因为该代码需要由提供者手工确认,而 URL 也使得用户在无法使用非文本方式时仍可继续。更多信息见 - RFC 8628 第 3.3.1 节。 + 如果提供了不为 NULL 的verification_uri_complete,则可以选择把它用于非文本形式的验证(例如显示二维码)。在这种情况下,仍应向最终用户显示 URL 和用户代码,因为该代码需要由提供者手工确认,而 URL 也使得用户在无法使用非文本方式时仍可继续。更多信息见 + RFC 8628 第 3.3.1 节。 @@ -7957,53 +7557,52 @@ typedef struct _PGpromptOAuthDevice - 添加一个自定义流程实现;如果内置流程已安装,则用它替换内置流程。该钩子应当要么直接返回一个适用于当前 user/issuer/scope 组合的 Bearer 令牌(如果能在不阻塞的情况下获得),要么设置一个异步回调来获取令牌。 + 添加一个自定义流程实现;如果内置流程已安装,则用它替换内置流程。该钩子应当要么直接返回一个适用于当前用户、签发者及授权范围组合的 Bearer 令牌(如果能在不阻塞的情况下获得),要么设置一个异步回调来获取令牌。 data指向一个PGoauthBearerRequest实例,应该由实现填充: typedef struct PGoauthBearerRequest { - /* Hook inputs (constant across all calls) */ - const char *openid_configuration; /* OIDC discovery URL */ - const char *scope; /* required scope(s), or NULL */ + /* 钩子输入(在所有调用中保持不变) */ + const char *openid_configuration; /* OIDC 发现 URL */ + const char *scope; /* 所需的授权范围,或为 NULL */ - /* Hook outputs */ + /* 钩子输出 */ /* - * Callback implementing a custom asynchronous OAuth flow. The signature is - * platform-dependent: PQ_SOCKTYPE is SOCKET on Windows, and int everywhere - * else. + * 实现自定义异步 OAuth 流程的回调。签名与平台有关: + * 在 Windows 上,PQ_SOCKTYPE 是 SOCKET;在其他平台上则为 int。 */ PostgresPollingStatusType (*async) (PGconn *conn, struct PGoauthBearerRequest *request, PQ_SOCKTYPE *altsock); - /* Callback to clean up custom allocations. */ + /* 清理自定义分配内存的回调。 */ void (*cleanup) (PGconn *conn, struct PGoauthBearerRequest *request); - char *token; /* acquired Bearer token */ - void *user; /* hook-defined allocated data */ + char *token; /* 获取的 Bearer 令牌 */ + void *user; /* 钩子定义并分配的数据 */ } PGoauthBearerRequest; - libpq会向该钩子提供两项信息:openid_configuration包含描述授权服务器所支持流程的 OAuth 发现文档 URL,而scope包含访问服务器所需的 OAuth scope 列表(以空格分隔,可以为空)。两者中的任意一个或两个都可能为NULL,表示无法发现该信息。(在这种情况下,实现可以通过其他预先配置的知识来确定要求,或者选择失败。) + libpq会向该钩子提供两项信息:openid_configuration包含描述授权服务器所支持流程的 OAuth 发现文档 URL,而scope包含访问服务器所需的 OAuth 授权范围列表(以空格分隔,可以为空)。两者中的任意一个或两个都可能为NULL,表示无法发现该信息。(在这种情况下,实现可以通过其他预先配置的知识来确定要求,或者选择失败。) - 该钩子的最终输出是token,它必须指向一个可在该连接上使用的有效 Bearer 令牌。(该令牌应由所指定的发行者签发,并持有所请求的 scope,否则连接会被服务器的验证器模块拒绝。)分配得到的令牌字符串必须在libpq完成连接之前始终有效;该钩子应设置cleanup回调,以便在libpq不再需要该令牌时调用。 + 该钩子的最终输出是token,它必须指向一个可在该连接上使用的有效 Bearer 令牌。(该令牌应由所指定的签发者签发,并持有所请求的授权范围,否则连接会被服务器的验证器模块拒绝。)分配得到的令牌字符串必须在libpq完成连接之前始终有效;该钩子应设置cleanup回调,以便在libpq不再需要该令牌时调用。 - 如果某个实现无法在首次调用钩子时立即产生token,则应设置async回调,以处理与授权服务器之间的非阻塞通信。 - + 如果实现在首次调用钩子时无法立即生成 token,应设置 async 回调,以处理与授权服务器之间的非阻塞通信。 + PQAUTHDATA_OAUTH_BEARER_TOKEN钩子回调中执行阻塞操作,会干扰诸如PQconnectPoll之类的非阻塞连接 API,并阻止并发连接继续推进。那些只使用同步连接原语(例如PQconnectdb)的应用程序,可以在钩子中同步获取令牌,而不是实现async回调,但这样它们必然一次只能处理一个连接。 - 从钩子返回后,将立即调用该回调以启动流程。当回调在不阻塞的情况下无法继续推进时,它应在设置*altsock后返回PGRES_POLLING_READINGPGRES_POLLING_WRITING,其中*altsock是当可以再次取得进展时会被标记为可读/可写的文件描述符。(然后,这个描述符会通过PQsocket()提供给顶层轮询循环。)当流程完成时,在设置好token之后返回PGRES_POLLING_OK;如果失败,则返回PGRES_POLLING_FAILED。 - +从钩子返回后,会立即调用该回调以启动流程。当回调无法在不阻塞的情况下继续时,应先将 *altsock 设为一个文件描述符,该描述符会在可以继续时被标记为可读或可写,然后返回 PGRES_POLLING_READINGPGRES_POLLING_WRITING。(该描述符随后会通过 PQsocket() 提供给顶层轮询循环。)流程完成时,应先设置 token,再返回 PGRES_POLLING_OK;返回 PGRES_POLLING_FAILED 表示失败。 + - 实现可能希望在多次调用asynccleanup回调之间保存额外的数据用于记账。为此提供了user指针;libpq不会触碰其内容,应用程序可以按自己的需要使用它。(记得在令牌清理时释放相关分配。) + 实现可能希望在多次调用asynccleanup回调之间保存额外的数据用于记录状态。为此提供了user指针;libpq不会触碰其内容,应用程序可以按自己的需要使用它。(记得在令牌清理时释放相关分配。) @@ -8050,7 +7649,7 @@ typedef struct PGoauthBearerRequest - 在线程化程序中的行为 + 多线程程序中的行为 线程 @@ -8089,7 +7688,7 @@ int PQisthreadsafe(); - 已废弃的函数不是线程安全的,不应在多线程程序中使用。可以用替代;可以用替代。 + 已弃用的函数 不是线程安全的,不应在多线程程序中使用。 可以用 替代; 可以用 替代。 @@ -8097,13 +7696,13 @@ int PQisthreadsafe(); - 同样地,如果你在应用程序中使用Curl,并且在启动新线程之前还没有先对 libcurl 进行全局初始化,那么你也需要通过PQregisterThreadLock协作地为任何可能初始化 libcurl 的代码加锁。对于支持线程安全初始化的较新版本Curl,这一限制已被解除;这类构建可以通过其版本元数据中声明的threadsafe特性识别出来。 + 同样地,如果你在应用程序中使用Curl并且在启动新线程之前还没有先对 libcurl 进行全局初始化,那么你也需要通过PQregisterThreadLock协作地为任何可能初始化 libcurl 的代码加锁。对于支持线程安全初始化的较新版本Curl,这一限制已被解除;这类构建可以通过其版本元数据中声明的threadsafe特性识别出来。 - 编译 <application>libpq</application> 程序 + 构建 <application>libpq</application> 程序 编译 @@ -8111,16 +7710,16 @@ int PQisthreadsafe(); - 要编译(即编译并且链接)一个使用libpq的程序,你需要做下列所有的事情: + 要构建(即编译和链接)一个使用 libpq 的程序,需要完成以下所有步骤: - 包括libpq-fe.h头文件: + 包含 libpq-fe.h 头文件: #include <libpq-fe.h> - 如果你无法这样做,那么你通常会从你的编译器得到像这样的错误消息: +如果没有这样做,编译器通常会给出类似以下内容的错误消息: foo.c: In function `main': foo.c:34: `PGconn' undeclared (first use in this function) @@ -8129,24 +7728,24 @@ foo.c:54: `CONNECTION_BAD' undeclared (first use in this function) foo.c:68: `PGRES_COMMAND_OK' undeclared (first use in this function) foo.c:95: `PGRES_TUPLES_OK' undeclared (first use in this function) - + - 通过为你的编译器提供-Idirectory选项,向你的编译器指出PostgreSQL头文件安装在哪里(在某些情况下编译器默认将查看该目录,因此你可以忽略这个选项)。例如你的编译命令行可能看起来像: + 向编译器提供 -Idirectory 选项,指定 PostgreSQL 头文件的安装目录。(某些情况下,编译器默认会搜索该目录,此时可以省略这个选项。)例如,编译命令行可以是: cc -c -I/usr/local/pgsql/include testprog.c - 如果你在使用 makefile,那么把该选项加到CPPFLAGS变量中: +如果使用 makefile,请将该选项添加到 CPPFLAGS 变量中: CPPFLAGS += -I/usr/local/pgsql/include - +
如果你的程序可能由其他用户编译,那么你不应该像那样硬编码目录位置。你可以运行工具pg_configpg_configwith libpq在本地系统上找出头文件在哪里: + sortas="libpq">用于 libpq在本地系统上找出头文件在哪里: $ pg_config --includedir /usr/local/include @@ -8154,8 +7753,7 @@ CPPFLAGS += -I/usr/local/pgsql/include - 如果你安装了pkg-configpkg-configwith - libpq,你可以运行: + 如果你安装了pkg-configpkg-config用于 libpq,你可以运行: $ pkg-config --cflags libpq -I/usr/local/include @@ -8164,20 +7762,20 @@ CPPFLAGS += -I/usr/local/pgsql/include - 无法为编译器指定正确的选项将导致一个错误消息,例如: + 未向编译器指定正确的选项将导致类似以下内容的错误消息: testlibpq.c:8:22: libpq-fe.h: No such file or directory - +
- 当链接最终的程序时,指定选项-lpq,这样libpq库会被编译进去,也可以用选项-Ldirectory向编译器指出libpq库所在的位置(再次,编译器将默认搜索某些目录)。为了最大的可移植性,将选项放在选项前面。例如: + 链接最终程序时,指定 -lpq 选项以链接 libpq 库,同时指定 -Ldirectory 选项,告知编译器 libpq 库所在的目录。(同样,编译器默认会搜索某些目录。)为获得最大的可移植性,请将 选项放在 选项之前。例如: cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq - +
你也可以使用pg_config找出库目录: @@ -8204,7 +7802,7 @@ testlibpq.o(.text+0x60): undefined reference to `PQsetdbLogin' testlibpq.o(.text+0x71): undefined reference to `PQstatus' testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' - 这意味着你忘了 . + 这意味着你忘记了 /usr/bin/ld: cannot find -lpq @@ -8221,7 +7819,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' 示例程序 - 这些示例和其他示例可以在源代码发布的src/test/examples目录中找到。 + 这些示例和其他示例可在源代码发行包的src/test/examples目录中找到。 @@ -8236,7 +7834,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' * * testlibpq.c * - * Test the C version of libpq, the PostgreSQL frontend library. + * 测试 PostgreSQL 前端库 libpq 的 C 语言版本。 */ #include #include @@ -8260,26 +7858,25 @@ main(int argc, char **argv) j; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -8290,19 +7887,17 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Our test case here involves using a cursor, for which we must be inside - * a transaction block. We could do the whole thing with a single - * PQexec() of "select * from pg_database", but that's too trivial to make - * a good example. + * 这里的测试用例使用游标,因此必须处于事务块内。 + * 只需调用一次 PQexec() 执行 "select * from pg_database" 就能完成全部操作, + * 但这太简单了,不足以作为一个好的示例。 */ - /* Start a transaction block */ + /* 开始一个事务块 */ res = PQexec(conn, "BEGIN"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -8313,7 +7908,7 @@ main(int argc, char **argv) PQclear(res); /* - * Fetch rows from pg_database, the system catalog of databases + * 从数据库系统目录 pg_database 中获取行 */ res = PQexec(conn, "DECLARE myportal CURSOR FOR select * from pg_database"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -8332,13 +7927,13 @@ main(int argc, char **argv) exit_nicely(conn); } - /* first, print out the attribute names */ + /* 首先,打印属性名 */ nFields = PQnfields(res); for (i = 0; i < nFields; i++) printf("%-15s", PQfname(res, i)); printf("\n\n"); - /* next, print out the rows */ + /* 接着,打印各行 */ for (i = 0; i < PQntuples(res); i++) { for (j = 0; j < nFields; j++) @@ -8348,15 +7943,15 @@ main(int argc, char **argv) PQclear(res); - /* close the portal ... we don't bother to check for errors ... */ + /* 关闭 portal……这里不再检查错误…… */ res = PQexec(conn, "CLOSE myportal"); PQclear(res); - /* end the transaction */ + /* 结束事务 */ res = PQexec(conn, "END"); PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -8376,15 +7971,15 @@ main(int argc, char **argv) * * * testlibpq2.c - * Test of the asynchronous notification interface + * 测试异步通知接口 * - * Start this program, then from psql in another window do + * 启动此程序,然后在另一个窗口中通过 psql 执行 * NOTIFY TBL2; - * Repeat four times to get this program to exit. + * 重复四次后,此程序便会退出。 * - * Or, if you want to get fancy, try this: - * populate a database with the following commands - * (provided in src/test/examples/testlibpq2.sql): + * 或者,可以尝试更复杂的示例: + * 使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq2.sql 中): * * CREATE SCHEMA TESTLIBPQ2; * SET search_path = TESTLIBPQ2; @@ -8393,7 +7988,7 @@ main(int argc, char **argv) * CREATE RULE r1 AS ON INSERT TO TBL1 DO * (INSERT INTO TBL2 VALUES (new.i); NOTIFY TBL2); * - * Start this program, then from psql do this four times: + * 启动此程序,然后通过 psql 将以下命令执行四次: * * INSERT INTO TESTLIBPQ2.TBL1 VALUES (10); */ @@ -8405,11 +8000,9 @@ main(int argc, char **argv) #include #include #include +#include #include #include -#ifdef HAVE_SYS_SELECT_H -#include -#endif #include "libpq-fe.h" @@ -8430,26 +8023,25 @@ main(int argc, char **argv) int nnotifies; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -8460,13 +8052,12 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Issue LISTEN command to enable notifications from the rule's NOTIFY. + * 发出 LISTEN 命令,以接收规则中的 NOTIFY 发出的通知。 */ res = PQexec(conn, "LISTEN TBL2"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -8477,14 +8068,13 @@ main(int argc, char **argv) } PQclear(res); - /* Quit after four notifies are received. */ + /* 收到四次通知后退出。 */ nnotifies = 0; while (nnotifies < 4) { /* - * Sleep until something happens on the connection. We use select(2) - * to wait for input, but you could also use poll() or similar - * facilities. + * 休眠,直到连接上有事件发生。这里使用 select(2) 等待输入, + * 也可以使用 poll() 或类似机制。 */ int sock; fd_set input_mask; @@ -8492,7 +8082,7 @@ main(int argc, char **argv) sock = PQsocket(conn); if (sock < 0) - break; /* shouldn't happen */ + break; /* 不应发生 */ FD_ZERO(&input_mask); FD_SET(sock, &input_mask); @@ -8503,7 +8093,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Now check for input */ + /* 现在检查是否有输入 */ PQconsumeInput(conn); while ((notify = PQnotifies(conn)) != NULL) { @@ -8518,7 +8108,7 @@ main(int argc, char **argv) fprintf(stderr, "Done.\n"); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -8538,10 +8128,10 @@ main(int argc, char **argv) * * * testlibpq3.c - * Test out-of-line parameters and binary I/O. + * 测试在 SQL 命令文本之外独立传递的参数和二进制 I/O。 * - * Before running this, populate a database with the following commands - * (provided in src/test/examples/testlibpq3.sql): + * 运行前,使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq3.sql 中): * * CREATE SCHEMA testlibpq3; * SET search_path = testlibpq3; @@ -8550,7 +8140,7 @@ main(int argc, char **argv) * INSERT INTO test1 values (1, 'joe''s place', '\000\001\002\003\004'); * INSERT INTO test1 values (2, 'ho there', '\004\003\002\001\000'); * - * The expected output is: + * 预期输出为: * * tuple 0: got * i = (4 bytes) 1 @@ -8574,7 +8164,7 @@ main(int argc, char **argv) #include #include "libpq-fe.h" -/* for ntohl/htonl */ +/* 用于 ntohl/htonl */ #include #include @@ -8586,9 +8176,8 @@ exit_nicely(PGconn *conn) } /* - * This function prints a query result that is a binary-format fetch from - * a table defined as in the comment above. We split it out because the - * main() function uses it twice. + * 此函数打印从上面注释所定义的表中以二进制格式获取的查询结果。 + * 由于 main() 会使用它两次,因此将它单独提取成一个函数。 */ static void show_binary_results(PGresult *res) @@ -8599,7 +8188,7 @@ show_binary_results(PGresult *res) t_fnum, b_fnum; - /* Use PQfnumber to avoid assumptions about field order in result */ + /* 使用 PQfnumber,以避免对结果中的字段顺序作出假设 */ i_fnum = PQfnumber(res, "i"); t_fnum = PQfnumber(res, "t"); b_fnum = PQfnumber(res, "b"); @@ -8612,24 +8201,22 @@ show_binary_results(PGresult *res) int blen; int ival; - /* Get the field values (we ignore possibility they are null!) */ + /* 获取字段值(这里忽略它们可能为 null 的情况!) */ iptr = PQgetvalue(res, i, i_fnum); tptr = PQgetvalue(res, i, t_fnum); bptr = PQgetvalue(res, i, b_fnum); /* - * The binary representation of INT4 is in network byte order, which - * we'd better coerce to the local byte order. + * INT4 的二进制表示采用网络字节序,最好将其转换为本机字节序。 */ ival = ntohl(*((uint32_t *) iptr)); /* - * The binary representation of TEXT is, well, text, and since libpq - * was nice enough to append a zero byte to it, it'll work just fine - * as a C string. + * TEXT 的二进制表示就是文本,而 libpq 会在其后追加一个零字节, + * 因此可以直接将其用作 C 字符串。 * - * The binary representation of BYTEA is a bunch of bytes, which could - * include embedded nulls so we have to pay attention to field length. + * BYTEA 的二进制表示是一组字节,其中可能嵌有零字节, + * 因此必须注意字段长度。 */ blen = PQgetlength(res, i, b_fnum); @@ -8657,26 +8244,25 @@ main(int argc, char **argv) uint32_t binaryIntVal; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SET search_path = testlibpq3"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -8687,27 +8273,25 @@ main(int argc, char **argv) PQclear(res); /* - * The point of this program is to illustrate use of PQexecParams() with - * out-of-line parameters, as well as binary transmission of data. + * 此程序旨在演示如何使用 PQexecParams() 在 SQL 命令文本之外独立传递参数, + * 以及如何以二进制方式传输数据。 * - * This first example transmits the parameters as text, but receives the - * results in binary format. By using out-of-line parameters we can avoid - * a lot of tedious mucking about with quoting and escaping, even though - * the data is text. Notice how we don't have to do anything special with - * the quote mark in the parameter value. + * 第一个示例以文本形式传输参数,但以二进制格式接收结果。 + * 通过在 SQL 命令文本之外独立传递参数,即使数据是文本,也可以避免 + * 许多繁琐的引号和转义处理。注意,参数值中的引号无需任何特殊处理。 */ - /* Here is our out-of-line parameter value */ + /* 这是在 SQL 命令文本之外独立传递的参数值 */ paramValues[0] = "joe's place"; res = PQexecParams(conn, "SELECT * FROM test1 WHERE t = $1", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, - NULL, /* don't need param lengths since text */ - NULL, /* default to all text params */ - 1); /* ask for binary results */ + NULL, /* 文本参数无需指定长度 */ + NULL, /* 默认所有参数均为文本 */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -8721,31 +8305,29 @@ main(int argc, char **argv) PQclear(res); /* - * In this second example we transmit an integer parameter in binary form, - * and again retrieve the results in binary form. + * 第二个示例以二进制形式传输一个整数参数,并同样以二进制形式获取结果。 * - * Although we tell PQexecParams we are letting the backend deduce - * parameter type, we really force the decision by casting the parameter - * symbol in the query text. This is a good safety measure when sending - * binary parameters. + * 虽然我们告诉 PQexecParams 让后端推断参数类型,但实际上, + * 查询文本中的参数符号经过强制类型转换,因此其类型已经确定。 + * 发送二进制参数时,这是一项良好的安全措施。 */ - /* Convert integer value "2" to network byte order */ + /* 将整数值 "2" 转换为网络字节序 */ binaryIntVal = htonl((uint32_t) 2); - /* Set up parameter arrays for PQexecParams */ + /* 为 PQexecParams 设置参数数组 */ paramValues[0] = (char *) &binaryIntVal; paramLengths[0] = sizeof(binaryIntVal); - paramFormats[0] = 1; /* binary */ + paramFormats[0] = 1; /* 二进制 */ res = PQexecParams(conn, "SELECT * FROM test1 WHERE i = $1::int4", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, paramLengths, paramFormats, - 1); /* ask for binary results */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -8758,7 +8340,7 @@ main(int argc, char **argv) PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; diff --git a/zh/18/lobj.sgml b/zh/18/lobj.sgml index ee9815e3..4a31786c 100644 --- a/zh/18/lobj.sgml +++ b/zh/18/lobj.sgml @@ -3,8 +3,8 @@ 大对象 - large object - BLOBlarge object + 大对象 + BLOB大对象 PostgreSQL提供一种大对象机制,允许以流式方式访问存储在专用大对象结构中的用户数据。在处理大到无法方便地整体操作的数据值时,这种流式访问非常有用。 @@ -19,7 +19,7 @@ TOAST - versus large objects + 与大对象对比 @@ -190,11 +190,11 @@ inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE); int lo_write(PGconn *conn, int fd, const char *buf, size_t len); - 将buf中的len字节(其大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 + 将buf中的len字节(缓冲区大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -211,7 +211,7 @@ int lo_read(PGconn *conn, int fd, char *buf, size_t len); - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -277,7 +277,7 @@ int64_t lo_tell64(PGconn *conn, int fd); int lo_truncate(PGconn *conn, int fd, size_t len); - 该函数把大对象描述符fd截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用空字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 + 该函数把大对象描述符fd对应的大对象截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用零字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 @@ -426,16 +426,16 @@ CREATE TABLE image ( raster oid ); -SELECT lo_creat(-1); -- returns OID of new, empty large object +SELECT lo_creat(-1); -- 返回新建的空大对象的 OID -SELECT lo_create(43213); -- attempts to create large object with OID 43213 +SELECT lo_create(43213); -- 尝试创建 OID 为 43213 的大对象 -SELECT lo_unlink(173454); -- deletes large object with OID 173454 +SELECT lo_unlink(173454); -- 删除 OID 为 173454 的大对象 INSERT INTO image (name, raster) VALUES ('beautiful image', lo_import('/etc/motd')); -INSERT INTO image (name, raster) -- same as above, but specify OID to use +INSERT INTO image (name, raster) -- 与上例相同,但指定要使用的 OID VALUES ('beautiful image', lo_import('/etc/motd', 68583)); SELECT lo_export(image.raster, '/tmp/motd') FROM image @@ -444,7 +444,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image - 服务器端的lo_importlo_export函数与其客户端对应函数的行为差异很大。这两个函数在服务器的文件系统中读写文件,使用数据库所有者的权限。因此,默认情况下它们的使用仅限于超级用户。相比之下,客户端导入和导出函数在客户端的文件系统中读写文件,使用客户端程序的权限。客户端函数不需要任何数据库权限,除了读取或写入相关大对象所需的权限。 + 服务器端的lo_importlo_export函数与其客户端对应函数的行为差异很大。这两个函数在服务器的文件系统中读写文件,使用运行数据库服务器的操作系统用户的权限。因此,默认情况下它们的使用仅限于超级用户。相比之下,客户端导入和导出函数在客户端的文件系统中读写文件,使用客户端程序的权限。客户端函数不需要任何数据库权限,除了读取或写入相关大对象所需的权限。 @@ -463,7 +463,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image 示例程序 - 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行版的src/test/examples/testlo.c中找到。 + 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行包的src/test/examples/testlo.c中找到。 @@ -472,13 +472,13 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /*----------------------------------------------------------------- * * testlo.c - * test using large objects with libpq + * 测试使用 libpq 操作大对象 * * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group * Portions Copyright (c) 1994, Regents of the University of California * * - * IDENTIFICATION + * 标识 * src/test/examples/testlo.c * *----------------------------------------------------------------- @@ -498,7 +498,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /* * importFile - - * import file "in_filename" into database as large object "lobjOid" + * 将文件 "in_filename" 作为大对象 "lobjOid" 导入数据库 * */ static Oid @@ -512,16 +512,16 @@ importFile(PGconn *conn, char *filename) int fd; /* - * open the file to be read in + * 打开要读取的文件 */ fd = open(filename, O_RDONLY, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"\n", filename); } /* - * create the large object + * 创建大对象 */ lobjId = lo_creat(conn, INV_READ | INV_WRITE); if (lobjId == 0) @@ -530,7 +530,7 @@ importFile(PGconn *conn, char *filename) lobj_fd = lo_open(conn, lobjId, INV_WRITE); /* - * read in from the Unix file and write to the inversion file + * 从 Unix 文件读取数据并写入大对象 */ while ((nbytes = read(fd, buf, BUFSIZE)) > 0) { @@ -568,7 +568,7 @@ pickout(PGconn *conn, Oid lobjId, int start, int len) fprintf(stderr, ">>> %s", buf); nread += nbytes; if (nbytes <= 0) - break; /* no more data? */ + break; /* 没有更多数据? */ } free(buf); fprintf(stderr, "\n"); @@ -614,7 +614,7 @@ overwrite(PGconn *conn, Oid lobjId, int start, int len) /* * exportFile - - * export large object "lobjOid" to file "out_filename" + * 将大对象 "lobjOid" 导出到文件 "out_filename" * */ static void @@ -627,24 +627,24 @@ exportFile(PGconn *conn, Oid lobjId, char *filename) int fd; /* - * open the large object + * 打开大对象 */ lobj_fd = lo_open(conn, lobjId, INV_READ); if (lobj_fd < 0) fprintf(stderr, "cannot open large object %u", lobjId); /* - * open the file to be written to + * 打开要写入的文件 */ fd = open(filename, O_CREAT | O_WRONLY | O_TRUNC, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"", filename); } /* - * read in from the inversion file and write to the Unix file + * 从大对象读取数据并写入 Unix 文件 */ while ((nbytes = lo_read(conn, lobj_fd, buf, BUFSIZE)) > 0) { @@ -689,18 +689,18 @@ main(int argc, char **argv) out_filename = argv[3]; /* - * set up the connection + * 建立连接 */ conn = PQsetdb(NULL, NULL, NULL, NULL, database); - /* check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) diff --git a/zh/18/monitoring.sgml b/zh/18/monitoring.sgml index fc12a802..65e3c607 100644 --- a/zh/18/monitoring.sgml +++ b/zh/18/monitoring.sgml @@ -4435,7 +4435,8 @@ description | Waiting for a newly initialized WAL file to reach durable storage checksum_failures bigint
- 在此数据库(或共享对象)中检测到的数据页校验码失败数,如果没有启用数据校验码则为NULL。 + 在此数据库(或共享对象)中检测到的数据页校验和失败次数,如果未启用 + 数据校验和则为 NULL。
@@ -4444,7 +4445,8 @@ description | Waiting for a newly initialized WAL file to reach durable storage checksum_last_failure timestamp with time zone - 在此数据库(或共享对象)中检测到最后一个数据页校验码失败的时间,如果没有启用数据校验码则为NULL。 + 在此数据库(或共享对象)中最后一次检测到数据页校验和失败的时间, + 如果未启用数据校验和则为 NULL。 diff --git a/zh/18/oauth-validators.sgml b/zh/18/oauth-validators.sgml index 844616e9..81f75617 100644 --- a/zh/18/oauth-validators.sgml +++ b/zh/18/oauth-validators.sgml @@ -80,27 +80,27 @@ 接下来,验证器必须确保终端用户已授权客户端代表其访问服务器。 - 这通常需要检查分配给令牌的作用域(scope), + 这通常需要检查分配给令牌的授权范围, 以确认其覆盖当前 HBA 参数所要求的数据库访问权限。 该步骤的目的是防止 OAuth 客户端在虚假前提下获取令牌。 - 如果验证器要求所有令牌都必须携带覆盖数据库访问的作用域, + 如果验证器要求所有令牌都必须携带覆盖数据库访问的授权范围, 提供方在流程中就应明确提示用户授予该访问权限。 这样一来,如果客户端本不应使用其凭据连接数据库, 用户就有机会拒绝该请求。 - 也可以通过部署架构的带外知识在没有显式作用域的情况下完成客户端授权, + 也可以通过部署架构的带外知识在没有显式授权范围的情况下完成客户端授权, 但这样会让用户无法参与授权过程, 用户将无法发现部署错误,而此类错误也可能被静默利用。 - 如果不提示用户授予额外作用域, + 如果不提示用户授予额外授权范围, 则对数据库的访问必须被严格限制为仅允许受信任客户端 即,“受信任”是指 OAuth 客户端与 PostgreSQL 服务器由同一实体控制。 - 特别地,libpq 支持的 Device Authorization 客户端流程通常不满足此条件, + 特别地,libpq 支持的设备授权客户端流程通常不满足此条件, 因为它的设计目标是公开/非受信任客户端。 @@ -236,7 +236,7 @@ 若要完全绕过用户名映射,并让验证器模块承担额外的用户连接授权职责, 可在 HBA 中配置 。 - 此后模块可使用令牌作用域或等效方法判断用户是否允许以其期望角色连接。 + 此后模块可使用令牌授权范围或等效方法判断用户是否允许以其期望角色连接。 用户标识符仍会由服务器记录,但它不再参与是否继续连接的判定。 diff --git a/zh/18/pgtrgm.sgml b/zh/18/pgtrgm.sgml index 09cc6fe5..fa60934c 100644 --- a/zh/18/pgtrgm.sgml +++ b/zh/18/pgtrgm.sgml @@ -513,11 +513,11 @@ SELECT * FROM test_trgm WHERE t ~ '(foo|bar)'; - 文本搜索集成 + 文本检索集成 与全文索引结合使用时,三字符组匹配是非常有用的工具。 - 尤其是,它有助于识别那些因拼写错误而无法被全文搜索机制直接匹配的输入词。 + 尤其是,它有助于识别那些因拼写错误而无法被全文检索机制直接匹配的输入词。 diff --git a/zh/18/protocol.sgml b/zh/18/protocol.sgml index 4607effe..5c467338 100644 --- a/zh/18/protocol.sgml +++ b/zh/18/protocol.sgml @@ -26,15 +26,15 @@ 概述 - 协议在启动和正常操作过程中有不同的阶段。在启动阶段里,前端打开一个到服务器的连接并且认证自身以满足服务器(这可能涉及到一条或多条消息,取决于使用的认证方法)。 如果一切正常,服务器就发送状态信息给前端,并最后进入正常操作。除了最初的启动请求消息之外,协议的这个部分是服务器驱动的。 + 协议分为启动和正常操作两个阶段。在启动阶段,前端打开到服务器的连接,并完成服务器所要求的认证。(这可能只涉及一条消息,也可能因所用认证方法不同而需要多条消息。)如果一切顺利,服务器随后会向前端发送状态信息,并最终进入正常操作。除最初的启动请求消息外,协议的这一部分由服务器驱动。 - 在正常操作中,前端发送查询和其它命令到后端,然后后端返回查询结果和其它响应。在少数几种情况(比如NOTIFY)中,后端会发送未被请求的消息,但这个会话中的绝大多部分都是由前端请求驱动的。 + 在正常操作中,前端向后端发送查询及其他命令,后端则返回查询结果和其他响应。少数情况下(例如 NOTIFY),后端会发送未请求的消息,但会话中的绝大多数交互仍由前端请求驱动。 - 会话的终止通常是由前端来选择的,但是也可以在某些情况下由后端强制执行。不管在那种情况下,如果后端关闭连接,那么它将在退出之前回滚所有打开的(未完成的)事务。 + 会话通常由前端选择终止,但在某些情况下也可能由后端强制终止。无论哪种情况,后端关闭连接时,都会在退出前回滚所有打开的(未完成的)事务。 @@ -73,9 +73,7 @@ 整个执行周期包括一个解析步骤,它从文本查询字符串创建预备语句; 一个绑定步骤,它根据预备语句和所需参数值创建 portal; - 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询 - (SELECTSHOW等),可以要求执行步骤只取回 - 有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 + 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询(SELECTSHOW等),可以要求执行步骤只取回有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 @@ -92,8 +90,8 @@ - 文本形式的数值是特定数据类型的输入/输出转换函数生成或接受的任何字符串。在传输形式上,字符串没有末尾空字符;如果前端要想把收到的值当作C字符串处理,那么必须自己加上一个(顺便说一下,文本格式不允许嵌入空字符)。 - + 值的文本表示是相应数据类型的输入/输出转换函数生成和接受的字符串。在传输形式中,值的末尾没有空字符;前端若要将收到的值作为 C 字符串处理,必须自行添加一个。(文本格式也不允许内嵌空字符。) + 整数的二进制表示采用网络字节序(最高有效字节在前)。至于其他数据类型,请查阅文档或源代码了解其二进制表示形式。要注意,复杂数据类型的二进制表示可能会在不同服务器版本之间发生变化;文本格式通常是可移植性更好的选择。 @@ -134,12 +132,12 @@ 3.2 PostgreSQL 18 及以后 - 当前最新版本。用于取消查询的 secret key 从 4 字节扩展为可变长度字段;BackendKeyData 与 CancelRequest 消息相应调整为可变长度负载。 + 当前最新版本。用于取消查询的密钥从 4 字节扩展为可变长度字段。BackendKeyData 消息已作相应调整,CancelRequest 消息则重新定义为使用可变长度负载。 3.1 - - 保留。PostgreSQL 从未使用 3.1;之所以跳过该版本,是因为旧版 pgbouncer 在协议协商中存在缺陷,会错误宣称支持 3.1。 + 保留。PostgreSQL 从未使用 3.1;之所以跳过该版本,是因为广泛使用的 pgbouncer 的旧版本在协议协商中存在缺陷,会错误宣称支持 3.1。 3.0 @@ -169,7 +167,7 @@ 启动 - 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,判断该连接在初步上是否可接受,以及是否需要额外的认证。 + 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,初步判断是否接受该连接,以及需要何种额外认证(如果需要)。 @@ -416,7 +414,7 @@ 表示即将返回行作为对SELECTFETCH等查询的响应。 - 此消息的内容描述了行的列布局。这将跟随每个返回给前端的行的DataRow消息。 + 此消息的内容描述了行的列布局。该消息之后,每个返回给前端的行都对应一条 DataRow 消息。 @@ -472,9 +470,7 @@ - - 对 SELECT 查询(或其他返回行集的查询,如 EXPLAINSHOW)的响应,通常包含 RowDescription、零条或多条 DataRow 消息,以及最后的 CommandComplete。向前端 COPY 或从前端 COPY 会调用中描述的特殊协议。所有其他类型的查询通常只产生一条 CommandComplete 消息。 - + SELECT 查询(或其他返回行集的查询,如 EXPLAINSHOW)的响应通常包含 RowDescription、零条或多条 DataRow 消息,以及最后的 CommandComplete。在前端与服务器之间执行 COPY 输入或输出时,会使用 所述的特殊协议。所有其他类型的查询通常只产生一条 CommandComplete 消息。 由于查询字符串可能包含若干条查询(以分号分隔),因此在后端完成整个查询字符串的处理之前,可能会出现多个这样的响应序列。只有在整个字符串处理完毕且后端已准备好接受新的查询字符串时,才会发出 ReadyForQuery 消息。 @@ -497,15 +493,15 @@ - 我们建议的方法是把前端代码写成状态机的风格,它可以在任何时刻接受任何有意义的消息类型,而不是假设消息的序列总是准确。 - + 建议以状态机的方式编写前端,使其能够在任何合理的时机接收相应类型的消息,而不把消息确切顺序的假设写死在代码中。 + 一个简单查询中的多条语句 - 当一个简单查询消息中包含多于一条SQL语句(被分号分隔)时,那些语句会被当做一个事务中执行,除非其中包括显式事务控制命令来强制不同的行为。例如,如果消息包括 + 当一个简单查询消息中包含多于一条SQL语句(被分号分隔)时,这些语句会作为单个事务执行,除非其中包括显式事务控制命令来强制不同的行为。例如,如果消息包括 INSERT INTO mytable VALUES(1); SELECT 1/0; @@ -527,15 +523,15 @@ SELECT 1/0; - 这种行为通过在一个隐式事务块中的一个多语句Query消息中运行那些语句来实现,除非它们运行在某个显式事务块中。隐式事务块与常规事务块之间的区别在于隐式块会在Query消息结束时自动被关闭,或者是在没有错误的情况下由一个隐式提交关闭,或者是在有错误时由一个隐式的回滚关闭。这类似于一个语句自己执行(当不在事务块中时)时发生的隐式提交或回滚。 - + 这种行为的实现方式是:除非已有显式事务块可供这些语句执行,否则就在一个隐式事务块中执行多语句 Query 消息中的语句。隐式事务块与常规事务块的主要区别在于,隐式块会在 Query 消息结束时自动关闭:没有错误时隐式提交,发生错误时隐式回滚。这类似于单独执行一条语句(不在事务块中)时发生的隐式提交或回滚。 + - 如果会话已经在一个事务块中,作为前面某个消息中BEGIN的结果,那么Query消息会简单地继续那个事务块,不管该消息包含一个语句还是多个语句。不过,如果该Query消息包含一个关闭现有事务块的COMMIT或者ROLLBACK,那么任何接下来的语句都会在一个隐式事务块中被执行。反过来,如果在多语句Query消息中出现一个BEGIN,那么它会开始一个常规事务块,这个常规事务块将只能被一个显式的COMMIT或者ROLLBACK终止,不管这两种命令是出现在这个Query消息还是后面的一个Query消息中。如果BEGIN跟在一些作为隐式事务块执行的语句后面,那些语句不会被立刻提交。实际上,它们会被包括到新的常规事务块中。 + 如果会话因前面某条消息中的BEGIN而已经处于事务块中,那么 Query 消息会继续该事务块,不管该消息包含一个语句还是多个语句。不过,如果该Query消息包含一个关闭现有事务块的COMMIT或者ROLLBACK,那么任何接下来的语句都会在一个隐式事务块中被执行。反过来,如果在多语句Query消息中出现一个BEGIN,那么它会开始一个常规事务块,这个常规事务块将只能被一个显式的COMMIT或者ROLLBACK终止,不管这两种命令是出现在这个Query消息还是后面的一个Query消息中。如果BEGIN跟在一些作为隐式事务块执行的语句后面,那些语句不会被立刻提交。实际上,它们会被包括到新的常规事务块中。 - 出现在一个隐式事务块中的COMMIT或者ROLLBACK会被正常执行并且关闭该隐式块。不过,由于没有先前的BEGIN配对的COMMIT或者ROLLBACK表示一种错误,所以将会发出一个警告。如果后面还有更多语句,将会为它们开始一个新的隐式事务块。 + 出现在一个隐式事务块中的COMMIT或者ROLLBACK会被正常执行并且关闭该隐式块。不过,由于没有先前的BEGIN配对的COMMIT或者ROLLBACK可能表示误操作,所以会发出警告。如果后面还有更多语句,将会为它们开始一个新的隐式事务块。 @@ -543,17 +539,17 @@ SELECT 1/0; - 记住,不管任何事务控制命令存不存在,Query消息的执行会在第一个错误时停止。因此,对于下面的在一个Query消息中的示例 + 请记住,无论消息中是否包含事务控制命令,Query 消息的执行都会在第一个错误处停止。例如,单条 Query 消息包含以下内容时: BEGIN; SELECT 1/0; ROLLBACK; - 会话中将留下一个失败的常规事务块,因为在出现除零错误后不会到达ROLLBACK。将需要另一个ROLLBACK把会话恢复到一种可用的状态。 - +会话会停留在失败的常规事务块内,因为发生除零错误后不会再执行ROLLBACK。需要另发一条ROLLBACK,才能将会话恢复到可用状态。 + - 另一种要注意的行为是,最初的词法和语法分析是在整个查询字符串被执行之前进行的。因此后面的语句中的简单错误(例如拼写错误的关键词)可能会阻止任何语句的执行。这通常对用户是不可见的,因为在当作一个隐式事务块执行时,这些语句不管怎样都会全部被回滚。不过,在尝试于一个多语句Query中执行多个事务时,这种现象可能是可见的。例如,如果一个拼写错误把我们之前的示例变成 + 另一种要注意的行为是,在执行任何语句之前,会先对整个查询字符串进行词法和语法分析。因此后面的语句中的简单错误(例如拼写错误的关键词)可能会阻止任何语句的执行。这通常对用户是不可见的,因为在当作一个隐式事务块执行时,这些语句不管怎样都会全部被回滚。不过,在尝试于一个多语句Query中执行多个事务时,这种现象可能是可见的。例如,如果一个拼写错误把我们之前的示例变成 BEGIN; INSERT INTO mytable VALUES(1); @@ -620,11 +616,11 @@ SELCT 1/0; - 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是执行不会导致后端发送 ReadyForQuery 或 RowDescription。 + 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是 Execute 不会导致后端发送 ReadyForQuery 或 RowDescription。 - 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息之一结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 + 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息中的恰好一条结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 @@ -639,7 +635,7 @@ SELCT 1/0; - 除了这些基本的、必须的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 + 除了这些基本的、必需的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 @@ -675,38 +671,32 @@ SELCT 1/0; - 流水线处理 + 管道化 - 流水线处理 + 管道化 协议规范 - 使用扩展查询协议允许流水线处理,这意味着发送一系列查询而无需等待先前的查询完成。 - 这减少了完成一系列操作所需的网络往返次数。然而,用户必须仔细考虑所需的行为,如果其中一步失败, - 因为后续查询已经在传输到服务器的过程中。 - + 扩展查询协议允许管道化,即连续发送一系列查询,而不等待先前查询完成。这减少了完成一组操作所需的网络往返次数。不过,用户必须仔细考虑其中某个步骤失败时所需的行为,因为后续查询已经在发往服务器的途中。 + - 处理这个问题的一种方法是将整个查询系列作为一个事务处理,即将其包装在BEGIN... - COMMIT中。然而,如果希望其中一些命令独立于其他命令提交,这并没有帮助。 - + 处理这个问题的一种方式是让整组查询成为单个事务,即用BEGIN ... COMMIT包围它们。不过,如果希望其中某些命令独立于其他命令提交,这种方式就无法满足要求。 + - 扩展查询协议提供了另一种管理这个问题的方式,即在依赖的步骤之间省略发送同步消息。 - 由于在错误后,后端会跳过命令消息直到找到同步消息,这允许在管道中的后续命令在前面的命令失败时自动跳过,而无需客户端明确地使用BEGINCOMMIT来管理。 - 管道中可以通过同步消息分隔独立可提交的段。 - + 扩展查询协议提供了另一种处理方式,即省略相互依赖的步骤之间的 Sync 消息。发生错误后,后端会跳过命令消息,直到遇到 Sync,因此当前面的命令失败时,管道中的后续命令便会自动跳过,而不必由客户端用BEGINCOMMIT显式管理。管道中可独立提交的各段可以用 Sync 消息分隔。 + 如果客户端没有发出显式 BEGIN,则会启动一个隐式事务块。每个 Sync 通常会在前序步骤成功时导致隐式 COMMIT,失败时导致隐式 ROLLBACK。服务器只有在第一个命令结束且尚未收到 Sync 时,才能识别这种隐式事务块。有一些 DDL 命令(例如 CREATE DATABASE)不能在事务块内执行;若这类命令在管道中执行,除非它是某个 Sync 之后的第一条命令,否则会失败。此外,它成功后会强制立即提交以保持数据库一致性。因此,紧随这些命令之后的 Sync 除了返回 ReadyForQuery 外不会产生额外效果。 - 当使用这种方法时,必须通过计算ReadyForQuery消息的数量并等待达到发送的Syncs数量来确定管道的完成。 - 计算命令完成响应是不可靠的,因为其中一些命令可能会被跳过,因此不会产生完成消息。 - + 使用这种方式时,必须统计 ReadyForQuery 消息的数量,并等待该数量达到已发送的 Sync 消息数量,才能确定管道已完成。统计命令完成响应并不可靠,因为某些命令可能被跳过,因而不会产生完成消息。 + @@ -714,8 +704,8 @@ SELCT 1/0; 函数调用 - 函数调用子协议允许客户端请求一个对存在于数据库pg_proc系统表中的任意函数的直接调用。客户端必须在该函数上有执行的权限。 - + 函数调用子协议允许客户端请求直接调用数据库pg_proc系统目录中的任意函数。客户端必须具有该函数的执行权限。 + @@ -725,8 +715,8 @@ SELCT 1/0; - 一个函数调用周期是由前端向后端发送一条FunctionCall消息初始化的。然后后端根据函数调用的结果发送一条或者更多响应消息,并且最后是一条ReadyForQuery响应消息。ReadyForQuery通知前端它可以安全地发送一个新的查询或者函数调用了。 - + 函数调用周期由前端向后端发送一条 FunctionCall 消息来启动。后端随后根据函数调用的结果发送一条或多条响应消息,最后发送一条 ReadyForQuery 响应消息。ReadyForQuery 告知前端,可以安全地发送新的查询或函数调用。 + 来自后端的可能的响应消息是: @@ -745,7 +735,7 @@ SELCT 1/0; FunctionCallResponse - 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者集合类型的结果)。 + 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者结果集合)。 @@ -780,7 +770,7 @@ SELCT 1/0; - 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(表示成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 + 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(允许成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 @@ -788,11 +778,11 @@ SELCT 1/0; - 在拷贝入模式下,后端将忽略所收到的Flush和Sync消息。收到任何其他非拷贝消息类型都会造成一个错误,它将导致上面所描述的拷贝入状态中断(Flush和Sync的例外是为了方便客户端库,它们总是在一个Execute消息之后发送Flush和Sync,而不检查被执行的命令是否为一个COPY FROM STDIN)。 - + 后端会忽略在拷贝入模式期间收到的 Flush 和 Sync 消息。收到任何其他非拷贝类型的消息都会构成错误,并按上述方式中止拷贝入状态。(Flush 和 Sync 的例外是为了方便那些总是在 Execute 消息之后发送 Flush 或 Sync、而不检查待执行命令是否为COPY FROM STDIN的客户端库。) + - 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句的时候初始化的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能退出传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 + 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句时启动的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能中止传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 @@ -800,16 +790,16 @@ SELCT 1/0; - 在CopyData消息中间可能会散布有NoticeResponse和ParameterStatus消息。前端必须处理这些情况,并且应该也为异步消息类型(参见)准备好。否则任何除CopyData或CopyDone之外的消息类型都会被认为是要中止拷贝出模式。 - + NoticeResponse 和 ParameterStatus 消息可能穿插在 CopyData 消息之间;前端必须处理这些情况,并应准备好处理其他异步消息类型(参见)。除此之外,可以将任何除 CopyData 或 CopyDone 以外的消息类型视为拷贝出模式的终止标志。 + - 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许数据以高速批量方式在客户端与服务器之间双向传输。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见。 + 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许高速批量地向服务器发送数据以及从服务器接收数据。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见 - CopyInResponse、CopyOutResponse和CopyBothResponse消息包括域和格式代码,域告诉前端每行的列数,而格式代码则用于具体每个列(就目前的实现而言,一个给定COPY操作中的所有列都将使用同样的格式,但是消息设计并不做这个假设)。 - + CopyInResponse、CopyOutResponse 和 CopyBothResponse 消息包含一些字段,用于告知前端每行的列数以及每列所使用的格式代码。(在当前实现中,同一次COPY操作的所有列都使用相同格式,但消息设计并不作此假设。) + @@ -853,8 +843,8 @@ SELCT 1/0; - 如果前端发出一个LISTEN命令, 那么无论何时在为同一个通道名NOTIFY时,后端将发送一个NotificationResponse消息(不要和NoticeResponse搞混!)。 - + 如果前端发出LISTEN命令,那么每当针对同一通道名执行NOTIFY命令时,后端都会发送一条 NotificationResponse 消息(不要与 NoticeResponse 混淆)。 + @@ -873,11 +863,11 @@ SELCT 1/0; - 要发出一条取消请求,前端打开一个与服务器的新连接并且发送一条CancelRequest消息, 而不是通常在新连接中经常发送的StartupMessage消息。服务器将处理这个请求然后关闭连接。 出于安全原因,对取消请求消息不做直接的响应。 - + 要发出取消请求,前端会新建到服务器的连接,并发送 CancelRequest 消息,而不是新连接通常发送的 StartupMessage 消息。服务器处理该请求后便会关闭连接。出于安全原因,服务器不会直接回复取消请求消息。 + - 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的关键数据(PID和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则退出当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 + 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的密钥数据(PID 和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则中止当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 @@ -885,7 +875,7 @@ SELCT 1/0; - 这么做是对安全性和有效性通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 + 这么做是对安全性和效率通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 @@ -906,11 +896,11 @@ SELCT 1/0; - 其他终止场景来自各种故障,例如任一端发生内核转储、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 + 其他终止场景来自各种故障,例如任一端发生 core dump、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 - 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果很可能在得知断开之前被提交。 + 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果可能在发现连接断开之前被提交。 @@ -924,32 +914,32 @@ SELCT 1/0; 要发起一条使用SSL加密的连接,前端首先发送 SSLRequest 消息,而不是 StartupMessage。随后服务器会响应一个包含SN的单字节,分别表示它愿意或不愿意执行SSL加密。如果前端对该响应不满意,此时可以关闭连接。若要在收到S后继续,就先与服务器完成SSL启动握手(这里不做描述,它属于SSL规范的一部分)。如果成功,再继续发送通常的 StartupMessage。在这种情况下,StartupMessage 以及后续所有数据都会被SSL加密。若要在收到N后继续,则发送通常的 StartupMessage,并在不使用加密的情况下继续。 - (另外,可以在 N 响应之后发出 GSSENCRequest 消息,尝试使用 GSSAPI 加密代替 SSL。) + (另外,可以在 N 响应之后发出 GSSENCRequest 消息,尝试使用 GSSAPI 加密代替 SSL。) - 前端也应准备处理服务器对 SSLRequest 返回的 ErrorMessage。前端不应将该错误直接展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 SSL 的情况下继续。 + 前端也应准备处理服务器对 SSLRequest 返回的 ErrorMessage。前端不应将该错误展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 SSL 的情况下继续。 - 当可以执行 SSL 加密时,服务器预计仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给他们的 SSL 库,要么在发现他们已经读取到额外的字节时将其视为协议违规。 + 当可以执行 SSL 加密时,服务器应仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给所用的 SSL 库,要么在发现已经读取到额外的字节时将其视为协议违规。 - 同样,服务器也期望客户端在收到服务器对 SSLRequest 的单字节响应之后,再开始SSL协商。如果客户端不等服务器响应到达就立即开始SSL协商,可以减少一次网络往返时延;但代价是无法处理服务器对SSL请求返回否定响应的情况。在这种情况下,服务器通常会直接断开连接,而不会继续回退到 GSSAPI、未加密连接或协议错误流程。 + 同样,服务器也期望客户端在收到服务器对SSL请求的单字节响应之后,再开始SSL协商。如果客户端不等服务器响应到达就立即开始SSL协商,可以减少一次网络往返时延;但代价是无法处理服务器对SSL请求返回否定响应的情况。在这种情况下,服务器会直接断开连接,而不会继续使用 GSSAPI 或未加密连接,也不会返回协议错误。 - 初始 SSLRequest 也可以用于那些正在建立、目的是发送 CancelRequest 消息的连接。 - + 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 SSLRequest。 + - 还支持第二种发起SSL加密的方式:客户端可以在不发送任何 SSLRequest 包的情况下,直接开始SSL协商。SSL连接建立后,服务器会在加密通道上继续等待普通的启动请求包并继续协商。在这种情况下,任何其他的加密请求都会被拒绝。这种方法不适合通用工具,因为它既不能协商出最佳的连接加密方式,也不能处理未加密连接;但在客户端和服务器都由同一方控制的环境中,它很有用,因为它可以减少一次往返时延,并允许使用依赖标准SSL连接的网络工具。使用这种风格的SSL连接时,客户端必须使用由 RFC 7301 定义的 ALPN 扩展,以防范协议混淆攻击。PostgreSQL 协议对应的 ALPN 标识是 postgresql,见 IANA TLS ALPN Protocol IDs 注册表。 + 还支持第二种发起SSL加密的方式:服务器能识别未发送任何 SSLRequest 包就立即开始SSL协商的连接。SSL连接建立后,服务器会在加密通道上继续等待普通的启动请求包并继续协商。在这种情况下,任何其他的加密请求都会被拒绝。这种方法不是通用工具的首选,因为它既不能协商出最佳的连接加密方式,也不能处理未加密连接;但在客户端和服务器都由同一方控制的环境中,它很有用,因为它可以减少一次往返时延,并允许使用依赖标准SSL连接的网络工具。使用这种风格的SSL连接时,客户端必须使用由 RFC 7301 定义的 ALPN 扩展,以防范协议混淆攻击。PostgreSQL 协议对应的 ALPN 标识是 postgresql,见 IANA TLS ALPN Protocol IDs 注册表。 - 虽然协议本身并不提供让服务器强制启用SSL加密的方法,但管理员可以把服务器配置为拒绝未加密会话,把它作为认证检查的一个副作用。 - + 虽然协议本身没有提供让服务器强制使用SSL加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + @@ -960,37 +950,27 @@ SELCT 1/0; 如果PostgreSQL构建时启用了GSSAPI支持,就可以使用GSSAPI对前端/后端通信进行加密。这为攻击者可能截获会话流量的环境提供了通信安全性。有关使用GSSAPI加密PostgreSQL会话的详细信息,请参阅。 - - 要启动一个GSSAPI加密连接,前端最初发送一个GSSENCRequest消息,而不是一个StartupMessage。 - 服务器随后会响应一个包含GN的单个字节,分别表示愿意或不愿意执行GSSAPI加密。 - 如果前端对响应不满意,可能会在此时关闭连接。 - 要在G之后继续,使用GSSAPI C绑定,如在RFC 2744 - 中讨论的,或等效的,通过在循环中调用gss_init_sec_context()来执行GSSAPI初始化, - 并将结果发送给服务器,从一个空输入开始,然后对每个来自服务器的结果进行处理,直到不再返回输出为止。 - 在将gss_init_sec_context()的结果发送给服务器时,在消息前加上以网络字节顺序表示的四字节整数的长度。 - 要在N之后继续,发送通常的StartupMessage,并在没有加密的情况下继续进行。 - (或者,可以在N响应后发出一个SSLRequest消息,尝试使用SSL加密代替GSSAPI。) - + 要建立 GSSAPI 加密连接,前端首先发送 GSSENCRequest 消息,而不是 StartupMessage。服务器随后以单个字节响应,内容为 GN,分别表示愿意或不愿意使用 GSSAPI 加密。如果前端对响应不满意,可以在此时关闭连接。收到 G 后要继续,应使用 RFC 2744 中介绍的 GSSAPI C 绑定或等效接口,在循环中调用 gss_init_sec_context() 来执行 GSSAPI 初始化,并将结果发送给服务器:先使用空输入,再依次使用服务器返回的每个结果,直到该调用不再产生输出。将 gss_init_sec_context() 的结果发送给服务器时,应在前面加上消息长度,以网络字节序的四字节整数表示。收到 N 后要继续,则发送通常的 StartupMessage,以不加密的方式继续。(也允许在收到 N 响应后发送 SSLRequest 消息,尝试使用 SSL 加密代替 GSSAPI。) - 前端也应准备处理服务器对 GSSENCRequest 返回的 ErrorMessage。前端不应将该错误直接展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 GSSAPI 加密的情况下继续。 + 前端也应准备处理服务器对 GSSENCRequest 返回的 ErrorMessage。前端不应将该错误展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 GSSAPI 加密的情况下继续。 - 当GSSAPI加密可用时,服务器预计只发送单个G字节,然后等待前端启动GSSAPI握手。此时如果还有其他可读字节,很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应编写代码,要么从套接字中恰好读取一个字节后再把套接字交给其 GSSAPI 库,要么在发现自己已经读到额外字节时将其视为协议违规。 + 当GSSAPI加密可用时,服务器应只发送单个G字节,然后等待前端启动GSSAPI握手。此时如果还有其他可读字节,很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应编写代码,要么从套接字中恰好读取一个字节后再把套接字交给其 GSSAPI 库,要么在发现自己已经读到额外字节时将其视为协议违规。 - 初始 GSSENCRequest 也可用于那些正在建立、目的是发送 CancelRequest 消息的连接。 - + 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 GSSENCRequest。 + 一旦成功建立GSSAPI加密连接,就应使用gss_wrap()加密通常的 StartupMessage 以及后续所有数据,并在实际加密负载前附上gss_wrap()结果长度,该长度以网络字节序的四字节整数表示。请注意,服务器只接受来自客户端、长度小于 16kB 的加密数据包。客户端应使用gss_wrap_size_limit()确定符合该限制的未加密消息大小,较大的消息则应拆分为多次gss_wrap()调用。典型分段是 8kB 的未加密数据,对应得到略大于 8kB 但明显小于 16kB 的加密数据包。通常可以认为,服务器不会向客户端发送大于 16kB 的加密数据包。 - 虽然协议本身并不为服务器提供强制启用GSSAPI加密的方法,但管理员可以把服务器配置为拒绝未加密会话,把它作为认证检查的一个副作用。 - + 虽然协议本身没有提供让服务器强制使用GSSAPI加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + @@ -1016,25 +996,22 @@ SELCT 1/0; - 客户端从列表中选择一个支持的机制,并向服务器发送一个SASLInitialResponse消息。 - 该消息包括所选机制的名称,以及如果所选机制使用的话,还包括一个可选的初始客户端响应。 - + 客户端从列表中选择一种受支持的机制,并向服务器发送 SASLInitialResponse 消息。消息包含所选机制的名称;如果该机制使用初始客户端响应,消息还可以包含这一可选响应。 + - 一个或多个服务器挑战和客户端响应消息将随后而来。每个服务器挑战都是在一个 - AuthenticationSASLContinue 消息中发送的,随后是客户端在一个 SASLResponse - 消息中的响应。这些消息的具体内容是特定于机制的。 - + 随后会进行一轮或多轮服务器挑战和客户端响应。每次服务器挑战都通过 AuthenticationSASLContinue 消息发送,随后客户端通过 SASLResponse 消息响应。消息的具体内容取决于所用机制。 + - 最后,当认证交换成功完成时,服务器会发送可选的 AuthenticationSASLFinal 消息,随后立即发送 AuthenticationOk。AuthenticationSASLFinal 包含机制特定的附加数据;若该机制不需要完成时附加数据,则不会发送 AuthenticationSASLFinal。 - + 最后,认证交换成功完成时,服务器会发送可选的 AuthenticationSASLFinal 消息,紧接着发送 AuthenticationOk 消息。AuthenticationSASLFinal 包含从服务器发给客户端的附加数据,其具体内容取决于所选认证机制。如果该认证机制不使用在完成时发送的附加数据,则不会发送 AuthenticationSASLFinal 消息。 + @@ -1060,31 +1037,22 @@ SELCT 1/0; - SCRAM规范规定密码也必须是UTF-8编码,并且使用SASLprep算法处理。 - 然而,PostgreSQL不要求密码必须使用UTF-8编码。 - 当用户设置密码时,无论实际使用的编码是什么,都会像使用UTF-8一样使用SASLprep进行处理。 - 但是,如果密码不是合法的UTF-8字节序列,或者包含SASLprep算法禁止的UTF-8字节序列, - 则会使用原始密码而不进行SASLprep处理,而不是抛出错误。这样可以在密码为UTF-8时对其进行规范化, - 但仍允许使用非UTF-8密码,并且不需要系统知道密码使用的编码方式。 - + SCRAM 规范规定密码也必须采用 UTF-8 编码,并通过SASLprep算法处理。不过,PostgreSQL并不要求密码使用 UTF-8。设置用户密码时,无论实际采用何种编码,都会将其视作 UTF-8 并用 SASLprep 处理。但是,如果密码不是合法的 UTF-8 字节序列,或者包含 SASLprep 算法禁止的 UTF-8 字节序列,就会直接使用未经 SASLprep 处理的原始密码,而不抛出错误。这样既能对 UTF-8 密码进行规范化,又允许使用非 UTF-8 密码,而且不要求系统知道密码采用何种编码。 + - Channel binding在支持SSL的PostgreSQL构建中受支持。带有通道绑定的SCRAM的SASL机制名称是 + 通道绑定在支持SSL的PostgreSQL构建中受支持。带有通道绑定的SCRAM的SASL机制名称是 SCRAM-SHA-256-PLUS。PostgreSQL使用的通道绑定类型是 tls-server-end-point - 在没有通道绑定的SCRAM中,服务器选择一个随机数, - 传输给客户端,与用户提供的密码在传输的密码哈希中混合。虽然这可以 - 防止密码哈希在后续会话中被成功重新传输,但无法阻止真实服务器和客 - 户端之间的虚假服务器通过服务器的随机值并成功进行认证。 - + 在不带通道绑定的SCRAM中,服务器会选择一个随机数并发送给客户端,将它与用户提供的密码混合,形成所传输的密码 hash。虽然这样可以防止在后续会话中成功重放该密码 hash,但无法阻止位于真实服务器与客户端之间的伪造服务器转发服务器的随机值并成功通过认证。 + - SCRAM与通道绑定一起防止这种中间人攻击,通过将服务器证书的签名混合到传输的密码哈希中。 - 虽然伪造服务器可以重新传输真实服务器的证书,但它无法访问与该证书匹配的私钥,因此无法证明自己是所有者,导致SSL连接失败。 - + 带通道绑定的SCRAM会将服务器证书的签名混入所传输的密码 hash,从而防止此类中间人攻击。虽然伪造服务器可以转发真实服务器的证书,但它无法取得与证书匹配的私钥,因此无法证明自己是证书所有者,最终导致 SSL 连接失败。 + @@ -1137,63 +1105,75 @@ SELCT 1/0; OAUTHBEARER 认证 - OAUTHBEARER 是一种基于令牌的联合认证机制,详见 - RFC 7628。 - + OAUTHBEARER 是一种基于令牌的联合认证机制。其详细说明见 RFC 7628。 + - 典型交互取决于客户端是否已经为当前用户缓存 bearer token。若没有,通常会经历两次连接:第一次“发现连接”用于从服务器获取 OAuth 元数据,第二次连接在客户端拿到 token 后再发送 token。(libpq 当前内置流程尚未实现缓存,因此使用两连接流程。) - + 典型交互取决于客户端是否已为当前用户缓存 Bearer 令牌。如果没有,交互将通过两次连接完成:第一次“发现”连接从服务器获取 OAuth 元数据,第二次连接在客户端取得令牌后发送该令牌。(libpq 的内置流程目前没有实现缓存方法,因此使用两次连接的交互方式。) + - 该机制与 SCRAM 一样由客户端发起。客户端初始响应由 SCRAM 使用的标准 GS2 头部加上一组 key=value 对组成。当前服务器仅支持 auth 键(即 bearer token)。OAUTHBEARER 还定义了三个可选组成(GS2 头部中的 authzid,以及 host/port),当前服务器会忽略它们。 - + 该机制与 SCRAM 一样由客户端发起。客户端初始响应由 SCRAM 使用的标准“GS2”头部以及随后的一组 key=value 对组成。服务器目前唯一支持的键是 auth,其中包含 Bearer 令牌。OAUTHBEARER 还规定了客户端初始响应的三个可选部分:GS2 头部的 authzid,以及 hostport 键;服务器目前会忽略它们。 + - OAUTHBEARER 不支持通道绑定,因此不存在 “OAUTHBEARER-PLUS”。该机制在成功认证时不使用额外服务器数据,所以不会使用 AuthenticationSASLFinal 消息。 - + OAUTHBEARER 不支持通道绑定,也不存在“OAUTHBEARER-PLUS”机制。该机制在成功认证期间不使用服务器数据,因此交互中不使用 AuthenticationSASLFinal 消息。 + 示例 - 第一次交互时,服务器发送 AuthenticationSASL,并在机制列表中声明 OAUTHBEARER。 - + 第一次交互期间,服务器发送 AuthenticationSASL 消息,并声明支持 OAUTHBEARER 机制。 + + - 客户端发送 SASLInitialResponse 并选择 OAUTHBEARER。若尚无可用 token,则 auth 为空,表示这是发现连接。 - + 客户端发送 SASLInitialResponse 消息作为响应,在其中指定 OAUTHBEARER 机制。假定客户端尚未持有当前用户的有效 Bearer 令牌,则 auth 字段为空,表示这是发现连接。 + + - 服务器发送 AuthenticationSASLContinue,包含错误 status、well-known URI 以及客户端应使用的 scopes。 - + 服务器发送 AuthenticationSASLContinue 消息,其中包含错误 status、well-known URI,以及客户端执行 OAuth 流程时应使用的授权范围。 + + - 客户端发送 SASLResponse,内容为空集合(单个 0x01 字节),结束发现阶段的客户端半程。 - + 客户端发送包含空集合(单个 0x01 字节)的 SASLResponse 消息,以结束发现交互中由客户端完成的部分。 + + - 服务器发送 ErrorMessage,使第一次交互失败。随后客户端按配置和服务器提供的元数据执行 OAuth 流程以获取 token。(具体获取方式由客户端实现决定,OAUTHBEARER 不强制规定。) - + 服务器发送 ErrorMessage,使第一次交互失败。 + + + 此时,客户端会执行多种可用 OAuth 流程中的一种,以获取 Bearer 令牌;所使用的元数据包括客户端已配置的元数据,以及服务器提供的元数据。(此处的描述有意保持宽泛;OAUTHBEARER 不指定也不强制要求采用任何特定的令牌获取方法。) + + + 取得令牌后,客户端会重新连接服务器,进行最后一次交互: + + - 客户端拿到 token 后重新连接;服务器再次发送 AuthenticationSASL,并声明 OAUTHBEARER。 - + 服务器再次发送 AuthenticationSASL 消息,并声明支持 OAUTHBEARER 机制。 + + - 客户端再次发送 SASLInitialResponse,这次在 auth 中携带 bearer token。 - + 客户端发送 SASLInitialResponse 消息作为响应,但这次消息中的 auth 字段包含客户端流程取得的 Bearer 令牌。 + + - 服务器按令牌提供方规则校验 token。若客户端被授权连接,服务器发送 AuthenticationOk,认证完成。 - + 服务器按照令牌提供者的说明验证令牌。如果客户端获准连接,服务器便发送 AuthenticationOk 消息,结束 SASL 交互。 + @@ -1220,16 +1200,15 @@ SELCT 1/0; - 为了测试复制命令,可以通过psql或任何其他使用连接字符串且包含replication选项的libpq工具建立复制连接, - 例如: + 为了测试复制命令,可以通过 psql 或其他使用 libpq 的工具建立复制连接,连接字符串中应包含 replication 选项,例如: psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 然而,更常用的是使用(用于物理复制)或(用于逻辑复制)。 - +不过,通常更有用的做法是使用 (用于物理复制)或 (用于逻辑复制)。 + - 复制命令在服务器日志中记录,当启用时。 + 启用 后,复制命令会记录到服务器日志中。 @@ -1239,7 +1218,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" IDENTIFY_SYSTEM - 识别系统 + IDENTIFY_SYSTEM @@ -1275,9 +1254,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" xlogpos (text) - - 当前 WAL 刷新位置。用于获得预写式日志中的一个已知位置,以便从该处开始流式传输。 - + 当前 WAL 刷盘位置。可用于获取预写式日志中一个已知的位置,以便从该处开始流式传输。 @@ -1329,10 +1306,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 请求服务器发送时间线历史文件以获取时间线tli。 - 服务器回复一行结果集,包含两个字段。虽然这些字段被标记为text, - 但它们实际上返回原始字节,没有编码转换: - + 请求服务器发送时间线 tli 的历史文件。服务器返回一个包含两个字段的单行结果集。虽然这些字段标记为 text,但实际返回的是原始字节,不进行编码转换: + @@ -1412,12 +1387,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果为 true,则该逻辑复制槽支持两阶段提交的解码。使用此选项后,与两阶段提交相关的命令,如 - PREPARE TRANSACTIONCOMMIT PREPARED - 和ROLLBACK PREPARED将被解码和传输。 - 事务将在PREPARE TRANSACTION时解码和传输。 - 默认值为false。 - + 如果为 true,则该逻辑复制槽支持对两阶段提交进行解码。使用此选项后,PREPARE TRANSACTIONCOMMIT PREPAREDROLLBACK PREPARED 等两阶段提交命令会被解码并传输。事务会在 PREPARE TRANSACTION 时解码并传输。默认值为 false。 + @@ -1426,10 +1397,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果为 true,则该物理复制槽会立即保留WAL。 - 否则,WAL仅在从流复制客户端连接时保留。 - 默认值为false。 - + 如果为 true,则该物理复制槽会立即保留 WAL。否则,只有在流复制客户端连接时才会保留 WAL。默认值为 false。 + @@ -1513,8 +1482,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 修改复制槽定义。参见 。当前仅支持逻辑复制槽。 - + 修改复制槽的定义。有关复制槽的更多信息,参见 。此命令目前仅支持逻辑复制槽。 + slot_name @@ -1531,8 +1500,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" TWO_PHASE [ boolean ] - 若为 true,则该逻辑复制槽支持两阶段提交解码。与两阶段提交相关的命令(如 PREPARE TRANSACTIONCOMMIT PREPAREDROLLBACK PREPARED)会被解码并发送;事务在 PREPARE TRANSACTION 时解码并发送。 - + 如果为 true,则该逻辑复制槽支持对两阶段提交进行解码。使用此选项后,PREPARE TRANSACTIONCOMMIT PREPAREDROLLBACK PREPARED 等两阶段提交命令会被解码并传输。事务会在 PREPARE TRANSACTION 时解码并传输。 + @@ -1541,8 +1510,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" FAILOVER [ boolean ] - 若为 true,则该复制槽会同步到备库,从而在故障切换后恢复逻辑复制。 - + 如果为 true,则允许该复制槽同步到备库,以便在故障切换后恢复逻辑复制。 + @@ -1553,14 +1522,13 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" READ_REPLICATION_SLOT slot_name - 读取复制槽 + READ_REPLICATION_SLOT - 读取与复制槽相关的一些信息。如果复制槽不存在,则返回一个包含NULL值的元组。 - 当前仅支持物理复制槽的此命令。 - + 读取与复制槽关联的一些信息。如果复制槽不存在,则返回包含 NULL 值的元组。此命令目前仅支持物理复制槽。 + 在响应此命令时,服务器将返回一个包含以下字段的单行结果集: @@ -1587,8 +1555,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" restart_tliint8 - 与restart_lsn相关联的时间线ID,遵循当前时间线历史。 - + 根据当前时间线的历史,与 restart_lsn 对应的时间线 ID。 + @@ -1600,35 +1568,29 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" START_REPLICATION [ SLOT slot_name ] [ PHYSICAL ] XXX/XXX [ TIMELINE tli ] - 开始复制 + START_REPLICATION - 指示服务器开始流式传输WAL,从WAL位置XXX/XXX开始。 - 如果指定了TIMELINE选项,则流式传输将从时间线tli开始; - 否则,将选择服务器当前的时间线。如果请求的WAL部分已经被回收,服务器可能会回复错误。 - 成功时,服务器将用CopyBothResponse消息回复,然后开始向前端流式传输WAL。 - + 指示服务器从 WAL 位置 XXX/XXX 开始流式传输 WAL。如果指定了 TIMELINE 选项,则从时间线 tli 开始传输;否则选择服务器当前的时间线。服务器可以返回错误,例如请求的 WAL 部分已被回收时。成功时,服务器返回 CopyBothResponse 消息,然后开始向前端流式传输 WAL。 + - 如果通过slot_name提供了复制槽名称, - 那么在复制进行期间会更新该复制槽,以便服务器知道哪些 WAL 段, - 以及在启用了 hot_standby_feedback 时,哪些事务 - 仍然被备库所需要。 - + 如果通过 slot_name 提供了复制槽名称,该复制槽会随着复制的进行而更新,使服务器知道备库仍需要哪些 WAL 段,以及在启用 hot_standby_feedback 时仍需要哪些事务。 + - 如果客户端请求的 timeline 不是最新的,但属于服务器历史的一部分,服务器会从请求的起点开始流式传输该 timeline 上的全部 WAL,直到服务器切换到另一个 timeline 的位置为止。如果客户端请求的位置正好是旧 timeline 的末尾,服务器将完全跳过 COPY 模式。 - + 如果客户端请求的时间线不是最新时间线,但属于服务器的历史,服务器会从请求的起点开始,流式传输该时间线上的所有 WAL,直到服务器切换到另一条时间线的位置。如果客户端请求的流式传输起点恰好位于旧时间线的末尾,服务器会完全跳过 COPY 模式。 + 在非最新时间线上流式传输完全部 WAL 后,服务器会通过退出 COPY 模式来结束流式传输。当客户端也通过退出 COPY 模式来确认时,服务器会发送一个包含一行两列的结果集,指示该服务器历史中的下一条时间线。第一列是下一条时间线的 ID(类型为 int8),第二列是发生切换的 WAL 位置(类型为 text)。通常,切换位置就是所流式传输 WAL 的末尾,但也存在一些边界情况,服务器可能会先发送一些自己在提升前尚未重放的旧时间线 WAL。最后,服务器会发送两个 CommandComplete 消息(一个结束 CopyData,另一个结束 START_REPLICATION 本身),然后准备接受新的命令。 - WAL 数据会作为一系列 CopyData 消息发送;详见 。(这使其他信息可与之交错发送;特别是服务器在开始流式传输后若遇到失败,仍可发送 ErrorResponse。)从服务器到客户端的每个 CopyData 消息负载都属于以下格式之一: - + WAL 数据通过一系列 CopyData 消息发送,详见 。(这样可以混合发送其他信息;尤其是服务器在开始流式传输后遇到故障时,可以发送 ErrorResponse 消息。)服务器发给客户端的每条 CopyData 消息,其有效载荷都包含一条具有下列格式之一的消息: + @@ -1641,9 +1603,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('w') - - 将消息标识为WAL数据。 - + 将该消息标识为 WAL 数据。 @@ -1652,9 +1612,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 该消息中 WAL 数据的起始点。 - + 本消息中 WAL 数据的起始位置。 @@ -1663,9 +1621,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 服务器上当前的WAL结束位置。 - + 服务器上当前的 WAL 末尾位置。 @@ -1674,9 +1630,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 传输时服务器的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时服务器的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1685,15 +1639,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byten - - WAL数据流的一个部分。 - + WAL 数据流的一个片段。 - - 单个 WAL 记录绝不会拆分为两个 XLogData 消息。 - 当 WAL 记录跨越 WAL 页面边界,并因此已使用连续记录进行拆分时,它可以在页面边界处进行拆分。 - 换句话说,第一个主 WAL 记录及其连续记录可以在不同的 XLogData 消息中发送。 - + 单条 WAL 记录绝不会被拆分到两条 XLogData 消息中。当 WAL 记录跨越 WAL 页边界,因而已经通过续接记录拆分时,可以在页边界处分开发送。换句话说,最初的主 WAL 记录及其续接记录可以在不同的 XLogData 消息中发送。 @@ -1702,7 +1650,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 主库 keepalive 消息 (B) + 主库保活消息 (B) @@ -1710,9 +1658,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('k') - - 将该消息标识为发送方 keepalive。 - + 将该消息标识为发送端保活消息。 @@ -1721,9 +1667,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 服务器上当前的WAL结束位置。 - + 服务器上当前的 WAL 末尾位置。 @@ -1732,9 +1676,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 传输时服务器的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时服务器的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1743,9 +1685,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1 - - 1 表示客户端应尽快回复此消息,以避免超时断开连接。否则为0。 - + 1 表示客户端应尽快回复此消息,以避免超时断开连接;否则为 0。 @@ -1753,9 +1693,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - - 接收进程可以随时使用以下某种消息格式向发送方回传响应(同样放在 CopyData 消息的负载中): - + 接收进程可以随时使用以下消息格式之一回复发送端(同样放在 CopyData 消息的有效载荷中): @@ -1768,9 +1706,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('r') - - 将该消息标识为接收方状态更新。 - + 将该消息标识为接收端状态更新。 @@ -1779,9 +1715,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已接收并写入磁盘的 WAL 字节位置 + 1。 - + 备库已接收并写入磁盘的最后一个 WAL 字节的位置加 1。 @@ -1790,9 +1724,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已刷写到磁盘的 WAL 字节位置 + 1。 - + 备库已刷盘的最后一个 WAL 字节的位置加 1。 @@ -1801,9 +1733,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已应用的 WAL 字节位置 + 1。 - + 备库已应用的最后一个 WAL 字节的位置加 1。 @@ -1812,9 +1742,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 客户端在传输时的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时客户端的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1823,9 +1751,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1 - - 如果为 1,则客户端请求服务器立即回复此消息。这可用于 ping 服务器,以测试连接是否仍然健康。 - + 如果为 1,表示客户端请求服务器立即回复此消息。可用它向服务器发送探测请求,以测试连接是否仍然正常。 @@ -1853,9 +1779,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 客户端在传输时的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时客户端的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1876,8 +1800,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 备库上全局 xmin xid 的纪元。 - + 备库全局 xmin 事务 ID 的纪元。 + @@ -1887,8 +1811,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 备库上任何复制槽中的最低 catalog_xmin。如果备库上不存在 catalog_xmin,或已禁用热备反馈,则设为 0。 - + 备库上所有复制槽中最小的 catalog_xmin。如果备库上不存在 catalog_xmin,或者正在禁用热备反馈,则设为 0。 + @@ -1898,8 +1822,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 备库上 catalog_xmin xid 的纪元。 - + 备库 catalog_xmin 事务 ID 的纪元。 + @@ -1985,7 +1909,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" DROP_REPLICATION_SLOT slot_name WAIT - 删除复制槽 + DROP_REPLICATION_SLOT @@ -2048,9 +1972,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 设置备份的标签。如果未指定,则将使用base backup作为备份标签。 - 标签的引号使用规则与打开的标准SQL字符串相同。 - + 设置备份标签。如果未指定,则使用 base backup 作为备份标签。标签的引号规则与启用 时的标准 SQL 字符串相同。 + @@ -2151,16 +2074,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - level关键字设置压缩级别。 - 对于gzip,压缩级别应该是一个介于19之间的整数 - (默认为Z_DEFAULT_COMPRESSION-1), - 对于lz4,压缩级别应该是介于1和12之间的整数 - (默认为0用于快速压缩模式), - 对于zstd,压缩级别应该是介于ZSTD_minCLevel() - (通常为-131072)和ZSTD_maxCLevel() - (通常为22)之间, - (默认为ZSTD_CLEVEL_DEFAULT3)。 - + level 关键字设置压缩级别。对于 gzip,压缩级别应为 19 之间的整数(默认为 Z_DEFAULT_COMPRESSION,即 -1);对于 lz4,应为 1 到 12 之间的整数(默认为 0,表示快速压缩模式);对于 zstd,应为 ZSTD_minCLevel()(通常为 -131072)到 ZSTD_maxCLevel()(通常为 22)之间的整数(默认为 ZSTD_CLEVEL_DEFAULT,即 3)。 + long 关键字用于启用长距离匹配模式,可提高压缩比,但会增加内存使用。长距离模式仅支持 zstd。 @@ -2282,17 +2197,16 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" size (int8) - 表空间的大致大小,以千字节(1024字节)为单位,如果已请求进度报告;否则为null。 - + 如果请求了进度报告,则为表空间的大致大小,以千字节(1024 字节)为单位;否则为 null。 + - 在第二个常规结果集之后,将发送一个CopyOutResponse。 - 每个CopyData消息的有效负载将包含以下格式之一的消息: - + 第二个普通结果集之后,会发送一条 CopyOutResponse。每条 CopyData 消息的有效载荷都包含一条具有下列格式之一的消息: + @@ -2473,11 +2387,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" + + 在上述所有命令中,指定 boolean 类型的参数时,可以省略 value 部分,这等同于指定 TRUE。 + - 逻辑复制协议 + 逻辑流复制协议 本节介绍逻辑复制协议,它是一种以复制命令START_REPLICATION @@ -2486,7 +2403,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 逻辑复制协议构建在物理流复制协议的底层机制之上。 + 逻辑流复制协议构建在物理流复制协议的基本机制之上。 @@ -2499,7 +2416,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 逻辑流复制参数 - 使用 START_REPLICATION 命令时,pgoutput 接受以下选项: + 使用START_REPLICATION命令,pgoutput接受以下选项: @@ -2517,7 +2434,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" 版本 3 仅在服务器版本 15 及以上受支持,允许流式传输两阶段提交。 - 版本 4 仅在服务器版本 16 及以上受支持,允许并行应用正在进行的大型事务的流。 + 版本 4 仅在服务器版本 16 及以上受支持,允许并行应用进行中的大型事务流。 @@ -2627,7 +2544,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每个被发送的事务都包含零条或多条 DML 消息(插入、更新、删除)。在级联场景下,它还会包含 Origin 消息。Origin 消息表示该事务产生于另一个复制节点。由于逻辑复制协议中的复制节点可以是任意实现,因此唯一标识符就是该源头的名称。下游是否以及如何处理这一信息,由其自行决定。Origin 消息总是在事务中的任何 DML 消息之前发送。 + 每个发送的事务都包含零条或多条 DML 消息(Insert、Update、Delete)。在级联配置中,还可能包含 Origin 消息。Origin 消息表示该事务源自另一个复制节点。由于逻辑复制协议中的复制节点几乎可以是任何实现,因此唯一的标识符就是复制源的名称。下游负责按需处理这一信息(如果需要处理)。Origin 消息总是在事务中的任何 DML 消息之前发送。 @@ -2692,9 +2609,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 对后端返回的字符串长度,没有预定义的限制。 - 前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。 - 如果做不到这一点,就应读取完整字符串,并丢弃不适合固定大小缓冲区的尾随字符。 + 后端返回的字符串长度没有预定义的限制。前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。如果做不到这一点,就应读取完整字符串,并丢弃固定大小的缓冲区容纳不下的尾随字符。 @@ -2736,7 +2651,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2758,7 +2673,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定认证成功。 + 表示认证成功。 @@ -2778,7 +2693,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2800,7 +2715,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 Kerberos V5 认证。 + 表示需要 Kerberos V5 认证。 @@ -2820,7 +2735,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2842,7 +2757,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要明文密码。 + 表示需要明文密码。 @@ -2861,7 +2776,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2883,7 +2798,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要MD5加密的密码。 + 表示需要经过 MD5 加密的密码。 @@ -2894,7 +2809,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 用于加密密码时使用的盐。 + 加密密码时使用的盐。 @@ -2913,7 +2828,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2934,7 +2849,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 GSSAPI 认证。 + 表示需要 GSSAPI 认证。 @@ -2953,7 +2868,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2975,7 +2890,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定此消息包含GSSAPI或SSPI数据。 + 表示此消息包含 GSSAPI 或 SSPI 数据。 @@ -3005,7 +2920,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -3027,7 +2942,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 SSPI 认证。 + 表示需要 SSPI 认证。 @@ -3046,7 +2961,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -3068,14 +2983,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 SASL 认证。 + 表示需要 SASL 认证。 - 消息正文是服务器首选的 SASL 认证机制列表。在最后一个认证机制名称后需要一个零字节作为终止符。对于每个机制,有以下内容: + 消息体是按服务器偏好顺序排列的 SASL 认证机制列表。在最后一个认证机制名称之后,必须有一个零字节作为终止符。每个机制包含以下内容: @@ -3102,7 +3017,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -3124,7 +3039,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定此消息包含一个SASL挑战。 + 表示此消息包含 SASL 挑战。 @@ -3135,7 +3050,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - SASL数据,特定于正在使用的SASL机制。 + SASL 数据,具体内容取决于所使用的 SASL 机制。 @@ -3154,7 +3069,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -3176,7 +3091,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定SASL认证已完成。 + 表示 SASL 认证已完成。 @@ -3187,7 +3102,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - SASL结果"附加数据",特定于正在使用的SASL机制。 + SASL 结果的“附加数据”,具体内容取决于所使用的 SASL 机制。 @@ -3206,15 +3121,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为取消键数据。 - 如果前端希望能够稍后发出CancelRequest消息,必须保存这些值。 + 将此消息标识为取消请求密钥数据。如果前端希望以后能够发送 CancelRequest 消息,就必须保存这些值。 - Int32(12) + Int32 @@ -3229,27 +3143,27 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 这个后端的进程ID。 + 此后端的进程 ID。 - Int32 + Byten - 该后端的 secret key。该字段长度由消息总长度决定,并一直延伸到消息末尾。 + 此后端的密钥。此字段延伸至消息末尾,其范围由长度字段确定。 - key 的最小与最大长度分别为 4 和 256 字节。PostgreSQL 服务器当前发送不超过 32 字节的 key;更大的上限用于兼容未来版本及连接池/中间件使用更长 key 的需求。中间件也不宜用满全部字节,以便多层中间件叠加时仍可附加自身数据。 + 密钥长度最小为 4 字节,最大为 256 字节。PostgreSQL 服务器只发送最长 32 字节的密钥,但更大的长度上限允许未来的服务器版本、连接池和其他中间件使用更长的密钥。一种可能的用途是在服务器密钥中附加额外信息。因此,也建议中间件不要用尽所有字节,以便多层中间件叠加时,每一层都可以在密钥外再附加数据。 - 在协议 3.2 之前,secret key 固定为 4 字节。 + 在协议版本 3.2 之前,密钥始终为 4 字节长。 @@ -3265,7 +3179,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为绑定命令。 + 将该消息标识为 Bind 命令。 @@ -3309,10 +3223,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后面跟着的参数格式代码的数量(以下标记为C)。 - 这可以是零,表示没有参数或者所有参数都使用默认格式(文本); - 或者是一个,这种情况下指定的格式代码应用于所有参数; - 或者等于实际参数的数量。 + 后续参数格式代码的数量(下文以 C 表示)。可以为零,表示没有参数,或者所有参数都使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有参数;还可以等于实际参数数量。 @@ -3323,7 +3234,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数格式代码。每个目前必须是零(文本)或一(二进制)。 + 参数格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -3334,15 +3245,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后面跟着的参数值的数量(可能为零)。 - 这个数量必须与查询所需的参数数量匹配。 + 后续参数值的数量(可以为零)。必须与查询所需的参数数量一致。 - 接下来,对于每个参数,都会出现以下一对字段: + 接下来,每个参数都有以下一对字段: @@ -3352,9 +3262,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数值的长度,以字节为单位(此计数不包括自身)。可以为零。 - 作为特殊情况,-1表示空参数值。 - 在空参数值的情况下,不会跟随任何值字节。 + 参数值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 参数值。为 NULL 时,后面不再有值的字节。 @@ -3365,15 +3273,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数的值,以相关格式代码指示的格式表示。 - n是上述长度。 + 参数值,格式由对应的格式代码指明。n 为上述长度。 - 在最后一个参数之后,出现以下字段: + 最后一个参数之后是以下字段: @@ -3383,10 +3290,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后跟的结果列格式代码数量(以下标记为R)。 - 这可以是零,表示没有结果列,或者所有结果列应该使用默认格式(文本); - 或者是一个,此时指定的格式代码将应用于所有结果列(如果有); - 或者等于查询的实际结果列数。 + 后续结果列格式代码的数量(下文以 R 表示)。可以为零,表示没有结果列,或者所有结果列都应使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有结果列(如果有);还可以等于查询实际的结果列数量。 @@ -3397,7 +3301,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 结果列格式代码。每个目前必须是零(文本)或一(二进制)。 + 结果列格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -3416,7 +3320,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为绑定完成指示器。 + 将该消息标识为 Bind 完成指示。 @@ -3444,7 +3348,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 - 消息内容的长度,以字节为单位,包括此长度字段本身。 + 消息内容的长度(以字节为单位),包括其自身。 @@ -3493,7 +3397,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为关闭命令。 + 将该消息标识为 Close 命令。 @@ -3515,8 +3419,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 'S' 表示关闭一个预备语句;或者 - 'P' 表示关闭一个 portal。 + “S”表示关闭预备语句;“P”表示关闭 portal。 @@ -3546,7 +3449,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为关闭完成指示符。 + 将该消息标识为 Close 完成指示。 @@ -3576,7 +3479,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为命令完成响应。 + 将该消息标识为命令完成响应。 @@ -3598,7 +3501,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 命令标签。这通常是一个单词,用于标识已完成的SQL命令。 + 命令标签。通常是一个单词,用来标识已完成的 SQL 命令。 @@ -3643,10 +3546,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 对于COPY命令,标签是 - COPY rows,其中 - rows是复制的行数。 - (注意:行数仅出现在PostgreSQL 8.2及更高版本中。) + 对于 COPY 命令,标签为 COPY rows,其中 rows 是复制的行数。(注意:行数仅出现在 PostgreSQL 8.2 及更高版本中。) @@ -3777,8 +3677,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为开始复制响应。 - 前端现在必须发送复制数据(如果没有准备好,发送CopyFail消息)。 + 将该消息标识为开始 COPY 输入的响应。前端此时必须发送 COPY 输入数据(如果尚未准备好,应发送 CopyFail 消息)。 @@ -3824,9 +3723,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -3845,8 +3742,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为开始复制输出响应。 - 该消息将被复制输出数据跟随。 + 将该消息标识为开始 COPY 输出的响应。此消息之后会发送 COPY 输出数据。 @@ -3868,8 +3764,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 0表示整体COPY格式为文本格式(行由换行符分隔,列由分隔符字符分隔等)。 - 1表示整体复制格式为二进制格式(类似于DataRow格式)。更多信息请参见。 + 0表示整体COPY格式是文本的(行由换行符分隔,列由分隔符分隔等)。 + 1表示整体复制格式是二进制的(类似于DataRow格式)。 + 更多信息请参见 @@ -3891,9 +3788,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -3912,7 +3807,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为开始复制双响应。此消息仅用于流复制。 + 将该消息标识为开始双向 COPY 的响应。此消息仅用于流复制。 @@ -3934,8 +3829,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 0表示整体COPY格式为文本格式(行由换行符分隔,列由分隔符字符分隔等)。 - 1表示整体复制格式为二进制格式(类似于DataRow格式)。更多信息请参见。 + 0表示整体COPY格式是文本的(行由换行符分隔,列由分隔符分隔等)。 + 1表示整体复制格式是二进制的(类似于DataRow格式)。 + 更多信息请参见 @@ -3957,9 +3853,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -4007,7 +3901,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于每一列,都会出现以下一对字段: + 接下来,每列都有以下两个字段: @@ -4017,8 +3911,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列值的长度,以字节为单位(此计数不包括其本身)。可以为零。 - 作为特殊情况,-1表示空列值。在空值情况下,不跟随任何值字节。 + 列值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 列值。为 NULL 时,后面不再有值的字节。 @@ -4049,7 +3942,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为描述命令。 + 将该消息标识为 Describe 命令。 @@ -4102,7 +3995,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为对空查询字符串的响应。(这相当于CommandComplete。) + 标识消息为对空查询字符串的响应。(此消息替代 CommandComplete。) @@ -4150,7 +4043,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 消息正文由一个或多个已识别的字段组成,后跟一个零字节作为终止符。字段可以以任何顺序出现。对于每个字段,都有以下内容: + 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -4173,7 +4066,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 字段数值。 + 字段值。 @@ -4192,7 +4085,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为一个执行命令。 + 将该消息标识为 Execute 命令。 @@ -4225,7 +4118,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果 portal 包含返回行的查询,则为要返回的最大行数(否则忽略)。零表示没有限制。 + 如果 portal 包含返回行的查询,则这是最多返回的行数(否则忽略此值)。零表示无限制 @@ -4244,7 +4137,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为Flush命令。 + 将该消息标识为 Flush 命令。 @@ -4296,7 +4189,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定要调用的函数的对象ID。 + 指定要调用的函数的对象 ID。 @@ -4307,10 +4200,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后面跟着的参数格式代码的数量(以下标记为C)。 - 这可以是零,表示没有参数或所有参数都使用默认格式(文本); - 或者是一个,这种情况下指定的格式代码应用于所有参数; - 或者等于实际参数的数量。 + 后续参数格式代码的数量(以下用 C 表示)。可以为零,表示没有参数,或所有参数都采用默认格式(文本);也可以为一,表示将指定的格式代码用于所有参数;还可以等于实际参数数量。 @@ -4339,7 +4229,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于每个参数,都会出现以下一对字段: + 接下来,每个参数都有以下两个字段: @@ -4349,9 +4239,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数值的长度,以字节为单位(此计数不包括自身)。可以为零。 - 作为特殊情况,-1表示空参数值。 - 在空参数值的情况下,不会跟随任何值字节。 + 参数值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 参数值。为 NULL 时,后面不再有值的字节。 @@ -4370,7 +4258,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 在最后一个参数之后,出现以下字段: + 最后一个参数之后还有以下字段: @@ -4380,7 +4268,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 函数结果的格式代码。目前必须是零(文本)或一(二进制)。 + 函数结果的格式代码。目前必须为零(文本)或一(二进制)。 @@ -4421,9 +4309,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 函数结果值的长度,以字节为单位(此计数不包括本身)。可以为零。 - 作为特殊情况,-1表示NULL函数结果。 - 在NULL情况下,不会跟随任何值字节。 + 函数结果值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 函数结果。为 NULL 时,后面不再有值的字节。 @@ -4549,7 +4435,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 服务器支持的最新次要协议版本,用于客户端请求的主要协议版本。 + 对于客户端请求的协议主版本,服务器所支持的最新协议次版本。 @@ -4560,14 +4446,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 服务器未识别的协议选项数量。 + 服务器无法识别的协议选项数量。 - 然后,对于服务器未识别的协议选项,有以下内容: + 接下来,对于服务器无法识别的每个协议选项,都有以下内容: @@ -4644,7 +4530,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 消息正文由一个或多个已识别的字段组成,后跟一个零字节作为终止符。字段可以以任何顺序出现。对于每个字段,都有以下内容: + 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -4667,7 +4553,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 字段数值。 + 字段值。 @@ -4708,7 +4594,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 通知后端进程的进程ID。 + 发出通知的后端进程的进程 ID。 @@ -4719,7 +4605,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 通知被触发的频道名称。 + 发出该通知的通道名称。 @@ -4730,7 +4616,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 从通知进程传递的有效负载字符串。 + 通知进程传来的有效载荷字符串。 @@ -4778,7 +4664,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 然后,对于每个参数,都有以下内容: + 接下来,每个参数都有以下内容: @@ -4788,7 +4674,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定参数数据类型的对象ID。 + 指定参数数据类型的对象 ID。 @@ -4829,7 +4715,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 正在报告的运行时参数的名称。 + 所报告的运行时参数的名称。 @@ -4859,7 +4745,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为解析命令。 + 将该消息标识为 Parse 命令。 @@ -4911,7 +4797,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 然后,对于每个参数,都有以下内容: + 接下来,每个参数都有以下内容: @@ -4921,7 +4807,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定参数数据类型的对象ID。在这里放置零相当于未指定类型。 + 指定参数数据类型的对象 ID。此处填零等同于不指定类型。 @@ -4940,7 +4826,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为解析完成指示器。 + 将该消息标识为 Parse 完成指示。 @@ -5012,8 +4898,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为 portal 挂起指示器。 - 请注意,仅当执行消息的行数限制达到时才会出现此消息。 + 将该消息标识为 portal 挂起指示。注意,仅当达到 Execute 消息指定的行数限制时,才会出现此消息。 @@ -5149,14 +5034,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定一行中的字段数(可以为零)。 + 指定一行中的字段数量(可以为零)。 - 然后,对于每个字段,都有以下内容: + 接下来,每个字段都有以下内容: @@ -5177,7 +5062,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果该字段可以被识别为特定表的列,则为该表的对象ID;否则为零。 + 如果能够确定该字段是某个特定表的列,则为该表的对象 ID;否则为零。 @@ -5188,7 +5073,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果该字段可以被识别为特定表的列,则为该列的属性编号;否则为零。 + 如果能够确定该字段是某个特定表的列,则为该列的属性编号;否则为零。 @@ -5199,7 +5084,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 字段数据类型的对象ID。 + 字段数据类型的对象 ID。 @@ -5234,7 +5119,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 正在使用的字段格式代码。目前将为零(文本)或一(二进制)。在从描述语句变体返回的RowDescription中,格式代码尚未知晓,将始终为零。 + 字段所使用的格式代码。目前为零(文本)或一(二进制)。对于 Describe 针对预备语句的变体所返回的 RowDescription,格式代码尚未确定,始终为零。 @@ -5287,7 +5172,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 长度为SASL机制特定的“初始客户端响应”,如果没有初始响应,则为-1。 + 后续 SASL 机制特有的“客户端初始响应”的长度;如果没有初始响应,则为 -1。 @@ -5398,21 +5283,18 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int32(196608) + Int32(196610) - 协议版本号。最重要的16位是主版本号(此处描述的协议为3)。 - 最不重要的16位是次版本号(此处描述的协议为2)。 + 协议版本号。高 16 位为主版本号(此处描述的协议为 3);低 16 位为次版本号(此处描述的协议为 2)。 - 协议版本号后面跟着一个或多个参数名和值字符串对。在最后一个名/值对之后需要一个零字节作为终止符。 - 参数可以以任何顺序出现。user是必需的,其他是可选的。 - 每个参数的指定方式为: + 协议版本号之后是一个或多个参数名与参数值字符串对。最后一个名称/值对之后必须有一个零字节作为终止符。参数可以按任意顺序出现。其中,user是必需的,其余均为可选。每个参数按以下方式指定: @@ -5422,7 +5304,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数名称。当前识别的名称包括: + 参数名称。目前能够识别的名称如下: @@ -5462,7 +5344,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 除上述之外,还可以列出其他参数。以_pq_.开头的参数名称保留用于协议扩展,而其他参数被视为后端启动时设置的运行时参数。这些设置将在后端启动时应用(在解析命令行参数后,如果有的话),并将作为会话默认值。 + 除上述参数外,还可以列出其他参数。以_pq_.开头的参数名称保留用于协议扩展,其余参数则作为运行时参数,在后端启动时设置。这些设置会在后端启动期间应用(在解析命令行参数之后,如果有的话),并作为会话默认值。 @@ -5473,7 +5355,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数数值。 + 参数值。 @@ -5492,7 +5374,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为同步命令。 + 将该消息标识为 Sync 命令。 @@ -5545,7 +5427,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 错误和通知消息域 + 错误和通知消息字段 本节描述了ErrorResponse和NoticeResponse消息中可能出现的字段。每个字段类型都有一个单字节的标识符。 @@ -5558,11 +5440,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 严重性: 字段内容为ERROR, FATAL, 或 - PANIC (在错误消息中), 或 - WARNING, NOTICE, DEBUG, - INFO, 或 LOG (在通知消息中), - 或者这些内容的本地化翻译。始终存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中),或这些内容的本地化翻译。始终存在。 @@ -5572,11 +5450,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 严重性:字段内容为ERRORFATAL或 - PANIC(在错误消息中),或WARNINGNOTICEDEBUG、 - INFOLOG(在通知消息中)。 - 这与S字段相同,只是内容不会被本地化。仅在由PostgreSQL版本9.6 - 及更高版本生成的消息中存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中)。它与 S 字段相同,只是内容从不本地化。仅在 PostgreSQL 9.6 及更高版本生成的消息中存在。 @@ -5586,7 +5460,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Code: 错误的SQLSTATE代码(参见)。不可本地化。始终存在。 + 代码:错误的 SQLSTATE 代码(见 )。不可本地化。始终存在。 @@ -5596,9 +5470,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 消息: 主要的人类可读错误消息。 - 这应该准确但简洁(通常一行)。 - 总是存在。 + 消息:主要的可读错误消息。应准确而简洁(通常为一行)。始终存在。 @@ -5608,7 +5480,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 详细信息:一个可选的次要错误消息,提供有关问题的更多详细信息。可能会跨多行。 + 详细信息:可选的次要错误消息,提供有关该问题的更多细节。可能占多行。 @@ -5618,9 +5490,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 提示: 关于问题应该怎么做的一个可选建议。 - 这意在与细节不同,它提供建议(可能不合适)而不是硬性事实。 - 可能会跨越多行。 + 提示:可选的建议,说明如何处理该问题。它与详细信息的区别在于,它提供建议(可能并不合适),而非确凿事实。可能占多行。 @@ -5663,9 +5533,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Where: 错误发生的上下文指示。 - 目前包括活动的过程语言函数和内部生成查询的调用堆栈回溯。 - 跟踪每行一个条目,最近的在前。 + 上下文:说明错误发生时的上下文。目前包括活跃的过程语言函数和内部生成的查询的调用栈回溯。回溯每行一个条目,最近的调用在前。 @@ -5675,7 +5543,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Schema name: 如果错误与特定数据库对象相关联,则为包含该对象的模式的名称(如果有)。 + 模式名:如果错误与某个特定数据库对象有关,则为包含该对象的模式名称(如果有)。 @@ -5685,7 +5553,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 表名: 如果错误与特定表相关联,则为表的名称。(有关表模式名称的名称,请参考模式名称字段。) + 表名:如果错误与某个特定表有关,则为该表的名称。(表所在模式的名称见模式名字段。) @@ -5695,7 +5563,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列名: 如果错误与特定表列相关联,则为列的名称。(请参考模式和表名字段以识别表。) + 列名:如果错误与某个特定表列有关,则为该列的名称。(通过模式名和表名字段确定该表。) @@ -5705,8 +5573,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 数据类型名称: 如果错误与特定数据类型相关联,则为数据类型的名称。 - (有关数据类型模式的名称,请参阅模式名称字段。) + 数据类型名:如果错误与某个特定数据类型有关,则为该数据类型的名称。(数据类型所在模式的名称见模式名字段。) @@ -5716,8 +5583,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 约束名称: 如果错误与特定约束相关联,则为约束的名称。请参考上面列出的字段,了解相关表或域。 - (为此,即使索引不是使用约束语法创建的,也将其视为约束。) + 约束名:如果错误与某个特定约束有关,则为该约束的名称。相关的表或域见上述字段。(这里将索引也视为约束,即使它不是用约束语法创建的。) @@ -5727,7 +5593,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 文件: 报告错误的源代码位置的文件名。 + 文件:报告错误的源代码位置所在的文件名。 @@ -5737,7 +5603,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Line: 源代码位置的行号,报告错误的位置。 + 行号:报告错误的源代码位置所在的行号。 @@ -5747,7 +5613,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Routine: 报告错误的源代码例程的名称。 + 例程:报告错误的源代码例程的名称。 @@ -5756,15 +5622,12 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 模式名称、表名称、列名称、数据类型名称和约束名称的字段仅针对有限数量的错误类型提供; - 请参阅。前端不应假设任何这些字段的存在就保证了另一个字段的存在。 - 核心错误源观察到上述相互关系,但用户定义的函数可能以其他方式使用这些字段。 - 同样地,客户端不应假设这些字段表示当前数据库中的当代对象。 + 模式名、表名、列名、数据类型名和约束名字段仅针对有限的几类错误提供,见 。前端不应假设其中任何字段的存在就保证了另一个字段的存在。核心错误源遵循上述相互关系,但用户定义的函数可能以其他方式使用这些字段。同样,客户端不应假设这些字段表示当前数据库中现存的对象。 - 客户端负责格式化显示的信息以满足其需求;特别是应根据需要换行。错误消息字段中出现的换行符应被视为段落分隔符,而不是换行符。 + 客户端负责按自身需要格式化显示的信息;尤其应根据需要将长行断开。错误消息字段中的换行符应视为段落分隔符,而非行分隔符。 @@ -5790,18 +5653,18 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为开始消息。 + 将该消息标识为 Begin 消息。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 事务的最终LSN。 + 事务的最终 LSN。 @@ -5812,7 +5675,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -5823,7 +5686,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -5853,8 +5716,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -5865,14 +5727,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标志; 逻辑解码消息是非事务性的时为0,是事务性的时为1。 + 标志:0 表示没有标志;1 表示该逻辑解码消息是事务性的。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -5928,7 +5790,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为提交消息。 + 将该消息标识为 Commit 消息。 @@ -5946,22 +5808,22 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 提交的LSN。 + 提交的 LSN。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 事务的结束LSN。 + 事务的结束 LSN。 @@ -5972,7 +5834,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -5991,18 +5853,18 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为原始消息。 + 将该消息标识为 Origin 消息。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 原始服务器上提交的LSN。 + 源服务器上提交的 LSN。 @@ -6013,14 +5875,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 原点的名称。 + 复制源的名称。 - 请注意,在单个事务中可能存在多个Origin消息。 + 注意,单个事务中可能有多条 Origin 消息。 @@ -6036,7 +5898,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为关系消息。 + 将该消息标识为 Relation 消息。 @@ -6047,8 +5909,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6070,7 +5931,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 命名空间(pg_catalog为空字符串)。 + 命名空间(对于 pg_catalog 为空字符串)。 @@ -6092,7 +5953,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 关系的复制标识设置(与relreplidentpg_class中相同)。 + 关系的复制标识设置(与 pg_class 中的 relreplident 相同)。 @@ -6110,7 +5971,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于出版物中包含的每一列(除了生成的列),会出现以下消息部分: + 接下来,发布中包含的每一列都会出现以下消息部分: @@ -6120,7 +5981,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列的标志。目前可以是0表示没有标志,或者是1表示将该列标记为键的一部分。 + 列的标志。目前可以为 0,表示没有标志;或为 1,标记该列是键的一部分。 @@ -6153,7 +6014,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列的类型修饰符 (atttypmod)。 + 列的类型修饰符(atttypmod)。 @@ -6172,7 +6033,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为类型消息。 + 将该消息标识为 Type 消息。 @@ -6183,8 +6044,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6206,7 +6066,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 命名空间(pg_catalog为空字符串)。 + 命名空间(对于 pg_catalog 为空字符串)。 @@ -6236,7 +6096,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为插入消息。 + 将该消息标识为 Insert 消息。 @@ -6247,8 +6107,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6259,7 +6118,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。 + 关系的 OID,与 Relation 消息中的 ID 对应。 @@ -6270,7 +6129,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData消息为新元组。 + 将后续 TupleData 消息标识为新元组。 @@ -6281,7 +6140,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分,表示新元组的内容。 + 表示新元组内容的 TupleData 消息部分。 @@ -6300,7 +6159,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为更新消息。 + 将该消息标识为 Update 消息。 @@ -6311,8 +6170,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6323,7 +6181,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。 + 关系的 OID,与 Relation 消息中的 ID 对应。 @@ -6334,8 +6192,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData子消息为键。 - 此字段是可选的,仅在更新更改了属于REPLICA IDENTITY索引的任何列的数据时才存在。 + 将后续 TupleData 子消息标识为键。此字段可选,仅在更新更改了属于 REPLICA IDENTITY 索引的某一列或多列的数据时出现。 @@ -6346,8 +6203,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData子消息为旧元组。 - 此字段是可选的,仅在发生更新的表中REPLICA IDENTITY设置为FULL时才存在。 + 将后续 TupleData 子消息标识为旧元组。此字段可选,仅在发生更新的表将 REPLICA IDENTITY 设为 FULL 时出现。 @@ -6358,7 +6214,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分表示旧元组或主键的内容。仅在先前的'O'或'K'部分存在时才存在。 + 表示旧元组或主键内容的 TupleData 消息部分。仅在前面的'O'或'K'部分存在时出现。 @@ -6369,7 +6225,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData消息为新元组。 + 将后续 TupleData 消息标识为新元组。 @@ -6380,14 +6236,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分表示新元组的内容。 + 表示新元组内容的 TupleData 消息部分。 - 更新消息可能包含一个'K'消息部分,也可能包含一个'O'消息部分,或者两者都不包含,但绝不会同时包含两者。 + Update 消息可以包含 'K' 消息部分或 'O' 消息部分,也可以两者都不包含,但绝不会同时包含两者。 @@ -6403,7 +6259,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为删除消息。 + 将该消息标识为 Delete 消息。 @@ -6414,8 +6270,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6426,7 +6281,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。 + 关系的 OID,与 Relation 消息中的 ID 对应。 @@ -6437,8 +6292,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData子消息为键。 - 如果发生删除操作的表使用索引作为REPLICA IDENTITY,则存在此字段。 + 将后续 TupleData 子消息标识为键。如果发生删除的表使用索引作为 REPLICA IDENTITY,则出现此字段。 @@ -6449,8 +6303,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData消息为旧元组。 - 如果发生删除操作的表的REPLICA IDENTITY设置为FULL,则存在此字段。 + 将后续 TupleData 消息标识为旧元组。如果发生删除的表将 REPLICA IDENTITY 设为 FULL,则出现此字段。 @@ -6461,14 +6314,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分,表示旧元组或主键的内容,取决于前一个字段。 + 表示旧元组或主键内容的 TupleData 消息部分,具体取决于前一个字段。 - 删除消息可能包含一个'K'消息部分或一个'O'消息部分,但绝不会同时包含两者。 + Delete 消息可以包含 'K' 消息部分或 'O' 消息部分,但绝不会同时包含两者。 @@ -6484,7 +6337,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为截断消息。 + 将该消息标识为 Truncate 消息。 @@ -6495,8 +6348,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6530,7 +6382,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。该字段对每个关系都重复。 + 关系的 OID,与 Relation 消息中的 ID 对应。每个关系都重复出现此字段。 @@ -6555,7 +6407,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为流开始消息。 + 将该消息标识为 Stream Start 消息。 @@ -6566,7 +6418,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6596,7 +6448,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为流停止消息。 + 将该消息标识为 Stream Stop 消息。 @@ -6615,7 +6467,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为流提交消息。 + 将该消息标识为 Stream Commit 消息。 @@ -6626,7 +6478,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6644,22 +6496,22 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 提交的LSN。 + 提交的 LSN。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 事务的结束LSN。 + 事务的结束 LSN。 @@ -6670,7 +6522,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6689,7 +6541,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为流中止消息。 + 将该消息标识为 Stream Abort 消息。 @@ -6700,7 +6552,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6757,14 +6609,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务开始消息。 + 将该消息标识为 Begin Prepare 消息。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6775,7 +6627,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6790,7 +6642,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6801,7 +6653,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6831,7 +6683,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务消息。 + 将该消息标识为 Prepare 消息。 @@ -6849,7 +6701,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6860,7 +6712,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6875,7 +6727,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6886,7 +6738,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6916,7 +6768,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务提交消息。 + 将该消息标识为 Commit Prepared 消息。 @@ -6934,7 +6786,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6945,7 +6797,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6960,7 +6812,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6971,7 +6823,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -7001,7 +6853,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务回滚消息。 + 将该消息标识为 Rollback Prepared 消息。 @@ -7019,7 +6871,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -7030,7 +6882,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -7045,7 +6897,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -7067,7 +6919,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -7097,7 +6949,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为流式预备事务消息。 + 将该消息标识为 Stream Prepare 消息。 @@ -7115,7 +6967,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -7126,7 +6978,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -7141,7 +6993,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -7152,7 +7004,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -7195,14 +7047,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于每一列(除了生成的列),会出现以下子消息之一: + 接下来,每个已发布的列都会出现以下子消息之一: Byte1('n') - 将数据标识为NULL值。 + 将该数据标识为 NULL 值。 @@ -7213,7 +7065,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('u') - 将TOASTed值标识为未更改的值(实际值未发送)。 + 标识未更改的 TOAST 值(不发送实际值)。 @@ -7224,7 +7076,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('t') - 将数据标识为文本格式化值。 + 将该数据标识为文本格式的值。 @@ -7235,7 +7087,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('b') - 将数据标识为二进制格式化值。 + 将该数据标识为二进制格式的值。 @@ -7253,9 +7105,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byten - 列的值,以二进制或文本格式呈现。 - (如前述格式字节中指定)。 - n是上述长度。 + 列值,采用二进制或文本格式(由前面的格式字节指定)。n 为上述长度。 diff --git a/zh/18/rangetypes.sgml b/zh/18/rangetypes.sgml index 68409fa3..5badec6c 100644 --- a/zh/18/rangetypes.sgml +++ b/zh/18/rangetypes.sgml @@ -5,11 +5,11 @@ 范围类型 - range type + 范围类型 - multirange type + 多范围类型 @@ -21,7 +21,7 @@ - 每种范围类型都有一个对应的多范围类型。多范围是由多个彼此不连续、非空且非 NULL 的范围构成的有序列表。大多数范围操作符也可作用于多范围,并且多范围还有一些专用函数。 + 每种范围类型都有一个对应的多范围类型。多范围是一个有序列表,其中的范围彼此不连续,且均非空、非 NULL。大多数范围操作符也可作用于多范围,并且多范围还有一些专用函数。 @@ -124,15 +124,15 @@ SELECT isempty(numrange(1, 5)); 无限(无界)范围 - 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作 +/-infinity,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的 +/-infinity 值。 + 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作正负无穷大,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的正负无穷大值。 - 具有infinity概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 + 具有无穷大概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 - 函数lower_infupper_inf分别测试范围的下界和上界是否为无限。 + 函数lower_infupper_inf分别测试范围是否没有下界和上界。 @@ -324,8 +324,8 @@ SELECT '[11:10, 23:00]'::timerange; 索引 - range type - indexes on + 范围类型 + 索引 @@ -357,7 +357,7 @@ CREATE INDEX reservation_idx ON reservation USING GIST (during); - 此外,也可以为范围类型的表列创建 B-树和哈希索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和哈希支持主要是为了允许在查询内部进行排序和哈希,而不是用于创建实际的索引。 + 此外,也可以为范围类型的表列创建 B-树和 hash 索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和 hash 支持主要是为了允许在查询内部进行排序和 hash 运算,而不是用于创建实际的索引。 @@ -366,8 +366,8 @@ CREATE INDEX reservation_idx ON reservation USING GIST (during); 范围上的约束 - range type - exclude + 范围类型 + 排他约束 diff --git a/zh/18/ref/alter_extension.sgml b/zh/18/ref/alter_extension.sgml index 3ceae003..b5824a68 100644 --- a/zh/18/ref/alter_extension.sgml +++ b/zh/18/ref/alter_extension.sgml @@ -170,7 +170,7 @@ ALTER EXTENSION name DROP 要添加到扩展中或从扩展中移除的对象名称。表、聚合、域、外部表、函数、 - 操作符、操作符类、操作符族、过程、例程、序列、文本搜索对象、类型和视图的名称 + 操作符、操作符类、操作符族、过程、例程、序列、文本检索对象、类型和视图的名称 可以带模式限定。 diff --git a/zh/18/ref/alter_tsconfig.sgml b/zh/18/ref/alter_tsconfig.sgml index 891dce66..0845a229 100644 --- a/zh/18/ref/alter_tsconfig.sgml +++ b/zh/18/ref/alter_tsconfig.sgml @@ -19,7 +19,7 @@ PostgreSQL documentation ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义 + 更改一个文本检索配置的定义 @@ -51,7 +51,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义。你可以修改其从记号类型到字典的映射, + 更改一个文本检索配置的定义。你可以修改其从词元类型到词典的映射, 或者更改该配置的名称或拥有者。 @@ -75,7 +75,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 一个现有文本搜索配置的名称(可以是模式限定的)。 + 一个现有文本检索配置的名称(可以是模式限定的)。 @@ -86,7 +86,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 由该配置的解析器发出的记号类型的名称。 + 由该配置的解析器发出的词元类型的名称。 @@ -97,7 +97,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 用于指定记号类型的文本搜索字典名称。如果列出了多个字典, + 用于指定词元类型的文本检索词典名称。如果列出了多个词典, 将按指定顺序依次查阅它们。 @@ -109,7 +109,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 在映射中要替换的文本搜索字典的名称。 + 在映射中要替换的文本检索词典的名称。 @@ -121,7 +121,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA 被用来替代old_dictionary - 的文本搜索字典的名称。 + 的文本检索词典的名称。 @@ -132,7 +132,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新名称。 + 该文本检索配置的新名称。 @@ -143,7 +143,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新拥有者。 + 该文本检索配置的新拥有者。 @@ -154,7 +154,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新模式。 + 该文本检索配置的新模式。 @@ -163,17 +163,17 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - ADD MAPPING FOR形式会为指定记号类型设置要查阅的字典列表; - 如果任一记号类型已经有映射,则会报错。ALTER MAPPING FOR - 形式作用相同,但会先移除这些记号类型的任何现有映射。 + ADD MAPPING FOR形式会为指定词元类型设置要查阅的词典列表; + 如果任一词元类型已经有映射,则会报错。ALTER MAPPING FOR + 形式作用相同,但会先移除这些词元类型的任何现有映射。 ALTER MAPPING REPLACE形式会在 old_dictionary出现的任何位置, 用new_dictionary替换它。 - 如果出现FOR,则只对指定的记号类型这样做;如果未出现 + 如果出现FOR,则只对指定的词元类型这样做;如果未出现 FOR,则对该配置的所有映射这样做。 - DROP MAPPING形式会移除指定记号类型的所有字典,使这些类型的 - 记号被文本搜索配置忽略。除非出现IF EXISTS,否则如果这些 - 记号类型没有映射就会报错。 + DROP MAPPING形式会移除指定词元类型的所有词典,使这些类型的 + 词元被文本检索配置忽略。除非出现IF EXISTS,否则如果这些 + 词元类型没有映射就会报错。 @@ -187,7 +187,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA 下面的示例将my_config中凡是使用 - english字典的地方,都替换为swedish字典。 + english词典的地方,都替换为swedish词典。 diff --git a/zh/18/ref/alter_tsdictionary.sgml b/zh/18/ref/alter_tsdictionary.sgml index 163d788b..798c6734 100644 --- a/zh/18/ref/alter_tsdictionary.sgml +++ b/zh/18/ref/alter_tsdictionary.sgml @@ -19,7 +19,7 @@ PostgreSQL documentation ALTER TEXT SEARCH DICTIONARY - 更改一个文本搜索字典的定义 + 更改一个文本检索词典的定义 @@ -43,14 +43,14 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - ALTER TEXT SEARCH DICTIONARY更改文本搜索字典的 - 定义。你可以更改该字典的模板相关选项,也可以更改该字典的名称或拥有者。 + ALTER TEXT SEARCH DICTIONARY更改文本检索词典的 + 定义。你可以更改该词典的模板相关选项,也可以更改该词典的名称或拥有者。 - 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该字典 + 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该词典 的拥有者。 @@ -67,7 +67,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 一个现有文本搜索字典的名称(可以是模式限定的)。 + 一个现有文本检索词典的名称(可以是模式限定的)。 @@ -78,7 +78,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -89,7 +89,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 模板相关选项要使用的新值。如果省略等号和值,则会从该字典中移除 + 模板相关选项要使用的新值。如果省略等号和值,则会从该词典中移除 该选项之前的设置,从而允许使用默认值。 @@ -101,7 +101,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新名称。 + 该文本检索词典的新名称。 @@ -112,7 +112,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新拥有者。 + 该文本检索词典的新拥有者。 @@ -123,7 +123,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新模式。 + 该文本检索词典的新模式。 @@ -144,7 +144,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 下面的示例命令更改了一个基于 Snowball 的字典的停用词列表。其他参数 + 下面的示例命令更改了一个基于 Snowball 的词典的停用词列表。其他参数 保持不变。 @@ -170,7 +170,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( language = dutch, StopWords ); - 下面的示例命令更新了该字典的定义,但实际上并没有做 + 下面的示例命令更新了该词典的定义,但实际上并没有做 任何更改。 @@ -178,7 +178,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( dummy ); (之所以可行,是因为选项移除代码在不存在该选项时也不会报错。) - 这种技巧在修改该字典的配置文件时很有用:ALTER + 这种技巧在修改该词典的配置文件时很有用:ALTER 会强制现有数据库会话重新读取配置文件,而如果它们先前已经读取过这 些文件,本来是不会再次读取的。 diff --git a/zh/18/ref/alter_tsparser.sgml b/zh/18/ref/alter_tsparser.sgml index 0844cb0a..ccc73f05 100644 --- a/zh/18/ref/alter_tsparser.sgml +++ b/zh/18/ref/alter_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH PARSER - 更改一个全文检索解析器的定义 + 更改一个文本检索解析器的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA 描述 - ALTER TEXT SEARCH PARSER更改全文检索解析器的定义。 + ALTER TEXT SEARCH PARSER更改文本检索解析器的定义。 当前唯一支持的功能是更改该解析器的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA name - 一个现有全文检索解析器的名称(可以是模式限定的)。 + 一个现有文本检索解析器的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_name - 该全文检索解析器的新名称。 + 该文本检索解析器的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_schema - 该全文检索解析器的新模式。 + 该文本检索解析器的新模式。 diff --git a/zh/18/ref/alter_tstemplate.sgml b/zh/18/ref/alter_tstemplate.sgml index a3eec599..9c9dfc2c 100644 --- a/zh/18/ref/alter_tstemplate.sgml +++ b/zh/18/ref/alter_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH TEMPLATE - 更改一个文本搜索模板的定义 + 更改一个文本检索模板的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA 描述 - ALTER TEXT SEARCH TEMPLATE更改文本搜索模板的定义。 + ALTER TEXT SEARCH TEMPLATE更改文本检索模板的定义。 当前唯一支持的功能是更改该模板的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA name - 一个现有文本搜索模板的名称(可以是模式限定的)。 + 一个现有文本检索模板的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_name - 该文本搜索模板的新名称。 + 该文本检索模板的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_schema - 该文本搜索模板的新模式。 + 该文本检索模板的新模式。 diff --git a/zh/18/ref/create_tsconfig.sgml b/zh/18/ref/create_tsconfig.sgml index 52970b36..fc77edb9 100644 --- a/zh/18/ref/create_tsconfig.sgml +++ b/zh/18/ref/create_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH CONFIGURATION - 定义一个新的文本搜索配置 + 定义一个新的文本检索配置 @@ -33,24 +33,24 @@ CREATE TEXT SEARCH CONFIGURATION name CREATE TEXT SEARCH CONFIGURATION - 创建一个新的文本搜索配置。文本搜索配置指定一个能把字符串拆分为记号 - 的文本搜索解析器,以及一些可用于判断哪些记号对搜索有意义的词典。 + 创建一个新的文本检索配置。文本检索配置指定一个能把字符串拆分为词元 + 的文本检索解析器,以及一些可用于判断哪些词元对搜索有意义的词典。 - 如果只指定了解析器,那么新文本搜索配置最初没有从记号类型到词典的映射, + 如果只指定了解析器,那么新文本检索配置最初没有从词元类型到词典的映射, 因而会忽略所有词。要让该配置真正可用,必须使用后续的ALTER TEXT SEARCH CONFIGURATION命令创建映射。 - 另一种方式是复制一个现有的文本搜索配置。 + 另一种方式是复制一个现有的文本检索配置。 - 如果给出了一个模式名称,则文本搜索配置会被创建在指定的模式中。否则它将会 + 如果给出了一个模式名称,则文本检索配置会被创建在指定的模式中。否则它将会 被创建在当前模式中。 - 定义该文本搜索配置的用户会成为其拥有者。 + 定义该文本检索配置的用户会成为其拥有者。 @@ -66,7 +66,7 @@ CREATE TEXT SEARCH CONFIGURATION namename - 要创建的文本搜索配置的名称。该名称可以是模式限定的。 + 要创建的文本检索配置的名称。该名称可以是模式限定的。 @@ -75,7 +75,7 @@ CREATE TEXT SEARCH CONFIGURATION nameparser_name - 此配置要使用的文本搜索解析器的名称。 + 此配置要使用的文本检索解析器的名称。 @@ -84,7 +84,7 @@ CREATE TEXT SEARCH CONFIGURATION namesource_config - 要复制的现有文本搜索配置的名称。 + 要复制的现有文本检索配置的名称。 diff --git a/zh/18/ref/create_tsdictionary.sgml b/zh/18/ref/create_tsdictionary.sgml index c45a7240..823710b7 100644 --- a/zh/18/ref/create_tsdictionary.sgml +++ b/zh/18/ref/create_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH DICTIONARY - 定义一个新的文本搜索字典 + 定义一个新的文本检索词典 @@ -33,19 +33,19 @@ CREATE TEXT SEARCH DICTIONARY name CREATE TEXT SEARCH DICTIONARY创建一个 - 新的文本搜索字典。文本搜索字典指定一种在搜索时识别哪些词值得关注、 - 哪些词不值得关注的方式。字典依赖于文本搜索模板,后者规定了实际执行 - 这项工作的函数。通常,字典会提供一些选项,用来控制模板函数的具体 + 新的文本检索词典。文本检索词典指定一种在搜索时识别哪些词值得关注、 + 哪些词不值得关注的方式。词典依赖于文本检索模板,后者规定了实际执行 + 这项工作的函数。通常,词典会提供一些选项,用来控制模板函数的具体 行为。 - 如果给出了一个模式名称,那么该文本搜索字典会被创建在指定的模式中。 + 如果给出了一个模式名称,那么该文本检索词典会被创建在指定的模式中。 否则它会被创建在当前模式中。 - 定义文本搜索字典的用户将成为其拥有者。 + 定义文本检索词典的用户将成为其拥有者。 @@ -61,7 +61,7 @@ CREATE TEXT SEARCH DICTIONARY name name - 要创建的文本搜索字典的名称。该名称可以被模式限定。 + 要创建的文本检索词典的名称。该名称可以被模式限定。 @@ -70,7 +70,7 @@ CREATE TEXT SEARCH DICTIONARY name template - 用于定义该字典基本行为的文本搜索模板名称。 + 用于定义该词典基本行为的文本检索模板名称。 @@ -79,7 +79,7 @@ CREATE TEXT SEARCH DICTIONARY name option - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -105,7 +105,7 @@ CREATE TEXT SEARCH DICTIONARY name 下面的示例命令创建了一个基于 Snowball 且使用非标准停用词列表的 - 字典。 + 词典。 diff --git a/zh/18/ref/create_tsparser.sgml b/zh/18/ref/create_tsparser.sgml index 358152ce..88be54e6 100644 --- a/zh/18/ref/create_tsparser.sgml +++ b/zh/18/ref/create_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH PARSER - 定义一个新的全文检索解析器 + 定义一个新的文本检索解析器 @@ -36,19 +36,19 @@ CREATE TEXT SEARCH PARSER name ( CREATE TEXT SEARCH PARSER创建一个 - 新的全文检索解析器。全文检索解析器定义了一种方法,用于将文本字符串 - 拆分成记号并为这些记号指定类型(类别)。解析器本身并没有太大用处, - 必须与一些全文检索字典一起绑定到一个全文检索配置中,才能用于搜索。 + 新的文本检索解析器。文本检索解析器定义了一种方法,用于将文本字符串 + 拆分成词元并为这些词元指定类型(类别)。解析器本身并没有太大用处, + 必须与一些文本检索词典一起绑定到一个文本检索配置中,才能用于搜索。 - 如果给出了一个模式名称,那么全文检索解析器将被创建在指定的模式中。 + 如果给出了一个模式名称,那么文本检索解析器将被创建在指定的模式中。 否则它会被创建在当前模式中。 要使用CREATE TEXT SEARCH PARSER,你必须是超级用户。 - 之所以有此限制,是因为错误的全文检索解析器定义可能会让服务器陷入 + 之所以有此限制,是因为错误的文本检索解析器定义可能会让服务器陷入 混乱,甚至崩溃。 @@ -65,7 +65,7 @@ CREATE TEXT SEARCH PARSER name ( name - 要创建的全文检索解析器的名称。该名称可以是模式限定的。 + 要创建的文本检索解析器的名称。该名称可以是模式限定的。 @@ -83,7 +83,7 @@ CREATE TEXT SEARCH PARSER name ( gettoken_function - 该解析器的获取下一个记号的函数名称。 + 该解析器的获取下一个词元的函数名称。 @@ -101,7 +101,7 @@ CREATE TEXT SEARCH PARSER name ( lextypes_function - 该解析器的 lextypes 函数的名称(该函数返回它所产生的记号类型集合的 + 该解析器的 lextypes 函数的名称(该函数返回它所产生的词元类型集合的 信息)。 @@ -111,7 +111,7 @@ CREATE TEXT SEARCH PARSER name ( headline_function - 该解析器的 headline 函数的名称(该函数对一组记号生成摘要)。 + 该解析器的 headline 函数的名称(该函数对一组词元生成摘要)。 diff --git a/zh/18/ref/create_tstemplate.sgml b/zh/18/ref/create_tstemplate.sgml index 702233e4..0f1b4e1a 100644 --- a/zh/18/ref/create_tstemplate.sgml +++ b/zh/18/ref/create_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH TEMPLATE - 定义一个新的全文检索模板 + 定义一个新的文本检索模板 @@ -33,22 +33,22 @@ CREATE TEXT SEARCH TEMPLATE name ( CREATE TEXT SEARCH TEMPLATE创建一个 - 新的全文检索模板。全文检索模板定义实现全文检索字典的函数。模板本身 - 并无直接用途,必须先实例化为字典后才能使用。字典通常会指定要传递给 + 新的文本检索模板。文本检索模板定义实现文本检索词典的函数。模板本身 + 并无直接用途,必须先实例化为词典后才能使用。词典通常会指定要传递给 模板函数的参数。 - 如果给出了模式名称,则全文检索模板会被创建在指定模式中。否则它会被 + 如果给出了模式名称,则文本检索模板会被创建在指定模式中。否则它会被 创建在当前模式中。 要使用CREATE TEXT SEARCH TEMPLATE,你 - 必须是超级用户。之所以有此限制,是因为错误的全文检索模板定义可能使 - 服务器陷入混乱,甚至崩溃。将模板与字典分离的原因在于,模板封装了定 - 义字典时那些不安全的方面。而在定义字典时可设置的参数, - 对非特权用户来说是安全的,因此创建字典不必是特权操作。 + 必须是超级用户。之所以有此限制,是因为错误的文本检索模板定义可能使 + 服务器陷入混乱,甚至崩溃。将模板与词典分离的原因在于,模板封装了定 + 义词典时那些不安全的方面。而在定义词典时可设置的参数, + 由普通用户设置也是安全的,因此创建词典不必是特权操作。 @@ -64,7 +64,7 @@ CREATE TEXT SEARCH TEMPLATE name ( name - 要创建的全文检索模板名称。该名称可以是模式限定的。 + 要创建的文本检索模板名称。该名称可以是模式限定的。 diff --git a/zh/18/ref/drop_opclass.sgml b/zh/18/ref/drop_opclass.sgml index 9d67dc64..545a2517 100644 --- a/zh/18/ref/drop_opclass.sgml +++ b/zh/18/ref/drop_opclass.sgml @@ -110,7 +110,7 @@ DROP OPERATOR CLASS [ IF EXISTS ] name示例 - 移除 B-tree 操作符类widget_ops: + 移除 B-树操作符类widget_ops DROP OPERATOR CLASS widget_ops USING btree; diff --git a/zh/18/ref/drop_tsconfig.sgml b/zh/18/ref/drop_tsconfig.sgml index ea139802..b3ebb9d1 100644 --- a/zh/18/ref/drop_tsconfig.sgml +++ b/zh/18/ref/drop_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH CONFIGURATION - 移除一个文本搜索配置 + 移除一个文本检索配置 @@ -29,7 +29,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 描述 - DROP TEXT SEARCH CONFIGURATION删除一个现有文本搜索配置。 + DROP TEXT SEARCH CONFIGURATION删除一个现有文本检索配置。 要执行此命令,你必须是该配置的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name IF EXISTS - 如果该文本搜索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name name - 现有文本搜索配置的名称(可以被模式限定)。 + 现有文本检索配置的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name CASCADE - 自动删除依赖于该文本搜索配置的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索配置的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name RESTRICT - 如果有任何对象依赖于该文本搜索配置,则拒绝删除该配置。这是默认值。 + 如果有任何对象依赖于该文本检索配置,则拒绝删除该配置。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 示例 - 移除文本搜索配置my_english: + 移除文本检索配置my_english DROP TEXT SEARCH CONFIGURATION my_english; 如果已有索引在to_tsvector调用中引用了该配置, - 此命令将不会成功。加上CASCADE可以在删除该文本搜索配置的同时删除这类索引。 + 此命令将不会成功。加上CASCADE可以在删除该文本检索配置的同时删除这类索引。 diff --git a/zh/18/ref/drop_tsdictionary.sgml b/zh/18/ref/drop_tsdictionary.sgml index 316c5d00..0f7751a1 100644 --- a/zh/18/ref/drop_tsdictionary.sgml +++ b/zh/18/ref/drop_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH DICTIONARY - 移除一个文本搜索字典 + 移除一个文本检索词典 @@ -29,8 +29,8 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name描述 - DROP TEXT SEARCH DICTIONARY删除一个现有文本搜索字典。 - 要执行此命令,你必须是该字典的拥有者。 + DROP TEXT SEARCH DICTIONARY删除一个现有文本检索词典。 + 要执行此命令,你必须是该词典的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索字典不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索词典不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] namename - 一个现有文本搜索字典的名称(可以被模式限定)。 + 一个现有文本检索词典的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索字典的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索词典的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索字典,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索词典,则拒绝删除它。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name示例 - 移除文本搜索字典english: + 移除文本检索词典english DROP TEXT SEARCH DICTIONARY english; - 如果已有文本搜索配置使用该字典,此命令将不会成功。 - 加上CASCADE可以在删除字典的同时删除这类配置。 + 如果已有文本检索配置使用该词典,此命令将不会成功。 + 加上CASCADE可以在删除词典的同时删除这类配置。 diff --git a/zh/18/ref/drop_tsparser.sgml b/zh/18/ref/drop_tsparser.sgml index a65f47be..ea74f0f8 100644 --- a/zh/18/ref/drop_tsparser.sgml +++ b/zh/18/ref/drop_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH PARSER - 移除一个文本搜索解析器 + 移除一个文本检索解析器 @@ -29,7 +29,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name描述 - DROP TEXT SEARCH PARSER删除一个现有文本搜索解析器。 + DROP TEXT SEARCH PARSER删除一个现有文本检索解析器。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] namename - 一个现有文本搜索解析器的名称(可以被模式限定)。 + 一个现有文本检索解析器的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索解析器的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索解析器的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索解析器,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索解析器,则拒绝删除它。这是默认值。 @@ -82,13 +82,13 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name示例 - 移除文本搜索解析器my_parser: + 移除文本检索解析器my_parser DROP TEXT SEARCH PARSER my_parser; - 如果已有文本搜索配置使用该解析器,此命令将不会成功。 + 如果已有文本检索配置使用该解析器,此命令将不会成功。 加上CASCADE可以在删除解析器的同时删除这类配置。 diff --git a/zh/18/ref/drop_tstemplate.sgml b/zh/18/ref/drop_tstemplate.sgml index fa1faab0..3a44c927 100644 --- a/zh/18/ref/drop_tstemplate.sgml +++ b/zh/18/ref/drop_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH TEMPLATE - 移除一个文本搜索模板 + 移除一个文本检索模板 @@ -29,7 +29,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name描述 - DROP TEXT SEARCH TEMPLATE删除一个现有文本搜索模板。 + DROP TEXT SEARCH TEMPLATE删除一个现有文本检索模板。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] namename - 现有文本搜索模板的名称(可以被模式限定)。 + 现有文本检索模板的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索模板的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索模板的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索模板,则拒绝删除该模板。这是默认值。 + 如果有任何对象依赖于该文本检索模板,则拒绝删除该模板。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name示例 - 移除文本搜索模板thesaurus: + 移除文本检索模板thesaurus DROP TEXT SEARCH TEMPLATE thesaurus; - 如果已有文本搜索字典使用该模板,此命令将不会成功。加上CASCADE - 可以在删除该模板的同时删除这类字典。 + 如果已有文本检索词典使用该模板,此命令将不会成功。加上CASCADE + 可以在删除该模板的同时删除这类词典。 diff --git a/zh/18/ref/initdb.sgml b/zh/18/ref/initdb.sgml index 6ac68117..80c714e3 100644 --- a/zh/18/ref/initdb.sgml +++ b/zh/18/ref/initdb.sgml @@ -327,7 +327,7 @@ PostgreSQL documentation - 设置默认文本搜索配置。更多信息见 + 设置默认文本检索配置。更多信息见 diff --git a/zh/18/ref/pgbench.sgml b/zh/18/ref/pgbench.sgml index e0fa9e55..e2afa67b 100644 --- a/zh/18/ref/pgbench.sgml +++ b/zh/18/ref/pgbench.sgml @@ -39,7 +39,7 @@ PostgreSQL documentation 描述 - pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,必要时可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 + pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,也可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 @@ -69,7 +69,7 @@ tps = 896.967014 (without initial connection time) - 默认的类 TPC-B 事务测试要求预先建立特定的表。应使用(initialize)选项调用pgbench来创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: + 默认的类 TPC-B 事务测试要求预先建立特定的表。应使用(初始化)选项调用pgbench来创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: pgbench -i other-options dbname @@ -89,14 +89,14 @@ pgbench -i other-options 在默认的比例因子 1 下,这些表最初包含如下行数: -table # of rows +表 行数 --------------------------------- pgbench_branches 1 pgbench_tellers 10 pgbench_accounts 100000 pgbench_history 0 - 可以使用(比例因子)选项来增加行数,而且在大多数场景下也确实应该这样做。此时还可以配合使用(fillfactor)选项。 + 可以使用(比例因子)选项来增加行数,而且在大多数场景下通常也应该这样做。此时还可以配合使用(fillfactor)选项。 @@ -116,7 +116,7 @@ pgbench options d 选项 - 下面分成三个部分。数据库初始化期间使用的选项和运行基准时会使用不同的选项,但也有一些选项在两种情况下都使用。 + 以下内容分为三个小节。数据库初始化和运行基准测试时使用不同的选项,但有些选项在这两种情况下都适用。 @@ -196,7 +196,7 @@ pgbench options d 使用G(服务器端生成数据)时, pgbench客户端只发送较小的查询,随后实际数据在服务器端生成。 - 这种方式几乎不需要额外带宽,但服务器会承担更多工作。 + 这种方式不需要大量带宽,但服务器会承担更多工作。 使用G时,生成数据期间不会打印任何进度消息。 @@ -505,13 +505,13 @@ pgbench options d 用于向服务器提交查询的协议: - simple: 使用简单查询协议。 + simple:使用简单查询协议。 - extended: 使用扩展查询协议。 + extended:使用扩展查询协议。 - prepared: 使用带有预备语句的扩展查询协议。 + prepared:使用带有预备语句的扩展查询协议。 @@ -572,7 +572,7 @@ pgbench options d - 在基准测试完成后,报告每条语句的以下统计信息:平均延迟(从客户端视角看到的语句执行时间)、失败次数,以及该语句因串行化或死锁错误而发生的重试次数。仅当选项不等于 1 时,报告才会显示重试统计信息。 + 在基准测试完成后,报告每条命令的以下统计信息:平均延迟(从客户端视角看到的语句执行时间)、失败次数,以及该命令因串行化或死锁错误而发生的重试次数。仅当选项不等于 1 时,报告才会显示重试统计信息。 @@ -607,7 +607,7 @@ pgbench options d 较高的计划滞后时间表明,在所选客户端数和线程数下,系统无法以指定速率处理事务。 当平均事务执行时间长于事务之间的计划间隔时,后续事务会不断进一步落后, - 而计划滞后时间也会随着测试持续时间增加。在这种情况下,只能降低指定的事务速率。 + 而计划滞后时间也会随着测试持续时间增加。在这种情况下,需要降低指定的事务速率。 @@ -619,7 +619,7 @@ pgbench options d pgbench输出中报告指定的比例因子。 - 对于内置测试,这通常没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 + 对于内置测试,这没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 但在只测试自定义基准(选项)时, 除非使用此选项,否则比例因子会被报告为 1。 @@ -733,7 +733,7 @@ pgbench options d 启用对出现串行化/死锁错误的事务进行重试,并设置最大尝试次数。此选项可与 - 组合使用,后者限制所有事务尝试的总耗时; + 组合使用,后者限制同一事务所有尝试的总耗时; 此外,如果没有, 则不能使用无限次尝试(--max-tries=0)。 默认值为 1,出现串行化/死锁错误的事务不会重试。有关此类事务重试的更多信息,见 @@ -813,7 +813,7 @@ pgbench options d - 打印关于所有错误和失败的消息(即不会重试的错误),包括超出了哪一种重试限制,以及对于串行化/死锁失败超出的幅度。(请注意,这种情况下输出量可能会显著增加。)更多信息见。 + 打印关于所有错误和失败(不再重试的错误)的消息,包括超出了哪一种重试限制,以及对于串行化/死锁失败超出的幅度。(请注意,这种情况下输出量可能会显著增加。)更多信息见 @@ -941,7 +941,7 @@ pgbench options d 注解 - + 在<application>pgbench</application>中实际执行的<quote>事务</quote>是什么? @@ -996,7 +996,7 @@ pgbench options d - 假定pgbench脚本不包含不完整的 SQL 事务块。如果在运行时客户端在尚未完成最后一个事务块时就到达脚本末尾,它将被中止。 + 假定pgbench脚本不包含不完整的 SQL 事务块。如果在运行时客户端在尚未完成最后一个事务块时就到达脚本末尾,该客户端将被中止。 @@ -1033,7 +1033,7 @@ pgbench options d default_seed - 默认在哈希和伪随机置换函数中使用的种子 + 默认在 hash 和伪随机置换函数中使用的种子 @@ -1050,7 +1050,7 @@ pgbench options d - 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令及其参数之间以空白分隔。支持的元命令如下: + 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令的参数以空白分隔。支持的元命令如下: @@ -1088,7 +1088,7 @@ UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid RETURNING abalance \gset --- compound of two queries +-- 两个查询的组合 SELECT 1 \; SELECT 2 AS two, 3 AS three \gset p_ SELECT 4 AS four \; SELECT 5 AS five \aset @@ -1180,7 +1180,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset - command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在其开头再写一个冒号。 + command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在argument开头再写一个冒号。 @@ -1218,7 +1218,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset - 这组命令用于实现 SQL 语句的流水线执行。流水线必须以\startpipeline开始,并以\endpipeline结束;在两者之间可以出现任意数量的\syncpipeline,它会发送一个sync 消息,但不会结束当前流水线,同时会刷新发送缓冲区。在流水线模式下,语句会发送到服务器,而不等待前一条语句的结果。更多细节见。流水线模式要求使用扩展查询协议。 + 这组命令用于实现 SQL 语句的管道执行。管道必须以\startpipeline开始,并以\endpipeline结束;在两者之间可以出现任意数量的\syncpipeline,它会发送一个sync 消息,既不会结束当前管道,也不会刷新发送缓冲区。在管道模式下,语句会发送到服务器,而不等待前一条语句的结果。更多细节见。管道模式要求使用扩展查询协议。 @@ -1514,7 +1514,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 加 + 加法 5 + 4 @@ -1528,7 +1528,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 减 + 减法 3 - 2.0 @@ -1542,7 +1542,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 乘 + 乘法 5 * 4 @@ -1556,7 +1556,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 除法(如果两个输入都是整数,则将结果截断为零) + 除法(如果两个输入都是整数,则将结果向零截断) 5 / 3 @@ -1584,7 +1584,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 取反 + 取相反数 - 2.0 @@ -1674,7 +1674,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset double - 指数(e 的给定次幂) + 指数函数(e 的给定次幂) exp(1.0) @@ -1716,7 +1716,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算 FNV-1a 哈希。 + 计算 FNV-1a hash hash_fnv1a(10, 5432) @@ -1730,7 +1730,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算 MurmurHash2 哈希。 + 计算 MurmurHash2 hash hash_murmur2(10, 5432) @@ -1800,8 +1800,8 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - i的排列值,范围在[0, size)内。 - 它表示i(模size)在整数0...size-1的伪随机排列中的新位置;该排列由seed参数化,详见下文。 + i的置换值,范围在[0, size)内。 + 它表示i(模size)在整数0...size-1的伪随机置换中的新位置;该置换由seed参数化,详见下文。 permute(0, 4) @@ -1861,7 +1861,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算[lb, ub]中的指数分布随机整数,如下所示。 + 计算[lb, ub]中的指数分布随机整数,详见下文。 random_exponential(1, 10, 3.0) @@ -1875,7 +1875,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算[lb, ub]中的高斯分布随机整数,如下所示。 + 计算[lb, ub]中的高斯分布随机整数,详见下文。 random_gaussian(1, 10, 2.5) @@ -1922,7 +1922,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset - 对于指数分布,parameter通过在parameter处截断一个快速衰减的指数分布,再将其投影到边界之间的整数上,从而控制分布。准确地说, + 对于指数分布,parameter通过在parameter处截断一个快速衰减的指数分布,再将其投影到边界之间的整数上,从而控制分布。准确地说,令 f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) @@ -1930,7 +1930,7 @@ f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) - 直观地说,parameter越大,越靠近min的值越容易被抽到,而越靠近max的值越不容易被抽到。parameter越接近 0,分布就越平坦(也就越均匀)。对这种分布的一个粗略近似是:范围内最靠近min的那 1% 常见值,大约会占到parameter% 的抽样次数。parameter必须严格大于 0。 + 直观地说,parameter越大,越靠近min的值越容易被抽到,而越靠近max的值越不容易被抽到。parameter越接近 0,分布就越平坦(也就越均匀)。对这种分布的一个粗略近似是:范围内出现频率最高的 1% 的值,即最靠近min的那些值,大约会占到parameter% 的抽样次数。parameter必须严格大于 0。 @@ -1942,7 +1942,7 @@ f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / (2.0 * PHI(parameter) - 1) - 则minmax(包含边界)之间的值i被抽中的概率为:f(i + 0.5) - f(i - 0.5)。直观地说,parameter越大,越靠近区间中间的值被抽到的频率越高,而越靠近minmax边界的值被抽到的频率越低。大约 67% 的值会落在区间中部1.0 / parameter这一段内,也就是均值两侧各0.5 / parameter的范围内;约 95% 的值会落在区间中部2.0 / parameter这一段内,也就是均值两侧各1.0 / parameter的范围内。例如,如果parameter为 4.0,则 67% 的值会落在区间中间四分之一(1.0 / 4.0)内,也就是从3.0 / 8.05.0 / 8.0;95% 的值会落在区间中间一半(2.0 / 4.0)内,也就是第二和第三四分位。允许的最小parameter值为 2.0。 + 则minmax(包含边界)之间的值i被抽中的概率为:f(i + 0.5) - f(i - 0.5)。直观地说,parameter越大,越靠近区间中间的值被抽到的频率越高,而越靠近minmax边界的值被抽到的频率越低。大约 67% 的值会落在区间中部1.0 / parameter这一段内,也就是均值两侧各占区间长度0.5 / parameter的范围内;约 95% 的值会落在区间中部2.0 / parameter这一段内,也就是均值两侧各占区间长度1.0 / parameter的范围内。例如,如果parameter为 4.0,则 67% 的值会落在区间中间四分之一(1.0 / 4.0)内,也就是从3.0 / 8.05.0 / 8.0;95% 的值会落在区间中间一半(2.0 / 4.0)内,也就是第二和第三四分位。允许的最小parameter值为 2.0。 @@ -1974,12 +1974,12 @@ f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / - 哈希函数hashhash_murmur2hash_fnv1a都接受一个输入值和一个可选的种子参数。 - 如果没有提供种子,则会使用:default_seed的值;除非通过命令行选项覆盖,否则该值会被随机初始化。 + Hash 函数hashhash_murmur2hash_fnv1a都接受一个输入值和一个可选的种子参数。 + 如果没有提供种子,则会使用:default_seed的值;除非通过命令行-D选项覆盖,否则该值会被随机初始化。 - permute接受一个输入值、一个大小参数以及一个可选的种子参数。它会生成范围[0, size)内整数的伪随机排列,并返回输入值在该排列中的索引。如果未指定种子,则默认使用:default_seed。与哈希函数不同,permute保证输出值中不会出现冲突或空洞。区间之外的输入值会按size取模解释。如果size不是正数,该函数会报错。permute可用于打散诸如random_zipfianrandom_exponential这类非均匀随机函数的分布,使那些更常抽到的值不再具有显而易见的相关性。例如,下面的pgbench脚本模拟了社交媒体和博客平台中一种可能的真实工作负载,其中少数账户会产生过量负载: + permute接受一个输入值、一个大小参数以及一个可选的种子参数。它会生成范围[0, size)内整数的伪随机置换,并返回输入值在该置换中的索引。所选置换由种子参数决定;如果未指定种子,则默认使用:default_seed。与 hash 函数不同,permute保证输出值中不会出现冲突或空洞。区间之外的输入值会按size取模解释。如果size不是正数,该函数会报错。permute可用于打散诸如random_zipfianrandom_exponential这类非均匀随机函数的分布,使那些更常抽到的值不再具有显而易见的相关性。例如,下面的pgbench脚本模拟了社交媒体和博客平台中一种可能的真实工作负载,其中少数账户会产生过量负载: \set size 1000000 @@ -2036,7 +2036,7 @@ END; - 每行日志文件描述一个事务。 + 日志文件的每一行描述一个事务。 它包含以下以空格分隔的字段: @@ -2436,7 +2436,7 @@ statement latencies in milliseconds and failures: 使用可串行化默认事务隔离级别的默认脚本的另一个输出示例 - (PGOPTIONS='-c default_transaction_isolation=serializable' pgbench ...): + (PGOPTIONS='-c default_transaction_isolation=serializable' pgbench ...): starting vacuum...end. transaction type: <builtin: TPC-B (sort of)> @@ -2479,7 +2479,7 @@ statement latencies in milliseconds, failures and retries: - + 失败和串行化/死锁重试 @@ -2537,7 +2537,7 @@ statement latencies in milliseconds, failures and retries: - 不指定选项时,事务在发生串行化或死锁错误后永远不会重试,因为其默认值为 1。可以使用无限次尝试(--max-tries=0)并配合选项,仅限制重试的最长时间。也可以使用选项,在无限次尝试的情况下限制基准测试持续时间。 + 不指定选项时,事务在发生串行化或死锁错误后永远不会重试,因为其默认值为 1。可以使用无限次尝试(--max-tries=0)并配合选项,仅限制尝试的最长总时间。也可以使用选项,在无限次尝试的情况下限制基准测试持续时间。 @@ -2558,7 +2558,7 @@ statement latencies in milliseconds, failures and retries: - 如果希望在逐事务日志、聚合日志以及主报告和逐脚本报告中按基本类型对失败进行分组,请使用选项。如果还希望按类型区分所有错误和失败(即不会重试的错误),包括超出了哪一种重试限制,以及串行化/死锁失败超出了多少,请使用选项。 + 如果希望在逐事务日志、聚合日志以及主报告和逐脚本报告中按基本类型对失败进行分组,请使用选项。如果还希望按类型区分所有错误和失败(不再重试的错误),包括超出了哪一种重试限制,以及串行化/死锁失败超出了多少,请使用选项。 @@ -2590,7 +2590,7 @@ PGOPTIONS='-c default_table_access_method=wuzza' - 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和空闲空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 + 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和无效空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 diff --git a/zh/18/ref/psql-ref.sgml b/zh/18/ref/psql-ref.sgml index 083bf93b..7490fca3 100644 --- a/zh/18/ref/psql-ref.sgml +++ b/zh/18/ref/psql-ref.sgml @@ -47,7 +47,7 @@ PostgreSQL documentation - 把所有非空输入行按照它们被读入的形式打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 + 在读入时将所有非空输入行打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 all @@ -58,7 +58,7 @@ PostgreSQL documentation - 切换到非对齐输出模式(默认输出模式是对齐的)。这等效于\pset format unaligned。 + 切换到非对齐输出模式(默认输出模式是aligned)。这等效于\pset format unaligned @@ -78,10 +78,10 @@ PostgreSQL documentation - 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,直到它处理完序列中所有的选项之后终止。 + 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,而是在按顺序处理完所有选项后终止。 - command必须是一个服务器完全可解析的命令字符串(即不包含psql相关的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: + command必须是一个服务器完全可解析的命令字符串(即不包含psql专有的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: psql -c '\x' -c 'SELECT * FROM foo;' @@ -172,7 +172,7 @@ EOF - 使用separator作为非对齐输出的域分隔符。这等效于\pset fieldsep或者\f。 + 使用separator作为非对齐输出的字段分隔符。这等效于\pset fieldsep或者\f @@ -246,7 +246,7 @@ EOF - 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。 + 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展名。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。 @@ -266,7 +266,7 @@ EOF - 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息以及多种输出。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon。 + 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息和各种提示信息。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon @@ -286,7 +286,7 @@ EOF - 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户一个可以取消执行的选项。使用这个选项可以调试脚本。 + 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户,并允许取消执行。使用这个选项可以调试脚本。 @@ -296,7 +296,7 @@ EOF - 运行在单行模式中,其中新行会终止一个 SQL 命令,就像分号的作用一样。 + 运行在单行模式中,其中换行符会终止一个 SQL 命令,就像分号的作用一样。 @@ -322,7 +322,7 @@ EOF - 指定要替换HTML table标签的选项。详见\pset tableattr。 + 指定要放在HTML table标签内的选项。详见\pset tableattr @@ -343,7 +343,7 @@ EOF - 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要重置一个变量,去掉等号就行。要把一个变量置为空值,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 + 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要取消变量的设置,去掉等号就行。要把一个变量设为空字符串,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 @@ -405,7 +405,7 @@ EOF - 不读取启动文件(要么是系统范围的psqlrc文件,要么是用户的~/.psqlrc文件)。 + 不读取启动文件(既不读取系统范围的psqlrc文件,也不读取用户的~/.psqlrc文件)。 @@ -415,7 +415,7 @@ EOF - 设置非对齐输出的域分隔符为零字节。这等效于\pset fieldsep_zero。 + 设置非对齐输出的字段分隔符为零字节。这等效于\pset fieldsep_zero @@ -425,7 +425,7 @@ EOF - 设置非对齐输出的记录分隔符为零字节。例如,这对与xargs -0配合有关。这等效于\pset recordsep_zero。 + 设置非对齐输出的记录分隔符为零字节。例如,这有助于与xargs -0配合使用。这等效于\pset recordsep_zero @@ -438,7 +438,7 @@ EOF 这个选项只能与一个或多个和/或选项结合使用。 它会导致psql在第一个这样的选项之前发出一个BEGIN命令, 并在最后一个选项之后发出一个COMMIT命令,从而将所有命令包装成一个单独的事务。 - 如果任何命令失败且变量ON_ERROR_STOP被设置,那么会发送一个ROLLBACK命令。 + 如果任何命令失败且变量ON_ERROR_STOP被设置,则会改为发送一个ROLLBACK命令。 这确保要么所有命令都成功完成,要么不应用任何更改。 @@ -550,7 +550,7 @@ testdb=> 元命令 - 你输入到psql中的任何以未加引用的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 + 你输入到psql中的任何以未加引号的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 @@ -567,7 +567,7 @@ testdb=> - 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉尾随换行)会替换反引号中的文本。在反引号包围的文本内部,不会发生特殊引用或其他处理,只有一种例外:如果出现:variable_name,且variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会被适当地引用成单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于回车和换行字符在所有平台上都无法安全引用,当变量值中出现这类字符时,:'variable_name'这种形式会打印错误消息,并且不会替换变量值。 + 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉末尾的换行符)会替换反引号中的文本。在反引号包围的文本内部,不会进行特殊的引号处理或其他处理,但出现:variable_name时,如果variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会适当地加上引号,使其成为单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于无法保证在所有平台上都能对回车和换行字符安全地加引号,当变量值中出现这类字符时,:'variable_name'形式会打印错误消息,并且不会替换变量值。 @@ -579,8 +579,8 @@ testdb=> - 很多元命令作用在当前查询缓冲区上。这就是一个缓冲区而已,它保存任何已经被键入但是还没有发送到服务器执行的SQL命令文本。这将包括之前输入的行以及在该元命令同一行上出现在前面的任何文本。 - + 许多元命令作用于当前查询缓冲区。这只是一个保存已输入但尚未发送到服务器执行的 SQL 命令文本的缓冲区。其中既包括先前输入的行,也包括同一行上位于元命令之前的文本。 + 许多元命令还允许在命令名后追加 x 作为选项。这会使结果以扩展模式显示,就像使用了 \x\pset expanded 一样。 @@ -594,7 +594,7 @@ testdb=> \a - 如果当前表格输出格式是不对齐,则切换为对齐;否则切换为不对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset。 + 如果当前表格输出格式是非对齐,则切换为对齐;否则切换为非对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset @@ -654,7 +654,7 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1 \c\connect [ -reuse-previous=on|off ] [ dbname [ username ] [ host ] [ port ] | conninfo ] - 建立到PostgreSQL服务器的新连接。可以使用位置语法(数据库名称、用户、主机和端口中的一个或多个)指定要使用的连接参数,也可以使用详细说明在中的conninfo连接字符串。如果没有给出参数,则使用与之前相同的参数建立新连接。 + 建立到PostgreSQL服务器的新连接。可以使用位置语法(数据库名称、用户、主机和端口中的一个或多个)指定要使用的连接参数,也可以使用conninfo连接字符串,详见。如果没有给出参数,则使用与之前相同的参数建立新连接。 @@ -670,7 +670,7 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1 默认情况下,参数在位置语法中被重用,但在给定conninfo字符串时不会被重用。 传递-reuse-previous=on-reuse-previous=off作为第一个参数将覆盖该默认设置。 如果参数被重用,则任何未明确指定为位置参数或在conninfo字符串中的参数将从现有连接的参数中获取。 - 一个例外是,如果使用位置语法将host设置更改为其先前值,则现有连接参数中存在的任何hostaddr设置将被删除。 + 一个例外是,如果使用位置语法更改host设置,使其不同于先前的值,则现有连接参数中存在的任何hostaddr设置将被删除。 此外,仅当用户、主机和端口设置未更改时,才会重用现有连接使用的任何密码。 当命令既不指定也不重用特定参数时,将使用libpq的默认值。 @@ -692,7 +692,7 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1 => \c mydb myuser host.dom 6432 => \c service=foo => \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable" -=> \c -reuse-previous=on sslmode=require -- changes only sslmode +=> \c -reuse-previous=on sslmode=require -- 仅更改 sslmode => \c postgresql://tom@localhost/mydb?application_name=myapp @@ -702,11 +702,8 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1 \C [ title ] - 设置作为查询结果打印的任何表格的标题,或取消任何这样的标题。此命令等效于 - \pset title title。(此命令的名称源自caption, - 因为它以前仅用于设置HTML表格中的标题。) - + 设置作为查询结果打印的表的标题,或取消此类标题。该命令等价于\pset title title。(此命令的名称源自caption,因为它过去只用于设置HTML表的标题。) + @@ -731,7 +728,7 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1 - 关闭指定的预备语句。空字符串表示未命名的预备语句。如果不存在该名称的预备语句,则该操作不执行任何操作。 + 关闭指定的预备语句。空字符串表示未命名的预备语句。如果不存在该名称的预备语句,则不执行任何操作。 @@ -836,46 +833,24 @@ SELECT $1 \parse stmt1 ] ] ] ] - 执行当前查询缓冲区(类似于\g)并在交叉表格中显示结果。 - 查询必须返回至少三列。 - 由colV标识的输出列成为垂直标题, - 由colH标识的输出列成为水平标题。 - colD标识要在网格中显示的输出列。 - sortcolH标识水平标题的可选排序列。 - + 执行当前查询缓冲区(与\g类似),并以交叉表网格显示结果。查询必须返回至少三列。由colV标识的输出列成为纵向表头,由colH标识的输出列成为横向表头。colD标识要在网格中显示的输出列。sortcolH标识横向表头的可选排序列。 + - 每个列规范可以是列号(从1开始)或列名。列名遵循通常的SQL大小写折叠和引用规则。如果省略, - colV被视为第1列, - colH被视为第2列。 - colH必须与 - colV不同。 - 如果未指定colD,则查询结果中必须恰好有三列, - 并且既不是colV也不是 - colH的列被视为 - colD。 - + 每个列指定都可以是列号(从 1 开始)或列名。通常的 SQL 大小写折叠和加引号规则适用于列名。如果省略,colV取第 1 列,colH取第 2 列。colH必须不同于colV。如果未指定colD,查询结果必须恰好有三列,既不是colV也不是colH的那一列被用作colD。 + - 垂直标题显示为最左侧的列,包含在列colV中找到的值, - 与查询结果中的顺序相同,但删除了重复项。 - + 纵向表头显示为最左列,包含colV列中的值,其顺序与查询结果中相同,但会移除重复值。 + - 水平标题作为第一行显示,包含在列colH中找到的值,去除重复项。 - 默认情况下,这些值按照查询结果中的顺序显示。但是,如果给定可选的sortcolH参数, - 它标识一个列,其值必须是整数,colH中的值将按照相应的 - sortcolH值排序后显示在水平标题中。 - + 横向表头显示为第一行,包含colH列中的值,并移除重复值。默认情况下,它们按查询结果中的相同顺序显示。但如果给出了可选的sortcolH参数,它所标识的列的值必须是整数,而colH中的值会按照对应的sortcolH值排序后显示在横向表头中。 + - 在交叉表格中,对于每个colH列的非重复值x, - 和每个colV列的非重复值y, - 位于交点(x,y)的单元格包含查询结果行中colD列的值, - 其中colH列的值为x, - colV列的值为y。 - 如果没有这样的行,则单元格为空。如果有多个这样的行,则报告错误。 - + 在交叉表网格中,对于colH中的每个不同值xcolV中的每个不同值y,交点(x,y)处的单元格包含查询结果中colD列的值,该结果行的colH值为xcolV值为y。如果没有这样的行,单元格为空。如果存在多条这样的行,则报错。 + @@ -897,11 +872,7 @@ SELECT $1 \parse stmt1 - 命令形式\d+与前者相同,只是会显示更多信息:显示与表列相关的任何注释, - 表中的OID的存在,如果关系是视图,则显示视图定义,非默认的 - 复制标识设置以及 - 如果关系具有访问方法,则显示 - 访问方法名称。 + 命令形式\d+与前者相同,但会显示更多信息:表列关联的注释、表是否包含 OID、当关系为视图时的视图定义、非默认的复制标识设置,以及当关系具有访问方法时的访问方法名称。 @@ -1048,7 +1019,7 @@ SELECT $1 \parse stmt1 显示constraintoperator classoperator familyrule和 - trigger类型对象的描述。所有其他注释可以通过相应的反斜杠命令查看这些对象类型。 + trigger类型对象的描述。其他注释可通过对应对象类型的反斜线命令查看。 \dd 显示与 @@ -1162,7 +1133,7 @@ SELECT $1 \parse stmt1 列出函数,以及它们的结果数据类型、参数数据类型和函数类型,函数类型分为 agg(聚合)、normalproceduretriggerwindow。要只显示特定类型的函数,请在命令后添加相应的字母 anptw。如果指定了 pattern,则只显示名称与模式匹配的函数。任何附加参数都是类型名模式,分别与函数第一、第二等参数的类型名匹配。(匹配到的函数可以比你指定的参数更多;若要防止这种情况,可将破折号 - 写成最后一个 arg_pattern。)默认情况下,只显示用户创建的对象;提供模式或 S + class="parameter">pattern,则只显示名称与模式匹配的函数。任何附加参数都是类型名模式,分别与函数第一、第二等参数的类型名匹配。(匹配到的函数可以比你指定的参数更多;若要防止这种情况,可将连字符 - 写成最后一个 arg_pattern。)默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个函数的附加信息,包括易变性、并行安全性、所有者、安全分类、是否防漏、访问权限、语言、内部名称(仅适用于 C 和 internal 函数)以及描述。特定函数的源代码可通过 \sf 查看。 @@ -1173,7 +1144,7 @@ SELECT $1 \parse stmt1 \dF[x+] [ pattern ] - 列出文本搜索配置。如果指定了 pattern,则只显示名称与模式匹配的配置。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个配置的完整描述,包括底层文本搜索解析器以及每种记号类型对应的词典列表。 + 列出全文检索配置。如果指定了 pattern,则只显示名称与模式匹配的配置。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个配置的完整描述,包括底层全文检索解析器以及每种解析器词元类型对应的词典列表。 @@ -1182,7 +1153,7 @@ SELECT $1 \parse stmt1 \dFd[x+] [ pattern ] - 列出文本搜索词典。如果指定了 pattern,则只显示名称与模式匹配的词典。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个所选词典的附加信息,包括底层文本搜索模板和选项值。 + 列出全文检索词典。如果指定了 pattern,则只显示名称与模式匹配的词典。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个所选词典的附加信息,包括底层全文检索模板和选项值。 @@ -1191,7 +1162,7 @@ SELECT $1 \parse stmt1 \dFp[x+] [ pattern ] - 列出文本搜索解析器。如果指定了 pattern,则只显示名称与模式匹配的解析器。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个解析器的完整描述,包括底层函数和已识别的记号类型列表。 + 列出全文检索解析器。如果指定了 pattern,则只显示名称与模式匹配的解析器。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个解析器的完整描述,包括底层函数和可识别的词元类型列表。 @@ -1200,7 +1171,7 @@ SELECT $1 \parse stmt1 \dFt[x+] [ pattern ] - 列出文本搜索模板。如果指定了 pattern,则只显示名称与模式匹配的模板。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个模板的附加信息,包括底层函数名。 + 列出全文检索模板。如果指定了 pattern,则只显示名称与模式匹配的模板。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个模板的附加信息,包括底层函数名。 @@ -1210,7 +1181,7 @@ SELECT $1 \parse stmt1 \dg[Sx+] [ pattern ] - 列出数据库角色。(由于 usersgroups 的概念已经统一为 roles,此命令现在等同于 + 列出数据库角色。(由于 用户的概念已经统一为角色,此命令现在等同于 \du。)默认情况下,只显示用户创建的角色;提供 S 修饰符可包括系统角色。如果指定了 pattern,则只列出名称与模式匹配的角色。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个角色的附加信息;目前这会增加每个角色的注释。 @@ -1315,9 +1286,7 @@ SELECT $1 \parse stmt1 \drds[x] [ role-pattern [ database-pattern ] ] - 列出已定义的配置设置。这些设置可以是特定于角色、特定于数据库,或者两者兼有。role-pattern 和 - database-pattern 分别用于选择要列出的特定角色和数据库。如果省略,或者指定了 - *,则会列出所有设置,包括那些未指定角色或数据库的设置。如果在命令名后追加 x,结果会以扩展模式显示。 + 列出已定义的配置设置。这些设置可以特定于角色、特定于数据库,或同时特定于两者。role-patterndatabase-pattern分别用于选择要列出的角色和数据库。省略某个模式参数或将其指定为*时,不会按该参数筛选,还会分别包含不特定于角色或不特定于数据库的设置。如果在命令名后追加x,结果会以扩展模式显示。 @@ -1339,7 +1308,7 @@ SELECT $1 \parse stmt1 默认情况下,只显示授予用户创建角色的成员身份;提供 - S 修饰符可包括系统角色。如果指定了 pattern,则只列出名称与模式匹配的角色。如果在命令名后追加 x,结果会以扩展模式显示。 + S 修饰符可包括系统角色。如果指定了 pattern,则只列出授予名称与模式匹配的角色的成员身份。如果在命令名后追加 x,结果会以扩展模式显示。 @@ -1367,7 +1336,7 @@ SELECT $1 \parse stmt1 \dT[Sx+] [ pattern ] - 列出数据类型。如果指定了 pattern,则只列出名称与模式匹配的类型。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则每个类型都会连同其内部名称和大小一起列出;对于 enum 类型,还会显示其允许值以及相关权限。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 + 列出数据类型。如果指定了 pattern,则只列出名称与模式匹配的类型。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则每个类型都会连同其内部名称、大小和相关权限一起列出;对于 enum 类型,还会显示其允许值。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 @@ -1376,7 +1345,7 @@ SELECT $1 \parse stmt1 \du[Sx+] [ pattern ] - 列出数据库角色。(由于 usersgroups 的概念已经统一为 roles,此命令现在等同于 + 列出数据库角色。(由于 用户的概念已经统一为角色,此命令现在等同于 \dg。)默认情况下,只显示用户创建的角色;提供 S 修饰符可包括系统角色。如果指定了 pattern,则只列出名称与模式匹配的角色。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个角色的附加信息;目前这会增加每个角色的注释。 @@ -1417,7 +1386,7 @@ SELECT $1 \parse stmt1 - \e\edit filename 行号 + \e\edit filename line_number @@ -1429,7 +1398,7 @@ SELECT $1 \parse stmt1 如果编辑文件或上一个查询后在未修改文件的情况下退出编辑器,则查询缓冲区将被清除。 否则,查询缓冲区的新内容将根据psql的正常规则重新解析, - 将整个缓冲区视为单行。任何完整的查询将立即执行;也就是说,如果查询缓冲区包含或以分号结尾, + 将整个缓冲区视为单行。任何完整的查询将立即执行;也就是说,如果查询缓冲区包含分号或以分号结尾, 则执行并从查询缓冲区中删除到该点的所有内容。查询缓冲区中剩余的内容将重新显示。 输入分号或\g发送它,或输入\r通过清除查询缓冲区来取消。 @@ -1441,7 +1410,7 @@ SELECT $1 \parse stmt1 如果指定了行号,psql将光标定位在文件或查询缓冲区的指定行上。 - 请注意,如果给出一个全是数字的参数, + 请注意,如果只给出一个全是数字的参数, psql会假定它是一个行号,而不是文件名。 @@ -1456,14 +1425,10 @@ SELECT $1 \parse stmt1 \echo text [ ... ] - - 将求值后的参数打印到标准输出,用空格分隔,并在末尾加上换行符。这对于在脚本输出中穿插信息很有用。例如: - + 将求值后的参数打印到标准输出,用空格分隔,并在末尾加上换行符。这对于在脚本输出中穿插信息很有用。例如: => \echo `date` Tue Oct 26 21:40:57 CEST 1999 - - 如果第一个参数是未引用的-n,则不会写入尾随的换行符(也不会写入第一个参数)。 - +如果第一个参数是未加引号的-n,则不会写入尾随的换行符(也不会写入第一个参数)。 @@ -1571,7 +1536,7 @@ Tue Oct 26 21:40:57 CEST 1999 - 设置未对齐查询输出的字段分隔符。默认值是竖线(|)。 + 设置非对齐查询输出的字段分隔符。默认值是竖线(|)。 它等同于\pset fieldsep @@ -1582,25 +1547,17 @@ Tue Oct 26 21:40:57 CEST 1999 \g [ (option=value [...]) ] [ filename ] \g [ (option=value [...]) ] [ |command ] - - 将当前查询缓冲区发送到服务器以执行。 - - - 如果在\g后面出现括号,则括号中包围着一个空格分隔的option=value格式选项子句的列表,这些选项子句的解释方式与\psetoptionvalue命令相同,但仅在此查询的持续时间内生效。在此列表中,不允许在=符号周围有空格,但在选项子句之间需要空格。 - 如果省略了=value,则命名的option将以与\psetoption没有显式value时相同的方式更改。 - - - 如果提供了一个filename|command参数, - 查询的输出将被写入到指定的文件或通过给定的shell命令进行传输,而不是像通常那样显示出来。只有在查询成功返回零个或多个元组时,文件或命令才会被写入,而不是在查询失败或是非数据返回的SQL命令时。 + 将当前查询缓冲区发送给服务器执行。 + 如果在\g后面出现括号,则括号中是用空格分隔的option=value格式选项子句列表。这些子句的解释方式与\pset + option + value命令相同,但仅在此查询执行期间生效。在此列表中,=符号周围不允许有空格,但选项子句之间必须有空格。如果=value被省略,则指定的option会按以下命令的方式更改:\pset option,其中不显式指定value + 如果给出了filename|command参数,查询输出就会写入指定文件,或通过管道传给指定的 shell 命令,而不是照常显示。只有当查询成功返回零个或多个元组时,才会向文件或命令写入;如果查询失败,或执行的是不返回数据的 SQL 命令,则不会写入。 如果当前查询缓冲区为空,则最近发送的查询将被重新执行。除此之外,没有任何参数的\g基本上等同于一个分号。 带有参数的\g提供了一个一次性替代\o命令的选择,并且还允许一次性调整通常由\pset设置的输出格式选项。 - - 当最后一个参数以|开头时,整行剩余部分被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分将被直接传递给shell。 - + 当最后一个参数以|开头时,该行剩余的全部内容都会被视为要执行的command,其中既不进行变量插值,也不进行反引号扩展。该行剩余部分会直接按字面传给 shell。 @@ -1609,14 +1566,9 @@ Tue Oct 26 21:40:57 CEST 1999 \gdesc - - 显示当前查询缓冲区结果的描述(即列名和数据类型)。 - 查询不会实际执行;但是,如果包含某种语法错误,该错误将以正常方式报告。 - + 显示当前查询缓冲区中查询结果的描述(即列名和数据类型)。查询并不会实际执行;不过,如果其中存在语法错误,会按通常的方式报告。 - - 如果当前查询缓冲区为空,则描述最近发送的查询。 - + 如果当前查询缓冲区为空,则改为描述最近发送的查询。 @@ -1671,37 +1623,23 @@ CREATE INDEX \gset [ prefix ] - - 将当前查询缓冲区发送到服务器,并将查询的输出存储到psql变量中 - (参见下面的)。 - 要执行的查询必须返回一行。该行的每一列都存储在一个单独的变量中,变量名与列名相同。例如: - + 将当前查询缓冲区发送给服务器,并将查询输出存入 psql 变量(参见下面的)。要执行的查询必须恰好返回一行。该行的每一列分别存入一个变量,变量名与列名相同。例如: => SELECT 'hello' AS var1, 10 AS var2 -> \gset => \echo :var1 :var2 hello 10 - - 如果指定了一个prefix, - 该字符串将被添加到查询的列名前,以创建要使用的变量名: - + 如果指定了prefix,则会将该字符串加到查询的列名前面,以构成要使用的变量名: => SELECT 'hello' AS var1, 10 AS var2 -> \gset result_ => \echo :result_var1 :result_var2 hello 10 - - 如果列的结果为NULL,则相应的变量将被取消设置,而不是被设置。 - - - 如果查询失败或者没有返回一行结果, - 则不会改变任何变量。 - - - 如果当前查询缓冲区为空,则重新执行最近发送的查询。 - + 如果某一列的结果为 NULL,则取消设置对应的变量,而不是设置它。 + 如果查询失败或没有恰好返回一行,则不会更改任何变量。 + 如果当前查询缓冲区为空,则改为重新执行最近发送的查询。 @@ -1724,7 +1662,7 @@ hello 10 给出指定SQL命令的语法帮助。如果未指定command, 则psql将列出所有可用语法帮助的命令。如果command是星号 - (*),则显示所有SQL命令的语法帮助。 + (*),则显示所有SQL命令的语法帮助。 @@ -1745,9 +1683,7 @@ hello 10 \H\html - 打开HTML查询输出格式。如果HTML格式已经打开, - 则切换回默认的对齐文本格式。此命令用于兼容性和便利性,但请参阅\pset - 有关设置其他输出选项。 + 打开HTML查询输出格式。如果HTML格式已经打开,则切换回默认的对齐文本格式。此命令是为兼容性和便利性而保留的;设置其他输出选项的方法见\pset @@ -1759,13 +1695,10 @@ hello 10 - 从文件filename中读取输入,并将其执行为 - 好像它是在键盘上键入的一样。 + 从文件filename中读取输入,并像在键盘上输入一样执行它。 - 如果filename- - (连字符),那么标准输入将被读取,直到EOF指示或\q元命令。 - 这可用于将交互式输入与文件输入交错使用。请注意,仅当在最外层级别处于活动状态时,Readline行为才会被使用。 + 如果filename-(连字符),则从标准输入读取,直到遇到 EOF 指示或\q元命令。这可用于将交互式输入与文件输入交错使用。请注意,只有在最外层启用了 Readline,此处才会使用 Readline 功能。 @@ -1785,42 +1718,26 @@ hello 10 这组命令实现了可嵌套的条件块。条件块必须以\if开始,并以\endif结束。 在两者之间可以有任意数量的\elif子句,后面可以选择性地跟着一个\else子句。 - 在形成条件块的命令之间通常会出现普通查询和其他类型的反斜杠命令。 + 在形成条件块的命令之间通常会出现普通查询和其他类型的反斜线命令。 - \if\elif命令读取它们的参数,并将其作为布尔表达式进行评估。 - 如果表达式为true,则处理将继续进行;否则,直到达到匹配的\elif、 - \else\endif为止,将跳过行。一旦\if或 - \elif测试成功,同一块中后续\elif命令的参数不会被评估,而是被视为false。 - 在\else之后的行只有在没有早期匹配的\if\elif成功时才会被处理。 + \if\elif命令读取其参数,并将其作为布尔表达式求值。如果表达式的值为true,则正常继续处理;否则,跳过后续行,直到遇到匹配的\elif\else\endif。一旦\if\elif测试成功,同一块中后续\elif命令的参数就不再求值,而是被视为假。只有前面所有匹配的\if\elif测试都未成功时,才会处理\else后面的行。 - expression参数 - 是\if\elif命令的参数, - 受变量插值和反引号扩展的影响,就像任何其他反斜杠命令参数一样。 - 之后,它被评估为一个开/关选项变量的值。因此,有效值是以下任何一个不 - 含糊的不区分大小写匹配之一: - true, false, 1, - 0, on, off, - yes, no。例如, - t, TtR - 都将被视为true。 + 与其他反斜线命令的参数一样,\if\elif命令的expression参数会经过变量插值和反引号扩展。随后,按开/关选项变量值的规则对结果求值。因此,有效值是以下值的不区分大小写且无歧义的匹配:truefalse10onoffyesno。例如,tTtR都会被视为true - 不正确评估为真或假的表达式将生成警告,并被视为假。 + 不能正确求值为真或假的表达式会产生警告,并被视为假。 - 被跳过的行会被正常解析以识别查询和反斜杠命令,但查询不会发送到服务器, - 而且除了条件命令(\if\elif, - \else\endif)之外的反斜杠命令会被忽略。 + 被跳过的行会被正常解析以识别查询和反斜线命令,但查询不会发送到服务器, + 而且除了条件命令(\if\elif、 + \else\endif)之外的反斜线命令会被忽略。 仅检查跳过行中条件命令的有效嵌套。跳过行中的变量引用不会被展开, 也不会执行反引号扩展。 - 所有给定条件块的反斜杠命令必须出现在同一个源文件中。如果在主输入文件或一个 - \include的文件上达到文件结束之前,所有本地 - \if块都没有关闭, - 那么psql将会引发错误。 + 同一个条件块的所有反斜线命令必须出现在同一个源文件中。如果主输入文件或通过\include引入的文件到达 EOF 时,仍有本地\if块未关闭,psql就会报错。 下面是一个示例: @@ -1854,17 +1771,13 @@ SELECT \ir\include_relative filename - - \ir命令类似于\i,但是解析相对文件名的方式不同。 - 在交互模式下执行时,这两个命令的行为是相同的。然而,在脚本中调用时, - \ir会将文件名解释为相对于脚本所在目录,而不是当前工作目录。 - + \ir命令与\i相似,但解析相对文件名的方式不同。在交互模式下执行时,这两个命令的行为相同。不过,在脚本中调用时,\ir会相对于脚本所在的目录来解释文件名,而不是相对于当前工作目录。 - \l[x+] or \list[x+] [ pattern ] + \l[x+]\list[x+] [ pattern ] 列出服务器中的数据库,并显示其名称、所有者、字符集编码和访问权限。如果指定了 pattern,则只列出名称与模式匹配的数据库。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则还会显示数据库大小、默认表空间和描述。当前用户对其拥有 CONNECT 权限的数据库可以显示大小信息;如果当前用户是超级用户或具有 pg_read_all_stats 角色的权限,也可以显示大小信息。 @@ -1881,7 +1794,7 @@ SELECT 从数据库中读取具有OIDloid的大对象,并将其写入filename。请注意,这与服务器函数 - lo_export略有不同,后者使用数据库服务器运行的用户权限, + lo_export略有不同,后者使用运行数据库服务器的用户的权限, 并在服务器的文件系统上操作。 @@ -1897,14 +1810,10 @@ SELECT \lo_import filename [ comment ] - - 将文件存储到一个PostgreSQL大对象中。可选地,它将给定的注释与对象关联起来。例如: - + 将文件存储到一个PostgreSQL大对象中。可选地,它将给定的注释与对象关联起来。例如: foo=> \lo_import '/home/peter/pictures/photo.xcf' 'a picture of me' lo_import 152801 - - 响应表明大对象收到了对象ID 152801,这个ID可以用来在将来访问新创建的大对象。为了可读性起见,建议始终将一个可读的注释与每个对象关联起来。OID和注释都可以用\lo_list命令查看。 - +响应表明大对象获得了对象 ID 152801,这个 ID 可以用来在将来访问新创建的大对象。为便于阅读,建议始终为每个对象关联一条便于人阅读的注释。查看 OID 和注释时,可以使用\lo_list命令。 请注意,此命令与服务器端的lo_import略有不同,因为它作为本地用户在本地文件系统上操作,而不是服务器的用户和文件系统。 @@ -1927,7 +1836,7 @@ lo_import 152801 - 从数据库中删除具有OIDloid的大对象。 + 从数据库中删除OIDloid的大对象。 @@ -1943,19 +1852,12 @@ lo_import 152801 \o\out [ filename ] \o\out [ |command ] - - 安排将未来的查询结果保存到文件filename, - 或将未来的结果传输到shell命令command。 - 如果未指定参数,则查询输出重置为标准输出。 - + 将后续查询结果保存到文件filename,或通过管道传给 shell 命令command。如果没有指定参数,查询输出将恢复为标准输出。 - - 如果参数以|开头,则整个剩余部分的行被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分的行会被直接传递给shell。 - + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 - 查询结果包括从数据库服务器获取的所有表、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 + 查询结果包括从数据库服务器获取的所有表格、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 @@ -2031,17 +1933,9 @@ SELECT $1 \parse stmt1 \pset [ option [ value ] ] - - 这个命令设置影响查询结果表输出的选项。 - option - 指示要设置哪个选项。根据所选选项,value的语义会有所不同。 - 对于某些选项,省略value会导致该选项被切换或取消设置,具体描述在特定选项下。 - 如果没有提到这样的行为,那么省略value只会显示当前设置。 - + 这个命令设置影响查询结果表输出的选项。option指定要设置哪个选项。value的含义取决于所选的选项。对于某些选项,省略value会切换或取消设置该选项,具体见各选项的说明。如果没有提及这类行为,那么省略value只会显示当前设置。 - - \pset不带任何参数时,显示所有打印选项的当前状态。 - + 不带任何参数的\pset会显示所有打印选项的当前状态。 可调整打印选项有: @@ -2049,12 +1943,7 @@ SELECT $1 \parse stmt1 border - - value必须是一个数字。一般来说,数字越高,表格的边框和线条就越多, - 但具体细节取决于特定格式。在HTML格式中,这将直接转换为border=...属性。 - 在大多数其他格式中,只有值0(无边框)、1(内部分隔线)和2(表框)有意义,值大于2将被视为border = 2。 - latexlatex-longtable格式还允许值为3,以在数据行之间添加分隔线。 - + value必须是数字。一般来说,数字越大,表格的边框和分隔线就越多,但细节取决于具体格式。在HTML格式中,它会直接转换为border=...属性。在大多数其他格式中,只有值 0(无边框)、1(内部分隔线)和 2(表格外框)有意义,大于 2 的值会与border = 2作相同处理。latexlatex-longtable格式还允许使用值 3,以在数据行之间添加分隔线。 @@ -2067,7 +1956,7 @@ SELECT $1 \parse stmt1 零(默认值)会导致目标宽度由环境变量COLUMNS控制,或者如果未设置 COLUMNS则由检测到的屏幕宽度控制。 另外,如果columns为零,则wrapped格式仅影响屏幕输出。 - 如果columns为非零,则文件和管道输出也会被包装到该宽度。 + 如果columns为非零,则文件和管道输出也会按该宽度折行。 @@ -2086,63 +1975,35 @@ SELECT $1 \parse stmt1 expanded(或x - - 如果指定了value,它必须是onoff, - 这将启用或禁用扩展模式,或者是auto。 - 如果省略了value,则命令在开启和关闭设置之间切换。 - 启用扩展模式时,查询结果以两列显示,左侧是列名,右侧是数据。 - 如果数据在正常的水平模式下无法完全显示在屏幕上,则此模式很有用。 - 在自动设置中,当查询输出具有多列且宽度超过屏幕时,将使用扩展模式;否则,将使用常规模式。 - 自动设置仅在对齐和换行格式中有效。在其他格式中,它始终表现为扩展模式已关闭。 - + 如果指定了value,它必须是onoff(分别启用或禁用扩展模式),或者是auto。如果省略value,该命令会在开启和关闭设置之间切换。启用扩展模式时,查询结果以两列显示,左侧为列名,右侧为数据。如果数据在通常的横向模式下无法适应屏幕,这种模式就很有用。在自动设置下,当查询输出包含多列且宽度超过屏幕时,会使用扩展模式;否则使用常规模式。自动设置只在对齐和折行格式中有效。在其他格式中,它的行为始终与关闭扩展模式相同。 fieldsep - - 指定在未对齐的输出格式中使用的字段分隔符。这样,可以创建例如制表符分隔的输出, - 其他程序可能更喜欢。要将制表符设置为字段分隔符,请键入 - \pset fieldsep '\t'。默认字段分隔符是 - '|'(一根竖线)。 - + 指定非对齐输出格式使用的字段分隔符。这样可以创建例如制表符分隔的输出,这可能更符合其他程序的需要。要将制表符设置为字段分隔符,请输入\pset fieldsep '\t'。默认字段分隔符是'|'(竖线)。 fieldsep_zero - - 将未对齐输出格式中使用的字段分隔符设置为零字节。 - + 将非对齐输出格式使用的字段分隔符设置为零字节。 footer - - 如果指定了value, - 它必须是onoff, - 这将启用或禁用表格页脚的显示 - ((n 行)计数)。 - 如果省略了value, - 命令将切换页脚的显示或隐藏。 - + 如果指定了value,它必须是onoff,分别启用或禁用表格页脚((n rows)计数)的显示。如果省略value,该命令会切换页脚显示的开关状态。 format - - 设置输出格式为alignedasciidoc、 - csvhtmllatex、 - latex-longtabletroff-ms、 - unalignedwrapped。 - 允许使用唯一缩写。 - + 设置输出格式为alignedasciidoccsvhtmllatexlatex-longtabletroff-msunalignedwrapped。允许使用唯一缩写。 aligned格式是标准的、适合人阅读且排版整齐的文本输出;这是默认格式。 @@ -2155,12 +2016,12 @@ SELECT $1 \parse stmt1 按逗号分隔的列值输出,并应用 RFC 4180 - 中描述的引用规则。 + 中描述的加引号规则。 此输出与服务器的CSV格式的 COPY命令兼容。 - 生成包含列名的标题行,除非 + 生成包含列名的表头行,除非 tuples_only参数设置为 - on。不打印标题和页脚。 + on。不打印表格标题和页脚。 每行以系统相关的行结束字符结束, 对于类Unix系统通常是单个换行符(\n), 对于Microsoft Windows则是回车和换行序列 @@ -2168,17 +2029,14 @@ SELECT $1 \parse stmt1 可以用\pset csv_fieldsep选择逗号以外的字段分隔字符。 - wrapped格式类似于aligned,但会将宽数据值跨行包装,以使输出适合目标列宽。 - 目标宽度由columns选项下描述的方式确定。请注意,psql不会尝试包装列标题; - 因此,如果列标题所需的总宽度超过目标宽度,则wrapped格式的行为与aligned相同。 - + wrapped格式与aligned相似,但会将较宽的数据值折成多行,使输出适应目标列宽。目标宽度的确定方式见columns选项的说明。请注意,psql不会尝试对列标题折行;因此,如果列标题所需的总宽度超过目标宽度,wrapped格式的行为就与aligned相同。 - asciidochtml, - latexlatex-longtable,和 + asciidochtml、 + latexlatex-longtabletroff-ms格式生成的表格旨在包含在使用相应标记语言的文档中。 它们不是完整的文档!这在HTML中可能不是必需的,但在 - LaTeX中,则必须有一个完整的文档包装器。 + LaTeX中,则必须有一个完整文档的外层结构。 latex格式使用LaTeXtabular 环境。 latex-longtable格式需要LaTeX @@ -2198,25 +2056,19 @@ SELECT $1 \parse stmt1 - ascii样式使用普通的ASCII字符。数据中的换行使用右边边缘的+符号显示。 - 当wrapped格式将数据从一行换到下一行而没有换行符时,在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 + ascii样式使用普通的ASCII字符。数据中的换行符以右边缘的+符号表示。当wrapped格式在没有换行符的位置把数据折到下一行时,会在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 - old-ascii样式使用普通的ASCII字符,使用在PostgreSQL 8.4及更早版本中使用的格式样式。 - 数据中的换行符使用:符号代替左侧列分隔符显示。 - 当数据从一行换行到下一行而没有换行符时,使用;符号代替左侧列分隔符。 + old-ascii样式使用普通的ASCII字符,采用PostgreSQL 8.4 及更早版本的格式样式。数据中的换行符以替代左侧列分隔符的:符号表示。当数据在没有换行符的位置折到下一行时,则用;符号替代左侧列分隔符。 - unicode样式使用Unicode绘图字符。数据中的换行使用右边距中的回车符号显示。 - 当数据从一行换行到下一行而没有换行符时,第一行的右边距显示省略号符号, - 接着在下一行的左边距再次显示省略号符号。 + unicode样式使用 Unicode 框线绘制字符。数据中的换行符以右边缘的回车符号表示。当数据在没有换行符的位置折到下一行时,会在第一行的右边缘显示省略号符号,并在下一行的左边缘再次显示。 - 当border设置大于零时,linestyle选项还确定了用哪些字符绘制边框线。 - 普通的ASCII字符在任何地方都有效,但在识别Unicode字符的显示器上看起来更好。 + 当border设置大于零时,linestyle选项还决定用哪些字符绘制边框线。普通的ASCII字符在任何环境中都可用,但在支持 Unicode 的显示设备上,Unicode 字符更美观。 @@ -2224,24 +2076,14 @@ SELECT $1 \parse stmt1 null - - 设置要打印在空值位置的字符串。默认情况下是不打印任何内容,这很容易被误解为空字符串。 - 例如,一个人可能更喜欢\pset null '(null)'。 - + 设置用于代替空值打印的字符串。默认不打印任何内容,这很容易被误认为空字符串。例如,你可能更喜欢使用\pset null '(null)' numericlocale - - 如果指定了value, - 它必须是onoff, - 这将启用或禁用显示一个特定于区域设置的字符, - 用于将小数点左侧的数字分组。如果省略了 - value, - 命令在常规和特定于区域设置的数字输出之间切换。 - + 如果指定了value,它必须是onoff,分别启用或禁用使用区域设置特定的字符来分隔小数点左侧的数字组。如果省略value,该命令会在常规数字输出和区域设置特定的数字输出之间切换。 @@ -2249,17 +2091,11 @@ SELECT $1 \parse stmt1 pager - 控制查询和psql帮助输出时使用分页程序的方式。 - 当pager选项为off时,不使用分页程序。 - 当pager选项为on时,在适当的情况下使用分页程序,即当输出到终端且不适合在屏幕上显示时。 - pager选项也可以设置为always,这会导致分页程序用于所有终端输出,无论是否适合在屏幕上显示。 - \pset pager 不带value时,会在开启和关闭分页器之间切换。 + 控制查询和psql帮助输出是否使用分页器程序。当pager选项为off时,不使用分页器程序。当pager选项为on时,会在适当时使用分页器,即输出目标为终端且内容无法在屏幕上完整显示时。pager选项也可以设为always,这样所有终端输出都会使用分页器,无论内容是否能在屏幕上完整显示。不带value\pset pager会切换分页器的使用状态。 - 如果环境变量PSQL_PAGERPAGER被设置, - 输出将被分页传输到指定的程序。否则,将使用一个平台相关的默认程序 - (例如more)。 + 如果设置了环境变量PSQL_PAGERPAGER,需要分页的输出会通过管道传给指定程序。否则,使用与平台有关的默认程序(如more)。 @@ -2274,94 +2110,64 @@ SELECT $1 \parse stmt1 pager_min_lines - - 如果pager_min_lines设置为大于页面高度的数字, - 则除非至少有这么多行的输出要显示,否则不会调用分页程序。默认设置为0。 - + 如果将pager_min_lines设置为大于页面高度的数字,那么只有待显示的输出至少达到这么多行时,才会调用分页器程序。默认设置为 0。 recordsep - - 指定在未对齐的输出格式中使用的记录(行)分隔符。默认为换行符。 - + 指定非对齐输出格式使用的记录(行)分隔符。默认为换行符。 recordsep_zero - - 设置未对齐输出格式中使用的记录分隔符为零字节。 - + 将非对齐输出格式使用的记录分隔符设置为零字节。 tableattr(或T - - 在HTML格式中,这指定要放置在table标签内的属性。 - 这可能是cellpaddingbgcolor等。 - 请注意,这里通常不需要指定border,因为它已经由\pset border处理。 - 如果没有给出value,则取消表格属性。 - - - 在latex-longtable格式中,这控制了包含左对齐数据类型的每列的比例宽度。 - 它被指定为一个以空格分隔的值列表,例如,'0.2 0.2 0.6'。 - 未指定输出列使用最后指定的值。 - + HTML格式中,这指定要放在table标签内的属性,例如cellpaddingbgcolor。请注意,你可能不需要在这里指定border,因为\pset border已经负责处理它。如果没有给出value,则取消设置表格属性。 + latex-longtable格式中,这控制每个包含左对齐数据类型的列的宽度比例。它以空白分隔的值列表指定,例如'0.2 0.2 0.6'。未指定的输出列使用最后指定的值。 - title(或者C + title(或C - - 设置后续打印的任何表的标题。这可以用来为输出提供说明性标签。 - 如果没有给出value,则标题将被取消设置。 - + 设置随后打印的所有表格的标题。这可以为输出提供描述性标签。如果没有给出value,则取消设置标题。 tuples_only(或t - - 如果指定了value,它必须是onoff, - 这将启用或禁用仅元组模式。如果省略了value, - 命令将在常规输出和仅元组输出之间切换。常规输出包括额外信息,如列标题、标题和各种页脚。 - 在仅元组模式下,只显示实际的表数据。 - + 如果指定了value,它必须是onoff,分别启用或禁用仅元组模式。如果省略value,该命令会在常规输出和仅元组输出之间切换。常规输出包含列标题、表格标题和各种页脚等附加信息。在仅元组模式下,只显示实际的表格数据。 unicode_border_linestyle - - 设置unicode线条样式的边框绘制样式为singledouble之一。 - + unicode线条样式的边框绘制样式设置为singledouble unicode_column_linestyle - - 设置unicode线条样式的列绘制样式为singledouble之一。 - + unicode线条样式的列分隔线绘制样式设置为singledouble unicode_header_linestyle - - 设置unicode线条样式的标题绘制样式为singledouble之一。 - + unicode线条样式的表头分隔线绘制样式设置为singledouble @@ -2369,35 +2175,33 @@ SELECT $1 \parse stmt1 xheader_width - 将扩展输出的标题最大宽度设置为以下之一: + 将扩展输出的表头最大宽度设置为以下之一: full(默认值)、 columnpage整数值 - full:扩展标题不截断,其宽度与最宽的输出行相同。 + full:扩展表头不截断,其宽度与最宽的输出行相同。 - column:将标题行截断为第一列的宽度。 + column:将表头行截断为第一列的宽度。 - page:将标题行截断为终端宽度。 + page:将表头行截断为终端宽度。 - 整数值:指定标题行的确切最大宽度。 + 整数值:指定表头行的确切最大宽度。 - - 这些不同格式的示例可以在下面的中看到。 - + 这些不同格式的外观示例可参见下面的 @@ -2414,10 +2218,7 @@ SELECT $1 \parse stmt1 \q\quit - - 退出psql程序。 - 在脚本文件中,只有该脚本的执行被终止。 - + 退出psql程序。在脚本文件中,只会终止该脚本的执行。 @@ -2426,7 +2227,7 @@ SELECT $1 \parse stmt1 \qecho text [ ... ] - 这个命令与\echo命令相同,只是输出将被写入查询输出通道,由\o设置。 + 这个命令与\echo相同,只是输出会写入由\o设置的查询输出通道。 @@ -2435,9 +2236,7 @@ SELECT $1 \parse stmt1 \r\reset - - 重置(清除)查询缓冲区。 - + 重置(清空)查询缓冲区。 @@ -2524,14 +2323,9 @@ testdb=> \setenv LESS -imx4F 定义将打印到当前查询输出通道,由\o设置。 - - 目标函数可以仅通过名称指定,也可以通过名称和参数指定,例如foo(integer, text)。 - 如果有多个同名函数,则必须给出参数类型。 - + 目标函数可以只用名称指定,也可以同时给出名称和参数,例如foo(integer, text)。如果存在多个同名函数,就必须给出参数类型。 - - 如果在命令名称后添加+,则输出的行将被编号,函数体的第一行将被标记为第1行。 - + 如果在命令名后附加+,输出行会带上行号,函数体的第一行编号为 1。 与大多数其他元命令不同,整个行的剩余部分始终被视为\sf的参数, @@ -2546,8 +2340,7 @@ testdb=> \setenv LESS -imx4F - 这个命令获取并显示指定视图的定义,以CREATE OR REPLACE VIEW命令的形式。 - 定义将打印到当前查询输出通道,由\o设置。 + 这个命令获取指定视图的定义,并以CREATE OR REPLACE VIEW命令的形式显示。定义会打印到由\o设置的当前查询输出通道。 @@ -2572,7 +2365,7 @@ testdb=> \setenv LESS -imx4F - 这组命令实现 SQL 语句的管道化。一个管道必须以 \startpipeline 开始,并以 \endpipeline 结束。其间可以出现任意数量的 \syncpipeline 命令,它会发送一条同步消息,但不会结束当前管道,并会刷新发送缓冲区。在管道模式下,语句会被发送到服务器,而不等待前面语句的结果。更多细节见 。 + 这组命令实现 SQL 语句的管道化。一个管道必须以 \startpipeline 开始,并以 \endpipeline 结束。其间可以出现任意数量的 \syncpipeline 命令,它会发送一条同步消息,而不会结束当前管道,也不会刷新发送缓冲区。在管道模式下,语句会被发送到服务器,而不等待前面语句的结果。更多细节见 @@ -2621,10 +2414,7 @@ SELECT 1 \bind \sendpipeline \t - - 切换显示输出列名标题和行数页脚。此命令等效于\pset tuples_only, - 仅为方便起见提供。 - + 切换输出中的列名标题和行数页脚的显示状态。这个命令等价于\pset tuples_only,提供它是为了使用方便。 @@ -2632,10 +2422,7 @@ SELECT 1 \bind \sendpipeline \T table_options - - 指定在table标签中放置的属性,在HTML输出格式中。 - 该命令等效于\pset tableattr table_options。 - + 指定在HTML输出格式中放在table标签内的属性。这个命令等价于\pset tableattr table_options @@ -2643,10 +2430,7 @@ SELECT 1 \bind \sendpipeline \timing [ on | off ] - - 使用参数,打开或关闭显示每个SQL语句执行时间的功能。没有参数时,切换显示开关。 - 显示的时间单位为毫秒;超过1秒的时间间隔也以分钟:秒的格式显示,如有必要还会显示小时和天。 - + 带参数时,开启或关闭每条 SQL 语句执行耗时的显示。不带参数时,切换显示的开关状态。耗时以毫秒显示;超过 1 秒的时间间隔还会以分钟:秒的格式显示,必要时添加小时和天字段。 @@ -2673,15 +2457,9 @@ SELECT 1 \bind \sendpipeline \unset name - - 取消设置(删除)psql变量name。 - + 取消设置(删除)psql变量name - - 大多数控制psql行为的变量不能被取消设置;相反,\unset命令被解释为将它们设置为默认值。 - 请参见下面的。 - + 大多数控制psql行为的变量不能取消设置;对于这些变量,\unset命令会被解释为将其设置为默认值。参见下面的 @@ -2690,15 +2468,9 @@ SELECT 1 \bind \sendpipeline \w\write filename \w\write |command - - 将当前查询缓冲区写入文件filename,或者通过管道传给 shell 命令command。 - 如果当前查询缓冲区为空,则写入最近执行的查询。 - + 将当前查询缓冲区写入文件filename,或通过管道传递给 shell 命令command。如果当前查询缓冲区为空,则改为写入最近执行的查询。 - - 如果参数以|开头,则整个剩余部分的行被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分的行会被直接传递给shell。 - + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 @@ -2732,9 +2504,7 @@ SELECT 1 \bind \sendpipeline \x [ on | off | auto ] - - 设置或切换扩展表格格式模式。因此,它等同于\pset expanded。 - + 设置或切换扩展表格格式模式。它等价于\pset expanded @@ -2757,13 +2527,11 @@ SELECT 1 \bind \sendpipeline \! [ command ] - 不带参数时,转义到一个子shell;psql在子shell退出时恢复。 - 带参数时,执行shell命令command。 + 不带参数时,进入一个子 shell;子 shell 退出后,psql恢复运行。带参数时,执行 shell 命令command - 与大多数其他元命令不同,整个行的剩余部分始终被视为\!的参数, - 在参数中不执行变量插值或反引号扩展。行的其余部分被直接传递给shell。 + 与大多数其他元命令不同,该行剩余的全部内容始终被视为\!的参数,其中不会进行变量插值或反引号扩展。该行剩余内容会原样传给 shell。 @@ -2775,7 +2543,7 @@ SELECT 1 \bind \sendpipeline 显示帮助信息。可选的topic参数 (默认为commands)选择要解释的psql的哪个部分: - commands描述psql的反斜杠命令; + commands描述psql的反斜线命令; options描述可以传递给psql的命令行选项; 而variables显示关于psql配置变量的帮助。 @@ -2787,7 +2555,7 @@ SELECT 1 \bind \sendpipeline \; - 反斜杠分号不像前面的命令那样是一个元命令;相反,它只是在不进行进一步处理的情况下将一个分号添加到查询缓冲区中。 + 反斜线分号不像前面的命令那样是一个元命令;相反,它只是在不进行进一步处理的情况下将一个分号添加到查询缓冲区中。 @@ -2799,8 +2567,8 @@ select 1; select 2; select 3; select 1\; select 2\; select 3; - 在到达非反斜杠分号时将三个SQL命令发送到服务器的单个请求中。 - 服务器将执行此类请求作为单个事务,除非字符串中包含明确的BEGIN/COMMIT命令将其分成多个事务。(有关服务器如何处理多查询字符串的更多详细信息,请参见。) + 会在遇到前面没有反斜线的分号时,将这三个 SQL 命令作为单个请求发送到服务器。 + 服务器会将此类请求作为单个事务执行,除非字符串中包含显式的BEGIN/COMMIT命令将其分成多个事务。(有关服务器如何处理多查询字符串的更多详细信息,请参见。) @@ -2808,16 +2576,16 @@ select 1\; select 2\; select 3; - + 模式 - patterns + 模式 在 psql 和 pg_dump 中 - 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要把它写成两个相邻的双引号,这同样是符合 SQL 引用标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你不能只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 + 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要在双引号包围的文本内把它写成两个相邻的双引号,这同样是符合 SQL 加引号标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你可以只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 @@ -2829,21 +2597,15 @@ select 1\; select 2\; select 3; - 包含点(.)的关系模式被解释为模式名称后跟对象名称模式。例如, - \dt foo*.*bar*显示所有位于模式名以foo开头的模式中、且表名包含bar的表。当没有出现点时,模式仅匹配当前模式搜索路径中可见的对象。 - 再次,双引号内的点失去其特殊含义,被视为字面匹配。包含两个点(.)的关系模式 - 被解释为数据库名称后跟模式名称后跟对象名称模式。数据库名称部分不会被视为模式,必须匹配当前连接的数据库名称, - 否则将引发错误。 + 如果用于匹配关系名的模式包含一个点(.),则会被解释为模式名的匹配模式,后接对象名的匹配模式。例如,\dt foo*.*bar*会显示所有位于模式名以foo开头的模式中、且表名包含bar的表。如果没有点,则只匹配当前模式搜索路径中可见的对象。同样,双引号内的点会失去特殊含义,按字面匹配。如果用于匹配关系名的模式包含两个点(.),则会被解释为数据库名、模式名的匹配模式和对象名的匹配模式。数据库名部分不会被当作匹配模式,必须与当前连接的数据库名相同,否则会报错。 - 包含一个点(.)的模式被解释为数据库名称后跟模式的模式名称。例如, - \dn mydb.*foo*显示所有包含foo的模式。数据库名称部分不会被视为模式, - 必须匹配当前连接数据库的名称,否则将引发错误。 + 如果用于匹配模式名的模式包含一个点(.),则会被解释为数据库名,后接模式名的匹配模式。例如,\dn mydb.*foo*会显示名称中包含foo的所有模式。数据库名部分不会被当作匹配模式,必须与当前连接的数据库名相同,否则会报错。 - 高级用户可以使用字符类等正则表达式记法,如[0-9]可以匹配任意数字。所有的正则表达式特殊字符都按照所说的工作,以下字符除外:.会按照上面所说的作为一种分隔符,*会被翻译成正则表达式记号.*?会被翻译成.,而$则按字面意思匹配。根据需要,可以通过书写?(R+|)(R|)R?来分别模拟模式字符.R*R?$不需要作为一个正则表达式字符,因为模式必须匹配整个名称,而不是像正则表达式的常规用法那样解释(换句话说,$会被自动地追加到模式上)。如果不希望该模式的匹配位置被固定,可以在开头或者结尾写上*。注意在双引号内,所有的正则表达式特殊字符会失去其特殊含义并且按照其字面意思进行匹配。还有,在操作符名称模式中(即作为\do的参数),正则表达式特殊字符也按照字面意思进行匹配。 + 高级用户可以使用字符类等正则表达式记法,如[0-9]可以匹配任意数字。所有的正则表达式特殊字符都按照所说的工作,以下字符除外:.会按照上面所说的作为一种分隔符,*会被翻译成正则表达式记号.*?会被翻译成.,而$则按字面意思匹配。根据需要,可以用?模拟.,用(R+|)模拟R*,或用(R|)模拟R?$不需要作为一个正则表达式字符,因为模式必须匹配整个名称,而不是像正则表达式的常规用法那样解释(换句话说,$会被自动地追加到模式上)。如果不希望该模式的匹配位置被固定,可以在开头或者结尾写上*。注意在双引号内,所有的正则表达式特殊字符会失去其特殊含义并且按照其字面意思进行匹配。还有,在操作符名称模式中(即作为\do的参数),正则表达式特殊字符也按照字面意思进行匹配。 @@ -2851,7 +2613,7 @@ select 1\; select 2\; select 3; 高级特性 - + 变量 @@ -2872,7 +2634,7 @@ bar - 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要重置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 + 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要取消设置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 @@ -2886,7 +2648,7 @@ bar - 控制psql行为的变量通常不能被重置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse。 + 控制psql行为的变量通常不能被取消设置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse @@ -2904,7 +2666,7 @@ bar - 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被重置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交打开模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身即不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 + 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被取消设置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交关闭模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身既不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 @@ -2934,7 +2696,7 @@ bar DBNAME - 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -2943,7 +2705,7 @@ bar ECHO - 如果被设置为all,所有非空输入行会被按照读入它们的样子打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被重置或者设置为none(默认值)则不会显示任何查询。 + 如果被设置为all,所有非空输入行会在读入时打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被设置为none(默认值)则不会显示任何查询。 @@ -2961,7 +2723,7 @@ bar ENCODING - 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者重置。 + 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者取消设置。 @@ -2979,12 +2741,12 @@ bar FETCH_COUNT - 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每一组就会包括这么多个行。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 + 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每组包含的行数等于该整数值。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 - 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT个行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 + 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 @@ -3013,7 +2775,7 @@ bar HISTCONTROL - 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则匹配之前的历史行的行不会被放入。值ignoreboth组合了上述两种值。如果被重置或者被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 + 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则与上一条历史记录相同的行不会被放入。值ignoreboth组合了上述两种值。如果被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 @@ -3027,7 +2789,7 @@ bar HISTFILE - 该文件名将被用于存储历史列表。如果被重设,文件名将从PSQL_HISTORY环境变量中取得。如果该环境变量也没有被设置,则默认值是~/.psql_history,在Windows上是%APPDATA%\postgresql\psql_history。例如, + 该文件名将被用于存储历史列表。如果未设置该变量,文件名将从PSQL_HISTORY环境变量中取得。如果该环境变量也没有被设置,则默认值是~/.psql_history,在Windows上是%APPDATA%\postgresql\psql_history。例如, \set HISTFILE ~/.psql_history-:DBNAME @@ -3059,7 +2821,7 @@ bar HOST - 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -3068,7 +2830,7 @@ bar IGNOREEOF - 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须键入多个连续的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 + 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须连续键入与该数值相等数量的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 @@ -3082,8 +2844,8 @@ bar LASTOID - 最后被影响的 OID 的值,这可能会由INSERT或者\lo_import命令返回。这个变量只保证在下一个SQL命令被显示完之前有效。 - PostgreSQL 服务器从12版开始不再支持 OID 系统列,因此,在面向此类服务器时,跟随在INSERT后面的 LASTOID 将始终为0。 + 最后被影响的 OID 的值,这可能会由INSERT或者\lo_import命令返回。这个变量仅保证在下一个SQL命令的结果显示完之前有效。 + PostgreSQL 服务器从12版开始不再支持 OID 系统列,因此,在面向此类服务器时,执行INSERT后的 LASTOID 将始终为0。 @@ -3108,7 +2870,7 @@ bar - 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被重置或者设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 + 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 @@ -3126,7 +2888,7 @@ bar PIPELINE_COMMAND_COUNT - 正在运行的管道中排队的命令数 。 + 正在运行的管道中排队的命令数。 @@ -3146,7 +2908,7 @@ bar PIPELINE_SYNC_COUNT - 正在运行的管道中排队的同步消息数量 。 + 正在运行的管道中排队的同步消息数量。 @@ -3155,7 +2917,7 @@ bar PORT - 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -3194,7 +2956,7 @@ bar SERVER_VERSION_NUM - 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者重设。 + 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者取消设置。 @@ -3214,7 +2976,7 @@ bar 如果最后一个 shell 命令失败,则为 true;如果成功,则为 false。这适用于通过 \!\g\o\w - 和 \copy 元命令调用的 shell 命令,也适用于反引号(`)展开。请注意,对于 \o,该变量会在下一个 \o 命令关闭输出管道时更新。 + 和 \copy 元命令调用的 shell 命令,也适用于反引号(`)扩展。请注意,对于 \o,该变量会在下一个 \o 命令关闭输出管道时更新。 另见 SHELL_EXIT_CODE @@ -3226,7 +2988,7 @@ bar 最后一个 shell 命令返回的退出状态。0–127 表示程序退出码,128–255 表示因信号而终止,-1 表示未能启动程序或未能取得其退出状态。这适用于通过 \!\g\o\w - 和 \copy 元命令调用的 shell 命令,也适用于反引号(`)展开。请注意,对于 \o,该变量会在下一个 \o 命令关闭输出管道时更新。 + 和 \copy 元命令调用的 shell 命令,也适用于反引号(`)扩展。请注意,对于 \o,该变量会在下一个 \o 命令关闭输出管道时更新。 另见 SHELL_ERROR @@ -3246,7 +3008,7 @@ bar SHOW_CONTEXT - 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT域。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 + 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT字段。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 当VERBOSITY被设置为tersesqlstate时,这个设置无效(另见\errverbose,它可以用来得到刚遇到的错误的详细信息)。 @@ -3265,7 +3027,7 @@ bar SINGLESTEP - 设置这个变量为on等效于命令选项。 + 设置这个变量为on等效于命令行选项 @@ -3283,7 +3045,7 @@ bar USER - 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -3292,7 +3054,7 @@ bar VERBOSITY - 这个变量可以被设置为值defaultverboseterse或者sqlstate来控制错误报告的详细程度(另见\errverbose,在想得到之前的错误的详细版本时使用)。 + 这个变量可以被设置为值defaultverboseterse或者sqlstate来控制错误报告的详细程度(另见\errverbose,在想得到刚遇到的错误的详细信息时使用)。 @@ -3303,7 +3065,7 @@ bar VERSION_NUM - 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或重设。 + 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或取消设置。 @@ -3321,11 +3083,11 @@ bar - - <acronym>SQL</acronym> 中插入变量 + + <acronym>SQL</acronym> 插值 - psql变量的一个关键特性是可以把它们替换(插入)到常规SQL语句中,也可以把它们作为元命令的参数。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。插入一个值而不加引号的语法是在变量名前面加上一个冒号(:)。例如, + psql变量的一个关键特性是可以把它们替换(插值)到常规SQL语句中,也可以把它们替换到元命令的参数中。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。不加引号地插值一个值的语法是在变量名前面加上一个冒号(:)。例如, testdb=> \set foo 'my_table' testdb=> SELECT * FROM :foo; @@ -3334,7 +3096,7 @@ testdb=> SELECT * FROM :foo; - 当一个值被用作 SQL 文本或者标识符时,最安全的是把它加上引用。要引用一个变量的值作为 SQL 文本,可以把变量名称放在单引号中并且在引号前面写一个冒号。要引用作为 SQL 标识符,则可以把变量名称放在双引号中并且在引号前面写一个冒号。这种结构可以正确地处理变量值中嵌入的引号和其他特殊字符。之前的示例用这种方法写会更安全: + 当一个值要用作 SQL 字面量或标识符时,最安全的做法是为它加上引号。要将变量值作为 SQL 字面量加引号,应写一个冒号,后面跟用单引号括起来的变量名。要将变量值作为 SQL 标识符加引号,则在冒号后面用双引号括起变量名。这些写法能正确处理变量值中嵌入的引号和其他特殊字符。前面的示例可用以下更安全的写法: testdb=> \set foo 'my_table' testdb=> SELECT * FROM :"foo"; @@ -3342,11 +3104,11 @@ testdb=> SELECT * FROM :"foo"; - 在被引用的SQL文本和标识符中将不会执行变量插入。因此,一个诸如':foo'的结构不会从一个变量的值产生一个被引用的文本(即便能够也会不安全,因为无法正确地处理嵌入在值中的引号)。 + 在加引号的SQL字面量和标识符内部,不会执行变量插值。因此,':foo'这样的写法不能根据变量值生成加引号的字面量(即使能够生效,也不安全,因为它无法正确处理变量值中嵌入的引号)。 - 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个被引用的字符串插入: + 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个加引号的字符串进行插值: testdb=> \set content `cat my_file.txt` testdb=> INSERT INTO my_table VALUES (:'content'); @@ -3355,7 +3117,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 因为冒号可以合法地出现在 SQL 命令中,一次明显的插入尝试(即:name:'name'或者:"name")不会被替换,除非所提及的变量就是当前被设置的。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 + 因为冒号可以合法地出现在 SQL 命令中,一次明显的插值尝试(即:name:'name'或者:"name")不会被替换,除非所指的变量当前已设置。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 @@ -3363,12 +3125,12 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 文本或者标识符的冒号引用语法是一种psql扩展。 + 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 字面量或者标识符的冒号加引号语法是一种psql扩展。 - + 提示符 @@ -3382,33 +3144,26 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %M - - 数据库服务器的完整主机名(带域名);如果连接通过 Unix 域套接字建立,则为 [local];如果 Unix 域套接字不在编译时默认位置,则为 [local:/dir/name]。 - + 数据库服务器的完整主机名(含域名);如果通过 Unix 域套接字连接,则为[local];如果 Unix 域套接字不在编译时指定的默认位置,则为[local:/dir/name] %m - - 数据库服务器的主机名,在第一个点处分截;如果连接通过 Unix 域套接字建立,则为 [local]。 - + 数据库服务器的主机名,在第一个点号处截断;如果通过 Unix 域套接字连接,则为[local] %> - 数据库服务器正在监听的端口号。 + 数据库服务器监听的端口号。 %n - - 数据库会话用户名。(由于 SET SESSION - AUTHORIZATION 命令的作用,该值在数据库会话期间可能会发生变化。) - + 数据库会话用户名。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) @@ -3431,11 +3186,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %# - - 如果会话用户是数据库超级用户,则输出 - #,否则输出 >。(由于 SET SESSION - AUTHORIZATION 命令的作用,该值的展开在数据库会话期间可能会发生变化。) - + 如果会话用户是数据库超级用户,则为#,否则为>。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) @@ -3461,7 +3212,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %R - 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 dollar-quoted 字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 + 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 美元引用字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 @@ -3488,7 +3239,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %digits - 带有所示八进制码的字符被替换。 + 替换为指定八进制代码对应的字符。 @@ -3590,14 +3341,14 @@ $endif - )命令行选项也可用于在单次运行psql时禁用 Readline。这会阻止制表补全、命令行历史的使用或记录,以及多行命令的编辑。当你需要复制粘贴包含 TAB 字符的文本时,它尤其有用。 + )命令行选项也可用于在单次运行psql时禁用 Readline。这会阻止TAB 补全、命令行历史的使用或记录,以及多行命令的编辑。当你需要复制粘贴包含 TAB 字符的文本时,它尤其有用。 - + 环境 @@ -3682,9 +3433,9 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 如果查询结果无法在屏幕上显示完整,它们将通过此命令进行传输。典型的值是moreless。 + 如果查询结果无法在屏幕上显示完整,它们会通过管道传给此命令。典型的值是moreless。 可以通过将PSQL_PAGERPAGER设置为空字符串,或通过调整\pset命令的与分页相关的选项来禁用分页器。 - 这些变量按照列出的顺序进行检查;首先设置的变量将被使用。 + 这些变量按照列出的顺序进行检查;使用按该顺序找到的第一个已设置的变量。 如果它们都没有设置,默认情况下在大多数平台上使用more,但在Cygwin上使用less @@ -3764,7 +3515,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' 在任何情况下,可以通过设置PSQLRC环境变量来覆盖此默认文件路径。 - 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加破折号和PostgreSQL的主要或次要版本标识符来使其与psql版本相关, + 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加连字符和PostgreSQL的大版本或小版本标识符来使其与psql版本相关, 例如~/.psqlrc-&majorversion;~/.psqlrc-&version;。 最具体版本匹配的文件将优先读取,而不是非特定版本的文件。 这些版本后缀是在确定文件路径后添加的,如上所述。 @@ -3792,14 +3543,14 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - psql最适合与相同或较旧主要版本的服务器配合使用。 - 如果服务器的版本比psql本身更新,反斜杠命令特别容易失败。 - 然而,\d系列的反斜杠命令应该可以在版本回溯到9.2的服务器上运行, + psql最适合与相同或较旧大版本的服务器配合使用。 + 如果服务器的版本比psql本身更新,反斜线命令特别容易失败。 + 然而,\d系列的反斜线命令应该可以在最低至 9.2 版本的服务器上运行, 但不一定适用于比psql本身更新的服务器。运行SQL命令和显示查询结果的一般功能 - 也应该可以在更新主要版本的服务器上运行,但不能保证在所有情况下都能实现。 + 也应该可以在更新大版本的服务器上运行,但不能保证在所有情况下都能实现。 - 如果你想用psql连接到多个具有不同主版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个主版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 + 如果你想用psql连接到多个具有不同大版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个大版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 @@ -3813,7 +3564,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空格。现在则要求一些空格。 + 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空白。现在则要求用空白分隔。 diff --git a/zh/18/release-18.sgml b/zh/18/release-18.sgml index a4f8985f..f63aa8fb 100644 --- a/zh/18/release-18.sgml +++ b/zh/18/release-18.sgml @@ -2013,7 +2013,7 @@ Branch: REL_14_STABLE [dda622edc] 2026-08-02 16:49:18 -0400 --> - 修复为文本搜索词典创建缓存条目的过程中发生内存不足后导致的崩溃 + 修复为文本检索词典创建缓存条目的过程中发生内存不足后导致的崩溃 (Tom Lane) § @@ -4767,7 +4767,7 @@ Branch: REL_14_STABLE [6cae0c2bd] 2026-04-22 11:09:21 -0400 损坏或恶意的词缀文件可能使服务器崩溃。 - 这不被视为安全问题,因为文本搜索配置文件被假定为可信, + 这不被视为安全问题,因为文本检索配置文件被假定为可信, 但仍然值得修复。 diff --git a/zh/18/rowtypes.sgml b/zh/18/rowtypes.sgml index 7782828c..47f3dccb 100644 --- a/zh/18/rowtypes.sgml +++ b/zh/18/rowtypes.sgml @@ -75,7 +75,7 @@ CREATE TABLE inventory_item ( - 构造组合值 + 构造复合值 复合类型 @@ -83,7 +83,7 @@ CREATE TABLE inventory_item ( - 要把组合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,组合常量的一般格式如下: + 要把复合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,复合常量的一般格式如下: '( val1 , val2 , ... )' @@ -103,11 +103,11 @@ CREATE TABLE inventory_item ( - (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。必要时可能需要显式指定类型。) + (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。可能需要显式指定类型,以指明应将该常量转换为哪种类型。) - ROW表达式语法也可以用于构造组合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: + ROW表达式语法也可以用于构造复合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: ROW('fuzzy dice', 42, 1.99) ROW('', 42, NULL) @@ -126,7 +126,7 @@ ROW('', 42, NULL) 访问复合类型 - 要访问组合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: + 要访问复合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: SELECT item.name FROM on_hand WHERE item.price > 9.99; @@ -148,7 +148,7 @@ SELECT (on_hand.item).name FROM on_hand WHERE (on_hand.item).price > 9.99; - 无论何时从组合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回组合值的函数结果中只选取一个字段,你需要这样写: + 无论何时从复合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回复合值的函数结果中只选取一个字段,你需要这样写: SELECT (my_func(...)).field FROM ... @@ -164,10 +164,10 @@ SELECT (my_func(...)).field FROM ... - 修改组合值 + 修改复合类型 - 下面是一些插入和更新组合列时正确语法的示例。先看插入或更新整个列值的情况: + 下面是一些插入和更新复合列时正确语法的示例。先看插入或更新整个列值的情况: INSERT INTO mytab (complex_col) VALUES((1.1,2.2)); @@ -179,7 +179,7 @@ UPDATE mytab SET complex_col = ROW(1.1,2.2) WHERE ...; - 我们也可以更新组合列中的单个子字段: + 我们也可以更新复合列中的单个子字段: UPDATE mytab SET complex_col.r = (complex_col).r + 1 WHERE ...; @@ -208,11 +208,11 @@ INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2); - 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的组合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: + 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的复合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: SELECT c FROM inventory_item c; - 这个查询会产生一个单独的组合值列,因此我们可能得到如下输出: + 这个查询会产生一个单独的复合值列,因此我们可能得到如下输出: c ------------------------ @@ -223,7 +223,7 @@ SELECT c FROM inventory_item c; - 普通的限定列名语法table_name.column_name可以理解为对该表当前行的组合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) + 普通的限定列名语法table_name.column_name可以理解为对该表当前行的复合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) @@ -256,19 +256,19 @@ SELECT (myfunc(x)).a, (myfunc(x)).b, (myfunc(x)).c FROM some_table; SELECT m.* FROM some_table, LATERAL myfunc(x) AS m; - 把该函数放在LATERAL FROM项中,可以防止它对每一行被调用多于一次。m.*仍会展开为m.a, m.b, m.c,但现在这些变量只是对该FROM项输出的引用。(这里的LATERAL关键字其实是可选的,不过我们把它写出来,是为了明确该函数会从some_table中取得x。) + 把该函数放在LATERAL FROM项中,可以避免它在每行上被调用多次。m.*仍会展开为m.a, m.b, m.c,但现在这些变量只是对该FROM项输出的引用。(这里的LATERAL关键字其实是可选的,不过我们把它写出来,是为了明确该函数会从some_table中取得x。) - 当composite_value.*出现在SELECT输出列表、INSERT/UPDATE/DELETE/MERGE中的RETURNING列表、VALUES子句或行构造器的顶层时,就会产生这种列展开行为。在所有其他上下文中(包括嵌套在上述结构之内时),给组合值附加.*不会改变其值,因为它表示所有列,因此结果仍然是同一个组合值。例如,如果somefunc()接受一个组合值参数,这些查询就是等价的: + 当composite_value.*出现在SELECT输出列表、INSERT/UPDATE/DELETE/MERGE中的RETURNING列表、VALUES子句或行构造器的顶层时,就会产生这种列展开行为。在所有其他上下文中(包括嵌套在上述结构之内时),给复合值附加.*不会改变其值,因为它表示所有列,因此结果仍然是同一个复合值。例如,如果somefunc()接受一个复合值参数,这些查询就是等价的: SELECT somefunc(c.*) FROM inventory_item c; SELECT somefunc(c) FROM inventory_item c; - 在这两种情况下,inventory_item的当前行都会作为单个组合值参数传递给该函数。尽管.*在这种场合并不起作用,使用它仍是一种良好风格,因为它能明确表明这里想要的是组合值。特别是,解析器会把c.*中的c视为表名或别名,而不是列名,因此不会产生歧义;而没有.*时,就不清楚c究竟表示表名还是列名,而且如果存在名为c的列,实际上会优先按列名解释。 + 在这两种情况下,inventory_item的当前行都会作为单个复合值参数传递给该函数。尽管.*在这种场合并不起作用,使用它仍是一种良好风格,因为它能明确表明这里想要的是复合值。特别是,解析器会把c.*中的c视为表名或别名,而不是列名,因此不会产生歧义;而没有.*时,就不清楚c究竟表示表名还是列名,而且如果存在名为c的列,实际上会优先按列名解释。 @@ -278,7 +278,7 @@ SELECT * FROM inventory_item c ORDER BY c; SELECT * FROM inventory_item c ORDER BY c.*; SELECT * FROM inventory_item c ORDER BY ROW(c.*); - 所有这些ORDER BY子句都指定了该行的组合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: + 所有这些ORDER BY子句都指定了该行的复合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: SELECT * FROM inventory_item c ORDER BY ROW(c.name, c.supplier_id, c.price); SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); @@ -287,7 +287,7 @@ SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); - 另一种与组合值有关的特殊语法行为是,我们可以使用函数记法来提取组合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: + 另一种与复合值有关的特殊语法行为是,我们可以使用函数记法来提取复合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: SELECT c.name FROM inventory_item c WHERE c.price > 1000; @@ -306,11 +306,11 @@ SELECT c.somefunc FROM inventory_item c; 函数记法与字段记法之间的这种等价性,使得我们可以通过在复合类型上使用函数来实现计算字段 - computed field + 计算字段 - field - computed + 字段 + 计算 使用上面最后一种查询形式的应用程序,无需直接知道somefunc并不是该表中的真实列。 @@ -328,7 +328,7 @@ SELECT c.somefunc FROM inventory_item c; 复合类型的输入和输出语法 - 组合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明组合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 + 复合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明复合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 '( 42)' @@ -336,7 +336,7 @@ SELECT c.somefunc FROM inventory_item c; - 如前所示,在写组合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让组合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的组合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作组合语法的数据字符。 + 如前所示,在写复合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让复合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的复合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作复合语法的数据字符。 @@ -350,18 +350,18 @@ SELECT c.somefunc FROM inventory_item c; - 记住,你在 SQL 命令中写的内容会先被解释为字符串字面量,然后才会被解释为组合值。这会使所需的反斜杠数量翻倍(假定使用的是转义字符串语法)。例如,要在组合值中插入一个包含双引号和反斜杠的text字段,需要写成: + 记住,你在 SQL 命令中写的内容会先被解释为字符串字面量,然后才会被解释为复合值。这会使所需的反斜杠数量翻倍(假定使用的是转义字符串语法)。例如,要在复合值中插入一个包含双引号和反斜杠的text字段,需要写成: INSERT ... VALUES ('("\"\\")'); - 字符串字面量处理器会去掉一层反斜杠,因此传到组合值解析器时看起来是("\"\\")。随后,送入text数据类型输入例程的字符串就变成了"\。(如果我们使用的数据类型的输入例程也会把反斜杠当作特殊字符处理,例如bytea,那么为了在存储的组合字段中得到一个反斜杠,命令里可能需要多达八个反斜杠。)美元引用(见)可用于避免反斜杠加倍的需要。 + 字符串字面量处理器会去掉一层反斜杠,因此传到复合值解析器时看起来是("\"\\")。随后,送入text数据类型输入例程的字符串就变成了"\。(如果我们使用的数据类型的输入例程也会把反斜杠当作特殊字符处理,例如bytea,那么为了在存储的复合字段中得到一个反斜杠,命令里可能需要多达八个反斜杠。)美元引用(见)可用于避免反斜杠加倍的需要。 - 在 SQL 命令中编写组合值时,ROW构造器语法通常比组合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是组合成员时完全相同。 + 在 SQL 命令中编写复合值时,ROW构造器语法通常比复合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是复合成员时完全相同。 diff --git a/zh/18/textsearch.sgml b/zh/18/textsearch.sgml index 17771cbf..a00dd8dc 100644 --- a/zh/18/textsearch.sgml +++ b/zh/18/textsearch.sgml @@ -1,21 +1,21 @@ - 全文搜索 + 全文检索 - 全文搜索 + 全文检索 - 文本搜索 + 文本检索 介绍 - 全文搜索(或简称文本搜索)提供了识别满足 + 全文检索(或简称文本检索)提供了识别满足 查询条件的自然语言文档的能力, 并且可按它们与查询的相关度进行排序。最常见的搜索类型,是找出所有包含给定 查询词的文档,并按它们与查询的相似性 @@ -25,7 +25,7 @@ - 文本搜索操作符在数据库中已经存在很多年了。 + 文本检索操作符在数据库中已经存在很多年了。 PostgreSQL为文本数据类型提供了 ~~*LIKEILIKE 操作符,但它们缺少现代信息系统所要求的许多关键特性: @@ -138,7 +138,7 @@ ()。围绕这两种数据类型还有许多函数和 操作符(),其中最重要的是匹配操作符 @@,我们将在中介绍。 - 全文搜索还可以借助索引加速()。 + 全文检索还可以借助索引加速()。 @@ -147,11 +147,11 @@ 文档 - 全文搜索 + 文本检索 - 文档是全文搜索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本搜索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 + 文档是全文检索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本检索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 @@ -179,7 +179,7 @@ WHERE m.mid = d.did AND m.mid = 12; - 为了进行文本搜索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 + 为了进行文本检索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 @@ -187,7 +187,7 @@ WHERE m.mid = d.did AND m.mid = 12; 基本文本匹配 - 在PostgreSQL中,全文搜索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: + 在PostgreSQL中,全文检索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: SELECT 'a fat cat sat on a mat and ate a fat rat'::tsvector @@ 'cat & rat'::tsquery; @@ -203,7 +203,7 @@ SELECT 'fat & cow'::tsquery @@ 'a fat cat sat on a mat and ate a fat rat'::t - 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索术语,这些术语必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个术语组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本搜索匹配更像是这样: + 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索词,这些搜索词必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个搜索词组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本检索匹配更像是这样: SELECT to_tsvector('fat cats ate fat rats') @@ to_tsquery('fat & rat'); @@ -221,7 +221,7 @@ SELECT 'fat cats ate fat rats'::tsvector @@ to_tsquery('fat & rat'); f - 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,默认假定已经正规化,因此 rats 不会匹配 rat。 + 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,被假定为已经正规化,因此 rats 不会匹配 rat @@ -290,49 +290,49 @@ SELECT phraseto_tsquery('the cats ate the rats'); 配置 - 前述的都是简单的文本搜索示例。正如前面所提到的,全文搜索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如基于空白之外的解析。这个功能由文本搜索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 + 前述的都是简单的文本检索示例。正如前面所提到的,全文检索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如不局限于按空白划分的解析。这个功能由文本检索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 - 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本搜索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config。 + 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本检索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config - 依赖一个配置的每一个文本搜索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当这个参数被忽略时,default_text_search_config才被使用。 + 依赖一个配置的每一个文本检索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当省略这个参数时,default_text_search_config才被使用。 - 为了让建立自定义文本搜索配置更容易,一个配置可以从更简单的数据库对象来建立。PostgreSQL的文本搜索功能提供了四类配置相关的数据库对象: + 为了便于构建自定义文本检索配置,配置由更简单的数据库对象组合而成。PostgreSQL 的文本检索功能提供了四类与配置相关的数据库对象: - 文本搜索解析器将文档拆分成词元并分类每个词元(例如,作为词或者数字)。 + 文本检索解析器将文档拆分成词元并对每个词元分类(例如,作为词或者数字)。 - 文本搜索词典将词元转变成正规化的形式并拒绝停用词。 + 文本检索词典将词元转变成正规化的形式并拒绝停用词。 - 文本搜索模板提供位于词典底层的函数(一个词典简单地指定一个模板和一组用于模板的参数)。 + 文本检索模板提供位于词典底层的函数(词典只需指定一个模板及其一组参数)。 - 文本搜索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 + 文本检索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 - 文本搜索解析器和模板是从低层 C 函数构建而来,因此它要求 C 编程能力来开发新的解析器和模板,并且还需要超级用户权限来把它们安装到一个数据库中(在PostgreSQL发布的contrib/区域中有一些附加的解析器和模板的示例)。由于词典和配置只是对底层解析器和模板的参数化和连接,不需要特殊的权限来创建一个新词典或配置。创建定制词典和配置的示例将在本章稍后的部分给出。 + 文本检索解析器和模板由底层 C 函数构成,因此开发新的解析器和模板需要 C 编程能力,将它们安装到数据库中则需要超级用户权限。(PostgreSQL 发行版的 contrib/ 目录中有附加解析器和模板的示例。)词典和配置只是为底层解析器和模板设置参数并将它们连接起来,因此创建新词典或配置不需要特殊权限。本章后面会给出创建自定义词典和配置的示例。 @@ -343,14 +343,14 @@ SELECT phraseto_tsquery('the cats ate the rats'); 表和索引 - 在前一节中的示例演示了使用简单常数字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 + 在前一节中的示例演示了使用简单常量字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 搜索表 - 即使没有索引,也可以执行全文搜索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend: + 即使没有索引,也可以执行全文检索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend SELECT title @@ -374,7 +374,7 @@ WHERE to_tsvector(body) @@ to_tsquery('friend'); - 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 中同时包含 createtable: + 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 合在一起包含 createtable SELECT title @@ -388,7 +388,7 @@ LIMIT 10; - 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本搜索在实际使用中通常都需要建立索引。 + 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本检索在实际使用中通常都需要建立索引。 @@ -397,13 +397,13 @@ LIMIT 10; 创建索引 - 我们可以创建一个GIN索引()来加速文本搜索: + 我们可以创建一个GIN索引()来加速文本检索: CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector('english', body)); - 注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本搜索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含使用不同文本搜索配置创建的tsvector,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 + 注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本检索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含使用不同文本检索配置创建的tsvector,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 @@ -420,10 +420,7 @@ CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector(config_name, body)); 这里 config_namepgweb 表中的一个列。这样就允许在同一个索引中混合使用不同配置,同时记录每个索引项使用的是哪一种配置。例如,如果文档集合中包含不同语言的文档,这就会很有用。同样,打算使用该索引的查询也必须写成对应的形式,例如 WHERE to_tsvector(config_name, body) @@ 'a & b' - - 索引甚至可以连接列: - - + 索引甚至可以串接多个列: CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector('english', title || ' ' || body)); @@ -443,7 +440,7 @@ ALTER TABLE pgweb CREATE INDEX textsearch_idx ON pgweb USING GIN(textsearchable_index_col); - 现在我们准备好执行一个快速的全文搜索了: + 现在我们准备好执行一个快速的全文检索了: SELECT title @@ -455,7 +452,7 @@ LIMIT 10; - 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本搜索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 + 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本检索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 @@ -463,10 +460,10 @@ LIMIT 10; - 控制文本搜索 + 控制文本检索 - 要实现全文搜索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 + 要实现全文检索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 @@ -485,7 +482,7 @@ to_tsvector( config - to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本搜索配置进行处理。下面是一个简单示例: + to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本检索配置进行处理。下面是一个简单示例: SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); @@ -500,7 +497,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每类词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本搜索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english。 + to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每个词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本检索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english @@ -508,7 +505,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为空,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: + 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为 NULL,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: UPDATE tt SET ti = @@ -659,12 +656,12 @@ websearch_to_tsquery( config - 无引号文本:不在引号中的文本会被转换为由&操作符分隔的词,就像经过plainto_tsquery处理一样。 + 未加引号的文本:不在引号中的文本会被转换为由&操作符分隔的词,就像经过plainto_tsquery处理一样。 - "引号文本":引号中的文本会被转换为由<->操作符分隔的词,就像经过phraseto_tsquery处理一样。 + "加引号的文本":引号中的文本会被转换为由<->操作符分隔的词,就像经过phraseto_tsquery处理一样。 @@ -722,7 +719,7 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); 搜索结果排名 - 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及它们出现于文档中哪个部分。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 + 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及这些词所处文档部分的重要程度。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 @@ -813,12 +810,12 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 8 用文档中唯一词的数量除排名 + 8 用文档中不同词的数量除排名 - 16 用 1 + 文档中唯一词数量的对数除排名 + 16 用 1 + 文档中不同词数量的对数除排名 @@ -832,7 +829,7 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。正规化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 + 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。归一化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 @@ -904,7 +901,7 @@ ts_headline( config ts_headline 接收文档和查询,并返回文档中一段 - 高亮查询词条的摘录。具体而言,该函数会先用查询选择相关文本片段,然后 + 高亮查询词的摘录。具体而言,该函数会先用查询选择相关文本片段,然后 高亮查询中出现的所有词,即使这些词的位置并不满足查询本身的位置限制。 用于解析文档的配置可通过 config 指定; 若省略 config,则使用 @@ -1011,7 +1008,7 @@ occurrences to display in the result.', 附加特性 - 本节介绍一些在文本搜索中很有用的附加函数和操作符。 + 本节介绍一些在文本检索中很有用的附加函数和操作符。 @@ -1124,7 +1121,7 @@ occurrences to display in the result.', - 返回用 AND 结合的两个给定查询。 + 返回两个给定查询的 AND 组合。 @@ -1138,7 +1135,7 @@ occurrences to display in the result.', - 返回用 OR 结合的两个给定查询。 + 返回两个给定查询的 OR 组合。 @@ -1191,7 +1188,7 @@ SELECT to_tsquery('fat') <-> to_tsquery('cat | rat'); - 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: + 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在其后距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: SELECT tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10); @@ -1245,10 +1242,7 @@ SELECT numnode('foo & bar'::tsquery); - - 返回可用于索引搜索的tsquery部分。这个函数可用于检测不可索引的查询,例如只包含停用词或只包含否定项的查询。例如: - - + 返回一个tsquery中可用于搜索索引的部分。此函数可用于检测无法使用索引的查询,例如只包含停用词或只包含否定词项的查询。例如: SELECT querytree(to_tsquery('defined')); querytree ----------- @@ -1424,7 +1418,7 @@ SELECT title, body FROM messages WHERE tsv @@ to_tsquery('title & body'); - 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本搜索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 + 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本检索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 @@ -1491,7 +1485,7 @@ ts_stat(sqlquery text, - 如果提供了 weights,则只统计具有这些权重之一的出现。 + 如果提供了 weights,则只统计具有这些权重之一的词的出现次数。 @@ -1520,7 +1514,7 @@ LIMIT 10; 解析器 - 文本搜索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 + 文本检索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 @@ -1543,12 +1537,12 @@ LIMIT 10; asciiword - 单词,所有 ASCII 字母 + 单词,全部由 ASCII 字母组成 elephant word - 单词,所有字母 + 单词,全部由字母组成 mañana @@ -1558,12 +1552,12 @@ LIMIT 10; asciihword - 带连字符的单词,所有 ASCII + 带连字符的单词,全部为 ASCII 字符 up-to-date hword - 带连字符的单词,所有字母 + 带连字符的单词,由字母组成 lógico-matemática @@ -1573,12 +1567,12 @@ LIMIT 10; hword_asciipart - 带连字符的单词部分,所有 ASCII + 带连字符的单词部分,全部为 ASCII 字符 postgresql-beta1 上下文中的 postgresql hword_part - 带连字符的单词部分,所有字母 + 带连字符的单词部分,全部由字母组成 lógico-matemática 上下文中的 lógicomatemática @@ -1653,8 +1647,8 @@ LIMIT 10; blank - 空格符号 - (其他不识别的任意空白或标点符号) + 空白符号 + (未被识别为其他类型的空白或标点符号) @@ -1662,12 +1656,12 @@ LIMIT 10; - 解析器的一个字母的概念由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时可以用来区别它们。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 + 解析器对字母的界定由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时区分它们会很有用。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 email不支持所有由RFC 5322定义的有效电子邮件字符。 - 具体来说,电子邮件用户名仅支持句号、短横线和下划线这些非字母数字字符。 + 具体来说,电子邮件用户名仅支持句点、短横线和下划线这些非字母数字字符。 @@ -1716,7 +1710,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h 词典 - 词典用于消除不应参与搜索的词(stop words),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 + 词典用于消除不应参与搜索的词(停用词),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 @@ -1731,7 +1725,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - URL地址可以被正规化,以便让等价的 URL 匹配: + URL 地址可以规范化,以便让等价的 URL 匹配: @@ -1776,32 +1770,32 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤字典) + 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤词典 - 如果字典知道该词元但它是一个停用词,则返回一个空数组 + 如果词典知道该词元但它是一个停用词,则返回一个空数组 - 如果字典不识别该输入词元,则返回NULL + 如果词典不识别该输入词元,则返回NULL - PostgreSQL为许多语言提供了预定义的字典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发布的contrib/区域。 + PostgreSQL为许多语言提供了预定义的词典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发行版的contrib/目录。 - 文本搜索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 + 文本检索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 - 配置词典列表的一般规则是,把最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语分类词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: + 配置词典列表的一般规则是,把适用范围最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语同义词词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: ALTER TEXT SEARCH CONFIGURATION astro_en @@ -1810,14 +1804,14 @@ ALTER TEXT SEARCH CONFIGURATION astro_en - 过滤词典可以放在列表中的任何位置,只是不能放在最后,因为放在最后就没有意义了。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 + 过滤词典可以放在列表中的任何位置,但放在末尾没有用处。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 停用词 - 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文搜索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: + 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文检索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: SELECT to_tsvector('english', 'in the list of stop words'); @@ -1949,7 +1943,7 @@ SELECT * FROM ts_debug('english', 'Paris'); - synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基本名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 + synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 @@ -2011,28 +2005,28 @@ mydb=# SELECT 'indexes are very useful'::tsvector @@ to_tsquery('tst', 'indices' - 基本上一个分类词典会用一个首选词替换所有非首选词,并且也可选择地保留原始术语用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典要求一个下列格式的配置文件: + 分类词典基本上会用一个首选词替换所有非首选词,并且也可以选择保留原始词用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典需要一个采用以下格式的配置文件: -# this is a comment -sample word(s) : indexed word(s) -more sample word(s) : more indexed word(s) +# 这是一条注释 +示例词(一个或多个) : 索引词(一个或多个) +更多示例词(一个或多个) : 更多索引词(一个或多个) ... - 其中冒号(:)符号扮演了一个短语及其替换之间的定界符。 + 其中冒号(:)符号用作短语及其替换词之间的分隔符。 - 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过对子词典的应用,但所有样例词都必须能被子词典识别。 + 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过将子词典应用于该词,但所有样例词都必须能被子词典识别。 - 如果有多个短语匹配输入,则分类词典选择最长的那一个,并且使用最后的定义打破连结。 + 如果有多个短语匹配输入,分类词典会选择最长的匹配;长度相同时使用最后的定义。 - 由子词典识别的特定停用词不能够被指定;改用?标记任何可以出现停用词的地方。例如,假定根据子词典athe是停用词: + 由子词典识别的特定停用词不能够被指定;改用?标记可出现任意停用词的位置。例如,假定根据子词典athe是停用词: ? one ? two : swsw @@ -2074,7 +2068,7 @@ CREATE TEXT SEARCH DICTIONARY thesaurus_simple ( - mythesaurus是分类词典配置文件的基础名称(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 + mythesaurus是分类词典配置文件的基名(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 @@ -2099,7 +2093,7 @@ ALTER TEXT SEARCH CONFIGURATION russian 分类词典示例 - 考虑简单的天文词库 thesaurus_astro,其中包含一些天文单词组合: + 考虑一个简单的天文分类词典 thesaurus_astro,其中包含一些天文单词组合: supernovae stars : sn @@ -2167,7 +2161,7 @@ SELECT plainto_tsquery('supernova star'); <application>Ispell</application> 词典 - Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以把搜索词 bank 的词尾变化和词形变化对应起来,例如 bankingbankedbanksbanks'bank's。 + Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以匹配搜索词 bank 的所有变格和变位形式,例如 bankingbankedbanksbanks'bank's @@ -2179,12 +2173,12 @@ SELECT plainto_tsquery('supernova star'); - 要创建一个Ispell词典,执行这三步: + 要创建一个Ispell词典,请执行以下步骤: - 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。有必要抽取.aff.dic文件,把扩展改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): + 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。需要提取.aff.dic文件,将扩展名改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): iconv -f ISO_8859-1 -t UTF-8 -o nn_no.affix nn_NO.aff iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic @@ -2193,7 +2187,7 @@ iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic - 拷贝文件到$SHAREDIR/tsearch_data目录 + 复制文件到$SHAREDIR/tsearch_data目录 @@ -2211,11 +2205,11 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( - 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基础名称。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 + 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基名。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 - Ispell 词典通常识别一个有限集合的词,这样它们后面应该跟着另一个更广义的词典;例如,一个 Snowball 词典,它可以识别所有东西。 + Ispell 词典通常只能识别有限的词,因此其后应跟着另一个覆盖范围更广的词典;例如,一个 Snowball 词典,它可以识别所有输入。 @@ -2223,13 +2217,13 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( prefixes flag *A: - . > RE # As in enter > reenter + . > RE # 例如 enter > reenter suffixes flag T: - E > ST # As in late > latest - [^AEIOU]Y > -Y,IEST # As in dirty > dirtiest - [AEIOU]Y > EST # As in gray > grayest - [^EY] > EST # As in small > smallest + E > ST # 例如 late > latest + [^AEIOU]Y > -Y,IEST # 例如 dirty > dirtiest + [AEIOU]Y > EST # 例如 gray > grayest + [^EY] > EST # 例如 small > smallest @@ -2245,14 +2239,14 @@ lark/MRS .dict文件的格式是: -basic_form/affix_class_name +基本词形/词缀类名 .affix文件中,每一个词缀标志以下面的格式描述: -condition > [-stripping_letters,] adding_affix +条件 > [-删除的字母,] 添加的词缀 @@ -2261,7 +2255,7 @@ condition > [-stripping_letters,] adding_affix - Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,它标记可以参与到复合格式中的词典词: + Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,用于标记词典中可以参与构成复合词的词: compoundwords controlled z @@ -2291,7 +2285,7 @@ SFX T 0 est [^ey] - 一个词缀类的第一行是头部。头部后面列出了词缀规则的域: + 一个词缀类的第一行是首部。首部后面列出了词缀规则的字段: @@ -2343,7 +2337,7 @@ largehearted <application>Snowball</application> 词典 - Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每一个算法懂得按照其语言中的拼写,如何缩减词的常见变体形式为一个基础或词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择地指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。例如,有一个内置的定义等效于 + Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每种算法都知道如何把其语言中词的常见变体约简为基本拼写形式,也就是词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。例如,有一个内置的定义等效于 CREATE TEXT SEARCH DICTIONARY english_stem ( @@ -2357,7 +2351,7 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( - 一个Snowball词典识别所有的东西,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 + 一个Snowball词典识别所有输入,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 @@ -2368,11 +2362,11 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( 配置示例 - 一个文本搜索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本搜索配置来执行其处理。配置参数指定了默认配置的名称,如果忽略了显式的配置参数,文本搜索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 + 一个文本检索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本检索配置来执行其处理。配置参数指定了默认配置的名称,如果省略了显式的配置参数,文本检索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 - 有一些预定义的文本搜索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本搜索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本搜索对象()的信息。 + 有一些预定义的文本检索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本检索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本检索对象()的信息。 @@ -2464,17 +2458,17 @@ SHOW default_text_search_config; - 测试和调试文本搜索 + 测试和调试文本检索 - 一个自定义文本搜索配置的行为很容易变得混乱。本节中描述的函数对于测试文本搜索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 + 一个自定义文本检索配置的行为很容易让人困惑。本节中描述的函数对于测试文本检索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 配置测试 - 函数ts_debug允许简单地测试一个文本搜索配置。 + 函数ts_debug可方便地测试一个文本检索配置。 @@ -2493,7 +2487,7 @@ ts_debug( config re - ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果该参数被忽略则使用default_text_search_config指定的配置。 + ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果省略该参数则使用default_text_search_config指定的配置。 @@ -2568,7 +2562,7 @@ SELECT * FROM ts_debug('english', 'a fat cat sat on a mat - it ate a fat rats') - 为了一个更广泛的示范,我们先为英语语言创建一个public.english配置和 Ispell 词典: + 为了做更完整的演示,我们先为英语创建一个public.english配置和 Ispell 词典: @@ -2626,7 +2620,7 @@ FROM ts_debug('public.english', 'The Brightest supernovaes'); 解析器测试 - 下列函数允许直接测试一个文本搜索解析器。 + 下列函数允许直接测试一个文本检索解析器。 @@ -2668,7 +2662,7 @@ ts_token_type(parser_oid oid< - ts_token_type返回一个表,描述指定解析器能够识别的每一种词元。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: + ts_token_type返回一个表,描述指定解析器能够识别的每一种词元类型。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: SELECT * FROM ts_token_type('default'); @@ -2706,7 +2700,7 @@ SELECT * FROM ts_token_type('default'); 词典测试 - ts_lexize函数帮助词典测试。 + ts_lexize函数便于测试词典。 @@ -2764,17 +2758,17 @@ SELECT plainto_tsquery('supernovae stars'); - 文本搜索的首选索引类型 + 文本检索的首选索引类型 - 文本搜索 + 文本检索 索引 - 有两种索引可以用来加速全文搜索:GIN和 + 有两种索引可以用来加速全文检索:GINGiST。 - 请注意,索引对于全文搜索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 + 请注意,索引对于全文检索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 @@ -2788,7 +2782,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GIN - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIN (column); @@ -2808,7 +2802,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GiST - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIST (column [ { DEFAULT | tsvector_ops } (siglen = number) ] ); @@ -2818,7 +2812,7 @@ SELECT plainto_tsquery('supernovae stars'); 创建基于 GiST(广义搜索树)的索引。 column可以是tsvectortsquery类型。 - 可选的整数参数siglen确定签名长度(有关详细信息,请参见下文)。 + 可选的整数参数siglen确定以字节为单位的签名长度(有关详细信息,请参见下文)。 @@ -2827,7 +2821,7 @@ SELECT plainto_tsquery('supernovae stars'); - GIN 索引是文本搜索的首选索引类型。作为倒排索引,每个词(词位)在 + GIN 索引是文本检索的首选索引类型。作为倒排索引,每个词(词位)在 其中都有一个索引项,其中有压缩过的匹配位置的列表。多词搜索可以找到 第一个匹配,然后使用该索引移除缺少额外词的行。GIN 索引只存储 tsvector值的词(词位),并且不存储它们的权重标签。因此, @@ -2835,19 +2829,19 @@ SELECT plainto_tsquery('supernovae stars'); - 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。以字节为单位的签名长度由可选整数参数 siglen 的值决定。 默认签名长度(未指定 siglen 时)为 124 字节,最大签名长度为 2024 字节。该签名通过哈希每一个词到一个 n 位串中的一个单一位来产生,通过将所有这些位 OR 在一起产生一个 n 位的文档签名。当两个词哈希到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。更长的签名导致更精确的搜索(扫描索引的一小部分和更少的堆页面),但代价是更大的索引。 + 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。以字节为单位的签名长度由可选整数参数 siglen 的值决定。 默认签名长度(未指定 siglen 时)为 124 字节,最大签名长度为 2024 字节。该签名通过将每个词 hash 到一个 n 位串中的一位,再将所有这些位进行 OR 运算来生成,结果是一个 n 位的文档签名。当两个词 hash 到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。更长的签名导致更精确的搜索(扫描更小比例的索引和更少的堆页面),但代价是更大的索引。 - GiST 可以构建为覆盖索引,例如使用 INCLUDE 子句。被包含的列可以具有没有任何 GiST 操作符类的数据类型。被包含的属性会以未压缩形式存储。 + GiST 可以构建为覆盖索引,即使用 INCLUDE 子句。被包含的列可以具有没有任何 GiST 操作符类的数据类型。被包含的属性会以未压缩形式存储。 - 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的可用性。假匹配的可能性取决于几个因素,特别是唯一词的数量,因此推荐使用词典来缩减这个数量。 + 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的实用性。假匹配的可能性取决于几个因素,特别是不同词的数量,因此推荐使用词典来缩减这个数量。 - 注意GIN索引的构件时间常常可以通过增加来改进,而GiST索引的构建时间则与该参数无关。 + 注意GIN索引的构建时间常常可以通过增加来改进,而GiST索引的构建时间则对该参数不敏感。 @@ -2861,7 +2855,7 @@ SELECT plainto_tsquery('supernovae stars'); <application>psql</application> 支持 - 关于文本搜索配置对象的信息可以在psql中使用一组命令获得: + 关于文本检索配置对象的信息可以在psql中使用一组命令获得: \dF{d,p,t}+ PATTERN @@ -2869,7 +2863,7 @@ SELECT plainto_tsquery('supernovae stars'); - 可选参数 PATTERN 可以是文本搜索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: + 可选参数 PATTERN 可以是文本检索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: => \dF *fulltext* @@ -2896,7 +2890,7 @@ SELECT plainto_tsquery('supernovae stars'); \dF+ PATTERN - 列出文本搜索配置(加上 + 可显示更多细节)。 + 列出文本检索配置(加上 + 可显示更多细节)。 => \dF russian List of text search configurations @@ -2937,7 +2931,7 @@ Parser: "pg_catalog.default" \dFd+ PATTERN - 列出文本搜索词典(加上 + 可显示更多细节)。 + 列出文本检索词典(加上 + 可显示更多细节)。 => \dFd List of text search dictionaries @@ -2982,7 +2976,7 @@ Parser: "pg_catalog.default" \dFp+ PATTERN - 列出文本搜索解析器(加上 + 可显示更多细节)。 + 列出文本检索解析器(加上 + 可显示更多细节)。 => \dFp List of text search parsers @@ -3035,7 +3029,7 @@ Parser: "pg_catalog.default" \dFt+ PATTERN - 列出文本搜索模板(加上 + 可显示更多细节)。 + 列出文本检索模板(加上 + 可显示更多细节)。 => \dFt List of text search templates @@ -3058,7 +3052,7 @@ Parser: "pg_catalog.default" 限制 - PostgreSQL 当前文本搜索特性的限制如下: + PostgreSQL 当前文本检索特性的限制如下: 每个词位的长度必须小于 2 千字节 @@ -3086,12 +3080,12 @@ Parser: "pg_catalog.default" - 为了对比,PostgreSQL 8.1 的文档包含 10,441 个唯一词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 + 为了对比,PostgreSQL 8.1 的文档包含 10,441 个不同词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 - 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个唯一词。 + 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个不同词。 diff --git a/zh/18/unaccent.sgml b/zh/18/unaccent.sgml index be5b7974..187386a3 100644 --- a/zh/18/unaccent.sgml +++ b/zh/18/unaccent.sgml @@ -1,18 +1,18 @@ - unaccent — 去除变音符号的文本搜索词典 + unaccent — 去除变音符号的文本检索词典 unaccent - unaccent是一个文本搜索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤字典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文搜索能够以不区分重音的方式处理文本。 + unaccent是一个文本检索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤词典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文检索能够以不区分重音的方式处理文本。 - unaccent当前的实现还不能作为thesaurus词典的正规化字典使用。 + unaccent当前的实现还不能作为thesaurus词典的正规化词典使用。 @@ -79,7 +79,7 @@ - 与其他PostgreSQL文本搜索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含不可转换字符的行都会被静默忽略,因此规则文件中可以包含不适用于当前编码的规则。 + 与其他PostgreSQL文本检索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含不可转换字符的行都会被静默忽略,因此规则文件中可以包含不适用于当前编码的规则。 @@ -93,7 +93,7 @@ 用法 - 安装unaccent扩展会创建一个文本搜索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 + 安装unaccent扩展会创建一个文本检索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 mydb=# ALTER TEXT SEARCH DICTIONARY unaccent (RULES='my_rules'); @@ -114,7 +114,7 @@ mydb=# select ts_lexize('unaccent','Hôtel'); - 下面的示例展示了如何将unaccent词典插入到文本搜索配置中: + 下面的示例展示了如何将unaccent词典插入到文本检索配置中: mydb=# CREATE TEXT SEARCH CONFIGURATION fr ( COPY = french ); mydb=# ALTER TEXT SEARCH CONFIGURATION fr @@ -145,7 +145,7 @@ mydb=# select ts_headline('fr','Hôtel de la Mer',to_tsquery('fr','Hotels') 函数 - unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本搜索环境之外使用。 + unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本检索环境之外使用。 @@ -157,7 +157,7 @@ unaccent(dictionary - 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本搜索词典。 + 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本检索词典。 diff --git a/zh/19/array.sgml b/zh/19/array.sgml index 10cc5e41..ead7c881 100644 --- a/zh/19/array.sgml +++ b/zh/19/array.sgml @@ -4,7 +4,7 @@ 数组 - array + 数组 @@ -15,8 +15,8 @@ 数组类型的声明 - array - declaration + 数组 + 声明 @@ -64,8 +64,8 @@ CREATE TABLE tictactoe ( 数组值输入 - array - constant + 数组 + 常量 @@ -86,7 +86,7 @@ CREATE TABLE tictactoe ( (这类数组常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。必要时可能需要显式指定类型。) + linkend="sql-syntax-constants-generic"/>中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。可能需要显式指定类型。) @@ -119,7 +119,7 @@ SELECT * FROM sal_emp; - 多维数组在每个维度上的范围必须匹配。不匹配会导致错误,例如: + 多维数组的各个子数组在每个维度上的长度必须匹配。不匹配会导致错误,例如: INSERT INTO sal_emp @@ -152,8 +152,8 @@ INSERT INTO sal_emp 访问数组 - array - accessing + 数组 + 访问 @@ -186,9 +186,9 @@ SELECT pay_by_quarter[3] FROM sal_emp; - 我们还可以访问数组或子数组的任意矩形切片。数组切片通过在一个或多个数组维度上写成 + 我们还可以访问数组的任意矩形切片,即子数组。数组切片通过在一个或多个数组维度上写成 lower-bound:upper-bound - 的形式来表示。例如,下面这个查询取回 Bill 在一周前两天日程安排中的第一个项目: + 的形式来表示。例如,下面这个查询取回 Bill 在一周中前两天里每天的首项日程: SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill'; @@ -235,11 +235,11 @@ SELECT schedule[:][1:1] FROM sal_emp WHERE name = 'Bill'; - 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回空值。此外,如果下标超出数组边界,也会返回空值(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是空值而不是错误。 + 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回 NULL。此外,如果下标超出数组边界,也会返回 NULL(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是 NULL 而不是错误。 - 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回空值。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是空值。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回空值。 + 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回 NULL。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是 NULL。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回 NULL。 @@ -293,8 +293,8 @@ SELECT cardinality(schedule) FROM sal_emp WHERE name = 'Carol'; 修改数组 - array - modifying + 数组 + 修改 @@ -331,7 +331,7 @@ UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}' - 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用空值填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含空值。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 + 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用 NULL 填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含 NULL。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 @@ -443,21 +443,21 @@ SELECT array_cat(ARRAY[5,6], ARRAY[[1,2],[3,4]]); 在简单情况下,优先使用上面讨论的连接操作符,而不是直接调用这些函数。不过,由于连接操作符被重载以同时服务于这三种情形,所以在某些场景下使用这些函数之一有助于避免歧义。例如,考虑: -SELECT ARRAY[1, 2] || '{3, 4}'; -- the untyped literal is taken as an array +SELECT ARRAY[1, 2] || '{3, 4}'; -- 未指定类型的字面量被当作数组 ?column? ----------- {1,2,3,4} -SELECT ARRAY[1, 2] || '7'; -- so is this one +SELECT ARRAY[1, 2] || '7'; -- 这个字面量也一样 ERROR: malformed array literal: "7" -SELECT ARRAY[1, 2] || NULL; -- so is an undecorated NULL +SELECT ARRAY[1, 2] || NULL; -- 未加类型修饰的 NULL 也一样 ?column? ---------- {1,2} (1 row) -SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant +SELECT array_append(ARRAY[1, 2], NULL); -- 这可能才是原本想表达的意思 array_append -------------- {1,2,NULL} @@ -471,8 +471,8 @@ SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant 在数组中搜索 - array - searching + 数组 + 搜索 @@ -552,7 +552,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); 数组输入和输出语法 - array + 数组 I/O @@ -565,7 +565,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); - 默认情况下,数组各维度的下界索引值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: + 默认情况下,数组各维度的下界下标值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2 FROM (SELECT '[1:1][-2:-1][3:5]={{{1,2,3},{4,5,6}}}'::int[] AS f1) AS ss; diff --git a/zh/19/catalogs.sgml b/zh/19/catalogs.sgml index f5bce9be..0ad681a8 100644 --- a/zh/19/catalogs.sgml +++ b/zh/19/catalogs.sgml @@ -345,27 +345,27 @@ pg_ts_config - 文本搜索配置 + 文本检索配置 pg_ts_config_map - 文本搜索配置的词元映射 + 文本检索配置的词元映射 pg_ts_dict - 文本搜索字典 + 文本检索词典 pg_ts_parser - 文本搜索分析器 + 文本检索解析器 pg_ts_template - 文本搜索模板 + 文本检索模板 @@ -8345,12 +8345,12 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config目录包含表示文本搜索配置的条目。一个配置指定某个特定的文本搜索分析器,以及针对该分析器每种输出词元类型所定义的字典列表。分析器由pg_ts_config项表示,而词元到字典的映射则由pg_ts_config系统目录包含表示文本检索配置的条目。一个配置指定某个特定的文本检索解析器,以及针对该解析器每种输出词元类型所定义的词典列表。解析器记录在pg_ts_config条目中,而词元到词典的映射则由pg_ts_config_map中的辅助项定义。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。 @@ -8382,7 +8382,7 @@ SCRAM-SHA-256$<iteration count>:&l cfgname name - 文本搜索配置名 + 文本检索配置名 @@ -8412,7 +8412,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_ts_parser.oid - 该配置的文本搜索分析器的OID + 该配置的文本检索解析器的 OID @@ -8429,11 +8429,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config_map目录包含的项展示了对于每一个文本搜索配置的每一种输出词元类型,有哪些文本搜索字典可供查询以及以何种顺序。 + pg_ts_config_map 系统目录中的条目说明了,对于每个文本检索配置所用解析器的每种输出词元类型,应当查询哪些文本检索词典以及查询的顺序。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -8466,7 +8466,7 @@ SCRAM-SHA-256$<iteration count>:&l maptokentype int4 - 一种由配置的分析器送出的词元类型 + 一种由配置的解析器送出的词元类型 @@ -8485,7 +8485,7 @@ SCRAM-SHA-256$<iteration count>:&l (参考 pg_ts_dict.oid - 要查询的文本搜索字典的OID + 要查询的文本检索词典的 OID @@ -8502,11 +8502,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_dict目录包含定义文本搜索字典的项。一个字典依赖于一个文本搜索模板,它指定了所有需要的函数实现,字典本身则为模板支持的用户可设置参数提供值。这种分工允许无权限的用户创建字典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 + pg_ts_dict系统目录包含定义文本检索词典的项。一个词典依赖于一个文本检索模板,它指定了所有需要的实现函数,词典本身则为模板支持的用户可设置参数提供值。这种分工允许普通用户创建词典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -8538,7 +8538,7 @@ SCRAM-SHA-256$<iteration count>:&l dictname name - 文本搜索字典名 + 文本检索词典名 @@ -8548,7 +8548,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_namespace.oid - 包含该字典的名字空间OID + 包含该词典的名字空间的 OID @@ -8558,7 +8558,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_authid.oid - 字典的拥有者 + 词典的拥有者 @@ -8568,7 +8568,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_ts_template.oid - 该字典的文本搜索模板的OID + 该词典的文本检索模板的 OID @@ -8594,11 +8594,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_parser目录包含定义文本搜索分析器的项。一个分析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个分析器必须用C语言级别的函数实现,创建新分析器的工作只限于数据库的超级用户。 + pg_ts_parser系统目录包含定义文本检索解析器的项。一个解析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个解析器必须用 C 语言级别的函数实现,创建新解析器的工作只限于数据库的超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -8630,7 +8630,7 @@ SCRAM-SHA-256$<iteration count>:&l prsname name - 文本搜索分析器的名字 + 文本检索解析器的名字 @@ -8640,7 +8640,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_namespace.oid - 包含此分析器的名字空间的OID + 包含此解析器的名字空间的 OID @@ -8650,7 +8650,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器启动函数的OID + 解析器启动函数的 OID @@ -8660,7 +8660,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的下一词元函数的OID + 解析器的下一词元函数的 OID @@ -8670,7 +8670,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的关闭函数的OID + 解析器的关闭函数的 OID @@ -8680,7 +8680,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器标题函数的 OID(如果没有则为零) + 解析器的 headline 函数的 OID(如果没有则为零) @@ -8690,7 +8690,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的词汇类型函数的OID + 解析器的 lextype 函数的 OID @@ -8707,11 +8707,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_template目录包含定义文本搜索模板的项。一个模板是一类文本搜索字典的实现骨架。由于一个模板必须用C语言级别的函数实现,新模板的创建只限于数据库超级用户。 + pg_ts_template系统目录包含定义文本检索模板的项。一个模板是一类文本检索词典的实现骨架。由于一个模板必须用 C 语言级别的函数实现,新模板的创建只限于数据库超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -8743,7 +8743,7 @@ SCRAM-SHA-256$<iteration count>:&l tmplname name - 文本搜索模板的名字 + 文本检索模板的名字 diff --git a/zh/19/client-auth.sgml b/zh/19/client-auth.sgml index 7e1eeb5f..72f74112 100644 --- a/zh/19/client-auth.sgml +++ b/zh/19/client-auth.sgml @@ -1685,7 +1685,7 @@ host ... ldap ldapbasedn="dc=example,dc=net" scope - 一个以空格分隔的 OAuth 作用域(scope)列表,服务器需要借此既能授权客户端,又能认证用户。合适的取值由授权服务器以及所使用的 OAuth 验证模块决定(关于验证器的更多信息,见 )。此参数为必需项。 + 一个以空格分隔的 OAuth 授权范围列表,服务器需要借此既能授权客户端,又能认证用户。合适的取值由授权服务器以及所使用的 OAuth 验证模块决定(关于验证器的更多信息,见 )。此参数为必需项。 diff --git a/zh/19/config.sgml b/zh/19/config.sgml index 0b147c74..eb7d759c 100644 --- a/zh/19/config.sgml +++ b/zh/19/config.sgml @@ -3106,7 +3106,7 @@ include_dir 'conf.d' 配置 - 恢复的 + 恢复 一般设置 @@ -3164,7 +3164,7 @@ include_dir 'conf.d' 配置 恢复 - 一个备库 + 备库 @@ -3635,7 +3635,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows - 列出安装在 所指定位置中、同时也被信任可供复制客户端用作逻辑输出插件的库。 + 列出安装在 所指定位置中、同时也受信任、可供复制客户端用作逻辑输出插件的库。 任何针对其他库的逻辑解码或 复制请求都将被拒绝。所有用户都受此限制。 默认值为 'pgoutput, test_decoding',它们是标准 @@ -4363,8 +4363,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( )。 + 设置规划器对一系列顺序磁盘页面读取中单次读取的代价估计。默认值是 1.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -4784,7 +4777,7 @@ ANY num_sync ( )。 + 设置规划器对一次非顺序磁盘页面读取的代价估计。默认值是 4.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -4797,14 +4790,13 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( 。 如果指定值时没有单位,则以块为单位,即BLCKSZ字节,通常为8kB。默认值是512千字节(512kB)。 @@ -4930,13 +4922,13 @@ ANY num_sync ( num_sync ( - 遗传查询优化 + 遗传查询优化器 - GEQO是一个使用探索式搜索来执行查询规划的算法。它可以降低负载查询的规划时间。 同时,GEQO的检索是随机的,因此它的规划可能会不可确定。 更多信息参阅Chapter 50。 - 遗传查询规划器(GEQO)是一种使用启发式搜索来进行查询规划的算法。它可以降低对于复杂查询(连接很多表的查询)的规划时间,但是代价是它产生的计划有时候要差于使用穷举搜索算法找到的计划。详见。 + 遗传查询优化器(GEQO)是一种使用启发式搜索进行查询规划的算法。它可以缩短复杂查询(连接很多关系的查询)的规划时间,代价是生成的计划有时不如常规穷举搜索算法找到的计划。更多信息见 @@ -5032,7 +5023,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( .) + 目前,约束排除仅在通常用于通过继承树实现表分区的情况下默认启用。为所有表启用它会增加额外的规划开销,这在简单查询上相当明显,而且通常不会为简单查询带来好处。如果没有通过传统继承方式进行分区的表,你可能希望完全关闭它。(注意,分区表的等效功能由另一个参数控制。) @@ -5281,13 +5269,7 @@ SELECT * FROM parent WHERE key = 2400; - 准备语句(显式准备或隐式生成的,例如 PL/pgSQL)可以使用自定义或通用计划执行。 - 使用其特定的参数值集为每个执行重新生成自定义计划,而通用计划不依赖于参数值,并且可以在执行中重复使用。 - 因此,使用通用计划可以节省计划时间,但如果理想计划严重依赖参数值,则通用计划可能效率低下。 - 这些选项之间的选择通常是自动进行的,但可以通过plan_cache_mode覆盖它。 - 允许的值为 auto (默认的),force_custom_planforce_generic_plan。 - 这个设置是在执行缓存计划时考虑,而不是在准备计划时考虑。 - 更多信息请参阅 . + 预备语句(无论是显式预备的,还是由 PL/pgSQL 等隐式生成的)可以使用自定义计划或通用计划执行。自定义计划会根据每次执行的具体参数值重新生成,而通用计划不依赖参数值,可以在多次执行之间复用。因此,使用通用计划能够节省规划时间,但如果理想计划高度依赖参数值,通用计划可能效率较低。系统通常会自动选择这两种计划,但可以通过plan_cache_mode覆盖这一选择。允许的值为auto(默认值)、force_custom_planforce_generic_plan。系统在执行缓存计划时考虑此设置,而不是在预备计划时。更多信息见 @@ -5305,7 +5287,7 @@ SELECT * FROM parent WHERE key = 2400; 设置规划器对递归查询 的工作表的平均大小的估计值,作为查询初始非递归项的估计大小的倍数。 这有助于规划器选择将工作表与查询的其他表连接的最合适方法。 - 默认值为10.0。当递归从一步到下一步的fan-out较低时,如最短路径查询中的示例,使用较小的值(如1.0)可能有所帮助。 + 默认值为10.0。当递归从一步到下一步的扇出较低时,例如最短路径查询,使用较小的值(如1.0)可能有所帮助。 图分析查询可能会从大于默认值的设置中受益。 @@ -5324,7 +5306,7 @@ SELECT * FROM parent WHERE key = 2400; - 在哪里做日志 + 日志记录到哪里 日志写到哪里 @@ -5332,7 +5314,7 @@ SELECT * FROM parent WHERE key = 2400; current_logfiles - 和日志_目的地配置参数 + 和 log_destination 配置参数 @@ -5380,13 +5362,13 @@ jsonlog log/postgresql.json 当由于轮换而创建新的日志文件时,以及重新加载log_destination时,current_logfiles会被重新创建。 当log_destination中不包含stderrcsvlogjsonlog, - 以及日志收集器被禁用时,它会被移除。 + 或者日志收集器被禁用时,它会被移除。 - 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设备LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: + 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设施LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: local0.* /var/log/postgresql @@ -5394,7 +5376,7 @@ local0.* /var/log/postgresql - 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源极其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见。 + 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源及其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见 @@ -5410,20 +5392,20 @@ local0.* /var/log/postgresql - 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 + 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息可能不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 - 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供方法来轮转日志文件。还有,在某些不使用日志收集器的平台上可能会导致丢失或者混淆日志输出,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 + 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供便捷的方法来轮转日志文件。还有,在某些平台上,不使用日志收集器可能会导致日志输出丢失或混杂,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 - 日志收集器被设计成从来不会丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 + 日志收集器被设计成从来不会丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它可能会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 @@ -5457,7 +5439,7 @@ local0.* /var/log/postgresql logging_collector被启用时,这个参数设置被创建的日志文件的文件名。 - 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何时区独立的%转义,计算将在由指定的时区中完成)。 + 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何依赖时区的%转义,计算将在由指定的时区中完成)。 被支持的%转义和开放组织的strftime说明中列举的类似。 注意系统的strftime不会被直接使用,因此平台相关(非标准)的扩展无法工作。 默认是postgresql-%Y-%m-%d_%H%M%S.log。 @@ -5495,7 +5477,7 @@ local0.* /var/log/postgresql - 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的十进制格式,该数字必须以一个0(零)开始)。 + 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的八进制格式,该数字必须以一个0(零)开始)。 @@ -5561,7 +5543,7 @@ local0.* /var/log/postgresql - 示例:要保留 24 小时的日志,每个小时一个日志文件,但是在日志文件尺寸超过 1GB 时轮转。可以这样做:将log_filename设置为server_log.%H%M、 + 示例:要保留 24 小时的日志,每个小时一个日志文件,如果日志文件尺寸超过 1GB,也会提前轮转。可以这样做:将log_filename设置为server_log.%H%M、 将log_truncate_on_rotation设置为on、 将log_rotation_age设置为60并且 将log_rotation_size设置为1000000。 @@ -5580,7 +5562,7 @@ local0.* /var/log/postgresql - 当启用了向syslog记录时,这个参数决定要使用的syslog设备。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4、 + 当启用了向syslog记录时,这个参数决定要使用的syslog设施。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4LOCAL5LOCAL6LOCAL7中选择,默认值是LOCAL0。还请参阅系统的syslog守护进程的文档。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -5635,7 +5617,7 @@ local0.* /var/log/postgresql - 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,有必要让消息保持逻辑上的整体性(也更加有用)。 + 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,让消息保持逻辑上的完整性可能是必要的,也可能更有用。 @@ -5654,7 +5636,7 @@ local0.* /var/log/postgresql - 当启用了向事件日志记录时,这个参数决定用来标识日志中PostgreSQL消息的程序名。默认值是PostgreSQL。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 当启用了向事件日志记录时,这个参数决定用来标识日志中PostgreSQL消息的程序名。默认值是PostgreSQL。这个参数只能在服务器启动时设置。 @@ -5725,9 +5707,7 @@ local0.* /var/log/postgresql - 控制在服务器日志中记录哪些导致错误条件的SQL语句。当前的SQL语句将包含在任何指定 - severity - 或更高消息的日志条目中。 + 控制在服务器日志中记录哪些导致错误条件的SQL语句。对于达到指定严重级别或更高级别的消息,其日志条目中会包含当前 SQL 语句。 有效值为DEBUG5DEBUG4DEBUG3DEBUG2DEBUG1、 @@ -5767,7 +5747,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -5805,7 +5785,7 @@ local0.* /var/log/postgresql - log_min_duration_statement的其他注释也适用于此设置。 + log_min_duration_statement的其他说明也适用于此设置。 @@ -5820,8 +5800,8 @@ local0.* /var/log/postgresql - 确定持续时间超过的语句的比例将被记录。 - 采样是随机的,例如0.5表示统计上有一半的机会任何给定的语句将被记录。 + 确定持续时间超过的语句中,将被记录的语句比例。 + 采样是随机的,例如0.5表示任意给定语句被记录的统计概率为二分之一。 默认值为1.0,表示记录所有采样的语句。 将此设置为零将禁用采样语句持续时间记录,与将log_min_duration_sample设置为-1相同。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -5839,7 +5819,7 @@ local0.* /var/log/postgresql - 设置所有语句都被记录的事务的比例,除了其他原因记录的语句。它适用于每个新事务,无论其语句的持续时间如何。 + 设置需要记录全部语句的事务比例,这些记录是在因其他原因记录的语句之外额外进行的。它适用于每个新事务,无论其语句的持续时间如何。 采样是随机的,例如0.1表示任何给定事务被记录的统计概率是十分之一。 log_transaction_sample_rate可以帮助构建事务样本。 默认值为0,表示不记录任何额外事务的语句。将其设置为1会记录所有事务的所有语句。 @@ -5864,8 +5844,7 @@ local0.* /var/log/postgresql - 设置启动进程在长时间运行的操作仍在进行时记录消息的时间间隔, - 以及该操作进一步进展消息之间的间隔时间。默认值为10秒。 + 设置启动进程在长时间运行的操作开始后,等待多久才记录第一条进度消息,以及此后该操作的进度消息之间的时间间隔。默认值为10秒。 设置为0会禁用该功能。如果未指定单位, 则将其视为毫秒。此设置分别应用于每个操作。 此参数只能在postgresql.conf文件或服务器命令行中设置。 @@ -5907,7 +5886,7 @@ local0.* /var/log/postgresql DEBUG1 .. DEBUG5 - 为开发者提供连续的更详细的信息。 + 为开发者提供逐级更加详细的信息。 DEBUG INFORMATION @@ -5967,7 +5946,7 @@ local0.* /var/log/postgresql - 记录什么到日志 + 记录哪些内容 @@ -5988,7 +5967,7 @@ local0.* /var/log/postgresql - application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。它也会被通过包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为C 风格的十六进制转义序列。 + application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。也可以通过将其包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为C 风格的十六进制转义序列。 @@ -6060,7 +6039,7 @@ local0.* /var/log/postgresql - 每次由自动清理执行的清理操作都会被记录,如果运行时间至少达到指定时间。 + 当自动清理执行的清理操作运行时间至少达到指定时间时,就会记录该操作。 将此设置为零会记录所有由自动清理执行的清理操作。 -1会禁用记录由自动清理执行的清理操作。 如果未指定单位,则将其视为毫秒。 @@ -6083,7 +6062,7 @@ local0.* /var/log/postgresql - 每次由自动清理执行的分析操作都会被记录,如果运行时间至少达到指定时间。 + 当自动清理执行的分析操作运行时间至少达到指定时间时,就会记录该操作。 将此设置为零会记录所有由自动清理执行的分析操作。 -1会禁用记录由自动清理执行的分析操作。 如果未指定单位,则将其视为毫秒。 @@ -6222,7 +6201,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -6245,7 +6224,7 @@ local0.* /var/log/postgresql 控制在服务器日志中记录的每条消息的详细程度。有效值为TERSE, - DEFAULTVERBOSE,每个值都会添加更多字段到显示的消息中。 + DEFAULTVERBOSE,它们依次在显示的消息中增加更多字段。 TERSE不包括DETAILHINTQUERYCONTEXT错误信息的记录。 VERBOSE输出包括SQLSTATE错误代码 @@ -6265,7 +6244,7 @@ local0.* /var/log/postgresql - 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致很微小的性能损失。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致不可忽视的性能开销。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -6284,7 +6263,7 @@ local0.* /var/log/postgresql %字符开始转义序列,它将被按照下文描述的替换成状态信息。 未识别的转义被忽略。其他字符被直接复制到日志行。某些转义只被会话进程识别并且被主服务器进程等后台进程当作空。 通过指定一个在%之后和该选项之前的数字可以让状态信息左对齐或右对齐。 - 负值将导致在右边用空格填充状态信息已达到最小宽度,而正值则在左边填充。填充对于日志文件的人类可读性大有帮助。 + 负值将导致在右边用空格填充状态信息以达到最小宽度,而正值则在左边填充。填充对于日志文件的人类可读性大有帮助。 @@ -6352,8 +6331,8 @@ local0.* /var/log/postgresql %P - 并行组leader的进程ID,如果该进程是一个并行查询worker - no + 如果该进程是并行查询工作进程,则为并行组领导者的进程 ID + @@ -6370,8 +6349,8 @@ local0.* /var/log/postgresql %n - 带毫秒的时间戳(作为 Unix 时代) - no + 带毫秒精度的 Unix 时间戳 + @@ -6426,7 +6405,7 @@ local0.* /var/log/postgresql %Q 当前查询的查询标识符。 查询标识符默认是不计算的,所以这个部分将是零,除非 参数被激活或者配置了计算查询标识符的第三方模块 - yes + @@ -6445,7 +6424,7 @@ local0.* /var/log/postgresql %c转义打印一个准唯一的会话标识符,它由两个 4 字节的十六进制数(不带先导零)组成,以点号分隔。 - 这些数字是进程启动时间和进程 ID,因此%c也可以被用作保存打印这些项的方式的空间。 + 这些数字是进程启动时间和进程 ID,因此%c也可以用来节省空间地输出这两项信息。 例如,要从pg_stat_activity生成会话标识符,使用这个查询: SELECT to_hex(trunc(EXTRACT(EPOCH FROM backend_start))::integer) || '.' || @@ -6483,7 +6462,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 对于输出的行,%Q 总是报告零标识符, - 因为log_statement在标识符能被计算之前生成输出,包括无效标识符不能计算的无效语句。 + 因为log_statement在标识符能被计算之前生成输出,也包括无法计算标识符的无效语句。 @@ -6531,8 +6510,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 控制启动进程等待时间超过针对恢复冲突的deadlock_timeout的时候是否产生日志消息。 - 这对于决定恢复冲突是否会阻止恢复应用WAL有所帮助。 + 控制启动进程因恢复冲突而等待超过deadlock_timeout时是否产生日志消息。这有助于判断恢复冲突是否阻碍了恢复过程应用 WAL。 @@ -6560,9 +6538,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 此设置仅影响由、 - 及相关设置产生的日志消息。 - 该设置的非零值会增加一些开销,特别是当参数以二进制形式发送时,因为需要转换为文本。 + 此设置仅影响由及相关设置产生的日志消息。此设置为非零值时会增加一些开销,特别是以二进制形式发送参数时,因为需要将参数转换为文本。 @@ -6606,7 +6582,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' UPDATEDELETETRUNCATE, 和COPY FROM。 如果PREPAREEXECUTE和 - EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个执行消息时会产生日志并且会包括绑定参数的值(任何内嵌的单引号会被双写)。 + EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个 Execute 消息时会产生日志并且会包括 Bind 参数的值(任何内嵌的单引号会被双写)。 @@ -6617,7 +6593,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在执行阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 + 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在 Execute 阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 @@ -6637,7 +6613,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 每个复制命令都会被记录在服务器日志中。 + 在服务器日志中记录每个复制命令,以及walsender进程获取和释放复制槽的操作。 有关复制命令的更多信息,请参见。 默认值为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -6656,8 +6632,8 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 控制临时文件名和大小的日志记录。 - 临时文件可以用于排序、哈希和临时查询结果。 - 如果通过此设置启用,每当删除临时文件时都会发出日志记录。 + 临时文件可以用于排序、hash 和临时查询结果。 + 如果通过此设置启用,每当删除临时文件时都会发出日志记录,其中文件大小以字节为单位。 值为零时记录所有临时文件信息,而正值仅记录大小大于或等于指定数据量的文件。 如果未指定单位,则将其视为千字节。 默认设置为-1,禁用此类日志记录。 @@ -6710,7 +6686,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 错误上下文、 导致错误的用户查询(如果有且被log_min_error_statement启用)、 错误位置所在的字符计数、 - 在 PostgreSQL 源代码中错误的位置(如果log_error_verbosity被设置为verbose)以及应用名,后端类型,并行组leader的进程ID和查询ID。 + 在 PostgreSQL 源代码中错误的位置(如果log_error_verbosity被设置为verbose)、应用名、后端类型、并行组领导者的进程 ID 和查询 ID。 下面是一个定义用来存储 CSV 格式日志输出的样表: @@ -6762,7 +6738,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 设置log_filenamelog_rotation_age为你的日志文件提供一种一致的、可预测的命名空间。这让你预测文件名会是怎样以及知道什么时候一个个体日志文件完成并且因此准备好被导入。 + 设置log_filenamelog_rotation_age,为日志文件提供一致且可预测的命名方案。这样就能预测文件名,并知道单个日志文件何时已完成写入、可以导入。 @@ -6791,12 +6767,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 使用JSON格式的日志输出 - 包括jsonloglog_destination列表中提供了一种方便的方式将日志文件导入到许多不同的程序中。此选项以JSON格式发出日志行。 + 将jsonlog加入log_destination列表,可以方便地将日志文件导入多种不同的程序。此选项以JSON格式输出日志行。 - 字段值为null的字符串字段将被排除在输出之外。 - 未来可能会添加其他字段。处理jsonlog输出的用户应忽略未知字段。 + 值为空值的字符串字段不会输出。将来可能会添加其他字段。处理jsonlog输出的用户应用程序应忽略未知字段。 @@ -6941,13 +6916,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; statement string - 客户提供的查询字符串 + 客户端提供的查询字符串 cursor_position number - 查询字符串中的光标索引 + 查询字符串中的游标索引 @@ -7001,7 +6976,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 进程标题 - 这些设置控制服务器进程的进程标题如何被修改。进程标题通常可以用ps或者 Windows 上的进程浏览器等程序来查看。详见。 + 这些设置控制服务器进程的进程标题如何修改。通常可以通过ps等程序查看进程标题,在 Windows 上则可以使用Process Explorer。详情参见 @@ -7035,7 +7010,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 每次服务器接收到新的SQL命令时,都可以更新进程标题。 + 启用后,每次服务器接收到新的 SQL 命令时都会更新进程标题。 在大多数平台上,默认情况下此设置为on,但在Windows上默认为off, 因为该平台更新进程标题的开销较大。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -7073,7 +7048,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对每个会话当前执行命令的信息收集,包括其标识符和命令开始执行的时间。 - 此参数默认为开启状态。请注意,即使启用了此信息,只有超级用户、具有 + 此参数默认为开启状态。请注意,即使启用了此参数,只有超级用户、具有 pg_read_all_stats角色权限的角色和拥有被报告会话的用户 (包括属于他们具有权限的角色的会话)才能看到此信息,因此不应构成安全风险。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -7091,7 +7066,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 为每个活动会话指定存储当前执行命令的文本所保留的内存量,它们被用于pg_stat_activity.query域。 + 为每个活动会话指定存储当前执行命令的文本所预留的内存量,它们被用于pg_stat_activity.query字段。 如果指定值时没有单位,则以字节为单位。默认值是 1024字节。这个参数只能在服务器启动时被设置。 @@ -7108,7 +7083,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对数据库活动的统计信息收集。 - 此参数默认为开启,因为自动清理守护进程需要收集的信息。 + 此参数默认为开启,因为自动清理守护进程需要这些收集到的信息。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -7184,7 +7159,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用函数调用次数和时间的跟踪。指定pl以仅跟踪过程语言函数, + 启用函数调用次数和耗时的跟踪。指定pl以仅跟踪过程语言函数, all以同时跟踪SQL和C语言函数。默认值为none, 即禁用函数统计跟踪。只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -7219,7 +7194,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - none适用于监控系统。如果值只被访问一次,它是最有效的。 + none最适合监控系统。如果值只被访问一次,它是最有效的。 cache确保重复访问产生相同的值,这对涉及自连接的查询很重要。 snapshot在交互式检查统计信息时可能很有用,但开销较高, 特别是存在许多数据库对象时。 @@ -7246,21 +7221,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用查询标识符的内核计算。 - 查询标识符可以在 pg_stat_activity - 视图中显示,使用 EXPLAIN,或者如果通过 - 参数进行配置,则可以在日志中发出。 - 扩展还需要计算查询标识符。 - 请注意,如果内核查询标识符计算方法不可接受,也可以使用外部模块。 - 在这种情况下,必须始终禁用内核计算。 - 有效值为 off(始终禁用), - on(始终启用),auto, - 允许诸如 这样的模块 - 自动启用它,并且 regress 具有与 - auto 相同的效果,只是查询标识符不会显示在 - EXPLAIN 输出中,以便促进自动回归测试。 - 默认值为 auto。 + 启用内置的查询标识符计算功能。查询标识符可以显示在pg_stat_activity视图或EXPLAIN的输出中,也可以通过参数配置后写入日志。扩展也要求计算查询标识符。注意,如果内置的查询标识符计算方法不符合要求,可以改用外部模块。在这种情况下,必须始终禁用内置计算功能。有效值为off(始终禁用)、on(始终启用)、auto(允许等模块自动启用此功能),以及regress。后者与auto效果相同,但不会在EXPLAIN输出中显示查询标识符,以便进行自动回归测试。默认值为auto @@ -7300,7 +7261,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 对于每个查询,将各自模块的性能统计输出到服务器日志中。这是一个简单的性能分析工具,类似于Unix getrusage()操作系统功能。 - log_statement_stats报告总语句统计,而其他选项报告每个模块的统计信息。 + log_statement_stats报告整个语句的统计信息,而其他选项报告每个模块的统计信息。 log_statement_stats不能与任何单独模块选项一起启用。所有这些选项默认情况下都是禁用的。 只有超级用户和具有适当SET权限的用户才能更改这些设置。 @@ -7983,7 +7944,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; DEBUG1LOGNOTICEWARNINGERROR。 每个级别都包括其后的所有级别。级别越靠后,被发送的消息越少。默认值是NOTICE。 - 注意LOG在这里有与中不同的排名。 + 注意LOG在这里的排序与中的不同。 @@ -8003,15 +7964,15 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,用于进行搜索该对象的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 + 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,搜索该对象时的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 - search_path的值必需是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被安静地忽略。 + search_path的值必须是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被静默忽略。 - 如果列表项之一是特殊名$user,则具有SESSION_USER返回的名字的模式将取代它(如果有这样一个模式并且该用户有该模式的USAGE权限;如果没有,$user会被忽略)。 + 如果列表项之一是特殊名$user,则具有CURRENT_USER返回的名字的模式将取代它(如果有这样一个模式并且该用户有该模式的USAGE权限;如果没有,$user会被忽略)。 @@ -8036,11 +7997,12 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个参数的缺省值是"$user", public。这种设置支持一个数据库(其中没有用户拥有私有模式,并且所有人共享使用public)、每个用户私有模式及其组合的共享使用。其它效果可以通过全局或者针对每个用户修改默认搜索路径设置获得。 + 这个参数的默认值是"$user", public。这种设置支持共享使用数据库(用户没有私有模式,所有人共享使用public)、每个用户拥有私有模式,以及二者的组合。 + 还可以通过全局或针对每个用户修改默认搜索路径设置来获得其他效果。 - 更多有关方案处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 + 更多有关模式处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 @@ -8060,7 +8022,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,只要有至少一条策略被应用则查询就会失败。默认为on。受限的行可见性会导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS)属性的角色没有效果。 + 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,原本会应用至少一条策略的查询就会失败。默认为on。受限的行可见性可能导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS属性的角色)没有效果。 @@ -8079,8 +8041,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个参数指定了在创建表或物化视图时使用的默认表访问方法,如果CREATE命令没有明确指定访问方法, - 或者当使用SELECT ... INTO时,不允许指定表访问方法。默认值是heap。 + 创建表或物化视图时,如果CREATE命令没有显式指定访问方法,或者使用了不允许指定表访问方法的SELECT ... INTO,则使用此参数指定的默认表访问方法。默认值为heap @@ -8100,7 +8061,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建企图将失败。 + 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建尝试将失败。 @@ -8108,7 +8069,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当创建数据库时也会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 + 创建数据库时也不会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 @@ -8157,11 +8118,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被放置在里表中的连续表空间中。如果列表被选中元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 + 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被依次放置在列表中的连续表空间中。如果列表中被选中的元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 - 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,类似于为用户指定一个不具有CREATE权限的表空间。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特殊地,使用一个在postgresql.conf中设置的值时,这条规则起效。 + 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,指定一个用户不具有CREATE权限的表空间也同样是错误。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特别是,使用一个在postgresql.conf中设置的值时,这条规则起效。 @@ -8186,7 +8147,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 这个参数通常为打开。 当设置为off时,它禁用期间对例程体字符串的验证。 - 禁用验证避免了验证处理的副作用,特别避免了如向前引用导致的伪肯定。 + 禁用验证避免了验证处理的副作用,特别是避免前向引用等问题导致的误报。 在代表其他用户载入函数之前设置这个参数为offpg_dump会自动这样做。 @@ -8229,7 +8190,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态 。默认是off(读/写)。 + 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态。默认是off(读/写)。 @@ -8252,11 +8213,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当运行在可串行化隔离级别时,一个可延迟只读 SQL 事务可以在它被允许继续之前延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的负荷;因此串行化代码将没有任何理由因为并发更新而强制它中断,使得这个选项适合于长时间运行的只读事务。 + 当运行在serializable隔离级别时,一个可延迟只读 SQL 事务可能在获准继续之前被延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的开销;因此串行化代码将没有任何理由因为并发更新而强制它中止,使得这个选项适合于长时间运行的只读事务。 - 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些操作在低于可串行化隔离级别上的事务无效。默认值是off。 + 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些运行在低于serializable隔离级别上的事务无效。默认值是off @@ -8300,7 +8261,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的只读状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -8320,7 +8281,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的可延迟性状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -8344,7 +8305,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 这个设置的预期用途是由逻辑复制系统在应用所复制的更改时将它设置为replica。 - 其效果将是触发器和规则(没有对其默认配置做修改)在复制机上将不会被触发。 + 其效果将是触发器和规则(没有对其默认配置做修改)在副本上将不会被触发。 更多信息请参考ALTER TABLE的子句ENABLE TRIGGER以及ENABLE RULE @@ -8374,9 +8335,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 超时从命令到达服务器的时间开始计算,一直到它被服务器完成为止。 - 如果单个简单查询消息中出现多个 SQL 语句,超时将分别应用于每个语句。(PostgreSQL 13 之前的版本通常将超时应用于整个查询字符串。 - 在扩展查询协议中,当任何与查询相关的消息(解析、绑定、执行、描述)到达时,超时就开始运行,并且可以通过执行完成或同步消息来取消超时。 + 超时从命令到达服务器时开始计算,直到服务器完成该命令为止。 + 如果单个简单查询消息中出现多个 SQL 语句,超时将分别应用于每个语句。 + (PostgreSQL 13 之前的版本通常将超时应用于整个查询字符串。) + 在扩展查询协议中,当任何与查询相关的消息(Parse、Bind、Execute、Describe)到达时开始计时, + 并在处理完 Execute 或 Sync 消息时取消计时。 @@ -8420,13 +8383,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 如果任何语句在试图获取表、索引、行或其他数据库对象上的锁时等到超过指定的时间量,该语句将被中止。 + 如果任何语句在试图获取表、索引、行或其他数据库对象上的锁时等待超过指定的时间量,该语句将被中止。 该时间限制独立地应用于每一次锁获取尝试。该限制会应用到显式锁定请求(如LOCK TABLE或不带NOWAITSELECT FOR UPDATE)和隐式获得的锁。 如果指定值时没有单位,则以毫秒为单位。一个零值(默认)将禁用超时。 - 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为事务超时将总是第一个被触发。 + 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为语句超时将总是第一个被触发。 如果log_min_error_statement 被设置为ERROR 或更低,超时的语句将被记录。 @@ -8446,15 +8409,14 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 终止任何已经闲置(这是指,等待客户端查询)超过这个参数所指定时间量的打开事务的会话。 - 如果这个值指定时没有单位,它被设为毫秒。 - 零值(默认)禁用超时。 + 终止在打开的事务中空闲(即等待客户端查询)超过指定时长的任何会话。 + 如果指定值时不带单位,则以毫秒为单位。零值(默认值)禁用此超时。 - 此选项可以用于确保空闲会话不会在不合理的时间内持有锁。 - 即使没有持有重要的锁的时候,打开的事务也会防止清理最近死亡的可能只对这个事务可见的元组;所以长时间保持空闲会导致表膨胀。 - 详见。 + 此选项可确保空闲会话不会持有锁过长时间。 + 即使没有持有重要的锁,打开的事务也会阻止清理最近死亡、且可能只对该事务可见的元组;因此长时间空闲可能造成表膨胀。 + 更多详情参见 @@ -8469,9 +8431,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 终止任何空闲的会话(也就是,等待客户端查询),但不在打开的事务中,且超过指定的时间量。 - 如果指定值时不带单位,其单位采用毫秒。 - 零值时(默认)禁用超时。 + 终止不在打开的事务中、且空闲(即等待客户端查询)超过指定时长的任何会话。 + 如果指定值时不带单位,则以毫秒为单位。零值(默认值)禁用此超时。 @@ -8479,8 +8440,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 注意不要对通过连接池软件或其他中间件建立的连接强制执行此超时,因为这样的层可能不会很好地响应意外的连接关闭。 - 只对交互会话启用此超时可能是帮助的,也许只对特定用户应用它。 + 应谨慎对通过连接池软件或其他中间件建立的连接强制执行此超时,因为这样的层可能不会很好地响应意外的连接关闭。 + 只对交互会话启用此超时可能有所帮助,也许只对特定用户应用它。 @@ -8514,7 +8475,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这里的实际选择都是根据爱好做出的,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码将比 base64 编码更大。 + 这里的实际选择主要取决于偏好,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码会比 base64 编码略大。 @@ -8535,7 +8496,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当在XML和字符串值之间进行转换时,无论设置DOCUMENT或 CONTENT都是隐式的。可参阅Section 8.13。 有效值是DOCUMENT和CONTENT。 缺省值是CONTENT。当在 XML 和字符串值之间进行转换时,设置DOCUMENTCONTENT都是隐式的。详见。有效值是DOCUMENTCONTENT。默认值是CONTENT。 + 设置在 XML 与字符串值之间进行转换时,隐含采用DOCUMENT还是CONTENT。 + 有关说明参见。有效值是DOCUMENTCONTENT。默认值是CONTENT @@ -8570,7 +8532,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; createrole_self_grant (string) - createrole_self_grant配置参数 + createrole_self_grant + 配置参数 @@ -8579,9 +8542,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 该值必须是setinherit或它们的逗号分隔列表。默认值为空字符串,这会禁用此功能。 - 此选项的目的是允许非超级用户的CREATEROLE用户自动继承或自动获得对新创建角色执行SET ROLE的能力。 + 此选项的目的是允许非超级用户的CREATEROLE用户自动继承所创建用户的权限,或自动获得对这些用户执行SET ROLE的能力。 由于CREATEROLE用户始终会隐式获得其所创建角色的ADMIN OPTION,因此该用户总是可以通过执行GRANT语句达到相同效果,但自动授予在可用性上更方便。 - 超级用户会自动继承每个角色的权限,并且始终可以切换到任何角色;此设置可让CREATEROLE用户对其创建的用户获得类似的行为。 + 超级用户会自动继承每个角色的权限,并且始终可以对任何角色执行SET ROLE;此设置可让CREATEROLE用户对其创建的用户获得类似的行为。 @@ -8589,7 +8552,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; event_triggers (boolean) - event_triggers配置参数 + event_triggers + 配置参数 @@ -8604,7 +8568,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; restrict_nonsystem_relation_kind (string) - restrict_nonsystem_relation_kind配置参数 + restrict_nonsystem_relation_kind + 配置参数 @@ -8619,7 +8584,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 区域和格式化 + 区域设置和格式化 @@ -8633,7 +8598,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域行为的设置初始化配置文件。 + 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域设置行为的设置初始化配置文件。 @@ -8648,11 +8613,14 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置间隔值的显示格式。值sql_standard将产生匹配 SQL 标准间隔文本的输出。当参数被设置为ISO时,值postgres(默认)将产生匹配PostgreSQL发行 8.4 之前的输出。当DateStyle参数被设置为非ISO输出时,值postgres_verbose会产生匹配PostgreSQL发行 8.4 之前的输出。值iso_8601会产生匹配在 ISO 8601 的 4.4.3.2 节中定义的带标志符格式的时间间隔的输出。 + 设置时间间隔值的显示格式。值sql_standard会生成符合SQL标准时间间隔字面量的输出。 + 值postgres(默认值)的输出与PostgreSQL 8.4 之前版本中设为ISO时的输出一致。 + 值postgres_verbose的输出与PostgreSQL 8.4 之前版本中DateStyle设为非ISO输出时的输出一致。 + 值iso_8601会生成符合 ISO 8601 第 4.4.3.2 节定义的时间间隔带标志符格式的输出。 - IntervalStyle参数也可以影响对有歧义的间隔输入的解释。详见。 + IntervalStyle参数也会影响对有歧义的时间间隔输入的解释。详见 @@ -8684,7 +8652,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置服务器接受的日期时间输入中使用的时区缩写集合。默认值为'Default', 这个集合在全世界大多数地方都能工作。也还有'Australia''India',以及可能为一种特定安装定义的其他集合。详见。 + 设置服务器在日期时间输入中接受的额外时区缩写集合(除当前TimeZone设置所定义的缩写之外)。默认值为'Default', 这个集合在全世界大多数地方都能工作。也还有'Australia''India',以及可能为一种特定安装定义的其他集合。详见 @@ -8710,23 +8678,23 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 如果值为1(默认值)或更高,浮点值被输出为最短-精度格式;参见。 + 如果值为 1(默认值)或更高,浮点值被输出为最短精确格式;参见。 实际生成的位数只取决于输出的值,而不取决于此参数的值。 - float8 值最多需要 17 位数字,float4值最多需要9位数字。 + float8 值最多需要 17 位数字,float4值最多需要9位数字。 这种格式既快速又精确,在正确读取时精确地保留了原始的二进制浮点值。为了历史兼容性,允许的值最大为3。 如果值为零或负,则输出四舍五入为给定的十进制精度。 - 使用的精度是根据此参数的值减小的类型((FLT_DIGDBL_DIG,视情况而定)的标准位数。 + 所用精度以该类型的标准位数(根据类型使用FLT_DIGDBL_DIG)为基础,再按此参数的值减少。 (例如,指定 -1 将导致float4 值输出四舍五入为 5 位有效数字,而float8值四舍五入为 14 位。) - 此格式较慢,不会保留二进制浮点值的所有位,但可能令人更易于阅读。 + 此格式较慢,不会保留二进制浮点值的所有位,但可能更便于阅读。 此参数的含义,以及其默认值,在 PostgreSQL 12 中发生了变化; - 参见 以便进一步讨论。 + 参见 了解进一步讨论。 @@ -8762,7 +8730,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 在一些系统上,这个区域分类并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 + 在一些系统上,这个区域设置类别并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 @@ -8781,7 +8749,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化货币量的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化货币量的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -8796,7 +8764,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化数字的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化数字的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -8811,7 +8779,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化日期和时间的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化日期和时间的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -8843,7 +8811,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 选择被那些没有显式参数指定配置的文本搜索函数变体使用的文本搜索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配区域的配置,initdb将用对应于选中的lc_ctype区域的设置初始化配置文件。 + 选择被那些没有显式参数指定配置的文本检索函数变体使用的文本检索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配该区域设置的配置,initdb将用对应于选中的lc_ctype区域设置的值初始化配置文件。 @@ -8858,7 +8826,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 为了载入附加的功能或者达到提高性能的目的,可用多个设置来预先载入共享库到服务器中。 - 例如'$libdir/mylib'设置可能会导致mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 + 例如'$libdir/mylib'设置会使mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 @@ -8867,12 +8835,12 @@ SET XML OPTION { DOCUMENT | CONTENT }; 只有特别为与PostgreSQL一起使用设计的共享库才能以这种方式载入。每一个PostgreSQL支持 - 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非PostgreSQL无法 + 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非 PostgreSQL 库无法 以这种方式被载入。你可能可以使用操作系统的工具(如LD_PRELOAD)载入它。 - 总之,请参考特定模块的文档来用推荐的方法载入它。 + 一般来说,请参考特定模块的文档来用推荐的方法载入它。 @@ -8906,9 +8874,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 这个特性的目的是允许非特权用户在特定的会话中载入正在调试的或者性能度量库, - 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客 - 户端的PGOPTIONS环境变量或者 + 这个特性的目的是允许非特权用户在特定的会话中载入用于调试或性能测量的库, + 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客户端的PGOPTIONS环境变量或者 ALTER ROLE SET来设置这个参数。 @@ -8946,7 +8913,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 不同,相对于在库被第一次使用 - 时载入它,在会话开始时载入库并没有什么性能优势。不过,当使用连接池时这样做还是有一些 + 时载入它,在会话开始时载入库并没有明显的性能优势。不过,当使用连接池时这样做还是有一些 优势。 @@ -8986,9 +8953,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 在 Windows 主机上,在服务器启动时预载入一个库并不会减少启动每个新服务器进程所需的 - 时间;每一个服务器进程将会重新载入预载入的库。不过,对于那些要在postmaster启动时 + 时间;每一个服务器进程将会重新载入所有预载入的库。不过,对于那些要在postmaster启动时 执行操作的库来说,Windows 主机上的 - shared_preload_libraries任然有用。 + shared_preload_libraries仍然有用。 @@ -9036,13 +9003,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 如果需要打开一个可以动态装载的模块并且在CREATE FUNCTIONLOAD命令中指定的文件名没有目录部分(即名字中不包含斜线),那么系统将搜索这个路径以查找所需的文件。 - - dynamic_library_path的值必须是一个冒号分隔(或者在 Windows 上以分号分隔)的绝对目录路径的列表。如果一个列表元素以特殊字符串开始,$libdir会被替换为PostgreSQL包中已编译好的库目录。这里是PostgreSQL发布提供的模块被安装的位置(使用pg_config --pkglibdir来找到这个目录的名字)。例如: - + 参数dynamic_library_path的值必须是由冒号(Windows上为分号)分隔的绝对目录路径列表。如果某个列表元素以特殊字符串$libdir开头,则会使用编译时确定的PostgreSQL软件包的库目录来替换$libdir;该目录是标准PostgreSQL发行版所提供模块的安装位置。(使用pg_config --pkglibdir可以找出此目录的名称。)例如: dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir' - - 或者在 Windows 环境中: - +或者,在 Windows 环境中: dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' @@ -9117,7 +9080,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - GIN 索引返回的集合尺寸的软上限。详见。 + GIN 索引扫描返回的集合尺寸的软上限。详见 @@ -9150,18 +9113,18 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 这是在锁上等待的时间,然后再检查是否存在死锁条件。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 + 指定在检查是否发生死锁之前等待锁的时间。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 我们乐观地假设在生产应用程序中死锁并不常见,所以在检查死锁之前只是等待一段时间。 增加此值会减少在不必要的死锁检查中浪费的时间,但会减慢实际死锁错误的报告速度。 如果未指定单位,则将其视为毫秒。 - 默认值为一秒(1s),这可能是您在实践中想要的最小值。 - 在负载较重的服务器上,您可能希望提高它。 - 理想情况下,设置应超过您的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 + 默认值为一秒(1s),这可能是你在实践中想要的最小值。 + 在负载较重的服务器上,你可能希望提高它。 + 理想情况下,设置应超过你的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 只有超级用户和具有适当SET权限的用户才能更改此设置。 - 当被设置时,这个参数还可以决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 + 当被设置时,这个参数也决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 @@ -9210,7 +9173,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 这个参数控制在谓词锁被提升为覆盖整个关系之前,该谓词锁能够在单个关系上锁住多少页面或元组。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个关系之前,可以对单个关系中的多少页面或元组加谓词锁。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -9225,7 +9188,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 这个参数控制在谓词锁被提升为覆盖整个页面之前,该谓词锁能在单一页面上锁住多少行。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个页面之前,可以对单个页面中的多少行加谓词锁。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -9253,7 +9216,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个空数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。对于那些要求旧行为的应用的向后兼容性,这个变量可以被设置为off。 + 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个值为空值的数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。为了向后兼容那些要求旧行为的应用,这个变量可以被设置为off @@ -9273,11 +9236,11 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 这个参数控制转义字符串语法(E'...')中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\。如果客户端代码没有做到正确转义,那么将会导致 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 + 这个参数控制转义字符串语法(E'...')中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\。如果客户端代码没有做到正确转义,那么就可能遭到 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 - 注意在普通字符串文本中,\就表示\。这个参数只影响转义字符串语法的处理。 + 注意在普通字符串字面量中,\就表示\。这个参数只影响转义字符串语法的处理。 @@ -9300,7 +9263,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 设置这个参数不会禁用所有与大对象相关的安全检查 — 除了那些在PostgreSQL 9.0中已经修改了的默认行为。 + 设置此变量不会禁用所有与大对象相关的安全检查 — 只禁用那些在PostgreSQL 9.0 中默认行为发生变化的检查。 @@ -9323,7 +9286,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' standard_conforming_strings (boolean) - 字符串标准符合 + 字符串符合标准 standard_conforming_strings配置参数 @@ -9331,7 +9294,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 从PostgreSQL 19 开始,这个参数始终为on。字符串文本始终按照 SQL 标准解析(即反斜线在字符串文本中是普通字符)。这个参数继续保留,是因为应用可能会查询它;但它不能被设为off。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 + 从PostgreSQL 19 开始,这个参数始终为on。字符串字面量始终按照 SQL 标准解析(即反斜线在字符串字面量中是普通字符)。这个参数继续保留,是因为应用可能会查询它;但它不能被设为off。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 @@ -9346,7 +9309,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询来,这样的扫描会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on。 + 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询,这样的扫描可能会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on @@ -9370,15 +9333,15 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr得出空值值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空(未知)。因此这个参数默认为off。 + 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr计算结果为空值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空值(未知)。因此这个参数默认为off - 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释)。它们不是非常有用并且在普通应用中也不常见,在应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及 空值的表达式的语义上感到困惑,因此这个选项默认为关闭。 + 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释),它们不是非常有用并且在普通应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及空值的表达式语义感到困惑,因此这个选项默认为关闭。 - 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不是劣质程序的一般修复。 + 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不能普遍修复错误的程序写法。 @@ -9454,7 +9417,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 当被设置为开(on),PostgreSQL将在一次后端崩溃后自动重新初始化。 + 当设置为 on(默认值)时,PostgreSQL将在一次后端崩溃后自动重新初始化。 让这个值设置为开(on)通常是将数据库可用性最大化的最佳方法。但是在某些环境中,例如PostgreSQL被集群软件调用时,禁用重启可能很有用,这样集群软件可以得到控制并且采取它认为适当的行动。 @@ -9474,7 +9437,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 如果设置为关(off),PostgreSQL在将修改的数据文件刷新到文件系统失败时,将引发PANIC级错误。 + 当设置为 off(默认值)时,PostgreSQL在将修改后的数据文件刷盘到文件系统失败时,将引发PANIC级错误。 这样会导致数据库服务器崩溃。这个参数只能在服务器启动时被设置。 @@ -9483,8 +9446,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 如果设置为开(on),PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷新操作。 - 仅在调查操作系统假如回写失败时对缓冲数据的处理方式的情况下,才将其设置为开(on)。 + 如果设置为开(on),PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷盘操作。 + 只有在调查清楚操作系统在回写失败时如何处理缓冲数据之后,才应将其设置为开(on)。 @@ -9501,14 +9464,14 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' 当设置为fsync,也就是默认值,PostgreSQL将在崩溃恢复开始之前递归地打开并同步数据目录中的所有文件。 对文件的搜索将遵循WAL目录和每个配置表空间的符号链接(而不是任何其它符号链接)。 - 这是为了确保在重现更改之前,所有WAL和数据文件都持久地存储在硬盘上。 - 这适用于在启动没有完全关闭的数据库集簇时,包括由pg_basebackup创建的副本。 + 这是为了确保在重放更改之前,所有WAL和数据文件都持久地存储在磁盘上。 + 这适用于每次启动未正常关闭的数据库集簇时,包括由pg_basebackup创建的副本。 - 在Linux上,可以用syncfs代替,请求操作系统来同步包含数据目录的整个文件系统,WAL文件和每个表空间(但不是通过符号链接可访问到的任何其他文件系统)。 + 在Linux上,可以用syncfs代替,请求操作系统来同步数据目录、WAL 文件和各个表空间所在的文件系统(但不是通过符号链接可访问到的任何其他文件系统)。 这可能比fsync设置快得多,因为它不需要逐个打开每个文件。 - 另一方面,如果一个文件系统是被其他需要修改大量文件的应用程序共享的,它可能会慢一些,因为这些文件也将写入硬盘。 + 另一方面,如果一个文件系统是被其他需要修改大量文件的应用程序共享的,它可能会慢一些,因为这些文件也将写入磁盘。 此外,在5.8之前的Linux版本中,向磁盘写入数据时遇到的I/O错误可能不会报告给PostgreSQL,相关的错误消息可能只出现在内核日志中。 @@ -9527,11 +9490,10 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' 预置选项 - 下列参数是只读的。 - 同样,它们被排除在postgresql.conf文件示例之外。 - 这些选项报告特定应用可能感兴趣的多种PostgreSQL行为,特别是管理前端相关的行为。 - 所有这些都是在PostgreSQL被编译或者它被安装时决定的。 - + 下列参数是只读的,因此未列入示例 postgresql.conf 文件。 + 这些选项报告 PostgreSQL 行为的各个方面,某些应用(特别是管理前端)可能对此感兴趣。 + 其中大多数参数在编译或安装 PostgreSQL 时确定。 + @@ -9575,9 +9537,9 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 在Unix系统上,这个参数报告启动时的数据目录(由定义)的权限。 + 在 Unix 系统上,这个参数报告服务器启动时数据目录(由定义)的权限。 (在Microsoft Windows上这个参数将总是显示0700。) - 更多信息请参考。 + 更多信息请参考initdb 选项。 @@ -9663,7 +9625,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告PostgreSQL是否在编译时打开了 64 位整数日期和时间。从PostgreSQL 10起,这个值总是on。 + 报告PostgreSQL是否在编译时启用了对 64 位整数日期和时间的支持。从PostgreSQL 10起,这个值总是on @@ -9679,9 +9641,9 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' 报告服务器当前是否处于热备模式。 - 当这个是on的时候,所有的事务强制为只读。 - 在会话中,这个只能在服务器提升为主库的时候变更。 - 更多信息参见 + 当此值为 on 时,所有事务都被强制为只读。 + 在会话中,此值只有在服务器被提升为主库时才会改变。 + 更多信息参见 @@ -9695,7 +9657,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定的。默认值是 100 个参数。 + 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定。默认值是 100 个参数。 @@ -9710,7 +9672,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64 ;因此max_identifier_length的默认值是 63,但是在使用多字节编码时可以少于 63 个字符。 + 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64;因此max_identifier_length的默认值是 63 字节,在使用多字节编码时,这可能不足 63 个字符。 @@ -9786,7 +9748,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告服务器版本数值。它是由编译服务器时的PG_VERSION值决定的。 + 报告服务器的版本号。它是由编译服务器时的PG_VERSION值决定的。 @@ -9801,7 +9763,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告服务器版本数值的整数值。它是由编译服务器时的PG_VERSION_NUM值决定的。 + 以整数形式报告服务器的版本号。它是由编译服务器时的PG_VERSION_NUM值决定的。 @@ -9816,7 +9778,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告主共享内存区域的大小,四舍五入到最接近的兆字节。 + 报告主共享内存区域的大小,向上取整到整数兆字节。 @@ -9853,8 +9815,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告此PostgreSQL服务器已构建的 SSL 库的名称(即使此实例当前未配置或使用 SSL), - 例如OpenSSL,或一个空字符串(如果没有)。 + 报告此PostgreSQL服务器在构建时使用的 SSL 库的名称(即使此实例当前未配置或使用 SSL), + 例如OpenSSL,如果没有使用 SSL 库,则报告空字符串。 @@ -9897,11 +9859,11 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' 自定义选项 - 这个特性被设计用来由附加模块向PostgreSQL添加通常不为系统知道的参数(例如过程语言)。这允许使用标准方法配置扩展模块。 + 这个特性允许附加模块(例如过程语言)向PostgreSQL添加系统通常不认识的参数。这样便能以标准方式配置扩展模块。 - 自定义选项有两部分名称:一个扩展名,然后是一个句点,再然后是正确的参数名,就像 SQL 中的合格名称。一个示例是plpgsql.variable_conflict。 + 自定义选项的名称由两部分组成:扩展名称和参数名本身,中间用句点分隔,类似于 SQL 中的限定名。例如plpgsql.variable_conflict @@ -9909,7 +9871,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' PostgreSQL将接受任何两部分参数名称的设置。 这些变量被视为占位符,在定义它们的模块加载之前没有任何功能。 当加载扩展模块时,它将添加其变量定义并根据这些定义转换任何占位符值。 - 如果存在以其扩展名开头的任何未识别的占位符,将发出警告并删除这些占位符。 + 如果存在以其扩展名称开头的任何未识别的占位符,将发出警告并删除这些占位符。 @@ -9918,11 +9880,10 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' 开发者选项 - 下面的参数目的是用在开发测试上, 并且永远不能用于生产数据库。 - 但是,它们中的一些能够用于帮助恢复严重损坏的数据库。 - 同样,它们被从示例postgresql.conf文件中排除。 - 请注意许多这些参数要求特殊的源代码编译标志才能工作。 - + 以下参数用于开发者测试,切勿用于生产数据库。不过,其中一些参数可用于辅助恢复严重损坏的数据库。 + 因此,它们未列入示例postgresql.conf文件。 + 请注意,许多参数需要特殊的源代码编译标志才能起作用。 + @@ -9935,7 +9896,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 允许将表空间创建为pg_tblspc内的目录,当CREATE TABLESPACE命令提供空位置字符串时。 + 当向CREATE TABLESPACE命令提供空的位置字符串时,允许将表空间创建为pg_tblspc内的目录。 这旨在允许测试主库和备库在同一台机器上运行的复制场景。这样的目录可能会混淆备份工具,因为这些工具期望在该位置只找到符号链接。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -9952,8 +9913,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 允许修改系统表的结构以及对系统表进行某些其他风险操作。即使对于超级用户,这也通常是不允许的。 - 不明智地使用此设置可能导致无法检索的数据丢失或严重损坏数据库系统。 + 允许修改系统表的结构以及对系统表进行某些其他风险操作。否则,即使超级用户也不允许执行这些操作。 + 不明智地使用此设置可能导致无法挽回的数据丢失或严重损坏数据库系统。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -10013,14 +9974,14 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 当设置为1时,每个系统目录缓存条目在第一个可能的机会时失效,不管任何使之无效的事情是否真的发生。 - 作为结果,系统目录的缓存被有效地禁用,因此服务器将运行得非常缓慢。 - 较高的值递归地运行缓存失效,这样会更慢,而且只用于测试缓存逻辑自身。 + 当设置为1时,每个系统目录缓存条目都会在最早可能的时刻被置为无效,无论是否真的发生了使其失效的事件。 + 这实际上禁用了系统目录缓存,因此服务器将运行得非常缓慢。 + 较高的值递归地运行缓存失效,这样会更慢,而且仅对测试缓存逻辑本身有用。 默认值0选择正常的目录缓存行为。 - 当试图触发涉及并发目录更改的难以复现的错误时,此参数非常有用,但除此之外它不太被需要。 + 当试图触发涉及并发目录更改的难以复现的错误时,此参数非常有用,但除此之外很少需要使用它。 详情请参见源码文件inval.cpg_config_manual.h @@ -10143,7 +10104,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据的时有用。这个参数在会话开始之后不能被更改。 + 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据时有用。这个参数在会话开始之后不能被更改。 @@ -10158,8 +10119,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 执行认证过程后启动新服务器进程时延迟的时间量。这是为了给开发者们一个机会在一个服务器进程上附加一个调试器。 - 如果指定值时没有单位,则以秒为单位。0值(默认值)禁用延迟。这个参数在会话开始之后不能被更改。 + 新服务器进程启动并完成认证过程之后的延迟时间。这旨在给开发者一个机会,用调试器附加到服务器进程上。 + 如果指定值时没有单位,则以秒为单位。零值(默认值)禁用延迟。这个参数在会话开始之后不能被更改。 @@ -10174,8 +10135,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 在新服务器进程分叉后,在进行认证过程之前,延迟的时间量。这是为了给开发者们一个机会在一个服务器进程上附加一个调试器来跟踪认证过程中的不当行为。 - 如果指定值时没有单位,则以秒为单位。0值(默认值)禁用延迟。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 新服务器进程刚刚派生之后、执行认证过程之前的延迟时间。这旨在给开发者一个机会,用调试器附加到服务器进程上,跟踪认证过程中的异常行为。 + 如果指定值时没有单位,则以秒为单位。零值(默认值)禁用延迟。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -10190,7 +10151,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 + 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 @@ -10204,7 +10165,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 如果打开,发出在排序操作中的资源使用的相关信息。只有在编译PostgreSQL时定义了TRACE_SORT宏, 这个参数才可用(不过,当前在默认情况下就定义了TRACE_SORT)。 + 如果开启,输出排序操作中的资源使用信息。 @@ -10219,7 +10180,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。对每一种锁类型,已授权锁和等待锁的计数也会被一起转储。一个日志文件输出的示例如下: + 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。还会转储每种锁类型已授予的锁数、等待的锁数,以及它们的总数。一个日志文件输出的示例如下: LOG: LockAcquire: new: lock(0xb7acd844) id(24688,24696,0,0,0,1) grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0 @@ -10291,7 +10252,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果设置,不会跟踪小于这个 OID 的锁(用于避免在系统表上的输出)。 + 如果设置,不会跟踪 OID 小于此值的表上的锁(用于避免在系统表上的输出)。 @@ -10367,7 +10328,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,被修改的任何缓冲区的整页镜像及其WAL记录都被加入到记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 + 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,与该 WAL 记录相关的所有已修改缓冲区的整页镜像都会被添加到该记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 @@ -10411,10 +10372,10 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 在读取过程中检测到校验和失败通常会导致PostgreSQL报告错误,中止当前事务。 - 将ignore_checksum_failure设置为on会导致系统忽略失败(但仍然报告警告),并继续处理。 - 这种行为可能导致崩溃,传播或隐藏损坏,或其他严重问题。然而,它可能允许您跳过错误, - 并检索可能仍然存在于表中的未损坏的元组,如果块头仍然正常。如果头部损坏,即使启用此选项也会报告错误。 - 默认设置为off。 + 将ignore_checksum_failure设置为 on 会使系统忽略失败(但仍报告警告),并继续处理。 + 这种行为可能导致崩溃、传播或隐藏损坏,或引发其他严重问题。 + 但是,如果块首部仍然正常,它可能允许你跳过错误,检索表中可能仍然存在的未损坏元组。 + 如果首部损坏,即使启用此选项也会报告错误。默认设置为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -10432,7 +10393,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 检测到损坏的页面头通常会导致PostgreSQL报告错误,中止当前事务。 将zero_damaged_pages设置为on会导致系统报告警告,将内存中的损坏页面清零,并继续处理。 - 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许您跳过错误,并从表中可能存在的未损坏页面中检索行。 + 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许你跳过错误,并从表中可能存在的未损坏页面中检索行。 如果由于硬件或软件错误而发生损坏,这对于恢复数据很有用。通常在放弃从表的损坏页面恢复数据的希望之前,不应将其设置为on。 清零的页面不会强制写入磁盘,因此建议在再次关闭此参数之前重新创建表或索引。默认设置为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -10452,9 +10413,9 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 如果设置为 off(默认值),则在恢复期间检测到引用无效页面的 WAL 记录会导致 PostgreSQL 引发 PANIC 级别错误,中止恢复。 将ignore_invalid_pages设置为on会导致系统忽略 WAL 记录中的无效页面引用(但仍报告警告),并继续恢复。 - 此行为可能会导致崩溃、数据丢失、传播或隐藏腐败,或其他严重问题。 - 但是,它可能允许你通过 PANIC 级错误,完成恢复,并启动服务器。 - 参数只能在服务器启动时设置。它仅在恢复期间或待机模式下生效。 + 此行为可能会导致崩溃、数据丢失、传播或隐藏损坏,或其他严重问题。 + 但是,它可能允许你跳过 PANIC 级错误,完成恢复,并启动服务器。 + 参数只能在服务器启动时设置。它仅在恢复期间或备库模式下生效。 @@ -10469,9 +10430,8 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果LLVM有所需要的功能,用GDB注册所生成的函数。这会让调试更加容易。 - 默认设置是off。只有超级用户和具有适当SET权限的用户 - 才能在会话启动时更改此参数,并且在会话期间完全无法更改。 + 如果 LLVM 具有所需的功能,则向GDB注册生成的函数。 + 这会让调试更加容易。默认设置为off。只有超级用户和具有适当SET权限的用户才能在会话开始时更改此参数,并且在会话内完全不能更改它。 @@ -10487,7 +10447,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 将生成的LLVM IR写入文件系统,位于内。 - 这仅对于在JIT实现内部工作时有用。默认设置为off。 + 这仅对开发 JIT 的内部实现有用。默认设置为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -10518,11 +10478,9 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果LLVM有所需的功能,发出需要的数据以允许perf对JIT生成的函数画像。 - 这会写出文件到~/.debug/jit/中,如果需要,由用户负责对其执行清除。 - 默认设置是off。 - 只有超级用户和具有适当SET权限的用户才能在会话启动时更改此参数, - 并且在会话期间完全无法更改。 + 如果 LLVM 具有所需的功能,则输出让perf对 JIT 生成的函数进行性能分析所需的数据。 + 这会将文件写入~/.debug/jit/;用户应在需要时自行清理。 + 默认设置为off。只有超级用户和具有适当SET权限的用户才能在会话开始时更改此参数,并且在会话内完全不能更改它。 @@ -10552,8 +10510,8 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 当设置为on时,这是默认值,PostgreSQL将在后端崩溃后自动删除临时文件。 - 如果禁用,文件将被保留,并且也许可用于调试,例如。 + 当设置为on(默认值)时,PostgreSQL将在后端崩溃后自动删除临时文件。 + 如果禁用,文件将被保留,例如可用于调试。 重复的崩溃可能会导致无用文件的积累。 该参数只能在postgresql.conf文件中或服务器命令行中设置。 @@ -10605,11 +10563,11 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 允许值为bufferedimmediate。默认值为buffered。 这个参数旨在用于测试逻辑解码以及大型事务的复制。 - debug_logical_replication_streaming对发布端和订阅端的影响不同。 + debug_logical_replication_streaming对发布者和订阅者的影响不同。 - 在发布端,debug_logical_replication_streaming允许在逻辑解码中立即流式传输或序列化更改。 + 在发布者端,debug_logical_replication_streaming允许在逻辑解码中立即流式传输或序列化更改。 当设置为immediate时,如果 streaming选项在 CREATE SUBSCRIPTION中已启用, @@ -10618,10 +10576,10 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 在订阅端,如果streaming选项被设置为parallel, - 则debug_logical_replication_streaming可用于控制主应用工作进程是将更改发送到共享内存队列, - 还是将所有更改序列化到文件。设置为buffered时,主进程通过共享内存队列将更改发送给并行应用工作进程。 - 设置为immediate时,主进程会将所有更改序列化到文件,并通知并行应用工作进程在事务结束时读取并应用这些更改。 + 在订阅者端,如果streaming选项被设置为parallel, + 则debug_logical_replication_streaming可用于控制领导者应用工作进程是将更改发送到共享内存队列, + 还是将所有更改序列化到文件。设置为buffered时,领导者通过共享内存队列将更改发送给并行应用工作进程。 + 设置为immediate时,领导者会将所有更改序列化到文件,并通知并行应用工作进程在事务结束时读取并应用这些更改。 @@ -10633,12 +10591,12 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 短选项 - 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,并且它们作为一个单字母选项存在并不表示它们会被大量使用。 + 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,它们以单字母选项的形式存在,并不一定表示鼓励频繁使用这些选项。
- 短选项键 + 短选项对照 diff --git a/zh/19/datatype.sgml b/zh/19/datatype.sgml index b0d3f18f..0d30690a 100644 --- a/zh/19/datatype.sgml +++ b/zh/19/datatype.sgml @@ -151,7 +151,7 @@ line - 平面上的无限长的线 + 平面上的无限直线 @@ -163,19 +163,19 @@ macaddr - MAC(Media Access Control)地址 + MAC(媒体访问控制)地址 macaddr8 - MAC(Media Access Control)地址(EUI-64格式) + MAC(媒体访问控制)地址(EUI-64格式) money - 货币数量 + 货币额 @@ -183,7 +183,7 @@ s) ] decimal [ (p, s) ] - 可选择精度的精确数字 + 可选择精度的精确数值 @@ -195,7 +195,7 @@ pg_lsn - PostgreSQL日志序列号类型 + PostgreSQL 日志序列号 @@ -273,13 +273,13 @@ tsquery - 文本搜索查询 + 文本检索查询 tsvector - 文本搜索文档 + 文本检索文档 @@ -420,14 +420,14 @@
- 数字类型常量的语法在里描述。数字类型有一整套对应的数学操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 + 数字类型常量的语法在里描述。数字类型有一整套对应的算术操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 整数类型 - 整数 + integer @@ -440,7 +440,7 @@ int4 - 整数 + integer @@ -460,11 +460,11 @@
- 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。而只有在integer的范围不够的时候才使用bigint。 + 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。bigint则设计用于integer的范围不够的情况。 - SQL只声明了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在许多其它SQL数据库系统中使用。 + SQL只规定了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在某些其他SQL数据库系统中使用。 @@ -473,11 +473,11 @@ 任意精度数值 - 数字(数据类型) + numeric(数据类型) - 任意精度数字 + 任意精度数值 @@ -578,18 +578,18 @@ NUMERIC(3, 5)
- infinity - numeric (数据类型) + 无穷大 + numeric(数据类型) NaN - 非数字 + 非数 - 非数字 - 数字(数据类型) + 非数 + numeric(数据类型) @@ -676,7 +676,7 @@ FROM generate_series(-3.5, 3.5, 1) AS x; - 双精度 + double precision @@ -686,7 +686,7 @@ FROM generate_series(-3.5, 3.5, 1) AS x; float8 - 双精度 + double precision @@ -739,8 +739,7 @@ FROM generate_series(-3.5, 3.5, 1) AS x; 默认情况下,浮点值会以最短且精确的十进制表示形式输出; - 生成的十进制值比同一二进制精度下任何其他可表示值都更接近真实 - 存储的二进制值。(不过,为了避免输入例程普遍存在的一个错误, + 所生成的十进制值与实际存储的二进制值之间的距离,小于它与任何其他可用相同二进制精度表示的值之间的距离。(不过,为了避免输入例程普遍存在的一个错误, 即未能正确遵守舍入到最近偶数规则,当前输出值绝不会 恰好位于两个可表示值的正中间。) 对于float8值,最多使用 17 位有效十进制数字; @@ -749,14 +748,14 @@ FROM generate_series(-3.5, 3.5, 1) AS x; - 生成这种最短且精确的输出格式,比历史上的圆整格式要快得多。 + 生成这种最短且精确的输出格式,比历史上的舍入格式要快得多。 为了兼容旧版本PostgreSQL生成的输出, 并允许降低输出精度,可以使用 - 参数改为选择圆整后的 + 参数改为选择舍入后的 十进制输出。将该参数设置为 0 会恢复之前的默认行为,也就是把值 舍入为 6 位(对于float4)或 15 位 (对于float8)有效十进制数字。设置为负值会 @@ -770,7 +769,7 @@ FROM generate_series(-3.5, 3.5, 1) AS x; - 过去那些需要精确值的应用,往往必须把 + 过去那些需要精确值的应用,必须把 设置为 3 才能获得它们。 为了在版本之间获得最大兼容性,这类应用应继续这样做。 @@ -778,12 +777,12 @@ FROM generate_series(-3.5, 3.5, 1) AS x; 无穷大 - 浮点型 + 浮点 - 非数字 - 浮点型 + 非数 + 浮点 @@ -855,13 +854,13 @@ FROM generate_series(-3.5, 3.5, 1) AS x; - auto-increment + 自动递增 serial - sequence - and serial type + 序列 + 与 serial 类型 @@ -914,7 +913,7 @@ ALTER SEQUENCE tablename_ - 要向 serial 列插入序列中的下一个值,应指定让该列 + 要向 serial 列插入序列中的下一个值,应指定让serial列 使用其默认值。这既可以通过在 INSERT 语句的 列表中省略该列来实现,也可以通过使用 DEFAULT 关键字来实现。 @@ -990,7 +989,7 @@ ALTER SEQUENCE tablename_ SELECT '12.34'::float8::numeric::money; - 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有圆整错误。 + 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有舍入误差。 @@ -1002,7 +1001,7 @@ SELECT '52093.89'::money::numeric::float8; 一个 money 值除以一个整数值时,会朝零方向截去小数 - 部分。要得到圆整结果,可以除以一个浮点值,或者在除法前先把 + 部分。要得到舍入后的结果,可以除以一个浮点值,或者在除法前先把 money 转换为 numeric,再在除法后转换回 money(如果要避免精度丢失风险,后一种做法更好)。 当一个 money 值被另一个 money 值除时, @@ -1021,12 +1020,12 @@ SELECT '52093.89'::money::numeric::float8; - string + 字符串 - 字符 + character @@ -1065,11 +1064,11 @@ SELECT '52093.89'::money::numeric::float8; character(n), char(n), bpchar(n) - 定长,空白填充 + 定长,空格填充 bpchar - 无限长度的变长,忽略尾随空白 + 无限长度的变长,忽略尾随空格 text @@ -1128,7 +1127,7 @@ SELECT '52093.89'::money::numeric::float8; 超过 10,485,760。若 character varying (或 varchar)没有长度说明,则该类型接受任意长度 的字符串。若 bpchar 没有长度说明,它也接受任意 - 长度的字符串,但尾随空白在语义上不重要。若 + 长度的字符串,但尾随空格在语义上不重要。若 character(或 char)缺少长度说明, 则等同于 character(1) @@ -1150,7 +1149,7 @@ SELECT '52093.89'::money::numeric::float8;
- 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储代码为零的字符(有时称为NUL)。有关更多信息,请参阅。 + 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储编码值为零的字符(有时称为NUL)。有关更多信息,请参阅 @@ -1169,7 +1168,7 @@ SELECT '52093.89'::money::numeric::float8; - 这三种类型之间没有性能差别,除了使用空白填充类型时会占用更多存储 + 这三种类型之间没有性能差别,除了使用空格填充类型时会占用更多存储 空间,以及在写入带长度约束的列时需要少量额外 CPU 周期来检查长度。 虽然在某些其他数据库系统中,character(n) 可能有一定性能优势,但在 PostgreSQL @@ -1204,7 +1203,7 @@ INSERT INTO test2 VALUES ('ok'); INSERT INTO test2 VALUES ('good '); INSERT INTO test2 VALUES ('too long'); ERROR: value too long for type character varying(5) -INSERT INTO test2 VALUES ('too long'::varchar(5)); -- explicit truncation +INSERT INTO test2 VALUES ('too long'::varchar(5)); -- 显式截断 SELECT b, char_length(b) FROM test2; b | char_length @@ -1328,7 +1327,7 @@ SELECT b, char_length(b) FROM test2; 开头(以便与转义格式区分)。在某些上下文中,这个开头的反斜线 可能需要通过双写进行转义(见 )。作为输入时,十六进制数字 - 可以使用大写或小写,并且在两个数字组成的一组之间允许出现空白 + 可以使用大写或小写,并且每两个数字组成一组,组与组之间允许出现空白 (但组内以及起始的 \x 序列中不能有空白)。 十六进制格式与大量外部应用和协议兼容,并且通常比转义格式转换得 更快,因此更推荐使用。 @@ -1392,7 +1391,7 @@ SELECT '\xDEADBEEF'::bytea; 0 - 0字节 + 零值字节 '\000' '\000'::bytea \x00 @@ -1537,10 +1536,10 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; time - 不带时区的时间 + time without time zone - 带时区的时间 + time with time zone timestamp @@ -1549,13 +1548,13 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; timestamptz - 带时区的时间戳 + timestamp with time zone - 不带时区的时间戳 + timestamp without time zone - 间隔 + interval 时间跨度 @@ -1639,7 +1638,7 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; - SQL 要求仅写 timestamp 时,应等效于 + SQL 标准要求仅写 timestamp 时,应等效于 timestamp without time zone,而 PostgreSQL 也遵循这种行为。 timestamptz 被接受为 @@ -1720,7 +1719,7 @@ MINUTE TO SECOND 其中 p 是可选的精度说明,给出秒字段中 保留的小数位数。精度可用于 timetimestampinterval 类型, - 范围是 0 到 6。这与前文描述的取值一致。如果在常量声明中没有指定 + 范围是 0 到 6。如果在常量声明中没有指定 精度,则默认采用该字面值本身的精度(但不超过 6 位)。 @@ -1749,7 +1748,7 @@ MINUTE TO SECOND 1999-01-08 - ISO 8601; 任何模式下的1月8日 + ISO 8601; 任何模式下的1月8日 (推荐格式) @@ -1785,27 +1784,27 @@ MINUTE TO SECOND 99-Jan-08 - YMD模式中的1月8日,否则错误 + YMD模式中的1月8日,否则报错 08-Jan-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 Jan-08-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 19990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 1999.008 - 年和一年中的日子 + 年和一年中的第几天 J2451187 @@ -1827,10 +1826,10 @@ MINUTE TO SECOND time - 无时区的时间 + time without time zone - 带时区的时间 + time with time zone @@ -1907,11 +1906,11 @@ MINUTE TO SECOND 040506+0730 - ISO 8601,以分数小时形式给出 UTC 偏移 + ISO 8601,时区的 UTC 偏移不是整小时 040506+07:30:00 - UTC偏移量指定为秒(ISO 8601中不允许) + UTC 偏移精确到秒(ISO 8601中不允许) 04:05:06 PST @@ -1988,11 +1987,11 @@ MINUTE TO SECOND - 带时区的时间戳 + timestamp with time zone - 无时区的时间戳 + timestamp without time zone @@ -2017,29 +2016,12 @@ January 8 04:05:06 1999 PST 也被支持。 - - SQL 标准通过时间后面是否带有 - +- 符号以及时区偏移,来区分 - timestamp without time zone 和 - timestamp with time zone 常量。因此,根据标准, - - + 按照SQL标准,timestamp without time zonetimestamp with time zone字面量的区别在于,时间后是否有+-符号及其后的时区偏移。因此,按照该标准, TIMESTAMP '2004-10-19 10:23:54' - - - 属于 timestamp without time zone,而 - - +timestamp without time zone,而 TIMESTAMP '2004-10-19 10:23:54+02' - - - 属于 timestamp with time zone。 - PostgreSQL 在确定字符串类型之前从不检查 - 其内容,因此会把上述两个值都视为 - timestamp without time zone。要确保一个常量被视为 - timestamp with time zone,应为其指定正确的显式类型: - - +timestamp with time zone。 + PostgreSQL在确定字符串字面量的类型之前,从不检查其内容,因此会把上述两者都视为timestamp without time zone。为确保字面量被视为timestamp with time zone,应为它显式指定正确类型: TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' @@ -2085,12 +2067,12 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' time - constants + 常量 date - constants + 常量 @@ -2191,13 +2173,13 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' date 输出格式 - formatting + 格式化 time 输出格式 - formatting + 格式化 @@ -2230,7 +2212,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' ISO - ISO 8601, SQL标准 + ISO 8601,SQL 标准 1997-12-17 07:37:16-08 @@ -2261,7 +2243,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' - SQL和POSTGRES风格中,如果DMY域顺序被指定,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。 + SQL和POSTGRES风格中,如果指定了 DMY 字段顺序,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。 @@ -2331,7 +2313,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 时区 - time zone + 时区 @@ -2416,8 +2398,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 除了时区名称和缩写之外, PostgreSQL 还接受 POSIX 风格的 时区说明,见 。 - 这个选项通常不如使用具名时区更合适,但如果没有可用的 IANA - 时区条目,它可能就是必需的。 + 这个选项通常不如使用具名时区更合适,但如果没有合适的 IANA 时区条目可用,它可能就是必需的。 @@ -2460,7 +2441,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 时区名称和缩写并不是硬编码在服务器中的;它们来自安装目录下 .../share/timezone/ 和 - .../share/timezonesets/ 子目录中的数据 + .../share/timezonesets/ 子目录中的配置文件 (见 )。 @@ -2498,13 +2479,13 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' - interval值可以使用下列语法书写: + interval值可以使用下列详细语法书写: @ quantity unit quantity unit... direction - 其中quantity是一个数字(很可能是有符号的); + 其中quantity是一个数字(可以带有符号); unitmicrosecondmillisecondsecondminutehourday、 @@ -2538,7 +2519,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' P quantity unit quantity unit ... T quantity unit ... 字符串必须以 P 开头,并且可以包含一个 - T 来引出一天中时间单位。可用的单位缩写见 + T 来引出一天中的时间单位。可用的单位缩写见 。单位可以省略, 也可以按任意顺序出现,但小于一天的单位必须出现在 T 之后。特别是,M 的含义 @@ -2577,7 +2558,7 @@ P quantity unit M - 分钟 (在时间部分中) + 分钟(在时间部分中) S @@ -2682,7 +2663,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; P1Y2M3DT4H5M6S - 带标志符的ISO 8601 格式:含义同上 + ISO 8601 带标志符的格式:含义同上 P0001-02-03T04:05:06 @@ -2700,7 +2681,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; interval 输出格式 - formatting + 格式化 @@ -2749,7 +2730,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; iso_8601 风格的输出符合 ISO 8601 标准 - 4.4.3.2 节描述的带标志符格式。 + 4.4.3.2 节描述的带标志符的格式
@@ -2800,7 +2781,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; 布尔类型 - Boolean + 布尔 数据类型 @@ -2911,15 +2892,15 @@ SELECT * FROM test1 WHERE a; 数据类型 - enumerated (enum) + 枚举(enum) - enumerated types + 枚举类型 - 枚举(enum)类型是由一个静态、值的有序集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的日期,或者一个数据的状态值集合。 + 枚举(enum)类型是由一个静态的有序值集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的各天,或者一个数据的状态值集合。 @@ -3028,7 +3009,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 实现细节 - 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空格也是有意义的。 + 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空白也是有意义的。 @@ -3040,7 +3021,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 从内部枚举值到文本标签的翻译被保存在系统目录pg_enum中。可以直接查询该目录。 + 从内部枚举值到文本标签的转换关系被保存在系统目录pg_enum中。直接查询该目录可能会有所帮助。 @@ -3115,7 +3096,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays circle24字节 - <(x,y),r>(中心点和半径) + <(x,y),r>(圆心和半径) @@ -3128,7 +3109,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 我们提供了丰富的函数和操作符来进行各种几何操作,例如缩放、平移、 - 旋转以及计算相交等,详见 。 + 旋转以及求交等,详见 @@ -3139,7 +3120,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 点是几何类型的基本二维构造块。用下面的语法描述point类型的值: + 点是几何类型的基本二维构造块。用下面任一种语法描述point类型的值: ( x , y ) @@ -3155,14 +3136,14 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线 + 直线 line - 线由线性方程Ax + By + C = 0 + 直线由线性方程Ax + By + C = 0 表示,其中AB不能同时为零。类型line 的值采用以下形式输入和输出: @@ -3182,7 +3163,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays (x1,y1)(x2,y2) - 是线上不同的两点。 + 是直线上不同的两点。 @@ -3198,7 +3179,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线段用一对线段的端点来表示。lseg类型的值用下面的语法声明: + 线段用一对线段的端点来表示。lseg类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ( x2 , y2 ) ] @@ -3222,15 +3203,15 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 方框 - box (data type) + box(数据类型) - rectangle + 矩形 - 方框用其对角的点对表示。box类型的值使用下面的语法指定: + 方框用其对角的点对表示。box类型的值使用下面任一种语法指定: ( ( x1 , y1 ) , ( x2 , y2 ) ) @@ -3249,7 +3230,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 在输入时可以提供任意两个对角,但是值将根据需要被按顺序记录为右上角和左下角。 + 在输入时可以提供任意两个对角,但是值将根据需要被重新排列,并依次存储为右上角和左下角。 @@ -3257,7 +3238,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 路径 - path (data type) + path(数据类型) @@ -3265,7 +3246,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - path类型的值用下面的语法声明: + path类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ... , ( xn , yn ) ] @@ -3275,11 +3256,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays x1 , y1 , ... , xn , yn - 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被忽略时,路径将被假定为封闭。 + 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被省略时,路径将被假定为封闭。 - 路径的输出使用第一种或第二种语法。 + 路径的输出视情况使用第一种或第二种语法。 @@ -3303,7 +3284,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - polygon类型的值用下列语法声明: + polygon类型的值用下列任一种语法指定: ( ( x1 , y1 ) , ... , ( xn , yn ) ) @@ -3328,7 +3309,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 圆由一个圆心和一个半径代表。circle类型的值用下面的语法指定: + 圆由一个圆心和一个半径代表。circle类型的值用下面任一种语法指定: < ( x , y ) , r > @@ -3351,7 +3332,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 网络地址类型 - network + 网络 数据类型 @@ -3408,8 +3389,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 在对 inetcidr 数据类型排序时,IPv4 - 地址总是排在 IPv6 地址之前,包括那些封装在 IPv6 地址中或映射到 - IPv6 地址中的 IPv4 地址,例如 ::10.2.3.4 或 + 地址总是排在 IPv6 地址之前,即使后者是封装或映射 IPv4 地址所得的 IPv6 地址,例如 ::10.2.3.4::ffff:10.4.3.2 @@ -3565,7 +3545,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - <type>inet</type> vs. <type>cidr</type> + <type>inet</type> 与 <type>cidr</type> inetcidr 两种数据类型的本质区别在于: @@ -3591,12 +3571,12 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - MAC地址 + MAC 地址 macaddr - macaddr类型存储 MAC 地址,也就是以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: + macaddr类型存储 MAC 地址,例如以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: '08:00:2b:01:02:03' @@ -3630,11 +3610,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays <type>macaddr8</type> - macaddr8 (data type) + macaddr8(数据类型) - MAC地址(EUI-64格式) + MAC 地址(EUI-64 格式) macaddr @@ -3761,31 +3741,31 @@ SELECT * FROM test; - 一个 bit 串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 + 一个位串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 开销,具体取决于串的长度。(不过,长值可能会被压缩或移到行外存储, 与 中对字符串的说明相同。) - 文本搜索类型 + 文本检索类型 - 全文搜索 + 全文检索 数据类型 - 文本搜索 + 文本检索 数据类型 - PostgreSQL 提供了两种专为支持全文搜索而 - 设计的数据类型。所谓全文搜索,是指在一组自然语言 + PostgreSQL 提供了两种专为支持全文检索而 + 设计的数据类型。所谓全文检索,是指在一组自然语言 文档中查找最匹配某个 查询的文档。tsvector 类型以 - 适合文本搜索的优化形式表示文档,tsquery 类型则表示 + 适合文本检索的优化形式表示文档,tsquery 类型则表示 文本查询。关于这一功能的详细解释见 ; 相关函数和操作符的概览见 @@ -3800,7 +3780,7 @@ SELECT * FROM test; tsvector 值是一个排好序且互不重复的 词位(lexeme)列表,这些词已经过 - 规范化,以便把同一单词的不同变体合并起来 + 正规化,以便把同一单词的不同变体合并起来 (详见 )。排序和去重会在输入时自动 完成,如下例所示: @@ -3859,12 +3839,12 @@ SELECT 'a:1A fat:2B,4C cat:5D'::tsvector; 权重通常用于反映文档结构,例如把标题中的词和正文中的词区分开来。 - 文本搜索排序函数可以为不同的权重标记分配不同优先级。 + 文本检索排序函数可以为不同的权重标记分配不同优先级。 必须认识到,tsvector 类型本身并不会执行任何词语 - 规范化;它假定输入的词已经按照应用需求完成规范化。例如: + 正规化;它假定输入的词已经按照应用需求完成正规化。例如: SELECT 'The Fat Rats'::tsvector; @@ -3873,9 +3853,9 @@ SELECT 'The Fat Rats'::tsvector; 'Fat' 'Rats' 'The' - 对于大多数英文全文搜索应用来说,上述词会被视为尚未规范化,但 + 对于大多数英文全文检索应用来说,上述词会被视为尚未正规化,但 tsvector 并不在意。原始文档文本通常应先经过 - to_tsvector,以按搜索需要对词语进行规范化: + to_tsvector,以按检索需要对词语进行正规化: SELECT to_tsvector('english', 'The Fat Rats'); @@ -3964,9 +3944,9 @@ SELECT 'super:*'::tsquery; 引号的使用规则与前面介绍 tsvector 时相同;同样, - 与 tsvector 一样,任何需要的词语规范化都必须在 + 与 tsvector 一样,任何需要的词语正规化都必须在 转换为 tsquery 类型之前完成。to_tsquery - 函数很适合用来实现这种规范化: + 函数很适合用来实现这种正规化: SELECT to_tsquery('Fat:ab & Cats'); @@ -3992,8 +3972,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); ---------------+------------ 'postgradu':1 | 'postgr':* - 因而它能够匹配其带前缀的后继形式 - postgraduate。 + 因而它能够匹配postgraduate 词干化后的形式。 @@ -4011,7 +3990,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); uuid 数据类型用于存储由 RFC 9562、 ISO/IEC 9834-8:2005 及相关标准定义的通用唯一标识符(UUID)。 - (有些系统把这种数据类型称为全局唯一标识符,或 GUID, + (有些系统把这种数据类型称为全局唯一标识符,或 GUID GUID。)这种标识符是一个 128 位的量,由某种算法生成,该算法被设计为使同一算法在已知宇宙中 被其他人生成出相同标识符的概率极低。因此,对于分布式系统而言, @@ -4036,9 +4015,9 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11 - PostgreSQL 也接受其他输入形式:可以使用 - 大写字母、用花括号包围标准格式、忽略部分或全部连字符,或者在任意 - 4 位分组后额外加上连字符。例如: + PostgreSQL 也接受其他输入形式:可以使用 + 大写字母、用花括号包围标准格式、省略部分或全部连字符,或者在任意 + 4 位分组后额外加上连字符。例如: A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11 {a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11} @@ -4149,8 +4128,8 @@ XMLSERIALIZE ( { DOCUMENT | CONTENT } value AS XMLPARSE 或 XMLSERIALIZE 的情况下与 xml 类型互相转换时, 选择 DOCUMENT 还是 CONTENT - 由会话配置参数 XML option - XML option 决定,可以使用 + 由会话配置参数 XML 选项 + XML 选项 决定,可以使用 标准命令设置: SET XML OPTION { DOCUMENT | CONTENT }; @@ -4167,20 +4146,20 @@ SET xmloption TO { DOCUMENT | CONTENT }; 编码处理 - 在客户端、服务器以及其间传输的 XML 数据上处理多字符编码时, + 在客户端、服务器以及其间传输的 XML 数据上处理多种字符编码时, 必须格外小心。使用文本模式向服务器发送查询并把查询结果返回给 - 客户端时,PostgreSQL 会将客户端与 + 客户端时(这是通常使用的模式),PostgreSQL 会将客户端与 服务器之间传输的所有字符数据转换为目标端的字符编码,参见 。这也包括表示 XML 值的字符串,如上例 所示。这通常意味着,由于字符数据在客户端和服务器之间传输时可能被 转换为其他编码,XML 数据中包含的编码声明可能会失效,因为内嵌的 编码声明本身并不会被修改。为处理这种情况,表示 xml 类型输入值的字符串中所包含的编码声明会被 - 忽略,其内容被假定为当前服务器编码。随后, + 忽略,其内容被假定为当前服务器编码。因此, 为了正确处理,客户端发出的 XML 数据字符串必须采用当前客户端编码。 客户端负责在将文档发送给服务器之前把它们转换为当前客户端编码, 或适当调整客户端编码。输出时,xml 类型值不会带有 - 编码声明,而客户端会假定所有数据都采用当前客户端编码。 + 编码声明,而客户端应假定所有数据都采用当前客户端编码。 @@ -4214,7 +4193,7 @@ SET xmloption TO { DOCUMENT | CONTENT }; xml 数据类型有些特殊,因为它不提供任何比较操作符。 这是因为对 XML 数据并不存在良定义且通用的比较算法。其结果是, - 你无法通过把某个 xml 值与搜索值比较来检索行。 + 你无法通过把某个 xml 列与搜索值比较来检索行。 因此,XML 值通常应伴随一个独立的键字段,例如 ID。另一种比较 XML 值的办法,是先把它们转换成字符串;但请注意,字符串比较对 XML 的比较需求通常帮助不大。 @@ -4222,14 +4201,14 @@ SET xmloption TO { DOCUMENT | CONTENT }; 由于 xml 数据类型没有可用的比较操作符,因此无法直接 - 在这种类型上创建索引。如果需要在 XML 中快速搜索,可行方案包括: + 在这种类型的列上创建索引。如果需要在 XML 中快速搜索,可行方案包括: 将表达式转换为字符串类型后为其建立索引,或者为某个 XPath 表达式 建立索引。当然,实际查询也必须相应调整为使用该被索引的表达式。 - PostgreSQL 的文本搜索功能也可用于加速 - XML 数据的全文搜索。不过,目前 PostgreSQL 发行版中仍缺少所需的 + PostgreSQL 的文本检索功能也可用于加速 + XML 数据的全文检索。不过,目前 PostgreSQL 发行版中仍缺少所需的 预处理支持。 @@ -4244,12 +4223,12 @@ SET xmloption TO { DOCUMENT | CONTENT }; 域类型 - domain + - data type - domain + 数据类型 + @@ -4261,13 +4240,13 @@ SET xmloption TO { DOCUMENT | CONTENT }; CREATE DOMAIN posint AS integer CHECK (VALUE > 0); CREATE TABLE mytable (id posint); -INSERT INTO mytable VALUES(1); -- works -INSERT INTO mytable VALUES(-1); -- fails +INSERT INTO mytable VALUES(1); -- 成功 +INSERT INTO mytable VALUES(-1); -- 失败 - 当底层类型的一个操作符或函数适用于一个域值时,域会被自动向下转换为底层类型。因此,mytable.id - 1的结果会被认为是类型integer而不是posint。我们可以写成(mytable.id - 1)::posint来把结果转换回posint,这会导致域的约束被重新检查。在这种情况下,如果该表达式被应用于一个值为1的id就会错误。把底层类型的值赋给域类型的一个字段或者变量不需要写显式的类型转换,但是域的约束将会被检查。 + 当底层类型的一个操作符或函数被应用于一个域值时,域会被自动向下转换为底层类型。因此,mytable.id - 1的结果会被认为是类型integer而不是posint。我们可以写成(mytable.id - 1)::posint来把结果转换回posint,这会导致域的约束被重新检查。在这种情况下,如果该表达式被应用于一个值为1的id就会报错。把底层类型的值赋给域类型的一个字段或者变量不需要写显式的类型转换,但是域的约束将会被检查。 @@ -4358,7 +4337,7 @@ INSERT INTO mytable VALUES(-1); -- fails 对象标识符(OID)在 PostgreSQL 内部被用作 若干系统表的主键。类型 oid 表示一个对象标识符。 - 此外还有若干 oid 的别名类型,统称为 + 此外还有若干 oid 的别名类型,其名称均形如 regsomething 给出了概要说明。 @@ -4441,7 +4420,7 @@ SELECT * FROM pg_attribute regconfig pg_ts_config - 文本搜索配置 + 文本检索配置 english @@ -4455,7 +4434,7 @@ SELECT * FROM pg_attribute regdictionary pg_ts_dict - 文本搜索字典 + 文本检索词典 simple @@ -4491,7 +4470,7 @@ SELECT * FROM pg_attribute regprocedure pg_proc - 函数与参数类型 + 带参数类型的函数 sum(int4) @@ -4527,7 +4506,7 @@ SELECT * FROM pg_attribute - 这些类型的输入函数允许在各个标记之间插入空白,并且会把大写字母 + 这些类型的输入函数允许在各个词元之间插入空白,并且会把大写字母 折叠为小写,双引号内除外;这样做是为了让语法规则更接近 SQL 中 书写对象名的方式。反过来,如果需要让输出成为有效的 SQL 标识符, 输出函数会自动加上双引号。例如,一个名为 Foo @@ -4602,8 +4581,7 @@ WHERE ... 它就会对被引用对象建立依赖。例如,如果某列的默认表达式是 nextval('my_seq'::regclass)PostgreSQL 就会知道该默认表达式依赖于 - 序列 my_seq,因此系统在删除该序列之前,必须先 - 移除该默认表达式。改用 + 序列 my_seq,因此系统不允许在尚未移除该默认表达式时删除序列。改用 nextval('my_seq'::text) 则不会建立依赖。 (regdatabaseregrole 是这一特性的例外:这些类型的常量不允许出现在 存储表达式中。) @@ -4803,7 +4781,7 @@ WHERE ... anyarray - 表示一个函数可以接受任意数组数据类型(参见 + 表示一个函数可以接受任意数组数据类型(参见)。 @@ -4922,7 +4900,7 @@ WHERE ... unknown - 标识一种尚未解析出的类型,例如未修饰的字符串字面值。 + 标识一种尚未解析出的类型,例如未修饰的字符串字面值的类型。 @@ -4940,7 +4918,7 @@ WHERE ... voidrecord 用作结果类型 (如果函数被用作触发器或事件触发器,则也允许 triggerevent_trigger 作为结果类型)。 - 有些语言还支持借助多态伪类型来实现多态函数;详见 + 有些语言还支持借助上面列出的多态伪类型来实现多态函数;详见 diff --git a/zh/19/dict-int.sgml b/zh/19/dict-int.sgml index 50c37473..34269dcd 100644 --- a/zh/19/dict-int.sgml +++ b/zh/19/dict-int.sgml @@ -1,16 +1,16 @@ - dict_int — 用于整数的示例全文搜索词典 + dict_int — 用于整数的示例全文检索词典 dict_int - dict_int是一个全文搜索附加词典模板的示例。 + dict_int是一个全文检索附加词典模板的示例。 引入这个示例词典是为了控制整数(有符号和无符号)的索引, - 使这类数字能够被索引,同时又避免唯一词的数量过度增长, + 使这类数字能够被索引,同时又避免不同词的数量过度增长, 因为那会严重影响搜索性能。 @@ -54,7 +54,7 @@ 用法 - 安装dict_int扩展后,会创建一个文本搜索模板 + 安装dict_int扩展后,会创建一个文本检索模板 intdict_template以及一个基于该模板、使用默认参数的词典 intdict。你可以修改这些参数,例如: @@ -77,7 +77,7 @@ mydb# SELECT ts_lexize('intdict', '12345678'); 但在实际使用中,通常需要像所述那样, - 将它包含到某个文本搜索配置中。可能类似如下: + 将它包含到某个文本检索配置中。可能类似如下: ALTER TEXT SEARCH CONFIGURATION english diff --git a/zh/19/func/func-string.sgml b/zh/19/func/func-string.sgml index 4e1821b3..89033d43 100644 --- a/zh/19/func/func-string.sgml +++ b/zh/19/func/func-string.sgml @@ -480,7 +480,7 @@ 还有其他字符串操作函数和操作符,列在中。 (其中一些用于内部实现中列出的SQL标准字符串函数。) - 此外,中还描述了模式匹配操作符,中则描述了全文搜索操作符。 + 此外,中还描述了模式匹配操作符,中则描述了全文检索操作符。
diff --git a/zh/19/func/func-textsearch.sgml b/zh/19/func/func-textsearch.sgml index 56953a63..de8ce02d 100644 --- a/zh/19/func/func-textsearch.sgml +++ b/zh/19/func/func-textsearch.sgml @@ -1,6 +1,6 @@ - 文本搜索函数和操作符 + 文本检索函数和操作符 全文检索 @@ -8,7 +8,7 @@ - 文本搜索 + 文本检索 函数和操作符 @@ -16,12 +16,12 @@ 以及 - 总结了为全文检索提供的函数和操作符。PostgreSQL的文本搜索功能的详细解释可参考。 + 总结了为全文检索提供的函数和操作符。PostgreSQL的文本检索功能的详细解释可参考
- 文本搜索操作符 + 文本检索操作符 @@ -179,12 +179,12 @@ 除了这些专用操作符之外, 中所示的常用比较操作符也适用于tsvectortsquery类型。 - 这些操作符对文本搜索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。 + 这些操作符对文本检索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。
- 文本搜索函数 + 文本检索函数 @@ -231,7 +231,7 @@ regconfig - 返回当前默认文本搜索配置的OID(由 所设定的). + 返回当前默认文本检索配置的 OID(由 设置)。 get_current_ts_config() @@ -767,18 +767,18 @@ - 所有接受一个可选的regconfig参数的文本搜索函数在省略该参数时,会使用由指定的配置。 + 所有接受一个可选的regconfig参数的文本检索函数在省略该参数时,会使用由指定的配置。 - 中的函数被单独列出,因为它们通常不被用于日常的文本搜索操作。 - 它们主要有助于开发和调试新的文本搜索配置。 + 中的函数被单独列出,因为它们通常不被用于日常的文本检索操作。 + 它们主要有助于开发和调试新的文本检索配置。
- 文本搜索调试函数 + 文本检索调试函数 @@ -814,7 +814,7 @@ lexemestext[] ) - 根据指定的或默认的文本搜索配置从document中提取和正规化词元,并返回关于每个词元是如何处理的信息。 + 根据指定的或默认的文本检索配置从document中提取和正规化词元,并返回关于每个词元是如何处理的信息。 详情参见 diff --git a/zh/19/gist.sgml b/zh/19/gist.sgml index 47d1dfd1..d0488f1e 100644 --- a/zh/19/gist.sgml +++ b/zh/19/gist.sgml @@ -1054,7 +1054,7 @@ my_translate_cmptype(PG_FUNCTION_ARGS) 示例 - PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本搜索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: + PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本检索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: diff --git a/zh/19/json.sgml b/zh/19/json.sgml index 1b9117b8..6ec1386d 100644 --- a/zh/19/json.sgml +++ b/zh/19/json.sgml @@ -38,7 +38,7 @@ - 由于 json 类型存储的是输入文本的精确副本,因此它会保留标记 + 由于 json 类型存储的是输入文本的精确副本,因此它会保留词元 之间在语义上无关紧要的空白,以及 JSON 对象内部键的顺序。此外,如果值中 的某个 JSON 对象包含同一个键多次,所有键/值对都会被保留下来(处理函数会 将最后一个值视为生效值)。相比之下,jsonb 不保留空白,不保留 @@ -86,7 +86,7 @@ 当把文本形式的 JSON 输入转换为 jsonb 时, - RFC 7159 描述的基本类型会有效映射到原生的 + RFC 7159 描述的基本类型实际上会映射到原生的 PostgreSQL 类型上,如 所示。因此,什么样的数据构成 有效的 jsonb 会有一些额外但较小的限制,这些限制不适用于 @@ -137,7 +137,7 @@ null - (无) + (无) SQL NULL 是不同的概念 @@ -152,18 +152,18 @@ 以下都是有效的 json(或 jsonb)表达式: --- Simple scalar/primitive value --- Primitive values can be numbers, quoted strings, true, false, or null +-- 简单的标量/基本值 +-- 基本值可以是数字、加引号的字符串、true、false 或 null SELECT '5'::json; --- Array of zero or more elements (elements need not be of same type) +-- 包含零个或多个元素的数组(元素不必是同一类型) SELECT '[1, 2, "foo", null]'::json; --- Object containing pairs of keys and values --- Note that object keys must always be quoted strings +-- 包含键值对的对象 +-- 注意,对象的键必须始终是加引号的字符串 SELECT '{"bar": "baz", "balance": 7.77, "active": false}'::json; --- Arrays and objects can be nested arbitrarily +-- 数组和对象可以任意嵌套 SELECT '{"foo": [true, "bar"], "tags": {"a": 1, "b": null}}'::json; @@ -219,8 +219,7 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 当 JSON 数据存储在表中时,它与任何其他数据类型一样,都要面对相同的并发控 制考量。虽然存储大型文档是可行的,但要记住,任何更新都会在整行上获取一个 行级锁。应考虑将 JSON 文档限制在可管理的大小,以减少更新事务之间的锁争用。 - 理想情况下,每个 JSON 文档都应表示一个原子数据项,按照业务规则,它不应被 - 合理地进一步拆分为更小且可独立修改的数据项。 + 理想情况下,每个 JSON 文档都应表示一个原子数据项,根据业务规则,无法再合理地将它细分为更小且可独立修改的数据项。 @@ -228,11 +227,11 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; <type>jsonb</type> 包含与存在 jsonb - containment + 包含 jsonb - existence + 存在 测试 包含jsonb 的一项重要能力。 @@ -241,33 +240,32 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 示例都返回真: --- Simple scalar/primitive values contain only the identical value: +-- 简单的标量/基本值只包含相同的值: SELECT '"foo"'::jsonb @> '"foo"'::jsonb; --- The array on the right side is contained within the one on the left: +-- 左侧数组包含右侧数组: SELECT '[1, 2, 3]'::jsonb @> '[1, 3]'::jsonb; --- Order of array elements is not significant, so this is also true: +-- 数组元素的顺序无关紧要,因此下面的结果也为真: SELECT '[1, 2, 3]'::jsonb @> '[3, 1]'::jsonb; --- Duplicate array elements don't matter either: +-- 重复的数组元素也无关紧要: SELECT '[1, 2, 3]'::jsonb @> '[1, 2, 2]'::jsonb; --- The object with a single pair on the right side is contained --- within the object on the left side: +-- 左侧对象包含右侧只有一个键值对的对象: SELECT '{"product": "PostgreSQL", "version": 9.4, "jsonb": true}'::jsonb @> '{"version": 9.4}'::jsonb; --- The array on the right side is not considered contained within the --- array on the left, even though a similar array is nested within it: -SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- yields false +-- 左侧数组被认为包含右侧数组, +-- 尽管其中嵌套了一个类似的数组: +SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- 结果为假 --- But with a layer of nesting, it is contained: +-- 但增加一层嵌套后,就构成了包含关系: SELECT '[1, 2, [1, 3]]'::jsonb @> '[[1, 3]]'::jsonb; --- Similarly, containment is not reported here: -SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- yields false +-- 同样,下面也不构成包含关系: +SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- 结果为假 --- A top-level key and an empty object is contained: +-- 包含由顶层键和空对象构成的对象: SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; @@ -282,11 +280,11 @@ SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; 对于结构必须匹配这一一般原则,有一个特殊例外:数组可以包含一个基本值: --- This array contains the primitive string value: +-- 这个数组包含该基本字符串值: SELECT '["foo", "bar"]'::jsonb @> '"bar"'::jsonb; --- This exception is not reciprocal -- non-containment is reported here: -SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false +-- 这个例外并不对称——下面的结果表示不包含: +SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- 结果为假 @@ -296,19 +294,19 @@ SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false 外,下面这些示例都返回真: --- String exists as array element: +-- 字符串作为数组元素存在: SELECT '["foo", "bar", "baz"]'::jsonb ? 'bar'; --- String exists as object key: +-- 字符串作为对象键存在: SELECT '{"foo": "bar"}'::jsonb ? 'foo'; --- Object values are not considered: -SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- yields false +-- 不考虑对象的值: +SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- 结果为假 --- As with containment, existence must match at the top level: -SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- yields false +-- 与包含关系一样,存在性必须在顶层匹配: +SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- 结果为假 --- A string is considered to exist if it matches a primitive JSON string: +-- 如果字符串与一个基本 JSON 字符串匹配,则认为它存在: SELECT '"foo"'::jsonb ? 'foo'; @@ -322,8 +320,7 @@ SELECT '"foo"'::jsonb ? 'foo'; 由于 JSON 包含是嵌套的,因此适当的查询可以跳过对子对象的显式选择。例如, 假设我们有一个 doc 列,其顶层是对象,而且大 多数对象都带有 tags 字段,该字段中包含子对象数组。下面 - 这个查询会找出那些包含同时带有 "term":"paris" 和 - "term":"food" 的子对象的项,同时忽略 + 这个查询会找出同时出现包含 "term":"paris" 的子对象和包含 "term":"food" 的子对象的项,同时忽略 tags 数组之外的任何此类键: SELECT doc->'site_name' FROM websites @@ -353,7 +350,7 @@ SELECT doc->'site_name' FROM websites <type>jsonb</type> 索引 jsonb - indexes on + 索引 @@ -403,14 +400,14 @@ CREATE INDEX idxginp ON api USING GIN (jdoc jsonb_path_ops); 名为 jdocjsonb 列里。 如果在该列上创建了 GIN 索引,那么下面这样的查询就可以利用这个索引: --- Find documents in which the key "company" has value "Magnafone" +-- 查找键 "company" 的值为 "Magnafone" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"company": "Magnafone"}'; 但是,类似下面这样的查询就无法使用该索引,因为虽然操作符 ? 可索引,但它并未直接应用到被索引的列 jdoc 上: --- Find documents in which the key "tags" contains key or array element "qui" +-- 查找键 "tags" 包含键或数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc -> 'tags' ? 'qui'; 不过,只要适当地使用表达式索引,上述查询也可以利用索引。如果经常查询 @@ -428,7 +425,7 @@ CREATE INDEX idxgintags ON api USING GIN ((jdoc -> 'tags')); 另一种查询方法是利用包含,例如: --- Find documents in which the key "tags" contains array element "qui" +-- 查找键 "tags" 包含数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qui"]}'; jdoc 列上的简单 GIN 索引可以支持这个查询。 @@ -466,7 +463,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; @@ 操作符的查询,但相较于默认操作符类 jsonb_ops,它具有显著的性能优势。 jsonb_path_ops 索引通常比相同数据上的 - jsonb_ops 索引小得多,而且搜索条件也更具特异性,尤其是在 + jsonb_ops 索引小得多,而且搜索也更有针对性,尤其是在 查询中包含数据里频繁出现的键时。因此,搜索操作通常比使用默认操作符类时 性能更佳。 @@ -482,9 +479,9 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; 基本上,每个 jsonb_path_ops 索引项都是该值连同 - 通向该值的键一起计算出的哈希。例如,要索引 + 通向该值的键一起计算出的 hash。例如,要索引 {"foo": {"bar": "baz"}},会创建一个单独的索引项, - 其哈希值中同时纳入 foobar 和 + 其 hash 值中同时纳入 foobarbaz 这三者。因此,查找这一结构的包含查询会得到一次 非常精确的索引搜索;但完全没有办法据此找出 foo 是否 作为键出现。另一方面,jsonb_ops 索引会分别创建三个 @@ -506,7 +503,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; jsonb 还支持 btreehash 索引。通常只有在需要检查完整 JSON 文档是否相等时, 它们才有用。btreejsonb 数据项的 - 排序通常没什么太大意义,但为了完整起见,其规则如下: + 排序顺序通常很少受到关注,但为了完整起见,其规则如下: 对象 > 数组 > 布尔值 > 数字 > 字符串 > null @@ -561,27 +558,24 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; --- Extract object value by key +-- 按键提取对象的值 SELECT ('{"a": 1}'::jsonb)['a']; --- Extract nested object value by key path +-- 按键路径提取嵌套对象的值 SELECT ('{"a": {"b": {"c": 1}}}'::jsonb)['a']['b']['c']; --- Extract array element by index +-- 按下标提取数组元素 SELECT ('[1, "2", null]'::jsonb)[1]; --- Update object value by key. Note the quotes around '1': the assigned --- value must be of the jsonb type as well +-- 按键更新对象的值。注意 '1' 两边的引号:赋予的值也必须是 jsonb 类型 UPDATE table_name SET jsonb_field['key'] = '1'; --- This will raise an error if any record's jsonb_field['a']['b'] is something --- other than an object. For example, the value {"a": 1} has a numeric value --- of the key 'a'. +-- 如果任何记录的 jsonb_field['a']['b'] 不是对象,就会报错。 +-- 例如,值 {"a": 1} 的键 'a' 对应的值是数字。 UPDATE table_name SET jsonb_field['a']['b']['c'] = '1'; --- Filter records using a WHERE clause with subscripting. Since the result of --- subscripting is jsonb, the value we compare it against must also be jsonb. --- The double quotes make "value" also a valid jsonb string. +-- 使用带下标的 WHERE 子句筛选记录。由于下标操作的结果是 jsonb, +-- 与之比较的值也必须是 jsonb。双引号使 "value" 也成为合法的 jsonb 字符串。 SELECT * FROM table_name WHERE jsonb_field['key'] = '"value"'; @@ -591,19 +585,19 @@ SELECT * FROM table_name WHERE jsonb_field['key'] = '"value"'; (对象或数组)的空 JSON 值来处理: --- Where jsonb_field was NULL, it is now {"a": 1} +-- 原先为 NULL 的 jsonb_field 现在为 {"a": 1} UPDATE table_name SET jsonb_field['a'] = '1'; --- Where jsonb_field was NULL, it is now [1] +-- 原先为 NULL 的 jsonb_field 现在为 [1] UPDATE table_name SET jsonb_field[0] = '1'; - 如果对一个元素数量不足的数组指定了某个索引,就会不断追加 - NULL 元素,直到该索引可达并且可以设置该值为止。 + 如果对一个元素数量不足的数组指定了某个下标,就会不断追加 + NULL 元素,直到该下标可达并且可以设置该值为止。 --- Where jsonb_field was [], it is now [null, null, 2]; --- where jsonb_field was [0], it is now [0, null, 2] +-- 原先为 [] 的 jsonb_field 现在为 [null, null, 2]; +-- 原先为 [0] 的 jsonb_field 现在为 [0, null, 2] UPDATE table_name SET jsonb_field[2] = '2'; @@ -614,10 +608,10 @@ UPDATE table_name SET jsonb_field[2] = '2'; null 填充,直到能够放入被赋值的值为止。 --- Where jsonb_field was {}, it is now {"a": [{"b": 1}]} +-- 原先为 {} 的 jsonb_field 现在为 {"a": [{"b": 1}]} UPDATE table_name SET jsonb_field['a'][0]['b'] = '1'; --- Where jsonb_field was [], it is now [null, {"a": 1}] +-- 原先为 [] 的 jsonb_field 现在为 [null, {"a": 1}] UPDATE table_name SET jsonb_field[1]['a'] = '1'; @@ -634,7 +628,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; PL/Perl 的扩展名为 jsonb_plperljsonb_plperlu。如果使用它们, - jsonb 值会按适当方式映射为 Perl 数组、哈希和标量。 + jsonb 值会按适当方式映射为 Perl 数组、hash 和标量。 @@ -694,7 +688,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; 的。还支持非十进制整数字面量和下划线分隔符,例如 1_000_0000x1EEE_FFFF0o2730b100101。在 SQL/JSON - 路径中(以及 JavaScript 中,但不包括严格意义上的 SQL),基数前缀后面不能 + 路径中(以及 JavaScript 中,但 SQL 本身并非如此),基数前缀后面不能 直接出现下划线分隔符。 @@ -723,7 +717,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; - 路径表达式由一系列路径元素构成,可以是下列任意一种: + 路径表达式由一系列路径元素构成,这些元素可以是下列任意一种: @@ -863,7 +857,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; 类似 .**,但只选择 JSON 层次结构中指定的层级。 - 嵌套层级以整数指定。层级零对应当前对象。若要访问最低的嵌套层级, + 嵌套层级以整数指定。层级零对应当前对象。若要访问最深的嵌套层级, 可以使用 last 关键字。这是 PostgreSQL 对 SQL/JSON 标准的扩展。 @@ -881,13 +875,13 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; 可以用两种形式给出: indexstart_index to end_index。 - 第一种形式按索引返回单个数组元素。第二种形式按索引范围返回数组切片, + 第一种形式按下标返回单个数组元素。第二种形式按下标范围返回数组切片, 其中包括与给定 start_indexend_index 对应的元素。 指定的 index 可以是整数,也可以是返回单个 - 数值的表达式,该表达式会自动转换为整数。索引零对应第一个数组元素。 + 数值的表达式,该数值会自动转换为整数。下标零对应第一个数组元素。 你也可以使用 last 关键字来表示最后一个数组元素, 这对于处理长度未知的数组很有用。 diff --git a/zh/19/libpq.sgml b/zh/19/libpq.sgml index 85568605..3d0f4dc1 100644 --- a/zh/19/libpq.sgml +++ b/zh/19/libpq.sgml @@ -2,7 +2,7 @@ - <application>libpq</application> - C 库 + <application>libpq</application> — C 库 libpq @@ -13,33 +13,27 @@ - libpq是应用程序员使用PostgreSQLC接口。libpq是一个库函数的集合,它们允许客户端程序传递查询给PostgreSQL后端服务器并且接收这些查询的结果。 + libpqPostgreSQLC应用程序编程接口。libpq是一组库函数,客户端程序可用它们向PostgreSQL后端服务器发送查询并接收查询结果。 - libpq也是很多其他PostgreSQL应用接口的底层引擎,包括为 C++、Perl、Python、Tcl 和 ECPG编写的接口。如果你使用那些包,某些方面的libpq行为将会对你很重要。特别是,描述了任何使用libpq的应用的用户可见的行为。 + libpq也是其他几个PostgreSQL应用程序接口的底层引擎,包括为 C++、Perl、Python、Tcl 和ECPG编写的接口。因此,对于这些包的用户,libpq行为的某些方面也很重要。特别是,描述了任何使用libpq的应用程序的用户都能观察到的行为。 - 在本章的末尾()包括了一些短程序来展示如何编写使用libpq的应用。在源代码发布的src/test/examples目录中还有一些完整的libpq应用的示例。 + 本章末尾()包含一些简短程序,展示如何编写使用libpq的程序。源代码发行包的src/test/examples目录中还提供了几个完整的libpq应用程序示例。 - 使用libpq的客户端程序必须包括头文件libpq-fe.hlibpq-fe.h并必须与libpq库链接在一起。 + 使用libpq的客户端程序必须包含头文件libpq-fe.hlibpq-fe.h,并且必须与libpq库链接。 数据库连接控制函数 - - 下列函数会建立到一个PostgreSQL后端服务器的连接。 - 一个应用程序可以在一个时刻打开多个后端连接(原因之一就是为了访问多个数据库)。 - 每个连接用一个PGconnPGconn对象表示,它从函数,或得到。 - 注意这些函数将总是返回一个非空的对象指针,除非正好没有内存来分配PGconn对象。 - 在通过该连接对象发送查询之前,应该调用函数来检查返回值以确定是否得到了一个成功的连接。 - - + 以下函数用于建立到PostgreSQL后端服务器的连接。应用程序可以同时保持多个后端连接。(这样做的原因之一是访问多个数据库。)每个连接由一个PGconnPGconn对象表示,该对象可以通过以下函数获取:, + 。注意,这些函数总是返回非空的对象指针,除非内存不足,甚至无法分配PGconn对象。应调用函数检查返回值,确认连接成功后,再通过连接对象发送查询。 如果不受信任的用户能够访问一个没有采用模式的安全使用方式的数据库,那么每个会话开始时都应从search_path中移除公开可写的模式。可以把参数关键词options设置为-csearch_path=。也可以在连接后发出PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)")。这种考虑并非专门针对libpq;它适用于每一种可执行任意 SQL 命令的接口。 @@ -47,7 +41,7 @@ - 在 Unix 上,复制一个拥有打开 libpq 连接的进程可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行代码是安全的。 + 在 Unix 上,对持有已打开 libpq 连接的进程执行 fork 操作可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行程序是安全的。 @@ -74,32 +68,32 @@ PGconn *PQconnectdbParams(const char * const *keywords, - 被传递的数组可以为空,这样就会使用所有默认参数。 - 也可以只包含一个或几个参数设置。他们在长度上必须匹配。 - 对于参数数组的处理将会停止于keywords数组中第一个NULL元素。 - 而且,如果与非-NULL keywords条目相关联的values条目为NULL或者空字符串,则忽略该项并继续处理下一对数组项。 + 传入的数组可以为空,以使用所有默认参数,也可以包含一个或多个参数设置。 + 两个数组的长度必须相同。处理会在 keywords 数组的第一个 NULL 元素处停止。 + 如果某个非 NULLkeywords 元素所对应的 + values 元素为 NULL 或空字符串,则忽略这一项,继续处理下一对数组元素。 - 当expand_dbname为非零时,会检查第一个dbname关键词的值以查看它是否为一个连接字符串。 - 如果是,它被扩展到从字符串中提取的单独的连接参数。 - 该值被认为是一个连接字符串,而不仅是一个数据库名称,如果它包含一个等号(=)或者它以URI模式标志符开头, - (有关连接字符串格式的更多详情可见。) - 只有dbname的第一次出现会按这种方式处理,任何后续dbname值会被当做一个普通数据库名处理。 + 当 expand_dbname 非零时,会检查第一个 dbname 关键词的值是否为 + 连接字符串。如果是,就将其展开为从该字符串中提取的各个连接参数。 + 如果该值包含等号(=),或以 URI 方案标识符开头,就会将其视为连接字符串,而非单纯的数据库名。 + (连接字符串格式的详细说明见。) + 只有第一次出现的 dbname 会按这种方式处理;后续的 dbname 参数都作为普通数据库名处理。 - 通常,参数数组从开头到结尾进行处理。 - 当关键词有重复时,使用最后一个值(不是 NULL 或空)。 - 此规则特别适用于连接字符串中的关键字与一个出现在keywords数组中的关键字冲突的情况。 - 因此,程序员可以决定数组条目是否能被覆盖或用连接字符串获取的值覆盖。 - 出现在扩展的dbname条目之前的数组条目可以被连接字符串的字段所覆盖,反之,这些字段被dbname之后出现的数组条目所覆盖。(但是,再有,只有在那些条目支持非空值时。) + 通常会从头到尾处理参数数组。如果某个关键词重复出现,则采用最后一个非 NULL 且非空的值。 + 此规则也适用于连接字符串中的关键词与 keywords 数组中的关键词冲突的情况。 + 因此,程序员可以决定数组元素是覆盖连接字符串中的值,还是被这些值覆盖。 + 出现在要展开的 dbname 元素之前的数组元素,可以被连接字符串中的字段覆盖; + 而这些字段又会被出现在 dbname 之后的数组元素覆盖(同样,只有这些元素提供非空值时才会覆盖)。 - 在处理完所有数组条目和任何扩展的连接字符串后,所有未设置的连接参数都将使用默认值填充。 - 如果一个未设置参数的相关环境变量(参见 )被设置了,它的值会被使用。 - 如果环境变量未被设置,则使用参数的内置默认值。 + 处理完所有数组元素及展开的连接字符串后,仍未设置的连接参数将填入默认值。 + 如果某个未设置参数对应的环境变量(见)已经设置,就使用该环境变量的值; + 否则使用该参数的内置默认值。 @@ -121,7 +115,7 @@ PGconn *PQconnectdb(const char *conninfo); - 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空格分隔的一个或多个参数设置,还可以包含一个URI。详见。 + 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空白分隔的一个或多个参数设置,还可以包含一个URI。详见 @@ -144,11 +138,11 @@ PGconn *PQsetdbLogin(const char *pghost, - 这是的带有固定参数集合的前辈。它具有相同的功能,不过其中缺失的参数将总是采用默认值。对任意一个固定参数写NULL或一个空字符串将会使它采用默认值。 + 这是 的前身,使用固定的一组参数。除缺失参数始终采用默认值之外,功能相同。对于要使用默认值的任意固定参数,请传入 NULL 或空字符串。 - 如果dbName包含一个=符号或者具有一个合法的连接URI前缀,它会被当作一个conninfo字符串,就好像它已经被传递给了,并且剩余的参数则被应用为指定给。 + 如果 dbName 包含 = 符号,或具有有效的连接 URI 前缀,就会将其当作 conninfo 字符串处理,方式与将其传给 完全相同,然后按照 的规则应用其余参数。 @@ -183,7 +177,7 @@ PGconn *PQsetdb(char *pghost, PQconnectPollPQconnectPoll - nonblocking connection + 非阻塞连接 以非阻塞的方式建立一个到数据库服务器的连接。 @@ -220,7 +214,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 如果你调用,确保你追踪的该流对象不会阻塞。 + 如果你调用,确保接收追踪输出的流对象不会阻塞。 @@ -233,11 +227,11 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 要开始无阻塞的连接请求,可调用PQconnectStart或者。如果结果为空,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 + 要开始非阻塞连接请求,可调用PQconnectStart或者。如果结果为空指针,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 - 如果PQconnectStart成功,下一个阶段是轮询libpq,这样它能够继续进行连接序列。使用PQsocket(conn)来获得该数据库连接底层的套接字描述符(警告:不要假定在PQconnectPoll调用之间套接字会保持相同)。这样循环:如果PQconnectPoll(conn)上一次返回PGRES_POLLING_READING,等到该套接字准备好读取(按照select()poll()或类似的系统函数所指示的)。则再次调用PQconnectPoll(conn)。反之,如果PQconnectPoll(conn)上一次返回PGRES_POLLING_WRITING,等到该套接字准备好写入,则再次调用PQconnectPoll(conn)。在第一次迭代时,即如果你还没有调用PQconnectPoll,行为就像是它上次返回了PGRES_POLLING_WRITING。持续这个循环直到PQconnectPoll(conn)返回PGRES_POLLING_FAILED指示连接过程已经失败,或者返回PGRES_POLLING_OK指示连接已经被成功地建立。 + 如果PQconnectStart成功,下一个阶段是轮询libpq,这样它能够继续进行连接序列。使用PQsocket(conn)来获得该数据库连接底层的套接字描述符(警告:不要假定在PQconnectPoll调用之间套接字会保持相同)。这样循环:如果PQconnectPoll(conn)上一次返回PGRES_POLLING_READING,等到该套接字准备好读取(按照select()poll()或类似的系统函数所指示的)。注意,PQsocketPoll封装了select(2)poll(2)(如果系统支持)的设置,可减少重复代码。然后再次调用PQconnectPoll(conn)。反之,如果PQconnectPoll(conn)上一次返回PGRES_POLLING_WRITING,等到该套接字准备好写入,则再次调用PQconnectPoll(conn)。在第一次迭代时,即如果你还没有调用PQconnectPoll,行为就像是它上次返回了PGRES_POLLING_WRITING。持续这个循环直到PQconnectPoll(conn)返回PGRES_POLLING_FAILED指示连接过程已经失败,或者返回PGRES_POLLING_OK指示连接已经被成功地建立。 @@ -327,7 +321,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 注意,尽管这些常数将被保留(为了维护兼容性),一个应用永远不应该依赖这些状态按照特定顺序出现,或者根本就不依赖它们,或者不依赖状态总是这些文档中所说的值。一个应用可能做些这样的事情: + 注意,虽然为保持兼容性会保留这些常量,但应用程序不应依赖它们按特定顺序出现,不应假定它们一定出现,也不应假定状态值一定是这里列出的某个值。应用程序可以采用如下方式: switch(PQstatus(conn)) { @@ -348,11 +342,11 @@ switch(PQstatus(conn)) - 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。否则,PQconnectStart后面跟着PQconnectPoll循环等效于。 + 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。除此之外,PQconnectStart后面跟着PQconnectPoll循环等效于 - 注意当PQconnectStart返回一个非空的指针时,你必须在用完它之后调用来处理那些结构体和任何相关的内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 + 注意当PQconnectStart返回一个非空的指针时,你必须在用完它之后调用来释放该结构体及其关联的所有内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 @@ -400,21 +394,21 @@ PQconninfoOption *PQconndefaults(void); typedef struct { char *keyword; /* 该选项的关键词 */ - char *envvar; /* 依赖的环境变量名 */ - char *compiled; /* 依赖的内置默认值 */ + char *envvar; /* 后备环境变量名 */ + char *compiled; /* 编译时设置的后备默认值 */ char *val; /* 选项的当前值,或者 NULL */ - char *label; /* 连接对话框中域的标签 */ - char *dispchar; /* 指示如何在一个连接对话框中显示这个域。值是: + char *label; /* 连接对话框中字段的标签 */ + char *dispchar; /* 指示如何在连接对话框中显示此字段。可取值: "" 显示输入的值 - "*" 密码域 - 隐藏值 + "*" 密码字段 - 隐藏值 "D" 调试选项 - 默认不显示 */ - int dispsize; /* 用于对话框的以字符计的域尺寸 */ + int dispsize; /* 对话框中的字段宽度,以字符计 */ } PQconninfoOption; - 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前缺省值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回该空指针。注意当前缺省值(val域)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 + 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前默认值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回空指针。注意当前默认值(val字段)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 @@ -435,9 +429,7 @@ PQconninfoOption *PQconninfo(PGconn *conn); - 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前缺省值。 - 返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。 - 上述所有对于的注解也适用于的结果。 + 返回一个连接选项数组。可以用它确定所有可能的 选项,以及实际用于连接服务器的值。返回值指向一个 PQconninfoOption 结构体数组,该数组以 keyword 指针为空的条目结束。上文针对 的所有注意事项,也适用于 的结果。 @@ -463,7 +455,9 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); - 如果errmsg不是NULL,那么成功时*errmsg会被设置为NULL, 否则设置为被malloc过的错误字符串以说明该问题(也可以将*errmsg设置为NULL并且函数返回NULL,这表示一种内存耗尽的情况)。 + 如果 errmsg 不是 NULL,则成功时将 *errmsg 设为 NULL; + 失败时将其设为由 malloc 分配的、用于说明问题的错误字符串。 + (也可能出现 *errmsg 被设为 NULL,同时函数返回 NULL 的情况;这表示内存不足。) @@ -493,7 +487,7 @@ void PQfinish(PGconn *conn); PQresetPQreset - 重置与服务器的通讯通道。 + 重置与服务器的通信通道。 void PQreset(PGconn *conn); @@ -511,7 +505,7 @@ void PQreset(PGconn *conn); PQresetPollPQresetPoll - 以非阻塞方式重置与服务器的通讯通道。 + 以非阻塞方式重置与服务器的通信通道。 int PQresetStart(PGconn *conn); @@ -528,7 +522,7 @@ PostgresPollingStatusType PQresetPoll(PGconn *conn); - 要发起一次连接重置,调用。如果它返回 0,那么重置失败。如果返回 1,就按使用PQresetPoll建立连接时相同的方法,继续调用PQresetPoll来重置连接。 + 要开始重置连接,请调用 。如果返回 0,表示重置失败。如果返回 1,则使用 PQresetPoll 轮询重置过程,方式与使用 PQconnectPoll 建立连接完全相同。 @@ -623,7 +617,7 @@ void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook); int callback_fn(char *buf, int size, PGconn *conn); - 随后,libpq会调用该回调,而不是调用其默认的PQdefaultSSLKeyPassHook_OpenSSL处理程序。 + 随后,libpq会调用该回调,而不是调用其默认的PQdefaultSSLKeyPassHook_OpenSSL处理程序。 回调函数应确定密钥密码,并将其复制到大小为size的结果缓冲区buf中。 buf中的字符串必须以空字符结尾。 回调函数必须返回存储在buf中的密码长度,不包括结尾的空字符。 @@ -642,7 +636,7 @@ int callback_fn(char *buf, int size, PGconn *conn); - 除了异常、longjmp(...)等情况外,回调务必不可跳出正常控制流。它必须正常返回。 + 回调不得通过异常、longjmp(...)等方式跳出正常控制流。它必须正常返回。 @@ -679,9 +673,9 @@ PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void); 几个libpq函数解析用户指定的字符串以获取连接参数。 - 这些字符串有两种被接受的格式:普通的关键字/值字符串和URI。URI通常遵循 + 这些字符串有两种被接受的格式:普通的关键词/值字符串和URI。URI通常遵循 RFC - 3986,除了允许多主机连接字符串,如下面进一步描述的那样。 + 3986,但也允许使用多主机连接字符串,详见下文。 @@ -689,10 +683,10 @@ PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void); 关键词/值连接字符串 - 在关键词/值格式中,每一个参数设置的形式都是关键词 = ,在设置之间有空白。 - 设置的等号周围的空白是可选的。 - 要写一个空值或一个包含空白的值,将它用单引号包围,例如关键词 = 'a value'。 - 值里面的单引号和反斜线必须用一个反斜线转义,即\'\\。 + 在关键词/值格式中,每一个参数设置的形式都是关键词 = ,设置之间以空格分隔。 + 设置的等号周围的空格是可选的。 + 要写一个空值或一个包含空格的值,将它用单引号包围,例如keyword = 'a value'。 + 值里面的单引号和反斜杠必须用一个反斜杠转义,即\'\\ @@ -716,22 +710,22 @@ host=localhost port=5432 dbname=mydb connect_timeout=10 postgresql://userspec@hostspec/dbname?paramspec -where userspec is: +其中 userspec 为: user:password -and hostspec is: +hostspec 为: host:port,... -and paramspec is: +paramspec 为: name=value&... - URI模式标志符可以是postgresql://postgres://。 + URI方案标识符可以是postgresql://postgres://。 每一个剩下的URI部分都是可选的。 下列示例展示了合法的URI语法: @@ -748,19 +742,15 @@ postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application postgresql:///mydb?host=localhost&port=5433 - 全部的命名参数必须匹配中列出的关键词,除了与JDBC连接URI兼容之外,ssl=true的实例转换到sslmode=require。 + 所有命名参数都必须与中列出的关键词匹配;唯一的例外是,为兼容 JDBC 连接 URI,会将 ssl=true 转换为 sslmode=require - 连接URI需要使用百分号编码 - 对其进行编码,如果其中包含具有特殊含义的符号。这里是一个示例,其中等号(=)被替换为 - %3D,空格字符被替换为 - %20: + 如果连接 URI 的任意部分包含具有特殊含义的符号,就需要使用百分号编码。下面的示例将等号(=)替换为 %3D,将空格字符替换为 %20 postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff - + 主机部分可能是主机名或一个 IP 地址。要指定一个 IPv6 地址,将它封闭在方括号中: @@ -773,7 +763,7 @@ postgresql://[2001:db8::1234]/database 主机组件会被按照参数对应的描述来解释。 特别地,如果主机部分是空或看起来像一个绝对路径名称,将使用一个 Unix 域套接字连接,否则将启动一个 TCP/IP 连接。 不过要注意,斜线是 URI 层次部分中的一个保留字符。 - 因此,要指定一个非标准的 Unix 域套接字目录,要么忽略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: + 因此,要指定一个非标准的 Unix 域套接字目录,要么省略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: postgresql:///dbname?host=/var/lib/postgresql postgresql://%2Fvar%2Flib%2Fpostgresql/dbname @@ -783,7 +773,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以在一个URI中指定多个主机,每一个都有一个可选的端口。 一个形式为postgresql://host1:port1,host2:port2,host3:port3/的URI等效于host=host1,host2,host3 port=port1,port2,port3形式的连接字符串。 - 如下所述,每一个主机都将被尝试,直到成功地建立一个连接。 + 如下所述,每一个主机都将被依次尝试,直到成功地建立一个连接。 @@ -793,7 +783,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以指定多个要连接的主机,这样它们会按给定的顺序被尝试。 - 在键/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 + 在关键词/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 在指定的每一个选项中都必须给出相同数量的元素,这样第一个hostaddr对应于第一个主机名,第二个hostaddr对应于第二个主机名,以此类推。 不过,如果仅指定一个port,它将被应用于所有的主机。 @@ -803,11 +793,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 不管是哪一种格式,单一的主机名可以被翻译成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 + 不管是哪一种格式,单一的主机名可以被解析成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 - 当多个主机被指定时或者单个主机名被翻译成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。 + 当多个主机被指定时或者单个主机名被解析成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。 @@ -829,14 +819,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 要连接的主机名。主机名如果主机名看起来像绝对路径名, - 则指定的是Unix域通信而不是TCP/IP通信;该值是存储套接字文件的目录的名称。 - (在Unix上,绝对路径名以斜杠开头。在Windows上,以驱动器号开头的路径也被识别。) - 如果主机名以@开头,则将其视为抽象命名空间中的Unix域套接字(目前在Linux和Windows上支持)。 - 当未指定host或为空时,默认行为是连接到Unix域套接字Unix域套接字在 - /tmp(或在构建PostgreSQL时指定的套接字目录)中。在Windows和 - 没有Unix域套接字的机器上,默认是连接到localhost。 - + 要连接的主机名。主机名如果主机名看起来像绝对路径名, + 则指定的是 Unix 域通信,而非 TCP/IP 通信;此值是存放套接字文件的目录名。 + (在 Unix 上,绝对路径名以斜杠开头。在 Windows 上,也会识别以驱动器号开头的路径。)如果主机名以 @ 开头,则将其视为抽象命名空间中的 Unix 域套接字(目前在 Linux 和 Windows 上支持)。 + 当未指定 host 或其值为空时,默认连接到 /tmp + (或构建 PostgreSQL 时指定的套接字目录)中的 Unix 域套接字。 + Unix 域套接字在 Windows 上,默认连接到 localhost。 + 也可以接受一个逗号分隔的主机名列表,此时列表中的每个主机名将按顺序尝试; @@ -864,7 +853,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 如果指定了host而没有指定hostaddr,则会发生主机名查找。 (当使用PQconnectPoll时,查找发生在PQconnectPoll首次考虑此主机名时, - 并且可能导致PQconnectPoll阻塞一段时间。) + 并且可能导致PQconnectPoll阻塞相当长的时间。) @@ -876,11 +865,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果同时指定了hosthostaddr, - 则hostaddr的值给出服务器的网络地址。 - 除非认证方法需要,否则host的值将被忽略, - 在这种情况下,它将用作主机名。 - + 如果同时指定了 hosthostaddr,则 hostaddr 的值给出服务器的网络地址。只有认证方法需要主机名时,才会将 host 的值用作主机名;否则忽略该值。 + 请注意,如果host不是网络地址hostaddr上服务器的名称, @@ -896,10 +882,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 没有主机名或主机地址, - libpq将使用本地的Unix域套接字进行连接; - 或者在Windows和没有Unix域套接字的机器上,它将尝试连接到localhost。 - + 如果既没有主机名也没有主机地址,libpq 会使用本地 Unix 域套接字连接;在 Windows 上,则会尝试连接到 localhost。 + @@ -933,8 +917,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - PostgreSQL用户连接的用户名。 - 默认为运行应用程序的操作系统用户名相同。 + 建立连接所用的 PostgreSQL 用户名。默认与运行应用程序的操作系统用户名相同。 @@ -944,7 +927,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果服务器要求密码认证,则使用密码。 + 服务器要求密码认证时所使用的密码。 @@ -965,7 +948,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname require_auth - 指定客户端要求服务器采用的认证方法。如果服务器没有使用所要求的方法来认证客户端,或者服务器没有完整完成认证握手,则连接将失败。也可以提供一个以逗号分隔的方法列表,此时服务器必须准确使用其中一种方法,连接才会成功。默认情况下接受任意认证方法,并且服务器也可以完全跳过认证。 + 指定客户端要求服务器采用的认证方法。如果服务器没有使用所要求的方法来认证客户端,或者服务器没有完整完成认证握手,则连接将失败。也可以提供一个以逗号分隔的方法列表,此时服务器必须恰好使用其中一种方法,连接才会成功。默认情况下接受任意认证方法,并且服务器也可以完全跳过认证。 可以在方法名前加上!前缀以表示否定,此时服务器不得尝试所列方法;除此之外,任何其他方法都可接受,并且服务器也可以完全不认证客户端。如果提供的是逗号分隔列表,服务器不得尝试其中任何一个被否定的方法。否定形式和非否定形式不能在同一设置中混用。 @@ -1055,7 +1038,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 这个选项控制客户端对通道绑定的使用。设置为require表示连接必须使用通道绑定, prefer表示客户端将在可用时选择通道绑定, 而disable则阻止使用通道绑定。默认情况下, - 如果PostgreSQL是使用SSL支持编译的,则默认为prefer; + 如果PostgreSQL是使用SSL支持编译的,则默认为prefer; 否则默认为disable @@ -1071,9 +1054,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 连接时的最长等待时间,以秒为单位(写成十进制整数,例如,10)。 - 零、负值或未指定表示无限等待。最小允许的超时时间为2秒,因此 - 1的值被解释为2。 - 此超时时间分别适用于每个主机名或IP地址。 + 零、负值或未指定表示无限等待。此超时时间分别适用于每个主机名或IP地址。 例如,如果指定了两个主机和connect_timeout 为5,如果在5秒内没有建立连接,每个主机将超时, 因此等待连接的总时间可能长达10秒。 @@ -1119,9 +1100,9 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 指定配置参数的回退值。 + 指定配置参数的后备值。 如果没有通过连接参数或PGAPPNAME环境变量为application_name指定值, - 则将使用此值。在通用实用程序中指定回退名称很有用,该程序希望设置默认应用程序名称, + 则将使用此值。在通用实用程序中指定后备名称很有用,该程序希望设置默认应用程序名称, 但允许用户覆盖它。 @@ -1132,9 +1113,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制是否使用客户端TCP保持活动。默认值为1,表示开启,但如果不想要保持活动,可以将其更改为0,表示关闭。 - 对于通过Unix域套接字进行的连接,此参数将被忽略。 - + 控制是否使用客户端 TCP keepalive。默认值为 1,表示开启;如果不需要 keepalive,可以将其设为 0,表示关闭。对于通过 Unix 域套接字建立的连接,此参数会被忽略。 + @@ -1143,11 +1123,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在多少秒的不活动后,TCP应向服务器发送保持活动消息。值为零使用系统默认值。 - 对通过Unix域套接字进行的连接或禁用保持活动的连接,此参数将被忽略。 - 仅在支持TCP_KEEPIDLE或等效套接字选项的系统以及Windows上支持; - 在其他系统上,它没有任何效果。 - + 控制在多久没有活动后,TCP 应向服务器发送 keepalive 消息,以秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPIDLE 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -1156,11 +1133,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在服务器未确认的情况下重新传输TCP保持活动消息的秒数。值为零时使用系统默认值。 - 此参数在通过Unix域套接字进行连接或禁用保持活动时将被忽略。 - 仅在支持TCP_KEEPINTVL或等效套接字选项的系统和Windows上支持; - 在其他系统上,此参数无效。 - + 控制未被服务器确认收到的 TCP keepalive 消息在多少秒后应被重传。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPINTVL 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -1169,11 +1143,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在客户端与服务器之间连接被视为断开之前可以丢失的TCP keepalive数量。 - 值为零时使用系统默认值。对通过Unix域套接字建立的连接或禁用keepalives的连接,此参数将被忽略。 - 仅在支持TCP_KEEPCNT或等效套接字选项的系统上受支持; - 在其他系统上,此参数无效。 - + 控制在客户端与服务器之间的连接被视为中断之前,可以丢失多少个 TCP keepalive 消息。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPCNT 或等效套接字选项的系统上受支持;在其他系统上无效。 + @@ -1182,10 +1153,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在连接在强制关闭之前,传输数据可以保持未被确认的毫秒数。 - 值为零时使用系统默认值。此参数对通过Unix域套接字进行的连接无效。 - 仅在支持TCP_USER_TIMEOUT的系统上受支持;在其他系统上,它没有效果。 - + 控制已发送的数据在连接被强制关闭之前最多可以保持未确认状态多长时间,以毫秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,此参数会被忽略。此参数仅在支持 TCP_USER_TIMEOUT 的系统上受支持;在其他系统上无效。 + @@ -1248,25 +1217,25 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个选项确定是否以及如何优先与服务器协商安全的GSS TCP/IP连接。有三种模式: + 这个选项确定是否以及以何种优先级与服务器协商安全的GSS TCP/IP连接。有三种模式: disable - 仅尝试非GSSAPI加密连接 + 仅尝试未经GSSAPI加密的连接 - prefer (默认) + prefer (默认) 如果存在GSSAPI凭据(即在凭据缓存中),首先尝试 GSSAPI加密连接;如果失败或没有凭据,则尝试 - 非GSSAPI加密连接。这是在编译PostgreSQL时使用GSSAPI支持时的默认设置。 + 未经GSSAPI加密的连接。这是在编译PostgreSQL时使用GSSAPI支持时的默认设置。 @@ -1285,7 +1254,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname gssencmode在Unix域套接字通信中被忽略。如果PostgreSQL没有编译GSSAPI支持, 使用require选项将导致错误,而prefer将被接受,但libpq实际上不会尝试 - 进行GSSAPI加密连接。GSSAPI与libpq + 进行GSSAPI加密连接。GSSAPI在 libpq 中 @@ -1317,7 +1286,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - prefer (默认) + prefer (默认) 首先尝试SSL连接;如果失败,则尝试非SSL连接 @@ -1357,22 +1326,18 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - sslmode被忽略用于Unix域套接字通信。 - 如果PostgreSQL没有SSL支持编译, + 在 Unix 域套接字通信中,sslmode 会被忽略。 + 如果PostgreSQL编译时未启用 SSL 支持, 使用选项requireverify-caverify-full会导致错误,而选项allowprefer 将被接受,但libpq实际上不会尝试建立SSL 连接。SSL使用libpq的SSL + sortas="libpq">在 libpq 中 - 请注意,如果可能使用GSSAPI加密, - 则优先使用该加密,而不考虑SSL的值。要在具有可用GSSAPI - 基础设施(如Kerberos服务器)的环境中强制使用 - SSL加密,还需将 - gssencmode设置为disable。 - + 注意,如果可以使用 GSSAPI 加密,就会优先使用它而不是 SSL 加密,无论 sslmode 的值是什么。在具有可用 GSSAPI 基础设施(例如 Kerberos 服务器)的环境中,要强制使用 SSL 加密,还应将 gssencmode 设为 disable。 + @@ -1381,15 +1346,15 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 此选项已被sslmode设置所取代。 - + 此选项已弃用,请改用 sslmode 设置。 + 如果设置为1,则需要与服务器建立SSL连接(这相当于sslmode require)。libpq将拒绝连接,如果服务器不接受 SSL连接。如果设置为0(默认值), libpq将与服务器协商连接类型(相当于sslmode - prefer)。此选项仅在PostgreSQL编译时启用SSL支持。 + prefer)。此选项仅在 PostgreSQL 编译时启用了 SSL 支持的情况下可用。 @@ -1439,7 +1404,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果安全性不是主要考虑因素,压缩可以提高吞吐量,如果网络是瓶颈的话。如果CPU性能是限制因素,禁用压缩可以提高响应时间和吞吐量。 + 如果安全性不是主要考虑因素,压缩可以提高吞吐量,如果网络是瓶颈的话。如果CPU性能是限制因素,禁用压缩可以缩短响应时间并提高吞吐量。 @@ -1463,7 +1428,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 这个参数指定了用于客户端证书的密钥的位置。它可以指定一个文件名,该文件名将被用来替代默认的 ~/.postgresql/postgresql.key,或者它可以指定一个从外部引擎 - (引擎是OpenSSL可加载模块)获取的密钥。外部引擎规范应该包括一个由冒号分隔的引擎名称和 + (引擎是OpenSSL可加载模块)获取的密钥。外部引擎的指定形式应包含一个由冒号分隔的引擎名称和 一个引擎特定的密钥标识符。如果没有进行SSL连接,则此参数将被忽略。 @@ -1492,10 +1457,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 指定此参数为任何非空值将抑制Enter PEM pass phrase: - 当提供加密的客户端证书密钥给libpq时, - OpenSSL默认会发出的提示。 - + 当向 libpq 提供加密的客户端证书密钥时,将此参数指定为任意非空值,都将抑制 OpenSSL 默认发出的 Enter PEM pass phrase: 提示。 + 如果密钥未加密,则忽略此参数。该参数对由OpenSSL引擎指定的密钥没有影响,除非引擎使用OpenSSL密码回调机制进行提示。 @@ -1577,10 +1540,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定SSL服务器证书吊销列表(CRL)的文件名。如果存在该文件中列出的证书,在尝试验证服务器证书时将被拒绝。 - 如果既没有设置也没有设置, - 则将采用~/.postgresql/root.crl。 - + 此参数指定 SSL 服务器证书吊销列表(CRL)的文件名。如果该文件存在,在验证服务器证书时,会拒绝其中列出的证书。如果既未设置,也未设置,则采用 ~/.postgresql/root.crl。 + @@ -1589,8 +1550,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定SSL服务器证书吊销列表(CRL)的目录名称。如果存在该目录中的文件中列出的证书,在尝试验证服务器证书时将被拒绝。 - + 此参数指定 SSL 服务器证书吊销列表(CRL)的目录名。如果该目录存在,在验证服务器证书时,会拒绝该目录下文件中列出的证书。 + 目录需要使用OpenSSL命令 @@ -1605,19 +1566,17 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - sslsniServer Name Indication + sslsni服务器名称指示 - 如果设置为1(默认值),libpq会在启用SSL的连接上设置TLS扩展Server Name IndicationSNI)。 + 如果设置为1(默认值),libpq会在启用SSL的连接上设置TLS扩展服务器名称指示SNI)。 通过将此参数设置为0,可以关闭此功能。 - 服务器名称指示可以被SSL感知代理使用,以便在不解密SSL流的情况下路由连接。 - (请注意,这需要一个了解PostgreSQL协议握手的代理,而不仅仅是任何SSL代理。) - 然而,SNI会使目标主机名以明文形式出现在网络流量中,因此在某些情况下可能不希望使用。 - + 支持 SSL 的代理可以利用服务器名称指示来路由连接,而无需解密 SSL 流。(注意,除非代理能够识别 PostgreSQL 协议握手,否则需要将 sslnegotiation 设为 direct。)不过,SNI 会使目标主机名以明文形式出现在网络流量中,因此在某些情况下可能不希望使用它。 + @@ -1642,8 +1601,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定连接允许的最低SSL/TLS协议版本。有效值为TLSv1, - TLSv1.1TLSv1.2和 + 这个参数指定连接允许的最低SSL/TLS协议版本。有效值为TLSv1、 + TLSv1.1TLSv1.2TLSv1.3。支持的协议取决于所使用的 OpenSSL版本,旧版本不支持最现代的协议版本。 如果未指定,默认值为TLSv1.2,符合本文撰写时的行业最佳实践。 @@ -1656,11 +1615,10 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定连接允许的最大SSL/TLS协议版本。有效值为TLSv1, - TLSv1.1TLSv1.2和 + 这个参数指定连接允许的最大SSL/TLS协议版本。有效值为TLSv1、 + TLSv1.1TLSv1.2TLSv1.3。支持的协议取决于使用的OpenSSL - 版本,旧版本不支持最新的协议版本。如果未设置,将忽略此参数,并且连接将使用后端定义的最大限制, - 如果设置。设置最大协议版本主要用于测试或者某些组件无法使用较新协议时。 + 版本,旧版本不支持最新的协议版本。如果未设置,则忽略此参数;如果后端定义了最大限制,连接将使用该限制。设置最大协议版本主要用于测试或者某些组件无法使用较新协议时。 @@ -1726,13 +1684,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 用于使用GSSAPI进行认证时要使用的Kerberos服务名称。 + 使用 GSSAPI 认证时所用的 Kerberos 服务名。 这必须与服务器配置中指定的Kerberos认证服务名称匹配,才能成功进行认证。 (另请参见。) 默认值通常为postgres, - 但在构建PostgreSQL时可以通过 - 选项进行更改 - configure。 + 但在构建 PostgreSQL 时,可以通过 configure 选项更改。 在大多数环境中,通常不需要更改此参数。 一些Kerberos实现可能需要不同的服务名称, 例如Microsoft Active Directory需要服务名称为大写(POSTGRES)。 @@ -1756,7 +1712,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname gssdelegation - 将 GSS 凭证转发(委派)给服务器。默认值为0,表示不向服务器转发凭证。将其设置为1时,会在可能的情况下转发凭证。 + 将 GSS 凭据转发(委派)给服务器。默认值为0,表示不向服务器转发凭据。将其设置为1时,会在可能的情况下转发凭据。 @@ -1765,7 +1721,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname scram_client_key - 以 Base64 编码的 SCRAM 客户端密钥。外部数据包装器或类似中间件可以利用它启用透传式 SCRAM 认证。一个实现示例见。普通用户或客户端应用不应直接指定它。 + 以 Base64 编码的 SCRAM 客户端密钥。外部数据包装器或类似中间件可以利用它启用透传式 SCRAM 认证。一个实现示例见。用户或客户端应用不应直接指定它。 @@ -1774,7 +1730,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname scram_server_key - 以 Base64 编码的 SCRAM 服务器密钥。外部数据包装器或类似中间件可以利用它启用透传式 SCRAM 认证。一个实现示例见。普通用户或客户端应用不应直接指定它。 + 以 Base64 编码的 SCRAM 服务器密钥。外部数据包装器或类似中间件可以利用它启用透传式 SCRAM 认证。一个实现示例见。用户或客户端应用不应直接指定它。 @@ -1916,7 +1872,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname “混淆攻击(mix-up attacks)” - 你也可以显式把oauth_issuer设置为 OAuth 发现所使用的/.well-known/ URI。在这种情况下,如果服务器要求使用不同的 URL,连接就会失败;不过,自定义 OAuth 流程也许能够通过使用先前缓存的令牌来加速标准握手。(此时也建议设置,因为客户端将没有机会向服务器询问正确的 scope 设置,而令牌的默认 scope 可能不足以完成连接。)libpq当前支持以下 well-known 端点: + 你也可以显式把oauth_issuer设置为 OAuth 发现所使用的/.well-known/ URI。在这种情况下,如果服务器要求使用不同的 URL,连接就会失败;不过,自定义 OAuth 流程也许能够通过使用先前缓存的令牌来加速标准握手。(此时也建议设置,因为客户端将没有机会向服务器询问正确的授权范围设置,而令牌的默认授权范围可能不足以完成连接。)libpq当前支持以下 well-known 端点: /.well-known/openid-configuration /.well-known/oauth-authorization-server @@ -1943,8 +1899,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname oauth_client_secret - 与 OAuth 授权服务器通信时要使用的客户端密码(如果有)。该参数是否必需由 OAuth 提供者决定;“public” 客户端通常不使用 secret,而 “confidential” 客户端通常会使用。 - + 与 OAuth 授权服务器通信时要使用的客户端密码(如果有)。该参数是否必需由 OAuth 提供者决定;公开客户端(public client)通常不使用密钥,而机密客户端(confidential client)通常会使用。 + @@ -1952,13 +1908,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname oauth_scope - 发送给授权服务器的访问请求 scope,以 OAuth scope 标识符的空格分隔列表指定(该列表可以为空)。该参数是可选的,面向高级用法。 - + 发送给授权服务器的访问请求的授权范围,以空格分隔的 OAuth 授权范围标识符列表指定(列表可以为空)。该参数是可选的,面向高级用法。 + - 通常客户端会从PostgreSQL服务器获得合适的 scope 设置。如果使用这个参数,服务器请求的 scope 列表会被忽略。这可以防止不那么受信任的服务器向最终用户请求不恰当的访问 scope。不过,如果客户端的 scope 设置不包含服务器所要求的 scope,服务器很可能会拒绝已经签发的令牌,连接也会失败。 + 通常客户端会从PostgreSQL服务器获得合适的授权范围设置。如果使用这个参数,服务器请求的授权范围列表会被忽略。这可以防止不那么受信任的服务器向最终用户请求不恰当的访问授权范围。不过,如果客户端的授权范围设置不包含服务器所要求的授权范围,服务器很可能会拒绝已经签发的令牌,连接也会失败。 - 空 scope 列表的含义取决于提供者。OAuth 授权服务器可以选择签发带有“默认 scope”的令牌,不管那具体是什么;也可以完全拒绝该令牌请求。 + 空授权范围列表的含义取决于提供者。OAuth 授权服务器可以选择签发带有“默认授权范围”的令牌,不管那具体是什么;也可以完全拒绝该令牌请求。 @@ -1986,23 +1942,21 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 连接状态函数 - 这些函数可以被用来询问一个已有数据库连接对象的状态。 + 这些函数可用于查询现有数据库连接对象的状态。 - libpq-fe.h - libpq-int.h - libpq应用程序员应该小心地维护PGconn抽象。使用下面描述的访问函数来理解PGconn的内容。我们不推荐使用libpq-int.h引用内部的PGconn域,因为它们可能在未来改变。 - + libpq-fe.h + libpq-int.h + 编写 libpq 应用程序时,应注意维护 PGconn 的抽象。请使用下述访问函数获取 PGconn 的内容。不建议通过 libpq-int.h 引用 PGconn 的内部字段,因为这些字段将来可能改变。 + - 下列函数返回一个连接所建立的参数值。这些值在连接的生命期中是固定的。 - 如果使用的是多主机连接字符串,如果使用同一个PGconn对象建立新连接,,, 和 可能会改变。其他值在PGconn对象的一生中都是固定的。 - - + 以下函数返回建立连接时确定的参数值。这些值在连接存续期间保持不变。如果使用多主机连接字符串,并使用同一个 PGconn 对象建立新连接,则 的返回值可能改变。其他值在 PGconn 对象的整个生命周期内保持不变。 + PQdbPQdb @@ -2052,7 +2006,7 @@ char *PQpass(const PGconn *conn); - 返回活跃连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 + 返回活动连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 char *PQhost(const PGconn *conn); @@ -2064,7 +2018,7 @@ char *PQhost(const PGconn *conn); - 如果conn参数是NULL,则返回NULL。否则,如果有一个错误产生主机信息(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成主机信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -2085,8 +2039,7 @@ char *PQhostaddr(const PGconn *conn); - 如果conn 参数为 NULL 返回 NULL 。 - 否则,如果生成主机信息时出现错误(如果连接尚未完全建立或出现错误),则返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成主机信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -2096,7 +2049,7 @@ char *PQhostaddr(const PGconn *conn); - 返回活跃连接的端口。 + 返回活动连接的端口。 char *PQport(const PGconn *conn); @@ -2108,7 +2061,7 @@ char *PQport(const PGconn *conn); - 如果conn参数是NULL,则返回NULL。否则,如果有一个错误产生端口信息(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成端口信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -2122,9 +2075,7 @@ char *PQport(const PGconn *conn); - 这个函数不再做任何事,但是它保持了向后兼容。 - 这个函数总是返回一个空字符串,或者NULL,如果connNULL。 - + 此函数已不再执行任何操作,但为保持向后兼容仍予以保留。如果 conn 参数为 NULL,则返回 NULL;否则始终返回空字符串。 char *PQtty(const PGconn *conn); @@ -2137,7 +2088,7 @@ char *PQtty(const PGconn *conn); - 返回被传递给连接请求的命令行选项。 + 返回连接请求中传递的命令行选项。 char *PQoptions(const PGconn *conn); @@ -2145,12 +2096,11 @@ char *PQoptions(const PGconn *conn); - + - 下列函数返回会随着在PGconn对象上执行的操作改变的状态数据。 - - + 以下函数返回的状态数据,可能随着对 PGconn 对象执行操作而改变。 + PQstatusPQstatus @@ -2163,9 +2113,9 @@ ConnStatusType PQstatus(const PGconn *conn); - 该状态可以是一系列值之一。不过,其中只有两个在一个异步连接过程之外可见:CONNECTION_OKCONNECTION_BAD。 - 一个到数据库的完好连接的状态为CONNECTION_OK。一个失败的连接尝试则由状态CONNECTION_BAD表示。 - 通常,一个 OK 状态将一直保持到,但是一次通信失败可能导致该状态过早地改变为CONNECTION_BAD。 + 该状态可以是一系列值之一。不过,其中只有两个在一个异步连接过程之外可见:CONNECTION_OKCONNECTION_BAD。 + 一个到数据库的完好连接的状态为CONNECTION_OK。一个失败的连接尝试则由状态CONNECTION_BAD表示。 + 通常,一个 OK 状态将一直保持到,但是一次通信失败可能导致该状态过早地改变为CONNECTION_BAD。 在那种情况下,该应用可以通过调用尝试恢复。 @@ -2186,7 +2136,7 @@ ConnStatusType PQstatus(const PGconn *conn); PGTransactionStatusType PQtransactionStatus(const PGconn *conn); - 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个合法的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接损坏,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE。 + 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个有效的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接异常,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE。 @@ -2281,21 +2231,21 @@ int PQserverVersion(const PGconn *conn); - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 + 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,为每个部分使用两位数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 + 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。在所有主版本系列中,各次版本(缺陷修复版本)之间只有最后两位数字不同。 - PQerrorMessagePQerrorMessage + PQerrorMessagePQerrorMessage错误消息PGconn - 错误消息返回连接上的一个操作最近产生的错误消息。 + 返回连接上的一个操作最近产生的错误消息。 char *PQerrorMessage(const PGconn *conn); @@ -2304,9 +2254,7 @@ char *PQerrorMessage(const PGconn *conn); - 几乎所有的libpq在失败时都会为设置一个消息。 - 注意按照libpq习惯,一个非空结果由多行构成,并且将包括一个尾部新行。 - 调用者不应该直接释放结果。当相关的PGconn句柄被传递给时,它将被释放。在PGconn结构体上的多个操作之间,不能指望结果字符串会保持不变。 + 几乎所有 libpq 函数在失败时都会设置一条供 返回的消息。注意,按照 libpq 的约定,非空的 结果可能包含多行,并以换行符结尾。调用者不应直接释放该结果;当关联的 PGconn 句柄被传给 时,结果会被释放。不能假定在对 PGconn 结构体执行其他操作后,结果字符串仍保持不变。 @@ -2315,7 +2263,7 @@ char *PQerrorMessage(const PGconn *conn); PQsocketPQsocket - 获得到服务器连接套接字的文件描述符号。一个合法的描述符将会大于等于零。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 + 获取与服务器相连的套接字的文件描述符编号。有效描述符大于或等于 0。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 int PQsocket(const PGconn *conn); @@ -2332,7 +2280,7 @@ int PQsocket(const PGconn *conn); 返回处理这个连接的后端进程的进程ID(PID)。 PID 确定服务器进程的 PID - in libpq + 在 libpq 中 @@ -2341,7 +2289,7 @@ int PQbackendPID(const PGconn *conn); - 后端PID有助于调试目的并且可用于与NOTIFY消息(它包括发出提示的后端进程的PID)进行比较。注意PID属于一个在数据库服务器主机上执行的进程,而不是本地主机进程! + 后端 PID 可用于调试,也可与 NOTIFY 消息进行比较(消息包含发出通知的后端进程的 PID)。注意,该 PID 属于在数据库服务器主机上运行的进程,而非本地主机上的进程! @@ -2396,19 +2344,18 @@ int PQconnectionUsedGSSAPI(const PGconn *conn); - + - 以下函数返回与SSL相关的信息。这些信息通常在建立连接后不会更改。 - - + 以下函数返回与 SSL 相关的信息。这些信息通常在连接建立后不会改变。 + PQsslInUsePQsslInUse - 返回true(1)如果连接使用SSL,返回false(0)如果不使用。 + 如果连接使用 SSL,则返回真(1);否则返回假(0)。 int PQsslInUse(const PGconn *conn); @@ -2424,7 +2371,7 @@ int PQsslInUse(const PGconn *conn); - 返回与连接相关的SSL信息。 + 返回连接的 SSL 相关信息。 const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); @@ -2436,7 +2383,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); - 常见的属性如下: + 通常可以获取以下属性: library @@ -2523,18 +2470,14 @@ const char * const * PQsslAttributeNames(const PGconn *conn); - 返回一个指向描述连接的SSL实现特定对象的指针。如果连接未加密或SSL实现不提供连接的请求对象类型,则返回NULL。 + 返回指向描述此连接的对象的指针,该对象的类型由 SSL 实现决定。如果连接未加密,或连接所用的 SSL 实现不提供所请求的对象类型,则返回 NULL。 void *PQsslStruct(const PGconn *conn, const char *struct_name); - 可用的结构体取决于正在使用的SSL实现。 - 对于OpenSSL,有一个结构体, - 可以通过名称OpenSSL获得, - 并返回一个指向OpenSSLSSL结构体的指针。 - 要使用这个函数,可以使用以下代码: + 可用的结构体取决于所使用的 SSL 实现。对于 OpenSSL,可以通过名称 OpenSSL 获取一个结构体,函数返回指向 OpenSSLSSL 结构体的指针。可以使用如下代码调用此函数: #include @@ -2585,7 +2528,7 @@ void *PQgetssl(const PGconn *conn); - + @@ -2594,7 +2537,7 @@ void *PQgetssl(const PGconn *conn); 命令执行函数 - 一旦到一个数据库服务器的连接被成功建立,这里描述的函数可以被用来执行 SQL 查询和命令。 + 与数据库服务器的连接成功建立后,此处描述的函数用于执行 SQL 查询和命令。 @@ -2616,11 +2559,8 @@ PGresult *PQexec(PGconn *conn, const char *command); - 返回一个PGresult指针或者可能是一个空指针。 - 除了内存不足的情况或者由于严重错误无法将命令发送给服务器之外,一般都会返回一个非空指针。 - 函数应当被调用来检查返回值是否代表错误(包括空指针的值,它会返回PGRES_FATAL_ERROR)。 - 用可得到关于那些错误的详细信息。 - + 返回一个 PGresult 指针,也可能返回空指针。除内存不足或无法向服务器发送命令等严重错误外,通常都会返回非空指针。应调用 函数检查返回值是否表示错误(也应检查空指针,此时该函数返回 PGRES_FATAL_ERROR)。使用 获取此类错误的更多信息。 + @@ -2701,8 +2641,8 @@ PGresult *PQexecParams(PGconn *conn, paramValues[] - 指定参数的实际值。这个数组中的一个空指针表示对应的参数为空,否则该指针指向一个以零终止的文本字符串(用于文本格式)或者以服务器所期待格式的二进制数据(用于二进制格式)。 - + 指定参数的实际值。数组中的空指针表示对应参数为 null;否则,指针指向以零结尾的文本字符串(文本格式),或采用服务器所要求格式的二进制数据(二进制格式)。 + @@ -2710,8 +2650,8 @@ PGresult *PQexecParams(PGconn *conn, paramLengths[] - 指定二进制格式参数的实际数据长度。它对空参数和文本格式参数被忽略。当没有二进制参数时,该数组指针可以为空。 - + 指定二进制格式参数的实际数据长度。对于 null 参数和文本格式参数,该值会被忽略。如果没有二进制参数,数组指针可以为空指针。 + @@ -2719,11 +2659,11 @@ PGresult *PQexecParams(PGconn *conn, paramFormats[] - 指定参数是否为文本(在参数相应的数组项中放一个零)或二进制(在参数相应的数组项中放一个一)。如果该数组指针为空,那么所有参数都会被假定为文本串。 - + 指定参数采用文本格式(在对应数组元素中填入零)还是二进制格式(填入一)。如果数组指针为空指针,则将所有参数视为文本字符串。 + - 以二进制格式传递的值要求后端所期待的内部表示形式的知识。例如,整数必须以网络字节序被传递。传递numeric值要求关于服务器存储格式的知识,正如src/backend/utils/adt/numeric.c::numeric_send()以及src/backend/utils/adt/numeric.c::numeric_recv()中所实现的。 - + 以二进制格式传递值时,需要了解后端所要求的内部表示形式。例如,整数必须以网络字节序传递。传递 numeric 值时,需要了解服务器的存储格式,其实现见 src/backend/utils/adt/numeric.c::numeric_send()src/backend/utils/adt/numeric.c::numeric_recv()。 + @@ -2731,8 +2671,8 @@ PGresult *PQexecParams(PGconn *conn, resultFormat - 指定零来得到文本格式的结果,或者指定一来得到二进制格式的结果(目前没有规定要求以不同格式得到不同的结果列,尽管在底层协议中这是可以实现的)。 - + 指定零以获取文本格式的结果,指定一以获取二进制格式的结果。(目前无法让不同结果列使用不同格式,尽管底层协议支持这样做。) + @@ -2743,8 +2683,8 @@ PGresult *PQexecParams(PGconn *conn, - 相对于的主要优点是参数值可以从命令串中分离,因此避免了冗长的书写、容易发生错误的引用以及转义。 - + 相对于 的主要优点是可以将参数值与命令字符串分开,从而避免繁琐且容易出错的加引号和转义工作。 + 不同,至多允许在给定串中出现一个 SQL 命令(其中可以有分号,但是不能有超过一个非空命令)。这是底层协议的一个限制,但是有助于抵抗 SQL 注入攻击。 @@ -2753,12 +2693,12 @@ PGresult *PQexecParams(PGconn *conn, - 通过 OID 指定参数类型很罗嗦,特别是如果你不愿意将特定的 OID 值硬编码到你的程序中时。不过,即使服务器本身也无法确定参数的类型,你可以避免这样做,或者选择一种与你想要的不同的类型。在 SQL 命令文本中,附加一个显式类型转换给参数符号来表示你将发送什么样的数据类型。例如: + 通过 OID 指定参数类型较为繁琐,尤其是在不希望将具体 OID 值写死在程序中时。不过,即使服务器无法自行确定参数类型,或者推断出的类型与你所需的不同,也可以避免直接指定 OID。在 SQL 命令文本中,为参数符号添加显式类型转换,即可指定要发送的数据类型。例如: SELECT * FROM mytable WHERE x = $1::bigint; - 这强制参数$1被当作bigint,而默认情况下它将被赋予与x相同的类型。当以二进制格式发送参数值时,我们强烈推荐以这种方式或通过指定一个数字类型的 OID 来强制参数类型决定。因为二进制格式比文本格式具有更少的冗余,并且因此服务器将不会有更多机会为你检测一个类型匹配错误。 - +这会强制将参数 $1 当作 bigint,而默认情况下会为它分配与 x 相同的类型。以二进制格式发送参数值时,强烈建议采用这种方式,或直接指定类型的数值 OID,来明确决定参数类型。因为二进制格式的冗余比文本格式更少,服务器发现类型不匹配错误的机会也更少。 + @@ -2779,15 +2719,15 @@ PGresult *PQprepare(PGconn *conn, - 创建一个后面会由执行的预备语句。 + 创建一个预备语句,供随后使用 执行。 这个特性允许命令被反复执行而无需每次都进行解析和规划,详见。 - + 该函数从query串创建一个名为stmtName的预备语句,该串必须包含一个单一 SQL 命令。 stmtName可以是""来创建一个未命名语句,在这种情况下任何已存在未命名语句将被自动替换。 否则,如果语句名称已经在当前会话中被定义,则是一种错误。如果使用了任何参数,它们在查询中以$1$2等引用。 - nParams是参数的个数,其类型在数组paramTypes[]中被预先指定(当nParams为零时,该数组指针可以是NULL)。 + nParams 是在数组 paramTypes[] 中预先指定了类型的参数数量(当nParams为零时,该数组指针可以是NULL)。 paramTypes[]通过 OID 指定要赋予给参数符号的数据类型。 如果paramTypesNULL或者该数组中任何特定元素为零,服务器会用对待未指定类型的字符串字面量的方式为参数符号推测一种数据类型。 还有,查询能够使用编号高于nParams的参数符号,它们的数据类型也会被自动推测(找出推测出的数据类型的方法见)。 @@ -2795,7 +2735,7 @@ PGresult *PQprepare(PGconn *conn, 正如一样,结果通常是一个PGresult对象,其内容代表服务器端成功或失败。 - 一个空结果表示内存不足或者根本无法发送命令。关于错误的更多信息请见。 + 返回空指针表示内存不足,或者根本无法发送命令。关于错误的更多信息请见 @@ -2827,9 +2767,9 @@ PGresult *PQexecPrepared(PGconn *conn, 类似于, - 但要执行的命令是通过指定先前准备好的语句来指定,而不是提供查询字符串。 - 此功能允许重复使用的命令只被解析和计划一次,而不是每次执行时都要进行。 - 该语句必须在当前会话中先前准备好。 + 但它通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。 + 此功能使重复使用的命令只需解析和规划一次,而不必在每次执行时都进行这些工作。 + 该语句必须事先在当前会话中创建为预备语句。 @@ -2846,23 +2786,23 @@ PGresult *PQexecPrepared(PGconn *conn, - 提交请求以获取有关指定准备好的语句的信息,并等待完成。 + 提交请求以获取有关指定预备语句的信息,并等待完成。 PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - 允许应用程序获取关于先前准备的语句的信息。 + 允许应用程序获取关于先前创建的预备语句的信息。 stmtName可以是""NULL来引用 - 未命名的语句,否则必须是现有准备好的语句的名称。成功时,返回一个 + 未命名的语句,否则必须是现有预备语句的名称。成功时,返回一个 状态为PGRES_COMMAND_OKPGresult。 函数可以应用于此 - PGresult以获取有关准备语句参数的信息, + PGresult以获取有关预备语句参数的信息, 函数等提供有关语句的结果列(如果有)的信息。 @@ -2876,22 +2816,21 @@ PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - 提交请求以获取有关指定门户的信息,并等待完成。 + 提交请求以获取有关指定 portal 的信息,并等待完成。 PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - 允许应用程序获取有关先前创建的portal的信息。 - (libpq不直接提供对portals的访问,但您可以使用此函数检查使用DECLARE CURSOR SQL命令创建的游标的属性。) - + 允许应用程序获取先前创建的 portal 的信息。(libpq 不提供对 portal 的直接访问,但可以用此函数检查通过 DECLARE CURSOR SQL 命令创建的游标的属性。) + - portalName可以是""NULL来引用未命名的portal, - 否则必须是现有portal的名称。成功时,将返回一个带有状态PGRES_COMMAND_OKPGresult。 + portalName可以是""NULL来引用未命名的 portal, + 否则必须是现有 portal 的名称。成功时,将返回一个带有状态PGRES_COMMAND_OKPGresult。 函数等可应用于 - PGresult,以获取有关portal的结果列(如果有)的信息。 + PGresult,以获取有关 portal 的结果列(如果有)的信息。 @@ -2908,11 +2847,11 @@ PGresult *PQclosePrepared(PGconn *conn, const char *stmtName); - 允许应用程序关闭先前准备好的预备语句。关闭语句会释放它在服务器上的全部相关资源,并允许重复使用其名称。 + 允许应用程序关闭先前创建的预备语句。关闭语句会释放它在服务器上的全部相关资源,并允许重复使用其名称。 - stmtName可以是""NULL来引用未命名语句。如果不存在该名称的语句也没有关系;在这种情况下,该操作不会执行任何操作。成功时,会返回一个状态为PGRES_COMMAND_OKPGresult。 + stmtName可以是""NULL来引用未命名语句。如果不存在该名称的语句也没有关系;在这种情况下,不执行任何操作。成功时,会返回一个状态为PGRES_COMMAND_OKPGresult @@ -2929,11 +2868,11 @@ PGresult *PQclosePortal(PGconn *conn, const char *portalName); - 允许应用程序关闭先前创建的 portal。关闭 portal 会释放它在服务器上的全部相关资源,并允许重复使用其名称。(libpq不直接提供对 portal 的访问,但你可以使用这个函数来关闭通过DECLARE CURSOR SQL 命令创建的游标。) + 允许应用程序关闭先前创建的 portal。关闭 portal 会释放它在服务器上的全部相关资源,并允许重复使用其名称。(libpq不直接提供对 portal 的访问,但你可以使用这个函数来关闭通过DECLARE CURSOR SQL 命令创建的游标。) - portalName可以是""NULL来引用未命名的 portal。如果不存在该名称的 portal 也没有关系;在这种情况下,该操作不会执行任何操作。成功时,会返回一个状态为PGRES_COMMAND_OKPGresult。 + portalName可以是""NULL来引用未命名的 portal。如果不存在该名称的 portal 也没有关系;在这种情况下,不执行任何操作。成功时,会返回一个状态为PGRES_COMMAND_OKPGresult @@ -2941,9 +2880,8 @@ PGresult *PQclosePortal(PGconn *conn, const char *portalName); - PGresultPGresult结构体封装了由服务器返回的结果。libpq应用程序员应该小心地维护PGresult的抽象。使用下面的存储器函数来得到PGresult的内容。避免直接引用PGresult结构体的域,因为它们可能在未来更改。 - - + PGresultPGresult 结构体封装服务器返回的结果。编写 libpq 应用程序时,应注意维护 PGresult 的抽象。请使用下述访问函数获取 PGresult 的内容。避免直接引用 PGresult 结构体的字段,因为这些字段将来可能改变。 + PQresultStatusPQresultStatus @@ -3044,7 +2982,7 @@ ExecStatusType PQresultStatus(const PGresult *res); PGRES_SINGLE_TUPLE - PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单一行模式时发生(见)。 + PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单行模式时发生(见)。 @@ -3092,12 +3030,11 @@ ExecStatusType PQresultStatus(const PGresult *res); - 将返回的枚举转换成描述状态编码的字符串常量。调用者不应该释放结果。 - + 将 返回的枚举值转换为描述该状态码的字符串常量。调用者不应释放此结果。 char *PQresStatus(ExecStatusType status); - + @@ -3106,12 +3043,12 @@ char *PQresStatus(ExecStatusType status); - 返回与该命令相关的错误消息,如果有错误则会返回一个空字符串。 + 返回与命令关联的错误消息;如果没有错误,则返回空字符串。 char *PQresultErrorMessage(const PGresult *res); - 如果有一个错误,被返回的字符串将包含一个收尾的新行。调用者不应该直接释放结果。它将在相关的PGresult句柄被传递给之后被释放。 - +如果发生了错误,返回的字符串会以换行符结尾。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 + 紧跟着一个调用,(在连接上)将返回与相同的字符串(在结果上)。 @@ -3127,16 +3064,14 @@ char *PQresultErrorMessage(const PGresult *res); - 返回与PGresult对象相关的错误消息的重新格式化的版本。 + 返回与 PGresult 对象关联的错误消息的重新格式化版本。 char *PQresultVerboseErrorMessage(const PGresult *res, PGVerbosity verbosity, PGContextVisibility show_context); - 在有些情况下,客户端可能希望得到之前报告过的错误的更加详尽的版本。 - 如果在产生给定PGresult的连接上 verbosity 设置有效,会通过计算已经被产生过的消息来满足这种需求。 - 如果PGresult不是一个错误结果,则会报告PG 结果不是错误结果。返回的字符串包括一个新行作为结尾。 - +有时客户端希望获取先前报告过的错误的更详细版本。 可满足这一需求:它按指定的详细程度设置重新生成消息。假如在生成给定 PGresult 时,连接已经采用这些设置,那么 返回的就会是这条消息。如果 PGresult 不是错误结果,则改为报告 PGresult is not an error result。返回的字符串以换行符结尾。 + 和大部分从PGresult中提取数据的其他函数不同,这个函数的结果是一个全新分配的字符串。调用者在不需要这个字符串以后,必须使用PQfreemem()释放它。 @@ -3152,24 +3087,21 @@ char *PQresultVerboseErrorMessage(const PGresult *res, PQresultErrorFieldPQresultErrorField - 返回一个错误报告的一个域。 + 返回错误报告中的单个字段。 char *PQresultErrorField(const PGresult *res, int fieldcode); - fieldcode是一个错误域标识符,见下列符号。 - 如果PGresult不是一个错误或者警告结果或者不包括指定域,会返回NULL。 - 域通常不包括一个收尾的新行。调用者不应该直接释放结果。 - 它将在相关的PGresult句柄被传递给之后被释放。 - +fieldcode 是错误字段标识符,参见下文列出的符号。如果 PGresult 不是错误或警告结果,或者不包含指定字段,则返回 NULL。字段值通常不含末尾换行符。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 + - 下列域代码可用: + 下列字段代码可用: PG_DIAG_SEVERITY - 严重性。域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 @@ -3178,17 +3110,17 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_SEVERITY_NONLOCALIZED - 域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY域相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 版本以后产生的报告中。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY字段相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 及更高版本产生的报告中。 PG_DIAG_SQLSTATEerror codeslibpq + >错误码libpq - 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个域无法被本地化,并且总是存在。 + 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个字段无法被本地化,并且总是存在。 @@ -3215,7 +3147,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_MESSAGE_HINT - 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是铁的事实。可能有多行。 + 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是确切事实。可能有多行。 @@ -3233,7 +3165,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_INTERNAL_POSITION - 这被定义为与PG_DIAG_STATEMENT_POSITION域相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个域出现时,PG_DIAG_INTERNAL_QUERY域将总是出现。 + 这被定义为与PG_DIAG_STATEMENT_POSITION字段相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个字段出现时,PG_DIAG_INTERNAL_QUERY字段将总是出现。 @@ -3251,7 +3183,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONTEXT - 指示错误发生的环境。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 + 指示错误发生的上下文。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 @@ -3269,7 +3201,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_TABLE_NAME - 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名域)。 + 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名字段)。 @@ -3278,7 +3210,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_COLUMN_NAME - 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名域来标识该表)。 + 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名字段来标识该表)。 @@ -3287,7 +3219,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_DATATYPE_NAME - 如果错误与一个特定数据类型相关,这里是该数据了行的名字(该数据类型的模式名参考模式名域)。 + 如果错误与一个特定数据类型相关,这里是该数据类型的名字(该数据类型的模式名参考模式名字段)。 @@ -3296,7 +3228,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONSTRAINT_NAME - 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的域(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 + 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的字段(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 @@ -3332,16 +3264,16 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); - 用于模式名、表名、列名、数据类型名和约束名的域只提供给有限的错误类型,见。不要假定任何这些域的存在保证另一个域的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些域。同样地,不要假定这些域代表当前数据库中同类的对象。 + 用于模式名、表名、列名、数据类型名和约束名的字段只提供给有限的错误类型,见。不要假定任何这些字段的存在保证另一个字段的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些字段。同样地,不要假定这些字段代表当前数据库中现存的对象。 - 客户端负责格式化显示信息来迎合它的需要,特别是根据需要打断长的行。出现在错误消息域中的新行字符应该被当作分段而不是换行。 + 客户端负责按自身需要格式化所显示的信息,尤其应在需要时将长行折行。错误消息字段中的换行符应当视为段落分隔,而非行分隔。 - libpq内部产生的错误将有严重和主要消息,但是通常没有其他域。 + libpq内部产生的错误将包含严重性和主要消息,但是通常没有其他字段。 @@ -3354,14 +3286,12 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PQclearPQclear - 释放与一个PGresult关联的存储。每个命令结果在不再需要时都应通过释放。 - + 释放与 PGresult 关联的存储空间。每个命令结果在不再需要时都应通过 释放。 void PQclear(PGresult *res); - - 如果参数是NULL指针,则不会执行任何操作。 - +如果参数是 NULL 指针,则不执行任何操作。 + 你可以在需要时一直保留PGresult对象;它不会在你发出新命令时消失,甚至在关闭连接后也不会消失。要销毁它,你必须调用。否则应用程序会发生内存泄漏。 @@ -3369,7 +3299,7 @@ void PQclear(PGresult *res); - + @@ -3377,8 +3307,8 @@ void PQclear(PGresult *res); 检索查询结果信息 - 这些函数被用来从一个代表成功查询结果(也就是状态为PGRES_TUPLES_OK或者PGRES_SINGLE_TUPLE)的PGresult对象中抽取信息。它们也可以被用来从一个成功的 Describe 操作中抽取信息:一个 Describe 的结果具有和该查询被实际执行所提供的完全相同的列信息,但是它没有行。对于其他状态值的对象,这些函数会认为结果具有零行和零列。 - + 这些函数用于从表示成功查询结果的 PGresult 对象中提取信息,即状态为 PGRES_TUPLES_OKPGRES_SINGLE_TUPLEPGRES_TUPLES_CHUNK 的对象。它们也可用于提取成功 Describe 操作的结果信息:Describe 结果包含的列信息与实际执行查询时相同,但行数为零。对于其他状态值的对象,这些函数会将结果视为零行、零列。 + @@ -3405,7 +3335,7 @@ int PQntuples(const PGresult *res); - 返回查询结果中每一行的列(域)数。 + 返回查询结果中每一行的列(字段)数。 int PQnfields(const PGresult *res); @@ -3421,7 +3351,7 @@ int PQnfields(const PGresult *res); - 返回与给定列号相关联的列名。列号从 0 开始。调用者不应该直接释放该结果。它将在相关的PGresult句柄被传递给之后被释放。 + 返回给定列号对应的列名。列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 char *PQfname(const PGresult *res, int column_number); @@ -3453,11 +3383,11 @@ int PQfnumber(const PGresult *res, - 给定的名称被视作一个 SQL 命令中的一个标识符,也就是说,除非被双引号引用,它是小写形式的。例如,给定一个 SQL 命令: + 给定名称按 SQL 命令中的标识符处理,即除非用双引号引用,否则会转换为小写。例如,对于以下 SQL 命令生成的查询结果: SELECT 1 AS FOO, 2 AS "BAR"; - 我们将得到结果: +会得到以下结果: PQfname(res, 0) foo PQfname(res, 1) BAR @@ -3477,7 +3407,7 @@ PQfnumber(res, "\"BAR\"") 1 - 返回给定列从中取出的表的 OID。列号从 0 开始。 + 返回给定列所取自的表的 OID。列号从 0 开始。 Oid PQftable(const PGresult *res, int column_number); @@ -3490,7 +3420,7 @@ Oid PQftable(const PGresult *res, - 当你包括libpq头文件,类型oid以及常数InvalidOid将被定义。它们将都是某种整数类型。 + 包含 libpq 头文件后,将定义类型 Oid 和常量 InvalidOid。它们都属于某种整数类型。 @@ -3502,7 +3432,7 @@ Oid PQftable(const PGresult *res, - 返回构成指定查询结果列的列(在其表中)的列号。查询结果列号从 0 开始,但是表列具有非零编号。 + 返回指定查询结果列所对应的表列在表中的列号。查询结果的列号从 0 开始,而表列的编号非零。 int PQftablecol(const PGresult *res, int column_number); @@ -3522,7 +3452,7 @@ int PQftablecol(const PGresult *res, - 返回指示给定列格式的格式编码。列号从 0 开始。 + 返回表示给定列格式的格式代码。列号从 0 开始。 int PQfformat(const PGresult *res, int column_number); @@ -3530,7 +3460,7 @@ int PQfformat(const PGresult *res, - 格式代码零指示文本数据表示,而格式代码一表示二进制表示(其他代码被保留用于未来的定义)。 + 格式代码零表示文本数据,格式代码一表示二进制数据。(其他代码保留供将来定义。) @@ -3550,7 +3480,7 @@ Oid PQftype(const PGresult *res, - 你可以查询系统表pg_type来得到多个数据类型的名字和属性。 + 你可以查询系统表pg_type来获取各种数据类型的名称和属性。 内置数据类型的OID被定义在PostgreSQL安装的include目录中的catalog/pg_type_d.h文件中。 @@ -3563,7 +3493,7 @@ Oid PQftype(const PGresult *res, - 返回与给定列号相关联的列的修饰符类型。列号从 0 开始。 + 返回与给定列号相关联的列的类型修饰符。列号从 0 开始。 int PQfmod(const PGresult *res, int column_number); @@ -3571,7 +3501,7 @@ int PQfmod(const PGresult *res, - 修饰符值的解释是与类型相关的,它们通常指示精度或尺寸限制。值 -1 被用来指示没有信息可用。大部分的数据类型不适用修饰符,在那种情况中值总是 -1。 + 修饰符值的含义由数据类型决定,通常表示精度或大小限制。值 -1 表示没有可用信息。大多数数据类型不使用修饰符,此时该值始终为 -1。 @@ -3583,7 +3513,7 @@ int PQfmod(const PGresult *res, - 返回与给定列号相关的列的尺寸(以字节计)。列号从 0 开始。 + 返回给定列号对应列的大小,以字节计。列号从 0 开始。 int PQfsize(const PGresult *res, int column_number); @@ -3591,7 +3521,7 @@ int PQfsize(const PGresult *res, - 返回在一个数据库行中为这个列分配的空间,换句话说是服务器对该数据类型的内部表示的尺寸(因此,它对客户端并不是真地非常有用)。一个负值指示该数据类型是变长的。 + 返回数据库行中为该列分配的空间,即服务器内部表示该数据类型所需的大小。(因此,它对客户端用处不大。)负值表示该数据类型是变长类型。 @@ -3610,8 +3540,7 @@ int PQbinaryTuples(const PGresult *res); - 这个函数已经被废弃(除了与COPY一起使用),因为一个单一PGresult可以在某些列中包含文本数据而且在另一些列中包含二进制数据。 - 要更好。只有结果的所有列是二进制(格式 1)时才返回 1。 + 此函数已弃用(与 COPY 配合使用的情况除外),因为单个 PGresult 可能在部分列中包含文本数据,而在其他列中包含二进制数据。推荐使用 。只有结果中的所有列都采用二进制格式(格式 1)时, 才返回 1。 @@ -3623,8 +3552,7 @@ int PQbinaryTuples(const PGresult *res); - 返回一个PGresult的一行的单一域值。行和列号从 0 开始。调用者不应该直接释放该结果。 - 它将在相关的PGresult句柄被传递给之后被释放。 + 返回 PGresult 中某一行的单个字段值。行号和列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 char *PQgetvalue(const PGresult *res, int row_number, @@ -3633,15 +3561,15 @@ char *PQgetvalue(const PGresult *res, - 对于文本格式的数据,返回的值是该域值的一种空值结束的字符串表示。对于二进制格式的数据,该值是由该数据类型的typsendtypreceive函数决定的二进制表示(在这种情况下该值实际上也跟随着一个零字节,但是这通常没有用处,因为该值很可能包含嵌入的空)。 + 对于文本格式的数据, 返回字段值的字符串表示,以零字节结尾。对于二进制格式的数据,返回值采用该数据类型的 typsendtypreceive 函数所决定的二进制表示。(这种情况下,值后面实际上也有一个零字节,但通常没有用处,因为值本身很可能包含零字节。) - 如果该域值为空,则返回一个空串。关于区分空值和空字符串值请见。 + 如果字段值为 null,则返回空字符串。关于如何区分 null 值与空字符串值,参见 - 返回的指针指向作为PGresult结构体一部分的存储。我们不应该修改它指向的数据,并且如果要在超过PGresult结构体本身的生命期之外使用它,我们必须显式地把该数据拷贝到其他存储中。 + 返回的指针指向属于 PGresult 结构体的存储空间。不应修改它所指向的数据;如果需要在 PGresult 结构体的生命周期结束后继续使用这些数据,就必须显式地将数据复制到其他存储空间。 @@ -3650,12 +3578,12 @@ char *PQgetvalue(const PGresult *res, PQgetisnullPQgetisnullnull valuein libpq + >null 值libpq 中的 - 测试一个域是否为空值。行号和列号从 0 开始。 + 检查字段是否为 null 值。行号和列号从 0 开始。 int PQgetisnull(const PGresult *res, int row_number, @@ -3664,7 +3592,7 @@ int PQgetisnull(const PGresult *res, - 如果该域是空,这个函数返回 1。如果它包含一个非空值,则返回 0(注意将为一个空域返回一个空串,不是一个空指针)。 + 如果字段为 null,此函数返回 1;如果包含非 null 值,则返回 0。(注意,对于 null 字段, 返回空字符串,而非空指针。) @@ -3676,7 +3604,7 @@ int PQgetisnull(const PGresult *res, - 返回一个域值的真实长度,以字节计。行号和列号从 0 开始。 + 返回字段值的实际长度,以字节计。行号和列号从 0 开始。 int PQgetlength(const PGresult *res, int row_number, @@ -3685,9 +3613,7 @@ int PQgetlength(const PGresult *res, - 这是特定数据值的真实数据长度,也就是指向的对象的尺寸。 - 对于文本数据格式,这和strlen()相同。对于二进制格式这是基本信息。 - 注意我们应该依赖于来得到真值的数据长度。 + 这是该数据值的实际数据长度,即 所指对象的大小。对于文本格式的数据,它与 strlen() 的结果相同。对于二进制格式,这是必不可少的信息。注意,不应依赖 来获取实际数据长度。 @@ -3706,7 +3632,7 @@ int PQnparams(const PGresult *res); - 只有在查看的结果时,这个函数才有用。对于其他类型的查询,它将返回零。 + 只有在查看的结果时,这个函数才有用。对于其他类型的结果,它将返回零。 @@ -3725,7 +3651,7 @@ Oid PQparamtype(const PGresult *res, int param_number); - 只有在查看的结果时,这个函数才有用。对于其他类型的查询,它将返回零。 + 只有在查看的结果时,这个函数才有用。对于其他类型的结果,它将返回零。 @@ -3737,29 +3663,29 @@ Oid PQparamtype(const PGresult *res, int param_number); - 将所有的行打印到指定的输出流,以及有选择地将列名打印到指定的输出流。 + 将所有行输出到指定的输出流,并可选择输出列名。 void PQprint(FILE *fout, /* 输出流 */ const PGresult *res, const PQprintOpt *po); typedef struct { - pqbool header; /* 打印输出域标题和行计数 */ - pqbool align; /* 填充对齐域 */ - pqbool standard; /* 旧的格式 */ + pqbool header; /* 打印输出字段标题和行数 */ + pqbool align; /* 填充并对齐字段 */ + pqbool standard; /* 旧的简陋格式 */ pqbool html3; /* 输出 HTML 表格 */ - pqbool expanded; /* 扩展表格 */ - pqbool pager; /* 如果必要为输出使用页 */ - char *fieldSep; /* 域分隔符 */ + pqbool expanded; /* 展开表格 */ + pqbool pager; /* 需要时使用分页器输出 */ + char *fieldSep; /* 字段分隔符 */ char *tableOpt; /* 用于 HTML 表格元素的属性 */ char *caption; /* HTML 表格标题 */ - char **fieldName; /* 替换域名称的空终止数组 */ + char **fieldName; /* 以空指针结尾的替换字段名数组 */ } PQprintOpt; - 这个函数以前被psql用来打印查询结果,但是现在不是这样了。注意它假定所有的数据都是文本格式。 + psql 以前用此函数打印查询结果,现在已不再使用。注意,此函数假定所有数据都是文本格式。 @@ -3808,13 +3734,7 @@ char *PQcmdTuples(PGresult *res); - 该函数返回一个字符串,其中包含由生成PGresultSQL语句影响的行数。 - 该函数只能在执行SELECTCREATE TABLE AS、 - INSERTUPDATEDELETE、 - MERGEMOVEFETCHCOPY语句, - 或包含INSERTUPDATEDELETEMERGE语句的预处理查询的EXECUTE之后使用。 - 如果生成PGresult的命令是其他任何命令,将返回一个空字符串。 - 调用者不应直接释放返回值。当关联的PGresult句柄传递给时,它将被释放。 + 此函数返回一个字符串,其中包含产生该 PGresultSQL 语句所影响的行数。此函数只能在执行 SELECTCREATE TABLE ASINSERTUPDATEDELETEMERGEMOVEFETCHCOPY 语句之后使用,也可以在对包含 INSERTUPDATEDELETEMERGE 语句的预备查询执行 EXECUTE 之后使用。如果产生 PGresult 的是其他命令, 将返回空字符串。调用者不应直接释放返回值;当关联的 PGresult 句柄被传给 时,返回值会被释放。 @@ -3826,7 +3746,7 @@ char *PQcmdTuples(PGresult *res); - 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDin libpq。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid。 + 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDlibpq 中的。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid Oid PQoidValue(const PGresult *res); @@ -3841,7 +3761,7 @@ Oid PQoidValue(const PGresult *res); - 这个函数已经被取代,并且不是线程安全的。它返回包含被插入行的 OID 的一个字符串,而返回 OID 值。 + 此函数不是线程安全的,现已弃用,推荐改用 。它返回包含插入行 OID 的字符串,而 返回 OID 值。 char *PQoidStatus(const PGresult *res); @@ -3859,7 +3779,7 @@ char *PQoidStatus(const PGresult *res); 转义字符串 - in libpq + libpq 中的 @@ -3877,17 +3797,13 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); 为了让一个字符串可用于 SQL 命令,会对它进行转义。 - 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜线)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 + 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜杠)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 执行这种操作。 - 返回一个str参数的已被转义版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - 返回字符串中的所有特殊字符都会被替换,这样它们就能被PostgreSQL字符串字面量解析器正确处理。 - 结果中也会附加一个终止零字节,并包含包围PostgreSQL字符串字面量所需的单引号。 - + 返回 str 参数的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便 PostgreSQL 字符串字面量解析器正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号包含在结果字符串中。 + 发生错误时,返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -3901,7 +3817,7 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); - 注意,当一个数据值被作为或其兄弟例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 + 注意,当一个数据值被作为或相关例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 @@ -3919,15 +3835,12 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - 转义一个要用作 SQL 标识符的字符串,例如表名、列名或函数名。当一个用户提供的标识符可能包含被 SQL 解析器解释为标识符一部分的特殊字符时,或者当该标识符可能包含大小写形式应该被保留的大写字符时,这个函数很有用。 - + 对字符串进行转义,使其可用作 SQL 标识符,例如表名、列名或函数名。当用户提供的标识符可能包含未经转义就不会被 SQL 解析器视为标识符一部分的特殊字符,或包含需要保留大小写的大写字符时,此函数很有用。 + - 返回一个str参数的已被转义为 SQL 标识符的版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - 返回串中的所有特殊字符都被替换掉,这样它们能被作为一个 SQL 标识符正确地处理。还会加上一个终止零字节。返回串也将被双引号包围。 - + 返回 str 参数作为 SQL 标识符的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,必须使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便正确地作为 SQL 标识符处理。还会添加一个末尾零字节,并用双引号包围返回的字符串。 + 发生错误时,返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -3936,7 +3849,7 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - 与字符串一样,要阻止 SQL 注入攻击,当从一个不可信的来源接收到 SQL 标识符时,它们必须被转义。 + 与字符串字面量一样,为防止 SQL 注入攻击,从不可信来源接收到的 SQL 标识符必须经过转义。 @@ -3957,18 +3870,12 @@ size_t PQescapeStringConn(PGconn *conn, - 转义字符串,它很像。 - 与不一样的是,调用者负责提供一个合适尺寸的缓冲区。 - 此外,不产生必须包围PostgreSQL字符串的单引号。 - 它们应该在结果要插入的 SQL 命令中提供。参数from指向要被转义的串的第一个字符,并且length参数给出了这个串中的字节数。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - to应当指向一个缓冲区,它能够保持至少比length值的两倍还要多至少一个字节,否则该行为是未被定义的。 - 如果tofrom串重叠,行为也是未被定义的。 - + 对字符串字面量进行转义,与 类似。与 不同,调用者需要提供大小合适的缓冲区。此外, 不会生成包围 PostgreSQL 字符串字面量所需的单引号;应在包含转义结果的 SQL 命令中提供这些引号。from 参数指向待转义字符串的首字符,length 参数给出该字符串的字节数。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)to 必须指向一个缓冲区,其容量至少为 length 的两倍加一个字节,否则行为未定义。如果 tofrom 字符串重叠,行为同样未定义。 + - 如果error参数不是NULL,那么成功时*error被设置为零,错误时设置为非零。当前唯一可能的错误情况涉及源串中非法的多字节编码。错误时仍然会产生输出串,但是可以预期服务器将认为它是畸形的并且拒绝它。在发生错误时,一个合适的消息被存储在conn对象中,不管error是不是NULL。 - + 如果 error 参数不是 NULL,则成功时将 *error 设为零,出错时设为非零。目前唯一可能的错误是源字符串中存在无效的多字节编码。出错时仍会生成输出字符串,但预计服务器会因其格式错误而拒绝它。发生错误时,无论 error 是否为 NULL,都会在 conn 对象中保存相应消息。 + 返回写到to的字节数,不包括终止的零字节。 @@ -3983,21 +3890,19 @@ size_t PQescapeStringConn(PGconn *conn, - 是一个更老的被废弃的版本。 + 的旧版本,现已弃用。 size_t PQescapeString (char *to, const char *from, size_t length); - + - 之间的唯一区别是不需要PGconnerror参数。 - 正因为如此,它不能基于连接属性(例如字符编码)调整它的行为并且因此它可能给出错误的结果。还有,它没有方法报告错误情况。 - + 与 唯一的区别是, 不接受 PGconnerror 参数。因此,它无法根据连接属性(例如字符编码)调整行为,可能给出错误的结果。此外,它也无法报告错误情况。 + - 可以在一次只使用一个PostgreSQL连接的客户端程序中安全地使用(在这种情况下它可以在现象后面找出它需要知道的东西)。 - 在其他环境中它是一个安全性灾难并且应该用来避免。 - + 可以在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。在其他情形下,它存在安全隐患,应改用 。 + @@ -4008,7 +3913,7 @@ size_t PQescapeString (char *to, const char *from, size_t length); - 把要用于一个 SQL 命令的二进制数据用类型bytea转义。和一样,只有在将数据直接插入到一个 SQL 命令串时才使用它。 + 对二进制数据进行转义,使其能够在 SQL 命令中用作 bytea 类型的值。与 一样,这仅用于将数据直接插入 SQL 命令字符串的情况。 unsigned char *PQescapeByteaConn(PGconn *conn, const unsigned char *from, @@ -4023,14 +3928,11 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - from参数指向要被转义的串的第一个字节,并且from_length参数给出这个二进制串中的字节数(一个终止的零字节是不需要的也是不被计算的)。to_length参数指向一个将保持生成的已转义串长度的变量。这个结果串长度包括结果的终止零字节。 + from 参数指向待转义字符串的首字节,from_length 参数给出该二进制字符串的字节数。(末尾零字节既不需要,也不计入长度。)to_length 参数指向用于保存转义后字符串长度的变量。该结果字符串长度包含结果末尾的零字节。 - 返回一个from参数的已被转义为二进制串的版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 返回串中的所有特殊字符都被替换掉,这样它们能被PostgreSQL的字符串解析器以及bytea输入函数正确地处理。 - 还会加上一个终止零字节。不是结果串一部分的PostgreSQL字符串必须被单引号包围。 + 返回 from 参数所指二进制字符串的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。返回字符串中的所有特殊字符都已替换,以便 PostgreSQL 字符串字面量解析器和 bytea 输入函数正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号不包含在结果字符串中。 @@ -4046,7 +3948,7 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - 是一个更老的被废弃的版本。 + 的旧版本,现已弃用。 unsigned char *PQescapeBytea(const unsigned char *from, size_t from_length, @@ -4055,9 +3957,7 @@ unsigned char *PQescapeBytea(const unsigned char *from, - 与的唯一区别是不用一个PGconn参数。 - 正因为这样,只能在一次只使用一个PostgreSQL连接的客户端程序中安全地使用(在这种情况下它可以在现象后面找出它需要知道的东西)。 - 如果在有多个数据库连接的程序中使用,它可能给出错误的结果(在那种情况下使用)。 + 与 唯一的区别是, 不接受 PGconn 参数。因此, 只能在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。如果在使用多个数据库连接的程序中使用,它可能给出错误的结果(此时应使用 )。 @@ -4129,25 +4029,15 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - 总是收集命令的整个结果,把它缓存在一个单一的PGresult中。虽然这简化了应用的错误处理逻辑,它对于包含很多行的结果并不现实。 - + 总是收集命令的完整结果,并将其缓存在单个 PGresult 中。这简化了应用程序的错误处理逻辑,但对于包含大量行的结果,可能不切实际。 + - 如果应用程序不希望受到这些限制,可以改用构成的底层函数:。此外,还有, - , - , - , - , - ,以及,它们可以与配合使用,分别实现以下函数的功能:, - , - , - , - , - ,以及。 - - + + 如果应用程序不希望受到这些限制,可以改用构成 的底层函数:。此外, 可以与 配合使用,分别实现 的功能。 + PQsendQueryPQsendQuery @@ -4155,14 +4045,11 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - 提交一个命令到服务器,而不等待结果。 - 如果成功发送命令,则返回1,如果失败则返回0(在这种情况下,使用获取更多关于失败的信息)。 + 向服务器提交命令,不等待结果。命令发送成功时返回 1,否则返回 0(此时可使用 获取更多失败信息)。 int PQsendQuery(PGconn *conn, const char *command); - - 成功调用后,调用一次或多次来获取结果。 - 在返回空指针,表示命令执行完成之前,无法再次调用(在同一连接上)。 +成功调用 后,应调用 一次或多次来获取结果。在 返回空指针、表明命令已完成之前,不得在同一连接上再次调用 @@ -4178,7 +4065,7 @@ int PQsendQuery(PGconn *conn, const char *command); - 提交一个命令和参数到服务器,而不等待结果。 + 向服务器提交命令及独立指定的参数,不等待结果。 int PQsendQueryParams(PGconn *conn, const char *command, @@ -4189,9 +4076,7 @@ int PQsendQueryParams(PGconn *conn, const int *paramFormats, int resultFormat); - - 这相当于,不同之处在于可以单独指定查询参数而不是与查询字符串一起指定。 - 函数的参数处理方式与完全相同。与一样,它在查询字符串中只允许一个命令。 +该函数等价于 ,但查询参数可以与查询字符串分开指定。函数参数的处理方式与 相同。与 一样,查询字符串中只允许包含一条命令。 @@ -4203,7 +4088,7 @@ int PQsendQueryParams(PGconn *conn, - 发送一个请求来创建一个带有给定参数的预备语句,而不等待完成。 + 发送按给定参数创建预备语句的请求,不等待完成。 int PQsendPrepare(PGconn *conn, const char *stmtName, @@ -4211,10 +4096,7 @@ int PQsendPrepare(PGconn *conn, int nParams, const Oid *paramTypes); - - 这是的异步版本:如果能够分派请求,则返回1,否则返回0。 - 成功调用后,调用来确定服务器是否成功创建了预备语句。 - 该函数的参数处理方式与完全相同。 +这是 的异步版本:请求发送成功时返回 1,否则返回 0。调用成功后,再调用 ,确定服务器是否成功创建了预备语句。函数参数的处理方式与 相同。 @@ -4226,7 +4108,7 @@ int PQsendPrepare(PGconn *conn, - 发送一个请求来执行一个准备好的语句,带有给定的参数,而不等待结果。 + 发送使用给定参数执行预备语句的请求,不等待结果。 int PQsendQueryPrepared(PGconn *conn, const char *stmtName, @@ -4236,9 +4118,7 @@ int PQsendQueryPrepared(PGconn *conn, const int *paramFormats, int resultFormat); - - 这类似于,但要执行的命令是通过指定一个之前准备好的语句的名称来指定,而不是提供一个查询字符串。 - 函数的参数处理方式与完全相同。 +该函数类似于 ,但通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。函数参数的处理方式与 相同。 @@ -4270,7 +4150,7 @@ int PQsendDescribePrepared(PGconn *conn, const char *stmtName); - 提交请求以获取有关指定门户的信息,而无需等待完成。 + 提交请求以获取有关指定 portal 的信息,而无需等待完成。 int PQsendDescribePortal(PGconn *conn, const char *portalName); @@ -4336,13 +4216,7 @@ PGresult *PQgetResult(PGconn *conn); - 必须重复调用直到返回空指针,表示命令已完成。 - (如果在没有活动命令时调用, - 将立即返回空指针。)每个非空结果从 - 应该使用先前描述的相同PGresult访问器函数进行处理。 - 完成后不要忘记使用释放每个结果对象。请注意, - 仅在有命令处于活动状态且必要的响应数据尚未被 - 读取时才会阻塞。 + 必须反复调用 ,直到它返回空指针,表明命令已经完成。(如果当前没有正在执行的命令,调用 会立即返回空指针。)对于 返回的非空指针,应使用前文介绍的 PGresult 访问函数处理相应结果。使用完毕后,不要忘记调用 释放每个结果对象。注意,只有存在正在执行的命令,且所需响应数据尚未被 读取时, 才会阻塞。 @@ -4365,41 +4239,37 @@ PGresult *PQgetResult(PGconn *conn); - + - 使用解决了的一个问题:如果一个命令字符串包含多个SQL命令,这些命令的结果可以被个别地获得(顺便说一句:这样就允许一种简单的重叠处理形式, 客户端可以处理一个命令的结果,而同时服务器可以继续处理同一命令字符串中后面的查询)。 - + 使用 可以解决 的一个问题:如果命令字符串包含多个 SQL 命令,就能分别获取这些命令的结果。(这也支持一种简单的重叠处理方式:客户端可以处理某条命令的结果,同时服务器继续处理同一命令字符串中后面的查询。) + - 可以被获得的另一种常常想要的特性是一次从大型结果中检索一行。这会在中讨论。 - + 使用 还可以实现另一项常见需求:从大型查询结果中一次读取有限行数。详见 。 + - 就其本身而言,调用将仍会导致客户端阻塞,直到服务器完成下一个SQL命令。可以通过正确使用两个函数来避免这种情况: - - + 仅仅调用 仍会使客户端阻塞,直到服务器完成下一条 SQL 命令。可以通过正确使用另外两个函数来避免这种情况: + PQconsumeInputPQconsumeInput - 如果有来自服务器的输入可用,则使用之。 + 如果服务器有可读取的输入,则读取这些输入。 int PQconsumeInput(PGconn *conn); - 通常返回 1 表明没有错误,而返回 0 表明有某种麻烦发生(此时可以用)。 - 注意该结果并不表明是否真正收集了任何输入数据。在调用之后,应用可以检查和/或PQnotifies来看看它们的状态是否改变。 + 通常返回 1,表示没有错误;发生问题时则返回 0(此时可查看 )。注意,返回值并不说明是否实际读取了输入数据。调用 后,应用程序可以检查 和/或 PQnotifies,以确定其状态是否发生变化。 - 即使应用还不准备处理一个结果或通知,也可以被调用。 - 这个函数将读取可用的数 据并且把它保存在一个缓冲区中,从而导致一个select()的读准备好指示消失。 - 因此应用可以使用立即清除select()条件,并且在空闲时再检查结果。 + 即使应用程序尚未准备好处理结果或通知,也可以调用 。此函数会读取可用数据并将其保存在缓冲区中,从而清除 select() 的可读就绪指示。因此,应用程序可以用 立即清除 select() 的就绪条件,随后在合适的时候检查结果。 @@ -4421,15 +4291,11 @@ int PQisBusy(PGconn *conn); - + - 一个使用这些函数的典型应用将有一个主循环,在主循环中会使用select()poll()等待所有它必须响应的情况。 - 其中之一将是来自服务器的输入可用,对select()来说意味着标识的文件描述符上有可读的数据。 - 当主循环检测到输入准备好时,它将调用读取输入。 - 然后它可以调用,如果返回假(0)则接着调用。 - 它还可以调用PQnotifies检测NOTIFY消息(见)。 - + 使用这些函数的典型应用程序会在主循环中通过 select()poll() 等待需要响应的各种条件。其中一个条件是服务器有可读取的输入;对于 select(),这意味着 标识的文件描述符上有可读数据。主循环检测到输入就绪时,应调用 读取输入,然后调用 。如果 返回假(0),就可以接着调用 。还可以调用 PQnotifies 检测 NOTIFY 消息(见 )。 + 一个使用/的客户端也可以尝试取消一个正在被服务器处理的命令,见。 @@ -4437,13 +4303,8 @@ int PQisBusy(PGconn *conn); - 通过使用上面描述的函数,可以避免在等待来自数据库服务器的输入时阻塞。 - 然而,应用程序仍然可能会在等待向服务器发送输出时阻塞。 - 这在发送非常长的SQL命令或数据值时可能会发生,尽管这相对不常见。 - (如果应用程序通过COPY IN发送数据,则更有可能发生。) - 为了防止这种可能性并实现完全非阻塞的数据库操作,可以使用以下附加函数。 - - + 使用上述函数可以避免在等待数据库服务器输入时阻塞。不过,应用程序仍可能在等待向服务器发送输出时阻塞。这种情况较少见,但发送很长的 SQL 命令或数据值时可能发生。(如果应用程序通过 COPY IN 发送数据,发生的可能性则大得多。)为了防止这种情况,实现完全非阻塞的数据库操作,可以使用以下附加函数。 + PQsetnonblockingPQsetnonblocking @@ -4461,11 +4322,7 @@ int PQsetnonblocking(PGconn *conn, int arg); - 在非阻塞状态下,成功调用、 - 、 - 不会阻塞; - 它们的更改将存储在本地输出缓冲区中,直到刷新为止。 - 不成功的调用将返回错误,必须重试。 + 在非阻塞状态下,成功调用 不会阻塞;产生的数据保存在本地输出缓冲区中,等待发送。失败的调用会返回错误,必须重试。 @@ -4496,9 +4353,7 @@ int PQisnonblocking(const PGconn *conn); - 尝试将任何排队的输出数据刷新到服务器。如果成功(或发送队列为空),则返回0; - 如果由于某种原因失败,则返回-1;如果尚未能够发送发送队列中的所有数据(只有在连接为非阻塞时才会发生此情况), - 则返回1。 + 尝试将发送队列中的输出数据发送到服务器。成功(或发送队列为空)时返回 0;因某种原因失败时返回 -1;如果尚未能发送队列中的全部数据,则返回 1(这种情况只可能发生在非阻塞连接上)。 int PQflush(PGconn *conn); @@ -4506,15 +4361,11 @@ int PQflush(PGconn *conn); - + - 在一个非阻塞连接上发送任何命令或者数据之后,要调用。 - 如果它返回 1,就要等待套接字变成读准备好或写准备好。如果它变为写准备好,应再次调用。 - 如果它变为读准备好,则应先调用,然后再调用。 - 一直重复直到返回 0(有必要检查读准备好并且用耗尽输入,因为服务器可能阻塞给我们发送数据的尝试,例如 NOTICE 消息,并且在我们读它的数据之前它都不会读我们的数据)。 - 一旦返回 0,应等待套接字变成读准备好并且接着按照上文所述读取响应。 - + 在非阻塞连接上发送命令或数据后,应调用 。如果返回 1,就等待套接字变为可读或可写。套接字可写时,再次调用 ;可读时,先调用 ,再调用 。重复上述步骤,直到 返回 0。(必须检查套接字是否可读,并用 读完输入,因为服务器可能在尝试向客户端发送数据时阻塞,例如发送 NOTICE 消息;在客户端读取这些数据之前,服务器不会读取客户端发送的数据。)当 返回 0 后,等待套接字变为可读,再按前述方法读取响应。 + @@ -4528,29 +4379,26 @@ int PQflush(PGconn *conn); - pipelining - in libpq + 管道化 + 在 libpq 中 - batch mode - in libpq + 批处理模式 + 在 libpq 中 - libpq 管道模式允许应用发送查询而无需读取先前发送查询的结果。 - 利用管道模式的优点,客户端将对服务器等待的更少,因为可以在单个网络事务中发送/接收多个查询/结果。 - + libpq 的管道模式允许应用程序在尚未读取先前查询结果时继续发送查询。多个查询及其结果可以在一次网络交互中发送和接收,从而减少客户端等待服务器的时间。 + - 虽然管道模式提供了显著的性能提升, - 使用管道模式写客户端会更加复杂,因为它涉及到管理一个挂起查询的队列,并查找队列中的哪个结果对应于哪个查询。 - + 管道模式可以显著提升性能,但使用它编写客户端也更复杂,因为需要管理待处理查询队列,并确定每个结果对应队列中的哪个查询。 + - 管道模式通常也会在客户端和服务器上面消耗更多的内存,尽管仔细和积极地管理发送/接收队列可以减轻这种消耗。 - 这适用于连接是否处于阻塞或非阻塞模式。 - + 管道模式通常也会增加客户端和服务器的内存消耗,不过仔细、主动地管理发送和接收队列可以缓解这一问题。无论连接处于阻塞还是非阻塞模式,都是如此。 + 虽然libpq的管道API是在PostgreSQL 14中引入的, @@ -4563,24 +4411,8 @@ int PQflush(PGconn *conn); 使用管道模式 - 要发出管道命令,应用程序必须将连接切换到管道模式, - 可以通过来完成。 - 可以使用来测试管道模式是否激活。 - 在管道模式下,只允许使用扩展查询协议的异步操作, - 不允许包含多个SQL命令的命令字符串,也不允许使用COPY命令。 - 使用同步命令执行函数,如PQfn、 - PQexec、 - PQexecParams、 - PQprepare、 - PQexecPrepared、 - PQdescribePrepared、 - PQdescribePortal, - 都会导致错误。 - 也不允许使用PQsendQuery,因为它使用简单查询协议。 - 一旦所有已分派的命令的结果已被处理,并且 - 结束管道结果已被消耗,应用程序可以通过返回 - 到非管道模式。 - + 要使用管道,应用程序必须通过 将连接切换到管道模式。可用 检查管道模式是否已启用。在管道模式下,只允许使用扩展查询协议的异步操作,不允许命令字符串包含多个 SQL 命令,也不允许 COPY。调用同步命令执行函数,例如 PQfnPQexecPQexecParamsPQpreparePQexecPreparedPQdescribePreparedPQdescribePortalPQclosePreparedPQclosePortal,会导致错误。也不允许使用 PQsendQuery,因为它使用简单查询协议。所有已发送命令的结果及管道结束结果都读取处理完毕后,应用程序便可通过 返回非管道模式。 + @@ -4589,9 +4421,8 @@ int PQflush(PGconn *conn); 如果在阻塞模式下使用,它可能发生客户端/服务器死锁。 - 客户端将阻止尝试发送查询到服务器,但服务器将阻止从它已经处理的查询向客户端发送结果。 - 这只有当客户端在它切换到处理从服务器的输入之前发送足够的查询来填充其输出缓冲区和服务器的接收缓冲区,才会发生这种情况,但很难准确预测何时将发生。 - + 客户端在尝试向服务器发送查询时阻塞,而服务器在尝试将已处理查询的结果发送给客户端时阻塞。只有当客户端在转而处理服务器输入之前,发送了足够多的查询,填满自身的输出缓冲区和服务器的接收缓冲区,才会发生这种情况;但很难准确预测何时会发生。 + @@ -4628,8 +4459,8 @@ int PQflush(PGconn *conn); - PQisBusyPQconsumeInput 等函数在处理管道结果时照常工作。特别地,在管道处理过程中调用 PQisBusy 时,如果到目前为止已发出查询的所有结果均已被消费,则返回 0。 - + PQisBusyPQconsumeInput 等函数在处理管道结果时照常工作。特别地,在管道处理过程中调用 PQisBusy 时,如果到目前为止已发出查询的所有结果均已被读取,则返回 0。 + libpq 不向应用程序提供当前正在处理哪个查询的信息(除了 PQgetResult 返回空指针,表示开始返回下一个查询的结果)。应用程序必须跟踪查询的发送顺序,以便将查询与对应结果关联起来。应用程序通常会使用状态机或 FIFO 队列实现这一点。 @@ -4642,21 +4473,16 @@ int PQflush(PGconn *conn); 错误处理 - 从客户端的视角,在PQresultStatus返回PGRES_FATAL_ERROR之后,管道被标记为中止。 - PQresultStatus将报告一个PGRES_PIPELINE_ABORTED结果,对中止的管道中的每一个剩余的排队操作。 - PQpipelineSync的结果报告为PGRES_PIPELINE_SYNC,以表示中止管道的结束并恢复正常的结果处理。 - + 从客户端的角度看,PQresultStatus 返回 PGRES_FATAL_ERROR 后,管道就会被标记为中止。对于已中止管道中剩余的每个排队操作,PQresultStatus 都会报告一个 PGRES_PIPELINE_ABORTED 结果。PQpipelineSyncPQsendPipelineSync 的结果报告为 PGRES_PIPELINE_SYNC,表示已中止的管道结束,并恢复正常的结果处理。 + 在错误恢复时,客户端必须 使用 PQgetResult处理结果。 - 如果管道使用隐式事务,那么已经执行的操作将被回滚,而排队跟在失败操作的操作将被完全跳过。 - 同样的行为也会发生,如果管道开始并提交单个显式事务(也就是,第一个语句是BEGIN ,最后一个是COMMIT),除非会话在管道结束时保持在中止事务状态。 - 如果管道包含多个显式事务,所有在错误发生前已提交的事务都会继续保留,当前正在进行的事务会被中止,所有后续操作都会被完全跳过,包括后续事务在内。 - 如果管道同步点发生时显式事务块为中止状态,则下一个管道将立即中止,除非下一个命令使用ROLLBACK将事务置于正常模式。 - + 如果管道使用隐式事务,已经执行的操作会被回滚,而失败操作之后排队的操作会全部跳过。如果管道开始并提交单个显式事务(即第一条语句为 BEGIN,最后一条为 COMMIT),行为也相同,不过在管道结束时,会话仍处于事务中止状态。如果管道包含多个显式事务,错误发生前已经提交的事务仍保持已提交状态,当前正在进行的事务会中止,所有后续操作都会被跳过,包括后续事务。如果到达管道同步点时,显式事务块仍处于中止状态,下一个管道会立即中止,除非下一条命令使用 ROLLBACK 将事务恢复为正常状态。 + @@ -4669,24 +4495,19 @@ int PQflush(PGconn *conn); - 交叉结果处理和查询分派 + 交错处理结果与发送查询 - 为避免大型管道上的死锁,客户端将被围绕非阻塞事件循环构建,通过使用操作系统工具,如select, poll, WaitForMultipleObjectEx等等, - + 为避免大型管道发生死锁,客户端应围绕非阻塞事件循环组织,使用 selectpollWaitForMultipleObjectEx 等操作系统机制。 + - 客户端应用通常应该维护一个尚未分派的工作队列和一个已分派但尚未处理结果的工作队列。 - 当套接字是可写时,它将可以分派更多的工作。 - 当套接字是可读时,它将读取结果并处理它们,将它们匹配到相应结果队列中的下一个条目。 - 基于可用内存,来自套接字的结果将被经常读取:这里不需要等到管道结束才读取结果。 - 管道将范围涵盖到工作的逻辑单元,通常(但不是必然)每个管道一个事务。 - 在管道之间,不需要退出管道模式再重新进入管道模式,也不需要等待一个管道结束后再发送下一个。 - + 客户端应用程序通常应维护两个队列:一个存放尚未发送的工作,另一个存放已经发送但尚未处理结果的工作。套接字可写时,应继续发送工作;套接字可读时,应读取并处理结果,将其与相应结果队列中的下一个条目匹配。应根据可用内存情况,频繁地从套接字读取结果,无需等到管道结束。每个管道应对应一个逻辑工作单元,通常是一个事务,但并非必须如此。管道之间无需退出再重新进入管道模式,也无需等待一个管道完成后才发送下一个。 + - 一个使用select()和一个简单状态机来跟踪发送和接收工作的示例,在PostgreSQL源代码发行版的src/test/modules/libpq_pipeline/libpq_pipeline.c文件中。 - + PostgreSQL 源代码发行版的 src/test/modules/libpq_pipeline/libpq_pipeline.c 中提供了一个示例,使用 select() 和简单状态机跟踪已发送和已接收的工作。 + @@ -4730,7 +4551,7 @@ PGpipelineStatus PQpipelineStatus(const PGconn *conn); - libpq 连接 是管道模式。 + libpq 连接处于管道模式。 @@ -4759,18 +4580,14 @@ PGpipelineStatus PQpipelineStatus(const PGconn *conn); - 造成连接进入管道模式,如果它当前空闲或已经是管道模式。 - + 如果连接当前空闲或已处于管道模式,则使该连接进入管道模式。 int PQenterPipelineMode(PGconn *conn); - - 成功返回1. - 如果连接当前不是空闲的,返回0并且无影响,也就是说,它已经有了一个结果,或者它正在等待服务器的更多输入,等等。 - 这个函数实际上不向服务器发送任何东西,它只是更改libpq连接状态。 + 成功时返回 1。如果连接当前不空闲,例如已有结果可供读取,或正在等待服务器的更多输入,则返回 0,且不产生任何影响。此函数实际上不向服务器发送任何内容,只改变 libpq 的连接状态。 @@ -4782,16 +4599,14 @@ int PQenterPipelineMode(PGconn *conn); - 造成连接退出管道模式,如果连接当前以空队列处于管道模式,并且没有待处理的结果。 + 如果连接当前处于管道模式、队列为空且没有待读取的结果,则使该连接退出管道模式。 int PQexitPipelineMode(PGconn *conn); - 成功则返回1。 - 如果不是管道模式,则返回1并且不采取操作。 - 如果当前语句没有完成处理,或者PQgetResult尚未被调用以收集所有先前发送查询的结果,则返回0(在这种情况下,使用以获取关于故障的更多信息)。 + 成功时返回 1。如果连接不处于管道模式,也返回 1,且不执行任何操作。如果当前语句尚未处理完毕,或尚未调用 PQgetResult 读取先前发送的所有查询的结果,则返回 0(此时可使用 获取更多失败信息)。 @@ -4803,17 +4618,14 @@ int PQexitPipelineMode(PGconn *conn); - 通过发送sync message并刷新发送缓冲区的方式来标记管道中的同步点。 - 它用作隐式事务的定界符和错误恢复点;参见。 - + 通过发送同步消息并将发送缓冲区中的数据发往服务器,在管道中标记同步点。同步点作为隐式事务的分界符和错误恢复点;见 int PQpipelineSync(PGconn *conn); - 成功就返回1。 - 如果连接不是管道模式或者发送sync message失败,则返回0。 + 成功时返回 1。如果连接不处于管道模式,或发送同步消息失败,则返回 0。 @@ -4823,14 +4635,13 @@ int PQpipelineSync(PGconn *conn); - 通过发送sync message但不刷新发送缓冲区,来标记管道中的一个同步点。它可作为隐式事务的分界符和错误恢复点;参见。 - + 通过发送同步消息在管道中标记同步点,但不刷新发送缓冲区。同步点作为隐式事务的分界符和错误恢复点;见 int PQsendPipelineSync(PGconn *conn); - 成功时返回 1。如果连接不处于管道模式,或者发送sync message失败,则返回 0。请注意,该消息本身不会自动刷新到服务器;必要时请使用PQflush。 + 成功时返回 1。如果连接不处于管道模式,或发送同步消息失败,则返回 0。注意,该消息本身不会自动发送到服务器;必要时可使用 PQflush @@ -4842,21 +4653,19 @@ int PQsendPipelineSync(PGconn *conn); - 发送一个请求到服务器以刷新它的输出缓冲区。 + 请求服务器发送其输出缓冲区中的数据。 int PQsendFlushRequest(PGconn *conn); - + - 成功就返回1。 - 任何失败则返回0。 - + 成功时返回 1;发生任何失败时返回 0。 + - 当PQpipelineSync被调用的结果,或者在非管道模式下的任何请求时,服务器自动刷新它的输出缓冲区;这个函数用于使得服务器在不建立同步点的情况下以管道模式刷新其输出缓冲区。 - 请注意,请求不是自身能自动刷新到服务器;如果需要时使用PQflush。 - + 调用 PQpipelineSync 后,或者在非管道模式下收到任何请求时,服务器都会自动发送其输出缓冲区中的数据。此函数可让服务器在管道模式下发送输出缓冲区中的数据,而不建立同步点。注意,该请求本身不会自动发送到服务器;必要时可使用 PQflush。 + @@ -4867,43 +4676,36 @@ int PQsendFlushRequest(PGconn *conn); 何时使用管道模式 - 非常像异步查询模式,在使用管道模式时没有明显的性能开销。 - 它增加了客户端应用的复杂性,并且需要特别注意以防止客户端/服务器死锁。 - 但是管道模式可以提供相当大的性能改进,代价是因为状态保留更久而增加内存使用。 - + 与异步查询模式类似,使用管道模式不会带来明显的性能开销。它增加了客户端应用程序的复杂性,需要格外注意防止客户端与服务器之间的死锁,但也能显著提升性能,代价是状态保留更久,因而占用更多内存。 + - 当服务器比较远,即网络延迟(ping time)高的时候,管道模式最有用,以及在许多小操作正在快速连续执行的时候。 - 当每个查询的执行时间是客户端/服务器往返时间的许多倍时,使用管道命令的优势通常会更少。 - 不用管道模式,在往返时间为300毫秒的服务器上运行一个100条语句的操作,仅网络延迟就需要30秒;使用管道,等待来自服务器的结果可能只消耗仅仅0.3秒。 - + 当服务器距离较远,即网络延迟(ping 时间)较高,或者需要快速连续执行许多小操作时,管道模式最有用。如果每个查询的执行时间是客户端与服务器往返时间的许多倍,使用管道命令的收益通常较小。在往返时间为 300 毫秒的服务器上执行一个包含 100 条语句的操作,不使用管道时,仅网络延迟就需要 30 秒;使用管道时,等待服务器结果的时间可能低至 0.3 秒。 + - 当你的应用需要完成很多小的INSERT, UPDATEDELETE 操作,并且不能方便的转换到集合操作或者 COPY操作时,用管道命令。 - + 如果应用程序需要执行大量小型 INSERTUPDATEDELETE 操作,而这些操作又难以转换为集合操作或 COPY 操作,就可以使用管道命令。 + - 当来自一个操作的信息需要客户端产生下一个操作时,管道模式是没有用的。 - 在这种情况下,客户机将不得不引入一个同步点,并等待完整的客户端/服务器往返以获取它需要的结果。 - 但是,通常可以调整客户端设计以交换服务器端所需的信息。 - 读-修改-写循环是非常好的选择;例如: + 如果客户端必须获得前一个操作的信息,才能生成下一个操作,管道模式就没有帮助。在这种情况下,客户端必须引入同步点,并等待一次完整的客户端与服务器往返,才能获得所需结果。不过,通常可以调整客户端设计,让所需信息在服务器端交换。读取、修改、写入的循环尤其适合这样改进。例如: BEGIN; SELECT x FROM mytable WHERE id = 42 FOR UPDATE; --- result: x=2 --- client adds 1 to x: +-- 结果:x=2 +-- 客户端将 x 加 1: UPDATE mytable SET x = 3 WHERE id = 42; COMMIT; - 可以更有效地开展以下工作: +可以改写为以下效率更高的操作: UPDATE mytable SET x = x + 1 WHERE id = 42; - + - 当单个管道包含多个事务时,管道的作用更小,而且更复杂(参见)。 - + 当单个管道包含多个事务时,使用管道的收益较小,复杂度也更高(见 )。 + @@ -4925,7 +4727,7 @@ UPDATE mytable SET x = x + 1 WHERE id = 42; - 要进入这些模式之一,请在成功调用(或其兄弟函数)后立即调用。这种模式选择只对当前正在执行的查询生效。然后按所述,反复调用直到其返回空指针。如果查询返回了任何行,这些行会作为一个或多个PGresult对象返回。它们看起来与普通查询结果相同,只是状态码在单行模式下为PGRES_SINGLE_TUPLE,在分块模式下为PGRES_TUPLES_CHUNK,而不是PGRES_TUPLES_OK。每个PGRES_SINGLE_TUPLE对象恰好包含一行结果,而PGRES_TUPLES_CHUNK对象至少包含一行、至多包含指定的每块行数。最后一行之后,或者如果查询返回零行,则会返回一个状态为PGRES_TUPLES_OK且不含行的对象,表示不会再有更多行到达。(但请注意,仍然必须继续调用直到其返回空指针。)所有这些PGresult对象都会包含与普通查询结果相同的行描述数据(列名、类型等)。每个对象在使用完之后都应像往常一样通过释放。 + 要进入这些模式之一,请在成功调用(或其同类函数)后立即调用。这种模式选择只对当前正在执行的查询生效。然后按所述,反复调用直到其返回空指针。如果查询返回了任何行,这些行会作为一个或多个PGresult对象返回。它们看起来与普通查询结果相同,只是状态码在单行模式下为PGRES_SINGLE_TUPLE,在分块模式下为PGRES_TUPLES_CHUNK,而不是PGRES_TUPLES_OK。每个PGRES_SINGLE_TUPLE对象恰好包含一行结果,而PGRES_TUPLES_CHUNK对象至少包含一行、至多包含指定的每块行数。最后一行之后,会返回一个状态为PGRES_TUPLES_OK且不含行的对象;如果查询返回零行,则立即返回该对象。这表示不会再有更多行到达。(但请注意,仍然必须继续调用直到其返回空指针。)所有这些PGresult对象都会包含与该查询的普通PGresult对象相同的行描述数据(列名、类型等)。每个对象在使用完之后都应像往常一样通过释放。 @@ -4947,7 +4749,7 @@ int PQsetSingleRowMode(PGconn *conn); - 此函数只能在调用或其某个兄弟函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活单行模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 + 此函数只能在调用或其某个同类函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活单行模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 @@ -4965,7 +4767,7 @@ int PQsetChunkedRowsMode(PGconn *conn, int chunkSize); - 该函数与类似,不同之处在于它指定每个PGresult最多返回chunkSize行,而不一定只返回一行。此函数也只能在调用或其某个兄弟函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活分块模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 + 该函数与类似,不同之处在于它指定每个PGresult最多返回chunkSize行,而不一定只返回一行。此函数也只能在调用或其某个同类函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活分块模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 @@ -4984,10 +4786,10 @@ int PQsetChunkedRowsMode(PGconn *conn, int chunkSize); 取消进行中的查询 - canceling SQL queries + 取消 SQL 查询 - query cancellation + 查询取消 @@ -5005,7 +4807,7 @@ PGcancelConn *PQcancelCreate(PGconn *conn); - 创建一个PGcancelConnPGcancelConn对象,但不会立即通过这条连接发送取消请求。可以使用以阻塞方式发送取消请求,或者使用以非阻塞方式发送。返回值可以传给,以检查该PGcancelConn对象是否成功创建。PGcancelConn是不透明结构体,不应由应用程序直接访问。它可用于以线程安全的方式取消原始连接上正在执行的查询。 + 创建一个PGcancelConnPGcancelConn对象,但不会立即通过这条连接发送取消请求。可以使用以阻塞方式发送取消请求,或者使用以非阻塞方式发送。返回值可以传给,以检查该PGcancelConn对象是否成功创建。PGcancelConn是不透明结构体,不应由应用程序直接访问。这个PGcancelConn对象可用于以线程安全的方式取消原始连接上正在执行的查询。 @@ -5058,7 +4860,7 @@ PostgresPollingStatusType PQcancelPoll(PGcancelConn *cancelConn); - 如果PQcancelStart成功,下一阶段就是轮询libpq,使其继续推进取消连接序列。使用获取底层套接字描述符。(注意:不要假定该套接字在多次调用PQcancelPoll之间保持不变。)循环规则如下:如果PQcancelPoll(cancelConn)上一次返回PGRES_POLLING_READING,就等待该套接字准备好可读(由select()poll()或类似系统函数指示),然后再次调用PQcancelPoll(cancelConn)。反之,如果其上一次返回PGRES_POLLING_WRITING,就等待套接字准备好可写,然后再次调用。第一次迭代时,也就是尚未调用过PQcancelPoll(cancelConn)时,按其上次返回PGRES_POLLING_WRITING来处理。持续这一循环,直到PQcancelPoll(cancelConn)返回PGRES_POLLING_FAILED,表示连接过程失败,或者返回PGRES_POLLING_OK,表示取消请求已成功分派。 + 如果PQcancelStart成功,下一阶段就是轮询libpq,使其继续进行取消连接的建立过程。使用获取数据库连接底层套接字的描述符。(注意:不要假定该套接字在多次调用PQcancelPoll之间保持不变。)循环规则如下:如果PQcancelPoll(cancelConn)上一次返回PGRES_POLLING_READING,就等待该套接字准备好可读(由select()poll()或类似系统函数指示),然后再次调用PQcancelPoll(cancelConn)。反之,如果PQcancelPoll(cancelConn)上一次返回PGRES_POLLING_WRITING,就等待套接字准备好可写,然后再次调用PQcancelPoll(cancelConn)。第一次迭代时,也就是尚未调用过PQcancelPoll(cancelConn)时,按其上次返回PGRES_POLLING_WRITING来处理。持续这一循环,直到PQcancelPoll(cancelConn)返回PGRES_POLLING_FAILED,表示连接过程失败,或者返回PGRES_POLLING_OK,表示取消请求已成功分派。 @@ -5124,7 +4926,7 @@ PostgresPollingStatusType PQcancelPoll(PGcancelConn *cancelConn); - 请注意,尽管这些常量会继续保留(为了保持兼容性),应用程序也绝不应依赖它们按某个特定顺序出现,甚至不应依赖它们一定会出现,或者依赖状态值始终属于这些已记录的取值之一。应用程序可以这样写: + 请注意,尽管这些常量会继续保留(为了保持兼容性),应用程序也绝不应依赖它们按某个特定顺序出现,甚至不应依赖它们一定会出现,或者依赖状态值始终属于本节列出的取值之一。应用程序可以这样写: switch(PQcancelStatus(conn)) { @@ -5195,7 +4997,7 @@ int PQcancelSocket(const PGcancelConn *cancelConn); PQcancelErrorMessagePQcancelErrorMessage - error messagein PGcancelConn + 错误消息PGcancelConn @@ -5254,8 +5056,8 @@ void PQcancelReset(PGcancelConn *cancelConn); 发送取消请求的过时函数 - 这些函数代表较旧的取消请求发送方式。虽然它们仍然可以工作,但由于即使原始连接通过sslmodegssencmode要求加密,它们发送取消请求时也不会以加密方式进行,因此已被废弃。因此,强烈不建议在新代码中继续使用这些旧方法,已有代码也建议迁移到新的函数。 - + 这些函数使用较旧的方式发送取消请求。即使原始连接通过 sslmodegssencmode 要求加密,它们也不会加密取消请求,因此虽然仍可使用,却已被弃用。强烈不建议在新代码中使用这些旧方法,也建议将现有代码改为使用新函数。 + @@ -5351,7 +5153,7 @@ int PQrequestCancel(PGconn *conn); 快速路径接口 - fast path + 快速路径 @@ -5361,8 +5163,8 @@ int PQrequestCancel(PGconn *conn); - 这个接口不安全,不应使用。当result_is_int被设置为0时,PQfn可能会在result_buf末尾之外写入数据,而不管缓冲区是否有足够空间容纳所请求的字节数。此外,它已经废弃。可以通过创建预备语句来定义函数调用,从而获得相近的性能和更强的功能。然后,以二进制形式传输参数和结果来执行该语句,就可以替代快速路径函数调用。 - + 此接口不安全,不应使用。当 result_is_int 设为 0 时,PQfn 可能越过 result_buf 的末尾写入数据,无论缓冲区是否有足够空间容纳请求的字节数。此外,此接口已经过时:可以通过创建预备语句来定义函数调用,获得相近的性能和更强的功能;再以二进制形式传输参数和结果来执行该语句,即可替代快速路径函数调用。 + @@ -5390,27 +5192,24 @@ typedef struct - fnid参数是要被执行的函数的 OID。argsnargs定义了要传递给函数的参数;它们必须匹配已声明的函数参数列表。当一个参数结构体的isint域为真时,u.integer值被以指定长度(必须是 1、2 或者 4 字节)整数的形式发送给服务器;这时候会发生恰当的字节交换。当isint为假时,*u.ptr中指定数量的字节将不做任何处理被发送出去;这些数据必须是服务器 预期的用于该函数参数数据类型的二进制传输的格式(由于历史原因u.ptr被声明为类型int *,其实把它考虑成void *会更好)。result_buf是放置该函数返回值的缓冲区。调用者必须已经分配了足够的空间来存储返回值(这里没有检查!)。实际的结果长度将被放在result_len指向的整数中返回。如果预期结果是 2 或 4 字节整数,把result_is_int设为 1;否则设为 0。把result_is_int设为 1 导致libpq在必要时对值进行交换字节,这样它就作为对客户端机器正确的int值被传输,注意对任一种允许的结果大小都会传递一个 4 字节到*result_buf。当result_is_int是 0 时,服务器发送的二进制格式字节将不做修改直接返回(在这种情况下,把result_buf考虑为类型void *更好)。 - + fnid 参数是要执行函数的 OID。argsnargs 指定传给函数的参数,必须与函数声明中的参数列表匹配。参数结构体的 isint 字段为真时,u.integer 值会以指定长度的整数发送到服务器,该长度必须是 2 或 4 字节,并会进行适当的字节序转换。isint 为假时,位于 *u.ptr 的指定数量字节会原样发送;数据必须符合服务器对该函数参数数据类型的二进制传输格式要求。(将 u.ptr 声明为 int * 是历史原因;将其视为 void * 更合适。)result_buf 指向用于存放函数返回值的缓冲区。调用者必须事先分配足够空间来保存返回值,这里不会检查!实际结果长度以字节为单位,返回到 result_len 指向的整数中。如果预期结果是 2 或 4 字节整数,将 result_is_int 设为 1,否则设为 0。将 result_is_int 设为 1 后,libpq 会按需转换字节序,使结果成为适合客户端机器的 int 值;注意,无论是哪种允许的结果大小,传入 *result_buf 的都是 4 字节整数。result_is_int 为 0 时,服务器发送的二进制格式字节串会原样返回。(此时,将 result_buf 视为 void * 更合适。) + - PQfn总是返回一个有效的PGresult指针,包括状态PGRES_COMMAND_OK 表示成功或者PGRES_FATAL_ERROR在出现什么问题时。 - 在使用结果之前应该检查结果状态。 - 当结果不再使用后,调用者有义务使用释放PGresult。 - + PQfn 总是返回有效的 PGresult 指针:成功时状态为 PGRES_COMMAND_OK,遇到问题时为 PGRES_FATAL_ERROR。使用结果前应检查其状态。不再需要结果时,调用者负责使用 释放 PGresult。 + - 要传递NULL参数到函数,将参数结构体的len字段设置为-1isintu 字段就不相关了。 - + 要向函数传入 NULL 参数,将该参数结构体的 len 字段设为 -1;此时,isintu 字段便不再相关。 + - 如果函数返回 NULL, *result_len 被设置为 -1, 并且 *result_buf 不调整。 - + 如果函数返回 NULL,则将 *result_len 设为 -1,而不修改 *result_buf。 + - 注意在使用此接口时,不能够处理集-值结果。 - 此外,函数必须是一个普通函数,而不是聚合、窗口函数或过程。 - + 注意,使用此接口时无法处理集合值结果。此外,函数必须是普通函数,不能是聚合函数、窗口函数或过程。 + @@ -5420,7 +5219,7 @@ typedef struct NOTIFY - in libpq + 在 libpq 中 @@ -5429,39 +5228,36 @@ typedef struct libpq应用把LISTENUNLISTENNOTIFY命令作为普通 SQL 命令提交。 - 随后通过调用PQnotifies.PQnotifies来检测NOTIFY消息的到达。 + 随后通过调用PQnotifiesPQnotifies来检测NOTIFY消息的到达。 - 函数PQnotifies从服务器发来的未处理通知消息列表中返回下一条通知。如果没有待处理通知,则返回空指针。一旦PQnotifies返回一条通知,该通知就被视为已处理,并会从通知列表中删除。 - + 函数 PQnotifies 从已收到但尚未处理的服务器通知消息列表中返回下一条通知。没有待处理通知时返回空指针。一旦 PQnotifies 返回一条通知,该通知就被视为已处理,并从通知列表中移除。 PGnotify *PQnotifies(PGconn *conn); typedef struct pgNotify { - char *relname; /* notification channel name */ - int be_pid; /* process ID of notifying server process */ - char *extra; /* notification payload string */ + char *relname; /* 通知通道名称 */ + int be_pid; /* 发送通知的服务器进程 ID */ + char *extra; /* 通知载荷字符串 */ } PGnotify; - - 在处理完PQnotifies返回的PGnotify对象后,别忘了用把它释放。 - 释放PGnotify指针本身就足够了;relnameextra域并不表示独立分配的内存(这些域名是历史遗留的,尤其是通道名称与关系名称并无关联)。 - +处理完 PQnotifies 返回的 PGnotify 对象后,务必使用 释放它。只需释放 PGnotify 指针;relnameextra 字段并非独立分配。(这些字段名称是历史遗留的;尤其是,通道名称与关系名称不必有任何关联。) + 给出了一个示例程序展示异步通知的使用。 - PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数吸收的消息。 + PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数读取的消息。 在较早版本的libpq中,及时收到NOTIFY消息的唯一方法是不断提交命令,哪怕是空命令,然后在每次后检查PQnotifies。 - 虽然这种方法仍然有效,但由于效率过低,现已废弃。 + 虽然这种方法仍然有效,但由于浪费处理能力,现已弃用。 - 当你没有可用的命令提交时,一种更好的检查NOTIFY消息的方法是调用,然后检查PQnotifies。 + 当没有需要执行的实际命令时,一种更好的检查NOTIFY消息的方法是调用,然后检查PQnotifies。 你可以使用select()等待服务器数据到达,这样在无事可做时就不会浪费CPU资源(参见以获得可传给select()的文件描述符)。 注意不管是用/提交命令还是简单地使用,这种方法都能正常工作。 不过,你应该记住在每次之后检查PQnotifies,看看在命令的处理过程中是否有通知到达。 @@ -5475,20 +5271,16 @@ typedef struct pgNotify COPY - with libpq + 使用 libpq - PostgreSQL中的COPY命令有用于libpq的对网络连接读出或者写入的选项。这一节描述的函数允许应用通过提供或者消耗已拷贝的数据来充分利用这个功能。 - + PostgreSQLCOPY 命令提供了选项,可以通过 libpq 使用的网络连接读取或写入数据。本节介绍的函数允许应用程序通过提供或接收复制数据来使用这一能力。 + - 整个处理是应用首先通过或者一个等效的函数发出 SQL COPY命令。 - 对这个命令的响应(如果命令无误)将是一个状态代码是PGRES_COPY_OUT或 者PGRES_COPY_IN(取决于指定的拷贝方向)的PGresult对象。 - 应用然后就应该使用这一节的函数接收或者传送数据行。在数据传输结束之后,另外一个PGresult对象会被返回以表明传输的成功或者失败。 - 它的状态将是:PGRES_COMMAND_OK表示成功,PGRES_FATAL_ERROR表示发生了一些问题。 - 此时我们可以通过发出进一步的 SQL 命令(在COPY操作的处理过程中,不能用同一个连接执行其它 SQL 命令)。 - + 整体流程如下:应用程序先通过 或等效函数发出 SQL COPY 命令。如果命令没有错误,响应就是一个 PGresult 对象,其状态码为 PGRES_COPY_OUTPGRES_COPY_IN,取决于指定的复制方向。应用程序随后应使用本节函数接收或发送数据行。数据传输完成后,会返回另一个 PGresult 对象,表示传输成功或失败:成功时状态为 PGRES_COMMAND_OK,出现问题时为 PGRES_FATAL_ERROR。此时可以通过 继续发出 SQL 命令。(COPY 操作进行期间,不能在同一连接上执行其他 SQL 命令。) + 如果一个COPY命令是通过在一个可能包含额外命令的字符串中发出的,那么应用在完成COPY序列之后必须继续用取得结果。 @@ -5496,17 +5288,15 @@ typedef struct pgNotify - 这一节的函数应该只在从获得了PGRES_COPY_OUTPGRES_COPY_IN结果状态的后执行。 - + 只有从 获得 PGRES_COPY_OUTPGRES_COPY_IN 结果状态后,才应调用本节函数。 + - 一个PGresult对象具有这些状态值之一,携带有关COPY操作开始的一些附加数据。 - 可以使用与查询结果相关的函数来获取这些附加数据: - - + 带有上述某个状态值的 PGresult 对象,还会携带关于即将开始的 COPY 操作的附加数据。这些数据可以通过下列函数获取,这些函数也用于查询结果: + PQnfieldsPQnfieldswith COPY + >PQnfields用于 COPY @@ -5517,7 +5307,7 @@ typedef struct pgNotify PQbinaryTuplesPQbinaryTupleswith COPY + >PQbinaryTuples用于 COPY @@ -5529,7 +5319,7 @@ typedef struct pgNotify PQfformatPQfformatwith COPY + >PQfformat用于 COPY @@ -5541,15 +5331,15 @@ typedef struct pgNotify - + 用于发送<command>COPY</command>数据的函数 - 这些函数用于在COPY FROM STDIN期间发送数据。如果在连接不是COPY_IN状态,调用它们会失败。 - + 这些函数用于在 COPY FROM STDIN 期间发送数据。如果连接不处于 COPY_IN 状态,调用它们会失败。 + @@ -5568,12 +5358,11 @@ int PQputCopyData(PGconn *conn, - 传输指定buffer中长度为nbytesCOPY数据到服务器。 - 如果数据被放在队列中,结果是 1;如果因为缓冲区满而无法被放在队列中(只可能发生在连接是非阻塞模式时),那么结果是零;如果发生错误,结果为 -1(如果返回值为 -1,那么使用检索细节。如果值是零,那么等待写准备好然后重试)。 + 将指定 buffer 中长度为 nbytesCOPY 数据传输到服务器。数据成功加入队列时返回 1;因缓冲区已满而无法加入队列时返回零(仅可能发生在非阻塞模式下);发生错误时返回 -1。(返回 -1 时,可用 获取详细信息。返回零时,应等待可写就绪后重试。) - 应用可以把COPY数据流划分成任意方便的大小放到缓冲区中。在发送时,缓冲区载荷的边界没有什么语意。数据流的内容必须匹配COPY命令预期的数据格式;详见。 + 应用程序可以将 COPY 数据流分成任意方便大小的数据块,逐块装入缓冲区。发送时,这些数据块的边界没有语义含义。数据流内容必须符合 COPY 命令预期的数据格式;详见 @@ -5593,21 +5382,15 @@ int PQputCopyEnd(PGconn *conn, - 如果errormsgNULL,则成功结束COPY_IN操作。 - 如果errormsg不是NULLCOPY被强制失败,errormsg指向的字符串是错误消息。 - (不过,我们不应假定这个准确的错误信息将会从服务器传回,因为服务器可能已经因为其自身原因导致COPY失败。)。 + 如果 errormsgNULL,则成功结束 COPY_IN 操作。如果 errormsg 不为 NULL,则强制 COPY 失败,并将 errormsg 指向的字符串用作错误消息。(但不应假定服务器一定会返回这条完全相同的错误消息,因为服务器可能已经因自身原因使 COPY 失败。) - 如果终止消息被发送,则结果为 1;在非阻塞模式中,结果为 1 也可能只表示终止消息被成功地放在了发送队列中 - (在非阻塞模式中,要确认数据确实被发送出去,你应该接着等待写准备好并且调用,重复这些直到返回零)。 - 零表示该函数由于缓冲区满而无法将该终止消息放在队列中,这只会发生在非阻塞模式中(在这种情况下,等待写准备好并且再次尝试调用)。 - 如果发生系统错误,则返回 -1,可以使用检索详情。 + 终止消息已发送时返回 1;在非阻塞模式下,返回 1 也可能仅表示该消息已成功加入发送队列。(在非阻塞模式下,要确认数据已经发送,应接着等待可写就绪并调用 ,反复执行直到返回零。)返回零表示缓冲区已满,无法将终止消息加入队列;这种情况仅可能发生在非阻塞模式下。(此时,应等待可写就绪,再次调用 。)发生严重错误时返回 -1,可用 获取详细信息。 - 在成功调用之后,调用获取COPY命令的最终结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 成功调用 后,调用 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -5640,29 +5423,19 @@ int PQgetCopyData(PGconn *conn, - 在一个COPY期间尝试从服务器获取另外一行数据。数据总是以每次一个数据行的方式被返回;如果只有一个部分行可用,那么它不会被返回。 - 成功返回一个数据行涉及到分配一块内存来保存该数据。buffer参数必须为非NULL。 - *buffer被设置为指向分配到的内存的指针,或者是在没有返回缓冲区的情况下指向NULL。 - 一个非NULL的结果缓冲区在不需要时必须用释放。 + 在 COPY 期间尝试从服务器获取下一行数据。每次总是返回一个完整数据行;如果只有部分行可用,则不返回。成功返回数据行时,会分配一块内存保存数据。buffer 参数必须为非 NULL*buffer 会被设置为指向所分配的内存;如果没有返回缓冲区,则设为 NULL。非 NULL 的结果缓冲区在不再需要时应使用 释放。 - 在成功返回一行之后,返回的值就是该数据行里数据的字节数(将是大于零)。 - 被返回的字符串总是空终止的,虽然这可能只是对文本COPY有用。 - 一个零结果表示该COPY仍然在处理中,但是还没有可用的行(只在async为真时才可能)。 - 一个 -1 结果表示COPY已经完成。-2 结果表示发生了错误(参考获取原因)。 + 成功返回一行时,返回值是该行的数据字节数,始终大于零。返回的字符串总是以零字节结尾,不过这可能仅对文本 COPY 有用。返回零表示 COPY 仍在进行,但尚无可用行(仅在 async 为真时可能发生)。返回 -1 表示 COPY 已完成;返回 -2 表示发生了错误(可用 查看原因)。 - 当async为真时(非零),将不会阻塞等待输入; - 如果COPY仍在处理过程中并且没有可用的完整行,那么它将返回零 - (在这种情况下等待读准备好,然后在再次调用之前,调用)。 - 当async为假(零)时,将阻塞,直到数据可用或者操作完成。 + 当 async 为真(非零)时, 不会阻塞等待输入;如果 COPY 仍在进行,但没有完整行可用,则返回零。(此时,应等待读就绪,先调用 ,再调用 。)当 async 为假(零)时, 会阻塞,直到数据可用或操作完成。 - 在返回 -1 之后,调用获取COPY命令的最后结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 在 返回 -1 后,调用 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -5672,11 +5445,11 @@ int PQgetCopyData(PGconn *conn, - 用于<command>COPY</command>的废弃函数 + 用于<command>COPY</command>的过时函数 - 这些函数代表了以前的处理COPY的方法。尽管它们还能用,但是现在已经被废弃,因为它们的错误处理很糟糕、检测结束数据的方法也不方便,并且缺少对二进制或非阻塞传输的支持。 - + 这些函数使用较旧的方式处理 COPY。虽然仍然可用,但由于错误处理欠佳、检测数据结束的方式不便,而且缺少对二进制或非阻塞传输的支持,已被弃用。 + @@ -5686,7 +5459,7 @@ int PQgetCopyData(PGconn *conn, - 读取一个以新行终止的字符行到(由服务器传输) 到一个长度为length的字符串缓冲区。 + 将服务器传来的、以换行符结尾的一行字符读入大小为 length 的字符串缓冲区。 int PQgetline(PGconn *conn, char *buffer, @@ -5695,12 +5468,11 @@ int PQgetline(PGconn *conn, - 这个函数拷贝最多length-1 个字符到该缓冲区中,并且把终止的新行转换成一个零字节。 - 在输入结束时返回EOF,如果整行都被读取则返回 0,如果缓冲区填满了而还没有遇到结束的新行则返回 1。 - + 此函数最多将 length-1 个字符复制到缓冲区,并将末尾的换行符转换为零字节。 在输入结束时返回 EOF,读完一整行时返回 0,缓冲区已满但尚未读到末尾换行符时返回 1。 + - 注意,应用必须检查是否一个新行包含两个字符\.,这表明服务器 已经完成了COPY命令的结果发送。如果应用可能收到超过length-1 字符长的行, 我们就应该确保正确识别\.行(例如,不要把一个长数据行的结束当作一个终止行)。 + 注意,应用程序必须检查新读入的一行是否仅由 \. 两个字符组成,这表示服务器已发送完 COPY 命令的结果。如果可能收到长度超过 length-1 个字符的行,必须确保正确识别 \. 行,例如不能把长数据行的末尾误当作终止行。 @@ -5712,7 +5484,7 @@ int PQgetline(PGconn *conn, - 不阻塞地读取一行COPY数据(由服务器传输)到一个缓冲区中。 + 以非阻塞方式将服务器传来的一行 COPY 数据读入缓冲区。 int PQgetlineAsync(PGconn *conn, char *buffer, @@ -5721,23 +5493,19 @@ int PQgetlineAsync(PGconn *conn, - 这个函数类似于,但是可以被用于那些必须异步读取COPY数据的应用, 也就是不阻塞的应用。 - 在发出了COPY命令并得到了PGRES_COPY_OUT响应之后, - 应用应该调用直到检测到结束数据的信号。 - + 此函数类似于 ,但可用于必须异步读取 COPY 数据的应用程序,即读取时不阻塞。发出 COPY 命令并收到 PGRES_COPY_OUT 响应后,应用程序应调用 ,直到检测到数据结束信号。 + - 不像,这个函数负责检测结束数据。 + 与 不同,此函数会负责检测数据结束。 - 在每次调用时,如果libpq的输入缓冲区中有一个完整的数据行可用,都将返回数据。 - 否则,在剩余行到达之前不会返回数据。如果识别到拷贝数据结束的标志,此函数返回 -1;如果没有可用数据则返回 0; - 或者是给出一个正数给出被返回的字节数。如果返回 -1,调用者下一步必须调用,然后回到正常处理。 + 每次调用时,如果 libpq 的输入缓冲区中有完整数据行, 就会返回数据;否则,要等该行剩余部分到达后才返回数据。识别到复制数据结束标记时返回 -1,没有可用数据时返回 0,否则返回正数,表示返回的数据字节数。返回 -1 后,调用者必须接着调用 ,然后恢复正常处理。 - 返回的数据将不超过一个数据行的范围。如果可能,每次将返回一个完整行。但如果调用者提供的缓冲区太小不足以容下服务器发送的行,那么将返回部分行。对于文本数据,这可以通过测试返回的最后一个字节是否\n来检测(在二进制COPY中, 需要对COPY数据格式进行实际的分析,以便做相同的判断)。被返回的字符串不是空结尾的(如果你想增加一个终止空,确保传递一个比实际可用空间少一字节的bufsize)。 + 返回的数据不会跨越数据行边界。只要可能,每次就返回一整行;但如果调用者提供的缓冲区太小,容不下服务器发送的一行,则只返回部分行。对于文本数据,可检查最后返回的字节是否为 \n,以判断是否返回了完整行。(对于二进制 COPY,则必须实际解析 COPY 数据格式才能作出相同判断。)返回的字符串不以零字节结尾。(如果要自行添加末尾的零字节,务必将传入的 bufsize 设置为比实际可用空间少一字节。) @@ -5749,7 +5517,7 @@ int PQgetlineAsync(PGconn *conn, - 向服务器发送一个空终止的字符串。如果 OK 则返回 0;如果不能发送字符串则返回EOF。 + 向服务器发送以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputline(PGconn *conn, const char *string); @@ -5757,17 +5525,14 @@ int PQputline(PGconn *conn, - 一系列调用发送的COPY数据流和返回的数据具有相同的格式, - 只是应用不需要每次调用中发送刚好一个数据行;在每次调用中发送多行或者部分行都是可以的。 + 连续调用 发送的 COPY 数据流,与 返回的数据格式相同。不过,应用程序不必在每次 调用中恰好发送一个数据行;每次发送部分行或多行也可以。 - 在PostgreSQL协议 3.0 之前,应用必须显式地发送两个字符\.作为最后一行来指示服务器已经完成发送COPY数据。 - 虽然这么做仍然有效,但是它已经被废弃并且\.的特殊含义可能在将来的版本中删除。 - 在发送完实际数据之后, 调用就足够了。 - + 在 PostgreSQL 协议 3.0 之前,应用程序必须显式发送由 \. 两个字符组成的最后一行,告知服务器应用程序已发送完 COPY 数据。虽然这种方式仍然有效,但已被弃用,\. 的特殊含义预计会在未来版本中移除。(在 CSV 模式下,这种做法已经会出现异常。)发送完实际数据后,调用 即可。 + @@ -5779,7 +5544,7 @@ int PQputline(PGconn *conn, - 向服务器发送一个非空终止的字符串。如果 OK 则返回 0,如果不能发送字符串则返回EOF。 + 向服务器发送不以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputnbytes(PGconn *conn, const char *buffer, @@ -5788,7 +5553,7 @@ int PQputnbytes(PGconn *conn, - 这个函数类似,除了数据缓冲区不需要是空终止,因为要发送的字节数是直接指定的。在发送二进制数据时使用这个过程。 + 此函数与 完全相同,只是直接指定了要发送的字节数,因此数据缓冲区不必以零字节结尾。发送二进制数据时可使用此函数。 @@ -5804,15 +5569,11 @@ int PQputnbytes(PGconn *conn, int PQendcopy(PGconn *conn); - 这个函数等待服务器完成拷贝。当最后一个字符串已经用发送给服务器时或者当最后一个字符串已经用PQgetline从服务器接收到时,就会发出这个函数。 - 这个函数必须被发出,否则服务器将会和客户端不同步。从这个函数返回后,服务器就已经准备好接收下一个 SQL 命令了。函数成功完成时返回值为 0,否则返回非零值(如果返回值为非零值,用检索详情)。 +此函数会等待服务器完成复制。应在使用 向服务器发送最后一个字符串后,或使用 PQgetline 从服务器接收最后一个字符串后调用它。必须调用此函数,否则服务器与客户端会失去同步。函数返回后,服务器便准备好接收下一条 SQL 命令。成功完成时返回 0,否则返回非零值。(返回非零值时,可用 获取详细信息。) - 在使用时,应用应该通过反复调用并且在看到终止行后调用来响应PGRES_COPY_OUT结果。 - 然后它应该返回到循环直到返回一个空指针。 - 类似地,PGRES_COPY_IN结果会用一系列加上之后的来处理,然后返 回到循环。 - 这样的安排将保证嵌入到一系列SQL命令中的COPY命令将被正确执行。 + 使用 时,收到 PGRES_COPY_OUT 结果后,应用程序应反复调用 ,并在看到终止行后调用 。随后应回到 循环,直到 返回空指针。类似地,收到 PGRES_COPY_IN 结果后,应连续调用 ,再调用 ,然后回到 循环。这样可以保证嵌在一系列 SQL 命令中的 COPY 命令正确执行。 @@ -5832,8 +5593,8 @@ int PQendcopy(PGconn *conn); 控制函数 - 这些函数控制libpq行为各种各样的细节。 - + 这些函数控制 libpq 行为的各种细节。 + @@ -5843,17 +5604,15 @@ int PQendcopy(PGconn *conn); - 返回客户端编码。 + 返回客户端编码。 int PQclientEncoding(const PGconn *conn); - - 请注意,它返回的是编码 ID,而不是一个符号串字符串,如EUC_JP。如果不成功,它会返回 -1。要把一个编码 ID 转换为为一个编码名称,可以用: - +注意,返回的是编码 ID,而不是 EUC_JP 这样的符号字符串。失败时返回 -1。要将编码 ID 转换为编码名称,可以使用: char *pg_encoding_to_char(int encoding_id); - + @@ -5863,14 +5622,11 @@ char *pg_encoding_to_char(int encoding_id); - - 设置客户端编码。 - + 设置客户端编码。 int PQsetClientEncoding(PGconn *conn, const char *encoding); - conn是一个到服务器的连接,而encoding是你想使用的编码。 - 如果函数成功地设置编码,则返回 0,否则返回 -1。这个连接的当前编码可以使用确定。 + conn是到服务器的连接,而encoding是要使用的编码。如果成功设置编码,函数返回 0,否则返回 -1。此连接的当前编码可以通过以下函数确定: @@ -5882,7 +5638,7 @@ int PQsetClientEncoding(PGconn *conn, const char * - 决定返回的消息的细节程度。 + 设置 所返回消息的详细程度。 typedef enum { @@ -5894,19 +5650,12 @@ typedef enum PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); - - 设置细节模式,并返回该连接的前一个设置。 - 在TERSE模式下,返回的消息只包括严重性、主要文本以及位置;这些东西通常放在一个单一行中。 - DEFAULT模式生成的消息包括上面的信息加上任何细节、提示或者上下文域(这些可能跨越多行)。 - VERBOSE模式包括所有可以可用的域。修改细节模式不会影响来自已有PGresult对象中的可用消息。 - 只有随后创建的PGresult对象才受到影响。 - SQLSTATE模式仅包括错误严重性和SQLSTATE错误代码,如果其中之一是可用的(如果没有,输出类似于TERSE模式)。 - + 设置详细程度模式,并返回该连接先前的设置。在 TERSE 模式下,返回的消息只包含严重级别、主要文本和位置;通常一行就能容纳。DEFAULT 模式生成的消息除上述内容外,还包含所有详细信息、提示或上下文字段(这些内容可能跨越多行)。VERBOSE 模式包含所有可用字段。SQLSTATE 模式仅包含错误严重级别,以及可用时的 SQLSTATE 错误代码(如果没有错误代码,则输出与 TERSE 模式相同)。 + - 更改详细程度设置不会影响已存在的PGresult对象的可用的消息,只会影响随后创建的对象。 - (如果想要用不同的详细程度打印之前的错误,请见 ) - + 更改详细程度设置不会影响从既有 PGresult 对象中取得的消息,只影响随后创建的对象。(如果希望以不同的详细程度打印之前的错误,请参见 。) + @@ -5917,7 +5666,7 @@ PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); - 决定如何处理返回的消息中的CONTEXT域。 + 确定 所返回消息中 CONTEXT 字段的处理方式。 typedef enum { @@ -5928,18 +5677,12 @@ typedef enum PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibility show_context); - - 设置上下文显示模式,返回该连接上之前的设置。 - 这个模式控制消息中是否包括CONTEXT域。 - NEVER模式不会包括CONTEXT,而ALWAYS则尽可能地包括这个域。 - 在ERRORS模式(默认)中,只在错误消息中包括CONTEXT域,而在通知和警告消息中不会包括。 - (但是,如果详细程度设置为 TERSESQLSTATE,则无论上下文显示模式如何,都会省略CONTEXT字段。) - + 设置上下文显示模式,并返回连接先前的设置。此模式控制消息中是否包含 CONTEXT 字段。NEVER 模式从不包含 CONTEXT,而 ALWAYS 模式在该字段可用时总是包含它。在 ERRORS 模式(默认)下,CONTEXT 字段只包含在错误消息中,不包含在通知和警告中。(不过,如果详细程度设置为 TERSESQLSTATE,则无论上下文显示模式如何,都会省略 CONTEXT 字段。) + - 更改这个模式不会影响从已经存在的PGresult对象项中得到的消息,只会影响后续创建的PGresult对象 - (如果想要用不同的详细程度打印之前的错误,请见)。 - + 更改此模式不会影响从既有 PGresult 对象中取得的消息,只影响随后创建的对象。(如果希望使用不同的显示模式打印之前的错误,请参见 。) + @@ -5950,25 +5693,20 @@ PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibilit - 启用对客户端/服务器通讯的跟踪,把跟踪信息输出到一个调试文件流中。 + 启用客户端/服务器通信跟踪,将跟踪信息写入调试文件流。 void PQtrace(PGconn *conn, FILE *stream); - + - 每行包括:一个可选的时间戳,一个方向指示器(F表示从客户端到服务器的消息或B表示从服务器到客户端的消息),消息长度、消息类型、和消息内容。 - 非消息内容字段(时间戳、方向、长度和消息类型)由一个制表符分隔。 - 消息内容用空格分隔。 - 协议字符串用双引号括起来,而用作数据值的字符串用单引号括起来。 - 不可打印的字符被打印为十六进制转义。 - 更多消息-类型-特定的详情可以在中发现。 - + 每行包含可选的时间戳、方向指示符(F 表示客户端发往服务器的消息,B 表示服务器发往客户端的消息)、消息长度、消息类型和消息内容。消息内容之外的字段(时间戳、方向、长度和消息类型)以制表符分隔。消息内容以空格分隔。协议字符串用双引号括起,用作数据值的字符串用单引号括起。不可打印字符以十六进制转义形式输出。各消息类型的进一步说明见 。 + - 在 Windows上,如果libpq库和应用使用了不同的标志编译,那么这个函数调用会导致应用崩溃,因为FILE指针的内部表达是不一样的。特别是多线程/单线程、发布/调试 以及静态/动态标志应该是库和所有使用库的应用都一致。 + 在 Windows 上,如果 libpq 库与应用程序使用不同的标志编译,调用此函数会导致应用程序崩溃,因为 FILE 指针的内部表示不同。具体而言,库与所有使用它的应用程序都应使用相同的多线程/单线程、发布/调试和静态/动态标志。 @@ -5989,11 +5727,8 @@ void PQsetTraceFlags(PGconn *conn, int flags); - flags包含描述跟踪的操作模式的标志位。 - 如果flags包含PQTRACE_SUPPRESS_TIMESTAMPS,则在打印每条消息时不包括时间戳。 - 如果flags包含PQTRACE_REGRESS_MODE,那么在打印每个消息时将修改一些字段,例如对象OIDs,以使输出在测试框架中更方便地使用。 - 这个函数必须在调用PQtrace之后调用。 - + flags 包含描述跟踪工作模式的标志位。如果 flags 包含 PQTRACE_SUPPRESS_TIMESTAMPS,则打印每条消息时不包含时间戳。如果 flags 包含 PQTRACE_REGRESS_MODE,则打印每条消息时会隐去某些字段,例如对象 OID,以便在测试框架中使用输出。必须在调用 PQtrace 之后调用此函数。 + @@ -6005,11 +5740,11 @@ void PQsetTraceFlags(PGconn *conn, int flags); - 禁用打开的跟踪。 + 禁用由 启动的跟踪。 void PQuntrace(PGconn *conn); - + @@ -6039,11 +5774,8 @@ void PQfreemem(void *ptr); - 释放libpq分配的内存,尤其是,,,和PQnotifies分配的内存。 - 特别重要的是,在微软 Windows 上使用这个函数,而不是free()。 - 这是因为只有 DLL 和应用的当多线程/单线程、发布/调试以及静态/动态标志相同时,才能在一个 DLL 中分配内存并且在应用中释放它。 - 在非微软 Windows 平台上,这个函数与标准库函数free()相同。 - + 释放 libpq 分配的内存,特别是 PQnotifies 分配的内存。在 Microsoft Windows 上,务必使用此函数,而不是 free()。这是因为只有 DLL 与应用程序使用相同的多线程/单线程、发布/调试和静态/动态标志,才能在 DLL 中分配内存并在应用程序中释放它。在 Microsoft Windows 以外的平台上,此函数与标准库函数 free() 相同。 + @@ -6054,15 +5786,16 @@ void PQfreemem(void *ptr); - 释放分配的数据结构。 + 释放 分配的数据结构。 void PQconninfoFree(PQconninfoOption *connOptions); - +如果参数为 NULL 指针,则不执行任何操作。 + - 一个简单的不会做这些,因为数组包含对子字符串的引用。 - + 仅调用 不足以完成此项释放,因为数组还包含指向附属字符串的引用。 + @@ -6086,8 +5819,8 @@ char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, 当前支持的算法是md5scram-sha-256onoff也被接受作为md5的别名,用于与较老的服务器版本兼容)。 注意,对scram-sha-256支持是在PostgreSQL版本10中引入的,并且在老的服务器版本上无法工作。 如果algorithmNULL,这个函数将向服务器查询设置的当前值。 - 这种行为可能会阻塞当前事务,并且当前事务被中止或者连接正忙于执行另一个查询时会失败。 - 如果希望为服务器使用默认的算法但避免阻塞,应在调用之前查询你自己的password_encryption,并且将该值作为algorithm传入。 + 这一查询可能阻塞,并且当前事务被中止或者连接正忙于执行另一个查询时会失败。 + 如果希望为服务器使用默认的算法但避免阻塞,应在调用之前自行查询password_encryption,并且将该值作为algorithm传入。 @@ -6153,8 +5886,8 @@ PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); 这是libpq内部用于分配并初始化一个空PGresult对象的函数。 如果无法分配内存,此函数返回NULL。 将它导出供外部调用,是因为一些应用需要自行生成结果对象,特别是带有错误状态的对象。 - 如果conn非空,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 - 此外,如果conn非空,连接中注册的所有事件过程也会被复制到PGresult中。 + 如果conn 不为 null,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 + 此外,如果conn 不为 null,连接中注册的所有事件过程也会被复制到PGresult中。 (这些过程不会收到PGEVT_RESULTCREATE调用,但可参见。) 注意,最终应对该对象调用,就像处理libpq自身返回的PGresult一样。 @@ -6175,16 +5908,16 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); - conn参数被传送给事件过程,但不会被直接使用。如果事件过程不使用它,则会返回NULL。 - + conn 参数会传递给事件过程,但此函数不会直接使用它。如果事件过程不使用此参数,则可以传入 NULL。 + 已经接收到这个对象的PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件过程不会被再次触发。 - 这个函数与分开的主要原因是在调用事件过程之前创建一个PGresult并且填充它常常是合适的。 - + 此函数与 分开的主要原因是,通常适合先创建 PGresult 并填充数据,然后再调用事件过程。 + @@ -6195,13 +5928,11 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); - 为一个PGresult对象创建一个拷贝。 - 这个拷贝不会以任何方式链接到源结果,并且当该拷贝不再需要时,必须调用进行清理。如果函数失败,返回NULL。 - + 创建 PGresult 对象的副本。副本与源结果没有任何关联,不再需要副本时必须调用 。函数失败时返回 NULL PGresult *PQcopyResult(const PGresult *src, int flags); - + 这不是为了制作一个精确的副本。返回的结果总是放在PGRES_TUPLES_OK状态中,并且不复制源中的任何错误消息。 @@ -6210,7 +5941,7 @@ PGresult *PQcopyResult(const PGresult *src, int flags); PG_COPYRES_TUPLES指定复制源结果的元组。(这也意味着复制属性。) PG_COPYRES_NOTICEHOOKS指定复制源结果的通知钩子。 PG_COPYRES_EVENTS指定复制源结果的事件。(但不复制与源相关的任何实例数据。) - 事件程序接收PGEVT_RESULTCOPY事件。 + 事件过程会收到 PGEVT_RESULTCOPY 事件。 @@ -6241,18 +5972,15 @@ int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs); - 设置一个PGresult对象的一个元组域值。 + 设置 PGresult 对象中某个元组的字段值。 int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len); - + - 这个函数将自动按需增加结果的内部元组数组。但是,tup_num参数必须小于等于,意味着这个函数对元组数组一次只能增加一个元组。 - 但已存在的任意元组中的任意域可以以任意顺序进行调整。如果field_num的一个值已经存在,它会被覆盖。 - 如果len是 -1,或valueNULL, 该域值会被设置为一个 SQL 空值。 - value会被复制到结果的私有存储中,因此函数返回后就不再需要了。如果函数失败,返回值是 0。如果函数成功,返回值会是非 0。 - + 此函数会根据需要自动扩展结果内部的元组数组。不过,tup_num 参数必须小于或等于 ,也就是说,每次只能向元组数组增加一个元组。已有元组的任何字段都可以按任意顺序修改。如果 field_num 指定的位置已有值,该值会被覆盖。如果 len 为 -1 或 valueNULL,则将该字段设置为 SQL null 值。value 会被复制到结果的私有存储中,因此函数返回后就不再需要它。函数失败时返回零,成功时返回非零值。 + @@ -6270,8 +5998,8 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); - 当res被清除时,这个函数分配的内存也会被释放掉。如果函数失败,返回值是NULL。结果被保证为按照数据的任意类型充分地对齐,正如malloc所作的。 - + 使用此函数分配的所有内存都会在清除 res 时释放。函数失败时返回 NULL。与 malloc 一样,返回的内存保证满足任意数据类型的对齐要求。 + @@ -6282,15 +6010,15 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); - 检索为PGresult对象分配的字节数。 + 获取为 PGresult 对象分配的字节数。 size_t PQresultMemorySize(const PGresult *res); - + - 此值是与PGresult对象关联的所有malloc请求的总和,就是说,将释放的所有空间。此信息可用于管理内存消耗。 - + 此值是与 PGresult 对象相关的所有 malloc 请求所分配字节数的总和,即 将释放的全部内存。这一信息有助于管理内存消耗。 + @@ -6302,35 +6030,32 @@ size_t PQresultMemorySize(const PGresult *res); - 返回所使用的libpq版本。 + 返回所使用的libpq版本。 int PQlibVersion(void); - 在运行时,这个函数的结果可以被用来决定在当前已载入的 libpq 版本中特定的功能是否可用。 - 例如,这个函数可以被用来决定哪些选项可以被用于。 - + 可在运行时根据此函数的结果,判断当前已加载的 libpq 版本是否具有特定功能。例如,可用它判断 支持哪些连接选项。 + - 结果通过将库的主版本号乘以10000再加上次版本号形成。例如,版本10.1将被返回为100001,而版本11.0将被返回为110000。 - + 返回值等于库的主版本号乘以 10000 再加上次版本号。例如,版本 10.1 返回 100001,版本 11.0 返回 110000。 + - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。 - 对于那些版本,为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - + 在主版本 10 之前,PostgreSQL 使用由三个部分组成的版本号,前两个部分共同表示主版本。对于这些版本, 用两位数字表示每个部分;例如,版本 9.1.5 返回 90105,版本 9.2.0 返回 90200。 + - 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。 - 在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 - + 因此,为了判断功能兼容性,应用程序应将 的结果除以 100 而非 10000,得到逻辑上的主版本号。在所有版本系列中,次版本(错误修复版本)之间只有最后两位数字不同。 + - 这个函数出现于PostgreSQL版本 9.1,因此它不能被用来在早期的版本中检测所需的功能,因为调用它将会创建一个对版本9.1及其后版本的链接依赖。 + 此函数从 PostgreSQL 9.1 起提供,因而不能用它检测更早版本是否具有所需功能:调用它会建立对 9.1 或更高版本的链接依赖。 @@ -6362,13 +6087,13 @@ pg_usec_time_t PQgetCurrentTimeUSec(void); 通知处理 - notice processing - in libpq + 通知处理 + 在 libpq 中 - 服务器产生的通知和警告消息不会被查询执行函数返回,因为它们不代表查询失败。它们可以被传递给一个通知处理函数,并且在处理者返回后执行会继续正常进行。默认的处理函数会把消息打印在stderr上,但是应用可以通过提供它自己的处理函数来重载这种行为。 - + 服务器生成的通知和警告消息不由查询执行函数返回,因为它们并不表示查询失败。这些消息会传递给通知处理函数,处理函数返回后,执行正常继续。默认通知处理函数将消息打印到 stderr,应用程序也可以提供自己的处理函数来替换这一行为。 + 由于历史原因,通知处理有两个级别,称为通知接收器和通知处理器。通知接收器的默认行为是格式化通知并且将一个字符串传递给通知处理器来打印。不过,如果一个应用选择提供自己的通知接收器,它通常会忽略通知处理器层并且在通知接收器中完成所有工作。 @@ -6376,10 +6101,10 @@ pg_usec_time_t PQgetCurrentTimeUSec(void); 函数PQsetNoticeReceiver - notice receiver + 通知接收器 PQsetNoticeReceiver为一个连接对象设置或者检查当前的通知接收器。 相似地,PQsetNoticeProcessor - notice processor + 通知处理器 PQsetNoticeProcessor设置或检查当前的通知处理器。 @@ -6402,19 +6127,16 @@ PQsetNoticeProcessor(PGconn *conn, - 当接收到一个服务器产生的或者libpq内部产生的通知或警告消息,通知接收器函数会被调用。 - 它会以一种PGRES_NONFATAL_ERROR PGresult的形式传递该消息 - (这允许接收器使用抽取个别的域,或者使用或者得到一个完整的预格式化的消息)。 - 被传递给PQsetNoticeReceiver的同一个空指针也被传递(必要时,这个指针可以被用来访问应用相关的状态)。 - + 从服务器收到通知或警告消息,或者 libpq 内部生成这类消息时,便会调用通知接收器函数。消息以状态为 PGRES_NONFATAL_ERRORPGresult 对象传给该函数。(接收器可使用 提取单个字段,也可使用 获取完整的预格式化消息。)传给 PQsetNoticeReceiver 的同一个 void 指针也会传入。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知接收器会简单地抽取消息(使用)并且将它传递给通知处理器。 - 通知处理器负责处理一个以文本形式给出的通知或警告消息。该消息的字符串文本(包括一个收尾的新行)被传递给通知处理器,外加一个同时被传递给PQsetNoticeProcessor的空指针(必要时,这个指针可以被用来访问应用相关的状态)。 - + 通知处理器负责处理以文本形式提供的通知或警告消息。传给它的参数包括消息字符串(含末尾的换行符),以及先前传给 PQsetNoticeProcessor 的同一个 void 指针。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知处理器很简单: @@ -6428,9 +6150,8 @@ defaultNoticeProcessor(void *arg, const char *message) - 一旦你设定了一个通知接收器或处理器,你应该期待只要PGconn对象或者从它构造出的PGresult对象存在,该函数就应该能被调用。 - 在一个PGresult创建时,PGconn的当前通知处理指针被复制到PGresult中,以备类似的函数使用。 - + 设置通知接收器或处理器后,应当预期:只要 PGconn 对象或由它生成的 PGresult 对象仍存在,就可能调用该函数。创建 PGresult 时,会将 PGconn 当前的通知处理指针复制到 PGresult 中,供 等函数在需要时使用。 + @@ -6439,19 +6160,19 @@ defaultNoticeProcessor(void *arg, const char *message) 事件系统 - libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和毁灭。一种主要的使用情况是这允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 + libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和销毁。一个主要用途是允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 - 每个注册的事件处理程序都与两个数据相关联,libpq仅将其视为不透明的void *指针。 - 有一个透传指针,当事件处理程序与PGconn注册时,应用程序提供。 + 每个注册的事件处理程序都与两项数据相关联,libpq仅将其视为不透明的void *指针。 + 有一个透传指针,由应用程序在向 PGconn 注册事件处理程序时提供。 透传指针在PGconn及其生成的所有PGresult的生命周期内永远不会更改; 因此,如果使用,它必须指向长期存在的数据。 此外,还有一个实例数据指针,在每个PGconnPGresult中一开始都是NULL。 可以使用函数来操作此指针。 请注意,与透传指针不同,PGconn的实例数据不会自动继承到从中创建的PGresult。 - libpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 —— 这是事件处理程序的责任。 + libpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 — 这是事件处理程序的责任。 @@ -6477,7 +6198,7 @@ typedef struct } PGEventRegister; - 当接收到PGEVT_REGISTER事件时,evtInfo指针应该转换为PGEventRegister *。这个结构体包含一个应该处于CONNECTION_OK状态的PGconn;如果在获得一个良好的PGconn后立即调用,则保证这一点。当返回一个失败代码时,所有清理工作必须完成,因为不会发送任何PGEVT_CONNDESTROY事件。 + 当接收到PGEVT_REGISTER事件时,evtInfo指针应该转换为PGEventRegister *。这个结构体包含一个应该处于CONNECTION_OK状态的PGconn;如果在获得一个良好的PGconn后立即调用,则保证这一点。当返回一个失败代码时,所有清理工作必须完成,因为不会发送任何PGEVT_CONNDESTROY事件。 @@ -6510,21 +6231,12 @@ typedef struct PGEVT_CONNDESTROY - - - 为了响应,连接销毁事件会被触发。由于 libpq 没有能力管理事件数据,事件过程有责任正确地清理它的事件数据。清理失败将会导致内存泄露。 - - + 连接销毁事件由以下调用触发:。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGconn *conn; } PGEventConnDestroy; - - - 当接收到一个PGEVT_CONNDESTROY事件时,evtInfo指针应该被类型转换为PGEventConnDestroy *。 - 这个事件在执行任何其他清理之前被触发。 - 该事件过程的返回值被忽略,因为没有办法指示一个来自的失败。还有,一个事件过程失败不该中断对不需要的内存的清理。 - +收到PGEVT_CONNDESTROY事件时,应将evtInfo指针强制转换为PGEventConnDestroy *。该事件触发于以下函数执行任何其他清理工作之前:。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:。此外,事件过程失败不应中止清理不再使用的内存的过程。 @@ -6580,21 +6292,12 @@ typedef struct PGEVT_RESULTDESTROY - - - 为了响应,结果销毁事件会被触发。由于 libpq 没有能力管理事件数据,事件过程有责任正确地清理它的事件数据。清理失败将会导致内存泄露。 - - + 结果销毁事件由以下调用触发:。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGresult *result; } PGEventResultDestroy; - - - 当接收到一个PGEVT_RESULTDESTROY事件时,evtInfo指针应该被类型转换为PGEventResultDestroy *。 - 这个事件在执行任何其他清理之前被触发。该事件过程的返回值被忽略,因为没有办法指示来自的失败。 - 还有,一个事件过程失败不该中断不需要的内存的清理过程。 - +收到PGEVT_RESULTDESTROY事件时,应将evtInfo指针强制转换为PGEventResultDestroy *。该事件触发于以下函数执行任何其他清理工作之前:。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:。此外,事件过程失败不应中止清理不再使用的内存的过程。 @@ -6602,7 +6305,7 @@ typedef struct - 事件回调函数 + 事件回调过程 @@ -6612,16 +6315,11 @@ typedef struct - PGEventProc是到一个事件过程的指针的 typedef,也就是从 libpq 接收事件的用户回调函数。一个事件过程的原型必须是 - + PGEventProc 是通过 typedef 定义的事件过程指针类型,也就是接收 libpq 事件的用户回调函数的指针类型。事件过程的签名必须为: int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) - - evtId指示发生了哪一个PGEVT事件。 - evtInfo指针必须被类型转换为合适的结构体类型才能获得关于事件的进一步信息。 - 当事件过程已被注册时,passThrough参数是提供给的指针。 - 如果成功,该函数应该返回非零值,失败则返回零。 +evtId 参数指示发生了哪一种 PGEVT 事件。必须将 evtInfo 指针强制转换为适当的结构体类型,以获取关于该事件的更多信息。passThrough 参数是在注册事件过程时传给 的指针。函数应在成功时返回非零值,在失败时返回零。 @@ -6631,8 +6329,8 @@ int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) - 在 Windows 上,函数能够有两个不同的地址:一个对 DLL 之外可见而另一个对 DLL 之内可见。我们应当小心只有其中之一会被用于libpq的事件过程函数,否则将会产生混淆。编写代码的最简单规则是将所有的事件过程声明为static。如果过程的地址必须对它自己的源代码文件之外可见,提供一个单独的函数来返回该地址。 - + 在 Windows 上,函数可能有两个不同的地址:一个在 DLL 外部可见,另一个在 DLL 内部可见。使用 libpq 的事件过程函数时,务必始终使用其中同一个地址,否则会产生混淆。确保代码正常工作的最简单做法,是将事件过程声明为 static。如果需要在过程所在的源文件之外取得其地址,应提供一个单独的函数来返回该地址。 + @@ -6660,7 +6358,7 @@ int PQregisterEventProc(PGconn *conn, PGEventProc proc, - 在每一个你想要接收事件的PGconn上必须注册一个事件过程。和内存不同,没有限制说一个连接上能注册多少个事件过程。如果该函数成功,它会返回一个非零值。如果它失败,则会返回零。 + 对于希望接收其事件的每个 PGconn,都必须注册一次事件过程。一个连接可注册的事件过程数量只受内存限制。函数成功时返回非零值,失败时返回零。 @@ -6705,16 +6403,14 @@ void *PQinstanceData(const PGconn *conn, PGEventProc proc); - 把结果的用于procinstanceData设置为data。成功返回非零,失败返回零(只有proc没有被正确地注册在conn中,才可能会失败)。 - + 将结果中针对 procinstanceData 设置为 data。成功时返回非零值,失败时返回零。(只有当 proc 未在结果中正确注册时,才可能失败。) int PQresultSetInstanceData(PGresult *res, PGEventProc proc, void *data); - 请注意,data表示的任何存储都不会由考虑,除非使用分配。 - (这样做是值得推荐的,因为它消除了在销毁结果时显式释放此类存储的需要。) + 注意,data 所指的存储不会计入 ,除非使用 分配它。(推荐这样做,因为结果销毁时便不必显式释放这部分存储。) @@ -6738,18 +6434,18 @@ void *PQresultInstanceData(const PGresult *res, PGEventProc proc); - 事件实例 + 事件示例 - 这里是一个管理与 libpq 连接和结果相关的私有数据的示例的框架。 - + 下面给出一个示例框架,用于管理与 libpq 连接和结果关联的私有数据。 + -/* The instanceData */ +/* instanceData 数据 */ typedef struct { int n; @@ -6769,14 +6465,14 @@ main(void) if (PQstatus(conn) != CONNECTION_OK) { - /* PQerrorMessage's result includes a trailing newline */ + /* PQerrorMessage 的结果包含末尾的换行符 */ fprintf(stderr, "%s", PQerrorMessage(conn)); PQfinish(conn); return 1; } - /* called once on any connection that should receive events. - * Sends a PGEVT_REGISTER to myEventProc. + /* 在每个需要接收事件的连接上调用一次。 + * 向 myEventProc 发送 PGEVT_REGISTER 事件。 */ if (!PQregisterEventProc(conn, myEventProc, "mydata_proc", NULL)) { @@ -6785,28 +6481,28 @@ main(void) return 1; } - /* conn instanceData is available */ + /* 可以取得 conn 的 instanceData */ data = PQinstanceData(conn, myEventProc); - /* Sends a PGEVT_RESULTCREATE to myEventProc */ + /* 向 myEventProc 发送 PGEVT_RESULTCREATE 事件 */ res = PQexec(conn, "SELECT 1 + 1"); - /* result instanceData is available */ + /* 可以取得结果的 instanceData */ data = PQresultInstanceData(res, myEventProc); - /* If PG_COPYRES_EVENTS is used, sends a PGEVT_RESULTCOPY to myEventProc */ + /* 使用 PG_COPYRES_EVENTS 时,向 myEventProc 发送 PGEVT_RESULTCOPY 事件 */ res_copy = PQcopyResult(res, PG_COPYRES_TUPLES | PG_COPYRES_EVENTS); - /* result instanceData is available if PG_COPYRES_EVENTS was - * used during the PQcopyResult call. + /* 如果调用 PQcopyResult 时使用了 PG_COPYRES_EVENTS, + * 就可以取得结果的 instanceData。 */ data = PQresultInstanceData(res_copy, myEventProc); - /* Both clears send a PGEVT_RESULTDESTROY to myEventProc */ + /* 两次清除操作都会向 myEventProc 发送 PGEVT_RESULTDESTROY 事件 */ PQclear(res); PQclear(res_copy); - /* Sends a PGEVT_CONNDESTROY to myEventProc */ + /* 向 myEventProc 发送 PGEVT_CONNDESTROY 事件 */ PQfinish(conn); return 0; @@ -6822,7 +6518,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventRegister *e = (PGEventRegister *)evtInfo; mydata *data = get_mydata(e->conn); - /* associate app specific data with connection */ + /* 将应用程序特有的数据与连接关联 */ PQsetInstanceData(e->conn, myEventProc, data); break; } @@ -6842,7 +6538,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventConnDestroy *e = (PGEventConnDestroy *)evtInfo; mydata *data = PQinstanceData(e->conn, myEventProc); - /* free instance data because the conn is being destroyed */ + /* 连接正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; @@ -6854,7 +6550,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *conn_data = PQinstanceData(e->conn, myEventProc); mydata *res_data = dup_mydata(conn_data); - /* associate app specific data with result (copy it from conn) */ + /* 将应用程序特有的数据与结果关联(从 conn 复制) */ PQresultSetInstanceData(e->result, myEventProc, res_data); break; } @@ -6865,7 +6561,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *src_data = PQresultInstanceData(e->src, myEventProc); mydata *dest_data = dup_mydata(src_data); - /* associate app specific data with result (copy it from a result) */ + /* 将应用程序特有的数据与结果关联(从另一个结果复制) */ PQresultSetInstanceData(e->dest, myEventProc, dest_data); break; } @@ -6875,18 +6571,18 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventResultDestroy *e = (PGEventResultDestroy *)evtInfo; mydata *data = PQresultInstanceData(e->result, myEventProc); - /* free instance data because the result is being destroyed */ + /* 结果正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; } - /* unknown event ID, just return true. */ + /* 未知的事件 ID,直接返回 true。 */ default: break; } - return true; /* event processing succeeded */ + return true; /* 事件处理成功 */ } ]]> @@ -6902,9 +6598,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 以下环境变量可用于选择默认连接参数值,这些值将被使用,如果调用代码没有直接指定值。这些对于避免将数据库连接信息硬编码到简单的客户端应用程序中非常有用,例如。 - - + 以下环境变量可用于选择连接参数的默认值,供 在调用代码未直接指定参数值时使用。例如,这样可以避免在简单的客户端应用程序中硬编码数据库连接信息。 + @@ -7076,7 +6771,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGREQUIRESSL的行为与连接参数相同。 - 这个环境变量已被弃用,推荐使用PGSSLMODE变量;设置这两个变量会抑制这个变量的效果。 + 这个环境变量已被弃用,推荐使用PGSSLMODE变量;同时设置这两个变量时,前者不再生效。 @@ -7314,9 +7009,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 下面的环境变量可用来为每一个PostgreSQL会话指定默认行为(为每一个用户或每一个数据库设置默认行为的方法还可见命令)。 - - + 以下环境变量可用于指定每个 PostgreSQL 会话的默认行为。(也可参见 命令,了解按用户或按数据库设置默认行为的方法。) + @@ -7344,8 +7038,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - - 这些环境变量的正确值可参考SQL 命令 。 +有关这些环境变量的正确取值,请参见 SQL 命令 @@ -7390,16 +7083,12 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) 用户主目录中的.pgpass文件可保存密码,供连接需要密码且尚未通过其他方式指定密码时使用。在 Unix 系统上,该目录可由HOME环境变量指定;如果未定义该变量,则使用有效用户的主目录。在 Microsoft Windows 上,文件名为%APPDATA%\postgresql\pgpass.conf(其中%APPDATA%指用户配置文件中的应用数据子目录)。也可以通过连接参数或环境变量PGPASSFILE指定要使用的密码文件。 - - 这个文件应该包含下列格式的行: - + 该文件中的行应采用以下格式: hostname:port:database:username:password - - (你可以向该文件增加一个提醒:把上面的行复制到该文件并且在前面加上#)。前四个字段的每一个都可以是字面值或者匹配任何东西的*。第一个匹配当前连接参数的行中的密码字段将被使用(因此,在使用通配符时把更特殊的项放在前面)。如果一个条目需要包含:或者\,用\对该字符转义。如果指定了host连接参数,主机名字段会被匹配到host,否则如果指定了hostaddr参数则匹配到hostaddr,如果两者都没有给出,则会搜索主机名localhost。当连接是一个Unix域套接字连接并且host参数匹配libpq的默认套接字目录路径时,也会搜索主机名localhost。在一台备库上,值为replication的数据库字段匹配连接到主库的流复制连接。否则数据库字段的用途有限,因为用户对同一个集簇中的所有数据库都有相同的密码。 - +(可以复制上面这一行,并在行首加上#,在文件中加入提示注释。)前四个字段中的每一个都可以是字面值,或者是*,后者可以匹配任何内容。将使用与当前连接参数匹配的第一行中的密码字段。(因此,使用通配符时,应将更具体的条目放在前面。)如果条目需要包含:\,请使用\转义该字符。主机名字段首先匹配已指定的host连接参数;否则匹配已指定的hostaddr参数。如果两者都未指定,则查找主机名localhost。在以下情况下也会查找主机名localhost:连接使用 Unix 域套接字,且host参数与libpq的默认套接字目录路径匹配。在备库中,数据库字段为replication时,匹配连接到主库的流复制连接。除此之外,数据库字段的用途有限,因为同一用户在同一数据库集簇的所有数据库中使用相同的密码。 - 在 Unix 系统上,密码文件上的权限必须不允许所有人或组内访问,可以用chmod 0600 ~/.pgpass这样的命令实现。如果权限没有这么严格,该文件将被忽略。在微软 Windows 上,该文件被假定存储在一个安全的目录中,因此不会进行特别的权限检查。 + 在 Unix 系统上,密码文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.pgpass 这样的命令实现。如果权限没有这么严格,该文件将被忽略。在 Microsoft Windows 上,假定该文件存储在安全的目录中,因此不进行特殊的权限检查。 @@ -7420,10 +7109,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 连接服务文件允许 libpq 连接参数与一个单一服务名称关联。 - 那个服务名称可以在一个 libpq 连接字符串里面指定,与其相关的设置将被使用。 - 这允许在不重新编译使用 libpq 的应用的前提下修改连接参数。 - 服务名称也可以被使用PGSERVICE环境变量来指定。 + 连接服务文件允许将 libpq 连接参数与单个服务名称关联。随后可以在 libpq 连接字符串中使用 service 关键字指定该服务名称,从而使用关联的设置。这样便可以修改连接参数,而无需重新编译使用 libpq 的应用程序。也可以使用 PGSERVICE 环境变量指定服务名称。 @@ -7431,7 +7117,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) 则用户文件优先。默认情况下,每个用户的服务文件名为~/.pg_service.conf。 在Microsoft Windows上,它的名称为%APPDATA%\postgresql\.pg_service.conf (其中%APPDATA%指用户配置文件夹中的应用数据子目录)。 - 可以通过在libpq连接字符串中使用servicefile关键字, + 可以通过在 libpq 连接字符串中使用servicefile关键字, 或者设置环境变量PGSERVICEFILE来指定不同的文件名。 系统范围的文件名为pg_service.conf。 默认情况下,在PostgreSQL安装的etc目录中寻找 @@ -7440,23 +7126,19 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 或者服务文件使用一种INI 文件格式,其中小节名是服务名并且参数是连接参数。 - 列表见。例如: + 两种服务文件均使用 INI 文件 格式,其中配置段名称是服务名称,参数是连接参数;参数列表见 。例如: -# comment +# 注释 [mydb] host=somehost port=5433 user=admin - 在PostgreSQL安装的share/pg_service.conf.sample中提供了一个示例文件。 +PostgreSQL 安装目录中的 share/pg_service.conf.sample 提供了一个示例文件。 - 从服务文件中获取的连接参数与从其他来源获取的参数相结合。 - 服务文件设置覆盖相应的环境变量,然后反过来可以由连接字符串中直接给出的值覆盖。 - 例如,使用上面的服务文件,连接字符串service=mydb port=5434将使用主机somehost,端口5434, - 用户admin,以及由环境变量或内置默认所设置的其他参数。 + 从服务文件中获取的连接参数会与其他来源的参数合并。服务文件中的设置会覆盖相应的环境变量,而连接字符串中直接给出的值又会覆盖服务文件中的设置。例如,使用上述服务文件时,连接字符串 service=mydb port=5434 将使用主机 somehost、端口 5434、用户 admin,以及由环境变量或内置默认值设置的其他参数。 @@ -7472,24 +7154,14 @@ user=admin 如果libpq已经在编译时打开了 LDAP 支持(configure的选项),就可以通过 LDAP 从一个中央服务器检索hostdbname之类的连接参数。这样做的好处是如果一个数据库的连接参数改变,不需要在所有的客户端机器上更新连接信息。 - - LDAP连接参数查找使用连接服务文件pg_service.conf(参见)。 - 在pg_service.conf段落中以ldap://开头的行将被识别为LDAP URL,并执行LDAP查询。 - 结果必须是一组keyword = value对,将用于设置连接选项。 - URL必须符合RFC 1959的形式为 - + LDAP 连接参数查询使用连接服务文件pg_service.conf(参见)。在pg_service.conf的配置段中,以ldap://开头的行会被识别为 LDAP URL,并执行 LDAP 查询。结果必须是一个keyword = value键值对列表,用于设置连接选项。URL 必须符合 RFC 1959,格式如下: ldap://[hostname[:port]]/search_base?attribute?search_scope?filter - - 其中hostname默认为localhostport默认为389。 - +其中,hostname默认为localhostport默认为 389。 - - 一次成功的 LDAP 查找后,pg_service.conf的处理被终止。但是如果联系不上 LDAP 则会继续处理pg_service.conf。这就提供了后手,可以加入更多指向不同 LDAP 服务器的 LDAP URL 行、经典的keyword = value对或者默认连接选项。如果你宁愿在这种情况下得到一个错误消息,在该 LDAP URL 之后增加一个语法错误的行。 - + LDAP 查找成功后就会停止处理 pg_service.conf;如果无法联系 LDAP 服务器,则会继续处理。这使后续指向其他 LDAP 服务器的 LDAP URL 行、常规的 keyword = value 对或默认连接选项能够作为后备。如果希望在这种情况下得到错误消息,可以在 LDAP URL 后添加一个语法不正确的行。 - - 一个和 LDIF 文件一起创建的 LDAP 条目实例 - + 例如,使用以下 LDIF 文件创建的 LDAP 条目: version:1 dn:cn=mydatabase,dc=mycompany,dc=com changetype:add @@ -7501,9 +7173,7 @@ description:port=5439 description:dbname=mydb description:user=mydb_user description:sslmode=require - - 可以用下面的 LDAP URL 查询: - +可以通过以下 LDAP URL 查询: ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase) @@ -7511,7 +7181,7 @@ ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase) 你也可以将常规的服务文件条目和 LDAP 查找混合。pg_service.conf中一节的完整示例: -# 只有主机和端口存储在LDAP中,显式指定dbname和user。 +# 仅 host 和 port 存储在 LDAP 中;显式指定 dbname 和 user [customerdb] dbname=customer user=appuser @@ -7531,9 +7201,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - PostgreSQL具有原生支持使用SSL连接来加密客户端/服务器通信, - 使用TLS协议以提高安全性。有关服务器端SSL功能的详细信息,请参见。 - + PostgreSQL 原生支持使用 SSL 连接,通过 TLS 协议加密客户端与服务器之间的通信,以提高安全性。有关服务器端 SSL 功能的详细信息,请参见 。 + libpq读取系统范围的OpenSSL配置文件。默认情况下,这个文件被命名为openssl.cnf并且位于openssl version -d所报告的目录中。可以通过设置环境变量OPENSSL_CONF把这个默认值覆盖为想要的配置文件的名称。 @@ -7541,39 +7210,25 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 服务器证书的客户端验证 + 客户端对服务器证书的验证 - 默认情况下,PostgreSQL将不会执行服务器证书的任何验证。这意味着可以在不被客户端知晓的情况下伪造服务器身份(例如通过修改一个 DNS 记录或者接管服务器的 IP 地址)。为了阻止哄骗,客户端必须能够通过一条信任链验证服务器的身份。信任链可以这样建立:在一台计算机上放置一个根(自签名的)证书机构(CA)的证书并且在另一台计算机上放置一个由根证书签发的叶子证书。还可以使用一种中间证书,它由根证书签发并且可以签发叶子证书。 + 默认情况下,PostgreSQL 不会对服务器证书执行任何验证。这意味着可以在客户端不知情的情况下伪造服务器身份,例如修改 DNS 记录或接管服务器的 IP 地址。要防止身份伪造,客户端必须能够通过信任链验证服务器身份。建立信任链的方法是:在一台计算机上放置根证书机构(CA)的自签名证书,在另一台计算机上放置由根证书签发的叶证书。也可以使用由根证书签发、又用于签发叶证书的中间证书。 - - 为了允许客户端验证服务器的身份,在客户端上放置一份根证书并且在服务器上放置由根证书签发的叶子证书。为了允许服务器验证客户端的身份,在服务器上放置一份根证书并且在客户端上放置由根证书签发的叶子证书。也可以使用一个或者更多个中间证书(通常与叶子证书存在一起)来将叶子证书链接到根证书。 - + 要让客户端验证服务器的身份,请在客户端放置根证书,并在服务器上放置由该根证书签发的叶证书。要让服务器验证客户端的身份,请在服务器上放置根证书,并在客户端放置由该根证书签发的叶证书。也可以使用一个或多个中间证书(通常与叶证书存储在一起),将叶证书链接到根证书。 - - 一旦信任链被建立起来,客户端有两种方法验证服务器发过来的叶子证书。如果参数sslmode被设置为verify-ca,libpq将通过检查该证书是否链接到存储在客户端上的根证书来验证服务器。如果sslmode被设置为verify-full,libpq将验证服务器的主机名匹配存储在服务器证书中的名称。如果服务器证书无法被验证,则SSL连接将失败。在大部分对安全性很敏感的环境中,推荐使用verify-full。 - + 建立信任链后,客户端可以通过两种方式验证服务器发送的叶证书。如果参数 sslmode 设为 verify-ca,libpq 会沿证书链检查到存储在客户端上的根证书,以验证服务器是否可信。如果 sslmode 设为 verify-full,libpq 还会验证服务器主机名是否与服务器证书中存储的名称匹配。如果无法验证服务器证书,SSL 连接将失败。在大多数对安全敏感的环境中,建议使用 verify-full - 在verify-full模式下,主机名将与证书的主体替代名称属性(SAN)匹配, - 或者与通用名称属性匹配,如果没有类型为dNSName的SAN存在。 - 如果证书的名称属性以星号(*)开头,那么星号将被视为通配符, - 可以匹配所有字符,除了点(.)。 - 这意味着证书将不匹配子域。如果连接使用IP地址而不是主机名进行, - 则IP地址将与类型为iPAddressdNSName的SAN匹配 - (不进行任何DNS查找)。如果没有iPAddress SAN存在, - 也没有匹配的dNSName SAN存在,则主机IP地址将与通用名称属性匹配。 - + 在 verify-full 模式下,会将主机名与证书的主体替代名称属性(SAN)匹配;如果不存在类型为 dNSName 的 SAN,则与通用名称属性匹配。如果证书的名称属性以星号(*)开头,该星号会被视为通配符,匹配点(.)以外的所有字符。这意味着该证书不会匹配子域。如果使用 IP 地址而不是主机名建立连接,则会将该 IP 地址与类型为 iPAddressdNSName 的 SAN 匹配(不执行任何 DNS 查询)。如果不存在 iPAddress SAN,也不存在匹配的 dNSName SAN,则将主机 IP 地址与通用名称属性匹配。 + - 为了与早期版本的PostgreSQL向后兼容,主机IP地址的验证方式与 - RFC 6125中的方式不同。 - 主机IP地址始终与dNSName SANs以及iPAddress SANs匹配, - 如果不存在相关的SANs,则可以与通用名称属性匹配。 - + 为与 PostgreSQL 的早期版本向后兼容,主机 IP 地址的验证方式与 RFC 6125 不同。主机 IP 地址始终会与 dNSName SAN 以及 iPAddress SAN 匹配;如果不存在相关的 SAN,还可以与通用名称属性匹配。 + @@ -7593,8 +7248,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 为了与 PostgreSQL 的早期版本达到向后兼容,如果存在一个根 CA 文件,sslmode=require的行为将与verify-ca相同,即服务器证书根据 CA 验证。我们鼓励依赖这种行为,并且需要证书验证的应用应该总是使用verify-ca或者verify-full。 - + 为与 PostgreSQL 的早期版本向后兼容,如果存在根 CA 文件,sslmode=require 的行为将与 verify-ca 相同,即根据 CA 验证服务器证书。不建议依赖这种行为;需要证书验证的应用程序应始终使用 verify-caverify-full。 + @@ -7603,44 +7258,27 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 客户端证书 - 如果服务器尝试通过请求客户端的叶证书来验证客户端的身份, - libpq将发送存储在文件 - ~/.postgresql/postgresql.crt中的证书,该文件位于用户的主目录中。 - 证书必须链到服务器信任的根证书。匹配的 - 私钥文件~/.postgresql/postgresql.key也必须存在。 - 在Microsoft Windows上,这些文件的名称分别为 - %APPDATA%\postgresql\postgresql.crt和 - %APPDATA%\postgresql\postgresql.key。 - 证书和密钥文件的位置可以通过连接参数 - sslcertsslkey, - 或通过环境变量PGSSLCERTPGSSLKEY来覆盖。 - + 如果服务器请求客户端的叶证书以验证客户端身份,libpq 将发送用户主目录下 ~/.postgresql/postgresql.crt 文件中存储的证书。这些证书必须通过证书链连接到服务器信任的根证书。还必须存在匹配的私钥文件 ~/.postgresql/postgresql.key。在 Microsoft Windows 上,这两个文件分别名为 %APPDATA%\postgresql\postgresql.crt%APPDATA%\postgresql\postgresql.key。可以通过连接参数 sslcertsslkey,或环境变量 PGSSLCERTPGSSLKEY,覆盖证书和密钥文件的位置。 + - 在Unix系统上,私钥文件的权限必须禁止任何对世界或组的访问;可以通过类似以下命令来实现: - chmod 0600 ~/.postgresql/postgresql.key。 - 或者,该文件可以由root拥有并具有组读取权限(即0640权限)。 - 该设置适用于由操作系统管理证书和密钥文件的安装。然后,libpq的用户应该成为具有对这些证书和密钥文件访问权限的组的成员。 - (在Microsoft Windows上,没有文件权限检查,因为假定%APPDATA%\postgresql目录是安全的。) - + 在 Unix 系统上,私钥文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.postgresql/postgresql.key 这样的命令实现。另一种做法是使文件归 root 所有,并允许组用户读取(即 0640 权限)。这种设置适用于由操作系统管理证书和密钥文件的安装环境。此时,应将 libpq 用户加入有权访问这些证书和密钥文件的组。(在 Microsoft Windows 上,不检查文件权限,因为假定 %APPDATA%\postgresql 目录是安全的。) + postgresql.crt中的第一个证书必须是客户端的证书,因为它必须匹配客户端的私钥。可以选择将中间证书追加到该文件 — 这样做避免了在服务器上存放中间证书的要求()。 - 证书和密钥可能是 PEM 或 ASN.1 DER 格式。 + 证书和密钥可以采用 PEM 或 ASN.1 DER 格式。 - 密钥可以以明文存储,也可以使用OpenSSL支持的任何算法(例如AES-128)使用密码进行加密。 - 如果密钥是加密存储的,那么可以在连接选项中提供密码。 - 如果提供了加密密钥,而且sslpassword选项不存在或为空,那么只要 TTY 可用,OpenSSL就会以Enter PEM pass phrase:提示交互式输入密码。 - 应用程序可以通过提供自己的密钥密码回调,覆盖客户端证书提示以及sslpassword参数的处理;参见。 + 密钥可以以明文存储,也可以使用密码,按 OpenSSL 支持的任意算法(例如 AES-128)进行加密。如果密钥以加密形式存储,可以在 连接选项中提供密码。如果提供了加密密钥,而 sslpassword 选项缺失或为空,则在有 TTY 可用时,OpenSSL 会显示 Enter PEM pass phrase: 提示,交互式地请求输入密码。应用程序可以提供自己的密钥密码回调,以覆盖客户端证书提示及 sslpassword 参数的处理;参见 - 创建证书的指令请参考。 + 有关创建证书的说明,请参见 @@ -7649,8 +7287,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 不同模式中提供的保护 - sslmode参数的不同值提供了不同级别的保护。SSL 能够针对三类攻击提供保护: - + sslmode 参数的不同值提供不同级别的保护。SSL 可以防范三类攻击: 窃听 @@ -7663,31 +7300,33 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 中间人(MITM - 如果一个第三方能对客户端和服务器之间传送的数据进行修改,它就能假装是服务器并且因此能看见并且修改数据,即使这些数据已被加密。然后第三方可以将连接信息和数据转送给原来的服务器,使得它不可能检测到攻击。这样做的通常途径包括 DNS 污染和地址劫持,借此客户端被重定向到一个不同的服务器。还有几种其他的攻击方式能够完成这种攻击。SSL使用证书验证让客户端认证服务器,就可以阻止这种攻击。 - + + 如果第三方能修改客户端与服务器之间传输的数据,就可以冒充服务器,进而查看和修改数据,即使数据已经加密。随后,第三方可以将连接信息和数据转发给原来的服务器,使攻击无法被察觉。常见的手段包括 DNS 污染和地址劫持,从而将客户端引向预期之外的服务器。还有其他几种攻击手段可以达到同样的目的。SSL 使用证书验证,让客户端认证服务器身份,以防范这种攻击。 + - 模仿 + 冒充 - 如果一个第三方能假装是一个授权的客户端,它能够简单地访问它本不能访问的数据。通常这可以由不安全的密码管理所致。SSL使用客户端证书来确保只有持有合法证书的客户端才能访问服务器,这样就能阻止这种攻击。 - + + 如果第三方能冒充获授权的客户端,就能直接访问其无权访问的数据。这通常可能由不安全的密码管理导致。SSL 使用客户端证书,确保只有持有有效证书的客户端才能访问服务器,以防范这种攻击。 + - 对于一个已知受 SSL 保护的连接,在连接建立之前,必须在客户端和服务器两端都配置 SSL。如果只在服务器端配置,客户端在得知服务器要求高安全性之前,可能就已经开始发送敏感信息(例如密码)。在 libpq 中,要确保连接安全,可以把sslmode参数设置为verify-fullverify-ca,并为系统提供一个用于验证的根证书。这类似于使用https URL浏览加密网页。 + 要确保连接受到 SSL 保护,必须在建立连接之前,在客户端和服务器两端配置 SSL。如果仅在服务器上配置,客户端可能在得知服务器要求高安全性之前就已发送敏感信息(例如密码)。在 libpq 中,可以将 sslmode 参数设为 verify-fullverify-ca,并向系统提供用于验证的根证书,以确保连接安全。这类似于使用 https URL 进行加密的网页浏览。 - 一旦服务器已经被认证,客户端可以传递敏感数据。这意味着直到这一点,客户端都不需要知道是否证书将被用于认证,这样只需要在服务器配置中指定就比较安全。 + 服务器通过身份认证后,客户端便可以传送敏感数据。这意味着,在此之前,客户端无需知道是否会使用证书进行认证,因此可以安全地仅在服务器配置中指定这一点。 - 所有SSL选项都带来了加密和密钥交换的负荷,因此必须在性能和安全性之间做出平衡。不同sslmode值所保护的风险,以及它们是怎样看待安全性和负荷的。 + 所有 SSL 选项都会产生加密和密钥交换的开销,因此必须在性能与安全性之间作出权衡。 说明了不同 sslmode 值所能防范的风险,以及它们所表达的对安全性和开销的取舍。
@@ -7703,7 +7342,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) sslmode 窃听保护 - 中间人攻击防护 + MITM 防护 声明 @@ -7714,7 +7353,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) disable - 我不关心安全性,并且我不想为加密增加负荷。 + 我不关心安全性,并且我不想为加密增加开销。 @@ -7722,7 +7361,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) allow 可能 - 我不关心安全性,但如果服务器坚持,我将承担加密带来的负荷。 + 我不关心安全性,但如果服务器坚持,我将承担加密带来的开销。 @@ -7730,7 +7369,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) prefer 可能 - 我不关心安全性,但如果服务器支持,我希望承担加密带来的负荷。 + 我不关心加密,但如果服务器支持,我希望承担加密带来的开销。 @@ -7738,7 +7377,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) require - 我想要对数据加密,并且我接受因此带来的负荷。我信任该网络会保证我总是连接到想要连接的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我信任该网络会保证我总是连接到想要连接的服务器。 @@ -7746,7 +7385,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-ca 取决于 CA 策略 - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器。 @@ -7754,7 +7393,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-full - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 @@ -7763,11 +7402,11 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
- verify-caverify-full之间的区别取决于根CA的策略。如果使用了一个公共CAverify-ca允许连接到那些可能已经被其他人注册到该CA的服务器。在这种情况下,总是应该使用verify-full。如果使用了一个本地CA或者甚至是一个自签名的证书,使用verify-ca常常就可以提供足够的保护。 + verify-caverify-full之间的区别取决于根CA的策略。如果使用了一个公共CAverify-ca允许连接到那些可能已经被其他人注册到该CA的服务器。在这种情况下,总是应该使用verify-full。如果使用了一个本地CA或者甚至是一个自签名的证书,使用verify-ca常常就可以提供足够的保护。 - sslmode的默认值是prefer。如表中所示,这在安全性的角度来说没有意义,并且它只承诺可能的性能负荷。提供它作为默认值只是为了向后兼容,并且我们不推荐在安全部署中使用它。 + sslmode 的默认值是 prefer。如表所示,从安全角度看,这一设置没有意义;它只会在可能时带来性能开销。将其作为默认值仅出于向后兼容的考虑,不建议在有安全要求的部署中使用。 @@ -7809,8 +7448,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) ~/.postgresql/root.crt - 可信的证书机构 - 检查服务器证书是由一个可信的证书机构签发 + 受信任的证书机构 + 检查服务器证书是由一个受信任的证书机构签发 @@ -7828,7 +7467,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) SSL 库初始化 - 需要兼容旧版 PostgreSQL、使用 OpenSSL 1.0.2 或更早版本的应用程序,需要在使用 SSL 库之前初始化它。自行初始化 libssl 和/或 libcrypto 库的应用程序应调用 ,告知 libpq 这些库已由应用程序初始化,使 libpq 不再初始化它们。不过,使用 OpenSSL 1.1.0 或更高版本时无需这样做,因为重复初始化已不再造成问题。 + 需要兼容旧版 PostgreSQL、使用 OpenSSL 1.0.2 或更早版本的应用程序,需要在使用 SSL 库之前初始化它。自行初始化 libssl 和/或 libcrypto 库的应用程序应调用 ,告知 libpq libssl 和/或 libcrypto 库已由应用程序初始化,使 libpq 不再初始化它们。不过,使用 OpenSSL 1.1.0 或更高版本时无需这样做,因为重复初始化已不再造成问题。 有关这些函数的用法,请参阅目标 PostgreSQL 版本的文档。 @@ -7883,8 +7522,8 @@ void PQinitSSL(int do_ssl); OAuth 支持 - libpq通过一个可选模块实现了对 OAuth v2 Device Authorization 客户端流程的支持,该流程记录在 - RFC 8628中。关于如何启用内置的 Device Authorization 流程,请参见安装文档。 + libpq通过一个可选模块实现了对 OAuth v2 设备授权客户端流程的支持,该流程记录在 + RFC 8628中。关于如何启用内置的设备授权流程,请参见安装文档。 当启用支持并安装该可选模块后,如果服务器在认证期间请求 Bearer 令牌,libpq默认会使用内置流程。即使运行客户端应用的系统没有可用的 Web 浏览器,例如通过SSH运行客户端时,也可以使用这一流程。 @@ -7906,7 +7545,7 @@ Visit https://example.com/device and enter the code: ABCD-EFGH - 当前 Windows 上尚不支持内置的 Device Authorization 流程。不过,仍然可以实现自定义客户端流程。 + 当前 Windows 上尚不支持内置的设备授权流程。不过,仍然可以实现自定义客户端流程。 @@ -7930,10 +7569,10 @@ void PQsetAuthDataHook(PQauthDataHook_type hook); int hook_fn(PGauthData type, PGconn *conn, void *data); - 当应用程序需要执行某个动作时,libpq会调用该回调。type描述所提出的请求,conn是正在认证的连接句柄,而data指向该请求特有的元数据。这个指针所指内容由type决定;支持的列表见。 + 当需要应用程序执行某个操作时,libpq会调用该回调。type描述所提出的请求,conn是正在认证的连接句柄,而data指向该请求特有的元数据。这个指针所指内容由type决定;支持的列表见 - 钩子可以串联起来,以支持协作式和/或回退式行为。一般来说,钩子实现应检查传入的type(以及可能的请求元数据和/或当前conn的设置),以决定是否处理某一项 authdata。如果不处理,则应把请求委托给链中的前一个钩子(可通过PQgetAuthDataHook获取)。 + 钩子可以串联起来,以支持协作和/或后备行为。一般来说,钩子实现应检查传入的type(以及可能的请求元数据和/或当前conn的设置),以决定是否处理某一项 authdata。如果不处理,则应把请求委托给链中的前一个钩子(可通过PQgetAuthDataHook获取)。 返回一个大于零的整数表示成功。返回负整数表示发生错误并放弃此次连接尝试。(值零保留给默认实现。) @@ -7975,23 +7614,23 @@ PQauthDataHook_type PQgetAuthDataHook(void); typedef struct _PGpromptOAuthDevice { - const char *verification_uri; /* verification URI to visit */ - const char *user_code; /* user code to enter */ - const char *verification_uri_complete; /* optional combination of URI and - * code, or NULL */ - int expires_in; /* seconds until user code expires */ + const char *verification_uri; /* 要访问的验证 URI */ + const char *user_code; /* 要输入的用户代码 */ + const char *verification_uri_complete; /* 可选的 URI 与代码组合, + * 或为 NULL */ + int expires_in; /* 距用户代码过期的秒数 */ } PGpromptOAuthDevice; - 可被包含在libpq中的 OAuth Device Authorization 流程要求最终用户使用浏览器访问一个 URL,然后输入一个代码,以允许libpq代表其连接到服务器。默认提示只是把verification_uriuser_code打印到标准错误。替换实现可以按任意偏好的方式展示这些信息,例如使用 GUI。 + 可被包含在libpq中的 OAuth 设备授权流程要求最终用户使用浏览器访问一个 URL,然后输入一个代码,以允许libpq代表其连接到服务器。默认提示只是把verification_uriuser_code打印到标准错误。替换实现可以按任意偏好的方式展示这些信息,例如使用 GUI。 该回调只会在内置设备授权流程中被调用。如果应用程序安装了自定义 OAuth 流程,或者libpq构建时未启用内置流程支持,则不会使用这种 authdata 类型。 - 如果提供了非空的verification_uri_complete,则可以选择把它用于非文本形式的验证(例如显示二维码)。在这种情况下,仍应向最终用户显示 URL 和用户代码,因为该代码需要由提供者手工确认,而 URL 也使得用户在无法使用非文本方式时仍可继续。更多信息见 - RFC 8628 第 3.3.1 节。 + 如果提供了不为 NULL 的verification_uri_complete,则可以选择把它用于非文本形式的验证(例如显示二维码)。在这种情况下,仍应向最终用户显示 URL 和用户代码,因为该代码需要由提供者手工确认,而 URL 也使得用户在无法使用非文本方式时仍可继续。更多信息见 + RFC 8628 第 3.3.1 节。
@@ -8004,7 +7643,7 @@ typedef struct _PGpromptOAuthDevice 适用于 PostgreSQL 18 及更高版本。 - 添加一个自定义流程实现;如果内置流程已安装,则用它替换内置流程。该钩子应当要么直接返回一个适用于当前 user/issuer/scope 组合的 Bearer 令牌(如果能在不阻塞的情况下获得),要么设置一个异步回调来获取令牌。 + 添加一个自定义流程实现;如果内置流程已安装,则用它替换内置流程。该钩子应当要么直接返回一个适用于当前用户、签发者及授权范围组合的 Bearer 令牌(如果能在不阻塞的情况下获得),要么设置一个异步回调来获取令牌。 @@ -8017,46 +7656,45 @@ typedef struct _PGpromptOAuthDevice typedef struct PGoauthBearerRequest { - /* Hook inputs (constant across all calls) */ - const char *openid_configuration; /* OIDC discovery URL */ - const char *scope; /* required scope(s), or NULL */ + /* 钩子输入(在所有调用中保持不变) */ + const char *openid_configuration; /* OIDC 发现 URL */ + const char *scope; /* 所需的授权范围,或为 NULL */ - /* Hook outputs */ + /* 钩子输出 */ /* - * Callback implementing a custom asynchronous OAuth flow. The signature is - * platform-dependent: PQ_SOCKTYPE is SOCKET on Windows, and int everywhere - * else. + * 实现自定义异步 OAuth 流程的回调。签名与平台有关: + * 在 Windows 上,PQ_SOCKTYPE 是 SOCKET;在其他平台上则为 int。 */ PostgresPollingStatusType (*async) (PGconn *conn, struct PGoauthBearerRequest *request, PQ_SOCKTYPE *altsock); - /* Callback to clean up custom allocations. */ + /* 清理自定义分配内存的回调。 */ void (*cleanup) (PGconn *conn, struct PGoauthBearerRequest *request); - char *token; /* acquired Bearer token */ - void *user; /* hook-defined allocated data */ + char *token; /* 获取的 Bearer 令牌 */ + void *user; /* 钩子定义并分配的数据 */ } PGoauthBearerRequest; - libpq会向该钩子提供两项信息:openid_configuration包含描述授权服务器所支持流程的 OAuth 发现文档 URL,而scope包含访问服务器所需的 OAuth scope 列表(以空格分隔,可以为空)。两者中的任意一个或两个都可能为NULL,表示无法发现该信息。(在这种情况下,实现可以通过其他预先配置的知识来确定要求,或者选择失败。) + libpq会向该钩子提供两项信息:openid_configuration包含描述授权服务器所支持流程的 OAuth 发现文档 URL,而scope包含访问服务器所需的 OAuth 授权范围列表(以空格分隔,可以为空)。两者中的任意一个或两个都可能为NULL,表示无法发现该信息。(在这种情况下,实现可以通过其他预先配置的知识来确定要求,或者选择失败。) - 该钩子的最终输出是token,它必须指向一个可在该连接上使用的有效 Bearer 令牌。(该令牌应由所指定的发行者签发,并持有所请求的 scope,否则连接会被服务器的验证器模块拒绝。)分配得到的令牌字符串必须在libpq完成连接之前始终有效;该钩子应设置cleanup回调,以便在libpq不再需要该令牌时调用。 + 该钩子的最终输出是token,它必须指向一个可在该连接上使用的有效 Bearer 令牌。(该令牌应由所指定的签发者签发,并持有所请求的授权范围,否则连接会被服务器的验证器模块拒绝。)分配得到的令牌字符串必须在libpq完成连接之前始终有效;该钩子应设置cleanup回调,以便在libpq不再需要该令牌时调用。 - 如果某个实现无法在首次调用钩子时立即产生token,则应设置async回调,以处理与授权服务器之间的非阻塞通信。 - + 如果实现在首次调用钩子时无法立即生成 token,应设置 async 回调,以处理与授权服务器之间的非阻塞通信。 + PQAUTHDATA_OAUTH_BEARER_TOKEN钩子回调中执行阻塞操作,会干扰诸如PQconnectPoll之类的非阻塞连接 API,并阻止并发连接继续推进。那些只使用同步连接原语(例如PQconnectdb)的应用程序,可以在钩子中同步获取令牌,而不是实现async回调,但这样它们必然一次只能处理一个连接。 - 从钩子返回后,将立即调用该回调以启动流程。当回调在不阻塞的情况下无法继续推进时,它应在设置*altsock后返回PGRES_POLLING_READINGPGRES_POLLING_WRITING,其中*altsock是当可以再次取得进展时会被标记为可读/可写的文件描述符。(然后,这个描述符会通过PQsocket()提供给顶层轮询循环。)当流程完成时,在设置好token之后返回PGRES_POLLING_OK;如果失败,则返回PGRES_POLLING_FAILED。 - +从钩子返回后,会立即调用该回调以启动流程。当回调无法在不阻塞的情况下继续时,应先将 *altsock 设为一个文件描述符,该描述符会在可以继续时被标记为可读或可写,然后返回 PGRES_POLLING_READINGPGRES_POLLING_WRITING。(该描述符随后会通过 PQsocket() 提供给顶层轮询循环。)流程完成时,应先设置 token,再返回 PGRES_POLLING_OK;返回 PGRES_POLLING_FAILED 表示失败。 +
- 实现可能希望在多次调用asynccleanup回调之间保存额外的数据用于记账。为此提供了user指针;libpq不会触碰其内容,应用程序可以按自己的需要使用它。(记得在令牌清理时释放相关分配。) + 实现可能希望在多次调用asynccleanup回调之间保存额外的数据用于记录状态。为此提供了user指针;libpq不会触碰其内容,应用程序可以按自己的需要使用它。(记得在令牌清理时释放相关分配。)
@@ -8080,13 +7718,13 @@ typedef struct PGoauthBearerRequest typedef struct { - PGoauthBearerRequest v1; /* see the PGoauthBearerRequest struct, above */ + PGoauthBearerRequest v1; /* 参见上面的 PGoauthBearerRequest 结构体 */ - /* Hook inputs (constant across all calls) */ - const char *issuer; /* the issuer identifier (RFC 9207) in use */ + /* 钩子输入(在所有调用中保持不变) */ + const char *issuer; /* 使用中的签发者标识符(RFC 9207) */ - /* Hook outputs */ - const char *error; /* hook-defined error message */ + /* 钩子输出 */ + const char *error; /* 钩子定义的错误消息 */ } PGoauthBearerRequestV2;
@@ -8094,24 +7732,24 @@ typedef struct 应用程序必须首先使用v1结构体成员来实现基础 API,如上面的 说明所述。 libpq还保证,传给v1.async和 - v1.cleanup回调的request指针可以安全地转换为 + v1.cleanup回调的request指针可以安全地强制转换为 (PGoauthBearerRequestV2 *),以便使用下面描述的附加成员。
- 只有当钩子类型为PQAUTHDATA_OAUTH_BEARER_TOKEN_V2时,才可以安全地转换为 + 只有当钩子类型为PQAUTHDATA_OAUTH_BEARER_TOKEN_V2时,才可以安全地强制转换为 (PGoauthBearerRequestV2 *)。如果钩子实现试图在处理 v1 (PQAUTHDATA_OAUTH_BEARER_TOKEN)请求时访问 v2 成员,应用程序可能会崩溃或表现异常。 - 除了 版本 1 API 的功能之外,v2 结构体还为该钩子提供了一个额外输入和一个额外输出: + 除版本 1 API 的功能外,v2 结构体还为该钩子提供了一个额外输入和一个额外输出: - issuer包含当前连接所使用的 签发者标识符(issuer identifier),定义见 + issuer包含当前连接所使用的签发者标识符(issuer identifier),定义见 RFC 9207。 - 该标识符来自。为避免 混淆攻击,自定义流程应确保授权服务器提供的任何发现元数据都与该 签发者 ID 一致。 + 该标识符来自。为避免混淆攻击,自定义流程应确保授权服务器提供的任何发现元数据都与该签发者 ID 一致。 当流程失败时,error可以被设置为指向一条自定义错误消息。 @@ -8153,7 +7791,7 @@ PGOAUTHDEBUG=UNSAFE 旧格式;启用所 http(危险) - 允许在 OAuth 提供者交换期间使用未加密的 HTTP。 + 允许在与 OAuth 提供者交互期间使用未加密的 HTTP。 这会让 OAuth 凭据通过未加密连接传输,极其危险,只应在本地测试时使用。 @@ -8223,7 +7861,7 @@ PGOAUTHDEBUG=UNSAFE:http,call-count 危险选项与安全选项 - 在线程化程序中的行为 + 多线程程序中的行为 线程 @@ -8262,7 +7900,7 @@ int PQisthreadsafe(); - 已废弃的函数不是线程安全的,不应在多线程程序中使用。可以用替代;可以用替代。 + 已弃用的函数 不是线程安全的,不应在多线程程序中使用。 可以用 替代; 可以用 替代。 @@ -8270,13 +7908,13 @@ int PQisthreadsafe(); - 同样地,如果你在应用程序中使用Curl,并且在启动新线程之前还没有先对 libcurl 进行全局初始化,那么你也需要通过PQregisterThreadLock协作地为任何可能初始化 libcurl 的代码加锁。对于支持线程安全初始化的较新版本Curl,这一限制已被解除;这类构建可以通过其版本元数据中声明的threadsafe特性识别出来。 + 同样地,如果你在应用程序中使用Curl并且在启动新线程之前还没有先对 libcurl 进行全局初始化,那么你也需要通过PQregisterThreadLock协作地为任何可能初始化 libcurl 的代码加锁。对于支持线程安全初始化的较新版本Curl,这一限制已被解除;这类构建可以通过其版本元数据中声明的threadsafe特性识别出来。 - 编译 <application>libpq</application> 程序 + 构建 <application>libpq</application> 程序 编译 @@ -8284,16 +7922,16 @@ int PQisthreadsafe(); - 要编译(即编译并且链接)一个使用libpq的程序,你需要做下列所有的事情: + 要构建(即编译和链接)一个使用 libpq 的程序,需要完成以下所有步骤: - 包括libpq-fe.h头文件: + 包含 libpq-fe.h 头文件: #include <libpq-fe.h> - 如果你无法这样做,那么你通常会从你的编译器得到像这样的错误消息: +如果没有这样做,编译器通常会给出类似以下内容的错误消息: foo.c: In function `main': foo.c:34: `PGconn' undeclared (first use in this function) @@ -8302,24 +7940,24 @@ foo.c:54: `CONNECTION_BAD' undeclared (first use in this function) foo.c:68: `PGRES_COMMAND_OK' undeclared (first use in this function) foo.c:95: `PGRES_TUPLES_OK' undeclared (first use in this function) - +
- 通过为你的编译器提供-Idirectory选项,向你的编译器指出PostgreSQL头文件安装在哪里(在某些情况下编译器默认将查看该目录,因此你可以忽略这个选项)。例如你的编译命令行可能看起来像: + 向编译器提供 -Idirectory 选项,指定 PostgreSQL 头文件的安装目录。(某些情况下,编译器默认会搜索该目录,此时可以省略这个选项。)例如,编译命令行可以是: cc -c -I/usr/local/pgsql/include testprog.c - 如果你在使用 makefile,那么把该选项加到CPPFLAGS变量中: +如果使用 makefile,请将该选项添加到 CPPFLAGS 变量中: CPPFLAGS += -I/usr/local/pgsql/include - +
如果你的程序可能由其他用户编译,那么你不应该像那样硬编码目录位置。你可以运行工具pg_configpg_configwith libpq在本地系统上找出头文件在哪里: + sortas="libpq">用于 libpq在本地系统上找出头文件在哪里: $ pg_config --includedir /usr/local/include @@ -8327,8 +7965,7 @@ CPPFLAGS += -I/usr/local/pgsql/include - 如果你安装了pkg-configpkg-configwith - libpq,你可以运行: + 如果你安装了pkg-configpkg-config用于 libpq,你可以运行: $ pkg-config --cflags libpq -I/usr/local/include @@ -8337,20 +7974,20 @@ CPPFLAGS += -I/usr/local/pgsql/include - 无法为编译器指定正确的选项将导致一个错误消息,例如: + 未向编译器指定正确的选项将导致类似以下内容的错误消息: testlibpq.c:8:22: libpq-fe.h: No such file or directory - +
- 当链接最终的程序时,指定选项-lpq,这样libpq库会被编译进去,也可以用选项-Ldirectory向编译器指出libpq库所在的位置(再次,编译器将默认搜索某些目录)。为了最大的可移植性,将选项放在选项前面。例如: + 链接最终程序时,指定 -lpq 选项以链接 libpq 库,同时指定 -Ldirectory 选项,告知编译器 libpq 库所在的目录。(同样,编译器默认会搜索某些目录。)为获得最大的可移植性,请将 选项放在 选项之前。例如: cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq - + 你也可以使用pg_config找出库目录: @@ -8377,7 +8014,7 @@ testlibpq.o(.text+0x60): undefined reference to `PQsetdbLogin' testlibpq.o(.text+0x71): undefined reference to `PQstatus' testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' - 这意味着你忘了 . + 这意味着你忘记了 /usr/bin/ld: cannot find -lpq @@ -8394,7 +8031,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' 示例程序 - 这些示例和其他示例可以在源代码发布的src/test/examples目录中找到。 + 这些示例和其他示例可在源代码发行包的src/test/examples目录中找到。 @@ -8409,7 +8046,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' * * testlibpq.c * - * Test the C version of libpq, the PostgreSQL frontend library. + * 测试 PostgreSQL 前端库 libpq 的 C 语言版本。 */ #include #include @@ -8433,26 +8070,25 @@ main(int argc, char **argv) j; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -8463,19 +8099,17 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Our test case here involves using a cursor, for which we must be inside - * a transaction block. We could do the whole thing with a single - * PQexec() of "select * from pg_database", but that's too trivial to make - * a good example. + * 这里的测试用例使用游标,因此必须处于事务块内。 + * 只需调用一次 PQexec() 执行 "SELECT * FROM pg_database" 就能完成全部操作, + * 但这太简单了,不足以作为一个好的示例。 */ - /* Start a transaction block */ + /* 开始一个事务块 */ res = PQexec(conn, "BEGIN"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -8486,9 +8120,9 @@ main(int argc, char **argv) PQclear(res); /* - * Fetch rows from pg_database, the system catalog of databases + * 从数据库系统目录 pg_database 中获取行 */ - res = PQexec(conn, "DECLARE myportal CURSOR FOR select * from pg_database"); + res = PQexec(conn, "DECLARE myportal CURSOR FOR SELECT * FROM pg_database"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { fprintf(stderr, "DECLARE CURSOR failed: %s", PQerrorMessage(conn)); @@ -8505,13 +8139,13 @@ main(int argc, char **argv) exit_nicely(conn); } - /* first, print out the attribute names */ + /* 首先,打印属性名 */ nFields = PQnfields(res); for (i = 0; i < nFields; i++) printf("%-15s", PQfname(res, i)); printf("\n\n"); - /* next, print out the rows */ + /* 接着,打印各行 */ for (i = 0; i < PQntuples(res); i++) { for (j = 0; j < nFields; j++) @@ -8521,15 +8155,15 @@ main(int argc, char **argv) PQclear(res); - /* close the portal ... we don't bother to check for errors ... */ + /* 关闭 portal……这里不再检查错误…… */ res = PQexec(conn, "CLOSE myportal"); PQclear(res); - /* end the transaction */ + /* 结束事务 */ res = PQexec(conn, "END"); PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -8549,15 +8183,15 @@ main(int argc, char **argv) * * * testlibpq2.c - * Test of the asynchronous notification interface + * 测试异步通知接口 * - * Start this program, then from psql in another window do + * 启动此程序,然后在另一个窗口中通过 psql 执行 * NOTIFY TBL2; - * Repeat four times to get this program to exit. + * 重复四次后,此程序便会退出。 * - * Or, if you want to get fancy, try this: - * populate a database with the following commands - * (provided in src/test/examples/testlibpq2.sql): + * 或者,可以尝试更复杂的示例: + * 使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq2.sql 中): * * CREATE SCHEMA TESTLIBPQ2; * SET search_path = TESTLIBPQ2; @@ -8566,7 +8200,7 @@ main(int argc, char **argv) * CREATE RULE r1 AS ON INSERT TO TBL1 DO * (INSERT INTO TBL2 VALUES (new.i); NOTIFY TBL2); * - * Start this program, then from psql do this four times: + * 启动此程序,然后通过 psql 将以下命令执行四次: * * INSERT INTO TESTLIBPQ2.TBL1 VALUES (10); */ @@ -8578,11 +8212,9 @@ main(int argc, char **argv) #include #include #include +#include #include #include -#ifdef HAVE_SYS_SELECT_H -#include -#endif #include "libpq-fe.h" @@ -8603,26 +8235,25 @@ main(int argc, char **argv) int nnotifies; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -8633,13 +8264,12 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Issue LISTEN command to enable notifications from the rule's NOTIFY. + * 发出 LISTEN 命令,以接收规则中的 NOTIFY 发出的通知。 */ res = PQexec(conn, "LISTEN TBL2"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -8650,14 +8280,13 @@ main(int argc, char **argv) } PQclear(res); - /* Quit after four notifies are received. */ + /* 收到四次通知后退出。 */ nnotifies = 0; while (nnotifies < 4) { /* - * Sleep until something happens on the connection. We use select(2) - * to wait for input, but you could also use poll() or similar - * facilities. + * 休眠,直到连接上有事件发生。这里使用 select(2) 等待输入, + * 也可以使用 poll() 或类似机制。 */ int sock; fd_set input_mask; @@ -8665,7 +8294,7 @@ main(int argc, char **argv) sock = PQsocket(conn); if (sock < 0) - break; /* shouldn't happen */ + break; /* 不应发生 */ FD_ZERO(&input_mask); FD_SET(sock, &input_mask); @@ -8676,7 +8305,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Now check for input */ + /* 现在检查是否有输入 */ PQconsumeInput(conn); while ((notify = PQnotifies(conn)) != NULL) { @@ -8691,7 +8320,7 @@ main(int argc, char **argv) fprintf(stderr, "Done.\n"); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -8711,19 +8340,18 @@ main(int argc, char **argv) * * * testlibpq3.c - * Test out-of-line parameters and binary I/O. + * 测试在 SQL 命令文本之外独立传递的参数和二进制 I/O。 * - * Before running this, populate a database with the following commands - * (provided in src/test/examples/testlibpq3.sql): + * 运行前,使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq3.sql 中): * * CREATE SCHEMA testlibpq3; * SET search_path = testlibpq3; - * SET standard_conforming_strings = ON; * CREATE TABLE test1 (i int4, t text, b bytea); * INSERT INTO test1 values (1, 'joe''s place', '\000\001\002\003\004'); * INSERT INTO test1 values (2, 'ho there', '\004\003\002\001\000'); * - * The expected output is: + * 预期输出为: * * tuple 0: got * i = (4 bytes) 1 @@ -8747,7 +8375,7 @@ main(int argc, char **argv) #include #include "libpq-fe.h" -/* for ntohl/htonl */ +/* 用于 ntohl/htonl */ #include #include @@ -8759,9 +8387,8 @@ exit_nicely(PGconn *conn) } /* - * This function prints a query result that is a binary-format fetch from - * a table defined as in the comment above. We split it out because the - * main() function uses it twice. + * 此函数打印从上面注释所定义的表中以二进制格式获取的查询结果。 + * 由于 main() 会使用它两次,因此将它单独提取成一个函数。 */ static void show_binary_results(PGresult *res) @@ -8772,7 +8399,7 @@ show_binary_results(PGresult *res) t_fnum, b_fnum; - /* Use PQfnumber to avoid assumptions about field order in result */ + /* 使用 PQfnumber,以避免对结果中的字段顺序作出假设 */ i_fnum = PQfnumber(res, "i"); t_fnum = PQfnumber(res, "t"); b_fnum = PQfnumber(res, "b"); @@ -8785,24 +8412,22 @@ show_binary_results(PGresult *res) int blen; int ival; - /* Get the field values (we ignore possibility they are null!) */ + /* 获取字段值(这里忽略它们可能为 null 的情况!) */ iptr = PQgetvalue(res, i, i_fnum); tptr = PQgetvalue(res, i, t_fnum); bptr = PQgetvalue(res, i, b_fnum); /* - * The binary representation of INT4 is in network byte order, which - * we'd better coerce to the local byte order. + * INT4 的二进制表示采用网络字节序,最好将其转换为本机字节序。 */ ival = ntohl(*((uint32_t *) iptr)); /* - * The binary representation of TEXT is, well, text, and since libpq - * was nice enough to append a zero byte to it, it'll work just fine - * as a C string. + * TEXT 的二进制表示就是文本,而 libpq 会在其后追加一个零字节, + * 因此可以直接将其用作 C 字符串。 * - * The binary representation of BYTEA is a bunch of bytes, which could - * include embedded nulls so we have to pay attention to field length. + * BYTEA 的二进制表示是一组字节,其中可能嵌有零字节, + * 因此必须注意字段长度。 */ blen = PQgetlength(res, i, b_fnum); @@ -8830,26 +8455,25 @@ main(int argc, char **argv) uint32_t binaryIntVal; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SET search_path = testlibpq3"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -8860,27 +8484,25 @@ main(int argc, char **argv) PQclear(res); /* - * The point of this program is to illustrate use of PQexecParams() with - * out-of-line parameters, as well as binary transmission of data. + * 此程序旨在演示如何使用 PQexecParams() 在 SQL 命令文本之外独立传递参数, + * 以及如何以二进制方式传输数据。 * - * This first example transmits the parameters as text, but receives the - * results in binary format. By using out-of-line parameters we can avoid - * a lot of tedious mucking about with quoting and escaping, even though - * the data is text. Notice how we don't have to do anything special with - * the quote mark in the parameter value. + * 第一个示例以文本形式传输参数,但以二进制格式接收结果。 + * 通过在 SQL 命令文本之外独立传递参数,即使数据是文本,也可以避免 + * 许多繁琐的引号和转义处理。注意,参数值中的引号无需任何特殊处理。 */ - /* Here is our out-of-line parameter value */ + /* 这是在 SQL 命令文本之外独立传递的参数值 */ paramValues[0] = "joe's place"; res = PQexecParams(conn, "SELECT * FROM test1 WHERE t = $1", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, - NULL, /* don't need param lengths since text */ - NULL, /* default to all text params */ - 1); /* ask for binary results */ + NULL, /* 文本参数无需指定长度 */ + NULL, /* 默认所有参数均为文本 */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -8894,31 +8516,29 @@ main(int argc, char **argv) PQclear(res); /* - * In this second example we transmit an integer parameter in binary form, - * and again retrieve the results in binary form. + * 第二个示例以二进制形式传输一个整数参数,并同样以二进制形式获取结果。 * - * Although we tell PQexecParams we are letting the backend deduce - * parameter type, we really force the decision by casting the parameter - * symbol in the query text. This is a good safety measure when sending - * binary parameters. + * 虽然我们告诉 PQexecParams 让后端推断参数类型,但实际上, + * 查询文本中的参数符号经过强制类型转换,因此其类型已经确定。 + * 发送二进制参数时,这是一项良好的安全措施。 */ - /* Convert integer value "2" to network byte order */ + /* 将整数值 "2" 转换为网络字节序 */ binaryIntVal = htonl((uint32_t) 2); - /* Set up parameter arrays for PQexecParams */ + /* 为 PQexecParams 设置参数数组 */ paramValues[0] = (char *) &binaryIntVal; paramLengths[0] = sizeof(binaryIntVal); - paramFormats[0] = 1; /* binary */ + paramFormats[0] = 1; /* 二进制 */ res = PQexecParams(conn, "SELECT * FROM test1 WHERE i = $1::int4", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, paramLengths, paramFormats, - 1); /* ask for binary results */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -8931,7 +8551,7 @@ main(int argc, char **argv) PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; diff --git a/zh/19/lobj.sgml b/zh/19/lobj.sgml index 82d63771..6922fa91 100644 --- a/zh/19/lobj.sgml +++ b/zh/19/lobj.sgml @@ -3,8 +3,8 @@ 大对象 - large object - BLOBlarge object + 大对象 + BLOB大对象 PostgreSQL提供一种大对象机制,允许以流式方式访问存储在专用大对象结构中的用户数据。在处理大到无法方便地整体操作的数据值时,这种流式访问非常有用。 @@ -19,7 +19,7 @@ TOAST - versus large objects + 与大对象对比 @@ -190,11 +190,11 @@ inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE); int lo_write(PGconn *conn, int fd, const char *buf, size_t len); - 将buf中的len字节(其大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 + 将buf中的len字节(缓冲区大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -211,7 +211,7 @@ int lo_read(PGconn *conn, int fd, char *buf, size_t len); - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -277,7 +277,7 @@ int64_t lo_tell64(PGconn *conn, int fd); int lo_truncate(PGconn *conn, int fd, size_t len); - 该函数把大对象描述符fd截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用空字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 + 该函数把大对象描述符fd对应的大对象截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用零字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 @@ -426,16 +426,16 @@ CREATE TABLE image ( raster oid ); -SELECT lo_creat(-1); -- returns OID of new, empty large object +SELECT lo_creat(-1); -- 返回新建的空大对象的 OID -SELECT lo_create(43213); -- attempts to create large object with OID 43213 +SELECT lo_create(43213); -- 尝试创建 OID 为 43213 的大对象 -SELECT lo_unlink(173454); -- deletes large object with OID 173454 +SELECT lo_unlink(173454); -- 删除 OID 为 173454 的大对象 INSERT INTO image (name, raster) VALUES ('beautiful image', lo_import('/etc/motd')); -INSERT INTO image (name, raster) -- same as above, but specify OID to use +INSERT INTO image (name, raster) -- 与上例相同,但指定要使用的 OID VALUES ('beautiful image', lo_import('/etc/motd', 68583)); SELECT lo_export(image.raster, '/tmp/motd') FROM image @@ -444,7 +444,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image - 服务器端的lo_importlo_export函数与其客户端对应函数的行为差异很大。这两个函数在服务器的文件系统中读写文件,使用数据库所有者的权限。因此,默认情况下它们的使用仅限于超级用户。相比之下,客户端导入和导出函数在客户端的文件系统中读写文件,使用客户端程序的权限。客户端函数不需要任何数据库权限,除了读取或写入相关大对象所需的权限。 + 服务器端的lo_importlo_export函数与其客户端对应函数的行为差异很大。这两个函数在服务器的文件系统中读写文件,使用运行数据库服务器的操作系统用户的权限。因此,默认情况下它们的使用仅限于超级用户。相比之下,客户端导入和导出函数在客户端的文件系统中读写文件,使用客户端程序的权限。客户端函数不需要任何数据库权限,除了读取或写入相关大对象所需的权限。 @@ -463,7 +463,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image 示例程序 - 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行版的src/test/examples/testlo.c中找到。 + 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行包的src/test/examples/testlo.c中找到。 @@ -472,13 +472,13 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /*----------------------------------------------------------------- * * testlo.c - * test using large objects with libpq + * 测试使用 libpq 操作大对象 * * Portions Copyright (c) 1996-2026, PostgreSQL Global Development Group * Portions Copyright (c) 1994, Regents of the University of California * * - * IDENTIFICATION + * 标识 * src/test/examples/testlo.c * *----------------------------------------------------------------- @@ -498,7 +498,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /* * importFile - - * import file "in_filename" into database as large object "lobjOid" + * 将文件 "in_filename" 作为大对象 "lobjOid" 导入数据库 * */ static Oid @@ -512,16 +512,16 @@ importFile(PGconn *conn, char *filename) int fd; /* - * open the file to be read in + * 打开要读取的文件 */ fd = open(filename, O_RDONLY, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"\n", filename); } /* - * create the large object + * 创建大对象 */ lobjId = lo_creat(conn, INV_READ | INV_WRITE); if (lobjId == 0) @@ -530,7 +530,7 @@ importFile(PGconn *conn, char *filename) lobj_fd = lo_open(conn, lobjId, INV_WRITE); /* - * read in from the Unix file and write to the inversion file + * 从 Unix 文件读取数据并写入大对象 */ while ((nbytes = read(fd, buf, BUFSIZE)) > 0) { @@ -568,7 +568,7 @@ pickout(PGconn *conn, Oid lobjId, int start, int len) fprintf(stderr, ">>> %s", buf); nread += nbytes; if (nbytes <= 0) - break; /* no more data? */ + break; /* 没有更多数据? */ } free(buf); fprintf(stderr, "\n"); @@ -614,7 +614,7 @@ overwrite(PGconn *conn, Oid lobjId, int start, int len) /* * exportFile - - * export large object "lobjOid" to file "out_filename" + * 将大对象 "lobjOid" 导出到文件 "out_filename" * */ static void @@ -627,24 +627,24 @@ exportFile(PGconn *conn, Oid lobjId, char *filename) int fd; /* - * open the large object + * 打开大对象 */ lobj_fd = lo_open(conn, lobjId, INV_READ); if (lobj_fd < 0) fprintf(stderr, "cannot open large object %u", lobjId); /* - * open the file to be written to + * 打开要写入的文件 */ fd = open(filename, O_CREAT | O_WRONLY | O_TRUNC, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"", filename); } /* - * read in from the inversion file and write to the Unix file + * 从大对象读取数据并写入 Unix 文件 */ while ((nbytes = lo_read(conn, lobj_fd, buf, BUFSIZE)) > 0) { @@ -689,18 +689,18 @@ main(int argc, char **argv) out_filename = argv[3]; /* - * set up the connection + * 建立连接 */ conn = PQsetdb(NULL, NULL, NULL, NULL, database); - /* check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) diff --git a/zh/19/logicaldecoding.sgml b/zh/19/logicaldecoding.sgml index 62d42e32..0e58da60 100644 --- a/zh/19/logicaldecoding.sgml +++ b/zh/19/logicaldecoding.sgml @@ -601,8 +601,7 @@ DETAIL: Synchronization could lead to data loss, because the remote slot needs binary (boolean) - 启用二进制传输模式。二进制模式比文本模式更快,但稳健性略差。默认值 - 为 off。 + 启用二进制传输模式。二进制模式比文本模式更快,但稳健性略差。默认值为 off @@ -630,8 +629,7 @@ DETAIL: Synchronization could lead to data loss, because the remote slot needs 当设置为 on 时, - pgoutput 会流式传输大型进行中事务。这要求协议 - 版本为 2 或更高。 + pgoutput 会流式传输大型进行中事务。这要求协议版本为 2 或更高。 当设置为 parallel 时, @@ -654,9 +652,7 @@ DETAIL: Synchronization could lead to data loss, because the remote slot needs origin (enum) - 指定是否按来源发送更改。可选值包括 none,仅发送 - 没有关联来源的更改;以及 any,不论其来源为何都 - 发送更改。这可用于避免复制节点之间出现环路(同一数据的无限复制)。 + 指定是否按来源发送更改。可选值包括 none,仅发送没有关联来源的更改;以及 any,不论其来源为何都发送更改。这可用于避免复制节点之间出现环路(同一数据的无限复制)。 默认值为 any diff --git a/zh/19/monitoring.sgml b/zh/19/monitoring.sgml index e6bed225..457a0af9 100644 --- a/zh/19/monitoring.sgml +++ b/zh/19/monitoring.sgml @@ -4860,7 +4860,7 @@ description | Waiting for a newly initialized WAL file to reach durable storage checksum_failures bigint - 在此数据库(或共享对象)中检测到的数据页校验和失败数。即使 设置发生变化,已检测到的失败也不会被重置。未启用数据校验和初始化的集簇会显示为 0。在 PostgreSQL 18 及更早版本中,对于未启用数据校验和的集簇,此值为 NULL。 + 在此数据库(或共享对象)中检测到的数据页校验和失败次数。即使 设置发生变化,已检测到的失败也不会被重置。未启用数据校验和初始化的集簇会显示为 0。在 PostgreSQL 18 及更早版本中,对于未启用数据校验和的集簇,此值为 NULL @@ -4869,7 +4869,7 @@ description | Waiting for a newly initialized WAL file to reach durable storage checksum_last_failure timestamp with time zone - 在此数据库(或共享对象)中检测到最后一个数据页校验和失败的时间。无论 设置如何,都会报告最近一次失败。 + 在此数据库(或共享对象)中最后一次检测到数据页校验和失败的时间。无论 设置如何,都会报告最近一次失败。 diff --git a/zh/19/oauth-validators.sgml b/zh/19/oauth-validators.sgml index 09fecf9d..97f0873b 100644 --- a/zh/19/oauth-validators.sgml +++ b/zh/19/oauth-validators.sgml @@ -80,27 +80,27 @@ 接下来,验证器必须确保终端用户已授权客户端代表其访问服务器。 - 这通常需要检查分配给令牌的作用域(scope), + 这通常需要检查分配给令牌的授权范围, 以确认其覆盖当前 HBA 参数所要求的数据库访问权限。 该步骤的目的是防止 OAuth 客户端在虚假前提下获取令牌。 - 如果验证器要求所有令牌都必须携带覆盖数据库访问的作用域, + 如果验证器要求所有令牌都必须携带覆盖数据库访问的授权范围, 提供方在流程中就应明确提示用户授予该访问权限。 这样一来,如果客户端本不应使用其凭据连接数据库, 用户就有机会拒绝该请求。 - 也可以通过部署架构的带外知识在没有显式作用域的情况下完成客户端授权, + 也可以通过部署架构的带外知识在没有显式授权范围的情况下完成客户端授权, 但这样会让用户无法参与授权过程, 用户将无法发现部署错误,而此类错误也可能被静默利用。 - 如果不提示用户授予额外作用域, + 如果不提示用户授予额外授权范围, 则对数据库的访问必须被严格限制为仅允许受信任客户端 即,“受信任”是指 OAuth 客户端与 PostgreSQL 服务器由同一实体控制。 - 特别地,libpq 支持的 Device Authorization 客户端流程通常不满足此条件, + 特别地,libpq 支持的设备授权客户端流程通常不满足此条件, 因为它的设计目标是公开/非受信任客户端。 @@ -248,7 +248,7 @@ 若要完全绕过用户名映射,并让验证器模块承担额外的用户连接授权职责, 可在 HBA 中配置 。 - 此后模块可使用令牌作用域或等效方法判断用户是否允许以其期望角色连接。 + 此后模块可使用令牌授权范围或等效方法判断用户是否允许以其期望角色连接。 用户标识符仍会由服务器记录,但它不再参与是否继续连接的判定。 diff --git a/zh/19/pgtrgm.sgml b/zh/19/pgtrgm.sgml index 09cc6fe5..fa60934c 100644 --- a/zh/19/pgtrgm.sgml +++ b/zh/19/pgtrgm.sgml @@ -513,11 +513,11 @@ SELECT * FROM test_trgm WHERE t ~ '(foo|bar)'; - 文本搜索集成 + 文本检索集成 与全文索引结合使用时,三字符组匹配是非常有用的工具。 - 尤其是,它有助于识别那些因拼写错误而无法被全文搜索机制直接匹配的输入词。 + 尤其是,它有助于识别那些因拼写错误而无法被全文检索机制直接匹配的输入词。 diff --git a/zh/19/protocol.sgml b/zh/19/protocol.sgml index cbccec3e..9d6dce4f 100644 --- a/zh/19/protocol.sgml +++ b/zh/19/protocol.sgml @@ -26,15 +26,15 @@ 概述 - 协议在启动和正常操作过程中有不同的阶段。在启动阶段里,前端打开一个到服务器的连接并且认证自身以满足服务器(这可能涉及到一条或多条消息,取决于使用的认证方法)。 如果一切正常,服务器就发送状态信息给前端,并最后进入正常操作。除了最初的启动请求消息之外,协议的这个部分是服务器驱动的。 + 协议分为启动和正常操作两个阶段。在启动阶段,前端打开到服务器的连接,并完成服务器所要求的认证。(这可能只涉及一条消息,也可能因所用认证方法不同而需要多条消息。)如果一切顺利,服务器随后会向前端发送状态信息,并最终进入正常操作。除最初的启动请求消息外,协议的这一部分由服务器驱动。 - 在正常操作中,前端发送查询和其它命令到后端,然后后端返回查询结果和其它响应。在少数几种情况(比如NOTIFY)中,后端会发送未被请求的消息,但这个会话中的绝大多部分都是由前端请求驱动的。 + 在正常操作中,前端向后端发送查询及其他命令,后端则返回查询结果和其他响应。少数情况下(例如 NOTIFY),后端会发送未请求的消息,但会话中的绝大多数交互仍由前端请求驱动。 - 会话的终止通常是由前端来选择的,但是也可以在某些情况下由后端强制执行。不管在那种情况下,如果后端关闭连接,那么它将在退出之前回滚所有打开的(未完成的)事务。 + 会话通常由前端选择终止,但在某些情况下也可能由后端强制终止。无论哪种情况,后端关闭连接时,都会在退出前回滚所有打开的(未完成的)事务。 @@ -73,9 +73,7 @@ 整个执行周期包括一个解析步骤,它从文本查询字符串创建预备语句; 一个绑定步骤,它根据预备语句和所需参数值创建 portal; - 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询 - (SELECTSHOW等),可以要求执行步骤只取回 - 有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 + 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询(SELECTSHOW等),可以要求执行步骤只取回有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 @@ -92,8 +90,8 @@ - 文本形式的数值是特定数据类型的输入/输出转换函数生成或接受的任何字符串。在传输形式上,字符串没有末尾空字符;如果前端要想把收到的值当作C字符串处理,那么必须自己加上一个(顺便说一下,文本格式不允许嵌入空字符)。 - + 值的文本表示是相应数据类型的输入/输出转换函数生成和接受的字符串。在传输形式中,值的末尾没有空字符;前端若要将收到的值作为 C 字符串处理,必须自行添加一个。(文本格式也不允许内嵌空字符。) + 整数的二进制表示采用网络字节序(最高有效字节在前)。至于其他数据类型,请查阅文档或源代码了解其二进制表示形式。要注意,复杂数据类型的二进制表示可能会在不同服务器版本之间发生变化;文本格式通常是可移植性更好的选择。 @@ -144,7 +142,7 @@ 3.2 PostgreSQL 18 及以后 - 当前最新版本。用于取消查询的 secret key 从 4 字节扩展为可变长度字段;BackendKeyData 与 CancelRequest 消息相应调整为可变长度负载。 + 当前最新版本。用于取消查询的密钥从 4 字节扩展为可变长度字段。BackendKeyData 消息已作相应调整,CancelRequest 消息则重新定义为使用可变长度负载。 3.0 @@ -170,12 +168,12 @@ 3.9999 - - 保留用于协议 防僵化测试(greasing)。libpq 可能会使用这个版本,它高于项目预期会用到的任何次版本,用于测试服务器和中间件是否正确实现协议版本协商。服务器不得为这个版本加入特例逻辑;它们只需把它与自己支持的最新版本比较(后者总会更小),然后通过 NegotiateProtocolVersion 消息进行降级。 + 保留用于协议防僵化测试(greasing)。libpq 可能会使用这个版本,它高于项目预期会用到的任何次版本,用于测试服务器和中间件是否正确实现协议版本协商。服务器不得为这个版本加入特例逻辑;它们只需把它与自己支持的最新版本比较(后者总会更小),然后通过 NegotiateProtocolVersion 消息进行降级。 3.1 - - 保留。PostgreSQL 从未使用 3.1;之所以跳过该版本,是因为旧版 pgbouncer 在协议协商中存在缺陷,会错误宣称支持 3.1。 + 保留。PostgreSQL 从未使用 3.1;之所以跳过该版本,是因为广泛使用的 pgbouncer 的旧版本在协议协商中存在缺陷,会错误宣称支持 3.1。 2.0 @@ -238,7 +236,7 @@ _pq_.test_protocol_negotiation - 保留用于协议 防僵化测试(greasing)。libpq 可能发送这个扩展,用于测试服务器和中间件是否正确实现协议扩展协商。服务器不得为这个参数加入特例逻辑;它们只需通过 NegotiateProtocolVersion 消息发送所有不受支持选项的列表(包括这个选项)即可。 + 保留用于协议防僵化测试(greasing)。libpq 可能发送这个扩展,用于测试服务器和中间件是否正确实现协议扩展协商。服务器不得为这个参数加入特例逻辑;它们只需通过 NegotiateProtocolVersion 消息发送所有不受支持选项的列表(包括这个选项)即可。 @@ -259,7 +257,7 @@ 启动 - 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地请求协议扩展,并包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,判断该连接在初步上是否可接受,以及是否需要额外的认证。 + 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地请求协议扩展,并包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,初步判断是否接受该连接,以及需要何种额外认证(如果需要)。 @@ -506,7 +504,7 @@ 表示即将返回行作为对SELECTFETCH等查询的响应。 - 此消息的内容描述了行的列布局。这将跟随每个返回给前端的行的DataRow消息。 + 此消息的内容描述了行的列布局。该消息之后,每个返回给前端的行都对应一条 DataRow 消息。 @@ -562,9 +560,7 @@ - - 对 SELECT 查询(或其他返回行集的查询,如 EXPLAINSHOW)的响应,通常包含 RowDescription、零条或多条 DataRow 消息,以及最后的 CommandComplete。向前端 COPY 或从前端 COPY 会调用中描述的特殊协议。所有其他类型的查询通常只产生一条 CommandComplete 消息。 - + SELECT 查询(或其他返回行集的查询,如 EXPLAINSHOW)的响应通常包含 RowDescription、零条或多条 DataRow 消息,以及最后的 CommandComplete。在前端与服务器之间执行 COPY 输入或输出时,会使用 所述的特殊协议。所有其他类型的查询通常只产生一条 CommandComplete 消息。 由于查询字符串可能包含若干条查询(以分号分隔),因此在后端完成整个查询字符串的处理之前,可能会出现多个这样的响应序列。只有在整个字符串处理完毕且后端已准备好接受新的查询字符串时,才会发出 ReadyForQuery 消息。 @@ -587,15 +583,15 @@ - 我们建议的方法是把前端代码写成状态机的风格,它可以在任何时刻接受任何有意义的消息类型,而不是假设消息的序列总是准确。 - + 建议以状态机的方式编写前端,使其能够在任何合理的时机接收相应类型的消息,而不把消息确切顺序的假设写死在代码中。 + 一个简单查询中的多条语句 - 当一个简单查询消息中包含多于一条SQL语句(被分号分隔)时,那些语句会被当做一个事务中执行,除非其中包括显式事务控制命令来强制不同的行为。例如,如果消息包括 + 当一个简单查询消息中包含多于一条SQL语句(被分号分隔)时,这些语句会作为单个事务执行,除非其中包括显式事务控制命令来强制不同的行为。例如,如果消息包括 INSERT INTO mytable VALUES(1); SELECT 1/0; @@ -617,15 +613,15 @@ SELECT 1/0; - 这种行为通过在一个隐式事务块中的一个多语句Query消息中运行那些语句来实现,除非它们运行在某个显式事务块中。隐式事务块与常规事务块之间的区别在于隐式块会在Query消息结束时自动被关闭,或者是在没有错误的情况下由一个隐式提交关闭,或者是在有错误时由一个隐式的回滚关闭。这类似于一个语句自己执行(当不在事务块中时)时发生的隐式提交或回滚。 - + 这种行为的实现方式是:除非已有显式事务块可供这些语句执行,否则就在一个隐式事务块中执行多语句 Query 消息中的语句。隐式事务块与常规事务块的主要区别在于,隐式块会在 Query 消息结束时自动关闭:没有错误时隐式提交,发生错误时隐式回滚。这类似于单独执行一条语句(不在事务块中)时发生的隐式提交或回滚。 + - 如果会话已经在一个事务块中,作为前面某个消息中BEGIN的结果,那么Query消息会简单地继续那个事务块,不管该消息包含一个语句还是多个语句。不过,如果该Query消息包含一个关闭现有事务块的COMMIT或者ROLLBACK,那么任何接下来的语句都会在一个隐式事务块中被执行。反过来,如果在多语句Query消息中出现一个BEGIN,那么它会开始一个常规事务块,这个常规事务块将只能被一个显式的COMMIT或者ROLLBACK终止,不管这两种命令是出现在这个Query消息还是后面的一个Query消息中。如果BEGIN跟在一些作为隐式事务块执行的语句后面,那些语句不会被立刻提交。实际上,它们会被包括到新的常规事务块中。 + 如果会话因前面某条消息中的BEGIN而已经处于事务块中,那么 Query 消息会继续该事务块,不管该消息包含一个语句还是多个语句。不过,如果该Query消息包含一个关闭现有事务块的COMMIT或者ROLLBACK,那么任何接下来的语句都会在一个隐式事务块中被执行。反过来,如果在多语句Query消息中出现一个BEGIN,那么它会开始一个常规事务块,这个常规事务块将只能被一个显式的COMMIT或者ROLLBACK终止,不管这两种命令是出现在这个Query消息还是后面的一个Query消息中。如果BEGIN跟在一些作为隐式事务块执行的语句后面,那些语句不会被立刻提交。实际上,它们会被包括到新的常规事务块中。 - 出现在一个隐式事务块中的COMMIT或者ROLLBACK会被正常执行并且关闭该隐式块。不过,由于没有先前的BEGIN配对的COMMIT或者ROLLBACK表示一种错误,所以将会发出一个警告。如果后面还有更多语句,将会为它们开始一个新的隐式事务块。 + 出现在一个隐式事务块中的COMMIT或者ROLLBACK会被正常执行并且关闭该隐式块。不过,由于没有先前的BEGIN配对的COMMIT或者ROLLBACK可能表示误操作,所以会发出警告。如果后面还有更多语句,将会为它们开始一个新的隐式事务块。 @@ -633,17 +629,17 @@ SELECT 1/0; - 记住,不管任何事务控制命令存不存在,Query消息的执行会在第一个错误时停止。因此,对于下面的在一个Query消息中的示例 + 请记住,无论消息中是否包含事务控制命令,Query 消息的执行都会在第一个错误处停止。例如,单条 Query 消息包含以下内容时: BEGIN; SELECT 1/0; ROLLBACK; - 会话中将留下一个失败的常规事务块,因为在出现除零错误后不会到达ROLLBACK。将需要另一个ROLLBACK把会话恢复到一种可用的状态。 - +会话会停留在失败的常规事务块内,因为发生除零错误后不会再执行ROLLBACK。需要另发一条ROLLBACK,才能将会话恢复到可用状态。 + - 另一种要注意的行为是,最初的词法和语法分析是在整个查询字符串被执行之前进行的。因此后面的语句中的简单错误(例如拼写错误的关键词)可能会阻止任何语句的执行。这通常对用户是不可见的,因为在当作一个隐式事务块执行时,这些语句不管怎样都会全部被回滚。不过,在尝试于一个多语句Query中执行多个事务时,这种现象可能是可见的。例如,如果一个拼写错误把我们之前的示例变成 + 另一种要注意的行为是,在执行任何语句之前,会先对整个查询字符串进行词法和语法分析。因此后面的语句中的简单错误(例如拼写错误的关键词)可能会阻止任何语句的执行。这通常对用户是不可见的,因为在当作一个隐式事务块执行时,这些语句不管怎样都会全部被回滚。不过,在尝试于一个多语句Query中执行多个事务时,这种现象可能是可见的。例如,如果一个拼写错误把我们之前的示例变成 BEGIN; INSERT INTO mytable VALUES(1); @@ -710,11 +706,11 @@ SELCT 1/0; - 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是执行不会导致后端发送 ReadyForQuery 或 RowDescription。 + 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是 Execute 不会导致后端发送 ReadyForQuery 或 RowDescription。 - 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息之一结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 + 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息中的恰好一条结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 @@ -729,7 +725,7 @@ SELCT 1/0; - 除了这些基本的、必须的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 + 除了这些基本的、必需的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 @@ -765,38 +761,32 @@ SELCT 1/0; - 流水线处理 + 管道化 - 流水线处理 + 管道化 协议规范 - 使用扩展查询协议允许流水线处理,这意味着发送一系列查询而无需等待先前的查询完成。 - 这减少了完成一系列操作所需的网络往返次数。然而,用户必须仔细考虑所需的行为,如果其中一步失败, - 因为后续查询已经在传输到服务器的过程中。 - + 扩展查询协议允许管道化,即连续发送一系列查询,而不等待先前查询完成。这减少了完成一组操作所需的网络往返次数。不过,用户必须仔细考虑其中某个步骤失败时所需的行为,因为后续查询已经在发往服务器的途中。 + - 处理这个问题的一种方法是将整个查询系列作为一个事务处理,即将其包装在BEGIN... - COMMIT中。然而,如果希望其中一些命令独立于其他命令提交,这并没有帮助。 - + 处理这个问题的一种方式是让整组查询成为单个事务,即用BEGIN ... COMMIT包围它们。不过,如果希望其中某些命令独立于其他命令提交,这种方式就无法满足要求。 + - 扩展查询协议提供了另一种管理这个问题的方式,即在依赖的步骤之间省略发送同步消息。 - 由于在错误后,后端会跳过命令消息直到找到同步消息,这允许在管道中的后续命令在前面的命令失败时自动跳过,而无需客户端明确地使用BEGINCOMMIT来管理。 - 管道中可以通过同步消息分隔独立可提交的段。 - + 扩展查询协议提供了另一种处理方式,即省略相互依赖的步骤之间的 Sync 消息。发生错误后,后端会跳过命令消息,直到遇到 Sync,因此当前面的命令失败时,管道中的后续命令便会自动跳过,而不必由客户端用BEGINCOMMIT显式管理。管道中可独立提交的各段可以用 Sync 消息分隔。 + 如果客户端没有发出显式 BEGIN,则会启动一个隐式事务块。每个 Sync 通常会在前序步骤成功时导致隐式 COMMIT,失败时导致隐式 ROLLBACK。服务器只有在第一个命令结束且尚未收到 Sync 时,才能识别这种隐式事务块。有一些 DDL 命令(例如 CREATE DATABASE)不能在事务块内执行;若这类命令在管道中执行,除非它是某个 Sync 之后的第一条命令,否则会失败。此外,它成功后会强制立即提交以保持数据库一致性。因此,紧随这些命令之后的 Sync 除了返回 ReadyForQuery 外不会产生额外效果。 - 当使用这种方法时,必须通过计算ReadyForQuery消息的数量并等待达到发送的Syncs数量来确定管道的完成。 - 计算命令完成响应是不可靠的,因为其中一些命令可能会被跳过,因此不会产生完成消息。 - + 使用这种方式时,必须统计 ReadyForQuery 消息的数量,并等待该数量达到已发送的 Sync 消息数量,才能确定管道已完成。统计命令完成响应并不可靠,因为某些命令可能被跳过,因而不会产生完成消息。 + @@ -804,8 +794,8 @@ SELCT 1/0; 函数调用 - 函数调用子协议允许客户端请求一个对存在于数据库pg_proc系统表中的任意函数的直接调用。客户端必须在该函数上有执行的权限。 - + 函数调用子协议允许客户端请求直接调用数据库pg_proc系统目录中的任意函数。客户端必须具有该函数的执行权限。 + @@ -815,8 +805,8 @@ SELCT 1/0; - 一个函数调用周期是由前端向后端发送一条FunctionCall消息初始化的。然后后端根据函数调用的结果发送一条或者更多响应消息,并且最后是一条ReadyForQuery响应消息。ReadyForQuery通知前端它可以安全地发送一个新的查询或者函数调用了。 - + 函数调用周期由前端向后端发送一条 FunctionCall 消息来启动。后端随后根据函数调用的结果发送一条或多条响应消息,最后发送一条 ReadyForQuery 响应消息。ReadyForQuery 告知前端,可以安全地发送新的查询或函数调用。 + 来自后端的可能的响应消息是: @@ -835,7 +825,7 @@ SELCT 1/0; FunctionCallResponse - 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者集合类型的结果)。 + 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者结果集合)。 @@ -870,7 +860,7 @@ SELCT 1/0; - 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(表示成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 + 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(允许成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 @@ -878,11 +868,11 @@ SELCT 1/0; - 在拷贝入模式下,后端将忽略所收到的Flush和Sync消息。收到任何其他非拷贝消息类型都会造成一个错误,它将导致上面所描述的拷贝入状态中断(Flush和Sync的例外是为了方便客户端库,它们总是在一个Execute消息之后发送Flush和Sync,而不检查被执行的命令是否为一个COPY FROM STDIN)。 - + 后端会忽略在拷贝入模式期间收到的 Flush 和 Sync 消息。收到任何其他非拷贝类型的消息都会构成错误,并按上述方式中止拷贝入状态。(Flush 和 Sync 的例外是为了方便那些总是在 Execute 消息之后发送 Flush 或 Sync、而不检查待执行命令是否为COPY FROM STDIN的客户端库。) + - 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句的时候初始化的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能退出传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 + 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句时启动的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能中止传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 @@ -890,16 +880,16 @@ SELCT 1/0; - 在CopyData消息中间可能会散布有NoticeResponse和ParameterStatus消息。前端必须处理这些情况,并且应该也为异步消息类型(参见)准备好。否则任何除CopyData或CopyDone之外的消息类型都会被认为是要中止拷贝出模式。 - + NoticeResponse 和 ParameterStatus 消息可能穿插在 CopyData 消息之间;前端必须处理这些情况,并应准备好处理其他异步消息类型(参见)。除此之外,可以将任何除 CopyData 或 CopyDone 以外的消息类型视为拷贝出模式的终止标志。 + - 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许数据以高速批量方式在客户端与服务器之间双向传输。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见。 + 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许高速批量地向服务器发送数据以及从服务器接收数据。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见 - CopyInResponse、CopyOutResponse和CopyBothResponse消息包括域和格式代码,域告诉前端每行的列数,而格式代码则用于具体每个列(就目前的实现而言,一个给定COPY操作中的所有列都将使用同样的格式,但是消息设计并不做这个假设)。 - + CopyInResponse、CopyOutResponse 和 CopyBothResponse 消息包含一些字段,用于告知前端每行的列数以及每列所使用的格式代码。(在当前实现中,同一次COPY操作的所有列都使用相同格式,但消息设计并不作此假设。) + @@ -943,8 +933,8 @@ SELCT 1/0; - 如果前端发出一个LISTEN命令, 那么无论何时在为同一个通道名NOTIFY时,后端将发送一个NotificationResponse消息(不要和NoticeResponse搞混!)。 - + 如果前端发出LISTEN命令,那么每当针对同一通道名执行NOTIFY命令时,后端都会发送一条 NotificationResponse 消息(不要与 NoticeResponse 混淆)。 + @@ -963,11 +953,11 @@ SELCT 1/0; - 要发出一条取消请求,前端打开一个与服务器的新连接并且发送一条CancelRequest消息, 而不是通常在新连接中经常发送的StartupMessage消息。服务器将处理这个请求然后关闭连接。 出于安全原因,对取消请求消息不做直接的响应。 - + 要发出取消请求,前端会新建到服务器的连接,并发送 CancelRequest 消息,而不是新连接通常发送的 StartupMessage 消息。服务器处理该请求后便会关闭连接。出于安全原因,服务器不会直接回复取消请求消息。 + - 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的关键数据(PID和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则退出当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 + 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的密钥数据(PID 和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则中止当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 @@ -975,7 +965,7 @@ SELCT 1/0; - 这么做是对安全性和有效性通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 + 这么做是对安全性和效率通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 @@ -996,11 +986,11 @@ SELCT 1/0; - 其他终止场景来自各种故障,例如任一端发生内核转储、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 + 其他终止场景来自各种故障,例如任一端发生 core dump、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 - 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果很可能在得知断开之前被提交。 + 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果可能在发现连接断开之前被提交。 @@ -1014,32 +1004,32 @@ SELCT 1/0; 要发起一条使用SSL加密的连接,前端首先发送 SSLRequest 消息,而不是 StartupMessage。随后服务器会响应一个包含SN的单字节,分别表示它愿意或不愿意执行SSL加密。如果前端对该响应不满意,此时可以关闭连接。若要在收到S后继续,就先与服务器完成SSL启动握手(这里不做描述,它属于SSL规范的一部分)。如果成功,再继续发送通常的 StartupMessage。在这种情况下,StartupMessage 以及后续所有数据都会被SSL加密。若要在收到N后继续,则发送通常的 StartupMessage,并在不使用加密的情况下继续。 - (另外,可以在 N 响应之后发出 GSSENCRequest 消息,尝试使用 GSSAPI 加密代替 SSL。) + (另外,可以在 N 响应之后发出 GSSENCRequest 消息,尝试使用 GSSAPI 加密代替 SSL。) - 前端也应准备处理服务器对 SSLRequest 返回的 ErrorMessage。前端不应将该错误直接展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 SSL 的情况下继续。 + 前端也应准备处理服务器对 SSLRequest 返回的 ErrorMessage。前端不应将该错误展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 SSL 的情况下继续。 - 当可以执行 SSL 加密时,服务器预计仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给他们的 SSL 库,要么在发现他们已经读取到额外的字节时将其视为协议违规。 + 当可以执行 SSL 加密时,服务器应仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给所用的 SSL 库,要么在发现已经读取到额外的字节时将其视为协议违规。 - 同样,服务器也期望客户端在收到服务器对 SSLRequest 的单字节响应之后,再开始SSL协商。如果客户端不等服务器响应到达就立即开始SSL协商,可以减少一次网络往返时延;但代价是无法处理服务器对SSL请求返回否定响应的情况。在这种情况下,服务器通常会直接断开连接,而不会继续回退到 GSSAPI、未加密连接或协议错误流程。 + 同样,服务器也期望客户端在收到服务器对SSL请求的单字节响应之后,再开始SSL协商。如果客户端不等服务器响应到达就立即开始SSL协商,可以减少一次网络往返时延;但代价是无法处理服务器对SSL请求返回否定响应的情况。在这种情况下,服务器会直接断开连接,而不会继续使用 GSSAPI 或未加密连接,也不会返回协议错误。 - 初始 SSLRequest 也可以用于那些正在建立、目的是发送 CancelRequest 消息的连接。 - + 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 SSLRequest。 + - 还支持第二种发起SSL加密的方式:客户端可以在不发送任何 SSLRequest 包的情况下,直接开始SSL协商。SSL连接建立后,服务器会在加密通道上继续等待普通的启动请求包并继续协商。在这种情况下,任何其他的加密请求都会被拒绝。这种方法不适合通用工具,因为它既不能协商出最佳的连接加密方式,也不能处理未加密连接;但在客户端和服务器都由同一方控制的环境中,它很有用,因为它可以减少一次往返时延,并允许使用依赖标准SSL连接的网络工具。使用这种风格的SSL连接时,客户端必须使用由 RFC 7301 定义的 ALPN 扩展,以防范协议混淆攻击。PostgreSQL 协议对应的 ALPN 标识是 postgresql,见 IANA TLS ALPN Protocol IDs 注册表。 + 还支持第二种发起SSL加密的方式:服务器能识别未发送任何 SSLRequest 包就立即开始SSL协商的连接。SSL连接建立后,服务器会在加密通道上继续等待普通的启动请求包并继续协商。在这种情况下,任何其他的加密请求都会被拒绝。这种方法不是通用工具的首选,因为它既不能协商出最佳的连接加密方式,也不能处理未加密连接;但在客户端和服务器都由同一方控制的环境中,它很有用,因为它可以减少一次往返时延,并允许使用依赖标准SSL连接的网络工具。使用这种风格的SSL连接时,客户端必须使用由 RFC 7301 定义的 ALPN 扩展,以防范协议混淆攻击。PostgreSQL 协议对应的 ALPN 标识是 postgresql,见 IANA TLS ALPN Protocol IDs 注册表。 - 虽然协议本身并不提供让服务器强制启用SSL加密的方法,但管理员可以把服务器配置为拒绝未加密会话,把它作为认证检查的一个副作用。 - + 虽然协议本身没有提供让服务器强制使用SSL加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + @@ -1050,37 +1040,27 @@ SELCT 1/0; 如果PostgreSQL构建时启用了GSSAPI支持,就可以使用GSSAPI对前端/后端通信进行加密。这为攻击者可能截获会话流量的环境提供了通信安全性。有关使用GSSAPI加密PostgreSQL会话的详细信息,请参阅。 - - 要启动一个GSSAPI加密连接,前端最初发送一个GSSENCRequest消息,而不是一个StartupMessage。 - 服务器随后会响应一个包含GN的单个字节,分别表示愿意或不愿意执行GSSAPI加密。 - 如果前端对响应不满意,可能会在此时关闭连接。 - 要在G之后继续,使用GSSAPI C绑定,如在RFC 2744 - 中讨论的,或等效的,通过在循环中调用gss_init_sec_context()来执行GSSAPI初始化, - 并将结果发送给服务器,从一个空输入开始,然后对每个来自服务器的结果进行处理,直到不再返回输出为止。 - 在将gss_init_sec_context()的结果发送给服务器时,在消息前加上以网络字节顺序表示的四字节整数的长度。 - 要在N之后继续,发送通常的StartupMessage,并在没有加密的情况下继续进行。 - (或者,可以在N响应后发出一个SSLRequest消息,尝试使用SSL加密代替GSSAPI。) - + 要建立 GSSAPI 加密连接,前端首先发送 GSSENCRequest 消息,而不是 StartupMessage。服务器随后以单个字节响应,内容为 GN,分别表示愿意或不愿意使用 GSSAPI 加密。如果前端对响应不满意,可以在此时关闭连接。收到 G 后要继续,应使用 RFC 2744 中介绍的 GSSAPI C 绑定或等效接口,在循环中调用 gss_init_sec_context() 来执行 GSSAPI 初始化,并将结果发送给服务器:先使用空输入,再依次使用服务器返回的每个结果,直到该调用不再产生输出。将 gss_init_sec_context() 的结果发送给服务器时,应在前面加上消息长度,以网络字节序的四字节整数表示。收到 N 后要继续,则发送通常的 StartupMessage,以不加密的方式继续。(也允许在收到 N 响应后发送 SSLRequest 消息,尝试使用 SSL 加密代替 GSSAPI。) - 前端也应准备处理服务器对 GSSENCRequest 返回的 ErrorMessage。前端不应将该错误直接展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 GSSAPI 加密的情况下继续。 + 前端也应准备处理服务器对 GSSENCRequest 返回的 ErrorMessage。前端不应将该错误展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 GSSAPI 加密的情况下继续。 - 当GSSAPI加密可用时,服务器预计只发送单个G字节,然后等待前端启动GSSAPI握手。此时如果还有其他可读字节,很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应编写代码,要么从套接字中恰好读取一个字节后再把套接字交给其 GSSAPI 库,要么在发现自己已经读到额外字节时将其视为协议违规。 + 当GSSAPI加密可用时,服务器应只发送单个G字节,然后等待前端启动GSSAPI握手。此时如果还有其他可读字节,很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应编写代码,要么从套接字中恰好读取一个字节后再把套接字交给其 GSSAPI 库,要么在发现自己已经读到额外字节时将其视为协议违规。 - 初始 GSSENCRequest 也可用于那些正在建立、目的是发送 CancelRequest 消息的连接。 - + 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 GSSENCRequest。 + 一旦成功建立GSSAPI加密连接,就应使用gss_wrap()加密通常的 StartupMessage 以及后续所有数据,并在实际加密负载前附上gss_wrap()结果长度,该长度以网络字节序的四字节整数表示。请注意,服务器只接受来自客户端、长度小于 16kB 的加密数据包。客户端应使用gss_wrap_size_limit()确定符合该限制的未加密消息大小,较大的消息则应拆分为多次gss_wrap()调用。典型分段是 8kB 的未加密数据,对应得到略大于 8kB 但明显小于 16kB 的加密数据包。通常可以认为,服务器不会向客户端发送大于 16kB 的加密数据包。 - 虽然协议本身并不为服务器提供强制启用GSSAPI加密的方法,但管理员可以把服务器配置为拒绝未加密会话,把它作为认证检查的一个副作用。 - + 虽然协议本身没有提供让服务器强制使用GSSAPI加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + @@ -1106,25 +1086,22 @@ SELCT 1/0; - 客户端从列表中选择一个支持的机制,并向服务器发送一个SASLInitialResponse消息。 - 该消息包括所选机制的名称,以及如果所选机制使用的话,还包括一个可选的初始客户端响应。 - + 客户端从列表中选择一种受支持的机制,并向服务器发送 SASLInitialResponse 消息。消息包含所选机制的名称;如果该机制使用初始客户端响应,消息还可以包含这一可选响应。 + - 一个或多个服务器挑战和客户端响应消息将随后而来。每个服务器挑战都是在一个 - AuthenticationSASLContinue 消息中发送的,随后是客户端在一个 SASLResponse - 消息中的响应。这些消息的具体内容是特定于机制的。 - + 随后会进行一轮或多轮服务器挑战和客户端响应。每次服务器挑战都通过 AuthenticationSASLContinue 消息发送,随后客户端通过 SASLResponse 消息响应。消息的具体内容取决于所用机制。 + - 最后,当认证交换成功完成时,服务器会发送可选的 AuthenticationSASLFinal 消息,随后立即发送 AuthenticationOk。AuthenticationSASLFinal 包含机制特定的附加数据;若该机制不需要完成时附加数据,则不会发送 AuthenticationSASLFinal。 - + 最后,认证交换成功完成时,服务器会发送可选的 AuthenticationSASLFinal 消息,紧接着发送 AuthenticationOk 消息。AuthenticationSASLFinal 包含从服务器发给客户端的附加数据,其具体内容取决于所选认证机制。如果该认证机制不使用在完成时发送的附加数据,则不会发送 AuthenticationSASLFinal 消息。 + @@ -1150,31 +1127,22 @@ SELCT 1/0; - SCRAM规范规定密码也必须是UTF-8编码,并且使用SASLprep算法处理。 - 然而,PostgreSQL不要求密码必须使用UTF-8编码。 - 当用户设置密码时,无论实际使用的编码是什么,都会像使用UTF-8一样使用SASLprep进行处理。 - 但是,如果密码不是合法的UTF-8字节序列,或者包含SASLprep算法禁止的UTF-8字节序列, - 则会使用原始密码而不进行SASLprep处理,而不是抛出错误。这样可以在密码为UTF-8时对其进行规范化, - 但仍允许使用非UTF-8密码,并且不需要系统知道密码使用的编码方式。 - + SCRAM 规范规定密码也必须采用 UTF-8 编码,并通过SASLprep算法处理。不过,PostgreSQL并不要求密码使用 UTF-8。设置用户密码时,无论实际采用何种编码,都会将其视作 UTF-8 并用 SASLprep 处理。但是,如果密码不是合法的 UTF-8 字节序列,或者包含 SASLprep 算法禁止的 UTF-8 字节序列,就会直接使用未经 SASLprep 处理的原始密码,而不抛出错误。这样既能对 UTF-8 密码进行规范化,又允许使用非 UTF-8 密码,而且不要求系统知道密码采用何种编码。 + - Channel binding在支持SSL的PostgreSQL构建中受支持。带有通道绑定的SCRAM的SASL机制名称是 + 通道绑定在支持SSL的PostgreSQL构建中受支持。带有通道绑定的SCRAM的SASL机制名称是 SCRAM-SHA-256-PLUS。PostgreSQL使用的通道绑定类型是 tls-server-end-point - 在没有通道绑定的SCRAM中,服务器选择一个随机数, - 传输给客户端,与用户提供的密码在传输的密码哈希中混合。虽然这可以 - 防止密码哈希在后续会话中被成功重新传输,但无法阻止真实服务器和客 - 户端之间的虚假服务器通过服务器的随机值并成功进行认证。 - + 在不带通道绑定的SCRAM中,服务器会选择一个随机数并发送给客户端,将它与用户提供的密码混合,形成所传输的密码 hash。虽然这样可以防止在后续会话中成功重放该密码 hash,但无法阻止位于真实服务器与客户端之间的伪造服务器转发服务器的随机值并成功通过认证。 + - SCRAM与通道绑定一起防止这种中间人攻击,通过将服务器证书的签名混合到传输的密码哈希中。 - 虽然伪造服务器可以重新传输真实服务器的证书,但它无法访问与该证书匹配的私钥,因此无法证明自己是所有者,导致SSL连接失败。 - + 带通道绑定的SCRAM会将服务器证书的签名混入所传输的密码 hash,从而防止此类中间人攻击。虽然伪造服务器可以转发真实服务器的证书,但它无法取得与证书匹配的私钥,因此无法证明自己是证书所有者,最终导致 SSL 连接失败。 + @@ -1227,63 +1195,75 @@ SELCT 1/0; OAUTHBEARER 认证 - OAUTHBEARER 是一种基于令牌的联合认证机制,详见 - RFC 7628。 - + OAUTHBEARER 是一种基于令牌的联合认证机制。其详细说明见 RFC 7628。 + - 典型交互取决于客户端是否已经为当前用户缓存 bearer token。若没有,通常会经历两次连接:第一次“发现连接”用于从服务器获取 OAuth 元数据,第二次连接在客户端拿到 token 后再发送 token。(libpq 当前内置流程尚未实现缓存,因此使用两连接流程。) - + 典型交互取决于客户端是否已为当前用户缓存 Bearer 令牌。如果没有,交互将通过两次连接完成:第一次“发现”连接从服务器获取 OAuth 元数据,第二次连接在客户端取得令牌后发送该令牌。(libpq 的内置流程目前没有实现缓存方法,因此使用两次连接的交互方式。) + - 该机制与 SCRAM 一样由客户端发起。客户端初始响应由 SCRAM 使用的标准 GS2 头部加上一组 key=value 对组成。当前服务器仅支持 auth 键(即 bearer token)。OAUTHBEARER 还定义了三个可选组成(GS2 头部中的 authzid,以及 host/port),当前服务器会忽略它们。 - + 该机制与 SCRAM 一样由客户端发起。客户端初始响应由 SCRAM 使用的标准“GS2”头部以及随后的一组 key=value 对组成。服务器目前唯一支持的键是 auth,其中包含 Bearer 令牌。OAUTHBEARER 还规定了客户端初始响应的三个可选部分:GS2 头部的 authzid,以及 hostport 键;服务器目前会忽略它们。 + - OAUTHBEARER 不支持通道绑定,因此不存在 “OAUTHBEARER-PLUS”。该机制在成功认证时不使用额外服务器数据,所以不会使用 AuthenticationSASLFinal 消息。 - + OAUTHBEARER 不支持通道绑定,也不存在“OAUTHBEARER-PLUS”机制。该机制在成功认证期间不使用服务器数据,因此交互中不使用 AuthenticationSASLFinal 消息。 + 示例 - 第一次交互时,服务器发送 AuthenticationSASL,并在机制列表中声明 OAUTHBEARER。 - + 第一次交互期间,服务器发送 AuthenticationSASL 消息,并声明支持 OAUTHBEARER 机制。 + + - 客户端发送 SASLInitialResponse 并选择 OAUTHBEARER。若尚无可用 token,则 auth 为空,表示这是发现连接。 - + 客户端发送 SASLInitialResponse 消息作为响应,在其中指定 OAUTHBEARER 机制。假定客户端尚未持有当前用户的有效 Bearer 令牌,则 auth 字段为空,表示这是发现连接。 + + - 服务器发送 AuthenticationSASLContinue,包含错误 status、well-known URI 以及客户端应使用的 scopes。 - + 服务器发送 AuthenticationSASLContinue 消息,其中包含错误 status、well-known URI,以及客户端执行 OAuth 流程时应使用的授权范围。 + + - 客户端发送 SASLResponse,内容为空集合(单个 0x01 字节),结束发现阶段的客户端半程。 - + 客户端发送包含空集合(单个 0x01 字节)的 SASLResponse 消息,以结束发现交互中由客户端完成的部分。 + + - 服务器发送 ErrorMessage,使第一次交互失败。随后客户端按配置和服务器提供的元数据执行 OAuth 流程以获取 token。(具体获取方式由客户端实现决定,OAUTHBEARER 不强制规定。) - + 服务器发送 ErrorMessage,使第一次交互失败。 + + + 此时,客户端会执行多种可用 OAuth 流程中的一种,以获取 Bearer 令牌;所使用的元数据包括客户端已配置的元数据,以及服务器提供的元数据。(此处的描述有意保持宽泛;OAUTHBEARER 不指定也不强制要求采用任何特定的令牌获取方法。) + + + 取得令牌后,客户端会重新连接服务器,进行最后一次交互: + + - 客户端拿到 token 后重新连接;服务器再次发送 AuthenticationSASL,并声明 OAUTHBEARER。 - + 服务器再次发送 AuthenticationSASL 消息,并声明支持 OAUTHBEARER 机制。 + + - 客户端再次发送 SASLInitialResponse,这次在 auth 中携带 bearer token。 - + 客户端发送 SASLInitialResponse 消息作为响应,但这次消息中的 auth 字段包含客户端流程取得的 Bearer 令牌。 + + - 服务器按令牌提供方规则校验 token。若客户端被授权连接,服务器发送 AuthenticationOk,认证完成。 - + 服务器按照令牌提供者的说明验证令牌。如果客户端获准连接,服务器便发送 AuthenticationOk 消息,结束 SASL 交互。 + @@ -1310,16 +1290,15 @@ SELCT 1/0; - 为了测试复制命令,可以通过psql或任何其他使用连接字符串且包含replication选项的libpq工具建立复制连接, - 例如: + 为了测试复制命令,可以通过 psql 或其他使用 libpq 的工具建立复制连接,连接字符串中应包含 replication 选项,例如: psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 然而,更常用的是使用(用于物理复制)或(用于逻辑复制)。 - +不过,通常更有用的做法是使用 (用于物理复制)或 (用于逻辑复制)。 + - 复制命令在服务器日志中记录,当启用时。 + 启用 后,复制命令会记录到服务器日志中。 @@ -1329,7 +1308,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" IDENTIFY_SYSTEM - 识别系统 + IDENTIFY_SYSTEM @@ -1365,9 +1344,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" xlogpos (text) - - 当前 WAL 刷新位置。用于获得预写式日志中的一个已知位置,以便从该处开始流式传输。 - + 当前 WAL 刷盘位置。可用于获取预写式日志中一个已知的位置,以便从该处开始流式传输。 @@ -1419,10 +1396,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 请求服务器发送时间线历史文件以获取时间线tli。 - 服务器回复一行结果集,包含两个字段。虽然这些字段被标记为text, - 但它们实际上返回原始字节,没有编码转换: - + 请求服务器发送时间线 tli 的历史文件。服务器返回一个包含两个字段的单行结果集。虽然这些字段标记为 text,但实际返回的是原始字节,不进行编码转换: + @@ -1503,12 +1478,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果为 true,则该逻辑复制槽支持两阶段提交的解码。使用此选项后,与两阶段提交相关的命令,如 - PREPARE TRANSACTIONCOMMIT PREPARED - 和ROLLBACK PREPARED将被解码和传输。 - 事务将在PREPARE TRANSACTION时解码和传输。 - 默认值为false。 - + 如果为 true,则该逻辑复制槽支持对两阶段提交进行解码。使用此选项后,PREPARE TRANSACTIONCOMMIT PREPAREDROLLBACK PREPARED 等两阶段提交命令会被解码并传输。事务会在 PREPARE TRANSACTION 时解码并传输。默认值为 false。 + @@ -1517,10 +1488,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果为 true,则该物理复制槽会立即保留WAL。 - 否则,WAL仅在从流复制客户端连接时保留。 - 默认值为false。 - + 如果为 true,则该物理复制槽会立即保留 WAL。否则,只有在流复制客户端连接时才会保留 WAL。默认值为 false。 + @@ -1604,8 +1573,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 修改复制槽定义。参见 。当前仅支持逻辑复制槽。 - + 修改复制槽的定义。有关复制槽的更多信息,参见 。此命令目前仅支持逻辑复制槽。 + slot_name @@ -1622,8 +1591,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" TWO_PHASE [ boolean ] - 若为 true,则该逻辑复制槽支持两阶段提交解码。与两阶段提交相关的命令(如 PREPARE TRANSACTIONCOMMIT PREPAREDROLLBACK PREPARED)会被解码并发送;事务在 PREPARE TRANSACTION 时解码并发送。 - + 如果为 true,则该逻辑复制槽支持对两阶段提交进行解码。使用此选项后,PREPARE TRANSACTIONCOMMIT PREPAREDROLLBACK PREPARED 等两阶段提交命令会被解码并传输。事务会在 PREPARE TRANSACTION 时解码并传输。 + @@ -1632,8 +1601,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" FAILOVER [ boolean ] - 若为 true,则该复制槽会同步到备库,从而在故障切换后恢复逻辑复制。 - + 如果为 true,则允许该复制槽同步到备库,以便在故障切换后恢复逻辑复制。 + @@ -1644,14 +1613,13 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" READ_REPLICATION_SLOT slot_name - 读取复制槽 + READ_REPLICATION_SLOT - 读取与复制槽相关的一些信息。如果复制槽不存在,则返回一个包含NULL值的元组。 - 当前仅支持物理复制槽的此命令。 - + 读取与复制槽关联的一些信息。如果复制槽不存在,则返回包含 NULL 值的元组。此命令目前仅支持物理复制槽。 + 在响应此命令时,服务器将返回一个包含以下字段的单行结果集: @@ -1678,8 +1646,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" restart_tliint8 - 与restart_lsn相关联的时间线ID,遵循当前时间线历史。 - + 根据当前时间线的历史,与 restart_lsn 对应的时间线 ID。 + @@ -1691,35 +1659,29 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" START_REPLICATION [ SLOT slot_name ] [ PHYSICAL ] XXX/XXX [ TIMELINE tli ] - 开始复制 + START_REPLICATION - 指示服务器开始流式传输WAL,从WAL位置XXX/XXX开始。 - 如果指定了TIMELINE选项,则流式传输将从时间线tli开始; - 否则,将选择服务器当前的时间线。如果请求的WAL部分已经被回收,服务器可能会回复错误。 - 成功时,服务器将用CopyBothResponse消息回复,然后开始向前端流式传输WAL。 - + 指示服务器从 WAL 位置 XXX/XXX 开始流式传输 WAL。如果指定了 TIMELINE 选项,则从时间线 tli 开始传输;否则选择服务器当前的时间线。服务器可以返回错误,例如请求的 WAL 部分已被回收时。成功时,服务器返回 CopyBothResponse 消息,然后开始向前端流式传输 WAL。 + - 如果通过slot_name提供了复制槽名称, - 那么在复制进行期间会更新该复制槽,以便服务器知道哪些 WAL 段, - 以及在启用了 hot_standby_feedback 时,哪些事务 - 仍然被备库所需要。 - + 如果通过 slot_name 提供了复制槽名称,该复制槽会随着复制的进行而更新,使服务器知道备库仍需要哪些 WAL 段,以及在启用 hot_standby_feedback 时仍需要哪些事务。 + - 如果客户端请求的 timeline 不是最新的,但属于服务器历史的一部分,服务器会从请求的起点开始流式传输该 timeline 上的全部 WAL,直到服务器切换到另一个 timeline 的位置为止。如果客户端请求的位置正好是旧 timeline 的末尾,服务器将完全跳过 COPY 模式。 - + 如果客户端请求的时间线不是最新时间线,但属于服务器的历史,服务器会从请求的起点开始,流式传输该时间线上的所有 WAL,直到服务器切换到另一条时间线的位置。如果客户端请求的流式传输起点恰好位于旧时间线的末尾,服务器会完全跳过 COPY 模式。 + 在非最新时间线上流式传输完全部 WAL 后,服务器会通过退出 COPY 模式来结束流式传输。当客户端也通过退出 COPY 模式来确认时,服务器会发送一个包含一行两列的结果集,指示该服务器历史中的下一条时间线。第一列是下一条时间线的 ID(类型为 int8),第二列是发生切换的 WAL 位置(类型为 text)。通常,切换位置就是所流式传输 WAL 的末尾,但也存在一些边界情况,服务器可能会先发送一些自己在提升前尚未重放的旧时间线 WAL。最后,服务器会发送两个 CommandComplete 消息(一个结束 CopyData,另一个结束 START_REPLICATION 本身),然后准备接受新的命令。 - WAL 数据会作为一系列 CopyData 消息发送;详见 。(这使其他信息可与之交错发送;特别是服务器在开始流式传输后若遇到失败,仍可发送 ErrorResponse。)从服务器到客户端的每个 CopyData 消息负载都属于以下格式之一: - + WAL 数据通过一系列 CopyData 消息发送,详见 。(这样可以混合发送其他信息;尤其是服务器在开始流式传输后遇到故障时,可以发送 ErrorResponse 消息。)服务器发给客户端的每条 CopyData 消息,其有效载荷都包含一条具有下列格式之一的消息: + @@ -1732,9 +1694,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('w') - - 将消息标识为WAL数据。 - + 将该消息标识为 WAL 数据。 @@ -1743,9 +1703,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 该消息中 WAL 数据的起始点。 - + 本消息中 WAL 数据的起始位置。 @@ -1754,9 +1712,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 服务器上当前的WAL结束位置。 - + 服务器上当前的 WAL 末尾位置。 @@ -1765,9 +1721,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 传输时服务器的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时服务器的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1776,15 +1730,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byten - - WAL数据流的一个部分。 - + WAL 数据流的一个片段。 - - 单个 WAL 记录绝不会拆分为两个 WALData 消息。 - 当 WAL 记录跨越 WAL 页面边界,并因此已使用连续记录进行拆分时,它可以在页面边界处进行拆分。 - 换句话说,第一个主 WAL 记录及其连续记录可以在不同的 WALData 消息中发送。 - + 单条 WAL 记录绝不会被拆分到两条 WALData 消息中。当 WAL 记录跨越 WAL 页边界,因而已经通过续接记录拆分时,可以在页边界处分开发送。换句话说,最初的主 WAL 记录及其续接记录可以在不同的 WALData 消息中发送。 @@ -1793,7 +1741,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 主库 keepalive 消息 (B) + 主库保活消息 (B) @@ -1801,9 +1749,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('k') - - 将该消息标识为发送方 keepalive。 - + 将该消息标识为发送端保活消息。 @@ -1812,9 +1758,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 服务器上当前的WAL结束位置。 - + 服务器上当前的 WAL 末尾位置。 @@ -1823,9 +1767,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 传输时服务器的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时服务器的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1834,9 +1776,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1 - - 1 表示客户端应尽快回复此消息,以避免超时断开连接。否则为0。 - + 1 表示客户端应尽快回复此消息,以避免超时断开连接;否则为 0。 @@ -1876,8 +1816,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 服务器上当前处于提交阶段的最老事务 ID,以及其 纪元。高 32 位是 纪元,低 32 位是事务 ID。如果服务器上没有活跃事务,则该数值为将要分配的下一个事务 ID。 - + 服务器上当前处于提交阶段的最老事务 ID 及其纪元。高 32 位为纪元,低 32 位为事务 ID。如果服务器上没有活跃事务,则该值为下一个待分配的事务 ID。 + @@ -1887,8 +1827,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 服务器上将要分配的下一个事务 ID,以及其 纪元。高 32 位是 纪元,低 32 位是事务 ID。 - + 服务器上下一个待分配的事务 ID 及其纪元。高 32 位为纪元,低 32 位为事务 ID。 + @@ -1897,9 +1837,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 传输时服务器的系统时钟,以 2000-01-01 午夜以来的微秒计算。 - + 发送消息时服务器的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1907,9 +1845,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - - 接收进程可以随时使用以下某种消息格式向发送方回传响应(同样放在 CopyData 消息的负载中): - + 接收进程可以随时使用以下消息格式之一回复发送端(同样放在 CopyData 消息的有效载荷中): @@ -1922,9 +1858,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('r') - - 将该消息标识为接收方状态更新。 - + 将该消息标识为接收端状态更新。 @@ -1933,9 +1867,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已接收并写入磁盘的 WAL 字节位置 + 1。 - + 备库已接收并写入磁盘的最后一个 WAL 字节的位置加 1。 @@ -1944,9 +1876,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已刷写到磁盘的 WAL 字节位置 + 1。 - + 备库已刷盘的最后一个 WAL 字节的位置加 1。 @@ -1955,9 +1885,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已应用的 WAL 字节位置 + 1。 - + 备库已应用的最后一个 WAL 字节的位置加 1。 @@ -1966,9 +1894,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 客户端在传输时的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时客户端的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1977,9 +1903,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1 - - 如果为 1,则客户端请求服务器立即回复此消息。这可用于 ping 服务器,以测试连接是否仍然健康。 - + 如果为 1,表示客户端请求服务器立即回复此消息。可用它向服务器发送探测请求,以测试连接是否仍然正常。 @@ -2007,9 +1931,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 客户端在传输时的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时客户端的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -2030,8 +1952,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 备库上全局 xmin xid 的纪元。 - + 备库全局 xmin 事务 ID 的纪元。 + @@ -2041,8 +1963,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 备库上任何复制槽中的最低 catalog_xmin。如果备库上不存在 catalog_xmin,或已禁用热备反馈,则设为 0。 - + 备库上所有复制槽中最小的 catalog_xmin。如果备库上不存在 catalog_xmin,或者正在禁用热备反馈,则设为 0。 + @@ -2052,8 +1974,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 备库上 catalog_xmin xid 的纪元。 - + 备库 catalog_xmin 事务 ID 的纪元。 + @@ -2076,9 +1998,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 客户端在传输时的系统时钟,以 2000-01-01 午夜以来的微秒数表示。 - + 发送消息时客户端的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -2164,7 +2084,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" DROP_REPLICATION_SLOT slot_name WAIT - 删除复制槽 + DROP_REPLICATION_SLOT @@ -2227,9 +2147,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 设置备份的标签。如果未指定,则将使用base backup作为备份标签。 - 标签的引号使用规则与标准SQL字符串相同。 - + 设置备份标签。如果未指定,则使用 base backup 作为备份标签。标签的引号规则与标准 SQL 字符串相同。 + @@ -2330,16 +2249,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - level关键字设置压缩级别。 - 对于gzip,压缩级别应该是一个介于19之间的整数 - (默认为Z_DEFAULT_COMPRESSION-1), - 对于lz4,压缩级别应该是介于1和12之间的整数 - (默认为0用于快速压缩模式), - 对于zstd,压缩级别应该是介于ZSTD_minCLevel() - (通常为-131072)和ZSTD_maxCLevel() - (通常为22)之间, - (默认为ZSTD_CLEVEL_DEFAULT3)。 - + level 关键字设置压缩级别。对于 gzip,压缩级别应为 19 之间的整数(默认为 Z_DEFAULT_COMPRESSION,即 -1);对于 lz4,应为 1 到 12 之间的整数(默认为 0,表示快速压缩模式);对于 zstd,应为 ZSTD_minCLevel()(通常为 -131072)到 ZSTD_maxCLevel()(通常为 22)之间的整数(默认为 ZSTD_CLEVEL_DEFAULT,即 3)。 + long 关键字用于启用长距离匹配模式,可提高压缩比,但会增加内存使用。长距离模式仅支持 zstd。 @@ -2461,17 +2372,16 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" size (int8) - 表空间的大致大小,以千字节(1024字节)为单位,如果已请求进度报告;否则为null。 - + 如果请求了进度报告,则为表空间的大致大小,以千字节(1024 字节)为单位;否则为 null。 + - 在第二个常规结果集之后,将发送一个CopyOutResponse。 - 每个CopyData消息的有效负载将包含以下格式之一的消息: - + 第二个普通结果集之后,会发送一条 CopyOutResponse。每条 CopyData 消息的有效载荷都包含一条具有下列格式之一的消息: + @@ -2652,11 +2562,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" + + 在上述所有命令中,指定 boolean 类型的参数时,可以省略 value 部分,这等同于指定 TRUE。 + - 逻辑复制协议 + 逻辑流复制协议 本节介绍逻辑复制协议,它是一种以复制命令START_REPLICATION @@ -2665,7 +2578,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 逻辑复制协议构建在物理流复制协议的底层机制之上。 + 逻辑流复制协议构建在物理流复制协议的基本机制之上。 @@ -2714,7 +2627,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每个被发送的事务都包含零条或多条 DML 消息(插入、更新、删除)。在级联场景下,它还会包含 Origin 消息。Origin 消息表示该事务产生于另一个复制节点。由于逻辑复制协议中的复制节点可以是任意实现,因此唯一标识符就是该源头的名称。下游是否以及如何处理这一信息,由其自行决定。Origin 消息总是在事务中的任何 DML 消息之前发送。 + 每个发送的事务都包含零条或多条 DML 消息(Insert、Update、Delete)。在级联配置中,还可能包含 Origin 消息。Origin 消息表示该事务源自另一个复制节点。由于逻辑复制协议中的复制节点几乎可以是任何实现,因此唯一的标识符就是复制源的名称。下游负责按需处理这一信息(如果需要处理)。Origin 消息总是在事务中的任何 DML 消息之前发送。 @@ -2779,9 +2692,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 对后端返回的字符串长度,没有预定义的限制。 - 前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。 - 如果做不到这一点,就应读取完整字符串,并丢弃不适合固定大小缓冲区的尾随字符。 + 后端返回的字符串长度没有预定义的限制。前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。如果做不到这一点,就应读取完整字符串,并丢弃固定大小的缓冲区容纳不下的尾随字符。 @@ -2823,7 +2734,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2845,7 +2756,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定认证成功。 + 表示认证成功。 @@ -2865,7 +2776,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2887,7 +2798,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 Kerberos V5 认证。 + 表示需要 Kerberos V5 认证。 @@ -2907,7 +2818,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2929,7 +2840,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要明文密码。 + 表示需要明文密码。 @@ -2948,7 +2859,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2970,7 +2881,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要MD5加密的密码。 + 表示需要经过 MD5 加密的密码。 @@ -2981,7 +2892,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 用于加密密码时使用的盐。 + 加密密码时使用的盐。 @@ -3000,7 +2911,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -3021,7 +2932,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 GSSAPI 认证。 + 表示需要 GSSAPI 认证。 @@ -3040,7 +2951,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -3062,7 +2973,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定此消息包含GSSAPI或SSPI数据。 + 表示此消息包含 GSSAPI 或 SSPI 数据。 @@ -3092,7 +3003,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -3114,7 +3025,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 SSPI 认证。 + 表示需要 SSPI 认证。 @@ -3133,7 +3044,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -3155,14 +3066,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 SASL 认证。 + 表示需要 SASL 认证。 - 消息正文是服务器首选的 SASL 认证机制列表。在最后一个认证机制名称后需要一个零字节作为终止符。对于每个机制,有以下内容: + 消息体是按服务器偏好顺序排列的 SASL 认证机制列表。在最后一个认证机制名称之后,必须有一个零字节作为终止符。每个机制包含以下内容: @@ -3189,7 +3100,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -3211,7 +3122,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定此消息包含一个SASL挑战。 + 表示此消息包含 SASL 挑战。 @@ -3222,7 +3133,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - SASL数据,特定于正在使用的SASL机制。 + SASL 数据,具体内容取决于所使用的 SASL 机制。 @@ -3241,7 +3152,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -3263,7 +3174,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定SASL认证已完成。 + 表示 SASL 认证已完成。 @@ -3274,7 +3185,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - SASL结果"附加数据",特定于正在使用的SASL机制。 + SASL 结果的“附加数据”,具体内容取决于所使用的 SASL 机制。 @@ -3293,15 +3204,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为取消键数据。 - 如果前端希望能够稍后发出CancelRequest消息,必须保存这些值。 + 将此消息标识为取消请求密钥数据。如果前端希望以后能够发送 CancelRequest 消息,就必须保存这些值。 - Int32(12) + Int32 @@ -3316,27 +3226,27 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 这个后端的进程ID。 + 此后端的进程 ID。 - Int32 + Byten - 该后端的 secret key。该字段长度由消息总长度决定,并一直延伸到消息末尾。 + 此后端的密钥。此字段延伸至消息末尾,其范围由长度字段确定。 - key 的最小与最大长度分别为 4 和 256 字节。PostgreSQL 服务器当前发送不超过 32 字节的 key;更大的上限用于兼容未来版本及连接池/中间件使用更长 key 的需求。中间件也不宜用满全部字节,以便多层中间件叠加时仍可附加自身数据。 + 密钥长度最小为 4 字节,最大为 256 字节。PostgreSQL 服务器只发送最长 32 字节的密钥,但更大的长度上限允许未来的服务器版本、连接池和其他中间件使用更长的密钥。一种可能的用途是在服务器密钥中附加额外信息。因此,也建议中间件不要用尽所有字节,以便多层中间件叠加时,每一层都可以在密钥外再附加数据。 - 在协议 3.2 之前,secret key 固定为 4 字节。 + 在协议版本 3.2 之前,密钥始终为 4 字节长。 @@ -3352,7 +3262,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为绑定命令。 + 将该消息标识为 Bind 命令。 @@ -3396,10 +3306,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后面跟着的参数格式代码的数量(以下标记为C)。 - 这可以是零,表示没有参数或者所有参数都使用默认格式(文本); - 或者是一个,这种情况下指定的格式代码应用于所有参数; - 或者等于实际参数的数量。 + 后续参数格式代码的数量(下文以 C 表示)。可以为零,表示没有参数,或者所有参数都使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有参数;还可以等于实际参数数量。 @@ -3410,7 +3317,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数格式代码。每个目前必须是零(文本)或一(二进制)。 + 参数格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -3421,15 +3328,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后面跟着的参数值的数量(可能为零)。 - 这个数量必须与查询所需的参数数量匹配。 + 后续参数值的数量(可以为零)。必须与查询所需的参数数量一致。 - 接下来,对于每个参数,都会出现以下一对字段: + 接下来,每个参数都有以下一对字段: @@ -3439,9 +3345,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数值的长度,以字节为单位(此计数不包括自身)。可以为零。 - 作为特殊情况,-1表示空参数值。 - 在空参数值的情况下,不会跟随任何值字节。 + 参数值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 参数值。为 NULL 时,后面不再有值的字节。 @@ -3452,15 +3356,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数的值,以相关格式代码指示的格式表示。 - n是上述长度。 + 参数值,格式由对应的格式代码指明。n 为上述长度。 - 在最后一个参数之后,出现以下字段: + 最后一个参数之后是以下字段: @@ -3470,10 +3373,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后跟的结果列格式代码数量(以下标记为R)。 - 这可以是零,表示没有结果列,或者所有结果列应该使用默认格式(文本); - 或者是一个,此时指定的格式代码将应用于所有结果列(如果有); - 或者等于查询的实际结果列数。 + 后续结果列格式代码的数量(下文以 R 表示)。可以为零,表示没有结果列,或者所有结果列都应使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有结果列(如果有);还可以等于查询实际的结果列数量。 @@ -3484,7 +3384,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 结果列格式代码。每个目前必须是零(文本)或一(二进制)。 + 结果列格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -3503,7 +3403,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为绑定完成指示器。 + 将该消息标识为 Bind 完成指示。 @@ -3531,7 +3431,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 - 消息内容的长度,以字节为单位,包括此长度字段本身。 + 消息内容的长度(以字节为单位),包括其自身。 @@ -3580,7 +3480,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为关闭命令。 + 将该消息标识为 Close 命令。 @@ -3602,8 +3502,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 'S' 表示关闭一个预备语句;或者 - 'P' 表示关闭一个 portal。 + “S”表示关闭预备语句;“P”表示关闭 portal。 @@ -3633,7 +3532,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为关闭完成指示符。 + 将该消息标识为 Close 完成指示。 @@ -3663,7 +3562,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为命令完成响应。 + 将该消息标识为命令完成响应。 @@ -3685,7 +3584,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 命令标签。这通常是一个单词,用于标识已完成的SQL命令。 + 命令标签。通常是一个单词,用来标识已完成的 SQL 命令。 @@ -3730,10 +3629,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 对于COPY命令,标签是 - COPY rows,其中 - rows是复制的行数。 - (注意:行数仅出现在PostgreSQL 8.2及更高版本中。) + 对于 COPY 命令,标签为 COPY rows,其中 rows 是复制的行数。(注意:行数仅出现在 PostgreSQL 8.2 及更高版本中。) @@ -3864,8 +3760,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为开始复制响应。 - 前端现在必须发送复制数据(如果没有准备好,发送CopyFail消息)。 + 将该消息标识为开始 COPY 输入的响应。前端此时必须发送 COPY 输入数据(如果尚未准备好,应发送 CopyFail 消息)。 @@ -3911,9 +3806,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -3932,8 +3825,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为开始复制输出响应。 - 该消息将被复制输出数据跟随。 + 将该消息标识为开始 COPY 输出的响应。此消息之后会发送 COPY 输出数据。 @@ -3955,8 +3847,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 0表示整体COPY格式为文本格式(行由换行符分隔,列由分隔符字符分隔等)。 - 1表示整体复制格式为二进制格式(类似于DataRow格式)。更多信息请参见。 + 0表示整体COPY格式是文本的(行由换行符分隔,列由分隔符分隔等)。 + 1表示整体复制格式是二进制的(类似于DataRow格式)。 + 更多信息请参见 @@ -3978,9 +3871,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -3999,7 +3890,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为开始复制双响应。此消息仅用于流复制。 + 将该消息标识为开始双向 COPY 的响应。此消息仅用于流复制。 @@ -4021,8 +3912,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 0表示整体COPY格式为文本格式(行由换行符分隔,列由分隔符字符分隔等)。 - 1表示整体复制格式为二进制格式(类似于DataRow格式)。更多信息请参见。 + 0表示整体COPY格式是文本的(行由换行符分隔,列由分隔符分隔等)。 + 1表示整体复制格式是二进制的(类似于DataRow格式)。 + 更多信息请参见 @@ -4044,9 +3936,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -4094,7 +3984,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于每一列,都会出现以下一对字段: + 接下来,每列都有以下两个字段: @@ -4104,8 +3994,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列值的长度,以字节为单位(此计数不包括其本身)。可以为零。 - 作为特殊情况,-1表示空列值。在空值情况下,不跟随任何值字节。 + 列值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 列值。为 NULL 时,后面不再有值的字节。 @@ -4136,7 +4025,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为描述命令。 + 将该消息标识为 Describe 命令。 @@ -4189,7 +4078,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为对空查询字符串的响应。(这相当于CommandComplete。) + 标识消息为对空查询字符串的响应。(此消息替代 CommandComplete。) @@ -4237,7 +4126,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 消息正文由一个或多个已识别的字段组成,后跟一个零字节作为终止符。字段可以以任何顺序出现。对于每个字段,都有以下内容: + 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -4260,7 +4149,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 字段数值。 + 字段值。 @@ -4279,7 +4168,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为一个执行命令。 + 将该消息标识为 Execute 命令。 @@ -4312,7 +4201,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果 portal 包含返回行的查询,则为要返回的最大行数(否则忽略)。零表示没有限制。 + 如果 portal 包含返回行的查询,则这是最多返回的行数(否则忽略此值)。零表示无限制 @@ -4331,7 +4220,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为Flush命令。 + 将该消息标识为 Flush 命令。 @@ -4383,7 +4272,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定要调用的函数的对象ID。 + 指定要调用的函数的对象 ID。 @@ -4394,10 +4283,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后面跟着的参数格式代码的数量(以下标记为C)。 - 这可以是零,表示没有参数或所有参数都使用默认格式(文本); - 或者是一个,这种情况下指定的格式代码应用于所有参数; - 或者等于实际参数的数量。 + 后续参数格式代码的数量(以下用 C 表示)。可以为零,表示没有参数,或所有参数都采用默认格式(文本);也可以为一,表示将指定的格式代码用于所有参数;还可以等于实际参数数量。 @@ -4426,7 +4312,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于每个参数,都会出现以下一对字段: + 接下来,每个参数都有以下两个字段: @@ -4436,9 +4322,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数值的长度,以字节为单位(此计数不包括自身)。可以为零。 - 作为特殊情况,-1表示空参数值。 - 在空参数值的情况下,不会跟随任何值字节。 + 参数值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 参数值。为 NULL 时,后面不再有值的字节。 @@ -4457,7 +4341,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 在最后一个参数之后,出现以下字段: + 最后一个参数之后还有以下字段: @@ -4467,7 +4351,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 函数结果的格式代码。目前必须是零(文本)或一(二进制)。 + 函数结果的格式代码。目前必须为零(文本)或一(二进制)。 @@ -4508,9 +4392,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 函数结果值的长度,以字节为单位(此计数不包括本身)。可以为零。 - 作为特殊情况,-1表示NULL函数结果。 - 在NULL情况下,不会跟随任何值字节。 + 函数结果值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 函数结果。为 NULL 时,后面不再有值的字节。 @@ -4636,7 +4518,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 服务器支持的最新次要协议版本,用于客户端请求的主要协议版本。 + 对于客户端请求的协议主版本,服务器所支持的最新协议次版本。 @@ -4647,14 +4529,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 服务器未识别的协议选项数量。 + 服务器无法识别的协议选项数量。 - 然后,对于服务器未识别的协议选项,有以下内容: + 接下来,对于服务器无法识别的每个协议选项,都有以下内容: @@ -4731,7 +4613,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 消息正文由一个或多个已识别的字段组成,后跟一个零字节作为终止符。字段可以以任何顺序出现。对于每个字段,都有以下内容: + 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -4754,7 +4636,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 字段数值。 + 字段值。 @@ -4795,7 +4677,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 通知后端进程的进程ID。 + 发出通知的后端进程的进程 ID。 @@ -4806,7 +4688,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 通知被触发的频道名称。 + 发出该通知的通道名称。 @@ -4817,7 +4699,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 从通知进程传递的有效负载字符串。 + 通知进程传来的有效载荷字符串。 @@ -4865,7 +4747,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 然后,对于每个参数,都有以下内容: + 接下来,每个参数都有以下内容: @@ -4875,7 +4757,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定参数数据类型的对象ID。 + 指定参数数据类型的对象 ID。 @@ -4916,7 +4798,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 正在报告的运行时参数的名称。 + 所报告的运行时参数的名称。 @@ -4946,7 +4828,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为解析命令。 + 将该消息标识为 Parse 命令。 @@ -4998,7 +4880,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 然后,对于每个参数,都有以下内容: + 接下来,每个参数都有以下内容: @@ -5008,7 +4890,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定参数数据类型的对象ID。在这里放置零相当于未指定类型。 + 指定参数数据类型的对象 ID。此处填零等同于不指定类型。 @@ -5027,7 +4909,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为解析完成指示器。 + 将该消息标识为 Parse 完成指示。 @@ -5099,8 +4981,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为 portal 挂起指示器。 - 请注意,仅当执行消息的行数限制达到时才会出现此消息。 + 将该消息标识为 portal 挂起指示。注意,仅当达到 Execute 消息指定的行数限制时,才会出现此消息。 @@ -5236,14 +5117,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定一行中的字段数(可以为零)。 + 指定一行中的字段数量(可以为零)。 - 然后,对于每个字段,都有以下内容: + 接下来,每个字段都有以下内容: @@ -5264,7 +5145,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果该字段可以被识别为特定表的列,则为该表的对象ID;否则为零。 + 如果能够确定该字段是某个特定表的列,则为该表的对象 ID;否则为零。 @@ -5275,7 +5156,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果该字段可以被识别为特定表的列,则为该列的属性编号;否则为零。 + 如果能够确定该字段是某个特定表的列,则为该列的属性编号;否则为零。 @@ -5286,7 +5167,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 字段数据类型的对象ID。 + 字段数据类型的对象 ID。 @@ -5321,7 +5202,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 正在使用的字段格式代码。目前将为零(文本)或一(二进制)。在从描述语句变体返回的RowDescription中,格式代码尚未知晓,将始终为零。 + 字段所使用的格式代码。目前为零(文本)或一(二进制)。对于 Describe 针对预备语句的变体所返回的 RowDescription,格式代码尚未确定,始终为零。 @@ -5374,7 +5255,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 长度为SASL机制特定的“初始客户端响应”,如果没有初始响应,则为-1。 + 后续 SASL 机制特有的“客户端初始响应”的长度;如果没有初始响应,则为 -1。 @@ -5489,7 +5370,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 协议版本号。高16位是主版本号。低16位是次版本号。 + 协议版本号。高 16 位是主版本号。低 16 位是次版本号。 例如,协议版本 3.2 在十进制中表示为 196610, 在十六进制中则更清楚地表示为 0x00030002 @@ -5498,9 +5379,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 协议版本号后面跟着一个或多个参数名和值字符串对。在最后一个名/值对之后需要一个零字节作为终止符。 - 参数可以以任何顺序出现。user是必需的,其他是可选的。 - 每个参数的指定方式为: + 协议版本号之后是一个或多个参数名与参数值字符串对。最后一个名称/值对之后必须有一个零字节作为终止符。参数可以按任意顺序出现。其中,user是必需的,其余均为可选。每个参数按以下方式指定: @@ -5510,7 +5389,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数名称。当前识别的名称包括: + 参数名称。目前能够识别的名称如下: @@ -5561,7 +5440,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数数值。 + 参数值。 @@ -5580,7 +5459,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为同步命令。 + 将该消息标识为 Sync 命令。 @@ -5633,7 +5512,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 错误和通知消息域 + 错误和通知消息字段 本节描述了ErrorResponse和NoticeResponse消息中可能出现的字段。每个字段类型都有一个单字节的标识符。 @@ -5646,11 +5525,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 严重性: 字段内容为ERROR, FATAL, 或 - PANIC (在错误消息中), 或 - WARNING, NOTICE, DEBUG, - INFO, 或 LOG (在通知消息中), - 或者这些内容的本地化翻译。始终存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中),或这些内容的本地化翻译。始终存在。 @@ -5660,11 +5535,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 严重性:字段内容为ERRORFATAL或 - PANIC(在错误消息中),或WARNINGNOTICEDEBUG、 - INFOLOG(在通知消息中)。 - 这与S字段相同,只是内容不会被本地化。仅在由PostgreSQL版本9.6 - 及更高版本生成的消息中存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中)。它与 S 字段相同,只是内容从不本地化。仅在 PostgreSQL 9.6 及更高版本生成的消息中存在。 @@ -5674,7 +5545,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Code: 错误的SQLSTATE代码(参见)。不可本地化。始终存在。 + 代码:错误的 SQLSTATE 代码(见 )。不可本地化。始终存在。 @@ -5684,9 +5555,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 消息: 主要的人类可读错误消息。 - 这应该准确但简洁(通常一行)。 - 总是存在。 + 消息:主要的可读错误消息。应准确而简洁(通常为一行)。始终存在。 @@ -5696,7 +5565,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 详细信息:一个可选的次要错误消息,提供有关问题的更多详细信息。可能会跨多行。 + 详细信息:可选的次要错误消息,提供有关该问题的更多细节。可能占多行。 @@ -5706,9 +5575,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 提示: 关于问题应该怎么做的一个可选建议。 - 这意在与细节不同,它提供建议(可能不合适)而不是硬性事实。 - 可能会跨越多行。 + 提示:可选的建议,说明如何处理该问题。它与详细信息的区别在于,它提供建议(可能并不合适),而非确凿事实。可能占多行。 @@ -5751,9 +5618,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Where: 错误发生的上下文指示。 - 目前包括活动的过程语言函数和内部生成查询的调用堆栈回溯。 - 跟踪每行一个条目,最近的在前。 + 上下文:说明错误发生时的上下文。目前包括活跃的过程语言函数和内部生成的查询的调用栈回溯。回溯每行一个条目,最近的调用在前。 @@ -5763,7 +5628,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Schema name: 如果错误与特定数据库对象相关联,则为包含该对象的模式的名称(如果有)。 + 模式名:如果错误与某个特定数据库对象有关,则为包含该对象的模式名称(如果有)。 @@ -5773,7 +5638,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 表名: 如果错误与特定表相关联,则为表的名称。(有关表模式名称的名称,请参考模式名称字段。) + 表名:如果错误与某个特定表有关,则为该表的名称。(表所在模式的名称见模式名字段。) @@ -5783,7 +5648,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列名: 如果错误与特定表列相关联,则为列的名称。(请参考模式和表名字段以识别表。) + 列名:如果错误与某个特定表列有关,则为该列的名称。(通过模式名和表名字段确定该表。) @@ -5793,8 +5658,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 数据类型名称: 如果错误与特定数据类型相关联,则为数据类型的名称。 - (有关数据类型模式的名称,请参阅模式名称字段。) + 数据类型名:如果错误与某个特定数据类型有关,则为该数据类型的名称。(数据类型所在模式的名称见模式名字段。) @@ -5804,8 +5668,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 约束名称: 如果错误与特定约束相关联,则为约束的名称。请参考上面列出的字段,了解相关表或域。 - (为此,即使索引不是使用约束语法创建的,也将其视为约束。) + 约束名:如果错误与某个特定约束有关,则为该约束的名称。相关的表或域见上述字段。(这里将索引也视为约束,即使它不是用约束语法创建的。) @@ -5815,7 +5678,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 文件: 报告错误的源代码位置的文件名。 + 文件:报告错误的源代码位置所在的文件名。 @@ -5825,7 +5688,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Line: 源代码位置的行号,报告错误的位置。 + 行号:报告错误的源代码位置所在的行号。 @@ -5835,7 +5698,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Routine: 报告错误的源代码例程的名称。 + 例程:报告错误的源代码例程的名称。 @@ -5844,15 +5707,12 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 模式名称、表名称、列名称、数据类型名称和约束名称的字段仅针对有限数量的错误类型提供; - 请参阅。前端不应假设任何这些字段的存在就保证了另一个字段的存在。 - 核心错误源观察到上述相互关系,但用户定义的函数可能以其他方式使用这些字段。 - 同样地,客户端不应假设这些字段表示当前数据库中的当代对象。 + 模式名、表名、列名、数据类型名和约束名字段仅针对有限的几类错误提供,见 。前端不应假设其中任何字段的存在就保证了另一个字段的存在。核心错误源遵循上述相互关系,但用户定义的函数可能以其他方式使用这些字段。同样,客户端不应假设这些字段表示当前数据库中现存的对象。 - 客户端负责格式化显示的信息以满足其需求;特别是应根据需要换行。错误消息字段中出现的换行符应被视为段落分隔符,而不是换行符。 + 客户端负责按自身需要格式化显示的信息;尤其应根据需要将长行断开。错误消息字段中的换行符应视为段落分隔符,而非行分隔符。 @@ -5878,18 +5738,18 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为开始消息。 + 将该消息标识为 Begin 消息。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 事务的最终LSN。 + 事务的最终 LSN。 @@ -5900,7 +5760,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -5911,7 +5771,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -5941,8 +5801,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -5953,14 +5812,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标志; 逻辑解码消息是非事务性的时为0,是事务性的时为1。 + 标志:0 表示没有标志;1 表示该逻辑解码消息是事务性的。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6016,7 +5875,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为提交消息。 + 将该消息标识为 Commit 消息。 @@ -6034,22 +5893,22 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 提交的LSN。 + 提交的 LSN。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 事务的结束LSN。 + 事务的结束 LSN。 @@ -6060,7 +5919,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6079,18 +5938,18 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为原始消息。 + 将该消息标识为 Origin 消息。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 原始服务器上提交的LSN。 + 源服务器上提交的 LSN。 @@ -6101,14 +5960,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 原点的名称。 + 复制源的名称。 - 请注意,在单个事务中可能存在多个Origin消息。 + 注意,单个事务中可能有多条 Origin 消息。 @@ -6124,7 +5983,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为关系消息。 + 将该消息标识为 Relation 消息。 @@ -6135,8 +5994,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6158,7 +6016,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 命名空间(pg_catalog为空字符串)。 + 命名空间(对于 pg_catalog 为空字符串)。 @@ -6180,7 +6038,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 关系的复制标识设置(与relreplidentpg_class中相同)。 + 关系的复制标识设置(与 pg_class 中的 relreplident 相同)。 @@ -6198,7 +6056,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于出版物中包含的每一列(除了生成的列),会出现以下消息部分: + 接下来,发布中包含的每一列都会出现以下消息部分: @@ -6208,7 +6066,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列的标志。目前可以是0表示没有标志,或者是1表示将该列标记为键的一部分。 + 列的标志。目前可以为 0,表示没有标志;或为 1,标记该列是键的一部分。 @@ -6241,7 +6099,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列的类型修饰符 (atttypmod)。 + 列的类型修饰符(atttypmod)。 @@ -6260,7 +6118,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为类型消息。 + 将该消息标识为 Type 消息。 @@ -6271,8 +6129,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6294,7 +6151,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 命名空间(pg_catalog为空字符串)。 + 命名空间(对于 pg_catalog 为空字符串)。 @@ -6324,7 +6181,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为插入消息。 + 将该消息标识为 Insert 消息。 @@ -6335,8 +6192,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6347,7 +6203,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。 + 关系的 OID,与 Relation 消息中的 ID 对应。 @@ -6358,7 +6214,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData消息为新元组。 + 将后续 TupleData 消息标识为新元组。 @@ -6369,7 +6225,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分,表示新元组的内容。 + 表示新元组内容的 TupleData 消息部分。 @@ -6388,7 +6244,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为更新消息。 + 将该消息标识为 Update 消息。 @@ -6399,8 +6255,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6411,7 +6266,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。 + 关系的 OID,与 Relation 消息中的 ID 对应。 @@ -6422,8 +6277,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData子消息为键。 - 此字段是可选的,仅在更新更改了属于REPLICA IDENTITY索引的任何列的数据时才存在。 + 将后续 TupleData 子消息标识为键。此字段可选,仅在更新更改了属于 REPLICA IDENTITY 索引的某一列或多列的数据时出现。 @@ -6434,8 +6288,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData子消息为旧元组。 - 此字段是可选的,仅在发生更新的表中REPLICA IDENTITY设置为FULL时才存在。 + 将后续 TupleData 子消息标识为旧元组。此字段可选,仅在发生更新的表将 REPLICA IDENTITY 设为 FULL 时出现。 @@ -6446,7 +6299,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分表示旧元组或主键的内容。仅在先前的'O'或'K'部分存在时才存在。 + 表示旧元组或主键内容的 TupleData 消息部分。仅在前面的'O'或'K'部分存在时出现。 @@ -6457,7 +6310,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData消息为新元组。 + 将后续 TupleData 消息标识为新元组。 @@ -6468,14 +6321,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分表示新元组的内容。 + 表示新元组内容的 TupleData 消息部分。 - 更新消息可能包含一个'K'消息部分,也可能包含一个'O'消息部分,或者两者都不包含,但绝不会同时包含两者。 + Update 消息可以包含 'K' 消息部分或 'O' 消息部分,也可以两者都不包含,但绝不会同时包含两者。 @@ -6491,7 +6344,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为删除消息。 + 将该消息标识为 Delete 消息。 @@ -6502,8 +6355,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6514,7 +6366,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。 + 关系的 OID,与 Relation 消息中的 ID 对应。 @@ -6525,8 +6377,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData子消息为键。 - 如果发生删除操作的表使用索引作为REPLICA IDENTITY,则存在此字段。 + 将后续 TupleData 子消息标识为键。如果发生删除的表使用索引作为 REPLICA IDENTITY,则出现此字段。 @@ -6537,8 +6388,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData消息为旧元组。 - 如果发生删除操作的表的REPLICA IDENTITY设置为FULL,则存在此字段。 + 将后续 TupleData 消息标识为旧元组。如果发生删除的表将 REPLICA IDENTITY 设为 FULL,则出现此字段。 @@ -6549,14 +6399,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分,表示旧元组或主键的内容,取决于前一个字段。 + 表示旧元组或主键内容的 TupleData 消息部分,具体取决于前一个字段。 - 删除消息可能包含一个'K'消息部分或一个'O'消息部分,但绝不会同时包含两者。 + Delete 消息可以包含 'K' 消息部分或 'O' 消息部分,但绝不会同时包含两者。
@@ -6572,7 +6422,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为截断消息。 + 将该消息标识为 Truncate 消息。 @@ -6583,8 +6433,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6618,7 +6467,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。该字段对每个关系都重复。 + 关系的 OID,与 Relation 消息中的 ID 对应。每个关系都重复出现此字段。 @@ -6643,7 +6492,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为流开始消息。 + 将该消息标识为 Stream Start 消息。 @@ -6654,7 +6503,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6684,7 +6533,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为流停止消息。 + 将该消息标识为 Stream Stop 消息。 @@ -6703,7 +6552,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为流提交消息。 + 将该消息标识为 Stream Commit 消息。 @@ -6714,7 +6563,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6732,22 +6581,22 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 提交的LSN。 + 提交的 LSN。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 事务的结束LSN。 + 事务的结束 LSN。 @@ -6758,7 +6607,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6777,7 +6626,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为流中止消息。 + 将该消息标识为 Stream Abort 消息。 @@ -6788,7 +6637,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6845,14 +6694,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务开始消息。 + 将该消息标识为 Begin Prepare 消息。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6863,7 +6712,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6878,7 +6727,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6889,7 +6738,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6919,7 +6768,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务消息。 + 将该消息标识为 Prepare 消息。 @@ -6937,7 +6786,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6948,7 +6797,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6963,7 +6812,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6974,7 +6823,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -7004,7 +6853,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务提交消息。 + 将该消息标识为 Commit Prepared 消息。 @@ -7022,7 +6871,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -7033,7 +6882,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -7048,7 +6897,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -7059,7 +6908,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -7089,7 +6938,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务回滚消息。 + 将该消息标识为 Rollback Prepared 消息。 @@ -7107,7 +6956,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -7118,7 +6967,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -7133,7 +6982,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -7155,7 +7004,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -7185,7 +7034,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为流式预备事务消息。 + 将该消息标识为 Stream Prepare 消息。 @@ -7203,7 +7052,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -7214,7 +7063,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -7229,7 +7078,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -7240,7 +7089,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -7283,14 +7132,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于每一列(除了生成的列),会出现以下子消息之一: + 接下来,每个已发布的列都会出现以下子消息之一: Byte1('n') - 将数据标识为NULL值。 + 将该数据标识为 NULL 值。 @@ -7301,7 +7150,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('u') - 将TOASTed值标识为未更改的值(实际值未发送)。 + 标识未更改的 TOAST 值(不发送实际值)。 @@ -7312,7 +7161,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('t') - 将数据标识为文本格式化值。 + 将该数据标识为文本格式的值。 @@ -7323,7 +7172,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('b') - 将数据标识为二进制格式化值。 + 将该数据标识为二进制格式的值。 @@ -7341,9 +7190,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byten - 列的值,以二进制或文本格式呈现。 - (如前述格式字节中指定)。 - n是上述长度。 + 列值,采用二进制或文本格式(由前面的格式字节指定)。n 为上述长度。 diff --git a/zh/19/rangetypes.sgml b/zh/19/rangetypes.sgml index 68409fa3..5badec6c 100644 --- a/zh/19/rangetypes.sgml +++ b/zh/19/rangetypes.sgml @@ -5,11 +5,11 @@ 范围类型 - range type + 范围类型 - multirange type + 多范围类型 @@ -21,7 +21,7 @@ - 每种范围类型都有一个对应的多范围类型。多范围是由多个彼此不连续、非空且非 NULL 的范围构成的有序列表。大多数范围操作符也可作用于多范围,并且多范围还有一些专用函数。 + 每种范围类型都有一个对应的多范围类型。多范围是一个有序列表,其中的范围彼此不连续,且均非空、非 NULL。大多数范围操作符也可作用于多范围,并且多范围还有一些专用函数。 @@ -124,15 +124,15 @@ SELECT isempty(numrange(1, 5)); 无限(无界)范围 - 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作 +/-infinity,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的 +/-infinity 值。 + 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作正负无穷大,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的正负无穷大值。 - 具有infinity概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 + 具有无穷大概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 - 函数lower_infupper_inf分别测试范围的下界和上界是否为无限。 + 函数lower_infupper_inf分别测试范围是否没有下界和上界。 @@ -324,8 +324,8 @@ SELECT '[11:10, 23:00]'::timerange; 索引 - range type - indexes on + 范围类型 + 索引 @@ -357,7 +357,7 @@ CREATE INDEX reservation_idx ON reservation USING GIST (during); - 此外,也可以为范围类型的表列创建 B-树和哈希索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和哈希支持主要是为了允许在查询内部进行排序和哈希,而不是用于创建实际的索引。 + 此外,也可以为范围类型的表列创建 B-树和 hash 索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和 hash 支持主要是为了允许在查询内部进行排序和 hash 运算,而不是用于创建实际的索引。 @@ -366,8 +366,8 @@ CREATE INDEX reservation_idx ON reservation USING GIST (during); 范围上的约束 - range type - exclude + 范围类型 + 排他约束 diff --git a/zh/19/ref/alter_extension.sgml b/zh/19/ref/alter_extension.sgml index 7b45aa24..1d4fded4 100644 --- a/zh/19/ref/alter_extension.sgml +++ b/zh/19/ref/alter_extension.sgml @@ -171,7 +171,7 @@ ALTER EXTENSION name DROP 要添加到扩展中或从扩展中移除的对象名称。表、聚合、域、外部表、函数、 - 操作符、操作符类、操作符族、过程、属性图、例程、序列、文本搜索对象、类型和视图的名称 + 操作符、操作符类、操作符族、过程、属性图、例程、序列、文本检索对象、类型和视图的名称 可以带模式限定。 diff --git a/zh/19/ref/alter_tsconfig.sgml b/zh/19/ref/alter_tsconfig.sgml index 891dce66..0845a229 100644 --- a/zh/19/ref/alter_tsconfig.sgml +++ b/zh/19/ref/alter_tsconfig.sgml @@ -19,7 +19,7 @@ PostgreSQL documentation ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义 + 更改一个文本检索配置的定义 @@ -51,7 +51,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义。你可以修改其从记号类型到字典的映射, + 更改一个文本检索配置的定义。你可以修改其从词元类型到词典的映射, 或者更改该配置的名称或拥有者。 @@ -75,7 +75,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 一个现有文本搜索配置的名称(可以是模式限定的)。 + 一个现有文本检索配置的名称(可以是模式限定的)。 @@ -86,7 +86,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 由该配置的解析器发出的记号类型的名称。 + 由该配置的解析器发出的词元类型的名称。 @@ -97,7 +97,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 用于指定记号类型的文本搜索字典名称。如果列出了多个字典, + 用于指定词元类型的文本检索词典名称。如果列出了多个词典, 将按指定顺序依次查阅它们。 @@ -109,7 +109,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 在映射中要替换的文本搜索字典的名称。 + 在映射中要替换的文本检索词典的名称。 @@ -121,7 +121,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA 被用来替代old_dictionary - 的文本搜索字典的名称。 + 的文本检索词典的名称。 @@ -132,7 +132,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新名称。 + 该文本检索配置的新名称。 @@ -143,7 +143,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新拥有者。 + 该文本检索配置的新拥有者。 @@ -154,7 +154,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新模式。 + 该文本检索配置的新模式。 @@ -163,17 +163,17 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - ADD MAPPING FOR形式会为指定记号类型设置要查阅的字典列表; - 如果任一记号类型已经有映射,则会报错。ALTER MAPPING FOR - 形式作用相同,但会先移除这些记号类型的任何现有映射。 + ADD MAPPING FOR形式会为指定词元类型设置要查阅的词典列表; + 如果任一词元类型已经有映射,则会报错。ALTER MAPPING FOR + 形式作用相同,但会先移除这些词元类型的任何现有映射。 ALTER MAPPING REPLACE形式会在 old_dictionary出现的任何位置, 用new_dictionary替换它。 - 如果出现FOR,则只对指定的记号类型这样做;如果未出现 + 如果出现FOR,则只对指定的词元类型这样做;如果未出现 FOR,则对该配置的所有映射这样做。 - DROP MAPPING形式会移除指定记号类型的所有字典,使这些类型的 - 记号被文本搜索配置忽略。除非出现IF EXISTS,否则如果这些 - 记号类型没有映射就会报错。 + DROP MAPPING形式会移除指定词元类型的所有词典,使这些类型的 + 词元被文本检索配置忽略。除非出现IF EXISTS,否则如果这些 + 词元类型没有映射就会报错。 @@ -187,7 +187,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA 下面的示例将my_config中凡是使用 - english字典的地方,都替换为swedish字典。 + english词典的地方,都替换为swedish词典。 diff --git a/zh/19/ref/alter_tsdictionary.sgml b/zh/19/ref/alter_tsdictionary.sgml index 163d788b..798c6734 100644 --- a/zh/19/ref/alter_tsdictionary.sgml +++ b/zh/19/ref/alter_tsdictionary.sgml @@ -19,7 +19,7 @@ PostgreSQL documentation ALTER TEXT SEARCH DICTIONARY - 更改一个文本搜索字典的定义 + 更改一个文本检索词典的定义 @@ -43,14 +43,14 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - ALTER TEXT SEARCH DICTIONARY更改文本搜索字典的 - 定义。你可以更改该字典的模板相关选项,也可以更改该字典的名称或拥有者。 + ALTER TEXT SEARCH DICTIONARY更改文本检索词典的 + 定义。你可以更改该词典的模板相关选项,也可以更改该词典的名称或拥有者。 - 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该字典 + 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该词典 的拥有者。 @@ -67,7 +67,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 一个现有文本搜索字典的名称(可以是模式限定的)。 + 一个现有文本检索词典的名称(可以是模式限定的)。 @@ -78,7 +78,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -89,7 +89,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 模板相关选项要使用的新值。如果省略等号和值,则会从该字典中移除 + 模板相关选项要使用的新值。如果省略等号和值,则会从该词典中移除 该选项之前的设置,从而允许使用默认值。 @@ -101,7 +101,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新名称。 + 该文本检索词典的新名称。 @@ -112,7 +112,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新拥有者。 + 该文本检索词典的新拥有者。 @@ -123,7 +123,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新模式。 + 该文本检索词典的新模式。 @@ -144,7 +144,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 下面的示例命令更改了一个基于 Snowball 的字典的停用词列表。其他参数 + 下面的示例命令更改了一个基于 Snowball 的词典的停用词列表。其他参数 保持不变。 @@ -170,7 +170,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( language = dutch, StopWords ); - 下面的示例命令更新了该字典的定义,但实际上并没有做 + 下面的示例命令更新了该词典的定义,但实际上并没有做 任何更改。 @@ -178,7 +178,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( dummy ); (之所以可行,是因为选项移除代码在不存在该选项时也不会报错。) - 这种技巧在修改该字典的配置文件时很有用:ALTER + 这种技巧在修改该词典的配置文件时很有用:ALTER 会强制现有数据库会话重新读取配置文件,而如果它们先前已经读取过这 些文件,本来是不会再次读取的。 diff --git a/zh/19/ref/alter_tsparser.sgml b/zh/19/ref/alter_tsparser.sgml index 6efd5c5b..17c9a062 100644 --- a/zh/19/ref/alter_tsparser.sgml +++ b/zh/19/ref/alter_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH PARSER - 更改一个全文检索解析器的定义 + 更改一个文本检索解析器的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA 描述 - ALTER TEXT SEARCH PARSER更改全文检索解析器的定义。 + ALTER TEXT SEARCH PARSER更改文本检索解析器的定义。 当前唯一支持的功能是更改该解析器的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA name - 一个现有全文检索解析器的名称(可以是模式限定的)。 + 一个现有文本检索解析器的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_name - 该全文检索解析器的新名称。 + 该文本检索解析器的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_schema - 该全文检索解析器的新模式。 + 该文本检索解析器的新模式。 diff --git a/zh/19/ref/alter_tstemplate.sgml b/zh/19/ref/alter_tstemplate.sgml index af25c5b4..2d9151e4 100644 --- a/zh/19/ref/alter_tstemplate.sgml +++ b/zh/19/ref/alter_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH TEMPLATE - 更改一个文本搜索模板的定义 + 更改一个文本检索模板的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA 描述 - ALTER TEXT SEARCH TEMPLATE更改文本搜索模板的定义。 + ALTER TEXT SEARCH TEMPLATE更改文本检索模板的定义。 当前唯一支持的功能是更改该模板的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA name - 一个现有文本搜索模板的名称(可以是模式限定的)。 + 一个现有文本检索模板的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_name - 该文本搜索模板的新名称。 + 该文本检索模板的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_schema - 该文本搜索模板的新模式。 + 该文本检索模板的新模式。 diff --git a/zh/19/ref/create_tsconfig.sgml b/zh/19/ref/create_tsconfig.sgml index 52970b36..fc77edb9 100644 --- a/zh/19/ref/create_tsconfig.sgml +++ b/zh/19/ref/create_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH CONFIGURATION - 定义一个新的文本搜索配置 + 定义一个新的文本检索配置 @@ -33,24 +33,24 @@ CREATE TEXT SEARCH CONFIGURATION name CREATE TEXT SEARCH CONFIGURATION - 创建一个新的文本搜索配置。文本搜索配置指定一个能把字符串拆分为记号 - 的文本搜索解析器,以及一些可用于判断哪些记号对搜索有意义的词典。 + 创建一个新的文本检索配置。文本检索配置指定一个能把字符串拆分为词元 + 的文本检索解析器,以及一些可用于判断哪些词元对搜索有意义的词典。 - 如果只指定了解析器,那么新文本搜索配置最初没有从记号类型到词典的映射, + 如果只指定了解析器,那么新文本检索配置最初没有从词元类型到词典的映射, 因而会忽略所有词。要让该配置真正可用,必须使用后续的ALTER TEXT SEARCH CONFIGURATION命令创建映射。 - 另一种方式是复制一个现有的文本搜索配置。 + 另一种方式是复制一个现有的文本检索配置。 - 如果给出了一个模式名称,则文本搜索配置会被创建在指定的模式中。否则它将会 + 如果给出了一个模式名称,则文本检索配置会被创建在指定的模式中。否则它将会 被创建在当前模式中。 - 定义该文本搜索配置的用户会成为其拥有者。 + 定义该文本检索配置的用户会成为其拥有者。 @@ -66,7 +66,7 @@ CREATE TEXT SEARCH CONFIGURATION namename - 要创建的文本搜索配置的名称。该名称可以是模式限定的。 + 要创建的文本检索配置的名称。该名称可以是模式限定的。 @@ -75,7 +75,7 @@ CREATE TEXT SEARCH CONFIGURATION nameparser_name - 此配置要使用的文本搜索解析器的名称。 + 此配置要使用的文本检索解析器的名称。 @@ -84,7 +84,7 @@ CREATE TEXT SEARCH CONFIGURATION namesource_config - 要复制的现有文本搜索配置的名称。 + 要复制的现有文本检索配置的名称。 diff --git a/zh/19/ref/create_tsdictionary.sgml b/zh/19/ref/create_tsdictionary.sgml index c45a7240..823710b7 100644 --- a/zh/19/ref/create_tsdictionary.sgml +++ b/zh/19/ref/create_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH DICTIONARY - 定义一个新的文本搜索字典 + 定义一个新的文本检索词典 @@ -33,19 +33,19 @@ CREATE TEXT SEARCH DICTIONARY name CREATE TEXT SEARCH DICTIONARY创建一个 - 新的文本搜索字典。文本搜索字典指定一种在搜索时识别哪些词值得关注、 - 哪些词不值得关注的方式。字典依赖于文本搜索模板,后者规定了实际执行 - 这项工作的函数。通常,字典会提供一些选项,用来控制模板函数的具体 + 新的文本检索词典。文本检索词典指定一种在搜索时识别哪些词值得关注、 + 哪些词不值得关注的方式。词典依赖于文本检索模板,后者规定了实际执行 + 这项工作的函数。通常,词典会提供一些选项,用来控制模板函数的具体 行为。 - 如果给出了一个模式名称,那么该文本搜索字典会被创建在指定的模式中。 + 如果给出了一个模式名称,那么该文本检索词典会被创建在指定的模式中。 否则它会被创建在当前模式中。 - 定义文本搜索字典的用户将成为其拥有者。 + 定义文本检索词典的用户将成为其拥有者。 @@ -61,7 +61,7 @@ CREATE TEXT SEARCH DICTIONARY name name - 要创建的文本搜索字典的名称。该名称可以被模式限定。 + 要创建的文本检索词典的名称。该名称可以被模式限定。 @@ -70,7 +70,7 @@ CREATE TEXT SEARCH DICTIONARY name template - 用于定义该字典基本行为的文本搜索模板名称。 + 用于定义该词典基本行为的文本检索模板名称。 @@ -79,7 +79,7 @@ CREATE TEXT SEARCH DICTIONARY name option - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -105,7 +105,7 @@ CREATE TEXT SEARCH DICTIONARY name 下面的示例命令创建了一个基于 Snowball 且使用非标准停用词列表的 - 字典。 + 词典。 diff --git a/zh/19/ref/create_tsparser.sgml b/zh/19/ref/create_tsparser.sgml index 358152ce..88be54e6 100644 --- a/zh/19/ref/create_tsparser.sgml +++ b/zh/19/ref/create_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH PARSER - 定义一个新的全文检索解析器 + 定义一个新的文本检索解析器 @@ -36,19 +36,19 @@ CREATE TEXT SEARCH PARSER name ( CREATE TEXT SEARCH PARSER创建一个 - 新的全文检索解析器。全文检索解析器定义了一种方法,用于将文本字符串 - 拆分成记号并为这些记号指定类型(类别)。解析器本身并没有太大用处, - 必须与一些全文检索字典一起绑定到一个全文检索配置中,才能用于搜索。 + 新的文本检索解析器。文本检索解析器定义了一种方法,用于将文本字符串 + 拆分成词元并为这些词元指定类型(类别)。解析器本身并没有太大用处, + 必须与一些文本检索词典一起绑定到一个文本检索配置中,才能用于搜索。 - 如果给出了一个模式名称,那么全文检索解析器将被创建在指定的模式中。 + 如果给出了一个模式名称,那么文本检索解析器将被创建在指定的模式中。 否则它会被创建在当前模式中。 要使用CREATE TEXT SEARCH PARSER,你必须是超级用户。 - 之所以有此限制,是因为错误的全文检索解析器定义可能会让服务器陷入 + 之所以有此限制,是因为错误的文本检索解析器定义可能会让服务器陷入 混乱,甚至崩溃。 @@ -65,7 +65,7 @@ CREATE TEXT SEARCH PARSER name ( name - 要创建的全文检索解析器的名称。该名称可以是模式限定的。 + 要创建的文本检索解析器的名称。该名称可以是模式限定的。 @@ -83,7 +83,7 @@ CREATE TEXT SEARCH PARSER name ( gettoken_function - 该解析器的获取下一个记号的函数名称。 + 该解析器的获取下一个词元的函数名称。 @@ -101,7 +101,7 @@ CREATE TEXT SEARCH PARSER name ( lextypes_function - 该解析器的 lextypes 函数的名称(该函数返回它所产生的记号类型集合的 + 该解析器的 lextypes 函数的名称(该函数返回它所产生的词元类型集合的 信息)。 @@ -111,7 +111,7 @@ CREATE TEXT SEARCH PARSER name ( headline_function - 该解析器的 headline 函数的名称(该函数对一组记号生成摘要)。 + 该解析器的 headline 函数的名称(该函数对一组词元生成摘要)。 diff --git a/zh/19/ref/create_tstemplate.sgml b/zh/19/ref/create_tstemplate.sgml index 702233e4..0f1b4e1a 100644 --- a/zh/19/ref/create_tstemplate.sgml +++ b/zh/19/ref/create_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH TEMPLATE - 定义一个新的全文检索模板 + 定义一个新的文本检索模板 @@ -33,22 +33,22 @@ CREATE TEXT SEARCH TEMPLATE name ( CREATE TEXT SEARCH TEMPLATE创建一个 - 新的全文检索模板。全文检索模板定义实现全文检索字典的函数。模板本身 - 并无直接用途,必须先实例化为字典后才能使用。字典通常会指定要传递给 + 新的文本检索模板。文本检索模板定义实现文本检索词典的函数。模板本身 + 并无直接用途,必须先实例化为词典后才能使用。词典通常会指定要传递给 模板函数的参数。 - 如果给出了模式名称,则全文检索模板会被创建在指定模式中。否则它会被 + 如果给出了模式名称,则文本检索模板会被创建在指定模式中。否则它会被 创建在当前模式中。 要使用CREATE TEXT SEARCH TEMPLATE,你 - 必须是超级用户。之所以有此限制,是因为错误的全文检索模板定义可能使 - 服务器陷入混乱,甚至崩溃。将模板与字典分离的原因在于,模板封装了定 - 义字典时那些不安全的方面。而在定义字典时可设置的参数, - 对非特权用户来说是安全的,因此创建字典不必是特权操作。 + 必须是超级用户。之所以有此限制,是因为错误的文本检索模板定义可能使 + 服务器陷入混乱,甚至崩溃。将模板与词典分离的原因在于,模板封装了定 + 义词典时那些不安全的方面。而在定义词典时可设置的参数, + 由普通用户设置也是安全的,因此创建词典不必是特权操作。 @@ -64,7 +64,7 @@ CREATE TEXT SEARCH TEMPLATE name ( name - 要创建的全文检索模板名称。该名称可以是模式限定的。 + 要创建的文本检索模板名称。该名称可以是模式限定的。 diff --git a/zh/19/ref/drop_opclass.sgml b/zh/19/ref/drop_opclass.sgml index ad861933..1110520c 100644 --- a/zh/19/ref/drop_opclass.sgml +++ b/zh/19/ref/drop_opclass.sgml @@ -110,7 +110,7 @@ DROP OPERATOR CLASS [ IF EXISTS ] name示例 - 移除 B-tree 操作符类widget_ops: + 移除 B-树操作符类widget_ops DROP OPERATOR CLASS widget_ops USING btree; diff --git a/zh/19/ref/drop_tsconfig.sgml b/zh/19/ref/drop_tsconfig.sgml index bf58e675..07af09ff 100644 --- a/zh/19/ref/drop_tsconfig.sgml +++ b/zh/19/ref/drop_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH CONFIGURATION - 移除一个文本搜索配置 + 移除一个文本检索配置 @@ -29,7 +29,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 描述 - DROP TEXT SEARCH CONFIGURATION删除一个现有文本搜索配置。 + DROP TEXT SEARCH CONFIGURATION删除一个现有文本检索配置。 要执行此命令,你必须是该配置的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name IF EXISTS - 如果该文本搜索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name name - 现有文本搜索配置的名称(可以被模式限定)。 + 现有文本检索配置的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name CASCADE - 自动删除依赖于该文本搜索配置的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索配置的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name RESTRICT - 如果有任何对象依赖于该文本搜索配置,则拒绝删除该配置。这是默认值。 + 如果有任何对象依赖于该文本检索配置,则拒绝删除该配置。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 示例 - 移除文本搜索配置my_english: + 移除文本检索配置my_english DROP TEXT SEARCH CONFIGURATION my_english; 如果已有索引在to_tsvector调用中引用了该配置, - 此命令将不会成功。加上CASCADE可以在删除该文本搜索配置的同时删除这类索引。 + 此命令将不会成功。加上CASCADE可以在删除该文本检索配置的同时删除这类索引。 diff --git a/zh/19/ref/drop_tsdictionary.sgml b/zh/19/ref/drop_tsdictionary.sgml index ff4362e2..e1d97e63 100644 --- a/zh/19/ref/drop_tsdictionary.sgml +++ b/zh/19/ref/drop_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH DICTIONARY - 移除一个文本搜索字典 + 移除一个文本检索词典 @@ -29,8 +29,8 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name描述 - DROP TEXT SEARCH DICTIONARY删除一个现有文本搜索字典。 - 要执行此命令,你必须是该字典的拥有者。 + DROP TEXT SEARCH DICTIONARY删除一个现有文本检索词典。 + 要执行此命令,你必须是该词典的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索字典不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索词典不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] namename - 一个现有文本搜索字典的名称(可以被模式限定)。 + 一个现有文本检索词典的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索字典的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索词典的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索字典,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索词典,则拒绝删除它。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name示例 - 移除文本搜索字典english: + 移除文本检索词典english DROP TEXT SEARCH DICTIONARY english; - 如果已有文本搜索配置使用该字典,此命令将不会成功。 - 加上CASCADE可以在删除字典的同时删除这类配置。 + 如果已有文本检索配置使用该词典,此命令将不会成功。 + 加上CASCADE可以在删除词典的同时删除这类配置。 diff --git a/zh/19/ref/drop_tsparser.sgml b/zh/19/ref/drop_tsparser.sgml index 592ce807..5aefba44 100644 --- a/zh/19/ref/drop_tsparser.sgml +++ b/zh/19/ref/drop_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH PARSER - 移除一个文本搜索解析器 + 移除一个文本检索解析器 @@ -29,7 +29,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name描述 - DROP TEXT SEARCH PARSER删除一个现有文本搜索解析器。 + DROP TEXT SEARCH PARSER删除一个现有文本检索解析器。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] namename - 一个现有文本搜索解析器的名称(可以被模式限定)。 + 一个现有文本检索解析器的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索解析器的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索解析器的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索解析器,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索解析器,则拒绝删除它。这是默认值。 @@ -82,13 +82,13 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name示例 - 移除文本搜索解析器my_parser: + 移除文本检索解析器my_parser DROP TEXT SEARCH PARSER my_parser; - 如果已有文本搜索配置使用该解析器,此命令将不会成功。 + 如果已有文本检索配置使用该解析器,此命令将不会成功。 加上CASCADE可以在删除解析器的同时删除这类配置。 diff --git a/zh/19/ref/drop_tstemplate.sgml b/zh/19/ref/drop_tstemplate.sgml index 1d05b98c..dea65084 100644 --- a/zh/19/ref/drop_tstemplate.sgml +++ b/zh/19/ref/drop_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH TEMPLATE - 移除一个文本搜索模板 + 移除一个文本检索模板 @@ -29,7 +29,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name描述 - DROP TEXT SEARCH TEMPLATE删除一个现有文本搜索模板。 + DROP TEXT SEARCH TEMPLATE删除一个现有文本检索模板。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] namename - 现有文本搜索模板的名称(可以被模式限定)。 + 现有文本检索模板的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索模板的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索模板的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索模板,则拒绝删除该模板。这是默认值。 + 如果有任何对象依赖于该文本检索模板,则拒绝删除该模板。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name示例 - 移除文本搜索模板thesaurus: + 移除文本检索模板thesaurus DROP TEXT SEARCH TEMPLATE thesaurus; - 如果已有文本搜索字典使用该模板,此命令将不会成功。加上CASCADE - 可以在删除该模板的同时删除这类字典。 + 如果已有文本检索词典使用该模板,此命令将不会成功。加上CASCADE + 可以在删除该模板的同时删除这类词典。 diff --git a/zh/19/ref/initdb.sgml b/zh/19/ref/initdb.sgml index efa40aa9..29fd5beb 100644 --- a/zh/19/ref/initdb.sgml +++ b/zh/19/ref/initdb.sgml @@ -327,7 +327,7 @@ PostgreSQL documentation - 设置默认文本搜索配置。更多信息见 + 设置默认文本检索配置。更多信息见 diff --git a/zh/19/ref/pgbench.sgml b/zh/19/ref/pgbench.sgml index 3fc38e07..ac39c5f5 100644 --- a/zh/19/ref/pgbench.sgml +++ b/zh/19/ref/pgbench.sgml @@ -39,7 +39,7 @@ PostgreSQL documentation 描述 - pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,必要时可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 + pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,也可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 @@ -69,7 +69,7 @@ tps = 896.967014 (without initial connection time) - 默认的类 TPC-B 事务测试要求预先建立特定的表。应使用(initialize)选项调用pgbench来创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: + 默认的类 TPC-B 事务测试要求预先建立特定的表。应使用(初始化)选项调用pgbench来创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: pgbench -i other-options dbname @@ -89,14 +89,14 @@ pgbench -i other-options 在默认的比例因子 1 下,这些表最初包含如下行数: -table # of rows +表 行数 --------------------------------- pgbench_branches 1 pgbench_tellers 10 pgbench_accounts 100000 pgbench_history 0 - 可以使用(比例因子)选项来增加行数,而且在大多数场景下也确实应该这样做。此时还可以配合使用(fillfactor)选项。 + 可以使用(比例因子)选项来增加行数,而且在大多数场景下通常也应该这样做。此时还可以配合使用(fillfactor)选项。 @@ -116,7 +116,7 @@ pgbench options d 选项 - 下面分成三个部分。数据库初始化期间使用的选项和运行基准时会使用不同的选项,但也有一些选项在两种情况下都使用。 + 以下内容分为三个小节。数据库初始化和运行基准测试时使用不同的选项,但有些选项在这两种情况下都适用。 @@ -196,7 +196,7 @@ pgbench options d 使用G(服务器端生成数据)时, pgbench客户端只发送较小的查询,随后实际数据在服务器端生成。 - 这种方式几乎不需要额外带宽,但服务器会承担更多工作。 + 这种方式不需要大量带宽,但服务器会承担更多工作。 使用G时,生成数据期间不会打印任何进度消息。 @@ -505,13 +505,13 @@ pgbench options d 用于向服务器提交查询的协议: - simple: 使用简单查询协议。 + simple:使用简单查询协议。 - extended: 使用扩展查询协议。 + extended:使用扩展查询协议。 - prepared: 使用带有预备语句的扩展查询协议。 + prepared:使用带有预备语句的扩展查询协议。 @@ -572,7 +572,7 @@ pgbench options d - 在基准测试完成后,报告每条语句的以下统计信息:平均延迟(从客户端视角看到的语句执行时间)、失败次数,以及该语句因串行化或死锁错误而发生的重试次数。仅当选项不等于 1 时,报告才会显示重试统计信息。 + 在基准测试完成后,报告每条命令的以下统计信息:平均延迟(从客户端视角看到的语句执行时间)、失败次数,以及该命令因串行化或死锁错误而发生的重试次数。仅当选项不等于 1 时,报告才会显示重试统计信息。 @@ -607,7 +607,7 @@ pgbench options d 较高的计划滞后时间表明,在所选客户端数和线程数下,系统无法以指定速率处理事务。 当平均事务执行时间长于事务之间的计划间隔时,后续事务会不断进一步落后, - 而计划滞后时间也会随着测试持续时间增加。在这种情况下,只能降低指定的事务速率。 + 而计划滞后时间也会随着测试持续时间增加。在这种情况下,需要降低指定的事务速率。 @@ -619,7 +619,7 @@ pgbench options d pgbench输出中报告指定的比例因子。 - 对于内置测试,这通常没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 + 对于内置测试,这没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 但在只测试自定义基准(选项)时, 除非使用此选项,否则比例因子会被报告为 1。 @@ -751,7 +751,7 @@ pgbench options d 启用对出现串行化/死锁错误的事务进行重试,并设置最大尝试次数。此选项可与 - 组合使用,后者限制所有事务尝试的总耗时; + 组合使用,后者限制同一事务所有尝试的总耗时; 此外,如果没有, 则不能使用无限次尝试(--max-tries=0)。 默认值为 1,出现串行化/死锁错误的事务不会重试。有关此类事务重试的更多信息,见 @@ -831,7 +831,7 @@ pgbench options d - 打印关于所有错误和失败的消息(即不会重试的错误),包括超出了哪一种重试限制,以及对于串行化/死锁失败超出的幅度。(请注意,这种情况下输出量可能会显著增加。)更多信息见。 + 打印关于所有错误和失败(不再重试的错误)的消息,包括超出了哪一种重试限制,以及对于串行化/死锁失败超出的幅度。(请注意,这种情况下输出量可能会显著增加。)更多信息见 @@ -959,7 +959,7 @@ pgbench options d 注解 - + 在<application>pgbench</application>中实际执行的<quote>事务</quote>是什么? @@ -1014,7 +1014,7 @@ pgbench options d - 假定pgbench脚本不包含不完整的 SQL 事务块。如果在运行时客户端在尚未完成最后一个事务块时就到达脚本末尾,它将被中止。 + 假定pgbench脚本不包含不完整的 SQL 事务块。如果在运行时客户端在尚未完成最后一个事务块时就到达脚本末尾,该客户端将被中止。 @@ -1051,7 +1051,7 @@ pgbench options d default_seed - 默认在哈希和伪随机置换函数中使用的种子 + 默认在 hash 和伪随机置换函数中使用的种子 @@ -1068,7 +1068,7 @@ pgbench options d - 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令及其参数之间以空白分隔。支持的元命令如下: + 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令的参数以空白分隔。支持的元命令如下: @@ -1104,7 +1104,7 @@ UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid RETURNING abalance \gset --- compound of two queries +-- 两个查询的组合 SELECT 1 \; SELECT 2 AS two, 3 AS three \gset p_ SELECT 4 AS four \; SELECT 5 AS five \aset @@ -1196,7 +1196,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset - command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在其开头再写一个冒号。 + command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在argument开头再写一个冒号。 @@ -1234,7 +1234,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset - 这组命令用于实现 SQL 语句的流水线执行。流水线必须以\startpipeline开始,并以\endpipeline结束;在两者之间可以出现任意数量的\syncpipeline,它会发送一个sync 消息,但不会结束当前流水线,同时会刷新发送缓冲区。在流水线模式下,语句会发送到服务器,而不等待前一条语句的结果。更多细节见。流水线模式要求使用扩展查询协议。 + 这组命令用于实现 SQL 语句的管道执行。管道必须以\startpipeline开始,并以\endpipeline结束;在两者之间可以出现任意数量的\syncpipeline,它会发送一个sync 消息,既不会结束当前管道,也不会刷新发送缓冲区。在管道模式下,语句会发送到服务器,而不等待前一条语句的结果。更多细节见。管道模式要求使用扩展查询协议。 @@ -1530,7 +1530,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 加 + 加法 5 + 4 @@ -1544,7 +1544,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 减 + 减法 3 - 2.0 @@ -1558,7 +1558,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 乘 + 乘法 5 * 4 @@ -1572,7 +1572,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 除法(如果两个输入都是整数,则将结果截断为零) + 除法(如果两个输入都是整数,则将结果向零截断) 5 / 3 @@ -1600,7 +1600,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 取反 + 取相反数 - 2.0 @@ -1690,7 +1690,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset double - 指数(e 的给定次幂) + 指数函数(e 的给定次幂) exp(1.0) @@ -1732,7 +1732,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算 FNV-1a 哈希。 + 计算 FNV-1a hash hash_fnv1a(10, 5432) @@ -1746,7 +1746,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算 MurmurHash2 哈希。 + 计算 MurmurHash2 hash hash_murmur2(10, 5432) @@ -1816,8 +1816,8 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - i的排列值,范围在[0, size)内。 - 它表示i(模size)在整数0...size-1的伪随机排列中的新位置;该排列由seed参数化,详见下文。 + i的置换值,范围在[0, size)内。 + 它表示i(模size)在整数0...size-1的伪随机置换中的新位置;该置换由seed参数化,详见下文。 permute(0, 4) @@ -1877,7 +1877,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算[lb, ub]中的指数分布随机整数,如下所示。 + 计算[lb, ub]中的指数分布随机整数,详见下文。 random_exponential(1, 10, 3.0) @@ -1891,7 +1891,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算[lb, ub]中的高斯分布随机整数,如下所示。 + 计算[lb, ub]中的高斯分布随机整数,详见下文。 random_gaussian(1, 10, 2.5) @@ -1938,7 +1938,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset - 对于指数分布,parameter通过在parameter处截断一个快速衰减的指数分布,再将其投影到边界之间的整数上,从而控制分布。准确地说, + 对于指数分布,parameter通过在parameter处截断一个快速衰减的指数分布,再将其投影到边界之间的整数上,从而控制分布。准确地说,令 f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) @@ -1946,7 +1946,7 @@ f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) - 直观地说,parameter越大,越靠近min的值越容易被抽到,而越靠近max的值越不容易被抽到。parameter越接近 0,分布就越平坦(也就越均匀)。对这种分布的一个粗略近似是:范围内最靠近min的那 1% 常见值,大约会占到parameter% 的抽样次数。parameter必须严格大于 0。 + 直观地说,parameter越大,越靠近min的值越容易被抽到,而越靠近max的值越不容易被抽到。parameter越接近 0,分布就越平坦(也就越均匀)。对这种分布的一个粗略近似是:范围内出现频率最高的 1% 的值,即最靠近min的那些值,大约会占到parameter% 的抽样次数。parameter必须严格大于 0。 @@ -1958,7 +1958,7 @@ f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / (2.0 * PHI(parameter) - 1) - 则minmax(包含边界)之间的值i被抽中的概率为:f(i + 0.5) - f(i - 0.5)。直观地说,parameter越大,越靠近区间中间的值被抽到的频率越高,而越靠近minmax边界的值被抽到的频率越低。大约 67% 的值会落在区间中部1.0 / parameter这一段内,也就是均值两侧各0.5 / parameter的范围内;约 95% 的值会落在区间中部2.0 / parameter这一段内,也就是均值两侧各1.0 / parameter的范围内。例如,如果parameter为 4.0,则 67% 的值会落在区间中间四分之一(1.0 / 4.0)内,也就是从3.0 / 8.05.0 / 8.0;95% 的值会落在区间中间一半(2.0 / 4.0)内,也就是第二和第三四分位。允许的最小parameter值为 2.0。 + 则minmax(包含边界)之间的值i被抽中的概率为:f(i + 0.5) - f(i - 0.5)。直观地说,parameter越大,越靠近区间中间的值被抽到的频率越高,而越靠近minmax边界的值被抽到的频率越低。大约 67% 的值会落在区间中部1.0 / parameter这一段内,也就是均值两侧各占区间长度0.5 / parameter的范围内;约 95% 的值会落在区间中部2.0 / parameter这一段内,也就是均值两侧各占区间长度1.0 / parameter的范围内。例如,如果parameter为 4.0,则 67% 的值会落在区间中间四分之一(1.0 / 4.0)内,也就是从3.0 / 8.05.0 / 8.0;95% 的值会落在区间中间一半(2.0 / 4.0)内,也就是第二和第三四分位。允许的最小parameter值为 2.0。 @@ -1990,12 +1990,12 @@ f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / - 哈希函数hashhash_murmur2hash_fnv1a都接受一个输入值和一个可选的种子参数。 - 如果没有提供种子,则会使用:default_seed的值;除非通过命令行选项覆盖,否则该值会被随机初始化。 + Hash 函数hashhash_murmur2hash_fnv1a都接受一个输入值和一个可选的种子参数。 + 如果没有提供种子,则会使用:default_seed的值;除非通过命令行-D选项覆盖,否则该值会被随机初始化。 - permute接受一个输入值、一个大小参数以及一个可选的种子参数。它会生成范围[0, size)内整数的伪随机排列,并返回输入值在该排列中的索引。如果未指定种子,则默认使用:default_seed。与哈希函数不同,permute保证输出值中不会出现冲突或空洞。区间之外的输入值会按size取模解释。如果size不是正数,该函数会报错。permute可用于打散诸如random_zipfianrandom_exponential这类非均匀随机函数的分布,使那些更常抽到的值不再具有显而易见的相关性。例如,下面的pgbench脚本模拟了社交媒体和博客平台中一种可能的真实工作负载,其中少数账户会产生过量负载: + permute接受一个输入值、一个大小参数以及一个可选的种子参数。它会生成范围[0, size)内整数的伪随机置换,并返回输入值在该置换中的索引。所选置换由种子参数决定;如果未指定种子,则默认使用:default_seed。与 hash 函数不同,permute保证输出值中不会出现冲突或空洞。区间之外的输入值会按size取模解释。如果size不是正数,该函数会报错。permute可用于打散诸如random_zipfianrandom_exponential这类非均匀随机函数的分布,使那些更常抽到的值不再具有显而易见的相关性。例如,下面的pgbench脚本模拟了社交媒体和博客平台中一种可能的真实工作负载,其中少数账户会产生过量负载: \set size 1000000 @@ -2052,7 +2052,7 @@ END; - 每行日志文件描述一个事务。 + 日志文件的每一行描述一个事务。 它包含以下以空格分隔的字段: @@ -2462,7 +2462,7 @@ statement latencies in milliseconds and failures: 使用可串行化默认事务隔离级别的默认脚本的另一个输出示例 - (PGOPTIONS='-c default_transaction_isolation=serializable' pgbench ...): + (PGOPTIONS='-c default_transaction_isolation=serializable' pgbench ...): starting vacuum...end. transaction type: <builtin: TPC-B (sort of)> @@ -2505,7 +2505,7 @@ statement latencies in milliseconds, failures and retries: - + 失败和串行化/死锁重试 @@ -2564,7 +2564,7 @@ statement latencies in milliseconds, failures and retries: - 不指定选项时,事务在发生串行化或死锁错误后永远不会重试,因为其默认值为 1。可以使用无限次尝试(--max-tries=0)并配合选项,仅限制重试的最长时间。也可以使用选项,在无限次尝试的情况下限制基准测试持续时间。 + 不指定选项时,事务在发生串行化或死锁错误后永远不会重试,因为其默认值为 1。可以使用无限次尝试(--max-tries=0)并配合选项,仅限制尝试的最长总时间。也可以使用选项,在无限次尝试的情况下限制基准测试持续时间。 @@ -2585,7 +2585,7 @@ statement latencies in milliseconds, failures and retries: - 如果希望在逐事务日志、聚合日志以及主报告和逐脚本报告中按基本类型对失败进行分组,请使用选项。如果还希望按类型区分所有错误和失败(即不会重试的错误),包括超出了哪一种重试限制,以及串行化/死锁失败超出了多少,请使用选项。 + 如果希望在逐事务日志、聚合日志以及主报告和逐脚本报告中按基本类型对失败进行分组,请使用选项。如果还希望按类型区分所有错误和失败(不再重试的错误),包括超出了哪一种重试限制,以及串行化/死锁失败超出了多少,请使用选项。 @@ -2617,7 +2617,7 @@ PGOPTIONS='-c default_table_access_method=wuzza' - 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和空闲空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 + 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和无效空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 diff --git a/zh/19/ref/psql-ref.sgml b/zh/19/ref/psql-ref.sgml index 552af7fb..e5e2e28a 100644 --- a/zh/19/ref/psql-ref.sgml +++ b/zh/19/ref/psql-ref.sgml @@ -47,7 +47,7 @@ PostgreSQL documentation - 把所有非空输入行按照它们被读入的形式打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 + 在读入时将所有非空输入行打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 all @@ -58,7 +58,7 @@ PostgreSQL documentation - 切换到非对齐输出模式(默认输出模式是对齐的)。这等效于\pset format unaligned。 + 切换到非对齐输出模式(默认输出模式是aligned)。这等效于\pset format unaligned @@ -78,10 +78,10 @@ PostgreSQL documentation - 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,直到它处理完序列中所有的选项之后终止。 + 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,而是在按顺序处理完所有选项后终止。 - command必须是一个服务器完全可解析的命令字符串(即不包含psql相关的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: + command必须是一个服务器完全可解析的命令字符串(即不包含psql专有的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: psql -c '\x' -c 'SELECT * FROM foo;' @@ -172,7 +172,7 @@ EOF - 使用separator作为非对齐输出的域分隔符。这等效于\pset fieldsep或者\f。 + 使用separator作为非对齐输出的字段分隔符。这等效于\pset fieldsep或者\f @@ -246,7 +246,7 @@ EOF - 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。 + 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展名。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。 @@ -266,7 +266,7 @@ EOF - 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息以及多种输出。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon。 + 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息和各种提示信息。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon @@ -286,7 +286,7 @@ EOF - 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户一个可以取消执行的选项。使用这个选项可以调试脚本。 + 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户,并允许取消执行。使用这个选项可以调试脚本。 @@ -296,7 +296,7 @@ EOF - 运行在单行模式中,其中新行会终止一个 SQL 命令,就像分号的作用一样。 + 运行在单行模式中,其中换行符会终止一个 SQL 命令,就像分号的作用一样。 @@ -322,7 +322,7 @@ EOF - 指定要替换HTML table标签的选项。详见\pset tableattr。 + 指定要放在HTML table标签内的选项。详见\pset tableattr @@ -343,7 +343,7 @@ EOF - 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要重置一个变量,去掉等号就行。要把一个变量置为空值,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 + 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要取消变量的设置,去掉等号就行。要把一个变量设为空字符串,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 @@ -405,7 +405,7 @@ EOF - 不读取启动文件(要么是系统范围的psqlrc文件,要么是用户的~/.psqlrc文件)。 + 不读取启动文件(既不读取系统范围的psqlrc文件,也不读取用户的~/.psqlrc文件)。 @@ -415,7 +415,7 @@ EOF - 设置非对齐输出的域分隔符为零字节。这等效于\pset fieldsep_zero。 + 设置非对齐输出的字段分隔符为零字节。这等效于\pset fieldsep_zero @@ -425,7 +425,7 @@ EOF - 设置非对齐输出的记录分隔符为零字节。例如,这对与xargs -0配合有关。这等效于\pset recordsep_zero。 + 设置非对齐输出的记录分隔符为零字节。例如,这有助于与xargs -0配合使用。这等效于\pset recordsep_zero @@ -438,7 +438,7 @@ EOF 这个选项只能与一个或多个和/或选项结合使用。 它会导致psql在第一个这样的选项之前发出一个BEGIN命令, 并在最后一个选项之后发出一个COMMIT命令,从而将所有命令包装成一个单独的事务。 - 如果任何命令失败且变量ON_ERROR_STOP被设置,那么会发送一个ROLLBACK命令。 + 如果任何命令失败且变量ON_ERROR_STOP被设置,则会改为发送一个ROLLBACK命令。 这确保要么所有命令都成功完成,要么不应用任何更改。 @@ -550,7 +550,7 @@ testdb=> 元命令 - 你输入到psql中的任何以未加引用的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 + 你输入到psql中的任何以未加引号的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 @@ -567,7 +567,7 @@ testdb=> - 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉尾随换行)会替换反引号中的文本。在反引号包围的文本内部,不会发生特殊引用或其他处理,只有一种例外:如果出现:variable_name,且variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会被适当地引用成单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于回车和换行字符在所有平台上都无法安全引用,当变量值中出现这类字符时,:'variable_name'这种形式会打印错误消息,并且不会替换变量值。 + 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉末尾的换行符)会替换反引号中的文本。在反引号包围的文本内部,不会进行特殊的引号处理或其他处理,但出现:variable_name时,如果variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会适当地加上引号,使其成为单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于无法保证在所有平台上都能对回车和换行字符安全地加引号,当变量值中出现这类字符时,:'variable_name'形式会打印错误消息,并且不会替换变量值。 @@ -579,8 +579,8 @@ testdb=> - 很多元命令作用在当前查询缓冲区上。这就是一个缓冲区而已,它保存任何已经被键入但是还没有发送到服务器执行的SQL命令文本。这将包括之前输入的行以及在该元命令同一行上出现在前面的任何文本。 - + 许多元命令作用于当前查询缓冲区。这只是一个保存已输入但尚未发送到服务器执行的 SQL 命令文本的缓冲区。其中既包括先前输入的行,也包括同一行上位于元命令之前的文本。 + 许多元命令还允许在命令名后追加 x 作为选项。这会使结果以扩展模式显示,就像使用了 \x\pset expanded 一样。 @@ -594,7 +594,7 @@ testdb=> \a - 如果当前表格输出格式是不对齐,则切换为对齐;否则切换为不对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset。 + 如果当前表格输出格式是非对齐,则切换为对齐;否则切换为非对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset @@ -654,7 +654,7 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1 \c\connect [ -reuse-previous=on|off ] [ dbname [ username ] [ host ] [ port ] | conninfo ] - 建立到PostgreSQL服务器的新连接。可以使用位置语法(数据库名称、用户、主机和端口中的一个或多个)指定要使用的连接参数,也可以使用详细说明在中的conninfo连接字符串。如果没有给出参数,则使用与之前相同的参数建立新连接。 + 建立到PostgreSQL服务器的新连接。可以使用位置语法(数据库名称、用户、主机和端口中的一个或多个)指定要使用的连接参数,也可以使用conninfo连接字符串,详见。如果没有给出参数,则使用与之前相同的参数建立新连接。 @@ -670,7 +670,7 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1 默认情况下,参数在位置语法中被重用,但在给定conninfo字符串时不会被重用。 传递-reuse-previous=on-reuse-previous=off作为第一个参数将覆盖该默认设置。 如果参数被重用,则任何未明确指定为位置参数或在conninfo字符串中的参数将从现有连接的参数中获取。 - 一个例外是,如果使用位置语法将host设置更改为其先前值,则现有连接参数中存在的任何hostaddr设置将被删除。 + 一个例外是,如果使用位置语法更改host设置,使其不同于先前的值,则现有连接参数中存在的任何hostaddr设置将被删除。 此外,仅当用户、主机和端口设置未更改时,才会重用现有连接使用的任何密码。 当命令既不指定也不重用特定参数时,将使用libpq的默认值。 @@ -692,7 +692,7 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1 => \c mydb myuser host.dom 6432 => \c service=foo => \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable" -=> \c -reuse-previous=on sslmode=require -- changes only sslmode +=> \c -reuse-previous=on sslmode=require -- 仅更改 sslmode => \c postgresql://tom@localhost/mydb?application_name=myapp @@ -702,11 +702,8 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1 \C [ title ] - 设置作为查询结果打印的任何表格的标题,或取消任何这样的标题。此命令等效于 - \pset title title。(此命令的名称源自caption, - 因为它以前仅用于设置HTML表格中的标题。) - + 设置作为查询结果打印的表的标题,或取消此类标题。该命令等价于\pset title title。(此命令的名称源自caption,因为它过去只用于设置HTML表的标题。) + @@ -731,7 +728,7 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1 - 关闭指定的预备语句。空字符串表示未命名的预备语句。如果不存在该名称的预备语句,则该操作不执行任何操作。 + 关闭指定的预备语句。空字符串表示未命名的预备语句。如果不存在该名称的预备语句,则不执行任何操作。 @@ -836,46 +833,24 @@ SELECT $1 \parse stmt1 ] ] ] ] - 执行当前查询缓冲区(类似于\g)并在交叉表格中显示结果。 - 查询必须返回至少三列。 - 由colV标识的输出列成为垂直标题, - 由colH标识的输出列成为水平标题。 - colD标识要在网格中显示的输出列。 - sortcolH标识水平标题的可选排序列。 - + 执行当前查询缓冲区(与\g类似),并以交叉表网格显示结果。查询必须返回至少三列。由colV标识的输出列成为纵向表头,由colH标识的输出列成为横向表头。colD标识要在网格中显示的输出列。sortcolH标识横向表头的可选排序列。 + - 每个列规范可以是列号(从1开始)或列名。列名遵循通常的SQL大小写折叠和引用规则。如果省略, - colV被视为第1列, - colH被视为第2列。 - colH必须与 - colV不同。 - 如果未指定colD,则查询结果中必须恰好有三列, - 并且既不是colV也不是 - colH的列被视为 - colD。 - + 每个列指定都可以是列号(从 1 开始)或列名。通常的 SQL 大小写折叠和加引号规则适用于列名。如果省略,colV取第 1 列,colH取第 2 列。colH必须不同于colV。如果未指定colD,查询结果必须恰好有三列,既不是colV也不是colH的那一列被用作colD。 + - 垂直标题显示为最左侧的列,包含在列colV中找到的值, - 与查询结果中的顺序相同,但删除了重复项。 - + 纵向表头显示为最左列,包含colV列中的值,其顺序与查询结果中相同,但会移除重复值。 + - 水平标题作为第一行显示,包含在列colH中找到的值,去除重复项。 - 默认情况下,这些值按照查询结果中的顺序显示。但是,如果给定可选的sortcolH参数, - 它标识一个列,其值必须是整数,colH中的值将按照相应的 - sortcolH值排序后显示在水平标题中。 - + 横向表头显示为第一行,包含colH列中的值,并移除重复值。默认情况下,它们按查询结果中的相同顺序显示。但如果给出了可选的sortcolH参数,它所标识的列的值必须是整数,而colH中的值会按照对应的sortcolH值排序后显示在横向表头中。 + - 在交叉表格中,对于每个colH列的非重复值x, - 和每个colV列的非重复值y, - 位于交点(x,y)的单元格包含查询结果行中colD列的值, - 其中colH列的值为x, - colV列的值为y。 - 如果没有这样的行,则单元格为空。如果有多个这样的行,则报告错误。 - + 在交叉表网格中,对于colH中的每个不同值xcolV中的每个不同值y,交点(x,y)处的单元格包含查询结果中colD列的值,该结果行的colH值为xcolV值为y。如果没有这样的行,单元格为空。如果存在多条这样的行,则报错。 + @@ -897,11 +872,7 @@ SELECT $1 \parse stmt1 - 命令形式\d+与前者相同,只是会显示更多信息:例如,显示与表列相关的任何注释, - 表中 OID 的存在情况,如果关系是视图,则显示视图定义,非默认的 - 复制标识设置以及 - 如果关系具有访问方法,则显示 - 访问方法名称。 + 命令形式\d+与前者相同,但会显示更多信息,例如:表列关联的注释、表是否包含 OID、当关系为视图时的视图定义、非默认的复制标识设置,以及当关系具有访问方法时的访问方法名称。 @@ -1048,7 +1019,7 @@ SELECT $1 \parse stmt1 显示constraintoperator classoperator familyrule和 - trigger类型对象的描述。所有其他注释可以通过相应的反斜杠命令查看这些对象类型。 + trigger类型对象的描述。其他注释可通过对应对象类型的反斜线命令查看。 \dd 显示与 @@ -1163,7 +1134,7 @@ SELECT $1 \parse stmt1 列出函数,以及它们的结果数据类型、参数数据类型和函数类型,函数类型分为 agg(聚合)、normalproceduretriggerwindow。要只显示特定类型的函数,请在命令后添加相应的字母 anptw。如果指定了 pattern,则只显示名称与模式匹配的函数。任何附加参数都是类型名模式,分别与函数第一、第二等参数的类型名匹配。(匹配到的函数可以比你指定的参数更多;若要防止这种情况,可将破折号 - 写成最后一个 arg_pattern。)默认情况下,只显示用户创建的对象;提供模式或 S + class="parameter">pattern,则只显示名称与模式匹配的函数。任何附加参数都是类型名模式,分别与函数第一、第二等参数的类型名匹配。(匹配到的函数可以比你指定的参数更多;若要防止这种情况,可将连字符 - 写成最后一个 arg_pattern。)默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个函数的附加信息,包括易变性、并行安全性、所有者、安全分类、是否防漏、访问权限、语言、内部名称(仅适用于 C 和 internal 函数)以及描述。特定函数的源代码可通过 \sf 查看。 @@ -1174,7 +1145,7 @@ SELECT $1 \parse stmt1 \dF[x+] [ pattern ] - 列出文本搜索配置。如果指定了 pattern,则只显示名称与模式匹配的配置。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个配置的完整描述,包括底层文本搜索解析器以及每种记号类型对应的词典列表。 + 列出全文检索配置。如果指定了 pattern,则只显示名称与模式匹配的配置。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个配置的完整描述,包括底层全文检索解析器以及每种解析器词元类型对应的词典列表。 @@ -1183,7 +1154,7 @@ SELECT $1 \parse stmt1 \dFd[x+] [ pattern ] - 列出文本搜索词典。如果指定了 pattern,则只显示名称与模式匹配的词典。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个所选词典的附加信息,包括底层文本搜索模板和选项值。 + 列出全文检索词典。如果指定了 pattern,则只显示名称与模式匹配的词典。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个所选词典的附加信息,包括底层全文检索模板和选项值。 @@ -1192,7 +1163,7 @@ SELECT $1 \parse stmt1 \dFp[x+] [ pattern ] - 列出文本搜索解析器。如果指定了 pattern,则只显示名称与模式匹配的解析器。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个解析器的完整描述,包括底层函数和已识别的记号类型列表。 + 列出全文检索解析器。如果指定了 pattern,则只显示名称与模式匹配的解析器。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个解析器的完整描述,包括底层函数和可识别的词元类型列表。 @@ -1201,7 +1172,7 @@ SELECT $1 \parse stmt1 \dFt[x+] [ pattern ] - 列出文本搜索模板。如果指定了 pattern,则只显示名称与模式匹配的模板。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个模板的附加信息,包括底层函数名。 + 列出全文检索模板。如果指定了 pattern,则只显示名称与模式匹配的模板。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个模板的附加信息,包括底层函数名。 @@ -1211,7 +1182,7 @@ SELECT $1 \parse stmt1 \dg[Sx+] [ pattern ] - 列出数据库角色。(由于 usersgroups 的概念已经统一为 roles,此命令现在等同于 + 列出数据库角色。(由于 用户的概念已经统一为角色,此命令现在等同于 \du。)默认情况下,只显示用户创建的角色;提供 S 修饰符可包括系统角色。如果指定了 pattern,则只列出名称与模式匹配的角色。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个角色的附加信息;目前这会增加每个角色的注释。 @@ -1316,9 +1287,7 @@ SELECT $1 \parse stmt1 \drds[x] [ role-pattern [ database-pattern ] ] - 列出已定义的配置设置。这些设置可以是特定于角色、特定于数据库,或者两者兼有。role-pattern 和 - database-pattern 分别用于选择要列出的特定角色和数据库。如果省略,或者指定了 - *,则会列出所有设置,包括那些未指定角色或数据库的设置。如果在命令名后追加 x,结果会以扩展模式显示。 + 列出已定义的配置设置。这些设置可以特定于角色、特定于数据库,或同时特定于两者。role-patterndatabase-pattern分别用于选择要列出的角色和数据库。省略某个模式参数或将其指定为*时,不会按该参数筛选,还会分别包含不特定于角色或不特定于数据库的设置。如果在命令名后追加x,结果会以扩展模式显示。 @@ -1340,7 +1309,7 @@ SELECT $1 \parse stmt1 默认情况下,只显示授予用户创建角色的成员身份;提供 - S 修饰符可包括系统角色。如果指定了 pattern,则只列出名称与模式匹配的角色。如果在命令名后追加 x,结果会以扩展模式显示。 + S 修饰符可包括系统角色。如果指定了 pattern,则只列出授予名称与模式匹配的角色的成员身份。如果在命令名后追加 x,结果会以扩展模式显示。 @@ -1368,7 +1337,7 @@ SELECT $1 \parse stmt1 \dT[Sx+] [ pattern ] - 列出数据类型。如果指定了 pattern,则只列出名称与模式匹配的类型。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则每个类型都会连同其内部名称和大小一起列出;对于 enum 类型,还会显示其允许值以及相关权限。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 + 列出数据类型。如果指定了 pattern,则只列出名称与模式匹配的类型。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则每个类型都会连同其内部名称、大小和相关权限一起列出;对于 enum 类型,还会显示其允许值。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 @@ -1377,7 +1346,7 @@ SELECT $1 \parse stmt1 \du[Sx+] [ pattern ] - 列出数据库角色。(由于 usersgroups 的概念已经统一为 roles,此命令现在等同于 + 列出数据库角色。(由于 用户的概念已经统一为角色,此命令现在等同于 \dg。)默认情况下,只显示用户创建的角色;提供 S 修饰符可包括系统角色。如果指定了 pattern,则只列出名称与模式匹配的角色。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个角色的附加信息;目前这会增加每个角色的注释。 @@ -1418,7 +1387,7 @@ SELECT $1 \parse stmt1 - \e\edit filename 行号 + \e\edit filename line_number @@ -1430,7 +1399,7 @@ SELECT $1 \parse stmt1 如果编辑文件或上一个查询后在未修改文件的情况下退出编辑器,则查询缓冲区将被清除。 否则,查询缓冲区的新内容将根据psql的正常规则重新解析, - 将整个缓冲区视为单行。任何完整的查询将立即执行;也就是说,如果查询缓冲区包含或以分号结尾, + 将整个缓冲区视为单行。任何完整的查询将立即执行;也就是说,如果查询缓冲区包含分号或以分号结尾, 则执行并从查询缓冲区中删除到该点的所有内容。查询缓冲区中剩余的内容将重新显示。 输入分号或\g发送它,或输入\r通过清除查询缓冲区来取消。 @@ -1442,7 +1411,7 @@ SELECT $1 \parse stmt1 如果指定了行号,psql将光标定位在文件或查询缓冲区的指定行上。 - 请注意,如果给出一个全是数字的参数, + 请注意,如果只给出一个全是数字的参数, psql会假定它是一个行号,而不是文件名。 @@ -1457,14 +1426,10 @@ SELECT $1 \parse stmt1 \echo text [ ... ] - - 将求值后的参数打印到标准输出,用空格分隔,并在末尾加上换行符。这对于在脚本输出中穿插信息很有用。例如: - + 将求值后的参数打印到标准输出,用空格分隔,并在末尾加上换行符。这对于在脚本输出中穿插信息很有用。例如: => \echo `date` Tue Oct 26 21:40:57 CEST 1999 - - 如果第一个参数是未引用的-n,则不会写入尾随的换行符(也不会写入第一个参数)。 - +如果第一个参数是未加引号的-n,则不会写入尾随的换行符(也不会写入第一个参数)。 @@ -1572,7 +1537,7 @@ Tue Oct 26 21:40:57 CEST 1999 - 设置未对齐查询输出的字段分隔符。默认值是竖线(|)。 + 设置非对齐查询输出的字段分隔符。默认值是竖线(|)。 它等同于\pset fieldsep @@ -1583,25 +1548,17 @@ Tue Oct 26 21:40:57 CEST 1999 \g [ (option=value [...]) ] [ filename ] \g [ (option=value [...]) ] [ |command ] - - 将当前查询缓冲区发送到服务器以执行。 - - - 如果在\g后面出现括号,则括号中包围着一个空格分隔的option=value格式选项子句的列表,这些选项子句的解释方式与\psetoptionvalue命令相同,但仅在此查询的持续时间内生效。在此列表中,不允许在=符号周围有空格,但在选项子句之间需要空格。 - 如果省略了=value,则命名的option将以与\psetoption没有显式value时相同的方式更改。 - - - 如果提供了一个filename|command参数, - 查询的输出将被写入到指定的文件或通过给定的shell命令进行传输,而不是像通常那样显示出来。只有在查询成功返回零个或多个元组时,文件或命令才会被写入,而不是在查询失败或是非数据返回的SQL命令时。 + 将当前查询缓冲区发送给服务器执行。 + 如果在\g后面出现括号,则括号中是用空格分隔的option=value格式选项子句列表。这些子句的解释方式与\pset + option + value命令相同,但仅在此查询执行期间生效。在此列表中,=符号周围不允许有空格,但选项子句之间必须有空格。如果=value被省略,则指定的option会按以下命令的方式更改:\pset option,其中不显式指定value + 如果给出了filename|command参数,查询输出就会写入指定文件,或通过管道传给指定的 shell 命令,而不是照常显示。只有当查询成功返回零个或多个元组时,才会向文件或命令写入;如果查询失败,或执行的是不返回数据的 SQL 命令,则不会写入。 如果当前查询缓冲区为空,则最近发送的查询将被重新执行。除此之外,没有任何参数的\g基本上等同于一个分号。 带有参数的\g提供了一个一次性替代\o命令的选择,并且还允许一次性调整通常由\pset设置的输出格式选项。 - - 当最后一个参数以|开头时,整行剩余部分被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分将被直接传递给shell。 - + 当最后一个参数以|开头时,该行剩余的全部内容都会被视为要执行的command,其中既不进行变量插值,也不进行反引号扩展。该行剩余部分会直接按字面传给 shell。 @@ -1610,14 +1567,9 @@ Tue Oct 26 21:40:57 CEST 1999 \gdesc - - 显示当前查询缓冲区结果的描述(即列名和数据类型)。 - 查询不会实际执行;但是,如果包含某种语法错误,该错误将以正常方式报告。 - + 显示当前查询缓冲区中查询结果的描述(即列名和数据类型)。查询并不会实际执行;不过,如果其中存在语法错误,会按通常的方式报告。 - - 如果当前查询缓冲区为空,则描述最近发送的查询。 - + 如果当前查询缓冲区为空,则改为描述最近发送的查询。 @@ -1672,37 +1624,23 @@ CREATE INDEX \gset [ prefix ] - - 将当前查询缓冲区发送到服务器,并将查询的输出存储到psql变量中 - (参见下面的)。 - 要执行的查询必须返回一行。该行的每一列都存储在一个单独的变量中,变量名与列名相同。例如: - + 将当前查询缓冲区发送给服务器,并将查询输出存入 psql 变量(参见下面的)。要执行的查询必须恰好返回一行。该行的每一列分别存入一个变量,变量名与列名相同。例如: => SELECT 'hello' AS var1, 10 AS var2 -> \gset => \echo :var1 :var2 hello 10 - - 如果指定了一个prefix, - 该字符串将被添加到查询的列名前,以创建要使用的变量名: - + 如果指定了prefix,则会将该字符串加到查询的列名前面,以构成要使用的变量名: => SELECT 'hello' AS var1, 10 AS var2 -> \gset result_ => \echo :result_var1 :result_var2 hello 10 - - 如果列的结果为NULL,则相应的变量将被取消设置,而不是被设置。 - - - 如果查询失败或者没有返回一行结果, - 则不会改变任何变量。 - - - 如果当前查询缓冲区为空,则重新执行最近发送的查询。 - + 如果某一列的结果为 NULL,则取消设置对应的变量,而不是设置它。 + 如果查询失败或没有恰好返回一行,则不会更改任何变量。 + 如果当前查询缓冲区为空,则改为重新执行最近发送的查询。 @@ -1725,7 +1663,7 @@ hello 10 给出指定SQL命令的语法帮助。如果未指定command, 则psql将列出所有可用语法帮助的命令。如果command是星号 - (*),则显示所有SQL命令的语法帮助。 + (*),则显示所有SQL命令的语法帮助。 @@ -1746,9 +1684,7 @@ hello 10 \H\html - 打开HTML查询输出格式。如果HTML格式已经打开, - 则切换回默认的对齐文本格式。此命令用于兼容性和便利性,但请参阅\pset - 有关设置其他输出选项。 + 打开HTML查询输出格式。如果HTML格式已经打开,则切换回默认的对齐文本格式。此命令是为兼容性和便利性而保留的;设置其他输出选项的方法见\pset @@ -1760,13 +1696,10 @@ hello 10 - 从文件filename中读取输入,并将其执行为 - 好像它是在键盘上键入的一样。 + 从文件filename中读取输入,并像在键盘上输入一样执行它。 - 如果filename- - (连字符),那么标准输入将被读取,直到EOF指示或\q元命令。 - 这可用于将交互式输入与文件输入交错使用。请注意,仅当在最外层级别处于活动状态时,Readline行为才会被使用。 + 如果filename-(连字符),则从标准输入读取,直到遇到 EOF 指示或\q元命令。这可用于将交互式输入与文件输入交错使用。请注意,只有在最外层启用了 Readline,此处才会使用 Readline 功能。 @@ -1786,42 +1719,26 @@ hello 10 这组命令实现了可嵌套的条件块。条件块必须以\if开始,并以\endif结束。 在两者之间可以有任意数量的\elif子句,后面可以选择性地跟着一个\else子句。 - 在形成条件块的命令之间通常会出现普通查询和其他类型的反斜杠命令。 + 在形成条件块的命令之间通常会出现普通查询和其他类型的反斜线命令。 - \if\elif命令读取它们的参数,并将其作为布尔表达式进行评估。 - 如果表达式为true,则处理将继续进行;否则,直到达到匹配的\elif、 - \else\endif为止,将跳过行。一旦\if或 - \elif测试成功,同一块中后续\elif命令的参数不会被评估,而是被视为false。 - 在\else之后的行只有在没有早期匹配的\if\elif成功时才会被处理。 + \if\elif命令读取其参数,并将其作为布尔表达式求值。如果表达式的值为true,则正常继续处理;否则,跳过后续行,直到遇到匹配的\elif\else\endif。一旦\if\elif测试成功,同一块中后续\elif命令的参数就不再求值,而是被视为假。只有前面所有匹配的\if\elif测试都未成功时,才会处理\else后面的行。 - expression参数 - 是\if\elif命令的参数, - 受变量插值和反引号扩展的影响,就像任何其他反斜杠命令参数一样。 - 之后,它被评估为一个开/关选项变量的值。因此,有效值是以下任何一个不 - 含糊的不区分大小写匹配之一: - true, false, 1, - 0, on, off, - yes, no。例如, - t, TtR - 都将被视为true。 + 与其他反斜线命令的参数一样,\if\elif命令的expression参数会经过变量插值和反引号扩展。随后,按开/关选项变量值的规则对结果求值。因此,有效值是以下值的不区分大小写且无歧义的匹配:truefalse10onoffyesno。例如,tTtR都会被视为true - 不正确评估为真或假的表达式将生成警告,并被视为假。 + 不能正确求值为真或假的表达式会产生警告,并被视为假。 - 被跳过的行会被正常解析以识别查询和反斜杠命令,但查询不会发送到服务器, - 而且除了条件命令(\if\elif, - \else\endif)之外的反斜杠命令会被忽略。 + 被跳过的行会被正常解析以识别查询和反斜线命令,但查询不会发送到服务器, + 而且除了条件命令(\if\elif、 + \else\endif)之外的反斜线命令会被忽略。 仅检查跳过行中条件命令的有效嵌套。跳过行中的变量引用不会被展开, 也不会执行反引号扩展。 - 所有给定条件块的反斜杠命令必须出现在同一个源文件中。如果在主输入文件或一个 - \include的文件上达到文件结束之前,所有本地 - \if块都没有关闭, - 那么psql将会引发错误。 + 同一个条件块的所有反斜线命令必须出现在同一个源文件中。如果主输入文件或通过\include引入的文件到达 EOF 时,仍有本地\if块未关闭,psql就会报错。 下面是一个示例: @@ -1855,17 +1772,13 @@ SELECT \ir\include_relative filename - - \ir命令类似于\i,但是解析相对文件名的方式不同。 - 在交互模式下执行时,这两个命令的行为是相同的。然而,在脚本中调用时, - \ir会将文件名解释为相对于脚本所在目录,而不是当前工作目录。 - + \ir命令与\i相似,但解析相对文件名的方式不同。在交互模式下执行时,这两个命令的行为相同。不过,在脚本中调用时,\ir会相对于脚本所在的目录来解释文件名,而不是相对于当前工作目录。 - \l[x+] or \list[x+] [ pattern ] + \l[x+]\list[x+] [ pattern ] 列出服务器中的数据库,并显示其名称、所有者、字符集编码和访问权限。如果指定了 pattern,则只列出名称与模式匹配的数据库。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则还会显示数据库大小、默认表空间和描述。当前用户对其拥有 CONNECT 权限的数据库可以显示大小信息;如果当前用户是超级用户或具有 pg_read_all_stats 角色的权限,也可以显示大小信息。 @@ -1882,7 +1795,7 @@ SELECT 从数据库中读取具有OIDloid的大对象,并将其写入filename。请注意,这与服务器函数 - lo_export略有不同,后者使用数据库服务器运行的用户权限, + lo_export略有不同,后者使用运行数据库服务器的用户的权限, 并在服务器的文件系统上操作。 @@ -1898,14 +1811,10 @@ SELECT \lo_import filename [ comment ] - - 将文件存储到一个PostgreSQL大对象中。可选地,它将给定的注释与对象关联起来。例如: - + 将文件存储到一个PostgreSQL大对象中。可选地,它将给定的注释与对象关联起来。例如: foo=> \lo_import '/home/peter/pictures/photo.xcf' 'a picture of me' lo_import 152801 - - 响应表明大对象收到了对象ID 152801,这个ID可以用来在将来访问新创建的大对象。为了可读性起见,建议始终将一个可读的注释与每个对象关联起来。OID和注释都可以用\lo_list命令查看。 - +响应表明大对象获得了对象 ID 152801,这个 ID 可以用来在将来访问新创建的大对象。为便于阅读,建议始终为每个对象关联一条便于人阅读的注释。查看 OID 和注释时,可以使用\lo_list命令。 请注意,此命令与服务器端的lo_import略有不同,因为它作为本地用户在本地文件系统上操作,而不是服务器的用户和文件系统。 @@ -1928,7 +1837,7 @@ lo_import 152801 - 从数据库中删除具有OIDloid的大对象。 + 从数据库中删除OIDloid的大对象。 @@ -1944,19 +1853,12 @@ lo_import 152801 \o\out [ filename ] \o\out [ |command ] - - 安排将未来的查询结果保存到文件filename, - 或将未来的结果传输到shell命令command。 - 如果未指定参数,则查询输出重置为标准输出。 - + 将后续查询结果保存到文件filename,或通过管道传给 shell 命令command。如果没有指定参数,查询输出将恢复为标准输出。 - - 如果参数以|开头,则整个剩余部分的行被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分的行会被直接传递给shell。 - + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 - 查询结果包括从数据库服务器获取的所有表、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 + 查询结果包括从数据库服务器获取的所有表格、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 @@ -2032,17 +1934,9 @@ SELECT $1 \parse stmt1 \pset [ option [ value ] ] - - 这个命令设置影响查询结果表输出的选项。 - option - 指示要设置哪个选项。根据所选选项,value的语义会有所不同。 - 对于某些选项,省略value会导致该选项被切换或取消设置,具体描述在特定选项下。 - 如果没有提到这样的行为,那么省略value只会显示当前设置。 - + 这个命令设置影响查询结果表输出的选项。option指定要设置哪个选项。value的含义取决于所选的选项。对于某些选项,省略value会切换或取消设置该选项,具体见各选项的说明。如果没有提及这类行为,那么省略value只会显示当前设置。 - - \pset不带任何参数时,显示所有打印选项的当前状态。 - + 不带任何参数的\pset会显示所有打印选项的当前状态。 可调整打印选项有: @@ -2050,12 +1944,7 @@ SELECT $1 \parse stmt1 border - - value必须是一个数字。一般来说,数字越高,表格的边框和线条就越多, - 但具体细节取决于特定格式。在HTML格式中,这将直接转换为border=...属性。 - 在大多数其他格式中,只有值0(无边框)、1(内部分隔线)和2(表框)有意义,值大于2将被视为border = 2。 - latexlatex-longtable格式还允许值为3,以在数据行之间添加分隔线。 - + value必须是数字。一般来说,数字越大,表格的边框和分隔线就越多,但细节取决于具体格式。在HTML格式中,它会直接转换为border=...属性。在大多数其他格式中,只有值 0(无边框)、1(内部分隔线)和 2(表格外框)有意义,大于 2 的值会与border = 2作相同处理。latexlatex-longtable格式还允许使用值 3,以在数据行之间添加分隔线。 @@ -2068,7 +1957,7 @@ SELECT $1 \parse stmt1 零(默认值)会导致目标宽度由环境变量COLUMNS控制,或者如果未设置 COLUMNS则由检测到的屏幕宽度控制。 另外,如果columns为零,则wrapped格式仅影响屏幕输出。 - 如果columns为非零,则文件和管道输出也会被包装到该宽度。 + 如果columns为非零,则文件和管道输出也会按该宽度折行。 @@ -2088,7 +1977,7 @@ SELECT $1 \parse stmt1 display_false - 设置替代 false 值打印的字符串。默认打印 f。 + 设置替代 假值打印的字符串。默认打印 f @@ -2097,7 +1986,7 @@ SELECT $1 \parse stmt1 display_true - 设置替代 true 值打印的字符串。默认打印 t。 + 设置替代 真值打印的字符串。默认打印 t @@ -2105,63 +1994,35 @@ SELECT $1 \parse stmt1 expanded(或x - - 如果指定了value,它必须是onoff, - 这将启用或禁用扩展模式,或者是auto。 - 如果省略了value,则命令在开启和关闭设置之间切换。 - 启用扩展模式时,查询结果以两列显示,左侧是列名,右侧是数据。 - 如果数据在正常的水平模式下无法完全显示在屏幕上,则此模式很有用。 - 在自动设置中,当查询输出具有多列且宽度超过屏幕时,将使用扩展模式;否则,将使用常规模式。 - 自动设置仅在对齐和换行格式中有效。在其他格式中,它始终表现为扩展模式已关闭。 - + 如果指定了value,它必须是onoff(分别启用或禁用扩展模式),或者是auto。如果省略value,该命令会在开启和关闭设置之间切换。启用扩展模式时,查询结果以两列显示,左侧为列名,右侧为数据。如果数据在通常的横向模式下无法适应屏幕,这种模式就很有用。在自动设置下,当查询输出包含多列且宽度超过屏幕时,会使用扩展模式;否则使用常规模式。自动设置只在对齐和折行格式中有效。在其他格式中,它的行为始终与关闭扩展模式相同。 fieldsep - - 指定在未对齐的输出格式中使用的字段分隔符。这样,可以创建例如制表符分隔的输出, - 其他程序可能更喜欢。要将制表符设置为字段分隔符,请键入 - \pset fieldsep '\t'。默认字段分隔符是 - '|'(一根竖线)。 - + 指定非对齐输出格式使用的字段分隔符。这样可以创建例如制表符分隔的输出,这可能更符合其他程序的需要。要将制表符设置为字段分隔符,请输入\pset fieldsep '\t'。默认字段分隔符是'|'(竖线)。 fieldsep_zero - - 将未对齐输出格式中使用的字段分隔符设置为零字节。 - + 将非对齐输出格式使用的字段分隔符设置为零字节。 footer - - 如果指定了value, - 它必须是onoff, - 这将启用或禁用表格页脚的显示 - ((n 行)计数)。 - 如果省略了value, - 命令将切换页脚的显示或隐藏。 - + 如果指定了value,它必须是onoff,分别启用或禁用表格页脚((n rows)计数)的显示。如果省略value,该命令会切换页脚显示的开关状态。 format - - 设置输出格式为alignedasciidoc、 - csvhtmllatex、 - latex-longtabletroff-ms、 - unalignedwrapped。 - 允许使用唯一缩写。 - + 设置输出格式为alignedasciidoccsvhtmllatexlatex-longtabletroff-msunalignedwrapped。允许使用唯一缩写。 aligned格式是标准的、适合人阅读且排版整齐的文本输出;这是默认格式。 @@ -2174,12 +2035,12 @@ SELECT $1 \parse stmt1 按逗号分隔的列值输出,并应用 RFC 4180 - 中描述的引用规则。 + 中描述的加引号规则。 此输出与服务器的CSV格式的 COPY命令兼容。 - 生成包含列名的标题行,除非 + 生成包含列名的表头行,除非 tuples_only参数设置为 - on。不打印标题和页脚。 + on。不打印表格标题和页脚。 每行以系统相关的行结束字符结束, 对于类Unix系统通常是单个换行符(\n), 对于Microsoft Windows则是回车和换行序列 @@ -2187,17 +2048,14 @@ SELECT $1 \parse stmt1 可以用\pset csv_fieldsep选择逗号以外的字段分隔字符。 - wrapped格式类似于aligned,但会将宽数据值跨行包装,以使输出适合目标列宽。 - 目标宽度由columns选项下描述的方式确定。请注意,psql不会尝试包装列标题; - 因此,如果列标题所需的总宽度超过目标宽度,则wrapped格式的行为与aligned相同。 - + wrapped格式与aligned相似,但会将较宽的数据值折成多行,使输出适应目标列宽。目标宽度的确定方式见columns选项的说明。请注意,psql不会尝试对列标题折行;因此,如果列标题所需的总宽度超过目标宽度,wrapped格式的行为就与aligned相同。 - asciidochtml, - latexlatex-longtable,和 + asciidochtml、 + latexlatex-longtabletroff-ms格式生成的表格旨在包含在使用相应标记语言的文档中。 它们不是完整的文档!这在HTML中可能不是必需的,但在 - LaTeX中,则必须有一个完整的文档包装器。 + LaTeX中,则必须有一个完整文档的外层结构。 latex格式使用LaTeXtabular 环境。 latex-longtable格式需要LaTeX @@ -2217,25 +2075,19 @@ SELECT $1 \parse stmt1 - ascii样式使用普通的ASCII字符。数据中的换行使用右边边缘的+符号显示。 - 当wrapped格式将数据从一行换到下一行而没有换行符时,在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 + ascii样式使用普通的ASCII字符。数据中的换行符以右边缘的+符号表示。当wrapped格式在没有换行符的位置把数据折到下一行时,会在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 - old-ascii样式使用普通的ASCII字符,使用在PostgreSQL 8.4及更早版本中使用的格式样式。 - 数据中的换行符使用:符号代替左侧列分隔符显示。 - 当数据从一行换行到下一行而没有换行符时,使用;符号代替左侧列分隔符。 + old-ascii样式使用普通的ASCII字符,采用PostgreSQL 8.4 及更早版本的格式样式。数据中的换行符以替代左侧列分隔符的:符号表示。当数据在没有换行符的位置折到下一行时,则用;符号替代左侧列分隔符。 - unicode样式使用Unicode绘图字符。数据中的换行使用右边距中的回车符号显示。 - 当数据从一行换行到下一行而没有换行符时,第一行的右边距显示省略号符号, - 接着在下一行的左边距再次显示省略号符号。 + unicode样式使用 Unicode 框线绘制字符。数据中的换行符以右边缘的回车符号表示。当数据在没有换行符的位置折到下一行时,会在第一行的右边缘显示省略号符号,并在下一行的左边缘再次显示。 - 当border设置大于零时,linestyle选项还确定了用哪些字符绘制边框线。 - 普通的ASCII字符在任何地方都有效,但在识别Unicode字符的显示器上看起来更好。 + 当border设置大于零时,linestyle选项还决定用哪些字符绘制边框线。普通的ASCII字符在任何环境中都可用,但在支持 Unicode 的显示设备上,Unicode 字符更美观。 @@ -2243,24 +2095,14 @@ SELECT $1 \parse stmt1 null - - 设置要打印在空值位置的字符串。默认情况下是不打印任何内容,这很容易被误解为空字符串。 - 例如,一个人可能更喜欢\pset null '(null)'。 - + 设置用于代替空值打印的字符串。默认不打印任何内容,这很容易被误认为空字符串。例如,你可能更喜欢使用\pset null '(null)' numericlocale - - 如果指定了value, - 它必须是onoff, - 这将启用或禁用显示一个特定于区域设置的字符, - 用于将小数点左侧的数字分组。如果省略了 - value, - 命令在常规和特定于区域设置的数字输出之间切换。 - + 如果指定了value,它必须是onoff,分别启用或禁用使用区域设置特定的字符来分隔小数点左侧的数字组。如果省略value,该命令会在常规数字输出和区域设置特定的数字输出之间切换。 @@ -2268,17 +2110,11 @@ SELECT $1 \parse stmt1 pager - 控制查询和psql帮助输出时使用分页程序的方式。 - 当pager选项为off时,不使用分页程序。 - 当pager选项为on时,在适当的情况下使用分页程序,即当输出到终端且不适合在屏幕上显示时。 - pager选项也可以设置为always,这会导致分页程序用于所有终端输出,无论是否适合在屏幕上显示。 - \pset pager 不带value时,会在开启和关闭分页器之间切换。 + 控制查询和psql帮助输出是否使用分页器程序。当pager选项为off时,不使用分页器程序。当pager选项为on时,会在适当时使用分页器,即输出目标为终端且内容无法在屏幕上完整显示时。pager选项也可以设为always,这样所有终端输出都会使用分页器,无论内容是否能在屏幕上完整显示。不带value\pset pager会切换分页器的使用状态。 - 如果环境变量PSQL_PAGERPAGER被设置, - 输出将被分页传输到指定的程序。否则,将使用一个平台相关的默认程序 - (例如more)。 + 如果设置了环境变量PSQL_PAGERPAGER,需要分页的输出会通过管道传给指定程序。否则,使用与平台有关的默认程序(如more)。 @@ -2293,94 +2129,64 @@ SELECT $1 \parse stmt1 pager_min_lines - - 如果pager_min_lines设置为大于页面高度的数字, - 则除非至少有这么多行的输出要显示,否则不会调用分页程序。默认设置为0。 - + 如果将pager_min_lines设置为大于页面高度的数字,那么只有待显示的输出至少达到这么多行时,才会调用分页器程序。默认设置为 0。 recordsep - - 指定在未对齐的输出格式中使用的记录(行)分隔符。默认为换行符。 - + 指定非对齐输出格式使用的记录(行)分隔符。默认为换行符。 recordsep_zero - - 设置未对齐输出格式中使用的记录分隔符为零字节。 - + 将非对齐输出格式使用的记录分隔符设置为零字节。 tableattr(或T - - 在HTML格式中,这指定要放置在table标签内的属性。 - 这可能是cellpaddingbgcolor等。 - 请注意,这里通常不需要指定border,因为它已经由\pset border处理。 - 如果没有给出value,则取消表格属性。 - - - 在latex-longtable格式中,这控制了包含左对齐数据类型的每列的比例宽度。 - 它被指定为一个以空格分隔的值列表,例如,'0.2 0.2 0.6'。 - 未指定输出列使用最后指定的值。 - + HTML格式中,这指定要放在table标签内的属性,例如cellpaddingbgcolor。请注意,你可能不需要在这里指定border,因为\pset border已经负责处理它。如果没有给出value,则取消设置表格属性。 + latex-longtable格式中,这控制每个包含左对齐数据类型的列的宽度比例。它以空白分隔的值列表指定,例如'0.2 0.2 0.6'。未指定的输出列使用最后指定的值。 - title(或者C + title(或C - - 设置后续打印的任何表的标题。这可以用来为输出提供说明性标签。 - 如果没有给出value,则标题将被取消设置。 - + 设置随后打印的所有表格的标题。这可以为输出提供描述性标签。如果没有给出value,则取消设置标题。 tuples_only(或t - - 如果指定了value,它必须是onoff, - 这将启用或禁用仅元组模式。如果省略了value, - 命令将在常规输出和仅元组输出之间切换。常规输出包括额外信息,如列标题、标题和各种页脚。 - 在仅元组模式下,只显示实际的表数据。 - + 如果指定了value,它必须是onoff,分别启用或禁用仅元组模式。如果省略value,该命令会在常规输出和仅元组输出之间切换。常规输出包含列标题、表格标题和各种页脚等附加信息。在仅元组模式下,只显示实际的表格数据。 unicode_border_linestyle - - 设置unicode线条样式的边框绘制样式为singledouble之一。 - + unicode线条样式的边框绘制样式设置为singledouble unicode_column_linestyle - - 设置unicode线条样式的列绘制样式为singledouble之一。 - + unicode线条样式的列分隔线绘制样式设置为singledouble unicode_header_linestyle - - 设置unicode线条样式的标题绘制样式为singledouble之一。 - + unicode线条样式的表头分隔线绘制样式设置为singledouble @@ -2388,35 +2194,33 @@ SELECT $1 \parse stmt1 xheader_width - 将扩展输出的标题最大宽度设置为以下之一: + 将扩展输出的表头最大宽度设置为以下之一: full(默认值)、 columnpage整数值 - full:扩展标题不截断,其宽度与最宽的输出行相同。 + full:扩展表头不截断,其宽度与最宽的输出行相同。 - column:将标题行截断为第一列的宽度。 + column:将表头行截断为第一列的宽度。 - page:将标题行截断为终端宽度。 + page:将表头行截断为终端宽度。 - 整数值:指定标题行的确切最大宽度。 + 整数值:指定表头行的确切最大宽度。 - - 这些不同格式的示例可以在下面的中看到。 - + 这些不同格式的外观示例可参见下面的 @@ -2433,10 +2237,7 @@ SELECT $1 \parse stmt1 \q\quit - - 退出psql程序。 - 在脚本文件中,只有该脚本的执行被终止。 - + 退出psql程序。在脚本文件中,只会终止该脚本的执行。 @@ -2445,7 +2246,7 @@ SELECT $1 \parse stmt1 \qecho text [ ... ] - 这个命令与\echo命令相同,只是输出将被写入查询输出通道,由\o设置。 + 这个命令与\echo相同,只是输出会写入由\o设置的查询输出通道。 @@ -2454,9 +2255,7 @@ SELECT $1 \parse stmt1 \r\reset - - 重置(清除)查询缓冲区。 - + 重置(清空)查询缓冲区。 @@ -2471,10 +2270,6 @@ SELECT $1 \parse stmt1 此命令主要用于pg_dumppg_dumpallpg_restore生成的纯文本转储文件中,但在其他场景下也可能有用。 - - 与大多数其他元命令不同,整个剩余行始终被视为\unrestrict的参数, - 并且不会执行变量插值或反引号扩展。 - @@ -2547,14 +2342,9 @@ testdb=> \setenv LESS -imx4F 定义将打印到当前查询输出通道,由\o设置。 - - 目标函数可以仅通过名称指定,也可以通过名称和参数指定,例如foo(integer, text)。 - 如果有多个同名函数,则必须给出参数类型。 - + 目标函数可以只用名称指定,也可以同时给出名称和参数,例如foo(integer, text)。如果存在多个同名函数,就必须给出参数类型。 - - 如果在命令名称后添加+,则输出的行将被编号,函数体的第一行将被标记为第1行。 - + 如果在命令名后附加+,输出行会带上行号,函数体的第一行编号为 1。 与大多数其他元命令不同,整个行的剩余部分始终被视为\sf的参数, @@ -2569,8 +2359,7 @@ testdb=> \setenv LESS -imx4F - 这个命令获取并显示指定视图的定义,以CREATE OR REPLACE VIEW命令的形式。 - 定义将打印到当前查询输出通道,由\o设置。 + 这个命令获取指定视图的定义,并以CREATE OR REPLACE VIEW命令的形式显示。定义会打印到由\o设置的当前查询输出通道。 @@ -2595,7 +2384,7 @@ testdb=> \setenv LESS -imx4F - 这组命令实现 SQL 语句的管道化。一个管道必须以 \startpipeline 开始,并以 \endpipeline 结束。其间可以出现任意数量的 \syncpipeline 命令,它会发送一条同步消息,但不会结束当前管道,并会刷新发送缓冲区。在管道模式下,语句会被发送到服务器,而不等待前面语句的结果。更多细节见 。 + 这组命令实现 SQL 语句的管道化。一个管道必须以 \startpipeline 开始,并以 \endpipeline 结束。其间可以出现任意数量的 \syncpipeline 命令,它会发送一条同步消息,而不会结束当前管道,也不会刷新发送缓冲区。在管道模式下,语句会被发送到服务器,而不等待前面语句的结果。更多细节见 @@ -2644,10 +2433,7 @@ SELECT 1 \bind \sendpipeline \t - - 切换显示输出列名标题和行数页脚。此命令等效于\pset tuples_only, - 仅为方便起见提供。 - + 切换输出中的列名标题和行数页脚的显示状态。这个命令等价于\pset tuples_only,提供它是为了使用方便。 @@ -2655,10 +2441,7 @@ SELECT 1 \bind \sendpipeline \T table_options - - 指定在table标签中放置的属性,在HTML输出格式中。 - 该命令等效于\pset tableattr table_options。 - + 指定在HTML输出格式中放在table标签内的属性。这个命令等价于\pset tableattr table_options @@ -2666,10 +2449,7 @@ SELECT 1 \bind \sendpipeline \timing [ on | off ] - - 使用参数,打开或关闭显示每个SQL语句执行时间的功能。没有参数时,切换显示开关。 - 显示的时间单位为毫秒;超过1秒的时间间隔也以分钟:秒的格式显示,如有必要还会显示小时和天。 - + 带参数时,开启或关闭每条 SQL 语句执行耗时的显示。不带参数时,切换显示的开关状态。耗时以毫秒显示;超过 1 秒的时间间隔还会以分钟:秒的格式显示,必要时添加小时和天字段。 @@ -2684,6 +2464,10 @@ SELECT 1 \bind \sendpipeline 此命令主要用于pg_dumppg_dumpallpg_restore生成的纯文本转储文件中,但在其他场景下也可能有用。 + + 与大多数其他元命令不同,整个剩余行始终被视为\unrestrict的参数, + 并且不会执行变量插值或反引号扩展。 + @@ -2692,15 +2476,9 @@ SELECT 1 \bind \sendpipeline \unset name - - 取消设置(删除)psql变量name。 - + 取消设置(删除)psql变量name - - 大多数控制psql行为的变量不能被取消设置;相反,\unset命令被解释为将它们设置为默认值。 - 请参见下面的。 - + 大多数控制psql行为的变量不能取消设置;对于这些变量,\unset命令会被解释为将其设置为默认值。参见下面的 @@ -2709,15 +2487,9 @@ SELECT 1 \bind \sendpipeline \w\write filename \w\write |command - - 将当前查询缓冲区写入文件filename,或者通过管道传给 shell 命令command。 - 如果当前查询缓冲区为空,则写入最近执行的查询。 - + 将当前查询缓冲区写入文件filename,或通过管道传递给 shell 命令command。如果当前查询缓冲区为空,则改为写入最近执行的查询。 - - 如果参数以|开头,则整个剩余部分的行被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分的行会被直接传递给shell。 - + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 @@ -2751,9 +2523,7 @@ SELECT 1 \bind \sendpipeline \x [ on | off | auto ] - - 设置或切换扩展表格格式模式。因此,它等同于\pset expanded。 - + 设置或切换扩展表格格式模式。它等价于\pset expanded @@ -2776,13 +2546,11 @@ SELECT 1 \bind \sendpipeline \! [ command ] - 不带参数时,转义到一个子shell;psql在子shell退出时恢复。 - 带参数时,执行shell命令command。 + 不带参数时,进入一个子 shell;子 shell 退出后,psql恢复运行。带参数时,执行 shell 命令command - 与大多数其他元命令不同,整个行的剩余部分始终被视为\!的参数, - 在参数中不执行变量插值或反引号扩展。行的其余部分被直接传递给shell。 + 与大多数其他元命令不同,该行剩余的全部内容始终被视为\!的参数,其中不会进行变量插值或反引号扩展。该行剩余内容会原样传给 shell。 @@ -2794,7 +2562,7 @@ SELECT 1 \bind \sendpipeline 显示帮助信息。可选的topic参数 (默认为commands)选择要解释的psql的哪个部分: - commands描述psql的反斜杠命令; + commands描述psql的反斜线命令; options描述可以传递给psql的命令行选项; 而variables显示关于psql配置变量的帮助。 @@ -2806,7 +2574,7 @@ SELECT 1 \bind \sendpipeline \; - 反斜杠分号不像前面的命令那样是一个元命令;相反,它只是在不进行进一步处理的情况下将一个分号添加到查询缓冲区中。 + 反斜线分号不像前面的命令那样是一个元命令;相反,它只是在不进行进一步处理的情况下将一个分号添加到查询缓冲区中。 @@ -2818,8 +2586,8 @@ SELECT 1; SELECT 2; SELECT 3; SELECT 1\; SELECT 2\; SELECT 3; - 在到达非反斜杠分号时将三个SQL命令发送到服务器的单个请求中。 - 服务器将执行此类请求作为单个事务,除非字符串中包含明确的BEGIN/COMMIT命令将其分成多个事务。(有关服务器如何处理多查询字符串的更多详细信息,请参见。) + 会在遇到前面没有反斜线的分号时,将这三个 SQL 命令作为单个请求发送到服务器。 + 服务器会将此类请求作为单个事务执行,除非字符串中包含显式的BEGIN/COMMIT命令将其分成多个事务。(有关服务器如何处理多查询字符串的更多详细信息,请参见。) @@ -2827,16 +2595,16 @@ SELECT 1\; SELECT 2\; SELECT 3; - + 模式 - patterns + 模式 在 psql 和 pg_dump 中 - 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要把它写成两个相邻的双引号,这同样是符合 SQL 引用标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你不能只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 + 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要在双引号包围的文本内把它写成两个相邻的双引号,这同样是符合 SQL 加引号标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你可以只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 @@ -2848,21 +2616,15 @@ SELECT 1\; SELECT 2\; SELECT 3; - 包含点(.)的关系模式被解释为模式名称后跟对象名称模式。例如, - \dt foo*.*bar*显示所有位于模式名以foo开头的模式中、且表名包含bar的表。当没有出现点时,模式仅匹配当前模式搜索路径中可见的对象。 - 再次,双引号内的点失去其特殊含义,被视为字面匹配。包含两个点(.)的关系模式 - 被解释为数据库名称后跟模式名称后跟对象名称模式。数据库名称部分不会被视为模式,必须匹配当前连接的数据库名称, - 否则将引发错误。 + 如果用于匹配关系名的模式包含一个点(.),则会被解释为模式名的匹配模式,后接对象名的匹配模式。例如,\dt foo*.*bar*会显示所有位于模式名以foo开头的模式中、且表名包含bar的表。如果没有点,则只匹配当前模式搜索路径中可见的对象。同样,双引号内的点会失去特殊含义,按字面匹配。如果用于匹配关系名的模式包含两个点(.),则会被解释为数据库名、模式名的匹配模式和对象名的匹配模式。数据库名部分不会被当作匹配模式,必须与当前连接的数据库名相同,否则会报错。 - 包含一个点(.)的模式被解释为数据库名称后跟模式的模式名称。例如, - \dn mydb.*foo*显示所有包含foo的模式。数据库名称部分不会被视为模式, - 必须匹配当前连接数据库的名称,否则将引发错误。 + 如果用于匹配模式名的模式包含一个点(.),则会被解释为数据库名,后接模式名的匹配模式。例如,\dn mydb.*foo*会显示名称中包含foo的所有模式。数据库名部分不会被当作匹配模式,必须与当前连接的数据库名相同,否则会报错。 - 高级用户可以使用字符类等正则表达式记法,如[0-9]可以匹配任意数字。所有的正则表达式特殊字符都按照所说的工作,以下字符除外:.会按照上面所说的作为一种分隔符,*会被翻译成正则表达式记号.*?会被翻译成.,而$则按字面意思匹配。根据需要,可以通过书写?(R+|)(R|)R?来分别模拟模式字符.R*R?$不需要作为一个正则表达式字符,因为模式必须匹配整个名称,而不是像正则表达式的常规用法那样解释(换句话说,$会被自动地追加到模式上)。如果不希望该模式的匹配位置被固定,可以在开头或者结尾写上*。注意在双引号内,所有的正则表达式特殊字符会失去其特殊含义并且按照其字面意思进行匹配。还有,在操作符名称模式中(即作为\do的参数),正则表达式特殊字符也按照字面意思进行匹配。 + 高级用户可以使用字符类等正则表达式记法,如[0-9]可以匹配任意数字。所有的正则表达式特殊字符都按照所说的工作,以下字符除外:.会按照上面所说的作为一种分隔符,*会被翻译成正则表达式记号.*?会被翻译成.,而$则按字面意思匹配。根据需要,可以通过书写?(R+|)(R|)来分别模拟模式字符.R*R?$不需要作为一个正则表达式字符,因为模式必须匹配整个名称,而不是像正则表达式的常规用法那样解释(换句话说,$会被自动地追加到模式上)。如果不希望该模式的匹配位置被固定,可以在开头或者结尾写上*。注意在双引号内,所有的正则表达式特殊字符会失去其特殊含义并且按照其字面意思进行匹配。还有,在操作符名称模式中(即作为\do的参数),正则表达式特殊字符也按照字面意思进行匹配。 @@ -2870,7 +2632,7 @@ SELECT 1\; SELECT 2\; SELECT 3; 高级特性 - + 变量 @@ -2891,7 +2653,7 @@ bar - 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要重置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 + 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要取消设置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 @@ -2905,7 +2667,7 @@ bar - 控制psql行为的变量通常不能被重置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse。 + 控制psql行为的变量通常不能被取消设置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse @@ -2923,7 +2685,7 @@ bar - 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被重置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交打开模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身即不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 + 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被取消设置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交关闭模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身既不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 @@ -2953,7 +2715,7 @@ bar DBNAME - 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -2962,7 +2724,7 @@ bar ECHO - 如果被设置为all,所有非空输入行会被按照读入它们的样子打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被重置或者设置为none(默认值)则不会显示任何查询。 + 如果被设置为all,所有非空输入行会在读入时打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被设置为none(默认值)则不会显示任何查询。 @@ -2980,7 +2742,7 @@ bar ENCODING - 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者重置。 + 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者取消设置。 @@ -2998,12 +2760,12 @@ bar FETCH_COUNT - 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每一组就会包括这么多个行。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 + 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每组包含的行数等于该整数值。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 - 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT个行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 + 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 @@ -3032,7 +2794,7 @@ bar HISTCONTROL - 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则匹配之前的历史行的行不会被放入。值ignoreboth组合了上述两种值。如果被重置或者被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 + 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则与上一条历史记录相同的行不会被放入。值ignoreboth组合了上述两种值。如果被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 @@ -3046,7 +2808,7 @@ bar HISTFILE - 该文件名将被用于存储历史列表。如果被重设,文件名将从PSQL_HISTORY环境变量中取得。如果该环境变量也没有被设置,则默认值是~/.psql_history,在Windows上是%APPDATA%\postgresql\psql_history。例如, + 该文件名将被用于存储历史列表。如果未设置该变量,文件名将从PSQL_HISTORY环境变量中取得。如果该环境变量也没有被设置,则默认值是~/.psql_history,在Windows上是%APPDATA%\postgresql\psql_history。例如, \set HISTFILE ~/.psql_history-:DBNAME @@ -3078,7 +2840,7 @@ bar HOST - 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -3087,7 +2849,7 @@ bar IGNOREEOF - 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须键入多个连续的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 + 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须连续键入与该数值相等数量的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 @@ -3101,8 +2863,8 @@ bar LASTOID - 最后被影响的 OID 的值,这可能会由INSERT或者\lo_import命令返回。这个变量只保证在下一个SQL命令被显示完之前有效。 - PostgreSQL 服务器从12版开始不再支持 OID 系统列,因此,在面向此类服务器时,跟随在INSERT后面的 LASTOID 将始终为0。 + 最后被影响的 OID 的值,这可能会由INSERT或者\lo_import命令返回。这个变量仅保证在下一个SQL命令的结果显示完之前有效。 + PostgreSQL 服务器从12版开始不再支持 OID 系统列,因此,在面向此类服务器时,执行INSERT后的 LASTOID 将始终为0。 @@ -3127,7 +2889,7 @@ bar - 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被重置或者设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 + 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 @@ -3145,7 +2907,7 @@ bar PIPELINE_COMMAND_COUNT - 正在运行的管道中排队的命令数 。 + 正在运行的管道中排队的命令数。 @@ -3165,7 +2927,7 @@ bar PIPELINE_SYNC_COUNT - 正在运行的管道中排队的同步消息数量 。 + 正在运行的管道中排队的同步消息数量。 @@ -3174,7 +2936,7 @@ bar PORT - 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -3213,7 +2975,7 @@ bar SERVER_VERSION_NUM - 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者重设。 + 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者取消设置。 @@ -3242,7 +3004,7 @@ bar 如果最后一个 shell 命令失败,则为 true;如果成功,则为 false。这适用于通过 \!\g\o\w - 和 \copy 元命令调用的 shell 命令,也适用于反引号(`)展开。请注意,对于 \o,该变量会在下一个 \o 命令关闭输出管道时更新。 + 和 \copy 元命令调用的 shell 命令,也适用于反引号(`)扩展。请注意,对于 \o,该变量会在下一个 \o 命令关闭输出管道时更新。 另见 SHELL_EXIT_CODE @@ -3254,7 +3016,7 @@ bar 最后一个 shell 命令返回的退出状态。0–127 表示程序退出码,128–255 表示因信号而终止,-1 表示未能启动程序或未能取得其退出状态。这适用于通过 \!\g\o\w - 和 \copy 元命令调用的 shell 命令,也适用于反引号(`)展开。请注意,对于 \o,该变量会在下一个 \o 命令关闭输出管道时更新。 + 和 \copy 元命令调用的 shell 命令,也适用于反引号(`)扩展。请注意,对于 \o,该变量会在下一个 \o 命令关闭输出管道时更新。 另见 SHELL_ERROR @@ -3274,7 +3036,7 @@ bar SHOW_CONTEXT - 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT域。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 + 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT字段。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 当VERBOSITY被设置为tersesqlstate时,这个设置无效(另见\errverbose,它可以用来得到刚遇到的错误的详细信息)。 @@ -3293,7 +3055,7 @@ bar SINGLESTEP - 设置这个变量为on等效于命令选项。 + 设置这个变量为on等效于命令行选项 @@ -3311,7 +3073,7 @@ bar USER - 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -3320,7 +3082,7 @@ bar VERBOSITY - 这个变量可以被设置为值defaultverboseterse或者sqlstate来控制错误报告的详细程度(另见\errverbose,在想得到之前的错误的详细版本时使用)。 + 这个变量可以被设置为值defaultverboseterse或者sqlstate来控制错误报告的详细程度(另见\errverbose,在想得到刚遇到的错误的详细信息时使用)。 @@ -3331,7 +3093,7 @@ bar VERSION_NUM - 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或重设。 + 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或取消设置。 @@ -3349,11 +3111,11 @@ bar - - <acronym>SQL</acronym> 中插入变量 + + <acronym>SQL</acronym> 插值 - psql变量的一个关键特性是可以把它们替换(插入)到常规SQL语句中,也可以把它们作为元命令的参数。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。插入一个值而不加引号的语法是在变量名前面加上一个冒号(:)。例如, + psql变量的一个关键特性是可以把它们替换(插值)到常规SQL语句中,也可以把它们替换到元命令的参数中。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。不加引号地插值一个值的语法是在变量名前面加上一个冒号(:)。例如, testdb=> \set foo 'my_table' testdb=> SELECT * FROM :foo; @@ -3362,7 +3124,7 @@ testdb=> SELECT * FROM :foo; - 当一个值被用作 SQL 文本或者标识符时,最安全的是把它加上引用。要引用一个变量的值作为 SQL 文本,可以把变量名称放在单引号中并且在引号前面写一个冒号。要引用作为 SQL 标识符,则可以把变量名称放在双引号中并且在引号前面写一个冒号。这种结构可以正确地处理变量值中嵌入的引号和其他特殊字符。之前的示例用这种方法写会更安全: + 当一个值要用作 SQL 字面量或标识符时,最安全的做法是为它加上引号。要将变量值作为 SQL 字面量加引号,应写一个冒号,后面跟用单引号括起来的变量名。要将变量值作为 SQL 标识符加引号,则在冒号后面用双引号括起变量名。这些写法能正确处理变量值中嵌入的引号和其他特殊字符。前面的示例可用以下更安全的写法: testdb=> \set foo 'my_table' testdb=> SELECT * FROM :"foo"; @@ -3370,11 +3132,11 @@ testdb=> SELECT * FROM :"foo"; - 在被引用的SQL文本和标识符中将不会执行变量插入。因此,一个诸如':foo'的结构不会从一个变量的值产生一个被引用的文本(即便能够也会不安全,因为无法正确地处理嵌入在值中的引号)。 + 在加引号的SQL字面量和标识符内部,不会执行变量插值。因此,':foo'这样的写法不能根据变量值生成加引号的字面量(即使能够生效,也不安全,因为它无法正确处理变量值中嵌入的引号)。 - 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个被引用的字符串插入: + 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个加引号的字符串进行插值: testdb=> \set content `cat my_file.txt` testdb=> INSERT INTO my_table VALUES (:'content'); @@ -3383,7 +3145,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 因为冒号可以合法地出现在 SQL 命令中,一次明显的插入尝试(即:name:'name'或者:"name")不会被替换,除非所提及的变量就是当前被设置的。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 + 因为冒号可以合法地出现在 SQL 命令中,一次明显的插值尝试(即:name:'name'或者:"name")不会被替换,除非所指的变量当前已设置。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 @@ -3391,12 +3153,12 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 文本或者标识符的冒号引用语法是一种psql扩展。 + 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 字面量或者标识符的冒号加引号语法是一种psql扩展。 - + 提示符 @@ -3410,33 +3172,26 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %M - - 数据库服务器的完整主机名(带域名);如果连接通过 Unix 域套接字建立,则为 [local];如果 Unix 域套接字不在编译时默认位置,则为 [local:/dir/name]。 - + 数据库服务器的完整主机名(含域名);如果通过 Unix 域套接字连接,则为[local];如果 Unix 域套接字不在编译时指定的默认位置,则为[local:/dir/name] %m - - 数据库服务器的主机名,在第一个点处分截;如果连接通过 Unix 域套接字建立,则为 [local]。 - + 数据库服务器的主机名,在第一个点号处截断;如果通过 Unix 域套接字连接,则为[local] %> - 数据库服务器正在监听的端口号。 + 数据库服务器监听的端口号。 %n - - 数据库会话用户名。(由于 SET SESSION - AUTHORIZATION 命令的作用,该值在数据库会话期间可能会发生变化。) - + 数据库会话用户名。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) @@ -3470,11 +3225,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %# - - 如果会话用户是数据库超级用户,则输出 - #,否则输出 >。(由于 SET SESSION - AUTHORIZATION 命令的作用,该值的展开在数据库会话期间可能会发生变化。) - + 如果会话用户是数据库超级用户,则为#,否则为>。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) @@ -3500,7 +3251,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %R - 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 dollar-quoted 字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 + 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 美元引用字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 @@ -3541,7 +3292,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %digits - 带有所示八进制码的字符被替换。 + 替换为指定八进制代码对应的字符。 @@ -3643,14 +3394,14 @@ $endif - )命令行选项也可用于在单次运行psql时禁用 Readline。这会阻止制表补全、命令行历史的使用或记录,以及多行命令的编辑。当你需要复制粘贴包含 TAB 字符的文本时,它尤其有用。 + )命令行选项也可用于在单次运行psql时禁用 Readline。这会阻止TAB 补全、命令行历史的使用或记录,以及多行命令的编辑。当你需要复制粘贴包含 TAB 字符的文本时,它尤其有用。 - + 环境 @@ -3735,9 +3486,9 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 如果查询结果无法在屏幕上显示完整,它们将通过此命令进行传输。典型的值是moreless。 + 如果查询结果无法在屏幕上显示完整,它们会通过管道传给此命令。典型的值是moreless。 可以通过将PSQL_PAGERPAGER设置为空字符串,或通过调整\pset命令的与分页相关的选项来禁用分页器。 - 这些变量按照列出的顺序进行检查;首先设置的变量将被使用。 + 这些变量按照列出的顺序进行检查;使用按该顺序找到的第一个已设置的变量。 如果它们都没有设置,默认情况下在大多数平台上使用more,但在Cygwin上使用less @@ -3817,7 +3568,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' 在任何情况下,可以通过设置PSQLRC环境变量来覆盖此默认文件路径。 - 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加破折号和PostgreSQL的主要或次要版本标识符来使其与psql版本相关, + 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加连字符和PostgreSQL的大版本或小版本标识符来使其与psql版本相关, 例如~/.psqlrc-&majorversion;~/.psqlrc-&version;。 最具体版本匹配的文件将优先读取,而不是非特定版本的文件。 这些版本后缀是在确定文件路径后添加的,如上所述。 @@ -3845,14 +3596,14 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - psql最适合与相同或较旧主要版本的服务器配合使用。 - 如果服务器的版本比psql本身更新,反斜杠命令特别容易失败。 - 然而,\d系列的反斜杠命令应该可以在版本回溯到9.2的服务器上运行, + psql最适合与相同或较旧大版本的服务器配合使用。 + 如果服务器的版本比psql本身更新,反斜线命令特别容易失败。 + 然而,\d系列的反斜线命令应该可以在最低至 9.2 版本的服务器上运行, 但不一定适用于比psql本身更新的服务器。运行SQL命令和显示查询结果的一般功能 - 也应该可以在更新主要版本的服务器上运行,但不能保证在所有情况下都能实现。 + 也应该可以在更新大版本的服务器上运行,但不能保证在所有情况下都能实现。 - 如果你想用psql连接到多个具有不同主版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个主版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 + 如果你想用psql连接到多个具有不同大版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个大版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 @@ -3866,7 +3617,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空格。现在则要求一些空格。 + 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空白。现在则要求用空白分隔。 diff --git a/zh/19/rowtypes.sgml b/zh/19/rowtypes.sgml index 6d6173e4..57ec958a 100644 --- a/zh/19/rowtypes.sgml +++ b/zh/19/rowtypes.sgml @@ -75,7 +75,7 @@ CREATE TABLE inventory_item ( - 构造组合值 + 构造复合值 复合类型 @@ -83,7 +83,7 @@ CREATE TABLE inventory_item ( - 要把组合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,组合常量的一般格式如下: + 要把复合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,复合常量的一般格式如下: '( val1 , val2 , ... )' @@ -103,11 +103,11 @@ CREATE TABLE inventory_item ( - (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。必要时可能需要显式指定类型。) + (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。可能需要显式指定类型,以指明应将该常量转换为哪种类型。) - ROW表达式语法也可以用于构造组合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: + ROW表达式语法也可以用于构造复合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: ROW('fuzzy dice', 42, 1.99) ROW('', 42, NULL) @@ -126,7 +126,7 @@ ROW('', 42, NULL) 访问复合类型 - 要访问组合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: + 要访问复合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: SELECT item.name FROM on_hand WHERE item.price > 9.99; @@ -148,7 +148,7 @@ SELECT (on_hand.item).name FROM on_hand WHERE (on_hand.item).price > 9.99; - 无论何时从组合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回组合值的函数结果中只选取一个字段,你需要这样写: + 无论何时从复合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回复合值的函数结果中只选取一个字段,你需要这样写: SELECT (my_func(...)).field FROM ... @@ -164,10 +164,10 @@ SELECT (my_func(...)).field FROM ... - 修改组合值 + 修改复合类型 - 下面是一些插入和更新组合列时正确语法的示例。先看插入或更新整个列值的情况: + 下面是一些插入和更新复合列时正确语法的示例。先看插入或更新整个列值的情况: INSERT INTO mytab (complex_col) VALUES((1.1,2.2)); @@ -179,7 +179,7 @@ UPDATE mytab SET complex_col = ROW(1.1,2.2) WHERE ...; - 我们也可以更新组合列中的单个子字段: + 我们也可以更新复合列中的单个子字段: UPDATE mytab SET complex_col.r = (complex_col).r + 1 WHERE ...; @@ -208,11 +208,11 @@ INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2); - 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的组合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: + 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的复合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: SELECT c FROM inventory_item c; - 这个查询会产生一个单独的组合值列,因此我们可能得到如下输出: + 这个查询会产生一个单独的复合值列,因此我们可能得到如下输出: c ------------------------ @@ -223,7 +223,7 @@ SELECT c FROM inventory_item c; - 普通的限定列名语法table_name.column_name可以理解为对该表当前行的组合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) + 普通的限定列名语法table_name.column_name可以理解为对该表当前行的复合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) @@ -256,19 +256,19 @@ SELECT (myfunc(x)).a, (myfunc(x)).b, (myfunc(x)).c FROM some_table; SELECT m.* FROM some_table, LATERAL myfunc(x) AS m; - 把该函数放在LATERAL FROM项中,可以防止它对每一行被调用多于一次。m.*仍会展开为m.a, m.b, m.c,但现在这些变量只是对该FROM项输出的引用。(这里的LATERAL关键字其实是可选的,不过我们把它写出来,是为了明确该函数会从some_table中取得x。) + 把该函数放在LATERAL FROM项中,可以避免它在每行上被调用多次。m.*仍会展开为m.a, m.b, m.c,但现在这些变量只是对该FROM项输出的引用。(这里的LATERAL关键字其实是可选的,不过我们把它写出来,是为了明确该函数会从some_table中取得x。) - 当composite_value.*出现在SELECT输出列表、INSERT/UPDATE/DELETE/MERGE中的RETURNING列表、VALUES子句或行构造器的顶层时,就会产生这种列展开行为。在所有其他上下文中(包括嵌套在上述结构之内时),给组合值附加.*不会改变其值,因为它表示所有列,因此结果仍然是同一个组合值。例如,如果somefunc()接受一个组合值参数,这些查询就是等价的: + 当composite_value.*出现在SELECT输出列表、INSERT/UPDATE/DELETE/MERGE中的RETURNING列表、VALUES子句或行构造器的顶层时,就会产生这种列展开行为。在所有其他上下文中(包括嵌套在上述结构之内时),给复合值附加.*不会改变其值,因为它表示所有列,因此结果仍然是同一个复合值。例如,如果somefunc()接受一个复合值参数,这些查询就是等价的: SELECT somefunc(c.*) FROM inventory_item c; SELECT somefunc(c) FROM inventory_item c; - 在这两种情况下,inventory_item的当前行都会作为单个组合值参数传递给该函数。尽管.*在这种场合并不起作用,使用它仍是一种良好风格,因为它能明确表明这里想要的是组合值。特别是,解析器会把c.*中的c视为表名或别名,而不是列名,因此不会产生歧义;而没有.*时,就不清楚c究竟表示表名还是列名,而且如果存在名为c的列,实际上会优先按列名解释。 + 在这两种情况下,inventory_item的当前行都会作为单个复合值参数传递给该函数。尽管.*在这种场合并不起作用,使用它仍是一种良好风格,因为它能明确表明这里想要的是复合值。特别是,解析器会把c.*中的c视为表名或别名,而不是列名,因此不会产生歧义;而没有.*时,就不清楚c究竟表示表名还是列名,而且如果存在名为c的列,实际上会优先按列名解释。 @@ -278,7 +278,7 @@ SELECT * FROM inventory_item c ORDER BY c; SELECT * FROM inventory_item c ORDER BY c.*; SELECT * FROM inventory_item c ORDER BY ROW(c.*); - 所有这些ORDER BY子句都指定了该行的组合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: + 所有这些ORDER BY子句都指定了该行的复合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: SELECT * FROM inventory_item c ORDER BY ROW(c.name, c.supplier_id, c.price); SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); @@ -287,7 +287,7 @@ SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); - 另一种与组合值有关的特殊语法行为是,我们可以使用函数记法来提取组合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: + 另一种与复合值有关的特殊语法行为是,我们可以使用函数记法来提取复合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: SELECT c.name FROM inventory_item c WHERE c.price > 1000; @@ -306,11 +306,11 @@ SELECT c.somefunc FROM inventory_item c; 函数记法与字段记法之间的这种等价性,使得我们可以通过在复合类型上使用函数来实现计算字段 - computed field + 计算字段 - field - computed + 字段 + 计算 使用上面最后一种查询形式的应用程序,无需直接知道somefunc并不是该表中的真实列。 @@ -328,7 +328,7 @@ SELECT c.somefunc FROM inventory_item c; 复合类型的输入和输出语法 - 组合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明组合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 + 复合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明复合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 '( 42)' @@ -336,7 +336,7 @@ SELECT c.somefunc FROM inventory_item c; - 如前所示,在写组合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让组合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的组合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作组合语法的数据字符。 + 如前所示,在写复合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让复合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的复合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作复合语法的数据字符。 @@ -350,7 +350,7 @@ SELECT c.somefunc FROM inventory_item c; - 在 SQL 命令中编写组合值时,ROW构造器语法通常比组合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是组合成员时完全相同。 + 在 SQL 命令中编写复合值时,ROW构造器语法通常比复合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是复合成员时完全相同。 diff --git a/zh/19/textsearch.sgml b/zh/19/textsearch.sgml index d887dfc0..798fca2b 100644 --- a/zh/19/textsearch.sgml +++ b/zh/19/textsearch.sgml @@ -1,21 +1,21 @@ - 全文搜索 + 全文检索 - 全文搜索 + 全文检索 - 文本搜索 + 文本检索 介绍 - 全文搜索(或简称文本搜索)提供了识别满足 + 全文检索(或简称文本检索)提供了识别满足 查询条件的自然语言文档的能力, 并且可按它们与查询的相关度进行排序。最常见的搜索类型,是找出所有包含给定 查询词的文档,并按它们与查询的相似性 @@ -25,7 +25,7 @@ - 文本搜索操作符在数据库中已经存在很多年了。 + 文本检索操作符在数据库中已经存在很多年了。 PostgreSQL为文本数据类型提供了 ~~*LIKEILIKE 操作符,但它们缺少现代信息系统所要求的许多关键特性: @@ -138,7 +138,7 @@ ()。围绕这两种数据类型还有许多函数和 操作符(),其中最重要的是匹配操作符 @@,我们将在中介绍。 - 全文搜索还可以借助索引加速()。 + 全文检索还可以借助索引加速()。 @@ -147,11 +147,11 @@ 文档 - 全文搜索 + 文本检索 - 文档是全文搜索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本搜索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 + 文档是全文检索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本检索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 @@ -179,7 +179,7 @@ WHERE m.mid = d.did AND m.mid = 12; - 为了进行文本搜索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 + 为了进行文本检索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 @@ -187,7 +187,7 @@ WHERE m.mid = d.did AND m.mid = 12; 基本文本匹配 - 在PostgreSQL中,全文搜索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: + 在PostgreSQL中,全文检索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: SELECT 'a fat cat sat on a mat and ate a fat rat'::tsvector @@ 'cat & rat'::tsquery; @@ -203,7 +203,7 @@ SELECT 'fat & cow'::tsquery @@ 'a fat cat sat on a mat and ate a fat rat'::t - 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索术语,这些术语必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个术语组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本搜索匹配更像是这样: + 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索词,这些搜索词必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个搜索词组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本检索匹配更像是这样: SELECT to_tsvector('fat cats ate fat rats') @@ to_tsquery('fat & rat'); @@ -221,7 +221,7 @@ SELECT 'fat cats ate fat rats'::tsvector @@ to_tsquery('fat & rat'); f - 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,默认假定已经正规化,因此 rats 不会匹配 rat。 + 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,被假定为已经正规化,因此 rats 不会匹配 rat @@ -290,49 +290,49 @@ SELECT phraseto_tsquery('the cats ate the rats'); 配置 - 前述的都是简单的文本搜索示例。正如前面所提到的,全文搜索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如基于空白之外的解析。这个功能由文本搜索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 + 前述的都是简单的文本检索示例。正如前面所提到的,全文检索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如不局限于按空白划分的解析。这个功能由文本检索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 - 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本搜索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config。 + 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本检索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config - 依赖一个配置的每一个文本搜索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当这个参数被忽略时,default_text_search_config才被使用。 + 依赖一个配置的每一个文本检索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当省略这个参数时,default_text_search_config才被使用。 - 为了让建立自定义文本搜索配置更容易,一个配置可以从更简单的数据库对象来建立。PostgreSQL的文本搜索功能提供了四类配置相关的数据库对象: + 为了便于构建自定义文本检索配置,配置由更简单的数据库对象组合而成。PostgreSQL 的文本检索功能提供了四类与配置相关的数据库对象: - 文本搜索解析器将文档拆分成词元并分类每个词元(例如,作为词或者数字)。 + 文本检索解析器将文档拆分成词元并对每个词元分类(例如,作为词或者数字)。 - 文本搜索词典将词元转变成正规化的形式并拒绝停用词。 + 文本检索词典将词元转变成正规化的形式并拒绝停用词。 - 文本搜索模板提供位于词典底层的函数(一个词典简单地指定一个模板和一组用于模板的参数)。 + 文本检索模板提供位于词典底层的函数(词典只需指定一个模板及其一组参数)。 - 文本搜索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 + 文本检索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 - 文本搜索解析器和模板是从低层 C 函数构建而来,因此它要求 C 编程能力来开发新的解析器和模板,并且还需要超级用户权限来把它们安装到一个数据库中(在PostgreSQL发布的contrib/区域中有一些附加的解析器和模板的示例)。由于词典和配置只是对底层解析器和模板的参数化和连接,不需要特殊的权限来创建一个新词典或配置。创建定制词典和配置的示例将在本章稍后的部分给出。 + 文本检索解析器和模板由底层 C 函数构成,因此开发新的解析器和模板需要 C 编程能力,将它们安装到数据库中则需要超级用户权限。(PostgreSQL 发行版的 contrib/ 目录中有附加解析器和模板的示例。)词典和配置只是为底层解析器和模板设置参数并将它们连接起来,因此创建新词典或配置不需要特殊权限。本章后面会给出创建自定义词典和配置的示例。 @@ -343,14 +343,14 @@ SELECT phraseto_tsquery('the cats ate the rats'); 表和索引 - 在前一节中的示例演示了使用简单常数字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 + 在前一节中的示例演示了使用简单常量字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 搜索表 - 即使没有索引,也可以执行全文搜索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend: + 即使没有索引,也可以执行全文检索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend SELECT title @@ -374,7 +374,7 @@ WHERE to_tsvector(body) @@ to_tsquery('friend'); - 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 中同时包含 createtable: + 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 合在一起包含 createtable SELECT title @@ -388,7 +388,7 @@ LIMIT 10; - 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本搜索在实际使用中通常都需要建立索引。 + 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本检索在实际使用中通常都需要建立索引。 @@ -397,13 +397,13 @@ LIMIT 10; 创建索引 - 我们可以创建一个GIN索引()来加速文本搜索: + 我们可以创建一个GIN索引()来加速文本检索: CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector('english', body)); - 注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本搜索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含使用不同文本搜索配置创建的tsvector,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 + 注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本检索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含使用不同文本检索配置创建的tsvector,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 @@ -420,10 +420,7 @@ CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector(config_name, body)); 这里 config_namepgweb 表中的一个列。这样就允许在同一个索引中混合使用不同配置,同时记录每个索引项使用的是哪一种配置。例如,如果文档集合中包含不同语言的文档,这就会很有用。同样,打算使用该索引的查询也必须写成对应的形式,例如 WHERE to_tsvector(config_name, body) @@ 'a & b' - - 索引甚至可以连接列: - - + 索引甚至可以串接多个列: CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector('english', title || ' ' || body)); @@ -443,7 +440,7 @@ ALTER TABLE pgweb CREATE INDEX textsearch_idx ON pgweb USING GIN(textsearchable_index_col); - 现在我们准备好执行一个快速的全文搜索了: + 现在我们准备好执行一个快速的全文检索了: SELECT title @@ -455,7 +452,7 @@ LIMIT 10; - 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本搜索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 + 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本检索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 @@ -463,10 +460,10 @@ LIMIT 10; - 控制文本搜索 + 控制文本检索 - 要实现全文搜索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 + 要实现全文检索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 @@ -485,7 +482,7 @@ to_tsvector( config - to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本搜索配置进行处理。下面是一个简单示例: + to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本检索配置进行处理。下面是一个简单示例: SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); @@ -500,7 +497,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每类词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本搜索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english。 + to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每个词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本检索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english @@ -508,7 +505,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为空,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: + 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为 NULL,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: UPDATE tt SET ti = @@ -659,12 +656,12 @@ websearch_to_tsquery( config - 无引号文本:不在引号中的文本会被转换为由&操作符分隔的词,就像经过plainto_tsquery处理一样。 + 未加引号的文本:不在引号中的文本会被转换为由&操作符分隔的词,就像经过plainto_tsquery处理一样。 - "引号文本":引号中的文本会被转换为由<->操作符分隔的词,就像经过phraseto_tsquery处理一样。 + "加引号的文本":引号中的文本会被转换为由<->操作符分隔的词,就像经过phraseto_tsquery处理一样。 @@ -722,7 +719,7 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); 搜索结果排名 - 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及它们出现于文档中哪个部分。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 + 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及这些词所处文档部分的重要程度。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 @@ -813,12 +810,12 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 8 用文档中唯一词的数量除排名 + 8 用文档中不同词的数量除排名 - 16 用 1 + 文档中唯一词数量的对数除排名 + 16 用 1 + 文档中不同词数量的对数除排名 @@ -832,7 +829,7 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。正规化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 + 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。归一化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 @@ -904,7 +901,7 @@ ts_headline( config ts_headline 接收文档和查询,并返回文档中一段 - 高亮查询词条的摘录。具体而言,该函数会先用查询选择相关文本片段,然后 + 高亮查询词的摘录。具体而言,该函数会先用查询选择相关文本片段,然后 高亮查询中出现的所有词,即使这些词的位置并不满足查询本身的位置限制。 用于解析文档的配置可通过 config 指定; 若省略 config,则使用 @@ -1011,7 +1008,7 @@ occurrences to display in the result.', 附加特性 - 本节介绍一些在文本搜索中很有用的附加函数和操作符。 + 本节介绍一些在文本检索中很有用的附加函数和操作符。 @@ -1124,7 +1121,7 @@ occurrences to display in the result.', - 返回用 AND 结合的两个给定查询。 + 返回两个给定查询的 AND 组合。 @@ -1138,7 +1135,7 @@ occurrences to display in the result.', - 返回用 OR 结合的两个给定查询。 + 返回两个给定查询的 OR 组合。 @@ -1191,7 +1188,7 @@ SELECT to_tsquery('fat') <-> to_tsquery('cat | rat'); - 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: + 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在其后距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: SELECT tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10); @@ -1245,10 +1242,7 @@ SELECT numnode('foo & bar'::tsquery); - - 返回可用于索引搜索的tsquery部分。这个函数可用于检测不可索引的查询,例如只包含停用词或只包含否定项的查询。例如: - - + 返回一个tsquery中可用于搜索索引的部分。此函数可用于检测无法使用索引的查询,例如只包含停用词或只包含否定词项的查询。例如: SELECT querytree(to_tsquery('defined')); querytree ----------- @@ -1424,7 +1418,7 @@ SELECT title, body FROM messages WHERE tsv @@ to_tsquery('title & body'); - 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本搜索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 + 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本检索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 @@ -1491,7 +1485,7 @@ ts_stat(sqlquery text, - 如果提供了 weights,则只统计具有这些权重之一的出现。 + 如果提供了 weights,则只统计具有这些权重之一的词的出现次数。 @@ -1520,7 +1514,7 @@ LIMIT 10; 解析器 - 文本搜索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 + 文本检索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 @@ -1543,12 +1537,12 @@ LIMIT 10; asciiword - 单词,所有 ASCII 字母 + 单词,全部由 ASCII 字母组成 elephant word - 单词,所有字母 + 单词,全部由字母组成 mañana @@ -1558,12 +1552,12 @@ LIMIT 10; asciihword - 带连字符的单词,所有 ASCII + 带连字符的单词,全部为 ASCII 字符 up-to-date hword - 带连字符的单词,所有字母 + 带连字符的单词,由字母组成 lógico-matemática @@ -1573,12 +1567,12 @@ LIMIT 10; hword_asciipart - 带连字符的单词部分,所有 ASCII + 带连字符的单词部分,全部为 ASCII 字符 postgresql-beta1 上下文中的 postgresql hword_part - 带连字符的单词部分,所有字母 + 带连字符的单词部分,全部由字母组成 lógico-matemática 上下文中的 lógicomatemática @@ -1653,8 +1647,8 @@ LIMIT 10; blank - 空格符号 - (其他不识别的任意空白或标点符号) + 空白符号 + (未被识别为其他类型的空白或标点符号) @@ -1662,12 +1656,12 @@ LIMIT 10; - 解析器的一个字母的概念由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时可以用来区别它们。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 + 解析器对字母的界定由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时区分它们会很有用。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 email不支持所有由RFC 5322定义的有效电子邮件字符。 - 具体来说,电子邮件用户名仅支持句号、短横线和下划线这些非字母数字字符。 + 具体来说,电子邮件用户名仅支持句点、短横线和下划线这些非字母数字字符。 @@ -1716,7 +1710,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h 词典 - 词典用于消除不应参与搜索的词(stop words),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 + 词典用于消除不应参与搜索的词(停用词),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 @@ -1731,7 +1725,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - URL地址可以被正规化,以便让等价的 URL 匹配: + URL 地址可以规范化,以便让等价的 URL 匹配: @@ -1776,32 +1770,32 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤字典) + 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤词典 - 如果字典知道该词元但它是一个停用词,则返回一个空数组 + 如果词典知道该词元但它是一个停用词,则返回一个空数组 - 如果字典不识别该输入词元,则返回NULL + 如果词典不识别该输入词元,则返回NULL - PostgreSQL为许多语言提供了预定义的字典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发布的contrib/区域。 + PostgreSQL为许多语言提供了预定义的词典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发行版的contrib/目录。 - 文本搜索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 + 文本检索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 - 配置词典列表的一般规则是,把最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语分类词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: + 配置词典列表的一般规则是,把适用范围最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语同义词词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: ALTER TEXT SEARCH CONFIGURATION astro_en @@ -1810,14 +1804,14 @@ ALTER TEXT SEARCH CONFIGURATION astro_en - 过滤词典可以放在列表中的任何位置,只是不能放在最后,因为放在最后就没有意义了。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 + 过滤词典可以放在列表中的任何位置,但放在末尾没有用处。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 停用词 - 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文搜索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: + 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文检索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: SELECT to_tsvector('english', 'in the list of stop words'); @@ -1949,7 +1943,7 @@ SELECT * FROM ts_debug('english', 'Paris'); - synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基本名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 + synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 @@ -2011,28 +2005,28 @@ mydb=# SELECT 'indexes are very useful'::tsvector @@ to_tsquery('tst', 'indices' - 基本上一个分类词典会用一个首选词替换所有非首选词,并且也可选择地保留原始术语用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典要求一个下列格式的配置文件: + 分类词典基本上会用一个首选词替换所有非首选词,并且也可以选择保留原始词用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典需要一个采用以下格式的配置文件: -# this is a comment -sample word(s) : indexed word(s) -more sample word(s) : more indexed word(s) +# 这是一条注释 +示例词(一个或多个) : 索引词(一个或多个) +更多示例词(一个或多个) : 更多索引词(一个或多个) ... - 其中冒号(:)符号扮演了一个短语及其替换之间的定界符。 + 其中冒号(:)符号用作短语及其替换词之间的分隔符。 - 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过对子词典的应用,但所有样例词都必须能被子词典识别。 + 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过将子词典应用于该词,但所有样例词都必须能被子词典识别。 - 如果有多个短语匹配输入,则分类词典选择最长的那一个,并且使用最后的定义打破连结。 + 如果有多个短语匹配输入,分类词典会选择最长的匹配;长度相同时使用最后的定义。 - 由子词典识别的特定停用词不能够被指定;改用?标记任何可以出现停用词的地方。例如,假定根据子词典athe是停用词: + 由子词典识别的特定停用词不能够被指定;改用?标记可出现任意停用词的位置。例如,假定根据子词典athe是停用词: ? one ? two : swsw @@ -2074,7 +2068,7 @@ CREATE TEXT SEARCH DICTIONARY thesaurus_simple ( - mythesaurus是分类词典配置文件的基础名称(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 + mythesaurus是分类词典配置文件的基名(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 @@ -2099,7 +2093,7 @@ ALTER TEXT SEARCH CONFIGURATION russian 分类词典示例 - 考虑简单的天文词库 thesaurus_astro,其中包含一些天文单词组合: + 考虑一个简单的天文分类词典 thesaurus_astro,其中包含一些天文单词组合: supernovae stars : sn @@ -2167,7 +2161,7 @@ SELECT plainto_tsquery('supernova star'); <application>Ispell</application> 词典 - Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以把搜索词 bank 的词尾变化和词形变化对应起来,例如 bankingbankedbanksbanks'bank's。 + Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以匹配搜索词 bank 的所有变格和变位形式,例如 bankingbankedbanksbanks'bank's @@ -2179,12 +2173,12 @@ SELECT plainto_tsquery('supernova star'); - 要创建一个Ispell词典,执行这三步: + 要创建一个Ispell词典,请执行以下步骤: - 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。有必要抽取.aff.dic文件,把扩展改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): + 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。需要提取.aff.dic文件,将扩展名改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): iconv -f ISO_8859-1 -t UTF-8 -o nn_no.affix nn_NO.aff iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic @@ -2193,7 +2187,7 @@ iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic - 拷贝文件到$SHAREDIR/tsearch_data目录 + 复制文件到$SHAREDIR/tsearch_data目录 @@ -2211,11 +2205,11 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( - 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基础名称。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 + 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基名。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 - Ispell 词典通常识别一个有限集合的词,这样它们后面应该跟着另一个更广义的词典;例如,一个 Snowball 词典,它可以识别所有东西。 + Ispell 词典通常只能识别有限的词,因此其后应跟着另一个覆盖范围更广的词典;例如,一个 Snowball 词典,它可以识别所有输入。 @@ -2223,13 +2217,13 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( prefixes flag *A: - . > RE # As in enter > reenter + . > RE # 例如 enter > reenter suffixes flag T: - E > ST # As in late > latest - [^AEIOU]Y > -Y,IEST # As in dirty > dirtiest - [AEIOU]Y > EST # As in gray > grayest - [^EY] > EST # As in small > smallest + E > ST # 例如 late > latest + [^AEIOU]Y > -Y,IEST # 例如 dirty > dirtiest + [AEIOU]Y > EST # 例如 gray > grayest + [^EY] > EST # 例如 small > smallest @@ -2245,14 +2239,14 @@ lark/MRS .dict文件的格式是: -basic_form/affix_class_name +基本词形/词缀类名 .affix文件中,每一个词缀标志以下面的格式描述: -condition > [-stripping_letters,] adding_affix +条件 > [-删除的字母,] 添加的词缀 @@ -2261,7 +2255,7 @@ condition > [-stripping_letters,] adding_affix - Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,它标记可以参与到复合格式中的词典词: + Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,用于标记词典中可以参与构成复合词的词: compoundwords controlled z @@ -2291,7 +2285,7 @@ SFX T 0 est [^ey] - 一个词缀类的第一行是头部。头部后面列出了词缀规则的域: + 一个词缀类的第一行是首部。首部后面列出了词缀规则的字段: @@ -2343,7 +2337,7 @@ largehearted <application>Snowball</application> 词典 - Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每一个算法懂得按照其语言中的拼写,如何缩减词的常见变体形式为一个基础或词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择地指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。 + Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每种算法都知道如何把其语言中词的常见变体约简为基本拼写形式,也就是词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。 @@ -2404,7 +2398,7 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( - 一个Snowball词典识别所有的东西,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 + 一个Snowball词典识别所有输入,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 @@ -2415,11 +2409,11 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( 配置示例 - 一个文本搜索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本搜索配置来执行其处理。配置参数指定了默认配置的名称,如果忽略了显式的配置参数,文本搜索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 + 一个文本检索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本检索配置来执行其处理。配置参数指定了默认配置的名称,如果省略了显式的配置参数,文本检索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 - 有一些预定义的文本搜索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本搜索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本搜索对象()的信息。 + 有一些预定义的文本检索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本检索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本检索对象()的信息。 @@ -2511,17 +2505,17 @@ SHOW default_text_search_config; - 测试和调试文本搜索 + 测试和调试文本检索 - 一个自定义文本搜索配置的行为很容易变得混乱。本节中描述的函数对于测试文本搜索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 + 一个自定义文本检索配置的行为很容易让人困惑。本节中描述的函数对于测试文本检索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 配置测试 - 函数ts_debug允许简单地测试一个文本搜索配置。 + 函数ts_debug可方便地测试一个文本检索配置。 @@ -2540,7 +2534,7 @@ ts_debug( config re - ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果该参数被忽略则使用default_text_search_config指定的配置。 + ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果省略该参数则使用default_text_search_config指定的配置。 @@ -2615,7 +2609,7 @@ SELECT * FROM ts_debug('english', 'a fat cat sat on a mat - it ate a fat rats') - 为了一个更广泛的示范,我们先为英语语言创建一个public.english配置和 Ispell 词典: + 为了做更完整的演示,我们先为英语创建一个public.english配置和 Ispell 词典: @@ -2673,7 +2667,7 @@ FROM ts_debug('public.english', 'The Brightest supernovaes'); 解析器测试 - 下列函数允许直接测试一个文本搜索解析器。 + 下列函数允许直接测试一个文本检索解析器。 @@ -2715,7 +2709,7 @@ ts_token_type(parser_oid oid< - ts_token_type返回一个表,描述指定解析器能够识别的每一种词元。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: + ts_token_type返回一个表,描述指定解析器能够识别的每一种词元类型。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: SELECT * FROM ts_token_type('default'); @@ -2753,7 +2747,7 @@ SELECT * FROM ts_token_type('default'); 词典测试 - ts_lexize函数帮助词典测试。 + ts_lexize函数便于测试词典。 @@ -2811,17 +2805,17 @@ SELECT plainto_tsquery('supernovae stars'); - 文本搜索的首选索引类型 + 文本检索的首选索引类型 - 文本搜索 + 文本检索 索引 - 有两种索引可以用来加速全文搜索:GIN和 + 有两种索引可以用来加速全文检索:GINGiST。 - 请注意,索引对于全文搜索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 + 请注意,索引对于全文检索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 @@ -2835,7 +2829,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GIN - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIN (column); @@ -2855,7 +2849,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GiST - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIST (column [ { DEFAULT | tsvector_ops } (siglen = number) ] ); @@ -2865,7 +2859,7 @@ SELECT plainto_tsquery('supernovae stars'); 创建基于 GiST(广义搜索树)的索引。 column可以是tsvectortsquery类型。 - 可选的整数参数siglen确定签名长度(有关详细信息,请参见下文)。 + 可选的整数参数siglen确定以字节为单位的签名长度(有关详细信息,请参见下文)。 @@ -2874,7 +2868,7 @@ SELECT plainto_tsquery('supernovae stars'); - GIN 索引是文本搜索的首选索引类型。作为倒排索引,每个词(词位)在 + GIN 索引是文本检索的首选索引类型。作为倒排索引,每个词(词位)在 其中都有一个索引项,其中有压缩过的匹配位置的列表。多词搜索可以找到 第一个匹配,然后使用该索引移除缺少额外词的行。GIN 索引只存储 tsvector值的词(词位),并且不存储它们的权重标签。因此, @@ -2882,19 +2876,19 @@ SELECT plainto_tsquery('supernovae stars'); - 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。以字节为单位的签名长度由可选整数参数 siglen 的值决定。 默认签名长度(未指定 siglen 时)为 124 字节,最大签名长度为 2024 字节。该签名通过哈希每一个词到一个 n 位串中的一个单一位来产生,通过将所有这些位 OR 在一起产生一个 n 位的文档签名。当两个词哈希到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。更长的签名导致更精确的搜索(扫描索引的一小部分和更少的堆页面),但代价是更大的索引。 + 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。以字节为单位的签名长度由可选整数参数 siglen 的值决定。 默认签名长度(未指定 siglen 时)为 124 字节,最大签名长度为 2024 字节。该签名通过将每个词 hash 到一个 n 位串中的一位,再将所有这些位进行 OR 运算来生成,结果是一个 n 位的文档签名。当两个词 hash 到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。更长的签名导致更精确的搜索(扫描更小比例的索引和更少的堆页面),但代价是更大的索引。 - GiST 可以构建为覆盖索引,例如使用 INCLUDE 子句。被包含的列可以具有没有任何 GiST 操作符类的数据类型。被包含的属性会以未压缩形式存储。 + GiST 可以构建为覆盖索引,即使用 INCLUDE 子句。被包含的列可以具有没有任何 GiST 操作符类的数据类型。被包含的属性会以未压缩形式存储。 - 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的可用性。假匹配的可能性取决于几个因素,特别是唯一词的数量,因此推荐使用词典来缩减这个数量。 + 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的实用性。假匹配的可能性取决于几个因素,特别是不同词的数量,因此推荐使用词典来缩减这个数量。 - 注意GIN索引的构件时间常常可以通过增加来改进,而GiST索引的构建时间则与该参数无关。 + 注意GIN索引的构建时间常常可以通过增加来改进,而GiST索引的构建时间则对该参数不敏感。 @@ -2908,7 +2902,7 @@ SELECT plainto_tsquery('supernovae stars'); <application>psql</application> 支持 - 关于文本搜索配置对象的信息可以在psql中使用一组命令获得: + 关于文本检索配置对象的信息可以在psql中使用一组命令获得: \dF{d,p,t}+ PATTERN @@ -2916,7 +2910,7 @@ SELECT plainto_tsquery('supernovae stars'); - 可选参数 PATTERN 可以是文本搜索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: + 可选参数 PATTERN 可以是文本检索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: => \dF *fulltext* @@ -2943,7 +2937,7 @@ SELECT plainto_tsquery('supernovae stars'); \dF+ PATTERN - 列出文本搜索配置(加上 + 可显示更多细节)。 + 列出文本检索配置(加上 + 可显示更多细节)。 => \dF russian List of text search configurations @@ -2984,7 +2978,7 @@ Parser: "pg_catalog.default" \dFd+ PATTERN - 列出文本搜索词典(加上 + 可显示更多细节)。 + 列出文本检索词典(加上 + 可显示更多细节)。 => \dFd List of text search dictionaries @@ -3031,7 +3025,7 @@ Parser: "pg_catalog.default" \dFp+ PATTERN - 列出文本搜索解析器(加上 + 可显示更多细节)。 + 列出文本检索解析器(加上 + 可显示更多细节)。 => \dFp List of text search parsers @@ -3084,7 +3078,7 @@ Parser: "pg_catalog.default" \dFt+ PATTERN - 列出文本搜索模板(加上 + 可显示更多细节)。 + 列出文本检索模板(加上 + 可显示更多细节)。 => \dFt List of text search templates @@ -3107,7 +3101,7 @@ Parser: "pg_catalog.default" 限制 - PostgreSQL 当前文本搜索特性的限制如下: + PostgreSQL 当前文本检索特性的限制如下: 每个词位的长度必须小于 2 千字节 @@ -3131,12 +3125,12 @@ Parser: "pg_catalog.default" - 为了对比,PostgreSQL 8.1 的文档包含 10,441 个唯一词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 + 为了对比,PostgreSQL 8.1 的文档包含 10,441 个不同词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 - 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个唯一词。 + 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个不同词。 diff --git a/zh/19/unaccent.sgml b/zh/19/unaccent.sgml index 645d82f8..bd8d629b 100644 --- a/zh/19/unaccent.sgml +++ b/zh/19/unaccent.sgml @@ -1,18 +1,18 @@ - unaccent — 去除变音符号的文本搜索词典 + unaccent — 去除变音符号的文本检索词典 unaccent - unaccent是一个文本搜索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤字典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文搜索能够以不区分重音的方式处理文本。 + unaccent是一个文本检索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤词典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文检索能够以不区分重音的方式处理文本。 - unaccent当前的实现还不能作为thesaurus词典的正规化字典使用。 + unaccent当前的实现还不能作为thesaurus词典的正规化词典使用。 @@ -79,7 +79,7 @@ - 与其他PostgreSQL文本搜索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含不可转换字符的行都会被静默忽略,因此规则文件中可以包含不适用于当前编码的规则。 + 与其他PostgreSQL文本检索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含不可转换字符的行都会被静默忽略,因此规则文件中可以包含不适用于当前编码的规则。 @@ -93,7 +93,7 @@ 用法 - 安装unaccent扩展会创建一个文本搜索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 + 安装unaccent扩展会创建一个文本检索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 mydb=# ALTER TEXT SEARCH DICTIONARY unaccent (RULES='my_rules'); @@ -114,7 +114,7 @@ mydb=# ALTER TEXT SEARCH DICTIONARY unaccent (RULES='my_rules'); - 下面的示例展示了如何将unaccent词典插入到文本搜索配置中: + 下面的示例展示了如何将unaccent词典插入到文本检索配置中: mydb=# CREATE TEXT SEARCH CONFIGURATION fr ( COPY = french ); mydb=# ALTER TEXT SEARCH CONFIGURATION fr @@ -145,7 +145,7 @@ mydb=# SELECT ts_headline('fr', 'Hôtel de la Mer', to_tsquery('fr', 'Hotel 函数 - unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本搜索环境之外使用。 + unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本检索环境之外使用。 @@ -157,7 +157,7 @@ unaccent(dictionary - 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本搜索词典。 + 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本检索词典。 diff --git a/zh/20/array.sgml b/zh/20/array.sgml index 10cc5e41..ead7c881 100644 --- a/zh/20/array.sgml +++ b/zh/20/array.sgml @@ -4,7 +4,7 @@ 数组 - array + 数组 @@ -15,8 +15,8 @@ 数组类型的声明 - array - declaration + 数组 + 声明 @@ -64,8 +64,8 @@ CREATE TABLE tictactoe ( 数组值输入 - array - constant + 数组 + 常量 @@ -86,7 +86,7 @@ CREATE TABLE tictactoe ( (这类数组常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。必要时可能需要显式指定类型。) + linkend="sql-syntax-constants-generic"/>中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给数组输入转换例程。可能需要显式指定类型。) @@ -119,7 +119,7 @@ SELECT * FROM sal_emp; - 多维数组在每个维度上的范围必须匹配。不匹配会导致错误,例如: + 多维数组的各个子数组在每个维度上的长度必须匹配。不匹配会导致错误,例如: INSERT INTO sal_emp @@ -152,8 +152,8 @@ INSERT INTO sal_emp 访问数组 - array - accessing + 数组 + 访问 @@ -186,9 +186,9 @@ SELECT pay_by_quarter[3] FROM sal_emp; - 我们还可以访问数组或子数组的任意矩形切片。数组切片通过在一个或多个数组维度上写成 + 我们还可以访问数组的任意矩形切片,即子数组。数组切片通过在一个或多个数组维度上写成 lower-bound:upper-bound - 的形式来表示。例如,下面这个查询取回 Bill 在一周前两天日程安排中的第一个项目: + 的形式来表示。例如,下面这个查询取回 Bill 在一周中前两天里每天的首项日程: SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill'; @@ -235,11 +235,11 @@ SELECT schedule[:][1:1] FROM sal_emp WHERE name = 'Bill'; - 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回空值。此外,如果下标超出数组边界,也会返回空值(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是空值而不是错误。 + 如果数组本身或任一下标表达式为 NULL,则数组下标表达式将返回 NULL。此外,如果下标超出数组边界,也会返回 NULL(这种情况不会报错)。例如,如果 schedule 当前的维度是 [1:3][1:2],那么引用 schedule[3][3] 会得到 NULL。类似地,使用错误数量的下标访问数组,得到的也是 NULL 而不是错误。 - 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回空值。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是空值。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回空值。 + 同样地,如果数组本身或任一下标表达式为 NULL,数组切片表达式也会返回 NULL。不过,在其他情况下,例如选择一个完全位于当前数组边界之外的数组切片时,切片表达式返回的是空(零维)数组而不是 NULL。(这与非切片行为不一致,是出于历史原因。)如果所请求的切片与数组边界仅部分重叠,那么它会被静默缩减为重叠区域,而不是返回 NULL。 @@ -293,8 +293,8 @@ SELECT cardinality(schedule) FROM sal_emp WHERE name = 'Carol'; 修改数组 - array - modifying + 数组 + 修改 @@ -331,7 +331,7 @@ UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}' - 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用空值填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含空值。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 + 已存储的数组值可以通过给尚不存在的元素赋值来扩展。原有元素与新赋值元素之间的任何位置都将用 NULL 填充。例如,如果数组 myarray 当前有 4 个元素,那么在一次更新把值赋给 myarray[6] 之后,它将有 6 个元素;myarray[5] 将包含 NULL。目前,以这种方式扩展只允许用于一维数组,不允许用于多维数组。 @@ -443,21 +443,21 @@ SELECT array_cat(ARRAY[5,6], ARRAY[[1,2],[3,4]]); 在简单情况下,优先使用上面讨论的连接操作符,而不是直接调用这些函数。不过,由于连接操作符被重载以同时服务于这三种情形,所以在某些场景下使用这些函数之一有助于避免歧义。例如,考虑: -SELECT ARRAY[1, 2] || '{3, 4}'; -- the untyped literal is taken as an array +SELECT ARRAY[1, 2] || '{3, 4}'; -- 未指定类型的字面量被当作数组 ?column? ----------- {1,2,3,4} -SELECT ARRAY[1, 2] || '7'; -- so is this one +SELECT ARRAY[1, 2] || '7'; -- 这个字面量也一样 ERROR: malformed array literal: "7" -SELECT ARRAY[1, 2] || NULL; -- so is an undecorated NULL +SELECT ARRAY[1, 2] || NULL; -- 未加类型修饰的 NULL 也一样 ?column? ---------- {1,2} (1 row) -SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant +SELECT array_append(ARRAY[1, 2], NULL); -- 这可能才是原本想表达的意思 array_append -------------- {1,2,NULL} @@ -471,8 +471,8 @@ SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant 在数组中搜索 - array - searching + 数组 + 搜索 @@ -552,7 +552,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); 数组输入和输出语法 - array + 数组 I/O @@ -565,7 +565,7 @@ SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1); - 默认情况下,数组各维度的下界索引值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: + 默认情况下,数组各维度的下界下标值都设为 1。要表示具有其他下界的数组,可以在写出数组内容之前显式指定数组下标范围。这种修饰由包围每个数组维度上下界的方括号([])构成,中间以冒号(:)作为分隔符字符。数组维度修饰后面再跟一个等号(=)。例如: SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2 FROM (SELECT '[1:1][-2:-1][3:5]={{{1,2,3},{4,5,6}}}'::int[] AS f1) AS ss; diff --git a/zh/20/catalogs.sgml b/zh/20/catalogs.sgml index 3388c164..28a87c67 100644 --- a/zh/20/catalogs.sgml +++ b/zh/20/catalogs.sgml @@ -320,27 +320,27 @@ pg_ts_config - 文本搜索配置 + 文本检索配置 pg_ts_config_map - 文本搜索配置的词元映射 + 文本检索配置的词元映射 pg_ts_dict - 文本搜索字典 + 文本检索词典 pg_ts_parser - 文本搜索分析器 + 文本检索解析器 pg_ts_template - 文本搜索模板 + 文本检索模板 @@ -7898,12 +7898,12 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config目录包含表示文本搜索配置的条目。一个配置指定某个特定的文本搜索分析器,以及针对该分析器每种输出词元类型所定义的字典列表。分析器由pg_ts_config项表示,而词元到字典的映射则由pg_ts_config系统目录包含表示文本检索配置的条目。一个配置指定某个特定的文本检索解析器,以及针对该解析器每种输出词元类型所定义的词典列表。解析器记录在pg_ts_config条目中,而词元到词典的映射则由pg_ts_config_map中的辅助项定义。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。 @@ -7935,7 +7935,7 @@ SCRAM-SHA-256$<iteration count>:&l cfgname name - 文本搜索配置名 + 文本检索配置名 @@ -7965,7 +7965,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_ts_parser.oid - 该配置的文本搜索分析器的OID + 该配置的文本检索解析器的 OID @@ -7982,11 +7982,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_config_map目录包含的项展示了对于每一个文本搜索配置的每一种输出词元类型,有哪些文本搜索字典可供查询以及以何种顺序。 + pg_ts_config_map 系统目录中的条目说明了,对于每个文本检索配置所用解析器的每种输出词元类型,应当查询哪些文本检索词典以及查询的顺序。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -8019,7 +8019,7 @@ SCRAM-SHA-256$<iteration count>:&l maptokentype int4 - 一种由配置的分析器送出的词元类型 + 一种由配置的解析器送出的词元类型 @@ -8038,7 +8038,7 @@ SCRAM-SHA-256$<iteration count>:&l (参考 pg_ts_dict.oid - 要查询的文本搜索字典的OID + 要查询的文本检索词典的 OID @@ -8055,11 +8055,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_dict目录包含定义文本搜索字典的项。一个字典依赖于一个文本搜索模板,它指定了所有需要的函数实现,字典本身则为模板支持的用户可设置参数提供值。这种分工允许无权限的用户创建字典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 + pg_ts_dict系统目录包含定义文本检索词典的项。一个词典依赖于一个文本检索模板,它指定了所有需要的实现函数,词典本身则为模板支持的用户可设置参数提供值。这种分工允许普通用户创建词典。参数由一个文本串dictinitoption定义,其格式和意义随着模板而变化。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -8091,7 +8091,7 @@ SCRAM-SHA-256$<iteration count>:&l dictname name - 文本搜索字典名 + 文本检索词典名 @@ -8101,7 +8101,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_namespace.oid - 包含该字典的名字空间OID + 包含该词典的名字空间的 OID @@ -8111,7 +8111,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_authid.oid - 字典的拥有者 + 词典的拥有者 @@ -8121,7 +8121,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_ts_template.oid - 该字典的文本搜索模板的OID + 该词典的文本检索模板的 OID @@ -8147,11 +8147,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_parser目录包含定义文本搜索分析器的项。一个分析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个分析器必须用C语言级别的函数实现,创建新分析器的工作只限于数据库的超级用户。 + pg_ts_parser系统目录包含定义文本检索解析器的项。一个解析器负责将输入文本分割成词位并为每一个词位分配一个词元类型。由于一个解析器必须用 C 语言级别的函数实现,创建新解析器的工作只限于数据库的超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -8183,7 +8183,7 @@ SCRAM-SHA-256$<iteration count>:&l prsname name - 文本搜索分析器的名字 + 文本检索解析器的名字 @@ -8193,7 +8193,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_namespace.oid - 包含此分析器的名字空间的OID + 包含此解析器的名字空间的 OID @@ -8203,7 +8203,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器启动函数的OID + 解析器启动函数的 OID @@ -8213,7 +8213,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的下一词元函数的OID + 解析器的下一词元函数的 OID @@ -8223,7 +8223,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的关闭函数的OID + 解析器的关闭函数的 OID @@ -8233,7 +8233,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器标题函数的 OID(如果没有则为零) + 解析器的 headline 函数的 OID(如果没有则为零) @@ -8243,7 +8243,7 @@ SCRAM-SHA-256$<iteration count>:&l (引用 pg_proc.oid - 分析器的词汇类型函数的OID + 解析器的 lextype 函数的 OID @@ -8260,11 +8260,11 @@ SCRAM-SHA-256$<iteration count>:&l - pg_ts_template目录包含定义文本搜索模板的项。一个模板是一类文本搜索字典的实现骨架。由于一个模板必须用C语言级别的函数实现,新模板的创建只限于数据库超级用户。 + pg_ts_template系统目录包含定义文本检索模板的项。一个模板是一类文本检索词典的实现骨架。由于一个模板必须用 C 语言级别的函数实现,新模板的创建只限于数据库超级用户。 - PostgreSQL的文本搜索特性在中有更详尽的描述。 + PostgreSQL的文本检索特性在中有更详尽的描述。
@@ -8296,7 +8296,7 @@ SCRAM-SHA-256$<iteration count>:&l tmplname name - 文本搜索模板的名字 + 文本检索模板的名字 diff --git a/zh/20/client-auth.sgml b/zh/20/client-auth.sgml index ecf573bf..98fa9691 100644 --- a/zh/20/client-auth.sgml +++ b/zh/20/client-auth.sgml @@ -1688,7 +1688,7 @@ host ... ldap ldapbasedn="dc=example,dc=net" scope - 一个以空格分隔的 OAuth 作用域(scope)列表,服务器需要借此既能授权客户端,又能认证用户。合适的取值由授权服务器以及所使用的 OAuth 验证模块决定(关于验证器的更多信息,见 )。此参数为必需项。 + 一个以空格分隔的 OAuth 授权范围列表,服务器需要借此既能授权客户端,又能认证用户。合适的取值由授权服务器以及所使用的 OAuth 验证模块决定(关于验证器的更多信息,见 )。此参数为必需项。 diff --git a/zh/20/config.sgml b/zh/20/config.sgml index 96395028..f273e0d8 100644 --- a/zh/20/config.sgml +++ b/zh/20/config.sgml @@ -3108,7 +3108,7 @@ include_dir 'conf.d' 配置 - 恢复的 + 恢复 一般设置 @@ -3166,7 +3166,7 @@ include_dir 'conf.d' 配置 恢复 - 一个备库 + 备库 @@ -3637,7 +3637,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows - 列出安装在 所指定位置中、同时也被信任可供复制客户端用作逻辑输出插件的库。 + 列出安装在 所指定位置中、同时也受信任、可供复制客户端用作逻辑输出插件的库。 任何针对其他库的逻辑解码或 复制请求都将被拒绝。所有用户都受此限制。 默认值为 'pgoutput, test_decoding',它们是标准 @@ -4365,8 +4365,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( )。 + 设置规划器对一系列顺序磁盘页面读取中单次读取的代价估计。默认值是 1.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -4799,7 +4792,7 @@ ANY num_sync ( )。 + 设置规划器对一次非顺序磁盘页面读取的代价估计。默认值是 4.0。对于某个表空间内的表和索引,可以通过设置该表空间的同名参数来覆盖此值(见)。 @@ -4812,14 +4805,13 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( 。 如果指定值时没有单位,则以块为单位,即BLCKSZ字节,通常为8kB。默认值是512千字节(512kB)。 @@ -4945,13 +4937,13 @@ ANY num_sync ( num_sync ( - 遗传查询优化 + 遗传查询优化器 - GEQO是一个使用探索式搜索来执行查询规划的算法。它可以降低负载查询的规划时间。 同时,GEQO的检索是随机的,因此它的规划可能会不可确定。 更多信息参阅Chapter 50。 - 遗传查询规划器(GEQO)是一种使用启发式搜索来进行查询规划的算法。它可以降低对于复杂查询(连接很多表的查询)的规划时间,但是代价是它产生的计划有时候要差于使用穷举搜索算法找到的计划。详见。 + 遗传查询优化器(GEQO)是一种使用启发式搜索进行查询规划的算法。它可以缩短复杂查询(连接很多关系的查询)的规划时间,代价是生成的计划有时不如常规穷举搜索算法找到的计划。更多信息见 @@ -5047,7 +5038,7 @@ ANY num_sync ( num_sync ( num_sync ( num_sync ( num_sync ( .) + 目前,约束排除仅在通常用于通过继承树实现表分区的情况下默认启用。为所有表启用它会增加额外的规划开销,这在简单查询上相当明显,而且通常不会为简单查询带来好处。如果没有通过传统继承方式进行分区的表,你可能希望完全关闭它。(注意,分区表的等效功能由另一个参数控制。) @@ -5296,13 +5284,7 @@ SELECT * FROM parent WHERE key = 2400; - 准备语句(显式准备或隐式生成的,例如 PL/pgSQL)可以使用自定义或通用计划执行。 - 使用其特定的参数值集为每个执行重新生成自定义计划,而通用计划不依赖于参数值,并且可以在执行中重复使用。 - 因此,使用通用计划可以节省计划时间,但如果理想计划严重依赖参数值,则通用计划可能效率低下。 - 这些选项之间的选择通常是自动进行的,但可以通过plan_cache_mode覆盖它。 - 允许的值为 auto (默认的),force_custom_planforce_generic_plan。 - 这个设置是在执行缓存计划时考虑,而不是在准备计划时考虑。 - 更多信息请参阅 . + 预备语句(无论是显式预备的,还是由 PL/pgSQL 等隐式生成的)可以使用自定义计划或通用计划执行。自定义计划会根据每次执行的具体参数值重新生成,而通用计划不依赖参数值,可以在多次执行之间复用。因此,使用通用计划能够节省规划时间,但如果理想计划高度依赖参数值,通用计划可能效率较低。系统通常会自动选择这两种计划,但可以通过plan_cache_mode覆盖这一选择。允许的值为auto(默认值)、force_custom_planforce_generic_plan。系统在执行缓存计划时考虑此设置,而不是在预备计划时。更多信息见 @@ -5320,7 +5302,7 @@ SELECT * FROM parent WHERE key = 2400; 设置规划器对递归查询 的工作表的平均大小的估计值,作为查询初始非递归项的估计大小的倍数。 这有助于规划器选择将工作表与查询的其他表连接的最合适方法。 - 默认值为10.0。当递归从一步到下一步的fan-out较低时,如最短路径查询中的示例,使用较小的值(如1.0)可能有所帮助。 + 默认值为10.0。当递归从一步到下一步的扇出较低时,例如最短路径查询,使用较小的值(如1.0)可能有所帮助。 图分析查询可能会从大于默认值的设置中受益。 @@ -5339,7 +5321,7 @@ SELECT * FROM parent WHERE key = 2400; - 在哪里做日志 + 日志记录到哪里 日志写到哪里 @@ -5347,7 +5329,7 @@ SELECT * FROM parent WHERE key = 2400; current_logfiles - 和日志_目的地配置参数 + 和 log_destination 配置参数 @@ -5395,13 +5377,13 @@ jsonlog log/postgresql.json 当由于轮换而创建新的日志文件时,以及重新加载log_destination时,current_logfiles会被重新创建。 当log_destination中不包含stderrcsvlogjsonlog, - 以及日志收集器被禁用时,它会被移除。 + 或者日志收集器被禁用时,它会被移除。 - 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设备LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: + 在大多数 Unix 系统上,你将需要修改系统的syslog守护进程的配置来使用log_destinationsyslog选项。PostgreSQL可以在syslog设施LOCAL0LOCAL7中记录(见),但是大部分平台上的默认syslog配置会丢弃所有这种消息。你将需要增加这样的内容: local0.* /var/log/postgresql @@ -5409,7 +5391,7 @@ local0.* /var/log/postgresql - 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源极其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见。 + 在 Windows 上,当你使用log_destinationeventlog选项时,你应该在操作系统中注册一个事件源及其库,这样 Windows 事件查看器能够清楚地显示事件日志消息。详见 @@ -5425,13 +5407,13 @@ local0.* /var/log/postgresql - 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 + 这个参数启用日志收集器,它是一个捕捉被发送到stderr的日志消息的后台进程,并且它会将这些消息重定向到日志文件中。这种方法比记录到syslog通常更有用,因为某些类型的消息可能不会在syslog输出中出现(一个常见的示例是动态链接器错误消息;另一个示例是由archive_command等脚本产生的错误消息)。这个参数只能在服务器启动时设置。 - 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供方法来轮转日志文件。还有,在某些不使用日志收集器的平台上可能会导致丢失或者混淆日志输出,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 + 也可以不使用日志收集器而把日志记录到stderr,日志消息将只会去到服务器的stderr被定向到的位置。不过,那种方法只适合于低日志量,因为它没有提供便捷的方法来轮转日志文件。还有,在某些平台上,不使用日志收集器可能会导致日志输出丢失或混杂,因为多个进程并发写入同一个日志文件时会覆盖彼此的输出。 @@ -5440,7 +5422,7 @@ local0.* /var/log/postgresql - 日志收集器旨在避免丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 + 日志收集器旨在避免丢失消息。这意味着在极高的负载下,如果服务器进程试图在收集器已经落后时发送更多的日志消息,那么它可能会被阻塞。相反,syslog倾向于在无法写入消息时丢掉消息,这意味着在这样的情况下它可能会无法记录某些消息,但是它不会阻塞系统的其他部分。 @@ -5478,7 +5460,7 @@ local0.* /var/log/postgresql logging_collector被启用时,这个参数设置被创建的日志文件的文件名。 - 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何时区独立的%转义,计算将在由指定的时区中完成)。 + 该值被视为一种strftime模式,因此%转义可以被用来指定根据时间变化的文件名(注意如果有任何依赖时区的%转义,计算将在由指定的时区中完成)。 被支持的%转义和开放组织的strftime说明中列举的类似。 注意系统的strftime不会被直接使用,因此平台相关(非标准)的扩展无法工作。 默认是postgresql-%Y-%m-%d_%H%M%S.log。 @@ -5516,7 +5498,7 @@ local0.* /var/log/postgresql - 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的十进制格式,该数字必须以一个0(零)开始)。 + 在 Unix 系统上,当logging_collector被启用时,这个参数设置日志文件的权限(在微软 Windows 上这个参数将被忽略)。这个参数值应当是一个数字形式的模式,它可以被chmodumask系统调用接受(要使用通常的八进制格式,该数字必须以一个0(零)开始)。 @@ -5582,7 +5564,7 @@ local0.* /var/log/postgresql - 示例:要保留 24 小时的日志,每个小时一个日志文件,但是在日志文件尺寸超过 1GB 时轮转。可以这样做:将log_filename设置为server_log.%H%M、 + 示例:要保留 24 小时的日志,每个小时一个日志文件,如果日志文件尺寸超过 1GB,也会提前轮转。可以这样做:将log_filename设置为server_log.%H%M、 将log_truncate_on_rotation设置为on、 将log_rotation_age设置为60并且 将log_rotation_size设置为1000000。 @@ -5601,7 +5583,7 @@ local0.* /var/log/postgresql - 当启用了向syslog记录时,这个参数决定要使用的syslog设备。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4、 + 当启用了向syslog记录时,这个参数决定要使用的syslog设施。你可以在LOCAL0LOCAL1LOCAL2LOCAL3LOCAL4LOCAL5LOCAL6LOCAL7中选择,默认值是LOCAL0。还请参阅系统的syslog守护进程的文档。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -5656,7 +5638,7 @@ local0.* /var/log/postgresql - 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,有必要让消息保持逻辑上的整体性(也更加有用)。 + 如果 syslog 最终被记录到一个文本文件中,那么两种设置的效果是一样的,但最好设置为 on,因为大部分 syslog 实现要么不能处理大型消息,要么需要做特殊的配置以处理大型消息。但是如果 syslog 最终写入到某种其他媒介,让消息保持逻辑上的完整性可能是必要的,也可能更有用。 @@ -5675,7 +5657,7 @@ local0.* /var/log/postgresql - 当启用了向事件日志记录时,这个参数决定用来标识日志中PostgreSQL消息的程序名。默认值是PostgreSQL。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 当启用了向事件日志记录时,这个参数决定用来标识日志中PostgreSQL消息的程序名。默认值是PostgreSQL。这个参数只能在服务器启动时设置。 @@ -5746,9 +5728,7 @@ local0.* /var/log/postgresql - 控制在服务器日志中记录哪些导致错误条件的SQL语句。当前的SQL语句将包含在任何指定 - severity - 或更高消息的日志条目中。 + 控制在服务器日志中记录哪些导致错误条件的SQL语句。对于达到指定严重级别或更高级别的消息,其日志条目中会包含当前 SQL 语句。 有效值为DEBUG5DEBUG4DEBUG3DEBUG2DEBUG1、 @@ -5788,7 +5768,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -5826,7 +5806,7 @@ local0.* /var/log/postgresql - log_min_duration_statement的其他注释也适用于此设置。 + log_min_duration_statement的其他说明也适用于此设置。 @@ -5841,8 +5821,8 @@ local0.* /var/log/postgresql - 确定持续时间超过的语句的比例将被记录。 - 采样是随机的,例如0.5表示统计上有一半的机会任何给定的语句将被记录。 + 确定持续时间超过的语句中,将被记录的语句比例。 + 采样是随机的,例如0.5表示任意给定语句被记录的统计概率为二分之一。 默认值为1.0,表示记录所有采样的语句。 将此设置为零将禁用采样语句持续时间记录,与将log_min_duration_sample设置为-1相同。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -5860,7 +5840,7 @@ local0.* /var/log/postgresql - 设置所有语句都被记录的事务的比例,除了其他原因记录的语句。它适用于每个新事务,无论其语句的持续时间如何。 + 设置需要记录全部语句的事务比例,这些记录是在因其他原因记录的语句之外额外进行的。它适用于每个新事务,无论其语句的持续时间如何。 采样是随机的,例如0.1表示任何给定事务被记录的统计概率是十分之一。 log_transaction_sample_rate可以帮助构建事务样本。 默认值为0,表示不记录任何额外事务的语句。将其设置为1会记录所有事务的所有语句。 @@ -5885,8 +5865,7 @@ local0.* /var/log/postgresql - 设置启动进程在长时间运行的操作仍在进行时记录消息的时间间隔, - 以及该操作进一步进展消息之间的间隔时间。默认值为10秒。 + 设置启动进程在长时间运行的操作开始后,等待多久才记录第一条进度消息,以及此后该操作的进度消息之间的时间间隔。默认值为10秒。 设置为0会禁用该功能。如果未指定单位, 则将其视为毫秒。此设置分别应用于每个操作。 此参数只能在postgresql.conf文件或服务器命令行中设置。 @@ -5928,7 +5907,7 @@ local0.* /var/log/postgresql DEBUG1 .. DEBUG5 - 为开发者提供连续的更详细的信息。 + 为开发者提供逐级更加详细的信息。 DEBUG INFORMATION @@ -5988,7 +5967,7 @@ local0.* /var/log/postgresql - 记录什么到日志 + 记录哪些内容 @@ -6009,7 +5988,7 @@ local0.* /var/log/postgresql - application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。它也会被通过包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为C 风格的十六进制转义序列。 + application_name可以是任意小于NAMEDATALEN个字符(标准编译中是 64 个字符)的字符串。应用通常在连接服务器时设置此值。该名称将被显示在pg_stat_activity视图中并被包括在 CSV 日志项中。也可以通过将其包括在普通日志项中。只有可打印 ASCII 字符能被使用在application_name之中。其他字符将被替换为C 风格的十六进制转义序列。 @@ -6075,7 +6054,7 @@ local0.* /var/log/postgresql - 每次由自动清理执行的清理操作都会被记录,如果运行时间至少达到指定时间。将此设置为零会记录所有由自动清理执行的清理操作。 + 当自动清理执行的清理操作运行时间至少达到指定时间时,就会记录该操作。将此设置为零会记录所有由自动清理执行的清理操作。 -1会禁用记录由自动清理执行的清理操作。如果未指定单位,则将其视为毫秒。 例如,如果将其设置为250ms,则所有运行时间为250ms或更长的自动清理都会被记录。 此外,当此参数设置为任何非-1值时,如果由于冲突锁或关系被并发删除而跳过自动清理执行的清理操作,则会记录一条消息。 @@ -6094,7 +6073,7 @@ local0.* /var/log/postgresql - 每次由自动清理执行的分析操作都会被记录,如果运行时间至少达到指定时间。 + 当自动清理执行的分析操作运行时间至少达到指定时间时,就会记录该操作。 将此设置为零会记录所有由自动清理执行的分析操作。 -1会禁用记录由自动清理执行的分析操作。 如果未指定单位,则将其视为毫秒。 @@ -6233,7 +6212,7 @@ local0.* /var/log/postgresql - 对于使用扩展查询协议的客户端,解析、绑定和执行步骤的持续时间将被独立记录。 + 对于使用扩展查询协议的客户端,Parse、Bind 和 Execute 步骤的持续时间将被独立记录。 @@ -6256,7 +6235,7 @@ local0.* /var/log/postgresql 控制在服务器日志中记录的每条消息的详细程度。有效值为TERSE, - DEFAULTVERBOSE,每个值都会添加更多字段到显示的消息中。 + DEFAULTVERBOSE,它们依次在显示的消息中增加更多字段。 TERSE不包括DETAILHINTQUERYCONTEXT错误信息的记录。 VERBOSE输出包括SQLSTATE错误代码 @@ -6276,7 +6255,7 @@ local0.* /var/log/postgresql - 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致很微小的性能损失。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 默认情况下,连接日志消息只显示连接主机的 IP 地址。打开这个参数将导致也记录主机名。注意根据你的主机名解析设置,这可能会导致不可忽视的性能开销。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -6295,7 +6274,7 @@ local0.* /var/log/postgresql %字符开始转义序列,它将被按照下文描述的替换成状态信息。 未识别的转义被忽略。其他字符被直接复制到日志行。某些转义只被会话进程识别并且被主服务器进程等后台进程当作空。 通过指定一个在%之后和该选项之前的数字可以让状态信息左对齐或右对齐。 - 负值将导致在右边用空格填充状态信息已达到最小宽度,而正值则在左边填充。填充对于日志文件的人类可读性大有帮助。 + 负值将导致在右边用空格填充状态信息以达到最小宽度,而正值则在左边填充。填充对于日志文件的人类可读性大有帮助。 @@ -6363,8 +6342,8 @@ local0.* /var/log/postgresql %P - 并行组leader的进程ID,如果该进程是一个并行查询worker - no + 如果该进程是并行查询工作进程,则为并行组领导者的进程 ID + @@ -6381,8 +6360,8 @@ local0.* /var/log/postgresql %n - 带毫秒的时间戳(作为 Unix 时代) - no + 带毫秒精度的 Unix 时间戳 + @@ -6437,7 +6416,7 @@ local0.* /var/log/postgresql %Q 当前查询的查询标识符。 查询标识符默认是不计算的,所以这个部分将是零,除非 参数被激活或者配置了计算查询标识符的第三方模块 - yes + @@ -6456,7 +6435,7 @@ local0.* /var/log/postgresql %c转义打印一个准唯一的会话标识符,它由两个 4 字节的十六进制数(不带先导零)组成,以点号分隔。 - 这些数字是进程启动时间和进程 ID,因此%c也可以被用作保存打印这些项的方式的空间。 + 这些数字是进程启动时间和进程 ID,因此%c也可以用来节省空间地输出这两项信息。 例如,要从pg_stat_activity生成会话标识符,使用这个查询: SELECT to_hex(trunc(EXTRACT(EPOCH FROM backend_start))::integer) || '.' || @@ -6494,7 +6473,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 对于输出的行,%Q 总是报告零标识符, - 因为log_statement在标识符能被计算之前生成输出,包括无效标识符不能计算的无效语句。 + 因为log_statement在标识符能被计算之前生成输出,也包括无法计算标识符的无效语句。 @@ -6542,8 +6521,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 控制启动进程等待时间超过针对恢复冲突的deadlock_timeout的时候是否产生日志消息。 - 这对于决定恢复冲突是否会阻止恢复应用WAL有所帮助。 + 控制启动进程因恢复冲突而等待超过deadlock_timeout时是否产生日志消息。这有助于判断恢复冲突是否阻碍了恢复过程应用 WAL。 @@ -6571,8 +6549,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 此设置仅影响作为结果打印的日志消息,, 和相关的设置。 - 该设置的非零值会增加一些开销,特别是当参数以二进制形式发送时,因为需要转换为文本。 + 此设置仅影响由及相关设置产生的日志消息。此设置为非零值时会增加一些开销,特别是以二进制形式发送参数时,因为需要将参数转换为文本。 @@ -6616,7 +6593,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' UPDATEDELETETRUNCATE, 和COPY FROM。 如果PREPAREEXECUTE和 - EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个执行消息时会产生日志并且会包括绑定参数的值(任何内嵌的单引号会被双写)。 + EXPLAIN ANALYZE包含合适类型的命令,它们也会被记录。对于使用扩展查询协议的客户端,当收到一个 Execute 消息时会产生日志并且会包括 Bind 参数的值(任何内嵌的单引号会被双写)。 @@ -6627,7 +6604,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在执行阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 + 即使使用log_statement = all设置,包含简单语法错误的语句也不会被记录。这是因为只有在完成基本语法解析并确定了语句类型之后才会发出日志消息。在扩展查询协议的情况下,在 Execute 阶段之前(即在解析分析或规划期间)出错的语句也不会被记录。将log_min_error_statement设置为ERROR(或更低)来记录这种语句。 @@ -6660,7 +6637,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' - 每个复制命令都会被记录在服务器日志中。 + 在服务器日志中记录每个复制命令,以及walsender进程获取和释放复制槽的操作。 有关复制命令的更多信息,请参见。 默认值为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -6679,8 +6656,8 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 控制临时文件名和大小的日志记录。 - 临时文件可以用于排序、哈希和临时查询结果。 - 如果通过此设置启用,每当删除临时文件时都会发出日志记录。 + 临时文件可以用于排序、hash 和临时查询结果。 + 如果通过此设置启用,每当删除临时文件时都会发出日志记录,其中文件大小以字节为单位。 值为零时记录所有临时文件信息,而正值仅记录大小大于或等于指定数据量的文件。 如果未指定单位,则将其视为千字节。 默认设置为-1,禁用此类日志记录。 @@ -6733,7 +6710,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' 错误上下文、 导致错误的用户查询(如果有且被log_min_error_statement启用)、 错误位置所在的字符计数、 - 在 PostgreSQL 源代码中错误的位置(如果log_error_verbosity被设置为verbose)以及应用名,后端类型,并行组leader的进程ID和查询ID。 + 在 PostgreSQL 源代码中错误的位置(如果log_error_verbosity被设置为verbose)、应用名、后端类型、并行组领导者的进程 ID 和查询 ID。 下面是一个定义用来存储 CSV 格式日志输出的样表: @@ -6785,7 +6762,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 设置log_filenamelog_rotation_age为你的日志文件提供一种一致的、可预测的命名空间。这让你预测文件名会是怎样以及知道什么时候一个个体日志文件完成并且因此准备好被导入。 + 设置log_filenamelog_rotation_age,为日志文件提供一致且可预测的命名方案。这样就能预测文件名,并知道单个日志文件何时已完成写入、可以导入。 @@ -6814,12 +6791,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 使用JSON格式的日志输出 - 包括jsonloglog_destination列表中提供了一种方便的方式将日志文件导入到许多不同的程序中。此选项以JSON格式发出日志行。 + 将jsonlog加入log_destination列表,可以方便地将日志文件导入多种不同的程序。此选项以JSON格式输出日志行。 - 字段值为null的字符串字段将被排除在输出之外。 - 未来可能会添加其他字段。处理jsonlog输出的用户应忽略未知字段。 + 值为空值的字符串字段不会输出。将来可能会添加其他字段。处理jsonlog输出的用户应用程序应忽略未知字段。 @@ -6964,13 +6940,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; statement string - 客户提供的查询字符串 + 客户端提供的查询字符串 cursor_position number - 查询字符串中的光标索引 + 查询字符串中的游标索引 @@ -7024,7 +7000,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 进程标题 - 这些设置控制服务器进程的进程标题如何被修改。进程标题通常可以用ps或者 Windows 上的进程浏览器等程序来查看。详见。 + 这些设置控制服务器进程的进程标题如何修改。通常可以通过ps等程序查看进程标题,在 Windows 上则可以使用Process Explorer。详情参见 @@ -7058,7 +7034,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 每次服务器接收到新的SQL命令时,都可以更新进程标题。 + 启用后,每次服务器接收到新的 SQL 命令时都会更新进程标题。 在大多数平台上,默认情况下此设置为on,但在Windows上默认为off, 因为该平台更新进程标题的开销较大。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -7096,7 +7072,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对每个会话当前执行命令的信息收集,包括其标识符和命令开始执行的时间。 - 此参数默认为开启状态。请注意,即使启用了此信息,只有超级用户、具有 + 此参数默认为开启状态。请注意,即使启用了此参数,只有超级用户、具有 pg_read_all_stats角色权限的角色和拥有被报告会话的用户 (包括属于他们具有权限的角色的会话)才能看到此信息,因此不应构成安全风险。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -7114,7 +7090,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 为每个活动会话指定存储当前执行命令的文本所保留的内存量,它们被用于pg_stat_activity.query域。 + 为每个活动会话指定存储当前执行命令的文本所预留的内存量,它们被用于pg_stat_activity.query字段。 如果指定值时没有单位,则以字节为单位。默认值是 1024字节。这个参数只能在服务器启动时被设置。 @@ -7131,7 +7107,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 启用对数据库活动的统计信息收集。 - 此参数默认为开启,因为自动清理守护进程需要收集的信息。 + 此参数默认为开启,因为自动清理守护进程需要这些收集到的信息。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -7207,7 +7183,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用函数调用次数和时间的跟踪。指定pl以仅跟踪过程语言函数, + 启用函数调用次数和耗时的跟踪。指定pl以仅跟踪过程语言函数, all以同时跟踪SQL和C语言函数。默认值为none, 即禁用函数统计跟踪。只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -7242,7 +7218,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - none适用于监控系统。如果值只被访问一次,它是最有效的。 + none最适合监控系统。如果值只被访问一次,它是最有效的。 cache确保重复访问产生相同的值,这对涉及自连接的查询很重要。 snapshot在交互式检查统计信息时可能很有用,但开销较高, 特别是存在许多数据库对象时。 @@ -7269,21 +7245,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 启用查询标识符的内核计算。 - 查询标识符可以在 pg_stat_activity - 视图中显示,使用 EXPLAIN,或者如果通过 - 参数进行配置,则可以在日志中发出。 - 扩展还需要计算查询标识符。 - 请注意,如果内核查询标识符计算方法不可接受,也可以使用外部模块。 - 在这种情况下,必须始终禁用内核计算。 - 有效值为 off(始终禁用), - on(始终启用),auto, - 允许诸如 这样的模块 - 自动启用它,并且 regress 具有与 - auto 相同的效果,只是查询标识符不会显示在 - EXPLAIN 输出中,以便促进自动回归测试。 - 默认值为 auto。 + 启用内置的查询标识符计算功能。查询标识符可以显示在pg_stat_activity视图或EXPLAIN的输出中,也可以通过参数配置后写入日志。扩展也要求计算查询标识符。注意,如果内置的查询标识符计算方法不符合要求,可以改用外部模块。在这种情况下,必须始终禁用内置计算功能。有效值为off(始终禁用)、on(始终启用)、auto(允许等模块自动启用此功能),以及regress。后者与auto效果相同,但不会在EXPLAIN输出中显示查询标识符,以便进行自动回归测试。默认值为auto @@ -7323,7 +7285,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 对于每个查询,将各自模块的性能统计输出到服务器日志中。这是一个简单的性能分析工具,类似于Unix getrusage()操作系统功能。 - log_statement_stats报告总语句统计,而其他选项报告每个模块的统计信息。 + log_statement_stats报告整个语句的统计信息,而其他选项报告每个模块的统计信息。 log_statement_stats不能与任何单独模块选项一起启用。所有这些选项默认情况下都是禁用的。 只有超级用户和具有适当SET权限的用户才能更改这些设置。 @@ -8004,7 +7966,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; DEBUG1LOGNOTICEWARNINGERROR。 每个级别都包括其后的所有级别。级别越靠后,被发送的消息越少。默认值是NOTICE。 - 注意LOG在这里有与中不同的排名。 + 注意LOG在这里的排序与中的不同。 @@ -8024,15 +7986,15 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,用于进行搜索该对象的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 + 这个变量指定当一个对象(表、数据类型、函数等)被用一个无模式限定的简单名称引用时,搜索该对象时的模式顺序。当在不同模式中有同名对象时,将使用第一个在搜索路径中被找到的对象。一个不属于搜索路径中任何一个模式的对象只能通过用限定名(带点号)指定包含它的模式来引用。 - search_path的值必需是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被安静地忽略。 + search_path的值必须是一个逗号分隔的模式名列表。任何不是一个已有模式的名称,或者是一个用户不具有USAGE权限的模式,将被静默忽略。 - 如果列表项之一是特殊名$user,则具有SESSION_USER返回的名字的模式将取代它(如果有这样一个模式并且该用户有该模式的USAGE权限;如果没有,$user会被忽略)。 + 如果列表项之一是特殊名$user,则具有CURRENT_USER返回的名字的模式将取代它(如果有这样一个模式并且该用户有该模式的USAGE权限;如果没有,$user会被忽略)。 @@ -8057,11 +8019,12 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个参数的缺省值是"$user", public。这种设置支持一个数据库(其中没有用户拥有私有模式,并且所有人共享使用public)、每个用户私有模式及其组合的共享使用。其它效果可以通过全局或者针对每个用户修改默认搜索路径设置获得。 + 这个参数的默认值是"$user", public。这种设置支持共享使用数据库(用户没有私有模式,所有人共享使用public)、每个用户拥有私有模式,以及二者的组合。 + 还可以通过全局或针对每个用户修改默认搜索路径设置来获得其他效果。 - 更多有关方案处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 + 更多有关模式处理的信息,请参考。特别地,只有当数据库只有一个用户或者有少数的相互信任的用户时,默认配置是合适的。 @@ -8081,7 +8044,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,只要有至少一条策略被应用则查询就会失败。默认为on。受限的行可见性会导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS)属性的角色没有效果。 + 这个变量控制是否以抛出一个错误来代替应用一条行安全性策略。在设置为on时,策略正常应用。在设置为off时,原本会应用至少一条策略的查询就会失败。默认为on。受限的行可见性可能导致不正确的结果时,可将其改成off。例如,pg_dump默认会做这种更改。这个变量对能绕过每一条行安全性策略的角色(即超级用户和具有BYPASSRLS属性的角色)没有效果。 @@ -8100,8 +8063,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这个参数指定了在创建表或物化视图时使用的默认表访问方法,如果CREATE命令没有明确指定访问方法, - 或者当使用SELECT ... INTO时,不允许指定表访问方法。默认值是heap。 + 创建表或物化视图时,如果CREATE命令没有显式指定访问方法,或者使用了不允许指定表访问方法的SELECT ... INTO,则使用此参数指定的默认表访问方法。默认值为heap @@ -8121,7 +8083,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建企图将失败。 + 该值要么是一个表空间的名字,要么是一个指定使用当前数据库默认表空间的空字符串。如果该值和任何现有表空间的名字都不匹配,PostgreSQL将自动使用当前数据库的默认表空间。如果指定了一个非默认的表空间,用户必须对它有CREATE权限,否则创建尝试将失败。 @@ -8129,7 +8091,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当创建数据库时也会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 + 创建数据库时也不会使用这个变量。默认情况下,一个新数据库会从它的模板数据库继承其表空间设置。 @@ -8178,11 +8140,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被放置在里表中的连续表空间中。如果列表被选中元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 + 该值是一个表空间名字的列表。当列表中有多于一个名称时,每次一个临时对象被创建时PostgreSQL随机选择列表中的一个成员。例外是在一个事务中,连续创建的临时对象被依次放置在列表中的连续表空间中。如果列表中被选中的元素是一个空字符串,PostgreSQL将自动使用当前数据库的默认表空间。 - 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,类似于为用户指定一个不具有CREATE权限的表空间。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特殊地,使用一个在postgresql.conf中设置的值时,这条规则起效。 + 当temp_tablespaces被交互式地设置时,指定一个不存在的表空间是一种错误,指定一个用户不具有CREATE权限的表空间也同样是错误。不过,当使用一个之前设置的值时,不存在的表空间会被忽略,就像用户缺少CREATE权限的表空间一样。特别是,使用一个在postgresql.conf中设置的值时,这条规则起效。 @@ -8207,7 +8169,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 这个参数通常为打开。 当设置为off时,它禁用期间对例程体字符串的验证。 - 禁用验证避免了验证处理的副作用,特别避免了如向前引用导致的伪肯定。 + 禁用验证避免了验证处理的副作用,特别是避免前向引用等问题导致的误报。 在代表其他用户载入函数之前设置这个参数为offpg_dump会自动这样做。 @@ -8250,7 +8212,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态 。默认是off(读/写)。 + 一个只读的 SQL 事务不能修改非临时表。这个参数控制每个新事务的默认只读状态。默认是off(读/写)。 @@ -8273,11 +8235,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当运行在可串行化隔离级别时,一个可延迟只读 SQL 事务可以在它被允许继续之前延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的负荷;因此串行化代码将没有任何理由因为并发更新而强制它中断,使得这个选项适合于长时间运行的只读事务。 + 当运行在serializable隔离级别时,一个可延迟只读 SQL 事务可能在获准继续之前被延迟一段时间。但是,一旦它开始执行就不会产生任何用来保证可串行化性的开销;因此串行化代码将没有任何理由因为并发更新而强制它中止,使得这个选项适合于长时间运行的只读事务。 - 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些操作在低于可串行化隔离级别上的事务无效。默认值是off。 + 这个参数控制每个新事务的默认可延迟状态。目前它对读写事务或者那些运行在低于serializable隔离级别上的事务无效。默认值是off @@ -8321,7 +8283,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的只读状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -8341,7 +8303,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 此参数反映当前事务的可延迟性状态。 在每个事务的开始,它被设置为的当前值。 - 任何后续尝试更改它的都等同于命令。 + 任何后续更改它的尝试都等同于命令。 @@ -8365,7 +8327,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 这个设置的预期用途是由逻辑复制系统在应用所复制的更改时将它设置为replica。 - 其效果将是触发器和规则(没有对其默认配置做修改)在复制机上将不会被触发。 + 其效果将是触发器和规则(没有对其默认配置做修改)在副本上将不会被触发。 更多信息请参考ALTER TABLE的子句ENABLE TRIGGER以及ENABLE RULE @@ -8395,9 +8357,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 超时从命令到达服务器的时间开始计算,一直到它被服务器完成为止。 - 如果单个简单查询消息中出现多个 SQL 语句,超时将分别应用于每个语句。(PostgreSQL 13 之前的版本通常将超时应用于整个查询字符串。 - 在扩展查询协议中,当任何与查询相关的消息(解析、绑定、执行、描述)到达时,超时就开始运行,并且可以通过执行完成或同步消息来取消超时。 + 超时从命令到达服务器时开始计算,直到服务器完成该命令为止。 + 如果单个简单查询消息中出现多个 SQL 语句,超时将分别应用于每个语句。 + (PostgreSQL 13 之前的版本通常将超时应用于整个查询字符串。) + 在扩展查询协议中,当任何与查询相关的消息(Parse、Bind、Execute、Describe)到达时开始计时, + 并在处理完 Execute 或 Sync 消息时取消计时。 @@ -8441,13 +8405,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 如果任何语句在试图获取表、索引、行或其他数据库对象上的锁时等到超过指定的时间量,该语句将被中止。 + 如果任何语句在试图获取表、索引、行或其他数据库对象上的锁时等待超过指定的时间量,该语句将被中止。 该时间限制独立地应用于每一次锁获取尝试。该限制会应用到显式锁定请求(如LOCK TABLE或不带NOWAITSELECT FOR UPDATE)和隐式获得的锁。 如果指定值时没有单位,则以毫秒为单位。一个零值(默认)将禁用超时。 - 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为事务超时将总是第一个被触发。 + 与statement_timeout不同,这个超时只在等待锁时发生。注意如果statement_timeout为非零,设置lock_timeout为相同或更大的值没有意义,因为语句超时将总是第一个被触发。 如果log_min_error_statement 被设置为ERROR 或更低,超时的语句将被记录。 @@ -8467,15 +8431,14 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 终止任何已经闲置(这是指,等待客户端查询)超过这个参数所指定时间量的打开事务的会话。 - 如果这个值指定时没有单位,它被设为毫秒。 - 零值(默认)禁用超时。 + 终止在打开的事务中空闲(即等待客户端查询)超过指定时长的任何会话。 + 如果指定值时不带单位,则以毫秒为单位。零值(默认值)禁用此超时。 - 此选项可以用于确保空闲会话不会在不合理的时间内持有锁。 - 即使没有持有重要的锁的时候,打开的事务也会防止清理最近死亡的可能只对这个事务可见的元组;所以长时间保持空闲会导致表膨胀。 - 详见。 + 此选项可确保空闲会话不会持有锁过长时间。 + 即使没有持有重要的锁,打开的事务也会阻止清理最近死亡、且可能只对该事务可见的元组;因此长时间空闲可能造成表膨胀。 + 更多详情参见 @@ -8490,9 +8453,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 终止任何空闲的会话(也就是,等待客户端查询),但不在打开的事务中,且超过指定的时间量。 - 如果指定值时不带单位,其单位采用毫秒。 - 零值时(默认)禁用超时。 + 终止不在打开的事务中、且空闲(即等待客户端查询)超过指定时长的任何会话。 + 如果指定值时不带单位,则以毫秒为单位。零值(默认值)禁用此超时。 @@ -8500,8 +8462,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 注意不要对通过连接池软件或其他中间件建立的连接强制执行此超时,因为这样的层可能不会很好地响应意外的连接关闭。 - 只对交互会话启用此超时可能是帮助的,也许只对特定用户应用它。 + 应谨慎对通过连接池软件或其他中间件建立的连接强制执行此超时,因为这样的层可能不会很好地响应意外的连接关闭。 + 只对交互会话启用此超时可能有所帮助,也许只对特定用户应用它。 @@ -8535,7 +8497,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 这里的实际选择都是根据爱好做出的,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码将比 base64 编码更大。 + 这里的实际选择主要取决于偏好,只受客户端应用中可能存在的限制的约束。两种方法都支持所有可能的值,尽管十六进制编码会比 base64 编码略大。 @@ -8556,7 +8518,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - 当在XML和字符串值之间进行转换时,无论设置DOCUMENT或 CONTENT都是隐式的。可参阅Section 8.13。 有效值是DOCUMENT和CONTENT。 缺省值是CONTENT。当在 XML 和字符串值之间进行转换时,设置DOCUMENTCONTENT都是隐式的。详见。有效值是DOCUMENTCONTENT。默认值是CONTENT。 + 设置在 XML 与字符串值之间进行转换时,隐含采用DOCUMENT还是CONTENT。 + 有关说明参见。有效值是DOCUMENTCONTENT。默认值是CONTENT @@ -8591,7 +8554,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; createrole_self_grant (string) - createrole_self_grant配置参数 + createrole_self_grant + 配置参数 @@ -8600,9 +8564,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 该值必须是setinherit或它们的逗号分隔列表。默认值为空字符串,这会禁用此功能。 - 此选项的目的是允许非超级用户的CREATEROLE用户自动继承或自动获得对新创建角色执行SET ROLE的能力。 + 此选项的目的是允许非超级用户的CREATEROLE用户自动继承所创建用户的权限,或自动获得对这些用户执行SET ROLE的能力。 由于CREATEROLE用户始终会隐式获得其所创建角色的ADMIN OPTION,因此该用户总是可以通过执行GRANT语句达到相同效果,但自动授予在可用性上更方便。 - 超级用户会自动继承每个角色的权限,并且始终可以切换到任何角色;此设置可让CREATEROLE用户对其创建的用户获得类似的行为。 + 超级用户会自动继承每个角色的权限,并且始终可以对任何角色执行SET ROLE;此设置可让CREATEROLE用户对其创建的用户获得类似的行为。 @@ -8610,7 +8574,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; event_triggers (boolean) - event_triggers配置参数 + event_triggers + 配置参数 @@ -8625,7 +8590,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; restrict_nonsystem_relation_kind (string) - restrict_nonsystem_relation_kind配置参数 + restrict_nonsystem_relation_kind + 配置参数 @@ -8640,7 +8606,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 区域和格式化 + 区域设置和格式化 @@ -8654,7 +8620,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域行为的设置初始化配置文件。 + 设置日期和时间值的显示格式,以及解释有歧义的日期输入值的规则。由于历史原因, 这个变量包含两个独立的部分:输出格式声明(ISOPostgresSQLGerman)、 输入/输出的年/月/日顺序(DMYMDYYMD)。这些可以被独立设置或者一起设置。关键字EuroEuropeanDMY的同义词;关键字USNonEuroNonEuropeanMDY的同义词。详见。内置默认值是ISO, MDY,但是initdb将用对应于选中的lc_time区域设置行为的设置初始化配置文件。 @@ -8669,11 +8635,14 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置间隔值的显示格式。值sql_standard将产生匹配 SQL 标准间隔文本的输出。当参数被设置为ISO时,值postgres(默认)将产生匹配PostgreSQL发行 8.4 之前的输出。当DateStyle参数被设置为非ISO输出时,值postgres_verbose会产生匹配PostgreSQL发行 8.4 之前的输出。值iso_8601会产生匹配在 ISO 8601 的 4.4.3.2 节中定义的带标志符格式的时间间隔的输出。 + 设置时间间隔值的显示格式。值sql_standard会生成符合SQL标准时间间隔字面量的输出。 + 值postgres(默认值)的输出与PostgreSQL 8.4 之前版本中设为ISO时的输出一致。 + 值postgres_verbose的输出与PostgreSQL 8.4 之前版本中DateStyle设为非ISO输出时的输出一致。 + 值iso_8601会生成符合 ISO 8601 第 4.4.3.2 节定义的时间间隔带标志符格式的输出。 - IntervalStyle参数也可以影响对有歧义的间隔输入的解释。详见。 + IntervalStyle参数也会影响对有歧义的时间间隔输入的解释。详见 @@ -8705,7 +8674,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置服务器接受的日期时间输入中使用的时区缩写集合。默认值为'Default', 这个集合在全世界大多数地方都能工作。也还有'Australia''India',以及可能为一种特定安装定义的其他集合。详见。 + 设置服务器在日期时间输入中接受的额外时区缩写集合(除当前TimeZone设置所定义的缩写之外)。默认值为'Default', 这个集合在全世界大多数地方都能工作。也还有'Australia''India',以及可能为一种特定安装定义的其他集合。详见 @@ -8731,23 +8700,23 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 如果值为1(默认值)或更高,浮点值被输出为最短-精度格式;参见。 + 如果值为 1(默认值)或更高,浮点值被输出为最短精确格式;参见。 实际生成的位数只取决于输出的值,而不取决于此参数的值。 - float8 值最多需要 17 位数字,float4值最多需要9位数字。 + float8 值最多需要 17 位数字,float4值最多需要9位数字。 这种格式既快速又精确,在正确读取时精确地保留了原始的二进制浮点值。为了历史兼容性,允许的值最大为3。 如果值为零或负,则输出四舍五入为给定的十进制精度。 - 使用的精度是根据此参数的值减小的类型((FLT_DIGDBL_DIG,视情况而定)的标准位数。 + 所用精度以该类型的标准位数(根据类型使用FLT_DIGDBL_DIG)为基础,再按此参数的值减少。 (例如,指定 -1 将导致float4 值输出四舍五入为 5 位有效数字,而float8值四舍五入为 14 位。) - 此格式较慢,不会保留二进制浮点值的所有位,但可能令人更易于阅读。 + 此格式较慢,不会保留二进制浮点值的所有位,但可能更便于阅读。 此参数的含义,以及其默认值,在 PostgreSQL 12 中发生了变化; - 参见 以便进一步讨论。 + 参见 了解进一步讨论。 @@ -8783,7 +8752,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 在一些系统上,这个区域分类并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 + 在一些系统上,这个区域设置类别并不存在。仍然可以设置这个变量,只是不会有任何效果。同样,所期望语言的翻译消息也可能不存在。在这种情况下,你将仍然继续看到英文消息。 @@ -8802,7 +8771,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化货币量的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化货币量的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -8817,7 +8786,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化数字的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化数字的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -8832,7 +8801,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 设置用于格式化日期和时间的区域,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 + 设置用于格式化日期和时间的区域设置,例如用to_char函数族。可接受的值是系统相关的;详见。如果这个变量被设置为空字符串(默认),那么该值将以一种系统相关的方式从服务器的执行环境中继承。 @@ -8864,7 +8833,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 选择被那些没有显式参数指定配置的文本搜索函数变体使用的文本搜索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配区域的配置,initdb将用对应于选中的lc_ctype区域的设置初始化配置文件。 + 选择被那些没有显式参数指定配置的文本检索函数变体使用的文本检索配置。详见。内置默认值是pg_catalog.simple,但是如果能够标识一个匹配该区域设置的配置,initdb将用对应于选中的lc_ctype区域设置的值初始化配置文件。 @@ -8879,7 +8848,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 为了载入附加的功能或者达到提高性能的目的,可用多个设置来预先载入共享库到服务器中。 - 例如'$libdir/mylib'设置可能会导致mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 + 例如'$libdir/mylib'设置会使mylib.so(或者某些平台上的mylib.sl)从安装的标准库目录被预装载。这些设置之间的区别在于生效的时间以及改变它们所需的权限。 @@ -8888,12 +8857,12 @@ SET XML OPTION { DOCUMENT | CONTENT }; 只有特别为与PostgreSQL一起使用设计的共享库才能以这种方式载入。每一个PostgreSQL支持 - 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非PostgreSQL无法 + 的库都有一个魔法块,它会被检查以保证兼容性。由于这个原因,非 PostgreSQL 库无法 以这种方式被载入。你可能可以使用操作系统的工具(如LD_PRELOAD)载入它。 - 总之,请参考特定模块的文档来用推荐的方法载入它。 + 一般来说,请参考特定模块的文档来用推荐的方法载入它。 @@ -8927,9 +8896,8 @@ SET XML OPTION { DOCUMENT | CONTENT }; - 这个特性的目的是允许非特权用户在特定的会话中载入正在调试的或者性能度量库, - 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客 - 户端的PGOPTIONS环境变量或者 + 这个特性的目的是允许非特权用户在特定的会话中载入用于调试或性能测量的库, + 而无需一个显式的LOAD命令。为了这个目的,通常通过使用客户端的PGOPTIONS环境变量或者 ALTER ROLE SET来设置这个参数。 @@ -8967,7 +8935,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; 不同,相对于在库被第一次使用 - 时载入它,在会话开始时载入库并没有什么性能优势。不过,当使用连接池时这样做还是有一些 + 时载入它,在会话开始时载入库并没有明显的性能优势。不过,当使用连接池时这样做还是有一些 优势。 @@ -9007,9 +8975,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 在 Windows 主机上,在服务器启动时预载入一个库并不会减少启动每个新服务器进程所需的 - 时间;每一个服务器进程将会重新载入预载入的库。不过,对于那些要在postmaster启动时 + 时间;每一个服务器进程将会重新载入所有预载入的库。不过,对于那些要在postmaster启动时 执行操作的库来说,Windows 主机上的 - shared_preload_libraries任然有用。 + shared_preload_libraries仍然有用。 @@ -9057,13 +9025,9 @@ SET XML OPTION { DOCUMENT | CONTENT }; 如果需要打开一个可以动态装载的模块并且在CREATE FUNCTIONLOAD命令中指定的文件名没有目录部分(即名字中不包含斜线),那么系统将搜索这个路径以查找所需的文件。 - - dynamic_library_path的值必须是一个冒号分隔(或者在 Windows 上以分号分隔)的绝对目录路径的列表。如果一个列表元素以特殊字符串开始,$libdir会被替换为PostgreSQL包中已编译好的库目录。这里是PostgreSQL发布提供的模块被安装的位置(使用pg_config --pkglibdir来找到这个目录的名字)。例如: - + 参数dynamic_library_path的值必须是由冒号(Windows上为分号)分隔的绝对目录路径列表。如果某个列表元素以特殊字符串$libdir开头,则会使用编译时确定的PostgreSQL软件包的库目录来替换$libdir;该目录是标准PostgreSQL发行版所提供模块的安装位置。(使用pg_config --pkglibdir可以找出此目录的名称。)例如: dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir' - - 或者在 Windows 环境中: - +或者,在 Windows 环境中: dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' @@ -9138,7 +9102,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - GIN 索引返回的集合尺寸的软上限。详见。 + GIN 索引扫描返回的集合尺寸的软上限。详见 @@ -9171,18 +9135,18 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 这是在锁上等待的时间,然后再检查是否存在死锁条件。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 + 指定在检查是否发生死锁之前等待锁的时间。检查死锁相对昂贵,因此服务器不会每次等待锁时都运行它。 我们乐观地假设在生产应用程序中死锁并不常见,所以在检查死锁之前只是等待一段时间。 增加此值会减少在不必要的死锁检查中浪费的时间,但会减慢实际死锁错误的报告速度。 如果未指定单位,则将其视为毫秒。 - 默认值为一秒(1s),这可能是您在实践中想要的最小值。 - 在负载较重的服务器上,您可能希望提高它。 - 理想情况下,设置应超过您的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 + 默认值为一秒(1s),这可能是你在实践中想要的最小值。 + 在负载较重的服务器上,你可能希望提高它。 + 理想情况下,设置应超过你的典型事务时间,以提高在等待者决定检查死锁之前释放锁的几率。 只有超级用户和具有适当SET权限的用户才能更改此设置。 - 当被设置时,这个参数还可以决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 + 当被设置时,这个参数也决定发出关于锁等待的日志之前等待的时间量。如果你想调查锁延迟,你可能希望设置一个比正常的deadlock_timeout小的值。 @@ -9237,7 +9201,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 这个参数控制在谓词锁被提升为覆盖整个关系之前,该谓词锁能够在单个关系上锁住多少页面或元组。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个关系之前,可以对单个关系中的多少页面或元组加谓词锁。大于等于零的值表示一种绝对限制,而负值表示用除以这个设置的绝对值。默认值为-2,它将保持以往版本的PostgreSQL中的行为。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -9252,7 +9216,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 这个参数控制在谓词锁被提升为覆盖整个页面之前,该谓词锁能在单一页面上锁住多少行。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 + 这个参数控制在谓词锁被提升为覆盖整个页面之前,可以对单个页面中的多少行加谓词锁。默认值是2。这个参数只能在postgresql.conf文件中或者服务器命令行上设置。 @@ -9280,7 +9244,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个空数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。对于那些要求旧行为的应用的向后兼容性,这个变量可以被设置为off。 + 这个参数控制数组输入解析器是否把未用引号的NULL识别为一个值为空值的数组元素。默认为on,允许输入包含空值的数组值。但是PostgreSQL 8.2 之前的版本不支持数组中的空值,并且因此将把NULL当作指定一个值为字符串NULL的正常数组元素。为了向后兼容那些要求旧行为的应用,这个变量可以被设置为off @@ -9300,11 +9264,11 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 这个参数控制转义字符串语法(E'...')中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\。如果客户端代码没有做到正确转义,那么将会导致 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 + 这个参数控制转义字符串语法(E'...')中的单引号是否能够用\'来表示。首选的 SQL 标准的方法是将其双写(''),但是PostgreSQL在历史上也接受\'。不过使用\'容易导致安全风险,因为在某些客户端字符集编码中,有多字节字符的最后一个字节在数值上等价于 ASCII 的\。如果客户端代码没有做到正确转义,那么就可能遭到 SQL 注入攻击。如果服务器拒绝看起来带有被反斜线转义的单引号的查询,那么就可以避免这种风险。backslash_quote的可用值是on(总是允许\')、off(总是拒绝)以及safe_encoding(只有客户端编码不允许在多字节字符中存在 ASCII \时允许)。safe_encoding是默认设置。 - 注意在普通字符串文本中,\就表示\。这个参数只影响转义字符串语法的处理。 + 注意在普通字符串字面量中,\就表示\。这个参数只影响转义字符串语法的处理。 @@ -9327,7 +9291,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 设置这个参数不会禁用所有与大对象相关的安全检查 — 除了那些在PostgreSQL 9.0中已经修改了的默认行为。 + 设置此变量不会禁用所有与大对象相关的安全检查 — 只禁用那些在PostgreSQL 9.0 中默认行为发生变化的检查。 @@ -9350,7 +9314,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' standard_conforming_strings (boolean) - 字符串标准符合 + 字符串符合标准 standard_conforming_strings配置参数 @@ -9358,7 +9322,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 从PostgreSQL 19 开始,这个参数始终为on。字符串文本始终按照 SQL 标准解析(即反斜线在字符串文本中是普通字符)。这个参数继续保留,是因为应用可能会查询它;但它不能被设为off。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 + 从PostgreSQL 19 开始,这个参数始终为on。字符串字面量始终按照 SQL 标准解析(即反斜线在字符串字面量中是普通字符)。这个参数继续保留,是因为应用可能会查询它;但它不能被设为off。如果一个应用希望反斜线被当做转义字符,应该使用转义字符串语法()。 @@ -9373,7 +9337,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询来,这样的扫描会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on。 + 它允许对大型表的顺序扫描与其他扫描同步,因此并发扫描可以在几乎相同的时刻读取相同的块,这样可以分担 I/O 负载。当启用这个参数时,一个扫描可能会从表的中间开始并且之后绕回到开头以覆盖所有的行,这样可以与已在进行中的扫描活动同步。对于没有ORDER BY子句的查询,这样的扫描可能会在返回行的顺序中造成不可预料的改变。将这个参数设置为off以保证 8.3 之前的行为(顺序扫描总是从表的起始处开始)。默认值是on @@ -9397,15 +9361,15 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr得出空值值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空(未知)。因此这个参数默认为off。 + 当打开时,形为expr = NULL(或NULL = expr)的表达式将被当做expr IS NULL, 也就是说,如果expr计算结果为空值则返回真,否则返回假。正确的 SQL 标准兼容的expr = NULL行为总是返回空值(未知)。因此这个参数默认为off - 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释)。它们不是非常有用并且在普通应用中也不常见,在应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及 空值的表达式的语义上感到困惑,因此这个选项默认为关闭。 + 不过,在Microsoft Access里的过滤表单生成的查询似乎使用expr = NULL来测试空值,因此,如果你使用这个接口访问数据库,你可能想把这个选项打开。因为expr = NULL形式的表达式总是返回空值(使用 SQL 标准解释),它们不是非常有用并且在普通应用中也不常见,因此这个选项实际上没有什么危害。但是新用户常常对涉及空值的表达式语义感到困惑,因此这个选项默认为关闭。 - 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不是劣质程序的一般修复。 + 请注意这个选项只影响= NULL形式,而不影响其它比较操作符或者其它与一些涉及等值操作符的表达式在计算上等效的其他表达式(例如IN)。因此,这个选项不能普遍修复错误的程序写法。 @@ -9481,7 +9445,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 当被设置为开(on),PostgreSQL将在一次后端崩溃后自动重新初始化。 + 当设置为 on(默认值)时,PostgreSQL将在一次后端崩溃后自动重新初始化。 让这个值设置为开(on)通常是将数据库可用性最大化的最佳方法。但是在某些环境中,例如PostgreSQL被集群软件调用时,禁用重启可能很有用,这样集群软件可以得到控制并且采取它认为适当的行动。 @@ -9501,7 +9465,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 如果设置为关(off),PostgreSQL在将修改的数据文件刷新到文件系统失败时,将引发PANIC级错误。 + 当设置为 off(默认值)时,PostgreSQL在将修改后的数据文件刷盘到文件系统失败时,将引发PANIC级错误。 这样会导致数据库服务器崩溃。这个参数只能在服务器启动时被设置。 @@ -9510,8 +9474,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 如果设置为开(on),PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷新操作。 - 仅在调查操作系统假如回写失败时对缓冲数据的处理方式的情况下,才将其设置为开(on)。 + 如果设置为开(on),PostgreSQL将报告错误,但会继续运行,以便可以在以后的检查点中重试数据刷盘操作。 + 只有在调查清楚操作系统在回写失败时如何处理缓冲数据之后,才应将其设置为开(on)。 @@ -9528,14 +9492,14 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' 当设置为fsync,也就是默认值,PostgreSQL将在崩溃恢复开始之前递归地打开并同步数据目录中的所有文件。 对文件的搜索将遵循WAL目录和每个配置表空间的符号链接(而不是任何其它符号链接)。 - 这是为了确保在重现更改之前,所有WAL和数据文件都持久地存储在硬盘上。 - 这适用于在启动没有完全关闭的数据库集簇时,包括由pg_basebackup创建的副本。 + 这是为了确保在重放更改之前,所有WAL和数据文件都持久地存储在磁盘上。 + 这适用于每次启动未正常关闭的数据库集簇时,包括由pg_basebackup创建的副本。 - 在Linux上,可以用syncfs代替,请求操作系统来同步包含数据目录的整个文件系统,WAL文件和每个表空间(但不是通过符号链接可访问到的任何其他文件系统)。 + 在Linux上,可以用syncfs代替,请求操作系统来同步数据目录、WAL 文件和各个表空间所在的文件系统(但不是通过符号链接可访问到的任何其他文件系统)。 这可能比fsync设置快得多,因为它不需要逐个打开每个文件。 - 另一方面,如果一个文件系统是被其他需要修改大量文件的应用程序共享的,它可能会慢一些,因为这些文件也将写入硬盘。 + 另一方面,如果一个文件系统是被其他需要修改大量文件的应用程序共享的,它可能会慢一些,因为这些文件也将写入磁盘。 此外,在5.8之前的Linux版本中,向磁盘写入数据时遇到的I/O错误可能不会报告给PostgreSQL,相关的错误消息可能只出现在内核日志中。 @@ -9554,11 +9518,10 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' 预置选项 - 下列参数是只读的。 - 同样,它们被排除在postgresql.conf文件示例之外。 - 这些选项报告特定应用可能感兴趣的多种PostgreSQL行为,特别是管理前端相关的行为。 - 所有这些都是在PostgreSQL被编译或者它被安装时决定的。 - + 下列参数是只读的,因此未列入示例 postgresql.conf 文件。 + 这些选项报告 PostgreSQL 行为的各个方面,某些应用(特别是管理前端)可能对此感兴趣。 + 其中大多数参数在编译或安装 PostgreSQL 时确定。 + @@ -9602,9 +9565,9 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 在Unix系统上,这个参数报告启动时的数据目录(由定义)的权限。 + 在 Unix 系统上,这个参数报告服务器启动时数据目录(由定义)的权限。 (在Microsoft Windows上这个参数将总是显示0700。) - 更多信息请参考。 + 更多信息请参考initdb 选项。 @@ -9690,7 +9653,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告PostgreSQL是否在编译时打开了 64 位整数日期和时间。从PostgreSQL 10起,这个值总是on。 + 报告PostgreSQL是否在编译时启用了对 64 位整数日期和时间的支持。从PostgreSQL 10起,这个值总是on @@ -9706,9 +9669,9 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' 报告服务器当前是否处于热备模式。 - 当这个是on的时候,所有的事务强制为只读。 - 在会话中,这个只能在服务器提升为主库的时候变更。 - 更多信息参见 + 当此值为 on 时,所有事务都被强制为只读。 + 在会话中,此值只有在服务器被提升为主库时才会改变。 + 更多信息参见 @@ -9722,7 +9685,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定的。默认值是 100 个参数。 + 报告函数参数的最大数量。它由编译服务器时的FUNC_MAX_ARGS值决定。默认值是 100 个参数。 @@ -9737,7 +9700,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64 ;因此max_identifier_length的默认值是 63,但是在使用多字节编码时可以少于 63 个字符。 + 报告标识符的最大长度。它由编译服务器时的NAMEDATALEN值减一决定。NAMEDATALEN的默认值是 64;因此max_identifier_length的默认值是 63 字节,在使用多字节编码时,这可能不足 63 个字符。 @@ -9813,7 +9776,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告服务器版本数值。它是由编译服务器时的PG_VERSION值决定的。 + 报告服务器的版本号。它是由编译服务器时的PG_VERSION值决定的。 @@ -9828,7 +9791,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告服务器版本数值的整数值。它是由编译服务器时的PG_VERSION_NUM值决定的。 + 以整数形式报告服务器的版本号。它是由编译服务器时的PG_VERSION_NUM值决定的。 @@ -9843,7 +9806,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告主共享内存区域的大小,四舍五入到最接近的兆字节。 + 报告主共享内存区域的大小,向上取整到整数兆字节。 @@ -9880,8 +9843,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 报告此PostgreSQL服务器已构建的 SSL 库的名称(即使此实例当前未配置或使用 SSL), - 例如OpenSSL,或一个空字符串(如果没有)。 + 报告此PostgreSQL服务器在构建时使用的 SSL 库的名称(即使此实例当前未配置或使用 SSL), + 例如OpenSSL,如果没有使用 SSL 库,则报告空字符串。 @@ -9924,11 +9887,11 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' 自定义选项 - 这个特性被设计用来由附加模块向PostgreSQL添加通常不为系统知道的参数(例如过程语言)。这允许使用标准方法配置扩展模块。 + 这个特性允许附加模块(例如过程语言)向PostgreSQL添加系统通常不认识的参数。这样便能以标准方式配置扩展模块。 - 自定义选项有两部分名称:一个扩展名,然后是一个句点,再然后是正确的参数名,就像 SQL 中的合格名称。一个示例是plpgsql.variable_conflict。 + 自定义选项的名称由两部分组成:扩展名称和参数名本身,中间用句点分隔,类似于 SQL 中的限定名。例如plpgsql.variable_conflict @@ -9936,7 +9899,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' PostgreSQL将接受任何两部分参数名称的设置。 这些变量被视为占位符,在定义它们的模块加载之前没有任何功能。 当加载扩展模块时,它将添加其变量定义并根据这些定义转换任何占位符值。 - 如果存在以其扩展名开头的任何未识别的占位符,将发出警告并删除这些占位符。 + 如果存在以其扩展名称开头的任何未识别的占位符,将发出警告并删除这些占位符。 @@ -9945,11 +9908,10 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' 开发者选项 - 下面的参数目的是用在开发测试上, 并且永远不能用于生产数据库。 - 但是,它们中的一些能够用于帮助恢复严重损坏的数据库。 - 同样,它们被从示例postgresql.conf文件中排除。 - 请注意许多这些参数要求特殊的源代码编译标志才能工作。 - + 以下参数用于开发者测试,切勿用于生产数据库。不过,其中一些参数可用于辅助恢复严重损坏的数据库。 + 因此,它们未列入示例postgresql.conf文件。 + 请注意,许多参数需要特殊的源代码编译标志才能起作用。 + @@ -9962,7 +9924,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 允许将表空间创建为pg_tblspc内的目录,当CREATE TABLESPACE命令提供空位置字符串时。 + 当向CREATE TABLESPACE命令提供空的位置字符串时,允许将表空间创建为pg_tblspc内的目录。 这旨在允许测试主库和备库在同一台机器上运行的复制场景。这样的目录可能会混淆备份工具,因为这些工具期望在该位置只找到符号链接。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -9979,8 +9941,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 允许修改系统表的结构以及对系统表进行某些其他风险操作。即使对于超级用户,这也通常是不允许的。 - 不明智地使用此设置可能导致无法检索的数据丢失或严重损坏数据库系统。 + 允许修改系统表的结构以及对系统表进行某些其他风险操作。否则,即使超级用户也不允许执行这些操作。 + 不明智地使用此设置可能导致无法挽回的数据丢失或严重损坏数据库系统。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -10040,14 +10002,14 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 当设置为1时,每个系统目录缓存条目在第一个可能的机会时失效,不管任何使之无效的事情是否真的发生。 - 作为结果,系统目录的缓存被有效地禁用,因此服务器将运行得非常缓慢。 - 较高的值递归地运行缓存失效,这样会更慢,而且只用于测试缓存逻辑自身。 + 当设置为1时,每个系统目录缓存条目都会在最早可能的时刻被置为无效,无论是否真的发生了使其失效的事件。 + 这实际上禁用了系统目录缓存,因此服务器将运行得非常缓慢。 + 较高的值递归地运行缓存失效,这样会更慢,而且仅对测试缓存逻辑本身有用。 默认值0选择正常的目录缓存行为。 - 当试图触发涉及并发目录更改的难以复现的错误时,此参数非常有用,但除此之外它不太被需要。 + 当试图触发涉及并发目录更改的难以复现的错误时,此参数非常有用,但除此之外很少需要使用它。 详情请参见源码文件inval.cpg_config_manual.h @@ -10170,7 +10132,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据的时有用。这个参数在会话开始之后不能被更改。 + 读取系统表时忽略系统索引(但是修改系统表时依然同时更新索引)。这在从被破坏的系统索引中恢复数据时有用。这个参数在会话开始之后不能被更改。 @@ -10185,8 +10147,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 执行认证过程后启动新服务器进程时延迟的时间量。这是为了给开发者们一个机会在一个服务器进程上附加一个调试器。 - 如果指定值时没有单位,则以秒为单位。0值(默认值)禁用延迟。这个参数在会话开始之后不能被更改。 + 新服务器进程启动并完成认证过程之后的延迟时间。这旨在给开发者一个机会,用调试器附加到服务器进程上。 + 如果指定值时没有单位,则以秒为单位。零值(默认值)禁用延迟。这个参数在会话开始之后不能被更改。 @@ -10201,8 +10163,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 在新服务器进程分叉后,在进行认证过程之前,延迟的时间量。这是为了给开发者们一个机会在一个服务器进程上附加一个调试器来跟踪认证过程中的不当行为。 - 如果指定值时没有单位,则以秒为单位。0值(默认值)禁用延迟。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 + 新服务器进程刚刚派生之后、执行认证过程之前的延迟时间。这旨在给开发者一个机会,用调试器附加到服务器进程上,跟踪认证过程中的异常行为。 + 如果指定值时没有单位,则以秒为单位。零值(默认值)禁用延迟。这个参数只能在postgresql.conf文件中或在服务器命令行上设置。 @@ -10217,7 +10179,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 + 为LISTENNOTIFY命令生成大量调试输出。必须是DEBUG1或者更低才能把这种输出分别发送到客户端或者服务器日志。 @@ -10231,7 +10193,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 如果打开,发出在排序操作中的资源使用的相关信息。只有在编译PostgreSQL时定义了TRACE_SORT宏, 这个参数才可用(不过,当前在默认情况下就定义了TRACE_SORT)。 + 如果开启,输出排序操作中的资源使用信息。 @@ -10246,7 +10208,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' - 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。对每一种锁类型,已授权锁和等待锁的计数也会被一起转储。一个日志文件输出的示例如下: + 如果开启,发出锁使用情况的信息。被转储信息中包括锁操作的类型、锁的类型和 被锁或被解锁对象的唯一标识符。同样包括的还有已经授予这个对象的锁类型的位掩码和 等待这个对象的锁类型的位掩码。还会转储每种锁类型已授予的锁数、等待的锁数,以及它们的总数。一个日志文件输出的示例如下: LOG: LockAcquire: new: lock(0xb7acd844) id(24688,24696,0,0,0,1) grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0 @@ -10318,7 +10280,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果设置,不会跟踪小于这个 OID 的锁(用于避免在系统表上的输出)。 + 如果设置,不会跟踪 OID 小于此值的表上的锁(用于避免在系统表上的输出)。 @@ -10394,7 +10356,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,被修改的任何缓冲区的整页镜像及其WAL记录都被加入到记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 + 这个参数被设计用来检查WAL重做例程中的缺陷。当这个参数被启用时,与该 WAL 记录相关的所有已修改缓冲区的整页镜像都会被添加到该记录中。如果该记录后来被重放,系统将首先应用每个记录然后测试该记录修改的缓冲区是否符合存储的镜像。在某些情况下(例如提示位),小的变动是可以接受的,并且会被忽略。任何预期之外的差别都将导致致命错误,最后中止恢复。 @@ -10433,15 +10395,15 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 只有当数据校验和被启用时才有效。 + 只有启用数据校验和时才有效。 在读取过程中检测到校验和失败通常会导致PostgreSQL报告错误,中止当前事务。 - 将ignore_checksum_failure设置为on会导致系统忽略失败(但仍然报告警告),并继续处理。 - 这种行为可能导致崩溃,传播或隐藏损坏,或其他严重问题。然而,它可能允许您跳过错误, - 并检索可能仍然存在于表中的未损坏的元组,如果块头仍然正常。如果头部损坏,即使启用此选项也会报告错误。 - 默认设置为off。 + 将ignore_checksum_failure设置为 on 会使系统忽略失败(但仍报告警告),并继续处理。 + 这种行为可能导致崩溃、传播或隐藏损坏,或引发其他严重问题。 + 但是,如果块首部仍然正常,它可能允许你跳过错误,检索表中可能仍然存在的未损坏元组。 + 如果首部损坏,即使启用此选项也会报告错误。默认设置为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -10459,7 +10421,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 检测到损坏的页面头通常会导致PostgreSQL报告错误,中止当前事务。 将zero_damaged_pages设置为on会导致系统报告警告,将内存中的损坏页面清零,并继续处理。 - 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许您跳过错误,并从表中可能存在的未损坏页面中检索行。 + 这种行为会破坏数据,即损坏页面上的所有行。但是,它确实允许你跳过错误,并从表中可能存在的未损坏页面中检索行。 如果由于硬件或软件错误而发生损坏,这对于恢复数据很有用。通常在放弃从表的损坏页面恢复数据的希望之前,不应将其设置为on。 清零的页面不会强制写入磁盘,因此建议在再次关闭此参数之前重新创建表或索引。默认设置为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -10479,9 +10441,9 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 如果设置为 off(默认值),则在恢复期间检测到引用无效页面的 WAL 记录会导致 PostgreSQL 引发 PANIC 级别错误,中止恢复。 将ignore_invalid_pages设置为on会导致系统忽略 WAL 记录中的无效页面引用(但仍报告警告),并继续恢复。 - 此行为可能会导致崩溃、数据丢失、传播或隐藏腐败,或其他严重问题。 - 但是,它可能允许你通过 PANIC 级错误,完成恢复,并启动服务器。 - 参数只能在服务器启动时设置。它仅在恢复期间或待机模式下生效。 + 此行为可能会导致崩溃、数据丢失、传播或隐藏损坏,或其他严重问题。 + 但是,它可能允许你跳过 PANIC 级错误,完成恢复,并启动服务器。 + 参数只能在服务器启动时设置。它仅在恢复期间或备库模式下生效。 @@ -10496,7 +10458,8 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果LLVM有所需要的功能,用GDB注册所生成的函数。这会让调试更加容易。默认设置是off。只有超级用户和具有适当SET权限的用户可以在会话开始时更改这个参数,并且在会话内完全不能更改它。 + 如果 LLVM 具有所需的功能,则向GDB注册生成的函数。 + 这会让调试更加容易。默认设置为off。只有超级用户和具有适当SET权限的用户才能在会话开始时更改此参数,并且在会话内完全不能更改它。 @@ -10512,7 +10475,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 将生成的LLVM IR写入文件系统,位于内。 - 这仅对于在JIT实现内部工作时有用。默认设置为off。 + 这仅对开发 JIT 的内部实现有用。默认设置为off。 只有超级用户和具有适当SET权限的用户才能更改此设置。 @@ -10543,10 +10506,9 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 如果LLVM有所需的功能,发出需要的数据以允许perf对JIT生成的函数画像。 - 这会写出文件到~/.debug/jit/中,如果需要,由用户负责对其执行清除。 - 默认设置是off。 - 只有超级用户和具有适当SET权限的用户可以在会话开始时更改这个参数,并且在会话内完全不能更改它。 + 如果 LLVM 具有所需的功能,则输出让perf对 JIT 生成的函数进行性能分析所需的数据。 + 这会将文件写入~/.debug/jit/;用户应在需要时自行清理。 + 默认设置为off。只有超级用户和具有适当SET权限的用户才能在会话开始时更改此参数,并且在会话内完全不能更改它。 @@ -10576,8 +10538,8 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 当设置为on时,这是默认值,PostgreSQL将在后端崩溃后自动删除临时文件。 - 如果禁用,文件将被保留,并且也许可用于调试,例如。 + 当设置为on(默认值)时,PostgreSQL将在后端崩溃后自动删除临时文件。 + 如果禁用,文件将被保留,例如可用于调试。 重复的崩溃可能会导致无用文件的积累。 该参数只能在postgresql.conf文件中或服务器命令行中设置。 @@ -10629,11 +10591,11 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 允许值为bufferedimmediate。默认值为buffered。 这个参数旨在用于测试逻辑解码以及大型事务的复制。 - debug_logical_replication_streaming对发布端和订阅端的影响不同。 + debug_logical_replication_streaming对发布者和订阅者的影响不同。 - 在发布端,debug_logical_replication_streaming允许在逻辑解码中立即流式传输或序列化更改。 + 在发布者端,debug_logical_replication_streaming允许在逻辑解码中立即流式传输或序列化更改。 当设置为immediate时,如果 streaming选项在 CREATE SUBSCRIPTION中已启用, @@ -10642,10 +10604,10 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 在订阅端,如果streaming选项被设置为parallel, - 则debug_logical_replication_streaming可用于控制主应用工作进程是将更改发送到共享内存队列, - 还是将所有更改序列化到文件。设置为buffered时,主进程通过共享内存队列将更改发送给并行应用工作进程。 - 设置为immediate时,主进程会将所有更改序列化到文件,并通知并行应用工作进程在事务结束时读取并应用这些更改。 + 在订阅者端,如果streaming选项被设置为parallel, + 则debug_logical_replication_streaming可用于控制领导者应用工作进程是将更改发送到共享内存队列, + 还是将所有更改序列化到文件。设置为buffered时,领导者通过共享内存队列将更改发送给并行应用工作进程。 + 设置为immediate时,领导者会将所有更改序列化到文件,并通知并行应用工作进程在事务结束时读取并应用这些更改。 @@ -10657,12 +10619,12 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) 短选项 - 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,并且它们作为一个单字母选项存在并不表示它们会被大量使用。 + 为了方便起见,系统中还为一些参数提供了单字母的命令行选项开关。它们在中描述。其中一些选项是由于历史原因而存在,它们以单字母选项的形式存在,并不一定表示鼓励频繁使用这些选项。
- 短选项键 + 短选项对照 diff --git a/zh/20/datatype.sgml b/zh/20/datatype.sgml index 6cfddb07..f2d9d33d 100644 --- a/zh/20/datatype.sgml +++ b/zh/20/datatype.sgml @@ -151,7 +151,7 @@ line - 平面上的无限长的线 + 平面上的无限直线 @@ -163,19 +163,19 @@ macaddr - MAC(Media Access Control)地址 + MAC(媒体访问控制)地址 macaddr8 - MAC(Media Access Control)地址(EUI-64格式) + MAC(媒体访问控制)地址(EUI-64格式) money - 货币数量 + 货币额 @@ -183,7 +183,7 @@ s) ] decimal [ (p, s) ] - 可选择精度的精确数字 + 可选择精度的精确数值 @@ -195,7 +195,7 @@ pg_lsn - PostgreSQL日志序列号类型 + PostgreSQL 日志序列号 @@ -273,13 +273,13 @@ tsquery - 文本搜索查询 + 文本检索查询 tsvector - 文本搜索文档 + 文本检索文档 @@ -420,14 +420,14 @@
- 数字类型常量的语法在里描述。数字类型有一整套对应的数学操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 + 数字类型常量的语法在里描述。数字类型有一整套对应的算术操作符和函数。相关信息请参考 。下面的几节详细描述这些类型。 整数类型 - 整数 + integer @@ -440,7 +440,7 @@ int4 - 整数 + integer @@ -460,11 +460,11 @@
- 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。而只有在integer的范围不够的时候才使用bigint。 + 常用的类型是integer,因为它提供了在范围、存储空间和性能之间的最佳平衡。一般只有在磁盘空间紧张的时候才使用 smallint类型。bigint则设计用于integer的范围不够的情况。 - SQL只声明了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在许多其它SQL数据库系统中使用。 + SQL只规定了整数类型integer(或int)、smallintbigint。类型int2int4int8都是扩展,也在某些其他SQL数据库系统中使用。 @@ -473,11 +473,11 @@ 任意精度数值 - 数字(数据类型) + numeric(数据类型) - 任意精度数字 + 任意精度数值 @@ -578,18 +578,18 @@ NUMERIC(3, 5)
- infinity - numeric (数据类型) + 无穷大 + numeric(数据类型) NaN - 非数字 + 非数 - 非数字 - 数字(数据类型) + 非数 + numeric(数据类型) @@ -676,7 +676,7 @@ FROM generate_series(-3.5, 3.5, 1) AS x; - 双精度 + double precision @@ -686,7 +686,7 @@ FROM generate_series(-3.5, 3.5, 1) AS x; float8 - 双精度 + double precision @@ -739,8 +739,7 @@ FROM generate_series(-3.5, 3.5, 1) AS x; 默认情况下,浮点值会以最短且精确的十进制表示形式输出; - 生成的十进制值比同一二进制精度下任何其他可表示值都更接近真实 - 存储的二进制值。(不过,为了避免输入例程普遍存在的一个错误, + 所生成的十进制值与实际存储的二进制值之间的距离,小于它与任何其他可用相同二进制精度表示的值之间的距离。(不过,为了避免输入例程普遍存在的一个错误, 即未能正确遵守舍入到最近偶数规则,当前输出值绝不会 恰好位于两个可表示值的正中间。) 对于float8值,最多使用 17 位有效十进制数字; @@ -749,14 +748,14 @@ FROM generate_series(-3.5, 3.5, 1) AS x; - 生成这种最短且精确的输出格式,比历史上的圆整格式要快得多。 + 生成这种最短且精确的输出格式,比历史上的舍入格式要快得多。 为了兼容旧版本PostgreSQL生成的输出, 并允许降低输出精度,可以使用 - 参数改为选择圆整后的 + 参数改为选择舍入后的 十进制输出。将该参数设置为 0 会恢复之前的默认行为,也就是把值 舍入为 6 位(对于float4)或 15 位 (对于float8)有效十进制数字。设置为负值会 @@ -770,7 +769,7 @@ FROM generate_series(-3.5, 3.5, 1) AS x; - 过去那些需要精确值的应用,往往必须把 + 过去那些需要精确值的应用,必须把 设置为 3 才能获得它们。 为了在版本之间获得最大兼容性,这类应用应继续这样做。 @@ -778,12 +777,12 @@ FROM generate_series(-3.5, 3.5, 1) AS x; 无穷大 - 浮点型 + 浮点 - 非数字 - 浮点型 + 非数 + 浮点 @@ -855,13 +854,13 @@ FROM generate_series(-3.5, 3.5, 1) AS x; - auto-increment + 自动递增 serial - sequence - and serial type + 序列 + 与 serial 类型 @@ -914,7 +913,7 @@ ALTER SEQUENCE tablename_ - 要向 serial 列插入序列中的下一个值,应指定让该列 + 要向 serial 列插入序列中的下一个值,应指定让serial列 使用其默认值。这既可以通过在 INSERT 语句的 列表中省略该列来实现,也可以通过使用 DEFAULT 关键字来实现。 @@ -990,7 +989,7 @@ ALTER SEQUENCE tablename_ SELECT '12.34'::float8::numeric::money; - 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有圆整错误。 + 但是,我们不推荐这样做。浮点数不应该被用来处理货币,因为浮点数可能会有舍入误差。 @@ -1002,7 +1001,7 @@ SELECT '52093.89'::money::numeric::float8; 一个 money 值除以一个整数值时,会朝零方向截去小数 - 部分。要得到圆整结果,可以除以一个浮点值,或者在除法前先把 + 部分。要得到舍入后的结果,可以除以一个浮点值,或者在除法前先把 money 转换为 numeric,再在除法后转换回 money(如果要避免精度丢失风险,后一种做法更好)。 当一个 money 值被另一个 money 值除时, @@ -1021,12 +1020,12 @@ SELECT '52093.89'::money::numeric::float8; - string + 字符串 - 字符 + character @@ -1065,11 +1064,11 @@ SELECT '52093.89'::money::numeric::float8; character(n), char(n), bpchar(n) - 定长,空白填充 + 定长,空格填充 bpchar - 无限长度的变长,忽略尾随空白 + 无限长度的变长,忽略尾随空格 text @@ -1128,7 +1127,7 @@ SELECT '52093.89'::money::numeric::float8; 超过 10,485,760。若 character varying (或 varchar)没有长度说明,则该类型接受任意长度 的字符串。若 bpchar 没有长度说明,它也接受任意 - 长度的字符串,但尾随空白在语义上不重要。若 + 长度的字符串,但尾随空格在语义上不重要。若 character(或 char)缺少长度说明, 则等同于 character(1) @@ -1150,7 +1149,7 @@ SELECT '52093.89'::money::numeric::float8;
- 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储代码为零的字符(有时称为NUL)。有关更多信息,请参阅。 + 可以存储在这些数据类型中的字符由数据库字符集确定,该数据库字符集在创建数据库时选择。无论特定的字符集是什么,都无法存储编码值为零的字符(有时称为NUL)。有关更多信息,请参阅 @@ -1169,7 +1168,7 @@ SELECT '52093.89'::money::numeric::float8; - 这三种类型之间没有性能差别,除了使用空白填充类型时会占用更多存储 + 这三种类型之间没有性能差别,除了使用空格填充类型时会占用更多存储 空间,以及在写入带长度约束的列时需要少量额外 CPU 周期来检查长度。 虽然在某些其他数据库系统中,character(n) 可能有一定性能优势,但在 PostgreSQL @@ -1204,7 +1203,7 @@ INSERT INTO test2 VALUES ('ok'); INSERT INTO test2 VALUES ('good '); INSERT INTO test2 VALUES ('too long'); ERROR: value too long for type character varying(5) -INSERT INTO test2 VALUES ('too long'::varchar(5)); -- explicit truncation +INSERT INTO test2 VALUES ('too long'::varchar(5)); -- 显式截断 SELECT b, char_length(b) FROM test2; b | char_length @@ -1328,7 +1327,7 @@ SELECT b, char_length(b) FROM test2; 开头(以便与转义格式区分)。在某些上下文中,这个开头的反斜线 可能需要通过双写进行转义(见 )。作为输入时,十六进制数字 - 可以使用大写或小写,并且在两个数字组成的一组之间允许出现空白 + 可以使用大写或小写,并且每两个数字组成一组,组与组之间允许出现空白 (但组内以及起始的 \x 序列中不能有空白)。 十六进制格式与大量外部应用和协议兼容,并且通常比转义格式转换得 更快,因此更推荐使用。 @@ -1392,7 +1391,7 @@ SELECT '\xDEADBEEF'::bytea; 0 - 0字节 + 零值字节 '\000' '\000'::bytea \x00 @@ -1537,10 +1536,10 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; time - 不带时区的时间 + time without time zone - 带时区的时间 + time with time zone timestamp @@ -1549,13 +1548,13 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; timestamptz - 带时区的时间戳 + timestamp with time zone - 不带时区的时间戳 + timestamp without time zone - 间隔 + interval 时间跨度 @@ -1639,7 +1638,7 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea; - SQL 要求仅写 timestamp 时,应等效于 + SQL 标准要求仅写 timestamp 时,应等效于 timestamp without time zone,而 PostgreSQL 也遵循这种行为。 timestamptz 被接受为 @@ -1720,7 +1719,7 @@ MINUTE TO SECOND 其中 p 是可选的精度说明,给出秒字段中 保留的小数位数。精度可用于 timetimestampinterval 类型, - 范围是 0 到 6。这与前文描述的取值一致。如果在常量声明中没有指定 + 范围是 0 到 6。如果在常量声明中没有指定 精度,则默认采用该字面值本身的精度(但不超过 6 位)。 @@ -1749,7 +1748,7 @@ MINUTE TO SECOND 1999-01-08 - ISO 8601; 任何模式下的1月8日 + ISO 8601; 任何模式下的1月8日 (推荐格式) @@ -1785,27 +1784,27 @@ MINUTE TO SECOND 99-Jan-08 - YMD模式中的1月8日,否则错误 + YMD模式中的1月8日,否则报错 08-Jan-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 Jan-08-99 - 1月8日,除了在YMD模式中错误 + 1月8日,但在YMD模式中会报错 19990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 990108 - ISO 8601; 任何模式中的1999年1月8日 + ISO 8601; 任何模式中的1999年1月8日 1999.008 - 年和一年中的日子 + 年和一年中的第几天 J2451187 @@ -1827,10 +1826,10 @@ MINUTE TO SECOND time - 无时区的时间 + time without time zone - 带时区的时间 + time with time zone @@ -1909,11 +1908,11 @@ MINUTE TO SECOND 040506+0730 - ISO 8601,以分数小时形式给出 UTC 偏移 + ISO 8601,时区的 UTC 偏移不是整小时 040506+07:30:00 - UTC偏移量指定为秒(ISO 8601中不允许) + UTC 偏移精确到秒(ISO 8601中不允许) 04:05:06 PST @@ -1990,11 +1989,11 @@ MINUTE TO SECOND - 带时区的时间戳 + timestamp with time zone - 无时区的时间戳 + timestamp without time zone @@ -2019,29 +2018,12 @@ January 8 04:05:06 1999 PST 也被支持。 - - SQL 标准通过时间后面是否带有 - +- 符号以及时区偏移,来区分 - timestamp without time zone 和 - timestamp with time zone 常量。因此,根据标准, - - + 按照SQL标准,timestamp without time zonetimestamp with time zone字面量的区别在于,时间后是否有+-符号及其后的时区偏移。因此,按照该标准, TIMESTAMP '2004-10-19 10:23:54' - - - 属于 timestamp without time zone,而 - - +timestamp without time zone,而 TIMESTAMP '2004-10-19 10:23:54+02' - - - 属于 timestamp with time zone。 - PostgreSQL 在确定字符串类型之前从不检查 - 其内容,因此会把上述两个值都视为 - timestamp without time zone。要确保一个常量被视为 - timestamp with time zone,应为其指定正确的显式类型: - - +timestamp with time zone。 + PostgreSQL在确定字符串字面量的类型之前,从不检查其内容,因此会把上述两者都视为timestamp without time zone。为确保字面量被视为timestamp with time zone,应为它显式指定正确类型: TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' @@ -2087,12 +2069,12 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' time - constants + 常量 date - constants + 常量 @@ -2193,13 +2175,13 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' date 输出格式 - formatting + 格式化 time 输出格式 - formatting + 格式化 @@ -2232,7 +2214,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' ISO - ISO 8601, SQL标准 + ISO 8601,SQL 标准 1997-12-17 07:37:16-08 @@ -2263,7 +2245,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' - SQL和POSTGRES风格中,如果DMY域顺序被指定,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。 + SQL和POSTGRES风格中,如果指定了 DMY 字段顺序,“日”将出现在“月”之前,否则“月”出现在“日”之前(有关该设置如何影响输入值的解释,请参考)。给出了示例。 @@ -2333,7 +2315,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 时区 - time zone + 时区 @@ -2418,8 +2400,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 除了时区名称和缩写之外, PostgreSQL 还接受 POSIX 风格的 时区说明,见 。 - 这个选项通常不如使用具名时区更合适,但如果没有可用的 IANA - 时区条目,它可能就是必需的。 + 这个选项通常不如使用具名时区更合适,但如果没有合适的 IANA 时区条目可用,它可能就是必需的。 @@ -2462,7 +2443,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' 时区名称和缩写并不是硬编码在服务器中的;它们来自安装目录下 .../share/timezone/ 和 - .../share/timezonesets/ 子目录中的数据 + .../share/timezonesets/ 子目录中的配置文件 (见 )。 @@ -2500,13 +2481,13 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' - interval值可以使用下列语法书写: + interval值可以使用下列详细语法书写: @ quantity unit quantity unit... direction - 其中quantity是一个数字(很可能是有符号的); + 其中quantity是一个数字(可以带有符号); unitmicrosecondmillisecondsecondminutehourday、 @@ -2540,7 +2521,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' P quantity unit quantity unit ... T quantity unit ... 字符串必须以 P 开头,并且可以包含一个 - T 来引出一天中时间单位。可用的单位缩写见 + T 来引出一天中的时间单位。可用的单位缩写见 。单位可以省略, 也可以按任意顺序出现,但小于一天的单位必须出现在 T 之后。特别是,M 的含义 @@ -2579,7 +2560,7 @@ P quantity unit M - 分钟 (在时间部分中) + 分钟(在时间部分中) S @@ -2684,7 +2665,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; P1Y2M3DT4H5M6S - 带标志符的ISO 8601 格式:含义同上 + ISO 8601 带标志符的格式:含义同上 P0001-02-03T04:05:06 @@ -2702,7 +2683,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; interval 输出格式 - formatting + 格式化 @@ -2751,7 +2732,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; iso_8601 风格的输出符合 ISO 8601 标准 - 4.4.3.2 节描述的带标志符格式。 + 4.4.3.2 节描述的带标志符的格式
@@ -2802,7 +2783,7 @@ SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::interval; 布尔类型 - Boolean + 布尔 数据类型 @@ -2913,15 +2894,15 @@ SELECT * FROM test1 WHERE a; 数据类型 - enumerated (enum) + 枚举(enum) - enumerated types + 枚举类型 - 枚举(enum)类型是由一个静态、值的有序集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的日期,或者一个数据的状态值集合。 + 枚举(enum)类型是由一个静态的有序值集合构成的数据类型。它们等效于很多编程语言所支持的enum类型。枚举类型的一个示例可以是一周中的各天,或者一个数据的状态值集合。 @@ -3030,7 +3011,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 实现细节 - 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空格也是有意义的。 + 枚举标签是大小写敏感的,因此'happy''HAPPY'是不同的。标签中的空白也是有意义的。 @@ -3042,7 +3023,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 从内部枚举值到文本标签的翻译被保存在系统目录pg_enum中。可以直接查询该目录。 + 从内部枚举值到文本标签的转换关系被保存在系统目录pg_enum中。直接查询该目录可能会有所帮助。 @@ -3117,7 +3098,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays circle24字节 - <(x,y),r>(中心点和半径) + <(x,y),r>(圆心和半径) @@ -3130,7 +3111,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 我们提供了丰富的函数和操作符来进行各种几何操作,例如缩放、平移、 - 旋转以及计算相交等,详见 。 + 旋转以及求交等,详见 @@ -3141,7 +3122,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 点是几何类型的基本二维构造块。用下面的语法描述point类型的值: + 点是几何类型的基本二维构造块。用下面任一种语法描述point类型的值: ( x , y ) @@ -3157,14 +3138,14 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线 + 直线 line - 线由线性方程Ax + By + C = 0 + 直线由线性方程Ax + By + C = 0 表示,其中AB不能同时为零。类型line 的值采用以下形式输入和输出: @@ -3184,7 +3165,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays (x1,y1)(x2,y2) - 是线上不同的两点。 + 是直线上不同的两点。 @@ -3200,7 +3181,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 线段用一对线段的端点来表示。lseg类型的值用下面的语法声明: + 线段用一对线段的端点来表示。lseg类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ( x2 , y2 ) ] @@ -3224,15 +3205,15 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 方框 - box (data type) + box(数据类型) - rectangle + 矩形 - 方框用其对角的点对表示。box类型的值使用下面的语法指定: + 方框用其对角的点对表示。box类型的值使用下面任一种语法指定: ( ( x1 , y1 ) , ( x2 , y2 ) ) @@ -3251,7 +3232,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 在输入时可以提供任意两个对角,但是值将根据需要被按顺序记录为右上角和左下角。 + 在输入时可以提供任意两个对角,但是值将根据需要被重新排列,并依次存储为右上角和左下角。 @@ -3259,7 +3240,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 路径 - path (data type) + path(数据类型) @@ -3267,7 +3248,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - path类型的值用下面的语法声明: + path类型的值用下面任一种语法指定: [ ( x1 , y1 ) , ... , ( xn , yn ) ] @@ -3277,11 +3258,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays x1 , y1 , ... , xn , yn - 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被忽略时,路径将被假定为封闭。 + 其中的点是组成路径的线段的端点。方括弧([])表示一个开放的路径,圆括弧(())表示一个封闭的路径。如第三种到第五种语法所示,当最外面的圆括号被省略时,路径将被假定为封闭。 - 路径的输出使用第一种或第二种语法。 + 路径的输出视情况使用第一种或第二种语法。 @@ -3305,7 +3286,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - polygon类型的值用下列语法声明: + polygon类型的值用下列任一种语法指定: ( ( x1 , y1 ) , ... , ( xn , yn ) ) @@ -3330,7 +3311,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - 圆由一个圆心和一个半径代表。circle类型的值用下面的语法指定: + 圆由一个圆心和一个半径代表。circle类型的值用下面任一种语法指定: < ( x , y ) , r > @@ -3353,7 +3334,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 网络地址类型 - network + 网络 数据类型 @@ -3410,8 +3391,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays 在对 inetcidr 数据类型排序时,IPv4 - 地址总是排在 IPv6 地址之前,包括那些封装在 IPv6 地址中或映射到 - IPv6 地址中的 IPv4 地址,例如 ::10.2.3.4 或 + 地址总是排在 IPv6 地址之前,即使后者是封装或映射 IPv4 地址所得的 IPv6 地址,例如 ::10.2.3.4::ffff:10.4.3.2 @@ -3567,7 +3547,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - <type>inet</type> vs. <type>cidr</type> + <type>inet</type> 与 <type>cidr</type> inetcidr 两种数据类型的本质区别在于: @@ -3593,12 +3573,12 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - MAC地址 + MAC 地址 macaddr - macaddr类型存储 MAC 地址,也就是以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: + macaddr类型存储 MAC 地址,例如以太网卡硬件地址 (尽管 MAC 地址还用于其它用途)。可以接受下列格式的输入: '08:00:2b:01:02:03' @@ -3632,11 +3612,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays <type>macaddr8</type> - macaddr8 (data type) + macaddr8(数据类型) - MAC地址(EUI-64格式) + MAC 地址(EUI-64 格式) macaddr @@ -3763,31 +3743,31 @@ SELECT * FROM test; - 一个 bit 串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 + 一个位串值每 8 位需要 1 个字节,再加上 5 或 8 个字节的额外 开销,具体取决于串的长度。(不过,长值可能会被压缩或移到行外存储, 与 中对字符串的说明相同。) - 文本搜索类型 + 文本检索类型 - 全文搜索 + 全文检索 数据类型 - 文本搜索 + 文本检索 数据类型 - PostgreSQL 提供了两种专为支持全文搜索而 - 设计的数据类型。所谓全文搜索,是指在一组自然语言 + PostgreSQL 提供了两种专为支持全文检索而 + 设计的数据类型。所谓全文检索,是指在一组自然语言 文档中查找最匹配某个 查询的文档。tsvector 类型以 - 适合文本搜索的优化形式表示文档,tsquery 类型则表示 + 适合文本检索的优化形式表示文档,tsquery 类型则表示 文本查询。关于这一功能的详细解释见 ; 相关函数和操作符的概览见 @@ -3802,7 +3782,7 @@ SELECT * FROM test; tsvector 值是一个排好序且互不重复的 词位(lexeme)列表,这些词已经过 - 规范化,以便把同一单词的不同变体合并起来 + 正规化,以便把同一单词的不同变体合并起来 (详见 )。排序和去重会在输入时自动 完成,如下例所示: @@ -3861,12 +3841,12 @@ SELECT 'a:1A fat:2B,4C cat:5D'::tsvector; 权重通常用于反映文档结构,例如把标题中的词和正文中的词区分开来。 - 文本搜索排序函数可以为不同的权重标记分配不同优先级。 + 文本检索排序函数可以为不同的权重标记分配不同优先级。 必须认识到,tsvector 类型本身并不会执行任何词语 - 规范化;它假定输入的词已经按照应用需求完成规范化。例如: + 正规化;它假定输入的词已经按照应用需求完成正规化。例如: SELECT 'The Fat Rats'::tsvector; @@ -3875,9 +3855,9 @@ SELECT 'The Fat Rats'::tsvector; 'Fat' 'Rats' 'The' - 对于大多数英文全文搜索应用来说,上述词会被视为尚未规范化,但 + 对于大多数英文全文检索应用来说,上述词会被视为尚未正规化,但 tsvector 并不在意。原始文档文本通常应先经过 - to_tsvector,以按搜索需要对词语进行规范化: + to_tsvector,以按检索需要对词语进行正规化: SELECT to_tsvector('english', 'The Fat Rats'); @@ -3966,9 +3946,9 @@ SELECT 'super:*'::tsquery; 引号的使用规则与前面介绍 tsvector 时相同;同样, - 与 tsvector 一样,任何需要的词语规范化都必须在 + 与 tsvector 一样,任何需要的词语正规化都必须在 转换为 tsquery 类型之前完成。to_tsquery - 函数很适合用来实现这种规范化: + 函数很适合用来实现这种正规化: SELECT to_tsquery('Fat:ab & Cats'); @@ -3994,8 +3974,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); ---------------+------------ 'postgradu':1 | 'postgr':* - 因而它能够匹配其带前缀的后继形式 - postgraduate。 + 因而它能够匹配postgraduate 词干化后的形式。 @@ -4013,7 +3992,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); uuid 数据类型用于存储由 RFC 9562、 ISO/IEC 9834-8:2005 及相关标准定义的通用唯一标识符(UUID)。 - (有些系统把这种数据类型称为全局唯一标识符,或 GUID, + (有些系统把这种数据类型称为全局唯一标识符,或 GUID GUID。)这种标识符是一个 128 位的量,由某种算法生成,该算法被设计为使同一算法在已知宇宙中 被其他人生成出相同标识符的概率极低。因此,对于分布式系统而言, @@ -4041,7 +4020,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11 PostgreSQL 也接受其他输入形式:可以使用 - 大写字母、用花括号包围标准格式、忽略部分或全部连字符,或者在任意 + 大写字母、用花括号包围标准格式、省略部分或全部连字符,或者在任意 4 位分组后额外加上连字符。例如: A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11 @@ -4153,8 +4132,8 @@ XMLSERIALIZE ( { DOCUMENT | CONTENT } value AS XMLPARSE 或 XMLSERIALIZE 的情况下与 xml 类型互相转换时, 选择 DOCUMENT 还是 CONTENT - 由会话配置参数 XML option - XML option 决定,可以使用 + 由会话配置参数 XML 选项 + XML 选项 决定,可以使用 标准命令设置: SET XML OPTION { DOCUMENT | CONTENT }; @@ -4171,20 +4150,20 @@ SET xmloption TO { DOCUMENT | CONTENT }; 编码处理 - 在客户端、服务器以及其间传输的 XML 数据上处理多字符编码时, + 在客户端、服务器以及其间传输的 XML 数据上处理多种字符编码时, 必须格外小心。使用文本模式向服务器发送查询并把查询结果返回给 - 客户端时,PostgreSQL 会将客户端与 + 客户端时(这是通常使用的模式),PostgreSQL 会将客户端与 服务器之间传输的所有字符数据转换为目标端的字符编码,参见 。这也包括表示 XML 值的字符串,如上例 所示。这通常意味着,由于字符数据在客户端和服务器之间传输时可能被 转换为其他编码,XML 数据中包含的编码声明可能会失效,因为内嵌的 编码声明本身并不会被修改。为处理这种情况,表示 xml 类型输入值的字符串中所包含的编码声明会被 - 忽略,其内容被假定为当前服务器编码。随后, + 忽略,其内容被假定为当前服务器编码。因此, 为了正确处理,客户端发出的 XML 数据字符串必须采用当前客户端编码。 客户端负责在将文档发送给服务器之前把它们转换为当前客户端编码, 或适当调整客户端编码。输出时,xml 类型值不会带有 - 编码声明,而客户端会假定所有数据都采用当前客户端编码。 + 编码声明,而客户端应假定所有数据都采用当前客户端编码。 @@ -4218,7 +4197,7 @@ SET xmloption TO { DOCUMENT | CONTENT }; xml 数据类型有些特殊,因为它不提供任何比较操作符。 这是因为对 XML 数据并不存在良定义且通用的比较算法。其结果是, - 你无法通过把某个 xml 值与搜索值比较来检索行。 + 你无法通过把某个 xml 列与搜索值比较来检索行。 因此,XML 值通常应伴随一个独立的键字段,例如 ID。另一种比较 XML 值的办法,是先把它们转换成字符串;但请注意,字符串比较对 XML 的比较需求通常帮助不大。 @@ -4226,14 +4205,14 @@ SET xmloption TO { DOCUMENT | CONTENT }; 由于 xml 数据类型没有可用的比较操作符,因此无法直接 - 在这种类型上创建索引。如果需要在 XML 中快速搜索,可行方案包括: + 在这种类型的列上创建索引。如果需要在 XML 中快速搜索,可行方案包括: 将表达式转换为字符串类型后为其建立索引,或者为某个 XPath 表达式 建立索引。当然,实际查询也必须相应调整为使用该被索引的表达式。 - PostgreSQL 的文本搜索功能也可用于加速 - XML 数据的全文搜索。不过,目前 PostgreSQL 发行版中仍缺少所需的 + PostgreSQL 的文本检索功能也可用于加速 + XML 数据的全文检索。不过,目前 PostgreSQL 发行版中仍缺少所需的 预处理支持。 @@ -4248,12 +4227,12 @@ SET xmloption TO { DOCUMENT | CONTENT }; 域类型 - domain + - data type - domain + 数据类型 + @@ -4265,13 +4244,13 @@ SET xmloption TO { DOCUMENT | CONTENT }; CREATE DOMAIN posint AS integer CHECK (VALUE > 0); CREATE TABLE mytable (id posint); -INSERT INTO mytable VALUES(1); -- works -INSERT INTO mytable VALUES(-1); -- fails +INSERT INTO mytable VALUES(1); -- 成功 +INSERT INTO mytable VALUES(-1); -- 失败 - 当底层类型的一个操作符或函数适用于一个域值时,域会被自动向下转换为底层类型。因此,mytable.id - 1的结果会被认为是类型integer而不是posint。我们可以写成(mytable.id - 1)::posint来把结果转换回posint,这会导致域的约束被重新检查。在这种情况下,如果该表达式被应用于一个值为1的id就会错误。把底层类型的值赋给域类型的一个字段或者变量不需要写显式的类型转换,但是域的约束将会被检查。 + 当底层类型的一个操作符或函数被应用于一个域值时,域会被自动向下转换为底层类型。因此,mytable.id - 1的结果会被认为是类型integer而不是posint。我们可以写成(mytable.id - 1)::posint来把结果转换回posint,这会导致域的约束被重新检查。在这种情况下,如果该表达式被应用于一个值为1的id就会报错。把底层类型的值赋给域类型的一个字段或者变量不需要写显式的类型转换,但是域的约束将会被检查。 @@ -4362,7 +4341,7 @@ INSERT INTO mytable VALUES(-1); -- fails 对象标识符(OID)在 PostgreSQL 内部被用作 若干系统表的主键。类型 oid 表示一个对象标识符。 - 此外还有若干 oid 的别名类型,统称为 + 此外还有若干 oid 的别名类型,其名称均形如 regsomething 给出了概要说明。 @@ -4447,7 +4426,7 @@ SELECT * FROM pg_attribute regconfig pg_ts_config - 文本搜索配置 + 文本检索配置 english @@ -4461,7 +4440,7 @@ SELECT * FROM pg_attribute regdictionary pg_ts_dict - 文本搜索字典 + 文本检索词典 simple @@ -4497,7 +4476,7 @@ SELECT * FROM pg_attribute regprocedure pg_proc - 函数与参数类型 + 带参数类型的函数 sum(int4) @@ -4533,7 +4512,7 @@ SELECT * FROM pg_attribute - 这些类型的输入函数允许在各个标记之间插入空白,并且会把大写字母 + 这些类型的输入函数允许在各个词元之间插入空白,并且会把大写字母 折叠为小写,双引号内除外;这样做是为了让语法规则更接近 SQL 中 书写对象名的方式。反过来,如果需要让输出成为有效的 SQL 标识符, 输出函数会自动加上双引号。例如,一个名为 Foo @@ -4608,8 +4587,7 @@ WHERE ... 它就会对被引用对象建立依赖。例如,如果某列的默认表达式是 nextval('my_seq'::regclass)PostgreSQL 就会知道该默认表达式依赖于 - 序列 my_seq,因此系统在删除该序列之前,必须先 - 移除该默认表达式。改用 + 序列 my_seq,因此系统不允许在尚未移除该默认表达式时删除序列。改用 nextval('my_seq'::text) 则不会建立依赖。 (regdatabaseregrole 是这一特性的例外:这些类型的常量不允许出现在 存储表达式中。) @@ -4809,7 +4787,7 @@ WHERE ... anyarray - 表示一个函数可以接受任意数组数据类型(参见 + 表示一个函数可以接受任意数组数据类型(参见)。 @@ -4928,7 +4906,7 @@ WHERE ... unknown - 标识一种尚未解析出的类型,例如未修饰的字符串字面值。 + 标识一种尚未解析出的类型,例如未修饰的字符串字面值的类型。 @@ -4946,7 +4924,7 @@ WHERE ... voidrecord 用作结果类型 (如果函数被用作触发器或事件触发器,则也允许 triggerevent_trigger 作为结果类型)。 - 有些语言还支持借助多态伪类型来实现多态函数;详见 + 有些语言还支持借助上面列出的多态伪类型来实现多态函数;详见 diff --git a/zh/20/dict-int.sgml b/zh/20/dict-int.sgml index 50c37473..34269dcd 100644 --- a/zh/20/dict-int.sgml +++ b/zh/20/dict-int.sgml @@ -1,16 +1,16 @@ - dict_int — 用于整数的示例全文搜索词典 + dict_int — 用于整数的示例全文检索词典 dict_int - dict_int是一个全文搜索附加词典模板的示例。 + dict_int是一个全文检索附加词典模板的示例。 引入这个示例词典是为了控制整数(有符号和无符号)的索引, - 使这类数字能够被索引,同时又避免唯一词的数量过度增长, + 使这类数字能够被索引,同时又避免不同词的数量过度增长, 因为那会严重影响搜索性能。 @@ -54,7 +54,7 @@ 用法 - 安装dict_int扩展后,会创建一个文本搜索模板 + 安装dict_int扩展后,会创建一个文本检索模板 intdict_template以及一个基于该模板、使用默认参数的词典 intdict。你可以修改这些参数,例如: @@ -77,7 +77,7 @@ mydb# SELECT ts_lexize('intdict', '12345678'); 但在实际使用中,通常需要像所述那样, - 将它包含到某个文本搜索配置中。可能类似如下: + 将它包含到某个文本检索配置中。可能类似如下: ALTER TEXT SEARCH CONFIGURATION english diff --git a/zh/20/func/func-string.sgml b/zh/20/func/func-string.sgml index ac23ac09..87896955 100644 --- a/zh/20/func/func-string.sgml +++ b/zh/20/func/func-string.sgml @@ -480,7 +480,7 @@ 还有其他字符串操作函数和操作符,列在中。 (其中一些用于内部实现中列出的SQL标准字符串函数。) - 此外,中还描述了模式匹配操作符,中则描述了全文搜索操作符。 + 此外,中还描述了模式匹配操作符,中则描述了全文检索操作符。
diff --git a/zh/20/func/func-textsearch.sgml b/zh/20/func/func-textsearch.sgml index 4a3f705a..cf7fa8dc 100644 --- a/zh/20/func/func-textsearch.sgml +++ b/zh/20/func/func-textsearch.sgml @@ -1,6 +1,6 @@ - 文本搜索函数和操作符 + 文本检索函数和操作符 全文检索 @@ -8,7 +8,7 @@ - 文本搜索 + 文本检索 函数和操作符 @@ -16,12 +16,12 @@ 以及 - 总结了为全文检索提供的函数和操作符。PostgreSQL的文本搜索功能的详细解释可参考。 + 总结了为全文检索提供的函数和操作符。PostgreSQL的文本检索功能的详细解释可参考
- 文本搜索操作符 + 文本检索操作符 @@ -181,12 +181,12 @@ 除了这些专用操作符之外, 中所示的常用比较操作符也适用于tsvectortsquery类型。 - 这些操作符对文本搜索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。 + 这些操作符对文本检索用处不大,但可以用于其他用途,例如在这些类型的列上建立唯一索引。
- 文本搜索函数 + 文本检索函数 @@ -233,7 +233,7 @@ regconfig - 返回当前默认文本搜索配置的OID(由 所设定的). + 返回当前默认文本检索配置的 OID(由 设置)。 get_current_ts_config() @@ -769,18 +769,18 @@ - 所有接受一个可选的regconfig参数的文本搜索函数在省略该参数时,会使用由指定的配置。 + 所有接受一个可选的regconfig参数的文本检索函数在省略该参数时,会使用由指定的配置。 - 中的函数被单独列出,因为它们通常不被用于日常的文本搜索操作。 - 它们主要有助于开发和调试新的文本搜索配置。 + 中的函数被单独列出,因为它们通常不被用于日常的文本检索操作。 + 它们主要有助于开发和调试新的文本检索配置。
- 文本搜索调试函数 + 文本检索调试函数 @@ -816,7 +816,7 @@ lexemestext[] ) - 根据指定的或默认的文本搜索配置从document中提取和正规化词元,并返回关于每个词元是如何处理的信息。 + 根据指定的或默认的文本检索配置从document中提取和正规化词元,并返回关于每个词元是如何处理的信息。 详情参见 diff --git a/zh/20/gist.sgml b/zh/20/gist.sgml index 47d1dfd1..d0488f1e 100644 --- a/zh/20/gist.sgml +++ b/zh/20/gist.sgml @@ -1054,7 +1054,7 @@ my_translate_cmptype(PG_FUNCTION_ARGS) 示例 - PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本搜索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: + PostgreSQL源代码发行包包含了若干使用GiST实现的索引方法示例。核心系统目前提供了文本检索支持(为tsvectortsquery建立索引),并为某些内置几何数据类型提供了与 R 树等价的功能(见src/backend/access/gist/gistproc.c)。下列contrib模块中也包含GiST操作符类: diff --git a/zh/20/json.sgml b/zh/20/json.sgml index c33914db..6ec1386d 100644 --- a/zh/20/json.sgml +++ b/zh/20/json.sgml @@ -38,7 +38,7 @@ - 由于 json 类型存储的是输入文本的精确副本,因此它会保留标记 + 由于 json 类型存储的是输入文本的精确副本,因此它会保留词元 之间在语义上无关紧要的空白,以及 JSON 对象内部键的顺序。此外,如果值中 的某个 JSON 对象包含同一个键多次,所有键/值对都会被保留下来(处理函数会 将最后一个值视为生效值)。相比之下,jsonb 不保留空白,不保留 @@ -86,7 +86,7 @@ 当把文本形式的 JSON 输入转换为 jsonb 时, - RFC 7159 描述的基本类型会有效映射到原生的 + RFC 7159 描述的基本类型实际上会映射到原生的 PostgreSQL 类型上,如 所示。因此,什么样的数据构成 有效的 jsonb 会有一些额外但较小的限制,这些限制不适用于 @@ -137,7 +137,7 @@ null - (无) + (无) SQL NULL 是不同的概念 @@ -152,18 +152,18 @@ 以下都是有效的 json(或 jsonb)表达式: --- Simple scalar/primitive value --- Primitive values can be numbers, quoted strings, true, false, or null +-- 简单的标量/基本值 +-- 基本值可以是数字、加引号的字符串、true、false 或 null SELECT '5'::json; --- Array of zero or more elements (elements need not be of same type) +-- 包含零个或多个元素的数组(元素不必是同一类型) SELECT '[1, 2, "foo", null]'::json; --- Object containing pairs of keys and values --- Note that object keys must always be quoted strings +-- 包含键值对的对象 +-- 注意,对象的键必须始终是加引号的字符串 SELECT '{"bar": "baz", "balance": 7.77, "active": false}'::json; --- Arrays and objects can be nested arbitrarily +-- 数组和对象可以任意嵌套 SELECT '{"foo": [true, "bar"], "tags": {"a": 1, "b": null}}'::json; @@ -219,8 +219,7 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 当 JSON 数据存储在表中时,它与任何其他数据类型一样,都要面对相同的并发控 制考量。虽然存储大型文档是可行的,但要记住,任何更新都会在整行上获取一个 行级锁。应考虑将 JSON 文档限制在可管理的大小,以减少更新事务之间的锁争用。 - 理想情况下,每个 JSON 文档都应表示一个原子数据项,按照业务规则,它不应被 - 合理地进一步拆分为更小且可独立修改的数据项。 + 理想情况下,每个 JSON 文档都应表示一个原子数据项,根据业务规则,无法再合理地将它细分为更小且可独立修改的数据项。 @@ -228,11 +227,11 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; <type>jsonb</type> 包含与存在 jsonb - containment + 包含 jsonb - existence + 存在 测试 包含jsonb 的一项重要能力。 @@ -241,33 +240,32 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; 示例都返回真: --- Simple scalar/primitive values contain only the identical value: +-- 简单的标量/基本值只包含相同的值: SELECT '"foo"'::jsonb @> '"foo"'::jsonb; --- The array on the right side is contained within the one on the left: +-- 左侧数组包含右侧数组: SELECT '[1, 2, 3]'::jsonb @> '[1, 3]'::jsonb; --- Order of array elements is not significant, so this is also true: +-- 数组元素的顺序无关紧要,因此下面的结果也为真: SELECT '[1, 2, 3]'::jsonb @> '[3, 1]'::jsonb; --- Duplicate array elements don't matter either: +-- 重复的数组元素也无关紧要: SELECT '[1, 2, 3]'::jsonb @> '[1, 2, 2]'::jsonb; --- The object with a single pair on the right side is contained --- within the object on the left side: +-- 左侧对象包含右侧只有一个键值对的对象: SELECT '{"product": "PostgreSQL", "version": 9.4, "jsonb": true}'::jsonb @> '{"version": 9.4}'::jsonb; --- The array on the right side is not considered contained within the --- array on the left, even though a similar array is nested within it: -SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- yields false +-- 左侧数组被认为包含右侧数组, +-- 尽管其中嵌套了一个类似的数组: +SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- 结果为假 --- But with a layer of nesting, it is contained: +-- 但增加一层嵌套后,就构成了包含关系: SELECT '[1, 2, [1, 3]]'::jsonb @> '[[1, 3]]'::jsonb; --- Similarly, containment is not reported here: -SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- yields false +-- 同样,下面也不构成包含关系: +SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- 结果为假 --- A top-level key and an empty object is contained: +-- 包含由顶层键和空对象构成的对象: SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; @@ -282,11 +280,11 @@ SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb; 对于结构必须匹配这一一般原则,有一个特殊例外:数组可以包含一个基本值: --- This array contains the primitive string value: +-- 这个数组包含该基本字符串值: SELECT '["foo", "bar"]'::jsonb @> '"bar"'::jsonb; --- This exception is not reciprocal -- non-containment is reported here: -SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false +-- 这个例外并不对称——下面的结果表示不包含: +SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- 结果为假 @@ -296,19 +294,19 @@ SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false 外,下面这些示例都返回真: --- String exists as array element: +-- 字符串作为数组元素存在: SELECT '["foo", "bar", "baz"]'::jsonb ? 'bar'; --- String exists as object key: +-- 字符串作为对象键存在: SELECT '{"foo": "bar"}'::jsonb ? 'foo'; --- Object values are not considered: -SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- yields false +-- 不考虑对象的值: +SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- 结果为假 --- As with containment, existence must match at the top level: -SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- yields false +-- 与包含关系一样,存在性必须在顶层匹配: +SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- 结果为假 --- A string is considered to exist if it matches a primitive JSON string: +-- 如果字符串与一个基本 JSON 字符串匹配,则认为它存在: SELECT '"foo"'::jsonb ? 'foo'; @@ -322,8 +320,7 @@ SELECT '"foo"'::jsonb ? 'foo'; 由于 JSON 包含是嵌套的,因此适当的查询可以跳过对子对象的显式选择。例如, 假设我们有一个 doc 列,其顶层是对象,而且大 多数对象都带有 tags 字段,该字段中包含子对象数组。下面 - 这个查询会找出那些包含同时带有 "term":"paris" 和 - "term":"food" 的子对象的项,同时忽略 + 这个查询会找出同时出现包含 "term":"paris" 的子对象和包含 "term":"food" 的子对象的项,同时忽略 tags 数组之外的任何此类键: SELECT doc->'site_name' FROM websites @@ -353,7 +350,7 @@ SELECT doc->'site_name' FROM websites <type>jsonb</type> 索引 jsonb - indexes on + 索引 @@ -403,14 +400,14 @@ CREATE INDEX idxginp ON api USING GIN (jdoc jsonb_path_ops); 名为 jdocjsonb 列里。 如果在该列上创建了 GIN 索引,那么下面这样的查询就可以利用这个索引: --- Find documents in which the key "company" has value "Magnafone" +-- 查找键 "company" 的值为 "Magnafone" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"company": "Magnafone"}'; 但是,类似下面这样的查询就无法使用该索引,因为虽然操作符 ? 可索引,但它并未直接应用到被索引的列 jdoc 上: --- Find documents in which the key "tags" contains key or array element "qui" +-- 查找键 "tags" 包含键或数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc -> 'tags' ? 'qui'; 不过,只要适当地使用表达式索引,上述查询也可以利用索引。如果经常查询 @@ -428,7 +425,7 @@ CREATE INDEX idxgintags ON api USING GIN ((jdoc -> 'tags')); 另一种查询方法是利用包含,例如: --- Find documents in which the key "tags" contains array element "qui" +-- 查找键 "tags" 包含数组元素 "qui" 的文档 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qui"]}'; jdoc 列上的简单 GIN 索引可以支持这个查询。 @@ -466,7 +463,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; @@ 操作符的查询,但相较于默认操作符类 jsonb_ops,它具有显著的性能优势。 jsonb_path_ops 索引通常比相同数据上的 - jsonb_ops 索引小得多,而且搜索条件也更具特异性,尤其是在 + jsonb_ops 索引小得多,而且搜索也更有针对性,尤其是在 查询中包含数据里频繁出现的键时。因此,搜索操作通常比使用默认操作符类时 性能更佳。 @@ -482,9 +479,9 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; 基本上,每个 jsonb_path_ops 索引项都是该值连同 - 通向该值的键一起计算出的哈希。例如,要索引 + 通向该值的键一起计算出的 hash。例如,要索引 {"foo": {"bar": "baz"}},会创建一个单独的索引项, - 其哈希值中同时纳入 foobar 和 + 其 hash 值中同时纳入 foobarbaz 这三者。因此,查找这一结构的包含查询会得到一次 非常精确的索引搜索;但完全没有办法据此找出 foo 是否 作为键出现。另一方面,jsonb_ops 索引会分别创建三个 @@ -506,7 +503,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; jsonb 还支持 btreehash 索引。通常只有在需要检查完整 JSON 文档是否相等时, 它们才有用。btreejsonb 数据项的 - 排序通常没什么太大意义,但为了完整起见,其规则如下: + 排序顺序通常很少受到关注,但为了完整起见,其规则如下: 对象 > 数组 > 布尔值 > 数字 > 字符串 > null @@ -561,27 +558,24 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; --- Extract object value by key +-- 按键提取对象的值 SELECT ('{"a": 1}'::jsonb)['a']; --- Extract nested object value by key path +-- 按键路径提取嵌套对象的值 SELECT ('{"a": {"b": {"c": 1}}}'::jsonb)['a']['b']['c']; --- Extract array element by index +-- 按下标提取数组元素 SELECT ('[1, "2", null]'::jsonb)[1]; --- Update object value by key. Note the quotes around '1': the assigned --- value must be of the jsonb type as well +-- 按键更新对象的值。注意 '1' 两边的引号:赋予的值也必须是 jsonb 类型 UPDATE table_name SET jsonb_field['key'] = '1'; --- This will raise an error if any record's jsonb_field['a']['b'] is something --- other than an object. For example, the value {"a": 1} has a numeric value --- of the key 'a'. +-- 如果任何记录的 jsonb_field['a']['b'] 不是对象,就会报错。 +-- 例如,值 {"a": 1} 的键 'a' 对应的值是数字。 UPDATE table_name SET jsonb_field['a']['b']['c'] = '1'; --- Filter records using a WHERE clause with subscripting. Since the result of --- subscripting is jsonb, the value we compare it against must also be jsonb. --- The double quotes make "value" also a valid jsonb string. +-- 使用带下标的 WHERE 子句筛选记录。由于下标操作的结果是 jsonb, +-- 与之比较的值也必须是 jsonb。双引号使 "value" 也成为合法的 jsonb 字符串。 SELECT * FROM table_name WHERE jsonb_field['key'] = '"value"'; @@ -591,19 +585,19 @@ SELECT * FROM table_name WHERE jsonb_field['key'] = '"value"'; (对象或数组)的空 JSON 值来处理: --- Where jsonb_field was NULL, it is now {"a": 1} +-- 原先为 NULL 的 jsonb_field 现在为 {"a": 1} UPDATE table_name SET jsonb_field['a'] = '1'; --- Where jsonb_field was NULL, it is now [1] +-- 原先为 NULL 的 jsonb_field 现在为 [1] UPDATE table_name SET jsonb_field[0] = '1'; - 如果对一个元素数量不足的数组指定了某个索引,就会不断追加 - NULL 元素,直到该索引可达并且可以设置该值为止。 + 如果对一个元素数量不足的数组指定了某个下标,就会不断追加 + NULL 元素,直到该下标可达并且可以设置该值为止。 --- Where jsonb_field was [], it is now [null, null, 2]; --- where jsonb_field was [0], it is now [0, null, 2] +-- 原先为 [] 的 jsonb_field 现在为 [null, null, 2]; +-- 原先为 [0] 的 jsonb_field 现在为 [0, null, 2] UPDATE table_name SET jsonb_field[2] = '2'; @@ -614,10 +608,10 @@ UPDATE table_name SET jsonb_field[2] = '2'; null 填充,直到能够放入被赋值的值为止。 --- Where jsonb_field was {}, it is now {"a": [{"b": 1}]} +-- 原先为 {} 的 jsonb_field 现在为 {"a": [{"b": 1}]} UPDATE table_name SET jsonb_field['a'][0]['b'] = '1'; --- Where jsonb_field was [], it is now [null, {"a": 1}] +-- 原先为 [] 的 jsonb_field 现在为 [null, {"a": 1}] UPDATE table_name SET jsonb_field[1]['a'] = '1'; @@ -634,7 +628,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; PL/Perl 的扩展名为 jsonb_plperljsonb_plperlu。如果使用它们, - jsonb 值会按适当方式映射为 Perl 数组、哈希和标量。 + jsonb 值会按适当方式映射为 Perl 数组、hash 和标量。 @@ -694,7 +688,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; 的。还支持非十进制整数字面量和下划线分隔符,例如 1_000_0000x1EEE_FFFF0o2730b100101。在 SQL/JSON - 路径中(以及 JavaScript 中,但不包括严格意义上的 SQL),基数前缀后面不能 + 路径中(以及 JavaScript 中,但 SQL 本身并非如此),基数前缀后面不能 直接出现下划线分隔符。 @@ -723,7 +717,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; - 路径表达式由一系列路径元素构成,可以是下列任意一种: + 路径表达式由一系列路径元素构成,这些元素可以是下列任意一种: @@ -784,7 +778,6 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; ),或者通过 SQL/JSON PASSING 子句来设置,如 所述。 - @@ -864,7 +857,7 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; 类似 .**,但只选择 JSON 层次结构中指定的层级。 - 嵌套层级以整数指定。层级零对应当前对象。若要访问最低的嵌套层级, + 嵌套层级以整数指定。层级零对应当前对象。若要访问最深的嵌套层级, 可以使用 last 关键字。这是 PostgreSQL 对 SQL/JSON 标准的扩展。 @@ -882,13 +875,13 @@ UPDATE table_name SET jsonb_field[1]['a'] = '1'; 可以用两种形式给出: indexstart_index to end_index。 - 第一种形式按索引返回单个数组元素。第二种形式按索引范围返回数组切片, + 第一种形式按下标返回单个数组元素。第二种形式按下标范围返回数组切片, 其中包括与给定 start_indexend_index 对应的元素。 指定的 index 可以是整数,也可以是返回单个 - 数值的表达式,该表达式会自动转换为整数。索引零对应第一个数组元素。 + 数值的表达式,该数值会自动转换为整数。下标零对应第一个数组元素。 你也可以使用 last 关键字来表示最后一个数组元素, 这对于处理长度未知的数组很有用。 diff --git a/zh/20/libpq.sgml b/zh/20/libpq.sgml index 888bf6e1..71a35bdd 100644 --- a/zh/20/libpq.sgml +++ b/zh/20/libpq.sgml @@ -2,7 +2,7 @@ - <application>libpq</application> - C 库 + <application>libpq</application> — C 库 libpq @@ -13,33 +13,27 @@ - libpq是应用程序员使用PostgreSQLC接口。libpq是一个库函数的集合,它们允许客户端程序传递查询给PostgreSQL后端服务器并且接收这些查询的结果。 + libpqPostgreSQLC应用程序编程接口。libpq是一组库函数,客户端程序可用它们向PostgreSQL后端服务器发送查询并接收查询结果。 - libpq也是很多其他PostgreSQL应用接口的底层引擎,包括为 C++、Perl、Python、Tcl 和 ECPG编写的接口。如果你使用那些包,某些方面的libpq行为将会对你很重要。特别是,描述了任何使用libpq的应用的用户可见的行为。 + libpq也是其他几个PostgreSQL应用程序接口的底层引擎,包括为 C++、Perl、Python、Tcl 和ECPG编写的接口。因此,对于这些包的用户,libpq行为的某些方面也很重要。特别是,描述了任何使用libpq的应用程序的用户都能观察到的行为。 - 在本章的末尾()包括了一些短程序来展示如何编写使用libpq的应用。在源代码发布的src/test/examples目录中还有一些完整的libpq应用的示例。 + 本章末尾()包含一些简短程序,展示如何编写使用libpq的程序。源代码发行包的src/test/examples目录中还提供了几个完整的libpq应用程序示例。 - 使用libpq的客户端程序必须包括头文件libpq-fe.hlibpq-fe.h并必须与libpq库链接在一起。 + 使用libpq的客户端程序必须包含头文件libpq-fe.hlibpq-fe.h,并且必须与libpq库链接。 数据库连接控制函数 - - 下列函数会建立到一个PostgreSQL后端服务器的连接。 - 一个应用程序可以在一个时刻打开多个后端连接(原因之一就是为了访问多个数据库)。 - 每个连接用一个PGconnPGconn对象表示,它从函数,或得到。 - 注意这些函数将总是返回一个非空的对象指针,除非正好没有内存来分配PGconn对象。 - 在通过该连接对象发送查询之前,应该调用函数来检查返回值以确定是否得到了一个成功的连接。 - - + 以下函数用于建立到PostgreSQL后端服务器的连接。应用程序可以同时保持多个后端连接。(这样做的原因之一是访问多个数据库。)每个连接由一个PGconnPGconn对象表示,该对象可以通过以下函数获取:, + 。注意,这些函数总是返回非空的对象指针,除非内存不足,甚至无法分配PGconn对象。应调用函数检查返回值,确认连接成功后,再通过连接对象发送查询。 如果不受信任的用户能够访问一个没有采用模式的安全使用方式的数据库,那么每个会话开始时都应从search_path中移除公开可写的模式。可以把参数关键词options设置为-csearch_path=。也可以在连接后发出PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)")。这种考虑并非专门针对libpq;它适用于每一种可执行任意 SQL 命令的接口。 @@ -47,7 +41,7 @@ - 在 Unix 上,复制一个拥有打开 libpq 连接的进程可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行代码是安全的。 + 在 Unix 上,对持有已打开 libpq 连接的进程执行 fork 操作可能导致不可预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行程序是安全的。 @@ -74,32 +68,32 @@ PGconn *PQconnectdbParams(const char * const *keywords, - 被传递的数组可以为空,这样就会使用所有默认参数。 - 也可以只包含一个或几个参数设置。他们在长度上必须匹配。 - 对于参数数组的处理将会停止于keywords数组中第一个NULL元素。 - 而且,如果与非-NULL keywords条目相关联的values条目为NULL或者空字符串,则忽略该项并继续处理下一对数组项。 + 传入的数组可以为空,以使用所有默认参数,也可以包含一个或多个参数设置。 + 两个数组的长度必须相同。处理会在 keywords 数组的第一个 NULL 元素处停止。 + 如果某个非 NULLkeywords 元素所对应的 + values 元素为 NULL 或空字符串,则忽略这一项,继续处理下一对数组元素。 - 当expand_dbname为非零时,会检查第一个dbname关键词的值以查看它是否为一个连接字符串。 - 如果是,它被扩展到从字符串中提取的单独的连接参数。 - 该值被认为是一个连接字符串,而不仅是一个数据库名称,如果它包含一个等号(=)或者它以URI模式标志符开头, - (有关连接字符串格式的更多详情可见。) - 只有dbname的第一次出现会按这种方式处理,任何后续dbname值会被当做一个普通数据库名处理。 + 当 expand_dbname 非零时,会检查第一个 dbname 关键词的值是否为 + 连接字符串。如果是,就将其展开为从该字符串中提取的各个连接参数。 + 如果该值包含等号(=),或以 URI 方案标识符开头,就会将其视为连接字符串,而非单纯的数据库名。 + (连接字符串格式的详细说明见。) + 只有第一次出现的 dbname 会按这种方式处理;后续的 dbname 参数都作为普通数据库名处理。 - 通常,参数数组从开头到结尾进行处理。 - 当关键词有重复时,使用最后一个值(不是 NULL 或空)。 - 此规则特别适用于连接字符串中的关键字与一个出现在keywords数组中的关键字冲突的情况。 - 因此,程序员可以决定数组条目是否能被覆盖或用连接字符串获取的值覆盖。 - 出现在扩展的dbname条目之前的数组条目可以被连接字符串的字段所覆盖,反之,这些字段被dbname之后出现的数组条目所覆盖。(但是,再有,只有在那些条目支持非空值时。) + 通常会从头到尾处理参数数组。如果某个关键词重复出现,则采用最后一个非 NULL 且非空的值。 + 此规则也适用于连接字符串中的关键词与 keywords 数组中的关键词冲突的情况。 + 因此,程序员可以决定数组元素是覆盖连接字符串中的值,还是被这些值覆盖。 + 出现在要展开的 dbname 元素之前的数组元素,可以被连接字符串中的字段覆盖; + 而这些字段又会被出现在 dbname 之后的数组元素覆盖(同样,只有这些元素提供非空值时才会覆盖)。 - 在处理完所有数组条目和任何扩展的连接字符串后,所有未设置的连接参数都将使用默认值填充。 - 如果一个未设置参数的相关环境变量(参见 )被设置了,它的值会被使用。 - 如果环境变量未被设置,则使用参数的内置默认值。 + 处理完所有数组元素及展开的连接字符串后,仍未设置的连接参数将填入默认值。 + 如果某个未设置参数对应的环境变量(见)已经设置,就使用该环境变量的值; + 否则使用该参数的内置默认值。 @@ -121,7 +115,7 @@ PGconn *PQconnectdb(const char *conninfo); - 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空格分隔的一个或多个参数设置,还可以包含一个URI。详见。 + 被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空白分隔的一个或多个参数设置,还可以包含一个URI。详见 @@ -144,11 +138,11 @@ PGconn *PQsetdbLogin(const char *pghost, - 这是的带有固定参数集合的前辈。它具有相同的功能,不过其中缺失的参数将总是采用默认值。对任意一个固定参数写NULL或一个空字符串将会使它采用默认值。 + 这是 的前身,使用固定的一组参数。除缺失参数始终采用默认值之外,功能相同。对于要使用默认值的任意固定参数,请传入 NULL 或空字符串。 - 如果dbName包含一个=符号或者具有一个合法的连接URI前缀,它会被当作一个conninfo字符串,就好像它已经被传递给了,并且剩余的参数则被应用为指定给。 + 如果 dbName 包含 = 符号,或具有有效的连接 URI 前缀,就会将其当作 conninfo 字符串处理,方式与将其传给 完全相同,然后按照 的规则应用其余参数。 @@ -183,7 +177,7 @@ PGconn *PQsetdb(char *pghost, PQconnectPollPQconnectPoll - nonblocking connection + 非阻塞连接 以非阻塞的方式建立一个到数据库服务器的连接。 @@ -220,7 +214,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 如果你调用,确保你追踪的该流对象不会阻塞。 + 如果你调用,确保接收追踪输出的流对象不会阻塞。 @@ -233,11 +227,11 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 要开始无阻塞的连接请求,可调用PQconnectStart或者。如果结果为空,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 + 要开始非阻塞连接请求,可调用PQconnectStart或者。如果结果为空指针,则libpq无法分配一个新的PGconn结构体。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。 - 如果PQconnectStart成功,下一个阶段是轮询libpq,这样它能够继续进行连接序列。使用PQsocket(conn)来获得该数据库连接底层的套接字描述符(警告:不要假定在PQconnectPoll调用之间套接字会保持相同)。这样循环:如果PQconnectPoll(conn)上一次返回PGRES_POLLING_READING,等到该套接字准备好读取(按照select()poll()或类似的系统函数所指示的)。则再次调用PQconnectPoll(conn)。反之,如果PQconnectPoll(conn)上一次返回PGRES_POLLING_WRITING,等到该套接字准备好写入,则再次调用PQconnectPoll(conn)。在第一次迭代时,即如果你还没有调用PQconnectPoll,行为就像是它上次返回了PGRES_POLLING_WRITING。持续这个循环直到PQconnectPoll(conn)返回PGRES_POLLING_FAILED指示连接过程已经失败,或者返回PGRES_POLLING_OK指示连接已经被成功地建立。 + 如果PQconnectStart成功,下一个阶段是轮询libpq,这样它能够继续进行连接序列。使用PQsocket(conn)来获得该数据库连接底层的套接字描述符(警告:不要假定在PQconnectPoll调用之间套接字会保持相同)。这样循环:如果PQconnectPoll(conn)上一次返回PGRES_POLLING_READING,等到该套接字准备好读取(按照select()poll()或类似的系统函数所指示的)。注意,PQsocketPoll封装了select(2)poll(2)(如果系统支持)的设置,可减少重复代码。然后再次调用PQconnectPoll(conn)。反之,如果PQconnectPoll(conn)上一次返回PGRES_POLLING_WRITING,等到该套接字准备好写入,则再次调用PQconnectPoll(conn)。在第一次迭代时,即如果你还没有调用PQconnectPoll,行为就像是它上次返回了PGRES_POLLING_WRITING。持续这个循环直到PQconnectPoll(conn)返回PGRES_POLLING_FAILED指示连接过程已经失败,或者返回PGRES_POLLING_OK指示连接已经被成功地建立。 @@ -327,7 +321,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - 注意,尽管这些常数将被保留(为了维护兼容性),一个应用永远不应该依赖这些状态按照特定顺序出现,或者根本就不依赖它们,或者不依赖状态总是这些文档中所说的值。一个应用可能做些这样的事情: + 注意,虽然为保持兼容性会保留这些常量,但应用程序不应依赖它们按特定顺序出现,不应假定它们一定出现,也不应假定状态值一定是这里列出的某个值。应用程序可以采用如下方式: switch(PQstatus(conn)) { @@ -348,11 +342,11 @@ switch(PQstatus(conn)) - 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。否则,PQconnectStart后面跟着PQconnectPoll循环等效于。 + 在使用PQconnectPoll时,连接参数connect_timeout会被忽略:判断是否超时是应用的责任。除此之外,PQconnectStart后面跟着PQconnectPoll循环等效于 - 注意当PQconnectStart返回一个非空的指针时,你必须在用完它之后调用来处理那些结构体和任何相关的内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 + 注意当PQconnectStart返回一个非空的指针时,你必须在用完它之后调用来释放该结构体及其关联的所有内存块。即使连接尝试失败或被放弃时也必须完成这些工作。 @@ -400,21 +394,21 @@ PQconninfoOption *PQconndefaults(void); typedef struct { char *keyword; /* 该选项的关键词 */ - char *envvar; /* 依赖的环境变量名 */ - char *compiled; /* 依赖的内置默认值 */ + char *envvar; /* 后备环境变量名 */ + char *compiled; /* 编译时设置的后备默认值 */ char *val; /* 选项的当前值,或者 NULL */ - char *label; /* 连接对话框中域的标签 */ - char *dispchar; /* 指示如何在一个连接对话框中显示这个域。值是: + char *label; /* 连接对话框中字段的标签 */ + char *dispchar; /* 指示如何在连接对话框中显示此字段。可取值: "" 显示输入的值 - "*" 密码域 - 隐藏值 + "*" 密码字段 - 隐藏值 "D" 调试选项 - 默认不显示 */ - int dispsize; /* 用于对话框的以字符计的域尺寸 */ + int dispsize; /* 对话框中的字段宽度,以字符计 */ } PQconninfoOption; - 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前缺省值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回该空指针。注意当前缺省值(val域)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 + 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前默认值。返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。如果无法分配内存,则返回空指针。注意当前默认值(val字段)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。 @@ -435,9 +429,7 @@ PQconninfoOption *PQconninfo(PGconn *conn); - 返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的选项和它们的当前缺省值。 - 返回值指向一个PQconninfoOption结构体的数组,该数组以一个包含空keyword指针的条目结束。 - 上述所有对于的注解也适用于的结果。 + 返回一个连接选项数组。可以用它确定所有可能的 选项,以及实际用于连接服务器的值。返回值指向一个 PQconninfoOption 结构体数组,该数组以 keyword 指针为空的条目结束。上文针对 的所有注意事项,也适用于 的结果。 @@ -463,7 +455,9 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); - 如果errmsg不是NULL,那么成功时*errmsg会被设置为NULL, 否则设置为被malloc过的错误字符串以说明该问题(也可以将*errmsg设置为NULL并且函数返回NULL,这表示一种内存耗尽的情况)。 + 如果 errmsg 不是 NULL,则成功时将 *errmsg 设为 NULL; + 失败时将其设为由 malloc 分配的、用于说明问题的错误字符串。 + (也可能出现 *errmsg 被设为 NULL,同时函数返回 NULL 的情况;这表示内存不足。) @@ -493,7 +487,7 @@ void PQfinish(PGconn *conn); PQresetPQreset - 重置与服务器的通讯通道。 + 重置与服务器的通信通道。 void PQreset(PGconn *conn); @@ -511,7 +505,7 @@ void PQreset(PGconn *conn); PQresetPollPQresetPoll - 以非阻塞方式重置与服务器的通讯通道。 + 以非阻塞方式重置与服务器的通信通道。 int PQresetStart(PGconn *conn); @@ -528,7 +522,7 @@ PostgresPollingStatusType PQresetPoll(PGconn *conn); - 要发起一次连接重置,调用。如果它返回 0,那么重置失败。如果返回 1,就按使用PQresetPoll建立连接时相同的方法,继续调用PQresetPoll来重置连接。 + 要开始重置连接,请调用 。如果返回 0,表示重置失败。如果返回 1,则使用 PQresetPoll 轮询重置过程,方式与使用 PQconnectPoll 建立连接完全相同。 @@ -623,7 +617,7 @@ void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook); int callback_fn(char *buf, int size, PGconn *conn); - 随后,libpq会调用该回调,而不是调用其默认的PQdefaultSSLKeyPassHook_OpenSSL处理程序。 + 随后,libpq会调用该回调,而不是调用其默认的PQdefaultSSLKeyPassHook_OpenSSL处理程序。 回调函数应确定密钥密码,并将其复制到大小为size的结果缓冲区buf中。 buf中的字符串必须以空字符结尾。 回调函数必须返回存储在buf中的密码长度,不包括结尾的空字符。 @@ -642,7 +636,7 @@ int callback_fn(char *buf, int size, PGconn *conn); - 除了异常、longjmp(...)等情况外,回调务必不可跳出正常控制流。它必须正常返回。 + 回调不得通过异常、longjmp(...)等方式跳出正常控制流。它必须正常返回。 @@ -679,9 +673,9 @@ PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void); 几个libpq函数解析用户指定的字符串以获取连接参数。 - 这些字符串有两种被接受的格式:普通的关键字/值字符串和URI。URI通常遵循 + 这些字符串有两种被接受的格式:普通的关键词/值字符串和URI。URI通常遵循 RFC - 3986,除了允许多主机连接字符串,如下面进一步描述的那样。 + 3986,但也允许使用多主机连接字符串,详见下文。 @@ -689,10 +683,10 @@ PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void); 关键词/值连接字符串 - 在关键词/值格式中,每一个参数设置的形式都是关键词 = ,在设置之间有空白。 - 设置的等号周围的空白是可选的。 - 要写一个空值或一个包含空白的值,将它用单引号包围,例如关键词 = 'a value'。 - 值里面的单引号和反斜线必须用一个反斜线转义,即\'\\。 + 在关键词/值格式中,每一个参数设置的形式都是关键词 = ,设置之间以空格分隔。 + 设置的等号周围的空格是可选的。 + 要写一个空值或一个包含空格的值,将它用单引号包围,例如keyword = 'a value'。 + 值里面的单引号和反斜杠必须用一个反斜杠转义,即\'\\ @@ -716,22 +710,22 @@ host=localhost port=5432 dbname=mydb connect_timeout=10 postgresql://userspec@hostspec/dbname?paramspec -where userspec is: +其中 userspec 为: user:password -and hostspec is: +hostspec 为: host:port,... -and paramspec is: +paramspec 为: name=value&... - URI模式标志符可以是postgresql://postgres://。 + URI方案标识符可以是postgresql://postgres://。 每一个剩下的URI部分都是可选的。 下列示例展示了合法的URI语法: @@ -748,19 +742,15 @@ postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application postgresql:///mydb?host=localhost&port=5433 - 全部的命名参数必须匹配中列出的关键词,除了与JDBC连接URI兼容之外,ssl=true的实例转换到sslmode=require。 + 所有命名参数都必须与中列出的关键词匹配;唯一的例外是,为兼容 JDBC 连接 URI,会将 ssl=true 转换为 sslmode=require - 连接URI需要使用百分号编码 - 对其进行编码,如果其中包含具有特殊含义的符号。这里是一个示例,其中等号(=)被替换为 - %3D,空格字符被替换为 - %20: + 如果连接 URI 的任意部分包含具有特殊含义的符号,就需要使用百分号编码。下面的示例将等号(=)替换为 %3D,将空格字符替换为 %20 postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff - + 主机部分可能是主机名或一个 IP 地址。要指定一个 IPv6 地址,将它封闭在方括号中: @@ -773,7 +763,7 @@ postgresql://[2001:db8::1234]/database 主机组件会被按照参数对应的描述来解释。 特别地,如果主机部分是空或看起来像一个绝对路径名称,将使用一个 Unix 域套接字连接,否则将启动一个 TCP/IP 连接。 不过要注意,斜线是 URI 层次部分中的一个保留字符。 - 因此,要指定一个非标准的 Unix 域套接字目录,要么忽略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: + 因此,要指定一个非标准的 Unix 域套接字目录,要么省略 URI 中的主机部分并且指定该主机为一个命名参数,要么在 URI 的主机部分用百分号编码路径: postgresql:///dbname?host=/var/lib/postgresql postgresql://%2Fvar%2Flib%2Fpostgresql/dbname @@ -783,7 +773,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以在一个URI中指定多个主机,每一个都有一个可选的端口。 一个形式为postgresql://host1:port1,host2:port2,host3:port3/的URI等效于host=host1,host2,host3 port=port1,port2,port3形式的连接字符串。 - 如下所述,每一个主机都将被尝试,直到成功地建立一个连接。 + 如下所述,每一个主机都将被依次尝试,直到成功地建立一个连接。 @@ -793,7 +783,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 可以指定多个要连接的主机,这样它们会按给定的顺序被尝试。 - 在键/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 + 在关键词/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 在指定的每一个选项中都必须给出相同数量的元素,这样第一个hostaddr对应于第一个主机名,第二个hostaddr对应于第二个主机名,以此类推。 不过,如果仅指定一个port,它将被应用于所有的主机。 @@ -803,11 +793,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 不管是哪一种格式,单一的主机名可以被翻译成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 + 不管是哪一种格式,单一的主机名可以被解析成多个网络地址。常见的示例是一个主机同时具有IPv4和IPv6地址。 - 当多个主机被指定时或者单个主机名被翻译成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。 + 当多个主机被指定时或者单个主机名被解析成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。 @@ -829,14 +819,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 要连接的主机名。主机名如果主机名看起来像绝对路径名, - 则指定的是Unix域通信而不是TCP/IP通信;该值是存储套接字文件的目录的名称。 - (在Unix上,绝对路径名以斜杠开头。在Windows上,以驱动器号开头的路径也被识别。) - 如果主机名以@开头,则将其视为抽象命名空间中的Unix域套接字(目前在Linux和Windows上支持)。 - 当未指定host或为空时,默认行为是连接到Unix域套接字Unix域套接字在 - /tmp(或在构建PostgreSQL时指定的套接字目录)中。在Windows和 - 没有Unix域套接字的机器上,默认是连接到localhost。 - + 要连接的主机名。主机名如果主机名看起来像绝对路径名, + 则指定的是 Unix 域通信,而非 TCP/IP 通信;此值是存放套接字文件的目录名。 + (在 Unix 上,绝对路径名以斜杠开头。在 Windows 上,也会识别以驱动器号开头的路径。)如果主机名以 @ 开头,则将其视为抽象命名空间中的 Unix 域套接字(目前在 Linux 和 Windows 上支持)。 + 当未指定 host 或其值为空时,默认连接到 /tmp + (或构建 PostgreSQL 时指定的套接字目录)中的 Unix 域套接字。 + Unix 域套接字在 Windows 上,默认连接到 localhost。 + 也可以接受一个逗号分隔的主机名列表,此时列表中的每个主机名将按顺序尝试; @@ -864,7 +853,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 如果指定了host而没有指定hostaddr,则会发生主机名查找。 (当使用PQconnectPoll时,查找发生在PQconnectPoll首次考虑此主机名时, - 并且可能导致PQconnectPoll阻塞一段时间。) + 并且可能导致PQconnectPoll阻塞相当长的时间。) @@ -876,11 +865,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果同时指定了hosthostaddr, - 则hostaddr的值给出服务器的网络地址。 - 除非认证方法需要,否则host的值将被忽略, - 在这种情况下,它将用作主机名。 - + 如果同时指定了 hosthostaddr,则 hostaddr 的值给出服务器的网络地址。只有认证方法需要主机名时,才会将 host 的值用作主机名;否则忽略该值。 + 请注意,如果host不是网络地址hostaddr上服务器的名称, @@ -896,10 +882,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 没有主机名或主机地址, - libpq将使用本地的Unix域套接字进行连接; - 或者在Windows和没有Unix域套接字的机器上,它将尝试连接到localhost。 - + 如果既没有主机名也没有主机地址,libpq 会使用本地 Unix 域套接字连接;在 Windows 上,则会尝试连接到 localhost。 + @@ -933,8 +917,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - PostgreSQL用户连接的用户名。 - 默认为运行应用程序的操作系统用户名相同。 + 建立连接所用的 PostgreSQL 用户名。默认与运行应用程序的操作系统用户名相同。 @@ -944,7 +927,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果服务器要求密码认证,则使用密码。 + 服务器要求密码认证时所使用的密码。 @@ -965,7 +948,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname require_auth - 指定客户端要求服务器采用的认证方法。如果服务器没有使用所要求的方法来认证客户端,或者服务器没有完整完成认证握手,则连接将失败。也可以提供一个以逗号分隔的方法列表,此时服务器必须准确使用其中一种方法,连接才会成功。默认情况下接受任意认证方法,并且服务器也可以完全跳过认证。 + 指定客户端要求服务器采用的认证方法。如果服务器没有使用所要求的方法来认证客户端,或者服务器没有完整完成认证握手,则连接将失败。也可以提供一个以逗号分隔的方法列表,此时服务器必须恰好使用其中一种方法,连接才会成功。默认情况下接受任意认证方法,并且服务器也可以完全跳过认证。 可以在方法名前加上!前缀以表示否定,此时服务器不得尝试所列方法;除此之外,任何其他方法都可接受,并且服务器也可以完全不认证客户端。如果提供的是逗号分隔列表,服务器不得尝试其中任何一个被否定的方法。否定形式和非否定形式不能在同一设置中混用。 @@ -1055,7 +1038,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 这个选项控制客户端对通道绑定的使用。设置为require表示连接必须使用通道绑定, prefer表示客户端将在可用时选择通道绑定, 而disable则阻止使用通道绑定。默认情况下, - 如果PostgreSQL是使用SSL支持编译的,则默认为prefer; + 如果PostgreSQL是使用SSL支持编译的,则默认为prefer; 否则默认为disable @@ -1071,9 +1054,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 连接时的最长等待时间,以秒为单位(写成十进制整数,例如,10)。 - 零、负值或未指定表示无限等待。最小允许的超时时间为2秒,因此 - 1的值被解释为2。 - 此超时时间分别适用于每个主机名或IP地址。 + 零、负值或未指定表示无限等待。此超时时间分别适用于每个主机名或IP地址。 例如,如果指定了两个主机和connect_timeout 为5,如果在5秒内没有建立连接,每个主机将超时, 因此等待连接的总时间可能长达10秒。 @@ -1119,9 +1100,9 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 指定配置参数的回退值。 + 指定配置参数的后备值。 如果没有通过连接参数或PGAPPNAME环境变量为application_name指定值, - 则将使用此值。在通用实用程序中指定回退名称很有用,该程序希望设置默认应用程序名称, + 则将使用此值。在通用实用程序中指定后备名称很有用,该程序希望设置默认应用程序名称, 但允许用户覆盖它。 @@ -1132,9 +1113,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制是否使用客户端TCP保持活动。默认值为1,表示开启,但如果不想要保持活动,可以将其更改为0,表示关闭。 - 对于通过Unix域套接字进行的连接,此参数将被忽略。 - + 控制是否使用客户端 TCP keepalive。默认值为 1,表示开启;如果不需要 keepalive,可以将其设为 0,表示关闭。对于通过 Unix 域套接字建立的连接,此参数会被忽略。 + @@ -1143,11 +1123,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在多少秒的不活动后,TCP应向服务器发送保持活动消息。值为零使用系统默认值。 - 对通过Unix域套接字进行的连接或禁用保持活动的连接,此参数将被忽略。 - 仅在支持TCP_KEEPIDLE或等效套接字选项的系统以及Windows上支持; - 在其他系统上,它没有任何效果。 - + 控制在多久没有活动后,TCP 应向服务器发送 keepalive 消息,以秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPIDLE 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -1156,11 +1133,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在服务器未确认的情况下重新传输TCP保持活动消息的秒数。值为零时使用系统默认值。 - 此参数在通过Unix域套接字进行连接或禁用保持活动时将被忽略。 - 仅在支持TCP_KEEPINTVL或等效套接字选项的系统和Windows上支持; - 在其他系统上,此参数无效。 - + 控制未被服务器确认收到的 TCP keepalive 消息在多少秒后应被重传。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPINTVL 或等效套接字选项的系统以及 Windows 上受支持;在其他系统上无效。 + @@ -1169,11 +1143,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在客户端与服务器之间连接被视为断开之前可以丢失的TCP keepalive数量。 - 值为零时使用系统默认值。对通过Unix域套接字建立的连接或禁用keepalives的连接,此参数将被忽略。 - 仅在支持TCP_KEEPCNT或等效套接字选项的系统上受支持; - 在其他系统上,此参数无效。 - + 控制在客户端与服务器之间的连接被视为中断之前,可以丢失多少个 TCP keepalive 消息。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,或禁用 keepalive 时,此参数会被忽略。此参数仅在支持 TCP_KEEPCNT 或等效套接字选项的系统上受支持;在其他系统上无效。 + @@ -1182,10 +1153,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 控制在连接在强制关闭之前,传输数据可以保持未被确认的毫秒数。 - 值为零时使用系统默认值。此参数对通过Unix域套接字进行的连接无效。 - 仅在支持TCP_USER_TIMEOUT的系统上受支持;在其他系统上,它没有效果。 - + 控制已发送的数据在连接被强制关闭之前最多可以保持未确认状态多长时间,以毫秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接,此参数会被忽略。此参数仅在支持 TCP_USER_TIMEOUT 的系统上受支持;在其他系统上无效。 + @@ -1248,25 +1217,25 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个选项确定是否以及如何优先与服务器协商安全的GSS TCP/IP连接。有三种模式: + 这个选项确定是否以及以何种优先级与服务器协商安全的GSS TCP/IP连接。有三种模式: disable - 仅尝试非GSSAPI加密连接 + 仅尝试未经GSSAPI加密的连接 - prefer (默认) + prefer (默认) 如果存在GSSAPI凭据(即在凭据缓存中),首先尝试 GSSAPI加密连接;如果失败或没有凭据,则尝试 - 非GSSAPI加密连接。这是在编译PostgreSQL时使用GSSAPI支持时的默认设置。 + 未经GSSAPI加密的连接。这是在编译PostgreSQL时使用GSSAPI支持时的默认设置。 @@ -1285,7 +1254,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname gssencmode在Unix域套接字通信中被忽略。如果PostgreSQL没有编译GSSAPI支持, 使用require选项将导致错误,而prefer将被接受,但libpq实际上不会尝试 - 进行GSSAPI加密连接。GSSAPI与libpq + 进行GSSAPI加密连接。GSSAPI在 libpq 中 @@ -1317,7 +1286,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - prefer (默认) + prefer (默认) 首先尝试SSL连接;如果失败,则尝试非SSL连接 @@ -1357,22 +1326,18 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - sslmode被忽略用于Unix域套接字通信。 - 如果PostgreSQL没有SSL支持编译, + 在 Unix 域套接字通信中,sslmode 会被忽略。 + 如果PostgreSQL编译时未启用 SSL 支持, 使用选项requireverify-caverify-full会导致错误,而选项allowprefer 将被接受,但libpq实际上不会尝试建立SSL 连接。SSL使用libpq的SSL + sortas="libpq">在 libpq 中 - 请注意,如果可能使用GSSAPI加密, - 则优先使用该加密,而不考虑SSL的值。要在具有可用GSSAPI - 基础设施(如Kerberos服务器)的环境中强制使用 - SSL加密,还需将 - gssencmode设置为disable。 - + 注意,如果可以使用 GSSAPI 加密,就会优先使用它而不是 SSL 加密,无论 sslmode 的值是什么。在具有可用 GSSAPI 基础设施(例如 Kerberos 服务器)的环境中,要强制使用 SSL 加密,还应将 gssencmode 设为 disable。 + @@ -1381,15 +1346,15 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 此选项已被sslmode设置所取代。 - + 此选项已弃用,请改用 sslmode 设置。 + 如果设置为1,则需要与服务器建立SSL连接(这相当于sslmode require)。libpq将拒绝连接,如果服务器不接受 SSL连接。如果设置为0(默认值), libpq将与服务器协商连接类型(相当于sslmode - prefer)。此选项仅在PostgreSQL编译时启用SSL支持。 + prefer)。此选项仅在 PostgreSQL 编译时启用了 SSL 支持的情况下可用。 @@ -1439,7 +1404,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 如果安全性不是主要考虑因素,压缩可以提高吞吐量,如果网络是瓶颈的话。如果CPU性能是限制因素,禁用压缩可以提高响应时间和吞吐量。 + 如果安全性不是主要考虑因素,压缩可以提高吞吐量,如果网络是瓶颈的话。如果CPU性能是限制因素,禁用压缩可以缩短响应时间并提高吞吐量。 @@ -1463,7 +1428,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 这个参数指定了用于客户端证书的密钥的位置。它可以指定一个文件名,该文件名将被用来替代默认的 ~/.postgresql/postgresql.key,或者它可以指定一个从外部引擎 - (引擎是OpenSSL可加载模块)获取的密钥。外部引擎规范应该包括一个由冒号分隔的引擎名称和 + (引擎是OpenSSL可加载模块)获取的密钥。外部引擎的指定形式应包含一个由冒号分隔的引擎名称和 一个引擎特定的密钥标识符。如果没有进行SSL连接,则此参数将被忽略。 @@ -1492,10 +1457,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 指定此参数为任何非空值将抑制Enter PEM pass phrase: - 当提供加密的客户端证书密钥给libpq时, - OpenSSL默认会发出的提示。 - + 当向 libpq 提供加密的客户端证书密钥时,将此参数指定为任意非空值,都将抑制 OpenSSL 默认发出的 Enter PEM pass phrase: 提示。 + 如果密钥未加密,则忽略此参数。该参数对由OpenSSL引擎指定的密钥没有影响,除非引擎使用OpenSSL密码回调机制进行提示。 @@ -1577,10 +1540,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定SSL服务器证书吊销列表(CRL)的文件名。如果存在该文件中列出的证书,在尝试验证服务器证书时将被拒绝。 - 如果既没有设置也没有设置, - 则将采用~/.postgresql/root.crl。 - + 此参数指定 SSL 服务器证书吊销列表(CRL)的文件名。如果该文件存在,在验证服务器证书时,会拒绝其中列出的证书。如果既未设置,也未设置,则采用 ~/.postgresql/root.crl。 + @@ -1589,8 +1550,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定SSL服务器证书吊销列表(CRL)的目录名称。如果存在该目录中的文件中列出的证书,在尝试验证服务器证书时将被拒绝。 - + 此参数指定 SSL 服务器证书吊销列表(CRL)的目录名。如果该目录存在,在验证服务器证书时,会拒绝该目录下文件中列出的证书。 + 目录需要使用OpenSSL命令 @@ -1605,19 +1566,17 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - sslsniServer Name Indication + sslsni服务器名称指示 - 如果设置为1(默认值),libpq会在启用SSL的连接上设置TLS扩展Server Name IndicationSNI)。 + 如果设置为1(默认值),libpq会在启用SSL的连接上设置TLS扩展服务器名称指示SNI)。 通过将此参数设置为0,可以关闭此功能。 - 服务器名称指示可以被SSL感知代理使用,以便在不解密SSL流的情况下路由连接。 - (请注意,这需要一个了解PostgreSQL协议握手的代理,而不仅仅是任何SSL代理。) - 然而,SNI会使目标主机名以明文形式出现在网络流量中,因此在某些情况下可能不希望使用。 - + 支持 SSL 的代理可以利用服务器名称指示来路由连接,而无需解密 SSL 流。(注意,除非代理能够识别 PostgreSQL 协议握手,否则需要将 sslnegotiation 设为 direct。)不过,SNI 会使目标主机名以明文形式出现在网络流量中,因此在某些情况下可能不希望使用它。 + @@ -1642,8 +1601,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定连接允许的最低SSL/TLS协议版本。有效值为TLSv1, - TLSv1.1TLSv1.2和 + 这个参数指定连接允许的最低SSL/TLS协议版本。有效值为TLSv1、 + TLSv1.1TLSv1.2TLSv1.3。支持的协议取决于所使用的 OpenSSL版本,旧版本不支持最现代的协议版本。 如果未指定,默认值为TLSv1.2,符合本文撰写时的行业最佳实践。 @@ -1656,11 +1615,10 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 这个参数指定连接允许的最大SSL/TLS协议版本。有效值为TLSv1, - TLSv1.1TLSv1.2和 + 这个参数指定连接允许的最大SSL/TLS协议版本。有效值为TLSv1、 + TLSv1.1TLSv1.2TLSv1.3。支持的协议取决于使用的OpenSSL - 版本,旧版本不支持最新的协议版本。如果未设置,将忽略此参数,并且连接将使用后端定义的最大限制, - 如果设置。设置最大协议版本主要用于测试或者某些组件无法使用较新协议时。 + 版本,旧版本不支持最新的协议版本。如果未设置,则忽略此参数;如果后端定义了最大限制,连接将使用该限制。设置最大协议版本主要用于测试或者某些组件无法使用较新协议时。 @@ -1712,13 +1670,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - 用于使用GSSAPI进行认证时要使用的Kerberos服务名称。 + 使用 GSSAPI 认证时所用的 Kerberos 服务名。 这必须与服务器配置中指定的Kerberos认证服务名称匹配,才能成功进行认证。 (另请参见。) 默认值通常为postgres, - 但在构建PostgreSQL时可以通过 - 选项进行更改 - configure。 + 但在构建 PostgreSQL 时,可以通过 configure 选项更改。 在大多数环境中,通常不需要更改此参数。 一些Kerberos实现可能需要不同的服务名称, 例如Microsoft Active Directory需要服务名称为大写(POSTGRES)。 @@ -1742,7 +1698,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname gssdelegation - 将 GSS 凭证转发(委派)给服务器。默认值为0,表示不向服务器转发凭证。将其设置为1时,会在可能的情况下转发凭证。 + 将 GSS 凭据转发(委派)给服务器。默认值为0,表示不向服务器转发凭据。将其设置为1时,会在可能的情况下转发凭据。 @@ -1751,7 +1707,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname scram_client_key - 以 Base64 编码的 SCRAM 客户端密钥。外部数据包装器或类似中间件可以利用它启用透传式 SCRAM 认证。一个实现示例见。普通用户或客户端应用不应直接指定它。 + 以 Base64 编码的 SCRAM 客户端密钥。外部数据包装器或类似中间件可以利用它启用透传式 SCRAM 认证。一个实现示例见。用户或客户端应用不应直接指定它。 @@ -1760,7 +1716,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname scram_server_key - 以 Base64 编码的 SCRAM 服务器密钥。外部数据包装器或类似中间件可以利用它启用透传式 SCRAM 认证。一个实现示例见。普通用户或客户端应用不应直接指定它。 + 以 Base64 编码的 SCRAM 服务器密钥。外部数据包装器或类似中间件可以利用它启用透传式 SCRAM 认证。一个实现示例见。用户或客户端应用不应直接指定它。 @@ -1902,7 +1858,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname “混淆攻击(mix-up attacks)” - 你也可以显式把oauth_issuer设置为 OAuth 发现所使用的/.well-known/ URI。在这种情况下,如果服务器要求使用不同的 URL,连接就会失败;不过,自定义 OAuth 流程也许能够通过使用先前缓存的令牌来加速标准握手。(此时也建议设置,因为客户端将没有机会向服务器询问正确的 scope 设置,而令牌的默认 scope 可能不足以完成连接。)libpq当前支持以下 well-known 端点: + 你也可以显式把oauth_issuer设置为 OAuth 发现所使用的/.well-known/ URI。在这种情况下,如果服务器要求使用不同的 URL,连接就会失败;不过,自定义 OAuth 流程也许能够通过使用先前缓存的令牌来加速标准握手。(此时也建议设置,因为客户端将没有机会向服务器询问正确的授权范围设置,而令牌的默认授权范围可能不足以完成连接。)libpq当前支持以下 well-known 端点: /.well-known/openid-configuration /.well-known/oauth-authorization-server @@ -1929,8 +1885,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname oauth_client_secret - 与 OAuth 授权服务器通信时要使用的客户端密码(如果有)。该参数是否必需由 OAuth 提供者决定;“public” 客户端通常不使用 secret,而 “confidential” 客户端通常会使用。 - + 与 OAuth 授权服务器通信时要使用的客户端密码(如果有)。该参数是否必需由 OAuth 提供者决定;公开客户端(public client)通常不使用密钥,而机密客户端(confidential client)通常会使用。 + @@ -1938,13 +1894,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname oauth_scope - 发送给授权服务器的访问请求 scope,以 OAuth scope 标识符的空格分隔列表指定(该列表可以为空)。该参数是可选的,面向高级用法。 - + 发送给授权服务器的访问请求的授权范围,以空格分隔的 OAuth 授权范围标识符列表指定(列表可以为空)。该参数是可选的,面向高级用法。 + - 通常客户端会从PostgreSQL服务器获得合适的 scope 设置。如果使用这个参数,服务器请求的 scope 列表会被忽略。这可以防止不那么受信任的服务器向最终用户请求不恰当的访问 scope。不过,如果客户端的 scope 设置不包含服务器所要求的 scope,服务器很可能会拒绝已经签发的令牌,连接也会失败。 + 通常客户端会从PostgreSQL服务器获得合适的授权范围设置。如果使用这个参数,服务器请求的授权范围列表会被忽略。这可以防止不那么受信任的服务器向最终用户请求不恰当的访问授权范围。不过,如果客户端的授权范围设置不包含服务器所要求的授权范围,服务器很可能会拒绝已经签发的令牌,连接也会失败。 - 空 scope 列表的含义取决于提供者。OAuth 授权服务器可以选择签发带有“默认 scope”的令牌,不管那具体是什么;也可以完全拒绝该令牌请求。 + 空授权范围列表的含义取决于提供者。OAuth 授权服务器可以选择签发带有“默认授权范围”的令牌,不管那具体是什么;也可以完全拒绝该令牌请求。 @@ -1972,23 +1928,21 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 连接状态函数 - 这些函数可以被用来询问一个已有数据库连接对象的状态。 + 这些函数可用于查询现有数据库连接对象的状态。 - libpq-fe.h - libpq-int.h - libpq应用程序员应该小心地维护PGconn抽象。使用下面描述的访问函数来理解PGconn的内容。我们不推荐使用libpq-int.h引用内部的PGconn域,因为它们可能在未来改变。 - + libpq-fe.h + libpq-int.h + 编写 libpq 应用程序时,应注意维护 PGconn 的抽象。请使用下述访问函数获取 PGconn 的内容。不建议通过 libpq-int.h 引用 PGconn 的内部字段,因为这些字段将来可能改变。 + - 下列函数返回一个连接所建立的参数值。这些值在连接的生命期中是固定的。 - 如果使用的是多主机连接字符串,如果使用同一个PGconn对象建立新连接,,, 和 可能会改变。其他值在PGconn对象的一生中都是固定的。 - - + 以下函数返回建立连接时确定的参数值。这些值在连接存续期间保持不变。如果使用多主机连接字符串,并使用同一个 PGconn 对象建立新连接,则 的返回值可能改变。其他值在 PGconn 对象的整个生命周期内保持不变。 + PQdbPQdb @@ -2038,7 +1992,7 @@ char *PQpass(const PGconn *conn); - 返回活跃连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 + 返回活动连接的服务器主机名。可能是主机名、IP 地址或者一个目录路径(如果通过 Unix 套接字连接,路径的情况很容易区分,因为路径总是一个绝对路径,以/开始)。 char *PQhost(const PGconn *conn); @@ -2050,7 +2004,7 @@ char *PQhost(const PGconn *conn); - 如果conn参数是NULL,则返回NULL。否则,如果有一个错误产生主机信息(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成主机信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -2071,8 +2025,7 @@ char *PQhostaddr(const PGconn *conn); - 如果conn 参数为 NULL 返回 NULL 。 - 否则,如果生成主机信息时出现错误(如果连接尚未完全建立或出现错误),则返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成主机信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -2082,7 +2035,7 @@ char *PQhostaddr(const PGconn *conn); - 返回活跃连接的端口。 + 返回活动连接的端口。 char *PQport(const PGconn *conn); @@ -2094,7 +2047,7 @@ char *PQport(const PGconn *conn); - 如果conn参数是NULL,则返回NULL。否则,如果有一个错误产生端口信息(或许是连接没有被完全建立或者有什么错误),它会返回一个空字符串。 + 如果 conn 参数为 NULL,则 返回 NULL。否则,如果在生成端口信息时发生错误(例如连接尚未完全建立,或出现了错误),则返回空字符串。 @@ -2108,9 +2061,7 @@ char *PQport(const PGconn *conn); - 这个函数不再做任何事,但是它保持了向后兼容。 - 这个函数总是返回一个空字符串,或者NULL,如果connNULL。 - + 此函数已不再执行任何操作,但为保持向后兼容仍予以保留。如果 conn 参数为 NULL,则返回 NULL;否则始终返回空字符串。 char *PQtty(const PGconn *conn); @@ -2123,7 +2074,7 @@ char *PQtty(const PGconn *conn); - 返回被传递给连接请求的命令行选项。 + 返回连接请求中传递的命令行选项。 char *PQoptions(const PGconn *conn); @@ -2131,12 +2082,11 @@ char *PQoptions(const PGconn *conn); - + - 下列函数返回会随着在PGconn对象上执行的操作改变的状态数据。 - - + 以下函数返回的状态数据,可能随着对 PGconn 对象执行操作而改变。 + PQstatusPQstatus @@ -2149,9 +2099,9 @@ ConnStatusType PQstatus(const PGconn *conn); - 该状态可以是一系列值之一。不过,其中只有两个在一个异步连接过程之外可见:CONNECTION_OKCONNECTION_BAD。 - 一个到数据库的完好连接的状态为CONNECTION_OK。一个失败的连接尝试则由状态CONNECTION_BAD表示。 - 通常,一个 OK 状态将一直保持到,但是一次通信失败可能导致该状态过早地改变为CONNECTION_BAD。 + 该状态可以是一系列值之一。不过,其中只有两个在一个异步连接过程之外可见:CONNECTION_OKCONNECTION_BAD。 + 一个到数据库的完好连接的状态为CONNECTION_OK。一个失败的连接尝试则由状态CONNECTION_BAD表示。 + 通常,一个 OK 状态将一直保持到,但是一次通信失败可能导致该状态过早地改变为CONNECTION_BAD。 在那种情况下,该应用可以通过调用尝试恢复。 @@ -2172,7 +2122,7 @@ ConnStatusType PQstatus(const PGconn *conn); PGTransactionStatusType PQtransactionStatus(const PGconn *conn); - 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个合法的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接损坏,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE。 + 该状态可能是PQTRANS_IDLE(当前空闲)、PQTRANS_ACTIVE(一个命令运行中)、PQTRANS_INTRANS(空闲,处于一个有效的事务块中)或者PQTRANS_INERROR(空闲,处于一个失败的事务块中)。如果该连接异常,将会报告PQTRANS_UNKNOWN。只有当一个查询已经被发送给服务器并且还没有完成时,才会报告PQTRANS_ACTIVE。 @@ -2267,21 +2217,21 @@ int PQserverVersion(const PGconn *conn); - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 + 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。对于那些版本,为每个部分使用两位数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 + 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。在所有主版本系列中,各次版本(缺陷修复版本)之间只有最后两位数字不同。 - PQerrorMessagePQerrorMessage + PQerrorMessagePQerrorMessage错误消息PGconn - 错误消息返回连接上的一个操作最近产生的错误消息。 + 返回连接上的一个操作最近产生的错误消息。 char *PQerrorMessage(const PGconn *conn); @@ -2290,9 +2240,7 @@ char *PQerrorMessage(const PGconn *conn); - 几乎所有的libpq在失败时都会为设置一个消息。 - 注意按照libpq习惯,一个非空结果由多行构成,并且将包括一个尾部新行。 - 调用者不应该直接释放结果。当相关的PGconn句柄被传递给时,它将被释放。在PGconn结构体上的多个操作之间,不能指望结果字符串会保持不变。 + 几乎所有 libpq 函数在失败时都会设置一条供 返回的消息。注意,按照 libpq 的约定,非空的 结果可能包含多行,并以换行符结尾。调用者不应直接释放该结果;当关联的 PGconn 句柄被传给 时,结果会被释放。不能假定在对 PGconn 结构体执行其他操作后,结果字符串仍保持不变。 @@ -2301,7 +2249,7 @@ char *PQerrorMessage(const PGconn *conn); PQsocketPQsocket - 获得到服务器连接套接字的文件描述符号。一个合法的描述符将会大于等于零。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 + 获取与服务器相连的套接字的文件描述符编号。有效描述符大于或等于 0。结果为 -1 表示当前没有打开服务器连接(在普通操作期间这将不会改变,但是在连接设置或重置期间可能改变)。 int PQsocket(const PGconn *conn); @@ -2318,7 +2266,7 @@ int PQsocket(const PGconn *conn); 返回处理这个连接的后端进程的进程ID(PID)。 PID 确定服务器进程的 PID - in libpq + 在 libpq 中 @@ -2327,7 +2275,7 @@ int PQbackendPID(const PGconn *conn); - 后端PID有助于调试目的并且可用于与NOTIFY消息(它包括发出提示的后端进程的PID)进行比较。注意PID属于一个在数据库服务器主机上执行的进程,而不是本地主机进程! + 后端 PID 可用于调试,也可与 NOTIFY 消息进行比较(消息包含发出通知的后端进程的 PID)。注意,该 PID 属于在数据库服务器主机上运行的进程,而非本地主机上的进程! @@ -2382,19 +2330,18 @@ int PQconnectionUsedGSSAPI(const PGconn *conn); - + - 以下函数返回与SSL相关的信息。这些信息通常在建立连接后不会更改。 - - + 以下函数返回与 SSL 相关的信息。这些信息通常在连接建立后不会改变。 + PQsslInUsePQsslInUse - 返回true(1)如果连接使用SSL,返回false(0)如果不使用。 + 如果连接使用 SSL,则返回真(1);否则返回假(0)。 int PQsslInUse(const PGconn *conn); @@ -2410,7 +2357,7 @@ int PQsslInUse(const PGconn *conn); - 返回与连接相关的SSL信息。 + 返回连接的 SSL 相关信息。 const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); @@ -2422,7 +2369,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); - 常见的属性如下: + 通常可以获取以下属性: library @@ -2509,18 +2456,14 @@ const char * const * PQsslAttributeNames(const PGconn *conn); - 返回一个指向描述连接的SSL实现特定对象的指针。如果连接未加密或SSL实现不提供连接的请求对象类型,则返回NULL。 + 返回指向描述此连接的对象的指针,该对象的类型由 SSL 实现决定。如果连接未加密,或连接所用的 SSL 实现不提供所请求的对象类型,则返回 NULL。 void *PQsslStruct(const PGconn *conn, const char *struct_name); - 可用的结构体取决于正在使用的SSL实现。 - 对于OpenSSL,有一个结构体, - 可以通过名称OpenSSL获得, - 并返回一个指向OpenSSLSSL结构体的指针。 - 要使用这个函数,可以使用以下代码: + 可用的结构体取决于所使用的 SSL 实现。对于 OpenSSL,可以通过名称 OpenSSL 获取一个结构体,函数返回指向 OpenSSLSSL 结构体的指针。可以使用如下代码调用此函数: #include @@ -2571,7 +2514,7 @@ void *PQgetssl(const PGconn *conn); - + @@ -2580,7 +2523,7 @@ void *PQgetssl(const PGconn *conn); 命令执行函数 - 一旦到一个数据库服务器的连接被成功建立,这里描述的函数可以被用来执行 SQL 查询和命令。 + 与数据库服务器的连接成功建立后,此处描述的函数用于执行 SQL 查询和命令。 @@ -2602,11 +2545,8 @@ PGresult *PQexec(PGconn *conn, const char *command); - 返回一个PGresult指针或者可能是一个空指针。 - 除了内存不足的情况或者由于严重错误无法将命令发送给服务器之外,一般都会返回一个非空指针。 - 函数应当被调用来检查返回值是否代表错误(包括空指针的值,它会返回PGRES_FATAL_ERROR)。 - 用可得到关于那些错误的详细信息。 - + 返回一个 PGresult 指针,也可能返回空指针。除内存不足或无法向服务器发送命令等严重错误外,通常都会返回非空指针。应调用 函数检查返回值是否表示错误(也应检查空指针,此时该函数返回 PGRES_FATAL_ERROR)。使用 获取此类错误的更多信息。 + @@ -2687,8 +2627,8 @@ PGresult *PQexecParams(PGconn *conn, paramValues[] - 指定参数的实际值。这个数组中的一个空指针表示对应的参数为空,否则该指针指向一个以零终止的文本字符串(用于文本格式)或者以服务器所期待格式的二进制数据(用于二进制格式)。 - + 指定参数的实际值。数组中的空指针表示对应参数为 null;否则,指针指向以零结尾的文本字符串(文本格式),或采用服务器所要求格式的二进制数据(二进制格式)。 + @@ -2696,8 +2636,8 @@ PGresult *PQexecParams(PGconn *conn, paramLengths[] - 指定二进制格式参数的实际数据长度。它对空参数和文本格式参数被忽略。当没有二进制参数时,该数组指针可以为空。 - + 指定二进制格式参数的实际数据长度。对于 null 参数和文本格式参数,该值会被忽略。如果没有二进制参数,数组指针可以为空指针。 + @@ -2705,11 +2645,11 @@ PGresult *PQexecParams(PGconn *conn, paramFormats[] - 指定参数是否为文本(在参数相应的数组项中放一个零)或二进制(在参数相应的数组项中放一个一)。如果该数组指针为空,那么所有参数都会被假定为文本串。 - + 指定参数采用文本格式(在对应数组元素中填入零)还是二进制格式(填入一)。如果数组指针为空指针,则将所有参数视为文本字符串。 + - 以二进制格式传递的值要求后端所期待的内部表示形式的知识。例如,整数必须以网络字节序被传递。传递numeric值要求关于服务器存储格式的知识,正如src/backend/utils/adt/numeric.c::numeric_send()以及src/backend/utils/adt/numeric.c::numeric_recv()中所实现的。 - + 以二进制格式传递值时,需要了解后端所要求的内部表示形式。例如,整数必须以网络字节序传递。传递 numeric 值时,需要了解服务器的存储格式,其实现见 src/backend/utils/adt/numeric.c::numeric_send()src/backend/utils/adt/numeric.c::numeric_recv()。 + @@ -2717,8 +2657,8 @@ PGresult *PQexecParams(PGconn *conn, resultFormat - 指定零来得到文本格式的结果,或者指定一来得到二进制格式的结果(目前没有规定要求以不同格式得到不同的结果列,尽管在底层协议中这是可以实现的)。 - + 指定零以获取文本格式的结果,指定一以获取二进制格式的结果。(目前无法让不同结果列使用不同格式,尽管底层协议支持这样做。) + @@ -2729,8 +2669,8 @@ PGresult *PQexecParams(PGconn *conn, - 相对于的主要优点是参数值可以从命令串中分离,因此避免了冗长的书写、容易发生错误的引用以及转义。 - + 相对于 的主要优点是可以将参数值与命令字符串分开,从而避免繁琐且容易出错的加引号和转义工作。 + 不同,至多允许在给定串中出现一个 SQL 命令(其中可以有分号,但是不能有超过一个非空命令)。这是底层协议的一个限制,但是有助于抵抗 SQL 注入攻击。 @@ -2739,12 +2679,12 @@ PGresult *PQexecParams(PGconn *conn, - 通过 OID 指定参数类型很罗嗦,特别是如果你不愿意将特定的 OID 值硬编码到你的程序中时。不过,即使服务器本身也无法确定参数的类型,你可以避免这样做,或者选择一种与你想要的不同的类型。在 SQL 命令文本中,附加一个显式类型转换给参数符号来表示你将发送什么样的数据类型。例如: + 通过 OID 指定参数类型较为繁琐,尤其是在不希望将具体 OID 值写死在程序中时。不过,即使服务器无法自行确定参数类型,或者推断出的类型与你所需的不同,也可以避免直接指定 OID。在 SQL 命令文本中,为参数符号添加显式类型转换,即可指定要发送的数据类型。例如: SELECT * FROM mytable WHERE x = $1::bigint; - 这强制参数$1被当作bigint,而默认情况下它将被赋予与x相同的类型。当以二进制格式发送参数值时,我们强烈推荐以这种方式或通过指定一个数字类型的 OID 来强制参数类型决定。因为二进制格式比文本格式具有更少的冗余,并且因此服务器将不会有更多机会为你检测一个类型匹配错误。 - +这会强制将参数 $1 当作 bigint,而默认情况下会为它分配与 x 相同的类型。以二进制格式发送参数值时,强烈建议采用这种方式,或直接指定类型的数值 OID,来明确决定参数类型。因为二进制格式的冗余比文本格式更少,服务器发现类型不匹配错误的机会也更少。 + @@ -2765,15 +2705,15 @@ PGresult *PQprepare(PGconn *conn, - 创建一个后面会由执行的预备语句。 + 创建一个预备语句,供随后使用 执行。 这个特性允许命令被反复执行而无需每次都进行解析和规划,详见。 - + 该函数从query串创建一个名为stmtName的预备语句,该串必须包含一个单一 SQL 命令。 stmtName可以是""来创建一个未命名语句,在这种情况下任何已存在未命名语句将被自动替换。 否则,如果语句名称已经在当前会话中被定义,则是一种错误。如果使用了任何参数,它们在查询中以$1$2等引用。 - nParams是参数的个数,其类型在数组paramTypes[]中被预先指定(当nParams为零时,该数组指针可以是NULL)。 + nParams 是在数组 paramTypes[] 中预先指定了类型的参数数量(当nParams为零时,该数组指针可以是NULL)。 paramTypes[]通过 OID 指定要赋予给参数符号的数据类型。 如果paramTypesNULL或者该数组中任何特定元素为零,服务器会用对待未指定类型的字符串字面量的方式为参数符号推测一种数据类型。 还有,查询能够使用编号高于nParams的参数符号,它们的数据类型也会被自动推测(找出推测出的数据类型的方法见)。 @@ -2781,7 +2721,7 @@ PGresult *PQprepare(PGconn *conn, 正如一样,结果通常是一个PGresult对象,其内容代表服务器端成功或失败。 - 一个空结果表示内存不足或者根本无法发送命令。关于错误的更多信息请见。 + 返回空指针表示内存不足,或者根本无法发送命令。关于错误的更多信息请见 @@ -2813,9 +2753,9 @@ PGresult *PQexecPrepared(PGconn *conn, 类似于, - 但要执行的命令是通过指定先前准备好的语句来指定,而不是提供查询字符串。 - 此功能允许重复使用的命令只被解析和计划一次,而不是每次执行时都要进行。 - 该语句必须在当前会话中先前准备好。 + 但它通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。 + 此功能使重复使用的命令只需解析和规划一次,而不必在每次执行时都进行这些工作。 + 该语句必须事先在当前会话中创建为预备语句。 @@ -2832,23 +2772,23 @@ PGresult *PQexecPrepared(PGconn *conn, - 提交请求以获取有关指定准备好的语句的信息,并等待完成。 + 提交请求以获取有关指定预备语句的信息,并等待完成。 PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - 允许应用程序获取关于先前准备的语句的信息。 + 允许应用程序获取关于先前创建的预备语句的信息。 stmtName可以是""NULL来引用 - 未命名的语句,否则必须是现有准备好的语句的名称。成功时,返回一个 + 未命名的语句,否则必须是现有预备语句的名称。成功时,返回一个 状态为PGRES_COMMAND_OKPGresult。 函数可以应用于此 - PGresult以获取有关准备语句参数的信息, + PGresult以获取有关预备语句参数的信息, 函数等提供有关语句的结果列(如果有)的信息。 @@ -2862,22 +2802,21 @@ PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - 提交请求以获取有关指定门户的信息,并等待完成。 + 提交请求以获取有关指定 portal 的信息,并等待完成。 PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - 允许应用程序获取有关先前创建的portal的信息。 - (libpq不直接提供对portals的访问,但您可以使用此函数检查使用DECLARE CURSOR SQL命令创建的游标的属性。) - + 允许应用程序获取先前创建的 portal 的信息。(libpq 不提供对 portal 的直接访问,但可以用此函数检查通过 DECLARE CURSOR SQL 命令创建的游标的属性。) + - portalName可以是""NULL来引用未命名的portal, - 否则必须是现有portal的名称。成功时,将返回一个带有状态PGRES_COMMAND_OKPGresult。 + portalName可以是""NULL来引用未命名的 portal, + 否则必须是现有 portal 的名称。成功时,将返回一个带有状态PGRES_COMMAND_OKPGresult。 函数等可应用于 - PGresult,以获取有关portal的结果列(如果有)的信息。 + PGresult,以获取有关 portal 的结果列(如果有)的信息。 @@ -2894,11 +2833,11 @@ PGresult *PQclosePrepared(PGconn *conn, const char *stmtName); - 允许应用程序关闭先前准备好的预备语句。关闭语句会释放它在服务器上的全部相关资源,并允许重复使用其名称。 + 允许应用程序关闭先前创建的预备语句。关闭语句会释放它在服务器上的全部相关资源,并允许重复使用其名称。 - stmtName可以是""NULL来引用未命名语句。如果不存在该名称的语句也没有关系;在这种情况下,该操作不会执行任何操作。成功时,会返回一个状态为PGRES_COMMAND_OKPGresult。 + stmtName可以是""NULL来引用未命名语句。如果不存在该名称的语句也没有关系;在这种情况下,不执行任何操作。成功时,会返回一个状态为PGRES_COMMAND_OKPGresult @@ -2915,11 +2854,11 @@ PGresult *PQclosePortal(PGconn *conn, const char *portalName); - 允许应用程序关闭先前创建的 portal。关闭 portal 会释放它在服务器上的全部相关资源,并允许重复使用其名称。(libpq不直接提供对 portal 的访问,但你可以使用这个函数来关闭通过DECLARE CURSOR SQL 命令创建的游标。) + 允许应用程序关闭先前创建的 portal。关闭 portal 会释放它在服务器上的全部相关资源,并允许重复使用其名称。(libpq不直接提供对 portal 的访问,但你可以使用这个函数来关闭通过DECLARE CURSOR SQL 命令创建的游标。) - portalName可以是""NULL来引用未命名的 portal。如果不存在该名称的 portal 也没有关系;在这种情况下,该操作不会执行任何操作。成功时,会返回一个状态为PGRES_COMMAND_OKPGresult。 + portalName可以是""NULL来引用未命名的 portal。如果不存在该名称的 portal 也没有关系;在这种情况下,不执行任何操作。成功时,会返回一个状态为PGRES_COMMAND_OKPGresult @@ -2927,9 +2866,8 @@ PGresult *PQclosePortal(PGconn *conn, const char *portalName); - PGresultPGresult结构体封装了由服务器返回的结果。libpq应用程序员应该小心地维护PGresult的抽象。使用下面的存储器函数来得到PGresult的内容。避免直接引用PGresult结构体的域,因为它们可能在未来更改。 - - + PGresultPGresult 结构体封装服务器返回的结果。编写 libpq 应用程序时,应注意维护 PGresult 的抽象。请使用下述访问函数获取 PGresult 的内容。避免直接引用 PGresult 结构体的字段,因为这些字段将来可能改变。 + PQresultStatusPQresultStatus @@ -3030,7 +2968,7 @@ ExecStatusType PQresultStatus(const PGresult *res); PGRES_SINGLE_TUPLE - PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单一行模式时发生(见)。 + PGresult包含来自于当前命令的一个单一结果元组。这个状态只在查询选择了单行模式时发生(见)。 @@ -3078,12 +3016,11 @@ ExecStatusType PQresultStatus(const PGresult *res); - 将返回的枚举转换成描述状态编码的字符串常量。调用者不应该释放结果。 - + 将 返回的枚举值转换为描述该状态码的字符串常量。调用者不应释放此结果。 char *PQresStatus(ExecStatusType status); - + @@ -3092,12 +3029,12 @@ char *PQresStatus(ExecStatusType status); - 返回与该命令相关的错误消息,如果有错误则会返回一个空字符串。 + 返回与命令关联的错误消息;如果没有错误,则返回空字符串。 char *PQresultErrorMessage(const PGresult *res); - 如果有一个错误,被返回的字符串将包含一个收尾的新行。调用者不应该直接释放结果。它将在相关的PGresult句柄被传递给之后被释放。 - +如果发生了错误,返回的字符串会以换行符结尾。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 + 紧跟着一个调用,(在连接上)将返回与相同的字符串(在结果上)。 @@ -3113,16 +3050,14 @@ char *PQresultErrorMessage(const PGresult *res); - 返回与PGresult对象相关的错误消息的重新格式化的版本。 + 返回与 PGresult 对象关联的错误消息的重新格式化版本。 char *PQresultVerboseErrorMessage(const PGresult *res, PGVerbosity verbosity, PGContextVisibility show_context); - 在有些情况下,客户端可能希望得到之前报告过的错误的更加详尽的版本。 - 如果在产生给定PGresult的连接上 verbosity 设置有效,会通过计算已经被产生过的消息来满足这种需求。 - 如果PGresult不是一个错误结果,则会报告PG 结果不是错误结果。返回的字符串包括一个新行作为结尾。 - +有时客户端希望获取先前报告过的错误的更详细版本。 可满足这一需求:它按指定的详细程度设置重新生成消息。假如在生成给定 PGresult 时,连接已经采用这些设置,那么 返回的就会是这条消息。如果 PGresult 不是错误结果,则改为报告 PGresult is not an error result。返回的字符串以换行符结尾。 + 和大部分从PGresult中提取数据的其他函数不同,这个函数的结果是一个全新分配的字符串。调用者在不需要这个字符串以后,必须使用PQfreemem()释放它。 @@ -3138,24 +3073,21 @@ char *PQresultVerboseErrorMessage(const PGresult *res, PQresultErrorFieldPQresultErrorField - 返回一个错误报告的一个域。 + 返回错误报告中的单个字段。 char *PQresultErrorField(const PGresult *res, int fieldcode); - fieldcode是一个错误域标识符,见下列符号。 - 如果PGresult不是一个错误或者警告结果或者不包括指定域,会返回NULL。 - 域通常不包括一个收尾的新行。调用者不应该直接释放结果。 - 它将在相关的PGresult句柄被传递给之后被释放。 - +fieldcode 是错误字段标识符,参见下文列出的符号。如果 PGresult 不是错误或警告结果,或者不包含指定字段,则返回 NULL。字段值通常不含末尾换行符。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 + - 下列域代码可用: + 下列字段代码可用: PG_DIAG_SEVERITY - 严重性。域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。或者是其中之一的一个本地化翻译。总是存在。 @@ -3164,17 +3096,17 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_SEVERITY_NONLOCALIZED - 域的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY域相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 版本以后产生的报告中。 + 严重性。字段的内容是ERRORFATALPANIC(在一个错误消息中)。或者是WARNINGNOTICEDEBUGINFOLOG(在一个提示消息中)。这和PG_DIAG_SEVERITY字段相同,不过内容不会被本地化。只存在于PostgreSQL 9.6 及更高版本产生的报告中。 PG_DIAG_SQLSTATEerror codeslibpq + >错误码libpq - 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个域无法被本地化,并且总是存在。 + 用于错误的 SQLSTATE 代码。SQLSTATE 代码标识了已经发生的错误的类型,它可以被前端应用用来执行特定操作(例如错误处理)来响应一个特定数据库错误。一个可能的 SQLSTATE 代码列表可见。这个字段无法被本地化,并且总是存在。 @@ -3201,7 +3133,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_MESSAGE_HINT - 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是铁的事实。可能有多行。 + 提示:一个关于如何处理该问题的可选建议。它与细节的区别在于它提供了建议(可能不合适)而不是确切事实。可能有多行。 @@ -3219,7 +3151,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_INTERNAL_POSITION - 这被定义为与PG_DIAG_STATEMENT_POSITION域相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个域出现时,PG_DIAG_INTERNAL_QUERY域将总是出现。 + 这被定义为与PG_DIAG_STATEMENT_POSITION字段相同,但是它被用在游标位置引用一个内部产生的命令而不是客户端提交的命令时。当这个字段出现时,PG_DIAG_INTERNAL_QUERY字段将总是出现。 @@ -3237,7 +3169,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONTEXT - 指示错误发生的环境。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 + 指示错误发生的上下文。当前这包括活动过程语言函数的调用栈追踪以及内部生成的查询。追踪是每行一项,最近的排在最前面。 @@ -3255,7 +3187,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_TABLE_NAME - 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名域)。 + 如果错误与某个特定表相关,这里是该表的名字(该表的模式参考模式名字段)。 @@ -3264,7 +3196,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_COLUMN_NAME - 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名域来标识该表)。 + 如果错误与一个特定表列相关,这里是该表列的名字(参考模式和表名字段来标识该表)。 @@ -3273,7 +3205,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_DATATYPE_NAME - 如果错误与一个特定数据类型相关,这里是该数据了行的名字(该数据类型的模式名参考模式名域)。 + 如果错误与一个特定数据类型相关,这里是该数据类型的名字(该数据类型的模式名参考模式名字段)。 @@ -3282,7 +3214,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_CONSTRAINT_NAME - 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的域(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 + 如果错误与一个特定约束相关,这里是该约束的名字。相关的表或域参考上面列出的字段(为了这个目的,索引也被视作约束,即使它们不是用约束语法创建的)。 @@ -3318,16 +3250,16 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); - 用于模式名、表名、列名、数据类型名和约束名的域只提供给有限的错误类型,见。不要假定任何这些域的存在保证另一个域的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些域。同样地,不要假定这些域代表当前数据库中同类的对象。 + 用于模式名、表名、列名、数据类型名和约束名的字段只提供给有限的错误类型,见。不要假定任何这些字段的存在保证另一个字段的存在。核心错误源会遵守上面提到的内在联系,但是用户定义的函数可能以其他方式使用这些字段。同样地,不要假定这些字段代表当前数据库中现存的对象。 - 客户端负责格式化显示信息来迎合它的需要,特别是根据需要打断长的行。出现在错误消息域中的新行字符应该被当作分段而不是换行。 + 客户端负责按自身需要格式化所显示的信息,尤其应在需要时将长行折行。错误消息字段中的换行符应当视为段落分隔,而非行分隔。 - libpq内部产生的错误将有严重和主要消息,但是通常没有其他域。 + libpq内部产生的错误将包含严重性和主要消息,但是通常没有其他字段。 @@ -3340,14 +3272,12 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PQclearPQclear - 释放与一个PGresult关联的存储。每个命令结果在不再需要时都应通过释放。 - + 释放与 PGresult 关联的存储空间。每个命令结果在不再需要时都应通过 释放。 void PQclear(PGresult *res); - - 如果参数是NULL指针,则不会执行任何操作。 - +如果参数是 NULL 指针,则不执行任何操作。 + 你可以在需要时一直保留PGresult对象;它不会在你发出新命令时消失,甚至在关闭连接后也不会消失。要销毁它,你必须调用。否则应用程序会发生内存泄漏。 @@ -3355,7 +3285,7 @@ void PQclear(PGresult *res); - + @@ -3363,8 +3293,8 @@ void PQclear(PGresult *res); 检索查询结果信息 - 这些函数被用来从一个代表成功查询结果(也就是状态为PGRES_TUPLES_OK或者PGRES_SINGLE_TUPLE)的PGresult对象中抽取信息。它们也可以被用来从一个成功的 Describe 操作中抽取信息:一个 Describe 的结果具有和该查询被实际执行所提供的完全相同的列信息,但是它没有行。对于其他状态值的对象,这些函数会认为结果具有零行和零列。 - + 这些函数用于从表示成功查询结果的 PGresult 对象中提取信息,即状态为 PGRES_TUPLES_OKPGRES_SINGLE_TUPLEPGRES_TUPLES_CHUNK 的对象。它们也可用于提取成功 Describe 操作的结果信息:Describe 结果包含的列信息与实际执行查询时相同,但行数为零。对于其他状态值的对象,这些函数会将结果视为零行、零列。 + @@ -3391,7 +3321,7 @@ int PQntuples(const PGresult *res); - 返回查询结果中每一行的列(域)数。 + 返回查询结果中每一行的列(字段)数。 int PQnfields(const PGresult *res); @@ -3407,7 +3337,7 @@ int PQnfields(const PGresult *res); - 返回与给定列号相关联的列名。列号从 0 开始。调用者不应该直接释放该结果。它将在相关的PGresult句柄被传递给之后被释放。 + 返回给定列号对应的列名。列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 char *PQfname(const PGresult *res, int column_number); @@ -3439,11 +3369,11 @@ int PQfnumber(const PGresult *res, - 给定的名称被视作一个 SQL 命令中的一个标识符,也就是说,除非被双引号引用,它是小写形式的。例如,给定一个 SQL 命令: + 给定名称按 SQL 命令中的标识符处理,即除非用双引号引用,否则会转换为小写。例如,对于以下 SQL 命令生成的查询结果: SELECT 1 AS FOO, 2 AS "BAR"; - 我们将得到结果: +会得到以下结果: PQfname(res, 0) foo PQfname(res, 1) BAR @@ -3463,7 +3393,7 @@ PQfnumber(res, "\"BAR\"") 1 - 返回给定列从中取出的表的 OID。列号从 0 开始。 + 返回给定列所取自的表的 OID。列号从 0 开始。 Oid PQftable(const PGresult *res, int column_number); @@ -3476,7 +3406,7 @@ Oid PQftable(const PGresult *res, - 当你包括libpq头文件,类型oid以及常数InvalidOid将被定义。它们将都是某种整数类型。 + 包含 libpq 头文件后,将定义类型 Oid 和常量 InvalidOid。它们都属于某种整数类型。 @@ -3488,7 +3418,7 @@ Oid PQftable(const PGresult *res, - 返回构成指定查询结果列的列(在其表中)的列号。查询结果列号从 0 开始,但是表列具有非零编号。 + 返回指定查询结果列所对应的表列在表中的列号。查询结果的列号从 0 开始,而表列的编号非零。 int PQftablecol(const PGresult *res, int column_number); @@ -3508,7 +3438,7 @@ int PQftablecol(const PGresult *res, - 返回指示给定列格式的格式编码。列号从 0 开始。 + 返回表示给定列格式的格式代码。列号从 0 开始。 int PQfformat(const PGresult *res, int column_number); @@ -3516,7 +3446,7 @@ int PQfformat(const PGresult *res, - 格式代码零指示文本数据表示,而格式代码一表示二进制表示(其他代码被保留用于未来的定义)。 + 格式代码零表示文本数据,格式代码一表示二进制数据。(其他代码保留供将来定义。) @@ -3536,7 +3466,7 @@ Oid PQftype(const PGresult *res, - 你可以查询系统表pg_type来得到多个数据类型的名字和属性。 + 你可以查询系统表pg_type来获取各种数据类型的名称和属性。 内置数据类型的OID被定义在PostgreSQL安装的include目录中的catalog/pg_type_d.h文件中。 @@ -3549,7 +3479,7 @@ Oid PQftype(const PGresult *res, - 返回与给定列号相关联的列的修饰符类型。列号从 0 开始。 + 返回与给定列号相关联的列的类型修饰符。列号从 0 开始。 int PQfmod(const PGresult *res, int column_number); @@ -3557,7 +3487,7 @@ int PQfmod(const PGresult *res, - 修饰符值的解释是与类型相关的,它们通常指示精度或尺寸限制。值 -1 被用来指示没有信息可用。大部分的数据类型不适用修饰符,在那种情况中值总是 -1。 + 修饰符值的含义由数据类型决定,通常表示精度或大小限制。值 -1 表示没有可用信息。大多数数据类型不使用修饰符,此时该值始终为 -1。 @@ -3569,7 +3499,7 @@ int PQfmod(const PGresult *res, - 返回与给定列号相关的列的尺寸(以字节计)。列号从 0 开始。 + 返回给定列号对应列的大小,以字节计。列号从 0 开始。 int PQfsize(const PGresult *res, int column_number); @@ -3577,7 +3507,7 @@ int PQfsize(const PGresult *res, - 返回在一个数据库行中为这个列分配的空间,换句话说是服务器对该数据类型的内部表示的尺寸(因此,它对客户端并不是真地非常有用)。一个负值指示该数据类型是变长的。 + 返回数据库行中为该列分配的空间,即服务器内部表示该数据类型所需的大小。(因此,它对客户端用处不大。)负值表示该数据类型是变长类型。 @@ -3596,8 +3526,7 @@ int PQbinaryTuples(const PGresult *res); - 这个函数已经被废弃(除了与COPY一起使用),因为一个单一PGresult可以在某些列中包含文本数据而且在另一些列中包含二进制数据。 - 要更好。只有结果的所有列是二进制(格式 1)时才返回 1。 + 此函数已弃用(与 COPY 配合使用的情况除外),因为单个 PGresult 可能在部分列中包含文本数据,而在其他列中包含二进制数据。推荐使用 。只有结果中的所有列都采用二进制格式(格式 1)时, 才返回 1。 @@ -3609,8 +3538,7 @@ int PQbinaryTuples(const PGresult *res); - 返回一个PGresult的一行的单一域值。行和列号从 0 开始。调用者不应该直接释放该结果。 - 它将在相关的PGresult句柄被传递给之后被释放。 + 返回 PGresult 中某一行的单个字段值。行号和列号从 0 开始。调用者不应直接释放结果;当关联的 PGresult 句柄被传给 时,结果会被释放。 char *PQgetvalue(const PGresult *res, int row_number, @@ -3619,15 +3547,15 @@ char *PQgetvalue(const PGresult *res, - 对于文本格式的数据,返回的值是该域值的一种空值结束的字符串表示。对于二进制格式的数据,该值是由该数据类型的typsendtypreceive函数决定的二进制表示(在这种情况下该值实际上也跟随着一个零字节,但是这通常没有用处,因为该值很可能包含嵌入的空)。 + 对于文本格式的数据, 返回字段值的字符串表示,以零字节结尾。对于二进制格式的数据,返回值采用该数据类型的 typsendtypreceive 函数所决定的二进制表示。(这种情况下,值后面实际上也有一个零字节,但通常没有用处,因为值本身很可能包含零字节。) - 如果该域值为空,则返回一个空串。关于区分空值和空字符串值请见。 + 如果字段值为 null,则返回空字符串。关于如何区分 null 值与空字符串值,参见 - 返回的指针指向作为PGresult结构体一部分的存储。我们不应该修改它指向的数据,并且如果要在超过PGresult结构体本身的生命期之外使用它,我们必须显式地把该数据拷贝到其他存储中。 + 返回的指针指向属于 PGresult 结构体的存储空间。不应修改它所指向的数据;如果需要在 PGresult 结构体的生命周期结束后继续使用这些数据,就必须显式地将数据复制到其他存储空间。 @@ -3636,12 +3564,12 @@ char *PQgetvalue(const PGresult *res, PQgetisnullPQgetisnullnull valuein libpq + >null 值libpq 中的 - 测试一个域是否为空值。行号和列号从 0 开始。 + 检查字段是否为 null 值。行号和列号从 0 开始。 int PQgetisnull(const PGresult *res, int row_number, @@ -3650,7 +3578,7 @@ int PQgetisnull(const PGresult *res, - 如果该域是空,这个函数返回 1。如果它包含一个非空值,则返回 0(注意将为一个空域返回一个空串,不是一个空指针)。 + 如果字段为 null,此函数返回 1;如果包含非 null 值,则返回 0。(注意,对于 null 字段, 返回空字符串,而非空指针。) @@ -3662,7 +3590,7 @@ int PQgetisnull(const PGresult *res, - 返回一个域值的真实长度,以字节计。行号和列号从 0 开始。 + 返回字段值的实际长度,以字节计。行号和列号从 0 开始。 int PQgetlength(const PGresult *res, int row_number, @@ -3671,9 +3599,7 @@ int PQgetlength(const PGresult *res, - 这是特定数据值的真实数据长度,也就是指向的对象的尺寸。 - 对于文本数据格式,这和strlen()相同。对于二进制格式这是基本信息。 - 注意我们应该依赖于来得到真值的数据长度。 + 这是该数据值的实际数据长度,即 所指对象的大小。对于文本格式的数据,它与 strlen() 的结果相同。对于二进制格式,这是必不可少的信息。注意,不应依赖 来获取实际数据长度。 @@ -3692,7 +3618,7 @@ int PQnparams(const PGresult *res); - 只有在查看的结果时,这个函数才有用。对于其他类型的查询,它将返回零。 + 只有在查看的结果时,这个函数才有用。对于其他类型的结果,它将返回零。 @@ -3711,7 +3637,7 @@ Oid PQparamtype(const PGresult *res, int param_number); - 只有在查看的结果时,这个函数才有用。对于其他类型的查询,它将返回零。 + 只有在查看的结果时,这个函数才有用。对于其他类型的结果,它将返回零。 @@ -3723,29 +3649,29 @@ Oid PQparamtype(const PGresult *res, int param_number); - 将所有的行打印到指定的输出流,以及有选择地将列名打印到指定的输出流。 + 将所有行输出到指定的输出流,并可选择输出列名。 void PQprint(FILE *fout, /* 输出流 */ const PGresult *res, const PQprintOpt *po); typedef struct { - pqbool header; /* 打印输出域标题和行计数 */ - pqbool align; /* 填充对齐域 */ - pqbool standard; /* 旧的格式 */ + pqbool header; /* 打印输出字段标题和行数 */ + pqbool align; /* 填充并对齐字段 */ + pqbool standard; /* 旧的简陋格式 */ pqbool html3; /* 输出 HTML 表格 */ - pqbool expanded; /* 扩展表格 */ - pqbool pager; /* 如果必要为输出使用页 */ - char *fieldSep; /* 域分隔符 */ + pqbool expanded; /* 展开表格 */ + pqbool pager; /* 需要时使用分页器输出 */ + char *fieldSep; /* 字段分隔符 */ char *tableOpt; /* 用于 HTML 表格元素的属性 */ char *caption; /* HTML 表格标题 */ - char **fieldName; /* 替换域名称的空终止数组 */ + char **fieldName; /* 以空指针结尾的替换字段名数组 */ } PQprintOpt; - 这个函数以前被psql用来打印查询结果,但是现在不是这样了。注意它假定所有的数据都是文本格式。 + psql 以前用此函数打印查询结果,现在已不再使用。注意,此函数假定所有数据都是文本格式。 @@ -3794,13 +3720,7 @@ char *PQcmdTuples(PGresult *res); - 该函数返回一个字符串,其中包含由生成PGresultSQL语句影响的行数。 - 该函数只能在执行SELECTCREATE TABLE AS、 - INSERTUPDATEDELETE、 - MERGEMOVEFETCHCOPY语句, - 或包含INSERTUPDATEDELETEMERGE语句的预处理查询的EXECUTE之后使用。 - 如果生成PGresult的命令是其他任何命令,将返回一个空字符串。 - 调用者不应直接释放返回值。当关联的PGresult句柄传递给时,它将被释放。 + 此函数返回一个字符串,其中包含产生该 PGresultSQL 语句所影响的行数。此函数只能在执行 SELECTCREATE TABLE ASINSERTUPDATEDELETEMERGEMOVEFETCHCOPY 语句之后使用,也可以在对包含 INSERTUPDATEDELETEMERGE 语句的预备查询执行 EXECUTE 之后使用。如果产生 PGresult 的是其他命令, 将返回空字符串。调用者不应直接释放返回值;当关联的 PGresult 句柄被传给 时,返回值会被释放。 @@ -3812,7 +3732,7 @@ char *PQcmdTuples(PGresult *res); - 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDin libpq。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid。 + 如果该SQL命令是一个正好将一行插入到具有 OID 的表的INSERT,或者是一个包含合适INSERT语句的预备查询的EXECUTE,这个函数返回被插入行的 OIDOIDlibpq 中的。否则,这个函数返回InvalidOid。如果被INSERT语句影响的表不包含 OID,这个函数也将返回InvalidOid Oid PQoidValue(const PGresult *res); @@ -3827,7 +3747,7 @@ Oid PQoidValue(const PGresult *res); - 这个函数已经被取代,并且不是线程安全的。它返回包含被插入行的 OID 的一个字符串,而返回 OID 值。 + 此函数不是线程安全的,现已弃用,推荐改用 。它返回包含插入行 OID 的字符串,而 返回 OID 值。 char *PQoidStatus(const PGresult *res); @@ -3845,7 +3765,7 @@ char *PQoidStatus(const PGresult *res); 转义字符串 - in libpq + libpq 中的 @@ -3863,17 +3783,13 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); 为了让一个字符串可用于 SQL 命令,会对它进行转义。 - 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜线)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 + 当在 SQL 命令中把数据值作为字符串字面量插入时,这个函数很有用。一些字符(例如引号和反斜杠)必须经过转义,才不会被 SQL 解析器解释成特殊含义。 执行这种操作。 - 返回一个str参数的已被转义版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - 返回字符串中的所有特殊字符都会被替换,这样它们就能被PostgreSQL字符串字面量解析器正确处理。 - 结果中也会附加一个终止零字节,并包含包围PostgreSQL字符串字面量所需的单引号。 - + 返回 str 参数的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便 PostgreSQL 字符串字面量解析器正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号包含在结果字符串中。 + 发生错误时,返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -3887,7 +3803,7 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); - 注意,当一个数据值被作为或其兄弟例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 + 注意,当一个数据值被作为或相关例程中的一个独立参数传递时,没有必要做转义而且做转义也不正确。 @@ -3905,15 +3821,12 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - 转义一个要用作 SQL 标识符的字符串,例如表名、列名或函数名。当一个用户提供的标识符可能包含被 SQL 解析器解释为标识符一部分的特殊字符时,或者当该标识符可能包含大小写形式应该被保留的大写字符时,这个函数很有用。 - + 对字符串进行转义,使其可用作 SQL 标识符,例如表名、列名或函数名。当用户提供的标识符可能包含未经转义就不会被 SQL 解析器视为标识符一部分的特殊字符,或包含需要保留大小写的大写字符时,此函数很有用。 + - 返回一个str参数的已被转义为 SQL 标识符的版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - 返回串中的所有特殊字符都被替换掉,这样它们能被作为一个 SQL 标识符正确地处理。还会加上一个终止零字节。返回串也将被双引号包围。 - + 返回 str 参数作为 SQL 标识符的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,必须使用 PQfreemem() 释放该内存。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)返回字符串中的所有特殊字符均已替换,以便正确地作为 SQL 标识符处理。还会添加一个末尾零字节,并用双引号包围返回的字符串。 + 发生错误时,返回NULL并且一个合适的消息会被存储在conn对象中。 @@ -3922,7 +3835,7 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - 与字符串一样,要阻止 SQL 注入攻击,当从一个不可信的来源接收到 SQL 标识符时,它们必须被转义。 + 与字符串字面量一样,为防止 SQL 注入攻击,从不可信来源接收到的 SQL 标识符必须经过转义。 @@ -3943,18 +3856,12 @@ size_t PQescapeStringConn(PGconn *conn, - 转义字符串,它很像。 - 与不一样的是,调用者负责提供一个合适尺寸的缓冲区。 - 此外,不产生必须包围PostgreSQL字符串的单引号。 - 它们应该在结果要插入的 SQL 命令中提供。参数from指向要被转义的串的第一个字符,并且length参数给出了这个串中的字节数。 - 一个终止的零字节不是必须的,并且不应该被计入length(如果在length字节被处理之前找到一个终止字节,会停止在零,该行为更像strncpy)。 - to应当指向一个缓冲区,它能够保持至少比length值的两倍还要多至少一个字节,否则该行为是未被定义的。 - 如果tofrom串重叠,行为也是未被定义的。 - + 对字符串字面量进行转义,与 类似。与 不同,调用者需要提供大小合适的缓冲区。此外, 不会生成包围 PostgreSQL 字符串字面量所需的单引号;应在包含转义结果的 SQL 命令中提供这些引号。from 参数指向待转义字符串的首字符,length 参数给出该字符串的字节数。输入不必以零字节结尾,末尾零字节也不应计入 length。(如果在处理完 length 个字节之前遇到末尾零字节, 会在该字节处停止;这一行为类似于 strncpy。)to 必须指向一个缓冲区,其容量至少为 length 的两倍加一个字节,否则行为未定义。如果 tofrom 字符串重叠,行为同样未定义。 + - 如果error参数不是NULL,那么成功时*error被设置为零,错误时设置为非零。当前唯一可能的错误情况涉及源串中非法的多字节编码。错误时仍然会产生输出串,但是可以预期服务器将认为它是畸形的并且拒绝它。在发生错误时,一个合适的消息被存储在conn对象中,不管error是不是NULL。 - + 如果 error 参数不是 NULL,则成功时将 *error 设为零,出错时设为非零。目前唯一可能的错误是源字符串中存在无效的多字节编码。出错时仍会生成输出字符串,但预计服务器会因其格式错误而拒绝它。发生错误时,无论 error 是否为 NULL,都会在 conn 对象中保存相应消息。 + 返回写到to的字节数,不包括终止的零字节。 @@ -3969,21 +3876,19 @@ size_t PQescapeStringConn(PGconn *conn, - 是一个更老的被废弃的版本。 + 的旧版本,现已弃用。 size_t PQescapeString (char *to, const char *from, size_t length); - + - 之间的唯一区别是不需要PGconnerror参数。 - 正因为如此,它不能基于连接属性(例如字符编码)调整它的行为并且因此它可能给出错误的结果。还有,它没有方法报告错误情况。 - + 与 唯一的区别是, 不接受 PGconnerror 参数。因此,它无法根据连接属性(例如字符编码)调整行为,可能给出错误的结果。此外,它也无法报告错误情况。 + - 可以在一次只使用一个PostgreSQL连接的客户端程序中安全地使用(在这种情况下它可以在现象后面找出它需要知道的东西)。 - 在其他环境中它是一个安全性灾难并且应该用来避免。 - + 可以在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。在其他情形下,它存在安全隐患,应改用 。 + @@ -3994,7 +3899,7 @@ size_t PQescapeString (char *to, const char *from, size_t length); - 把要用于一个 SQL 命令的二进制数据用类型bytea转义。和一样,只有在将数据直接插入到一个 SQL 命令串时才使用它。 + 对二进制数据进行转义,使其能够在 SQL 命令中用作 bytea 类型的值。与 一样,这仅用于将数据直接插入 SQL 命令字符串的情况。 unsigned char *PQescapeByteaConn(PGconn *conn, const unsigned char *from, @@ -4009,14 +3914,11 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - from参数指向要被转义的串的第一个字节,并且from_length参数给出这个二进制串中的字节数(一个终止的零字节是不需要的也是不被计算的)。to_length参数指向一个将保持生成的已转义串长度的变量。这个结果串长度包括结果的终止零字节。 + from 参数指向待转义字符串的首字节,from_length 参数给出该二进制字符串的字节数。(末尾零字节既不需要,也不计入长度。)to_length 参数指向用于保存转义后字符串长度的变量。该结果字符串长度包含结果末尾的零字节。 - 返回一个from参数的已被转义为二进制串的版本,该版本被放在用malloc()分配的内存中。 - 当该结果不再被需要时,这个内存应该用PQfreemem()释放。 - 返回串中的所有特殊字符都被替换掉,这样它们能被PostgreSQL的字符串解析器以及bytea输入函数正确地处理。 - 还会加上一个终止零字节。不是结果串一部分的PostgreSQL字符串必须被单引号包围。 + 返回 from 参数所指二进制字符串的转义版本,存放在通过 malloc() 分配的内存中。结果不再需要时,应使用 PQfreemem() 释放该内存。返回字符串中的所有特殊字符都已替换,以便 PostgreSQL 字符串字面量解析器和 bytea 输入函数正确处理。还会添加一个末尾零字节。包围 PostgreSQL 字符串字面量所需的单引号不包含在结果字符串中。 @@ -4032,7 +3934,7 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - 是一个更老的被废弃的版本。 + 的旧版本,现已弃用。 unsigned char *PQescapeBytea(const unsigned char *from, size_t from_length, @@ -4041,9 +3943,7 @@ unsigned char *PQescapeBytea(const unsigned char *from, - 与的唯一区别是不用一个PGconn参数。 - 正因为这样,只能在一次只使用一个PostgreSQL连接的客户端程序中安全地使用(在这种情况下它可以在现象后面找出它需要知道的东西)。 - 如果在有多个数据库连接的程序中使用,它可能给出错误的结果(在那种情况下使用)。 + 与 唯一的区别是, 不接受 PGconn 参数。因此, 只能在同一时刻仅使用一个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它能够在内部取得所需信息)。如果在使用多个数据库连接的程序中使用,它可能给出错误的结果(此时应使用 )。 @@ -4115,25 +4015,15 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - 总是收集命令的整个结果,把它缓存在一个单一的PGresult中。虽然这简化了应用的错误处理逻辑,它对于包含很多行的结果并不现实。 - + 总是收集命令的完整结果,并将其缓存在单个 PGresult 中。这简化了应用程序的错误处理逻辑,但对于包含大量行的结果,可能不切实际。 + - 如果应用程序不希望受到这些限制,可以改用构成的底层函数:。此外,还有, - , - , - , - , - ,以及,它们可以与配合使用,分别实现以下函数的功能:, - , - , - , - , - ,以及。 - - + + 如果应用程序不希望受到这些限制,可以改用构成 的底层函数:。此外, 可以与 配合使用,分别实现 的功能。 + PQsendQueryPQsendQuery @@ -4141,14 +4031,11 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - 提交一个命令到服务器,而不等待结果。 - 如果成功发送命令,则返回1,如果失败则返回0(在这种情况下,使用获取更多关于失败的信息)。 + 向服务器提交命令,不等待结果。命令发送成功时返回 1,否则返回 0(此时可使用 获取更多失败信息)。 int PQsendQuery(PGconn *conn, const char *command); - - 成功调用后,调用一次或多次来获取结果。 - 在返回空指针,表示命令执行完成之前,无法再次调用(在同一连接上)。 +成功调用 后,应调用 一次或多次来获取结果。在 返回空指针、表明命令已完成之前,不得在同一连接上再次调用 @@ -4164,7 +4051,7 @@ int PQsendQuery(PGconn *conn, const char *command); - 提交一个命令和参数到服务器,而不等待结果。 + 向服务器提交命令及独立指定的参数,不等待结果。 int PQsendQueryParams(PGconn *conn, const char *command, @@ -4175,9 +4062,7 @@ int PQsendQueryParams(PGconn *conn, const int *paramFormats, int resultFormat); - - 这相当于,不同之处在于可以单独指定查询参数而不是与查询字符串一起指定。 - 函数的参数处理方式与完全相同。与一样,它在查询字符串中只允许一个命令。 +该函数等价于 ,但查询参数可以与查询字符串分开指定。函数参数的处理方式与 相同。与 一样,查询字符串中只允许包含一条命令。 @@ -4189,7 +4074,7 @@ int PQsendQueryParams(PGconn *conn, - 发送一个请求来创建一个带有给定参数的预备语句,而不等待完成。 + 发送按给定参数创建预备语句的请求,不等待完成。 int PQsendPrepare(PGconn *conn, const char *stmtName, @@ -4197,10 +4082,7 @@ int PQsendPrepare(PGconn *conn, int nParams, const Oid *paramTypes); - - 这是的异步版本:如果能够分派请求,则返回1,否则返回0。 - 成功调用后,调用来确定服务器是否成功创建了预备语句。 - 该函数的参数处理方式与完全相同。 +这是 的异步版本:请求发送成功时返回 1,否则返回 0。调用成功后,再调用 ,确定服务器是否成功创建了预备语句。函数参数的处理方式与 相同。 @@ -4212,7 +4094,7 @@ int PQsendPrepare(PGconn *conn, - 发送一个请求来执行一个准备好的语句,带有给定的参数,而不等待结果。 + 发送使用给定参数执行预备语句的请求,不等待结果。 int PQsendQueryPrepared(PGconn *conn, const char *stmtName, @@ -4222,9 +4104,7 @@ int PQsendQueryPrepared(PGconn *conn, const int *paramFormats, int resultFormat); - - 这类似于,但要执行的命令是通过指定一个之前准备好的语句的名称来指定,而不是提供一个查询字符串。 - 函数的参数处理方式与完全相同。 +该函数类似于 ,但通过已创建的预备语句的名称指定要执行的命令,而非提供查询字符串。函数参数的处理方式与 相同。 @@ -4256,7 +4136,7 @@ int PQsendDescribePrepared(PGconn *conn, const char *stmtName); - 提交请求以获取有关指定门户的信息,而无需等待完成。 + 提交请求以获取有关指定 portal 的信息,而无需等待完成。 int PQsendDescribePortal(PGconn *conn, const char *portalName); @@ -4322,13 +4202,7 @@ PGresult *PQgetResult(PGconn *conn); - 必须重复调用直到返回空指针,表示命令已完成。 - (如果在没有活动命令时调用, - 将立即返回空指针。)每个非空结果从 - 应该使用先前描述的相同PGresult访问器函数进行处理。 - 完成后不要忘记使用释放每个结果对象。请注意, - 仅在有命令处于活动状态且必要的响应数据尚未被 - 读取时才会阻塞。 + 必须反复调用 ,直到它返回空指针,表明命令已经完成。(如果当前没有正在执行的命令,调用 会立即返回空指针。)对于 返回的非空指针,应使用前文介绍的 PGresult 访问函数处理相应结果。使用完毕后,不要忘记调用 释放每个结果对象。注意,只有存在正在执行的命令,且所需响应数据尚未被 读取时, 才会阻塞。 @@ -4351,41 +4225,37 @@ PGresult *PQgetResult(PGconn *conn); - + - 使用解决了的一个问题:如果一个命令字符串包含多个SQL命令,这些命令的结果可以被个别地获得(顺便说一句:这样就允许一种简单的重叠处理形式, 客户端可以处理一个命令的结果,而同时服务器可以继续处理同一命令字符串中后面的查询)。 - + 使用 可以解决 的一个问题:如果命令字符串包含多个 SQL 命令,就能分别获取这些命令的结果。(这也支持一种简单的重叠处理方式:客户端可以处理某条命令的结果,同时服务器继续处理同一命令字符串中后面的查询。) + - 可以被获得的另一种常常想要的特性是一次从大型结果中检索一行。这会在中讨论。 - + 使用 还可以实现另一项常见需求:从大型查询结果中一次读取有限行数。详见 。 + - 就其本身而言,调用将仍会导致客户端阻塞,直到服务器完成下一个SQL命令。可以通过正确使用两个函数来避免这种情况: - - + 仅仅调用 仍会使客户端阻塞,直到服务器完成下一条 SQL 命令。可以通过正确使用另外两个函数来避免这种情况: + PQconsumeInputPQconsumeInput - 如果有来自服务器的输入可用,则使用之。 + 如果服务器有可读取的输入,则读取这些输入。 int PQconsumeInput(PGconn *conn); - 通常返回 1 表明没有错误,而返回 0 表明有某种麻烦发生(此时可以用)。 - 注意该结果并不表明是否真正收集了任何输入数据。在调用之后,应用可以检查和/或PQnotifies来看看它们的状态是否改变。 + 通常返回 1,表示没有错误;发生问题时则返回 0(此时可查看 )。注意,返回值并不说明是否实际读取了输入数据。调用 后,应用程序可以检查 和/或 PQnotifies,以确定其状态是否发生变化。 - 即使应用还不准备处理一个结果或通知,也可以被调用。 - 这个函数将读取可用的数 据并且把它保存在一个缓冲区中,从而导致一个select()的读准备好指示消失。 - 因此应用可以使用立即清除select()条件,并且在空闲时再检查结果。 + 即使应用程序尚未准备好处理结果或通知,也可以调用 。此函数会读取可用数据并将其保存在缓冲区中,从而清除 select() 的可读就绪指示。因此,应用程序可以用 立即清除 select() 的就绪条件,随后在合适的时候检查结果。 @@ -4407,15 +4277,11 @@ int PQisBusy(PGconn *conn); - + - 一个使用这些函数的典型应用将有一个主循环,在主循环中会使用select()poll()等待所有它必须响应的情况。 - 其中之一将是来自服务器的输入可用,对select()来说意味着标识的文件描述符上有可读的数据。 - 当主循环检测到输入准备好时,它将调用读取输入。 - 然后它可以调用,如果返回假(0)则接着调用。 - 它还可以调用PQnotifies检测NOTIFY消息(见)。 - + 使用这些函数的典型应用程序会在主循环中通过 select()poll() 等待需要响应的各种条件。其中一个条件是服务器有可读取的输入;对于 select(),这意味着 标识的文件描述符上有可读数据。主循环检测到输入就绪时,应调用 读取输入,然后调用 。如果 返回假(0),就可以接着调用 。还可以调用 PQnotifies 检测 NOTIFY 消息(见 )。 + 一个使用/的客户端也可以尝试取消一个正在被服务器处理的命令,见。 @@ -4423,13 +4289,8 @@ int PQisBusy(PGconn *conn); - 通过使用上面描述的函数,可以避免在等待来自数据库服务器的输入时阻塞。 - 然而,应用程序仍然可能会在等待向服务器发送输出时阻塞。 - 这在发送非常长的SQL命令或数据值时可能会发生,尽管这相对不常见。 - (如果应用程序通过COPY IN发送数据,则更有可能发生。) - 为了防止这种可能性并实现完全非阻塞的数据库操作,可以使用以下附加函数。 - - + 使用上述函数可以避免在等待数据库服务器输入时阻塞。不过,应用程序仍可能在等待向服务器发送输出时阻塞。这种情况较少见,但发送很长的 SQL 命令或数据值时可能发生。(如果应用程序通过 COPY IN 发送数据,发生的可能性则大得多。)为了防止这种情况,实现完全非阻塞的数据库操作,可以使用以下附加函数。 + PQsetnonblockingPQsetnonblocking @@ -4447,11 +4308,7 @@ int PQsetnonblocking(PGconn *conn, int arg); - 在非阻塞状态下,成功调用、 - 、 - 不会阻塞; - 它们的更改将存储在本地输出缓冲区中,直到刷新为止。 - 不成功的调用将返回错误,必须重试。 + 在非阻塞状态下,成功调用 不会阻塞;产生的数据保存在本地输出缓冲区中,等待发送。失败的调用会返回错误,必须重试。 @@ -4482,9 +4339,7 @@ int PQisnonblocking(const PGconn *conn); - 尝试将任何排队的输出数据刷新到服务器。如果成功(或发送队列为空),则返回0; - 如果由于某种原因失败,则返回-1;如果尚未能够发送发送队列中的所有数据(只有在连接为非阻塞时才会发生此情况), - 则返回1。 + 尝试将发送队列中的输出数据发送到服务器。成功(或发送队列为空)时返回 0;因某种原因失败时返回 -1;如果尚未能发送队列中的全部数据,则返回 1(这种情况只可能发生在非阻塞连接上)。 int PQflush(PGconn *conn); @@ -4492,15 +4347,11 @@ int PQflush(PGconn *conn); - + - 在一个非阻塞连接上发送任何命令或者数据之后,要调用。 - 如果它返回 1,就要等待套接字变成读准备好或写准备好。如果它变为写准备好,应再次调用。 - 如果它变为读准备好,则应先调用,然后再调用。 - 一直重复直到返回 0(有必要检查读准备好并且用耗尽输入,因为服务器可能阻塞给我们发送数据的尝试,例如 NOTICE 消息,并且在我们读它的数据之前它都不会读我们的数据)。 - 一旦返回 0,应等待套接字变成读准备好并且接着按照上文所述读取响应。 - + 在非阻塞连接上发送命令或数据后,应调用 。如果返回 1,就等待套接字变为可读或可写。套接字可写时,再次调用 ;可读时,先调用 ,再调用 。重复上述步骤,直到 返回 0。(必须检查套接字是否可读,并用 读完输入,因为服务器可能在尝试向客户端发送数据时阻塞,例如发送 NOTICE 消息;在客户端读取这些数据之前,服务器不会读取客户端发送的数据。)当 返回 0 后,等待套接字变为可读,再按前述方法读取响应。 + @@ -4514,29 +4365,26 @@ int PQflush(PGconn *conn); - pipelining - in libpq + 管道化 + 在 libpq 中 - batch mode - in libpq + 批处理模式 + 在 libpq 中 - libpq 管道模式允许应用发送查询而无需读取先前发送查询的结果。 - 利用管道模式的优点,客户端将对服务器等待的更少,因为可以在单个网络事务中发送/接收多个查询/结果。 - + libpq 的管道模式允许应用程序在尚未读取先前查询结果时继续发送查询。多个查询及其结果可以在一次网络交互中发送和接收,从而减少客户端等待服务器的时间。 + - 虽然管道模式提供了显著的性能提升, - 使用管道模式写客户端会更加复杂,因为它涉及到管理一个挂起查询的队列,并查找队列中的哪个结果对应于哪个查询。 - + 管道模式可以显著提升性能,但使用它编写客户端也更复杂,因为需要管理待处理查询队列,并确定每个结果对应队列中的哪个查询。 + - 管道模式通常也会在客户端和服务器上面消耗更多的内存,尽管仔细和积极地管理发送/接收队列可以减轻这种消耗。 - 这适用于连接是否处于阻塞或非阻塞模式。 - + 管道模式通常也会增加客户端和服务器的内存消耗,不过仔细、主动地管理发送和接收队列可以缓解这一问题。无论连接处于阻塞还是非阻塞模式,都是如此。 + 虽然libpq的管道API是在PostgreSQL 14中引入的, @@ -4549,23 +4397,8 @@ int PQflush(PGconn *conn); 使用管道模式 - 要发出管道命令,应用程序必须将连接切换到管道模式, - 可以通过来完成。 - 可以使用来测试管道模式是否激活。 - 在管道模式下,只允许使用扩展查询协议的异步操作, - 不允许包含多个SQL命令的命令字符串,也不允许使用COPY命令。 - 使用同步命令执行函数,如PQexec、 - PQexecParams、 - PQprepare、 - PQexecPrepared、 - PQdescribePrepared、 - PQdescribePortal, - 都会导致错误。 - 也不允许使用PQsendQuery,因为它使用简单查询协议。 - 一旦所有已分派的命令的结果已被处理,并且 - 结束管道结果已被消耗,应用程序可以通过返回 - 到非管道模式。 - + 要使用管道,应用程序必须通过 将连接切换到管道模式。可用 检查管道模式是否已启用。在管道模式下,只允许使用扩展查询协议的异步操作,不允许命令字符串包含多个 SQL 命令,也不允许 COPY。调用同步命令执行函数,例如 PQexecPQexecParamsPQpreparePQexecPreparedPQdescribePreparedPQdescribePortalPQclosePreparedPQclosePortal,会导致错误。也不允许使用 PQsendQuery,因为它使用简单查询协议。所有已发送命令的结果及管道结束结果都读取处理完毕后,应用程序便可通过 返回非管道模式。 + @@ -4574,9 +4407,8 @@ int PQflush(PGconn *conn); 如果在阻塞模式下使用,它可能发生客户端/服务器死锁。 - 客户端将阻止尝试发送查询到服务器,但服务器将阻止从它已经处理的查询向客户端发送结果。 - 这只有当客户端在它切换到处理从服务器的输入之前发送足够的查询来填充其输出缓冲区和服务器的接收缓冲区,才会发生这种情况,但很难准确预测何时将发生。 - + 客户端在尝试向服务器发送查询时阻塞,而服务器在尝试将已处理查询的结果发送给客户端时阻塞。只有当客户端在转而处理服务器输入之前,发送了足够多的查询,填满自身的输出缓冲区和服务器的接收缓冲区,才会发生这种情况;但很难准确预测何时会发生。 + @@ -4613,8 +4445,8 @@ int PQflush(PGconn *conn); - PQisBusyPQconsumeInput 等函数在处理管道结果时照常工作。特别地,在管道处理过程中调用 PQisBusy 时,如果到目前为止已发出查询的所有结果均已被消费,则返回 0。 - + PQisBusyPQconsumeInput 等函数在处理管道结果时照常工作。特别地,在管道处理过程中调用 PQisBusy 时,如果到目前为止已发出查询的所有结果均已被读取,则返回 0。 + libpq 不向应用程序提供当前正在处理哪个查询的信息(除了 PQgetResult 返回空指针,表示开始返回下一个查询的结果)。应用程序必须跟踪查询的发送顺序,以便将查询与对应结果关联起来。应用程序通常会使用状态机或 FIFO 队列实现这一点。 @@ -4627,21 +4459,16 @@ int PQflush(PGconn *conn); 错误处理 - 从客户端的视角,在PQresultStatus返回PGRES_FATAL_ERROR之后,管道被标记为中止。 - PQresultStatus将报告一个PGRES_PIPELINE_ABORTED结果,对中止的管道中的每一个剩余的排队操作。 - PQpipelineSync的结果报告为PGRES_PIPELINE_SYNC,以表示中止管道的结束并恢复正常的结果处理。 - + 从客户端的角度看,PQresultStatus 返回 PGRES_FATAL_ERROR 后,管道就会被标记为中止。对于已中止管道中剩余的每个排队操作,PQresultStatus 都会报告一个 PGRES_PIPELINE_ABORTED 结果。PQpipelineSyncPQsendPipelineSync 的结果报告为 PGRES_PIPELINE_SYNC,表示已中止的管道结束,并恢复正常的结果处理。 + 在错误恢复时,客户端必须 使用 PQgetResult处理结果。 - 如果管道使用隐式事务,那么已经执行的操作将被回滚,而排队跟在失败操作的操作将被完全跳过。 - 同样的行为也会发生,如果管道开始并提交单个显式事务(也就是,第一个语句是BEGIN ,最后一个是COMMIT),除非会话在管道结束时保持在中止事务状态。 - 如果管道包含多个显式事务,所有在错误发生前已提交的事务都会继续保留,当前正在进行的事务会被中止,所有后续操作都会被完全跳过,包括后续事务在内。 - 如果管道同步点发生时显式事务块为中止状态,则下一个管道将立即中止,除非下一个命令使用ROLLBACK将事务置于正常模式。 - + 如果管道使用隐式事务,已经执行的操作会被回滚,而失败操作之后排队的操作会全部跳过。如果管道开始并提交单个显式事务(即第一条语句为 BEGIN,最后一条为 COMMIT),行为也相同,不过在管道结束时,会话仍处于事务中止状态。如果管道包含多个显式事务,错误发生前已经提交的事务仍保持已提交状态,当前正在进行的事务会中止,所有后续操作都会被跳过,包括后续事务。如果到达管道同步点时,显式事务块仍处于中止状态,下一个管道会立即中止,除非下一条命令使用 ROLLBACK 将事务恢复为正常状态。 + @@ -4654,24 +4481,19 @@ int PQflush(PGconn *conn); - 交叉结果处理和查询分派 + 交错处理结果与发送查询 - 为避免大型管道上的死锁,客户端将被围绕非阻塞事件循环构建,通过使用操作系统工具,如select, poll, WaitForMultipleObjectEx等等, - + 为避免大型管道发生死锁,客户端应围绕非阻塞事件循环组织,使用 selectpollWaitForMultipleObjectEx 等操作系统机制。 + - 客户端应用通常应该维护一个尚未分派的工作队列和一个已分派但尚未处理结果的工作队列。 - 当套接字是可写时,它将可以分派更多的工作。 - 当套接字是可读时,它将读取结果并处理它们,将它们匹配到相应结果队列中的下一个条目。 - 基于可用内存,来自套接字的结果将被经常读取:这里不需要等到管道结束才读取结果。 - 管道将范围涵盖到工作的逻辑单元,通常(但不是必然)每个管道一个事务。 - 在管道之间,不需要退出管道模式再重新进入管道模式,也不需要等待一个管道结束后再发送下一个。 - + 客户端应用程序通常应维护两个队列:一个存放尚未发送的工作,另一个存放已经发送但尚未处理结果的工作。套接字可写时,应继续发送工作;套接字可读时,应读取并处理结果,将其与相应结果队列中的下一个条目匹配。应根据可用内存情况,频繁地从套接字读取结果,无需等到管道结束。每个管道应对应一个逻辑工作单元,通常是一个事务,但并非必须如此。管道之间无需退出再重新进入管道模式,也无需等待一个管道完成后才发送下一个。 + - 一个使用select()和一个简单状态机来跟踪发送和接收工作的示例,在PostgreSQL源代码发行版的src/test/modules/libpq_pipeline/libpq_pipeline.c文件中。 - + PostgreSQL 源代码发行版的 src/test/modules/libpq_pipeline/libpq_pipeline.c 中提供了一个示例,使用 select() 和简单状态机跟踪已发送和已接收的工作。 + @@ -4715,7 +4537,7 @@ PGpipelineStatus PQpipelineStatus(const PGconn *conn); - libpq 连接 是管道模式。 + libpq 连接处于管道模式。 @@ -4744,18 +4566,14 @@ PGpipelineStatus PQpipelineStatus(const PGconn *conn); - 造成连接进入管道模式,如果它当前空闲或已经是管道模式。 - + 如果连接当前空闲或已处于管道模式,则使该连接进入管道模式。 int PQenterPipelineMode(PGconn *conn); - - 成功返回1. - 如果连接当前不是空闲的,返回0并且无影响,也就是说,它已经有了一个结果,或者它正在等待服务器的更多输入,等等。 - 这个函数实际上不向服务器发送任何东西,它只是更改libpq连接状态。 + 成功时返回 1。如果连接当前不空闲,例如已有结果可供读取,或正在等待服务器的更多输入,则返回 0,且不产生任何影响。此函数实际上不向服务器发送任何内容,只改变 libpq 的连接状态。 @@ -4767,16 +4585,14 @@ int PQenterPipelineMode(PGconn *conn); - 造成连接退出管道模式,如果连接当前以空队列处于管道模式,并且没有待处理的结果。 + 如果连接当前处于管道模式、队列为空且没有待读取的结果,则使该连接退出管道模式。 int PQexitPipelineMode(PGconn *conn); - 成功则返回1。 - 如果不是管道模式,则返回1并且不采取操作。 - 如果当前语句没有完成处理,或者PQgetResult尚未被调用以收集所有先前发送查询的结果,则返回0(在这种情况下,使用以获取关于故障的更多信息)。 + 成功时返回 1。如果连接不处于管道模式,也返回 1,且不执行任何操作。如果当前语句尚未处理完毕,或尚未调用 PQgetResult 读取先前发送的所有查询的结果,则返回 0(此时可使用 获取更多失败信息)。 @@ -4788,17 +4604,14 @@ int PQexitPipelineMode(PGconn *conn); - 通过发送sync message并刷新发送缓冲区的方式来标记管道中的同步点。 - 它用作隐式事务的定界符和错误恢复点;参见。 - + 通过发送同步消息并将发送缓冲区中的数据发往服务器,在管道中标记同步点。同步点作为隐式事务的分界符和错误恢复点;见 int PQpipelineSync(PGconn *conn); - 成功就返回1。 - 如果连接不是管道模式或者发送sync message失败,则返回0。 + 成功时返回 1。如果连接不处于管道模式,或发送同步消息失败,则返回 0。 @@ -4808,14 +4621,13 @@ int PQpipelineSync(PGconn *conn); - 通过发送sync message但不刷新发送缓冲区,来标记管道中的一个同步点。它可作为隐式事务的分界符和错误恢复点;参见。 - + 通过发送同步消息在管道中标记同步点,但不刷新发送缓冲区。同步点作为隐式事务的分界符和错误恢复点;见 int PQsendPipelineSync(PGconn *conn); - 成功时返回 1。如果连接不处于管道模式,或者发送sync message失败,则返回 0。请注意,该消息本身不会自动刷新到服务器;必要时请使用PQflush。 + 成功时返回 1。如果连接不处于管道模式,或发送同步消息失败,则返回 0。注意,该消息本身不会自动发送到服务器;必要时可使用 PQflush @@ -4827,21 +4639,19 @@ int PQsendPipelineSync(PGconn *conn); - 发送一个请求到服务器以刷新它的输出缓冲区。 + 请求服务器发送其输出缓冲区中的数据。 int PQsendFlushRequest(PGconn *conn); - + - 成功就返回1。 - 任何失败则返回0。 - + 成功时返回 1;发生任何失败时返回 0。 + - 当PQpipelineSync被调用的结果,或者在非管道模式下的任何请求时,服务器自动刷新它的输出缓冲区;这个函数用于使得服务器在不建立同步点的情况下以管道模式刷新其输出缓冲区。 - 请注意,请求不是自身能自动刷新到服务器;如果需要时使用PQflush。 - + 调用 PQpipelineSync 后,或者在非管道模式下收到任何请求时,服务器都会自动发送其输出缓冲区中的数据。此函数可让服务器在管道模式下发送输出缓冲区中的数据,而不建立同步点。注意,该请求本身不会自动发送到服务器;必要时可使用 PQflush。 + @@ -4852,43 +4662,36 @@ int PQsendFlushRequest(PGconn *conn); 何时使用管道模式 - 非常像异步查询模式,在使用管道模式时没有明显的性能开销。 - 它增加了客户端应用的复杂性,并且需要特别注意以防止客户端/服务器死锁。 - 但是管道模式可以提供相当大的性能改进,代价是因为状态保留更久而增加内存使用。 - + 与异步查询模式类似,使用管道模式不会带来明显的性能开销。它增加了客户端应用程序的复杂性,需要格外注意防止客户端与服务器之间的死锁,但也能显著提升性能,代价是状态保留更久,因而占用更多内存。 + - 当服务器比较远,即网络延迟(ping time)高的时候,管道模式最有用,以及在许多小操作正在快速连续执行的时候。 - 当每个查询的执行时间是客户端/服务器往返时间的许多倍时,使用管道命令的优势通常会更少。 - 不用管道模式,在往返时间为300毫秒的服务器上运行一个100条语句的操作,仅网络延迟就需要30秒;使用管道,等待来自服务器的结果可能只消耗仅仅0.3秒。 - + 当服务器距离较远,即网络延迟(ping 时间)较高,或者需要快速连续执行许多小操作时,管道模式最有用。如果每个查询的执行时间是客户端与服务器往返时间的许多倍,使用管道命令的收益通常较小。在往返时间为 300 毫秒的服务器上执行一个包含 100 条语句的操作,不使用管道时,仅网络延迟就需要 30 秒;使用管道时,等待服务器结果的时间可能低至 0.3 秒。 + - 当你的应用需要完成很多小的INSERT, UPDATEDELETE 操作,并且不能方便的转换到集合操作或者 COPY操作时,用管道命令。 - + 如果应用程序需要执行大量小型 INSERTUPDATEDELETE 操作,而这些操作又难以转换为集合操作或 COPY 操作,就可以使用管道命令。 + - 当来自一个操作的信息需要客户端产生下一个操作时,管道模式是没有用的。 - 在这种情况下,客户机将不得不引入一个同步点,并等待完整的客户端/服务器往返以获取它需要的结果。 - 但是,通常可以调整客户端设计以交换服务器端所需的信息。 - 读-修改-写循环是非常好的选择;例如: + 如果客户端必须获得前一个操作的信息,才能生成下一个操作,管道模式就没有帮助。在这种情况下,客户端必须引入同步点,并等待一次完整的客户端与服务器往返,才能获得所需结果。不过,通常可以调整客户端设计,让所需信息在服务器端交换。读取、修改、写入的循环尤其适合这样改进。例如: BEGIN; SELECT x FROM mytable WHERE id = 42 FOR UPDATE; --- result: x=2 --- client adds 1 to x: +-- 结果:x=2 +-- 客户端将 x 加 1: UPDATE mytable SET x = 3 WHERE id = 42; COMMIT; - 可以更有效地开展以下工作: +可以改写为以下效率更高的操作: UPDATE mytable SET x = x + 1 WHERE id = 42; - + - 当单个管道包含多个事务时,管道的作用更小,而且更复杂(参见)。 - + 当单个管道包含多个事务时,使用管道的收益较小,复杂度也更高(见 )。 + @@ -4910,7 +4713,7 @@ UPDATE mytable SET x = x + 1 WHERE id = 42; - 要进入这些模式之一,请在成功调用(或其兄弟函数)后立即调用。这种模式选择只对当前正在执行的查询生效。然后按所述,反复调用直到其返回空指针。如果查询返回了任何行,这些行会作为一个或多个PGresult对象返回。它们看起来与普通查询结果相同,只是状态码在单行模式下为PGRES_SINGLE_TUPLE,在分块模式下为PGRES_TUPLES_CHUNK,而不是PGRES_TUPLES_OK。每个PGRES_SINGLE_TUPLE对象恰好包含一行结果,而PGRES_TUPLES_CHUNK对象至少包含一行、至多包含指定的每块行数。最后一行之后,或者如果查询返回零行,则会返回一个状态为PGRES_TUPLES_OK且不含行的对象,表示不会再有更多行到达。(但请注意,仍然必须继续调用直到其返回空指针。)所有这些PGresult对象都会包含与普通查询结果相同的行描述数据(列名、类型等)。每个对象在使用完之后都应像往常一样通过释放。 + 要进入这些模式之一,请在成功调用(或其同类函数)后立即调用。这种模式选择只对当前正在执行的查询生效。然后按所述,反复调用直到其返回空指针。如果查询返回了任何行,这些行会作为一个或多个PGresult对象返回。它们看起来与普通查询结果相同,只是状态码在单行模式下为PGRES_SINGLE_TUPLE,在分块模式下为PGRES_TUPLES_CHUNK,而不是PGRES_TUPLES_OK。每个PGRES_SINGLE_TUPLE对象恰好包含一行结果,而PGRES_TUPLES_CHUNK对象至少包含一行、至多包含指定的每块行数。最后一行之后,会返回一个状态为PGRES_TUPLES_OK且不含行的对象;如果查询返回零行,则立即返回该对象。这表示不会再有更多行到达。(但请注意,仍然必须继续调用直到其返回空指针。)所有这些PGresult对象都会包含与该查询的普通PGresult对象相同的行描述数据(列名、类型等)。每个对象在使用完之后都应像往常一样通过释放。 @@ -4932,7 +4735,7 @@ int PQsetSingleRowMode(PGconn *conn); - 此函数只能在调用或其某个兄弟函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活单行模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 + 此函数只能在调用或其某个同类函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活单行模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 @@ -4950,7 +4753,7 @@ int PQsetChunkedRowsMode(PGconn *conn, int chunkSize); - 该函数与类似,不同之处在于它指定每个PGresult最多返回chunkSize行,而不一定只返回一行。此函数也只能在调用或其某个兄弟函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活分块模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 + 该函数与类似,不同之处在于它指定每个PGresult最多返回chunkSize行,而不一定只返回一行。此函数也只能在调用或其某个同类函数之后立即调用,并且必须在该连接上执行任何其他操作之前调用,例如。如果调用时机正确,该函数会为当前查询激活分块模式并返回 1;否则模式保持不变并返回 0。无论如何,当前查询结束后都会恢复为普通模式。 @@ -4969,10 +4772,10 @@ int PQsetChunkedRowsMode(PGconn *conn, int chunkSize); 取消进行中的查询 - canceling SQL queries + 取消 SQL 查询 - query cancellation + 查询取消 @@ -4990,7 +4793,7 @@ PGcancelConn *PQcancelCreate(PGconn *conn); - 创建一个PGcancelConnPGcancelConn对象,但不会立即通过这条连接发送取消请求。可以使用以阻塞方式发送取消请求,或者使用以非阻塞方式发送。返回值可以传给,以检查该PGcancelConn对象是否成功创建。PGcancelConn是不透明结构体,不应由应用程序直接访问。它可用于以线程安全的方式取消原始连接上正在执行的查询。 + 创建一个PGcancelConnPGcancelConn对象,但不会立即通过这条连接发送取消请求。可以使用以阻塞方式发送取消请求,或者使用以非阻塞方式发送。返回值可以传给,以检查该PGcancelConn对象是否成功创建。PGcancelConn是不透明结构体,不应由应用程序直接访问。这个PGcancelConn对象可用于以线程安全的方式取消原始连接上正在执行的查询。 @@ -5043,7 +4846,7 @@ PostgresPollingStatusType PQcancelPoll(PGcancelConn *cancelConn); - 如果PQcancelStart成功,下一阶段就是轮询libpq,使其继续推进取消连接序列。使用获取底层套接字描述符。(注意:不要假定该套接字在多次调用PQcancelPoll之间保持不变。)循环规则如下:如果PQcancelPoll(cancelConn)上一次返回PGRES_POLLING_READING,就等待该套接字准备好可读(由select()poll()或类似系统函数指示),然后再次调用PQcancelPoll(cancelConn)。反之,如果其上一次返回PGRES_POLLING_WRITING,就等待套接字准备好可写,然后再次调用。第一次迭代时,也就是尚未调用过PQcancelPoll(cancelConn)时,按其上次返回PGRES_POLLING_WRITING来处理。持续这一循环,直到PQcancelPoll(cancelConn)返回PGRES_POLLING_FAILED,表示连接过程失败,或者返回PGRES_POLLING_OK,表示取消请求已成功分派。 + 如果PQcancelStart成功,下一阶段就是轮询libpq,使其继续进行取消连接的建立过程。使用获取数据库连接底层套接字的描述符。(注意:不要假定该套接字在多次调用PQcancelPoll之间保持不变。)循环规则如下:如果PQcancelPoll(cancelConn)上一次返回PGRES_POLLING_READING,就等待该套接字准备好可读(由select()poll()或类似系统函数指示),然后再次调用PQcancelPoll(cancelConn)。反之,如果PQcancelPoll(cancelConn)上一次返回PGRES_POLLING_WRITING,就等待套接字准备好可写,然后再次调用PQcancelPoll(cancelConn)。第一次迭代时,也就是尚未调用过PQcancelPoll(cancelConn)时,按其上次返回PGRES_POLLING_WRITING来处理。持续这一循环,直到PQcancelPoll(cancelConn)返回PGRES_POLLING_FAILED,表示连接过程失败,或者返回PGRES_POLLING_OK,表示取消请求已成功分派。 @@ -5109,7 +4912,7 @@ PostgresPollingStatusType PQcancelPoll(PGcancelConn *cancelConn); - 请注意,尽管这些常量会继续保留(为了保持兼容性),应用程序也绝不应依赖它们按某个特定顺序出现,甚至不应依赖它们一定会出现,或者依赖状态值始终属于这些已记录的取值之一。应用程序可以这样写: + 请注意,尽管这些常量会继续保留(为了保持兼容性),应用程序也绝不应依赖它们按某个特定顺序出现,甚至不应依赖它们一定会出现,或者依赖状态值始终属于本节列出的取值之一。应用程序可以这样写: switch(PQcancelStatus(conn)) { @@ -5180,7 +4983,7 @@ int PQcancelSocket(const PGcancelConn *cancelConn); PQcancelErrorMessagePQcancelErrorMessage - error messagein PGcancelConn + 错误消息PGcancelConn @@ -5239,8 +5042,8 @@ void PQcancelReset(PGcancelConn *cancelConn); 发送取消请求的过时函数 - 这些函数代表较旧的取消请求发送方式。虽然它们仍然可以工作,但由于即使原始连接通过sslmodegssencmode要求加密,它们发送取消请求时也不会以加密方式进行,因此已被废弃。因此,强烈不建议在新代码中继续使用这些旧方法,已有代码也建议迁移到新的函数。 - + 这些函数使用较旧的方式发送取消请求。即使原始连接通过 sslmodegssencmode 要求加密,它们也不会加密取消请求,因此虽然仍可使用,却已被弃用。强烈不建议在新代码中使用这些旧方法,也建议将现有代码改为使用新函数。 + @@ -5339,7 +5142,7 @@ int PQrequestCancel(PGconn *conn); NOTIFY - in libpq + 在 libpq 中 @@ -5348,39 +5151,36 @@ int PQrequestCancel(PGconn *conn); libpq应用把LISTENUNLISTENNOTIFY命令作为普通 SQL 命令提交。 - 随后通过调用PQnotifies.PQnotifies来检测NOTIFY消息的到达。 + 随后通过调用PQnotifiesPQnotifies来检测NOTIFY消息的到达。 - 函数PQnotifies从服务器发来的未处理通知消息列表中返回下一条通知。如果没有待处理通知,则返回空指针。一旦PQnotifies返回一条通知,该通知就被视为已处理,并会从通知列表中删除。 - + 函数 PQnotifies 从已收到但尚未处理的服务器通知消息列表中返回下一条通知。没有待处理通知时返回空指针。一旦 PQnotifies 返回一条通知,该通知就被视为已处理,并从通知列表中移除。 PGnotify *PQnotifies(PGconn *conn); typedef struct pgNotify { - char *relname; /* notification channel name */ - int be_pid; /* process ID of notifying server process */ - char *extra; /* notification payload string */ + char *relname; /* 通知通道名称 */ + int be_pid; /* 发送通知的服务器进程 ID */ + char *extra; /* 通知载荷字符串 */ } PGnotify; - - 在处理完PQnotifies返回的PGnotify对象后,别忘了用把它释放。 - 释放PGnotify指针本身就足够了;relnameextra域并不表示独立分配的内存(这些域名是历史遗留的,尤其是通道名称与关系名称并无关联)。 - +处理完 PQnotifies 返回的 PGnotify 对象后,务必使用 释放它。只需释放 PGnotify 指针;relnameextra 字段并非独立分配。(这些字段名称是历史遗留的;尤其是,通道名称与关系名称不必有任何关联。) + 给出了一个示例程序展示异步通知的使用。 - PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数吸收的消息。 + PQnotifies实际上并不从服务器读取数据;它只是返回之前已被其他libpq函数读取的消息。 在较早版本的libpq中,及时收到NOTIFY消息的唯一方法是不断提交命令,哪怕是空命令,然后在每次后检查PQnotifies。 - 虽然这种方法仍然有效,但由于效率过低,现已废弃。 + 虽然这种方法仍然有效,但由于浪费处理能力,现已弃用。 - 当你没有可用的命令提交时,一种更好的检查NOTIFY消息的方法是调用,然后检查PQnotifies。 + 当没有需要执行的实际命令时,一种更好的检查NOTIFY消息的方法是调用,然后检查PQnotifies。 你可以使用select()等待服务器数据到达,这样在无事可做时就不会浪费CPU资源(参见以获得可传给select()的文件描述符)。 注意不管是用/提交命令还是简单地使用,这种方法都能正常工作。 不过,你应该记住在每次之后检查PQnotifies,看看在命令的处理过程中是否有通知到达。 @@ -5394,20 +5194,16 @@ typedef struct pgNotify COPY - with libpq + 使用 libpq - PostgreSQL中的COPY命令有用于libpq的对网络连接读出或者写入的选项。这一节描述的函数允许应用通过提供或者消耗已拷贝的数据来充分利用这个功能。 - + PostgreSQLCOPY 命令提供了选项,可以通过 libpq 使用的网络连接读取或写入数据。本节介绍的函数允许应用程序通过提供或接收复制数据来使用这一能力。 + - 整个处理是应用首先通过或者一个等效的函数发出 SQL COPY命令。 - 对这个命令的响应(如果命令无误)将是一个状态代码是PGRES_COPY_OUT或 者PGRES_COPY_IN(取决于指定的拷贝方向)的PGresult对象。 - 应用然后就应该使用这一节的函数接收或者传送数据行。在数据传输结束之后,另外一个PGresult对象会被返回以表明传输的成功或者失败。 - 它的状态将是:PGRES_COMMAND_OK表示成功,PGRES_FATAL_ERROR表示发生了一些问题。 - 此时我们可以通过发出进一步的 SQL 命令(在COPY操作的处理过程中,不能用同一个连接执行其它 SQL 命令)。 - + 整体流程如下:应用程序先通过 或等效函数发出 SQL COPY 命令。如果命令没有错误,响应就是一个 PGresult 对象,其状态码为 PGRES_COPY_OUTPGRES_COPY_IN,取决于指定的复制方向。应用程序随后应使用本节函数接收或发送数据行。数据传输完成后,会返回另一个 PGresult 对象,表示传输成功或失败:成功时状态为 PGRES_COMMAND_OK,出现问题时为 PGRES_FATAL_ERROR。此时可以通过 继续发出 SQL 命令。(COPY 操作进行期间,不能在同一连接上执行其他 SQL 命令。) + 如果一个COPY命令是通过在一个可能包含额外命令的字符串中发出的,那么应用在完成COPY序列之后必须继续用取得结果。 @@ -5415,17 +5211,15 @@ typedef struct pgNotify - 这一节的函数应该只在从获得了PGRES_COPY_OUTPGRES_COPY_IN结果状态的后执行。 - + 只有从 获得 PGRES_COPY_OUTPGRES_COPY_IN 结果状态后,才应调用本节函数。 + - 一个PGresult对象具有这些状态值之一,携带有关COPY操作开始的一些附加数据。 - 可以使用与查询结果相关的函数来获取这些附加数据: - - + 带有上述某个状态值的 PGresult 对象,还会携带关于即将开始的 COPY 操作的附加数据。这些数据可以通过下列函数获取,这些函数也用于查询结果: + PQnfieldsPQnfieldswith COPY + >PQnfields用于 COPY @@ -5436,7 +5230,7 @@ typedef struct pgNotify PQbinaryTuplesPQbinaryTupleswith COPY + >PQbinaryTuples用于 COPY @@ -5448,7 +5242,7 @@ typedef struct pgNotify PQfformatPQfformatwith COPY + >PQfformat用于 COPY @@ -5460,15 +5254,15 @@ typedef struct pgNotify - + 用于发送<command>COPY</command>数据的函数 - 这些函数用于在COPY FROM STDIN期间发送数据。如果在连接不是COPY_IN状态,调用它们会失败。 - + 这些函数用于在 COPY FROM STDIN 期间发送数据。如果连接不处于 COPY_IN 状态,调用它们会失败。 + @@ -5487,12 +5281,11 @@ int PQputCopyData(PGconn *conn, - 传输指定buffer中长度为nbytesCOPY数据到服务器。 - 如果数据被放在队列中,结果是 1;如果因为缓冲区满而无法被放在队列中(只可能发生在连接是非阻塞模式时),那么结果是零;如果发生错误,结果为 -1(如果返回值为 -1,那么使用检索细节。如果值是零,那么等待写准备好然后重试)。 + 将指定 buffer 中长度为 nbytesCOPY 数据传输到服务器。数据成功加入队列时返回 1;因缓冲区已满而无法加入队列时返回零(仅可能发生在非阻塞模式下);发生错误时返回 -1。(返回 -1 时,可用 获取详细信息。返回零时,应等待可写就绪后重试。) - 应用可以把COPY数据流划分成任意方便的大小放到缓冲区中。在发送时,缓冲区载荷的边界没有什么语意。数据流的内容必须匹配COPY命令预期的数据格式;详见。 + 应用程序可以将 COPY 数据流分成任意方便大小的数据块,逐块装入缓冲区。发送时,这些数据块的边界没有语义含义。数据流内容必须符合 COPY 命令预期的数据格式;详见 @@ -5512,21 +5305,15 @@ int PQputCopyEnd(PGconn *conn, - 如果errormsgNULL,则成功结束COPY_IN操作。 - 如果errormsg不是NULLCOPY被强制失败,errormsg指向的字符串是错误消息。 - (不过,我们不应假定这个准确的错误信息将会从服务器传回,因为服务器可能已经因为其自身原因导致COPY失败。)。 + 如果 errormsgNULL,则成功结束 COPY_IN 操作。如果 errormsg 不为 NULL,则强制 COPY 失败,并将 errormsg 指向的字符串用作错误消息。(但不应假定服务器一定会返回这条完全相同的错误消息,因为服务器可能已经因自身原因使 COPY 失败。) - 如果终止消息被发送,则结果为 1;在非阻塞模式中,结果为 1 也可能只表示终止消息被成功地放在了发送队列中 - (在非阻塞模式中,要确认数据确实被发送出去,你应该接着等待写准备好并且调用,重复这些直到返回零)。 - 零表示该函数由于缓冲区满而无法将该终止消息放在队列中,这只会发生在非阻塞模式中(在这种情况下,等待写准备好并且再次尝试调用)。 - 如果发生系统错误,则返回 -1,可以使用检索详情。 + 终止消息已发送时返回 1;在非阻塞模式下,返回 1 也可能仅表示该消息已成功加入发送队列。(在非阻塞模式下,要确认数据已经发送,应接着等待可写就绪并调用 ,反复执行直到返回零。)返回零表示缓冲区已满,无法将终止消息加入队列;这种情况仅可能发生在非阻塞模式下。(此时,应等待可写就绪,再次调用 。)发生严重错误时返回 -1,可用 获取详细信息。 - 在成功调用之后,调用获取COPY命令的最终结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 成功调用 后,调用 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -5559,29 +5346,19 @@ int PQgetCopyData(PGconn *conn, - 在一个COPY期间尝试从服务器获取另外一行数据。数据总是以每次一个数据行的方式被返回;如果只有一个部分行可用,那么它不会被返回。 - 成功返回一个数据行涉及到分配一块内存来保存该数据。buffer参数必须为非NULL。 - *buffer被设置为指向分配到的内存的指针,或者是在没有返回缓冲区的情况下指向NULL。 - 一个非NULL的结果缓冲区在不需要时必须用释放。 + 在 COPY 期间尝试从服务器获取下一行数据。每次总是返回一个完整数据行;如果只有部分行可用,则不返回。成功返回数据行时,会分配一块内存保存数据。buffer 参数必须为非 NULL*buffer 会被设置为指向所分配的内存;如果没有返回缓冲区,则设为 NULL。非 NULL 的结果缓冲区在不再需要时应使用 释放。 - 在成功返回一行之后,返回的值就是该数据行里数据的字节数(将是大于零)。 - 被返回的字符串总是空终止的,虽然这可能只是对文本COPY有用。 - 一个零结果表示该COPY仍然在处理中,但是还没有可用的行(只在async为真时才可能)。 - 一个 -1 结果表示COPY已经完成。-2 结果表示发生了错误(参考获取原因)。 + 成功返回一行时,返回值是该行的数据字节数,始终大于零。返回的字符串总是以零字节结尾,不过这可能仅对文本 COPY 有用。返回零表示 COPY 仍在进行,但尚无可用行(仅在 async 为真时可能发生)。返回 -1 表示 COPY 已完成;返回 -2 表示发生了错误(可用 查看原因)。 - 当async为真时(非零),将不会阻塞等待输入; - 如果COPY仍在处理过程中并且没有可用的完整行,那么它将返回零 - (在这种情况下等待读准备好,然后在再次调用之前,调用)。 - 当async为假(零)时,将阻塞,直到数据可用或者操作完成。 + 当 async 为真(非零)时, 不会阻塞等待输入;如果 COPY 仍在进行,但没有完整行可用,则返回零。(此时,应等待读就绪,先调用 ,再调用 。)当 async 为假(零)时, 会阻塞,直到数据可用或操作完成。 - 在返回 -1 之后,调用获取COPY命令的最后结果状态。 - 我们可以用平常的方法来等待这个结果可用。然后返回到正常的操作。 + 在 返回 -1 后,调用 获取 COPY 命令的最终结果状态。可以按通常方式等待该结果就绪,然后恢复正常操作。 @@ -5591,11 +5368,11 @@ int PQgetCopyData(PGconn *conn, - 用于<command>COPY</command>的废弃函数 + 用于<command>COPY</command>的过时函数 - 这些函数代表了以前的处理COPY的方法。尽管它们还能用,但是现在已经被废弃,因为它们的错误处理很糟糕、检测结束数据的方法也不方便,并且缺少对二进制或非阻塞传输的支持。 - + 这些函数使用较旧的方式处理 COPY。虽然仍然可用,但由于错误处理欠佳、检测数据结束的方式不便,而且缺少对二进制或非阻塞传输的支持,已被弃用。 + @@ -5605,7 +5382,7 @@ int PQgetCopyData(PGconn *conn, - 读取一个以新行终止的字符行到(由服务器传输) 到一个长度为length的字符串缓冲区。 + 将服务器传来的、以换行符结尾的一行字符读入大小为 length 的字符串缓冲区。 int PQgetline(PGconn *conn, char *buffer, @@ -5614,12 +5391,11 @@ int PQgetline(PGconn *conn, - 这个函数拷贝最多length-1 个字符到该缓冲区中,并且把终止的新行转换成一个零字节。 - 在输入结束时返回EOF,如果整行都被读取则返回 0,如果缓冲区填满了而还没有遇到结束的新行则返回 1。 - + 此函数最多将 length-1 个字符复制到缓冲区,并将末尾的换行符转换为零字节。 在输入结束时返回 EOF,读完一整行时返回 0,缓冲区已满但尚未读到末尾换行符时返回 1。 + - 注意,应用必须检查是否一个新行包含两个字符\.,这表明服务器 已经完成了COPY命令的结果发送。如果应用可能收到超过length-1 字符长的行, 我们就应该确保正确识别\.行(例如,不要把一个长数据行的结束当作一个终止行)。 + 注意,应用程序必须检查新读入的一行是否仅由 \. 两个字符组成,这表示服务器已发送完 COPY 命令的结果。如果可能收到长度超过 length-1 个字符的行,必须确保正确识别 \. 行,例如不能把长数据行的末尾误当作终止行。 @@ -5631,7 +5407,7 @@ int PQgetline(PGconn *conn, - 不阻塞地读取一行COPY数据(由服务器传输)到一个缓冲区中。 + 以非阻塞方式将服务器传来的一行 COPY 数据读入缓冲区。 int PQgetlineAsync(PGconn *conn, char *buffer, @@ -5640,23 +5416,19 @@ int PQgetlineAsync(PGconn *conn, - 这个函数类似于,但是可以被用于那些必须异步读取COPY数据的应用, 也就是不阻塞的应用。 - 在发出了COPY命令并得到了PGRES_COPY_OUT响应之后, - 应用应该调用直到检测到结束数据的信号。 - + 此函数类似于 ,但可用于必须异步读取 COPY 数据的应用程序,即读取时不阻塞。发出 COPY 命令并收到 PGRES_COPY_OUT 响应后,应用程序应调用 ,直到检测到数据结束信号。 + - 不像,这个函数负责检测结束数据。 + 与 不同,此函数会负责检测数据结束。 - 在每次调用时,如果libpq的输入缓冲区中有一个完整的数据行可用,都将返回数据。 - 否则,在剩余行到达之前不会返回数据。如果识别到拷贝数据结束的标志,此函数返回 -1;如果没有可用数据则返回 0; - 或者是给出一个正数给出被返回的字节数。如果返回 -1,调用者下一步必须调用,然后回到正常处理。 + 每次调用时,如果 libpq 的输入缓冲区中有完整数据行, 就会返回数据;否则,要等该行剩余部分到达后才返回数据。识别到复制数据结束标记时返回 -1,没有可用数据时返回 0,否则返回正数,表示返回的数据字节数。返回 -1 后,调用者必须接着调用 ,然后恢复正常处理。 - 返回的数据将不超过一个数据行的范围。如果可能,每次将返回一个完整行。但如果调用者提供的缓冲区太小不足以容下服务器发送的行,那么将返回部分行。对于文本数据,这可以通过测试返回的最后一个字节是否\n来检测(在二进制COPY中, 需要对COPY数据格式进行实际的分析,以便做相同的判断)。被返回的字符串不是空结尾的(如果你想增加一个终止空,确保传递一个比实际可用空间少一字节的bufsize)。 + 返回的数据不会跨越数据行边界。只要可能,每次就返回一整行;但如果调用者提供的缓冲区太小,容不下服务器发送的一行,则只返回部分行。对于文本数据,可检查最后返回的字节是否为 \n,以判断是否返回了完整行。(对于二进制 COPY,则必须实际解析 COPY 数据格式才能作出相同判断。)返回的字符串不以零字节结尾。(如果要自行添加末尾的零字节,务必将传入的 bufsize 设置为比实际可用空间少一字节。) @@ -5668,7 +5440,7 @@ int PQgetlineAsync(PGconn *conn, - 向服务器发送一个空终止的字符串。如果 OK 则返回 0;如果不能发送字符串则返回EOF。 + 向服务器发送以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputline(PGconn *conn, const char *string); @@ -5676,17 +5448,14 @@ int PQputline(PGconn *conn, - 一系列调用发送的COPY数据流和返回的数据具有相同的格式, - 只是应用不需要每次调用中发送刚好一个数据行;在每次调用中发送多行或者部分行都是可以的。 + 连续调用 发送的 COPY 数据流,与 返回的数据格式相同。不过,应用程序不必在每次 调用中恰好发送一个数据行;每次发送部分行或多行也可以。 - 在PostgreSQL协议 3.0 之前,应用必须显式地发送两个字符\.作为最后一行来指示服务器已经完成发送COPY数据。 - 虽然这么做仍然有效,但是它已经被废弃并且\.的特殊含义可能在将来的版本中删除。 - 在发送完实际数据之后, 调用就足够了。 - + 在 PostgreSQL 协议 3.0 之前,应用程序必须显式发送由 \. 两个字符组成的最后一行,告知服务器应用程序已发送完 COPY 数据。虽然这种方式仍然有效,但已被弃用,\. 的特殊含义预计会在未来版本中移除。(在 CSV 模式下,这种做法已经会出现异常。)发送完实际数据后,调用 即可。 + @@ -5698,7 +5467,7 @@ int PQputline(PGconn *conn, - 向服务器发送一个非空终止的字符串。如果 OK 则返回 0,如果不能发送字符串则返回EOF。 + 向服务器发送不以零字节结尾的字符串。成功时返回 0,无法发送字符串时返回 EOF int PQputnbytes(PGconn *conn, const char *buffer, @@ -5707,7 +5476,7 @@ int PQputnbytes(PGconn *conn, - 这个函数类似,除了数据缓冲区不需要是空终止,因为要发送的字节数是直接指定的。在发送二进制数据时使用这个过程。 + 此函数与 完全相同,只是直接指定了要发送的字节数,因此数据缓冲区不必以零字节结尾。发送二进制数据时可使用此函数。 @@ -5723,15 +5492,11 @@ int PQputnbytes(PGconn *conn, int PQendcopy(PGconn *conn); - 这个函数等待服务器完成拷贝。当最后一个字符串已经用发送给服务器时或者当最后一个字符串已经用PQgetline从服务器接收到时,就会发出这个函数。 - 这个函数必须被发出,否则服务器将会和客户端不同步。从这个函数返回后,服务器就已经准备好接收下一个 SQL 命令了。函数成功完成时返回值为 0,否则返回非零值(如果返回值为非零值,用检索详情)。 +此函数会等待服务器完成复制。应在使用 向服务器发送最后一个字符串后,或使用 PQgetline 从服务器接收最后一个字符串后调用它。必须调用此函数,否则服务器与客户端会失去同步。函数返回后,服务器便准备好接收下一条 SQL 命令。成功完成时返回 0,否则返回非零值。(返回非零值时,可用 获取详细信息。) - 在使用时,应用应该通过反复调用并且在看到终止行后调用来响应PGRES_COPY_OUT结果。 - 然后它应该返回到循环直到返回一个空指针。 - 类似地,PGRES_COPY_IN结果会用一系列加上之后的来处理,然后返 回到循环。 - 这样的安排将保证嵌入到一系列SQL命令中的COPY命令将被正确执行。 + 使用 时,收到 PGRES_COPY_OUT 结果后,应用程序应反复调用 ,并在看到终止行后调用 。随后应回到 循环,直到 返回空指针。类似地,收到 PGRES_COPY_IN 结果后,应连续调用 ,再调用 ,然后回到 循环。这样可以保证嵌在一系列 SQL 命令中的 COPY 命令正确执行。 @@ -5751,8 +5516,8 @@ int PQendcopy(PGconn *conn); 控制函数 - 这些函数控制libpq行为各种各样的细节。 - + 这些函数控制 libpq 行为的各种细节。 + @@ -5762,17 +5527,15 @@ int PQendcopy(PGconn *conn); - 返回客户端编码。 + 返回客户端编码。 int PQclientEncoding(const PGconn *conn); - - 请注意,它返回的是编码 ID,而不是一个符号串字符串,如EUC_JP。如果不成功,它会返回 -1。要把一个编码 ID 转换为为一个编码名称,可以用: - +注意,返回的是编码 ID,而不是 EUC_JP 这样的符号字符串。失败时返回 -1。要将编码 ID 转换为编码名称,可以使用: char *pg_encoding_to_char(int encoding_id); - + @@ -5782,14 +5545,11 @@ char *pg_encoding_to_char(int encoding_id); - - 设置客户端编码。 - + 设置客户端编码。 int PQsetClientEncoding(PGconn *conn, const char *encoding); - conn是一个到服务器的连接,而encoding是你想使用的编码。 - 如果函数成功地设置编码,则返回 0,否则返回 -1。这个连接的当前编码可以使用确定。 + conn是到服务器的连接,而encoding是要使用的编码。如果成功设置编码,函数返回 0,否则返回 -1。此连接的当前编码可以通过以下函数确定: @@ -5801,7 +5561,7 @@ int PQsetClientEncoding(PGconn *conn, const char * - 决定返回的消息的细节程度。 + 设置 所返回消息的详细程度。 typedef enum { @@ -5813,19 +5573,12 @@ typedef enum PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); - - 设置细节模式,并返回该连接的前一个设置。 - 在TERSE模式下,返回的消息只包括严重性、主要文本以及位置;这些东西通常放在一个单一行中。 - DEFAULT模式生成的消息包括上面的信息加上任何细节、提示或者上下文域(这些可能跨越多行)。 - VERBOSE模式包括所有可以可用的域。修改细节模式不会影响来自已有PGresult对象中的可用消息。 - 只有随后创建的PGresult对象才受到影响。 - SQLSTATE模式仅包括错误严重性和SQLSTATE错误代码,如果其中之一是可用的(如果没有,输出类似于TERSE模式)。 - + 设置详细程度模式,并返回该连接先前的设置。在 TERSE 模式下,返回的消息只包含严重级别、主要文本和位置;通常一行就能容纳。DEFAULT 模式生成的消息除上述内容外,还包含所有详细信息、提示或上下文字段(这些内容可能跨越多行)。VERBOSE 模式包含所有可用字段。SQLSTATE 模式仅包含错误严重级别,以及可用时的 SQLSTATE 错误代码(如果没有错误代码,则输出与 TERSE 模式相同)。 + - 更改详细程度设置不会影响已存在的PGresult对象的可用的消息,只会影响随后创建的对象。 - (如果想要用不同的详细程度打印之前的错误,请见 ) - + 更改详细程度设置不会影响从既有 PGresult 对象中取得的消息,只影响随后创建的对象。(如果希望以不同的详细程度打印之前的错误,请参见 。) + @@ -5836,7 +5589,7 @@ PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); - 决定如何处理返回的消息中的CONTEXT域。 + 确定 所返回消息中 CONTEXT 字段的处理方式。 typedef enum { @@ -5847,18 +5600,12 @@ typedef enum PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibility show_context); - - 设置上下文显示模式,返回该连接上之前的设置。 - 这个模式控制消息中是否包括CONTEXT域。 - NEVER模式不会包括CONTEXT,而ALWAYS则尽可能地包括这个域。 - 在ERRORS模式(默认)中,只在错误消息中包括CONTEXT域,而在通知和警告消息中不会包括。 - (但是,如果详细程度设置为 TERSESQLSTATE,则无论上下文显示模式如何,都会省略CONTEXT字段。) - + 设置上下文显示模式,并返回连接先前的设置。此模式控制消息中是否包含 CONTEXT 字段。NEVER 模式从不包含 CONTEXT,而 ALWAYS 模式在该字段可用时总是包含它。在 ERRORS 模式(默认)下,CONTEXT 字段只包含在错误消息中,不包含在通知和警告中。(不过,如果详细程度设置为 TERSESQLSTATE,则无论上下文显示模式如何,都会省略 CONTEXT 字段。) + - 更改这个模式不会影响从已经存在的PGresult对象项中得到的消息,只会影响后续创建的PGresult对象 - (如果想要用不同的详细程度打印之前的错误,请见)。 - + 更改此模式不会影响从既有 PGresult 对象中取得的消息,只影响随后创建的对象。(如果希望使用不同的显示模式打印之前的错误,请参见 。) + @@ -5869,25 +5616,20 @@ PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibilit - 启用对客户端/服务器通讯的跟踪,把跟踪信息输出到一个调试文件流中。 + 启用客户端/服务器通信跟踪,将跟踪信息写入调试文件流。 void PQtrace(PGconn *conn, FILE *stream); - + - 每行包括:一个可选的时间戳,一个方向指示器(F表示从客户端到服务器的消息或B表示从服务器到客户端的消息),消息长度、消息类型、和消息内容。 - 非消息内容字段(时间戳、方向、长度和消息类型)由一个制表符分隔。 - 消息内容用空格分隔。 - 协议字符串用双引号括起来,而用作数据值的字符串用单引号括起来。 - 不可打印的字符被打印为十六进制转义。 - 更多消息-类型-特定的详情可以在中发现。 - + 每行包含可选的时间戳、方向指示符(F 表示客户端发往服务器的消息,B 表示服务器发往客户端的消息)、消息长度、消息类型和消息内容。消息内容之外的字段(时间戳、方向、长度和消息类型)以制表符分隔。消息内容以空格分隔。协议字符串用双引号括起,用作数据值的字符串用单引号括起。不可打印字符以十六进制转义形式输出。各消息类型的进一步说明见 。 + - 在 Windows上,如果libpq库和应用使用了不同的标志编译,那么这个函数调用会导致应用崩溃,因为FILE指针的内部表达是不一样的。特别是多线程/单线程、发布/调试 以及静态/动态标志应该是库和所有使用库的应用都一致。 + 在 Windows 上,如果 libpq 库与应用程序使用不同的标志编译,调用此函数会导致应用程序崩溃,因为 FILE 指针的内部表示不同。具体而言,库与所有使用它的应用程序都应使用相同的多线程/单线程、发布/调试和静态/动态标志。 @@ -5908,11 +5650,8 @@ void PQsetTraceFlags(PGconn *conn, int flags); - flags包含描述跟踪的操作模式的标志位。 - 如果flags包含PQTRACE_SUPPRESS_TIMESTAMPS,则在打印每条消息时不包括时间戳。 - 如果flags包含PQTRACE_REGRESS_MODE,那么在打印每个消息时将修改一些字段,例如对象OIDs,以使输出在测试框架中更方便地使用。 - 这个函数必须在调用PQtrace之后调用。 - + flags 包含描述跟踪工作模式的标志位。如果 flags 包含 PQTRACE_SUPPRESS_TIMESTAMPS,则打印每条消息时不包含时间戳。如果 flags 包含 PQTRACE_REGRESS_MODE,则打印每条消息时会隐去某些字段,例如对象 OID,以便在测试框架中使用输出。必须在调用 PQtrace 之后调用此函数。 + @@ -5924,11 +5663,11 @@ void PQsetTraceFlags(PGconn *conn, int flags); - 禁用打开的跟踪。 + 禁用由 启动的跟踪。 void PQuntrace(PGconn *conn); - + @@ -5958,11 +5697,8 @@ void PQfreemem(void *ptr); - 释放libpq分配的内存,尤其是,,,和PQnotifies分配的内存。 - 特别重要的是,在微软 Windows 上使用这个函数,而不是free()。 - 这是因为只有 DLL 和应用的当多线程/单线程、发布/调试以及静态/动态标志相同时,才能在一个 DLL 中分配内存并且在应用中释放它。 - 在非微软 Windows 平台上,这个函数与标准库函数free()相同。 - + 释放 libpq 分配的内存,特别是 PQnotifies 分配的内存。在 Microsoft Windows 上,务必使用此函数,而不是 free()。这是因为只有 DLL 与应用程序使用相同的多线程/单线程、发布/调试和静态/动态标志,才能在 DLL 中分配内存并在应用程序中释放它。在 Microsoft Windows 以外的平台上,此函数与标准库函数 free() 相同。 + @@ -5973,15 +5709,16 @@ void PQfreemem(void *ptr); - 释放分配的数据结构。 + 释放 分配的数据结构。 void PQconninfoFree(PQconninfoOption *connOptions); - +如果参数为 NULL 指针,则不执行任何操作。 + - 一个简单的不会做这些,因为数组包含对子字符串的引用。 - + 仅调用 不足以完成此项释放,因为数组还包含指向附属字符串的引用。 + @@ -6005,8 +5742,8 @@ char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, 当前支持的算法是md5scram-sha-256onoff也被接受作为md5的别名,用于与较老的服务器版本兼容)。 注意,对scram-sha-256支持是在PostgreSQL版本10中引入的,并且在老的服务器版本上无法工作。 如果algorithmNULL,这个函数将向服务器查询设置的当前值。 - 这种行为可能会阻塞当前事务,并且当前事务被中止或者连接正忙于执行另一个查询时会失败。 - 如果希望为服务器使用默认的算法但避免阻塞,应在调用之前查询你自己的password_encryption,并且将该值作为algorithm传入。 + 这一查询可能阻塞,并且当前事务被中止或者连接正忙于执行另一个查询时会失败。 + 如果希望为服务器使用默认的算法但避免阻塞,应在调用之前自行查询password_encryption,并且将该值作为algorithm传入。 @@ -6072,8 +5809,8 @@ PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); 这是libpq内部用于分配并初始化一个空PGresult对象的函数。 如果无法分配内存,此函数返回NULL。 将它导出供外部调用,是因为一些应用需要自行生成结果对象,特别是带有错误状态的对象。 - 如果conn非空,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 - 此外,如果conn非空,连接中注册的所有事件过程也会被复制到PGresult中。 + 如果conn 不为 null,并且status表示错误,指定连接的当前错误消息会被复制到PGresult中。 + 此外,如果conn 不为 null,连接中注册的所有事件过程也会被复制到PGresult中。 (这些过程不会收到PGEVT_RESULTCREATE调用,但可参见。) 注意,最终应对该对象调用,就像处理libpq自身返回的PGresult一样。 @@ -6094,16 +5831,16 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); - conn参数被传送给事件过程,但不会被直接使用。如果事件过程不使用它,则会返回NULL。 - + conn 参数会传递给事件过程,但此函数不会直接使用它。如果事件过程不使用此参数,则可以传入 NULL。 + 已经接收到这个对象的PGEVT_RESULTCREATEPGEVT_RESULTCOPY事件的事件过程不会被再次触发。 - 这个函数与分开的主要原因是在调用事件过程之前创建一个PGresult并且填充它常常是合适的。 - + 此函数与 分开的主要原因是,通常适合先创建 PGresult 并填充数据,然后再调用事件过程。 + @@ -6114,13 +5851,11 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); - 为一个PGresult对象创建一个拷贝。 - 这个拷贝不会以任何方式链接到源结果,并且当该拷贝不再需要时,必须调用进行清理。如果函数失败,返回NULL。 - + 创建 PGresult 对象的副本。副本与源结果没有任何关联,不再需要副本时必须调用 。函数失败时返回 NULL PGresult *PQcopyResult(const PGresult *src, int flags); - + 这不是为了制作一个精确的副本。返回的结果总是放在PGRES_TUPLES_OK状态中,并且不复制源中的任何错误消息。 @@ -6129,7 +5864,7 @@ PGresult *PQcopyResult(const PGresult *src, int flags); PG_COPYRES_TUPLES指定复制源结果的元组。(这也意味着复制属性。) PG_COPYRES_NOTICEHOOKS指定复制源结果的通知钩子。 PG_COPYRES_EVENTS指定复制源结果的事件。(但不复制与源相关的任何实例数据。) - 事件程序接收PGEVT_RESULTCOPY事件。 + 事件过程会收到 PGEVT_RESULTCOPY 事件。 @@ -6160,18 +5895,15 @@ int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs); - 设置一个PGresult对象的一个元组域值。 + 设置 PGresult 对象中某个元组的字段值。 int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len); - + - 这个函数将自动按需增加结果的内部元组数组。但是,tup_num参数必须小于等于,意味着这个函数对元组数组一次只能增加一个元组。 - 但已存在的任意元组中的任意域可以以任意顺序进行调整。如果field_num的一个值已经存在,它会被覆盖。 - 如果len是 -1,或valueNULL, 该域值会被设置为一个 SQL 空值。 - value会被复制到结果的私有存储中,因此函数返回后就不再需要了。如果函数失败,返回值是 0。如果函数成功,返回值会是非 0。 - + 此函数会根据需要自动扩展结果内部的元组数组。不过,tup_num 参数必须小于或等于 ,也就是说,每次只能向元组数组增加一个元组。已有元组的任何字段都可以按任意顺序修改。如果 field_num 指定的位置已有值,该值会被覆盖。如果 len 为 -1 或 valueNULL,则将该字段设置为 SQL null 值。value 会被复制到结果的私有存储中,因此函数返回后就不再需要它。函数失败时返回零,成功时返回非零值。 + @@ -6189,8 +5921,8 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); - 当res被清除时,这个函数分配的内存也会被释放掉。如果函数失败,返回值是NULL。结果被保证为按照数据的任意类型充分地对齐,正如malloc所作的。 - + 使用此函数分配的所有内存都会在清除 res 时释放。函数失败时返回 NULL。与 malloc 一样,返回的内存保证满足任意数据类型的对齐要求。 + @@ -6201,15 +5933,15 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); - 检索为PGresult对象分配的字节数。 + 获取为 PGresult 对象分配的字节数。 size_t PQresultMemorySize(const PGresult *res); - + - 此值是与PGresult对象关联的所有malloc请求的总和,就是说,将释放的所有空间。此信息可用于管理内存消耗。 - + 此值是与 PGresult 对象相关的所有 malloc 请求所分配字节数的总和,即 将释放的全部内存。这一信息有助于管理内存消耗。 + @@ -6221,35 +5953,32 @@ size_t PQresultMemorySize(const PGresult *res); - 返回所使用的libpq版本。 + 返回所使用的libpq版本。 int PQlibVersion(void); - 在运行时,这个函数的结果可以被用来决定在当前已载入的 libpq 版本中特定的功能是否可用。 - 例如,这个函数可以被用来决定哪些选项可以被用于。 - + 可在运行时根据此函数的结果,判断当前已加载的 libpq 版本是否具有特定功能。例如,可用它判断 支持哪些连接选项。 + - 结果通过将库的主版本号乘以10000再加上次版本号形成。例如,版本10.1将被返回为100001,而版本11.0将被返回为110000。 - + 返回值等于库的主版本号乘以 10000 再加上次版本号。例如,版本 10.1 返回 100001,版本 11.0 返回 110000。 + - 在主版本10之前,PostgreSQL采用一种由三个部分组成的版本号,其中前两部分共同表示主版本。 - 对于那些版本,为每个部分使用两个数字,例如版本9.1.5将被返回为90105,而版本9.2.0将被返回为90200。 - + 在主版本 10 之前,PostgreSQL 使用由三个部分组成的版本号,前两个部分共同表示主版本。对于这些版本, 用两位数字表示每个部分;例如,版本 9.1.5 返回 90105,版本 9.2.0 返回 90200。 + - 因此,出于判断特性兼容性的目的,应用应该将的结果除以100而不是10000来判断逻辑的主版本号。 - 在所有的发行序列中,只有最后两个数字在次发行(问题修正发行)之间不同。 - + 因此,为了判断功能兼容性,应用程序应将 的结果除以 100 而非 10000,得到逻辑上的主版本号。在所有版本系列中,次版本(错误修复版本)之间只有最后两位数字不同。 + - 这个函数出现于PostgreSQL版本 9.1,因此它不能被用来在早期的版本中检测所需的功能,因为调用它将会创建一个对版本9.1及其后版本的链接依赖。 + 此函数从 PostgreSQL 9.1 起提供,因而不能用它检测更早版本是否具有所需功能:调用它会建立对 9.1 或更高版本的链接依赖。 @@ -6281,13 +6010,13 @@ pg_usec_time_t PQgetCurrentTimeUSec(void); 通知处理 - notice processing - in libpq + 通知处理 + 在 libpq 中 - 服务器产生的通知和警告消息不会被查询执行函数返回,因为它们不代表查询失败。它们可以被传递给一个通知处理函数,并且在处理者返回后执行会继续正常进行。默认的处理函数会把消息打印在stderr上,但是应用可以通过提供它自己的处理函数来重载这种行为。 - + 服务器生成的通知和警告消息不由查询执行函数返回,因为它们并不表示查询失败。这些消息会传递给通知处理函数,处理函数返回后,执行正常继续。默认通知处理函数将消息打印到 stderr,应用程序也可以提供自己的处理函数来替换这一行为。 + 由于历史原因,通知处理有两个级别,称为通知接收器和通知处理器。通知接收器的默认行为是格式化通知并且将一个字符串传递给通知处理器来打印。不过,如果一个应用选择提供自己的通知接收器,它通常会忽略通知处理器层并且在通知接收器中完成所有工作。 @@ -6295,10 +6024,10 @@ pg_usec_time_t PQgetCurrentTimeUSec(void); 函数PQsetNoticeReceiver - notice receiver + 通知接收器 PQsetNoticeReceiver为一个连接对象设置或者检查当前的通知接收器。 相似地,PQsetNoticeProcessor - notice processor + 通知处理器 PQsetNoticeProcessor设置或检查当前的通知处理器。 @@ -6321,19 +6050,16 @@ PQsetNoticeProcessor(PGconn *conn, - 当接收到一个服务器产生的或者libpq内部产生的通知或警告消息,通知接收器函数会被调用。 - 它会以一种PGRES_NONFATAL_ERROR PGresult的形式传递该消息 - (这允许接收器使用抽取个别的域,或者使用或者得到一个完整的预格式化的消息)。 - 被传递给PQsetNoticeReceiver的同一个空指针也被传递(必要时,这个指针可以被用来访问应用相关的状态)。 - + 从服务器收到通知或警告消息,或者 libpq 内部生成这类消息时,便会调用通知接收器函数。消息以状态为 PGRES_NONFATAL_ERRORPGresult 对象传给该函数。(接收器可使用 提取单个字段,也可使用 获取完整的预格式化消息。)传给 PQsetNoticeReceiver 的同一个 void 指针也会传入。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知接收器会简单地抽取消息(使用)并且将它传递给通知处理器。 - 通知处理器负责处理一个以文本形式给出的通知或警告消息。该消息的字符串文本(包括一个收尾的新行)被传递给通知处理器,外加一个同时被传递给PQsetNoticeProcessor的空指针(必要时,这个指针可以被用来访问应用相关的状态)。 - + 通知处理器负责处理以文本形式提供的通知或警告消息。传给它的参数包括消息字符串(含末尾的换行符),以及先前传给 PQsetNoticeProcessor 的同一个 void 指针。(必要时,可通过该指针访问应用程序特有的状态。) + 默认的通知处理器很简单: @@ -6347,9 +6073,8 @@ defaultNoticeProcessor(void *arg, const char *message) - 一旦你设定了一个通知接收器或处理器,你应该期待只要PGconn对象或者从它构造出的PGresult对象存在,该函数就应该能被调用。 - 在一个PGresult创建时,PGconn的当前通知处理指针被复制到PGresult中,以备类似的函数使用。 - + 设置通知接收器或处理器后,应当预期:只要 PGconn 对象或由它生成的 PGresult 对象仍存在,就可能调用该函数。创建 PGresult 时,会将 PGconn 当前的通知处理指针复制到 PGresult 中,供 等函数在需要时使用。 + @@ -6358,19 +6083,19 @@ defaultNoticeProcessor(void *arg, const char *message) 事件系统 - libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和毁灭。一种主要的使用情况是这允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 + libpq的事件系统被设计为通知已注册的事件处理器它感兴趣的libpq事件,例如PGconn以及PGresult对象的创建和销毁。一个主要用途是允许应用将自己的数据与一个PGconn或者PGresult关联在一起,并且确保那些数据在适当的时候被释放。 - 每个注册的事件处理程序都与两个数据相关联,libpq仅将其视为不透明的void *指针。 - 有一个透传指针,当事件处理程序与PGconn注册时,应用程序提供。 + 每个注册的事件处理程序都与两项数据相关联,libpq仅将其视为不透明的void *指针。 + 有一个透传指针,由应用程序在向 PGconn 注册事件处理程序时提供。 透传指针在PGconn及其生成的所有PGresult的生命周期内永远不会更改; 因此,如果使用,它必须指向长期存在的数据。 此外,还有一个实例数据指针,在每个PGconnPGresult中一开始都是NULL。 可以使用函数来操作此指针。 请注意,与透传指针不同,PGconn的实例数据不会自动继承到从中创建的PGresult。 - libpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 —— 这是事件处理程序的责任。 + libpq不知道透传和实例数据指针指向的内容(如果有的话),也永远不会尝试释放它们 — 这是事件处理程序的责任。 @@ -6396,7 +6121,7 @@ typedef struct } PGEventRegister; - 当接收到PGEVT_REGISTER事件时,evtInfo指针应该转换为PGEventRegister *。这个结构体包含一个应该处于CONNECTION_OK状态的PGconn;如果在获得一个良好的PGconn后立即调用,则保证这一点。当返回一个失败代码时,所有清理工作必须完成,因为不会发送任何PGEVT_CONNDESTROY事件。 + 当接收到PGEVT_REGISTER事件时,evtInfo指针应该转换为PGEventRegister *。这个结构体包含一个应该处于CONNECTION_OK状态的PGconn;如果在获得一个良好的PGconn后立即调用,则保证这一点。当返回一个失败代码时,所有清理工作必须完成,因为不会发送任何PGEVT_CONNDESTROY事件。 @@ -6429,21 +6154,12 @@ typedef struct PGEVT_CONNDESTROY - - - 为了响应,连接销毁事件会被触发。由于 libpq 没有能力管理事件数据,事件过程有责任正确地清理它的事件数据。清理失败将会导致内存泄露。 - - + 连接销毁事件由以下调用触发:。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGconn *conn; } PGEventConnDestroy; - - - 当接收到一个PGEVT_CONNDESTROY事件时,evtInfo指针应该被类型转换为PGEventConnDestroy *。 - 这个事件在执行任何其他清理之前被触发。 - 该事件过程的返回值被忽略,因为没有办法指示一个来自的失败。还有,一个事件过程失败不该中断对不需要的内存的清理。 - +收到PGEVT_CONNDESTROY事件时,应将evtInfo指针强制转换为PGEventConnDestroy *。该事件触发于以下函数执行任何其他清理工作之前:。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:。此外,事件过程失败不应中止清理不再使用的内存的过程。 @@ -6499,21 +6215,12 @@ typedef struct PGEVT_RESULTDESTROY - - - 为了响应,结果销毁事件会被触发。由于 libpq 没有能力管理事件数据,事件过程有责任正确地清理它的事件数据。清理失败将会导致内存泄露。 - - + 结果销毁事件由以下调用触发:。事件过程负责正确清理其事件数据,因为 libpq 无法管理这部分内存。如果不清理,就会造成内存泄漏。 typedef struct { PGresult *result; } PGEventResultDestroy; - - - 当接收到一个PGEVT_RESULTDESTROY事件时,evtInfo指针应该被类型转换为PGEventResultDestroy *。 - 这个事件在执行任何其他清理之前被触发。该事件过程的返回值被忽略,因为没有办法指示来自的失败。 - 还有,一个事件过程失败不该中断不需要的内存的清理过程。 - +收到PGEVT_RESULTDESTROY事件时,应将evtInfo指针强制转换为PGEventResultDestroy *。该事件触发于以下函数执行任何其他清理工作之前:。事件过程的返回值会被忽略,因为无法通过以下函数报告失败:。此外,事件过程失败不应中止清理不再使用的内存的过程。 @@ -6521,7 +6228,7 @@ typedef struct - 事件回调函数 + 事件回调过程 @@ -6531,16 +6238,11 @@ typedef struct - PGEventProc是到一个事件过程的指针的 typedef,也就是从 libpq 接收事件的用户回调函数。一个事件过程的原型必须是 - + PGEventProc 是通过 typedef 定义的事件过程指针类型,也就是接收 libpq 事件的用户回调函数的指针类型。事件过程的签名必须为: int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) - - evtId指示发生了哪一个PGEVT事件。 - evtInfo指针必须被类型转换为合适的结构体类型才能获得关于事件的进一步信息。 - 当事件过程已被注册时,passThrough参数是提供给的指针。 - 如果成功,该函数应该返回非零值,失败则返回零。 +evtId 参数指示发生了哪一种 PGEVT 事件。必须将 evtInfo 指针强制转换为适当的结构体类型,以获取关于该事件的更多信息。passThrough 参数是在注册事件过程时传给 的指针。函数应在成功时返回非零值,在失败时返回零。 @@ -6550,8 +6252,8 @@ int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) - 在 Windows 上,函数能够有两个不同的地址:一个对 DLL 之外可见而另一个对 DLL 之内可见。我们应当小心只有其中之一会被用于libpq的事件过程函数,否则将会产生混淆。编写代码的最简单规则是将所有的事件过程声明为static。如果过程的地址必须对它自己的源代码文件之外可见,提供一个单独的函数来返回该地址。 - + 在 Windows 上,函数可能有两个不同的地址:一个在 DLL 外部可见,另一个在 DLL 内部可见。使用 libpq 的事件过程函数时,务必始终使用其中同一个地址,否则会产生混淆。确保代码正常工作的最简单做法,是将事件过程声明为 static。如果需要在过程所在的源文件之外取得其地址,应提供一个单独的函数来返回该地址。 + @@ -6579,7 +6281,7 @@ int PQregisterEventProc(PGconn *conn, PGEventProc proc, - 在每一个你想要接收事件的PGconn上必须注册一个事件过程。和内存不同,没有限制说一个连接上能注册多少个事件过程。如果该函数成功,它会返回一个非零值。如果它失败,则会返回零。 + 对于希望接收其事件的每个 PGconn,都必须注册一次事件过程。一个连接可注册的事件过程数量只受内存限制。函数成功时返回非零值,失败时返回零。 @@ -6624,16 +6326,14 @@ void *PQinstanceData(const PGconn *conn, PGEventProc proc); - 把结果的用于procinstanceData设置为data。成功返回非零,失败返回零(只有proc没有被正确地注册在conn中,才可能会失败)。 - + 将结果中针对 procinstanceData 设置为 data。成功时返回非零值,失败时返回零。(只有当 proc 未在结果中正确注册时,才可能失败。) int PQresultSetInstanceData(PGresult *res, PGEventProc proc, void *data); - 请注意,data表示的任何存储都不会由考虑,除非使用分配。 - (这样做是值得推荐的,因为它消除了在销毁结果时显式释放此类存储的需要。) + 注意,data 所指的存储不会计入 ,除非使用 分配它。(推荐这样做,因为结果销毁时便不必显式释放这部分存储。) @@ -6657,18 +6357,18 @@ void *PQresultInstanceData(const PGresult *res, PGEventProc proc); - 事件实例 + 事件示例 - 这里是一个管理与 libpq 连接和结果相关的私有数据的示例的框架。 - + 下面给出一个示例框架,用于管理与 libpq 连接和结果关联的私有数据。 + -/* The instanceData */ +/* instanceData 数据 */ typedef struct { int n; @@ -6688,14 +6388,14 @@ main(void) if (PQstatus(conn) != CONNECTION_OK) { - /* PQerrorMessage's result includes a trailing newline */ + /* PQerrorMessage 的结果包含末尾的换行符 */ fprintf(stderr, "%s", PQerrorMessage(conn)); PQfinish(conn); return 1; } - /* called once on any connection that should receive events. - * Sends a PGEVT_REGISTER to myEventProc. + /* 在每个需要接收事件的连接上调用一次。 + * 向 myEventProc 发送 PGEVT_REGISTER 事件。 */ if (!PQregisterEventProc(conn, myEventProc, "mydata_proc", NULL)) { @@ -6704,28 +6404,28 @@ main(void) return 1; } - /* conn instanceData is available */ + /* 可以取得 conn 的 instanceData */ data = PQinstanceData(conn, myEventProc); - /* Sends a PGEVT_RESULTCREATE to myEventProc */ + /* 向 myEventProc 发送 PGEVT_RESULTCREATE 事件 */ res = PQexec(conn, "SELECT 1 + 1"); - /* result instanceData is available */ + /* 可以取得结果的 instanceData */ data = PQresultInstanceData(res, myEventProc); - /* If PG_COPYRES_EVENTS is used, sends a PGEVT_RESULTCOPY to myEventProc */ + /* 使用 PG_COPYRES_EVENTS 时,向 myEventProc 发送 PGEVT_RESULTCOPY 事件 */ res_copy = PQcopyResult(res, PG_COPYRES_TUPLES | PG_COPYRES_EVENTS); - /* result instanceData is available if PG_COPYRES_EVENTS was - * used during the PQcopyResult call. + /* 如果调用 PQcopyResult 时使用了 PG_COPYRES_EVENTS, + * 就可以取得结果的 instanceData。 */ data = PQresultInstanceData(res_copy, myEventProc); - /* Both clears send a PGEVT_RESULTDESTROY to myEventProc */ + /* 两次清除操作都会向 myEventProc 发送 PGEVT_RESULTDESTROY 事件 */ PQclear(res); PQclear(res_copy); - /* Sends a PGEVT_CONNDESTROY to myEventProc */ + /* 向 myEventProc 发送 PGEVT_CONNDESTROY 事件 */ PQfinish(conn); return 0; @@ -6741,7 +6441,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventRegister *e = (PGEventRegister *)evtInfo; mydata *data = get_mydata(e->conn); - /* associate app specific data with connection */ + /* 将应用程序特有的数据与连接关联 */ PQsetInstanceData(e->conn, myEventProc, data); break; } @@ -6761,7 +6461,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventConnDestroy *e = (PGEventConnDestroy *)evtInfo; mydata *data = PQinstanceData(e->conn, myEventProc); - /* free instance data because the conn is being destroyed */ + /* 连接正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; @@ -6773,7 +6473,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *conn_data = PQinstanceData(e->conn, myEventProc); mydata *res_data = dup_mydata(conn_data); - /* associate app specific data with result (copy it from conn) */ + /* 将应用程序特有的数据与结果关联(从 conn 复制) */ PQresultSetInstanceData(e->result, myEventProc, res_data); break; } @@ -6784,7 +6484,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) mydata *src_data = PQresultInstanceData(e->src, myEventProc); mydata *dest_data = dup_mydata(src_data); - /* associate app specific data with result (copy it from a result) */ + /* 将应用程序特有的数据与结果关联(从另一个结果复制) */ PQresultSetInstanceData(e->dest, myEventProc, dest_data); break; } @@ -6794,18 +6494,18 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGEventResultDestroy *e = (PGEventResultDestroy *)evtInfo; mydata *data = PQresultInstanceData(e->result, myEventProc); - /* free instance data because the result is being destroyed */ + /* 结果正在销毁,因此释放实例数据 */ if (data) free_mydata(data); break; } - /* unknown event ID, just return true. */ + /* 未知的事件 ID,直接返回 true。 */ default: break; } - return true; /* event processing succeeded */ + return true; /* 事件处理成功 */ } ]]> @@ -6821,9 +6521,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 以下环境变量可用于选择默认连接参数值,这些值将被使用,如果调用代码没有直接指定值。这些对于避免将数据库连接信息硬编码到简单的客户端应用程序中非常有用,例如。 - - + 以下环境变量可用于选择连接参数的默认值,供 在调用代码未直接指定参数值时使用。例如,这样可以避免在简单的客户端应用程序中硬编码数据库连接信息。 + @@ -6994,7 +6693,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGREQUIRESSL的行为与连接参数相同。 - 这个环境变量已被弃用,推荐使用PGSSLMODE变量;设置这两个变量会抑制这个变量的效果。 + 这个环境变量已被弃用,推荐使用PGSSLMODE变量;同时设置这两个变量时,前者不再生效。 @@ -7230,9 +6929,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 下面的环境变量可用来为每一个PostgreSQL会话指定默认行为(为每一个用户或每一个数据库设置默认行为的方法还可见命令)。 - - + 以下环境变量可用于指定每个 PostgreSQL 会话的默认行为。(也可参见 命令,了解按用户或按数据库设置默认行为的方法。) + @@ -7260,8 +6958,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - - 这些环境变量的正确值可参考SQL 命令 。 +有关这些环境变量的正确取值,请参见 SQL 命令 @@ -7306,16 +7003,12 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) 用户主目录中的.pgpass文件可保存密码,供连接需要密码且尚未通过其他方式指定密码时使用。在 Unix 系统上,该目录可由HOME环境变量指定;如果未定义该变量,则使用有效用户的主目录。在 Microsoft Windows 上,文件名为%APPDATA%\postgresql\pgpass.conf(其中%APPDATA%指用户配置文件中的应用数据子目录)。也可以通过连接参数或环境变量PGPASSFILE指定要使用的密码文件。 - - 这个文件应该包含下列格式的行: - + 该文件中的行应采用以下格式: hostname:port:database:username:password - - (你可以向该文件增加一个提醒:把上面的行复制到该文件并且在前面加上#)。前四个字段的每一个都可以是字面值或者匹配任何东西的*。第一个匹配当前连接参数的行中的密码字段将被使用(因此,在使用通配符时把更特殊的项放在前面)。如果一个条目需要包含:或者\,用\对该字符转义。如果指定了host连接参数,主机名字段会被匹配到host,否则如果指定了hostaddr参数则匹配到hostaddr,如果两者都没有给出,则会搜索主机名localhost。当连接是一个Unix域套接字连接并且host参数匹配libpq的默认套接字目录路径时,也会搜索主机名localhost。在一台备库上,值为replication的数据库字段匹配连接到主库的流复制连接。否则数据库字段的用途有限,因为用户对同一个集簇中的所有数据库都有相同的密码。 - +(可以复制上面这一行,并在行首加上#,在文件中加入提示注释。)前四个字段中的每一个都可以是字面值,或者是*,后者可以匹配任何内容。将使用与当前连接参数匹配的第一行中的密码字段。(因此,使用通配符时,应将更具体的条目放在前面。)如果条目需要包含:\,请使用\转义该字符。主机名字段首先匹配已指定的host连接参数;否则匹配已指定的hostaddr参数。如果两者都未指定,则查找主机名localhost。在以下情况下也会查找主机名localhost:连接使用 Unix 域套接字,且host参数与libpq的默认套接字目录路径匹配。在备库中,数据库字段为replication时,匹配连接到主库的流复制连接。除此之外,数据库字段的用途有限,因为同一用户在同一数据库集簇的所有数据库中使用相同的密码。 - 在 Unix 系统上,密码文件上的权限必须不允许所有人或组内访问,可以用chmod 0600 ~/.pgpass这样的命令实现。如果权限没有这么严格,该文件将被忽略。在微软 Windows 上,该文件被假定存储在一个安全的目录中,因此不会进行特别的权限检查。 + 在 Unix 系统上,密码文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.pgpass 这样的命令实现。如果权限没有这么严格,该文件将被忽略。在 Microsoft Windows 上,假定该文件存储在安全的目录中,因此不进行特殊的权限检查。 @@ -7336,10 +7029,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 连接服务文件允许 libpq 连接参数与一个单一服务名称关联。 - 那个服务名称可以在一个 libpq 连接字符串里面指定,与其相关的设置将被使用。 - 这允许在不重新编译使用 libpq 的应用的前提下修改连接参数。 - 服务名称也可以被使用PGSERVICE环境变量来指定。 + 连接服务文件允许将 libpq 连接参数与单个服务名称关联。随后可以在 libpq 连接字符串中使用 service 关键字指定该服务名称,从而使用关联的设置。这样便可以修改连接参数,而无需重新编译使用 libpq 的应用程序。也可以使用 PGSERVICE 环境变量指定服务名称。 @@ -7355,23 +7045,19 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - 或者服务文件使用一种INI 文件格式,其中小节名是服务名并且参数是连接参数。 - 列表见。例如: + 两种服务文件均使用 INI 文件 格式,其中配置段名称是服务名称,参数是连接参数;参数列表见 。例如: -# comment +# 注释 [mydb] host=somehost port=5433 user=admin - 在PostgreSQL安装的share/pg_service.conf.sample中提供了一个示例文件。 +PostgreSQL 安装目录中的 share/pg_service.conf.sample 提供了一个示例文件。 - 从服务文件中获取的连接参数与从其他来源获取的参数相结合。 - 服务文件设置覆盖相应的环境变量,然后反过来可以由连接字符串中直接给出的值覆盖。 - 例如,使用上面的服务文件,连接字符串service=mydb port=5434将使用主机somehost,端口5434, - 用户admin,以及由环境变量或内置默认所设置的其他参数。 + 从服务文件中获取的连接参数会与其他来源的参数合并。服务文件中的设置会覆盖相应的环境变量,而连接字符串中直接给出的值又会覆盖服务文件中的设置。例如,使用上述服务文件时,连接字符串 service=mydb port=5434 将使用主机 somehost、端口 5434、用户 admin,以及由环境变量或内置默认值设置的其他参数。 @@ -7387,24 +7073,14 @@ user=admin 如果libpq已经在编译时打开了 LDAP 支持(configure的选项),就可以通过 LDAP 从一个中央服务器检索hostdbname之类的连接参数。这样做的好处是如果一个数据库的连接参数改变,不需要在所有的客户端机器上更新连接信息。 - - LDAP连接参数查找使用连接服务文件pg_service.conf(参见)。 - 在pg_service.conf段落中以ldap://开头的行将被识别为LDAP URL,并执行LDAP查询。 - 结果必须是一组keyword = value对,将用于设置连接选项。 - URL必须符合RFC 1959的形式为 - + LDAP 连接参数查询使用连接服务文件pg_service.conf(参见)。在pg_service.conf的配置段中,以ldap://开头的行会被识别为 LDAP URL,并执行 LDAP 查询。结果必须是一个keyword = value键值对列表,用于设置连接选项。URL 必须符合 RFC 1959,格式如下: ldap://[hostname[:port]]/search_base?attribute?search_scope?filter - - 其中hostname默认为localhostport默认为389。 - +其中,hostname默认为localhostport默认为 389。 - - 一次成功的 LDAP 查找后,pg_service.conf的处理被终止。但是如果联系不上 LDAP 则会继续处理pg_service.conf。这就提供了后手,可以加入更多指向不同 LDAP 服务器的 LDAP URL 行、经典的keyword = value对或者默认连接选项。如果你宁愿在这种情况下得到一个错误消息,在该 LDAP URL 之后增加一个语法错误的行。 - + LDAP 查找成功后就会停止处理 pg_service.conf;如果无法联系 LDAP 服务器,则会继续处理。这使后续指向其他 LDAP 服务器的 LDAP URL 行、常规的 keyword = value 对或默认连接选项能够作为后备。如果希望在这种情况下得到错误消息,可以在 LDAP URL 后添加一个语法不正确的行。 - - 一个和 LDIF 文件一起创建的 LDAP 条目实例 - + 例如,使用以下 LDIF 文件创建的 LDAP 条目: version:1 dn:cn=mydatabase,dc=mycompany,dc=com changetype:add @@ -7416,9 +7092,7 @@ description:port=5439 description:dbname=mydb description:user=mydb_user description:sslmode=require - - 可以用下面的 LDAP URL 查询: - +可以通过以下 LDAP URL 查询: ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase) @@ -7426,7 +7100,7 @@ ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase) 你也可以将常规的服务文件条目和 LDAP 查找混合。pg_service.conf中一节的完整示例: -# 只有主机和端口存储在LDAP中,显式指定dbname和user。 +# 仅 host 和 port 存储在 LDAP 中;显式指定 dbname 和 user [customerdb] dbname=customer user=appuser @@ -7446,9 +7120,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - PostgreSQL具有原生支持使用SSL连接来加密客户端/服务器通信, - 使用TLS协议以提高安全性。有关服务器端SSL功能的详细信息,请参见。 - + PostgreSQL 原生支持使用 SSL 连接,通过 TLS 协议加密客户端与服务器之间的通信,以提高安全性。有关服务器端 SSL 功能的详细信息,请参见 。 + libpq读取系统范围的OpenSSL配置文件。默认情况下,这个文件被命名为openssl.cnf并且位于openssl version -d所报告的目录中。可以通过设置环境变量OPENSSL_CONF把这个默认值覆盖为想要的配置文件的名称。 @@ -7456,39 +7129,25 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 服务器证书的客户端验证 + 客户端对服务器证书的验证 - 默认情况下,PostgreSQL将不会执行服务器证书的任何验证。这意味着可以在不被客户端知晓的情况下伪造服务器身份(例如通过修改一个 DNS 记录或者接管服务器的 IP 地址)。为了阻止哄骗,客户端必须能够通过一条信任链验证服务器的身份。信任链可以这样建立:在一台计算机上放置一个根(自签名的)证书机构(CA)的证书并且在另一台计算机上放置一个由根证书签发的叶子证书。还可以使用一种中间证书,它由根证书签发并且可以签发叶子证书。 + 默认情况下,PostgreSQL 不会对服务器证书执行任何验证。这意味着可以在客户端不知情的情况下伪造服务器身份,例如修改 DNS 记录或接管服务器的 IP 地址。要防止身份伪造,客户端必须能够通过信任链验证服务器身份。建立信任链的方法是:在一台计算机上放置根证书机构(CA)的自签名证书,在另一台计算机上放置由根证书签发的叶证书。也可以使用由根证书签发、又用于签发叶证书的中间证书。 - - 为了允许客户端验证服务器的身份,在客户端上放置一份根证书并且在服务器上放置由根证书签发的叶子证书。为了允许服务器验证客户端的身份,在服务器上放置一份根证书并且在客户端上放置由根证书签发的叶子证书。也可以使用一个或者更多个中间证书(通常与叶子证书存在一起)来将叶子证书链接到根证书。 - + 要让客户端验证服务器的身份,请在客户端放置根证书,并在服务器上放置由该根证书签发的叶证书。要让服务器验证客户端的身份,请在服务器上放置根证书,并在客户端放置由该根证书签发的叶证书。也可以使用一个或多个中间证书(通常与叶证书存储在一起),将叶证书链接到根证书。 - - 一旦信任链被建立起来,客户端有两种方法验证服务器发过来的叶子证书。如果参数sslmode被设置为verify-ca,libpq将通过检查该证书是否链接到存储在客户端上的根证书来验证服务器。如果sslmode被设置为verify-full,libpq将验证服务器的主机名匹配存储在服务器证书中的名称。如果服务器证书无法被验证,则SSL连接将失败。在大部分对安全性很敏感的环境中,推荐使用verify-full。 - + 建立信任链后,客户端可以通过两种方式验证服务器发送的叶证书。如果参数 sslmode 设为 verify-ca,libpq 会沿证书链检查到存储在客户端上的根证书,以验证服务器是否可信。如果 sslmode 设为 verify-full,libpq 还会验证服务器主机名是否与服务器证书中存储的名称匹配。如果无法验证服务器证书,SSL 连接将失败。在大多数对安全敏感的环境中,建议使用 verify-full - 在verify-full模式下,主机名将与证书的主体替代名称属性(SAN)匹配, - 或者与通用名称属性匹配,如果没有类型为dNSName的SAN存在。 - 如果证书的名称属性以星号(*)开头,那么星号将被视为通配符, - 可以匹配所有字符,除了点(.)。 - 这意味着证书将不匹配子域。如果连接使用IP地址而不是主机名进行, - 则IP地址将与类型为iPAddressdNSName的SAN匹配 - (不进行任何DNS查找)。如果没有iPAddress SAN存在, - 也没有匹配的dNSName SAN存在,则主机IP地址将与通用名称属性匹配。 - + 在 verify-full 模式下,会将主机名与证书的主体替代名称属性(SAN)匹配;如果不存在类型为 dNSName 的 SAN,则与通用名称属性匹配。如果证书的名称属性以星号(*)开头,该星号会被视为通配符,匹配点(.)以外的所有字符。这意味着该证书不会匹配子域。如果使用 IP 地址而不是主机名建立连接,则会将该 IP 地址与类型为 iPAddressdNSName 的 SAN 匹配(不执行任何 DNS 查询)。如果不存在 iPAddress SAN,也不存在匹配的 dNSName SAN,则将主机 IP 地址与通用名称属性匹配。 + - 为了与早期版本的PostgreSQL向后兼容,主机IP地址的验证方式与 - RFC 6125中的方式不同。 - 主机IP地址始终与dNSName SANs以及iPAddress SANs匹配, - 如果不存在相关的SANs,则可以与通用名称属性匹配。 - + 为与 PostgreSQL 的早期版本向后兼容,主机 IP 地址的验证方式与 RFC 6125 不同。主机 IP 地址始终会与 dNSName SAN 以及 iPAddress SAN 匹配;如果不存在相关的 SAN,还可以与通用名称属性匹配。 + @@ -7508,8 +7167,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - 为了与 PostgreSQL 的早期版本达到向后兼容,如果存在一个根 CA 文件,sslmode=require的行为将与verify-ca相同,即服务器证书根据 CA 验证。我们鼓励依赖这种行为,并且需要证书验证的应用应该总是使用verify-ca或者verify-full。 - + 为与 PostgreSQL 的早期版本向后兼容,如果存在根 CA 文件,sslmode=require 的行为将与 verify-ca 相同,即根据 CA 验证服务器证书。不建议依赖这种行为;需要证书验证的应用程序应始终使用 verify-caverify-full。 + @@ -7518,44 +7177,27 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 客户端证书 - 如果服务器尝试通过请求客户端的叶证书来验证客户端的身份, - libpq将发送存储在文件 - ~/.postgresql/postgresql.crt中的证书,该文件位于用户的主目录中。 - 证书必须链到服务器信任的根证书。匹配的 - 私钥文件~/.postgresql/postgresql.key也必须存在。 - 在Microsoft Windows上,这些文件的名称分别为 - %APPDATA%\postgresql\postgresql.crt和 - %APPDATA%\postgresql\postgresql.key。 - 证书和密钥文件的位置可以通过连接参数 - sslcertsslkey, - 或通过环境变量PGSSLCERTPGSSLKEY来覆盖。 - + 如果服务器请求客户端的叶证书以验证客户端身份,libpq 将发送用户主目录下 ~/.postgresql/postgresql.crt 文件中存储的证书。这些证书必须通过证书链连接到服务器信任的根证书。还必须存在匹配的私钥文件 ~/.postgresql/postgresql.key。在 Microsoft Windows 上,这两个文件分别名为 %APPDATA%\postgresql\postgresql.crt%APPDATA%\postgresql\postgresql.key。可以通过连接参数 sslcertsslkey,或环境变量 PGSSLCERTPGSSLKEY,覆盖证书和密钥文件的位置。 + - 在Unix系统上,私钥文件的权限必须禁止任何对世界或组的访问;可以通过类似以下命令来实现: - chmod 0600 ~/.postgresql/postgresql.key。 - 或者,该文件可以由root拥有并具有组读取权限(即0640权限)。 - 该设置适用于由操作系统管理证书和密钥文件的安装。然后,libpq的用户应该成为具有对这些证书和密钥文件访问权限的组的成员。 - (在Microsoft Windows上,没有文件权限检查,因为假定%APPDATA%\postgresql目录是安全的。) - + 在 Unix 系统上,私钥文件的权限必须禁止所属组及其他用户的任何访问;可以用 chmod 0600 ~/.postgresql/postgresql.key 这样的命令实现。另一种做法是使文件归 root 所有,并允许组用户读取(即 0640 权限)。这种设置适用于由操作系统管理证书和密钥文件的安装环境。此时,应将 libpq 用户加入有权访问这些证书和密钥文件的组。(在 Microsoft Windows 上,不检查文件权限,因为假定 %APPDATA%\postgresql 目录是安全的。) + postgresql.crt中的第一个证书必须是客户端的证书,因为它必须匹配客户端的私钥。可以选择将中间证书追加到该文件 — 这样做避免了在服务器上存放中间证书的要求()。 - 证书和密钥可能是 PEM 或 ASN.1 DER 格式。 + 证书和密钥可以采用 PEM 或 ASN.1 DER 格式。 - 密钥可以以明文存储,也可以使用OpenSSL支持的任何算法(例如AES-128)使用密码进行加密。 - 如果密钥是加密存储的,那么可以在连接选项中提供密码。 - 如果提供了加密密钥,而且sslpassword选项不存在或为空,那么只要 TTY 可用,OpenSSL就会以Enter PEM pass phrase:提示交互式输入密码。 - 应用程序可以通过提供自己的密钥密码回调,覆盖客户端证书提示以及sslpassword参数的处理;参见。 + 密钥可以以明文存储,也可以使用密码,按 OpenSSL 支持的任意算法(例如 AES-128)进行加密。如果密钥以加密形式存储,可以在 连接选项中提供密码。如果提供了加密密钥,而 sslpassword 选项缺失或为空,则在有 TTY 可用时,OpenSSL 会显示 Enter PEM pass phrase: 提示,交互式地请求输入密码。应用程序可以提供自己的密钥密码回调,以覆盖客户端证书提示及 sslpassword 参数的处理;参见 - 创建证书的指令请参考。 + 有关创建证书的说明,请参见 @@ -7564,8 +7206,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 不同模式中提供的保护 - sslmode参数的不同值提供了不同级别的保护。SSL 能够针对三类攻击提供保护: - + sslmode 参数的不同值提供不同级别的保护。SSL 可以防范三类攻击: 窃听 @@ -7578,31 +7219,33 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 中间人(MITM - 如果一个第三方能对客户端和服务器之间传送的数据进行修改,它就能假装是服务器并且因此能看见并且修改数据,即使这些数据已被加密。然后第三方可以将连接信息和数据转送给原来的服务器,使得它不可能检测到攻击。这样做的通常途径包括 DNS 污染和地址劫持,借此客户端被重定向到一个不同的服务器。还有几种其他的攻击方式能够完成这种攻击。SSL使用证书验证让客户端认证服务器,就可以阻止这种攻击。 - + + 如果第三方能修改客户端与服务器之间传输的数据,就可以冒充服务器,进而查看和修改数据,即使数据已经加密。随后,第三方可以将连接信息和数据转发给原来的服务器,使攻击无法被察觉。常见的手段包括 DNS 污染和地址劫持,从而将客户端引向预期之外的服务器。还有其他几种攻击手段可以达到同样的目的。SSL 使用证书验证,让客户端认证服务器身份,以防范这种攻击。 + - 模仿 + 冒充 - 如果一个第三方能假装是一个授权的客户端,它能够简单地访问它本不能访问的数据。通常这可以由不安全的密码管理所致。SSL使用客户端证书来确保只有持有合法证书的客户端才能访问服务器,这样就能阻止这种攻击。 - + + 如果第三方能冒充获授权的客户端,就能直接访问其无权访问的数据。这通常可能由不安全的密码管理导致。SSL 使用客户端证书,确保只有持有有效证书的客户端才能访问服务器,以防范这种攻击。 + - 对于一个已知受 SSL 保护的连接,在连接建立之前,必须在客户端和服务器两端都配置 SSL。如果只在服务器端配置,客户端在得知服务器要求高安全性之前,可能就已经开始发送敏感信息(例如密码)。在 libpq 中,要确保连接安全,可以把sslmode参数设置为verify-fullverify-ca,并为系统提供一个用于验证的根证书。这类似于使用https URL浏览加密网页。 + 要确保连接受到 SSL 保护,必须在建立连接之前,在客户端和服务器两端配置 SSL。如果仅在服务器上配置,客户端可能在得知服务器要求高安全性之前就已发送敏感信息(例如密码)。在 libpq 中,可以将 sslmode 参数设为 verify-fullverify-ca,并向系统提供用于验证的根证书,以确保连接安全。这类似于使用 https URL 进行加密的网页浏览。 - 一旦服务器已经被认证,客户端可以传递敏感数据。这意味着直到这一点,客户端都不需要知道是否证书将被用于认证,这样只需要在服务器配置中指定就比较安全。 + 服务器通过身份认证后,客户端便可以传送敏感数据。这意味着,在此之前,客户端无需知道是否会使用证书进行认证,因此可以安全地仅在服务器配置中指定这一点。 - 所有SSL选项都带来了加密和密钥交换的负荷,因此必须在性能和安全性之间做出平衡。不同sslmode值所保护的风险,以及它们是怎样看待安全性和负荷的。 + 所有 SSL 选项都会产生加密和密钥交换的开销,因此必须在性能与安全性之间作出权衡。 说明了不同 sslmode 值所能防范的风险,以及它们所表达的对安全性和开销的取舍。
@@ -7618,7 +7261,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) sslmode 窃听保护 - 中间人攻击防护 + MITM 防护 声明 @@ -7629,7 +7272,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) disable - 我不关心安全性,并且我不想为加密增加负荷。 + 我不关心安全性,并且我不想为加密增加开销。 @@ -7637,7 +7280,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) allow 可能 - 我不关心安全性,但如果服务器坚持,我将承担加密带来的负荷。 + 我不关心安全性,但如果服务器坚持,我将承担加密带来的开销。 @@ -7645,7 +7288,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) prefer 可能 - 我不关心安全性,但如果服务器支持,我希望承担加密带来的负荷。 + 我不关心加密,但如果服务器支持,我希望承担加密带来的开销。 @@ -7653,7 +7296,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) require - 我想要对数据加密,并且我接受因此带来的负荷。我信任该网络会保证我总是连接到想要连接的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我信任该网络会保证我总是连接到想要连接的服务器。 @@ -7661,7 +7304,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-ca 取决于 CA 策略 - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器。 @@ -7669,7 +7312,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) verify-full - 我想要对数据加密,并且我接受因此带来的负荷。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 + 我想要对数据加密,并且我接受因此带来的开销。我想要确保我连接到的是我信任的服务器,并且就是我指定的那一个。 @@ -7678,11 +7321,11 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
- verify-caverify-full之间的区别取决于根CA的策略。如果使用了一个公共CAverify-ca允许连接到那些可能已经被其他人注册到该CA的服务器。在这种情况下,总是应该使用verify-full。如果使用了一个本地CA或者甚至是一个自签名的证书,使用verify-ca常常就可以提供足够的保护。 + verify-caverify-full之间的区别取决于根CA的策略。如果使用了一个公共CAverify-ca允许连接到那些可能已经被其他人注册到该CA的服务器。在这种情况下,总是应该使用verify-full。如果使用了一个本地CA或者甚至是一个自签名的证书,使用verify-ca常常就可以提供足够的保护。 - sslmode的默认值是prefer。如表中所示,这在安全性的角度来说没有意义,并且它只承诺可能的性能负荷。提供它作为默认值只是为了向后兼容,并且我们不推荐在安全部署中使用它。 + sslmode 的默认值是 prefer。如表所示,从安全角度看,这一设置没有意义;它只会在可能时带来性能开销。将其作为默认值仅出于向后兼容的考虑,不建议在有安全要求的部署中使用。 @@ -7724,8 +7367,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) ~/.postgresql/root.crt - 可信的证书机构 - 检查服务器证书是由一个可信的证书机构签发 + 受信任的证书机构 + 检查服务器证书是由一个受信任的证书机构签发 @@ -7743,7 +7386,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) SSL 库初始化 - 需要兼容旧版 PostgreSQL、使用 OpenSSL 1.0.2 或更早版本的应用程序,需要在使用 SSL 库之前初始化它。自行初始化 libssl 和/或 libcrypto 库的应用程序应调用 ,告知 libpq 这些库已由应用程序初始化,使 libpq 不再初始化它们。不过,使用 OpenSSL 1.1.0 或更高版本时无需这样做,因为重复初始化已不再造成问题。 + 需要兼容旧版 PostgreSQL、使用 OpenSSL 1.0.2 或更早版本的应用程序,需要在使用 SSL 库之前初始化它。自行初始化 libssl 和/或 libcrypto 库的应用程序应调用 ,告知 libpq libssl 和/或 libcrypto 库已由应用程序初始化,使 libpq 不再初始化它们。不过,使用 OpenSSL 1.1.0 或更高版本时无需这样做,因为重复初始化已不再造成问题。 有关这些函数的用法,请参阅目标 PostgreSQL 版本的文档。 @@ -7798,8 +7441,8 @@ void PQinitSSL(int do_ssl); OAuth 支持 - libpq通过一个可选模块实现了对 OAuth v2 Device Authorization 客户端流程的支持,该流程记录在 - RFC 8628中。关于如何启用内置的 Device Authorization 流程,请参见安装文档。 + libpq通过一个可选模块实现了对 OAuth v2 设备授权客户端流程的支持,该流程记录在 + RFC 8628中。关于如何启用内置的设备授权流程,请参见安装文档。 当启用支持并安装该可选模块后,如果服务器在认证期间请求 Bearer 令牌,libpq默认会使用内置流程。即使运行客户端应用的系统没有可用的 Web 浏览器,例如通过SSH运行客户端时,也可以使用这一流程。 @@ -7821,7 +7464,7 @@ Visit https://example.com/device and enter the code: ABCD-EFGH - 当前 Windows 上尚不支持内置的 Device Authorization 流程。不过,仍然可以实现自定义客户端流程。 + 当前 Windows 上尚不支持内置的设备授权流程。不过,仍然可以实现自定义客户端流程。 @@ -7845,10 +7488,10 @@ void PQsetAuthDataHook(PQauthDataHook_type hook); int hook_fn(PGauthData type, PGconn *conn, void *data); - 当应用程序需要执行某个动作时,libpq会调用该回调。type描述所提出的请求,conn是正在认证的连接句柄,而data指向该请求特有的元数据。这个指针所指内容由type决定;支持的列表见。 + 当需要应用程序执行某个操作时,libpq会调用该回调。type描述所提出的请求,conn是正在认证的连接句柄,而data指向该请求特有的元数据。这个指针所指内容由type决定;支持的列表见 - 钩子可以串联起来,以支持协作式和/或回退式行为。一般来说,钩子实现应检查传入的type(以及可能的请求元数据和/或当前conn的设置),以决定是否处理某一项 authdata。如果不处理,则应把请求委托给链中的前一个钩子(可通过PQgetAuthDataHook获取)。 + 钩子可以串联起来,以支持协作和/或后备行为。一般来说,钩子实现应检查传入的type(以及可能的请求元数据和/或当前conn的设置),以决定是否处理某一项 authdata。如果不处理,则应把请求委托给链中的前一个钩子(可通过PQgetAuthDataHook获取)。 返回一个大于零的整数表示成功。返回负整数表示发生错误并放弃此次连接尝试。(值零保留给默认实现。) @@ -7891,23 +7534,23 @@ PQauthDataHook_type PQgetAuthDataHook(void); typedef struct _PGpromptOAuthDevice { - const char *verification_uri; /* verification URI to visit */ - const char *user_code; /* user code to enter */ - const char *verification_uri_complete; /* optional combination of URI and - * code, or NULL */ - int expires_in; /* seconds until user code expires */ + const char *verification_uri; /* 要访问的验证 URI */ + const char *user_code; /* 要输入的用户代码 */ + const char *verification_uri_complete; /* 可选的 URI 与代码组合, + * 或为 NULL */ + int expires_in; /* 距用户代码过期的秒数 */ } PGpromptOAuthDevice; - 可被包含在libpq中的 OAuth Device Authorization 流程要求最终用户使用浏览器访问一个 URL,然后输入一个代码,以允许libpq代表其连接到服务器。默认提示只是把verification_uriuser_code打印到标准错误。替换实现可以按任意偏好的方式展示这些信息,例如使用 GUI。 + 可被包含在libpq中的 OAuth 设备授权流程要求最终用户使用浏览器访问一个 URL,然后输入一个代码,以允许libpq代表其连接到服务器。默认提示只是把verification_uriuser_code打印到标准错误。替换实现可以按任意偏好的方式展示这些信息,例如使用 GUI。 该回调只会在内置设备授权流程中被调用。如果应用程序安装了自定义 OAuth 流程,或者libpq构建时未启用内置流程支持,则不会使用这种 authdata 类型。 - 如果提供了非空的verification_uri_complete,则可以选择把它用于非文本形式的验证(例如显示二维码)。在这种情况下,仍应向最终用户显示 URL 和用户代码,因为该代码需要由提供者手工确认,而 URL 也使得用户在无法使用非文本方式时仍可继续。更多信息见 - RFC 8628 第 3.3.1 节。 + 如果提供了不为 NULL 的verification_uri_complete,则可以选择把它用于非文本形式的验证(例如显示二维码)。在这种情况下,仍应向最终用户显示 URL 和用户代码,因为该代码需要由提供者手工确认,而 URL 也使得用户在无法使用非文本方式时仍可继续。更多信息见 + RFC 8628 第 3.3.1 节。
@@ -7921,7 +7564,7 @@ typedef struct _PGpromptOAuthDevice 适用于 PostgreSQL 18 及更高版本。 - 添加一个自定义流程实现;如果内置流程已安装,则用它替换内置流程。该钩子应当要么直接返回一个适用于当前 user/issuer/scope 组合的 Bearer 令牌(如果能在不阻塞的情况下获得),要么设置一个异步回调来获取令牌。 + 添加一个自定义流程实现;如果内置流程已安装,则用它替换内置流程。该钩子应当要么直接返回一个适用于当前用户、签发者及授权范围组合的 Bearer 令牌(如果能在不阻塞的情况下获得),要么设置一个异步回调来获取令牌。 @@ -7935,46 +7578,45 @@ typedef struct _PGpromptOAuthDevice typedef struct PGoauthBearerRequest { - /* Hook inputs (constant across all calls) */ - const char *openid_configuration; /* OIDC discovery URL */ - const char *scope; /* required scope(s), or NULL */ + /* 钩子输入(在所有调用中保持不变) */ + const char *openid_configuration; /* OIDC 发现 URL */ + const char *scope; /* 所需的授权范围,或为 NULL */ - /* Hook outputs */ + /* 钩子输出 */ /* - * Callback implementing a custom asynchronous OAuth flow. The signature is - * platform-dependent: PQ_SOCKTYPE is SOCKET on Windows, and int everywhere - * else. + * 实现自定义异步 OAuth 流程的回调。签名与平台有关: + * 在 Windows 上,PQ_SOCKTYPE 是 SOCKET;在其他平台上则为 int。 */ PostgresPollingStatusType (*async) (PGconn *conn, struct PGoauthBearerRequest *request, PQ_SOCKTYPE *altsock); - /* Callback to clean up custom allocations. */ + /* 清理自定义分配内存的回调。 */ void (*cleanup) (PGconn *conn, struct PGoauthBearerRequest *request); - char *token; /* acquired Bearer token */ - void *user; /* hook-defined allocated data */ + char *token; /* 获取的 Bearer 令牌 */ + void *user; /* 钩子定义并分配的数据 */ } PGoauthBearerRequest; - libpq会向该钩子提供两项信息:openid_configuration包含描述授权服务器所支持流程的 OAuth 发现文档 URL,而scope包含访问服务器所需的 OAuth scope 列表(以空格分隔,可以为空)。两者中的任意一个或两个都可能为NULL,表示无法发现该信息。(在这种情况下,实现可以通过其他预先配置的知识来确定要求,或者选择失败。) + libpq会向该钩子提供两项信息:openid_configuration包含描述授权服务器所支持流程的 OAuth 发现文档 URL,而scope包含访问服务器所需的 OAuth 授权范围列表(以空格分隔,可以为空)。两者中的任意一个或两个都可能为NULL,表示无法发现该信息。(在这种情况下,实现可以通过其他预先配置的知识来确定要求,或者选择失败。) - 该钩子的最终输出是token,它必须指向一个可在该连接上使用的有效 Bearer 令牌。(该令牌应由所指定的发行者签发,并持有所请求的 scope,否则连接会被服务器的验证器模块拒绝。)分配得到的令牌字符串必须在libpq完成连接之前始终有效;该钩子应设置cleanup回调,以便在libpq不再需要该令牌时调用。 + 该钩子的最终输出是token,它必须指向一个可在该连接上使用的有效 Bearer 令牌。(该令牌应由所指定的签发者签发,并持有所请求的授权范围,否则连接会被服务器的验证器模块拒绝。)分配得到的令牌字符串必须在libpq完成连接之前始终有效;该钩子应设置cleanup回调,以便在libpq不再需要该令牌时调用。 - 如果某个实现无法在首次调用钩子时立即产生token,则应设置async回调,以处理与授权服务器之间的非阻塞通信。 - + 如果实现在首次调用钩子时无法立即生成 token,应设置 async 回调,以处理与授权服务器之间的非阻塞通信。 + PQAUTHDATA_OAUTH_BEARER_TOKEN钩子回调中执行阻塞操作,会干扰诸如PQconnectPoll之类的非阻塞连接 API,并阻止并发连接继续推进。那些只使用同步连接原语(例如PQconnectdb)的应用程序,可以在钩子中同步获取令牌,而不是实现async回调,但这样它们必然一次只能处理一个连接。 - 从钩子返回后,将立即调用该回调以启动流程。当回调在不阻塞的情况下无法继续推进时,它应在设置*altsock后返回PGRES_POLLING_READINGPGRES_POLLING_WRITING,其中*altsock是当可以再次取得进展时会被标记为可读/可写的文件描述符。(然后,这个描述符会通过PQsocket()提供给顶层轮询循环。)当流程完成时,在设置好token之后返回PGRES_POLLING_OK;如果失败,则返回PGRES_POLLING_FAILED。 - +从钩子返回后,会立即调用该回调以启动流程。当回调无法在不阻塞的情况下继续时,应先将 *altsock 设为一个文件描述符,该描述符会在可以继续时被标记为可读或可写,然后返回 PGRES_POLLING_READINGPGRES_POLLING_WRITING。(该描述符随后会通过 PQsocket() 提供给顶层轮询循环。)流程完成时,应先设置 token,再返回 PGRES_POLLING_OK;返回 PGRES_POLLING_FAILED 表示失败。 +
- 实现可能希望在多次调用asynccleanup回调之间保存额外的数据用于记账。为此提供了user指针;libpq不会触碰其内容,应用程序可以按自己的需要使用它。(记得在令牌清理时释放相关分配。) + 实现可能希望在多次调用asynccleanup回调之间保存额外的数据用于记录状态。为此提供了user指针;libpq不会触碰其内容,应用程序可以按自己的需要使用它。(记得在令牌清理时释放相关分配。)
@@ -7996,13 +7638,13 @@ typedef struct PGoauthBearerRequest typedef struct { - PGoauthBearerRequest v1; /* see the PGoauthBearerRequest struct, above */ + PGoauthBearerRequest v1; /* 参见上面的 PGoauthBearerRequest 结构体 */ - /* Hook inputs (constant across all calls) */ - const char *issuer; /* the issuer identifier (RFC 9207) in use */ + /* 钩子输入(在所有调用中保持不变) */ + const char *issuer; /* 使用中的签发者标识符(RFC 9207) */ - /* Hook outputs */ - const char *error; /* hook-defined error message */ + /* 钩子输出 */ + const char *error; /* 钩子定义的错误消息 */ } PGoauthBearerRequestV2;
@@ -8010,23 +7652,23 @@ typedef struct 应用程序必须首先使用v1结构体成员来实现基础 API,如上面的 说明所述。 libpq还保证,传给v1.async和 - v1.cleanup回调的request指针可以安全地转换为 + v1.cleanup回调的request指针可以安全地强制转换为 (PGoauthBearerRequestV2 *),以便使用下面描述的附加成员。
- 只有当钩子类型为PQAUTHDATA_OAUTH_BEARER_TOKEN_V2时,才可以安全地转换为 + 只有当钩子类型为PQAUTHDATA_OAUTH_BEARER_TOKEN_V2时,才可以安全地强制转换为 (PGoauthBearerRequestV2 *)。如果钩子实现试图在处理 v1 (PQAUTHDATA_OAUTH_BEARER_TOKEN)请求时访问 v2 成员,应用程序可能会崩溃或表现异常。 - 除了 版本 1 API 的功能之外,v2 结构体还为该钩子提供了一个额外输入和一个额外输出: + 除版本 1 API 的功能外,v2 结构体还为该钩子提供了一个额外输入和一个额外输出: - issuer包含当前连接所使用的 签发者标识符(issuer identifier),定义见 + issuer包含当前连接所使用的签发者标识符(issuer identifier),定义见 RFC 9207。 - 该标识符来自。为避免 混淆攻击,自定义流程应确保授权服务器提供的任何发现元数据都与该 签发者 ID 一致。 + 该标识符来自。为避免混淆攻击,自定义流程应确保授权服务器提供的任何发现元数据都与该签发者 ID 一致。 当流程失败时,error可以被设置为指向一条自定义错误消息。 @@ -8071,7 +7713,7 @@ PGOAUTHDEBUG=UNSAFE 旧格式;启用所 http(危险) - 允许在 OAuth 提供者交换期间使用未加密的 HTTP。 + 允许在与 OAuth 提供者交互期间使用未加密的 HTTP。 这会让 OAuth 凭据通过未加密连接传输,极其危险,只应在本地测试时使用。 @@ -8141,7 +7783,7 @@ PGOAUTHDEBUG=UNSAFE:http,call-count 危险选项与安全选项 - 在线程化程序中的行为 + 多线程程序中的行为 线程 @@ -8180,7 +7822,7 @@ int PQisthreadsafe(); - 已废弃的函数不是线程安全的,不应在多线程程序中使用。可以用替代;可以用替代。 + 已弃用的函数 不是线程安全的,不应在多线程程序中使用。 可以用 替代; 可以用 替代。 @@ -8188,13 +7830,13 @@ int PQisthreadsafe(); - 同样地,如果你在应用程序中使用Curl,并且在启动新线程之前还没有先对 libcurl 进行全局初始化,那么你也需要通过PQregisterThreadLock协作地为任何可能初始化 libcurl 的代码加锁。对于支持线程安全初始化的较新版本Curl,这一限制已被解除;这类构建可以通过其版本元数据中声明的threadsafe特性识别出来。 + 同样地,如果你在应用程序中使用Curl并且在启动新线程之前还没有先对 libcurl 进行全局初始化,那么你也需要通过PQregisterThreadLock协作地为任何可能初始化 libcurl 的代码加锁。对于支持线程安全初始化的较新版本Curl,这一限制已被解除;这类构建可以通过其版本元数据中声明的threadsafe特性识别出来。 - 编译 <application>libpq</application> 程序 + 构建 <application>libpq</application> 程序 编译 @@ -8202,16 +7844,16 @@ int PQisthreadsafe(); - 要编译(即编译并且链接)一个使用libpq的程序,你需要做下列所有的事情: + 要构建(即编译和链接)一个使用 libpq 的程序,需要完成以下所有步骤: - 包括libpq-fe.h头文件: + 包含 libpq-fe.h 头文件: #include <libpq-fe.h> - 如果你无法这样做,那么你通常会从你的编译器得到像这样的错误消息: +如果没有这样做,编译器通常会给出类似以下内容的错误消息: foo.c: In function `main': foo.c:34: `PGconn' undeclared (first use in this function) @@ -8220,24 +7862,24 @@ foo.c:54: `CONNECTION_BAD' undeclared (first use in this function) foo.c:68: `PGRES_COMMAND_OK' undeclared (first use in this function) foo.c:95: `PGRES_TUPLES_OK' undeclared (first use in this function) - +
- 通过为你的编译器提供-Idirectory选项,向你的编译器指出PostgreSQL头文件安装在哪里(在某些情况下编译器默认将查看该目录,因此你可以忽略这个选项)。例如你的编译命令行可能看起来像: + 向编译器提供 -Idirectory 选项,指定 PostgreSQL 头文件的安装目录。(某些情况下,编译器默认会搜索该目录,此时可以省略这个选项。)例如,编译命令行可以是: cc -c -I/usr/local/pgsql/include testprog.c - 如果你在使用 makefile,那么把该选项加到CPPFLAGS变量中: +如果使用 makefile,请将该选项添加到 CPPFLAGS 变量中: CPPFLAGS += -I/usr/local/pgsql/include - +
如果你的程序可能由其他用户编译,那么你不应该像那样硬编码目录位置。你可以运行工具pg_configpg_configwith libpq在本地系统上找出头文件在哪里: + sortas="libpq">用于 libpq在本地系统上找出头文件在哪里: $ pg_config --includedir /usr/local/include @@ -8245,8 +7887,7 @@ CPPFLAGS += -I/usr/local/pgsql/include - 如果你安装了pkg-configpkg-configwith - libpq,你可以运行: + 如果你安装了pkg-configpkg-config用于 libpq,你可以运行: $ pkg-config --cflags libpq -I/usr/local/include @@ -8255,20 +7896,20 @@ CPPFLAGS += -I/usr/local/pgsql/include - 无法为编译器指定正确的选项将导致一个错误消息,例如: + 未向编译器指定正确的选项将导致类似以下内容的错误消息: testlibpq.c:8:22: libpq-fe.h: No such file or directory - +
- 当链接最终的程序时,指定选项-lpq,这样libpq库会被编译进去,也可以用选项-Ldirectory向编译器指出libpq库所在的位置(再次,编译器将默认搜索某些目录)。为了最大的可移植性,将选项放在选项前面。例如: + 链接最终程序时,指定 -lpq 选项以链接 libpq 库,同时指定 -Ldirectory 选项,告知编译器 libpq 库所在的目录。(同样,编译器默认会搜索某些目录。)为获得最大的可移植性,请将 选项放在 选项之前。例如: cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq - + 你也可以使用pg_config找出库目录: @@ -8295,7 +7936,7 @@ testlibpq.o(.text+0x60): undefined reference to `PQsetdbLogin' testlibpq.o(.text+0x71): undefined reference to `PQstatus' testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' - 这意味着你忘了 . + 这意味着你忘记了 /usr/bin/ld: cannot find -lpq @@ -8312,7 +7953,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' 示例程序 - 这些示例和其他示例可以在源代码发布的src/test/examples目录中找到。 + 这些示例和其他示例可在源代码发行包的src/test/examples目录中找到。 @@ -8327,7 +7968,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' * * testlibpq.c * - * Test the C version of libpq, the PostgreSQL frontend library. + * 测试 PostgreSQL 前端库 libpq 的 C 语言版本。 */ #include #include @@ -8351,26 +7992,25 @@ main(int argc, char **argv) j; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -8381,19 +8021,17 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Our test case here involves using a cursor, for which we must be inside - * a transaction block. We could do the whole thing with a single - * PQexec() of "SELECT * FROM pg_database", but that's too trivial to make - * a good example. + * 这里的测试用例使用游标,因此必须处于事务块内。 + * 只需调用一次 PQexec() 执行 "SELECT * FROM pg_database" 就能完成全部操作, + * 但这太简单了,不足以作为一个好的示例。 */ - /* Start a transaction block */ + /* 开始一个事务块 */ res = PQexec(conn, "BEGIN"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -8404,7 +8042,7 @@ main(int argc, char **argv) PQclear(res); /* - * Fetch rows from pg_database, the system catalog of databases + * 从数据库系统目录 pg_database 中获取行 */ res = PQexec(conn, "DECLARE myportal CURSOR FOR SELECT * FROM pg_database"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -8423,13 +8061,13 @@ main(int argc, char **argv) exit_nicely(conn); } - /* first, print out the attribute names */ + /* 首先,打印属性名 */ nFields = PQnfields(res); for (i = 0; i < nFields; i++) printf("%-15s", PQfname(res, i)); printf("\n\n"); - /* next, print out the rows */ + /* 接着,打印各行 */ for (i = 0; i < PQntuples(res); i++) { for (j = 0; j < nFields; j++) @@ -8439,15 +8077,15 @@ main(int argc, char **argv) PQclear(res); - /* close the portal ... we don't bother to check for errors ... */ + /* 关闭 portal……这里不再检查错误…… */ res = PQexec(conn, "CLOSE myportal"); PQclear(res); - /* end the transaction */ + /* 结束事务 */ res = PQexec(conn, "END"); PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -8467,15 +8105,15 @@ main(int argc, char **argv) * * * testlibpq2.c - * Test of the asynchronous notification interface + * 测试异步通知接口 * - * Start this program, then from psql in another window do + * 启动此程序,然后在另一个窗口中通过 psql 执行 * NOTIFY TBL2; - * Repeat four times to get this program to exit. + * 重复四次后,此程序便会退出。 * - * Or, if you want to get fancy, try this: - * populate a database with the following commands - * (provided in src/test/examples/testlibpq2.sql): + * 或者,可以尝试更复杂的示例: + * 使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq2.sql 中): * * CREATE SCHEMA TESTLIBPQ2; * SET search_path = TESTLIBPQ2; @@ -8484,7 +8122,7 @@ main(int argc, char **argv) * CREATE RULE r1 AS ON INSERT TO TBL1 DO * (INSERT INTO TBL2 VALUES (new.i); NOTIFY TBL2); * - * Start this program, then from psql do this four times: + * 启动此程序,然后通过 psql 将以下命令执行四次: * * INSERT INTO TESTLIBPQ2.TBL1 VALUES (10); */ @@ -8496,11 +8134,9 @@ main(int argc, char **argv) #include #include #include +#include #include #include -#ifdef HAVE_SYS_SELECT_H -#include -#endif #include "libpq-fe.h" @@ -8521,26 +8157,25 @@ main(int argc, char **argv) int nnotifies; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) @@ -8551,13 +8186,12 @@ main(int argc, char **argv) } /* - * Should PQclear PGresult whenever it is no longer needed to avoid memory - * leaks + * 不再需要 PGresult 时,应调用 PQclear 将其释放,以避免内存泄漏。 */ PQclear(res); /* - * Issue LISTEN command to enable notifications from the rule's NOTIFY. + * 发出 LISTEN 命令,以接收规则中的 NOTIFY 发出的通知。 */ res = PQexec(conn, "LISTEN TBL2"); if (PQresultStatus(res) != PGRES_COMMAND_OK) @@ -8568,14 +8202,13 @@ main(int argc, char **argv) } PQclear(res); - /* Quit after four notifies are received. */ + /* 收到四次通知后退出。 */ nnotifies = 0; while (nnotifies < 4) { /* - * Sleep until something happens on the connection. We use select(2) - * to wait for input, but you could also use poll() or similar - * facilities. + * 休眠,直到连接上有事件发生。这里使用 select(2) 等待输入, + * 也可以使用 poll() 或类似机制。 */ int sock; fd_set input_mask; @@ -8583,7 +8216,7 @@ main(int argc, char **argv) sock = PQsocket(conn); if (sock < 0) - break; /* shouldn't happen */ + break; /* 不应发生 */ FD_ZERO(&input_mask); FD_SET(sock, &input_mask); @@ -8594,7 +8227,7 @@ main(int argc, char **argv) exit_nicely(conn); } - /* Now check for input */ + /* 现在检查是否有输入 */ PQconsumeInput(conn); while ((notify = PQnotifies(conn)) != NULL) { @@ -8609,7 +8242,7 @@ main(int argc, char **argv) fprintf(stderr, "Done.\n"); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; @@ -8629,10 +8262,10 @@ main(int argc, char **argv) * * * testlibpq3.c - * Test out-of-line parameters and binary I/O. + * 测试在 SQL 命令文本之外独立传递的参数和二进制 I/O。 * - * Before running this, populate a database with the following commands - * (provided in src/test/examples/testlibpq3.sql): + * 运行前,使用以下命令填充数据库 + * (这些命令位于 src/test/examples/testlibpq3.sql 中): * * CREATE SCHEMA testlibpq3; * SET search_path = testlibpq3; @@ -8640,7 +8273,7 @@ main(int argc, char **argv) * INSERT INTO test1 values (1, 'joe''s place', '\000\001\002\003\004'); * INSERT INTO test1 values (2, 'ho there', '\004\003\002\001\000'); * - * The expected output is: + * 预期输出为: * * tuple 0: got * i = (4 bytes) 1 @@ -8664,7 +8297,7 @@ main(int argc, char **argv) #include #include "libpq-fe.h" -/* for ntohl/htonl */ +/* 用于 ntohl/htonl */ #include #include @@ -8677,9 +8310,8 @@ exit_nicely(PGconn *conn) } /* - * This function prints a query result that is a binary-format fetch from - * a table defined as in the comment above. We split it out because the - * main() function uses it twice. + * 此函数打印从上面注释所定义的表中以二进制格式获取的查询结果。 + * 由于 main() 会使用它两次,因此将它单独提取成一个函数。 */ static void show_binary_results(PGresult *res) @@ -8690,7 +8322,7 @@ show_binary_results(PGresult *res) t_fnum, b_fnum; - /* Use PQfnumber to avoid assumptions about field order in result */ + /* 使用 PQfnumber,以避免对结果中的字段顺序作出假设 */ i_fnum = PQfnumber(res, "i"); t_fnum = PQfnumber(res, "t"); b_fnum = PQfnumber(res, "b"); @@ -8703,24 +8335,22 @@ show_binary_results(PGresult *res) int blen; int ival; - /* Get the field values (we ignore possibility they are null!) */ + /* 获取字段值(这里忽略它们可能为 null 的情况!) */ iptr = PQgetvalue(res, i, i_fnum); tptr = PQgetvalue(res, i, t_fnum); bptr = PQgetvalue(res, i, b_fnum); /* - * The binary representation of INT4 is in network byte order, which - * we'd better coerce to the local byte order. + * INT4 的二进制表示采用网络字节序,最好将其转换为本机字节序。 */ ival = ntohl(*((uint32_t *) iptr)); /* - * The binary representation of TEXT is, well, text, and since libpq - * was nice enough to append a zero byte to it, it'll work just fine - * as a C string. + * TEXT 的二进制表示就是文本,而 libpq 会在其后追加一个零字节, + * 因此可以直接将其用作 C 字符串。 * - * The binary representation of BYTEA is a bunch of bytes, which could - * include embedded nulls so we have to pay attention to field length. + * BYTEA 的二进制表示是一组字节,其中可能嵌有零字节, + * 因此必须注意字段长度。 */ blen = PQgetlength(res, i, b_fnum); @@ -8748,26 +8378,25 @@ main(int argc, char **argv) uint32_t binaryIntVal; /* - * If the user supplies a parameter on the command line, use it as the - * conninfo string; otherwise default to setting dbname=postgres and using - * environment variables or defaults for all other connection parameters. + * 如果用户在命令行上提供了一个参数,就将其用作 conninfo 字符串; + * 否则默认设置 dbname=postgres,并对所有其他连接参数使用环境变量或默认值。 */ if (argc > 1) conninfo = argv[1]; else conninfo = "dbname = postgres"; - /* Make a connection to the database */ + /* 连接数据库 */ conn = PQconnectdb(conninfo); - /* Check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SET search_path = testlibpq3"); if (PQresultStatus(res) != PGRES_COMMAND_OK) { @@ -8778,27 +8407,25 @@ main(int argc, char **argv) PQclear(res); /* - * The point of this program is to illustrate use of PQexecParams() with - * out-of-line parameters, as well as binary transmission of data. + * 此程序旨在演示如何使用 PQexecParams() 在 SQL 命令文本之外独立传递参数, + * 以及如何以二进制方式传输数据。 * - * This first example transmits the parameters as text, but receives the - * results in binary format. By using out-of-line parameters we can avoid - * a lot of tedious mucking about with quoting and escaping, even though - * the data is text. Notice how we don't have to do anything special with - * the quote mark in the parameter value. + * 第一个示例以文本形式传输参数,但以二进制格式接收结果。 + * 通过在 SQL 命令文本之外独立传递参数,即使数据是文本,也可以避免 + * 许多繁琐的引号和转义处理。注意,参数值中的引号无需任何特殊处理。 */ - /* Here is our out-of-line parameter value */ + /* 这是在 SQL 命令文本之外独立传递的参数值 */ paramValues[0] = "joe's place"; res = PQexecParams(conn, "SELECT * FROM test1 WHERE t = $1", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, - NULL, /* don't need param lengths since text */ - NULL, /* default to all text params */ - 1); /* ask for binary results */ + NULL, /* 文本参数无需指定长度 */ + NULL, /* 默认所有参数均为文本 */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -8812,31 +8439,29 @@ main(int argc, char **argv) PQclear(res); /* - * In this second example we transmit an integer parameter in binary form, - * and again retrieve the results in binary form. + * 第二个示例以二进制形式传输一个整数参数,并同样以二进制形式获取结果。 * - * Although we tell PQexecParams we are letting the backend deduce - * parameter type, we really force the decision by casting the parameter - * symbol in the query text. This is a good safety measure when sending - * binary parameters. + * 虽然我们告诉 PQexecParams 让后端推断参数类型,但实际上, + * 查询文本中的参数符号经过强制类型转换,因此其类型已经确定。 + * 发送二进制参数时,这是一项良好的安全措施。 */ - /* Convert integer value "2" to network byte order */ + /* 将整数值 "2" 转换为网络字节序 */ binaryIntVal = htonl((uint32_t) 2); - /* Set up parameter arrays for PQexecParams */ + /* 为 PQexecParams 设置参数数组 */ paramValues[0] = (char *) &binaryIntVal; paramLengths[0] = sizeof(binaryIntVal); - paramFormats[0] = 1; /* binary */ + paramFormats[0] = 1; /* 二进制 */ res = PQexecParams(conn, "SELECT * FROM test1 WHERE i = $1::int4", - 1, /* one param */ - NULL, /* let the backend deduce param type */ + 1, /* 一个参数 */ + NULL, /* 让后端推断参数类型 */ paramValues, paramLengths, paramFormats, - 1); /* ask for binary results */ + 1); /* 请求二进制结果 */ if (PQresultStatus(res) != PGRES_TUPLES_OK) { @@ -8849,7 +8474,7 @@ main(int argc, char **argv) PQclear(res); - /* close the connection to the database and cleanup */ + /* 关闭数据库连接并清理 */ PQfinish(conn); return 0; diff --git a/zh/20/lobj.sgml b/zh/20/lobj.sgml index 82d63771..6922fa91 100644 --- a/zh/20/lobj.sgml +++ b/zh/20/lobj.sgml @@ -3,8 +3,8 @@ 大对象 - large object - BLOBlarge object + 大对象 + BLOB大对象 PostgreSQL提供一种大对象机制,允许以流式方式访问存储在专用大对象结构中的用户数据。在处理大到无法方便地整体操作的数据值时,这种流式访问非常有用。 @@ -19,7 +19,7 @@ TOAST - versus large objects + 与大对象对比 @@ -190,11 +190,11 @@ inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE); int lo_write(PGconn *conn, int fd, const char *buf, size_t len); - 将buf中的len字节(其大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 + 将buf中的len字节(缓冲区大小必须为len)写入大对象描述符fdfd参数必须是先前由lo_open返回的大对象描述符。返回值是实际写入的字节数(在当前实现中,除非出错,否则它总会等于len)。发生错误时,返回值为 -1。 - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -211,7 +211,7 @@ int lo_read(PGconn *conn, int fd, char *buf, size_t len); - 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,无论如何最好按每块最多几兆字节来传输数据。 + 虽然len参数被声明为size_t,但该函数会拒绝大于INT_MAX的长度值。实际上,最好按每块最多几兆字节来传输数据。 @@ -277,7 +277,7 @@ int64_t lo_tell64(PGconn *conn, int fd); int lo_truncate(PGconn *conn, int fd, size_t len); - 该函数把大对象描述符fd截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用空字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 + 该函数把大对象描述符fd对应的大对象截断为长度lenfd参数必须是先前由lo_open返回的大对象描述符。如果len大于大对象当前的长度,则会用零字节('\0')把该大对象扩展到指定长度。成功时,lo_truncate返回零;出错时返回值为 -1。 @@ -426,16 +426,16 @@ CREATE TABLE image ( raster oid ); -SELECT lo_creat(-1); -- returns OID of new, empty large object +SELECT lo_creat(-1); -- 返回新建的空大对象的 OID -SELECT lo_create(43213); -- attempts to create large object with OID 43213 +SELECT lo_create(43213); -- 尝试创建 OID 为 43213 的大对象 -SELECT lo_unlink(173454); -- deletes large object with OID 173454 +SELECT lo_unlink(173454); -- 删除 OID 为 173454 的大对象 INSERT INTO image (name, raster) VALUES ('beautiful image', lo_import('/etc/motd')); -INSERT INTO image (name, raster) -- same as above, but specify OID to use +INSERT INTO image (name, raster) -- 与上例相同,但指定要使用的 OID VALUES ('beautiful image', lo_import('/etc/motd', 68583)); SELECT lo_export(image.raster, '/tmp/motd') FROM image @@ -444,7 +444,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image - 服务器端的lo_importlo_export函数与其客户端对应函数的行为差异很大。这两个函数在服务器的文件系统中读写文件,使用数据库所有者的权限。因此,默认情况下它们的使用仅限于超级用户。相比之下,客户端导入和导出函数在客户端的文件系统中读写文件,使用客户端程序的权限。客户端函数不需要任何数据库权限,除了读取或写入相关大对象所需的权限。 + 服务器端的lo_importlo_export函数与其客户端对应函数的行为差异很大。这两个函数在服务器的文件系统中读写文件,使用运行数据库服务器的操作系统用户的权限。因此,默认情况下它们的使用仅限于超级用户。相比之下,客户端导入和导出函数在客户端的文件系统中读写文件,使用客户端程序的权限。客户端函数不需要任何数据库权限,除了读取或写入相关大对象所需的权限。 @@ -463,7 +463,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image 示例程序 - 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行版的src/test/examples/testlo.c中找到。 + 是一个示例程序,它展示了如何使用libpq中的大对象接口。程序中有些部分已经被注释掉,但仍保留在源代码中供读者参考。该程序也可以在源代码发行包的src/test/examples/testlo.c中找到。 @@ -472,13 +472,13 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /*----------------------------------------------------------------- * * testlo.c - * test using large objects with libpq + * 测试使用 libpq 操作大对象 * * Portions Copyright (c) 1996-2026, PostgreSQL Global Development Group * Portions Copyright (c) 1994, Regents of the University of California * * - * IDENTIFICATION + * 标识 * src/test/examples/testlo.c * *----------------------------------------------------------------- @@ -498,7 +498,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image /* * importFile - - * import file "in_filename" into database as large object "lobjOid" + * 将文件 "in_filename" 作为大对象 "lobjOid" 导入数据库 * */ static Oid @@ -512,16 +512,16 @@ importFile(PGconn *conn, char *filename) int fd; /* - * open the file to be read in + * 打开要读取的文件 */ fd = open(filename, O_RDONLY, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"\n", filename); } /* - * create the large object + * 创建大对象 */ lobjId = lo_creat(conn, INV_READ | INV_WRITE); if (lobjId == 0) @@ -530,7 +530,7 @@ importFile(PGconn *conn, char *filename) lobj_fd = lo_open(conn, lobjId, INV_WRITE); /* - * read in from the Unix file and write to the inversion file + * 从 Unix 文件读取数据并写入大对象 */ while ((nbytes = read(fd, buf, BUFSIZE)) > 0) { @@ -568,7 +568,7 @@ pickout(PGconn *conn, Oid lobjId, int start, int len) fprintf(stderr, ">>> %s", buf); nread += nbytes; if (nbytes <= 0) - break; /* no more data? */ + break; /* 没有更多数据? */ } free(buf); fprintf(stderr, "\n"); @@ -614,7 +614,7 @@ overwrite(PGconn *conn, Oid lobjId, int start, int len) /* * exportFile - - * export large object "lobjOid" to file "out_filename" + * 将大对象 "lobjOid" 导出到文件 "out_filename" * */ static void @@ -627,24 +627,24 @@ exportFile(PGconn *conn, Oid lobjId, char *filename) int fd; /* - * open the large object + * 打开大对象 */ lobj_fd = lo_open(conn, lobjId, INV_READ); if (lobj_fd < 0) fprintf(stderr, "cannot open large object %u", lobjId); /* - * open the file to be written to + * 打开要写入的文件 */ fd = open(filename, O_CREAT | O_WRONLY | O_TRUNC, 0666); if (fd < 0) - { /* error */ + { /* 错误 */ fprintf(stderr, "cannot open unix file\"%s\"", filename); } /* - * read in from the inversion file and write to the Unix file + * 从大对象读取数据并写入 Unix 文件 */ while ((nbytes = lo_read(conn, lobj_fd, buf, BUFSIZE)) > 0) { @@ -689,18 +689,18 @@ main(int argc, char **argv) out_filename = argv[3]; /* - * set up the connection + * 建立连接 */ conn = PQsetdb(NULL, NULL, NULL, NULL, database); - /* check to see that the backend connection was successfully made */ + /* 检查是否已成功建立到后端的连接 */ if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "%s", PQerrorMessage(conn)); exit_nicely(conn); } - /* Set always-secure search path, so malicious users can't take control. */ + /* 设置始终安全的搜索路径,防止恶意用户取得控制权。 */ res = PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)"); if (PQresultStatus(res) != PGRES_TUPLES_OK) diff --git a/zh/20/logicaldecoding.sgml b/zh/20/logicaldecoding.sgml index c1df90aa..26b087b9 100644 --- a/zh/20/logicaldecoding.sgml +++ b/zh/20/logicaldecoding.sgml @@ -602,8 +602,7 @@ DETAIL: Synchronization could lead to data loss, because the remote slot needs binary (boolean) - 启用二进制传输模式。二进制模式比文本模式更快,但稳健性略差。默认值 - 为 off。 + 启用二进制传输模式。二进制模式比文本模式更快,但稳健性略差。默认值为 off @@ -631,8 +630,7 @@ DETAIL: Synchronization could lead to data loss, because the remote slot needs 当设置为 on 时, - pgoutput 会流式传输大型进行中事务。这要求协议 - 版本为 2 或更高。 + pgoutput 会流式传输大型进行中事务。这要求协议版本为 2 或更高。 当设置为 parallel 时, @@ -655,9 +653,7 @@ DETAIL: Synchronization could lead to data loss, because the remote slot needs origin (enum) - 指定是否按来源发送更改。可选值包括 none,仅发送 - 没有关联来源的更改;以及 any,不论其来源为何都 - 发送更改。这可用于避免复制节点之间出现环路(同一数据的无限复制)。 + 指定是否按来源发送更改。可选值包括 none,仅发送没有关联来源的更改;以及 any,不论其来源为何都发送更改。这可用于避免复制节点之间出现环路(同一数据的无限复制)。 默认值为 any diff --git a/zh/20/monitoring.sgml b/zh/20/monitoring.sgml index 84fbe1ac..15bd77c1 100644 --- a/zh/20/monitoring.sgml +++ b/zh/20/monitoring.sgml @@ -3492,7 +3492,7 @@ description | Waiting for a newly initialized WAL file to reach durable storage checksum_failures bigint - 在此数据库(或共享对象)中检测到的数据页校验和失败数。即使 设置发生变化,已检测到的失败也不会被重置。未启用数据校验和初始化的集簇会显示为 0。在 PostgreSQL 18 及更早版本中,对于未启用数据校验和的集簇,此值为 NULL。 + 在此数据库(或共享对象)中检测到的数据页校验和失败次数。即使 设置发生变化,已检测到的失败也不会被重置。未启用数据校验和初始化的集簇会显示为 0。在 PostgreSQL 18 及更早版本中,对于未启用数据校验和的集簇,此值为 NULL @@ -3501,7 +3501,7 @@ description | Waiting for a newly initialized WAL file to reach durable storage checksum_last_failure timestamp with time zone - 在此数据库(或共享对象)中检测到最后一个数据页校验和失败的时间。无论 设置如何,都会报告最近一次失败。 + 在此数据库(或共享对象)中最后一次检测到数据页校验和失败的时间。无论 设置如何,都会报告最近一次失败。 diff --git a/zh/20/oauth-validators.sgml b/zh/20/oauth-validators.sgml index 713ac140..8a354740 100644 --- a/zh/20/oauth-validators.sgml +++ b/zh/20/oauth-validators.sgml @@ -80,27 +80,27 @@ 接下来,验证器必须确保终端用户已授权客户端代表其访问服务器。 - 这通常需要检查分配给令牌的作用域(scope), + 这通常需要检查分配给令牌的授权范围, 以确认其覆盖当前 HBA 参数所要求的数据库访问权限。 该步骤的目的是防止 OAuth 客户端在虚假前提下获取令牌。 - 如果验证器要求所有令牌都必须携带覆盖数据库访问的作用域, + 如果验证器要求所有令牌都必须携带覆盖数据库访问的授权范围, 提供方在流程中就应明确提示用户授予该访问权限。 这样一来,如果客户端本不应使用其凭据连接数据库, 用户就有机会拒绝该请求。 - 也可以通过部署架构的带外知识在没有显式作用域的情况下完成客户端授权, + 也可以通过部署架构的带外知识在没有显式授权范围的情况下完成客户端授权, 但这样会让用户无法参与授权过程, 用户将无法发现部署错误,而此类错误也可能被静默利用。 - 如果不提示用户授予额外作用域, + 如果不提示用户授予额外授权范围, 则对数据库的访问必须被严格限制为仅允许受信任客户端 即,“受信任”是指 OAuth 客户端与 PostgreSQL 服务器由同一实体控制。 - 特别地,libpq 支持的 Device Authorization 客户端流程通常不满足此条件, + 特别地,libpq 支持的设备授权客户端流程通常不满足此条件, 因为它的设计目标是公开/非受信任客户端。 @@ -252,7 +252,7 @@ 若要完全绕过用户名映射,并让验证器模块承担额外的用户连接授权职责, 可在 HBA 中配置 。 - 此后模块可使用令牌作用域或等效方法判断用户是否允许以其期望角色连接。 + 此后模块可使用令牌授权范围或等效方法判断用户是否允许以其期望角色连接。 用户标识符仍会由服务器记录,但它不再参与是否继续连接的判定。 diff --git a/zh/20/pgtrgm.sgml b/zh/20/pgtrgm.sgml index 09cc6fe5..fa60934c 100644 --- a/zh/20/pgtrgm.sgml +++ b/zh/20/pgtrgm.sgml @@ -513,11 +513,11 @@ SELECT * FROM test_trgm WHERE t ~ '(foo|bar)'; - 文本搜索集成 + 文本检索集成 与全文索引结合使用时,三字符组匹配是非常有用的工具。 - 尤其是,它有助于识别那些因拼写错误而无法被全文搜索机制直接匹配的输入词。 + 尤其是,它有助于识别那些因拼写错误而无法被全文检索机制直接匹配的输入词。 diff --git a/zh/20/protocol.sgml b/zh/20/protocol.sgml index 52f82551..1b3a2214 100644 --- a/zh/20/protocol.sgml +++ b/zh/20/protocol.sgml @@ -26,15 +26,15 @@ 概述 - 协议在启动和正常操作过程中有不同的阶段。在启动阶段里,前端打开一个到服务器的连接并且认证自身以满足服务器(这可能涉及到一条或多条消息,取决于使用的认证方法)。 如果一切正常,服务器就发送状态信息给前端,并最后进入正常操作。除了最初的启动请求消息之外,协议的这个部分是服务器驱动的。 + 协议分为启动和正常操作两个阶段。在启动阶段,前端打开到服务器的连接,并完成服务器所要求的认证。(这可能只涉及一条消息,也可能因所用认证方法不同而需要多条消息。)如果一切顺利,服务器随后会向前端发送状态信息,并最终进入正常操作。除最初的启动请求消息外,协议的这一部分由服务器驱动。 - 在正常操作中,前端发送查询和其它命令到后端,然后后端返回查询结果和其它响应。在少数几种情况(比如NOTIFY)中,后端会发送未被请求的消息,但这个会话中的绝大多部分都是由前端请求驱动的。 + 在正常操作中,前端向后端发送查询及其他命令,后端则返回查询结果和其他响应。少数情况下(例如 NOTIFY),后端会发送未请求的消息,但会话中的绝大多数交互仍由前端请求驱动。 - 会话的终止通常是由前端来选择的,但是也可以在某些情况下由后端强制执行。不管在那种情况下,如果后端关闭连接,那么它将在退出之前回滚所有打开的(未完成的)事务。 + 会话通常由前端选择终止,但在某些情况下也可能由后端强制终止。无论哪种情况,后端关闭连接时,都会在退出前回滚所有打开的(未完成的)事务。 @@ -73,9 +73,7 @@ 整个执行周期包括一个解析步骤,它从文本查询字符串创建预备语句; 一个绑定步骤,它根据预备语句和所需参数值创建 portal; - 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询 - (SELECTSHOW等),可以要求执行步骤只取回 - 有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 + 以及一个执行步骤,用于执行 portal 中的查询。对于返回行的查询(SELECTSHOW等),可以要求执行步骤只取回有限数量的行,因此可能需要多次执行步骤才能完成整个操作。 @@ -92,8 +90,8 @@ - 文本形式的数值是特定数据类型的输入/输出转换函数生成或接受的任何字符串。在传输形式上,字符串没有末尾空字符;如果前端要想把收到的值当作C字符串处理,那么必须自己加上一个(顺便说一下,文本格式不允许嵌入空字符)。 - + 值的文本表示是相应数据类型的输入/输出转换函数生成和接受的字符串。在传输形式中,值的末尾没有空字符;前端若要将收到的值作为 C 字符串处理,必须自行添加一个。(文本格式也不允许内嵌空字符。) + 整数的二进制表示采用网络字节序(最高有效字节在前)。至于其他数据类型,请查阅文档或源代码了解其二进制表示形式。要注意,复杂数据类型的二进制表示可能会在不同服务器版本之间发生变化;文本格式通常是可移植性更好的选择。 @@ -135,7 +133,7 @@ 3.2 PostgreSQL 18 及以后 - 当前最新版本。用于取消查询的 secret key 从 4 字节扩展为可变长度字段;BackendKeyData 与 CancelRequest 消息相应调整为可变长度负载。 + 当前最新版本。用于取消查询的密钥从 4 字节扩展为可变长度字段。BackendKeyData 消息已作相应调整,CancelRequest 消息则重新定义为使用可变长度负载。 @@ -166,7 +164,7 @@ 3.1 - - 保留。PostgreSQL 从未使用 3.1;之所以跳过该版本,是因为旧版 pgbouncer 在协议协商中存在缺陷,会错误宣称支持 3.1。 + 保留。PostgreSQL 从未使用 3.1;之所以跳过该版本,是因为广泛使用的 pgbouncer 的旧版本在协议协商中存在缺陷,会错误宣称支持 3.1。 2.0 @@ -252,7 +250,7 @@ 启动 - 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地请求协议扩展,并包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,判断该连接在初步上是否可接受,以及是否需要额外的认证。 + 要开始一个会话,前端会打开到服务器的连接并发送一条启动消息。该消息包含用户名以及用户希望连接的数据库名;它还指明要使用的协议版本。(启动消息也可以选择性地请求协议扩展,并包含运行时参数的附加设置。)随后服务器会结合这些信息以及配置文件(例如 pg_hba.conf)的内容,初步判断是否接受该连接,以及需要何种额外认证(如果需要)。 @@ -499,7 +497,7 @@ 表示即将返回行作为对SELECTFETCH等查询的响应。 - 此消息的内容描述了行的列布局。这将跟随每个返回给前端的行的DataRow消息。 + 此消息的内容描述了行的列布局。该消息之后,每个返回给前端的行都对应一条 DataRow 消息。 @@ -555,9 +553,7 @@ - - 对 SELECT 查询(或其他返回行集的查询,如 EXPLAINSHOW)的响应,通常包含 RowDescription、零条或多条 DataRow 消息,以及最后的 CommandComplete。向前端 COPY 或从前端 COPY 会调用中描述的特殊协议。所有其他类型的查询通常只产生一条 CommandComplete 消息。 - + SELECT 查询(或其他返回行集的查询,如 EXPLAINSHOW)的响应通常包含 RowDescription、零条或多条 DataRow 消息,以及最后的 CommandComplete。在前端与服务器之间执行 COPY 输入或输出时,会使用 所述的特殊协议。所有其他类型的查询通常只产生一条 CommandComplete 消息。 由于查询字符串可能包含若干条查询(以分号分隔),因此在后端完成整个查询字符串的处理之前,可能会出现多个这样的响应序列。只有在整个字符串处理完毕且后端已准备好接受新的查询字符串时,才会发出 ReadyForQuery 消息。 @@ -580,15 +576,15 @@ - 我们建议的方法是把前端代码写成状态机的风格,它可以在任何时刻接受任何有意义的消息类型,而不是假设消息的序列总是准确。 - + 建议以状态机的方式编写前端,使其能够在任何合理的时机接收相应类型的消息,而不把消息确切顺序的假设写死在代码中。 + 一个简单查询中的多条语句 - 当一个简单查询消息中包含多于一条SQL语句(被分号分隔)时,那些语句会被当做一个事务中执行,除非其中包括显式事务控制命令来强制不同的行为。例如,如果消息包括 + 当一个简单查询消息中包含多于一条SQL语句(被分号分隔)时,这些语句会作为单个事务执行,除非其中包括显式事务控制命令来强制不同的行为。例如,如果消息包括 INSERT INTO mytable VALUES(1); SELECT 1/0; @@ -610,15 +606,15 @@ SELECT 1/0; - 这种行为通过在一个隐式事务块中的一个多语句Query消息中运行那些语句来实现,除非它们运行在某个显式事务块中。隐式事务块与常规事务块之间的区别在于隐式块会在Query消息结束时自动被关闭,或者是在没有错误的情况下由一个隐式提交关闭,或者是在有错误时由一个隐式的回滚关闭。这类似于一个语句自己执行(当不在事务块中时)时发生的隐式提交或回滚。 - + 这种行为的实现方式是:除非已有显式事务块可供这些语句执行,否则就在一个隐式事务块中执行多语句 Query 消息中的语句。隐式事务块与常规事务块的主要区别在于,隐式块会在 Query 消息结束时自动关闭:没有错误时隐式提交,发生错误时隐式回滚。这类似于单独执行一条语句(不在事务块中)时发生的隐式提交或回滚。 + - 如果会话已经在一个事务块中,作为前面某个消息中BEGIN的结果,那么Query消息会简单地继续那个事务块,不管该消息包含一个语句还是多个语句。不过,如果该Query消息包含一个关闭现有事务块的COMMIT或者ROLLBACK,那么任何接下来的语句都会在一个隐式事务块中被执行。反过来,如果在多语句Query消息中出现一个BEGIN,那么它会开始一个常规事务块,这个常规事务块将只能被一个显式的COMMIT或者ROLLBACK终止,不管这两种命令是出现在这个Query消息还是后面的一个Query消息中。如果BEGIN跟在一些作为隐式事务块执行的语句后面,那些语句不会被立刻提交。实际上,它们会被包括到新的常规事务块中。 + 如果会话因前面某条消息中的BEGIN而已经处于事务块中,那么 Query 消息会继续该事务块,不管该消息包含一个语句还是多个语句。不过,如果该Query消息包含一个关闭现有事务块的COMMIT或者ROLLBACK,那么任何接下来的语句都会在一个隐式事务块中被执行。反过来,如果在多语句Query消息中出现一个BEGIN,那么它会开始一个常规事务块,这个常规事务块将只能被一个显式的COMMIT或者ROLLBACK终止,不管这两种命令是出现在这个Query消息还是后面的一个Query消息中。如果BEGIN跟在一些作为隐式事务块执行的语句后面,那些语句不会被立刻提交。实际上,它们会被包括到新的常规事务块中。 - 出现在一个隐式事务块中的COMMIT或者ROLLBACK会被正常执行并且关闭该隐式块。不过,由于没有先前的BEGIN配对的COMMIT或者ROLLBACK表示一种错误,所以将会发出一个警告。如果后面还有更多语句,将会为它们开始一个新的隐式事务块。 + 出现在一个隐式事务块中的COMMIT或者ROLLBACK会被正常执行并且关闭该隐式块。不过,由于没有先前的BEGIN配对的COMMIT或者ROLLBACK可能表示误操作,所以会发出警告。如果后面还有更多语句,将会为它们开始一个新的隐式事务块。 @@ -626,17 +622,17 @@ SELECT 1/0; - 记住,不管任何事务控制命令存不存在,Query消息的执行会在第一个错误时停止。因此,对于下面的在一个Query消息中的示例 + 请记住,无论消息中是否包含事务控制命令,Query 消息的执行都会在第一个错误处停止。例如,单条 Query 消息包含以下内容时: BEGIN; SELECT 1/0; ROLLBACK; - 会话中将留下一个失败的常规事务块,因为在出现除零错误后不会到达ROLLBACK。将需要另一个ROLLBACK把会话恢复到一种可用的状态。 - +会话会停留在失败的常规事务块内,因为发生除零错误后不会再执行ROLLBACK。需要另发一条ROLLBACK,才能将会话恢复到可用状态。 + - 另一种要注意的行为是,最初的词法和语法分析是在整个查询字符串被执行之前进行的。因此后面的语句中的简单错误(例如拼写错误的关键词)可能会阻止任何语句的执行。这通常对用户是不可见的,因为在当作一个隐式事务块执行时,这些语句不管怎样都会全部被回滚。不过,在尝试于一个多语句Query中执行多个事务时,这种现象可能是可见的。例如,如果一个拼写错误把我们之前的示例变成 + 另一种要注意的行为是,在执行任何语句之前,会先对整个查询字符串进行词法和语法分析。因此后面的语句中的简单错误(例如拼写错误的关键词)可能会阻止任何语句的执行。这通常对用户是不可见的,因为在当作一个隐式事务块执行时,这些语句不管怎样都会全部被回滚。不过,在尝试于一个多语句Query中执行多个事务时,这种现象可能是可见的。例如,如果一个拼写错误把我们之前的示例变成 BEGIN; INSERT INTO mytable VALUES(1); @@ -703,11 +699,11 @@ SELCT 1/0; - 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是执行不会导致后端发送 ReadyForQuery 或 RowDescription。 + 一旦 portal 存在,就可以使用 Execute 消息执行它。Execute 消息指定 portal 的名称(空字符串表示未命名 portal)以及一个最大的结果行计数(零表示取回全部行)。结果行计数只对包含返回行集命令的 portal 有意义;在其他情况下,命令总会执行到完成,而行计数会被忽略。Execute 的可能响应与通过简单查询协议发出的查询相同,只是 Execute 不会导致后端发送 ReadyForQuery 或 RowDescription。 - 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息之一结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 + 如果 Execute 在 portal 执行完成之前终止(因为达到了非零的结果行计数),它会发送一条 PortalSuspended 消息;该消息表明前端应当针对同一个 portal 再发出一条 Execute 消息,以完成此次操作。在 portal 执行完成之前,不会发送表示源 SQL 命令结束的 CommandComplete 消息。因此,一个 Execute 阶段总会以下列消息中的恰好一条结束:CommandComplete、EmptyQueryResponse(如果 portal 是从空查询字符串创建的)、ErrorResponse 或 PortalSuspended。 @@ -722,7 +718,7 @@ SELCT 1/0; - 除了这些基本的、必须的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 + 除了这些基本的、必需的操作之外,在扩展查询协议里还有几种可选的操作可以使用。 @@ -758,38 +754,32 @@ SELCT 1/0; - 流水线处理 + 管道化 - 流水线处理 + 管道化 协议规范 - 使用扩展查询协议允许流水线处理,这意味着发送一系列查询而无需等待先前的查询完成。 - 这减少了完成一系列操作所需的网络往返次数。然而,用户必须仔细考虑所需的行为,如果其中一步失败, - 因为后续查询已经在传输到服务器的过程中。 - + 扩展查询协议允许管道化,即连续发送一系列查询,而不等待先前查询完成。这减少了完成一组操作所需的网络往返次数。不过,用户必须仔细考虑其中某个步骤失败时所需的行为,因为后续查询已经在发往服务器的途中。 + - 处理这个问题的一种方法是将整个查询系列作为一个事务处理,即将其包装在BEGIN... - COMMIT中。然而,如果希望其中一些命令独立于其他命令提交,这并没有帮助。 - + 处理这个问题的一种方式是让整组查询成为单个事务,即用BEGIN ... COMMIT包围它们。不过,如果希望其中某些命令独立于其他命令提交,这种方式就无法满足要求。 + - 扩展查询协议提供了另一种管理这个问题的方式,即在依赖的步骤之间省略发送同步消息。 - 由于在错误后,后端会跳过命令消息直到找到同步消息,这允许在管道中的后续命令在前面的命令失败时自动跳过,而无需客户端明确地使用BEGINCOMMIT来管理。 - 管道中可以通过同步消息分隔独立可提交的段。 - + 扩展查询协议提供了另一种处理方式,即省略相互依赖的步骤之间的 Sync 消息。发生错误后,后端会跳过命令消息,直到遇到 Sync,因此当前面的命令失败时,管道中的后续命令便会自动跳过,而不必由客户端用BEGINCOMMIT显式管理。管道中可独立提交的各段可以用 Sync 消息分隔。 + 如果客户端没有发出显式 BEGIN,则会启动一个隐式事务块。每个 Sync 通常会在前序步骤成功时导致隐式 COMMIT,失败时导致隐式 ROLLBACK。服务器只有在第一个命令结束且尚未收到 Sync 时,才能识别这种隐式事务块。有一些 DDL 命令(例如 CREATE DATABASE)不能在事务块内执行;若这类命令在管道中执行,除非它是某个 Sync 之后的第一条命令,否则会失败。此外,它成功后会强制立即提交以保持数据库一致性。因此,紧随这些命令之后的 Sync 除了返回 ReadyForQuery 外不会产生额外效果。 - 当使用这种方法时,必须通过计算ReadyForQuery消息的数量并等待达到发送的Syncs数量来确定管道的完成。 - 计算命令完成响应是不可靠的,因为其中一些命令可能会被跳过,因此不会产生完成消息。 - + 使用这种方式时,必须统计 ReadyForQuery 消息的数量,并等待该数量达到已发送的 Sync 消息数量,才能确定管道已完成。统计命令完成响应并不可靠,因为某些命令可能被跳过,因而不会产生完成消息。 + @@ -797,8 +787,8 @@ SELCT 1/0; 函数调用 - 函数调用子协议允许客户端请求一个对存在于数据库pg_proc系统表中的任意函数的直接调用。客户端必须在该函数上有执行的权限。 - + 函数调用子协议允许客户端请求直接调用数据库pg_proc系统目录中的任意函数。客户端必须具有该函数的执行权限。 + @@ -808,8 +798,8 @@ SELCT 1/0; - 一个函数调用周期是由前端向后端发送一条FunctionCall消息初始化的。然后后端根据函数调用的结果发送一条或者更多响应消息,并且最后是一条ReadyForQuery响应消息。ReadyForQuery通知前端它可以安全地发送一个新的查询或者函数调用了。 - + 函数调用周期由前端向后端发送一条 FunctionCall 消息来启动。后端随后根据函数调用的结果发送一条或多条响应消息,最后发送一条 ReadyForQuery 响应消息。ReadyForQuery 告知前端,可以安全地发送新的查询或函数调用。 + 来自后端的可能的响应消息是: @@ -828,7 +818,7 @@ SELCT 1/0; FunctionCallResponse - 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者集合类型的结果)。 + 函数调用完成并且在消息中返回一个结果(请注意函数调用协议只能处理单个标量结果,不能处理行类型或者结果集合)。 @@ -863,7 +853,7 @@ SELCT 1/0; - 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(表示成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 + 拷贝入模式(向服务器传输数据)在后端执行COPY FROM STDIN SQL 语句时启动。后端会向前端发送一条 CopyInResponse 消息。随后前端应发送零条或多条 CopyData 消息,构成一条输入数据流。(消息边界与行边界之间没有任何对应关系要求,尽管让它们对齐通常是合理的选择。)前端可以通过发送 CopyDone 消息来结束拷贝入模式(允许成功结束),也可以发送 CopyFail 消息(这会使COPY语句以错误失败)。然后后端会恢复到COPY开始之前的命令处理模式,也就是简单查询协议或扩展查询协议。接下来它会发送 CommandComplete(成功时)或 ErrorResponse(失败时)。 @@ -871,11 +861,11 @@ SELCT 1/0; - 在拷贝入模式下,后端将忽略所收到的Flush和Sync消息。收到任何其他非拷贝消息类型都会造成一个错误,它将导致上面所描述的拷贝入状态中断(Flush和Sync的例外是为了方便客户端库,它们总是在一个Execute消息之后发送Flush和Sync,而不检查被执行的命令是否为一个COPY FROM STDIN)。 - + 后端会忽略在拷贝入模式期间收到的 Flush 和 Sync 消息。收到任何其他非拷贝类型的消息都会构成错误,并按上述方式中止拷贝入状态。(Flush 和 Sync 的例外是为了方便那些总是在 Execute 消息之后发送 Flush 或 Sync、而不检查待执行命令是否为COPY FROM STDIN的客户端库。) + - 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句的时候初始化的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能退出传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 + 拷贝出模式(数据从服务器发出)是在后端执行一个COPY TO STDOUT语句时启动的。后端发出一个CopyOutResponse消息给前端,后面跟着零或者多个CopyData消息(总是每行一个),然后跟着CopyDone。然后后端回退到它在COPY开始之前的命令处理模式,然后发送CommandComplete。前端不能中止传输(除非是关闭连接或者发出一个Cancel请求),但是它可以抛弃不需要的CopyData和CopyDone消息。 @@ -883,16 +873,16 @@ SELCT 1/0; - 在CopyData消息中间可能会散布有NoticeResponse和ParameterStatus消息。前端必须处理这些情况,并且应该也为异步消息类型(参见)准备好。否则任何除CopyData或CopyDone之外的消息类型都会被认为是要中止拷贝出模式。 - + NoticeResponse 和 ParameterStatus 消息可能穿插在 CopyData 消息之间;前端必须处理这些情况,并应准备好处理其他异步消息类型(参见)。除此之外,可以将任何除 CopyData 或 CopyDone 以外的消息类型视为拷贝出模式的终止标志。 + - 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许数据以高速批量方式在客户端与服务器之间双向传输。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见。 + 还有另一种与拷贝相关的模式,称为双向拷贝(copy-both),它允许高速批量地向服务器发送数据以及从服务器接收数据。当处于 walsender 模式的后端执行START_REPLICATION语句时,会启动双向拷贝模式。后端会向前端发送一条 CopyBothResponse 消息。此后,前端和后端都可以发送 CopyData 消息,直到任一方发送 CopyDone 消息。客户端发送 CopyDone 后,连接会从双向拷贝模式切换到拷贝出模式,客户端也不得再发送 CopyData。类似地,当服务器发送 CopyDone 后,连接会进入拷贝入模式,服务器也不得再发送 CopyData。当双方都发送完 CopyDone 后,拷贝模式结束,后端恢复到原先的命令处理模式。如果双向拷贝模式期间发生后端检测到的错误,后端会发出 ErrorResponse,丢弃前端消息直到收到 Sync,然后发出 ReadyForQuery 并返回正常处理。前端应将收到 ErrorResponse 视为双向拷贝终止的信号;在这种情况下不应再发送 CopyDone。关于在双向拷贝模式上传输的子协议,见 - CopyInResponse、CopyOutResponse和CopyBothResponse消息包括域和格式代码,域告诉前端每行的列数,而格式代码则用于具体每个列(就目前的实现而言,一个给定COPY操作中的所有列都将使用同样的格式,但是消息设计并不做这个假设)。 - + CopyInResponse、CopyOutResponse 和 CopyBothResponse 消息包含一些字段,用于告知前端每行的列数以及每列所使用的格式代码。(在当前实现中,同一次COPY操作的所有列都使用相同格式,但消息设计并不作此假设。) + @@ -936,8 +926,8 @@ SELCT 1/0; - 如果前端发出一个LISTEN命令, 那么无论何时在为同一个通道名NOTIFY时,后端将发送一个NotificationResponse消息(不要和NoticeResponse搞混!)。 - + 如果前端发出LISTEN命令,那么每当针对同一通道名执行NOTIFY命令时,后端都会发送一条 NotificationResponse 消息(不要与 NoticeResponse 混淆)。 + @@ -956,11 +946,11 @@ SELCT 1/0; - 要发出一条取消请求,前端打开一个与服务器的新连接并且发送一条CancelRequest消息, 而不是通常在新连接中经常发送的StartupMessage消息。服务器将处理这个请求然后关闭连接。 出于安全原因,对取消请求消息不做直接的响应。 - + 要发出取消请求,前端会新建到服务器的连接,并发送 CancelRequest 消息,而不是新连接通常发送的 StartupMessage 消息。服务器处理该请求后便会关闭连接。出于安全原因,服务器不会直接回复取消请求消息。 + - 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的关键数据(PID和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则退出当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 + 除非CancelRequest消息包含在连接启动过程中传递给前端的相同的密钥数据(PID 和密钥),否则它将被忽略。如果该请求匹配当前运行着的后端的PID和密钥, 则中止当前查询的处理(目前的实现里采用的方法是向正在处理该查询的后端进程发送一个特殊的信号)。 @@ -968,7 +958,7 @@ SELCT 1/0; - 这么做是对安全性和有效性通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 + 这么做是对安全性和效率通盘考虑的结果,前端没有直接的方法获知一个取消请求是否成功。它必须继续等待后端对查询响应。发出一个取消仅仅是增加了当前查询快些结束的可能性, 同时也增加了当前查询会伴随着一条错误消息失败而不是成功执行的可能性。 @@ -989,11 +979,11 @@ SELCT 1/0; - 其他终止场景来自各种故障,例如任一端发生内核转储、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 + 其他终止场景来自各种故障,例如任一端发生 core dump、通信链路中断、消息边界同步丢失等。如果前端或后端看到连接意外关闭,就应清理并终止。若前端不想自行终止,也可以重新联系服务器以启动一个新的后端。如果收到无法识别的消息类型,同样建议关闭连接,因为这通常意味着消息边界同步已经丢失。 - 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果很可能在得知断开之前被提交。 + 不管是正常还是不正常的终止,任何打开的事务都会回滚而不是提交。不过,我们应该注意的是如果一个前端在一个非SELECT查询正在处理的时候断开, 那么后端很可能在发现断开之前先完成查询的处理。如果查询处于任何事务块之外(BEGIN ... COMMIT序列),那么其结果可能在发现连接断开之前被提交。 @@ -1007,32 +997,32 @@ SELCT 1/0; 要发起一条使用SSL加密的连接,前端首先发送 SSLRequest 消息,而不是 StartupMessage。随后服务器会响应一个包含SN的单字节,分别表示它愿意或不愿意执行SSL加密。如果前端对该响应不满意,此时可以关闭连接。若要在收到S后继续,就先与服务器完成SSL启动握手(这里不做描述,它属于SSL规范的一部分)。如果成功,再继续发送通常的 StartupMessage。在这种情况下,StartupMessage 以及后续所有数据都会被SSL加密。若要在收到N后继续,则发送通常的 StartupMessage,并在不使用加密的情况下继续。 - (另外,可以在 N 响应之后发出 GSSENCRequest 消息,尝试使用 GSSAPI 加密代替 SSL。) + (另外,可以在 N 响应之后发出 GSSENCRequest 消息,尝试使用 GSSAPI 加密代替 SSL。) - 前端也应准备处理服务器对 SSLRequest 返回的 ErrorMessage。前端不应将该错误直接展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 SSL 的情况下继续。 + 前端也应准备处理服务器对 SSLRequest 返回的 ErrorMessage。前端不应将该错误展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 SSL 的情况下继续。 - 当可以执行 SSL 加密时,服务器预计仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给他们的 SSL 库,要么在发现他们已经读取到额外的字节时将其视为协议违规。 + 当可以执行 SSL 加密时,服务器应仅发送单个 S 字节,然后等待前端启动 SSL 握手。如果此时有其他可读取的字节,则很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应该编写代码,要么从套接字中恰好读取一个字节,然后将套接字交给所用的 SSL 库,要么在发现已经读取到额外的字节时将其视为协议违规。 - 同样,服务器也期望客户端在收到服务器对 SSLRequest 的单字节响应之后,再开始SSL协商。如果客户端不等服务器响应到达就立即开始SSL协商,可以减少一次网络往返时延;但代价是无法处理服务器对SSL请求返回否定响应的情况。在这种情况下,服务器通常会直接断开连接,而不会继续回退到 GSSAPI、未加密连接或协议错误流程。 + 同样,服务器也期望客户端在收到服务器对SSL请求的单字节响应之后,再开始SSL协商。如果客户端不等服务器响应到达就立即开始SSL协商,可以减少一次网络往返时延;但代价是无法处理服务器对SSL请求返回否定响应的情况。在这种情况下,服务器会直接断开连接,而不会继续使用 GSSAPI 或未加密连接,也不会返回协议错误。 - 初始 SSLRequest 也可以用于那些正在建立、目的是发送 CancelRequest 消息的连接。 - + 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 SSLRequest。 + - 还支持第二种发起SSL加密的方式:客户端可以在不发送任何 SSLRequest 包的情况下,直接开始SSL协商。SSL连接建立后,服务器会在加密通道上继续等待普通的启动请求包并继续协商。在这种情况下,任何其他的加密请求都会被拒绝。这种方法不适合通用工具,因为它既不能协商出最佳的连接加密方式,也不能处理未加密连接;但在客户端和服务器都由同一方控制的环境中,它很有用,因为它可以减少一次往返时延,并允许使用依赖标准SSL连接的网络工具。使用这种风格的SSL连接时,客户端必须使用由 RFC 7301 定义的 ALPN 扩展,以防范协议混淆攻击。PostgreSQL 协议对应的 ALPN 标识是 postgresql,见 IANA TLS ALPN Protocol IDs 注册表。 + 还支持第二种发起SSL加密的方式:服务器能识别未发送任何 SSLRequest 包就立即开始SSL协商的连接。SSL连接建立后,服务器会在加密通道上继续等待普通的启动请求包并继续协商。在这种情况下,任何其他的加密请求都会被拒绝。这种方法不是通用工具的首选,因为它既不能协商出最佳的连接加密方式,也不能处理未加密连接;但在客户端和服务器都由同一方控制的环境中,它很有用,因为它可以减少一次往返时延,并允许使用依赖标准SSL连接的网络工具。使用这种风格的SSL连接时,客户端必须使用由 RFC 7301 定义的 ALPN 扩展,以防范协议混淆攻击。PostgreSQL 协议对应的 ALPN 标识是 postgresql,见 IANA TLS ALPN Protocol IDs 注册表。 - 虽然协议本身并不提供让服务器强制启用SSL加密的方法,但管理员可以把服务器配置为拒绝未加密会话,把它作为认证检查的一个副作用。 - + 虽然协议本身没有提供让服务器强制使用SSL加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + @@ -1043,37 +1033,27 @@ SELCT 1/0; 如果PostgreSQL构建时启用了GSSAPI支持,就可以使用GSSAPI对前端/后端通信进行加密。这为攻击者可能截获会话流量的环境提供了通信安全性。有关使用GSSAPI加密PostgreSQL会话的详细信息,请参阅。 - - 要启动一个GSSAPI加密连接,前端最初发送一个GSSENCRequest消息,而不是一个StartupMessage。 - 服务器随后会响应一个包含GN的单个字节,分别表示愿意或不愿意执行GSSAPI加密。 - 如果前端对响应不满意,可能会在此时关闭连接。 - 要在G之后继续,使用GSSAPI C绑定,如在RFC 2744 - 中讨论的,或等效的,通过在循环中调用gss_init_sec_context()来执行GSSAPI初始化, - 并将结果发送给服务器,从一个空输入开始,然后对每个来自服务器的结果进行处理,直到不再返回输出为止。 - 在将gss_init_sec_context()的结果发送给服务器时,在消息前加上以网络字节顺序表示的四字节整数的长度。 - 要在N之后继续,发送通常的StartupMessage,并在没有加密的情况下继续进行。 - (或者,可以在N响应后发出一个SSLRequest消息,尝试使用SSL加密代替GSSAPI。) - + 要建立 GSSAPI 加密连接,前端首先发送 GSSENCRequest 消息,而不是 StartupMessage。服务器随后以单个字节响应,内容为 GN,分别表示愿意或不愿意使用 GSSAPI 加密。如果前端对响应不满意,可以在此时关闭连接。收到 G 后要继续,应使用 RFC 2744 中介绍的 GSSAPI C 绑定或等效接口,在循环中调用 gss_init_sec_context() 来执行 GSSAPI 初始化,并将结果发送给服务器:先使用空输入,再依次使用服务器返回的每个结果,直到该调用不再产生输出。将 gss_init_sec_context() 的结果发送给服务器时,应在前面加上消息长度,以网络字节序的四字节整数表示。收到 N 后要继续,则发送通常的 StartupMessage,以不加密的方式继续。(也允许在收到 N 响应后发送 SSLRequest 消息,尝试使用 SSL 加密代替 GSSAPI。) - 前端也应准备处理服务器对 GSSENCRequest 返回的 ErrorMessage。前端不应将该错误直接展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 GSSAPI 加密的情况下继续。 + 前端也应准备处理服务器对 GSSENCRequest 返回的 ErrorMessage。前端不应将该错误展示给用户/应用,因为此时服务器尚未完成认证(CVE-2024-10977)。遇到这种情况必须关闭连接,但前端可以选择重新建立连接并在不请求 GSSAPI 加密的情况下继续。 - 当GSSAPI加密可用时,服务器预计只发送单个G字节,然后等待前端启动GSSAPI握手。此时如果还有其他可读字节,很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应编写代码,要么从套接字中恰好读取一个字节后再把套接字交给其 GSSAPI 库,要么在发现自己已经读到额外字节时将其视为协议违规。 + 当GSSAPI加密可用时,服务器应只发送单个G字节,然后等待前端启动GSSAPI握手。此时如果还有其他可读字节,很可能意味着中间人正在尝试执行缓冲区填充攻击(CVE-2021-23222)。前端应编写代码,要么从套接字中恰好读取一个字节后再把套接字交给其 GSSAPI 库,要么在发现自己已经读到额外字节时将其视为协议违规。 - 初始 GSSENCRequest 也可用于那些正在建立、目的是发送 CancelRequest 消息的连接。 - + 如果建立连接是为了发送 CancelRequest 消息,也可以先发送 GSSENCRequest。 + 一旦成功建立GSSAPI加密连接,就应使用gss_wrap()加密通常的 StartupMessage 以及后续所有数据,并在实际加密负载前附上gss_wrap()结果长度,该长度以网络字节序的四字节整数表示。请注意,服务器只接受来自客户端、长度小于 16kB 的加密数据包。客户端应使用gss_wrap_size_limit()确定符合该限制的未加密消息大小,较大的消息则应拆分为多次gss_wrap()调用。典型分段是 8kB 的未加密数据,对应得到略大于 8kB 但明显小于 16kB 的加密数据包。通常可以认为,服务器不会向客户端发送大于 16kB 的加密数据包。 - 虽然协议本身并不为服务器提供强制启用GSSAPI加密的方法,但管理员可以把服务器配置为拒绝未加密会话,把它作为认证检查的一个副作用。 - + 虽然协议本身没有提供让服务器强制使用GSSAPI加密的方法,但管理员可以配置服务器,使其在认证检查中拒绝未加密的会话。 + @@ -1099,25 +1079,22 @@ SELCT 1/0; - 客户端从列表中选择一个支持的机制,并向服务器发送一个SASLInitialResponse消息。 - 该消息包括所选机制的名称,以及如果所选机制使用的话,还包括一个可选的初始客户端响应。 - + 客户端从列表中选择一种受支持的机制,并向服务器发送 SASLInitialResponse 消息。消息包含所选机制的名称;如果该机制使用初始客户端响应,消息还可以包含这一可选响应。 + - 一个或多个服务器挑战和客户端响应消息将随后而来。每个服务器挑战都是在一个 - AuthenticationSASLContinue 消息中发送的,随后是客户端在一个 SASLResponse - 消息中的响应。这些消息的具体内容是特定于机制的。 - + 随后会进行一轮或多轮服务器挑战和客户端响应。每次服务器挑战都通过 AuthenticationSASLContinue 消息发送,随后客户端通过 SASLResponse 消息响应。消息的具体内容取决于所用机制。 + - 最后,当认证交换成功完成时,服务器会发送可选的 AuthenticationSASLFinal 消息,随后立即发送 AuthenticationOk。AuthenticationSASLFinal 包含机制特定的附加数据;若该机制不需要完成时附加数据,则不会发送 AuthenticationSASLFinal。 - + 最后,认证交换成功完成时,服务器会发送可选的 AuthenticationSASLFinal 消息,紧接着发送 AuthenticationOk 消息。AuthenticationSASLFinal 包含从服务器发给客户端的附加数据,其具体内容取决于所选认证机制。如果该认证机制不使用在完成时发送的附加数据,则不会发送 AuthenticationSASLFinal 消息。 + @@ -1143,31 +1120,22 @@ SELCT 1/0; - SCRAM规范规定密码也必须是UTF-8编码,并且使用SASLprep算法处理。 - 然而,PostgreSQL不要求密码必须使用UTF-8编码。 - 当用户设置密码时,无论实际使用的编码是什么,都会像使用UTF-8一样使用SASLprep进行处理。 - 但是,如果密码不是合法的UTF-8字节序列,或者包含SASLprep算法禁止的UTF-8字节序列, - 则会使用原始密码而不进行SASLprep处理,而不是抛出错误。这样可以在密码为UTF-8时对其进行规范化, - 但仍允许使用非UTF-8密码,并且不需要系统知道密码使用的编码方式。 - + SCRAM 规范规定密码也必须采用 UTF-8 编码,并通过SASLprep算法处理。不过,PostgreSQL并不要求密码使用 UTF-8。设置用户密码时,无论实际采用何种编码,都会将其视作 UTF-8 并用 SASLprep 处理。但是,如果密码不是合法的 UTF-8 字节序列,或者包含 SASLprep 算法禁止的 UTF-8 字节序列,就会直接使用未经 SASLprep 处理的原始密码,而不抛出错误。这样既能对 UTF-8 密码进行规范化,又允许使用非 UTF-8 密码,而且不要求系统知道密码采用何种编码。 + - Channel binding在支持SSL的PostgreSQL构建中受支持。带有通道绑定的SCRAM的SASL机制名称是 + 通道绑定在支持SSL的PostgreSQL构建中受支持。带有通道绑定的SCRAM的SASL机制名称是 SCRAM-SHA-256-PLUS。PostgreSQL使用的通道绑定类型是 tls-server-end-point - 在没有通道绑定的SCRAM中,服务器选择一个随机数, - 传输给客户端,与用户提供的密码在传输的密码哈希中混合。虽然这可以 - 防止密码哈希在后续会话中被成功重新传输,但无法阻止真实服务器和客 - 户端之间的虚假服务器通过服务器的随机值并成功进行认证。 - + 在不带通道绑定的SCRAM中,服务器会选择一个随机数并发送给客户端,将它与用户提供的密码混合,形成所传输的密码 hash。虽然这样可以防止在后续会话中成功重放该密码 hash,但无法阻止位于真实服务器与客户端之间的伪造服务器转发服务器的随机值并成功通过认证。 + - SCRAM与通道绑定一起防止这种中间人攻击,通过将服务器证书的签名混合到传输的密码哈希中。 - 虽然伪造服务器可以重新传输真实服务器的证书,但它无法访问与该证书匹配的私钥,因此无法证明自己是所有者,导致SSL连接失败。 - + 带通道绑定的SCRAM会将服务器证书的签名混入所传输的密码 hash,从而防止此类中间人攻击。虽然伪造服务器可以转发真实服务器的证书,但它无法取得与证书匹配的私钥,因此无法证明自己是证书所有者,最终导致 SSL 连接失败。 + @@ -1220,63 +1188,75 @@ SELCT 1/0; OAUTHBEARER 认证 - OAUTHBEARER 是一种基于令牌的联合认证机制,详见 - RFC 7628。 - + OAUTHBEARER 是一种基于令牌的联合认证机制。其详细说明见 RFC 7628。 + - 典型交互取决于客户端是否已经为当前用户缓存 bearer token。若没有,通常会经历两次连接:第一次“发现连接”用于从服务器获取 OAuth 元数据,第二次连接在客户端拿到 token 后再发送 token。(libpq 当前内置流程尚未实现缓存,因此使用两连接流程。) - + 典型交互取决于客户端是否已为当前用户缓存 Bearer 令牌。如果没有,交互将通过两次连接完成:第一次“发现”连接从服务器获取 OAuth 元数据,第二次连接在客户端取得令牌后发送该令牌。(libpq 的内置流程目前没有实现缓存方法,因此使用两次连接的交互方式。) + - 该机制与 SCRAM 一样由客户端发起。客户端初始响应由 SCRAM 使用的标准 GS2 头部加上一组 key=value 对组成。当前服务器仅支持 auth 键(即 bearer token)。OAUTHBEARER 还定义了三个可选组成(GS2 头部中的 authzid,以及 host/port),当前服务器会忽略它们。 - + 该机制与 SCRAM 一样由客户端发起。客户端初始响应由 SCRAM 使用的标准“GS2”头部以及随后的一组 key=value 对组成。服务器目前唯一支持的键是 auth,其中包含 Bearer 令牌。OAUTHBEARER 还规定了客户端初始响应的三个可选部分:GS2 头部的 authzid,以及 hostport 键;服务器目前会忽略它们。 + - OAUTHBEARER 不支持通道绑定,因此不存在 “OAUTHBEARER-PLUS”。该机制在成功认证时不使用额外服务器数据,所以不会使用 AuthenticationSASLFinal 消息。 - + OAUTHBEARER 不支持通道绑定,也不存在“OAUTHBEARER-PLUS”机制。该机制在成功认证期间不使用服务器数据,因此交互中不使用 AuthenticationSASLFinal 消息。 + 示例 - 第一次交互时,服务器发送 AuthenticationSASL,并在机制列表中声明 OAUTHBEARER。 - + 第一次交互期间,服务器发送 AuthenticationSASL 消息,并声明支持 OAUTHBEARER 机制。 + + - 客户端发送 SASLInitialResponse 并选择 OAUTHBEARER。若尚无可用 token,则 auth 为空,表示这是发现连接。 - + 客户端发送 SASLInitialResponse 消息作为响应,在其中指定 OAUTHBEARER 机制。假定客户端尚未持有当前用户的有效 Bearer 令牌,则 auth 字段为空,表示这是发现连接。 + + - 服务器发送 AuthenticationSASLContinue,包含错误 status、well-known URI 以及客户端应使用的 scopes。 - + 服务器发送 AuthenticationSASLContinue 消息,其中包含错误 status、well-known URI,以及客户端执行 OAuth 流程时应使用的授权范围。 + + - 客户端发送 SASLResponse,内容为空集合(单个 0x01 字节),结束发现阶段的客户端半程。 - + 客户端发送包含空集合(单个 0x01 字节)的 SASLResponse 消息,以结束发现交互中由客户端完成的部分。 + + - 服务器发送 ErrorMessage,使第一次交互失败。随后客户端按配置和服务器提供的元数据执行 OAuth 流程以获取 token。(具体获取方式由客户端实现决定,OAUTHBEARER 不强制规定。) - + 服务器发送 ErrorMessage,使第一次交互失败。 + + + 此时,客户端会执行多种可用 OAuth 流程中的一种,以获取 Bearer 令牌;所使用的元数据包括客户端已配置的元数据,以及服务器提供的元数据。(此处的描述有意保持宽泛;OAUTHBEARER 不指定也不强制要求采用任何特定的令牌获取方法。) + + + 取得令牌后,客户端会重新连接服务器,进行最后一次交互: + + - 客户端拿到 token 后重新连接;服务器再次发送 AuthenticationSASL,并声明 OAUTHBEARER。 - + 服务器再次发送 AuthenticationSASL 消息,并声明支持 OAUTHBEARER 机制。 + + - 客户端再次发送 SASLInitialResponse,这次在 auth 中携带 bearer token。 - + 客户端发送 SASLInitialResponse 消息作为响应,但这次消息中的 auth 字段包含客户端流程取得的 Bearer 令牌。 + + - 服务器按令牌提供方规则校验 token。若客户端被授权连接,服务器发送 AuthenticationOk,认证完成。 - + 服务器按照令牌提供者的说明验证令牌。如果客户端获准连接,服务器便发送 AuthenticationOk 消息,结束 SASL 交互。 + @@ -1303,16 +1283,15 @@ SELCT 1/0; - 为了测试复制命令,可以通过psql或任何其他使用连接字符串且包含replication选项的libpq工具建立复制连接, - 例如: + 为了测试复制命令,可以通过 psql 或其他使用 libpq 的工具建立复制连接,连接字符串中应包含 replication 选项,例如: psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 然而,更常用的是使用(用于物理复制)或(用于逻辑复制)。 - +不过,通常更有用的做法是使用 (用于物理复制)或 (用于逻辑复制)。 + - 复制命令在服务器日志中记录,当启用时。 + 启用 后,复制命令会记录到服务器日志中。 @@ -1322,7 +1301,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" IDENTIFY_SYSTEM - 识别系统 + IDENTIFY_SYSTEM @@ -1358,9 +1337,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" xlogpos (text) - - 当前 WAL 刷新位置。用于获得预写式日志中的一个已知位置,以便从该处开始流式传输。 - + 当前 WAL 刷盘位置。可用于获取预写式日志中一个已知的位置,以便从该处开始流式传输。 @@ -1412,10 +1389,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 请求服务器发送时间线历史文件以获取时间线tli。 - 服务器回复一行结果集,包含两个字段。虽然这些字段被标记为text, - 但它们实际上返回原始字节,没有编码转换: - + 请求服务器发送时间线 tli 的历史文件。服务器返回一个包含两个字段的单行结果集。虽然这些字段标记为 text,但实际返回的是原始字节,不进行编码转换: + @@ -1496,12 +1471,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果为 true,则该逻辑复制槽支持两阶段提交的解码。使用此选项后,与两阶段提交相关的命令,如 - PREPARE TRANSACTIONCOMMIT PREPARED - 和ROLLBACK PREPARED将被解码和传输。 - 事务将在PREPARE TRANSACTION时解码和传输。 - 默认值为false。 - + 如果为 true,则该逻辑复制槽支持对两阶段提交进行解码。使用此选项后,PREPARE TRANSACTIONCOMMIT PREPAREDROLLBACK PREPARED 等两阶段提交命令会被解码并传输。事务会在 PREPARE TRANSACTION 时解码并传输。默认值为 false。 + @@ -1510,10 +1481,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果为 true,则该物理复制槽会立即保留WAL。 - 否则,WAL仅在从流复制客户端连接时保留。 - 默认值为false。 - + 如果为 true,则该物理复制槽会立即保留 WAL。否则,只有在流复制客户端连接时才会保留 WAL。默认值为 false。 + @@ -1597,8 +1566,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 修改复制槽定义。参见 。当前仅支持逻辑复制槽。 - + 修改复制槽的定义。有关复制槽的更多信息,参见 。此命令目前仅支持逻辑复制槽。 + slot_name @@ -1615,8 +1584,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" TWO_PHASE [ boolean ] - 若为 true,则该逻辑复制槽支持两阶段提交解码。与两阶段提交相关的命令(如 PREPARE TRANSACTIONCOMMIT PREPAREDROLLBACK PREPARED)会被解码并发送;事务在 PREPARE TRANSACTION 时解码并发送。 - + 如果为 true,则该逻辑复制槽支持对两阶段提交进行解码。使用此选项后,PREPARE TRANSACTIONCOMMIT PREPAREDROLLBACK PREPARED 等两阶段提交命令会被解码并传输。事务会在 PREPARE TRANSACTION 时解码并传输。 + @@ -1625,8 +1594,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" FAILOVER [ boolean ] - 若为 true,则该复制槽会同步到备库,从而在故障切换后恢复逻辑复制。 - + 如果为 true,则允许该复制槽同步到备库,以便在故障切换后恢复逻辑复制。 + @@ -1637,14 +1606,13 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" READ_REPLICATION_SLOT slot_name - 读取复制槽 + READ_REPLICATION_SLOT - 读取与复制槽相关的一些信息。如果复制槽不存在,则返回一个包含NULL值的元组。 - 当前仅支持物理复制槽的此命令。 - + 读取与复制槽关联的一些信息。如果复制槽不存在,则返回包含 NULL 值的元组。此命令目前仅支持物理复制槽。 + 在响应此命令时,服务器将返回一个包含以下字段的单行结果集: @@ -1671,8 +1639,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" restart_tliint8 - 与restart_lsn相关联的时间线ID,遵循当前时间线历史。 - + 根据当前时间线的历史,与 restart_lsn 对应的时间线 ID。 + @@ -1684,35 +1652,29 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" START_REPLICATION [ SLOT slot_name ] [ PHYSICAL ] XXX/XXX [ TIMELINE tli ] - 开始复制 + START_REPLICATION - 指示服务器开始流式传输WAL,从WAL位置XXX/XXX开始。 - 如果指定了TIMELINE选项,则流式传输将从时间线tli开始; - 否则,将选择服务器当前的时间线。如果请求的WAL部分已经被回收,服务器可能会回复错误。 - 成功时,服务器将用CopyBothResponse消息回复,然后开始向前端流式传输WAL。 - + 指示服务器从 WAL 位置 XXX/XXX 开始流式传输 WAL。如果指定了 TIMELINE 选项,则从时间线 tli 开始传输;否则选择服务器当前的时间线。服务器可以返回错误,例如请求的 WAL 部分已被回收时。成功时,服务器返回 CopyBothResponse 消息,然后开始向前端流式传输 WAL。 + - 如果通过slot_name提供了复制槽名称, - 那么在复制进行期间会更新该复制槽,以便服务器知道哪些 WAL 段, - 以及在启用了 hot_standby_feedback 时,哪些事务 - 仍然被备库所需要。 - + 如果通过 slot_name 提供了复制槽名称,该复制槽会随着复制的进行而更新,使服务器知道备库仍需要哪些 WAL 段,以及在启用 hot_standby_feedback 时仍需要哪些事务。 + - 如果客户端请求的 timeline 不是最新的,但属于服务器历史的一部分,服务器会从请求的起点开始流式传输该 timeline 上的全部 WAL,直到服务器切换到另一个 timeline 的位置为止。如果客户端请求的位置正好是旧 timeline 的末尾,服务器将完全跳过 COPY 模式。 - + 如果客户端请求的时间线不是最新时间线,但属于服务器的历史,服务器会从请求的起点开始,流式传输该时间线上的所有 WAL,直到服务器切换到另一条时间线的位置。如果客户端请求的流式传输起点恰好位于旧时间线的末尾,服务器会完全跳过 COPY 模式。 + 在非最新时间线上流式传输完全部 WAL 后,服务器会通过退出 COPY 模式来结束流式传输。当客户端也通过退出 COPY 模式来确认时,服务器会发送一个包含一行两列的结果集,指示该服务器历史中的下一条时间线。第一列是下一条时间线的 ID(类型为 int8),第二列是发生切换的 WAL 位置(类型为 text)。通常,切换位置就是所流式传输 WAL 的末尾,但也存在一些边界情况,服务器可能会先发送一些自己在提升前尚未重放的旧时间线 WAL。最后,服务器会发送两个 CommandComplete 消息(一个结束 CopyData,另一个结束 START_REPLICATION 本身),然后准备接受新的命令。 - WAL 数据会作为一系列 CopyData 消息发送;详见 。(这使其他信息可与之交错发送;特别是服务器在开始流式传输后若遇到失败,仍可发送 ErrorResponse。)从服务器到客户端的每个 CopyData 消息负载都属于以下格式之一: - + WAL 数据通过一系列 CopyData 消息发送,详见 。(这样可以混合发送其他信息;尤其是服务器在开始流式传输后遇到故障时,可以发送 ErrorResponse 消息。)服务器发给客户端的每条 CopyData 消息,其有效载荷都包含一条具有下列格式之一的消息: + @@ -1725,9 +1687,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('w') - - 将消息标识为WAL数据。 - + 将该消息标识为 WAL 数据。 @@ -1736,9 +1696,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 该消息中 WAL 数据的起始点。 - + 本消息中 WAL 数据的起始位置。 @@ -1747,9 +1705,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 服务器上当前的WAL结束位置。 - + 服务器上当前的 WAL 末尾位置。 @@ -1758,9 +1714,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 传输时服务器的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时服务器的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1769,15 +1723,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byten - - WAL数据流的一个部分。 - + WAL 数据流的一个片段。 - - 单个 WAL 记录绝不会拆分为两个 WALData 消息。 - 当 WAL 记录跨越 WAL 页面边界,并因此已使用连续记录进行拆分时,它可以在页面边界处进行拆分。 - 换句话说,第一个主 WAL 记录及其连续记录可以在不同的 WALData 消息中发送。 - + 单条 WAL 记录绝不会被拆分到两条 WALData 消息中。当 WAL 记录跨越 WAL 页边界,因而已经通过续接记录拆分时,可以在页边界处分开发送。换句话说,最初的主 WAL 记录及其续接记录可以在不同的 WALData 消息中发送。 @@ -1786,7 +1734,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 主库 keepalive 消息 (B) + 主库保活消息 (B) @@ -1794,9 +1742,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('k') - - 将该消息标识为发送方 keepalive。 - + 将该消息标识为发送端保活消息。 @@ -1805,9 +1751,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 服务器上当前的WAL结束位置。 - + 服务器上当前的 WAL 末尾位置。 @@ -1816,9 +1760,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 传输时服务器的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时服务器的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1827,9 +1769,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1 - - 1 表示客户端应尽快回复此消息,以避免超时断开连接。否则为0。 - + 1 表示客户端应尽快回复此消息,以避免超时断开连接;否则为 0。 @@ -1867,8 +1807,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 服务器上当前处于提交阶段的最老事务 ID,以及其 纪元。高 32 位是 纪元,低 32 位是事务 ID。如果服务器上没有活跃事务,则该数值为将要分配的下一个事务 ID。 - + 服务器上当前处于提交阶段的最老事务 ID 及其纪元。高 32 位为纪元,低 32 位为事务 ID。如果服务器上没有活跃事务,则该值为下一个待分配的事务 ID。 + @@ -1878,8 +1818,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 服务器上将要分配的下一个事务 ID,以及其 纪元。高 32 位是 纪元,低 32 位是事务 ID。 - + 服务器上下一个待分配的事务 ID 及其纪元。高 32 位为纪元,低 32 位为事务 ID。 + @@ -1888,9 +1828,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 传输时服务器的系统时钟,以 2000-01-01 午夜以来的微秒计算。 - + 发送消息时服务器的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1900,9 +1838,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - - 接收进程可以随时使用以下某种消息格式向发送方回传响应(同样放在 CopyData 消息的负载中): - + 接收进程可以随时使用以下消息格式之一回复发送端(同样放在 CopyData 消息的有效载荷中): @@ -1915,9 +1851,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('r') - - 将该消息标识为接收方状态更新。 - + 将该消息标识为接收端状态更新。 @@ -1926,9 +1860,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已接收并写入磁盘的 WAL 字节位置 + 1。 - + 备库已接收并写入磁盘的最后一个 WAL 字节的位置加 1。 @@ -1937,9 +1869,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已刷写到磁盘的 WAL 字节位置 + 1。 - + 备库已刷盘的最后一个 WAL 字节的位置加 1。 @@ -1948,9 +1878,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 备库中最后一个已应用的 WAL 字节位置 + 1。 - + 备库已应用的最后一个 WAL 字节的位置加 1。 @@ -1959,9 +1887,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 客户端在传输时的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时客户端的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -1970,9 +1896,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1 - - 如果为 1,则客户端请求服务器立即回复此消息。这可用于 ping 服务器,以测试连接是否仍然健康。 - + 如果为 1,表示客户端请求服务器立即回复此消息。可用它向服务器发送探测请求,以测试连接是否仍然正常。 @@ -2000,9 +1924,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 客户端在传输时的系统时钟,以2000-01-01午夜以来的微秒计算。 - + 发送消息时客户端的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -2023,8 +1945,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 备库上全局 xmin xid 的纪元。 - + 备库全局 xmin 事务 ID 的纪元。 + @@ -2034,8 +1956,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 备库上任何复制槽中的最低 catalog_xmin。如果备库上不存在 catalog_xmin,或已禁用热备反馈,则设为 0。 - + 备库上所有复制槽中最小的 catalog_xmin。如果备库上不存在 catalog_xmin,或者正在禁用热备反馈,则设为 0。 + @@ -2045,8 +1967,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 备库上 catalog_xmin xid 的纪元。 - + 备库 catalog_xmin 事务 ID 的纪元。 + @@ -2067,9 +1989,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - - 客户端在传输时的系统时钟,以 2000-01-01 午夜以来的微秒数表示。 - + 发送消息时客户端的系统时钟,以自 2000-01-01 午夜以来的微秒数表示。 @@ -2157,7 +2077,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" DROP_REPLICATION_SLOT slot_name WAIT - 删除复制槽 + DROP_REPLICATION_SLOT @@ -2220,9 +2140,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 设置备份的标签。如果未指定,则将使用base backup作为备份标签。 - 标签的引号使用规则与标准SQL字符串相同。 - + 设置备份标签。如果未指定,则使用 base backup 作为备份标签。标签的引号规则与标准 SQL 字符串相同。 + @@ -2323,16 +2242,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - level关键字设置压缩级别。 - 对于gzip,压缩级别应该是一个介于19之间的整数 - (默认为Z_DEFAULT_COMPRESSION-1), - 对于lz4,压缩级别应该是介于1和12之间的整数 - (默认为0用于快速压缩模式), - 对于zstd,压缩级别应该是介于ZSTD_minCLevel() - (通常为-131072)和ZSTD_maxCLevel() - (通常为22)之间, - (默认为ZSTD_CLEVEL_DEFAULT3)。 - + level 关键字设置压缩级别。对于 gzip,压缩级别应为 19 之间的整数(默认为 Z_DEFAULT_COMPRESSION,即 -1);对于 lz4,应为 1 到 12 之间的整数(默认为 0,表示快速压缩模式);对于 zstd,应为 ZSTD_minCLevel()(通常为 -131072)到 ZSTD_maxCLevel()(通常为 22)之间的整数(默认为 ZSTD_CLEVEL_DEFAULT,即 3)。 + long 关键字用于启用长距离匹配模式,可提高压缩比,但会增加内存使用。长距离模式仅支持 zstd。 @@ -2454,17 +2365,16 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" size (int8) - 表空间的大致大小,以千字节(1024字节)为单位,如果已请求进度报告;否则为null。 - + 如果请求了进度报告,则为表空间的大致大小,以千字节(1024 字节)为单位;否则为 null。 + - 在第二个常规结果集之后,将发送一个CopyOutResponse。 - 每个CopyData消息的有效负载将包含以下格式之一的消息: - + 第二个普通结果集之后,会发送一条 CopyOutResponse。每条 CopyData 消息的有效载荷都包含一条具有下列格式之一的消息: + @@ -2645,11 +2555,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" + + 在上述所有命令中,指定 boolean 类型的参数时,可以省略 value 部分,这等同于指定 TRUE。 + - 逻辑复制协议 + 逻辑流复制协议 本节介绍逻辑复制协议,它是一种以复制命令START_REPLICATION @@ -2658,7 +2571,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 逻辑复制协议构建在物理流复制协议的底层机制之上。 + 逻辑流复制协议构建在物理流复制协议的基本机制之上。 @@ -2707,7 +2620,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每个被发送的事务都包含零条或多条 DML 消息(插入、更新、删除)。在级联场景下,它还会包含 Origin 消息。Origin 消息表示该事务产生于另一个复制节点。由于逻辑复制协议中的复制节点可以是任意实现,因此唯一标识符就是该源头的名称。下游是否以及如何处理这一信息,由其自行决定。Origin 消息总是在事务中的任何 DML 消息之前发送。 + 每个发送的事务都包含零条或多条 DML 消息(Insert、Update、Delete)。在级联配置中,还可能包含 Origin 消息。Origin 消息表示该事务源自另一个复制节点。由于逻辑复制协议中的复制节点几乎可以是任何实现,因此唯一的标识符就是复制源的名称。下游负责按需处理这一信息(如果需要处理)。Origin 消息总是在事务中的任何 DML 消息之前发送。 @@ -2772,9 +2685,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 对后端返回的字符串长度,没有预定义的限制。 - 前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。 - 如果做不到这一点,就应读取完整字符串,并丢弃不适合固定大小缓冲区的尾随字符。 + 后端返回的字符串长度没有预定义的限制。前端较好的编码策略是使用可扩展缓冲区,以便接收所有能放进内存的内容。如果做不到这一点,就应读取完整字符串,并丢弃固定大小的缓冲区容纳不下的尾随字符。 @@ -2816,7 +2727,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2838,7 +2749,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定认证成功。 + 表示认证成功。 @@ -2858,7 +2769,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2880,7 +2791,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 Kerberos V5 认证。 + 表示需要 Kerberos V5 认证。 @@ -2900,7 +2811,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2922,7 +2833,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要明文密码。 + 表示需要明文密码。 @@ -2941,7 +2852,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -2963,7 +2874,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要MD5加密的密码。 + 表示需要经过 MD5 加密的密码。 @@ -2974,7 +2885,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 用于加密密码时使用的盐。 + 加密密码时使用的盐。 @@ -2993,7 +2904,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -3014,7 +2925,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 GSSAPI 认证。 + 表示需要 GSSAPI 认证。 @@ -3033,7 +2944,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -3055,7 +2966,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定此消息包含GSSAPI或SSPI数据。 + 表示此消息包含 GSSAPI 或 SSPI 数据。 @@ -3085,7 +2996,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -3107,7 +3018,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 SSPI 认证。 + 表示需要 SSPI 认证。 @@ -3126,7 +3037,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -3148,14 +3059,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定需要 SASL 认证。 + 表示需要 SASL 认证。 - 消息正文是服务器首选的 SASL 认证机制列表。在最后一个认证机制名称后需要一个零字节作为终止符。对于每个机制,有以下内容: + 消息体是按服务器偏好顺序排列的 SASL 认证机制列表。在最后一个认证机制名称之后,必须有一个零字节作为终止符。每个机制包含以下内容: @@ -3182,7 +3093,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -3204,7 +3115,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定此消息包含一个SASL挑战。 + 表示此消息包含 SASL 挑战。 @@ -3215,7 +3126,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - SASL数据,特定于正在使用的SASL机制。 + SASL 数据,具体内容取决于所使用的 SASL 机制。 @@ -3234,7 +3145,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为认证请求。 + 将该消息标识为认证请求。 @@ -3256,7 +3167,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定SASL认证已完成。 + 表示 SASL 认证已完成。 @@ -3267,7 +3178,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - SASL结果"附加数据",特定于正在使用的SASL机制。 + SASL 结果的“附加数据”,具体内容取决于所使用的 SASL 机制。 @@ -3286,15 +3197,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为取消键数据。 - 如果前端希望能够稍后发出CancelRequest消息,必须保存这些值。 + 将此消息标识为取消请求密钥数据。如果前端希望以后能够发送 CancelRequest 消息,就必须保存这些值。 - Int32(12) + Int32 @@ -3309,27 +3219,27 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 这个后端的进程ID。 + 此后端的进程 ID。 - Int32 + Byten - 该后端的 secret key。该字段长度由消息总长度决定,并一直延伸到消息末尾。 + 此后端的密钥。此字段延伸至消息末尾,其范围由长度字段确定。 - key 的最小与最大长度分别为 4 和 256 字节。PostgreSQL 服务器当前发送不超过 32 字节的 key;更大的上限用于兼容未来版本及连接池/中间件使用更长 key 的需求。中间件也不宜用满全部字节,以便多层中间件叠加时仍可附加自身数据。 + 密钥长度最小为 4 字节,最大为 256 字节。PostgreSQL 服务器只发送最长 32 字节的密钥,但更大的长度上限允许未来的服务器版本、连接池和其他中间件使用更长的密钥。一种可能的用途是在服务器密钥中附加额外信息。因此,也建议中间件不要用尽所有字节,以便多层中间件叠加时,每一层都可以在密钥外再附加数据。 - 在协议 3.2 之前,secret key 固定为 4 字节。 + 在协议版本 3.2 之前,密钥始终为 4 字节长。 @@ -3345,7 +3255,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为绑定命令。 + 将该消息标识为 Bind 命令。 @@ -3389,10 +3299,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后面跟着的参数格式代码的数量(以下标记为C)。 - 这可以是零,表示没有参数或者所有参数都使用默认格式(文本); - 或者是一个,这种情况下指定的格式代码应用于所有参数; - 或者等于实际参数的数量。 + 后续参数格式代码的数量(下文以 C 表示)。可以为零,表示没有参数,或者所有参数都使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有参数;还可以等于实际参数数量。 @@ -3403,7 +3310,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数格式代码。每个目前必须是零(文本)或一(二进制)。 + 参数格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -3414,15 +3321,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后面跟着的参数值的数量(可能为零)。 - 这个数量必须与查询所需的参数数量匹配。 + 后续参数值的数量(可以为零)。必须与查询所需的参数数量一致。 - 接下来,对于每个参数,都会出现以下一对字段: + 接下来,每个参数都有以下一对字段: @@ -3432,9 +3338,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数值的长度,以字节为单位(此计数不包括自身)。可以为零。 - 作为特殊情况,-1表示空参数值。 - 在空参数值的情况下,不会跟随任何值字节。 + 参数值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 参数值。为 NULL 时,后面不再有值的字节。 @@ -3445,15 +3349,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数的值,以相关格式代码指示的格式表示。 - n是上述长度。 + 参数值,格式由对应的格式代码指明。n 为上述长度。 - 在最后一个参数之后,出现以下字段: + 最后一个参数之后是以下字段: @@ -3463,10 +3366,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后跟的结果列格式代码数量(以下标记为R)。 - 这可以是零,表示没有结果列,或者所有结果列应该使用默认格式(文本); - 或者是一个,此时指定的格式代码将应用于所有结果列(如果有); - 或者等于查询的实际结果列数。 + 后续结果列格式代码的数量(下文以 R 表示)。可以为零,表示没有结果列,或者所有结果列都应使用默认格式(文本);也可以为一,此时指定的格式代码应用于所有结果列(如果有);还可以等于查询实际的结果列数量。 @@ -3477,7 +3377,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 结果列格式代码。每个目前必须是零(文本)或一(二进制)。 + 结果列格式代码。目前每个格式代码必须为零(文本)或一(二进制)。 @@ -3496,7 +3396,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为绑定完成指示器。 + 将该消息标识为 Bind 完成指示。 @@ -3524,7 +3424,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 - 消息内容的长度,以字节为单位,包括此长度字段本身。 + 消息内容的长度(以字节为单位),包括其自身。 @@ -3573,7 +3473,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为关闭命令。 + 将该消息标识为 Close 命令。 @@ -3595,8 +3495,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 'S' 表示关闭一个预备语句;或者 - 'P' 表示关闭一个 portal。 + “S”表示关闭预备语句;“P”表示关闭 portal。 @@ -3626,7 +3525,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为关闭完成指示符。 + 将该消息标识为 Close 完成指示。 @@ -3656,7 +3555,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为命令完成响应。 + 将该消息标识为命令完成响应。 @@ -3678,7 +3577,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 命令标签。这通常是一个单词,用于标识已完成的SQL命令。 + 命令标签。通常是一个单词,用来标识已完成的 SQL 命令。 @@ -3723,10 +3622,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 对于COPY命令,标签是 - COPY rows,其中 - rows是复制的行数。 - (注意:行数仅出现在PostgreSQL 8.2及更高版本中。) + 对于 COPY 命令,标签为 COPY rows,其中 rows 是复制的行数。(注意:行数仅出现在 PostgreSQL 8.2 及更高版本中。) @@ -3857,8 +3753,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为开始复制响应。 - 前端现在必须发送复制数据(如果没有准备好,发送CopyFail消息)。 + 将该消息标识为开始 COPY 输入的响应。前端此时必须发送 COPY 输入数据(如果尚未准备好,应发送 CopyFail 消息)。 @@ -3904,9 +3799,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -3925,8 +3818,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为开始复制输出响应。 - 该消息将被复制输出数据跟随。 + 将该消息标识为开始 COPY 输出的响应。此消息之后会发送 COPY 输出数据。 @@ -3948,8 +3840,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 0表示整体COPY格式为文本格式(行由换行符分隔,列由分隔符字符分隔等)。 - 1表示整体复制格式为二进制格式(类似于DataRow格式)。更多信息请参见。 + 0表示整体COPY格式是文本的(行由换行符分隔,列由分隔符分隔等)。 + 1表示整体复制格式是二进制的(类似于DataRow格式)。 + 更多信息请参见 @@ -3971,9 +3864,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -3992,7 +3883,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为开始复制双响应。此消息仅用于流复制。 + 将该消息标识为开始双向 COPY 的响应。此消息仅用于流复制。 @@ -4014,8 +3905,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 0表示整体COPY格式为文本格式(行由换行符分隔,列由分隔符字符分隔等)。 - 1表示整体复制格式为二进制格式(类似于DataRow格式)。更多信息请参见。 + 0表示整体COPY格式是文本的(行由换行符分隔,列由分隔符分隔等)。 + 1表示整体复制格式是二进制的(类似于DataRow格式)。 + 更多信息请参见 @@ -4037,9 +3929,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 每列要使用的格式代码。 - 每个必须目前为零(文本)或一(二进制)。 - 如果整体复制格式为文本,则所有必须为零。 + 各列使用的格式代码。目前每个代码必须为零(文本)或一(二进制)。如果整体复制格式为文本,则所有代码都必须为零。 @@ -4087,7 +3977,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于每一列,都会出现以下一对字段: + 接下来,每列都有以下两个字段: @@ -4097,8 +3987,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列值的长度,以字节为单位(此计数不包括其本身)。可以为零。 - 作为特殊情况,-1表示空列值。在空值情况下,不跟随任何值字节。 + 列值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 列值。为 NULL 时,后面不再有值的字节。 @@ -4129,7 +4018,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为描述命令。 + 将该消息标识为 Describe 命令。 @@ -4182,7 +4071,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为对空查询字符串的响应。(这相当于CommandComplete。) + 标识消息为对空查询字符串的响应。(此消息替代 CommandComplete。) @@ -4230,7 +4119,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 消息正文由一个或多个已识别的字段组成,后跟一个零字节作为终止符。字段可以以任何顺序出现。对于每个字段,都有以下内容: + 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -4253,7 +4142,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 字段数值。 + 字段值。 @@ -4272,7 +4161,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为一个执行命令。 + 将该消息标识为 Execute 命令。 @@ -4305,7 +4194,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果 portal 包含返回行的查询,则为要返回的最大行数(否则忽略)。零表示没有限制。 + 如果 portal 包含返回行的查询,则这是最多返回的行数(否则忽略此值)。零表示无限制 @@ -4324,7 +4213,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为Flush命令。 + 将该消息标识为 Flush 命令。 @@ -4376,7 +4265,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定要调用的函数的对象ID。 + 指定要调用的函数的对象 ID。 @@ -4387,10 +4276,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 后面跟着的参数格式代码的数量(以下标记为C)。 - 这可以是零,表示没有参数或所有参数都使用默认格式(文本); - 或者是一个,这种情况下指定的格式代码应用于所有参数; - 或者等于实际参数的数量。 + 后续参数格式代码的数量(以下用 C 表示)。可以为零,表示没有参数,或所有参数都采用默认格式(文本);也可以为一,表示将指定的格式代码用于所有参数;还可以等于实际参数数量。 @@ -4419,7 +4305,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于每个参数,都会出现以下一对字段: + 接下来,每个参数都有以下两个字段: @@ -4429,9 +4315,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数值的长度,以字节为单位(此计数不包括自身)。可以为零。 - 作为特殊情况,-1表示空参数值。 - 在空参数值的情况下,不会跟随任何值字节。 + 参数值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 参数值。为 NULL 时,后面不再有值的字节。 @@ -4450,7 +4334,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 在最后一个参数之后,出现以下字段: + 最后一个参数之后还有以下字段: @@ -4460,7 +4344,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 函数结果的格式代码。目前必须是零(文本)或一(二进制)。 + 函数结果的格式代码。目前必须为零(文本)或一(二进制)。 @@ -4501,9 +4385,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 函数结果值的长度,以字节为单位(此计数不包括本身)。可以为零。 - 作为特殊情况,-1表示NULL函数结果。 - 在NULL情况下,不会跟随任何值字节。 + 函数结果值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 函数结果。为 NULL 时,后面不再有值的字节。 @@ -4629,7 +4511,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 服务器支持的最新次要协议版本,用于客户端请求的主要协议版本。 + 对于客户端请求的协议主版本,服务器所支持的最新协议次版本。 @@ -4640,14 +4522,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 服务器未识别的协议选项数量。 + 服务器无法识别的协议选项数量。 - 然后,对于服务器未识别的协议选项,有以下内容: + 接下来,对于服务器无法识别的每个协议选项,都有以下内容: @@ -4724,7 +4606,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 消息正文由一个或多个已识别的字段组成,后跟一个零字节作为终止符。字段可以以任何顺序出现。对于每个字段,都有以下内容: + 消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容: @@ -4747,7 +4629,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 字段数值。 + 字段值。 @@ -4788,7 +4670,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 通知后端进程的进程ID。 + 发出通知的后端进程的进程 ID。 @@ -4799,7 +4681,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 通知被触发的频道名称。 + 发出该通知的通道名称。 @@ -4810,7 +4692,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 从通知进程传递的有效负载字符串。 + 通知进程传来的有效载荷字符串。 @@ -4858,7 +4740,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 然后,对于每个参数,都有以下内容: + 接下来,每个参数都有以下内容: @@ -4868,7 +4750,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定参数数据类型的对象ID。 + 指定参数数据类型的对象 ID。 @@ -4909,7 +4791,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 正在报告的运行时参数的名称。 + 所报告的运行时参数的名称。 @@ -4939,7 +4821,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为解析命令。 + 将该消息标识为 Parse 命令。 @@ -4991,7 +4873,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 然后,对于每个参数,都有以下内容: + 接下来,每个参数都有以下内容: @@ -5001,7 +4883,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定参数数据类型的对象ID。在这里放置零相当于未指定类型。 + 指定参数数据类型的对象 ID。此处填零等同于不指定类型。 @@ -5020,7 +4902,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为解析完成指示器。 + 将该消息标识为 Parse 完成指示。 @@ -5092,8 +4974,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为 portal 挂起指示器。 - 请注意,仅当执行消息的行数限制达到时才会出现此消息。 + 将该消息标识为 portal 挂起指示。注意,仅当达到 Execute 消息指定的行数限制时,才会出现此消息。 @@ -5229,14 +5110,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 指定一行中的字段数(可以为零)。 + 指定一行中的字段数量(可以为零)。 - 然后,对于每个字段,都有以下内容: + 接下来,每个字段都有以下内容: @@ -5257,7 +5138,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果该字段可以被识别为特定表的列,则为该表的对象ID;否则为零。 + 如果能够确定该字段是某个特定表的列,则为该表的对象 ID;否则为零。 @@ -5268,7 +5149,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 如果该字段可以被识别为特定表的列,则为该列的属性编号;否则为零。 + 如果能够确定该字段是某个特定表的列,则为该列的属性编号;否则为零。 @@ -5279,7 +5160,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 字段数据类型的对象ID。 + 字段数据类型的对象 ID。 @@ -5314,7 +5195,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 正在使用的字段格式代码。目前将为零(文本)或一(二进制)。在从描述语句变体返回的RowDescription中,格式代码尚未知晓,将始终为零。 + 字段所使用的格式代码。目前为零(文本)或一(二进制)。对于 Describe 针对预备语句的变体所返回的 RowDescription,格式代码尚未确定,始终为零。 @@ -5367,7 +5248,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 长度为SASL机制特定的“初始客户端响应”,如果没有初始响应,则为-1。 + 后续 SASL 机制特有的“客户端初始响应”的长度;如果没有初始响应,则为 -1。 @@ -5491,9 +5372,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 协议版本号后面跟着一个或多个参数名和值字符串对。在最后一个名/值对之后需要一个零字节作为终止符。 - 参数可以以任何顺序出现。user是必需的,其他是可选的。 - 每个参数的指定方式为: + 协议版本号之后是一个或多个参数名与参数值字符串对。最后一个名称/值对之后必须有一个零字节作为终止符。参数可以按任意顺序出现。其中,user是必需的,其余均为可选。每个参数按以下方式指定: @@ -5503,7 +5382,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数名称。当前识别的名称包括: + 参数名称。目前能够识别的名称如下: @@ -5554,7 +5433,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 参数数值。 + 参数值。 @@ -5573,7 +5452,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为同步命令。 + 将该消息标识为 Sync 命令。 @@ -5626,7 +5505,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 错误和通知消息域 + 错误和通知消息字段 本节描述了ErrorResponse和NoticeResponse消息中可能出现的字段。每个字段类型都有一个单字节的标识符。 @@ -5639,11 +5518,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 严重性: 字段内容为ERROR, FATAL, 或 - PANIC (在错误消息中), 或 - WARNING, NOTICE, DEBUG, - INFO, 或 LOG (在通知消息中), - 或者这些内容的本地化翻译。始终存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中),或这些内容的本地化翻译。始终存在。 @@ -5653,11 +5528,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 严重性:字段内容为ERRORFATAL或 - PANIC(在错误消息中),或WARNINGNOTICEDEBUG、 - INFOLOG(在通知消息中)。 - 这与S字段相同,只是内容不会被本地化。仅在由PostgreSQL版本9.6 - 及更高版本生成的消息中存在。 + 严重性:字段内容为 ERRORFATALPANIC(在错误消息中),或 WARNINGNOTICEDEBUGINFOLOG(在通知消息中)。它与 S 字段相同,只是内容从不本地化。仅在 PostgreSQL 9.6 及更高版本生成的消息中存在。 @@ -5667,7 +5538,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Code: 错误的SQLSTATE代码(参见)。不可本地化。始终存在。 + 代码:错误的 SQLSTATE 代码(见 )。不可本地化。始终存在。 @@ -5677,9 +5548,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 消息: 主要的人类可读错误消息。 - 这应该准确但简洁(通常一行)。 - 总是存在。 + 消息:主要的可读错误消息。应准确而简洁(通常为一行)。始终存在。 @@ -5689,7 +5558,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 详细信息:一个可选的次要错误消息,提供有关问题的更多详细信息。可能会跨多行。 + 详细信息:可选的次要错误消息,提供有关该问题的更多细节。可能占多行。 @@ -5699,9 +5568,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 提示: 关于问题应该怎么做的一个可选建议。 - 这意在与细节不同,它提供建议(可能不合适)而不是硬性事实。 - 可能会跨越多行。 + 提示:可选的建议,说明如何处理该问题。它与详细信息的区别在于,它提供建议(可能并不合适),而非确凿事实。可能占多行。 @@ -5744,9 +5611,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Where: 错误发生的上下文指示。 - 目前包括活动的过程语言函数和内部生成查询的调用堆栈回溯。 - 跟踪每行一个条目,最近的在前。 + 上下文:说明错误发生时的上下文。目前包括活跃的过程语言函数和内部生成的查询的调用栈回溯。回溯每行一个条目,最近的调用在前。 @@ -5756,7 +5621,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Schema name: 如果错误与特定数据库对象相关联,则为包含该对象的模式的名称(如果有)。 + 模式名:如果错误与某个特定数据库对象有关,则为包含该对象的模式名称(如果有)。 @@ -5766,7 +5631,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 表名: 如果错误与特定表相关联,则为表的名称。(有关表模式名称的名称,请参考模式名称字段。) + 表名:如果错误与某个特定表有关,则为该表的名称。(表所在模式的名称见模式名字段。) @@ -5776,7 +5641,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列名: 如果错误与特定表列相关联,则为列的名称。(请参考模式和表名字段以识别表。) + 列名:如果错误与某个特定表列有关,则为该列的名称。(通过模式名和表名字段确定该表。) @@ -5786,8 +5651,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 数据类型名称: 如果错误与特定数据类型相关联,则为数据类型的名称。 - (有关数据类型模式的名称,请参阅模式名称字段。) + 数据类型名:如果错误与某个特定数据类型有关,则为该数据类型的名称。(数据类型所在模式的名称见模式名字段。) @@ -5797,8 +5661,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 约束名称: 如果错误与特定约束相关联,则为约束的名称。请参考上面列出的字段,了解相关表或域。 - (为此,即使索引不是使用约束语法创建的,也将其视为约束。) + 约束名:如果错误与某个特定约束有关,则为该约束的名称。相关的表或域见上述字段。(这里将索引也视为约束,即使它不是用约束语法创建的。) @@ -5808,7 +5671,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 文件: 报告错误的源代码位置的文件名。 + 文件:报告错误的源代码位置所在的文件名。 @@ -5818,7 +5681,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Line: 源代码位置的行号,报告错误的位置。 + 行号:报告错误的源代码位置所在的行号。 @@ -5828,7 +5691,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Routine: 报告错误的源代码例程的名称。 + 例程:报告错误的源代码例程的名称。 @@ -5837,15 +5700,12 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 模式名称、表名称、列名称、数据类型名称和约束名称的字段仅针对有限数量的错误类型提供; - 请参阅。前端不应假设任何这些字段的存在就保证了另一个字段的存在。 - 核心错误源观察到上述相互关系,但用户定义的函数可能以其他方式使用这些字段。 - 同样地,客户端不应假设这些字段表示当前数据库中的当代对象。 + 模式名、表名、列名、数据类型名和约束名字段仅针对有限的几类错误提供,见 。前端不应假设其中任何字段的存在就保证了另一个字段的存在。核心错误源遵循上述相互关系,但用户定义的函数可能以其他方式使用这些字段。同样,客户端不应假设这些字段表示当前数据库中现存的对象。 - 客户端负责格式化显示的信息以满足其需求;特别是应根据需要换行。错误消息字段中出现的换行符应被视为段落分隔符,而不是换行符。 + 客户端负责按自身需要格式化显示的信息;尤其应根据需要将长行断开。错误消息字段中的换行符应视为段落分隔符,而非行分隔符。 @@ -5871,18 +5731,18 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为开始消息。 + 将该消息标识为 Begin 消息。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 事务的最终LSN。 + 事务的最终 LSN。 @@ -5893,7 +5753,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -5904,7 +5764,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -5934,8 +5794,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -5946,14 +5805,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标志; 逻辑解码消息是非事务性的时为0,是事务性的时为1。 + 标志:0 表示没有标志;1 表示该逻辑解码消息是事务性的。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6009,7 +5868,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为提交消息。 + 将该消息标识为 Commit 消息。 @@ -6027,22 +5886,22 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 提交的LSN。 + 提交的 LSN。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 事务的结束LSN。 + 事务的结束 LSN。 @@ -6053,7 +5912,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6072,18 +5931,18 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为原始消息。 + 将该消息标识为 Origin 消息。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 原始服务器上提交的LSN。 + 源服务器上提交的 LSN。 @@ -6094,14 +5953,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 原点的名称。 + 复制源的名称。 - 请注意,在单个事务中可能存在多个Origin消息。 + 注意,单个事务中可能有多条 Origin 消息。 @@ -6117,7 +5976,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为关系消息。 + 将该消息标识为 Relation 消息。 @@ -6128,8 +5987,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6151,7 +6009,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 命名空间(pg_catalog为空字符串)。 + 命名空间(对于 pg_catalog 为空字符串)。 @@ -6173,7 +6031,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 关系的复制标识设置(与relreplidentpg_class中相同)。 + 关系的复制标识设置(与 pg_class 中的 relreplident 相同)。 @@ -6191,7 +6049,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于出版物中包含的每一列(除了生成的列),会出现以下消息部分: + 接下来,发布中包含的每一列都会出现以下消息部分: @@ -6201,7 +6059,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列的标志。目前可以是0表示没有标志,或者是1表示将该列标记为键的一部分。 + 列的标志。目前可以为 0,表示没有标志;或为 1,标记该列是键的一部分。 @@ -6234,7 +6092,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 列的类型修饰符 (atttypmod)。 + 列的类型修饰符(atttypmod)。 @@ -6253,7 +6111,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为类型消息。 + 将该消息标识为 Type 消息。 @@ -6264,8 +6122,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6287,7 +6144,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 命名空间(pg_catalog为空字符串)。 + 命名空间(对于 pg_catalog 为空字符串)。 @@ -6317,7 +6174,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为插入消息。 + 将该消息标识为 Insert 消息。 @@ -6328,8 +6185,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6340,7 +6196,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。 + 关系的 OID,与 Relation 消息中的 ID 对应。 @@ -6351,7 +6207,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData消息为新元组。 + 将后续 TupleData 消息标识为新元组。 @@ -6362,7 +6218,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分,表示新元组的内容。 + 表示新元组内容的 TupleData 消息部分。 @@ -6381,7 +6237,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为更新消息。 + 将该消息标识为 Update 消息。 @@ -6392,8 +6248,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6404,7 +6259,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。 + 关系的 OID,与 Relation 消息中的 ID 对应。 @@ -6415,8 +6270,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData子消息为键。 - 此字段是可选的,仅在更新更改了属于REPLICA IDENTITY索引的任何列的数据时才存在。 + 将后续 TupleData 子消息标识为键。此字段可选,仅在更新更改了属于 REPLICA IDENTITY 索引的某一列或多列的数据时出现。 @@ -6427,8 +6281,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData子消息为旧元组。 - 此字段是可选的,仅在发生更新的表中REPLICA IDENTITY设置为FULL时才存在。 + 将后续 TupleData 子消息标识为旧元组。此字段可选,仅在发生更新的表将 REPLICA IDENTITY 设为 FULL 时出现。 @@ -6439,7 +6292,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分表示旧元组或主键的内容。仅在先前的'O'或'K'部分存在时才存在。 + 表示旧元组或主键内容的 TupleData 消息部分。仅在前面的'O'或'K'部分存在时出现。 @@ -6450,7 +6303,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData消息为新元组。 + 将后续 TupleData 消息标识为新元组。 @@ -6461,14 +6314,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分表示新元组的内容。 + 表示新元组内容的 TupleData 消息部分。 - 更新消息可能包含一个'K'消息部分,也可能包含一个'O'消息部分,或者两者都不包含,但绝不会同时包含两者。 + Update 消息可以包含 'K' 消息部分或 'O' 消息部分,也可以两者都不包含,但绝不会同时包含两者。 @@ -6484,7 +6337,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为删除消息。 + 将该消息标识为 Delete 消息。 @@ -6495,8 +6348,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6507,7 +6359,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。 + 关系的 OID,与 Relation 消息中的 ID 对应。 @@ -6518,8 +6370,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData子消息为键。 - 如果发生删除操作的表使用索引作为REPLICA IDENTITY,则存在此字段。 + 将后续 TupleData 子消息标识为键。如果发生删除的表使用索引作为 REPLICA IDENTITY,则出现此字段。 @@ -6530,8 +6381,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识以下TupleData消息为旧元组。 - 如果发生删除操作的表的REPLICA IDENTITY设置为FULL,则存在此字段。 + 将后续 TupleData 消息标识为旧元组。如果发生删除的表将 REPLICA IDENTITY 设为 FULL,则出现此字段。 @@ -6542,14 +6392,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - TupleData消息部分,表示旧元组或主键的内容,取决于前一个字段。 + 表示旧元组或主键内容的 TupleData 消息部分,具体取决于前一个字段。 - 删除消息可能包含一个'K'消息部分或一个'O'消息部分,但绝不会同时包含两者。 + Delete 消息可以包含 'K' 消息部分或 'O' 消息部分,但绝不会同时包含两者。
@@ -6565,7 +6415,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为截断消息。 + 将该消息标识为 Truncate 消息。 @@ -6576,8 +6426,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid(仅适用于流式事务)。 - 该字段自协议版本2起可用。 + 事务的 Xid(仅在流式传输的事务中出现)。此字段从协议版本 2 起可用。 @@ -6611,7 +6460,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 与关系消息中ID对应的关系的OID。该字段对每个关系都重复。 + 关系的 OID,与 Relation 消息中的 ID 对应。每个关系都重复出现此字段。 @@ -6636,7 +6485,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为流开始消息。 + 将该消息标识为 Stream Start 消息。 @@ -6647,7 +6496,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6677,7 +6526,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为流停止消息。 + 将该消息标识为 Stream Stop 消息。 @@ -6696,7 +6545,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为流提交消息。 + 将该消息标识为 Stream Commit 消息。 @@ -6707,7 +6556,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6725,22 +6574,22 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 提交的LSN。 + 提交的 LSN。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) - 事务的结束LSN。 + 事务的结束 LSN。 @@ -6751,7 +6600,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6770,7 +6619,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 将消息标识为流中止消息。 + 将该消息标识为 Stream Abort 消息。 @@ -6781,7 +6630,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6838,14 +6687,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务开始消息。 + 将该消息标识为 Begin Prepare 消息。 - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6856,7 +6705,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6871,7 +6720,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6882,7 +6731,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6912,7 +6761,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务消息。 + 将该消息标识为 Prepare 消息。 @@ -6930,7 +6779,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6941,7 +6790,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -6956,7 +6805,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -6967,7 +6816,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -6997,7 +6846,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务提交消息。 + 将该消息标识为 Commit Prepared 消息。 @@ -7015,7 +6864,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -7026,7 +6875,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -7041,7 +6890,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的提交时间戳。该值是自PostgreSQL纪元(2000-01-01)以来的微秒数。 + 事务的提交时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -7052,7 +6901,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -7082,7 +6931,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为预备事务回滚消息。 + 将该消息标识为 Rollback Prepared 消息。 @@ -7100,7 +6949,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -7111,7 +6960,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -7126,7 +6975,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -7148,7 +6997,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -7178,7 +7027,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 标识消息为流式预备事务消息。 + 将该消息标识为 Stream Prepare 消息。 @@ -7196,7 +7045,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -7207,7 +7056,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Int64(XLogRecPtr) + Int64 (XLogRecPtr) @@ -7222,7 +7071,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 预备事务的时间戳。该值是自 PostgreSQL 纪元(2000-01-01)以来的微秒数。 + 事务进入预备状态的时间戳。其值为自 PostgreSQL 纪元(2000-01-01)起经过的微秒数。 @@ -7233,7 +7082,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 事务的Xid。 + 事务的 Xid。 @@ -7276,14 +7125,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - 接下来,对于每一列(除了生成的列),会出现以下子消息之一: + 接下来,每个已发布的列都会出现以下子消息之一: Byte1('n') - 将数据标识为NULL值。 + 将该数据标识为 NULL 值。 @@ -7294,7 +7143,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('u') - 将TOASTed值标识为未更改的值(实际值未发送)。 + 标识未更改的 TOAST 值(不发送实际值)。 @@ -7305,7 +7154,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('t') - 将数据标识为文本格式化值。 + 将该数据标识为文本格式的值。 @@ -7316,7 +7165,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byte1('b') - 将数据标识为二进制格式化值。 + 将该数据标识为二进制格式的值。 @@ -7334,9 +7183,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Byten - 列的值,以二进制或文本格式呈现。 - (如前述格式字节中指定)。 - n是上述长度。 + 列值,采用二进制或文本格式(由前面的格式字节指定)。n 为上述长度。 diff --git a/zh/20/rangetypes.sgml b/zh/20/rangetypes.sgml index 68409fa3..5badec6c 100644 --- a/zh/20/rangetypes.sgml +++ b/zh/20/rangetypes.sgml @@ -5,11 +5,11 @@ 范围类型 - range type + 范围类型 - multirange type + 多范围类型 @@ -21,7 +21,7 @@ - 每种范围类型都有一个对应的多范围类型。多范围是由多个彼此不连续、非空且非 NULL 的范围构成的有序列表。大多数范围操作符也可作用于多范围,并且多范围还有一些专用函数。 + 每种范围类型都有一个对应的多范围类型。多范围是一个有序列表,其中的范围彼此不连续,且均非空、非 NULL。大多数范围操作符也可作用于多范围,并且多范围还有一些专用函数。 @@ -124,15 +124,15 @@ SELECT isempty(numrange(1, 5)); 无限(无界)范围 - 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作 +/-infinity,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的 +/-infinity 值。 + 范围的下界可以省略,这意味着所有小于上界的值都包含在范围内,例如(,3]。同样,如果省略范围的上界,则所有大于下界的值都包含在范围内。如果上下界都被省略,则该元素类型的所有值都被认为处于该范围内。把缺失的界限指定为包含,会自动转换为排除,例如[,]会转换为(,)。你可以把这些缺失的值看作正负无穷大,但它们是特殊的范围类型值,并且被认为超出了任何范围元素类型的正负无穷大值。 - 具有infinity概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 + 具有无穷大概念的元素类型可以将其用作显式界限值。例如,对于时间戳范围,[today,infinity)不包括特殊的timestampinfinity,而[today,infinity]则包括它,[today,)[today,]也一样。 - 函数lower_infupper_inf分别测试范围的下界和上界是否为无限。 + 函数lower_infupper_inf分别测试范围是否没有下界和上界。 @@ -324,8 +324,8 @@ SELECT '[11:10, 23:00]'::timerange; 索引 - range type - indexes on + 范围类型 + 索引 @@ -357,7 +357,7 @@ CREATE INDEX reservation_idx ON reservation USING GIST (during); - 此外,也可以为范围类型的表列创建 B-树和哈希索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和哈希支持主要是为了允许在查询内部进行排序和哈希,而不是用于创建实际的索引。 + 此外,也可以为范围类型的表列创建 B-树和 hash 索引。对于这些索引类型,基本上唯一有用的范围操作就是等值。系统为范围值定义了对应<>操作符的 B-树排序顺序,但这种顺序相当任意,在现实中通常并没有什么用处。范围类型的 B-树和 hash 支持主要是为了允许在查询内部进行排序和 hash 运算,而不是用于创建实际的索引。 @@ -366,8 +366,8 @@ CREATE INDEX reservation_idx ON reservation USING GIST (during); 范围上的约束 - range type - exclude + 范围类型 + 排他约束 diff --git a/zh/20/ref/alter_extension.sgml b/zh/20/ref/alter_extension.sgml index 3ceae003..b5824a68 100644 --- a/zh/20/ref/alter_extension.sgml +++ b/zh/20/ref/alter_extension.sgml @@ -170,7 +170,7 @@ ALTER EXTENSION name DROP 要添加到扩展中或从扩展中移除的对象名称。表、聚合、域、外部表、函数、 - 操作符、操作符类、操作符族、过程、例程、序列、文本搜索对象、类型和视图的名称 + 操作符、操作符类、操作符族、过程、例程、序列、文本检索对象、类型和视图的名称 可以带模式限定。 diff --git a/zh/20/ref/alter_tsconfig.sgml b/zh/20/ref/alter_tsconfig.sgml index 891dce66..0845a229 100644 --- a/zh/20/ref/alter_tsconfig.sgml +++ b/zh/20/ref/alter_tsconfig.sgml @@ -19,7 +19,7 @@ PostgreSQL documentation ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义 + 更改一个文本检索配置的定义 @@ -51,7 +51,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA ALTER TEXT SEARCH CONFIGURATION - 更改一个文本搜索配置的定义。你可以修改其从记号类型到字典的映射, + 更改一个文本检索配置的定义。你可以修改其从词元类型到词典的映射, 或者更改该配置的名称或拥有者。 @@ -75,7 +75,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 一个现有文本搜索配置的名称(可以是模式限定的)。 + 一个现有文本检索配置的名称(可以是模式限定的)。 @@ -86,7 +86,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 由该配置的解析器发出的记号类型的名称。 + 由该配置的解析器发出的词元类型的名称。 @@ -97,7 +97,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 用于指定记号类型的文本搜索字典名称。如果列出了多个字典, + 用于指定词元类型的文本检索词典名称。如果列出了多个词典, 将按指定顺序依次查阅它们。 @@ -109,7 +109,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 在映射中要替换的文本搜索字典的名称。 + 在映射中要替换的文本检索词典的名称。 @@ -121,7 +121,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA 被用来替代old_dictionary - 的文本搜索字典的名称。 + 的文本检索词典的名称。 @@ -132,7 +132,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新名称。 + 该文本检索配置的新名称。 @@ -143,7 +143,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新拥有者。 + 该文本检索配置的新拥有者。 @@ -154,7 +154,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - 该文本搜索配置的新模式。 + 该文本检索配置的新模式。 @@ -163,17 +163,17 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA - ADD MAPPING FOR形式会为指定记号类型设置要查阅的字典列表; - 如果任一记号类型已经有映射,则会报错。ALTER MAPPING FOR - 形式作用相同,但会先移除这些记号类型的任何现有映射。 + ADD MAPPING FOR形式会为指定词元类型设置要查阅的词典列表; + 如果任一词元类型已经有映射,则会报错。ALTER MAPPING FOR + 形式作用相同,但会先移除这些词元类型的任何现有映射。 ALTER MAPPING REPLACE形式会在 old_dictionary出现的任何位置, 用new_dictionary替换它。 - 如果出现FOR,则只对指定的记号类型这样做;如果未出现 + 如果出现FOR,则只对指定的词元类型这样做;如果未出现 FOR,则对该配置的所有映射这样做。 - DROP MAPPING形式会移除指定记号类型的所有字典,使这些类型的 - 记号被文本搜索配置忽略。除非出现IF EXISTS,否则如果这些 - 记号类型没有映射就会报错。 + DROP MAPPING形式会移除指定词元类型的所有词典,使这些类型的 + 词元被文本检索配置忽略。除非出现IF EXISTS,否则如果这些 + 词元类型没有映射就会报错。 @@ -187,7 +187,7 @@ ALTER TEXT SEARCH CONFIGURATION name SET SCHEMA 下面的示例将my_config中凡是使用 - english字典的地方,都替换为swedish字典。 + english词典的地方,都替换为swedish词典。 diff --git a/zh/20/ref/alter_tsdictionary.sgml b/zh/20/ref/alter_tsdictionary.sgml index 163d788b..798c6734 100644 --- a/zh/20/ref/alter_tsdictionary.sgml +++ b/zh/20/ref/alter_tsdictionary.sgml @@ -19,7 +19,7 @@ PostgreSQL documentation ALTER TEXT SEARCH DICTIONARY - 更改一个文本搜索字典的定义 + 更改一个文本检索词典的定义 @@ -43,14 +43,14 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - ALTER TEXT SEARCH DICTIONARY更改文本搜索字典的 - 定义。你可以更改该字典的模板相关选项,也可以更改该字典的名称或拥有者。 + ALTER TEXT SEARCH DICTIONARY更改文本检索词典的 + 定义。你可以更改该词典的模板相关选项,也可以更改该词典的名称或拥有者。 - 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该字典 + 要使用ALTER TEXT SEARCH DICTIONARY,你必须是该词典 的拥有者。 @@ -67,7 +67,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 一个现有文本搜索字典的名称(可以是模式限定的)。 + 一个现有文本检索词典的名称(可以是模式限定的)。 @@ -78,7 +78,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -89,7 +89,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 模板相关选项要使用的新值。如果省略等号和值,则会从该字典中移除 + 模板相关选项要使用的新值。如果省略等号和值,则会从该词典中移除 该选项之前的设置,从而允许使用默认值。 @@ -101,7 +101,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新名称。 + 该文本检索词典的新名称。 @@ -112,7 +112,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新拥有者。 + 该文本检索词典的新拥有者。 @@ -123,7 +123,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 该文本搜索字典的新模式。 + 该文本检索词典的新模式。 @@ -144,7 +144,7 @@ ALTER TEXT SEARCH DICTIONARY name SET SCHEMA - 下面的示例命令更改了一个基于 Snowball 的字典的停用词列表。其他参数 + 下面的示例命令更改了一个基于 Snowball 的词典的停用词列表。其他参数 保持不变。 @@ -170,7 +170,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( language = dutch, StopWords ); - 下面的示例命令更新了该字典的定义,但实际上并没有做 + 下面的示例命令更新了该词典的定义,但实际上并没有做 任何更改。 @@ -178,7 +178,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( dummy ); (之所以可行,是因为选项移除代码在不存在该选项时也不会报错。) - 这种技巧在修改该字典的配置文件时很有用:ALTER + 这种技巧在修改该词典的配置文件时很有用:ALTER 会强制现有数据库会话重新读取配置文件,而如果它们先前已经读取过这 些文件,本来是不会再次读取的。 diff --git a/zh/20/ref/alter_tsparser.sgml b/zh/20/ref/alter_tsparser.sgml index 0844cb0a..ccc73f05 100644 --- a/zh/20/ref/alter_tsparser.sgml +++ b/zh/20/ref/alter_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH PARSER - 更改一个全文检索解析器的定义 + 更改一个文本检索解析器的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA 描述 - ALTER TEXT SEARCH PARSER更改全文检索解析器的定义。 + ALTER TEXT SEARCH PARSER更改文本检索解析器的定义。 当前唯一支持的功能是更改该解析器的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA name - 一个现有全文检索解析器的名称(可以是模式限定的)。 + 一个现有文本检索解析器的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_name - 该全文检索解析器的新名称。 + 该文本检索解析器的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH PARSER name SET SCHEMA new_schema - 该全文检索解析器的新模式。 + 该文本检索解析器的新模式。 diff --git a/zh/20/ref/alter_tstemplate.sgml b/zh/20/ref/alter_tstemplate.sgml index a3eec599..9c9dfc2c 100644 --- a/zh/20/ref/alter_tstemplate.sgml +++ b/zh/20/ref/alter_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation ALTER TEXT SEARCH TEMPLATE - 更改一个文本搜索模板的定义 + 更改一个文本检索模板的定义 @@ -30,7 +30,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA 描述 - ALTER TEXT SEARCH TEMPLATE更改文本搜索模板的定义。 + ALTER TEXT SEARCH TEMPLATE更改文本检索模板的定义。 当前唯一支持的功能是更改该模板的名称。 @@ -47,7 +47,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA name - 一个现有文本搜索模板的名称(可以是模式限定的)。 + 一个现有文本检索模板的名称(可以是模式限定的)。 @@ -56,7 +56,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_name - 该文本搜索模板的新名称。 + 该文本检索模板的新名称。 @@ -65,7 +65,7 @@ ALTER TEXT SEARCH TEMPLATE name SET SCHEMA new_schema - 该文本搜索模板的新模式。 + 该文本检索模板的新模式。 diff --git a/zh/20/ref/create_tsconfig.sgml b/zh/20/ref/create_tsconfig.sgml index 52970b36..fc77edb9 100644 --- a/zh/20/ref/create_tsconfig.sgml +++ b/zh/20/ref/create_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH CONFIGURATION - 定义一个新的文本搜索配置 + 定义一个新的文本检索配置 @@ -33,24 +33,24 @@ CREATE TEXT SEARCH CONFIGURATION name CREATE TEXT SEARCH CONFIGURATION - 创建一个新的文本搜索配置。文本搜索配置指定一个能把字符串拆分为记号 - 的文本搜索解析器,以及一些可用于判断哪些记号对搜索有意义的词典。 + 创建一个新的文本检索配置。文本检索配置指定一个能把字符串拆分为词元 + 的文本检索解析器,以及一些可用于判断哪些词元对搜索有意义的词典。 - 如果只指定了解析器,那么新文本搜索配置最初没有从记号类型到词典的映射, + 如果只指定了解析器,那么新文本检索配置最初没有从词元类型到词典的映射, 因而会忽略所有词。要让该配置真正可用,必须使用后续的ALTER TEXT SEARCH CONFIGURATION命令创建映射。 - 另一种方式是复制一个现有的文本搜索配置。 + 另一种方式是复制一个现有的文本检索配置。 - 如果给出了一个模式名称,则文本搜索配置会被创建在指定的模式中。否则它将会 + 如果给出了一个模式名称,则文本检索配置会被创建在指定的模式中。否则它将会 被创建在当前模式中。 - 定义该文本搜索配置的用户会成为其拥有者。 + 定义该文本检索配置的用户会成为其拥有者。 @@ -66,7 +66,7 @@ CREATE TEXT SEARCH CONFIGURATION namename - 要创建的文本搜索配置的名称。该名称可以是模式限定的。 + 要创建的文本检索配置的名称。该名称可以是模式限定的。 @@ -75,7 +75,7 @@ CREATE TEXT SEARCH CONFIGURATION nameparser_name - 此配置要使用的文本搜索解析器的名称。 + 此配置要使用的文本检索解析器的名称。 @@ -84,7 +84,7 @@ CREATE TEXT SEARCH CONFIGURATION namesource_config - 要复制的现有文本搜索配置的名称。 + 要复制的现有文本检索配置的名称。 diff --git a/zh/20/ref/create_tsdictionary.sgml b/zh/20/ref/create_tsdictionary.sgml index c45a7240..823710b7 100644 --- a/zh/20/ref/create_tsdictionary.sgml +++ b/zh/20/ref/create_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH DICTIONARY - 定义一个新的文本搜索字典 + 定义一个新的文本检索词典 @@ -33,19 +33,19 @@ CREATE TEXT SEARCH DICTIONARY name CREATE TEXT SEARCH DICTIONARY创建一个 - 新的文本搜索字典。文本搜索字典指定一种在搜索时识别哪些词值得关注、 - 哪些词不值得关注的方式。字典依赖于文本搜索模板,后者规定了实际执行 - 这项工作的函数。通常,字典会提供一些选项,用来控制模板函数的具体 + 新的文本检索词典。文本检索词典指定一种在搜索时识别哪些词值得关注、 + 哪些词不值得关注的方式。词典依赖于文本检索模板,后者规定了实际执行 + 这项工作的函数。通常,词典会提供一些选项,用来控制模板函数的具体 行为。 - 如果给出了一个模式名称,那么该文本搜索字典会被创建在指定的模式中。 + 如果给出了一个模式名称,那么该文本检索词典会被创建在指定的模式中。 否则它会被创建在当前模式中。 - 定义文本搜索字典的用户将成为其拥有者。 + 定义文本检索词典的用户将成为其拥有者。 @@ -61,7 +61,7 @@ CREATE TEXT SEARCH DICTIONARY name name - 要创建的文本搜索字典的名称。该名称可以被模式限定。 + 要创建的文本检索词典的名称。该名称可以被模式限定。 @@ -70,7 +70,7 @@ CREATE TEXT SEARCH DICTIONARY name template - 用于定义该字典基本行为的文本搜索模板名称。 + 用于定义该词典基本行为的文本检索模板名称。 @@ -79,7 +79,7 @@ CREATE TEXT SEARCH DICTIONARY name option - 要为此字典设置的模板相关选项的名称。 + 要为此词典设置的模板相关选项的名称。 @@ -105,7 +105,7 @@ CREATE TEXT SEARCH DICTIONARY name 下面的示例命令创建了一个基于 Snowball 且使用非标准停用词列表的 - 字典。 + 词典。 diff --git a/zh/20/ref/create_tsparser.sgml b/zh/20/ref/create_tsparser.sgml index 358152ce..88be54e6 100644 --- a/zh/20/ref/create_tsparser.sgml +++ b/zh/20/ref/create_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH PARSER - 定义一个新的全文检索解析器 + 定义一个新的文本检索解析器 @@ -36,19 +36,19 @@ CREATE TEXT SEARCH PARSER name ( CREATE TEXT SEARCH PARSER创建一个 - 新的全文检索解析器。全文检索解析器定义了一种方法,用于将文本字符串 - 拆分成记号并为这些记号指定类型(类别)。解析器本身并没有太大用处, - 必须与一些全文检索字典一起绑定到一个全文检索配置中,才能用于搜索。 + 新的文本检索解析器。文本检索解析器定义了一种方法,用于将文本字符串 + 拆分成词元并为这些词元指定类型(类别)。解析器本身并没有太大用处, + 必须与一些文本检索词典一起绑定到一个文本检索配置中,才能用于搜索。 - 如果给出了一个模式名称,那么全文检索解析器将被创建在指定的模式中。 + 如果给出了一个模式名称,那么文本检索解析器将被创建在指定的模式中。 否则它会被创建在当前模式中。 要使用CREATE TEXT SEARCH PARSER,你必须是超级用户。 - 之所以有此限制,是因为错误的全文检索解析器定义可能会让服务器陷入 + 之所以有此限制,是因为错误的文本检索解析器定义可能会让服务器陷入 混乱,甚至崩溃。 @@ -65,7 +65,7 @@ CREATE TEXT SEARCH PARSER name ( name - 要创建的全文检索解析器的名称。该名称可以是模式限定的。 + 要创建的文本检索解析器的名称。该名称可以是模式限定的。 @@ -83,7 +83,7 @@ CREATE TEXT SEARCH PARSER name ( gettoken_function - 该解析器的获取下一个记号的函数名称。 + 该解析器的获取下一个词元的函数名称。 @@ -101,7 +101,7 @@ CREATE TEXT SEARCH PARSER name ( lextypes_function - 该解析器的 lextypes 函数的名称(该函数返回它所产生的记号类型集合的 + 该解析器的 lextypes 函数的名称(该函数返回它所产生的词元类型集合的 信息)。 @@ -111,7 +111,7 @@ CREATE TEXT SEARCH PARSER name ( headline_function - 该解析器的 headline 函数的名称(该函数对一组记号生成摘要)。 + 该解析器的 headline 函数的名称(该函数对一组词元生成摘要)。 diff --git a/zh/20/ref/create_tstemplate.sgml b/zh/20/ref/create_tstemplate.sgml index 702233e4..0f1b4e1a 100644 --- a/zh/20/ref/create_tstemplate.sgml +++ b/zh/20/ref/create_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE TEXT SEARCH TEMPLATE - 定义一个新的全文检索模板 + 定义一个新的文本检索模板 @@ -33,22 +33,22 @@ CREATE TEXT SEARCH TEMPLATE name ( CREATE TEXT SEARCH TEMPLATE创建一个 - 新的全文检索模板。全文检索模板定义实现全文检索字典的函数。模板本身 - 并无直接用途,必须先实例化为字典后才能使用。字典通常会指定要传递给 + 新的文本检索模板。文本检索模板定义实现文本检索词典的函数。模板本身 + 并无直接用途,必须先实例化为词典后才能使用。词典通常会指定要传递给 模板函数的参数。 - 如果给出了模式名称,则全文检索模板会被创建在指定模式中。否则它会被 + 如果给出了模式名称,则文本检索模板会被创建在指定模式中。否则它会被 创建在当前模式中。 要使用CREATE TEXT SEARCH TEMPLATE,你 - 必须是超级用户。之所以有此限制,是因为错误的全文检索模板定义可能使 - 服务器陷入混乱,甚至崩溃。将模板与字典分离的原因在于,模板封装了定 - 义字典时那些不安全的方面。而在定义字典时可设置的参数, - 对非特权用户来说是安全的,因此创建字典不必是特权操作。 + 必须是超级用户。之所以有此限制,是因为错误的文本检索模板定义可能使 + 服务器陷入混乱,甚至崩溃。将模板与词典分离的原因在于,模板封装了定 + 义词典时那些不安全的方面。而在定义词典时可设置的参数, + 由普通用户设置也是安全的,因此创建词典不必是特权操作。 @@ -64,7 +64,7 @@ CREATE TEXT SEARCH TEMPLATE name ( name - 要创建的全文检索模板名称。该名称可以是模式限定的。 + 要创建的文本检索模板名称。该名称可以是模式限定的。 diff --git a/zh/20/ref/drop_opclass.sgml b/zh/20/ref/drop_opclass.sgml index 9d67dc64..545a2517 100644 --- a/zh/20/ref/drop_opclass.sgml +++ b/zh/20/ref/drop_opclass.sgml @@ -110,7 +110,7 @@ DROP OPERATOR CLASS [ IF EXISTS ] name示例 - 移除 B-tree 操作符类widget_ops: + 移除 B-树操作符类widget_ops DROP OPERATOR CLASS widget_ops USING btree; diff --git a/zh/20/ref/drop_tsconfig.sgml b/zh/20/ref/drop_tsconfig.sgml index ea139802..b3ebb9d1 100644 --- a/zh/20/ref/drop_tsconfig.sgml +++ b/zh/20/ref/drop_tsconfig.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH CONFIGURATION - 移除一个文本搜索配置 + 移除一个文本检索配置 @@ -29,7 +29,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 描述 - DROP TEXT SEARCH CONFIGURATION删除一个现有文本搜索配置。 + DROP TEXT SEARCH CONFIGURATION删除一个现有文本检索配置。 要执行此命令,你必须是该配置的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name IF EXISTS - 如果该文本搜索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索配置不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name name - 现有文本搜索配置的名称(可以被模式限定)。 + 现有文本检索配置的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name CASCADE - 自动删除依赖于该文本搜索配置的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索配置的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name RESTRICT - 如果有任何对象依赖于该文本搜索配置,则拒绝删除该配置。这是默认值。 + 如果有任何对象依赖于该文本检索配置,则拒绝删除该配置。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name 示例 - 移除文本搜索配置my_english: + 移除文本检索配置my_english DROP TEXT SEARCH CONFIGURATION my_english; 如果已有索引在to_tsvector调用中引用了该配置, - 此命令将不会成功。加上CASCADE可以在删除该文本搜索配置的同时删除这类索引。 + 此命令将不会成功。加上CASCADE可以在删除该文本检索配置的同时删除这类索引。 diff --git a/zh/20/ref/drop_tsdictionary.sgml b/zh/20/ref/drop_tsdictionary.sgml index 316c5d00..0f7751a1 100644 --- a/zh/20/ref/drop_tsdictionary.sgml +++ b/zh/20/ref/drop_tsdictionary.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH DICTIONARY - 移除一个文本搜索字典 + 移除一个文本检索词典 @@ -29,8 +29,8 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name描述 - DROP TEXT SEARCH DICTIONARY删除一个现有文本搜索字典。 - 要执行此命令,你必须是该字典的拥有者。 + DROP TEXT SEARCH DICTIONARY删除一个现有文本检索词典。 + 要执行此命令,你必须是该词典的拥有者。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索字典不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索词典不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] namename - 一个现有文本搜索字典的名称(可以被模式限定)。 + 一个现有文本检索词典的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索字典的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索词典的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索字典,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索词典,则拒绝删除它。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name示例 - 移除文本搜索字典english: + 移除文本检索词典english DROP TEXT SEARCH DICTIONARY english; - 如果已有文本搜索配置使用该字典,此命令将不会成功。 - 加上CASCADE可以在删除字典的同时删除这类配置。 + 如果已有文本检索配置使用该词典,此命令将不会成功。 + 加上CASCADE可以在删除词典的同时删除这类配置。 diff --git a/zh/20/ref/drop_tsparser.sgml b/zh/20/ref/drop_tsparser.sgml index a65f47be..ea74f0f8 100644 --- a/zh/20/ref/drop_tsparser.sgml +++ b/zh/20/ref/drop_tsparser.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH PARSER - 移除一个文本搜索解析器 + 移除一个文本检索解析器 @@ -29,7 +29,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name描述 - DROP TEXT SEARCH PARSER删除一个现有文本搜索解析器。 + DROP TEXT SEARCH PARSER删除一个现有文本检索解析器。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索解析器不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] namename - 一个现有文本搜索解析器的名称(可以被模式限定)。 + 一个现有文本检索解析器的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索解析器的对象,以及进一步依赖于这些对象的所有对象 + 自动删除依赖于该文本检索解析器的对象,以及进一步依赖于这些对象的所有对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索解析器,则拒绝删除它。这是默认值。 + 如果有任何对象依赖于该文本检索解析器,则拒绝删除它。这是默认值。 @@ -82,13 +82,13 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] name示例 - 移除文本搜索解析器my_parser: + 移除文本检索解析器my_parser DROP TEXT SEARCH PARSER my_parser; - 如果已有文本搜索配置使用该解析器,此命令将不会成功。 + 如果已有文本检索配置使用该解析器,此命令将不会成功。 加上CASCADE可以在删除解析器的同时删除这类配置。 diff --git a/zh/20/ref/drop_tstemplate.sgml b/zh/20/ref/drop_tstemplate.sgml index fa1faab0..3a44c927 100644 --- a/zh/20/ref/drop_tstemplate.sgml +++ b/zh/20/ref/drop_tstemplate.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP TEXT SEARCH TEMPLATE - 移除一个文本搜索模板 + 移除一个文本检索模板 @@ -29,7 +29,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name描述 - DROP TEXT SEARCH TEMPLATE删除一个现有文本搜索模板。 + DROP TEXT SEARCH TEMPLATE删除一个现有文本检索模板。 要使用此命令,你必须是超级用户。 @@ -43,7 +43,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameIF EXISTS - 如果该文本搜索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 + 如果该文本检索模板不存在,则不要抛出错误。这种情况下会发出一个提示。 @@ -52,7 +52,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] namename - 现有文本搜索模板的名称(可以被模式限定)。 + 现有文本检索模板的名称(可以被模式限定)。 @@ -61,7 +61,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameCASCADE - 自动删除依赖于该文本搜索模板的对象,以及所有进一步依赖于这些对象的对象 + 自动删除依赖于该文本检索模板的对象,以及所有进一步依赖于这些对象的对象 (参见)。 @@ -71,7 +71,7 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameRESTRICT - 如果有任何对象依赖于该文本搜索模板,则拒绝删除该模板。这是默认值。 + 如果有任何对象依赖于该文本检索模板,则拒绝删除该模板。这是默认值。 @@ -82,14 +82,14 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name示例 - 移除文本搜索模板thesaurus: + 移除文本检索模板thesaurus DROP TEXT SEARCH TEMPLATE thesaurus; - 如果已有文本搜索字典使用该模板,此命令将不会成功。加上CASCADE - 可以在删除该模板的同时删除这类字典。 + 如果已有文本检索词典使用该模板,此命令将不会成功。加上CASCADE + 可以在删除该模板的同时删除这类词典。 diff --git a/zh/20/ref/initdb.sgml b/zh/20/ref/initdb.sgml index 20797adc..88bcd8ac 100644 --- a/zh/20/ref/initdb.sgml +++ b/zh/20/ref/initdb.sgml @@ -329,7 +329,7 @@ PostgreSQL documentation - 设置默认文本搜索配置。更多信息见 + 设置默认文本检索配置。更多信息见 diff --git a/zh/20/ref/pgbench.sgml b/zh/20/ref/pgbench.sgml index 17817b32..accc0837 100644 --- a/zh/20/ref/pgbench.sgml +++ b/zh/20/ref/pgbench.sgml @@ -39,7 +39,7 @@ PostgreSQL documentation 描述 - pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,必要时可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 + pgbench是一个用于对PostgreSQL执行基准测试的简单程序。它会反复执行同一组 SQL 命令,也可在多个并发数据库会话中运行,然后计算平均事务速率(每秒事务数)。默认情况下,pgbench测试的是一个大体上基于 TPC-B 的场景,每个事务包含五条SELECTUPDATEINSERT命令。不过,通过编写自己的事务脚本文件,也很容易测试其他场景。 @@ -69,7 +69,7 @@ tps = 896.967014 (without initial connection time) - 默认的类 TPC-B 事务测试要求预先建立特定的表。应使用(initialize)选项调用pgbench来创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: + 默认的类 TPC-B 事务测试要求预先建立特定的表。应使用(初始化)选项调用pgbench来创建并填充这些表。(测试自定义脚本时不需要这一步,但需要自行完成测试所需的准备工作。)初始化命令如下: pgbench -i other-options dbname @@ -89,14 +89,14 @@ pgbench -i other-options 在默认的比例因子 1 下,这些表最初包含如下行数: -table # of rows +表 行数 --------------------------------- pgbench_branches 1 pgbench_tellers 10 pgbench_accounts 100000 pgbench_history 0 - 可以使用(比例因子)选项来增加行数,而且在大多数场景下也确实应该这样做。此时还可以配合使用(fillfactor)选项。 + 可以使用(比例因子)选项来增加行数,而且在大多数场景下通常也应该这样做。此时还可以配合使用(fillfactor)选项。 @@ -116,7 +116,7 @@ pgbench options d 选项 - 下面分成三个部分。数据库初始化期间使用的选项和运行基准时会使用不同的选项,但也有一些选项在两种情况下都使用。 + 以下内容分为三个小节。数据库初始化和运行基准测试时使用不同的选项,但有些选项在这两种情况下都适用。 @@ -196,7 +196,7 @@ pgbench options d 使用G(服务器端生成数据)时, pgbench客户端只发送较小的查询,随后实际数据在服务器端生成。 - 这种方式几乎不需要额外带宽,但服务器会承担更多工作。 + 这种方式不需要大量带宽,但服务器会承担更多工作。 使用G时,生成数据期间不会打印任何进度消息。 @@ -505,13 +505,13 @@ pgbench options d 用于向服务器提交查询的协议: - simple: 使用简单查询协议。 + simple:使用简单查询协议。 - extended: 使用扩展查询协议。 + extended:使用扩展查询协议。 - prepared: 使用带有预备语句的扩展查询协议。 + prepared:使用带有预备语句的扩展查询协议。 @@ -572,7 +572,7 @@ pgbench options d - 在基准测试完成后,报告每条语句的以下统计信息:平均延迟(从客户端视角看到的语句执行时间)、失败次数,以及该语句因串行化或死锁错误而发生的重试次数。仅当选项不等于 1 时,报告才会显示重试统计信息。 + 在基准测试完成后,报告每条命令的以下统计信息:平均延迟(从客户端视角看到的语句执行时间)、失败次数,以及该命令因串行化或死锁错误而发生的重试次数。仅当选项不等于 1 时,报告才会显示重试统计信息。 @@ -607,7 +607,7 @@ pgbench options d 较高的计划滞后时间表明,在所选客户端数和线程数下,系统无法以指定速率处理事务。 当平均事务执行时间长于事务之间的计划间隔时,后续事务会不断进一步落后, - 而计划滞后时间也会随着测试持续时间增加。在这种情况下,只能降低指定的事务速率。 + 而计划滞后时间也会随着测试持续时间增加。在这种情况下,需要降低指定的事务速率。 @@ -619,7 +619,7 @@ pgbench options d pgbench输出中报告指定的比例因子。 - 对于内置测试,这通常没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 + 对于内置测试,这没有必要;系统会通过统计pgbench_branches表中的行数来检测正确的比例因子。 但在只测试自定义基准(选项)时, 除非使用此选项,否则比例因子会被报告为 1。 @@ -752,7 +752,7 @@ pgbench options d 启用对出现串行化/死锁错误的事务进行重试,并设置最大尝试次数。此选项可与 - 组合使用,后者限制所有事务尝试的总耗时; + 组合使用,后者限制同一事务所有尝试的总耗时; 此外,如果没有, 则不能使用无限次尝试(--max-tries=0)。 默认值为 1,出现串行化/死锁错误的事务不会重试。有关此类事务重试的更多信息,见 @@ -832,7 +832,7 @@ pgbench options d - 打印关于所有错误和失败的消息(即不会重试的错误),包括超出了哪一种重试限制,以及对于串行化/死锁失败超出的幅度。(请注意,这种情况下输出量可能会显著增加。)更多信息见。 + 打印关于所有错误和失败(不再重试的错误)的消息,包括超出了哪一种重试限制,以及对于串行化/死锁失败超出的幅度。(请注意,这种情况下输出量可能会显著增加。)更多信息见 @@ -960,7 +960,7 @@ pgbench options d 注解 - + 在<application>pgbench</application>中实际执行的<quote>事务</quote>是什么? @@ -1015,7 +1015,7 @@ pgbench options d - 假定pgbench脚本不包含不完整的 SQL 事务块。如果在运行时客户端在尚未完成最后一个事务块时就到达脚本末尾,它将被中止。 + 假定pgbench脚本不包含不完整的 SQL 事务块。如果在运行时客户端在尚未完成最后一个事务块时就到达脚本末尾,该客户端将被中止。 @@ -1052,7 +1052,7 @@ pgbench options d default_seed - 默认在哈希和伪随机置换函数中使用的种子 + 默认在 hash 和伪随机置换函数中使用的种子 @@ -1069,7 +1069,7 @@ pgbench options d - 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令及其参数之间以空白分隔。支持的元命令如下: + 脚本文件中的元命令以反斜线(\)开头,通常延伸到行尾,不过也可以通过写反斜线换行继续到后续行。元命令的参数以空白分隔。支持的元命令如下: @@ -1108,7 +1108,7 @@ UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid RETURNING abalance \gset --- compound of two queries +-- 两个查询的组合 SELECT 1 \; SELECT 2 AS two, 3 AS three \gset p_ SELECT 4 AS four \; SELECT 5 AS five \aset @@ -1200,7 +1200,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset - command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在其开头再写一个冒号。 + command和每个argument都可以是文本常量,也可以是引用某个变量的:variablename。如果要使用以冒号开头的argument,请在argument开头再写一个冒号。 @@ -1238,7 +1238,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset - 这组命令用于实现 SQL 语句的流水线执行。流水线必须以\startpipeline开始,并以\endpipeline结束;在两者之间可以出现任意数量的\syncpipeline,它会发送一个sync 消息,但不会结束当前流水线,同时会刷新发送缓冲区。在流水线模式下,语句会发送到服务器,而不等待前一条语句的结果。更多细节见。流水线模式要求使用扩展查询协议。 + 这组命令用于实现 SQL 语句的管道执行。管道必须以\startpipeline开始,并以\endpipeline结束;在两者之间可以出现任意数量的\syncpipeline,它会发送一个sync 消息,既不会结束当前管道,也不会刷新发送缓冲区。在管道模式下,语句会发送到服务器,而不等待前一条语句的结果。更多细节见。管道模式要求使用扩展查询协议。 @@ -1534,7 +1534,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 加 + 加法 5 + 4 @@ -1548,7 +1548,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 减 + 减法 3 - 2.0 @@ -1562,7 +1562,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 乘 + 乘法 5 * 4 @@ -1576,7 +1576,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 除法(如果两个输入都是整数,则将结果截断为零) + 除法(如果两个输入都是整数,则将结果向零截断) 5 / 3 @@ -1604,7 +1604,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset number - 取反 + 取相反数 - 2.0 @@ -1694,7 +1694,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset double - 指数(e 的给定次幂) + 指数函数(e 的给定次幂) exp(1.0) @@ -1736,7 +1736,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算 FNV-1a 哈希。 + 计算 FNV-1a hash hash_fnv1a(10, 5432) @@ -1750,7 +1750,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算 MurmurHash2 哈希。 + 计算 MurmurHash2 hash hash_murmur2(10, 5432) @@ -1820,8 +1820,8 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - i的排列值,范围在[0, size)内。 - 它表示i(模size)在整数0...size-1的伪随机排列中的新位置;该排列由seed参数化,详见下文。 + i的置换值,范围在[0, size)内。 + 它表示i(模size)在整数0...size-1的伪随机置换中的新位置;该置换由seed参数化,详见下文。 permute(0, 4) @@ -1881,7 +1881,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算[lb, ub]中的指数分布随机整数,如下所示。 + 计算[lb, ub]中的指数分布随机整数,详见下文。 random_exponential(1, 10, 3.0) @@ -1895,7 +1895,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset integer - 计算[lb, ub]中的高斯分布随机整数,如下所示。 + 计算[lb, ub]中的高斯分布随机整数,详见下文。 random_gaussian(1, 10, 2.5) @@ -1942,7 +1942,7 @@ SELECT 4 AS four \; SELECT 5 AS five \aset - 对于指数分布,parameter通过在parameter处截断一个快速衰减的指数分布,再将其投影到边界之间的整数上,从而控制分布。准确地说, + 对于指数分布,parameter通过在parameter处截断一个快速衰减的指数分布,再将其投影到边界之间的整数上,从而控制分布。准确地说,令 f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) @@ -1950,7 +1950,7 @@ f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) - 直观地说,parameter越大,越靠近min的值越容易被抽到,而越靠近max的值越不容易被抽到。parameter越接近 0,分布就越平坦(也就越均匀)。对这种分布的一个粗略近似是:范围内最靠近min的那 1% 常见值,大约会占到parameter% 的抽样次数。parameter必须严格大于 0。 + 直观地说,parameter越大,越靠近min的值越容易被抽到,而越靠近max的值越不容易被抽到。parameter越接近 0,分布就越平坦(也就越均匀)。对这种分布的一个粗略近似是:范围内出现频率最高的 1% 的值,即最靠近min的那些值,大约会占到parameter% 的抽样次数。parameter必须严格大于 0。 @@ -1962,7 +1962,7 @@ f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / (2.0 * PHI(parameter) - 1) - 则minmax(包含边界)之间的值i被抽中的概率为:f(i + 0.5) - f(i - 0.5)。直观地说,parameter越大,越靠近区间中间的值被抽到的频率越高,而越靠近minmax边界的值被抽到的频率越低。大约 67% 的值会落在区间中部1.0 / parameter这一段内,也就是均值两侧各0.5 / parameter的范围内;约 95% 的值会落在区间中部2.0 / parameter这一段内,也就是均值两侧各1.0 / parameter的范围内。例如,如果parameter为 4.0,则 67% 的值会落在区间中间四分之一(1.0 / 4.0)内,也就是从3.0 / 8.05.0 / 8.0;95% 的值会落在区间中间一半(2.0 / 4.0)内,也就是第二和第三四分位。允许的最小parameter值为 2.0。 + 则minmax(包含边界)之间的值i被抽中的概率为:f(i + 0.5) - f(i - 0.5)。直观地说,parameter越大,越靠近区间中间的值被抽到的频率越高,而越靠近minmax边界的值被抽到的频率越低。大约 67% 的值会落在区间中部1.0 / parameter这一段内,也就是均值两侧各占区间长度0.5 / parameter的范围内;约 95% 的值会落在区间中部2.0 / parameter这一段内,也就是均值两侧各占区间长度1.0 / parameter的范围内。例如,如果parameter为 4.0,则 67% 的值会落在区间中间四分之一(1.0 / 4.0)内,也就是从3.0 / 8.05.0 / 8.0;95% 的值会落在区间中间一半(2.0 / 4.0)内,也就是第二和第三四分位。允许的最小parameter值为 2.0。 @@ -1994,12 +1994,12 @@ f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / - 哈希函数hashhash_murmur2hash_fnv1a都接受一个输入值和一个可选的种子参数。 - 如果没有提供种子,则会使用:default_seed的值;除非通过命令行选项覆盖,否则该值会被随机初始化。 + Hash 函数hashhash_murmur2hash_fnv1a都接受一个输入值和一个可选的种子参数。 + 如果没有提供种子,则会使用:default_seed的值;除非通过命令行-D选项覆盖,否则该值会被随机初始化。 - permute接受一个输入值、一个大小参数以及一个可选的种子参数。它会生成范围[0, size)内整数的伪随机排列,并返回输入值在该排列中的索引。如果未指定种子,则默认使用:default_seed。与哈希函数不同,permute保证输出值中不会出现冲突或空洞。区间之外的输入值会按size取模解释。如果size不是正数,该函数会报错。permute可用于打散诸如random_zipfianrandom_exponential这类非均匀随机函数的分布,使那些更常抽到的值不再具有显而易见的相关性。例如,下面的pgbench脚本模拟了社交媒体和博客平台中一种可能的真实工作负载,其中少数账户会产生过量负载: + permute接受一个输入值、一个大小参数以及一个可选的种子参数。它会生成范围[0, size)内整数的伪随机置换,并返回输入值在该置换中的索引。所选置换由种子参数决定;如果未指定种子,则默认使用:default_seed。与 hash 函数不同,permute保证输出值中不会出现冲突或空洞。区间之外的输入值会按size取模解释。如果size不是正数,该函数会报错。permute可用于打散诸如random_zipfianrandom_exponential这类非均匀随机函数的分布,使那些更常抽到的值不再具有显而易见的相关性。例如,下面的pgbench脚本模拟了社交媒体和博客平台中一种可能的真实工作负载,其中少数账户会产生过量负载: \set size 1000000 @@ -2056,7 +2056,7 @@ END; - 每行日志文件描述一个事务。 + 日志文件的每一行描述一个事务。 它包含以下以空格分隔的字段: @@ -2466,7 +2466,7 @@ statement latencies in milliseconds and failures: 使用可串行化默认事务隔离级别的默认脚本的另一个输出示例 - (PGOPTIONS='-c default_transaction_isolation=serializable' pgbench ...): + (PGOPTIONS='-c default_transaction_isolation=serializable' pgbench ...): starting vacuum...end. transaction type: <builtin: TPC-B (sort of)> @@ -2509,7 +2509,7 @@ statement latencies in milliseconds, failures and retries: - + 失败和串行化/死锁重试 @@ -2571,7 +2571,7 @@ statement latencies in milliseconds, failures and retries: - 不指定选项时,事务在发生串行化或死锁错误后永远不会重试,因为其默认值为 1。可以使用无限次尝试(--max-tries=0)并配合选项,仅限制重试的最长时间。也可以使用选项,在无限次尝试的情况下限制基准测试持续时间。 + 不指定选项时,事务在发生串行化或死锁错误后永远不会重试,因为其默认值为 1。可以使用无限次尝试(--max-tries=0)并配合选项,仅限制尝试的最长总时间。也可以使用选项,在无限次尝试的情况下限制基准测试持续时间。 @@ -2592,7 +2592,7 @@ statement latencies in milliseconds, failures and retries: - 如果希望在逐事务日志、聚合日志以及主报告和逐脚本报告中按基本类型对失败进行分组,请使用选项。如果还希望按类型区分所有错误和失败(即不会重试的错误),包括超出了哪一种重试限制,以及串行化/死锁失败超出了多少,请使用选项。 + 如果希望在逐事务日志、聚合日志以及主报告和逐脚本报告中按基本类型对失败进行分组,请使用选项。如果还希望按类型区分所有错误和失败(不再重试的错误),包括超出了哪一种重试限制,以及串行化/死锁失败超出了多少,请使用选项。 @@ -2624,7 +2624,7 @@ PGOPTIONS='-c default_table_access_method=wuzza' - 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和空闲空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 + 默认测试场景还会对表初始化后的时间长短非常敏感:表中死元组和无效空间的累积会改变结果。要理解这些结果,必须跟踪更新总数以及何时发生清理。如果启用了自动清理,它可能会给测得的性能带来不可预测的变化。 diff --git a/zh/20/ref/psql-ref.sgml b/zh/20/ref/psql-ref.sgml index c9f3d88d..a5a2b208 100644 --- a/zh/20/ref/psql-ref.sgml +++ b/zh/20/ref/psql-ref.sgml @@ -47,7 +47,7 @@ PostgreSQL documentation - 把所有非空输入行按照它们被读入的形式打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 + 在读入时将所有非空输入行打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 all @@ -58,7 +58,7 @@ PostgreSQL documentation - 切换到非对齐输出模式(默认输出模式是对齐的)。这等效于\pset format unaligned。 + 切换到非对齐输出模式(默认输出模式是aligned)。这等效于\pset format unaligned @@ -78,10 +78,10 @@ PostgreSQL documentation - 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,直到它处理完序列中所有的选项之后终止。 + 指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与选项组合在一起。当或者被指定时,psql不会从标准输入读取命令,而是在按顺序处理完所有选项后终止。 - command必须是一个服务器完全可解析的命令字符串(即不包含psql相关的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: + command必须是一个服务器完全可解析的命令字符串(即不包含psql专有的特性)或者单个反斜线命令。因此不能在一个选项中混合SQLpsql元命令。要那样做,可以使用多个选项或者把字符串用管道输送到psql中,例如: psql -c '\x' -c 'SELECT * FROM foo;' @@ -172,7 +172,7 @@ EOF - 使用separator作为非对齐输出的域分隔符。这等效于\pset fieldsep或者\f。 + 使用separator作为非对齐输出的字段分隔符。这等效于\pset fieldsep或者\f @@ -246,7 +246,7 @@ EOF - 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。 + 指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展名。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。 @@ -266,7 +266,7 @@ EOF - 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息以及多种输出。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon。 + 指定psql应该安静地工作。默认情况下,它会打印出欢迎消息和各种提示信息。如果使用了这个选项,以上那些就都不会输出。在使用选项时,配合这个选项很有用。这等效于设置变量QUIETon @@ -286,7 +286,7 @@ EOF - 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户一个可以取消执行的选项。使用这个选项可以调试脚本。 + 运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户,并允许取消执行。使用这个选项可以调试脚本。 @@ -296,7 +296,7 @@ EOF - 运行在单行模式中,其中新行会终止一个 SQL 命令,就像分号的作用一样。 + 运行在单行模式中,其中换行符会终止一个 SQL 命令,就像分号的作用一样。 @@ -322,7 +322,7 @@ EOF - 指定要替换HTML table标签的选项。详见\pset tableattr。 + 指定要放在HTML table标签内的选项。详见\pset tableattr @@ -343,7 +343,7 @@ EOF - 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要重置一个变量,去掉等号就行。要把一个变量置为空值,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 + 执行一次变量赋值,和\set元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要取消变量的设置,去掉等号就行。要把一个变量设为空字符串,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。 @@ -405,7 +405,7 @@ EOF - 不读取启动文件(要么是系统范围的psqlrc文件,要么是用户的~/.psqlrc文件)。 + 不读取启动文件(既不读取系统范围的psqlrc文件,也不读取用户的~/.psqlrc文件)。 @@ -415,7 +415,7 @@ EOF - 设置非对齐输出的域分隔符为零字节。这等效于\pset fieldsep_zero。 + 设置非对齐输出的字段分隔符为零字节。这等效于\pset fieldsep_zero @@ -425,7 +425,7 @@ EOF - 设置非对齐输出的记录分隔符为零字节。例如,这对与xargs -0配合有关。这等效于\pset recordsep_zero。 + 设置非对齐输出的记录分隔符为零字节。例如,这有助于与xargs -0配合使用。这等效于\pset recordsep_zero @@ -438,7 +438,7 @@ EOF 这个选项只能与一个或多个和/或选项结合使用。 它会导致psql在第一个这样的选项之前发出一个BEGIN命令, 并在最后一个选项之后发出一个COMMIT命令,从而将所有命令包装成一个单独的事务。 - 如果任何命令失败且变量ON_ERROR_STOP被设置,那么会发送一个ROLLBACK命令。 + 如果任何命令失败且变量ON_ERROR_STOP被设置,则会改为发送一个ROLLBACK命令。 这确保要么所有命令都成功完成,要么不应用任何更改。 @@ -550,7 +550,7 @@ testdb=> 元命令 - 你输入到psql中的任何以未加引用的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 + 你输入到psql中的任何以未加引号的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 @@ -567,7 +567,7 @@ testdb=> - 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉尾随换行)会替换反引号中的文本。在反引号包围的文本内部,不会发生特殊引用或其他处理,只有一种例外:如果出现:variable_name,且variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会被适当地引用成单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于回车和换行字符在所有平台上都无法安全引用,当变量值中出现这类字符时,:'variable_name'这种形式会打印错误消息,并且不会替换变量值。 + 在参数中,用反引号(`)包围的文本会被视为传给 shell 的命令行。该命令的输出(去掉末尾的换行符)会替换反引号中的文本。在反引号包围的文本内部,不会进行特殊的引号处理或其他处理,但出现:variable_name时,如果variable_namepsql变量名,就会被替换为该变量的值。此外,:'variable_name'也会被替换为该变量的值,并会适当地加上引号,使其成为单个 shell 命令参数。(后一种形式几乎总是更可取,除非你非常确定变量中包含什么。)由于无法保证在所有平台上都能对回车和换行字符安全地加引号,当变量值中出现这类字符时,:'variable_name'形式会打印错误消息,并且不会替换变量值。 @@ -579,8 +579,8 @@ testdb=> - 很多元命令作用在当前查询缓冲区上。这就是一个缓冲区而已,它保存任何已经被键入但是还没有发送到服务器执行的SQL命令文本。这将包括之前输入的行以及在该元命令同一行上出现在前面的任何文本。 - + 许多元命令作用于当前查询缓冲区。这只是一个保存已输入但尚未发送到服务器执行的 SQL 命令文本的缓冲区。其中既包括先前输入的行,也包括同一行上位于元命令之前的文本。 + 许多元命令还允许在命令名后追加 x 作为选项。这会使结果以扩展模式显示,就像使用了 \x\pset expanded 一样。 @@ -594,7 +594,7 @@ testdb=> \a - 如果当前表格输出格式是不对齐,则切换为对齐;否则切换为不对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset。 + 如果当前表格输出格式是非对齐,则切换为对齐;否则切换为非对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset @@ -654,7 +654,7 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1 \c\connect [ -reuse-previous=on|off ] [ dbname [ username ] [ host ] [ port ] | conninfo ] - 建立到PostgreSQL服务器的新连接。可以使用位置语法(数据库名称、用户、主机和端口中的一个或多个)指定要使用的连接参数,也可以使用详细说明在中的conninfo连接字符串。如果没有给出参数,则使用与之前相同的参数建立新连接。 + 建立到PostgreSQL服务器的新连接。可以使用位置语法(数据库名称、用户、主机和端口中的一个或多个)指定要使用的连接参数,也可以使用conninfo连接字符串,详见。如果没有给出参数,则使用与之前相同的参数建立新连接。 @@ -670,7 +670,7 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1 默认情况下,参数在位置语法中被重用,但在给定conninfo字符串时不会被重用。 传递-reuse-previous=on-reuse-previous=off作为第一个参数将覆盖该默认设置。 如果参数被重用,则任何未明确指定为位置参数或在conninfo字符串中的参数将从现有连接的参数中获取。 - 一个例外是,如果使用位置语法将host设置更改为其先前值,则现有连接参数中存在的任何hostaddr设置将被删除。 + 一个例外是,如果使用位置语法更改host设置,使其不同于先前的值,则现有连接参数中存在的任何hostaddr设置将被删除。 此外,仅当用户、主机和端口设置未更改时,才会重用现有连接使用的任何密码。 当命令既不指定也不重用特定参数时,将使用libpq的默认值。 @@ -692,7 +692,7 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1 => \c mydb myuser host.dom 6432 => \c service=foo => \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable" -=> \c -reuse-previous=on sslmode=require -- changes only sslmode +=> \c -reuse-previous=on sslmode=require -- 仅更改 sslmode => \c postgresql://tom@localhost/mydb?application_name=myapp @@ -702,11 +702,8 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1 \C [ title ] - 设置作为查询结果打印的任何表格的标题,或取消任何这样的标题。此命令等效于 - \pset title title。(此命令的名称源自caption, - 因为它以前仅用于设置HTML表格中的标题。) - + 设置作为查询结果打印的表的标题,或取消此类标题。该命令等价于\pset title title。(此命令的名称源自caption,因为它过去只用于设置HTML表的标题。) + @@ -731,7 +728,7 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1 - 关闭指定的预备语句。空字符串表示未命名的预备语句。如果不存在该名称的预备语句,则该操作不执行任何操作。 + 关闭指定的预备语句。空字符串表示未命名的预备语句。如果不存在该名称的预备语句,则不执行任何操作。 @@ -836,46 +833,24 @@ SELECT $1 \parse stmt1 ] ] ] ] - 执行当前查询缓冲区(类似于\g)并在交叉表格中显示结果。 - 查询必须返回至少三列。 - 由colV标识的输出列成为垂直标题, - 由colH标识的输出列成为水平标题。 - colD标识要在网格中显示的输出列。 - sortcolH标识水平标题的可选排序列。 - + 执行当前查询缓冲区(与\g类似),并以交叉表网格显示结果。查询必须返回至少三列。由colV标识的输出列成为纵向表头,由colH标识的输出列成为横向表头。colD标识要在网格中显示的输出列。sortcolH标识横向表头的可选排序列。 + - 每个列规范可以是列号(从1开始)或列名。列名遵循通常的SQL大小写折叠和引用规则。如果省略, - colV被视为第1列, - colH被视为第2列。 - colH必须与 - colV不同。 - 如果未指定colD,则查询结果中必须恰好有三列, - 并且既不是colV也不是 - colH的列被视为 - colD。 - + 每个列指定都可以是列号(从 1 开始)或列名。通常的 SQL 大小写折叠和加引号规则适用于列名。如果省略,colV取第 1 列,colH取第 2 列。colH必须不同于colV。如果未指定colD,查询结果必须恰好有三列,既不是colV也不是colH的那一列被用作colD。 + - 垂直标题显示为最左侧的列,包含在列colV中找到的值, - 与查询结果中的顺序相同,但删除了重复项。 - + 纵向表头显示为最左列,包含colV列中的值,其顺序与查询结果中相同,但会移除重复值。 + - 水平标题作为第一行显示,包含在列colH中找到的值,去除重复项。 - 默认情况下,这些值按照查询结果中的顺序显示。但是,如果给定可选的sortcolH参数, - 它标识一个列,其值必须是整数,colH中的值将按照相应的 - sortcolH值排序后显示在水平标题中。 - + 横向表头显示为第一行,包含colH列中的值,并移除重复值。默认情况下,它们按查询结果中的相同顺序显示。但如果给出了可选的sortcolH参数,它所标识的列的值必须是整数,而colH中的值会按照对应的sortcolH值排序后显示在横向表头中。 + - 在交叉表格中,对于每个colH列的非重复值x, - 和每个colV列的非重复值y, - 位于交点(x,y)的单元格包含查询结果行中colD列的值, - 其中colH列的值为x, - colV列的值为y。 - 如果没有这样的行,则单元格为空。如果有多个这样的行,则报告错误。 - + 在交叉表网格中,对于colH中的每个不同值xcolV中的每个不同值y,交点(x,y)处的单元格包含查询结果中colD列的值,该结果行的colH值为xcolV值为y。如果没有这样的行,单元格为空。如果存在多条这样的行,则报错。 + @@ -897,11 +872,7 @@ SELECT $1 \parse stmt1 - 命令形式\d+与前者相同,只是会显示更多信息:例如,显示与表列相关的任何注释, - 表中 OID 的存在情况,如果关系是视图,则显示视图定义,非默认的 - 复制标识设置以及 - 如果关系具有访问方法,则显示 - 访问方法名称。 + 命令形式\d+与前者相同,但会显示更多信息,例如:表列关联的注释、表是否包含 OID、当关系为视图时的视图定义、非默认的复制标识设置,以及当关系具有访问方法时的访问方法名称。 @@ -1048,7 +1019,7 @@ SELECT $1 \parse stmt1 显示constraintoperator classoperator familyrule和 - trigger类型对象的描述。所有其他注释可以通过相应的反斜杠命令查看这些对象类型。 + trigger类型对象的描述。其他注释可通过对应对象类型的反斜线命令查看。 \dd 显示与 @@ -1162,7 +1133,7 @@ SELECT $1 \parse stmt1 列出函数,以及它们的结果数据类型、参数数据类型和函数类型,函数类型分为 agg(聚合)、normalproceduretriggerwindow。要只显示特定类型的函数,请在命令后添加相应的字母 anptw。如果指定了 pattern,则只显示名称与模式匹配的函数。任何附加参数都是类型名模式,分别与函数第一、第二等参数的类型名匹配。(匹配到的函数可以比你指定的参数更多;若要防止这种情况,可将破折号 - 写成最后一个 arg_pattern。)默认情况下,只显示用户创建的对象;提供模式或 S + class="parameter">pattern,则只显示名称与模式匹配的函数。任何附加参数都是类型名模式,分别与函数第一、第二等参数的类型名匹配。(匹配到的函数可以比你指定的参数更多;若要防止这种情况,可将连字符 - 写成最后一个 arg_pattern。)默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个函数的附加信息,包括易变性、并行安全性、所有者、安全分类、是否防漏、访问权限、语言、内部名称(仅适用于 C 和 internal 函数)以及描述。特定函数的源代码可通过 \sf 查看。 @@ -1173,7 +1144,7 @@ SELECT $1 \parse stmt1 \dF[x+] [ pattern ] - 列出文本搜索配置。如果指定了 pattern,则只显示名称与模式匹配的配置。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个配置的完整描述,包括底层文本搜索解析器以及每种记号类型对应的词典列表。 + 列出全文检索配置。如果指定了 pattern,则只显示名称与模式匹配的配置。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个配置的完整描述,包括底层全文检索解析器以及每种解析器词元类型对应的词典列表。 @@ -1182,7 +1153,7 @@ SELECT $1 \parse stmt1 \dFd[x+] [ pattern ] - 列出文本搜索词典。如果指定了 pattern,则只显示名称与模式匹配的词典。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个所选词典的附加信息,包括底层文本搜索模板和选项值。 + 列出全文检索词典。如果指定了 pattern,则只显示名称与模式匹配的词典。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个所选词典的附加信息,包括底层全文检索模板和选项值。 @@ -1191,7 +1162,7 @@ SELECT $1 \parse stmt1 \dFp[x+] [ pattern ] - 列出文本搜索解析器。如果指定了 pattern,则只显示名称与模式匹配的解析器。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个解析器的完整描述,包括底层函数和已识别的记号类型列表。 + 列出全文检索解析器。如果指定了 pattern,则只显示名称与模式匹配的解析器。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个解析器的完整描述,包括底层函数和可识别的词元类型列表。 @@ -1200,7 +1171,7 @@ SELECT $1 \parse stmt1 \dFt[x+] [ pattern ] - 列出文本搜索模板。如果指定了 pattern,则只显示名称与模式匹配的模板。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个模板的附加信息,包括底层函数名。 + 列出全文检索模板。如果指定了 pattern,则只显示名称与模式匹配的模板。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个模板的附加信息,包括底层函数名。 @@ -1210,7 +1181,7 @@ SELECT $1 \parse stmt1 \dg[Sx+] [ pattern ] - 列出数据库角色。(由于 usersgroups 的概念已经统一为 roles,此命令现在等同于 + 列出数据库角色。(由于 用户的概念已经统一为角色,此命令现在等同于 \du。)默认情况下,只显示用户创建的角色;提供 S 修饰符可包括系统角色。如果指定了 pattern,则只列出名称与模式匹配的角色。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个角色的附加信息;目前这会增加每个角色的注释。 @@ -1315,9 +1286,7 @@ SELECT $1 \parse stmt1 \drds[x] [ role-pattern [ database-pattern ] ] - 列出已定义的配置设置。这些设置可以是特定于角色、特定于数据库,或者两者兼有。role-pattern 和 - database-pattern 分别用于选择要列出的特定角色和数据库。如果省略,或者指定了 - *,则会列出所有设置,包括那些未指定角色或数据库的设置。如果在命令名后追加 x,结果会以扩展模式显示。 + 列出已定义的配置设置。这些设置可以特定于角色、特定于数据库,或同时特定于两者。role-patterndatabase-pattern分别用于选择要列出的角色和数据库。省略某个模式参数或将其指定为*时,不会按该参数筛选,还会分别包含不特定于角色或不特定于数据库的设置。如果在命令名后追加x,结果会以扩展模式显示。 @@ -1339,7 +1308,7 @@ SELECT $1 \parse stmt1 默认情况下,只显示授予用户创建角色的成员身份;提供 - S 修饰符可包括系统角色。如果指定了 pattern,则只列出名称与模式匹配的角色。如果在命令名后追加 x,结果会以扩展模式显示。 + S 修饰符可包括系统角色。如果指定了 pattern,则只列出授予名称与模式匹配的角色的成员身份。如果在命令名后追加 x,结果会以扩展模式显示。 @@ -1367,7 +1336,7 @@ SELECT $1 \parse stmt1 \dT[Sx+] [ pattern ] - 列出数据类型。如果指定了 pattern,则只列出名称与模式匹配的类型。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则每个类型都会连同其内部名称和大小一起列出;对于 enum 类型,还会显示其允许值以及相关权限。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 + 列出数据类型。如果指定了 pattern,则只列出名称与模式匹配的类型。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则每个类型都会连同其内部名称、大小和相关权限一起列出;对于 enum 类型,还会显示其允许值。默认情况下,只显示用户创建的对象;提供模式或 S 修饰符可包括系统对象。 @@ -1376,7 +1345,7 @@ SELECT $1 \parse stmt1 \du[Sx+] [ pattern ] - 列出数据库角色。(由于 usersgroups 的概念已经统一为 roles,此命令现在等同于 + 列出数据库角色。(由于 用户的概念已经统一为角色,此命令现在等同于 \dg。)默认情况下,只显示用户创建的角色;提供 S 修饰符可包括系统角色。如果指定了 pattern,则只列出名称与模式匹配的角色。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则会显示每个角色的附加信息;目前这会增加每个角色的注释。 @@ -1417,7 +1386,7 @@ SELECT $1 \parse stmt1 - \e\edit filename 行号 + \e\edit filename line_number @@ -1429,7 +1398,7 @@ SELECT $1 \parse stmt1 如果编辑文件或上一个查询后在未修改文件的情况下退出编辑器,则查询缓冲区将被清除。 否则,查询缓冲区的新内容将根据psql的正常规则重新解析, - 将整个缓冲区视为单行。任何完整的查询将立即执行;也就是说,如果查询缓冲区包含或以分号结尾, + 将整个缓冲区视为单行。任何完整的查询将立即执行;也就是说,如果查询缓冲区包含分号或以分号结尾, 则执行并从查询缓冲区中删除到该点的所有内容。查询缓冲区中剩余的内容将重新显示。 输入分号或\g发送它,或输入\r通过清除查询缓冲区来取消。 @@ -1441,7 +1410,7 @@ SELECT $1 \parse stmt1 如果指定了行号,psql将光标定位在文件或查询缓冲区的指定行上。 - 请注意,如果给出一个全是数字的参数, + 请注意,如果只给出一个全是数字的参数, psql会假定它是一个行号,而不是文件名。 @@ -1456,14 +1425,10 @@ SELECT $1 \parse stmt1 \echo text [ ... ] - - 将求值后的参数打印到标准输出,用空格分隔,并在末尾加上换行符。这对于在脚本输出中穿插信息很有用。例如: - + 将求值后的参数打印到标准输出,用空格分隔,并在末尾加上换行符。这对于在脚本输出中穿插信息很有用。例如: => \echo `date` Tue Oct 26 21:40:57 CEST 1999 - - 如果第一个参数是未引用的-n,则不会写入尾随的换行符(也不会写入第一个参数)。 - +如果第一个参数是未加引号的-n,则不会写入尾随的换行符(也不会写入第一个参数)。 @@ -1571,7 +1536,7 @@ Tue Oct 26 21:40:57 CEST 1999 - 设置未对齐查询输出的字段分隔符。默认值是竖线(|)。 + 设置非对齐查询输出的字段分隔符。默认值是竖线(|)。 它等同于\pset fieldsep @@ -1582,25 +1547,17 @@ Tue Oct 26 21:40:57 CEST 1999 \g [ (option=value [...]) ] [ filename ] \g [ (option=value [...]) ] [ |command ] - - 将当前查询缓冲区发送到服务器以执行。 - - - 如果在\g后面出现括号,则括号中包围着一个空格分隔的option=value格式选项子句的列表,这些选项子句的解释方式与\psetoptionvalue命令相同,但仅在此查询的持续时间内生效。在此列表中,不允许在=符号周围有空格,但在选项子句之间需要空格。 - 如果省略了=value,则命名的option将以与\psetoption没有显式value时相同的方式更改。 - - - 如果提供了一个filename|command参数, - 查询的输出将被写入到指定的文件或通过给定的shell命令进行传输,而不是像通常那样显示出来。只有在查询成功返回零个或多个元组时,文件或命令才会被写入,而不是在查询失败或是非数据返回的SQL命令时。 + 将当前查询缓冲区发送给服务器执行。 + 如果在\g后面出现括号,则括号中是用空格分隔的option=value格式选项子句列表。这些子句的解释方式与\pset + option + value命令相同,但仅在此查询执行期间生效。在此列表中,=符号周围不允许有空格,但选项子句之间必须有空格。如果=value被省略,则指定的option会按以下命令的方式更改:\pset option,其中不显式指定value + 如果给出了filename|command参数,查询输出就会写入指定文件,或通过管道传给指定的 shell 命令,而不是照常显示。只有当查询成功返回零个或多个元组时,才会向文件或命令写入;如果查询失败,或执行的是不返回数据的 SQL 命令,则不会写入。 如果当前查询缓冲区为空,则最近发送的查询将被重新执行。除此之外,没有任何参数的\g基本上等同于一个分号。 带有参数的\g提供了一个一次性替代\o命令的选择,并且还允许一次性调整通常由\pset设置的输出格式选项。 - - 当最后一个参数以|开头时,整行剩余部分被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分将被直接传递给shell。 - + 当最后一个参数以|开头时,该行剩余的全部内容都会被视为要执行的command,其中既不进行变量插值,也不进行反引号扩展。该行剩余部分会直接按字面传给 shell。 @@ -1609,14 +1566,9 @@ Tue Oct 26 21:40:57 CEST 1999 \gdesc - - 显示当前查询缓冲区结果的描述(即列名和数据类型)。 - 查询不会实际执行;但是,如果包含某种语法错误,该错误将以正常方式报告。 - + 显示当前查询缓冲区中查询结果的描述(即列名和数据类型)。查询并不会实际执行;不过,如果其中存在语法错误,会按通常的方式报告。 - - 如果当前查询缓冲区为空,则描述最近发送的查询。 - + 如果当前查询缓冲区为空,则改为描述最近发送的查询。 @@ -1671,37 +1623,23 @@ CREATE INDEX \gset [ prefix ] - - 将当前查询缓冲区发送到服务器,并将查询的输出存储到psql变量中 - (参见下面的)。 - 要执行的查询必须返回一行。该行的每一列都存储在一个单独的变量中,变量名与列名相同。例如: - + 将当前查询缓冲区发送给服务器,并将查询输出存入 psql 变量(参见下面的)。要执行的查询必须恰好返回一行。该行的每一列分别存入一个变量,变量名与列名相同。例如: => SELECT 'hello' AS var1, 10 AS var2 -> \gset => \echo :var1 :var2 hello 10 - - 如果指定了一个prefix, - 该字符串将被添加到查询的列名前,以创建要使用的变量名: - + 如果指定了prefix,则会将该字符串加到查询的列名前面,以构成要使用的变量名: => SELECT 'hello' AS var1, 10 AS var2 -> \gset result_ => \echo :result_var1 :result_var2 hello 10 - - 如果列的结果为NULL,则相应的变量将被取消设置,而不是被设置。 - - - 如果查询失败或者没有返回一行结果, - 则不会改变任何变量。 - - - 如果当前查询缓冲区为空,则重新执行最近发送的查询。 - + 如果某一列的结果为 NULL,则取消设置对应的变量,而不是设置它。 + 如果查询失败或没有恰好返回一行,则不会更改任何变量。 + 如果当前查询缓冲区为空,则改为重新执行最近发送的查询。 @@ -1724,7 +1662,7 @@ hello 10 给出指定SQL命令的语法帮助。如果未指定command, 则psql将列出所有可用语法帮助的命令。如果command是星号 - (*),则显示所有SQL命令的语法帮助。 + (*),则显示所有SQL命令的语法帮助。 @@ -1745,9 +1683,7 @@ hello 10 \H\html - 打开HTML查询输出格式。如果HTML格式已经打开, - 则切换回默认的对齐文本格式。此命令用于兼容性和便利性,但请参阅\pset - 有关设置其他输出选项。 + 打开HTML查询输出格式。如果HTML格式已经打开,则切换回默认的对齐文本格式。此命令是为兼容性和便利性而保留的;设置其他输出选项的方法见\pset @@ -1759,13 +1695,10 @@ hello 10 - 从文件filename中读取输入,并将其执行为 - 好像它是在键盘上键入的一样。 + 从文件filename中读取输入,并像在键盘上输入一样执行它。 - 如果filename- - (连字符),那么标准输入将被读取,直到EOF指示或\q元命令。 - 这可用于将交互式输入与文件输入交错使用。请注意,仅当在最外层级别处于活动状态时,Readline行为才会被使用。 + 如果filename-(连字符),则从标准输入读取,直到遇到 EOF 指示或\q元命令。这可用于将交互式输入与文件输入交错使用。请注意,只有在最外层启用了 Readline,此处才会使用 Readline 功能。 @@ -1785,42 +1718,26 @@ hello 10 这组命令实现了可嵌套的条件块。条件块必须以\if开始,并以\endif结束。 在两者之间可以有任意数量的\elif子句,后面可以选择性地跟着一个\else子句。 - 在形成条件块的命令之间通常会出现普通查询和其他类型的反斜杠命令。 + 在形成条件块的命令之间通常会出现普通查询和其他类型的反斜线命令。 - \if\elif命令读取它们的参数,并将其作为布尔表达式进行评估。 - 如果表达式为true,则处理将继续进行;否则,直到达到匹配的\elif、 - \else\endif为止,将跳过行。一旦\if或 - \elif测试成功,同一块中后续\elif命令的参数不会被评估,而是被视为false。 - 在\else之后的行只有在没有早期匹配的\if\elif成功时才会被处理。 + \if\elif命令读取其参数,并将其作为布尔表达式求值。如果表达式的值为true,则正常继续处理;否则,跳过后续行,直到遇到匹配的\elif\else\endif。一旦\if\elif测试成功,同一块中后续\elif命令的参数就不再求值,而是被视为假。只有前面所有匹配的\if\elif测试都未成功时,才会处理\else后面的行。 - expression参数 - 是\if\elif命令的参数, - 受变量插值和反引号扩展的影响,就像任何其他反斜杠命令参数一样。 - 之后,它被评估为一个开/关选项变量的值。因此,有效值是以下任何一个不 - 含糊的不区分大小写匹配之一: - true, false, 1, - 0, on, off, - yes, no。例如, - t, TtR - 都将被视为true。 + 与其他反斜线命令的参数一样,\if\elif命令的expression参数会经过变量插值和反引号扩展。随后,按开/关选项变量值的规则对结果求值。因此,有效值是以下值的不区分大小写且无歧义的匹配:truefalse10onoffyesno。例如,tTtR都会被视为true - 不正确评估为真或假的表达式将生成警告,并被视为假。 + 不能正确求值为真或假的表达式会产生警告,并被视为假。 - 被跳过的行会被正常解析以识别查询和反斜杠命令,但查询不会发送到服务器, - 而且除了条件命令(\if\elif, - \else\endif)之外的反斜杠命令会被忽略。 + 被跳过的行会被正常解析以识别查询和反斜线命令,但查询不会发送到服务器, + 而且除了条件命令(\if\elif、 + \else\endif)之外的反斜线命令会被忽略。 仅检查跳过行中条件命令的有效嵌套。跳过行中的变量引用不会被展开, 也不会执行反引号扩展。 - 所有给定条件块的反斜杠命令必须出现在同一个源文件中。如果在主输入文件或一个 - \include的文件上达到文件结束之前,所有本地 - \if块都没有关闭, - 那么psql将会引发错误。 + 同一个条件块的所有反斜线命令必须出现在同一个源文件中。如果主输入文件或通过\include引入的文件到达 EOF 时,仍有本地\if块未关闭,psql就会报错。 下面是一个示例: @@ -1854,17 +1771,13 @@ SELECT \ir\include_relative filename - - \ir命令类似于\i,但是解析相对文件名的方式不同。 - 在交互模式下执行时,这两个命令的行为是相同的。然而,在脚本中调用时, - \ir会将文件名解释为相对于脚本所在目录,而不是当前工作目录。 - + \ir命令与\i相似,但解析相对文件名的方式不同。在交互模式下执行时,这两个命令的行为相同。不过,在脚本中调用时,\ir会相对于脚本所在的目录来解释文件名,而不是相对于当前工作目录。 - \l[x+] or \list[x+] [ pattern ] + \l[x+]\list[x+] [ pattern ] 列出服务器中的数据库,并显示其名称、所有者、字符集编码和访问权限。如果指定了 pattern,则只列出名称与模式匹配的数据库。如果在命令名后追加 x,结果会以扩展模式显示。如果在命令名后追加 +,则还会显示数据库大小、默认表空间和描述。当前用户对其拥有 CONNECT 权限的数据库可以显示大小信息;如果当前用户是超级用户或具有 pg_read_all_stats 角色的权限,也可以显示大小信息。 @@ -1881,7 +1794,7 @@ SELECT 从数据库中读取具有OIDloid的大对象,并将其写入filename。请注意,这与服务器函数 - lo_export略有不同,后者使用数据库服务器运行的用户权限, + lo_export略有不同,后者使用运行数据库服务器的用户的权限, 并在服务器的文件系统上操作。 @@ -1897,14 +1810,10 @@ SELECT \lo_import filename [ comment ] - - 将文件存储到一个PostgreSQL大对象中。可选地,它将给定的注释与对象关联起来。例如: - + 将文件存储到一个PostgreSQL大对象中。可选地,它将给定的注释与对象关联起来。例如: foo=> \lo_import '/home/peter/pictures/photo.xcf' 'a picture of me' lo_import 152801 - - 响应表明大对象收到了对象ID 152801,这个ID可以用来在将来访问新创建的大对象。为了可读性起见,建议始终将一个可读的注释与每个对象关联起来。OID和注释都可以用\lo_list命令查看。 - +响应表明大对象获得了对象 ID 152801,这个 ID 可以用来在将来访问新创建的大对象。为便于阅读,建议始终为每个对象关联一条便于人阅读的注释。查看 OID 和注释时,可以使用\lo_list命令。 请注意,此命令与服务器端的lo_import略有不同,因为它作为本地用户在本地文件系统上操作,而不是服务器的用户和文件系统。 @@ -1927,7 +1836,7 @@ lo_import 152801 - 从数据库中删除具有OIDloid的大对象。 + 从数据库中删除OIDloid的大对象。 @@ -1943,19 +1852,12 @@ lo_import 152801 \o\out [ filename ] \o\out [ |command ] - - 安排将未来的查询结果保存到文件filename, - 或将未来的结果传输到shell命令command。 - 如果未指定参数,则查询输出重置为标准输出。 - + 将后续查询结果保存到文件filename,或通过管道传给 shell 命令command。如果没有指定参数,查询输出将恢复为标准输出。 - - 如果参数以|开头,则整个剩余部分的行被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分的行会被直接传递给shell。 - + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 - 查询结果包括从数据库服务器获取的所有表、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 + 查询结果包括从数据库服务器获取的所有表格、命令响应和通知,以及查询数据库的各种反斜杠命令的输出(例如\d);但不包括错误消息。 @@ -2031,17 +1933,9 @@ SELECT $1 \parse stmt1 \pset [ option [ value ] ] - - 这个命令设置影响查询结果表输出的选项。 - option - 指示要设置哪个选项。根据所选选项,value的语义会有所不同。 - 对于某些选项,省略value会导致该选项被切换或取消设置,具体描述在特定选项下。 - 如果没有提到这样的行为,那么省略value只会显示当前设置。 - + 这个命令设置影响查询结果表输出的选项。option指定要设置哪个选项。value的含义取决于所选的选项。对于某些选项,省略value会切换或取消设置该选项,具体见各选项的说明。如果没有提及这类行为,那么省略value只会显示当前设置。 - - \pset不带任何参数时,显示所有打印选项的当前状态。 - + 不带任何参数的\pset会显示所有打印选项的当前状态。 可调整打印选项有: @@ -2049,12 +1943,7 @@ SELECT $1 \parse stmt1 border - - value必须是一个数字。一般来说,数字越高,表格的边框和线条就越多, - 但具体细节取决于特定格式。在HTML格式中,这将直接转换为border=...属性。 - 在大多数其他格式中,只有值0(无边框)、1(内部分隔线)和2(表框)有意义,值大于2将被视为border = 2。 - latexlatex-longtable格式还允许值为3,以在数据行之间添加分隔线。 - + value必须是数字。一般来说,数字越大,表格的边框和分隔线就越多,但细节取决于具体格式。在HTML格式中,它会直接转换为border=...属性。在大多数其他格式中,只有值 0(无边框)、1(内部分隔线)和 2(表格外框)有意义,大于 2 的值会与border = 2作相同处理。latexlatex-longtable格式还允许使用值 3,以在数据行之间添加分隔线。 @@ -2067,7 +1956,7 @@ SELECT $1 \parse stmt1 零(默认值)会导致目标宽度由环境变量COLUMNS控制,或者如果未设置 COLUMNS则由检测到的屏幕宽度控制。 另外,如果columns为零,则wrapped格式仅影响屏幕输出。 - 如果columns为非零,则文件和管道输出也会被包装到该宽度。 + 如果columns为非零,则文件和管道输出也会按该宽度折行。 @@ -2087,7 +1976,7 @@ SELECT $1 \parse stmt1 display_false - 设置替代 false 值打印的字符串。默认打印 f。 + 设置替代 假值打印的字符串。默认打印 f @@ -2096,7 +1985,7 @@ SELECT $1 \parse stmt1 display_true - 设置替代 true 值打印的字符串。默认打印 t。 + 设置替代 真值打印的字符串。默认打印 t @@ -2104,63 +1993,35 @@ SELECT $1 \parse stmt1 expanded(或x - - 如果指定了value,它必须是onoff, - 这将启用或禁用扩展模式,或者是auto。 - 如果省略了value,则命令在开启和关闭设置之间切换。 - 启用扩展模式时,查询结果以两列显示,左侧是列名,右侧是数据。 - 如果数据在正常的水平模式下无法完全显示在屏幕上,则此模式很有用。 - 在自动设置中,当查询输出具有多列且宽度超过屏幕时,将使用扩展模式;否则,将使用常规模式。 - 自动设置仅在对齐和换行格式中有效。在其他格式中,它始终表现为扩展模式已关闭。 - + 如果指定了value,它必须是onoff(分别启用或禁用扩展模式),或者是auto。如果省略value,该命令会在开启和关闭设置之间切换。启用扩展模式时,查询结果以两列显示,左侧为列名,右侧为数据。如果数据在通常的横向模式下无法适应屏幕,这种模式就很有用。在自动设置下,当查询输出包含多列且宽度超过屏幕时,会使用扩展模式;否则使用常规模式。自动设置只在对齐和折行格式中有效。在其他格式中,它的行为始终与关闭扩展模式相同。 fieldsep - - 指定在未对齐的输出格式中使用的字段分隔符。这样,可以创建例如制表符分隔的输出, - 其他程序可能更喜欢。要将制表符设置为字段分隔符,请键入 - \pset fieldsep '\t'。默认字段分隔符是 - '|'(一根竖线)。 - + 指定非对齐输出格式使用的字段分隔符。这样可以创建例如制表符分隔的输出,这可能更符合其他程序的需要。要将制表符设置为字段分隔符,请输入\pset fieldsep '\t'。默认字段分隔符是'|'(竖线)。 fieldsep_zero - - 将未对齐输出格式中使用的字段分隔符设置为零字节。 - + 将非对齐输出格式使用的字段分隔符设置为零字节。 footer - - 如果指定了value, - 它必须是onoff, - 这将启用或禁用表格页脚的显示 - ((n 行)计数)。 - 如果省略了value, - 命令将切换页脚的显示或隐藏。 - + 如果指定了value,它必须是onoff,分别启用或禁用表格页脚((n rows)计数)的显示。如果省略value,该命令会切换页脚显示的开关状态。 format - - 设置输出格式为alignedasciidoc、 - csvhtmllatex、 - latex-longtabletroff-ms、 - unalignedwrapped。 - 允许使用唯一缩写。 - + 设置输出格式为alignedasciidoccsvhtmllatexlatex-longtabletroff-msunalignedwrapped。允许使用唯一缩写。 aligned格式是标准的、适合人阅读且排版整齐的文本输出;这是默认格式。 @@ -2173,12 +2034,12 @@ SELECT $1 \parse stmt1 按逗号分隔的列值输出,并应用 RFC 4180 - 中描述的引用规则。 + 中描述的加引号规则。 此输出与服务器的CSV格式的 COPY命令兼容。 - 生成包含列名的标题行,除非 + 生成包含列名的表头行,除非 tuples_only参数设置为 - on。不打印标题和页脚。 + on。不打印表格标题和页脚。 每行以系统相关的行结束字符结束, 对于类Unix系统通常是单个换行符(\n), 对于Microsoft Windows则是回车和换行序列 @@ -2186,17 +2047,14 @@ SELECT $1 \parse stmt1 可以用\pset csv_fieldsep选择逗号以外的字段分隔字符。 - wrapped格式类似于aligned,但会将宽数据值跨行包装,以使输出适合目标列宽。 - 目标宽度由columns选项下描述的方式确定。请注意,psql不会尝试包装列标题; - 因此,如果列标题所需的总宽度超过目标宽度,则wrapped格式的行为与aligned相同。 - + wrapped格式与aligned相似,但会将较宽的数据值折成多行,使输出适应目标列宽。目标宽度的确定方式见columns选项的说明。请注意,psql不会尝试对列标题折行;因此,如果列标题所需的总宽度超过目标宽度,wrapped格式的行为就与aligned相同。 - asciidochtml, - latexlatex-longtable,和 + asciidochtml、 + latexlatex-longtabletroff-ms格式生成的表格旨在包含在使用相应标记语言的文档中。 它们不是完整的文档!这在HTML中可能不是必需的,但在 - LaTeX中,则必须有一个完整的文档包装器。 + LaTeX中,则必须有一个完整文档的外层结构。 latex格式使用LaTeXtabular 环境。 latex-longtable格式需要LaTeX @@ -2216,25 +2074,19 @@ SELECT $1 \parse stmt1 - ascii样式使用普通的ASCII字符。数据中的换行使用右边边缘的+符号显示。 - 当wrapped格式将数据从一行换到下一行而没有换行符时,在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 + ascii样式使用普通的ASCII字符。数据中的换行符以右边缘的+符号表示。当wrapped格式在没有换行符的位置把数据折到下一行时,会在第一行的右边缘显示一个点(.),并在下一行的左边缘再次显示。 - old-ascii样式使用普通的ASCII字符,使用在PostgreSQL 8.4及更早版本中使用的格式样式。 - 数据中的换行符使用:符号代替左侧列分隔符显示。 - 当数据从一行换行到下一行而没有换行符时,使用;符号代替左侧列分隔符。 + old-ascii样式使用普通的ASCII字符,采用PostgreSQL 8.4 及更早版本的格式样式。数据中的换行符以替代左侧列分隔符的:符号表示。当数据在没有换行符的位置折到下一行时,则用;符号替代左侧列分隔符。 - unicode样式使用Unicode绘图字符。数据中的换行使用右边距中的回车符号显示。 - 当数据从一行换行到下一行而没有换行符时,第一行的右边距显示省略号符号, - 接着在下一行的左边距再次显示省略号符号。 + unicode样式使用 Unicode 框线绘制字符。数据中的换行符以右边缘的回车符号表示。当数据在没有换行符的位置折到下一行时,会在第一行的右边缘显示省略号符号,并在下一行的左边缘再次显示。 - 当border设置大于零时,linestyle选项还确定了用哪些字符绘制边框线。 - 普通的ASCII字符在任何地方都有效,但在识别Unicode字符的显示器上看起来更好。 + 当border设置大于零时,linestyle选项还决定用哪些字符绘制边框线。普通的ASCII字符在任何环境中都可用,但在支持 Unicode 的显示设备上,Unicode 字符更美观。 @@ -2242,24 +2094,14 @@ SELECT $1 \parse stmt1 null - - 设置要打印在空值位置的字符串。默认情况下是不打印任何内容,这很容易被误解为空字符串。 - 例如,一个人可能更喜欢\pset null '(null)'。 - + 设置用于代替空值打印的字符串。默认不打印任何内容,这很容易被误认为空字符串。例如,你可能更喜欢使用\pset null '(null)' numericlocale - - 如果指定了value, - 它必须是onoff, - 这将启用或禁用显示一个特定于区域设置的字符, - 用于将小数点左侧的数字分组。如果省略了 - value, - 命令在常规和特定于区域设置的数字输出之间切换。 - + 如果指定了value,它必须是onoff,分别启用或禁用使用区域设置特定的字符来分隔小数点左侧的数字组。如果省略value,该命令会在常规数字输出和区域设置特定的数字输出之间切换。 @@ -2267,17 +2109,11 @@ SELECT $1 \parse stmt1 pager - 控制查询和psql帮助输出时使用分页程序的方式。 - 当pager选项为off时,不使用分页程序。 - 当pager选项为on时,在适当的情况下使用分页程序,即当输出到终端且不适合在屏幕上显示时。 - pager选项也可以设置为always,这会导致分页程序用于所有终端输出,无论是否适合在屏幕上显示。 - \pset pager 不带value时,会在开启和关闭分页器之间切换。 + 控制查询和psql帮助输出是否使用分页器程序。当pager选项为off时,不使用分页器程序。当pager选项为on时,会在适当时使用分页器,即输出目标为终端且内容无法在屏幕上完整显示时。pager选项也可以设为always,这样所有终端输出都会使用分页器,无论内容是否能在屏幕上完整显示。不带value\pset pager会切换分页器的使用状态。 - 如果环境变量PSQL_PAGERPAGER被设置, - 输出将被分页传输到指定的程序。否则,将使用一个平台相关的默认程序 - (例如more)。 + 如果设置了环境变量PSQL_PAGERPAGER,需要分页的输出会通过管道传给指定程序。否则,使用与平台有关的默认程序(如more)。 @@ -2292,94 +2128,64 @@ SELECT $1 \parse stmt1 pager_min_lines - - 如果pager_min_lines设置为大于页面高度的数字, - 则除非至少有这么多行的输出要显示,否则不会调用分页程序。默认设置为0。 - + 如果将pager_min_lines设置为大于页面高度的数字,那么只有待显示的输出至少达到这么多行时,才会调用分页器程序。默认设置为 0。 recordsep - - 指定在未对齐的输出格式中使用的记录(行)分隔符。默认为换行符。 - + 指定非对齐输出格式使用的记录(行)分隔符。默认为换行符。 recordsep_zero - - 设置未对齐输出格式中使用的记录分隔符为零字节。 - + 将非对齐输出格式使用的记录分隔符设置为零字节。 tableattr(或T - - 在HTML格式中,这指定要放置在table标签内的属性。 - 这可能是cellpaddingbgcolor等。 - 请注意,这里通常不需要指定border,因为它已经由\pset border处理。 - 如果没有给出value,则取消表格属性。 - - - 在latex-longtable格式中,这控制了包含左对齐数据类型的每列的比例宽度。 - 它被指定为一个以空格分隔的值列表,例如,'0.2 0.2 0.6'。 - 未指定输出列使用最后指定的值。 - + HTML格式中,这指定要放在table标签内的属性,例如cellpaddingbgcolor。请注意,你可能不需要在这里指定border,因为\pset border已经负责处理它。如果没有给出value,则取消设置表格属性。 + latex-longtable格式中,这控制每个包含左对齐数据类型的列的宽度比例。它以空白分隔的值列表指定,例如'0.2 0.2 0.6'。未指定的输出列使用最后指定的值。 - title(或者C + title(或C - - 设置后续打印的任何表的标题。这可以用来为输出提供说明性标签。 - 如果没有给出value,则标题将被取消设置。 - + 设置随后打印的所有表格的标题。这可以为输出提供描述性标签。如果没有给出value,则取消设置标题。 tuples_only(或t - - 如果指定了value,它必须是onoff, - 这将启用或禁用仅元组模式。如果省略了value, - 命令将在常规输出和仅元组输出之间切换。常规输出包括额外信息,如列标题、标题和各种页脚。 - 在仅元组模式下,只显示实际的表数据。 - + 如果指定了value,它必须是onoff,分别启用或禁用仅元组模式。如果省略value,该命令会在常规输出和仅元组输出之间切换。常规输出包含列标题、表格标题和各种页脚等附加信息。在仅元组模式下,只显示实际的表格数据。 unicode_border_linestyle - - 设置unicode线条样式的边框绘制样式为singledouble之一。 - + unicode线条样式的边框绘制样式设置为singledouble unicode_column_linestyle - - 设置unicode线条样式的列绘制样式为singledouble之一。 - + unicode线条样式的列分隔线绘制样式设置为singledouble unicode_header_linestyle - - 设置unicode线条样式的标题绘制样式为singledouble之一。 - + unicode线条样式的表头分隔线绘制样式设置为singledouble @@ -2387,35 +2193,33 @@ SELECT $1 \parse stmt1 xheader_width - 将扩展输出的标题最大宽度设置为以下之一: + 将扩展输出的表头最大宽度设置为以下之一: full(默认值)、 columnpage整数值 - full:扩展标题不截断,其宽度与最宽的输出行相同。 + full:扩展表头不截断,其宽度与最宽的输出行相同。 - column:将标题行截断为第一列的宽度。 + column:将表头行截断为第一列的宽度。 - page:将标题行截断为终端宽度。 + page:将表头行截断为终端宽度。 - 整数值:指定标题行的确切最大宽度。 + 整数值:指定表头行的确切最大宽度。 - - 这些不同格式的示例可以在下面的中看到。 - + 这些不同格式的外观示例可参见下面的 @@ -2432,10 +2236,7 @@ SELECT $1 \parse stmt1 \q\quit - - 退出psql程序。 - 在脚本文件中,只有该脚本的执行被终止。 - + 退出psql程序。在脚本文件中,只会终止该脚本的执行。 @@ -2444,7 +2245,7 @@ SELECT $1 \parse stmt1 \qecho text [ ... ] - 这个命令与\echo命令相同,只是输出将被写入查询输出通道,由\o设置。 + 这个命令与\echo相同,只是输出会写入由\o设置的查询输出通道。 @@ -2453,9 +2254,7 @@ SELECT $1 \parse stmt1 \r\reset - - 重置(清除)查询缓冲区。 - + 重置(清空)查询缓冲区。 @@ -2542,14 +2341,9 @@ testdb=> \setenv LESS -imx4F 定义将打印到当前查询输出通道,由\o设置。 - - 目标函数可以仅通过名称指定,也可以通过名称和参数指定,例如foo(integer, text)。 - 如果有多个同名函数,则必须给出参数类型。 - + 目标函数可以只用名称指定,也可以同时给出名称和参数,例如foo(integer, text)。如果存在多个同名函数,就必须给出参数类型。 - - 如果在命令名称后添加+,则输出的行将被编号,函数体的第一行将被标记为第1行。 - + 如果在命令名后附加+,输出行会带上行号,函数体的第一行编号为 1。 与大多数其他元命令不同,整个行的剩余部分始终被视为\sf的参数, @@ -2564,8 +2358,7 @@ testdb=> \setenv LESS -imx4F - 这个命令获取并显示指定视图的定义,以CREATE OR REPLACE VIEW命令的形式。 - 定义将打印到当前查询输出通道,由\o设置。 + 这个命令获取指定视图的定义,并以CREATE OR REPLACE VIEW命令的形式显示。定义会打印到由\o设置的当前查询输出通道。 @@ -2590,7 +2383,7 @@ testdb=> \setenv LESS -imx4F - 这组命令实现 SQL 语句的管道化。一个管道必须以 \startpipeline 开始,并以 \endpipeline 结束。其间可以出现任意数量的 \syncpipeline 命令,它会发送一条同步消息,但不会结束当前管道,并会刷新发送缓冲区。在管道模式下,语句会被发送到服务器,而不等待前面语句的结果。更多细节见 。 + 这组命令实现 SQL 语句的管道化。一个管道必须以 \startpipeline 开始,并以 \endpipeline 结束。其间可以出现任意数量的 \syncpipeline 命令,它会发送一条同步消息,而不会结束当前管道,也不会刷新发送缓冲区。在管道模式下,语句会被发送到服务器,而不等待前面语句的结果。更多细节见 @@ -2639,10 +2432,7 @@ SELECT 1 \bind \sendpipeline \t - - 切换显示输出列名标题和行数页脚。此命令等效于\pset tuples_only, - 仅为方便起见提供。 - + 切换输出中的列名标题和行数页脚的显示状态。这个命令等价于\pset tuples_only,提供它是为了使用方便。 @@ -2650,10 +2440,7 @@ SELECT 1 \bind \sendpipeline \T table_options - - 指定在table标签中放置的属性,在HTML输出格式中。 - 该命令等效于\pset tableattr table_options。 - + 指定在HTML输出格式中放在table标签内的属性。这个命令等价于\pset tableattr table_options @@ -2661,10 +2448,7 @@ SELECT 1 \bind \sendpipeline \timing [ on | off ] - - 使用参数,打开或关闭显示每个SQL语句执行时间的功能。没有参数时,切换显示开关。 - 显示的时间单位为毫秒;超过1秒的时间间隔也以分钟:秒的格式显示,如有必要还会显示小时和天。 - + 带参数时,开启或关闭每条 SQL 语句执行耗时的显示。不带参数时,切换显示的开关状态。耗时以毫秒显示;超过 1 秒的时间间隔还会以分钟:秒的格式显示,必要时添加小时和天字段。 @@ -2691,15 +2475,9 @@ SELECT 1 \bind \sendpipeline \unset name - - 取消设置(删除)psql变量name。 - + 取消设置(删除)psql变量name - - 大多数控制psql行为的变量不能被取消设置;相反,\unset命令被解释为将它们设置为默认值。 - 请参见下面的。 - + 大多数控制psql行为的变量不能取消设置;对于这些变量,\unset命令会被解释为将其设置为默认值。参见下面的 @@ -2708,15 +2486,9 @@ SELECT 1 \bind \sendpipeline \w\write filename \w\write |command - - 将当前查询缓冲区写入文件filename,或者通过管道传给 shell 命令command。 - 如果当前查询缓冲区为空,则写入最近执行的查询。 - + 将当前查询缓冲区写入文件filename,或通过管道传递给 shell 命令command。如果当前查询缓冲区为空,则改为写入最近执行的查询。 - - 如果参数以|开头,则整个剩余部分的行被视为要执行的command, - 在其中不进行变量插值或反引号扩展。其余部分的行会被直接传递给shell。 - + 如果参数以|开头,则该行剩余的全部内容会被视为要执行的command,其中不会进行变量插值或反引号扩展。该行剩余的内容只会原样传递给 shell。 @@ -2750,9 +2522,7 @@ SELECT 1 \bind \sendpipeline \x [ on | off | auto ] - - 设置或切换扩展表格格式模式。因此,它等同于\pset expanded。 - + 设置或切换扩展表格格式模式。它等价于\pset expanded @@ -2775,13 +2545,11 @@ SELECT 1 \bind \sendpipeline \! [ command ] - 不带参数时,转义到一个子shell;psql在子shell退出时恢复。 - 带参数时,执行shell命令command。 + 不带参数时,进入一个子 shell;子 shell 退出后,psql恢复运行。带参数时,执行 shell 命令command - 与大多数其他元命令不同,整个行的剩余部分始终被视为\!的参数, - 在参数中不执行变量插值或反引号扩展。行的其余部分被直接传递给shell。 + 与大多数其他元命令不同,该行剩余的全部内容始终被视为\!的参数,其中不会进行变量插值或反引号扩展。该行剩余内容会原样传给 shell。 @@ -2793,7 +2561,7 @@ SELECT 1 \bind \sendpipeline 显示帮助信息。可选的topic参数 (默认为commands)选择要解释的psql的哪个部分: - commands描述psql的反斜杠命令; + commands描述psql的反斜线命令; options描述可以传递给psql的命令行选项; 而variables显示关于psql配置变量的帮助。 @@ -2805,7 +2573,7 @@ SELECT 1 \bind \sendpipeline \; - 反斜杠分号不像前面的命令那样是一个元命令;相反,它只是在不进行进一步处理的情况下将一个分号添加到查询缓冲区中。 + 反斜线分号不像前面的命令那样是一个元命令;相反,它只是在不进行进一步处理的情况下将一个分号添加到查询缓冲区中。 @@ -2817,8 +2585,8 @@ SELECT 1; SELECT 2; SELECT 3; SELECT 1\; SELECT 2\; SELECT 3; - 在到达非反斜杠分号时将三个SQL命令发送到服务器的单个请求中。 - 服务器将执行此类请求作为单个事务,除非字符串中包含明确的BEGIN/COMMIT命令将其分成多个事务。(有关服务器如何处理多查询字符串的更多详细信息,请参见。) + 会在遇到前面没有反斜线的分号时,将这三个 SQL 命令作为单个请求发送到服务器。 + 服务器会将此类请求作为单个事务执行,除非字符串中包含显式的BEGIN/COMMIT命令将其分成多个事务。(有关服务器如何处理多查询字符串的更多详细信息,请参见。) @@ -2826,16 +2594,16 @@ SELECT 1\; SELECT 2\; SELECT 3; - + 模式 - patterns + 模式 在 psql 和 pg_dump 中 - 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要把它写成两个相邻的双引号,这同样是符合 SQL 引用标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你不能只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 + 很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要在双引号包围的文本内把它写成两个相邻的双引号,这同样是符合 SQL 加引号标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你可以只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 @@ -2847,21 +2615,15 @@ SELECT 1\; SELECT 2\; SELECT 3; - 包含点(.)的关系模式被解释为模式名称后跟对象名称模式。例如, - \dt foo*.*bar*显示所有位于模式名以foo开头的模式中、且表名包含bar的表。当没有出现点时,模式仅匹配当前模式搜索路径中可见的对象。 - 再次,双引号内的点失去其特殊含义,被视为字面匹配。包含两个点(.)的关系模式 - 被解释为数据库名称后跟模式名称后跟对象名称模式。数据库名称部分不会被视为模式,必须匹配当前连接的数据库名称, - 否则将引发错误。 + 如果用于匹配关系名的模式包含一个点(.),则会被解释为模式名的匹配模式,后接对象名的匹配模式。例如,\dt foo*.*bar*会显示所有位于模式名以foo开头的模式中、且表名包含bar的表。如果没有点,则只匹配当前模式搜索路径中可见的对象。同样,双引号内的点会失去特殊含义,按字面匹配。如果用于匹配关系名的模式包含两个点(.),则会被解释为数据库名、模式名的匹配模式和对象名的匹配模式。数据库名部分不会被当作匹配模式,必须与当前连接的数据库名相同,否则会报错。 - 包含一个点(.)的模式被解释为数据库名称后跟模式的模式名称。例如, - \dn mydb.*foo*显示所有包含foo的模式。数据库名称部分不会被视为模式, - 必须匹配当前连接数据库的名称,否则将引发错误。 + 如果用于匹配模式名的模式包含一个点(.),则会被解释为数据库名,后接模式名的匹配模式。例如,\dn mydb.*foo*会显示名称中包含foo的所有模式。数据库名部分不会被当作匹配模式,必须与当前连接的数据库名相同,否则会报错。 - 高级用户可以使用字符类等正则表达式记法,如[0-9]可以匹配任意数字。所有的正则表达式特殊字符都按照所说的工作,以下字符除外:.会按照上面所说的作为一种分隔符,*会被翻译成正则表达式记号.*?会被翻译成.,而$则按字面意思匹配。根据需要,可以通过书写?(R+|)(R|)R?来分别模拟模式字符.R*R?$不需要作为一个正则表达式字符,因为模式必须匹配整个名称,而不是像正则表达式的常规用法那样解释(换句话说,$会被自动地追加到模式上)。如果不希望该模式的匹配位置被固定,可以在开头或者结尾写上*。注意在双引号内,所有的正则表达式特殊字符会失去其特殊含义并且按照其字面意思进行匹配。还有,在操作符名称模式中(即作为\do的参数),正则表达式特殊字符也按照字面意思进行匹配。 + 高级用户可以使用字符类等正则表达式记法,如[0-9]可以匹配任意数字。所有的正则表达式特殊字符都按照所说的工作,以下字符除外:.会按照上面所说的作为一种分隔符,*会被翻译成正则表达式记号.*?会被翻译成.,而$则按字面意思匹配。根据需要,可以通过书写?(R+|)(R|)来分别模拟模式字符.R*R?$不需要作为一个正则表达式字符,因为模式必须匹配整个名称,而不是像正则表达式的常规用法那样解释(换句话说,$会被自动地追加到模式上)。如果不希望该模式的匹配位置被固定,可以在开头或者结尾写上*。注意在双引号内,所有的正则表达式特殊字符会失去其特殊含义并且按照其字面意思进行匹配。还有,在操作符名称模式中(即作为\do的参数),正则表达式特殊字符也按照字面意思进行匹配。 @@ -2869,7 +2631,7 @@ SELECT 1\; SELECT 2\; SELECT 3; 高级特性 - + 变量 @@ -2890,7 +2652,7 @@ bar - 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要重置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 + 如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要取消设置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。 @@ -2904,7 +2666,7 @@ bar - 控制psql行为的变量通常不能被重置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse。 + 控制psql行为的变量通常不能被取消设置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse @@ -2922,7 +2684,7 @@ bar - 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被重置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交打开模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身即不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 + 在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被取消设置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交关闭模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身既不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。 @@ -2952,7 +2714,7 @@ bar DBNAME - 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -2961,7 +2723,7 @@ bar ECHO - 如果被设置为all,所有非空输入行会被按照读入它们的样子打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被重置或者设置为none(默认值)则不会显示任何查询。 + 如果被设置为all,所有非空输入行会在读入时打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是。如果被设置为none(默认值)则不会显示任何查询。 @@ -2979,7 +2741,7 @@ bar ENCODING - 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者重置。 + 当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者取消设置。 @@ -2997,12 +2759,12 @@ bar FETCH_COUNT - 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每一组就会包括这么多个行。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 + 如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每组包含的行数等于该整数值。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。 - 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT个行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 + 尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。 @@ -3031,7 +2793,7 @@ bar HISTCONTROL - 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则匹配之前的历史行的行不会被放入。值ignoreboth组合了上述两种值。如果被重置或者被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 + 如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则与上一条历史记录相同的行不会被放入。值ignoreboth组合了上述两种值。如果被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。 @@ -3045,7 +2807,7 @@ bar HISTFILE - 该文件名将被用于存储历史列表。如果被重设,文件名将从PSQL_HISTORY环境变量中取得。如果该环境变量也没有被设置,则默认值是~/.psql_history,在Windows上是%APPDATA%\postgresql\psql_history。例如, + 该文件名将被用于存储历史列表。如果未设置该变量,文件名将从PSQL_HISTORY环境变量中取得。如果该环境变量也没有被设置,则默认值是~/.psql_history,在Windows上是%APPDATA%\postgresql\psql_history。例如, \set HISTFILE ~/.psql_history-:DBNAME @@ -3077,7 +2839,7 @@ bar HOST - 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器主机。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -3086,7 +2848,7 @@ bar IGNOREEOF - 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须键入多个连续的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 + 如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是ControlD)将会终止应用。如果设置为一个较大的数字值,则必须连续键入与该数值相等数量的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。 @@ -3100,8 +2862,8 @@ bar LASTOID - 最后被影响的 OID 的值,这可能会由INSERT或者\lo_import命令返回。这个变量只保证在下一个SQL命令被显示完之前有效。 - PostgreSQL 服务器从12版开始不再支持 OID 系统列,因此,在面向此类服务器时,跟随在INSERT后面的 LASTOID 将始终为0。 + 最后被影响的 OID 的值,这可能会由INSERT或者\lo_import命令返回。这个变量仅保证在下一个SQL命令的结果显示完之前有效。 + PostgreSQL 服务器从12版开始不再支持 OID 系统列,因此,在面向此类服务器时,执行INSERT后的 LASTOID 将始终为0。 @@ -3126,7 +2888,7 @@ bar - 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被重置或者设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 + 当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。 @@ -3144,7 +2906,7 @@ bar PIPELINE_COMMAND_COUNT - 正在运行的管道中排队的命令数 。 + 正在运行的管道中排队的命令数。 @@ -3164,7 +2926,7 @@ bar PIPELINE_SYNC_COUNT - 正在运行的管道中排队的同步消息数量 。 + 正在运行的管道中排队的同步消息数量。 @@ -3173,7 +2935,7 @@ bar PORT - 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或重置。 + 当前连接到的数据库服务器端口。每次连接到数据库时都会设置该变量(包括程序启动时),但也可以被更改或取消设置。 @@ -3212,7 +2974,7 @@ bar SERVER_VERSION_NUM - 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者重设。 + 字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者取消设置。 @@ -3241,7 +3003,7 @@ bar 如果最后一个 shell 命令失败,则为 true;如果成功,则为 false。这适用于通过 \!\g\o\w - 和 \copy 元命令调用的 shell 命令,也适用于反引号(`)展开。请注意,对于 \o,该变量会在下一个 \o 命令关闭输出管道时更新。 + 和 \copy 元命令调用的 shell 命令,也适用于反引号(`)扩展。请注意,对于 \o,该变量会在下一个 \o 命令关闭输出管道时更新。 另见 SHELL_EXIT_CODE @@ -3253,7 +3015,7 @@ bar 最后一个 shell 命令返回的退出状态。0–127 表示程序退出码,128–255 表示因信号而终止,-1 表示未能启动程序或未能取得其退出状态。这适用于通过 \!\g\o\w - 和 \copy 元命令调用的 shell 命令,也适用于反引号(`)展开。请注意,对于 \o,该变量会在下一个 \o 命令关闭输出管道时更新。 + 和 \copy 元命令调用的 shell 命令,也适用于反引号(`)扩展。请注意,对于 \o,该变量会在下一个 \o 命令关闭输出管道时更新。 另见 SHELL_ERROR @@ -3273,7 +3035,7 @@ bar SHOW_CONTEXT - 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT域。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 + 这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT字段。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 当VERBOSITY被设置为tersesqlstate时,这个设置无效(另见\errverbose,它可以用来得到刚遇到的错误的详细信息)。 @@ -3292,7 +3054,7 @@ bar SINGLESTEP - 设置这个变量为on等效于命令选项。 + 设置这个变量为on等效于命令行选项 @@ -3310,7 +3072,7 @@ bar USER - 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。 + 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者取消设置。 @@ -3319,7 +3081,7 @@ bar VERBOSITY - 这个变量可以被设置为值defaultverboseterse或者sqlstate来控制错误报告的详细程度(另见\errverbose,在想得到之前的错误的详细版本时使用)。 + 这个变量可以被设置为值defaultverboseterse或者sqlstate来控制错误报告的详细程度(另见\errverbose,在想得到刚遇到的错误的详细信息时使用)。 @@ -3330,7 +3092,7 @@ bar VERSION_NUM - 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或重设。 + 这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或取消设置。 @@ -3348,11 +3110,11 @@ bar - - <acronym>SQL</acronym> 中插入变量 + + <acronym>SQL</acronym> 插值 - psql变量的一个关键特性是可以把它们替换(插入)到常规SQL语句中,也可以把它们作为元命令的参数。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。插入一个值而不加引号的语法是在变量名前面加上一个冒号(:)。例如, + psql变量的一个关键特性是可以把它们替换(插值)到常规SQL语句中,也可以把它们替换到元命令的参数中。此外,psql还提供了功能来确保被用作 SQL 字面量和标识符的变量值会被正确地加引号。不加引号地插值一个值的语法是在变量名前面加上一个冒号(:)。例如, testdb=> \set foo 'my_table' testdb=> SELECT * FROM :foo; @@ -3361,7 +3123,7 @@ testdb=> SELECT * FROM :foo; - 当一个值被用作 SQL 文本或者标识符时,最安全的是把它加上引用。要引用一个变量的值作为 SQL 文本,可以把变量名称放在单引号中并且在引号前面写一个冒号。要引用作为 SQL 标识符,则可以把变量名称放在双引号中并且在引号前面写一个冒号。这种结构可以正确地处理变量值中嵌入的引号和其他特殊字符。之前的示例用这种方法写会更安全: + 当一个值要用作 SQL 字面量或标识符时,最安全的做法是为它加上引号。要将变量值作为 SQL 字面量加引号,应写一个冒号,后面跟用单引号括起来的变量名。要将变量值作为 SQL 标识符加引号,则在冒号后面用双引号括起变量名。这些写法能正确处理变量值中嵌入的引号和其他特殊字符。前面的示例可用以下更安全的写法: testdb=> \set foo 'my_table' testdb=> SELECT * FROM :"foo"; @@ -3369,11 +3131,11 @@ testdb=> SELECT * FROM :"foo"; - 在被引用的SQL文本和标识符中将不会执行变量插入。因此,一个诸如':foo'的结构不会从一个变量的值产生一个被引用的文本(即便能够也会不安全,因为无法正确地处理嵌入在值中的引号)。 + 在加引号的SQL字面量和标识符内部,不会执行变量插值。因此,':foo'这样的写法不能根据变量值生成加引号的字面量(即使能够生效,也不安全,因为它无法正确处理变量值中嵌入的引号)。 - 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个被引用的字符串插入: + 使用这种机制的一个示例是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个加引号的字符串进行插值: testdb=> \set content `cat my_file.txt` testdb=> INSERT INTO my_table VALUES (:'content'); @@ -3382,7 +3144,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 因为冒号可以合法地出现在 SQL 命令中,一次明显的插入尝试(即:name:'name'或者:"name")不会被替换,除非所提及的变量就是当前被设置的。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 + 因为冒号可以合法地出现在 SQL 命令中,一次明显的插值尝试(即:name:'name'或者:"name")不会被替换,除非所指的变量当前已设置。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。 @@ -3390,12 +3152,12 @@ testdb=> INSERT INTO my_table VALUES (:'content'); - 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 文本或者标识符的冒号引用语法是一种psql扩展。 + 变量的冒号语法对嵌入式查询语言(例如ECPG)来说是标准的SQL。用于数组切片和类型转换的冒号语法是PostgreSQL扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 字面量或者标识符的冒号加引号语法是一种psql扩展。 - + 提示符 @@ -3409,33 +3171,26 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %M - - 数据库服务器的完整主机名(带域名);如果连接通过 Unix 域套接字建立,则为 [local];如果 Unix 域套接字不在编译时默认位置,则为 [local:/dir/name]。 - + 数据库服务器的完整主机名(含域名);如果通过 Unix 域套接字连接,则为[local];如果 Unix 域套接字不在编译时指定的默认位置,则为[local:/dir/name] %m - - 数据库服务器的主机名,在第一个点处分截;如果连接通过 Unix 域套接字建立,则为 [local]。 - + 数据库服务器的主机名,在第一个点号处截断;如果通过 Unix 域套接字连接,则为[local] %> - 数据库服务器正在监听的端口号。 + 数据库服务器监听的端口号。 %n - - 数据库会话用户名。(由于 SET SESSION - AUTHORIZATION 命令的作用,该值在数据库会话期间可能会发生变化。) - + 数据库会话用户名。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) @@ -3469,11 +3224,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %# - - 如果会话用户是数据库超级用户,则输出 - #,否则输出 >。(由于 SET SESSION - AUTHORIZATION 命令的作用,该值的展开在数据库会话期间可能会发生变化。) - + 如果会话用户是数据库超级用户,则为#,否则为>。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。) @@ -3499,7 +3250,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %R - 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 dollar-quoted 字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 + 在提示符 1 中,通常为 =;但如果会话处于条件块的非活动分支中,则为 @;如果处于单行模式,则为 ^;如果会话已与数据库断开连接(这可能发生在 \connect 失败时),则为 !。在提示符 2 中,%R 会被替换为一个字符,该字符取决于 psql 为什么还期待更多输入:如果命令只是尚未终止,则为 -;如果存在未结束的 /* ... */ 注释,则为 *;如果存在未结束的带引号字符串,则为单引号;如果存在未结束的带引号标识符,则为双引号;如果存在未结束的 美元引用字符串,则为美元符号;如果存在未匹配的左括号,则为 (。在提示符 3 中,%R 不会产生任何输出。 @@ -3540,7 +3291,7 @@ testdb=> INSERT INTO my_table VALUES (:'content'); %digits - 带有所示八进制码的字符被替换。 + 替换为指定八进制代码对应的字符。 @@ -3642,14 +3393,14 @@ $endif - )命令行选项也可用于在单次运行psql时禁用 Readline。这会阻止制表补全、命令行历史的使用或记录,以及多行命令的编辑。当你需要复制粘贴包含 TAB 字符的文本时,它尤其有用。 + )命令行选项也可用于在单次运行psql时禁用 Readline。这会阻止TAB 补全、命令行历史的使用或记录,以及多行命令的编辑。当你需要复制粘贴包含 TAB 字符的文本时,它尤其有用。 - + 环境 @@ -3734,9 +3485,9 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 如果查询结果无法在屏幕上显示完整,它们将通过此命令进行传输。典型的值是moreless。 + 如果查询结果无法在屏幕上显示完整,它们会通过管道传给此命令。典型的值是moreless。 可以通过将PSQL_PAGERPAGER设置为空字符串,或通过调整\pset命令的与分页相关的选项来禁用分页器。 - 这些变量按照列出的顺序进行检查;首先设置的变量将被使用。 + 这些变量按照列出的顺序进行检查;使用按该顺序找到的第一个已设置的变量。 如果它们都没有设置,默认情况下在大多数平台上使用more,但在Cygwin上使用less @@ -3816,7 +3567,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' 在任何情况下,可以通过设置PSQLRC环境变量来覆盖此默认文件路径。 - 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加破折号和PostgreSQL的主要或次要版本标识符来使其与psql版本相关, + 系统范围的启动文件和用户个人的启动文件都可以通过在文件名后附加连字符和PostgreSQL的大版本或小版本标识符来使其与psql版本相关, 例如~/.psqlrc-&majorversion;~/.psqlrc-&version;。 最具体版本匹配的文件将优先读取,而不是非特定版本的文件。 这些版本后缀是在确定文件路径后添加的,如上所述。 @@ -3844,14 +3595,14 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - psql最适合与相同或较旧主要版本的服务器配合使用。 - 如果服务器的版本比psql本身更新,反斜杠命令特别容易失败。 - 然而,\d系列的反斜杠命令应该可以在版本回溯到10的服务器上运行, + psql最适合与相同或较旧大版本的服务器配合使用。 + 如果服务器的版本比psql本身更新,反斜线命令特别容易失败。 + 然而,\d系列的反斜线命令应该可以在最低至 10 版本的服务器上运行, 但不一定适用于比psql本身更新的服务器。运行SQL命令和显示查询结果的一般功能 - 也应该可以在更新主要版本的服务器上运行,但不能保证在所有情况下都能实现。 + 也应该可以在更新大版本的服务器上运行,但不能保证在所有情况下都能实现。 - 如果你想用psql连接到多个具有不同主版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个主版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 + 如果你想用psql连接到多个具有不同大版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个大版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。 @@ -3865,7 +3616,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' - 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空格。现在则要求一些空格。 + 在PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空白。现在则要求用空白分隔。 diff --git a/zh/20/rowtypes.sgml b/zh/20/rowtypes.sgml index 6c0490d5..23681bae 100644 --- a/zh/20/rowtypes.sgml +++ b/zh/20/rowtypes.sgml @@ -75,7 +75,7 @@ CREATE TABLE inventory_item ( - 构造组合值 + 构造复合值 复合类型 @@ -83,7 +83,7 @@ CREATE TABLE inventory_item ( - 要把组合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,组合常量的一般格式如下: + 要把复合值写成字面常量,请将各字段值放在圆括号内,并用逗号分隔。你可以给任意字段值加双引号;如果它包含逗号或圆括号,则必须这样做。(更多细节见下文。)因此,复合常量的一般格式如下: '( val1 , val2 , ... )' @@ -103,11 +103,11 @@ CREATE TABLE inventory_item ( - (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。必要时可能需要显式指定类型。) + (这些常量实际上只是中讨论的通用类型常量的一种特例。该常量最初会被当作字符串处理,然后传递给复合类型输入转换例程。可能需要显式指定类型,以指明应将该常量转换为哪种类型。) - ROW表达式语法也可以用于构造组合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: + ROW表达式语法也可以用于构造复合值。在大多数情况下,它比字符串字面量语法简单得多,因为你不必担心多层引号。我们在上文已经用过这种方法: ROW('fuzzy dice', 42, 1.99) ROW('', 42, NULL) @@ -126,7 +126,7 @@ ROW('', 42, NULL) 访问复合类型 - 要访问组合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: + 要访问复合列中的某个字段,可以写一个点号再加字段名,这很像通过表名选取字段。实际上,它与通过表名选取字段太像了,以至于你通常必须使用圆括号,以免让解析器混淆。例如,你可能尝试从示例表on_hand中选取一些子字段: SELECT item.name FROM on_hand WHERE item.price > 9.99; @@ -148,7 +148,7 @@ SELECT (on_hand.item).name FROM on_hand WHERE (on_hand.item).price > 9.99; - 无论何时从组合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回组合值的函数结果中只选取一个字段,你需要这样写: + 无论何时从复合值中选择字段,都会遇到类似的语法问题。例如,要从一个返回复合值的函数结果中只选取一个字段,你需要这样写: SELECT (my_func(...)).field FROM ... @@ -164,10 +164,10 @@ SELECT (my_func(...)).field FROM ... - 修改组合值 + 修改复合类型 - 下面是一些插入和更新组合列时正确语法的示例。先看插入或更新整个列值的情况: + 下面是一些插入和更新复合列时正确语法的示例。先看插入或更新整个列值的情况: INSERT INTO mytab (complex_col) VALUES((1.1,2.2)); @@ -179,7 +179,7 @@ UPDATE mytab SET complex_col = ROW(1.1,2.2) WHERE ...; - 我们也可以更新组合列中的单个子字段: + 我们也可以更新复合列中的单个子字段: UPDATE mytab SET complex_col.r = (complex_col).r + 1 WHERE ...; @@ -208,11 +208,11 @@ INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2); - 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的组合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: + 在PostgreSQL中,查询中对表名(或别名)的引用,实际上就是对该表当前行的复合值的引用。例如,如果我们有一个如上文所示的表inventory_item,就可以写: SELECT c FROM inventory_item c; - 这个查询会产生一个单独的组合值列,因此我们可能得到如下输出: + 这个查询会产生一个单独的复合值列,因此我们可能得到如下输出: c ------------------------ @@ -223,7 +223,7 @@ SELECT c FROM inventory_item c; - 普通的限定列名语法table_name.column_name可以理解为对该表当前行的组合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) + 普通的限定列名语法table_name.column_name可以理解为对该表当前行的复合值进行字段选择。(出于效率原因,实际上并不是这样实现的。) @@ -256,19 +256,19 @@ SELECT (myfunc(x)).a, (myfunc(x)).b, (myfunc(x)).c FROM some_table; SELECT m.* FROM some_table, LATERAL myfunc(x) AS m; - 把该函数放在LATERAL FROM项中,可以防止它对每一行被调用多于一次。m.*仍会展开为m.a, m.b, m.c,但现在这些变量只是对该FROM项输出的引用。(这里的LATERAL关键字其实是可选的,不过我们把它写出来,是为了明确该函数会从some_table中取得x。) + 把该函数放在LATERAL FROM项中,可以避免它在每行上被调用多次。m.*仍会展开为m.a, m.b, m.c,但现在这些变量只是对该FROM项输出的引用。(这里的LATERAL关键字其实是可选的,不过我们把它写出来,是为了明确该函数会从some_table中取得x。) - 当composite_value.*出现在SELECT输出列表、INSERT/UPDATE/DELETE/MERGE中的RETURNING列表、VALUES子句或行构造器的顶层时,就会产生这种列展开行为。在所有其他上下文中(包括嵌套在上述结构之内时),给组合值附加.*不会改变其值,因为它表示所有列,因此结果仍然是同一个组合值。例如,如果somefunc()接受一个组合值参数,这些查询就是等价的: + 当composite_value.*出现在SELECT输出列表、INSERT/UPDATE/DELETE/MERGE中的RETURNING列表、VALUES子句或行构造器的顶层时,就会产生这种列展开行为。在所有其他上下文中(包括嵌套在上述结构之内时),给复合值附加.*不会改变其值,因为它表示所有列,因此结果仍然是同一个复合值。例如,如果somefunc()接受一个复合值参数,这些查询就是等价的: SELECT somefunc(c.*) FROM inventory_item c; SELECT somefunc(c) FROM inventory_item c; - 在这两种情况下,inventory_item的当前行都会作为单个组合值参数传递给该函数。尽管.*在这种场合并不起作用,使用它仍是一种良好风格,因为它能明确表明这里想要的是组合值。特别是,解析器会把c.*中的c视为表名或别名,而不是列名,因此不会产生歧义;而没有.*时,就不清楚c究竟表示表名还是列名,而且如果存在名为c的列,实际上会优先按列名解释。 + 在这两种情况下,inventory_item的当前行都会作为单个复合值参数传递给该函数。尽管.*在这种场合并不起作用,使用它仍是一种良好风格,因为它能明确表明这里想要的是复合值。特别是,解析器会把c.*中的c视为表名或别名,而不是列名,因此不会产生歧义;而没有.*时,就不清楚c究竟表示表名还是列名,而且如果存在名为c的列,实际上会优先按列名解释。 @@ -278,7 +278,7 @@ SELECT * FROM inventory_item c ORDER BY c; SELECT * FROM inventory_item c ORDER BY c.*; SELECT * FROM inventory_item c ORDER BY ROW(c.*); - 所有这些ORDER BY子句都指定了该行的组合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: + 所有这些ORDER BY子句都指定了该行的复合值,因此会按照中描述的规则对行进行排序。不过,如果inventory_item包含一个名为c的列,第一种情况就会不同于其他情况,因为它表示只按那一列排序。按照前面展示的列名,下面这些查询也与上述查询等效: SELECT * FROM inventory_item c ORDER BY ROW(c.name, c.supplier_id, c.price); SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); @@ -287,7 +287,7 @@ SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); - 另一种与组合值有关的特殊语法行为是,我们可以使用函数记法来提取组合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: + 另一种与复合值有关的特殊语法行为是,我们可以使用函数记法来提取复合值中的字段。简单来说,记法field(table)table.field可以互换。例如,这些查询是等价的: SELECT c.name FROM inventory_item c WHERE c.price > 1000; @@ -306,11 +306,11 @@ SELECT c.somefunc FROM inventory_item c; 函数记法与字段记法之间的这种等价性,使得我们可以通过在复合类型上使用函数来实现计算字段 - computed field + 计算字段 - field - computed + 字段 + 计算 使用上面最后一种查询形式的应用程序,无需直接知道somefunc并不是该表中的真实列。 @@ -328,7 +328,7 @@ SELECT c.somefunc FROM inventory_item c; 复合类型的输入和输出语法 - 组合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明组合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 + 复合值的外部文本表示由两部分组成:一部分是按照各字段类型的 I/O 转换规则解释的项,另一部分是表明复合结构的附加符号。这些附加符号包括包围整个值的圆括号(()),以及相邻项之间的逗号(,)。圆括号外部的空白会被忽略;但在圆括号内部,空白会被视为字段值的一部分,其是否有意义取决于该字段数据类型的输入转换规则。例如,在 '( 42)' @@ -336,7 +336,7 @@ SELECT c.somefunc FROM inventory_item c; - 如前所示,在写组合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让组合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的组合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作组合语法的数据字符。 + 如前所示,在写复合值时,你可以给任意单个字段值加双引号。如果字段值本身可能让复合值解析器混淆,则必须这样做。特别是,包含圆括号、逗号、双引号或反斜杠的字段必须用双引号括起来。要在带引号的复合字段值中写入双引号或反斜杠,需要在其前面加一个反斜杠。(另外,带双引号的字段值内部成对出现的双引号会被视为一个双引号字符,这与 SQL 字面字符串中单引号的规则类似。)或者,你也可以完全不使用引号,而改用反斜杠转义,保护所有原本会被当作复合语法的数据字符。 @@ -352,7 +352,7 @@ SELECT c.somefunc FROM inventory_item c; - 在 SQL 命令中编写组合值时,ROW构造器语法通常比组合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是组合成员时完全相同。 + 在 SQL 命令中编写复合值时,ROW构造器语法通常比复合字面量语法更容易使用。在ROW中,各个字段值的写法与它们不是复合成员时完全相同。 diff --git a/zh/20/textsearch.sgml b/zh/20/textsearch.sgml index 93284080..506b591a 100644 --- a/zh/20/textsearch.sgml +++ b/zh/20/textsearch.sgml @@ -1,21 +1,21 @@ - 全文搜索 + 全文检索 - 全文搜索 + 全文检索 - 文本搜索 + 文本检索 介绍 - 全文搜索(或简称文本搜索)提供了识别满足 + 全文检索(或简称文本检索)提供了识别满足 查询条件的自然语言文档的能力, 并且可按它们与查询的相关度进行排序。最常见的搜索类型,是找出所有包含给定 查询词的文档,并按它们与查询的相似性 @@ -25,7 +25,7 @@ - 文本搜索操作符在数据库中已经存在很多年了。 + 文本检索操作符在数据库中已经存在很多年了。 PostgreSQL为文本数据类型提供了 ~~*LIKEILIKE 操作符,但它们缺少现代信息系统所要求的许多关键特性: @@ -138,7 +138,7 @@ ()。围绕这两种数据类型还有许多函数和 操作符(),其中最重要的是匹配操作符 @@,我们将在中介绍。 - 全文搜索还可以借助索引加速()。 + 全文检索还可以借助索引加速()。 @@ -147,11 +147,11 @@ 文档 - 全文搜索 + 文本检索 - 文档是全文搜索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本搜索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 + 文档是全文检索系统中的搜索单位,例如一篇杂志文章或一封电子邮件。文本检索引擎必须能够解析文档,并保存词位(关键字)与其所属文档之间的关联。随后,就可以利用这些关联来搜索包含查询词的文档。 @@ -179,7 +179,7 @@ WHERE m.mid = d.did AND m.mid = 12; - 为了进行文本搜索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 + 为了进行文本检索,每个文档都必须被化简为预处理后的 tsvector 格式。搜索和排名完全基于文档的 tsvector 表示来执行 — 只有当文档被选中并准备展示给用户时,才需要取回原始文本。因此,我们常常把 tsvector 直接称作文档,但它当然只是完整文档的一种紧凑表示。 @@ -187,7 +187,7 @@ WHERE m.mid = d.did AND m.mid = 12; 基本文本匹配 - 在PostgreSQL中,全文搜索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: + 在PostgreSQL中,全文检索基于匹配操作符@@。如果一个tsvector(文档)匹配一个tsquery(查询),它就返回true。哪一种数据类型写在前面并不重要: SELECT 'a fat cat sat on a mat and ate a fat rat'::tsvector @@ 'cat & rat'::tsquery; @@ -203,7 +203,7 @@ SELECT 'fat & cow'::tsquery @@ 'a fat cat sat on a mat and ate a fat rat'::t - 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索术语,这些术语必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个术语组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本搜索匹配更像是这样: + 正如上例所示,tsquery并不只是原始文本,tsvector也不是。tsquery包含搜索词,这些搜索词必须已经是正规化后的词位,并且可以用 AND、OR、NOT 和 FOLLOWED BY 操作符把多个搜索词组合起来。(语法细节见。)to_tsqueryplainto_tsqueryphraseto_tsquery 有助于把用户输入的文本转换为合适的 tsquery,其主要工作就是对文本中的词做正规化。类似地,to_tsvector 用于解析并正规化文档字符串。因此在实践中,文本检索匹配更像是这样: SELECT to_tsvector('fat cats ate fat rats') @@ to_tsquery('fat & rat'); @@ -221,7 +221,7 @@ SELECT 'fat cats ate fat rats'::tsvector @@ to_tsquery('fat & rat'); f - 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,默认假定已经正规化,因此 rats 不会匹配 rat。 + 就不会匹配成功,因为这里不会对单词 rats 做正规化。tsvector 的元素是词位,被假定为已经正规化,因此 rats 不会匹配 rat @@ -290,49 +290,49 @@ SELECT phraseto_tsquery('the cats ate the rats'); 配置 - 前述的都是简单的文本搜索示例。正如前面所提到的,全文搜索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如基于空白之外的解析。这个功能由文本搜索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 + 前述的都是简单的文本检索示例。正如前面所提到的,全文检索功能包括做更多事情的能力:跳过索引特定词(停用词)、处理同义词并使用更高级的解析,例如不局限于按空白划分的解析。这个功能由文本检索配置控制。PostgreSQL中有多种语言的预定义配置,并且你可以很容易地创建你自己的配置(psql\dF命令显示所有可用的配置)。 - 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本搜索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config。 + 在安装期间会选择一个合适的配置,并据此在postgresql.conf中设置。如果整个集簇都使用同一种文本检索配置,你可以直接使用postgresql.conf中的这个值。若要在整个集簇中使用不同配置,但保证每个数据库内部使用同一种配置,可以使用ALTER DATABASE ... SET。否则,你也可以在每个会话中设置default_text_search_config - 依赖一个配置的每一个文本搜索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当这个参数被忽略时,default_text_search_config才被使用。 + 依赖一个配置的每一个文本检索函数都有一个可选的regconfig参数,因此要使用的配置可以被显式指定。只有当省略这个参数时,default_text_search_config才被使用。 - 为了让建立自定义文本搜索配置更容易,一个配置可以从更简单的数据库对象来建立。PostgreSQL的文本搜索功能提供了四类配置相关的数据库对象: + 为了便于构建自定义文本检索配置,配置由更简单的数据库对象组合而成。PostgreSQL 的文本检索功能提供了四类与配置相关的数据库对象: - 文本搜索解析器将文档拆分成词元并分类每个词元(例如,作为词或者数字)。 + 文本检索解析器将文档拆分成词元并对每个词元分类(例如,作为词或者数字)。 - 文本搜索词典将词元转变成正规化的形式并拒绝停用词。 + 文本检索词典将词元转变成正规化的形式并拒绝停用词。 - 文本搜索模板提供位于词典底层的函数(一个词典简单地指定一个模板和一组用于模板的参数)。 + 文本检索模板提供位于词典底层的函数(词典只需指定一个模板及其一组参数)。 - 文本搜索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 + 文本检索配置选择一个解析器和一组用于将解析器产生的词元正规化的词典。 - 文本搜索解析器和模板是从低层 C 函数构建而来,因此它要求 C 编程能力来开发新的解析器和模板,并且还需要超级用户权限来把它们安装到一个数据库中(在PostgreSQL发布的contrib/区域中有一些附加的解析器和模板的示例)。由于词典和配置只是对底层解析器和模板的参数化和连接,不需要特殊的权限来创建一个新词典或配置。创建定制词典和配置的示例将在本章稍后的部分给出。 + 文本检索解析器和模板由底层 C 函数构成,因此开发新的解析器和模板需要 C 编程能力,将它们安装到数据库中则需要超级用户权限。(PostgreSQL 发行版的 contrib/ 目录中有附加解析器和模板的示例。)词典和配置只是为底层解析器和模板设置参数并将它们连接起来,因此创建新词典或配置不需要特殊权限。本章后面会给出创建自定义词典和配置的示例。 @@ -343,14 +343,14 @@ SELECT phraseto_tsquery('the cats ate the rats'); 表和索引 - 在前一节中的示例演示了使用简单常数字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 + 在前一节中的示例演示了使用简单常量字符串进行全文匹配。本节展示如何搜索表数据,以及可选择地使用索引。 搜索表 - 即使没有索引,也可以执行全文搜索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend: + 即使没有索引,也可以执行全文检索。下面这个简单查询会输出每一行的title,其中对应的body字段包含单词friend SELECT title @@ -374,7 +374,7 @@ WHERE to_tsvector(body) @@ to_tsquery('friend'); - 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 中同时包含 createtable: + 更复杂一点的例子,是选出最近的 10 个文档,它们的 titlebody 合在一起包含 createtable SELECT title @@ -388,7 +388,7 @@ LIMIT 10; - 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本搜索在实际使用中通常都需要建立索引。 + 虽然这些查询在没有索引的情况下也能工作,但除偶尔的临时搜索外,大多数应用都会觉得这种方式太慢。文本检索在实际使用中通常都需要建立索引。 @@ -397,13 +397,13 @@ LIMIT 10; 创建索引 - 我们可以创建一个GIN索引()来加速文本搜索: + 我们可以创建一个GIN索引()来加速文本检索: CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector('english', body)); - 注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本搜索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含使用不同文本搜索配置创建的tsvector,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 + 注意这里使用的是to_tsvector的双参数版本。只有显式指定配置名称的文本检索函数,才能用于表达式索引()。这是因为索引内容必须不受的影响。否则,索引内容就可能不一致,因为不同的索引项可能包含使用不同文本检索配置创建的tsvector,而且无法判断各自使用了哪一种配置。这样的索引也不可能被正确地转储和恢复。 @@ -420,10 +420,7 @@ CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector(config_name, body)); 这里 config_namepgweb 表中的一个列。这样就允许在同一个索引中混合使用不同配置,同时记录每个索引项使用的是哪一种配置。例如,如果文档集合中包含不同语言的文档,这就会很有用。同样,打算使用该索引的查询也必须写成对应的形式,例如 WHERE to_tsvector(config_name, body) @@ 'a & b' - - 索引甚至可以连接列: - - + 索引甚至可以串接多个列: CREATE INDEX pgweb_idx ON pgweb USING GIN(to_tsvector('english', title || ' ' || body)); @@ -443,7 +440,7 @@ ALTER TABLE pgweb CREATE INDEX textsearch_idx ON pgweb USING GIN(textsearchable_index_col); - 现在我们准备好执行一个快速的全文搜索了: + 现在我们准备好执行一个快速的全文检索了: SELECT title @@ -455,7 +452,7 @@ LIMIT 10; - 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本搜索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 + 与表达式索引相比,单独列方法的一个优点是,为了利用索引,查询中不必显式指定文本检索配置。正如上面的例子所示,查询可以依赖default_text_search_config。另一个优点是搜索会更快,因为它不必重新执行to_tsvector调用来验证索引匹配(使用 GiST 索引时这一点比使用 GIN 索引时更重要;见)。不过,表达式索引方法更容易设置,而且占用更少磁盘空间,因为tsvector表示并没有被显式存储。 @@ -463,10 +460,10 @@ LIMIT 10; - 控制文本搜索 + 控制文本检索 - 要实现全文搜索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 + 要实现全文检索,必须有函数能够从文档创建 tsvector,并从用户查询创建 tsquery。此外,我们还希望结果能按有意义的顺序返回,因此还需要函数根据文档与查询的相关性进行比较。同样重要的,是把结果良好地展示出来。PostgreSQL为这些能力都提供了支持。 @@ -485,7 +482,7 @@ to_tsvector( config - to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本搜索配置进行处理。下面是一个简单示例: + to_tsvector 会把文本文档解析为词元,将词元归约为词位,并返回一个 tsvector,其中列出各词位及其在文档中的位置。文档会按指定的或默认的文本检索配置进行处理。下面是一个简单示例: SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); @@ -500,7 +497,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每类词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本搜索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english。 + to_tsvector 在内部会调用解析器,把文档文本拆分成词元并为每个词元分配类型。对于每个词元,系统都会查询一个词典列表(),而这个列表会随词元类型而变化。第一个能够识别该词元的词典,会输出一个或多个正规化后的词位来表示它。例如,rats 之所以变成 rat,是因为某个词典识别出 ratsrat 的复数形式。某些词会被识别为停用词),于是被忽略,因为它们出现得过于频繁,对搜索没有帮助。在这个示例中,aonit 就是停用词。如果列表中的词典都无法识别某个词元,它也会被忽略。示例里的标点符号 - 就属于这种情况,因为其词元类型(Space symbols)实际上没有分配任何词典,也就是说,空白类词元永远不会被索引。解析器、词典以及需要索引哪些词元类型,都由所选的文本检索配置()决定。一个数据库里可以同时存在多种不同配置,并且系统已经为多种语言提供了预定义配置。在本例中,我们使用的是英语的默认配置 english @@ -508,7 +505,7 @@ SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats'); - 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为空,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: + 由于 to_tsvector(NULL) 会返回 NULL,因此只要字段可能为 NULL,就建议使用 coalesce。下面是从结构化文档创建 tsvector 的推荐方法: UPDATE tt SET ti = @@ -659,12 +656,12 @@ websearch_to_tsquery( config - 无引号文本:不在引号中的文本会被转换为由&操作符分隔的词,就像经过plainto_tsquery处理一样。 + 未加引号的文本:不在引号中的文本会被转换为由&操作符分隔的词,就像经过plainto_tsquery处理一样。 - "引号文本":引号中的文本会被转换为由<->操作符分隔的词,就像经过phraseto_tsquery处理一样。 + "加引号的文本":引号中的文本会被转换为由<->操作符分隔的词,就像经过phraseto_tsquery处理一样。 @@ -722,7 +719,7 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); 搜索结果排名 - 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及它们出现于文档中哪个部分。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 + 排名旨在衡量文档与特定查询的相关程度,以便在匹配很多时优先显示最相关的结果。PostgreSQL提供了两种预定义的排名函数,它们会综合考虑词法信息、邻近关系和结构信息;也就是说,会考虑查询词在文档中出现的频率、这些词彼此之间的距离,以及这些词所处文档部分的重要程度。不过,相关性这一概念本身就比较模糊,而且高度依赖具体应用。不同应用可能还需要额外信息参与排名,例如文档修改时间。内置排名函数仅仅是示例。你可以编写自己的排名函数,或者把它们的结果与其他因素结合起来,以满足特定需求。 @@ -813,12 +810,12 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 8 用文档中唯一词的数量除排名 + 8 用文档中不同词的数量除排名 - 16 用 1 + 文档中唯一词数量的对数除排名 + 16 用 1 + 文档中不同词数量的对数除排名 @@ -832,7 +829,7 @@ SELECT websearch_to_tsquery('english', '""" )( dummy \\ query <->'); - 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。正规化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 + 需要注意的是,排名函数不会使用任何全局信息,因此不可能像有时人们希望的那样,给出一种能够公平归一化到 1% 或 100% 的结果。归一化选项 32(rank/(rank+1))可以把所有排名缩放到 0 到 1 的范围内,但这当然只是表面上的变化,不会影响搜索结果的顺序。 @@ -904,7 +901,7 @@ ts_headline( config ts_headline 接收文档和查询,并返回文档中一段 - 高亮查询词条的摘录。具体而言,该函数会先用查询选择相关文本片段,然后 + 高亮查询词的摘录。具体而言,该函数会先用查询选择相关文本片段,然后 高亮查询中出现的所有词,即使这些词的位置并不满足查询本身的位置限制。 用于解析文档的配置可通过 config 指定; 若省略 config,则使用 @@ -1011,7 +1008,7 @@ occurrences to display in the result.', 附加特性 - 本节介绍一些在文本搜索中很有用的附加函数和操作符。 + 本节介绍一些在文本检索中很有用的附加函数和操作符。 @@ -1124,7 +1121,7 @@ occurrences to display in the result.', - 返回用 AND 结合的两个给定查询。 + 返回两个给定查询的 AND 组合。 @@ -1138,7 +1135,7 @@ occurrences to display in the result.', - 返回用 OR 结合的两个给定查询。 + 返回两个给定查询的 OR 组合。 @@ -1191,7 +1188,7 @@ SELECT to_tsquery('fat') <-> to_tsquery('cat | rat'); - 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: + 返回一个查询,它使用 <N> tsquery 操作符,搜索第一个给定查询的匹配,并在其后距离正好为 distance 个词位处搜索第二个给定查询的匹配。例如: SELECT tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10); @@ -1245,10 +1242,7 @@ SELECT numnode('foo & bar'::tsquery); - - 返回可用于索引搜索的tsquery部分。这个函数可用于检测不可索引的查询,例如只包含停用词或只包含否定项的查询。例如: - - + 返回一个tsquery中可用于搜索索引的部分。此函数可用于检测无法使用索引的查询,例如只包含停用词或只包含否定词项的查询。例如: SELECT querytree(to_tsquery('defined')); querytree ----------- @@ -1424,7 +1418,7 @@ SELECT title, body FROM messages WHERE tsv @@ to_tsquery('title & body'); - 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本搜索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 + 第一个触发器参数必须是要更新的 tsvector 列名。第二个参数指定执行转换时要使用的文本检索配置。对于 tsvector_update_trigger,配置名直接作为第二个触发器参数给出。如上所示,它必须带模式限定,这样触发器行为就不会随着 search_path 的变化而变化。对于 tsvector_update_trigger_column,第二个触发器参数则是另一个表列的名称,该列必须是 regconfig 类型。这样就可以按行选择配置。其余参数是文本列的名称(类型为 textvarcharchar),它们会按给定顺序并入文档。NULL 值会被跳过(但其他列仍会被索引)。 @@ -1491,7 +1485,7 @@ ts_stat(sqlquery text, - 如果提供了 weights,则只统计具有这些权重之一的出现。 + 如果提供了 weights,则只统计具有这些权重之一的词的出现次数。 @@ -1520,7 +1514,7 @@ LIMIT 10; 解析器 - 文本搜索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 + 文本检索解析器负责把未处理的文档文本划分成词元并标识每个词元的类型,而可能的类型集合由解析器本身定义。注意,解析器完全不会修改文本 — 它只是识别看似合理的词边界。由于作用范围有限,相比自定义词典,对应用相关的自定义解析器的需求没有那么强烈。目前PostgreSQL只提供一种内置解析器,而它已经被证明对广泛的应用都很有用。 @@ -1543,12 +1537,12 @@ LIMIT 10; asciiword - 单词,所有 ASCII 字母 + 单词,全部由 ASCII 字母组成 elephant word - 单词,所有字母 + 单词,全部由字母组成 mañana @@ -1558,12 +1552,12 @@ LIMIT 10; asciihword - 带连字符的单词,所有 ASCII + 带连字符的单词,全部为 ASCII 字符 up-to-date hword - 带连字符的单词,所有字母 + 带连字符的单词,由字母组成 lógico-matemática @@ -1573,12 +1567,12 @@ LIMIT 10; hword_asciipart - 带连字符的单词部分,所有 ASCII + 带连字符的单词部分,全部为 ASCII 字符 postgresql-beta1 上下文中的 postgresql hword_part - 带连字符的单词部分,所有字母 + 带连字符的单词部分,全部由字母组成 lógico-matemática 上下文中的 lógicomatemática @@ -1653,8 +1647,8 @@ LIMIT 10; blank - 空格符号 - (其他不识别的任意空白或标点符号) + 空白符号 + (未被识别为其他类型的空白或标点符号) @@ -1662,12 +1656,12 @@ LIMIT 10; - 解析器的一个字母的概念由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时可以用来区别它们。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 + 解析器对字母的界定由数据库的区域设置决定,具体是lc_ctype。只包含基本 ASCII 字母的词被报告为一个单独的词元类型,因为有时区分它们会很有用。在大部分欧洲语言中,词元类型wordasciiword应该被同样对待。 email不支持所有由RFC 5322定义的有效电子邮件字符。 - 具体来说,电子邮件用户名仅支持句号、短横线和下划线这些非字母数字字符。 + 具体来说,电子邮件用户名仅支持句点、短横线和下划线这些非字母数字字符。 @@ -1716,7 +1710,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h 词典 - 词典用于消除不应参与搜索的词(stop words),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 + 词典用于消除不应参与搜索的词(停用词),并用于对词进行正规化,以便同一个词的不同派生形式能够匹配。成功完成正规化的词被称为词位。除了改善搜索质量,正规化和移除停用词还会减小文档的tsvector表示,从而提高性能。正规化并不总是具有语言学意义,而且通常依赖于应用的语义。 @@ -1731,7 +1725,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - URL地址可以被正规化,以便让等价的 URL 匹配: + URL 地址可以规范化,以便让等价的 URL 匹配: @@ -1776,32 +1770,32 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h - 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤字典) + 一个带有 TSL_FILTER 标志的单个词位,它会用一个新词元替换原始词元,并把它传递给后续词典(执行这种工作的词典称为过滤词典 - 如果字典知道该词元但它是一个停用词,则返回一个空数组 + 如果词典知道该词元但它是一个停用词,则返回一个空数组 - 如果字典不识别该输入词元,则返回NULL + 如果词典不识别该输入词元,则返回NULL - PostgreSQL为许多语言提供了预定义的字典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发布的contrib/区域。 + PostgreSQL为许多语言提供了预定义的词典。也有多种预定义模板可以被用于创建带自定义参数的新词典。每一种预定义词典模板在下面描述。如果没有合适的现有模板,可以创建新的;示例见PostgreSQL发行版的contrib/目录。 - 文本搜索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 + 文本检索配置把一个解析器与一组用于处理解析器输出词元的词典绑定在一起。对于解析器可能返回的每一种词元类型,配置都会指定一个单独的词典列表。当解析器找到该类型的词元时,会按顺序依次查询列表中的每个词典,直到有某个词典把它识别为已知词。如果它被识别为停用词,或者没有任何词典识别它,那么该词元就会被丢弃,既不会建立索引,也不会参与搜索。通常,第一个返回非 NULL 输出的词典就决定结果,后续词典不会再被查询;但过滤词典可以把给定单词替换为一个修改后的单词,再传递给后续词典。 - 配置词典列表的一般规则是,把最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语分类词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: + 配置词典列表的一般规则是,把适用范围最窄、最专门的词典放在最前面,然后是更通用的词典,最后以一个非常通用的词典收尾,例如 Snowball 词干分析器,或能识别所有内容的 simple。例如,对于一个天文学相关搜索(配置名为 astro_en),可以把词元类型 asciiword(ASCII 词)绑定到一个天文学术语同义词词典、一个通用英语词典,以及一个 Snowball 英语词干分析器: ALTER TEXT SEARCH CONFIGURATION astro_en @@ -1810,14 +1804,14 @@ ALTER TEXT SEARCH CONFIGURATION astro_en - 过滤词典可以放在列表中的任何位置,只是不能放在最后,因为放在最后就没有意义了。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 + 过滤词典可以放在列表中的任何位置,但放在末尾没有用处。过滤词典可用于先对词做部分正规化,以简化后续词典的工作。例如,可以用过滤词典去掉带重音字母中的重音符号,就像模块所做的那样。 停用词 - 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文搜索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: + 停用词是非常常见、几乎出现在每个文档中的词,没有区分价值。因此,在全文检索中可以忽略它们。例如,每篇英文文本都包含像 athe 这样的词,所以把它们存储在索引中没有用处。不过,停用词确实会影响 tsvector 中的位置,而这又会影响排名: SELECT to_tsvector('english', 'in the list of stop words'); @@ -1949,7 +1943,7 @@ SELECT * FROM ts_debug('english', 'Paris'); - synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基本名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 + synonym模板要求的唯一参数是SYNONYMS,它是其配置文件的基名 — 上例中的my_synonyms。该文件的完整名称将是$SHAREDIR/tsearch_data/my_synonyms.syn(其中$SHAREDIR表示PostgreSQL安装的共享数据目录)。该文件格式是每行一个要被替换的词,后面跟着它的同义词,用空白分隔。空行和结尾的空格会被忽略。 @@ -2011,28 +2005,28 @@ mydb=# SELECT 'indexes are very useful'::tsvector @@ to_tsquery('tst', 'indices' - 基本上一个分类词典会用一个首选词替换所有非首选词,并且也可选择地保留原始术语用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典要求一个下列格式的配置文件: + 分类词典基本上会用一个首选词替换所有非首选词,并且也可以选择保留原始词用于索引。PostgreSQL的分类词典的当前实现是同义词词典的一个扩展,并增加了短语支持。一个分类词典需要一个采用以下格式的配置文件: -# this is a comment -sample word(s) : indexed word(s) -more sample word(s) : more indexed word(s) +# 这是一条注释 +示例词(一个或多个) : 索引词(一个或多个) +更多示例词(一个或多个) : 更多索引词(一个或多个) ... - 其中冒号(:)符号扮演了一个短语及其替换之间的定界符。 + 其中冒号(:)符号用作短语及其替换词之间的分隔符。 - 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过对子词典的应用,但所有样例词都必须能被子词典识别。 + 分类词典会使用一个子词典(在词典配置中指定)在检查短语匹配之前正规化输入文本。只能选择一个子词典。如果子词典无法识别某个词,就会报错。在这种情况下,你应当避免使用该词,或者让子词典学会它。你可以在某个被索引词的开头放置一个星号(*),以跳过将子词典应用于该词,但所有样例词都必须能被子词典识别。 - 如果有多个短语匹配输入,则分类词典选择最长的那一个,并且使用最后的定义打破连结。 + 如果有多个短语匹配输入,分类词典会选择最长的匹配;长度相同时使用最后的定义。 - 由子词典识别的特定停用词不能够被指定;改用?标记任何可以出现停用词的地方。例如,假定根据子词典athe是停用词: + 由子词典识别的特定停用词不能够被指定;改用?标记可出现任意停用词的位置。例如,假定根据子词典athe是停用词: ? one ? two : swsw @@ -2074,7 +2068,7 @@ CREATE TEXT SEARCH DICTIONARY thesaurus_simple ( - mythesaurus是分类词典配置文件的基础名称(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 + mythesaurus是分类词典配置文件的基名(它的全名将是$SHAREDIR/tsearch_data/mythesaurus.ths,其中$SHAREDIR表示安装的共享数据目录)。 @@ -2099,7 +2093,7 @@ ALTER TEXT SEARCH CONFIGURATION russian 分类词典示例 - 考虑简单的天文词库 thesaurus_astro,其中包含一些天文单词组合: + 考虑一个简单的天文分类词典 thesaurus_astro,其中包含一些天文单词组合: supernovae stars : sn @@ -2167,7 +2161,7 @@ SELECT plainto_tsquery('supernova star'); <application>Ispell</application> 词典 - Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以把搜索词 bank 的词尾变化和词形变化对应起来,例如 bankingbankedbanksbanks'bank's。 + Ispell词典模板支持形态词典,它可以把一个词的许多不同语言学形式正规化为同一个词位。例如,一个英语 Ispell 词典可以匹配搜索词 bank 的所有变格和变位形式,例如 bankingbankedbanksbanks'bank's @@ -2179,12 +2173,12 @@ SELECT plainto_tsquery('supernova star'); - 要创建一个Ispell词典,执行这三步: + 要创建一个Ispell词典,请执行以下步骤: - 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。有必要抽取.aff.dic文件,把扩展改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): + 下载词典配置文件。OpenOffice扩展文件的扩展名是.oxt。需要提取.aff.dic文件,将扩展名改为.affix.dict。对于某些词典文件,还需要使用下面的命令把字符转换成 UTF-8 编码(例如挪威语词典): iconv -f ISO_8859-1 -t UTF-8 -o nn_no.affix nn_NO.aff iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic @@ -2193,7 +2187,7 @@ iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic - 拷贝文件到$SHAREDIR/tsearch_data目录 + 复制文件到$SHAREDIR/tsearch_data目录 @@ -2211,11 +2205,11 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( - 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基础名称。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 + 这里,DictFileAffFileStopWords指定词典、词缀和停用词文件的基名。停用词文件的格式和前面解释的simple词典类型相同。其他文件的格式在这里没有指定,但是也可以从上面提到的网站获得。 - Ispell 词典通常识别一个有限集合的词,这样它们后面应该跟着另一个更广义的词典;例如,一个 Snowball 词典,它可以识别所有东西。 + Ispell 词典通常只能识别有限的词,因此其后应跟着另一个覆盖范围更广的词典;例如,一个 Snowball 词典,它可以识别所有输入。 @@ -2223,13 +2217,13 @@ CREATE TEXT SEARCH DICTIONARY english_hunspell ( prefixes flag *A: - . > RE # As in enter > reenter + . > RE # 例如 enter > reenter suffixes flag T: - E > ST # As in late > latest - [^AEIOU]Y > -Y,IEST # As in dirty > dirtiest - [AEIOU]Y > EST # As in gray > grayest - [^EY] > EST # As in small > smallest + E > ST # 例如 late > latest + [^AEIOU]Y > -Y,IEST # 例如 dirty > dirtiest + [AEIOU]Y > EST # 例如 gray > grayest + [^EY] > EST # 例如 small > smallest @@ -2245,14 +2239,14 @@ lark/MRS .dict文件的格式是: -basic_form/affix_class_name +基本词形/词缀类名 .affix文件中,每一个词缀标志以下面的格式描述: -condition > [-stripping_letters,] adding_affix +条件 > [-删除的字母,] 添加的词缀 @@ -2261,7 +2255,7 @@ condition > [-stripping_letters,] adding_affix - Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,它标记可以参与到复合格式中的词典词: + Ispell 词典支持划分复合词,这是一个有用的特性。注意词缀文件应该用compoundwords controlled语句指定一个特殊标志,用于标记词典中可以参与构成复合词的词: compoundwords controlled z @@ -2291,7 +2285,7 @@ SFX T 0 est [^ey] - 一个词缀类的第一行是头部。头部后面列出了词缀规则的域: + 一个词缀类的第一行是首部。首部后面列出了词缀规则的字段: @@ -2345,7 +2339,7 @@ largehearted - Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每一个算法懂得按照其语言中的拼写,如何缩减词的常见变体形式为一个基础或词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择地指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。 + Snowball词典模板基于 Martin Porter 的一个项目,他是流行的英语 Porter 词干分析算法的发明者。Snowball 现在对许多语言提供词干分析算法(详见Snowball 站点)。每种算法都知道如何把其语言中词的常见变体约简为基本拼写形式,也就是词干。一个 Snowball 词典要求一个language参数来标识要用哪种词干分析器,并且可以选择指定一个stopword文件名来给出一个要被消除的词列表(PostgreSQL的标准停用词列表也是由 Snowball 项目提供的)。 @@ -2406,7 +2400,7 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( - 一个Snowball词典识别所有的东西,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 + 一个Snowball词典识别所有输入,不管它能不能简化该词,因此它应当被放置在词典列表的最后。把它放在任何其他词典前面是没有用处的,因为一个词元永远不会穿过它而进入到下一个词典。 @@ -2417,11 +2411,11 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( 配置示例 - 一个文本搜索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本搜索配置来执行其处理。配置参数指定了默认配置的名称,如果忽略了显式的配置参数,文本搜索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 + 一个文本检索配置指定了将一个文档转换成一个tsvector所需的所有选项:用于把文本分解成词元的解析器,以及用于将每一个词元转换成词位的词典。每一次to_tsvectorto_tsquery的调用都需要一个文本检索配置来执行其处理。配置参数指定了默认配置的名称,如果省略了显式的配置参数,文本检索函数将会使用它。它可以在postgresql.conf中设置,或者使用SET命令为一个单独的会话设置。 - 有一些预定义的文本搜索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本搜索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本搜索对象()的信息。 + 有一些预定义的文本检索配置可用,并且你可以容易地创建自定义的配置。为了便于管理文本检索对象,可以使用一组SQL命令,并且有多个psql命令可以显示有关文本检索对象()的信息。 @@ -2513,17 +2507,17 @@ SHOW default_text_search_config; - 测试和调试文本搜索 + 测试和调试文本检索 - 一个自定义文本搜索配置的行为很容易变得混乱。本节中描述的函数对于测试文本搜索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 + 一个自定义文本检索配置的行为很容易让人困惑。本节中描述的函数对于测试文本检索对象有用。你可以测试一个完整的配置,或者独立测试解析器和词典。 配置测试 - 函数ts_debug允许简单地测试一个文本搜索配置。 + 函数ts_debug可方便地测试一个文本检索配置。 @@ -2542,7 +2536,7 @@ ts_debug( config re - ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果该参数被忽略则使用default_text_search_config指定的配置。 + ts_debug显示document的每一个词元的信息,词元由解析器产生并由配置的词典处理过。该函数使用由config指定的配置,如果省略该参数则使用default_text_search_config指定的配置。 @@ -2617,7 +2611,7 @@ SELECT * FROM ts_debug('english', 'a fat cat sat on a mat - it ate a fat rats') - 为了一个更广泛的示范,我们先为英语语言创建一个public.english配置和 Ispell 词典: + 为了做更完整的演示,我们先为英语创建一个public.english配置和 Ispell 词典: @@ -2675,7 +2669,7 @@ FROM ts_debug('public.english', 'The Brightest supernovaes'); 解析器测试 - 下列函数允许直接测试一个文本搜索解析器。 + 下列函数允许直接测试一个文本检索解析器。 @@ -2717,7 +2711,7 @@ ts_token_type(parser_oid oid< - ts_token_type返回一个表,描述指定解析器能够识别的每一种词元。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: + ts_token_type返回一个表,描述指定解析器能够识别的每一种词元类型。对于每种词元类型,该表给出解析器用来标记该类词元的整数 tokid、在配置命令中命名该词元类型的 alias,以及简短的 description。例如: SELECT * FROM ts_token_type('default'); @@ -2755,7 +2749,7 @@ SELECT * FROM ts_token_type('default'); 词典测试 - ts_lexize函数帮助词典测试。 + ts_lexize函数便于测试词典。 @@ -2813,17 +2807,17 @@ SELECT plainto_tsquery('supernovae stars'); - 文本搜索的首选索引类型 + 文本检索的首选索引类型 - 文本搜索 + 文本检索 索引 - 有两种索引可以用来加速全文搜索:GIN和 + 有两种索引可以用来加速全文检索:GINGiST。 - 请注意,索引对于全文搜索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 + 请注意,索引对于全文检索并非强制要求,但在定期搜索某一列的情况下,通常是可取的。 @@ -2837,7 +2831,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GIN - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIN (column); @@ -2857,7 +2851,7 @@ SELECT plainto_tsquery('supernovae stars'); 索引 GiST - 文本搜索 + 文本检索 CREATE INDEX name ON table USING GIST (column [ { DEFAULT | tsvector_ops } (siglen = number) ] ); @@ -2867,7 +2861,7 @@ SELECT plainto_tsquery('supernovae stars'); 创建基于 GiST(广义搜索树)的索引。 column可以是tsvectortsquery类型。 - 可选的整数参数siglen确定签名长度(有关详细信息,请参见下文)。 + 可选的整数参数siglen确定以字节为单位的签名长度(有关详细信息,请参见下文)。 @@ -2876,7 +2870,7 @@ SELECT plainto_tsquery('supernovae stars'); - GIN 索引是文本搜索的首选索引类型。作为倒排索引,每个词(词位)在 + GIN 索引是文本检索的首选索引类型。作为倒排索引,每个词(词位)在 其中都有一个索引项,其中有压缩过的匹配位置的列表。多词搜索可以找到 第一个匹配,然后使用该索引移除缺少额外词的行。GIN 索引只存储 tsvector值的词(词位),并且不存储它们的权重标签。因此, @@ -2884,19 +2878,19 @@ SELECT plainto_tsquery('supernovae stars'); - 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。以字节为单位的签名长度由可选整数参数 siglen 的值决定。 默认签名长度(未指定 siglen 时)为 124 字节,最大签名长度为 2024 字节。该签名通过哈希每一个词到一个 n 位串中的一个单一位来产生,通过将所有这些位 OR 在一起产生一个 n 位的文档签名。当两个词哈希到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。更长的签名导致更精确的搜索(扫描索引的一小部分和更少的堆页面),但代价是更大的索引。 + 一个 GiST 索引是有损的,这表示索引可能产生假匹配,并且有必要检查真实的表行来消除这种假匹配(PostgreSQL在需要时会自动做这一步)。GiST 索引之所以是有损的,是因为每一个文档在索引中被表示为一个定长的签名。以字节为单位的签名长度由可选整数参数 siglen 的值决定。 默认签名长度(未指定 siglen 时)为 124 字节,最大签名长度为 2024 字节。该签名通过将每个词 hash 到一个 n 位串中的一位,再将所有这些位进行 OR 运算来生成,结果是一个 n 位的文档签名。当两个词 hash 到同一个位位置时就会产生假匹配。如果查询中所有词都有匹配(真或假),则必须检索表行查看匹配是否正确。更长的签名导致更精确的搜索(扫描更小比例的索引和更少的堆页面),但代价是更大的索引。 - GiST 可以构建为覆盖索引,例如使用 INCLUDE 子句。被包含的列可以具有没有任何 GiST 操作符类的数据类型。被包含的属性会以未压缩形式存储。 + GiST 可以构建为覆盖索引,即使用 INCLUDE 子句。被包含的列可以具有没有任何 GiST 操作符类的数据类型。被包含的属性会以未压缩形式存储。 - 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的可用性。假匹配的可能性取决于几个因素,特别是唯一词的数量,因此推荐使用词典来缩减这个数量。 + 有损性导致的性能下降归因于不必要的表记录(即被证实为假匹配的记录)获取。因为表记录的随机访问是较慢的,这限制了 GiST 索引的实用性。假匹配的可能性取决于几个因素,特别是不同词的数量,因此推荐使用词典来缩减这个数量。 - 注意GIN索引的构件时间常常可以通过增加来改进,而GiST索引的构建时间则与该参数无关。 + 注意GIN索引的构建时间常常可以通过增加来改进,而GiST索引的构建时间则对该参数不敏感。 @@ -2910,7 +2904,7 @@ SELECT plainto_tsquery('supernovae stars'); <application>psql</application> 支持 - 关于文本搜索配置对象的信息可以在psql中使用一组命令获得: + 关于文本检索配置对象的信息可以在psql中使用一组命令获得: \dF{d,p,t}+ PATTERN @@ -2918,7 +2912,7 @@ SELECT plainto_tsquery('supernovae stars'); - 可选参数 PATTERN 可以是文本搜索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: + 可选参数 PATTERN 可以是文本检索对象的名称,也可以可选地带上模式限定。如果省略 PATTERN,则会显示所有可见对象的信息。PATTERN 还可以是正则表达式,并且可以为模式名和对象名分别提供独立的模式。下面的示例说明了这一点: => \dF *fulltext* @@ -2945,7 +2939,7 @@ SELECT plainto_tsquery('supernovae stars'); \dF+ PATTERN - 列出文本搜索配置(加上 + 可显示更多细节)。 + 列出文本检索配置(加上 + 可显示更多细节)。 => \dF russian List of text search configurations @@ -2986,7 +2980,7 @@ Parser: "pg_catalog.default" \dFd+ PATTERN - 列出文本搜索词典(加上 + 可显示更多细节)。 + 列出文本检索词典(加上 + 可显示更多细节)。 => \dFd List of text search dictionaries @@ -3033,7 +3027,7 @@ Parser: "pg_catalog.default" \dFp+ PATTERN - 列出文本搜索解析器(加上 + 可显示更多细节)。 + 列出文本检索解析器(加上 + 可显示更多细节)。 => \dFp List of text search parsers @@ -3086,7 +3080,7 @@ Parser: "pg_catalog.default" \dFt+ PATTERN - 列出文本搜索模板(加上 + 可显示更多细节)。 + 列出文本检索模板(加上 + 可显示更多细节)。 => \dFt List of text search templates @@ -3109,7 +3103,7 @@ Parser: "pg_catalog.default" 限制 - PostgreSQL 当前文本搜索特性的限制如下: + PostgreSQL 当前文本检索特性的限制如下: 每个词位的长度必须小于 2 千字节 @@ -3133,12 +3127,12 @@ Parser: "pg_catalog.default" - 为了对比,PostgreSQL 8.1 的文档包含 10,441 个唯一词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 + 为了对比,PostgreSQL 8.1 的文档包含 10,441 个不同词,总数 335,420 个词,并且最频繁的词postgresql在 655 个文档中被提到 6,127 次。 - 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个唯一词。 + 另一个示例 — PostgreSQL的邮件列表归档在 461,020 条消息的 57,491,343 个词位中包含 910,989 个不同词。 diff --git a/zh/20/unaccent.sgml b/zh/20/unaccent.sgml index 4ead0d7e..3f3658f4 100644 --- a/zh/20/unaccent.sgml +++ b/zh/20/unaccent.sgml @@ -1,18 +1,18 @@ - unaccent — 去除变音符号的文本搜索词典 + unaccent — 去除变音符号的文本检索词典 unaccent - unaccent是一个文本搜索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤字典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文搜索能够以不区分重音的方式处理文本。 + unaccent是一个文本检索词典,它会从词位中移除重音符号(变音符号)。它是一个过滤词典,也就是说,它的输出总会被传递给下一个词典(如果有),这不同于词典的通常行为。这使得全文检索能够以不区分重音的方式处理文本。 - unaccent当前的实现还不能作为thesaurus词典的正规化字典使用。 + unaccent当前的实现还不能作为thesaurus词典的正规化词典使用。 @@ -79,7 +79,7 @@ - 与其他PostgreSQL文本搜索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含不可转换字符的行都会被静默忽略,因此规则文件中可以包含不适用于当前编码的规则。 + 与其他PostgreSQL文本检索配置文件一样,规则文件必须以 UTF-8 编码存储。加载时,数据会自动转换为当前数据库的编码。任何包含不可转换字符的行都会被静默忽略,因此规则文件中可以包含不适用于当前编码的规则。 @@ -93,7 +93,7 @@ 用法 - 安装unaccent扩展会创建一个文本搜索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 + 安装unaccent扩展会创建一个文本检索模板unaccent以及一个基于该模板的词典unaccentunaccent词典的默认参数设置是RULES='unaccent',因此它可立即配合标准的unaccent.rules文件使用。如果愿意,也可以修改这个参数,例如 mydb=# ALTER TEXT SEARCH DICTIONARY unaccent (RULES='my_rules'); @@ -114,7 +114,7 @@ mydb=# SELECT ts_lexize('unaccent', 'Hôtel'); - 下面的示例展示了如何将unaccent词典插入到文本搜索配置中: + 下面的示例展示了如何将unaccent词典插入到文本检索配置中: mydb=# CREATE TEXT SEARCH CONFIGURATION fr ( COPY = french ); mydb=# ALTER TEXT SEARCH CONFIGURATION fr @@ -145,7 +145,7 @@ mydb=# SELECT ts_headline('fr', 'Hôtel de la Mer', to_tsquery('fr', 'Hotel 函数 - unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本搜索环境之外使用。 + unaccent()函数会从给定字符串中移除重音符号(变音符号)。从本质上说,它是对unaccent这一类型词典的一个包装器,但也可以在常规文本检索环境之外使用。 @@ -157,7 +157,7 @@ unaccent(dictionary - 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本搜索词典。 + 如果省略dictionary参数,则会使用与unaccent()函数本身位于同一模式中、名为unaccent的文本检索词典。