Skip to content
Browse files

update README

  • Loading branch information...
1 parent f6165b4 commit c380ceb53bb04d59dbeaebec1ada3ac078b5c3c4 @orlandov committed
Showing with 58 additions and 6 deletions.
  1. +0 −3 .gitignore
  2. +58 −3 README.md
View
3 .gitignore
@@ -1,6 +1,3 @@
build/
-README.html
-test.db
.lock-wscript
-speedtest.db
sqlite3_bindings.node
View
61 README.md
@@ -6,8 +6,16 @@ node-sqlite - Asynchronous SQLite3 driver for Node.js
SYNOPSIS
--------
+High-level Driver
+=================
+
+High-level bindings are provide a simple interface to SQLite3. They should be
+fast enough for most purposes, but if you absolutely need more performance,
+the low level drivers are also straight-forward to use, but require a few
+additional steps.
+
var sys = require('sys'),
- sqlite = require('./sqlite');
+ sqlite = require('sqlite');
var db = new sqlite.Database();
@@ -16,7 +24,7 @@ SYNOPSIS
db.open("lilponies.db", function () {
var colour = 'pink';
- var sql = 'SELECT name FROM ponies WHERE tail_colour = ?';
+ var sql = 'SELECT name FROM ponies WHERE hair_colour = ?';
// bindings list is optional
@@ -35,6 +43,52 @@ SYNOPSIS
});
});
+Low-level Driver
+================
+
+The low-level bindings directly interface with the SQLite C API. The API
+approximately matches the SQLite3 API when it makes sense. Some deviations
+from the API have been made to improve performance.
+
+ var sys = require('sys'),
+ sqlite = require('sqlite_bindings');
+
+ var db = new sqlite.Database();
+
+ // open the database for reading if file exists
+ // create new database file if not
+
+ db.open("lilponies.db", function () {
+ var colour = 'pink';
+ var sql = 'SELECT name FROM ponies WHERE hair_colour = ?';
+
+ var ponies = [];
+
+ // The prepare method will try to prefetch one row of results, so that
+ // if there are no rows we can avoid having to make two trips into the
+ // thread-pool.
+ // If `statement` and didn't have any variable place-holders to bind
+ // and doesn't evaluate to true, then it means the statement
+ // executed successfully but returned no rows (think INSERT's).
+
+ db.prepare(sql, function (error, statement) {
+ if (error) throw error;
+
+ statement.bind(0, 'pink', function () {
+
+ // call step once per row result
+ statement.step(function (row) {
+ if (!row) {
+ // end of rows
+ }
+
+ // do some stuff
+ // call statement.step() again for next row
+ });
+ });
+ });
+ });
+
DESCRIPTION
-----------
@@ -54,7 +108,8 @@ This SQLite interface is incompatible with verison 2.
SQLite's synchronous nature is fundamentally incompatible with a non-blocking
system such as Node. To get around this synchronous calls happen within Node's
libeio thread-pool, in a similar manner to how POSIX calls are currently made.
-This is exposed to JavaScript in the form of Database and Statement objects.
+SQLite's serialized threading mode is used to make sure we use SQLite safely.
+See http://www.sqlite.org/threadsafe.html for more info.
The author is aware that SQLite ships with an asynchronous interface. This
interface however lacks the necessariy notification mechanism to alert the

0 comments on commit c380ceb

Please sign in to comment.
Something went wrong with that request. Please try again.