node-red-contrib-db-storage 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Muralidhar Reddy Challa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,557 @@
+# Node-RED Storage Plugin
+
+A flexible storage plugin for Node-RED that supports multiple database backends including MongoDB, PostgreSQL, MySQL/MariaDB, and SQLite.
+
+## Features
+
+- **Multi-database support**: MongoDB, PostgreSQL, MySQL/MariaDB, SQLite
+- Store all Node-RED data in your preferred database
+- Separate collections/tables for each entity type
+- Configurable collection/table names
+- Support for Node-RED library entries
+- Backward compatible with existing MongoDB configurations
+- **Extensible adapter registry** - easily add custom database adapters
+- Standardized configuration interface across all adapters
+- Input validation and SQL injection protection
+
+## Installation
+
+```bash
+npm install node-red-contrib-db-storage
+```
+
+### Database-specific dependencies
+
+**MongoDB** (included by default):
+```bash
+# MongoDB driver is included
+```
+
+**PostgreSQL**:
+```bash
+npm install pg
+```
+
+**MySQL/MariaDB**:
+```bash
+npm install mysql2
+```
+
+**SQLite**:
+```bash
+npm install better-sqlite3
+```
+
+## Requirements
+
+- Node.js >= 10.x
+- Node-RED (embedded mode)
+- One of the following databases:
+  - MongoDB >= 3.4
+  - PostgreSQL >= 9.6
+  - MySQL >= 5.7 or MariaDB >= 10.2
+  - SQLite 3
+
+## Quick Start
+
+### MongoDB Configuration
+
+```javascript
+const settings = {
+    storageModule: require('node-red-contrib-db-storage'),
+    storageModuleOptions: {
+        type: 'mongodb',
+        url: 'mongodb://localhost:27017',
+        database: 'nodered'
+    }
+};
+```
+
+### PostgreSQL Configuration
+
+```javascript
+const settings = {
+    storageModule: require('node-red-contrib-db-storage'),
+    storageModuleOptions: {
+        type: 'postgres',
+        url: 'postgresql://user:password@localhost:5432/nodered'
+    }
+};
+```
+
+### MySQL/MariaDB Configuration
+
+```javascript
+const settings = {
+    storageModule: require('node-red-contrib-db-storage'),
+    storageModuleOptions: {
+        type: 'mysql',  // or 'mariadb'
+        url: 'mysql://user:password@localhost:3306/nodered'
+    }
+};
+```
+
+### SQLite Configuration
+
+```javascript
+const settings = {
+    storageModule: require('node-red-contrib-db-storage'),
+    storageModuleOptions: {
+        type: 'sqlite',
+        url: '/path/to/nodered.db'
+        // or use ':memory:' for in-memory database
+    }
+};
+```
+
+## Usage
+
+This plugin requires running Node-RED in embedded mode. See the [Node-RED embedding guide](http://nodered.org/docs/embedding.html) for details.
+
+### Complete Example
+
+```javascript
+const http = require('http');
+const express = require('express');
+const RED = require('node-red');
+
+const app = express();
+const server = http.createServer(app);
+
+const settings = {
+    httpAdminRoot: '/red',
+    httpNodeRoot: '/api',
+    userDir: './user',
+
+    // Storage Plugin Configuration
+    storageModule: require('node-red-contrib-db-storage'),
+    storageModuleOptions: {
+        type: 'mongodb',  // or 'postgres', 'mysql', 'sqlite'
+        url: 'mongodb://localhost:27017',
+        database: 'nodered',
+
+        // Optional: custom collection/table names
+        collectionNames: {
+            flows: 'my-flows',
+            credentials: 'my-credentials',
+            settings: 'my-settings',
+            sessions: 'my-sessions'
+        }
+    }
+};
+
+RED.init(server, settings);
+
+app.use(settings.httpAdminRoot, RED.httpAdmin);
+app.use(settings.httpNodeRoot, RED.httpNode);
+
+server.listen(8000, () => {
+    console.log('Node-RED server running on port 8000');
+});
+
+RED.start();
+```
+
+## Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `type` | string | Yes* | Database type: `'mongodb'`, `'postgres'`, `'mysql'`, `'sqlite'` |
+| `url` | string | Yes | Database connection URL or file path |
+| `database` | string | No** | Database name |
+| `collectionNames` | object | No | Custom collection/table names |
+
+*For backward compatibility, `mongoUrl` or `postgresUrl` can be used instead of `type` + `url`
+
+**Database name is automatically extracted from the URL for PostgreSQL, MySQL, and SQLite. Required for MongoDB if not in URL.
+
+### Legacy Configuration (Backward Compatible)
+
+```javascript
+// Old MongoDB configuration still works
+storageModuleOptions: {
+    mongoUrl: 'mongodb://localhost:27017',
+    database: 'nodered'
+}
+```
+
+### Environment Variables
+
+```javascript
+const settings = {
+    storageModule: require('node-red-contrib-db-storage'),
+    storageModuleOptions: {
+        type: process.env.DB_TYPE || 'mongodb',
+        url: process.env.DATABASE_URL || 'mongodb://localhost:27017',
+        database: process.env.DB_NAME || 'nodered'
+    }
+};
+```
+
+### Default Collection/Table Names
+
+| Entity | Default Name |
+|--------|-------------|
+| Flows | `nodered-flows` |
+| Credentials | `nodered-credentials` |
+| Settings | `nodered-settings` |
+| Sessions | `nodered-sessions` |
+
+## API
+
+The plugin implements the Node-RED storage module interface:
+
+- `init(settings)` - Initialize the storage module
+- `getFlows()` / `saveFlows(flows)` - Manage flows
+- `getCredentials()` / `saveCredentials(credentials)` - Manage credentials
+- `getSettings()` / `saveSettings(settings)` - Manage settings
+- `getSessions()` / `saveSessions(sessions)` - Manage sessions
+- `getLibraryEntry(type, path)` / `saveLibraryEntry(type, path, meta, body)` - Manage library entries
+- `close()` - Close database connection
+
+## Creating Custom Adapters
+
+You can create your own database adapter by extending the `DatabaseAdapter` class and registering it with the factory:
+
+```javascript
+const { DatabaseAdapter, AdapterFactory } = require('node-red-contrib-db-storage/adapters');
+
+class MyCustomAdapter extends DatabaseAdapter {
+    constructor(config) {
+        super(config);
+        // Initialize your adapter
+        // this.url and this.databaseName are set by parent class
+    }
+
+    async connect() {
+        // Connect to your database
+    }
+
+    async close() {
+        // Close connection
+    }
+
+    async findAll(collectionName) {
+        // Validate input (inherited from parent)
+        this.validateCollectionName(collectionName);
+        // Return all documents as array
+    }
+
+    async saveAll(collectionName, objects) {
+        this.validateCollectionName(collectionName);
+        this.validateObjectArray(objects);
+        // Save all objects (replace existing)
+    }
+
+    async findOneByPath(collectionName, path) {
+        this.validateCollectionName(collectionName);
+        this.validatePath(path);
+        // Find by path, return body or {}
+    }
+
+    async saveOrUpdateByPath(collectionName, path, meta, body) {
+        this.validateCollectionName(collectionName);
+        this.validatePath(path);
+        // Upsert by path
+    }
+}
+
+// Register the adapter with the factory
+AdapterFactory.register(['mycustom', 'custom'], MyCustomAdapter);
+
+// Now you can use it in configuration:
+// { type: 'mycustom', url: '...', database: '...' }
+```
+
+### Using the Adapter Registry
+
+The `AdapterFactory` uses a registry pattern for extensibility:
+
+```javascript
+const { AdapterFactory } = require('node-red-contrib-db-storage/adapters');
+
+// Register a new adapter type
+AdapterFactory.register('redis', RedisAdapter);
+
+// Register with multiple aliases
+AdapterFactory.register(['cockroachdb', 'crdb'], CockroachAdapter);
+
+// Check if a type is registered
+AdapterFactory.isRegistered('redis'); // true
+
+// Get all supported types
+AdapterFactory.getSupportedTypes(); // ['mongodb', 'postgres', 'mysql', 'sqlite', 'redis', ...]
+
+// Unregister an adapter
+AdapterFactory.unregister('redis');
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/srmurali002/node-red-contrib-db-storage.git
+cd node-red-storage-plugin
+npm install
+```
+
+### Running Tests
+
+**Unit Tests** (with mocks, no database required):
+```bash
+npm test
+# or
+npm run test:unit
+```
+
+**Integration Tests** (require running databases):
+```bash
+# Start test databases
+npm run docker:up
+
+# Run all integration tests
+npm run test:integration
+
+# Run MongoDB integration tests only
+npm run test:integration:mongo
+
+# Run PostgreSQL integration tests only
+npm run test:integration:postgres
+
+# Run all tests (unit + integration)
+npm run test:all
+
+# Stop test databases
+npm run docker:down
+```
+
+**Environment Variables for Integration Tests:**
+```bash
+MONGO_URL=mongodb://localhost:27017
+MONGO_DATABASE=nodered_test
+POSTGRES_URL=postgresql://nodered:nodered@localhost:5432/nodered_test
+TEST_DATABASES=mongodb,postgres  # or just one
+SKIP_INTEGRATION=true  # skip integration tests
+```
+
+### Project Structure
+
+```
+node-red-contrib-db-storage/
+├── index.js                    # Main module
+├── constants.js                # Default configuration
+├── adapters/
+│   ├── index.js               # Adapter exports
+│   ├── DatabaseAdapter.js     # Base adapter class
+│   ├── AdapterFactory.js      # Adapter factory with registry
+│   ├── MongoAdapter.js        # MongoDB implementation
+│   ├── PostgresAdapter.js     # PostgreSQL implementation
+│   ├── MySQLAdapter.js        # MySQL/MariaDB implementation
+│   └── SQLiteAdapter.js       # SQLite implementation
+├── utils/
+│   ├── index.js               # Utility exports
+│   └── UrlParser.js           # URL parsing utilities
+├── tests/
+│   └── UrlParser.test.js      # URL parser tests
+├── examples/
+│   └── node-red-app.js        # Example application
+└── package.json
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### "storageModuleOptions is required"
+**Cause:** The settings object passed to Node-RED is missing the `storageModuleOptions` property.
+
+**Solution:** Ensure your settings include the required options:
+```javascript
+const settings = {
+    storageModule: require('node-red-contrib-db-storage'),
+    storageModuleOptions: {
+        type: 'mongodb',
+        url: 'mongodb://localhost:27017',
+        database: 'nodered'
+    }
+};
+```
+
+#### "Database URL is required"
+**Cause:** No database URL was provided in the configuration.
+
+**Solution:** Provide either:
+- `url` with `type` (new format)
+- `mongoUrl` (legacy MongoDB format)
+- `postgresUrl` (legacy PostgreSQL format)
+
+#### "Database name is required"
+**Cause:** The database name could not be determined from the URL or configuration.
+
+**Solution:** Either include the database name in the URL or add the `database` property:
+```javascript
+storageModuleOptions: {
+    type: 'mongodb',
+    url: 'mongodb://localhost:27017/nodered',  // Database in URL
+    // or
+    database: 'nodered'  // Explicit database name
+}
+```
+
+#### "PostgreSQL adapter requires the 'pg' package"
+**Cause:** The `pg` package is not installed but you're trying to use PostgreSQL.
+
+**Solution:** Install the PostgreSQL driver:
+```bash
+npm install pg
+```
+
+#### "MySQL adapter requires the 'mysql2' package"
+**Cause:** The `mysql2` package is not installed but you're trying to use MySQL/MariaDB.
+
+**Solution:** Install the MySQL driver:
+```bash
+npm install mysql2
+```
+
+#### "SQLite adapter requires the 'better-sqlite3' package"
+**Cause:** The `better-sqlite3` package is not installed but you're trying to use SQLite.
+
+**Solution:** Install the SQLite driver:
+```bash
+npm install better-sqlite3
+```
+
+#### Connection Timeouts
+**Cause:** Database server is not running or not accessible.
+
+**Solutions:**
+1. Verify the database server is running
+2. Check the connection URL is correct
+3. Ensure network/firewall allows the connection
+4. For Docker, ensure the container is healthy:
+   ```bash
+   docker ps
+   docker logs <container-name>
+   ```
+
+#### Data Not Persisting
+**Cause:** Multiple Node-RED instances using the same database, or data being overwritten.
+
+**Solutions:**
+1. Use unique collection names for each Node-RED instance
+2. Check that `saveFlows()` is being called on deploy
+3. Verify database connection is still active
+
+### Debug Mode
+
+Enable debug logging by setting the `DEBUG` environment variable:
+```bash
+DEBUG=* node your-app.js
+```
+
+### Database-Specific Issues
+
+#### MongoDB: "MongoNetworkError"
+- Check MongoDB is running: `mongosh --eval "db.runCommand('ping')"`
+- Verify connection string format: `mongodb://[user:pass@]host[:port]`
+
+#### PostgreSQL: "ECONNREFUSED"
+- Check PostgreSQL is running: `pg_isready`
+- Verify connection string format: `postgresql://user:pass@host:port/database`
+- Ensure the database exists: `psql -l`
+
+#### MySQL: "ECONNREFUSED" or "Access denied"
+- Check MySQL is running: `mysqladmin ping`
+- Verify connection string format: `mysql://user:pass@host:port/database`
+- Ensure user has necessary permissions: `GRANT ALL PRIVILEGES ON database.* TO 'user'@'host'`
+
+#### SQLite: "SQLITE_CANTOPEN"
+- Ensure the directory for the database file exists
+- Check file permissions for the target path
+- For in-memory databases, use `:memory:` as the URL
+
+### Getting Help
+
+If you're still experiencing issues:
+1. Check [existing issues](https://github.com/srmurali002/node-red-contrib-db-storage/issues)
+2. Create a new issue with:
+   - Node.js version
+   - Node-RED version
+   - Database type and version
+   - Full error message and stack trace
+   - Configuration (without sensitive data)
+
+## Changelog
+
+### v0.3.0 (2025)
+- Added MySQL/MariaDB adapter
+- Added SQLite adapter
+- **New**: Adapter registry pattern for extensibility (Open/Closed Principle)
+- **New**: URL parsing utility for automatic database name extraction
+- **New**: Input validation to prevent SQL injection
+- Refactored to encapsulate module state
+- Standardized configuration interface across all adapters
+- Comprehensive test coverage (136 tests)
+
+### v0.2.0 (2025)
+- **Breaking**: Restructured to support multiple databases
+- Added PostgreSQL adapter
+- Added database adapter abstraction layer
+- Added AdapterFactory for creating adapters
+- Backward compatible with existing MongoDB configurations
+- Improved error handling and validation
+- Comprehensive test suite
+
+### v0.1.3 (2025)
+- Fixed critical bugs in MongoDB operations
+- Added unit tests
+
+### v0.1.2 (2019)
+- Added configurable collection names
+
+## Roadmap
+
+- [x] Integration tests
+- [x] MySQL/MariaDB adapter
+- [x] SQLite adapter
+- [x] Adapter registry pattern
+- [x] Input validation and security
+- [ ] Redis adapter
+- [ ] Connection pooling configuration
+- [ ] Retry logic for connection failures
+- [ ] TypeScript definitions
+- [ ] Migration utilities between databases
+- [ ] Per-data-type adapter configuration (e.g., Redis for sessions, PostgreSQL for flows)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Adding a New Database Adapter
+
+1. Create a new adapter file in `adapters/` extending `DatabaseAdapter`
+2. Register it with `AdapterFactory.register()` in `AdapterFactory.js`
+3. Export it from `adapters/index.js`
+4. Add unit tests in `adapters/YourAdapter.test.js`
+5. Add integration tests in `adapters/YourAdapter.integration.test.js`
+6. Update documentation in README.md
+
+## License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Credits
+
+Multi-database support and continued development by [Muralidhar Reddy Challa](https://github.com/srmurali002).
+
+## Support
+
+If you encounter any issues or have questions, please [open an issue](https://github.com/srmurali002/node-red-contrib-db-storage/issues).

package/adapters/AdapterFactory.js

@@ -0,0 +1,87 @@
+const MongoAdapter = require('./MongoAdapter');
+const PostgresAdapter = require('./PostgresAdapter');
+const MySQLAdapter = require('./MySQLAdapter');
+const SQLiteAdapter = require('./SQLiteAdapter');
+
+/**
+ * Factory for creating database adapters using a registry pattern.
+ * Follows Open/Closed Principle - open for extension, closed for modification.
+ *
+ * All adapters use a standardized configuration interface:
+ * @typedef {Object} AdapterConfig
+ * @property {string} url - Required: Database connection URL
+ * @property {string} database - Required: Database name
+ */
+class AdapterFactory {
+  // Private registry for adapter types
+  static #registry = new Map();
+
+  /**
+   * Register a new adapter type
+   * @param {string|Array<string>} types - The type name(s) to register (e.g., 'mongodb' or ['mongodb', 'mongo'])
+   * @param {Function} AdapterClass - The adapter class constructor
+   */
+  static register(types, AdapterClass) {
+    const typeArray = Array.isArray(types) ? types : [types];
+    for (const type of typeArray) {
+      this.#registry.set(type.toLowerCase(), AdapterClass);
+    }
+  }
+
+  /**
+   * Unregister an adapter type
+   * @param {string} type - The type name to unregister
+   */
+  static unregister(type) {
+    this.#registry.delete(type.toLowerCase());
+  }
+
+  /**
+   * Create a database adapter based on the type
+   * @param {string} type - The database type ('mongodb', 'postgres', 'mysql', 'sqlite')
+   * @param {AdapterConfig} config - Standardized configuration for the adapter
+   * @returns {DatabaseAdapter} The database adapter instance
+   */
+  static create(type, config) {
+    const AdapterClass = this.#registry.get(type.toLowerCase());
+
+    if (!AdapterClass) {
+      const supportedTypes = this.getSupportedTypes().join(', ');
+      throw new Error(`Unsupported database type: ${type}. Supported types: ${supportedTypes}`);
+    }
+
+    return new AdapterClass(config);
+  }
+
+  /**
+   * Check if an adapter type is registered
+   * @param {string} type - The type name to check
+   * @returns {boolean} True if the type is registered
+   */
+  static isRegistered(type) {
+    return this.#registry.has(type.toLowerCase());
+  }
+
+  /**
+   * Get list of supported database types
+   * @returns {Array<string>} List of supported database types
+   */
+  static getSupportedTypes() {
+    return [...new Set(this.#registry.keys())];
+  }
+
+  /**
+   * Clear all registered adapters (useful for testing)
+   */
+  static clearRegistry() {
+    this.#registry.clear();
+  }
+}
+
+// Register built-in adapters
+AdapterFactory.register(['mongodb', 'mongo'], MongoAdapter);
+AdapterFactory.register(['postgresql', 'postgres', 'pg'], PostgresAdapter);
+AdapterFactory.register(['mysql', 'mariadb'], MySQLAdapter);
+AdapterFactory.register(['sqlite', 'sqlite3'], SQLiteAdapter);
+
+module.exports = AdapterFactory;