NAME

yasql - Yet Another SQL*Plus replacement

SYNOPSIS

yasql [options] [connect_string]

connect_string
[username[/password]][@connection_descriptor]

options
-d debuglevel, --debug=debuglevel
Turn debuggin on to debuglevel level. Valid levels: 1,2,3,4

-H hostaddress, --host=hostaddress
Host to connect to

-p hostport, --port=hostport
Host port to connect to

-s SID, --sid=SID
Oracle SID to connect to

-h, -?, --help
Output usage information and quit.

-b, --bench, --benchmark
Turn on extended benchmark info, which includes times and CPU usages for both queries and formatting.

-A
Turn off the generation of the auto-completion list at startup. Use This if it takes too long to generate the list with a large database.

Examples
Connect to local database
yasql
yasql user
yasql user/password
yasql @LOCAL
yasql user@LOCAL
yasql user/password@LOCAL
yasql -h localhost
yasql -h localhost -p 1521
yasql -h localhost -p 1521 -s ORCL
Connect to remote host
yasql @REMOTE
yasql user@REMOTE
yasql user/password@REMOTE
yasql -h remote.domain.com
yasql -h remote.domain.com -p 1512
yasql -h remote.domain.com -p 1512 -s ORCL

If no connect_string or a hostaddress is given, then will attempt to connect to the local default database.

DESCRIPTION

YASQL is an open Oracle command line interface. YASQL features a much kinder alternative to SQL*Plus's user interface. This does not provide every feature that SQL*Plus does, only the ones needed for general ad hoc queries. The main intent of this program is for viewing data in the database, or testing queries. It is not intended to create fancy reports, such as those featured in SQL*Plus. It also does not have any sort of scripting language such as PL/SQL. It has a few native commands, such as describe, show, quit, and everything else is passed through to the Oracle server. The main things it provides are:

Full ReadLine support
Allows the same command line style editing as other ReadLine enabled programs such as BASH and the Perl Debugger. You can edit the command line as well as browse your command history. The command history is saved in your home directory in a file called .yasql_history. You can also use tab completion on all table and column names.

Alternate output methods
A different style of output suited to each type of need. There is currently a table and list output style. Table style outputs in the same manner as SQL*Plus, except the column widths are set based on the width of the data in the column, and not the column length defined in the table schema. List outputs each row on it's own line, column after column for easier viewing of wide return results.

Tab completion
All tables, columns, and other misc objects can be completed using tab, much like you can with bash.

Easy top row_num listings
You can easily put a number after a terminator, which will only output those number of lines. No more typing ``where row_num < 10'' after every query. Now you can type 'select * from table;10' instead.

Enhanced Data Dictionary commands
Special commands like 'show tables', 'desc <table>', 'show indexes on <table>', 'desc <sequence>', and many many more so that you can easily see your schema.

Query editing
You can open and edit queries in your favorite text editor.

Basic scripting
You can put basic SQL queries in a script and execute them from YASQL.

Config file
You can create a config file of options so that you don't have to set them everytime you run it.

Future extensibility
We, the community, can modify and add to this whatever we want, we can't do that with SQL*Plus.

REQUIREMENTS

Perl 5
This was developed with Perl 5.6, but is known to work on 5.005_03 and above. Any earlier version of Perl 5 may or may not work. Perl 4 will definately not work.

Unix environment
YASQL was developed under linux, and aimed at as many Unix installations as possible. Known to be compatible with RedHat Linux as well as Sun Solaris. Please send me an email (nshafer@ephibian.com) if it works for other platforms. I'd be especially interested if it worked on Win32.

DBD::Oracle
DBD::Oracle must be installed since this uses DBI for database connections.

Oracle client libraries
The Oracle client libraries must be installed for DBD::Oracle. Of course you can't install DBD::Oracle without them...

Term::Readline
Term::Readline must be installed (it is with most Perl installations), but more importantly, installing Term::Readline:Gnu from CPAN will greatly enhance the usability.

ORACLE_HOME
The ORACLE_HOME environment variable must be set if you use a connection descriptor to connect so that YASQL can translate the descriptor into usefull connection information to make the actual connection.

