Skip to content
Newer
Older
100644 207 lines (136 sloc) 5.38 KB
144800f @felixge Readme update and added License
authored
1 # node-mysql
ce8fdea @felixge Initial import
authored
2
3 ## Purpose
4
5 A node.js module implementing the
44d9e53 @felixge Changing caps
authored
6 [MySQL protocol](http://forge.mysql.com/wiki/MySQL_Internals_ClientServer_Protocol).
ce8fdea @felixge Initial import
authored
7
5e1183f @felixge Add contributors to readme
authored
8 ## Contributors
9
10 * Bert Belder ([piscisaureus](http://github.com/felixge/node-mysql/commits/master?author=piscisaureus))
11 * Alan Gutierrez ([bigeasy](http://github.com/felixge/node-mysql/commits/master?author=bigeasy))
12 * Brian ([mscdex](http://github.com/felixge/node-mysql/commits/master?author=mscdex))
13 * Cal Henderson ([iamcal](http://github.com/felixge/node-mysql/commits/master?author=iamcal))
14
185f77e @felixge Readme updates
authored
15 ## Sponsors
16
17 * [Joyent](http://www.joyent.com/)
18
19 I'm working on this driver because I need it for my own startup
20 ([transloadit.com][transloadit]), but it's a big project (~100-200 hours) with
21 obvious benefits to other companies who are using MySql.
22
23 So if your company could benefit from a well-engineered node.js mysql driver,
4d012d6 @felixge One more readme update
authored
24 I would greatly appriciate any sponsorship you may be able to provide. All
25 sponsors will get lifetime display in this readme, priority support on problems,
26 and votes on roadmap decisions. If you are interested, contact me at
27 [felix@debuggable.com](mailto:felix@debuggable.com) for details.
185f77e @felixge Readme updates
authored
28
29 Of course I'm also happy about code contributions. If you're interested in
30 working on features, just get in touch so we can talk about API design and
31 testing.
32
33 [transloadit]: http://transloadit.com/
34
d54a27d @felixge Add npm install hint to readme
authored
35 ## Installation
36
37 npm install mysql
38
ce8fdea @felixge Initial import
authored
39 ## Design Goals
40
185f77e @felixge Readme updates
authored
41 * TDD: All code is written using test driven development, code coverage should approach 100%
44d9e53 @felixge Changing caps
authored
42 * Simplicity: The MySQL protocol is easy, a good parser should reflect that
ce8fdea @felixge Initial import
authored
43 * Efficiency: Use fast algorithms, buffers and as little memory as possible.
44 * Portability: Should run anywhere node runs
44d9e53 @felixge Changing caps
authored
45 * Completeness: The goal is to support the full MySQL API.
185f77e @felixge Readme updates
authored
46 * Compatibility: MySql >= 4.1
ce8fdea @felixge Initial import
authored
47
456f4f1 @felixge Initial tutorial
authored
48 ## Tutorial
49
4f40891 @piscisaureus Fix obvious mistake in readme
piscisaureus authored
50 var Client = require('mysql').Client,
456f4f1 @felixge Initial tutorial
authored
51 client = new Client();
52
53 client.user = 'root';
50db0ce @felixge Documenting client properties
authored
54 client.password = 'root';
456f4f1 @felixge Initial tutorial
authored
55
56 client.connect();
57
58 client.query('CREATE DATABASE '+TEST_CONFIG.database, function() {
59 if (err && err.errorNumber != Client.ERROR_DB_CREATE_EXISTS) {
60 throw err;
61 }
62 });
63
64 // If no callback is provided, any errors will be emitted as `'error'`
65 // events by the client
66 client.query('USE '+TEST_CONFIG.database);
67
68 client.query(
69 'CREATE TEMPORARY TABLE '+TEST_TABLE+
70 '(id INT(11) AUTO_INCREMENT, '+
71 'title VARCHAR(255), '+
72 'text TEXT, '+
73 'created DATETIME, '+
74 'PRIMARY KEY (id));',
75 );
76
77 client.query(
78 'INSERT INTO '+TEST_TABLE+' '+
79 'SET title = ?, text = ?, created = ?',
80 ['super cool', 'this is a nice text', '2010-08-16 10:00:23'],
81 );
82
83 var query = client.query(
84 'INSERT INTO '+TEST_TABLE+' '+
85 'SET title = ?, text = ?, created = ?',
86 ['another entry', 'because 2 entries make a better test', '2010-08-16 12:42:15']
87 );
88
89 client.query(
90 'SELECT * FROM '+TEST_TABLE,
91 gently.expect(function selectCb(err, results, fields) {
92 if (err) {
93 throw err;
94 }
95
96 console.log(results);
97 console.log(fields);
98 client.end();
99 })
100 );
101
50db0ce @felixge Documenting client properties
authored
102 ## API
103
104 ### new mysql.Client([options])
105
106 Creates a new client instance. Any client property can be set using the
4a93056 @felixge Readme fix
authored
107 `options` object.
50db0ce @felixge Documenting client properties
authored
108
109 ### client.host = 'localhost'
110
111 The host to connect to.
112
113 ### client.port = 3306
114
115 The port to connect to.
116
117 ### client.user = null
118
119 The username to authenticate as.
120
121 ### client.password = null
122
123 The password to use.
124
125 ### client.database = null
126
127 The name of the database to connect to (optional).
128
9633f0d @felixge Document debug mode
authored
129 ### client.debug = false
130
131 Prints incoming and outgoing packets, useful for development / testing purposes.
132
50db0ce @felixge Documenting client properties
authored
133 ### client.flags = Client.defaultFlags
134
135 Connection flags send to the server.
136
3c5e180 @felixge Document client methods
authored
137 ### client.connect([cb])
138
139 Initiates a connection to the specified host server.
140
141 ### client.query(sql, [params, cb])
142
143 Sends a `sql` query to the server. `'?'` characters can be used as placeholders
144 for an array of `params` that will be safely escaped before sending the final
145 query.
146
658cc73 @felixge Documentation for the Query object
authored
147 This method returns a `Query` object which can be used to stream incoming row
148 data.
149
3c5e180 @felixge Document client methods
authored
150 ### client.format(sql, params)
151
152 Allows to safely insert a list of `params` into a `sql` string using the
153 placeholder mechanism described above.
154
155 ### client.escape(val)
156
157 Escapes a single `val` for use inside of a sql string.
158
159 ### client.end()
160
161 Closes the connection to the server.
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
144800f @felixge Readme update and added License
authored
191 ## Todo
192
1a8a2e1 @felixge Note about state of the module
authored
193 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
194
c14b4d2 @felixge Update todo
authored
195 * Handle timeouts / reconnect
196 * Remaining mysql commands
144800f @felixge Readme update and added License
authored
197 * Prepared Statements
6d0027c @felixge Initial auth and OutgoingPacket implementation
authored
198 * Charsets handling
c14b4d2 @felixge Update todo
authored
199 * Packet's > 16 MB
200 * Compression
201 * Performance profiling
202 * ?
144800f @felixge Readme update and added License
authored
203
204 ## License
ce8fdea @felixge Initial import
authored
205
144800f @felixge Readme update and added License
authored
206 node-mysql is licensed under the MIT license.
Something went wrong with that request. Please try again.