华为云云数据库 GaussDB 对接使用完全指南

1. 华为云 GaussDB 概述

华为云云数据库 GaussDB 是华为自主研发的企业级分布式关系型数据库，主打高可用、高性能与高安全。GaussDB 支持集中式与分布式两种部署形态，集中式适用于中小型业务系统，分布式则面向海量数据高并发场景。它完全兼容 PostgreSQL 生态，这意味着大量基于 PostgreSQL 开发的应用程序可以低成本迁移到 GaussDB 之上。同时，GaussDB 提供包年包月和按需计费两种模式，开发者可以根据业务负载灵活选择。

在对接使用 GaussDB 之前，首先需要明确几个核心概念：实例（即数据库服务器）、数据库（逻辑上的数据集合）、用户与权限体系、以及 VPC 网络环境。GaussDB 默认提供 postgres 作为初始数据库，以及 template0 和 template1 两个模板数据库。开发者需要先完成实例购买、网络配置和账号创建，才能开始后续的对接工作。

需要先登录华为云控制台，点击：华为云控制台，还没有账号，点击：注册并关联，已有账号点击：登录后关联

2. 创建 GaussDB 实例

2.1 购买流程

登录华为云管理控制台后，在左上角区域选择合适的地理位置，然后依次点击“数据库” > “云数据库 GaussDB”进入实例管理页面。点击“购买数据库实例”按钮，进入购买配置页面。

在配置页面中，需要依次完成以下关键参数的设置：

• 计费模式：按需计费适合测试和短期项目，包年包月适合长期稳定生产环境。
• 区域与可用区：选择离业务用户最近的区域以降低网络延迟，多可用区部署可提高容灾能力。
• 数据库引擎版本：选择最新的稳定版本以获取最新特性和安全补丁。
• 部署形态：集中式版（一主两备或一主一备一日志）适合中小规模业务；分布式版（多分片）适合海量数据和高并发场景。
• 性能规格：通用型适合轻量负载，独享型和鲲鹏独享型适合高性能要求的生产环境。
• 存储空间：单分片起配 40GB，步长 4GB，需根据业务数据量合理规划。

完成配置后点击“立即购买”，等待实例创建完成（通常需要几分钟到十几分钟）。

2.2 初始化设置

实例创建成功后，系统会自动生成管理员账号（默认为 root）和密码。建议第一时间登录并修改密码，同时创建专用于应用程序的非管理员账号，遵循最小权限原则。此外，建议在实例详情页绑定标签（如项目名称、环境类型等），方便后续的资源分类和成本核算。

3. GaussDB 连接方式详解

GaussDB 提供多种连接方式，开发者可根据使用场景灵活选择。

3.1 DAS 数据管理服务（推荐新手）

数据管理服务（Data Admin Service，简称 DAS）是华为云提供的可视化数据库管理工具，无需安装任何客户端，直接在浏览器中即可完成 SQL 执行、表结构管理、用户权限配置等操作。GaussDB 默认开通 DAS 连接权限。

使用步骤如下：在控制台左侧导航栏选择“数据库 > 数据管理服务 DAS”，进入 DAS 页面后点击“开发工具”，选择对应的 GaussDB 实例即可直接登录。DAS 还提供慢 SQL 分析、性能监控等高级功能，非常适合开发测试阶段的快速调试。

3.2 gsql 命令行工具

gsql 是 GaussDB 自带的命令行交互工具，支持通过 -d（数据库名）、-U（用户名）、-h（主机 IP）、-p（端口号）等参数连接数据库。适合自动化脚本、批量任务和运维管理场景。

基本连接命令示例：

gsql -d postgres -U root -h 192.168.1.100 -p 8000

如果 GaussDB 实例与 ECS 在同一 VPC 内，可以直接使用内网 IP 连接。对于分布式实例，可以将多个 DN 的 IP 用逗号分隔传给 -h 参数，gsql 会自动寻找主 DN 进行连接。

gsql -h 10.180.123.163,10.180.123.164,10.180.123.165 -d postgres -U jack -p 8000

连接成功后，可以执行 SQL 语句，也可以使用 \l 列出所有数据库、\dt 列出所有表等元命令。

3.3 内网连接

当应用程序部署在华为云 ECS 上，且 ECS 与 GaussDB 实例处于同一 VPC 时，推荐使用内网 IP 连接。内网连接具有延迟低、速度快、安全性高的优点，且不产生额外的公网流量费用。需要注意的是，即使在同一 VPC 内，如果 ECS 和 GaussDB 分属不同安全组，也需要配置安全组规则放通对应的端口。

3.4 公网连接

当无法通过内网访问时（如本地开发环境或第三方服务），可以为 GaussDB 实例绑定弹性公网 IP（EIP），然后通过公网地址连接。公网连接需要额外注意安全防护，建议仅对必要的 IP 地址开放访问，并强制使用 SSL 加密传输。

4. 安全组与访问控制

安全组是 GaussDB 网络安全的第一道防线，通过白名单机制控制哪些 IP 地址和端口可以访问实例。默认情况下，安全组拒绝所有外部请求，需要手动添加入方向规则。

配置步骤如下：进入 GaussDB 实例详情页，在“网络信息”模块点击安全组名称，跳转到安全组配置页面。添加入方向规则时，需要指定协议（TCP）、端口（GaussDB 默认 8000）和源 IP 地址（允许访问的 IP 或 CIDR 段）。生产环境建议将源 IP 限制为应用服务器的内网 IP 段，避免将 0.0.0.0/0 开放给公网。

此外，GaussDB 支持 SSL 加密连接，可以在连接字符串中配置 sslmode=require 来强制启用。使用 SSL 时，需要将服务器根证书（ca.pem）导入客户端的受信任根证书存储区。

5. Python 连接 GaussDB（Psycopg2）

Psycopg2 是 Python 生态中最流行的 PostgreSQL 适配器，由于 GaussDB 兼容 PostgreSQL 协议，因此可以直接使用 Psycopg2 连接 GaussDB。Psycopg2 采用 C 语言实现，性能高效且支持客户端游标、服务端游标、COPY 指令等高级特性。

5.1 安装驱动

pip install psycopg2-binary

5.2 连接示例

import psycopg2
import os

conn = psycopg2.connect(
    host=os.getenv('GAUSSDB_HOST', '192.168.1.100'),
    port=os.getenv('GAUSSDB_PORT', '8000'),
    database=os.getenv('GAUSSDB_DB', 'postgres'),
    user=os.getenv('GAUSSDB_USER', 'root'),
    password=os.getenv('GAUSSDB_PASSWORD', 'your_password'),
    sslmode=os.getenv('GAUSSDB_SSLMODE', 'disable')
)

cur = conn.cursor()
cur.execute('SELECT version()')
version = cur.fetchone()
print(f'GaussDB 版本: {version[0]}')

cur.execute('''
    CREATE TABLE IF NOT EXISTS users (
        id SERIAL PRIMARY KEY,
        name VARCHAR(100) NOT NULL,
        email VARCHAR(200) UNIQUE,
        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
    )
''')
conn.commit()

cur.execute(
    'INSERT INTO users (name, email) VALUES (%s, %s) RETURNING id',
    ('张三', 'zhangsan@example.com')
)
user_id = cur.fetchone()[0]
conn.commit()
print(f'插入成功，用户 ID: {user_id}')

cur.execute('SELECT id, name, email, created_at FROM users')
rows = cur.fetchall()
for row in rows:
    print(f'ID: {row[0]}, 姓名: {row[1]}, 邮箱: {row[2]}, 创建时间: {row[3]}')

cur.close()
conn.close()

需要注意的是，如果环境变量 LD_LIBRARY_PATH 与 GaussDB 依赖的 OpenSSL 版本冲突，可能需要显式指定库路径。

6. Java 连接 GaussDB（JDBC）

GaussDB 提供了专有的 JDBC 驱动包，主类为 com.huawei.gaussdb.jdbc.Driver，URL 前缀为 jdbc:gaussdb。驱动包分为 gaussdbjdbc.jar（标准版）和 gscejdbc.jar（密态数据库增强版）。

6.1 添加依赖

在 Maven 项目中，需要手动将 gaussdbjdbc.jar 添加到 classpath，或通过私有仓库引入。

6.2 JDBC 连接示例

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.Statement;
import java.sql.ResultSet;
import java.sql.PreparedStatement;
import java.sql.SQLException;

public class GaussDBExample {
    public static void main(String[] args) {
        String username = System.getenv("GAUSSDB_USER");
        String password = System.getenv("GAUSSDB_PASSWORD");
        String url = "jdbc:gaussdb://192.168.1.100:8000/postgres";

        Connection conn = null;
        Statement stmt = null;
        ResultSet rs = null;

        try {
            Class.forName("com.huawei.gaussdb.jdbc.Driver");
            conn = DriverManager.getConnection(url, username, password);
            System.out.println("GaussDB 连接成功！");

            stmt = conn.createStatement();
            stmt.execute(
                "CREATE TABLE IF NOT EXISTS products (" +
                "id SERIAL PRIMARY KEY, " +
                "name VARCHAR(100) NOT NULL, " +
                "price DECIMAL(10,2), " +
                "stock INT DEFAULT 0" +
                ")"
            );
            System.out.println("建表完成");

            String insertSQL = "INSERT INTO products (name, price, stock) VALUES (?, ?, ?)";
            PreparedStatement pstmt = conn.prepareStatement(insertSQL);
            pstmt.setString(1, "华为 MateBook");
            pstmt.setBigDecimal(2, new java.math.BigDecimal("6999.00"));
            pstmt.setInt(3, 100);
            int affected = pstmt.executeUpdate();
            System.out.println("插入 " + affected + " 条记录");
            pstmt.close();

            conn.setAutoCommit(false);
            PreparedStatement batchPstmt = conn.prepareStatement(
                "INSERT INTO products (name, price, stock) VALUES (?, ?, ?)"
            );
            for (int i = 1; i <= 10; i++) {
                batchPstmt.setString(1, "商品" + i);
                batchPstmt.setBigDecimal(2, new java.math.BigDecimal(100 + i * 10));
                batchPstmt.setInt(3, i * 5);
                batchPstmt.addBatch();
            }
            int[] batchResults = batchPstmt.executeBatch();
            conn.commit();
            System.out.println("批量插入 " + batchResults.length + " 条记录");
            batchPstmt.close();

            rs = stmt.executeQuery("SELECT id, name, price, stock FROM products");
            while (rs.next()) {
                System.out.printf(
                    "ID: %d, 名称: %s, 价格: %.2f, 库存: %d%n",
                    rs.getInt("id"),
                    rs.getString("name"),
                    rs.getDouble("price"),
                    rs.getInt("stock")
                );
            }

        } catch (ClassNotFoundException e) {
            System.err.println("未找到 GaussDB JDBC 驱动");
            e.printStackTrace();
        } catch (SQLException e) {
            System.err.println("数据库操作异常");
            e.printStackTrace();
        } finally {
            try { if (rs != null) rs.close(); } catch (SQLException e) {}
            try { if (stmt != null) stmt.close(); } catch (SQLException e) {}
            try { if (conn != null) conn.close(); } catch (SQLException e) {}
        }
    }
}

6.3 批量查询优化

对于大结果集查询，可以使用 setFetchSize() 方法控制每次从服务端获取的行数，避免 OOM。注意使用游标时需先关闭自动提交。

stmt.setFetchSize(50);
ResultSet rs = stmt.executeQuery("SELECT * FROM large_table");
while (rs.next()) {
    // 处理每一行
}
conn.commit();

7. Go 语言连接 GaussDB

Go 语言可以通过 gaussdb-go 驱动连接 GaussDB，该驱动是专为 GaussDB 设计的高性能原生驱动，支持 COPY 等高级特性。同时也提供 database/sql 标准接口的兼容层。

7.1 安装驱动

go get github.com/jackc/pgx/v5

由于 GaussDB 兼容 PostgreSQL 协议，可以使用 pgx 驱动连接。

7.2 Go 连接示例

package main

import (
    "context"
    "database/sql"
    "fmt"
    "log"
    "os"

    _ "github.com/jackc/pgx/v5/stdlib"
)

func main() {
    host := os.Getenv("GAUSSDB_HOST")
    port := os.Getenv("GAUSSDB_PORT")
    user := os.Getenv("GAUSSDB_USER")
    password := os.Getenv("GAUSSDB_PASSWORD")
    dbname := os.Getenv("GAUSSDB_DB")

    dsn := fmt.Sprintf(
        "host=%s port=%s user=%s password=%s dbname=%s sslmode=disable",
        host, port, user, password, dbname,
    )

    db, err := sql.Open("pgx", dsn)
    if err != nil {
        log.Fatalf("连接失败: %v", err)
    }
    defer db.Close()

    ctx := context.Background()
    if err := db.PingContext(ctx); err != nil {
        log.Fatalf("Ping 失败: %v", err)
    }
    fmt.Println("GaussDB 连接成功！")

    _, err = db.ExecContext(ctx, `
        CREATE TABLE IF NOT EXISTS orders (
            id SERIAL PRIMARY KEY,
            order_no VARCHAR(50) UNIQUE NOT NULL,
            amount DECIMAL(12,2),
            status SMALLINT DEFAULT 0,
            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
        )
    `)
    if err != nil {
        log.Fatalf("建表失败: %v", err)
    }
    fmt.Println("建表完成")

    _, err = db.ExecContext(ctx,
        "INSERT INTO orders (order_no, amount, status) VALUES ($1, $2, $3)",
        "ORD-2026-001", 1299.50, 1,
    )
    if err != nil {
        log.Fatalf("插入失败: %v", err)
    }
    fmt.Println("数据插入成功")

    rows, err := db.QueryContext(ctx,
        "SELECT id, order_no, amount, status, created_at FROM orders",
    )
    if err != nil {
        log.Fatalf("查询失败: %v", err)
    }
    defer rows.Close()

    for rows.Next() {
        var id int
        var orderNo string
        var amount float64
        var status int
        var createdAt string
        if err := rows.Scan(&id, &orderNo, &amount, &status, &createdAt); err != nil {
            log.Fatal(err)
        }
        fmt.Printf("ID: %d, 单号: %s, 金额: %.2f, 状态: %d, 时间: %s\n",
            id, orderNo, amount, status, createdAt)
    }
}

对于分布式 GaussDB 实例，连接串中可以使用逗号分隔多个 IP 地址，驱动会自动进行负载均衡和故障切换。

8. 数据迁移（DRS 服务）

华为云数据复制服务（Data Replication Service，简称 DRS）提供了数据库在线迁移和实时同步能力，支持将 MySQL、Oracle、PostgreSQL 等数据源迁移到 GaussDB。DRS 采用全量+增量同步模式，能够在不中断业务的情况下完成数据迁移。

8.1 迁移流程

• 创建 DRS 任务：在 DRS 控制台选择“实时同步”或“实时迁移”，配置源端和目标端数据库信息。
• 预检查：DRS 会自动检查源端和目标端的连通性、账号权限、版本兼容性等。
• 全量迁移：将源端的表结构、历史数据一次性复制到目标端。
• 增量同步：通过解析源端数据库的日志（如 MySQL 的 binlog），持续将增量变更同步到目标端。
• 数据比对：迁移完成后，DRS 支持对源端和目标端的数据进行一致性比对。
• 业务割接：确认数据一致后，将业务流量切换到 GaussDB。

