{"id":16613,"library":"dbms","title":"Total.js Node Database Management System (ORM)","description":"The `dbms` package is a Node.js Object Relational Mapper (ORM) primarily designed for the Total.js framework. It offers a unified interface for interacting with various database systems, including PostgreSQL, MySQL, MariaDB, and Total.js's embedded TextDB, with partial support for MongoDB. Currently at version 1.0.9, the package was last updated approximately two years ago, suggesting a maintenance-focused release cadence tied to the Total.js ecosystem rather than independent rapid development. Its key differentiator is its deep integration with Total.js, exposing database access via a global `DBMS()` function within Total.js applications. This package operates exclusively within the CommonJS module system.","status":"active","version":"1.0.9","language":"javascript","source_language":"en","source_url":"https://github.com/totaljs/dbms","tags":["javascript","orm","database","postgresql","mysql","mariadb","mongodb","sqlserver","nosql"],"install":[{"cmd":"npm install dbms","lang":"bash","label":"npm"},{"cmd":"yarn add dbms","lang":"bash","label":"yarn"},{"cmd":"pnpm add dbms","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for MySQL/MariaDB database connections.","package":"mysql2","optional":true},{"reason":"Required for PostgreSQL database connections.","package":"pg","optional":true},{"reason":"Required for MongoDB database connections (partial support).","package":"mongodb","optional":true}],"imports":[{"note":"The `dbms` package is CommonJS-only; direct ES module `import` statements are not natively supported.","wrong":"import dbms from 'dbms';","symbol":"dbms","correct":"const dbms = require('dbms');"},{"note":"The `DBMS()` function becomes a global accessible method within a Total.js application after `require('dbms').init()` has been successfully called, typically within `/definitions/db.js`. It is not directly exported by the `dbms` module.","symbol":"DBMS()","correct":"var db = DBMS();"},{"note":"`init` is a method on the module object obtained via `require('dbms')`, not on the global `DBMS()` function.","wrong":"DBMS.init('...');","symbol":"dbms.init","correct":"const dbms = require('dbms'); dbms.init('postgresql://user:pass@localhost:5432/dbname');"}],"quickstart":{"code":"const dbms = require('dbms');\n\n// In a Total.js application, dbms.init() would typically be called once\n// within a configuration or definition file (e.g., `/definitions/db.js`).\n// This action makes the `DBMS()` function globally available.\n\n// Initialize a PostgreSQL connection named 'default'\ndbms.init('postgresql://user:password@localhost:5432/testdb?pooling=false');\n\n// Initialize another PostgreSQL connection named 'mypg'\ndbms.init('mypg', 'postgresql://user:password@localhost:5432/anothertestdb');\n\n// --- Simulate Global DBMS() Function (for non-Total.js standalone use) ---\n// In a real Total.js app, `DBMS()` would be globally available after init.\n// This mock helps illustrate usage but isn't how it works natively outside Total.js.\nfunction DBMS(name) {\n  const _dbmsModule = require('dbms');\n  return _dbmsModule(name);\n}\n\n// Example 1: Find records using the default database\nDBMS().find('users').where('age', '>', 25).callback(function(err, response) {\n    if (err) {\n        console.error('Error finding users:', err);\n        return;\n    }\n    console.log('Found users (default DB):', response);\n});\n\n// Example 2: Insert a new record into a named database ('mypg')\nDBMS('mypg').insert('products', { name: 'New Widget', price: 99.99, stock: 100 }).callback(function(err, id) {\n    if (err) {\n        console.error('Error inserting product:', err);\n        return;\n    }\n    console.log('Inserted product with ID (mypg DB):', id);\n});\n\n// Example 3: Find a single record\nDBMS().one('settings').where('key', 'app_name').callback(function(err, setting) {\n    if (err) {\n        console.error('Error fetching setting:', err);\n        return;\n    }\n    console.log('App Name setting:', setting);\n});\n\n// Note: Ensure the `pg` npm package is installed: `npm install pg`\n// And replace `user` and `password` with actual credentials for the database.","lang":"javascript","description":"Demonstrates initializing database connections with `dbms.init()` and performing basic `find`, `insert`, and `one` operations using the `DBMS()` global function, illustrating common patterns within a Total.js application."},"warnings":[{"fix":"Ensure you are running within a Total.js application where `dbms.init()` has been called in `/definitions/db.js`, or manually expose the function to the global scope if adapting for standalone use (though not recommended for production).","message":"The primary interaction method, `DBMS()`, is designed to be a global function within Total.js applications after the module is initialized via `dbms.init()` in a definitions file. Attempting to use `DBMS()` directly in a non-Total.js environment without proper global scope management will result in a `ReferenceError`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use `const dbms = require('dbms');` for all imports. If your project is pure ESM, you may need to use a CommonJS wrapper or consider alternative ORMs that offer native ESM support.","message":"This package is CommonJS-only. It does not natively support ECMAScript Modules (`import` syntax). Attempting to `import dbms from 'dbms'` will result in a module loading error in pure ESM environments.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Install the necessary driver(s) using `npm install <driver-package-name>`, e.g., `npm install pg` for PostgreSQL.","message":"Database drivers (e.g., `pg` for PostgreSQL, `mysql2` for MySQL, `mongodb` for MongoDB) are peer dependencies and must be installed separately alongside `dbms`. The package will not function with a specific database type unless its corresponding driver is explicitly installed.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review the Total.js DBMS documentation for specific limitations with MongoDB. For complex MongoDB operations, consider using a dedicated MongoDB driver or ODM directly.","message":"The `dbms` package offers only 'partial' support for MongoDB. This implies that not all MongoDB features or query patterns may be fully implemented or optimized compared to dedicated MongoDB ORMs/ODMs.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Evaluate compatibility with your current Node.js and database versions. Monitor the Total.js ecosystem for any announcements regarding future `dbms` development or replacements.","message":"The package's latest version (1.0.9) was published approximately two years ago. While not explicitly deprecated, the infrequent updates suggest a mature but slowly evolving project. This could mean slower adoption of new database features, less frequent security patches, or compatibility issues with very recent Node.js versions or database releases.","severity":"gotcha","affected_versions":"<=1.0.9"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure `dbms.init()` has been executed within a Total.js application's `/definitions/db.js` file, which registers `DBMS()` globally. For standalone use, this pattern is not natively supported and requires manual global exposure or direct module interaction, which may deviate from documented usage.","cause":"Attempting to call the global `DBMS()` function outside of a properly initialized Total.js application context.","error":"ReferenceError: DBMS is not defined"},{"fix":"Install the missing driver: `npm install pg` (for PostgreSQL). Replace `pg` with `mysql2` or `mongodb` as appropriate for your configured database type.","cause":"The required database driver for PostgreSQL (`pg`) was not installed as a peer dependency.","error":"Error: Cannot find module 'pg'"},{"fix":"Call `dbms.init([alias], connection_string);` at application startup. For Total.js, this is typically in `/definitions/db.js`.","cause":"The `dbms.init()` method was not called for the specified or default database alias before attempting database operations.","error":"Database 'default' was not initialized."}],"ecosystem":"npm"}