How to Use CSQL (CUBRID SQL Interpreter)

What is CSQL?

Definition of CSQL

To execute a SQL query in CUBRID, there are three tools:

CSQL Command Line SQL Interpreter
CUBRID Manager, Graphical User Interface based database administration tool.
CUBRID Query Browser, Graphical User Interface based database administration tool.

The CSQL Interpreter is the command line-based SQL Interpreter. It allows you to create a SQL query, retrieve execution result, and save the SQL query and its result into a file for later use. In addition, it can print the execution result or display it page by page on a screen. Thus:

Supports all terminal environments without X Windows
Can be used to enter, edit, and execute all CUBRID commands
Outputs the result to a file or screen

Connecting to a Database

The CSQL Interpreter allows to connect to both local and remote database hosts.

Connecting to a local database

The syntax used to connect to a local host in the command line using the CSQL Interpreter is shown below:

csql [options list] database_name

In other words, you can connect to the demodb database using CSQL by entering the followings in the shell prompt. (The demodb database is the default demo database installed automatically with CUBRID.)

> csql demodb

Connecting to a remote database

To connect to a remote database using the CSQL Interpreter, you need to enter the remote database information in the databases.txt configuration file located in the databases directory under the CUBRID installation directory (the environment variable which stores the location is $CUBRID_DATABASES).

vi $CUBRID_DATABASES/databases.txt
# local db information
demodb /home/cubrid/CUBRID/CUBRID_DATABASES/demodb DBHOST /home/cubrid/CUBRID/CUBRID_DATABASES/demodb
# remote db information
testdb /home/cubrid/CUBRID/CUBRID_DATABASES/testdb 192.168.1.1 /home/cubrid/CUBRID/CUBRID_DATABASES/testdb

Remember that the CUBRID version of a local database and that of a remote database must be the same.

The syntax used to connect to a remote host in the command line using the CSQL Interpreter is shown below, where testdb is the name of the remote database you indicated in the databases.txt file:

prompt csql -C testdb

Command-line options

The CSQL Interpreter allows to specify the following options:

Option	Description
-S	Executes the CSQL Interpreter in a standalone mode.
-C	Executes the CSQL Interpreter in a client/server mode.
-i input_file	Executes the CSQL Interpreter in a batch mode. The input_file parameter is the file name where SQL statements have been saved.
-o output_file	Saves a result of the statement execution in the specified output_file without displaying it on the screen.
-u user_name	Specifies the user that tries to access the database. The default value is public.
-p password	Specifies the password of the user who wants to access the database (if any).
-s	Executes multiple SQL statements saved consecutively in a file one by one. Multiple SQL statements must be separated by semicolons (;).
-c "CSQL commands"	Executes SQL statements directly from the prompt. To use this option, enclose the SQL statement to execute in double quotes.
-l	Displays the results of the SQL statement in a line format instead of a column. By default, the results will be displayed in a column format.
-e	Continues the query execution even when an error occurs.
--no-auto-commit	Sets the auto-commit mode of the CSQL Interpreter to OFF.
--no-pager	Displays the results of the query performed by the CSQL Interpreter at once instead of page-by-page.

You can see the option list when you enter 'csql' in the shell prompt as shown below:

C:\Users\me> csql
A database-name is missing.
interactive SQL utility, version R3.1
usage: csql.exe [OPTION] database-name

valid options:
  -S, --SA-mode                standalone mode execution
  -C, --CS-mode                client-server mode execution
  -u, --user=ARG               alternate user name
  -p, --pasword=ARG            password string, give "" for none
  -e, --error-continue         don't exit on statement error
  -i, --input-file=ARG         input-file-name
  -o, --output-file=ARG        output-file-name
  -s, --single-line            single line oriented execution
  -c, --command=ARG            CSQL-commands
  -l, --line-output            display each value in a line
  -r, --read-only              read-only mode
      --no-auto-commit         disable auto commit mode execution
      --no-pager               do not use pager

For addtional information, see http://www.cubrid.org

Options Usage Examples

Standalone mode -S

csql -S demodb

The above command means a database administrator wants to connect to the demodb database in a standalone mode. As a result no one except the current user will be allowed to connect to this database.

Line format -l

csql -S -l demodb

The -l option will tell CSQL to output the result of the SQL statement in a line format as shown below. If the -l option is omitted, the results will be displayed in a column format.

csql select * from code
csql ;x

=== Result of SELECT Command in Line 1===

