pg-replica

A tiny (240B) utility to enable pg read replicas

Allows you to easily pass your pg-driven queries though a master-replica architecture.
By doing this, you can divert all select queries to your read replica(s). This frees up your master node (aka, the writer) to handle all transactions, inserts, updates, and deletes. These changes will propagate (aka, replicate) to your replica(s) at the rate and discretion of your cluster.

When more than one replica is provided, the client will be chosen using a weighted round robin via the wrr package.
Each replica can be assigned a different weight (signifying capacity), but is given an equal weight distribution by default.

Important: The actual read-replication process is NOT handled by this library.
You must configure this within the database cluster directly.

This module is available in two formats:

• ES Module: dist/replica.mjs
• CommonJS: dist/replica.js

Install

$ npm install --save pg-replica

Usage

import { Pool } from 'pg';
import replica from 'pg-replica';
 
const writer = new Pool(...);
const reader1 = new Pool(...);
const reader2 = new Pool(...);
 
const DB = replica(writer, [reader1, reader2]);
assert(DB === writer); //=> true
 
await DB.query('insert into todos (title, completed) values ($1, $2);', ['hello', false]);
//=> uses writer
 
await DB.query('select * from todos;');
//=> uses reader1 OR reader2
 
DB.query('select * from todos where id = $1;', [5], (err, res) => {
    // Supports callback style too
});
//=> uses reader1 OR reader2

Clients

The pg-replica accepts any Pool or Client instance from the pg module.

Important: You must instantiate your writer and any readers before passing them to pg-replica.

When defining readers, you may pass a single instance or an array of instances. These, too, can be pg.Client or pg.Pool instances.

Additionally, read replicas (if more than one) will be chosen using a weighted round robin via the wrr package.
When unspecified, read replicas are given equal weight distributions.

import pg from 'pg';
import { Weighted } from '@lukeed/wrr';
 
type Client = pg.Client | pg.Pool;
type Replica = Client | Weighted<Client>;
 
declare function replica(writer: Client, readers?: Replica | Replica[]): Client;

API

replica(writer, readers?)

Returns: typeof writer

Always returns the writer instance.
This is the original pg.Pool or pg.Client you provided – except the query method is now wrapped.

Because the original client is returned, all flavors of client.query are supported. See pg documentation for more info.

writer

Type: Client
Required: true

A pg.Client or pg.Pool instance.

This writer will be used for all transactions and any non-select queries.

readers

Type: Client | Client[] | Weighted<Client> | Weighted<Client>[]
Required: false

The read replica(s) to use for any select queries.

When more than one replica is given, they are chosen via a weighted round robin – see Clients.
When zero replicas are provided, the writer is used for all queries.

License

MIT © Luke Edwards