node-mimer

Node.js driver for Mimer SQL using the Mimer SQL C API.

Features

Native C++ bindings to the Mimer SQL C API via Node-API — no ODBC required
Prebuilt binaries for supported platforms — no compiler needed at install time
Promise-based API
Parameterized queries with ? placeholders (SQL injection safe)
Prepared statements for repeated execution
Result metadata with column names, types, and nullability
Support for all major Mimer SQL data types (including BLOB, NCLOB, UUID)
Transaction support (commit/rollback)
Structured error objects with Mimer error codes
Cursor support for streaming large result sets (for await)
Connection pooling with automatic acquire/release

Prerequisites

Node.js 18.0 or later
Mimer SQL 11.0 or later installed (the libmimerapi shared library must be available)

Installation

npm install @mimersql/node-mimer

Prebuilt binaries are included for supported platforms (linux-x64, linux-arm64, darwin-x64, darwin-arm64, win32-x64). On other platforms, the install script will compile from source using node-gyp (requires a C++ compiler and Mimer SQL development headers).

Verifying Mimer SQL is found

npm run check-mimer

Platform-specific library locations

Linux: libmimerapi.so (found via the standard library search path)

macOS: /usr/local/lib/libmimerapi.dylib

Windows: Automatically detected via MIMER_HOME environment variable, Windows Registry, or Program Files scan (highest version wins).

Usage

Basic Example

const { connect } = require('@mimersql/node-mimer');

async function example() {
  // Connect to database
  const client = await connect({
    dsn: 'mydb',
    user: 'SYSADM',
    password: 'password'
  });

  // Execute a query
  const result = await client.query('SELECT * FROM my_table');
  console.log(result.rows);

  // Close connection
  await client.close();
}

example();

Using Transactions

const { MimerClient } = require('@mimersql/node-mimer');

async function transactionExample() {
  const client = new MimerClient();

  try {
    await client.connect({
      dsn: 'mydb',
      user: 'SYSADM',
      password: 'password'
    });

    // Start transaction
    await client.beginTransaction();

    // Execute multiple statements
    await client.query("INSERT INTO accounts VALUES (1, 1000)");
    await client.query("INSERT INTO accounts VALUES (2, 500)");

    // Commit transaction
    await client.commit();

  } catch (error) {
    // Rollback on error
    await client.rollback();
    throw error;
  } finally {
    await client.close();
  }
}

Parameterized Queries

Use ? placeholders to pass parameters safely. This prevents SQL injection and lets the database optimize execution.

// INSERT with parameters
await client.query('INSERT INTO users VALUES (?, ?)', [1, 'Anna']);

// SELECT with a WHERE parameter
const result = await client.query(
  'SELECT * FROM users WHERE id = ?', [1]
);

// Multiple types are supported
await client.query(
  'INSERT INTO readings VALUES (?, ?, ?, ?)',
  [42, 'sensor-1', 3.14, true]
);

// NULL values
await client.query(
  'INSERT INTO users VALUES (?, ?)', [2, null]
);

Parameter types are mapped automatically:

JavaScript type	Mimer SQL binding
`number` (integer)	`INTEGER` or `BIGINT`
`number` (decimal)	`DOUBLE PRECISION`
`string`	`VARCHAR` / `NVARCHAR`
`boolean`	`BOOLEAN`
`null` / `undefined`	`NULL`
`Buffer`	`BINARY` / `BLOB`

Prepared Statements

For statements executed multiple times with different parameters, prepared statements avoid re-parsing the SQL on each call.

// Prepare once
const stmt = await client.prepare('INSERT INTO users VALUES (?, ?)');

// Execute many times with different parameters
await stmt.execute([1, 'Anna']);
await stmt.execute([2, 'Fredrik']);
await stmt.execute([3, 'Charlie']);

// Always close when done to release database resources
await stmt.close();

Prepared SELECT statements work the same way:

const stmt = await client.prepare(
  'SELECT * FROM users WHERE id = ?'
);

const r1 = await stmt.execute([1]);
console.log(r1.rows); // [{ id: 1, name: 'Anna' }]

const r2 = await stmt.execute([2]);
console.log(r2.rows); // [{ id: 2, name: 'Fredrik' }]

await stmt.close();

Cursors (Streaming Large Result Sets)

For large result sets, queryCursor() returns a cursor that fetches rows one at a time instead of loading everything into memory. The cursor implements the async iterator protocol, so you can use for await...of.

const cursor = await client.queryCursor('SELECT * FROM big_table');

for await (const row of cursor) {
  console.log(row);
  if (someDoneCondition) break;  // early exit closes the cursor automatically
}

