NAME
DBIO::PostgreSQL::PostGIS - PostGIS spatial extension support for DBIO::PostgreSQL
VERSION
version 0.900007
SYNOPSIS
package MyApp::DB;
use DBIO Schema => -pg;
__PACKAGE__->pg_extensions('postgis');
package MyApp::Schema::Result::Place;
use base 'DBIO::Core';
__PACKAGE__->load_components('PostgreSQL::PostGIS');
__PACKAGE__->table('place');
__PACKAGE__->add_columns(
id => { data_type => 'integer', is_auto_increment => 1 },
name => { data_type => 'text' },
geom => {
data_type => 'geometry',
geometry_type => 'POINT',
srid => 4326,
},
);
# Inflated reads
my $place = $schema->resultset('Place')->find(1);
$place->geom->isa('DBIO::PostgreSQL::PostGIS::Geometry');
$place->geom->x; # longitude
$place->geom->y; # latitude
# Deflated writes — pass a Geometry object, the helper builds EWKT
$place->geom(
DBIO::PostgreSQL::PostGIS::Geometry->point(13.4, 52.5, srid => 4326),
);
$place->update;
# Spatial query — raw SQL via -bool literal
my $rs = $schema->resultset('Place')->search({
-bool => \['ST_DWithin(geom, ST_MakePoint(?, ?)::geography, ?)',
$lon, $lat, $meters],
});
DESCRIPTION
DBIO::PostgreSQL::PostGIS is a result-class component that adds PostGIS spatial type handling to DBIO result classes:
Columns with
data_type => 'geometry'or'geography'are automatically inflated to DBIO::PostgreSQL::PostGIS::Geometry objects on read and deflated on write: to the EWKB hex the object carries if it was read from the database, to EWKT if it was built in Perl (see "register_column").Spatial-query helpers are mixed into the resultset class via DBIO::PostgreSQL::PostGIS::ResultSet.
Activating PostGIS
PostGIS is a database extension, and a schema states that its database has it in its list of extensions (ADR 0066), not by loading this component:
package MyApp::DB;
use DBIO Schema => -pg;
__PACKAGE__->pg_extensions('postgis'); # or
__PACKAGE__->pg_extensions(postgis => { schema => 'gis' });
The driver resolves the name to DBIO::PostgreSQL::PostGIS::Extension. That class carries the model rules (the geometry type and SRID of a column; the verdict on a change of them: another SRID is converted with ST_Transform, another type is refused), names the storage layer (DBIO::PostgreSQL::PostGIS::Storage: ensure_postgis, postgis_version) and names this component as the inflation. postgis_topology is its own extension with its own class, DBIO::PostgreSQL::PostGIS::Topology::Extension. The ::Deploy and ::Introspect classes of this distribution are stubs.
This component is the result side. Loading it in a result class gives the inflation and the resultset helpers above. Loading it on a schema registers the storage layer too, which the driver does for a declared postgis anyway (registering twice is a no-op); the layer is composed over the resolved driver storage (see DBIO::Storage::Composed).
METHODS
register_column
Hooks into the column registration chain. When a column declares data_type => 'geometry' or 'geography', registers inflate/deflate handlers for DBIO::PostgreSQL::PostGIS::Geometry objects.
Inflate takes whichever text form the database returned: EWKB hex (what PostGIS sends for a plain SELECT geom), EWKT (SRID=N;..., as from ST_AsEWKT), or plain WKT, which gets the column's srid.
Only NULL inflates to undef. Every other value inflates to a Geometry object, and that includes the geometry types this distribution names and does not decode: CIRCULARSTRING, COMPOUNDCURVE, CURVEPOLYGON, MULTICURVE, MULTISURFACE, POLYHEDRALSURFACE, TIN, TRIANGLE, and a GEOMETRYCOLLECTION holding one of them. Such an object has its ewkb_hex, the srid and the geometry_type of the value (circularstring, ...) and no coordinates -- coordinates, wkt, bbox and the like return undef, see "from_ewkb_hex" in DBIO::PostgreSQL::PostGIS::Geometry. It is written back as its hex like any other read value, so the row stays readable, and its geometry can be copied to another row, without Perl knowing its coordinates. The alternative, an inflater that throws on such a value, would make every row holding one unreadable.
Deflate writes a Geometry object in the most faithful form it has:
An object that carries EWKB hex -- every value inflated from a plain
SELECTdoes -- is written as that hex, unchanged. Reading a geometry and writing it to another row ($b->geom($a->geom); $b->update, or acreatewith it) therefore stores the same geometry: same type, same Z/M dimension, the same doubles bit for bit. PostGIS takes the hex forgeometryandgeographycolumns alike.An object without hex (an empty
ewkb_hexis no hex; built withpoint,linestring,polygon,from_wkt,from_ewkt,from_geojson, ...) is written as EWKT,SRID=N;WKT, or as bare WKT when it has no SRID.An object with none of these -- no hex, no WKT and no coordinates, or coordinates without a
geometry_typeto build a WKT under -- throws a DBIO::Exception that says what is missing. It is not written asNULL:NULLis whatundefstands for, and an object is notundef. (It was written asNULL, or, for coordinates without a type, as(), which the server refuses.)
A plain string is passed through as it is, whichever of the three forms it holds.
Override the auto-detection by setting inflate_geometry => 0 explicitly on the column.
Also promotes the result source's resultset_class to DBIO::PostgreSQL::PostGIS::ResultSet the first time a spatial column is registered, giving the resultset spatial-query helpers (within_distance, nearest_to, etc.). If you need custom resultset methods alongside the PostGIS helpers, subclass DBIO::PostgreSQL::PostGIS::ResultSet and set resultset_class to your subclass — the promotion guard skips any class that already inherits from DBIO::PostgreSQL::PostGIS::ResultSet.
SEE ALSO
DBIO::PostgreSQL - Base PostgreSQL driver component
DBIO::PostgreSQL::PostGIS::Geometry - Lightweight geometry value object
DBIO::PostgreSQL::PostGIS::Extension - The extension class: model rules for deploy, introspection and diff
DBIO::PostgreSQL::PostGIS::Topology::Extension - The postgis_topology extension
DBIO::PostgreSQL::PostGIS::Storage - Storage layer with spatial methods
DBIO::PostgreSQL::PostGIS::ResultSet - Spatial query helpers
AUTHOR
DBIO Authors
COPYRIGHT AND LICENSE
Copyright (C) 2026 DBIO Authors
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.