👋 欢迎来到吴老二技术博客,专注运维 / 数据库 / 云原生
首页/数据库/正文

人大金仓 KingbaseES 命令行操作指南

吴
吴老二
2026-11-16数据库21 次浏览0 条评论

在日常数据库运维过程中,除了通过图形化工具管理数据库之外,命令行也是非常常用的一种操作方式。

人大金仓(KingbaseES)提供了 KSQL 命令行客户端,可以通过命令行完成数据库连接、对象查询、SQL 执行、数据导入导出以及数据库日常管理等工作。

本文主要介绍 KSQL 的基本使用方法,重点讲解进入 KSQL 后通过 \? 查看帮助信息时涉及的命令,以及日常工作中经常使用的 COPY 数据导入导出操作。

一、KSQL 基本介绍

KSQL 是人大金仓提供的数据库命令行客户端,类似于 MySQL 的 mysql 客户端,可以连接数据库服务器并执行 SQL 语句。

1.1 查找 KSQL 客户端

Linux 环境下,人大金仓安装完成后,可以通过安装目录查找 KSQL。

find /opt -name ksql -type f 2>/dev/null

如果已经配置了环境变量,也可以直接执行:

which ksql

1.2 连接数据库

基本连接方式:

ksql -h 127.0.0.1 -p 54321 -U system -d TEST

参数说明:

| 参数 | 说明 | | ---- | ---------------- | | -h | 数据库服务器地址 | | -p | 数据库端口 | | -U | 登录用户名 | | -d | 数据库名称 |

执行后,根据提示输入数据库密码。

也可以使用环境变量传递密码:

export PGPASSWORD='数据库密码'

ksql -h 127.0.0.1 -p 54321 -U system -d TEST

unset PGPASSWORD

生产环境不建议将密码直接写入脚本或命令历史。

1.3 连接成功后的界面

连接成功后,一般会看到类似下面的提示符:

TEST=#

不同用户权限、数据库名称和客户端版本,提示符可能有所不同。

1.4 退出 KSQL

\q

也可以使用:

\quit

二、KSQL 帮助命令 ?

进入数据库后,输入:

\?

可以查看 KSQL 客户端支持的反斜线命令。

需要注意,\? 显示的是 KSQL 客户端元命令,不是数据库服务器支持的全部 SQL 语句。

如果只想查看某一类帮助,可以使用:

\? commands
\? options
\? variables

分别查看反斜线命令、客户端启动参数和客户端配置变量。

下面按照实际使用场景介绍这些命令。

2.1 数据库连接与基本信息

| 命令 | 功能说明 | | ------------ | ------------------------------------------------ | | \c | 重新连接数据库,可以指定数据库、用户、地址和端口 | | \connect | 与\c相同,用于建立新的数据库连接 | | \conninfo | 查看当前数据库连接信息 | | \l | 查看当前实例中的数据库列表 | | \list | 与\l相同 | | \copyright | 查看数据库版权及发布条款 | | \password | 修改当前用户或指定用户的密码 |

常用示例:

查看当前连接:

\conninfo

切换数据库:

\c TEST

切换指定用户连接:

\c TEST system 127.0.0.1 54321

查看数据库:

\l

修改当前用户密码:

\password

2.2 数据库对象查询命令

这一类命令在日常运维中使用频率比较高,主要用于查看表、视图、索引、函数、用户和其他数据库对象。

