prisma-sharding 0.0.4 → 0.0.6

package/README.md

@@ -168,8 +168,8 @@ Add to your `package.json`:
 ```json
 {
   "scripts": {
-    "db:studio:all": "prisma-sharding-studio",
-    "migrate:shards": "prisma-sharding-migrate",
+    "db:update": "prisma-sharding-update",
+    "db:studio": "prisma-sharding-studio",
     "test:shards": "prisma-sharding-test"
   }
 }
@@ -184,25 +184,146 @@ SHARD_2_URL=postgresql://user:pass@host:5432/db2
 SHARD_3_URL=postgresql://user:pass@host:5432/db3
 SHARD_ROUTING_STRATEGY=modulo  # or consistent-hash
 SHARD_STUDIO_BASE_PORT=51212   # optional, for studio
+SHARD_STUDIO_REUSE_EXISTING=true # optional, defaults to true
+SHARD_STUDIO_STRICT_PORT_CHECK=false # optional, defaults to false
+SHARD_STUDIO_START_TIMEOUT_MS=15000 # optional, defaults to 15000
+SHARD_STUDIO_VERBOSE=false # optional, defaults to false
+SHARD_CLI_VERBOSE=false # optional, verbose update/migrate output
+PRISMA_SHARDING_VERBOSE=false # optional, library lifecycle logs
 ```
 
 ### Commands
 
+#### `prisma-sharding-update` (Recommended)
+
+The "All-in-One" command. It generates Prisma Client types and migrates all shards.
+**Use this whenever you change `schema.prisma`.**
+
+1. Runs `prisma generate` (Updates TypeScript types)
+2. Runs `prisma db push` on all shards (Updates Databases)
+
+```bash
+yarn db:update
+
+```
+
+Default output stays compact:
+
+```text
+🔄 Prisma Sharding Update
+
+✅ client  Generated
+✅ shard_1  Synced
+✅ shard_2  Synced
+✅ shard_3  Synced
+```
+
+Interactive terminals show a single inline loader while Prisma Client generation and each shard
+sync are running. The loader is replaced by the completed row and is disabled for piped or CI logs.
+
+Set `SHARD_CLI_VERBOSE=true` or `SHARD_UPDATE_VERBOSE=true` to include Prisma command
+output, masked database URLs, and detailed diagnostics.
+
+**With Flags:**
+You can pass flags like `--force-reset` if you need to wipe data due to schema conflicts.
+
+```bash
+yarn db:update --force-reset
+
+```
+
 #### `prisma-sharding-migrate`
 
-Push schema to all shards using `prisma db push`.
+Only pushes schema to all shards (skips type generation). Useful for production deployment pipelines.
 
 ```bash
 yarn migrate:shards
+
 ```
 
