NAME

DBIx::QuickORM - Actively maintained Object Relational Mapping that makes getting started Quick and has a rich feature set.

EXTREMELY EARLY VERSION WARNING!

THIS IS A VERY EARLY VERSION!

About 90% of the functionality from the features section is written.
About 80% of the features have been listed.
About 40% of the written code is tested.
About 10% of the documentation has been written.

If you want to try it, go for it. Some of the tests give a pretty good idea of how to use it.

DO NOT USE THIS FOR ANYTHING PRODUCTION it is not ready yet.

The API can and will change!

DESCRIPTION

An actively maintained ORM tool that is quick and easy to start with, but powerful and expandable for long term and larger projects. An alternative to DBIx::Class, but not a drop-in replacement.

SCOPE

The primary scope of this project is to write a good ORM for perl. It is very easy to add scope, and try to focus on things outside this scope. I am not opposed to such things being written around the ORM functionality, afterall the project has a lot of useful code, and knowledge of the database. But the primary focus must always be the ORM functionality, and it must not suffer in favor of functionality beyond that scope.

SYNOPSIS

FIXME!

MOTIVATION

The most widely accepted ORM for perl, DBIx::Class is for all intents and purposes, dead. There is only 1 maintainer, and that person has stated that the project is feature complete. The project will recieve no updates apart from critical bugs. The distribution has been marked such that it absolutely can never be transferred to anyone else.

There are 4 ways forward:

Use DBIx::Class it as it is.

Many people continue to do this.

Monkeypatch DBIx::Class

I know a handful of people who are working on a way to do this that is not terrible and will effectively keep DBIx::Class on life support.

Fork DBIx::Class

I was initially going to take this route. But after a couple hours in the codebase I realized I dislike the internals of DBIx::Class almost as much as I dislike using its interface.

Write an alternative

I decided to take this route. I have never liked DBIx::Class, I find it difficult to approach, and it is complicated to start a project with it. The interface is unintuitive, and the internals are very opaque.

My goal is to start with the interface, make it approachable, easy to start, etc. I also want the interface to be intuitive to use. I also want expandability. I also want to make sure I adopt the good ideas and capabilities from DBIx::Class. Only a fool would say DBIx::Class has nothing of value.

MAINTENANCE COMMITMENT

I want to be sure that what happened to DBIx::Class cannot happen to this project. I will maintain this as long as I am able. When I am not capable I will let others pick up where I left off.

I am stating here, in the docs, for all to see for all time:

If I become unable to maintain this project, I approve of others being given cpan and github permissions to develop and release this distribution.

Peferably maint will be handed off to someone who has been a contributor, or to a group of contributors, If none can be found, or none are willing, I trust the cpan toolchain group to takeover.

FEATURE/GOAL OVERVIEW

Quick to start

It should be very simple to start a project. The ORM should stay out of your way until you want to make it do something for you.

Intuitive

Names, interfaces, etc should make sense and be obvious.

Declarative syntax

Look at the "DECLARATIVE INTERFACE" section below, or the "SYNOPSIS" section above.

SQL <-> Perl conversion

It can go either way.

Generate the perl schema from a populated database.

my $orm = orm 'MyOrm' => sub {
    # First provide db credentials and connect info
    db { ... };

    # Tell DBIx::QuickORM to do the rest
    autofill();
};

# Built for you by reading from the database.
my $schema = $orm->schema;

Generate SQL to populate a database from a schema defined in perl.

See DBIx::QuickORM::Util::SchemaBuilder for more info.

Async query support

Async query support is a key and first class feature of DBIx::QuickORM.

Single async query - single connection

Launch an async query on the current connection, then do other stuff until it is ready.

See DBIx::QuickORM::Select::Async for full details. but here are some teasers:

# It can take more args than just \%where, this is just a simply case
my $async = $orm->async(\%where)->start;
until ($async->ready) { ... };
my @rows = $async->all;

You can also turn any select into an async:

my $select = $orm->select(...);
my $async = $orm->async;
$async->start;

Multiple concurrent async query support - multiple connections on 1 process

DBIx::QuickORM calls this an 'aside'. See DBIx::QuickORM::Select::Aside for more detail.

In this case we have 2 queries executing simultaneously.

my $aside  = $orm->aside(\%where)->start;    # Runs async query on a new connection
my $select = $orm->select(\%where);
my @rows1  = $select->all;
my @rows2  = $aside->all;

Note that if both queries return some of the same rows there will only be 1 copy in cache, and both @row arrays will have the same object reference.

Multiple concurrent async query support - emulation via forking

See DBIx::QuickORM::Select::Forked for more detail.

Similar to the 'aside' functionality above, but instead of running an async query on a new connection, a new process is forked, and that process does a synchronous query and returns the results. This is useful for emulating aside/async with databases that do not support it such as SQLite.

First class inflation and deflation (Conflation)

Inflation and Deflation of columns is a first-class feature. But since saying 'inflation and deflation' every time is a chore DBIx::QuickORM shortens the concept to 'conflation'. No, the word "conflation" is not actually related to "inflation" or "deflation", but it is an amusing pun, specially since it still kind of works with the actual definition of "conflation".

If you specify that a column has a conflator, then using my $val = $row->column('name') will give you the inflated form. You can also set the column by giving it either the inflated or deflated form. You also always have access to the raw values, and asking for either the 'stored' or 'dirty' value will give the raw form.

You can also use inflated forms in the %where argument to select/find.

The rows are also smart enough to check if your inflated forms have been mutated and consider the row dirty (in need of saving or discarding) after the mutation. This is done by deflating the values to compare to the stored form when checking for dirtyness.

If your inflated values are readonly, locked restricted hashes, or objects that implement the 'qorm_immutible' method (and it returns true). Then the row is smart enough to skip checking them for mutations as they cannot be mutated.

Oh, also of note, inflated forms do not need to be blessed, nor do they even need to be references. You could write a conflator that inflates string to have "inflated: " prefixed to them, and no prefix when they are raw/deflated. A conflator that encrypts/decrypts passively is also possible, assuming the encrypted and decrypted forms are easily distinguishable.

UUID, UUID::Binary, UUID::Stringy

Automatically inflate and deflate UUID's. Your database can store it as a native UUID, a BIN(16), a VARCHAR(36), or whatever. Tell the orm the row should be conflated as a UUID and it will just work. You can set the value by providing a string, binary data, or anything else the conflator recognizes. In the DB it will store the right type, and in perl you will get a UUID object.

schema sub {
    table my_table => sub {
        column thing_uuid => sub {
            conflate 'UUID'; # OR provide '+Your::Conflator', adds 'DBIx::QuickORM::Conflator::' without the '+'
        };
    };
};

DBIx::QuickORM::Conflator::UUID

Inflates to an object of this class, deflates to whatever the database column type is. Object stringifies as a UUID string, and you can get both the string and binary value from it through accessors.

If generating the SQL to populate the db this will tell it the column should be the 'UUID' type, and will throw an exception if that type is not supported by the db.

DBIx::QuickORM::Conflator::UUID::Binary

This is useful only if you are generating the schema SQL to populate the db and the db does not support UUID types. This will create the column using a binary data type like BIN(16).

DBIx::QuickORM::Conflator::UUID::Stringy

This is useful only if you are generating the schema SQL to populate the db and the db does not support UUID types. This will create the column using a stringy data type like VARCHAR(36).

JSON, JSON::ASCII

This conflator will inflate the JSON into a perl data structure and deflate it back into a JSON string.

This uses Cpanel::JSON::XS under the hood.

DBIx::QuickORM::Conflator::JSON

Defaults to $json->utf8->encode_json

This produces a utf8 encoded json string.

DBIx::QuickORM::Conflator::JSON::ASCII

Defaults to $json->ascii->encode_json

This produces an ASCII encoded json string with non-ascii characters escaped.

DateTime - Will not leave a mess with Data::Dumper!

DBIx::QuickORM::Conflator::DateTime

This conflator will inflate dates and times into DateTime objects. However it also wraps them in an DBIx::QuickORM::Util::Mask object. This object hides the DateTime object in a sub { $datetime }. When dumped by Data::Dumper you get something like this:

bless( [
         '2024-10-26T06:18:45',
         sub { "DUMMY" }
       ], 'DBIx::QuickORM::Conflator::DateTime' );

This is much better than spewing the DateTime internals, whcih can take several pages of scrollback.

You can still call any valid DateTime method on this object and it will delegate it to the one that is masked beind the coderef.

Custom conflator

See the DBIx::QuickORM::Role::Conflator role.

Custom on the fly

Declarative:

my $conflator = conflator NAME => sub {
    inflate { ... };
    deflate { ... };
};

OOP:

my $conflator = DBIx::QuickORM::Conflator->new(
    name => 'NAME',
    inflate => sub { ... },
    defalte => sub { ... }
);

Multiple ORM instances for different databases and schemas

db develop    => sub { ... };
db staging    => sub { ... };
db production => sub { ... };

my $app1 = schema app1 => { ... };
my $app2 = schema app2 { ... };

orm app1_dev => sub {
    db 'develop';
    schema 'app1';
};

orm app2_prod => sub {
    db 'production';
    schema 'app2';
};

orm both_stage => sub {
    db 'staging';

    # Builds a new schema object, does not modify either original
    schema $app1->merge($app2);
};

"Select" object that is very similar to DBIx::Class's ResultSet

ResultSet was a good idea, regardless of your opinion on DBIx::Class. The DBIx::QuickORM::Select objects implement most of the same things.

my $sel = $orm->select('TABLE/SOURCE', \%where)
my $sel = $orm->select('TABLE/SOURCE', \%where, $order_by)
my $sel = $orm->select('TABLE/SOURCE', where => $where, order_by => $order_by, ... );
$sel = $sel->and(\%where);
my @rows = $sel->all;
my $row = $sel->next;
my $total = $sel->count;

Find exactly 1 row

# Throws an exception if multiple rows are found.
my $row = $orm->find($source, \%where);

Fetch just the data, no row object (bypasses cache)

my $data_hashref = $orm->fetch($source, \%where);

Uses SQL::Abstract under the hood for familiar query syntax

See SQL::Abstract.

Built in support for transactions and nested transactions (savepoints)

See DBIx::QuickORM::Transaction and "TRANSACTIONS" in DBIx::QuickORM::ORM for additional details.

$orm->txn_do(sub { ... });

Void context will commit if there are no exceptions. It will rollback the transaction and re-throw the exception if it encounters one.

$res = $orm->txn_do(sub { ... });

Scalar context.

On success it will commit and return whatever the sub returns, or the number 1 if the sub returns nothing, or anything falsy. If you want to return a false value you must send it as a ref, or use the list context form.

If an exception is thrown by the block then the transaction will be rolled back and $res will be false.

($ok, $res_or_err) = $orm->txn_do(sub { ... });

List context.

On success it will commit and return (1, $result).

If an exception occurs in the block then the transaction will be rolled back, $ok will be 0, and $ret_or_err will contain the exception.

$orm->txn_do(sub {
    my $txn = shift;

    # Nested!
    my ($ok, $res_or_err) = $orm->txn_do(sub { ... });

    if ($ok) { $txn->commit }
    else     { $txn->rollback };

    # Automatic rollback if an exception is thrown, or if commit is not called
});

# Commit if no exception is thrown, rollback on exception
$orm->txn_do(sub { ... });

Or manually:

my $txn = $orm->start_txn;

if ($ok) { $txn->commit }
else     { $txn->rollback };

# Force a rollback unless commit or rollback were called:
$txn = undef;

Caching system

Each DBIx::QuickORM::ORM instance has its own cache object.

Default cache: Naive, only 1 copy of any row in active memory

DBIx::QuickORM::Cache::Naive is a basic caching system that insures you only have 1 copy of any specific row at any given time (assuming it has a primary key, no cahcing is attempted for rows with no primary key).

Note: If you have multiple ORMs connecting to the same db, they do not share a cache and you can end up with the same row in memory twice with 2 different references.

'None' cache option to skip caching, every find/select gets a new row instance

You can also choose to use DBIx::QuickORM::Cache::None which is basically a no-op for everything meaning there is no cache, every time you get an object from the db it is a new copy.

Write your own cache if you do not like these

Write your own based on the DBIx::QuickORM::Cache base class.

Multiple databases supported:

Database interactions are defined by DBIx::QuickORM::DB subclasses. The parent class provides a lot of generic functionality that is fairly universal. But the subclasses allow you to specify if a DB does or does not support things, how to translate type names from other DBs, etc.

PostgreSQL

Tells the ORM what features are supported by PostgreSQL, and how to access them.

See DBIx::QuickORM::DB::PostgreSQL, which uses DBD::Pg under the hood.

MySQL (Generic)

Tells the ORM what features are supported by any generic MySQL, and how to access them.

This FULLY supports both DBD::mysql and DBD::MariaDB for connections, pick whichever you prefer, the DBIx::QuickORM::DB::MySQL class is aware of the differences and will alter behavior accordingly.

MySQL (Percona)

Tells the ORM what features are supported by Percona MySQL, and how to access them.

This FULLY supports both DBD::mysql and DBD::MariaDB for connections, pick whichever you prefer, the DBIx::QuickORM::DB::MySQL and DBIx::QuickORM::DB::Percona classes are aware of the differences and will alter behavior accordingly.

MariaDB

Tells the ORM what features are supported by MariaDB, and how to access them.

This is essentially MySQL + the extra features MariaDB supports.

This FULLY supports both DBD::mysql and DBD::MariaDB for connections, pick whichever you prefer, the DBIx::QuickORM::DB::MySQL and DBIx::QuickORM::DB::MariaDB classes are aware of the differences and will alter behavior accordingly.

SQLite

Tells the ORM what features are supported by SQLite, and how to access them.

See DBIx::QuickORM::DB::SQLite, which uses DBD::SQLite under the hood.

Write your own orm <-> db link class

Take a look at DBIx::QuickORM::DB to see what you need to implement.

Temporary tables and views

Each ORM object DBIx::QuickORM::ORM has the static schema it is built with, but it also has a second 'connection' schema. Using this second schema you can define temporary views and tables (on supported databases).

$orm->create_temp_table(...);
$orm->create_temp_view(...);

See the DBIx::QuickORM::ORM documentation for more details.

Highly functional Row class, ability to use custom ones

DBIx::QuickORM::Row is the base class for rows, and the default one used for rows that are returned. It provides several methods for getting/setting columns, including directly accessing stored, pending, and inflated values. It also has methods for finding and fetching relations.

This row class does not provide any per-column accessors. For those you need one of the following:

DBIx::QuickORM::Row::AutoAccessors

This row class uses AUTOLOAD to generate accessors based on column names on the fly. So my $val = $row->foo is the same as $row->column('foo').

It also generates accessors for relationships on the fly.

Create your own row subclasses and tell the schema to use them.

table foo => sub {
    row_class 'My::Row::Class::Foo';
};

Create a class that defines the table and generates a table specific row class

My::Table::Foo.pm:

package My::Table::Foo
use DBIx::QuickORM ':TABLE_CLASS';

use DBIx::QuickORM::MetaTable foo => sub {
    column id => ...;
    column foo => ...;

    # Declarative keywords are removed after this scope ends.
};

# There are now accessors for all the columns and relationships.

sub whatever_methods_you_want {
    my $self = shift;
    ...
}

Elsware...

orm MyORM => sub {
    table My::Table::Foo;

    # or to load a bunch:
    tables 'My::Table'; # Loads all My::Table::* tables
};

Relation mapping and pre-fetching

TODO: Fill this in.

Plugin system

There are a lot of hooks, essentially a plugin is either a codered called for all hooks (with params telling you about the hook, or they are classes/objects that define the 'qorm_plugin_action()" method or that consume the DBIx::QuickORM::Role::Plugin role.

plugin sub { ... }; # On the fly plugin writing
plugin Some::Plugin; # Use a plugin class (does not have or need a new method)
plugin Other::Plugin->new(...); Plugin that needs to be blessed

Bigger example:

plugin sub {
    my $self = shift;
    my %params     = @_;
    my $hook       = $params{hook};
    my $return_ref = $params{return_ref};

    ...

    # if the hook expects you to return a value, instead of modifying a ref
    # in %params, then the return_ref will have a scalar reference to set.
    ${return_ref} = $out if defined($return_ref);
};

Define custom plugin hooks in your custom tools:

plugin_hook NAME => \%params; # Any/All plugins can take action here.

Current hooks

auto_conflate => (data_type => $dtype, sql_type => $stype, column => $col, table => $table): Use this to automatically inject conflation when auto-generating perl-side schema from a populated db.
post_build => (build_params => \%params, built => $out, built_ref => \$out): Called after building an object (ORM, Schema, DB, etc).
pre_build => (build_params => \%params): Called before building an object (ORM, Schema, DB, etc).
relation_name => (default_name => $alias, table => $table, table_name => $tname, fk => $fk): use to rename relations when auto-generating perl-side schema from a populated db.
sql_spec => (column => $col, table => $table, sql_spec => $spec): Opportunity to modify the DBIx::QuickORM::SQLSpec data for a row.
sql_spec => (table => $table, sql_spec => sql_spec()): Opportunity to modify the DBIx::QuickORM::SQLSpec data for a table.

Ability to customize relationship names when auto-generating perl schema from SQL schema

TODO: Fill this in.

Does not use Moose under the hood (light weight)

Most objects in DBIx::QuickORM use Object::HashBase which is what Test2 uses under the hood. Object::HashBase is very lightweight and performant.

For roles DBIx::QuickORM uses Role::Tiny.

Using Data::Dumper on a row does not dump all the ORM internals

DBIx::QuickORM::Row objects need access to the source, and to the orm. If a reference to these was simply put into the row objects hashref then Data::Dumper is going to work hard to absolutely fill your scrollback with useless info every time you dump your row. DBIx::Class suffers from this issue.

For DBIx::QuickORM the source is an DBIx::QuickORM::Source object. And it is put into the $row->{source} hash key. But first it is masked using DBIx::QuickORM::Util::Mask so that when dumped with Data::Dumper you see this:

bless( {
         'source' => bless( [
                              'DBIx::QuickORM::Source=HASH(0x59d72c1c33c8)',
                              sub { "DUMMY" }
                            ], 'DBIx::QuickORM::Util::Mask' ),
         ...
                          }
       }, 'DBIx::QuickORM::Row' );

All methods that are valid on DBIx::QuickORM::Source can be called on the masked form and they will be delegated to the masked object.

This + the DateTime conflator mean that rows from DBIx::QuickORM can be dumped by Data::Dumper without wiping out your scrollback buffer.

DECLARATIVE INTERFACE

TODO - Fill this in.

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)

NAME

EXTREMELY EARLY VERSION WARNING!

DESCRIPTION

SCOPE

SYNOPSIS

MOTIVATION

MAINTENANCE COMMITMENT

FEATURE/GOAL OVERVIEW

Quick to start

Intuitive

Declarative syntax

SQL <-> Perl conversion

Generate the perl schema from a populated database.

Generate SQL to populate a database from a schema defined in perl.

Async query support

Single async query - single connection

Multiple concurrent async query support - multiple connections on 1 process

Multiple concurrent async query support - emulation via forking

First class inflation and deflation (Conflation)

UUID, UUID::Binary, UUID::Stringy

JSON, JSON::ASCII

DateTime - Will not leave a mess with Data::Dumper!

Custom conflator

Custom on the fly

Multiple ORM instances for different databases and schemas

"Select" object that is very similar to DBIx::Class's ResultSet

Find exactly 1 row

Fetch just the data, no row object (bypasses cache)

Uses SQL::Abstract under the hood for familiar query syntax

Built in support for transactions and nested transactions (savepoints)

Caching system

Default cache: Naive, only 1 copy of any row in active memory

'None' cache option to skip caching, every find/select gets a new row instance

Write your own cache if you do not like these

Multiple databases supported:

PostgreSQL

MySQL (Generic)

MySQL (Percona)

MariaDB

SQLite

Write your own orm <-> db link class

Temporary tables and views

Highly functional Row class, ability to use custom ones

Relation mapping and pre-fetching

Plugin system

Current hooks

Ability to customize relationship names when auto-generating perl schema from SQL schema

Does not use Moose under the hood (light weight)

Using Data::Dumper on a row does not dump all the ORM internals

DECLARATIVE INTERFACE

SOURCE

MAINTAINERS

AUTHORS

COPYRIGHT

Module Install Instructions