You can also iterate manually with next() and close():

const cursor = await client.queryCursor(
  'SELECT * FROM orders WHERE status = ?', ['pending']
);

// Column metadata is available immediately
console.log(cursor.fields);
// [{ name: 'id', dataTypeCode: 50, dataTypeName: 'INTEGER', nullable: true }, ...]

let row;
while ((row = await cursor.next()) !== null) {
  process(row);
}
// cursor closes automatically when exhausted, or call cursor.close() to stop early

queryCursor() only accepts SELECT statements. DDL and DML statements are rejected with an error.

Connection Pool

For applications that need concurrent database access, the connection pool manages a set of reusable connections — lending them out on demand and returning them when done.

const { createPool } = require('@mimersql/node-mimer');

const pool = createPool({
  dsn: 'mydb',
  user: 'SYSADM',
  password: 'password',
  max: 10,               // maximum connections (default 10)
  idleTimeout: 30000,    // ms before idle connection is closed (default 30s)
  acquireTimeout: 5000,  // ms to wait for a connection (default 5s)
});

// Convenience — auto-acquires and releases a connection
const result = await pool.query('SELECT * FROM t WHERE id = ?', [1]);

// Cursor — connection held until cursor closes
const cursor = await pool.queryCursor('SELECT * FROM big_table');
for await (const row of cursor) { ... }
// connection auto-released when cursor closes or exhausts

// Explicit checkout — for transactions or multiple operations
const client = await pool.connect();
try {
  await client.beginTransaction();
  await client.query('INSERT INTO t VALUES (?, ?)', [1, 'a']);
  await client.commit();
} finally {
  client.release();   // return to pool (NOT client.close())
}

// Shutdown — closes all connections
await pool.end();

Result Metadata

SELECT queries return a fields array with column metadata alongside rows. This is available even when the query returns zero rows, letting you discover column names and types without needing actual data.

const result = await client.query('SELECT id, name FROM users');

console.log(result.fields);
// [
//   { name: 'id',   dataTypeCode: 50, dataTypeName: 'INTEGER', nullable: true },
//   { name: 'name', dataTypeCode: 63, dataTypeName: 'NVARCHAR',    nullable: false }
// ]

console.log(result.rows);
// [{ id: 1, name: 'Anna' }, ...]

Each field object contains:

Property	Type	Description
`name`	string	Column name
`dataTypeCode`	number	Numeric Mimer type code
`dataTypeName`	string	Human-readable SQL type (`INTEGER`, `DOUBLE PRECISION`, `BOOLEAN`, etc.)
`nullable`	boolean	Whether the column allows NULL values

Zero-row results still include full metadata:

const result = await client.query('SELECT * FROM users WHERE 1 = 0');
console.log(result.rowCount);       // 0
console.log(result.fields.length);  // 2 — column info is still available
console.log(result.fields[0].name); // 'id'

DML statements (INSERT, UPDATE, DELETE) do not return fields — only rowCount.

Prepared statements also return fields on each execute():

const stmt = await client.prepare('SELECT * FROM users WHERE id = ?');
const result = await stmt.execute([1]);
console.log(result.fields[0].dataTypeName); // 'INTEGER'
await stmt.close();

Error Handling

All errors from the Mimer SQL C API are thrown as JavaScript Error objects with structured properties:

try {
  await client.query('INSERT INTO nonexistent VALUES (1)');
} catch (err) {
  console.log(err.message);   // Human-readable description
  console.log(err.mimerCode);  // Numeric Mimer error code (e.g. -12200)
  console.log(err.operation);  // C API function that failed (e.g. "MimerExecute")
}

This lets you handle specific error conditions programmatically:

try {
  await client.query('CREATE TABLE t1 (id INTEGER)');
} catch (err) {
  if (err.mimerCode === -12517) {
    // Table already exists — ignore
  } else {
    throw err;
  }
}

Parameter binding errors also include structured properties:

try {
  // Wrong number of parameters
  await client.query('INSERT INTO users VALUES (?, ?)', [1]);
} catch (err) {
  console.log(err.mimerCode);  // 0 (validation error, not from Mimer API)
  console.log(err.operation);  // "BindParameters"
}

Data Type Mapping

Mimer SQL Type	JavaScript Type
INTEGER, SMALLINT	Number
BIGINT	Number
FLOAT, REAL, DOUBLE	Number
VARCHAR, NVARCHAR	String
CHARACTER, NCHAR	String
DATE, TIME, TIMESTAMP	String
DECIMAL, NUMERIC	String
UUID	String
BINARY, VARBINARY	Buffer
BLOB	Buffer
CLOB, NCLOB	String
BOOLEAN	Boolean
NULL	null