ORACLE_SID
The ORACLE_SID environment variable must be set unless you specify one with the -s option (see options above).

CONFIG

YASQL will look for a config file first in ~/.yasqlrc then /etc/yasql.conf. The following options are available:

connection_timeout = <seconds>
Timeout for connection attempts

Default: 20

max_connection_attempts = <num>
The amount of times to attempt the connection if the username/password are wrong

Default: 3

history_file = <file>
Where to save the history file. Shell metachars will be globbed (expanded)

Default: ~/.yasql_history

pager = <file>
Your favorite pager for extended output. (right now only the help command)

Default: /bin/more

AutoCommit = [0/1]
Autocommit any updates/inserts etc

Default: 0

CommitOnExit = [0/1]
Commit any pending transactions on exit. Errors or crashes will still cause the current transaction to rollback. But with this on a commit will occur when you explicitly exit.

Default: 0

LongTruncOk = [0/1]
Long truncation OK. If set to 1 then when a row contains a field that is set to a LONG time, such as BLOB, CLOB, etc will be truncated to LongReadLen length. If 0, then the row will be skipped and not outputted.

Default: 1

LongReadLen = <num_chars>
Long Read Length. This is the length of characters to truncate to if LongTruncOk is on

Default: 80

edit_history = [0/1]
Whether or not to put the query edited from the 'edit' command into the command history.

Default: 1

auto_complete = [0/1]
Whether or not to generate the autocompletion list on connection. If connecting to a large database (in number of tables/columns sense), the generation process could take a bit. For most databases it shouldn't take long at all though.

Default: 1

extended_benchmarks = [0/1]
Whether or not to include extended benchmarking info after queries. Will include both execution times and CPU loads for both the query and formatting parts of the process.

Default: 0

column_wildcards = [0/1]
Column wildcards is an extremely experimental feature that is still being hashed out due to the complex nature of it. This should affect only select statements and expands any wildcards (*) in the column list. such as 'select col* from table;'.

Default: 0

extended_tab_list = [0/1]
extended tab list will cause the possible matches list to be filled by basicly any and all objects. With it off the tab list will be restricted to only tables, columns, and objects owned by the current user.

Default: 0

AUTHOR

Written by Nathan Shafer (nshafer@ephibian.com) with support from Ephibian, Inc. http://www.ephibian.com

THANKS

Thanks to everyone at Ephibian that helped with testing, and a special thanks to Tom Renfro at Ephibian who did a lot of testing and found quite a few doozies.

The following people have also contributed to help make YASQL what it is: Allan Peda Lance Klein

COPYRIGHT

Copyright (C) 2000 Ephibian, Inc.

LICENSE

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

TODO

When the given terminal type is not in the termcap readline will die with a nasty error message. Possibly try to catch it before, or even specify a default term-type (vt100).
Add smarter tables and wrapping in columns. Also add configurable max column widths and max table width.
Add a curses interface option for easy viewing and scrolling, etc. This will require some research to determine if it's even worth it.
Add HTML and CSV output options
Add support for MySQL and PostgreSQL

CHANGELOG

$Log: yasql,v $ Revision 1.63 2001/03/01 17:30:26 nshafer Refined the ctrl-c process for not-so-linuxy OS's, namely solaris. Now stripping out Dos carriage returns since SQL*Plus seems to.

Revision 1.62 2001/02/26 22:39:12 nshafer Fixed bug where prompt would reset itself when a blank line was entered. Added script argument on command line (Lance Klein) Added support for any command line commands in the script (Lance Klein) The 'desc' and 'show' commands no longer require a terminator (like ;) as long as the whole statement is on one line (Lance Klein) Added option 'extended_tab_list' for a much bigger, more complete tab listing (Lance Klein) The edit command is no longer limited to 1 query at a time. You can now put any valid command or query, and as many of them as you want. The parsing rules for the edit command is exactly identical to the script parsing. cleaned up documentation a bit

Revision 1.61 2001/01/31 19:56:22 nshafer changed CommitOnExit to be 1 by default, to emulate SQL*Plus behavior, and at popular request

Revision 1.60 2001/01/29 16:38:17 nshafer got rid of (tm)

