Updates with changes merged/edited from ribasushis review

[dbsrgits/DBIx-Class-Manual-SQLHackers.git] / lib / DBIx / Class / Manual / SQLHackers / INSERT.pod

diff --git a/lib/DBIx/Class/Manual/SQLHackers/INSERT.pod b/lib/DBIx/Class/Manual/SQLHackers/INSERT.pod
index 8686d5b..87742a9 100644 (file)
--- a/lib/DBIx/Class/Manual/SQLHackers/INSERT.pod
+++ b/lib/DBIx/Class/Manual/SQLHackers/INSERT.pod
@@ -27,7 +27,7 @@ DBIx::Class::Manual::SQLHackers::INSERT - DBIx::Class for SQL Hackers - INSERT
 
 =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.
 
@@ -37,24 +37,24 @@ In scalar or list context populate is a proxy to the B<create> method (on which
 
         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
 
@@ -100,7 +100,7 @@ Now *$newuser* is a Row object containing data that represents what is in the da
     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
 
@@ -115,7 +115,7 @@ Now that we have a user, they would like to submit their first blog post. We alr
 
 =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
 
@@ -161,7 +161,7 @@ This also can be shortcut using B<create>:
 
         ## new+insert in one
         my $newuser = $schema->resultset('User')->create( $user_and_post );
-       
+
 =back
 
 =head2 Insert using a SELECT as input: