What is it about
Being the author of the connection module for Firebird for NodeJS, I have long postponed the publication about it, considering that the module is still quite raw. In addition, the development of the module has somewhat stalled, since all the functionality I need is already present in it (however, it is still far from being universal).
From time to time, it only becomes necessary to correct the identified error or correct something to ensure compatibility with the latest stable version of NodeJS. I must say that the module is not popular due to the focus of the NodeJS community on the NoSQL solution. And the Firebird community, apparently, looks at NodeJS with caution, and it’s not that big either. In addition, quite often Firebird is used in conjunction with Delphi on the Windows platform, so it is also hard to interest anyone working on Windows with a specific Linux solution. However, the recent significant advancement of the NodeJS project towards Windows support has given hope of attracting the attention of such people to the project. This post will discuss how to work with Firebird from NodeJS. Installation instructions for Linux and Windows, examples of typical work scenarios will be given. The topic, however, is designed for those who are at least a little familiar with Firebird (a working copy of the database server is needed for experiments). For those who are not familiar with Firebird, at the end of the publication will be given links to resources to learn.
Interested - welcome under cat.
')
Installation
Linux
Nodejs
First of all you need NodeJS. The Internet is full of NodeJS installation guides for Linux. However, for the sake of completeness, you will have to bring one more here. I downloaded the Ubuntu 11.10 Server 32bit distribution. Installation was performed in a virtual machine. The task of this publication does not include the description of the struggle with the difficulties of various distributions. Rather, on the contrary, a description of the easiest way to get the result is needed
So, I installed Ubuntu 11.10 Server with a minimal set of packages (only OpenSSH server).
Only two console commands allow you to get your copy of NodeJS.
sudo apt-get update sudo apt-get install nodejs
However, despite the fresh distribution, you will get the NodeJS version that is up to date at the end of the summer of 2011.
xdenser@ubuntu:~$ node > process.version 'v0.4.9' > .exit xdenser@ubuntu:~$
Next, you need to install NodeJS package manager.
sudo apt-get install npm
We also need the development package for Firebird 2.5 if you already have a server to which you want to connect.
sudo apt-get install firebird2.5-dev
If you do not have a server, you can install the server locally. The description of this process is beyond the scope of the publication.
When installing, the Firebird access module is compiled. For this we need a compiler.
sudo apt-get install g++
Well, in fact, the access module itself in this case is put by the following command.
sudo npm install firebird@0.0.5 -g
or
npm install firebird@0.0.5
The difference is that in the first case the module is installed globally - i.e. for all users.
These commands install an outdated version of the module (the current version at the time of writing this article is v0.0.8), but is compatible with the version of NodeJS v0.4.9 included in the distribution.
In order to install the latest version, you must enter the command
npm install firebird
Only for this you will need to update NodeJS to version 0.6.x.
We are now following the simplest path.
So, let's check that everything is set right with us:
xdenser@ubuntu:~$ node > require('firebird'); { createConnection: [Function], createConnectionPool: [Function], Stream: { [Function: Stream] super_: { [Function: Stream] super_: [Function: EventEmitter] } } } > .exit xdenser@ubuntu:~$
Windows
For Windows, at a minimum, you must install
the Firebird client libraries from the installation package for your version of Windows.
With Windows NodeJS recently everything is much easier. You can use the official installation
package , along with which you will receive the npm package manager.
However, it is not worth while to use npm to install the firebird module for Windows, since the module is distributed as source codes, and the automatic build for Windows is not yet available.
For Windows, you can use a pre
-built build that already includes NodeJS. Your scripts should be placed in the root folder of the assembly and run the command
node.exe myScript.js
What's next?
You can try to connect to some database. To do this, create two files.
test.js:
var fb = require('firebird'); console.log(fb); var cfg = require("./config").cfg; var conn = fb.createConnection(); console.log(conn); conn.connect(cfg.db, cfg.user, cfg.password, cfg.role, function(){ console.log("Connected to database"); conn.query("select * from rdb$relations", function(err,res){ if(err){ console.log("error"); console.log(err); return; } console.log( res ); var r = res.fetchSync("all",true); console.log( r ); conn.disconnect(); }); });
and
config.js:
exports.cfg = {
Naturally, the connection settings in config.js need to be replaced with your own.
And run the command
node.exe test.js
Line execution
console.log( r );
from the file test.js will give you in the console a dump of the result of the SQL query
select * from rdb$relations
Small module guide
A module, like all NodeJS modules, is loaded with a similar command:
var fb = require('firebird');
The module essentially exports only two properties:
- createConnection is a method that creates a new Connection object to the Connection database.
- Stream is a stream object for working with BLOB fields.
We will not consider working with BLOB fields yet.
And the
createConnection method
is called without parameters.
var conn = fb.createConnection();
after such a call, conn can be viewed as an instance of the Connection class with the following methods and properties:
- connected - a property that reflects the connection status of an instance of Connection;
- inTransaction; - a property reflecting the state of the current transaction (on working with transactions, see below);
- function connect (database, username, password, role, callback); - makes connection to the database;
- function querySync (sql); - method. Executes a SQL query and returns an instance of the FBResult class;
- function query (sql, callback); - method. Asynchronously executes the SQL query and returns the result in the callback function. The result is also an instance of FBResult;
- function commitSync (); - method. Commit to commit current transaction;
- function commit (callback); - method. Makes asynchronous commit the current transaction;
- function rollbackSync (); - method. Performs a rollback on the current transaction;
- function rollback (callback); - method. Makes an asynchronous rollback of the current transaction;
- function addFBevent (name); - method. Allows you to subscribe to the name event in Firebird;
- function deleteFBevent (name); - method. Allows you to unsubscribe from the name event in Firebird.
Instances of the FBResult class provide only two methods:
- function fetchSync (rowCount, asObject); - method. Returns a JavaScript array of rowCount (or fewer) query result records. The asObject parameter can be true or false. The form of presentation of each record depends on it. In the case of true, each entry is represented by a JavaScript object, where each field corresponds to a property with the same name. If false, each entry is just an array of values, i.e. fetchSync will then return a two-dimensional array;
- function fetch (rowCount, asObject, rowCallback, eofCallback); - method. Produces asynchronous selection of records. The first two parameters correspond to the fetchSync method. rowCallback is a callback function that is executed for each sample record and receives as input 1 parameter - an object or an array, depending on asObject. The second eofCallback callback is executed when the sample ends and takes two parameters as input:
- err - in case of error, this is the Error object,
- eof is a sign of the end of the sample; it is true only if we have reached the end of the sample.
You can choose not the entire result of the query.
A more complete guide is in the README file that comes with the module. It can also be read online at the
GitHub repository .
Work with transactions
The current version of the module does not provide complete transaction management capabilities. Each Connection object automatically starts a transaction before executing the query, if it was not started earlier or was interrupted by one of the methods commitSync, commit, rollbackSync, rollback.
Perhaps, this amount of material is quite enough for the initial experiments with the module. If there is interest in this topic, then I will publish examples of working with BLOB fields, events, and prepared query.
In addition, I prepared an example of a project that implements an interactive service for executing SQL queries to a Firebird database through a browser:
References: