↑↓ 选择↵ 打开⌫ 切换范围完整搜索

PG.CENTER 连接 PostgreSQL 文档、百科与生态知识。由 Pigsty 维护。

Wiki / SQLSTATE

22001 — string_data_right_truncation

值超过目标类型长度而被右截断。

英文手册覆盖始于 PostgreSQL 8.1. 来源历史与运行验证各自保留独立版本边界。

当前阅读 PG 18·选择有来源记录的版本

8.18.28.38.49.09.19.29.39.49.59.61011121314151617181920
aliases
未知
class name
Data Exception
condition name
string_data_right_truncation
lang
en
sqlstate
22001

版本定义 PG 18

22001

速览 {#at-a-glance}

固定 varchar 路径报告 value too long for type character(%d)；hstore、varbit 等路径会使用各自的具体变体。

共享案例创建 varchar_limits(value varchar(3))，用 'too-long' 触发 22001，再插入修复值 'ok' 并查询存储值。应在自动提交下逐条发送这些语句：触发语句预期失败，之后再执行修复语句。案例运行器在结束阶段负责清理对象。

CREATE TABLE varchar_limits (value varchar(3));
INSERT INTO varchar_limits VALUES ('too-long');
INSERT INTO varchar_limits VALUES ('ok');
SELECT value FROM varchar_limits;

校准实测 character varying(3) 拒绝超长值并报告 value too long for type character varying(3)；修正值 ok 成功，运行器的两条自动提交会话均回到 IDLE。

报文 {#messages}

固定 character 和 varchar guard 以 ERROR 严重性报告 primary 模板 value too long for type character(%d) 与 value too long for type character varying(%d)。hstore 与 varbit 路径使用各自的 primary：string too long for hstore key、string too long for hstore value 和 bit string too long for type bit varying(%d)。这些源码组没有独立 DETAIL 或 HINT；本次运行只观察了上面的 varchar 模板。

含义 {#meaning}

当值无法满足字符串类型的长度契约时会出现 22001。PostgreSQL 按字符数而不是字节数计算 character(n) 和 character varying(n)，因此 value too long for type character(%d) 中的 %d 指向响应里的 typmod。固定 varchar.c 是服务器端检查；hstore 键值和 bit string 有各自的路径和消息。

值进入类型的方式也会改变边界。varchar() 和 bpchar() 都接收 isExplicit 标志：赋值/输入转换遇到超出的非空格字符会报错，而显式 cast 到有界类型可以按 PostgreSQL 字符类型规则截断；超出的尾随空格和非空格字符处理不同。修改存储或校验前应先明确这个选择。

诊断 {#diagnosis}

保存 schema_name、table_name、column_name、datatype_name、routine 和完整 message。先从目录确认目标类型和 typmod，再按字符数而不是字节数测量实际值。区分赋值/插入、显式 cast，以及 hstore/bit 路径，因为它们的截断行为并不完全相同。

常见 varchar 路径要检查超出宽度的后缀是否全是尾随空格。只有尾随空格超出时可能适用字符类型的截断规则；有意义的非空格数据应视为契约被拒绝。固定源码消息说明的是类型宽度问题，不是一般编码或网络错误。

处置 {#response}

选择能保留数据契约的修复：校验并拒绝超长输入，有意扩大列/类型，或只在业务明确允许时显式 cast 截断。截断前保存原值和目标 typmod；静默裁剪标识符、键或审计文本可能写入与调用方意图不同的内容。本次固定案例使用自动提交，失败语句结束后会话仍为 IDLE；显式事务中应先回滚整个事务，或回滚到语句前建立的保存点，再重试修正值。修正输入或 schema 后重新转换，并核对保存后的字符长度。

版本 {#versions}

锁定目录从 7.4 记录该条件，并在列出的正式快照及 19beta3 中出现；固定源码覆盖为 PostgreSQL 18.6。

相关条件 {#related}

22003 是数值/范围越界，22007 是日期时间格式错误，22004 是独立的 NULL 契约。

来源 {#sources}

固定 character(n) 检查见 varchar.c#L300-L313，character varying(n) 检查见 varchar.c#L633-L640。PostgreSQL 18 的字符类型文档说明了字符数限制、尾随空格和显式 cast。结构化证据记录固定了源码 SHA，并区分 hstore/varbit 变体。

比较版本

SQLSTATE 证据与已记录的运行版本

cases · varchar_width_overflow
{
  "assertions": [
    "SQLSTATE is 22001",
    "The varchar width diagnostic names character varying(3)",
    "The failed autocommit session remains IDLE",
    "A representable value is stored after the error"
  ],
  "case_id": "varchar_width_overflow",
  "cleanup": "Drop the case schema with an owner connection.",
  "has_snippet": true,
  "position": 0,
  "preconditions": [],
  "repair": "Use a value that satisfies the declared width or revise the data contract explicitly; do not rely on an explicit cast that silently truncates the input.",
  "trigger": "Insert a value longer than the declared varchar(3) width.",
  "versions": [
    "10",
    "18"
  ]
}
claims · identity
{
  "claim_id": "identity",
  "limits": "",
  "method": "Read fixed definition.",
  "position": 0,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "22001 is string_data_right_truncation in SQLSTATE Class 22."
}
claims · mechanism.character-varchar
{
  "claim_id": "mechanism.character-varchar",
  "limits": "The exact behavior depends on target type and explicitness.",
  "method": "Read complete varchar.c width checks.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.path.character",
    "src.path.varchar"
  ],
  "statement": "The character and character-varying input paths check the non-explicit value against the typmod and emit distinct primary templates; explicit casts may truncate according to the type rules."
}
claims · mechanism.extension-types
{
  "claim_id": "mechanism.extension-types",
  "limits": "These are not interchangeable with varchar typmod diagnostics.",
  "method": "Read fixed extension/type guards.",
  "position": 2,
  "runtime": [],
  "sources": [
    "src.path.hstore",
    "src.path.varbit"
  ],
  "statement": "hstore key/value and varbit length checks use 22001 with subsystem-specific messages."
}
claims · history
{
  "claim_id": "history",
  "limits": "",
  "method": "Use catalogue boundary.",
  "position": 3,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "The locked catalogue records 22001 from 7.4 without proving an exact implementation introduction date."
}
claims · runtime.observation
{
  "claim_id": "runtime.observation",
  "limits": "The observation covers varchar varying input only, not hstore, varbit, or explicit-cast truncation.",
  "method": "Execute the shared registry and inspect selected summaries.",
  "position": 4,
  "runtime": [
    "runtime.22001-data1-latest.latest",
    "runtime.22001-data1-pg10.pg10"
  ],
  "sources": [
    "manifest.22001",
    "snippet-registry.22001"
  ],
  "statement": "The varchar_width_overflow case passed on isolated PostgreSQL 18.6 and 10.21: the non-fitting varchar(3) value produced 22001, left the autocommit session IDLE, and the corrected value ok was accepted."
}
messages · message.character
{
  "limits": "",
  "message_id": "message.character",
  "path": "",
  "position": 0,
  "raw": {
    "id": "message.character",
    "primary_template": "value too long for type character(%d)",
    "severity_source": "ERROR",
    "sources": [
      "src.path.character"
    ],
    "sqlstate": "22001"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.character"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "value too long for type character( )",
      "position": 0,
      "role": "",
      "template": "value too long for type character(%d)"
    }
  ]
}
messages · message.varchar
{
  "limits": "",
  "message_id": "message.varchar",
  "path": "",
  "position": 1,
  "raw": {
    "id": "message.varchar",
    "primary_template": "value too long for type character varying(%d)",
    "severity_source": "ERROR",
    "sources": [
      "src.path.varchar"
    ],
    "sqlstate": "22001"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.varchar"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "value too long for type character varying( )",
      "position": 0,
      "role": "",
      "template": "value too long for type character varying(%d)"
    }
  ]
}
messages · message.hstore-key
{
  "limits": "",
  "message_id": "message.hstore-key",
  "path": "",
  "position": 2,
  "raw": {
    "id": "message.hstore-key",
    "primary_template": "string too long for hstore key",
    "severity_source": "ERROR",
    "sources": [
      "src.path.hstore"
    ],
    "sqlstate": "22001"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.hstore"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "string too long for hstore key",
      "position": 0,
      "role": "",
      "template": "string too long for hstore key"
    }
  ]
}
messages · message.hstore-value
{
  "limits": "",
  "message_id": "message.hstore-value",
  "path": "",
  "position": 3,
  "raw": {
    "id": "message.hstore-value",
    "primary_template": "string too long for hstore value",
    "severity_source": "ERROR",
    "sources": [
      "src.path.hstore"
    ],
    "sqlstate": "22001"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.hstore"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "string too long for hstore value",
      "position": 0,
      "role": "",
      "template": "string too long for hstore value"
    }
  ]
}
messages · message.varbit
{
  "limits": "",
  "message_id": "message.varbit",
  "path": "",
  "position": 4,
  "raw": {
    "id": "message.varbit",
    "primary_template": "bit string too long for type bit varying(%d)",
    "severity_source": "ERROR",
    "sources": [
      "src.path.varbit"
    ],
    "sqlstate": "22001"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.varbit"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "bit string too long for type bit varying( )",
      "position": 0,
      "role": "",
      "template": "bit string too long for type bit varying(%d)"
    }
  ]
}
runtimes · runtime.22001-data1-latest.latest · 18.6 (Homebrew) · passed
{
  "cases": [
    "varchar_width_overflow"
  ],
  "limits": "",
  "position": 0,
  "raw": {
    "cases": [
      "varchar_width_overflow"
    ],
    "id": "runtime.22001-data1-latest.latest",
    "observed": {
      "sqlstate": "22001",
      "status_after_repair": "IDLE"
    },
    "raw": "verify/results/22001-data1-latest/latest/raw.jsonl",
    "raw_sha256": "722254ec20e72752649e81427aec2e21f8072d75e22960c3183883a04625c48a",
    "run_id": "22001-data1-latest",
    "server_version": "18.6 (Homebrew)",
    "server_version_num": 180006,
    "snippet_registry": {
      "path": "verify/cases/22001/snippets.json",
      "sha256": "ee3932e6fef2bd5b1c3ff35391019940f81eb61fd72854d9c79447efceeab634"
    },
    "status": "passed",
    "summary": "verify/results/22001-data1-latest/latest/summary.json",
    "summary_sha256": "d4700f6daef109b19ddfddc1f70948979400702a04024dc8ba4dfbcb13cd3def",
    "target": "latest"
  },
  "run_id": "22001-data1-latest",
  "runtime_id": "runtime.22001-data1-latest.latest",
  "server_version": "18.6 (Homebrew)",
  "status": "passed",
  "target": "latest"
}
runtimes · runtime.22001-data1-pg10.pg10 · 10.21 (Debian 10.21-1.pgdg90+1) · passed
{
  "cases": [
    "varchar_width_overflow"
  ],
  "limits": "",
  "position": 1,
  "raw": {
    "cases": [
      "varchar_width_overflow"
    ],
    "id": "runtime.22001-data1-pg10.pg10",
    "observed": {
      "sqlstate": "22001",
      "status_after_repair": "IDLE"
    },
    "raw": "verify/results/22001-data1-pg10/pg10/raw.jsonl",
    "raw_sha256": "da3eabf6714cfde3179b8d3456f74b7378ea4fc24b63905a8fef18acc93a8d31",
    "run_id": "22001-data1-pg10",
    "server_version": "10.21 (Debian 10.21-1.pgdg90+1)",
    "server_version_num": 100021,
    "snippet_registry": {
      "path": "verify/cases/22001/snippets.json",
      "sha256": "ee3932e6fef2bd5b1c3ff35391019940f81eb61fd72854d9c79447efceeab634"
    },
    "status": "passed",
    "summary": "verify/results/22001-data1-pg10/pg10/summary.json",
    "summary_sha256": "0acd54978ccf0df63136d6d32d1259804d5ae52c1cf9b45a48b165bdc9f201e1",
    "target": "pg10"
  },
  "run_id": "22001-data1-pg10",
  "runtime_id": "runtime.22001-data1-pg10.pg10",
  "server_version": "10.21 (Debian 10.21-1.pgdg90+1)",
  "status": "passed",
  "target": "pg10"
}
sources · src.errcodes.18.6
{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/errcodes.txt",
  "position": 0,
  "sha256": "6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba",
  "source_id": "src.errcodes.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt#L200"
}
sources · src.calls.REL_18_6
{
  "commit": "",
  "docs_url": "",
  "kind": "local_artifact",
  "location": "",
  "path": "raw/calls/REL_18_6.jsonl",
  "position": 1,
  "sha256": "9ee8a0e81d8f0825c5c1ae45583439859a26e602bdd4ce2f2a62aa278867ccbf",
  "source_id": "src.calls.REL_18_6",
  "tag": "",
  "url": ""
}
sources · src.path.character
{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/varchar.c",
  "position": 2,
  "sha256": "aee29b2c745b34a7299d158b8e8c60b2c6c4900a5e3751fd211acea81b431f42",
  "source_id": "src.path.character",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/varchar.c#L300-L313"
}
sources · src.path.varchar
{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/varchar.c",
  "position": 3,
  "sha256": "aee29b2c745b34a7299d158b8e8c60b2c6c4900a5e3751fd211acea81b431f42",
  "source_id": "src.path.varchar",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/varchar.c#L633-L640"
}
sources · src.path.hstore
{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "contrib/hstore/hstore_io.c",
  "position": 4,
  "sha256": "4f9e853ca79e1412d989e937749eeb2a251f7e8173d2732098e4c8a67a96b3d4",
  "source_id": "src.path.hstore",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/hstore/hstore_io.c#L407-L434"
}
sources · src.path.varbit
{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/varbit.c",
  "position": 5,
  "sha256": "f719afe56683db3714a41d2f49f454a6b65b38e310c00d5afe47cbc44fd9480d",
  "source_id": "src.path.varbit",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/varbit.c#L733-L758"
}
sources · snippet-registry.22001
{
  "commit": "",
  "docs_url": "",
  "kind": "local_artifact",
  "location": "",
  "path": "verify/cases/22001/snippets.json",
  "position": 6,
  "sha256": "ee3932e6fef2bd5b1c3ff35391019940f81eb61fd72854d9c79447efceeab634",
  "source_id": "snippet-registry.22001",
  "tag": "",
  "url": ""
}
sources · manifest.22001
{
  "commit": "",
  "docs_url": "",
  "kind": "local_artifact",
  "location": "",
  "path": "verify/cases/22001/cases.json",
  "position": 7,
  "sha256": "2fbab08d586504b3f34996e7413ab9e8899bf15cc3bc5f3c2d540ff0459ac053",
  "source_id": "manifest.22001",
  "tag": "workspace",
  "url": "verify/cases/22001/cases.json"
}

来源引用

完整定义与证据 JSON

定义来源

center · PostgreSQL 18 · english-manuals:219c1a4ac33d92ca4b553bd7dbeabee09dff8be49043a214ca10a34539956013

正文语言: zh-Hans · english-manuals:219c1a4ac33d92ca4b553bd7dbeabee09dff8be49043a214ca10a34539956013