Migration আর seed — schema বদলের নিরাপদ পথ

১ · Schema বদল কেন সংস্করণ ধরে রাখতে হয়

বাজারঘরের পণ্যের টেবিলে একটি নতুন কলাম দরকার। আপনি pgAdmin খুলে হাতে যোগ করলেন, অ্যাপ চলল। এক সপ্তাহ পরে সহকর্মী রহিমার কম্পিউটারে অ্যাপ ভেঙে গেল, কারণ তাঁর ডেটাবেসে কলামটি নেই। Production-এও কেউ যোগ করতে ভুলে গেছেন। এখন কেউ জানে না কোন ডেটাবেসের গঠন কেমন।

ডেটাবেসের তত্ত্ব, মানে migration কী আর expand–contract কেন, এসেছে DBMS কোর্সের ORM আর migration পর্বে। এখানে সেটি আর পড়াব না, বরং পর্ব ৩৯-এর মতো একটি ছোট Prisma প্রজেক্টে, সত্যিকারের PostgreSQL-এ চালিয়ে দেখব। বদলগুলো চোখে পড়ার জন্য Product মডেল এখানে সেখানকার চেয়ে সরল। সেই সরলতার জন্য এই lab-এ price পুরো টাকায় (যেমন 420), যদিও বাজারঘরের আসল চুক্তিতে দাম integer পয়সায়, pricePaisa. কোড আর ডেটার একটি মৌলিক পার্থক্য মনে রাখুন: কোড ভুল হলে আগের সংস্করণ আবার চালানো যায়, কিন্তু ডেটাবেসের ভেতরের ডেটা অবস্থা ধরে রাখে। একটি কলাম মুছে ফেললে আগের কোড চালালে ডেটা ফেরে না।

প্রজেক্টের config-ও আগের দিনের মতো নেই। Prisma 7-এ ডেটাবেসের ঠিকানা schema ফাইলে বসে না, বসে prisma.config.ts-এ, আর seed-এর কমান্ডও এখানেই। পুরোনো কায়দায় url = env("DATABASE_URL") লিখলে 7.10.1 সরাসরি P1012 দেয়। ফাইলটি আমরা হাতে লিখেছি। prisma init দিয়ে শুরু করলে, যেমন পর্ব ৩৯-এ, নাম হয় prisma7.config.ts, কারণ 7.10.0 থেকে Prisma 8-এর পাশাপাশি থাকার জন্য এই নাম এসেছে। এখানে আমরা প্রচলিত পুরোনো নামটি রেখেছি, যা বেশিরভাগ docs আর টিউটোরিয়ালে পাবেন। 7.10.1-এর CLI দুটি নামই খুঁজে নেয়, তবে আগে prisma7.config.* দেখে। তাই একই project-এ দুটি ফাইল রাখবেন না।

import 'dotenv/config';
import { defineConfig, env } from 'prisma/config';

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
    seed: 'tsx prisma/seed.ts',
  },
  datasource: {
    url: env('DATABASE_URL'),
    shadowDatabaseUrl: env('SHADOW_DATABASE_URL'),
  },
});

২ · Prisma-র পাঁচ কমান্ড — কোনটি কোথায় নিরাপদ

Prisma Migrate-এর কমান্ডগুলো নামে কাছাকাছি, কিন্তু কাজে আলাদা। ভুল জায়গায় ভুল কমান্ড চালানোই বেশিরভাগ দুর্ঘটনার শুরু। আগে টেবিলটি মাথায় রাখুন:

দুটি সত্যিকারের ফল দেখুন। প্রথমটি production-ধরনের ডেটাবেসে status, তারপর deploy, তারপর আবার deploy. দ্বিতীয়বারে কিছুই হয় না, তাই পাইপলাইনে এটি বারবার চালানো নিরাপদ।

$ npx prisma migrate status
2 migrations found in prisma/migrations
Following migrations have not yet been applied:
20261101174715_init
20261101174717_add_stock
[exit code 1]

$ npx prisma migrate deploy
Applying migration `20261101174715_init`
Applying migration `20261101174717_add_stock`
All migrations have been successfully applied.

$ npx prisma migrate deploy
No pending migrations to apply.

Exit code ১ কাজের জিনিস: CI-তে migrate status দিয়ে “কিছু বাকি আছে কি না” যাচাই করা যায়। আর db push ফাইল রাখে না বলে শুরুর খসড়ায় দ্রুত, কিন্তু দলে বা production-এ তার কোনো হিসাব থাকে না। সেখানে সে ডেটা হারানোর আগে থামে, যদি না কেউ জোর করে --accept-data-loss দেন:

$ npx prisma db push
⚠️  There might be data loss when applying the changes:
  • You are about to drop the column `discount` on the `Product` table, which still contains 1 non-null values.
Error: Use the --accept-data-loss flag to ignore the data loss warnings like prisma db push --accept-data-loss

৩ · migrate dev-এর ভেতরে — SQL ফাইল আর হিসাবের টেবিল

ছোট Product মডেলে stock কলাম যোগ করলাম। কমান্ড একটিই, কিন্তু ভেতরে কয়েকটি আলাদা কাজ হয়। নিচে সত্যিকারের run-এর ফাইল আর সারি দিয়ে ধাপগুলো দেখুন।

model Product {
  id    Int    @id @default(autoincrement())
  name  String
  price Int
  stock Int    @default(0)
}

একটি খালি সাময়িক ডেটাবেসে পুরোনো ফাইলগুলো ক্রমে চলে:
  20261101174715_init/migration.sql
ফল = “ইতিহাস অনুযায়ী গঠন যেমন হওয়ার কথা”
এর সাথে dev ডেটাবেস মেলানো হয় → drift নেই

-- AlterTable
ALTER TABLE "Product" ADD COLUMN     "stock" INTEGER NOT NULL DEFAULT 0;

migration_name            applied_steps  finished_at
20261101174715_init            1         17:47:15
20261101174717_add_stock       1         17:47:17

হিসাবের টেবিলের আসল চেহারা, প্রথম migration-এর পরে:

migration_name         checksum (প্রথম ১২)  started_at     finished_at    applied_steps_count  rolled_back_at
20261101174715_init    235f0213d39c        …17:47:15.150  …17:47:15.154  1                    null

ভিতরের প্রতিটি ঘরের কাজ আছে। finished_at ফাঁকা মানে চলা শেষ হয়নি বা ব্যর্থ। rolled_back_at ভরা মানে হাতে ফেরানো চিহ্নিত। আর checksum ফাইলের আঙুলের ছাপ, যা দিয়ে ধরা পড়ে কেউ পরে ফাইল বদলেছেন কি না। পুরো ব্যবস্থাটি এত সরল যে ২৫ লাইনে একটি শিক্ষামূলক মডেল বানানো যায়। নিচের Node কোডে ডেটাবেসের জায়গায় একটি সাধারণ object, কিন্তু যুক্তি একই:

const { createHash } = require('node:crypto');

const files = [
  { name: '001_init', sql: 'CREATE TABLE Product (id INT, name TEXT)' },
  { name: '002_add_stock', sql: 'ALTER TABLE Product ADD COLUMN stock INT' },
];
const db = { ran: [], migrations: [] }; // ডেটাবেসের নকল
const hash = (s) => createHash('sha256').update(s).digest('hex').slice(0, 8);

function migrate() {
  let applied = 0;
  for (const f of files) {
    const row = db.migrations.find((m) => m.name === f.name);
    if (row) {
      if (row.checksum !== hash(f.sql)) throw new Error(f.name + ' changed after apply');
      continue; // আগেই চলেছে
    }
    db.ran.push(f.sql);
    db.migrations.push({ name: f.name, checksum: hash(f.sql) });
    applied++;
  }
  console.log('applied', applied, '| total', db.migrations.length);
}

migrate();
migrate();
files.push({ name: '003_add_brand', sql: 'ALTER TABLE Product ADD COLUMN brand TEXT' });
migrate();
files[0].sql += ' -- পরে বদলানো';
try { migrate(); } catch (e) { console.log('ERROR:', e.message); }
console.log(db.ran.length, 'statements ran');

applied 2 | total 2
applied 0 | total 2
applied 1 | total 3
ERROR: 001_init changed after apply
3 statements ran

৪ · দলে migration — commit, conflict আর drift

Migration ফোল্ডার আর migration_lock.toml Git-এ commit করতে হয়। এগুলোই দলের সবার সাধারণ ইতিহাস। .env commit হবে না। দুজন একসাথে কাজ করলে কী হয়, একটি আলাদা scratch repo-তে সত্যিই করে দেখলাম। রহিম brand, করিম weight যোগ করলেন, প্রথমে করিমেরটি production-এ গেল।

$ git merge rahim/brand
Auto-merging prisma/schema.prisma
CONFLICT (content): Merge conflict in prisma/schema.prisma
Automatic merge failed; fix conflicts and then commit the result.

model Product {
  …
  stock    Int    @default(0)
<<<<<<< HEAD
  weight   Int?
=======
  brand    String?
>>>>>>> rahim/brand
}

Conflict হলো schema.prisma-য়, migration ফাইলে নয়, কারণ ফোল্ডার দুটির নাম আলাদা। দুটি লাইনই রেখে merge শেষ করলাম। এবার মজার দৃশ্য: রহিমের ফাইলের সময়চিহ্ন করিমেরটির আগের, অথচ production-এ করিমেরটি আগেই চলে গেছে। এরপরও deploy বাকি ফাইলটি চালাল:

migration_name             started_at
20261101175005_init        17:50:12.628
20261101175010_add_weight  17:50:12.635
20261101175007_add_brand   17:50:23.335   ← নামে আগে, চলেছে পরে

