Migration Guide

Migrate to Zodipus from other Prisma-Zod generators.

When to Apply

• User mentions migrating from another generator
• User has existing prisma-zod-generator setup
• User wants to switch from zod-prisma or zod-prisma-types
• User asks about differences between generators
• User needs to replace existing Prisma-Zod solution

Why Migrate to Zodipus?

From prisma-zod-generator

Step 1: Remove Old Generator

// Before: Remove this
generator zod {
  provider = "prisma-zod-generator"
  output   = "./generated/zod"
}

// After: Add Zodipus
generator zodipus {
  provider = "zodipus"
  output   = "./generated"
}

Step 2: Update Imports

Before:

import {
  UserSchema,
  UserCreateInputSchema,
  UserUpdateInputSchema,
  PostSchema,
} from '@generated/zod';

After:

import { UserSchema, PostSchema } from './generated';

// For create/update inputs, derive from schema:
const UserCreateInputSchema = UserSchema.omit({
  id: true,
  createdAt: true,
  updatedAt: true,
});

const UserUpdateInputSchema = UserSchema.partial().omit({
  id: true,
  createdAt: true,
  updatedAt: true,
});

Step 3: Update Validation Code

Before (prisma-zod-generator):

import { UserSchema } from '@generated/zod';

const user = UserSchema.parse(data);
// Includes relations in type, may have extra fields

After (Zodipus):

import { UserSchema } from './generated';

// For simple validation
const user = UserSchema.parse(data);

// For queries with relations, use Query Engine
import { createRegistry } from 'zodipus/queryEngine';
import { models, modelRelations } from './generated/generated-index';

const registry = createRegistry({ models, relations: modelRelations });
const userQuery = registry.createQuery('user');

const query = userQuery({
  select: { id: true, email: true },
  posts: { select: { title: true } }
});

const result = query.parse(await prisma.user.findFirst(query.query));

Step 4: Handle Relation Schemas

Before (relations in schema):

// prisma-zod-generator includes relations
const userWithPosts = UserWithRelationsSchema.parse(data);

After (Query Engine):

// Zodipus uses Query Engine for relations
const query = userQuery({
  select: { id: true, email: true, name: true },
  posts: {
    select: { id: true, title: true, published: true }
  }
});

const userWithPosts = query.parse(data);

Key Differences

1. No relation schemas - Use Query Engine instead
2. No input schemas - Derive with .omit() and .partial()
3. Cleaner output - Only model schemas and enums
4. Better performance - Validates only selected fields

From zod-prisma

Step 1: Replace Generator

// Before
generator zod {
  provider        = "zod-prisma"
  output          = "./zod"
  relationModel   = true
  modelCase       = "PascalCase"
}

// After
generator zodipus {
  provider = "zodipus"
  output   = "./generated"
}

Step 2: Update Imports

Before:

import { UserModel, PostModel } from './zod';

After:

import { UserSchema, PostSchema } from './generated';

Step 3: Naming Convention Changes

Step 4: Handle RelationModel

Before (zod-prisma relationModel):

import { UserModelWithRelations } from './zod';

After (Zodipus Query Engine):

import { createRegistry } from 'zodipus/queryEngine';
import { models, modelRelations } from './generated/generated-index';

const registry = createRegistry({ models, relations: modelRelations });
const query = registry.createQuery('user')({
  select: { id: true, email: true },
  posts: { select: { title: true } }
});

From zod-prisma-types

Step 1: Replace Generator

// Before
generator zod {
  provider = "zod-prisma-types"
  output   = "./zod"
}

// After
generator zodipus {
  provider = "zodipus"
  output   = "./generated"
}

Step 2: Update Imports

Before:

import {
  UserSchema,
  UserCreateInputSchema,
  UserUpdateInputSchema,
  UserWhereInputSchema,
} from './zod';

After:

import { UserSchema } from './generated';

// Create input schemas as needed
const CreateUserSchema = UserSchema.omit({
  id: true,
  createdAt: true,
  updatedAt: true,
});

Key Difference

zod-prisma-types generates many schema variants (Create, Update, Where, OrderBy, etc.). Zodipus generates only the core model schema - derive variants as needed.

Migration Checklist

Phase 1: Setup

• Install Zodipus: npm install zodipus
• Remove old generator from schema.prisma
• Add Zodipus generator to schema.prisma
• Run npx prisma generate

Phase 2: Update Imports

• Find all imports from old generator
• Update to Zodipus import path
• Update schema names (if different)

Phase 3: Refactor Relation Handling

• Identify code using relation schemas
• Set up Query Engine registry
• Replace relation schemas with Query Engine queries

Phase 4: Derive Input Schemas

• Find all CreateInput / UpdateInput usage
• Create derived schemas with .omit() / .partial()

Phase 5: Test

• Run existing tests
• Verify validation behavior
• Check type inference

Phase 6: Cleanup

• Remove old generated files
• Uninstall old generator: npm uninstall [old-package]
• Update documentation

Common Migration Patterns

Create Input Schema

// Reusable pattern for all models
function createInputSchema<T extends z.ZodObject<any>>(
  schema: T,
  autoFields = ['id', 'createdAt', 'updatedAt']
) {
  return schema.omit(
    Object.fromEntries(autoFields.map(f => [f, true])) as any
  );
}

const CreateUserSchema = createInputSchema(UserSchema);
const CreatePostSchema = createInputSchema(PostSchema);

Update Input Schema

function updateInputSchema<T extends z.ZodObject<any>>(
  schema: T,
  immutableFields = ['id', 'createdAt']
) {
  return schema.partial().omit(
    Object.fromEntries(immutableFields.map(f => [f, true])) as any
  );
}

const UpdateUserSchema = updateInputSchema(UserSchema);

Relation Query Factory

// Create reusable query configurations
const queries = {
  minimalUser: { select: { id: true, email: true } },
  fullUser: {
    select: { id: true, email: true, name: true, role: true },
    posts: { select: { id: true, title: true } }
  },
  minimalPost: { select: { id: true, title: true } },
  fullPost: {
    select: { id: true, title: true, content: true, published: true },
    author: { select: { id: true, name: true } }
  },
};

const userQ = registry.createQuery('user');
const fullUserQuery = userQ(queries.fullUser);

Troubleshooting Migration

Types Don't Match After Migration

Cause: Different nullability or optionality.

Debug:

// Compare types
type OldUser = z.infer<typeof OldUserSchema>;
type NewUser = z.infer<typeof UserSchema>;

// Check specific fields
type OldName = OldUser['name']; // string | null ?
type NewName = NewUser['name']; // string | null ?

Relation Data Not Validated

Cause: Using plain schema instead of Query Engine.

Fix: Switch to Query Engine for relation queries.

Missing Schema Variants

Cause: Zodipus doesn't generate CreateInput, WhereInput, etc.

Fix: Derive them:

const CreateUserInput = UserSchema.omit({ id: true, createdAt: true, updatedAt: true });
const UpdateUserInput = CreateUserInput.partial();

Feature Comparison