/ 
DBIO-0.900004
/ DBIO::Extension::List

NAME

DBIO::Extension::List - The declared list of database extensions of a schema, resolved to classes

VERSION

version 0.900004

SYNOPSIS

my $list = DBIO::Extension::List->new(
  declaration => [ 'age', postgis => { schema => 'gis' }, 'citext' ],
  class_table => sub {
    my ($name) = @_;
    return ('DBIO::PostgreSQL::Age::Extension',     'DBIO-PostgreSQL-Age')     if $name eq 'age';
    return ('DBIO::PostgreSQL::PostGIS::Extension', 'DBIO-PostgreSQL-PostGIS') if $name eq 'postgis';
    return;
  },
  plain_class => 'DBIO::PostgreSQL::Extension',
);

my @entries = $list->entries;     # sorted by name
$list->check_driver('DBIO::PostgreSQL');   # later, once the driver is resolved

DESCRIPTION

The list of ADR 0066 section 1: one entry per database extension the schema declares, keyed by the engine's own name. The driver builds it from the declaration it spells (PostgreSQL: pg_extensions) and hands core its table of the family's extension classes; core knows no driver class.

The list is declared state. It never determines the driver (ADR 0032 section 7), changes no @ISA and registers nothing: it is data plus the checks of ADR 0066 section 5.3. An entry is a hash reference

{ name => 'postgis', class => 'DBIO::PostgreSQL::PostGIS::Extension',
  options => { schema => 'gis' },
  # attached later, by set_installed:
  installed => 1, version => '3.4.2', schema => 'gis' }

METHODS

new

my $list = DBIO::Extension::List->new(
  declaration => \@declaration,
  class_table => \&lookup,
  plain_class => $class,
);
declaration

An array reference in the spelling of pg_extensions: a name, optionally followed by a hash reference of options. class => $class among the options names the extension class and wins over the table; it is not kept in options. A name declared twice merges its options; an option with two different values, or two different classes, refuse.

class_table

A code reference, called with the name. It returns the extension class of a name the driver knows, optionally followed by the name of the distribution that ships it (($class, $distribution)), or the empty list for a name it does not know.

plain_class

The driver's extension class without rules, used for a name neither the declaration (class) nor the table knows. Without it such a name refuses.

Every class is loaded and its interface version checked ("check_interface" in DBIO::Extension) here, when the list is resolved. A class that is not installed throws a DBIO::Exception naming the distribution (when the table gave one) or the class. A class whose name differs from its entry's name throws too.

entries

my @entries = $list->entries;

The entries, sorted by name, as copies. This is the order the rules of every phase run in and the activation is composed in.

names

The names of the entries, sorted.

set_installed

$list->set_installed({
  postgis => { installed => 1, version => '3.4.2', schema => 'gis' },
  age     => { installed => 0 },
});

Attaches the installed state the driver read to the entries of the declared names. The keys installed, version and schema are kept. A name that is not in the list throws: an extension that is installed but not declared is not part of the list (ADR 0066 section 1.3). Returns the list.

check_driver

$list->check_driver($resolved_driver);

The driver assertion of ADR 0066 section 1.3, called by the driver once the DSN has decided the driver -- at the first use after driver resolution, never at connect. For every entry whose class states a driver that is neither $resolved_driver nor a base class of it, throws a DBIO::Exception naming the extension, the asserted driver and the resolved one. A class that states no driver asserts nothing. Returns true.

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.