@underpostnet/underpost 2.90.4 → 2.95.0

package/src/cli/db.js

@@ -1,13 +1,16 @@
 /**
- * UnderpostDB CLI index module
+ * UnderpostDB CLI module
  * @module src/cli/db.js
  * @namespace UnderpostDB
+ * @description Manages database operations, backups, and cluster metadata for Kubernetes deployments.
+ * Supports MariaDB and MongoDB with import/export capabilities, Git integration, and multi-pod operations.
  */
 
 import { mergeFile, splitFileFactory } from '../server/conf.js';
 import { loggerFactory } from '../server/logger.js';
 import { shellExec } from '../server/process.js';
 import fs from 'fs-extra';
+import os from 'os';
 import UnderpostDeploy from './deploy.js';
 import UnderpostCron from './cron.js';
 import { DataBaseProvider } from '../db/DataBaseProvider.js';
@@ -16,33 +19,768 @@ import { loadReplicas, pathPortAssignmentFactory } from '../server/conf.js';
 const logger = loggerFactory(import.meta);
 
 /**
- * @class UnderpostDB
- * @description Manages database operations and backups.
- * This class provides a set of static methods to handle database operations,
- * including importing and exporting data, managing database backups, and
- * handling database connections for different providers (e.g., MariaDB, MongoDB).
+ * Constants for database operations
+ * @constant {number} MAX_BACKUP_RETENTION - Maximum number of backups to retain
+ * @memberof UnderpostDB
+ */
+const MAX_BACKUP_RETENTION = 5;
+
+/**
+ * Timeout for kubectl operations in milliseconds
+ * @constant {number} KUBECTL_TIMEOUT
+ * @memberof UnderpostDB
+ */
+const KUBECTL_TIMEOUT = 300000; // 5 minutes
+
+/**
+ * @typedef {Object} DatabaseOptions
+ * @memberof UnderpostDB
+ * @property {boolean} [import=false] - Flag to import data from a backup
+ * @property {boolean} [export=false] - Flag to export data to a backup
+ * @property {string} [podName=''] - Comma-separated list of pod names or patterns
+ * @property {string} [nodeName=''] - Comma-separated list of node names for pod filtering
+ * @property {string} [ns='default'] - Kubernetes namespace
+ * @property {string} [collections=''] - Comma-separated list of collections to include
+ * @property {string} [outPath=''] - Output path for backup files
+ * @property {boolean} [drop=false] - Flag to drop the database before importing
+ * @property {boolean} [preserveUUID=false] - Flag to preserve UUIDs during import
+ * @property {boolean} [git=false] - Flag to enable Git integration
+ * @property {string} [hosts=''] - Comma-separated list of hosts to include
+ * @property {string} [paths=''] - Comma-separated list of paths to include
+ * @property {string} [labelSelector=''] - Kubernetes label selector for pods
+ * @property {boolean} [allPods=false] - Flag to target all matching pods
+ * @property {boolean} [primaryPod=false] - Flag to automatically detect and use MongoDB primary pod
+ * @property {boolean} [stats=false] - Flag to display collection/table statistics
+ */
+
+/**
+ * @typedef {Object} PodInfo
+ * @memberof UnderpostDB
+ * @property {string} NAME - Pod name
+ * @property {string} NAMESPACE - Pod namespace
+ * @property {string} NODE - Node where pod is running
+ * @property {string} STATUS - Pod status
+ * @property {string} [IP] - Pod IP address
+ */
+
+/**
+ * @typedef {Object} DatabaseConfig
  * @memberof UnderpostDB
+ * @property {string} provider - Database provider (mariadb, mongoose)
+ * @property {string} name - Database name
+ * @property {string} user - Database user
+ * @property {string} password - Database password
+ * @property {string} hostFolder - Host folder path
+ * @property {string} host - Host identifier
+ * @property {string} path - Path identifier
+ * @property {number} [currentBackupTimestamp] - Timestamp of current backup
+ */
+
+/**
+ * @class UnderpostDB
+ * @description Manages database operations and backups for Kubernetes-based deployments.
+ * Provides comprehensive database management including import/export, multi-pod targeting,
+ * Git integration, and cluster metadata management.
  */
 class UnderpostDB {
   static API = {
     /**
+     * Helper: Validates namespace name
+     * @private
+     * @param {string} namespace - Namespace to validate
+     * @returns {boolean} True if valid
+     */
+    _validateNamespace(namespace) {
+      if (!namespace || typeof namespace !== 'string') return false;
+      // Kubernetes namespace naming rules: lowercase alphanumeric, -, max 63 chars
+      return /^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/.test(namespace) && namespace.length <= 63;
+    },
+
+    /**
+     * Helper: Validates pod name
+     * @private
+     * @param {string} podName - Pod name to validate
+     * @returns {boolean} True if valid
+     */
+    _validatePodName(podName) {
+      if (!podName || typeof podName !== 'string') return false;
+      // Kubernetes pod naming rules: lowercase alphanumeric, -, max 253 chars
+      return /^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/.test(podName) && podName.length <= 253;
+    },
+
+    /**
+     * Helper: Gets filtered pods based on criteria
+     * @private
+     * @param {Object} criteria - Filter criteria
+     * @param {string} [criteria.podNames] - Comma-separated pod name patterns
+     * @param {string} [criteria.nodeNames] - Comma-separated node names
+     * @param {string} [criteria.namespace='default'] - Kubernetes namespace
+     * @param {string} [criteria.labelSelector] - Label selector
+     * @param {string} [criteria.deployId] - Deployment ID pattern
+     * @returns {Array<PodInfo>} Filtered pod list
+     */
+    _getFilteredPods(criteria = {}) {
+      const { podNames, nodeNames, namespace = 'default', labelSelector, deployId } = criteria;
+
+      try {
+        // Get all pods using UnderpostDeploy.API.get
+        let pods = UnderpostDeploy.API.get(deployId || '', 'pods', namespace);
+
+        // Filter by pod names if specified
+        if (podNames) {
+          const patterns = podNames.split(',').map((p) => p.trim());
+          pods = pods.filter((pod) => {
+            return patterns.some((pattern) => {
+              // Support wildcards
+              const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$');
+              return regex.test(pod.NAME);
+            });
+          });
+        }
+
+        // Filter by node names if specified (only if NODE is not '<none>')
+        if (nodeNames) {
+          const nodes = nodeNames.split(',').map((n) => n.trim());
+          pods = pods.filter((pod) => {
+            // Skip filtering if NODE is '<none>' or undefined
+            if (!pod.NODE || pod.NODE === '<none>') {
+              return true;
+            }
+            return nodes.includes(pod.NODE);
+          });
+        }
+
+        // Filter by label selector if specified
+        if (labelSelector) {
+          // Note: UnderpostDeploy.API.get doesn't support label selectors directly
+          // This would require a separate kubectl command
+          logger.warn('Label selector filtering requires additional implementation');
+        }
+
+        logger.info(`Found ${pods.length} pod(s) matching criteria`, { criteria, podNames: pods.map((p) => p.NAME) });
+        return pods;
+      } catch (error) {
+        logger.error('Error filtering pods', { error: error.message, criteria });
+        return [];
+      }
+    },
+
+    /**
+     * Helper: Executes kubectl command with error handling
+     * @private
+     * @param {string} command - kubectl command to execute
+     * @param {Object} options - Execution options
+     * @param {string} [options.context=''] - Command context for logging
+     * @returns {string|null} Command output or null on error
+     */
+    _executeKubectl(command, options = {}) {
+      const { context = '' } = options;
+
+      try {
+        logger.info(`Executing kubectl command`, { command, context });
+        return shellExec(command, { stdout: true });
+      } catch (error) {
+        logger.error(`kubectl command failed`, { command, error: error.message, context });
+        throw error;
+      }
+    },
+
+    /**
+     * Helper: Copies file to pod
+     * @private
+     * @param {Object} params - Copy parameters
+     * @param {string} params.sourcePath - Source file path
+     * @param {string} params.podName - Target pod name
+     * @param {string} params.namespace - Pod namespace
+     * @param {string} params.destPath - Destination path in pod
+     * @returns {boolean} Success status
+     */
+    _copyToPod({ sourcePath, podName, namespace, destPath }) {
+      try {
+        const command = `sudo kubectl cp ${sourcePath} ${namespace}/${podName}:${destPath}`;
+        UnderpostDB.API._executeKubectl(command, { context: `copy to pod ${podName}` });
+        return true;
+      } catch (error) {
+        logger.error('Failed to copy file to pod', { sourcePath, podName, destPath, error: error.message });
+        return false;
+      }
+    },
+
+    /**
+     * Helper: Copies file from pod
+     * @private
+     * @param {Object} params - Copy parameters
+     * @param {string} params.podName - Source pod name
+     * @param {string} params.namespace - Pod namespace
+     * @param {string} params.sourcePath - Source path in pod
+     * @param {string} params.destPath - Destination file path
+     * @returns {boolean} Success status
+     */
+    _copyFromPod({ podName, namespace, sourcePath, destPath }) {
+      try {
+        const command = `sudo kubectl cp ${namespace}/${podName}:${sourcePath} ${destPath}`;
+        UnderpostDB.API._executeKubectl(command, { context: `copy from pod ${podName}` });
+        return true;
+      } catch (error) {
+        logger.error('Failed to copy file from pod', { podName, sourcePath, destPath, error: error.message });
+        return false;
+      }
+    },
+
+    /**
+     * Helper: Executes command in pod
+     * @private
+     * @param {Object} params - Execution parameters
+     * @param {string} params.podName - Pod name
+     * @param {string} params.namespace - Pod namespace
+     * @param {string} params.command - Command to execute
+     * @returns {string|null} Command output or null
+     */
+    _execInPod({ podName, namespace, command }) {
+      try {
+        const kubectlCmd = `sudo kubectl exec -n ${namespace} -i ${podName} -- sh -c "${command}"`;
+        return UnderpostDB.API._executeKubectl(kubectlCmd, { context: `exec in pod ${podName}` });
+      } catch (error) {
+        logger.error('Failed to execute command in pod', { podName, command, error: error.message });
+        throw error;
+      }
+    },
+
+    /**
+     * Helper: Manages Git repository for backups
+     * @private
+     * @param {Object} params - Git parameters
+     * @param {string} params.repoName - Repository name
+     * @param {string} params.operation - Operation (clone, pull, commit, push)
+     * @param {string} [params.message=''] - Commit message
+     * @returns {boolean} Success status
+     */
+    _manageGitRepo({ repoName, operation, message = '' }) {
+      try {
+        const username = process.env.GITHUB_USERNAME;
+        if (!username) {
+          logger.error('GITHUB_USERNAME environment variable not set');
+          return false;
+        }
+
+        const repoPath = `../${repoName}`;
+
+        switch (operation) {
+          case 'clone':
+            if (!fs.existsSync(repoPath)) {
+              shellExec(`cd .. && underpost clone ${username}/${repoName}`);
+              logger.info(`Cloned repository: ${repoName}`);
+            }
+            break;
+
+          case 'pull':
+            if (fs.existsSync(repoPath)) {
+              shellExec(`cd ${repoPath} && git checkout . && git clean -f -d`);
+              shellExec(`cd ${repoPath} && underpost pull . ${username}/${repoName}`, {
+                silent: true,
+              });
+              logger.info(`Pulled repository: ${repoName}`);
+            }
+            break;
+
+          case 'commit':
+            if (fs.existsSync(repoPath)) {
+              shellExec(`cd ${repoPath} && git add .`);
+              shellExec(`underpost cmt ${repoPath} backup '' '${message}'`);
+              logger.info(`Committed to repository: ${repoName}`, { message });
+            }
+            break;
+
+          case 'push':
+            if (fs.existsSync(repoPath)) {
+              shellExec(`cd ${repoPath} && underpost push . ${username}/${repoName}`, { silent: true });
+              logger.info(`Pushed repository: ${repoName}`);
+            }
+            break;
+
+          default:
+            logger.warn(`Unknown git operation: ${operation}`);
+            return false;
+        }
+
+        return true;
+      } catch (error) {
+        logger.error(`Git operation failed`, { repoName, operation, error: error.message });
+        return false;
+      }
+    },
+
+    /**
+     * Helper: Manages backup timestamps and cleanup
+     * @private
+     * @param {string} backupPath - Backup directory path
+     * @param {number} newTimestamp - New backup timestamp
+     * @param {boolean} shouldCleanup - Whether to cleanup old backups
+     * @returns {Object} Backup info with current and removed timestamps
+     */
+    _manageBackupTimestamps(backupPath, newTimestamp, shouldCleanup) {
+      try {
+        if (!fs.existsSync(backupPath)) {
+          fs.mkdirSync(backupPath, { recursive: true });
+        }
+
+        // Delete empty folders
+        shellExec(`cd ${backupPath} && find . -type d -empty -delete`);
+
+        const times = fs.readdirSync(backupPath);
+        const validTimes = times.map((t) => parseInt(t)).filter((t) => !isNaN(t));
+
+        const currentBackupTimestamp = validTimes.length > 0 ? Math.max(...validTimes) : null;
+        const removeBackupTimestamp = validTimes.length > 0 ? Math.min(...validTimes) : null;
+
+        // Cleanup old backups if we have too many
+        if (shouldCleanup && validTimes.length >= MAX_BACKUP_RETENTION && removeBackupTimestamp) {
+          const removeDir = `${backupPath}/${removeBackupTimestamp}`;
+          logger.info('Removing old backup', { path: removeDir });
+          fs.removeSync(removeDir);
+        }
+
+        // Create new backup directory
+        if (shouldCleanup) {
+          const newBackupDir = `${backupPath}/${newTimestamp}`;
+          logger.info('Creating new backup directory', { path: newBackupDir });
+          fs.mkdirSync(newBackupDir, { recursive: true });
+        }
+
+        return {
+          current: currentBackupTimestamp,
+          removed: removeBackupTimestamp,
+          count: validTimes.length,
+        };
+      } catch (error) {
+        logger.error('Error managing backup timestamps', { backupPath, error: error.message });
+        return { current: null, removed: null, count: 0 };
+      }
+    },
+
+    /**
+     * Helper: Performs MariaDB import operation
+     * @private
+     * @param {Object} params - Import parameters
+     * @param {PodInfo} params.pod - Target pod
+     * @param {string} params.namespace - Namespace
+     * @param {string} params.dbName - Database name
+     * @param {string} params.user - Database user
+     * @param {string} params.password - Database password
+     * @param {string} params.sqlPath - SQL file path
+     * @returns {boolean} Success status
+     */
+    _importMariaDB({ pod, namespace, dbName, user, password, sqlPath }) {
+      try {
+        const podName = pod.NAME;
+        const containerSqlPath = `/${dbName}.sql`;
+
+        logger.info('Importing MariaDB database', { podName, dbName });
+
+        // Remove existing SQL file in container
+        UnderpostDB.API._execInPod({
+          podName,
+          namespace,
+          command: `rm -rf ${containerSqlPath}`,
+        });
+
+        // Copy SQL file to pod
+        if (
+          !UnderpostDB.API._copyToPod({
+            sourcePath: sqlPath,
+            podName,
+            namespace,
+            destPath: containerSqlPath,
+          })
+        ) {
+          return false;
+        }
+
+        // Create database if it doesn't exist
+        UnderpostDB.API._executeKubectl(
+          `kubectl exec -n ${namespace} -i ${podName} -- mariadb -p${password} -e 'CREATE DATABASE IF NOT EXISTS ${dbName};'`,
+          { context: `create database ${dbName}` },
+        );
+
+        // Import SQL file
+        const importCmd = `mariadb -u ${user} -p${password} ${dbName} < ${containerSqlPath}`;
+        UnderpostDB.API._execInPod({ podName, namespace, command: importCmd });
+
+        logger.info('Successfully imported MariaDB database', { podName, dbName });
+        return true;
+      } catch (error) {
+        logger.error('MariaDB import failed', { podName: pod.NAME, dbName, error: error.message });
+        return false;
+      }
+    },
+
+    /**
+     * Helper: Performs MariaDB export operation
+     * @private
+     * @param {Object} params - Export parameters
+     * @param {PodInfo} params.pod - Source pod
+     * @param {string} params.namespace - Namespace
+     * @param {string} params.dbName - Database name
+     * @param {string} params.user - Database user
+     * @param {string} params.password - Database password
+     * @param {string} params.outputPath - Output file path
+     * @returns {boolean} Success status
+     */
+    async _exportMariaDB({ pod, namespace, dbName, user, password, outputPath }) {
+      try {
+        const podName = pod.NAME;
+        const containerSqlPath = `/home/${dbName}.sql`;
+
+        logger.info('Exporting MariaDB database', { podName, dbName });
+
+        // Remove existing SQL file in container
+        UnderpostDB.API._execInPod({
+          podName,
+          namespace,
+          command: `rm -rf ${containerSqlPath}`,
+        });
+
+        // Dump database
+        const dumpCmd = `mariadb-dump --user=${user} --password=${password} --lock-tables ${dbName} > ${containerSqlPath}`;
+        UnderpostDB.API._execInPod({ podName, namespace, command: dumpCmd });
+
+        // Copy SQL file from pod
+        if (
+          !UnderpostDB.API._copyFromPod({
+            podName,
+            namespace,
+            sourcePath: containerSqlPath,
+            destPath: outputPath,
+          })
+        ) {
+          return false;
+        }
+
+        // Split file if it exists
+        if (fs.existsSync(outputPath)) {
+          await splitFileFactory(dbName, outputPath);
+        }
+
+        logger.info('Successfully exported MariaDB database', { podName, dbName, outputPath });
+        return true;
+      } catch (error) {
+        logger.error('MariaDB export failed', { podName: pod.NAME, dbName, error: error.message });
+        return false;
+      }
+    },
+
+    /**
+     * Helper: Performs MongoDB import operation
+     * @private
+     * @param {Object} params - Import parameters
+     * @param {PodInfo} params.pod - Target pod
+     * @param {string} params.namespace - Namespace
+     * @param {string} params.dbName - Database name
+     * @param {string} params.bsonPath - BSON directory path
+     * @param {boolean} params.drop - Whether to drop existing database
+     * @param {boolean} params.preserveUUID - Whether to preserve UUIDs
+     * @returns {boolean} Success status
+     */
+    _importMongoDB({ pod, namespace, dbName, bsonPath, drop, preserveUUID }) {
+      try {
+        const podName = pod.NAME;
+        const containerBsonPath = `/${dbName}`;
+
+        logger.info('Importing MongoDB database', { podName, dbName });
+
+        // Remove existing BSON directory in container
+        UnderpostDB.API._execInPod({
+          podName,
+          namespace,
+          command: `rm -rf ${containerBsonPath}`,
+        });
+
+        // Copy BSON directory to pod
+        if (
+          !UnderpostDB.API._copyToPod({
+            sourcePath: bsonPath,
+            podName,
+            namespace,
+            destPath: containerBsonPath,
+          })
+        ) {
+          return false;
+        }
+
+        // Restore database
+        const restoreCmd = `mongorestore -d ${dbName} ${containerBsonPath}${drop ? ' --drop' : ''}${
+          preserveUUID ? ' --preserveUUID' : ''
+        }`;
+        UnderpostDB.API._execInPod({ podName, namespace, command: restoreCmd });
+
+        logger.info('Successfully imported MongoDB database', { podName, dbName });
+        return true;
+      } catch (error) {
+        logger.error('MongoDB import failed', { podName: pod.NAME, dbName, error: error.message });
+        return false;
+      }
+    },
+
+    /**
+     * Helper: Performs MongoDB export operation
+     * @private
+     * @param {Object} params - Export parameters
+     * @param {PodInfo} params.pod - Source pod
+     * @param {string} params.namespace - Namespace
+     * @param {string} params.dbName - Database name
+     * @param {string} params.outputPath - Output directory path
+     * @param {string} [params.collections=''] - Comma-separated collection list
+     * @returns {boolean} Success status
+     */
+    _exportMongoDB({ pod, namespace, dbName, outputPath, collections = '' }) {
+      try {
+        const podName = pod.NAME;
+        const containerBsonPath = `/${dbName}`;
+
+        logger.info('Exporting MongoDB database', { podName, dbName, collections });
+
+        // Remove existing BSON directory in container
+        UnderpostDB.API._execInPod({
+          podName,
+          namespace,
+          command: `rm -rf ${containerBsonPath}`,
+        });
+
+        // Dump database or specific collections
+        if (collections) {
+          const collectionList = collections.split(',').map((c) => c.trim());
+          for (const collection of collectionList) {
+            const dumpCmd = `mongodump -d ${dbName} --collection ${collection} -o /`;
+            UnderpostDB.API._execInPod({ podName, namespace, command: dumpCmd });
+          }
+        } else {
+          const dumpCmd = `mongodump -d ${dbName} -o /`;
+          UnderpostDB.API._execInPod({ podName, namespace, command: dumpCmd });
+        }
+
+        // Copy BSON directory from pod
+        if (
+          !UnderpostDB.API._copyFromPod({
+            podName,
+            namespace,
+            sourcePath: containerBsonPath,
+            destPath: outputPath,
+          })
+        ) {
+          return false;
+        }
+
+        logger.info('Successfully exported MongoDB database', { podName, dbName, outputPath });
+        return true;
+      } catch (error) {
+        logger.error('MongoDB export failed', { podName: pod.NAME, dbName, error: error.message });
+        return false;
+      }
+    },
+
+    /**
+     * Helper: Gets MongoDB collection statistics
+     * @private
+     * @param {Object} params - Parameters
+     * @param {string} params.podName - Pod name
+     * @param {string} params.namespace - Namespace
+     * @param {string} params.dbName - Database name
+     * @returns {Object|null} Collection statistics or null on error
+     */
+    _getMongoStats({ podName, namespace, dbName }) {
+      try {
+        logger.info('Getting MongoDB collection statistics', { podName, dbName });
+
+        // Use db.getSiblingDB() instead of 'use' command
+        const script = `db.getSiblingDB('${dbName}').getCollectionNames().map(function(c) { return { collection: c, count: db.getSiblingDB('${dbName}')[c].countDocuments() }; })`;
+
+        // Execute the script
+        const command = `sudo kubectl exec -n ${namespace} -i ${podName} -- mongosh --quiet --eval "${script}"`;
+        const output = shellExec(command, { stdout: true, silent: true });
+
+        if (!output || output.trim() === '') {
+          logger.warn('No collections found or empty output');
+          return null;
+        }
+
+        // Clean the output: remove newlines, handle EJSON format, replace single quotes with double quotes
+        let cleanedOutput = output
+          .trim()
+          .replace(/\n/g, '')
+          .replace(/\s+/g, ' ')
+          .replace(/NumberLong\("(\d+)"\)/g, '$1')
+          .replace(/NumberLong\((\d+)\)/g, '$1')
+          .replace(/NumberInt\("(\d+)"\)/g, '$1')
+          .replace(/NumberInt\((\d+)\)/g, '$1')
+          .replace(/ISODate\("([^"]+)"\)/g, '"$1"')
+          .replace(/'/g, '"')
+          .replace(/(\w+):/g, '"$1":');
+
+        try {
+          const stats = JSON.parse(cleanedOutput);
+          logger.info('MongoDB statistics retrieved', { dbName, collections: stats.length });
+          return stats;
+        } catch (parseError) {
+          logger.error('Failed to parse MongoDB output', {
+            podName,
+            dbName,
+            error: parseError.message,
+            rawOutput: output.substring(0, 200),
+            cleanedOutput: cleanedOutput.substring(0, 200),
+          });
+          return null;
+        }
+      } catch (error) {
+        logger.error('Failed to get MongoDB statistics', { podName, dbName, error: error.message });
+        return null;
+      }
+    },
+
+    /**
+     * Helper: Gets MariaDB table statistics
+     * @private
+     * @param {Object} params - Parameters
+     * @param {string} params.podName - Pod name
+     * @param {string} params.namespace - Namespace
+     * @param {string} params.dbName - Database name
+     * @param {string} params.user - Database user
+     * @param {string} params.password - Database password
+     * @returns {Object|null} Table statistics or null on error
+     */
+    _getMariaDBStats({ podName, namespace, dbName, user, password }) {
+      try {
+        logger.info('Getting MariaDB table statistics', { podName, dbName });
+
+        const command = `sudo kubectl exec -n ${namespace} -i ${podName} -- mariadb -u ${user} -p${password} ${dbName} -e "SELECT TABLE_NAME as 'table', TABLE_ROWS as 'count' FROM information_schema.TABLES WHERE TABLE_SCHEMA = '${dbName}' ORDER BY TABLE_NAME;" --skip-column-names --batch`;
+        const output = shellExec(command, { stdout: true, silent: true });
+
+        if (!output || output.trim() === '') {
+          logger.warn('No tables found or empty output');
+          return null;
+        }
+
+        // Parse the output (tab-separated values)
+        const lines = output.trim().split('\n');
+        const stats = lines.map((line) => {
+          const [table, count] = line.split('\t');
+          return { table, count: parseInt(count) || 0 };
+        });
+
+        logger.info('MariaDB statistics retrieved', { dbName, tables: stats.length });
+        return stats;
+      } catch (error) {
+        logger.error('Failed to get MariaDB statistics', { podName, dbName, error: error.message });
+        return null;
+      }
+    },
+
+    /**
+     * Helper: Displays database statistics in table format
+     * @private
+     * @param {Object} params - Parameters
+     * @param {string} params.provider - Database provider
+     * @param {string} params.dbName - Database name
+     * @param {Array<Object>} params.stats - Statistics array
+     */
+    _displayStats({ provider, dbName, stats }) {
+      if (!stats || stats.length === 0) {
+        logger.warn('No statistics to display', { provider, dbName });
+        return;
+      }
+
+      const title = provider === 'mongoose' ? 'Collections' : 'Tables';
+      const itemKey = provider === 'mongoose' ? 'collection' : 'table';
+
+      console.log('\n' + '='.repeat(70));
+      console.log(`DATABASE: ${dbName} (${provider.toUpperCase()})`);
+      console.log('='.repeat(70));
+      console.log(`${title.padEnd(50)} ${'Documents/Rows'.padStart(18)}`);
+      console.log('-'.repeat(70));
+
+      let totalCount = 0;
+      stats.forEach((item) => {
+        const name = item[itemKey] || 'Unknown';
+        const count = item.count || 0;
+        totalCount += count;
+        console.log(`${name.padEnd(50)} ${count.toString().padStart(18)}`);
+      });
+
+      console.log('-'.repeat(70));
+      console.log(`${'TOTAL'.padEnd(50)} ${totalCount.toString().padStart(18)}`);
+      console.log('='.repeat(70) + '\n');
+    },
+
+    /**
+     * Public API: Gets MongoDB primary pod name
+     * @public
+     * @param {Object} options - Options for getting primary pod
+     * @param {string} [options.namespace='default'] - Kubernetes namespace
+     * @param {string} [options.podName='mongodb-0'] - Initial pod name to query replica set status
+     * @returns {string|null} Primary pod name or null if not found
+     * @memberof UnderpostDB
+     * @example
+     * const primaryPod = UnderpostDB.API.getMongoPrimaryPodName({ namespace: 'production' });
+     * console.log(primaryPod); // 'mongodb-1'
+     */
+    getMongoPrimaryPodName(options = { namespace: 'default', podName: 'mongodb-0' }) {
+      const { namespace = 'default', podName = 'mongodb-0' } = options;
+
+      try {
+        logger.info('Checking for MongoDB primary pod', { namespace, checkingPod: podName });
+
+        const command = `sudo kubectl exec -n ${namespace} -i ${podName} -- mongosh --quiet --eval 'rs.status().members.filter(m => m.stateStr=="PRIMARY").map(m=>m.name)'`;
+        const output = shellExec(command, { stdout: true, silent: true });
+
+        if (!output || output.trim() === '') {
+          logger.warn('No primary pod found in replica set');
+          return null;
+        }
+
+        // Parse the output to get the primary pod name
+        // Output format: [ 'mongodb-0:27017' ] or [ 'mongodb-1.mongodb-service:27017' ] or similar
+        const match = output.match(/['"]([^'"]+)['"]/);
+        if (match && match[1]) {
+          let primaryName = match[1].split(':')[0]; // Extract pod name without port
+          // Remove service suffix if present (e.g., "mongodb-1.mongodb-service" -> "mongodb-1")
+          primaryName = primaryName.split('.')[0];
+          logger.info('Found MongoDB primary pod', { primaryPod: primaryName });
+          return primaryName;
+        }
+
+        logger.warn('Could not parse primary pod from replica set status', { output });
+        return null;
+      } catch (error) {
+        logger.error('Failed to get MongoDB primary pod', { error: error.message });
+        return null;
+      }
+    },
+
+    /**
+     * Main callback: Initiates database backup workflow
      * @method callback
-     * @description Initiates a database backup workflow based on the provided options.
-     * This method orchestrates the backup process for multiple deployments, handling
+     * @description Orchestrates the backup process for multiple deployments, handling
      * database connections, backup storage, and optional Git integration for version control.
-     * @param {string} [deployList='default'] - List of deployment IDs to include in the backup.
-     * @param {object} [options] - An object containing boolean flags for various operations.
-     * @param {boolean} [options.import=false] - Flag to import data from a backup.
-     * @param {boolean} [options.export=false] - Flag to export data to a backup.
-     * @param {string} [options.podName=false] - The name of the Kubernetes pod to use for database operations.
-     * @param {string} [options.ns=false] - The namespace to use for database operations.
-     * @param {string} [options.collections=''] - Comma-separated list of collections to include in the backup.
-     * @param {string} [options.outPath=''] - Output path for the backup file.
-     * @param {boolean} [options.drop=false] - Flag to drop the database before importing.
-     * @param {boolean} [options.preserveUUID=false] - Flag to preserve UUIDs during import.
-     * @param {boolean} [options.git=false] - Flag to enable Git integration for version control.
-     * @param {string} [options.hosts=''] - Comma-separated list of hosts to include in the backup.
-     * @param {string} [options.paths=''] - Comma-separated list of paths to include in the backup.
+     * Supports targeting multiple specific pods, nodes, and namespaces with advanced filtering.
+     * @param {string} [deployList='default'] - Comma-separated list of deployment IDs
+     * @param {Object} options - Backup options
+     * @param {boolean} [options.import=false] - Whether to perform import operation
+     * @param {boolean} [options.export=false] - Whether to perform export operation
+     * @param {string} [options.podName=''] - Comma-separated pod name patterns to target
+     * @param {string} [options.nodeName=''] - Comma-separated node names to target
+     * @param {string} [options.ns='default'] - Kubernetes namespace
+     * @param {string} [options.collections=''] - Comma-separated MongoDB collections for export
+     * @param {string} [options.outPath=''] - Output path for backups
+     * @param {boolean} [options.drop=false] - Whether to drop existing database on import
+     * @param {boolean} [options.preserveUUID=false] - Whether to preserve UUIDs on MongoDB import
+     * @param {boolean} [options.git=false] - Whether to use Git for backup versioning
+     * @param {string} [options.hosts=''] - Comma-separated list of hosts to filter databases
+     * @param {string} [options.paths=''] - Comma-separated list of paths to filter databases
+     * @param {string} [options.labelSelector=''] - Label selector for pod filtering
+     * @param {boolean} [options.allPods=false] - Whether to target all pods in deployment
+     * @param {boolean} [options.primaryPod=false] - Whether to target MongoDB primary pod only
+     * @param {boolean} [options.stats=false] - Whether to display database statistics
+     * @param {number} [options.macroRollbackExport=1] - Number of commits to rollback in macro export
+     * @returns {Promise<void>} Resolves when operation is complete
      * @memberof UnderpostDB
      */
     async callback(
@@ -50,8 +788,9 @@ class UnderpostDB {
       options = {
         import: false,
         export: false,
-        podName: false,
-        ns: false,
+        podName: '',
+        nodeName: '',
+        ns: 'default',
         collections: '',
         outPath: '',
         drop: false,
@@ -59,17 +798,51 @@ class UnderpostDB {
         git: false,
         hosts: '',
         paths: '',
+        labelSelector: '',
+        allPods: false,
+        primaryPod: false,
+        stats: false,
+        macroRollbackExport: 1,
       },
     ) {
       const newBackupTimestamp = new Date().getTime();
-      const nameSpace = options.ns && typeof options.ns === 'string' ? options.ns : 'default';
+      const namespace = options.ns && typeof options.ns === 'string' ? options.ns : 'default';
+
+      // Validate namespace
+      if (!UnderpostDB.API._validateNamespace(namespace)) {
+        logger.error('Invalid namespace format', { namespace });
+        throw new Error(`Invalid namespace: ${namespace}`);
+      }
+
+      if (deployList === 'dd') deployList = fs.readFileSync(`./engine-private/deploy/dd.router`, 'utf8');
+
+      logger.info('Starting database operation', {
+        deployList,
+        namespace,
+        import: options.import,
+        export: options.export,
+      });
+
       for (const _deployId of deployList.split(',')) {
         const deployId = _deployId.trim();
         if (!deployId) continue;
+
+        logger.info('Processing deployment', { deployId });
+
+        /** @type {Object.<string, Object.<string, DatabaseConfig>>} */
         const dbs = {};
         const repoName = `engine-${deployId.split('dd-')[1]}-cron-backups`;
 
-        const confServer = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.server.json`, 'utf8'));
+        // Load server configuration
+        const confServerPath = `./engine-private/conf/${deployId}/conf.server.json`;
+        if (!fs.existsSync(confServerPath)) {
+          logger.error('Configuration file not found', { path: confServerPath });
+          continue;
+        }
+
+        const confServer = JSON.parse(fs.readFileSync(confServerPath, 'utf8'));
+
+        // Build database configuration map
         for (const host of Object.keys(confServer)) {
           for (const path of Object.keys(confServer[host])) {
             const { db } = confServer[host][path];
@@ -77,193 +850,307 @@ class UnderpostDB {
               const { provider, name, user, password } = db;
               if (!dbs[provider]) dbs[provider] = {};
 
-              if (!(name in dbs[provider]))
-                dbs[provider][name] = { user, password, hostFolder: host + path.replaceAll('/', '-'), host, path };
+              if (!(name in dbs[provider])) {
+                dbs[provider][name] = {
+                  user,
+                  password,
+                  hostFolder: host + path.replaceAll('/', '-'),
+                  host,
+                  path,
+                };
+              }
             }
           }
         }
 
+        // Handle Git operations
         if (options.git === true) {
-          if (!fs.existsSync(`../${repoName}`)) {
-            shellExec(`cd .. && underpost clone ${process.env.GITHUB_USERNAME}/${repoName}`);
+          UnderpostDB.API._manageGitRepo({ repoName, operation: 'clone' });
+          UnderpostDB.API._manageGitRepo({ repoName, operation: 'pull' });
+        }
+
+        if (options.macroRollbackExport) {
+          UnderpostDB.API._manageGitRepo({ repoName, operation: 'clone' });
+          UnderpostDB.API._manageGitRepo({ repoName, operation: 'pull' });
+
+          const nCommits = parseInt(options.macroRollbackExport);
+          const repoPath = `../${repoName}`;
+          const username = process.env.GITHUB_USERNAME;
+
+          if (fs.existsSync(repoPath) && username) {
+            logger.info('Executing macro rollback export', { repoName, nCommits });
+            shellExec(`cd ${repoPath} && underpost cmt . reset ${nCommits}`);
+            shellExec(`cd ${repoPath} && git reset`);
+            shellExec(`cd ${repoPath} && git checkout .`);
+            shellExec(`cd ${repoPath} && git clean -f -d`);
+            shellExec(`cd ${repoPath} && underpost push . ${username}/${repoName} -f`);
           } else {
-            shellExec(`cd ../${repoName} && git checkout . && git clean -f -d`);
-            shellExec(`cd ../${repoName} && underpost pull . ${process.env.GITHUB_USERNAME}/${repoName}`);
+            if (!username) logger.error('GITHUB_USERNAME environment variable not set');
+            logger.warn('Repository not found for macro rollback', { repoPath });
           }
         }
 
+        // Process each database provider
         for (const provider of Object.keys(dbs)) {
           for (const dbName of Object.keys(dbs[provider])) {
             const { hostFolder, user, password, host, path } = dbs[provider][dbName];
+
+            // Filter by hosts and paths if specified
             if (
-              (options.hosts && !options.hosts.split(',').includes(host)) ||
-              (options.paths && !options.paths.split(',').includes(path))
-            )
+              (options.hosts &&
+                !options.hosts
+                  .split(',')
+                  .map((h) => h.trim())
+                  .includes(host)) ||
+              (options.paths &&
+                !options.paths
+                  .split(',')
+                  .map((p) => p.trim())
+                  .includes(path))
+            ) {
+              logger.info('Skipping database due to host/path filter', { dbName, host, path });
               continue;
-            if (hostFolder) {
-              logger.info('', { hostFolder, provider, dbName });
-
-              const backUpPath = `../${repoName}/${hostFolder}`;
-              if (!fs.existsSync(backUpPath)) fs.mkdirSync(backUpPath, { recursive: true });
-              shellExec(`cd ${backUpPath} && find . -type d -empty -delete`); // delete empty folders
-              const times = await fs.readdir(backUpPath);
-              const currentBackupTimestamp = Math.max(...times.map((t) => parseInt(t)).filter((t) => !isNaN(t)));
-              dbs[provider][dbName].currentBackupTimestamp = currentBackupTimestamp;
-              const removeBackupTimestamp = Math.min(...times.map((t) => parseInt(t)).filter((t) => !isNaN(t)));
-
-              const sqlContainerPath = `/home/${dbName}.sql`;
-              const _fromPartsParts = `../${repoName}/${hostFolder}/${currentBackupTimestamp}/${dbName}-parths.json`;
-              const _toSqlPath = `../${repoName}/${hostFolder}/${currentBackupTimestamp}/${dbName}.sql`;
-              const _toNewSqlPath = `../${repoName}/${hostFolder}/${newBackupTimestamp}/${dbName}.sql`;
-              const _toBsonPath = `../${repoName}/${hostFolder}/${currentBackupTimestamp}/${dbName}`;
-              const _toNewBsonPath = `../${repoName}/${hostFolder}/${newBackupTimestamp}/${dbName}`;
-
-              if (options.import === true && fs.existsSync(_fromPartsParts) && !fs.existsSync(_toSqlPath)) {
-                const names = JSON.parse(fs.readFileSync(_fromPartsParts, 'utf8')).map((_path) => {
-                  return `../${repoName}/${hostFolder}/${currentBackupTimestamp}/${_path.split('/').pop()}`;
-                });
-                logger.info('merge Back Up paths', {
-                  _fromPartsParts,
-                  _toSqlPath,
-                  names,
-                });
-                await mergeFile(names, _toSqlPath);
-              }
+            }
+
+            if (!hostFolder) {
+              logger.warn('No hostFolder defined for database', { dbName, provider });
+              continue;
+            }
+
+            logger.info('Processing database', { hostFolder, provider, dbName });
+
+            const backUpPath = `../${repoName}/${hostFolder}`;
+            const backupInfo = UnderpostDB.API._manageBackupTimestamps(
+              backUpPath,
+              newBackupTimestamp,
+              options.export === true,
+            );
+
+            dbs[provider][dbName].currentBackupTimestamp = backupInfo.current;
+
+            const currentTimestamp = backupInfo.current || newBackupTimestamp;
+            const sqlContainerPath = `/home/${dbName}.sql`;
+            const fromPartsPath = `../${repoName}/${hostFolder}/${currentTimestamp}/${dbName}-parths.json`;
+            const toSqlPath = `../${repoName}/${hostFolder}/${currentTimestamp}/${dbName}.sql`;
+            const toNewSqlPath = `../${repoName}/${hostFolder}/${newBackupTimestamp}/${dbName}.sql`;
+            const toBsonPath = `../${repoName}/${hostFolder}/${currentTimestamp}/${dbName}`;
+            const toNewBsonPath = `../${repoName}/${hostFolder}/${newBackupTimestamp}/${dbName}`;
+
+            // Merge split SQL files if needed for import
+            if (options.import === true && fs.existsSync(fromPartsPath) && !fs.existsSync(toSqlPath)) {
+              const names = JSON.parse(fs.readFileSync(fromPartsPath, 'utf8')).map((_path) => {
+                return `../${repoName}/${hostFolder}/${currentTimestamp}/${_path.split('/').pop()}`;
+              });
+              logger.info('Merging backup parts', { fromPartsPath, toSqlPath, parts: names.length });
+              await mergeFile(names, toSqlPath);
+            }
+
+            // Get target pods based on provider and options
+            let targetPods = [];
+            const podCriteria = {
+              podNames: options.podName,
+              nodeNames: options.nodeName,
+              namespace,
+              labelSelector: options.labelSelector,
+              deployId: provider === 'mariadb' ? 'mariadb' : 'mongo',
+            };
+
+            targetPods = UnderpostDB.API._getFilteredPods(podCriteria);
+
+            // Fallback to default if no custom pods specified
+            if (targetPods.length === 0 && !options.podName && !options.nodeName) {
+              const defaultPods = UnderpostDeploy.API.get(
+                provider === 'mariadb' ? 'mariadb' : 'mongo',
+                'pods',
+                namespace,
+              );
+              console.log('defaultPods', defaultPods);
+              targetPods = defaultPods;
+            }
+
+            if (targetPods.length === 0) {
+              logger.warn('No pods found matching criteria', { provider, criteria: podCriteria });
+              continue;
+            }
+
+            // Handle primary pod detection for MongoDB
+            let podsToProcess = [];
+            if (provider === 'mongoose' && !options.allPods) {
+              // For MongoDB, always use primary pod unless allPods is true
+              if (!targetPods || targetPods.length === 0) {
+                logger.warn('No MongoDB pods available to check for primary');
+                podsToProcess = [];
+              } else {
+                const firstPod = targetPods[0].NAME;
+                const primaryPodName = UnderpostDB.API.getMongoPrimaryPodName({ namespace, podName: firstPod });
 
-              if (options.export === true && times.length >= 5) {
-                logger.info('remove', `../${repoName}/${hostFolder}/${removeBackupTimestamp}`);
-                fs.removeSync(`../${repoName}/${hostFolder}/${removeBackupTimestamp}`);
-                logger.info('create', `../${repoName}/${hostFolder}/${newBackupTimestamp}`);
-                fs.mkdirSync(`../${repoName}/${hostFolder}/${newBackupTimestamp}`, { recursive: true });
+                if (primaryPodName) {
+                  const primaryPod = targetPods.find((p) => p.NAME === primaryPodName);
+                  if (primaryPod) {
+                    podsToProcess = [primaryPod];
+                    logger.info('Using MongoDB primary pod', { primaryPod: primaryPodName });
+                  } else {
+                    logger.warn('Primary pod not in filtered list, using first pod', { primaryPodName });
+                    podsToProcess = [targetPods[0]];
+                  }
+                } else {
+                  logger.warn('Could not detect primary pod, using first pod');
+                  podsToProcess = [targetPods[0]];
+                }
               }
+            } else {
+              // For MariaDB or when allPods is true, limit to first pod unless allPods is true
+              podsToProcess = options.allPods === true ? targetPods : [targetPods[0]];
+            }
+
+            logger.info(`Processing ${podsToProcess.length} pod(s) for ${provider}`, {
+              dbName,
+              pods: podsToProcess.map((p) => p.NAME),
+            });
+
+            // Process each pod
+            for (const pod of podsToProcess) {
+              logger.info('Processing pod', { podName: pod.NAME, node: pod.NODE, status: pod.STATUS });
 
               switch (provider) {
                 case 'mariadb': {
-                  const podNames =
-                    options.podName && typeof options.podName === 'string'
-                      ? options.podName.split(',')
-                      : UnderpostDeploy.API.get('mariadb'); // `mariadb-statefulset-0`;
-                  const serviceName = 'mariadb';
-                  for (const podNameData of [podNames[0]]) {
-                    const podName = podNameData.NAME;
-                    if (options.import === true) {
-                      shellExec(`sudo kubectl exec -n ${nameSpace} -i ${podName} -- sh -c "rm -rf /${dbName}.sql"`);
-                      shellExec(`sudo kubectl cp ${_toSqlPath} ${nameSpace}/${podName}:/${dbName}.sql`);
-                      const cmd = `mariadb -u ${user} -p${password} ${dbName} < /${dbName}.sql`;
-                      shellExec(
-                        `kubectl exec -n ${nameSpace} -i ${podName} -- ${serviceName} -p${password} -e 'CREATE DATABASE ${dbName};'`,
-                      );
-                      shellExec(`sudo kubectl exec -n ${nameSpace} -i ${podName} -- sh -c "${cmd}"`);
-                    }
-                    if (options.export === true) {
-                      shellExec(
-                        `sudo kubectl exec -n ${nameSpace} -i ${podName} -- sh -c "rm -rf ${sqlContainerPath}"`,
-                      );
-                      const cmd = `mariadb-dump --user=${user} --password=${password} --lock-tables ${dbName} > ${sqlContainerPath}`;
-                      shellExec(`sudo kubectl exec -n ${nameSpace} -i ${podName} -- sh -c "${cmd}"`);
-                      shellExec(
-                        `sudo kubectl cp ${nameSpace}/${podName}:${sqlContainerPath} ${
-                          options.outPath ? options.outPath : _toNewSqlPath
-                        }`,
-                      );
-                      await splitFileFactory(dbName, options.outPath ? options.outPath : _toNewSqlPath);
+                  if (options.stats === true) {
+                    const stats = UnderpostDB.API._getMariaDBStats({
+                      podName: pod.NAME,
+                      namespace,
+                      dbName,
+                      user,
+                      password,
+                    });
+                    if (stats) {
+                      UnderpostDB.API._displayStats({ provider, dbName, stats });
                     }
                   }
+
+                  if (options.import === true) {
+                    UnderpostDB.API._importMariaDB({
+                      pod,
+                      namespace,
+                      dbName,
+                      user,
+                      password,
+                      sqlPath: toSqlPath,
+                    });
+                  }
+
+                  if (options.export === true) {
+                    const outputPath = options.outPath || toNewSqlPath;
+                    await UnderpostDB.API._exportMariaDB({
+                      pod,
+                      namespace,
+                      dbName,
+                      user,
+                      password,
+                      outputPath,
+                    });
+                  }
                   break;
                 }
 
                 case 'mongoose': {
-                  if (options.import === true) {
-                    const podNames =
-                      options.podName && typeof options.podName === 'string'
-                        ? options.podName.split(',')
-                        : UnderpostDeploy.API.get('mongo');
-                    // `mongodb-0`;
-                    for (const podNameData of [podNames[0]]) {
-                      const podName = podNameData.NAME;
-                      shellExec(`sudo kubectl exec -n ${nameSpace} -i ${podName} -- sh -c "rm -rf /${dbName}"`);
-                      shellExec(
-                        `sudo kubectl cp ${
-                          options.outPath ? options.outPath : _toBsonPath
-                        } ${nameSpace}/${podName}:/${dbName}`,
-                      );
-                      const cmd = `mongorestore -d ${dbName} /${dbName}${options.drop ? ' --drop' : ''}${
-                        options.preserveUUID ? ' --preserveUUID' : ''
-                      }`;
-                      shellExec(`sudo kubectl exec -n ${nameSpace} -i ${podName} -- sh -c "${cmd}"`);
+                  if (options.stats === true) {
+                    const stats = UnderpostDB.API._getMongoStats({
+                      podName: pod.NAME,
+                      namespace,
+                      dbName,
+                    });
+                    if (stats) {
+                      UnderpostDB.API._displayStats({ provider, dbName, stats });
                     }
                   }
+
+                  if (options.import === true) {
+                    const bsonPath = options.outPath || toBsonPath;
+                    UnderpostDB.API._importMongoDB({
+                      pod,
+                      namespace,
+                      dbName,
+                      bsonPath,
+                      drop: options.drop,
+                      preserveUUID: options.preserveUUID,
+                    });
+                  }
+
                   if (options.export === true) {
-                    const podNames =
-                      options.podName && typeof options.podName === 'string'
-                        ? options.podName.split(',')
-                        : UnderpostDeploy.API.get('mongo'); // `backup-access`;
-                    for (const podNameData of [podNames[0]]) {
-                      const podName = podNameData.NAME;
-                      shellExec(`sudo kubectl exec -n ${nameSpace} -i ${podName} -- sh -c "rm -rf /${dbName}"`);
-                      if (options.collections)
-                        for (const collection of options.collections.split(','))
-                          shellExec(
-                            `sudo kubectl exec -n ${nameSpace} -i ${podName} -- sh -c "mongodump -d ${dbName} --collection ${collection} -o /"`,
-                          );
-                      else
-                        shellExec(
-                          `sudo kubectl exec -n ${nameSpace} -i ${podName} -- sh -c "mongodump -d ${dbName} -o /"`,
-                        );
-                      shellExec(
-                        `sudo kubectl cp ${nameSpace}/${podName}:/${dbName} ${
-                          options.outPath ? options.outPath : _toNewBsonPath
-                        }`,
-                      );
-                    }
+                    const outputPath = options.outPath || toNewBsonPath;
+                    UnderpostDB.API._exportMongoDB({
+                      pod,
+                      namespace,
+                      dbName,
+                      outputPath,
+                      collections: options.collections,
+                    });
                   }
                   break;
                 }
 
                 default:
+                  logger.warn('Unsupported database provider', { provider });
                   break;
               }
             }
           }
         }
+
+        // Commit and push to Git if enabled
         if (options.export === true && options.git === true) {
-          shellExec(`cd ../${repoName} && git add .`);
-          shellExec(
-            `underpost cmt ../${repoName} backup '' '${new Date(newBackupTimestamp).toLocaleDateString()} ${new Date(
-              newBackupTimestamp,
-            ).toLocaleTimeString()}'`,
-          );
-          shellExec(`cd ../${repoName} && underpost push . ${process.env.GITHUB_USERNAME}/${repoName}`, {
-            disableLog: true,
-          });
+          const commitMessage = `${new Date(newBackupTimestamp).toLocaleDateString()} ${new Date(
+            newBackupTimestamp,
+          ).toLocaleTimeString()}`;
+          UnderpostDB.API._manageGitRepo({ repoName, operation: 'commit', message: commitMessage });
+          UnderpostDB.API._manageGitRepo({ repoName, operation: 'push' });
         }
       }
+
+      logger.info('Database operation completed successfully');
     },
 
     /**
+     * Creates cluster metadata for the specified deployment
      * @method clusterMetadataFactory
-     * @description Creates a cluster metadata object for the specified deployment.
-     * This method loads database configuration and initializes a cluster metadata object
-     * using the provided deployment ID, host, and path.
-     * @param {string} [deployId=process.env.DEFAULT_DEPLOY_ID] - The deployment ID to use.
-     * @param {string} [host=process.env.DEFAULT_DEPLOY_HOST] - The host to use.
-     * @param {string} [path=process.env.DEFAULT_DEPLOY_PATH] - The path to use.
+     * @description Loads database configuration and initializes cluster metadata including
+     * instances and cron jobs. This method populates the database with deployment information.
+     * @param {string} [deployId=process.env.DEFAULT_DEPLOY_ID] - The deployment ID
+     * @param {string} [host=process.env.DEFAULT_DEPLOY_HOST] - The host identifier
+     * @param {string} [path=process.env.DEFAULT_DEPLOY_PATH] - The path identifier
+     * @returns {Promise<void>}
      * @memberof UnderpostDB
+     * @throws {Error} If database configuration is invalid or connection fails
      */
     async clusterMetadataFactory(
       deployId = process.env.DEFAULT_DEPLOY_ID,
       host = process.env.DEFAULT_DEPLOY_HOST,
       path = process.env.DEFAULT_DEPLOY_PATH,
     ) {
-      deployId = deployId ?? process.env.DEFAULT_DEPLOY_ID;
-      host = host ?? process.env.DEFAULT_DEPLOY_HOST;
-      path = path ?? process.env.DEFAULT_DEPLOY_PATH;
+      deployId = deployId ? deployId : process.env.DEFAULT_DEPLOY_ID;
+      host = host ? host : process.env.DEFAULT_DEPLOY_HOST;
+      path = path ? path : process.env.DEFAULT_DEPLOY_PATH;
+
+      logger.info('Creating cluster metadata', { deployId, host, path });
+
       const env = 'production';
-      const deployList = fs.readFileSync('./engine-private/deploy/dd.router', 'utf8').split(',');
+      const deployListPath = './engine-private/deploy/dd.router';
+
+      if (!fs.existsSync(deployListPath)) {
+        logger.error('Deploy router file not found', { path: deployListPath });
+        throw new Error(`Deploy router file not found: ${deployListPath}`);
+      }
+
+      const deployList = fs.readFileSync(deployListPath, 'utf8').split(',');
+
+      const confServerPath = `./engine-private/conf/${deployId}/conf.server.json`;
+      if (!fs.existsSync(confServerPath)) {
+        logger.error('Server configuration not found', { path: confServerPath });
+        throw new Error(`Server configuration not found: ${confServerPath}`);
+      }
+
+      const { db } = JSON.parse(fs.readFileSync(confServerPath, 'utf8'))[host][path];
 
-      const { db } = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.server.json`, 'utf8'))[host][
-        path
-      ];
       try {
         await DataBaseProvider.load({ apis: ['instance', 'cron'], host, path, db });
 
@@ -271,14 +1158,21 @@ class UnderpostDB {
         const Instance = DataBaseProvider.instance[`${host}${path}`].mongoose.models.Instance;
 
         await Instance.deleteMany();
+        logger.info('Cleared existing instance metadata');
 
         for (const _deployId of deployList) {
           const deployId = _deployId.trim();
           if (!deployId) continue;
-          const confServer = loadReplicas(
-            deployId,
-            JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.server.json`, 'utf8')),
-          );
+
+          logger.info('Processing deployment for metadata', { deployId });
+
+          const confServerPath = `./engine-private/conf/${deployId}/conf.server.json`;
+          if (!fs.existsSync(confServerPath)) {
+            logger.warn('Configuration not found for deployment', { deployId, path: confServerPath });
+            continue;
+          }
+
+          const confServer = loadReplicas(deployId, JSON.parse(fs.readFileSync(confServerPath, 'utf8')));
           const router = await UnderpostDeploy.API.routerFactory(deployId, env);
           const pathPortAssignmentData = await pathPortAssignmentFactory(deployId, router, confServer);
 
