Slonik Node.js PostgreSQL Client

Slonik is a battle-tested Node.js PostgreSQL client designed with strict types, detailed logging, and assertions. It is built on several core principles:

• Promotes writing raw SQL: Instead of using an abstraction layer, Slonik encourages using actual SQL.
• Discourages ad-hoc dynamic generation of SQL: It aims to prevent the unsafe and complex generation of SQL strings at runtime.

Key features include runtime validation, safe connection and transaction handling, transaction nesting, query retrying, and a rich set of interceptors (middlewares).

Slonik is a high-level abstraction built on top of pg. Unlike pg, which is unopinionated and minimal, Slonik provides convenience methods for building queries and querying data.

Key differences from pg-promise include:

• Security: Slonik does not allow raw text queries; all queries must be constructed using sql tagged template literals to protect against unsafe value interpolation.
• Extensibility: Slonik implements an interceptor API (middleware) to modify connection handling, override queries, and modify results (e.g., field name transformation or query logging).

Comparison mapping for developers migrating from pg-promise:

• Use Slonik tagged template value expressions instead of formatting filters.
• Use slonik-sql-tag-raw instead of Query files.
• Use pool.connect() instead of Tasks.
• Use interceptors instead of Events.

Use createPool to initialize a connection pool. You can run queries directly on the pool for single queries, or use pool.connect() to check out a connection for multiple queries that must share the same backend.

Terminate the pool

Use pool.end() to end idle connections and prevent new ones from being created. This returns a promise that resolves when all connections are ended. Note that pool.end() does not terminate active connections or transactions.

import { createPool, sql } from "slonik";
import { createPgDriverFactory } from "@slonik/pg-driver";

const pool = await createPool("postgres://", {
  driverFactory: createPgDriverFactory(),
});

const main = async () => {
  await pool.query(sql.typeAlias("id")`
    SELECT 1 AS id
  `);

  await pool.end();
};

main();

You can run a PostgreSQL instance configured with SSL for testing purposes using the provided Docker setup. Build the image and then run the container, mapping the internal port 5432 to host port 5433.

docker build -t slonik-ssl-test .
docker run --name slonik-ssl-test --rm -it -e POSTGRES_PASSWORD=postgres -p 5433:5432 slonik-ssl-test

The slonik-interceptor-query-logging package allows you to log Slonik queries. To see logs in your console, you must set the ROARR_LOG=true environment variable. The interceptor uses Roarr for logging.

To use it, include the interceptor returned by createQueryLoggingInterceptor() in your Slonik pool configuration.

import { createPool } from "slonik";
import { createQueryLoggingInterceptor } from "slonik-interceptor-query-logging";

const interceptors = [createQueryLoggingInterceptor()];

const pool = createPool("postgres://", {
  interceptors,
});

await pool.any(sql`
  SELECT
    id,
    code_alpha_2
  FROM country
`);

Use eslint-plugin-slonik to validate Slonik SQL queries against your database schema at lint time. This helps catch:

• References to non-existent tables and columns.
• Type mismatches between query results and Zod schemas.
• Other common SQL mistakes before they reach runtime.