{{tag>[cli oracle database sql sqlplus]}}
====== SQL*Plus ======
Oracle Database에 접속해 SQL, PL/SQL, SQL*Plus command와 script를 실행하는 command-line client다. 전체 Oracle Database Client 또는 가벼운 Oracle Instant Client의 SQL*Plus package로 제공된다.
===== Summary =====
* interactive query, database administration, batch script와 report 생성에 사용한다.
* remote database에는 Oracle Net service name 또는 Easy Connect string으로 접속한다.
* command line에 password를 쓰면 process list, shell history, job log에 노출될 수 있으므로 username만 지정하고 prompt에서 입력한다.
===== Installation =====
SQL*Plus Instant Client에는 같은 version과 architecture의 ''Basic'' 또는 ''Basic Light'' package와 ''SQL*Plus'' package가 모두 필요하다. Oracle은 호환되는 최신 Instant Client Release Update 사용을 권장한다.
==== Oracle Linux / RPM 계열 ====
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
==== Debian / Ubuntu ====
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
==== macOS ====
Oracle이 제공하는 architecture별 ''Basic'' 또는 ''Basic Light'' DMG와 ''SQL*Plus'' DMG를 함께 설치하고 installation directory를 ''PATH''에 추가한다. official Homebrew formula는 제공되지 않는다.
==== Windows ====
Oracle의 Windows x64 page에서 같은 version의 ''Basic'' 또는 ''Basic Light'' ZIP과 ''SQL*Plus'' ZIP을 같은 directory에 풀고 그 directory를 ''PATH'' 앞쪽에 추가한다. 해당 release가 요구하는 Microsoft Visual C++ Redistributable도 설치한다. official ''winget'' package는 제공되지 않는다.
==== Verify ====
sqlplus -V
===== Usage =====
* ''**sqlplus** [OPTIONS] [LOGON] [@SCRIPT [ARGS...]]''
* ''**sqlplus** USERNAME@TNS_ALIAS'': Oracle Net service name으로 접속하고 password는 prompt에서 입력
* ''**sqlplus** USERNAME@\"HOST:PORT/SERVICE_NAME\"'': Easy Connect로 직접 접속
* ''**sqlplus** / **AS SYSDBA**'': local OS 인증으로 privileged connection
* ''**sqlplus** /NOLOG'': initial database connection 없이 시작
''sqlplus USER/PASSWORD@TNS_ALIAS''처럼 password를 command argument에 포함하는 legacy 사용법은 피한다. ''sqlplus USER@TNS_ALIAS''로 실행해 password prompt를 사용하거나 Oracle Wallet 같은 external authentication을 사용한다.
===== Options =====
* ''**-H**, **-HELP**'': program syntax 표시 후 종료
* ''**-V**, **-VERSION**'': SQL*Plus version 표시 후 종료
* ''**-L**, **-LOGON**'': initial login 실패 시 다시 묻지 않고 종료. unattended script에 유용
* ''**-S**, **-SILENT**'': banner, prompt와 command echo를 줄임
* ''**-R**, **-RESTRICT** 1|2|3'': file system과 OS command 접근을 단계적으로 제한
* ''**-M**, **-MARKUP** CSV|HTML ...'': machine-readable CSV 또는 HTML output 설정
* ''**-F**, **-FAST**'': script performance에 유리한 system variable 조합을 적용
===== Examples =====
==== Interactive Connection ====
# 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
''CONNECT''는 현재 connection을 먼저 끊는다. 새 credential이나 connect identifier가 잘못되면 기존 database session도 유지되지 않는다.
==== 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
batch job에서는 ''-L''과 ''WHENEVER SQLERROR'' / ''WHENEVER OSERROR''를 함께 사용한다. SQL*Plus는 이 지시문이 없으면 SQL error가 발생해도 shell에 success exit status를 반환할 수 있다.
===== 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 실행
''HOST'', ''!''와 ''EDIT''는 local system command 또는 editor를 실행한다. 신뢰하지 않는 SQL script를 실행할 때는 내용을 먼저 검토하고 필요하면 ''sqlplus -R 3''으로 제한한다.
==== 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:config:ko|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;
''CONNECT''와 ''RESOURCE'' role에 의존하는 방식은 legacy application에서 볼 수 있다. 새 account에는 실제 필요한 system/object privilege만 명시적으로 부여하고 production password를 script나 wiki에 저장하지 않는다.
===== Help =====
++++ sqlplus -help |
현재 base environment에는 ''sqlplus''가 설치되어 있지 않아 live ''sqlplus -help'' output을 수집하지 않았다. 설치된 target version에서 실행한 원문으로 이 block을 보강한다.
++++
===== See Also =====
* [[sql_plus:config:ko|SQL*Plus configuration]]
* [[oracle:sql|Oracle SQL]]
* [[oracle:database:ko|Oracle Database]]
* [[https://docs.oracle.com/en/database/oracle/oracle-database/26/sqpug/|Oracle SQL*Plus User's Guide and Reference]]
* [[https://docs.oracle.com/en/database/oracle/oracle-database/26/sqpug/starting-SQL-Plus.html|Starting SQL*Plus]]
* [[https://www.oracle.com/database/technologies/instant-client.html|Oracle Instant Client]]
===== History =====
* codex:: 2026-08-13 Migrated the legacy page and expanded installation, secure connection, scripting, command, configuration, and troubleshooting guidance while preserving existing records.
{{indexmenu>.#1|js}}