qtopology-mysql

library2.2.1jsnpmunverified

MySQL-based coordination storage backend for QTopology distributed topology framework. Version 2.2.1 is the current stable release. It provides database schema initialization, upgrade scripts, and stored procedures for managing worker registration, leader election, topology tracking, and message queues. Key differentiator: it handles schema migration automatically on instantiation, similar to Flyway-like versioning. The library ships with TypeScript declarations and is intended for use with Node.js environments running MySQL 5.7+.

database devops

npm install qtopology-mysql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · QTOPOLOGY-MYSQL

qtopology-mysql

databasejavascriptv2.2.1

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.

MySqlCoordinationStorage

✓ import { MySqlCoordinationStorage } from 'qtopology-mysql';

✗ const MySqlCoordinationStorage = require('qtopology-mysql');

Package is ESM-only since v2.x, TypeScript declarations included.

default

✓ import QTopologyMySQL from 'qtopology-mysql';

✗ const QTopologyMySQL = require('qtopology-mysql').default;

Default export is the same as MySqlCoordinationStorage.

initDatabase

✓ import { initDatabase } from 'qtopology-mysql';

✗ import { initialize } from 'qtopology-mysql';

Function to manually initialize the database schema.

Initializes MySQL storage connection and schema, then fetches the current topology leader.

import { MySqlCoordinationStorage } from 'qtopology-mysql'; import mysql from 'mysql2/promise'; const connection = await mysql.createConnection({ host: process.env.DB_HOST ?? 'localhost', user: process.env.DB_USER ?? 'root', password: process.env.DB_PASSWORD ?? '', database: process.env.DB_NAME ?? 'qtopology' }); const storage = new MySqlCoordinationStorage(connection); await storage.initialize(); // runs schema migrations if needed const leader = await storage.getLeader(); console.log('Current leader:', leader);

Debug

Known issues

breakingVersion 2.x dropped support for callback-based initialization. Async/await or Promise-based initialization is now mandatory.

fix

Replace callback-based initialization with async/await pattern.

affects: >=2.0.0

breakingDatabase schema auto-upgrades may fail if MySQL user does not have CREATE, ALTER, DROP privileges.

fix

Ensure the MySQL user has sufficient privileges to run DDL statements during initialization.

affects: >=1.0.0

gotchaThe package does not manage connection pooling; it expects the caller to pass a single connection. Using a pool can lead to unexpected behavior.

fix

Use mysql2/promise and create a single connection instance, not a pool, for storage operations.

affects: >=1.0.0

gotchaStored procedures are recreated on every database initialization, which may reset any custom modifications.

fix

Do not manually modify stored procedures; they are managed by the package.

affects: >=1.0.0

Errors

Common errors & fixes

Error: ER_ACCESS_DENIED_ERROR: Access denied for user 'user'@'host' to database 'qtopology'

MySQL user lacks permissions to create or modify the database schema during initialization.

fix

Grant necessary privileges: GRANT ALL ON qtopology.* TO 'user'@'host';

TypeError: Cannot read properties of undefined (reading 'query')

Connection is not passed as an argument to MySqlCoordinationStorage constructor or is undefined.

fix

Ensure a valid mysql2 connection object is passed: new MySqlCoordinationStorage(connection).

Error: listen EADDRINUSE :::3306

Another process is already using the default MySQL port. Not directly a qtopology-mysql error, but common in dev environments.

fix

Stop the conflicting process or change MySQL port in connection config.

Upgrade

Version history

2.2.1latest on npm

Audit

Dependencies

mysqlrequiredRequired for MySQL database connectivity

qtopologyrequiredCore QTopology library for topology orchestration

Agent activity

13 hits · last 30 days

node