← Back to branch summary

~launchpad-pqm/launchpad/devel

« back to all changes in this revision

Viewing changes to lib/canonical/launchpad/database/README.txt

  • Committer: William Grant
  • Date: 2011-12-22 05:37:22 UTC
  • mto: This revision was merged to the branch mainline in revision 14581.
  • Revision ID: william.grant@canonical.com-20111222053722-gm6h9zi3lioz00ky
Move librarian stuff from canonical.launchpad to lp.services.librarian. canonical.librarian remains untouched.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/canonical/launchpad/database/README.txt
1
 
Notes on using SQLObject
2
 
========================
3
 
 
4
 
SQLOS
5
 
-----
6
 
 
7
 
We inherit from sqlos.SQLOS rather than sqlobject.SQLObject, to get the Zope 3
8
 
glue that sqlos provides, e.g. per-thread connections.
9
 
 
10
 
Dealing with naming
11
 
-------------------
12
 
 
13
 
SQLObject's default naming "style" for translating Python names (such as
14
 
class and attribute names) to SQL names (such as table and column names) doesn't
15
 
match our SQL's naming scheme.  As a result, we can't simply say::
16
 
 
17
 
    class SourcePackageRelease(SQLOS):
18
 
        """A source package release."""
19
 
 
20
 
        version = StringCol()
21
 
 
22
 
Instead, we need to say::
23
 
 
24
 
    class SourcePackageRelease(SQLOS):
25
 
        """A source package release."""
26
 
 
27
 
        _table = 'SourcePackageRelease'
28
 
        name =  StringCol()
29
 
 
30
 
TODO: This should be fixable by defining our own style (see the sqlobject.styles
31
 
module).
32
 
 
33
 
Foreign Keys and Joins
34
 
----------------------
35
 
 
36
 
SQLObject also tries to guess names for foreign keys, but doesn't provide anyway
37
 
to hook that with its styles mechanism, so again we need to explicitly tell
38
 
SQLObject the names to use.  See this example::
39
 
 
40
 
    class Branch(SQLOS):
41
 
        """A specific branch in Arch (archive/category--branch--version)"""
42
 
 
43
 
        implements(IBranch)
44
 
 
45
 
        _table = 'branch'
46
 
        _idName = 'branch'
47
 
        description = StringCol(dbName='description')
48
 
        changesets = MultipleJoin('Changeset', joinColumn='branch')
49
 
 
50
 
 
51
 
    class Changeset(SQLOS):
52
 
        """A changeset"""
53
 
 
54
 
        implements(IChangeset)
55
 
 
56
 
        _table = 'changeset'
57
 
        _idName = 'changeset'
58
 
        branch = ForeignKey(foreignKey='Branch', dbName='branch',
59
 
                            notNull=True)
60
 
        message = StringCol(dbName='logmessage', notNull=True)
61
 
 
62
 
Note the passing of `name`, `foreignKey` and `dbName` to the ForeignKey column.
63
 
 
64
 
This example also demonstrates the MultipleJoin feature of SQLObject, which is
65
 
used for one-to-many relationships.  e.g.::
66
 
 
67
 
    Grab a random branch out of the DB
68
 
    >>> branch = Branch.select()[0]
69
 
 
70
 
    Grab that branch's changesets
71
 
    >>> changesets = branch.changesets
72
 
 
73
 
    A changeset's branch attribute gives us the original branch
74
 
    >>> changesets[0].branch is branch
75
 
    True
76
 
 
77
 
The string you pass to MultipleJoin is the name of another SQLOS subclass, as is
78
 
string passed as the `foreignKey` argument to ForeignKey (strings are used so
79
 
that you can reference a class that hasn't been declared yet).  We also need to
80
 
specify the `joinColumn` (SQLObject guesses the wrong name for it, like
81
 
everything else).
82