Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  DBIX::CLASS::MANUAL::QUICKSTART (3)

.ds Aq ’


DBIx::Class::Manual::QuickStart - up and running with DBIC in 10 minutes



This document shows the minimum amount of code to make you a productive DBIC user. It requires you to be familiar with just the basics of database programming (what database tables, rows and columns are) and the basics of Perl object-oriented programming (calling methods on an object instance). It also helps if you already know a bit of SQL and how to connect to a database through DBI.

Follow along with the example database shipping with this distribution, see directory examples/Schema. This database is also used through-out the rest of the documentation.


First, install DBIx::Class like you do with any other CPAN distribution. See <> and perlmodinstall.

Then open the distribution in your shell and change to the subdirectory mentioned earlier, the next command will download and unpack it:

    $ perl -mCPAN -eCPAN::Shell->look("DBIx::Class")
    DBIx-Class$ cd examples/Schema

Inspect the database:

    DBIx-Class/examples/Schema$ sqlite3 db/example.db .dump

You can also use a GUI database browser such as SQLite Manager <>.

Have a look at the schema classes files in the subdirectory MyApp. The MyApp::Schema class is the entry point for loading the other classes and interacting with the database through DBIC and the Result classes correspond to the tables in the database. DBIx::Class::Manual::Example shows how to write all that Perl code. That is almost never necessary, though. Instead use dbicdump (part of the distribution DBIx::Class::Schema::Loader) to automatically create schema classes files from an existing database. The chapter Resetting the database below shows an example invocation.

    Connecting to the database

A schema object represents the database.

    use MyApp::Schema qw();
    my $schema = MyApp::Schema->connect(dbi:SQLite:db/example.db);

The first four arguments are the same as for connect in DBI.

    Working with data

Almost all actions go through a resultset object.

Adding data

Via intermediate result objects:

    my $artist_ma = $schema->resultset(Artist)->create({
        name => Massive Attack,
    my $cd_mezz = $artist_ma->create_related(cds => {
        title => Mezzanine,
    for (Angel, Teardrop) {
        $cd_mezz->create_related(tracks => {
            title => $_

Via relation accessors:

        name => Metallica,
        cds => [
                title => q{Kill Em All},
                tracks => [
                    { title => Jump in the Fire },
                    { title => Whiplash },
                title => ReLoad,
                tracks => [
                    { title => The Memory Remains },
                    { title => The Unforgiven II },
                    { title => Fuel },

Columns that are not named are filled with default values. The value undef acts as a NULL in the database.

See the chapter Introspecting the schema classes below to find out where the non-obvious source name strings such as Artist and accessors such as cds and tracks come from.

Set the environment variable DBI_TRACE=1|SQL to see the generated queries.

Retrieving data

Set up a condition.

    my $artists_starting_with_m = $schema->resultset(Artist)->search(
            name => { like => M% }

Iterate over result objects of class MyApp::Schema::Result::Artist. Result objects represent a row and automatically get accessors for their column names.

    for my $artist ($artists_starting_with_m->all) {
        say $artist->name;

Changing data

Change the release year of all CDs titled ReLoad.

            title => ReLoad,
            year => 1997,

Removing data

Removes all tracks titled Fuel regardless of which CD the belong to.

            title => Fuel,

    Introspecting the schema classes

This is useful for getting a feel for the naming of things in a REPL or during explorative programming.

From the root to the details:

    $schema->sources;                       # returns qw(Cd Track Artist)
    $schema->source(Cd)->columns;         # returns qw(cdid artist title year)
    $schema->source(Cd)->relationships;   # returns qw(artist tracks)

From a detail to the root:

    $some_result->result_source;            # returns appropriate source
    $some_resultsource->schema;             # returns appropriate schema

    Resetting the database

    # delete database file
    DBIx-Class/examples/Schema$ rm -f db/example.db

    # create database and set up tables from definition
    DBIx-Class/examples/Schema$ sqlite3 db/example.db < db/example.sql

    # fill them with data
    DBIx-Class/examples/Schema$ perl ./

    # delete the schema classes files
    DBIx-Class/examples/Schema$ rm -rf MyApp

    # recreate schema classes files from database file
    DBIx-Class/examples/Schema$ dbicdump \
        -o dump_directory=. MyApp::Schema dbi:SQLite:db/example.db

    Where to go next

If you want to exercise what you learned with a more complicated schema, load Northwind <> into your database.

If you want to transfer your existing SQL knowledge, read DBIx::Class::Manual::SQLHackers.

Continue with DBIx::Class::Tutorial and WHERE TO START READING in DBIx::Class.


Check the list of additional DBIC resources.


This module is free software copyright by the DBIx::Class (DBIC) authors. You can redistribute it and/or modify it under the same terms as the DBIx::Class library.
Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 DBIX::CLASS::MANUAL::QUICKSTART (3) 2016-02-09

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.