{"id":43401,"library":"natis","title":"Natis","description":"Natis is a MySQL utility library (version 3.0.1) that provides a thin wrapper around the mysql2 package for Node.js. It simplifies common MySQL operations such as querying, connection pooling, and transaction management with a promise-based API. Unlike full-fledged ORMs like Sequelize or TypeORM, Natis focuses on lightweight, minimal abstraction, giving developers direct SQL control while handling connection lifecycle and error retries. It is released on an as-needed cadence, with v3 introducing breaking changes to the API (async/await required, no callback support). Requires mysql2 as a peer dependency and supports TypeScript definitions.","status":"active","version":"3.0.1","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","mysql","natis"],"install":[{"cmd":"npm install natis","lang":"bash","label":"npm"},{"cmd":"yarn add natis","lang":"bash","label":"yarn"},{"cmd":"pnpm add natis","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Natis wraps mysql2 for MySQL protocol handling and connection pooling.","package":"mysql2","optional":false}],"imports":[{"note":"ESM-only since v3. For older versions, use require with .default.","wrong":"const { createConnection } = require('natis')","symbol":"createConnection","correct":"import { createConnection } from 'natis'"},{"note":"NatisClient is a named export, not default.","wrong":"import NatisClient from 'natis'","symbol":"NatisClient","correct":"import { NatisClient } from 'natis'"},{"note":"All exports are at the package root, no subpath exports.","wrong":"import { query } from 'natis/query'","symbol":"query","correct":"import { query } from 'natis'"}],"quickstart":{"code":"import { createConnection, query } from 'natis';\n\nasync function main() {\n  const conn = await createConnection({\n    host: 'localhost',\n    user: 'root',\n    password: process.env.DB_PASSWORD ?? '',\n    database: 'test'\n  });\n\n  await query(conn, 'CREATE TABLE IF NOT EXISTS users (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255))');\n  const result = await query(conn, 'INSERT INTO users (name) VALUES (?)', ['Alice']);\n  console.log('Insert ID:', result.insertId);\n\n  const rows = await query(conn, 'SELECT * FROM users');\n  console.log('Users:', rows);\n\n  await conn.end();\n}\n\nmain().catch(console.error);","lang":"typescript","description":"Establishes a MySQL connection using createConnection, creates a table, inserts a row, and queries all rows."},"warnings":[{"fix":"Switch to ESM imports (import { ... } from 'natis') or continue using v2.x for CommonJS support.","message":"Natis v3 is ESM-only. Requires Node.js >= 14 and 'type': 'module' in package.json.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use async/await or .then() instead of callback functions.","message":"All API methods return Promises; callbacks removed in v3.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Replace 'pool' with 'createPool' from '@natis/core' or upgrade to v3.","message":"The 'pool' export is deprecated since v2.5 in favor of createPool.","severity":"deprecated","affected_versions":">=2.5.0 <3.0.0"},{"fix":"Always check connection state and re-create on error. Use connection pools for reliability.","message":"Connection objects are not directly reusable after a query error; you must create a new connection.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'3.0.1':9 'abstract':54 'api':39,83 'around':15 'as-need':72 'async/await':84 'base':38 'break':79 'cadenc':75 'callback':87 'chang':80 'common':23 'connect':29,62 'control':59 'definit':98 'depend':94 'develop':56 'direct':57 'error':65 'fledg':43 'focus':50 'full':42 'full-fledg':41 'give':55 'handl':61 'introduc':78 'javascript':99 'librari':7 'lifecycl':63 'lightweight':52 'like':45 'manag':33 'minim':53 'mysql':5,24,100 'mysql2':17,90 'nati':1,2,49,101 'need':74 'node.js':20 'oper':25 'orm':44 'packag':18 'peer':93 'pool':30 'promis':37 'promise-bas':36 'provid':11 'queri':28 'releas':69 'requir':85,89 'retri':66 'sequel':46 'simplifi':22 'sql':58 'support':88,96 'thin':13 'transact':32 'typeorm':48 'typescript':97 'unlik':40 'util':6 'v3':77 'version':8 'wrapper':14","created_at":"2026-06-05T16:59:37.451316+00:00","updated_at":"2026-06-05T16:59:37.451316+00:00","problems":[{"fix":"npm install natis mysql2","cause":"Missing peer dependency mysql2 or installed in wrong environment.","error":"Cannot find module 'natis' or its corresponding type declarations."},{"fix":"Use dynamic import: const natis = await import('natis') or add 'type': 'module' to package.json.","cause":"Using CommonJS require() with v3 ESM-only package.","error":"Error: Must use import to load ES Module: /path/to/node_modules/natis/index.js"},{"fix":"Use query(conn, 'SQL') instead of conn.query().","cause":"Misunderstanding API: query is a standalone function, not a method on connection.","error":"TypeError: conn.query is not a function"}],"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":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"natis","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}}