এখানে দুই বদল আলাদা কলামে, তাই ক্রম উল্টে গেলেও ক্ষতি হয়নি, পরে migrate diff “No difference detected” বলল। কিন্তু দুজন একই কলাম যোগ করলে পরেরটি column already exists-এ থামবে, আর একটির ওপর অন্যটি নির্ভর করলে ক্রম উল্টে SQL ভাঙতে পারে। Merge-এর পরে তাই খালি ডেটাবেসে পুরো ইতিহাস একবার চালিয়ে দেখা ভালো অভ্যাস। Git-এর দিকটি আছে Git branching পর্বে।

Drift — খাতার বাইরে বদল

গভীর রাতে কেউ production-এ হাতে একটি কলাম যোগ করলেন। হিসাবের সাথে আসল গঠন আর মিলছে না, এর নাম schema drift. ডেটাবেসে হাতে ALTER TABLE "Product" ADD COLUMN "discount" INTEGER চালিয়ে তিনটি কমান্ড দিলাম:

$ npx prisma migrate status
2 migrations found in prisma/migrations
Database schema is up to date!                 ← drift ধরল না

$ npx prisma migrate dev --name noop
Drift detected: Your database schema is not in sync with your migration history.
[*] Changed the `Product` table
  [+] Added column `discount`
We need to reset the "public" schema at "127.0.0.1:38741"
You may use prisma migrate reset to drop the development database.
All data will be lost.

$ npx prisma migrate diff --from-migrations prisma/migrations \
    --to-config-datasource --exit-code
[*] Changed the `Product` table
  [+] Added column `discount`
[exit code 2]

এখান থেকে তিনটি শিক্ষা। status শুধু ফাইল আর হিসাবের টেবিল মেলায়, আসল গঠন দেখে না। migrate dev ধরে, কিন্তু তার সমাধান reset, যা dev-এ চলে, production-এ কখনো নয়। আর production-এ drift খুঁজতে migrate diff --exit-code সবচেয়ে সৎ: পার্থক্য থাকলে exit code ২. এটি পড়ে শুধু, লেখে না, তবে shadow database-এর ঠিকানা লাগে।

৫ · হাতে সম্পাদনা, ধ্বংসাত্মক বদল আর ব্যর্থ migration

Prisma SQL বানায় পার্থক্য দেখে, আপনার মনের ইচ্ছা দেখে নয়। name কলামের নাম title করলাম। Prisma এটিকে নাম বদল ভাবল না, ভাবল একটি মুছে আরেকটি যোগ:

-- AlterTable
ALTER TABLE "Product" DROP COLUMN "name",
ADD COLUMN     "title" TEXT NOT NULL;

$ npx prisma migrate dev --name rename_title
⚠️ We found changes that cannot be executed:
  • Step 0 Added the required column `title` to the `Product` table without a default value.
    There are 3 rows in this table, it is not possible to execute this step.
You can use prisma migrate dev --create-only to create the migration file, and manually modify it
to address the underlying issue(s).

এই SQL চলতে পারলে ৩টি পণ্যের নাম চিরতরে যেত। এটিই destructive change. কলাম মুছলে Prisma আরেকটি সতর্কতা দেয়:

⚠️  Warnings for the current datasource:
  • You are about to drop the column `discount` on the `Product` table, which still contains 1 non-null values.

পথ হলো --create-only: ফাইল বানায়, চালায় না। আপনি খুলে হাতে ঠিক করেন, তারপর চালান। আমাদের terminal-ছাড়া lab-এ শুধু-সতর্কতার ক্ষেত্রে এটিও “non-interactive” বলে থেমেছে, তখন একই ফাইল এসেছে migrate diff --script থেকে। মূল নিয়মটি স্পষ্ট: যে ফাইল এখনো কোথাও চলেনি, সেটি সম্পাদনা করা যায়; যেটি চলেছে, সেটি আর ছোঁবেন না। চলে যাওয়া ফাইলে শুধু একটি comment যোগ করলে কী হয়, দেখুন:

$ npx prisma migrate dev --name check2
The migration `20261101180000_add_discount` was modified after it was applied.
We need to reset the "public" schema at "127.0.0.1:38741"

$ npx prisma migrate deploy        # production-ধরনের ডেটাবেসে
No pending migrations to apply.    ← কিছুই বলল না

আগে যে কড়া মডেলের কথা বলেছিলাম, এই তার পার্থক্য। v7 docs বলছে deploy এমন ফাইলে একটি WARNING দেয়, কিন্তু 7.10.1-এ আলাদা একটি পরীক্ষাতেও কোনো সতর্কতা ছাপা হয়নি, বাকি migration থাকলেও না। তাই এর ওপর ভরসা করবেন না। ধরার ভরসা migrate dev, code review আর CI-এর যাচাই।

ব্যর্থ migration আর migrate resolve

৩টি সারি আছে এমন টেবিলে "sku" TEXT NOT NULL চালাতে গেলে ফল এমন:

$ npx prisma migrate deploy
Applying migration `20261101181000_add_sku`
Error: P3018
A migration failed to apply. New migrations cannot be applied before the error is recovered from.
Migration name: 20261101181000_add_sku
Database error code: 23502
ERROR: column "sku" of relation "Product" contains null values

