~free.ekanayaka/storm/any-expr : revision 324

1

Storm is an Object Relational Mapper for Python developed at

2

Canonical. API docs, a manual, and a tutorial are available from:

1

Storm is an Object Relational Mapper for Python.

3

2

3

API docs, a manual, and a tutorial are available from

4

http://storm.canonical.com/

5

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

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.

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