ngx_postgres 项目技术文档

1. 安装指南

1.1 环境要求

ngx_postgres 模块适用于以下版本的 Nginx：

• 0.7.x (测试版本：0.7.60 到 0.7.69)
• 0.8.x (测试版本：0.8.0 到 0.8.55)
• 0.9.x (测试版本：0.9.0 到 0.9.7)
• 1.0.x (测试版本：1.0.0 到 1.0.11)
• 1.1.x (测试版本：1.1.0 到 1.1.12)
• 1.2.x (测试版本：1.2.3 到 1.2.3)
• 1.3.x (测试版本：1.3.4 到 1.3.4)

1.2 安装步骤

1. 下载并编译 Nginx：

   • 下载适合版本的 Nginx 源码。
   • 解压源码并进入目录。

2. 下载 ngx_postgres 模块：

   • 从 GitHub 或其他源码托管平台下载 ngx_postgres 模块的源码。

3. 编译 Nginx：

   • 在 Nginx 源码目录下执行以下命令：

     ./configure --add-module=/path/to/ngx_postgres
     make
     make install
     

   • 将 /path/to/ngx_postgres 替换为 ngx_postgres 模块的实际路径。

4. 验证安装：

   • 启动 Nginx，检查是否正常运行。
   • 通过配置文件验证 ngx_postgres 模块是否正确加载。

2. 项目的使用说明

2.1 基本概念

ngx_postgres 是一个 Nginx 的上游模块，允许 Nginx 直接与 PostgreSQL 数据库通信。生成的响应格式为 rds，因此与 ngx_rds_json 和 ngx_drizzle 模块兼容。

2.2 配置文件示例

以下是一个简单的配置示例，展示如何使用 ngx_postgres 模块从 PostgreSQL 数据库中获取数据：

http {
    upstream database {
        postgres_server  127.0.0.1 dbname=test user=test password=test;
    }

    server {
        location / {
            postgres_pass   database;
            postgres_query  "SELECT * FROM cats";
        }
    }
}

2.3 响应格式

ngx_postgres 模块支持多种输出格式，包括 rds、text、value、binary_value 和 none。默认输出格式为 rds。

3. 项目API使用文档

3.1 postgres_server

• 语法: postgres_server ip[:port] dbname=dbname user=user password=pass
• 默认值: 无
• 上下文: upstream

设置数据库服务器的详细信息。

3.2 postgres_keepalive

• 语法: postgres_keepalive off | max=count [mode=single|multi] [overflow=ignore|reject]
• 默认值: max=10 mode=single overflow=ignore
• 上下文: upstream

配置长连接参数。

3.3 postgres_pass

• 语法: postgres_pass upstream
• 默认值: 无
• 上下文: location, if location

设置用于数据库连接的上游块名称。

3.4 postgres_query

• 语法: postgres_query [methods] query
• 默认值: 无
• 上下文: http, server, location, if location

设置查询字符串。

3.5 postgres_rewrite

• 语法: postgres_rewrite [methods] condition [=]status_code
• 默认值: 无
• 上下文: http, server, location, if location

根据条件重写响应状态码。

3.6 postgres_output

• 语法: postgres_output rds|text|value|binary_value|none
• 默认值: rds
• 上下文: http, server, location, if location

设置输出格式。

3.7 postgres_set

• 语法: postgres_set $variable row column [optional|required]
• 默认值: 无
• 上下文: http, server, location

从结果集中获取单个值并存储在变量中。

3.8 postgres_escape

• 语法: postgres_escape $escaped [[=]$unescaped]
• 默认值: 无
• 上下文: http, server, location

转义并引用字符串。

3.9 postgres_connect_timeout

• 语法: postgres_connect_timeout timeout
• 默认值: 10s
• 上下文: http, server, location

设置连接数据库的超时时间。

3.10 postgres_result_timeout

• 语法: postgres_result_timeout timeout
• 默认值: 30s
• 上下文: http, server, location

设置接收数据库结果的超时时间。

4. 项目安装方式

4.1 源码编译安装

通过源码编译安装 ngx_postgres 模块，具体步骤如下：

1. 下载 Nginx 源码。
2. 下载 ngx_postgres 模块源码。
3. 编译 Nginx 并添加 ngx_postgres 模块。

4.2 使用包管理器安装

某些操作系统可能提供包管理器安装方式，具体请参考相关文档。

---

通过以上文档，您可以详细了解 ngx_postgres 模块的安装、配置和使用方法。