Prisma 7 Setup

VeloxTS uses Prisma 7, which introduces significant architectural changes from previous versions.

Breaking Changes in Prisma 7

Prisma 7 removes datasourceUrl from PrismaClient and requires driver adapters. All VeloxTS templates are pre-configured—this guide is for understanding or migrating existing projects.

What Changed in Prisma 7?

Prisma 6 (Old)

schema.prisma

datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")  // URL configured here
}

database.ts

import { PrismaClient } from '@prisma/client';
export const db = new PrismaClient();  // Just works

Prisma 7 (New)

schema.prisma

datasource db {
  provider = "sqlite"
  // NO url field - configured in prisma.config.ts
}

// prisma.config.ts (NEW - required)
import 'dotenv/config';
import { defineConfig } from 'prisma/config';

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

database.ts

import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3';
import { PrismaClient } from '@prisma/client';

const adapter = new PrismaBetterSqlite3({ url: process.env.DATABASE_URL! });
export const db = new PrismaClient({ adapter });  // Adapter required

Why Driver Adapters?

• Separation of concerns: CLI configuration (migrations) separate from runtime (client)
• Connection control: Full control over pooling, timeouts, and behavior
• Edge support: Enables serverless and edge deployments
• Type safety: Type-safe adapter configuration

Quick Setup

1. Create prisma.config.ts at project root:

   import 'dotenv/config';
   import { defineConfig } from 'prisma/config';
   
   export default defineConfig({
     schema: './prisma/schema.prisma',
     datasource: {
       url: process.env.DATABASE_URL,
     },
   });

2. Update prisma/schema.prisma (remove url field):

   generator client {
     provider = "prisma-client-js"
     output   = "../node_modules/.prisma/client"
   }
   
   datasource db {
     provider = "sqlite"
     // NO url here - it's in prisma.config.ts
   }
   
   model User {
     id        String   @id @default(uuid())
     name      String
     email     String   @unique
     createdAt DateTime @default(now())
     updatedAt DateTime @updatedAt
   
     @@map("users")
   }

3. Create database client at src/config/database.ts:

   import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3';
   import { PrismaClient } from '@prisma/client';
   
   if (!process.env.DATABASE_URL) {
     throw new Error('DATABASE_URL environment variable is required');
   }
   
   const adapter = new PrismaBetterSqlite3({
     url: process.env.DATABASE_URL,
   });
   
   export const db = new PrismaClient({ adapter });

4. Set environment variable in .env:

   DATABASE_URL="file:./dev.db"

5. Generate client and push schema:

   pnpm prisma generate
   pnpm prisma db push

Database-Specific Setup

SQLite (Development)

Best for local development, testing, and demos.

Dependencies:

{
  "@prisma/adapter-better-sqlite3": "7.2.0",
  "@prisma/client": "7.2.0",
  "better-sqlite3": "11.9.1",
  "prisma": "7.2.0"
}

Configuration:

import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3';
import { PrismaClient } from '@prisma/client';

const adapter = new PrismaBetterSqlite3({
  url: process.env.DATABASE_URL,  // "file:./dev.db"
});
export const db = new PrismaClient({ adapter });

Note

After installing, rebuild the native module: npm rebuild better-sqlite3

PostgreSQL (Production)

Best for production applications with high concurrency.

Dependencies:

{
  "@prisma/adapter-pg": "7.2.0",
  "@prisma/client": "7.2.0",
  "pg": "8.13.0",
  "prisma": "7.2.0"
}

Configuration:

import { PrismaPg } from '@prisma/adapter-pg';
import { PrismaClient } from '@prisma/client';

// Pass connectionString directly (Prisma 7 pattern)
const adapter = new PrismaPg({
  connectionString: process.env.DATABASE_URL,
});
export const db = new PrismaClient({ adapter });

Environment:

DATABASE_URL="postgresql://user:password@localhost:5432/mydb?schema=public"

VeloxTS Integration

