NAME
DBIO::DuckDB::Introspect - Introspect a DuckDB database via information_schema + duckdb_* views
VERSION
version 0.900007
DESCRIPTION
DBIO::DuckDB::Introspect reads the live state of a DuckDB database via the standard SQL information_schema views (tables, columns, constraints, views) plus DuckDB's duckdb_indexes() system function. It is the source side of the test-deploy-and-compare strategy used by DBIO::DuckDB::Deploy.
my $intro = DBIO::DuckDB::Introspect->new(dbh => $dbh);
my $model = $intro->model;
With a locally-attached file or DuckLake catalog pass catalog:
my $intro = DBIO::DuckDB::Introspect->new(dbh => $dbh, catalog => 'mycat');
my $model = $intro->model;
Model shape mirrors DBIO::SQLite::Introspect:
{
tables => { $name => { ... } },
columns => { $table => [ { ... }, ... ] },
indexes => { $table => { $name => { ... } } },
foreign_keys => { $table => [ { ... }, ... ] },
unique_constraints => { $table => { $name => { columns => [ ... ] } } },
}
Quack RPC catalogs are opaque: information_schema and duckdb_indexes() return no rows for tables in a remote Quack-attached catalog. Do not pass catalog for a Quack remote. To inspect a remote table's columns from the client side, use PRAGMA table_info('remote.tablename') directly on a known table.
Only the default main schema is introspected unless schema is overridden.
ATTRIBUTES
schema
Schema name to introspect. Defaults to main.
schemas
Further schemas to read besides schema, as an arrayref. A table of one of them is keyed schema.table in every part of the model, which is how a source declared table('other.t') is named. Empty by default: nothing but schema is read.
catalog
Optional catalog name. When set, restricts introspection to the named catalog (e.g. a locally-attached file DB or DuckLake volume). Adds AND table_catalog = ? / AND database_name = ? filters to all queries. When undef (the default) the existing schema-only queries run unchanged.
Do not use with Quack RPC catalogs -- remote quack catalogs are opaque to information_schema and DuckDB system views.
METHODS
table_columns_info
Hashref { col_name = { data_type, size, is_nullable, default_value, is_auto_increment, sequence, ... } }>.
table_uniq_info
List of [ $name, \@col_names ] pairs for non-partial unique indexes and for the UNIQUE constraints of the table. PK-backed indexes are already excluded from the model.
A UNIQUE constraint written in CREATE TABLE (what the install DDL emits for add_unique_constraint) is no entry of duckdb_indexes(), so it is read from duckdb_constraints(). Only this contract method shows it; the model, and with it the diff, are unchanged.
view_definition
SQL text of the view definition, or undef. Fetched lazily from information_schema.views on demand.
NORMALIZED CONTRACT
These methods implement the generation contract defined in DBIO::Introspect::Base. The canonical-model defaults in DBIO::Introspect::Base (table_keys, table_columns, table_pk_info, table_fk_info, table_is_view) are inherited unchanged -- the DuckDB native model follows the canonical shape. Only table_columns_info (DuckDB-specific nextval() auto-increment and type-size normalization), table_uniq_info (partial-unique exclusion), and view_definition (lazy information_schema.views lookup) are overridden below. Table keys are plain table names (only the main schema is introspected).
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.