NAME
DBIO::PostgreSQL::PostGIS::Storage - Storage class with PostGIS spatial extensions
VERSION
version 0.900007
DESCRIPTION
A storage layer that adds PostGIS-aware helper methods (extension ensure/probe, version) to a PostgreSQL storage. It is not a storage subclass: it is a plain method package composed over the resolved driver storage at connection time (see DBIO::Storage::Composed). DBIO::PostgreSQL::PostGIS registers it via "register_storage_layer" in DBIO::Schema, so on $schema->connect the live storage isa both this layer and DBIO::PostgreSQL::Storage, and its methods below are callable on that composed storage.
Layer rules
Per the storage-layer composition model (DBIO core, storage-layer composition): this package does not use base a driver storage, defines no constructor, and calls only the documented public storage surface (dbh_do, throw_exception, schema, connection_schema) -- which resolves through the composed MRO to the driver base at runtime. New methods here (ensure_postgis, postgis_version, _ensure_postgis_extension) do not shadow any base method. The layer does not define dbio_deploy_class: that hook has one owner, the driver storage (ADR 0066, section 4). The model rules of PostGIS are in DBIO::PostgreSQL::PostGIS::Extension; the driver registers this layer for a declared postgis (storage_layer of that class).
No async layer
PostGIS ships no ::Async sibling: its storage surface (extension ensure, version) is synchronous, and the spatial codecs / ResultSet helpers are not storage-async-level. The layer states this through "async_layer_class", which returns undef for every async mode -- the declared sync-only opt-out of the core async-mirror resolver (ADR 0032 addendum 2026-09-25). Core therefore neither probes nor loads a ::Async sibling for it, so under any async connection mode ({ async => ... }) the composed async backend carries no PostGIS async layer, and CRUD on geometry columns flows through the transport unchanged. If async deploy or codec hooks are ever needed, that is a separate ticket.
METHODS
ensure_postgis
$storage->ensure_postgis;
Makes sure the postgis extension is installed in the connected database: CREATE EXTENSION IF NOT EXISTS postgis WITH SCHEMA .... Idempotent.
The statement always names the schema. It is the one the schema class declares for the extension,
__PACKAGE__->pg_extensions(postgis => { schema => 'gis' });
("pg_extension_schemas" in DBIO::PostgreSQL); when it declares none, the schema the control file of the server fixes for postgis (asked with "control_schemas_sql" in DBIO::PostgreSQL::DDL, only then); and public when that fixes none -- for a schema class without the DBIO::PostgreSQL component and a storage without a schema class as well. Where the extension goes therefore does not depend on the search_path of the session.
An extension belongs to the database, not to the namespace of one connection. A connection opened with the connect key schema ("ONE SCHEMA CLASS IN SEVERAL NAMESPACES" in DBIO::PostgreSQL) has its namespace first in the search_path, and postgis cannot be moved to another schema once it is installed. So when the schema chosen for the extension is the namespace of the connection -- declared so, or public on a connection that works in public -- this method throws a DBIO::Exception and sends no statement; declare another schema for the extension.
The schema itself is not created here: one the database does not have is the server's error. An extension that is installed already stays in the schema it is in.
postgis_version
my $v = $storage->postgis_version;
Returns the PostGIS extension version string from PostGIS_Full_Version(), or undef if the extension is not installed.
_ensure_postgis_extension
$storage->_ensure_postgis_extension;
Cheap fail-fast check that the postgis extension is installed on the connected database. Throws a DBIO::Exception with a message naming the missing extension and the database when the extension is not present. A no-op when the extension is installed.
Intended to be wrapped around first-use storage operations by callers that require PostGIS (deploy, schema load, geometry inflation). The core driver does not call this automatically so that storage construction against a non-PostGIS database remains possible for introspection and other PostGIS-agnostic tasks.
async_layer_class
my $async_layer = DBIO::PostgreSQL::PostGIS::Storage->async_layer_class($mode); # undef
Answers the core async-mirror resolver: returns undef for every async mode, declaring this layer deliberately sync-only (see "No async layer"). Defining the method is the statement; core skips the layer without probing a ::Async sibling, instead of relying on the transitional silent skip for layers that say nothing.
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.