@nicolaech/n8n-nodes-ibmi-db2-mapepire

A policy-controlled n8n community node for Db2 for IBM i using the official
Mapepire Node.js client.

This is an independent Mapepire-based implementation maintained under the npm
scope @nicolaech. It is not a fork, continuation, or distribution of any
ODBC-based n8n package. The distinct basename n8n-nodes-ibmi-db2-mapepire
avoids npm ownership conflicts and gives the implementation a distinct n8n package identity.

Version 0.2.4 keeps the published community package free of package-owned npm
runtime dependencies and adds a Node.js 26-safe peer-install layout. During the
build, @ibm/mapepire-js@0.6.1 is copied into dist together with its
Apache-2.0 license and a SHA-256 manifest. n8n-workflow remains the host API
peer, but it is marked optional so npm does not install a second n8n dependency
tree inside the community-node directory. This avoids pulling isolated-vm
into PPC64LE Node.js 26 installations.

Supported operations

The node deliberately exposes only:

• SELECT
• INSERT ... VALUES
• UPDATE
• restricted CREATE TABLE

There is no unrestricted “execute SQL” operation.

Security policy

The node enforces the rules from the original IBM i SQL container project:

• one statement only; comments and semicolons are rejected
• the selected operation must match the first SQL verb
• all tables and views must be written as SCHEMA.OBJECT
• reads are limited to SQL_ALLOWED_READ_SCHEMAS
• writes are limited to one SQL_ALLOWED_WRITE_SCHEMA; blank disables writes
• parenthesized functions must be unqualified and explicitly allowlisted
• schema-qualified routines and SQL table functions are rejected
• dangerous functions such as QCMDEXC, IFS writes, HTTP writes, and email
  functions are rejected even when allowlisted
• DELETE, MERGE, ALTER, DROP, TRUNCATE, CALL, GRANT, REVOKE,
  transaction control, dynamic SQL, and command execution are rejected
• INSERT ... SELECT, CTE-based INSERT, SELECT INTO, and data-change table
  references are rejected
• UPDATE requires a top-level WHERE, unless the visible full-table override
  is deliberately enabled
• CREATE TABLE permits explicit columns, identity columns, primary keys, and
  unique constraints, while rejecting CTAS, LIKE, foreign references,
  generated expressions, table functions, and trailing physical options
• protected IBM system schemas can never be write targets
• placeholder count, scalar parameters, and batch size are validated

Writes are never retried after a transport failure because Db2 may already have
committed. A SELECT may be retried once after invalidating its process-local
pool.

The SQL validator is defence in depth. Use a dedicated IBM i profile with only
the object authorities required by the workflow.

Requirements

• self-hosted n8n with community packages enabled
• a Mapepire server reachable from n8n, normally on TCP port 8076
• an IBM i user profile with least privilege
• a Node.js runtime supported by the installed n8n release

The package is designed for self-hosted n8n and sets n8n.strict=false because
it optionally reads a CA certificate from a local container path. It is not
presented as an n8n Cloud verified node.

Credential mapping

The credential also defines maximum SELECT rows, page size, maximum batch rows,
SELECT retry behavior, date format, and decimal separator.

X_API_KEY is intentionally absent. It protected the previous HTTP service;
the direct node exposes no HTTP API. n8n authentication, encrypted credential
permissions, and IBM i authority now form the access boundary.

Clean build and complete verification

Always extract the release into a new directory. Do not reuse an old
node_modules directory or lock file. Run the official lint/build toolchain
with Node.js 24; the packed JavaScript artifact is then tested separately with
Node.js 26.5.0 before deployment.

npm run release:build

On the first connected build, the script uses npm install and generates
package-lock.json. Commit that lock file before enabling GitHub CI. Subsequent
runs use npm ci automatically.

To deliberately regenerate the lock file:

RESET_LOCKFILE=1 npm run release:build

The release command performs:

