
=head1 NAME

SQL::DBx::Simple - Simple CRUD extension for SQL::DB

=head1 VERSION

0.19_9. Development release.

=head1 SYNOPSIS

    use SQL::DB;
    use SQL::DBx::Simple;

    my $db = SQL::DB->connect($dsn);

    # INSERT INTO
    #   actors (id, name)
    # VALUES
    #   (1, 'John Smith')

    my $success = $db->insert(
        into   => 'actors',
        values => { id => 1, name => 'John Smith' },
    );

    # UPDATE
    #   actors
    # SET
    #   name = 'Jack Smith'
    # WHERE
    #   id = 1 AND name = 'John Smith'

    my $count = $db->update( 'actors',
        set   => { name => 'Jack Smith' },
        where => { id => 1, name => 'John Smith' },
    );

    # DELETE FROM
    #   actors
    # WHERE
    #   actor_id = 1 AND last_name = 'Jones'

    my $count = $db->delete(
        from  => 'actors',
        where => { actor_id => 1, last_name => 'Jones' },
    );

    # SELECT
    #   id, name
    # FROM
    #   actors
    # WHERE
    #   id = 1

    my $row = $db->select( ['id', 'name'],
        from => 'actors',
        where => { id => 1 },
    )

    print $row->id .':'. $row->name ."\n";


=head1 DESCRIPTION

B<SQL::DBx::Simple> is a Role that adds very simple Create, Retrieve,
Update and Delete (CRUD) actions to L<SQL::DB>.  The added methods are
designed to get you up and running quickly when your query data is
already inside a hash. These methods are abstractions of the real API,
but should still read as much as possible like SQL.

The insert(), update() and delete() methods return the result of the
underlying L<DBI> do() call, which is typically the number of rows
affected. Security conscious coders will be pleased to know that all
user-supplied values are bound properly using L<DBI> "bind_param()".

=head1 METHODS

=over 4

=item insert(into => $table, values => \%val) -> Int

Insert a row into the database.

=item update($table, set => \%values, where => \%expr) -> Int

Update rows in the database.  This method is retricted to the wholesale
replacement of column values (no database-side calculations etc).
Multiple WHERE key/values are only 'AND'd together. An 'undef' value
maps to SQL's NULL value.

=item delete(from => $table, where => \%expr) -> Int

Delete rows from the database.

=item select(\@columns, from => $table, where => \%expr) -> @Obj

Retrieve rows from the database as a list of objects in array context,
or a single object in scalar context. These objects (blessed into a
dynamically created class) have an accessor method for each column.

The first argument to the select() method must be either an array
reference of column names, or a single '*'. If the array reference is
given only the columns specified will be retrieved from the database.

=back

=head1 SEE ALSO

L<SQL::DB>, L<Moo::Role>

=head1 AUTHOR

Mark Lawrence E<lt>nomad@null.netE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2011 Mark Lawrence <nomad@null.net>

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 3 of the License, or (at your
option) any later version.

