百科 / 外部数据包装器 / 服务器文件

file_fdw

Server files

通过外部数据包装器接口读取服务器端文件或程序输出。

当前查看 PostgreSQL 18.6。

说明

通过外部数据包装器接口读取服务器端文件或程序输出。

接口类别: 外部数据包装器
处理函数或例程: file_fdw_handler
记录的回调: 10

接口与能力边界

矩阵记录此源码构建实际注册的回调。注册表明实现了相应接口钩子；操作是否允许还取决于选项、查询形式、权限和提供方规则。

下方保留同版本完整手册，包括配置、约束和示例。不声称已进行运行时能力测试。

文件访问边界

file_fdw 模块提供了外部数据包装器 file_fdw ，可用于访问服务器文件系统中的数据文件，或者在服务器上执行程序并读取其输出。数据文件或程序输出必须采用 COPY FROM 可读取的格式；详见 COPY 。当前对数据文件的访问为只读。

核心源码中注册的实现

{
	FdwRoutine *fdwroutine = makeNode(FdwRoutine);

	fdwroutine->GetForeignRelSize = fileGetForeignRelSize;
	fdwroutine->GetForeignPaths = fileGetForeignPaths;
	fdwroutine->GetForeignPlan = fileGetForeignPlan;
	fdwroutine->ExplainForeignScan = fileExplainForeignScan;
	fdwroutine->BeginForeignScan = fileBeginForeignScan;
	fdwroutine->IterateForeignScan = fileIterateForeignScan;
	fdwroutine->ReScanForeignScan = fileReScanForeignScan;
	fdwroutine->EndForeignScan = fileEndForeignScan;
	fdwroutine->AnalyzeForeignTable = fileAnalyzeForeignTable;
	fdwroutine->IsForeignScanParallelSafe = fileIsForeignScanParallelSafe;

	PG_RETURN_POINTER(fdwroutine);
}

注册的接口处理函数

接口操作	源码观察	回调	实现
扫描数据行	已注册处理函数；适用条件限制	IterateForeignScan	fileIterateForeignScan
INSERT	此构建未注册处理函数	ExecForeignInsert	未登记
UPDATE	此构建未注册处理函数	ExecForeignUpdate	未登记
DELETE	此构建未注册处理函数	ExecForeignDelete	未登记
TRUNCATE	此构建未注册处理函数	ExecForeignTruncate	未登记
连接路径下推	此构建未注册处理函数	GetForeignJoinPaths	未登记
上层路径，包括聚合	此构建未注册处理函数	GetForeignUpperPaths	未登记
批量插入	此构建未注册处理函数	ExecForeignBatchInsert	未登记
异步追加执行	此构建未注册处理函数	ForeignAsyncRequest	未登记
导入模式	此构建未注册处理函数	ImportForeignSchema	未登记

手册中的选项

选项	同版本定义
filename	指定要读取的文件。相对路径以数据目录为基准。必须指定 filename 或 program 之一，但不能同时指定二者。
program	指定要执行的命令。该命令的标准输出会按使用 COPY FROM PROGRAM 时的方式读取。必须指定 program 或 filename 之一，但不能同时指定二者。
format	指定数据格式，与 COPY 的 FORMAT 选项相同。
header	指定数据是否包含标题行，与 COPY 的 HEADER 选项相同。
delimiter	指定数据的定界符字符，与 COPY 的 DELIMITER 选项相同。
quote	指定数据的引用字符，与 COPY 的 QUOTE 选项相同。
转义	指定数据的转义字符，与 COPY 的 ESCAPE 选项相同。
null	指定数据的空值串，与 COPY 的 NULL 选项相同。
默认	指定表示默认值的字符串，与 COPY 的 DEFAULT 选项相同。
encoding	指定数据编码，与 COPY 的 ENCODING 选项相同。
on_error	指定在将列输入值转换为其数据类型时遇到错误的处理方式，与 COPY 的 ON_ERROR 选项相同。
reject_limit	指定在将列输入值转换为其数据类型时可容忍的最大错误数，与 COPY 的 REJECT_LIMIT 选项相同。
log_verbosity	指定 file_fdw 发出消息的详细程度，与 COPY 的 LOG_VERBOSITY 选项相同。
force_not_null	这是一个布尔选项。如果为真，它指定该列的值不应与空值串（即表级的 null 选项）匹配。其效果与在 COPY 的 FORCE_NOT_NULL 选项中列出该列相同。
force_null	这是一个布尔选项。如果为真，它指定该列中与空值串匹配的值即使带有引号，也会作为 NULL 返回。没有此选项时，只有未加引号且与空值串匹配的值才会作为 NULL 返回。其效果与在 COPY 的 FORCE_NULL 选项中列出该列相同。

