gajus /slonik

A Node.js PostgreSQL client with runtime and build time type safety, and composable SQL.

★ 4,937⑂ 156👁 26⑃ 360● 411▤ 1,768
TypeScriptNOASSERTIONCreated 2017-03-24
Download: [email protected][email protected] ↓49.13.02026-11-06
+0
Daily
4,937
stars
156
forks
26
watchers
360
prs
411
issues
1,768
releases

README

Slonik





A battle-tested Node.js PostgreSQL client with strict types, detailed logging and assertions.

!Tailing Slonik logs

 Principles

- Promotes writing raw SQL.
- Discourages ad-hoc dynamic generation of SQL.

Read: Stop using Knex.js

 Features

- Runtime validation.
- Assertions and type safety.
- Safe connection handling.
- Safe transaction handling.
- Safe value interpolation.
- Transaction nesting.
- Transaction events.
- Transaction retrying.
- Query retrying.
- Detailed logging.
- Asynchronous stack trace resolution.
- Middlewares.
- Mapped errors.
- ESLint plugin.

 Contents

- Slonik
  - Principles
  - Features
  - Contents
  - About Slonik
    - Battle-Tested
    - Origin of the name
    - Repeating code patterns and type safety
    - Protecting against unsafe connection handling
    - Protecting against unsafe transaction handling
    - Protecting against unsafe value interpolation
  - Usage
    - Connection URI
    - Create connection
    - End connection pool
    - Describing the current state of the connection pool
    - API
    - Default configuration
    - Checking out a client from the connection pool
    - Events
  - How are they different?
    - pg vs slonik
    - pg-promise vs slonik
    - postgres vs slonik
  - Type parsers
    - Built-in type parsers
    - Overriding type parsers for a sql tag
  - Interceptors
    - Interceptor methods
    - Community interceptors
  - Recipes
    - Inserting large number of rows
    - Routing queries to different connections
    - Building Utility Statements
    - Inserting vector data
  - Runtime validation
    - Motivation
    - Result parser interceptor
    - Example use of sql.type
    - Performance penalty
    - Unknown keys
    - Handling schema validation errors
    - Inferring types
    - Transforming results
  - sql tag
    - Type aliases
    - Typing sql tag
  - Value placeholders
    - Tagged template literals
    - Manually constructing the query
    - Nesting sql
  - Query building
    - sql.and
    - sql.array
    - sql.binary
    - sql.date
    - sql.fragment
    - sql.identifier
    - sql.interval
    - sql.join
    - sql.json
    - sql.jsonb
    - sql.list
    - sql.or
    - sql.literalValue
    - sql.timestamp
    - sql.unnest
    - sql.unsafe
    - sql.uuid
    - sql.prepared
  - Tips
    - Prefer sql.and, sql.or, and sql.list over sql.join
    - Compile Zod schemas at build time
    - Hoist Zod schemas with babel-plugin-zod-hoist
    - Validate SQL queries with eslint-plugin-slonik
  - Query methods
    - any
    - anyFirst
    - exists
    - many
    - manyFirst
    - maybeOne
    - maybeOneFirst
    - one
    - oneFirst
    - query
    - record
    - stream
    - transaction
  - Utilities
    - parseDsn
    - stringifyDsn
  - Error handling
    - Original node-postgres error
    - Handling BackendTerminatedError
    - Handling CheckIntegrityConstraintViolationError
    - Handling ConnectionError
    - Handling DataIntegrityError
    - Handling ForeignKeyIntegri

Top issues

Discussions

Latest release

[email protected] [email protected] 2026-11-06
Patch Changes

- Updated dependencies []:
  - @slonik/[email protected]

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON