|
1 | | -MySQL Cluster NoSQL API for Node.JS |
2 | | -=================================== |
| 1 | +MySQL-JS |
| 2 | +======== |
3 | 3 |
|
4 | 4 | INTRODUCTION |
5 | 5 | ------------ |
6 | | -The NoSQL API for Node.JS provides a lightweight domain object model for |
7 | | -JavaScript. You write code using common JavaScript objects, and use simple |
8 | | -API calls to read and write those objects to the database, like this: |
| 6 | +This package provides a fast, easy, and safe framework for building |
| 7 | +database applications in Node.js. It is organized around the concept |
| 8 | +of a database *session*, which allows standard JavaScript objects to be |
| 9 | +read from and written to a database. |
9 | 10 |
|
| 11 | +This example uses a session to store a single object into a MySQL table: |
10 | 12 | ``` |
11 | | - var nosql = require("mysql-js"); |
12 | | - |
13 | | - function onSession(err, session) { |
14 | | - var data = new Tweet(username, message); |
15 | | - session.persist(data); |
16 | | - } |
| 13 | +var nosql = require("mysql-js"); |
| 14 | +
|
| 15 | +var connectionProperties = { |
| 16 | + "implementation" : "mysql", |
| 17 | + "database" : "test", |
| 18 | + "mysql_host" : "localhost", |
| 19 | + "mysql_port" : 3306, |
| 20 | + "mysql_user" : "test", |
| 21 | + "mysql_password" : "", |
| 22 | +}; |
| 23 | +
|
| 24 | +nosql.openSession(connectionProperties).then( |
| 25 | + function(session) { |
| 26 | + var user = { id: 1, name: "Database Jones"}; |
| 27 | + return session.persist("user", user); |
| 28 | + } |
| 29 | +).then( |
| 30 | + function() { |
| 31 | + console.log("Complete"); |
| 32 | + nosql.closeAllOpenSessionFactories(); |
| 33 | + } |
| 34 | +); |
| 35 | +``` |
| 36 | + |
17 | 37 |
|
18 | | - nosql.openSession(onSession); |
| 38 | +QUICK INSTALL |
| 39 | +------------- |
| 40 | +MySQL-JS can be installed using NPM: |
| 41 | + |
| 42 | +``` |
| 43 | +npm install https://github.com/mysql/mysql-js/archive/2014-10-06.tar.gz |
19 | 44 | ``` |
20 | 45 |
|
21 | | -More sample code is available in the samples/ directory. |
22 | 46 |
|
23 | | - The API includes two backend adapters: |
| 47 | +SUPPORTED DATABASES AND CONNECTION PROPERTIES |
| 48 | +--------------------------------------------- |
| 49 | +MySQL-JS provides a common data management API over a variety of back-end |
| 50 | +database connections. Two database adapters are currently supported. |
| 51 | +The *mysql* adapter provides generic support for any MySQL database, |
| 52 | +based on all-JavaScript mysql connector node-mysql. |
| 53 | +The *ndb* adapter provides optimized high-performance access to MySQL Cluster |
| 54 | +using the NDB API. |
24 | 55 |
|
25 | | - - The "ndb" adapter, which uses the native NDB API to provide |
26 | | - high-performance native access to MySQL Cluster. |
| 56 | +Each backend adapter supports its own set of connection properties. |
| 57 | ++ [MySQL Connection Properties](Backend-documentation/mysql.md) |
| 58 | ++ [NDB Connection Properties](Backend-documentation/ndb.md) |
27 | 59 |
|
28 | | - - The "mysql" adapter, which connects to any MySQL Server using the node-mysql |
29 | | - driver, available from https://github.com/felixge/node-mysql/ |
30 | 60 |
|
| 61 | +SESSION |
| 62 | +------- |
| 63 | +The central concept of mysql-js is the *session* class. A session provides |
| 64 | +a context for database operations and transactions. Each independent user |
| 65 | +context should have a distinct session. For instance, in a web application, |
| 66 | +handling each HTTP request involves opening a session, using the session to |
| 67 | +access the database, and then closing the session. |
| 68 | + |
| 69 | + |
| 70 | +### Session methods |
| 71 | + |
| 72 | +Most methods on session() are available on several varieties: they may take |
| 73 | +either a mapped object or a literal table name; they may take a callback, or |
| 74 | +rely on the returned promise for continuation; and they may take any number |
| 75 | +of extra arguments after a callback. |
| 76 | + |
| 77 | +Each of the following methods is *asynchronous* and *returns a promise*: |
| 78 | ++ *find()* Find an instance in the database using a primary or unique key. |
| 79 | +++ find(Constructor, keys, [callback], [...]) |
| 80 | +++ find(Projection, keys, [callback], [...]) |
| 81 | +++ find(tableName, keys, [callback], [...]) |
| 82 | ++ *load(instance, [callback], [...])* Loads a specific instance from the database |
| 83 | +based on the primary or unique key present in the object. |
| 84 | ++ *persist()* Insert an instance into the database. |
| 85 | +++ persist(instance, [callback], [...]) |
| 86 | +++ persist(Constructor, values, [callback], [...]) |
| 87 | +++ persist(tableName, values, [callback], [...]) |
| 88 | ++ *remove()* Delete an instance by primary or unique key. |
| 89 | +++ remove(instance, [callback], [...]) |
| 90 | +++ remove(Constructor, keys, [callback], [...]) |
| 91 | +++ remove(tableName, keys, [callback], [...]) |
| 92 | ++ *update()* Update an instance by primary or unique key without necessarily retrieving it. |
| 93 | +++ update(instance, [callback], [...]) |
| 94 | +++ update(Constructor, keys, values, [callback], [...]) |
| 95 | +++ update(tableName, keys, values, [callback], [...]) |
| 96 | ++ *save()* Write an object to the database without checking for existence; could result in either an update or an insert. |
| 97 | +++ save(instance, [callback], [...]) |
| 98 | +++ save(Constructor, values, [callback], [...]) |
| 99 | +++ save(tableName, values, [callback], [...]) |
| 100 | ++ *createQuery()* Create an object that can be used to query the database |
| 101 | +++ createQuery(instance, [callback], [...]) |
| 102 | +++ createQuery(Constructor, [callback], [...]) |
| 103 | +++ createQuery(tableName, [callback], [...]) |
| 104 | ++ *getMapping()* Resolve and fetch mappings for a table or class |
| 105 | +++ getMapping(object, [callback], [...]) |
| 106 | +++ getMapping(Constructor, [callback], [...]) |
| 107 | +++ getMapping(tableName, [callback], [...]) |
| 108 | ++ *close([callback], [...])* Close the current session |
| 109 | + |
| 110 | +The following methods are *immediate*: |
| 111 | ++ createBatch(). Returns a batch. |
| 112 | ++ listBatches(). Returns an array of batches. |
| 113 | ++ isClosed(). Returns boolean. |
| 114 | ++ isBatch(). Returns boolean. |
| 115 | ++ currentTransaction(). Returns a Transaction. |
| 116 | + |
| 117 | +See the [Complete documentation for Session](API-documentaiton/Session) |
| 118 | + |
| 119 | + |
| 120 | +PROMISES |
| 121 | +-------- |
| 122 | +The majority of the asynchronous API methods in mysql-js return a |
| 123 | +<a href="promisesaplus.com">Promises/A+ compatible promise</a>. |
31 | 124 |
|
32 | | -REQUIREMENTS |
33 | | ------------- |
34 | | -Building the ndb backend requires an installed copy of MySQL Cluster 7.x |
35 | | -including headers and shared library files. The MySQL architecture must match |
36 | | -the node architecture: if node.js is 64-bit, then MySQL must also be 64-bit. If |
37 | | -node is 32-bit, MySQL must be 32-bit. |
38 | 125 |
|
39 | | -The mysql backend requires version 2.0 of node-mysql, an all-JavaScript |
40 | | -MySQL client. |
| 126 | +NOSQL |
| 127 | +----- |
41 | 128 |
|
42 | | -### WINDOWS REQURIREMENTS LIST ### |
43 | | -1. Microsoft Visual Studio |
44 | | -2. MySQL Cluster |
45 | | -3. Python 2.6 or 2.7 |
46 | | -4. Node.JS |
47 | | -5. node-gyp |
| 129 | ++ *ConnectionProperties(adapterName)*: *Constructor*. Creates a ConnectionProperties |
| 130 | + object containing default values for all properties. |
| 131 | ++ *TableMapping(tableName)*: *Constructor*. Creates a new TableMapping. |
| 132 | ++ *Projection(mappedConstructor)*: *Constructor*. Creates a new Projection. |
| 133 | ++ *connect(properties, [mappings], [callback], [...]): *ASYNC*. The callback |
| 134 | +or promise receives a SessionFactory. |
| 135 | ++ *openSession(properties, [mappings], [callback], [...]): *ASYNC*. An implicit |
| 136 | +SessionFactory is opened if needed; the callback or promise receives a Session. |
| 137 | ++ *getOpenSessionFactories()* Returns an array |
| 138 | ++ *closeAllOpenSessionFactories()* Returns undefined |
48 | 139 |
|
| 140 | +See the [Complete documentation for the top-level API](API-documentation/Mynode) |
49 | 141 |
|
50 | 142 |
|
51 | | -BUILDING |
52 | | --------- |
53 | | -The installation script is interactive. It will try to locate a suitable copy |
54 | | -of MySQL, and it will prompt you to accept its choice or enter an alternative. |
| 143 | +MAPPED JAVASCRIPT OBJECTS |
| 144 | +------------------------- |
55 | 145 |
|
56 | | -* To build the module in place, type: |
57 | | - ```node configure.js``` |
| 146 | + describe mapping |
| 147 | + put an table mapping code example |
| 148 | + link to table mapping docs |
| 149 | + |
58 | 150 |
|
59 | | -* After configuring, build a binary. The -d argument to node-gyp makes it a |
60 | | -"debug" binary |
61 | | - ```node-gyp configure build -d``` |
| 151 | +CONVERTERS |
| 152 | +---------- |
62 | 153 |
|
63 | | -* After testing the debug binary, on platforms other than Windows, it is |
64 | | -possible to build an optimized (non-debug) binary. *Non-debug builds are |
65 | | -generally not possible on Windows, and usually result in link-time errors.* |
66 | | - ```node-gyp rebuild``` |
67 | 154 |
|
| 155 | +BATCHES |
| 156 | +------- |
68 | 157 |
|
69 | | -DIRECTORY STRUCTURE |
70 | | -------------------- |
71 | | -<dl compact> |
72 | | - <dt> API-documentation <dd> Documentation of the main API |
73 | | - <dt> samples/ <dd> Sample code |
74 | | - <dt> setup/ <dd> Scripts used to build and install the adapter |
75 | | - <dt> test/ <dd> Test driver and test suite |
76 | | - <dt> Adapter/ <dd> The node.js adapter |
77 | | - <dt> Adapter/api <dd> Implementation of the top-level API |
78 | | - <dt> Adapter/impl <dd> Backend implementations |
79 | | -</dl> |
80 | 158 |
|
| 159 | +TRANSACTIONS |
| 160 | +------------ |
81 | 161 |
|
82 | | -TESTING |
| 162 | + |
| 163 | +QUERIES |
83 | 164 | ------- |
84 | | -The MySQL server must have the database "test" created. The test infrastructure |
85 | | -currently relies on a mysql command-line client for creating and dropping tables, |
86 | | -so the "mysql" executable must be in your command path. |
87 | 165 |
|
88 | | -To configure the servers and ports used for testing, edit test/test_connection.js |
89 | 166 |
|
90 | | -To run the test suite using the native NDB adapter: |
91 | | -``` |
92 | | - cd test |
93 | | - node driver |
94 | | -``` |
| 167 | +SESSIONFACTORY |
| 168 | +-------------- |
| 169 | + |
95 | 170 |
|
96 | | -To run the test suite using the MySQL adapter: |
97 | | -``` |
98 | | - cd test |
99 | | - node driver --adapter=mysql/ndb |
100 | | - node driver --adapter=mysql/innodb |
101 | | -``` |
102 | 171 |
|
103 | 172 |
|
104 | | -FOR MORE INFORMATION |
105 | | --------------------- |
106 | | -See the issues and other information at http://github.com/mysql/mysql-js/ |
107 | 173 |
|
0 commit comments