Revision 1.59 2001/01/29 16:28:22 nshafer Modified docs a little with the new scope of open source now in the mix.

Revision 1.58 2001/01/24 15:27:00 nshafer cleanup_after_signals is not in the Term::ReadLine::Stub, so it would output error messages on systems without Term::ReadLine::Gnu. Fixed

Revision 1.57 2001/01/17 23:26:53 nshafer Added Tom Renfro's column_wildcard expansion code. New conf variable: column_wildcards. 0 by default until this code is expanded on a bit more.

Revision 1.56 2001/01/17 23:00:25 nshafer Added CommitOnExit config, 0 by default. Added info output at startup and when a new connection is initiated about the state of AutoCommit and CommitOnExit. Also added statement about explicit rollback or commit when disconnecting. Added warning message to commit_cmd and rollback_cmd if AutoCommit is on. Now explicitly committing or rolling back on disconnect, it is no longer left up to the DBI's discretion... except in abnormal termination.

Revision 1.55 2001/01/11 18:05:12 nshafer Added trap for regex errors in tab completion (like if you put 'blah[' then hit tab)

Revision 1.54 2001/01/10 17:07:22 nshafer added output to those last 2 commands

Revision 1.53 2001/01/10 17:03:58 nshafer added commit and rollback commands so that you don't have to send them to the backend

Revision 1.52 2001/01/10 16:00:08 nshafer fixed bug with prompt where on each call get_prompt would add another '@'. Thanks Tom

Revision 1.51 2001/01/09 21:16:12 nshafer dar... fixed another bug where the %H would stay if there was no prompt_host

Revision 1.50 2001/01/09 21:12:13 nshafer fixed bug with that last update. Now it only interpolates the %H variable if there is something to interpolate it with

Revision 1.49 2001/01/09 21:09:56 nshafer changed the %H variable to be prefixed with a @

Revision 1.48 2001/01/09 21:04:36 nshafer changed 'default' to '' for the prompt's hostname when no connect_string is used

Revision 1.47 2001/01/09 20:55:11 nshafer added configurable prompt and changed the default prompt

Revision 1.46 2001/01/09 18:50:50 nshafer updated todo list

Revision 1.45 2001/01/09 18:32:35 nshafer Added 'connect <connect_string>' command. I may add the ability to specify options like on the command line (like '-H blah.com')

Revision 1.44 2001/01/08 22:08:49 nshafer more documentation changes

Revision 1.43 2001/01/08 20:51:31 nshafer added some documentation

Revision 1.42 2001/01/08 20:09:35 nshafer Added debug and autocommit commands

Revision 1.41 2001/01/08 18:12:43 nshafer added END handler to hopefully clean up the terminal better

Revision 1.40 2001/01/05 23:29:38 nshafer new name!

Revision 1.39 2001/01/05 18:00:16 nshafer Added config file options for auto completion generation and extended benchmark info

Revision 1.38 2001/01/05 16:39:47 nshafer Fixed error where calling edit a second time would not open the file properly because of the way glob() works.

Revision 1.37 2001/01/04 23:52:30 nshafer changed the version string to parse it out of the revision string (duh...) moved the prompting of username and password so that the check for the oracle_home variable happens before. Before if you didn't have the environment variable set then it will prompt you for username and password, then die with the error, which is annoying fixed the quit calls so taht they properly erase the quit line from the history. I had broken this a long time ago when I added the exit status param to the quit function Outputting in full table format (';' terminator) with a num_rows number (like ';100') would still cause the entire result set to be pulled into memory, which was really slow and could take a lot of memory if the table was large. Fixed it so that it only pulls in num_rows number of rows when using the digit option

Revision 1.36 2000/12/22 22:12:18 nshafer fixed a wrong-quote-type in the debug messages

Revision 1.35 2000/12/22 22:07:06 nshafer forgot version... you know the drill...

Revision 1.34 2000/12/22 21:57:01 nshafer Added config file support, queries from the 'edit' command are now entered into the command history (configurable), cleaned up the SIGINT actions quite a bit so they should work better now, added LongReadLen and LongTruncOk options so that LONG columns types won't mess up, added the number after terminator feature to limit how many rows are returned.

Revision 1.33 2000/12/20 22:56:03 nshafer version number.... again.... sigh

Revision 1.32 2000/12/20 22:55:32 nshafer added todo item, now in rpms

Revision 1.31 2000/12/20 17:07:52 nshafer added the reprompt for username/password on error 1005 null password given

Revision 1.30 2000/12/20 17:04:18 nshafer Refined the shadow_redisplay stuff. Now I will only use my builtin function if the terminal type is set to ``xterm'' because that terminal type has a broken termcap entry. Also set it to not echo when entering password if Term::ReadLine::Gnu is not installed

Revision 1.29 2000/12/20 15:47:56 nshafer trying a new scheme for the shadow_redisplay. Clear to EOL wasn't working Also fixed a few problems in the documentation .,

Revision 1.28 2000/12/19 23:55:03 nshafer I need to stop forgetting the revision number...

Revision 1.27 2000/12/19 23:48:49 nshafer cleaned up debugging

Revision 1.26 2000/12/19 23:10:18 nshafer Lotsa new stuff... tab completion of table, column, and object names, improved signal handling, the edit command now accepts a filename parameter, new command 'show processes' which shows you info on who's connected, improved benchmark info, and a lot of other cleanup/tweaks

Revision 1.25 2000/12/13 16:58:26 nshafer oops forgot documentation again

Revision 1.24 2000/12/13 16:54:42 nshafer added desc <trigger>

Revision 1.23 2000/12/12 17:52:15 nshafer updated todo list (oops, forgot)

Revision 1.22 2000/12/12 17:51:39 nshafer added desc <index>

Revision 1.21 2000/12/12 17:15:28 nshafer fixed bug when connecting using a host string (-H option) added a few more types to the 'show' and 'desc' commands

Revision 1.20 2000/12/08 22:13:43 nshafer many little fixes and tweaks here and there

Revision 1.19 2000/12/06 20:50:03 nshafer added scripting ability with ``@<filename>'' command changed all tabs to spaces!

Revision 1.18 2000/12/06 19:30:38 nshafer added clear command refined connection process. if invalid username/password entered then prompt again

Revision 1.17 2000/12/05 22:20:58 nshafer Tightened up outputs. Doesn't show column names if no rows selected, if it's not a select, then show number of rows affected

Revision 1.16 2000/12/04 18:04:53 nshafer *** empty log message ***

Revision 1.15 2000/12/04 18:03:14 nshafer fixed bug where the -H option was interpreted as -h or help. All command line options are now case sensitive

Revision 1.14 2000/12/04 17:54:38 nshafer Added list command (and \l and l)

Revision 1.13 2000/12/04 17:34:18 nshafer fixed a formatting issue if Time::HiRes isn't installed

Revision 1.12 2000/12/04 17:29:41 nshafer Added benchmark options to view the extended benchmark info. Now it displays just the time in a more friendly format. The old style is only active if the benchmark option is specified. Cleaned up some formatting issues Brought the usage and POD documentation up to date Added some items to the TODO

Revision 1.11 2000/11/30 22:54:38 nshafer Fixed bug with the edit command where if you were 'inquotes' then you would stay in quotes even after editing the file

Revision 1.10 2000/11/30 22:01:38 nshafer Fixed bug where username and password were added to the command history. Set it so that the quit commands are not added to the command history either. Added the 'edit' command and modified it's todo list item, as well as added it to the 'help' command

Revision 1.9 2000/11/29 17:55:35 nshafer changed version from .21 to 1.0 beta 9. I'll follow the revision numbers now

Revision 1.8 2000/11/29 17:46:31 nshafer added a few items to the todo list

Revision 1.7 2000/11/29 15:50:56 nshafer got rid of SID output at startup

Revision 1.6 2000/11/29 15:49:51 nshafer moved revision info to $revision and added Id output

Revision 1.5 2000/11/29 15:46:41 nshafer fixed revision number

Revision 1.4 2000/11/29 15:44:23 nshafer fixed issue where environment variable ORACLE_SID overwrote explicit set on the command line. now whatever you put on the command line will overwrite the environment variable