NAME
DBIO::PostgreSQL::Introspect - Introspect a PostgreSQL database via pg_catalog
VERSION
version 0.900000
DESCRIPTION
DBIO::PostgreSQL::Introspect reads the live state of a PostgreSQL database via pg_catalog and returns a unified model hashref. It is the source side of the test-deploy-and-compare strategy used by DBIO::PostgreSQL::Deploy.
my $intro = DBIO::PostgreSQL::Introspect->new(
dbh => $dbh,
schema_filter => [qw( public auth api )],
);
my $model = $intro->model;
# $model->{schemas}, $model->{tables}, $model->{columns}, ...The model is built lazily on first access and covers schemas, extensions, types (enums/composites/ranges), tables, columns, indexes, triggers, functions, RLS policies, and sequences. The same model shape is consumed by DBIO::PostgreSQL::Diff and by the test-deploy workflow in DBIO::PostgreSQL::Deploy. On top of it, this class implements the normalized generation contract from DBIO::Introspect::Base so it can act as a DBIO::Generate source.
ATTRIBUTES
schema_filter
Optional ArrayRef of PostgreSQL schema names to restrict introspection to. When undef, all non-system schemas are introspected.
METHODS
table_keys
Returns sorted ArrayRef of schema-qualified table keys (schema.name).
table_columns
my \@names = $intro->table_columns($key);Ordered list of column names for $key.
table_columns_info
my \%info = %{ $intro->table_columns_info($key) };Hashref of column metadata.
table_pk_info
my \@pk_cols = @{ $intro->table_pk_info($key) };Ordered list of primary key column names.
table_uniq_info
my \@constraints = @{ $intro->table_uniq_info($key) };List of [ $constraint_name, \@col_names ] pairs.
table_fk_info
my \@fks = @{ $intro->table_fk_info($key) };Each FK is a hashref.
table_is_view
Returns true if $key is a view.
view_definition
SQL text of the view definition, or undef.
table_comment
Comment string for the table, or undef.
column_comment
Comment string for a column, or undef.
result_class_extra_statements
my @stmts = $intro->result_class_extra_statements($key);Driver-specific PostgreSQL statements for the generated Result class. Emits pg_schema, pg_index, pg_trigger, pg_rls, pg_check_constraint.
NORMALIZED CONTRACT
These methods implement the generation contract defined in DBIO::Introspect::Base. They build on the native model.
identity_kind
my $kind = DBIO::PostgreSQL::Introspect->identity_kind($id);Maps the attidentity opcode from pg_catalog.pg_attribute to the SQL keyword that follows GENERATED in CREATE TABLE: 'a' becomes 'ALWAYS', 'd' becomes 'BY DEFAULT', anything else (including undef and '') returns undef. The same map is needed by every site that emits identity syntax (Diff::Column, Diff::Table, DDL).
qualified_key
my $key = DBIO::PostgreSQL::Introspect->qualified_key($schema, $name);
my $key = DBIO::PostgreSQL::Introspect->qualified_key($row);Builds the canonical "schema.name" key used to index introspected models. Accepts either two positional args ($schema, $name) or a single hashref that contains both schema_name and one of table_name, type_name, function_name, sequence_name, index_name, or policy_name. Centralising the construction here keeps every section key in lockstep — if the separator ever changes, only this helper moves.
system_schema_filter
my $sql = DBIO::PostgreSQL::Introspect->system_schema_filter($alias);Returns a two-line SQL fragment for the pg_catalog namespace filter that excludes the PostgreSQL reserved namespaces (pg_* and information_schema). The optional $alias is the alias used in the query for the pg_namespace row (defaults to n). Every introspect helper concatenates this fragment into its WHERE clause so the set of excluded namespaces is centralised.
SEE ALSO
DBIO::PostgreSQL::Deploy, DBIO::PostgreSQL::Diff.
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.