# PODNAME: Yancy::Backend

__END__

=pod

=head1 NAME

Yancy::Backend

=head1 VERSION

version 0.010

=head1 SYNOPSIS

    my $be = Yancy::Backend->new( $url );

    $result = $be->list( $collection, $where, $options );
    say "Total: " . $result->{total};
    say "Name: " . $_->{name} for @{ $result->{rows} };

    $item = $be->get( $collection, $id );
    $be->set( $collection, $id, $item );
    $be->delete( $collection, $id );
    $item = $be->create( $collection, $id, $item );

=head1 DESCRIPTION

A C<Yancy::Backend> handles talking to the database. Different Yancy
backends will support different databases. To use a backend, see
L</SUPPORTED BACKENDS>. To make your own backend, see L</METHODS> for
the list of methods you must implement, their arguments, and their
return values.

=head2 Terminology

Yancy backends work with collections, which are made up of items.
A collection is a set of items, like a database table. An item is
a single element of a collection, and must be a hashref.

=head1 SUPPORTED BACKENDS

=over

=item * L<Yancy::Backend::Pg> - Postgres backend

=item * L<Yancy::Backend::Mysql> - MySQL backend

=item * L<Yancy::Backend::Sqlite> - SQLite backend

=item * L<Yancy::Backend::Dbic> - L<DBIx::Class> backend

=back

=head1 METHODS

=head2 new

    my $url = 'test://custom_string';
    my $be = Yancy::Backend::Test->new( $url, $collections );

Create a new backend object. C<$url> is a string that begins with the
backend name followed by a colon. Everything else in the URL is for the
backend to use to describe how to connect to the underlying database and
any options for the backend object itself.

C<$collections> is a hash reference of collection configuration from the
Yancy configuration. Important configuration for the backend to support:

=over

=item x-id-field

The name of the ID field for the collection. Defaults to C<id>.

=back

The backend name will be run through C<ucfirst> before being looked up
in C<Yancy::Backend::>. For example, C<mysql://...> will use the
L<Yancy::Backend::Mysql> module.

=head2 list

    my $result = $be->list( $collection, $where, $opt );
    # { total => ..., rows => [ ... ] }

Fetch a list of items from a collection. C<$collection> is the
collection name. C<$where> is a L<SQL::Abstract where
structure|SQL::Abstract/WHERE CLAUSES>.

C<$opt> is a hash reference with the following keys:

=over

=item * limit - The number of rows to return

=item * offset - The number of rows to skip

=item * order_by - A L<SQL::Abstract order by clause|SQL::Abstract/ORDER BY CLAUSES>

=back

Returns a hashref with two keys:

=over

=item rows

An array reference of hash references of item data

=item total

The total count of rows that would be returned without C<limit> or
C<offset>.

=back

=head2 get

    my $item = $be->get( $collection, $id );

Get a single item. C<$collection> is the collection name. C<$id> is the
ID of the item to get. Returns a hashref of item data.

=head2 set

    $be->set( $collection, $id, $item );

Update an item. C<$collection> is the collection name. C<$id> is the
ID of the item to update. C<$item> is the item's data to set. There is
no return value.

=head2 create

    $item = $be->create( $collection, $item );

Create a new item. C<$collection> is the collection name.  C<$item> is
the item's data. Returns the item's data after being saved in the
database (so, including any defaults or autogenerated data).

=head2 delete

    $be->delete( $collection, $id );

Delete an item. C<$collection> is the collection name. C<$id> is the
ID of the item to delete.

=head2 read_schema

    my $schema = $be->read_schema;

Read the schema from the database tables. Returns an OpenAPI schema
ready to be merged into the user's configuration.

=head1 AUTHOR

Doug Bell <preaction@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Doug Bell.

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
