Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 297 lines (195 sloc) 8.143 kb
144800f @felixge Readme update and added License
authored
1 # node-mysql
ce8fdea @felixge Initial import
authored
2
4c462d4 @felixge Add badge of nerd honor again
authored
3 [![Build Status](https://secure.travis-ci.org/felixge/node-mysql.png)](http://travis-ci.org/felixge/node-mysql)
4
ce8fdea @felixge Initial import
authored
5 ## Purpose
6
9779d70 @felixge Better project description
authored
7 A pure node.js JavaScript Client implementing the [MySQL protocol](http://forge.mysql.com/wiki/MySQL_Internals_ClientServer_Protocol).
ce8fdea @felixge Initial import
authored
8
e862258 @felixge Best shameless promotion I could come up with so far
authored
9 ## Support this module
ad1e2d1 @felixge Note about current status of this module
authored
10
e862258 @felixge Best shameless promotion I could come up with so far
authored
11 If you like this module, check out and spread the word about our service
12 [transloadit.com][]. We provide file uploading and encoding functionality to
52b8c48 @felixge Fix typo
authored
13 other applications, and have performed billions of queries with this module so
14 far.
e862258 @felixge Best shameless promotion I could come up with so far
authored
15
16 [transloadit.com]: http://transloadit.com/
ad1e2d1 @felixge Note about current status of this module
authored
17
d54a27d @felixge Add npm install hint to readme
authored
18 ## Installation
19
9dec840 @felixge Update install instructions
authored
20 ```
21 npm install mysql
22 ```
9dd3057 @felixge Add instructions for installing without npm
authored
23
192336e @felixge Change headline
authored
24 **Important**: If you are upgrading from 0.9.1 or below, there have been
25 backwards incompatible changes in the API. Please read the [upgrading guide][].
26
27 [upgrading guide]: https://github.com/felixge/node-mysql/wiki/Upgrading-to-0.9.2+
28
8d82839 @felixge Drop design goal section
authored
29 ## Usage
456f4f1 @felixge Initial tutorial
authored
30
331c7a4 @felixge Update Readme for new API goal
authored
31 ``` javascript
32 var mysql = require('mysql');
33 var TEST_DATABASE = 'nodejs_mysql_test';
34 var TEST_TABLE = 'test';
35 var client = mysql.createClient({
36 user: 'root',
37 password: 'root',
38 });
39
40 client.query('CREATE DATABASE '+TEST_DATABASE, function(err) {
41 if (err && err.number != mysql.ERROR_DB_CREATE_EXISTS) {
42 throw err;
43 }
44 });
45
46 // If no callback is provided, any errors will be emitted as `'error'`
47 // events by the client
48 client.query('USE '+TEST_DATABASE);
49
50 client.query(
51 'CREATE TEMPORARY TABLE '+TEST_TABLE+
52 '(id INT(11) AUTO_INCREMENT, '+
53 'title VARCHAR(255), '+
54 'text TEXT, '+
55 'created DATETIME, '+
56 'PRIMARY KEY (id))'
57 );
58
59 client.query(
60 'INSERT INTO '+TEST_TABLE+' '+
61 'SET title = ?, text = ?, created = ?',
62 ['super cool', 'this is a nice text', '2010-08-16 10:00:23']
63 );
64
65 var query = client.query(
66 'INSERT INTO '+TEST_TABLE+' '+
67 'SET title = ?, text = ?, created = ?',
68 ['another entry', 'because 2 entries make a better test', '2010-08-16 12:42:15']
69 );
70
71 client.query(
72 'SELECT * FROM '+TEST_TABLE,
73 function selectCb(err, results, fields) {
74 if (err) {
75 throw err;
76 }
77
78 console.log(results);
79 console.log(fields);
80 client.end();
81 }
82 );
83 ```
456f4f1 @felixge Initial tutorial
authored
84
50db0ce @felixge Documenting client properties
authored
85 ## API
86
bc3ba52 @felixge Update docs, remove more deprecated stuff
authored
87 ### mysql.createClient([options])
50db0ce @felixge Documenting client properties
authored
88
89 Creates a new client instance. Any client property can be set using the
4a93056 @felixge Readme fix
authored
90 `options` object.
50db0ce @felixge Documenting client properties
authored
91
92 ### client.host = 'localhost'
93
94 The host to connect to.
95
96 ### client.port = 3306
97
98 The port to connect to.
99
100 ### client.user = null
101
102 The username to authenticate as.
103
104 ### client.password = null
105
106 The password to use.
107
108 ### client.database = null
109
110 The name of the database to connect to (optional).
111
9633f0d @felixge Document debug mode
authored
112 ### client.debug = false
113
114 Prints incoming and outgoing packets, useful for development / testing purposes.
115
50db0ce @felixge Documenting client properties
authored
116 ### client.flags = Client.defaultFlags
117
118 Connection flags send to the server.
119
3c5e180 @felixge Document client methods
authored
120 ### client.query(sql, [params, cb])
121
122 Sends a `sql` query to the server. `'?'` characters can be used as placeholders
123 for an array of `params` that will be safely escaped before sending the final
124 query.
125
658cc73 @felixge Documentation for the Query object
authored
126 This method returns a `Query` object which can be used to stream incoming row
127 data.
128
cbb1fc8 @felixge Add note about multiple queries in one sql query
authored
129 **Warning:** `sql` statements with multiple queries separated by semicolons
130 are not supported yet.
131
5628337 @felixge Update docs
authored
132 ### client.ping([cb])
133
134 Sends a ping command to the server.
135
0f4cdc6 @FrankGrimm Fix typo.
FrankGrimm authored
136 ### client.useDatabase(database, [cb])
5628337 @felixge Update docs
authored
137
138 Same as issuing a `'USE <database>'` query.
139
140 ### client.statistics([cb])
141
142 Returns some server statistics provided by MySql.
143
3c5e180 @felixge Document client methods
authored
144 ### client.format(sql, params)
145
146 Allows to safely insert a list of `params` into a `sql` string using the
147 placeholder mechanism described above.
148
149 ### client.escape(val)
150
151 Escapes a single `val` for use inside of a sql string.
152
077d985 @felixge Fix destroy() documentation
authored
153 ### client.destroy()
f2e895c @felixge Implemented client.destroy()
authored
154
077d985 @felixge Fix destroy() documentation
authored
155 Forces the client connection / socket to be destroyed right away.
f2e895c @felixge Implemented client.destroy()
authored
156
1708b1e @piscisaureus Delay client.end until queries are finished
piscisaureus authored
157 ### client.end([cb])
3c5e180 @felixge Document client methods
authored
158
f2e895c @felixge Implemented client.destroy()
authored
159 Schedule a COM_QUIT packet for closing the connection. All currently queued
160 queries will still execute before the graceful termination of the connection
161 is attempted.
3c5e180 @felixge Document client methods
authored
162
d3dedd9 @felixge Lowercase event
authored
163 ### client event: 'error' (err)
658cc73 @felixge Documentation for the Query object
authored
164
165 When the client has no callback / delegate for an error, it is emitted with this
166 event instead.
167
168 ### new mysql.Query()
169
170 Query objects are not meant to be invoked manually. To get a query object, use
171 the `client.query` API.
172
d3dedd9 @felixge Lowercase event
authored
173 ### query event: 'error' (err)
658cc73 @felixge Documentation for the Query object
authored
174
175 Emitted when mysql returns an error packet for the query.
176
d3dedd9 @felixge Lowercase event
authored
177 ### query event: 'field' (field)
658cc73 @felixge Documentation for the Query object
authored
178
179 Emitted upon receiving a field packet from mysql.
180
d3dedd9 @felixge Lowercase event
authored
181 ### query event: 'row' (row)
658cc73 @felixge Documentation for the Query object
authored
182
183 Emitted upon receiving a row. An option for streaming the contents of the row
184 itself will be made available soon.
185
d3dedd9 @felixge Lowercase event
authored
186 ### query event: 'end' ([result])
658cc73 @felixge Documentation for the Query object
authored
187
188 Emitted once the query is finished. In case there is no result set, a `result`
189 parameter is provided which contains the information from the mysql OK packet.
190
c5540bf @felixge Document retrieval of last insert id
authored
191 ## FAQ
192
e174096 @felixge Add another FAQ entry
authored
193 ### How do I compile this module?
194
195 This module is written entirely in JavaScript. There is no dependency on external
196 C libraries such as libmysql. That means you don't have to compile this module
197 at all.
198
c5540bf @felixge Document retrieval of last insert id
authored
199 ### How can I retrieve the id from the last inserted record?
200
201 client.query('INSERT INTO my_table SET title = ?', function(err, info) {
202 console.log(info.insertId);
203 });
204
2c96da4 @mjbaldwin Added documentation for affectedRows to FAQ
mjbaldwin authored
205 ### How can I find out the number of rows affected by the last query?
206
207 client.query('UPDATE my_table SET title = ?', function(err, info) {
208 console.log(info.affectedRows);
209 });
210
144800f @felixge Readme update and added License
authored
211 ## Todo
212
1a8a2e1 @felixge Note about state of the module
authored
213 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
214
ab60f4c @felixge Update todos
authored
215 * Implement retry
20a542e @felixge Update todo list
authored
216 * Pause / resume
c14b4d2 @felixge Update todo
authored
217 * Remaining mysql commands
144800f @felixge Readme update and added License
authored
218 * Prepared Statements
c14b4d2 @felixge Update todo
authored
219 * Packet's > 16 MB
220 * Compression
cbb1fc8 @felixge Add note about multiple queries in one sql query
authored
221 * Decide how to handle queries with multiple statements
144800f @felixge Readme update and added License
authored
222
416bf38 @felixge Move stuff in Readme
authored
223 ## Contributors
224
225 [Click here][contributors] for a full list of contributors.
226
227 [contributors]: https://github.com/felixge/node-mysql/contributors
228
229 ## Sponsors
230
231 * [Joyent](http://www.joyent.com/) - Main sponsor, you should check out their [node.js hosting](https://no.de/).
232 * [pinkbike.com](http://pinkbike.com/) - The most awesome biking site there is
233
234 This is a rather large project requiring a significant amount of my limited resources.
235
236 If your company could benefit from a well-engineered non-blocking mysql driver, and
237 wants to support this project, I would greatly appriciate any sponsorship you may be
238 able to provide. All sponsors will get lifetime display in this readme, priority
239 support on problems, and votes on roadmap decisions. If you are interested, contact
240 me at [felix@debuggable.com](mailto:felix@debuggable.com) for details.
241
242 Of course I'm also happy about code contributions. If you're interested in
243 working on features, just get in touch so we can talk about API design and
244 testing.
245
246 [transloadit]: http://transloadit.com/
247
1b0e9c8 @felixge Prepare readme for next release
authored
248 ## Changelog
249
27efc0c @felixge Update changelog
authored
250 ### v0.9.5
251
252 * Fix #142 Driver stalls upon reconnect attempt that's immediately closed
253 * Add travis build
254 * Switch to urun as a test runner
255 * Switch to utest for unit tests
256 * Remove fast-or-slow dependency for tests
257 * Split integration tests into individual files again
258
259 ### v0.9.4
260
261 * Expose package.json as `mysql.PACKAGE` (#104)
262
263 ### v0.9.3
264
265 * Set default `client.user` to root
266 * Fix #91: Client#format should not mutate params array
267 * Fix #94: TypeError in client.js
268 * Parse decimals as string (vadimg)
269
88881c4 @felixge Update Changelog
authored
270 ### v0.9.2
271
272 * The underlaying socket connection is now managed implicitly rather than explicitly.
273 * Check the [upgrading guide][] for a full list of changes.
274
1521eda @felixge Bump version
authored
275 ### v0.9.1
1b0e9c8 @felixge Prepare readme for next release
authored
276
277 * Fix issue #49 / `client.escape()` throwing exceptions on objects. (Nick Payne)
278 * Drop < v0.4.x compatibility. From now on you need node v0.4.x to use this module.
279
280 ### Older releases
281
282 These releases were done before starting to maintain the above Changelog:
283
8882039 @felixge Fix copy & paste failure
authored
284 * [v0.9.0](https://github.com/felixge/node-mysql/compare/v0.8.0...v0.9.0)
0790eba @felixge Fix changelog diff links
authored
285 * [v0.8.0](https://github.com/felixge/node-mysql/compare/v0.7.0...v0.8.0)
286 * [v0.7.0](https://github.com/felixge/node-mysql/compare/v0.6.0...v0.7.0)
287 * [v0.6.0](https://github.com/felixge/node-mysql/compare/v0.5.0...v0.6.0)
288 * [v0.5.0](https://github.com/felixge/node-mysql/compare/v0.4.0...v0.5.0)
289 * [v0.4.0](https://github.com/felixge/node-mysql/compare/v0.3.0...v0.4.0)
290 * [v0.3.0](https://github.com/felixge/node-mysql/compare/v0.2.0...v0.3.0)
291 * [v0.2.0](https://github.com/felixge/node-mysql/compare/v0.1.0...v0.2.0)
8882039 @felixge Fix copy & paste failure
authored
292 * [v0.1.0](https://github.com/felixge/node-mysql/commits/v0.1.0)
1b0e9c8 @felixge Prepare readme for next release
authored
293
144800f @felixge Readme update and added License
authored
294 ## License
ce8fdea @felixge Initial import
authored
295
144800f @felixge Readme update and added License
authored
296 node-mysql is licensed under the MIT license.
Something went wrong with that request. Please try again.