view release on metacpan or  search on metacpan

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

                    my %params = @_;
                    my $link = $params{link};

                    return "obtain_" . $link->other_table if $params{link}->unique;
                    return "select_" . $link->other_table . "s";
                };

                # You can provide custom names for field accessors when using autorow
                autoname field_accessor => sub {
                    my %params = @_;
                    return "get_$params{name}";
                };
            };
        };
    };

=head2 YOUR APP CODE

    package My::App;
    use My::Orm qw/orm/;

    # Get a connection to the orm
    # Note: This will return the same connection each time, no need to cache it yourself.
    # See DBIx::QuickORM::Connection for more info.
    my $orm = orm('my_orm');

    # See DBIx::QuickORM::Handle for more info.
    my $h = $orm->handle('people', {surname => 'smith'});
    for my $person ($handle->all) {
        print $person->field('first_name') . "\n"
    }

    my $new_h = $h->limit(5)->order_by('surname')->omit(@large_fields);
    my $iterator = $new_h->iterator; # Query is actually sent to DB here.
    while (my $row = $iterator->next) {
        ...
    }

    # Start an async query
    my $async = $h->async->iterator;

    while (!$async->ready) {
        do_something_else();
    }

    while (my $item = $iterator->next) {
        ...
    }

See L<DBIx::QuickORM::Connection> for details on the object returned by
C<< my $orm = orm('my_orm'); >>.

See L<DBIx::QuickORM::Handle> for more details on handles, which are similar to
ResultSets from L<DBIx::Class>.

=head1 RECIPES

=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 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',

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

        attributes { foo => 1 };
    };

Or:

    db mydb => sub {
        attributes foo => 1;
    };

=item C<host $HOSTNAME>

=item C<hostname $HOSTNAME>

Provide a hostname or IP address for database connections

    db mydb => sub {
        host 'mydb.mydomain.com';
    };

=item C<port $PORT>

Provide a port number for database connection.

    db mydb => sub {
        port 1234;
    };

=item C<socket $SOCKET_PATH>

Provide a socket instead of a host+port

    db mydb => sub {
        socket '/path/to/db.socket';
    };

=item C<user $USERNAME>

=item C<username $USERNAME>

provide a database username

    db mydb => sub {
        user 'bob';
    };

=item C<pass $PASSWORD>

=item C<password $PASSWORD>

provide a database password

    db mydb => sub {
        pass 'hunter2'; # Do not store any real passwords in plaintext in code!!!!
    };

=item C<creds sub { return \%CREDS }>

Allows you to provide a coderef that will return a hashref with all the
necessary database connection fields.

This is mainly useful if you credentials are in an encrypted YAML or JSON file
and you have a method to decrypt and read it returning it as a hash.

    db mydb => sub {
        creds sub { ... };
    };

=item C<connect sub { ... }>

=item C<connect \&connect>

Instead of providing all the other fields, you may specify a coderef that
returns a L<DBI> connection.

B<IMPORTANT:> This function must always return a new L<DBI> connection it
B<MUST NOT> cache it!

    sub mydb => sub {
        connect sub { ... };
    };

=item C<dsn $DSN>

Specify the DSN used to connect to the database. If not provided then an
attempt will be made to construct a DSN from other parameters, if they are
available.

    db mydb => sub {
        dsn "dbi:Pg:dbname=foo";
    };

=item C<< server $NAME => sub { ... } >>

Used to define a server with multiple databases. This is a way to avoid
re-specifying credentials for each database you connect to.

You can use C<< db('server_name.db_name') >> to fetch the database.

Basically this allows you to specify any database fields once in the server, then
define any number of databases that inherit them.

Example:

    server pg => sub {
        host 'pg.myapp.com';
        user $USER;
        pass $PASS;
        attributes { work_well => 1 }

        db 'myapp';       # Points at the 'myapp' database on this db server
        db 'otherapp';    # Points at the 'otherapp' database on this db server

        # You can also override any if a special db needs slight modifications.
        db special => sub {
            attributes { work_well => 0, work_wrong => 1 };
        };
    };

    orm myapp => sub {
        db 'pg.myapp';
        ...;
    };

    orm otherapp => sub {
        db 'pg.otherapp';
        ...;
    };

=item C<< schema $NAME => sub { ... } >>

=item C<< $schema = schema($NAME) >>

=item C<< $schema = schema($NAME => sub { ... }) >>

Used to either fetch or define a schema.

When called with only 1 argument it will fetch the schema with the given name.

When used inside an ORM builder it will set the schema for the ORM (all ORMs
have exactly one schema).

When called with 2 arguments it will define the schema using the coderef as a
builder.

When called in a non-void context it will return the compiled schema, otherwise
it adds it to the ORM class.

    # Define the 'foo' schema:
    schema foo => sub {
        table a => sub { ... };
        table b => sub { ... };
    };

    # Fetch it:
    my $foo = schema('foo');