Saltar al contenido principal

Resumen Prisma ORM (desde cero)

Este anexo resume la configuración necesaria para inicializar un proyecto desde cero que utilice Prisma ORM.

Ante dudas, lo más recomendable es consultar la documentación oficial.

Paso 1 — Inicializar proyecto de Node.js​

Creamos el package.json:

npm init -y
Ejemplo de salida del comando
Wrote to /home/debian/dwcs/package.json:

{
  "name": "dwcs",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "commonjs"
}

Establecemos type="module" al package.json para permitir la sintaxis de Módulos ES6 (uso de import / export en lugar de require):

npm pkg set type="module"

También podemos modificar el fichero package.json manualmente.

Paso 2 — Instalación de dependencias​

Comprobar versiones de Prisma (última versión):

npm show prisma versions --json

Instalamos la dependencia de Prisma ORM para desarrollo:

npm install prisma --save-dev

Instalamos la dependencia de Prisma ORM para producción:

npm install @prisma/client dotenv

Los paquetes instalados son los siguientes:

  • @prisma — Herramienta de línea de comandos de Prisma.
  • @prisma/client — Cliente de Prisma ORM.
  • dotenv — Gestor de variables de entorno.

A mayores, según el tipo de base de datos que vayamos a utilizar, tenemos que instalar el adapter correspondiente:

# SQLite
npm install @prisma/adapter-better-sqlite3

# MySQL / MariaDB
npm install @prisma/adapter-mariadb

# PostgreSQL
npm install @prisma/adapter-pg

Paso 3 — Inicialización de ficheros de Prisma​

Inicializamos Prisma (crea ficheros y directorios para la configuración de Prisma):

npx prisma init
Ejemplo de salida del comando
Initialized Prisma in your project

  prisma/
    schema.prisma
  prisma.config.ts
  .env
  .gitignore

Next, choose how you want to set up your database:

CONNECT EXISTING DATABASE:
  1. Configure your DATABASE_URL in prisma.config.ts
  2. Run prisma db pull to introspect your database.

CREATE NEW DATABASE:
  Local: npx prisma dev (runs Postgres locally in your terminal)
  Cloud: npx create-db (creates a free Prisma Postgres database)

Then, define your models in prisma/schema.prisma and run prisma migrate dev to apply your schema.

Learn more: https://pris.ly/getting-started

Como nos indica la salida del comando, crea los ficheros:

  • prisma/schema.prisma
  • prisma.config.ts
  • .env
  • .gitignore
Complemento para Visual Studio Code

Para el resaltado de sintaxis de ficheros .prisma podemos utilizar la extensión Prisma.

Paso 4 — Establecer el cliente JS​

Comenzaremos por modificar el fichero prisma/schema.prisma. Estableceremos el cliente de Prisma ORM en su versión Javascript cambiando el valor de generator.provider por prisma-client-js.

// This is your Prisma schema file,
// learn more about it in the docs: https://pris.ly/d/prisma-schema

// Get a free hosted Postgres database in seconds: `npx create-db`

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

datasource db {
  provider = "postgresql"
}

El valor prisma-client utiliza TypeScript.

Paso 5 — Definir la conexión a la base de datos​

En el .env creado, viene por defecto lo siguiente:

DATABASE_URL="prisma+postgres://localhost:51213/?api_key=xxxxxxxxxxxxxxxxxxxxxxx"

Lo que indiquemos en DATABASE_URL determinará a qué base de datos se conectará.

Por otro lado, debemos modificar el valor datasource.provider del fichero prisma/schema.prisma. Se debe establecer el valor correspondiente con la base de datos que se va a utilizar dentro de los valores soportados: mysql, sqlite, postgresql, mongodb, etc.

// This is your Prisma schema file,
// learn more about it in the docs: https://pris.ly/d/prisma-schema

// Get a free hosted Postgres database in seconds: `npx create-db`

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

datasource db {
  provider = "sqlite"
}

Este paso se puede evitar si usásemos el siguiente comando en el paso 3:

npx prisma init --datasource-provider sqlite

SQLite​

Para una base de datos SQLite (fichero local), el valor de DATABASE_URL lo reemplazaremos por el siguiente:

DATABASE_URL="file:./dev.sqlite"

MySQL/MariaDB​

Para una base de datos MySQL o MariaDB, el valor de DATABASE_URL lo reemplazaremos por el siguiente:

DATABASE_URL="mysql://root:abc123.@mysql:3306/miBD"

Esa URL define:

  • Nombre de usuario: root
  • Contraseña: abc123.
  • Hostname: mysql
  • Puerto de MySQL/MariaDB: 3306 (dejar este valor por defecto si no se ha modificado el puerto en la instancia de la base de datos)
  • Nombre de la base de datos que se va emplear: miBD

Paso 6 — Generar el schema de Prisma​

npx prisma generate
Ejemplo de salida del comando
Loaded Prisma config from prisma.config.ts.

