/ 
DBIO-DuckDB-0.900000
/ DBIO::DuckDB::Deploy

NAME

DBIO::DuckDB::Deploy - Deploy and upgrade DuckDB schemas via test-deploy-and-compare

VERSION

version 0.900000

DESCRIPTION

DBIO::DuckDB::Deploy orchestrates schema deployment and upgrades for DuckDB using the test-deploy-and-compare strategy, parallel to DBIO::SQLite::Deploy and DBIO::PostgreSQL::Deploy.

For upgrades it:

1. Introspects the live database via information_schema / duckdb_*
2. Connects to a fresh in-memory DuckDB database
3. Deploys the desired schema (from DBIO classes) into that in-memory DB
4. Introspects the in-memory database the same way
5. Computes the diff between the two models using DBIO::DuckDB::Diff

DuckDB supports :memory: so the throwaway DB is as cheap as with SQLite -- no CREATE DATABASE dance like PostgreSQL.

my $deploy = DBIO::DuckDB::Deploy->new(
    schema => MyApp::DB->connect("dbi:DuckDB:dbname=app.duckdb"),
);
$deploy->install;                       # fresh
my $diff = $deploy->diff;               # or step-by-step
$deploy->apply($diff) if $diff->has_changes;
$deploy->upgrade;                       # convenience

ATTRIBUTES

schema

A connected DBIO::Schema instance using the DBIO::DuckDB component. Required.

catalog

Optional catalog name (e.g. a locally-attached file database). When set, the source introspection is scoped to this catalog. Useful for multi-catalog deployments and DuckLake.

Not applicable for Quack RPC remotes. The remote catalog is opaque to information_schema -- deploy the schema on the server process instead, not against the client-side quack attach. Use PRAGMA table_info('remote.t') on the client to verify remote columns.

METHODS

install

$deploy->install;

Generates DDL via "install_ddl" in DBIO::DuckDB::DDL and executes each statement against the connected database. Suitable for fresh installs. Inherited from DBIO::Deploy::Base.

diff

my $diff = $deploy->diff;

Computes the difference between the live database and the desired state. Spins up a throwaway in-memory DuckDB, deploys the desired schema there, introspects both, and returns a DBIO::DuckDB::Diff object. The orchestration is inherited from DBIO::Deploy::Base; only the in-memory target build ("_build_target_model") and the catalog-aware source introspection ("_new_introspect") are DuckDB-specific.

apply

$deploy->apply($diff);

Applies a DBIO::DuckDB::Diff object by executing each statement from $diff->as_sql. No-op if the diff has no changes. Inherited from DBIO::Deploy::Base.

upgrade

my $diff = $deploy->upgrade;

Convenience: calls "diff" then "apply". Returns the diff object if changes were applied, or undef if the database was already up to date. Inherited from DBIO::Deploy::Base.

_new_introspect

Factory for the source-side introspector. Overrides "_new_introspect" in DBIO::Deploy::Base to forward the catalog attribute (for locally-attached file / DuckLake catalogs) when it is set.

_build_target_model

Builds the desired-state model: connects a throwaway in-memory DuckDB, deploys the install DDL there, and introspects it. DuckDB supports :memory:, so this is as cheap as with SQLite -- no temporary-database dance like PostgreSQL. The temp DB is never scoped to catalog.

SEE ALSO

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.