API Reference

MimerClient

`async connect(options)`

Connect to a Mimer SQL database.

Parameters:

options.dsn (string): Database name
options.user (string): Username
options.password (string): Password

`async query(sql, params)`

Execute a SQL statement with optional parameter binding.

Parameters:

sql (string): SQL statement, may contain ? placeholders
params (array, optional): Values to bind to ? placeholders

Returns: Result object:

For SELECT: { rows, rowCount, fields } — fields is an array of column metadata
For DML (INSERT/UPDATE/DELETE): { rowCount }
For DDL (CREATE/DROP/ALTER): { rowCount: 0 }

`async prepare(sql)`

Prepare a SQL statement for repeated execution.

Parameters:

sql (string): SQL statement with ? placeholders

Returns: PreparedStatement instance

PreparedStatement

`async execute(params)`

Execute the prepared statement with parameter values.

Parameters:

params (array, optional): Values to bind to ? placeholders

Returns: Result object:

For SELECT statements: { rows, rowCount, fields }
For DML statements: { rowCount }

`async close()`

Close the prepared statement and release its database resources. The statement cannot be used after calling close().

`async queryCursor(sql, params)`

Execute a SELECT query and return a cursor for row-at-a-time streaming.

Parameters:

sql (string): SELECT statement, may contain ? placeholders
params (array, optional): Values to bind to ? placeholders

Returns: ResultSet instance

Throws: Error if sql is a DDL or DML statement.

ResultSet

Returned by queryCursor(). Fetches rows one at a time from an open database cursor. Implements Symbol.asyncIterator for for await...of.

`fields`

Column metadata array (same format as query() results). Available immediately after creation.

`async next()`

Fetch the next row as a plain object, or null when all rows have been read. The cursor closes automatically when exhausted.

`async close()`

Close the cursor and release database resources. Safe to call multiple times. Called automatically when for await...of ends or breaks.

`async beginTransaction()`

Begin a new transaction.

`async commit()`

Commit the current transaction.

`async rollback()`

Rollback the current transaction.

`async close()`

Close the database connection.

`isConnected()`

Check if connected to database.

Returns: boolean

Pool

`createPool(options)`

Create a new connection pool.

Parameters:

options.dsn (string): Database name
options.user (string): Username
options.password (string): Password
options.max (number, optional): Maximum connections (default 10)
options.idleTimeout (number, optional): Ms before idle connection is closed (default 30000)
options.acquireTimeout (number, optional): Ms to wait for a connection (default 5000)

Returns: Pool instance

`async pool.query(sql, params)`

Acquire a connection, execute the query, and release the connection.

Returns: Result object (same as MimerClient.query())

`async pool.queryCursor(sql, params)`

Acquire a connection and open a cursor. The connection is automatically released when the cursor closes or is exhausted.

Returns: ResultSet instance

`async pool.connect()`

Check out a connection for multiple operations (e.g. transactions).

Returns: PoolClient instance

`async pool.end()`

Close all idle connections and reject pending waiters. Operations after end() will reject with an error.

PoolClient

Returned by pool.connect(). Delegates query(), queryCursor(), prepare(), beginTransaction(), commit(), and rollback() to the underlying MimerClient.

`release()`

Return the connection to the pool. Always call this instead of close(). Safe to call multiple times.

Helper Functions

`async connect(options)`

Create and connect a new MimerClient instance.

Returns: Connected MimerClient instance

Testing

Tests use the Node.js built-in test runner (node:test) and are split into focused files by category:

test/
  helper.js                        # Shared utilities (createClient, dropTable)
  connection.test.js               # Connect, isConnected, close
  basic-queries.test.js            # DDL, DML, SELECT
  transactions.test.js             # beginTransaction, commit, rollback
  result-metadata.test.js          # fields array, properties, edge cases
  unicode.test.js                  # NVARCHAR round-trip, Unicode WHERE
  parameterized-queries.test.js    # ? params, types, NULL, mismatch error
  prepared-statements.test.js      # prepare/execute/close lifecycle
  cursor.test.js                   # queryCursor, for-await-of, early break
  error-handling.test.js           # Structured errors (mimerCode, operation)
  pool.test.js                     # Connection pool, PoolClient, auto-release

# Run all tests (requires a running Mimer SQL instance)
npm test

# Run a single test file
node --test test/unicode.test.js

Architecture

Application (JavaScript)
        |
        | require('@mimersql/node-mimer')
        v
JavaScript Wrapper (Promise-based)
  index.js, lib/client.js, lib/prepared.js,
  lib/resultset.js, lib/pool.js
        |
        | lib/native.js (loads native addon)
        v
