Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 218 lines (150 sloc) 9.262 kB
10c397d @straps Versione 1.0.3, added the filesystem driver and the inotifywait metho…
authored
1 # Database and Filesystem monitor utilities for nodejs
2
3 If you are trying to update a GUI when a database table changes (_insert_, _update_, _delete_) or when a file is being created/modified/deleted/moved, this library is for you.
f3ec110 @straps node-dbmon initial release
authored
4
5 This is a node.js module supporting a growing number of database drivers and notification transports
6 you can extend and improve.
7
8 It is designed to be easily extended with simple sintax by anyone and, where possibile,
9 to notify of changes without classic polling, but with real-time notification mechanism
10
10c397d @straps Versione 1.0.3, added the filesystem driver and the inotifywait metho…
authored
11
f3ec110 @straps node-dbmon initial release
authored
12 ## Usage sample
10c397d @straps Versione 1.0.3, added the filesystem driver and the inotifywait metho…
authored
13
14 This is a short example of the PostgreSQL driver; you can find more on `test/test-postgresql.js`
f3ec110 @straps node-dbmon initial release
authored
15
16 Install a local postgresql database server; grant temporary trust access to the postgresql
17 user editing the pg_hba.conf file and create a test table like this `create table testtable(id integer primary key, val varchar(10));`
18 then run the following
19
20 var pg=require('pg'), cli=new pg.Client('tcp://postgres@localhost/template1'), dbmon=require('dbmon');
21
22 cli.connect();
23 //uncomment if you want node to create the temporary table for you
24 //cli.query('drop table if exists testtable; create table testtable(id integer primary key, val varchar(10));');
25
26 var channel=dbmon.channel({
27 driver:'postgresql',
28 driverOpts:{
29 postgresql:{
30 cli:cli
31 }
32 },
33 table:'testtable',
34 monitor:'all',
35 keyfld:{
36 name:'id',type:'integer'
37 }
38 });
39
40 Now monitor the console and execute some insert/update/delete and see what happens...
41
42 You should see come console messages saying you are modifiyng `testtable` like this
43
44 Console Transport Notification: insert, row={"op":"i","k":2,"oldk":2,"id":1}
45
46 In this case I've executed a simple insert like `insert into testtable values(2,'TWO');`.
47 Console says that the type of notification is an insert and the row modified
48 from last notification is `{"op":"i","k":2,"oldk":2,"id":1}` where fields means:
49
50 - *op* is the operation type; can be *i* for insert, *u* for update, *d* for delete and *t* for truncate
51 - *k* is the key inserted/updated/deleted based on what specified in `keyfld.name`
52 - *oldk* is the old key value, see what happens executing `update testtable set id=20, val='twenty' where id=2`
53 - *id* is an internal change sequence id, an ordered number useful to keep track of modifications
54
55 It is very interesting to know that if you update 2 or more rows in the same transaction, there will
56 arrive 2 ore more notifications based on the number or rows being modified
57
58 Another good thing is that for PostgreSQL, *dbmon* is powered by the NOTIFY/LISTEN constructs. It means
59 that, when something changes, the server that contacts node and node notify listeners via the transports specified, making
60 it really real-time, not like other polling-based alternatives.
61
62 To see the complete list of options see [lib/channelDefaults.js](https://github.com/straps/node-dbmon/blob/master/lib/channelDefaults.js)
63
64
10c397d @straps Versione 1.0.3, added the filesystem driver and the inotifywait metho…
authored
65 ### Sample for the new filesystem driver
66
67 On linux, you can experiment the new `filesystem` driver. It is based on `inotifywait`, a linux command line utility
68 that helps you monitor for file changes; on ubuntu you can install it by typing
69
70 sudo apt-get install inotify-tools
71
72 Now Execute this code
73
74 require('dbmon').channel({
75 driver:'filesystem',
76 driverOpts:{filesystem:{root:'/home'}},
77 method:'inotifywait',
78 transports:'console'
79 });
80
81 and monitor the console when you create/modify/delete files on your home directory or subdirectories (Desktop too). FUN
82
f3ec110 @straps node-dbmon initial release
authored
83 ## Structure and Naming Conventions
84
85 Dbmon is designed to be dynamic and easily extensible; there are 3 main actors to extend it
86
87 - **transports**, in [lib/providers](https://github.com/straps/node-dbmon/tree/master/lib/transports) are the way dbmon notify events. You can use how many tranports you want separating them by comma. The name specified in the options object have to match the name of the file followed by `-tranport.js` in the `transports` foler, like the `console` transport in the example above.
88 - **providers**, in [lib/providers](https://github.com/straps/node-dbmon/tree/master/lib/providers), have to initialize their method to fetch data and notify transports whene something happen; in most cases (surely for postgresql case) they should only require the `generic-driver` that dynamiccaly instantiate the method and notify transports
89 - **methods**, in [lib/providers](https://github.com/straps/node-dbmon/tree/master/lib/methods), are the core of the system; their implementation depends upon the driver and the method specified in the configuration object and their name should respect `DRIVER-METHOD-method.js` convention (ie: postgresql-trigger-method.js). Methods init function return an `EventEmitter` inherited object that notify listeners where data changes firing the event notification chain
90
91
10c397d @straps Versione 1.0.3, added the filesystem driver and the inotifywait metho…
authored
92 ### How To Create a new Transport
f3ec110 @straps node-dbmon initial release
authored
93
10c397d @straps Versione 1.0.3, added the filesystem driver and the inotifywait metho…
authored
94 Creating a new transport is very simple; the node module have to export a single function `init` that `dbmon` will call passing the global options object.
f3ec110 @straps node-dbmon initial release
authored
95
10c397d @straps Versione 1.0.3, added the filesystem driver and the inotifywait metho…
authored
96 The `init` function have to return an object with a `notify` method, magically called from drivers, when something server side changes.
f3ec110 @straps node-dbmon initial release
authored
97
98 Say we want a generic TCP Socket transport to communicate with another application, transmitting db update notification.
99
100 Create the file `lib/transports/tcpsocket.js` and insert the following lines:
101
102 //TCP Socket Tranport
103 var init=function init(opts){
104 console.log('TCP Socket Transport init');
105 var me={
106 notify:function(type, row){
107 opts.transportsOpts.tcpsocket.client.write(JSON.stringify(row));
108 return me;
109 }
110 };
111 return me;
112 };
113 module.exports={init:init};
114
115 Now use it from your node.js server socket app:
116
117 var net = require('net');
118 var server = net.createServer(function (c) {
119 c.on('data', function(data){
120 console.log('DATA FROM SOCKET HURRAAA --> '+data);
121 });
122 });
123 server.listen(8124, 'localhost', function(){
124 var client=new net.Socket();
125 client.connect(8124, 'localhost', function(){
126 console.log('connected');
127
128 var pg=require('pg'), cli=new pg.Client('tcp://postgres@localhost/template1'), dbmon=require('dbmon');
129 cli.connect();
130
131 dbmon.channel({
132 driver:'postgresql',
133 driverOpts:{
134 postgresql:{
135 cli:cli
136 }
137 },
138 table:'testtable',
139 method:'trigger',
140 transports:'tcpsocket',
141 transportsOpts:{
142 tcpsocket:{
143 client:client
144 }
145 },
146 keyfld:{ name:'id', type:'integer'}
147 });
148 });
149 });
150
10c397d @straps Versione 1.0.3, added the filesystem driver and the inotifywait metho…
authored
151 In 20 lines of (uncompressed) code you can create and use a new tranport, contribute to the library and make others happy (me too :)
f3ec110 @straps node-dbmon initial release
authored
152
153 Creating a new driver and a new driver method, could be some more complicated, but I thing, in next releases will be a generic
10c397d @straps Versione 1.0.3, added the filesystem driver and the inotifywait metho…
authored
154 mixed trigger/polling based driver I'm thinking on.
f3ec110 @straps node-dbmon initial release
authored
155
156
157 ## Testing
158
159 Test cases are home-made and could not be complete or well done, so feel free to fork and improve tests too.
160
5c1f91e @straps Version 1.0.4, Added Faye transport, see History.md for complete list
authored
161 In any case, you can test the library doing a `make test` from main directory
f3ec110 @straps node-dbmon initial release
authored
162
163
164 ## Installation
165
166 Using npm: `npm install dbmon`
167
168 Or `npm install dbmon -g` and `npm link dbmon` if you prefer linking a global installation
169
170 Or you can download/fork and copy on a local folder inside your project
171
172
173 ### External Dependencies, automatically installed if you use npm
174
175 - [Underscore.js](http://documentcloud.github.com/underscore/) (`npm install underscore`)
176 - [Step](https://github.com/creationix/step) (`npm install step`)
177
178 Database drivers, depends on the driver you use, including
179
180 - [Pg](https://github.com/brianc/node-postgres) (`npm install pg`)
181
10c397d @straps Versione 1.0.3, added the filesystem driver and the inotifywait metho…
authored
182 Only for test
f3ec110 @straps node-dbmon initial release
authored
183
184 - [Colors](https://github.com/Marak/colors.js) (`npm install colors`)
185
186
187
188 ## ToDo
189 - Develop other drivers (MySQL, Oracle, MsSQL, etc...)
190 - Develop other transports (Faye, Hook.io, etc..)
10c397d @straps Versione 1.0.3, added the filesystem driver and the inotifywait metho…
authored
191 - Write better tests with a single connection, command line parameters and one file per driver/method/transport
f3ec110 @straps node-dbmon initial release
authored
192
193
194 ## License
195
196 (The MIT License)
197
198 Copyright (c) 2011 Francesco Strappini <f@strx.it>
199
200 Permission is hereby granted, free of charge, to any person obtaining
201 a copy of this software and associated documentation files (the
202 'Software'), to deal in the Software without restriction, including
203 without limitation the rights to use, copy, modify, merge, publish,
204 distribute, sublicense, and/or sell copies of the Software, and to
205 permit persons to whom the Software is furnished to do so, subject to
206 the following conditions:
207
208 The above copyright notice and this permission notice shall be
209 included in all copies or substantial portions of the Software.
210
211 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
212 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
213 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
214 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
215 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
216 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
217 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.