Merge branch 'master' into topic/constructor_rewrite

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

=head1 NAME

DBIx::Class::Manual::Glossary - Clarification of terms used.

=head1 INTRODUCTION

This document lists various terms used in DBIx::Class and attempts to
explain them.

=head1 DBIx::Class TERMS

=head2 DB schema

Refers to a single physical schema within an RDBMS. Synonymous with the terms
'database', for MySQL; and 'schema', for most other RDBMS(s).

In other words, it's the 'xyz' _thing_ you're connecting to when using any of
the following L<DSN|DBI/connect>(s):

  dbi:DriverName:xyz@hostname:port
  dbi:DriverName:database=xyz;host=hostname;port=port

=head2 Inflation

The act of turning database row data into objects in
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<DBIx::Class::InflateColumn::DateTime> for
datetime or timestamp column data.

See also L<DBIx::Class::InflateColumn>.

=head2 Deflation

The opposite of L</Inflation>. Existing perl objects that represent
column values can be passed to DBIx::Class methods to store into the
database. For example a L<DateTime> object can be automatically
deflated into a datetime string for insertion.

See L<DBIx::Class::InflateColumn> and other modules in that namespace.

=head2 ORM

Object-relational mapping, or Object-relationship modelling. Either
way it's a method of mapping the contents of database tables (rows),
to objects in programming-language-space. DBIx::Class is an ORM.

=head2 Relationship

In DBIx::Class a relationship defines the connection between exactly
two tables. The relationship condition lists the columns in each table
that contain the same values. It is used to output an SQL JOIN
condition between the tables.

=head2 Relationship bridge

A relationship bridge, such as C<many_to_many> defines an accessor to
retrieve row contents across multiple relationships.

The difference between a bridge and a relationship is, that the bridge
cannot be used to C<join> tables in a C<search>, instead its component
relationships must be used.

=head2 Schema

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</Result class> definitions.

At least one L<DBIx::Class::Schema> 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</Row> 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<DBIx::Class::Core>.

=head2 ResultSource

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</Result class> in your L</Schema>, by
the proxied methods C<table> and C<add_columns>.

See also: L<DBIx::Class::ResultSource/METHODS>

=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<DBIx::Class::ResultSet/METHODS>

=head2 Record

See Row.

=head2 Row

Row objects contain your actual data. They are returned from ResultSet objects.

=head2 Object

See Row.

=head2 join

=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<DBIx::Class::Manual::FAQ|the FAQ>.

=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).