Project

General

Profile

Model » History » Version 5

Elmer de Looff, 2011-09-20 18:43

1 1 Elmer de Looff
h1. Database abstraction model
2 1 Elmer de Looff
3 1 Elmer de Looff
h2. Goal of this component
4 1 Elmer de Looff
5 1 Elmer de Looff
The µWeb framework provides a @model@ module with the intention of simplifying database access. The design goal is to provide a rich abstraction that
6 1 Elmer de Looff
* takes away the tedious work of retrieving, creating and deleting records
7 1 Elmer de Looff
* can load its parent objects automatically if so required
8 1 Elmer de Looff
* _does *not* get in the way of the developer_
9 1 Elmer de Looff
10 1 Elmer de Looff
Making database interaction easier without restricting the abilities of the developer is our main goal. Some default mechanisms make assumptions on the way the database is organised, but these are well-documented, and it's entirely possible to change the behavior of these mechanisms.
11 1 Elmer de Looff
12 2 Elmer de Looff
h2. Using the Record
13 1 Elmer de Looff
14 2 Elmer de Looff
The basic idea of the @Record@ class is that it is a container for your database records, with related records automatically loaded as needed, and custom methods that provide more info, child objects, etc. Outlined below are the default features available, with minimal configuration requirements.
15 1 Elmer de Looff
16 2 Elmer de Looff
h3. Basic Record usage
17 1 Elmer de Looff
18 2 Elmer de Looff
There are a few ways to use the @Record@ class. The direct way to create a @Record@ is to initiate it with a connection, and a dictionary of @field -> value@ information. The @Record@ is a dictionary subclass that largely copies all the functionality of a dictionary. Retrieving values for keys works exactly as you'd expect.
19 1 Elmer de Looff
20 2 Elmer de Looff
h3. Creating your own @Record@
21 1 Elmer de Looff
22 2 Elmer de Looff
To create your own @Record@ subclass, nothing is required beyond the class name. The following example substitutes a complete working example:
23 2 Elmer de Looff
<pre><code class="python">
24 2 Elmer de Looff
from underdark.uweb import model
25 2 Elmer de Looff
class Message(model.Record):
26 2 Elmer de Looff
  """Abstraction class for messages stored in the database."""
27 2 Elmer de Looff
</code></pre>
28 1 Elmer de Looff
29 2 Elmer de Looff
h3. Primary field definition
30 1 Elmer de Looff
31 2 Elmer de Looff
The @Record@ requires that a table has a single-field unique column. It's advisable for this to be a PRIMARY index in the database, though this is not required. This field is used to automatically look up a record if it is referenced and requested elsewhere.
32 1 Elmer de Looff
33 2 Elmer de Looff
By default, this primary key field is assumed to be @ID@. If this is not the case for your table, you can easily change this by defining the @_PRIMARY_KEY@ class constant:
34 1 Elmer de Looff
35 2 Elmer de Looff
<pre><code class="python">
36 2 Elmer de Looff
from underdark.uweb import model
37 2 Elmer de Looff
class Country(model.Record):
38 2 Elmer de Looff
  """Abstraction class for a country table.
39 1 Elmer de Looff
40 2 Elmer de Looff
  This class uses the ISO-3166-1 alpha2 country code as primary key.
41 2 Elmer de Looff
  """
42 2 Elmer de Looff
  _PRIMARY_KEY = 'alpha2'
43 2 Elmer de Looff
</code></pre>
44 1 Elmer de Looff
45 2 Elmer de Looff
h3. Class and table relation
46 2 Elmer de Looff
47 2 Elmer de Looff
By default, the assumption is made that the table name is the same as the class name, with the first letter lowercase. *The table related to the class @Message@ would be @message@.* To change this behavior, assign the correct table name to the @_TABLE@ class constant. This new table name will then be used in all built-in Record methods:
48 2 Elmer de Looff
49 2 Elmer de Looff
<pre><code class="python">
50 2 Elmer de Looff
from underdark.uweb import model
51 2 Elmer de Looff
class Message(model.Record):
52 2 Elmer de Looff
  """Abstraction class for messages stored in the database."""
53 2 Elmer de Looff
  _TABLE = 'MyMessage'
54 2 Elmer de Looff
</code></pre>
55 2 Elmer de Looff
56 2 Elmer de Looff
h3. Alternative initializers
57 2 Elmer de Looff
58 2 Elmer de Looff
59 2 Elmer de Looff
60 2 Elmer de Looff
61 2 Elmer de Looff
62 2 Elmer de Looff
*N.B.* In the default implementation, fields that refer to a record in another table (@n to 1@ or @1 to 1@ relationships) *MUST have the name of that table.*
63 2 Elmer de Looff
For example: Given two tables `child` and `parent`. Entries in `child` that refer to their parent, must do so using a field called `parent` (not parentID or some such). If the table names are plural, the fields that refer to the relation should also have a pluralized name.