手册定义

F.15. file_fdw — 访问服务器文件系统中的数据文件

file_fdw模块提供了外部数据包装器 file_fdw，可用于访问服务器文件系统中的数据文件，或者在服务器上执行程序并读取其输出。数据文件或程序输出必须采用 COPY FROM可读取的格式；详见COPY。当前对数据文件的访问为只读。

使用此包装器创建的外部表可以具有下列选项：

filename

指定要读取的文件。相对路径以数据目录为基准。必须指定filename或program之一，但不能同时指定二者。

program

指定要执行的命令。该命令的标准输出会按使用 COPY FROM PROGRAM时的方式读取。必须指定program或filename之一，但不能同时指定二者。

format

指定数据格式，与COPY的FORMAT选项相同。

header

指定数据是否包含标题行，与COPY的HEADER选项相同。

delimiter

指定数据的定界符字符，与COPY的DELIMITER选项相同。

quote

指定数据的引用字符，与COPY的QUOTE选项相同。

转义

指定数据的转义字符，与COPY的ESCAPE选项相同。

null

指定数据的空值串，与COPY的NULL选项相同。

默认

指定表示默认值的字符串，与COPY的DEFAULT选项相同。

encoding

指定数据编码，与COPY的ENCODING选项相同。

on_error

指定在将列输入值转换为其数据类型时遇到错误的处理方式，与COPY的ON_ERROR选项相同。

reject_limit

指定在将列输入值转换为其数据类型时可容忍的最大错误数，与COPY的REJECT_LIMIT选项相同。

log_verbosity

指定file_fdw发出消息的详细程度，与COPY的LOG_VERBOSITY选项相同。

虽然 COPY 允许 HEADER 等选项不带值，但外部表选项语法在任何情况下都要求提供值。要启用通常不带值书写的 COPY 选项，可以传入 TRUE，因为这些选项都是布尔类型。

使用此包装器创建的外部表的列可以具有下列选项：

force_not_null

这是一个布尔选项。如果为真，它指定该列的值不应与空值串（即表级的 null选项）匹配。其效果与在COPY的 FORCE_NOT_NULL选项中列出该列相同。

force_null

这是一个布尔选项。如果为真，它指定该列中与空值串匹配的值即使带有引号，也会作为NULL返回。没有此选项时，只有未加引号且与空值串匹配的值才会作为NULL返回。其效果与在COPY的 FORCE_NULL选项中列出该列相同。

file_fdw 目前不支持 COPY 的 FORCE_QUOTE 选项。

这些选项只能在外部表或其列上指定，不能在file_fdw外部数据包装器的选项中指定，也不能在使用该包装器的服务器或用户映射的选项中指定。

出于安全原因，更改表级选项需要是超级用户，或者拥有角色pg_read_server_files（使用文件名时）或角色pg_execute_server_program（使用程序时）的权限：只有特定用户才应能够控制读取哪个文件或运行哪个程序。原则上也可以允许普通用户更改其他选项，但目前尚不支持。

在指定program选项时，请记住，该选项字符串会由 shell 执行。如果需要向该命令传递来自不受信任来源的参数，必须谨慎去除或转义任何对 shell 可能具有特殊含义的字符。出于安全原因，最好使用固定的命令字符串，或者至少避免向其中传递任何用户输入。

