Database Introspection

Available since v3.4.0

Experimental Feature

Database introspection is experimental and should be used with caution.

Database introspection loads your database's schema, calculates the difference between it and your current ZModel schema, and then make necessary updates to the ZModel schema to bring it in sync with the database. This is useful when you have a pre-existing database and want to start using ZenStack with it, or when you need to keep your ZModel schema in sync with changes made directly to the database.

This feature is initially contributed by @svetch.

Use the zen db pull CLI command to run introspection. Refer to the CLI reference for more details and options.

info

The "db pull" command is NOT based on Prisma's introspection engine and has its own implementation.

Common Workflows

Starting a new ZenStack project from an existing database

If you already have a database and want to adopt ZenStack:

1. Initialize a ZenStack project:
   npm

   npx zen init

   pnpm

   pnpm zen init

   bun

   bunx zen init

   yarn

   npx zen init
2. Configure the datasource block in your ZModel schema with the correct database connection URL.
3. Run introspection to generate the schema:
   npm

   npx zen db pull

   pnpm

   pnpm zen db pull

   bun

   bunx zen db pull

   yarn

   npx zen db pull
4. Review and refine the generated ZModel schema (e.g., add access control rules, computed fields, etc.).
5. Run code generation:
   npm

   npx zen generate

   pnpm

   pnpm zen generate

   bun

   bunx zen generate

   yarn

   npx zen generate

Syncing after direct database changes

If changes were made directly to the database (outside of the ZenStack migration workflow), you can re-introspect to update your schema:

1. Run introspection:

   zen db pull
2. Review the ZModel schema changes and make necessary adjustments

warning

Running zen db pull may overwrite an existing schema file. Make sure to use source control or manually back up your schema file before running the command.