@seip/blue-bird 0.7.4 → 0.7.6

package/.env_example

@@ -21,16 +21,14 @@ REDIS_PASSWORD=""
 PM2_INSTANCES=1
 
 # Database Configuration (Used only for local development outside Docker)
-# SQLite (Default)
-DATABASE_URL="file:./dev.db"
-
-# MySQL (Uncomment to use MySQL locally or DEV)
-# DATABASE_URL="mysql://root:root@localhost:3306/blue_bird"
+# MySQL
+DATABASE_URL="mysql://root:root@localhost:3306/blue_bird"
 
 # PostgreSQL (Uncomment to use PostgreSQL locally or DEV)
-# DATABASE_URL="postgresql://root:root@localhost:5432/blue_bird?schema=public"
+# DATABASE_URL="postgresql://postgres:root@localhost:5432/blue_bird?schema=public"
 
 # Database / Docker Configuration
+DB_TYPE="mysql"
 DB_NAME="blue_bird"
 DB_USER="root"
 DB_PASSWORD="root"

package/AGENTS.md

@@ -156,31 +156,34 @@ apiRouter.use(App.helmet());
 
 ## 8. Docker Compose CLI
 
-Blue Bird features a built-in Docker Compose CLI wrapper to deploy and manage containerized development databases and production stacks.
+Blue Bird features a built-in Docker Compose CLI wrapper (`core/cli/docker.js`) to deploy and manage containerized development databases and production stacks across MySQL, PostgreSQL, or no-database (`none`) architectures.
 
 Production deployments always use Docker for orchestration, running:
 - Nginx: Serves static files directly from `frontend/dist/client/` and blocks common scanner requests (`.env`, `.git`, etc.) with fallback to Express.
 - Node.js App: Managed via PM2 in cluster mode using `PM2_INSTANCES` configuration (defaults to `1`, can be set to `max`).
-- MySQL: Database service.
+- Database: MySQL (`mysql:8.0`) or PostgreSQL (`postgres:18-alpine`), dynamically detected via `getDbType()` reading `DB_TYPE` / `DATABASE_URL` from `.env`.
 - Redis: Memory caching and session store.
 
 ```bash
 # Manage containers using blue-bird CLI
-npx blue-bird docker start          # Starts production app stack (mysql, redis, app, nginx)
-npx blue-bird docker start mysql    # Starts MySQL container only (useful for local development)
+npx blue-bird docker start          # Starts production app stack (DB, redis, app, nginx)
+npx blue-bird docker start db       # Starts configured database container only (postgres or mysql)
 npx blue-bird docker start redis    # Starts Redis container only
-npx blue-bird docker start dbs      # Starts both database containers (MySQL + Redis)
+npx blue-bird docker start dbs      # Starts both database containers (configured DB + Redis)
 npx blue-bird docker stop           # Stops all running containers
 npx blue-bird docker build          # Builds/rebuilds application image
 npx blue-bird docker ps             # Shows status of active containers
 npx blue-bird docker logs           # Tails Node.js app container logs
+npx blue-bird docker logs db        # Tails configured database container logs
 npx blue-bird docker pm2 [args]     # Runs PM2 commands inside the app container (e.g. status, monit)
-npx blue-bird docker mysql          # Runs interactive MySQL client terminal inside the container
-npx blue-bird docker redis          # Runs interactive Redis client terminal inside the container
+npx blue-bird docker db             # Runs interactive shell inside container (psql for Postgres, mysql for MySQL)
+npx blue-bird docker psql           # Runs interactive PostgreSQL client terminal inside container
+npx blue-bird docker mysql          # Runs interactive MySQL client terminal inside container
+npx blue-bird docker redis          # Runs interactive Redis client terminal inside container
 npx blue-bird docker prune          # Cleans unused volumes, dangling images, and BuildKit caches
 ```
 
-The container names and virtual networks are namespaced by the `TITLE` environment variable parsed from `.env` to prevent resource collisions on VPS hosts. Alternatively, PM2 and other services can be run manually in standalone server environments.
+The container names and virtual networks are namespaced by the `TITLE` environment variable parsed from `.env` to prevent resource collisions on VPS hosts. Alternatively, PM2 and other services can be run manually in standalone server environments by configuring `DATABASE_URL` inside `.env`.
 
 ## 9. AI Development Guidelines
 
@@ -191,18 +194,23 @@ The container names and virtual networks are namespaced by the `TITLE` environme
 
 ## 10. Database Module (database.js)
 
-Blue Bird provides a unified wrapper class for MySQL databases via `mysql2` connections pool with automatic retries and built-in query caching:
+Blue Bird provides a unified wrapper class (`core/database.js`) supporting **MySQL (`mysql2/promise`)** and **PostgreSQL (`pg`)**. It features connection pooling, automatic retries on startup, query formatting, and built-in Redis query caching:
+
+- **Dynamic Initialization:** When `npx blue-bird` (`core/cli/init.js`) runs, it prompts the developer for the database type (`none`, `mysql`, `postgres`). It then intelligently copies the correct `docker-compose.yml` template (`docker-compose.mysql.yml`, `docker-compose.postgres.yml`, or `docker-compose.none.yml`) and configures `.env` with `DB_TYPE` and `DATABASE_URL`.
+- **Parameter Placeholders:** When using `pg` for PostgreSQL with `connection.query()`, `?` placeholders are automatically translated to `$1, $2, ...` under the hood.
 
 ```javascript
-import connection from "@seip/blue-bird/core/database.js";
+import { Database, DB_TYPE } from "@seip/blue-bird/core/database.js";
+
+const connection = new Database(20);
 
-// Basic SELECT query returning single row
+// Basic SELECT query returning single row (Supports both MySQL and PostgreSQL)
 const user = await connection.query("SELECT * FROM users WHERE id = ?", [1], "return_row");
 
 // Query caching in Redis (stores results in Redis for 60 seconds)
 const stats = await connection.query("SELECT COUNT(*) as cnt FROM logs", [], { cache: 60 });
 
-// INSERT query returns insertId directly
+// INSERT query returns insertId directly (or row ID/rowCount in Postgres)
 const newUserId = await connection.query("INSERT INTO users (name) VALUES (?)", ["Alice"]);
 ```
 

package/README.md

@@ -39,7 +39,11 @@ npm install @seip/blue-bird
 npx blue-bird
 ```
 
-_This copies the base structure: `backend`, `frontend`, `docker`, `docker-compose.yml`, `AGENTS.md`, and `.env`._
+When run, the interactive CLI prompts for your preferred infrastructure configuration:
+- Database Selection: Choose between `none`, `mysql`, or `postgres`.
+- Credentials: Set your database name, user, password, and port (`3306` or `5432`).
+
+The CLI intelligently copies the appropriate Docker configuration (`docker/docker-compose.mysql.yml`, `docker/docker-compose.postgres.yml`, or `docker/docker-compose.none.yml`) to your project root as `docker-compose.yml`. It also writes the environment settings (`DB_TYPE`, `DATABASE_URL`) to `.env` and installs the required database packages (`mysql2` or `pg`) automatically.
 
 ### 3. Run Development Server / Modo Desarrollo
 
@@ -220,18 +224,38 @@ webRouter.use(App.helmet());
 
 ### 7. Database wrapper (`Database`)
 
-MySQL database client connection pool configuration featuring automated retry loops, query formatting utilities, and Redis query caching.
+Blue Bird provides a unified, multi-database client wrapper (`core/database.js`) supporting **MySQL** and **PostgreSQL** with automated connection retry loops, query formatting utilities, and Redis query caching.
+
+#### Driver Support
+- **Native MySQL (`mysql2/promise`)**: High-performance connection pool for MySQL 8.0+.
+- **Native PostgreSQL (`pg`)**: Connection pool for PostgreSQL 18+. When running standard queries with `connection.query(sql, params)`, the wrapper automatically converts `?` parameter placeholders into PostgreSQL `$1, $2, ...` syntax, allowing unified SQL query writing across both database engines.
+- **No Database (`none`)**: If no database is configured, the wrapper is disabled gracefully without crashing the server.
+
+#### Standalone & Remote Database Configuration
+You can connect to any local or remote database instance (outside Docker, such as Supabase, Neon, AWS RDS, or local services) simply by defining the `DATABASE_URL` in your `.env` file:
+
+```env
+DB_TYPE="postgres"
+DATABASE_URL="postgresql://postgres:password@localhost:5432/blue_bird?schema=public"
+# OR for MySQL:
+# DATABASE_URL="mysql://root:password@localhost:3306/blue_bird"
+```
+
+#### Usage Examples
 
 ```javascript
