Integrating Prisma with Next.js and MySQL

Integrating Prisma with Next.js is a popular choice for building modern, type-safe applications. However, to make this setup stable and production-ready, it’s important to pay attention to a few key details — especially when working with MySQL.

In this article, I’ll walk through:

• choosing the correct Prisma adapter for MySQL,
• configuring Prisma Client properly in a Next.js environment,
• using a single shared Prisma instance across the app,
• and setting up prisma.config.ts for schema, migrations, and environment variables.

---

Choosing the Correct Database Adapter

One of the most important things to understand when working with Prisma is that each database type requires the correct adapter.

In my case, I’m using MySQL, and according to the official Prisma documentation, the recommended adapter is MariaDB. While this might sound confusing at first, MySQL and MariaDB are compatible, and Prisma officially supports MySQL connections through the MariaDB adapter.

Installing the MariaDB Adapter

npm install @prisma/adapter-mariadb

Configuring Prisma Client with the Adapter

Here’s how my Prisma Client configuration looks in a Next.js project:
File: lib/prisma.ts

import { PrismaMariaDb } from "@prisma/adapter-mariadb";
import { PrismaClient } from "../generated/prisma/client";

const globalForPrisma = global as unknown as { prisma: PrismaClient };

const adapter = new PrismaMariaDb({
  host: process.env.MYSQL_HOST,
  user: process.env.MYSQL_USER,
  password: process.env.MYSQL_PASSWORD,
  database: process.env.MYSQL_DATABASE,
  port: 3306,
  connectionLimit: 5,
});

export const prisma = globalForPrisma.prisma || new PrismaClient({ adapter });

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

What’s happening here?

• PrismaMariaDb: Handles communication between Prisma and the MySQL database.
• Environment variables: Credentials are loaded from process.env, keeping sensitive data out of the codebase.
• Global Prisma instance: Prevents creating multiple Prisma Client instances during development.
• connectionLimit: Helps avoid exhausting database connections — especially important in serverless or hot-reload environments.

---

Using a Single Prisma Instance Across the Application

Once Prisma Client is configured, it’s crucial to always reuse the same instance throughout the entire application.

I keep my Prisma instance in a single file:

lib / prisma.ts;

And everywhere I need database access, I import it like this:

import { prisma } from "../../../lib/prisma";

Why does this matter?

Next.js (especially in development mode):

• reloads modules frequently,
• re-executes server code due to Hot Reload,
• can easily create multiple database connections unintentionally.

Creating a new PrismaClient instance in multiple places can quickly lead to:

• database connection limit errors,
• degraded performance,
• hard-to-debug issues.

By exporting one shared Prisma instance, we ensure:

• predictable behavior,
• controlled database connections,
• compliance with Prisma’s official recommendations for Next.js.

Best practice: Never instantiate PrismaClient directly in routes or components — always import the shared prisma instance.

---

Prisma Global Configuration (prisma.config.ts)

The final piece of the setup is the prisma.config.ts file, which defines global Prisma configuration such as the schema location, migrations folder, and datasource URL.

Here’s how it looks in my project:

// This file was generated by Prisma, and assumes you have installed the following:
// npm install --save-dev prisma dotenv
import "dotenv/config";
import { defineConfig } from "prisma/config";

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

Breakdown of the configuration

• schema: Points to schema.prisma, where models, relations, and generators are defined.
• migrations.path: Specifies where Prisma stores database migrations, keeping the project structure clean.
• datasource.url: Reads the database connection string from DATABASE_URL, allowing easy switching between environments.
• dotenv/config: Automatically loads environment variables from .env without additional setup.

Why this setup works well

This configuration:

• improves clarity and maintainability,
• supports multiple environments (development, staging, production),
• follows Prisma’s recommended project structure.

---

Conclusion

A solid Prisma + Next.js + MySQL setup requires more than just installing dependencies. The key points are:

• choosing the correct database adapter (PrismaMariaDb for MySQL),
• creating and reusing a single Prisma Client instance,
• avoiding multiple database connections in development,
• and keeping Prisma configuration clean and explicit.

With this approach, you get a stable, scalable, and production-ready integration that plays nicely with Next.js and Prisma’s architecture.

Happy coding 🚀