+This command uses the same compact shard rows as `db:update`. Set
+`SHARD_CLI_VERBOSE=true` or `SHARD_MIGRATE_VERBOSE=true` for Prisma command output.
+
 #### `prisma-sharding-studio`
 
 Start Prisma Studio for all shards on sequential ports.
 
 ```bash
-yarn db:studio:all
-# Opens shard_1 on :51212, shard_2 on :51213, etc.
+yarn db:studio
+```
+
+By default, ports are assigned from `SHARD_STUDIO_BASE_PORT`:
+
+```text
+shard_1 -> http://localhost:51212
+shard_2 -> http://localhost:51213
+shard_3 -> http://localhost:51214
+```
+
+Set `SHARD_STUDIO_BASE_PORT` to move the whole range:
+
+```bash
+SHARD_STUDIO_BASE_PORT=52000 yarn db:studio
+# shard_1 -> :52000, shard_2 -> :52001, etc.
+```
+
+Studio startup is safe to run from multiple local APIs. Before starting a shard Studio,
+the CLI checks whether the target port is already active. If it finds an existing Prisma
+Studio on that port, it reuses it instead of spawning another process:
+
+```text
+🗄️ Prisma Sharding Studio
+
+♻️ shard_1  http://localhost:51212
+♻️ shard_2  http://localhost:51213
+♻️ shard_3  http://localhost:51214
+```
+
+If a port is occupied by another process that does not look like Prisma Studio, the shard
+is marked with a warning and the CLI continues with the remaining shards. It will not kill,
+restart, or claim ownership of processes it did not start.
+
+Default output is intentionally compact:
+
+```text
+🗄️ Prisma Sharding Studio
+
+✅ shard_1  http://localhost:51212
+✅ shard_2  http://localhost:51213
+✅ shard_3  http://localhost:51214
+```
+
+Run with `SHARD_STUDIO_VERBOSE=true` to print port checks, masked database URLs, Prisma
+Studio child-process output, startup timings, and detailed failure diagnostics.
+
+Useful Studio environment variables:
+
+- `SHARD_STUDIO_BASE_PORT`: first port in the shard Studio range. Defaults to `51212`.
+- `SHARD_STUDIO_REUSE_EXISTING`: reuse already-running Prisma Studio ports. Defaults to `true`.
+- `SHARD_STUDIO_STRICT_PORT_CHECK`: when `true`, any failed shard makes the command exit
+  non-zero after stopping Studio processes started by that run. Defaults to `false`.
+- `SHARD_STUDIO_START_TIMEOUT_MS`: maximum time to wait for a newly spawned Studio to become
+  reachable. Defaults to `15000`.
+- `SHARD_STUDIO_STABILITY_MS`: short window a newly-ready Studio process must survive before
+  it is reported as started. Defaults to `500`.
+- `SHARD_STUDIO_SHUTDOWN_TIMEOUT_MS`: time to wait for owned Studio processes to close during
+  shutdown before sending a force-stop signal. Defaults to `5000`.
+- `SHARD_STUDIO_VERBOSE`: print detailed Studio startup diagnostics. Defaults to `false`.
+- `SHARD_STUDIO_DEBUG`: alias for `SHARD_STUDIO_VERBOSE`.
+
+When multiple APIs use the same shard configuration locally, the first API starts the Studio
+processes and later APIs reuse the existing Studio ports. Reused-only commands stay quietly
+attached, preventing process supervisors from printing a normal child-exit message. Pressing
+Ctrl+C only stops Studio processes started by the current CLI run; reused processes are left running.
+
+If you run Studio beside `nodemon`, prefer an explicit watch scope for the API process. Prisma
+Studio does not need to write to your app source, but broad nodemon defaults can restart on
+generated TypeScript or JSON files produced by other dev tooling:
+
+```bash
+nodemon --watch src --ext ts,json \
+  --ignore 'src/types/*.generated.ts' \
+  --exec tsx --env-file=.env --no-warnings src/server.ts
 ```
 
 #### `prisma-sharding-test`
