{"id":17299,"library":"mysql-import","title":"Node.js MySQL SQL File Importer","description":"mysql-import is a Node.js library designed to facilitate the programmatic import of `.sql` dump files into a MySQL database. Currently at version 5.0.26, the package provides a streamlined API for tasks such as database seeding, migration, or restoring backups. It differs from general ORMs or query builders by focusing solely on bulk SQL import operations. A key differentiator is its event-driven progress tracking (`onProgress`, `onDumpCompleted`), allowing developers to monitor long-running imports in real-time, which is crucial for large datasets. The library leverages Node.js streams and underlying MySQL client binaries to efficiently process SQL files of various sizes, making it a robust solution for environments requiring automated database provisioning or data synchronization.","status":"active","version":"5.0.26","language":"javascript","source_language":"en","source_url":"https://github.com/pamblam/mysql-import","tags":["javascript","nodejs","mysql","textfiles","import","sql"],"install":[{"cmd":"npm install mysql-import","lang":"bash","label":"npm"},{"cmd":"yarn add mysql-import","lang":"bash","label":"yarn"},{"cmd":"pnpm add mysql-import","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the underlying MySQL connection functionality; the constructor accepts options compatible with the 'mysqljs/mysql' library.","package":"mysql","optional":false}],"imports":[{"note":"For CommonJS, the library exports the Importer class directly as the module's default export.","wrong":"const { Importer } = require('mysql-import');","symbol":"Importer","correct":"const Importer = require('mysql-import');"},{"note":"For ES Modules, the Importer class is the default export. Avoid named import syntax.","wrong":"import { Importer } from 'mysql-import';","symbol":"Importer","correct":"import Importer from 'mysql-import';"}],"quickstart":{"code":"const host = 'localhost';\nconst user = 'root';\nconst password = 'password';\nconst database = 'mydb';\n\nconst Importer = require('mysql-import');\nconst importer = new Importer({host, user, password, database});\n\nimporter.onProgress(progress=>{\n  var percent = Math.floor(progress.bytes_processed / progress.total_bytes * 10000) / 100;\n  console.log(`${percent}% Completed`);\n});\n\nimporter.import('path/to/dump.sql').then(()=>{\n  var files_imported = importer.getImported();\n  console.log(`${files_imported.length} SQL file(s) imported.`);\n}).catch(err=>{\n  console.error(err);\n});","lang":"javascript","description":"Demonstrates how to initialize the Importer, set up progress tracking, and import a single SQL file."},"warnings":[{"fix":"Adjust `max_allowed_packet` in your `my.cnf` or `my.ini` file (e.g., `max_allowed_packet=256M`) and restart MySQL.","message":"When dealing with very large SQL dump files, ensure that your MySQL server's `max_allowed_packet` setting is sufficiently large to accommodate the largest single SQL statement. Insufficient packet size can lead to import failures.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use `importer.setEncoding('utf8mb4')` if your dump is UTF-8 based, and verify your MySQL database and table collations are also `utf8mb4_unicode_ci` or similar.","message":"Character encoding mismatches between your SQL dump file and the target MySQL database or connection can lead to 'Incorrect string value' errors or corrupted data. Always ensure consistent encoding, typically UTF-8 or utf8mb4.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Pre-create the database if it doesn't exist, and consider stripping `CREATE DATABASE` and `USE` statements from your SQL dump if you intend to import into a specific pre-selected database.","message":"If your SQL dump contains `CREATE DATABASE` or `USE database` statements, particularly when importing into an existing database or an environment with restricted permissions (e.g., shared hosting), these statements might cause 'Access denied' or 'Unknown database' errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always validate and sanitize file paths, ensuring they point only to expected and trusted SQL dump files.","message":"Providing dynamically generated or untrusted file paths to `importer.import()` without validation can pose a security risk, potentially allowing path traversal or the execution of arbitrary SQL files on your server.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Double-check the `host`, `user`, and `password` parameters in the Importer constructor. Ensure the MySQL user has appropriate privileges to connect and write to the target database.","cause":"Incorrect MySQL database credentials (username or password) or insufficient permissions for the user.","error":"ER_ACCESS_DENIED_ERROR: Access denied for user 'user'@'localhost' (using password: YES)"},{"fix":"Create the database manually on your MySQL server before running the import, or ensure the SQL dump itself includes a `CREATE DATABASE` statement that executes successfully beforehand.","cause":"The specified `database` in the Importer constructor or `importer.use()` method does not exist on the MySQL server.","error":"ER_BAD_DB_ERROR: Unknown database 'mydb'"},{"fix":"Verify the absolute or relative path to your SQL dump file. Ensure file permissions allow Node.js to read the file.","cause":"The path provided to `importer.import()` is incorrect, or the SQL file does not exist at the specified location.","error":"Error: ENOENT: no such file or directory, open 'path/to/dump.sql'"}],"ecosystem":"npm","meta_description":null}