CLI command reference
Overview
This document describes the Prisma CLI commands, arguments, and options.
Synopsis
The prisma
command can be called from command line once installed. When called without arguments, it will display its command usage and help document:
$prisma
Prisma is a modern DB toolkit to query, migrate and model your database (https://prisma.io)Usage$ prisma [command]Commandsinit Setup Prisma for your appintrospect Get the datamodel of your databasegenerate Generate artifacts (e.g. Prisma Client)studio Open Prisma Studioformat Format your schemamigrate Migrate your database (Preview)db Manage your database schema and lifecycle (Preview)Flags--preview-feature Run Preview Prisma commandsExamplesSetup a new Prisma project$ prisma initIntrospect an existing database$ prisma introspectGenerate artifacts (e.g. Prisma Client)$ prisma generateBrowse your data$ prisma studioCreate migrations from your Prisma schema, apply them to the database, generate artifacts (e.g. Prisma Client)$ prisma migrate dev --preview-featurePush the Prisma schema state to the database$ prisma db push --preview-feature
You can get additional help on any of the prisma
commands by adding the --help
flag after the command.
Commands
version (-v )
The version
command outputs information about your current @prisma/cli
version, platform, and engine binaries.
Options
The version
command recognizes the following options to modify its behavior:
Option | Required | Description |
---|---|---|
--json | No | Outputs version information in JSON format. |
Examples
Output version information
$prisma version
Environment variables loaded from ./prisma/.env @prisma/cli : 2.13.0-beta.3 Current platform: windows Query Engine : query-engine 2fb8f444d9cdf7c0beee7b041194b42d7a9ce1e6 (atC:\Users\veroh\AppData\Roaming\npm\node_modules\@prisma\cli\query-engine-windows.exe) MigrationEngine : migration-engine-cli 2fb8f444d9cdf7c0beee7b041194b42d7a9ce1e6 (atC:\Users\veroh\AppData\Roaming\npm\node_modules\@prisma\cli\migration-engine-windows.exe)Introspection Engine : introspection-core 2fb8f444d9cdf7c0beee7b041194b42d7a9ce1e6 (atC:\Users\veroh\AppData\Roaming\npm\node_modules\@prisma\cli\introspection-engine-windows.exe)
Output version information (-v )
$prisma -v
Environment variables loaded from ./prisma/.env @prisma/cli : 2.0.0-beta.3 Current platform: windows Query Engine : query-engine 2fb8f444d9cdf7c0beee7b041194b42d7a9ce1e6 (atC:\Users\veroh\AppData\Roaming\npm\node_modules\@prisma\cli\query-engine-windows.exe) MigrationEngine : migration-engine-cli 2fb8f444d9cdf7c0beee7b041194b42d7a9ce1e6 (atC:\Users\veroh\AppData\Roaming\npm\node_modules\@prisma\cli\migration-engine-windows.exe)Introspection Engine : introspection-core 2fb8f444d9cdf7c0beee7b041194b42d7a9ce1e6 (atC:\Users\veroh\AppData\Roaming\npm\node_modules\@prisma\cli\introspection-engine-windows.exe)
Output version information as JSON
$prisma version --json
Environment variables loaded from ./prisma/.env{"@prisma/cli": "2.0.0-beta.3","current-platform": "windows","query-engine": "query-engine 2fb8f444d9cdf7c0beee7b041194b42d7a9ce1e6 (at C:\\Users\\veroh\\AppData\\Roaming\\npm\\node_modules\\@prisma\\cli\\query-engine-windows.exe)","migration-engine": "migration-engine-cli 2fb8f444d9cdf7c0beee7b041194b42d7a9ce1e6 (at C:\\Users\\veroh\\AppData\\Roaming\\npm\\node_modules\\@prisma\\cli\\migration-engine-windows.exe)", "introspection-engine": "introspection-core 2fb8f444d9cdf7c0beee7b041194b42d7a9ce1e6 (at C:\\Users\\veroh\\AppData\\Roaming\\npm\\node_modules\\@prisma\\cli\\introspection-engine-windows.exe)"}
init
Bootstraps a fresh Prisma project within the current directory.
The init
command does not interpret any existing files. Instead, it creates a prisma
directory containing a bare-bones schema.prisma
file within your current directory.
Examples
Run prisma init
$prisma init
✔ Your Prisma schema was created at prisma/schema.prisma.You can now open it in your favorite editor.Next steps:1. Set the provider of the datasource block in schema.prisma to match your database: postgresql, mysql or sqlite.2. Set the DATABASE_URL in the .env file to point to your existing database. If your database has no tables yet, read https://pris.ly/d/getting-started.3. Run prisma introspect to turn your database schema into a Prisma data model.4. Run prisma generate to install Prisma Client. You can then start querying your database.More information in our documentation:https://pris.ly/d/getting-started
The command output contains helpful information on how to use the generated files and begin using Prisma with your project.
Generated Assets
prisma/schema.prisma
A minimal schema.prisma
file to define your schema in:
// This is your Prisma schema file,// learn more about it in the docs: https://pris.ly/d/prisma-schemadatasource db {provider = "postgresql"url = env("DATABASE_URL")}generator client {provider = "prisma-client-js"}
prisma/.env
A file to define environment variables for your project:
# Environment variables declared in this file are automatically made available to Prisma.# See the documentation for more detail: https://pris.ly/d/prisma-schema#using-environment-variables# Prisma supports the native connection string format for PostgreSQL, MySQL and SQLite.# See the documentation for all the connection string options: https://pris.ly/d/connection-stringsDATABASE_URL="postgresql://johndoe:johndoe@localhost:5432/mydb?schema=public"
generate
The generate
command generates assets like Prisma Client based on the generator
and data model
blocks defined in your prisma/schema.prisma
file.
The generate
command is most often used to generate Prisma Client with the prisma-client-js
generator. This does three things:
- Searches the current directory and parent directories to find the applicable
npm
project. It will create apackage.json
file in the current directory if it cannot find one. - Installs the
@prisma/client
into thenpm
project if it is not already present. - Inspects the current directory to find a Prisma schema file to process. It will then generate a customized Prisma Client for your project.
Prerequisites
To use the generate
command, you must add a generator definition in your schema.prisma
file. The prisma-client-js
generator, used to generate Prisma Client, can be added by including the following in your schema.prisma
file:
generator client {provider = "prisma-client-js"}
Options
The generate
command recognizes the following options to modify its behavior:
Option | Required | Description | Default |
---|---|---|---|
--schema | No | Specifies the path to the desired schema.prisma file to be processed instead of the default path. Both absolute and relative paths are supported. | ./schema.prisma , ./prisma/schema.prisma |
--watch | No | The generate command will continue to watch the schema.prisma file and re-generate Prisma Client on file changes. |
Examples
Generate Prisma Client using the default schema.prisma
path
$prisma generate
✔ Generated Prisma Client to ./node_modules/@prisma/client in 61msYou can now start using Prisma Client in your code:import { PrismaClient } from '@prisma/client'// or const { PrismaClient } = require('@prisma/client')const prisma = new PrismaClient()Explore the full API: http://pris.ly/d/client
Generate Prisma Client using a non-default schema.prisma
path
$prisma generate --schema=./alternative/schema.prisma
Continue watching the schema.prisma
file for changes to automatically re-generate Prisma Client
$prisma generate --watch
Watching... /home/prismauser/prisma/prisma-play/prisma/schema.prisma✔ Generated Prisma Client to ./node_modules/@prisma/client in 45ms
Generated Assets
The prisma-client-js
generator creates a customized client for working with your database within the ./node_modules/@prisma/client
directory.
introspect
The introspect
command connects to your database and adds Prisma models to your Prisma schema that reflect the current database schema.
To run the introspect
command, a schema.prisma
file with a valid datasource
must be available.
Warning: The command will overwrite the current
schema.prisma
file with the new schema. Any manual changes or customization will be lost. Be sure to back up your currentschema.prisma
file before runningintrospect
if it contains important modifications.
Prerequisites
Before using the introspect
command, you must define a valid datasource
within your schema.prisma
file.
For example, the following datasource
defines a SQLite database file within the current directory:
datasource db {provider = "sqlite"url = "file:my-database.db"}
Options
The introspect
command recognizes the following options to modify its behavior:
Option | Required | Description | Default |
---|---|---|---|
--force | No | Force overwrite of manual changes made to schema. The generated schema will be based on the introspected schema only. | |
--schema | No | Specifies the path to the desired schema.prisma file to be processed instead of the default path. Both absolute and relative paths are supported. | ./schema.prisma , ./prisma/schema.prisma |
--print | No | Prints the created schema.prisma to the screen instead of writing it to the filesystem. |
Examples
Analyze the database and write its schema to the schema.prisma
file
$prisma introspect
Introspecting based on datasource defined in schema.prisma …✔ Wrote Prisma data model into schema.prisma in 38msRun prisma generate to generate Prisma Client.
Specify an alternative schema.prisma
file to read and write to
$prisma introspect --schema=./alternative/schema.prisma
Introspecting based on datasource defined in alternative/schema.prisma …✔ Wrote Prisma data model into alternative/schema.prisma in 60msRun prisma generate to generate Prisma Client.
Display the generated schema.prisma
file instead of writing it to the filesystem
$prisma introspect --print
generator client {provider = "prisma-client-js"}datasource db {provider = "sqlite"url = "file:./hello-prisma.db"}model User {email String @uniquename String?user_id Int @default(autoincrement()) @idpost Post[]profile Profile[]}model Post {content String?post_id Int @default(autoincrement()) @idtitle Stringauthor_id User?}model Profile {bio String?profile_id Int @default(autoincrement()) @iduser_id User}
db
db push
Note: This feature is currently in Preview. Features in Preview may still have some issues, and are not recommended for use in production environments. To access commands in Preview, you must opt-in via the
--preview-feature
flag.
The db push
command pushes the state of your Prisma schema file to the database without using migrations. This command is a good choice when you do not need to version schema changes, such as during prototyping and local development. db push
works as follows:
db push
introspects the database, and infers and executes the changes required to make your database schema reflect the state of your Prisma schema.By default, after changes have been applied to the database schema, generators are triggered (for example, Prisma Client). You do not need to manually invoke
prisma generate
.If
db push
anticipates that the changes could result in data loss, it will:- Throw an error
- Require the
--force
option if you still want to make the changes
db push
does not interact with or rely on migrations. The migrations table will no be updated, and no migration files will be generated.
db push
works well if:
- You want to quickly prototype and iterate on schema design locally without the need to deploy these changes to other environments such as other developers, or staging and production environments.
- You are prioritizing reaching a desired end-state and not the changes or steps executed to reach that end-state. There is no way to Preview the changes that will be made to the database.
- You do not need control over how schema changes impact data. There is no way to orchestrate schema and data migrations - if
db push
anticipates that changes will result in data loss, it will require specific confirmation via a--force
option. You can either accept data loss by specifying the option or stop the process, but there is no way to customize the changes.
db push
is not recommended if:
- You want to replicate your schema changes in other environments where there could be important data you cannot afford to lose. You can use
db push
for prototyping, but you should use migrations to commit the schema changes and apply these in your other environments. - You want fine-grained control over how the schema changes are executed - for example, renaming a column instead of dropping it and creating a new one.
- You want to keep track of changes made to the database schema over time.
db push
does not create any artifacts that allow you to keep track of these changes. - You want the schema changes to be reversible. You can use
db push
again to revert to the original state, but this might result in data loss and there will be no mechanism for you to orchestrate these changes.
db push and Migrate (Preview)
If you are already using migrations with Prisma Migrate, db push
will still work. However, be aware of the following side effects of using both Prisma Migrate and db push
:
Prisma Migrate introspects the database to anticipate the changes needed to reach the end-state of the migration and Preview these changes as DDL statements in README.md
files.
If you use db push
to change the database schema using the Prisma Schema file, and subsequently use prisma migrate dev --preview-feature
to generate the corresponding migration:
- Migrate will still work regardless if it is executed on top of the changes from
db push
or not, but - the DDL statements in
README.md
will not reflect the steps carried out in other environments wheredb push
was not used - the statements can be different or entirely missing.
Because this behavior could be confusing to some, if db push
detect migration files, it will require confirmation to proceed or supplying an —-ignore-migrations
option.
Prerequisites
Before using the db push
command, you must define a valid datasource within your schema.prisma
file.
For example, the following datasource
defines a SQLite database file within the current directory:
datasource db {provider = "sqlite"url = "file:my-database.db"}
Arguments
Argument | Required | Description | Default |
---|---|---|---|
--schema | No | Specifies the path to the desired schema.prisma file to be processed instead of the default path. Both absolute and relative paths are supported. | ./schema.prisma ./prisma/schema.prisma |
Options
Options | Required | Description |
---|---|---|
--preview-feature | Yes | Enables use of Preview feature commands |
--skip-generate | No | Skip generation of artifacts such as Prisma Client |
--force | No | Ignore data loss warnings. This option is required if as a result of making the schema changes, data may be lost. |
--help / --h | No | Displays the help message |
Examples
Push the schema:
$npx prisma db push --preview-feature
Push the schema, accepting data loss:
$npx prisma db push --preview-feature --force
Push the schema with a custom schema location:
$npx prisma db push --preview-feature --schema=/tmp/schema.prisma
db seed (Preview)
Options
Options | Required | Description |
---|---|---|
--preview-feature | Yes | Enables use of Preview feature commands |
--help / --h | No | Displays the help message |
Examples
$npx prisma db push --preview-feature --force
Prisma Migrate (Preview)
Note: Prisma Migrate is currently in Preview. Features in Preview may still have some issues, and are not recommended for use in production environments. To access commands in Preview, you must opt-in via the
--preview-feature
flag.
migrate dev
For use in development environments only, requires shadow database
The migrate dev
command updates your database using migrations during development. In the simplest case, it does the following:
- Applies pending migrations
- Generate a new migration based on the changes in the Prisma schema
- Applies the new migration to the database and updates the
_prisma_migrations
table - Trigger the generation of artifacts (for example, the Prisma Client)
The migrate dev
command will prompt you to reset the database in the following scenarios:
- Migration history conflicts caused by modified or missing migration
- The database schema has drifted away from the end-state of the migration history
When the database is reset, if Prisma Migrate detects a seed script, the database will be automatically seeded.
Note: For a simple and integrated way to re-create data in your development database as often as needed, check out our seeding guide.
Options
Argument | Required | Description | Default |
---|---|---|---|
--name | No | The name of the migration. If no name is provided, the CLI will prompt you. | |
--create-only | No | Creates a new migration based on the changes in the schema but does not apply that migration. Run migrate dev to apply migration. |
Examples
Apply all migrations, then create and apply any new migrations:
$prisma migrate dev --preview-feature
Apply all migrations and create a new migration if there are schema changes, but do not apply it:
$prisma migrate dev --create-only --preview-feature
migrate reset
For use in development environments only.
The migrate reset
command:
- Drops the database
- Creates a new database with the same name
- Applies all migrations
Note: For a simple way to re-create data in your development database as often as needed, check out our seeding guide.
Arguments
Argument | Required | Description | Default |
---|---|---|---|
--schema | No | Specifies the path to the desired schema.prisma file to be processed instead of the default path. Both absolute and relative paths are supported. | ./schema.prisma ./prisma/schema.prisma |
Options
Argument | Required | Description | Default |
---|---|---|---|
--skip-generate | No | Skip triggering generators (for example, Prisma Client) |
Examples
$prisma migrate reset --preview-feature
migrate deploy
The migrate deploy
command applies all pending migrations. Primarily used in non-development environments. This command:
- Does not look for drift in the database or changes in the Prisma schema
- Does not reset the database or generate artifacts
- Does not rely on a shadow database
Arguments
Argument | Required | Description | Default |
---|---|---|---|
--schema | No | Specifies the path to the desired schema.prisma file to be processed instead of the default path. Both absolute and relative paths are supported. | ./schema.prisma ./prisma/schema.prisma |
Examples
$prisma migrate deploy --preview-feature
migrate resolve
The migrate resolve
command allows you to solve migration history issues in production by marking a migration as already applied (supports baselining) or rolled back.
Arguments
Argument | Required | Description | Default |
---|---|---|---|
--applied | No* | Record a specific migration as applied - for example --applied "20201231000000_add_users_table" | |
--rolled-back | No* | Record a specific migration as rolled back - for example --rolled-back "20201231000000_add_users_table" | ./schema.prisma ./prisma/schema.prisma |
--schema | No | Specifies the path to the desired schema.prisma file to be processed instead of the default path. Both absolute and relative paths are supported. | ./schema.prisma ./prisma/schema.prisma |
You must specify either --rolled-back
or --applied
.
Examples
$prisma migrate resolve --applied 20201231000000_add_users_table --preview-feature
$prisma migrate resolve --rolled-back 20201231000000_add_users_table --preview-feature
migrate status
The prisma migrate status
command looks up the migrations in /prisma/migrations/*
folder and the entries in the _prisma_migrations
table and compiles informatoin about the state of the migrations in your databae. For example:
Status3 migrations found in prisma/migrationsYour local migration history and the migrations table from your database are different:The last common migration is: 20201127134938_new_migrationThe migration have not yet been applied:20201208100950_test_migrationThe migrations from the database are not found locally in prisma/migrations:20201208100950_new_migration
Arguments
Argument | Required | Description | Default |
---|---|---|---|
--schema | No | Specifies the path to the desired schema.prisma file to be processed instead of the default path. Both absolute and relative paths are supported. | ./schema.prisma ./prisma/schema.prisma |
Examples
$prisma migrate status --preview-feature
Studio
studio
The studio
command allows you to interact with and manage your data interactively. It does this by starting a local web server with a web app configured with your project's data schema and records.
Prerequisites
Before using the studio
command, you must define a valid datasource
within your schema.prisma
file.
For example, the following datasource
defines a SQLite database file within the current directory:
datasource db {provider = "sqlite"url = "file:my-database.db"}
Options
The studio
command recognizes the following options:
Option | Required | Description | Default |
---|---|---|---|
-p , --port | No | The port number to start Studio on. | 5555 |
Examples
Start Studio on the default port and open a new browser tab to it
$prisma studio
Start Studio on a different port and open a new browser tab to it
$prisma studio --port 7777