$ npx prisma migrate deploy
Error: P3009
migrate found failed migrations in the target database, new migrations will not be applied.

$ npx prisma migrate resolve --rolled-back 20261101181000_add_sku
Migration 20261101181000_add_sku marked as rolled back.

ব্যর্থ ফাইল পরের সব migration আটকে দেয়, যতক্ষণ না আপনি জানান কী হলো। --rolled-back মানে “আমি নিশ্চিত, এর ফল ডেটাবেসে নেই”। তারপর ফাইল ঠিক করলাম তিন ধাপে, আবার deploy চলল। হিসাবের টেবিলে একই নামের দুটি সারি থেকে গেল, প্রথমটি ফেরানো, দ্বিতীয়টি সফল। এটি ইতিহাসই, ভুল নয়।

ALTER TABLE "Product" ADD COLUMN "sku" TEXT;
UPDATE "Product" SET "sku" = 'BG-' || "id" WHERE "sku" IS NULL;
ALTER TABLE "Product" ALTER COLUMN "sku" SET NOT NULL;

৬ · Expand and contract — পুরোনো আর নতুন অ্যাপ একসাথে

Rolling deployment-এ (deployment কৌশল পর্ব) সার্ভার একটি একটি করে বদলায়। কয়েক মিনিট পুরোনো V1 আর নতুন V2 একই ডেটাবেসে চলে। তাই প্রতিটি schema বদলকে দুই সংস্করণের সাথেই চলতে হবে। এক ধাপে নাম বদলালে কী হয়, সত্যিকারের Prisma Client দিয়ে দেখুন:

ALTER TABLE "Product" RENAME COLUMN "name" TO "title";

V1 findMany    ERROR P2022 The column `Product.name` does not exist in the current database.
V1 create      ERROR P2022 The column `name of relation Product` does not exist in the current database.

ডেটা একটুও হারায়নি, তবু পুরোনো অ্যাপের পণ্যের পাতা বন্ধ। Zero-downtime চাইলে expand and contract লাগবে।

নিচের stepper আমাদের real run. দুটি আলাদা generated client, V1 আর V2, একই PostgreSQL টেবিলে একসাথে পড়ছে আর লিখছে। V2-এর schema-য় name String? @ignore আছে, যাতে V2 পুরোনো কলাম SELECT-ই না করে। এই লাইনটি না থাকলে contract-এর পরে V2-ও ভেঙে যেত।

চারটি migration ফাইলই হাতে লেখা, চালানো হয়েছে migrate deploy দিয়ে। M1-এর trigger-টি PostgreSQL-এর:

BEGIN;
ALTER TABLE "Product" ADD COLUMN "title" TEXT;
ALTER TABLE "Product" ALTER COLUMN "name" DROP NOT NULL;

CREATE FUNCTION product_sync_title() RETURNS trigger AS $$
BEGIN
  IF TG_OP = 'INSERT' THEN
    NEW."title" := COALESCE(NEW."title", NEW."name");
    NEW."name"  := COALESCE(NEW."name", NEW."title");
  ELSIF NEW."name" IS DISTINCT FROM OLD."name" THEN
    NEW."title" := NEW."name";
  ELSIF NEW."title" IS DISTINCT FROM OLD."title" THEN
    NEW."name" := NEW."title";
  END IF;
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER product_sync_title_trg
  BEFORE INSERT OR UPDATE ON "Product"
  FOR EACH ROW EXECUTE FUNCTION product_sync_title();
COMMIT;

শেষে যাচাই: V3 schema-র সাথে migrate diff --exit-code বলল “No difference detected.”. Trigger ছাড়া আরেকটি পথ হলো V2 কোড নিজেই দুই কলামে লেখা (dual write), তবে তখন V1-এর লেখা সারিতে title ফাঁকা থাকবে, তাই V1 বন্ধের পরে আরেকবার backfill লাগে। এবার পুরো ধারণাটি পাতায় নিজে চালান। এখানে ইঞ্জিন SQLite: trigger-এর ভাষা ভিন্ন, আর ALTER COLUMN … SET NOT NULL SQLite-এ নেই, তাই ওই ধাপটি বাদ।

CREATE TABLE Product (id INTEGER PRIMARY KEY, name TEXT, price INTEGER);
INSERT INTO Product (name, price) VALUES ('চাল', 420), ('ডাল', 135);

-- expand: নতুন কলাম, পুরোনো অ্যাপ টের পায় না
ALTER TABLE Product ADD COLUMN title TEXT;
CREATE TRIGGER sync_ins AFTER INSERT ON Product
WHEN NEW.title IS NULL OR NEW.name IS NULL
BEGIN
  UPDATE Product SET title = COALESCE(NEW.title, NEW.name),
                     name  = COALESCE(NEW.name, NEW.title)
  WHERE id = NEW.id;
END;

-- দুই সংস্করণ একসাথে: V1 লেখে name, V2 লেখে title
INSERT INTO Product (name, price)  VALUES ('তেল', 190);
INSERT INTO Product (title, price) VALUES ('চিনি', 150);

