NAME

DBIx::SQLEngine::Mixin::SeqTable - For databases without native sequences

SYNOPSIS

  # Classes can import this behavior if they don't have native sequences
  use DBIx::SQLEngine::Mixin::SeqTable ':all';
  
  # Public interface for SeqTable functionality
  $nextid = $sqldb->seq_increment( $table, $field );

  # Housekeeping functions for setup and removal
  $sqldb->seq_create_table();
  $sqldb->seq_insert_record( $table, $field );
  $sqldb->seq_delete_record( $table, $field );
  $sqldb->seq_drop_table();

DESCRIPTION

This mixin supports SQL database servers which do natively support an auto-incrementing or unique sequence trigger. Instead, a special table is allocated to store sequence values, and queries are used to atomically retrieve and increment the sequence value to ensure uniqueness.

Caution

Because of the way DBIx::AnyDBD munges the inheritance tree, DBIx::SQLEngine subclasses can not reliably inherit from this package. To work around this, we export all of the methods into their namespace using Exporter and @EXPORT.

Note that, strictly speaking, this is not a real mixin class, but the above implementation issue was not discovered and worked around until after the class had already been put into service.

REFERENCE

The following methods are provided:

seq_fetch_current

  $sqldb->seq_fetch_current( $table, $field ) : $current_value

Fetches the current sequence value.

Implemented as an exception-handling wrapper around sql_fetch_current(), and attempts to create the sequence table if it doesn't exist.

sql_fetch_current

  $sqldb->sql_fetch_current( $table, $field ) : $sql, @params

Returns a SQL statement to fetch the current value from the sequence table.

seq_increment

  $sqldb->seq_increment( $table, $field ) : $new_value

Increments the sequence, and returns the newly allocated value.

This is the primary "public" interface of this package.

If someone else has completed the same increment before we have, our update will have no effect and we'll immeidiately try again and again until successful.

If the table does not yet exist, attempts to create it automatically.

If the sequence record does not yet exist, attempts to create it automatically.

seq_table_name

Constant 'dbix_sqlengine_seq'.

seq_create_table

  $sqldb->seq_create_table()

Issues a SQL create table statement to create the sequence table.

seq_drop_table

  $sqldb->seq_drop_table()

Issues a SQL drop table statement to remove the sequence table.

seq_insert_record

  $sqldb->seq_insert_record( $table, $field )

Creates a record in the sequence table for a given field in a particular table.

seq_delete_record

  $sqldb->seq_delete_record( $table, $field )

Removes the corresponding record in the sequence table.

seq_bootstrap_init

  $sqldb->seq_bootstrap_init( $table, $field ) : $current_value

Scans the designated field in a given table to determine its maximum value, and then stores that in sequence table.

SEE ALSO

See DBIx::Sequence for another version of the sequence-table functionality, which greatly inspired this module.

cpanm DBIx::SQLEngine

perl -MCPAN -e shell
install DBIx::SQLEngine