Prisma — schema, client আর CRUD

১ · Prisma কী, আর আজ কোন version

পর্ব ৩৮-এ দেখেছেন, ORM মানে object আর table-এর মাঝের অনুবাদক। Prisma সেই দলের, তবে এর ধরন একটু আলাদা। এখানে class লিখে table বোঝাতে হয় না। আপনি একটি আলাদা ফাইলে দোকানের তথ্যের নকশা লেখেন, আর সেই নকশা থেকে কোড তৈরি হয়।

শুরুর আগে version দেখা দরকার, কারণ এখানে একটি আসল ফাঁদ আছে। লেখার সময়ে (নভেম্বর ২০২৬) npm-এ সত্যিকারের run:

$ npm view prisma dist-tags
{ ...
  next: '8.0.0-rc.10',
  prev: '7.10.1',
  latest: '8.0.0-rc.29',
  ... }          (ট্রিম করা)

$ npm view @prisma/client dist-tags
{ ... latest: '7.10.1', ... }

অর্থাৎ npm install prisma লিখলে আপনি একটি release candidate পাবেন, অথচ @prisma/client থাকবে 7-এ। দুটির version আলাদা হলে গোলমাল হবে। Prisma-র নিজের docs-ও এখন 7-এর জন্য prisma@prev লিখতে বলে। এই পর্ব তাই নির্দিষ্ট version-এ চলেছে: Prisma 7.10.1. আমাদের lab-এ CLI একবার update-এর একটি বার্তাও দেখিয়েছে, যাতে prisma@latest লেখা ছিল। সেই বার্তা না ভেবে মানবেন না।

এবার পুরো ছবিটি দেখুন। Prisma-র দুটি জগৎ আছে: একটি শুধু তৈরির সময়ে চলে, অন্যটি অ্যাপ চলার সময়ে।

আগের version-গুলোতে client-এর ভেতরে Rust-এ লেখা একটি আলাদা query engine চলত। Prisma 7 (নভেম্বর ২০২৫) থেকে সেটি client-এর ডিফল্ট পথ থেকে সরে গেছে। এখন query compiler SQL বানায়, আর আসল কথা বলে সাধারণ Node driver pg. তবে “Rust-free” কথাটি client-এর জন্য। আমাদের prisma -v-এ schema engine এখনো একটি আলাদা binary হিসেবেই দেখিয়েছে, যা table বদলানোর কাজ করে।

২ · শূন্য থেকে setup

একটি খালি folder-এ শুরু করি। Prisma 7-এর দরকার Node 20.19 বা তার ওপরে, TypeScript 5.4 বা তার ওপরে, আর docs অনুযায়ী ESM project. প্রথমে package.json-এ "type": "module", তারপর install:

npm pkg set type=module
npm install -D prisma@7.10.1 typescript tsx @types/node @types/pg
npm install @prisma/client@7.10.1 @prisma/adapter-pg@7.10.1 pg dotenv
npx prisma init --datasource-provider postgresql \
  --output ../generated/prisma --no-skills

সত্যিকারের run-এ init বলল (ট্রিম করা):

Initialized Prisma in your project

  prisma/
    schema.prisma
  prisma7.config.ts
  .env
  .gitignore
…
Then, define your models in prisma/schema.prisma and run prisma migrate dev to apply your schema.

একটি নাম খেয়াল করুন: prisma7.config.ts. পুরোনো লেখা আর বেশিরভাগ টিউটোরিয়ালে পাবেন prisma.config.ts. Prisma 7.10.0-এর release notes অনুযায়ী নতুন নামটি এসেছে, যাতে একই project-এ Prisma 7 আর Prisma 8 পাশাপাশি থাকতে পারে, আর Prisma 7-এর CLI দিয়ে নতুন শুরু করা project এই নামই পায়। 7.10.1-এর CLI দুটো নামই খুঁজে নেয়: আগে prisma7.config.*, না পেলে পুরোনো prisma.config.*. তাই দুটি ফাইল একসাথে রাখবেন না, নইলে পুরোনোটি চুপচাপ উপেক্ষিত হবে। ভেতরে যা তৈরি হলো (মন্তব্য বাদে হুবহু):

import "dotenv/config";
import { defineConfig } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: {
    path: "prisma/migrations",
  },
  datasource: {
    url: process.env["DATABASE_URL"],
  },
});

এখানে তিনটি জিনিস আগের চেয়ে বদলেছে, আর AI প্রায়ই পুরোনোটি লেখে:

প্রথম ঘরের error আমরা সত্যিই চালিয়ে দেখেছি। পুরোনো schema-য় prisma validate বলল:

error: The datasource property `url` is no longer supported in schema files.
Move connection URLs for Migrate to `prisma.config.ts` and pass either `adapter`
for a direct database connection or `accelerateUrl` for Accelerate to the
`PrismaClient` constructor.

এবার .env. এতে থাকে connection string, যা একটি secret. init-এর বানানো .gitignore এই ফাইল আর /generated/prisma, দুটোকেই বাদ দেয়। নিচের মানগুলো নকল:

DATABASE_URL="postgresql://bazar:example-secret@127.0.0.1:5432/bazarghar?schema=public"

৩ · schema.prisma পড়া

পর্ব ২৯ আর ৩৪-এ বাজারঘরের পণ্য ছিল হাতে লেখা SQL table-এ। এবার সেটি Prisma schema-য় লিখি। generator বলে কী তৈরি হবে, datasource বলে কোন database, আর model বলে কোন তথ্য।

generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
}

datasource db {
  provider = "postgresql"
}

enum ProductStatus {
  DRAFT
  ACTIVE
  ARCHIVED
}

model Product {
  id         Int           @id @default(autoincrement())
  sku        String        @unique
  name       String
  category   String
  pricePaisa Int           @map("price_paisa")
  stock      Int           @default(0)
  status     ProductStatus @default(ACTIVE)
  createdAt  DateTime      @default(now()) @map("created_at")
  updatedAt  DateTime      @updatedAt @map("updated_at")

  @@map("products")
}

এক @ মানে একটি ঘরের ওপর নিয়ম, দুই @@ মানে পুরো model-এর ওপর। @map কেন? পর্ব ২৯-এর নিয়মটি মনে করুন: কোডে pricePaisa, database-এ price_paisa. @map ছাড়া column-এর নাম হতো pricePaisa, আর হাতে SQL লেখার সময় প্রতিবার quote দিতে হতো।

টেবিলের শেষের আগের সারিটি গুরুত্বপূর্ণ। @updatedAt-এর কাজ করে client, database নয়। সত্যিকারের run:

raw update changed updatedAt? false
client update changed updatedAt? true

অর্থাৎ $executeRaw বা অন্য কোনো টুল দিয়ে সারি বদলালে updatedAt পুরোনোই থাকে। Cache বা sync এর ওপর ভরসা করলে এটি মনে রাখা দরকার।

Lab-এ ঘরটি হয়েছে timestamp without time zone. পর্ব ৩৪-এর timestamptz চাইলে DateTime @db.Timestamptz লিখতে হয়। আর table বানাতে এই পর্বে চলেছে prisma db push:

$ npx prisma db push
Loaded Prisma config from prisma7.config.ts.
Prisma schema loaded from prisma\schema.prisma.
Datasource "db": PostgreSQL database "bazarghar", schema "public" at "127.0.0.1:38939"

Your database is now in sync with your Prisma schema. Done in 153ms

৪ · টাকা রাখবেন কীভাবে: Decimal নাকি integer paisa

চায়ের দোকানের খাতায় কেউ “সাড়ে বারো টাকা”র দশমিক নিয়ে ভাবেন না। মনে মনে হিসাব হয় পয়সায়। কম্পিউটারের জন্যও সেটিই নিরাপদ। Float-এ টাকা রাখলে floating point-এর ভুল আসে। JavaScript-এ সত্যিকারের run:

> 0.1 + 0.2
0.30000000000000004
> 19.99 * 100
1998.9999999999998

দুটি ভালো পথ আছে: Decimal, অথবা ছোট একক অর্থাৎ minor unit-এ integer. টাকার ছোট একক পয়সা, ১ টাকা = ১০০ পয়সা। তাহলে ৳১৫০.৫০ মানে 15050.

একটি Decimal(12, 2) ঘরে '150.50' রেখে সত্যিকারের run-এ পড়া হলো:

typeof row.amount  → object
JSON.stringify     → {"id":1,"amount":"150.5"}
row.amount.plus('0.25').toString() → 150.75

খেয়াল করুন, JSON-এ "150.5" এসেছে একটি স্ট্রিং হয়ে, শেষের শূন্যটিও নেই। Frontend-কে এটি জানতে হবে। পুরো কোর্সে বাজারঘরের দাম তাই integer paisa: pricePaisa Int. দেখানোর সময়ে ১০০ দিয়ে ভাগ, হিসাবের সময়ে সব পূর্ণসংখ্যা। Decimal ভুল নয়, শুধু আমাদের দরকারের চেয়ে ভারী।

কতটুকু পর্যন্ত ধরবে: একটি হিসাব

PostgreSQL-এর integer ৩২ bit, সর্বোচ্চ 2,147,483,647. একে পয়সা ধরলে:

একটি পণ্যের দামের জন্য ২ কোটি টাকার বেশি যথেষ্ট। কিন্তু মাসিক বিক্রির মোট এই ঘরে ধরবে, এমন নিশ্চয়তা নেই। সেখানে BigInt বিবেচনা করুন। সীমা পেরোলে আসল run-এ error এলো P2020:

Value out of range for the type: value "2147483648" is out of range for type integer
PrismaClientKnownRequestError P2020

আসল ফাঁদ: দশমিক চুপচাপ হারিয়ে গেল

