Skip to content
Browse files

Update README and package.json

  • Loading branch information...
1 parent c448d19 commit 8710ae28778e877988fa1e2ec8d17d313dae6635 @orlandov committed Sep 5, 2010
Showing with 111 additions and 52 deletions.
  1. +109 −50 README.md
  2. +2 −2 package.json
View
159 README.md
@@ -1,13 +1,19 @@
-NAME
-----
+# NAME
node-sqlite - Asynchronous SQLite3 driver for Node.js
-SYNOPSIS
---------
+This distribution includes two SQLite libraries: a low level driver
+written in C++ and a high level driver. The latter wraps the former to add
+simpler API.
+
+SQLite calls block, so to work around this, synchronous calls happen within
+Node's libeio thread-pool, in a similar manner to how POSIX calls are
+currently made. SQLite's serialized threading mode is used to make sure we
+use SQLite safely. See http://www.sqlite.org/threadsafe.html for more info.
+
+# SYNOPSIS
-High-level Driver
-=================
+## High-level Driver
High-level bindings provide a simple interface to SQLite3. They should be
fast enough for most purposes, but if you absolutely need more performance,
@@ -43,15 +49,13 @@ additional steps.
});
});
-Low-level Driver
-================
+## 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.
+approximately matches the SQLite3 API when it makes sense.
var sys = require('sys'),
- sqlite = require('sqlite_bindings');
+ sqlite = require('sqlite/sqlite3_bindings');
var db = new sqlite.Database();
@@ -60,17 +64,12 @@ from the API have been made to improve performance.
db.open("lilponies.db", function () {
var colour = 'pink';
- var sql = 'SELECT name FROM ponies WHERE hair_colour = $hair_colour and gemstones = ?';
+ var sql = 'SELECT name FROM ponies' +
+ ' WHERE hair_colour = $hair_colour' +
+ ' AND gemstones = ?';
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;
@@ -93,73 +92,133 @@ from the API have been made to improve performance.
});
});
+# API
-DESCRIPTION
------------
+## Database Objects
-This distribution includes two SQLite version 3 drivers: a low level driver
-written in C++ and a high level driver. The latter wraps the former to add
-nicer API.
+To create a new database object:
+
+ var db = sqlite_bindings.Database();
+
+### database.open(filename, function (error) {})
+
+Open a database handle to the database at the specified filename. If the file
+does not exist the bindings will attempt to create it. The callback takes no
+arguments.
+
+A filename of ":memory:" may be used to create an in-memory database.
+
+### database.close(function (error) {})
+
+Close the database handle.
+
+### database.prepare(SQL, [options,] function (error, statement) {})
+
+Create a prepared statement from an SQL string. Prepared statements can be
+used used to iterate over results and to avoid compiling SQL each time a query
+is performed.
+
+Options:
+
+- lastInsertRowID: boolean, default false.
+ If true, when this statement is stepped over, the context object (this) in
+ the callback will contain a lastInsertRowID member with the ID of the last
+ inserted row.
+
+- affectedRows: boolean, default false.
+ If true, when this statement is stepped over, the context object (this) in
+ the callback will contain an affectedRows member with the number of
+ affected rows for the last step.
+
+## Statement Objects
+
+### statement.bindArray(array, function (error) {})
+
+ statement.bindArray([1, 'robots', 4.20], callback)
+
+Bind array items to place-holder values (? or $foo) in statement.
+
+### statement.bindObject(object, function (error) {})
+
+ statement.bindObject({ $name: 'meatwad',
+ $occupation: 'Former detective' }, callback)
+
+Bind object properties to named place-holder values ($foo, $bar, $baz) in
+statement.
+
+### statement.bind(position, value, function (error) {})
+
+ statement.bind(1, "tango", function (error) {})
+
+Bind a value to a place-holder position. Because binding place-holders is done
+by position (not index), the first place-holder is at position 1, second at
+place-holder position 2, etc.
+
+### statement.clearBindings()
+
+Immediately clear the bindings from the statement. There is no callback.
+
+### statement.step(function (error, row) {})
+
+Fetch one row from a prepared statement and hand it off to a callback. If
+there are no more rows to be fetched, row will be undefined. Rows are
+represented as objects with
+properties named after the respective columns.
+
+### statement.fetchAll(function (error, rows) {})
+
+Fetch all rows in statement and pass them to the callback as an array of
+objects, each object representing one row.
+
+### statement.reset()
-It's HTML5 WebDatabasish but much, much simpler.
+Immediately reset a statement object back to it's initial state, ready to be
+step() or fetchAll()'d again.
-At the moment, this library is the bare minimum necessary to get results out
-of SQLite, but extending either driver should be quite straight forward.
+### statement.finalize(function (error) {})
-This SQLite interface is incompatible with version 2.
+Free SQLite objects associated with this statement and mark it for garbage
+collection.
-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.
-SQLite's serialized threading mode is used to make sure we use SQLite safely.
-See http://www.sqlite.org/threadsafe.html for more info.
+## Supported Types
-The author is aware that SQLite ships with an asynchronous interface. This
-interface however lacks the necessary notification mechanism to alert the
-caller when the SQLite call has completed. In other words, to be able to
-support callbacks, we use the synchronous driver within a seperate thread.
+At the moment, the supported types are TEXT, NUMBER, FLOAT and NULL.
-BUILDING
---------
+# BUILDING
-To build the bindings:
+To obtain and build the bindings:
git clone http://github.com/orlandov/node-sqlite.git
cd node-sqlite
node-waf configure build
-TESTS
------
+# TESTS
Running the unit tests could not be easier. Simply:
git submodule update --init
./run-tests
-SEE ALSO
---------
+# SEE ALSO
* http://sqlite.org/docs.html
* http://github.com/grumdrig/node-sqlite/
-AUTHORS
--------
+# AUTHORS
Orlando Vazquez [ovazquez@gmail.com]
Ryan Dahl [ry@tinyclouds.org]
-THANKS
-------
+# THANKS
Many thanks to Eric Fredricksen for his synchronous driver on which this
driver was originally based.
* http://github.com/grumdrig/node-sqlite/
* http://grumdrig.com/node-sqlite/
-LICENSE
--------
+# LICENSE
node-sqlite is BSD licensed.
View
4 package.json
@@ -1,6 +1,6 @@
{ "name": "sqlite"
, "description": "SQLite3 bindings for Node"
-, "version": "0.0.2"
+, "version": "0.0.3"
, "homepage": "http://github.com/orlandov/node-sqlite"
, "author":
"Orlando Vazquez <ovazquez@gmail.com> (http://2wycked.net)"
@@ -15,7 +15,7 @@
, "url": "http://github.com/orlandov/node-sqlite.git"
}
, "directories" : { "lib" : "." }
-, "engines" : { "node" : ">=0.1.103" }
+, "engines" : { "node" : ">=0.2.0" }
, "scripts" : { "test" : "./run-tests" }
, "licenses" :
[ { "type" : "BSD" }

0 comments on commit 8710ae2

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