活动专区

活动公告

上车！GBase 8a开发者联盟发车了 技术福利、人脉资源全都有！

认证培训专区

认证培训资料

GBase 8s GDCA 认证培训课前准备

GBase 8a

其他

物化视图报错：references invalid table(s) or column(s) or function(s) or definer/invoker of view lack rights to use them

01-GBase 8s 事务型数据库 安装与卸载

GBase 8s

适配迁移

[GBase 8s 教程]GBase 8s 常用函数、表达式


> 字符集乱码是 GBase 8a 使用中最高频的坑，从导入乱码、查询乱码到跨系统乱码，根因各不相同。本文系统梳理 GBase 8a 的字符集体系、转换流程、各场景配置规范，并给出乱码的诊断和修复方法。

---

## 一、GBase 8a 支持的字符集

| 字符集        | 说明                       | 最大字节/字符 | 适用场景                |
| --------------- | ---------------------------- | --------------- | ------------------------- |
| `utf8`    | 标准 UTF-8（1-3 字节）     | 3             | 通用，**默认值**  |
| `utf8mb4` | 完整 UTF-8（1-4 字节）     | 4             | 需要存储 Emoji 或生僻字 |
| `gbk`     | 国标扩展汉字编码（双字节） | 2             | 存量系统，数据源为 GBK  |
| `gb18030` | 国家标准，GBK 超集         | 4             | 需覆盖生僻字的政务场景  |

**几个重要限制：**

* GBase 8a 的 `utf8` 最多处理 3 字节字符（与 MySQL 的 `utf8mb3` 一致），不支持 4 字节的 Emoji，需要 `utf8mb4`
* `gb18030` 每字符预留 4 字节空间，内存压力是 `gbk` 的两倍，在内存紧张时对性能影响较大
* ​**字符集一经安装确定，不支持 `ALTER TABLE` 直接修改表字符集**​，变更字符集需重建表并重新导入数据
* ​**校验规则（Collation）**​：GBase 8a 当前所有字符集的校验规则均为区分大小写，与 MySQL 默认的 `utf8_general_ci`（不区分大小写）不同，迁移时需注意

---

## 二、字符集转换链路

理解乱码的关键是搞清楚 SQL 从客户端到数据库存储的完整转换链路：

```
客户端发 SQL
    │
    ▼ character_set_client（客户端声明自己用什么字符集）
gcluster 接收
    │
    ▼ character_set_connection（gcluster 内部转换目标字符集）
查询执行 / 数据存储（使用表/库的字符集）
    │
    ▼ character_set_results（返回给客户端的字符集）
客户端接收并显示
```

​**乱码只会在字符集不一致的转换点产生**​。只要链路上每一层的字符集声明与实际编码一致，就不会乱码。

---

## 三、字符集相关参数一览

```sql
-- 查看当前所有字符集参数
SHOW VARIABLES LIKE '%character%';
```

| 参数                           | 作用                          | 可修改范围              |
| -------------------------------- | ------------------------------- | ------------------------- |
| `character_set_server`     | 实例字符集（安装时确定）      | 配置文件，重启生效      |
| `character_set_database`   | 当前库的字符集                | 只读，反映当前 USE 的库 |
| `character_set_client`     | 客户端发送 SQL 的字符集       | SET 或配置文件          |
| `character_set_connection` | 服务端接收后的中间转换字符集  | SET 或配置文件          |
| `character_set_results`    | 查询结果返回给客户端的字符集  | SET 或配置文件          |
| `character_set_system`     | 系统元数据字符集（固定 utf8） | 不可修改                |
| `character_set_sort`       | 排序时使用的字符集            | SET 或配置文件          |

**最简原则：让 `client = connection = results = 表字符集`，不产生任何转换。**

---

## 四、字符集配置规范

### 4.1 安装时确定字符集（最重要）

GBase 8a 的实例字符集在安装时确定，通过配置文件中的 `default_character_set` 指定。​**安装后修改代价很高**​（所有已有库表不受影响，只对新建对象生效）。

```ini
# gcluster 和 gnode 所有节点的 gbase.cnf（安装前配置）
[client]
default-character-set = utf8    # 或 gbk

[gbased]
default_character_set = utf8    # 或 gbk
```

