From f6f7da7d6ab8654771218a9c52c928ed45d3cc10 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Konstantin=20K=C3=A4fer?= Date: Thu, 24 Feb 2011 22:42:59 -0500 Subject: [PATCH] document verbose mode --- README.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5bee702fa..99c79f9f6 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ node-sqlite3 - Asynchronous, non-blocking [SQLite3](http://sqlite.org/) bindings # 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. +`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. For debugging aid, consult the *Error Messages* section. ## new sqlite3.Database(filename, [mode], [callback]) @@ -237,6 +237,28 @@ If you call it without a function parameter, the execution mode setting is stick +# ERROR MESSAGES + +Writing asynchronous functions using the threadpool unfortunately also removes all stack trace information, making debugging very hard since you only see the error message, not which statement caused it. To mitigate this problem, `node-sqlite3` has a **verbose mode** which captures stack traces when enqueuing queries. To enable this mode, call the `sqlite3.verbose()`, or call it directly when requiring: `var sqlite3 = require('sqlite3').verbose()`. + +When you throw an error from a callback passed to any of the database functions, `node-sqlite3` will append the stack trace information from the original call, like this: + + Error: SQLITE_RANGE: bind or column index out of range + --> in Database#run('CREATE TABLE foo (a, b)', 3, [Function]) + at Object. (demo.js:5:4) + at Module._compile (module.js:374:26) + at Object..js (module.js:380:10) + at Module.load (module.js:306:31) + at Function._load (module.js:272:10) + at Array. (module.js:393:10) + at EventEmitter._tickCallback (node.js:108:26) + +Note that you shouldn't enable the verbose mode in a production setting as the performance penalty for collecting stack traces is quite high. + +Verbose mode currently does not add stack trace information to error objects emitted on Statement or Database objects. + + + # BUILDING Make sure you have the sources for `sqlite3` installed. Mac OS X ships with these by default. If you don't have them installed, install the `-dev` package with your package manager, e.g. `apt-get install libsqlite3-dev` for Debian/Ubuntu.