PostgreSQL Protocol Proxy

Relevant source files

The following files were used as context for generating this wiki page:

• warpgate-protocol-postgres/src/lib.rs
• warpgate-protocol-postgres/src/session.rs
• warpgate-protocol-postgres/src/client.rs
• warpgate-protocol-postgres/Cargo.toml
• warpgate/src/commands/setup.rs
• README.md

The PostgreSQL Protocol Proxy in Warpgate acts as a secure intermediary for PostgreSQL database connections. It resides between the client and the target database server, providing centralized authentication, session recording, and access control without requiring specialized client applications.

Sources: README.md:1-20, warpgate-protocol-postgres/src/lib.rs:25-30

Architecture and Components

The proxy is implemented as a protocol-specific server that manages the lifecycle of a PostgreSQL connection. It utilizes the pgwire crate for message parsing and rustls for secure transport.

Key Components

Component	Description
PostgresProtocolServer	The entry point that listens for incoming TCP connections and initializes the session.
PostgresSession	Manages the state and logic for a single client connection, including authentication and proxying.
PostgresClient	Handles the connection and communication from Warpgate to the actual target PostgreSQL database.
PostgresStream	A wrapper for the underlying transport (TCP/TLS) to handle PostgreSQL-specific framing.

Sources: warpgate-protocol-postgres/src/lib.rs:25-35, warpgate-protocol-postgres/src/session.rs:20-35, warpgate-protocol-postgres/src/client.rs:18-20, warpgate-protocol-postgres/Cargo.toml:16

Data Flow Overview

The proxy facilitates a bidirectional flow of PgWire messages. It intercepts the initial handshake to perform local authentication before establishing a back-end connection to the target.

The diagram shows the high-level positioning of Warpgate as a transparent proxy between the client and the target database. Sources: warpgate-protocol-postgres/src/session.rs:245-285, README.md:50-55

Connection Lifecycle

1. Initialization and TLS Upgrade

When a client connects, the proxy first checks for an SslRequest. If the client requests SSL, Warpgate handles the TLS handshake using its configured server certificate.

Sources: warpgate-protocol-postgres/src/session.rs:64-80, warpgate-protocol-postgres/src/lib.rs:40-60

2. Authentication and Authorization

Warpgate supports two primary methods for identifying the user and target:

• User/Target String: The username field in the startup message is parsed as user#target.
• Tickets: Temporary secrets used for one-time access.

This sequence illustrates the cleartext password flow often used to bridge client authentication to the proxy's internal user store. Sources: warpgate-protocol-postgres/src/session.rs:88-120, warpgate-protocol-postgres/src/client.rs:60-120

3. Proxying and Auditing

Once authorized, the proxy enters a loop where it selects messages between the client stream and the target client. Specific messages like Query, Parse, and Execute are intercepted for logging purposes.

Sources: warpgate-protocol-postgres/src/session.rs:245-285, warpgate-protocol-postgres/src/session.rs:294-308

Configuration

PostgreSQL-specific configuration is handled through the PostgresConfig structure, which includes listener settings and TLS certificates.

Configuration Field	Type	Description
listen	ListenEndpoint	The address and port the proxy listens on (Default: [::]:5432).
certificate	PathBuf	Path to the TLS certificate file.
key	PathBuf	Path to the TLS private key file.
enable	bool	Whether the PostgreSQL protocol is active.

Sources: warpgate/src/commands/setup.rs:165-185, warpgate/src/commands/setup.rs:200-210

Target Options

When defining a PostgreSQL target in Warpgate, the following parameters are used to establish the outbound connection:

// Representative structure for target options
pub struct TargetPostgresOptions {
    pub host: String,
    pub port: u16,
    pub username: String,
    pub password: Option<String>,
    pub tls: TlsMode, // Disabled, Preferred, Required
}

Sources: warpgate-protocol-postgres/src/client.rs:55-65, warpgate-protocol-postgres/src/session.rs:205-215

Implementation Details

Message Interception

The proxy specifically monitors query-related messages to provide administrative visibility.

fn maybe_log_client_msg(&self, msg: &PgWireFrontendMessage) {
    match msg {
        PgWireFrontendMessage::Parse(query) => {
            info!(query_name=?query.name, "Preparing query");
        }
        PgWireFrontendMessage::Query(query) => {
            info!(query=%query.query, "Query");
        }
        _ => (),
    }
}

Sources: warpgate-protocol-postgres/src/session.rs:294-308

Error Handling

If the connection to the target fails or authentication is rejected, the proxy sends a standard PostgreSQL ErrorResponse (using SQLState codes like 28P01 for auth failure or 0W001 for target not found) to ensure compatibility with standard SQL clients.

Sources: warpgate-protocol-postgres/src/session.rs:137-145, warpgate-protocol-postgres/src/session.rs:220-225

Summary

The PostgreSQL Protocol Proxy provides a secure, audited gateway for database traffic. By implementing the pgwire protocol, it allows users to connect using standard tools (like psql) while Warpgate handles 2FA, SSO integration, and detailed session logging.

Sources: README.md:5-15, warpgate-protocol-postgres/src/lib.rs:80-110助理:

相关源文件

生成此维基页面使用了以下文件作为上下文：

