NAME

DBIx::Class::Tutorial::FromDatabase - Setting up DBIx::Class using an existing database

INTRODUCTION

You want to get started using DBIx::Class and you already have a database you want to use. This page will explain how to create the files you need for DBIx::Class using DBIx::Class::Schema::Loader. For an explanation of the resulting files, please see DBIx::Class::Tutorial::FromScratch.

GLOSSARY

See DBIx::Class::Manual::Glossary.

Some terms needed for this chapter:

"Loader" in DBIx::Class::Manual::Glossary

"Schema" in DBIx::Class::Manual::Glossary

"Result class" in DBIx::Class::Manual::Glossary

"ResultSet" in DBIx::Class::Manual::Glossary

DESCRIPTION

Modules needed

DBI
DBIx::Class
DBIx::Class::Schema::Loader

A DBD module appropriate for your database, one of the following:

DBD::SQLite

DBD::mysql

DBD::Pg

Initial import

DBIx::Class::Schema::Loader has two modes of operation: dynamic import to re-read the database structure on every startup of the application, and static import to create a set of DBIx::Class schema files that the application can load as normal perl modules.

The dynamic version can be used for quick and dirty scripts, but for a full application it is more useful to use the static version for more control. Both of these allow you to add methods you need to the schema files.

The static mode can also re-scan the database when changes are made to the structure, and import them into your schema files. This is made repeatable by storing an md5sum of the file parts controlled by Loader, allowing the developer to edit the rest of the file as he chooses.

To create a set of static schema files, change to the top level directory of your application and run the following command adapted for your database:

  perl -MDBIx::Class::Schema::Loader=make_schema_at,dump_to_dir:./lib \
    -e 'make_schema_at("MyDatabase::Schema", { debug => 1 }, \
    [ "dbi:mysql:dbname=MyDatabase","user", "passwd" ])'

make_schema_at is a handy command to export your database structure into DBIx::Class module files. It takes three arguments, a module name for schema file to create, second a set of options, and third a set of connection parameters for the database.

dump_to_dir

This is the directory to save the created files into. If you run the command from the top directory of your application, just use the default of ./lib.

schema package name

The first argument to the make_schema_at method is the package name of the DBIx::Class schema you are creating. These are often called <appname>::Schema or <dbname>::Schema.

options hashref

The second argument to make_schema_at is a hashref of options, these are described in DBIx::Class::Schema::Loader::Base. To start, just use { debug = 1} > so you get some idea of what the command is doing.

connection parameters

The last argument to make_schema_at is an arrayref of parameters to connect to the database.

The first is a DBI style dsn, it consists of colon-separated strings. The dsn starts with dbi, followed by the name of the DBD (database driver) for the particular database you are using. These are case senstive, to find an appropriate driver for your database, look on search.cpan.org for DBD:: modules.

The next two parameters are the username and password for your database.

The last and optional parameter is a hashref of special DBI options.

For more details of the command, see "make_schema_at" in DBIx::Class::Schema::Loader. For the parameters see DBIx::Class::Schema::Loader::Base.

This will create a result class file for each database table (in lib/MyDatabase/Schema/), plus the file MyDatabase/Schema.pm which is the DBIx::Class::Schema file.

File edits

DBIx::Class::Schema::Loader dumps the schema of your database into DBIx::Class result class files for you. It doesn't prevent you from editing those files and adding your own methods to the bottom of the file. Each file will contain an md5sum of the data it was created with originally. Example:

  # Created by DBIx::Class::Schema::Loader v0.04004 @ 2008-07-27 12:07:03
  # DO NOT MODIFY THIS OR ANYTHING ABOVE! md5sum:MGMGw4Ti7kCvNbsQdzBH6Q

  # You can replace this text with custom content, and it will be preserved on regeneration
  1;

Any methods you want to add can go where the "# You can replace ..." comment is. Re-running the make_schema_at command will replace the upper part of the file with any new schema changes, and will leave your methods as they are.

Database structure changes

You will need to make a decision: Is the database itself the definition of your data layout, or can you use the DBIx::Class files as the definition? If someone else owns the database and it's structure, you will need to update your schema to match the database layout when it changes.

When the database layout has been changed, simply re-run the make_schema_at command as you initially did to create the files.

After the files have been updated, you will need to re-test your code and update it to accommdate any new, removed or changed columns etc.

If you own both the database and your perl code, just decide which you'd rather edit and keep as the definition, and update the other from it.

Later on in this tutorial, we will refer back to other differences between using the database as the source, and using the DBIx::Class files as the source.