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.66 2001/03/13 21:34:58 nshafer There are no
    longer any references to termcap, so yasql should now work on
    termcap-less systems such as Debian Linux and AIX

    Revision 1.65 2001/03/12 17:44:31 nshafer Restoring the terminal is
    hopefully more robust and better now. YASQL now tries to use the 'stty'
    program to dump the settings of the terminal on startup so that it can
    restore it back to those settings. It requires that stty is installed in
    the path, but that should be the case with most systems. Also made the
    output of the query in the error message an option that is off by
    default. I had never meant to include that in the final release, but
    kept on forgetting to take it out.

    Revision 1.64 2001/03/06 16:00:33 nshafer Fixed bug where desc would
    match anytime, even in middle of query, which is bad.

    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