1. exact @n8n/node-cli 0.41.2 verification
2. high/critical audit of the development toolchain
3. isolated audit of @ibm/mapepire-js@0.6.1
4. official n8n-node lint
5. official n8n-node build
6. 35 automated policy and execution tests
7. TypeScript verification
8. built-package policy and vendor-manifest verification
9. production-package audit excluding the host-provided peer
10. npm tarball creation, content inspection, checksum verification, and compiled entry-point smoke loading

The outputs are:

release/nicolaech-n8n-nodes-ibmi-db2-mapepire-0.2.4.tgz
release/nicolaech-n8n-nodes-ibmi-db2-mapepire-0.2.4.tgz.sha256

Do not run npm audit fix --force. It can replace the pinned n8n CLI or alter
the reviewed Mapepire version. Update dependencies deliberately and rerun the
complete release pipeline.

Test the tarball in an existing Podman n8n container

Copy the built tarball:

podman cp \
  release/nicolaech-n8n-nodes-ibmi-db2-mapepire-0.2.4.tgz \
  n8n:/tmp/nicolaech-n8n-nodes-ibmi-db2-mapepire-0.2.4.tgz

Install it as the same user that runs n8n:

podman exec -u node n8n sh -lc '
  set -eu
  mkdir -p /home/node/.n8n/nodes
  cd /home/node/.n8n/nodes
  [ -f package.json ] || npm init -y >/dev/null
  npm uninstall @nicolaech/n8n-nodes-ibmi-db2-mapepire --no-audit --no-fund || true
  npm install /tmp/nicolaech-n8n-nodes-ibmi-db2-mapepire-0.2.4.tgz \
    --omit=dev --omit=peer --no-audit --no-fund
'

podman restart n8n

No separate @ibm/mapepire-js or n8n-workflow installation is needed. The
official Mapepire client is already present inside the node tarball, and n8n
provides n8n-workflow at runtime.

Verify the installed package:

podman exec -u node n8n node -e '
const p = require("/home/node/.n8n/nodes/node_modules/@nicolaech/n8n-nodes-ibmi-db2-mapepire/package.json");
console.log(p.name, p.version, p.dependencies, p.peerDependencies, p.peerDependenciesMeta);
'

Expected package metadata:

@nicolaech/n8n-nodes-ibmi-db2-mapepire 0.2.4 undefined { n8n-workflow: '*' } { n8n-workflow: { optional: true } }

Search for IBM i Db2 (Mapepire) in the editor, create an IBM I Mapepire
API credential, test the connection, and begin with a read-only credential by
leaving the write schema blank.

Example SELECT

Credential policy:

Allowed Read Schemas: SYSIBM,APPDATA
Allowed Write Schema: <blank>
Allowed SQL Functions: UPPER

SQL:

SELECT CUSTOMER_ID, UPPER(CUSTOMER_NAME) AS CUSTOMER_NAME
FROM APPDATA.CUSTOMERS
WHERE CUSTOMER_ID = ?

Parameters:

[123]

Publishing

After npm run release:build succeeds and the generated lock file is committed, publish the exact verified tarball:

npm publish release/nicolaech-n8n-nodes-ibmi-db2-mapepire-0.2.4.tgz \
  --provenance --access public

The package can then be installed from Settings → Community Nodes using:

@nicolaech/n8n-nodes-ibmi-db2-mapepire

See docs/PUBLISHING.md for GitHub Actions and npm trusted publishing.

Workflows created with the earlier local unscoped package must change the node
type from n8n-nodes-ibmi-mapepire.ibmiMapepire to
@nicolaech/n8n-nodes-ibmi-db2-mapepire.ibmiMapepire; see
docs/PACKAGE-IDENTITY.md.

Verification scope

The included automated suite validates the SQL policy, configuration mapping,
pool construction, paging, truncation, SELECT retry, write no-retry behavior,
pool-disabled behavior, batch parameters, failed-pool recovery, queue timeout,
and package structure. Final certification still requires a live disposable
IBM i schema and reachable Mapepire server; see docs/TESTING.md.

License

This project is MIT licensed. The bundled @ibm/mapepire-js runtime is
Apache-2.0 licensed; its license and bundle manifest are included in the built
package under dist/vendor-licenses.