NAME

DBIx::QuickORM::Handle - A handle for building and executing queries.

DESCRIPTION

This object is the equivelent of the DBIx::Class::ResultSet provided by DBIx::Class. It is not identical, and not intended to be a drop in replacement.

A handle object allows you to compose queries, and execute them.

SYNOPSIS

use My::Orm qw/orm/;

# Get a connection to the orm
my $orm = orm('my_orm');

# Get a handle on the 'people' table. This does NOT execute a query
my $people_handle = $orm->handle('people');

# Do something for all rows in the people table. This DOES execute a query.
for my $person ($people_handle->all) {
    ...
}

# A handle for all people witht he 'smith' surname.
my $smith_handle = $people_handle->where({surname => 'smith'});

# print the first names of all people with the 'smith' surname.
for my $person ($handle->all) {
    print $person->field('first_name') . "\n"
}

METHODS

CONSTRUCTORS

$new_h = DBIx::QuickORM::Handle->new(@params)

$new_h = $h->clone(@params)

$new_h = $h->handle(@params)

new(), handle(), and clone() are all aliases for the same functionality. They can be used interchangably.

This can be used to duplicate an existing handle, or create a new one. So you can call any of these on an existing instance, or on the handle class.

CONSTRUCTOR ARGS

Note: Some of these are mutually exclusive, an exception will be thrown if you provide conflicting arguments.

Note: Most of these are better documented in the "Immutators" and "Immucessors" sections.

Blessed Object that implements DBIx::QuickORM::Role::Source: If a source object is in the args it is treated as the source.
Blessed Object that implements DBIx::QuickORM::Role::Row: If a row object is in the args it will be set as the row the handle operates on. This will also set the WHERE clause, and an exception will be thrown if you attempt to set both. This will also set the SOURCE to be the rows source, an exception will be thrown if you provide a source other than the one in the row.
Blessed Object that implements DBIx::QuickORM::Role::SQLBuilder: Specify what DBIx::QuickORM::Role::SQLBuilder implementation will be used. The default is DBIx::QuickORM::SQLBuilder::SQLAbstract.
Blessed Object that subclasses DBIx::QuickORM::Connection: Sets the connection the handle should use.
\%hash - Where Clause: If a hashref is provided it will be used as the WHERE clause.
\@array - Order by: If an arrayref is provided it will be used as the ORDER_BY.
INTEGER - Limit: If a simple integer is provided it will be used as the query LIMIT.
$table_name - source: If a string is provided that does not match any other string, it will be asusmed to be a table name and will be used as the source.
connection => $CONNECTION: You can specify the connection using the connection key in a key/value pair.
source => $SOURCE: You can specify the source using the source key in a key/value pair.
sql_builder => $SQL_BUILDER: You can specify the sql_builder using the sql_builder key in a key/value pair.
row => $ROW: You can specify the row using the row key in a key/value pair.
where => $WHERE: You can specify the where using the where key in a key/value pair.
order_by => \@ORDER_BY: You can specify the order_by using the order_by key in a key/value pair.
limit => $LIMIT: You can specify the limit using the limit key in a key/value pair.
fields => \@FIELDS: You can specify the fields using the fields key in a key/value pair.
omit => \@FIELDS: You can specify the omit using the omit key in a key/value pair.
async => $BOOL: You can use the 'async' key and a boolean value to toggle async on/off.
aside => $BOOL: You can use the 'aside' key and a boolean value to toggle aside on/off.
forked => $BOOL: You can use the 'forked' key and a boolean value to toggle forked on/off.
auto_refresh => $BOOL: You can use the auto_refresh key and a boolean to turn auto_refresh on and off.
data_only => $BOOL: You can use the data_only key and a boolean to turn data_only on and off.
internal_transactions => $BOOL: You can use the internal_transactions key and a boolean to turn internal_transactions on and off.
-FLAG => sub { ... }: This can be used to modify the behavior or error messages of the constructor.

CONSTRUCTOR FLAGS

The following flags are all available to modify constructor behavior.

These are primarily useful for custom methods that modify or extend handle behavior.

-allow_override => $BOOL

Defaults to true.

This allows overriding values from the original handle when cloning it:

my $h1 = DBIx::QuickORM::Handle->new(where => { id => 1 });
my $h2 = $h1->handle({id => 2});

The above is fine when allow_override is set to true. In most cases this is the behavior you want.

The following will die and tell you that you tried to set the where clause when the handle you are cloning already had one set:

my $h1 = DBIx::QuickORM::Handle->new(where => { id => 1 });
my $h2 = $h1->handle(-allow_override => 0, {id => 2});

-array => sub { my ($new_h, $arrayref) = @_; ...; return $bool }

You can use this flag to provide alternate behavior for when an arrayref is provided as an argument. Normally it is treated as an ORDER_BY. You can provide a callback that implements alternate behavior. Your callback will receive the new handle and the arg as arguments. The sub should return true if the alternate behavior handled the argument, it should return false to fallback to the default behavior of treating it as an ORDER_BY.

-array => sub {
    my ($new_h, $arrayref) = @_;

    $did_alternate_behavior = ...;

    return 1 if $did_alternate_behavior;
    return 0;
},

-bad_override => sub { ($handle, $key, @args) = @_; die "..." }

This allows you to override what happens when someone does a bad override (IE -allow_override is set to false, and an override was attempted)

-hash => sub { my ($new_h, $hashref) = @_; ...; return $bool }

You can use this flag to provide alternate behavior for when an hashref is provided as an argument. Normally it is treated as an WHERE. You can provide a callback that implements alternate behavior. Your callback will receive the new handle and the arg as arguments. The sub should return true if the alternate behavior handled the argument, it should return false to fallback to the default behavior of treating it as an WHERE.

-hash => sub {
    my ($new_h, $hashref) = @_;

    $did_alternate_behavior = ...;

    return 1 if $did_alternate_behavior;
    return 0;
},

-integer

You can use this flag to provide alternate behavior for when an integer is provided as an argument. Normally it is treated as a LIMIT. You can provide a callback that implements alternate behavior. Your callback will receive the new handle and the arg as arguments. The sub should return true if the alternate behavior handled the argument, it should return false to fallback to the default behavior of treating it as a LIMIT.

-integer => sub {
    my ($new_h, $integer) = @_;

    $did_alternate_behavior = ...;

    return 1 if $did_alternate_behavior;
    return 0;
},

-row_and_source => sub { my ($h) = @_; die "..." }

What to do when someone provides both a row, and a source that does not match the rows source. Normally it throws an exception.

-row_and_where => sub { my ($h) = @_; die "..." }

What to do when someone provides both a row, and a WHERE condition. Normally an exception is thrown.

-scalar => sub { my ($h, $arg, $args) = @_; ...; return $bool }

This provides an opportunity to override what is done if a scalar argument is encountered. Return false to fallback to original behavior.

This is a place to inject custom my_arg => $my_val options for the constructor to process.

-unknown_arg => sub { my ($h, $arg) = @_; die ... }

-unknown_object => sub { my ($h, $arg) = @_; die ... }

-unknown_ref => sub { my ($h, $arg) = @_; die ... }

These allow custom handlers for unknown arguments. The defaults throw exceptions.

SHORTCUTS

$dialect = $h->dialect: Return the DBIx::QuickORM::Dialect object.

Joining

$new_h = $h->join(@args)

Used to create a join handle.

$new_h = $h->left_join(@args)

$new_h = $h->right_join(@args)

$new_h = $h->inner_join(@args)

$new_h = $h->full_join(@args)

$new_h = $h->cross_join(@args)

These are all shortcuts for:

$new_h = $h->join(type => $DIRECTION, @args);

Then you can get DBIx::QuickORM::Join::Row objects:

my $jrow = $h->first;

my @jrows = $h->all;

Here is an example, here is some schema:

CREATE TABLE foo (
    foo_id  SERIAL      NOT NULL PRIMARY KEY,
    name    VARCHAR(20) NOT NULL,
    UNIQUE(name)
);

CREATE TABLE bar (
    bar_id  SERIAL      NOT NULL PRIMARY KEY,
    name    VARCHAR(20) NOT NULL,
    foo_id  INTEGER     DEFAULT NULL REFERENCES foo(foo_id),
    UNIQUE(name)
);

CREATE TABLE baz (
    baz_id  SERIAL      NOT NULL PRIMARY KEY,
    name    VARCHAR(20) NOT NULL,
    foo_id  INTEGER     DEFAULT NULL REFERENCES foo(foo_id),
    bar_id  INTEGER     DEFAULT NULL REFERENCES bar(bar_id),
    UNIQUE(name)
);

Define the ORM:

orm my_orm => sub {
    db 'mydb';
    autofill sub {
        autorow 'My::Test::Row';
    };
};

Insert some data and use join:

my $con = orm('my_orm');

# Insert a row into foo
my $foo_a = $con->insert(foo => {name => 'a'});

# Insert 3 rows into bar that link to foo.
my $bar_a1 = $con->insert(bar => {name => 'a1', foo_id => $foo_a->foo_id});
my $bar_a2 = $con->insert(bar => {name => 'a2', foo_id => $foo_a->foo_id});
my $bar_a3 = $con->insert(bar => {name => 'a3', foo_id => $foo_a->foo_id});

# Insert a row into baz linked to foo_a and bar_a1
my $baz = $con->insert(baz => {name => 'a', foo_id => $foo_a->foo_id, bar_id => $bar_a1->bar_id});

my $h = $con->handle('foo')->left_join('bar')->left_join('baz', from => 'foo')->order_by(qw/a.foo_id b.bar_id c.baz_id/);

The handle can be used to fetch DBIx::QuickORM::Join::Row instances, that lets you get each component row object by alias:

my $one = $iter->first;

Getting component rows using by_alias() will return regular row objects, they will be the same references if the rows have already been fetched and are in memory/cache.

use Test2::V0 qw/ref_is/;

ref_is($one->by_alias('a'), $foo_a,  "Got the foo_a reference");
ref_is($one->by_alias('b'), $bar_a1, "Got the bar_a reference");
ref_is($one->by_alias('c'), $baz,    "Got the baz reference");

You can also directly access fields:

my $a_name = $one->field('a.name');

Immutators

These always return a new handle instance with a state that copies the original except where arguments would mutate it. The original handle is never modified.

$new_h = $h->auto_refresh()

$new_h = $h->no_auto_refresh()

Toggle auto_refresh on and off.

auto_refresh applies only to insert operations. If true then all row fields will be refreshed from the database after the insert is complete. Without auto_refresh only the primary key fields are pulled from the database post-insert, the rest of the fields in the row are assumed to contain the values used for insert. The auto-refresh behavior is desirable if triggers or other behaviors might modify the data once it is inserted.

$new_h = $h->sync()

Turn off async, aside, and forked flags returning a synchronous handle.

$new_h = $h->async()

The newly returned handle will run async operations.

$new_h = $h->aside()

The newly returned handle will run aside operations (async, but with a seperate DB connection)

$new_h = $h->forked()

The newly returned handle will run 'forked' operartions. This means the query is executed in a forked process with a new db connection, the results will be returned to the parent.

This can be used to emulate async operations on databases that do not support them, such as DBD::SQlite.

$new_h = $h->data_only()

The newly returned handle will return hashrefs instead of blessed row objects.

$new_h = $h->all_fields()

Make sure the handle selects all fields when fetching rows. Normally some rows may be omitted by default based on if they have an omit flag set.

$new_h = $h->and($WHERE)

Create a new handle that has a union of the original WHERE clause and the additional WHERE clause

SELECT ... WHERE old_where AND new_where

$new_h = $h->or($WHERE)

Create a new handle that has a union of the original WHERE clause or the additional WHERE clause

SELECT ... WHERE old_where OR new_where

$new_h = $h->internal_txns()

$new_h = $h->internal_transactions()

Enable internal transactions. These are mainly used in cases where an operation needs multiple queries.

$new_h = $h->no_internal_txns()

$new_h = $h->no_internal_transactions()

Disable internal transactions. These are mainly used in cases where an operation needs multiple queries.

Immucessors

These are methods that return their value if called without arguments, but return a clone of the handle with the new value set when provided with an argument.

$sql_builder = $h->sql_builder()
$new_h = $h->sql_builder($sql_builder): Can be used to get the SQL Builder that is already set, or create a clone fo the handle with a new sql_builder set.
$connection = $h->connection()
$new_h = $h->connection($connection): Can be used to get the connection of a handle, or to create a clone of the handle that uses a new connection.
$source = $h->source()
$new_h = $h->source($source): Can be used to get the connection of a source, or to create a clone of the source that uses a new connection.
$row = $h->row()
$new_h = $h->row($row): Can be used to get the connection of a row, or to create a clone of the row that uses a new connection.
$fields = $h->fields()
$new_h = $h->fields(\@fields): Can be used to get the fields of a handle, or to create a clone of the handle that uses the new fields.
$omit = $h->omit()
$new_h = $h->omit(\@omit): Can be used to get the omitted fields of a handle, or to create a clone of the handle that uses the new omitted fields.
$limit = $h->limit()
$new_h = $h->limit($limit): Can be used to get the limit of a handle, or to create a clone of the handle that uses the new limit.
$where = $h->where()
$new_h = $h->where($where): Can be used to get the where condition of a handle, or to create a clone of the handle that uses the new where condition.
$order_by = $h->order_by()
$new_h = $h->order_by(\@order_by): Can be used to get the order_by of a handle, or to create a clone of the handle that uses the new order_by.

