CONTENTS
- NAME
- VERSION
- SYNOPSIS
- DESCRIPTION
- SUPPORTED BACKENDS
- EXTENDING
- METHODS
- INTERNAL METHODS
- AUTHOR
- COPYRIGHT AND LICENSE
- POD ERRORS
#NAME
Yancy::Backend - Interface to a database
#VERSION
version 1.081
#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
Yancy::Backend::Pg - Postgres backend
Yancy::Backend::Mysql - MySQL backend
Yancy::Backend::Sqlite - SQLite backend
Yancy::Backend::Dbic - DBIx::Class backend
Other backends are available on CPAN.
Yancy::Backend::Static - Backend for a static site generator with Markdown.
#EXTENDING
To create your own Yancy::Backend for a new database system, inherit from this class and provide the standard six interface methods: "get", "create", "set", "list", "delete", and "read_schema".
There are roles to aid backend development:
Yancy::Backend::Role::DBI provides some methods based on DBI
Yancy::Backend::Role::Sync provides promise-based API methods for databases which are synchronous-only.
Backends do not have to talk to databases. For an example, see Yancy::Backend::Static for a backend that uses plain files like a static site generator.
#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. See Yancy::Guides::Schema for more information.
#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 list of name/value pairs with the following keys:
limit - The number of items to return
offset - The number of items to skip
order_by - A SQL::Abstract order by clause
join - Join one or more tables using a
x-foreign-key
field. This can be the name of a foreign key field on this schema, or the name of a table with a foreign key field that refers to this schema. Join multiple tables at the same time by passing an arrayref of joins. Fields in joined tables can be queried by prefixing the join name to the field, separated by a dot.
# 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
oroffset
.
#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, %opts );
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.
%opts
is a list of name/value pairs of options with the following names:
- join
-
Join one or more tables using a
x-foreign-key
field. This can be the name of a foreign key field on this schema, or the name of a table with a foreign key field that refers to this schema. Join multiple tables at the same time by passing an arrayref of joins.
#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.
#INTERNAL METHODS
These methods are documented for use in subclasses and should not need to be called externally.
#supports
Returns true if the backend supports a given feature. Returns false for now. In the future, features like 'json' will be detectable.
#ignore_table
Returns true if the given table should be ignored when doing "read_schema". By default, backends will ignore tables used by:
Minion backends (Minion::Backend::mysql, Minion::Backend::Pg, Minion::Backend::SQLite) =item * DBIx::Class::Schema::Versioned =item * Mojo DB migrations (Mojo::mysql::Migrations, Mojo::Pg::Migrations, Mojo::SQLite::Migrations) =item * Mojo::mysql::PubSub
#normalize
This method normalizes data to and from the database.
#id_field
Get the ID field for the given schema. Defaults to id
.
#id_where
Get the query structure for the ID field of the given schema with the given ID value.
#AUTHOR
Doug Bell <preaction@cpan.org>
#COPYRIGHT AND LICENSE
This software is copyright (c) 2021 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.
#POD ERRORS
Hey! The above document had some coding errors, which are explained below:
- Around line 760:
-
You forgot a '=back' before '=head2'