SQL*Plus

Oracle Database에 접속해 SQL, PL/SQL, SQL*Plus command와 script를 실행하는 command-line client다. 전체 Oracle Database Client 또는 가벼운 Oracle Instant Client의 SQL*Plus package로 제공된다.

• 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에서 입력한다.

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 2|3</color>: 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

<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 현재 base environment에는 sqlplus가 설치되어 있지 않아 live sqlplus -help output을 수집하지 않았다. 설치된 target version에서 실행한 원문으로 이 block을 보강한다. ++

• SQL*Plus configuration
• Oracle SQL
• Oracle Database
• Oracle SQL*Plus User's Guide and Reference
• Starting SQL*Plus
• Oracle Instant Client

• codex:: 2026-08-13 Migrated the legacy page and expanded installation, secure connection, scripting, command, configuration, and troubleshooting guidance while preserving existing records.