lib/DBIx/Class/Manual/SQLHackers/INSERT.pod

   1 =head1 NAME
   2
   3 DBIx::Class::Manual::SQLHackers::INSERT - DBIx::Class for SQL Hackers - INSERT
   4
   5 =over
   6
   7 =item L<Introduction|DBIx::Class::Manual::SQLHackers::Introduction>
   8
   9 =item L<CREATE|DBIx::Class::Manual::SQLHackers::CREATE>
  10
  11 =item INSERT
  12
  13 =item L<SELECT|DBIx::Class::Manual::SQLHackers::SELECT>
  14
  15 =item L<UPDATE|DBIx::Class::Manual::SQLHackers::UPDATE>
  16
  17 =item L<DELETE|DBIx::Class::Manual::SQLHackers::DELETE>
  18
  19 =item L<BEGIN, COMMIT|DBIx::Class::Manual::SQLHackers::Transactions>
  20
  21 =back
  22
  23 =head1 INSERTing data
  24
  25     INSERT INTO users (id, username, dob, realname, password)
  26     VALUES (1, 'fredbloggs', '1910-02-01', 'Fred Bloggs', 'secretpass');
  27
  28 =head2 Simple bulk insertion, populating rows
  29
  30 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 optimized "execute_for_fetch" method.
  31
  32 In scalar or list context populate is a proxy to the B<create> method (on which more below), and returns Row objects.
  33
  34 =over
  35
  36 =item 1. Create a Schema object representing the database you are working with:
  37
  38         my $schema = MyDatabase::Schema->connect('dbi:SQLite:my.db');
  39
  40 =item 2. Call the B<populate> method for the ResultSource you wish to insert data into:
  41
  42         $schema->populate('User', [
  43           [qw(id  username      dob           realname       password     )],
  44           [   1,  'fredbloggs', '1910-02-01', 'Fred Bloggs', 'secretpass' ],
  45         ]);
  46
  47 =back
  48
  49 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 (e.g. InflateColumn components).
  50
  51 =head2 Constructing and inserting Row object
  52
  53     INSERT INTO users (username, dob, realname, password)
  54     VALUES ('fredbloggs', '1910-02-01', 'Fred Bloggs', 'secretpass');
  55
  56 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)
  57
  58 =over
  59
  60 =item 1. Obtain a Schema object:
  61
  62         my $schema = MyDatabase::Schema->connect('dbi:SQLite:my.db');
  63
  64 (Ideally you will always have one of these handy, no need to make many connections to the database.)
  65
  66 NB: DBIx::Class does not store a Singleton schema object for you, calling C<connect> again will create a new Schema object with a new database connection. Avoid doing this, store and re-use the Schema object.
  67
  68 =item 2. Create a User object:
  69
  70         my $newuser = $schema->resultset('User')->new({
  71           username  => 'fredbloggs',
  72           dob       => '1910-02-01',
  73           realname  => 'Fred Bloggs',
  74           password  => 'secretpass',
  75         });
  76
  77 B<$newuser> is now a DBIx::Class::Row object, containing uninserted data. This can be verified by calling C<< $newuser->in_storage >>, which will return false.
  78
  79 =item 3. Insert the user's data into the database:
  80
  81         $newuser->insert();
  82
  83 $newuser has been updated to contain the auto-incremented id value in its primary key field (id). C<< $newuser->in_storage >> now returns true.
  84
  85 You can also shortcut these two methods if you don't need to build up the Row object before inserting:
  86
  87         ## new+insert in one
  88         my $newuser = $schema->resultset('User')->create({
  89           username  => 'fredbloggs',
  90           dob       => '1910-02-01',
  91           realname  => 'Fred Bloggs',
  92           password  => 'secretpass',
  93         });
  94
  95 Now B<$newuser> is a Row object containing data that represents what is in the database.
  96
  97 =back
  98
  99 =head2 Add a post for this user
 100
 101     INSERT INTO posts (user_id, created_date, title, post)
 102     VALUES (1, '2010-03-24T09:00:00', 'First post!', 'Just testing my blog');
 103
 104 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.
 105
 106 =over
 107
 108 =item 1. Add a post for an existing user:
 109
 110         ## Remember, create == new and insert.
 111         my $post = $user->create_related('posts', {
 112           created_date => '2010-03-24T09:00:00',
 113           title        => 'First post!',
 114           post         => 'Just testing my blog',
 115         });
 116
 117 =back
 118
 119 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.
 120
 121 =head2 Insert a new user and their first post
 122
 123     INSERT INTO users (username, dob, realname, password)
 124     VALUES ('fredbloggs', '1910-02-01', 'Fred Bloggs', 'secretpass');
 125
 126     INSERT INTO posts (user_id, created_date, title, post)
 127     VALUES (1, '2010-03-24T09:00:00', 'First post!', 'Just testing my blog');
 128
 129 This is a somewhat contrived example, as hopefully you'll want to create the user, and confirm who they are via email confirmation or similar, before allowing them to submit a blog post. Maybe it can be used for commenters and comments..
 130
 131 =over
 132
 133 =item 1. Create a Schema object:
 134
 135         my $schema = MyDatabase::Schema->connect('dbi:SQLite:my.db');
 136
 137 (You still have one of these, right?)
 138
 139 =item 2. Collect the User and first Post data:
 140
 141         my $user_and_post = {
 142           username  => 'fredbloggs',
 143           dob       => '1910-02-01',
 144           realname  => 'Fred Bloggs',
 145           password  => 'secretpass',
 146           posts     => [ {
 147              created_date => '2010-03-24T09:00:00',
 148              title        => 'First post!',
 149              post         => 'Just testing my blog',
 150           } ],
 151         });
 152
 153 =item 3. Create the User object together with the post data:
 154
 155         my $newuser = $schema->resultset('User')->new( $user_and_post );
 156
 157 =item 4. Insert the user and post data into the database:
 158
 159         $newuser->insert();
 160
 161 This also can be shortcut using B<create>:
 162
 163         ## new+insert in one
 164         my $newuser = $schema->resultset('User')->create( $user_and_post );
 165
 166 =back
 167