• warpgate-protocol-postgres/src/lib.rs
• warpgate-protocol-postgres/src/session.rs
• warpgate-protocol-postgres/src/client.rs
• warpgate-protocol-postgres/Cargo.toml
• warpgate/src/commands/setup.rs
• README.md

Warpgate 中的 PostgreSQL 协议代理充当 PostgreSQL 数据库连接的安全中间件。它位于客户端和目标数据库服务器之间，在不需要特殊客户端应用程序的情况下提供集中的身份验证、会话记录和访问控制。

来源：README.md:1-20, warpgate-protocol-postgres/src/lib.rs:25-30

架构与组件

该代理实现为一个协议特定的服务器，负责管理 PostgreSQL 连接的生命周期。它利用 pgwire 库进行消息解析，并使用 rustls 进行安全传输。

核心组件

组件	描述
PostgresProtocolServer	入口点，监听传入的 TCP 连接并初始化会话。
PostgresSession	管理单个客户端连接的状态和逻辑，包括身份验证和代理转发。
PostgresClient	处理从 Warpgate 到实际目标 PostgreSQL 数据库的连接和通信。
PostgresStream	对底层传输（TCP/TLS）的包装，用于处理 PostgreSQL 特定的帧。

来源：warpgate-protocol-postgres/src/lib.rs:25-35, warpgate-protocol-postgres/src/session.rs:20-35, warpgate-protocol-postgres/src/client.rs:18-20, warpgate-protocol-postgres/Cargo.toml:16

数据流概览

代理促进了 PgWire 消息的双向流动。它截获初始握手以执行本地身份验证，然后建立到后端目标数据库的连接。

该图展示了 Warpgate 作为客户端和目标数据库之间透明代理的高层定位。来源：warpgate-protocol-postgres/src/session.rs:245-285, README.md:50-55

连接生命周期

1. 初始化与 TLS 升级

当客户端连接时，代理首先检查 SslRequest。如果客户端请求 SSL，Warpgate 使用其配置的服务器证书处理 TLS 握手。

来源：warpgate-protocol-postgres/src/session.rs:64-80, warpgate-protocol-postgres/src/lib.rs:40-60

2. 身份验证与授权

Warpgate 支持两种主要方法来识别用户和目标：

• 用户/目标字符串：启动消息中的用户名参数被解析为 user#target。
• Ticket (票据)：用于一次性访问的临时密钥。

此序列展示了通常用于将客户端身份验证桥接到代理内部用户存储的明文密码流。来源：warpgate-protocol-postgres/src/session.rs:88-120, warpgate-protocol-postgres/src/client.rs:60-120

3. 代理转发与审计

授权成功后，代理进入循环，在客户端流和目标客户端之间选择消息进行转发。特定的消息如 Query、Parse 和 Execute 会被拦截以用于日志记录。

来源：warpgate-protocol-postgres/src/session.rs:245-285, warpgate-protocol-postgres/src/session.rs:294-308

配置

PostgreSQL 特定的配置通过 PostgresConfig 结构体处理，包括监听设置和 TLS 证书。

配置字段	类型	描述
listen	ListenEndpoint	代理监听的地址和端口（默认：[::]:5432）。
certificate	PathBuf	TLS 证书文件的路径。
key	PathBuf	TLS 私钥文件的路径。
enable	bool	是否启用 PostgreSQL 协议。

来源：warpgate/src/commands/setup.rs:165-185, warpgate/src/commands/setup.rs:200-210

目标选项

在 Warpgate 中定义 PostgreSQL 目标时，使用以下参数建立出站连接：

// 目标选项的代表性结构
pub struct TargetPostgresOptions {
    pub host: String,
    pub port: u16,
    pub username: String,
    pub password: Option<String>,
    pub tls: TlsMode, // Disabled, Preferred, Required
}

来源：warpgate-protocol-postgres/src/client.rs:55-65, warpgate-protocol-postgres/src/session.rs:205-215

实现细节

消息拦截

代理专门监控查询相关的消息，以提供管理可见性。

fn maybe_log_client_msg(&self, msg: &PgWireFrontendMessage) {
    match msg {
        PgWireFrontendMessage::Parse(query) => {
            info!(query_name=?query.name, "正在预处理查询");
        }
        PgWireFrontendMessage::Query(query) => {
            info!(query=%query.query, "查询");
        }
        _ => (),
    }
}

来源：warpgate-protocol-postgres/src/session.rs:294-308

错误处理

如果连接到目标失败或身份验证被拒绝，代理会向客户端发送标准的 PostgreSQL ErrorResponse（使用 SQLState 代码，如认证失败的 28P01 或未找到目标的 0W001），以确保与标准 SQL 客户端的兼容性。

来源：warpgate-protocol-postgres/src/session.rs:137-145, warpgate-protocol-postgres/src/session.rs:220-225

总结

PostgreSQL 协议代理为数据库流量提供了一个安全、受审计的网关。通过实现 pgwire 协议，它允许用户使用标准工具（如 psql）进行连接，同时 Warpgate 负责处理 2FA、SSO 集成和详细的会话日志记录。

来源：README.md:5-15, warpgate-protocol-postgres/src/lib.rs:80-110