=item L<BEGIN, COMMIT|DBIx::Class::Manual::SQLHackers::Transactions>
+=back
+
=head1 Database structure
-To use DBIx::Class, we need to teach it about the layout of the underlying database. Several methods are supported. The built-in method involves defining your database structure as a set of perl modules. The other oft used method is to import the definitions from an existing database using the module
+To use DBIx::Class, we need to teach it about the layout of the underlying database. Several methods are supported. The built-in method involves defining your database structure as a set of perl classes, one per resultsource (table, view, etc). The other oft used method is to import the definitions from an existing database using the module
L<DBIx::Class::Schema::Loader>.
-Once a DBIx::Class schema (set of classes describing the database) has been created, built-in methods can be used to export it to SQL using L<SQL::Translator>.
+Once a DBIx::Class schema (set of classes describing the database) has been created, built-in methods can be used to export it as SQL DDL using L<SQL::Translator>.
=head2 Using Loader
Run the included L<dbicdump> script.
- dbicdump -Ilib -o dump_directory=./lib \
+ dbicdump -o dump_directory=./lib \
-o components='["InflateColumn::DateTime"]' \
-o preserve_case=1 \
- MyApp::Schema dbi:mysql:database=foo user pass '{ quote_char => "`" }'
+ MyApp::Schema dbi:mysql:database=foo user pass '{ quote_names => 1 }'
=head2 Manual Result class creation (and understanding Loader results)
+This section covers the common and oft used CREATE DDL statements that DBIx::Class can replaces with Perl classes: B<CREATE TABLE>, B<CREATE VIEW> and B<CREATE INDEX>. The classes can be used to write the actual SQL DDL to the database or disc, if required.
+
=head3 CREATE TABLE
=head4 Standard basic table creation in SQL:
The fully descriptive version is required if you want to have DBIx::Class create your CREATE TABLE sql for you later. Many DBIC components also use settings in the column info hashrefs to decide how to treat the data for those columns.
-The snappy version:
-
- package MyDatabase::Schema::Result::User;
- use strict;
- use warnings;
-
- use base 'DBIx::Class::Core';
-
- __PACKAGE__->table('users');
- __PACKAGE__->add_columns(
- id => {
- data_type => 'integer',
- is_auto_increment => 1,
- },
- qw/username dob realname password/
- );
- __PACKAGE__->set_primary_key('id');
-
- 1;
-
-This shows a minimal Result class to represent our "users" table. DBIx::Class itself does not use or care about the field types or lengths. However many external components exist on CPAN, and some of may use this information.
-
=head4 Table creation with references:
A relational database isn't worth much if we don't actually use references and constraints, so here is an example which constrains the B<user_id> column to only contain B<id> values from the *users* table.
__PACKAGE__->belongs_to('user', 'MyDatabase::Schema::Result::User', 'user_id');
1;
-The B<belongs_to> relation allows us to refer to the B<user> who authored a post as the object representing the user, rather than as just the integer tha database uses as the linking information.
+The B<belongs_to> relation creates a B<user> method which returns the user object, as well as storing JOIN information to be used when querying with JOINs. The joined colums on the remote side are taken from the remote PRIMARY KEY value, if not specified, as in this example.
+
+Relationships may also be specified with completely custom JOIN conditions, using any columns, whether the database has them defined as constraints or not, or literal values.
To allow access from the B<user> object back to the posts they have written, we need to define another relationship in the User class:
use base qw/DBIx::Class::Core/;
+ # Defaults to 'DBIx::Class::ResultSource::Table' unless specified like this
__PACKAGE__->table_class('DBIx::Class::ResultSource::View');
__PACKAGE__->table('user_posts');
+
+ # Do not emit SQL DDL for this particular resultsource
__PACKAGE__->result_source_instance->is_virtual(1);
+
__PACKAGE__->result_source_instance->view_definition(
"SELECT posts.user_id, users.username, users.dob, users.realname, posts.createddate, posts.title, posts.post
FROM users
__PACKAGE__->add_unique_constraint('username_idx' => ['username']);
-=head3 Outputting SQL
+=head3 Outputting SQL DDL
-Once the DBIC schema has been defined, you can outout the SQL needed to create the schema in the database in one of several ways.
+Once the DBIC schema has been defined, you can outout the SQL DDL needed to create the schema in your database (using the RDBMS-specific flavor of SQL DDL) in one of several ways.
=head4 Deploy directly to the database
=head4 Write out SQL files
-Create a schema object with the a database connection (any will do), and call the B<create_ddl_dir> on it.
+Create a schema object with the a database connection (any will do), and call the B<create_ddl_dir> method on it.
my $schema = MyDatabase::Schema->connect('dbi:SQLite:my.db');
$schema->create_ddl_dir(['SQLite', 'MySQL']);
-By default this will create an SQL file for MySQL, PostgreSQL and SQLite. More databases are supported by L<SQL::Translator> if necessary.
+If called with no arguments, this method will create an SQL file each for MySQL, PostgreSQL and SQLite. More databases are supported by L<SQL::Translator> if necessary.
=head4 SQL files for upgrades (ALTER TABLE)
-DBIC can also make use of L<SQL::Translator::Diff> to write out ALTER TABLE statements when the schema classes are change.
+DBIC can also make use of L<SQL::Translator::Diff> to write out ALTER TABLE statements when the schema classes are changed.
To do this, make sure that you set a B<$VERSION> in your main Schema class, and run B<create_ddl_dir> on the initial version to provide a baseline.
=head2 Simple insertion, populating rows
-The B<populate> method is for inserting chunks of data to pre-populate / initialise a database with a set of known values. In void context it uses DBI's fast "insert_bulk" method.
+The B<populate> method is for inserting chunks of data to pre-populate / initialise a database with a set of known values. In void context it uses DBI's fast "execute_array" method.
In scalar or list context populate is a proxy to the B<create> method (on which more below), and returns Row objects.
my $schema = MyDatabase::Schema->connect('dbi:SQLite:my.db');
-=item 2. Call the B<populate> method for the [Source] you wish to insert data into:
+=item 2. Call the B<populate> method for the ResultSource you wish to insert data into:
$schema->populate('User', [
- [ qw/id username, dob, realname, password/ ],
+ [ qw/id username dob realname password/ ],
[ 1, 'fredbloggs', '1910-02-01',
'Fred Bloggs', 'secretpass'],
]);
=back
-Note that in void context you can skip passing primary key values that will be supplied by the database. However no automatic assignment of foreign key values will be made, nor will any code in your Result classes be run (eg InflateColumn components).
+Note that in void context you can skip passing primary key values that will be supplied by the database, and any other values that are allowed to DEFAULT. However no code in your Result classes will be run (eg InflateColumn components).
=head2 Inserting with Row objects
INSERT INTO users (username, dob, realname, password)
VALUES ('fredbloggs', '1910-02-01', 'Fred Bloggs', 'secretpass');
-In the course of your application, you will often want to retrieve data from a user, insert it into the database, then continue to use or manipulate the resulting object.
+In the course of your application, you will often want to retrieve data from a user, insert it into the database, then continue to use or manipulate the resulting object (the object represents the state of the corresponding database row immediately after creation)
=over
INSERT INTO posts (user_id, created_date, title, post)
VALUES (1, '2010-03-24T09:00:00', 'First post!', 'Just testing my blog');
-Now that we have a user, they would like to submit their first blog post. We already have the user object, from creation, or from the session when they logged in, so we can create posts using it.
+Now that we have a user, they would like to submit their first blog post. We already have the user object, from creation, or from the session when they logged in, so we can create posts using it.
=over
=back
-This does not require us to dig out the user's database id and pass it to the insert call for the posts table, as it is already contained in the User object.
+This does not require us to dig out the user's database id and pass it to the insert call for the posts table, as it is already contained in the $user object.
=head2 Insert a new user and their first post
## new+insert in one
my $newuser = $schema->resultset('User')->create( $user_and_post );
-
+
=back
=head2 Insert using a SELECT as input:
projects / dbsrgits/DBIx-Class-Manual-SQLHackers.git / commitdiff