/ 
Yancy-1.071
River stage one • 3 direct dependents • 3 total dependents
/ Yancy::Backend

NAME

Yancy::Backend - Handles talking to the database.

VERSION

version 1.071

SYNOPSIS

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

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

$item = $be->get( $schema, $id );
$be->set( $schema, $id, $item );
$be->delete( $schema, $id );
$id = $be->create( $schema, $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 schemas, which are made up of items. A schema is a set of items, like a database table. An item is a single element of a schema, 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

Other backends are available on CPAN.

METHODS

new

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

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.

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.

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

x-id-field

The name of the ID field or fields for the schema. Defaults to id. It does not need to be the primary key: This can be any unique identifier. To define a composite key, provide an array of strings.

properties

Each schema is, at the very top, an array of hashrefs (a series of rows of column/value pairs). So, each schema should have a properties key to declare what properties are available on the items in this schema.

This is a hash reference with the keys as the field names and the values as hash references of configuration for the field. Some important configuration for fields are:

type

The type of the field. Can be an array reference of multiple types (this is JSON Schema, not OpenAPI Schema).

See "Types" in Yancy::Help::Config for more information on supported types.

Other field configuration can be supported by the backend's read_schema method, but are not relevant for the standard API: Yancy backends do not perform data validation. Yancy relies on the Controller and the underlying database to do that.

list

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

Fetch a list of items from a schema. $schema is the schema name.

$where is a SQL::Abstract where structure.

# Search for all Dougs
$be->list( 'people', { name => { -like => 'Doug%' } } );
# Find adults
$be->list( 'people', { age => { '>=' => 18 } } );
# Find men we can contact
$be->list( 'people', { gender => 'male', contact => 1 } );

Additionally, Yancy backends support the following additional keys in the where structure:

-has (EXPERIMENTAL)

The -has operator searches inside a data structure (an array or a hash). This operator examines the type of the field being searched to perform the appropriate query.

# Create a new page with an array of tags and a hash of author
# information
$be->create( pages => {
    title => 'Release v1.481',
    tags => [ 'release', 'minor' ],
    author => {
        name => 'Doug Bell',
        email => 'doug@example.com',
    },
} );

# All pages that have the tag "release"
$be->list( pages => { tags => { -has => 'release' } } );

# All pages that have both the tags "release" and "major"
$be->list( pages => { tags => { -has => [ 'release', 'major' ] } } );

# All pages that have the author's name starting with Doug
$be->list( pages => { author => { -has => { name => { -like => 'Doug%' } } } } );

This is not yet supported by all backends, and may never be supported by some. Postgres has array columns and JSON fields. MySQL has JSON fields. The "match" in Yancy::Util function matches against Perl data structures. All of these should support -has and -not_has before it can be considered not experimental.

$opt is a hash reference with the following keys:

# Get the second page of 20 people
$be->list( 'people', {}, { limit => 20, offset => 20 } );
# Get the list of people sorted by age, oldest first
$be->list( 'people', {}, { order_by => { -desc => 'age' } } );
# Get the list of people sorted by age first, then name (ascending)
$be->list( 'people', {}, { order_by => [ 'age', 'name' ] } );

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( $schema, $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( $schema, $id );

Get a single item. $schema is the schema name. $id is the ID of the item to get: Either a string for a single key field, or a hash reference for a composite key. Returns a hashref of item data.

get_p

my $promise = $be->get_p( $schema, $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( $schema, $id, $item );

Update an item. $schema is the schema name. $id is the ID of the item to update: Either a string for a single key field, or a hash reference for a composite key. $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.

Currently the values of the data cannot be references, only simple scalars or JSON booleans.

set_p

my $promise = $be->set_p( $schema, $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( $schema, $item );

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

Currently the values of the data cannot be references, only simple scalars or JSON booleans.

create_p

my $promise = $be->create_p( $schema, $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( $schema, $id );

Delete an item. $schema is the schema name. $id is the ID of the item to delete: Either a string for a single key field, or a hash reference for a composite key. 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( $schema, $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) 2020 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.