-- backfill: পুরোনো সারি
UPDATE Product SET title = name WHERE title IS NULL;
SELECT id, name, title FROM Product;

-- contract: এখন কেউ name পড়ে না
DROP TRIGGER sync_ins;
ALTER TABLE Product DROP COLUMN name;
SELECT id, title, price FROM Product;

একটি কলাম ভাগ করা — ঠিকানা থেকে area আর city

নাম বদলে তথ্য একই থাকে। ভাগ করায় পুরোনো ডেটাকে বুঝতে হয়, আর বাস্তবের ডেটা অগোছালো। fullAddress থেকে area আর city করার সময় শেষ কমা ধরে backfill চালালাম, একই expand ধাপে। PostgreSQL-এর real ফল:

backfilled 3
id  fullAddress                     area                      city
1   মিরপুর ১০, ঢাকা                 মিরপুর ১০                 ঢাকা
2   আগ্রাবাদ, চট্টগ্রাম                আগ্রাবাদ                  চট্টগ্রাম
3   জিন্দাবাজার সিলেট               null                      null
4   বাড়ি ৫, রোড ২, ধানমন্ডি, ঢাকা   বাড়ি ৫, রোড ২, ধানমন্ডি   ঢাকা

৪টির মধ্যে ১টি বোঝা গেল না, কারণ কমা নেই। অনুমান করে ভাগ না করে এমন সারি আলাদা তালিকায় তুলে মানুষ দিয়ে বা গ্রাহকের কাছ থেকে ঠিক করানোই সৎ পথ। তাই NOT NULL আর contract আসবে এই সংখ্যা ০ হওয়ার পরে। Trigger দুই দিকেই কাজ করল: পুরোনো অ্যাপের নিউ মার্কেট, খুলনা ভেঙে area, city হলো, আর নতুন অ্যাপের কাজলা, রাজশাহী জুড়ে কাজলা, রাজশাহী হলো।

৭ · NOT NULL, backfill, lock আর CONCURRENTLY

Expand and contract ঠিক থাকলেও একটি বদল সাইট থামিয়ে দিতে পারে, যদি সেটি বড় বা ভুল সময়ে হয়। কারণ lock. PostgreSQL-এ বেশিরভাগ ALTER TABLE নেয় ACCESS EXCLUSIVE lock, যা সাধারণ SELECT-ও আটকায়। Lock-এর তত্ত্ব আছে concurrency control পর্বে। ভয়ের জায়গাটি হলো সারি: ALTER নিজে এক মিলিসেকেন্ডের কাজ হলেও সে অপেক্ষায় দাঁড়ালে পেছনের সবাই তার পেছনে দাঁড়ায়। ১০ লাখ সারির টেবিলে তিনটি সংযোগ দিয়ে এটি সত্যিই ঘটালাম।

ওষুধ lock_timeout: “এত সময়ে lock না পেলে হাল ছাড়ো”। আমাদের run-এ SET lock_timeout = '2s' দিয়ে ২০১৬ ms পরে ALTER ব্যর্থ হলো: 55P03 canceling statement due to lock timeout. ব্যর্থ হওয়া এখানে ভালো ফল। সাইট চলতে থাকে, পরে আবার চেষ্টা করা যায়।

কোন বদল কতটা ভারী — এক run-এর মাপ

১০ লাখ সারির (৮৭ MB) টেবিলে কাজ চলার সময় পাশে একটি লেখক প্রতি ৫ ms-এ একটি ছোট UPDATE পাঠাচ্ছিল। শেষ ঘরটি সেই UPDATE-এর সবচেয়ে বেশি অপেক্ষা। এটি একটি ল্যাপটপে একবারের মাপ, সাধারণ নিয়ম নয়। তুলনাটুকুই দেখার।

প্রথম দুই সারি দেখায় কেন PostgreSQL ১১-এর পরে স্থির DEFAULT-সহ কলাম যোগ এত দ্রুত: মানটি টেবিলের metadata-য় থাকে, সারিগুলো নতুন করে লেখা হয় না। আর NOT NULL-এর সারি দেখায় নিরাপদ পথটি: VALIDATE হালকা lock নেয়, আর বৈধ CHECK থাকলে SET NOT NULL scan করে না। ব্যাচে মোট সময় প্রায় দ্বিগুণ, কিন্তু লেখার অপেক্ষা ৮ সেকেন্ড থেকে ১ সেকেন্ডের নিচে। এই দামটিই আমরা দিই।

NOT NULL কলাম, ব্যাচে backfill

নতুন slug কলামের মান প্রতিটি সারির জন্য আলাদা, তাই সহজ DEFAULT চলে না। ধাপ: nullable যোগ, অ্যাপ নতুন সারিতে লেখা শুরু, পুরোনো সারি ব্যাচে ভরা, তারপর NOT NULL. বড় টেবিলের backfill migration ফাইলে রাখবেন না, কারণ deploy ততক্ষণ আটকে থাকবে। এটি আলাদা script. নিচেরটি Prisma-র $queryRaw দিয়ে সত্যিই চলেছে, parameter সহ, তাই SQL injection-এর ভয় নেই:

const BATCH = 10_000;
let lastId = 0n;
let total = 0;

for (;;) {
  const rows = await prisma.$queryRaw<{ id: bigint }[]>`
    WITH batch AS (
      SELECT id FROM products
      WHERE id > ${lastId} AND slug2 IS NULL
      ORDER BY id LIMIT ${BATCH}
    )
    UPDATE products p SET slug2 = 'p-' || p.id
    FROM batch WHERE p.id = batch.id
    RETURNING p.id`;
  if (rows.length === 0) break;
  lastId = rows.reduce((m, r) => (r.id > m ? r.id : m), lastId);
  total += rows.length;
  await sleep(20); // অন্য কাজকে জায়গা দেওয়া
}

batch 25: total 250000, lastId 250000
batch 50: total 500000, lastId 500000
batch 75: total 750000, lastId 750000
batch 100: total 1000000, lastId 1000000
done: 1000000 rows in 100 batches

প্রতিটি ব্যাচ নিজের transaction, তাই lock দ্রুত ছাড়া পায়। slug2 IS NULL শর্ত থাকায় script মাঝপথে থামলে আবার চালানো নিরাপদ। ছোট একটি টেবিলে ব্যাচের হাঁটা দেখুন, expand and contract-এর real run থেকে নেওয়া:

একই কৌশল পাতায় চালান। SQLite-এ লুপ নেই, তাই প্রতিটি ব্যাচ আলাদা UPDATE:

-- ১০টি সারি, ব্যাচের আকার ৪
UPDATE Product SET slug = 'p-' || id
WHERE id IN (SELECT id FROM Product WHERE slug IS NULL ORDER BY id LIMIT 4);
SELECT count(*) AS still_null FROM Product WHERE slug IS NULL;

UPDATE Product SET slug = 'p-' || id
WHERE id IN (SELECT id FROM Product WHERE slug IS NULL ORDER BY id LIMIT 4);
SELECT count(*) AS still_null FROM Product WHERE slug IS NULL;

UPDATE Product SET slug = 'p-' || id
WHERE id IN (SELECT id FROM Product WHERE slug IS NULL ORDER BY id LIMIT 4);
SELECT count(*) AS still_null FROM Product WHERE slug IS NULL;

SELECT id, slug FROM Product WHERE id IN (1, 10);

CREATE INDEX CONCURRENTLY — সত্যিকারের আচরণ

সাধারণ CREATE INDEX লেখা আটকায় (পড়া নয়)। উপরের টেবিলে তাই ৭৫৭ ms অপেক্ষা। CONCURRENTLY লেখা আটকায় না, একই সময়ে ৪৪টি UPDATE চলেছে, আগেরটিতে মাত্র ২টি। সাধারণত এটি বেশি সময় নেয়, আমাদের এই একটি run-এ তফাত ছিল না। এর দুটি শর্ত real run-এ দেখুন:

BEGIN; CREATE INDEX CONCURRENTLY idx_c ON products (name);
25001 CREATE INDEX CONCURRENTLY cannot run inside a transaction block

CREATE UNIQUE INDEX CONCURRENTLY idx_u ON products (name);
23505 could not create unique index "idx_u"  Key (name)=(ডুপ্লিকেট) is duplicated.

relname        indisvalid
products_pkey  true
idx_b          true
idx_u          false      ← ব্যর্থ, কিন্তু পড়ে আছে

ব্যর্থ হলে সে একটি invalid index রেখে যায়। Query এটি ব্যবহার করে না, অথচ লেখার খরচ থাকতে পারে। PostgreSQL docs-এর পরামর্শ: DROP INDEX করে আবার চেষ্টা। Prisma-য় একে নিজের ফাইলে রাখুন, একটিমাত্র statement, কোনো BEGIN নয়। schema-তে @@index লিখে index-এর নাম মিলিয়ে দিন, নইলে drift হবে। আমাদের run-এ একা ফাইলে থাকা CREATE INDEX CONCURRENTLY "Product_cat_idx" ON "Product"("cat"); deploy-এ চলেছে।

৮ · Deploy-এর ক্রম, rollback আর backup

Migration চলবে একবার, অ্যাপের আগে, একটি আলাদা ধাপে। “আগে”, কারণ expand করা schema-য় পুরোনো অ্যাপ চলে, কিন্তু পুরোনো schema-য় নতুন অ্যাপ চলে না। “একবার”, কারণ ১০টি সার্ভার চালু হওয়ার সময় ১০ বার চালানো অর্থহীন আর ঝুঁকির।

দুটি প্রক্রিয়া ভুলে একসাথে deploy চালালে কী হয়? Prisma একটি advisory lock ধরে। ৩ সেকেন্ডের migration-এ দ্বিতীয়টি অপেক্ষা করে “No pending migrations to apply.” বলল, আর একটি migration একবারই চলল। ১৪ সেকেন্ডের migration-এ দ্বিতীয়টি হাল ছাড়ল। v7 docs অনুযায়ী এই ১০ সেকেন্ডের সীমা বদলানো যায় না, আবার চালাতে হয়:

Error: P1002
The database server was reached but timed out.
Context: Timed out trying to acquire a postgres advisory lock
(SELECT pg_advisory_lock(72707369)). Timeout: 10000ms.

অর্থাৎ lock দুর্ঘটনা থামায়, কিন্তু অ্যাপ চালুর সময় প্রতিটি server থেকে migration চালানোকে ভালো নকশা বানায় না। এটি পাইপলাইনের একটি আলাদা ধাপ। আরও আছে পর্ব ৮১-তে আর pipeline নকশা পর্বে।

Rollback — সামনে সারানো বনাম down migration

7.10.1-এ migrate down বলে কোনো কমান্ড নেই। উল্টো SQL দরকার হলে বানানো যায়, কিন্তু কী পাওয়া যায় দেখুন। discount কলাম মোছার উল্টো script:

$ npx prisma migrate diff --from-schema new.prisma --to-schema old.prisma --script
-- AlterTable
ALTER TABLE "Product" ADD COLUMN     "discount" INTEGER;

কলাম ফিরল, কিন্তু খালি। Down migration গঠন ফেরায়, ডেটা নয়। তা ছাড়া migration-এর পরে নতুন অ্যাপ যে ডেটা লিখেছে, সেটিও সে জানে না। তাই বাস্তবের অভ্যাস roll forward: ভুল দেখলে আরেকটি নতুন migration. Expand and contract এটি সহজ করে দেয়। contract-এর আগ পর্যন্ত অ্যাপের কোড পেছনে নিলেই হয়, schema দুই দিকেই চলে। দ্রুত ব্যবহারের নিয়মটি হলো: কোড ফেরান, schema সামনে সারান, ডেটা ফিরবে শুধু backup থেকে।

Backup — restore না করলে সেটি আশা মাত্র

embedded-postgres-এ pg_dump নেই, তাই PostgreSQL-এর অফিসিয়াল 18.6 Windows বাইনারি থেকে নিলাম। একটি ভুল UPDATE ঘটিয়ে আলাদা ডেটাবেসে ফেরালাম (পাসওয়ার্ড PGPASSWORD-এ, লেখা example-secret):

$ pg_dump -h 127.0.0.1 -p 38741 -U postgres -Fc -f before.dump bazarghar
# ভুল: সব দাম 0
UPDATE "Product" SET price = 0;     → BG-1001 0, BG-1002 0, BG-1003 0

# আলাদা, নতুন খালি ডেটাবেস: bazarghar_verify
$ pg_restore -h 127.0.0.1 -p 38741 -U postgres -d bazarghar_verify before.dump
[exit code 0]
sku      price
BG-1001  420
BG-1002  135
BG-1003  190
_prisma_migrations-এ সফল সারি: 5

দুটি বিষয় খেয়াল করুন। Restore করা হয়েছে আলাদা ডেটাবেসে, চলমানটির ওপর নয়, তাই আগে দেখে নেওয়া যায়। আর হিসাবের টেবিলও সাথে এসেছে, ফলে restore-এর পরে Prisma ঠিকই জানে কোন migration চলেছে। Backup-এর পরে লেখা ডেটা এই ফাইলে নেই, এই ফাঁক কমানোর কৌশল backup আর replication পর্বে।

৯ · Seed — বারবার চালালেও একই ফল

Migration গঠন বদলায়, seed শুরুর ডেটা বসায়। নতুন সহকর্মী ফাঁকা অ্যাপ না দেখে যেন “মিনিকেট চাল”-সহ দোকান দেখেন। Seed-এ দুই ধরনের ডেটা আলাদা রাখুন: reference data, যেমন বিভাগ, যা সব পরিবেশে লাগে; আর নমুনা ডেটা, যা production-এ যাবে না। 7.10.1-এ কমান্ডটি prisma.config.ts-এর migrations.seed-এ থাকে। পুরোনো package.json-এর prisma.seed লিখলে সে শুধু বলে ⚠️ No seed command configured. Docs বলছে, v7-এ seed আর নিজে থেকে migrate dev বা reset-এর পরে চলে না, npx prisma db seed নিজে চালাতে হয়।

const categories = [
  { slug: 'chal-dal', nameBn: 'চাল ও ডাল' },
  { slug: 'tel-moshla', nameBn: 'তেল ও মসলা' },
];
const demoProducts = [
  { sku: 'BG-1001', name: 'মিনিকেট চাল ৫ কেজি', price: 420, stock: 30, cat: 'chal-dal' },
  { sku: 'BG-1002', name: 'মসুর ডাল ১ কেজি', price: 135, stock: 50, cat: 'chal-dal' },
  { sku: 'BG-1003', name: 'সয়াবিন তেল ১ লিটার', price: 190, stock: 0, cat: 'tel-moshla' },
];

