mysql-shaman

library1.0.11jsnpmunverified

mysql-shaman is a lightweight ORM for Node.js that provides a simple, familiar syntax for MySQL CRUD operations, wrapping the official mysql package. Version 1.0.11 (latest) ships TypeScript types and includes a CLI for database management. Unlike heavy ORMs like Sequelize or TypeORM, it focuses on minimalism and discoverability, allowing developers to use JavaScript expressions instead of raw SQL strings. Released under the IoT Shaman project, it targets developers who want a thin abstraction over mysql with minimal configuration.

database

npm install mysql-shaman

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MYSQL-SHAMAN

mysql-shaman

databasejavascriptv1.0.11

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.

DatabaseContext

✓ import { DatabaseContext } from 'mysql-shaman'

✗ const DatabaseContext = require('mysql-shaman').DatabaseContext

Default export not available, use named import. TypeScript types are included.

Collection

✓ import { Collection } from 'mysql-shaman'

✗ import Collection from 'mysql-shaman'

Named import, not default.

mysql-shaman (CLI)

✓ Call commands via npx mysql-shaman or global install

✗ const cli = require('mysql-shaman/cli')

CLI is not a programmatic module. Install globally and use from terminal.

Shows setting up a database context with a User model, initializing connection, and performing a simple find query.

import { DatabaseContext, Collection } from 'mysql-shaman'; class User { userId?: string; email: string; firstName: string; lastName: string; } class MyDbContext extends DatabaseContext { models = { user: new Collection<User>() } } const db = new MyDbContext(); db.initialize({ connectionLimit: 10, host: process.env.DB_HOST ?? 'localhost', user: process.env.DB_USER ?? 'root', password: process.env.DB_PASS ?? '', database: process.env.DB_NAME ?? 'test', waitForConnections: false }); db.models.user.find({ conditions: ['email = ?'], args: ['test@example.com'] }) .then(users => console.log(users)) .catch(err => console.error(err));

Debug

Known issues

gotchaCollection property name must exactly match MySQL table name (case-sensitive). Mismatch causes silent failures.

fix

Ensure model property names match table names exactly, including case.

affects: >=0.0.0

gotchaSpecifying 'conditions' without 'args' leads to SQL injection vulnerability if user input is directly concatenated.

fix

Always use parameterized queries: provide 'conditions' with '?' placeholders and pass values in 'args'.

affects: >=0.0.0

deprecatedMethod 'fi' appears in quickstart but is not documented; likely a typo for 'find' or removed method.

fix

Use find() with appropriate filters.

affects: 1.0.11

Errors

Common errors & fixes

Error: Cannot find module 'mysql-shaman'

Package not installed or import path incorrect.

fix

Run `npm install mysql-shaman` and ensure import matches 'import { ... } from 'mysql-shaman''

ER_NOT_SUPPORTED_AUTH_MODE: Client does not support authentication protocol requested by server

MySQL 8+ default authentication plugin is caching_sha2_password.

fix

Either update mysql driver or run `ALTER USER 'user'@'host' IDENTIFIED WITH mysql_native_password BY 'password';`

TypeError: database.models.user.find is not a function

Database not initialized before calling methods.

fix

Ensure `database.initialize()` is called and awaited before performing queries.

Upgrade

Version history

1.0.11latest on npm

Audit

Dependencies

mysqlrequiredCore mysql driver for database connectivity

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/iotshaman/mysql-shaman ↗

packagemysql-shaman ↗

homepagehttps://github.com/iotshaman/mysql-shaman#readme ↗