.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 "Easy 3pm"
.TH Easy 3pm 2024-03-24 "perl v5.38.2" "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
DBIx::Easy \- Easy to Use DBI interface
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&  use DBIx::Easy;
\&  my $dbi_interface = new DBIx::Easy qw(Pg template1);
\&
\&  $dbi_interface \-> insert (\*(Aqtransaction\*(Aq,
\&                   id => serial (\*(Aqtransaction\*(Aq, \*(Aqtransactionid\*(Aq),
\&                   time => \e$dbi_interface \-> now);
\&
\&  $dbi_interface \-> update (\*(Aqcomponents\*(Aq, "table=\*(Aqram\*(Aq", price => 100);
\&  $rows_deleted = $dbi_interface \-> delete (\*(Aqcomponents\*(Aq, \*(Aqstock = 0\*(Aq);
\&  $dbi_interface \-> makemap (\*(Aqcomponents\*(Aq, \*(Aqid\*(Aq, \*(Aqprice\*(Aq, \*(Aqprice > 10\*(Aq);
\&  $components = $dbi_interface \-> rows (\*(Aqcomponents\*(Aq);
\&  $components_needed = $dbi_interface \-> rows (\*(Aqcomponents\*(Aq, \*(Aqstock = 0\*(Aq);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
DBIx::Easy is an easy to use DBI interface.
Currently the Pg, mSQL, mysql, Sybase, ODBC and XBase drivers are supported.
.SH "CREATING A NEW DBI INTERFACE OBJECT"
.IX Header "CREATING A NEW DBI INTERFACE OBJECT"
.Vb 5
\&  $dbi_interface = new DBIx::Easy qw(Pg template1);
\&  $dbi_interface = new DBIx::Easy qw(Pg template1 racke);
\&  $dbi_interface = new DBIx::Easy qw(Pg template1 racke aF3xD4_i);
\&  $dbi_interface = new DBIx::Easy qw(Pg template1 racke@linuxia.de aF3xD4_i);
\&  $dbi_interface = new DBIx::Easy qw(Pg template1 racke@linuxia.de:3306 aF3xD4_i);
.Ve
.PP
The required parameters are the database driver
and the database name. Additional parameters are the database user
and the password to access the database. To specify the database host
use the USER@HOST notation for the user parameter. If you want to specify the
port to connect to use USER@HOST:PORT.
.SH "DESTROYING A DBI INTERFACE OBJECT"
.IX Header "DESTROYING A DBI INTERFACE OBJECT"
It is important that you commit all changes at the end of the interaction
with the DBMS. You can either explicitly commit
.PP
.Vb 1
\&  $dbi_interface \-> commit ();
.Ve
.PP
or do it implicitly:
.PP
.Vb 1
\&  undef $dbi_interface;
.Ve
.SH "ERROR HANDLING"
.IX Header "ERROR HANDLING"
.Vb 5
\&  sub fatal {
\&    my ($statement, $err, $msg) = @_;
\&    die ("$0: Statement \e"$statement\e" failed (ERRNO: $err, ERRMSG: $msg)\en");
\&  }
\&  $dbi_interface \-> install_handler (\e&fatal);
.Ve
.PP
If any of the DBI methods fails, either \fIdie\fR will be invoked
or an error handler installed with \fIinstall_handler\fR will be
called.
.SH "CACHING ISSUES"
.IX Header "CACHING ISSUES"
By default, this module caches table structures. This can be
disabled by setting \fR\f(CI$DBIx::Easy::cache_structs\fR\fI\fR to 0.
.SH "XBASE DRIVER"
.IX Header "XBASE DRIVER"
The DBIx::Easy method rows fails to work with the DBD::XBase driver.
.SH METHODS
.IX Header "METHODS"
.SS "DATABASE ACCESS"
.IX Subsection "DATABASE ACCESS"
.IP "process \fIstatement\fR" 4
.IX Item "process statement"
.Vb 2
\&  $sth = $dbi_interface \-> process ("SELECT * FROM foo");
\&  print "Table foo contains ", $sth \-> rows, " rows.\en";
.Ve
.Sp
Processes \fIstatement\fR by just combining the \fIprepare\fR and \fIexecute\fR
steps of the DBI. Returns statement handle in case of success.
.IP "insert \fItable\fR \fIcolumn\fR \fIvalue\fR [\fIcolumn\fR \fIvalue\fR] ..." 4
.IX Item "insert table column value [column value] ..."
.Vb 1
\&  $sth = $dbi_interface \-> insert (\*(Aqbar\*(Aq, drink => \*(AqCaipirinha\*(Aq);
.Ve
.Sp
Inserts the given \fIcolumn\fR/\fIvalue\fR pairs into \fItable\fR. Determines from the
SQL data type which values has to been quoted. Just pass a reference to
the value to protect values with SQL functions from quoting.
.IP "update \fItable\fR \fIconditions\fR \fIcolumn\fR \fIvalue\fR [\fIcolumn\fR \fIvalue\fR] ..." 4
.IX Item "update table conditions column value [column value] ..."
.Vb 2
\&  $dbi_interface \-> update (\*(Aqcomponents\*(Aq, "table=\*(Aqram\*(Aq", price => 100);
\&  $dbi_interface \-> update (\*(Aqcomponents\*(Aq, "table=\*(Aqram\*(Aq", price => \e"price + 20");
.Ve
.Sp
Updates any row of \fItable\fR which fulfill the \fIconditions\fR by inserting the given \fIcolumn\fR/\fIvalue\fR pairs. Scalar references can be used to embed strings without further quoting into the resulting SQL statement. Returns the number of rows modified.
.IP "put \fItable\fR \fIconditions\fR \fIcolumn\fR \fIvalue\fR [\fIcolumn\fR \fIvalue\fR] ..." 4
.IX Item "put table conditions column value [column value] ..."
.PD 0
.IP "delete \fItable\fR \fIconditions\fR" 4
.IX Item "delete table conditions"
.PD
.Vb 1
\&  $dbi_interface \-> delete (\*(Aqcomponents\*(Aq, "stock=0");
.Ve
.Sp
Deletes any row of \fItable\fR which fulfill the \fIconditions\fR. Without conditions
all rows are deleted. Returns the number of rows deleted.
.IP "do_without_transaction \fIstatement\fR" 4
.IX Item "do_without_transaction statement"
.Vb 1
\&  $sth = $dbi_interface \-> do_without_transaction ("CREATE DATABASE foo");
\&
\&  Issues a DBI do statement while forcing autocommit. This is used for
\&  statements that can\*(Aqt be run in transaction mode (like CREATE DATABASE
\&  in PostgreSQL).
.Ve
.IP "rows \fItable\fR [\fIconditions\fR]" 4
.IX Item "rows table [conditions]"
.Vb 2
\&  $components = $dbi_interface \-> rows (\*(Aqcomponents\*(Aq);
\&  $components_needed = $dbi_interface \-> rows (\*(Aqcomponents\*(Aq, \*(Aqstock = 0\*(Aq);
.Ve
.Sp
Returns the number of rows within \fItable\fR satisfying \fIconditions\fR if any.
.IP "makemap \fItable\fR \fIkeycol\fR \fIvalcol\fR [\fIcondition\fR]" 4
.IX Item "makemap table keycol valcol [condition]"
.Vb 4
\&    $dbi_interface \-> makemap (\*(Aqcomponents\*(Aq, \*(Aqidf\*(Aq, \*(Aqprice\*(Aq);
\&    $dbi_interface \-> makemap (\*(Aqcomponents\*(Aq, \*(Aqidf\*(Aq, \*(Aqprice\*(Aq, \*(Aqprice > 10\*(Aq);
\&    $dbi_interface \-> makemap (\*(Aqcomponents\*(Aq, \*(Aqidf\*(Aq, \*(Aq*\*(Aq);
\&    $dbi_interface \-> makemap (\*(Aqcomponents\*(Aq, \*(Aqidf\*(Aq, \*(Aq*\*(Aq, \*(Aqprice > 10\*(Aq);
.Ve
.Sp
Produces a mapping between the values within column
\&\fIkeycol\fR and column \fIvalcol\fR from \fItable\fR. If an
\&\fIcondition\fR is given, only rows matching this
\&\fIcondition\fR are used for the mapping.
.Sp
In order to get the hash reference to the record as value of the
mapping, use the asterisk as the \fIvalcol\fR parameter.
.IP "random_row \fItable\fR \fIconditions\fR [\fImap\fR]" 4
.IX Item "random_row table conditions [map]"
Returns random row of the specified \fItable\fR. If \fImap\fR is set,
the result is a hash reference of the selected row, otherwise
an array reference. If the table doesn't contains rows, undefined
is returned.
.IP "serial \fItable\fR \fIsequence\fR" 4
.IX Item "serial table sequence"
Returns a serial number for \fItable\fR by querying the next value from
\&\fIsequence\fR. Depending on the DBMS one of the parameters is ignored.
This is \fIsequence\fR for mSQL resp. \fItable\fR for PostgreSQL. mysql
doesn't support sequences, but the AUTO_INCREMENT keyword for fields.
In this case this method returns 0 and mysql generates a serial
number for this field.
.IP "fill \fIsth\fR \fIhashref\fR [\fIflag\fR \fIcolumn\fR ...]" 4
.IX Item "fill sth hashref [flag column ...]"
Fetches the next table row from the result stored into \fIsth\fR
and records the value of each field in \fIhashref\fR. If \fIflag\fR
is set, only the fields specified by the \fIcolumn\fR arguments are
considered, otherwise the fields specified by the \fIcolumn\fR arguments
are omitted.
.IP "view \fItable\fR [\fIname\fR \fIvalue\fR ...]" 4
.IX Item "view table [name value ...]"
.Vb 5
\&  foreach my $table (sort $dbi_interface \-> tables)
\&    {
\&    print $cgi \-> h2 (\*(AqContents of \*(Aq, $cgi \-> code ($table));
\&    print $dbi_interface \-> view ($table);
\&    }
.Ve
.Sp
Produces plain text representation of the database table
\&\fItable\fR. This method accepts the following options as \fIname\fR/\fIvalue\fR
pairs:
.Sp
\&\fBcolumns\fR: Which columns to display.
.Sp
\&\fBorder\fR: Which column to sort the row after.
.Sp
\&\fBlimit\fR: Maximum number of rows to display.
.Sp
\&\fBseparator\fR: Separator inserted between the columns.
.Sp
\&\fBwhere\fR: Display only rows matching this condition.
.Sp
.Vb 3
\&  print $dbi_interface \-> view ($table,
\&                                order => $cgi \-> param (\*(Aqorder\*(Aq) || \*(Aq\*(Aq,
\&                                where => "price > 0");
.Ve
.SS "DATABASE INFORMATION"
.IX Subsection "DATABASE INFORMATION"
.IP "is_table \fINAME\fR" 4
.IX Item "is_table NAME"
Returns truth value if there exists a table \fINAME\fR in
this database.
.IP tables 4
.IX Item "tables"
Returns list of all tables in this database.
.IP sequences 4
.IX Item "sequences"
Returns list of all sequences in this database (Postgres only).
.IP "columns \fITABLE\fR" 4
.IX Item "columns TABLE"
Returns list of the column names of \fITABLE\fR.
.IP "types \fITABLE\fR" 4
.IX Item "types TABLE"
Returns list of the column types of \fITABLE\fR.
.IP "sizes \fITABLE\fR" 4
.IX Item "sizes TABLE"
Returns list of the column sizes of \fITABLE\fR.
.IP "typemap \fITABLE\fR" 4
.IX Item "typemap TABLE"
Returns mapping between column names and column types
for table \fITABLE\fR.
.IP "sizemap \fITABLE\fR" 4
.IX Item "sizemap TABLE"
Returns mapping between column names and column sizes
for table \fITABLE\fR.
.SS "TIME VALUES"
.IX Subsection "TIME VALUES"
.IP now 4
.IX Item "now"
.Vb 3
\&  $dbi_interface \-> insert (\*(Aqtransaction\*(Aq,
\&                   id => serial (\*(Aqtransaction\*(Aq, \*(Aqtransactionid\*(Aq),
\&                   time => \e$dbi_interface \-> now);
.Ve
.Sp
Returns representation for the current time. Uses special values of
the DBMS if possible.
.SS "MONETARY VALUES"
.IX Subsection "MONETARY VALUES"
.IP "money2num \fImoney\fR" 4
.IX Item "money2num money"
Converts the monetary value \fImoney\fR to a numeric one.
.SS MISCELLANEOUS
.IX Subsection "MISCELLANEOUS"
.IP "is_auth_error \fImsg\fR" 4
.IX Item "is_auth_error msg"
This method decides if the error message \fImsg\fR
is caused by an authentification error or not.
.SH AUTHORS
.IX Header "AUTHORS"
Stefan Hornburg (Racke), racke@linuxia.de
Dennis Sch\e[:o]n, ds@1d10t.de
.PP
Support for Sybase and ODBC provided by
David B. Bitton <david@codenoevil.com>.
.SH VERSION
.IX Header "VERSION"
0.20
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1), \fBDBI\fR\|(3), \fBDBD::Pg\fR\|(3), \fBDBD::mysql\fR\|(3), \fBDBD::msql\fR\|(3), \fBDBD::Sybase\fR\|(3), \fBDBD::ODBC\fR\|(3).