view release on metacpan or  search on metacpan

lib/DBIx/QuickORM/Manual/Types.pm  view on Meta::CPAN

package DBIx::QuickORM::Manual::Types;
use strict;
use warnings;

our $VERSION = '0.000028';

1;

__END__

=pod

=encoding UTF-8

=head1 NAME

DBIx::QuickORM::Manual::Types - Inflating and deflating column values.

=head1 DESCRIPTION

A B<type> in L<DBIx::QuickORM> is a class that knows how to convert a column
value between the form stored in the database and a richer Perl form. Going
from the database to Perl is I<inflation>; going from Perl back to the database
is I<deflation>.

The database stores a JSON document as a string; you usually want a Perl hash
or array. A UUID is bytes or text in a column; you usually want the canonical
hyphenated string. A type bridges that gap so your row accessors hand back the
inflated value and your writes are deflated transparently.

This document covers the built-in JSON and UUID types, how to apply a type to a
column, how C<autotype> applies types automatically, and how to write your own
type class.

This is part of the L<DBIx::QuickORM::Manual>.

=head1 HOW A TYPE MAPS DATABASE VALUE TO PERL VALUE

A type class consumes L<DBIx::QuickORM::Role::Type> and implements a small set
of methods. The two you care about most are:

=over 4

=item $perl = $type->qorm_inflate(...)

Convert a raw value just read from the database into its inflated Perl form.

=item $raw = $type->qorm_deflate(...)

Convert an inflated Perl value back into the form to store in the database.

=back

The remaining contract methods (C<qorm_compare>, C<qorm_affinity>, and
C<qorm_sql_type>) let the type compare two values for equality, declare its
storage affinity, and pick a SQL column type. See
L<DBIx::QuickORM::Role::Type> for the full contract.

=head1 AFFINITY IN BRIEF

Every column has an I<affinity> - one of C<string>, C<numeric>, C<binary>, or
C<boolean> - that describes how its value is treated when written to or read
from the database. A type usually declares an affinity (via
C<qorm_affinity>), and deflation can vary by affinity: the UUID type, for
example, deflates to a hyphenated string for C<string> columns and to packed
16-byte data for C<binary> columns.

This is only a summary. For the full explanation of affinities and where they
come from, see the L<AFFINITY|DBIx::QuickORM::Manual::Concepts/AFFINITY>
section of L<DBIx::QuickORM::Manual::Concepts> and the helper functions in
L<DBIx::QuickORM::Affinity>.

=head1 BUILT-IN TYPES

DBIx::QuickORM ships three type classes.

=head2 JSON

L<DBIx::QuickORM::Type::JSON> stores Perl data structures as JSON. Inflation
decodes the stored JSON into a Perl reference; deflation encodes a reference
back to JSON. Comparison uses a canonical encoding so structurally identical
values compare equal. Its affinity is C<string>, and its SQL type prefers a
native C<jsonb>/C<json> column, falling back to C<longtext>/C<text>.

=head2 UUID

L<DBIx::QuickORM::Type::UUID> handles UUID columns. Values inflate to the
canonical hyphenated string. Deflation honors the affinity: C<string> produces
the hyphenated form, C<binary> produces the packed 16-byte form. Its SQL type