State Accessors

$bool = $h->is_sync: True if the handle is synchronous.
$bool = $h->is_async: True if the handle is async.
$bool = $h->is_aside: True if the handle uses 'aside' operations (async but on a seperate db connection).
$bool = $h->is_forked: True if the handle uses 'forked' operations, (queries run in a child process on a second connection).
$bool = $h->using_internal_transactions: True if the handle is allowed to use internal transactions.

Results Fetchers

$row = $h->by_id($id)

$row = $h->by_id(\@id_vals)

$row = $h->by_id({field => $val})

Fetch a row by ID. If the row is already in cache no database query is needed.

$h->by_ids(@ids)

A convenience method for fetching several rows by ID. See by_id() above for ID formats.

$row = $h->vivify(\%ROW_DATA)

Create a row object witht he provided data. The Row will NOT be inserted into the database unless you call $row->insert or $row->save.

$row = $h->insert(\%ROW_DATA)

Insert the data into the database and return a proper row object for it.

$row = $h->insert_and_refresh(\%ROW_DATA)

Insert the data into the database and return a proper row object. The row will be refreshed to contain the actual stored data, including data modified by triggers. If the database supports 'returning on insert' then that will be used, otherwise the insert and fetch operations are wrapped in a single transaction, unless internal transactions are disabled in which case an exception may be thrown.

$h->update(\%CHANGES)

Apply the changes (field names and new values) to all rows matching the where condition.

$h->update($row_obj)

Write pending changes to the row.

$row = $h->upsert(\%ROW_DATA)

$row = $h->upsert_and_refresh(\%ROW_DATA)

These will either insert or update the row depending on if it already exists in the database.

Depending on SQL dialect it will usually result in a sql statement like one of these:

INSERT INTO example (id, name) VALUES (?, ?) ON CONFLICT(id) DO UPDATE SET name = ? RETURNING id
INSERT INTO example (id, name) VALUES (?, ?) ON DUPLICATE KEY UPDATE name = ? RETURNING id
INSERT INTO example (id, name) VALUES (?, ?) ON DUPLICATE KEY UPDATE name = ?

$h->delete

$h->delete($row)

$h->delete($where)

If no arguments are provided the handle will delete all applicable rows.

If a row is provided it will be deleted

If a where clause is provided then all rows it would find will be deleted.

If a row or where condition are provided they will override any that are already associated with the handle.

$row = $h->one()

Return a row matching the conditions on the handle, if any. Will return undef if there are no matching rows. Will throw an exception if the query returns more than 1 row.

In dat_only mode this will return the hashref of the returned row.

$row = $h->first()

Similar to one() above, but will not die if more than 1 row matches the query.

In dat_only mode this will return the hashref of the returned row.

@rows = $h->all

Return all matching rows.

This cannot be used in async mode, use iterator() instead as it provides mechanisms to check if the async query is ready.

In data_only mode this will return a list of hashrefs instead of blessed row objects.

my $iter = $h->iterator

Returns an DBIx::QuickORM::Iterator object that can be used to iterate over all rows.

my $iter = $h->iterator;
while (my $row = $iter->next) {
    ...;
}

If used in data_only mode then the rows will be hashrefs instead of blessed objects.

In Async mode the iterator will heve a $iter->ready() method you can use to check if the query is ready. For sync queries ready() will always return true.

$number = $h->count

Get the number of rows that the query would return.

$h->iterate(sub { my $row = shift; ... })

Run the callback for each row found.

In data_only mode this will provide hashrefs instead of blessed row objects.

SOURCE

The source code repository for DBIx-QuickORM can be found at http://github.com/exodist/DBIx-QuickORM/.

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

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

See http://dev.perl.org/licenses/

To install DBIx::QuickORM, copy and paste the appropriate command in to your terminal.

cpanm

cpanm DBIx::QuickORM

CPAN shell

perl -MCPAN -e shell
install DBIx::QuickORM

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)