# 通过 PostgreSQL 协议连接 EMQX Tables

EMQX Tables 支持 PostgreSQL 网络连接协议，可以使用 `psql` 和兼容客户端驱动连接数据库并执行 SQL。连接使用 TLS 加密。

PostgreSQL 协议兼容不代表完整 PostgreSQL 服务兼容。SQL 方言、函数和扩展的支持范围以 Tables 为准。

## 连接参数

进入目标 Tables 部署，点击**集成与客户端**，然后点击 **PostgreSQL**。Console 会在连接指南中填入当前部署的域名、端口、数据库名称、用户名和密码。

| 参数 | 值 |
| --- | --- |
| 主机 | `{HOST}`，替换为 Tables 公网域名 |
| 端口 | `4003` |
| 数据库 | `{DB_NAME}`，例如 `public` |
| 用户名 | `{USER}`，替换为连接信息中显示的用户名 |
| 密码 | `{PASSWORD}`，替换为该部署连接信息中显示的密码 |
| SSL 模式 | `require` |

使用目标部署的连接地址、端口和连接凭据，将以下模板中的占位符替换为实际连接值。

## PostgreSQL 命令行工具

安装 `psql` 后，将占位符替换为实际连接值，运行：

```bash
psql "host={HOST} port=4003 dbname={DB_NAME} user={USER} sslmode=require" -W
```

按提示输入密码。连接成功后，执行以下 SQL 验证：

```sql
SELECT 1;
```

如已完成快速开始，还可查询业务数据：

```sql
SELECT * FROM machine_metrics ORDER BY ts DESC LIMIT 10;
```

## 连接字符串

在支持 PostgreSQL 连接字符串的客户端库中，可使用以下模板：

```text
host={HOST} port=4003 dbname={DB_NAME} user={USER} password={PASSWORD} sslmode=require
```

根据所用驱动的规则处理密码中的特殊字符。应用配置中应通过环境变量或凭据管理机制提供密码，避免将真实密码提交到代码仓库。

## URL 格式

### JDBC

```text
jdbc:postgresql://{HOST}:4003/{DB_NAME}?sslmode=require
```

将用户名和密码作为 JDBC 连接属性传入。

### PostgreSQL URI

```text
postgresql://{USER}:{PASSWORD}@{HOST}:4003/{DB_NAME}?sslmode=require
```

URI 中的用户名和密码需要按 URI 规则编码。应优先使用驱动提供的独立用户名、密码参数，避免把凭据记录到日志中。

## TLS 和连接排查

`sslmode=require` 要求加密连接，但不提供完整的服务端主机名校验。
需要验证服务端身份时，应按所用驱动的要求配置受信任 CA 和主机名验证，并使用 Tables 域名连接。

连接失败时，检查域名、端口 `4003`、网络连通性、TLS、连接密码和数据库名称。连接成功但 SQL 失败时，应检查 SQL 是否属于 Tables 支持的语法。