Prisma ORM Notes

Prisma is a typesafe, schema-driven ORM for Node.js and TypeScript that generates a tailored client based on your structural definitions.

🐊 Key Capabilities

• Type Safety: Automatically generates TypeScript types matching your database schema.
• Declarative Schema: A single schema.prisma file serves as the source of truth for tables, relations, and configurations.
• Migration Engine: Declarative migration generation tracking state differences via plain SQL files.
• Prisma Studio: An embedded GUI for data inspection and manipulation (npx prisma studio).

🚀 Implementation Workflow

1. Project Initialisation & Dependencies

Configure a Node.js workspace running native ES Modules (ESM).

# Initialize workspace
mkdir hello-prisma && cd hello-prisma
npm init -y

# Install TypeScript toolchain
npm install typescript tsx @types/node --save-dev
npx tsc --init

# Install Prisma engine and PostgreSQL adapters
npm install prisma @types/pg --save-dev
npm install @prisma/client @prisma/adapter-pg pg dotenv

☘ Environment Configurations

Update your configuration files to support target environments

// tsconfig.json
{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "node",
    "target": "ES2023",
    "strict": true,
    "esModuleInterop": true
  }
}

// package.json
{
  "type": "module"
}

2. Initializing Prisma

Generate the configuration layer and schema framework:

npx prisma init

Scaffolding Prisma

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

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

Configure your local or remote target instance within your secure configuration file:

# .env
DATABASE_URL="postgresql://username:password@localhost:5432/mydb?schema=public"

3. Schema Design & Data Modeling

Define application models

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

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

model Post {
  id        Int     @id @default(autoincrement())
  title     String
  content   String?
  published Boolean @default(false)
  author    User    @relation(fields: [authorId], references: [id])
  authorId  Int
}

4. Running Database Migrations

Synchronize your target database with the declaration models. This maps the .prisma file

npx prisma migrate dev --name init

5. Client Singleton Architectural Pattern

To optimize application connection pooling

// lib/prisma.ts
import pg from 'pg';
import { PrismaPg } from '@prisma/adapter-pg';
import { PrismaClient } from '../generated/prisma/client/index.js';

const connectionString = `${process.env.DATABASE_URL}`;

// Setup physical driver layer
const pool = new pg.Pool({ connectionString });
const adapter = new PrismaPg(pool);

// Instantiate global client
export const prisma = new PrismaClient({ adapter });

6. Executing CRUD Actions

Verify transaction lifecycles and relation joins natively using type-safe logic execution:

// script.ts
import { prisma } from './lib/prisma.js';

async function main() {
  // Write operation with nested relation creation
  const newUser = await prisma.user.create({
    data: {
      name: 'Alice',
      email: 'alice@prisma.io',
      posts: {
        create: {
          title: 'Hello World',
          content: 'This is my first post!',
          published: true,
        },
      },
    },
    include: {
      posts: true,
    },
  });
  console.log('User created safely:', newUser);

  // Read operation with relation hydration
  const allUsers = await prisma.user.findMany({
    include: { posts: true },
  });
  console.dir(allUsers, { depth: null });
}

main()
  .then(async () => {
    await prisma.$disconnect();
  })
  .catch(async (e) => {
    console.error(e);
    await prisma.$disconnect();
    process.exit(1);
  });