.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DBI::Shell 3"
.TH DBI::Shell 3 "2020-08-20" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DBI::Shell \- Interactive command shell for the DBI
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& perl \-MDBI::Shell \-e shell [<DBI data source> [<user> [<password>]]]
.Ve
.PP
or
.PP
.Vb 3
\& dbish [<DBI data source> [<user> [<password>]]]
\& dbish \-\-debug [<DBI data source> [<user> [<password>]]]
\& dbish \-\-batch [<DBI data source> [<user> [<password>]]] < batch file
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The DBI::Shell module (and dbish command, if installed) provide a
simple but effective command line interface for the Perl \s-1DBI\s0 module.
.SH "TO DO"
.IX Header "TO DO"
Proper docs \- but not yet, too much is changing.
.PP
\&\*(L"source file\*(R" command to read command file.
Allow to nest via stack of command file handles.
Add command log facility to create batch files.
.PP
Commands:
.PP
Use Data::ShowTable if available.
.PP
Define DBI::Shell plug-in semantics.
Implement import/export as plug-in module
.PP
Clarify meaning of batch mode
.PP
Completion hooks
.PP
Set/Get \s-1DBI\s0 handle attributes
.PP
Portability
.PP
Emulate popular command shell modes (Oracle, Ingres etc)?
.SH "ARGUMENTS"
.IX Header "ARGUMENTS"
.IP "debug" 4
.IX Item "debug"
dbish \-\-debug enable debug messages
.IP "batch" 4
.IX Item "batch"
dbish \-\-batch < batch_file
.SH "COMMANDS"
.IX Header "COMMANDS"
Many commands \- few documented, yet!
.IP "help" 4
.IX Item "help"
.Vb 1
\& help
.Ve
.IP "chistory" 4
.IX Item "chistory"
.Vb 2
\& chistory (display history of all commands entered)
\& chistory | YourPager (display history with paging)
.Ve
.IP "clear" 4
.IX Item "clear"
.Vb 1
\& clear (Clears the current command buffer)
.Ve
.IP "commit" 4
.IX Item "commit"
.Vb 1
\& commit (commit changes to the database)
.Ve
.IP "connect" 4
.IX Item "connect"
.Vb 3
\& connect (pick from available drivers and sources)
\& connect dbi:Oracle (pick source from based on driver)
\& connect dbi:YourDriver:YourSource i.e. dbi:Oracle:mysid
.Ve
.Sp
Use this option to change userid or password.
.IP "count" 4
.IX Item "count"
.Vb 1
\& count table1 [...]
.Ve
.Sp
Run a select count(*) from table on each table listed with this command.
.IP "current" 4
.IX Item "current"
.Vb 1
\& current (Display current statement in the buffer)
.Ve
.IP "do" 4
.IX Item "do"
.Vb 1
\& do (execute the current (non\-select) statement)
\&
\& dbish> create table foo ( mykey integer )
\& dbish> /do
\&
\& dbish> truncate table OldTable /do (Oracle truncate)
.Ve
.IP "drivers" 4
.IX Item "drivers"
.Vb 1
\& drivers (Display available DBI drivers)
.Ve
.IP "edit" 4
.IX Item "edit"
.Vb 1
\& edit (Edit current statement in an external editor)
.Ve
.Sp
Editor is defined using the environment variable \f(CW$VISUAL\fR or
\&\f(CW$EDITOR\fR or default is vi. Use option editor=new editor to change
in the current session.
.Sp
To read a file from the operating system invoke the editor (edit)
and read the file into the editor buffer.
.IP "exit" 4
.IX Item "exit"
.Vb 1
\& exit (Exits the shell)
.Ve
.IP "get" 4
.IX Item "get"
.Vb 1
\& get Retrieve a previous command to the current buffer.
\&
\& get 1 Retrieve the 1 command executed into the current
\& buffer.
\&
\& get \-1 Retrieve the second to last command executed into
\& the current buffer.
.Ve
.IP "go" 4
.IX Item "go"
.Vb 1
\& go (Execute the current statement)
.Ve
.Sp
Run (execute) the statement in the current buffer. This is the default
action if the statement ends with /
.Sp
.Vb 1
\& dbish> select * from user_views/
\&
\& dbish> select table_name from user_tables
\& dbish> where table_name like \*(AqDSP%\*(Aq
\& dbish> /
\&
\& dbish> select table_name from all_tables/ | more
.Ve
.IP "history" 4
.IX Item "history"
.Vb 2
\& history (Display combined command and result history)
\& history | more
.Ve
.IP "load" 4
.IX Item "load"
.Vb 1
\& load file name (read contains of file into the current buffer)
.Ve
.Sp
The contains of the file is loaded as the current buffer.
.IP "option" 4
.IX Item "option"
.Vb 4
\& option [option1[=value]] [option2 ...]
\& option (Displays the current options)
\& option MyOption (Displays the value, if exists, of MyOption)
\& option MyOption=4 (defines and/or sets value for MyOption)
.Ve
.IP "perl" 4
.IX Item "perl"
.Vb 1
\& perl (Evaluate the current statement as perl code)
.Ve
.IP "quit" 4
.IX Item "quit"
.Vb 1
\& quit (quit shell. Same as exit)
.Ve
.IP "redo" 4
.IX Item "redo"
.Vb 1
\& redo (Re\-execute the previously executed statement)
.Ve
.IP "rhistory" 4
.IX Item "rhistory"
.Vb 1
\& rhistory (Display result history)
.Ve
.IP "rollback" 4
.IX Item "rollback"
.Vb 1
\& rollback (rollback changes to the database)
.Ve
.Sp
For this to be useful, turn the autocommit off. option autocommit=0
.IP "run" 4
.IX Item "run"
.Vb 1
\& run file name (load and execute a file.)
.Ve
.Sp
This commands load the file (may include full path) and executes. The
file is loaded (replaces) the current buffer. Only 1 statement per
file is allowed (at this time).
.IP "save" 4
.IX Item "save"
.Vb 1
\& save file name (write contains of current buffer to file.)
.Ve
.Sp
The contains of the current buffer is written to file. Currently,
this command will overwrite a file if it exists.
.IP "spool" 4
.IX Item "spool"
.Vb 4
\& spool file name (Starts sending all output to file name)
\& spool on (Starts sending all output to on.lst)
\& spool off (Stops sending output)
\& spool (Displays the status of spooling)
.Ve
.Sp
When spooling, everything seen in the command window is written to a file
(except some of the prompts).
.IP "table_info" 4
.IX Item "table_info"
.Vb 2
\& table_info (display all tables that exist in current database)
\& table_info | more (for paging)
.Ve
.IP "trace" 4
.IX Item "trace"
.Vb 1
\& trace (set DBI trace level for current database)
.Ve
.Sp
Adjust the trace level for \s-1DBI 0\s0 \- 4. 0 off. 4 lots of information.
Useful for determining what is really happening in \s-1DBI.\s0 See \s-1DBI.\s0
.IP "type_info" 4
.IX Item "type_info"
.Vb 1
\& type_info (display data types supported by current server)
.Ve
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
The configuration file (\fI~/.dbish_config\fR by default, overridden by
\&\f(CW$DBISH_CONFIG\fR) is eval'd as perl code and should return a hash ref
containing the configuration items. Notable keys include
.IP "options" 4
.IX Item "options"
The value is another hashref containing the options and their values.
Type \f(CW\*(C`/option\*(C'\fR at the prompt to get a list of acceptable options.
.IP "plug-ins" 4
.IX Item "plug-ins"
Plugins to load. This is a rather complex data structure which is
recursively walked to determine which plugins should be loaded. At the
top level, there are the phases
\&\f(CW\*(C`pre\-init\*(C'\fR, \f(CW\*(C`post\-init\*(C'\fR, \f(CW\*(C`pre\-connect\*(C'\fR, and \f(CW\*(C`post\-connect\*(C'\fR. At lower
levels plugins can be selected by the name of the database driver, and
individual options can be set. Finally, at some point an arrayref
containing the package names of the plugins to load must be found.
.PP
Since the config file can contain arbitrary perl code, it can do
anything which can be done in perl. One rather useful hack is to call
binmode to set the encoding for standard input and output.
.SS "Example"
.IX Subsection "Example"
.Vb 2
\& binmode STDIN, ":utf8";
\& binmode STDOUT, ":utf8";
\&
\& {
\& options => {
\& format => \*(Aqpartbox\*(Aq,
\& },
\& \*(Aqplug\-ins\*(Aq => {
\& \*(Aqpre\-init\*(Aq => [
\& \*(AqDBI::Shell::Timing\*(Aq,
\& \*(AqDBI::Shell::Spool\*(Aq,
\& ],
\& },
\& };
.Ve
.PP
This config file first sets the :utf8 layer for input and output to
match the terminal (if you don't use \s-1UTF\-8,\s0 you could use :\fBencoding()\fR
here), and then returns the hashref with the configuration items:
The format is set 'partbox', and the the two plugins
\&'DBI::Shell::Timing' and 'DBI::Shell::Spool' are loaded.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
.IP "\s-1DBISH_TMP\s0" 4
.IX Item "DBISH_TMP"
Where to write temporary files.
.IP "\s-1DBISH_CONFIG\s0" 4
.IX Item "DBISH_CONFIG"
Which configuration file used. Unset to not read any additional
configurations.
.SH "AUTHORS and ACKNOWLEDGEMENTS"
.IX Header "AUTHORS and ACKNOWLEDGEMENTS"
The DBI::Shell has a long lineage.
.PP
It started life around 1994\-1997 as the pmsql script written by Andreas
König. Jochen Wiedmann picked it up and ran with it (adding much along
the way) as \fIdbimon\fR, bundled with his DBD::mSQL driver modules. In
1998, around the time I wanted to bundle a shell with the \s-1DBI,\s0 Adam
Marks was working on a dbish modeled after the Sybase sqsh utility.
.PP
Wanting to start from a cleaner slate than the feature-full but complex
dbimon, I worked with Adam to create a fairly open modular and very
configurable DBI::Shell module. Along the way Tom Lowery chipped in
ideas and patches. As we go further along more useful code and concepts
from Jochen's dbimon is bound to find it's way back in.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
The DBI::Shell module is Copyright (c) 1998 Tim Bunce. England.
All rights reserved. Portions are Copyright by Jochen Wiedmann,
Adam Marks, Tom Lowery, Kent Fredric, Rafael Kitover and Mike Pomraning. It
is currently maintained by Dave Lambley.
.PP
You may distribute under the terms of either the \s-1GNU\s0 General Public
License or the Artistic License, as specified in the Perl \s-1README\s0 file.