/ 
DBIx-DBO2-0.005
River stage zero No dependents
/ DBIx::DBO2::Table

NAME

DBIx::DBO2::Table - A table in a datasource

SYNOPSIS

my $sqldb = DBIx::SQLEngine->new( ... );

my $table = DBIx::DBO2::Table->new( name => 'foo', datasource => $ds );

my $row = $table->fetch_id(1);
my $row_ary = $table->fetch_select( criteria => { status => 2 } );

DESCRIPTION

The DBIx::DBO2::Table class represents database tables accessible via DBIx::SQLEngine.

A table acts as an interface to a particular set of data, uniquely identfied by the datasource that it connects to and the b<name> of the table.

It facilitates generation of SQL queries that operate on the named table.

Each table can retrieve and cache a ColumnSet containing information about the name and type of the columns in the table. Column information is loaded from the storage as needed, but if you are creating a new table you must provide the definition.

REFERENCE

Constructor

Create one Table for each underlying database table you will use.

new

You are expected to provde the name and datasource or datasource_name arguments. (Standard::Hash:new)

Name

Required. Identifies this table in the DataSource.

name
$table->name($string)
$table->name() : $string

Set and get the table name. (Template::Hash:string)

DataSource

Required. The DataSource provides the DBI connection and SQL execution capabilities required to talk to the remote data storage.

datasource

Refers to our current DBIx::SQLEngine. (Standard::Hash:object)

datasource_name
$table->datasource_name () : $name

Get the name of the current datasource.

datasource_name
$table->datasource_name ($name) : ()

Attempt to find a datasource with the given name, and store it as our datasource reference.

Inserting Rows

insert_row
$table->insert_row ( $row_hash ) : ()

Adds the provided row by executing a SQL insert statement.

insert_rows
$table->insert_rows ( $row_hash_ary ) : ()

Insert each of the rows from the provided array into the table.

Selecting Rows

fetch_all
$table->fetch_all () : $row_hash_array

Retrieve all of the rows from the datasource.

fetch_select
$table->fetch_select ( %select_clauses ) : $row_hash_array

Return rows from the table that match the provided criteria, and in the requested order, by executing a SQL select statement.

fetch_id
$table->fetch_id ( $PRIMARY_KEY ) : $row

Fetch the row with the specified ID.

visit_select
$table->visit_select ( $sub_ref, %select_clauses ) : @results

Calls the provided subroutine on each matching row as it is retrieved. Returns the accumulated results of each subroutine call (in list context).

Updating Rows

update_row
$table->update_row ( $row_hash ) : ()

Update this existing row based on its primary key.

update_where
$table->update_where ( CRITERIA, $changes_hash ) : ()

Make changes as indicated in changes hash to all rows that meet criteria

Deleting Rows

delete_all
$table->delete_all () : ()

Delete all of the rows from table.

delete_where
$table->delete_where ( $criteria ) : ()
delete_row
$table->delete_row ( $row_hash ) : ()

Deletes the provided row from the table.

delete_id
$table->delete_id ( $PRIMARY_KEY ) : ()

Deletes the row with the provided ID.

Agregate functions

count_rows
$table->count_rows ( CRITERIA ) : $number

Return the number of rows in the table. If called with criteria, returns the number of matching rows.

fetch_max
$table->count_rows ( $colname, CRITERIA ) : $number

Returns the largest value in the named column.

Storage And Source Management

detect_datasource
$table->detect_datasource : $flag

Detects whether the SQL database is avaialable by attempting to connect.

table_exists
$table->table_exists : $flag

Checks to see if the table exists in the SQL database by attempting to retrieve its columns.

ColumnSet

columnset
$table->columnset () : $columnset

Returns the current columnset, if any.

get_columnset
$table->get_columnset () : $columnset

Returns the current columnset, or runs a trivial query to detect the columns in the DataSource. If the table doesn't exist, the columnset will be empty.

columns
$table->columns () : @columns

Return the column objects from the current columnset.

column_names
$table->column_names () : @column_names

Return the names of the columns, in order.

column_named
$table->column_named ( $name ) : $column

Return the column info object for the specicifcally named column.

DDL

table_create
$table->table_create () 
$table->table_create ( $column_ary )
table_drop
$table->table_drop ()
table_ensure_exists
$table->table_ensure_exists ( $column_ary )

Create the table's remote storage if it does not already exist.

table_recreate
$table->table_recreate ()

Remove and then recreate the table's remote storage.

SEE ALSO

See DBIx::DBO2 for an overview of this framework.