async function main() {
  for (const c of categories) {
    await prisma.category.upsert({
      where: { slug: c.slug },
      update: { nameBn: c.nameBn },
      create: c,
    });
  }
  if (process.env.NODE_ENV === 'production') {
    console.log('production: নমুনা ডেটা বাদ');
    return;
  }
  for (const { cat, ...p } of demoProducts) {
    await prisma.product.upsert({
      where: { sku: p.sku },
      update: { name: p.name, price: p.price },
      create: { ...p, category: { connect: { slug: cat } } },
    });
  }
}

$ npx prisma db seed
Running seed command `tsx prisma/seed.ts` ...
{ categories: 2, products: 3 }
The seed command has been executed.

$ npx prisma db seed
{ categories: 2, products: 3 }      ← দ্বিতীয়বারেও ২ আর ৩

# dev-এ হাতে BG-1001: price 999, stock 7 করে আবার seed
sku       price  stock
BG-1001   420    7                  ← price ফিরল, stock রইল

# NODE_ENV=production
production: নমুনা ডেটা বাদ          → Category 2, Product 0

দ্বিতীয় run-এ কিছু বাড়েনি, এটিই idempotent. Upsert-এ where লাগে কোনো unique কলামে, তাই sku আর slug @unique. update-এ যা লিখবেন শুধু সেটিই ফেরে, তাই stock বাদ দিয়ে হাতের বদলটি রক্ষা পেল। Upsert ছাড়া সাধারণ create দ্বিতীয়বারে দেয় P2002 Unique constraint failed on the constraint: `Category_slug_key`. Unique না থাকলে আরও খারাপ: কোনো error ছাড়াই ডুপ্লিকেট। নিচে দুটোই:

CREATE TABLE Category (id INTEGER PRIMARY KEY, slug TEXT UNIQUE NOT NULL, nameBn TEXT NOT NULL);
CREATE TABLE BadCategory (id INTEGER PRIMARY KEY, slug TEXT, nameBn TEXT);

-- প্রথম seed
INSERT INTO Category (slug, nameBn) VALUES ('chal-dal', 'চাল'), ('tel', 'তেল')
ON CONFLICT (slug) DO UPDATE SET nameBn = excluded.nameBn;
INSERT INTO BadCategory (slug, nameBn) VALUES ('chal-dal', 'চাল'), ('tel', 'তেল');

-- দ্বিতীয় seed, একটি নাম ঠিক করা হয়েছে
INSERT INTO Category (slug, nameBn) VALUES ('chal-dal', 'চাল ও ডাল'), ('tel', 'তেল')
ON CONFLICT (slug) DO UPDATE SET nameBn = excluded.nameBn;
INSERT INTO BadCategory (slug, nameBn) VALUES ('chal-dal', 'চাল ও ডাল'), ('tel', 'তেল');

SELECT slug, nameBn FROM Category ORDER BY id;
SELECT count(*) AS good FROM Category;
SELECT count(*) AS bad FROM BadCategory;

Seed আর test fixture আলাদা

Seed মানুষের জন্য, test fixture একটি নির্দিষ্ট test-এর জন্য। দুটি মেশালে একদিন কেউ seed-এর দাম বদলাবেন, আর দশটি test অকারণে ভাঙবে। Test নিজের ডেটা নিজে বানাবে আর গুছিয়ে নেবে, পর্ব ৭৫ আর ৭৭-এ দেখবেন।

১০ · AI-এর যুগে migration

AI একটি সুন্দর migration মিনিটে লিখে দেয়। কিন্তু সে আপনার টেবিলের আকার, সারির ব্যস্ততা বা কোন সংস্করণ চলছে, কিছুই দেখে না। ভুল কোড ফেরানো যায়, ভুল migration সব সময় নয়। মজার তথ্য: আমাদের lab-এ Prisma 7.10.1 নিজেই টের পেল যে একটি AI agent কমান্ড চালাচ্ছে, আর থামিয়ে দিল। আমরা এই reset চালাইনি:

$ npx prisma migrate reset --force
Error: Prisma Migrate detected that it was invoked by Claude Code.
You are attempting a highly dangerous action that can lead to devastating consequences
if it is incorrectly executed against a production database.
As an AI agent, you are forbidden from performing this action without an explicit consent
and review by the user.

টুলের লেখকরাই বলছেন, ধ্বংসাত্মক কমান্ডের সিদ্ধান্ত মানুষের। AI যে ভুলগুলো বেশি করে:

Migration merge করার আগে — চেকলিস্ট

• তৈরি হওয়া migration.sql লাইন ধরে পড়েছি, শুধু schema-র diff নয়
• এই SQL চালু V1 অ্যাপের সাথে চলে, আর ফেরার পথ জানি
• staging-এ বাস্তব আকারের ডেটায় সময় মেপেছি, lock_timeout বসিয়েছি
• DROP থাকলে আলাদা release-এ, আর আগে backup নিয়ে restore পরীক্ষা করেছি
• খালি ডেটাবেসে পুরো ইতিহাস চলেছে, migrate diff --exit-code পরিষ্কার
• কোনো পাসওয়ার্ড বা production-এর ঠিকানা AI-কে দিইনি বা ফাইলে রাখিনি