net-connector 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fdd886424e85114a4773396098117ed0e89ddbfe4e4ad3b1dc43dfc003dbc589
-  data.tar.gz: f29240ec971ecddb62f9d8d31bd45db027ae0e799c5c14872e8dfdf55ad2f0be
+  metadata.gz: b9f2c5dfacb73a1c1aecf350bd4d1fe93755e0be25dbd1cc5c964a5676beaee7
+  data.tar.gz: 3afcf973ef1a25d848b1a91feb5803348eea6881f9d4b2721525378f9611d0d9
 SHA512:
-  metadata.gz: 97f0d16f83f74c24caf69d3beaa1dbb0c01b3fed6eb58a1609c385eb48eba9acfaa9bb47250d18d91274b06412aada14d1baed6b8e4531603987a4a84505657d
-  data.tar.gz: 343cf7298e695ea38fab06a4e838fbb643de8393a4c9ed87ddaee77401eccd5aeeaead086cb9408cb5321a861be423e43b525488a5d06d9014ced050fa3942bd
+  metadata.gz: 5b168ca118a7323f1b698908b7e6db2e627c97b52f57a4817f8b932456862ba9097491f4f879b23ffcdd9d8ea1c6f287b870354a9c279cf04963295b9cec815f
+  data.tar.gz: 1d5cdcedba90facbc57a9a33438c66a244c482ea580399e901f9b42572a5b6401f0cbb68f01e1bf106eb53e0562f4f213742de1cc2dc9dff80f0bae47697eb81

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 更新记录
 
+## 0.6.0 - 2026-09-27
+
+- 支持直接查询 PostgreSQL 获取 Netdisco 设备清单，SQL 和绑定参数可通过 YAML、环境变量或 CLI 设置，查询结果继续使用已有的厂商映射、计划预览和批量备份流程。
+- 数据库连接信息只从 `NETDISCO_DB_*` 环境变量读取，查询在只读事务中执行并限制时间和容量，失败时停止整批任务，错误输出不包含数据库凭据或原始响应。
+- 增加可编辑的数据库查询示例并随 gem 分发，安装时包含所需的 `pg` 驱动，原有 HTTP 清单及离线配置导出保持可用。
+
 ## 0.5.0 - 2026-09-27
 
 本版包含不兼容的接口调整，不保留旧路径或方法别名；升级时请按[当前接口说明](https://github.com/gatework/net-connector/blob/v0.5.0/docs/architecture.md#当前命名与接口调整)更新调用方。

data/README.md

@@ -274,6 +274,47 @@ net-connector-backup --config config.yml --tftp --all
 net-connector-backup --config config.yml --export 192.0.2.7 --output ./exports/device.cfg
 ```
 
+### PostgreSQL 联机查询
+
+设置 `netdisco.source: postgres` 可以直接从数据库查询清单，继续使用同一套 Fleet、规则、计划和备份流程。库不内置表名、SQL 或业务筛选条件；必须提供查询，可直接修改 [YAML 示例](examples/netdisco_database.yml)：
+
+```yaml
+netdisco:
+  source: postgres
+  query: |
+    SELECT host(ip) AS ip, name, dns, vendor, os, model, os_ver, serial
+    FROM device
+    WHERE vendor = $1
+    ORDER BY ip
+  query_params: [H3C]
+```
+
+查询必须返回唯一命名的 `ip` 列；可选列为 `name`、`dns`、`vendor`、`os`、`model`、`os_ver`、`serial`，其他列会丢弃。自定义表、视图、JOIN 和只读 CTE 均可用列别名适配这一契约。PostgreSQL 的 `inet` 字段建议用 `host(ip) AS ip` 去除前缀长度；筛选及排序由 SQL 决定。参数按数组顺序绑定 `$1`、`$2`，支持字符串、数字、布尔和 null，不做字符串插值或环境变量展开。
+
+数据库连接信息只从进程环境读取，沿用 [Netdisco 官方环境变量命名](https://github.com/netdisco/netdisco/wiki/Environment-Variables)。`HOST`、`NAME`、`USER`、`PASS` 必填；HTTP 地址、API key 和设备登录凭据不是清单查询的前置条件：
+
+```sh
+export NETDISCO_DB_HOST=database.example
+export NETDISCO_DB_NAME=netdisco
+export NETDISCO_DB_USER=inventory-reader
+export NETDISCO_DB_PASS='replace-me'
+export NETDISCO_DB_SSLMODE=verify-full
+export NETDISCO_DB_SSLROOTCERT=/etc/net-connector/database-ca.crt
+
+net-connector-backup --config examples/netdisco_database.yml --show-config
+net-connector-backup --config examples/netdisco_database.yml --plan
+# 覆盖查询参数；实际备份仍需设置 NET_CONNECTOR_DEVICE_* 凭据。
+net-connector-backup --config examples/netdisco_database.yml --plan --query-params '["Cisco"]'
+```
+
+SQL 也可通过 `NETDISCO_QUERY` / `--query SQL` 提供，参数通过 `NETDISCO_QUERY_PARAMS` / `--query-params JSON` 提供；来源对应 `NETDISCO_SOURCE` / `--source postgres`。优先级均为 CLI > ENV > YAML。SQL 和参数属于可公开配置，会出现在 `--show-config` 中；数据库密码只放在连接环境变量中。连接信息不进入策略快照、计划、报告或 `inspect`。已有 Fleet 每次重新查询时读取最新连接凭据；传入已有 `plan:` 执行时不会重新查询。
+
+客户端通过 `pg` 驱动执行只读事务，使用参数化游标分批取数，并在每批启用单行读取。PostgreSQL 原生解析拒绝多条语句，写入和锁定查询会失败；查询账户应仅授予所需表/视图的 SELECT 权限，只读事务不能替代账户权限隔离。驱动只在实际查询时加载，HTTP 和离线导出路径不加载它。
+
+数据库查询复用现有清单预算：`page_size` 控制每次 FETCH 的行数，`max_pages` 限制 FETCH 次数，`max_devices` 在去重前计数；字节预算统计返回列名与文本值，包含最终丢弃的列。字节检查发生在 libpq 解码一行之后，不能限制单个超大字段在驱动内部的瞬时内存。连接、查询和全部 FETCH 共用总期限，同时设置数据库 statement_timeout。任一查询错误、超时或超限均关闭连接并丢弃整份清单，不连接设备；错误消息不输出原始 SQL、参数或数据库响应。建议只选所需字段，并提供明确的 ORDER BY 保持采样顺序稳定。
+
+### 计划与执行
+
 `--plan` 只拉取并验证清单；`--host` 选择一个管理地址；`--tftp` 默认每厂商最多选择五台，`--all` 选择所有就绪设备。本地备份默认选择所有就绪设备，可用 `--limit-per-vendor` 限制。`--show-config` 只输出有效的非敏感设置，不访问 Netdisco。CLI 会拒绝未知 YAML 字段、Ruby 对象标签及配置中的凭据。`--export IP` 只离线读取规范化管理地址对应的 `<IP>.txt`；默认原样写到标准输出，指定 `--output` 后以 `0600` 权限原子写文件。导出的配置仍是敏感数据。
 
 CLI 的计划与批次摘要使用 JSON。默认 `--success-policy strict` 使用严格规则：非空清单且全部成功、回调及报告正常时为 `0`；空清单或有跳过、部分成功、失败时为 `1`；清单或配置错误为 `2`。`--host` 未在清单中找到也返回 `2`。由于其他清单记录会标记为过滤，默认单主机备份成功时批次退出码仍可能是 `1`；应查看 JSON 中的 `succeeded`、`skipped` 和逐台 `status`。
@@ -291,10 +332,18 @@ CLI 的计划与批次摘要使用 JSON。默认 `--success-policy strict` 使
 
 | 环境变量 | 默认值 | 用途 |
 | --- | --- | --- |
-| `NETDISCO_URL` | 必填 | Netdisco 服务根地址，可包含租户路径 |
+| `NETDISCO_SOURCE` | `http` | 清单来源，支持 `http`、`postgres` |
+| `NETDISCO_URL` | HTTP 模式必填 | Netdisco 服务根地址，可包含租户路径 |
 | `NET_CONNECTOR_CONFIG` | 未设置 | CLI 的非敏感 YAML 配置文件 |
 | `NETDISCO_USERNAME`, `NETDISCO_PASSWORD` | 未提供 API 密钥时必填 | 清单 API 登录 |
 | `NETDISCO_API_KEY` | 未设置 | 直接使用已有 API 密钥 |
+| `NETDISCO_QUERY` | PostgreSQL 模式必填 | 用户提供的单条清单 SQL |
+| `NETDISCO_QUERY_PARAMS` | `[]` | SQL 参数的 JSON 标量数组 |
+| `NETDISCO_DB_HOST`, `NETDISCO_DB_NAME` | PostgreSQL 模式必填 | 数据库主机或 Unix socket 目录、数据库名 |
+| `NETDISCO_DB_USER`, `NETDISCO_DB_PASS` | PostgreSQL 模式必填 | 仅从环境注入的数据库用户名、密码 |
+| `NETDISCO_DB_PORT` | libpq 默认 `5432` | PostgreSQL 端口 |
+| `NETDISCO_DB_SSLMODE`, `NETDISCO_DB_SSLROOTCERT` | libpq 默认 | TLS 模式、CA 文件；远程连接建议 `verify-full` |
+| `NETDISCO_DB_CONNECT_TIMEOUT` | 未单独设置 | 可选正整数秒；连接始终受清单总期限限制 |
 | `NETDISCO_PAGE_SIZE` | `500` | 清单分页大小 |
 | `NETDISCO_MAX_PAGES` | `10000` | 最大分页次数 |
 | `NETDISCO_MAX_RESPONSE_BYTES` | `16777216` | 单次响应正文上限，认证和错误正文也计数 |

data/docs/architecture.md

@@ -112,6 +112,12 @@ Diagnostic 只保存固定词表中的码、类型、阶段和受控产物状态
 
 注入的 `requester` 接收 URI 和 request。它返回后才接受长度和期限检查，不在任意用户 Ruby 回调中注入异步异常。解析和集合操作完成后也检查期限，但这不构成任意 CPU 回调的抢占保证。预算失败仅报告错误码与安全类型，没有部分清单、响应正文或底层 cause。HTTPS 的标准证书检查不变；默认允许明文 HTTP，可通过显式策略禁止。
 
+`Settings#inventory_source` 选择 HTTP `Client` 或 PostgreSQL `DatabaseClient`，两者只向 Fleet 提供 `devices`，不改变设备映射、计划和执行接口。数据库 SQL 与标量参数由用户配置，不内置业务表名或筛选；结果用列别名适配 `Client::FIELDS`，只保留这份现有字段白名单。连接参数由 `DatabaseClient::CONNECTION_ENV` 集中映射到 Netdisco 的 `NETDISCO_DB_*` 环境变量，全部排除在纯策略快照外；每次新建清单客户端时读取最新值。
+
+`DatabaseClient` 每次调用独占 PostgreSQL 连接，在只读事务中用扩展查询协议声明游标，原生解析器拒绝多语句和非查询输入。FETCH 大小及次数复用清单预算，单行模式使 libpq 不缓存整页；每行在追加前计数，额外列也消耗字节预算。驱动必须先解码单行，所以单个超大字段仍可超过 Ruby 预算的瞬时内存。总 deadline 覆盖连接和所有语句，每次 FETCH 前缩短 statement_timeout；正常完成回滚只读事务，异常关闭连接，任何失败均不交付部分清单。NOTICE、原始数据库异常及 cause 不进入日志或 CLI；稳定错误码区分连接失败、查询失败、无效清单和预算超限。SQL/参数可在 show-config 中查看，不能用于传递凭据。
+
+数据库集成测试运行 `bundle exec rake test:postgres`，通过 `pg_config --bindir`（或 `NET_CONNECTOR_TEST_PG_BINDIR`）定位服务端工具。测试只创建临时 SCRAM 数据库和私有 Unix socket，退出时停止并删除；不会读取真实 Netdisco 凭据或连接已有服务。覆盖 SQL/参数、只读限制、真实认证失败、查询中途失败、各项预算、连接回收以及 CLI 计划。
+
 ## 迁移与尚未启用的能力
 
 | 变化 | 调用方需要保留的约定 |

data/examples/netdisco_database.yml

@@ -0,0 +1,16 @@
+# 数据库连接只从 NETDISCO_DB_* 环境变量读取；此文件可直接编辑并纳入版本控制。
+netdisco:
+  source: postgres
+  query: |
+    SELECT host(ip) AS ip, name, dns, vendor, os, model, os_ver, serial
+    FROM device
+    WHERE vendor = $1
+    ORDER BY ip
+  query_params: [H3C]
+  page_size: 500
+  max_devices: 100000
+  inventory_timeout: 300
+
+backup:
+  directory: ./backups
+  concurrency: 4

data/lib/net/connector/engine/authentication.rb

@@ -62,7 +62,7 @@ module Net
         host_key = Interaction.new(SSH_CONFIRMATION, lambda { |_prompt|
           if @config.host_key_policy == :strict
             raise @session.build_error(ConnectionError, "host key confirmation rejected",
-                                 phase: :login, code: :host_key_untrusted), cause: nil
+                                       phase: :login, code: :host_key_untrusted), cause: nil
           end
           "yes\n"
         }, limit: 1)

data/lib/net/connector/engine/dialogue.rb

@@ -172,7 +172,7 @@ module Net
       def validate_event!(event, bytes, raw, phase, command)
         if bytes > @session.configuration.max_output_bytes
           raise @session.build_error(OutputLimitExceeded, "device output exceeded max_output_bytes",
-                               phase: phase, command: command, output: (raw + [event.match]).join), cause: nil
+                                     phase: phase, command: command, output: (raw + [event.match]).join), cause: nil
         end
         raise build_read_error(event, phase, command, raw.join), cause: nil unless event.matched?
       end
@@ -181,7 +181,7 @@ module Net
       def finish_response(prompt, raw, output, phase, command)
         if prompt.empty?
           raise @session.build_error(PromptError, "prompt pattern did not consume any output",
-                               phase: phase, command: command, output: raw.join), cause: nil
+                                     phase: phase, command: command, output: raw.join), cause: nil
         end
 
         raw << prompt
@@ -229,7 +229,7 @@ module Net
       def build_read_error(event, phase, command, output)
         if event&.error.is_a?(Exception)
           return @session.build_error(TransportError, "transport read failed", phase: phase, command: command,
-                                underlying: event.error, output: output)
+                                      underlying: event.error, output: output)
         end
         klass = if event&.error == :eof
                   ConnectionClosed
