# knex-dynamic-connection

> Adds support for dynamically returning connection config for knex queries

Latest version **5.1.1** (published 2026-09-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install knex-dynamic-connection
pnpm add knex-dynamic-connection
yarn add knex-dynamic-connection
bun add knex-dynamic-connection
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 5.1.1 |
| Published | 2026-09-01 |
| First published | 2019-08-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=24.0.0 |
| Dependencies | 2 |
| Unpacked size | 24.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 39 |
| Author | virk |
| Maintainers | virk |
| Keywords | knex, db |

## Links

- npm: https://www.npmjs.com/package/knex-dynamic-connection
- Repository: https://github.com/thetutlage/knex-dynamic-connection
- Homepage: https://github.com/thetutlage/knex-dynamic-connection#readme
- Issues: https://github.com/thetutlage/knex-dynamic-connection/issues
- npm.io page: https://npm.io/package/knex-dynamic-connection

## Dependencies (2)

- [knex](https://npm.io/package/knex.md) 3.3.0
- [debug](https://npm.io/package/debug.md) ^4.4.3

## Alternatives

- [angular-pipes](https://npm.io/package/angular-pipes.md) — 5.6K weekly downloads
- [@ng-web-apis/midi](https://npm.io/package/@ng-web-apis/midi.md) — 2.6K weekly downloads
- [happn-3](https://npm.io/package/happn-3.md) — 1.6K weekly downloads
- [@opensip-cli/lang-go](https://npm.io/package/@opensip-cli/lang-go.md) — 1.2K weekly downloads
- [mongoose-typescript](https://npm.io/package/mongoose-typescript.md) — 85 weekly downloads

## Recent versions

- 5.1.1 (latest) — 2026-09-01
- 4.0.0-next.1 (next) — 2026-03-23
- 5.1.0 — 2026-05-08
- 5.0.1 — 2026-03-28
- 5.0.0 — 2026-03-23
- 4.0.0 — 2026-03-23
- 4.0.0-next.0 — 2025-12-26
- 3.2.0 — 2024-06-14
- 3.1.1 — 2023-10-20
- 3.1.0 — 2023-07-11
- 3.0.1 — 2023-05-22
- 3.0.0 — 2022-05-06
- 2.1.3 — 2022-03-02
- 2.1.2 — 2022-02-28
- 2.1.1 — 2021-06-20
- … 9 more at https://npm.io/package/knex-dynamic-connection/versions

## README

# Knex Dynamic Connection

This module is meant to patch knex and add support for defining dynamic connection configuration.

[![gh-workflow-image]][gh-workflow-url] [![npm-image]][npm-url] ![](https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript)

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
## Table of contents

- [Why you need it?](#why-you-need-it)
- [Is it reliable?](#is-it-reliable)
- [How does it actually work?](#how-does-it-actually-work)
- [Will this work in the future?](#will-this-work-in-the-future)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Why you need it?
Knex.js doesn't have inbuilt support for read/write connections. One can create two seperate instances of knex for read and write, but that still doesn't completely solve the problem. For example:

```js
const Knex = require('knex')

const writeConfig = {
  client: 'pg',
  connection: {
  }
}
const writer = Knex(writeConfig)

const readConfig = {
  client: 'pg',
  connection: {
  }
}
const reader = Knex(readConfig)
```

Now, if you want to use multiple servers for read operations, you cannot do that, since knex.js allows only one connection server and will pool connections within that server.

**Following is not possible**

```js
const readConfig = {
  client: 'pg',
  connection: [
    {
      host: ''
    },
    {
      host: ''
    }
  ]
}
```

With the help of this module, you can make knex create a connection using the dynamic config for every query.

```sh
npm i knex-dynamic-connection
```

```js
const Knex = require('knex')
const { patchKnex } = require('knex-dynamic-connection')

const readConfig = {
  client: 'pg',
  connection: {},
  replicas: [
    {
      host: '',
    },
    {
      host: '',
    }
  ],
}

const knex = Knex(readConfig)
let roundRobinCounter = 0

patchKnex(knex, (originalConfig) => {
  const node = roundRobinCounter++ % originalConfig.replicas.length
  return originalConfig.replicas[node]
})
```

The `patchKnex` method overwrites the `acquireRawConnection` on all the dialects and make them fetch the config from your callback vs reading it from a static source.

## Is it reliable?
Yes!

1. I have copied the code of `acquireRawConnection` from the knex codebase and have just made one line of change to read the config from a different source.
2. I have written tests for `select`, `insert`, `transactions` and `schema` methods.
3. The code is tested against `mssql`, `mysql`, `mysql2` and `pg`.
4. The connection is still managed inside the pool, so don't worry about any extra maintaince overhead.

## How does it actually work?
Knex.js makes use of [tarn.js](https://github.com/vincit/tarn.js/) for managing pool resources and everytime pool needs a connection, knexjs calls [acquireRawConnection](https://github.com/tgriesser/knex/blob/master/lib/client.js#L258) on the dialect in use.

The dialect creates a new connection to the database server, **but uses static configuration**. I have just added a patch, which will rely on your closure to return the config vs using the same static config all the time.

## Will this work in the future?
I am using Knex.js to write the ORM of https://adonisjs.com/ and will keep a close eye on the releases of Knex to make sure that I incorporate any changes made of the underlying code and keep this module upto date. If knex.js team plans to re-write the entire codebase (which is less likely to happen), then I will pitch this change to be a first class citizen.

## Can I help?
Yes, there are currently no tests for oracle. It will be great, if you can help set it up using docker

[gh-workflow-image]: https://img.shields.io/github/actions/workflow/status/thetutlage/knex-dynamic-connection/test.yml?style=for-the-badge
[gh-workflow-url]: https://github.com/thetutlage/knex-dynamic-connection/actions/workflows/test.yml "Github action"

[npm-image]: https://img.shields.io/npm/v/knex-dynamic-connection.svg?style=for-the-badge&logo=npm
[npm-url]: https://npmjs.org/package/knex-dynamic-connection "npm"

---
_Source: https://npm.io/package/knex-dynamic-connection · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._