nominatim_fdw

概览

SQL/control and tagged release version 2.3; PGXN distribution 2.3.0. Maintained in the local RPM and DEB recipes.

版本

构建

您可以使用 pig build 命令构建 nominatim_fdw 扩展的 RPM / DEB 包：

pig build pkg nominatim_fdw         # 构建 RPM / DEB 包

安装

您可以直接安装 nominatim_fdw 扩展包的预置二进制包，首先确保 PGDG 和 PIGSTY 仓库已经添加并启用：

pig repo add pgsql -u          # 添加仓库并更新缓存

使用 pig 或者是 apt/yum/dnf 安装扩展：

pig install nominatim_fdw;          # 当前活跃 PG 版本安装

pig ext install -y nominatim_fdw -v 18  # PG 18
pig ext install -y nominatim_fdw -v 17  # PG 17
pig ext install -y nominatim_fdw -v 16  # PG 16
pig ext install -y nominatim_fdw -v 15  # PG 15
pig ext install -y nominatim_fdw -v 14  # PG 14

dnf install -y nominatim_fdw_18       # PG 18
dnf install -y nominatim_fdw_17       # PG 17
dnf install -y nominatim_fdw_16       # PG 16
dnf install -y nominatim_fdw_15       # PG 15
dnf install -y nominatim_fdw_14       # PG 14

apt install -y postgresql-18-nominatim-fdw   # PG 18
apt install -y postgresql-17-nominatim-fdw   # PG 17
apt install -y postgresql-16-nominatim-fdw   # PG 16
apt install -y postgresql-15-nominatim-fdw   # PG 15
apt install -y postgresql-14-nominatim-fdw   # PG 14

创建扩展：

CREATE EXTENSION nominatim_fdw;

用法

来源：

• nominatim_fdw v2.3 README
• nominatim_fdw v2.1 变更日志
• nominatim_fdw v2.1 控制文件
• 官方Nominatim API概览
• OpenStreetMap Nominatim使用政策

nominatim_fdw 从PostgreSQL调用一个Nominatim地理编码服务。与传统的FDW不同，它暴露了用于搜索、逆向地理编码和OSM对象查找的函数；它不会创建可查询的外部表。

配置服务器

CREATE EXTENSION nominatim_fdw;

CREATE SERVER osm
  FOREIGN DATA WRAPPER nominatim_fdw
  OPTIONS (
    url 'https://nominatim.openstreetmap.org',
    connect_timeout '10',
    max_connect_retry '2',
    max_connect_redirect '1',
    accept_language 'en'
  );

公共OpenStreetMap端点有一个官方使用政策。对于持续或批量工作负载，请使用授权提供商或运行自己的Nominatim服务，根据要求标识应用程序，并遵守速率限制。

2.1 支持通过逐用户映射配置 HTTP Basic 认证：

CREATE USER MAPPING FOR app_user
SERVER osm
OPTIONS (user 'remote_user', password 'secret');

应把 endpoint 与 proxy 凭据放在 USER MAPPING 中，以便 PostgreSQL 应用其凭据可见性规则，而不是写进 foreign-server options。

核心流程

自由文本搜索：

SELECT osm_id, display_name, lon, lat
FROM nominatim_search(
  server_name => 'osm',
  q => 'Neubrückenstraße 63, Münster, Germany'
);

逆向地理编码和对象查找：

SELECT osm_id, display_name, addressdetails
FROM nominatim_reverse(
  server_name => 'osm',
  lon => 7.6293,
  lat => 51.9648,
  addressdetails => true
);

SELECT osm_id, display_name
FROM nominatim_lookup(
  server_name => 'osm',
  osm_ids => 'W121736959'
);

重要对象

• nominatim_search(...) 实现了自由文本或结构化前向搜索。
• nominatim_reverse(...) 将经度和纬度解析为最近的合适OSM地址。
• nominatim_lookup(...) 获取节点、方式或关系标识符，如 N123、W456 或 R789。
• nominatim_fdw_version() 报告扩展和主库版本。
• nominatim_fdw_settings 以行的形式暴露依赖和构建版本。
• 服务器选项包括 url、代理配置、超时设置、重试和重定向限制，以及默认的 accept_language。

所有端点函数都是 STRICT：显式SQL中的 NULL 参数返回空结果而不发送请求。在2.0中它们正确声明为 VOLATILE，因为响应是远程的且可以更改。

2.1 版本变更和注意事项

2.0版本验证逆向坐标、添加了 email、polygon_threshold 和 entrances，暴露依赖设置，并修复了返回详细字段中的JSON转义。它还具有用户可见的变化：逆向输出使用 display_name；addressparts 变为 addressdetails；地址细节默认为真用于逆向和查找；版本输出更短。

安装 2.3 扩展文件后，在已有数据库中升级：

ALTER EXTENSION nominatim_fdw UPDATE TO '2.3';

2.1 增加 Basic-auth 映射，并把 libcurl 初始化改为每个 PostgreSQL backend 一次，不再依赖每次请求的隐式初始化。libcurl 修复不要求新增 SQL 或预加载设置。

每次调用都会在网络语句中执行网络I/O操作。请使用有限的超时设置，限制谁可以创建或修改服务器，并避免在一个大型查询中的每一行都调用公共服务。上游构建需要PostgreSQL 10或更高版本、libxml2 2.6.0或更高版本以及libcurl 7.74或更高版本。

2.3 权限与请求限制

SQL/control 版本为 2.3，PGXN 发行版本为 2.3.0。查询函数现在检查外部服务器的 USAGE 权限；需要访问的角色必须获得授权：

GRANT USAGE ON FOREIGN SERVER osm TO app_user;
ALTER SERVER osm OPTIONS (ADD max_response_size '10485760');

max_response_size 以字节为单位，默认 0 表示不额外限制；可配置上限为 1 GiB。2.3 仅允许 HTTP/HTTPS，请求头禁止 CR/LF；polygon_threshold 必须有限且非负，zoom 保留 -1 默认值，其余值限制在 0–18。新版还修复响应编码、XML 根元素校验及取消请求时的资源释放。目录版本不表示当前 2.2.0 软件包已经包含这些修复。