Permalink
Browse files

Clean up README

  • Loading branch information...
1 parent 6d53991 commit 4bddfa7853dfaed5ae838dcc7c207d42282d693f @orlandov committed Sep 25, 2010
Showing with 24 additions and 74 deletions.
  1. +24 −74 README.md
View
98 README.md
@@ -2,24 +2,14 @@
node-sqlite - Asynchronous SQLite3 driver for Node.js
-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.
+currently made.
# SYNOPSIS
## 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,
-the low level drivers are also straight-forward to use, but require a few
-additional steps.
-
var sys = require('sys'),
sqlite = require('sqlite');
@@ -28,66 +18,21 @@ additional steps.
// 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 = ?';
-
- // bindings list is optional
-
- var ponies = [];
-
- db.query(sql, [colour], function (error, pony) {
- if (error) throw error;
- if (!pony) {
- // no more ponies
- if (!ponies.length)
- sys.puts('There are no ponies with ' + colour + ' tails. :(');
- else
- sys.puts('The following ponies have ' + colour + ' tails: ' + ponies.join(', '));
- }
- sys.puts(sys.inspect(pony));
- ponies.push(pony);
- });
- });
-
-## 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.
-
- var sys = require('sys'),
- sqlite = require('sqlite');
-
- 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 = $hair_colour' +
- ' AND gemstones = ?';
-
- var ponies = [];
+ db.open("aquateen.db", function (error) {
+ if (error) {
+ console.log("Purple Alert! Aqua Teen Database unabled to be opened!"));
+ throw error;
+ }
+ var sql = 'SELECT name FROM dudes WHERE type = ? AND age > ?';
db.prepare(sql, function (error, statement) {
if (error) throw error;
// Fill in the placeholders
- // Could also have used:
- // statement.bind(position, value, function () { ... });
- // statement.bindObject({ $hair_colour: 'pink' }, function () {});
- statement.bindArray(['pink', 4], function () {
-
- // call step once per row result
- statement.step(function (error, row) {
- if (!row) {
- // end of rows
- }
-
- // do some stuff
- // call statement.step() again for next row
+ statement.bindArray(['milkshake', 30], function () {
+
+ statement.fetchAll(function (error, rows) {
+ // ...
});
});
});
@@ -98,6 +43,7 @@ approximately matches the SQLite3 API when it makes sense.
## Database Objects
To create a new database object:
+ var sqlite = require('sqlite');
var db = sqlite.Database();
@@ -113,6 +59,12 @@ A filename of ":memory:" may be used to create an in-memory database.
Close the database handle.
+### database.query(sql, [bindings,] function (error, row) {})
+
+Execute a SQL query, `sql`, with optional bindings `bindings` on the currently
+opened database. The callback will be executed once per row returned, plus
+once more with row set to undefined to indicate end of results.
+
### database.executeScript(SQL, function (error) {});
db.executeScript
@@ -126,25 +78,24 @@ Close the database handle.
});
Execute multiple semi-colon separated SQL statements. Statements must take no
-placeholders. Each statements will be executed with a single step() and then
-reset. This is ideally suited to executing DDL statements that take no
-arguments and return no results.
+placeholders. Each statement will be executed with a single step() and then
+reset. This is ideally suited to executing multiple DDL statements.
### 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.
+is performed.
Options:
- lastInsertRowID: boolean, default false.
- If true, when this statement is stepped over, the context object (this) in
+ If true, when this statement is step()'d 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
+ If true, when this statement is step()'d over, the context object (this) in
the callback will contain an affectedRows member with the number of
affected rows for the last step.
@@ -180,8 +131,7 @@ Immediately clear the bindings from the statement. There is no callback.
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.
+represented as objects with properties named after the respective columns.
### statement.fetchAll(function (error, rows) {})

1 comment on commit 4bddfa7

@timlind

An example for using the options argument of prepare would be very useful, so that it's clear that it is an object with those two properties.

Please sign in to comment.