> 如果数据源（业务系统、历史数据文件）是 GBK 编码，建议安装时就指定 `gbk`；如果是全新系统，优先选 `utf8`。

### 4.2 建库建表时指定字符集

即使实例字符集是 utf8，也可以在建库或建表时指定不同字符集：

```sql
-- 建库时指定
CREATE DATABASE legacy_db DEFAULT CHARACTER SET gbk;

-- 建表时指定（如不指定，继承库的字符集）
CREATE TABLE t_product (
    product_id   INT,
    product_name VARCHAR(100)
) ENGINE=EXPRESS DEFAULT CHARSET=gbk DISTRIBUTED BY HASH(product_id);
```

### 4.3 会话级字符集设置

当客户端字符集与服务端不一致时，可以在会话开始时临时对齐：

```sql
-- 一次性设置 client / connection / results 三个参数
SET NAMES gbk;
-- 等价于：
SET character_set_client = gbk;
SET character_set_connection = gbk;
SET character_set_results = gbk;
```

### 4.4 配置文件中的全局默认

如果所有连接都来自 GBK 客户端，可以在配置文件中写死：

```ini
# gcluster 的 gbase.cnf
[client]
default-character-set = gbk

[gbased]
character_set_client     = gbk
character_set_connection = gbk
character_set_results    = gbk
```

---

## 五、乱码场景诊断与修复

### 场景 1：gccli / 命令行工具查询乱码

​**现象**​：在终端查询中文，显示问号或方块。

**诊断步骤：**

```sql
-- 1. 查看当前会话字符集
SHOW VARIABLES LIKE '%character%';

-- 2. 查看操作系统终端字符集
-- 在 Linux Shell 执行：
echo $LANG
-- 期望：zh_CN.UTF-8

-- 3. 确认表的实际字符集
SHOW CREATE TABLE your_table;
```

**修复：**

```sql
-- 如果终端是 UTF-8，数据库是 GBK：
SET NAMES utf8;   -- 告诉数据库"请把结果以 UTF-8 返回给我"

-- 如果终端是 GBK（Windows cmd），数据库是 UTF-8：
SET NAMES gbk;
```

### 场景 2：LOAD DATA 导入后乱码

​**现象**​：数据文件是 GBK 编码，但导入后查询中文乱码。

**诊断：**

```bash
# 确认数据文件的实际编码
file -i /data/import/data.csv
# 或：
head -1 /data/import/data.csv | hexdump -C | head
```

**gload 配置文件中指定字符集：**

```ini
# load.cfg
character_set = gbk    # 告诉 gload 文件是 GBK 编码
```

**LOAD DATA 语句中指定：**

```sql
LOAD DATA INFILE '/data/import/data.csv'
INTO TABLE t_product
CHARACTER SET gbk       -- 指定文件编码
FIELDS TERMINATED BY ','
LINES TERMINATED BY '\n';
```

> ⚠️ ​**GBase 8a 的 LOAD DATA 不支持在加载时自动转换字符集**​。如果文件是 GBK，目标表是 UTF-8，需要先在 OS 层将文件转换为 UTF-8，再导入：
> 
> ```bash
> iconv -f GBK -t UTF-8 data_gbk.csv > data_utf8.csv
> ```

### 场景 3：JDBC 应用写入乱码

​**现象**​：Java 应用写入的中文，在 gccli 中查询是乱码。

**诊断：**

```java
// 检查 JDBC URL 中是否指定了 characterEncoding
// 错误：没有指定，JDBC 会用 JVM 默认编码（可能是 GBK/ISO-8859-1）
String url = "jdbc:gbase://host:5258/db";

// 正确：明确指定编码
String url = "jdbc:gbase://host:5258/db?characterEncoding=utf8&useUnicode=true";
```

同时确保数据库服务端的 `character_set_client` 与 JDBC 指定的编码一致：

```sql
-- 会话连接建立后，服务端收到的 character_set_client 应该与 JDBC 的 characterEncoding 一致
SHOW VARIABLES LIKE 'character_set_client';
```

### 场景 4：SELECT INTO OUTFILE 导出文件乱码

​**现象**​：导出的 CSV 文件在 Excel/Windows 下打开乱码。

​**根因​**​：GBase 8a 导出的文件编码与打开工具预期编码不一致。

```sql
-- 导出时指定字符集（让结果以 GBK 返回，适合 Windows Excel）
SET character_set_results = gbk;
SELECT ...
INTO OUTFILE '/data/export/result.csv'
CHARACTER SET gbk
FIELDS TERMINATED BY ','
LINES TERMINATED BY '\r\n';  -- Windows 换行符
```

或者在 OS 层转换导出文件的编码：

```bash
iconv -f UTF-8 -t GBK result_utf8.csv > result_gbk.csv
```

### 场景 5：表字符集已确定为 GBK，但个别列需要存储特殊字符

GBase 8a 支持在建表时**列级别**指定字符集（部分版本支持）：

```sql
CREATE TABLE t_mixed (
    id          INT,
    name_cn     VARCHAR(100) CHARACTER SET gbk,
    name_intl   VARCHAR(100) CHARACTER SET utf8mb4  -- 支持 emoji
) DISTRIBUTED BY HASH(id);
```

---

## 六、字符集变更方案

​**GBase 8a 不支持直接 ALTER TABLE 修改字符集**​，正确的变更流程如下：

```sql
-- 步骤 1：导出原表数据（以目标字符集导出）
SET character_set_results = utf8;  -- 目标字符集
SELECT * INTO OUTFILE '/tmp/t_product_utf8.csv'
FIELDS TERMINATED BY ','
LINES TERMINATED BY '\n'
FROM t_product_gbk;

-- 步骤 2：创建新表（使用目标字符集）
CREATE TABLE t_product_new (
    product_id   INT,
    product_name VARCHAR(100)
) ENGINE=EXPRESS DEFAULT CHARSET=utf8
DISTRIBUTED BY HASH(product_id);

-- 步骤 3：导入数据
LOAD DATA INFILE '/tmp/t_product_utf8.csv'
INTO TABLE t_product_new
CHARACTER SET utf8
FIELDS TERMINATED BY ','
LINES TERMINATED BY '\n';

-- 步骤 4：验证数据完整性后重命名
-- 原表改名保留备份
ALTER TABLE t_product_gbk RENAME TO t_product_gbk_bak;
ALTER TABLE t_product_new RENAME TO t_product_gbk;
```

---

## 七、排序与字符集

GBase 8a 默认按字符的二进制值排序（`character_set_sort = binary`）。对于中文数据，二进制排序不等于拼音顺序。如果需要拼音排序：

```sql
-- 会话级设置（对当前连接后续查询生效）
SET character_set_sort = gbk;   -- 按 GBK 内码（拼音）排序

-- 或在配置文件中全局设置
-- [gbased]
-- character_set_sort = gbk
```

```sql
-- 验证效果
SELECT name FROM t_person ORDER BY name;
-- binary 排序：按字节值，可能是：东、中、人、大（不是拼音顺序）
-- gbk 排序：按拼音，应为：大、东、人、中
```

---

## 八、字符集问题速查手册

| 现象                  | 第一检查点                          | 常见根因                       | 修复方向                         |
| ----------------------- | ------------------------------------- | -------------------------------- | ---------------------------------- |
| 查询结果全是 `???` | `character_set_results`         | 客户端不支持该编码             | `SET NAMES 客户端编码`       |
| 查询结果有乱码方块    | 表字符集 vs 实际数据编码            | 写入时编码不匹配               | 重新导入，统一编码               |
| LOAD DATA 后乱码      | cfg 文件的 `character_set`       | 文件编码与声明不符             | 先用 iconv 转换文件              |
| JDBC 写入乱码         | JDBC URL 的 `characterEncoding`  | 未指定或与表字符集不符         | 补充 `characterEncoding=utf8` |
| Excel 打开 CSV 乱码   | 导出时的 `character_set_results` | UTF-8 文件被 Excel 当 GBK 打开 | 导出为 GBK 或加 BOM              |
| 中文排序不是拼音顺序  | `character_set_sort`            | 默认 binary 排序               | `SET character_set_sort=gbk` |
| 插入表情符号报错      | 表的字符集                          | utf8 不支持 4 字节字符         | 改用 utf8mb4                     |



安装配置

GBase 8a 字符集完全指南：乱码根因分析、配置规范与修复方案

GBase 8a 字符集完全指南：乱码根因分析、配置规范与修复方案

评论

热门帖子