Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

more documentation

  • Loading branch information...
commit d828344fa1975666a705736d9ebc211fe2dd272a 1 parent 5d97fa3
@kkaefer kkaefer authored
Showing with 77 additions and 1 deletion.
  1. +77 −1 README.md
View
78 README.md
@@ -7,6 +7,7 @@ node-sqlite3 - Asynchronous, non-blocking [SQLite3](http://sqlite.org/) bindings
# USAGE
var db = new sqlite3.Database(':memory:');
+
db.serialize(function() {
db.run("CREATE TABLE lorem (info TEXT)");
@@ -20,10 +21,14 @@ node-sqlite3 - Asynchronous, non-blocking [SQLite3](http://sqlite.org/) bindings
});
});
+ db.close();
+
# API
+`node-sqlite3` has built-in function call serialization and automatically waits before executing a blocking action until no other action is pending. This means that it's safe start calling functions on the database object even if it is not yet fully opened. The `Database#close()` function will wait until all pending queries are completed before closing the database. To control serialization and parallelization of queries, see the *Control Flow* section of this document.
+
## new sqlite3.Database(filename, [mode], [callback])
Returns a new Database object and automatically opens the database. There is no separate method to open the database.
@@ -63,6 +68,8 @@ Runs the SQL query with the specified parameters and calls the callback afterwar
This binds the first placeholder (`$id`) to `2` and the placeholder with index `5` to `"bar"`. While this is valid in SQLite and `node-sqlite3`, it is not recommended to mix different placeholder types.
+ If you use an array or an object to bind parameters, it must be the first value in the bind arguments list. If any other object is before it, an error will be thrown. Additional bind parameters after an array or object will be ignored.
+
* `callback` *(optional)*: If given, it will be called when an error occurs during any step of the statement preparation or execution, *and* after the query was run. If an error occured, the first (and only) parameter will be an error object containing the error message. If execution was successful, the first parameter is `null`. The context of the function (the `this` object inside the function) is the statement object. Note that it is not possible to run the statement again because it is automatically finalized after running for the first time. Any subsequent attempts to run the statement again will fail.
If execution was successful, it contains two properties named `lastID` and `changes` which contain the value of the last inserted row ID and the number of rows affected by this query respectively. Note that `lastID` **only** contains valid information when the query was a successfully completed `INSERT` statement and `changes` **only** contains valid information when the query was a successfully completed `UPDATE` or `DELETE` statement. In all other cases, the content of these properties is inaccurate and should not be used. The `.run()` function is the only query method that sets these two values; all other query methods such as `.all()` or `.get()` don't retrieve these values.
@@ -99,7 +106,76 @@ There is currently no way to abort execution.
-## more to come
+## Database#prepare(sql, [param, ...], [callback])
+
+Prepares the SQL statement and optionally binds the specified parameters and calls the callback when done. The function returns a Statement object.
+
+When preparing was successful, the first and only argument to the callback is `null`, otherwise it is the error object. When bind parameters are supplied, they are bound to the prepared statement before calling the callback.
+
+
+
+## Statement#bind([param, ...], [callback])
+
+Binds parameters to the prepared statement and calls the callback when done or when an error occurs. The function returns the Statement object to allow for function chaining. The first and only argument to the callback is `null` when binding was successful, otherwise it is the error object.
+
+Binding parameters with this function completely resets the statement object and row cursor and removes all previously bound parameters, if any.
+
+
+
+## Statement#reset([callback])
+
+Resets the row cursor of the statement and preserves the parameter bindings. Use this function to reexecute the same query with the same bindings. The function returns the Statement object to allow for function chaining. The callback will be called after the reset is complete. This action will never fail and will always return `null` as the first and only callback parameter.
+
+
+
+## Statement#finalize([callback])
+
+Finalizes the statement. This is typically optional, but if you experience long delays before the next query is executed, explicitly finalizing your statement might be necessary. This might be the case when you run an exclusive query (see section *Serialization*). After the statement is finalized, all further function calls on that statement object will throw errors.
+
+
+
+## Statement#run([param, ...], [callback])
+
+Binds parameters and executes the statement. The function returns the Statement object to allow for function chaining.
+
+If you specify bind parameters, they will be bound to the statement before it is executed. Note that the bindings and the row cursor are reset when you specify even a single bind parameter.
+
+The callback behavior is identical to the `Database#run` method with the difference that the statement will not be finalized after it is run. This means you can run it multiple times.
+
+
+
+## Statement#get([param, ...], [callback])
+
+Binds parameters, executes the statement and retrieves the first result row. The function returns the Statement object to allow for function chaining. The parameters are the same as the Statement#run function, with the following differences:
+
+The signature of the callback is `function(err, row) {}`. If the result set is empty, the second parameter is undefined, otherwise it is an object containing the values for the first row. Like with `Statement#run`, the statement will not be finalized after executing this function.
+
+
+
+## Statement#all([param, ...], [callback])
+
+Binds parameters, executes the statement and calls the callback with all result rows. The function returns the Statement object to allow for function chaining. The parameters are the same as the Statement#run function, with the following differences:
+
+The signature of the callback is `function(err, rows) {}`. If the result set is empty, the second parameter is an empty array, otherwise it contains an object for each result row which in turn contains the values of that row. Like with `Statement#run`, the statement will not be finalized after executing this function.
+
+
+
+## Statement#each([param, ...], [callback])
+
+Binds parameters, executes the statement and calls the callback for each result row. The function returns the Statement object to allow for function chaining. The parameters are the same as the Statement#run function, with the following differences:
+
+The signature of the callback is `function(err, row) {}`. If the result set succeeds but is empty, the callback is never called (this will change in the future). In all other cases, the callback is called once for every retrieved row. The order of calls correspond exactly to the order of rows in the result set. Like with `Statement#run`, the statement will not be finalized after executing this function.
+
+If you know that a query only returns a very limited number of rows, it might be more convenient to use `Statement#all` to retrieve all rows at once.
+
+There is currently no way to abort execution.
+
+
+
+# CONTROL FLOW
+
+TODO
+
# BUILDING
Please sign in to comment.
Something went wrong with that request. Please try again.