Prisma schema loaded from prisma\schema.prisma.

✔ Generated Prisma Client (v7.6.0) to .\generated\prisma in 9ms

Start by importing your Prisma Client (See: https://pris.ly/d/importing-client)

La salida del comando anterior nos indica que el cliente de Prisma se ha generado en el directorio ./generated/prisma. Si accdemos a él, veremos múltiples ficheros JavaScript.

Paso 7 — Definir nuestros modelos​

En el mismo fichero ./generated/prisma, añadimos los esquemas que necesitemos:

// This is your Prisma schema file,
// learn more about it in the docs: https://pris.ly/d/prisma-schema

// Get a free hosted Postgres database in seconds: `npx create-db`

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

datasource db {
  provider = "sqlite"
}

model Usuario {
  id     Int    @id @default(autoincrement())
  nombre String
  email  String @unique
}
Importante

Si en el directorio ./generated/prisma no vemos ficheros .js es que no hemos configurado correctamente el cliente a prisma-client-js.

Paso 8 — Ejecutamos las migraciones​

Llevamos a cabo la migración de la base de datos (esto creará las tablas necesarias):

npx prisma migrate dev --name init
Ejemplo de salida del comando
Loaded Prisma config from prisma.config.ts.

Prisma schema loaded from prisma\schema.prisma.
Datasource "db": SQLite database "dev.sqlite" at "file:./dev.sqlite"

SQLite database dev.sqlite created at file:./dev.sqlite

Applying migration `20260402075436_init`

The following migration(s) have been created and applied from new schema changes:

prisma\migrations/
  └─ 20260402075436_init/
    └─ migration.sql

El comando genera un archivo SQL de migración en la carpeta prisma/migrations/, lo aplica y actualiza el historial de migraciones en la tabla _prisma_migrations de tu base de datos.

Alternativa rápida a migraciones

De forma alternativa, se puede usar:

npx prisma db push

Esto "empuja" el schema directamente a la base de datos sin crear archivos de migración. Es destructivo si hay cambios incompatibles (puede borrar datos) y no lleva historial.

Cuándo usarlo:

  • Prototipado rápido o exploración inicial.
  • Proyectos personales sin datos importantes.
  • Cuando quieres iterar el schema rápidamente sin preocuparte del historial.
  • Entornos donde la base de datos es efímera (tests, demos).

Paso 9 — Actualizar schema de Prisma​

Cada vez que se hace un cambio en el schema de Prisma (prisma/schema.prisma), ejecutar:

npx prisma generate

Esto actualizará el cliente de Prisma.

Ejemplo de salida del comando
Loaded Prisma config from prisma.config.ts.

Prisma schema loaded from prisma\schema.prisma.

✔ Generated Prisma Client (v7.6.0) to .\generated\prisma in 45ms

Start by importing your Prisma Client (See: https://pris.ly/d/importing-client)

También se deberá ejecutar el comando si decidimos cambiar de motor de base de datos.

Paso 10 — Configurar el cliente en el programa​

Según la base de datos que utilicemos, el cliente Prisma se debe configurar de diferente manera, aunque los pasos base son los mismos: importamos el cliente Prisma y el adpatador de la base de datos. Para crear el objeto PrismaClient utilizamos un objeto obtenido a partir del adapter.

Vamos a ver cómo hacerlo para:

SQLite​

import 'dotenv/config';
import { PrismaBetterSqlite3 } from "@prisma/adapter-better-sqlite3";
import { PrismaClient } from "./generated/prisma/index.js";

// El .env debe tener una URL para SQLite
const adapter = new PrismaBetterSqlite3({ url: process.env.DATABASE_URL });
const prisma = new PrismaClient({ adapter });

MySQL/MariaDB​

import 'dotenv/config';
import { PrismaMariaDb } from "@prisma/adapter-mariadb";
import { PrismaClient } from "./generated/prisma/index.js";

// El .env debe tener una URL para MySQL/MariaDB
const adapter = new PrismaMariaDb(process.env.DATABASE_URL);
const prisma = new PrismaClient({ adapter });

PostgreSQL​

import 'dotenv/config';
import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "./generated/prisma/index.js";

// El .env debe tener una URL para PostgreSQL
const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL }); 
const prisma = new PrismaClient({ adapter });

Paso 11 — Realizar consultas​

Para realizar las consultas, se debe utilizar el objeto prisma:

import 'dotenv/config';
import { PrismaBetterSqlite3 } from "@prisma/adapter-better-sqlite3";
import { PrismaClient } from "./generated/prisma/index.js";

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

try {
    const usuario = await prisma.usuario.create({
        data: {
            nombre: 'Juan Perez',
            email: 'juan.perez@example.com',
        },
    });
    console.log(`Usuario creado correctamente con ID: ${usuario.id}`);
} catch (error) {
    console.error('Error al crear el usuario:', error.message);
}

await prisma.$disconnect();