腾讯云云数据库PostgreSQL完全对接指南：从开通到生产级应用
1. 云数据库PostgreSQL概述与实例创建
腾讯云云数据库PostgreSQL（TencentDB for PostgreSQL）是腾讯云基于开源PostgreSQL打造的一款企业级关系型数据库服务。它具备自动备份、监控告警、弹性扩容、只读实例、安全组隔离等全套能力，让开发者无需关心底层运维，即可享受高性能、高可用的数据库服务。
在使用之前，首先需要完成实例的创建。登录腾讯云控制台后，在数据库分类下找到云数据库PostgreSQL，点击创建实例。创建过程中需要选择数据库版本（目前支持PostgreSQL 10到17等多个大版本）、地域与可用区、实例规格（CPU与内存）、存储空间大小以及网络类型。网络类型建议选择私有网络VPC，将数据库部署在与你业务服务器相同的VPC内，以便利用内网高速通道进行低延迟访问。创建完成后，系统会自动分配一个内网地址（VIP）和端口（默认为5432），该VIP通过接入网关集群统一访问数据库实例，即使发生主机故障或主备切换，内网IP也不会发生变化。
需要先登录腾讯云控制台，点击：腾讯云控制台，还没有账号，点击：注册后再关联，已有账号点击：登录后再关联
2. 网络连接方式：内网与外网
腾讯云PostgreSQL提供两种连接方式：内网连接和外网连接。
2.1 内网连接（推荐）
内网连接是指通过同一VPC内的云服务器CVM访问数据库的内网地址。这种方式的优势在于：使用内网高速网络，延迟极低（通常在1ms以内）；数据传输不走公网，安全性更高；不产生额外的外网流量费用。建议将CVM和数据库部署在同一账号、同一地域、同一VPC内。如果CVM和数据库处于不同的VPC下，可以通过对等连接或云联网实现内网互通。
2.2 外网连接
外网连接适用于开发测试或辅助管理场景，不推荐用于正式业务访问。开启外网地址后，数据库服务将暴露在公网上，存在被攻击的风险。目前仅广州、上海、北京、成都、中国香港、硅谷等地域支持开启外网访问。开启方式为：在实例详情页的基本信息区域，单击外网IPv4地址后的开启按钮。开启外网后，必须配置安全组规则才能正常访问。需要注意的是，外网访问不纳入SLA可用性保障，且外网IP可能因规格调整或网络升级而发生变化，建议使用外网域名而非IP进行访问。
3. 客户端连接方式
3.1 使用psql命令行工具（Linux）
psql是PostgreSQL官方自带的命令行客户端，是在Linux环境下最常用的连接方式。首先需要在Linux云服务器上安装PostgreSQL客户端：
yum install -y postgresql.x86_64安装完成后，执行以下命令连接数据库：
psql -U 用户名 -h 访问地址 -p 端口 -d postgres其中，-U指定数据库用户名（默认为创建实例时设置的管理员账号），-h指定数据库的内网或外网地址，-p指定端口（默认为5432），-d指定要连接的数据库名称。如果是在与数据库同一VPC的CVM中，访问地址使用内网地址；如果是从公网连接，则使用外网地址。连接成功后，会进入psql交互式命令行界面，可以执行SQL语句进行数据操作。
除了参数形式，psql也支持使用连接字符串或URI方式连接：
psql postgresql://用户名@访问地址:端口/postgres3.2 使用pgAdmin图形化工具（Windows）
pgAdmin是PostgreSQL官方推荐的图形化管理工具，适合不熟悉命令行的开发者进行数据库管理。使用步骤如下：
- 从pgAdmin官网下载并安装适合自己系统的版本。
- 打开pgAdmin，在顶部菜单选择Object > Create > Server。
- 在弹出的对话框中，填写连接信息：Name（自定义名称）、Host（数据库内网或外网地址）、Port（端口号）、Username（数据库用户名）、Password（密码）。
- 单击Save保存，即可在左侧导航中看到连接成功的数据库实例。
pgAdmin提供了可视化的表结构管理、数据浏览、SQL查询执行、性能监控等功能，是日常运维和开发调试的得力工具。
3.3 使用其他通用数据库客户端
除了psql和pgAdmin，开发者还可以使用DBeaver、Navicat、DataGrip等通用数据库客户端连接腾讯云PostgreSQL。这些工具通常只需要填写Host、Port、Database、Username、Password等标准连接参数即可，连接方式与连接自建PostgreSQL完全一致。
4. 安全组配置与访问控制
安全组是腾讯云提供的虚拟防火墙，用于控制云数据库的入站流量。云数据库PostgreSQL安全组目前仅支持私有网络VPC内网访问和外网访问的网络控制。一个数据库实例最多可以绑定5个安全组，多个安全组按优先级顺序依次匹配执行，所有安全组配置取并集。
4.1 创建与配置安全组
在安全组控制台中，选择地域后点击新建，可以创建新的安全组。创建时可以选用预置模板（如放通全部端口、放通常用端口等），也可以选择自定义模板按需配置规则。对于PostgreSQL数据库，最关键的是在入站规则中放通5432端口：
- 来源：指定允许访问的IP地址范围（如CVM的内网IP或CIDR段）
- 协议端口：TCP:5432
- 策略：允许
如果开启了外网访问，还需要在安全组中放通允许公网访问的IP地址。安全组规则支持单个IP、IP段（CIDR表示法）、引用其他安全组等多种来源配置方式。
4.2 绑定安全组到实例
创建好安全组后，需要将其绑定到PostgreSQL实例上：
- 登录PostgreSQL控制台，在实例列表单击目标实例ID进入管理页面。
- 选择安全组页签，单击配置安全组。
- 在弹出的对话框中选择需要绑定的安全组，单击确定完成绑定。
对于只读实例组，也可以在只读实例管理页面的安全组页签中，选择生效对象为只读实例组，再绑定安全组。
5. 账号管理与权限控制
实例创建时会自动生成一个管理员账号（默认为postgres），拥有最高权限。开发者可以通过控制台的账号管理功能创建新的数据库账号，并为不同账号分配不同的权限。在生产环境中，建议遵循最小权限原则：为不同的应用创建独立的数据库账号，仅授予其所需的最小权限（如只读账号仅授予SELECT权限，读写账号授予CRUD权限）。如果忘记管理员密码，可以在控制台的账号管理页进行重置。
6. 编程语言SDK对接
6.1 Java应用对接（JDBC）
Java应用通过JDBC驱动连接PostgreSQL是最常见的方式。首先需要在项目中引入PostgreSQL JDBC驱动依赖（Maven）：
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<version>42.7.3</version>
</dependency>连接示例代码：
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.Statement;
import java.sql.SQLException;
public class PostgreSQLConnector {
public static void main(String[] args) {
String host = "你的数据库内网地址";
String port = "5432";
String database = "postgres";
String username = "你的用户名";
String password = "你的密码";
String jdbcUrl = "jdbc:postgresql://" + host + ":" + port + "/" + database;
try {
Class.forName("org.postgresql.Driver");
Connection conn = DriverManager.getConnection(jdbcUrl, username, password);
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery("SELECT version()");
while (rs.next()) {
System.out.println("PostgreSQL version: " + rs.getString(1));
}
rs.close();
stmt.close();
conn.close();
} catch (ClassNotFoundException | SQLException e) {
e.printStackTrace();
}
}
}6.2 Python应用对接（psycopg2）
Python开发者可以使用psycopg2库连接PostgreSQL。安装方式：
pip install psycopg2-binary连接示例代码：
import psycopg2
try:
conn = psycopg2.connect(
host="你的数据库内网地址",
port=5432,
database="postgres",
user="你的用户名",
password="你的密码"
)
cur = conn.cursor()
cur.execute("SELECT version()")
version = cur.fetchone()
print(f"PostgreSQL version: {version[0]}")
cur.close()
conn.close()
except Exception as e:
print(f"连接失败: {e}")6.3 Node.js应用对接（pg库）
Node.js开发者可以使用pg库连接PostgreSQL。安装方式：
npm install pg连接示例代码：
const { Client } = require('pg');
const client = new Client({
host: '你的数据库内网地址',
port: 5432,
database: 'postgres',
user: '你的用户名',
password: '你的密码'
});
client.connect()
.then(() => {
return client.query('SELECT version()');
})
.then(res => {
console.log('PostgreSQL version:', res.rows[0].version);
return client.end();
})
.catch(err => {
console.error('连接失败:', err);
});6.4 Go应用对接（pgx）
Go语言推荐使用pgx库连接PostgreSQL，它比标准database/sql性能更好且支持更多PostgreSQL特性。安装方式：
go get github.com/jackc/pgx/v5连接示例代码：
package main
import (
"context"
"fmt"
"github.com/jackc/pgx/v5"
)
func main() {
conn, err := pgx.Connect(context.Background(),
"postgres://用户名:密码@数据库地址:5432/postgres")
if err != nil {
fmt.Printf("连接失败: %v\n", err)
return
}
defer conn.Close(context.Background())
var version string
err = conn.QueryRow(context.Background(), "SELECT version()").Scan(&version)
if err != nil {
fmt.Printf("查询失败: %v\n", err)
return
}
fmt.Printf("PostgreSQL version: %s\n", version)
}7. 性能调优与参数优化
7.1 syscache/relcache缓存淘汰机制
在大规模复杂业务场景下，数据库进程长连接可能会打开大量表和索引，导致syscache和relcache缓存压力巨大，进而引发内存占用过高或缓存命中率下降的问题。腾讯云PostgreSQL支持基于LRU（Least Recently Used）算法的syscache和relcache缓存淘汰机制。用户可以通过参数设置开启该功能：
- tencentdb_syscache_max_num：一个进程最多能拥有多少个syscache，超过此数量开始淘汰。默认-1表示不开启，建议取值范围10000-50000。
- tencentdb_syscache_evict_num：一次淘汰清理多少个syscache。默认1，可适当调高至5-10以加速内存释放。
- tencentdb_relcache_max_num：一个进程最多能拥有多少个relcache，默认-1不开启，建议取值范围1000-5000。
- tencentdb_relcache_evict_num：一次淘汰清理多少个relcache。默认1。
这些参数可以在控制台的参数设置页面进行修改。建议根据实例内存大小和负载情况逐步调整，避免频繁淘汰带来的性能开销。
7.2 连接数控制（soft_limit_connections）
在PostgreSQL中，从库的max_connections参数值需要大于或等于主库。当主实例规格较大而只读实例规格较小时，主实例的max_connections可能受限于只读实例而无法设置为规格允许的最大值。此时可以通过启用soft_limit_connections参数来解决：
- 将只读实例的soft_limit_connections设置为非-1值，使只读实例的连接数由该参数控制。
- 然后调整只读实例的max_connections为主实例期望的值。
- 最后调整主实例的max_connections到目标值。
该参数修改不需要重启实例。如果不需要此功能，可将soft_limit_connections恢复为-1。
7.3 其他关键性能参数
除了上述腾讯云特有的参数外，标准的PostgreSQL性能参数同样适用于云数据库实例：
- shared_buffers：数据库共享缓冲区大小，通常建议设置为实例内存的15%-25%。
- work_mem：单个查询操作可用的内存大小，影响排序和哈希操作的性能。
- effective_cache_size：操作系统缓存大小的估算值，影响查询规划器的索引选择。
这些参数均可在控制台的参数设置页面进行调整。腾讯云还提供了参数模板功能，可以预先定义一套参数配置方案，然后批量应用到多个实例，简化参数管理。
8. 只读实例与读写分离
只读实例是腾讯云PostgreSQL提供的一种特殊实例类型，仅提供读功能，数据通过主从同步从主实例获取。只读实例无法单独存在，必须隶属于某个主实例，且只能与主实例同地域。默认允许一个主实例创建6个只读实例。
8.1 只读实例的访问方式
只读实例可以通过独立的IP和端口进行访问。也可以将多个只读实例组成只读实例RO组，通过RO组的统一访问地址进行负载均衡访问。目前暂不支持自动读写分离地址（即自动将读请求和写请求分离到不同实例），需要应用层根据业务需求自行判断读写操作的路由。
8.2 只读实例的最佳实践
在读写分离架构中，主实例负责处理写数据请求，只读实例承担读请求，从而分担主实例压力，提高整体读性能和系统吞吐量。建议将报表查询、数据分析、后台统计等读密集型任务路由到只读实例，而将交易写入等写操作保留在主实例执行。
9. 跨库访问与外部数据源
腾讯云PostgreSQL提供了跨库访问能力，支持对本实例中其他库的数据或其他实例的数据进行读取、写入和联合操作。跨库访问通过插件实现，主要分为两类：
- 同构跨库访问：dblink、postgresql_fdw，用于访问其他PostgreSQL数据库。
- 异构跨库访问：mysql_fdw、cos_fdw，用于访问MySQL数据库或腾讯云COS对象存储。
使用跨库访问的基本步骤：
- 使用CREATE EXTENSION语句安装插件。
- 为需要连接的远程数据库创建外部服务器对象并创建链接映射。
- 使用对应命令访问外部表以获取数据。
以大版本10及以上的实例为例，使用postgres_fdw进行跨实例访问时，需要配置以下辅助参数：host（目标实例IP）、port（端口）、instanceid（实例ID）、dbname（数据库名）、access_type（目标实例类型）、uin（账号ID）等。腾讯云在开源版本基础上增加了额外的辅助参数来验证用户身份和调整网络策略，增强了安全性。
10. 插件管理
云数据库PostgreSQL支持多款开源和自研插件，通过插件能够提升实例运维易用性、查询和写入性能、分词查询、数据检索、数据增量迁移等各方面的能力。PostgreSQL的插件是在database级别进行管理的，不同database之间可创建不同的插件，且无法互相使用。
10.1 插件的安装与使用
大部分常用插件已默认支持，可直接使用。安装插件的方式是在目标数据库中执行CREATE EXTENSION命令：
CREATE EXTENSION 插件名;部分插件需要在shared_preload_libraries参数中预先加载，这需要先在控制台的参数设置页面修改该参数，然后重启实例生效。还有一些插件需要特定版本或特殊权限支持，需要提交工单联系工作人员开启。
10.2 常用插件介绍
- postgis：空间数据库扩展，支持地理空间数据存储和查询。
- vector：向量数据库插件，支持向量检索，适用于AI应用场景。
- dblink / postgresql_fdw：跨库访问插件。
- hll：HyperLogLog算法扩展，用于基数估算。
11. 监控与告警
腾讯云PostgreSQL提供了完善的监控与告警能力，帮助开发者实时掌握数据库运行状态。
11.1 监控指标
控制台提供了丰富的监控视图，可查看CPU利用率、内存利用率、磁盘使用率、连接数、QPS、TPS、慢查询等关键指标。还提供了大量性能视图，可查看正在执行的SQL、当前锁等待、表扫描和索引扫描等方面的性能数据，帮助快速精准定位性能问题。
11.2 告警配置
通过腾讯云可观测平台可以配置告警策略：
- 登录腾讯云可观测平台控制台，在左侧导航选择告警管理 > 告警配置。
- 在告警策略列表页中单击新建策略。
- 设置策略名称、策略类型（选择云数据库PostgreSQL）、告警对象（选择具体实例）、触发条件（如CPU超过80%持续5分钟）等。
- 配置告警通知方式（短信、邮件、微信等）。
对于需要自定义监控的场景，还可以通过集成中心的云监控集成，部署PostgreSQL Exporter实现一键采集云产品指标。
12. 备份与恢复
腾讯云PostgreSQL默认提供自动备份功能，支持全量备份和增量备份（基于WAL日志）。
12.1 备份机制
系统会根据设置的备份周期自动进行数据备份。当实例从回收站下线时，系统会发起一次最终备份并产生最终备份集，该备份集将保留8天。
12.2 数据恢复方式
当出现数据丢失或损坏时，可以通过以下方式恢复数据：
- 按时间点恢复：通过克隆实例功能，将数据恢复到指定时间点。
- 按备份集恢复：从已有的全量备份集中恢复数据。
- 下载备份到自建数据库：将备份文件下载到本地或CVM，然后恢复到自建PostgreSQL中。
可恢复的时间范围取决于日志保留时间和全量备份的保留策略。
12.3 已删除实例的备份恢复
对于已删除（已销毁）的实例，可以在数据库备份页面的已销毁实例备份列表中找到对应的备份集，单击恢复即可将备份恢复到新实例。
13. 数据迁移（DTS）
腾讯云数据传输服务DTS支持将数据迁移到云数据库PostgreSQL，支持不停机迁移，能够最小化避免迁移过程对业务的影响。
13.1 迁移方式
除了使用传统的pg_dump和pg_restore进行数据导入导出外，DTS提供了更便捷的迁移方案：
- 同构迁移：支持PostgreSQL 10及之后的所有版本互相跨版本迁移，如PostgreSQL 10迁移至PostgreSQL 12。
- 异构迁移：支持TDSQL-C PostgreSQL版与云数据库PostgreSQL数据互相迁移。
13.2 迁移注意事项
DTS在执行全量数据迁移时会占用一定的源端实例资源，可能导致源实例负载上升。如果源数据库配置较低，建议在业务低峰期进行迁移。迁移前应仔细阅读逻辑迁移使用说明，了解功能约束和注意事项。
14. 审计日志
云数据库PostgreSQL具备数据库审计能力，记录对数据库的访问及SQL语句执行情况，帮助企业进行风险控制，提高数据安全等级。审计日志支持极速审计和精细审计两种模式。开通审计服务时，需要设置日志保存时长及高低频存储时长。开启后，可以在数据库审计页面查看和检索审计日志。审计日志还支持投递功能，可将日志投递到指定的存储服务中。
15. 成本优化建议
合理使用腾讯云PostgreSQL可以有效控制成本：
- 内网访问免流量：同VPC内的CVM访问数据库使用内网通道，不产生外网流量费用，建议所有业务访问均使用内网。
- 按需选择规格：根据业务实际的QPS、TPS和存储需求选择合适的实例规格，避免资源浪费。
- 合理配置只读实例：对于读多写少的场景，通过只读实例分担读压力，可以提升性能的同时避免主实例规格过度扩容。
- 监控与弹性伸缩：通过监控告警及时发现资源瓶颈，按需进行弹性扩容或缩容。
- 备份策略优化：根据数据重要性和恢复时间要求，合理设置备份周期和保留天数，避免不必要的存储费用。
16. 常见问题解答
问：忘记数据库管理员密码怎么办？
可以在PostgreSQL控制台的实例详情页，进入账号管理页，找到管理员账号后单击重置密码即可。
问：内网地址和外网地址有什么区别？
内网地址是数据库在VPC内部的私有IP，只能从同一VPC内访问，延迟低且安全。外网地址是公网可访问的地址，需要手动开启，存在安全风险，仅建议用于开发测试。
问：如何查看数据库当前正在执行的SQL？
可以通过控制台的性能监控页面查看正在执行的SQL语句，或连接数据库后执行pg_stat_activity系统视图查询。
问：只读实例的数据同步延迟有多大？
只读实例通过主从复制同步数据，延迟通常在毫秒级，具体取决于主实例的写入压力和网络状况。在控制台的监控页面可以查看复制延迟指标。
问：云数据库PostgreSQL支持哪些PostgreSQL版本？
腾讯云PostgreSQL支持PostgreSQL 10到17等多个大版本，具体支持的版本列表可在创建实例时查看下拉选项。
问：如何将自建PostgreSQL数据迁移到腾讯云？
可以使用DTS数据传输服务进行不停机迁移，也可以使用pg_dump导出数据后再用pg_restore导入。DTS支持跨版本迁移，更加便捷。
