NAME

DBIx::Cursor - Perl extension for easy DBI-access to a single table.

SYNOPSIS

  use DBIx::Cursor;
  my $c = new DBIx::Cursor($dbh, 'person', 'per_pid');

  while (my $r = $t->fetch)
  { printf "%s %s\n", $r->{per_firstname}, $r->{per_name}; }

  $c->read(1);

  $c->where('per_pid = 1 order by per_name');
  $c->fetch
  $c->set(per_firstname => 'Larry', per_name => 'Wall')
  $c->update;

  $c->reset
  $c->set(per_pid => 5, per_firstname => 'Linus', per_name => 'Torvalds')
  $c->insert;

DESCRIPTION

The class DBIx::Cursor represents a cursor for a single Database-table. You can select, update, insert or delete entries in a table easier than creating SQL-statements. It does not use any specific features of any database, so it should work with every DBD-driver.

DBIx::Cursor is not a replacement for DBI, but a add-on. You can use DBI as usual and use SQL-statements as you need.

METHODS

new

  my $c = new DBIx::Cursor($dbh, $table, $pk1, $pk2, ...)

The method new creates an instance of DBIx::Cursor. It returns a object, which represents a table in the database. It checks, that the table exists, so if you create a cursor for a not existing table, it will die.

$dbh is your connection-handle, you get from DBI.

$table is the tablename, you want to use.

The remaining parameters are the names of your primary key. You can use some alternate unique index as well.

But be aware, that DBIx::Cursor does not check, if the index is ok. It expects, that these columns identify exactly one row.

If you don't provide a key, DBIx::Cursor tries to get one through the $dbh->primary_key-method. But not every driver support this method, so to be compatible you should not use this feature. DBD::Pg, which I use for testing, does not provide one.

dbh

Returns the databasehandle

get_type

  $c->get_type('col1');

Returns the type of the column. Refer to DBI-documentation and your driver for Columntypes

get_columns

Returns the columns of the table as an array.

read

  $c->read($value_of_pk1, $value_of_pk2, ...)

Fetches a row into the Cursor through the primary key.

You have to give him a value for every primary key column.

Returns the object itself on success or undef when not found.

set

  $c->set(col1 => 'value 1', col2 => 'value 2', ...);

Sets the values of the named columns.

The Method dies if you give values for not existing columns.

The Values are not updated in the database.

get

  my $value1 = $c->get('col1');
  my @values = $c->get('col1', 'col2');
  my $values = $c->get;         # get hash-reference
  my %values = $c->get;

get returns values for each column you request or a hash of all columns it holds.

In scalar-context with one parameter it returns the value.

In array-context with one or more parameters it returns a array of the values.

In array-context without parameters it returns a hash of key-value-pairs.

In scalar-context without parameters it returns a hash-reference of the internel hash. You can modify the values of the hash if you need to.

The Method does not check, if the requested columns exist. It just returns undef for unknown values.

reset

  $c->reset

Clears the content of the cursor.

It returs the used DBIx::Cursor-object itself.

where

  $c->where('per_name like \'M%\' order by per_firstname');
  $c->where('per_firstname = ?', $name);

The where method sets a filter for retrieving rows. The string is directly passed to the driver when needed. You can every SQL-feature you want.

You can also use the placeholder '?' and pass the values as additional parameters. You don't need to give values here for these. You can later pass or modify the values with the values-Method.

The parameters aren't checked here. If the expression is not valid you get an error if you try to fetch the values.

The Cursor is reseted, so you get a fresh start on next fetch.

The condition is actually appended to the SQL-statement:

  select * from table where

If the condition starts with 'where' or 'order by' the where is left out. You can fetch all values from a table in a specific order with:

  $c->where('order by per_firstname')

It returs the used DBIx::Cursor-object itself.

values

  $c->values($name);

Set the values of the placeholders you passed with where.

fetch

  $c->fetch

Do the actual fetch to the database. On the first call (or after resetting the cursor) it builds the SQL-select statement and fetches the first row. On subsequent calls it uses the statement and fetches subsequent rows.

It returns the fetched data as a hash-reference or - in array-context - the hash or undef when there is no more data availible.

update

  $c->update;
  $c->update('col1', 'col2');

Updates the record in the database to match the internal record.

It returns the number of updated records (should be 1, but this isn't checked).

You can pass the column-names you want to update. By default every not primary key column is updated.

If you want to update your primary key also, you can fetch the row, modify your key and call $c-update($c->get_columns)>.

The method does no commit.

insert

  $c->insert;

Inserts a new Record with the values set.

Returns whatever DBI::execute returns.

replace

  $c->replace;

Tries to update data. If no record with the primary key set is found, does a insert.

Returns whatever DBI::execute returns.

delete

  $c->delete

Deletes the record, which matches the primary key set.

AUTHOR

Tommi Mäkitalo, Dr. Eckhardt + Partner GmbH, <tommi@maekitalo.de>

COPYRIGHT

Copyright (c) 2001 by Tommi Mäkitalo, Dr. Eckhardt + Partner GmbH

LICENSE

This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

DISCLAIMER

This package is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO

DBI

perl.

cpanm DBIx::Cursor

perl -MCPAN -e shell
install DBIx::Cursor