/ 
DBIx-DBO-0.40
River stage zero No dependents
/ DBIx::DBO::Table

NAME

DBIx::DBO::Table - An OO interface to SQL queries and results. Encapsulates a table in an object.

SYNOPSIS

# Create a Table object
my $table = $dbo->table('my_table');

# Get a column reference
my $column = $table ** 'employee_id';

# Quickly display my employee id
print $table->fetch_value('employee_id', name => 'Vernon');

# Find the IDs of fired employees
my @fired = @{ $table->fetch_column('id', status => 'fired');

# Insert a new row into the table
$table->insert(employee_id => 007, name => 'James Bond');

# Remove rows from the table where the name IS NULL
$table->delete(name => undef);

DESCRIPTION

Table objects are mostly used for column references in a Query. They can also be used for INSERTs, DELETEs and simple lookups (fetch_*).

METHODS

new

DBIx::DBO::Table->new($dbo, $table);
# or
$dbo->table($table);

Create and return a new Table object. The $table argument that specifies the table can be a string containing the table name, 'customers' or 'history.log', it can be an arrayref of schema and table name ['history', 'log'] or as another Table object to clone.

tables

Return a list of Table objects, which will always be this Table object.

name

$table_name = $table->name;
($schema_name, $table_name) = $table->name;

In scalar context it returns the name of the table in list context the schema and table names are returned.

columns

Return a list of column names.

column

$table->column($column_name);
$table ** $column_name;

Returns a reference to a column for use with other methods. The ** method is a shortcut for the column method.

row

Returns a new empty Row object for this table.

fetch_row

$table->fetch_row(%where);

Fetch the first matching row from the table returning it as a Row object.

The %where is a hash of field/value pairs. The value can be a simple SCALAR or undef for NULL It can also be a SCALAR reference, which will be used without quoting, or an ARRAY reference for multiple IN values.

$someone = $table->fetch_row(age => 21, join_date => \'CURDATE()', end_date => undef);
$a_child = $table->fetch_row(name => \'NOT NULL', age => [5 .. 15]);

fetch_value

$table->fetch_value($column, %where);

Fetch the first matching row from the table returning the value in one column.

fetch_hash

$table->fetch_hash(%where);

Fetch the first matching row from the table returning it as a hashref.

fetch_column

$table->fetch_column($column, %where);

Fetch all matching rows from the table returning an arrayref of the values in one column.

insert

$table->insert(name => 'Richard', age => 103);

Insert a row into the table. Returns true on success or undef on failure.

On supporting databases you may also use $table->last_insert_id to retreive the autogenerated ID (if there was one) from the last inserted row.

last_insert_id

$table->insert(name => 'Quentin');
my $row_id = $table->last_insert_id;

Retreive the autogenerated ID (if there was one) from the last inserted row.

Returns the ID or undef if it's unavailable.

bulk_insert

$table->bulk_insert(
    columns => [qw(id name age)], # Optional
    rows => [{name => 'Richard', age => 103}, ...]
);
$table->bulk_insert(
    columns => [qw(id name age)], # Optional
    rows => [[ undef, 'Richard', 103 ], ...]
);

Insert multiple rows into the table. Returns the number of rows inserted or undef on failure.

The columns need not be passed in, and will default to all the columns in the table.

On supporting databases you may also use $table->last_insert_id to retreive the autogenerated ID (if there was one) from the last inserted row.

delete

$table->delete(name => 'Richard', age => 103);

Delete all rows from the table matching the criteria. Returns the number of rows deleted or undef on failure.

truncate

$table->truncate;

Truncate the table. Returns true on success or undef on failure.

Common Methods

These methods are accessible from all DBIx::DBO* objects.

dbo

The DBO object.

dbh

The read-write DBI handle.

rdbh

The read-only DBI handle, or if there is no read-only connection, the read-write DBI handle.

config

$table_setting = $table->config($option);
$table->config($option => $table_setting);

Get or set the Table config settings. When setting an option, the previous value is returned. When getting an option's value, if the value is undefined, the DBIx::DBO's value is returned.

See "Available_config_options" in DBIx::DBO.

SEE ALSO

DBIx::DBO