view release on metacpan or  search on metacpan

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

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

our $VERSION = '0.000022';

1;

__END__

=head1 NAME

DBIx::QuickORM::Manual::Recipes - A hub of focused, task-oriented recipes for L<DBIx::QuickORM>.

=head1 DESCRIPTION

This is a hub of focused, task-oriented recipes for L<DBIx::QuickORM>. Each
recipe below solves a specific problem; for broader topics see the guides
linked under L</SEE ALSO>.

=head2 DEFINE DB LATER

In some cases you may want to define your orm/schema before you have your
database credentials. Then you want to add the database later in an app/script
bootstrap process.

Schema:

    package My::Schema;
    use DBIx::QuickORM;

    orm MyORM => sub {
        autofill;
    };

Bootstrap process:

    package My::Bootstrap;
    use DBIx::QuickORM only => [qw/db db_name host port user pass/];
    use My::Schema;

    sub import {
        # Get the orm (the `orm => ...` param is required to prevent it from attempting a connection now)
        my $orm = qorm(orm => 'MyORM');

        return if $orm->db; # Already bootstrapped

        my %db_params = decrypt_creds();

        # Define the DB
        my $db = db {
            db_name 'quickdb';
            host $db_params{host};
            port $db_params{port};
            user $db_params{user};
            pass $db_params{pass};
        };

        # Set the db on the ORM:
        $orm->db($db);
    }

Your app:

    package My::App;

    # Get the qorm() subroutine
    use My::Schema;

    # This will do the db bootstrap
    use My::Bootstrap;

    # Connect to the database with the ORM
    my $con = qorm('MyORM');

=head2 SCHEMA WITH NO DATABASE, ADD A CONNECT CALLBACK LATER

Like L</"DEFINE DB LATER">, but instead of credentials you attach your own
C<connect> callback (any sub that returns a fresh L<DBI> handle) right before
you need the connection. This is handy when the connection comes from
something you build yourself - a pool, a tunnel, an already-open handle, and
so on.

Define the schema with no database at all:

    package My::Schema;
    use DBIx::QuickORM;

    orm MyORM => sub {
        # No db here - just the schema.
        schema my_schema => sub {
            table users => sub {
                column id   => sub { primary_key; identity; not_null };
                column name => sub { type \'VARCHAR(128)'; affinity 'string'; not_null };
            };
        };
    };

Then, just before you get a connection, build a database from a C<connect>
callback and set it on the ORM:

    use DBIx::QuickORM only => [qw/db dialect connect/];
    use My::Schema;

    # 'orm => ...' returns the ORM without trying to connect yet.
    my $orm = qorm(orm => 'MyORM');

    $orm->db(db {
        dialect 'PostgreSQL';                 # the dialect is still required
        connect sub { $pool->checkout_dbh };  # any sub returning a new DBI handle
    });

    # Now connect:
    my $con = $orm->connection;

The C<connect> callback must hand back a B<new> handle each time it is called
and must not cache or reuse one; the connection manages the handle's lifecycle
(see L<DBIx::QuickORM::Manual::Connections>).

=head2 RENAMING EXPORTS

When importing L<DBIx::QuickORM> you can provide
C<< rename => { name => new_name } >> mapping to rename exports.

    package My::ORM;
    use DBIx::QuickORM rename => {
        pass  => 'password',
        user  => 'username',
        table => 'build_table',
    };

B<Note> If you do not want to bring in the C<import()> method that normally
gets produced, you can also add C<< type => 'porcelain' >>.

    use DBIx::QuickORM type => 'porcelain';

Really any 'type' other than 'orm' and undef (which becomes 'orm' by default)
will work to prevent C<import()> from being exported to your namespace.