{"id":43471,"library":"node-sql-util","title":"node-sql-util","description":"A lightweight Node.js database utility library built on MySQL2 and SSH2 that provides a simple ORM-like interface for MySQL queries, including SELECT, INSERT, UPDATE, DELETE, JOIN, and transaction support. Version 1.14.9 is the current stable release. It offers SSH tunneling for remote debugging, connection pooling, SQL injection protection, and the ability to return raw SQL strings. It is less flexible than full ORMs like Sequelize but simpler for basic CRUD operations, with a focus on ease of use and security. The library is actively maintained with regular updates.","status":"active","version":"1.14.9","language":"javascript","source_language":"en","source_url":"https://github.com/xv1998/node-sql-util","tags":["javascript","mysql","sql tool","sql util","orm","sql builder","JavaScript","sql","sqlserver"],"install":[{"cmd":"npm install node-sql-util","lang":"bash","label":"npm"},{"cmd":"yarn add node-sql-util","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-sql-util","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core MySQL database driver for query execution and connection pooling.","package":"mysql2","optional":false},{"reason":"Required for SSH tunneling support when connecting to remote databases.","package":"ssh2","optional":true}],"imports":[{"note":"The package exports a default class via CommonJS. ES module import is not supported natively. Use require() or dynamic import().","wrong":"import { SqlUtil } from 'node-sql-util';","symbol":"SqlUtil","correct":"const SqlUtil = require('node-sql-util');"},{"note":"Alternative import style using CommonJS destructuring. Works the same as the default require.","symbol":"SqlUtil","correct":"const SqlUtil = require('node-sql-util');"},{"note":"When using ES module syntax with a bundler or Node.js ESM, use default import. Named import will fail.","wrong":"import { SqlUtil } from 'node-sql-util';","symbol":"SqlUtil","correct":"import SqlUtil from 'node-sql-util';"},{"note":"Dynamic import in ESM environments. The module has no named exports; default is the class.","symbol":"SqlUtil","correct":"const { default: SqlUtil } = await import('node-sql-util');"}],"quickstart":{"code":"const SqlUtil = require('node-sql-util');\nconst mySql = new SqlUtil({\n  dbConfig: {\n    host: '1.2.3.4',\n    port: 3306,\n    database: 'testdb',\n    user: 'user',\n    password: 'pass',\n    connectionLimit: 5,\n  }\n});\n\nasync function quickStart() {\n  let searchRes = await mySql.select({\n    table: 'users',\n    fields: ['name', 'age'],\n    where: { age: 18 },\n    limit: 10\n  });\n  if (searchRes.code === 0) {\n    console.log('Success:', searchRes.data);\n  } else {\n    console.error('Error:', searchRes.message);\n  }\n}\n\nquickStart();","lang":"javascript","description":"Initializes a SqlUtil instance with MySQL connection config, performs a simple SELECT query with conditions and limit, and handles the response."},"warnings":[{"fix":"Use array notation for where: [{field: 'age', value: 18}], [{field: 'name', value: 'lili'}] to combine with OR.","message":"The WHERE clause by default uses AND logic. To use OR, you must use the array syntax documented in the condition chapter.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Replace `order: 'desc'` with `orderCustom: 'order by id desc'`.","message":"The `order` parameter in select/find is deprecated and may be removed in future versions. Use `orderCustom` instead.","severity":"deprecated","affected_versions":">=1.10.0"},{"fix":"Always check if `res.data` is truthy before accessing properties. Use `if (res.data)` not `if (res.data.length)`.","message":"The `find` method returns a single object (not an array) in `res.data`, even if no rows found (returns null). This differs from `select` which always returns an array.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Check the return value: if `asSql` is true, it's a string; otherwise it's an object with `code`, `data`, etc.","message":"When using `asSql: true`, the method returns the SQL string instead of executing it. The return format is the SQL string directly, not wrapped in a response object.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Set these to false (default) to get consistent response format, or parse the return accordingly.","message":"The `returnOriginError` and `returnOriginSource` options affect the response format. When set to true, the error/success object is returned directly instead of the standard { code, subcode, message, data } wrapper.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"search_vec":"'1.14.9':37 'abil':57 'activ':90 'basic':75 'builder':103 'built':11 'connect':50 'crud':76 'current':40 'databas':8 'debug':49 'delet':31 'eas':82 'flexibl':66 'focus':80 'full':68 'includ':27 'inject':53 'insert':29 'interfac':23 'javascript':95,104 'join':32 'less':65 'librari':10,88 'lightweight':6 'like':22,70 'maintain':91 'mysql':25,96 'mysql2':13 'node':2 'node-sql-util':1 'node.js':7 'offer':44 'oper':77 'orm':21,69,101 'orm-lik':20 'pool':51 'protect':54 'provid':17 'queri':26 'raw':60 'regular':93 'releas':42 'remot':48 'return':59 'secur':86 'select':28 'sequel':71 'simpl':19 'simpler':73 'sql':3,52,61,97,99,102,105 'sqlserver':106 'ssh':45 'ssh2':15 'stabl':41 'string':62 'support':35 'tool':98 'transact':34 'tunnel':46 'updat':30,94 'use':84 'util':4,9,100 'version':36","created_at":"2026-06-05T16:59:57.553088+00:00","updated_at":"2026-06-05T16:59:57.553088+00:00","problems":[{"fix":"Verify host/port are correct. For SSH, add sshConfig to SqlUtil constructor: `new SqlUtil({ dbConfig: {...}, sshConfig: { host: 'proxy', username: 'user', privateKey: require('fs').readFileSync('/path/to/key') } })`.","cause":"MySQL host is not reachable; port might be closed, or SSH tunnel not configured correctly.","error":"Error: connect ECONNREFUSED 1.2.3.4:3306"},{"fix":"Check the `asSql` field: if true, the return value is a string (the SQL). Remove `asSql` or set to false to get the response object.","cause":"sqlUtil.select() returned undefined because `asSql: true` was set and the function returned a string, not an object.","error":"TypeError: Cannot destructure property 'code' of 'undefined' or null."},{"fix":"Double-check credentials. Ensure the user has access from the specified host. For SSH, the database connection goes through the tunnel; the host in dbConfig might be 'localhost' if using SSH.","cause":"Invalid username or password in dbConfig.","error":"Error: ER_ACCESS_DENIED_ERROR: Access denied for user 'user'@'host' (using password: YES)"},{"fix":"Ensure you use `new SqlUtil(config)` and that the import is correct: `const SqlUtil = require('node-sql-util')`.","cause":"SqlUtil is not properly instantiated or the import failed (e.g., used named import instead of default).","error":"TypeError: sqlUtil.select is not a function"},{"fix":"Run `npm install node-sql-util --save` or `yarn add node-sql-util`.","cause":"Package not installed or not in node_modules.","error":"Error: Cannot find module 'node-sql-util'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/xv1998/node-sql-util#readme","github":"https://github.com/xv1998/node-sql-util","docs":null,"changelog":null,"pypi":null,"npm":"node-sql-util","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}