KingbaseES数据库命令行工具ksql的实用操作技巧

一、写在前面做 DBA 这么多年GUI 工具我用过不少KStudio、Navicat、DBeaver 都挺好使。但真正到了生产环境——尤其是那种只能通过堡垒机跳进去的机房服务器——你会发现能依赖的只有命令行。KingbaseES 自带的 ksql 就是这样一个趁手的命令行工具功能丰富且针对国产环境做了不少优化。这篇文章把我日常工作中最常用的 ksql 操作整理出来希望能帮你少踩几个坑。二、连接数据库别小看这一行命令2.1 找到你的 ksqlKingbaseES 安装后ksql一般藏在两个地方# 服务端自带的 /opt/Kingbase/ES/V8/Server/bin/ksql # 独立的客户端工具推荐用这个 /opt/Kingbase/ES/V8/ClientTools/bin/ksql生产环境建议用 ClientTools 目录下的版本不依赖服务端的库文件拷贝到跳板机上也能直接用。如果你懒得记路径直接加到环境变量echo export PATH/opt/Kingbase/ES/V8/ClientTools/bin:$PATH ~/.bashrc source ~/.bashrc2.2 基础连接方式最朴素的连接命令长这样ksql -U system -d test-U指定用户名-d指定数据库名。执行后会让你输密码连上之后提示符变成这样ksql (V8.0) Type help for help. test#注意那个#它表示当前用户是超级用户。如果是普通用户提示符会变成这个细节在写操作文档时很有用一眼就能看出来权限级别。2.3 远程连接与密码处理本地 socket 连接有个坑有时候不指定-h参数KingbaseES 不会强制验密输什么密码都能进。这在开发环境是方便生产环境就是安全隐患了。稳妥的做法是始终指定主机地址ksql -U system -h 192.168.1.100 -p 54321 -W -d test-W 是强制要求输入密码-p 指定端口金仓默认 54321注意别跟其他数据库的默认端口搞混。如果你经常连同一个库可以建一个密码文件免掉每次输入的麻烦# ~/.pgpass 文件权限必须是 600 chmod 600 ~/.pgpass cat ~/.pgpass内容格式主机名:端口:数据库名:用户名:密码比如192.168.1.100:54321:test:system:YourPassword1232.4 环境变量偷懒法如果你连的参数每次都一样可以设几个环境变量export KINGBASE_HOST192.168.1.100 export KINGBASE_PORT54321 export KINGBASE_DATABASEtest export KINGBASE_USERsystem设完之后直接敲ksql就能连连-U、-d都不用写了。三、交互模式ksql 的核心战场3.1 先搞清楚自己在哪连进去之后第一件事是确认环境免得操作错了库-- 当前连接信息 \conninfo -- 数据库版本 SELECT version(); -- 许可证剩余天数这个很重要别等到过期了才发现 SELECT get_license_validdays();\conninfo的输出大概长这样You are connected to database test as user system on host 192.168.1.100 at port 54321.3.2 数据库和对象的地图在陌生的库里干活就像进了一个没开灯的仓库得先摸清布局。ksql提供了一堆以\开头的元命令我称之为地图工具-- 列出所有数据库 \l -- 切换到另一个库 \c production_db -- 列出当前库的所有模式Schema \dn -- 列出当前模式下的所有表 \dt -- 列出所有索引 \di -- 列出所有视图 \dv -- 列出所有函数 \df -- 查看某张表的结构 \d orders -- 查看表的权限分配 \dp orders -- 列出所有角色/用户 \du这些命令支持模糊匹配比如你想找所有以user开头的表\dt user*输出会过滤出user_info、user_log、user_permission之类的表。3.3 结果格式化让输出更符合你的习惯默认的输出是表格对齐模式字段多了之后会变得很难看。ksql提供了几种格式化切换-- 扩展模式每行一个字段适合字段很多的宽表 \x -- 再执行一次查询看看效果 SELECT * FROM user_info WHERE user_id 10001;扩展模式的输出会变成这样-[ RECORD 1 ]---------------------------------- user_id | 10001 username | zhangsan email | zhangsancompany.com created_at | 2024-03-15 09:23:17 last_login | 2026-05-07 18:45:33 is_active | t department | 技术研发部 phone | 13800138000比挤在一行里清晰多了。想切回表格模式再执行一次\x就行。其他常用的格式控制-- 只显示数据不显示表头 \t -- 切换 HTML 输出有时候需要把查询结果贴到邮件里 \H -- 设置 CSV 格式 \pset format csv -- 设置字段分隔符为制表符方便粘贴到 Excel \pset fieldsep \t -- 显示执行时间 \timing on\timing on是我必开的选项优化 SQL 的时候心里得有个数\timing on SELECT COUNT(*) FROM orders WHERE created_at 2026-01-01;输出末尾会多一行Time: 1243.567 ms (00:01.244)3.4 把结果存到文件有时候查询结果太多终端里翻不动或者需要交给别人分析可以重定向到文件-- 开始输出到文件 \o /tmp/query_result.txt -- 执行查询 SELECT * FROM orders WHERE status pending; -- 关闭文件输出回到终端 \o更省事的做法是在 shell 层面直接重定向ksql -U system -d test -c SELECT * FROM orders -o /tmp/orders.csv四、脚本执行从手工到自动化4.1 执行外部 SQL 文件这是最常用的场景。假设你有一个init_tables.sql文件ksql -U system -d test -f init_tables.sql如果想在交互模式里临时执行一个脚本\i /home/kingbase/scripts/backup_check.sql4.2 单行命令快速执行不需要进交互模式直接在 shell 里执行一条 SQLksql -U system -d test -c SELECT COUNT(*) FROM users输出count ------- 15234 (1 row)这个技巧在写 Shell 脚本时特别好用比如做一个定时巡检#!/bin/bash # daily_check.sh DB_NAMEproduction USERmonitor # 检查连接数 CONN_COUNT$(ksql -U $USER -d $DB_NAME -t -c SELECT COUNT(*) FROM sys_stat_activity WHERE datname $DB_NAME | xargs) if [ $CONN_COUNT -gt 400 ]; then echo [WARNING] $(date) - 当前连接数: $CONN_COUNT接近上限 /var/log/db_check.log fi4.3 变量与条件执行ksql支持变量定义这在写可复用的脚本时很有用-- 定义变量 \set table_name orders \set start_date 2026-01-01 -- 在 SQL 中使用变量 SELECT COUNT(*) FROM :table_name WHERE created_at :start_date;注意语法细节:table_name用于标识符表名、列名:start_date用于字符串值。混用会报错我第一次用的时候在这里卡了十分钟。条件执行适合处理不同环境的差异化逻辑\if :DB_NAME production \echo 正在操作生产库请谨慎 \elif :DB_NAME test \echo 测试环境放心折腾 \else \echo 未知环境 \endif4.4 错误处理别让小错误搞崩整个脚本默认情况下ksql遇到错误会继续往下执行这在批处理脚本里很危险。建议开启严格模式ksql -U system -d test -v ON_ERROR_STOP1 -f critical_update.sql或者在脚本开头加\set ON_ERROR_STOP on这样一旦某条 SQL 失败整个脚本会立刻退出不会继续执行后面的语句避免数据处于半完成状态。五、一些不太起眼但很实用的高级技巧5.1 历史命令与快速编辑ksql支持 Readline 库上下箭头可以翻历史命令CtrlR可以反向搜索。更爽的是\e命令-- 用外部编辑器编辑上一条命令 \e这会调用你系统默认的编辑器通常是 vi 或 nano编辑完保存退出后ksql会自动执行修改后的命令。写复杂 SQL 的时候比在原终端里来回删改舒服多了。5.2 在 ksql 里执行系统命令不需要退出ksql就能看系统信息-- 查看当前目录文件 \! ls -lh -- 查看磁盘空间数据目录够不够 \! df -h /opt/Kingbase/ES/V8/data -- 切换工作目录 \cd /tmp -- 查看当前工作目录 \! pwd这个\!命令我经常用来检查日志文件大小或者临时拷贝备份文件。5.3 大对象LOB操作虽然现在的业务系统很少直接操作大对象了但万一遇到老系统维护这几个命令能救命-- 导入文件到大对象 \lo_import /tmp/product_manual.pdf -- 查看所有大对象 \lo_list -- 导出大对象到文件 \lo_export 12345 /tmp/exported_manual.pdf -- 删除大对象 \lo_unlink 123455.4 自定义提示符默认的test#太单调了可以改成更有信息量的样式\set PROMPT1 %n%m %/%R%# 效果systemdbserver production#%n是用户名%m是主机名截断域名%/是当前数据库名%R是提示符符号%#是超级用户标识。如果你管理多个环境强烈建议把环境信息加到提示符里避免误操作。更花哨一点的带颜色\set PROMPT1 %[%033[1;32m%]%n%m%[%033[0m%] %/%R%# 这样用户名和主机名是绿色的在黑白终端里一眼就能定位。5.5 自动提交控制KingbaseES 默认是自动提交模式每条 SQL 执行完就提交。如果你需要显式控制事务-- 关闭自动提交 \set AUTOCOMMIT off -- 现在可以手动控制事务了 BEGIN; UPDATE accounts SET balance balance - 100 WHERE id 1; UPDATE accounts SET balance balance 100 WHERE id 2; -- 确认没问题再提交 COMMIT; -- 或者发现问题回滚 -- ROLLBACK;关闭自动提交后退出ksql时如果有未提交的事务会收到警告避免漏提交。六、KingbaseES 特有功能6.1 兼容模式查看金仓的一个卖点是兼容 Oracle 和 MySQL你可以查看当前的兼容模式SHOW COMPATIBILITY_MODE;返回值可能是 STD标准模式、ORAOracle 模式或 MYSQLMySQL 模式。不同模式下同样的 SQL 可能有不同的行为迁移的时候尤其要注意。6.2 查看已安装的扩展\dx输出示例List of installed extensions Name | Version | Schema | Description ------------------------------------------------------------------------------------------------- plsql | 1.0 | pg_catalog | PL/SQL procedural language sys_stat_statements | 1.0 | public | track execution statistics of all SQL statements pgcrypto | 1.3 | public | cryptographic functionssys_stat_statements是性能分析的利器默认可能没有启用需要手动加载CREATE EXTENSION IF NOT EXISTS sys_stat_statements;6.3 错误详情查看SQL 报错时默认信息有时候不够详细。用\errverbose可以看到更完整的信息SELECT * FROM non_existent_table; -- ERROR: relation non_existent_table does not exist \errverbose输出会包含 SQLSTATE 错误码、出错位置等详细信息排错的时候很有用。七、常见问题与排错7.1 连接失败排查 checklist遇到连不上的情况按这个顺序检查服务有没有起ps -ef | grep kingbase端口对不对ss -tlnp | grep 54321监听地址设了没检查kingbase.conf里的listen_addresses默认可能是localhost远程连需要改成*或具体 IP。防火墙放行了吗firewall-cmd --list-ports密码对不对注意 KingbaseES 的密码策略默认可能有复杂度要求而且区分大小写。7.2 字符集乱码遇到中文乱码先查编码-- 服务端编码 SHOW server_encoding; -- 客户端编码 SHOW client_encoding; -- 修改客户端编码 \encoding UTF8如果服务端是UTF8客户端是GBK中文基本会乱。统一成UTF8最省事。7.3 权限问题报错permission denied for relation先确认权限-- 查看当前用户 SELECT current_user; -- 查看表权限 \dp table_name -- 查看角色权限 \du username有时候不是没权限是搜索路径search_path不对表在别的 Schema 里-- 查看当前搜索路径 SHOW search_path; -- 临时切换 SET search_path TO app_schema, public;八、实用命令速查表最后整理一张速查表建议收藏或者打印贴显示器旁边命令作用\l列出所有数据库\c dbname切换数据库\dt列出当前模式下的表\d tablename查看表结构\di列出索引\dv列出视图\df列出函数\dn列出模式\du列出角色/用户\dp列出权限\x切换扩展显示模式\t切换只显示数据无表头\timing on/off开启/关闭执行时间显示\o filename输出结果到文件\i filename执行外部 SQL 文件\e用编辑器编辑上条命令\! command执行系统命令\cd dir切换工作目录\conninfo显示当前连接信息\q退出 ksql\?查看所有元命令帮助\h SQL命令查看 SQL 语法帮助九、写在最后ksql这个工具表面上看起来就是个黑框框但用熟了之后效率比 GUI 高得多。特别是当你需要批量处理、写自动化脚本、或者在服务器直接排错的时候命令行的优势是图形工具没法比的。几个我个人觉得最值得养成习惯的操作连接时始终加-h参数养成安全连接的习惯开\timing on对 SQL 性能心里有数复杂操作先\set AUTOCOMMIT off给自己留回滚的余地用好\o和-f把重复操作脚本化。如果你是从 MySQL 的 mysql 客户端转过来的刚开始可能会觉得 ksql 的元命令语法有点别扭为啥都是反斜线但坚持用一周基本就能形成肌肉记忆了。毕竟命令行工具的设计逻辑一旦熟悉效率提升是非常明显的。如果这篇文章对你有帮助点个赞或者收藏一下下次找起来方便。有问题也可以留言看到都会回。