@@ -287,6 +1181,8 @@ class UnderpostDB {
               if (!confServer[host][path]) continue;
 
               const { client, runtime, apis, peer } = confServer[host][path];
+
+              // Save main instance
               {
                 const body = {
                   deployId,
@@ -298,10 +1194,11 @@ class UnderpostDB {
                   apis,
                 };
 
-                logger.info('Instance save', body);
+                logger.info('Saving instance metadata', body);
                 await new Instance(body).save();
               }
 
+              // Save peer instance if exists
               if (peer) {
                 const body = {
                   deployId,
@@ -311,15 +1208,16 @@ class UnderpostDB {
                   runtime: 'nodejs',
                 };
 
-                logger.info('Instance save', body);
+                logger.info('Saving peer instance metadata', body);
                 await new Instance(body).save();
               }
             }
           }
-          if (fs.existsSync(`./engine-private/conf/${deployId}/conf.instances.json`)) {
-            const confInstances = JSON.parse(
-              fs.readFileSync(`./engine-private/conf/${deployId}/conf.instances.json`, 'utf8'),
-            );
+
+          // Process additional instances
+          const confInstancesPath = `./engine-private/conf/${deployId}/conf.instances.json`;
+          if (fs.existsSync(confInstancesPath)) {
+            const confInstances = JSON.parse(fs.readFileSync(confInstancesPath, 'utf8'));
             for (const instance of confInstances) {
               const { id, host, path, fromPort, metadata } = instance;
               const { runtime } = metadata;
@@ -331,18 +1229,31 @@ class UnderpostDB {
                 client: id,
                 runtime,
               };
-              logger.info('Instance save', body);
+              logger.info('Saving additional instance metadata', body);
               await new Instance(body).save();
             }
           }
         }
       } catch (error) {
-        logger.error(error, error.stack);
+        logger.error('Failed to create instance metadata', { error: error.message, stack: error.stack });
+        throw error;
       }
 
       try {
-        const cronDeployId = fs.readFileSync('./engine-private/deploy/dd.cron', 'utf8').trim();
+        const cronDeployPath = './engine-private/deploy/dd.cron';
+        if (!fs.existsSync(cronDeployPath)) {
+          logger.warn('Cron deploy file not found', { path: cronDeployPath });
+          return;
+        }
+
+        const cronDeployId = fs.readFileSync(cronDeployPath, 'utf8').trim();
         const confCronPath = `./engine-private/conf/${cronDeployId}/conf.cron.json`;
+
+        if (!fs.existsSync(confCronPath)) {
+          logger.warn('Cron configuration not found', { path: confCronPath });
+          return;
+        }
+
         const confCron = JSON.parse(fs.readFileSync(confCronPath, 'utf8'));
 
         await DataBaseProvider.load({ apis: ['cron'], host, path, db });
@@ -351,6 +1262,7 @@ class UnderpostDB {
         const Cron = DataBaseProvider.instance[`${host}${path}`].mongoose.models.Cron;
 
         await Cron.deleteMany();
+        logger.info('Cleared existing cron metadata');
 
         for (const jobId of Object.keys(confCron.jobs)) {
           const body = {
@@ -359,33 +1271,36 @@ class UnderpostDB {
             expression: confCron.jobs[jobId].expression,
             enabled: confCron.jobs[jobId].enabled,
           };
-          logger.info('Cron save', body);
+          logger.info('Saving cron metadata', body);
           await new Cron(body).save();
         }
       } catch (error) {
-        logger.error(error, error.stack);
+        logger.error('Failed to create cron metadata', { error: error.message, stack: error.stack });
       }
+
       await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+      logger.info('Cluster metadata creation completed');
     },
 
     /**
+     * Handles backup of cluster metadata
      * @method clusterMetadataBackupCallback
-     * @description Handles the backup of cluster metadata for the specified deployment.
-     * This method orchestrates the backup process for cluster metadata, including
-     * instances and crons, and handles optional Git integration for version control.
-     * @param {string} [deployId=process.env.DEFAULT_DEPLOY_ID] - The deployment ID to use.
-     * @param {string} [host=process.env.DEFAULT_DEPLOY_HOST] - The host to use.
-     * @param {string} [path=process.env.DEFAULT_DEPLOY_PATH] - The path to use.
-     * @param {object} [options] - An object containing boolean flags for various operations.
-     * @param {boolean} [options.generate=false] - Flag to generate cluster metadata.
-     * @param {boolean} [options.itc=false] - Flag to enable Git integration for version control.
-     * @param {boolean} [options.import=false] - Flag to import data from a backup.
-     * @param {boolean} [options.export=false] - Flag to export data to a backup.
-     * @param {boolean} [options.instances=false] - Flag to backup instances.
-     * @param {boolean} [options.crons=false] - Flag to backup crons.
+     * @description Orchestrates backup and restore operations for cluster metadata including
+     * instances and cron jobs. Supports import/export and metadata generation.
+     * @param {string} [deployId=process.env.DEFAULT_DEPLOY_ID] - The deployment ID
+     * @param {string} [host=process.env.DEFAULT_DEPLOY_HOST] - The host identifier
+     * @param {string} [path=process.env.DEFAULT_DEPLOY_PATH] - The path identifier
+     * @param {Object} [options] - Backup operation options
+     * @param {boolean} [options.generate=false] - Generate cluster metadata
+     * @param {boolean} [options.itc=false] - Execute in container context
+     * @param {boolean} [options.import=false] - Import metadata from backup
+     * @param {boolean} [options.export=false] - Export metadata to backup
+     * @param {boolean} [options.instances=false] - Process instances collection
+     * @param {boolean} [options.crons=false] - Process crons collection
+     * @returns {void}
      * @memberof UnderpostDB
      */
-    clusterMetadataBackupCallback(
+    async clusterMetadataBackupCallback(
       deployId = process.env.DEFAULT_DEPLOY_ID,
       host = process.env.DEFAULT_DEPLOY_HOST,
       path = process.env.DEFAULT_DEPLOY_PATH,
@@ -398,40 +1313,67 @@ class UnderpostDB {
         crons: false,
       },
     ) {
-      deployId = deployId ?? process.env.DEFAULT_DEPLOY_ID;
-      host = host ?? process.env.DEFAULT_DEPLOY_HOST;
-      path = path ?? process.env.DEFAULT_DEPLOY_PATH;
+      deployId = deployId ? deployId : process.env.DEFAULT_DEPLOY_ID;
+      host = host ? host : process.env.DEFAULT_DEPLOY_HOST;
+      path = path ? path : process.env.DEFAULT_DEPLOY_PATH;
+
+      logger.info('Starting cluster metadata backup operation', {
+        deployId,
+        host,
+        path,
+        options,
+      });
 
       if (options.generate === true) {
-        UnderpostDB.API.clusterMetadataFactory(deployId, host, path);
+        logger.info('Generating cluster metadata');
+        await UnderpostDB.API.clusterMetadataFactory(deployId, host, path);
       }
 
       if (options.instances === true) {
         const outputPath = './engine-private/instances';
-        if (fs.existsSync(outputPath)) fs.mkdirSync(outputPath, { recursive: true });
+        if (!fs.existsSync(outputPath)) {
+          fs.mkdirSync(outputPath, { recursive: true });
+        }
         const collection = 'instances';
-        if (options.export === true)
+
+        if (options.export === true) {
+          logger.info('Exporting instances collection', { outputPath });
           shellExec(
-            `node bin db --export --collections ${collection} --out-path ${outputPath} --hosts ${host} --paths '${path}' ${deployId}`,
+            `node bin db --export --primary-pod --collections ${collection} --out-path ${outputPath} --hosts ${host} --paths '${path}' ${deployId}`,
           );
-        if (options.import === true)
+        }
+
+        if (options.import === true) {
+          logger.info('Importing instances collection', { outputPath });
           shellExec(
-            `node bin db --import --drop --preserveUUID --out-path ${outputPath} --hosts ${host} --paths '${path}' ${deployId}`,
+            `node bin db --import --primary-pod --drop --preserveUUID --out-path ${outputPath} --hosts ${host} --paths '${path}' ${deployId}`,
           );
+        }
       }
+
       if (options.crons === true) {
         const outputPath = './engine-private/crons';
-        if (fs.existsSync(outputPath)) fs.mkdirSync(outputPath, { recursive: true });
+        if (!fs.existsSync(outputPath)) {
+          fs.mkdirSync(outputPath, { recursive: true });
+        }
         const collection = 'crons';
-        if (options.export === true)
+
+        if (options.export === true) {
+          logger.info('Exporting crons collection', { outputPath });
           shellExec(
-            `node bin db --export --collections ${collection} --out-path ${outputPath} --hosts ${host} --paths '${path}' ${deployId}`,
+            `node bin db --export --primary-pod --collections ${collection} --out-path ${outputPath} --hosts ${host} --paths '${path}' ${deployId}`,
           );
-        if (options.import === true)
+        }
+
+        if (options.import === true) {
+          logger.info('Importing crons collection', { outputPath });
           shellExec(
-            `node bin db --import --drop --preserveUUID --out-path ${outputPath} --hosts ${host} --paths '${path}' ${deployId}`,
+            `node bin db --import --primary-pod --drop --preserveUUID --out-path ${outputPath} --hosts ${host} --paths '${path}' ${deployId}`,
           );
+        }
       }
+
+      logger.info('Cluster metadata backup operation completed');
     },
   };
 }