The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Yancy::Backend - Handles talking to the database.

VERSION

version 1.021

SYNOPSIS

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

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

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

DESCRIPTION

A Yancy::Backend handles talking to the database. Different Yancy backends will support different databases. To use a backend, see "SUPPORTED BACKENDS". To make your own backend, see "METHODS" for the list of methods each backend supports, their arguments, and their return values.

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.

Asynchronous Backends

Asynchronous backends implement both a synchronous and an asynchronous API (using promises).

Synchronous-only Backends

Synchronous-only backends also implement a promises API for compatibility, but will not perform requests concurrently.

SUPPORTED BACKENDS

METHODS

new

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

Create a new backend object. $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.

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

x-id-field

The name of the ID field for the collection. Defaults to id. It does not need to be the primary key: This can be any unique identifier.

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

list

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

Fetch a list of items from a collection. $collection is the collection name. $where is a SQL::Abstract where structure.

$opt is a hash reference with the following keys:

Returns a hashref with two keys:

items

An array reference of hash references of item data

total

The total count of items that would be returned without limit or offset.

list_p

    my $promise = $be->list_p( $collection, $where, $opt );
    $promise->then( sub {
        my ( $result ) = @_;
        # { total => ..., items => [ ... ] }
    } );

Fetch a list of items asynchronously using promises. Returns a promise that resolves to a hashref with items and total keys. See "list" for arguments and return values.

get

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

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

get_p

    my $promise = $be->get_p( $collection, $id );
    $promise->then( sub {
        my ( $item ) = @_;
        # ...
    } );

Get a single item asynchronously using promises. Returns a promise that resolves to the item. See "get" for arguments and return values.

set

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

Update an item. $collection is the collection name. $id is the ID of the item to update. $item is the item's data to set. Returns a boolean that is true if a row with the given ID was found and updated, false otherwise.

set_p

    my $promise = $be->set_p( $collection, $id );
    $promise->then( sub {
        my ( $success ) = @_;
        # ...
    } );

Update a single item asynchronously using promises. Returns a promise that resolves to a boolean indicating if the row was updated. See "set" for arguments and return values.

create

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

Create a new item. $collection is the collection name. $item is the item's data. Returns the ID of the row created suitable to be passed in to the get() method|/get.

create_p

    my $promise = $be->create_p( $collection, $item );
    $promise->then( sub {
        my ( $id ) = @_;
        # ...
    } );

Create a new item asynchronously using promises. Returns a promise that resolves to the ID of the newly-created item. See "create" for arguments and return values.

delete

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

Delete an item. $collection is the collection name. $id is the ID of the item to delete. Returns a boolean that is true if a row with the given ID was found and deleted. False otherwise.

delete_p

    my $promise = $be->delete_p( $collection, $id );
    $promise->then( sub {
        my ( $success ) = @_;
        # ...
    } );

Delete an item asynchronously using promises. Returns a promise that resolves to a boolean indicating if the row was deleted. See "delete" for arguments and return values.

read_schema

    my $schema = $be->read_schema;
    my $table = $be->read_schema( $table_name );

Read the schema from the database tables. Returns an OpenAPI schema ready to be merged into the user's configuration. Can be restricted to only a single table.

AUTHOR

Doug Bell <preaction@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 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.