--- name: "DBIx::Class::Manual::QuickStart" section: "3pm" platform: "linux" package: "libdbix-class-perl" version: "0.082844-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/DBIx::Class::Manual::QuickStart" --- # DBIx::Class::Manual::QuickStart(3pm) up and running with DBIC in 10 minutes ## NAME DBIx::Class::Manual::QuickStart - up and running with DBIC in 10 minutes ## DESCRIPTION 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. ### Preparation 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 -e'CPAN::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: ``` $schema->resultset('Artist')->create({ 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*. ``` $schema->resultset('Cd')->search( { title => 'ReLoad', } )->update_all( { year => 1997, } ); ``` *Removing data* Removes all tracks titled *Fuel* regardless of which CD the belong to. ``` $schema->resultset('Track')->search( { title => 'Fuel', } )->delete_all; ``` ### 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_resultset->result_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 ./insertdb.pl # 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. ## FURTHER QUESTIONS? Check the list of additional DBIC resources. ## COPYRIGHT AND LICENSE 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.