-import connection from "@seip/blue-bird/core/database.js";
+import { Database, DB_TYPE } from "@seip/blue-bird/core/database.js";
+
+// Instantiate the database connection pool with a connection limit (e.g., 20)
+const connection = new Database(20);
 
-// Fetch single row from a SELECT query
+// 1. Basic SELECT query returning single row (Works for both MySQL and PostgreSQL using ? placeholders)
 const user = await connection.query("SELECT * FROM users WHERE email = ?", ["test@example.com"], "return_row");
 
-// Fetch rows with 60 seconds Redis caching enabled
+// 2. Fetch rows with 60 seconds Redis caching enabled
 const stats = await connection.query("SELECT COUNT(*) as count FROM access_logs", [], { cache: 60 });
 
-// INSERT queries return the last insert ID directly
+// 3. INSERT query (returns insertId for MySQL, or inserted row ID / rowCount for PostgreSQL)
 const newId = await connection.query("INSERT INTO users (name) VALUES (?)", ["John"]);
 ```
 
@@ -260,9 +284,9 @@ Nginx reverse proxy is preconfigured with a page cache zone (`astro_cache`) that
 
 ---
 
-## 🐳 Docker CLI Workflow
+## Docker CLI Workflow
 
-Blue Bird comes with a built-in Docker CLI wrapper that handles both local development database bootstrapping and full-stack VPS production deployments.
+Blue Bird comes with a built-in Docker CLI wrapper that handles both local development database bootstrapping and full-stack VPS production deployments across MySQL, PostgreSQL, or no-database architectures.
 
 ### Commands Syntax:
 
@@ -272,16 +296,16 @@ npx blue-bird docker <command> [options]
 
 ### Supported Actions:
 
-- **`npx blue-bird docker start`**: Boots the production stack (Node.js App + Nginx + MySQL + Redis).
-- **`npx blue-bird docker start mysql`**: Boots the MySQL container only (great for local HTTP development).
+- **`npx blue-bird docker start`**: Boots the production stack (Node.js App + Nginx + Database + Redis).
+- **`npx blue-bird docker start db`** (or `postgres` / `mysql`): Boots the configured database container only (great for local development outside Docker).
 - **`npx blue-bird docker start redis`**: Boots the Redis container only.
-- **`npx blue-bird docker start dbs`**: Boots both database containers (MySQL + Redis).
-- **`npx blue-bird docker stop`**: Stops all active containers.
+- **`npx blue-bird docker start dbs`**: Boots both database containers (configured DB + Redis).
+- **`npx blue-bird docker stop`**: Stops all active project containers.
 - **`npx blue-bird docker build [--no-cache]`**: Builds or updates the Node.js production image.
 - **`npx blue-bird docker ps`**: Lists running project containers and ports.
-- **`npx blue-bird docker logs [app|mysql]`**: Tails logs for the specified container.
+- **`npx blue-bird docker logs [app|db|postgres|mysql]`**: Tails logs for the specified container.
 - **`npx blue-bird docker pm2 [args]`**: Runs PM2 commands inside the Node.js application container (e.g. `status`, `monit`, `reload all`).
-- **`npx blue-bird docker db`**: Connects into the container's interactive MySQL shell using credentials from `.env`.
+- **`npx blue-bird docker db`** (or `psql` / `mysql`): Connects into the container's interactive database shell (`psql` for PostgreSQL, `mysql` for MySQL) using credentials from `.env`.
 - **`npx blue-bird docker redis`**: Connects into the container's interactive Redis CLI terminal.
 - **`npx blue-bird docker prune`**: Safely clears orphaned volumes, dangling build caches, and images.
 

package/core/cli/docker.js

@@ -25,6 +25,32 @@ function getEnvVars() {
   return env;
 }
 
+/**
+ * Determines the target database type (mysql or postgres) from environment variables.
+ * @param {Object} [env] - Environment dictionary.
+ * @returns {string} 'postgres' or 'mysql'.
+ */
+function getDbType(env = getEnvVars()) {
+  if (env.DB_TYPE && (env.DB_TYPE.toLowerCase() === "postgres" || env.DB_TYPE.toLowerCase() === "postgresql" || env.DB_TYPE.toLowerCase() === "pg")) {
+    return "postgres";
+  }
+  if (env.DB_TYPE && env.DB_TYPE.toLowerCase() === "mysql") {
+    return "mysql";
+  }
+  if (env.DB_TYPE && env.DB_TYPE.toLowerCase() === "none") {
+    return "none";
+  }
+  if (env.DATABASE_URL && !env.DATABASE_URL.startsWith("#")) {
+    if (env.DATABASE_URL.startsWith("postgres://") || env.DATABASE_URL.startsWith("postgresql://")) {
+      return "postgres";
+    }
+    if (env.DATABASE_URL.startsWith("mysql://")) {
+      return "mysql";
+    }
+  }
+  return "mysql";
+}
+
 /**
  * Spawns a child process and inherits standard IO for interactive terminal sessions.
  * @param {string} command - The binary to execute.
@@ -56,14 +82,20 @@ function checkComposeFile() {
  */
 async function startCommand(service) {
   checkComposeFile();
+  const dbType = getDbType();
 
-  if (service === "mysql" || service === "--mysql" || service === "dev") {
-    console.log(chalk.cyan("Starting MySQL container..."));
-    const code = await runCmd("docker", ["compose", "up", "-d", "mysql"]);
+  if (service === "mysql" || service === "--mysql" || service === "postgres" || service === "--postgres" || service === "db" || service === "--db" || service === "dev") {
+    const targetContainer = (service === "postgres" || service === "--postgres") ? "postgres" : ((service === "mysql" || service === "--mysql") ? "mysql" : dbType);
+    if (targetContainer === "none") {
+      console.log(chalk.yellow("[INFO] DB_TYPE is set to 'none', skipping database container startup."));
+      return;
+    }
+    console.log(chalk.cyan(`Starting ${targetContainer.toUpperCase()} container...`));
+    const code = await runCmd("docker", ["compose", "up", "-d", targetContainer]);
     if (code === 0) {
-      console.log(chalk.green("MySQL started."));
+      console.log(chalk.green(`${targetContainer.toUpperCase()} started.`));
     } else {
-      console.error(chalk.red("Error starting MySQL."));
+      console.error(chalk.red(`Error starting ${targetContainer}. Make sure '${targetContainer}' service is defined in docker-compose.yml.`));
       process.exit(1);
     }
   } else if (service === "redis" || service === "--redis") {
@@ -76,8 +108,19 @@ async function startCommand(service) {
       process.exit(1);
     }
   } else if (service === "dbs" || service === "databases") {
-    console.log(chalk.cyan("Starting Database containers (MySQL + Redis)..."));
-    const code = await runCmd("docker", ["compose", "up", "-d", "mysql", "redis"]);
+    if (dbType === "none") {
+      console.log(chalk.cyan("DB_TYPE is 'none', starting Redis container only..."));
+      const code = await runCmd("docker", ["compose", "up", "-d", "redis"]);
+      if (code === 0) {
+        console.log(chalk.green("Redis started."));
+      } else {
+        console.error(chalk.red("Error starting Redis."));
+        process.exit(1);
+      }
+      return;
+    }
+    console.log(chalk.cyan(`Starting Database containers (${dbType.toUpperCase()} + Redis)...`));
+    const code = await runCmd("docker", ["compose", "up", "-d", dbType, "redis"]);
     if (code === 0) {
       console.log(chalk.green("Database containers started."));
     } else {
@@ -85,7 +128,7 @@ async function startCommand(service) {
       process.exit(1);
     }
   } else if (service === "prod" || service === "app" || service === "--app" || !service) {
-    console.log(chalk.cyan("Starting production stack (MySQL + Redis + App + Nginx)..."));
+    console.log(chalk.cyan("Starting production stack (DB + Redis + App + Nginx)..."));
     const code = await runCmd("docker", ["compose", "--profile", "prod", "up", "-d"]);
     if (code === 0) {
       console.log(chalk.green("Production stack started."));
@@ -94,7 +137,7 @@ async function startCommand(service) {
       process.exit(1);
     }
   } else {
-    console.error(chalk.red(`Unknown service '${service}'. Use: mysql, redis, dbs, prod.`));
+    console.error(chalk.red(`Unknown service '${service}'. Use: mysql, postgres, db, redis, dbs, prod.`));
     process.exit(1);
   }
 }
@@ -105,16 +148,22 @@ async function startCommand(service) {
  */
 async function stopCommand(service) {
   checkComposeFile();
+  const dbType = getDbType();
 
   if (!service || service === "all") {
     console.log(chalk.cyan("Stopping all Blue Bird containers..."));
     await runCmd("docker", ["compose", "--profile", "prod", "down"]);
     console.log(chalk.green("All containers stopped."));
-  } else if (service === "mysql" || service === "--mysql") {
-    console.log(chalk.cyan("Stopping MySQL..."));
-    await runCmd("docker", ["compose", "stop", "mysql"]);
-    await runCmd("docker", ["compose", "rm", "-f", "mysql"]);
-    console.log(chalk.green("MySQL stopped."));
+  } else if (service === "mysql" || service === "--mysql" || service === "postgres" || service === "--postgres" || service === "db" || service === "--db") {
+    const targetContainer = (service === "postgres" || service === "--postgres") ? "postgres" : ((service === "mysql" || service === "--mysql") ? "mysql" : dbType);
+    if (targetContainer === "none") {
+      console.log(chalk.yellow("[INFO] DB_TYPE is set to 'none', no database container to stop."));
+      return;
+    }
+    console.log(chalk.cyan(`Stopping ${targetContainer.toUpperCase()}...`));
+    await runCmd("docker", ["compose", "stop", targetContainer]);
+    await runCmd("docker", ["compose", "rm", "-f", targetContainer]);
+    console.log(chalk.green(`${targetContainer.toUpperCase()} stopped.`));
   } else if (service === "redis" || service === "--redis") {
     console.log(chalk.cyan("Stopping Redis..."));
     await runCmd("docker", ["compose", "stop", "redis"]);
@@ -126,7 +175,7 @@ async function stopCommand(service) {
     await runCmd("docker", ["compose", "--profile", "prod", "rm", "-f", "app"]);
     console.log(chalk.green("App container stopped."));
   } else {
-    console.error(chalk.red(`Unknown service '${service}'. Use: all, mysql, redis, app.`));
+    console.error(chalk.red(`Unknown service '${service}'. Use: all, mysql, postgres, db, redis, app.`));
     process.exit(1);
   }
 }
@@ -170,7 +219,15 @@ async function psCommand() {
 async function logsCommand(service, followOpt) {
   checkComposeFile();
   const follow = followOpt !== "--no-follow";
-  const targetService = service === "mysql" ? "mysql" : "app";
+  const dbType = getDbType();
+  let targetService = "app";
+  if (service === "mysql" || service === "postgres" || service === "db") {
+    targetService = service === "db" ? dbType : service;
+  }
+  if (targetService === "none") {
+    console.log(chalk.yellow("[INFO] DB_TYPE is set to 'none', no database container logs to display."));
+    return;
+  }
 
   const cmdArgs = ["compose"];
   if (targetService === "app") {
@@ -186,44 +243,72 @@ async function logsCommand(service, followOpt) {
 }
 
 /**
- * Handles interactive shell connections into the MySQL container.
+ * Handles interactive shell connections into the MySQL or PostgreSQL container.
  * @param {string} userOpt - DB username.
  * @param {string} passOpt - DB password.
  * @param {string} dbOpt - DB database name.
- * @param {boolean} rootOpt - Flag for overriding database credentials to connect as root.
+ * @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 mysqlCommand(userOpt, passOpt, dbOpt, rootOpt) {
+async function dbClientCommand(userOpt, passOpt, dbOpt, rootOpt, explicitService) {
   checkComposeFile();
   const env = getEnvVars();
+  const dbType = explicitService === "postgres" || explicitService === "psql" ? "postgres" : (explicitService === "mysql" ? "mysql" : getDbType(env));
+  if (dbType === "none") {
+    console.error(chalk.yellow("[INFO] DB_TYPE is set to 'none'. No database container available to connect to."));
+    return;
+  }
 
   let dbUser = userOpt;
   let dbPass = passOpt;
   let dbName = dbOpt;
 
-  if (rootOpt) {
-    dbUser = "root";
-    dbPass = env.DB_PASSWORD || "root";
+  if (dbType === "postgres") {
+    if (rootOpt) {
+      dbUser = "postgres";
+    } else {
+      dbUser = dbUser || env.DB_USER || "postgres";
+    }
+    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}...`));
+
+    const cmdArgs = ["compose", "exec", "postgres", "psql", `-U${dbUser}`];
+    if (dbName) {
+      cmdArgs.push("-d", dbName);
+    }
+    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"));
+      process.exit(1);
+    }
   } else {
-    dbUser = dbUser || env.DB_USER || "root";
-    dbPass = dbPass || env.DB_PASSWORD || "root";
-  }
-  dbName = dbName || env.DB_NAME || "blue_bird";
+    if (rootOpt) {
+      dbUser = "root";
+      dbPass = env.DB_PASSWORD || "root";
+    } else {
+      dbUser = dbUser || env.DB_USER || "root";
+      dbPass = dbPass || env.DB_PASSWORD || "root";
+    }
+    dbName = dbName || env.DB_NAME || "blue_bird";
 
