{"id":27974,"library":"murmuration","title":"Murmuration","description":"Murmuration is a low-level database library providing statement generation, transactions, and migrations. It serves as a lightweight alternative to ORMs like Sequelize or TypeORM, focusing on minimal, dynamic query building with a promise-like syntax. The base package (v2.0.80) is abstract and intended to be extended by specific implementations: Murmuration-MariaDB and Murmuration-PostGreSQL. Key differentiators include its use of operations to wrap transactions and its built-in migration support that synchronizes the database schema during deployment. It deliberately avoids abstractions like models or query builders, giving developers direct control over SQL.","status":"active","version":"2.0.80","language":"javascript","source_language":"en","source_url":"https://github.com/djalbat/murmuration","tags":["javascript"],"install":[{"cmd":"npm install murmuration","lang":"bash","label":"npm"},{"cmd":"yarn add murmuration","lang":"bash","label":"yarn"},{"cmd":"pnpm add murmuration","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary import is a function called 'using'. The package is CommonJS-only; ESM is not supported. In practice, you should install a specific package like 'murmuration-mariadb' and import from there.","wrong":"import using from 'murmuration';","symbol":"using","correct":"const using = require('murmuration');"},{"note":"The Statement class is exported as a named export. It is intended to be extended when creating the 'using' function with database-specific connection details.","wrong":"const Statement = require('murmuration').Statement;","symbol":"Statement","correct":"const { Statement } = require('murmuration');"},{"note":"The migrate function is a named export for running migrations. It is CommonJS only. Typically called from deployment scripts.","wrong":"import { migrate } from 'murmuration';","symbol":"migrate","correct":"const { migrate } = require('murmuration');"}],"quickstart":{"code":"const { Statement, migrate } = require('murmuration');\nconst withConnection = (connection) => ({\n  selectFromUsers: () => ({\n    where: (conditions) => ({\n      one: (handler) => ({ else: (elseHandler) => ({ catch: (errHandler) => ({ execute: async () => {\n        const sql = `SELECT * FROM users WHERE ${Object.keys(conditions).map(k => `${k} = ?`).join(' AND ')}`;\n        const values = Object.values(conditions);\n        try {\n          const rows = await connection.execute(sql, values);\n          if (rows.length === 1) handler(rows[0]);\n          else elseHandler();\n        } catch (err) { errHandler(err); }\n      }})\n    })\n  })\n});\n\nconst using = (connection) => withConnection(connection);\n\nasync function quickstart() {\n  const connection = { execute: async (sql, params) => [[{ id: 1, name: 'Alice' }], []] };\n  const context = { emailAddress: 'alice@example.com', password: 'secret' };\n  using(connection)\n    .selectFromUsers()\n    .where({ emailAddress: context.emailAddress, password: context.password })\n    .one(({ id }) => { console.log('Found user:', id); })\n    .else(() => { console.log('User not found'); })\n    .catch((err) => { console.error('Error:', err); })\n    .execute();\n}\n\nquickstart();","lang":"javascript","description":"Demonstrates building a query dynamically with using(), where(), one(), else(), catch(), and execute()."},"warnings":[{"fix":"Replace .end() with .execute() on statement chains.","message":"Version 2.x changed the API from callback-based to promise-like chaining. Old .end() method replaced with .execute().","severity":"breaking","affected_versions":">1.0"},{"fix":"Change const Murmuration = require('murmuration') to const { Statement } = require('murmuration').","message":"Version 2.0 removed the default export; require('murmuration') no longer returns a constructor. Use named exports like { Statement } or { migrate }.","severity":"breaking","affected_versions":">=2.0"},{"fix":"Install the appropriate database-specific package: npm install murmuration-mariadb or npm install murmuration-postgresql.","message":"The base Murmuration package is deprecated; use Murmuration-MariaDB or Murmuration-PostGreSQL instead.","severity":"deprecated","affected_versions":">=2.0.80"},{"fix":"Create a using.js file that imports and extends Statement with your database driver's execute method.","message":"The using() function must be defined locally; the package does not export it directly. It is typically created by extending the Statement class with database-specific connection methods.","severity":"gotcha","affected_versions":">=2.0"},{"fix":"Use a raw query method or extend Statement to support custom conditions.","message":"The where() method only supports equality conditions (simple object). For operators like IN, LIKE, or OR, you must write raw SQL and use a different approach.","severity":"gotcha","affected_versions":"all"},{"fix":"Refactor migration files to export { up: async (connection) => { ... }, down: async (connection) => { ... } }.","message":"Migration schema changed: migration files must export an object with up and down functions instead of arrays of SQL strings.","severity":"breaking","affected_versions":">=2.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Run `npm install murmuration-mariadb` or `npm install murmuration-postgresql` and import from that package instead.","cause":"The package is not installed, or you are trying to use the base package without installing a database-specific implementation.","error":"Cannot find module 'murmuration'"},{"fix":"Define a local `using` function by extending the Statement class. Example: const { Statement } = require('murmuration'); const using = (connection) => new Statement(connection);","cause":"You are trying to use require('murmuration') directly as a function, but the package exports an object with named exports, not a function.","error":"TypeError: using is not a function"},{"fix":"Create a using function that extends Statement with your database schema's methods, or use a package like murmuration-mariadb that provides them.","cause":"The using() function is not properly set up with database-specific methods like selectFromAccount(). The base murmurration does not include these.","error":"TypeError: Cannot read properties of undefined (reading 'selectFromAccount')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}