Introduction

ship-hold is a small and fast data access framework for Postgres relational database, developed for the Nodejs environment.

It is based around intuitive SQL query builders which mirror closely the SQL syntax while keeping the flexibility functions may have. It also allows you to create convenient services and relations between them in order to easily fetch related resources (aka eager loading). It is actually the only library I know of which has it right when it comes to pagination and nested pagination!

It differs a lot from other popular libraries so called ORM such Sequelize or Bookshelf. They come with a wide range of features: schema management, migrations, validations, different sql dialects, model instances, etc. But it comes at the price of very complex API's / code base (we are usually talking about more than 200 API functions and more than 10/20 thousands source lines of code). Ship-hold, however, focuses on a limited set of features while remaining extensible.

Getting started

Installation

run in your terminal npm install --save ship-hold (assuming you have npm installed)

initialisation

Pass database connection information to the ship-hold factory. Every option the driver pg takes can be passed.

const {shiphold} = require('ship-hold');
const sh = shiphold({
    host: '127.0.0.1',
    user: 'docker',
    password: 'docker',
    database: 'dev'
});

That's it! You can start to query your database.

sh.select()
    .from('users')
    .where('age', '>', 42)
    .and('first_name', 'ILIKE', 'lorenzo')
    .run()
    .then(users => {
        console.table(users);
    });

How to read this documentation

We recommend first to read the documentation in the order shown by the table of content. Once you are familiar with the different sections you can jump directly from one topic to another one as one would do in a API reference document.

It is not mandatory to read the performances section in order to use ship-hold. However we highly recommend it to understand how complex queries are generated and when they should be avoided.

All the examples in the documentation use a database defined by the initialization script in the annexes section