ravel-postgresql-provider

Ravel DatabaseProvider for postgresql

ravel-postgresql-provider is a DatabaseProvider for Ravel, wrapping the powerful node postgresql library. It supports connection pooling as well as Ravel's transaction system (including rollbacks).

Example usage:

Step 1: Import and instantiate the PostgreSQL provider

app.js

const app = new require('ravel')();
const postgresqlProvider = require('ravel-postgresql-provider');
new postgresqlProvider(app);
// ... other providers and parameters
app.modules('./modules');
app.resources('./resources');
// ... the rest of your Ravel app
app.init();
app.listen();

Step 2: Access connections via @transaction

resources/posts_resource.js

const Ravel = require('ravel');
const inject = Ravel.inject;
const Resource = Ravel.Resource;
const transaction = Resource.transaction;

@inject('posts')
class PostsResource extends Resource {
  constructor(posts) {
    super('/posts');
    this.posts = posts;
  }

  /**
   * Retrieve a single post
   */
  @transaction('postgresql')
  get(ctx) {
    // Best practice is to pass the transaction object through to a Module, where you handle the actual business logic.
    return this.posts.getPost(ctx.transaction, ctx.params.id)
    .then((posts) => {
      ctx.body = posts;
    });
  }
}

Step 3: Use connections to perform queries

modules/posts.js

const Ravel = require('ravel');
const Module = Ravel.Module;

class Posts extends Module {
  getPost(transaction, id) {
    return new Promise((resolve, reject) => {
      const postgresql = transaction['postgresql'];
      // for more information about the postgresql connection's capabilities, visit the docs: https://github.com/postgresqljs/postgresql
      postgresql.query(
        `SELECT * from posts WHERE \`id\` = ?`,
        [id],
        (err, results) => {
          if (err) { return reject(err); }
          resolve(results);
        }
      );
    });
  }
}

Step 4: Configuration

Requiring the ravel-postgresql-provider module will register a configuration parameter with Ravel which must be supplied via .ravelrc or app.set(). This configuration parameter matches the format defined by pg for Pools:

.ravelrc

{
  "postgresql options": {
    "host": "localhost",
    "port": 5432,
    "user": "my_user",
    "password": "a password",
    "database": "my_database",
    "connectionTimeoutMillis": 5000,
    "idleTimeoutMillis": 5000,
    "max": 10
  }
}

All options for a node-postres connection are supported, and are documented here.

Additional Notes

Multiple Simultaneous Providers

ravel-postgresql-provider also supports multiple simultaneous pools for different postgresql databases, as long as you name them:

app.js

const app = new require('ravel')();
const postgresqlProvider = require('ravel-postgresql-provider');
new postgresqlProvider(app, 'first postgresql');
new postgresqlProvider(app, 'second postgresql');
// ... other providers and parameters
app.init();
// ... the rest of your app

.ravelrc

{
  "first postgresql options": {
    "host": "localhost",
    "port": 5432,
    "user": "ravel",
    "password": "a password",
    "database": "myfirstdatabase",
    "connectionTimeoutMillis": 5000,
    "idleTimeoutMillis": 5000,
    "max": 10
  },
  "second postgresql options": {
    "host": "localhost",
    "port": 5432,
    "user": "ravel",
    "password": "another password",
    "database": "myseconddatabase",
    "connectionTimeoutMillis": 5000,
    "idleTimeoutMillis": 5000,
    "max": 10
  }
}

resources/posts_resource.js

const Ravel = require('ravel');
const Resource = Ravel.Resource;
const transaction = Resource.transaction;

class PostsResource extends Resource {
  // ...
  @transaction('first postgresql', 'second postgresql')
  get(ctx) {
    // can use ctx.transaction['first postgresql']
    // and ctx.transaction['second postgresql']
  }
}