NAME

DBIO::DuckDB - DuckDB-specific schema management for DBIO

VERSION

version 0.900007

SYNOPSIS

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

my $schema = MyApp::Schema->connect('dbi:DuckDB:dbname=app.duckdb');

# or, using the `-du` shortcut:
package MyApp::Schema;
use DBIO Schema => -du;

DESCRIPTION

DBIO::DuckDB is the DuckDB driver component for DBIO. When loaded into a schema class, connection() sets "storage_type" in DBIO::Schema to +DBIO::DuckDB::Storage, which enables DuckDB-specific storage behavior.

The driver is built on top of DBD::DuckDB (which itself is a pure-FFI DBI driver -- no XS compile, only libduckdb at runtime). DuckDB is an embedded, synchronous, columnar analytical database. This driver keeps the DBI plumbing for all the boring ORM work (transactions, bind, cursor, ResultSet) and exposes the interesting DuckDB-native features as direct methods on the storage object:

Schema management (install/diff/upgrade) uses the native test-deploy-and-compare strategy via DBIO::DuckDB::Deploy.

METHODS

connection

Overrides "connection" in DBIO to force +DBIO::DuckDB::Storage as storage_type, and registers the storage layer (ADR 0032) of every declared extension whose class names one. An extension chooses a layer, never the driver: the driver is the one pinned here.

duckdb_extensions

__PACKAGE__->duckdb_extensions('httpfs', spatial => { class => 'MyApp::DB::Extension::Spatial' });

Get or set the DuckDB extensions the database of this schema has (ADR 0066 of DBIO core). The declaration is a list of extension names, each optionally followed by a hash reference of options. The only option is class: the extension class (a DBIO::Extension) of an extension that has rules of its own; it wins over the plain class. Every other option, an empty hash reference, a second one, one without a name before it and a class that is no class name croak.

A declared extension is INSTALLed and LOADed on every new connection of the schema ("_activate_extensions" in DBIO::DuckDB::Storage), and an upgrade builds its throwaway target database with the same activation ("_build_target_model" in DBIO::DuckDB::Deploy), so a type an extension adds is known to the target model. A deploy never drops an extension. Without a declaration nothing is loaded. In list context returns the declared names.

duckdb_extension_classes

my $classes = __PACKAGE__->duckdb_extension_classes;   # { spatial => 'MyApp::DB::Extension::Spatial' }

The classes "duckdb_extensions" declared, as a hash reference extension name to class name. Only the extensions that named one are in it. A copy: changing it changes nothing.

TESTING

Tests use in-memory DuckDB databases and do not require external credentials. The tests under t/ are automated TAP tests (prove -l t/); DBIO_TEST_DUCKDB_DSN can override the DSN.

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.