/ 
DBIO-DuckDB-0.900000
/ DBIO::DuckDB::Introspect

NAME

DBIO::DuckDB::Introspect - Introspect a DuckDB database via information_schema + duckdb_* views

VERSION

version 0.900000

DESCRIPTION

DBIO::DuckDB::Introspect reads the live state of a DuckDB database via the standard SQL information_schema views and DuckDB's system views (duckdb_tables(), duckdb_columns(), duckdb_indexes(), duckdb_constraints()). 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 => [ { ... }, ... ] },
}

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.

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 [ $index_name, \@col_names ] pairs for non-partial unique indexes. PK-backed indexes are already excluded from the model.

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.