活动专区

活动公告

上车！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 8c gsql 工具使用教程

## 一、课程概述

### 1.1 课程目标

1. 掌握 gsql 连接数据库、常用元命令的使用方法
2. 熟悉 gsql 变量相关特性
3. 能够排查、简单定位 gsql 常见连接问题
4. 适用范围：功能同时兼容 GBase 8c 单机、分布式集群

## 二、gsql 工具介绍

### 2.1 工具定位

gsql 是 GBase 8c 专属命令行客户端连接工具，作用等同于 MySQL 的 MySQL、Oracle 的 sqlplus，主要用于连接数据库、执行 SQL、调试数据库。

配套可视化工具：DBeaver。

## 三、gsql 基础使用

### 3.1 命令通用格式

```
gsql -d dbname -p port  
```

**\*远程连接必须知道用户名**

参数说明：

| 参数     | 作用                | 默认值                               |
| ---------- | --------------------- | -------------------------------------- |
| `-d` | 指定连接的数据库名  | 首次连接推荐使用默认库 `postgres` |
| `-p` | 指定数据库端口      | -                                    |
| `-U` | 指定登录用户名      | `gbase`                          |
| `-h` | 指定数据库服务器 IP | 当前本机（本地连接）                 |

拓展：执行 `gsql --help` 可查看全部参数说明。

### 3.2 本地连接

直接在数据库服务器执行连接命令，示例：

```
gsql -d postgres -p 5432
```

连接成功标识：进入 `postgres=#` 命令行交互界面。

> 提示：默认非 SSL 连接，高安全场景建议启用 SSL 连接。

### 3.3 远程连接

#### 3.3.1 服务端配置（分布式集群读写 CN 节点，gbase 用户执行）

```
# 放行所有主机访问、认证方式为sha256
gs_guc reload -Z coordinator -N all -I all -h "host all all 0.0.0.0/0 sha256"
# 设置密码加密类型
gs_guc reload -Z coordinator -N all -I all -c "password_encryption_type=1"
# 监听所有IP地址
gs_guc reload -Z coordinator -N all -I all -c "listen_addresses = '*'"
```

#### 3.3.2 客户端配置

\*服务器上没有安装 gsql 的需要配置，GBase8c 安装完以后默认安装 gsql，不需要单独配置。

1. 上传并解压 gsql 客户端工具包；
2. 拷贝服务端 bin 目录至客户端：
   ```
   scp -r /home/gbase/服务端安装目录/bin gbase@客户端ip:客户端安装目录
   ```
3. 配置环境变量（编辑 \~/.bashrc）：
   ```
   export PATH=客户端安装目录/bin:$PATH
   export LD_LIBRARY_PATH=客户端安装目录/lib:$LD_LIBRARY_PATH
   ```
4. 生效环境变量：
   ```
   source ~/.bashrc
   ```
5. 客户端执行远程连接命令：
   ```
   gsql -d postgres -h 数据库IP -p 端口号
   ```

### 3.4 执行 SQL 语句

1. 交互式直接输入 SQL 执行；
2. 查看 SQL 语法：`\help [语法名称]`；
3. 示例：
   ```
   -- 插入数据
   insert into test values(1),(18);
   -- 查询数据
   select * from test;
   ```

### 3.5 gsql 变量特性

类似 Linux Shell 变量操作，常用命令：

```
-- 定义变量
\set vartest 20
-- 查看变量值
\echo :vartest
-- 删除变量
\unset vartest
```

### 3.6 常用元命令（反斜杠 `\` 开头）

元命令用于数据库管理、环境设置，常用指令：

* 数据库与连接管理

| 命令                                       | 功能说明                                       |
| -------------------------------------------- | ------------------------------------------------ |
| `\c 数据库名 [用户名] [主机名] [端口]` | 切换到指定数据库，可同时更换用户 / 主机 / 端口 |
| `\l`/`\list`                       | 列出所有数据库                                 |
| `\conninfo`                            | 显示当前连接信息（主机、端口、用户、数据库等） |
| `\q`/`\quit`                       | 退出 `gsql` 会话                             |
| `\password [用户名]`                   | 修改指定用户的密码                             |

* 对象查看（表 / 视图 / 索引 / 序列等）

| 命令                        | 功能说明                                   |
| ----------------------------- | -------------------------------------------- |
| `\dt`                   | 列出当前模式下的所有表                     |
| `\dt *.*`               | 列出所有模式下的所有表（包括系统模型）     |
| `\d 表名`               | 查看表的结构（列、数据类型、约束、索引等） |
| `\dv`                   | 列出当前模式下的所有视图                   |
| `\df 模式.*`            | 列出当前模式下的所有函数                   |
| `\di`                   | 列出当前模式下的所有索引                   |
| `\ds`                   | 列出当前模式下的所有序列                   |
| `\dp 表名`              | 查看表的权限分配情况                       |
| `\du`/`\list roles` | 列出所有用户 / 角色                        |
| `\dn`                   | 列出所有模式（schema）                     |

### 3.7 命令自动补全

gsql 支持 **Tab 键** 自动补齐关键字、命令。

## 四、gsql 常见问题排查

### 4.1 连接故障类

#### 4.1.1 报错：`could not connect to server: No route to host`

* 原因：IP 地址、端口填写错误，网络不通；
* 解决：核对 `-h` 主机 IP、`-p` 端口参数，检查网络连通性。

#### 4.1.2 报错：`FATAL: Invalid username/password,login denied.`

* 原因：用户名或密码错误；
* 解决：核对登录账号、密码。

#### 4.1.3 报错：`permission denied for database "postgres"`

* 原因：当前用户无数据库 `CONNECT` 连接权限；
* 解决：使用管理员 gbase 授权：
  ```
  GRANT CONNECT ON DATABASE dbname TO user_name;
  ```

#### 4.1.4 报错：`no pg_hba.conf entry for host`

* 原因：服务端未配置客户端主机访问权限；
* 解决：重新执行**远程连接服务端配置**指令，放行客户端 IP。

### 4.2 连接性能类

#### 4.2.1 数据库初始化语句执行慢

1. 使用 strace 跟踪连接全过程：
   ```
   strace gsql -U 用户名 ...
   ```
2. 登录库后通过执行计划分析慢语句：
   ```
   explain performance select version();
   ```
3. 参考官方《GBase 8c V5\_3.0.0\_开发者手册》优化。

#### 4.2.2 连接假死、无法认证

* 原因：数据库主节点磁盘空间满 / 磁盘故障；
* 解决：清理主节点数据盘空闲空间。

#### 4.2.3 TCP 连接创建缓慢

* 现象：`strace` 跟踪卡在 `connect` 阶段；
* 原因：客户端与服务端物理网络不稳定、网络负载过高；
* 解决：排查网络链路、带宽、网络拥堵问题。

## 五、总结

1. gsql 是 GBase 8c 核心命令行连接工具，分为本地、远程两种连接方式，远程需配置服务端访问策略与客户端环境变量；
2. 支持 SQL 执行、自定义变量、元命令管理，Tab 键支持自动补全；
3. 连接问题优先排查**网络、IP / 端口、账号密码、权限、服务端访问策略**；性能问题可通过 `strace`、执行计划、服务器资源定位根因。



GBase 8c

工具

8cA03 GBase 8c gsql工具课件

8cA03 GBase 8c gsql工具课件

评论

热门帖子