mysql2-ssh

library1.2.0jsnpmunverified

Provides a wrapper around mysql2 to create a MySQL connection over an SSH tunnel using ssh2. Enables async/await patterns for establishing the tunnel and executing queries. Current version 1.2.0, forks grrr-amsterdam/mysql-ssh with modern async support. Key differentiator: simple Promise-based API versus older callback-based alternatives. Key differentiator: simple Promise-based API versus older callback-based alternatives. Requires both mysql2 and ssh2 as peer dependencies. Release cadence is low, mainly bug fixes.

database devops

npm install mysql2-ssh

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MYSQL2-SSH

mysql2-ssh

databasejavascriptv1.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

getConnection

✓ import { getConnection } from 'mysql2-ssh'

✗ const getConnection = require('mysql2-ssh').getConnection

Package is ESM-only (type: module). CommonJS require works but triggers warning; use import or dynamic import.

✓ import { close } from 'mysql2-ssh'

close is a named export, not a method on the connection. Must be called to cleanly close the SSH tunnel.

getConnection and close

✓ const { getConnection } = await import('mysql2-ssh')

✗ const { getConnection } = require('mysql2-ssh')

In CJS projects, use dynamic import() instead of require() to avoid ESM/CJS mismatch.

Demonstrates async/await usage for creating an SSH tunnel to a MySQL database, running a query, and closing the tunnel.

import { getConnection, close } from 'mysql2-ssh'; const sshConfig = { host: process.env.SSH_HOST ?? '', username: process.env.SSH_USER ?? '', privateKey: require('fs').readFileSync(process.env.SSH_KEY_PATH ?? '') }; const dbConfig = { host: 'localhost', port: 3306, user: process.env.DB_USER ?? '', password: process.env.DB_PASS ?? '', database: process.env.DB_NAME ?? '' }; async function query() { try { const connection = await getConnection(sshConfig, dbConfig); const [rows] = await connection.query('SELECT 1 AS result'); console.log(rows); } finally { await close(); // Must close the tunnel after use } } query();

Debug

Known issues

gotchaCalling close() is mandatory to release the SSH tunnel; failing to do so keeps the tunnel open indefinitely.

fix

Always call await close() in a finally block after your queries.

affects: >=1.0.0

gotchaThe package is ESM-only; using require() may work but can cause instability in pure CJS projects.

fix

Use dynamic import: const { getConnection } = await import('mysql2-ssh')

affects: >=1.0.0

deprecatedNode.js versions <12 are not supported due to async/await usage.

fix

Upgrade Node.js to >=12.

affects: >=1.0.0

gotchaSSH private key must be in OpenSSH format; other formats may cause errors.

fix

Convert key to OpenSSH format using ssh-keygen -p -m PEM -f keyfile

affects: >=1.0.0

Errors

Common errors & fixes

Error: getConnection is not a function

Using require() in CJS instead of import or dynamic import()

fix

Use 'await import('mysql2-ssh')' or set 'type': 'module' in package.json

Error: All configured authentication methods failed

SSH authentication failure (wrong key, passphrase, or username)

fix

Verify SSH credentials and key format; use ssh -i key user@host to test

Error: connect ECONNREFUSED 127.0.0.1:3306

MySQL server not running on remote host's localhost or incorrect port

fix

Ensure MySQL is running and accessible on the remote host; check dbConfig.host and port

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'mysql2'

Missing peer dependency mysql2

fix

npm install mysql2

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

mysql2requiredMySQL client library for executing queries over the SSH tunnel

ssh2requiredSSH2 client for creating the tunnel connection

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/Engelswoord/mysql2-ssh ↗

packagemysql2-ssh ↗

homepagehttps://github.com/Engelswoord/mysql2-ssh ↗