TypeScript icon, indicating that this package has built-in type declarations

0.1.1 • Public • Published

pg-replica build status codecov

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


$ npm install --save pg-replica


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


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;


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.


Type: Client
Required: true

A pg.Client or pg.Pool instance.

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


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.


MIT © Luke Edwards


npm i pg-replica

DownloadsWeekly Downloads






Unpacked Size

7.55 kB

Total Files


Last publish


  • lukeed