https://github.com/alranel/dbix-lite
Chained and minimal ORM
https://github.com/alranel/dbix-lite
cpan dbi perl
Last synced: about 1 year ago
JSON representation
Chained and minimal ORM
- Host: GitHub
- URL: https://github.com/alranel/dbix-lite
- Owner: alranel
- Created: 2012-02-08T10:46:11.000Z (over 14 years ago)
- Default Branch: master
- Last Pushed: 2024-10-31T17:10:01.000Z (over 1 year ago)
- Last Synced: 2025-04-12T19:52:40.476Z (about 1 year ago)
- Topics: cpan, dbi, perl
- Language: Perl
- Homepage:
- Size: 153 KB
- Stars: 12
- Watchers: 3
- Forks: 5
- Open Issues: 7
-
Metadata Files:
- Readme: README.pod
Awesome Lists containing this project
README
=pod
=encoding UTF-8
=head1 NAME
DBIx::Lite - Chained and minimal ORM
=head1 VERSION
version 0.37
=head1 SYNOPSIS
use DBIx::Lite;
my $dbix = DBIx::Lite->new(driver_name => 'Pg'); # disconnected mode
my $dbix = DBIx::Lite->new(dbh => $dbh);
my $dbix = DBIx::Lite->connect("dbi:Pg:dbname=$db", $user, $passwd, {pg_enable_utf8 => 1});
# build queries using chained methods -- no schema definition required
my $authors_rs = $dbix->table('authors');
my $authors_rs = $dbix->table('authors')->search({ country => 'IT' });
my $books_rs = $dbix
->table('books')
->select('id', 'title', 'year')
->left_join('authors', { author_id => 'id' })
->select_also(['authors.name' => 'author_name'])
->order_by('year');
# retrieve rows and columns -- still no schema definition required
my @authors = $authors_rs->all;
my $author = $authors_rs->search({ id => 1 })->single;
while (my $book = $books_rs->next) {
printf "%s (%s)\n", $book->title, $book->author_name; # automatic accessor methods
}
my @author_names = $authors_rs->get_column('name');
my $book_count = $books_rs->count;
# manipulate rows
my $book = $dbix->table('books')->insert({ name => 'Camel Tales', year => 2012 });
$books_rs->search({ year => { '<' => 1920 } })->update({ very_old => 1 });
$authors_rs->search({ age => { '>' => 99 } })->delete;
# define a primary key and get more features
$dbix->schema->table('authors')->autopk('id');
my $author = $dbix_lite->table('authors')->find(2);
$author->update({ age => 40 });
$author->delete;
# define relationships
$dbix->schema->one_to_many('authors.id' => 'books.author_id', 'author');
my $author = $books->author;
my $books_rs = $author->books->search({ year => 2012 });
my $book = $author->insert_related('books', { title => "A Camel's Life" });
# define custom object classes
$dbix->schema
->table('subjects')
->class('My::Subject')
->resultset_class('My::Subject::ResultSet');
=head1 ABSTRACT
Many ORMs and DBI abstraction layers are available on CPAN, one of the most notables
being L which provides the most powerful features to handle database
contents using OOP.
DBIx::Lite was written with some goals in mind, that no other available module provides.
Such goals/key features are:
=over 4
=item no need to define your database schema (most features work without one and some advanced features only require some bits, and still not the full table definitions)
=item no need to connect to database: the module can just generate SQL for you
=item chained methods with lazy SQL generation
=item joins/relationships
=item optional custom classes for results and resultsets with custom methods
=item L syntax
=item paging features (with L)
=back
=head1 METHODS
Instantiating a DBIx::Lite object isn't more difficult than just writing:
my $dbix = DBIx::Lite->new(driver_name => 'Pg');
Driver name is the name of the DBI module you expect to use. We need to specify it as the
generated SQL will depend on the driver.
This constructor will give you an unconnected object, that you can use to generate SQL commands using
the L, L, L and L methods without
executing it.
If you want to connect to a database you can pass a pre-connected database handle with the
C argument or you can supply your connection options to the C method. All
arguments passed to C will be just passed to L which will be
used to manage your connection under the hood.
my $dbix = DBIx::Lite->new(dbh => $dbh);
my $dbix = DBIx::Lite->connect("dbi:Pg:dbname=$db", $user, $passwd, {pg_enable_utf8 => 1});
Note that C can be called as an object method too, if you want to connect an
unconnected DBIx::Lite object at a later stage:
my $dbix = DBIx::Lite->new;
$dbix->connect("dbi:Pg:dbname=$db", $user, $passwd);
=head2 new
This class method may accept the following optional arguments:
=over 4
=item I
This argument allows you to supply a pre-made L database handle. See the example in
the previous paragraph.
=item I
This argument allows you to supply a pre-made L object.
=item I
This argument allows you to supply a pre-made L object. If none is
provided, a new empty one will be created for each DBIx::Lite object. This argument is
useful if you want to prepare your schema in advance and reutilize it across multiple
connections.
=item I
This argument allows you to supply options for L module. Here is
example for MySQL DB backend to quote fields names with backtick to allow using reserved
words as column's names.
my $dbix = DBIx::Lite->new( abstract => { quote_char => '`', name_sep => '.' } );
$dbix->connect("DBI:mysql:$db_dbname;host=$db_host", $db_username, $db_password);
=back
=head2 connect
This methods accepts a list of arguments that are passed to L. It
returns the DBIx::Lite object. It can be called either as class or object method.
=head2 table
This method accepts a table name and returns a L object on which
you can chain its methods to build your query.
my $rs = $dbix->table('books');
=head2 schema
This method returns our L object which may hold the definitions
required for some advanced feature of DBIx::Lite. You can call then call its methods:
$dbix->schema->table('authors')->autopk('id');
See the L documentation for an explanation of its methods.
=head2 dbh
This method returns a L database handle that you can use to perform manual queries.
=head2 txn
This method accepts a coderef which will be run inside a transaction.
$dbix->txn(sub {
$dbix->table('books')->update({ year => 2015 });
});
=for Pod::Coverage dbh_do driver_name
=head1 AUTHOR
Alessandro Ranellucci
=head1 COPYRIGHT AND LICENSE
This software is copyright (c) 2024 by Alessandro Ranellucci.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
=cut