---
title: "OBClient 使用技巧和问题排查 - 命令行客户端 V2.2.13 | OceanBase 文档中心"
description: "OBClient 使用技巧和问题排查 本文档介绍 OBClient 的使用技巧、常见问题和平台特定说明。 使用技巧 垂直显示查询结果 某些查询结果在垂直显示时比通常的水平表格格式更具可读性。通过以 \\G 而不是分号（ ; ）终止查询，可以垂直显示查询。例如，包含换行符的较长文本值通常更容易用垂直输出阅读： obcli…"
image: https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*OSPzQ6GUQF4AAAAAQHAAAAgAeiGDAQ/original
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*1DGSQqsgFKcAAAAARrAAAAgAeiGDAQ/original) 命令行客户端V 2.2.13

# OBClient 使用技巧和问题排查

更新时间：2026-06-30 18:11:26

[编辑](https://github.com/oceanbase/obclient/edit/V2.2.13/zh-CN/700.tips-and-troubleshooting/700.tips-and-troubleshooting.md)  

本文档介绍 OBClient 的使用技巧、常见问题和平台特定说明。

## 使用技巧

### 垂直显示查询结果

某些查询结果在垂直显示时比通常的水平表格格式更具可读性。通过以 `\G` 而不是分号（`;`）终止查询，可以垂直显示查询。例如，包含换行符的较长文本值通常更容易用垂直输出阅读：

```sql
obclient> SELECT * FROM mails WHERE LENGTH(txt) < 300 LIMIT 300,1\G
*************************** 1. row ***************************
  msg_nro: 3068
    date: 2000-03-01 23:29:50
time_zone: +0200
mail_from: Monty
    reply: monty@no.spam.com
  mail_to: "Thimble Smith" <tim@no.spam.com>
      sbj: UTF-8
      txt: >>>>> "Thimble" == Thimble Smith writes:

Thimble> Hi.  I think this is a good idea.  Is anyone familiar
Thimble> with UTF-8 or Unicode? Otherwise, I´ll put this on my
Thimble> TODO list and see what happens.

Yes, please do that.

Regards,
Monty

    file: inbox-jani-1
    hash: 190402944
1 row in set (0.09 sec)

```

### 使用 --safe-updates 选项

对于初学者，一个有用的启动选项是 `--safe-updates`（或 `--i-am-a-dummy`，具有相同的效果）。当您可能发出了 `DELETE FROM tbl_name` 语句但忘记了 `WHERE` 子句时，这很有帮助。通常，这样的语句会从表中删除所有行。使用 `--safe-updates`，您只能通过指定标识它们的键值来删除行。这有助于防止事故。

当您使用 `--safe-updates` 选项时，OBClient 在连接到 OceanBase 服务器时发出以下语句：

```sql
SET sql_safe_updates=1, sql_select_limit=1000, sql_max_join_size=1000000;

```

`SET` 语句具有以下效果：

- 除非您在 `WHERE` 子句中指定键约束或提供 `LIMIT` 子句（或两者），否则不允许执行 `UPDATE` 或 `DELETE` 语句。例如：

```sql
UPDATE tbl_name SET not_key_column=val WHERE key_column=val;
UPDATE tbl_name SET not_key_column=val LIMIT 1;

```

- 服务器将所有大型 `SELECT` 结果限制为 1,000 行，除非语句包含 `LIMIT` 子句。
 - 服务器中止可能需要检查超过 1,000,000 行组合的多表 `SELECT` 语句。

要指定不同于 1,000 和 1,000,000 的限制，您可以使用 `--select_limit` 和 `--max_join_size` 选项覆盖默认值：

```sql
obclient --safe-updates --select_limit=500 --max_join_size=10000

```

### 禁用 OBClient 自动重连

如果 OBClient 客户端在发送语句时失去与服务器的连接，它会立即自动尝试重新连接到服务器并再次发送语句。但是，即使 OBClient 成功重新连接，您的第一个连接也已结束，并且您之前的所有会话对象和设置都丢失了：临时表、自动提交模式和用户定义和会话变量。此外，任何当前事务都会回滚。这可能对您很危险，如下例所示，服务器在第一个和第二个语句之间关闭并重新启动，而您不知道：

```sql
obclient> SET @a=1;
Query OK, 0 rows affected (0.05 sec)

obclient> INSERT INTO t VALUES(@a);
ERROR 2006: MySQL server has gone away
No connection. Trying to reconnect...
Connection id:    1
Current database: test
Query OK, 1 row affected (1.30 sec)

obclient> SELECT * FROM t;
+------+
| a    |
+------+
| NULL |
+------+

```

`@a` 用户变量已随连接丢失，重新连接后未定义。如果连接丢失时让 OBClient 终止并报错很重要，您可以使用 `--skip-reconnect` 选项启动 OBClient 客户端。

### 使用分隔符创建存储程序

从命令行创建存储程序时，您可能需要区分常规分隔符和 `BEGIN END` 块内的分隔符。考虑以下示例：

```sql
CREATE FUNCTION FortyTwo() RETURNS TINYINT DETERMINISTIC
BEGIN
 DECLARE x TINYINT;
 SET x = 42;
 RETURN x;
END;

```

如果您逐行输入上述内容，OBClient 会将第一个分号（在 `DECLARE x TINYINT` 行的末尾）视为语句的结束。由于这只是一个部分定义，它将抛出语法错误。

解决方案是在过程持续时间内指定一个不同的分隔符，使用 `DELIMITER`。分隔符可以是您选择的任何字符集，但它需要是一个不会造成进一步混淆的独特字符集。`//` 是一个常见的选择：

```sql
DELIMITER //

CREATE FUNCTION FortyTwo() RETURNS TINYINT DETERMINISTIC
BEGIN
  DECLARE x TINYINT;
  SET x = 42;
  RETURN x;
END
//

DELIMITER ;

```

最后，分隔符恢复为默认分号。`\g` 和 `\G` 分隔符始终可以使用，即使指定了自定义分隔符。

## Mac 系统支持

OBClient 支持在 macOS 系统上运行。以下介绍 Mac 系统使用时的注意事项。

### 权限问题

在 Mac 系统上首次运行时，可能会遇到权限提示。需要在"系统设置" > "隐私与安全性"中允许使用。

## 常见问题

### 连接问题

#### 问题：无法连接到服务器

**可能原因：**

- 主机地址或端口号错误
 - 网络连接问题
 - 防火墙阻止连接
 - 服务器未启动

**解决方法：**

1. 检查主机地址和端口号是否正确
 2. 使用 `ping` 命令测试网络连通性
 3. 检查防火墙设置
 4. 确认服务器状态

#### 问题：localhost 和 127.0.0.1 连接行为不同

在 Unix 系统上，`localhost` 和 `127.0.0.1` 的连接行为不同：

- 使用 `localhost` 时，OBClient 会尝试使用 Unix 套接字连接
 - 使用 `127.0.0.1` 时，OBClient 会使用 TCP/IP 连接

如果您的服务器只监听 TCP/IP 端口，请使用 `127.0.0.1` 或实际的 IP 地址。

### 字符集问题

#### 问题：输出格式不正确

当操作系统使用 utf8 或其他多字节字符集时，可能会出现 OBClient 的输出格式不正确的问题，这是因为 OBClient 客户端默认使用 latin1 字符集。

**解决方法：**

使用 `--default-character-set` 选项强制客户端使用系统字符集：

```bash
obclient --default-character-set=utf8

```

或者设置为 `auto`，从客户端环境获取字符集：

```bash
obclient --default-character-set=auto

```

### 历史文件问题

#### 问题：历史文件包含敏感信息

`.mysql_history` 文件可能包含敏感信息（例如包含密码的 SQL 语句）。

**解决方法：**

1. 使用限制性访问模式保护该文件：

```bash
chmod 600 ~/.mysql_history

```

2. 如果不想维护历史文件，可以将 `MYSQL_HISTFILE` 环境变量设置为 `/dev/null`：

```bash
export MYSQL_HISTFILE=/dev/null

```

### TNS 配置问题

#### 问题：tnsnames.ora 文件无效

在使用多IP连接时，如果 TNS 配置文件格式不正确，会出现"tnsnames.ora文件无效"的错误。

**解决方法：**

1. 检查 `TNS_ADMIN` 环境变量是否正确设置
 2. 检查 `tnsnames.ora` 文件格式是否正确
 3. 确保文件路径和权限正确

## 相关文档

- [OBClient 概述](https://www.oceanbase.com/docs/common-obclient-doc-cn-1000000006361905)
 - [OBClient 命令行选项参考](https://www.oceanbase.com/docs/common-obclient-doc-cn-1000000006361909)
 - [`--error-sql`（脚本报错上下文）](https://www.oceanbase.com/docs/common-obclient-doc-cn-1000000006361908)
 - [OBClient 配置和环境变量](https://www.oceanbase.com/docs/common-obclient-doc-cn-1000000006361920)
 - [Oracle 模式支持](https://www.oceanbase.com/docs/common-obclient-doc-cn-1000000006361914)

 上一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线