@@ -314,6 +435,9 @@ try {
 
 ## Custom Logger
 
+The default logger prints warnings and errors only. Set `PRISMA_SHARDING_VERBOSE=true` to include
+initialization, shard connection, and shutdown lifecycle messages.
+
 ```typescript
 const sharding = new PrismaSharding({
   // ...config,

package/dist/cli/migrate.js

@@ -25,93 +25,209 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 // src/cli/migrate.ts
 var import_config = require("dotenv/config");
-var import_child_process = require("child_process");
-var import_path = __toESM(require("path"));
-var getShardConfigs = () => {
-  const shards = [];
-  const shardCount = parseInt(process.env.SHARD_COUNT || "0", 10);
-  for (let i = 1; i <= shardCount; i++) {
-    const url = process.env[`SHARD_${i}_URL`];
-    if (url) {
-      shards.push({ id: `shard_${i}`, url });
-    }
+
+// src/utils/env.ts
+var parseBooleanEnv = (name, defaultValue, env = process.env) => {
+  const value = env[name]?.trim();
+  if (value === void 0 || value === "") {
+    return defaultValue;
   }
-  if (shards.length === 0 && process.env.DATABASE_URL) {
-    shards.push({ id: "shard_1", url: process.env.DATABASE_URL });
+  return ["1", "true", "yes", "on"].includes(value.toLowerCase());
+};
+var isVerboseEnv = (names, env = process.env) => names.some((name) => parseBooleanEnv(name, false, env));
+
+// src/cli/utils/output.ts
+var import_readline = __toESM(require("readline"));
+var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+var printCliHeader = (icon, title) => {
+  console.log(`${icon} ${title}
+`);
+};
+var printCliRow = (icon, label, message) => {
+  console.log(`${icon} ${label}  ${message}`);
+};
+var printVerboseHint = () => {
+  console.log("\nRun with SHARD_CLI_VERBOSE=true for details.");
+};
+var createCliLoader = (label, message, enabled = true) => {
+  const animated = enabled && Boolean(process.stdout.isTTY);
+  let frameIndex = 0;
+  let timer;
+  let finished = false;
+  const clear = () => {
+    if (animated) {
+      import_readline.default.clearLine(process.stdout, 0);
+      import_readline.default.cursorTo(process.stdout, 0);
+    }
+  };
+  const render = () => {
+    clear();
+    process.stdout.write(`${SPINNER_FRAMES[frameIndex]} ${label}  ${message}`);
+    frameIndex = (frameIndex + 1) % SPINNER_FRAMES.length;
+  };
+  if (animated) {
+    render();
+    timer = setInterval(render, 80);
   }
-  return shards;
+  const finish = (icon, finalMessage) => {
+    if (finished) {
+      return;
+    }
+    finished = true;
+    if (timer) {
+      clearInterval(timer);
+    }
+    clear();
+    printCliRow(icon, label, finalMessage);
+  };
+  return {
+    succeed: (finalMessage) => finish("\u2705", finalMessage),
+    fail: (finalMessage) => finish("\u274C", finalMessage)
+  };
 };
-var runPrismaCommand = (shardUrl, command) => {
+
+// src/cli/utils/command.ts
+var import_child_process = require("child_process");
+var import_path = __toESM(require("path"));
+var getNpxCommand = () => process.platform === "win32" ? "npx.cmd" : "npx";
+var runCommand = (command, args, options = {}) => {
   return new Promise((resolve) => {
-    const prisma = (0, import_child_process.spawn)("npx", ["prisma", ...command, "--url", shardUrl], {
-      env: process.env,
-      cwd: import_path.default.resolve(process.cwd()),
-      shell: true
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const child = (0, import_child_process.spawn)(command, args, {
+      env: options.env || process.env,
+      cwd: import_path.default.resolve(options.cwd || process.cwd()),
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"]
     });
-    let output = "";
-    let errorOutput = "";
-    prisma.stdout.on("data", (data) => {
-      output += data.toString();
-    });
-    prisma.stderr.on("data", (data) => {
-      errorOutput += data.toString();
+    const settle = (result) => {
+      if (!settled) {
+        settled = true;
+        resolve(result);
+      }
+    };
+    child.stdout?.on("data", (data) => {
+      const output = data.toString();
+      stdout += output;
+      if (options.verbose) {
+        process.stdout.write(output);
+      }
     });
-    prisma.on("close", (code) => {
-      if (code === 0) {
-        resolve({ output });
-      } else {
-        resolve({ output, error: errorOutput || `Exit code: ${code}` });
+    child.stderr?.on("data", (data) => {
+      const output = data.toString();
+      stderr += output;
+      if (options.verbose) {
+        process.stderr.write(output);
       }
     });
-    prisma.on("error", (err) => {
-      resolve({ output, error: err.message });
+    child.once("error", (error) => {
+      settle({
+        success: false,
+        stdout,
+        stderr,
+        error: error.message
+      });
+    });
+    child.once("close", (exitCode) => {
+      settle({
+        success: exitCode === 0,
+        stdout,
+        stderr,
+        exitCode,
+        error: exitCode === 0 ? void 0 : stderr.trim() || stdout.trim() || `Command exited with code ${exitCode}`
+      });
     });
   });
 };
-var migrateAllShards = async () => {
-  const shards = getShardConfigs();
-  console.log("\u{1F504} prisma-sharding: Starting migrations...\n");
-  console.log(`\u{1F4CA} Total shards to migrate: ${shards.length}
-`);
-  if (shards.length === 0) {
-    console.error(
-      "\u274C No shards configured. Set SHARD_COUNT and SHARD_N_URL environment variables."
-    );
-    process.exit(1);
+var runPrismaCommand = (args, options = {}) => runCommand(getNpxCommand(), ["prisma", ...args], options);
+
+// src/cli/utils/shards.ts
+var NO_SHARDS_CONFIGURED_MESSAGE = "No shards configured. Set SHARD_COUNT and SHARD_N_URL environment variables.";
+var getShardConfigResult = (env = process.env) => {
+  const shards = [];
+  const missingShardIds = [];
+  const shardCount = parseInt(env.SHARD_COUNT || "0", 10);
+  for (let i = 1; i <= shardCount; i++) {
+    const url = env[`SHARD_${i}_URL`];
+    if (url) {
+      shards.push({ id: `shard_${i}`, index: i - 1, url });
+    } else {
+      missingShardIds.push(`shard_${i}`);
+    }
   }
+  if (shards.length === 0 && env.DATABASE_URL) {
+    shards.push({ id: "shard_1", index: 0, url: env.DATABASE_URL });
+  }
+  return { shards, missingShardIds };
+};
+var getShardConfigs = (env = process.env) => {
+  return getShardConfigResult(env).shards;
+};
+var maskShardUrl = (url) => {
+  try {
+    const parsed = new URL(url);
+    if (parsed.password) {
+      parsed.password = "***";
+    }
+    return parsed.toString();
+  } catch {
+    return url.replace(/:[^:@]+@/, ":***@");
+  }
+};
+
+// src/cli/utils/prisma.ts
+var syncShardSchemas = async (shards, extraArgs, verbose) => {
   const results = [];
   for (const shard of shards) {
-    console.log(`
-\u{1F4E6} Migrating ${shard.id}...`);
-    console.log(`   URL: ${shard.url.replace(/:[^:@]+@/, ":***@")}`);
-    const { output, error } = await runPrismaCommand(shard.url, ["db", "push"]);
-    if (error && !output.includes("Your database is now in sync")) {
-      console.error(`   \u274C Failed: ${error.split("\n")[0]}`);
-      results.push({ shardId: shard.id, success: false, output, error });
+    const loader = createCliLoader(shard.id, "Syncing", !verbose);
+    if (verbose) {
+      console.log(`
+Syncing ${shard.id}...`);
+      console.log(`Database: ${maskShardUrl(shard.url)}
+`);
+    }
+    const result = await runPrismaCommand(
+      ["db", "push", "--accept-data-loss", ...extraArgs],
+      {
+        env: { ...process.env, DATABASE_URL: shard.url },
+        verbose
+      }
+    );
+    if (verbose && result.error && !result.stderr.trim() && !result.stdout.trim()) {
+      console.error(result.error);
+    }
+    results.push({ shardId: shard.id, success: result.success });
+    if (result.success) {
+      loader.succeed("Synced");
     } else {
-      console.log(`   \u2705 Success`);
-      results.push({ shardId: shard.id, success: true, output });
+      loader.fail("Failed");
     }
   }
-  console.log("\n" + "=".repeat(50));
-  console.log("\u{1F4CB} Migration Summary\n");
-  const successful = results.filter((r) => r.success).length;
-  const failed = results.filter((r) => !r.success).length;
-  results.forEach((result) => {
-    const status = result.success ? "\u2705" : "\u274C";
-    console.log(
-      `   ${status} ${result.shardId}${result.error ? ` - ${result.error.split("\n")[0]}` : ""}`
-    );
-  });
-  console.log(`
-   Total: ${results.length} | Success: ${successful} | Failed: ${failed}`);
+  return results;
+};
+
+// src/cli/migrate.ts
+var migrateAllShards = async () => {
+  const verbose = isVerboseEnv(["SHARD_MIGRATE_VERBOSE", "SHARD_CLI_VERBOSE"]);
+  const shards = getShardConfigs();
+  const extraArgs = process.argv.slice(2);
+  printCliHeader("\u{1F504}", "Prisma Sharding Migrate");
+  if (shards.length === 0) {
+    printCliRow("\u274C", "config", NO_SHARDS_CONFIGURED_MESSAGE);
+    process.exit(1);
+  }
+  const results = await syncShardSchemas(shards, extraArgs, verbose);
+  const successful = results.filter((result) => result.success).length;
+  const failed = results.length - successful;
   if (failed > 0) {
-    console.log("\n\u26A0\uFE0F  Some migrations failed. Please review the errors above.");
+    if (!verbose) {
+      printVerboseHint();
+    }
     process.exit(1);
   }
-  console.log("\n\u2705 All shard migrations completed successfully!");
 };
 migrateAllShards().catch((error) => {
-  console.error("Migration script failed:", error);
+  console.error(error instanceof Error ? error.message : String(error));
   process.exit(1);
 });