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