view release on metacpan or  search on metacpan

lib/DBIx/QuickORM/Manual/QuickStart.pm  view on Meta::CPAN

package DBIx::QuickORM::Manual::QuickStart;
use strict;
use warnings;

our $VERSION = '0.000022';

1;

__END__

=head1 NAME

DBIx::QuickORM::Manual::QuickStart - A friendly first tour of
L<DBIx::QuickORM>.

=head1 DESCRIPTION

This is the first page to read if you are new to L<DBIx::QuickORM>. It walks
you from an empty script to fetching rows, inserting rows, following relations,
and running a transaction - all using the C<quick()> interface, which needs no
schema definition at all.

The idea: point C<quick()> at a database, and DBIx::QuickORM introspects all
the table and column metadata directly from the live database. You get back a
ready-to-use connection and start treating rows as objects immediately.

When you want more control (defining your own schema, custom row classes,
joins, and so on) follow the links at the end of this page. For the bigger
picture and the full set of guides, see L<DBIx::QuickORM::Manual>.

=head1 CONNECT

Use the C<quick()> class method. Provide exactly one of C<credentials> or
C<connect>. The SQL dialect is detected automatically from the DSN (or the
C<dbd>), so you usually do not need to think about it.

    use DBIx::QuickORM;

    my $con = DBIx::QuickORM->quick(
        credentials => {
            dsn   => $dsn,        # e.g. "dbi:Pg:dbname=myapp;host=..."
            user  => $user,
            pass  => $pass,
        },

        # Type classes (under DBIx::QuickORM::Type unless fully qualified)
        # used to auto inflate/deflate matching columns.
        auto_types => ['JSON', 'UUID'],
    );

If you would rather hand DBIx::QuickORM a callback that produces a fresh DBI
handle, use C<connect> instead of C<credentials>:

    my $con = DBIx::QuickORM->quick(
        connect => sub { DBI->connect($dsn, $user, $pass) },
    );

C<$con> is a L<DBIx::QuickORM::Connection>. It self-heals: it can reconnect in
place and retry work, preserving its row cache. That is the only object you
need to keep around.

=head2 OPTIONS

C<quick()> accepts a few optional affordances:

=over 4

=item auto_types => \@type_classes

Type classes (under C<DBIx::QuickORM::Type> unless fully qualified) used to
auto inflate/deflate matching columns. See L<DBIx::QuickORM::Manual::Types>.

=item dialect => $name

Force a specific dialect instead of detecting it from the DSN/driver.

=item autorow => 0 | 1 | $prefix

Whether to generate a row class per table (with named field and relation
accessors). Defaults to B<0> (off - you get generic L<DBIx::QuickORM::Row>
objects). Pass B<1> to enable it under a generated namespace, or pass a
namespace prefix string (e.g. C<'My::Row'>) to generate classes like
C<My::Row::Users>. See L<DBIx::QuickORM::Manual::Schema>.

=item row_manager => $class_or_instance

The row manager that provides per-connection row caching/identity. Defaults
to B<C<'DBIx::QuickORM::RowManager::Cached'>>. See
L<DBIx::QuickORM::Manual::Caching>.

=back

=head1 FETCH ROWS

A B<handle> is the interface for talking to a table. Get one with
C<< $con->handle('table_name') >>, then ask it for rows.

    # Every row in the 'users' table, as Row objects:
    my @users = $con->handle('users')->all;

    # Narrow it down with a where clause, then fetch:
    my @smiths = $con->handle('users')->where({surname => 'smith'})->all;

    # Exactly one matching row (dies if more than one matches):
    my $user = $con->handle('users')->where({email => $email})->one;

When you want a row by primary key, C<by_id> is the shortcut:

    my $user = $con->by_id(users => 5);

For convenience the connection proxies the common handle methods directly, so
the simple cases need no explicit handle: