NAME

DBIO::PostgreSQL::PgSchema - Base class for PostgreSQL schema namespaces

VERSION

version 0.900007

DESCRIPTION

DBIO::PostgreSQL::PgSchema is the base class for the intermediate PostgreSQL schema (namespace) layer in DBIO. Subclass it to declare the enums, composite types, and functions that belong to a specific PostgreSQL namespace.

package MyApp::DB::PgSchema::Auth;
use base 'DBIO::PostgreSQL::PgSchema';

__PACKAGE__->pg_enum('role_type' => [qw( admin moderator user guest )]);

__PACKAGE__->pg_type('address_type' => {
    street => 'text',
    city   => 'text',
    zip    => 'varchar(10)',
});

__PACKAGE__->pg_function('update_modified_at' => q{
    CREATE OR REPLACE FUNCTION auth.update_modified_at()
    RETURNS TRIGGER AS $$ BEGIN NEW.modified_at = NOW(); RETURN NEW; END;
    $$ LANGUAGE plpgsql
});

The schema class attaches a PgSchema class to its namespace with "pg_schema_class" in DBIO::PostgreSQL:

package MyApp::DB;
use base 'DBIO::Schema';
__PACKAGE__->load_components('PostgreSQL');

__PACKAGE__->pg_schema_class('auth' => 'MyApp::DB::PgSchema::Auth');

DBIO::PostgreSQL::DDL then emits the class's definitions for the auth namespace. It calls the class by name, so the class must be loaded by then.

The class-method forms of pg_enum, pg_type, and pg_function record definitions that DBIO::PostgreSQL::DDL reads when generating install DDL. The instance-method forms are used at runtime when a PgSchema object is instantiated.

ATTRIBUTES

pg_schema_name

my $obj = MyApp::DB::PgSchema::Auth->new(pg_schema_name => 'auth');
my $name = $obj->pg_schema_name;

The PostgreSQL schema name (e.g. auth, public, api) an instance was constructed with. Optional, and a reader on instances only: it takes no value and cannot be called on the class. The namespace a class's definitions are installed into comes from one source, the binding the schema class makes with "pg_schema_class" in DBIO::PostgreSQL.

METHODS

new

my $obj = MyApp::DB::PgSchema::Auth->new(pg_schema_name => 'auth');

Returns an instance with no enum, type or function definition of its own: what the class declared with the class-method forms is not copied into it. The instance forms of "pg_enum", "pg_type" and "pg_function" fill and read it; "pg_schema_name" is the one named argument it has a reader for.

_pg_enum_defs

my $defs = $class->_pg_enum_defs;

Returns the arrayref of [$name, $values] pairs declared on this specific class via "pg_enum". Does not inherit from parent classes.

_pg_type_defs

my $defs = $class->_pg_type_defs;

Returns the arrayref of [$name, $fields] pairs declared on this class via "pg_type".

_pg_function_defs

my $defs = $class->_pg_function_defs;

Returns the arrayref of [$name, $sql] pairs declared on this class via "pg_function".

pg_enum

# Class method (declarative — records for DDL generation):
__PACKAGE__->pg_enum('role_type' => [qw( admin moderator user guest )]);

# Instance method (runtime access):
my $values = $obj->pg_enum('role_type');

Declare or retrieve an enum type definition. The values arrayref preserves declaration order, which PostgreSQL requires. Class-method calls accumulate definitions consumed by DBIO::PostgreSQL::DDL.

pg_type

# Class method:
__PACKAGE__->pg_type('address_type' => {
    street  => 'text',
    city    => 'text',
    zip     => 'varchar(10)',
    country => 'varchar(2)',
});

# Instance method:
my $fields = $obj->pg_type('address_type');

Declare or retrieve a composite type definition. The fields hashref maps attribute names to PostgreSQL type strings.

pg_function

# Class method:
__PACKAGE__->pg_function('update_modified_at' => q{
    CREATE OR REPLACE FUNCTION auth.update_modified_at()
    RETURNS TRIGGER AS $$ ... $$ LANGUAGE plpgsql
});

# Instance method:
my $sql = $obj->pg_function('update_modified_at');

Declare or retrieve a function definition. The SQL string is emitted verbatim by DBIO::PostgreSQL::DDL during install_ddl.

pg_enums

my $all = $obj->pg_enums;  # hashref of name => values

Returns a copy of all enum definitions held by this instance.

pg_types

my $all = $obj->pg_types;  # hashref of name => fields

Returns a copy of all composite type definitions held by this instance.

pg_functions

my $all = $obj->pg_functions;  # hashref of name => sql

Returns a copy of all function definitions held by this instance.

SEE ALSO

AUTHOR

DBIO & DBIx::Class Authors

COPYRIGHT AND LICENSE

Copyright (C) 2026 DBIO Authors Portions Copyright (C) 2005-2025 DBIx::Class Authors Based on DBIx::Class, heavily modified.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.