From: Arthur Axel 'fREW' Schmidt Date: Fri, 10 May 2013 18:41:31 +0000 (-0500) Subject: fix typos, formatting, and wording X-Git-Tag: v1.200001~1 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=1060e1bd57cbe7de09617773863e73a95442c619;p=dbsrgits%2FDBIx-Class-Manual-SQLHackers.git fix typos, formatting, and wording --- diff --git a/lib/DBIx/Class/Manual/SQLHackers/CREATE.pod b/lib/DBIx/Class/Manual/SQLHackers/CREATE.pod index eacfe4b..7eb2d8e 100644 --- a/lib/DBIx/Class/Manual/SQLHackers/CREATE.pod +++ b/lib/DBIx/Class/Manual/SQLHackers/CREATE.pod @@ -53,11 +53,11 @@ Run the included L script. =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, B and B. The classes can be used to write the actual SQL DDL to the database or disc, if required. +This section covers the common and oft used CREATE DDL statements that DBIx::Class can replace with Perl classes: B, B and B. 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: +=head4 Standard basic table creation in SQL CREATE TABLE users ( id INTEGER AUTO_INCREMENT, @@ -105,7 +105,7 @@ The recommended version: 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. -=head4 Table creation with references: +=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 column to only contain B values from the *users* table. @@ -180,7 +180,7 @@ In DBIx::Class this can have a Result Class of its own: # Defaults to 'DBIx::Class::ResultSource::Table' unless specified like this __PACKAGE__->table_class('DBIx::Class::ResultSource::View'); - __PACKAGE__->table('user_posts'); + __PACKAGE__->table('userposts'); # Do not emit SQL DDL for this particular resultsource __PACKAGE__->result_source_instance->is_virtual(1); @@ -217,7 +217,7 @@ In DBIx::Class this can have a Result Class of its own: }, ); - __PACKAGE__->set_primary_key('user_id, post_id'); + __PACKAGE__->set_primary_key('user_id', 'post_id'); =head3 CREATE INDEX @@ -233,9 +233,9 @@ To add extra unique indexes, add the B call to your Resul CREATE INDEX user_email_idx ON user (username, email); -These are not created or used by DBIx::Class itself, but can be added so that deploying (creating DDL SQL from your Schema) can include them. +These are not created or used by DBIx::Class itself, but can be added so that deploying (creating DDL SQL from your schema) can include them. -The B method allows you to add L code to your Result class. It is called with the SQL::Translator::Schema::Table object, and allows you to amend the Table before it is converted into SQL. +The B method allows you to add L code to your Result class. It is called with the SQL::Translator::Schema::Table object, and allows you to amend the Table before it is converted into SQL. sub sqlt_deploy_hook { my ($self, $sqlt_table) = @_; diff --git a/lib/DBIx/Class/Manual/SQLHackers/DELETE.pod b/lib/DBIx/Class/Manual/SQLHackers/DELETE.pod index 9d5761a..88adf3b 100644 --- a/lib/DBIx/Class/Manual/SQLHackers/DELETE.pod +++ b/lib/DBIx/Class/Manual/SQLHackers/DELETE.pod @@ -48,13 +48,13 @@ method on it. B can be called on any result row object. =back This can also be done as one statement, skipping the extra temporary -variable, if it is not needed later: +variable if it is not needed later: $schema->resultset('User')->find({ id => 1 })->delete; In the first variant, the $fred_user row object will still contain the last known contents of Fred's data. A call to $fred_user->L will return -false (0), showing that the row object is no longer connected to a actual +false (0), showing that the row object is no longer connected to an actual database row. =head2 Delete one or more rows based on a WHERE clause @@ -84,11 +84,11 @@ the B method on it directly. =back Unlike the single row deletion above, the contents of the rows to be -deleted are never fetched from the database, so no record of them now -remains. +deleted are never fetched from the database, so no record of them +remains afterwards. NOTE: Calling B on a ResultSet object will not run any -overridden B methods in your Result Classes or any loaded +overridden B methods in your Result classes or any loaded Components. To force these to run, call B instead: $old_posts->delete_all(); @@ -104,11 +104,11 @@ This will also issue a separate delete statement for each row to be removed. WHERE user_id = 1; -Cascading deletes ensure the integrity of your data, if a User row is +Cascading deletes ensure the integrity of your data. If a User row is removed, then any items belonging to that user (for example comments -created by the user), should also be removed. +created by the user) should also be removed. -NOTE: This is a rather drastic action, to prevent problems in your +NOTE: This is a rather drastic action. To prevent problems in your application, consider de-activating accounts instead of removing them! For the time being DBIx::Class defaults to cascade deletion for the @@ -121,12 +121,10 @@ L. If your database is already properly set up to cascade deletes for you, -you can noop DBIx::Class' extra cascading statements: +you can turn off DBIx::Class' extra cascading statements: __PACKAGE__->has_many('posts', 'MyDatabase::Schema::Result::Post', 'user_id', { cascade_delete => 0 }); - - diff --git a/lib/DBIx/Class/Manual/SQLHackers/INSERT.pod b/lib/DBIx/Class/Manual/SQLHackers/INSERT.pod index 1c5325d..c192a0e 100644 --- a/lib/DBIx/Class/Manual/SQLHackers/INSERT.pod +++ b/lib/DBIx/Class/Manual/SQLHackers/INSERT.pod @@ -46,7 +46,7 @@ In scalar or list context populate is a proxy to the B method (on which =back -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). +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). =head2 Constructing and inserting Row object @@ -61,7 +61,7 @@ In the course of your application, you will often want to retrieve data from a u my $schema = MyDatabase::Schema->connect('dbi:SQLite:my.db'); -(ideally you will always have one of these handy, no need to make many connections to the database) +(Ideally you will always have one of these handy, no need to make many connections to the database.) NB: DBIx::Class does not store a Singleton schema object for you, calling C again will create a new Schema object with a new database connection. Avoid doing this, store and re-use the Schema object. @@ -74,13 +74,13 @@ NB: DBIx::Class does not store a Singleton schema object for you, calling C 'secretpass', }); - $newuser is now a DBIx::Class::Row object, containing uninserted data. This can be verified by calling $newuser->in_storage, which will return false. +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. -=item 3. Insert the users data into the database: +=item 3. Insert the user's data into the database: $newuser->insert(); - $newuser has been updated to contain the auto-incremented id value in its primary key field (id). $newuser->in_storage now returns true. +$newuser has been updated to contain the auto-incremented id value in its primary key field (id). C<< $newuser->in_storage >> now returns true. You can also shortcut these two methods if you don't need to build up the Row object before inserting: diff --git a/lib/DBIx/Class/Manual/SQLHackers/SELECT.pod b/lib/DBIx/Class/Manual/SQLHackers/SELECT.pod index 44a0513..eb74ce8 100644 --- a/lib/DBIx/Class/Manual/SQLHackers/SELECT.pod +++ b/lib/DBIx/Class/Manual/SQLHackers/SELECT.pod @@ -54,7 +54,7 @@ You can either fetch all the data at once, or iterate over the results: =head2 Fetching column values from a Row object -The Row object represents the results from a single data source in the query. The column values can be retrieved by using the accessor methods named after the column names. (By default that is, accessors can be changed in the L if needed). +The Row object represents the results from a single data source in the query. The column values can be retrieved by using the accessor methods named after the column names. (By default that is; accessors can be changed in the L if needed.) print $user->username; @@ -116,7 +116,7 @@ B also works well on unique constraints, for example the username of our u FROM users WHERE dob = '1910-02-01'; -To select all users born on the date '1910-02-01', we can use the B method to prepare a query. Search returns a new resultset with the search conditions stored in it, it does not run the query on the database. +To select all users born on the date '1910-02-01', we can use the B method to prepare a query. Search returns a new resultset with the search conditions stored in it; it does not run the query on the database. =over @@ -136,39 +136,67 @@ To run the query, use the B or B methods shown at the beginning of th =head2 SELECT with different WHERE conditions -Below are shown some common SQL where conditions. The syntax for these is parsed by a module called L which DBIx::Class uses. They can all be passed to the B method as conditions. +Shown below are some common SQL WHERE conditions. The syntax for these is parsed by a module called L, which DBIx::Class uses. They can all be passed to the B method as conditions. SELECT id, username, dob, realname, password FROM users WHERE username LIKE 'fred%'; - my $name_search = $schema->resultset('User')->search( - { username => { '-like' => 'fred%' } } - ); +=cut + +=pod + + my $name_search = $schema->resultset('User')->search( + { username => { '-like' => 'fred%' } } + ); + +=cut + +=pod SELECT id, username, dob, realname, password FROM users WHERE dob BETWEEN '1910-01-01' AND '1910-12-31'; - my $year_dob_search = $schema->resultset('User')->search( - { dob => { '-between' => ['1910-01-01', '1910-12-31'] } } - ); +=cut + +=pod + + my $year_dob_search = $schema->resultset('User')->search( + { dob => { '-between' => ['1910-01-01', '1910-12-31'] } } + ); + +=cut + +=pod SELECT id, username, dob, realname, password FROM users WHERE dob IN ('1910-02-01', '1910-02-02'); - my $feb_dob_search = $schema->resultset('User')->search( - { dob => { '-in' => ['1910-02-01', '1910-02-02'] } } - ); +=cut + +=pod + + my $feb_dob_search = $schema->resultset('User')->search( + { dob => { '-in' => ['1910-02-01', '1910-02-02'] } } + ); + +=cut + +=pod SELECT id, username, dob, realname, password FROM users WHERE dob >= 1911-01-01; - my $next_year_dob = $schema->resultset('User')->search( - { dob => { '>=', '1911-01-01' } } - ); +=cut + +=pod + + my $next_year_dob = $schema->resultset('User')->search( + { dob => { '>=', '1911-01-01' } } + ); =head2 SELECT with WHERE condition on JOINed table @@ -195,7 +223,7 @@ The second argument to B is a hashref of attributes to apply to the quer =back -Note that the string "user", used twice here, refers to the B of the L between the "Post" source and the "User" source. All dealings with related tables are refered to by relationship names, not table names. +Note that the string "user", used twice here, refers to the B of the L between the "Post" source and the "User" source. All dealings with related tables are referred to by relationship names, not table names. To run the query, use the B or B methods show at the beginning of this page. @@ -221,7 +249,7 @@ There's usually little reason to do this sort of query, as fetching all the data =back -Note that accessors for other columns not fetched will return B, which is also the perl equivalent of the SQL C value. To disambiguate between an C meaning "this column is set null" and "we never retrieved the value of this column" use L. +Note that accessors for other columns not fetched will return B, which is also the perl equivalent of the SQL C value. To disambiguate between an C meaning "this column is set null" and "we never retrieved the value of this column" use L. =head2 SELECT with aggregates @@ -229,7 +257,7 @@ Note that accessors for other columns not fetched will return B, which is SELECT COUNT(*) FROM users; -To find out how many users exist. This simple one can be achieved with a built-in method, B. +Finding out how many users exist can be achieved with a built-in method, B. =over @@ -237,7 +265,7 @@ To find out how many users exist. This simple one can be achieved with a built-i my $schema = MyDatabase::Schema->connect('dbi:SQLite:my.db'); -=item 2. Call the *count* method on the resultset for the [Source] you wish to fetch data from: +=item 2. Call the B method on the resultset for the L you wish to fetch data from: my $posts_count = $schema->resultset('Post')->count(); @@ -258,14 +286,13 @@ A rather pointless exercise in summing an entire "amount" column from an imagina =item 2. Call the B method on the resultset for the L you wish to fetch data from, then the B method: - my $sum_prices = $schema->resultset('Price')->get_column('amount') - ->sum(); + my $sum_prices = $schema->resultset('Price')->get_column('amount')->sum(); =back The result is just a number. -The alternate way uses the B method and is easier to build further refinements into. +The alternative way uses the B method and is easier to build further refinements into. =over @@ -337,7 +364,7 @@ To group your results, use the B attribute on a B method. We a my $schema = MyDatabase::Schema->connect('dbi:SQLite:my.db'); -=item 2. Call the *search* method on the resultset of the L you wish to group data on: +=item 2. Call the B method on the resultset of the L you wish to group data on: my $posts_count_per_user = $schema->resultset('User')->search( { }, @@ -490,7 +517,7 @@ The result will be an arrayref of the actual values. If a ResultSet object is ne FROM users FOR UPDATE -To fetch data and lock it for updating from other transactions, use the B attribute and pass it the value B. This should be done inside a L. +To fetch data and lock it for updating from other transactions, use the B attribute and pass it the value B. This should be done inside a L. =over @@ -509,7 +536,7 @@ To fetch data and lock it for updating from other transactions, use the B a =back -The resultset and rows will be returned as normal, and can be used to update the rows without worrying about other +The resultset and rows will be returned as normal, and can be used to update the rows without worrying about other processes modifying the table behind your back. =head2 SELECT with LIMIT and OFFSET @@ -540,4 +567,3 @@ To reduce the set of rows fetched, use the B and B attributes. The v This will return exactly 10 row objects, sorted by descending date of birth of the users, starting at the 11th row of the sorted result. =back - diff --git a/lib/DBIx/Class/Manual/SQLHackers/Transactions.pod b/lib/DBIx/Class/Manual/SQLHackers/Transactions.pod index ad1552a..091fe67 100644 --- a/lib/DBIx/Class/Manual/SQLHackers/Transactions.pod +++ b/lib/DBIx/Class/Manual/SQLHackers/Transactions.pod @@ -27,8 +27,8 @@ DBIx::Class::Manual::SQLHackers::Transactions - DBIx::Class for SQL Hackers - DE UPDATE users SET username = 'fred' WHERE id = 1; COMMIT; -To create a transaction, put all your changes inside a coderef, and pass it to the B method on the Schema object. Transactions can also be safely nested, -in which case all but the top level transaction blocks become noops. +To create a transaction, put all your changes inside a coderef and pass it to the B method on the Schema object. Transactions can also be safely nested, +in which case all but the top level transaction blocks become no-ops. =over diff --git a/lib/DBIx/Class/Manual/SQLHackers/UPDATE.pod b/lib/DBIx/Class/Manual/SQLHackers/UPDATE.pod index ac291cb..d57fa8f 100644 --- a/lib/DBIx/Class/Manual/SQLHackers/UPDATE.pod +++ b/lib/DBIx/Class/Manual/SQLHackers/UPDATE.pod @@ -26,7 +26,7 @@ DBIx::Class::Manual::SQLHackers::UPDATE - DBIx::Class for SQL Hackers - UPDATE Individual rows may be updated via their Result object in one of two ways. You can create an object representing an existing database table -row and hold it in your programmes memory, passing it around from +row and hold it in your program's memory, passing it around from function to function changing its values, before actually updating the contents into the database. This is a delayed update. @@ -36,13 +36,13 @@ the update method is called and passed the set of new values to store in the table. NOTE: Running a direct update on a row object that already has changed -values, will *also* apply those values to the database. If values are -changed both on the object, and in the update method arguments, the +values will B apply those values to the database. If some values are +changed both on the object and in the update method arguments, the argument values take precedence. =head2 Updating a row in memory -To create a Row object for delayed update (or other manipulations), first fetch it from the database as described in L. +To create a Row object for delayed update (or other manipulations), first fetch it from the database as described in L. =over @@ -66,9 +66,9 @@ the B method. This value has not yet changed in the database, we can make the actual -update by calling *update*: +update by calling B: -=item 4. Update the set value(s) into the database: +=item 4. Write the new value(s) into the database: $fred_user->update(); @@ -78,7 +78,7 @@ The update method will only actually send an UPDATE statement to the database if one or more of the columns have changed. The internal tracking of which columns have been changed can be queried using several methods. B returns true (or a list of changed -column names), if any column values have changed. B +column names) if any column values have changed. B will return true or false for the given column name argument. The previous values of the columns are not stored. @@ -101,8 +101,8 @@ To update an existing row, first B it using the methods shown in Lresultset('User')->find({ id => 1 }); - The Row object has an B method that will change the values on -the object, and send an UPDATE query to the database. +The Row object has an B method that will change the values on +the object and send an UPDATE query to the database. =item 3. Call the B method, passing it a hashref of new data: @@ -110,9 +110,7 @@ the object, and send an UPDATE query to the database. =back -See also: L. - -## Removed from UPDATE.pod: +See also: L. =head2 Update a row or rows using a column calculation @@ -138,7 +136,7 @@ the object, and send an UPDATE query to the database. $fred_user->update({ username => \['username || ?', [ {} => '.uk'] ] }); -The \[ .. ] syntax here is base on L, and adds some extra syntax for the "values" to be able to supply things like the exact SQL bind type and so on. This extra syntax will be documented in DBIx::Class soon. +The C<\[ ... ]> syntax here is based on L, and adds some extra syntax for the "values" to be able to supply things like the exact SQL bind type and so on. This extra syntax will be documented in DBIx::Class soon. =back @@ -203,18 +201,18 @@ To avoid race conditions, this should be done in a transaction. =item 3. Call the B method on the resultset for the L you wish to update data in: - $schema->resultset('User')->update_or_create( - { - username => 'joebloggs', - dob => '2010-09-10', - realname = 'Joe Bloggs' - }, - { - key => 'uniq_username' - } - ); + $schema->resultset('User')->update_or_create( + { + username => 'joebloggs', + dob => '2010-09-10', + realname = 'Joe Bloggs' + }, + { + key => 'uniq_username' + } + ); -=item 4. Close off the transaction / coderef: +=item 4. Close off the coderef / transaction: } ); @@ -223,9 +221,9 @@ To avoid race conditions, this should be done in a transaction. A transaction is issued containing two statements, a B