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 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 fast "execute_array" 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',
  45                             'Fred Bloggs', 'secretpass'],
  46                       ]);
  47
  48 =back
  49
  50 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).
  51
  52 =head2 Inserting with Row objects
  53
  54     INSERT INTO users (username, dob, realname, password)
  55     VALUES ('fredbloggs', '1910-02-01', 'Fred Bloggs', 'secretpass');
  56
  57 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)
  58
  59 =over
  60
  61 =item 1. Create a Schema object:
  62
  63         my $schema = MyDatabase::Schema->connect('dbi:SQLite:my.db');
  64
  65 (ideally you will always have one of these handy, no need to make many connections to the database)
  66
  67 =item 2. Create a User object:
  68
  69         my $newuser = $schema->resultset('User')->new({
  70           username  => 'fredbloggs',
  71           dob       => '1910-02-01',
  72           realname  => 'Fred Bloggs',
  73           password  => 'secretpass',
  74         });
  75
  76     $newuser is now a DBIx::Class::Row object, containing uninserted data. This can be verified by calling $newuser->in_storage, which will return false.
  77
  78 =item 3. Insert the users data into the database:
  79
  80         $newuser->insert();
  81
  82     $newuser has been updated to contain the auto-incremented id value in its primary key field (id). $newuser->in_storage now returns true.
  83
  84 You can also shortcut these two methods if you don't need to build up the Row object before inserting:
  85
  86         ## new+insert in one
  87         my $newuser = $schema->resultset('User')->create({
  88           username  => 'fredbloggs',
  89           dob       => '1910-02-01',
  90           realname  => 'Fred Bloggs',
  91           password  => 'secretpass',
  92         });
  93
  94 Now *$newuser* is a Row object containing data that represents what is in the database.
  95
  96 =back
  97
  98 =head2 Add a post for this user
  99
 100     INSERT INTO posts (user_id, created_date, title, post)
 101     VALUES (1, '2010-03-24T09:00:00', 'First post!', 'Just testing my blog');
 102
 103 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.
 104
 105 =over
 106
 107 =item 1. Add a post for an existing user:
 108
 109         ## Remember, create == new and insert.
 110         my $post = $user->create_related('posts', {
 111           created_date => '2010-03-24T09:00:00',
 112           title        => 'First post!',
 113           post         => 'Just testing my blog',
 114         });
 115
 116 =back
 117
 118 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.
 119
 120 =head2 Insert a new user and their first post
 121
 122     INSERT INTO users (username, dob, realname, password)
 123     VALUES ('fredbloggs', '1910-02-01', 'Fred Bloggs', 'secretpass');
 124
 125     INSERT INTO posts (user_id, created_date, title, post)
 126     VALUES (1, '2010-03-24T09:00:00', 'First post!', 'Just testing my blog');
 127
 128 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..
 129
 130 =over
 131
 132 =item 1. Create a Schema object:
 133
 134         my $schema = MyDatabase::Schema->connect('dbi:SQLite:my.db');
 135
 136 (You still have one of these, right?)
 137
 138 =item 2. Collect the User and first Post data:
 139
 140         my $user_and_post = {
 141           username  => 'fredbloggs',
 142           dob       => '1910-02-01',
 143           realname  => 'Fred Bloggs',
 144           password  => 'secretpass',
 145           posts     => [ {
 146              created_date => '2010-03-24T09:00:00',
 147              title        => 'First post!',
 148              post         => 'Just testing my blog',
 149           } ],
 150         });
 151
 152 =item 3. Create the User object together with the post data:
 153
 154         my $newuser = $schema->resultset('User')->new( $user_and_post );
 155
 156 =item 4. Insert the user and post data into the database:
 157
 158         $newuser->insert();
 159
 160 This also can be shortcut using B<create>:
 161
 162         ## new+insert in one
 163         my $newuser = $schema->resultset('User')->create( $user_and_post );
 164
 165 =back
 166
 167 =head2 Insert using a SELECT as input:
 168
 169     INSERT INTO users (id, username, dob, realname, password)
 170     SELECT (1, 'fredbloggs', '1910-02-01', 'Fred Bloggs', 'secretpass')
 171     FROM nowhere;
 172
 173 This is a TODO item for DBIC.