/ 
DBIO-0.900000
/ DBIO::Manual::Component

NAME

DBIO::Manual::Component - Developing DBIO Components

VERSION

version 0.900000

WHAT IS A COMPONENT

A component is a module that can be added to your DBIO classes to provide extra functionality. A good example is DBIO::InflateColumn, which automatically inflates and deflates column values to and from Perl objects.

DBIO distinguishes between core infrastructure -- the classes every result class transitively inherits from, whether you ask for them or not -- and optional components that you opt into via load_components.

USING

Optional components are loaded with load_components() on your result class:

package My::Schema::Result::Thing;
use base qw( DBIO::Core );
__PACKAGE__->load_components(qw/InflateColumn::DateTime Timestamp/);

You usually omit the DBIO:: prefix; load_components looks under DBIO:: by default. To load a component outside that namespace, prefix the name with +:

__PACKAGE__->load_components(qw/ +My::Component /);

The order in which components are loaded matters -- it determines the order they appear in the C3 inheritance chain. If a component overrides a method also overridden by another component, the one loaded first wins. When in doubt, read the docs of the components you are using.

CREATING COMPONENTS

A component is a class inheriting from DBIO::Base:

package DBIO::MyComp;
use base qw(DBIO::Base);
# Add methods, accessors, load other components, etc.
1;

When loaded, the component is injected into the result class' inheritance chain via Class::C3. A component can provide new methods, override methods provided by other components, or hook into lifecycle methods on DBIO::Row:

sub insert {
  my $self = shift;
  # Do stuff with $self before insert.
  return $self->next::method(@_);
}

sub delete {
  my $self = shift;
  # Do stuff with $self before delete.
  return $self->next::method(@_);
}

Components loaded earlier sit closer to the front of the @ISA chain. If you override insert() but DBIO::Row appears in the chain before your component, your override is shadowed. To inspect the actual resolution order:

print join ', ', mro::get_linear_isa('YourClass::Name');

CORE INFRASTRUCTURE

These classes are the substrate for every result class. They are loaded implicitly by DBIO::Core and you do not list them in load_components.

DBIO::Core -- The standard component bundle that user-facing result classes inherit from. Loads the rest of the core infrastructure.

DBIO::Row -- Per-row state, accessors, insert/update/delete, the lifecycle hook surface every other component cooperates with.

DBIO::PK -- Primary key handling.

DBIO::ResultSourceProxy -- Provides __PACKAGE__->table(...) and proxies result-source methods onto the result class.

DBIO::Relationship -- Inter-table relationships (belongs_to, has_many, might_have, many_to_many).

DBIO::InflateColumn -- Per-column inflate/deflate hook used by both core and optional components.

BUILT-IN OPTIONAL COMPONENTS

These ship in the DBIO core distribution and are loaded explicitly via load_components.

DBIO::InflateColumn::DateTime -- Inflate date/time columns to DateTime objects.

DBIO::InflateColumn::Serializer -- Serialise complex Perl structures into a single column (JSON, Storable, YAML).

DBIO::FilterColumn -- Bidirectional filter callbacks between in-memory and storage representations.

DBIO::Timestamp -- set_on_create / set_on_update column flags for automatic timestamp maintenance.

DBIO::EncodedColumn -- One-way encode columns such as passwords.

DBIO::UUIDColumns -- uuid_on_create column flag for automatic UUID generation on insert.

DBIO::Ordered -- position / grouping column flags to maintain a position column over an ordered list of rows.

DBIO::HashAccessor -- Generate get/set/exists/delete/push helpers for serialised hash columns.

DBIO::ChangeLog -- Record per-column change history into companion ChangeLog tables. Per-column changelog => 0 flag to exclude sensitive fields.

SEE ALSO

DBIO::Manual::Cookbook

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.