8.2 权限要求

使用 DRS 迁移 MySQL 到 GaussDB 时，源端 MySQL 账号需要具备 SELECT、LOCK TABLES、REPLICATION SLAVE、REPLICATION CLIENT 等权限。

9. 性能优化与参数调优

9.1 关键数据库参数

GaussDB 的性能受多个数据库参数影响，合理配置可以显著提升吞吐量：

• shared_buffers：数据库共享缓冲区大小，建议设置为物理内存的 25%~40%。
• work_mem：单个查询操作（如排序、哈希连接）可用的内存，需根据并发数合理分配。
• kernel.shmmax：操作系统共享内存段最大尺寸，增大该值可提升 GaussDB 性能。
• log_min_duration_statement：记录执行时间超过设定值的 SQL，便于慢查询分析。

9.2 表设计规范

GaussDB 的表设计直接影响查询性能：

• 分布方式选择：分布式实例中，合理选择哈希分布、复制分布或范围分布，避免数据倾斜。
• 分布键设计：应选择查询频率高、取值分布均匀的列作为分布键。
• 索引策略：为高频查询条件创建索引，但避免过多索引影响写入性能。
• 分区表：对于大表，按时间或范围分区可以提高查询和维护效率。

9.3 连接池配置

应用程序应使用连接池管理数据库连接，避免频繁创建和销毁连接。常见的连接池框架包括 HikariCP（Java）、SQLAlchemy 连接池（Python）等。建议将最大连接数设置为 GaussDB 实例规格支持的连接数上限的 80%，预留缓冲。

10. 运维与监控

10.1 慢查询分析

通过 DAS 的慢 SQL 分析功能，可以快速定位执行时间较长的 SQL 语句。结合 EXPLAIN 命令分析执行计划，优化索引或改写 SQL。

10.2 实例监控

华为云控制台提供 CPU 使用率、内存使用率、磁盘 IOPS、连接数等监控指标。建议设置告警阈值，当指标异常时及时收到通知。

10.3 备份与恢复

GaussDB 自动提供每日备份，保留天数可配置。赠送与存储空间等量的免费备份空间，超出部分按需计费。开发者也可以手动触发全量备份或恢复到指定时间点。

11. 常见问题与解答

问：连接 GaussDB 时报“拒绝连接”错误怎么办？
答：首先检查 GaussDB 实例是否处于运行状态，其次确认安全组规则是否放通了客户端 IP 和端口（默认 8000）。如果使用公网连接，确认是否已绑定弹性公网 IP。

问：psycopg2 连接时报“SSL 错误”如何解决？
答：可以在连接参数中设置 sslmode=disable 临时禁用 SSL，或下载 GaussDB 的根证书（ca.pem）并配置 sslrootcert 参数。

问：Java JDBC 驱动从哪里获取？
答：可以从华为云官网的 GaussDB 开发指南中下载 gaussdbjdbc.jar，或通过 Maven 仓库引入。驱动主类为 com.huawei.gaussdb.jdbc.Driver。

问：GaussDB 分布式实例和集中式实例在连接方式上有什么区别？
答：连接方式基本相同，但分布式实例的 gsql 连接串中可以传入多个 DN 的 IP 地址，驱动会自动寻找主 DN。JDBC 和 Go 驱动也支持多 IP 配置实现负载均衡。

问：如何将自建 MySQL 迁移到 GaussDB？
答：推荐使用华为云 DRS 服务，配置源端 MySQL 和目标端 GaussDB 的连接信息后，DRS 会自动完成全量+增量迁移，支持业务不停机割接。

问：GaussDB 支持哪些编程语言的驱动？
答：GaussDB 兼容 PostgreSQL 生态，因此支持 Python（psycopg2）、Java（JDBC）、Go（pgx/gaussdb-go）、ODBC、C（libpq）等多种语言驱动。