@@ -241,7 +241,7 @@ module Net
                   CommandTimeout
                 end
         @session.build_error(klass, "device response #{event&.error || :timeout}", phase: phase,
-                       command: command, output: output)
+                             command: command, output: output)
       end
     end
   end

data/lib/net/connector/engine/execution.rb

@@ -90,8 +90,8 @@ module Net
         return unless @output_limit && (completed ? @output_bytes > @output_limit : @output_bytes >= @output_limit)
 
         raise @session.build_error(ScriptOutputLimitExceeded,
-                             "script output reached max_script_output_bytes; commands already sent may have executed",
-                             phase: :script, command: command), cause: nil
+                                   "script output reached max_script_output_bytes; commands already sent may have executed",
+                                   phase: :script, command: command), cause: nil
       end
     end
   end

data/lib/net/connector/engine/session.rb

@@ -350,7 +350,7 @@ module Net
           redactor.reset
           @log.open(transport)
           @log.log_event("connect", host: configuration.host, username: configuration.username,
-                     phase: :connect, protocol: transport.respond_to?(:protocol) ? transport.protocol : configuration.protocol)
+                         phase: :connect, protocol: transport.respond_to?(:protocol) ? transport.protocol : configuration.protocol)
           transport.open
           @state = :authenticating
           @log.log_event("login_start", level: :debug, phase: :login)

data/lib/net/connector/netdisco/cli.rb

@@ -69,6 +69,9 @@ module Net
         def settings_for(options)
           defaults = options[:config] ? ConfigFile.load(options[:config]) : {}
           values = {}
+          values["NETDISCO_SOURCE"] = options[:source] if options[:source]
+          values["NETDISCO_QUERY"] = options[:query] if options[:query]
+          values["NETDISCO_QUERY_PARAMS"] = options[:query_params] if options[:query_params]
           values["NET_CONNECTOR_BACKUP_DIRECTORY"] = options[:directory] if options[:directory]
           values["NET_CONNECTOR_CONCURRENCY"] = options[:concurrency].to_s if options[:concurrency]
           values["NET_CONNECTOR_MAX_SCRIPT_OUTPUT_BYTES"] = options[:max_script_output_bytes].to_s if options[:max_script_output_bytes]
@@ -81,7 +84,7 @@ module Net
         # 导出已有配置不创建清单或设备连接。
         def export_config(settings, options)
           path = Storage::SavedConfig.new(directory: settings.backup_directory)