00001s_name: 'X'
f_name: 'Mixed'
00002s_name: 'W'
f_name: 'Woman'
00003s_name: 'M'
f_name: 'Man'
00004s_name: 'B'
f_name: 'Bronze'
00005s_name: 'S'
f_name: 'Silver'
00006s_name: 'G'
f_name: 'Gold'


6 rows selected.

Current transaction has been committed.

1 command(s) successfully processed.
csql

Execute SQL statement in the shell -c

prompt csql -S -c "select * from code" demodb

The -c option will allow you to execute a SQL statement in the shell without connecting to the CSQL Interpreter.

Enter a SQL statement in double quotes when executing it directly in the shell.

csql -S -c "select * from code" demodb

=== Result of SELECT Command in Line 1 ===

s_name f_name
============================================
'X' 'Mixed'
'W' 'Woman'
'M' 'Man'
'B' 'Bronze'
'S' 'Silver'
'G' 'Gold'

Force SQL statement execution -e

prompt csql -S -e -i infile demodb

If you use the -e option, the next SQL statement is executed even when a semantic error or a runtime error occurs during the current SQL statement execution.

vi infile

select * from test_tb;
create table test_tb (n int);
insert into test_tb(m) values (10);
insert into test_tb(n) values (5);
select * from test_tb;

prompt csql -e -i infile demodb
In line 1, column 1,

ERROR: Unknown class "test_tb".


In line 3, column 23,

ERROR: m is not defined.


=== Result of SELECT Command in Line 5 ===

n
=============
5

CSQL Session Commands

Command Syntax

In addition to SQL statements, CSQL Interpreter provides special commands allowing you to control the Interpreter. These commands are called session commands. All the session commands must start with a semicolon (;). Enter the ';help' command in the CSQL Interpreter to display a list of the session commands available. Note that only the uppercase letters of each session command are required to make the CSQL Interpreter recognize it and not case sensitive.

csql ;help === Help: Session Command Summary ===
All session commands should be prefixed by `;' and only blanks/tabs
can precede the prefix. Capitalized characters represent the minimum
abbreviation that you need to enter to execute the specified command.
;REad [ file-name] - read a file into command buffer.
;Write [ file-name] - (over)write command buffer into a file.
;APpend [ file-name] - append command buffer into a file.
;PRINT - print command buffer.
;SHELL - invoke shell.
;CD - change current working directory.
;EXit - exit program.
;CLear - clear command buffer.
;EDIT - invoke system editor with command buffer.
;List - display the content of command buffer.
;RUn - execute sql in command buffer.
;Xrun - execute sql in command buffer,
and clear the command buffer.
;COmmit - commit the current transaction.
;ROllback - roll back the current transaction.
;AUtocommit [ON|OFF] - enable/disable auto commit mode.
;SHELL_Cmd [shell-cmd] - set default shell, editor, print and pager
;EDITOR_Cmd [editor-cmd] command to new one, or display the current
;PRINT_Cmd [print-cmd] one, respectively.
;PAger_cmd [pager-cmd]
;DATE - display the local time, date.
;DATAbase - display the name of database being accessed.
;SChema class-name - display schema information of a class.
;SYntax [sql-cmd-name] - display syntax of a command.
;TRigger [`*'|trigger-name] - display trigger definition.
;Get system_parameter - get the value of a system parameter.
;SEt system_parameter=value - set the value of a system parameter.
;Info command- display internal information.
;TIme [ON/OFF] - enable/disable to display the query
execution time.
;HISTORYList - display list of the executed queries.
;HISTORYRead history_num- read entry on the history number into command buffer
;HElp - display this help message.
csql

Commands

Command	Description
;RE ad file name	Reads the specified file into a buffer.
;W rite filename	Saves the contents of the buffer in the specified file name.
;A ppend filename	Appends the contents of the buffer into the specified file.
;L ist	Displays the contents of the buffer
;P rint	Prints the contents of the buffer.
;CL ear	Deletes the contents of the buffer.
;CD [dir_path]	Changes the current working directory to the specified directory.
;SHELL	Exits to the shell prompt.
;EX it	Exits CSQL.
;EDIT	Edits the contents of the buffer by using vi.
;RU n	Executes the SQL statement in the buffer. However, the contents of the buffer are not changed.
;X run	Executes the SQL statement in the buffer and also deletes the contents of the buffer.
;CO mmit	Commits current transaction to database.
;RO llback	Rolls back transactions up to now.
;AU tocommit [ON\|OFF]	Displays current Auto Commit mode. Auto Commit mode can be changed according to value of [ON\|OFF].
;DATA base	Displays database name that is being accessed.
;SHELL_C md [shell_cmd]	Displays current default shell. If you want to set up a new one, see "Setting up the SQL/X processor environment" manual.
;EDITOR_C md [print_cmd]	Sets up the editor that is used in ;edit command.
;PRINT_C md [print_cmd]	Displays current default printer. If you want to set up a new printer as a default, see "Setting up the SQL/X processor environment".
;PA ger_cmd [pager_cmd]	Displays current default page. If you want to set up a new one, see "Setting up the SQL/X processor environment" manual.
;SC hema [table_name]	Shows schema in the database. That is, the created table and its structure are displayed.
;TR igger ['*'\|trigger_name]	Displays the created trigger in the current database.
;SY ntax [csql_cmd_name]	Displays the grammar of SQL statement.
;G et system_parameter	Checks the defined parameter value.
;SE t system_parameter=value	Sets a parameter value. (However, you can set only client parameter value, not server parameters.)
;I nfo command	Displays the status of schema, trigger, deferred, workspace, lock, and stats.
;TI me [ON\|OFF]	Outputs query execution time.
;HISTORYL ist	This command displays the list that contains previously executed commands (input) and their history numbers.
;HISTORYR ead history_num	Moves input with the specified history number into the buffer.
;HE lp	Displays all of the CSQL session commands.

Basic Examples of Session Commands

Default Screen

When the CSQL is executed, the following information is displayed on the screen.

CUBRID SQL Interpreter


Type `;help' for help messages.

csql

Examples

You can use the read command, which reads an input file into a buffer, to check the contents of the input file. The list command displays the contents of a buffer and the edit command modifies the contents of a buffer.

csql ;re infile

The file has been read into the command buffer.
csql ;li 

1 select * from test_tb;
2 create table test_tb (n int);
3 insert into test_tb(m) values (10);
4 insert into test_tb(n) values (5);
5 select * from test_tb;

csql

First, create a table with the schema creation command. Just type the new schema information of the new table, once completed, type ;x and hit enter to execute the SQL statement you have just written. This will execute the SQL statement in the buffer and also deletes the contents of the buffer.

Then, use ';sc table_name' to check the details of the newly created table.

csql create table student
csql (
csql name varchar(10),
csql gender char(3),
csql phone varchar(20),
csql addr string
csql )
csql ;x

Current transaction has been committed.

1 command(s) successfully processed.

csql ;sc student

=== Help: Schema of a Class ===


Class Name

student

Attributes

name CHARACTER VARYING(10)
gender CHARACTER(3)
phone CHARACTER VARYING(20)
addr CHARACTER VARYING(1073741823)


Current transaction has been committed.
csql

Now insert the data. Type the SQL statement as shown below and execute it by using the ;r run command. Then search for the data.

csql insert into student (name, gender, phone, addr) values ('Gildong Hong', 'F', '111-2222', 'Seoul Gangnamgu Nonhyundong')
csql ;ru 

1 rows inserted.

Current transaction has been committed.

1 command(s) successfully processed.
csql ;cl 
csql select * from student
csql ;ru 

=== Result of SELECT Command in Line 1 ===

name gender phone addr

===========================================================================
Gildong Hong' 'F ' '111-2222' 'Seoul Gangnamgu Nonhyundong'


1 rows selected.

Current transaction has been committed.

1 command(s) successfully processed.
csql

If the -noac (no auto-commit) option was used when starting CSQL, all the transactions till now, e.g. entering, deleting, or changing schema or data, must be reflected on the database using the ;co (commit) or ;ro (rollback) command before termination. If you exit without reflecting the transactions on the database, the system will ask whether you want to reflect it or not.

csql -no-auto-commit demodb
csql insert into student(name,gender,phone,addr) values('Hani','F','333-9999',
csql 'Seoul Youngdeungpogu Yeoidodong')
csql ;ru

1 rows inserted.

1 command(s) successfully processed.
csql ;co

Current transaction has been committed.
csql ;exit

Display Query Plan

Optimization level

Query plan shows which index is used in a query and what type of join is used. A user can see the query plan by changing optimization level before query execution.

csql set optimization level 257
csql ;x

Current transaction has been committed.

1 command(s) successfully processed.
csql select name from student where gender='F'
csql ;x

Query plan: 

Sequential scan(student student) br
=== Result of SELECT Command in Line 1 ===

name
======================
Gildong Hong'
Hani'


2 rows selected.

Current transaction has been committed.

1 command(s) successfully processed.