Provided by: libdbix-abstract-perl_1.040-3_all bug

NAME

       DBIx::Abstract - DBI SQL abstraction

VERSION

       version 1.04

SYNOPSIS

         use DBIx::Abstract;
         my $db = DBIx::Abstract->connect({
           driver=>'mydriver',
           host=>'myhost.org',
           dbname=>'mydb',
           user=>'myuser',
           password=>'mypassword',
           });

         if ($db->select('*','table')->rows) {
           while (my $data = $db->fetchrow_hashref) {
             # ...
           }
         }

         my $id = 23;

         my ($name) = $db->select('name','table',{id=>$id})->fetchrow_array;

         ###

         $db = DBIx::Abstract->connect( { driver=>'csv', f_name=>'foo/' } );

         ###

         $db = DBIx::Abstract->connect({
           dsn=>'dbi:someotherdb:so_db_name=mydb',
           user=>'myuser',
           password=>'mypassword',
           });

DESCRIPTION

       This module provides methods for doing manipulating database tables This module provides
       methods retrieving and storing data in SQL databases.  It provides methods for all of the
       more important SQL commands (like SELECT, INSERT, REPLACE, UPDATE, DELETE).

       It endeavors to produce an interface that will be intuitive to those already familiar with
       SQL.

       Notable features include:

         * data_source generation for some DBD drivers.
         * Can check to make sure the connection is not stale and reconnect
           if it is.
         * Controls statement handles for you.
         * Can delay writes.
         * Generates complex where clauses from hashes and arrays.
         * Shortcuts (convenience functions) for some common cases. (Like
           select_all_to_hashref.)

DEPRICATED

       We highly recommend that you use something like SQL::Abstract, which was inspired by this
       module.  Or even DBIx::Class (which uses SQL::Abstract for it's query syntax).  They're
       maintained and widely used.

METHODS

       Unless otherwise mentioned all methods return the database handle.

   connect
       "connect($connect_config | $dbihandle [,$options])" CONSTRUCTOR

       Open a connection to a database as configured by $connect_config.  $connect_config can
       either be a scalar, in which case it is a DBI data source, or a reference to a hash with
       the following keys:

        dsn      -- The data source to connect to your database

        OR, DBIx::Abstract will try to generate it if you give these instead:

        driver   -- DBD driver to use (defaults to mysql)
        host     -- Host of database server
        port     -- Port of database server
        dbname   -- Name of database

        Username and password are always valid.

        user     -- Username to connect as
        password -- Password for user

       Alternatively you can pass in a DBI handle directly.  This will disable the methods
       "reconnect" and "ensure_connection" as they rely on connection info not available on a DBI
       handle.

       Options is a hash reference.  Each key/value pair is passed on to the opt method.

   clone
       This clones the object.  For those times when you need a second connection to the same DB.
       If you need a second connection to a different DB, create a new object with 'connect'.

       This operation is logged at level 5 with the message "Cloned."

   connected
       Check to see if this object is connected to a database.  It checks to see if it has a
       database handle and if that handle's "Active" attribute is true.

   reconnect
       If the object is not connected to a database it will reconnect using the same parameters
       connect was originally called with.

   ensure_connection
       Makes sure that the object is connect to a database.  Makes sure that the connect is
       active (by sending a "SELECT 1").  If there is no connection, or the connection is not
       active then it tries to reconnect.  If it fails to reconnect then it dies.

   opt
       ($key[,$value])

       ({key=>$key[,value=>$value])

       Set option $key to $value.  Available keys are:

         loglevel (default 0)
             0 -- Fatal errors only
             1 -- Modifications
             2 -- And selects
             3 -- And user created queries
             4 -- And results of queries
             5 -- And other misc commands
             6 -- Internals of commands

         logfile (default undef)
           Log file

         delaymods (default false)
           Delay making modifications to the database until
           run_delayed is run.

         useCached
           If this is true then prepare_cached is used instead of prepare.
           Checkout the DBI documentation on this feature before using this
           feature.

         saveSQL
           If this is true then with each query DBIx::Abstract will stuff the generated
           SQL into the 'lastsql' key in the self payload.

         Additionally you may use any valid DBI attribute.  So, for instance, you
         can pass AutoCommit or LongReadLen.

       This operation is logged at level 5 with the message "Option Change" and the the key, the
       old value and new new value.

   query
       ($sql,@bind_params)

       ({sql=>$sql,bind_params=>[@bind_params]})

       This sends $sql to the database object's query method.  This should be used for
       applications where the existing methods are not able to generate flexible enough SQL for
       you.

       If you find yourself using this very often with things other then table manipulation (eg
       'create table','alter table','drop table') then please let me know so I can extend
       DBIx::Abstract to include the functionality you are using.

       This operation is logged at level 3

   run_delayed
       Execute delayed update/insert/delete queries.

       This operation is logged at level 5 with the message "Run delayed".

   delete
       ($table[,$where])

       ({table=>$table[,where=>$where]})

       Deletes records from $table.  See also the documentation on "DBIx::Abstract Where
       Clauses".

   insert
       ($table,$fields)

       ({table=>$table,fields=>$fields})

       $table is the name of the table to insert into.

       $fields is either a reference to a hash of field name/value or a scalar containing the SQL
       to insert after the "SET" portion of the statement.

       These all produce functionally equivalent SQL.

         $db->insert('foo',{bar=>'baz'});
         $db->insert('foo',q|bar='baz'|);
         $db->insert({table=>'foo',fields=>{bar=>'baz'}});
         $db->insert({table=>'foo',fields=>q|bar='baz'|});

       We also support literals by making the value in the hash an arrayref:

         $db->insert('foo',{name=>'bar',date=>['substring(now(),1,10)']});

       Would generate something like this:

         INSERT INTO foo (name,date) VALUES (?,substring(now(),1,10))

       With "bar" bound to the first parameter.

   replace
       ($table,$fields)

       ({table=>$table,fields=>$fields})

       $table is the name of the table to replace into.

       $fields is either a reference to a hash of field name/value or a scalar containing the SQL
       to insert after the "SET" portion of the statement.

       Replace works just like insert, except that if a record with the same primary key already
       exists then the existing record is replaced, instead of producing an error.

   update
       ($table,$fields[,$where])

       ({table=>$table,fields=>$fields[,where=>$where]})

       $table is the table to update.

       $fields is a reference to a hash keyed on field name/new value.

       See also the documentation on "DBIx::Abstract Where Clauses".

   select
       "select"

       ($fields,[$table,[$where[,$order]]])

       ({ fields=>$fields, table=>$table [,where=>$where] [,order=>$order] [,join=>$join]
       [,group=>$group] })

       The select method returns the DBIx::Abstract object it was invoked with.  This allows you
       to chain commands.

       $fields can be either an array reference or a scalar.  If it is an array reference then it
       should be a list of fields to include.  If it is a scalar then it should be a literal to
       be inserted into the generated SQL after "SELECT".

       $table can be either an array reference or a scalar. If it is an array reference then it
       should be a list of tables to use.  If it is a scalar then it should be a literal to be
       inserted into the generated SQL after "FROM".

       See also the documentation on "DBIx::Abstract Where Clauses".

       $order is the output order.  If it is a scalar then it is inserted literally after "ORDER
       BY".  If it is an arrayref then it is join'd with a comma and inserted.

       $join is there to make joining tables more convenient.  It will takes one or more (as an
       arrayref) sets of statements to use when joining.  For instance:

         $dbh->select({
           fields=>'*',
           table=>'foo,bar',
           join=>'foo.id=bar.foo_id',
           where=>{'foo.dollars',['>',30]}
           });

       Would produce:

         SELECT * FROM foo,bar WHERE (foo.dollars > ?) and (foo.id=foo_id)

       And put 30 into the bind_params list.

       $group is/are the field(s) to group by.  It may be scalar or an arrayref.  If it is a
       scalar then it should be a literal to be inserted after "GROUP BY".  If it is an arrayref
       then it should be a list of fields to group on.

   select_one_to_hashref
       ($fields,$table[,$where])

       ({fields=>$fields,table=>$table[,where=>$where]})

       This returns a hashref to the first record returned by the select.  Typically this should
       be used for cases when your where clause limits you to one record anyway.

       $fields is can be either a array reference or a scalar.  If it is an array reference then
       it should be a list of fields to include.  If it is a scalar then it should be a literal
       to be inserted into the generated SQL.

       $table is the table to select from.

       See also the documentation on "DBIx::Abstract Where Clauses".

   select_one_to_arrayref
       ($fields,$table[,$where])

       ({fields=>$fields,table=>$table[,where=>$where]})

       This returns a arrayref to the first record returned by the select.  Typically this should
       be used for cases when your where clause limits you to one record anyway.

       $fields is can be either a array reference or a scalar.  If it is an array reference then
       it should be a list of fields to include.  If it is a scalar then it should be a literal
       to be inserted into the generated SQL.

       $table is the table to select from.

       See also the documentation on "DBIx::Abstract Where Clauses".

   select_one_to_array
       ($fields,$table[,$where])

       ({fields=>$fields,table=>$table[,where=>$where]})

       This returns a array to the first record returned by the select.  Typically this should be
       used for cases when your where clause limits you to one record anyway.

       $fields is can be either a array reference or a scalar.  If it is an array reference then
       it should be a list of fields to include.  If it is a scalar then it should be a literal
       to be inserted into the generated SQL.

       $table is the table to select from.

       See also the documentation on "DBIx::Abstract Where Clauses".

   select_all_to_hashref
       ($fields,$table[,$where])

       ({fields=>$fields,table=>$table[,where=>$where]})

       This returns a hashref to all of the results of the select.  It is keyed on the first
       field.  If there are only two fields then the value is just the second field.  If there
       are more then two fields then the value is set to an arrayref that contains all of the
       fields.

       $fields is can be either a array reference or a scalar.  If it is an array reference then
       it should be a list of fields to include.  If it is a scalar then it should be a literal
       to be inserted into the generated SQL.

       $table is the table to select from.

       See also the documentation on "DBIx::Abstract Where Clauses".

   fetchrow_hashref
       This is just a call to the DBI method.

   fetchrow_hash
       This calls fetchrow_hashref and dereferences it for you.

   fetchrow_array
       This method calls the database handle's method of the same name.

   fetchall_arrayref
       This method calls the database handle's method of the same name.

   rows
       This method calls the database handle's method of the same name.

   quote
       This method is passed to the database handle via AUTOLOAD.

   disconnect
       This method is passed to the database handle via AUTOLOAD.

   commit
       This method is passed to the database handle via AUTOLOAD.

   rollback
       This method is passed to the database handle via AUTOLOAD.

   trace
       This method is passed to the database handle via AUTOLOAD.

   finish
       This method is passed to the statement handle via AUTOLOAD.

   bind_col
       This method is passed to the statement handle via AUTOLOAD.

   bind_columns
       This method is passed to the statement handle via AUTOLOAD.

Other things that need explanation

   DBIx::Abstract Where Clauses
       Where clauses in DBIx::Abstract can either be very simple, or highly complex.  They are
       designed to be easy to use if you are just typing in a hard coded statement or have to
       build a complex query from data.

       Wheres are either a scalar, hash-ref or array-ref:

       If it is a scalar, then it is used as the literal where.

       If it is a hash-ref then the key is the field to check, the value is either a literal
       value to compare equality to, or an array-ref to an array of operator and value.

         {
          first=>'joe',
          age=>['>',26],
          last=>['like',q|b'%|]
         }

       Would produce:

        WHERE first = ? AND last like ? AND age > ?

       With joe, b'% and 26 passed as bind values.

       If it is an array-ref then it is an array of hash-refs and connectors:

         [
           {
             first=>'joe',
             age=>['>',26]
           },
           'OR',
           {
             last=>['like',q|b'%|]
           }
         ]

       Would produce:

        WHERE (first = ? AND age > ?) OR (last like ?)

       With joe, 26 and b'% passed as bind values.

         [
           {
             first=>'joe',
             last=>['like','%foo%'],
           },
           'AND',
           [
             {age=>['>',26]},
             'OR',
             {age=>['<',30]}
           ]
         ]

       Would produce:

         WHERE (first = ? AND last like ?) AND ((age > ?) OR (age < ?))

       With joe, %foo%, 26 and 30 passed as bind values.

SUPPORTED DBD DRIVERS

       These drivers have been reported to work:

       •   mysql (development environment)

       •   Pg (development environment)

       •   Oracle

       •   XBase

       Any driver that uses ODBC syntax should work using the hash ref method.  With other
       drivers you should pass the DBI data source instead (this method will work with all
       drivers.)

CHANGES SINCE LAST RELEASE

       • Updated source pointers to github.

       • Fixed hash randomization related test failure

AUTHOR

       Rebecca Turner <me@re-becca.org>

SOURCE

       The development version is on github at <http://https://github.com/iarna/DBIx-Abstract>
       and may be cloned from <git://https://github.com/iarna/DBIx-Abstract.git>

SUPPORT

   Websites
       The following websites have more information about this module, and may be of help to you.
       As always, in addition to those websites please use your favorite search engine to
       discover more resources.

       •   MetaCPAN

           A modern, open-source CPAN search engine, useful to view POD in HTML format.

           <http://metacpan.org/release/DBIx-Abstract>

   Bugs / Feature Requests
       Please report any bugs at <https://github.com/iarna/DBIx-Abstract/issues>.

AUTHOR

       Rebecca Turner <me@re-becca.org>

COPYRIGHT AND LICENSE

       Portions copyright 2001-2014 by Rebecca Turner

       Portions copyright 2000-2001 by Adelphia Business Solutions

       Portions copyright 1998-2000 by the Maine Internetworks (MINT)

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.

       DBI(3)