Database & Schema Management

Database & Schema Management

The Next.js Boilerplate provides a robust, type-safe data layer designed to bridge the gap between rapid local prototyping and high-scale production environments. By leveraging Drizzle ORM, the system ensures you have a lightweight, performant way to interact with your data while maintaining full TypeScript support across your entire stack.

Unified Data Strategy

Managing databases often involves juggling complex local setups and disparate production configurations. This boilerplate simplifies that workflow by providing a dual-stage database environment:

• Local Development with PGlite: Experience a full PostgreSQL environment without the need to install a heavy database engine or manage Docker containers. PGlite runs directly in your environment, providing instant startup and zero-config persistence.
• Production-Ready Scalability: Transition seamlessly to Prisma Postgres or any PostgreSQL-compatible provider for production. The system is architected to ensure your local queries behave exactly like your production queries.

Type-Safe Schema Modeling

The source of truth for your data resides in src/models/Schema.ts. Using Drizzle’s declarative syntax, you define your tables, columns, and relationships in pure TypeScript. This approach eliminates the mismatch between your database schema and your application code.

// Example: Defining a schema in src/models/Schema.ts
import { integer, pgTable, serial, timestamp } from 'drizzle-orm/pg-core';

export const counterSchema = pgTable('counter', {
  id: serial('id').primaryKey(),
  count: integer('count').default(0),
  updatedAt: timestamp('updated_at', { mode: 'date' })
    .defaultNow()
    .$onUpdate(() => new Date())
    .notNull(),
});

Seamless Migration Workflow

Evolving your database is handled through a streamlined migration pipeline. Instead of writing manual SQL scripts, the boilerplate automates the synchronization between your TypeScript models and the database state.

1. Modify: Update your schema in src/models/Schema.ts.
2. Generate: Run npm run db:generate to automatically create a migration file that reflects your changes.
3. Apply: Changes are applied automatically during development, or can be manually pushed using npm run db:migrate.

This workflow ensures that your database versioning is tracked in source control, making it easy for teams to stay in sync.

Built-in Data Validation

Data integrity is enforced at both the database level and the application level. The boilerplate integrates Zod alongside Drizzle to provide a "validation sandwich":

• Drizzle ensures the database structure is sound.
• Zod validates incoming API requests (e.g., in src/validations/) before they ever touch the database, preventing malformed data from causing runtime errors.

High-Performance Querying

Because Drizzle is a "thin" ORM, it offers a developer experience similar to writing SQL but with the safety of TypeScript. You get the benefits of auto-completion and type checking without the performance overhead of traditional, heavy ORMs.

// Example usage in an API route
import { db } from '@/libs/DB';
import { counterSchema } from '@/models/Schema';

const result = await db
  .insert(counterSchema)
  .values({ count: 1 })
  .returning();

Whether you are building a simple counter or a complex multi-tenant SaaS application, the database architecture in this boilerplate provides the flexibility to grow and the safety to move fast.