| 命令 | 功能说明 | | ------- | ----------------------------- | | \d | 查看数据库对象结构 | | \d+ | 查看对象详细信息 | | \da | 查看聚集函数 | | \dA | 查看访问方法 | | \db | 查看表空间 | | \dc | 查看字符集编码转换 | | \dC | 查看类型转换 | | \dd | 查看对象注释 | | \dD | 查看域 | | \ddp | 查看默认权限配置 | | \dE | 查看外部表 | | \di | 查看索引 | | \dm | 查看物化视图 | | \ds | 查看序列 | | \dt | 查看普通表 | | \dv | 查看视图 | | \des | 查看外部服务器 | | \det | 查看外部表 | | \deu | 查看用户映射 | | \dew | 查看外部数据包装器 | | \df | 查看函数 | | \dF | 查看文本搜索配置 | | \dFd | 查看文本搜索字典 | | \dFp | 查看文本搜索解析器 | | \dFt | 查看文本搜索模板 | | \dg | 查看数据库角色 | | \dl | 查看大对象 | | \dL | 查看过程语言 | | \dn | 查看 Schema | | \do | 查看操作符 | | \dO | 查看排序规则 | | \dp | 查看表、视图和序列权限 | | \dP | 查看分区表及分区索引 | | \drds | 查看角色和数据库的配置设置 | | \dRp | 查看逻辑复制 Publication | | \dRs | 查看逻辑复制 Subscription | | \dT | 查看数据类型 | | \du | 查看数据库用户及角色 | | \dx | 查看已安装扩展 | | \dy | 查看事件触发器 | | \z | 查看对象访问权限,与\dp类似 |

其中,\d 家族需要重点掌握。

查看当前 Schema 下的表:

\dt

查看指定 Schema 下的表:

\dt public.*

查看指定表结构:

\d public.test

查看表详细信息:

\d+ public.test

查看索引:

\di

查看指定表的索引:

\di public.*

查看视图:

\dv

查看函数:

\df

查看数据库用户:

\du

查看 Schema:

\dn

查看表权限:

\dp

这里有一个细节:\dt 只显示当前可见范围内的表,如果没有看到目标表,可以指定 Schema 进行查询。

2.3 SQL 编辑和执行命令

| 命令 | 功能说明 | | --------------- | ------------------------------------------------ | | \e | 使用外部编辑器编辑当前 SQL | | \edit | 与\e相同 | | \ef | 编辑指定函数或存储过程 | | \ev | 编辑指定视图定义 | | \p | 显示当前 SQL 缓冲区内容 | | \print | 与\p相同 | | \g | 执行当前 SQL,也可以将结果输出到文件 | | \gx | 执行 SQL,并强制使用扩展输出格式 | | \gdesc | 查看当前查询结果的列名和数据类型,不实际执行查询 | | \gexec | 将查询结果中的内容作为 SQL 语句继续执行 | | \gset | 将查询结果保存为 KSQL 变量 | | \crosstabview | 将查询结果转换成交叉表显示 | | \r | 清空当前 SQL 缓冲区 | | \reset | 与\r相同 | | \w | 将当前 SQL 缓冲区写入文件 | | \write | 与\w相同 | | \h | 查看 SQL 语法帮助 | | \help | 与\h相同 |

例如,输入一条 SQL 但暂时不执行:

SELECT * FROM public.test

查看当前 SQL:

\p

执行 SQL:

\g

清空当前 SQL:

\r

查看 SQL 语法:

\h SELECT

需要注意,\h 查询的是 SQL 语法帮助,\? 查询的是 KSQL 客户端命令帮助,两者用途不同。

2.4 数据导入导出与文件操作命令

| 命令 | 功能说明 | | ------------------- | ---------------------------------- | | \copy | 从客户端本地文件导入数据或导出数据 | | \i | 执行指定 SQL 文件 | | \include | 与\i相同 | | \ir | 相对于当前脚本目录执行文件 | | \include_relative | 与\ir相同 | | \lo_import | 将本地文件导入数据库大对象 | | \lo_export | 将数据库大对象导出到本地文件 | | \lo_list | 查看数据库大对象 | | \lo_unlink | 删除指定 OID 的大对象 |

示例:

执行 SQL 文件:

\i /data/test.sql

查看当前目录:

\! pwd

切换目录:

\cd /data

查看大对象:

\lo_list

删除指定大对象:

\lo_unlink 152801

这里的 \lo_unlink 删除的是数据库大对象,不是普通表数据。

2.5 查询结果显示控制命令

| 命令 | 功能说明 | | ------------- | ------------------------------ | | \a | 切换对齐和非对齐输出格式 | | \C | 设置查询结果标题 | | \f | 设置非对齐模式的字段分隔符 | | \H | 切换 HTML 输出格式 | | \html | 与\H相同 | | \o | 将查询输出重定向到文件或命令 | | \out | 与\o相同 | | \pset | 设置查询结果显示格式 | | \t | 仅显示数据,不显示列标题和行数 | | \T | 设置 HTML 表格属性 | | \x | 切换扩展显示模式 | | \timing | 显示 SQL 执行耗时 | | \encoding | 查看或设置客户端字符编码 | | \errverbose | 显示最近一次错误的详细信息 |

