DBIx::Schema::UpToDate - Helps keep a database schema up to date


version 1.001


  package Local::Database;
  use parent 'DBIx::Schema::UpToDate';

  sub updates {
    shift->{updates} ||= [

      # version 1
      sub {
        my ($self) = @_;
        $self->dbh->do('-- sql');

      # version 2
      sub {
        my ($self) = @_;
        my $val = Local::Project::NewerClass->value;
        $self->dbh->do('INSERT INTO values (?)', {}, $val);

  package main;

  my $dbh = DBI->connect(@connection_args);
  Local::Database->new(dbh => $dbh);

  # do something with $dbh which now contains the schema you expect


This module provides a base class for keeping a database schema up to date. If you need to make changes to the schema in remote databases in an automated manner you may not be able to ensure what version of the database is installed by the time it gets the update. This module will apply updates (defined as perl subs (coderefs)) sequentially to bring the database schema up to the latest version from whatever the current version is.

The aim of this module is to enable you to write incredibly simple subclasses so that all you have to do is define the updates you want to apply. This is done with subs (coderefs) so you can access the object and its database handle.

It is intentionally simple and is not intended for large scale applications. It may be a good fit for small embedded databases. It can also be useful if you need to reference other parts of your application as the subs allow you to utilize the object (and anything else you can reach).

Check "SEE ALSO" for alternative solutions and pick the one that's right for your situation.


Subclasses should overwrite "updates" to return an arrayref of subs (coderefs) that will be executed to bring the schema up to date.

Each sub (coderef) will be called as a method (it will receive the object as its first parameter):

  sub { my ($self) = @_; $self->dbh->do('...'); }

The rest of the methods are small in the hopes that you can overwrite the ones you need to get the customization you require.

The updates can be run individually (outside of "up_to_date") for testing your subs...

  my $dbh = DBI->connect(@in_memory_database);
  my $schema = DBIx::Schema::UpToDate->new(dbh => $dbh, auto_update => 0);

  # don't forget this:

  # execute calls on $dbh to test changes
  $schema->dbh->do( @something );
  # test row output or column information or whatever
  ok( $test_something, $here );

  # test things

  # test changes


  is($schema->current_version, $schema->latest_version, 'updated to latest version');



Constructor; Accepts a hash or hashref of options.

Options used by the base module:

  • dbh - A database handle (as returned from DBI->connect)

    Database commands will be executed against this handle.

  • auto_update - Boolean

    By default "up_to_date" is called at initialization (just after being blessed). Set this value to false to disable this if you need to do something else before updating. You will have to call "up_to_date" yourself.

  • sql_limit - Boolean

    By default "current_version" uses a LIMIT 1 suffix. Set this value to false to disable this behavior (in case your database doesn't support the LIMIT syntax).

  • transactions - Boolean

    By default "update_to_version" does its work in a transaction. Set this value to false to disable this behavior (in case your database doesn't support transactions).


Convenience method for calling "begin_work" in DBI on the database handle if transactions are enabled.


Convenience method for calling "commit" in DBI on the database handle if transactions are enabled.


Returns the object's database handle.


Determine the current version of the database schema.


Create the version metadata table in the database and insert initial version record.


Returns the latest [possible] version of the database schema.


Returns the table name ("version_table_name") quoted by "quote_identifier" in DBI.


  @quoted = $self->quote_identifiers(qw(field1 field2));

Convenience method for passing each argument through "quote_identifier" in DBI.

Returns a list.



Sets the current database version to $version. Called from "update_to_version" after executing the appropriate update.


Returns an arrayref of subs (coderefs) that can be used to update the database from one version to the next. This is used by "up_to_date" to replay a recorded database history on the "dbh" until the database schema is up to date.



Executes the update associated with $version in order to bring database up to that version.


Ensures that the database is up to date. If it is not it will apply updates after "current_version" up to "latest_version" to bring the schema up to date.


The name to use the for the schema version metadata.

Defaults to 'schema_version'.


  • Come up with a better name (too late).

  • Add an initial_version attribute to allow altering the history


I had already written most of the logic for this module in another project when I realized I should abstract it. Then I went looking and found the modules listed in "SEE ALSO" but didn't find one that fit my needs, so I released what I had made.


Here are a number of alternative modules I have found (some older, some newer) that perform a similar task, why I didn't use them, and why you probably should.



You can find documentation for this module with the perldoc command.

  perldoc DBIx::Schema::UpToDate


The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources.

Bugs / Feature Requests

Please report any bugs or feature requests by email to bug-dbix-schema-uptodate at, or through the web interface at You will be automatically notified of any progress on the request by the system.

Source Code

  git clone


Randy Stauner <>


This software is copyright (c) 2011 by Randy Stauner.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.