{"id":43725,"library":"qtopology-mysql","title":"qtopology-mysql","description":"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+.","status":"active","version":"2.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/qminer/qtopology-mysql","tags":["javascript","node.js","typescript"],"install":[{"cmd":"npm install qtopology-mysql","lang":"bash","label":"npm"},{"cmd":"yarn add qtopology-mysql","lang":"bash","label":"yarn"},{"cmd":"pnpm add qtopology-mysql","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for MySQL database connectivity","package":"mysql","optional":false},{"reason":"Core QTopology library for topology orchestration","package":"qtopology","optional":false}],"imports":[{"note":"Package is ESM-only since v2.x, TypeScript declarations included.","wrong":"const MySqlCoordinationStorage = require('qtopology-mysql');","symbol":"MySqlCoordinationStorage","correct":"import { MySqlCoordinationStorage } from 'qtopology-mysql';"},{"note":"Default export is the same as MySqlCoordinationStorage.","wrong":"const QTopologyMySQL = require('qtopology-mysql').default;","symbol":"default","correct":"import QTopologyMySQL from 'qtopology-mysql';"},{"note":"Function to manually initialize the database schema.","wrong":"import { initialize } from 'qtopology-mysql';","symbol":"initDatabase","correct":"import { initDatabase } from 'qtopology-mysql';"}],"quickstart":{"code":"import { MySqlCoordinationStorage } from 'qtopology-mysql';\nimport mysql from 'mysql2/promise';\n\nconst connection = await mysql.createConnection({\n  host: process.env.DB_HOST ?? 'localhost',\n  user: process.env.DB_USER ?? 'root',\n  password: process.env.DB_PASSWORD ?? '',\n  database: process.env.DB_NAME ?? 'qtopology'\n});\n\nconst storage = new MySqlCoordinationStorage(connection);\nawait storage.initialize(); // runs schema migrations if needed\n\nconst leader = await storage.getLeader();\nconsole.log('Current leader:', leader);","lang":"typescript","description":"Initializes MySQL storage connection and schema, then fetches the current topology leader."},"warnings":[{"fix":"Replace callback-based initialization with async/await pattern.","message":"Version 2.x dropped support for callback-based initialization. Async/await or Promise-based initialization is now mandatory.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure the MySQL user has sufficient privileges to run DDL statements during initialization.","message":"Database schema auto-upgrades may fail if MySQL user does not have CREATE, ALTER, DROP privileges.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Use mysql2/promise and create a single connection instance, not a pool, for storage operations.","message":"The package does not manage connection pooling; it expects the caller to pass a single connection. Using a pool can lead to unexpected behavior.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Do not manually modify stored procedures; they are managed by the package.","message":"Stored procedures are recreated on every database initialization, which may reset any custom modifications.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'2.2.1':16 '5.7':74 'automat':49 'backend':9 'base':6 'coordin':7 'current':19 'databas':24 'declar':63 'differenti':44 'distribut':12 'elect':37 'environ':71 'flyway':55 'flyway-lik':54 'framework':14 'handl':46 'initi':26 'instanti':51 'intend':66 'javascript':75 'key':43 'leader':36 'librari':59 'like':56 'manag':33 'messag':41 'migrat':48 'mysql':3,5,73 'mysql-bas':4 'node.js':70,76 'procedur':31 'provid':23 'qtopolog':2,11 'qtopology-mysql':1 'queue':42 'registr':35 'releas':21 'run':72 'schema':25,47 'script':28 'ship':60 'similar':52 'stabl':20 'storag':8 'store':30 'topolog':13,38 'track':39 'typescript':62,77 'upgrad':27 'use':68 'version':15,57 'worker':34","created_at":"2026-06-05T17:01:10.674734+00:00","updated_at":"2026-06-05T17:01:10.674734+00:00","problems":[{"fix":"Grant necessary privileges: GRANT ALL ON qtopology.* TO 'user'@'host';","cause":"MySQL user lacks permissions to create or modify the database schema during initialization.","error":"Error: ER_ACCESS_DENIED_ERROR: Access denied for user 'user'@'host' to database 'qtopology'"},{"fix":"Ensure a valid mysql2 connection object is passed: new MySqlCoordinationStorage(connection).","cause":"Connection is not passed as an argument to MySqlCoordinationStorage constructor or is undefined.","error":"TypeError: Cannot read properties of undefined (reading 'query')"},{"fix":"Stop the conflicting process or change MySQL port in connection config.","cause":"Another process is already using the default MySQL port. Not directly a qtopology-mysql error, but common in dev environments.","error":"Error: listen EADDRINUSE :::3306"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/qminer/qtopology-mysql#readme","github":"https://github.com/qminer/qtopology-mysql","docs":null,"changelog":null,"pypi":null,"npm":"qtopology-mysql","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}