Skip to content
This repository
Newer
Older
100644 174 lines (113 sloc) 4.247 kb
144800f9 »
2010-07-29 Readme update and added License
1 # node-mysql
ce8fdea8 »
2010-07-29 Initial import
2
3 ## Purpose
4
5 A node.js module implementing the
44d9e53a »
2010-07-29 Changing caps
6 [MySQL protocol](http://forge.mysql.com/wiki/MySQL_Internals_ClientServer_Protocol).
ce8fdea8 »
2010-07-29 Initial import
7
8 ## Design Goals
9
44d9e53a »
2010-07-29 Changing caps
10 * Simplicity: The MySQL protocol is easy, a good parser should reflect that
ce8fdea8 »
2010-07-29 Initial import
11 * Efficiency: Use fast algorithms, buffers and as little memory as possible.
12 * Portability: Should run anywhere node runs
44d9e53a »
2010-07-29 Changing caps
13 * Completeness: The goal is to support the full MySQL API.
ce8fdea8 »
2010-07-29 Initial import
14
456f4f1f »
2010-08-16 Initial tutorial
15 ## Tutorial
16
17 var Client = new require('mysql').Client,
18 client = new Client();
19
20 client.user = 'root';
50db0ce7 »
2010-08-16 Documenting client properties
21 client.password = 'root';
456f4f1f »
2010-08-16 Initial tutorial
22
23 client.connect();
24
25 client.query('CREATE DATABASE '+TEST_CONFIG.database, function() {
26 if (err && err.errorNumber != Client.ERROR_DB_CREATE_EXISTS) {
27 throw err;
28 }
29 });
30
31 // If no callback is provided, any errors will be emitted as `'error'`
32 // events by the client
33 client.query('USE '+TEST_CONFIG.database);
34
35 client.query(
36 'CREATE TEMPORARY TABLE '+TEST_TABLE+
37 '(id INT(11) AUTO_INCREMENT, '+
38 'title VARCHAR(255), '+
39 'text TEXT, '+
40 'created DATETIME, '+
41 'PRIMARY KEY (id));',
42 );
43
44 client.query(
45 'INSERT INTO '+TEST_TABLE+' '+
46 'SET title = ?, text = ?, created = ?',
47 ['super cool', 'this is a nice text', '2010-08-16 10:00:23'],
48 );
49
50 var query = client.query(
51 'INSERT INTO '+TEST_TABLE+' '+
52 'SET title = ?, text = ?, created = ?',
53 ['another entry', 'because 2 entries make a better test', '2010-08-16 12:42:15']
54 );
55
56 client.query(
57 'SELECT * FROM '+TEST_TABLE,
58 gently.expect(function selectCb(err, results, fields) {
59 if (err) {
60 throw err;
61 }
62
63 console.log(results);
64 console.log(fields);
65 client.end();
66 })
67 );
68
50db0ce7 »
2010-08-16 Documenting client properties
69 ## API
70
71 ### new mysql.Client([options])
72
73 Creates a new client instance. Any client property can be set using the
74 `options array.
75
76 ### client.host = 'localhost'
77
78 The host to connect to.
79
80 ### client.port = 3306
81
82 The port to connect to.
83
84 ### client.user = null
85
86 The username to authenticate as.
87
88 ### client.password = null
89
90 The password to use.
91
92 ### client.database = null
93
94 The name of the database to connect to (optional).
95
96 ### client.flags = Client.defaultFlags
97
98 Connection flags send to the server.
99
3c5e1802 »
2010-08-16 Document client methods
100 ### client.connect([cb])
101
102 Initiates a connection to the specified host server.
103
104 ### client.query(sql, [params, cb])
105
106 Sends a `sql` query to the server. `'?'` characters can be used as placeholders
107 for an array of `params` that will be safely escaped before sending the final
108 query.
109
658cc73e »
2010-08-16 Documentation for the Query object
110 This method returns a `Query` object which can be used to stream incoming row
111 data.
112
3c5e1802 »
2010-08-16 Document client methods
113 ### client.format(sql, params)
114
115 Allows to safely insert a list of `params` into a `sql` string using the
116 placeholder mechanism described above.
117
118 ### client.escape(val)
119
120 Escapes a single `val` for use inside of a sql string.
121
122 ### client.end()
123
124 Closes the connection to the server.
125
d3dedd9d »
2010-08-16 Lowercase event
126 ### client event: 'error' (err)
658cc73e »
2010-08-16 Documentation for the Query object
127
128 When the client has no callback / delegate for an error, it is emitted with this
129 event instead.
130
131 ### new mysql.Query()
132
133 Query objects are not meant to be invoked manually. To get a query object, use
134 the `client.query` API.
135
d3dedd9d »
2010-08-16 Lowercase event
136 ### query event: 'error' (err)
658cc73e »
2010-08-16 Documentation for the Query object
137
138 Emitted when mysql returns an error packet for the query.
139
d3dedd9d »
2010-08-16 Lowercase event
140 ### query event: 'field' (field)
658cc73e »
2010-08-16 Documentation for the Query object
141
142 Emitted upon receiving a field packet from mysql.
143
d3dedd9d »
2010-08-16 Lowercase event
144 ### query event: 'row' (row)
658cc73e »
2010-08-16 Documentation for the Query object
145
146 Emitted upon receiving a row. An option for streaming the contents of the row
147 itself will be made available soon.
148
d3dedd9d »
2010-08-16 Lowercase event
149 ### query event: 'end' ([result])
658cc73e »
2010-08-16 Documentation for the Query object
150
151 Emitted once the query is finished. In case there is no result set, a `result`
152 parameter is provided which contains the information from the mysql OK packet.
153
144800f9 »
2010-07-29 Readme update and added License
154 ## Todo
155
1a8a2e1c »
2010-08-16 Note about state of the module
156 At this point the module is ready to be tried out, but a lot of things are yet to be done:
144800f9 »
2010-07-29 Readme update and added License
157
158 * Prepared Statements
6d0027cf »
2010-07-30 Initial auth and OutgoingPacket implementation
159 * Test using no Password
160 * Charsets handling
d732d488 »
2010-07-31 Parse OK_PACKET
161 * Import Error code constants
144800f9 »
2010-07-29 Readme update and added License
162 * ...
163
164 ## License
ce8fdea8 »
2010-07-29 Initial import
165
144800f9 »
2010-07-29 Readme update and added License
166 node-mysql is licensed under the MIT license.
ce8fdea8 »
2010-07-29 Initial import
167
168 ## Sponsors
169
170 * [Joyent](http://www.joyent.com/)
171
44d9e53a »
2010-07-29 Changing caps
172 This is a big effort. If your company could benefit from a top-notch MySQL driver
71bd2ab5 »
2010-07-29 Details
173 for node, a small sponsorship payment would be greatly appreciated. Contact
075a4bf7 »
2010-08-16 Update todos
174 me at [felix@debuggable.com](mailto:felix@debuggable.com) for details.
Something went wrong with that request. Please try again.