Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 525 lines (404 sloc) 19.05 kb
cd6c915 Simple prefetching works.
zef authored
1 persistence.js
2 ==============
4537c59 @zefhemel Rewrite and fixes to the README
zefhemel authored
3 `persistence.js` is a asynchronous Javascript object-relational
4 mapper library. It can be used both in the web browser and on
5 the server using [node.js](http://nodejs.org). It currently
6 supports 4 types of data stores:
7
8 * [HTML5 WebSQL database](http://dev.w3.org/html5/webdatabase/), a
9 somewhat controversial part of HTML5 that is supported in Webkit
10 browsers, specifically on mobile devices, including iPhone, Android
11 and Palm's WebOS.
12 * [Google Gears](http://gears.google.com), a browser plug-in that adds
13 a number of feature to the browser, including a in-browser database.
14 * [MySQL](http://www.mysql.com), using the
15 [node-mysql](http://github.com/stevebest/node-mysql), node.js module
16 on the server.
17 * In-memory, as a fallback. Keeps the database in memory and is cleaned
18 upon a page refresh (or server restart).
19
20 There is also an experimental support for [Qt 4.7 Declarative UI
21 framework
22 (QML)](http://doc.trolltech.org/4.7-snapshot/declarativeui.html) which
23 is an extension to JavaScript.
1b2c013 @zefhemel Documentation tweaks to accomodate for server environments.
zefhemel authored
24
25 For browser use, `persistence.js` has no dependencies on any other
26 frameworks, other than the Google Gears [initialization
27 script](http://code.google.com/apis/gears/gears_init.js), in case you
28 want to enable Gears support.
cd6c915 Simple prefetching works.
zef authored
29
4537c59 @zefhemel Rewrite and fixes to the README
zefhemel authored
30 A Brief Intro to Async Programming
31 ----------------------------------
bf2edb5 More info on asynchronous programming
Zef Hemel authored
32
127d79b Rewrote parts of readme. Added documentation for supported property
Zef Hemel authored
33 In browsers, Javascript and the web page's rendering engine share
34 a single thread. The result of this is that only one thing can happen
35 at a time. If a database query would be performed _synchronously_,
36 like in many other programming environments like Java and PHP the
37 browser would freeze from the moment the query was issued until the
38 results came back. Therefore, many APIs in Javascript are defined as
39 _asynchronous_ APIs, which mean that they do not block when an
40 "expensive" computation is performed, but instead provide the call
41 with a function that will be invoked once the result is known. In the
42 meantime, the browser can perform other duties.
bf2edb5 More info on asynchronous programming
Zef Hemel authored
43
44 For instance, a synchronous database call call would look as follows:
45
46 var results = db.query("SELECT * FROM Table");
47 for(...) { ... }
48
49 The execution of the first statement could take half a second, during
50 which the browser doesn't do anything else. By contrast, the
51 asynchronous version looks as follows:
52
53 db.query("SELECT * FROM Table", function(results) {
54 for(...) { ... }
55 });
56
57 Note that there will be a delay between the `db.query` call and the
58 result being available and that while the database is processing the
59 query, the execution of the Javascript continues. To make this clear,
60 consider the following program:
61
62 db.query("SELECT * FROM Table", function(results) {
63 console.log("hello");
64 });
65 console.log("world");
66
67 Although one could assume this would print "hello", followed by
68 "world", the result will likely be that "world" is printed before
127d79b Rewrote parts of readme. Added documentation for supported property
Zef Hemel authored
69 "hello", because "hello" is only printed when the results from the
bf2edb5 More info on asynchronous programming
Zef Hemel authored
70 query are available. This is a tricky thing about asynchronous
71 programming that a Javascript developer will have to get used to.
72
4537c59 @zefhemel Rewrite and fixes to the README
zefhemel authored
73 Using persistence.js in the browser
74 ===================================
75
14f8aac Working on the readme
Zef Hemel authored
76 Browser support
77 ---------------
78
79 * Modern webkit browsers (Google Chrome and Safari)
80 * Firefox (through Google Gears)
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
81 * Android browser (tested on 1.6 and 2.1)
82 * iPhone browser (iPhone OS 3+)
06e6304 Added WebOS to supported platforms.
Zef Hemel authored
83 * Palm WebOS (tested on 1.4.0)
cd6c915 Simple prefetching works.
zef authored
84
4537c59 @zefhemel Rewrite and fixes to the README
zefhemel authored
85 (The following is being worked on:)
14f8aac Working on the readme
Zef Hemel authored
86 Internet Explorer is likely not supported (untested) because it
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
87 lacks `__defineGetter__` and `__defineSetter__` support, which
88 `persistence.js` uses heavily. This may change in IE 8.
14f8aac Working on the readme
Zef Hemel authored
89
4537c59 @zefhemel Rewrite and fixes to the README
zefhemel authored
90 Setting up
91 ----------
92
93 To use `persistence.js` you need to clone the git repository:
94
95 git clone git://github.com/zefhemel/persistencejs.git
96
97 To use it you need to copy `persistence.js` to your web directory,
98 as well as any data stores you want to use. Note that the `mysql` and
99 `websql` stores both depend on the `sql` store. A typical setup
100 requires you to copy at least `persistence.js`,
101 `persistence.store.sql.js` and `persistence.store.websql.js` to your
102 web directory. You can then load them as follows:
103
104 <script src="persistence.js" type="application/javascript"></script>
105 <script src="persistence.store.sql.js" type="application/javascript"></script>
106 <script src="persistence.store.websql.js" type="application/javascript"></script>
107
14f8aac Working on the readme
Zef Hemel authored
108
4537c59 @zefhemel Rewrite and fixes to the README
zefhemel authored
109 Setup your database
110 -------------------
cd6c915 Simple prefetching works.
zef authored
111
4537c59 @zefhemel Rewrite and fixes to the README
zefhemel authored
112 You need to explicitly configure the data store you want to use,
113 configuration of the data store is store-specific. The WebSQL store
114 (which includes Google Gears support) is configured as follows:
115
116 persistence.store.websql.config(persistence, 'yourdbname', 'A database description', 5 * 1024 * 1024);
117
118 The first argument is always supposed to be `persistence`. The second
119 in your database name (it will create it if it does not already exist,
120 the third is a description for you database, the last argument is the
121 maximum size of your database in bytes (5MB in this example).
122
123 If you're using the in-memory store, you can configure it as follows:
124
125 persistence.store.memory.config(persistence);
14f8aac Working on the readme
Zef Hemel authored
126
127 Schema definition
128 -----------------
129
130 A data model is declared using `persistence.define`. The following two
131 definitions define a `Task` and `Category` entity with a few simple
127d79b Rewrote parts of readme. Added documentation for supported property
Zef Hemel authored
132 properties. The property types are based on [SQLite
4537c59 @zefhemel Rewrite and fixes to the README
zefhemel authored
133 types](http://www.sqlite.org/datatype3.html), specifically supported
134 types are (but any SQLite type is supported):
127d79b Rewrote parts of readme. Added documentation for supported property
Zef Hemel authored
135
136 * `TEXT`: for textual data
137 * `INT`: for numeric values
138 * `BOOL`: for boolean values (`true` or `false`)
c65213f Added Fabio's Date type to documentation.
Zef Hemel authored
139 * `DATE`: for date/time value (with precision of 1 second)
127d79b Rewrote parts of readme. Added documentation for supported property
Zef Hemel authored
140 * `JSON`: a special type that can be used to store arbitrary
141 [JSON](http://www.json.org) data. Note that this data can not be used
1e94adf Some more JSON property examples + minified version.
Zef Hemel authored
142 to filter or sort in any sensible way. If internal changes are made to a `JSON`
143 property, `persistence.js` may not register them. Therefore, a manual
144 call to `anObj.markDirty('jsonPropertyName')` is required before calling
145 `persistence.flush`.
127d79b Rewrote parts of readme. Added documentation for supported property
Zef Hemel authored
146
147 Example use:
cd6c915 Simple prefetching works.
zef authored
148
73724ff Added .add and .remove methods to QueryCollections.
zef authored
149 var Task = persistence.define('Task', {
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
150 name: "TEXT",
151 description: "TEXT",
152 done: "BOOL"
cd6c915 Simple prefetching works.
zef authored
153 });
154
73724ff Added .add and .remove methods to QueryCollections.
zef authored
155 var Category = persistence.define('Category', {
1e94adf Some more JSON property examples + minified version.
Zef Hemel authored
156 name: "TEXT",
157 metaData: "JSON"
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
158 });
159
160 var Tag = persistence.define('Task', {
161 name: "TEXT"
cd6c915 Simple prefetching works.
zef authored
162 });
163
14f8aac Working on the readme
Zef Hemel authored
164 The returned values are constructor functions and can be used to
165 create new instances of these entities later:
cd6c915 Simple prefetching works.
zef authored
166
167
14f8aac Working on the readme
Zef Hemel authored
168 Relationships between entities are defined using the constructor
169 function's `hasMany` call:
cd6c915 Simple prefetching works.
zef authored
170
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
171 // This defines a one-to-many relationship:
73724ff Added .add and .remove methods to QueryCollections.
zef authored
172 Category.hasMany('tasks', Task, 'category');
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
173 // These two definitions define a many-to-many relationship
174 Task.hasMany('tags', Tag, 'tasks');
175 Tag.hasMany('tasks', Task, 'tags');
cd6c915 Simple prefetching works.
zef authored
176
127d79b Rewrote parts of readme. Added documentation for supported property
Zef Hemel authored
177 The first statement defines a `tasks` relationship on category objects
178 containing a `QueryCollection` (see the section on query collections
179 later) of `Task`s, it also defines an inverse relationship on `Task`
180 objects with the name `category`. The last two statements define a
181 many-to-many relationships between `Task` and `Tag`. `Task` gets a
182 `tags` property (a `QueryCollection`) containing all its tags and vice
183 versa, `Tag` gets a `tasks` property containing all of its tasks.
cd6c915 Simple prefetching works.
zef authored
184
14f8aac Working on the readme
Zef Hemel authored
185 The defined entity definitions are synchronized (activated) with the
186 database using a `persistence.schemaSync` call, which takes a callback
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
187 function (with a newly created transaction as an argument), that is called
14f8aac Working on the readme
Zef Hemel authored
188 when the schema synchronization has completed, the callback is
189 optional.
cd6c915 Simple prefetching works.
zef authored
190
191 persistence.schemaSync();
73724ff Added .add and .remove methods to QueryCollections.
zef authored
192 // or
14f8aac Working on the readme
Zef Hemel authored
193 persistence.schemaSync(function(tx) {
194 // tx is the transaction object of the transaction that was
195 // automatically started
196 });
cd6c915 Simple prefetching works.
zef authored
197
eae6f59 @fgrehm Finishing up documentation
fgrehm authored
198 There is also a migrations plugin you can check out, documentation can be found
58183c9 @fgrehm Fixing link to migrations documentation
fgrehm authored
199 in [persistence.migrations.docs.md](migrations/persistence.migrations.docs.md) file.
eae6f59 @fgrehm Finishing up documentation
fgrehm authored
200
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
201 Creating and manipulating objects
202 ---------------------------------
203
204 New objects can be instantiated with the constructor functions.
205 Optionally, an object with initial property values can be passed as
206 well, or the properties may be set later:
207
208 var task = new Task();
209 var category = new Category({name: "My category"});
1e94adf Some more JSON property examples + minified version.
Zef Hemel authored
210 category.metaData = {rating: 5};
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
211 var tag = new Tag();
212 tag.name = "work";
213
214 Many-to-one relationships are accessed using their specified name, e.g.:
215 task.category = category;
216
217 One-to-many and many-to-many relationships are access and manipulated
218 through the `QueryCollection` API that will be discussed later:
219
220 task.tags.add(tag);
221 tasks.tags.remove(tag)l
222 tasks.tags.list(tx, function(allTags) { console.log(allTags); });
223
4941cd3 Added support for object removal (via `persistence.remove`).
Zef Hemel authored
224 Persisting/removing objects
e2d2c10 @zefhemel IMPORTANT: Minor breaking changes!
zefhemel authored
225 ---------------------------
cd6c915 Simple prefetching works.
zef authored
226
14f8aac Working on the readme
Zef Hemel authored
227 Similar to [hibernate](http://www.hibernate.org), `persistence.js`
228 uses a tracking mechanism to determine which objects' changes have to
229 be persisted to the datase. All objects retrieved from the database
230 are automatically tracked for changes. New entities can be tracked to
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
231 be persisted using the `persistence.add` function:
cd6c915 Simple prefetching works.
zef authored
232
c37c40d Formatted readme slightly
Zef Hemel authored
233 var c = new Category({name: "Main category"});
234 persistence.add(c);
235 for ( var i = 0; i < 5; i++) {
236 var t = new Task();
237 t.name = 'Task ' + i;
238 t.done = i % 2 == 0;
239 t.category = c;
240 persistence.add(t);
241 }
cd6c915 Simple prefetching works.
zef authored
242
4941cd3 Added support for object removal (via `persistence.remove`).
Zef Hemel authored
243 Objects can also be removed from the database:
244
245 persistence.remove(c);
246
14f8aac Working on the readme
Zef Hemel authored
247 All changes made to tracked objects can be flushed to the database by
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
248 using `persistence.flush`, which takes a transaction object and
249 callback function as arguments. A new transaction can be started using
e38fbe0 Got rid of redundancy in readme.
Zef Hemel authored
250 `persistence.transaction`:
cd6c915 Simple prefetching works.
zef authored
251
252 persistence.transaction(function(tx) {
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
253 persistence.flush(tx, function() {
254 alert('Done flushing!');
255 });
256 });
14f8aac Working on the readme
Zef Hemel authored
257
127d79b Rewrote parts of readme. Added documentation for supported property
Zef Hemel authored
258 For convenience, it is also possible to not specify a transaction or
259 callback, in that case a new transaction will be started
260 automatically. For instance:
14f8aac Working on the readme
Zef Hemel authored
261
262 persistence.flush();
263 // or, with callback
e2d2c10 @zefhemel IMPORTANT: Minor breaking changes!
zefhemel authored
264 persistence.flush(function() {
14f8aac Working on the readme
Zef Hemel authored
265 alert('Done flushing');
266 });
267
127d79b Rewrote parts of readme. Added documentation for supported property
Zef Hemel authored
268 Note that when no callback is defined, the flushing still happens
269 asynchronously.
14f8aac Working on the readme
Zef Hemel authored
270
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
271 __Important__: Changes and new objects will not be persisted until you
272 explicitly call `persistence.flush()`. The exception to this rule is
e38fbe0 Got rid of redundancy in readme.
Zef Hemel authored
273 using the `list(...)` method on a database `QueryCollection`, which also
274 flushes first, although this behavior may change in the future.
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
275
d61084e persistence.sync.js now keeps track of changes to all entities in
Zef Hemel authored
276 Dumping and restoring data
ef3606a A simple database dump function. Restore will come soon.
Zef Hemel authored
277 --------------------------------
278
279 `persistence.dump` can be used to create an object containing a full
280 dump of a database. Naturally, it is adviced to only do this with
281 smaller databases. Example:
282
283 persistence.dump(tx, [Task, Category], function(dump) {
284 console.log(dump);
285 });
286
e2d2c10 @zefhemel IMPORTANT: Minor breaking changes!
zefhemel authored
287 The `tx` is left out, a new transaction will be started for the
288 operation. If the second argument is left out, `dump` defaults
289 to dumping _all_ defined entities.
ef3606a A simple database dump function. Restore will come soon.
Zef Hemel authored
290
291 The dump format is:
292
293 {"entity-name": [list of instances],
294 ...}
295
127d79b Rewrote parts of readme. Added documentation for supported property
Zef Hemel authored
296 `persistence.load` is used to restore the dump produced by
297 `persistence.dump`. Usage:
298
299 persistence.load(tx, dumpObj, function() {
300 alert('Dump restored!');
301 });
302
e2d2c10 @zefhemel IMPORTANT: Minor breaking changes!
zefhemel authored
303 The `tx` argument can be left out to automatically start a new
127d79b Rewrote parts of readme. Added documentation for supported property
Zef Hemel authored
304 transaction. Note that `persistence.load` does not empty the database
305 first, it simply attempts to add all objects to the database. If
306 objects with, e.g. the same ID already exist, this will fail.
ef3606a A simple database dump function. Restore will come soon.
Zef Hemel authored
307
d61084e persistence.sync.js now keeps track of changes to all entities in
Zef Hemel authored
308 Similarly, `persistence.loadFromJson` and `persistence.dumpToJson`
309 respectively load and dump all the database's data as JSON strings.
310
e2d2c10 @zefhemel IMPORTANT: Minor breaking changes!
zefhemel authored
311 Entity constructor functions
312 ----------------------------
313
314 The constructor function returned by a `persistence.define` call
315 cannot only be used to instantiate new objects, it also has some
316 useful methods of its own:
317
318 * `EntityName.all([session])` returns a query collection containing
319 all
320 persisted instances of that object. The `session` argument is
321 optional and only required when `persistence.js` is used in
322 multi-session mode.
323 * `EntityName.load([session], [tx], id, callback)` loads an particular
324 object from the database by id or returns `null` if it has not been
325 found.
326 * `EntityName.findBy([session], [tx], property, value, callback)` searches
327 for a particular object based on a property value (this is assumed to
328 be unique), the callback function is called with the found object or
329 `null` if it has not been found.
330
331 And of course the methods to define relationships to other entities:
332
333 * `EntityName.hasMany(property, Entity, inverseProperty)` defines a
334 1:N or N:M relationship (depending on the inverse property)
335 * `EntityName.hasOne(property, Entity)` defines a 1:1 or N:1
336 relationship
337
14f8aac Working on the readme
Zef Hemel authored
338 Query collections
339 -----------------
340
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
341 A core concept of `persistence.js` is the `QueryCollection`. A
14f8aac Working on the readme
Zef Hemel authored
342 `QueryCollection` represents a (sometimes) virtual collection that can
127d79b Rewrote parts of readme. Added documentation for supported property
Zef Hemel authored
343 be filtered, ordered or paginated. `QueryCollection`s are somewhate
344 inspired by [Google AppEngine's Query
345 class](http://code.google.com/appengine/docs/python/datastore/queryclass.html).
14f8aac Working on the readme
Zef Hemel authored
346 A `QueryCollection` has the following methods:
347
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
348 * `filter(property, operator, value)`
033f67a Added .limit(n) and .skip(n) support.
Zef Hemel authored
349 Returns a new `QueryCollection` that adds a filter, filtering a
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
350 certain property based on an operator and value. Supported operators
80824fe @zefhemel Introduced bug fixes, and new 'not in' operator.
zefhemel authored
351 are '=', '!=', '<', '<=', '>', '>=', 'in' and 'not in'. Example:
352 `.filter('done', '=', true)`
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
353 * `order(property, ascending)`
033f67a Added .limit(n) and .skip(n) support.
Zef Hemel authored
354 Returns a new `QueryCollection` that will order its results by the
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
355 property specified in either an ascending (ascending === true) or
356 descending (ascending === false) order.
033f67a Added .limit(n) and .skip(n) support.
Zef Hemel authored
357 * `limit(n)`
358 Returns a new `QueryCollection` that limits the size of the result
359 set to `n` items. Useful for pagination.
360 * `skip(n)`
361 Returns a new `QueryCollection` that skips the first `n` results.
362 Useful for pagination.
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
363 * `prefetch(rel)`
033f67a Added .limit(n) and .skip(n) support.
Zef Hemel authored
364 Returns a new `QueryCollection` that prefetches entities linked
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
365 through relationship `rel`, note that this only works for one-to-one
366 and many-to-one relationships.
a9fa189 @zefhemel Added `count` call to query collections. Fixed a little bug in
zefhemel authored
367 * `add(obj)`
368 Adds object `obj` to the collection.
369 * `remove(obj)`
370 Removes object `obj` from the collection.
e2d2c10 @zefhemel IMPORTANT: Minor breaking changes!
zefhemel authored
371 * `list([tx], callback)`
033f67a Added .limit(n) and .skip(n) support.
Zef Hemel authored
372 Asynchronously fetches the results matching the formulated query.
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
373 Once retrieved, the callback function is invoked with an array of
374 entity objects as argument.
e2d2c10 @zefhemel IMPORTANT: Minor breaking changes!
zefhemel authored
375 * `each([tx], eachCallback)`
9520607 Basic implementation of LocalQueryCollection, only supports filtering
Zef Hemel authored
376 Asynchronously fetches the results matching the formulated query.
377 Once retrieved, the `eachCallback` function is invoked on each
378 element of the result objects.
e2d2c10 @zefhemel IMPORTANT: Minor breaking changes!
zefhemel authored
379 * `forEach([tx], eachCallback)`
380 Alias for `each`
381 * `one([tx], callback)`
a2c07b5 @zefhemel Added `destroyAll` method to DbQueryCollections to remove all the items
zefhemel authored
382 Asynchronously fetches the first element of the collection, or `null` if none.
e2d2c10 @zefhemel IMPORTANT: Minor breaking changes!
zefhemel authored
383 * `destroyAll([tx], callback)`
a2c07b5 @zefhemel Added `destroyAll` method to DbQueryCollections to remove all the items
zefhemel authored
384 Asynchronously removes all the items in the collection. __Important__: this does
385 not only remove the items from the collection, but removes the items themselves!
e2d2c10 @zefhemel IMPORTANT: Minor breaking changes!
zefhemel authored
386 * `count([tx], callback)`
a9fa189 @zefhemel Added `count` call to query collections. Fixed a little bug in
zefhemel authored
387 Asynchronously counts the number of items in the collection. The arguments passed
388 to the `callback` function is the number of items.
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
389
390 Query collections are returned by:
391
392 * `EntityName.all()`, e.g. `Task.all()`
393 * one-to-many and many-to-many relationships, e.g. `task.tags`
394
395 Example:
cd6c915 Simple prefetching works.
zef authored
396
033f67a Added .limit(n) and .skip(n) support.
Zef Hemel authored
397 var allTasks = Task.all().filter("done", '=', true).prefetch("category").order("name", false).limit(10);
cd6c915 Simple prefetching works.
zef authored
398
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
399 allTasks.list(null, function (results) {
400 results.forEach(function (r) {
401 console.log(r.name)
402 window.task = r;
cd6c915 Simple prefetching works.
zef authored
403 });
404 });
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
405
4537c59 @zefhemel Rewrite and fixes to the README
zefhemel authored
406 Using persistence.js on the server
407 ==================================
408
409 Sadly the node.js server environment requires slight changes to
410 `persistence.js` to make it work with multiple database connections:
411
412 * A `Session` object needs to be passed as an extra argument to
413 certain method calls, typically as a first argument.
414 * Methods previously called on the `persistence` object itself are now
415 called on the `Session` object.
416
417 An example `node.js` application is included in `test/node-blog.js`.
418
419 Setup
420 -----
421 You need to `require` two modules, the `persistence.js` library itself
422 and the MySQL backend module. Also make sure the MySQL library
423 is located (or symlinked) from the current directory:
424
425 var persistence = require('./persistence').persistence;
426 var persistenceStore = require('./persistence.store.mysql');
427
428 Then, you configure the database settings to use:
429
430 persistenceStore.config(persistence, 'localhost', 'dbname', 'username', 'password');
431
432 Subsequently, for every connection you handle (assuming you're
433 building a sever), you call the `persistenceStore.getSession()`
434 method:
435
436 var session = persistenceBackend.getSession();
437
438 This session is what you pass around, typically together with a
439 transaction object. Note that currently you can only have one
440 transaction open per session and transactions cannot be nested.
441
442 session.transaction(function(tx) {
443 ...
444 });
445
446 Defining your data model
447 ------------------------
448
449 Defining your data model is done in exactly the same way as regular `persistence.js`:
450
451 var Task = persistence.define('Task', {
452 name: "TEXT",
453 description: "TEXT",
454 done: "BOOL"
455 });
456
457 A `schemaSync` is typically performed as follows:
458
459 session.schemaSync(tx, function() {
460 ...
461 });
462
463 Creating and manipulating objects
464 ---------------------------------
465
466 Creating and manipulating objects is done much the same way as with
467 regular `persistence.js`, except that in the entity's constructor you
468 need to reference the `Session` again:
469
470 var t = new Task(session);
471 ...
472 session.add(t);
473
474 session.flush(tx, function() {
475 ...
476 });
477
478 Query collections
b07a858 Moved issues to the issue tracker.
Zef Hemel authored
479 -----------------
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
480
4537c59 @zefhemel Rewrite and fixes to the README
zefhemel authored
481 Query collections work the same way as in regular `persistence.js`
482 with the exception of the `Entity.all()` method that now also requires
483 a `Session` to be passed to it:
484
485 Task.all(session).filter('done', '=', true).list(tx, function(tasks) {
486 ...
487 });
488
489 Closing the session
490 -------------------
491
492 After usage, you need to close your session:
493
494 session.close();
495
496 Bugs and Contributions
497 ======================
498
127d79b Rewrote parts of readme. Added documentation for supported property
Zef Hemel authored
499 If you find a bug, please [report it](http://yellowgrass.org/project/persistence.js).
c65213f Added Fabio's Date type to documentation.
Zef Hemel authored
500 or fork the project, fix the problem and send me a pull request. For
b07a858 Moved issues to the issue tracker.
Zef Hemel authored
501 a list of planned features and open issues, have a look at the [issue
b5cd840 Changed location of issue tracker.
Zef Hemel authored
502 tracker](http://yellowgrass.org/project/persistence.js).
033f67a Added .limit(n) and .skip(n) support.
Zef Hemel authored
503
0302c86 Added link to Google Group
Zef Hemel authored
504 For support and discussion, please join the [persistence.js Google
505 Group](http://groups.google.com/group/persistencejs).
506
0e32d43 @zefhemel Added AUTHORS file
zefhemel authored
507 Thanks goes to the people listed in `AUTHORS` for their contributions.
c65213f Added Fabio's Date type to documentation.
Zef Hemel authored
508
cda1de2 @zefhemel Added link to the persistence.js GWT wrapper.
zefhemel authored
509 If you use [GWT](http://code.google.com/webtoolkit/) (the Google Web
510 Toolkit), be sure to have a look at [Dennis Z. Jiang's GWT persistence.js
511 wrapper](http://github.com/dennisjzh/gwt-persistence).
512
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
513 License
4537c59 @zefhemel Rewrite and fixes to the README
zefhemel authored
514 =======
90ea29b Extended README + license. Preparing for initial release.
Zef Hemel authored
515
516 This work is licensed under the [MIT license](http://en.wikipedia.org/wiki/MIT_License).
cb16171 Added flattr link
Zef Hemel authored
517
518 Support this work
4537c59 @zefhemel Rewrite and fixes to the README
zefhemel authored
519 =================
cb16171 Added flattr link
Zef Hemel authored
520
521 You can support this project by flattering it:
522
523 <a href="http://flattr.com/thing/2510/persistence-js" target="_blank">
524 <img src="http://api.flattr.com/button/button-static-50x60.png" title="Flattr this" border="0" /></a>
Something went wrong with that request. Please try again.