PG-Scanner

PG-Scanner is a library which reports statistics about PostgreSQL databases.

TL;DR

const { Scanner } = require("pg-scanner");

const config = {
  host: "localhost",
  port: 5432,
  user: "postgres",
  password: "password",
  database: "mydb",
};

const scanner = new Scanner({ config });

(async () => {
  await scanner.init();
  scheduleScan(60 * 60 * 1000);
})();

function scheduleScan(delay) {
  setTimeout(async () => {
    const stats = await scanner.scan();
    dump(stats);
    scheduleScan(delay);
  }, delay).unref();
}

function dump(stats) {
  const serializer = (_, value) => typeof value === "bigint" ? value.toString() : value;
  const text = JSON.stringify(stats, serializer);
  console.log(text);
}

In this example, we create a new instance of the Scanner class with the database configuration. We intialise the scanner to establish a baseline, then re-scan once per hour, logging the statistics each time.

The custom serializer is required because JavaScripts maximum safe integer is less than the maximum value of a PostgreSQL integer, and the numerical stats have a type of BigInt.

We call unref to ensure the scheduled scans to not prevent your application from shutting down if the event loop is otherwise inactive, but if you are running the above script in a standalone process you may wish to remove this call.

Index

• Installation
• API
  • Constructor
  • init
  • scan
  • Stats
• Contributing
• License

Installation

To use the Scanner module in your project, follow these steps:

Install the Scanner module using npm or yarn:

npm install pg-scanner
# or
yarn add pg-scanner

Import the Scanner module into your JavaScript or TypeScript file:

const { Scanner } = require('pg-scanner');
// or
import { Scanner } from 'pg-scanner';

API

Scanner(options? : ScannerOptions)

Name	Required	Notes
config	No	A configuration object which is passed directly to node-pg. Alternatively, you can use environment variables if you prefer.
filter	No	A function for filtering out unwanted tables. It will be called with an object with a table and schema property and should return truthy if the table is to be included in the statistics. See the filter example for more details.

init() : Promise<void>

await scanner.init();

The init method is responsible for initialising the scanner wise baseline statistics. It will error if called repeatedly.

scan() : Promise<Stats>

await scanner.scan();

The scan method is responsible for retrieving and augmenting database statistics.

Stats

The stats returned by the scan is an array of objects with the following properties

Name	Type	Notes
schema	String	The schema to which the stats relate
table	String	The table to which the stats relate
sequentialScans	BigInt	The total number of sequential scans performed on the table
rowsScanned	BigInt	The total number of rows returned by the sequential scans
sequentialScansDelta	BigInt	The change in sequential scans since the last check
rowsScannedDelta	BigInt	The change in rows scanned since the last check

Contributing

Contributions to the Scanner module are welcome. If you find a bug, have a feature request, or want to improve the code, please open an issue or submit a pull request on GitHub.

License

This project is licensed under the MIT License. Feel free to use and modify the code as needed.