常用示例:

开启 SQL 执行时间统计:

\timing on

关闭:

\timing off

扩展模式显示:

\x on

恢复普通显示:

\x off

切换 CSV 输出:

\pset format csv

恢复默认表格输出:

\pset format aligned

只输出数据,不输出表头:

\t

将查询结果保存到文件:

\o /data/result.txt

SELECT * FROM public.test;

\o

注意:\o 会重定向 KSQL 的查询输出,并不等同于数据库 COPY 导出 CSV。

2.6 脚本、变量和终端操作命令

| 命令 | 功能说明 | | --------- | ----------------------------------- | | \echo | 在终端打印文本 | | \qecho | 将文本输出到当前查询输出通道 | | \set | 设置 KSQL 变量 | | \unset | 删除 KSQL 变量 | | \setenv | 设置客户端环境变量 | | \prompt | 提示输入内容并保存到变量 | | \if | 条件判断开始 | | \elif | 条件判断分支 | | \else | 条件判断否则分支 | | \endif | 结束条件判断 | | \s | 查看或保存命令历史 | | \watch | 按指定时间间隔重复执行 SQL | | \! | 执行操作系统 Shell 命令 | | \? | 显示 KSQL 帮助 | | \; | 将分号加入 SQL 缓冲区,但不立即执行 |

示例:

打印文本:

\echo 'Hello KingbaseES'

设置变量:

\set test_name 'kingbase'

查看变量:

\echo :test_name

删除变量:

\unset test_name

执行 Linux 命令:

\! df -h

查看命令历史:

\s

每隔 5 秒执行一次查询:

SELECT now();
\watch 5

按 Ctrl+C 可以中断重复执行。

以上命令涵盖官方 V9 KSQL 命令参考中的 88 个命令章节。部分命令存在别名或组合形式,例如 \q 与 \quit、\i 与 \include,并不代表它们是不同的功能。

三、KSQL 中常用的 SQL 基本操作

KSQL 中除了反斜线命令之外,也可以直接执行数据库 SQL 语句。

下面介绍一些日常操作中比较常用的 SQL。

3.1 查看当前数据库

SELECT current_database();

查看当前登录用户:

SELECT current_user;

查看当前 Schema:

SELECT current_schema();

查看当前数据库版本:

SELECT version();

3.2 查看 Schema

SELECT schema_name
FROM information_schema.schemata
ORDER BY schema_name;

3.3 查看表

SELECT table_schema, table_name
FROM information_schema.tables
WHERE table_type = 'BASE TABLE'
ORDER BY table_schema, table_name;

只查看 public Schema:

SELECT table_name
FROM information_schema.tables
WHERE table_schema = 'public'
AND table_type = 'BASE TABLE';

3.4 查看表数据

SELECT * FROM public.test;

只查看前 10 条:

SELECT * FROM public.test LIMIT 10;

查看表数据量:

SELECT COUNT(*) FROM public.test;

3.5 创建表

CREATE TABLE public.test (
    id INTEGER,
    name VARCHAR(100),
    age INTEGER,
    create_time TIMESTAMP
);

3.6 插入数据

INSERT INTO public.test
(id, name, age, create_time)
VALUES
(1, '张三', 25, CURRENT_TIMESTAMP);

3.7 修改数据

UPDATE public.test
SET age = 26
WHERE id = 1;

3.8 删除指定数据

DELETE FROM public.test
WHERE id = 1;

3.9 清空整张表

TRUNCATE TABLE public.test;

DELETE 和 TRUNCATE 都可以清理表数据,但两者并不相同。

  • DELETE:可以根据 WHERE 条件删除指定记录。
  • TRUNCATE:直接清空整张表的数据。
  • DROP TABLE:删除整张表,包括表结构。

日常操作时一定要区分这三个命令。

四、人大金仓 COPY 数据导入导出

