Registry / database / mysql-ssh

mysql-ssh

JSON →
library1.0.6jsnpmunverified

A lightweight Node.js library that establishes a MySQL connection through an SSH tunnel. Currently at version 1.0.6, it wraps ssh2 and mysql2 to provide a simple promise-based API for connecting to remote MySQL databases only accessible via SSH. Unlike manually managing SSH tunnels with separate libraries, mysql-ssh handles forwarding and cleanup automatically. Suitable for temporary connections, but users must call close() to avoid resource leaks. Low maintenance cadence.

database
npm install mysql-ssh
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · MYSQL-SSH
M
mysql-ssh
databasejavascriptv1.0.6
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.

default
✓ const mysqlssh = require('mysql-ssh')
✗ import mysqlssh from 'mysql-ssh'
This package does not ship ESM; use CommonJS require.
connect
✓ const { connect } = require('mysql-ssh')
✗ import { connect } from 'mysql-ssh'
Named exports are not available in ESM; destructure from require.
close
✓ const { close } = require('mysql-ssh')
✗ import { close } from 'mysql-ssh'
Same as connect.

Connects to a MySQL database through an SSH tunnel using private key authentication, runs a query, prints results, and closes the tunnel.

const mysqlssh = require('mysql-ssh'); const fs = require('fs'); mysqlssh.connect( { host: 'ssh.example.com', user: 'sshuser', privateKey: fs.readFileSync(process.env.SSH_KEY_PATH ?? '/home/user/.ssh/id_rsa') }, { host: 'db.example.com', user: 'dbuser', password: process.env.DB_PASS ?? '', database: 'test' } ).then(client => { client.query('SELECT 1 AS success', (err, results) => { if (err) throw err; console.log(results); mysqlssh.close(); }); }).catch(err => console.error(err));
Debug
Known issues
gotchaForgetting to call mysqlssh.close() will leave the SSH tunnel open, causing resource leaks.
fix
Always call mysqlssh.close() after you finish querying.
affects: <=1.0.6
gotchaThe library does not handle connection retries; if the SSH or MySQL connection fails, the promise rejects immediately.
fix
Add your own retry logic using .catch or async/await try-catch.
affects: <=1.0.6
deprecatedThe Greenkeeper badge in the README indicates automated dependency updates, but Greenkeeper is deprecated in favor of Renovate.
fix
No direct impact on functionality; switch to Renovate for dependency management.
affects: <=1.0.6
Errors
Common errors & fixes
Error: connect ECONNREFUSED 127.0.0.1:3306
SSH tunnel configured but MySQL not running on local forwarded port.
fix
Ensure the SSH tunnel forwards the correct remote port to a local port, and that MySQL is reachable from the SSH server.
Error: All configured authentication methods failed
SSH authentication failed due to wrong private key or passphrase.
fix
Check that the private key path is correct and the key has proper permissions (600). If using passphrase, add passphrase property to sshConfig.
Upgrade
Version history
1.0.6latest on npm
Audit
Dependencies
ssh2requiredProvides SSH tunnel functionality
mysql2requiredProvides MySQL client connectivity
Agent activity
4 hits · last 30 days
node
4
Resources
githubhttps://github.com/grrr-amsterdam/mysql-ssh ↗
packagemysql-ssh ↗
homepagehttps://github.com/grrr-amsterdam/mysql-ssh#readme ↗
mysql-ssh — npm install mysql-ssh · libregistry