-                                        .export(host: options[:export], output: options[:output], io: @output)
+                                     .export(host: options[:export], output: options[:output], io: @output)
           @output.puts JSON.generate(host: options[:export], output: path) if path
         end
 
@@ -120,6 +123,9 @@ module Net
           parser = OptionParser.new do |args|
             args.banner = "用法：net-connector-backup [--config FILE] [--plan | --show-config | --export IP] [--tftp]"
             args.on("--config FILE", "读取不含凭据的 YAML 设置") { |value| options[:config] = value }
+            args.on("--source SOURCE", %w[http postgres], "清单来源：http（默认）或 postgres") { |value| options[:source] = value }
+            args.on("--query SQL", "PostgreSQL 清单查询，使用 $1、$2 绑定参数") { |value| options[:query] = value }
+            args.on("--query-params JSON", "查询参数的 JSON 数组") { |value| options[:query_params] = value }
             args.on("--show-config", "显示生效的非敏感设置") { options[:show_config] = true }
             args.on("--plan", "预览设备清单，不连接设备") { options[:plan] = true }
             args.on("--tftp", "由设备发起 TFTP 备份") { options[:tftp] = true }
@@ -158,8 +164,11 @@ module Net
           raise ArgumentError, "--show-config、--plan 和 --export 只能选择一项" if modes > 1
           raise ArgumentError, "--output 需要同时指定 --export" if options[:output] && !options[:export]
           raise ArgumentError, "--all 不能与 --limit-per-vendor 同时使用" if options[:all] && options[:limit]
+          if options[:export] && (options[:source] || options[:query] || options[:query_params])
+            raise ArgumentError, "--export 不能与清单查询选项同时使用"
+          end
           if options[:export] && (options[:tftp] || options[:all] || options[:limit] || options[:concurrency] || options[:host] ||
-                                  options[:success_policy] || options[:max_script_output_bytes])
+            options[:success_policy] || options[:max_script_output_bytes])
             raise ArgumentError, "--export 不能与备份选项同时使用"
           end
         end

data/lib/net/connector/netdisco/client.rb

@@ -96,7 +96,7 @@ module Net
           @options.fetch(:max_pages).times do |index|
             uri = endpoint("api/v1/search/device")
             uri.query = URI.encode_www_form(fields: FIELDS.join(","), limit: @options.fetch(:page_size),
-                                           offset: index * @options.fetch(:page_size))
+                                            offset: index * @options.fetch(:page_size))
             page = request_json(uri, authorized_get(uri, token), budget, allow_empty: true, query_fallback: true)
             validate_rows!(page, budget)
             return rows.uniq if page.empty?
@@ -274,6 +274,7 @@ module Net
         end
 
         def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
         def present?(value) = value.is_a?(String) && !value.strip.empty?
       end
     end

data/lib/net/connector/netdisco/config_file.rb