COPY 是数据库日常运维中非常实用的功能,尤其是在数据库迁移、数据初始化、批量数据导入和数据备份时。

人大金仓支持 SQL 层面的 COPY 命令,同时 KSQL 也提供了 \copy 客户端命令。

两者虽然功能相似,但是文件访问位置存在明显区别。

4.1 COPY 和 \copy 的区别

| 对比项目 | COPY | \copy | | ------------------ | ------------------------ | -------------------------- | | 命令类型 | SQL 命令 | KSQL 元命令 | | 文件访问位置 | 数据库服务器 | KSQL 客户端 | | 文件权限 | 数据库服务器操作系统用户 | 运行 KSQL 的本地用户 | | 是否经过客户端传输 | 文件由服务器直接读写 | 数据经过客户端传输 | | 权限要求 | 需要服务器文件访问权限 | 不需要服务器端文件权限 | | 常见用途 | 服务器本地大批量导入导出 | 从运维电脑或客户端导入导出 |

举个例子:

假设数据库服务器 IP 为 192.168.1.100,数据库客户端在另一台 Linux 机器上。

如果使用 COPY:

COPY public.test
TO '/data/test.csv'
WITH (FORMAT CSV, HEADER);

这里的 /data/test.csv 是数据库服务器上的路径。

如果使用 \copy:

\copy public.test TO '/data/test.csv' WITH (FORMAT CSV, HEADER)

这里的 /data/test.csv 是运行 KSQL 的客户端机器上的路径。

这是两种命令最需要注意的区别。

4.2 COPY 导出表数据

将整张表导出为 CSV 文件:

COPY public.test
TO '/data/test.csv'
WITH (
    FORMAT CSV,
    HEADER,
    DELIMITER ','
);

参数说明:

| 参数 | 说明 | | ------------- | ------------------ | | FORMAT CSV | 使用 CSV 格式 | | HEADER | 导出字段名称 | | DELIMITER ',' | 使用逗号作为分隔符 |

如果使用 KSQL 客户端导出:

\copy public.test TO '/data/test.csv' WITH (FORMAT CSV, HEADER, DELIMITER ',')

如果只想导出指定字段:

COPY public.test(id, name, age)
TO '/data/test.csv'
WITH (FORMAT CSV, HEADER);

也可以通过查询条件导出部分数据:

COPY (
    SELECT *
    FROM public.test
    WHERE age > 20
)
TO '/data/test.csv'
WITH (FORMAT CSV, HEADER);

4.3 COPY 导入 CSV 文件

假设有一个 CSV 文件:

id,name,age,create_time
1,张三,25,2026-11-01 10:00:00
2,李四,30,2026-11-02 11:00:00
3,王五,28,2026-11-03 12:00:00

对应的表结构:

CREATE TABLE public.test (
    id INTEGER,
    name VARCHAR(100),
    age INTEGER,
    create_time TIMESTAMP
);

使用 COPY 导入:

COPY public.test
FROM '/data/test.csv'
WITH (
    FORMAT CSV,
    HEADER,
    DELIMITER ','
);

使用 \copy 导入客户端文件:

\copy public.test FROM '/data/test.csv' WITH (FORMAT CSV, HEADER, DELIMITER ',')

导入成功后,一般会返回类似信息:

COPY 3

表示本次成功导入了 3 条记录。

4.4 COPY 指定字段导入

有时候 CSV 文件中的字段顺序和数据库表结构不一致,可以在 COPY 中指定字段。

例如:

COPY public.test(id, name, age)
FROM '/data/test.csv'
WITH (FORMAT CSV, HEADER);

此时只导入指定的三个字段。

需要注意,未指定的字段必须允许为空或者有默认值,否则可能会出现导入失败。

4.5 COPY 追加数据

COPY 默认不会先清空目标表。

例如:

COPY public.test
FROM '/data/test.csv'
WITH (FORMAT CSV, HEADER);

如果表中原本有 100 条数据,本次 CSV 又导入 50 条,那么正常情况下导入完成后就有 150 条数据。

因此,COPY 本身是追加导入,不是覆盖导入。

如果需要覆盖原有数据,可以先清理表,再导入:

TRUNCATE TABLE public.test;

COPY public.test
FROM '/data/test.csv'
WITH (FORMAT CSV, HEADER);

生产环境执行前必须确认表内原有数据是否允许清空。

五、COPY 导入的数据如何删除

这是日常数据迁移中很容易遇到的问题。

例如,原本表中已经有 1000 条数据,通过 COPY 又导入了 500 条,发现导入文件有问题,需要删除刚刚导入的 500 条数据。

这时候需要注意:

COPY 不会自动记录本次导入的数据批次,也没有与之对应的 COPY UNDO 命令。

因此,不能简单地通过 COPY 命令反向删除刚刚导入的数据。

具体处理方法取决于数据导入时有没有做好隔离。

5.1 方法一:清空整张表

如果表中原有数据不需要保留,可以直接执行:

TRUNCATE TABLE public.test;

查看数据:

SELECT COUNT(*) FROM public.test;

返回:

0

说明数据已经清空。

如果只想删除数据,保留表结构,这种方式比较直接。

5.2 方法二:根据条件删除导入的数据

如果导入的数据有明确的特征,例如导入数据的 ID 都在 10000 到 10500 之间,可以根据条件删除。

DELETE FROM public.test
WHERE id BETWEEN 10000 AND 10500;

删除后检查:

SELECT COUNT(*)
FROM public.test
WHERE id BETWEEN 10000 AND 10500;

这种方式适合数据本身存在唯一标识或者可以通过明确条件区分的场景。

注意:如果原有数据也满足这个条件,同样会被删除。

5.3 方法三:通过临时表隔离导入数据

如果不确定导入的数据有哪些,建议不要直接 COPY 到正式业务表。

可以先创建一张临时表:

CREATE TEMP TABLE temp_test
(
    LIKE public.test INCLUDING DEFAULTS
);

然后将 CSV 文件导入临时表:

COPY temp_test
FROM '/data/test.csv'
WITH (
    FORMAT CSV,
    HEADER,
    DELIMITER ','
);

检查导入数量:

SELECT COUNT(*) FROM temp_test;

查看导入数据:

SELECT * FROM temp_test LIMIT 10;

确认数据没有问题后,再写入正式表:

INSERT INTO public.test
SELECT * FROM temp_test;

如果发现数据不正确,只需要清空临时表:

TRUNCATE TABLE temp_test;

也可以直接删除临时表:

DROP TABLE temp_test;

临时表会在当前数据库会话结束后自动删除。

这种方式比较适合日常数据迁移和批量初始化操作。

5.4 方法四:通过批次号管理导入数据

如果经常需要批量导入数据,建议在业务表中增加一个批次标识字段。

例如:

ALTER TABLE public.test
ADD COLUMN import_batch VARCHAR(50);

导入数据时指定批次号:

INSERT INTO public.test
(id, name, age, create_time, import_batch)
SELECT
    id,
    name,
    age,
    create_time,
    'batch_20261116'
FROM temp_test;

查看某次导入的数据:

SELECT *
FROM public.test
WHERE import_batch = 'batch_20261116';

如果发现本次导入有问题:

DELETE FROM public.test
WHERE import_batch = 'batch_20261116';

这种方法的好处是可以准确区分每次导入的数据,不会影响之前已经存在的业务数据。

5.5 删除 COPY 导出的文件

如果 COPY 已经执行了数据导出,例如:

COPY public.test
TO '/data/test.csv'
WITH (FORMAT CSV, HEADER);

此时生成的是数据库服务器上的文件。

需要登录数据库服务器,使用 Linux 命令删除:

rm -f /data/test.csv

如果使用的是:

\copy public.test TO '/data/test.csv' WITH (FORMAT CSV, HEADER)

则应该在运行 KSQL 的客户端机器上删除:

rm -f /data/test.csv

Windows 环境可以使用:

del D:\data\test.csv

需要区分的是,删除 CSV 文件不会删除数据库表中的数据,删除表数据也不会自动删除导出的 CSV 文件。

六、COPY 常见问题及排查

6.1 Permission denied

错误示例:

ERROR: could not open file "/data/test.csv":
Permission denied

原因:

使用 SQL COPY 时,数据库服务器需要访问指定文件。

检查数据库运行用户:

ps -ef | grep kingbase

检查文件权限:

ls -l /data/test.csv

根据实际情况调整文件权限和属主。

如果不方便调整数据库服务器文件权限,可以改用客户端 \copy。

6.2 No such file or directory

错误示例:

ERROR: could not open file:
No such file or directory

原因:

指定的文件路径不存在,或者文件位于另一台机器上。

排查:

ls -l /data/test.csv

注意区分 COPY 和 \copy 的文件路径。

6.3 invalid input syntax

错误示例:

ERROR: invalid input syntax for type integer

原因:

CSV 文件中的字段内容与数据库字段类型不匹配。

例如,数据库字段定义为 INTEGER,但是 CSV 中存在:

abc

需要检查 CSV 文件中的数据类型和字段顺序。

6.4 extra data after last expected column

错误示例:

ERROR: extra data after last expected column

常见原因:

  • CSV 字段数量与表结构不一致。
  • 分隔符配置不正确。
  • 字段内容中的逗号没有正确使用双引号包裹。

检查文件格式和 COPY 的 DELIMITER 参数。

6.5 中文乱码

如果导入后出现中文乱码,需要检查:

  • CSV 文件的实际编码。
  • 数据库编码。
  • KSQL 客户端编码。

查看数据库编码:

SHOW server_encoding;

查看客户端编码:

SHOW client_encoding;

也可以通过下面的命令查看或设置客户端编码:

\encoding

如果文件编码和数据库编码不一致,需要先确认实际编码,再选择正确的转换方式,不能只通过修改客户端显示编码解决所有乱码问题。

七、日常运维常用命令汇总

下面整理了一些日常工作中比较常用的命令,可以直接保存下来备用。

| 操作 | 命令 | | --------------- | ------------------------------------------------------ | | 查看帮助 | \? | | 查看数据库 | \l | | 查看当前连接 | \conninfo | | 切换数据库 | \c TEST | | 查看 Schema | \dn | | 查看所有表 | \dt | | 查看表结构 | \d 表名 | | 查看表详细结构 | \d+ 表名 | | 查看索引 | \di | | 查看视图 | \dv | | 查看用户 | \du | | 查看权限 | \dp | | 查看数据库版本 | SELECT version(); | | 查看当前用户 | SELECT current_user; | | 查看当前数据库 | SELECT current_database(); | | 查看表数据量 | SELECT COUNT(*) FROM 表名; | | 执行 SQL 文件 | \i 文件路径 | | 开启执行时间 | \timing on | | 查看执行历史 | \s | | 清空 SQL 缓冲区 | \r | | 导入 CSV | \copy 表名 FROM '文件路径' WITH (FORMAT CSV, HEADER) | | 导出 CSV | \copy 表名 TO '文件路径' WITH (FORMAT CSV, HEADER) | | 删除指定记录 | DELETE FROM 表名 WHERE 条件; | | 清空整张表 | TRUNCATE TABLE 表名; | | 删除表 | DROP TABLE 表名; | | 退出客户端 | \q |

八、总结

人大金仓 KSQL 命令行工具提供了比较完整的数据库管理能力。

日常运维中,并不需要记住全部的反斜线命令,但下面这些命令建议熟练掌握:

  • \?:查看客户端帮助。
  • \l:查看数据库。
  • \dt:查看表。
  • \d:查看表结构。
  • \du:查看用户。
  • \dp:查看权限。
  • \i:执行 SQL 文件。
  • \copy:从客户端进行数据导入导出。
  • \timing:统计 SQL 执行时间。
  • \conninfo:查看当前连接。

另外,COPY 数据导入导出需要特别注意文件所在的位置。使用 COPY 时,文件由数据库服务器访问;使用 \copy 时,文件由 KSQL 客户端访问。

如果涉及正式业务表的数据导入,建议优先采用临时表或批次号的方式管理数据。这样即使导入出现问题,也可以准确清理本次导入的数据,避免误删原有业务数据。

对于数据库运维人员来说,熟悉这些命令后,很多原本需要通过图形化工具完成的工作,都可以直接通过命令行完成。

评论 0

评论需 登录 后发表(注册并验证邮箱)。
还没有评论,来抢沙发~