-  const cmdArgs = ["compose", "exec", "mysql", "mysql", `-u${dbUser}`];
-  if (dbPass) {
-    cmdArgs.push(`-p${dbPass}`);
-  }
-  if (dbName) {
-    cmdArgs.push(dbName);
-  }
+    const cmdArgs = ["compose", "exec", "mysql", "mysql", `-u${dbUser}`];
+    if (dbPass) {
+      cmdArgs.push(`-p${dbPass}`);
+    }
+    if (dbName) {
+      cmdArgs.push(dbName);
+    }
 
-  const targetDb = dbName ? ` (database: {dbName})` : "";
-  console.log(chalk.cyan(`Connecting to MySQL shell in container as '${dbUser}'${targetDb}...`));
+    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) {
-    console.error(chalk.yellow("Make sure the MySQL container is running: npx blue-bird docker start mysql"));
-    process.exit(1);
+    const code = await runCmd("docker", cmdArgs);
+    if (code !== 0) {
+      console.error(chalk.yellow("Make sure the MySQL container is running: npx blue-bird docker start mysql"));
+      process.exit(1);
+    }
   }
 }
 
@@ -338,6 +423,8 @@ async function main() {
       await redisCommand();
       break;
     case "mysql":
+    case "postgres":
+    case "psql":
     case "db": {
       let user, password, db, root = false;
       for (let i = 1; i < args.length; i++) {
@@ -346,7 +433,7 @@ async function main() {
         else if (args[i] === "-d" || args[i] === "--db") db = args[++i];
         else if (args[i] === "--root") root = true;
       }
-      await mysqlCommand(user, password, db, root);
+      await dbClientCommand(user, password, db, root, command);
       break;
     }
     case "df":
@@ -363,7 +450,7 @@ async function main() {
     }
     default:
       console.log(chalk.yellow(`Unknown docker command: ${command}`));
-      console.log("Available commands: start, stop, build, ps, logs, pm2, mysql/db, redis, df/disk, prune/clean");
+      console.log("Available commands: start, stop, build, ps, logs, pm2, mysql/postgres/db, redis, df/disk, prune/clean");
   }
 }