@ttoss/postgresdb-cli 0.1.20 → 0.1.22

package/README.md

@@ -1,6 +1,6 @@
 # @ttoss/postgresdb-cli
 
-This package provides a CLI to interact with a PostgreSQL database using the [sequelize](https://sequelize.org/) library.
+CLI for managing PostgreSQL databases with [Sequelize](https://sequelize.org/).
 
 ## Installation
 
@@ -8,50 +8,80 @@ This package provides a CLI to interact with a PostgreSQL database using the [se
 pnpm add -D @ttoss/postgresdb-cli
 ```
 
-## Usage
+## Prerequisites
 
-First, you need to create define the `db` object in your project using the `@ttoss/postgresdb` package. Check [@ttoss/postgresdb documentation](https://ttoss.dev/docs/modules/packages/postgresdb/) for more information. The CLI will use this object to load the models and interact with the database.
+Define your `db` object using [@ttoss/postgresdb](https://ttoss.dev/docs/modules/packages/postgresdb/). The CLI imports this object to load models and interact with the database.
 
-Second, you need to define the following environment variables to connect to the database:
+Set connection environment variables in `.env` files:
 
-- `DB_NAME`: database name
-- `DB_USERNAME`: database username
-- `DB_PASSWORD`: database password
-- `DB_HOST`: database host
-- `DB_PORT`: database port. Default: 5432
+```env
+DB_NAME=postgres
+DB_USERNAME=postgres
+DB_PASSWORD=mysecretpassword
+DB_HOST=localhost
+DB_PORT=5432
+```
+
+**Environment-specific configuration:** Use `--environment` or `-e` flag to load `.env.<environment>` files (e.g., `.env.Production`, `.env.Staging`) instead of the default `.env`. This prevents accidental use of production credentials.
+
+## Commands
+
+### `sync`
+
+[Synchronize](https://sequelize.org/docs/v6/core-concepts/model-basics/#model-synchronization) database schema with models:
+
+```bash
+pnpm dlx @ttoss/postgresdb-cli sync -e Development
+```
 
-### Sync
+**⚠️ Required:** The `--environment` or `-e` flag is **mandatory** to explicitly specify which environment credentials to use. This prevents accidental operations on the wrong database.
 
-To [sync](https://sequelize.org/docs/v6/core-concepts/model-basics/#model-synchronization) the database schema with the models, you can use the `sync` command:
+**Using environment-specific credentials:**
 
 ```bash
-pnpm dlx @ttoss/postgresdb-cli sync
+pnpm dlx @ttoss/postgresdb-cli sync --alter -e Production
 ```
 
-Or you can add the command to your `package.json` scripts for easier access:
+This loads variables from `.env.Production`.
+
+**Behavior:**
+
+- **Without `--alter`**: Creates new tables only (preserves existing schema)
+- **With `--alter`**: Creates new tables, adds/removes columns to match models, creates new indexes (preserves tables and indexes not in models). **Requires confirmation** before executing.
+
+⚠️ **Caution:** The `--alter` flag modifies your database schema. Removing columns will **delete data permanently**. The CLI will prompt for confirmation before proceeding. Always backup your database before using `--alter` in production. For production environments, use proper migration tools instead of `sync`.
+
+**Testing before using `--alter`:** Always ensure your models have comprehensive tests before running `sync --alter`. Tests validate that all model properties are correctly defined and prevent accidental column removal. If a column is missing from your model definition, `--alter` will drop it from the database. See the [@ttoss/postgresdb testing guide](https://ttoss.dev/docs/modules/packages/postgresdb/#testing) for details on setting up model tests.
+
+**Add to `package.json` for convenience:**
 
 ```json
 {
   "scripts": {
-    "sync": "ttoss-postgresdb sync"
+    "sync:dev": "ttoss-postgresdb sync -e Development",
+    "sync:staging": "ttoss-postgresdb sync --alter -e Staging",
+    "sync:prod": "ttoss-postgresdb sync --alter -e Production"
   }
 }
 ```
 
-#### Options
+**Options:**
 
-- `--db-path` or `-d`: Path to the file where the `db` object is defined. Default: `./src/db.js`.
-- `--alter`: Alter the database schema to match the models. Default: `false`.
+- `--db-path, -d`: Path to `db` object file (default: `./src/db.js`)
+- `--alter`: Alter schema to match models (default: `false`)
+- `--environment, -e`: **(Required)** Specify environment to load `.env.<environment>` file
 
-### ERD (Entity-Relationship Diagram)
+### `erd`
 
-To generate an [ERD](https://en.wikipedia.org/wiki/Entity%E2%80%93relationship_model) of the database, you can use the `erd` command:
+Generate an [Entity-Relationship Diagram](https://en.wikipedia.org/wiki/Entity%E2%80%93relationship_model) from your models:
 
 ```bash
 pnpm dlx @ttoss/postgresdb-cli erd
 ```
 
-Or you can add the command to your `package.json` scripts for easier access:
+**Note:** This command generates diagrams from model definitions only - database credentials are **not required** unless you need to validate against an actual database.
+
+**Add to `package.json` for convenience:**
 
 ```json
 {
@@ -61,7 +91,7 @@ Or you can add the command to your `package.json` scripts for easier access:
 }
 ```
 
-#### Options
+**Options:**
 
-- `--db-path` or `-d`: Path to the file where the `db` object is defined. Default: `./src/db.js`.
-- `--engine`: Layout engine to use, options are "circo", "dot", "fdp", "neato", "osage", "twopi". Default to "circo"
+- `--db-path, -d`: Path to `db` object file (default: `./src/db.js`)
+- `--engine`: Layout engine - `circo`, `dot`, `fdp`, `neato`, `osage`, `twopi` (default: `circo`)

package/dist/esm/index.js

@@ -11,7 +11,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@ttoss/postgresdb-cli",
-  version: "0.1.19",
+  version: "0.1.21",
   description: "A library to handle PostgreSQL database actions through the command line",
   license: "MIT",
   author: "ttoss",
@@ -53,14 +53,23 @@ import * as fs from "fs";
 import sequelizeErd from "sequelize-erd";
 
 // src/getDbDynamically.ts
-import "dotenv/config";
 import * as builtinModules from "module";
 import path from "path";
+import { config } from "dotenv";
 import * as esbuild from "esbuild";
 var nodeBuiltins = builtinModules.builtinModules;
 var getDbDynamically = /* @__PURE__ */__name(async ({
-  dbPath
+  dbPath,
+  environment
 }) => {
+  if (environment) {
+    const envPath = path.resolve(process.cwd(), `.env.${environment}`);
+    config({
+      path: envPath,
+      override: true
+    });
+    console.info(`Loaded environment variables from .env.${environment}`);
+  }
   const lastEntryPointName = dbPath.split("/").pop();
   const filename = lastEntryPointName?.split(".")[0];
   const outfile = path.resolve(process.cwd(), "out", filename + ".js");
@@ -104,13 +113,45 @@ var erd = /* @__PURE__ */__name(async ({
 }, "erd");
 
 // src/sync.ts
+import * as readline from "readline";
+var confirmAlter = /* @__PURE__ */__name(() => {
+  return new Promise(resolve => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    rl.question("Do you want to continue? (yes/no): ", answer => {
+      rl.close();
+      resolve(answer.toLowerCase() === "yes" || answer.toLowerCase() === "y");
+    });
+  });
+}, "confirmAlter");
 var sync = /* @__PURE__ */__name(async ({
   alter,
-  dbPath
+  dbPath,
+  environment
 }) => {
+  console.info("Starting database synchronization...");
+  console.info("Environment: %s", environment || "default (.env)");
+  console.info("DB Path: %s", dbPath);
+  console.info("Mode: %s", alter ? "ALTER (will modify schema)" : "SAFE (create tables only)");
+  if (alter) {
+    console.warn("\n\u26A0\uFE0F  WARNING: ALTER mode will modify your database schema!");
+    console.warn("   - Columns not in models will be DELETED (data loss!)");
+    console.warn("   - New columns will be added");
+    console.warn("   - Tables not in models will be preserved\n");
+    const confirmed = await confirmAlter();
+    if (!confirmed) {
+      console.info("Synchronization cancelled.");
+      process.exit(0);
+    }
+  }
+  console.info("\nConnecting to database...");
   const db = await getDbDynamically({
-    dbPath
+    dbPath,
+    environment
   });
+  console.info("Synchronizing schema...");
   await db.sequelize.sync({
     /**
     * Don't force anymore because it's better to run migrations.
@@ -118,13 +159,13 @@ var sync = /* @__PURE__ */__name(async ({
     force: false,
     alter
   });
-  console.info("Database synced (alter: %s)", alter);
+  console.info("\u2713 Database synchronized successfully (alter: %s)", alter);
   db.sequelize.close();
 }, "sync");
 
 // src/index.ts
 var program = new Command();
 program.name("ttoss-postgresdb").version(package_default.version).description("ttoss postgresdb CLI");
-program.command("sync").description("Sync database").action(sync).option("--alter", "Alter sync", false).option("-d, --db-path <dbPath>", "db initialization file path", "src/db.ts");
+program.command("sync").description("Sync database").action(sync).option("--alter", "Alter sync", false).option("-d, --db-path <dbPath>", "db initialization file path", "src/db.ts").requiredOption("-e, --environment <environment>", "Environment name to load .env.<environment> file");
 program.command("erd").description("Generate ERD").action(erd).option("-d, --db-path <dbPath>", "db initialization file path", "src/db.ts").option("--engine <engine>", "Layout engine to use", "circo");
 program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/postgresdb-cli",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "A library to handle PostgreSQL database actions through the command line",
   "license": "MIT",
   "author": "ttoss",
@@ -30,7 +30,7 @@
   "devDependencies": {
     "jest": "^30.2.0",
     "tsup": "^8.5.1",
-    "@ttoss/config": "^1.35.10"
+    "@ttoss/config": "^1.35.11"
   },
   "keywords": [
     "database",