对于使用file_fdw的外部表，EXPLAIN会显示待读取的文件名或待运行的程序名。对于文件，除非指定COSTS OFF，否则还会显示文件大小（以字节为单位）。

例 F.1. 为 PostgreSQL CSV 日志创建外部表

file_fdw的一个明显用途，是将 PostgreSQL 活动日志作为表提供以供查询。要做到这一点，首先必须将日志记录到 CSV 文件中，这里将该文件称为pglog.csv。首先，将file_fdw 安装为扩展：

CREATE EXTENSION file_fdw;

然后创建一个外部服务器：

CREATE SERVER pglog FOREIGN DATA WRAPPER file_fdw;

现在就可以创建外部表了。使用CREATE FOREIGN TABLE命令时，需要定义该表的列、CSV 文件名及其格式：

CREATE FOREIGN TABLE pglog (
  log_time timestamp(3) with time zone,
  user_name text,
  database_name text,
  process_id integer,
  connection_from text,
  session_id text,
  session_line_num bigint,
  command_tag text,
  session_start_time timestamp with time zone,
  virtual_transaction_id text,
  transaction_id bigint,
  error_severity text,
  sql_state_code text,
  message text,
  detail text,
  hint text,
  internal_query text,
  internal_query_pos integer,
  context text,
  query text,
  query_pos integer,
  location text,
  application_name text,
  backend_type text,
  leader_pid integer,
  query_id bigint
) SERVER pglog
OPTIONS ( filename 'log/pglog.csv', format 'csv' );

到这里就完成了 — 现在可以直接查询日志了。当然，在生产环境中，还需要定义某种方法来处理日志轮转。

例 F.2. 创建具有列选项的外部表

要为某一列设置force_null选项，请使用OPTIONS关键字。

CREATE FOREIGN TABLE films (
 code char(5) NOT NULL,
 title text NOT NULL,
 rating text OPTIONS (force_null 'true')
) SERVER film_server
OPTIONS ( filename 'films/db.csv', format 'csv' );

文档与源码

来源构建

版本: 18.6
构建: PostgreSQL 18.6 source archive
来源指纹: 555610c24d53e4316da5b7d3fc25c279d96856d5e0e23ee308c328c5fa881d9f

版本比较

PostgreSQL 17 → 18: 属性变化。

以下差异保留原始字段名与英文源描述。

--- PostgreSQL 17
+++ PostgreSQL 18
@@ -53,6 +53,18 @@
       "name": "encoding"
     },
     {
+      "definition": "Specifies how to behave when encountering an error converting a column's input value into its data type, the same as COPY 's ON_ERROR option.",
+      "name": "on_error"
+    },
+    {
+      "definition": "Specifies the maximum number of errors tolerated while converting a column's input value to its data type, the same as COPY 's REJECT_LIMIT option.",
+      "name": "reject_limit"
+    },
+    {
+      "definition": "Specifies the amount of messages emitted by file_fdw , the same as COPY 's LOG_VERBOSITY option.",
+      "name": "log_verbosity"
+    },
+    {
       "definition": "This is a Boolean option. If true, it specifies that values of the column should not be matched against the null string (that is, the table-level null option). This has the same effect as listing the column in COPY 's FORCE_NOT_NULL option.",
       "name": "force_not_null"
     },

比较已记录的接口与属性，排除来源指纹和构建元数据。某个样本中没有记录，不能据此判断实际引入或移除的版本。

导出 JSON · 返回外部数据包装器 · 收录范围为 PostgreSQL 10 至 20；最早采样版本不一定是实际引入版本。

快速链接

file_fdw

说明

接口与能力边界

文件访问边界

核心源码中注册的实现

注册的接口处理函数

手册中的选项

手册定义

F.15. file_fdw — 访问服务器文件系统中的数据文件

F.15. file_fdw — 访问服务器文件系统中的数据文件

相关条目

文档与源码

版本比较