Prisma 7 Setup

Velox TS uses Prisma 7 with driver adapters. All scaffolded templates are pre-configured — this guide explains the setup if you need to understand or customize it.

Already scaffolded?

If you created your project with create-velox-app, Prisma 7 is already configured. You can skip to Velox TS Integration or Common Errors if you run into issues.

How Prisma 7 Works

Prisma 7 uses driver adapters to connect to databases at runtime. Three configuration files work together:

• prisma.config.ts — Tells the Prisma CLI where to find the schema and database URL
• prisma/schema.prisma — Defines your data model (no connection URL here)
• src/config/database.ts — Creates the runtime client with a driver adapter

// prisma.config.ts — CLI configuration
import 'dotenv/config';
import { defineConfig } from 'prisma/config';

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

// schema.prisma — data model only
datasource db {
  provider = "sqlite"
}

// database.ts — runtime client with adapter
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 });

This separation gives you full control over connection pooling, timeouts, and enables edge/serverless deployments.

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. Define your schema in prisma/schema.prisma:

   generator client {
     provider = "prisma-client-js"
     output   = "../node_modules/.prisma/client"
   }
   
   datasource db {
     provider = "sqlite"
   }
   
   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';

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"

Velox TS 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 Velox TS context
declare module '@veloxts/core' {
  interface BaseContext {
    db: PrismaClient;
  }
}

Use in procedures:

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

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: datasourceUrl is not a valid PrismaClient option in Prisma 7.

Fix: Use a driver adapter:

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

// CORRECT
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 present in schema.prisma datasource block.

Fix: Remove url from the schema — the database URL belongs in prisma.config.ts:

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

// 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 5/6

Note

This section is for developers bringing an existing Prisma project into Velox TS. If you started with create-velox-app, you can skip this.

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 5/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

Related Content

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