Yancy::Backend - Handles talking to the database.
version 1.035
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 );
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.
Yancy::Backend
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 implement both a synchronous and an asynchronous API (using promises).
Synchronous-only backends also implement a promises API for compatibility, but will not perform requests concurrently.
Yancy::Backend::Pg - Postgres backend
Yancy::Backend::Mysql - MySQL backend
Yancy::Backend::Sqlite - SQLite backend
Yancy::Backend::Dbic - DBIx::Class backend
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.
$url
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.
ucfirst
Yancy::Backend::
mysql://...
$schema is a hash reference of schema configuration from the Yancy configuration. Important configuration for the backend to support:
$schema
The name of the ID field for the schema. Defaults to id. It does not need to be the primary key: This can be any unique identifier.
id
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.
properties
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:
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.
read_schema
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.
$where
# 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 } );
$opt is a hash reference with the following keys:
$opt
limit - The number of items to return
offset - The number of items to skip
order_by - A SQL::Abstract order by clause
# 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:
An array reference of hash references of item data
The total count of items that would be returned without limit or offset.
limit
offset
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.
items
total
my $item = $be->get( $schema, $id );
Get a single item. $schema is the schema name. $id is the ID of the item to get. Returns a hashref of item data.
$id
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.
my $success = $be->set( $schema, $id, $item );
Update an item. $schema is the schema 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.
$item
Currently the values of the data cannot be references, only simple scalars or JSON booleans.
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.
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.
the get() method|/get
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.
$be->delete( $schema, $id );
Delete an item. $schema is the schema 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.
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.
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.
Doug Bell <preaction@cpan.org>
This software is copyright (c) 2019 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.
To install Yancy, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Yancy
CPAN shell
perl -MCPAN -e shell install Yancy
For more information on module installation, please visit the detailed CPAN module installation guide.