The easiest way to “deploy” a node app is to clone the git repo on a server, and run npm install. There are a couple of disadvantages though: first, I don’t really like having to install git, and manage credentials for a private repo.

Second, installing the dependencies like that means you may get different versions of the modules you rely on than you were expecting. One of the tenets of a reliable build pipeline is ensuring that builds are repeatable, and that what you deploy matches what you tested.

There are a few alternatives: you could vendor in the node_modules folder, but this dirties the commit history, and increases the size of your repo. You could use npm shrinkwrap, which is the same concept as Bundler’s Gemfile.lock, a list of specific versions to install. This is definitely an improvement, but still leaves the risk of npm i failing during a deployment.

I’d prefer to only install the dependencies once, on the build server. This means I can run the tests, then tar up the folder and upload that to each environment in turn:

npm install
npm test
npm prune --production
npm dedupe
tar -czf app.tar.gz --exclude='*/coverage' app/

After running the tests, we prune the dependencies to remove mocha etc. We then dedupe to try and reduce the number of copies of shared modules, and finally create an archive of the app. This is output as an artifact of the build, and pulled in the by the deploy to staging build, output from that again, and finally pulled in by the deploy to production build.

While it is possible to use node-pg with just raw callbacks, as soon as you want to use transactions the chances of getting it right dwindle rapidly.

Using a promise library helps remove some of the pain. I ended up with something like this (using Q):

var Q = require('q'),
    pg = require('pg'),
    Connection = require('./Connection');

module.exports = function(connString) {
    this.connect = function() {
        var deferred = Q.defer();

        pg.connect(connString, function(err, client, done) {
            if (err) {
                return deferred.reject(new Error(err));
            }

            deferred.resolve(new Connection(client, done));
        });

        return deferred.promise;
    };
};

var Q = require('q'),
    pg = require('pg');

module.exports = function(client, done) {
    this.begin = function() {
        return this.query('BEGIN;', []);
    };

    this.query = function(sql, args) {
        var deferred = Q.defer();

        client.query(sql, args, function(err, result) {
            if (err) {
                err.message = err.message + ' (Query: ' + sql + ', Args: ' + args + ')';
                return deferred.reject(err);
            }

            deferred.resolve(result.rows);
        });

        return deferred.promise;
    };

    this.rollback = function() {
        var deferred = Q.defer();

        client.query('ROLLBACK', function(err) {
            deferred.resolve();
            return done(err);
        });

        return deferred.promise;
    };

    this.commit = function() {
        var deferred = Q.defer();

        client.query('COMMIT', function(err) {
            if (err) {
                deferred.reject(err);
            } else {
                deferred.resolve();
            }
            return done(err);
        });

        return deferred.promise;
    };

    this.close = function() {
        done();
    };
}

Which you can use like this:

var db = new Db(connString);

return db.connect().then(function(conn) {
    return db.begin().then(function() {
        return conn.query('SELECT something FROM foo WHERE id = $1;', [id]).then(function(rows) {
            return conn.query('INSERT INTO ...', [...]);
        }).then(function() {
            return conn.commit();
        });
    }).fin(conn.close);
});

And remove at least some of the risk of failing to return the connection to the pool, or otherwise bungling your error handling.