Allow enabling the RETURNING clause via the knex configuration

Branch: feat/knex-returning-config (head: nm3xyz/feathers, commit 173ad8f)
Repo: feathersjs/feathers — base dove @ 8c007bc (v5.0.53, the repository default branch)

Summary

• Tell us about the problem your pull request is solving.

KnexAdapter._create decides whether to use the RETURNING clause in the insert statement with a hard-coded list of clients:

const RETURNING_CLIENTS = ['postgresql', 'pg', 'oracledb', 'mssql', 'sqlite3']
...
const returning = RETURNING_CLIENTS.includes(client.driverName) ? [this.id] : []

Any database that does support RETURNING but is not in that list — Firebird via knex-firebird-dialect is a concrete example — can not get the id back from the insert. The adapter then falls back to using the returned row value / an additional _get, which either does not work or costs an extra query.

This PR lets the knex configuration opt in (or out of the default) with a returning boolean:

const db = knex({
  client: knexFirebirdDialect,
  connection: { /* ... */ },
  returning: true
})

Implementation

export const supportsReturning = (client: Knex.Client) => {
  const { returning } = (client.config || {}) as ReturningConfig

  return Boolean(returning) || RETURNING_CLIENTS.includes(client.driverName)
}

• A truthy client.config.returning enables the clause.
• If it is not set or falsy, the existing RETURNING_CLIENTS check is used, so behaviour for every currently supported database is unchanged.

_create now calls supportsReturning(client) instead of the inline check.

Tests

Added a returning clause support suite in packages/knex/test/index.test.ts (no database required, the client and the insert are stubbed):

• default list is used when the option is not set (postgresql, oracledb, sqlite3 → true; node-firebird-driver-native → false)
• the option enables it for a client outside the default list
• a falsy option falls back to the default list (false + Firebird → false, false + PostgreSQL → true)
• _create actually passes [id] to insert when the option is enabled, and [] when it is not

Full package suite: 336 passing, 20 pending (sqlite), plus eslint and prettier clean on the changed files.

Docs

Added a short "RETURNING clause support" section to docs/api/databases/knex.md, documenting the returning knex option and the Firebird example.

Other Information

• Are there any open issues that are related to this? — None found; this came up while porting a Feathers service to Firebird.
• Is this PR dependent on PRs in other repos? — No.

Files changed: packages/knex/src/adapter.ts, packages/knex/test/index.test.ts, docs/api/databases/knex.md (99 insertions, 2 deletions).