README for dbishell
-------------------

   --driver                 # DBIShell driver
   --dsn                    # dsn [The bit after 'dbi:<DRIVER>:' ]
   --user|u                 # database user name
   --pass|passwd|password|p # database password
   --help|h                 # print the help and exit
   --shell-driver           # real DBIShell driver to use if
                            # using driver=Proxy or driver=ODBC
   --dotdir                 # location of your dbishell dotfiles

All of these are implemented to some extent, some might be problematic...

1) Commands must be terminated with a trailing /
   Or, if you want to, you can configure it by setting the $EOL variable.
   No, it can't default to ';', that would cause problems w. dr::Oracle.
   So stop complaining already. [You know who you are]

2) Tab completion should be available. The mysql tab completer is reasonably
   smart, the Oracle one will be once I get some more work done on it.

3)Special variables:
	  
   $FIELD_SEPARATOR
   
   Contains the character sequence used to separate fields in output.
   If unset, you get '|' as the separator.
   
   $PRESCAN_FORMAT
   
   If true, [cf. Perl "What is truth"] then the whole of the dataset
   returned by all queries is prescanned, and the output formatted accordingly
   This can be helpful when you have large columns which typically hold
   values much shorter than they have the capacity for, since it shrinks
   the display columns down to the size of the largest output value on a per
   column basis. On the other hand, if you're fetching large numbers of rows,
   This may hurt, since you'll be prefetching the whole dataset into memory,
   scanning it, and then printing it. 
   
   $TRUNCATE_COLUMN_NAMES
   
   If false, a column will never be narrower than its name in the output.
   Othewise, column names will be shortened to fit their columns display
   widths [if PRESCAN_ROWS is set]
   
   $CASE_SENSITIVE
   
   Is the DB case sensitive or not? [mainly effects tab completion]
   
   $PAGER 
   
   The command to open a pipe to, to use as a pager. If $PAGER is unset,
   $env:PAGER is tried instead, and if there's nothing there, 'less -S'
   is used instead. If that doesn't work, then bad things probably 
   happen. Like paging not working, and maybe your output disappearing.
   
   $PAGING
   
   If this is true, then output from certain commands [just selects at 
   the moment] will be paged, depending on the value of $PAGE_SIZE and 
   $PRESCAN_FORMAT

   $PAGE_SIZE

   The number of rows above which dbishell will try to page output.
   Paging is decided as follows:

   If $PAGING is true, and $PRESCAN_FORMAT is true, output exceeding
   $PAGE_SIZE [or exceeding the size of the terminal, if $PAGE_SIZE
   is 0 or unset] will be paged.

   If $PRESCAN_FORMAT is false, and $PAGING is true, then output will 
   be paged regardless of the amount of data returned, unless the DBI 
   driver can determine the number of rows before they are all fetched.

   $EOL

   The end of line character used by dbishell to determine when you want
   a command executed. If unset [the default] then '/' is used.
   [except that the '/' that terminates a comment will be ignored].
   Otherwise, whatever you put in $EOL will be scanned for.

4) History:

   Command history is stored in ~/.dbishell/<driver>.history

5) Examples:

dbishell --driver Oracle --dsn host=foobar\;sid=argh        --user=scott
dbishell --driver mysql  --dsn host=narf\;database=argh     --user vivek
dbishell --driver Sybase --dsn hostname=narf\;database=argh --user=sa
dbishell --driver ODBC   --dsn FOO:  --shell-driver=Sybase  --user sa

6) DSN strings

dbishell and DBI have slightly different views of the meaning of the
term 'DSN'.

DBI expects a DSN in the following forms:

  dbi:DriverName:database_name
  dbi:DriverName:database_name@hostname
  dbi:DriverName:database_name~hostname!port
  dbi:DriverName:database=database_name;host=hostname;port=port

(examples from DBI man page).

dbishell requires you to specify the driver seperately, and the 
above examples would be handed as:

  database_name
  database_name@hostname
  database_name~hostname!port
  database_name;host=hostname;port=port

These strings would be arguments to the --dsn parameter, with the
actual database driver to use specified with --driver and --shell-driver.

The 'dbi' string is dropped, as it is implicit that if you are using
dbishell you are connecting to a dbi data source.

7) Help topics:

help
show
read
describe
interpolation
escaping
parameters
dbi_attr
environment
procedure_calls
logging
connect
disconnect
subshell
quit

Vivek Dasmohapatra <vivek@etla.org>