Preface
This article demonstrates the simplest cases regarding autoserialization and deserialization to the database of objects in PGObject. It also demonstrates a minimal subset of the problems that three valued logic introduces and the most general solutions to those problems. The next article in this series will address more specific solutions and more complex scenarios.
The Problems
Often times we want to have database fields automatically turned into object types which are useful to an application. The example here turns SQL numeric fields into Perl Math::Bigfloat objects. However the transformation isn't perfect and if not carefully done can be lossy. Most applications types don't support database nulls properly and therefore a NULL making a round trip may end up with an unexpected value if we aren't careful. Therefore we have to create our type in a way which can make round trips in a proper, lossless way.
NULLs introduce another subtle problem with such mappings, in that object methods are usually not prepared to handle them properly. One solution here is to try to follow the basic functional programming approach and copy on write. This prevents a lot of problems. Most Math::BigFloat operations do not mutate the objects so we are relatively safe there, but we still have to be careful.
The simplest way to address this is to build into one's approach a basic sensitivity into three value logic. However, this poses a number of problems, in that one can accidentally assign a value which can have other values which can impact things elsewhere.
A key principle on all our types is that they should handle a null round trip properly for the data type, i.e. a null from the db should be turned into a null on database insert. We generally allow programmers to check the types for nulls, but don't explicitly handle them with three value logic in the application (that's the programmer's job).
The Example Module and Repository
This article follows the code of PGObject::Type::BigFloat.. The code is licensed under the two-clause BSD license as is the rest of the PGObject framework. You can read the code to see the boilerplate. I won't be including it in here. I will though note that this extends the Math::BigFloat library which provides arbitrary precision arithmetic for PostgreSQL and is a good match for LedgerSMB's numeric types.
NULL handling
To solve the problem of null inputs we extend the hashref slightly with a key _pgobject_undef and allow this to be set or checked by applications with a function "is_undef." This is fairly trivial:
sub is_undef {
my ($self, $set) = @_;
$self->{_pgobject_undef} = $set if defined $set;
return $self->{_pgobject_undef};
}
How PGObject Serializes
When a stored procedure is called, the mapper class calls PGObject::call_procedure with an enumerated set of arguments. A query is generated to call the procedure, and each argument is checked for a "to_db" method. That method, if it exists, is called and the output used instead of the argument provided. This allows an object to specify how it is serialized.
The to_db method may return either a literal value or a hashref with two keys, type and value. If the latter, the value is used as the value literal and the type is the cast type (i.e. it generates ?::type for the placeholder and binds the value to it). This hash approach is automatically used when bytea arguments are found.
The code used by PGObject::Type::BigFloat is simple:
sub to_db {
my $self = shift @_;
return undef if $self->is_undef;
return $self->bstr;
}
Any type of course can specify a to_db method for serialization purposes.
How and When PGObject Deserializes
Unlike serialization, deserialization from the database can't happen automatically without the developer specifying which database types correspond to which application classes, because multiple types could serialize into the same application classes. We might even want different portions of an application (for example in a database migration tool) to handle these differently.
For this reason, PGObject has what is called a "type registry" which specifies which types are deserialized and as what. The type registry is optionally segmented into several "registries" but most uses will in fact simply use the default registry and assume the whole application wants to use the same mappings. If a registry is not specified the default subregistry is used and that is consistent throughout the framework.
Registering a type is fairly straight forward but mostly amounts to boilerplate code in both the type handler and using scripts. For this type handler:
sub register{
my $self = shift @_;
croak "Can't pass reference to register \n".
"Hint: use the class instead of the object" if ref $self;
my %args = @_;
my $registry = $args{registry};
$registry ||= 'default';
my $types = $args{types};
$types = ['float4', 'float8', 'numeric'] unless defined $types and @$types;
for my $type (@$types){
my $ret =
PGObject->register_type(registry => $registry, pg_type => $type,
perl_class => $self);
return $ret unless $ret;
}
return 1;
}
Then we can just call this in another script as:
PGObject::Type::BigFloat->register;
Or we can specify a subset of types or different types, or the like.
The deserialization logic is handled by a method called 'from_db' which takes in the database literal and returns the blessed object. In this case:
sub from_db {
my ($self, $value) = @_;
my $obj = "$self"->new($value);
$obj->is_undef(1) if ! defined $value;
return $obj;
}
Use Cases
This module is used as the database interface for numeric types in the LedgerSMB 1.5 codebase. We subclass this module and add support for localized input and output (with different decimal and thousands separators). This gives us a data type which can present itself to the user as one format and to the database as another. The module could be further subclassed to make nulls contageous (which in this module they are not) and the like.
Caveats
PGObject::Type::BigFloat does not currently handle making the null handling contageous and this module as such probably never will, as this is part of our philosophy of handing control to the programmer. Those who do want contageous nulls can override additional methods from Math::BigFloat to provide such in subclasses.
A single null can go from the db into the application and return to the db and be serialized as a null, but a running total of nulls will be saved in the db as a 0. To this point, that behavior is probably correct. More specific handling of nulls in the application, however, is passed to the developer which can check the is_undef method.
Next In Series: Advanced Serialization and Deserialization: Dates, Times, and JSON
