From: Jess Robinson Date: Sun, 5 Sep 2010 10:57:46 +0000 (+0100) Subject: Adding more manual bits to main Manual.pod X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=92fcfd01a5408299cc040bb2282d644b46a7c41d;p=dbsrgits%2FDBIx-Class-Historic.git Adding more manual bits to main Manual.pod Updating/adding glossary definitions --- diff --git a/lib/DBIx/Class/Manual.pod b/lib/DBIx/Class/Manual.pod index 752544c..3585941 100644 --- a/lib/DBIx/Class/Manual.pod +++ b/lib/DBIx/Class/Manual.pod @@ -15,6 +15,10 @@ from your SQL database. Short answers and doc pointers to questions. +=head2 L + +Explanations of terms used in this documentation. + =head2 L Beginner guide to using DBIx::Class. @@ -31,6 +35,10 @@ How to translate known SQL JOINs into DBIx-Class-ish. Convenient recipes for DBIC usage. +=head2 L + +How to read (and write) the reference documentation. + =head2 L Lists of modules by task to help you find the correct document. diff --git a/lib/DBIx/Class/Manual/Glossary.pod b/lib/DBIx/Class/Manual/Glossary.pod index b245dc9..5cd25b6 100644 --- a/lib/DBIx/Class/Manual/Glossary.pod +++ b/lib/DBIx/Class/Manual/Glossary.pod @@ -7,7 +7,7 @@ DBIx::Class::Manual::Glossary - Clarification of terms used. This document lists various terms used in DBIx::Class and attempts to explain them. -=head1 TERMS +=head1 DBIx::Class TERMS =head2 DB schema @@ -23,23 +23,21 @@ the following L(s): =head2 Inflation The act of turning database row data into objects in -language-space. DBIx::Class further allows you to inflate your data -into perl objects which more usefully represent their contents. For -example: L for datetime or -timestamp column data. +language-space. DBIx::Class result classes can be set up to inflate +your data into perl objects which more usefully represent their +contents. For example: L for +datetime or timestamp column data. -=head2 Join +See also L. -This is an SQL keyword that gets mentioned a lot. It is used to fetch -data from more than one table at once, by Cing the tables on -fields where they have common data. +=head2 Deflation -=head2 Normalisation +The opposite of L. Existing perl objects that represent +column values can be passed to DBIx::Class methods to store into the +database. For example a L object can be automatically +deflated into a datetime string for insertion. -A normalised database is a sane database. Each table contains only -data belonging to one concept, related tables refer to the key field -or fields of each other. Some links to webpages about normalisation -can be found in L. +See L and other modules in that namespace. =head2 ORM @@ -57,23 +55,50 @@ condition between the tables. =head2 Relationship bridge A relationship bridge, such as C defines an accessor to -retrieve row contents across multiple relationships. +retrieve row contents across multiple relationships. -=head2 ResultSet +The difference between a bridge and a relationship is, that the bridge +cannot be used to C tables in a C, instead its component +relationships must be used. -This is an object representing a set of data. It can either be an -entire table, or the results of a query. The actual data is not held -in the ResultSet, it is only a description of how to fetch the data. +=head2 Schema -See also: L +A Schema object represents your entire table collection, plus the +connection to the database. You can create one or more schema objects, +connected to various databases, with various users, using the same set +of table L definitions. + +At least one L class is needed per database. + +=head2 Result class + +A Result class defines both a source of data (usually one per table), +and the methods that will be available in the L objects created +using that source. + +One Result class is needed per data source (table, view, query) used +in your application, they should inherit from L. =head2 ResultSource -ResultSource objects represent the source of your data, they are also known as -a table objects. +ResultSource objects represent the source of your data, these are +sometimes (incorrectly) called table objects. + +ResultSources do not need to be directly created, a ResultSource +instance is created for each L in your L, by +the proxied methods C and C. See also: L +=head2 ResultSet + +This is an object representing a set of conditions to filter data. It +can either be an entire table, or the results of a query. The actual +data is not held in the ResultSet, it is only a description of how to +fetch the data. + +See also: L + =head2 Record See Row. @@ -86,9 +111,28 @@ Row objects contain your actual data. They are returned from ResultSet objects. See Row. -=head2 Schema +=head2 join -A Schema object represents your entire table collection, plus the -connection to the database. You can create one or more schema objects, -connected to various databases, with various users, using the same set -of table (ResultSource) definitions. +=head2 prefetch + + +=head1 SQL TERMS + +=head2 Join + +This is an SQL keyword, it is used to link multiple tables in one SQL +statement. This enables us to fetch data from more than one table at +once, or filter data based on content in another table, without having +to issue multiple SQL queries. + +=head2 Normalisation + +A normalised database is a sane database. Each table contains only +data belonging to one concept, related tables refer to the key field +or fields of each other. Some links to webpages about normalisation +can be found in L. + +=head2 Related data + +In SQL, related data actually refers to data that are normalised into +the same table. (Yes. DBIC does mis-use this term).