sqlplus: Usage, Options & Common CI Errors

sqlplus runs SQL and PL/SQL against an Oracle Database from the shell.

sqlplus drives Oracle migrations and checks in CI. Failures speak in ORA- codes: no listener, invalid login, and the silent "did not exit" problem when a script lacks EXIT.

What it does

sqlplus connects to an Oracle Database using an Easy Connect string or a tnsnames alias and runs SQL/PL-SQL interactively or from an @script. In CI it targets an Oracle service container or remote instance.

Common usage

Terminal

sqlplus -S user/pass@//localhost:1521/XEPDB1 @migrate.sql
sqlplus -S system/oracle@//db:1521/FREEPDB1 <<'SQL'
SELECT 1 FROM dual;
EXIT;
SQL
sqlplus -L user/pass@//localhost:1521/XEPDB1   # do not re-prompt on fail

Options

Item	What it does
user/pass@//host:port/service	Easy Connect string
@<script>	Run a SQL script
-S / --silent	Suppress banners and prompts
-L	Attempt login once, do not re-prompt
EXIT / QUIT	Leave sqlplus (and set return code)
WHENEVER SQLERROR EXIT	Fail the script on the first error

Common errors in CI

ORA-12541: TNS:no listener - the listener/port is wrong or the database is not up; wait for the container and check host:port/service. "ORA-01017: invalid username/password; logon denied" is bad credentials. "ORA-12514: TNS:listener does not currently know of service requested" means the service/PDB name is wrong. A script without EXIT leaves sqlplus waiting on stdin and the job hangs - end scripts with EXIT and add WHENEVER SQLERROR EXIT FAILURE so SQL errors fail the step.