NAME

DBIx::SQLEngine::Schema::Table - A table in a data source

SYNOPSIS

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

$table = $sqldb->table( $table_name );

$row_ary = $table->fetch_select( criteria => { status => 2 } );
$table->do_update( values => { status => 3 }, criteria => { status => 2 } );

$table->insert_row( { id => $primary_key, somefield => 'Some Value' } );
$row = $table->fetch_row( $primary_key );
$row->{somefield} = 'New Value';
$table->update_row( $row );
$table->detele_row( $row );

DESCRIPTION

The DBIx::SQLEngine::Schema::Table class represents database tables accessible via a particular DBIx::SQLEngine.

By storing a reference to a SQLEngine and the name of a table to operate on, a Schema::Table object can facilitate 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.

The *_row() methods use this information about the table columns to facilitate common operations on table rows using simple hash-refs.

REFERENCE

Table Object Creation

SQLEngine->table()

DBIx::SQLEngine->new( ... )->table( $tablename ) : $table

Convenience function to create a table with the given table name and sqlengine.

new()

DBIx::SQLEngine::Schema::Table->new( sqlengine=>$sqldb, name=>$name ) : $table

Standard hash constructor. You are expected to provde the name and sqlengine arguments.

Name Accessor

name()

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

Get and set the table name. Required value. Identifies this table in the data source.

get_name()

$table->get_name() : $string or exception

Returns the table name, or throws an exception if it is not set.

SQLEngine Accessor

sqlengine()

$table->sqlengine() : $sqldb
$table->sqlengine($sqldb)

Get and set our current DBIx::SQLEngine. Required value. The SQLEngine provides the DBI connection and SQL execution capabilities required to talk to the remote data storage.

get_sqlengine()

$table->get_sqlengine() : $sqldb or exception

Returns the SQLEngine, or throws an exception if it is not set.

sqlengine_do()

$table->sqlengine_do( $method, %sql_clauses ) : $results or exception

Calls the provided method name on the associated SQLEngine, passing along the table name and the other provided arguments. Intended for methods with hash-based argument parsing like fetch_select( table => $table_name ).

sqlengine_table_method()

$table->sqlengine_table_method( $method, @args ) : $results or exception

Calls the provided method name on the associated SQLEngine, passing along the table name and the other provided arguments. Intended for methods with list-based argument parsing like detect_table( $table_name ).

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 sqlengine. 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 specifically named column.

Select to Retrieve Rows

fetch_select()

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

Calls the corresponding SQLEngine method with the table name and the provided arguments. Return rows from the table that match the provided criteria, and in the requested order, by executing a SQL select statement.

Fetch the row with the specified ID.

visit_select()

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

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

select_row()

$table->select_row ( $primary_key_value ) : $row
$table->select_row ( \%hash_with_primary_key_value ) : $row

Insert to Add Rows

do_insert()

$table->do_insert ( %insert_clauses ) : $row_count

Calls the corresponding SQLEngine method with the table name and the provided arguments.

insert_row()

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

Adds the provided row by executing a SQL insert statement. Uses column_names() and column_primary_is_sequence() to produce the proper clauses.

insert_rows()

$table->insert_rows ( @row_hashes ) : ()

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

Update to Change Rows

do_update()

$table->do_update ( %update_clauses ) : $row_count

Calls the corresponding SQLEngine method with the table name and the provided arguments.

update_row()

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

Update this existing row based on its primary key. Uses column_names() and column_primary_is_sequence() to produce the proper clauses.

Delete to Remove Rows

do_delete()

$table->do_delete ( %delete_clauses ) : $row_count

Calls the corresponding SQLEngine method with the table name and the provided arguments.

delete_row()

$table->delete_row ( $row_hash_or_id ) : ()

Deletes the provided row from the table.

delete_rows()

$table->delete_rows ( @row_hashes_or_ids ) : ()

Deletes the provided row from the table.

Selecting Agregate Values

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.

Detect Availability

detect_sqlengine()

$table->detect_sqlengine : $flag

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

detect_table()

$table->detect_table : @columns

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

Create, Detect, and Drop

create_table()

$table->create_table () 
$table->create_table ( $column_ary ) 

drop_table()

$table->drop_table () 

ensure_table_exists()

$table->ensure_table_exists ( $column_ary )

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

recreate_table()

$table->recreate_table ()

Remove and then recreate the table's remote storage.

SEE ALSO

See DBIx::SQLEngine for the overall interface and developer documentation.

See DBIx::SQLEngine::Docs::ReadMe for general information about this distribution, including installation and license information.

cpanm DBIx::SQLEngine

perl -MCPAN -e shell
install DBIx::SQLEngine