Extend the context to include your Prisma client:

src/config/database.ts

import type { BaseContext } from '@veloxts/core';
import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3';
import { PrismaClient } from '@prisma/client';

const adapter = new PrismaBetterSqlite3({
  url: process.env.DATABASE_URL!,
});

export const db = new PrismaClient({ adapter });

// Extend VeloxTS context
declare module '@veloxts/core' {
  interface BaseContext {
    db: PrismaClient;
  }
}

Use in procedures:

import { procedures, procedure } from '@veloxts/velox';
import { z } from 'zod';

export const userProcedures = procedures('users', {
  listUsers: procedure()
    .query(({ ctx }) => ctx.db.user.findMany()),

  getUser: procedure()
    .input(z.object({ id: z.string().uuid() }))
    .query(({ input, ctx }) => ctx.db.user.findUniqueOrThrow({
      where: { id: input.id },
    })),
});

Common Errors

”Unknown property datasourceUrl”

Cause: Prisma 7 removed datasourceUrl from PrismaClient constructor.

Fix: Use a driver adapter instead:

// WRONG (Prisma 6 pattern)
const db = new PrismaClient({ datasourceUrl: process.env.DATABASE_URL });

// CORRECT (Prisma 7 pattern)
const adapter = new PrismaBetterSqlite3({ url: process.env.DATABASE_URL! });
const db = new PrismaClient({ adapter });

“The datasource property ‘url’ is no longer supported”

Cause: url field in schema.prisma datasource block.

Fix: Remove url from schema, configure in prisma.config.ts:

// WRONG
datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")  // Remove this
}

// CORRECT
datasource db {
  provider = "sqlite"
}

“Cannot find module ‘better-sqlite3’”

Cause: Native module not rebuilt after installation.

Fix:

npm rebuild better-sqlite3

“PrismaBetterSQLite3 is not a constructor”

Cause: Incorrect class name casing.

Fix: Use PrismaBetterSqlite3 (lowercase “qlite”):

// WRONG
import { PrismaBetterSQLite3 } from '@prisma/adapter-better-sqlite3';

// CORRECT
import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3';

“ENOENT: no such file or directory”

Cause: Database path relative to wrong directory.

Fix: Paths are relative to project root (where prisma.config.ts is):

# CORRECT
DATABASE_URL="file:./dev.db"

# WRONG (if running from src/)
DATABASE_URL="file:../dev.db"

Migrating from Prisma 6

1. Update dependencies:

   pnpm add @prisma/client@7.2.0 @prisma/adapter-better-sqlite3@7.2.0
   pnpm add -D prisma@7.2.0

2. Remove url from schema:

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

3. Create prisma.config.ts:

   import 'dotenv/config';
   import { defineConfig } from 'prisma/config';
   
   export default defineConfig({
     schema: './prisma/schema.prisma',
     datasource: {
       url: process.env.DATABASE_URL!,
     },
   });

4. Update database client:

   // Before (Prisma 6)
   import { PrismaClient } from '@prisma/client';
   export const db = new PrismaClient();
   
   // After (Prisma 7)
   import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3';
   import { PrismaClient } from '@prisma/client';
   
   const adapter = new PrismaBetterSqlite3({ url: process.env.DATABASE_URL! });
   export const db = new PrismaClient({ adapter });

5. Rebuild and regenerate:

   npm rebuild better-sqlite3
   pnpm prisma generate

Troubleshooting Checklist

• Prisma version is 7.x: pnpm list prisma
• Adapter package installed: pnpm list @prisma/adapter-*
• Native module rebuilt (SQLite): npm rebuild better-sqlite3
• No url field in schema.prisma datasource
• prisma.config.ts exists with correct URL
• DATABASE_URL environment variable is set
• Prisma client generated: pnpm prisma generate
• Database schema pushed: pnpm prisma db push

Next Steps

• Driver Adapters - All adapter options
• Migrations - Schema changes
• Seeding - Test data