Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

update README

  • Loading branch information...
commit c380ceb53bb04d59dbeaebec1ada3ac078b5c3c4 1 parent f6165b4
@orlandov authored
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
Please sign in to comment.
Something went wrong with that request. Please try again.