C++ Native Addon (Node-API)
  src/connection.cc, src/statement.cc,
  src/resultset.cc, src/helpers.cc
        |
        | C API calls
        v
Mimer SQL C API (libmimerapi.so)
        |
        v
Mimer SQL Database

The package ships prebuilt .node binaries for supported platforms via prebuildify. At install time, prebuild-install downloads the matching binary. If no prebuilt is available, the addon is compiled from source using node-gyp. The native addon uses Node-API (N-API v8), so binaries are stable across Node.js versions without recompilation.

Mimer SQL C API Functions Used

MimerBeginSession8() - Establish database connection
MimerEndSession() - Close connection
MimerBeginStatement8() - Prepare SQL statements
MimerExecuteStatement8() - Execute DDL statements directly
MimerOpenCursor() / MimerFetch() - Fetch result rows
MimerGetString8(), MimerGetInt32(), etc. - Get column values
MimerSetString8(), MimerSetInt32(), etc. - Bind parameter values
MimerSetLob() / MimerSetBlobData() / MimerSetNclobData8() - Write LOBs
MimerGetLob() / MimerGetBlobData() / MimerGetNclobData8() - Read LOBs
MimerBeginTransaction() / MimerEndTransaction() - Transaction control
MimerGetError8() - Error handling

File Structure

node-mimer/
├── src/                          # C++ native addon
│   ├── mimer_addon.cc           # Module entry point
│   ├── connection.cc/h          # Connection class
│   ├── statement.cc/h           # Prepared statement class
│   ├── resultset.cc/h           # Cursor/streaming result set class
│   └── helpers.cc/h             # Parameter binding, row fetching, errors
│
├── lib/                          # JavaScript modules
│   ├── native.js                # Loads native addon via node-gyp-build
│   ├── client.js                # MimerClient, connect()
│   ├── prepared.js              # PreparedStatement
│   ├── resultset.js             # ResultSet (cursor wrapper)
│   └── pool.js                  # Pool, PoolClient
│
├── prebuilds/                    # Prebuilt binaries (per platform)
│   └── linux-x64/               # Example: Linux x64 binary
│
├── scripts/
│   ├── check-mimer.js           # Verify Mimer installation
│   └── find-mimer-windows.js    # Auto-detect Mimer on Windows
│
├── binding.gyp                   # Native addon build configuration
├── index.js                      # Re-exports from lib/
├── index.d.ts                    # TypeScript type definitions
├── package.json
├── README.md
│
└── test/
    ├── helper.js                # Shared test utilities
    └── *.test.js                # Test suites (node:test)

License

MIT

Contributing

Contributions are welcome! Please submit pull requests or open issues on GitHub.

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github/workflows		.github/workflows
doc		doc
lib		lib
scripts		scripts
src		src
test		test
.gitignore		.gitignore
LICENSE		LICENSE
OVERVIEW.md		OVERVIEW.md
README.md		README.md
ZERO_CONFIG.md		ZERO_CONFIG.md
binding.gyp		binding.gyp
index.d.ts		index.d.ts
index.js		index.js
package.json		package.json

License

mimersql/node-mimer

Folders and files

Latest commit

History

Repository files navigation

node-mimer

Features

Prerequisites

Installation

Verifying Mimer SQL is found

Platform-specific library locations

Usage

Basic Example

Using Transactions

Parameterized Queries

Prepared Statements

Cursors (Streaming Large Result Sets)

Connection Pool

Result Metadata

Error Handling

Data Type Mapping

API Reference

MimerClient

async connect(options)

async query(sql, params)

async prepare(sql)

PreparedStatement

async execute(params)

async close()

async queryCursor(sql, params)

ResultSet

fields

async next()

async close()

async beginTransaction()

async commit()

async rollback()

async close()

isConnected()

Pool

createPool(options)

async pool.query(sql, params)

async pool.queryCursor(sql, params)

async pool.connect()

async pool.end()

PoolClient

release()

Helper Functions

async connect(options)

Testing

Architecture

Mimer SQL C API Functions Used

File Structure

License

Contributing

References

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`async connect(options)`

`async query(sql, params)`

`async prepare(sql)`

`async execute(params)`

`async close()`

`async queryCursor(sql, params)`

`fields`

`async next()`

`async close()`

`async beginTransaction()`

`async commit()`

`async rollback()`

`async close()`

`isConnected()`

`createPool(options)`

`async pool.query(sql, params)`

`async pool.queryCursor(sql, params)`

`async pool.connect()`

`async pool.end()`

`release()`

`async connect(options)`

Packages