TypeScript-এর চোখে Int মানে শুধু number, তাই 150.5 compile হয়ে যায়। আমরা আশা করেছিলাম Prisma থামাবে। থামায়নি। Prisma 7.10.1 আর PostgreSQL-এ সত্যিকারের run:

create({ pricePaisa: 150.4 })                → 150
create({ pricePaisa: 150.5 })                → 150
create({ pricePaisa: 151.5 })                → 151
create({ pricePaisa: 0.30000000000000004 })  → 0

কোনো error নেই, সারি তৈরি হয়ে গেল, আর দাম গোল না হয়ে কেটে গেল। এটি এই এক সেটআপের এক run-এর ফল, অন্য version-এ আচরণ আলাদা হতে পারে। শিক্ষা একই: ভরসা রাখুন প্রবেশপথে। পর্ব ২৭-এর Zod দিয়ে z.number().int() দিলে একই ভুল status 422 হয়ে ফিরল:

$ curl -X POST /products -d '{"sku":"GHI-002", … ,"pricePaisa":620.5}'
422
{"error":{"code":"VALIDATION_FAILED", … "fields":[{"path":"pricePaisa",
 "message":"Invalid input: expected int, received number"}]}}

৫ · prisma generate আর type-সহ client

prisma generate schema পড়ে আপনার project-এ TypeScript ফাইল লেখে। আমাদের run:

$ npx prisma generate
✔ Generated Prisma Client (7.10.1) to .\generated\prisma in 21ms

generated/prisma/
  client.ts   browser.ts   enums.ts   models.ts   commonInputTypes.ts
  internal/   models/Product.ts  …      (ট্রিম করা; এই lab-এ মোট 162K)

এবার একটি সম্পূর্ণ query-র পথ দেখুন, খাতা থেকে শুরু করে হাতে আসা object পর্যন্ত। “পরে” চাপুন।

model Product {
  sku        String @unique
  name       String
  pricePaisa Int    @map("price_paisa")
  …
}

// আসল ফাইলে অনেক বেশি লাইন; ধারণাটি এমন
export type ProductModel = {
  id: number; sku: string; name: string;
  pricePaisa: number; stock: number; …
}

const p = await prisma.product.findUnique({
  where:  { sku: 'DAL-001' },
  select: { id: true, name: true, pricePaisa: true },
});

SELECT "id", "name", "price_paisa" FROM "products"
WHERE ("sku" = $1 AND 1=1) LIMIT $2 OFFSET $3
params ["DAL-001","1","0"]

{ "id": 1, "name": "মসুর ডাল ১ কেজি", "pricePaisa": 15000 }

এর সবচেয়ে বড় উপহার হলো select অনুযায়ী ফেরত type বদলানো। নিচের block-টি generated type-এর একটি ছোট শেখার মডেল, আসল কোড নয়। চালিয়ে দেখুন, compiler কোথায় আটকায়।

type Product = {
  id: number; sku: string; name: string;
  pricePaisa: number; stock: number;
};

type Select = { [K in keyof Product]?: true };
type Payload<S> = { [K in keyof S & keyof Product]: Product[K] };

function findUnique<S extends Select>(args: {
  where: { sku: string };
  select: S;
}): Payload<S> {
  const row: Product = {
    id: 1, sku: args.where.sku, name: 'dal',
    pricePaisa: 15000, stock: 40,
  };
  return row as unknown as Payload<S>;
}

const p = findUnique({
  where: { sku: 'DAL-001' },
  select: { name: true, pricePaisa: true },
});

console.log(p.name, p.pricePaisa);
console.log(p.stock);

আসল client-এও হুবহু একই ভাবে থামে। Prisma 7.10.1-এর generated type-এ tsc-এর সত্যিকারের run:

src/select-types.ts(8,15): error TS2339: Property 'stock' does not exist on type
  '{ name: string; pricePaisa: number; }'.
src/select-types.ts(11,32): error TS2322: Type 'string' is not assignable to type 'number'.
src/select-types.ts(14,42): error TS2561: Object literal may only specify known properties,
  but 'pricePoisha' does not exist in type 'ProductWhereInput'. Did you mean to write 'pricePaisa'?

তৃতীয় বার্তাটি দেখুন: বানান ভুল ধরে ঠিক নামটিও বলে দিল। কিন্তু এই পাহারা ততক্ষণ ঠিক, যতক্ষণ client নতুন। Prisma 7-এ db push আর migrate dev নিজে থেকে generate চালায় না। আমরা schema-য় weightGram যোগ করে শুধু db push চালালাম:

src/stale.ts(2,54): error TS2353: Object literal may only specify known properties,
  and 'weightGram' does not exist in type 'ProductSelect<DefaultArgs>'.

Table-এ ঘর আছে, client জানে না। npx prisma generate চালাতেই error গেল। Schema বদলের পরের অভ্যাস: push, তারপর generate.

৬ · CRUD আর আসল SQL দেখা

ORM-এর সবচেয়ে বড় বিপদ হলো না দেখে বিশ্বাস করা। তাই শুরুতেই query log চালু করি। log-এ emit: 'event' দিলে প্রতিটি query একটি event হয়:

const prisma = new PrismaClient({
  adapter,
  log: [{ emit: 'event', level: 'query' }, 'warn'],
});

prisma.$on('query', (e) =>
  console.log(`SQL> ${e.query}\nparams ${e.params} (${e.duration}ms)`));

এবার বাজারঘরের পণ্য নিয়ে সব কাজ। প্রতিটির নিচে আসল SQL, সত্যিকারের run. পড়ার সুবিধায় বারবার আসা "public"."products". অংশ ছেঁটে দেওয়া হয়েছে, আর লম্বা তালিকায় “…” বসেছে।

const dal = await prisma.product.create({
  data: { sku: 'DAL-001', name: 'মসুর ডাল ১ কেজি',
          category: 'dal', pricePaisa: 15000, stock: 40 },
});

INSERT INTO "products" ("sku","name","category","price_paisa","stock","status",
  "created_at","updated_at")
VALUES ($1,$2,$3,$4,$5,CAST($6::text AS "ProductStatus"),$7,$8) RETURNING "id", "sku", …
params ["DAL-001","মসুর ডাল ১ কেজি","dal",15000,40,"ACTIVE","2026-11-01T17:48:27.526Z", …]

=> {"id":1,"sku":"DAL-001", … ,"pricePaisa":15000,"stock":40,"status":"ACTIVE", …}

const r = await prisma.product.createMany({
  data: [ /* ৬টি পণ্য, যার একটি DAL-001 ডুপ্লিকেট */ ],
  skipDuplicates: true,
});

INSERT INTO "products" (…) VALUES ($1,…,$8), ($9,…,$16), … ($41,…,$48) ON CONFLICT DO NOTHING

=> {"count":5}

await prisma.product.findUnique({ where: { sku: 'NOPE' } });

SELECT "id", "sku", "name", … FROM "products" WHERE ("sku" = $1 AND 1=1) LIMIT $2 OFFSET $3
params ["NOPE","1","0"]

=> null

await prisma.product.update({
  where: { sku: 'TEL-001' },
  data: { stock: { increment: 20 } },
});

UPDATE "products" SET "stock" = ("stock" + $1), "updated_at" = $2
WHERE ("sku" = $3 AND 1=1) RETURNING "id", "sku", "stock", …
params [20,"2026-11-01T17:48:27.554Z","TEL-001"]

await prisma.product.delete({ where: { sku: 'SUG-001' } });

DELETE FROM "products" WHERE ("sku" = $1 AND 1=1) RETURNING "id", "sku"

=> {"id":9,"sku":"SUG-001"}

নিচে একই ধরনের query আপনি নিজে চালাতে পারেন। এটি পাতার ভেতরের SQLite, তাই সারিগুলো আসল PostgreSQL-এর lab-এর মতো সাজানো হলেও dialect একটু আলাদা। মান বদলে দেখুন।

-- findMany({ where: { category: { in: ['rice','dal'] },
--   pricePaisa: { lte: 45000 }, stock: { gt: 0 } },
--   select: {...}, orderBy: [{pricePaisa:'desc'},{id:'asc'}],
--   take: 2, skip: 1 })
SELECT id, name, price_paisa FROM products
WHERE category IN ('rice', 'dal')
  AND price_paisa <= 45000 AND stock > 0
ORDER BY price_paisa DESC, id ASC
LIMIT 2 OFFSET 1;

-- update({ where: {sku}, data: { stock: { increment: 20 } } })
UPDATE products SET stock = stock + 20 WHERE sku = 'TEL-001'
RETURNING sku, stock;

-- upsert: DAL-001 already exists, so the UPDATE part runs
INSERT INTO products (sku, name, category, price_paisa, stock)
VALUES ('DAL-001', 'Masoor dal 1kg', 'dal', 15000, 5)
ON CONFLICT (sku) DO UPDATE SET stock = stock + 5
RETURNING sku, stock;

-- upsert: SUG-001 is new, so the INSERT part runs
INSERT INTO products (sku, name, category, price_paisa, stock)
VALUES ('SUG-001', 'Sugar 1kg', 'sugar', 14000, 5)
ON CONFLICT (sku) DO UPDATE SET stock = stock + 5
RETURNING sku, stock;

upsert: থাকলে বদলানো, না থাকলে নতুন বানানো

Upsert সবচেয়ে ভুল বোঝা কাজগুলোর একটি। সরবরাহকারীর তালিকা থেকে পণ্য আসছে: থাকলে stock বাড়াতে হবে, না থাকলে নতুন পণ্য বসাতে হবে। শর্ত মিললে Prisma কাজটি একটি মাত্র SQL-এ করে, ON CONFLICT দিয়ে। আগে DAL-001-এ stock ছিল 40, আর sequence-এর পরের id ছিল 8.

1INSERT INTO products (sku, …, stock)2VALUES ($1, …, 5)3ON CONFLICT (sku)4DO UPDATE SET stock = stock + 55RETURNING id, sku, stock;

