Registry / web-framework / express-slonik

express-slonik

JSON →
library3.2.0jsnpmunverified

express-slonik provides an Express.js middleware for managing PostgreSQL transactions using the Slonik client library. It simplifies the integration of database transactions into Express route handlers, ensuring that all database operations within a request either commit successfully or roll back entirely. The current stable version is 3.2.0, released in October 2023. The project maintains a frequent release cadence, primarily to align with new major versions of its peer dependency, Slonik, adding support for recent Slonik versions shortly after their release. Its key differentiator is its zero-dependency approach (beyond Express and Slonik itself) and its focus on robust transaction management within the Express middleware pattern, including support for isolation levels and explicit transaction control across multiple handlers.

npm install express-slonik
INSTALL
IMPORT
SIG · EXPRESS-SLONIK
E
express-slonik
web-frameworkjavascriptv3.2.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createMiddleware
import createMiddleware from 'express-slonik';
import { createMiddleware } from 'express-slonik';
The primary export is a default export, not a named one.
TransactionContext
import { type TransactionContext } from 'express-slonik';
Type import for `req.transaction` context, useful for TypeScript users.
createMiddleware (CJS)
const createMiddleware = require('express-slonik').default;
const createMiddleware = require('express-slonik');
When using CommonJS `require`, access the default export via `.default`.

This example demonstrates basic usage, setting up an Express application with Slonik, initializing express-slonik middleware, and handling a GET request within a database transaction.

import express from 'express'; import { createPool, sql, NotFoundError } from 'slonik'; import createMiddleware from 'express-slonik'; import { z } from 'zod'; import { Server } from 'http'; const userSchema = z.object({ id: z.number().int(), name: z.string(), email: z.string().email(), }); export const createExpressApp = ({ app, pool }) => { const transaction = createMiddleware(pool); app.get( '/user/:id', // Starts the transaction. transaction.begin(), async (req, res, next) => { try { const userId = parseInt(req.params.id, 10); if (isNaN(userId)) { return res.status(400).json({ message: 'Invalid user ID' }); } const user = await req.transaction.one( sql.type(userSchema)`SELECT * FROM users WHERE users.id = ${userId}` ); res.json(user); } catch (error) { if (error instanceof NotFoundError) { res.status(404).json({ name: error.name, message: `User with given id (${req.params.id}) not found.`, }); return; } next(error); } }, // Optional: Explicitly commits the transaction. If omitted, it auto-commits on response send or rolls back on error. transaction.end() ); return app; }; /** * Gracefully attempt to shut down the server. */ async function shutdownHandler(server: Server, pool) { return async function () { server.close(); await pool.end(); // Ensure the Slonik pool is also terminated }; } (async function () { const app = express(); // Ensure DATABASE_URL is set in your environment variables, e.g., 'postgres://user:pass@host:port/database' const pool = await createPool(process.env.DATABASE_URL ?? 'postgres://user:password@localhost:5432/mydb'); const server = createExpressApp({ app, pool }).listen(8080, () => { console.log('Server listening on http://localhost:8080'); }); process .on('SIGTERM', shutdownHandler(server, pool)) .on('SIGINT', shutdownHandler(server, pool)); })();
Debug
Known issues
breakingVersion 3.0.0 introduced a breaking change by upgrading to Slonik v33. This change is not backward compatible with older Slonik versions due to API differences in Slonik itself.
fix
Ensure your project's `slonik` dependency is at version `33.x.x` or higher when upgrading to `express-slonik` v3.x.x. Specifically, peer dependency `slonik` should be `>=33.0.0 <38.0.0` for `express-slonik@3.2.0`.
affects: >=3.0.0
breakingVersion 2.0.0 dropped support for Slonik versions 29 and below, requiring Slonik v30+.
fix
Upgrade your `slonik` dependency to version `30.x.x` or higher before upgrading to `express-slonik` v2.x.x.
affects: >=2.0.0 <3.0.0
gotchaTransaction middleware relies on `req.transaction` being available. If other middleware modifies `req` in a conflicting way, it might cause issues.
fix
Ensure `express-slonik` middleware is placed appropriately in your Express middleware chain so that `transaction.begin()` runs before route handlers that need `req.transaction`, and no subsequent middleware overwrites `req.transaction`.
affects: >=1.0.0
gotchaFailing to explicitly call `transaction.end()` or having unhandled errors within a transactional route handler will automatically commit/rollback the transaction. While this is often desired, it can lead to unexpected behavior if manual control is intended.
fix
For explicit control, always include `transaction.end()` after your route logic. Implement robust error handling (`try-catch`) to manage transaction outcomes precisely, especially for non-critical errors that shouldn't roll back the entire transaction.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'one')
`req.transaction` is undefined, typically because `transaction.begin()` middleware was not run or `slonik` peer dependency is missing/incorrect.
fix
Ensure `transaction.begin()` is used before the route handler that accesses `req.transaction`. Verify `slonik` is installed and meets the `express-slonik` peer dependency requirements (e.g., `npm ls slonik` or `yarn why slonik`).
Error: Peer dependency "slonik" is not met. Expected ">=33.0.0 <38.0.0" but found "^32.0.0".
The installed `slonik` version does not satisfy the peer dependency range specified by `express-slonik`.
fix
Upgrade your `slonik` dependency to a compatible version, e.g., `npm install slonik@^37` or `yarn add slonik@^37`.
SyntaxError: Cannot use import statement outside a module
Attempting to use ES module `import` syntax in a CommonJS (`.js` without `"type": "module"` in `package.json`) Node.js environment.
fix
Either change your file to use CommonJS `require()` syntax (`const createMiddleware = require('express-slonik').default;`) or configure your project to use ES Modules by adding `"type": "module"` to your `package.json` and using `.mjs` file extensions if necessary.
Upgrade
Version history
3.2.0latest on npm
Audit
Dependencies
slonikrequiredCore database client for PostgreSQL transactions. express-slonik wraps Slonik's transaction capabilities.
expressrequiredThe middleware is built for the Express.js web framework.
Agent activity
6 hits · last 30 days
node
6
Resources
express-slonik — npm install express-slonik · libregistry