NAME

Pinwheel::Database

SYNOPSIS

    use Pinwheel::Database;

    my $sth = prepare('SELECT * FROM episodes');
    my $results = fetchall_tables($sth);

DESCRIPTION

set_connection and connection manage a single, persistent DBI connection to a MySQL database.

TODO, an overview of the other routines.

ROUTINES

set_connection(ARGS)

Sets the DBI connection arguments used by connect.

connect()

Ensures the database connection is up, initialised, and ready for use.

If there was no previous connection, or the previous connection is dead, or the previous connection was originally established >= 5 minutes ago, then a new connection is made (first closing down any existing connection).

New connections are made using the arguments previously specified by set_connection.

After the connection is established, the following settings are applied:

        $dbh->do("SET time_zone='+00:00'");
        $dbh->do("SET names 'utf8'");
        $dbh->{unicode} = 1;

Finally, <connect> discovers the 'hostname' mysql variable and stores it in $Pinwheel::Database::dbhostname.

disconnect()

Ensures the database connection is down.

$Pinwheel::Database::dbhostname is set to undef.

finish_all()

Closes all the query handles for the database connections.

$sth = prepare($query[, $transient])

Prepares a query and returns the statement handle, connecting to the database if required.

If the prepared statement cache already contains a statement handle for this query, and that handle is idle, then it is returned.

Otherwise, connect is called to ensure the database connection is up, and the query is prepared. The statement handle is stored in the cache, unless $transient is true. Then the statement handle is returned.

$fields = describe($table_name)

Retrieves a list of the fields for the given table.

Returns a reference to a hash which might look like this:

  $fields = {
    'id' => { type => 'int(11)', null => 0 },
    'title' => { type => 'varchar(64)', null => 0 },
    'expires' => { type => 'datetime', null => 1 },
  }

The keys are the column names, 'type' is the MySQL column type, and 'null' is boolean.

tables()

Returns an array of the names of the tables in the database.

dbhostname()

Return the hostname of the database server.

without_foreign_keys(BLOCK)

Runs BLOCK in a separate database transaction. Foreign key constraints are disabled at the start of the transaction, and re-enabled at the end.

fetchone_tables($sth[, $tables])

TODO, document me.

fetchall_tables($sth[, $tables])

TODO, document me.

EXPORTS

Nothing is exported by default. The following can be exported:

    set_connection
    connect
    dbhostname
    describe
    disconnect
    do
    fetchall_tables
    fetchone_tables
    finish_all
    prepare
    tables
    without_foreign_keys

BUGS

set_connection doesn't take a deep copy of its arguments.

The 300 second threshold in connect is hard-wired.

AUTHOR

A&M Network Publishing <DLAMNetPub@bbc.co.uk>