@@ -9,7 +9,10 @@ module Net
       # 命令行使用的无凭据 YAML 配置，环境变量优先。
       class ConfigFile
         FIELDS = {
-          "netdisco" => { "url" => ["NETDISCO_URL", :string],
+          "netdisco" => { "source" => ["NETDISCO_SOURCE", :string],
+                          "query" => ["NETDISCO_QUERY", :string],
+                          "query_params" => ["NETDISCO_QUERY_PARAMS", :json_array],
+                          "url" => ["NETDISCO_URL", :string],
                           "page_size" => ["NETDISCO_PAGE_SIZE", :integer],
                           "max_pages" => ["NETDISCO_MAX_PAGES", :integer],
                           "max_response_bytes" => ["NETDISCO_MAX_RESPONSE_BYTES", :integer],
@@ -94,8 +97,8 @@ module Net
             end
 
             value.join(",")
-          when :json
-            expected = name == "device_rules" ? Array : Hash
+          when :json, :json_array
+            expected = type == :json_array || name == "device_rules" ? Array : Hash
             raise ArgumentError, "#{section}.#{name} must be a #{expected}" unless value.is_a?(expected)
 
             JSON.generate(value)

data/lib/net/connector/netdisco/database_client.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "timeout"
+require_relative "client"
+
+module Net
+  module Connector
+    module Netdisco
+      # SQL 负责业务选择和列别名；适配器只管理只读查询、清单预算与连接生命周期。
+      class DatabaseClient
+        CONNECTION_ENV = {
+          host: "NETDISCO_DB_HOST", port: "NETDISCO_DB_PORT", dbname: "NETDISCO_DB_NAME",
+          user: "NETDISCO_DB_USER", password: "NETDISCO_DB_PASS",
+          sslmode: "NETDISCO_DB_SSLMODE", sslrootcert: "NETDISCO_DB_SSLROOTCERT",
+          connect_timeout: "NETDISCO_DB_CONNECT_TIMEOUT"
+        }.freeze
+        REQUIRED_CONNECTION_KEYS = %i[host dbname user password].freeze
+        DEFAULTS = Client::DEFAULTS.except(:allow_insecure_http).freeze
+
+        def self.options(query:, query_params: [], **values)
+          unless query.is_a?(String) && !query.strip.empty? && !query.include?("\0")
+            raise ArgumentError, "query must be a nonempty SQL string without NUL"
+          end
+          unless query_params.is_a?(Array) && query_params.all? { |value|
+            value.nil? || value == true || value == false || value.is_a?(Integer) ||
+              (value.is_a?(Float) && value.finite?) || (value.is_a?(String) && !value.include?("\0"))
+          }
+            raise ArgumentError, "query_params must be an array of JSON scalar values without NUL"
+          end
+          raise ArgumentError, "unknown database inventory options" unless (values.keys - DEFAULTS.keys).empty?
+
+          Client.options(**values).slice(*DEFAULTS.keys).merge(
+            query: query.dup.freeze,
+            query_params: query_params.map { |value| value.is_a?(String) ? value.dup.freeze : value }.freeze
+          ).freeze
+        end
+
+        def initialize(connection_options:, **options)
+          @options = self.class.options(**options)
+          @connection_options = validate_connection_options(connection_options)
+        end
+
+        # 每次查询独占连接和游标；只有全部结果验证成功后才把清单交给 Fleet。
+        def devices
+          require "pg"
+          budget = InventoryBudget.new(@options, clock: method(:monotonic))
+          connection = nil
+          connected = false
+          begin
+            Timeout.timeout(budget.remaining, Client::InventoryTimeout) do
+              # 从握手开始持有连接；PG.connect 尚未返回时被超时中断，调用方无法负责关闭它。
+              connection = PG::Connection.connect_start(@connection_options)
+              # PostgreSQL NOTICE 可能包含 SQL 或数据，不交给 libpq 默认的 stderr 输出器。
+              connection.set_notice_processor { |_notice| nil }
+              wait_for_connection(connection, budget)
+              connected = true
+              # 使用 pg 可中断的 Ruby 等待接口；底层 socket 仍以非阻塞方式工作。
+              connection.setnonblocking(false)
+              connection.set_client_encoding("UTF8")
+              connection.exec("BEGIN READ ONLY").clear
+              set_statement_timeout(connection, budget)
+              # 即使没有参数也走扩展查询协议，由 PostgreSQL 拒绝多语句和非查询命令。
+              connection.exec_params("DECLARE net_connector_inventory NO SCROLL CURSOR FOR\n#{@options.fetch(:query)}",
+                                     @options.fetch(:query_params)).clear
+              rows = inventory(connection, budget)
+              connection.exec("ROLLBACK").clear
+              budget.remaining
+              rows
+            end
+          rescue Client::Error => error
+            raise error, cause: nil
+          rescue PG::QueryCanceled
+            raise Client::InventoryTimeout, cause: nil
+          rescue PG::Error, IOError, SystemCallError
+            code = connected ? :query_failed : :connection_failed
+            raise Client::Error.new("Netdisco database #{code.to_s.tr("_", " ")}", code: code), cause: nil
+          ensure
+            connection&.finish
+          end
+        end
+
+        def inspect = "#<#{self.class}>"
+
+        private
+
+        def wait_for_connection(connection, budget)
+          deadline = monotonic + @connection_options.fetch(:connect_timeout, budget.remaining).to_f
+          loop do
+            status = connection.connect_poll
+            return if status == PG::PGRES_POLLING_OK
+            raise PG::ConnectionBad unless [PG::PGRES_POLLING_READING, PG::PGRES_POLLING_WRITING].include?(status)
+
+            remaining = [budget.remaining, deadline - monotonic].min
+            raise PG::ConnectionBad if remaining <= 0
+
+            socket = connection.socket_io
+            readers = status == PG::PGRES_POLLING_READING ? [socket] : nil
+            writers = status == PG::PGRES_POLLING_WRITING ? [socket] : nil
+            next if IO.select(readers, writers, [socket], remaining)
+
+            budget.remaining
+            raise PG::ConnectionBad
+          end
+        end
+
+        def validate_connection_options(options)
+          unless options.is_a?(Hash) && (options.keys - CONNECTION_ENV.keys).empty?
+            raise ArgumentError, "connection_options must contain supported PostgreSQL connection keys"
+          end
+          REQUIRED_CONNECTION_KEYS.each do |key|
+            value = options[key]
+            unless value.is_a?(String) && !value.strip.empty?
+              raise ArgumentError, "#{CONNECTION_ENV.fetch(key)} is required"
+            end
+          end
+          options.each do |key, value|
+            valid = value.is_a?(String) && !value.empty? && !value.include?("\0")
+            valid ||= %i[port connect_timeout].include?(key) && value.is_a?(Integer)
+            raise ArgumentError, "#{CONNECTION_ENV.fetch(key)} is invalid" unless valid
+          end
+          %i[port connect_timeout].each do |key|
+            next unless options.key?(key)
+
+            value = options.fetch(key).to_s
+            maximum = key == :port ? 65_535 : 2_147_483_647
+            unless value.match?(/\A\d+\z/) && value.to_i.between?(1, maximum)
+              raise ArgumentError, "#{CONNECTION_ENV.fetch(key)} must be a positive integer within range"
+            end
+          end
+          if options[:sslmode] && !%w[disable allow prefer require verify-ca verify-full].include?(options[:sslmode])
+            raise ArgumentError, "NETDISCO_DB_SSLMODE is invalid"
+          end
+          # libpq 会把 dbname 中的 URI/conninfo 再解释为连接参数，不能借此绕过凭据来源。
+          if options.fetch(:dbname).match?(/=|\Apostgres(?:ql)?:\/\//)
+            raise ArgumentError, "NETDISCO_DB_NAME must be a database name, not a connection string"
+          end
+          options.transform_values { |value| value.is_a?(String) ? value.dup.freeze : value }.freeze
+        end
+
+        def set_statement_timeout(connection, budget)
+          milliseconds = [(budget.remaining * 1000).ceil, 2_147_483_647].min
+          connection.exec_params("SELECT set_config('statement_timeout', $1, true)", [milliseconds.to_s]).clear
+        end
+
+        def inventory(connection, budget)
+          rows = []
+          @options.fetch(:max_pages).times do
+            set_statement_timeout(connection, budget)
+            count = fetch_page(connection, rows, budget)
+            return rows if count < @options.fetch(:page_size)
+          end
+          raise Client::Error.new("Netdisco inventory exceeded max_pages", code: :max_pages), cause: nil
+        end
+
+        # 单行模式避免 libpq 先缓存整页；Ruby 只积累已经通过预算检查的白名单字段。
+        def fetch_page(connection, rows, budget)
+          connection.send_query_params("FETCH FORWARD #{@options.fetch(:page_size)} FROM net_connector_inventory", [])
+          connection.set_single_row_mode
+          count = 0
+          response_bytes = 0
+          while (result = connection.get_result)
+            begin
+              result.check
+              response_bytes = append_rows(result, rows, budget, response_bytes)
+              count += result.ntuples
+            ensure
+              result.clear
+            end
+          end
+          count
+        end
+
+        def append_rows(result, rows, budget, response_bytes)
+          fields = result.fields
+          unless fields.include?("ip") && fields.uniq == fields
+            raise Client::Error.new("Netdisco database query must return unique column names including ip",
+                                    code: :invalid_inventory), cause: nil
+          end
+          budget.consume_devices(result.ntuples)
+          result.each do |row|
+            # 未选用的列也占传输预算，但不会进入清单、计划或报告。
+            size = row.sum { |key, value| key.bytesize + (value&.bytesize || 0) }
+            budget.consume_bytes(size, response_bytes: response_bytes)
+            response_bytes += size
+            unless row["ip"].is_a?(String) && !row["ip"].strip.empty?
+              raise Client::Error.new("Netdisco returned an invalid device inventory", code: :invalid_inventory), cause: nil
+            end
+            rows << row.slice(*Client::FIELDS)
+          end
+          response_bytes
+        end
+
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/net/connector/netdisco/settings.rb

@@ -63,6 +63,13 @@ module Net
 
         def client(policy: snapshot(mode: :inventory))
           options = policy.client_options
+          if policy.inventory_source == :postgres
+            connection = DatabaseClient::CONNECTION_ENV.each_with_object({}) do |(key, name), values|
+              item = secret_value(name)
+              values[key] = item if item
+            end
+            return DatabaseClient.new(connection_options: connection, **options)
+          end
           raise ArgumentError, "NETDISCO_URL is required" unless options.fetch(:url)
 
           authentication = if (token = secret_value("NETDISCO_API_KEY"))
@@ -73,9 +80,17 @@ module Net
           Client.new(**options, **authentication)
         end
 
-        # 原生客户端和 --show-config 共享同一预算、地址与 HTTP 策略校验。
+        def inventory_source
+          source = value("NETDISCO_SOURCE") || "http"
+          raise ArgumentError, "NETDISCO_SOURCE must be http or postgres" unless %w[http postgres].include?(source)
+
+          source.to_sym
+        end
+
+        # 原生客户端和 --show-config 共享预算校验；只验证所选来源的查询设置。
         def client_options
-          options = Client::DEFAULTS.to_h do |name, default|
+          defaults = inventory_source == :postgres ? DatabaseClient::DEFAULTS : Client::DEFAULTS
+          options = defaults.to_h do |name, default|
             key = "NETDISCO_#{name.to_s.upcase}"
             parsed = case name
                      when :inventory_timeout then number(key, default)
@@ -84,6 +99,13 @@ module Net
                      end
             [name, parsed]
           end
+          if inventory_source == :postgres
+            query = value("NETDISCO_QUERY") || (raise ArgumentError, "NETDISCO_QUERY is required for postgres")
+            return DatabaseClient.options(query: query, query_params: json("NETDISCO_QUERY_PARAMS", []), **options)
+          end
+          if value("NETDISCO_QUERY") || value("NETDISCO_QUERY_PARAMS")
+            raise ArgumentError, "SQL query settings require NETDISCO_SOURCE=postgres"
+          end
           options = Client.options(**options)
           url = value("NETDISCO_URL")
           Client.validate_url!(url, allow_insecure_http: options.fetch(:allow_insecure_http)) if url
@@ -189,7 +211,7 @@ module Net
 
         def config_hash
           {
-            netdisco: client_options,
+            netdisco: client_options.merge(source: inventory_source),
             backup: { directory: backup_directory, concurrency: concurrency, limit_per_vendor: limit_per_vendor },
             inventory: { include_hosts: list("NET_CONNECTOR_INCLUDE_HOSTS"),
                          exclude_hosts: list("NET_CONNECTOR_EXCLUDE_HOSTS"),
@@ -279,6 +301,7 @@ module Net
         end
 
         def required_secret(key) = secret_value(key) || (raise ArgumentError, "#{key} is required")
+
         def present?(value) = value.is_a?(String) && !value.strip.empty?
       end
     end

data/lib/net/connector/netdisco.rb

@@ -2,6 +2,7 @@
 
 require_relative "../connector"
 require_relative "netdisco/client"
+require_relative "netdisco/database_client"
 require_relative "netdisco/rules"
 require_relative "netdisco/device"
 require_relative "netdisco/config_file"

data/lib/net/connector/version.rb

@@ -2,6 +2,6 @@
 
 module Net
   module Connector
-    VERSION = "0.5.0"
+    VERSION = "0.6.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-connector
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - net-connector contributors
@@ -37,6 +37,26 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: digest
   requirement: !ruby/object:Gem::Requirement
@@ -407,6 +427,7 @@ files:
 - docs/RELEASING.md
 - docs/VERIFICATION.md
 - docs/architecture.md
+- examples/netdisco_database.yml
 - exe/net-connector-backup
 - lib/net-connector.rb
 - lib/net/connector.rb
@@ -451,6 +472,7 @@ files:
 - lib/net/connector/netdisco/cli.rb
 - lib/net/connector/netdisco/client.rb
 - lib/net/connector/netdisco/config_file.rb
+- lib/net/connector/netdisco/database_client.rb
 - lib/net/connector/netdisco/device.rb
 - lib/net/connector/netdisco/diagnostic.rb
 - lib/net/connector/netdisco/fleet.rb