Oracle Database에 접속해 SQL, PL/SQL, SQL*Plus command와 script를 실행하는 command-line client다. 전체 Oracle Database Client 또는 가벼운 Oracle Instant Client의 SQL*Plus package로 제공된다.
SQL*Plus Instant Client에는 같은 version과 architecture의 Basic 또는 Basic Light package와 SQL*Plus package가 모두 필요하다. Oracle은 호환되는 최신 Instant Client Release Update 사용을 권장한다.
Oracle Linux 8 이상에서 Oracle Instant Client repository를 구성한 뒤 설치한다.
sudo dnf install oracle-instantclient-basic sudo dnf install oracle-instantclient-sqlplus
RHEL / Fedora에서는 Oracle download page에서 대상 platform과 architecture에 맞는 official RPM 두 개를 받아 local file로 설치할 수 있다. 배포판의 Oracle 지원 matrix와 RPM 의존성을 먼저 확인한다.
sudo dnf install ./oracle-instantclient-basic-*.rpm ./oracle-instantclient-sqlplus-*.rpm
Oracle은 SQL*Plus용 official APT repository를 제공하지 않는다. Linux x86-64 download page에서 같은 version의 Basic 또는 Basic Light ZIP과 SQL*Plus ZIP을 받아 같은 directory에 푼 뒤 그 directory를 PATH에 추가한다. 필요한 OS library는 해당 download page의 installation steps를 따른다.
unzip instantclient-basic-linux.x64-VERSION.zip -d /opt/oracle unzip instantclient-sqlplus-linux.x64-VERSION.zip -d /opt/oracle export PATH=/opt/oracle/instantclient_VERSION:$PATH
Oracle이 제공하는 architecture별 Basic 또는 Basic Light DMG와 SQL*Plus DMG를 함께 설치하고 installation directory를 PATH에 추가한다. official Homebrew formula는 제공되지 않는다.
Oracle의 Windows x64 page에서 같은 version의 Basic 또는 Basic Light ZIP과 SQL*Plus ZIP을 같은 directory에 풀고 그 directory를 PATH 앞쪽에 추가한다. 해당 release가 요구하는 Microsoft Visual CRedistributable도 설치한다. official ''winget'' package는 제공되지 않는다.
==== Verify ====
<code bash>
sqlplus -V
</code>
===== Usage =====
* ''<color #c3c3c3>**sqlplus**</color> <color #22b14c>[OPTIONS]</color> <color #7092be>[LOGON] [@SCRIPT [ARGS...]]</color>''
* ''<color #c3c3c3>**sqlplus**</color> <color #7092be>USERNAME@TNS_ALIAS</color>'': Oracle Net service name으로 접속하고 password는 prompt에서 입력
* ''<color #c3c3c3>**sqlplus**</color> <color #7092be>USERNAME@\"HOST:PORT/SERVICE_NAME\"</color>'': Easy Connect로 직접 접속
* ''<color #c3c3c3>**sqlplus**</color> <color #7092be>/</color> <color #ff7f27>**AS SYSDBA**</color>'': local OS 인증으로 privileged connection
* ''<color #c3c3c3>**sqlplus**</color> <color #7092be>/NOLOG</color>'': initial database connection 없이 시작
<note warning>
<del>''sqlplus USER/PASSWORD@TNS_ALIAS''</del>처럼 password를 command argument에 포함하는 legacy 사용법은 피한다. ''sqlplus USER@TNS_ALIAS''로 실행해 password prompt를 사용하거나 Oracle Wallet 같은 external authentication을 사용한다.
</note>
===== Options =====
* ''<color #22b14c>**-H**, **-HELP**</color>'': program syntax 표시 후 종료
* ''<color #22b14c>**-V**, **-VERSION**</color>'': SQL*Plus version 표시 후 종료
* ''<color #22b14c>**-L**, **-LOGON**</color>'': initial login 실패 시 다시 묻지 않고 종료. unattended script에 유용
* ''<color #22b14c>**-S**, **-SILENT**</color>'': banner, prompt와 command echo를 줄임
* ''<color #22b14c>**-R**, **-RESTRICT**</color> <color #7092be>1
# TNS alias: password는 prompt에서 입력 sqlplus app_user@PRODDB # Easy Connect sqlplus app_user@"db.example.com:1521/appsvc.example.com" # 먼저 connectionless session을 열고 SQL> prompt에서 접속 sqlplus /nolog
SQL> CONNECT app_user@PRODDB Enter password: SQL> SHOW USER
<note important>
CONNECT는 현재 connection을 먼저 끊는다. 새 credential이나 connect identifier가 잘못되면 기존 database session도 유지되지 않는다.
</note>
==== Run a Script ====
sqlplus -L app_user@PRODDB @report.sql 2026-08-13
-- report.sql WHENEVER OSERROR EXIT 9 WHENEVER SQLERROR EXIT SQL.SQLCODE SET ECHO OFF SET FEEDBACK OFF SET HEADING ON SET PAGESIZE 50000 SET LINESIZE 200 SET TRIMSPOOL ON SPOOL report.log SELECT * FROM report_view WHERE report_date = TO_DATE('&1', 'YYYY-MM-DD'); SPOOL OFF EXIT SUCCESS
<note important>
batch job에서는 -L과 WHENEVER SQLERROR / WHENEVER OSERROR를 함께 사용한다. SQL*Plus는 이 지시문이 없으면 SQL error가 발생해도 shell에 success exit status를 반환할 수 있다.
</note>
===== Commands =====
==== Session and Buffer ====
* CONNECT USERNAME@CONNECT_IDENTIFIER: 다른 account 또는 database로 reconnect
* DISCONNECT: SQL*Plus를 종료하지 않고 database session만 종료
* EXIT, QUIT: session을 종료하고 operating system으로 복귀
* SHOW USER: 현재 접속 user 확인
* DESCRIBE OBJECT: table, view, procedure 등 object 구조 확인
* LIST: SQL buffer 내용 표시
* /: SQL buffer의 마지막 SQL 또는 PL/SQL block 재실행
* EDIT: configured external editor로 SQL buffer 편집
* CLEAR SCREEN: terminal 화면 지우기
* HOST COMMAND, !COMMAND: OS shell command 실행
<note warning>
HOST, !와 EDIT는 local system command 또는 editor를 실행한다. 신뢰하지 않는 SQL script를 실행할 때는 내용을 먼저 검토하고 필요하면 sqlplus -R 3으로 제한한다.
</note>
==== Spool and Scripts ====
* SPOOL PATH: 화면 output을 file에 기록
* SPOOL PATH APPEND: 기존 file에 이어쓰기
* SPOOL OFF: spool file 닫기
* START SCRIPT.sql [ARGS…], @SCRIPT.sql [ARGS…]: script 실행
* @@SCRIPT.sql [ARGS…]: 현재 실행 중인 script의 directory를 기준으로 nested script 실행
==== Variables ====
* DEFINE NAME = VALUE: substitution variable 정의
* &NAME: substitution variable 참조. undefined variable는 값을 prompt로 요청
* &&NAME: 값을 요청한 뒤 이후 참조에 재사용하도록 정의
* UNDEFINE NAME: substitution variable 해제
* ACCEPT NAME PROMPT 'MESSAGE': 사용자 입력을 variable에 저장
* COLUMN COLUMN_NAME NEW_VALUE NAME: query 결과 column 값을 substitution variable에 저장
===== Configuration =====
Oracle Net file, TNS_ADMIN, glogin.sql, login.sql, startup precedence와 안전한 profile 작성법은 SQL*Plus configuration을 참조한다.
===== Troubleshooting =====
* sqlplus: command not found: Instant Client Basic과 SQL*Plus package가 같은 version인지, executable directory가 PATH에 있는지 확인한다.
* ORA-12154: connect identifier 철자, TNS_ADMIN과 tnsnames.ora 위치를 확인한다. Easy Connect로 name resolution 문제를 분리한다.
* ORA-12514 / ORA-12541: service name, listener host와 port, listener registration을 확인한다.
* script가 error 후에도 success로 끝남: script 시작 부분에 WHENEVER SQLERROR EXIT SQL.SQLCODE와 WHENEVER OSERROR EXIT를 추가한다.
* 한글이 깨짐: client NLS_LANG, terminal encoding과 database character set의 조합을 확인한다.
===== Compatibility =====
* SQL*Plus client와 Oracle Database server version은 반드시 같을 필요가 없지만, 지원 가능한 client/server 조합은 Oracle Client/Database interoperability matrix를 따른다.
* Instant Client installation은 platform과 architecture가 같은 Basic 또는 Basic Light 및 SQL*Plus package를 조합한다.
* Basic Light는 English error message와 제한된 character set만 포함하므로 다국어 환경에서는 Basic을 우선 검토한다.
===== Related SQL Records =====
다음은 기존 페이지에 기록되어 있던 database SQL이다. SQL*Plus 전용 command가 아니며 필요한 최소 privilege를 가진 account에서 실행한다.
CREATE USER app_user IDENTIFIED BY "REDACTED_PASSWORD"; GRANT CONNECT, RESOURCE TO app_user;
<note warning>
CONNECT와 RESOURCE role에 의존하는 방식은 legacy application에서 볼 수 있다. 새 account에는 실제 필요한 system/object privilege만 명시적으로 부여하고 production password를 script나 wiki에 저장하지 않는다.
</note>
===== Help =====
sqlplus -help ++