├── LICENSE
└── README.md


/LICENSE:
--------------------------------------------------------------------------------
 1 | The MIT License (MIT)
 2 | 
 3 | Copyright (c) 2016 Unofficial Oracle Database Documentation
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # SQLcl
  2 | 
  3 | * [Intro](#intro)
  4 | * [Commands](#commands)
  5 | * [Scripting](#scripting)
  6 | * Advanced usage
  7 | 
  8 | ## Intro
  9 | 
 10 | What is SQLcl? From their own web portal:
 11 | 
 12 | > Oracle SQLcl is a free command line interface for Oracle Database. It allows you to interactively or batch execute it's own commands alongside with SQL, PL/SQL, operating system commands, and JavaScript. SQLcl offers a feature-rich experience in a shell environment, while also supporting all of the previous scripts our customers have developed for their Oracle environments..
 13 | 
 14 | Whilst SQL*Plus is still around, no new features have been added in a while. SQLcl aims to bridge the divide. The purpose of this project is to provide some high level documentation in lieu of any current official documentation - currently, there is a lot of content out there - but most of it is located in blog posts, so this should provide a single point of reference.
 15 | 
 16 | New commands that have been made available can be identified with the help command. Any new commands (new, as in, not available in SQL*Plus) will be styled with bold and underline when running the `help` command. They currently include:
 17 | 
 18 | * ALIAS
 19 | * APEX
 20 | * BRIDGE
 21 | * CD
 22 | * CTAS
 23 | * [DDL](#ddl)
 24 | * FORMAT
 25 | * HISTORY
 26 | * INFORMATION
 27 | * LOAD
 28 | * NET
 29 | * NOHISTORY
 30 | * OERR
 31 | * REPEAT
 32 | * REST
 33 | * SCRIPT
 34 | * SODA
 35 | * SSHTUNNEL
 36 | * TNSPING
 37 | 
 38 | You can get more help on each command by typing `help <cmd>`, which will provide a basic overview of the command.
 39 | 
 40 | One of the great new features is the ability to run SQLcl commands through a script. Typically, the scripting language would be JavaScript - but SQLcl is Java based, so any language that can be run in Java will be supported.
 41 | 
 42 | ## Commands
 43 | 
 44 | ### DDL
 45 | 
 46 | DDL can be used to pull the DDL for any database object that is available to the connected user. The syntax is `DDL [<object_name> [<type>] [SAVE <filename>]]`
 47 | 
 48 | So, as a basic example - if we connect to `HR` we can generate the DDL for our employees table with `DDL employees`. We could additionally specify it's a table: `DDL employees table`. Or if we want to save it to a file (avoiding spools), `DDL employees save emp.sql`.
 49 | 
 50 | If you run this as is, you will notice that all the storage options are included. This is all configurable. If you run the command `ddl options` you will see what's available to be set:
 51 | 
 52 | ```sql
 53 | SQL> show ddl
 54 | STORAGE : ON
 55 | INHERIT : ON
 56 | SQLTERMINATOR : ON
 57 | OID : ON
 58 | SPECIFICATION : ON
 59 | TABLESPACE : ON
 60 | SIZE_BYTE_KEYWORD : ON
 61 | PRETTY : ON
 62 | REF_CONSTRAINTS : ON
 63 | FORCE : ON
 64 | PARTITIONING : ON
 65 | CONSTRAINTS : ON
 66 | INSERT : ON
 67 | BODY : ON
 68 | CONSTRAINTS_AS_ALTER : ON
 69 | SEGMENT_ATTRIBUTES : ON
 70 | ```
 71 | 
 72 | So, we can turn any of these options off with: `set ddl <option> <value>`. So, if we turn storage off with: `set ddl storage off`, we will have our DDL without storage. Other ones I like to turn off are `tablespace` and `segment_attributes`.
 73 | 
 74 | ```sql
 75 | set ddl storage off
 76 | set ddl tablespace off
 77 | set ddl segment_attributes off
 78 | 
 79 | ddl employees
 80 | ```
 81 | 
 82 | The documentation states the `type` field is only used for materialized views. I've had success specifying the type for other object types, however not when used with the save option. For this, you may need to make use of spooling. e.g.
 83 | 
 84 | ```
 85 | SQL> spool foo.sql
 86 | SQL> ddl foo package
 87 |   CREATE OR REPLACE PACKAGE "HR"."FOO"
 88 | as
 89 |     lc_bar NUMBER := 1001;
 90 | end foo;
 91 | /
 92 | SQL> spool off
 93 | SQL> !ls | grep foo
 94 | foo.sql
 95 | 
 96 | SQL> !cat foo.sql
 97 |   CREATE OR REPLACE PACKAGE "HR"."FOO"
 98 | as
 99 |     lc_bar NUMBER := 1001;
100 | end foo;
101 | /
102 | SQL> spool off
103 | ```
104 | 
105 | ### Information
106 | 
107 | The information command expands on the desc command. The desc command provides an overview of all the columns in a table, where info will go one step further and list all table indexes and constraints. If you post fix the command with a `+` you will also get the column statistics.
108 | 
109 | ```
110 | SQL> desc employees
111 | Name           Null?    Type         
112 | -------------- -------- ------------
113 | EMPLOYEE_ID    NOT NULL NUMBER(6)    
114 | FIRST_NAME              VARCHAR2(20)
115 | LAST_NAME      NOT NULL VARCHAR2(25)
116 | EMAIL          NOT NULL VARCHAR2(25)
117 | PHONE_NUMBER            VARCHAR2(20)
118 | HIRE_DATE      NOT NULL DATE         
119 | JOB_ID         NOT NULL VARCHAR2(10)
120 | SALARY                  NUMBER(8,2)  
121 | COMMISSION_PCT          NUMBER(2,2)  
122 | MANAGER_ID              NUMBER(6)    
123 | DEPARTMENT_ID           NUMBER(4)    
124 | SQL>
125 | SQL> info employees
126 | Columns
127 | NAME             DATA TYPE           NULL  DEFAULT    COMMENTS
128 | *EMPLOYEE_ID     NUMBER(6,0)         No                   Primary key of employees table.
129 |  FIRST_NAME      VARCHAR2(20 BYTE)   Yes                  First name of the employee. A not null column.
130 |  LAST_NAME       VARCHAR2(25 BYTE)   No                   Last name of the employee. A not null column.
131 |  EMAIL           VARCHAR2(25 BYTE)   No                   Email id of the employee
132 |  PHONE_NUMBER    VARCHAR2(20 BYTE)   Yes                  Phone number of the employee; includes country code and area code
133 |  HIRE_DATE       DATE                No                   Date when the employee started on this job. A not null column.
134 |  JOB_ID          VARCHAR2(10 BYTE)   No                   Current job of the employee; foreign key to job_id column of the
135 |                                                                     jobs table. A not null column.
136 |  SALARY          NUMBER(8,2)         Yes                  Monthly salary of the employee. Must be greater
137 |                                                                     than zero (enforced by constraint emp_salary_min)
138 |  COMMISSION_PCT  NUMBER(2,2)         Yes                  Commission percentage of the employee; Only employees in sales
139 |                                                                     department elgible for commission percentage
140 |  MANAGER_ID      NUMBER(6,0)         Yes                  Manager id of the employee; has same domain as manager_id in
141 |                                                                     departments table. Foreign key to employee_id column of employees table.
142 |                                                                     (useful for reflexive joins and CONNECT BY query)
143 |  DEPARTMENT_ID   NUMBER(4,0)         Yes                  Department id where employee works; foreign key to department_id
144 |                                                                     column of the departments table
145 | 
146 | Indexes
147 | INDEX_NAME            UNIQUENESS  STATUS  FUNCIDX_STATUS  COLUMNS                COLUMN_EXPRESSION  
148 | HR.EMP_JOB_IX         NONUNIQUE   VALID                   JOB_ID                                    
149 | HR.EMP_NAME_IX        NONUNIQUE   VALID                   LAST_NAME, FIRST_NAME                     
150 | HR.EMP_EMAIL_UK       UNIQUE      VALID                   EMAIL                                     
151 | HR.EMP_EMP_ID_PK      UNIQUE      VALID                   EMPLOYEE_ID                               
152 | HR.EMP_MANAGER_IX     NONUNIQUE   VALID                   MANAGER_ID                                
153 | HR.EMP_DEPARTMENT_IX  NONUNIQUE   VALID                   DEPARTMENT_ID                             
154 | 
155 | 
156 | References
157 | TABLE_NAME   CONSTRAINT_NAME  DELETE_RULE  STATUS   DEFERRABLE      VALIDATED  GENERATED  
158 | DEPARTMENTS  DEPT_MGR_FK      NO ACTION    ENABLED  NOT DEFERRABLE  VALIDATED  USER NAME  
159 | EMPLOYEES    EMP_MANAGER_FK   NO ACTION    ENABLED  NOT DEFERRABLE  VALIDATED  USER NAME  
160 | JOB_HISTORY  JHIST_EMP_FK     NO ACTION    ENABLED  NOT DEFERRABLE  VALIDATED  USER NAME  
161 | 
162 | SQL>
163 | ```
164 | 
165 | ### Loading data
166 | 
167 | The load command allows you to load data from a CSV file.
168 | 
169 | ## Scripting
170 | 
171 | You could build scripts to run particiular SQLcl commands, which can be run in any language that can be run through the JVM (See JSR-232). This will most typically be with JavaScipt. To run a script you have developed, you just prefix the script filename with `script`. So, if I have a script called `demo.js` I would run `script demo` (not, leaving off the file prefix assumed javascript).
172 | 
173 | ## Advanced usage
174 | 
175 | ### Pre and post commands
176 | 
177 | You can set up a script to run before and after every command/script you run. This is done with `set precommand|postcommand <script|command>`.
178 | 
179 | ```
180 | SQL> set precommand select 'begin' start_msg from dual
181 | SQL> set postcommand select 'end' end_msg from dual
182 | SQL> select count(1) from employees;
183 | 
184 | START
185 | -----
186 | begin
187 | 
188 | 
189 |   COUNT(1)
190 | ----------
191 |        107
192 | 
193 | 
194 | END
195 | ---
196 | end
197 | ```
198 | 
199 | ### Output formats
200 | 
201 | You can easily display query data in a number of different formats:
202 | 
203 | * csv
204 | * html
205 | * xml
206 | * json
207 | * ansiconsole
208 | * insert
209 | * loader
210 | * fixed
211 | * default
212 | 
213 | To change the active output format, you just run: `set sqlformat <format>`. For example, to output the data in CSV, you can run:
214 | 
215 | ```
216 | SQL> help set sqlformat
217 | SET SQLFORMAT
218 |   SET SQLFORMAT { csv,html,xml,json,ansiconsole,insert,loader,fixed,default}   
219 | 
220 | SQL> set sqlformat csv
221 | SQL> select * from departments;
222 | "DEPARTMENT_ID","DEPARTMENT_NAME","MANAGER_ID","LOCATION_ID"
223 | 10,"Administration",200,1700
224 | 20,"Marketing",201,1800
225 | 30,"Purchasing",114,1700
226 | 40,"Human Resources",203,2400
227 | 50,"Shipping",121,1500
228 | --output ommitted
229 | 
230 | 27 rows selected.
231 | 
232 | SQL>
233 | ```
234 | 
235 | double check this:
236 | An additional argument can also be specified if you want to specify a default number format when querying data.
237 | 
238 | todo: `set sqlformat [num format]`
239 | source: http://krisrice.blogspot.com.au/2015/10/sqlcl-oct-5th-edition.html
240 | 
241 | ### History
242 | 
243 | History is self explanatory - it shows a list of recently run operations. It comes with a list of extra opererations, so it is run with: `history <command>`, where command is one of:
244 | 
245 | * time - time to run the operation
246 | * usage - the number of times a comamnd has been run
247 | * script
248 | * full
249 | * clear
250 | * fails
251 | 
252 | Or, instead of the command, you can pass in index to output the entry from the history in that index location.
253 | 
254 | ### Connection strings
255 | 
256 | Typically to connect, you would pass in a string such as: `user/pass@//server:port/sid`. With SQLcl you can pass in various jdbc connection strings.
257 | 
258 | * jdbc:oracle:thin
259 | * jdbc:oracle:oci8
260 | * jdbc:oracle:kprb
261 | * jdbc:default:connection
262 | * jdbc:oracle:kprb:
263 | * jdbc:default:connection:
264 | 
265 | So, with that, we could use the connection string: `user/pass@jdbc:oracle:thin:@server:port/sid`
266 | 
267 | Source: http://krisrice.blogspot.com.au/2015/10/sqlcl-oct-5th-edition.html
268 | 


--------------------------------------------------------------------------------