Prisma 7 y driver adapters: el cambio que rompe tutoriales viejos

Si aprendiste Prisma con cualquier tutorial de hace más de un año, el setup que conoces probablemente ya no es el que te vas a encontrar en un proyecto nuevo. Prisma rediseñó su arquitectura de conexión alrededor de driver adapters, y el cambio no es cosmético — afecta directamente cómo instancias el cliente, dónde vive el código generado, y algunos errores nuevos que no vas a encontrar en la documentación antigua.

El setup “clásico” que probablemente conoces

// Cómo se veía antes (Prisma 5 y anteriores)
import { PrismaClient } from '@prisma/client'
const prisma = new PrismaClient()

Simple: el cliente se conectaba directamente a la base de datos usando la DATABASE_URL del .env, sin ningún paso intermedio. Este patrón sigue apareciendo en la gran mayoría de tutoriales y cursos disponibles hoy.

El setup actual, con driver adapters

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

const adapter = new PrismaBetterSqlite3({ url: 'file:./prisma/dev.db' })
const prisma = new PrismaClient({ adapter })

Dos diferencias saltan a la vista de inmediato: el cliente ya no viene de @prisma/client directo, sino de una carpeta generated/ propia del proyecto; y la conexión a la base de datos ahora pasa explícitamente por un adapter — en este caso, para SQLite usando el driver nativo better-sqlite3.

Por qué Prisma hizo este cambio

Los drivers adapters desacoplan el cliente de Prisma del motor de conexión específico de cada base de datos. Esto habilita casos que antes eran difíciles o imposibles: usar drivers nativos más rápidos (como better-sqlite3 en vez del motor de query engine binario tradicional de Prisma), o conectar a bases de datos serverless (Neon, PlanetScale, D1 de Cloudflare) con sus propios protocolos de conexión optimizados para edge — sin que Prisma tenga que reimplementar soporte específico para cada uno dentro de su propio binario.

Los errores nuevos que vas a encontrar (y cómo resolverlos)

@prisma/client did not initialize yet

Error: @prisma/client did not initialize yet. Please run "prisma generate"

Este error aparece cuando el cliente tipado (el código generado a partir de tu schema.prisma) todavía no existe o quedó desincronizado. La solución:

npx prisma generate

The table ... does not exist in the current database

Este síntoma aparece cuando el cliente está bien generado, pero las migraciones nunca se aplicaron sobre el archivo de base de datos real:

npx prisma migrate dev --name init

Rutas de archivo que no coinciden entre CLI y adapter

Este es el más confuso de los tres, y el que menos documentado está. El CLI de Prisma (cuando corres migrate, db seed, etc.) resuelve rutas relativas de la DATABASE_URL de una forma; el driver adapter, dentro de tu código de aplicación, puede resolverlas de otra (típicamente relativo al directorio de trabajo desde donde ejecutas el proceso). El síntoma es que la migración parece exitosa, pero tu aplicación sigue reportando que las tablas no existen — porque en realidad está mirando un archivo .db distinto al que el CLI usó.

La solución más robusta es evitar la ambigüedad por completo, usando una ruta absoluta calculada en tiempo de ejecución:

import path from 'node:path'
import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3'
import { PrismaClient } from '../generated/prisma/client'

const dbPath = path.join(process.cwd(), 'prisma', 'dev.db')
const adapter = new PrismaBetterSqlite3({ url: `file:${dbPath}` })
const prisma = new PrismaClient({ adapter })

process.cwd() siempre apunta a la raíz desde donde ejecutas npm run/npx, sin importar si es el CLI o tu aplicación quien interpreta esa ruta — eliminando la ambigüedad de raíz.

El singleton, ahora con el adapter incluido

El patrón de singleton para evitar agotar el pool de conexiones en desarrollo (por el hot-reload de Next.js) sigue siendo necesario, ahora envolviendo también la creación del adapter:

// src/lib/prisma.ts
import path from 'node:path'
import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3'
import { PrismaClient } from '../../generated/prisma/client'

const globalForPrisma = globalThis as unknown as { prisma: PrismaClient | undefined }

function createPrismaClient() {
  const dbPath = path.join(process.cwd(), 'prisma', 'dev.db')
  const adapter = new PrismaBetterSqlite3({ url: `file:${dbPath}` })
  return new PrismaClient({ adapter })
}

export const prisma = globalForPrisma.prisma ?? createPrismaClient()

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

Sin este singleton, cada recarga en caliente durante desarrollo re-ejecuta el módulo, y sin cachear el cliente en globalThis, cada reload abre una nueva conexión hasta agotar el límite del driver.

Configuración centralizada con prisma.config.ts

Otro cambio: en vez de que todo dependa implícitamente de variables de entorno leídas por el CLI de forma mágica, Prisma ahora recomienda un archivo de configuración explícito:

// prisma.config.ts
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'),
  },
})

Esto hace explícito qué comando de seed usar, dónde viven las migraciones, y de dónde sale la URL de conexión — información que antes vivía dispersa entre .env, package.json, y convenciones implícitas.

Conclusión

Si vienes de un proyecto Prisma anterior, o de un tutorial que asumía el setup clásico, este cambio de arquitectura vale la pena entenderlo antes de perder tiempo debuggeando errores que parecen de configuración pero en realidad son de arquitectura. La clave para evitar el 90% de los problemas: rutas absolutas para el adapter, prisma generate después de cualquier cambio de schema, y no asumir que el setup de un tutorial de hace un año sigue siendo válido tal cual.

¿Tu equipo está migrando un proyecto Prisma a la nueva arquitectura de driver adapters? Agenda una asesoría técnica gratuita de 15 minutos.