@seip/blue-bird 0.9.0 → 0.9.2

package/core/cli/docker.js

@@ -278,7 +278,12 @@ async function logsCommand(service, followOpt) {
  * @param {boolean} rootOpt - Flag for overriding database credentials to connect as root/postgres.
  * @param {string} explicitService - Explicit target service if specified ('mysql' or 'postgres').
  */
-async function dbClientCommand(userOpt, passOpt, dbOpt, rootOpt, explicitService) {
+/**
+ * Handles interactive shell connections or smart queries into the MySQL or PostgreSQL container.
+ * @param {string[]} clientArgs - CLI arguments.
+ * @param {string} explicitService - Explicit target service if specified ('mysql', 'postgres', 'psql', 'db').
+ */
+async function dbClientCommand(clientArgs = [], explicitService) {
   checkComposeFile();
   const env = getEnvVars();
   const dbType = explicitService === "postgres" || explicitService === "psql" ? "postgres" : (explicitService === "mysql" ? "mysql" : getDbType(env));
@@ -287,25 +292,111 @@ async function dbClientCommand(userOpt, passOpt, dbOpt, rootOpt, explicitService
     return;
   }
 
+  let userOpt, passOpt, dbOpt, rootOpt = false;
+  let limitOpt = null, whereOpt = null;
+  const positionalArgs = [];
+
+  for (let i = 0; i < clientArgs.length; i++) {
+    const arg = clientArgs[i];
+    if (arg === "-u" || arg === "--user") {
+      userOpt = clientArgs[++i];
+    } else if (arg.startsWith("--user=")) {
+      userOpt = arg.split("=")[1];
+    } else if (arg === "-p" || arg === "--password") {
+      passOpt = clientArgs[++i];
+    } else if (arg.startsWith("--password=")) {
+      passOpt = arg.split("=")[1];
+    } else if (arg === "-d" || arg === "--db") {
+      dbOpt = clientArgs[++i];
+    } else if (arg.startsWith("--db=")) {
+      dbOpt = arg.split("=")[1];
+    } else if (arg === "--root") {
+      rootOpt = true;
+    } else if (arg === "--limit" || arg === "-l") {
+      limitOpt = clientArgs[++i];
+    } else if (arg.startsWith("--limit=")) {
+      limitOpt = arg.split("=")[1];
+    } else if (arg === "--where" || arg === "-w") {
+      whereOpt = clientArgs[++i];
+    } else if (arg.startsWith("--where=")) {
+      whereOpt = arg.split("=")[1];
+    } else if (!arg.startsWith("-")) {
+      positionalArgs.push(arg);
+    }
+  }
+
   let dbUser = userOpt;
   let dbPass = passOpt;
   let dbName = dbOpt;
 
-  if (dbType === "postgres") {
-    if (rootOpt) {
-      dbUser = "postgres";
+  let sqlQuery = null;
+  if (positionalArgs.length > 0) {
+    const firstPos = positionalArgs[0].toLowerCase();
+
+    if (firstPos === "export" || firstPos === "dump") {
+      await exportDbCommand(dbType, positionalArgs[1], userOpt, passOpt, dbOpt);
+      return;
+    }
+    if (firstPos === "import" || firstPos === "restore") {
+      await importDbCommand(dbType, positionalArgs[1], userOpt, passOpt, dbOpt);
+      return;
+    }
+    if (firstPos === "tables") {
+      if (dbType === "postgres") {
+        sqlQuery = "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public';";
+      } else {
+        sqlQuery = "SHOW TABLES;";
+      }
+    } else if (firstPos === "columns" || firstPos === "cols" || firstPos === "describe" || firstPos === "desc") {
+      const tableName = positionalArgs[1];
+      if (!tableName) {
+        console.error(chalk.red("Error: Please specify a table name. Example: npx blue-bird docker mysql columns users"));
+        process.exit(1);
+      }
+      if (dbType === "postgres") {
+        sqlQuery = `SELECT column_name, data_type, is_nullable, column_default FROM information_schema.columns WHERE table_name = '${tableName}';`;
+      } else {
+        sqlQuery = `SHOW COLUMNS FROM ${tableName};`;
+      }
     } else {
-      dbUser = dbUser || env.DB_USER || "postgres";
+      const rawInput = positionalArgs.join(" ").trim();
+      const isFullQuery = /^(select|show|desc|describe|explain|insert|update|delete|create|drop|alter|truncate)\b/i.test(rawInput) || rawInput.includes(" ");
+      if (isFullQuery) {
+        sqlQuery = rawInput;
+      } else {
+        const tableName = rawInput;
+        sqlQuery = `SELECT * FROM ${tableName}`;
+        if (whereOpt) {
+          sqlQuery += ` WHERE ${whereOpt}`;
+        }
+        if (limitOpt) {
+          sqlQuery += ` LIMIT ${limitOpt}`;
+        }
+      }
+      if (!sqlQuery.endsWith(";")) {
+        sqlQuery += ";";
+      }
     }
-    dbName = dbName || env.DB_NAME || "blue_bird";
+  }
 
-    const targetDb = dbName ? ` (database: ${dbName})` : "";
-    console.log(chalk.cyan(`Connecting to PostgreSQL shell (psql) in container as '${dbUser}'${targetDb}...`));
+  if (dbType === "postgres") {
+    dbUser = rootOpt ? "postgres" : (dbUser || env.DB_USER || "postgres");
+    dbName = dbName || env.DB_NAME || "blue_bird";
 
     const cmdArgs = ["compose", "exec", "postgres", "psql", `-U${dbUser}`];
     if (dbName) {
       cmdArgs.push("-d", dbName);
     }
+
+    if (sqlQuery) {
+      console.log(chalk.cyan(`🔍 Executing PostgreSQL query on database '${dbName}':`));
+      console.log(chalk.gray(`   ${sqlQuery}\n`));
+      cmdArgs.push("-c", sqlQuery);
+    } else {
+      const targetDb = dbName ? ` (database: ${dbName})` : "";
+      console.log(chalk.cyan(`Connecting to PostgreSQL shell (psql) in container as '${dbUser}'${targetDb}...`));
+    }
+
     const code = await runCmd("docker", cmdArgs);
     if (code !== 0) {
       console.error(chalk.yellow("Make sure the PostgreSQL container is running: npx blue-bird docker start postgres"));
@@ -329,8 +420,14 @@ async function dbClientCommand(userOpt, passOpt, dbOpt, rootOpt, explicitService
       cmdArgs.push(dbName);
     }
 
-    const targetDb = dbName ? ` (database: ${dbName})` : "";
-    console.log(chalk.cyan(`Connecting to MySQL shell in container as '${dbUser}'${targetDb}...`));
+    if (sqlQuery) {
+      console.log(chalk.cyan(`🔍 Executing MySQL query on database '${dbName}':`));
+      console.log(chalk.gray(`   ${sqlQuery}\n`));
+      cmdArgs.push("-t", "-e", sqlQuery);
+    } else {
+      const targetDb = dbName ? ` (database: ${dbName})` : "";
+      console.log(chalk.cyan(`Connecting to MySQL shell in container as '${dbUser}'${targetDb}...`));
+    }
 
     const code = await runCmd("docker", cmdArgs);
     if (code !== 0) {
@@ -340,6 +437,196 @@ async function dbClientCommand(userOpt, passOpt, dbOpt, rootOpt, explicitService
   }
 }
 
+/**
+ * Exports database schema & data into a .sql file inside backups/ folder.
+ * @param {string} dbType - Target db type ('mysql', 'postgres', 'none').
+ * @param {string} [filenameArg] - Custom backup filename.
+ * @param {string} [userOpt] - Custom db user.
+ * @param {string} [passOpt] - Custom db password.
+ * @param {string} [dbOpt] - Custom db name.
+ */
+async function exportDbCommand(dbType, filenameArg, userOpt, passOpt, dbOpt) {
+  checkComposeFile();
+  const env = getEnvVars();
+  const targetDbType = dbType === "none" ? getDbType(env) : dbType;
+
+  if (targetDbType === "none") {
+    console.error(chalk.yellow("[INFO] DB_TYPE is set to 'none'. No database available to export."));
+    return;
+  }
+
+  const backupsDir = path.join(process.cwd(), "backups");
+  if (!fs.existsSync(backupsDir)) {
+    fs.mkdirSync(backupsDir, { recursive: true });
+  }
+
+  let outputFile;
+  if (filenameArg) {
+    let name = filenameArg;
+    if (!name.endsWith(".sql")) name += ".sql";
+    if (path.isAbsolute(name)) {
+      outputFile = name;
+    } else if (name.includes("/") || name.includes("\\")) {
+      outputFile = path.resolve(process.cwd(), name);
+    } else {
+      outputFile = path.join(backupsDir, name);
+    }
+  } else {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-").replace("T", "_").slice(0, 19);
+    outputFile = path.join(backupsDir, `backup_${targetDbType}_${timestamp}.sql`);
+  }
+
+  const dbUser = userOpt || env.DB_USER || (targetDbType === "postgres" ? "postgres" : "root");
+  const dbPass = passOpt || env.DB_PASSWORD || (targetDbType === "postgres" ? "postgres" : "root");
+  const dbName = dbOpt || env.DB_NAME || "blue_bird";
+
+  let cmdArgs = [];
+  if (targetDbType === "postgres") {
+    cmdArgs = ["compose", "exec", "-T", "postgres", "pg_dump", `-U${dbUser}`, "-d", dbName];
+  } else {
+    cmdArgs = ["compose", "exec", "-T", "mysql", "mysqldump", `-u${dbUser}`, `-p${dbPass}`, dbName];
+  }
+
+  const relPath = path.relative(process.cwd(), outputFile);
+  console.log(chalk.cyan(`📦 Exporting ${targetDbType.toUpperCase()} database '${dbName}' to '${relPath}'...`));
+
+  const success = await exportDbToFile(cmdArgs, outputFile);
+  if (success) {
+    const stats = fs.statSync(outputFile);
+    const sizeKb = (stats.size / 1024).toFixed(2);
+    console.log(chalk.green(`\n✔ Database exported successfully!`));
+    console.log(chalk.cyan(`   File: ${relPath} (${sizeKb} KB)`));
+  } else {
+    console.error(chalk.red(`\n✖ Database export failed.`));
+    process.exit(1);
+  }
+}
+
+/**
+ * Streams stdout from container dump command into a local file.
+ */
+function exportDbToFile(cmdArgs, outputFile) {
+  return new Promise((resolve) => {
+    const outStream = fs.createWriteStream(outputFile);
+    const proc = spawn("docker", cmdArgs, { stdio: ["inherit", "pipe", "pipe"], env: process.env });
+    proc.stdout.pipe(outStream);
+
+    let errOutput = "";
+    proc.stderr.on("data", (chunk) => {
+      errOutput += chunk.toString();
+    });
+
+    proc.on("close", (code) => {
+      outStream.close();
+      if (code === 0) {
+        resolve(true);
+      } else {
+        if (errOutput) console.error(chalk.yellow(`Warning/Stderr: ${errOutput.trim()}`));
+        resolve(code === 0);
+      }
+    });
+  });
+}
+
+/**
+ * Imports a .sql file from backups/ folder into the container database.
+ * @param {string} dbType - Target db type ('mysql', 'postgres', 'none').
+ * @param {string} [filenameArg] - Custom backup filename.
+ * @param {string} [userOpt] - Custom db user.
+ * @param {string} [passOpt] - Custom db password.
+ * @param {string} [dbOpt] - Custom db name.
+ */
+async function importDbCommand(dbType, filenameArg, userOpt, passOpt, dbOpt) {
+  checkComposeFile();
+  const env = getEnvVars();
+  const targetDbType = dbType === "none" ? getDbType(env) : dbType;
+
+  if (targetDbType === "none") {
+    console.error(chalk.yellow("[INFO] DB_TYPE is set to 'none'. No database available to import into."));
+    return;
+  }
+
+  const backupsDir = path.join(process.cwd(), "backups");
+  if (!fs.existsSync(backupsDir)) {
+    fs.mkdirSync(backupsDir, { recursive: true });
+  }
+
+  let inputFile;
+  if (filenameArg) {
+    let name = filenameArg;
+    if (!name.endsWith(".sql") && !fs.existsSync(name)) name += ".sql";
+    if (fs.existsSync(name)) {
+      inputFile = path.resolve(process.cwd(), name);
+    } else if (fs.existsSync(path.join(backupsDir, name))) {
+      inputFile = path.join(backupsDir, name);
+    } else {
+      console.error(chalk.red(`Error: Backup file '${filenameArg}' not found in current directory or 'backups/' folder.`));
+      process.exit(1);
+    }
+  } else {
+    const files = fs.readdirSync(backupsDir)
+      .filter(f => f.endsWith(".sql"))
+      .map(f => ({ name: f, time: fs.statSync(path.join(backupsDir, f)).mtimeMs }))
+      .sort((a, b) => b.time - a.time);
+
+    if (files.length === 0) {
+      console.error(chalk.red(`Error: No .sql backup files found in 'backups/' directory.`));
+      console.log(chalk.yellow(`Usage: npx blue-bird docker import <file.sql>`));
+      process.exit(1);
+    }
+
+    inputFile = path.join(backupsDir, files[0].name);
+    console.log(chalk.yellow(`[INFO] No file specified. Using most recent backup: '${files[0].name}'`));
+  }
+
+  const dbUser = userOpt || env.DB_USER || (targetDbType === "postgres" ? "postgres" : "root");
+  const dbPass = passOpt || env.DB_PASSWORD || (targetDbType === "postgres" ? "postgres" : "root");
+  const dbName = dbOpt || env.DB_NAME || "blue_bird";
+
+  let cmdArgs = [];
+  if (targetDbType === "postgres") {
+    cmdArgs = ["compose", "exec", "-T", "postgres", "psql", `-U${dbUser}`, "-d", dbName];
+  } else {
+    cmdArgs = ["compose", "exec", "-T", "mysql", "mysql", `-u${dbUser}`, `-p${dbPass}`, dbName];
+  }
+
+  const relPath = path.relative(process.cwd(), inputFile);
+  console.log(chalk.cyan(`📥 Importing SQL dump '${relPath}' into ${targetDbType.toUpperCase()} database '${dbName}'...`));
+
+  const success = await importDbFromFile(cmdArgs, inputFile);
+  if (success) {
+    console.log(chalk.green(`\n✔ Database imported successfully from '${relPath}'!`));
+  } else {
+    console.error(chalk.red(`\n✖ Database import failed.`));
+    process.exit(1);
+  }
+}
+
+/**
+ * Streams a local .sql file into container stdin.
+ */
+function importDbFromFile(cmdArgs, inputFile) {
+  return new Promise((resolve) => {
+    const inStream = fs.createReadStream(inputFile);
+    const proc = spawn("docker", cmdArgs, { stdio: ["pipe", "inherit", "pipe"], env: process.env });
+    inStream.pipe(proc.stdin);
+
+    let errOutput = "";
+    proc.stderr.on("data", (chunk) => {
+      errOutput += chunk.toString();
+    });
+
+    proc.on("close", (code) => {
+      if (code === 0) {
+        resolve(true);
+      } else {
+        if (errOutput) console.error(chalk.yellow(`Warning/Stderr: ${errOutput.trim()}`));
+        resolve(code === 0);
+      }
+    });
+  });
+}
+
 /**
  * Handles cleaning up and pruning unused Docker resources.
  * @param {boolean} forceOpt - Force cleaning without user confirmation.
@@ -385,12 +672,43 @@ async function pm2Command(pm2Args = []) {
 }
 
 /**
- * Handles interactive shell connections into the Redis container.
+ * Handles interactive shell connections or smart query subcommands into the Redis container.
+ * @param {string[]} redisArgs - Subcommands or key parameters.
  */
-async function redisCommand() {
+async function redisCommand(redisArgs = []) {
   checkComposeFile();
   const cmdArgs = ["compose", "exec", "redis", "redis-cli"];
-  await runCmd("docker", cmdArgs);
+
+  if (redisArgs.length > 0) {
+    const firstArg = redisArgs[0].toLowerCase();
+
+    if (firstArg === "monitor") {
+      console.log(chalk.cyan("📡 Monitoring live Redis commands... (Press Ctrl+C to exit)"));
+      cmdArgs.push("monitor");
+    } else if (firstArg === "keys") {
+      const pattern = redisArgs[1] || "*";
+      console.log(chalk.cyan(`🔑 Fetching Redis keys matching '${pattern}'...`));
+      cmdArgs.push("keys", pattern);
+    } else if (firstArg === "key") {
+      const keyName = redisArgs[1];
+      if (!keyName) {
+        console.error(chalk.red("Error: Please specify a key name. Example: npx blue-bird docker redis key session:123"));
+        process.exit(1);
+      }
+      console.log(chalk.cyan(`📄 Getting value for Redis key '${keyName}'...`));
+      cmdArgs.push("get", keyName);
+    } else {
+      cmdArgs.push(...redisArgs);
+    }
+  } else {
+    console.log(chalk.cyan("Connecting to Redis interactive terminal (redis-cli)..."));
+  }
+
+  const code = await runCmd("docker", cmdArgs);
+  if (code !== 0) {
+    console.error(chalk.yellow("Make sure the Redis container is running: npx blue-bird docker start redis"));
+    process.exit(1);
+  }
 }
 
 /**
@@ -450,23 +768,23 @@ async function main() {
     case "pm2":
       await pm2Command(args.slice(1));
       break;
+    case "export":
+    case "dump":
+      await exportDbCommand("none", args[1]);
+      break;
+    case "import":
+    case "restore":
+      await importDbCommand("none", args[1]);
+      break;
     case "redis":
-      await redisCommand();
+      await redisCommand(args.slice(1));
       break;
     case "mysql":
     case "postgres":
     case "psql":
-    case "db": {
-      let user, password, db, root = false;
-      for (let i = 1; i < args.length; i++) {
-        if (args[i] === "-u" || args[i] === "--user") user = args[++i];
-        else if (args[i] === "-p" || args[i] === "--password") password = args[++i];
-        else if (args[i] === "-d" || args[i] === "--db") db = args[++i];
-        else if (args[i] === "--root") root = true;
-      }
-      await dbClientCommand(user, password, db, root, command);
+    case "db":
+      await dbClientCommand(args.slice(1), command);
       break;
-    }
     case "df":
     case "disk":
       console.log(chalk.cyan("📊 Docker Disk Usage:"));
@@ -481,7 +799,7 @@ async function main() {
     }
     default:
       console.log(chalk.yellow(`Unknown docker command: ${command}`));
-      console.log("Available commands: dev, start, stop, build, ps, logs, pm2, mysql/postgres/db, redis, df/disk, prune/clean");
+      console.log("Available commands: dev, start, stop, build, ps, logs, pm2, export/dump, import/restore, mysql/postgres/db, redis, df/disk, prune/clean");
   }
 }
 

package/core/database.js

@@ -258,6 +258,142 @@ class Database {
       throw err;
     }
   }
+
+  /**
+   * Executes a paginated SQL query.
+   * Runs an automatic count query to calculate total records and pages, then appends LIMIT and OFFSET.
+   *
+   * @param {string} sql - SQL query string.
+   * @param {Array} [params=[]] - Query parameters.
+   * @param {Object} [options={}] - Pagination options: page, limit, cache.
+   * @returns {Promise<{data: Array, total: number, page: number, limit: number, totalPages: number}>}
+   * @example const result = await connection.paginate("SELECT * FROM users WHERE status = ?", ["active"], { page: 1, limit: 10 });
+   */
+  async paginate(sql, params = [], options = {}) {
+    const page = Math.max(1, parseInt(options.page) || 1);
+    const limit = Math.max(1, parseInt(options.limit) || 10);
+    const offset = (page - 1) * limit;
+
+    const cleanSql = sql.trim().replace(/;$/, "");
+    const countSql = `SELECT COUNT(*) as total FROM (${cleanSql}) as _count_subquery`;
+
+    const countResult = await this.query(countSql, params, { return_row: true });
+    const total = Number(countResult?.total || countResult?.count || 0);
+    const totalPages = Math.ceil(total / limit);
+
+    const paginatedSql = `${cleanSql} LIMIT ${limit} OFFSET ${offset}`;
+    const rows = await this.query(paginatedSql, params, options);
+
+    return {
+      data: Array.isArray(rows) ? rows : [],
+      total,
+      page,
+      limit,
+      totalPages,
+    };
+  }
+
+  /**
+   * Executes a database transaction with automatic commit and rollback.
+   * @param {Function} callback - Async function receiving transaction client: async (tx) => { ... }
+   * @returns {Promise<*>} Value returned from callback.
+   * @example
+   * const userId = await connection.transaction(async (tx) => {
+   *   const id = await tx.query("INSERT INTO users (name) VALUES (?)", ["Alice"]);
+   *   await tx.query("INSERT INTO profiles (user_id) VALUES (?)", [id]);
+   *   return id;
+   * });
+   */
+  async transaction(callback) {
+    if (!mysqlPromise && !pgPromise) throw new Error("[DATABASE ERROR] No database driver available.");
+    if (!this.pool) {
+      const initialized = await this.init();
+      if (!initialized) throw new Error("[DATABASE ERROR] Failed to initialize database pool.");
+    }
+
+    if (this.type === "postgres" && pgPromise) {
+      const client = await this.pool.connect();
+      try {
+        await client.query("BEGIN");
+
+        const tx = {
+          query: async (sql, params = [], options = {}) => {
+            const queryOptions = typeof options === "string" ? { [options]: true } : options;
+            const cleanSql = sql.trim();
+            const isSelect = cleanSql.toLowerCase().startsWith("select");
+            const isInsert = cleanSql.toLowerCase().startsWith("insert");
+
+            let paramIndex = 1;
+            const pgSql = cleanSql.replace(/\?/g, () => `$${paramIndex++}`);
+            const res = await client.query(pgSql, params);
+
+            if (isSelect) {
+              const rows = res.rows || [];
+              return queryOptions.return_row ? (rows[0] || null) : rows;
+            }
+            if (isInsert) {
+              if (res.rows && res.rows.length > 0) return res.rows[0].id || res.rows[0];
+              return res.rowCount;
+            }
+            return res.rowCount;
+          }
+        };
+
+        const result = await callback(tx);
+        await client.query("COMMIT");
+        return result;
+      } catch (err) {
+        await client.query("ROLLBACK").catch(() => {});
+        console.error("[DATABASE ERROR] Transaction rolled back:", err.message);
+        throw err;
+      } finally {
+        client.release();
+      }
+    } else {
+      const connection = await this.pool.getConnection();
+      try {
+        await connection.beginTransaction();
+
+        const tx = {
+          query: async (sql, params = [], options = {}) => {
+            const queryOptions = typeof options === "string" ? { [options]: true } : options;
+            const cleanSql = sql.trim();
+            const isSelect = cleanSql.toLowerCase().startsWith("select");
+            const isInsert = cleanSql.toLowerCase().startsWith("insert");
+
+            const [results] = await connection.execute(cleanSql, params);
+
+            if (isSelect) {
+              const rows = Array.isArray(results) ? results : [];
+              return queryOptions.return_row ? (rows[0] || null) : rows;
+            }
+            if (isInsert) {
+              return results.insertId || results;
+            }
+            return results;
+          }
+        };
+
+        const result = await callback(tx);
+        await connection.commit();
+        return result;
+      } catch (err) {
+        await connection.rollback().catch(() => {});
+        console.error("[DATABASE ERROR] Transaction rolled back:", err.message);
+        throw err;
+      } finally {
+        connection.release();
+      }
+    }
+  }
+
+  /**
+   * Alias for transaction().
+   * @param {Function} callback
+   */
+  async executeTransaction(callback) {
+    return this.transaction(callback);
+  }
 }
 
 export { Database, DB_TYPE };