শর্ত না মিললে কী হয়? Docs-এর শর্ত এগুলো: create আর update-এ nested কাজ নেই, where-এ একটিই unique ঘর, আর সেই ঘরের মান where ও create-এ এক। আমরা ইচ্ছা করে create-এ ভিন্ন sku দিলাম। আসল log:

SELECT "id" FROM "products" WHERE ("sku" = $1 AND 1=1) OFFSET $2
INSERT INTO "products" (…) VALUES (…) RETURNING "id"
SELECT "id", "sku", "stock" FROM "products" WHERE "id" = $1 LIMIT $2 OFFSET $3
COMMIT

একের জায়গায় তিনটি query, আর মাঝখানে সময়ের ফাঁক। এই ফাঁকের ফল কী, একটি run-এ মাপা হলো। একই পণ্যে ১০টি অনুরোধ একসাথে পাঠানো হলো, দুই পথে:

native upsert ×10            → ok 10, stock = 10
findUnique, তারপর create ×10 → ok 1, rejected 9, codes [ 'P2002' ], stock = 1

একই কাজ, অথচ নিজে হাতে লেখা “দেখে তারপর বানাও” ১০টির ৯টিতে ব্যর্থ, আর ৯টি যোগ হারিয়ে গেছে। এই race-এর পূর্ণ আলোচনা পর্ব ৪৩-এ। এখনকার নিয়ম: unique constraint-ই আসল পাহারাদার, আগের SELECT নয়।

৭ · পড়া: where, select, orderBy, take, skip আর cursor

পর্ব ৩৪-এ filter আর pagination-এর নিয়ম শিখেছেন। এখানে দেখুন Prisma-র ভাষায় সেগুলো কী হয়। সব SQL এই lab-এর আসল log থেকে ছোট করা।

এক where-এর কয়েকটি শর্ত মানে AND. contains সুন্দর দেখায়, কিন্তু সামনে % থাকায় সাধারণ B-tree index কাজে আসে না, যা পর্ব ৩৪-এ দেখেছেন। বড় টেবিলে এর জন্য full-text search ভাবতে হয়।

একসাথে সব ব্যবহার করলে এমন, সত্যিকারের run:

const rows = await prisma.product.findMany({
  where: {
    category: { in: ['rice', 'dal'] },
    pricePaisa: { lte: 45000 },
    stock: { gt: 0 },
  },
  select: { id: true, name: true, pricePaisa: true },
  orderBy: [{ pricePaisa: 'desc' }, { id: 'asc' }],
  take: 2,
  skip: 1,
});

SELECT "id", "name", "price_paisa" FROM "products"
WHERE ("category" IN ($1,$2) AND "price_paisa" <= $3 AND "stock" > $4)
ORDER BY "price_paisa" DESC, "id" ASC LIMIT $5 OFFSET $6
params ["rice","dal",45000,0,"2","1"]

=> [{"id":5,"name":"মুগ ডাল ১ কেজি","pricePaisa":19000},
    {"id":1,"name":"মসুর ডাল ১ কেজি","pricePaisa":15000}]

take হলো LIMIT, skip হলো OFFSET. select শুধু দরকারি ঘর আনে, আর ফোনের network-এ এই ছোট্ট লাইনটিই payload কমায়। উল্টো কাজের জন্য আছে omit, তবে দুটো একসাথে চলে না।

ভেতরের নিয়মগুলো চোখে দেখতে নিচে একটি ছোট নকল prisma.product. এটি শেখার মডেল, আসল Prisma নয়, তবে এর শেষ লাইনটি আসল আচরণটিই দেখায়।

const rows = [
  { id: 1, sku: 'DAL-001', category: 'dal',  pricePaisa: 15000, stock: 40 },
  { id: 2, sku: 'CHL-001', category: 'rice', pricePaisa: 42000, stock: 25 },
  { id: 3, sku: 'CHL-002', category: 'rice', pricePaisa: 47500, stock: 8 },
  { id: 4, sku: 'TEL-001', category: 'oil',  pricePaisa: 18500, stock: 0 },
  { id: 5, sku: 'DAL-002', category: 'dal',  pricePaisa: 19000, stock: 12 },
];
const ok = (value, f) => {
  if (f === undefined) return true;          // undefined মানে কোনো শর্তই নেই
  if (typeof f !== 'object') return value === f;
  if (f.in && !f.in.includes(value)) return false;
  if (f.gt !== undefined && !(value > f.gt)) return false;
  return true;
};
const product = {
  findMany({ where = {}, select, orderBy, take, skip = 0 }) {
    let out = rows.filter((r) =>
      Object.entries(where).every(([k, f]) => ok(r[k], f)));
    if (orderBy) {
      const [[k, dir]] = Object.entries(orderBy);
      out = [...out].sort((a, b) => (dir === 'asc' ? a[k] - b[k] : b[k] - a[k]));
    }
    out = out.slice(skip, take === undefined ? undefined : skip + take);
    if (!select) return out;
    return out.map((r) => Object.fromEntries(Object.keys(select).map((k) => [k, r[k]])));
  },
};
console.log(product.findMany({
  where: { category: { in: ['rice', 'dal'] }, stock: { gt: 0 } },
  select: { sku: true, pricePaisa: true },
  orderBy: { pricePaisa: 'desc' }, take: 2, skip: 1,
}));
const sku = undefined;                       // ভুল করে খালি
console.log(product.findMany({ where: { sku } }).length, 'rows');

Cursor: পর্ব ৩৪-এর সাথে মিলিয়ে

Prisma-য় cursor লেখা সহজ: cursor-এ শেষ সারির id, আর skip: 1 দিয়ে সেই সারিটি বাদ। না হলে সেটি আবার আসে।

const page2 = await prisma.product.findMany({
  take: 2, skip: 1,
  cursor: { id: 2 },
  orderBy: { id: 'asc' },
  select: { id: true, sku: true },
});

SELECT "id", "sku" FROM "products"
WHERE "id" >= (SELECT "id" FROM "products" WHERE ("id") = ($1))
ORDER BY "id" ASC LIMIT $2 OFFSET $3
params [2,"2","1"]

=> [{"id":3,"sku":"CHL-002"},{"id":4,"sku":"TEL-001"}]

দেখুন, আসল SQL পর্ব ৩৪-এর সরল WHERE id > ? নয়। এতে একটি subquery আর OFFSET 1 আছে। ছোট অফসেট, তাই গভীরতায় খরচ বাড়ে না, তবে cursor-এ দেওয়া ঘরটি অনন্য হতে হয়। পর্ব ৩৪-এর (created_at, id) ক্রমের জন্য তাই একটি compound unique লাগবে, নয়তো নিজের where লিখতে হবে। আর hasMore এর জন্য পর্ব ৩৪-এর limit + 1 কৌশলই চলে। Client-এর পাঠানো object কখনো সরাসরি orderBy-এ দেবেন না, পর্ব ৩৪-এর allowlist এখানেও দরকার।

৮ · P2002, P2025 আর API error

পর্ব ২৮-এর error handling-এ toAppError লিখেছিলেন, যা ভেতরের ভুলকে একটি ভাষায় আনে। সেখানে কথা দেওয়া ছিল, Prisma-য় unique violation-এর code হবে P2002. Prisma-র এই ভুলগুলো আসে PrismaClientKnownRequestError হয়ে, যার code স্থির।

এবার সবচেয়ে সূক্ষ্ম জায়গা। প্রায় সব পুরোনো টিউটোরিয়াল আর AI লেখে e.meta.target, যাতে ঘরের নাম থাকত। Docs-এর সাধারণ error পাতাতেও উদাহরণটি এখনো আছে। Driver adapter-এ আমাদের সত্যিকারের run-এ দেখা গেল অন্য আকার (trim করা):

name: PrismaClientKnownRequestError | code: P2002 | clientVersion: 7.10.1
instanceof: true
meta: {
  driverAdapterError: DriverAdapterError: UniqueConstraintViolation {
    cause: {
      originalCode: '23505',
      originalMessage: 'duplicate key value violates unique constraint "products_sku_key"',
      kind: 'UniqueConstraintViolation',
      constraint: { index: 'products_sku_key' },
      table: 'products'
    }
  },
  modelName: 'Product'
}

meta.target নেই। পর্ব ২৮-এ বলা SQLSTATE 23505 ভেতরে আছে, আর index-এর নামও আছে। তাই meta-র আকারের ওপর ব্যবসার নিয়ম দাঁড় করাবেন না। নিচে দুই ধরনের লেখার তুলনা। এটিও শেখার মডেল: class-টি নকল, তবে meta-র আকার ওপরের আসল run থেকে নেওয়া।

class KnownError extends Error {               // নকল, আসলটি generated client-এ
  constructor(code, meta) { super('prisma detail'); this.code = code; this.meta = meta; }
}
class AppError extends Error {
  constructor(status, code, message) {
    super(message); this.status = status; this.code = code;
  }
}
function toAppError(err) {
  if (err instanceof AppError) return err;
  if (err instanceof KnownError) {
    if (err.code === 'P2002') return new AppError(409, 'DUPLICATE_SKU', 'SKU exists');
    if (err.code === 'P2025') return new AppError(404, 'PRODUCT_NOT_FOUND', 'Not found');
  }
  return null;                                 // অচেনা মানে bug
}
const reply = (err) => {
  const k = toAppError(err);
  return { status: k?.status ?? 500, code: k?.code ?? 'INTERNAL',
    message: k?.message ?? 'Something went wrong on our side' };
};
const dup = new KnownError('P2002', {
  modelName: 'Product',
  driverAdapterError: { cause: { originalCode: '23505',
    constraint: { index: 'products_sku_key' }, table: 'products' } },
});
console.log('old habit :', dup.meta.target);
console.log('real path :', dup.meta.driverAdapterError.cause.constraint.index);
console.log(reply(dup));
console.log(reply(new KnownError('P2025', { modelName: 'Product' })));
console.log(reply(new KnownError('P2010', {})));
console.log(reply(new TypeError('secret table name in here')));

একটি ডুপ্লিকেট SKU কীভাবে database থেকে উঠে 409 হয়, সেটি স্তর ধরে দেখুন।

POST /products
{ "sku": "GHI-001", "name": "again",
  "category": "ghee", "pricePaisa": 62000 }

create: (p) => db.product.create({ data: p, select: fields })

duplicate key value violates unique constraint
"products_sku_key"

PrismaClientKnownRequestError
code: P2002
message: (ফাইলের path আর কোডের লাইনসহ লম্বা লেখা)

if (err.code === 'P2002')
  return new AppError(409, 'DUPLICATE_SKU', 'এই SKU আগেই আছে', …)

409
{"error":{"code":"DUPLICATE_SKU","message":"এই SKU আগেই আছে",
 "fields":[{"path":"sku","message":"এই SKU আগেই আছে"}]}}

আসল Express অ্যাপে পাঁচটি request-এর সত্যিকারের run (Express 5.3.0, ট্রিম করা). id 62 এসেছে, কারণ আগের পরীক্ষাগুলো sequence খরচ করেছে:

$ POST   /products            {"sku":"GHI-001", …}     → 201 {"id":62,"sku":"GHI-001", … }
$ POST   /products            {"sku":"GHI-001", …}     → 409 {"error":{"code":"DUPLICATE_SKU", … }}
$ PATCH  /products/GHI-001/price {"pricePaisa":64500}  → 200 {"id":62, … ,"pricePaisa":64500, … }
$ PATCH  /products/NOPE-999/price {"pricePaisa":100}   → 404 {"error":{"code":"PRODUCT_NOT_FOUND", … }}
$ DELETE /products/NOPE-999                            → 404 {"error":{"code":"PRODUCT_NOT_FOUND", … }}

৯ · একটিই client, hot reload আর repository

Client-এর ভেতরে থাকে একটি connection pool, অর্থাৎ আগে থেকে খোলা কিছু সংযোগ। তিনটি CNG-র একটি স্ট্যান্ড ভাবুন: যাত্রী অপেক্ষা করেন, গাড়ি ফিরলে পরের জন ওঠেন। Prisma 7-এ pool-টি pg-এর, তাই তার ডিফল্টই চলে: max ১০টি সংযোগ। Prisma 6-এর ডিফল্ট আলাদা ছিল, আর docs সতর্ক করে যে pg-এর সংযোগের ডিফল্ট timeout নেই।

একটি হিসাব: pool কতটা কাজ নিতে পারে

৩০টি query, প্রতিটি ১০০ ms. Pool-এ cটি সংযোগ থাকলে আদর্শ সময় হবে ⌈30 ÷ c⌉ × 100 ms:

বাড়তি সময়টি নতুন সংযোগ খোলার আর Prisma-র নিজের খরচ, এবং এটি একটি মেশিনের এক run-এর মাপ। Pool ঠিক করতে হলে adapter-এ দিন:

const adapter = new PrismaPg({
  connectionString: process.env.DATABASE_URL,
  max: 10,
  connectionTimeoutMillis: 5000,
});

Hot reload-এ সংযোগ জমে কেন

Client মানে pool, আর pool মানে খোলা সংযোগ। কিছু dev server ফাইল বদলালে পুরো process চালু রেখে module আবার চালায়, যেমন Next.js-এর dev server (পর্ব ৫১). তখন new PrismaClient() আবার চলে, কিন্তু আগের client বন্ধ হয় না। tsx watch বা node --watch সাধারণত পুরো process নতুন করে চালায়, তাই সেখানে এই সমস্যা কম। আমরা একই process-এ module বারবার import করে এই ঘটনাটি অনুকরণ করলাম, প্রতিবার ১০টি query একসাথে। সত্যিকারের run, PostgreSQL-এর max_connections 100:

সাধারণ module                            singleton
reload  1: clients=1 connections=10      reload  1: clients=1 connections=10
reload  2: clients=2 connections=20      reload  2: clients=1 connections=10
…                                        …
reload  9: clients=9 connections=90      reload  9: clients=1 connections=10
reload 10: FAILED P2010 Raw query failed.      reload 10: clients=1 connections=10
  Code: `53300`. sorry, too many clients already      …

বাঁয়ে দশম reload-এই database নতুন সংযোগ নিতে অস্বীকার করল। হিসাবটি সহজ: ৯ × ১০ = ৯০, পরীক্ষার নিজের ১টি, আর দশম client-এর ১০টির কিছু। ডানে সংখ্যাটি নড়েনি। সমাধান হলো singleton: client-কে এমন জায়গায় রাখা, যা module আবার চললেও টিকে থাকে, অর্থাৎ globalThis:

import 'dotenv/config';
import { PrismaPg } from '@prisma/adapter-pg';
import { PrismaClient } from '../../generated/prisma/client.ts';

function createClient() {
  const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL });
  return new PrismaClient({
    adapter,
    log: [{ emit: 'event', level: 'query' }, 'warn'],
  });
}

type Client = ReturnType<typeof createClient>;
const globalForPrisma = globalThis as unknown as { prisma?: Client };

export const prisma = globalForPrisma.prisma ?? createClient();

if (process.env.NODE_ENV !== 'production') {
  globalForPrisma.prisma = prisma;
}

Adapter ছাড়া client বানাতে গেলে আসল run-এ বার্তা স্পষ্ট:

PrismaClientInitializationError: PrismaClient was instantiated without any options.
A driver adapter is required to connect to your database.

আর বন্ধ করার সময় সংযোগ ফেরত দিন। পর্ব ২৮-এর graceful shutdown-এ SIGTERM পেলে await prisma.$disconnect() ডাকুন। আমাদের run-এ সব client-এর $disconnect-এর পরে সংযোগ ছিল ০।

পর্ব ২৯-এর repository-তে জোড়া

পর্ব ২৯-এ repository-র চুক্তি ছিল interface, আর আসল কোড ছিল SQLite-এ। এবার একই ধরনের চুক্তির নিচে Prisma বসে। Service কিছুই টের পায় না।

import { Prisma, PrismaClient } from '../generated/prisma/client.ts';
import type { ProductRepository } from './product.repository.ts';

const fields = {
  id: true, sku: true, name: true, category: true,
  pricePaisa: true, stock: true,
} satisfies Prisma.ProductSelect;

export function prismaProductRepository(db: PrismaClient): ProductRepository {
  return {
    findBySku: (sku) =>
      db.product.findUnique({ where: { sku }, select: fields }),

    list: ({ category, limit, after }) =>
      db.product.findMany({
        where: { status: 'ACTIVE', category },
        select: fields,
        orderBy: { id: 'asc' },
        take: limit,
        ...(after ? { cursor: { id: after }, skip: 1 } : {}),
      }),

    create: (p) => db.product.create({ data: p, select: fields }),

    async setPrice(sku, pricePaisa) {
      try {
        return await db.product.update({
          where: { sku }, data: { pricePaisa }, select: fields,
        });
      } catch (e) {
        if (e instanceof Prisma.PrismaClientKnownRequestError
            && e.code === 'P2025') return null;
        throw e;
      }
    },
  };
}

চারটি সিদ্ধান্ত খেয়াল করুন। select: fields রাখায় createdAt-এর মতো ভেতরের ঘর বাইরে যায় না। db parameter-এ আসে, তাই dependency injection অটুট। P2025 এখানে null হয়েছে, কারণ পর্ব ২৯-এর চুক্তি বলে “না পেলে null”, আর 404-এর সিদ্ধান্ত repository-র নয়। আর list-এ category undefined হলে filter চলে যায়, এখানে সেটিই আমরা চাই। ঐচ্ছিক filter-এ এটি সুবিধা, বাধ্যতামূলক শর্তে এটি বিপদ।

সত্যিকারের run-এ category=dal&limit=1 দিল "hasMore":true,"next":1, আর after=1 দিয়ে পরের পাতা দিল "hasMore":false.

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

Prisma দ্রুত বদলেছে, আর AI-এর শেখা উপাদানে পুরোনো version-ই বেশি। তাই এখানে AI খুব আত্মবিশ্বাসে পুরোনো কোড লেখে। নিচের প্রতিটি আমরা 7.10.1-এ চালিয়ে বা docs-এ মিলিয়ে দেখেছি।

আরেকটি কথা। Prisma-র CLI 6.15 থেকে AI agent চিনতে পারে, আর data মুছে দিতে পারে এমন কমান্ড সে নিজে থেকে চালায় না। আমাদের lab-এই db push --accept-data-loss থেমে গিয়ে মানুষের স্পষ্ট সম্মতি চেয়েছে। এটি ভালো নকশা, তবে একমাত্র পাহারা নয়। Production-এর URL কখনো AI-এর হাতে দেবেন না, আর সম্মতির ঘরে AI-কে নিজে লিখতে দেবেন না।

AI-এর লেখা Prisma কোড মেলানোর চেকলিস্ট

• package.json-এ prisma আর @prisma/client একই stable version-এ, কোনো RC নেই
• npx prisma validate, prisma generate আর tsc --noEmit চালিয়েছি
• Query log খুলে আসল SQL আর query-র সংখ্যা দেখেছি
• where-এর কোনো মান undefined হলে কী হবে, ভেবে দেখেছি, বিশেষ করে owner-এর id
• ডুপ্লিকেট আর না-পাওয়া, দুটো ঘটনাই চালিয়ে 409 আর 404 দেখেছি
• .env Git-এ যায়নি, আর কোনো secret AI-কে পাঠাইনি