Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 288 lines (189 sloc) 8.799 kb
144800f @felixge Readme update and added License
authored
1 # node-mysql
ce8fdea @felixge Initial import
authored
2
3 ## Purpose
4
9779d70 @felixge Better project description
authored
5 A pure node.js JavaScript Client implementing the [MySQL protocol](http://forge.mysql.com/wiki/MySQL_Internals_ClientServer_Protocol).
ce8fdea @felixge Initial import
authored
6
ad1e2d1 @felixge Note about current status of this module
authored
7 ## Current status
8
9 This module was developed for [Transloadit](http://transloadit.com/), a service focused on uploading
10 and encoding images and videos. It is currently used in production there, but since the service is not
11 very heavy on database interaction your milage may vary.
12
5e1183f @felixge Add contributors to readme
authored
13 ## Contributors
14
a1a6585 @felixge Small readme change
authored
15 * Felix Geisendörfer ([felixge](http://github.com/felixge/node-mysql/commits/master?author=felixge)) - Author and maintainer
5e1183f @felixge Add contributors to readme
authored
16 * Bert Belder ([piscisaureus](http://github.com/felixge/node-mysql/commits/master?author=piscisaureus))
17 * Alan Gutierrez ([bigeasy](http://github.com/felixge/node-mysql/commits/master?author=bigeasy))
18 * Brian ([mscdex](http://github.com/felixge/node-mysql/commits/master?author=mscdex))
19 * Cal Henderson ([iamcal](http://github.com/felixge/node-mysql/commits/master?author=iamcal))
3ff75d8 @felixge Update contributors
authored
20 * Frank Grimm ([FrankGrimm](http://github.com/felixge/node-mysql/commits/master?author=FrankGrimm))
15df342 @felixge Update contributors
authored
21 * Nick Payne ([makeusabrew](http://github.com/felixge/node-mysql/commits/master?author=makeusabrew))
5e1183f @felixge Add contributors to readme
authored
22
185f77e @felixge Readme updates
authored
23 ## Sponsors
24
d0cc512 @felixge Better introduction of the sponsors
authored
25 * [Joyent](http://www.joyent.com/) - Main sponsor, you should check out their [node.js hosting](https://no.de/).
26 * [pinkbike.com](http://pinkbike.com/) - The most awesome biking site there is
185f77e @felixge Readme updates
authored
27
ad1e2d1 @felixge Note about current status of this module
authored
28 This is a rather large project requiring a significant amount of my limited resources.
185f77e @felixge Readme updates
authored
29
ad1e2d1 @felixge Note about current status of this module
authored
30 If your company could benefit from a well-engineered non-blocking mysql driver, and
31 wants to support this project, I would greatly appriciate any sponsorship you may be
32 able to provide. All sponsors will get lifetime display in this readme, priority
33 support on problems, and votes on roadmap decisions. If you are interested, contact
34 me at [felix@debuggable.com](mailto:felix@debuggable.com) for details.
185f77e @felixge Readme updates
authored
35
36 Of course I'm also happy about code contributions. If you're interested in
37 working on features, just get in touch so we can talk about API design and
38 testing.
39
40 [transloadit]: http://transloadit.com/
41
d54a27d @felixge Add npm install hint to readme
authored
42 ## Installation
43
44 npm install mysql
45
9dd3057 @felixge Add instructions for installing without npm
authored
46 Or if you don't want to use npm / run the latest source:
47
48 cd ~/.node_libraries
49 git clone git://github.com/felixge/node-mysql.git mysql
50
ab90020 @felixge Add note about compatibility
authored
51 ## Compatibility
52
1b0e9c8 @felixge Prepare readme for next release
authored
53 This module is compatible with node v0.4.x.
54
55 If you need to work with an older node version, download v0.9.0. It supports
56 node >= v0.1.102.
ab90020 @felixge Add note about compatibility
authored
57
ce8fdea @felixge Initial import
authored
58 ## Design Goals
59
185f77e @felixge Readme updates
authored
60 * TDD: All code is written using test driven development, code coverage should approach 100%
44d9e53 @felixge Changing caps
authored
61 * Simplicity: The MySQL protocol is easy, a good parser should reflect that
ce8fdea @felixge Initial import
authored
62 * Efficiency: Use fast algorithms, buffers and as little memory as possible.
63 * Portability: Should run anywhere node runs
44d9e53 @felixge Changing caps
authored
64 * Completeness: The goal is to support the full MySQL API.
185f77e @felixge Readme updates
authored
65 * Compatibility: MySql >= 4.1
ce8fdea @felixge Initial import
authored
66
456f4f1 @felixge Initial tutorial
authored
67 ## Tutorial
68
4f40891 @piscisaureus Fix obvious mistake in readme
piscisaureus authored
69 var Client = require('mysql').Client,
0d3f5c4 @felixge Improve Readme example further
authored
70 client = new Client(),
71 TEST_DATABASE = 'nodejs_mysl_test',
72 TEST_TABLE = 'test';
456f4f1 @felixge Initial tutorial
authored
73
74 client.user = 'root';
50db0ce @felixge Documenting client properties
authored
75 client.password = 'root';
456f4f1 @felixge Initial tutorial
authored
76
77 client.connect();
78
5eecbdb Readme.md: fix syntax in tutorial, cleanup
Jason Woofenden authored
79 client.query('CREATE DATABASE '+TEST_DATABASE, function(err) {
80 if (err && err.number != Client.ERROR_DB_CREATE_EXISTS) {
456f4f1 @felixge Initial tutorial
authored
81 throw err;
82 }
83 });
84
85 // If no callback is provided, any errors will be emitted as `'error'`
86 // events by the client
5eecbdb Readme.md: fix syntax in tutorial, cleanup
Jason Woofenden authored
87 client.query('USE '+TEST_DATABASE);
456f4f1 @felixge Initial tutorial
authored
88
89 client.query(
90 'CREATE TEMPORARY TABLE '+TEST_TABLE+
91 '(id INT(11) AUTO_INCREMENT, '+
92 'title VARCHAR(255), '+
93 'text TEXT, '+
94 'created DATETIME, '+
5eecbdb Readme.md: fix syntax in tutorial, cleanup
Jason Woofenden authored
95 'PRIMARY KEY (id))'
456f4f1 @felixge Initial tutorial
authored
96 );
97
98 client.query(
99 'INSERT INTO '+TEST_TABLE+' '+
100 'SET title = ?, text = ?, created = ?',
5eecbdb Readme.md: fix syntax in tutorial, cleanup
Jason Woofenden authored
101 ['super cool', 'this is a nice text', '2010-08-16 10:00:23']
456f4f1 @felixge Initial tutorial
authored
102 );
103
104 var query = client.query(
105 'INSERT INTO '+TEST_TABLE+' '+
106 'SET title = ?, text = ?, created = ?',
107 ['another entry', 'because 2 entries make a better test', '2010-08-16 12:42:15']
108 );
109
110 client.query(
111 'SELECT * FROM '+TEST_TABLE,
0d3f5c4 @felixge Improve Readme example further
authored
112 function selectCb(err, results, fields) {
456f4f1 @felixge Initial tutorial
authored
113 if (err) {
114 throw err;
115 }
116
117 console.log(results);
118 console.log(fields);
119 client.end();
0d3f5c4 @felixge Improve Readme example further
authored
120 }
456f4f1 @felixge Initial tutorial
authored
121 );
122
50db0ce @felixge Documenting client properties
authored
123 ## API
124
125 ### new mysql.Client([options])
126
127 Creates a new client instance. Any client property can be set using the
4a93056 @felixge Readme fix
authored
128 `options` object.
50db0ce @felixge Documenting client properties
authored
129
130 ### client.host = 'localhost'
131
132 The host to connect to.
133
134 ### client.port = 3306
135
136 The port to connect to.
137
138 ### client.user = null
139
140 The username to authenticate as.
141
142 ### client.password = null
143
144 The password to use.
145
146 ### client.database = null
147
148 The name of the database to connect to (optional).
149
9633f0d @felixge Document debug mode
authored
150 ### client.debug = false
151
152 Prints incoming and outgoing packets, useful for development / testing purposes.
153
50db0ce @felixge Documenting client properties
authored
154 ### client.flags = Client.defaultFlags
155
156 Connection flags send to the server.
157
3c5e180 @felixge Document client methods
authored
158 ### client.connect([cb])
159
160 Initiates a connection to the specified host server.
161
162 ### client.query(sql, [params, cb])
163
164 Sends a `sql` query to the server. `'?'` characters can be used as placeholders
165 for an array of `params` that will be safely escaped before sending the final
166 query.
167
658cc73 @felixge Documentation for the Query object
authored
168 This method returns a `Query` object which can be used to stream incoming row
169 data.
170
cbb1fc8 @felixge Add note about multiple queries in one sql query
authored
171 **Warning:** `sql` statements with multiple queries separated by semicolons
172 are not supported yet.
173
5628337 @felixge Update docs
authored
174 ### client.ping([cb])
175
176 Sends a ping command to the server.
177
0f4cdc6 @FrankGrimm Fix typo.
FrankGrimm authored
178 ### client.useDatabase(database, [cb])
5628337 @felixge Update docs
authored
179
180 Same as issuing a `'USE <database>'` query.
181
182 ### client.statistics([cb])
183
184 Returns some server statistics provided by MySql.
185
3c5e180 @felixge Document client methods
authored
186 ### client.format(sql, params)
187
188 Allows to safely insert a list of `params` into a `sql` string using the
189 placeholder mechanism described above.
190
191 ### client.escape(val)
192
193 Escapes a single `val` for use inside of a sql string.
194
f2e895c @felixge Implemented client.destroy()
authored
195 ### client.destroy([cb])
196
197 Forces the client connection to be destroyed right away. This is not a
198 nice way to terminate the connection, use with caution.
199
1708b1e @piscisaureus Delay client.end until queries are finished
piscisaureus authored
200 ### client.end([cb])
3c5e180 @felixge Document client methods
authored
201
f2e895c @felixge Implemented client.destroy()
authored
202 Schedule a COM_QUIT packet for closing the connection. All currently queued
203 queries will still execute before the graceful termination of the connection
204 is attempted.
3c5e180 @felixge Document client methods
authored
205
d3dedd9 @felixge Lowercase event
authored
206 ### client event: 'error' (err)
658cc73 @felixge Documentation for the Query object
authored
207
208 When the client has no callback / delegate for an error, it is emitted with this
209 event instead.
210
211 ### new mysql.Query()
212
213 Query objects are not meant to be invoked manually. To get a query object, use
214 the `client.query` API.
215
d3dedd9 @felixge Lowercase event
authored
216 ### query event: 'error' (err)
658cc73 @felixge Documentation for the Query object
authored
217
218 Emitted when mysql returns an error packet for the query.
219
d3dedd9 @felixge Lowercase event
authored
220 ### query event: 'field' (field)
658cc73 @felixge Documentation for the Query object
authored
221
222 Emitted upon receiving a field packet from mysql.
223
d3dedd9 @felixge Lowercase event
authored
224 ### query event: 'row' (row)
658cc73 @felixge Documentation for the Query object
authored
225
226 Emitted upon receiving a row. An option for streaming the contents of the row
227 itself will be made available soon.
228
d3dedd9 @felixge Lowercase event
authored
229 ### query event: 'end' ([result])
658cc73 @felixge Documentation for the Query object
authored
230
231 Emitted once the query is finished. In case there is no result set, a `result`
232 parameter is provided which contains the information from the mysql OK packet.
233
c5540bf @felixge Document retrieval of last insert id
authored
234 ## FAQ
235
e174096 @felixge Add another FAQ entry
authored
236 ### How do I compile this module?
237
238 This module is written entirely in JavaScript. There is no dependency on external
239 C libraries such as libmysql. That means you don't have to compile this module
240 at all.
241
c5540bf @felixge Document retrieval of last insert id
authored
242 ### How can I retrieve the id from the last inserted record?
243
244 client.query('INSERT INTO my_table SET title = ?', function(err, info) {
245 console.log(info.insertId);
246 });
247
144800f @felixge Readme update and added License
authored
248 ## Todo
249
1a8a2e1 @felixge Note about state of the module
authored
250 At this point the module is ready to be tried out, but a lot of things are yet to be done:
144800f @felixge Readme update and added License
authored
251
20a542e @felixge Update todo list
authored
252 * Pause / resume
c14b4d2 @felixge Update todo
authored
253 * Remaining mysql commands
144800f @felixge Readme update and added License
authored
254 * Prepared Statements
c14b4d2 @felixge Update todo
authored
255 * Packet's > 16 MB
256 * Compression
257 * Performance profiling
f7aeead @felixge Update readme
authored
258 * Handle re-connect after bad credential error (should query queue be kept?)
e62b900 @felixge Update Readme
authored
259 * Deal with stale connections / other potential network issues
cbb1fc8 @felixge Add note about multiple queries in one sql query
authored
260 * Decide how to handle queries with multiple statements
144800f @felixge Readme update and added License
authored
261
1b0e9c8 @felixge Prepare readme for next release
authored
262 ## Changelog
263
1521eda @felixge Bump version
authored
264 ### v0.9.1
1b0e9c8 @felixge Prepare readme for next release
authored
265
266 * Fix issue #49 / `client.escape()` throwing exceptions on objects. (Nick Payne)
267 * Drop < v0.4.x compatibility. From now on you need node v0.4.x to use this module.
268
269 [See Commits](https://github.com/felixge/node-formidable/compare/v0.9.0...v0.9.1)
270
271 ### Older releases
272
273 These releases were done before starting to maintain the above Changelog:
274
275 * [v0.9.0](https://github.com/felixge/node-formidable/compare/v0.8.0...v0.9.0)
276 * [v0.8.0](https://github.com/felixge/node-formidable/compare/v0.7.0...v0.9.0)
277 * [v0.7.0](https://github.com/felixge/node-formidable/compare/v0.6.0...v0.9.0)
278 * [v0.6.0](https://github.com/felixge/node-formidable/compare/v0.5.0...v0.9.0)
279 * [v0.5.0](https://github.com/felixge/node-formidable/compare/v0.4.0...v0.9.0)
280 * [v0.4.0](https://github.com/felixge/node-formidable/compare/v0.3.0...v0.9.0)
281 * [v0.3.0](https://github.com/felixge/node-formidable/compare/v0.2.0...v0.9.0)
282 * [v0.2.0](https://github.com/felixge/node-formidable/compare/v0.1.0...v0.9.0)
283 * [v0.1.0](https://github.com/felixge/node-formidable/commits/v0.1.0)
284
144800f @felixge Readme update and added License
authored
285 ## License
ce8fdea @felixge Initial import
authored
286
144800f @felixge Readme update and added License
authored
287 node-mysql is licensed under the MIT license.
Something went wrong with that request. Please try again.