NAME

DBIx::SQLEngine::Record::Table - Records accessed via a Schema::Table

SYNOPSIS

Setup: Several ways to create a class.

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

  $class_name = $sqldb->record_class( $table_name );
  
  $sqldb->record_class( $table_name, $class_name );
  
  package My::Record;
  use DBIx::SQLEngine::Record::Class '-isasubclass';  
  My::Record->table( $sqldb->table($table_name) );

Basics: Common operations on a record.

  $record = $class_name->new_with_values(somefield => 'My Value');
  
  print $record->get_values( 'somefield' );

  $record->change_values( somefield => 'New Value' );

Fetch: Retrieve records by ID or other query.

  $record = $class_name->select_record( $primary_key );
  
  @records = $class_name->fetch_select(%clauses)->records;

Modify: Write changes to the data source.

  $record->insert_record();
  
  $record->update_record();
  
  $record->delete_record();

Schema: Access to table and columns.

  unless ( $class_name->table_exists ) {
    $class_name->create_table( { name => 'id', type => 'int'} );
  }

DESCRIPTION

DBIx::SQLEngine::Record::Table is a mixin class for database records in tables accessible via DBIx::SQLEngine.

Don't use this module directly; instead, pass its name as a trait when you create a new record class. This package provides a multiply-composable collection of functionality for Record classes. It is combined with the base class and other traits by DBIx::SQLEngine::Record::Class.

TABLE INTERFACE

Each record class is associated with a table object. The table provides the DBI connection and SQL execution capabilities required to talk to the remote data storage.

Table Accessor

table()

  $class_name->table() : $table
  $class_name->table($table)

Get and set our current DBIx::SQLEngine::Schema::Table. Required value. Establishes the table a specific class of record will be stored in.

get_table()

  $class_name->get_table() : $table or exception

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

Methods Delegated to Table

These methods all call the same method on the associated table.

detect_sqlengine()

  $class_name->detect_sqlengine : $flag

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

table_exists()

  $class_name->table_exists : $flag

Detects whether the table has been created and has not been dropped.

columnset()

  $class_name->columnset () : $columnset

Returns the current columnset, if any.

fetch_one_value()

  $class_name->fetch_one_value( %sql_clauses ) : $scalar

Calls fetch_select, then returns the first value from the first row of results.

count_rows()

  $class_name->count_rows ( ) : $number
  $class_name->count_rows ( $criteria ) : $number

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

Table Delegation Methods

The following methods are used internally to facilitate delegation to the table object.

table_fetch_one_method()

  $class->table_fetch_one_method( $method, @args );

Calls the named method on the table and inflates the result with record_from_db_data.

table_fetch_set_method()

  $class->table_fetch_set_method( $method, @args );

Calls the named method on the table and inflates the result with record_set_from_db_data.

table_record_method()

  $record->table_record_method( $method, @args );

Calls the named method on the table, passing the record itself as the first argument.

Primary Keys

primary_criteria()

  $record->primary_criteria() : $hash_ref

Returns a hash of key-value pairs which could be used to select this record by its primary key.

primary_key_value()

  $record->primary_key_value() : $id_value

Returns the primary key value for this object.

FETCHING DATA (SQL DQL)

Select to Retrieve Records

fetch_select()

  $class_name->fetch_select ( %select_clauses ) : $record_set

Retrives records from the table using the provided SQL select clauses.

Calls the corresponding SQLEngine method with the table name and the provided arguments. Each row hash is blessed into the record class before being wrapped in a RecordSet::Set object.

fetch_one_record()

  $sqldb->fetch_one_record( %select_clauses ) : $record_hash

Retrives one record from the table using the provided SQL select clauses.

Calls fetch_select, then returns only the first row of results. The row hash is blessed into the record class before being returned.

visit_select()

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

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

Each row hash is blessed into the record class before being the subroutine is called.

Selecting by Primary Key

select_record()

  $class_name->select_record ( $primary_key_value ) : $record_obj
  $class_name->select_record ( \@compound_primary_key ) : $record_obj
  $class_name->select_record ( \%hash_with_primary_key_value ) : $record_obj

Fetches a single record by primary key.

The row hash is blessed into the record class before being returned.

select_records()

  $class_name->select_records ( @primary_key_values_or_hashrefs ) : $record_set

Fetches a set of one or more records by primary key.

Each row hash is blessed into the record class before being wrapped in a RecordSet::Set object.

EDITING DATA (SQL DML)

Insert to Add Records

After constructing a record with one of the new_*() methods, you may save any changes by calling insert_record.

insert_record()

  $record_obj->insert_record() : $flag

Adds the values from this record to the table. Returns the number of rows affected, which should be 1 unless there's an error.

Update to Change Records

After retrieving a record with one of the fetch methods, you may save any changes by calling update_record.

update_record()

  $record_obj->update_record() : $record_count

Attempts to update the record using its primary key as a unique identifier. Returns the number of rows affected, which should be 1 unless there's an error.

Delete to Remove Records

delete_record()

  $record_obj->delete_record() : $record_count

Delete this existing record based on its primary key. Returns the number of rows affected, which should be 1 unless there's an error.