Oracle Instant Client 설치 및 SQL*Plus 실행

최근 AI 프로젝트에서 Oracle DB 연동을 위해 Oracle Instant Client 23.7 버전을 설치하고 SQL*Plus를 세팅하는 과정을 진행했습니다.
직접 겪은 시행착오와 트러블슈팅 과정을 공유합니다.

 

 

실행 환경:

• WSL Ubuntu 24.04.02 LTS

---

1. 설치 파일 준비

Oracle 공식 다운로드 페이지에서 Instant Client 두 가지 ZIP 파일을 다운받습니다.

• instantclient-basiclite-< cpu 아키텍쳐 >.zip (또는 basic)
• instantclient-sqlplus-< cpu 아키텍쳐 >.zip

직접 다운받아도 되고, 다운로드 링크를 복사해서 curl 명령어로 다운받아줄 수도 있습니다.

curl -O https://download.oracle.com/otn_software/linux/instantclient/2380000/instantclient-basic-linux.x64-23.8.0.25.04.zip
curl -O https://download.oracle.com/otn_software/linux/instantclient/2380000/instantclient-sqlplus-linux.x64-23.8.0.25.04.zip

 

 

---

2. 압축 해제 및 폴더 구조

두 ZIP 파일을 동일한 폴더(instantclient_23_8/)에 순서대로 압축 해제를 해줍니다.

• 먼저 basiclite를 풀고,
• 그 위에 sqlplus ZIP 파일을 덮어쓰기(overwrite) 방식으로 풀어야 합니다. 

unzip instantclient-basiclite-linux.x64-23.7.0.0.0.zip -d instantclient_23_8
unzip instantclient-sqlplus-linux.x64-23.7.0.0.0.zip -d instantclient_23_8

 

 

---

3. 프로젝트 내 폴더 이동 및 환경 변수 설정

instantclient_23_8/ 폴더를 프로젝트 내 경로에 위치시켜줍니다.

 

project_root_dir/agent/oracle/instantclient_23_8

이 위치를 기준으로 환경변수를 설정합니다:

export ORACLE_HOME="$(pwd)/agent/oracle/instantclient_23_7"
export LD_LIBRARY_PATH=$ORACLE_HOME:$LD_LIBRARY_PATH
export PATH=$ORACLE_HOME:$PATH

 

 

---

4. 동작 확인

$ sqlplus -v
SQL*Plus: Release 23.0.0.0.0 - Production

 

정상적으로 동작한다면 SQL*Plus 버전이 출력됩니다.

 

 

---

트러블슈팅

1. sqplus: command not found

$ sqlplus -v
sqlplus: command not found

원인

이 에러는 보통 sqlplus 실행 파일을 찾을 수 없을 때 발생합니다.
대부분 환경 변수(PATH) 설정이 잘못되었거나,
sqlplus가 들어있는 폴더 경로가 올바르지 않을 때 생깁니다.

 

 

Instant Client를 압축 해제할 때 -d 옵션을 빼먹고 풀면,
instantclient_23_8 폴더 내부에 또 다른 instantclient_23_8 폴더가 생성되는 경우가 있습니다.

즉, instantclient_23_8/instantclient_23_8/...

이런 중첩 구조가 만들어져 실제 sqlplus 실행 파일 경로와 환경 변수에 지정한 경로가 불일치하게 됩니다.

 

해결법

하위 폴더를 상위 폴더로 옮기고, 빈 하위 폴더를 제거해줍니다.

 

---

 

2. sqlplus 실행 오류 (libaio.so.1 not found)

 

원인

sqlplus 실행 시 필요한 libaio.so.1 라이브러리가 Ubuntu 24.04 LTS 기본 저장소에서 제거됨.
→ libaio1 패키지가 누락되어 생기는 문제.

 

해결방법

https://community.localwp.com/t/unable-to-install-on-ubuntu-24-04-lts-due-to-missing-dependency/43709/9

위 사이트에서 단서를 얻어서 해결했습니다.

 

• libaio1 수동 설치

curl -O http://launchpadlibrarian.net/646633572/libaio1_0.3.113-4_amd64.deb
sudo dpkg -i libaio1_0.3.113-4_amd64.deb

 

다시 동작을 확인해보니 잘 됩니다:

 

 

• 만약 그래도 안 된다면, 추가 설치:

# libtinfo5 설치
curl -O http://launchpadlibrarian.net/648013231/libtinfo5_6.4-2_amd64.deb
sudo dpkg -i libtinfo5_6.4-2_amd64.deb

# libncurses5 설치
curl -O http://launchpadlibrarian.net/648013227/libncurses5_6.4-2_amd64.deb
sudo dpkg -i libncurses5_6.4-2_amd64.deb

# 기타 패키지 설치
sudo apt install libnss3-tools

 

---

 

Oracle Instant Client 설치는 공식 문서만 봐서는 생략된 세부 사항들이 많아 초반에 약간 고생했지만,
위 절차와 트러블슈팅 경험을 토대로 문제없이 세팅을 완료할 수 있었습니다.

혹시 같은 작업을 하시는 분들은 폴더 구조와 의존 라이브러리 문제를 꼭 확인하시고 진행하시길 바랍니다!