~lifeless/storm/bug-620615

« back to all changes in this revision

Viewing changes to README

  • Committer: Jamu Kakar
  • Date: 2009-10-08 07:23:43 UTC
  • Revision ID: jkakar@kakar.ca-20091008072343-221jle214fop77z8
- The README file now includes information about Storm's license,
  design characteristics and features, and instructions for setting
  up a development environment.  Thanks to Gabriel Grant for helping
  write and test the setup notes [trivial].

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
Storm is an Object Relational Mapper for Python.
 
1
Storm is an Object Relational Mapper for Python developed at
 
2
Canonical.  API docs, a manual, and a tutorial are available from:
2
3
 
3
 
API docs, a manual, and a tutorial are available from
4
4
http://storm.canonical.com/
5
5
 
6
 
To run the tests, execute "./test" in the toplevel directory.  You
7
 
will need to set the environment variables STORM_MYSQL_URI and
8
 
STORM_POSTGRES_URI in order to run the full suite, including
9
 
backend-specific tests. For example::
10
 
 
11
 
  $ export STORM_MYSQL_URI=mysql:storm_tests
12
 
  $ export STORM_POSTGRES_URI=postgres:storm_tests
13
 
  $ ./test
14
 
  Running unittests...
15
 
 
 
6
 
 
7
Introduction
 
8
============
 
9
 
 
10
The project was in development for more than a year for use in
 
11
Canonical projects such as Launchpad and Landscape before being
 
12
released as free software on July 9th, 2007.
 
13
 
 
14
Design:
 
15
 
 
16
 * Clean and lightweight API offers a short learning curve and
 
17
   long-term maintainability.
 
18
 * Storm is developed in a test-driven manner. An untested line of
 
19
   code is considered a bug.
 
20
 * Storm needs no special class constructors, nor imperative base
 
21
   classes.
 
22
 * Storm is well designed (different classes have very clear
 
23
   boundaries, with small and clean public APIs).
 
24
 * Designed from day one to work both with thin relational
 
25
   databases, such as SQLite, and big iron systems like PostgreSQL
 
26
   and MySQL.
 
27
 * Storm is easy to debug, since its code is written with a KISS
 
28
   principle, and thus is easy to understand.
 
29
 * Designed from day one to work both at the low end, with trivial
 
30
   small databases, and the high end, with applications accessing
 
31
   billion row tables and committing to multiple database backends.
 
32
 * It's very easy to write and support backends for Storm (current
 
33
   backends have around 100 lines of code).
 
34
 
 
35
Features:
 
36
 
 
37
 * Storm is fast.
 
38
 * Storm lets you efficiently access and update large datasets by
 
39
   allowing you to formulate complex queries spanning multiple
 
40
   tables using Python.
 
41
 * Storm allows you to fallback to SQL if needed (or if you just
 
42
   prefer), allowing you to mix "old school" code and ORM code
 
43
 * Storm handles composed primary keys with ease (no need for
 
44
   surrogate keys).
 
45
 * Storm doesn't do schema management, and as a result you're free
 
46
   to manage the schema as wanted, and creating classes that work
 
47
   with Storm is clean and simple.
 
48
 * Storm works very well connecting to several databases and using
 
49
   the same Python types (or different ones) with all of them.
 
50
 * Storm can handle obj.attr = <A SQL expression> assignments, when
 
51
   that's really needed (the expression is executed at INSERT/UPDATE
 
52
   time).
 
53
 * Storm handles relationships between objects even before they were
 
54
   added to a database.
 
55
 * Storm works well with existing database schemas.
 
56
 * Storm will flush changes to the database automatically when
 
57
   needed, so that queries made affect recently modified objects.
 
58
 
 
59
 
 
60
License
 
61
=======
 
62
 
 
63
Copyright (C) 2006-2009 Canonical, Ltd.  All contributions must have
 
64
copyright assigned to Canonical.
 
65
 
 
66
This library is free software; you can redistribute it and/or
 
67
modify it under the terms of the GNU Lesser General Public
 
68
License as published by the Free Software Foundation; either
 
69
version 2.1 of the License, or (at your option) any later version.
 
70
 
 
71
This library is distributed in the hope that it will be useful,
 
72
but WITHOUT ANY WARRANTY; without even the implied warranty of
 
73
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 
74
Lesser General Public License for more details.
 
75
 
 
76
You should have received a copy of the GNU Lesser General Public
 
77
License along with this library; if not, write to the Free Software
 
78
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 
79
02110-1301 USA
 
80
 
 
81
On Ubuntu systems, the complete text of the GNU Lesser General
 
82
Public Version 2.1 License is in /usr/share/common-licenses/LGPL-2.1
 
83
 
 
84
 
 
85
Developing Storm
 
86
================
 
87
 
 
88
The following instructions describe the procedure for setting up a
 
89
development environment and running the test suite.
 
90
 
 
91
Installing dependencies
 
92
-----------------------
 
93
 
 
94
The following instructions assume that you're using Ubuntu.  The
 
95
same procedure will probably work without changes on a Debian system
 
96
and with minimal changes on a non-Debian-based linux distribution.
 
97
In order to run the test suite, and exercise all supported backends,
 
98
you will need to install MySQL and PostgreSQL, along with the
 
99
related Python database drivers:
 
100
 
 
101
 $ sudo apt-get install python-mysqldb python-psycopg2 mysql-server \
 
102
                        postgresql build-essential
 
103
 
 
104
These will take a few minutes to download (its a bit under 200MB all
 
105
together).  Once the download is complete, a screen called
 
106
"configuring mysql-server-5.0" will be shown.  When asked for a
 
107
password for the root user leave the field blank and hit enter to
 
108
continue.  This is not a recommended setting for a production
 
109
server, but makes life easier on a development machine.  You may be
 
110
asked to enter a password multiple times.  Leave it blank in each
 
111
case.
 
112
 
 
113
Setting up database users and access security
 
114
---------------------------------------------
 
115
 
 
116
PostgreSQL needs to be setup to allow TCP/IP connections from
 
117
localhost.  Edit /etc/postgresql/8.3/main/pg_hba.conf and make sure
 
118
the following line is present:
 
119
 
 
120
 host all all 127.0.0.1/32 trust
 
121
 
 
122
This will probably (with PostgresSQL 8.4) entail changing 'md5' to
 
123
'trust'.  Save and close, then restart the server:
 
124
 
 
125
 $ sudo /etc/init.d/postgresql-8.4 restart
 
126
 
 
127
Next, you probably noticed that, while MySQL asked us about a root
 
128
user several times, PostgreSQL didn't ask us at all.  Lets create
 
129
our PostgreSQL user now.  As noted in the Ubuntu PostgreSQL
 
130
documentation, the easiest thing is to create a user with the same
 
131
name as your username.  Run the following command to create a user
 
132
for yourself (if prompted for a password, leave it blank):
 
133
 
 
134
 $ sudo -u postgres createuser --superuser $USER
 
135
 
 
136
Despite having created our root user already, MySQL requires an
 
137
extra step. First we start mysql as the root user (which, you may
 
138
recall, has no password) with:
 
139
 
 
140
 $ mysql -u root
 
141
 
 
142
Then we create a new user. Be sure to replace YOUR_USERNAME with
 
143
your actual user name (leaving the quotes in place).
 
144
 
 
145
mysql> GRANT ALL PRIVILEGES ON *.* TO 'YOUR_USERNAME'@'localhost'
 
146
IDENTIFIED BY '' WITH GRANT OPTION;
 
147
 
 
148
Creating test databases
 
149
-----------------------
 
150
 
 
151
The test suite needs some local databases in place to exercise MySQL
 
152
and PostgreSQL functionality.  While still at the MySQL command
 
153
prompt run:
 
154
 
 
155
mysql> CREATE DATABASE storm_test CHARACTER SET utf8;
 
156
 
 
157
Use Ctrl+D to exit, then, once back on the standard terminal, run
 
158
the command for PostgreSQL:
 
159
 
 
160
 $ createdb storm_test
 
161
 
 
162
Running the tests
 
163
-----------------
 
164
 
 
165
Finally, its time to run the tests!  Go into the base directory of
 
166
the storm branch you want to test, and run:
 
167
 
 
168
 $ make check
 
169
 
 
170
They'll take a while to run.  All tests should pass: failures mean
 
171
there's a problem with your environment or a bug in Storm.