0x-4-Oracle 23 ai-sqlcl 25.1.1 独立安装-配置和优化

一、独立安装sqlcl

1. ​安装 Java 环境​

SQLcl 需要 Java 1.8.0_220 或更高版本，

Oracle Linux9.6 上已经默认安装Oracle 23ai后Java 是11 lts版本

如果java jdk安装错误将遇上SQLcl困扰n多人的bug

sql /nolog
错误：找不到或加载主类 oracle.dbtools.raptor.scriptrunner.cmdline.SqlCli
原因：java.lang.ClassNotFoundException：oracle.dbtools.raptor.scriptrunner.cmdline.SqlCli

bash复制# 检查当前 Java 版本
java -version

# 若未安装或版本过低，安装 OpenJDK 17（推荐）
sudo dnf install java-17-openjdk-devel

# 设置 JAVA_HOME（根据实际路径调整）
echo "export JAVA_HOME=/usr/lib/jvm/java-17-openjdk" >> ~/.bashrc
source ~/.bashrc

[oracle@OL96 ~]$ which java
/usr/bin/java
[oracle@OL96 ~]$ which sqlcl
/usr/bin/which: no sqlcl in (/opt/oracle/product/23ai/dbhomeFree/bin:/home/oracle/.local/bin:/home/oracle/bin:/usr/local/bin:/usr/bin:/usr/local/sbin:/usr/sbin:/usr/lib/jvm/java-11-openjdk/bin:/opt/sqlcl/bin:/opt/sqlcl/bin:/opt/sqlcl/bin:/usr/lib/jvm/java-11-openjdk/bin)

2. ​下载并安装 SQLcl--默认安装了一个版本

可以独立下载

SQLcl Downloads

也可以直接wget​ 

# 下载最新版 SQLcl（当前最新为 25.1.1）--20250607
wget https://download.oracle.com/otn_software/java/sqldeveloper/sqlcl-latest.zip
unzip sqlcl-latest.zip -d /opt/
[root@OL96 home]# wget https://download.oracle.com/otn_software/java/sqldeveloper/sqlcl-latest.zip
--2025-06-08 00:10:08--  https://download.oracle.com/otn_software/java/sqldeveloper/sqlcl-latest.zip
Resolving download.oracle.com (download.oracle.com)... 23.35.208.76
Connecting to download.oracle.com (download.oracle.com)|23.35.208.76|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 87557295 (84M) [application/zip]
Saving to: ‘sqlcl-latest.zip’

sqlcl-latest.zip                  100%[=============================================================>]  83.50M  2.26MB/s    in 57s

2025-06-08 00:11:07 (1.47 MB/s) - ‘sqlcl-latest.zip’ saved [87557295/87557295]

# 设置环境变量
echo 'export PATH=$PATH:/opt/oracle/sqlcl/bin' >> ~/.bashrc
source ~/.bashrc

2. 查找默认的sqlcl路径和rpm安装的sqlcl 

---可以使用默认的sql也可以用dnf install 下载最新的sqlcl，需要提前添加oracle linux repo
sudo dnf config-manager --add-repo https://yum.oracle.com/repo/OracleLinux/OL9/oracle/software/x86_64
sudo dnf install sqlcl
--这个sqlcl安装后，会在/opt/oracle/sqlcl路径下。
而原生的随着oracle 23 ai free安装的sql在/opt/oracle/product/23ai/dbhomeFree/sqlcl/bin

--需要修改oracle下的.bash_profile文件，才能正常使用sqlcl
--关键设置export PATH=$PATH:/opt/oracle/product/23ai/dbhomeFree/sqlcl/bin
[oracle@OL96 ~]$ vi .bash_profile
--
[oracle@OL96 ~]$ cat .bash_profile
# .bash_profile

# Get the aliases and functions
if [ -f ~/.bashrc ]; then
        . ~/.bashrc
fi

# User specific environment and startup programs
export ORACLE_HOME=/opt/oracle/product/23ai/dbhomeFree
export ORACLE_SID=FREE
export PATH=$ORACLE_HOME/bin:$PATH
export PATH=$PATH:/opt/oracle/product/23ai/dbhomeFree/sqlcl/bin
export JAVA_HOME=/usr/lib/jvm/java-11-openjdk
export PATH=$PATH:$JAVA_HOME/bin
[oracle@OL96 ~]$
--
[oracle@OL96 ~]$ source .bash_profile
[oracle@OL96 ~]$ sql / as sysdba
SQLcl: Release 25.1 Production on Sun Jun 08 09:33:25 2025

Copyright (c) 1982, 2025, Oracle.  All rights reserved.

Connected to:
Oracle Database 23ai Free Release 23.0.0.0.0 - Develop, Learn, and Run for Free
Version 23.8.0.25.04

3. ​配置 SQLcl 基础连接 

# 连接 Oracle 23ai Free 数据库
sql username/password@//localhost:1521/FREE

# 或使用 EZConnect 格式
sql user@//db_host:1521/service_name

4. ​启用 23ai 特性支持​

在 SQLcl 中设置兼容性参数：

-- 在 SQLcl 会话中执行
SET SQLCOMPATIBILITY '23'

5. ​常用配置优化

-- 启用自动补全（默认开启）
SET AUTOTRACE ON

-- 设置历史记录（保存 1000 条命令）
SET HISTSIZE 1000

-- 启用 JSON 输出格式（适合 23ai 的 JSON 功能）
SET SQLFORMAT JSON

-- 显示执行时间
SET TIMING ON

6. ​23ai 特定功能配置 

-- 向量搜索示例（使用 23ai 的 AI Vector Search）
SELECT content 
FROM documents 
ORDER BY VECTOR_DISTANCE(embedding, :query_vector) 
FETCH FIRST 5 ROWS ONLY;

7. ​登录属性配置​

创建 $HOME/sqlcl/login.sql 自动加载脚本：

-- login.sql 内容
SET SQLFORMAT ANSICONSOLE
SET FEEDBACK 1
DEFINE _EDITOR = vim
SET HISTSIZE 1000
ALTER SESSION SET NLS_DATE_FORMAT = 'YYYY-MM-DD HH24:MI:SS';

 8. ​异常排除

# 启用调试模式
SQLCL_DEBUG=true sql user/pass@db

# 检查 23ai 特性兼容性
SELECT * FROM v$compatibility WHERE feature_id LIKE '%23AI%';

TIPS​：

undefined.Oracle 23ai 的 AI Vector Search 需要单独启用

undefined.使用 SET COMPATIBILITY 确保语法兼容性

undefined.通过 ALTER SYSTEM SET enable_vector_engine=TRUE 启用向量引擎（需要 DBA 权限）

9. 常用 SQLcl 命令