← Back to branch summary

~azzar1/unity/add-show-desktop-key

« back to all changes in this revision

Viewing changes to doc/dev/faq.rst

  • Committer: Matt Giuca
  • Date: 2009-12-15 04:55:31 UTC
  • Revision ID: matt.giuca@gmail.com-20091215045531-4c7w11nc6avx97l7
dev/faq: Database access tips.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/dev/faq.rst
50
50
   variables than code running outside. It will be missing a lot of data, and
51
51
   will contain some user-specific data.
52
52
 
 
53
Database
 
54
--------
 
55
 
 
56
IVLE exclusively uses the `Storm`_ API for database access. Do not write any
 
57
SQL code yourself, or make use of low-level database libraries. The only
 
58
exception is in preparing the database schema, which is stored as an SQL file.
 
59
 
 
60
.. _Storm: https://storm.canonical.com/
 
61
 
 
62
... update the database schema?
 
63
-------------------------------
 
64
 
 
65
Modify :file:`userdb/users.sql`. Any changes also need to be made in to a
 
66
migrations file, in :file:`userdb/migrations/`.
 
67
 
 
68
TODO: More detail on migrations.
 
69
 
 
70
.. _ref-dev-faq-read-data:
 
71
 
 
72
... read data from the database?
 
73
--------------------------------
 
74
 
 
75
::
 
76
 
 
77
    import ivle.database
 
78
    # Typically, you import all database classes you want here
 
79
    from ivle.database import User
 
80
 
 
81
You need a `store` object to perform any interactions with the database. If
 
82
you are inside the web app, get a hold of the `req` (request) object, and use
 
83
``req.store``. In other code, create a new store as follows (where `config` is
 
84
a :ref:`config <ref-dev-faq-config>` object)::
 
85
 
 
86
    store = ivle.database.get_store(config)
 
87
 
 
88
You can read objects out of the database through the store. For example, to
 
89
get a User object::
 
90
 
 
91
    user = store.find(User, User.login==username).one()
 
92
 
 
93
(Note that ``store.find(User)`` just returns a sequence of all users.)
 
94
 
 
95
You can then treat `user` as a normal object, and read from its attributes.
 
96
All of the classes are defined in ``ivle/database.py``.
 
97
 
 
98
.. note::
 
99
   The code must be executed outside of the jail. Jail code runs under user
 
100
   privileges and cannot access the database.
 
101
 
 
102
.. note::
 
103
   For help with the database API, see the `Storm`_ documentation.
 
104
 
 
105
... write data to the database?
 
106
--------------------------------
 
107
 
 
108
Get an object out of the database, as :ref:`above <ref-dev-faq-read-data>`,
 
109
and simply write to the object's attributes. This updates the *in-memory* copy
 
110
of the data only.
 
111
 
 
112
To write the changes back to the database, simply use::
 
113
 
 
114
    store.commit()
 
115
 
 
116
using the same store object as used to retrieve the object in the first place.
 
117
 
 
118
... insert a new object into the database?
 
119
------------------------------------------
 
120
 
 
121
Create the new object using its constructor, as with any Python object. e.g.::
 
122
 
 
123
    import ivle.database
 
124
    user = ivle.database.User()
 
125
 
 
126
You can then set the attributes of the object as desired. As with writing,
 
127
this only creates an *in-memory* object.
 
128
 
 
129
To add the object to the database, get a :ref:`store <ref-dev-faq-read-data>`,
 
130
and use::
 
131
 
 
132
    store.add(user)
 
133
    store.commit()
 
134
 
53
135
Subversion
54
136
----------
55
137
 
104
186
==================
105
187
 
106
188
.. This is for finding obscure things in the code.
 
189
 
 
190
... the class definitions for database objects?
 
191
-----------------------------------------------
 
192
 
 
193
All of the classes are defined in ``ivle/database.py``.